From 7c31434529294015e61a72b085d60f68ac916f23 Mon Sep 17 00:00:00 2001 From: Martin Konstantin Herrmann Date: Mon, 9 Nov 2026 00:40:43 +0100 Subject: [PATCH 1/4] Design onboarding addon Draft for a load-on-demand UnitFrames_Onboarding addon: four-step guided setup with preset previews, tweaks, frame toggles and Workbench deep links, plus SVG mockups. --- todos/09-design-onboarding.md | 241 +++++++++++++++++++++++ todos/09-onboarding/01-pick-a-look.svg | 190 ++++++++++++++++++ todos/09-onboarding/02-make-it-yours.svg | 131 ++++++++++++ todos/09-onboarding/03-your-frames.svg | 93 +++++++++ todos/09-onboarding/04-ready.svg | 99 ++++++++++ 5 files changed, 754 insertions(+) create mode 100644 todos/09-design-onboarding.md create mode 100644 todos/09-onboarding/01-pick-a-look.svg create mode 100644 todos/09-onboarding/02-make-it-yours.svg create mode 100644 todos/09-onboarding/03-your-frames.svg create mode 100644 todos/09-onboarding/04-ready.svg diff --git a/todos/09-design-onboarding.md b/todos/09-design-onboarding.md new file mode 100644 index 0000000..1f1034d --- /dev/null +++ b/todos/09-design-onboarding.md @@ -0,0 +1,241 @@ +# Design: Getting started (UnitFrames_Onboarding) + +Status: draft; no implementation. Targets Forever Interface 16001 and Lua 5.1. +Mockups: `todos/09-onboarding/01-pick-a-look.svg` … `04-ready.svg` (generated, not pixel-exact). + +## Goal + +A first run that feels like a product, not a settings dump. In four short +steps a new user picks a look from live previews, nudges the few options that +change the feel most, chooses which frames exist, and leaves knowing where the +depth lives. Every step can be skipped; nothing is saved until **Apply**; the +old look stays one profile switch away. + +## Packaging: its own load-on-demand addon + +`UnitFrames_Onboarding/`, shipped with the others, independent of the Workbench: + +``` +## Interface: 16001 +## Title: UnitFrames |cff4fa3ffGetting started|r +## Notes: A guided first setup with style presets. Open with /uf welcome. +## Dependencies: UnitFrames +## OptionalDeps: UnitFrames_Media, UnitFrames_ClickGrid +## LoadOnDemand: 1 +``` + +No SavedVariables of its own. The "done" flag lives in the core's AceDB +`global.onboarding = { done = false }`, so the core decides whether to load it +without loading it. Turning the addon off in the AddOns list removes it +entirely: `C_AddOns.LoadAddOn` returns `false, "DISABLED"` (already in the API +snapshot) and the core stays silent instead of erroring. + +Core touch points stay tiny (all in the always-loaded addon): + +| Where | What | +| --- | --- | +| `Core/Config.lua` | `global.onboarding = { done = false }` default. | +| `Core/Commands.lua` | `ns:OpenOnboarding()` (load, then `UnitFrames.Onboarding:Open()`); `/uf welcome`. A disabled addon prints one hint line. | +| `Integration/Launcher.lua` | "Getting started" in the minimap right-click menu. | +| `Integration/Onboarding.lua` (new) | First-run trigger, below. | +| `Integration/SettingsPanel.lua` (new) | A minimal Blizzard Settings → AddOns category: version, "Open Workbench", "Getting started". This is the "via settings" entry; it costs a few frames, no options. | + +The Workbench gets a "Getting started" button in its toolbar that calls +`UF:OpenOnboarding()`; no dependency between the two addons. + +### First-run trigger + +- **Fresh install** (`UnitFramesDB` was nil before `AceDB:New`): on + `PLAYER_ENTERING_WORLD` with `isInitialLogin`, outside combat, open the + wizard after a short delay (`C_Timer.After(2, …)`) so it doesn't fight the + loading screen. In combat: wait for `PLAYER_REGEN_ENABLED` via `ns.AfterCombat`. +- **Existing install** without the flag: set `done = true` silently and print + once: `New: /uf welcome walks you through presets.` +- Skip, Close and Apply all set `done = true`. Reopening is always manual. +- Entering combat while open hides the wizard (pending choices kept in memory), + and it comes back on `PLAYER_REGEN_ENABLED` with a chat line if it was open. + +## Visual language + +Built only from `UF.Skin` colours and `UnitFrames/Media` glows, so it matches the +Workbench and needs no new art. + +- **Backdrop:** a full-screen `UIParent` child at `FULLSCREEN_DIALOG`, black at + 55% alpha, mouse-enabled (clicks don't leak into the world). The world stays + visible behind it, so the setup feels like it's happening in your game. +- **Window:** 1060×660, centred, `Skin.colors.window`, 1 px `border`, a 2 px + accent line across the top, `GlowFrameSoft.tga` as a soft drop shadow. Esc + closes it (`UISpecialFrames`), which counts as Skip. +- **Step rail (left, 230 px, darker):** small caps "UNITFRAMES", "Getting + started", then four numbered nodes on a vertical line. The line's accent fill + grows to the current step; the current node has a soft glow; finished nodes + show a tick and are clickable to jump back. "Skip for now" and "Reopen: + /uf welcome" sit at the bottom. +- **Type:** titles 26 px, body 13 px dim, labels 10 px small caps with letter + spacing. Roboto Condensed through `Media:GetFontObject` when + UnitFrames_Media is loaded, otherwise `GameFont*` objects. +- **Primary action:** one accent-filled button bottom right, labelled with the + next step ("Next: tweaks →"). Back is a quiet outline button. A plain + "Step n of 4" sits between them. +- **Motion** (AnimationGroups only, ~180 ms, smooth): step content slides 24 px + and fades in; the rail line grows; a preset card scales to 1.03 on hover; + previews cross-fade when the style changes. Nothing loops except the animated + sample data. + +## The four steps + +### 1. Pick a look (`01-pick-a-look.svg`) + +A big **stage** shows player (with castbar) and target, side by side and +animated: health waves, a cast filling, pending DoT stripes on the target. A +"Live preview · animated" pill sits bottom left; bottom right, a +Hostile / Friendly / Dead toggle flips the target's sample. + +Under the stage, four **preset cards**, each with a mini player frame in its +own style, a name and two tags: + +| Preset | Pitch | Tags | +| --- | --- | --- | +| Default | The shared style as shipped. | Balanced, 3D portraits | +| Minimal | Flat pixel border, class-coloured bars, no portraits, compact text. | Flat, No portraits | +| Classic | Bigger frames, portraits, chunky tooltip-style border, warmer colours. | Chunky, Gold trim | +| Healer | Wide health bars, deficit text, ClickGrid on when installed. | Wide bars, ClickGrid | + +Clicking a card selects it (accent border, glow, tick) and cross-fades the +stage. Arrow keys move between cards; Enter goes on. + +### 2. Make it yours (`02-make-it-yours.svg`) + +The stage moves left and stacks player above target; a caption reads "Minimal ++ your tweaks". On the right are six controls drawn as **chips**, not dropdowns, +because you can see every option at once: + +- **Font:** three curated faces, each chip rendered in its own font. +- **Bar texture:** four, from LibSharedMedia. +- **Border:** None / Pixel / Tooltip / Gold. +- **Health colour:** Class / Green / Gradient. +- **Portraits:** 3D / Class icon / Off. +- **Size:** a Compact ↔ Chunky slider that scales width and height together. + +Each chip writes into the pending payload (theme or every unit) and restyles +the stage at once. The chip values are fixed lists in the presets file; +anything they don't cover is a Workbench job. + +### 3. Your frames (`03-your-frames.svg`) + +A **screen map**: a schematic of the game screen with ghost minimap and action +bars. Each frame is a tile at roughly its default position: Player, Pet, +Target, Target's target, Focus, Focus target, Castbar & GCD (amber), and +Party / Raid (green, ClickGrid; shown only when that addon is installed and +enabled). Click toggles; enabled tiles glow, disabled ones are dashed. Hovering +a tile highlights that frame in a small preview strip. A summary card reads +"6 frames on · 2 off". Tile positions are fixed artwork; real placement is +Edit Mode's job at the end. + +### 4. Ready (`04-ready.svg`) + +A centred glowing tick, "You're set.", and one line saying which profile now +holds the style ("Saved as the profile “Minimal”. Your old look is still one +click away in Profiles."). One accent button: **Place frames in Edit Mode** +(closes the wizard, opens Edit Mode). + +Under it, "Dig deeper when you feel like it": six cards with a tinted icon +square, a title, one line and an arrow, each deep-linking into the Workbench +through `ns:OpenWorkbench(entryId)`: + +| Card | Opens | +| --- | --- | +| Auras | `player` entry, auras page | +| Texts | `player` entry, text content page | +| Castbar & timers | castbar / timers entries | +| Party & raid | `clickgrid.panel` (hidden without ClickGrid) | +| Import a string | `profiles` entry | +| Everything else | Workbench at its last entry | + +**Apply happens when Next is pressed on step 3**, so step 4 only shows the +result. A "Save as a new profile" checkbox (on by default) sits next to that +button. + +## Data and application + +`UnitFrames_Onboarding/Presets.lua` is pure data. Each preset is a style payload +in exactly the shape `Profiles` exports (`{ theme = {…}, units = { player = {…}, … }, clickgrid = {…}? }`) +plus `name`, `pitch`, `tags`, `profileName`. Chips and frame toggles are small +functions that write paths into a **copy** of the selected payload: +`pending = Util.Copy(preset.style)`. + +Apply: + +1. `local apply, dropped = UF.Profiles.kinds.style.prepare(pending)`: the same + validation as string import. If it fails, show the reason inline and save nothing. +2. If "new profile" is ticked: `UF.Profiles:Create(uniqueName(preset.profileName))`, + which keeps the current Edit Mode positions. +3. `apply()`; one `ThemeChanged` restyles the live frames and any open Workbench. +4. `global.onboarding.done = true`. + +Expose `Profiles:Prepare(kind, data)` on the core rather than reaching into +`kinds`, so the onboarding addon uses a public seam. + +## Previews without touching saved style + +Preview frames come from `UF.Units:CreateFromDefinition(def, stage, unitConfig)` +with the pending unit config, and are applied with a resolved table built +against the pending theme: +`Schema.Resolve(Units:GetSchema(unit), cfg, Schema.Resolve(Theme.schema, pending.theme))`, +passed as `Component:Apply(config, resolved)`. Data comes from +`Units:ShowSample` with `Units:GetSample(unit)` plus a wave, the same way +`Entries/Units.lua` animates its samples. Previews are released on step change +and on close. + +**Risk to verify first:** child components that call `ns.Config:GetTheme()` +themselves instead of using the passed `resolved` would show the live theme. +Audit `Component:ApplyChild` and the Backdrop, Text and Auras paths. If they +leak, add a scoped preview theme (e.g. `Component:SetThemeSource(fn)`) +instead of temporarily swapping the global theme. + +## Files (each under 200 lines) + +``` +UnitFrames_Onboarding/ +├── UnitFrames_Onboarding.toc +├── Init.lua namespace, UnitFrames.Onboarding:Open/Close, combat hide +├── Presets.lua four payloads + chip/toggle value tables +├── Pending.lua pending payload, chip/toggle writers, Apply +├── Shell.lua backdrop, window, rail, footer, step transitions +├── Preview.lua sample frames from a payload, animate, release +├── Widgets.lua Card, Chip, ChipRow, Tile, DigCard (on UF.Widgets.Widget) +└── Steps/ + ├── Look.lua + ├── Tweaks.lua + ├── Frames.lua + └── Ready.lua +``` + +Plus `scripts/install.sh`, release packaging and `tests/helpers.lua` learning +the new TOC. + +## Tests (`tests/spec/onboarding/`) + +- Every preset payload passes style `prepare` with **zero dropped paths**, both + with and without ClickGrid loaded. +- Every chip and toggle writes paths that `prepare` accepts. +- Apply with "new profile" creates and switches profiles and keeps positions; + without it, the active style is replaced. A failed `prepare` writes nothing. +- Previews never change `Config` (snapshot before and after). +- First run: a fresh DB opens once; an existing DB only prints; done is never re-opened. +- Disabled addon: `ns:OpenOnboarding()` prints the hint and does not error. +- Opening, switching steps and closing release every preview frame. + +## In-game checks offline mocks can't prove + +Fresh SavedVariables auto-open after login; combat hides and restores it; +previews match what each preset applies; Esc counts as Skip; Edit Mode opens +from step 4; deep links land on the right Workbench pages; the addon disabled +in the AddOns list stays silent. + +## Open questions + +- Final preset contents: Classic's "gold trim" needs a border that's + licence-clean and already shipped (AGENTS.md: no new third-party art). +- Should existing users ever get the wizard auto-opened (for example once, after a major version)? +- Do we want a fifth preset that's community-sourced (an import string shipped as data)? diff --git a/todos/09-onboarding/01-pick-a-look.svg b/todos/09-onboarding/01-pick-a-look.svg new file mode 100644 index 0000000..48eef52 --- /dev/null +++ b/todos/09-onboarding/01-pick-a-look.svg @@ -0,0 +1,190 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +UNITFRAMES +Getting started + + + + +1 +Pick a look + +2 +Make it yours + +3 +Your frames + +4 +Ready +Skip for now +Reopen: /uf welcome +Pick a look +Start from a style you like. Everything stays tweakable later — this just gets you 90% there. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Voshond +82% · 60 + + +Frostbolt +1.2 + + + + + + + + + + + +Ragnaros +46% · ?? +PLAYER +TARGET + + +Live preview · animated + +◐ Hostile · ◑ Friendly · ○ Dead + + + + + + + + + + + + + +Jaina +72% · 60 +Default + +Balanced + +3D portraits + +✓ + + + + + + + + + +Jaina +72% · 60 +Minimal + +Flat + +No portraits + + + + + + + + + + + + +Jaina +72% · 60 +Classic + +Chunky + +Gold trim + + + + + + + + + +Jaina +72% · 60 +Healer + +Wide bars + +ClickGrid + +Back +Step 1 of 4 + +Next: tweaks → + \ No newline at end of file diff --git a/todos/09-onboarding/02-make-it-yours.svg b/todos/09-onboarding/02-make-it-yours.svg new file mode 100644 index 0000000..15deb03 --- /dev/null +++ b/todos/09-onboarding/02-make-it-yours.svg @@ -0,0 +1,131 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +UNITFRAMES +Getting started + + + +✓ +Pick a look + + +2 +Make it yours + +3 +Your frames + +4 +Ready +Skip for now +Reopen: /uf welcome +Make it yours +Six things that change the feel most. Every option has dozens more friends in the Workbench. + + + + + + + + + +Voshond +82% · 60 + + +Frostbolt +1.2 + + + + + + + + +Ragnaros +46% · ?? +Minimal + your tweaks + +FONT + +Roboto + +Friz Quadrata + +Expressway +BAR TEXTURE + +Flat + +Raid bar + +Gloss + +Stripes +BORDER + +None + +Pixel + +Tooltip + +Gold +HEALTH COLOUR + +Class + +Green + +Gradient +PORTRAITS + +3D + +Class icon + +Off +SIZE + + + +Compact +Chunky + +Back +Step 2 of 4 + +Next: frames → + \ No newline at end of file diff --git a/todos/09-onboarding/03-your-frames.svg b/todos/09-onboarding/03-your-frames.svg new file mode 100644 index 0000000..8a5cdd0 --- /dev/null +++ b/todos/09-onboarding/03-your-frames.svg @@ -0,0 +1,93 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +UNITFRAMES +Getting started + + + +✓ +Pick a look + +✓ +Make it yours + + +3 +Your frames + +4 +Ready +Skip for now +Reopen: /uf welcome +Your frames +Click a tile to switch that frame on or off. You'll drag them into place in Edit Mode at the end. + + + +action bars + +minimap + +Player + + +Target + + +Target's target + + +Pet + + +Focus + + +Focus target + + +Castbar & GCD + + +Party / Raid + +ClickGrid + +6 frames on · 2 off +Hover a tile to see it in the preview + +Back +Step 3 of 4 + +Next: finish → + \ No newline at end of file diff --git a/todos/09-onboarding/04-ready.svg b/todos/09-onboarding/04-ready.svg new file mode 100644 index 0000000..4324ab1 --- /dev/null +++ b/todos/09-onboarding/04-ready.svg @@ -0,0 +1,99 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +UNITFRAMES +Getting started + + + +✓ +Pick a look + +✓ +Make it yours + +✓ +Your frames + + +4 +Ready +Reopen: /uf welcome + + +✓ +You're set. +Saved as the profile “Minimal”. Your old look is still one click away in Profiles. + +Place frames in Edit Mode +DIG DEEPER WHEN YOU FEEL LIKE IT + + +◎ +Auras +Buffs, debuffs, dispel colours +→ + + +T +Texts +Templates, tags, custom pieces +→ + + +▬ +Castbar & timers +GCD, swing, ranged timers +→ + + +☰ +Party & raid +ClickGrid click casting +→ + + +⇄ +Import a string +Paste a style someone shared +→ + + +⚙ +Everything else +The full Workbench (/uf wb) +→ + +Back + +Close + \ No newline at end of file From b860c64a74c708302d1005ee1e02c4491a5bb852 Mon Sep 17 00:00:00 2001 From: Martin Konstantin Herrmann Date: Mon, 9 Nov 2026 01:15:09 +0100 Subject: [PATCH 2/4] Add Getting started onboarding addon New load-on-demand UnitFrames_Onboarding: four-step guide with preset looks and live previews, quick tweaks, extras on a screen map, and Workbench/Edit Mode hand-off. Opens once on a fresh install; /uf welcome, minimap menu and a Workbench button reopen it. Core: Config:WithTheme for unsaved-style previews, Profiles:Prepare and UniqueName, Workbench:Open at a settings path, first-run trigger. Mock gains C_Timer.After; API snapshot regenerated against the pinned source. --- AGENTS.md | 3 +- DEVELOPMENT.md | 1 + NOTICE.txt | 3 +- README.md | 21 +- USER_GUIDE.md | 26 ++ UnitFrames/Core/Commands.lua | 30 +- UnitFrames/Core/Config.lua | 20 ++ UnitFrames/Core/Profiles.lua | 19 ++ UnitFrames/Integration/Launcher.lua | 1 + UnitFrames/Integration/Onboarding.lua | 55 ++++ UnitFrames/NOTICE.txt | 3 +- UnitFrames/UnitFrames.toc | 1 + UnitFrames_ClickGrid/NOTICE.txt | 3 +- UnitFrames_Media/NOTICE.txt | 3 +- UnitFrames_Onboarding/LICENSE | 73 +++++ UnitFrames_Onboarding/NOTICE.txt | 24 ++ UnitFrames_Onboarding/Onboarding.lua | 123 ++++++++ UnitFrames_Onboarding/Pending.lua | 133 +++++++++ UnitFrames_Onboarding/Presets.lua | 140 +++++++++ UnitFrames_Onboarding/Preview.lua | 94 ++++++ UnitFrames_Onboarding/Shell.lua | 199 +++++++++++++ UnitFrames_Onboarding/Steps/Extras.lua | 96 ++++++ UnitFrames_Onboarding/Steps/Look.lua | 95 ++++++ UnitFrames_Onboarding/Steps/Ready.lua | 117 ++++++++ UnitFrames_Onboarding/Steps/Tweaks.lua | 78 +++++ .../UnitFrames_Onboarding.toc | 21 ++ UnitFrames_Onboarding/Widgets.lua | 164 ++++++++++ UnitFrames_Workbench/NOTICE.txt | 3 +- UnitFrames_Workbench/Search.lua | 4 + UnitFrames_Workbench/Workbench.lua | 6 +- scripts/api-snapshot.lua | 2 +- scripts/build-dev.sh | 2 +- scripts/release.sh | 2 +- scripts/validate-release.lua | 2 +- tests/fixtures/api_snapshot.lua | 5 + tests/helpers.lua | 11 + tests/mock/wow.lua | 13 + tests/run.lua | 2 +- tests/spec/core/commands_spec.lua | 1 + tests/spec/onboarding/onboarding_spec.lua | 280 ++++++++++++++++++ todos/09-design-onboarding.md | 24 +- 41 files changed, 1880 insertions(+), 23 deletions(-) create mode 100644 UnitFrames/Integration/Onboarding.lua create mode 100644 UnitFrames_Onboarding/LICENSE create mode 100644 UnitFrames_Onboarding/NOTICE.txt create mode 100644 UnitFrames_Onboarding/Onboarding.lua create mode 100644 UnitFrames_Onboarding/Pending.lua create mode 100644 UnitFrames_Onboarding/Presets.lua create mode 100644 UnitFrames_Onboarding/Preview.lua create mode 100644 UnitFrames_Onboarding/Shell.lua create mode 100644 UnitFrames_Onboarding/Steps/Extras.lua create mode 100644 UnitFrames_Onboarding/Steps/Look.lua create mode 100644 UnitFrames_Onboarding/Steps/Ready.lua create mode 100644 UnitFrames_Onboarding/Steps/Tweaks.lua create mode 100644 UnitFrames_Onboarding/UnitFrames_Onboarding.toc create mode 100644 UnitFrames_Onboarding/Widgets.lua create mode 100644 tests/spec/onboarding/onboarding_spec.lua diff --git a/AGENTS.md b/AGENTS.md index c18134c..b5cd18a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,7 @@ - `UnitFrames/Integration/EditMode.lua`: layout-specific positions and snapping through LibEditMode. - `UnitFrames_Workbench/`: load-on-demand settings and previews, opened with `/uf wb`. `Entries/Units.lua` edits the real saved unit style; `Data.lua` defines preview sources. Keep static, animated and live previews consistent with runtime behaviour. - `UnitFrames_Media/`: independently registered LibSharedMedia fonts and their licences. +- `UnitFrames_Onboarding/`: load-on-demand Getting started guide (`/uf welcome`). `Integration/Onboarding.lua` in the core opens it once on a fresh install (`global.onboarding.done`). Presets are style-string data applied through `Profiles:Prepare("style", …)`; previews render unsaved styles inside `Config:WithTheme`, which gives the preview theme a revision of its own. Never write saved config before Apply. - `UnitFrames_ClickGrid/`: optional healing panel companion (`/ufcg`): party/raid groups, member targets, native aura slots, status indicators and click-spell bindings, built from the same `UnitFrame` component through the public `UnitFrames` handle. - Match nearby code: tabs, local helpers, existing component methods. New runtime files must be added to the appropriate `.toc` in dependency order; the tests load those TOCs too. - Embedded libraries under either addon's `Libs/` are pinned dependencies, not normal edit targets. The folders are gitignored: `scripts/fetch-libs.sh` replaces local copies and records `UnitFrames/Libs/VERSIONS.md`, and `scripts/setup-test-libs.sh` holds the commits tests and releases build from. Run them only for an intentional dependency update and keep both pins in step. @@ -87,7 +88,7 @@ luajit tests/run.lua --tag shields luajit tests/run.lua workbench -t "preview" ``` -- Specs live in `tests/spec//` (`core`, `contract`, `components`, `auras`, `units`, `workbench`, `editmode`, `clickgrid`, `tracking`). Put new specs in the area of the code they exercise; a feature spec keeps its live and Workbench preview tests together. When behaviour also has tests in other areas, tag them in the `describe`/`it` name (`#shields`) and keep existing tags. +- Specs live in `tests/spec//` (`core`, `contract`, `components`, `auras`, `units`, `workbench`, `editmode`, `clickgrid`, `tracking`, `onboarding`). Put new specs in the area of the code they exercise; a feature spec keeps its live and Workbench preview tests together. When behaviour also has tests in other areas, tag them in the `describe`/`it` name (`#shields`) and keep existing tags. - Path filters match **spec paths** (`units/` is exactly that folder, `name_spec.lua` exactly that file); `-t` matches test names and `--tag` matches tags. `-j [N]` runs spec files in parallel; `--times` (runner or `scripts/run-tests.sh`) reports per-spec durations; `luajit -jp=F tests/run.lua ...` profiles. The runner includes addon Lua syntax checks. No external busted installation is needed. - `tests/helpers.lua` loads TOCs into a fresh mocked client; `tests/mock/wow.lua` includes fake secrets and `tests/mock/ouf.lua` supplies the usual oUF stand-in. Some specs exercise embedded oUF paths explicitly. - The mock is held to the client API through `tests/fixtures/api_snapshot.lua`, generated from Blizzard's API documentation and Lua source by `luajit scripts/api-snapshot.lua` (regenerate after adding API usage or updating the source checkout, and review the diff). The checkout must match the commit pinned in the workflows, or CI regenerates a different snapshot. `tests/mock/api.lua` enforces it on every mock call: undocumented widget methods, rejected arguments, secrets passed where addon (tainted) code may not pass them, and protected calls in combat raise errors. `tests/spec/contract/api_contract_spec.lua` checks the mock's functions, methods, enums, restricted secret returns and our event names, and that the snapshot is current when the source checkout exists. diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 5b3b66a..ff952f5 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -184,6 +184,7 @@ in source is needed before tagging. | `UnitFrames/Integration/` | Edit Mode and launcher integration | | `UnitFrames_Workbench/` | Load-on-demand settings, component gallery and static/animated/live previews | | `UnitFrames_ClickGrid/` | Party/raid panel, member targets, indicators, auras and click-spell bindings | +| `UnitFrames_Onboarding/` | Load-on-demand Getting started guide: preset looks, tweaks, extras and Workbench hand-off | | `UnitFrames_Media/` | Additional fonts and their licences | | `tests/` | Mocked client, API snapshot and regression specs | | `scripts/` | Library fetching, installation and API snapshot generation | diff --git a/NOTICE.txt b/NOTICE.txt index f31510c..be42db9 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -2,7 +2,8 @@ Required Notice: Copyright (c) 2026 Martin Konstantin Herrmann. Original UnitFrames code and documentation are licensed under the PolyForm Noncommercial License 1.0.0; see LICENSE. This covers original work in -UnitFrames, UnitFrames_Workbench, UnitFrames_Media and UnitFrames_ClickGrid. +UnitFrames, UnitFrames_Workbench, UnitFrames_Media, UnitFrames_ClickGrid and +UnitFrames_Onboarding. Third-party libraries, fonts, reference projects and Blizzard materials are excluded and retain their own terms. diff --git a/README.md b/README.md index b826bee..e7d12ab 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,12 @@ Use **Global Settings** to adjust inherited defaults. Development builds also include a **Developer tools** component gallery for testing; those demonstrations do not change your unit settings. +New to the addon? **Getting started** (`/uf welcome`, or the button at the +top of the Workbench) lets you pick one of four preset looks with live +previews, adjust font, textures, border, colours, portraits and size, and +switch on castbars and timers. It saves the result as a new profile, so your +previous look stays one switch away. + To move frames, open the game's **Edit Mode**. If you want matching frames, start with your player and use **Copy player style** under **Layout & border** on the others. You can still customise each one afterward. @@ -110,12 +116,15 @@ those separately. If no release is listed yet, the first bundle has not been published. Extract the ZIP into your Forever client's `Interface/AddOns` folder. It -contains four addon folders: `UnitFrames`, `UnitFrames_Workbench`, -`UnitFrames_Media` and `UnitFrames_ClickGrid`. Keep the first two for frames -and settings. The extra fonts and ClickGrid healing panel are optional. - -Restart the game, enable the addons on the character selection screen, -then type `/uf wb` to get started. +contains five addon folders: `UnitFrames`, `UnitFrames_Workbench`, +`UnitFrames_Media`, `UnitFrames_ClickGrid` and `UnitFrames_Onboarding`. Keep +the first two for frames and settings. The extra fonts, ClickGrid healing +panel and the Getting started guide are optional. + +Restart the game and enable the addons on the character selection screen. +On your first login, **Getting started** walks you through picking a preset +look, the options that matter most and the extras you want. Afterwards, +`/uf wb` opens all settings and `/uf welcome` reopens the guide. Use the attached **UnitFrames-….zip**, rather than GitHub's **Source code** archives or **Download ZIP** button, which contain source without dependencies. diff --git a/USER_GUIDE.md b/USER_GUIDE.md index 7a3bb2e..55e6873 100644 --- a/USER_GUIDE.md +++ b/USER_GUIDE.md @@ -4,6 +4,32 @@ A detailed reference for the settings available in game. For a quick introduction, see the [main README](README.md). For setup and implementation, see the [developer guide](DEVELOPMENT.md). +## Getting started + +On a first install, the **Getting started** guide opens shortly after you log +in (never during combat). Reopen it any time with `/uf welcome`, the +**Getting started** button at the top of the Workbench or the minimap icon's +right-click menu. It is its own optional addon, **UnitFrames Getting +started**: turn it off in the AddOns list and nothing of it loads. + +1. **Pick a look**: Default, Minimal, Classic or Healer, each with a live + preview of your player and target frames. +2. **Make it yours**: font, bar texture, border, health colour, portraits and + size, shown on the preview as you click. +3. **Add the extras**: castbars on your player, target and focus frames, + experience, combo points, and the standalone timer bars with global + cooldown and swing timer. **Save as a new profile** (on by default) puts + the look into a new profile named after it and switches to it; your + previous profile is left untouched. Turn it off to replace the style of + the current profile instead. Frame positions always stay. +4. **Ready**: open Edit Mode to place your frames, or jump straight to the + Workbench pages for buffs and debuffs, texts, timers, ClickGrid or + importing a shared string. + +Nothing is saved before **Apply and finish**. Skip, Escape or the close +button end the guide without changes. Combat hides it with your choices kept; +it returns when combat ends. + ## Open settings In game: `/uf wb` opens the Workbench. diff --git a/UnitFrames/Core/Commands.lua b/UnitFrames/Core/Commands.lua index cc9f62e..64e8976 100644 --- a/UnitFrames/Core/Commands.lua +++ b/UnitFrames/Core/Commands.lua @@ -3,26 +3,45 @@ local _, ns = ... local HELP = { "/uf help - show this list of commands", "/uf wb - open settings and previews", + "/uf welcome - walk through presets and the first setup again", "/uf minimap - show or hide the minimap icon", "/uf logs [clear] - show or clear saved diagnostic entries", "/uf dots [reset] - toggle DoT tracking with its trace in chat, or forget learned tick sizes", "/uf perf help - show developer performance commands", } --- Loads the Workbench on demand and shows it, optionally at an entry. -function ns:OpenWorkbench(entryId) +-- Loads the Workbench on demand and shows it, optionally at an entry and the +-- settings page holding `path` (e.g. "auras"). +function ns:OpenWorkbench(entryId, path) local loaded, reason = C_AddOns.LoadAddOn("UnitFrames_Workbench") if not loaded then self:Print("could not load UnitFrames_Workbench:", reason or "unknown reason") return end if entryId then - self.Workbench:Open(entryId) + self.Workbench:Open(entryId, path) else self.Workbench:Toggle() end end +-- Loads Getting started on demand and shows it. Players who turned the addon +-- off in the AddOns list only get a hint, and none when `quiet` (first login). +function ns:OpenOnboarding(quiet) + local loaded, reason = C_AddOns.LoadAddOn("UnitFrames_Onboarding") + if not loaded then + if quiet then return false end + if reason == "DISABLED" then + self:Print("Getting started is turned off. Enable UnitFrames Getting started in the AddOns list to use it.") + else + self:Print("could not load UnitFrames_Onboarding:", reason or "unknown reason") + end + return false + end + self.Onboarding:Open() + return true +end + local commands = {} function commands.help() @@ -37,6 +56,11 @@ function commands.wb() end commands.workbench = commands.wb +function commands.welcome() + ns:OpenOnboarding() +end +commands.onboarding = commands.welcome + function commands.minimap() ns.Launcher:ToggleMinimap() ns:Print(ns.Launcher:IsMinimapShown() and "minimap icon shown" or "minimap icon hidden") diff --git a/UnitFrames/Core/Config.lua b/UnitFrames/Core/Config.lua index 072644d..93623b5 100644 --- a/UnitFrames/Core/Config.lua +++ b/UnitFrames/Core/Config.lua @@ -27,6 +27,8 @@ local function BuildDefaults() }, global = { minimap = { hide = false }, + -- Getting started (UnitFrames_Onboarding): finished or skipped once. + onboarding = { done = false }, }, } end @@ -47,6 +49,8 @@ local function OwnProfile(db) end function Config:Initialize() + -- No saved variables yet: a first install, offered the Getting started guide. + self.freshInstall = UnitFramesDB == nil self.db = LibStub("AceDB-3.0"):New("UnitFramesDB", BuildDefaults(), true) OwnProfile(self.db) local function OnProfile() @@ -65,7 +69,9 @@ function Config:ProfileChanged() end -- Before ADDON_LOADED (and in offline tests) the static defaults are used. +-- Inside WithTheme a preview's own theme is returned instead. function Config:GetTheme() + if self.previewTheme then return self.previewTheme end if self.db then return self.db.profile.theme end @@ -73,6 +79,20 @@ function Config:GetTheme() return self.defaultTheme end +-- Runs fn with `theme` as the effective theme, for previews of a style that +-- isn't saved (Getting started presets). Theme-derived caches see a revision +-- of their own, so neither the preview nor the live frames reuse the other's. +-- The previous theme is restored even when fn raises; the error still raises. +local previewRevision = 0 +function Config:WithTheme(theme, fn, ...) + local previous, revision = self.previewTheme, self.themeRevision + previewRevision = previewRevision - 1 + self.previewTheme, self.themeRevision = theme, previewRevision + local ok, err = pcall(fn, ...) + self.previewTheme, self.themeRevision = previous, revision + if not ok then error(err, 0) end +end + function Config:GetThemeDefaults() self.themeDefaults = self.themeDefaults or Schema.Defaults(ns.Theme.schema) return self.themeDefaults diff --git a/UnitFrames/Core/Profiles.lua b/UnitFrames/Core/Profiles.lua index 4483593..b351c17 100644 --- a/UnitFrames/Core/Profiles.lua +++ b/UnitFrames/Core/Profiles.lua @@ -70,6 +70,16 @@ local function CheckName(name) return name end +-- `base`, or "base 2", "base 3"... when that name is taken. +function Profiles:UniqueName(base) + local name, index = base, 1 + while self:Exists(name) do + index = index + 1 + name = base .. " " .. index + end + return name +end + function Profiles:Switch(name) if not self:Exists(name) then return false, "There is no profile named " .. tostring(name) .. "." end DB():SetProfile(name) @@ -159,6 +169,15 @@ function Profiles:Decode(text) return payload end +-- Validates decoded data of one kind (as a string would carry it) without +-- writing anything: an apply function and the skipped paths, or nil and a +-- reason. Built-in presets use it to apply style tables. +function Profiles:Prepare(kindKey, data) + local kind = self.kinds[kindKey] + assert(kind, "Profiles: unknown kind " .. tostring(kindKey)) + return kind.prepare(data) +end + --[[ Imports a string. With `profileName` (different from the active profile) the data goes into a new profile, created and made active; otherwise it replaces diff --git a/UnitFrames/Integration/Launcher.lua b/UnitFrames/Integration/Launcher.lua index 1d5cef4..431294e 100644 --- a/UnitFrames/Integration/Launcher.lua +++ b/UnitFrames/Integration/Launcher.lua @@ -33,6 +33,7 @@ end local function BuildMenu(_, root) root:CreateTitle("UnitFrames") root:CreateButton("Toggle Workbench", function() ns:OpenWorkbench() end) + root:CreateButton("Getting started", function() ns:OpenOnboarding() end) root:CreateCheckbox("Show minimap icon", function() return Launcher:IsMinimapShown() end, function() Launcher:ToggleMinimap() end) diff --git a/UnitFrames/Integration/Onboarding.lua b/UnitFrames/Integration/Onboarding.lua new file mode 100644 index 0000000..ccba1c0 --- /dev/null +++ b/UnitFrames/Integration/Onboarding.lua @@ -0,0 +1,55 @@ +local _, ns = ... + +--[[ +Offers Getting started (UnitFrames_Onboarding, load on demand) once. A first +install opens it shortly after the first login, waiting for combat to end; +an existing install is marked done and gets a one-line hint instead. The +guide marks itself done when it is skipped, closed or applied. +]] +local FirstRun = {} +ns.FirstRun = FirstRun + +FirstRun.DELAY = 2 + +local frame = CreateFrame("Frame") + +local function Settings() + return ns.Config.db.global.onboarding +end + +function FirstRun:IsDone() + return Settings().done == true +end + +function FirstRun:MarkDone() + Settings().done = true +end + +local function OpenWhenReady() + if FirstRun:IsDone() then return end + if InCombatLockdown() then + frame:RegisterEvent("PLAYER_REGEN_ENABLED") + return + end + frame:UnregisterEvent("PLAYER_REGEN_ENABLED") + ns:OpenOnboarding(true) +end + +frame:SetScript("OnEvent", function(self, event, isInitialLogin) + if event == "PLAYER_ENTERING_WORLD" then + self:UnregisterEvent(event) + if isInitialLogin then C_Timer.After(FirstRun.DELAY, OpenWhenReady) end + return + end + OpenWhenReady() +end) + +ns.Events.RegisterCallback(FirstRun, "Initialized", function() + if FirstRun:IsDone() then return end + if not ns.Config.freshInstall then + FirstRun:MarkDone() + ns:Print("New: /uf welcome walks you through preset looks and the most important options.") + return + end + frame:RegisterEvent("PLAYER_ENTERING_WORLD") +end) diff --git a/UnitFrames/NOTICE.txt b/UnitFrames/NOTICE.txt index dd92a78..0a76214 100644 --- a/UnitFrames/NOTICE.txt +++ b/UnitFrames/NOTICE.txt @@ -2,7 +2,8 @@ Required Notice: Copyright (c) 2026 Martin Konstantin Herrmann. Original UnitFrames code and documentation are licensed under the PolyForm Noncommercial License 1.0.0; see LICENSE. This covers original work in -UnitFrames, UnitFrames_Workbench, UnitFrames_Media and UnitFrames_ClickGrid. +UnitFrames, UnitFrames_Workbench, UnitFrames_Media, UnitFrames_ClickGrid and +UnitFrames_Onboarding. Third-party libraries, fonts, reference projects and Blizzard materials are excluded and retain their own terms. diff --git a/UnitFrames/UnitFrames.toc b/UnitFrames/UnitFrames.toc index 92d6755..34df189 100644 --- a/UnitFrames/UnitFrames.toc +++ b/UnitFrames/UnitFrames.toc @@ -112,3 +112,4 @@ Timers\Runtime.lua Core\Commands.lua Integration\Launcher.lua +Integration\Onboarding.lua diff --git a/UnitFrames_ClickGrid/NOTICE.txt b/UnitFrames_ClickGrid/NOTICE.txt index eeaeef4..cfecd08 100644 --- a/UnitFrames_ClickGrid/NOTICE.txt +++ b/UnitFrames_ClickGrid/NOTICE.txt @@ -2,7 +2,8 @@ Required Notice: Copyright (c) 2026 Martin Konstantin Herrmann. Original UnitFrames code and documentation are licensed under the PolyForm Noncommercial License 1.0.0; see LICENSE. This covers original work in -UnitFrames, UnitFrames_Workbench, UnitFrames_Media and UnitFrames_ClickGrid. +UnitFrames, UnitFrames_Workbench, UnitFrames_Media, UnitFrames_ClickGrid and +UnitFrames_Onboarding. Third-party libraries, fonts, reference projects and Blizzard materials are excluded and retain their own terms. diff --git a/UnitFrames_Media/NOTICE.txt b/UnitFrames_Media/NOTICE.txt index efee59c..a2be83c 100644 --- a/UnitFrames_Media/NOTICE.txt +++ b/UnitFrames_Media/NOTICE.txt @@ -2,7 +2,8 @@ Required Notice: Copyright (c) 2026 Martin Konstantin Herrmann. Original UnitFrames code and documentation are licensed under the PolyForm Noncommercial License 1.0.0; see LICENSE. This covers original work in -UnitFrames, UnitFrames_Workbench, UnitFrames_Media and UnitFrames_ClickGrid. +UnitFrames, UnitFrames_Workbench, UnitFrames_Media, UnitFrames_ClickGrid and +UnitFrames_Onboarding. Third-party libraries, fonts, reference projects and Blizzard materials are excluded and retain their own terms. diff --git a/UnitFrames_Onboarding/LICENSE b/UnitFrames_Onboarding/LICENSE new file mode 100644 index 0000000..5ecc88c --- /dev/null +++ b/UnitFrames_Onboarding/LICENSE @@ -0,0 +1,73 @@ +# PolyForm Noncommercial License 1.0.0 + + + +## Acceptance + +In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses. + +## Copyright License + +The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license). + +## Distribution License + +The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license). + +## Notices + +You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example: + +> Required Notice: Copyright Yoyodyne, Inc. (http://example.com) + +## Changes and New Works License + +The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose. + +## Patent License + +The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software. + +## Noncommercial Purposes + +Any noncommercial purpose is a permitted purpose. + +## Personal Uses + +Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose. + +## Noncommercial Organizations + +Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding. + +## Fair Use + +You may have "fair use" rights for the software under the law. These terms do not limit them. + +## No Other Rights + +These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses. + +## Patent Defense + +If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company. + +## Violations + +The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately. + +## No Liability + +***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.*** + +## Definitions + +The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms. + +**You** refers to the individual or entity agreeing to these terms. + +**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect. + +**Your licenses** are all the licenses granted to you for the software under these terms. + +**Use** means anything you do with the software requiring one of your licenses. diff --git a/UnitFrames_Onboarding/NOTICE.txt b/UnitFrames_Onboarding/NOTICE.txt new file mode 100644 index 0000000..41c3620 --- /dev/null +++ b/UnitFrames_Onboarding/NOTICE.txt @@ -0,0 +1,24 @@ +Required Notice: Copyright (c) 2026 Martin Konstantin Herrmann. + +Original UnitFrames code and documentation are licensed under the PolyForm +Noncommercial License 1.0.0; see LICENSE. This covers original work in +UnitFrames, UnitFrames_Workbench, UnitFrames_Media, UnitFrames_ClickGrid and +UnitFrames_Onboarding. +Third-party libraries, fonts, reference projects and Blizzard materials are +excluded and retain their own terms. + +Additional permission for LGPL compatibility: +The copyright holder additionally permits modification of the original code +for the user's own use and reverse engineering to debug modifications to an +LGPL-covered library. Users may modify or replace that library under its +own terms. This permission does not grant commercial redistribution of the +original UnitFrames code. Preserve this permission with redistributed copies. + +This addon uses components and libraries supplied by the required UnitFrames +addon; see that addon's NOTICE.txt and third-party license files. +Blizzard icons, atlases, textures and fonts are referenced from the WoW client +and are not bundled as asset files. No ownership or redistribution permission +for them is claimed. Media registered by other addons retains its owners' terms. + +The original code's noncommercial restriction does not restrict rights under +third-party licenses. Preserve this notice when redistributing the addon. diff --git a/UnitFrames_Onboarding/Onboarding.lua b/UnitFrames_Onboarding/Onboarding.lua new file mode 100644 index 0000000..292b29b --- /dev/null +++ b/UnitFrames_Onboarding/Onboarding.lua @@ -0,0 +1,123 @@ +local _, ob = ... +local UF = UnitFrames +local Pending, Steps = ob.Pending, ob.Steps + +--[[ +Getting started: four steps over the shell. UF:OpenOnboarding() loads this +addon and calls Open. Closing it any way (Skip, Escape, the close button, +finishing) marks the guide done, so it never opens by itself again. Combat +hides it with the choices kept; it comes back when combat ends. +]] +local Onboarding = { steps = { Steps.Look, Steps.Tweaks, Steps.Extras, Steps.Ready } } +UF.Onboarding = Onboarding +ob.Onboarding = Onboarding + +local APPLY_STEP = 3 + +function Onboarding:Build() + self.shell = ob.Shell:New(self, self.steps) + local frame = self.shell.frame + frame:SetScript("OnUpdate", function(_, elapsed) self:OnUpdate(elapsed) end) + frame:SetScript("OnHide", function() self:OnHidden() end) + frame:SetScript("OnEvent", function(_, event) self:OnEvent(event) end) + frame:RegisterEvent("PLAYER_REGEN_DISABLED") + frame:RegisterEvent("PLAYER_REGEN_ENABLED") + Pending.onChange = function() + local step = self.steps[self.index] + if step and step.page and step.Refresh and self.shell.frame:IsShown() then step:Refresh() end + end +end + +function Onboarding:Open() + if not self.shell then self:Build() end + if InCombatLockdown() then + self.pendingOpen = true + UF:Print("Getting started opens when combat ends.") + return + end + if self.shell.frame:IsShown() then return end + Pending:Reset() + self.shell:Show() + self:Go(1) +end + +function Onboarding:IsShown() + return self.shell ~= nil and self.shell.frame:IsShown() +end + +function Onboarding:Close() + if self.shell then self.shell.frame:Hide() end +end + +function Onboarding:Go(index) + local current = self.steps[self.index] + if current and current.page then + if current.Leave then current:Leave() end + current.page:Hide() + end + self.index = index + local step = self.steps[index] + if not step.page then + step.page = CreateFrame("Frame", nil, self.shell.body) + step.page:SetPoint("TOPLEFT") + step.page:SetSize(ob.Shell.PAGE_WIDTH, ob.Shell.PAGE_HEIGHT) + step:Build(step.page, self) + end + step.page:Show() + self.shell:SetStep(index, step, #self.steps) + step:Enter() +end + +function Onboarding:Next() + if self.index == #self.steps then + self:Close() + return + end + if self.index == APPLY_STEP then + local ok, reason = Pending:Apply() + if not ok then + self.shell:SetMessage(reason) + return + end + end + self:Go(self.index + 1) +end + +function Onboarding:Back() + if self.index > 1 and self.index < #self.steps then self:Go(self.index - 1) end +end + +-- The rail: earlier steps only, and not once the look is applied. +function Onboarding:Jump(index) + if index < self.index and self.index < #self.steps then self:Go(index) end +end + +function Onboarding:OnUpdate(elapsed) + self.shell:Tick(elapsed) + local step = self.steps[self.index] + if step and step.Tick then step:Tick(elapsed) end +end + +function Onboarding:OnHidden() + if self.combatHidden then return end + local step = self.steps[self.index] + if step and step.page and step.Leave then step:Leave() end + self.index = nil + UF.FirstRun:MarkDone() +end + +function Onboarding:OnEvent(event) + if event == "PLAYER_REGEN_DISABLED" then + if not self:IsShown() then return end + self.combatHidden = true + self.shell.frame:Hide() + return + end + if self.combatHidden then + self.combatHidden = false + self.shell:Show() + elseif self.pendingOpen then + self.pendingOpen = false + self:Open() + end +end diff --git a/UnitFrames_Onboarding/Pending.lua b/UnitFrames_Onboarding/Pending.lua new file mode 100644 index 0000000..068d85a --- /dev/null +++ b/UnitFrames_Onboarding/Pending.lua @@ -0,0 +1,133 @@ +local _, ob = ... +local UF = UnitFrames +local Util, Schema = UF.Util, UF.Schema +local Presets = ob.Presets + +--[[ +The choices made so far: a preset, tweaks on top of it, a size and extras. +Nothing is saved until Apply; Style() composes a fresh style table from the +choices each time, and Resolved() its effective values for the steps. +]] +local Pending = {} +ob.Pending = Pending + +local function Base(style) + style = Util.Copy(style) + style.theme, style.units, style.timers = style.theme or {}, style.units or {}, style.timers or {} + for _, unit in ipairs(UF.Units.order) do style.units[unit] = style.units[unit] or {} end + return style +end + +-- Effective values of a style: { theme, units = { [unit] = resolved }, timers }. +function Pending.Resolve(style) + local theme = Schema.Defaults(UF.Theme.schema, style.theme) + local resolved = { theme = theme, units = {}, timers = Schema.Resolve(UF.Timers:GetSchema(), style.timers, theme) } + for _, unit in ipairs(UF.Units.order) do + resolved.units[unit] = Schema.Resolve(UF.Units:GetSchema(unit), style.units[unit], theme) + end + return resolved +end + +-- A preset as shipped, for the cards in step 1. +function Pending.PresetStyle(preset) + return Base(preset.style) +end + +local function Round(value) + return math.floor(value + 0.5) +end + +-- Scales every frame's width and bar heights from their effective values. +local function Scale(style, factor) + if factor == 1 then return end + local resolved = Pending.Resolve(style) + for _, unit in ipairs(UF.Units.order) do + local values, config = resolved.units[unit], style.units[unit] + config.width = Round(values.width * factor) + Util.SetPath(config, "health.height", math.max(2, Round(values.health.height * factor))) + Util.SetPath(config, "power.height", math.max(2, Round(values.power.height * factor))) + end +end + +function Pending:Reset() + self.preset = Presets.byId.default + self.tweaks, self.extras, self.size = {}, {}, "normal" + self.newProfile = true + self.result = nil + self:Changed() +end + +function Pending:Changed() + self.style, self.resolved = nil, nil + if self.onChange then self.onChange() end +end + +-- Choosing another look starts its tweaks afresh; extras stay. +function Pending:SelectPreset(id) + self.preset = Presets.byId[id] + self.tweaks, self.size = {}, "normal" + self:Changed() +end + +function Pending:Style() + if not self.style then + local style = Base(self.preset.style) + for _, tweak in ipairs(Presets.tweaks) do + local value = self.tweaks[tweak.key] + if value ~= nil and tweak.write then tweak.write(style, value) end + end + for _, extra in ipairs(Presets.extras) do + local value = self.extras[extra.key] + if value ~= nil then extra.write(style, value) end + end + Scale(style, Presets.SIZES[self.size]) + self.style = style + end + return self.style +end + +function Pending:Resolved() + if not self.resolved then self.resolved = Pending.Resolve(self:Style()) end + return self.resolved +end + +function Pending:GetTweak(key) + return Presets.tweaksByKey[key].read(self:Resolved(), self) +end + +function Pending:SetTweak(key, value) + if key == "size" then self.size = value else self.tweaks[key] = value end + self:Changed() +end + +function Pending:GetExtra(key) + return Presets.extrasByKey[key].read(self:Resolved()) +end + +function Pending:SetExtra(key, enabled) + self.extras[key] = enabled + self:Changed() +end + +function Pending:SetNewProfile(enabled) + self.newProfile = enabled and true or false +end + +--[[ +Saves the composed style through the same validation as an imported string: +into a new profile named after the look (made active, keeping positions), or +over the active profile. Returns true and the profile's name, or false and a +reason; nothing is written when it fails. +]] +function Pending:Apply() + local apply, reason = UF.Profiles:Prepare("style", self:Style()) + if not apply then return false, reason end + if self.newProfile then + local ok, created = UF.Profiles:Create(UF.Profiles:UniqueName(self.preset.name .. " look")) + if not ok then return false, created end + end + apply() + UF.FirstRun:MarkDone() + self.result = UF.Profiles:GetCurrent() + return true, self.result +end diff --git a/UnitFrames_Onboarding/Presets.lua b/UnitFrames_Onboarding/Presets.lua new file mode 100644 index 0000000..85e40e7 --- /dev/null +++ b/UnitFrames_Onboarding/Presets.lua @@ -0,0 +1,140 @@ +local _, ob = ... +local UF = UnitFrames + +--[[ +Getting started data. A preset's `style` has the shape of a style string's +data (Core/Profiles.lua: theme, units, sections such as timers), so it goes +through the same validation as an import. Missing parts mean defaults: every +preset replaces the theme, all unit frames and the timers. + +Tweaks (step 2) and extras (step 3) change a composed copy of a preset: + write(style, value) change the style table + read(resolved) -> value the current choice, from Pending:Resolved() +]] +local Presets = { byId = {}, tweaksByKey = {}, extrasByKey = {} } +ob.Presets = Presets + +local function EveryUnit(config) + local units = {} + for _, unit in ipairs(UF.Units.order) do units[unit] = UF.Util.Copy(config) end + return units +end + +Presets.list = { + { id = "default", name = "Default", tags = { "Balanced", "3D portraits" }, + pitch = "The shared UnitFrames style: centred texts, 3D portraits and a standalone castbar.", + style = {} }, + { id = "minimal", name = "Minimal", tags = { "Flat", "No portraits" }, + pitch = "Flat bars with a one-pixel border and no portraits. Calm and compact.", + style = { + theme = { borderTexture = "UnitFrames Pixel", borderSize = 1, borderColor = { 0, 0, 0, 1 }, + barTexture = "Solid", backgroundColor = { 0.06, 0.06, 0.08, 0.85 } }, + units = EveryUnit({ portrait = { enabled = false }, border = { padding = 1, inset = 1 } }), + } }, + { id = "classic", name = "Classic", tags = { "Gold trim", "Portraits" }, + pitch = "A nod to the old frames: gold trim, painted portraits and green health bars.", + style = { + theme = { font = "Friz Quadrata TT", fontSize = 12, borderTexture = "Blizzard Dialog Gold", borderSize = 16, + borderColor = { 1, 1, 1, 1 }, barTexture = "Blizzard" }, + units = EveryUnit({ portrait = { mode = "2D" }, health = { colorMode = "theme" }, border = { padding = 5, inset = 4 } }), + } }, + { id = "healer", name = "Healer", tags = { "Wide bars", "Class colours" }, + pitch = "Wide, tall health bars in class colours. Pairs well with ClickGrid for your group.", + style = { + theme = { barTexture = "Blizzard Raid Bar", fontSize = 12 }, + units = EveryUnit({ portrait = { enabled = false }, health = { colorMode = "class", height = 30 } }), + } }, +} + +-- Writes `path` = value into every unit frame of a style. +local function AllUnits(path) + return function(style, value) + for _, unit in ipairs(UF.Units.order) do UF.Util.SetPath(style.units[unit], path, value) end + end +end + +local BORDERS = { + none = { borderTexture = "None", borderSize = 1 }, + pixel = { borderTexture = "UnitFrames Pixel", borderSize = 1, borderColor = { 0, 0, 0, 1 } }, + tooltip = { borderTexture = "Blizzard Tooltip", borderSize = 12, borderColor = { 0.5, 0.5, 0.5, 1 } }, + gold = { borderTexture = "Blizzard Dialog Gold", borderSize = 16, borderColor = { 1, 1, 1, 1 } }, +} +local BORDER_OF = { None = "none", ["UnitFrames Pixel"] = "pixel", ["Blizzard Tooltip"] = "tooltip", ["Blizzard Dialog Gold"] = "gold" } + +Presets.SIZES = { compact = 0.85, normal = 1, large = 1.2 } + +Presets.tweaks = { + { key = "font", label = "Font", media = "font", choices = { + { "Roboto Condensed Medium", "Roboto" }, { "Friz Quadrata TT", "Friz Quadrata" }, + { "Arial Narrow", "Arial Narrow" }, { "Morpheus", "Morpheus" } }, + write = function(style, value) style.theme.font = value end, + read = function(resolved) return resolved.theme.font end }, + { key = "barTexture", label = "Bar texture", media = "statusbar", choices = { + { "Solid", "Flat" }, { "Blizzard Raid Bar", "Raid bar" }, { "Blizzard", "Classic" }, { "Blizzard Character Skills Bar", "Gloss" } }, + write = function(style, value) style.theme.barTexture = value end, + read = function(resolved) return resolved.theme.barTexture end }, + { key = "border", label = "Border", choices = { { "none", "None" }, { "pixel", "Pixel" }, { "tooltip", "Tooltip" }, { "gold", "Gold" } }, + write = function(style, value) UF.Util.Merge(style.theme, UF.Util.Copy(BORDERS[value])) end, + read = function(resolved) return BORDER_OF[resolved.theme.borderTexture] end }, + { key = "healthColor", label = "Health colour", choices = { { "class", "Class" }, { "theme", "Green" }, { "gradient", "Gradient" } }, + write = AllUnits("health.colorMode"), + read = function(resolved) return resolved.units.player.health.colorMode end }, + { key = "portrait", label = "Portraits", choices = { { "3D", "3D" }, { "2D", "Painted" }, { "class", "Class icon" }, { "off", "Off" } }, + write = function(style, value) + AllUnits("portrait.enabled")(style, value ~= "off") + if value ~= "off" then AllUnits("portrait.mode")(style, value) end + end, + read = function(resolved) + local portrait = resolved.units.player.portrait + return portrait.enabled and portrait.mode or "off" + end }, + { key = "size", label = "Size", choices = { { "compact", "Compact" }, { "normal", "Normal" }, { "large", "Large" } }, + read = function(_, pending) return pending.size end }, +} + +local function UnitExtra(unit, path, extra) + extra.write = function(style, value) UF.Util.SetPath(style.units[unit], path, value) end + extra.read = function(resolved) return UF.Util.GetPath(resolved.units[unit], path) == true end + return extra +end + +local function TimerExtra(path, extra) + extra.write = function(style, value) UF.Util.SetPath(style.timers, path, value) end + extra.read = function(resolved) return UF.Util.GetPath(resolved.timers, path) == true end + extra.area, extra.accent = "center", "cast" + return extra +end + +-- Step 3 tiles; `area` places them on the screen map (Steps/Extras.lua). +Presets.extras = { + UnitExtra("player", "castbar.enabled", { key = "playerCast", label = "Player castbar", area = "player", + hint = "A castbar attached to your own frame." }), + UnitExtra("player", "experience.enabled", { key = "playerXP", label = "Experience", area = "player", + hint = "Your XP and rested bar under the player frame." }), + UnitExtra("player", "comboPoints.enabled", { key = "comboPoints", label = "Combo points", area = "player", + hint = "Pips for rogues and druids in cat form." }), + UnitExtra("target", "castbar.enabled", { key = "targetCast", label = "Target castbar", area = "target", + hint = "See what your target is casting, and whether you can interrupt it." }), + UnitExtra("focus", "castbar.enabled", { key = "focusCast", label = "Focus castbar", area = "focus", + hint = "Keep an eye on your focus target's casts." }), + TimerExtra("enabled", { key = "timers", label = "Timer bars", + hint = "A big standalone castbar in the middle of the screen." }), + TimerExtra("castbar.gcd.enabled", { key = "gcd", label = "Global cooldown", + hint = "A thin global cooldown sweep under the timer castbar." }), + TimerExtra("mainHand.enabled", { key = "swing", label = "Swing timer", + hint = "Main-hand swings, for melee classes." }), +} + +for _, preset in ipairs(Presets.list) do Presets.byId[preset.id] = preset end +for _, tweak in ipairs(Presets.tweaks) do Presets.tweaksByKey[tweak.key] = tweak end +for _, extra in ipairs(Presets.extras) do Presets.extrasByKey[extra.key] = extra end + +-- Choices this client can show: media choices need their LibSharedMedia key. +function Presets.Choices(tweak) + if not tweak.media then return tweak.choices end + local choices = {} + for _, choice in ipairs(tweak.choices) do + if UF.Media.LSM:IsValid(tweak.media, choice[1]) then choices[#choices + 1] = choice end + end + return choices +end diff --git a/UnitFrames_Onboarding/Preview.lua b/UnitFrames_Onboarding/Preview.lua new file mode 100644 index 0000000..381d362 --- /dev/null +++ b/UnitFrames_Onboarding/Preview.lua @@ -0,0 +1,94 @@ +local _, ob = ... +local UF = UnitFrames + +--[[ +Sample unit frames in a style that isn't saved. They are built, applied and +filled inside Config:WithTheme with that style's own theme, so neither the +live frames nor the saved style are read or changed. + + layout: array of { unit, point = { SetPoint arguments }, buffs, debuffs, cast, dots } + opts: animated +]] +local Preview = UF.Object:Extend("OnboardingPreview") +ob.Preview = Preview + +local FRAME_INTERVAL = 1 / 30 + +local DOT = { name = "Corruption", school = 32 } + +local function Slice(list, count) + local out = {} + for index = 1, math.min(count or 0, #list) do out[index] = list[index] end + return out +end + +-- Plain sample values; animated, health and power drift and casts loop. +local function Values(slot, time) + local v = UF.Units:GetSample(slot.unit) + local phase = slot.unit == "player" and 0 or 2.1 + local wave = time and 0.5 + 0.5 * math.sin(time * 0.8 + phase) or 0.55 + v.health = v.healthMax * (0.38 + 0.52 * wave) + v.absorb = v.healthMax * 0.12 + v.power = v.powerMax * (0.85 - 0.45 * wave) + v.pendingDamage = {} + if slot.dots then + v.pendingDamage[1] = { name = DOT.name, school = DOT.school, damage = v.healthMax * 0.14 } + end + v.showCast = slot.cast == true + v.castProgress = time and (time + phase) % 2.4 / 2.4 or 0.6 + if time then v.gcdProgress = time % 1.5 / 1.5 end + v.categoryAuras = {} + v.buffs = Slice(v.buffs, slot.buffs) + v.debuffs = Slice(v.debuffs, slot.debuffs) + v.animateAuras = time ~= nil + return v +end + +function Preview:Init(parent, layout, opts) + self.parent, self.layout, self.opts = parent, layout, opts or {} + self.frames, self.time, self.elapsed = {}, 0, 0 +end + +local function Build(self, style) + for index, slot in ipairs(self.layout) do + local config = style.units[slot.unit] + local frame = self.frames[index] + if not frame then + frame = UF.Units:CreateFromDefinition(UF.Units:GetDefinition(slot.unit), self.parent, config) + frame:SetPoint(unpack(slot.point)) + self.frames[index] = frame + end + frame:Apply(config) + end +end + +local function Fill(self, time) + for index, slot in ipairs(self.layout) do + UF.Units:ShowSample(self.frames[index], Values(slot, time)) + end +end + +-- Shows `style` (Pending:Style()) with its resolved theme. +function Preview:Show(style, theme) + self.style, self.theme = style, theme + UF.Config:WithTheme(theme, Build, self, style) + self:Update() +end + +function Preview:Update() + if not self.theme then return end + UF.Config:WithTheme(self.theme, Fill, self, self.opts.animated and self.time or nil) +end + +function Preview:Tick(elapsed) + if not self.opts.animated or not self.theme then return end + self.time, self.elapsed = self.time + elapsed, self.elapsed + elapsed + if self.elapsed < FRAME_INTERVAL then return end + self.elapsed = 0 + self:Update() +end + +function Preview:Release() + for _, frame in ipairs(self.frames) do frame:Release() end + self.frames, self.style, self.theme = {}, nil, nil +end diff --git a/UnitFrames_Onboarding/Shell.lua b/UnitFrames_Onboarding/Shell.lua new file mode 100644 index 0000000..97d2168 --- /dev/null +++ b/UnitFrames_Onboarding/Shell.lua @@ -0,0 +1,199 @@ +local _, ob = ... +local UF = UnitFrames +local Skin = UF.Skin +local C, COLORS = Skin.colors, ob.COLORS + +--[[ +The guide's frame: a dimmed full-screen backdrop (Escape closes it), the +window with its step rail on the left, the step's title, a page area and the +footer (Back, step count, the primary action). Pages fade and slide in. +]] +local Shell = UF.Object:Extend("OnboardingShell") +ob.Shell = Shell + +Shell.WIDTH, Shell.HEIGHT, Shell.RAIL = 1060, 660, 230 +Shell.PAGE_WIDTH, Shell.PAGE_HEIGHT = 770, 470 +local NODE_GAP, TRANSITION, SLIDE = 64, 0.2, 24 +local ICON_COORDS = { 0, 0.25, 0, 0.25 } + +local function Ease(progress) + return 1 - (1 - progress) ^ 3 +end + +local function PrimaryButton(parent, onClick) + local button = CreateFrame("Button", nil, parent, "BackdropTemplate") + ob.Panel(button, C.accent) + ob.Glow(button, C.accent):Show() + button.text = ob.Text(button, 14, COLORS.ink, true) + button.text:SetPoint("CENTER") + button:SetScript("OnClick", onClick) + button:SetScript("OnEnter", function() ob.Paint(button, { 0.45, 0.73, 1, 1 }) end) + button:SetScript("OnLeave", function() ob.Paint(button, C.accent) end) + return button +end + +function Shell:BuildRail(window, steps, owner) + local rail = CreateFrame("Frame", nil, window, "BackdropTemplate") + rail:SetPoint("TOPLEFT", 1, -3) + rail:SetPoint("BOTTOMLEFT", 1, 1) + rail:SetWidth(Shell.RAIL) + ob.Panel(rail, COLORS.rail) + local icon = rail:CreateTexture(nil, "ARTWORK") + icon:SetTexture([[Interface\Glues\CharacterCreate\UI-CharacterCreate-Classes]]) + icon:SetTexCoord(unpack(ICON_COORDS)) + icon:SetSize(30, 30) + icon:SetPoint("TOPLEFT", 28, -34) + local brand = ob.Text(rail, 11, C.accent, true) + brand:SetPoint("TOPLEFT", icon, "TOPRIGHT", 10, 1) + brand:SetText("UNITFRAMES") + local title = ob.Text(rail, 19, C.text, true) + title:SetPoint("TOPLEFT", brand, "BOTTOMLEFT", 0, -3) + title:SetText("Getting started") + + local top = -112 + local line = rail:CreateTexture(nil, "BORDER") + line:SetColorTexture(unpack(C.border)) + line:SetSize(2, NODE_GAP * (#steps - 1)) + line:SetPoint("TOPLEFT", 39, top - 11) + self.progress = rail:CreateTexture(nil, "ARTWORK") + self.progress:SetColorTexture(unpack(C.accent)) + self.progress:SetPoint("TOPLEFT", line, "TOPLEFT") + self.progress:SetSize(2, 1) + self.nodes = {} + for index, step in ipairs(steps) do + local node = CreateFrame("Button", nil, rail) + node:SetSize(Shell.RAIL - 40, 24) + node:SetPoint("TOPLEFT", 28, top - (index - 1) * NODE_GAP) + node.box = CreateFrame("Frame", nil, node, "BackdropTemplate") + node.box:SetSize(24, 24) + node.box:SetPoint("LEFT") + ob.Panel(node.box, C.panel, C.border) + node.glow = ob.Glow(node.box, C.accent) + node.number = ob.Text(node.box, 12, C.textDim, true) + node.number:SetPoint("CENTER") + node.number:SetText(index) + node.check = node.box:CreateTexture(nil, "OVERLAY") + node.check:SetTexture(ob.CHECK) + node.check:SetVertexColor(unpack(COLORS.ink)) + node.check:SetAllPoints() + node.label = ob.Text(node, 14) + node.label:SetPoint("LEFT", node.box, "RIGHT", 12, 0) + node.label:SetText(step.label) + node:SetScript("OnClick", function() owner:Jump(index) end) + self.nodes[index] = node + end + + local skip = CreateFrame("Button", nil, rail) + skip:SetSize(120, 18) + skip:SetPoint("BOTTOMLEFT", 28, 58) + local skipText = ob.Text(skip, 12, C.textDim) + skipText:SetPoint("LEFT") + skipText:SetText("Skip for now") + skip:SetScript("OnClick", function() owner:Close() end) + skip:SetScript("OnEnter", function() skipText:SetTextColor(unpack(C.text)) end) + skip:SetScript("OnLeave", function() skipText:SetTextColor(unpack(C.textDim)) end) + self.skip = skip + local reopen = ob.Text(rail, 11, COLORS.faint) + reopen:SetPoint("TOPLEFT", skip, "BOTTOMLEFT", 0, -6) + reopen:SetText("Reopen any time: /uf welcome") +end + +function Shell:Init(owner, steps) + local backdrop = CreateFrame("Frame", "UnitFramesOnboarding", UIParent) + backdrop:SetAllPoints(UIParent) + backdrop:SetFrameStrata("FULLSCREEN_DIALOG") + backdrop:EnableMouse(true) + backdrop:Hide() + tinsert(UISpecialFrames, "UnitFramesOnboarding") + self.frame = backdrop + local dim = backdrop:CreateTexture(nil, "BACKGROUND") + dim:SetAllPoints() + dim:SetColorTexture(0, 0, 0, 0.6) + local fade = backdrop:CreateAnimationGroup() + local alpha = fade:CreateAnimation("Alpha") + alpha:SetFromAlpha(0) + alpha:SetToAlpha(1) + alpha:SetDuration(0.25) + alpha:SetSmoothing("OUT") + self.fade = fade + + local window = CreateFrame("Frame", nil, backdrop, "BackdropTemplate") + window:SetSize(Shell.WIDTH, Shell.HEIGHT) + window:SetPoint("CENTER") + window:EnableMouse(true) + ob.Panel(window, C.window, C.border) + local accent = window:CreateTexture(nil, "OVERLAY") + accent:SetColorTexture(unpack(C.accent)) + accent:SetPoint("TOPLEFT", 1, -1) + accent:SetPoint("TOPRIGHT", -1, -1) + accent:SetHeight(2) + local close = CreateFrame("Button", nil, window, "UIPanelCloseButtonNoScripts") + close:SetPoint("TOPRIGHT", -4, -6) + close:SetScript("OnClick", function() owner:Close() end) + self:BuildRail(window, steps, owner) + + local left = Shell.RAIL + 32 + self.title = ob.Text(window, 28, C.text, true) + self.title:SetPoint("TOPLEFT", left, -36) + self.subtitle = ob.Text(window, 13, C.textDim) + self.subtitle:SetPoint("TOPLEFT", self.title, "BOTTOMLEFT", 0, -8) + self.subtitle:SetWidth(Shell.PAGE_WIDTH) + self.body = CreateFrame("Frame", nil, window) + self.body:SetSize(Shell.PAGE_WIDTH, Shell.PAGE_HEIGHT) + self.body:SetPoint("TOPLEFT", left, -100) + + self.back = UF.Widgets.Button:New(window, { text = "Back", width = 92, height = 34, onClick = function() owner:Back() end }) + self.back:SetPoint("BOTTOMLEFT", left, 24) + self.counter = ob.Text(window, 12, C.textDim) + self.counter:SetPoint("BOTTOM", window, "BOTTOMLEFT", left + Shell.PAGE_WIDTH / 2, 35) + self.next = PrimaryButton(window, function() owner:Next() end) + self.next:SetSize(190, 34) + self.next:SetPoint("BOTTOMRIGHT", -32, 24) + self.message = ob.Text(window, 12, C.warning) + self.message:SetPoint("BOTTOMRIGHT", self.next, "TOPRIGHT", 0, 10) +end + +function Shell:SetStep(index, step, count) + self.title:SetText(step.title) + self.subtitle:SetText(step.subtitle) + self.counter:SetText(("Step %d of %d"):format(index, count)) + self.next.text:SetText(step.nextLabel) + self.back:SetShown(index > 1 and index < count) + self.skip:SetShown(index < count) + self:SetMessage(nil) + for nodeIndex, node in ipairs(self.nodes) do + local done, current = nodeIndex < index, nodeIndex == index + ob.Paint(node.box, (done or current) and C.accent or C.panel, (done or current) and C.accent or C.border) + node.glow:SetShown(current) + node.number:SetShown(not done) + node.number:SetTextColor(unpack(current and COLORS.ink or C.textDim)) + node.check:SetShown(done) + node.label:SetTextColor(unpack((done or current) and C.text or C.textDim)) + node:SetEnabled(done and index < count) + end + self.railFrom, self.railTo = self.railTo or 0, NODE_GAP * (index - 1) + self.transition = { page = step.page, time = 0 } + step.page:SetAlpha(0) +end + +function Shell:SetMessage(text) + self.message:SetText(text or "") +end + +function Shell:Tick(elapsed) + local transition = self.transition + if not transition then return end + transition.time = transition.time + elapsed + local eased = Ease(math.min(1, transition.time / TRANSITION)) + transition.page:SetAlpha(eased) + transition.page:ClearAllPoints() + transition.page:SetPoint("TOPLEFT", SLIDE * (1 - eased), 0) + transition.page:SetSize(Shell.PAGE_WIDTH, Shell.PAGE_HEIGHT) + self.progress:SetHeight(math.max(1, self.railFrom + (self.railTo - self.railFrom) * eased)) + if eased >= 1 then self.transition = nil end +end + +function Shell:Show() + self.frame:Show() + self.fade:Play() +end diff --git a/UnitFrames_Onboarding/Steps/Extras.lua b/UnitFrames_Onboarding/Steps/Extras.lua new file mode 100644 index 0000000..0646faf --- /dev/null +++ b/UnitFrames_Onboarding/Steps/Extras.lua @@ -0,0 +1,96 @@ +local _, ob = ... +local UF = UnitFrames +local C, COLORS = UF.Skin.colors, ob.COLORS +local Pending, Presets = ob.Pending, ob.Presets + +--[[ +Step 3: a map of the screen. The frames themselves are fixed blocks; the +extras around them are tiles to switch on or off. Below it, whether the +look goes into a new profile. Next applies everything. +]] +local Extras = { + label = "Extras", + title = "Add the extras", + subtitle = "Click a tile to switch it on or off. You'll drag everything into place in Edit Mode at the end.", + nextLabel = "Apply and finish", +} +ob.Steps.Extras = Extras + +local MAP_HEIGHT, TILE_WIDTH, TILE_HEIGHT, TILE_GAP = 400, 170, 28, 6 + +-- Fixed blocks (centre offsets on the map) and where each area's tiles start. +local BLOCKS = { + { label = "Player", x = -200, y = 50, width = 170, height = 44 }, + { label = "Target", x = 200, y = 50, width = 170, height = 44 }, + { label = "Focus", x = 200, y = 150, width = 150, height = 36 }, +} +local AREAS = { player = { -200, 0 }, target = { 200, 0 }, focus = { 200, 108 }, center = { 0, -78 } } + +local function Block(map, block) + local frame = CreateFrame("Frame", nil, map, "BackdropTemplate") + frame:SetSize(block.width, block.height) + frame:SetPoint("CENTER", block.x, block.y) + ob.Panel(frame, { C.accent[1], C.accent[2], C.accent[3], 0.1 }, { C.accent[1], C.accent[2], C.accent[3], 0.45 }) + local text = ob.Text(frame, 13, C.text, true) + text:SetPoint("CENTER") + text:SetText(block.label) +end + +function Extras:Build(page) + local map = ob.Stage(page, ob.Shell.PAGE_WIDTH, MAP_HEIGHT) + map:SetPoint("TOPLEFT") + self.map = map + local bars = map:CreateTexture(nil, "ARTWORK") + bars:SetColorTexture(1, 1, 1, 0.05) + bars:SetSize(260, 14) + bars:SetPoint("BOTTOM", 0, 14) + local barsText = ob.Text(map, 10, COLORS.faint) + barsText:SetPoint("CENTER", bars, "CENTER") + barsText:SetText("action bars") + for _, block in ipairs(BLOCKS) do Block(map, block) end + + self.tiles = {} + local placed = {} + for _, extra in ipairs(Presets.extras) do + local area = AREAS[extra.area] + local index = placed[extra.area] or 0 + placed[extra.area] = index + 1 + local tile = ob.Widgets.Chip:New(map, { text = extra.label, width = TILE_WIDTH, height = TILE_HEIGHT, dot = true, + accent = extra.accent and COLORS[extra.accent] or nil, tooltip = extra.hint, + onClick = function() Pending:SetExtra(extra.key, not Pending:GetExtra(extra.key)) end }) + tile:SetPoint("CENTER", area[1], area[2] - index * (TILE_HEIGHT + TILE_GAP)) + self.tiles[extra.key] = tile + end + + self.newProfile = UF.Widgets.Checkbox:New(page, { label = "Save as a new profile", + onChange = function(value) Pending:SetNewProfile(value); self:Refresh() end }) + self.newProfile:SetPoint("TOPLEFT", 0, -(MAP_HEIGHT + 20)) + self.newProfile:SetWidth(240) + self.profileNote = ob.Text(page, 12, C.textDim) + self.profileNote:SetPoint("TOPLEFT", 0, -(MAP_HEIGHT + 46)) + self.profileNote:SetWidth(ob.Shell.PAGE_WIDTH) +end + +function Extras:Refresh() + local on, count = 0, 0 + for key, tile in pairs(self.tiles) do + local enabled = Pending:GetExtra(key) + tile:SetSelected(enabled) + count = count + 1 + if enabled then on = on + 1 end + end + self.map.caption:SetText(("%d OF %d EXTRAS ON"):format(on, count)) + self.map.note:SetText("Hover a tile to see what it adds.") + self.newProfile:SetValue(Pending.newProfile) + if Pending.newProfile then + self.profileNote:SetText(("A new profile \"%s\" gets this look. Your current profile \"%s\" stays as it is.") + :format(UF.Profiles:UniqueName(Pending.preset.name .. " look"), UF.Profiles:GetCurrent())) + else + self.profileNote:SetText(("This look replaces the style of your current profile \"%s\". Frame positions stay.") + :format(UF.Profiles:GetCurrent())) + end +end + +function Extras:Enter() + self:Refresh() +end diff --git a/UnitFrames_Onboarding/Steps/Look.lua b/UnitFrames_Onboarding/Steps/Look.lua new file mode 100644 index 0000000..f8b6ea8 --- /dev/null +++ b/UnitFrames_Onboarding/Steps/Look.lua @@ -0,0 +1,95 @@ +local _, ob = ... +local UF = UnitFrames +local C, COLORS = UF.Skin.colors, ob.COLORS +local Pending, Presets = ob.Pending, ob.Presets + +--[[ +Step 1: an animated stage (player with a cast, target with DoTs) in the +chosen look, and a card per preset with a still mini preview of its own. +]] +ob.Steps = ob.Steps or {} +local Look = { + label = "Pick a look", + title = "Pick a look", + subtitle = "Start from a style you like. Everything stays adjustable later; this gets you most of the way there.", + nextLabel = "Next: make it yours", +} +ob.Steps.Look = Look + +local STAGE_HEIGHT, CARD_WIDTH, CARD_GAP, CARD_SCALE = 272, 186, 8, 0.6 + +local STAGE_LAYOUT = { + { unit = "player", point = { "CENTER", -190, 6 }, cast = true, buffs = 4 }, + { unit = "target", point = { "CENTER", 190, 6 }, dots = true, debuffs = 3 }, +} + +-- A dark preview well with faint guide lines, as on the mockups. +function ob.Stage(parent, width, height) + local stage = CreateFrame("Frame", nil, parent, "BackdropTemplate") + stage:SetSize(width, height) + ob.Panel(stage, COLORS.well, C.border) + for x = 20, width - 1, 40 do + local line = stage:CreateTexture(nil, "BACKGROUND", nil, 1) + line:SetColorTexture(1, 1, 1, 0.025) + line:SetPoint("TOPLEFT", x, -1) + line:SetPoint("BOTTOMLEFT", x, 1) + line:SetWidth(1) + end + stage.caption = ob.Text(stage, 12, C.accent, true) + stage.caption:SetPoint("TOPLEFT", 16, -14) + stage.note = ob.Text(stage, 11, C.textDim) + stage.note:SetPoint("TOPLEFT", stage.caption, "BOTTOMLEFT", 0, -4) + stage.note:SetWidth(width - 32) + local live = stage:CreateTexture(nil, "OVERLAY") + live:SetColorTexture(0.33, 1, 0.47, 1) + live:SetSize(6, 6) + live:SetPoint("BOTTOMLEFT", 18, 18) + local liveText = ob.Text(stage, 11, C.textDim) + liveText:SetPoint("LEFT", live, "RIGHT", 8, 0) + liveText:SetText("Live preview with sample data") + return stage +end + +function Look:Build(page, owner) + self.owner = owner + self.stage = ob.Stage(page, ob.Shell.PAGE_WIDTH, STAGE_HEIGHT) + self.stage:SetPoint("TOPLEFT") + self.preview = ob.Preview:New(self.stage, STAGE_LAYOUT, { animated = true }) + self.cards, self.cardPreviews = {}, {} + for index, preset in ipairs(Presets.list) do + local card = ob.Widgets.Card:New(page, { name = preset.name, tags = preset.tags, width = CARD_WIDTH, + onClick = function() Pending:SelectPreset(preset.id) end }) + card:SetPoint("TOPLEFT", (index - 1) * (CARD_WIDTH + CARD_GAP), -(STAGE_HEIGHT + 22)) + local holder = CreateFrame("Frame", nil, card.well) + holder:SetScale(CARD_SCALE) + holder:SetSize(CARD_WIDTH / CARD_SCALE, card.well:GetHeight() / CARD_SCALE) + holder:SetPoint("CENTER", card.well, "CENTER") + self.cards[preset.id] = card + self.cardPreviews[preset.id] = ob.Preview:New(holder, { { unit = "player", point = { "CENTER" } } }) + end +end + +function Look:Refresh() + local preset = Pending.preset + self.stage.caption:SetText(preset.name:upper()) + self.stage.note:SetText(preset.pitch) + self.preview:Show(Pending:Style(), Pending:Resolved().theme) + for id, card in pairs(self.cards) do card:SetSelected(id == preset.id) end +end + +function Look:Enter() + for _, preset in ipairs(Presets.list) do + local style = Pending.PresetStyle(preset) + self.cardPreviews[preset.id]:Show(style, Pending.Resolve(style).theme) + end + self:Refresh() +end + +function Look:Leave() + self.preview:Release() + for _, preview in pairs(self.cardPreviews) do preview:Release() end +end + +function Look:Tick(elapsed) + self.preview:Tick(elapsed) +end diff --git a/UnitFrames_Onboarding/Steps/Ready.lua b/UnitFrames_Onboarding/Steps/Ready.lua new file mode 100644 index 0000000..87f4a5c --- /dev/null +++ b/UnitFrames_Onboarding/Steps/Ready.lua @@ -0,0 +1,117 @@ +local _, ob = ... +local UF = UnitFrames +local C, COLORS = UF.Skin.colors, ob.COLORS +local Pending = ob.Pending + +--[[ +Step 4: the look is saved. One button into Edit Mode to place the frames, +and cards that open the Workbench where each topic lives. +]] +local Ready = { + label = "Ready", + title = "", + subtitle = "", + nextLabel = "Close", +} +ob.Steps.Ready = Ready + +local ICONS = [[Interface\Icons\]] +local CARD_WIDTH, CARD_HEIGHT, CARD_GAP = 248, 92, 13 + +local DESTINATIONS = { + { title = "Buffs & debuffs", body = "Icon sizes, filters, dispel colours", icon = ICONS .. "Spell_Holy_WordFortitude", + entry = "unit.player", path = "auras" }, + { title = "Texts", body = "Names, values, percentages, custom texts", icon = ICONS .. "Spell_Nature_Regeneration", + entry = "unit.player", path = "health.left" }, + { title = "Castbar & timers", body = "Global cooldown, swing and ranged timers", icon = ICONS .. "Spell_Frost_FrostBolt02", + entry = "timers" }, + { title = "Party & raid", body = "ClickGrid panels and click casting", icon = ICONS .. "Spell_Holy_FlashHeal", + entry = "clickgrid.panel", addon = "UnitFrames_ClickGrid" }, + { title = "Import a string", body = "Paste a style someone shared", icon = ICONS .. "Spell_Nature_StarFall", + entry = "profiles" }, + { title = "Everything else", body = "The whole Workbench (/uf wb)", icon = [[Interface\Glues\CharacterCreate\UI-CharacterCreate-Classes]], + coords = { 0, 0.25, 0, 0.25 }, entry = "unit.player" }, +} + +local function DigCard(parent, destination, owner) + local card = CreateFrame("Button", nil, parent, "BackdropTemplate") + card:SetSize(CARD_WIDTH, CARD_HEIGHT) + ob.Panel(card, C.panel, C.border) + local icon = card:CreateTexture(nil, "ARTWORK") + icon:SetTexture(destination.icon) + if destination.coords then icon:SetTexCoord(unpack(destination.coords)) end + icon:SetSize(40, 40) + icon:SetPoint("TOPLEFT", 16, -16) + local title = ob.Text(card, 14, C.text, true) + title:SetPoint("TOPLEFT", icon, "TOPRIGHT", 14, -2) + title:SetText(destination.title) + local body = ob.Text(card, 11, C.textDim) + body:SetPoint("TOPLEFT", title, "BOTTOMLEFT", 0, -6) + body:SetWidth(CARD_WIDTH - 96) + body:SetWordWrap(true) + body:SetText(destination.body) + local arrow = ob.Text(card, 16, COLORS.faint, true) + arrow:SetPoint("TOPRIGHT", -14, -16) + arrow:SetText(">") + card:SetScript("OnEnter", function() ob.Paint(card, C.buttonHover, C.accent); arrow:SetTextColor(unpack(C.accent)) end) + card:SetScript("OnLeave", function() ob.Paint(card, C.panel, C.border); arrow:SetTextColor(unpack(COLORS.faint)) end) + card:SetScript("OnClick", function() + owner:Close() + UF:OpenWorkbench(destination.entry, destination.path) + end) + return card +end + +local function CanEnterEditMode() + return EditModeManagerFrame ~= nil and EditModeManagerFrame:CanEnterEditMode() +end + +function Ready:Build(page, owner) + local center = ob.Shell.PAGE_WIDTH / 2 + local badge = CreateFrame("Frame", nil, page, "BackdropTemplate") + badge:SetSize(56, 56) + badge:SetPoint("TOP", page, "TOPLEFT", center, -16) + ob.Panel(badge, C.accent) + ob.Glow(badge, C.accent):Show() + local check = badge:CreateTexture(nil, "OVERLAY") + check:SetTexture(ob.CHECK) + check:SetVertexColor(unpack(COLORS.ink)) + check:SetPoint("TOPLEFT", 6, -6) + check:SetPoint("BOTTOMRIGHT", -6, 6) + local heading = ob.Text(page, 30, C.text, true) + heading:SetPoint("TOP", badge, "BOTTOM", 0, -18) + heading:SetText("You're set.") + self.summary = ob.Text(page, 13, C.textDim) + self.summary:SetPoint("TOP", heading, "BOTTOM", 0, -10) + self.summary:SetJustifyH("CENTER") + + self.editMode = UF.Widgets.Button:New(page, { text = "Place frames in Edit Mode", width = 280, height = 36, + onClick = function() + owner:Close() + if CanEnterEditMode() then ShowUIPanel(EditModeManagerFrame) end + end }) + self.editMode:SetPoint("TOP", self.summary, "BOTTOM", 0, -20) + self.editMode:SetSelected(true) + + local label = ob.Text(page, 10, C.textDim, true) + label:SetPoint("TOPLEFT", 0, -252) + label:SetText("DIG DEEPER WHEN YOU FEEL LIKE IT") + local index = 0 + for _, destination in ipairs(DESTINATIONS) do + if not destination.addon or C_AddOns.IsAddOnLoaded(destination.addon) then + local card = DigCard(page, destination, owner) + card:SetPoint("TOPLEFT", (index % 3) * (CARD_WIDTH + CARD_GAP), -270 - math.floor(index / 3) * (CARD_HEIGHT + CARD_GAP)) + index = index + 1 + end + end +end + +function Ready:Enter() + local profile = Pending.result or UF.Profiles:GetCurrent() + if Pending.newProfile then + self.summary:SetText(("Saved as the profile \"%s\". Your previous look is still one switch away in Profiles."):format(profile)) + else + self.summary:SetText(("Applied to your profile \"%s\". Frame positions stayed where they were."):format(profile)) + end + self.editMode:SetShown(CanEnterEditMode()) +end diff --git a/UnitFrames_Onboarding/Steps/Tweaks.lua b/UnitFrames_Onboarding/Steps/Tweaks.lua new file mode 100644 index 0000000..223159a --- /dev/null +++ b/UnitFrames_Onboarding/Steps/Tweaks.lua @@ -0,0 +1,78 @@ +local _, ob = ... +local UF = UnitFrames +local C = UF.Skin.colors +local Pending, Presets = ob.Pending, ob.Presets + +--[[ +Step 2: the chosen look on a stage, and a row of chips per tweak. Every chip +shows its option directly (fonts in their own face) and restyles the stage. +]] +local Tweaks = { + label = "Make it yours", + title = "Make it yours", + subtitle = "The few options that change the feel most. Hundreds more are waiting in the Workbench.", + nextLabel = "Next: extras", +} +ob.Steps.Tweaks = Tweaks + +local STAGE_WIDTH, COLUMN_GAP, CHIP_GAP, ROW_GAP = 400, 24, 8, 18 + +local STAGE_LAYOUT = { + { unit = "player", point = { "CENTER", 0, 76 }, cast = true }, + { unit = "target", point = { "CENTER", 0, -84 }, dots = true }, +} + +local function ChipRow(parent, tweak, width, top) + local label = ob.Text(parent, 10, C.textDim, true) + label:SetPoint("TOPLEFT", 0, top) + label:SetText(tweak.label:upper()) + local chips, x, y = {}, 0, top - 18 + for _, choice in ipairs(Presets.Choices(tweak)) do + local chip = ob.Widgets.Chip:New(parent, { text = choice[2], font = tweak.media == "font" and choice[1] or nil, + onClick = function() Pending:SetTweak(tweak.key, choice[1]) end }) + local chipWidth = chip.frame:GetWidth() + if x > 0 and x + chipWidth > width then x, y = 0, y - 28 - CHIP_GAP end + chip:SetPoint("TOPLEFT", x, y) + x = x + chipWidth + CHIP_GAP + chip.value = choice[1] + chips[#chips + 1] = chip + end + return chips, y - 28 - ROW_GAP +end + +function Tweaks:Build(page) + self.stage = ob.Stage(page, STAGE_WIDTH, ob.Shell.PAGE_HEIGHT) + self.stage:SetPoint("TOPLEFT") + self.preview = ob.Preview:New(self.stage, STAGE_LAYOUT, { animated = true }) + local column = CreateFrame("Frame", nil, page) + local width = ob.Shell.PAGE_WIDTH - STAGE_WIDTH - COLUMN_GAP + column:SetPoint("TOPLEFT", STAGE_WIDTH + COLUMN_GAP, -2) + column:SetSize(width, ob.Shell.PAGE_HEIGHT) + self.rows = {} + local top = 0 + for _, tweak in ipairs(Presets.tweaks) do + self.rows[tweak.key], top = ChipRow(column, tweak, width, top) + end +end + +function Tweaks:Refresh() + self.stage.caption:SetText(Pending.preset.name:upper() .. " + YOUR TWEAKS") + self.stage.note:SetText("") + self.preview:Show(Pending:Style(), Pending:Resolved().theme) + for key, chips in pairs(self.rows) do + local value = Pending:GetTweak(key) + for _, chip in ipairs(chips) do chip:SetSelected(chip.value == value) end + end +end + +function Tweaks:Enter() + self:Refresh() +end + +function Tweaks:Leave() + self.preview:Release() +end + +function Tweaks:Tick(elapsed) + self.preview:Tick(elapsed) +end diff --git a/UnitFrames_Onboarding/UnitFrames_Onboarding.toc b/UnitFrames_Onboarding/UnitFrames_Onboarding.toc new file mode 100644 index 0000000..2b8bff3 --- /dev/null +++ b/UnitFrames_Onboarding/UnitFrames_Onboarding.toc @@ -0,0 +1,21 @@ +## Interface: 16001 +## Title: UnitFrames |cff4fa3ffGetting started|r +## Notes: A guided first setup with preset looks. Open with /uf welcome. +## Author: Martin Konstantin Herrmann +## Version: dev +## X-Build-Channel: development +## X-Build-Commit: unknown +## Dependencies: UnitFrames +## OptionalDeps: UnitFrames_Media, UnitFrames_ClickGrid +## LoadOnDemand: 1 + +Presets.lua +Pending.lua +Widgets.lua +Preview.lua +Shell.lua +Steps\Look.lua +Steps\Tweaks.lua +Steps\Extras.lua +Steps\Ready.lua +Onboarding.lua diff --git a/UnitFrames_Onboarding/Widgets.lua b/UnitFrames_Onboarding/Widgets.lua new file mode 100644 index 0000000..76b4a8c --- /dev/null +++ b/UnitFrames_Onboarding/Widgets.lua @@ -0,0 +1,164 @@ +local _, ob = ... +local UF = UnitFrames +local Skin = UF.Skin +local C = Skin.colors + +--[[ +The guide's look: flat panels from the shared Skin, an accent glow made of +two soft outer rings, and Roboto Condensed headings when UnitFrames_Media +is loaded. Controls extend UF.Widget like the Workbench's. +]] +ob.COLORS = { + rail = { 0.035, 0.035, 0.05, 1 }, + well = { 0.03, 0.03, 0.045, 1 }, + ink = { 0.05, 0.05, 0.07, 1 }, + faint = { 0.36, 0.36, 0.41, 1 }, + off = { 0.13, 0.13, 0.16, 0.6 }, + cast = { 1, 0.7, 0, 1 }, + group = { 0.33, 0.84, 0.54, 1 }, + aura = { 0.69, 0.49, 1, 1 }, + import = { 1, 0.48, 0.35, 1 }, +} +local COLORS = ob.COLORS + +ob.CHECK = [[Interface\Buttons\UI-CheckBox-Check]] + +local HEADING_FONTS = { "Roboto Condensed Bold", "Friz Quadrata TT" } +local BODY_FONTS = { "Roboto Condensed", "Friz Quadrata TT" } + +local function FontKey(candidates) + for _, key in ipairs(candidates) do + if UF.Media.LSM:IsValid("font", key) then return key end + end + return UF.Media.LSM:GetDefault("font") +end + +function ob.Font(size, heading) + return UF.Media:GetFontObject(FontKey(heading and HEADING_FONTS or BODY_FONTS), size) +end + +function ob.Text(parent, size, color, heading) + local text = parent:CreateFontString(nil, "OVERLAY") + text:SetFontObject(ob.Font(size, heading)) + text:SetTextColor(unpack(color or C.text)) + text:SetJustifyH("LEFT") + return text +end + +function ob.Panel(frame, background, border) + frame:SetBackdrop({ bgFile = Skin.WHITE, edgeFile = Skin.WHITE, edgeSize = 1 }) + ob.Paint(frame, background, border) +end + +function ob.Paint(frame, background, border) + frame:SetBackdropColor(unpack(background)) + frame:SetBackdropBorderColor(unpack(border or background)) +end + +-- Two rings outside `frame` in `color`, hidden until shown. +function ob.Glow(frame, color) + local glow = CreateFrame("Frame", nil, frame) + glow:SetAllPoints() + glow:SetFrameLevel(math.max(0, frame:GetFrameLevel() - 1)) + for index, ring in ipairs({ { 2, 0.55 }, { 5, 0.18 } }) do + local edge = CreateFrame("Frame", nil, glow, "BackdropTemplate") + edge:SetPoint("TOPLEFT", -ring[1], ring[1]) + edge:SetPoint("BOTTOMRIGHT", ring[1], -ring[1]) + edge:SetBackdrop({ edgeFile = Skin.WHITE, edgeSize = index }) + edge:SetBackdropBorderColor(color[1], color[2], color[3], ring[2]) + end + glow:Hide() + return glow +end + +--[[ +Selectable flat button: chips (step 2), tiles (step 3), preset cards. +opts: text, font (LSM key), width, height, accent (colour), dot, tooltip, onClick(self) +]] +local Chip = UF.Widget:Extend("OnboardingChip") +ob.Widgets = { Chip = Chip } + +function Chip:OnCreate(parent, opts) + local frame = CreateFrame("Button", nil, parent, "BackdropTemplate") + self.frame = frame + self.accent = opts.accent or C.accent + ob.Panel(frame, C.button, C.border) + self.glow = ob.Glow(frame, self.accent) + self.text = ob.Text(frame, opts.size or 12) + self.text:SetJustifyH("CENTER") + self.text:SetPoint("CENTER") + if opts.font then self.text:SetFontObject(UF.Media:GetFontObject(opts.font, opts.size or 12)) end + self.text:SetText(opts.text or "") + frame:SetSize(opts.width or math.max(54, self.text:GetStringWidth() + 28), opts.height or 28) + if opts.dot then + self.dot = frame:CreateTexture(nil, "OVERLAY") + self.dot:SetTexture(Skin.WHITE) + self.dot:SetSize(6, 6) + self.dot:SetPoint("TOPRIGHT", -6, -6) + end + frame:SetScript("OnEnter", function() self.hover = true; self:UpdateColors() end) + frame:SetScript("OnLeave", function() self.hover = false; self:UpdateColors() end) + frame:SetScript("OnClick", function() if self.opts.onClick then self.opts.onClick(self) end end) + UF.Widget.AttachTooltip(frame, opts.text, opts.tooltip) + self:UpdateColors() +end + +function Chip:SetSelected(selected) + self.selected = selected and true or false + self:UpdateColors() +end + +function Chip:UpdateColors() + local accent, selected = self.accent, self.selected + local background = selected and { accent[1], accent[2], accent[3], 0.2 } or (self.hover and C.buttonHover or C.button) + ob.Paint(self.frame, background, (selected or self.hover) and accent or C.border) + self.text:SetTextColor(unpack(selected and accent or C.text)) + self.glow:SetShown(selected) + if self.dot then self.dot:SetVertexColor(unpack(selected and accent or COLORS.faint)) end +end + +--[[ +Preset card: a dark well for a mini preview, the name, two tags and a check +badge when chosen. opts: name, tags, onClick(self) +]] +local Card = Chip:Extend("OnboardingCard") +ob.Widgets.Card = Card + +function Card:OnCreate(parent, opts) + Chip.OnCreate(self, parent, { width = opts.width or 190, height = 176, onClick = opts.onClick, text = "" }) + local frame = self.frame + self.well = CreateFrame("Frame", nil, frame, "BackdropTemplate") + self.well:SetPoint("TOPLEFT", 1, -1) + self.well:SetPoint("TOPRIGHT", -1, -1) + self.well:SetHeight(94) + ob.Panel(self.well, COLORS.well) + self.name = ob.Text(frame, 17, C.text, true) + self.name:SetPoint("TOPLEFT", 14, -106) + self.name:SetText(opts.name) + local previous + for _, tag in ipairs(opts.tags or {}) do + local pill = CreateFrame("Frame", nil, frame, "BackdropTemplate") + ob.Panel(pill, { 1, 1, 1, 0.06 }) + local text = ob.Text(pill, 10, C.textDim) + text:SetPoint("CENTER") + text:SetText(tag) + pill:SetSize(text:GetStringWidth() + 14, 18) + pill:SetPoint("TOPLEFT", previous or frame, previous and "TOPRIGHT" or "TOPLEFT", previous and 6 or 14, previous and 0 or -138) + previous = pill + end + self.badge = CreateFrame("Frame", nil, frame, "BackdropTemplate") + self.badge:SetSize(20, 20) + self.badge:SetPoint("TOPRIGHT", -12, -104) + ob.Panel(self.badge, C.accent) + local check = self.badge:CreateTexture(nil, "OVERLAY") + check:SetTexture(ob.CHECK) + check:SetVertexColor(unpack(COLORS.ink)) + check:SetAllPoints() + self:UpdateColors() +end + +function Card:UpdateColors() + Chip.UpdateColors(self) + ob.Paint(self.frame, C.panel, (self.selected or self.hover) and C.accent or C.border) + if self.badge then self.badge:SetShown(self.selected) end +end diff --git a/UnitFrames_Workbench/NOTICE.txt b/UnitFrames_Workbench/NOTICE.txt index 8888b6d..41c3620 100644 --- a/UnitFrames_Workbench/NOTICE.txt +++ b/UnitFrames_Workbench/NOTICE.txt @@ -2,7 +2,8 @@ Required Notice: Copyright (c) 2026 Martin Konstantin Herrmann. Original UnitFrames code and documentation are licensed under the PolyForm Noncommercial License 1.0.0; see LICENSE. This covers original work in -UnitFrames, UnitFrames_Workbench, UnitFrames_Media and UnitFrames_ClickGrid. +UnitFrames, UnitFrames_Workbench, UnitFrames_Media, UnitFrames_ClickGrid and +UnitFrames_Onboarding. Third-party libraries, fonts, reference projects and Blizzard materials are excluded and retain their own terms. diff --git a/UnitFrames_Workbench/Search.lua b/UnitFrames_Workbench/Search.lua index 2c38ce2..45aba86 100644 --- a/UnitFrames_Workbench/Search.lua +++ b/UnitFrames_Workbench/Search.lua @@ -88,6 +88,10 @@ function Workbench:BuildSearch(content) self:LayoutWorkbench() end }) self.previewToggle:SetPoint("TOPRIGHT", 0, -18) + self.gettingStarted = W.Button:New(content, { text = "Getting started", width = 120, height = 26, + tooltip = "Pick a preset look, try the most important options and find your way around. Your current style stays in its profile.", + onClick = function() UF:OpenOnboarding() end }) + self.gettingStarted:SetPoint("TOPRIGHT", self.previewToggle:GetFrame(), "TOPLEFT", -8, 0) self.profileLabel = Skin.FontString(content) self.profileLabel:SetPoint("TOPLEFT", 0, -50) self.profileLabel:SetJustifyH("LEFT") diff --git a/UnitFrames_Workbench/Workbench.lua b/UnitFrames_Workbench/Workbench.lua index 7ef3753..ff39f9d 100644 --- a/UnitFrames_Workbench/Workbench.lua +++ b/UnitFrames_Workbench/Workbench.lua @@ -181,8 +181,9 @@ function Workbench:Toggle() self.window:Toggle() end --- Shows the Workbench at a given entry. -function Workbench:Open(id) +-- Shows the Workbench at a given entry, optionally at the settings page +-- holding `path` (a schema path or its prefix, e.g. "auras"). +function Workbench:Open(id, path) if not self.window then self:Build() end @@ -190,6 +191,7 @@ function Workbench:Open(id) if self.entries[id] then self.list:Select(id) self:Select(id) + if path and self.pageModel then self:SelectFeaturePage(path) end end end diff --git a/scripts/api-snapshot.lua b/scripts/api-snapshot.lua index 94724fd..d6963ca 100644 --- a/scripts/api-snapshot.lua +++ b/scripts/api-snapshot.lua @@ -34,7 +34,7 @@ local version = Read(sourceDir .. "/version.txt"):match("^%s*(.-)%s*$") -- Every identifier our code, embedded libraries, mocks and specs mention, -- and those the mock itself defines. local words, mockWords = {}, {} -for _, path in ipairs(Lines("find UnitFrames UnitFrames_Workbench UnitFrames_ClickGrid UnitFrames_Media tests" +for _, path in ipairs(Lines("find UnitFrames UnitFrames_Workbench UnitFrames_ClickGrid UnitFrames_Onboarding UnitFrames_Media tests" .. " -name '*.lua' -not -name 'api_snapshot.lua'")) do local mock = path:match("^tests/mock/") ~= nil for word in Read(path):gmatch("[%a_][%w_]*") do diff --git a/scripts/build-dev.sh b/scripts/build-dev.sh index b2ce3a4..e45ee86 100644 --- a/scripts/build-dev.sh +++ b/scripts/build-dev.sh @@ -13,7 +13,7 @@ else mkdir -p "$repo_dir/.build" output_dir="$(mktemp -d "$repo_dir/.build/$build_version.XXXXXX")" fi -addons=(UnitFrames UnitFrames_Workbench UnitFrames_Media UnitFrames_ClickGrid) +addons=(UnitFrames UnitFrames_Workbench UnitFrames_Media UnitFrames_ClickGrid UnitFrames_Onboarding) for addon in "${addons[@]}"; do cp -a "$repo_dir/$addon" "$output_dir/" done diff --git a/scripts/release.sh b/scripts/release.sh index 05aa178..c484d78 100755 --- a/scripts/release.sh +++ b/scripts/release.sh @@ -30,7 +30,7 @@ done release_tmp="$(mktemp -d)" trap 'rm -rf -- "$release_tmp"' EXIT -addons=(UnitFrames UnitFrames_Workbench UnitFrames_Media UnitFrames_ClickGrid) +addons=(UnitFrames UnitFrames_Workbench UnitFrames_Media UnitFrames_ClickGrid UnitFrames_Onboarding) # Only committed addon files from this tag are shipped; no working-tree extras. git archive "refs/tags/$tag" LICENSE "${addons[@]}" | tar -x -C "$release_tmp" for addon in UnitFrames UnitFrames_Media; do diff --git a/scripts/validate-release.lua b/scripts/validate-release.lua index 716b770..b5471e5 100644 --- a/scripts/validate-release.lua +++ b/scripts/validate-release.lua @@ -1,7 +1,7 @@ -- Validate the staged installable bundle without loading client APIs. local root, version = assert(arg[1], "bundle directory required"), assert(arg[2], "version required") local channel, commit = arg[3] or "release", arg[4] -local addons = { "UnitFrames", "UnitFrames_Workbench", "UnitFrames_Media", "UnitFrames_ClickGrid" } +local addons = { "UnitFrames", "UnitFrames_Workbench", "UnitFrames_Media", "UnitFrames_ClickGrid", "UnitFrames_Onboarding" } local checked = {} local function Read(path) diff --git a/tests/fixtures/api_snapshot.lua b/tests/fixtures/api_snapshot.lua index b112d84..3ec51c3 100644 --- a/tests/fixtures/api_snapshot.lua +++ b/tests/fixtures/api_snapshot.lua @@ -204,6 +204,7 @@ return { ["math.wrap"] = { args = { "value:number", "minimum:number", "maximum:number" }, returns = { "wrapped:number" }, secretArguments = "AllowedWhenUntainted", system = "LuaMathExtensions" }, scrubsecretvalues = { args = { "values:LuaValueReference" }, returns = { "scrubbed:LuaValueReference" }, secretArguments = "AllowedWhenUntainted", system = "FrameScript" }, ["string.contains"] = { args = { "str:stringView", "substring:stringView" }, returns = { "contains:bool" }, secretArguments = "AllowedWhenUntainted", system = "LuaStringExtensions" }, + ["string.trim"] = { args = { "str:stringView", "characters:stringView?" }, returns = { "trimmed:stringView" }, secretArguments = "AllowedWhenUntainted", system = "LuaStringExtensions" }, ["table.contains"] = { args = { "table:table", "value:any?" }, returns = { "containsValue:bool" }, secretArguments = "AllowedWhenUntainted", system = "LuaTableExtensions" }, ["table.count"] = { args = { "table:table" }, returns = { "count:number" }, secretArguments = "AllowedWhenUntainted", secretWhen = { "LuaTableHasSecretKeys" }, system = "LuaTableExtensions" }, ["table.create"] = { args = { "arraySizeHint:number", "nodeSizeHint:number?" }, returns = { "table:table" }, secretArguments = "AllowedWhenUntainted", system = "LuaTableExtensions" }, @@ -1708,6 +1709,7 @@ return { Bind = "InputActionBinding", Build = "builder", CallMethod = "HANDLE", + CanEnterEditMode = "EditModeManagerFrameMixin", Cancel = "AuctionHouseBuyDialogMixin", Check = "WatchData", CheckName = "CharacterCreateNameAvailabilityStateMixin", @@ -1874,6 +1876,7 @@ return { Move = "RectangleMixin", Name = "Class_TutorialBase", New = "MapBridgeDataProviderMixin", + Next = "CharacterServicesAutoCompleteButtonMixin", OnApply = "DecorPetCustomizationMixin", OnAttributeChanged = "ActionBarActionButtonMixin", OnCheckButtonClick = "CharacterCreateStartingZoneButtonMixin", @@ -1916,6 +1919,7 @@ return { PLAYER_TARGET_CHANGED = "Class_TabTargetingWatcher", PLAYER_UNGHOST = "Class_Death_MapPrompt", Pause = "MarchingAntsMixin", + Pick = "DropdownButtonMixin", Play = "AdventuresFriendlyTargetingIndicatorMixin", ProcessAura = "PrivateAuraAnchorContainerMixin", Pulse = "VehicleSeatIndicatorButtonMixin", @@ -2074,6 +2078,7 @@ return { ShowNewLayoutDialog = "EditModeLayoutDialogMixin", ShowSelected = "EditModeSystemSelectionBaseMixin", ShowTooltip = "AssistedCombatRotationSpellFrameMixin", + ShowUIPanel = "CooldownViewerSettingsMixin", Size = "t", Start = "AnimatedShineMixin", Status = "Class_TutorialBase", diff --git a/tests/helpers.lua b/tests/helpers.lua index 4ca925d..831e319 100644 --- a/tests/helpers.lua +++ b/tests/helpers.lua @@ -130,6 +130,17 @@ function Helpers.LoadWorkbench(build) return ns, ns.Workbench end +-- Core (initialized, frames spawned) + Getting started, loaded the way +-- UF:OpenOnboarding loads it. saved: the UnitFramesDB found at load. +-- Returns core ns, the guide and its private namespace. +function Helpers.LoadOnboarding(saved) + local ns = Helpers.LoadAddon(true, true, saved) + Mock.InstallUI() + local ob = Helpers.LoadToc("UnitFrames_Onboarding/UnitFrames_Onboarding.toc", "UnitFrames_Onboarding") + C_AddOns.LoadAddOn = function(name) return name == "UnitFrames_Onboarding" end + return ns, ns.Onboarding, ob +end + -- saved: the ClickGrid profile found at load ({ settings, member, target, pet }). function Helpers.LoadClickGrid(workbench, saved) local db = saved and { namespaces = { ClickGrid = { profiles = { Default = saved } } } } diff --git a/tests/mock/wow.lua b/tests/mock/wow.lua index 61eb08e..b0a7362 100644 --- a/tests/mock/wow.lua +++ b/tests/mock/wow.lua @@ -1038,6 +1038,13 @@ function Mock.NewEncodingUtil() } end +-- Runs the pending C_Timer.After callbacks, in the order they were scheduled. +function Mock.RunTimers() + local timers = Mock.timers + Mock.timers = {} + for _, timer in ipairs(timers) do timer.callback() end +end + function Mock.Install() -- Client chat belongs to the mock, not the test runner's stdout. Mock.messages = {} @@ -1056,6 +1063,12 @@ function Mock.Install() Mock.ranges = {} Mock.spellRanges = {} Mock.registeredEvents = {} + -- C_Timer.After callbacks wait until a spec runs them (Mock.RunTimers). + Mock.timers = {} + _G.C_Timer = { After = function(seconds, callback) + assert(type(seconds) == "number" and type(callback) == "function", "C_Timer.After(seconds, callback)") + Mock.timers[#Mock.timers + 1] = { seconds = seconds, callback = callback } + end } _G.UnitAttackSpeed = function() return Secret(2.6), Secret(1.8), Secret(2.8) end -- No cast in progress; InstallUI casts a sample spell. _G.UnitCastingInfo = function() return nil end diff --git a/tests/run.lua b/tests/run.lua index af54630..a1a4065 100644 --- a/tests/run.lua +++ b/tests/run.lua @@ -360,7 +360,7 @@ end -- Syntax check of all addon code (catches typos in files the specs don't load). local syntaxErrors = 0 -local addonFiles = ListFiles("find UnitFrames UnitFrames_Workbench UnitFrames_ClickGrid -name '*.lua' -not -path '*/Libs/*'") +local addonFiles = ListFiles("find UnitFrames UnitFrames_Workbench UnitFrames_ClickGrid UnitFrames_Onboarding -name '*.lua' -not -path '*/Libs/*'") for _, file in ipairs(addonFiles) do local _, err = loadfile(file) if err then diff --git a/tests/spec/core/commands_spec.lua b/tests/spec/core/commands_spec.lua index 4dfe2cb..a2f0331 100644 --- a/tests/spec/core/commands_spec.lua +++ b/tests/spec/core/commands_spec.lua @@ -38,6 +38,7 @@ describe("Slash command help", function() { "version", ns.version }, { "/uf help - show this list of commands" }, { "/uf wb - open settings and previews" }, + { "/uf welcome - walk through presets and the first setup again" }, { "/uf minimap - show or hide the minimap icon" }, { "/uf logs [clear] - show or clear saved diagnostic entries" }, { "/uf dots [reset] - toggle DoT tracking with its trace in chat, or forget learned tick sizes" }, diff --git a/tests/spec/onboarding/onboarding_spec.lua b/tests/spec/onboarding/onboarding_spec.lua new file mode 100644 index 0000000..f5c363e --- /dev/null +++ b/tests/spec/onboarding/onboarding_spec.lua @@ -0,0 +1,280 @@ +local Helpers = require("helpers") +local Mock = Helpers.Mock + +local function Messages() + local lines = {} + for _, message in ipairs(Mock.messages) do lines[#lines + 1] = table.concat(message, " ") end + return table.concat(lines, "\n") +end + +describe("Getting started presets #onboarding", function() + it("composes every preset, tweak, size and extra into a style that imports without dropping anything", function() + local ns, _, ob = Helpers.LoadOnboarding() + local pending = ob.Pending + local function Check(label) + local apply, dropped = ns.Profiles:Prepare("style", pending:Style()) + assert.is_not_nil(apply, label) + assert.same({}, dropped, label) + end + for _, preset in ipairs(ob.Presets.list) do + pending:Reset() + pending:SelectPreset(preset.id) + Check(preset.id) + for _, tweak in ipairs(ob.Presets.tweaks) do + for _, choice in ipairs(ob.Presets.Choices(tweak)) do + pending:SetTweak(tweak.key, choice[1]) + Check(preset.id .. " " .. tweak.key .. "=" .. tostring(choice[1])) + assert.equals(choice[1], pending:GetTweak(tweak.key)) + end + end + for _, extra in ipairs(ob.Presets.extras) do + for _, enabled in ipairs({ true, false }) do + pending:SetExtra(extra.key, enabled) + Check(preset.id .. " " .. extra.key) + assert.equals(enabled, pending:GetExtra(extra.key)) + end + end + end + end) + + it("scales widths and bar heights from the look's own sizes", function() + local ns, _, ob = Helpers.LoadOnboarding() + local pending = ob.Pending + pending:Reset() + pending:SelectPreset("healer") + local normal = pending:Resolved().units.player + pending:SetTweak("size", "large") + local large = pending:Resolved().units.player + assert.equals(math.floor(normal.width * 1.2 + 0.5), large.width) + assert.equals(math.floor(normal.health.height * 1.2 + 0.5), large.health.height) + end) +end) + +describe("Getting started applying #onboarding", function() + it("saves the look as a new profile, switched to, keeping frame positions", function() + local ns, _, ob = Helpers.LoadOnboarding() + local pending = ob.Pending + local before = ns.Profiles:GetCurrent() + ns.Config:SetPositions({ Default = { player = { "CENTER", 10, 20 } } }) + local positions = ns.Config:GetPositions() + pending:Reset() + pending:SelectPreset("minimal") + pending:SetExtra("targetCast", true) + local ok, profile = pending:Apply() + assert.is_true(ok) + assert.equals("Minimal look", profile) + assert.equals("Minimal look", ns.Profiles:GetCurrent()) + assert.same(positions.Default, ns.Config:GetPositions().Default) + assert.equals("UnitFrames Pixel", ns.Config:GetTheme().borderTexture) + assert.is_false(ns.Config:UnitStore("player"):Resolved().portrait.enabled) + assert.is_true(ns.Config:UnitStore("target"):Resolved().castbar.enabled) + assert.is_true(ns.FirstRun:IsDone()) + ns.Profiles:Switch(before) + assert.equals("Blizzard Tooltip", ns.Config:GetTheme().borderTexture) + end) + + it("numbers a second profile of the same look", function() + local ns, _, ob = Helpers.LoadOnboarding() + local pending = ob.Pending + pending:Reset() + pending:SelectPreset("classic") + pending:Apply() + pending:Reset() + pending:SelectPreset("classic") + local _, profile = pending:Apply() + assert.equals("Classic look 2", profile) + end) + + it("replaces the active profile's style when no new profile is wanted", function() + local ns, _, ob = Helpers.LoadOnboarding() + local pending = ob.Pending + local current, count = ns.Profiles:GetCurrent(), #ns.Profiles:List() + pending:Reset() + pending:SelectPreset("classic") + pending:SetNewProfile(false) + local ok, profile = pending:Apply() + assert.is_true(ok) + assert.equals(current, profile) + assert.equals(count, #ns.Profiles:List()) + assert.equals("Friz Quadrata TT", ns.Config:GetTheme().font) + end) + + it("writes nothing when the style does not validate", function() + local ns, _, ob = Helpers.LoadOnboarding() + local pending = ob.Pending + local count, exported = #ns.Profiles:List(), ns.Profiles:Export("style") + pending:Reset() + pending.style = "damaged" + local ok, reason = pending:Apply() + assert.is_false(ok) + assert.is_not_nil(reason) + assert.equals(count, #ns.Profiles:List()) + assert.equals(exported, ns.Profiles:Export("style")) + assert.is_false(ns.FirstRun:IsDone()) + end) +end) + +describe("Getting started previews #onboarding", function() + it("never changes the saved style or the live theme while browsing looks", function() + local ns, onboarding, ob = Helpers.LoadOnboarding() + local pending = ob.Pending + local theme, revision, exported = ns.Config:GetTheme(), ns.Config.themeRevision, ns.Profiles:Export("style") + onboarding:Open() + for _, id in ipairs({ "minimal", "classic", "healer" }) do pending:SelectPreset(id) end + onboarding:Next() + pending:SetTweak("border", "gold") + pending:SetTweak("portrait", "class") + onboarding:OnUpdate(0.5) + onboarding:Next() + pending:SetExtra("swing", true) + assert.equals(theme, ns.Config:GetTheme()) + assert.equals(revision, ns.Config.themeRevision) + assert.equals(exported, ns.Profiles:Export("style")) + end) + + it("renders a preview with its own theme, and restores the live one even after an error", function() + local ns = Helpers.LoadOnboarding() + local preview = { borderTexture = "Blizzard Dialog Gold" } + local seen + ns.Config:WithTheme(preview, function() seen = ns.Config:GetTheme() end) + assert.equals(preview, seen) + assert.has_error(function() ns.Config:WithTheme(preview, function() error("boom") end) end) + assert.equals("Blizzard Tooltip", ns.Config:GetTheme().borderTexture) + assert.is_nil(ns.Config.previewTheme) + end) + + it("releases every preview frame when the guide closes", function() + local _, onboarding, ob = Helpers.LoadOnboarding() + local steps = ob.Steps + onboarding:Open() + assert.equals(2, #steps.Look.preview.frames) + onboarding:Next() + assert.equals(0, #steps.Look.preview.frames) + assert.equals(2, #steps.Tweaks.preview.frames) + onboarding:Close() + assert.equals(0, #steps.Tweaks.preview.frames) + for _, preview in pairs(steps.Look.cardPreviews) do assert.equals(0, #preview.frames) end + end) +end) + +describe("Getting started flow #onboarding", function() + it("walks four steps, applies on the third and only closes from the last", function() + local ns, onboarding = Helpers.LoadOnboarding() + onboarding:Open() + local shell = onboarding.shell + assert.equals(1, onboarding.index) + assert.is_false(shell.back:IsShown()) + onboarding:Next() + onboarding:Next() + assert.equals(3, onboarding.index) + assert.equals("Apply and finish", shell.next.text:GetText()) + onboarding:Next() + assert.equals(4, onboarding.index) + assert.equals("Default look", ns.Profiles:GetCurrent()) + assert.is_false(shell.back:IsShown()) + onboarding:Jump(1) + assert.equals(4, onboarding.index) + onboarding:Next() + assert.is_false(onboarding:IsShown()) + end) + + it("counts Escape, Skip and the close button as done", function() + local ns, onboarding = Helpers.LoadOnboarding() + local count = #ns.Profiles:List() + onboarding:Open() + onboarding.shell.frame:Hide() + assert.is_true(ns.FirstRun:IsDone()) + assert.equals(count, #ns.Profiles:List()) + end) + + it("hides in combat with the choices kept and comes back afterwards", function() + local ns, onboarding, ob = Helpers.LoadOnboarding() + local pending = ob.Pending + onboarding:Open() + onboarding:Next() + pending:SetTweak("font", "Morpheus") + Mock.inCombat = true + Mock.FireEvent("PLAYER_REGEN_DISABLED") + assert.is_false(onboarding:IsShown()) + assert.is_false(ns.FirstRun:IsDone()) + Mock.inCombat = false + Mock.FireEvent("PLAYER_REGEN_ENABLED") + assert.is_true(onboarding:IsShown()) + assert.equals(2, onboarding.index) + assert.equals("Morpheus", pending:GetTweak("font")) + end) +end) + +describe("Getting started first run #onboarding", function() + it("opens once after the first login of a fresh install", function() + local ns, onboarding = Helpers.LoadOnboarding() + Mock.FireEvent("PLAYER_ENTERING_WORLD", true, false) + assert.is_false(onboarding:IsShown()) + Mock.RunTimers() + assert.is_true(onboarding:IsShown()) + onboarding:Close() + Mock.FireEvent("PLAYER_ENTERING_WORLD", true, false) + Mock.RunTimers() + assert.is_false(onboarding:IsShown()) + assert.is_true(ns.FirstRun:IsDone()) + end) + + it("waits for combat to end before opening", function() + local _, onboarding = Helpers.LoadOnboarding() + Mock.FireEvent("PLAYER_ENTERING_WORLD", true, false) + Mock.inCombat = true + Mock.RunTimers() + assert.is_false(onboarding:IsShown()) + Mock.inCombat = false + Mock.FireEvent("PLAYER_REGEN_ENABLED") + assert.is_true(onboarding:IsShown()) + end) + + it("leaves existing installs alone with a one-line hint", function() + local ns, onboarding = Helpers.LoadOnboarding({}) + Mock.FireEvent("PLAYER_ENTERING_WORLD", true, false) + Mock.RunTimers() + assert.is_false(onboarding:IsShown()) + assert.is_true(ns.FirstRun:IsDone()) + assert.is_not_nil(Messages():find("/uf welcome", 1, true)) + end) + + it("stays silent at login and hints on request when the addon is turned off", function() + local ns = Helpers.LoadAddon(true, true) + C_AddOns.LoadAddOn = function() return false, "DISABLED" end + assert.is_false(ns:OpenOnboarding(true)) + assert.is_nil(Messages():find("turned off", 1, true)) + assert.is_false(ns:OpenOnboarding()) + assert.is_not_nil(Messages():find("turned off", 1, true)) + end) +end) + +describe("Getting started hand-off #onboarding", function() + it("opens Edit Mode from the last step only when the client allows it", function() + local _, onboarding, ob = Helpers.LoadOnboarding() + local shown = {} + _G.ShowUIPanel = function(frame) shown[#shown + 1] = frame end + _G.EditModeManagerFrame = { CanEnterEditMode = function() return true end } + onboarding:Open() + for _ = 1, 3 do onboarding:Next() end + local button = ob.Steps.Ready.editMode + assert.is_true(button:IsShown()) + button:GetFrame():RunScript("OnClick") + assert.is_false(onboarding:IsShown()) + assert.same({ EditModeManagerFrame }, shown) + _G.ShowUIPanel, _G.EditModeManagerFrame = nil, nil + end) + + it("opens the Workbench at the settings page holding a path", function() + local ns, wb = Helpers.LoadWorkbench() + C_AddOns.LoadAddOn = function() return true end + ns:OpenWorkbench("unit.player", "auras") + local expected + for _, record in ipairs(wb.pageModel.records) do + if record.path == "auras.enabled" then expected = record.pageId end + end + assert.is_not_nil(expected) + assert.equals("unit.player", wb.entry.id) + assert.equals(expected, wb.state.section) + end) +end) diff --git a/todos/09-design-onboarding.md b/todos/09-design-onboarding.md index 1f1034d..e2fb953 100644 --- a/todos/09-design-onboarding.md +++ b/todos/09-design-onboarding.md @@ -1,6 +1,6 @@ # Design: Getting started (UnitFrames_Onboarding) -Status: draft; no implementation. Targets Forever Interface 16001 and Lua 5.1. +Status: implemented (offline tests only; in-game verification pending). Targets Forever Interface 16001 and Lua 5.1. Mockups: `todos/09-onboarding/01-pick-a-look.svg` … `04-ready.svg` (generated, not pixel-exact). ## Goal @@ -239,3 +239,25 @@ in the AddOns list stays silent. licence-clean and already shipped (AGENTS.md: no new third-party art). - Should existing users ever get the wizard auto-opened (for example once, after a major version)? - Do we want a fifth preset that's community-sourced (an import string shipped as data)? + +## Implementation notes (deviations from this draft) + +- **Step 3 is "Add the extras", not frame toggles.** Unit frames have no + on/off setting (oUF always spawns them), and ClickGrid's switch is the addon + itself. The screen map keeps Player/Target/Focus as fixed blocks and toggles + the extras that exist: player/target/focus castbars, experience, combo + points, timer bars, global cooldown and swing timer. Per-frame disabling would + be a core feature of its own. +- **No Blizzard Settings panel yet.** Entry points are the first-run trigger, + `/uf welcome`, the minimap menu and a Workbench button. A Settings category + (`Settings.RegisterCanvasLayoutCategory`/`RegisterAddOnCategory`, verified in + the pinned source) is a small follow-up. +- **Preview isolation** is `Config:WithTheme(theme, fn, ...)`, not a + per-component theme source: child components resolve through + `Config:GetTheme()` outside shared scopes, so the override covers them all. + Each scope gets a unique negative `themeRevision`, so colour-curve caches never + serve a preview's curve to live frames. +- Pages fade and slide through an OnUpdate tween; only the backdrop uses an + Alpha AnimationGroup (the mock models no Translation animations). +- The Edit Mode button follows Blizzard's game menu: + `EditModeManagerFrame:CanEnterEditMode()` then `ShowUIPanel(EditModeManagerFrame)`. From 84e2bfd51efd93d95c910c95adeaf77878cb2d7d Mon Sep 17 00:00:00 2001 From: Martin Konstantin Herrmann Date: Mon, 9 Nov 2026 01:27:20 +0100 Subject: [PATCH 3/4] Include onboarding addon in release check The release smoke test copied and counted a hard-coded set of four addons, so packaging UnitFrames_Onboarding failed in CI. --- tests/scripts/release.sh | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/scripts/release.sh b/tests/scripts/release.sh index b52e3d4..1ff488d 100644 --- a/tests/scripts/release.sh +++ b/tests/scripts/release.sh @@ -6,7 +6,7 @@ release_test_tmp="$(mktemp -d)" trap 'rm -rf -- "$release_test_tmp"' EXIT fixture="$release_test_tmp/repo" mkdir -p "$fixture/scripts" -for addon in UnitFrames UnitFrames_Workbench UnitFrames_Media UnitFrames_ClickGrid; do +for addon in UnitFrames UnitFrames_Workbench UnitFrames_Media UnitFrames_ClickGrid UnitFrames_Onboarding; do cp -a "$repo_dir/$addon" "$fixture/" done cp "$repo_dir/LICENSE" "$repo_dir/.gitignore" "$fixture/" @@ -21,7 +21,7 @@ git init -q git config user.name 'Release test' git config user.email 'release-test@example.invalid' # Libraries are separate build inputs, as in the real repo. -git add .gitignore LICENSE scripts tests UnitFrames UnitFrames_Workbench UnitFrames_Media UnitFrames_ClickGrid +git add .gitignore LICENSE scripts tests UnitFrames UnitFrames_Workbench UnitFrames_Media UnitFrames_ClickGrid UnitFrames_Onboarding git reset -q -- UnitFrames/Libs UnitFrames_Media/Libs git -c core.hooksPath=/dev/null commit -qm 'Release fixture' git tag v0.0.0-beta.1 @@ -56,7 +56,7 @@ archive="$release_test_tmp/output/UnitFrames-v0.0.0-beta.1.zip" unzip -tq "$archive" >/dev/null mkdir -p "$release_test_tmp/unpacked" unzip -q "$archive" -d "$release_test_tmp/unpacked" -[[ "$(find "$release_test_tmp/unpacked" -mindepth 1 -maxdepth 1 -type d | wc -l)" -eq 4 ]] +[[ "$(find "$release_test_tmp/unpacked" -mindepth 1 -maxdepth 1 -type d | wc -l)" -eq 5 ]] [[ ! -e "$release_test_tmp/unpacked/UnitFrames/untracked.sh" ]] cmp "$release_test_tmp/unpacked/UnitFrames/Core/Init.lua" <(git show v0.0.0-beta.1:UnitFrames/Core/Init.lua) cp LICENSE "$release_test_tmp/unpacked/" From e6052f5e560ff7757917fd39d0b7b730a08fb2f1 Mon Sep 17 00:00:00 2001 From: Martin Konstantin Herrmann Date: Mon, 9 Nov 2026 07:12:21 +0100 Subject: [PATCH 4/4] Install over SSH with --host scripts/install.sh --host runs the checks, removal and rsync copy on another machine, so a client elsewhere (arch) can be updated from the dev box. --link stays local. --- AGENTS.md | 2 +- DEVELOPMENT.md | 6 ++++ scripts/install.sh | 84 ++++++++++++++++++++++++++++++++++------------ 3 files changed, 69 insertions(+), 23 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b5cd18a..f555284 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,7 +100,7 @@ luajit tests/run.lua workbench -t "preview" ## Local installation - Default client AddOns directory: `/mnt/data02/Games/Faugus/battlenet/drive_c/Program Files (x86)/World of Warcraft/_forever_/Interface/AddOns/`. `scripts/install.sh` supports `WOW_DIR` overrides; validate the actual target before deploying. -- For authorized deployments, use `scripts/install.sh` by default, passing the changed addon names when appropriate (for example, `scripts/install.sh UnitFrames_Workbench`). Do not substitute manual `rsync` deployments unless specifically requested. +- For authorized deployments, use `scripts/install.sh` by default, passing the changed addon names when appropriate (for example, `scripts/install.sh UnitFrames_Workbench`). When the client runs on another machine than the checkout, add `--host ` (for example `--host arch`). Do not substitute manual `rsync` deployments unless specifically requested. - The install script replaces the targeted addon directories before copying/linking; this replacement is expected and authorized as part of a requested installation. SavedVariables under `WTF/` are retained. `--uninstall` is a separate removal operation and requires an explicit uninstall request. - Request the required filesystem approval when installing outside the workspace. Never edit SavedVariables or unrelated installed addons as part of routine deployment. - `/reload` normally picks up changed Lua. Restart the client for new TOC-listed files or new media/font assets. State clearly whether changes were installed or only edited/tested in the repository. diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index ff952f5..3303850 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -386,6 +386,12 @@ supports `WOW_DIR`, named addon arguments, `--link` and `--uninstall`. `--uninstall` removes it too.** SavedVariables under `WTF/` remain intact, but other files in those addon folders are replaced. +`--host ` does the same on another machine, for a client +that runs elsewhere than the checkout: `scripts/install.sh --host arch +UnitFrames_Onboarding`. It needs key-based SSH login and rsync on both ends; +`WOW_DIR` then names the path on that machine (same default). `--link` is +local only. + Use `/reload` for changed Lua in existing files. Restart the client for new TOC-listed files or new media/font assets. Keep repository edits and game installation distinct when reporting changes. diff --git a/scripts/install.sh b/scripts/install.sh index 76cb23c..d05cf41 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -8,8 +8,12 @@ # scripts/install.sh [addon...] # remove old copies, copy fresh ones into AddOns/ # scripts/install.sh --link [addon...] # remove old copies, symlink AddOns/ -> repo folder # scripts/install.sh --uninstall [addon...] # remove from AddOns/ (SavedVariables in WTF/ are kept) +# scripts/install.sh --host arch [addon...] # the same on another machine over SSH (copy or --uninstall) # -# Without addon names, all addons in the repo are handled. +# Without addon names, all addons in the repo are handled. --host takes an +# SSH destination (a host alias from your SSH config, or user@host) with +# key-based login; WOW_DIR is then a path on that machine. --link needs the +# repo on the client machine, so it only works locally. # # Environment overrides: # WOW_DIR WoW client dir (default: Forever under Faugus/battlenet) @@ -22,6 +26,21 @@ ADDONS_DIR="$WOW_DIR/Interface/AddOns" die() { echo "error: $*" >&2; exit 1; } +HOST="" + +# Runs a command here, or on $HOST over SSH with its arguments quoted. +on_target() { + if [[ -n "$HOST" ]]; then + ssh -o BatchMode=yes "$HOST" "$(printf '%q ' "$@")" + else + "$@" + fi +} + +where() { + if [[ -n "$HOST" ]]; then echo "$HOST:$1"; else echo "$1"; fi +} + repo_addons() { local dir name for dir in "$REPO_DIR"/*/; do @@ -30,29 +49,45 @@ repo_addons() { done } +# Exit status: 0 removed, 1 nothing there, 2 something else is in the way. +REMOVE_SCRIPT=' +if [[ -L "$1" ]]; then rm -- "$1" +elif [[ -d "$1" ]]; then rm -rf -- "$1" +elif [[ -e "$1" ]]; then exit 2 +else exit 1 +fi' + remove_existing() { - local target="$1" - if [[ -L "$target" ]]; then - rm "$target" - elif [[ -d "$target" ]]; then - rm -rf -- "$target" - elif [[ -e "$target" ]]; then - die "$target exists but is not a directory or symlink, refusing to touch it" - else - return 1 - fi + local target="$1" result=0 + on_target bash -c "$REMOVE_SCRIPT" remove "$target" || result=$? + case "$result" in + 0) return 0 ;; + 1) return 1 ;; + 2) die "$(where "$target") exists but is not a directory or symlink, refusing to touch it" ;; + *) die "could not check $(where "$target") (exit $result)" ;; + esac } mode="copy" -case "${1:-}" in - --link) mode="link"; shift ;; - --uninstall) mode="uninstall"; shift ;; - -h|--help) sed -n '2,16p' "$0"; exit 0 ;; - -*) die "unknown option: $1 (see --help)" ;; -esac +while [[ $# -gt 0 ]]; do + case "$1" in + --link) mode="link"; shift ;; + --uninstall) mode="uninstall"; shift ;; + --host) + [[ -n "${2:-}" && "$2" != -* ]] || die "--host needs an SSH destination, e.g. --host arch" + HOST="$2"; shift 2 ;; + -h|--help) sed -n '2,22p' "$0"; exit 0 ;; + -*) die "unknown option: $1 (see --help)" ;; + *) break ;; + esac +done -[[ -d "$WOW_DIR" ]] || die "WoW dir not found: $WOW_DIR" -mkdir -p "$ADDONS_DIR" +[[ -z "$HOST" || "$mode" != "link" ]] || die "--link only works locally; use plain copies with --host" +if [[ -n "$HOST" ]]; then + on_target true || die "cannot reach $HOST over SSH (key-based login is required)" +fi +on_target test -d "$WOW_DIR" || die "WoW dir not found: $(where "$WOW_DIR")" +on_target mkdir -p "$ADDONS_DIR" mapfile -t available < <(repo_addons) [[ ${#available[@]} -gt 0 ]] || die "no addon folders (/.toc) in $REPO_DIR" @@ -69,7 +104,7 @@ for name in "${addons[@]}"; do target="$ADDONS_DIR/$name" if remove_existing "$target"; then - echo "removed $target" + echo "removed $(where "$target")" fi case "$mode" in uninstall) @@ -80,8 +115,13 @@ for name in "${addons[@]}"; do echo "linked $target -> $source_dir" ;; copy) - rsync -a "$source_dir/" "$target/" - echo "copied $name" + if [[ -n "$HOST" ]]; then + # -s keeps the spaces and parentheses in the client path away from the remote shell. + rsync -a -s -e "ssh -o BatchMode=yes" "$source_dir/" "$HOST:$target/" + else + rsync -a "$source_dir/" "$target/" + fi + echo "copied $name -> $(where "$target")" ;; esac done