@canonical/anatomy-dsl 0.5.0 → 0.6.0

package/README.md

@@ -196,12 +196,16 @@ styles:
 ```
 
 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.
+`focus`, `disabled`, `selected`, `expanded`, `indeterminate`, `invalid`.
+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*); `expanded` is a disclosure's open state (`[open]`,
+`aria-expanded`); `indeterminate` is a mixed checkbox or progress bar, on
+neither setting; `invalid` is a failed validation (`:invalid`,
+`aria-invalid`). `@default` is not admitted — 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:
 

package/definitions/ontology.ttl

@@ -340,13 +340,17 @@ anatomy:styleState a owl:DatatypeProperty ;
     rdfs:range xsd:string ;
     skos:definition """Interaction state this style value applies in. Absent
     means the default state. Closed vocabulary (hover, active, focus,
-    disabled, selected), governed by registry — 'active' subsumes Material's
-    'pressed' and Spectrum's 'down'; 'focus' maps to CSS :focus-visible
-    (Spectrum's 'key-focus'). States re-value style channels only: they never
+    disabled, selected, expanded, indeterminate, invalid), governed by
+    registry — 'active' subsumes Material's 'pressed' and Spectrum's 'down';
+    'focus' maps to CSS :focus-visible (Spectrum's 'key-focus'); 'expanded'
+    is a disclosure's open state ([open], aria-expanded); 'indeterminate' is
+    a mixed checkbox or progress bar; 'invalid' is a failed validation
+    (:invalid, aria-invalid). States re-value style channels only: they never
     add structure (that is the Switch construct) and never define transitions
     or interaction logic (state machines stay out of scope). Authored as an
     @state suffix on the style key.""" ;
-    skos:example "hover" , "active" , "focus" , "disabled" , "selected" .
+    skos:example "hover" , "active" , "focus" , "disabled" , "selected" ,
+                 "expanded" , "indeterminate" , "invalid" .
 
 anatomy:projectionType a owl:DatatypeProperty ;
     rdfs:label "projection type" ;

package/definitions/registry.ttl

@@ -14,7 +14,9 @@
 #                          shapes state that disjunction.
 #   anatomy:tokenNamespace the dotted prefixes whose symbols the key admits,
 #                          multi-valued: N., modifier.N. and surface.N., so a
-#                          channel binding is not a namespace violation.
+#                          channel binding is not a namespace violation. A key
+#                          may admit more than one base namespace, and then it
+#                          carries the three spellings of each.
 #
 # PROVENANCE. The roster is not designed: these 111 keys were measured from
 # the 89 published component stylesheets of
@@ -460,109 +462,109 @@ anatomy:key.spacing.external.block.end
     a anatomy:StyleKey ;
     rdfs:label "spacing.external.block.end" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.external.block.start
     a anatomy:StyleKey ;
     rdfs:label "spacing.external.block.start" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.external.bottom
     a anatomy:StyleKey ;
     rdfs:label "spacing.external.bottom" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.external.inline.end
     a anatomy:StyleKey ;
     rdfs:label "spacing.external.inline.end" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.external.inline.start
     a anatomy:StyleKey ;
     rdfs:label "spacing.external.inline.start" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.external.left
     a anatomy:StyleKey ;
     rdfs:label "spacing.external.left" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.external.right
     a anatomy:StyleKey ;
     rdfs:label "spacing.external.right" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.external.top
     a anatomy:StyleKey ;
     rdfs:label "spacing.external.top" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.gap
     a anatomy:StyleKey ;
     rdfs:label "spacing.gap" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.gap.block
     a anatomy:StyleKey ;
     rdfs:label "spacing.gap.block" ;
     anatomy:valueKind "token" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.gap.inline
     a anatomy:StyleKey ;
     rdfs:label "spacing.gap.inline" ;
     anatomy:valueKind "token" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.internal.block.end
     a anatomy:StyleKey ;
     rdfs:label "spacing.internal.block.end" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.internal.block.start
     a anatomy:StyleKey ;
     rdfs:label "spacing.internal.block.start" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.internal.bottom
     a anatomy:StyleKey ;
     rdfs:label "spacing.internal.bottom" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.internal.inline.end
     a anatomy:StyleKey ;
     rdfs:label "spacing.internal.inline.end" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.internal.inline.start
     a anatomy:StyleKey ;
     rdfs:label "spacing.internal.inline.start" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.internal.left
     a anatomy:StyleKey ;
     rdfs:label "spacing.internal.left" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.spacing.internal.top
     a anatomy:StyleKey ;
     rdfs:label "spacing.internal.top" ;
     anatomy:valueKind "either" ;
-    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." .
+    anatomy:tokenNamespace "spacing." , "modifier.spacing." , "surface.spacing." , "dimension." , "modifier.dimension." , "surface.dimension." .
 
 anatomy:key.typography.align
     a anatomy:StyleKey ;

package/definitions/shapes.ttl

@@ -511,6 +511,13 @@ anatomy:StyleShape a sh:NodeShape ;
     # candidates), never through loosening this list ad hoc. There is no
     # "default" state: an absent styleState IS the default.
     #
+    # expanded, indeterminate and invalid entered that way, and the line they
+    # sit on is worth stating: a state is admitted where the implementation
+    # RE-VALUES a channel in it, and refused where it changes what exists. A
+    # disclosure header with a different background while open is the first;
+    # the panel that exists only while open is the second, and stays the
+    # Switch construct's.
+    #
     # A state value that differs from its base state's is a LINT, not a
     # constraint (AT.11): the reference does it — Button's :disabled reads a
     # different symbol — so it is reported with its ranks and never rejected,
@@ -519,8 +526,8 @@ anatomy:StyleShape a sh:NodeShape ;
         sh:path anatomy:styleState ;
         sh:maxCount 1 ;
         sh:datatype xsd:string ;
-        sh:in ( "hover" "active" "focus" "disabled" "selected" ) ;
-        sh:message "styleState must be one of: hover, active, focus, disabled, selected (absent = default state)." ;
+        sh:in ( "hover" "active" "focus" "disabled" "selected" "expanded" "indeterminate" "invalid" ) ;
+        sh:message "styleState must be one of: hover, active, focus, disabled, selected, expanded, indeterminate, invalid (absent = default state)." ;
     ] ;
 
     # BEGIN GENERATED valueKind sh:or — bun run generate:shapes

package/definitions/style-keys.yaml

@@ -49,14 +49,22 @@
 #               needs: `N.`, `modifier.N.` and `surface.N.`, because a
 #               channel of a symbol in `N.` is what the anatomy consumes
 #               where the implementation reads the channel.
+#               A key that admits symbols from more than one namespace
+#               states them as a LIST — `[spacing., dimension.]` — and each
+#               one is projected into its own three spellings, grouped by
+#               namespace and in the order written here. One namespace and
+#               a one-element list mean the same thing; the scalar form is
+#               the ordinary one, and the list says a key really does draw
+#               on two populations.
 #   why:        required on a `primitive` key whose reference values read a
 #               `var()` anyway — a component-local count, an asset — and
 #               emitted as the key's `rdfs:comment`, so the exception is
 #               stated and not silent. Forbidden on a key that takes a token.
 #
-# `spacing.*` keys admit `spacing.` alone and never `dimension.`: the
-# reference binds `dimension.*` there throughout, and that population is
-# the register's to carry rather than the roster's to bless.
+# `spacing.*` keys admit `spacing.` and, for now, `dimension.` too: the
+# reference binds `dimension.*` there throughout, and until semantic spacing
+# lands the roster admits both rather than sending every real binding to the
+# register. The second namespace is temporary and is marked as such below.
 #
 # `motion.` is declared as a namespace though no stratum publishes one yet,
 # so a `motion.duration.fast` binding is admitted and its absence is a
@@ -291,60 +299,64 @@ keys:
     valueKind: either
     namespace: dimension.
 
+  # dimension. is admitted temporarily — the implementations read
+  # `--dimension-*` directly for padding and gaps, and the semantic spacing
+  # namespace is still thin (twelve symbols). Remove `dimension.` here once
+  # semantic spacing lands (ADR J ledger, row G1).
   spacing.external.block.end:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.external.block.start:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.external.bottom:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.external.inline.end:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.external.inline.start:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.external.left:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.external.right:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.external.top:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.gap:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.gap.block:
     valueKind: token
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.gap.inline:
     valueKind: token
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.internal.block.end:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.internal.block.start:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.internal.bottom:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.internal.inline.end:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.internal.inline.start:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.internal.left:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
   spacing.internal.top:
     valueKind: either
-    namespace: spacing.
+    namespace: [spacing., dimension.]
 
   typography.align:
     valueKind: primitive

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+export { parseAnatomyYAML } from "./parse.js";
+export { PLACEHOLDER_SEGMENTS, STYLE_KEYS, takesToken, } from "./registry.generated.js";
+export { anatomyToTTL } from "./transform.js";
+export { AnatomyValueError, authoredSpelling, classifyElement, liftSymbols, parseStyleValue, RULES, } from "./value.js";

package/dist/esm/parse.js

@@ -0,0 +1,138 @@
+import { parseDocument } from "yaml";
+import { authoredSpelling, liftSymbols } from "./value.js";
+/**
+ * The one lift every consumer shares. It is implemented in `./value.js`,
+ * beside the grammar it belongs to, and re-exported here because the parser
+ * is where a reader looks for it.
+ */
+export { liftSymbols } from "./value.js";
+/**
+ * Parse an anatomy document.
+ *
+ * Give it the YAML text — which is what design-system holds, one
+ * `ds:anatomyDsl` literal per block — and it is parsed here, with the
+ * `yaml` package's Document API; that is why `yaml` is a runtime dependency
+ * and not a devDependency. An already-parsed value is still accepted, for a
+ * caller that has one.
+ */
+export function parseAnatomyYAML(raw) {
+    const doc = (typeof raw === "string" ? parseDocument(raw).toJS() : raw);
+    if (doc === null || typeof doc !== "object" || doc.node === undefined) {
+        throw new Error("An anatomy document is a mapping with one `node` key");
+    }
+    return {
+        root: toNamedNode(doc.node),
+    };
+}
+function toNamedNode(raw) {
+    return {
+        type: "named",
+        uri: raw.uri,
+        ...(raw.projection ? { projection: toProjection(raw.projection) } : {}),
+        ...(raw.props ? { props: toProps(raw.props) } : {}),
+        ...(raw.styles ? { styles: toStyles(raw.styles) } : {}),
+        ...(raw.edges ? { edges: raw.edges.map(toEdge) } : {}),
+    };
+}
+function toNode(raw) {
+    if ("uri" in raw && raw.uri) {
+        return toNamedNode(raw);
+    }
+    if ("props" in raw) {
+        throw new Error("Props are only allowed on named nodes");
+    }
+    const anon = raw;
+    return {
+        type: "anonymous",
+        role: anon.role,
+        ...(anon.projection ? { projection: toProjection(anon.projection) } : {}),
+        ...(anon.styles ? { styles: toStyles(anon.styles) } : {}),
+        ...(anon.edges ? { edges: anon.edges.map(toEdge) } : {}),
+    };
+}
+function toProjection(raw) {
+    if (raw.on === undefined && raw.field === undefined) {
+        throw new Error("Projection must have at least one of on, field");
+    }
+    return {
+        ...(raw.on !== undefined ? { on: raw.on } : {}),
+        ...(raw.field !== undefined ? { field: raw.field } : {}),
+    };
+}
+function toStyles(raw) {
+    return Object.entries(raw).map(([rawKey, value]) => {
+        const [key, state, ...rest] = rawKey.split("@");
+        if (rest.length > 0) {
+            throw new Error(`Compound states are not yet supported: ${rawKey}`);
+        }
+        if (state === "") {
+            throw new Error(`Style key has an empty state: ${rawKey}`);
+        }
+        if (state === "default") {
+            throw new Error(`The unmarked key is the default state — drop "@default": ${rawKey}`);
+        }
+        return {
+            key: key,
+            // The authored spelling is kept verbatim as evidence; the symbols are
+            // lifted from it by the one lift every consumer shares (§4.1).
+            value: authoredSpelling(value),
+            symbols: liftSymbols(value, key),
+            ...(state !== undefined ? { state } : {}),
+        };
+    });
+}
+function toProps(raw) {
+    return Object.entries(raw).map(([name, value]) => ({
+        name,
+        value: String(value),
+    }));
+}
+function toEdge(raw) {
+    let target;
+    if (raw.switch) {
+        target = toSwitch(raw.switch);
+    }
+    else if (raw.node) {
+        target = toNode(raw.node);
+    }
+    else if (raw.uri) {
+        target = { type: "named", uri: raw.uri };
+    }
+    else {
+        throw new Error("Edge must have node, uri, or switch");
+    }
+    return {
+        target,
+        relation: toRelation(raw.relation),
+    };
+}
+function toSwitch(raw) {
+    return {
+        discriminator: raw.on,
+        cases: raw.cases.map(toSwitchCase),
+    };
+}
+function toSwitchCase(raw) {
+    if (raw.uri !== undefined) {
+        const node = { type: "named", uri: raw.uri };
+        return { value: raw.uri, node };
+    }
+    const node = toNode(raw.node);
+    const value = node.type === "named" ? node.uri : node.role;
+    return { value, node };
+}
+function toRelation(raw) {
+    return {
+        cardinality: raw.cardinality,
+        ...(raw.slotName ? { slotName: raw.slotName } : {}),
+        ...(raw.projection
+            ? { projection: toRelationProjection(raw.projection) }
+            : {}),
+    };
+}
+function toRelationProjection(raw) {
+    if (!raw.field) {
+        throw new Error("Relation projection requires a field");
+    }
+    return { field: raw.field };
+}