@cynodia/axiom-ui 0.7.0-alpha.1

package/dist/patterns/entity-list.js

@@ -0,0 +1,236 @@
+import { field, ref } from '@cynodia/axiom-core';
+import { definePattern } from '../pattern.js';
+import { actionOf, defaultListFields, entityOf, fieldOf, formatFor, isCollection, labelFor, memberEntityId, roleForAction, stateOf, } from '../inference.js';
+/** The expression that names the current row inside a `repeat`: the repeat node's own id. */
+export function rowRef(instance) {
+    return ref(`ui_${instance}_rows`.replace(/[^a-zA-Z0-9_]/g, '_'));
+}
+export function rowField(instance, fieldId) {
+    return field(rowRef(instance), fieldId);
+}
+export const entityList = definePattern({
+    name: 'entity-list',
+    version: '0.7.0',
+    purpose: 'Lists the instances of a collection, one row per member, with optional per-row actions.',
+    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' },
+    ],
+    check(declaration, { graph, instance }) {
+        const findings = [];
+        const state = stateOf(graph, declaration.source);
+        if (!state) {
+            return [
+                {
+                    code: 'SOURCE_NOT_A_STATE',
+                    message: `${String(declaration.source)} is not a state in this graph.`,
+                    severity: 'error',
+                    path: `${instance}.source`,
+                },
+            ];
+        }
+        if (!isCollection(state.valueType)) {
+            return [
+                {
+                    code: 'SOURCE_NOT_A_COLLECTION',
+                    message: `${state.name ?? String(declaration.source)} is not a collection, so it has no rows to list.`,
+                    severity: 'error',
+                    path: `${instance}.source`,
+                },
+            ];
+        }
+        const entityId = memberEntityId(state.valueType);
+        const entity = entityId ? entityOf(graph, entityId) : undefined;
+        if (!entity) {
+            return [
+                {
+                    code: 'SOURCE_NOT_ENTITIES',
+                    message: `${state.name ?? String(declaration.source)} holds primitives, not entity instances, so it has no fields to show.`,
+                    severity: 'error',
+                    path: `${instance}.source`,
+                },
+            ];
+        }
+        (declaration.fields ?? []).forEach((fieldId, index) => {
+            if (!fieldOf(entity, fieldId)) {
+                findings.push({
+                    code: 'FIELD_NOT_ON_ENTITY',
+                    message: `${String(fieldId)} is not a field of ${entity.name ?? String(entity.id)}.`,
+                    severity: 'error',
+                    path: `${instance}.fields[${index}]`,
+                });
+            }
+        });
+        if (!entity.identityFieldId && (declaration.rowActions ?? []).length > 0) {
+            findings.push({
+                code: 'NO_IDENTITY_FIELD',
+                message: `${entity.name ?? String(entity.id)} declares no identityFieldId, so a row action cannot address the row it belongs to.`,
+                severity: 'warning',
+                path: `${instance}.rowActions`,
+            });
+        }
+        return findings;
+    },
+    expand(declaration, context) {
+        const state = stateOf(context.graph, declaration.source);
+        if (!state) {
+            throw new Error(`entity-list ${declaration.instance}: source disappeared between check and expansion`);
+        }
+        const entity = entityOf(context.graph, memberEntityId(state.valueType));
+        if (!entity) {
+            throw new Error(`entity-list ${declaration.instance}: member entity disappeared between check and expansion`);
+        }
+        const fields = declaration.fields ?? defaultListFields(entity);
+        if (!declaration.fields) {
+            context.explain(`fields inferred from ${entity.name ?? String(entity.id)}: every field except the identity field ${String(entity.identityFieldId)}`);
+        }
+        // The repeat binds the current member to its own id, so a cell reads
+        // `field(ref(<repeat id>), <field id>)`. The id is derived from the instance, which is
+        // what lets `rowRef(instance)` be written by a caller before expansion has happened.
+        const rowsId = context.id('rows');
+        const cells = fields.map((fieldId, index) => {
+            const definition = fieldOf(entity, fieldId);
+            const format = declaration.formats?.[String(fieldId)] ?? (definition ? formatFor(definition.valueType) : undefined);
+            if (!declaration.formats?.[String(fieldId)] && format) {
+                context.explain(`${String(fieldId)} formatted as ${format.kind}, from its declared type`);
+            }
+            const label = definition ? labelFor(definition) : undefined;
+            return context.add({
+                id: context.id('cell', index),
+                kind: 'field-display',
+                source: ref(rowsId),
+                fieldId,
+                ...(label ? { label } : {}),
+                presentation: { ...(format ? { format } : {}) },
+            }, 'cell');
+        });
+        const rowChildren = [...cells, ...context.slot('rowExtra')];
+        const rowActions = (declaration.rowActions ?? []).map((actionId, index) => {
+            const action = actionOf(context.graph, actionId);
+            const uxRole = action ? roleForAction(action, index === 0 && !action.destructive) : 'secondary-action';
+            if (action?.destructive) {
+                context.explain(`${String(actionId)} placed in row actions as destructive because the action declares it`);
+            }
+            return context.add({
+                id: context.id('row_action', index),
+                kind: 'button',
+                label: action?.name ?? String(actionId),
+                actionId,
+                ...(declaration.rowArguments?.[String(actionId)]
+                    ? { arguments: declaration.rowArguments[String(actionId)] }
+                    : {}),
+                presentation: { uxRole },
+            }, 'row-action');
+        });
+        if (rowActions.length > 0) {
+            rowChildren.push(context.add({
+                id: context.id('row_actions'),
+                kind: 'container',
+                children: rowActions,
+                presentation: { uxRole: 'action-group', layout: { kind: 'horizontal', gap: 'small', align: 'center' } },
+            }, 'row-actions'));
+        }
+        const row = context.add({
+            id: context.id('row'),
+            kind: 'container',
+            children: rowChildren,
+            presentation: {
+                surface: 'base',
+                padding: { horizontal: 'medium', vertical: 'small' },
+                // Wide: a row reads across, table-like. Compact: it stacks into a record. Both are
+                // stated as intent; neither names a width.
+                layout: { kind: 'horizontal', gap: 'medium', align: 'center', justify: 'between' },
+                responsive: { compact: { layout: { kind: 'vertical', gap: 'xsmall' }, } },
+            },
+        }, 'row');
+        const emptyCaption = context.add({
+            id: context.id('empty_caption'),
+            kind: 'text',
+            value: declaration.emptyMessage ?? `No ${entity.name ?? 'records'} yet.`,
+            presentation: { textRole: 'body', headingLevel: 'none', emphasis: 'subtle' },
+        }, 'empty-caption');
+        const emptyChildren = [emptyCaption];
+        if (declaration.emptyAction !== undefined) {
+            const recovery = actionOf(context.graph, declaration.emptyAction);
+            emptyChildren.push(context.add({
+                id: context.id('empty_action'),
+                kind: 'button',
+                label: recovery?.name ?? String(declaration.emptyAction),
+                actionId: declaration.emptyAction,
+                ...(declaration.emptyActionArguments ? { arguments: declaration.emptyActionArguments } : {}),
+                presentation: { uxRole: 'primary-action' },
+            }, 'empty-action'));
+            context.explain('the empty state offers a recovery action, so it says what to do and not only that there is nothing');
+        }
+        // The empty state is a container even when it holds only a caption, so adding a recovery
+        // action later changes a declaration rather than the shape of the generated tree.
+        const empty = context.add({
+            id: context.id('empty'),
+            kind: 'container',
+            children: emptyChildren,
+            presentation: {
+                uxRole: 'empty-state',
+                padding: 'medium',
+                layout: { kind: 'vertical', gap: 'small', align: 'start' },
+            },
+        }, 'empty-state');
+        context.explain('an empty state is always generated: a collection may be empty and a blank region explains nothing');
+        const repeat = context.add({
+            id: rowsId,
+            kind: 'repeat',
+            // A collection state is never null in a validated graph, but a derived one can be;
+            // the coalesce is what keeps a legitimately absent collection from failing the render.
+            source: ref(declaration.source),
+            templateId: row,
+            emptyTemplateId: empty,
+            presentation: { layout: { kind: 'vertical', gap: 'xsmall' } },
+        }, 'rows');
+        return context.add({
+            id: context.id('root'),
+            kind: 'container',
+            name: state.name,
+            children: [repeat],
+            presentation: { layout: { kind: 'vertical', gap: 'small' } },
+        }, 'root');
+    },
+});

