@quillmark/svelte 0.10.1 → 0.12.0

package/dist/visual/structure.d.ts

@@ -1,6 +1,9 @@
-import type { QuillCardSchema, QuillFieldSchema, ResolvedField, Resolved } from '@quillmark/wasm';
+import { type PathStep, type PayloadItem, type QuillCardSchema, type QuillFieldSchema, type ResolvedField, type Resolved } from '@quillmark/wasm';
 /** The control a field type maps to (VISUAL_EDITOR §"Structure mirrors the schema"). */
-export type ControlKind = 'prose' | 'text' | 'enum' | 'variant' | 'number' | 'boolean' | 'date' | 'array' | 'object';
+export type ControlKind = 'prose' | 'text' | 'enum' | 'variant' | 'number' | 'boolean' | 'date' | 'array' | 'object' | 'matrix';
+/** The container controls: the ones a nested address walks into and a deep
+ *  diagnostic routes through. */
+export declare function isContainer(kind: ControlKind): boolean;
 /** One field, projected: its schema, the control it renders as, and its layout hints. */
 export interface FieldModel {
     name: string;
@@ -148,9 +151,90 @@ export declare function resolveBodyGhost(resolvedDefault: string | undefined, cu
  * An array's element control is this over `items`: a missing `items` is a text
  * element. */
 export declare function controlKind(f: QuillFieldSchema): ControlKind;
-/** The discriminant cell of a variant container (`VARIANT_DISCRIMINANT_KEY` upstream,
- *  which the boundary does not export). Reserved: no variant may declare it. */
-export declare const VARIANT_DISCRIMINANT = "value";
+/** The discriminant cell of a variant container, off the boundary's own constant: it
+ *  crosses inside untyped container data with no type to read it off, so a literal here
+ *  would be a second spelling of a reserved key. No variant may declare it. */
+export declare const VARIANT_DISCRIMINANT: "value";
+/** The tick cell of a matrix member, the second reserved key beside the discriminant.
+ *  The boundary synthesizes it on every member and exports no constant for it, so this
+ *  is where the package spells it once (canon `SCHEMAS.md` §Matrix). */
+export declare const MATRIX_HELD = "held";
+/** One member of the roster: its id and its title. */
+export interface MatrixMember {
+    id: string;
+    title: string;
+}
+/** The roster's members, in declaration order. Own keys only: a schema map is indexed
+ *  by a document-supplied id, and `'toString' in members` is true of every roster. */
+export declare function matrixMembers(roster: Record<string, string> | undefined): MatrixMember[];
+/** A member's stored payload, off the sparse map by own key: a document key can be
+ *  spelled `constructor`. */
+export declare function memberValue(map: Record<string, unknown> | undefined, id: string): unknown;
+/**
+ * Whether a stored member is held. A bare scalar is the tick and a mapping is the member
+ * object, whose `held` cell resolves as every absent cell does, to its `default:` of
+ * `false` (canon `SCHEMAS.md` §Matrix): an absent key is unheld, a bare `true` is held,
+ * and a member object is held only where its `held` cell says so. The spellings the
+ * engine coerces to false — `false`, `0`, `"false"`, `null` — read false here; every other
+ * present scalar reads held, so a document the engine would refuse still draws the tick
+ * its spelling claims.
+ */
+export declare function matrixHeld(stored: unknown): boolean;
+/** A member's columns: the member object with its `held` cell taken out, `{}` for the
+ *  bare and absent spellings. What the columns subform takes as its value. */
+export declare function matrixColumns(stored: unknown): Record<string, unknown>;
+/**
+ * The map after one member moves: `next` written under `id`, or the key dropped where
+ * `next` is `undefined`; a map left holding nothing is an unset field. Every other
+ * member rides through in the spelling the document had, so a stored `cyber_200: true`
+ * stays `true` while its neighbour is edited.
+ */
+export declare function commitMember(map: Record<string, unknown> | undefined, id: string, next: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+/**
+ * The member a tick or an edit writes. Held with columns is the member object with an
+ * explicit `held: true`; unheld keeps the columns under `held: false`, so tick, type,
+ * untick, retick loses nothing; unheld with no columns is `undefined`, the key dropped.
+ * Which columns are blank is the engine's rule and not restated here: a column control
+ * that clears drops its key (`ObjectField`), so a member emptied by hand arrives with no
+ * columns and only then leaves the map.
+ */
+export declare function memberWrite(held: boolean, columns: Record<string, unknown>): Record<string, unknown> | undefined;
+/** The `object` a matrix member desugars to, for the schema walk: `held` beside the
+ *  declared columns. Composed here because the boundary serializes the roster alone. */
+export declare function matrixMemberSchema(matrix: QuillFieldSchema): QuillFieldSchema;
+/** Whether `id` is on the roster. */
+export declare function matrixDeclares(matrix: QuillFieldSchema, id: string): boolean;
+/**
+ * The schema at `steps` under `field`, or `undefined` where the schema declares no such
+ * place: an index under an `array`, a key under an `object`'s properties, a member id
+ * under a `matrix` and a key under that member, a cell of any world (or the
+ * discriminant) under a variant-bearing `enum`. The editor's copy of the boundary's
+ * `schema_at`, held here because the landing lane checks an address against the schema
+ * before it asks the mounted tree for it (VISUAL_EDITOR §Surface).
+ */
+export declare function schemaAt(field: QuillFieldSchema, steps: readonly PathStep[]): QuillFieldSchema | undefined;
+/** Whether a cell is one line tall by declaration: the shape a table column and a row
+ *  summary can hold. A `plaintext` leaf is inline at the codec whatever it declares. */
+export declare function shortCell(sub: QuillFieldSchema): boolean;
+/**
+ * A collapsed row's own words: `items.ui.title` interpolated with the row's values
+ * where the schema declares one, else the first short text cell in declaration order
+ * — a `string`, or an inline `richtext` / `plaintext` — read through {@link titleText};
+ * `undefined` while the row has nothing to say for itself. `title` sits on `items.ui`,
+ * describing a row, where `layout` sits on the array's own `ui`, describing the array.
+ */
+export declare function rowSummary(items: QuillFieldSchema | undefined, row: unknown): string | undefined;
+/** How an `array` draws its elements. */
+export type ArrayLayout = 'list' | 'table';
+/**
+ * The layout an array takes: `'table'` where the array's own `ui.layout` asks for it
+ * and every cell of the row is short (a block prose cell declines it, at load width and
+ * every width after), else `'list'`. That every column is a leaf is the loader's
+ * contract (`quill::table_column_not_flat`); whether a leaf fits a cell is the surface's
+ * answer (canon `SCHEMAS.md`): a table composes by position, so a row that would stack
+ * inside a cell is not one.
+ */
+export declare function arrayLayout(field: QuillFieldSchema): ArrayLayout;
 /**
  * Which world's cells to draw: the authored discriminant when the container carries
  * one, else the ghosted default's member — an unset field renders its `default:`, so a
@@ -170,9 +254,9 @@ export declare function variantCells(schema: QuillFieldSchema, member: string |
 export declare function commitDiscriminant(value: Record<string, unknown> | undefined, member: string | undefined): Record<string, unknown> | undefined;
 /**
  * Whether the schema obliges a cell: `default:`'s absence, which is the whole of the
- * obligation (DOCUMENT_MODEL). A typed dictionary is exempt — a namespace declares no
- * `default:` at all, and `validate` anchors obligation on the leaves under it, so
- * reading one off the container would mark every subform required.
+ * obligation (DOCUMENT_MODEL). A typed dictionary and a matrix are exempt — a namespace
+ * declares no `default:` at all, and `validate` anchors obligation on the leaves under
+ * it, so reading one off the container would mark every subform required.
  */
 export declare function obliged(schema: QuillFieldSchema): boolean;
 /** `foo_bar` → `Foo bar`: the label fallback when a field declares no `ui.title`. */
@@ -233,8 +317,17 @@ export interface PlacedField {
  * Pure, and stays pure: no width, no measurement, nothing to re-derive on resize.
  */
 export declare function placeFields(fields: FieldModel[]): PlacedField[];
+/** A card's field values by key, off its payload items. */
+export declare function fieldValues(items: readonly PayloadItem[]): Record<string, unknown>;
 /** Interpolate a `{field}` card-title template against live field values. */
 export declare function interpolateTitle(template: string, values: Record<string, unknown>): string;
+/** A field value as title text. A parsed field rests as the authored string and a
+ *  committed one as `Content`, whose `text` is the same words; a scalar reads as
+ *  itself; a variant container reads as its discriminant member, the one cell of it
+ *  that names the world; any other container as nothing. */
+export declare function titleText(v: unknown): string;
+/** The field names a `{field}` title reads. */
+export declare function titleFields(template: string | undefined): string[];
 /**
  * Resolve a card instance's header title: the per-instance `$ext.editor.title`
  * override wins; else the schema `ui.title` (literal or `{field}` template

package/dist/visual/structure.js

@@ -1,3 +1,15 @@
+// The schema × payload join, done by the editor (VISUAL_EDITOR §Structure). Pure
+// functions only (no runes, no Document reads) so the ordering, control
+// dispatch, group layout, title interpolation, and session-identity bookkeeping
+// are unit-testable in isolation (tests/visual/structure.test.ts). The reactive
+// orchestration (revision counter, live doc reads) lives in VisualEditor.svelte;
+// this module is the projection math it feeds.
+import { VARIANT_DISCRIMINANT_KEY } from '@quillmark/wasm';
+/** The container controls: the ones a nested address walks into and a deep
+ *  diagnostic routes through. */
+export function isContainer(kind) {
+    return kind === 'array' || kind === 'object' || kind === 'variant' || kind === 'matrix';
+}
 /**
  * A card's resolved rows keyed by field name: the provenance channel parallel to
  * {@link CardModel.values}. `resolve` returns rows in declaration order; the
@@ -72,13 +84,208 @@ export function controlKind(f) {
             return 'array';
         case 'object':
             return 'object';
+        case 'matrix':
+            return 'matrix';
         default:
             return 'text';
     }
 }
-/** The discriminant cell of a variant container (`VARIANT_DISCRIMINANT_KEY` upstream,
- *  which the boundary does not export). Reserved: no variant may declare it. */
-export const VARIANT_DISCRIMINANT = 'value';
+/** The discriminant cell of a variant container, off the boundary's own constant: it
+ *  crosses inside untyped container data with no type to read it off, so a literal here
+ *  would be a second spelling of a reserved key. No variant may declare it. */
+export const VARIANT_DISCRIMINANT = VARIANT_DISCRIMINANT_KEY;
+/** The tick cell of a matrix member, the second reserved key beside the discriminant.
+ *  The boundary synthesizes it on every member and exports no constant for it, so this
+ *  is where the package spells it once (canon `SCHEMAS.md` §Matrix). */
+export const MATRIX_HELD = 'held';
+/** The roster's members, in declaration order. Own keys only: a schema map is indexed
+ *  by a document-supplied id, and `'toString' in members` is true of every roster. */
+export function matrixMembers(roster) {
+    return roster ? Object.keys(roster).map((id) => ({ id, title: roster[id] })) : [];
+}
+/** A member's stored payload, off the sparse map by own key: a document key can be
+ *  spelled `constructor`. */
+export function memberValue(map, id) {
+    return map && Object.hasOwn(map, id) ? map[id] : undefined;
+}
+/**
+ * Whether a stored member is held. A bare scalar is the tick and a mapping is the member
+ * object, whose `held` cell resolves as every absent cell does, to its `default:` of
+ * `false` (canon `SCHEMAS.md` §Matrix): an absent key is unheld, a bare `true` is held,
+ * and a member object is held only where its `held` cell says so. The spellings the
+ * engine coerces to false — `false`, `0`, `"false"`, `null` — read false here; every other
+ * present scalar reads held, so a document the engine would refuse still draws the tick
+ * its spelling claims.
+ */
+export function matrixHeld(stored) {
+    if (typeof stored === 'object' && stored !== null)
+        return (Object.hasOwn(stored, MATRIX_HELD) && tickOf(stored[MATRIX_HELD]));
+    return tickOf(stored);
+}
+/** A tick's scalar reading: absent and the engine's false spellings unheld, the rest held. */
+function tickOf(v) {
+    if (v === undefined || v === null)
+        return false;
+    if (typeof v === 'boolean')
+        return v;
+    if (typeof v === 'number')
+        return v !== 0;
+    if (typeof v === 'string')
+        return v !== 'false';
+    return true;
+}
+/** A member's columns: the member object with its `held` cell taken out, `{}` for the
+ *  bare and absent spellings. What the columns subform takes as its value. */
+export function matrixColumns(stored) {
+    if (typeof stored !== 'object' || stored === null || Array.isArray(stored))
+        return {};
+    const rest = { ...stored };
+    delete rest[MATRIX_HELD];
+    return rest;
+}
+/**
+ * The map after one member moves: `next` written under `id`, or the key dropped where
+ * `next` is `undefined`; a map left holding nothing is an unset field. Every other
+ * member rides through in the spelling the document had, so a stored `cyber_200: true`
+ * stays `true` while its neighbour is edited.
+ */
+export function commitMember(map, id, next) {
+    const out = { ...(map ?? {}) };
+    if (next === undefined)
+        delete out[id];
+    else
+        out[id] = next;
+    return Object.keys(out).length ? out : undefined;
+}
+/**
+ * The member a tick or an edit writes. Held with columns is the member object with an
+ * explicit `held: true`; unheld keeps the columns under `held: false`, so tick, type,
+ * untick, retick loses nothing; unheld with no columns is `undefined`, the key dropped.
+ * Which columns are blank is the engine's rule and not restated here: a column control
+ * that clears drops its key (`ObjectField`), so a member emptied by hand arrives with no
+ * columns and only then leaves the map.
+ */
+export function memberWrite(held, columns) {
+    if (!held && Object.keys(columns).length === 0)
+        return undefined;
+    return { [MATRIX_HELD]: held, ...columns };
+}
+/** The `object` a matrix member desugars to, for the schema walk: `held` beside the
+ *  declared columns. Composed here because the boundary serializes the roster alone. */
+export function matrixMemberSchema(matrix) {
+    return {
+        type: 'object',
+        properties: {
+            [MATRIX_HELD]: { type: 'boolean', default: false },
+            ...(matrix.properties ?? {})
+        }
+    };
+}
+/** Whether `id` is on the roster. */
+export function matrixDeclares(matrix, id) {
+    return matrix.members != null && Object.hasOwn(matrix.members, id);
+}
+// ── The schema walk ──────────────────────────────────────────────────────────
+/**
+ * The schema at `steps` under `field`, or `undefined` where the schema declares no such
+ * place: an index under an `array`, a key under an `object`'s properties, a member id
+ * under a `matrix` and a key under that member, a cell of any world (or the
+ * discriminant) under a variant-bearing `enum`. The editor's copy of the boundary's
+ * `schema_at`, held here because the landing lane checks an address against the schema
+ * before it asks the mounted tree for it (VISUAL_EDITOR §Surface).
+ */
+export function schemaAt(field, steps) {
+    let cursor = field;
+    for (const step of steps) {
+        if (!cursor)
+            return undefined;
+        cursor = stepInto(cursor, step);
+    }
+    return cursor;
+}
+/** What an array declaring no `items` holds, the walk's copy of the element control
+ *  {@link controlKind} names for one: a text element, so an index into such an array is
+ *  a place and not a refusal. */
+const UNDECLARED_ELEMENT = { type: 'string' };
+function stepInto(schema, step) {
+    switch (controlKind(schema)) {
+        case 'array':
+            return typeof step === 'number' ? (schema.items ?? UNDECLARED_ELEMENT) : undefined;
+        case 'object':
+            return typeof step === 'string' && Object.hasOwn(schema.properties ?? {}, step)
+                ? schema.properties[step]
+                : undefined;
+        case 'matrix':
+            return typeof step === 'string' && matrixDeclares(schema, step)
+                ? matrixMemberSchema(schema)
+                : undefined;
+        case 'variant': {
+            if (typeof step !== 'string')
+                return undefined;
+            if (step === VARIANT_DISCRIMINANT)
+                return { type: 'enum', values: schema.values };
+            // Which world is live is a value-time fact, so the walk unions the worlds, as
+            // the boundary's does.
+            for (const cells of Object.values(schema.variants ?? {}))
+                if (Object.hasOwn(cells, step))
+                    return cells[step];
+            return undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+// ── Row summaries and layouts ────────────────────────────────────────────────
+/** Whether a cell is one line tall by declaration: the shape a table column and a row
+ *  summary can hold. A `plaintext` leaf is inline at the codec whatever it declares. */
+export function shortCell(sub) {
+    const kind = controlKind(sub);
+    if (kind === 'prose')
+        return sub.type === 'plaintext' || !!sub.inline;
+    return (kind === 'text' || kind === 'enum' || kind === 'number' || kind === 'boolean' || kind === 'date');
+}
+/**
+ * A collapsed row's own words: `items.ui.title` interpolated with the row's values
+ * where the schema declares one, else the first short text cell in declaration order
+ * — a `string`, or an inline `richtext` / `plaintext` — read through {@link titleText};
+ * `undefined` while the row has nothing to say for itself. `title` sits on `items.ui`,
+ * describing a row, where `layout` sits on the array's own `ui`, describing the array.
+ */
+export function rowSummary(items, row) {
+    const values = (row ?? {});
+    const template = items?.ui?.title;
+    if (template && template.trim()) {
+        const shown = interpolateTitle(template, values).trim();
+        if (shown)
+            return shown;
+    }
+    for (const [k, sub] of Object.entries(items?.properties ?? {})) {
+        const kind = controlKind(sub);
+        if (kind !== 'text' && !(kind === 'prose' && shortCell(sub)))
+            continue;
+        const text = titleText(ownValue(values, k)).trim();
+        if (text)
+            return text;
+    }
+    return undefined;
+}
+/**
+ * The layout an array takes: `'table'` where the array's own `ui.layout` asks for it
+ * and every cell of the row is short (a block prose cell declines it, at load width and
+ * every width after), else `'list'`. That every column is a leaf is the loader's
+ * contract (`quill::table_column_not_flat`); whether a leaf fits a cell is the surface's
+ * answer (canon `SCHEMAS.md`): a table composes by position, so a row that would stack
+ * inside a cell is not one.
+ */
+export function arrayLayout(field) {
+    if (field.ui?.layout !== 'table')
+        return 'list';
+    const items = field.items;
+    if (!items || controlKind(items) !== 'object')
+        return 'list';
+    const cells = Object.values(items.properties ?? {});
+    return cells.length > 0 && cells.every(shortCell) ? 'table' : 'list';
+}
 /**
  * Which world's cells to draw: the authored discriminant when the container carries
  * one, else the ghosted default's member — an unset field renders its `default:`, so a
@@ -109,12 +316,12 @@ export function commitDiscriminant(value, member) {
 }
 /**
  * Whether the schema obliges a cell: `default:`'s absence, which is the whole of the
- * obligation (DOCUMENT_MODEL). A typed dictionary is exempt — a namespace declares no
- * `default:` at all, and `validate` anchors obligation on the leaves under it, so
- * reading one off the container would mark every subform required.
+ * obligation (DOCUMENT_MODEL). A typed dictionary and a matrix are exempt — a namespace
+ * declares no `default:` at all, and `validate` anchors obligation on the leaves under
+ * it, so reading one off the container would mark every subform required.
  */
 export function obliged(schema) {
-    return schema.type !== 'object' && schema.default === undefined;
+    return schema.type !== 'object' && schema.type !== 'matrix' && schema.default === undefined;
 }
 /** `foo_bar` → `Foo bar`: the label fallback when a field declares no `ui.title`. */
 export function humanize(name) {
@@ -225,12 +432,14 @@ export function initialExpandedGroup(sections) {
  * An array declines whatever its items are: one-line elements make a one-line step,
  * but nothing holds two arrays to the same number of them, so the shorter of a packed
  * pair pays a cell of whitespace for every element the taller one has past it, and
- * pays more of it as the document is filled.
+ * pays more of it as the document is filled. A matrix declines as a roster does: its
+ * height is the roster's, and grows again under every member ticked open. Its hint
+ * reaches the roster instead, whose members stand abreast (`MatrixField`).
  */
 function packable(f) {
     if (!f.compact)
         return false;
-    if (f.control === 'object' || f.control === 'array' || f.control === 'variant')
+    if (isContainer(f.control))
         return false;
     return f.control !== 'prose' || f.inline;
 }
@@ -268,12 +477,42 @@ export function placeFields(fields) {
     flush();
     return out;
 }
+/** A card's field values by key, off its payload items. */
+export function fieldValues(items) {
+    const values = {};
+    for (const p of items)
+        if (p.type === 'field')
+            values[p.key] = p.value;
+    return values;
+}
 /** Interpolate a `{field}` card-title template against live field values. */
 export function interpolateTitle(template, values) {
-    return template.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name) => {
-        const v = values[name];
-        return v == null ? '' : String(v);
-    });
+    return template.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name) => titleText(ownValue(values, name)));
+}
+/** A value by own key: a template or a declaration can name `constructor`. */
+function ownValue(values, name) {
+    return Object.hasOwn(values, name) ? values[name] : undefined;
+}
+/** A field value as title text. A parsed field rests as the authored string and a
+ *  committed one as `Content`, whose `text` is the same words; a scalar reads as
+ *  itself; a variant container reads as its discriminant member, the one cell of it
+ *  that names the world; any other container as nothing. */
+export function titleText(v) {
+    if (v == null)
+        return '';
+    if (typeof v !== 'object')
+        return String(v);
+    const text = v.text;
+    if (typeof text === 'string')
+        return text;
+    const member = v[VARIANT_DISCRIMINANT];
+    return typeof member === 'string' ? member : '';
+}
+/** The field names a `{field}` title reads. */
+export function titleFields(template) {
+    if (!template)
+        return [];
+    return [...template.matchAll(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g)].map((m) => m[1]);
 }
 /**
  * Resolve a card instance's header title: the per-instance `$ext.editor.title`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quillmark/svelte",
-	"version": "0.10.1",
+	"version": "0.12.0",
 	"description": "Editor, live-preview and source surfaces over a Quillmark WASM session.",
 	"repository": {
 		"type": "git",
@@ -66,7 +66,7 @@
 		"check": "svelte-check --tsconfig ./tsconfig.json"
 	},
 	"peerDependencies": {
-		"@quillmark/wasm": ">=0.110.0-0",
+		"@quillmark/wasm": ">=0.115.0-0",
 		"svelte": "^5.0.0"
 	},
 	"dependencies": {