@canonical/anatomy-dsl 0.2.2 → 0.5.0

package/README.md

@@ -9,12 +9,11 @@ A YAML-based DSL for representing design system component anatomies — platform
 node:
   uri: global.component.button
   styles:
-    layout.type: flow
-    layout.direction: horizontal
+    layout.type: inline-flex
     layout.align: center
-    spacing.internal: spacing/medium
-    appearance.background: color/surface/button
-    appearance.radius: radius/button
+    spacing.internal.inline.start: spacing.inset.action.inline
+    appearance.background: [modifier.color.foreground.primary, color.foreground.primary]
+    appearance.radius: dimension.radius.medium
   edges:
     - node:
         uri: global.subcomponent.button-icon
@@ -28,7 +27,201 @@ node:
         slotName: default
 ```
 
-Style values are **design token paths** (`spacing/medium`, `color/surface/button`) — forward-slash delimited references resolved at runtime against the active theme. Primitives like `flow` and `center` are used for layout semantics that don't vary across themes.
+Style values are **token symbols**, written in the symbol's own dotted
+spelling: `dimension.radius.medium`, `color.foreground.primary`. A list is
+the **fallback order** — a one-to-one transcription of the implementation's
+own `var()` chain, so `[modifier.color.foreground.primary,
+color.foreground.primary]` says "read the primary-foreground channel, and
+fall back to the primary foreground token", which is what the reference CSS
+does. A **channel** (`modifier.*`, `surface.*`) is a symbol like any other:
+the anatomy consumes it by name where the implementation reads the channel,
+and the semantic token by name where it reads the token — nothing is
+inferred. Primitives like `inline-flex` and `center` are used for layout
+semantics that do not vary across themes, and one may end a list where the
+implementation's chain ends in a literal
+(`[modifier.color.icon, modifier.color.text, currentColor]`).
+
+Keys come from a **closed roster** — `definitions/style-keys.yaml`, from
+which `definitions/registry.ttl` is generated. The roster is measured, not
+designed: its 111 keys are the right-hand column of a table whose left-hand
+column was every CSS property bound on a component selector across 89
+published component stylesheets, so a key exists because an implementation
+binds the property. That measurement lives in `canonical/design-system`,
+where the reference stylesheets are an input; this package reads no CSS and
+holds the roster, with its provenance stated in both files. The
+slash-delimited path and the trailing `?` marker of earlier versions are
+retired — see `docs/api-reference.md` §5, §11 and §12.
+
+## Projections
+
+Projections bind the anatomy tree directly to graph data, after the Relay
+fragment-colocation pattern: the tree carries its data requirements the way a
+lens component carries its fragment.
+
+```yaml
+---
+node:
+  uri: global.component.entity-card
+  projection:
+    on: Component            # type condition — the tree is a view over one Component
+  edges:
+    - node:
+        uri: global.subcomponent.entity-card-header
+        projection:
+          field: _meta.title # this node renders the entity's title
+      relation:
+        cardinality: "1"
+        slotName: header
+    - node:
+        uri: global.component.chip
+        projection:
+          field: _meta.title # relative to the traversed Tag
+      relation:
+        cardinality: "0..*"
+        slotName: tags
+        projection:
+          field: documentationStages  # traversal populating the slot
+```
+
+Semantics:
+
+- The **root node's** `projection.on` establishes the data context — the anatomy
+  is a parameterized view over one entity of that GraphQL type, like
+  `fragment EntityCard on Component`. Children inherit the context.
+- `projection.field` on a **relation** is a traversal: the slot is populated
+  from that field of the current context. The DSL names the field only —
+  never `edges.node`. Anatomy cardinality ↔ graph multiplicity is the Relay
+  pattern taken one level further.
+- **Cardinality decomposes against the schema.** The upper bound claims
+  multiplicity: `..1` maps to an object or scalar field, `..*` to a
+  connection or list. The lower bound claims nullability: `0..` tolerates
+  `null`, `1..` requires the provider to always have the value. So
+  `field: _meta.title` may sit under `cardinality: "1"` (title is total in
+  the contract), but a nullable field like `summary` must sit under `0..1`.
+  `1..*` asserts a non-empty list — deliberately stronger than GraphQL can
+  express, and checkable only at runtime.
+- **Mechanism-blindness.** Whether a plural field is a Relay connection
+  (`subcomponents`) or a plain list (`properties`) is a provider mechanism,
+  not an anatomy fact. Consumers discover the shape from the SDL and unwrap
+  `edges { node }` when needed; an anatomy survives a provider promoting a
+  list to a connection unchanged.
+- `projection.on` on a **child node** narrows the traversed entity's type — the
+  analog of an inline fragment. Switch cases carrying different `on` values
+  mirror an interface resolved through inline fragments.
+- `projection.field` on a **node** means the node renders that field's value,
+  as a dot-delimited path relative to the enclosing context (`_meta.title`).
+- A node projection needs at least one of `on` / `field`; a relation projection
+  requires `field` and admits no type condition (narrowing belongs on the
+  child node).
+
+Field names are anchored to the provider schema the docsite runs against
+(compiled with `prefixing: "none"`); the committed SDL is the naming authority.
+
+A fully projected anatomy **derives a GraphQL fragment** mechanically — the
+example above reads as:
+
+```graphql
+fragment EntityCardAnatomy on Component {
+  _meta { title }                        # header node
+  documentationStages {                  # tags relation (connection per SDL)
+    edges { node { _meta { title } } }   #   each chip
+  }
+}
+```
+
+The derivation rules (type conditions, dot-path expansion, connection
+unwrapping, inline fragments) are specified in the API reference §3.10
+*Derived fragment*; a worked gallery of every projection form is in §13, and
+`examples/yaml/entity-card.anatomy.yaml` is the golden example.
+
+## Props (pinned values)
+
+A named node can **pin** props of the component it references — fixing a prop
+value at one tree position:
+
+```yaml
+node:
+  uri: global.component.icon
+  props:
+    icon: chevron-down
+```
+
+This is how icons become idiomatic with zero icon-specific machinery. The
+design system models the icon as a component whose glyph is a required prop
+(`ds:global.component.icon` › `ds:hasProperty [ ds:name "icon" ]`), so icon
+usage in anatomies splits into exactly two cases:
+
+- **Consumer-filled icon slot** — an icon-component edge with a slot and no
+  pin. The consumer chooses the glyph; the anatomy correctly says nothing.
+- **Component-intrinsic icon** — the accordion chevron, the modal close ×, a
+  status glyph: the component's own spec fixes the glyph, and the anatomy
+  pins it.
+
+Semantics:
+
+- Pins live on **named nodes only** — anonymous nodes have no prop surface.
+  This is enforced in the types, the parser, and SHACL.
+- The DSL **never defines a prop surface** (names, types, optionality live in
+  the design system ontology); it only asserts values. Whether a pinned prop
+  exists on the component, and whether a value is admissible (e.g. a glyph
+  name in the icon set), are consumer-side checks against the DS graph — the
+  same posture as projection checking against the provider SDL.
+- Values are scalars, coerced to strings — no symbols and no fallback lists: a pin is a value, not a style.
+  Pins are *values with meaning*, not styles: a theme may reskin what
+  `chevron-down` looks like (asset layer), but never remap which glyph an
+  anatomy means.
+- A **data-driven** value is a projection (`projection: { field: … }`), and a
+  **state-driven** one is a `switch` — pinned props are static by design.
+
+In TTL, pins reify like styles do: `hasProp [ a :Prop ; propName "…" ;
+propValue "…" ]`. See `examples/yaml/status-header.anatomy.yaml` for
+intrinsic icons, a status-glyph switch, and an unpinned consumer slot in one
+anatomy.
+
+## Interaction states
+
+Interaction states re-value style channels — they never add structure. A
+style key takes an `@state` suffix scoping its value to a state; the unmarked
+key is the default state:
+
+```yaml
+styles:
+  interaction.cursor: pointer
+  interaction.cursor@disabled: not-allowed
+  appearance.background: [modifier.color.foreground.primary, color.foreground.primary]
+  appearance.background@hover: color.foreground.primary.hover
+  appearance.background@disabled: color.foreground.primary.disabled
+  # A slot may read a channel only in one state.
+  appearance.outline.color@focus: [modifier.color.focusRing, color.focusRing, currentColor]
+```
+
+The state vocabulary is **closed and registry-governed**: `hover`, `active`,
+`focus`, `disabled`, `selected`. Naming follows the industry consensus where
+systems diverge — `active` subsumes Material's *pressed* and Spectrum's
+*down* (and matches Canonical's own token tree); `focus` maps to CSS
+`:focus-visible` (Spectrum's *key-focus*). `@default` is invalid — absence is
+the default. Candidate additions (`checked`, `visited`, `dragged`, `pending`,
+`error`, `read-only`) go through the registry, never by loosening the schema.
+
+The boundaries that keep "state machines out of scope" true:
+
+- **States hold style values only.** A state that changes the tree is not a
+  state — it is a `switch on: internal` case (async-button's
+  idle/loading/success/error). The DSL declares appearance *per* state, never
+  transitions, triggers, or logic.
+- **Gate vs appearance**: `props: { disabled: true }` (or the consumer) puts
+  a node in the disabled state; `…@disabled` styles say how it looks there.
+- A state-scoped value that differs from its base state's is a **lint, not a
+  constraint**: it is reported with the ranks at which they differ and never
+  rejected, because the reference does it — Button's `:disabled` reads
+  `color.text.disabled`, a different symbol from its resting `color.text`.
+- The grammar reserves repeatable markers for compound states
+  (`@selected@hover`, canonical order: value/control state before user-action
+  state); v1 permits a single `@`.
+
+In TTL, the Style tuple gains one optional dimension:
+`[ a :Style ; :styleKey "appearance.background" ; :styleState "hover" ; :styleValue "…" ]`.
+See `examples/yaml/stateful-button.anatomy.yaml`.
 
 ## Install
 
@@ -50,19 +243,19 @@ const ttl = anatomyToTTL(spec);
 The button example above produces:
 
 ```turtle
