gacha-event-tracker/docs/superpowers/plans/2026-10-14-form-examples.md

# Examples to start from, and a pass over the add forms — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Give *Add an event* and *Add a task* a row of examples that shape the form, and make both
forms read as a reader thinks.

**Architecture:** Examples are pure data in `src/shared/templates.ts`. Each form applies one through a
pure function on its state, so the suite (static render, no clicks) can prove what a tap does. The
event form's derived state moves into one exported pure function, `eventFormState`, so validity, the
draft and the "still needed" line all come from one place. Shared field/pill classes, the example row
and the "still needed" sentence live in `src/client/components/formParts.tsx`.

**Tech Stack:** Bun, React 19 (static render in tests via `react-dom/server`), Tailwind, zod.

**Spec:** `docs/superpowers/specs/2026-10-14-form-examples-design.md`

## Global Constraints

- An example sets a shape, never a fact: never a title (placeholder only), date, time, target or game. Only exception: *Monthly shop buy-out* sets `required: "1"`.
- Nothing is saved until the reader saves; Save stays disabled until every date and figure the shape needs is typed.
- No date is guessed — no "today", no "the 1st".
- "I don't know when it ends" stays first-class; preset windows, measured cycles, delays, `comesRoundEarly`, the stranded notice and `until` survival behave exactly as before.
- No schema, store, id or export change.
- The examples row renders only on add (no `initial`), never on edit.
- Copy: How often → *Once · Every day · Every week · Every month · On its own cycle*; Repeat → *Doesn't repeat · Comes back as it ends · Comes back after a wait*; Kind → *Banner · Story · Rerun · Challenge / endgame · Login rewards · Shop · Maintenance · Other*; the name field is *Name* in both forms.
- Commits wait for the owner's go-ahead (AGENTS.md); work stays uncommitted until asked.

## Review Focus

1. A reader types a title and dates, then taps an example — the title and dates must survive (Task 1/2/3 tests on `withEventTemplate` / `withTaskTemplate`).
2. Switching from *Recurring endgame cycle* to *Banner with a known end* must leave no repeat on the draft (Task 3 test).
3. *A few days each week* leaves the day count empty: Save disabled and the line says "how many days" (Task 2 test).
4. Choosing *On its own cycle* from *Doesn't repeat* must land on *Comes back as it ends*; a stored custom-never record must still reopen as never (Task 3 test).
5. At 360px the example row and the pills wrap without horizontal scroll (Task 4 browser check).

---

### Task 1: The examples, as data

**Files:**
- Create: `src/shared/templates.ts`
- Test: `test/templates.test.ts`

**Interfaces:**
- Produces: `EventTemplate`, `TaskTemplate`, `EVENT_TEMPLATES`, `TASK_TEMPLATES` (shapes in the spec).

- [ ] **Step 1: Write the failing test** — ids unique per list; `sets` keys limited to the shape keys;
  no `sets` carries a title/date/target; only `monthly-shop` sets `required`, to `"1"` (and
  `few-days` to `""`); placeholders non-empty and none equals a real event name in the list (smoke).
- [ ] **Step 2:** `bun test test/templates.test.ts` → FAIL (module not found).
- [ ] **Step 3: Implement** `src/shared/templates.ts` with the two tables from the spec verbatim.
- [ ] **Step 4:** `bun test test/templates.test.ts` → PASS.

### Task 2: Task form — shared parts, examples, still-needed

**Files:**
- Create: `src/client/components/formParts.tsx` — `field`, `pill(on)`, `labelClass`, `stillNeededLine(needs: string[]): string | null`, `ExampleRow`.
- Modify: `src/client/components/TaskForm.tsx`
- Test: `test/custom-ui.test.tsx`, `test/templates.test.ts`

**Interfaces:**
- Consumes: `TASK_TEMPLATES`, `TaskTemplate`.
- Produces:
  - `stillNeededLine(["a name","a start date"]) === "Still needed: a name and a start date."`; three → `"a, b and c"`; `[]` → `null`.
  - `ExampleRow<T extends {id:string;label:string;hint:string}>({ examples: readonly T[]; chosen: string | null; onChoose: (t: T) => void })` — renders "Start from an example", one pill per example with `aria-pressed`, and the chosen one's hint.
  - `withTaskTemplate(f: TaskFields, t: TaskTemplate): TaskFields` — `{...f, unit, kind, required?, amountUnit?}` only.
  - `taskStillNeeded(f: TaskFields): string[]` — in order "a name", "a day of the month", "how many days", "the target".