package/dist/patterns/metric-grid.d.ts

@@ -0,0 +1,31 @@
+import type { Expression, ValueFormat } from '@cynodia/axiom-core';
+import type { Emphasis } from '@cynodia/axiom-core';
+import type { PatternText } from '../pattern.js';
+/**
+ * Prominent summary values — the row of figures at the top of a dashboard.
+ *
+ * The caller supplies a label, a value expression and optionally an emphasis. Everything
+ * structural is the pattern's: the grid that reflows by available width rather than by
+ * breakpoint, the caption-above-figure pairing, the fact that a metric's label is a label and
+ * not a heading, and that the figure is drawn at display scale while staying outside the
+ * document outline.
+ */
+export interface MetricDeclaration {
+    /**
+     * The caption. Absent, and where `value` is a plain reference to a named state, the
+     * state's own `name` — because a measure the graph has already named does not need
+     * naming twice, and prose duplicated is prose that can disagree.
+     */
+    label?: PatternText;
+    value: Expression;
+    format?: ValueFormat;
+    emphasis?: Emphasis;
+    description?: PatternText;
+}
+export interface MetricGridDeclaration {
+    pattern: 'metric-grid';
+    instance: string;
+    metrics: MetricDeclaration[];
+}
+export declare const metricGrid: import("../pattern.js").PatternDefinition<MetricGridDeclaration>;
+//# sourceMappingURL=metric-grid.d.ts.map

