2026 10 14 compendium wizards design - xopherdeep/do-it-for-the-xp GitHub Wiki

Compendium wizards

Status: draft 1, 2026-10-14. Owner: "polish all the form pages in our Compendium; they should look more like polished wizards so it's easy for parents to walk through." Inventory by a read-only sweep the same day (section 4).

1. The pattern

The hero-side Quest Wizard (src/app/Console/MyPortal/UserHud/MyQuests/components/XpQuestWizardModal.vue, src/lib/services/quests/questWizard.ts) is the model. Every Compendium form becomes steps inside one shared shell:

  • XpWizardShell (new organism, src/components/organisms/WizardShell/): a header with the step name and "n / N", progress dots, one guide line per step in the family's voice with the speak button (XpSpeakButton), the step's content in a scrolling body, and a footer in thumb reach: Back (Close on the first step) and Next (the last step's button is the form's verb: Summon, Save, Open). Next is disabled until the step is valid; the shell shows the one line that says why ("Give it a name"). The accent follows the app the form belongs to (per-app accents, cream text; no Ionic alerts, reveal prompts only).
  • useWizardSteps (pure, src/lib/services/wizard/wizardSteps.ts): steps { id, title, guide, isValid(draft), isSkipped?(draft) }, the current index, next/back with skipped steps jumped over, progress, and ready (every step valid). One jest spec. Forms supply their steps and their draft; the shell never knows the fields.
  • Save once at the end, on the last step's verb, with the fanfare (XpHeroFanfare) where the thing created is something the hero will meet (a quest, a beast, a power). Forms that autosave today (the quest config) keep the autosave as the draft mechanism and the last step turns the draft Ready (the existing READY/DRAFT ribbon).
  • Edit = the same wizard, opened at the summary step, with the dots tappable to jump back; new = step 1.
  • One decision per step, named the way a parent would say it (section 3). Defaults are filled in silently and shown on the summary, where a tap jumps to the step that owns them.
  • Field components stay: the hero picker, the Fibonacci control, the schedule pickers, the icon and background pickers, the beast avatar grid are reused inside steps; nothing is redrawn for its own sake. The three separate difficulty controls collapse into the Quest Why tab's one.
  • The stacked bottom nav bars are never hidden, relabelled or reordered: the stepper lives inside the page.

2. Order of work

  1. W0 the shell: extract XpWizardShell + useWizardSteps from the Quest Wizard and make the Quest Wizard use them (no visible change there). Ships alone, first, so every later form is one shell.
  2. W1 Beast (3 steps), W2 Power (3), W3 Shop item (4), one builder each, in parallel, on the shell.
  3. W4 Quest config (5 steps; the GM's main form, the biggest; keeps autosave as draft) and W5 Shop (4).
  4. W6 Temple: only the attributes become steps ("Name and theme", "Check and open"); the Temple Creator and the room editor stay the tools they are (the room editor's footer rails already are the thumb-reach pattern). The Generate modal becomes 4 steps.

Bugs the inventory found are fixed inside the form's own wizard task unless listed in section 5 as separate.

3. Step splits (the owner checks these)

Form Steps (parent's words)
Quest (W4) What's the chore? (name, category, normal / beast / chain) → Who does it? → When? → How hard? (difficulty, rewards, approval, bonus) → Ready? (summary, Ready)
Beast (W1) Pick its look → Name it → Chores that beat it → (summary, Summon)
Power (W2) What is it? → What does it do? → What does it cost? → (summary, Save)
Shop item (W3) What is it? → What does it cost? → Who can buy it? → Gear stats (virtual only, skipped otherwise) → (summary, Stock it)
Shop (W5) Name the shop and clerk → Dress the shop → Open hours → Stock it → (summary, Open)
Temple attributes (W6) Name and theme → Check and open (audit summary, Save); Generate: seed → size and floors → theme → preview and save

4. What exists today (inventory, 2026-10-14)

  • Quest config achievements/config/:id: five free ion-tabs (How, Who, What, When, Why), XpWizardCoach is a toast per tab, autosave 2 s debounced to AchievementDb, READY/DRAFT ribbon, Save chip lists what is missing.
  • Beast bestiary/create-update/:id?: one page over a live canvas; avatar, name, ordered tasks, background; footer Cancel/Save (good).
  • Power abilities/create-update/:id?: one long list; type swaps the last section; footer Cancel/Save.
  • Shop item economy/create-update/:id?: three header segments; no validation; footer Cancel/Save.
  • Shop economy/create-shop/:id? + detail tabs Items / Hours / Decorate / Clerk, each with its own save.
  • Temple: Config > General card with an inline Save; the Creator's Save FAB; the room editor's footer rails.
  • Shared today: XpSpeakButton, XpHeroFanfare, the Quest Wizard's dots and guide line, XpHeroPicker, the Fibonacci control, schedule pickers, XpIconPicker (Powers), XpBackgroundSelector + AvatarSelect (Beast).

5. Bugs found by the inventory (separate board tasks, fixed first or inside the form's wizard task)

  1. Quest category modal: rows have no tap handler, a parent cannot pick an existing category; typing an existing name makes a duplicate.
  2. Beast setBeast replaces the record with defaults plus seven fields: editing likely drops achievementIds, element, theme, variantAvatar (verify).
  3. Power icon picker is opened with the string "XpIconPicker" and probably does nothing (verify).
  4. Shop item route lacks props: true: editing an existing item likely opens empty and saves a duplicate (verify); availableToMembers defaults to [""]; a blank name saves.
  5. Shop create: the world select offers mountain / desert / snow / volcano while the art ids are mountains / ice / swamps (those fall back to the world map); the "Info" tab links to /splash (route is dashboard).
  6. Temple Create opens templeId "new" and nothing swaps it for a real id: a second new temple would overwrite the first (verify); Import is an empty stub.
  7. Shop item Inventory and Purchase History blocks have no segment button (unreachable).
  8. Three separate difficulty controls (Quest Why tab, RoomQuestPicker, wizard SIZE_CHOICES).
⚠️ **GitHub.com Fallback** ⚠️