@cynodia/axiom-ui 0.7.0-alpha.1

package/docs/OWNERSHIP.md

@@ -0,0 +1,75 @@
+# Ownership
+
+Who decides what a generated node contains, after expansion.
+
+Leaving this implicit makes "may I edit this node?" unanswerable, so every expansion records
+an answer.
+
+## Two modes
+
+| | `declaration` (default) | `graph` |
+| --- | --- | --- |
+| Source of truth | the pattern declaration | the expanded graph |
+| The graph is | a build artifact | the application |
+| Re-expansion | authoritative, overwrites | a mistake |
+| Editing a generated node | **drift** — reported, then lost on the next build | legitimate |
+| The declaration afterwards | still required | history |
+| Toolkit dependency | build-time | none after materializing |
+
+```ts
+axiomUi.expand(graph, declaration);                          // declaration-owned
+axiomUi.expand(graph, declaration, { ownership: 'graph' });  // graph-owned from the start
+materializePattern(graph, axiomUi.inspect(graph, 'products')!);  // hand over later
+```
+
+## Declaration-owned
+
+The default, because a toolkit is an authoring layer. The declaration is what you maintain;
+the graph is what the build produces from it.
+
+Editing a generated node here is not forbidden — nothing can forbid it — but it is **drift**,
+and the next expansion silently discards it. So drift is detected rather than ignored:
+
+```ts
+detectDrift(graph, axiomUi.inspect(graph, 'product_list')!);
+// [{ code: 'TOOLKIT_EXPANSION_DRIFT', nodeId: 'ui_product_list_row',
+//    property: 'children', expected: [...], actual: [...],
+//    message: 'ui_product_list_row.children differs from what entity-list generated' }]
+```
+
+It names the node and the property, not merely that something changed, because "your edit will
+be lost" is only actionable if it says which edit.
+
+### Resolving drift
+
+A `TOOLKIT_EXPANSION_DRIFT` finding has exactly **two** correct resolutions, and the property it
+names tells you which fits:
+
+1. **Change the declaration** so expansion produces what you edited. Right whenever a pattern
+   input, an option or a slot can express the change — which is most of the time, and it keeps
+   the declaration the single source of truth. Re-expand and `detectDrift` returns `[]`.
+2. **Materialize the instance**, taking ownership of the generated nodes. Right when the change
+   is something no input can express. After this the edit is legitimate, the declaration is
+   history, and the next build will not overwrite it.
+
+Reverting the edit is a third outcome but not a resolution: it discards the intent that caused
+the drift. What is never correct is leaving it — under `declaration` ownership the next
+expansion discards the edit without asking.
+
+## Graph-owned
+
+For an application that no longer wants a toolkit dependency, or one that has outgrown a
+pattern. `materializePattern` keeps every generated node exactly as it is and re-marks it, so
+nothing treats the declaration as authoritative again.
+
+There is no un-materialize. Recovering a declaration from an expanded graph is a different
+problem and is not attempted.
+
+## Which to choose
+
+Start with `declaration`. Materialize a specific instance when you need to diverge from what
+the pattern generates in a way no slot or option covers — that is a deliberate, recorded
+decision, and it is better than an edit that quietly disappears.
+
+A materialized application is an ordinary Axiom application with no toolkit involvement: it
+validates, compiles, executes and renders with the package uninstalled.

package/docs/PATTERN_AUTHORING.md