package/dist/patterns/metric-grid.js

@@ -0,0 +1,107 @@
+import { definePattern, nameOf } from '../pattern.js';
+import { stateOf } from '../inference.js';
+/**
+ * The label a metric can be given without the author writing one.
+ *
+ * Only a plain `ref` to a state qualifies: the state has a name, and that name is the
+ * measure. Nothing is guessed from an id or from the shape of a computation — a label
+ * invented from an identifier is a guess presented as a fact.
+ */
+function inferredLabel(graph, metric) {
+    return metric.value.kind === 'ref' ? stateOf(graph, metric.value.targetId)?.name : undefined;
+}
+export const metricGrid = definePattern({
+    name: 'metric-grid',
+    version: '0.7.0',
+    purpose: 'A reflowing grid of prominent summary values.',
+    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' },
+    ],
+    check(declaration, { graph, instance }) {
+        const findings = [];
+        declaration.metrics.forEach((metric, index) => {
+            if (metric.label === undefined && inferredLabel(graph, metric) === undefined) {
+                findings.push({
+                    code: 'METRIC_LABEL_REQUIRED',
+                    message: 'A metric needs a label, and one can only be inferred when its value is a reference to a named state.',
+                    severity: 'error',
+                    path: `${instance}.metrics[${index}].label`,
+                });
+            }
+        });
+        return findings;
+    },
+    expand(declaration, context) {
+        const cells = declaration.metrics.map((metric, index) => {
+            const caption = metric.label ?? inferredLabel(context.graph, metric);
+            if (metric.label === undefined) {
+                context.explain(`metric ${index} labelled "${String(caption)}" from the name of the state it reads`);
+            }
+            const label = context.add({
+                id: context.id('label', index),
+                kind: 'text',
+                value: caption,
+                // A metric's caption is a label, never a heading: a dashboard of eight figures
+                // would otherwise put eight headings into the document outline.
+                presentation: { textRole: 'label', headingLevel: 'none', emphasis: 'subtle' },
+            }, 'metric-label');
+            const value = context.add({
+                id: context.id('value', index),
+                kind: 'text',
+                value: metric.value,
+                presentation: {
+                    textRole: 'display',
+                    headingLevel: 'none',
+                    ...(metric.emphasis ? { emphasis: metric.emphasis } : {}),
+                    ...(metric.format ? { format: metric.format } : {}),
+                },
+            }, 'metric-value');
+            const children = [label, value];
+            if (metric.description !== undefined) {
+                children.push(context.add({
+                    id: context.id('description', index),
+                    kind: 'text',
+                    value: metric.description,
+                    presentation: { textRole: 'caption', headingLevel: 'none', emphasis: 'subtle' },
+                }, 'metric-description'));
+            }
+            return context.add({
+                id: context.id('metric', index),
+                kind: 'container',
+                ...(nameOf(caption) ? { name: nameOf(caption) } : {}),
+                children,
+                presentation: {
+                    surface: 'raised',
+                    padding: 'medium',
+                    layout: { kind: 'vertical', gap: 'xsmall' },
+                },
+            }, 'metric');
+        });
+        context.explain(`${cells.length} metrics laid out as an adaptive grid: as many columns of at least medium width as fit`);
+        return context.add({
+            id: context.id('root'),
+            kind: 'container',
+            children: cells,
+            presentation: {
+                layout: { kind: 'grid', gap: 'medium', columns: { mode: 'adaptive', minimum: 'narrow' } },
+                // Stacking on a compact device is responsive *intent*; what width triggers it is
+                // the renderer's business and appears nowhere in the graph.
+                responsive: { compact: { layout: { kind: 'vertical', gap: 'small' } } },
+            },
+        }, 'root');
+    },
+});

