@relyio/sdk 0.12.0 → 0.14.0

package/dist/rich-text.d-BWc-5gX1.d.cts

@@ -0,0 +1,326 @@
+/**
+ * Nesting composes through the declaration: a field's nested fields, each with the facets its own
+ * kind declares, under its key path (REL-1783). No package writes code per shape — an object's
+ * fields and a list item's fields are reached by the same walk, and each is declared by the kind it
+ * is.
+ *
+ * **An object's value and a list's items take a Shape** (REL-1796, REL-1799, ADR 0012): `config.of`
+ * is a fieldset, or several — a page builder for a list (REL-1798), one value of either shape for an
+ * object — and each item, and an object's one value, holds its fieldset's fields beside
+ * {@link LIST_ITEM_TYPE} (the fieldset's id) and {@link LIST_ITEM_KEY}. {@link shapesOf} is the one
+ * reading of `of`, for both kinds — every consumer asks it for a field's shapes and never reads
+ * `of` itself.
+ *
+ * **The path convention.** A path is its segments: the fields of an object's value and of a list's
+ * items sit under the field's id and the **item segment of their shape**, {@link itemSegmentOf} —
+ * `$` and the shape's id (`hero`, `$screenshot`, `alt`; `sections`, `$hero`, `heading`). Joined
+ * with `.`: `hero.$screenshot.alt`, `faq.$question.question`, `sections.$hero.heading`. An object's
+ * value is walked exactly as a list item is, so the walk path of an object's field and of a list
+ * item's look alike to every consumer, and an object is "a list of one" to anything that reads a
+ * path. The item segment names the shape because two shapes are two records: `heading` in `hero`
+ * and `heading` in `ctaBanner` are not one field (owner, REL-1990 item 2), so a change, a count or a
+ * rewrite of one never reaches the other's values, and a value walk takes only the values whose
+ * `_type` the segment names (`./values`). It names it for one shape too, so adding a second shape
+ * changes no path. A bare {@link LIST_ITEM_SEGMENT} is every item whatever its shape — what a caller
+ * writing a path by hand may still pass to `./values` — and the walk never produces it.
+ * `SchemaReader`'s own expansion (`ExpandedField.path`, `faq.$.question`) is the reader's spelling
+ * and is not this walk's; the validation document nests objects and AJV reports `/faq/0/question`
+ * and `/hero/alt`; and the design addresses one item by its key,
+ * `sections[_key=="f2k6ub9s"].heading`, and an object's field by its id, `hero.alt` — an object
+ * holds one value, so it needs no key in an address (`./item-keys`).
+ *
+ * Two differences from the reader's expansion are deliberate. The walk descends into shapes always,
+ * where the reader does only when asked; and it has no depth cap, where the reader stops at three
+ * levels of nesting (`maxDepth`). It stops at a shape that contains itself instead, and says so —
+ * deploy refuses such a schema (`FieldsetValidator`), so a served one has none.
+ *
+ * Structural, and dependency-free like `./declaration`: it reads `id`, `type` and `config.of` of a
+ * field and the `fields` of each shape and section, and nothing else.
+ *
+ * **A section adds no segment** (REL-1794). A type's `fields` — and a fieldset's — hold fields and
+ * fieldsets side by side, in one order; a fieldset placed there is a Section, whose fields join the
+ * record it sits in. So {@link walkMembers} reaches a section's fields under the path of the record
+ * the section sits in, exactly as if they had been declared beside it, and a read, a filter path, a
+ * reference path or a count never learns that a form groups them. {@link fieldsOfMembers} is the same
+ * flattening for a consumer that wants the fields and not their facets.
+ */
+
+/**
+ * The `_type` of an entry link: a rich-text mark linking text to another entry (REL-1808,
+ * `./rich-text`'s `RichTextEntryLinkMark`). Declared here, beside the walk that finds it.
+ */
+declare const RICH_TEXT_ENTRY_LINK_TYPE = "entryLink";
+
+/**
+ * Rich text's stored and served value: a tree we define (ADR 0013, REL-1803).
+ *
+ * A `richText` field holds one {@link RichTextValue} per locale — a documented, **versioned** JSON
+ * tree shaped like the editor's document: a quote and a list item hold blocks, lists nest, a text
+ * run names its marks. Every node carries `_type`; every node but a text run carries `_key`, unique
+ * within the field. It is not Portable Text (flat: a quote of two paragraphs becomes two quotes,
+ * nested lists become levels) and not TipTap's JSON (TipTap's node names and attributes would be
+ * our public API, and a TipTap upgrade a breaking change for customers). The vocabulary is written
+ * down for readers in `devtools/docs/guide/schema/field-types/rich-text-format.md`; this module is
+ * its one definition in code.
+ *
+ * **The version grows by addition.** {@link RICH_TEXT_VERSION} changes only when a node, a mark or
+ * an attribute is renamed, removed or reshaped. A new node type, a new mark, a new `list` style or a
+ * new optional attribute is not a version change — the docs set's built-ins (REL-1805: tables, task
+ * lists, code groups with tabs, highlight, sub- and superscript) arrived inside version 1, and P3b's
+ * entry links and declared blocks will, so a reader must treat a `_type` it does not know as content
+ * it cannot draw rather than as an error.
+ *
+ * **A field narrows the docs set** (REL-1805): its config's `structure`, `marks` and `multiline` are
+ * read by {@link richTextNarrowingOf}, held to on every write by {@link richTextNarrowingProblems}
+ * (the validation document's `x-richTextNarrowing` keyword), enforced in the editor by
+ * `@relyio/studio-core`'s `RichTextPolicy`, and applied by schema adaptation through
+ * {@link narrowRichText} when a field is narrowed over content it no longer allows.
+ *
+ * Who uses it: the projection writes and reads a live document by it (`@relyio/entry-projection`'s
+ * `./blocks`), the validation document holds a written value to it ({@link richTextProblems}), the
+ * write core keys a written value ({@link keyRichText}), the index embeds its text
+ * ({@link richTextPlainText}), and `@relyio/sdk` types a read by it (the types only, build-inlined
+ * through the package root).
+ *
+ * **Declared Blocks and Inline elements** (REL-1807): a field's `blocks` and `inline` name
+ * fieldsets an editor inserts between paragraphs and inside a sentence. Each stands in the tree as
+ * the fieldset's value — `{ _type: <fieldset id>, _key, …fields }`, exactly a page builder's item —
+ * wherever blocks, or inline content, go. A rich-text field of it is a tree of its own (a callout's
+ * title and body), whose keys are the field's. The tree's walk ({@link richTextProblems}) takes such
+ * a node by its `_type` and reads no schema; the field's narrowing says which it declares, and the
+ * shape's own validation fragment holds its fields.
+ *
+ * Dependency-free like `./declaration` (`__tests__/dependency-free.test.ts`): its runtime imports
+ * are `./walk`'s and `./declared-text`'s, inside the subpath.
+ */
+
+/** The format's version. The stored value carries it, so a reader knows which vocabulary it holds. */
+declare const RICH_TEXT_VERSION = 1;
+/** The root's `_type`: what a value of a `richText` field is. */
+declare const RICH_TEXT_TYPE = "richText";
+/**
+ * A rich-text field's value: the root of the tree. The root is the field, so it has no `_key`.
+ *
+ * `B` and `I` are the field's declared Blocks and Inline elements (REL-1807): the values of the
+ * fieldsets its `blocks` and `inline` name, each `{ _type, _key, …fields }` exactly as a page
+ * builder's item is. Both are `never` for a field that declares none, which is every built-in's
+ * reading; the SDK infers them from a field's config, so a read of a field declaring a callout is a
+ * tree that may hold one where blocks go.
+ */
+interface RichTextValue<B extends RichTextShapeValue = never, I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> {
+    readonly _type: typeof RICH_TEXT_TYPE;
+    readonly version: typeof RICH_TEXT_VERSION;
+    readonly children: ReadonlyArray<RichTextBlock<B, I, L>>;
+}
+/**
+ * A link to another entry (REL-1808): a **reference** — `to`, the target entry's id — and an optional
+ * `anchor`, a heading on it ({@link richTextHeadingAnchors}). A mark, as a link to a URL is, so it
+ * wraps any run of text and the formatting inside it. It may point only at the types its field's
+ * `links` names, and it is found, checked on publish, blocks or is nullified on its target's delete,
+ * purges and expands as every reference does: its walk path is `<field>.~entryLink.to`
+ * (`./walk`'s `richTextTreeSegmentOf`).
+ *
+ * `To` is what `to` holds: the id, as it is stored and written — and the target entry itself in a read
+ * whose include paths expand the field, as a reference field's id becomes the entry.
+ */
+interface RichTextEntryLinkMark<To = string> {
+    readonly _type: typeof RICH_TEXT_ENTRY_LINK_TYPE;
+    readonly to: To;
+    readonly anchor?: string;
+}
+/** An entry link, whatever its `to` holds: the third parameter of {@link RichTextValue}. */
+type AnyRichTextEntryLink = RichTextEntryLinkMark<unknown>;
+/** What every node but a text run carries: its identity within the field (design decision 10). */
+interface RichTextKeyed {
+    readonly _key: string;
+}
+/**
+ * What every declared Block and Inline element carries (REL-1807): the fieldset's id in `_type` and
+ * its Item key in `_key`, beside the fieldset's fields — the value a page builder's item of the same
+ * fieldset is. Its `_type` is never a built-in's name (deploy refuses such a fieldset in rich text,
+ * {@link RICH_TEXT_RESERVED_SHAPE_IDS}).
+ */
+interface RichTextShapeValue extends RichTextKeyed {
+    readonly _type: string;
+}
+/** A paragraph: inline content. */
+interface RichTextParagraph<I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'paragraph';
+    readonly children: ReadonlyArray<RichTextInline<I, L>>;
+}
+/** The heading levels, as numbers. */
+declare const RICH_TEXT_HEADING_LEVELS: readonly [1, 2, 3, 4, 5, 6];
+/**
+ * A heading of `level` 1 to 6: inline content. Its anchor — what an entry link's `anchor` names and
+ * the `id` a renderer gives it — is derived from its text ({@link richTextHeadingAnchors}).
+ */
+interface RichTextHeading<I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'heading';
+    readonly level: (typeof RICH_TEXT_HEADING_LEVELS)[number];
+    readonly children: ReadonlyArray<RichTextInline<I, L>>;
+}
+/** A quote: one block or more — a quote of two paragraphs is one quote. */
+interface RichTextQuote<B extends RichTextShapeValue = never, I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'quote';
+    readonly children: ReadonlyArray<RichTextBlock<B, I, L>>;
+}
+/**
+ * The list styles. Version 1 held `bullet` and `numbered`; REL-1805 added `task`, whose items each
+ * carry `checked`, without a version change.
+ */
+declare const RICH_TEXT_LIST_STYLES: readonly ['bullet', 'numbered', 'task'];
+type RichTextListStyle = (typeof RICH_TEXT_LIST_STYLES)[number];
+/**
+ * A list: one item or more. `start` is a numbered list's first number, present only when it is not
+ * `1`. Lists nest: an item holds blocks, and a list is a block.
+ */
+interface RichTextList<B extends RichTextShapeValue = never, I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'list';
+    readonly style: RichTextListStyle;
+    readonly start?: number;
+    readonly children: ReadonlyArray<RichTextListItem<B, I, L>>;
+}
+/**
+ * A list's item: blocks, the first of them a paragraph (the editor's model, `paragraph block*`).
+ * `checked` is a task list's item's, and present on every one of them: whether its task is done.
+ * An item of a bullet or a numbered list carries none.
+ */
+interface RichTextListItem<B extends RichTextShapeValue = never, I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'listItem';
+    readonly checked?: boolean;
+    readonly children: ReadonlyArray<RichTextBlock<B, I, L>>;
+}
+/** The lines of a file a code block is, 1-based and inclusive: the docs' code citations. */
+interface RichTextCodeLines {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * A block of code: its text exactly, newlines included, with no marks, and the `language` it is
+ * written in when one is named. Standing in a code group it is one of the group's tabs, and `label`
+ * is the tab's name; `filename` is the file it shows and `lines` which of that file's lines. All
+ * three are optional, alone or in a group (REL-1805).
+ */
+interface RichTextCodeBlock extends RichTextKeyed {
+    readonly _type: 'codeBlock';
+    readonly language?: string;
+    readonly label?: string;
+    readonly filename?: string;
+    readonly lines?: RichTextCodeLines;
+    readonly text: string;
+}
+/**
+ * Code with tabs: one code block or more, each a tab — the same snippet for another language,
+ * package manager or client (REL-1805). Each tab's text is its own, so two people typing in two tabs
+ * keep both. A `code` field holds this node as its value (REL-1806).
+ */
+interface RichTextCodeGroup extends RichTextKeyed {
+    readonly _type: 'codeGroup';
+    readonly children: readonly RichTextCodeBlock[];
+}
+/** How a table cell's text is aligned. Absent is the reader's default. */
+declare const RICH_TEXT_CELL_ALIGNMENTS: readonly ['left', 'center', 'right'];
+type RichTextCellAlignment = (typeof RICH_TEXT_CELL_ALIGNMENTS)[number];
+/**
+ * A table: one row or more, every row holding the same number of cells (REL-1805). `headerRow` is
+ * present, `true`, when the first row is the table's header. Cells hold formatted text, and nothing
+ * merges cells. A `table` field holds this node as its value (REL-1806).
+ */
+interface RichTextTable<I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'table';
+    readonly headerRow?: true;
+    readonly children: ReadonlyArray<RichTextTableRow<I, L>>;
+}
+/** A table's row: one cell or more. */
+interface RichTextTableRow<I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'tableRow';
+    readonly children: ReadonlyArray<RichTextTableCell<I, L>>;
+}
+/**
+ * A table's cell: one paragraph or more of formatted text, and its alignment when one is set. Its
+ * paragraphs hold the field's Inline elements as any paragraph does; never a declared Block.
+ */
+interface RichTextTableCell<I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'tableCell';
+    readonly align?: RichTextCellAlignment;
+    readonly children: ReadonlyArray<RichTextParagraph<I, L>>;
+}
+/** A horizontal rule between blocks. */
+interface RichTextDivider extends RichTextKeyed {
+    readonly _type: 'divider';
+}
+/**
+ * A block: what a field, a quote and a list item hold — a built-in, or one of the field's declared
+ * Blocks (`B`, REL-1807), which stand wherever blocks go and nowhere else.
+ */
+type RichTextBlock<B extends RichTextShapeValue = never, I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> = RichTextParagraph<I, L> | RichTextHeading<I, L> | RichTextQuote<B, I, L> | RichTextList<B, I, L> | RichTextCodeBlock | RichTextCodeGroup | RichTextTable<I, L> | RichTextDivider | B;
+/**
+ * A run of text: its characters and the marks on all of them. `marks` is absent when there are
+ * none, and in {@link RICH_TEXT_MARK_ORDER} when there are, each type at most once. A text run has no
+ * `_key`: it is not addressable apart from the block that holds it, and the live document gives it no
+ * identity to keep. `L` is the field's entry link (REL-1808), `never` for a field that declares no
+ * `links`.
+ */
+interface RichTextSpan<L extends AnyRichTextEntryLink = never> {
+    readonly _type: 'text';
+    readonly text: string;
+    readonly marks?: ReadonlyArray<RichTextMark | L>;
+}
+/** A line break inside a paragraph or a heading. */
+interface RichTextLineBreak extends RichTextKeyed {
+    readonly _type: 'lineBreak';
+}
+/**
+ * Inline content: what a paragraph and a heading hold — runs, line breaks, and the field's declared
+ * Inline elements (`I`, REL-1807) beside its text.
+ */
+type RichTextInline<I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> = RichTextSpan<L> | RichTextLineBreak | I;
+/**
+ * The marks a field's `marks` option names, in the order a run holds them: the link first, so a
+ * renderer that nests marks in this order wraps the formatting in the anchor. REL-1805 added
+ * highlight, subscript and superscript after the first six. The entry link (REL-1808) is not among
+ * them: a field allows it by naming the types it links to in `links`, not in `marks` (design
+ * decision 31), and it stands second in a run's order ({@link RICH_TEXT_MARK_ORDER}).
+ */
+declare const RICH_TEXT_MARK_TYPES: readonly ['link', 'bold', 'italic', 'underline', 'strike', 'code', 'highlight', 'subscript', 'superscript'];
+type RichTextMarkType = (typeof RICH_TEXT_MARK_TYPES)[number];
+/**
+ * A link to a URL. `href` is all a reader is given: whether it opens a new tab and which `rel` it
+ * carries are the site's rendering decisions, not content (the editor's defaults for them are not
+ * stored), and a link's title was dropped before the tree existed (REL-1942).
+ */
+interface RichTextLinkMark {
+    readonly _type: 'link';
+    readonly href: string;
+}
+/**
+ * A mark: formatting by name, or a link. `code` holds no other mark beside it, and `subscript` and
+ * `superscript` are never on one run together.
+ */
+type RichTextMark = RichTextLinkMark | {
+    readonly _type: Exclude<RichTextMarkType, 'link'>;
+};
+/** Any node of the tree below the root. */
+type RichTextNode<B extends RichTextShapeValue = never, I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> = RichTextBlock<B, I, L> | RichTextListItem<B, I, L> | RichTextTableRow<I, L> | RichTextTableCell<I, L> | RichTextInline<I, L>;
+/**
+ * The built-ins a field kind holds as its whole value (REL-1806): a `table` field holds a
+ * {@link RichTextTable}, a `code` field a {@link RichTextCodeGroup} — the very node a rich-text value
+ * holds among its blocks, so a value copied from one to the other is accepted unchanged. Each is read
+ * by {@link richTextFieldBlockProblems}, keyed by {@link keyRichTextFieldBlock} and searched by
+ * {@link richTextFieldBlockPlainText}.
+ */
+declare const RICH_TEXT_FIELD_BLOCK_TYPES: readonly ['table', 'codeGroup'];
+type RichTextFieldBlockType = (typeof RICH_TEXT_FIELD_BLOCK_TYPES)[number];
+/** A built-in a field holds as its whole value, by its `_type`. */
+type RichTextFieldBlock<T extends RichTextFieldBlockType = RichTextFieldBlockType> = Extract<RichTextBlock, {
+    readonly _type: T;
+}>;
+/**
+ * The built-in blocks a field's `structure` names (REL-1805): every block but the paragraph, which
+ * every field holds. A list is named by its style, since a field may want bullets and no tasks; a
+ * code group's tabs come with the group, whether or not `codeBlock` is named.
+ */
+declare const RICH_TEXT_STRUCTURES: readonly ['heading', 'quote', 'bulletList', 'numberedList', 'taskList', 'codeBlock', 'codeGroup', 'table', 'divider'];
+type RichTextStructure = (typeof RICH_TEXT_STRUCTURES)[number];
+
+export type { AnyRichTextEntryLink as A, RichTextTableRow as B, RichTextFieldBlockType as R, RichTextFieldBlock as a, RichTextValue as b, RichTextShapeValue as c, RichTextEntryLinkMark as d, RichTextBlock as e, RichTextCellAlignment as f, RichTextCodeBlock as g, RichTextCodeGroup as h, RichTextCodeLines as i, RichTextDivider as j, RichTextHeading as k, RichTextInline as l, RichTextLineBreak as m, RichTextLinkMark as n, RichTextList as o, RichTextListItem as p, RichTextListStyle as q, RichTextMark as r, RichTextMarkType as s, RichTextNode as t, RichTextParagraph as u, RichTextQuote as v, RichTextSpan as w, RichTextStructure as x, RichTextTable as y, RichTextTableCell as z };