@@ -0,0 +1,71 @@
+# Authoring a pattern
+
+For a third party defining patterns outside `@cynodia/axiom-ui`. Requires **no changes to
+Axiom core, the runtime or any renderer**.
+
+```ts
+import { createToolkit, definePattern } from '@cynodia/axiom-ui';
+
+const inventoryStatusPanel = definePattern<{
+  pattern: 'inventory-status-panel';
+  instance: string;
+  threshold: number;
+}>({
+  name: 'inventory-status-panel',
+  version: '1.0.0',
+  purpose: 'A domain-specific panel reporting stock health.',
+  inputs: { threshold: { kind: 'token', required: true, purpose: 'Below this, stock counts as low.' } },
+  slots: [],
+  produces: ['container', 'text'],
+  expansion: [
+    { part: 'root', kind: 'container', role: 'the panel' },
+    { part: 'caption', kind: 'text', role: 'heading' },
+  ],
+  check(declaration, { graph, instance }) {
+    return declaration.threshold > 0
+      ? []
+      : [{ code: 'INVALID_THRESHOLD', message: 'A threshold must be positive.', severity: 'error', path: `${instance}.threshold` }];
+  },
+  expand(declaration, context) {
+    const caption = context.add({ id: context.id('caption'), kind: 'text', value: 'Stock health' }, 'caption');
+    context.explain(`low stock counted below ${declaration.threshold}`);
+    return context.add({ id: context.id('root'), kind: 'container', children: [caption] }, 'root');
+  },
+});
+
+export const hospitality = createToolkit([inventoryStatusPanel]);
+```
+
+## The two halves
+
+`inputs`, `slots`, `produces`, `purpose` and `version` are **data**, and the catalogue serves
+them to agents. `check` and `expand` are authoring-time TypeScript and never reach a graph, an
+IR or a runtime.
+
+That split is the whole portability story: the part an agent must discover is data; the part
+that only runs during a build is code. A pattern *definition* is not portable across
+languages. A pattern *declaration*, and everything it expands into, is.
+
+## Rules
+
+- **MUST** create every node through `context.add(node, part)`. It stamps provenance, records the node for drift detection and keeps ids deterministic. A `graph.addNode` inside `expand` is invisible to all three.
+- **MUST** derive ids with `context.id(part, index?)`. Never a counter, never a random value: expansion must be deterministic, and the same declaration must always produce the same graph.
+- **MUST NOT** create state, actions, constraints or transition constraints. A pattern composes existing behaviour. Business semantics belong to the application.
+- **MUST NOT** emit a colour, a length, a breakpoint, a CSS property or a renderer name. Emit roles, tokens and responsive intent; the theme decides how they look.
+- **MUST NOT** accept a callback as an input. No `renderRow(item) => …`. Take a slot instead.
+- **SHOULD** implement `check` for anything expansion assumes, so a mistake points at the declaration rather than at a generated node.
+- **SHOULD** call `context.explain(...)` whenever the pattern decides something the author did not write. This is what an agent reads back.
+- **SHOULD** declare `inferredWhenAbsent` on every optional input the pattern works out for itself. It is how an agent knows what it may leave out.
+
+## Versioning
+
+`version` is recorded in each generated node's provenance. It is what makes a stored expansion
+reproducible and an upgrade diffable:
+
+```ts
+diffPatternExpansion(expansion, nextToolkit, scratchGraph);
+// { added: [...], removed: [...], changed: [{ nodeId, property, from, to }] }
+```
+
+Change it whenever expansion output changes. An application should learn that an upgrade
+reshapes it from a diff, not from a rendering.

package/docs/PATTERN_CATALOG.json

