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:
65
CONTEXT.md
Normal file
65
CONTEXT.md
Normal 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**.
|
||||
Reference in New Issue
Block a user