@relyio/sdk 0.10.0 → 0.12.0

package/dist/rich-text/index.d.cts

@@ -0,0 +1,148 @@
+import { w as RichTextValue, t as RichTextTable, c as RichTextCodeGroup, o as RichTextNode, r as RichTextSpan, m as RichTextMark } from '../rich-text.d-rKmpgdGd.cjs';
+
+/**
+ * The one walk of a rich-text tree into elements, for every output (REL-1804).
+ *
+ * Rich text is a versioned tree (ADR 0013, `RichTextValue`). What each built-in looks like by
+ * default — which element a node or a mark becomes, with which attributes, holding what — is
+ * written here once, generic over the output: {@link richTextToHtml} hands it a target that builds
+ * strings, `@relyio/react`'s `<RichText>` one that builds React elements. So the HTML a server
+ * writes and the markup `<RichText>` renders are one rendering by construction, not two kept equal
+ * by hand; a test over the corpus holds them byte for byte.
+ *
+ * Three rules every output inherits from this walk:
+ *
+ * - **Every tag is a literal here, never data.** A heading's level picks from a fixed table, and a
+ *   level the table lacks renders as a paragraph. An attribute's name is a literal too; its value is
+ *   the target's to escape.
+ * - **A link to an unsafe scheme is not a link.** An `href` is drawn only when it is relative or
+ *   `http:`, `https:`, `mailto:` or `tel:` ({@link safeRichTextHref}); any other scheme —
+ *   `javascript:`, `data:`, `vbscript:`, … — renders the link's text with no anchor, and a site's
+ *   own `link` renderer is never handed one.
+ * - **Version 1 grows by addition** (`rich-text-format.md`). The switches below cover every node
+ *   and mark of the vocabulary this build knows, with no fallback: a type added to it fails to
+ *   compile here until it is drawn. At run time a newer server can still send a `_type` this build
+ *   does not know; such a node renders nothing, and such a mark renders its text unformatted. Never
+ *   an error.
+ */
+
+/** Every element the default rendering of rich text uses. A tag is always one of these literals. */
+type RichTextTag = 'p' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'blockquote' | 'ul' | 'ol' | 'li' | 'input' | 'pre' | 'code' | 'figure' | 'figcaption' | 'div' | 'table' | 'thead' | 'tbody' | 'tr' | 'th' | 'td' | 'hr' | 'br' | 'a' | 'strong' | 'em' | 'u' | 's' | 'mark' | 'sub' | 'sup';
+/** The elements that hold nothing and have no closing tag. */
+declare const RICH_TEXT_VOID_TAGS: ReadonlySet<RichTextTag>;
+/**
+ * An element's attributes, in the order they are written. A value is a string or a number, or
+ * `true` for a boolean attribute that is present. `style` is a CSS declaration list (`text-align:center`).
+ */
+type RichTextAttributes = Readonly<Record<string, string | number | true>>;
+/** Every node a site may draw itself: all of them but a run of text, whose marks are drawn instead. */
+type RichTextReplaceableNode = Exclude<RichTextNode, RichTextSpan>;
+/** Where a node stands, for a renderer that draws it differently there. */
+interface RichTextNodeContext {
+    /** Whether a table row or cell is in the table's header row; `false` for every other node. */
+    readonly header: boolean;
+}
+/**
+ * What a walk of the tree builds with. {@link renderRichText} decides what each built-in becomes and
+ * calls `element` and `text` for it; `node` and `mark` are where an output may draw a node or a mark
+ * its own way, handed the default drawing to fall back on.
+ */
+interface RichTextTarget<Out> {
+    /** An element of the default rendering. `key` is the node's `_key` when the element is a node's own. */
+    element(tag: RichTextTag, attributes: RichTextAttributes | undefined, children: readonly Out[], key: string | undefined): Out;
+    /** Text, exactly as the tree holds it: the target escapes it. */
+    text(text: string): Out;
+    /**
+     * A node, given what it holds already drawn (`contents`) and the default drawing of it (`draw`).
+     * Return `draw(contents)` to draw it the default way.
+     */
+    node(node: RichTextReplaceableNode, contents: readonly Out[], draw: (contents: readonly Out[]) => Out, context: RichTextNodeContext): Out;
+    /**
+     * A mark around `contents`, the runs it covers already drawn. A link reaches it only with a safe
+     * `href`. Return `draw(contents)` to draw it the default way.
+     */
+    mark(mark: RichTextMark, contents: readonly Out[], draw: (contents: readonly Out[]) => Out): Out;
+}
+/**
+ * What the walk renders: a `richText` field's tree, or a `table` or `code` field's value — exactly
+ * one of the tree's built-ins (REL-1806), drawn as the same block is inside a tree, so a table field
+ * on a page and a table in a doc render the same markup.
+ */
+type RichTextRenderable = RichTextValue | RichTextTable | RichTextCodeGroup;
+/**
+ * Walk `value` into `target`'s output: one entry per block the tree holds, in order — or, for a
+ * `table` or `code` field's value, the one block it is. A block of a `_type` this build does not
+ * know adds nothing.
+ */
+declare function renderRichText<Out>(value: RichTextRenderable, target: RichTextTarget<Out>): Out[];
+/**
+ * `href` as a link may carry it, or `undefined` when it must not be one: not a string, empty, or
+ * naming a scheme outside `http:`, `https:`, `mailto:` and `tel:`. The scheme is read the way a
+ * browser reads it — leading and trailing controls and spaces stripped, tabs and newlines removed
+ * anywhere — so `" java\tscript:"` is the `javascript:` it runs as. The `href` returned is the one
+ * given; escaping it is the output's.
+ */
+declare function safeRichTextHref(href: unknown): string | undefined;
+
+/**
+ * Rich text as HTML (REL-1804): the default rendering ({@link renderRichText}) written as a string.
+ * No DOM and no dependency, so it runs the same in a browser, Node and a Worker.
+ */
+
+/**
+ * A rich-text value as HTML: every built-in drawn the way `<RichText>` from `@relyio/react` draws it
+ * with no components given, text and attributes escaped. `''` for an absent value. A `table` or
+ * `code` field's value — one of the tree's built-ins — is drawn as the same block inside a tree.
+ *
+ * - A link keeps its `href` only when it is relative or `http:`, `https:`, `mailto:` or `tel:`;
+ *   one to any other scheme (`javascript:`, `data:`, …) renders its text with no anchor.
+ * - A node of a `_type` this version of the SDK does not know — content a newer server sends —
+ *   renders nothing, and a mark it does not know leaves its text unformatted.
+ *
+ * @example
+ * ```ts
+ * import { richTextToHtml } from '@relyio/sdk'
+ *
+ * const post = await relyio.content('post').findById('hello').execute()
+ * const html = richTextToHtml(post?.body) // '<h2>Getting started</h2><p>Install the <code>SDK</code>…</p>'
+ * ```
+ */
+declare function richTextToHtml(value: RichTextRenderable | undefined): string;
+
+/**
+ * Rich text as plain Markdown (REL-1804): GitHub Flavored Markdown — CommonMark with tables, task
+ * lists and strikethrough — which drops what it cannot hold. RelyIO Markdown, the form that
+ * round-trips through directives for what plain Markdown lacks, is a separate serializer (REL-1809).
+ *
+ * What plain Markdown cannot hold, and what becomes of it:
+ *
+ * - The marks `underline`, `highlight`, `subscript` and `superscript`: their text, unformatted.
+ * - A code block's `filename`, `label` and line range: dropped; a code group's tabs follow one
+ *   another as fenced blocks.
+ * - A table's per-cell alignment: a column takes its first row's; a table with no header row gets
+ *   an empty one, since a Markdown table has to have one; a cell's paragraphs and line breaks join
+ *   with spaces.
+ * - A line break in a heading: a space. An empty paragraph or heading: nothing.
+ * - A link to a scheme other than `http:`, `https:`, `mailto:` and `tel:`: its text, as in HTML.
+ * - A node of a `_type` this version of the SDK does not know: nothing. A mark it does not know:
+ *   its text, unformatted.
+ *
+ * Text is escaped so it reads back as the same text: `*`, `_`, a bracket or a backtick in a
+ * sentence is a character, not syntax.
+ */
+
+/**
+ * A rich-text value as plain Markdown, ending in a newline; `''` for an absent or empty value. What
+ * Markdown cannot hold is dropped, its text kept (see the module's notes). A `table` or `code`
+ * field's value — one of the tree's built-ins — is written as the same block inside a tree.
+ *
+ * @example
+ * ```ts
+ * import { richTextToMarkdown } from '@relyio/sdk'
+ *
+ * richTextToMarkdown(post.body) // '## Getting started\n\nInstall the `SDK`, then read the [**guide**](/docs/guide).\n'
+ * ```
+ */
+declare function richTextToMarkdown(value: RichTextRenderable | undefined): string;
+
+export { RICH_TEXT_VOID_TAGS, type RichTextAttributes, type RichTextNodeContext, type RichTextRenderable, type RichTextReplaceableNode, type RichTextTag, type RichTextTarget, renderRichText, richTextToHtml, richTextToMarkdown, safeRichTextHref };

