@beyondwork/docx-react-component 1.0.38 → 1.0.40

package/src/ui-tailwind/editor-surface/pm-page-break-decorations.ts

@@ -0,0 +1,389 @@
+/**
+ * In-flow page chrome as ProseMirror widget decorations.
+ *
+ * Every page boundary (between pages N and N+1) gets a widget whose DOM
+ * renders the full visible inter-page chrome:
+ *   - the bottom edge + footer band of page N (with a PAGE/NUMPAGES read
+ *     for page N)
+ *   - a visible vertical gap with the inter-page "separator line" between
+ *     the two frames (the frames themselves are rendered as CSS borders
+ *     on the chrome widget's sections, so no absolute overlay is needed)
+ *   - the top edge + header band of page N+1 (with a PAGE/NUMPAGES read
+ *     for page N+1)
+ *
+ * Because the chrome lives INSIDE the PM flow, it cannot drift relative
+ * to paragraphs: whatever height the browser paints for the paragraphs
+ * naturally stacks with the widget's fixed height.  No DOM measurement
+ * or absolute positioning is needed — this closes the alignment gap the
+ * earlier absolute-overlay approach suffered from.
+ *
+ * Double-clicking a band dispatches a custom event
+ * `wre-open-header-story-for-page` / `wre-open-footer-story-for-page`
+ * whose `detail.pageIndex` is the target page. The shell listens at the
+ * document level and routes to `runtime.openStory()`.
+ */
+
+import { Decoration } from "prosemirror-view";
+import type { RuntimePageGraph } from "../../runtime/layout/page-graph.ts";
+import { resolvePageFieldDisplayText } from "../../runtime/layout/resolve-page-fields.ts";
+
+export const PAGE_CHROME_DEFAULTS = {
+  headerBandPx: 32,
+  footerBandPx: 32,
+  interGapPx: 24,
+} as const;
+
+export function totalPageBreakGapPx(
+  dimensions: {
+    headerBandPx?: number;
+    footerBandPx?: number;
+    interGapPx?: number;
+  } = {},
+): number {
+  const header = dimensions.headerBandPx ?? PAGE_CHROME_DEFAULTS.headerBandPx;
+  const footer = dimensions.footerBandPx ?? PAGE_CHROME_DEFAULTS.footerBandPx;
+  const gap = dimensions.interGapPx ?? PAGE_CHROME_DEFAULTS.interGapPx;
+  return header + footer + gap;
+}
+
+export type PageChromePosture = "canvas" | "page";
+
+export interface PageBreakDecorationInput {
+  graph: RuntimePageGraph | null;
+  /** Controls the visual weight of the chrome; canvas is minimal. */
+  posture: PageChromePosture;
+  /** Height in px of each page's header band. Default 32. */
+  headerBandPx?: number;
+  /** Height in px of each page's footer band. Default 32. */
+  footerBandPx?: number;
+  /** Visible gap between the footer of page N and the header of page N+1. */
+  interGapPx?: number;
+  /**
+   * Map a canonical runtime offset to a ProseMirror document offset.  The
+   * surface's `PositionMap` provides this.  Optional — when omitted, we
+   * use the runtime offset as-is (tests without a mapped PM surface).
+   */
+  runtimeToPmOffset?: (runtimeOffset: number) => number | null;
+  /**
+   * Optional per-page preview text for the header band (`pageId` →
+   * flattened first-paragraph text with PAGE / NUMPAGES resolved).  When a
+   * preview is present it replaces the generic "Header" label in the band
+   * on that page.  See `resolve-page-previews.ts`.
+   */
+  headerPreviewByPageId?: ReadonlyMap<string, string>;
+  /** Same shape for footers. */
+  footerPreviewByPageId?: ReadonlyMap<string, string>;
+}
+
+export function buildPageBreakDecorations(
+  input: PageBreakDecorationInput,
+): Decoration[] {
+  const { graph, posture, runtimeToPmOffset } = input;
+  if (!graph || graph.pages.length < 2) return [];
+
+  const headerBandPx =
+    input.headerBandPx ?? PAGE_CHROME_DEFAULTS.headerBandPx;
+  const footerBandPx =
+    input.footerBandPx ?? PAGE_CHROME_DEFAULTS.footerBandPx;
+  const interGapPx = input.interGapPx ?? PAGE_CHROME_DEFAULTS.interGapPx;
+
+  const decorations: Decoration[] = [];
+  for (let i = 1; i < graph.pages.length; i += 1) {
+    const prev = graph.pages[i - 1]!;
+    const next = graph.pages[i]!;
+    if (next.isBlankFiller) continue;
+    const runtimeOffset = next.startOffset;
+    const pmOffset = runtimeToPmOffset
+      ? runtimeToPmOffset(runtimeOffset)
+      : runtimeOffset;
+    if (pmOffset === null || pmOffset === undefined) continue;
+
+    const prevPageLabel = pageLabelForChrome(prev, graph, posture);
+    const nextPageLabel = pageLabelForChrome(next, graph, posture);
+
+    const prevFooterPreview =
+      input.footerPreviewByPageId?.get(prev.pageId) ?? "";
+    const nextHeaderPreview =
+      input.headerPreviewByPageId?.get(next.pageId) ?? "";
+
+    decorations.push(
+      Decoration.widget(
+        pmOffset,
+        () =>
+          buildChromeWidgetDom({
+            posture,
+            prevPageId: prev.pageId,
+            prevPageIndex: prev.pageIndex,
+            nextPageId: next.pageId,
+            nextPageIndex: next.pageIndex,
+            headerBandPx,
+            footerBandPx,
+            interGapPx,
+            prevPageLabel,
+            nextPageLabel,
+            hasPrevFooterStory: Boolean(prev.stories.footer),
+            hasNextHeaderStory: Boolean(next.stories.header),
+            prevFooterPreview,
+            nextHeaderPreview,
+          }),
+        {
+          side: -1,
+          key: `pb-${prev.pageId}-${next.pageId}-${posture}`,
+          ignoreSelection: true,
+          stopEvent: (event) => {
+            // Keep the dbl-click from bubbling into PM and stealing focus.
+            if (event.type === "mousedown" || event.type === "click") {
+              return true;
+            }
+            return false;
+          },
+        },
+      ),
+    );
+  }
+  return decorations;
+}
+
+/**
+ * The page label shown in both the footer band of page N and the header
+ * band of page N+1.  Canvas mode uses a terser "N / M" format because the
+ * dotted line is already minimal; page mode uses the full "Page N of M".
+ */
+function pageLabelForChrome(
+  page: { stories: { displayPageNumber: number } },
+  graph: RuntimePageGraph,
+  posture: PageChromePosture,
+): string {
+  const total = graph.contentPageCount;
+  if (posture === "canvas") {
+    return `${page.stories.displayPageNumber} / ${total}`;
+  }
+  return `Page ${page.stories.displayPageNumber} of ${total}`;
+}
+
+interface ChromeWidgetInput {
+  posture: PageChromePosture;
+  prevPageId: string;
+  prevPageIndex: number;
+  nextPageId: string;
+  nextPageIndex: number;
+  headerBandPx: number;
+  footerBandPx: number;
+  interGapPx: number;
+  prevPageLabel: string;
+  nextPageLabel: string;
+  hasPrevFooterStory: boolean;
+  hasNextHeaderStory: boolean;
+  prevFooterPreview: string;
+  nextHeaderPreview: string;
+}
+
+function buildChromeWidgetDom(input: ChromeWidgetInput): HTMLElement {
+  const root = document.createElement("div");
+  root.className = "wre-page-chrome-widget";
+  root.setAttribute("data-kind", "page-chrome-widget");
+  root.setAttribute("data-posture", input.posture);
+  root.setAttribute("data-prev-page-id", input.prevPageId);
+  root.setAttribute("data-next-page-id", input.nextPageId);
+  root.setAttribute("data-prev-page-index", String(input.prevPageIndex));
+  root.setAttribute("data-next-page-index", String(input.nextPageIndex));
+  root.contentEditable = "false";
+  root.setAttribute("aria-hidden", "false");
+  root.style.display = "block";
+  root.style.width = "100%";
+  root.style.userSelect = "none";
+
+  if (input.posture === "canvas") {
+    // Single dotted horizontal line with a small page-number callout.
+    root.style.height = `${input.interGapPx + 1}px`;
+    root.style.position = "relative";
+
+    const line = document.createElement("div");
+    line.className = "wre-page-chrome-canvas-seam";
+    line.style.position = "absolute";
+    line.style.left = "0";
+    line.style.right = "0";
+    line.style.top = `${Math.round(input.interGapPx / 2)}px`;
+    line.style.height = "0";
+    line.style.borderTop = "1px dotted var(--color-border, rgba(0,0,0,0.3))";
+    root.appendChild(line);
+
+    const badge = document.createElement("span");
+    badge.className = "wre-page-chrome-canvas-badge";
+    badge.setAttribute("data-kind", "canvas-seam-badge");
+    badge.textContent = input.nextPageLabel;
+    badge.style.position = "absolute";
+    badge.style.top = `${Math.round(input.interGapPx / 2) - 9}px`;
+    badge.style.left = "50%";
+    badge.style.transform = "translateX(-50%)";
+    badge.style.fontSize = "10px";
+    badge.style.letterSpacing = "0.12em";
+    badge.style.textTransform = "uppercase";
+    badge.style.color = "var(--color-text-tertiary, #6b7280)";
+    badge.style.backgroundColor =
+      "var(--color-surface, rgba(255,255,255,0.9))";
+    badge.style.padding = "0 8px";
+    root.appendChild(badge);
+    return root;
+  }
+
+  // PAGE-MODE chrome: footer band of prev + visible gap + header band of next.
+  root.style.height = `${
+    input.footerBandPx + input.interGapPx + input.headerBandPx
+  }px`;
+  root.style.position = "relative";
+
+  const footer = buildBand({
+    kind: "footer",
+    pageId: input.prevPageId,
+    pageIndex: input.prevPageIndex,
+    pageLabel: input.prevPageLabel,
+    bandPx: input.footerBandPx,
+    position: "top",
+    hasStory: input.hasPrevFooterStory,
+    previewText: input.prevFooterPreview,
+  });
+  root.appendChild(footer);
+
+  const separator = document.createElement("div");
+  separator.className = "wre-page-chrome-separator";
+  separator.style.position = "absolute";
+  separator.style.left = "0";
+  separator.style.right = "0";
+  separator.style.top = `${input.footerBandPx}px`;
+  separator.style.height = `${input.interGapPx}px`;
+  // Background: two subtle page-edge shadows mimicking real paper gap.
+  separator.style.background =
+    "linear-gradient(to bottom, rgba(0,0,0,0.045), rgba(0,0,0,0) 40%, rgba(0,0,0,0) 60%, rgba(0,0,0,0.035))";
+  root.appendChild(separator);
+
+  const header = buildBand({
+    kind: "header",
+    pageId: input.nextPageId,
+    pageIndex: input.nextPageIndex,
+    pageLabel: input.nextPageLabel,
+    bandPx: input.headerBandPx,
+    position: "bottom",
+    topOffsetPx: input.footerBandPx + input.interGapPx,
+    hasStory: input.hasNextHeaderStory,
+    previewText: input.nextHeaderPreview,
+  });
+  root.appendChild(header);
+
+  return root;
+}
+
+function buildBand(input: {
+  kind: "header" | "footer";
+  pageId: string;
+  pageIndex: number;
+  pageLabel: string;
+  bandPx: number;
+  position: "top" | "bottom";
+  topOffsetPx?: number;
+  hasStory: boolean;
+  previewText: string;
+}): HTMLElement {
+  const band = document.createElement("div");
+  band.className = `wre-page-chrome-band wre-page-chrome-band-${input.kind}`;
+  band.setAttribute("data-band-kind", input.kind);
+  band.setAttribute("data-page-id", input.pageId);
+  band.setAttribute("data-page-index", String(input.pageIndex));
+  band.style.position = "absolute";
+  band.style.left = "0";
+  band.style.right = "0";
+  band.style.top = `${input.topOffsetPx ?? 0}px`;
+  band.style.height = `${input.bandPx}px`;
+  band.style.display = "flex";
+  band.style.alignItems = "center";
+  band.style.justifyContent = "space-between";
+  band.style.padding = "0 16px";
+  band.style.fontSize = "10px";
+  band.style.letterSpacing = "0.12em";
+  band.style.textTransform = "uppercase";
+  band.style.color = "var(--color-text-tertiary, #6b7280)";
+  band.style.backgroundColor =
+    "var(--color-surface-subtle, rgba(0,0,0,0.02))";
+  band.style.borderTop =
+    input.kind === "header"
+      ? "1px solid var(--color-border, rgba(0,0,0,0.08))"
+      : "none";
+  band.style.borderBottom =
+    input.kind === "footer"
+      ? "1px solid var(--color-border, rgba(0,0,0,0.08))"
+      : "none";
+  // Bands are interactive: double-click fires a custom event the shell
+  // forwards to `runtime.openStory()`.
+  band.style.pointerEvents = "auto";
+  band.style.cursor = input.hasStory ? "pointer" : "default";
+  band.title = input.hasStory
+    ? `Double-click to edit ${input.kind}`
+    : `No ${input.kind} defined for this page`;
+
+  const label = document.createElement("span");
+  label.className = "wre-page-chrome-band-label";
+  if (input.previewText && input.previewText.trim().length > 0) {
+    // Show the live content (with PAGE/NUMPAGES resolved) rather than the
+    // static "Header" / "Footer" placeholder.  Band is compact so truncate
+    // at ~80 chars visually via CSS overflow; keep raw in textContent.
+    label.textContent = input.previewText;
+    label.style.textTransform = "none";
+    label.style.letterSpacing = "0";
+    label.style.fontSize = "11px";
+    label.style.color = "var(--color-text-secondary, #374151)";
+    label.style.overflow = "hidden";
+    label.style.textOverflow = "ellipsis";
+    label.style.whiteSpace = "nowrap";
+    label.style.maxWidth = "70%";
+  } else {
+    label.textContent = input.kind === "header" ? "Header" : "Footer";
+  }
+  band.appendChild(label);
+
+  const pageLabel = document.createElement("span");
+  pageLabel.className = "wre-page-chrome-band-page";
+  pageLabel.textContent = input.pageLabel;
+  band.appendChild(pageLabel);
+
+  if (input.hasStory) {
+    band.addEventListener("dblclick", (event) => {
+      event.stopPropagation();
+      event.preventDefault();
+      const eventName =
+        input.kind === "header"
+          ? "wre-open-header-story-for-page"
+          : "wre-open-footer-story-for-page";
+      // Use the band's owning document's `CustomEvent` constructor so the
+      // event passes through jsdom's instance-of check.  In a real browser
+      // `band.ownerDocument.defaultView.CustomEvent` is the same as the
+      // global `CustomEvent`; in jsdom the two differ and the global one
+      // fails `dispatchEvent`'s internal Event-type convert step.
+      const view = band.ownerDocument?.defaultView as
+        | (Window & typeof globalThis)
+        | null;
+      const Ctor = view?.CustomEvent ?? CustomEvent;
+      band.dispatchEvent(
+        new Ctor(eventName, {
+          bubbles: true,
+          detail: { pageIndex: input.pageIndex, pageId: input.pageId },
+        }),
+      );
+    });
+  }
+
+  return band;
+}
+
+/**
+ * Resolve a `PAGE` or `NUMPAGES` value for a specific page, using the graph.
+ * Small re-export + convenience wrapper so the PM surface's field-atom
+ * renderer can swap the cached display text without importing the
+ * resolver module directly.
+ */
+export function resolvePageFieldForPage(
+  family: "PAGE" | "NUMPAGES",
+  cachedText: string,
+  input: { page: RuntimePageGraph["pages"][number]; graph: RuntimePageGraph },
+): string {
+  return resolvePageFieldDisplayText(family, cachedText, input);
+}

