@bettercms-ai/richtext 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# @bettercms-ai/richtext
+
+The one Portable Text contract for BetterCMS: schema, converters, and rendering. Shared by the
+backend, the dashboard, and every delivery SDK.
+
+BetterCMS shipped four hand-rolled "Portable Text" trees before this package, and all four
+diverged from [the spec](https://portabletext.org) 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. This package is the spec, so the official
+`@portabletext/*` packages can read and write our content without a shim.
+
+## Install
+
+```bash
+npm install @bettercms-ai/richtext
+```
+
+## Reading a stored value
+
+`toPortableText` reads every shape BetterCMS has ever stored and **never throws** — a throw
+here would be a blank field, and a blank field is one autosave away from being permanent.
+Unrecognised input returns `[]` and is reported through `onUnreadable`.
+
+```ts
+import { toPortableText, portableTextToPlainText } from "@bettercms-ai/richtext";
+
+const value = toPortableText(entry.data.body);
+const preview = portableTextToPlainText(value);
+```
+
+It handles a bare `PortableText[]`, the `{format, value, html}` envelope, a Lexical state
+(object or JSON string), the `bettercms-notion-doc` document format, a pre-envelope
+`{html}` seed, bare HTML, and plain text — which stays **literal**, because running an
+author's copy through a Markdown parser is how a line beginning `#` silently became a heading.
+
+## Rendering
+
+```ts
+import { portableTextToHtml } from "@bettercms-ai/richtext/html";
+
+const html = portableTextToHtml(value);
+const inline = portableTextToHtml(value, { inline: true }); // unwraps a lone <p>
+```
+
+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 attributes this
+writes are an `href` through `safeHref` and a class token matched against a pattern.
+
+## Ingesting HTML
+
+```ts
+import { htmlToPortableText } from "@bettercms-ai/richtext/ingest";
+import { ptSchemaFor } from "@bettercms-ai/richtext";
+
+htmlToPortableText(html, {
+  parseHtml: (h) => new JSDOM(h).window.document, // required outside a browser
+  schema: ptSchemaFor(["p", "h2", "link", "table"]),
+});
+```
+
+**The filter IS the schema.** A tag with no place in the schema produces *no node* — `<script>`
+is not "sanitised away", it fails to parse into anything. One `ptSchemaFor(accept)` object
+drives the editor's toolbar, the server's write validation, and this filter at once, so they
+cannot drift.
+
+## Subpath exports
+
+| import | pulls in | use it for |
+| --- | --- | --- |
+| `@bettercms-ai/richtext` | nothing heavy | types, schema, reading, plain text |
+| `@bettercms-ai/richtext/html` | the HTML serialiser | rendering |
+| `@bettercms-ai/richtext/ingest` | a DOM parser | HTML → Portable Text |
+
+The split is deliberate: `ingest` needs a DOM and `html` needs the serialiser, and neither
+should reach a dashboard bundle just because someone imported a type.
+
+## Ships as source
+
+`main` points at `./src/index.ts`, like `@bettercms-ai/db` and `@bettercms-ai/content`. The
+BetterCMS API runs Bun and consumes this directly; a `dist`-pointing export once crash-looped
+the container. Consumers that need compiled output should bundle it as they would any
+TypeScript source dependency.
+
+## Licence
+
+Proprietary — part of BetterCMS.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@bettercms-ai/richtext",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "The one Portable Text contract for BetterCMS: schema, converters, and rendering. Shared by the backend, the dashboard and every delivery SDK.",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/__tests__",
+    "package.json",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./html": "./src/html.ts",
+    "./ingest": "./src/ingest.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@portabletext/to-html": "^6.0.0",
+    "@portabletext/html": "^2.0.0",
+    "@portabletext/schema": "^3.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "vitest": "^4.1.4"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/accept.ts

@@ -0,0 +1,201 @@
+import { RICH_TEXT_CAPABILITY_MANIFEST, type RichTextFeature } from './features'
+import type { AllowEntry } from './features'
+
+/**
+ * The Accept model — which HTML elements a rich-text field is allowed to contain.
+ *
+ * ELEMENT-LEVEL, not feature-level, so `h2` and `h3` can be permitted independently — the
+ * repo's `RichTextFeature` catalog is one `headings` switch covering H1–H6, which cannot
+ * express that. Element names are also the vocabulary the SANITISER speaks, and the sanitiser
+ * is what makes this configuration real: a list only the toolbar honours is decorative the
+ * moment content arrives by paste, from the AI hook, or from before the list was narrowed.
+ */
+
+/** The elements Prismic exposes — the default-visible set. */
+export const CORE_ELEMENTS = [
+  'p', 'pre', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+  'b', 'i', 'link', 'image', 'code', 'ul', 'ol', 'rtl',
+] as const
+
+/**
+ * What this repo can do beyond Prismic. Behind "Advanced" so the panel reads like the spec at
+ * rest, but present so enabling them is not a capability deletion.
+ */
+export const ADVANCED_ELEMENTS = [
+  'u', 'mark', 's', 'checklist', 'table', 'columns', 'embed', 'internalLink',
+] as const
+
+export const ALL_ELEMENTS = [...CORE_ELEMENTS, ...ADVANCED_ELEMENTS] as const
+export type AcceptElement = (typeof ALL_ELEMENTS)[number]
+
+/** Labels name the CAPABILITY, never the key — an author reads "Headings", not `accept.h1`. */
+export const ELEMENT_LABELS: Record<AcceptElement, string> = {
+  p: 'Paragraph', pre: 'Preformatted',
+  h1: 'H1', h2: 'H2', h3: 'H3', h4: 'H4', h5: 'H5', h6: 'H6',
+  b: 'Bold', i: 'Italic', link: 'Link', image: 'Image', code: 'Inline code',
+  ul: 'Bulleted list', ol: 'Numbered list', rtl: 'Right-to-left',
+  u: 'Underline', mark: 'Highlight', s: 'Strikethrough', checklist: 'Checklist',
+  table: 'Table', columns: 'Columns', embed: 'Video embed', internalLink: 'Internal link',
+}
+
+/**
+ * Grouped for the panel. Twenty-four flat switches is a wall, not a form — an author is
+ * choosing what KIND of writing this field is for, and the groups say that out loud.
+ */
+export const ELEMENT_GROUPS: { id: string; label: string; elements: AcceptElement[] }[] = [
+  { id: 'structure', label: 'Structure', elements: ['p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'ul', 'ol', 'pre'] },
+  { id: 'marks', label: 'Inline marks', elements: ['b', 'i', 'code', 'u', 'mark', 's'] },
+  // `internalLink` stays in ALL_ELEMENTS for stored-config compatibility, but is intentionally
+  // absent here: new authoring uses the ordinary URL Link until a real internal-entry contract exists.
+  { id: 'insert', label: 'Insert', elements: ['link', 'image', 'table', 'columns', 'embed', 'checklist'] },
+  // `rtl` stays in ALL_ELEMENTS for stored-config compatibility. There is no editor command
+  // for it yet, so new schema authoring must not advertise an inert toggle.
+]
+
+/**
+ * Element → the HTML tags the sanitiser must permit for it.
+ *
+ * `p` CARRIES `hr` AND `blockquote`, and it has to. `featuresFor` grants `horizontalRule` and
+ * `blockquote` to any field that accepts `p` — neither has a Prismic element of its own — so
+ * leaving their tags out here made the editor and the sanitiser disagree about the same field:
+ * typing `---` really did insert a divider, and `lexicalToBlockHtml` then stripped it on the way
+ * to storage, every time. The transformer was fixed twice while the value was being destroyed one
+ * layer later, which is why it kept reading as "the shortcut does not work" (FLO-723).
+ *
+ * The rule this file already states cuts both ways: a list only the toolbar honours is
+ * decorative, AND a feature only the editor grants is a value the author loses on save.
+ */
+const ELEMENT_TAGS: Record<AcceptElement, string[]> = {
+  p: ['p', 'br', 'hr', 'blockquote'], pre: ['pre'],
+  h1: ['h1'], h2: ['h2'], h3: ['h3'], h4: ['h4'], h5: ['h5'], h6: ['h6'],
+  b: ['strong', 'b'], i: ['em', 'i'], code: ['code'],
+  link: ['a'], internalLink: ['a'], image: ['img', 'figure', 'figcaption'],
+  ul: ['ul', 'li'], ol: ['ol', 'li'], rtl: ['bdo'],
+  u: ['u'], mark: ['mark'], s: ['s', 'strike', 'del'],
+  checklist: ['ul', 'li', 'input'], table: ['table', 'thead', 'tbody', 'tr', 'th', 'td'],
+  columns: ['section', 'div', 'p', 'br'],
+  embed: ['figure', 'iframe', 'video', 'source', 'figcaption'],
+}
+
+/**
+ * Visible but not yet authorable during the backend-first rollout. The panel renders these as
+ * focusable aria-disabled controls with persistent reasons instead of advertising dead toggles.
+ */
+export const UNAVAILABLE_ACCEPT_REASONS: Partial<Record<AcceptElement, string>> = {}
+
+/** Generic BlockNodes cannot round-trip through component props' legacy HTML storage. */
+export const HTML_BACKED_UNAVAILABLE_ACCEPT_REASONS: Partial<Record<AcceptElement, string>> = {
+  image: 'Embedded blocks are available in entry rich text; component rich text stores HTML.',
+  embed: 'Embedded blocks are available in entry rich text; component rich text stores HTML.',
+  table: 'Embedded blocks are available in entry rich text; component rich text stores HTML.',
+  columns: 'Embedded blocks are available in entry rich text; component rich text stores HTML.',
+}
+
+const NEW_AUTHORING_EXCLUSIONS = new Set<AcceptElement>(['internalLink', 'rtl'])
+
+/** New defaults contain every capability whose complete consumer pipeline is currently live. */
+export const DEFAULT_ACCEPT: AcceptElement[] = ALL_ELEMENTS.filter(
+  (element) => !NEW_AUTHORING_EXCLUSIONS.has(element),
+)
+
+export interface RichTextConfig {
+  accept: AcceptElement[]
+  /** Links may open in a new tab. Off ⇒ `target` is stripped, not just hidden in the UI. */
+  allowTargetBlank: boolean
+  /**
+   * Off ⇒ a single-paragraph field: the value is stored INLINE with no `<p>` wrapper, so it
+   * can sit inside a consumer's own heading or button without nesting a block in it.
+   */
+  allowMultipleParagraphs: boolean
+  placeholder?: string
+  /**
+   * Which components the `/` menu may insert. ABSENT means all of them; an EMPTY array means
+   * none — an explicit author choice, deliberately distinct from "not configured".
+   */
+  components?: AllowEntry[]
+}
+
+export const DEFAULT_RICHTEXT_CONFIG: RichTextConfig = {
+  accept: DEFAULT_ACCEPT,
+  allowTargetBlank: true,
+  allowMultipleParagraphs: true,
+}
+
+/** The tag allowlist the sanitiser enforces for a given Accept set. */
+export function allowedTags(accept: AcceptElement[]): string[] {
+  const tags = new Set<string>(['span']) // spans carry marks; never the reason content is stripped
+  for (const el of accept) for (const t of ELEMENT_TAGS[el] ?? []) tags.add(t)
+  return [...tags]
+}
+
+/** Read a stored config bag, filling defaults. Unknown elements are dropped, not trusted. */
+export function readConfig(raw: unknown): RichTextConfig {
+  const c = (raw ?? {}) as Partial<RichTextConfig>
+  const accept = Array.isArray(c.accept)
+    ? (c.accept.filter((e) => (ALL_ELEMENTS as readonly string[]).includes(e)) as AcceptElement[])
+    : DEFAULT_ACCEPT
+  return {
+    accept: accept.length ? accept : DEFAULT_ACCEPT,
+    allowTargetBlank: c.allowTargetBlank ?? true,
+    allowMultipleParagraphs: c.allowMultipleParagraphs ?? true,
+    placeholder: typeof c.placeholder === 'string' ? c.placeholder : undefined,
+    // Absent stays absent — `readConfig` must NOT default this to an empty array, or
+    // "not configured" would silently become "no components allowed".
+    components: Array.isArray(c.components) ? (c.components as AllowEntry[]) : undefined,
+  }
+}
+
+/**
+ * Accept elements → the Lexical FEATURES the editor must enable.
+ *
+ * Two vocabularies exist because they answer different questions: `accept` is what the
+ * SANITISER permits (HTML elements, per-heading-level), while `RichTextFeature` is what the
+ * EDITOR registers (plugins and nodes, headings as one switch). This is the only place they
+ * meet, so the translation lives here rather than being re-derived at each call site.
+ *
+ * Getting this wrong is not cosmetic: `createLexicalEditorConfig` registers NODES from the
+ * feature list and `markdownTransformers` gates every element transformer on it, so a missing
+ * feature means the markdown shortcut AND the slash-menu item both silently do nothing.
+ */
+export function featuresFor(accept: AcceptElement[]): RichTextFeature[] {
+  const has = (e: AcceptElement) => accept.includes(e)
+  const out: RichTextFeature[] = ['bold', 'italic', 'underline', 'strikethrough', 'code', 'highlight']
+  if (['h1', 'h2', 'h3', 'h4', 'h5', 'h6'].some((h) => has(h as AcceptElement))) out.push('headings')
+  if (has('pre')) out.push('codeBlock')
+  if (has('ul')) out.push('unorderedList')
+  if (has('ol')) out.push('orderedList')
+  if (has('checklist')) out.push('checklist')
+  if (has('link')) out.push('link')
+  if (has('internalLink')) out.push('internalLink')
+  if (has('image')) out.push('inlineImage')
+  if (has('table')) out.push('table')
+  if (has('columns')) out.push('columns')
+  if (has('embed')) out.push('videoEmbed')
+  // Blockquote and horizontal rule have no Prismic element of their own, so they ride with
+  // the structural set — a field that allows paragraphs allows a quote and a divider.
+  if (has('p')) out.push('blockquote', 'horizontalRule')
+  return out
+}
+
+/**
+ * The one resolution every richtext mount uses. Absent ≢ empty: an explicit `[]` really does mean
+ * no features, while `undefined` means EVERYTHING — because no stored field config carries a
+ * feature list, so reading undefined as "none" silently disables every shortcut in the field.
+ *
+ * It lives here, and call sites import it, because the same line re-typed at each mount is how
+ * `ArrayField` came to forward `features` raw: node registration then read undefined as NONE while
+ * the slash menu read it as ALL, and the mount offered "Heading 1" to an editor with no HeadingNode.
+ */
+export function resolveFeatures(config: unknown, explicit?: readonly RichTextFeature[]): RichTextFeature[] {
+  return explicit ? [...explicit] : featuresFor(readConfig(config).accept)
+}
+
+/** Component props store HTML, which cannot reconstruct opaque generic BlockNodes on reload. */
+export function featuresForHtmlStorage(features: readonly RichTextFeature[]): RichTextFeature[] {
+  return features.filter((feature) => {
+    const capability = RICH_TEXT_CAPABILITY_MANIFEST[
+      feature as keyof typeof RICH_TEXT_CAPABILITY_MANIFEST
+    ]
+    return !capability || capability.storage !== 'generic-block'
+  })
+}

package/src/features.ts

@@ -0,0 +1,104 @@
+// ─── Feature Catalog ───────────────────────────────────────────────────────────
+
+export const ALWAYS_ON_FEATURES = [
+  'bold',
+  'italic',
+  'underline',
+  'strikethrough',
+  'code',
+  'highlight',
+] as const
+
+export const TOGGLEABLE_FEATURES = [
+  'headings',
+  'blockquote',
+  'horizontalRule',
+  'orderedList',
+  'unorderedList',
+  'checklist',
+  'link',
+  'internalLink',
+  'inlineImage',
+  'videoEmbed',
+  'codeBlock',
+  'table',
+  'columns',
+] as const
+
+export type ToggleableRichTextFeature = (typeof TOGGLEABLE_FEATURES)[number]
+
+/**
+ * The authoring/storage contract for every configurable capability.
+ *
+ * This is deliberately exhaustive. A picker checkbox, an insertion surface, and a load-time
+ * node strategy are one product capability; keeping them in separate ad-hoc lists is how FLO-814
+ * shipped inert options. `featuresSchism.test.tsx` proves this manifest against the real slash
+ * catalog and editor registration.
+ */
+export const RICH_TEXT_CAPABILITY_MANIFEST = {
+  headings: { authoring: 'slash-and-toolbar', storage: 'native', loader: 'feature-gated' },
+  blockquote: { authoring: 'slash-and-toolbar', storage: 'native', loader: 'feature-gated' },
+  horizontalRule: { authoring: 'slash', storage: 'native', loader: 'feature-gated' },
+  orderedList: { authoring: 'slash-and-toolbar', storage: 'native', loader: 'unconditional' },
+  unorderedList: { authoring: 'slash-and-toolbar', storage: 'native', loader: 'unconditional' },
+  checklist: { authoring: 'slash', storage: 'native', loader: 'unconditional' },
+  link: { authoring: 'toolbar', storage: 'native', loader: 'feature-gated' },
+  internalLink: { authoring: 'compatibility-only', storage: 'native', loader: 'feature-gated' },
+  inlineImage: { authoring: 'slash', storage: 'generic-block', loader: 'unconditional' },
+  videoEmbed: { authoring: 'slash', storage: 'generic-block', loader: 'unconditional' },
+  codeBlock: { authoring: 'slash', storage: 'native', loader: 'feature-gated' },
+  table: { authoring: 'slash', storage: 'generic-block', loader: 'unconditional' },
+  columns: { authoring: 'slash', storage: 'generic-block', loader: 'unconditional' },
+} as const satisfies Record<
+  ToggleableRichTextFeature,
+  {
+    authoring: 'slash' | 'toolbar' | 'slash-and-toolbar' | 'compatibility-only'
+    storage: 'native' | 'generic-block'
+    loader: 'feature-gated' | 'unconditional'
+  }
+>
+
+/**
+ * What a NEW field may offer today. TOGGLEABLE_FEATURES remains the compatibility catalog:
+ * stored internalLink/videoEmbed/columns configs must still register their loaders while those
+ * capabilities are absent or gated from new authoring.
+ */
+export const AUTHORABLE_TOGGLEABLE_FEATURES = TOGGLEABLE_FEATURES.filter(
+  (feature) => RICH_TEXT_CAPABILITY_MANIFEST[feature].authoring !== 'compatibility-only',
+)
+
+export const ALL_FEATURES = [
+  ...ALWAYS_ON_FEATURES,
+  ...TOGGLEABLE_FEATURES,
+] as const
+
+export type RichTextFeature = (typeof ALL_FEATURES)[number]
+
+export const FEATURE_LABELS: Record<RichTextFeature, string> = {
+  bold: 'Bold',
+  italic: 'Italic',
+  underline: 'Underline',
+  strikethrough: 'Strikethrough',
+  code: 'Inline code',
+  highlight: 'Highlight',
+  headings: 'Headings (H1–H6)',
+  blockquote: 'Blockquote',
+  horizontalRule: 'Horizontal rule',
+  orderedList: 'Ordered list',
+  unorderedList: 'Unordered list',
+  checklist: 'Checklist',
+  link: 'External link',
+  internalLink: 'Internal link',
+  inlineImage: 'Inline image',
+  videoEmbed: 'Video embed',
+  codeBlock: 'Code block',
+  table: 'Table',
+  columns: 'Columns',
+}
+
+// ─── Component allowlist (moved with `accept`, which references it) ───────────
+
+/** The `/` menu's allowlist entry: a whole section-type family, or one component by id. */
+export type AllowEntry =
+  | { kind: 'family'; sectionType: string; variantIds?: string[] }
+  | { kind: 'component'; id: string }