docs: archive the finished backlogs (RD-30)
Two backlog trees are complete: `docs/project/backlog/` (75 files, every WP done) and `docs/project/refactor-backlog-setup/` (the arc before it). Move both under `docs/project/archive/` with `git mv`, so history stays intact through `git log --follow`. `SHOWCASE-ROADMAP.md` moves with them, because it points at the now-archived backlog README. Add `docs/project/archive/README.md`. It states that these trees are historical and names the two directories that are still live. Repoint every inbound reference named in RD-30's Files table: CLAUDE.md, the root README, both backend READMEs, `LetterHtml.cs`, `a11y.mdx`, the `document-feature` and `new-ssp` skills, and the readable-codebase PLAN, README, and RD-19 ticket. Fix two upward-relative links inside the moved WP files (WP-68, WP-69) that gained a directory level and would otherwise break. Repoint `.prettierignore`'s two agent-prompt exclusions to their new path, so prettier keeps leaving those files' exact wording alone. Mark RD-30 done and check off its acceptance criteria; flip its README row to done. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,49 @@
|
||||
# WP-39 — Showcase: linked code snippets + teaching animations
|
||||
|
||||
Status: done
|
||||
Phase: 8 — platform/DX/showcase
|
||||
Priority: P1
|
||||
|
||||
## Outcome
|
||||
|
||||
`?raw` imports are NOT supported by Angular's esbuild build (verified), so anti-drift is done via
|
||||
a generator (mirrors `gen:api`): `// #region showcase:<name>` markers in real source
|
||||
(registration.ts, remote-data.ts, postcode.ts, change-request.machine.ts, intake.machine.ts) →
|
||||
`scripts/gen-snippets.mjs` (`npm run gen:snippets`) → committed `src/app/showcase/snippets.generated.ts`.
|
||||
A CI drift gate (`gen:snippets && git diff --exit-code`) forces a regen after any edit, so the shown
|
||||
code IS the shipped code. The showcase renders the 5 real snippets (union/fold/parse/machine/steps)
|
||||
each with a `↳ <source file>` caption, highlighted by a tiny dependency-free `highlightTs` (+spec);
|
||||
the deliberately-wrong illustrations stay authored (no real source to link). Teaching animation: the
|
||||
active state node pops (scale) as the wizard transitions, and the parse result animates in
|
||||
(`animate.enter`), reusing the existing reduced-motion-safe toolkit. Generated file is
|
||||
prettier-ignored (like api-client.ts) so the drift gate and format:check don't conflict.
|
||||
|
||||
## Why
|
||||
|
||||
The `/concepts` showcase shows live components, but its code snippets are hand-authored
|
||||
`innerHTML` strings with manual highlighting — they drift from the real code. And the animation
|
||||
toolkit (`withViewTransitions`, native `animate.enter/leave`, reduced-motion-safe keyframes in
|
||||
`styles.scss`) is proven in dashboard/upload but unused for teaching motion.
|
||||
|
||||
## Decisions
|
||||
|
||||
- **Anti-drift snippets:** load _real_ source excerpts via Vite `?raw` imports with `// #region name`
|
||||
markers + a tiny pure extractor; render with lightweight highlighting. No more `innerHTML` literals.
|
||||
- On the Storybook/MDX side, use `<Source>`/Canvas "show code" consistently (extend beyond the
|
||||
current 4 of 14 pages).
|
||||
- **Reuse** the existing motion toolkit (no new animation lib): `animate.enter/leave` on the
|
||||
fold/union demos + a "step through `reduce`" animation for the TEA loop; keep reduced-motion-safe.
|
||||
|
||||
## Files
|
||||
|
||||
- `src/app/showcase/concepts.page.ts` — replace `innerHTML` snippets with `?raw`+region excerpts;
|
||||
apply animations.
|
||||
- New tiny extractor util (pure) + spec (region slicing).
|
||||
- `src/docs/machines.mdx`, `fp-in-ui.mdx`, `remote-data.mdx` — reference the live linked snippets.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] The good-side snippets are sourced from real files via region markers (edit source → regen →
|
||||
snippet updates); a CI drift gate enforces it. Bad-pattern illustrations stay authored.
|
||||
- [x] The state machine + parse demos animate (reduced-motion respected globally); no new dependency.
|
||||
- [x] `npm run ci` green.
|
||||
Reference in New Issue
Block a user