package/dist/patterns/page.d.ts

@@ -0,0 +1,28 @@
+import type { PatternText } from '../pattern.js';
+/**
+ * A conventional application page: a header region carrying the title, description and the
+ * page-level actions, then a content region.
+ *
+ * What the caller does not write: the header container, the content container, the heading
+ * level, the landmark roles, the spacing between regions, or the decision that the page
+ * title is the document's level-1 heading. Those are the same on every page of every
+ * application, which is exactly what makes them the pattern's business rather than the
+ * author's.
+ */
+export interface PageDeclaration {
+    pattern: 'page';
+    instance: string;
+    /**
+     * The page heading. `string | Expression`, so a detail page can be titled by the record it
+     * is about — `field(find(products, …), name)` — rather than by a caption that is the same
+     * on every product.
+     */
+    title: PatternText;
+    description?: PatternText;
+    /** Placed in the header, to the trailing side of the title. */
+    actions?: unknown;
+    /** The page body, in order. */
+    content?: unknown;
+}
+export declare const page: import("../pattern.js").PatternDefinition<PageDeclaration>;
+//# sourceMappingURL=page.d.ts.map

package/dist/patterns/page.js

@@ -0,0 +1,104 @@
+import { definePattern, nameOf } from '../pattern.js';
+export const page = definePattern({
+    name: 'page',
+    version: '0.7.0',
+    purpose: 'A titled application page with a header region, page-level actions and a content region.',
+    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' },
+    ],
+    expand(declaration, context) {
+        const children = [];
+        const heading = context.add({
+            id: context.id('title'),
+            kind: 'text',
+            // Whatever the author gave: a caption, or an expression over the record on screen.
+            value: declaration.title,
+            // `title` is the type scale; level 1 is the document outline. They are separate
+            // decisions and the pattern makes both, because a page has exactly one of each.
+            presentation: { textRole: 'title', headingLevel: 1 },
+        }, 'title');
+        const headerChildren = [heading];
+        context.explain('page title rendered at text role "title" and heading level 1');
+        if (declaration.description !== undefined) {
+            headerChildren.push(context.add({
+                id: context.id('description'),
+                kind: 'text',
+                value: declaration.description,
+                presentation: { textRole: 'caption', headingLevel: 'none', emphasis: 'subtle' },
+            }, 'description'));
+        }
+        // The title and description are one block so the action group sits beside the pair
+        // rather than beside the title alone.
+        const titleBlock = context.add({
+            id: context.id('title_block'),
+            kind: 'container',
+            children: headerChildren,
+            presentation: { layout: { kind: 'vertical', gap: 'xsmall' } },
+        }, 'title-block');
+        const actions = context.slot('actions');
+        const headerBlocks = [titleBlock];
+        if (actions.length > 0) {
+            headerBlocks.push(context.add({
+                id: context.id('actions'),
+                kind: 'container',
+                children: actions,
+                presentation: { uxRole: 'action-group', layout: { kind: 'horizontal', gap: 'small', align: 'center' } },
+            }, 'actions'));
+            context.explain('page actions grouped in an action-group beside the title');
+        }
+        children.push(context.add({
+            id: context.id('header'),
+            kind: 'container',
+            children: headerBlocks,
+            presentation: {
+                uxRole: 'header-region',
+                layout: { kind: 'horizontal', justify: 'between', align: 'center', gap: 'medium', wrap: true },
+                // A header that cannot fit its actions beside the title stacks them rather than
+                // truncating either. Intent, not a breakpoint.
+                responsive: { compact: { layout: { kind: 'vertical', gap: 'small' }, } },
+            },
+        }, 'header'));
+        const content = context.slot('content');
+        if (content.length > 0) {
+            children.push(context.add({
+                id: context.id('content'),
+                kind: 'container',
+                children: content,
+                presentation: { uxRole: 'content-region', layout: { kind: 'vertical', gap: 'large' } },
+            }, 'content'));
+        }
+        if (typeof declaration.title !== 'string') {
+            context.explain('page title is an expression, so it follows the record the page is about');
+        }
+        return context.add({
+            id: context.id('root'),
+            kind: 'container',
+            ...(nameOf(declaration.title) ? { name: nameOf(declaration.title) } : {}),
+            children,
+            presentation: { layout: { kind: 'vertical', gap: 'large' }, padding: 'large' },
+        }, 'root');
+    },
+});

