@bettercms-ai/richtext 0.7.0 → 0.8.1

package/package.json

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

@@ -10,6 +10,7 @@ import { resolveVideoSource } from "./video";
 import { builtInTableToTable } from "./table";
 import { safeHref } from "./href";
 import { isStyledTag, styledAttrEntries } from "./styled";
+import { richTextImageLayout } from "./image-layout";
 
 /**
  * Portable Text → HTML.
@@ -151,8 +152,15 @@ function imageHtml(value: unknown, classes: HtmlClasses): string {
   const src = mediaSrc(str(f.src));
   if (!src) return "";
   const caption = str(f.caption);
-  const img = `<img${cls(classes, "img")} src="${esc(src)}" alt="${esc(str(f.alt))}">`;
-  return `<figure${cls(classes, "figure")}>${img}${
+  const layout = richTextImageLayout(f);
+  // A placed image fills its figure; the figure carries the width and position (image-layout.ts).
+  const imgStyle = layout ? ' style="display:block;width:100%;height:auto"' : "";
+  const img = `<img${cls(classes, "img")} src="${esc(src)}" alt="${esc(str(f.alt))}"${imgStyle}>`;
+  const figureClass = [classes.figure, layout?.className].filter(Boolean).join(" ");
+  const figureAttrs = `${figureClass ? ` class="${esc(figureClass)}"` : ""}${
+    layout ? ` style="${esc(layout.figureStyle)}"` : ""
+  }`;
+  return `<figure${figureAttrs}>${img}${
     caption ? `<figcaption>${esc(caption)}</figcaption>` : ""
   }</figure>`;
 }

package/src/image-layout.ts

@@ -0,0 +1,69 @@
+/**
+ * Where a rich-text image sits and how wide it is — `align` and `size` on a `builtin:image`
+ * block's fields.
+ *
+ * WHY ONE TABLE. The editor draws the image with `align` (RichTextImageBlock's ALIGN_CLASS) and
+ * every delivered rendition is written by `portableTextToHtml` — which used to ignore `align`
+ * entirely, so an author centred an image and the published article showed it full width. The
+ * numbers here are the editor's, so the two cannot drift again: a centred image is 78% of the
+ * column, a left/right one 62%, full is the whole column. `size` overrides that width when set.
+ *
+ * The rendition carries classes (`bcms-rt-img--{align}`, `bcms-rt-img--{size}`) for a site that
+ * wants to restyle it, AND inline max-width/margins so it looks right on a site with no CSS for
+ * them at all — which is every site today.
+ */
+
+export const RICHTEXT_IMAGE_ALIGNS = ["full", "center", "left", "right"] as const;
+export type RichTextImageAlign = (typeof RICHTEXT_IMAGE_ALIGNS)[number];
+
+export const RICHTEXT_IMAGE_SIZES = ["small", "medium", "large", "full"] as const;
+export type RichTextImageSize = (typeof RICHTEXT_IMAGE_SIZES)[number];
+
+/** Column share when `size` is unset — the editor's ALIGN_CLASS max-widths. */
+export const RICHTEXT_IMAGE_ALIGN_MAX_WIDTH: Record<RichTextImageAlign, string> = {
+  full: "100%",
+  center: "78%",
+  left: "62%",
+  right: "62%",
+};
+
+/** Column share for an explicit `size`. Wins over the align default. */
+export const RICHTEXT_IMAGE_SIZE_MAX_WIDTH: Record<RichTextImageSize, string> = {
+  small: "33%",
+  medium: "50%",
+  large: "75%",
+  full: "100%",
+};
+
+export interface RichTextImageLayout {
+  align: RichTextImageAlign;
+  size: RichTextImageSize | null;
+  /** `bcms-rt-img bcms-rt-img--{align}[ bcms-rt-img--{size}]` */
+  className: string;
+  /** Inline CSS for the `<figure>`: max-width plus the margins that place it. */
+  figureStyle: string;
+}
+
+const oneOf = <T extends string>(list: readonly T[], v: unknown): T | null =>
+  typeof v === "string" && (list as readonly string[]).includes(v) ? (v as T) : null;
+
+/**
+ * The layout a block's fields ask for, or `null` when they ask for none — an image with neither
+ * a known `align` nor a known `size` renders exactly as it always did. Unknown values are
+ * ignored, never echoed: both come from stored data and end up in an attribute.
+ */
+export function richTextImageLayout(fields: Record<string, unknown>): RichTextImageLayout | null {
+  const alignValue = oneOf(RICHTEXT_IMAGE_ALIGNS, fields.align);
+  const size = oneOf(RICHTEXT_IMAGE_SIZES, fields.size);
+  if (!alignValue && !size) return null;
+  const align = alignValue ?? "full";
+  const maxWidth = size ? RICHTEXT_IMAGE_SIZE_MAX_WIDTH[size] : RICHTEXT_IMAGE_ALIGN_MAX_WIDTH[align];
+  // left hugs the start, right the end; centre and full centre (a sized full image is centred).
+  const [ml, mr] = align === "left" ? ["0", "auto"] : align === "right" ? ["auto", "0"] : ["auto", "auto"];
+  return {
+    align,
+    size,
+    className: `bcms-rt-img bcms-rt-img--${align}${size ? ` bcms-rt-img--${size}` : ""}`,
+    figureStyle: `max-width:${maxWidth};margin-left:${ml};margin-right:${mr}`,
+  };
+}

