@bettercms-ai/richtext 0.1.0

package/src/schema.ts

@@ -0,0 +1,159 @@
+import { ALL_ELEMENTS, type AcceptElement } from "./accept";
+import { PT_TYPES, TABLE_CAPABILITY } from "./types";
+
+/**
+ * Accept elements → one Portable Text schema.
+ *
+ * THIS FILE EXISTS TO DELETE THREE COPIES OF ITSELF. The same mapping was written by hand in
+ * three places that had no way to notice each other drifting:
+ *
+ *   `capsFor`            (backend/src/lib/richtext/index.ts)   — what the SERVER would accept
+ *   `richtextFeatures`   (backend/src/lib/content/…normalize)  — what the WRITE PATH allowed
+ *   `featuresFor`        (dashboard/src/lib/richtext/accept)   — what the EDITOR offered
+ *
+ * When they disagreed, the editor offered a control whose output the sanitiser then stripped
+ * on save, so the value was destroyed one layer below the thing everyone kept fixing (FLO-723
+ * is that bug, twice). One schema object now drives the editor's toolbar, the server's
+ * write-time validation AND the HTML ingest filter, because `htmlToPortableText` takes a
+ * schema directly — they cannot drift, because there is only one of them.
+ *
+ * A note on `PT_LOAD_SCHEMA` below: this is the read/write split, and Portable Text makes it
+ * almost free where Lexical made it dangerous.
+ */
+
+export interface PtStyle { name: string; title?: string }
+export interface PtDecorator { name: string; title?: string }
+export interface PtList { name: string; title?: string }
+export interface PtField { name: string; type: string }
+export interface PtAnnotation { name: string; title?: string; fields?: PtField[] }
+export interface PtObject { name: string; title?: string; fields?: PtField[] }
+
+export interface PtSchema {
+  styles: PtStyle[];
+  decorators: PtDecorator[];
+  annotations: PtAnnotation[];
+  lists: PtList[];
+  blockObjects: PtObject[];
+  inlineObjects: PtObject[];
+}
+
+const HEADINGS = ["h1", "h2", "h3", "h4", "h5", "h6"] as const;
+
+/** Element → the decorator it grants. Bare names, because a decorator carries no data. */
+const DECORATOR_FOR: Partial<Record<AcceptElement, PtDecorator>> = {
+  b: { name: "strong", title: "Bold" },
+  i: { name: "em", title: "Italic" },
+  u: { name: "underline", title: "Underline" },
+  s: { name: "strike-through", title: "Strikethrough" },
+  code: { name: "code", title: "Inline code" },
+  mark: { name: "highlight", title: "Highlight" },
+};
+
+/**
+ * What the editor OFFERS for a given Accept set.
+ *
+ * `p` carries `blockquote` and the divider, exactly as `featuresFor` did — neither has a
+ * Prismic element of its own, and changing that here would silently narrow every existing
+ * field on its next save.
+ */
+export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
+  const has = (e: AcceptElement) => accept.includes(e);
+
+  // 'normal' is always present. Portable Text has no concept of a block without a style, and
+  // a field that accepts nothing structural still has to be able to hold a line of text.
+  const styles: PtStyle[] = [{ name: "normal", title: "Paragraph" }];
+  for (const h of HEADINGS) if (has(h)) styles.push({ name: h, title: h.toUpperCase() });
+  if (has("p")) styles.push({ name: "blockquote", title: "Quote" });
+
+  const decorators: PtDecorator[] = [];
+  for (const el of ALL_ELEMENTS) {
+    const d = DECORATOR_FOR[el];
+    if (d && has(el)) decorators.push(d);
+  }
+
+  const annotations: PtAnnotation[] = [];
+  if (has("link") || has("internalLink")) {
+    annotations.push({
+      name: PT_TYPES.link,
+      title: "Link",
+      // `target` is a FIELD, not a separate annotation: `allowTargetBlank:false` has to strip
+      // it on write, and a value you strip has to be somewhere you can find it.
+      fields: [
+        { name: "href", type: "string" },
+        { name: "target", type: "string" },
+      ],
+    });
+  }
+
+  const lists: PtList[] = [];
+  if (has("ul")) lists.push({ name: "bullet", title: "Bulleted list" });
+  if (has("ol")) lists.push({ name: "number", title: "Numbered list" });
+  if (has("checklist")) lists.push({ name: "check", title: "Checklist" });
+
+  const blockObjects: PtObject[] = [];
+  if (has("p")) blockObjects.push({ name: PT_TYPES.divider, title: "Divider" });
+  if (has("pre")) {
+    blockObjects.push({
+      name: PT_TYPES.code,
+      title: "Code block",
+      fields: [
+        { name: "code", type: "string" },
+        { name: "language", type: "string" },
+      ],
+    });
+  }
+  // Image, embed, table and columns all store as ONE generic block object under their existing
+  // `builtin:` schemaKeys rather than four bespoke types. That keeps a single converter lane
+  // and leaves `BuiltInBlockCard` (799 lines of working editor UI) untouched.
+  if (has("image") || has("embed") || has("table") || has("columns")) {
+    blockObjects.push({
+      name: PT_TYPES.block,
+      title: "Embedded block",
+      fields: [
+        { name: "schemaKey", type: "string" },
+        { name: "schemaLabel", type: "string" },
+        { name: "fields", type: "object" },
+      ],
+    });
+  }
+  /**
+   * A SECOND, table-specific entry — the one exception to "one generic block object".
+   *
+   * It exists because the generic entry cannot answer the question the HTML ingest has to ask.
+   * A custom deserializer rule runs BEFORE the compiled schema is consulted, so the rule has to
+   * decide for itself whether this field permits a table; asking "is the generic block object
+   * present?" answers yes for a field that accepts only IMAGES, and a `<table>` then lands in a
+   * field that forbids one. Nothing stores under this name — it is a capability marker read by
+   * `allowsTables`, and the value still stores as `builtin:table` on the generic block.
+   */
+  if (has("table")) blockObjects.push({ name: TABLE_CAPABILITY, title: "Table" });
+
+  return {
+    styles,
+    decorators,
+    annotations,
+    lists,
+    blockObjects,
+    // Mentions are not gated on `accept`: they are an authoring affordance rather than a
+    // content element, and a stored mention must survive in a field that never offered one.
+    inlineObjects: [
+      { name: PT_TYPES.mention, title: "Mention", fields: [{ name: "label", type: "string" }] },
+    ],
+  };
+}
+
+/**
+ * The READ schema: everything, always.
+ *
+ * Lexical needed this split and paid dearly for it. It registers NODE CLASSES from the feature
+ * list, so stored content using anything outside a field's configured features made
+ * `parseEditorState` THROW and the field opened EMPTY — silent data loss on the next autosave.
+ * That is why `RICHTEXT_LOAD_FEATURES` carries 15 entries against `RICHTEXT_FEATURES`' 10, and
+ * why `createLexicalEditor.ts` warns at length that table nodes must never be unregistered.
+ *
+ * Portable Text is plain JSON. An unknown `_type` is data, not a parse error — it round-trips
+ * untouched and renders through `unknownType`. So this schema is a superset used for READING
+ * and the whole failure class is gone; keeping the split is now only about what the toolbar
+ * OFFERS, which is a UI question with no way to destroy a value.
+ */
+export const PT_LOAD_SCHEMA: PtSchema = ptSchemaFor(ALL_ELEMENTS);

