@quillmark/svelte 0.12.0 → 0.13.0

package/dist/visual/structure.js

@@ -1,10 +1,11 @@
 // 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
+// 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) {
@@ -33,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, custom, builtIn) {
-    return resolvedDefault || custom || builtIn;
+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 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';
@@ -237,29 +314,22 @@ function stepInto(schema, step) {
 }
 // ── 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. */
+ *  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.type === 'plaintext' || !!sub.inline;
+        return !!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.
+ * 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`.
  */
-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 ?? {})) {
+function firstShortText(cells, values) {
+    for (const [k, sub] of Object.entries(cells ?? {})) {
         const kind = controlKind(sub);
         if (kind !== 'text' && !(kind === 'prose' && shortCell(sub)))
             continue;
@@ -269,6 +339,11 @@ export function rowSummary(items, row) {
     }
     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
@@ -316,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 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.
+ * 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.type !== 'matrix' && 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;
@@ -336,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'
     }));
 }
 /**
@@ -485,11 +564,7 @@ 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(ownValue(values, name)));
-}
-/** A value by own key: a template or a declaration can name `constructor`. */
+/** A value by own key: a declaration can name `constructor`. */
 function ownValue(values, name) {
     return Object.hasOwn(values, name) ? values[name] : undefined;
 }
@@ -508,25 +583,25 @@ export function titleText(v) {
     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.12.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.115.0-0",
+		"@quillmark/wasm": ">=0.116.0-0",
 		"svelte": "^5.0.0"
 	},
 	"dependencies": {