@quillmark/svelte 0.11.0 → 0.13.0

package/dist/visual/structure.js

@@ -1,3 +1,16 @@
+// 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, titles, ghosts, 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';
+import { core } from '../core/lifecycle.js';
+/** 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
@@ -21,36 +34,112 @@ export const NO_RESOLVED_ROWS = { fields: [], body: null };
 export function resolvedByCardIndex(resolved) {
     return new Map((resolved?.cards ?? []).map((c) => [c.index, { fields: c.fields, body: c.body }]));
 }
-/** The ghost a field shows when unset: the resolved `default:` value the render
- * would use (`source === 'default'`), else undefined: an `authored` field shows
- * its value, a `zero` field has no default to ghost. */
+/** What an unset field shows of its `default:`: the resolved value the render would
+ * use (`source === 'default'`), else undefined: an `authored` field shows its value,
+ * a `blank` field has no default to show. */
 export function ghostDefault(row) {
     return row?.source === 'default' ? row.value : undefined;
 }
 /** A ghost value's string form, or undefined for null/object (only text ghosts
- * render a placeholder). The one text-ghost projection: a scalar field's
- * placeholder and a body leaf's both read `stringifyGhost ∘
- * ghostDefault`, since a richtext body resolves to a text render: the correct
- * thing to display as a placeholder (FIELD_PROVENANCE). */
+ * render a placeholder). A scalar's resolved default reads through it; a content
+ * field's resolves as `Content`, which a prose leaf reads by its text instead
+ * ({@link titleText}). */
 export function stringifyGhost(ghost) {
     return ghost != null && typeof ghost !== 'object' ? String(ghost) : undefined;
 }
 /**
- * The empty body's ghost: the resolved body `default:`, else the consumer's
- * wording, else the flat built-in. The `default:` wins because it is the only one
- * of the three that describes the render: it promises what prints if nothing is
- * written, and wording placed over it would make that promise unreadable. The
- * other two are invitations, and an invitation belongs only where there is no
- * promise.
+ * The empty body's ghost: the resolved body `default:`, else the kind's
+ * `body.example`, else the consumer's wording, else the flat built-in. The
+ * `default:` wins because it is the only one that describes the render: it promises
+ * what prints if nothing is written, and wording placed over it would make that
+ * promise unreadable. The rest are invitations, and an invitation belongs only where
+ * there is no promise; the quill's own comes first, being the one an agent working
+ * from the blueprint sees too.
+ */
+export function resolveBodyGhost(resolvedDefault, example, custom, builtIn) {
+    return resolvedDefault || example || custom || builtIn;
+}
+/** Whether a cell is optional: a `t?` type, which renders `none` unanswered and so
+ *  never declares a `default:` (canon `SCHEMAS.md` §"Optional cells"). */
+export function optionalCell(f) {
+    return f.type.endsWith('?');
+}
+/** The type a cell's control reads: the declared one, an optional cell's `?` stripped.
+ *  The `?` moves the render floor and nothing else, so every read of a type is this. */
+export function baseType(f) {
+    return (optionalCell(f) ? f.type.slice(0, -1) : f.type);
+}
+/**
+ * A value the schema declares, as ghost text: a `default:`, an `example:` or a
+ * `body.example`. Markdown — a `richtext` value — ghosts as the text it renders, one
+ * block to a line, as a resolved default does ({@link titleText}); anything else as
+ * itself. `undefined` for a blank or a non-scalar.
+ */
+export function declaredGhost(v, markdown) {
+    const text = stringifyGhost(v)?.trim();
+    if (!text)
+        return undefined;
+    return (markdown ? core().importMarkdown(text).text.trim() : text) || undefined;
+}
+/**
+ * A scalar `default:` as the text an unset control holds, where it prints: as
+ * declared, `undefined` for none, a blank or a non-scalar. A default of spaces prints
+ * nothing a reader sees, so a control holds none and draws its example instead.
+ */
+export function printedText(v) {
+    const text = stringifyGhost(v);
+    return text?.trim() ? text : undefined;
+}
+/**
+ * A declared content literal as the `Content` it holds: a `richtext` one's markdown
+ * imported, a `plaintext` one's text taken literally, one paragraph whose later lines
+ * continue it, as the literal codec reads a stored one. What a cell's static
+ * `default:` stands in its leaf as, where no resolved row reaches it. `undefined` for
+ * a blank or a non-scalar.
+ */
+export function declaredContent(v, markdown) {
+    const text = printedText(v);
+    if (text === undefined)
+        return undefined;
+    if (markdown)
+        return core().importMarkdown(text);
+    return {
+        text,
+        lines: text
+            .split('\n')
+            .map((_, i) => i === 0
+            ? { containers: [], kind: 'para' }
+            : { containers: [], kind: 'para', continues: true }),
+        marks: [],
+        islands: []
+    };
+}
+/**
+ * The `example:` an unset free-text cell ghosts: a `string`, `plaintext` or `richtext`
+ * whose `default:` prints nothing. Every other type takes none. A default that prints
+ * dominates, standing in the control as the value it is; a type-empty one, the
+ * skippable marker, prints nothing and leaves the example the only thing to draw.
  */