package/src/types.ts

@@ -0,0 +1,127 @@
+/**
+ * Portable Text, the real spec — https://portabletext.org
+ *
+ * BetterCMS shipped four hand-rolled "Portable Text" trees before this file, and all four
+ * diverged from the spec in the same expensive way: no `markDefs`. Without markDefs a link
+ * has nowhere to live, so every one of them could render bold text and none of them could
+ * render a hyperlink. Two also dropped unknown marks silently. This file is the spec, so the
+ * official `@portabletext/*` packages can read and write our content without a shim.
+ *
+ * THE SHAPE, and why each part earns its place:
+ *
+ *   block      ─ one paragraph/heading/quote. `style` says which. `listItem` + `level` make
+ *                it a list item, because Portable Text keeps lists FLAT and reconstructs the
+ *                nesting at render time; there is no `<ul>` node to lose.
+ *   span       ─ a run of text inside a block. `marks` are strings, and a mark is either a
+ *                DECORATOR (a bare name like "strong") or an ANNOTATION (the `_key` of an
+ *                entry in the block's `markDefs`). That one indirection is the whole reason
+ *                links, and any other data-carrying mark, are expressible.
+ *   markDefs   ─ the data behind annotation marks. A link's `href` lives here, not on the span.
+ *   blockObject─ anything that is not text: an image, an embed, a table, a placed component.
+ *
+ * `_key` is not decoration. It is the stable identity of a block, and it is what lets the
+ * Visual Editor address ONE paragraph inside a rich-text field instead of treating the whole
+ * field as a single opaque string. Everything the editor gained rests on it, so `_key` is
+ * minted on ingest and never trusted from foreign content.
+ */
+
+/** Every Portable Text node carries a type and a stable key. */
+export interface PortableTextNode {
+  _type: string;
+  _key: string;
+}
+
+/**
+ * A run of text. `marks` mixes decorator NAMES and markDef `_key`s; a consumer resolves the
+ * difference by looking each mark up in the parent block's `markDefs`. A mark that resolves to
+ * nothing is a decorator.
+ */
+export interface PortableTextSpan extends PortableTextNode {
+  _type: "span";
+  text: string;
+  marks: string[];
+}
+
+/** The data behind an annotation mark. `_key` is what a span's `marks` entry points at. */
+export interface PortableTextMarkDef extends PortableTextNode {
+  [field: string]: unknown;
+}
+
+/** A text block. Lists are FLAT: `listItem` + `level`, never a nested container. */
+export interface PortableTextBlock extends PortableTextNode {
+  _type: "block";
+  style: string;
+  markDefs: PortableTextMarkDef[];
+  children: (PortableTextSpan | PortableTextNode)[];
+  listItem?: string;
+  level?: number;
+  /** Only meaningful when `listItem` is "check". A checklist item's state is content, not style. */
+  checked?: boolean;
+}
+
+/** Anything that is not text — an image, an embed, a table, a placed component. */
+export interface PortableTextObject extends PortableTextNode {
+  [field: string]: unknown;
+}
+
+/** The value of a rich-text field: a flat array of blocks and block objects. */
+export type PortableText = (PortableTextBlock | PortableTextObject)[];
+
+export const isPortableTextBlock = (n: unknown): n is PortableTextBlock =>
+  !!n && typeof n === "object" && (n as PortableTextNode)._type === "block";
+
+export const isPortableTextSpan = (n: unknown): n is PortableTextSpan =>
+  !!n && typeof n === "object" && (n as PortableTextNode)._type === "span";
+
+/**
+ * The stored envelope.
+ *
+ * `value` is the source of truth; `html` is a DERIVED CACHE and is never trusted from a client
+ * when `value` is present. The envelope survives rather than storing a bare array because
+ * customer sites that shipped months ago read `.html` directly and cannot be recompiled —
+ * `packages/sdk/src/richtext.ts` `isRichText()` even returns false for an array, so a bare
+ * array would make every deployed `rich()` call return "" and blank the page at 200 OK.
+ */
+export const PORTABLE_TEXT_FORMAT = "portable-text-1" as const;
+
+export interface RichTextEnvelope {
+  format: typeof PORTABLE_TEXT_FORMAT;
+  value: PortableText;
+  html: string;
+}
+
+/**
+ * Our block-object and annotation type names, spelled once.
+ *
+ * Two repos serialise these and four renderers read them. A typo in any one of them is a node
+ * that renders as nothing, with no error — the failure mode this whole migration exists to
+ * stop — so the strings live here and nowhere else.
+ */
+export const PT_TYPES = {
+  /** A generic embedded block: `{schemaKey, schemaLabel, fields}`, the successor to Lexical's BlockNode. */
+  block: "bcmsBlock",
+  /** An inline mention. A PT inline object is natively void, which is what Lexical's `token` mode was faking. */
+  mention: "bcmsMention",
+  divider: "bcmsDivider",
+  code: "bcmsCode",
+  /** The annotation carrying a hyperlink's `href`. Spelled `link` because that is the spec's convention. */
+  link: "link",
+} as const;
+
+/**
+ * The `schemaKey` of the one table BetterCMS has.
+ *
+ * Both table lanes converge here — pasted HTML through `ingest.ts` and a native Lexical
+ * `TableNode` through `from-lexical.ts` — and `plain.ts` reads it back out, so it is spelled
+ * once for the same reason `PT_TYPES` is: three copies of a string that renders as nothing
+ * when it is wrong.
+ */
+export const BUILTIN_TABLE_KEY = "builtin:table" as const;
+
+/**
+ * A schema-only marker meaning "this field accepts tables". Never stored: a table's VALUE is a
+ * generic block object keyed `builtin:table`. It exists because the HTML ingest's table rule
+ * runs before the compiled schema is consulted and has to gate itself, and the generic block
+ * object cannot tell a table-accepting field from an image-accepting one.
+ */
+export const TABLE_CAPABILITY = "bcmsTableCapability" as const;