package/dist/rich-text/index.d.ts

@@ -0,0 +1,148 @@
+import { w as RichTextValue, t as RichTextTable, c as RichTextCodeGroup, o as RichTextNode, r as RichTextSpan, m as RichTextMark } from '../rich-text.d-rKmpgdGd.js';
+
+/**
+ * The one walk of a rich-text tree into elements, for every output (REL-1804).
+ *
+ * Rich text is a versioned tree (ADR 0013, `RichTextValue`). What each built-in looks like by
+ * default — which element a node or a mark becomes, with which attributes, holding what — is
+ * written here once, generic over the output: {@link richTextToHtml} hands it a target that builds
+ * strings, `@relyio/react`'s `<RichText>` one that builds React elements. So the HTML a server
+ * writes and the markup `<RichText>` renders are one rendering by construction, not two kept equal
+ * by hand; a test over the corpus holds them byte for byte.
+ *
+ * Three rules every output inherits from this walk:
+ *
+ * - **Every tag is a literal here, never data.** A heading's level picks from a fixed table, and a
+ *   level the table lacks renders as a paragraph. An attribute's name is a literal too; its value is
+ *   the target's to escape.
+ * - **A link to an unsafe scheme is not a link.** An `href` is drawn only when it is relative or
+ *   `http:`, `https:`, `mailto:` or `tel:` ({@link safeRichTextHref}); any other scheme —
+ *   `javascript:`, `data:`, `vbscript:`, … — renders the link's text with no anchor, and a site's
+ *   own `link` renderer is never handed one.
+ * - **Version 1 grows by addition** (`rich-text-format.md`). The switches below cover every node
+ *   and mark of the vocabulary this build knows, with no fallback: a type added to it fails to
+ *   compile here until it is drawn. At run time a newer server can still send a `_type` this build
+ *   does not know; such a node renders nothing, and such a mark renders its text unformatted. Never
+ *   an error.
+ */
+
+/** Every element the default rendering of rich text uses. A tag is always one of these literals. */
+type RichTextTag = 'p' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'blockquote' | 'ul' | 'ol' | 'li' | 'input' | 'pre' | 'code' | 'figure' | 'figcaption' | 'div' | 'table' | 'thead' | 'tbody' | 'tr' | 'th' | 'td' | 'hr' | 'br' | 'a' | 'strong' | 'em' | 'u' | 's' | 'mark' | 'sub' | 'sup';
+/** The elements that hold nothing and have no closing tag. */
+declare const RICH_TEXT_VOID_TAGS: ReadonlySet<RichTextTag>;
+/**
+ * An element's attributes, in the order they are written. A value is a string or a number, or
+ * `true` for a boolean attribute that is present. `style` is a CSS declaration list (`text-align:center`).
+ */
+type RichTextAttributes = Readonly<Record<string, string | number | true>>;
+/** Every node a site may draw itself: all of them but a run of text, whose marks are drawn instead. */
+type RichTextReplaceableNode = Exclude<RichTextNode, RichTextSpan>;
+/** Where a node stands, for a renderer that draws it differently there. */
+interface RichTextNodeContext {
+    /** Whether a table row or cell is in the table's header row; `false` for every other node. */
+    readonly header: boolean;
+}
+/**
+ * What a walk of the tree builds with. {@link renderRichText} decides what each built-in becomes and
+ * calls `element` and `text` for it; `node` and `mark` are where an output may draw a node or a mark
+ * its own way, handed the default drawing to fall back on.
+ */
+interface RichTextTarget<Out> {
+    /** An element of the default rendering. `key` is the node's `_key` when the element is a node's own. */
+    element(tag: RichTextTag, attributes: RichTextAttributes | undefined, children: readonly Out[], key: string | undefined): Out;
+    /** Text, exactly as the tree holds it: the target escapes it. */
+    text(text: string): Out;
+    /**
+     * A node, given what it holds already drawn (`contents`) and the default drawing of it (`draw`).
+     * Return `draw(contents)` to draw it the default way.
+     */
+    node(node: RichTextReplaceableNode, contents: readonly Out[], draw: (contents: readonly Out[]) => Out, context: RichTextNodeContext): Out;
+    /**
+     * A mark around `contents`, the runs it covers already drawn. A link reaches it only with a safe
+     * `href`. Return `draw(contents)` to draw it the default way.
+     */
+    mark(mark: RichTextMark, contents: readonly Out[], draw: (contents: readonly Out[]) => Out): Out;
+}
+/**
+ * What the walk renders: a `richText` field's tree, or a `table` or `code` field's value — exactly
+ * one of the tree's built-ins (REL-1806), drawn as the same block is inside a tree, so a table field
+ * on a page and a table in a doc render the same markup.
+ */
+type RichTextRenderable = RichTextValue | RichTextTable | RichTextCodeGroup;
+/**
+ * Walk `value` into `target`'s output: one entry per block the tree holds, in order — or, for a
+ * `table` or `code` field's value, the one block it is. A block of a `_type` this build does not
+ * know adds nothing.
+ */
+declare function renderRichText<Out>(value: RichTextRenderable, target: RichTextTarget<Out>): Out[];
+/**
+ * `href` as a link may carry it, or `undefined` when it must not be one: not a string, empty, or
+ * naming a scheme outside `http:`, `https:`, `mailto:` and `tel:`. The scheme is read the way a
+ * browser reads it — leading and trailing controls and spaces stripped, tabs and newlines removed
+ * anywhere — so `" java\tscript:"` is the `javascript:` it runs as. The `href` returned is the one
+ * given; escaping it is the output's.
+ */
+declare function safeRichTextHref(href: unknown): string | undefined;
+
+/**
+ * Rich text as HTML (REL-1804): the default rendering ({@link renderRichText}) written as a string.
+ * No DOM and no dependency, so it runs the same in a browser, Node and a Worker.
+ */
+
+/**
+ * A rich-text value as HTML: every built-in drawn the way `<RichText>` from `@relyio/react` draws it
+ * with no components given, text and attributes escaped. `''` for an absent value. A `table` or
+ * `code` field's value — one of the tree's built-ins — is drawn as the same block inside a tree.
+ *
+ * - A link keeps its `href` only when it is relative or `http:`, `https:`, `mailto:` or `tel:`;
+ *   one to any other scheme (`javascript:`, `data:`, …) renders its text with no anchor.
+ * - A node of a `_type` this version of the SDK does not know — content a newer server sends —
+ *   renders nothing, and a mark it does not know leaves its text unformatted.
+ *
+ * @example
+ * ```ts
+ * import { richTextToHtml } from '@relyio/sdk'
+ *
+ * const post = await relyio.content('post').findById('hello').execute()
+ * const html = richTextToHtml(post?.body) // '<h2>Getting started</h2><p>Install the <code>SDK</code>…</p>'
+ * ```
+ */
+declare function richTextToHtml(value: RichTextRenderable | undefined): string;
+
+/**
+ * Rich text as plain Markdown (REL-1804): GitHub Flavored Markdown — CommonMark with tables, task
+ * lists and strikethrough — which drops what it cannot hold. RelyIO Markdown, the form that
+ * round-trips through directives for what plain Markdown lacks, is a separate serializer (REL-1809).
+ *
+ * What plain Markdown cannot hold, and what becomes of it:
+ *
+ * - The marks `underline`, `highlight`, `subscript` and `superscript`: their text, unformatted.
+ * - A code block's `filename`, `label` and line range: dropped; a code group's tabs follow one
+ *   another as fenced blocks.
+ * - A table's per-cell alignment: a column takes its first row's; a table with no header row gets
+ *   an empty one, since a Markdown table has to have one; a cell's paragraphs and line breaks join
+ *   with spaces.
+ * - A line break in a heading: a space. An empty paragraph or heading: nothing.
+ * - A link to a scheme other than `http:`, `https:`, `mailto:` and `tel:`: its text, as in HTML.
+ * - A node of a `_type` this version of the SDK does not know: nothing. A mark it does not know:
+ *   its text, unformatted.
+ *
+ * Text is escaped so it reads back as the same text: `*`, `_`, a bracket or a backtick in a
+ * sentence is a character, not syntax.
+ */
+
+/**
+ * A rich-text value as plain Markdown, ending in a newline; `''` for an absent or empty value. What
+ * Markdown cannot hold is dropped, its text kept (see the module's notes). A `table` or `code`
+ * field's value — one of the tree's built-ins — is written as the same block inside a tree.
+ *
+ * @example
+ * ```ts
+ * import { richTextToMarkdown } from '@relyio/sdk'
+ *
+ * richTextToMarkdown(post.body) // '## Getting started\n\nInstall the `SDK`, then read the [**guide**](/docs/guide).\n'
+ * ```
+ */
+declare function richTextToMarkdown(value: RichTextRenderable | undefined): string;
+
+export { RICH_TEXT_VOID_TAGS, type RichTextAttributes, type RichTextNodeContext, type RichTextRenderable, type RichTextReplaceableNode, type RichTextTag, type RichTextTarget, renderRichText, richTextToHtml, richTextToMarkdown, safeRichTextHref };

