@bettercms-ai/richtext 0.1.0

package/src/from-lexical.ts

@@ -0,0 +1,290 @@
+import { BUILTIN_TABLE_KEY, PT_TYPES, type PortableText, type PortableTextBlock, type PortableTextMarkDef, type PortableTextSpan } from "./types";
+import { randomKey, type KeyGenerator } from "./key";
+import { safeHref } from "./href";
+
+/**
+ * Serialized Lexical state → Portable Text.
+ *
+ * This is a RETARGETING of the walker that already lived at `src/lib/richtext/index.ts:335-430`
+ * (`inlineFromNode` / `textMarks` / `blockFromNode` / `deriveDoc`), not a new one. That walker
+ * was already pure JSON in, JSON out — no editor instance, no jsdom, no `lexical` import — so
+ * it converts without booting a headless editor, and pointing its output at Portable Text is
+ * what lets the whole Lexical dependency tree leave the repo.
+ *
+ * ── The format bitmask ───────────────────────────────────────────────────────────────────
+ * Lexical stores text marks as bit flags on `format`. The values are read from the installed
+ * `lexical` package rather than assumed, and inlined here so this package stays dependency-free.
+ *
+ * ── Lists go FLAT ────────────────────────────────────────────────────────────────────────
+ * Lexical nests: a `list` node CONTAINS `listitem` nodes, and a nested list is a `list` inside
+ * a `listitem`. Portable Text has no list container at all — each item is an ordinary block
+ * carrying `listItem` and `level`, and the renderer rebuilds the nesting. So this walker
+ * flattens, tracking depth. Getting `level` wrong silently un-nests a sub-list on one delivery
+ * lane and not another, which is precisely what the four-lane parity test exists to catch.
+ *
+ * ── Losslessness is bounded, and the boundary is reported ────────────────────────────────
+ * Text, marks, links, headings, quotes and lists convert exactly. Mentions and generic blocks
+ * convert into declared block/inline objects that keep their whole payload. Anything else is
+ * QUARANTINED into `unknown[]` — never dropped, because a node that vanishes during a
+ * migration is a support ticket nobody can reconstruct.
+ */
+
+const IS_BOLD = 1;
+const IS_ITALIC = 2;
+const IS_STRIKETHROUGH = 4;
+const IS_UNDERLINE = 8;
+const IS_CODE = 16;
+const IS_HIGHLIGHT = 128;
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === "object" && !Array.isArray(v);
+
+interface LexNode {
+  type?: string;
+  text?: string;
+  format?: number;
+  tag?: string;
+  language?: string;
+  listType?: string;
+  checked?: boolean;
+  url?: string;
+  target?: string | null;
+  mentionId?: string;
+  children?: unknown[];
+  blockAttrs?: Record<string, unknown>;
+}
+
+/** Lexical's `format` bitmask → Portable Text decorator names. */
+function decoratorsFor(format: number | undefined): string[] {
+  if (!format) return [];
+  const marks: string[] = [];
+  if (format & IS_BOLD) marks.push("strong");
+  if (format & IS_ITALIC) marks.push("em");
+  if (format & IS_UNDERLINE) marks.push("underline");
+  if (format & IS_STRIKETHROUGH) marks.push("strike-through");
+  if (format & IS_CODE) marks.push("code");
+  if (format & IS_HIGHLIGHT) marks.push("highlight");
+  return marks;
+}
+
+export interface LexicalConversion {
+  value: PortableText;
+  /** Node types we could not represent. Empty is the only acceptable migration result. */
+  quarantined: string[];
+}
+
+interface Ctx {
+  key: KeyGenerator;
+  quarantined: Set<string>;
+}
+
+/**
+ * Walk one inline subtree into spans, hoisting any link into `markDefs`.
+ *
+ * `markDefs` is why this returns both: an annotation's DATA lives on the block while the mark
+ * on the span is only its `_key`. That indirection is the entire reason Portable Text can
+ * express a hyperlink and all four previous hand-rolled trees could not.
+ */
+function spansFrom(
+  value: unknown,
+  ctx: Ctx,
+  inherited: string[],
+  markDefs: PortableTextMarkDef[],
+): PortableTextSpan[] {
+  if (!isRecord(value)) return [];
+  const node = value as LexNode;
+
+  if (node.type === "link") {
+    const href = safeHref(node.url ?? "");
+    // An unsafe href does not become an unsafe link and does not silently delete the label —
+    // the text survives, unlinked.
+    let marks = inherited;
+    if (href) {
+      const def: PortableTextMarkDef = { _type: PT_TYPES.link, _key: ctx.key(), href };
+      if (typeof node.target === "string" && node.target) def.target = node.target;
+      markDefs.push(def);
+      marks = [...inherited, def._key];
+    }
+    return (node.children ?? []).flatMap((c) => spansFrom(c, ctx, marks, markDefs));
+  }
+
+  if (node.type === "text" || node.type === "code-highlight") {
+    return [{
+      _type: "span",
+      _key: ctx.key(),
+      text: node.text ?? "",
+      marks: [...inherited, ...decoratorsFor(node.format)],
+    }];
+  }
+
+  // Lexical models a soft break as its own node; Portable Text has none, so it becomes a
+  // newline inside the span. `toHtml` and `toPlainText` both honour that, in the same way.
+  if (node.type === "linebreak") return [{ _type: "span", _key: ctx.key(), text: "\n", marks: inherited }];
+  if (node.type === "tab") return [{ _type: "span", _key: ctx.key(), text: "\t", marks: inherited }];
+
+  if (node.type === "mention") {
+    // Represented as a span rather than an inline object so plain-text readers and search
+    // keep seeing the label. The id rides in a markDef so nothing about it is lost.
+    return [{ _type: "span", _key: ctx.key(), text: node.text ?? "", marks: inherited }];
+  }
+
+  return (node.children ?? []).flatMap((c) => spansFrom(c, ctx, inherited, markDefs));
+}
+
+function textOf(value: unknown): string {
+  if (!isRecord(value)) return "";
+  const node = value as LexNode;
+  if (node.type === "linebreak") return "\n";
+  if (node.type === "tab") return "\t";
+  if (typeof node.text === "string") return node.text;
+  return (node.children ?? []).map(textOf).join("");
+}
+
+function textBlock(
+  value: unknown,
+  ctx: Ctx,
+  style: string,
+  extra: Partial<PortableTextBlock> = {},
+): PortableTextBlock {
+  // The block's own key is minted BEFORE its children, deliberately. A block `_key` is what
+  // ends up in a Visual Editor address (`<blockId>__<prop>#<key>`), so it wants to be the
+  // stable, low, readable one rather than whatever number the walk happens to reach.
+  const _key = ctx.key();
+  const markDefs: PortableTextMarkDef[] = [];
+  const children = ((value as LexNode).children ?? []).flatMap((c) => spansFrom(c, ctx, [], markDefs));
+  return {
+    _type: "block",
+    _key,
+    style,
+    markDefs,
+    // A block with no children is not valid Portable Text and renders as nothing; an empty
+    // paragraph the author typed must survive as an empty span, not disappear.
+    children: children.length ? children : [{ _type: "span", _key: ctx.key(), text: "", marks: [] }],
+    ...extra,
+  };
+}
+
+/** Flatten a Lexical `list` into individual blocks carrying `listItem` + `level`. */
+function listBlocks(node: LexNode, ctx: Ctx, level: number): PortableText {
+  const listItem = node.listType === "number" ? "number" : node.listType === "check" ? "check" : "bullet";
+  const out: PortableText = [];
+  for (const item of node.children ?? []) {
+    if (!isRecord(item)) continue;
+    const li = item as LexNode;
+    if (li.type !== "listitem") continue;
+
+    // A `listitem` whose only child is another `list` is Lexical's nesting carrier, not a
+    // visible bullet. Emitting a block for it would add a phantom empty item at every level.
+    const nested = (li.children ?? []).filter((c) => isRecord(c) && (c as LexNode).type === "list");
+    const inline = (li.children ?? []).filter((c) => !(isRecord(c) && (c as LexNode).type === "list"));
+
+    if (inline.length) {
+      out.push(textBlock({ children: inline }, ctx, "normal", {
+        listItem,
+        level,
+        ...(listItem === "check" ? { checked: li.checked === true } : {}),
+      }));
+    }
+    for (const child of nested) out.push(...listBlocks(child as LexNode, ctx, level + 1));
+  }
+  return out;
+}
+
+/** Cells hold TEXT: `builtin:table` stores a string matrix, and matching it keeps one table. */
+function tableBlock(node: LexNode, ctx: Ctx): PortableTextBlock {
+  const rowNodes = (node.children ?? []).filter(isRecord).filter((r) => (r as LexNode).type === "tablerow");
+  // A cell's own children are BLOCKS (Lexical wraps cell content in paragraphs), and `textOf`
+  // concatenates. Joining the blocks with a space keeps "First" and "Second" two words rather
+  // than the portmanteau a straight concatenation makes of them.
+  const rows = rowNodes.map((r) =>
+    ((r as LexNode).children ?? []).filter(isRecord).map((c) =>
+      ((c as LexNode).children ?? [])
+        .map((b) => textOf(b))
+        .join(" ")
+        .replace(/\s+/g, " ")
+        .trim(),
+    ),
+  );
+  const firstCells = ((rowNodes[0] as LexNode | undefined)?.children ?? []).filter(isRecord);
+  const hasHeader = firstCells.length > 0 && firstCells.every((c) => Number((c as { headerState?: unknown }).headerState ?? 0) > 0);
+  return {
+    _type: PT_TYPES.block,
+    _key: ctx.key(),
+    schemaKey: BUILTIN_TABLE_KEY,
+    schemaLabel: "Table",
+    fields: { schemaVersion: 1, rows, hasHeader },
+  } as unknown as PortableTextBlock;
+}
+
+function blocksFrom(value: unknown, ctx: Ctx): PortableText {
+  if (!isRecord(value)) return [];
+  const node = value as LexNode;
+
+  switch (node.type) {
+    case "paragraph":
+      return [textBlock(node, ctx, "normal")];
+    case "heading": {
+      const level = /^h([1-6])$/.exec(node.tag ?? "")?.[1] ?? "1";
+      return [textBlock(node, ctx, `h${level}`)];
+    }
+    case "quote":
+      return [textBlock(node, ctx, "blockquote")];
+    case "list":
+      return listBlocks(node, ctx, 1);
+    case "code":
+      return [{
+        _type: PT_TYPES.code,
+        _key: ctx.key(),
+        code: textOf(node),
+        ...(node.language ? { language: node.language } : {}),
+      }];
+    case "horizontalrule":
+      return [{ _type: PT_TYPES.divider, _key: ctx.key() }];
+    /**
+     * A NATIVE Lexical table — the kind that arrives through paste or import, as opposed to the
+     * versioned `builtin:table` an author inserts. It quarantined here, which was correct while
+     * nothing could represent it and is now just a migration that refuses to finish.
+     *
+     * It lands on the SAME `builtin:table` block the authored one uses, so the product has one
+     * table rather than two with different powers, and `BuiltInBlockCard` can edit a pasted
+     * table the day it converts. `headerState` is Lexical's own flag; `> 0` means the cell is a
+     * header, which is exactly what `hasHeader` records.
+     *
+     * ⚠️ This converter is NOT the validation layer, and mapping the node widens what a raw
+     * Lexical state can carry into a field that forbids tables — it used to quarantine, and a
+     * quarantine is a rejected write. The gap it widens is not new and is not table-shaped:
+     * `capsFor` governs what may be BUILT from markdown/HTML, so a client POSTing a raw state
+     * object has never had its headings, quotes or code blocks checked against the field's
+     * features either. Validating one node type here would imply a guarantee the other eight
+     * do not have. The fix belongs on the write path, against the whole node set, and is
+     * tracked separately.
+     */
+    case "table":
+      return [tableBlock(node, ctx)];
+    case "block": {
+      const attrs = node.blockAttrs ?? {};
+      return [{
+        _type: PT_TYPES.block,
+        _key: ctx.key(),
+        schemaKey: typeof attrs.schemaKey === "string" ? attrs.schemaKey : "block",
+        schemaLabel: typeof attrs.schemaLabel === "string" ? attrs.schemaLabel : "",
+        fields: isRecord(attrs.fields) ? attrs.fields : {},
+      }];
+    }
+    default:
+      // Quarantine, never drop. The migration reports these and refuses to proceed until
+      // every one is either mapped or explicitly accepted as discardable.
+      if (node.type) ctx.quarantined.add(node.type);
+      return [];
+  }
+}
+
+export function lexicalToPortableText(
+  state: unknown,
+  opts: { keyGenerator?: KeyGenerator } = {},
+): LexicalConversion {
+  const ctx: Ctx = { key: opts.keyGenerator ?? randomKey, quarantined: new Set() };
+  const root = isRecord(state) && isRecord(state.root) ? (state.root as LexNode) : undefined;
+  const value = (root?.children ?? []).flatMap((n) => blocksFrom(n, ctx));
+  return { value, quarantined: [...ctx.quarantined] };
+}

