@avocadostudio-ai/richtext 0.2.0

package/dist/portable-text.js

@@ -0,0 +1,424 @@
+/**
+ * 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 { MARK, NODE } from "./doc.js";
+import { mergeByIdentity, omitDeep } from "./merge.js";
+/** Portable Text's standard decorators, and the pivot marks they are. */
+const DECORATOR_TO_MARK = {
+    strong: MARK.bold,
+    em: MARK.italic,
+    underline: MARK.underline,
+    "strike-through": MARK.strike,
+    code: MARK.code
+};
+const MARK_TO_DECORATOR = Object.fromEntries(Object.entries(DECORATOR_TO_MARK).map(([decorator, mark]) => [mark, decorator]));
+const HEADING_STYLE = /^h([1-6])$/;
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// ---------------------------------------------------------------------------
+// Portable Text -> document
+// ---------------------------------------------------------------------------
+function spansToInline(block) {
+    const markDefs = new Map((block.markDefs ?? []).map((def) => [def._key, def]));
+    const nodes = [];
+    for (const span of block.children ?? []) {
+        if (span._type !== "span") {
+            // An inline object (a mention, an inline image). No text to salvage, so
+            // keep the whole thing as data rather than silently deleting it.
+            nodes.push({ type: NODE.unknown, attrs: { data: span, _key: span._key ?? null } });
+            continue;
+        }
+        const text = typeof span.text === "string" ? span.text : "";
+        if (text.length === 0)
+            continue;
+        const marks = [];
+        for (const name of span.marks ?? []) {
+            const decorator = DECORATOR_TO_MARK[name];
+            if (decorator) {
+                marks.push({ type: decorator });
+                continue;
+            }
+            const def = markDefs.get(name);
+            if (!def) {
+                // A decorator this converter does not know about — a custom one the
+                // schema declares. Carry the name through so it survives the trip.
+                marks.push({ type: name });
+                continue;
+            }
+            const { _type, _key, ...attrs } = def;
+            marks.push({
+                type: _type === "link" ? MARK.link : _type,
+                attrs: { ...attrs, _key }
+            });
+        }
+        nodes.push({
+            type: NODE.text,
+            text,
+            ...(marks.length > 0 ? { marks } : {})
+        });
+    }
+    return nodes;
+}
+function withKey(node, key) {
+    if (key === undefined)
+        return node;
+    return { ...node, attrs: { ...(node.attrs ?? {}), _key: key } };
+}
+function unknownNode(block) {
+    return { type: NODE.unknown, attrs: { data: block, _key: block._key ?? null } };
+}
+function textBlockToNode(block) {
+    const content = spansToInline(block);
+    const style = typeof block.style === "string" ? block.style : "normal";
+    const heading = HEADING_STYLE.exec(style);
+    const node = heading
+        ? { type: NODE.heading, attrs: { level: Number(heading[1]) } }
+        : { type: NODE.paragraph };
+    const withBody = content.length > 0 ? { ...node, content } : node;
+    return withKey(withBody, block._key);
+}
+function listLevel(block) {
+    return typeof block.level === "number" && block.level > 0 ? block.level : 1;
+}
+function listTypeFor(block) {
+    return block.listItem === "number" ? NODE.orderedList : NODE.bulletList;
+}
+/**
+ * Rebuild one run of `listItem` blocks into nested list nodes.
+ *
+ * Returns the node plus the index of the first block it did not consume. A run
+ * ends when the level drops below where it started or the list style changes at
+ * the same level — which is exactly how a renderer has to read it too.
+ */
+function buildList(run, start, level) {
+    const type = listTypeFor(run[start]);
+    const items = [];
+    let i = start;
+    while (i < run.length) {
+        const blockLevel = listLevel(run[i]);
+        if (blockLevel < level)
+            break;
+        if (blockLevel > level) {
+            const [nested, next] = buildList(run, i, blockLevel);
+            const parent = items[items.length - 1];
+            if (parent) {
+                parent.content = [...(parent.content ?? []), nested];
+            }
+            else {
+                // A run that opens deeper than it should. Keep the content by treating
+                // the nested list as a sibling rather than dropping it.
+                items.push({ type: NODE.listItem, content: [nested] });
+            }
+            i = next;
+            continue;
+        }
+        if (listTypeFor(run[i]) !== type)
+            break;
+        const content = spansToInline(run[i]);
+        const paragraph = content.length > 0 ? { type: NODE.paragraph, content } : { type: NODE.paragraph };
+        items.push(withKey({ type: NODE.listItem, content: [paragraph] }, run[i]._key));
+        i++;
+    }
+    return [{ type, content: items }, i];
+}
+/** Convert an array of Portable Text blocks into the pivot document. */
+export function fromPortableText(blocks) {
+    if (!Array.isArray(blocks))
+        return { type: "doc", content: [] };
+    const source = blocks.filter(isObject);
+    const content = [];
+    let i = 0;
+    while (i < source.length) {
+        const block = source[i];
+        if (block._type !== "block") {
+            // Sanity's code-input plugin is common enough to be worth understanding;
+            // everything else rides through untouched.
+            if (block._type === "code" && typeof block.code === "string") {
+                content.push(withKey({
+                    type: NODE.codeBlock,
+                    attrs: { language: typeof block.language === "string" ? block.language : null },
+                    ...(block.code.length > 0 ? { content: [{ type: NODE.text, text: block.code }] } : {})
+                }, block._key));
+            }
+            else {
+                content.push(unknownNode(block));
+            }
+            i++;
+            continue;
+        }
+        if (typeof block.listItem === "string" && block.listItem.length > 0) {
+            const runEnd = (() => {
+                let j = i;
+                while (j < source.length && typeof source[j].listItem === "string" && source[j]._type === "block")
+                    j++;
+                return j;
+            })();
+            const run = source.slice(i, runEnd);
+            let cursor = 0;
+            while (cursor < run.length) {
+                const [node, next] = buildList(run, cursor, listLevel(run[cursor]));
+                content.push(node);
+                cursor = next === cursor ? cursor + 1 : next;
+            }
+            i = runEnd;
+            continue;
+        }
+        if (block.style === "blockquote") {
+            // A quote spanning several paragraphs is several blocks in a row. Fold
+            // them into one node so the editor shows one quote, not three.
+            const children = [];
+            let j = i;
+            while (j < source.length && source[j]._type === "block" && source[j].style === "blockquote" && !source[j].listItem) {
+                children.push(textBlockToNode({ ...source[j], style: "normal" }));
+                j++;
+            }
+            content.push({ type: NODE.blockquote, content: children });
+            i = j;
+            continue;
+        }
+        content.push(textBlockToNode(block));
+        i++;
+    }
+    return { type: "doc", content };
+}
+function createKeyMint(prefix) {
+    let counter = 0;
+    // Deterministic, not random: the same document must serialise to the same
+    // keys every time or every publish diff shows every block as changed.
+    return () => `${prefix}${counter++}`;
+}
+function nodeKey(node) {
+    const key = node.attrs?._key;
+    return typeof key === "string" && key.length > 0 ? key : undefined;
+}
+function inlineToSpans(nodes, blockKey) {
+    const children = [];
+    const markDefs = [];
+    const defByKey = new Map();
+    let annotationCount = 0;
+    for (const node of nodes ?? []) {
+        if (node.type === NODE.unknown && isObject(node.attrs?.data)) {
+            children.push(node.attrs.data);
+            continue;
+        }
+        if (node.type === NODE.hardBreak) {
+            // Portable Text has no break node; a newline inside the span is how every
+            // Sanity renderer expresses one.
+            const last = children[children.length - 1];
+            if (last && typeof last.text === "string")
+                last.text += "\n";
+            continue;
+        }
+        if (typeof node.text !== "string" || node.text.length === 0)
+            continue;
+        const marks = [];
+        for (const mark of node.marks ?? []) {
+            const decorator = MARK_TO_DECORATOR[mark.type];
+            if (decorator && !mark.attrs) {
+                marks.push(decorator);
+                continue;
+            }
+            if (!mark.attrs) {
+                marks.push(mark.type);
+                continue;
+            }
+            const { _key, ...rest } = mark.attrs;
+            const key = typeof _key === "string" && _key.length > 0 ? _key : `${blockKey}a${annotationCount++}`;
+            if (!defByKey.has(key)) {
+                const def = {
+                    _type: mark.type === MARK.link ? "link" : mark.type,
+                    _key: key,
+                    ...rest
+                };
+                defByKey.set(key, def);
+                markDefs.push(def);
+            }
+            marks.push(key);
+        }
+        children.push({
+            _type: "span",
+            _key: `${blockKey}s${children.length}`,
+            text: node.text,
+            ...(marks.length > 0 ? { marks } : {})
+        });
+    }
+    return { children, markDefs };
+}
+function textNodeToBlock(node, style, mint) {
+    const key = nodeKey(node) ?? mint("b");
+    const { children, markDefs } = inlineToSpans(node.content, key);
+    return {
+        _type: "block",
+        _key: key,
+        style,
+        ...(markDefs.length > 0 ? { markDefs } : { markDefs: [] }),
+        children
+    };
+}
+function styleForNode(node) {
+    if (node.type !== NODE.heading)
+        return "normal";
+    const level = typeof node.attrs?.level === "number" ? node.attrs.level : 2;
+    return `h${Math.min(6, Math.max(1, level))}`;
+}
+function flattenList(node, level, mint, out) {
+    const listItem = node.type === NODE.orderedList ? "number" : "bullet";
+    for (const item of node.content ?? []) {
+        const children = item.content ?? [];
+        const paragraph = children.find((c) => c.type === NODE.paragraph);
+        const key = nodeKey(item) ?? mint("b");
+        const spans = inlineToSpans(paragraph?.content, key);
+        out.push({
+            _type: "block",
+            _key: key,
+            style: "normal",
+            listItem,
+            level,
+            ...(spans.markDefs.length > 0 ? { markDefs: spans.markDefs } : { markDefs: [] }),
+            children: spans.children
+        });
+        for (const child of children) {
+            if (child.type === NODE.bulletList || child.type === NODE.orderedList) {
+                flattenList(child, level + 1, mint, out);
+            }
+        }
+    }
+}
+function nodeToBlocks(node, mint) {
+    switch (node.type) {
+        case NODE.paragraph:
+        case NODE.heading:
+            return [textNodeToBlock(node, styleForNode(node), mint)];
+        case NODE.bulletList:
+        case NODE.orderedList: {
+            const out = [];
+            flattenList(node, 1, mint, out);
+            return out;
+        }
+        case NODE.blockquote:
+            return (node.content ?? []).map((child) => textNodeToBlock(child, "blockquote", mint));
+        case NODE.codeBlock:
+            return [
+                {
+                    _type: "code",
+                    _key: nodeKey(node) ?? mint("b"),
+                    code: (node.content ?? []).map((c) => c.text ?? "").join(""),
+                    ...(typeof node.attrs?.language === "string" ? { language: node.attrs.language } : {})
+                }
+            ];
+        case NODE.horizontalRule:
+            // Portable Text has no rule primitive. Sanity schemas that want one
+            // declare their own object type, so emitting a fabricated `_type` here
+            // would write a block the dataset rejects.
+            return [];
+        case NODE.unknown:
+            return isObject(node.attrs?.data) ? [node.attrs.data] : [];
+        default:
+            return (node.content ?? []).flatMap((child) => nodeToBlocks(child, mint));
+    }
+}
+/**
+ * The fields of a `block` that this converter can rebuild from the pivot.
+ *
+ * Anything else on the block — a field the Sanity schema adds, an annotation
+ * store, whatever a plugin wrote — is content Avocado never saw and cannot
+ * reproduce. It is excluded from the content comparison (or every such block
+ * would look edited on every publish) and carried across verbatim instead.
+ */
+const REPRESENTABLE_BLOCK_FIELDS = ["_type", "_key", "style", "listItem", "level", "children", "markDefs"];
+function unrepresentedFields(block) {
+    const out = {};
+    for (const [key, value] of Object.entries(block)) {
+        if (REPRESENTABLE_BLOCK_FIELDS.includes(key))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * Reduce a block to the part a person authored.
+ *
+ * Keys are stripped, and annotation references renumbered in order of first
+ * use, so a block rebuilt with generated keys compares equal to the stored one
+ * it came from. Without the renumbering every block with a link in it would
+ * look changed on every publish.
+ *
+ * Empty is also absent here, on both sides. Sanity writes `marks: []` on a
+ * span with no marks and this converter omits the key entirely, so the two
+ * spell the same span two ways — and a comparison that reads them as different
+ * makes *every* stored block look edited. That is not a cosmetic difference:
+ * failing the content match drops the block to the positional pass, which
+ * keeps the block's own key but reissues every span key beneath it, so a
+ * publish rewrites prose nobody touched. It is the same mistake as a required
+ * prop holding `undefined`, one level down.
+ *
+ * An empty span goes the same way. It holds no text, so the pivot has no node
+ * to put it in — ProseMirror has no empty text node — and it can never be
+ * rebuilt. Dropping it from the stored side too lets the block match and be
+ * re-emitted *as the stored object*, which is what actually preserves it.
+ *
+ * Only `_type: "block"` gets the field projection. For every other type the
+ * object *is* the content — a code block's `code` and `language` are the whole
+ * value — so those compare whole, minus the key.
+ */
+function canonicalBlock(block) {
+    if (block._type !== "block")
+        return omitDeep(block, ["_key"]);
+    const order = new Map();
+    for (const def of block.markDefs ?? []) {
+        if (!order.has(def._key))
+            order.set(def._key, `a${order.size}`);
+    }
+    const rewritten = {
+        _type: block._type,
+        style: block.style,
+        listItem: block.listItem,
+        level: block.level,
+        markDefs: (block.markDefs ?? []).map((def) => ({ ...def, _key: order.get(def._key) ?? def._key })),
+        children: (block.children ?? [])
+            .filter((span) => span._type !== "span" || (typeof span.text === "string" && span.text.length > 0))
+            .map(({ marks, ...span }) => ({
+            ...span,
+            ...(marks && marks.length > 0 ? { marks: marks.map((m) => order.get(m) ?? m) } : {})
+        }))
+    };
+    if (rewritten.markDefs?.length === 0)
+        delete rewritten.markDefs;
+    return omitDeep(rewritten, ["_key"]);
+}
+/** Convert the pivot document back to an array of Portable Text blocks. */
+export function toPortableText(doc, options = {}) {
+    const mint = createKeyMint(options.keyPrefix ?? "avo");
+    const next = (doc.content ?? []).flatMap((node) => nodeToBlocks(node, mint));
+    const previous = Array.isArray(options.previous) ? options.previous.filter(isObject) : [];
+    if (previous.length === 0)
+        return next;
+    return mergeByIdentity(next, previous, {
+        canonical: canonicalBlock,
+        // An edited block keeps the identity *and* the fields the pivot could not
+        // carry — editing the prose must not strip a schema field off the block.
+        adopt: (rebuilt, stored) => ({
+            ...(stored._type === "block" ? unrepresentedFields(stored) : {}),
+            ...rebuilt,
+            ...(stored._key ? { _key: stored._key } : {})
+        }),
+        matches: (rebuilt, stored) => rebuilt._type === stored._type && rebuilt.listItem === stored.listItem
+    });
+}

package/dist/strapi.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Strapi 5 Blocks <-> the pivot document.
+ *
+ * Strapi's blocks field is Slate-shaped: a flat array of block objects, each
+ * with a `children` array, and formatting expressed as *boolean props on the
+ * text node* (`bold: true`) rather than as a list of marks. Links are inline
+ * nodes wrapping their text, the way Contentful does it, so the same
+ * gather-adjacent-text logic applies on the way out.
+ *
+ * Nesting is real here — a `list` may appear inside another list's children —
+ * which makes lists the one place Strapi is closer to the pivot than Portable
+ * Text is. Like Contentful and unlike Sanity, nothing carries a key, so a write
+ * replaces the field and there is nothing to merge against.
+ *
+ * The vocabulary has no thematic break. A `horizontalRule` in the pivot has
+ * nowhere to go and is dropped rather than faked as a paragraph of dashes.
+ */
+import { type RichTextDoc } from "./doc.ts";
+export type StrapiText = {
+    type: "text";
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    code?: boolean;
+    [key: string]: unknown;
+};
+export type StrapiNode = {
+    type: string;
+    children?: StrapiNode[];
+    level?: number;
+    format?: string;
+    url?: string;
+    text?: string;
+    [key: string]: unknown;
+};
+/** Convert a Strapi Blocks value into the pivot document. */
+export declare function fromStrapiBlocks(blocks: unknown): RichTextDoc;
+/** Convert the pivot document back to a Strapi Blocks value. */
+export declare function toStrapiBlocks(doc: RichTextDoc): StrapiNode[];