@quillmark/wasm 0.95.1 → 0.97.0

package/core/wasm.d.ts

@@ -102,7 +102,14 @@ export type ContentContainer =
 | { container: "list_item"; ordered: boolean; start: number; ordinal: number }
 | { container: "quote" };
 
-/** A mark over char range `[start, end)` into `Content.text`. */
+/** A mark over char range `[start, end)` into `Content.text`. The open `type`
+ * arm blocks discriminant narrowing (as on `ContentIsland`), so read a
+ * payload-carrying arm behind its guard — `isLinkMark` (`url`) / `isAnchorMark`
+ * (`id`), from `@quillmark/wasm/runtime`; the bare arms carry no payload. An
+ * `anchor`'s `id` is a caller-supplied, opaque handle, unique per `Content` and
+ * invariant while the mark lives (positions rebase, the id never does); it has no
+ * markdown projection and survives only through the edit lane. See DOCUMENT_STORAGE
+ * § Anchor-id identity. */
 export type ContentMark = { start: number; end: number } & (
 | { type: "strong" | "emph" | "underline" | "strike" | "code" }
 | { type: "link"; url: string }
@@ -110,14 +117,45 @@ export type ContentMark = { start: number; end: number } & (
 | { type: string; attrs: unknown }
 );
 
-/** A structured object (table, figure, …) occupying one island slot in `Content.text`. */
-export interface ContentIsland {
+/** A cell in a `TableProps` — its plain `text` plus the `marks` over it. `marks`
+ * rides the same wire shape as prose `ContentMark`, but each mark's `start`/`end`
+ * are USV offsets into this cell's `text` (`0..text.length`), not into
+ * `Content.text`. */
+export interface TableCell {
+    text: string;
+    marks: ContentMark[];
+}
+
+/** `props` of a `type: "table"` island: a pipe table normalized to one column
+ * count that `header`, every row of `rows`, and `aligns` all share. */
+export interface TableProps {
+    header: TableCell[];
+    rows: TableCell[][];
+    /** Per-column alignment, one entry per column. */
+    aligns: ("none" | "left" | "center" | "right")[];
+}
+
+/** `props` of a `type: "image"` island. */
+export interface ImageProps {
+    url: string;
+    alt: string;
+}
+
+/** A structured object occupying one island slot in `Content.text`. `type` is an
+ * open set: the engine pins `props` as `TableProps` for `table` and `ImageProps`
+ * for `image`; an island of any other type round-trips with opaque `props`. Like
+ * `ContentMark`, the open `type` arm means a discriminant check does not itself
+ * narrow `props` — read `props` as the matching shape behind the `isTableIsland` /
+ * `isImageIsland` guards (from `@quillmark/wasm/runtime`), which narrow it. */
+export type ContentIsland = {
     id: string;
-    type: string;
-    props: unknown;
     /** How faithfully the markdown projection can carry this island. */
     loss: "lossless" | "degraded" | "unrepresentable";
-}
+} & (
+| { type: "table"; props: TableProps }
+| { type: "image"; props: ImageProps }
+| { type: string; props: unknown }
+);
 
 /**
  * A write address — one navigation concept for the whole `Document` surface. An
@@ -161,7 +199,10 @@ export type Assoc = "before" | "after";
 /**
  * A mark edit in final-text coordinates (post-delta, post-line-op). `add` /
  * `remove` carry the `ContentMark` vocabulary (`{ type, … }`); `removeAnchor`
- * drops one identity anchor by id.
+ * drops one identity anchor by id. An `add` of an `anchor` requires a non-empty
+ * `id` not already live in the field — a collision or the empty id throws
+ * (ids are caller-supplied and unique per `Content`; DOCUMENT_STORAGE
+ * § Anchor-id identity).
  */
 export type MarkOp =
 | ({ op: "add" | "remove"; start: number; end: number } & (
@@ -203,6 +244,70 @@ export interface ChangeBundle {
 
 
 
+/**
+ * One segment of a parsed `Diagnostic.path` (see `parseDocPath`). The head
+ * carries the document-model root — `main` (only before `body`), a `card`
+ * (`kind: null` is the unknown-kind `cards[i]` form), or a `field`; the tail is
+ * `field` / `index` / a terminal `body`.
+ */
+export type DocPathSeg =
+| { seg: "main" }
+| { seg: "card"; kind: string | null; index: number }
+| { seg: "field"; name: string }
+| { seg: "index"; index: number }
+| { seg: "body" };
+
+
+
+/** The commitment-ladder rung that produced a `ResolvedField.value`. */
+export type FieldSource = "authored" | "default" | "zero";
+
+/**
+ * One resolved row: its `name`, the value the render projection would use, and
+ * the `FieldSource` rung it came from. Rows are an ordered array — declaration
+ * order is structural, not object-key order. The card body is a `body` sibling
+ * on its card, never a row in `fields`. Diagnostics stay `Quill.validate`'s;
+ * schema guidance (`example:`, labels) reads from `Quill.schema`.
+ */
+export interface ResolvedField {
+    name: string;
+    value: unknown;
+    source: FieldSource;
+}
+
+/**
+ * The main card's resolved rows in declaration order, plus its body row —
+ * `null` when the main enables no body.
+ */
+export interface ResolvedMain {
+    fields: ResolvedField[];
+    body: ResolvedField | null;
+}
+
+/**
+ * One composable card's resolved rows in declaration order, with its authored
+ * `kind` (`null` for an unknown-kind card), its document-array `index`, and its
+ * body row — `null` when the kind enables no body.
+ */
+export interface ResolvedCard {
+    kind: string | null;
+    index: number;
+    fields: ResolvedField[];
+    body: ResolvedField | null;
+}
+
+/**
+ * The resolved-value view (`Quill.resolve`): the main card and every
+ * composable card. Value and provenance only — completeness and errors stay
+ * `Quill.validate`.
+ */
+export interface Resolved {
+    main: ResolvedMain;
+    cards: ResolvedCard[];
+}
+
+
+
 /** UI layout hints for a single field. Field display order is not a hint:
  * key order in the schema's `fields`/`properties` objects is declaration
  * order, the ordering contract. */
@@ -213,9 +318,23 @@ export interface QuillFieldUi {
     multiline?: boolean;
 }
 
+/** One entry in a card's `ui.groups` registry: a display-label override for the
+ * group id (the map key). An empty object carries no override — the consumer
+ * derives the label from the id (`memo_for` → "Memo For"), as it does a field
+ * label from its key. */
+export interface QuillGroupUi {
+    title?: string;
+}
+
 /** UI layout hints for a card (main or named card kind). */
 export interface QuillCardUi {
     title?: string;
+    /** The card's group registry: the ordered table of contents naming every
+     * group a field's `ui.group` may reference. The map key is the group id, and
+     * key order is declaration order — the display-order contract, the same one
+     * `fields` key order carries. Absent when the card declares no groups (or
+     * uses the deprecated implicit-group form). */
+    groups?: Record<string, QuillGroupUi>;
 }
 
 /** Body namespace for a card (main or named card kind). */
@@ -338,15 +457,15 @@ export class Document {
      * A single composable card by index — the whole `Card`, the card-indexed
      * twin of the [`main`](Self::main) getter, so reading one card need not
      * materialize every card via [`cards`](Self::cards). An out-of-range
-     * `index` throws `[EditError::IndexOutOfRange]`, matching the card write
+     * `index` throws `edit::index_out_of_range`, matching the card write
      * verbs.
      */
     card(index: number): Card;
     /**
-     * The index of the first composable card whose `$id` equals `id`, or
-     * `undefined` when none carries it. Resolves the canonical durable address
+     * The index of the composable card whose `$id` equals `id`, or
+     * `undefined` when none carries it. Resolves the durable card handle
      * without a hand-rolled scan over [`cards`](Self::cards); `$id` is
-     * non-unique by design, so the first match wins.
+     * unique per document, so at most one card matches.
      */
     cardIndexById(id: string): number | undefined;
     clone(): Document;
@@ -388,17 +507,6 @@ export class Document {
      * Parse markdown into a typed Document. Throws on parse errors.
      */
     static fromMarkdown(markdown: string): Document;
-    /**
-     * Read the value at `addr` — the raw stored payload value of a field (a
-     * content object for a richtext field, a scalar/array/object otherwise), or
-     * the **body content** when `addr.field` is absent. A bare string is `Addr`
-     * shorthand for `{ field }`. Reads are total over the field axis: an absent
-     * field is `undefined`; only an out-of-range `addr.card` throws
-     * `[EditError::IndexOutOfRange]`. Reads need no schema, so they live on
-     * `Document`, not the typed writer; for the markdown projection of a
-     * richtext value use [`getMarkdown`](Self::get_markdown).
-     */
-    get(addr: Addr | string): unknown;
     /**
      * The whole `$ext` map at `addr` (a card address, absent `card` = main), or
      * `undefined` when the card carries none. The fine-grained `$ext` read —
@@ -421,10 +529,23 @@ export class Document {
      *
      * `addr` is an optional **card address** (`{ card }`, absent = main). A
      * present `field` throws — a field's markdown is read through the
-     * schema-plane `quill.view(doc).get(field)`, which interprets by declared
+     * schema-plane `quill.reader(doc).get(field)`, which interprets by declared
      * type (#978). An out-of-range `addr.card` throws.
      */
     getMarkdown(addr?: CardAddr): string;
+    /**
+     * Read the **verbatim stored value** at `addr` — the raw payload value of a
+     * field (a content object for a richtext field, a scalar/array/object
+     * otherwise), or the **body content** when `addr.field` is absent. A bare
+     * string is `Addr` shorthand for `{ field }`. Reads are total over the field
+     * axis: an absent field is `undefined`; only an out-of-range `addr.card`
+     * throws `edit::index_out_of_range`. Needs no schema, so it lives on
+     * `Document` — the read echo of the verbatim `store*` write, distinct from
+     * the interpreted schema-plane [`reader.get`](Self::reader_get). For the
+     * markdown projection use [`getMarkdown`](Self::get_markdown) (body) or
+     * `reader.get` (a field's declared type).
+     */
+    getStored(addr: Addr | string): unknown;
     /**
      * Insert a card — the single insertion verb: `at` absent appends, a number
      * inserts at that index (must be in `0..=cards.length`). Accepts a
@@ -525,7 +646,7 @@ export class Document {
     removeSeedNamespace(card_kind: string): any;
     /**
      * **Revise** the richtext value at `addr` from a markdown string — **edit
-     * semantics**, the default write path, returning the text [`Delta`]. Imports
+     * semantics**, the default write path, returning the text `Delta`. Imports
      * the markdown, diffs it against the current value, rebases surviving
      * identity anchors, and returns the change an editor bridge maps its own
      * positions through (`mapPos`). An absent `addr.field` targets the body, an
@@ -664,6 +785,18 @@ export class Quill {
      * canonical shape.
      */
     static fromTree(tree: Map<string, Uint8Array>): Quill;
+    /**
+     * The resolved-value view of `doc` against this quill's schema — for every
+     * declared field the value the render projection would use and the
+     * `FieldSource` rung it came from (`"authored" | "default" | "zero"`), in
+     * one call. The card body is a `body` sibling on its card (row `name`
+     * `"body"`), never a row in `fields` — `null` when the kind enables no body.
+     *
+     * Value and provenance only: completeness and errors stay `validate`'s
+     * (a consumer merges it with its own diagnostic producers regardless), and
+     * schema guidance reads from `Quill.schema`.
+     */
+    resolve(doc: Document): Resolved;
     /**
      * Seed a starter composable `Card` of the given kind (carries `$kind`),
      * layering an optional per-kind seed `overlay` over the schema-example
@@ -749,6 +882,15 @@ export class Quill {
  */
 export function exportMarkdown(rt: Content): string;
 
+/**
+ * Serialize structured [`DocPathSeg`] segments back to the canonical path
+ * string — the inverse of `parseDocPath`, for a consumer that builds a path
+ * rather than reads one. Throws on a segment array the deserializer rejects,
+ * and on an empty segment array (symmetric with `parseDocPath("")`, which
+ * throws "empty path").
+ */
+export function formatDocPath(segs: DocPathSeg[]): string;
+
 /**
  * Import a markdown string to a canonical `Content` content — the pure,
  * document-free codec. Pair with `install(addr, importMarkdown(md))` to spell
@@ -763,18 +905,29 @@ export function importMarkdown(markdown: string): Content;
 export function init(): void;
 
 /**
- * Map a base content position through a `delta` to its new position — the pure
- * position-mapping codec an editor bridge composes to hold a caret stable
- * across a `revise`. `assoc` decides the side of a same-position insertion
- * (`"after"` moves past it). Throws on a malformed `delta`.
+ * Map a base content position — a USV index into `Content.text`, not a UTF-16
+ * offset — through a `delta` to its new USV position: the pure position-mapping
+ * codec an editor bridge composes to hold a caret stable across a `revise`.
+ * `assoc` decides the side of a same-position insertion (`"after"` moves past
+ * it). Throws on a malformed `delta`.
  */
 export function mapPos(delta: Delta, pos: number, assoc: Assoc): number;
 
+/**
+ * Parse a canonical document-model `Diagnostic.path`
+ * (`cards.<kind>[<i>].<field>`, `main.body`, `recipients[0].name`) into its
+ * structured [`DocPathSeg`] segments — the exported inverse of the engine's
+ * one path serializer, so a consumer routes on segments instead of regexing
+ * the string. Throws on a malformed path.
+ */
+export function parseDocPath(path: string): DocPathSeg[];
+
 /**
  * Rebase `markdown` onto a `base` content — the pure, document-free twin of
  * `revise`: cold-import + `diff_import`, returning the new `content` and the
- * text `delta` (surviving anchors rebased). Use it to compute a revise without
- * a document in hand; `revise(addr, md)` fuses this with the store for
- * atomicity. Throws on an over-nested markdown input or a non-content `base`.
+ * text `delta` (its offsets USV indices into `Content.text`, surviving anchors
+ * rebased). Use it to compute a revise without a document in hand; `revise(addr,
+ * md)` fuses this with the store for atomicity. Throws on an over-nested
+ * markdown input or a non-content `base`.
  */
 export function rebase(base: Content, markdown: string): { content: Content; delta: Delta };

package/core/wasm.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./wasm_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    Document, Quill, exportMarkdown, importMarkdown, init, mapPos, rebase
+    Document, Quill, exportMarkdown, formatDocPath, importMarkdown, init, mapPos, parseDocPath, rebase
 } from "./wasm_bg.js";