docs: reorganize into project/ + reference/, expand Storybook Foundations
Move working docs (backlog, prd, roadmap) under docs/project/ and durable docs (architecture ADRs, guides, audits) under docs/reference/; add a docs/README.md index. Update every path reference in code comments, CLAUDE.md, READMEs, and the new-ssp skill. Expand the Storybook Foundations curriculum (Overview, BDD, i18n; rename Layers→Domain-Driven Design) and reorder the sidebar. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -10,7 +10,7 @@ professional logs in, sees their registration, and can apply for
|
||||
re-registration — "herregistratie").
|
||||
|
||||
> New to functional programming or The Elm Architecture? Start with the progressive
|
||||
> learning guide [`fp-tea-atomic-design.md`](./fp-tea-atomic-design.md), which teaches
|
||||
> learning guide [`fp-tea-atomic-design.md`](../fp-tea-atomic-design.md), which teaches
|
||||
> the concepts (with Elm ↔ this-app examples) and the recipes; this document is the
|
||||
> reference deep-dive it points back to.
|
||||
|
||||
|
||||
@@ -17,7 +17,7 @@ feature." A senior can skim Parts 1–4 and jump to **Part 5** (FP × atomic des
|
||||
defined in plain words on first use and again in the **glossary** (Part 8).
|
||||
|
||||
This guide is the _teaching_ layer. For the reference deep-dives it points to
|
||||
[`ARCHITECTURE.md`](./ARCHITECTURE.md) and
|
||||
[`ARCHITECTURE.md`](./architecture/ARCHITECTURE.md) and
|
||||
[ADR-0001](./architecture/0001-bff-lite-decision-dtos.md) rather than repeating them.
|
||||
Every code snippet below is real code from this repo, with its file path.
|
||||
|
||||
@@ -127,7 +127,7 @@ Two kinds of type do most of the work:
|
||||
|
||||
The decisive move is choosing types so that **illegal states can't be written down**.
|
||||
Compare three booleans (2³ = 8 combinations, most nonsense) with one union of the 4 real
|
||||
states — see [`ARCHITECTURE.md` §2a](./ARCHITECTURE.md#2a-remotedata--one-value-instead-of-three-booleans)
|
||||
states — see [`ARCHITECTURE.md` §2a](./architecture/ARCHITECTURE.md#2a-remotedata--one-value-instead-of-three-booleans)
|
||||
for the full `RemoteData` treatment and diagram. The wizard's own Model is the same
|
||||
idea (`herregistratie.machine.ts`):
|
||||
|
||||
@@ -216,7 +216,7 @@ This app implements TEA with Angular **signals**. There is no extra state librar
|
||||
important shape difference from textbook Elm: **state is per-wizard, not one global
|
||||
Model** — each flow (`herregistratie`, `intake`, `registratie`) has its own little
|
||||
store. Cross-page state that _must_ be shared lives in one root singleton
|
||||
(`BigProfileStore`, see [`ARCHITECTURE.md` §2e](./ARCHITECTURE.md#2e-optimistic-update--rollback-and-shared-state-across-pages)).
|
||||
(`BigProfileStore`, see [`ARCHITECTURE.md` §2e](./architecture/ARCHITECTURE.md#2e-optimistic-update--rollback-and-shared-state-across-pages)).
|
||||
|
||||
### 4a. The store — TEA's runtime in ~10 lines
|
||||
|
||||
@@ -424,7 +424,7 @@ Molecules compose atoms; organisms compose molecules — exactly like composing
|
||||
functions, where the composite is still pure. `address-fields` is pure because the
|
||||
`form-field` and `text-input` it's built from are pure. Each atomic level only uses the
|
||||
level(s) below it (see the hierarchy diagram in
|
||||
[`ARCHITECTURE.md` §1](./ARCHITECTURE.md#1-the-big-picture-three-contexts-four-layers)).
|
||||
[`ARCHITECTURE.md` §1](./architecture/ARCHITECTURE.md#1-the-big-picture-three-contexts-four-layers)).
|
||||
|
||||
### 5c. Pages / containers are the TEA runtime (the shell)
|
||||
|
||||
@@ -474,7 +474,7 @@ Each property maps to a tangible benefit you can point at in this repo:
|
||||
- **Illegal states won't compile.** `Submitting` carries `Valid` data and has no `errors`
|
||||
field, so "submit with errors showing" is unwritable. A whole bug class disappears
|
||||
before runtime — contrast the 8-state boolean soup in
|
||||
[`ARCHITECTURE.md` §2a](./ARCHITECTURE.md#2a-remotedata--one-value-instead-of-three-booleans).
|
||||
[`ARCHITECTURE.md` §2a](./architecture/ARCHITECTURE.md#2a-remotedata--one-value-instead-of-three-booleans).
|
||||
|
||||
- **Pure presentational components.** `address-fields` is tested by inputs → DOM and
|
||||
reused in two call-sites (the registratie wizard and the change-request form) with no
|
||||
@@ -500,7 +500,7 @@ Each recipe follows the existing pattern and naming, and ends with the same remi
|
||||
### Recipe A — Add an atomic component (atom / molecule / organism)
|
||||
|
||||
**When:** you genuinely need a new building block (not a one-off; reuse must earn it —
|
||||
see [CLAUDE.md §2](../CLAUDE.md)).
|
||||
see [CLAUDE.md §2](../../CLAUDE.md)).
|
||||
|
||||
**Where:** `shared/ui/` if generic; a context's `ui/` if domain-specific. Pick the level
|
||||
by composition: composes nothing → **atom**; composes atoms → **molecule**; composes
|
||||
@@ -634,7 +634,7 @@ _This is the same loop, again — now nested inside the wizard._
|
||||
|
||||
---
|
||||
|
||||
_See also:_ [`ARCHITECTURE.md`](./ARCHITECTURE.md) (reference deep-dive on RemoteData,
|
||||
_See also:_ [`ARCHITECTURE.md`](./architecture/ARCHITECTURE.md) (reference deep-dive on RemoteData,
|
||||
the store, parse-don't-validate, and the .NET backend seam) and
|
||||
[ADR-0001](./architecture/0001-bff-lite-decision-dtos.md) (the BFF-lite + decision-DTO
|
||||
decision). Live demo: `/concepts` in the running app.
|
||||
|
||||
Reference in New Issue
Block a user