package/dist/queries.d.ts

@@ -0,0 +1,60 @@
+import type { ApplicationGraph, NodeId } from '@cynodia/axiom-core';
+import type { PatternDeclaration, ToolkitProvenance } from './pattern.js';
+import type { PatternExpansion, Toolkit } from './expand.js';
+/**
+ * Toolkit-aware queries, deliberately **not** part of `AgentAPI`.
+ *
+ * They live here for two reasons. The dependency direction forbids the other arrangement —
+ * `agent-api` knows only core, and a toolkit that core knew about would stop being a toolkit.
+ * And the separation is the point: canonical `AgentAPI` must answer every question about an
+ * expanded application without knowing a toolkit exists, or the abstraction is opaque. These
+ * are additive convenience, and an agent that never finds them loses nothing it needs.
+ *
+ * Everything here reads the graph. Only `getPatternExpansion` and `getPatternDeclaration`
+ * need the toolkit instance, because a declaration is not stored in the graph — which is
+ * itself the answer to "is the expanded graph enough": for semantics yes, for authoring
+ * history no.
+ */
+export interface ToolkitQueries {
+    /** Every pattern instance in the graph, from provenance alone. */
+    getPatternInstances(): Array<{
+        instance: string;
+        pattern: string;
+        nodeIds: NodeId[];
+    }>;
+    getPatternForNode(nodeId: NodeId): ToolkitProvenance | undefined;
+    getNodesForInstance(instance: string): NodeId[];
+    getInstancesOfPattern(pattern: string): string[];
+    /** Requires the toolkit that expanded it: the record is not in the graph. */
+    getPatternExpansion(instance: string): PatternExpansion | undefined;
+    getPatternDeclaration(instance: string): PatternDeclaration | undefined;
+    /** Why the pattern chose what it chose, if the expansion is still in memory. */
+    explainInstance(instance: string): string[];
+}
+export declare function createToolkitQueries(graph: ApplicationGraph, toolkit?: Toolkit): ToolkitQueries;
+/**
+ * Rewrites a canonical validation finding so it points at the declaration that caused it.
+ *
+ * Toolkit `check` catches what it can before expansion. Anything it cannot — a rule that only
+ * holds over the assembled graph — surfaces from `validateGraph` against a node the author
+ * never wrote. Provenance is what turns `ui_product_list_row_action_0 has no argument for
+ * param_product` into `product_list ▸ entity-list ▸ row-action`, which is the difference
+ * between a diagnostic an agent can act on and one it has to reverse-engineer.
+ */
+export interface MappedIssue {
+    code: string;
+    message: string;
+    nodeId?: NodeId;
+    /** `product_list.row-action`, when the node came from a pattern. */
+    declarationPath?: string;
+    pattern?: string;
+    instance?: string;
+    /** The full chain, outermost first, for a node from a nested pattern. */
+    ancestry?: string[];
+}
+export declare function mapIssuesToDeclarations(graph: ApplicationGraph, issues: readonly {
+    code: string;
+    message: string;
+    nodeId?: NodeId;
+}[]): MappedIssue[];
+//# sourceMappingURL=queries.d.ts.map