- [ ] **Step 1: Failing tests:**
  - `stillNeededLine` cases above.
  - `withTaskTemplate` keeps `game`, `title`, `target`, `weekday`, `monthDay`; sets `unit`/`kind`; *A few days each week* empties `required`.
  - `taskStillNeeded`: blank title → "a name"; `kind:"days", required:""` → "how many days"; `unit:"week", required:"9"` → "how many days"; amount with `target:""` → "the target"; complete → `[]`.
  - Every task template, applied to `{title:"x", target:"100", required kept or "2"}` fields, gives `taskStillNeeded === []` and a non-null `taskDraftFrom`.
  - Render: add form contains "Start from an example" and each label; edit form (`initial`) does not; label "Name" present.
- [ ] **Step 2:** `bun test test/custom-ui.test.tsx test/templates.test.ts` → FAIL.
- [ ] **Step 3: Implement** — formParts.tsx; TaskForm imports `field`/`pill`, labels "Name", inputs `px-3 py-2`, `chosen` state, `ExampleRow` only when `initial === undefined`, title placeholder from the chosen template, Save `disabled={draft === null || needs.length > 0}`, the still-needed line beside the buttons in `text-faint`.
- [ ] **Step 4:** same command → PASS; `bun run typecheck` clean.

### Task 3: Event form — order, words, pills, messages, examples

**Files:**
- Modify: `src/client/components/CustomForms.tsx`
- Test: `test/custom-ui.test.tsx`, `test/templates.test.ts`

**Interfaces:**
- Consumes: `EVENT_TEMPLATES`, `ExampleRow`, `pill`, `stillNeededLine`.
- Produces:
  - `EventShape = { type: EventType; cadence: Cadence; repeatMode: RepeatMode; endKnown: boolean; ownCadence: boolean }`, held as one `useState`.
  - `withEventTemplate(shape: EventShape, t: EventTemplate): EventShape` → `{...shape, ...t.sets, ownCadence: false}`.
  - `withCadence(shape: EventShape, cadence: Cadence): EventShape` — choosing `custom` while `repeatMode === "never"` moves to `"forever"`.
  - `eventStillNeeded(s: { title; startDate; datedWindow; endKnown; endDate; delayNeedsEnd; needsCycle }): string[]` — "a name", "a start date", "an end date", "a cycle length".
  - `eventFormState(values: EventFormValues, existingUntil: string | null)` — returns `{ startsAt, endsAt, endMs, preset, datedWindow, measured, measuring, delayNeedsEnd, repeat, backwards, endMissing, earlyReturn, needs, valid, draft }`, the block that is inline today, moved verbatim, plus `needs`. `valid = needs.length === 0 && !backwards && !endMissing && !earlyReturn && !repeatIncomplete`.

- [ ] **Step 1: Failing tests:**
  - `withEventTemplate` keeps nothing it shouldn't touch (shape only) and clears `ownCadence`.
  - `withCadence(never-shape, "custom").repeatMode === "forever"`; a stored custom-never event reopens with *Doesn't repeat* pressed.
  - Endgame → Banner: `eventFormState` with the banner shape and dates has `repeat === null`.
  - Each event template, with title "x", start `2026-10-01`, end `2026-10-15`, is `valid` with a draft; a fresh banner with no dates lists "a name", "a start date", "an end date".
  - Copy: update existing assertions (`Cadence` → `How often`; answers list; `value="daily" selected=""` → `/aria-pressed="true"[^>]*>Every day</`; `with a delay` → `Comes back after a wait`).
  - Add form shows the example row; edit form does not.
- [ ] **Step 2:** `bun test test/custom-ui.test.tsx test/templates.test.ts` → FAIL.
- [ ] **Step 3: Implement** in the spec's order with messages beside their fields.
- [ ] **Step 4:** same → PASS; full `bun test` and `bun run typecheck` green.

### Task 4: Browser check and docs

- [ ] Build (`bun run build:css && bun run build:js && bun run build:static`), serve on a fresh port, puppeteer (scratchpad) at 360px and 1280px: open Settings → Your own → Add an event, tap each example, check no horizontal scroll, fill the banner and save, see the row; same for Add a task.
- [ ] PRD F13 and F17: a sentence each on examples and their bar. DESIGN.md chips: the example row. TODO.md: tick the item.
- [ ] Final `bun test`, `bun run typecheck`.
- [ ] Final whole-change review (fresh reviewer); then report. Changelog entry follows the feature commit when the owner asks to commit.