package/src/index.ts

@@ -10,3 +10,4 @@ export * from "./read";
 export * from "./accept";
 export * from "./features";
 export * from "./video";
+export * from "./image-layout";

package/src/ingest.ts

@@ -187,6 +187,35 @@ function tableRule(key: KeyGenerator, ingestCell: (html: string) => PortableText
   };
 }
 
+/** A code block's text, line breaks included: Lexical writes them as `<br>`, not newlines. */
+const codeText = (node: Node): string =>
+  node.nodeName.toLowerCase() === "br"
+    ? "\n"
+    : node.nodeType === 3
+      ? (node.textContent ?? "")
+      : [...node.childNodes].map(codeText).join("");
+
+/** `language-x` on the `<code>` (Markdown, our renderer) or `data-language` on the `<pre>` (Lexical, Shiki). */
+const codeLanguage = (pre: Element): string | undefined =>
+  /(?:^|\s)language-([\w+#-]+)/.exec(pre.querySelector("code")?.getAttribute("class") ?? "")?.[1] ??
+  (pre.getAttribute("data-language") || undefined);
+
+/**
+ * `<pre>` → the `bcmsCode` block the renderer turns back into `<pre><code>`. Without it the
+ * deserialiser's default flattens a code block to a paragraph with a `code` mark and its
+ * newlines collapsed: every imported code fence became one line of inline code.
+ */
+function codeRule(key: KeyGenerator): DeserializerRule {
+  return {
+    deserialize(el: Node, _next, createBlock) {
+      if (!isElement(el) || el.nodeName.toLowerCase() !== "pre") return undefined;
+      const language = codeLanguage(el);
+      const code = codeText(el).replace(/\n$/, "");
+      return createBlock({ _type: PT_TYPES.code, _key: key(), code, ...(language ? { language } : {}) });
+    },
+  };
+}
+
 /**
  * An inline element Portable Text does not model → the `styled` annotation.
  *
@@ -384,9 +413,9 @@ function mediaRule(key: KeyGenerator, schema: PtSchema | undefined): Deserialize
 const allowsStyled = (schema: PtSchema | undefined): boolean =>
   !schema || schema.annotations.some((a) => a.name === PT_TYPES.styled);
 
-/** Does this field's schema carry the table block object? Asked by name, not by capability. */
-const allowsTables = (schema: PtSchema | undefined): boolean =>
-  !schema || schema.blockObjects.some((o) => o.name === PT_TYPES.table);
+/** Does this field's schema carry the named block object? Asked by name, not by capability. */
+const allowsBlockObject = (schema: PtSchema | undefined, name: string): boolean =>
+  !schema || schema.blockObjects.some((o) => o.name === name);
 
 const isElement = (n: unknown): n is Element =>
   !!n && typeof n === "object" && (n as Node).nodeType === 1;
@@ -413,7 +442,8 @@ export function htmlToPortableText(html: string, opts: IngestOptions = {}): Port
      * accepts only images.
      */
     rules: [
-      ...(allowsTables(opts.schema) ? [tableRule(key, (cell) => htmlToPortableText(cell, opts))] : []),
+      ...(allowsBlockObject(opts.schema, PT_TYPES.table) ? [tableRule(key, (cell) => htmlToPortableText(cell, opts))] : []),
+      ...(allowsBlockObject(opts.schema, PT_TYPES.code) ? [codeRule(key)] : []),
       mediaRule(key, opts.schema),
       ...(allowsStyled(opts.schema) ? [styledRule(key)] : []),
       ...(allowsLinks(opts.schema) ? [classedLinkRule(key)] : []),