@relyio/sdk 0.12.0 → 0.14.0

package/dist/index-C-pcllqY.d.cts

@@ -0,0 +1,507 @@
+import { k as RichTextHeading, b as RichTextValue, y as RichTextTable, h as RichTextCodeGroup, e as RichTextBlock, l as RichTextInline, t as RichTextNode, w as RichTextSpan, r as RichTextMark, A as AnyRichTextEntryLink, c as RichTextShapeValue } from './rich-text.d-BWc-5gX1.cjs';
+import { cs as BaseContent } from './define-content-type-BUZeWtpk.cjs';
+
+/**
+ * The DOM↔field binding contract, as the one pure helper that emits it.
+ *
+ * Spread onto the element that renders a field, it stamps which entry, content type, field and
+ * locale produced that element, so an editing surface can find the field by scanning the DOM
+ * rather than by guessing (`INV-TB-BINDING`). The contract is `toolbar-spec.md` §DOM↔field; this
+ * file is its only implementation.
+ *
+ * **Frozen** (`INV-SS-BINDING-FROZEN`). The attribute set is exactly the five below. Adding,
+ * renaming or dropping one is a new contract, and a new contract is a bump of `data-relyio-v` — a
+ * page built against version 1 keeps being read as version 1 by any surface that scans it.
+ *
+ * **Pure** (`INV-TB-SDK-PURE`). It reads the entry it is handed and returns attributes. It imports
+ * nothing but the SDK's own types: no realtime, no AI, no first-party code, no framework. That is
+ * what lets it live in the customer SDK and run on a server render as happily as in a browser.
+ *
+ * **Every value comes from the entry.** The id, the content type and the locale are the ones the
+ * API reported in `_metadata` — the locale is the one the payload's field values were composed
+ * for. There is deliberately no `locale` argument: a caller-supplied locale could bind a node to a
+ * locale whose value it is not rendering, which is the silently inferred binding `INV-TB-BINDING`
+ * forbids.
+ *
+ * **The field is a path** (REL-1814). `data-relyio-field` has always named the binding's field path
+ * (`toolbar-spec.md`'s `(entryId, fieldPath, locale)`); it reaches into structure by key — a block of
+ * a page builder, a field of it, a declared Block in rich text — in the spelling every other surface
+ * names such a value by (`./key-path.ts`), so the attribute set and the version are unchanged. A
+ * binding continues into what it binds (`relyioField(binding, 'heading')`, `relyioField(binding,
+ * item)`), which is how `@relyio/react`'s `<Blocks>` and `<RichText>` stamp each item they render.
+ */
+
+/** The version of the binding contract this helper emits. */
+declare const BINDING_VERSION = "1";
+/** The attributes `relyioField` returns — the whole of binding contract version 1. */
+interface RelyIOFieldAttributes {
+    /** The entry's id (`_metadata.id`). */
+    readonly 'data-relyio-entry': string;
+    /** The entry's content type (`_metadata.type`); every customer read is keyed by it. */
+    readonly 'data-relyio-type': string;
+    /**
+     * The field the element renders: its id, or a key path into it — `sections[_key=="k1"].heading`
+     * (REL-1814).
+     */
+    readonly 'data-relyio-field': string;
+    /** The locale the entry's field values were composed for (`_metadata.locale`). */
+    readonly 'data-relyio-locale': string;
+    /** The binding contract's version. */
+    readonly 'data-relyio-v': typeof BINDING_VERSION;
+}
+/**
+ * The field names `relyioField` accepts for an entry of type `T`.
+ *
+ * A schema-typed entry narrows to its declared field names, so they autocomplete and a misspelt
+ * one does not compile. An entry with no declared fields — `BaseContent`, which is what an
+ * un-generated client returns — has none to narrow to, and `keyof` of it is `never`; that would
+ * make the helper uncallable for every untyped customer, so it accepts any field name instead.
+ */
+type RelyIOFieldName<T extends BaseContent> = [Exclude<keyof T, '_metadata'>] extends [never] ? string : string & Exclude<keyof T, '_metadata'>;
+/**
+ * The fields of `T` a key path may reach into: those holding a list, an object's value or rich text —
+ * each a value that names its shape in `_type`, or an array of items. A text, number or reference
+ * field holds nothing a path can name.
+ */
+type StructuredFieldName<T extends BaseContent> = {
+    [Name in Exclude<keyof T, '_metadata'> & string]: [NonNullable<T[Name]>] extends [
+        ReadonlyArray<unknown> | {
+            readonly _type: string;
+        }
+    ] ? Name : never;
+}[Exclude<keyof T, '_metadata'> & string];
+/**
+ * What `relyioField(entry, path)` accepts for an entry of type `T` (REL-1814): a field's name, or a
+ * key path into a field holding structure — `sections[_key=="k1"].heading`, `hero.title`,
+ * `body[_key=="c1"]`. Its first step is held to `T`'s fields; what follows is checked when it runs,
+ * and an editor's resolver refuses a path the entry's schema does not know.
+ */
+type RelyIOFieldPath<T extends BaseContent> = [Exclude<keyof T, '_metadata'>] extends [never] ? string : RelyIOFieldName<T> | `${StructuredFieldName<T>}.${string}` | `${StructuredFieldName<T>}[_key==${string}`;
+/** An item a binding continues to: anything carrying its `_key`, as every list item and block does. */
+interface RelyIOKeyed {
+    readonly _key: string;
+}
+/**
+ * Binding attributes for one field of one entry, or for a value inside it by key path.
+ *
+ * @example
+ * ```tsx
+ * import { relyioField } from '@relyio/sdk'
+ *
+ * <h1 {...relyioField(post, 'title')}>{post.title}</h1>
+ * // → data-relyio-entry="6710f…" data-relyio-type="post" data-relyio-field="title"
+ * //   data-relyio-locale="en-US" data-relyio-v="1"
+ *
+ * <h2 {...relyioField(page, 'sections[_key=="f2k6ub9s"].heading')}>…</h2>
+ * ```
+ *
+ * @throws {TypeError} when the entry's `_metadata` lacks its id, content type or locale. Every
+ * entry the API returns carries all three, so this is reached only by a value that was not read
+ * from RelyIO. It throws rather than emitting a partial binding: a node stamped with no locale, or
+ * none at all, is a binding a surface would have to guess the rest of. And when `path` is not a
+ * field or a key path — an index (`sections[0]`) names another item once the list is reordered.
+ */
+declare function relyioField<T extends BaseContent>(entry: T, path: RelyIOFieldPath<T>): RelyIOFieldAttributes;
+/**
+ * The binding of a value inside one `relyioField` returned (REL-1814): a field below it — `heading`,
+ * `actions[_key=="b"].label` — or an item of the list (or rich text) it binds. What `<Blocks>` and
+ * `<RichText>` stamp each item with, and how a component binds what it renders inside its block:
+ *
+ * @example
+ * ```tsx
+ * <Blocks
+ *   value={page.sections}
+ *   field={relyioField(page, 'sections')}
+ *   components={{
+ *     hero: (block, field) => (
+ *       <header>
+ *         <h1 {...relyioField(field, 'headline')}>{block.headline}</h1>
+ *       </header>
+ *     ),
+ *   }}
+ * />
+ * ```
+ *
+ * No binding — a renderer handed none — binds nothing: `undefined`, which spreads as no attribute.
+ *
+ * @throws {TypeError} when `binding` is not one `relyioField` returned, or the path it makes is not a
+ * key path — an item of an item, an item with no key.
+ */
+declare function relyioField(binding: RelyIOFieldAttributes, path: string | RelyIOKeyed): RelyIOFieldAttributes;
+declare function relyioField(binding: RelyIOFieldAttributes | undefined, path: string | RelyIOKeyed): RelyIOFieldAttributes | undefined;
+
+/**
+ * A heading's anchor (REL-1808): the `id` every renderer gives a heading, and what an entry link's
+ * `anchor` names — so a site's `#anchor` lands on it.
+ *
+ * The rule is `@relyio/schema`'s `richTextHeadingSlug` and `richTextEntryHeadingAnchors`, restated
+ * here because this package takes no runtime from that one (it is build-inlined for types only);
+ * `devtools/verification`'s `rich-text-anchors-sdk.test.ts` holds the two to one corpus, as the server
+ * checks an entry link's anchor against the schema's on publish. GitHub's: the heading's text
+ * (a line break a space) trimmed and lower-cased, every character that is not a letter, a digit, a
+ * combining mark, a space, a hyphen or an underscore removed, each space a hyphen; a second heading
+ * of one text `setup-1`, a third `setup-2`; a heading with no such character has no anchor.
+ *
+ * Anchors are unique **per entry** (REL-2110): the headings of an entry's top-level rich-text fields
+ * are numbered across them in the order its type declares the fields — `intro`'s "Overview" is
+ * `overview`, `body`'s `overview-1` — and a read returns an entry's fields in that order, so
+ * {@link entryHeadingAnchors} needs nothing but the entry.
+ */
+
+/** A heading's anchor from its text, `''` when it has none: `UI options` is `ui-options`. */
+declare function richTextHeadingSlug(text: string): string;
+/**
+ * Every heading of one rich-text value with its anchor, in document order, numbered within that
+ * value alone — the tree's own headings at any depth, not those inside a declared block, whose
+ * component draws them. What a field rendered with no entry around it gives its headings; for an
+ * entry with several rich-text fields, {@link entryHeadingAnchors} numbers them across the fields.
+ */
+declare function richTextHeadingAnchors(value: unknown): ReadonlyMap<RichTextHeading<never, never>, string>;
+/**
+ * Every heading of an entry's rich-text fields with its anchor (REL-2110): each top-level field
+ * holding a rich-text value, in the order the entry holds them — a read returns an entry's fields in
+ * the order its type declares them — and each value's document order, numbered across the entry. So
+ * `intro`'s "Overview" is `overview` and `body`'s `overview-1`, the anchors the server checks an
+ * entry link's `anchor` against. Hand it to `<RichText anchors>` or `richTextToHtml`'s `anchors` for
+ * each field of the entry, and read a heading's `id` from it where you draw headings yourself.
+ *
+ * Pass the entry as the read returned it, in one locale and with every rich-text field before the
+ * one you render: a field left out of the read, or a value moved, numbers the headings after it
+ * differently.
+ *
+ * @example
+ * ```ts
+ * const anchors = entryHeadingAnchors(page)
+ * const html = richTextToHtml(page.intro, { anchors }) + richTextToHtml(page.body, { anchors })
+ * ```
+ */
+declare function entryHeadingAnchors(entry: object | null | undefined): ReadonlyMap<RichTextHeading<never, never>, string>;
+
+/**
+ * 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.
+ * - **A declared Block or Inline element is the site's to draw** (REL-1807): RelyIO cannot know what a
+ *   callout or a glossary term looks like, so the walk hands each to the target's `declared` — a
+ *   node whose `_type` is no built-in's — and draws what it returns, nothing for `undefined`.
+ *   `<RichText>` requires a component for every one the field declares; `richTextToHtml` and
+ *   `richTextToMarkdown` take a function for each, likewise required.
+ * - **An entry link is the site's to draw too** (REL-1808): only the site knows its own URLs, so the
+ *   walk hands each, with the runs it covers drawn, to the target's `entryLink`. Every output
+ *   requires one wherever the field declares `links`.
+ * - **A heading carries its anchor as its `id`** (REL-1808, `./anchors.ts`): the slug of its text,
+ *   deduplicated across the entry, the very anchor an entry link names — so a link's `#anchor`
+ *   lands. A walk handed `anchors` (`entryHeadingAnchors(entry)`, REL-2110) reads each heading's
+ *   there; one handed none numbers the value's own headings alone.
+ */
+
+/** 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;
+    /**
+     * An entry link around `contents`, the runs it covers already drawn (REL-1808): the site's own
+     * drawing — RelyIO cannot know its URLs. `to` is the linked entry's id, or the entry where the read
+     * included the field.
+     */
+    entryLink(link: AnyRichTextEntryLink, contents: readonly Out[]): Out;
+    /**
+     * A declared Block (`block`, where blocks go) or Inline element (`inline`, beside a paragraph's
+     * text) — REL-1807: the site's own drawing of it, or `undefined` to draw nothing.
+     */
+    declared(node: RichTextShapeValue, place: 'block' | 'inline'): Out | undefined;
+}
+/** Whether a node is a declared Block or Inline element: an object whose `_type` no built-in takes. */
+declare function isDeclaredRichTextNode(node: unknown): boolean;
+type ChildrenOf<V> = V extends {
+    readonly children: ReadonlyArray<infer Child>;
+} ? Child : never;
+/** A rich-text field's tree, of a union holding one; a `table` or `code` field's value is not. */
+type TreeOf<V> = Extract<V, {
+    readonly _type: 'richText';
+}>;
+/**
+ * The declared Blocks a rich-text value may hold (REL-1807): its children that are no built-in —
+ * the fieldsets its field's `blocks` names, each its value. `never` for a field that declares none.
+ */
+type RichTextBlocksOf<V> = Exclude<ChildrenOf<TreeOf<V>>, {
+    readonly _type: RichTextBlock['_type'];
+}>;
+/** The declared Inline elements a rich-text value's paragraphs may hold (REL-1807); `never` for none. */
+type RichTextInlineOf<V> = Exclude<ChildrenOf<Extract<ChildrenOf<TreeOf<V>>, {
+    readonly _type: 'paragraph';
+}>>, {
+    readonly _type: RichTextInline['_type'];
+}>;
+/** Every declared Block and Inline element a rich-text value may hold, as one union. */
+type RichTextDeclaredOf<V> = RichTextBlocksOf<V> | RichTextInlineOf<V>;
+/** The `_type`s of {@link RichTextDeclaredOf}. */
+type DeclaredTypeOf<V> = RichTextDeclaredOf<V> extends infer Node ? Node extends {
+    readonly _type: infer Type extends string;
+} ? Type : never : never;
+/**
+ * A function for every declared Block and Inline element a value may hold, keyed by its `_type` and
+ * handed exactly its value — what `richTextToHtml` and `richTextToMarkdown` take as `declared`.
+ */
+type RichTextDeclaredWriters<V, Out> = {
+    readonly [Type in DeclaredTypeOf<V>]: (value: Extract<RichTextDeclaredOf<V>, {
+        readonly _type: Type;
+    }>) => 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;
+/**
+ * A renderable value of any field, its declared Blocks and Inline elements whatever they are: what a
+ * walk takes, and what `<RichText>`'s value is held to.
+ */
+type RichTextRenderableOf = RichTextValue<any, any, any> | RichTextTable<any, any> | RichTextCodeGroup;
+/**
+ * The entry link a rich-text value's runs may carry (REL-1808): the mark, its `to` an id or — where the
+ * read included the field — the entry. `never` for a field that declares no `links`.
+ */
+type RichTextEntryLinkOf<V> = [TreeOf<V>] extends [never] ? never : TreeOf<V> extends RichTextValue<infer _B, infer _I, infer L> ? L : never;
+/**
+ * What an output takes for an entry link (REL-1808): nothing for a value whose field declares no
+ * `links`; for one that does, `entryLink` — the site's drawing of a link, handed the link and what it
+ * covers already written, since only the site knows its URLs. The compiler requires it there.
+ */
+type RichTextEntryLinkOption<V, Out> = [RichTextEntryLinkOf<V>] extends [never] ? {
+    readonly entryLink?: never;
+} : {
+    readonly entryLink: (link: RichTextEntryLinkOf<V>, contents: Out) => Out;
+};
+/**
+ * What every output takes to give a field's headings the anchors of the entry it belongs to
+ * (REL-2110): an entry's headings are numbered across its rich-text fields, so `body`'s "Overview"
+ * is `overview-1` where `intro` already has one.
+ */
+interface RichTextAnchorsOption {
+    /**
+     * Each heading's anchor, by the heading — `entryHeadingAnchors(entry)` for the entry the value
+     * belongs to. A heading it does not hold renders with no `id`. Absent, the value's own headings
+     * are numbered alone (`richTextHeadingAnchors(value)`), which is right for an entry with one
+     * rich-text field.
+     */
+    readonly anchors?: ReadonlyMap<object, string>;
+}
+/**
+ * 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. `options.anchors` gives the headings their entry's anchors.
+ */
+declare function renderRichText<Out>(value: RichTextRenderableOf, target: RichTextTarget<Out>, options?: RichTextAnchorsOption): 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.
+ *
+ * **Each declared Block and Inline element carries its key path** (REL-2142), as `<RichText>` from
+ * `@relyio/react` stamps it (REL-1814). Handed the field's binding — `field: relyioField(post,
+ * 'body')` — each declared node's writer is handed that node's binding, `body[_key=="c1"]`, and the
+ * HTML it returns is stamped with it when it is exactly one element: the binding's attributes after
+ * the element's own, as React writes the props `<RichText>` stamps. Anything else — text, several
+ * elements, a comment — is written as it is, and the writer, holding the binding, writes it where it
+ * belongs; a root carrying `data-relyio-entry` already was bound by its writer and keeps its own.
+ */
+
+/**
+ * `text` with every character HTML gives a meaning escaped — `&`, `<`, `>`, `"` and `'` — as React
+ * escapes them, so this file's output and `<RichText>`'s server render are the same bytes.
+ */
+declare function escapeHtml(text: string): string;
+/**
+ * What `richTextToHtml` takes beside the value: nothing for a field that declares no Block or Inline
+ * element; for one that does, `declared` — a function per declared `_type`, each returning that
+ * node's HTML (REL-1807). RelyIO cannot know what a callout looks like, so the compiler holds the
+ * map to every one the field declares, and to none it does not. What it returns is written as it is,
+ * stamped with the node's key path when `field` is given (REL-2142): escaping text the node holds is
+ * the function's ({@link escapeHtml}).
+ */
+type RichTextHtmlOptions<V> = [RichTextDeclaredOf<V> | RichTextEntryLinkOf<V>] extends [
+    never
+] ? [
+    options?: {
+        readonly declared?: Record<string, never>;
+        readonly entryLink?: never;
+    } & RichTextAnchorsOption & RichTextHtmlFieldOption
+] : [
+    options: DeclaredHtmlOption<V> & RichTextEntryLinkOption<V, string> & RichTextAnchorsOption & RichTextHtmlFieldOption
+];
+/** The binding of the field the value is (REL-2142), which each declared node's key path continues. */
+interface RichTextHtmlFieldOption {
+    /**
+     * The field's binding — `relyioField(post, 'body')`, or `relyioField(field, 'body')` inside a
+     * declared node's writer — so each declared Block and Inline element is stamped with its key path.
+     * Absent, nothing is stamped and each writer is handed `undefined`.
+     */
+    readonly field?: RelyIOFieldAttributes;
+}
+/**
+ * A function for every declared Block and Inline element a value may hold, keyed by its `_type`:
+ * handed exactly its value, and its binding — `body[_key=="c1"]` — when `richTextToHtml` was handed
+ * the field's (REL-2142), `undefined` otherwise. What it writes inside itself binds below it:
+ * `richTextToHtml(value.body, { field: relyioField(field, 'body') })`.
+ */
+type RichTextHtmlDeclaredWriters<V> = {
+    readonly [Type in DeclaredTypeOf<V>]: (value: Extract<RichTextDeclaredOf<V>, {
+        readonly _type: Type;
+    }>, field: RelyIOFieldAttributes | undefined) => string;
+};
+type DeclaredHtmlOption<V> = [RichTextDeclaredOf<V>] extends [never] ? {
+    readonly declared?: Record<string, never>;
+} : {
+    readonly declared: RichTextHtmlDeclaredWriters<V>;
+};
+/**
+ * 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 declared Block or Inline element (REL-1807) is written by `options.declared`, which a field
+ *   declaring any requires; a value built by hand holding one no function names writes nothing.
+ *   Handed `options.field` — `relyioField(post, 'body')` — each is stamped with its key path, and its
+ *   writer handed the node's binding (REL-2142).
+ * - An entry link (REL-1808) is written by `options.entryLink`, handed the link — `to` an id, or the
+ *   entry where the read included the field — and the HTML of the text it covers; a field declaring
+ *   `links` requires it, since only your site knows its URLs.
+ * - A heading carries its anchor as its `id`: the slug of its text, the anchor an entry link names.
+ *   `options.anchors` — `entryHeadingAnchors(entry)` — numbers the field's headings after those of
+ *   the entry's fields before it (REL-2110); absent, the value's headings are numbered alone.
+ * - 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').get('hello')
+ * const html = richTextToHtml(post?.body) // '<h2>Getting started</h2><p>Install the <code>SDK</code>…</p>'
+ * ```
+ */
+declare function richTextToHtml<V extends RichTextRenderableOf | undefined>(value: V, ...[options]: RichTextHtmlOptions<V>): 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 declared Block or Inline element (REL-1807): what `options.declared` writes for it — required
+ *   for a field that declares any, since plain Markdown has no way to say a callout; a value built
+ *   by hand holding one no function names writes nothing.
+ * - An entry link (REL-1808): what `options.entryLink` writes for it, handed the link and its text's
+ *   Markdown — required for a field that declares `links`, since only your site knows its URLs. A
+ *   heading's anchor is the one GitHub gives it, which is the anchor an entry link names.
+ * - 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.
+ */
+
+/**
+ * What `richTextToMarkdown` takes beside the value: nothing for a field that declares no Block or
+ * Inline element; for one that does, `declared` — a function per declared `_type` returning its
+ * Markdown (REL-1807), held by the compiler to every one the field declares and to none other.
+ */
+type RichTextMarkdownOptions<V> = [RichTextDeclaredOf<V> | RichTextEntryLinkOf<V>] extends [
+    never
+] ? [options?: {
+    readonly declared?: Record<string, never>;
+    readonly entryLink?: never;
+}] : [options: DeclaredMarkdownOption<V> & RichTextEntryLinkOption<V, string>];
+type DeclaredMarkdownOption<V> = [RichTextDeclaredOf<V>] extends [never] ? {
+    readonly declared?: Record<string, never>;
+} : {
+    readonly declared: RichTextDeclaredWriters<V, string>;
+};
+/**
+ * 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<V extends RichTextRenderableOf | undefined>(value: V, ...[options]: RichTextMarkdownOptions<V>): string;
+
+export { type RichTextNodeContext as A, type RichTextRenderable as B, type RichTextRenderableOf as C, type RichTextReplaceableNode as D, type RichTextTag as E, type RichTextTarget as F, type RelyIOFieldAttributes as R, type RelyIOFieldName as a, type RelyIOFieldPath as b, type RelyIOKeyed as c, richTextHeadingAnchors as d, entryHeadingAnchors as e, richTextHeadingSlug as f, escapeHtml as g, richTextToHtml as h, richTextToMarkdown as i, type RichTextHtmlDeclaredWriters as j, type RichTextHtmlFieldOption as k, type RichTextHtmlOptions as l, type RichTextMarkdownOptions as m, RICH_TEXT_VOID_TAGS as n, isDeclaredRichTextNode as o, renderRichText as p, type RichTextAnchorsOption as q, relyioField as r, safeRichTextHref as s, type RichTextAttributes as t, type RichTextBlocksOf as u, type RichTextDeclaredOf as v, type RichTextDeclaredWriters as w, type RichTextEntryLinkOf as x, type RichTextEntryLinkOption as y, type RichTextInlineOf as z };