@bettercms-ai/richtext 0.7.0 → 0.8.0

package/package.json

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

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";