@quillmark/wasm 0.123.1 → 0.125.0

package/render/wasm.d.ts

@@ -105,10 +105,17 @@ export type ContentLineKind =
 export type ContentContainer =
 | {
     container: "list_item";
-    attrs: { ordered: boolean; start: number; ordinal: number };
+    /** `checked` is present on a task item: `true` ticked, `false` open. */
+    attrs: { ordered: boolean; start: number; ordinal: number; checked?: boolean };
     instance?: number;
 }
-| { container: "quote"; instance?: number };
+| { container: "quote"; instance?: number }
+| { container: "element"; attrs: ElementAttrs; instance?: number };
+
+/** A carrier element's name and attributes, one bag: `$name` is the part of
+ * its `qm-<name>` tag after the prefix, and every other key an attribute as
+ * written. */
+export type ElementAttrs = { $name: string; [attr: string]: string };
 
 /** A mark over char range `[start, end)` into `Content.text`. `type` is a
  * closed set, so `type === "link"` narrows `attrs` to `{ url: string }` with no
@@ -131,20 +138,34 @@ export type ContentMarkKind =
 export interface TableCell {
     text: string;
     marks: ContentMark[];
+    /** The cell's horizontal alignment; absent is its column's. */
+    align?: "left" | "center" | "right";
+    /** The cell's vertical alignment; absent is the quill's. */
+    valign?: "top" | "middle" | "bottom";
 }
 
 /** `props` of a `type: "table"` island: a pipe table normalized to one column
- * count that `header`, every row of `rows`, and `aligns` all share. */
+ * count that `header`, every row of `rows`, `aligns` and `widths` all share.
+ * A layout key at its default is absent; one holding a value outside its type
+ * stays as written and reads as absent. */
 export interface TableProps {
     header: TableCell[];
     rows: TableCell[][];
     /** Per-column alignment, one entry per column. */
     aligns: ("none" | "left" | "center" | "right")[];
+    /** Per-column relative weights; `null` is an auto-fit column. Absent when
+     * every column is auto-fit. A weight is an integer from 1 to
+     * `Number.MAX_SAFE_INTEGER`. */
+    widths?: (number | null)[];
+    /** The table's placement; absent is the quill's. */
+    align?: "left" | "center" | "right";
+    /** `true` draws `header` as the first body row; absent is a header row. */
+    headless?: true;
 }
 
 /** `props` of a `type: "image"` island. Stores and round-trips; no backend
  * typesets one, and a render that holds one warns `backend::declined_construct`,
- * because what `url` names is undecided. */
+ * because no backend resolves `url`. */
 export interface ImageProps {
     url: string;
     alt: string;
@@ -205,6 +226,57 @@ export interface Delta {
     ops: ({ retain: number } | { insert: string } | { delete: number })[];
 }
 
+/**
+ * The receipt of a markdown revise (`revise`, `writer.reviseBody`,
+ * `writer.reviseField`): the text `delta`, and one `parse::dropped_construct`
+ * warning per construct the import dropped, anchored at the revised address.
+ */
+export interface Revised {
+    delta: Delta;
+    warnings: Diagnostic[];
+}
+
+/**
+ * The receipt of `writer.reviseDocument`. `droppedAnchors` names every prose
+ * anchor the write did not carry, at its path and line in the stored document; a table
+ * cell's anchors drop unnamed. `warnings` are the parse's, then each revised
+ * content field's `parse::dropped_construct`, then the writer's `conform::*`.
+ * A field that lands rather than revises, on an inserted card or over no stored
+ * content, reports no drop.
+ */
+export interface DocumentRevised {
+    droppedAnchors: DocumentAnchor[];
+    warnings: Diagnostic[];
+}
+
+/**
+ * The read `toAnnotatedMarkdown` returns: `toMarkdown`'s markdown with a
+ * read-only `<qm-anchor ref="…"></qm-anchor>` at each prose anchor's
+ * start its line can hold, and every prose anchor of every body and content
+ * field, spelled or not; a table cell's anchors are neither. Each names the
+ * `path` of its body or field and the text of the `line` its start sits on,
+ * island slots removed.
+ */
+export interface AnnotatedMarkdown {
+    markdown: string;
+    anchors: DocumentAnchor[];
+}
+
+export interface DocumentAnchor {
+    id: string;
+    path: string;
+    line: string;
+}
+
+/**
+ * A markdown import (`importMarkdown`): the canonical `content`, and one
+ * `parse::dropped_construct` warning per construct it dropped, with no `path`.
+ */
+export interface Imported {
+    content: Content;
+    warnings: Diagnostic[];
+}
+
 /** Which side of a same-position insertion `mapPos` lands a point on. */
 export type Assoc = "before" | "after";
 
@@ -385,6 +457,8 @@ export interface Resolved {
 /** UI layout hints for a single field. Display order is not a hint: key order
  * in the schema's `fields`/`properties` objects is the ordering contract. */
 export interface QuillFieldUi {
+    /** The id of the card section holding the field, a key of the card's
+     *  `ui.groups`. */
     group?: string;
     compact?: boolean;
     multiline?: boolean;
@@ -401,18 +475,18 @@ export interface QuillFieldUi {
     layout?: "table" | "flat";
 }
 
-/** 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, and the consumer
- * derives the label from the id (`memo_for` → "Memo For"). */
+/** One section in a card's `ui.groups`: a display-label override for the
+ * section id (the map key). An empty object carries no override, and the
+ * consumer derives the label from the id (`memo_for` → "Memo For"). */
 export interface QuillGroupUi {
     title?: string;
 }
 
 /** UI layout hints for a card (main or named card kind). */
 export interface QuillCardUi {
-    /** The groups a field's `ui.group` may reference, keyed by group id. Key
-     * order is the display-order contract, as with `fields`. Absent when the
-     * card declares no groups. */
+    /** The card's sections keyed by id, each holding at least one field, which
+     * names it in its `ui.group`. Key order is the display-order contract, as
+     * with `fields`. Absent when the card declares no sections. */
     groups?: Record<string, QuillGroupUi>;
 }
 
@@ -554,7 +628,8 @@ export interface FieldRegion {
     rect: [number, number, number, number];
     /**
      * The slice this box covers: USV `[start, end)` into the field's `Content`
-     * for one content segment, `undefined` for a scalar site or widget.
+     * for one content segment, `undefined` for a scalar's ink, a claim or a
+     * widget.
      */
     span?: [number, number];
 }
@@ -565,6 +640,23 @@ export interface FieldRegion {
  */
 export type HitGranularity = "cluster" | "segment";
 
+/**
+ * One address a compiled document fills and the region address a click
+ * reaches it through: the consumer's copy of this contract is
+ * `runtime/runtime.d.ts`.
+ */
+export interface FieldCoverage {
+    /**
+     * Canonical `DocPath` field address, as `FieldRegion.field` spells it.
+     */
+    field: string;
+    /**
+     * The `DocPath` of the region reaching `field`: itself, or the nearest
+     * enclosing address a region carries. `undefined` where no click does.
+     */
+    coveredBy?: string;
+}
+
 /**
  * Output formats supported by backends. Gated behind the engine surface so
  * tsify omits it from the core bundle, which has no rendering surface.
@@ -596,8 +688,8 @@ export interface Diagnostic {
     message: string;
     location?: Location;
     /**
-     * Document-model path anchor (e.g. `"cards.indorsement[0].signature_block"`),
-     * set on schema validation diagnostics and `undefined` otherwise.
+     * Document-model path anchor (e.g. `"cards.indorsement[0].signature_block"`)
+     * where the diagnostic has a document address, `undefined` otherwise.
      */
     path?: string;
     hint?: string;
@@ -828,15 +920,17 @@ export class Document {
     /**
      * **Revise** the richtext value at `addr` from a markdown string: the
      * default write path. Imports the markdown, diffs it against the current
-     * value, rebases surviving identity anchors, and returns the text `Delta` an
-     * editor bridge maps its own positions through (`mapPos`). An absent
-     * `addr.field` targets the body, an absent `addr.card` the main card; an
-     * absent field cold-imports from empty.
+     * value, rebases surviving identity anchors, and returns the `Revised`
+     * receipt: the text `delta` an editor bridge maps its own positions through
+     * (`mapPos`), and a `parse::dropped_construct` warning per construct the
+     * import dropped, its `path` the address written. An absent `addr.field`
+     * targets the body, an absent `addr.card` the main card; an absent field
+     * cold-imports from empty.
      *
      * Throws on an out-of-range card, a malformed field name, a present
      * non-content field value, or an over-nested markdown input.
      */
-    revise(addr: Addr | string, markdown: string): Delta;
+    revise(addr: Addr | string, markdown: string): Revised;
     /**
      * The main card's `$seed[kind]` overlay object, or `undefined`. Feeds
      * `quill.seedCard(kind, overlay)` without serializing the whole main card,
@@ -889,8 +983,18 @@ export class Document {
      */
     storeSeedOverlay(card_kind: string, overlay: any): void;
     /**
-     * Emit canonical Quillmark Markdown. Round-trip safe: re-parsing the
-     * result produces a `Document` equal to `self` by value and by type.
+     * `toMarkdown` with each prose anchor of every body and content field
+     * spelled read-only at its start where its line can hold the tag, and
+     * listed with its field's path and line either way. An import drops every
+     * tag, so `writer.reviseDocument` with the markdown keeps the anchors it keeps
+     * with `toMarkdown`'s.
+     */
+    toAnnotatedMarkdown(): AnnotatedMarkdown;
+    /**
+     * Emit canonical Quillmark Markdown. Re-parsing the result produces a
+     * `Document` equal to `self` by value and by type, but for content: a body
+     * or content field holds what its markdown spells, so its anchors drop and
+     * its island ids re-mint. `toStored` keeps both.
      */
     toMarkdown(): string;
     /**
@@ -914,7 +1018,7 @@ export class Document {
      * The non-fatal diagnostics of the load that produced this document: parse
      * warnings, plus `conform::*` warnings when it came through `quill.parse`.
      * Session state, not document value: `equals` and the storage DTO exclude
-     * it, and `fromStored` / `loadStored` clear it.
+     * it, and `fromStored` / `loadStored` / `writer.reviseDocument` clear it.
      */
     readonly warnings: Diagnostic[];
 }
@@ -933,6 +1037,13 @@ export class LiveSession {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Each address the current compile fills that a reader could want to
+     * click, and the `DocPath` of the region reaching it: the address itself,
+     * the nearest enclosing one a region carries (a row claim reaching its
+     * cells), or `undefined` where no click does. Reflects the current compile.
+     */
+    coverage(): FieldCoverage[];
     /**
      * The schema field whose content is under a point on `page`: the `DocPath`
      * address to focus in the editor, or `undefined` off any field's ink.
@@ -953,9 +1064,9 @@ export class LiveSession {
     /**
      * The whole-field highlight boxes for `field`: one union rect per page over
      * the field's `span`-bearing content segments, the union `regions()` leaves
-     * derived. **Content only**: a field placed solely as a scalar reference or
-     * a bound widget carries no `span` and returns `[]`, its box being a single
-     * `regions()` rect. Reflects the current compile.
+     * derived. **Content only**: a field placed solely as a scalar's ink, a
+     * claim or a bound widget carries no `span` and returns `[]`, its box being
+     * a single `regions()` rect. Reflects the current compile.
      */
     fieldBoxes(field: string): FieldRegion[];
     /**
@@ -1000,9 +1111,9 @@ export class LiveSession {
      */
     positionAt(page: number, x: number, y: number, tol_pt?: number | null): ContentHit | undefined;
     /**
-     * Schema-field geometry for this compiled session: each content field's
-     * **first placement** (one region per page it touches) plus widget and
-     * scalar-reference-site regions, keyed on the canonical `DocPath` address. A
+     * Schema-field geometry for this compiled session: each piece of generated
+     * ink's **first placement** (one region per page it touches) plus claim and
+     * widget regions, keyed on the canonical `DocPath` address. A
      * field may appear more than once, so group by `field` (see `FieldRegion`).
      * A session-level query: no render, no byte artifact. The click direction is
      * `fieldAt`. Empty for backends that place no schema fields.
@@ -1119,9 +1230,10 @@ export class Quill {
      */
     toTree(): Map<string, Uint8Array>;
     /**
-     * Validate `doc` against this quill's schema, returning every diagnostic
-     * (empty when the document is valid). Forwards the canonical
-     * `validation::*` diagnostics the engine emits.
+     * Validate `doc` against this quill's schema, returning every diagnostic:
+     * an error blocks a render, a warning does not. Forwards the engine's
+     * `validation::*`, a markdown string's `parse::dropped_construct` and the
+     * backend's `backend::declined_construct`.
      */
     validate(doc: Document): Diagnostic[];
     /**
@@ -1165,9 +1277,10 @@ export class Quillmark {
     open(quill: Quill, doc: Document, today?: string | null): LiveSession;
     /**
      * Render `doc` against `quill` in one shot: `open` + `LiveSession.render`,
-     * with `doc.warnings`, then every `quill.validate` warning, ahead of the
-     * compile's in `warnings`. An unset `output_format` falls back to the
-     * backend's first supported format. `today` reads as on `open`.
+     * with every `quill.validate` warning in `warnings`, a decline among the
+     * compile's and the rest ahead of them; the load's stay on `doc.warnings`.
+     * An unset `output_format` falls back to the backend's first supported
+     * format. `today` reads as on `open`.
      */
     render(quill: Quill, doc: Document, opts?: RenderOptions | null, today?: string | null): RenderResult;
     /**
@@ -1198,18 +1311,20 @@ export function exportMarkdown(rt: Content): string;
 export function formatDiagnostic(diagnostic: Diagnostic): string;
 
 /**
- * Serialize structured [`DocPathSeg`] segments back to the canonical path
+ * Serialize structured `DocPathSeg` segments back to the canonical path
  * string: the inverse of `parseDocPath`. Throws on a segment array the
  * deserializer rejects, and on an empty one.
  */
 export function formatDocPath(segs: DocPathSeg[]): string;
 
 /**
- * Import a markdown string to canonical `Content`: the pure, document-free
- * codec. `overwrite(addr, importMarkdown(md))` spells the cold, anchor-losing
- * write; prefer `revise` for edit semantics. Throws on an over-nested input.
+ * Import a markdown string: the pure, document-free codec. Returns the
+ * canonical `content` and a `parse::dropped_construct` warning per construct
+ * the import dropped, with no `path`. `overwrite(addr, importMarkdown(md).content)`
+ * spells the cold, anchor-losing write; prefer `revise` for edit semantics.
+ * Throws on an over-nested input.
  */
-export function importMarkdown(markdown: string): Content;
+export function importMarkdown(markdown: string): Imported;
 
 /**
  * Whether `content` satisfies the `inline` constraint of `richtext` and
@@ -1257,7 +1372,7 @@ 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 structured [`DocPathSeg`] segments, so
+ * `main.body`, `recipients[0].name`) into structured `DocPathSeg` segments, so
  * a consumer routes on segments instead of regexing the string. Throws on a
  * malformed path.
  */
@@ -1265,11 +1380,12 @@ export function parseDocPath(path: string): DocPathSeg[];
 
 /**
  * Rebase `markdown` onto a `base` content: the document-free twin of `revise`,
- * returning the new `content` and the text `delta` (offsets are USV indices into
- * `Content.text`, surviving anchors rebased). Throws on an over-nested markdown
- * input or a non-content `base`.
+ * returning the new `content`, the text `delta` (offsets are USV indices into
+ * `Content.text`, surviving anchors rebased), and the import's
+ * `parse::dropped_construct` warnings, with no `path`. Throws on an
+ * over-nested markdown input or a non-content `base`.
  */
-export function rebase(base: Content, markdown: string): { content: Content; delta: Delta };
+export function rebase(base: Content, markdown: string): { content: Content; delta: Delta; warnings: Diagnostic[] };
 
 /**
  * Runs at instantiation, so a Rust panic reaches the console as a stack trace
@@ -1292,6 +1408,7 @@ export interface InitOutput {
     readonly document__readerGet: (a: number, b: number, c: number, d: number) => void;
     readonly document__readerGetContent: (a: number, b: number, c: number, d: number) => void;
     readonly document__readerGetContentAt: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly document__reviseDocument: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly document__reviseField: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly document_applyChange: (a: number, b: number, c: number, d: number) => void;
     readonly document_bodyMarkdown: (a: number, b: number, c: number) => void;
@@ -1328,6 +1445,7 @@ export interface InitOutput {
     readonly document_storeField: (a: number, b: number, c: number, d: number) => void;
     readonly document_storeFields: (a: number, b: number, c: number, d: number) => void;
     readonly document_storeSeedOverlay: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly document_toAnnotatedMarkdown: (a: number, b: number) => void;
     readonly document_toMarkdown: (a: number, b: number) => void;
     readonly document_toStored: (a: number, b: number) => void;
     readonly document_warnings: (a: number, b: number) => void;
@@ -1338,6 +1456,7 @@ export interface InitOutput {
     readonly isInline: (a: number, b: number) => void;
     readonly isPlain: (a: number, b: number) => void;
     readonly livesession_backendId: (a: number, b: number) => void;
+    readonly livesession_coverage: (a: number, b: number) => void;
     readonly livesession_fieldAt: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly livesession_fieldBoxes: (a: number, b: number, c: number, d: number) => void;
     readonly livesession_locate: (a: number, b: number, c: number, d: number, e: number) => void;