@@ -0,0 +1,504 @@
+{
+  "catalog": "axiom.ui.catalog.v1",
+  "toolkit": "@cynodia/axiom-ui",
+  "version": "0.7.0",
+  "release": "0.7.0-alpha.1",
+  "description": "Semantic UI patterns for Axiom. A pattern is not a component: it expands, at authoring time, into ordinary Axiom UI nodes and has no runtime existence. Declare the UX concept; the expansion is explicit, inspectable application semantics.",
+  "ownership": {
+    "default": "declaration",
+    "values": {
+      "declaration": "The pattern declaration is the source of truth. Re-expansion is authoritative and editing a generated node is drift.",
+      "graph": "The expanded graph is the source of truth. The declaration is history and edits are legitimate."
+    }
+  },
+  "reading": {
+    "inputs": "Every declaration key, its kind, whether it is required, and what the pattern does with it.",
+    "inferred": "What the pattern works out for itself when an input is absent, and from what.",
+    "expansion": "The generated tree, part by part: the canonical node kind each part is, and where it sits. Describing only inputs was not enough — an agent composing against a generated tree needs its shape.",
+    "generatedIdFormat": "How to address a generated node before expansion has happened.",
+    "slots": "Where caller-supplied semantic content is placed. Slot content is node ids or nested declarations, never markup."
+  },
+  "patterns": [
+    {
+      "name": "action-bar",
+      "purpose": "A row of action controls whose emphasis is inferred from the actions themselves.",
+      "required": [
+        "actions"
+      ],
+      "optional": [
+        "primary",
+        "labels",
+        "arguments",
+        "alignment"
+      ],
+      "inputs": {
+        "actions": {
+          "kind": "action-list",
+          "required": true,
+          "purpose": "The actions to expose, in order."
+        },
+        "primary": {
+          "kind": "action",
+          "required": false,
+          "purpose": "Which action is the primary one.",
+          "inferredWhenAbsent": "The first action that is not destructive."
+        },
+        "labels": {
+          "kind": "text",
+          "required": false,
+          "purpose": "Override a control’s label.",
+          "inferredWhenAbsent": "The action’s own name."
+        },
+        "arguments": {
+          "kind": "nodes",
+          "required": false,
+          "purpose": "Arguments per action, keyed by action parameter id."
+        },
+        "alignment": {
+          "kind": "token",
+          "required": false,
+          "purpose": "Where the group sits along its axis.",
+          "inferredWhenAbsent": "start"
+        }
+      },
+      "slots": [],
+      "produces": [
+        "container",
+        "button"
+      ],
+      "expansion": [
+        {
+          "part": "root",
+          "kind": "container",
+          "role": "the action-group"
+        },
+        {
+          "part": "button",
+          "kind": "button",
+          "role": "one per action, emphasis from the action"
+        }
+      ],
+      "generatedIdFormat": "ui_<instance>_<part>, or ui_<instance>_<part>_<index> for a repeated part",
+      "inferred": {
+        "primary": "The first action that is not destructive.",
+        "labels": "The action’s own name.",
+        "alignment": "start"
+      }
+    },
+    {
+      "name": "entity-form",
+      "purpose": "A form that creates a record in a draft state or edits an existing one addressed by expression, with labels, controls, required markers and a submit action inferred from the graph.",
+      "required": [
+        "submit"
+      ],
+      "optional": [
+        "draft",
+        "target",
+        "options",
+        "mode",
+        "fields",
+        "submitArguments",
+        "submitLabel",
+        "title",
+        "titleLevel",
+        "description",
+        "secondaryActions"
+      ],
+      "inputs": {
+        "draft": {
+          "kind": "state",
+          "required": false,
+          "purpose": "Create mode: the draft state the controls write into. Its entity supplies every field’s label, control and required status.",
+          "inferredWhenAbsent": "Required unless `target` is given; exactly one of the two is."
+        },
+        "target": {
+          "kind": "nodes",
+          "required": false,
+          "purpose": "Edit mode: { state, identity } addressing an existing collection member — identity is an expression, usually a route parameter.",
+          "inferredWhenAbsent": "Required unless `draft` is given; exactly one of the two is."
+        },
+        "options": {
+          "kind": "nodes",
+          "required": false,
+          "purpose": "A canonical InputOptionsSource per field id, for a field whose value identifies another record.",
+          "inferredWhenAbsent": "A field with no options source uses the control its declared type implies."
+        },
+        "submit": {
+          "kind": "action",
+          "required": true,
+          "purpose": "The action the form submits."
+        },
+        "mode": {
+          "kind": "token",
+          "required": false,
+          "purpose": "\"create\" offers the identity field; \"edit\" omits it, because an identity is not editable.",
+          "inferredWhenAbsent": "edit when `target` is given, create when `draft` is. Declaring it is only needed to edit through a draft state."
+        },
+        "fields": {
+          "kind": "field-list",
+          "required": false,
+          "purpose": "Which fields to edit, in order.",
+          "inferredWhenAbsent": "Every field of the entity, in declaration order, identity included — omitting a required field would produce a form that can never submit."
+        },
+        "submitArguments": {
+          "kind": "nodes",
+          "required": false,
+          "purpose": "Arguments for the submit action."
+        },
+        "submitLabel": {
+          "kind": "text",
+          "required": false,
+          "purpose": "The submit control’s label.",
+          "inferredWhenAbsent": "The action’s own name."
+        },
+        "title": {
+          "kind": "text",
+          "required": false,
+          "purpose": "A heading above the form."
+        },
+        "titleLevel": {
+          "kind": "token",
+          "required": false,
+          "purpose": "The title’s document-outline level.",
+          "inferredWhenAbsent": "2 — the level below a page title, so a page and its form do not skip a level."
+        },
+        "description": {
+          "kind": "text",
+          "required": false,
+          "purpose": "A caption under the heading."
+        },
+        "secondaryActions": {
+          "kind": "slot",
+          "required": false,
+          "purpose": "Controls placed beside the submit button."
+        }
+      },
+      "slots": [
+        "secondaryActions"
+      ],
+      "produces": [
+        "form",
+        "input",
+        "button",
+        "container",
+        "text",
+        "diagnostic"
+      ],
+      "expansion": [
+        {
+          "part": "root",
+          "kind": "form",
+          "role": "the form; submitButtonId is the generated submit, and target reads the record being edited"
+        },
+        {
+          "part": "title",
+          "kind": "text",
+          "role": "optional heading, level 2"
+        },
+        {
+          "part": "description",
+          "kind": "text",
+          "role": "optional caption"
+        },
+        {
+          "part": "input",
+          "kind": "input",
+          "role": "one per field, in entity declaration order; bound to the draft field or to the addressed member’s field"
+        },
+        {
+          "part": "diagnostic",
+          "kind": "diagnostic",
+          "role": "where a refusal of the submit action appears"
+        },
+        {
+          "part": "actions",
+          "kind": "container",
+          "role": "action-group holding submit and the secondaryActions slot"
+        },
+        {
+          "part": "submit",
+          "kind": "button",
+          "role": "the primary action"
+        }
+      ],
+      "generatedIdFormat": "ui_<instance>_<part>, or ui_<instance>_<part>_<index> for a repeated part",
+      "inferred": {
+        "draft": "Required unless `target` is given; exactly one of the two is.",
+        "target": "Required unless `draft` is given; exactly one of the two is.",
+        "options": "A field with no options source uses the control its declared type implies.",
+        "mode": "edit when `target` is given, create when `draft` is. Declaring it is only needed to edit through a draft state.",
+        "fields": "Every field of the entity, in declaration order, identity included — omitting a required field would produce a form that can never submit.",
+        "submitLabel": "The action’s own name.",
+        "titleLevel": "2 — the level below a page title, so a page and its form do not skip a level."
+      }
+    },
+    {
+      "name": "entity-list",
+      "purpose": "Lists the instances of a collection, one row per member, with optional per-row actions.",
+      "required": [
+        "source"
+      ],
+      "optional": [
+        "fields",
+        "formats",
+        "rowActions",
+        "rowArguments",
+        "emptyMessage",
+        "emptyAction",
+        "emptyActionArguments",
+        "rowExtra"
+      ],
+      "inputs": {
+        "source": {
+          "kind": "state",
+          "required": true,
+          "purpose": "The collection state to list."
+        },
+        "fields": {
+          "kind": "field-list",
+          "required": false,
+          "purpose": "Which fields to display, in order.",
+          "inferredWhenAbsent": "Every field of the member entity except its identity field."
+        },
+        "formats": {
+          "kind": "nodes",
+          "required": false,
+          "purpose": "Value format per field, where the declared type cannot imply one.",
+          "inferredWhenAbsent": "number, boolean, date and datetime from the field’s type; currency and percentage are never guessed."
+        },
+        "rowActions": {
+          "kind": "action-list",
+          "required": false,
+          "purpose": "Actions offered on each row."
+        },
+        "rowArguments": {
+          "kind": "nodes",
+          "required": false,
+          "purpose": "Arguments per row action, evaluated in the row scope."
+        },
+        "emptyMessage": {
+          "kind": "text",
+          "required": false,
+          "purpose": "What the empty state says.",
+          "inferredWhenAbsent": "An empty state is still generated, with a generic caption."
+        },
+        "emptyAction": {
+          "kind": "action",
+          "required": false,
+          "purpose": "An action offered from the empty state, so it says what to do about it.",
+          "inferredWhenAbsent": "The empty state is a caption only, and validateGraph warns that it offers no recovery."
+        },
+        "emptyActionArguments": {
+          "kind": "nodes",
+          "required": false,
+          "purpose": "Arguments for the empty-state action."
+        },
+        "rowExtra": {
+          "kind": "slot",
+          "required": false,
+          "purpose": "Extra semantic content inside each row."
+        }
+      },
+      "slots": [
+        "rowExtra"
+      ],
+      "produces": [
+        "container",
+        "repeat",
+        "field-display",
+        "button",
+        "text"
+      ],
+      "expansion": [
+        {
+          "part": "root",
+          "kind": "container",
+          "role": "wraps the list"
+        },
+        {
+          "part": "rows",
+          "kind": "repeat",
+          "role": "the repeat; ref this id to address the current row"
+        },
+        {
+          "part": "row",
+          "kind": "container",
+          "role": "one row, horizontal when wide and stacked when compact"
+        },
+        {
+          "part": "cell",
+          "kind": "field-display",
+          "role": "one per field, in order"
+        },
+        {
+          "part": "row-actions",
+          "kind": "container",
+          "role": "action-group at the end of the row"
+        },
+        {
+          "part": "row-action",
+          "kind": "button",
+          "role": "one per row action"
+        },
+        {
+          "part": "empty-state",
+          "kind": "container",
+          "role": "shown when the collection is empty"
+        },
+        {
+          "part": "empty-caption",
+          "kind": "text",
+          "role": "what the empty state says"
+        },
+        {
+          "part": "empty-action",
+          "kind": "button",
+          "role": "the recovery action, when one is given"
+        }
+      ],
+      "generatedIdFormat": "ui_<instance>_<part>, or ui_<instance>_<part>_<index> for a repeated part",
+      "inferred": {
+        "fields": "Every field of the member entity except its identity field.",
+        "formats": "number, boolean, date and datetime from the field’s type; currency and percentage are never guessed.",
+        "emptyMessage": "An empty state is still generated, with a generic caption.",
+        "emptyAction": "The empty state is a caption only, and validateGraph warns that it offers no recovery."
+      }
+    },
+    {
+      "name": "metric-grid",
+      "purpose": "A reflowing grid of prominent summary values.",
+      "required": [
+        "metrics"
+      ],
+      "optional": [],
+      "inputs": {
+        "metrics": {
+          "kind": "nodes",
+          "required": true,
+          "purpose": "Each metric: a value expression, and optionally a label, format, emphasis and description.",
+          "inferredWhenAbsent": "A metric label is inferred from the name of the state its value refers to; a label is required only where the value is not a plain state reference."
+        }
+      },
+      "slots": [],
+      "produces": [
+        "container",
+        "text"
+      ],
+      "expansion": [
+        {
+          "part": "root",
+          "kind": "container",
+          "role": "adaptive grid of metrics"
+        },
+        {
+          "part": "metric",
+          "kind": "container",
+          "role": "one raised cell per metric"
+        },
+        {
+          "part": "metric-label",
+          "kind": "text",
+          "role": "the caption, a label and not a heading"
+        },
+        {
+          "part": "metric-value",
+          "kind": "text",
+          "role": "the figure, display scale, outside the outline"
+        },
+        {
+          "part": "metric-description",
+          "kind": "text",
+          "role": "optional caption under the figure"
+        }
+      ],
+      "generatedIdFormat": "ui_<instance>_<part>, or ui_<instance>_<part>_<index> for a repeated part",
+      "inferred": {
+        "metrics": "A metric label is inferred from the name of the state its value refers to; a label is required only where the value is not a plain state reference."
+      }
+    },
+    {
+      "name": "page",
+      "purpose": "A titled application page with a header region, page-level actions and a content region.",
+      "required": [
+        "title"
+      ],
+      "optional": [
+        "description",
+        "actions",
+        "content"
+      ],
+      "inputs": {
+        "title": {
+          "kind": "text",
+          "required": true,
+          "purpose": "The page heading, and the document’s level-1 heading. A string, or an expression for a title that names the record the page is about."
+        },
+        "description": {
+          "kind": "text",
+          "required": false,
+          "purpose": "A caption under the title. A string or an expression."
+        },
+        "actions": {
+          "kind": "slot",
+          "required": false,
+          "purpose": "Page-level controls, placed in the header.",
+          "inferredWhenAbsent": "No action group is generated."
+        },
+        "content": {
+          "kind": "slot",
+          "required": false,
+          "purpose": "The page body, in the order given."
+        }
+      },
+      "slots": [
+        "actions",
+        "content"
+      ],
+      "produces": [
+        "container",
+        "text"
+      ],
+      "expansion": [
+        {
+          "part": "root",
+          "kind": "container",
+          "role": "the page, padded and vertical"
+        },
+        {
+          "part": "header",
+          "kind": "container",
+          "role": "header-region landmark"
+        },
+        {
+          "part": "title-block",
+          "kind": "container",
+          "role": "title and description"
+        },
+        {
+          "part": "title",
+          "kind": "text",
+          "role": "the h1"
+        },
+        {
+          "part": "description",
+          "kind": "text",
+          "role": "caption under the title"
+        },
+        {
+          "part": "actions",
+          "kind": "container",
+          "role": "action-group beside the title, from the actions slot"
+        },
+        {
+          "part": "content",
+          "kind": "container",
+          "role": "content-region landmark, holding the content slot"
+        }
+      ],
+      "generatedIdFormat": "ui_<instance>_<part>, or ui_<instance>_<part>_<index> for a repeated part",
+      "inferred": {
+        "actions": "No action group is generated."
+      }
+    }
+  ]
+}