@bettercms-ai/richtext 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.3.0",
+  "version": "0.4.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.",
@@ -15,6 +15,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./html": "./src/html.ts",
+    "./heading": "./src/heading.ts",
     "./ingest": "./src/ingest.ts"
   },
   "scripts": {

package/src/from-lexical.ts

@@ -49,6 +49,7 @@ interface LexNode {
   checked?: boolean;
   url?: string;
   target?: string | null;
+  rel?: string | null;
   mentionId?: string;
   children?: unknown[];
   blockAttrs?: Record<string, unknown>;
@@ -102,6 +103,8 @@ function spansFrom(
     if (href) {
       const def: PortableTextMarkDef = { _type: PT_TYPES.link, _key: ctx.key(), href };
       if (typeof node.target === "string" && node.target) def.target = node.target;
+      // `rel` rides next to `target` — the importer keeps `prev`/`next` on pagination links.
+      if (typeof node.rel === "string" && node.rel) (def as PortableTextMarkDef & { rel?: string }).rel = node.rel;
       markDefs.push(def);
       marks = [...inherited, def._key];
     }

package/src/heading.ts

@@ -0,0 +1,132 @@
+/**
+ * A `richtext` block rendered AS a heading — `props.level` (1–6).
+ *
+ * Closes the gap between the two blocks that each held half of a title: `heading` has a level
+ * but a PLAIN `text` (the renderer escapes it, so `Equip Your Projects with <span
+ * class="text-yellow-500">ScrewFast</span>` loses its brand span), and `richtext` keeps the
+ * markup but had no level. With `level` set, the renderer emits `<hN>` around the rich copy
+ * instead of `<div class="bcms-text">`, so the marks survive AND the element is a real heading —
+ * the one site CSS sizes (`.bcms-page h1{font-size:…}` keys on the tag, not a class).
+ *
+ * WHY A LEVEL ON `richtext` RATHER THAN MARKS ON `heading.text`: `props.html` is already the one
+ * MARKUP slot every writer, override and coercion rule knows about (`MARKUP_PATH` in
+ * prop-value.ts, block-pass.ts and @bettercms-ai/ui/resolve). Making `heading.props.text` a
+ * Portable Text value would add a second markup slot, and every reader that does
+ * `String(p.text)` would print `[object Object]`. A number beside `html` touches nothing that
+ * reads `html`.
+ *
+ * ── The one rule both the validator and the renderer apply ──────────────────────────────────
+ * A heading holds PHRASING content only. `<h1><p>…</p><p>…</p></h1>` is not a heading, it is
+ * two paragraphs in a heading-shaped box, and it is what a naïve wrapper would emit for every
+ * editor that stores a lone line as `<p>…</p>`. So the value must reduce to ONE line of inline
+ * copy: a lone Portable Text text block, or html with at most a bare `<p>`/`<hN>` wrapper around
+ * inline markup. The write schema refuses anything else with a message naming the fix; the
+ * renderer, which also sees values no block schema checked (component overrides), falls back to
+ * the ordinary `<div class="bcms-text">` rather than emit invalid markup or drop copy.
+ */
+import { isPortableTextBlock, type PortableTextBlock } from "./types";
+import { readStructuredContent } from "./read";
+import { portableTextToHtml } from "./html";
+
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+/**
+ * The level a `richtext` block renders at, or null for "not a heading" — which is every block
+ * stored before this existed. No clamping: `heading` clamps because its level is always a
+ * heading, but here an absent/invalid level must mean the ordinary paragraph render, so a
+ * stray `0`, `null` or `""` cannot quietly turn body copy into an `<h1>`.
+ */
+export function richtextHeadingLevel(value: unknown): HeadingLevel | null {
+  if (value === null || value === undefined || value === "" || typeof value === "boolean") return null;
+  const n = Number(value);
+  return Number.isInteger(n) && n >= 1 && n <= 6 ? (n as HeadingLevel) : null;
+}
+
+/** Flow-content tags a heading may not contain. Phrasing tags (`span`, `a`, `strong`, `br`) pass. */
+const BLOCK_TAG =
+  /<\/?(?:address|article|aside|blockquote|details|dialog|div|dl|dd|dt|fieldset|figcaption|figure|footer|form|h[1-6]|header|hr|li|main|nav|ol|p|pre|section|summary|table|tbody|td|tfoot|th|thead|tr|ul)\b/i;
+
+/**
+ * An ATTRIBUTE-LESS lone `<p>` or `<hN>`. With attributes it is not unwrapped: dropping a
+ * `<p class="lead">` would silently change the design, so that value is refused instead.
+ */
+const LONE_WRAPPER = /^<(p|h[1-6])>([\s\S]*)<\/\1>$/i;
+
+/** `html` as the inner content of a heading, or null when it is not one line of inline copy. */
+export function inlineHeadingHtml(html: string): string | null {
+  const m = LONE_WRAPPER.exec(html.trim());
+  const inner = m ? m[2]! : html;
+  return BLOCK_TAG.test(inner) ? null : inner;
+}
+
+/**
+ * The ONE Portable Text block a heading can be made of, or null. A list item, a quote, a table
+ * or a second block is not a heading; `normal` and an existing `h1`–`h6` style are (the level
+ * on the block, not the style in the value, decides the tag).
+ */
+export function loneHeadingBlock(content: unknown[]): PortableTextBlock | null {
+  if (content.length !== 1) return null;
+  const node = content[0];
+  if (!isPortableTextBlock(node) || node.listItem !== undefined) return null;
+  const style = node.style ?? "normal";
+  return style === "normal" || /^h[1-6]$/.test(style) ? node : null;
+}
+
+/** True when these richtext props can render as a heading. What the write schema enforces. */
+export function canRenderAsHeading(props: Record<string, unknown>): boolean {
+  const structured = readStructuredContent(props);
+  if (structured) return loneHeadingBlock(structured) !== null;
+  return inlineHeadingHtml(typeof props.html === "string" ? props.html : "") !== null;
+}
+
+/**
+ * The level the VALUE spells for itself — a lone `<h3>` wrapper, or a lone `h3`-styled Portable
+ * Text block — or null when it names none (a `<p>`, bare inline copy, `normal`).
+ *
+ * `props.level` decides the tag, so a value that names a DIFFERENT one is a contradiction the
+ * write schema refuses rather than silently overriding: `{ html: "<h3>T</h3>", level: 1 }` would
+ * store as an h3 and render as an h1, and the editor's block-style control reads the VALUE.
+ * Same class of defect as `headingLevelMismatch` in publish-static.ts, one layer up.
+ */
+export function valueHeadingLevel(props: Record<string, unknown>): HeadingLevel | null {
+  const structured = readStructuredContent(props);
+  const tag = structured
+    ? loneHeadingBlock(structured)?.style
+    : LONE_WRAPPER.exec(String(props.html ?? "").trim())?.[1];
+  return tag && /^h[1-6]$/i.test(tag) ? (Number(tag[1]) as HeadingLevel) : null;
+}
+
+/**
+ * The inner markup + binding ADDRESS of a levelled richtext value, or null when the value is
+ * not one line of inline copy (the caller then renders it as ordinary rich text).
+ *
+ * Shared by all three renderers — render-page.ts, @bettercms-ai/next and @bettercms-ai/astro —
+ * because a heading assembled once per lane is exactly the divergence `parity.test.ts` exists to
+ * catch: three green suites and one lane shipping a `<div>` where the others ship an `<hN>`.
+ * The lanes differ only in how they SPELL attributes (a string, a React prop, an Astro spread),
+ * so the address comes back raw and each lane formats it the way it already does.
+ *
+ * The binding is the one each lane already emits, moved from the wrapper onto the heading so no
+ * `<div>` lands inside an `<hN>`: the html lane binds the whole field (`<blockId>__html`); the
+ * Portable Text lane binds the lone block by its `_key` (`<base>#<_key>`), exactly as
+ * `portableTextToHtml({ bindingBase })` addresses it — so the editor's writer is unchanged.
+ */
+export function headingParts(
+  /** Any block's props — `{ html?, content? }`, as loose as the three lanes' own types are. */
+  props: { html?: unknown },
+  base: string | null,
+): { inner: string; address: string | null } | null {
+  const structured = readStructuredContent(props);
+  if (structured) {
+    const node = loneHeadingBlock(structured);
+    if (!node) return null;
+    // Style normalised to `normal` so the serialiser emits a lone <p> that `inline` unwraps; the
+    // block's LEVEL, not any h1–h6 style inside the value, decides the tag.
+    return {
+      inner: portableTextToHtml([{ ...node, style: "normal" }], { inline: true }),
+      address: base && node._key ? `${base}#${node._key}` : null,
+    };
+  }
+  const inner = inlineHeadingHtml(String(props.html ?? ""));
+  return inner === null ? null : { inner, address: base };
+}

package/src/href.ts

@@ -11,6 +11,12 @@ 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();
+  // An in-page FRAGMENT (`#where-it-comes-from`) can only move within the page, so it is as safe
+  // as a site-relative path. Refusing it cost every imported Contents list its links: the
+  // importer's Lexical anchors were dropped on conversion, on ingest and on render alike
+  // (astro-sumi, 2026-09-14). No whitespace or markup characters, so it cannot break out of the
+  // attribute it is written into.
+  if (trimmed.startsWith("#")) return /^#[^\s<>"'`]*$/.test(trimmed) ? trimmed : null;
   // A site-relative path has no scheme to check and cannot navigate off-origin.
   if (trimmed.startsWith("/") && !trimmed.startsWith("//")) return trimmed;
   try {

package/src/html.ts

@@ -150,11 +150,21 @@ const components: Partial<PortableTextHtmlComponents> = {
      * 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 v = (value ?? {}) as { href?: unknown; target?: unknown; rel?: 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>`;
+      // `rel` is author data too (the importer keeps `prev`/`next` on pagination links), so only
+      // plain link-type tokens pass; a new tab always adds noopener + noreferrer.
+      const rel = new Set(
+        typeof v.rel === "string" ? v.rel.toLowerCase().split(/\s+/).filter((t) => /^[a-z][a-z-]*$/.test(t)) : [],
+      );
+      const target = v.target === "_blank" ? ' target="_blank"' : "";
+      if (target) {
+        rel.add("noopener");
+        rel.add("noreferrer");
+      }
+      const relAttr = rel.size ? ` rel="${esc([...rel].join(" "))}"` : "";
+      return `<a href="${esc(href)}"${target}${relAttr}>${children}</a>`;
     },
     /**
      * The site's own inline markup, written back out as itself.