-@prefix : <http://anatomy-dsl.example.org/ontology#> .
+@prefix : <https://anatomy.canonical.com/> .
+@prefix dt: <https://dt.canonical.com/> .
 
 [] a :Specification ;
     :rootNode [
         a :NamedNode ;
         :uri "global.component.button" ;
         :hasStyle
-            [ :styleKey "layout.type" ; :styleValue "flow" ] ,
-            [ :styleKey "layout.direction" ; :styleValue "horizontal" ] ,
-            [ :styleKey "layout.align" ; :styleValue "center" ] ,
-            [ :styleKey "spacing.internal" ; :styleValue "spacing/medium" ] ,
-            [ :styleKey "appearance.background" ; :styleValue "color/surface/button" ] ,
-            [ :styleKey "appearance.radius" ; :styleValue "radius/button" ] ;
+            [ a :Style ; :styleKey "layout.type" ; :styleValue "inline-flex" ] ,
+            [ a :Style ; :styleKey "layout.align" ; :styleValue "center" ] ,
+            [ a :Style ; :styleKey "spacing.internal.inline.start" ; :styleValue "spacing.inset.action.inline" ; :consumes ( dt:spacing.inset.action.inline ) ] ,
+            [ a :Style ; :styleKey "appearance.background" ; :styleValue "[modifier.color.foreground.primary, color.foreground.primary]" ; :consumes ( dt:modifier.color.foreground.primary dt:color.foreground.primary ) ] ,
+            [ a :Style ; :styleKey "appearance.radius" ; :styleValue "dimension.radius.medium" ; :consumes ( dt:dimension.radius.medium ) ] ;
         :hasEdge [
             a :Edge ;
             :edgeTarget [
@@ -111,31 +304,53 @@ All types mirror the [OWL ontology](definitions/ontology.ttl) exactly:
 | `Node` | `NamedNode \| AnonymousNode` (discriminated on `type`) |
 | `Edge` | Reified parent→child relationship |
 | `Relation` | Cardinality and optional slot name |
-| `Style` | Reified key-value tuple |
+| `Style` | Reified key-value tuple, with an optional interaction `state` dimension |
 | `Switch` | Polymorphic position (discriminator: `props \| internal \| override`) |
 | `SwitchCase` | One alternative within a switch |
+| `Projection` | Fragment-style graph binding on a node (`on` type condition and/or `field` path) |
+| `RelationProjection` | Traversal populating a slot (`field` required) |
+| `Prop` | Pinned prop value on a named node (reified name-value tuple) |
 
 ## Repository Structure
 
 ```
-definitions/   Turtle ontology (OWL) + SHACL shapes
-schemas/       JSON Schema for validating .anatomy.yaml files
-docs/          API reference (merged WD404 + WD404.1)
-examples/      Example anatomy files (YAML + Turtle pairs)
-src/           TypeScript types, parser, and transform
+definitions/   Turtle ontology (OWL) + SHACL shapes, the style-key roster and
+               the registry generated from it, and the lift fixture — all of
+               it public API, since exports lists it
+docs/          API reference (WD404 + WD404.1 + WD404.2 + WD404.3)
+examples/      Example anatomy files (YAML + Turtle pairs), the corpus the
+               round-trip and SHACL tests read
+src/           TypeScript types, parser, value grammar, transform and the
+               generators
 ```
 
 ## Scope
 
-The Anatomy DSL describes **structure only**. It does not handle:
+The Anatomy DSL describes **structure**, **graph-data bindings** (projections
+— what data each position renders), **pinned prop values** (props — fixed
+component configuration at a position), and **state-scoped styles**
+(interaction states — how channels re-value per state). It does not handle:
 
-- **Prop mapping** — which props a component accepts and how they map to behaviour
-- **State or state machines** — component states, transitions, or interaction logic
+- **Prop surface definition** — which props a component accepts, their types
+  and optionality live in the design system ontology; the DSL only pins values
+- **State machines** — transitions, triggers, and interaction logic; the DSL
+  declares appearance per state only, and structural state variation is the
+  switch construct's job
 - **Modifier descriptions** — only design token references are supported, not semantic modifier definitions
 
 ## Design Notes
 
-Styles are modelled as reified key-value tuples (`hasStyle [ styleKey "…" ; styleValue "…" ]`). This keeps the ontology open-ended while remaining lossless. Frequently used style keys may be promoted to first-class datatype properties in a future version.
+Styles are modelled as reified key-value tuples
+(`hasStyle [ a :Style ; :styleKey "…" ; :styleValue "…" ]`), which stays
+lossless whatever the key roster becomes. Since 0.4.0 a tuple whose key takes
+a token also carries `:consumes`, an ordered `rdf:List` of the `dt:` symbols
+it reads: `:styleValue` is the authored spelling kept verbatim as evidence —
+it is where a terminal literal lives, since a literal is not a symbol — and
+`:consumes` is the form a query can walk. The key vocabulary is no longer
+open: `anatomy:styleKey`'s `sh:in` is projected from the registry, so a key
+outside the roster is a SHACL violation rather than a silent addition.
+
+Projections and pinned props reuse the same reification idiom (`hasProjection [ projectionType "…" ; projectionField "…" ]`, `hasProp [ propName "…" ; propValue "…" ]`). Projections attach to both nodes and relations — the reified `Relation` is precisely what makes slot-level traversal annotations possible without changing the `Edge` class; pins attach to named nodes only.
 
 ## Specification Status
 
@@ -143,3 +358,5 @@ Styles are modelled as reified key-value tuples (`hasStyle [ styleKey "…" ; st
 |---------|--------------------------|----------------|
 | [WD404](https://docs.google.com/document/d/1eFr-SNsAZyidnZzpWp1Jeegiat_SSM7mOW_G8p3nXo8/edit?tab=t.pndvuecem8cf)   | Anatomy DSL              | Approved       |
 | [WD404.1](https://docs.google.com/document/d/1eFr-SNsAZyidnZzpWp1Jeegiat_SSM7mOW_G8p3nXo8/edit?tab=t.pndvuecem8cf) | Anatomy DSL — Addendum 1 | Pending Review |
+| WD404.2 | Anatomy DSL — Projections | Draft (this repository) |
+| WD404.3 | Anatomy DSL — Prop pinning | Draft (this repository) |

package/definitions/lift.fixture.json

@@ -0,0 +1,216 @@
+{
+  "$comment": [
+    "The committed lift fixture (ADR J §4.1, §8.2). Both TypeScript repositories assert against it, so anatomy-dsl and design-system lift identically and cannot drift apart without a failing test.",
+    "`values` is the value lift this package implements: `liftSymbols(value)` over what the YAML parser holds for a style value — a scalar or a sequence of scalars — returning the symbols in fallback order. A primitive is not a symbol: it resolves against nothing by design, so it is never lifted.",
+    "`rejections` is the retired notation, with the rule each breaks. Every one throws an AnatomyValueError naming the value and the rule.",
+    "`names` is the CSS-name lift of §5.1 step 5d, which design-system implements because it needs S4 to run: a custom-property name to the dotted symbol it lifts to, or null where it names no symbol in any stratum and is kept as consumed with a register row (AT.09). It is DATA here, not an implementation — this package ships it so the two repositories agree on the expected pairs."
+  ],
+  "values": [
+    { "case": "a symbol", "value": "color.text", "symbols": ["color.text"] },
+    {
+      "case": "a camelCase segment is the symbol's own spelling, not renamed",
+      "value": "color.focusRing",
+      "symbols": ["color.focusRing"]
+    },
+    {
+      "case": "a numeric segment",
+      "value": "dimension.100",
+      "symbols": ["dimension.100"]
+    },
+    {
+      "case": "a deep camelCase symbol",
+      "value": "typography.weight.semiBold",
+      "symbols": ["typography.weight.semiBold"]
+    },
+    {
+      "case": "a channel symbol, consumed by name where the implementation reads the channel",
+      "value": "modifier.color.text",
+      "symbols": ["modifier.color.text"]
+    },
+    {
+      "case": "the surface channel spelling",
+      "value": "surface.color.background",
+      "symbols": ["surface.color.background"]
+    },
+    {
+      "case": "the programme's central binding: a channel then the semantic token",
+      "value": ["modifier.color.text", "color.text"],
+      "symbols": ["modifier.color.text", "color.text"]
+    },
+    {
+      "case": "three ranks, in the reference's own order",
+      "value": ["modifier.color.border", "color.border.highlighted", "color.border"],
+      "symbols": [
+        "modifier.color.border",
+        "color.border.highlighted",
+        "color.border"
+      ]
+    },
+    {
+      "case": "a terminal literal is kept in the value and lifted from none of it",
+      "value": ["modifier.color.icon", "modifier.color.text", "currentColor"],
+      "symbols": ["modifier.color.icon", "modifier.color.text"]
+    },
+    {
+      "case": "a dimension tail",
+      "value": ["dimension.stroke.thickness.large", "2px"],
+      "symbols": ["dimension.stroke.thickness.large"]
+    },
+    {
+      "case": "a bare keyword, for a key the registry says takes a primitive",
+      "value": "flow",
+      "symbols": []
+    },
+    {
+      "case": "a hyphenated CSS keyword, which the reference uses throughout",
+      "value": "not-allowed",
+      "symbols": []
+    },
+    { "case": "a number", "value": "1.6", "symbols": [] },
+    { "case": "a percentage", "value": "0%", "symbols": [] },
+    { "case": "a colour", "value": "#ccc", "symbols": [] },
+    {
+      "case": "a literal holding a slash between spaces: the slash ban is on symbol spellings, never on literals",
+      "value": "1 / -1",
+      "symbols": []
+    },
+    {
+      "case": "a literal a bare YAML would read as an alias",
+      "value": "*",
+      "symbols": []
+    },
+    {
+      "case": "an undeclared name is still a symbol by grammar: whether it resolves is the register's question, not the parser's",
+      "value": ["modifier.surface", "color.foreground.primary"],
+      "symbols": ["modifier.surface", "color.foreground.primary"]
+    },
+    {
+      "case": "a computed state variable, kept as consumed under the hover.X spelling",
+      "value": ["hover.color.foreground.secondary", "color.foreground.secondary.hover"],
+      "symbols": [
+        "hover.color.foreground.secondary",
+        "color.foreground.secondary.hover"
+      ]
+    }
+  ],
+  "rejections": [
+    { "case": "a slash path", "value": "spacing/medium", "rule": "slashPath" },
+    {
+      "case": "a slash path with a camelCase-bearing segment",
+      "value": "color/focus-ring",
+      "rule": "slashPath"
+    },
+    {
+      "case": "a slash path inside a sequence",
+      "value": ["modifier/color/foreground", "color/foreground/primary"],
+      "rule": "slashPath"
+    },
+    {
+      "case": "the retired optional marker on a slash path",
+      "value": "color/surface/button?",
+      "rule": "slashPath"
+    },
+    {
+      "case": "the retired optional marker on a dotted symbol",
+      "value": "color.surface.button?",
+      "rule": "marker"
+    },
+    { "case": "the reserved root segment", "value": "$root", "rule": "root" },
+    {
+      "case": "the reserved root segment inside a dotted name",
+      "value": "color.$root.text",
+      "rule": "root"
+    },
+    {
+      "case": "a bare root segment",
+      "value": "color.root.text",
+      "rule": "root"
+    },
+    {
+      "case": "a primitive before the end: the sequence is the fallback order and a literal is what the chain ends in",
+      "value": ["2px", "dimension.stroke.thickness.large"],
+      "rule": "primitiveNotLast"
+    },
+    {
+      "case": "a primitive in the middle",
+      "value": ["modifier.color.text", "currentColor", "color.text"],
+      "rule": "primitiveNotLast"
+    },
+    {
+      "case": "a one-element sequence: a fallback order needs two",
+      "value": ["color.text"],
+      "rule": "singleton"
+    },
+    { "case": "an empty sequence", "value": [], "rule": "empty" },
+    { "case": "an empty scalar", "value": "", "rule": "empty" }
+  ],
+  "names": [
+    {
+      "case": "a plain semantic token",
+      "variable": "--color-text",
+      "symbol": "color.text"
+    },
+    {
+      "case": "camelCase is restored from the kebab spelling S4 emits",
+      "variable": "--color-focus-ring",
+      "symbol": "color.focusRing"
+    },
+    {
+      "case": "the drift spelling S4 also emits for the same symbol",
+      "variable": "--color-focusRing",
+      "symbol": "color.focusRing"
+    },
+    {
+      "case": "a modifier channel",
+      "variable": "--modifier-color-text",
+      "symbol": "modifier.color.text"
+    },
+    {
+      "case": "a surface channel",
+      "variable": "--surface-color-background",
+      "symbol": "surface.color.background"
+    },
+    {
+      "case": "a channel with no base symbol: kept as consumed, register row X7",
+      "variable": "--modifier-surface",
+      "symbol": "modifier.surface",
+      "resolves": false
+    },
+    {
+      "case": "a state variant of a channel: register row X5",
+      "variable": "--modifier-surface-hover",
+      "symbol": "modifier.surface.hover",
+      "resolves": false
+    },
+    {
+      "case": "a computed state variable: the double dash lifts to a dot, register row X15",
+      "variable": "--hover--color-foreground-secondary",
+      "symbol": "hover.color.foreground.secondary",
+      "resolves": false
+    },
+    {
+      "case": "a component-local variable is followed through its :root definition and replaced by what it consumes",
+      "variable": "--button-color-text",
+      "symbol": "color.text",
+      "via": "--button-color-text: var(--color-text)"
+    },
+    {
+      "case": "a component-local variable whose definition is itself a chain",
+      "variable": "--button-color-background",
+      "symbol": "modifier.color.foreground.primary",
+      "via": "--button-color-background: var(--modifier-color-foreground-primary, var(--color-foreground-primary))"
+    },
+    {
+      "case": "an undeclared name: kept as consumed with a comment, register row X1",
+      "variable": "--motion-duration-fast",
+      "symbol": "motion.duration.fast",
+      "resolves": false
+    },
+    {
+      "case": "a composite typography slot no stratum declares",
+      "variable": "--typography-text-secondary-font-size",
+      "symbol": "typography.text.secondary.fontSize",
+      "resolves": false
+    }
+  ]
+}