@avocadostudio-ai/richtext 0.2.0

package/dist/parse.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The rich-text grammar, in one place.
+ *
+ * A `richtext` field is stored as a markdown string, and until now three
+ * separate implementations parsed it: the block renderers (to React elements),
+ * the editor overlay (to an HTML string) and the Puck adapter (to HTML, and
+ * back). They had already drifted — the Puck adapter honoured heading depth
+ * while the page hard-coded `<h3>` — so the same document rendered a different
+ * outline depending on which editor you had open.
+ *
+ * This module owns the grammar; the callers own presentation. Anything a
+ * particular surface does differently (HTML-escaping its input, skipping the
+ * paragraph wrapper for single-line values, choosing a heading tag) belongs in
+ * that surface's serializer, not here.
+ *
+ * The grammar is a subset of CommonMark, sized to exactly what the property
+ * panel's editor can produce — anything it can write must render, or the user
+ * sees their own formatting come back as punctuation:
+ *   inline   `**strong**`, `*em*`, `~~strike~~`, `` `code` ``, `[label](href)`,
+ *            hard breaks (`\` or two trailing spaces)
+ *   blocks   ATX headings, bullet and ordered lists (nested), blockquotes,
+ *            fenced code, thematic breaks, paragraphs
+ * Still outside it: tables, setext headings, reference links, footnotes, and
+ * inline images — the editor has no image node and deletes them, so an
+ * `![alt](src)` renders its alt text rather than promising an image the stack
+ * cannot keep. See the rich-text characterisation tests for each case.
+ */
+/** A span of text inside a block, already resolved to its mark. */
+export type InlineToken = {
+    type: "text";
+    text: string;
+    at: number;
+} | {
+    type: "strong";
+    text: string;
+    at: number;
+} | {
+    type: "em";
+    text: string;
+    at: number;
+} | {
+    type: "strike";
+    text: string;
+    at: number;
+} | {
+    type: "code";
+    text: string;
+    at: number;
+} | {
+    type: "link";
+    text: string;
+    href: string;
+    at: number;
+}
+/** An explicit line break inside a block — markdown's `\` or two trailing spaces. */
+ | {
+    type: "break";
+    at: number;
+};
+/** One item in a list, with an optional nested list under it. */
+export type RichTextListItem = {
+    inline: InlineToken[];
+    children?: RichTextList;
+};
+export type RichTextList = {
+    type: "unordered-list" | "ordered-list";
+    items: RichTextListItem[];
+};
+/**
+ * One top-level block.
+ *
+ * `index` is the block's position in the source document. Serializers use it to
+ * key their output; it is stable for a given input.
+ */
+export type RichTextBlock = {
+    type: "heading";
+    index: number;
+    /** Hash count, 1–6, as written. Serializers decide which tag that maps to. */
+    level: number;
+    inline: InlineToken[];
+    /** Text that followed the heading inside the same block, if any. */
+    trailing?: InlineToken[];
+} | {
+    type: "unordered-list";
+    index: number;
+    items: RichTextListItem[];
+} | {
+    type: "ordered-list";
+    index: number;
+    items: RichTextListItem[];
+} | {
+    type: "blockquote";
+    index: number;
+    children: RichTextBlock[];
+} | {
+    type: "code";
+    index: number;
+    code: string;
+    language?: string;
+} | {
+    type: "rule";
+    index: number;
+} | {
+    type: "paragraph";
+    index: number;
+    inline: InlineToken[];
+    raw: string;
+};
+/**
+ * Map an authored hash count onto the heading level a body actually renders.
+ *
+ * Every serializer must use this, or the same document gets a different outline
+ * depending on which surface you are looking at — which is exactly the drift
+ * that made the page emit `<h3>` while Puck emitted `<h2>`.
+ */
+export declare function resolveRichTextHeadingLevel(level: number): number;
+/**
+ * Rewrite heading markers so the source agrees with what will be rendered.
+ *
+ * Only `#` moves (to `##`); 2-6 are already renderable. Use it on a value
+ * entering an editor whose schema does not accept `h1`: without it the editor
+ * silently degrades the heading to a paragraph and saves that back, so a `#`
+ * that the page was rendering as `h2` disappears on the next edit.
+ */
+export declare function clampMarkdownHeadings(markdown: string): string;
+/** Undo the serialiser's escaping of a text span. */
+export declare function unescapeMarkdownText(text: string): string;
+/** Split a line of text into marked spans. Unterminated markers stay literal. */
+export declare function parseInline(text: string): InlineToken[];
+/**
+ * Whitespace clean-up applied to a body before it is parsed.
+ *
+ * This used to also apply `/([.!?])([A-Z])/g → "$1 $2"`, a band-aid for
+ * planners that emitted `requested.Here's`. It fired on correct prose far more
+ * often than on the malformed kind: every `U.S.A.` became `U. S. A.`, and any
+ * URL with a capital after a dot (`/API.Reference`) gained a space and stopped
+ * resolving. It ran on every render of every page, so the damage was permanent
+ * from the reader's point of view even though the stored string was fine.
+ *
+ * If a planner starts emitting run-on sentences again, fix it in the prompt —
+ * not by rewriting everyone's prose at render time.
+ */
+export declare function normalizeRichTextBody(input: string): string;
+/**
+ * Parse a body that has already been through `normalizeRichTextBody`.
+ *
+ * Callers that need to inspect or transform the normalized string first (the
+ * editor overlay checks it for newlines) use this; everyone else wants
+ * `parseRichText`.
+ */
+export declare function parseRichTextBlocks(normalizedBody: string): RichTextBlock[];
+/** Parse a rich-text string into its blocks. */
+export declare function parseRichText(input: string): RichTextBlock[];

package/dist/parse.js

@@ -0,0 +1,363 @@
+/**
+ * The rich-text grammar, in one place.
+ *
+ * A `richtext` field is stored as a markdown string, and until now three
+ * separate implementations parsed it: the block renderers (to React elements),
+ * the editor overlay (to an HTML string) and the Puck adapter (to HTML, and
+ * back). They had already drifted — the Puck adapter honoured heading depth
+ * while the page hard-coded `<h3>` — so the same document rendered a different
+ * outline depending on which editor you had open.
+ *
+ * This module owns the grammar; the callers own presentation. Anything a
+ * particular surface does differently (HTML-escaping its input, skipping the
+ * paragraph wrapper for single-line values, choosing a heading tag) belongs in
+ * that surface's serializer, not here.
+ *
+ * The grammar is a subset of CommonMark, sized to exactly what the property
+ * panel's editor can produce — anything it can write must render, or the user
+ * sees their own formatting come back as punctuation:
+ *   inline   `**strong**`, `*em*`, `~~strike~~`, `` `code` ``, `[label](href)`,
+ *            hard breaks (`\` or two trailing spaces)
+ *   blocks   ATX headings, bullet and ordered lists (nested), blockquotes,
+ *            fenced code, thematic breaks, paragraphs
+ * Still outside it: tables, setext headings, reference links, footnotes, and
+ * inline images — the editor has no image node and deletes them, so an
+ * `![alt](src)` renders its alt text rather than promising an image the stack
+ * cannot keep. See the rich-text characterisation tests for each case.
+ */
+/*
+ * `(?<!\\)` on every delimiter: an escaped `*` or `[` is literal text, not the
+ * start or end of a mark. Without it `\*not emphasis\*` would open a mark on a
+ * character the author explicitly escaped.
+ *
+ * Known limit: a genuine escaped backslash immediately before a delimiter
+ * (`\\*emphasis*`) reads as an escaped delimiter and the mark is missed. It
+ * needs a full character-by-character scanner to get right and has never come
+ * up in real content.
+ */
+const INLINE_PATTERN = new RegExp([
+    // Code spans bind tightest, so they come first: nothing inside them is markup.
+    "(?<!\\\\)`(?<code>[^`]+?)`",
+    // Before the link alternative, so the `!` is consumed rather than left behind.
+    "!\\[(?<imageAlt>.*?)(?<!\\\\)\\]\\((?<imageSrc>.+?)(?<!\\\\)\\)",
+    "(?<!\\\\)\\*\\*(?<strong>.+?)(?<!\\\\)\\*\\*",
+    "(?<!\\\\)~~(?<strike>.+?)(?<!\\\\)~~",
+    "(?<!\\\\)\\*(?<em>.+?)(?<!\\\\)\\*",
+    "(?<!\\\\)\\[(?<linkText>.+?)(?<!\\\\)\\]\\((?<linkHref>.+?)(?<!\\\\)\\)"
+].join("|"), "g");
+/** A trailing `\` (what the editor's Shift+Enter serialises to) or two trailing spaces. */
+const HARD_BREAK_PATTERN = /(\\\n|[ ]{2,}\n)/;
+const HEADING_PATTERN = /^(#{1,6})\s+(.+)$/;
+const UNORDERED_ITEM_PATTERN = /^(\s*)[-*+•]\s+(.+)$/;
+const ORDERED_ITEM_PATTERN = /^(\s*)\d+[.)]\s+(.+)$/;
+/** ``` or ~~~, optionally followed by an info string naming the language. */
+const FENCE_PATTERN = /^(```|~~~)(.*)$/;
+/** A thematic break: three or more of the same marker, alone on its line. */
+const RULE_PATTERN = /^(?:-{3,}|\*{3,}|_{3,})$/;
+const BLOCKQUOTE_PATTERN = /^>\s?(.*)$/;
+/*
+ * The characters `prosemirror-markdown`'s `esc()` escapes when it serialises a
+ * text node. Everything that comes out of the property panel has been through
+ * it, so a bracket the author typed arrives here as `\[` — and used to reach
+ * the page with the backslash showing.
+ */
+const ESCAPED_TEXT_CHARACTER = /\\([`*\\~[\]_])/g;
+/** Link hrefs use a different set — see the link mark's serialiser. */
+const ESCAPED_HREF_CHARACTER = /\\([()"])/g;
+/**
+ * The shallowest heading a rich-text body may render.
+ *
+ * A body heading is never the page's most important one — the Hero or the
+ * block's own title already holds `h1`. Letting `#` through would put a second
+ * `h1` on the page, which costs both the document outline and the screen-reader
+ * landmark list. So `#` and `##` both land on `h2`.
+ */
+const MIN_HEADING_LEVEL = 2;
+const MAX_HEADING_LEVEL = 6;
+/**
+ * Map an authored hash count onto the heading level a body actually renders.
+ *
+ * Every serializer must use this, or the same document gets a different outline
+ * depending on which surface you are looking at — which is exactly the drift
+ * that made the page emit `<h3>` while Puck emitted `<h2>`.
+ */
+export function resolveRichTextHeadingLevel(level) {
+    return Math.min(MAX_HEADING_LEVEL, Math.max(MIN_HEADING_LEVEL, level));
+}
+/**
+ * Rewrite heading markers so the source agrees with what will be rendered.
+ *
+ * Only `#` moves (to `##`); 2-6 are already renderable. Use it on a value
+ * entering an editor whose schema does not accept `h1`: without it the editor
+ * silently degrades the heading to a paragraph and saves that back, so a `#`
+ * that the page was rendering as `h2` disappears on the next edit.
+ */
+export function clampMarkdownHeadings(markdown) {
+    return markdown.replace(/^(#{1,6})(\s)/gm, (_match, hashes, space) => "#".repeat(resolveRichTextHeadingLevel(hashes.length)) + space);
+}
+/** Undo the serialiser's escaping of a text span. */
+export function unescapeMarkdownText(text) {
+    return text.replace(ESCAPED_TEXT_CHARACTER, "$1");
+}
+function unescapeHref(href) {
+    return href.replace(ESCAPED_HREF_CHARACTER, "$1");
+}
+/** Tokenize a run of text with no hard breaks in it. */
+function tokenizeSegment(text, base) {
+    const tokens = [];
+    // A fresh regex per call: the module-level one carries `lastIndex` state.
+    const regex = new RegExp(INLINE_PATTERN.source, "g");
+    let last = 0;
+    let match;
+    const pushText = (value, at) => {
+        if (value.length > 0)
+            tokens.push({ type: "text", text: unescapeMarkdownText(value), at });
+    };
+    while ((match = regex.exec(text)) !== null) {
+        const groups = match.groups ?? {};
+        pushText(text.slice(last, match.index), base + last);
+        const at = base + match.index;
+        if (groups.code !== undefined) {
+            // Code spans are literal: no unescaping, no nested markup.
+            tokens.push({ type: "code", text: groups.code, at });
+        }
+        else if (groups.imageSrc !== undefined) {
+            /*
+             * Inline images are not supported, and rendering one would be worse than
+             * not: the property panel's editor has no image node, so it deletes an
+             * `![alt](src)` outright the moment anyone edits the field. Keeping the
+             * alt text at least preserves the words instead of leaving the stray `!`
+             * the old link-only regex produced. Images belong in an `f.image` field.
+             */
+            pushText(groups.imageAlt ?? "", at);
+        }
+        else if (groups.strong !== undefined) {
+            tokens.push({ type: "strong", text: unescapeMarkdownText(groups.strong), at });
+        }
+        else if (groups.strike !== undefined) {
+            tokens.push({ type: "strike", text: unescapeMarkdownText(groups.strike), at });
+        }
+        else if (groups.em !== undefined) {
+            tokens.push({ type: "em", text: unescapeMarkdownText(groups.em), at });
+        }
+        else if (groups.linkText !== undefined && groups.linkHref !== undefined) {
+            tokens.push({
+                type: "link",
+                text: unescapeMarkdownText(groups.linkText),
+                href: unescapeHref(groups.linkHref),
+                at
+            });
+        }
+        last = match.index + match[0].length;
+    }
+    pushText(text.slice(last), base + last);
+    return tokens;
+}
+/** Split a line of text into marked spans. Unterminated markers stay literal. */
+export function parseInline(text) {
+    const tokens = [];
+    // The capture group keeps the separators, so they land on the odd indices.
+    const segments = text.split(HARD_BREAK_PATTERN);
+    let offset = 0;
+    for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        if (i % 2 === 1) {
+            tokens.push({ type: "break", at: offset });
+        }
+        else if (segment.length > 0) {
+            tokens.push(...tokenizeSegment(segment, offset));
+        }
+        offset += segment.length;
+    }
+    return tokens;
+}
+/**
+ * Whitespace clean-up applied to a body before it is parsed.
+ *
+ * This used to also apply `/([.!?])([A-Z])/g → "$1 $2"`, a band-aid for
+ * planners that emitted `requested.Here's`. It fired on correct prose far more
+ * often than on the malformed kind: every `U.S.A.` became `U. S. A.`, and any
+ * URL with a capital after a dot (`/API.Reference`) gained a space and stopped
+ * resolving. It ran on every render of every page, so the damage was permanent
+ * from the reader's point of view even though the stored string was fine.
+ *
+ * If a planner starts emitting run-on sentences again, fix it in the prompt —
+ * not by rewriting everyone's prose at render time.
+ */
+export function normalizeRichTextBody(input) {
+    return input
+        .replace(/\r\n?/g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+function readListLine(line) {
+    const unordered = UNORDERED_ITEM_PATTERN.exec(line);
+    if (unordered) {
+        const text = unordered[2].trim();
+        return text.length > 0 ? { indent: unordered[1].length, ordered: false, text } : null;
+    }
+    const ordered = ORDERED_ITEM_PATTERN.exec(line);
+    if (ordered) {
+        const text = ordered[2].trim();
+        return text.length > 0 ? { indent: ordered[1].length, ordered: true, text } : null;
+    }
+    return null;
+}
+/**
+ * Build a nested list from indented source lines.
+ *
+ * Indent width is compared, not counted in fixed units: the editor writes two
+ * spaces under a `-` and three under a `1.` so that the text of a nested item
+ * lines up under its parent's, and other producers use four. Anything deeper
+ * than the enclosing item opens a nested list; anything shallower closes one.
+ *
+ * A block is a list only when *every* one of its lines is a list item — a
+ * continuation line makes the whole block a paragraph, as it always has.
+ */
+function parseList(rawLines, index) {
+    const lines = rawLines.filter((line) => line.trim().length > 0);
+    const parsed = [];
+    for (const line of lines) {
+        const item = readListLine(line);
+        if (!item)
+            return null;
+        parsed.push(item);
+    }
+    if (parsed.length === 0)
+        return null;
+    const root = {
+        type: parsed[0].ordered ? "ordered-list" : "unordered-list",
+        items: []
+    };
+    // Each frame is a list that is currently open, with the indent it started at.
+    const stack = [
+        { indent: parsed[0].indent, list: root }
+    ];
+    for (const line of parsed) {
+        while (stack.length > 1 && line.indent < stack[stack.length - 1].indent)
+            stack.pop();
+        let top = stack[stack.length - 1];
+        if (line.indent > top.indent) {
+            const parent = top.list.items[top.list.items.length - 1];
+            // An indented first item has no parent to hang from; treat it as a sibling.
+            if (parent) {
+                const nested = {
+                    type: line.ordered ? "ordered-list" : "unordered-list",
+                    items: []
+                };
+                parent.children = nested;
+                stack.push({ indent: line.indent, list: nested });
+                top = stack[stack.length - 1];
+            }
+        }
+        top.list.items.push({ inline: parseInline(line.text) });
+    }
+    return { type: root.type, index, items: root.items };
+}
+function parseBlock(raw, index) {
+    const rawLines = raw.split("\n");
+    const lines = rawLines.map((line) => line.trim()).filter(Boolean);
+    if (lines.length === 0)
+        return null;
+    // Fenced code. The splitter keeps a fenced run together, blank lines and all.
+    const fence = FENCE_PATTERN.exec(lines[0]);
+    if (fence) {
+        const language = fence[2].trim();
+        const openIndex = rawLines.findIndex((line) => FENCE_PATTERN.test(line.trim()));
+        const body = rawLines.slice(openIndex + 1);
+        const closeIndex = body.findIndex((line) => line.trim().startsWith(fence[1]));
+        const code = (closeIndex === -1 ? body : body.slice(0, closeIndex)).join("\n");
+        return { type: "code", index, code, ...(language ? { language } : {}) };
+    }
+    if (lines.length === 1 && RULE_PATTERN.test(lines[0])) {
+        return { type: "rule", index };
+    }
+    const heading = HEADING_PATTERN.exec(lines[0]);
+    if (heading) {
+        const trailing = lines.slice(1).join(" ").trim();
+        return {
+            type: "heading",
+            index,
+            level: heading[1].length,
+            inline: parseInline(heading[2].trim()),
+            ...(trailing ? { trailing: parseInline(trailing) } : {})
+        };
+    }
+    // A blockquote carries its marker on every line, blank ones included — which
+    // is how a multi-paragraph quote survives the blank-line split above. Strip
+    // the markers and parse what is left as blocks, so a quote can hold lists and
+    // headings the way it does in every other markdown implementation.
+    if (lines.every((line) => BLOCKQUOTE_PATTERN.test(line))) {
+        const inner = rawLines
+            .map((line) => BLOCKQUOTE_PATTERN.exec(line.trim())?.[1] ?? "")
+            .join("\n");
+        const children = parseRichTextBlocks(inner);
+        if (children.length > 0)
+            return { type: "blockquote", index, children };
+    }
+    const list = parseList(rawLines, index);
+    if (list)
+        return list;
+    // Note: the paragraph's inline spans come from the *raw* block, newlines
+    // included, not from the trimmed `lines` above.
+    return { type: "paragraph", index, inline: parseInline(raw), raw };
+}
+/**
+ * Split a normalized body into block-level chunks on blank lines.
+ *
+ * Fence-aware: a blank line inside a fenced code block is part of the code, not
+ * a block separator. Splitting on the blank line first would cut the fence in
+ * half and render both halves as paragraphs of literal backticks.
+ */
+function splitBlocks(body) {
+    const chunks = [];
+    let current = [];
+    let openFence = null;
+    const flush = () => {
+        const text = current.join("\n").trim();
+        if (text.length > 0)
+            chunks.push(text);
+        current = [];
+    };
+    for (const line of body.split("\n")) {
+        const trimmed = line.trim();
+        if (openFence !== null) {
+            current.push(line);
+            if (trimmed.startsWith(openFence)) {
+                openFence = null;
+                flush();
+            }
+            continue;
+        }
+        const fence = FENCE_PATTERN.exec(trimmed);
+        if (fence) {
+            flush();
+            openFence = fence[1];
+            current.push(line);
+            continue;
+        }
+        if (trimmed.length === 0) {
+            flush();
+            continue;
+        }
+        current.push(line);
+    }
+    flush();
+    return chunks;
+}
+/**
+ * Parse a body that has already been through `normalizeRichTextBody`.
+ *
+ * Callers that need to inspect or transform the normalized string first (the
+ * editor overlay checks it for newlines) use this; everyone else wants
+ * `parseRichText`.
+ */
+export function parseRichTextBlocks(normalizedBody) {
+    return splitBlocks(normalizedBody)
+        .map(parseBlock)
+        .filter((block) => block !== null);
+}
+/** Parse a rich-text string into its blocks. */
+export function parseRichText(input) {
+    return parseRichTextBlocks(normalizeRichTextBody(input));
+}

package/dist/portable-text.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Sanity Portable Text <-> the pivot document.
+ *
+ * Portable Text is a *flat* array. A nested list is not a tree: it is a run of
+ * sibling blocks that each declare `listItem` and a `level`, and the nesting
+ * only exists once a renderer groups them. A multi-paragraph quote is likewise
+ * several blocks that happen to share `style: "blockquote"`. Both are rebuilt
+ * into real trees on the way in and flattened again on the way out.
+ *
+ * Two things about the format make a lossless round trip possible, and both are
+ * relied on here:
+ *
+ * - Every block, span and annotation carries a `_key`. Those keys are how the
+ *   Sanity dataset addresses content, so they are carried through the pivot
+ *   (`attrs._key`) and written back rather than regenerated.
+ * - An unrecognised `_type` is just data. A block this converter does not know
+ *   is not an error and must not be dropped; it rides through as
+ *   `avocadoUnknownBlock` and comes back out byte-identical.
+ */
+import { type RichTextDoc } from "./doc.ts";
+export type PortableTextSpan = {
+    _type: string;
+    _key?: string;
+    text?: string;
+    marks?: string[];
+    [key: string]: unknown;
+};
+export type PortableTextMarkDef = {
+    _type: string;
+    _key: string;
+    [key: string]: unknown;
+};
+export type PortableTextBlock = {
+    _type: string;
+    _key?: string;
+    style?: string;
+    listItem?: string;
+    level?: number;
+    children?: PortableTextSpan[];
+    markDefs?: PortableTextMarkDef[];
+    [key: string]: unknown;
+};
+/** Convert an array of Portable Text blocks into the pivot document. */
+export declare function fromPortableText(blocks: unknown): RichTextDoc;
+export type ToPortableTextOptions = {
+    /**
+     * The blocks currently stored for this field.
+     *
+     * Supplying them is what turns a write into an update: an unchanged block is
+     * re-emitted as the stored object itself, keys and unrecognised fields
+     * included, so the CMS sees a diff of what actually changed.
+     */
+    previous?: unknown;
+    /** Prefix for generated `_key`s. Only used where no stored key exists. */
+    keyPrefix?: string;
+};
+/** Convert the pivot document back to an array of Portable Text blocks. */
+export declare function toPortableText(doc: RichTextDoc, options?: ToPortableTextOptions): PortableTextBlock[];