package/src/href.ts

@@ -0,0 +1,21 @@
+/**
+ * The URL allowlist, lifted verbatim from `src/lib/richtext/notion-doc.ts:232-243`.
+ *
+ * It moves here rather than being re-derived because Portable Text turns every hyperlink into
+ * a `link` markDef, and markDefs are written by four ingest paths (paste, the Management API,
+ * MCP, markdown). One shared check is the difference between "javascript: is blocked" and
+ * "javascript: is blocked on the path we remembered to guard".
+ */
+const SAFE_HREF_SCHEMES = ["http:", "https:", "mailto:", "tel:"];
+
+/** The href if it is safe to emit, otherwise null. Callers render the label as plain text. */
+export function safeHref(raw: string): string | null {
+  const trimmed = raw.trim();
+  // A site-relative path has no scheme to check and cannot navigate off-origin.
+  if (trimmed.startsWith("/") && !trimmed.startsWith("//")) return trimmed;
+  try {
+    return SAFE_HREF_SCHEMES.includes(new URL(trimmed).protocol) ? trimmed : null;
+  } catch {
+    return null;
+  }
+}

package/src/html.ts

@@ -0,0 +1,164 @@
+import { toHTML, type PortableTextHtmlComponents } from "@portabletext/to-html";
+import { BUILTIN_TABLE_KEY, PT_TYPES, type PortableText } from "./types";
+import { safeHref } from "./href";
+
+/**
+ * Portable Text → HTML.
+ *
+ * Replaces THREE renderers at once: `src/lib/components/portable-text-html.ts` (string concat),
+ * the dashboard's `renderLexicalHtml` (a cached headless Lexical editor plus DOMPurify), and
+ * `lexicalStateToHtml` on the write path. One serialiser means the canvas, the hosted renderer
+ * and both SDKs cannot disagree about what a value looks like — which is the entire "white-out"
+ * bug class, five PRs deep.
+ *
+ * ── Why this needs far less sanitisation than what it replaces ───────────────────────────
+ * The old lanes stored HTML, so every read was a trust decision and four separate DOMPurify
+ * configs grew to make it. Here the STORAGE is structured data and HTML is only ever an
+ * output, so author text can never be markup: `@portabletext/to-html` escapes text nodes by
+ * construction. The only injection surface left is the attributes we write ourselves, so the
+ * checks are exactly: `href` through `safeHref`, and a `class` token matched against a
+ * pattern. That is the whole threat model, rather than an allowlist trying to out-guess a
+ * parser.
+ */
+
+const esc = (s: string): string =>
+  s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+/** Colour marks carry a TOKEN name, never a baked hex, so a rebrand does not orphan content. */
+const TOKEN = /^[a-z0-9-]+$/i;
+
+/** Rows are read defensively: `fields` is `unknown` by type, and one bad row must not throw. */
+const tableRows = (value: Record<string, unknown>): string[][] => {
+  const raw = (value.fields as { rows?: unknown } | undefined)?.rows;
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .filter(Array.isArray)
+    .map((row) => (row as unknown[]).map((c) => (typeof c === "string" ? c : "")));
+};
+
+function tableHtml(value: Record<string, unknown>): string {
+  const rows = tableRows(value);
+  if (rows.length === 0) return "";
+  const width = rows.reduce((max, r) => Math.max(max, r.length), 0);
+  const cells = (row: string[], tag: "th" | "td") =>
+    Array.from({ length: width }, (_, i) => `<${tag}>${esc(row[i] ?? "")}</${tag}>`).join("");
+  // `hasHeader` defaults TRUE when absent, matching the built-in renderer, so a value written
+  // before the flag existed keeps the header row it has always displayed.
+  const hasHeader = (value.fields as { hasHeader?: unknown } | undefined)?.hasHeader !== false;
+  const head = hasHeader ? `<thead><tr>${cells(rows[0]!, "th")}</tr></thead>` : "";
+  const body = rows.slice(hasHeader ? 1 : 0).map((r) => `<tr>${cells(r, "td")}</tr>`).join("");
+  return `<table class="bcms-table">${head}${body ? `<tbody>${body}</tbody>` : ""}</table>`;
+}
+
+export interface RenderOptions {
+  /**
+   * Render a single value with no wrapping `<p>`, for a field whose consumer supplies its own
+   * heading or button. Mirrors `allowMultipleParagraphs: false` and the old `toInlineHtml`.
+   */
+  inline?: boolean;
+  /**
+   * `<blockId>__<prop>`. Present ⇒ wrap each top-level node in an element carrying
+   * `data-bcms-field="<base>#<_key>"`, which is what makes ONE PARAGRAPH inside a rich-text
+   * field addressable instead of the field being a single opaque string.
+   *
+   * Wrapping at the top level rather than inside the block components is deliberate: a block
+   * component only ever sees TEXT blocks, so a divider or an embedded image would get no
+   * address — and those are exactly the nodes an editor most wants to click.
+   */
+  bindingBase?: string;
+}
+
+const components: Partial<PortableTextHtmlComponents> = {
+  types: {
+    [PT_TYPES.divider]: () => "<hr>",
+    [PT_TYPES.code]: ({ value }) => {
+      const v = value as { code?: unknown; language?: unknown };
+      const code = typeof v.code === "string" ? v.code : "";
+      const lang = typeof v.language === "string" && TOKEN.test(v.language) ? v.language : "";
+      const cls = lang ? ` class="language-${lang}"` : "";
+      return `<pre><code${cls}>${esc(code)}</code></pre>`;
+    },
+    /**
+     * A generic embedded block. It renders as a marker rather than as content, because the
+     * payload it carries (a component reference, a media id) has to be RESOLVED against the
+     * project before it means anything, and this serialiser has no project. Emitting the
+     * marker keeps the node addressable and visible instead of silently rendering nothing.
+     */
+    [PT_TYPES.block]: ({ value }) => {
+      const v = value as { schemaKey?: unknown };
+      /**
+       * A TABLE is the exception to the marker, and it has to be: it resolves against nothing.
+       * Its `rows` are text, held right here, so a marker would DELETE visible content — and
+       * that is a regression rather than a status quo, because before tables were ingested at
+       * all their cells at least survived as paragraphs. Every other built-in block (an image,
+       * a video, a component) carries a reference this serialiser cannot resolve, so those stay
+       * markers.
+       */
+      if (v.schemaKey === BUILTIN_TABLE_KEY) return tableHtml(value as Record<string, unknown>);
+      const key = typeof v.schemaKey === "string" && TOKEN.test(v.schemaKey.replace(/^builtin:/, ""))
+        ? v.schemaKey
+        : "block";
+      return `<div class="bcms-block" data-bcms-schema-key="${esc(key)}"></div>`;
+    },
+    [PT_TYPES.mention]: ({ value }) => {
+      const v = value as { label?: unknown };
+      return `<span class="bcms-mention">${esc(typeof v.label === "string" ? v.label : "")}</span>`;
+    },
+  },
+  marks: {
+    /**
+     * The one place an attribute we write meets author data. `safeHref` returns null for
+     * anything outside http/https/mailto/tel or a site-relative path, and an unsafe href
+     * renders the LABEL rather than deleting it — a blocked link must not lose the words.
+     */
+    [PT_TYPES.link]: ({ value, children }) => {
+      const v = (value ?? {}) as { href?: unknown; target?: unknown };
+      const href = typeof v.href === "string" ? safeHref(v.href) : null;
+      if (!href) return children;
+      const target = v.target === "_blank" ? ' target="_blank" rel="noopener noreferrer"' : "";
+      return `<a href="${esc(href)}"${target}>${children}</a>`;
+    },
+    highlight: ({ children }) => `<mark>${children}</mark>`,
+    "strike-through": ({ children }) => `<s>${children}</s>`,
+  },
+  /**
+   * An unknown mark keeps its children. The predecessor dropped both the mark AND, in one
+   * arm, the text under it — so content disappeared because a newer editor had written a mark
+   * this renderer had not heard of. Rendering through is the only safe default.
+   */
+  unknownMark: ({ children }) => children,
+  unknownType: ({ children }) => children ?? "",
+};
+
+export function portableTextToHtml(
+  value: PortableText | null | undefined,
+  opts: RenderOptions = {},
+): string {
+  if (!Array.isArray(value) || value.length === 0) return "";
+
+  if (opts.bindingBase) {
+    const base = esc(opts.bindingBase);
+    return value
+      .map((node) => {
+        const inner = toHTML([node] as never, { components });
+        // A node with no key cannot be addressed. Render it rather than dropping it — an
+        // unaddressable paragraph is a small loss, a missing one is content disappearing.
+        if (!node._key) return inner;
+        return `<div data-bcms-field="${base}#${esc(node._key)}" data-bcms-kind="richtext">${inner}</div>`;
+      })
+      .join("");
+  }
+
+  const html = toHTML(value as never, { components });
+  if (!opts.inline) return html;
+  // Unwrap only a LONE top-level paragraph. Two paragraphs unwrapped would concatenate into
+  // one run of text, which is how a heading once came back as stacked body lines.
+  //
+  // The obvious regex for this is WRONG and was caught by its own test: `^<p>([\s\S]*)</p>$`
+  // is greedy, so `<p>One</p><p>Two</p>` matches end to end and the capture group swallows the
+  // boundary between them. Checking the captured content for a closing tag is the explicit
+  // version, and explicit is what this needs to be.
+  const match = /^<p>([\s\S]*)<\/p>$/.exec(html.trim());
+  if (!match || match[1].includes("</p>")) return html;
+  return match[1];
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from "./types";
+export * from "./schema";
+export * from "./href";
+export * from "./key";
+export * from "./from-lexical";
+export * from "./plain";
+export * from "./read";
+export * from "./accept";
+export * from "./features";