Files

T

ehoandClaude Opus 5 12f17d9d73 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>

2026-09-08 23:00:38 +02:00

2.7 KiB

Raw Blame History

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

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.
The state machine + parse demos animate (reduced-motion respected globally); no new dependency.
npm run ci green.

2.7 KiB Raw Blame History