feat(showcase): WP-39 — linked code snippets + teaching animations

Anti-drift snippets: `?raw` isn't supported by Angular's esbuild build, so real code is exposed via // #region showcase:<name> markers in source (registration/remote-data/ postcode/change-request.machine/intake.machine) → scripts/gen-snippets.mjs → committed snippets.generated.ts, with a CI drift gate so the shown code is the shipped code. The /concepts page renders the 5 real snippets (union/fold/parse/machine/steps) with a source caption + a tiny dependency-free highlightTs (+spec); deliberately-wrong illustrations stay authored. Teaching motion: active state node pops on transition + parse result animates in (existing reduced-motion-safe toolkit). Generated file prettier-ignored (like api-client). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-23 14:49:52 +02:00
parent f8cd77a48a
commit 19f2e9b734
16 changed files with 258 additions and 34 deletions
@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// Extract `// #region showcase:<name>` … `// #endregion showcase:<name>` blocks from real
+// source files into src/app/showcase/snippets.generated.ts (WP-39). The teaching showcase
+// renders these, so the code it shows IS the code that ships — it can't drift. A CI drift
+// gate (`npm run gen:snippets && git diff --exit-code`) forces a regen after any edit to a
+// marked region. Mirrors the gen:api pattern. Run: `npm run gen:snippets`.
+import { readFileSync, writeFileSync } from 'node:fs';
+
+// Real source files that carry showcase regions. Add a file here + a #region marker there
+// to expose a new snippet; no other change needed.
+const SOURCES = [
+  'src/app/registratie/domain/registration.ts',
+  'src/app/shared/application/remote-data.ts',
+  'src/app/registratie/domain/value-objects/postcode.ts',
+  'src/app/registratie/domain/change-request.machine.ts',
+  'src/app/herregistratie/domain/intake.machine.ts',
+];
+
+const START = /\/\/\s*#region showcase:([\w-]+)/;
+const END = /\/\/\s*#endregion showcase:/;
+
+/** Remove the shared leading indentation so an extracted, once-nested block reads flush. */
+function dedent(lines) {
+  const indents = lines.filter((l) => l.trim()).map((l) => l.match(/^\s*/)[0].length);
+  const min = indents.length ? Math.min(...indents) : 0;
+  return lines
+    .map((l) => l.slice(min))
+    .join('\n')
+    .trim();
+}
+
+const snippets = {};
+for (const file of SOURCES) {
+  const lines = readFileSync(file, 'utf8').split('\n');
+  let name = null;
+  let buf = [];
+  for (const line of lines) {
+    const start = line.match(START);
+    if (start) {
+      name = start[1];
+      buf = [];
+      continue;
+    }
+    if (name && END.test(line)) {
+      if (snippets[name]) throw new Error(`duplicate showcase region: ${name}`);
+      snippets[name] = dedent(buf);
+      name = null;
+      continue;
+    }
+    if (name) buf.push(line);
+  }
+  if (name) throw new Error(`unterminated showcase region "${name}" in ${file}`);
+}
+
+const names = Object.keys(snippets).sort();
+const body = names.map((n) => `  ${JSON.stringify(n)}: ${JSON.stringify(snippets[n])},`).join('\n');
+const out = `// GENERATED by \`npm run gen:snippets\` (scripts/gen-snippets.mjs) — do not edit.
+// Source-of-truth code excerpts extracted from real files via // #region showcase:<name>.
+export const SNIPPETS: Record<string, string> = {
+${body}
+};
+`;
+writeFileSync('src/app/showcase/snippets.generated.ts', out);
+console.log(
+  `wrote src/app/showcase/snippets.generated.ts (${names.length} snippets: ${names.join(', ')})`,
+);