@bettercms-ai/richtext 0.6.1 → 0.8.0

package/package.json

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

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>`;
 }
@@ -235,6 +243,11 @@ export interface RenderOptions {
    * sits on each `<li>`, because a wrapper per item would split the list into one-item lists.
    */
   bindingBase?: string;
+  /**
+   * Renders an embedded block this serialiser cannot resolve itself (a component, say). A
+   * string replaces the marker; `undefined` keeps it.
+   */
+  renderBlock?: (value: Record<string, unknown>) => string | undefined;
 }
 
 /**
@@ -269,6 +282,7 @@ const bindingAttrs = (base: string, key: unknown): string =>
 const buildComponents = (
   classes: HtmlClasses = {},
   binding?: { base: string; keys: ReadonlySet<unknown> },
+  renderBlock?: RenderOptions["renderBlock"],
 ): Partial<PortableTextHtmlComponents> => ({
   block: tagOverrides(classes, STYLE_TAGS),
   list: tagOverrides(classes, { bullet: "ul", number: "ol", check: "ul" }),
@@ -315,6 +329,8 @@ const buildComponents = (
        */
       const legacy = builtInTableToTable(value);
       if (legacy) return tableHtml(legacy);
+      const rendered = renderBlock?.(value as Record<string, unknown>);
+      if (rendered !== undefined) return rendered;
       const key = typeof v.schemaKey === "string" && TOKEN.test(v.schemaKey.replace(/^builtin:/, ""))
         ? v.schemaKey
         : "block";
@@ -392,11 +408,12 @@ export function portableTextToHtml(
   opts: RenderOptions = {},
 ): string {
   if (!Array.isArray(value) || value.length === 0) return "";
-  const components = opts.classes ? buildComponents(opts.classes) : defaultComponents;
+  const components =
+    opts.classes || opts.renderBlock ? buildComponents(opts.classes, undefined, opts.renderBlock) : defaultComponents;
 
   if (opts.bindingBase) {
     const base = opts.bindingBase;
-    const bound = buildComponents(opts.classes, { base, keys: new Set(value.map((n) => n._key)) });
+    const bound = buildComponents(opts.classes, { base, keys: new Set(value.map((n) => n._key)) }, opts.renderBlock);
     const out: string[] = [];
     for (let i = 0; i < value.length; ) {
       const node = value[i];

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/read.ts

@@ -1,4 +1,4 @@
-import { PORTABLE_TEXT_FORMAT, PT_TYPES, type PortableText } from "./types";
+import { EMBEDDED_COMPONENT_KEY, PORTABLE_TEXT_FORMAT, PT_TYPES, type PortableText } from "./types";
 import { lexicalToPortableText } from "./from-lexical";
 import { migrateTable } from "./table";
 import { randomKey, type KeyGenerator } from "./key";
@@ -231,3 +231,26 @@ export function readStructuredContent(props: unknown): PortableText | null {
       : null;
   return arr && arr.length > 0 ? (arr as PortableText) : null;
 }
+
+/** The `component` block an embed in rich text stands for. */
+export interface EmbeddedComponentBlock {
+  type: "component";
+  /** The node's `_key` — unique within its rich-text field only. */
+  id: string;
+  props: { componentId: string; overrides: Record<string, unknown> };
+}
+
+/**
+ * A component embedded in rich text, as the ordinary `component` block every renderer already
+ * draws — so an embed gets the same resolver, cycle guard and identity attributes as a placed
+ * instance. Null for any other node.
+ */
+export function embeddedComponentBlock(value: unknown): EmbeddedComponentBlock | null {
+  if (!isRecord(value) || value.schemaKey !== EMBEDDED_COMPONENT_KEY || !isRecord(value.fields)) return null;
+  const { componentId, overrides } = value.fields;
+  return {
+    type: "component",
+    id: typeof value._key === "string" ? value._key : "",
+    props: { componentId: String(componentId ?? ""), overrides: isRecord(overrides) ? overrides : {} },
+  };
+}

package/src/types.ts

@@ -276,6 +276,12 @@ export const STORABLE_BLOCK_TYPES: ReadonlySet<string> = new Set<string>([
 export const BUILTIN_IMAGE_KEY = "builtin:image" as const;
 export const BUILTIN_EMBED_KEY = "builtin:video" as const;
 
+/**
+ * The `schemaKey` of a component embedded in rich text. A wire value shared with the dashboard
+ * (`COMPONENT_SCHEMA_KEY`) and the backend (`RICHTEXT_COMPONENT_KEY`).
+ */
+export const EMBEDDED_COMPONENT_KEY = "component" as const;
+
 /**
  * Top-level nodes whose `_type` this platform cannot store or render, in document order.
  *