package/src/ui-tailwind/editor-surface/pm-schema.ts

@@ -137,6 +137,7 @@ export const editorSchema = new Schema({
         numberingSuffix: { default: null },
         numberingMarkerWidth: { default: null },
         numberingMarkerJustification: { default: null },
+        numberingMarkerRunProperties: { default: null },
         alignment: { default: null },
         spacingBefore: { default: null },
         spacingAfter: { default: null },
@@ -266,10 +267,47 @@ export const editorSchema = new Schema({
               : numberingSuffix === "space"
                 ? "0.5rem"
                 : "0.75rem";
+
+          const markerRunProperties = node.attrs.numberingMarkerRunProperties as
+            | {
+                bold?: boolean;
+                italic?: boolean;
+                underline?: string;
+                fontSizeHalfPoints?: number;
+                colorHex?: string;
+                fontFamily?: string;
+                fontFamilyAscii?: string;
+              }
+            | null;
+
+          const baseClasses: string[] = ["inline-flex", "select-none", "items-center"];
+          if (!markerRunProperties) {
+            baseClasses.push("text-tertiary", "font-[family-name:var(--font-legal-sans)]");
+          }
+
           const prefixStyles = [
             `font-variant-numeric: tabular-nums`,
             `justify-content: ${resolveMarkerJustificationCss(numberingMarkerJustification)}`,
           ];
+
+          if (markerRunProperties) {
+            if (markerRunProperties.bold) prefixStyles.push("font-weight: bold");
+            if (markerRunProperties.italic) prefixStyles.push("font-style: italic");
+            if (markerRunProperties.underline && markerRunProperties.underline !== "none") {
+              prefixStyles.push("text-decoration: underline");
+            }
+            if (typeof markerRunProperties.fontSizeHalfPoints === "number") {
+              prefixStyles.push(`font-size: ${markerRunProperties.fontSizeHalfPoints / 2}pt`);
+            }
+            if (markerRunProperties.colorHex && markerRunProperties.colorHex !== "auto") {
+              prefixStyles.push(`color: #${markerRunProperties.colorHex.toLowerCase()}`);
+            }
+            const family = markerRunProperties.fontFamilyAscii ?? markerRunProperties.fontFamily;
+            if (family && SAFE_FONT_RE.test(family)) {
+              prefixStyles.push(`font-family: ${family}`);
+            }
+          }
+
           if (hasResolvedMarkerWidth) {
             const markerWidthPx = Math.max(1, Math.round(numberingMarkerWidth / 20));
             prefixStyles.push(
@@ -285,11 +323,11 @@ export const editorSchema = new Schema({
               `margin-right: ${fallbackMarginRight}`,
             );
           }
+
           children.push([
             "span",
             {
-              class:
-                "inline-flex select-none items-center text-tertiary font-[family-name:var(--font-legal-sans)]",
+              class: baseClasses.join(" "),
               contenteditable: "false",
               "data-numbering-prefix": numberingPrefix,
               ...(typeof numberingLevel === "number"