feat: gallery + generic blueprint viewer, add Grid blueprint

Refactor the List-specific screen into a data-driven, reusable viewer:
- generic Blueprint type + shared LoadState machine + registry
- vue-router: / (gallery) and /b/:slug (illustration)
- BlueprintViewer renders any blueprint; specimens stay bespoke
- add Grid blueprint (6 functions incl. Position) + GridSpecimen
This commit is contained in:
Julien Calixte
2026-07-02 18:34:49 +02:00
parent 4405497658
commit 03804b10dc
21 changed files with 2304 additions and 765 deletions

65
CONTEXT.md Normal file
View File

@@ -0,0 +1,65 @@
# Context — ubiquitous language
The shared vocabulary for `blueprints`. These terms should appear verbatim in
conversation, code, file names, and commits. This file is a glossary only — no
implementation details (those live in `DESIGN.md`).
## Blueprint
A named contract for a recurring UI pattern, taken from the `blueprint-ontology`
repo — declarative, categorical, abstract (a _concept_ in Jackson's sense). It
defines what must be true of the pattern: its signature, state machine, behaviors,
invariants, functions, critical-performance thresholds, and failure modes. Examples:
`List`, `Grid`, `Table`, `Async`.
Blueprints come in two roles (from the ontology):
- **Feature** — a standalone pattern a user interacts with (`List`, `Grid`, `Form`).
- **Capability** — a composable blueprint that adds state/behavior onto a host
feature (`Async`, `Paginated`, `Selectable`).
## Illustration
This app's rendered, interactive presentation of a single blueprint. `blueprints`
is a gallery of illustrations. "Illustration" is the noun for the whole per-blueprint
screen; do not use "demo" (implies a live working widget — these are static) or
"page" (routing concept, not domain).
## Viewer
The one reusable component that renders any blueprint's illustration. It draws the
generic parts from a blueprint's typed data and slots in that blueprint's bespoke
Specimen. Every illustration is the Viewer applied to one blueprint.
## Specimen
The interactive-looking but **static** visual mock of the blueprint's actual UI —
the left pane of the Viewer. Bespoke per blueprint (a Grid specimen looks nothing
like a List's). Selecting a Function highlights the region of the specimen that
function owns. Not "mockup", not "demo".
## Readout
The right pane of the Viewer: the blueprint's formal contract for the selected
Function — source capability, responsibility, state touched, behaviors (pre →
effect), invariants, failure modes, critical-performance thresholds.
## Companion
A supporting schematic shown below the Viewer's two panes. Two kinds exist so far:
the **composition map** (how a feature extends/composes with capabilities) and the
**state machine** (the blueprint's lifecycle). A blueprint may have neither, one, or
both.
## Function
One row of a blueprint's "Functional analysis" — a named responsibility of the
pattern (e.g. List's `Display`, `Scroll`, `Load`). Functions are the unit the Viewer
lets you explore, tab by tab. Distinct from **Behavior** (a concrete state
transition like `loadMore()`); behaviors are the mechanics underneath a function.
## Gallery
The app's index (landing screen): every blueprint in the ontology, each as a card
linking to its illustration — including blueprints not yet illustrated, shown as
**planned**.