-export function resolveBodyGhost(resolvedDefault, custom, builtIn) {
-    return resolvedDefault || custom || builtIn;
+export function exampleGhost(f) {
+    const kind = controlKind(f);
+    if (kind !== 'text' && kind !== 'prose')
+        return undefined;
+    const markdown = baseType(f) === 'richtext';
+    if (declaredGhost(f.default, markdown) !== undefined)
+        return undefined;
+    return declaredGhost(f.example, markdown);
+}
+/** A field's `{#each}` key: its name and what a mounted leaf reads once, its type and
+ *  `inline` and its elements'. A retype or a quill swap that changes any of them under a
+ *  name remounts the field, where a kept leaf would commit on the old schema. */
+export function mountKey(name, f) {
+    return `${name}\u0000${f.type}\u0000${f.inline === true}\u0000${f.items?.type ?? ''}\u0000${f.items?.inline === true}`;
 }
 /** Map a field schema to its control (precedence: prose › enum › text › …).
  * An array's element control is this over `items`: a missing `items` is a text
  * element. */
 export function controlKind(f) {
-    switch (f.type) {
+    switch (baseType(f)) {
         case 'richtext':
         case 'plaintext':
             return 'prose';
@@ -72,13 +161,206 @@ 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 prose cell is one where it declares `inline`, `richtext` or
+ *  `plaintext` alike. */
+export function shortCell(sub) {
+    const kind = controlKind(sub);
+    if (kind === 'prose')
+        return !!sub.inline;
+    return (kind === 'text' || kind === 'enum' || kind === 'number' || kind === 'boolean' || kind === 'date');
+}
+/**
+ * The first short text cell's words, in declaration order — a `string`, or an inline
+ * `richtext` / `plaintext` — read through {@link titleText}; `undefined` while none of
+ * them has any. What names an instance from its own values: a collapsed row, and a
+ * card whose kind declares no `title`.
+ */
+function firstShortText(cells, values) {
+    for (const [k, sub] of Object.entries(cells ?? {})) {
+        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;
+}
+/** A collapsed row's own words ({@link firstShortText}); `undefined` while the row has
+ *  nothing to say for itself. */
+export function rowSummary(items, row) {
+    return firstShortText(items?.properties, (row ?? {}));
+}
+/**
+ * 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,14 +391,18 @@ 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). Exempt are the cells whose absence of one says nothing:
+ * a typed dictionary and a matrix, since a namespace declares no `default:` at all and
+ * `validate` anchors obligation on the leaves under it; and an optional cell, which can
+ * declare none, its unanswered render being `none`.
  */
 export function obliged(schema) {
-    return schema.type !== 'object' && schema.default === undefined;
+    return (schema.type !== 'object' &&
+        schema.type !== 'matrix' &&
+        !optionalCell(schema) &&
+        schema.default === undefined);
 }
-/** `foo_bar` → `Foo bar`: the label fallback when a field declares no `ui.title`. */
+/** `foo_bar` → `Foo bar`: the label fallback when a field declares no `title`. */
 export function humanize(name) {
     const spaced = name.replace(/_/g, ' ').trim();
     return spaced ? spaced[0].toUpperCase() + spaced.slice(1) : spaced;
@@ -129,11 +415,11 @@ export function fieldModels(cardSchema) {
         control: controlKind(schema),
         group: schema.ui?.group,
         compact: !!schema.ui?.compact,
-        label: schema.ui?.title ?? humanize(name),
+        label: schema.title ?? humanize(name),
         description: schema.description,
         required: obliged(schema),
         inline: !!schema.inline,
-        plaintext: schema.type === 'plaintext'
+        plaintext: baseType(schema) === 'plaintext'
     }));
 }
 /**
@@ -225,12 +511,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;
 }
@@ -276,40 +564,44 @@ export function fieldValues(items) {
             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) => titleText(values[name]));
+/** A value by own key: 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 and any other container as nothing. */
+ *  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;
-    return typeof text === 'string' ? 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]);
+/** A card kind's name: its schema `title`, else the humanized kind. What names a kind
+ *  before there is an instance of it: the add menu, the retype select. */
+export function kindTitle(cardSchema, kind) {
+    const t = cardSchema?.title;
+    return t && t.trim() ? t : humanize(kind);
 }
 /**
- * Resolve a card instance's header title: the per-instance `$ext.editor.title`
- * override wins; else the schema `ui.title` (literal or `{field}` template
- * interpolated); else the humanized kind. Empty overrides fall through so a
- * cleared rename reverts to the schema title.
+ * A card instance's header: the per-instance `$ext.editor.title` rename; else the
+ * kind's schema `title`, which names every instance alike; else the instance's own
+ * first short text cell ({@link firstShortText}); else the humanized kind. Empty
+ * renames fall through, so a cleared rename reverts to what the schema says.
  */
 export function cardTitle(cardSchema, kind, values, extTitle) {
     if (extTitle && extTitle.trim())
         return extTitle;
-    const t = cardSchema?.ui?.title;
+    const t = cardSchema?.title;
     if (t && t.trim())
-        return interpolateTitle(t, values);
-    return humanize(kind);
+        return t;
+    return firstShortText(cardSchema?.fields, values) ?? humanize(kind);
 }
 /** Whether a card kind renders a body leaf: gated by `body.enabled !== false`. */
 export function bodyEnabled(cardSchema) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quillmark/svelte",
-	"version": "0.11.0",
+	"version": "0.13.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.113.0-0",
+		"@quillmark/wasm": ">=0.116.0-0",
 		"svelte": "^5.0.0"
 	},
 	"dependencies": {