@bettercms-ai/richtext 0.6.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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.",

package/src/html.ts

@@ -332,7 +332,7 @@ const buildComponents = (
      * 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; rel?: unknown };
+      const v = (value ?? {}) as { href?: unknown; target?: unknown; rel?: unknown; className?: unknown };
       const href = typeof v.href === "string" ? safeHref(v.href) : null;
       if (!href) return children;
       // `rel` is author data too (the importer keeps `prev`/`next` on pagination links), so only
@@ -346,7 +346,9 @@ const buildComponents = (
         rel.add("noreferrer");
       }
       const relAttr = rel.size ? ` rel="${esc([...rel].join(" "))}"` : "";
-      return `<a${cls(classes, "a")} href="${esc(href)}"${target}${relAttr}>${children}</a>`;
+      // The link's own class (kept on ingest) wins over the caller's default: it IS the site.
+      const own = typeof v.className === "string" && v.className ? ` class="${esc(v.className)}"` : "";
+      return `<a${own || cls(classes, "a")} href="${esc(href)}"${target}${relAttr}>${children}</a>`;
     },
     /**
      * The site's own inline markup, written back out as itself.

package/src/ingest.ts

@@ -9,7 +9,7 @@ import {
 } from "./types";
 import { randomKey, isValidKey, type KeyGenerator } from "./key";
 import { safeHref } from "./href";
-import { isStyledTag, styledAttrsOf, type StyledMarkDef } from "./styled";
+import { BARE_IS_DESIGN, isStyledTag, styledAttrsOf, type StyledMarkDef } from "./styled";
 import type { PtSchema } from "./schema";
 
 /**
@@ -197,11 +197,12 @@ function tableRule(key: KeyGenerator, ingestCell: (html: string) => PortableText
  * for exactly that reason.
  *
  * A `<span>` with nothing on it is NOT annotated: it carries no design, so recording it would
- * mint a markDef per stray wrapper and bloat every value for nothing. The other tags are
- * annotated bare, because there the TAG is the design (`<small>`, `<sup>`, `<kbd>`).
+ * mint a markDef per stray wrapper and bloat every value for nothing. `<small>`, `<sup>`,
+ * `<kbd>` … are annotated bare, because there the TAG is the design.
  *
- * Decorator tags (`b/strong`, `i/em`, `u`, `s`, `mark`, `code`) are deliberately absent: they
- * have real decorators and the standard rules run right after this one.
+ * Decorator tags (`b/strong`, `i/em`, `u`, `s`, `mark`, `code`, …) take this rule ONLY when
+ * they carry a class or an admitted attribute — the one thing their decorator cannot hold.
+ * Bare, they fall through to the standard rules and become the decorator as before.
  *
  * `__annotation` is the deserialiser's own internal placeholder — the same one its built-in
  * link rule returns — so nesting composes for free: `<strong><span class>` comes back as one
@@ -215,7 +216,7 @@ function styledRule(key: KeyGenerator): DeserializerRule {
       if (!isStyledTag(tag)) return undefined;
       const className = el.getAttribute("class")?.trim() || undefined;
       const attrs = styledAttrsOf(el);
-      if (tag === "span" && !className && !attrs) return undefined;
+      if (!className && !attrs && !BARE_IS_DESIGN.has(tag)) return undefined;
       const markDef: StyledMarkDef = {
         _type: PT_TYPES.styled,
         _key: key(),
@@ -228,6 +229,38 @@ function styledRule(key: KeyGenerator): DeserializerRule {
   };
 }
 
+/**
+ * `<a class>` → a `link` annotation that keeps the site's class as `className`.
+ *
+ * The built-in link rule records `href` and nothing else, so a styled link (`<a class="underline
+ * text-brand">`) came back bare and the design died on ingest. Only a link WITH a class takes
+ * this rule; a plain link still goes to the built-in one. `href` is checked by `normalise`.
+ */
+function classedLinkRule(key: KeyGenerator): DeserializerRule {
+  return {
+    deserialize(el: Node, next) {
+      if (!isElement(el) || el.nodeName.toLowerCase() !== "a") return undefined;
+      const className = el.getAttribute("class")?.trim();
+      const href = el.getAttribute("href")?.trim();
+      if (!className || !href) return undefined;
+      const rel = el.getAttribute("rel")?.trim();
+      const markDef = {
+        _type: PT_TYPES.link,
+        _key: key(),
+        href,
+        className,
+        ...(el.getAttribute("target") === "_blank" ? { target: "_blank" } : {}),
+        ...(rel ? { rel } : {}),
+      };
+      return { _type: "__annotation", markDef, children: next(el.childNodes) } as never;
+    },
+  };
+}
+
+/** Does this field's schema carry the link annotation? */
+const allowsLinks = (schema: PtSchema | undefined): boolean =>
+  !schema || schema.annotations.some((a) => a.name === PT_TYPES.link);
+
 /**
  * ── MEDIA, WHICH USED TO PRODUCE NO NODE AT ALL ──────────────────────────────────────────
  *
@@ -383,6 +416,7 @@ export function htmlToPortableText(html: string, opts: IngestOptions = {}): Port
       ...(allowsTables(opts.schema) ? [tableRule(key, (cell) => htmlToPortableText(cell, opts))] : []),
       mediaRule(key, opts.schema),
       ...(allowsStyled(opts.schema) ? [styledRule(key)] : []),
+      ...(allowsLinks(opts.schema) ? [classedLinkRule(key)] : []),
     ],
     keyGenerator: key,
   });

package/src/schema.ts

@@ -111,6 +111,8 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
       fields: [
         { name: "href", type: "string" },
         { name: "target", type: "string" },
+        // The site's own class on the `<a>`, kept so a styled link round-trips.
+        { name: "className", type: "string" },
       ],
     });
   }

package/src/styled.ts

@@ -22,8 +22,22 @@
  * NOT passed through — its value is a language of its own, bounded by `safeStyle` below.
  */
 
-/** Inline tags a `styled` annotation may wear. Nothing outside this list is ever rendered. */
-export const STYLED_TAGS = ["span", "small", "sup", "sub", "kbd", "abbr", "time"] as const;
+/**
+ * Inline tags a `styled` annotation may wear. Nothing outside this list is ever rendered.
+ *
+ * The decorator tags (`strong` … `code`) are here for the one case their decorator cannot
+ * hold: the site put a CLASS on them (`<strong class="text-yellow-500">`). A decorator is a
+ * bit with nowhere to keep a class, so without this the design died on ingest — which is what
+ * made agents rewrite a site's markup to dodge the loss. A bare `<strong>` still becomes the
+ * decorator (see `BARE_IS_DESIGN`).
+ */
+export const STYLED_TAGS = [
+  "span", "small", "sup", "sub", "kbd", "abbr", "time",
+  "strong", "b", "em", "i", "u", "s", "mark", "code", "q", "cite", "dfn", "var", "samp", "ins", "del",
+] as const;
+
+/** Tags whose bare form IS the design, so they are annotated even with no class. */
+export const BARE_IS_DESIGN: ReadonlySet<string> = new Set(["small", "sup", "sub", "kbd", "abbr", "time"]);
 
 export type StyledTag = (typeof STYLED_TAGS)[number];