package/dist/rich-text/index.js

@@ -0,0 +1,4 @@
+export { RICH_TEXT_VOID_TAGS, renderRichText, richTextToHtml, richTextToMarkdown, safeRichTextHref } from '../chunk-3DRDHXLY.js';
+import '../chunk-XQ4QHWZE.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/rich-text.d-rKmpgdGd.d.cts

@@ -0,0 +1,200 @@
+/**
+ * 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).
+ *
+ * Dependency-free like `./declaration` (`__tests__/dependency-free.test.ts`): no import at all.
+ */
+/** 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`. */
+interface RichTextValue {
+    readonly _type: typeof RICH_TEXT_TYPE;
+    readonly version: typeof RICH_TEXT_VERSION;
+    readonly children: readonly RichTextBlock[];
+}
+/** What every node but a text run carries: its identity within the field (design decision 10). */
+interface RichTextKeyed {
+    readonly _key: string;
+}
+/** A paragraph: inline content. */
+interface RichTextParagraph extends RichTextKeyed {
+    readonly _type: 'paragraph';
+    readonly children: readonly RichTextInline[];
+}
+/** 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. */
+interface RichTextHeading extends RichTextKeyed {
+    readonly _type: 'heading';
+    readonly level: (typeof RICH_TEXT_HEADING_LEVELS)[number];
+    readonly children: readonly RichTextInline[];
+}
+/** A quote: one block or more — a quote of two paragraphs is one quote. */
+interface RichTextQuote extends RichTextKeyed {
+    readonly _type: 'quote';
+    readonly children: readonly RichTextBlock[];
+}
+/**
+ * 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 extends RichTextKeyed {
+    readonly _type: 'list';
+    readonly style: RichTextListStyle;
+    readonly start?: number;
+    readonly children: readonly RichTextListItem[];
+}
+/**
+ * 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 extends RichTextKeyed {
+    readonly _type: 'listItem';
+    readonly checked?: boolean;
+    readonly children: readonly RichTextBlock[];
+}
+/** 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 extends RichTextKeyed {
+    readonly _type: 'table';
+    readonly headerRow?: true;
+    readonly children: readonly RichTextTableRow[];
+}
+/** A table's row: one cell or more. */
+interface RichTextTableRow extends RichTextKeyed {
+    readonly _type: 'tableRow';
+    readonly children: readonly RichTextTableCell[];
+}
+/** A table's cell: one paragraph or more of formatted text, and its alignment when one is set. */
+interface RichTextTableCell extends RichTextKeyed {
+    readonly _type: 'tableCell';
+    readonly align?: RichTextCellAlignment;
+    readonly children: readonly RichTextParagraph[];
+}
+/** A horizontal rule between blocks. */
+interface RichTextDivider extends RichTextKeyed {
+    readonly _type: 'divider';
+}
+/** A block: what a field, a quote and a list item hold. */
+type RichTextBlock = RichTextParagraph | RichTextHeading | RichTextQuote | RichTextList | RichTextCodeBlock | RichTextCodeGroup | RichTextTable | RichTextDivider;
+/**
+ * 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_TYPES}' 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.
+ */
+interface RichTextSpan {
+    readonly _type: 'text';
+    readonly text: string;
+    readonly marks?: readonly RichTextMark[];
+}
+/** 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. */
+type RichTextInline = RichTextSpan | RichTextLineBreak;
+/**
+ * The marks, 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, and P3b adds the entry link, without a version change.
+ */
+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 = RichTextBlock | RichTextListItem | RichTextTableRow | RichTextTableCell | RichTextInline;
+/**
+ * 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 { RichTextBlock as R, RichTextCellAlignment as a, RichTextCodeBlock as b, RichTextCodeGroup as c, RichTextCodeLines as d, RichTextDivider as e, RichTextHeading as f, RichTextInline as g, RichTextLineBreak as h, RichTextLinkMark as i, RichTextList as j, RichTextListItem as k, RichTextListStyle as l, RichTextMark as m, RichTextMarkType as n, RichTextNode as o, RichTextParagraph as p, RichTextQuote as q, RichTextSpan as r, RichTextStructure as s, RichTextTable as t, RichTextTableCell as u, RichTextTableRow as v, RichTextValue as w };