package/dist/rich-text.d-BWc-5gX1.d.ts

@@ -0,0 +1,326 @@
+/**
+ * Nesting composes through the declaration: a field's nested fields, each with the facets its own
+ * kind declares, under its key path (REL-1783). No package writes code per shape — an object's
+ * fields and a list item's fields are reached by the same walk, and each is declared by the kind it
+ * is.
+ *
+ * **An object's value and a list's items take a Shape** (REL-1796, REL-1799, ADR 0012): `config.of`
+ * is a fieldset, or several — a page builder for a list (REL-1798), one value of either shape for an
+ * object — and each item, and an object's one value, holds its fieldset's fields beside
+ * {@link LIST_ITEM_TYPE} (the fieldset's id) and {@link LIST_ITEM_KEY}. {@link shapesOf} is the one
+ * reading of `of`, for both kinds — every consumer asks it for a field's shapes and never reads
+ * `of` itself.
+ *
+ * **The path convention.** A path is its segments: the fields of an object's value and of a list's
+ * items sit under the field's id and the **item segment of their shape**, {@link itemSegmentOf} —
+ * `$` and the shape's id (`hero`, `$screenshot`, `alt`; `sections`, `$hero`, `heading`). Joined
+ * with `.`: `hero.$screenshot.alt`, `faq.$question.question`, `sections.$hero.heading`. An object's
+ * value is walked exactly as a list item is, so the walk path of an object's field and of a list
+ * item's look alike to every consumer, and an object is "a list of one" to anything that reads a
+ * path. The item segment names the shape because two shapes are two records: `heading` in `hero`
+ * and `heading` in `ctaBanner` are not one field (owner, REL-1990 item 2), so a change, a count or a
+ * rewrite of one never reaches the other's values, and a value walk takes only the values whose
+ * `_type` the segment names (`./values`). It names it for one shape too, so adding a second shape
+ * changes no path. A bare {@link LIST_ITEM_SEGMENT} is every item whatever its shape — what a caller
+ * writing a path by hand may still pass to `./values` — and the walk never produces it.
+ * `SchemaReader`'s own expansion (`ExpandedField.path`, `faq.$.question`) is the reader's spelling
+ * and is not this walk's; the validation document nests objects and AJV reports `/faq/0/question`
+ * and `/hero/alt`; and the design addresses one item by its key,
+ * `sections[_key=="f2k6ub9s"].heading`, and an object's field by its id, `hero.alt` — an object
+ * holds one value, so it needs no key in an address (`./item-keys`).
+ *
+ * Two differences from the reader's expansion are deliberate. The walk descends into shapes always,
+ * where the reader does only when asked; and it has no depth cap, where the reader stops at three
+ * levels of nesting (`maxDepth`). It stops at a shape that contains itself instead, and says so —
+ * deploy refuses such a schema (`FieldsetValidator`), so a served one has none.
+ *
+ * Structural, and dependency-free like `./declaration`: it reads `id`, `type` and `config.of` of a
+ * field and the `fields` of each shape and section, and nothing else.
+ *
+ * **A section adds no segment** (REL-1794). A type's `fields` — and a fieldset's — hold fields and
+ * fieldsets side by side, in one order; a fieldset placed there is a Section, whose fields join the
+ * record it sits in. So {@link walkMembers} reaches a section's fields under the path of the record
+ * the section sits in, exactly as if they had been declared beside it, and a read, a filter path, a
+ * reference path or a count never learns that a form groups them. {@link fieldsOfMembers} is the same
+ * flattening for a consumer that wants the fields and not their facets.
+ */
+
+/**
+ * The `_type` of an entry link: a rich-text mark linking text to another entry (REL-1808,
+ * `./rich-text`'s `RichTextEntryLinkMark`). Declared here, beside the walk that finds it.
+ */
+declare const RICH_TEXT_ENTRY_LINK_TYPE = "entryLink";
+
+/**
+ * Rich text's stored and served value: a tree we define (ADR 0013, REL-1803).
+ *
+ * A `richText` field holds one {@link RichTextValue} per locale — a documented, **versioned** JSON
+ * tree shaped like the editor's document: a quote and a list item hold blocks, lists nest, a text
+ * run names its marks. Every node carries `_type`; every node but a text run carries `_key`, unique
+ * within the field. It is not Portable Text (flat: a quote of two paragraphs becomes two quotes,
+ * nested lists become levels) and not TipTap's JSON (TipTap's node names and attributes would be
+ * our public API, and a TipTap upgrade a breaking change for customers). The vocabulary is written
+ * down for readers in `devtools/docs/guide/schema/field-types/rich-text-format.md`; this module is
+ * its one definition in code.
+ *
+ * **The version grows by addition.** {@link RICH_TEXT_VERSION} changes only when a node, a mark or
+ * an attribute is renamed, removed or reshaped. A new node type, a new mark, a new `list` style or a
+ * new optional attribute is not a version change — the docs set's built-ins (REL-1805: tables, task
+ * lists, code groups with tabs, highlight, sub- and superscript) arrived inside version 1, and P3b's
+ * entry links and declared blocks will, so a reader must treat a `_type` it does not know as content
+ * it cannot draw rather than as an error.
+ *
+ * **A field narrows the docs set** (REL-1805): its config's `structure`, `marks` and `multiline` are
+ * read by {@link richTextNarrowingOf}, held to on every write by {@link richTextNarrowingProblems}
+ * (the validation document's `x-richTextNarrowing` keyword), enforced in the editor by
+ * `@relyio/studio-core`'s `RichTextPolicy`, and applied by schema adaptation through
+ * {@link narrowRichText} when a field is narrowed over content it no longer allows.
+ *
+ * Who uses it: the projection writes and reads a live document by it (`@relyio/entry-projection`'s
+ * `./blocks`), the validation document holds a written value to it ({@link richTextProblems}), the
+ * write core keys a written value ({@link keyRichText}), the index embeds its text
+ * ({@link richTextPlainText}), and `@relyio/sdk` types a read by it (the types only, build-inlined
+ * through the package root).
+ *
+ * **Declared Blocks and Inline elements** (REL-1807): a field's `blocks` and `inline` name
+ * fieldsets an editor inserts between paragraphs and inside a sentence. Each stands in the tree as
+ * the fieldset's value — `{ _type: <fieldset id>, _key, …fields }`, exactly a page builder's item —
+ * wherever blocks, or inline content, go. A rich-text field of it is a tree of its own (a callout's
+ * title and body), whose keys are the field's. The tree's walk ({@link richTextProblems}) takes such
+ * a node by its `_type` and reads no schema; the field's narrowing says which it declares, and the
+ * shape's own validation fragment holds its fields.
+ *
+ * Dependency-free like `./declaration` (`__tests__/dependency-free.test.ts`): its runtime imports
+ * are `./walk`'s and `./declared-text`'s, inside the subpath.
+ */
+
+/** The format's version. The stored value carries it, so a reader knows which vocabulary it holds. */
+declare const RICH_TEXT_VERSION = 1;
+/** The root's `_type`: what a value of a `richText` field is. */
+declare const RICH_TEXT_TYPE = "richText";
+/**
+ * A rich-text field's value: the root of the tree. The root is the field, so it has no `_key`.
+ *
+ * `B` and `I` are the field's declared Blocks and Inline elements (REL-1807): the values of the
+ * fieldsets its `blocks` and `inline` name, each `{ _type, _key, …fields }` exactly as a page
+ * builder's item is. Both are `never` for a field that declares none, which is every built-in's
+ * reading; the SDK infers them from a field's config, so a read of a field declaring a callout is a
+ * tree that may hold one where blocks go.
+ */
+interface RichTextValue<B extends RichTextShapeValue = never, I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> {
+    readonly _type: typeof RICH_TEXT_TYPE;
+    readonly version: typeof RICH_TEXT_VERSION;
+    readonly children: ReadonlyArray<RichTextBlock<B, I, L>>;
+}
+/**
+ * A link to another entry (REL-1808): a **reference** — `to`, the target entry's id — and an optional
+ * `anchor`, a heading on it ({@link richTextHeadingAnchors}). A mark, as a link to a URL is, so it
+ * wraps any run of text and the formatting inside it. It may point only at the types its field's
+ * `links` names, and it is found, checked on publish, blocks or is nullified on its target's delete,
+ * purges and expands as every reference does: its walk path is `<field>.~entryLink.to`
+ * (`./walk`'s `richTextTreeSegmentOf`).
+ *
+ * `To` is what `to` holds: the id, as it is stored and written — and the target entry itself in a read
+ * whose include paths expand the field, as a reference field's id becomes the entry.
+ */
+interface RichTextEntryLinkMark<To = string> {
+    readonly _type: typeof RICH_TEXT_ENTRY_LINK_TYPE;
+    readonly to: To;
+    readonly anchor?: string;
+}
+/** An entry link, whatever its `to` holds: the third parameter of {@link RichTextValue}. */
+type AnyRichTextEntryLink = RichTextEntryLinkMark<unknown>;
+/** What every node but a text run carries: its identity within the field (design decision 10). */
+interface RichTextKeyed {
+    readonly _key: string;
+}
+/**
+ * What every declared Block and Inline element carries (REL-1807): the fieldset's id in `_type` and
+ * its Item key in `_key`, beside the fieldset's fields — the value a page builder's item of the same
+ * fieldset is. Its `_type` is never a built-in's name (deploy refuses such a fieldset in rich text,
+ * {@link RICH_TEXT_RESERVED_SHAPE_IDS}).
+ */
+interface RichTextShapeValue extends RichTextKeyed {
+    readonly _type: string;
+}
+/** A paragraph: inline content. */
+interface RichTextParagraph<I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'paragraph';
+    readonly children: ReadonlyArray<RichTextInline<I, L>>;
+}
+/** The heading levels, as numbers. */
+declare const RICH_TEXT_HEADING_LEVELS: readonly [1, 2, 3, 4, 5, 6];
+/**
+ * A heading of `level` 1 to 6: inline content. Its anchor — what an entry link's `anchor` names and
+ * the `id` a renderer gives it — is derived from its text ({@link richTextHeadingAnchors}).
+ */
+interface RichTextHeading<I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'heading';
+    readonly level: (typeof RICH_TEXT_HEADING_LEVELS)[number];
+    readonly children: ReadonlyArray<RichTextInline<I, L>>;
+}
+/** A quote: one block or more — a quote of two paragraphs is one quote. */
+interface RichTextQuote<B extends RichTextShapeValue = never, I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'quote';
+    readonly children: ReadonlyArray<RichTextBlock<B, I, L>>;
+}
+/**
+ * The list styles. Version 1 held `bullet` and `numbered`; REL-1805 added `task`, whose items each
+ * carry `checked`, without a version change.
+ */
+declare const RICH_TEXT_LIST_STYLES: readonly ['bullet', 'numbered', 'task'];
+type RichTextListStyle = (typeof RICH_TEXT_LIST_STYLES)[number];
+/**
+ * A list: one item or more. `start` is a numbered list's first number, present only when it is not
+ * `1`. Lists nest: an item holds blocks, and a list is a block.
+ */
+interface RichTextList<B extends RichTextShapeValue = never, I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'list';
+    readonly style: RichTextListStyle;
+    readonly start?: number;
+    readonly children: ReadonlyArray<RichTextListItem<B, I, L>>;
+}
+/**
+ * A list's item: blocks, the first of them a paragraph (the editor's model, `paragraph block*`).
+ * `checked` is a task list's item's, and present on every one of them: whether its task is done.
+ * An item of a bullet or a numbered list carries none.
+ */
+interface RichTextListItem<B extends RichTextShapeValue = never, I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'listItem';
+    readonly checked?: boolean;
+    readonly children: ReadonlyArray<RichTextBlock<B, I, L>>;
+}
+/** The lines of a file a code block is, 1-based and inclusive: the docs' code citations. */
+interface RichTextCodeLines {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * A block of code: its text exactly, newlines included, with no marks, and the `language` it is
+ * written in when one is named. Standing in a code group it is one of the group's tabs, and `label`
+ * is the tab's name; `filename` is the file it shows and `lines` which of that file's lines. All
+ * three are optional, alone or in a group (REL-1805).
+ */
+interface RichTextCodeBlock extends RichTextKeyed {
+    readonly _type: 'codeBlock';
+    readonly language?: string;
+    readonly label?: string;
+    readonly filename?: string;
+    readonly lines?: RichTextCodeLines;
+    readonly text: string;
+}
+/**
+ * Code with tabs: one code block or more, each a tab — the same snippet for another language,
+ * package manager or client (REL-1805). Each tab's text is its own, so two people typing in two tabs
+ * keep both. A `code` field holds this node as its value (REL-1806).
+ */
+interface RichTextCodeGroup extends RichTextKeyed {
+    readonly _type: 'codeGroup';
+    readonly children: readonly RichTextCodeBlock[];
+}
+/** How a table cell's text is aligned. Absent is the reader's default. */
+declare const RICH_TEXT_CELL_ALIGNMENTS: readonly ['left', 'center', 'right'];
+type RichTextCellAlignment = (typeof RICH_TEXT_CELL_ALIGNMENTS)[number];
+/**
+ * A table: one row or more, every row holding the same number of cells (REL-1805). `headerRow` is
+ * present, `true`, when the first row is the table's header. Cells hold formatted text, and nothing
+ * merges cells. A `table` field holds this node as its value (REL-1806).
+ */
+interface RichTextTable<I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'table';
+    readonly headerRow?: true;
+    readonly children: ReadonlyArray<RichTextTableRow<I, L>>;
+}
+/** A table's row: one cell or more. */
+interface RichTextTableRow<I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'tableRow';
+    readonly children: ReadonlyArray<RichTextTableCell<I, L>>;
+}
+/**
+ * A table's cell: one paragraph or more of formatted text, and its alignment when one is set. Its
+ * paragraphs hold the field's Inline elements as any paragraph does; never a declared Block.
+ */
+interface RichTextTableCell<I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> extends RichTextKeyed {
+    readonly _type: 'tableCell';
+    readonly align?: RichTextCellAlignment;
+    readonly children: ReadonlyArray<RichTextParagraph<I, L>>;
+}
+/** A horizontal rule between blocks. */
+interface RichTextDivider extends RichTextKeyed {
+    readonly _type: 'divider';
+}
+/**
+ * A block: what a field, a quote and a list item hold — a built-in, or one of the field's declared
+ * Blocks (`B`, REL-1807), which stand wherever blocks go and nowhere else.
+ */
+type RichTextBlock<B extends RichTextShapeValue = never, I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> = RichTextParagraph<I, L> | RichTextHeading<I, L> | RichTextQuote<B, I, L> | RichTextList<B, I, L> | RichTextCodeBlock | RichTextCodeGroup | RichTextTable<I, L> | RichTextDivider | B;
+/**
+ * A run of text: its characters and the marks on all of them. `marks` is absent when there are
+ * none, and in {@link RICH_TEXT_MARK_ORDER} when there are, each type at most once. A text run has no
+ * `_key`: it is not addressable apart from the block that holds it, and the live document gives it no
+ * identity to keep. `L` is the field's entry link (REL-1808), `never` for a field that declares no
+ * `links`.
+ */
+interface RichTextSpan<L extends AnyRichTextEntryLink = never> {
+    readonly _type: 'text';
+    readonly text: string;
+    readonly marks?: ReadonlyArray<RichTextMark | L>;
+}
+/** A line break inside a paragraph or a heading. */
+interface RichTextLineBreak extends RichTextKeyed {
+    readonly _type: 'lineBreak';
+}
+/**
+ * Inline content: what a paragraph and a heading hold — runs, line breaks, and the field's declared
+ * Inline elements (`I`, REL-1807) beside its text.
+ */
+type RichTextInline<I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> = RichTextSpan<L> | RichTextLineBreak | I;
+/**
+ * The marks a field's `marks` option names, in the order a run holds them: the link first, so a
+ * renderer that nests marks in this order wraps the formatting in the anchor. REL-1805 added
+ * highlight, subscript and superscript after the first six. The entry link (REL-1808) is not among
+ * them: a field allows it by naming the types it links to in `links`, not in `marks` (design
+ * decision 31), and it stands second in a run's order ({@link RICH_TEXT_MARK_ORDER}).
+ */
+declare const RICH_TEXT_MARK_TYPES: readonly ['link', 'bold', 'italic', 'underline', 'strike', 'code', 'highlight', 'subscript', 'superscript'];
+type RichTextMarkType = (typeof RICH_TEXT_MARK_TYPES)[number];
+/**
+ * A link to a URL. `href` is all a reader is given: whether it opens a new tab and which `rel` it
+ * carries are the site's rendering decisions, not content (the editor's defaults for them are not
+ * stored), and a link's title was dropped before the tree existed (REL-1942).
+ */
+interface RichTextLinkMark {
+    readonly _type: 'link';
+    readonly href: string;
+}
+/**
+ * A mark: formatting by name, or a link. `code` holds no other mark beside it, and `subscript` and
+ * `superscript` are never on one run together.
+ */
+type RichTextMark = RichTextLinkMark | {
+    readonly _type: Exclude<RichTextMarkType, 'link'>;
+};
+/** Any node of the tree below the root. */
+type RichTextNode<B extends RichTextShapeValue = never, I extends RichTextShapeValue = never, L extends AnyRichTextEntryLink = never> = RichTextBlock<B, I, L> | RichTextListItem<B, I, L> | RichTextTableRow<I, L> | RichTextTableCell<I, L> | RichTextInline<I, L>;
+/**
+ * The built-ins a field kind holds as its whole value (REL-1806): a `table` field holds a
+ * {@link RichTextTable}, a `code` field a {@link RichTextCodeGroup} — the very node a rich-text value
+ * holds among its blocks, so a value copied from one to the other is accepted unchanged. Each is read
+ * by {@link richTextFieldBlockProblems}, keyed by {@link keyRichTextFieldBlock} and searched by
+ * {@link richTextFieldBlockPlainText}.
+ */
+declare const RICH_TEXT_FIELD_BLOCK_TYPES: readonly ['table', 'codeGroup'];
+type RichTextFieldBlockType = (typeof RICH_TEXT_FIELD_BLOCK_TYPES)[number];
+/** A built-in a field holds as its whole value, by its `_type`. */
+type RichTextFieldBlock<T extends RichTextFieldBlockType = RichTextFieldBlockType> = Extract<RichTextBlock, {
+    readonly _type: T;
+}>;
+/**
+ * The built-in blocks a field's `structure` names (REL-1805): every block but the paragraph, which
+ * every field holds. A list is named by its style, since a field may want bullets and no tasks; a
+ * code group's tabs come with the group, whether or not `codeBlock` is named.
+ */
+declare const RICH_TEXT_STRUCTURES: readonly ['heading', 'quote', 'bulletList', 'numberedList', 'taskList', 'codeBlock', 'codeGroup', 'table', 'divider'];
+type RichTextStructure = (typeof RICH_TEXT_STRUCTURES)[number];
+
+export type { AnyRichTextEntryLink as A, RichTextTableRow as B, RichTextFieldBlockType as R, RichTextFieldBlock as a, RichTextValue as b, RichTextShapeValue as c, RichTextEntryLinkMark as d, RichTextBlock as e, RichTextCellAlignment as f, RichTextCodeBlock as g, RichTextCodeGroup as h, RichTextCodeLines as i, RichTextDivider as j, RichTextHeading as k, RichTextInline as l, RichTextLineBreak as m, RichTextLinkMark as n, RichTextList as o, RichTextListItem as p, RichTextListStyle as q, RichTextMark as r, RichTextMarkType as s, RichTextNode as t, RichTextParagraph as u, RichTextQuote as v, RichTextSpan as w, RichTextStructure as x, RichTextTable as y, RichTextTableCell as z };