package/dist/queries.js

@@ -0,0 +1,53 @@
+import { provenanceOf } from './pattern.js';
+import { instancesOfPattern, nodesOfInstance } from './expand.js';
+export function createToolkitQueries(graph, toolkit) {
+    return {
+        getPatternInstances() {
+            const byInstance = new Map();
+            for (const node of graph.listNodes()) {
+                const provenance = provenanceOf(node);
+                if (!provenance) {
+                    continue;
+                }
+                const existing = byInstance.get(provenance.instance) ?? {
+                    instance: provenance.instance,
+                    pattern: provenance.pattern,
+                    nodeIds: [],
+                };
+                existing.nodeIds.push(node.id);
+                byInstance.set(provenance.instance, existing);
+            }
+            return [...byInstance.values()];
+        },
+        getPatternForNode: (nodeId) => {
+            const node = graph.getNode(nodeId);
+            return node ? provenanceOf(node) : undefined;
+        },
+        getNodesForInstance: (instance) => nodesOfInstance(graph, instance),
+        getInstancesOfPattern: (pattern) => instancesOfPattern(graph, pattern),
+        getPatternExpansion: (instance) => toolkit?.inspect(graph, instance),
+        getPatternDeclaration: (instance) => toolkit?.inspect(graph, instance)?.declaration,
+        explainInstance: (instance) => toolkit?.inspect(graph, instance)?.explanations ?? [],
+    };
+}
+export function mapIssuesToDeclarations(graph, issues) {
+    return issues.map((issue) => {
+        if (!issue.nodeId) {
+            return { code: issue.code, message: issue.message };
+        }
+        const node = graph.getNode(issue.nodeId);
+        const provenance = node ? provenanceOf(node) : undefined;
+        if (!provenance) {
+            return { code: issue.code, message: issue.message, nodeId: issue.nodeId };
+        }
+        return {
+            code: issue.code,
+            message: issue.message,
+            nodeId: issue.nodeId,
+            declarationPath: `${provenance.instance}.${provenance.part}`,
+            pattern: provenance.pattern,
+            instance: provenance.instance,
+            ...(provenance.ancestry ? { ancestry: provenance.ancestry } : {}),
+        };
+    });
+}

package/dist/toolkit.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The prototype toolkit: five patterns, deliberately.
+ *
+ * Adding a sixth because it would be convenient is how a pattern layer becomes a component
+ * catalogue, which is the outcome this research exists to avoid.
+ */
+export declare const axiomUi: import("./expand.js").Toolkit;
+//# sourceMappingURL=toolkit.d.ts.map

package/dist/toolkit.js

@@ -0,0 +1,19 @@
+import { createToolkit } from './expand.js';
+import { page } from './patterns/page.js';
+import { metricGrid } from './patterns/metric-grid.js';
+import { entityList } from './patterns/entity-list.js';
+import { entityForm } from './patterns/entity-form.js';
+import { actionBar } from './patterns/action-bar.js';
+/**
+ * The prototype toolkit: five patterns, deliberately.
+ *
+ * Adding a sixth because it would be convenient is how a pattern layer becomes a component
+ * catalogue, which is the outcome this research exists to avoid.
+ */
+export const axiomUi = createToolkit([
+    page,
+    metricGrid,
+    entityList,
+    entityForm,
+    actionBar,
+]);