@beyondwork/docx-react-component 1.0.42 → 1.0.45

package/src/ui-tailwind/page-stack/tw-region-block-renderer.tsx

@@ -0,0 +1,374 @@
+import React from "react";
+
+import type {
+  SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
+} from "../../api/public-types.ts";
+import {
+  buildMarkerStyle,
+  buildParagraphStyle,
+  buildSegmentStyle,
+  hasStyleEntries,
+  headingClassList,
+  resolveHeadingLevel,
+} from "../editor-surface/tw-page-block-view.helpers.ts";
+
+// ---------------------------------------------------------------------------
+// TwRegionBlockRenderer (P8.4)
+//
+// Read-only React DOM renderer for `SurfaceBlockSnapshot[]`.  Mounted by the
+// per-page region bands — header, footer, footnote area, endnote area — so
+// typography matches the body's `tw-page-block-view` output exactly.
+//
+// Uses the same pure helpers as `tw-page-block-view` (extracted into
+// `tw-page-block-view.helpers.ts`) so indents, margins, line heights, and
+// numbering-marker geometry stay identical across all regions.
+//
+// Unlike the body renderer this component:
+//   - Never mounts a PM view; it is pure presentational React.
+//   - Sets `contentEditable={false}` on its root.
+//   - Emits `data-block-kind` + `data-block-id` on every block element so
+//     downstream region diagnostics can introspect what rendered.
+//   - Emits a `<colgroup>` on every table (P6.a) so column widths come from
+//     the canonical `gridColumns`, not intrinsic cell measurement.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Inline segment renderer — mirrors `tw-page-block-view`'s `renderSegment`.
+// ---------------------------------------------------------------------------
+
+function renderSegment(seg: SurfaceInlineSegment): React.ReactNode {
+  switch (seg.kind) {
+    case "text": {
+      const style = buildSegmentStyle(seg.marks, seg.markAttrs);
+      const content = seg.text;
+      if (!hasStyleEntries(style)) {
+        return <React.Fragment key={seg.segmentId}>{content}</React.Fragment>;
+      }
+      return (
+        <span key={seg.segmentId} style={style}>
+          {content}
+        </span>
+      );
+    }
+    case "tab":
+      return (
+        <span
+          key={seg.segmentId}
+          data-node-type="tab"
+          style={{ display: "inline-block", width: "32px", minWidth: "8px" }}
+        >
+          {"\u00A0"}
+        </span>
+      );
+    case "hard_break":
+      return <br key={seg.segmentId} />;
+    case "image":
+      return (
+        <span
+          key={seg.segmentId}
+          data-node-type="image"
+          style={{
+            display: "inline-block",
+            width: "48px",
+            height: "32px",
+            backgroundColor: "#e0e0e0",
+            verticalAlign: "middle",
+            margin: "0 4px",
+            borderRadius: "2px",
+          }}
+          title={seg.altText ?? "Image"}
+        />
+      );
+    case "field_ref":
+      return (
+        <span
+          key={seg.segmentId}
+          data-node-type="field_ref"
+          style={{ opacity: 0.6, fontSize: "0.85em" }}
+        >
+          [field]
+        </span>
+      );
+    case "note_ref":
+      return (
+        <span
+          key={seg.segmentId}
+          data-node-type="note_ref"
+          style={{ verticalAlign: "super", fontSize: "0.75em" }}
+        >
+          {seg.label}
+        </span>
+      );
+    case "opaque_inline":
+      return (
+        <span
+          key={seg.segmentId}
+          data-node-type="opaque_inline"
+          style={{ opacity: 0.6, fontSize: "0.85em" }}
+        >
+          {seg.displayText ?? seg.label}
+        </span>
+      );
+    default:
+      return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Block renderers
+// ---------------------------------------------------------------------------
+
+function RegionParagraph({
+  block,
+}: {
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>;
+}): React.ReactElement {
+  const headingLevel = resolveHeadingLevel(block.styleId, block.outlineLevel);
+  const classes: string[] = ["leading-relaxed"];
+  if (headingLevel) {
+    classes.push(...headingClassList(headingLevel));
+  }
+
+  const pStyle = buildParagraphStyle(block);
+
+  // Numbering prefix span — matches tw-page-block-view so region content that
+  // happens to carry numbering (e.g. footnote bodies authored as lists) shows
+  // the same marker geometry.
+  const numberingPrefix = block.numberingPrefix;
+  const numberingSuffix = block.numberingSuffix;
+  const resolvedNumbering = block.resolvedNumbering;
+  const markerRunProperties = resolvedNumbering?.markerRunProperties;
+  const markerWidth = resolvedNumbering?.geometry?.markerLane?.width;
+  const markerJustification = resolvedNumbering?.geometry?.markerJustification;
+
+  const prefixSpan =
+    numberingPrefix != null ? (
+      <span
+        className={[
+          "inline-flex",
+          "select-none",
+          "items-center",
+          ...(!markerRunProperties
+            ? ["text-tertiary", "font-[family-name:var(--font-legal-sans)]"]
+            : []),
+        ].join(" ")}
+        contentEditable={false}
+        data-numbering-prefix={numberingPrefix}
+        {...(typeof resolvedNumbering?.level === "number"
+          ? { "data-numbering-level": String(resolvedNumbering.level) }
+          : {})}
+        {...(numberingSuffix ? { "data-numbering-suffix": numberingSuffix } : {})}
+        style={buildMarkerStyle(
+          numberingPrefix,
+          numberingSuffix,
+          markerRunProperties,
+          markerWidth,
+          markerJustification,
+        )}
+      >
+        {numberingPrefix}
+      </span>
+    ) : null;
+
+  const attrs: React.HTMLAttributes<HTMLDivElement> & {
+    "data-block-kind": "paragraph";
+    "data-block-id": string;
+    "data-heading-level"?: string;
+    "data-numbered"?: string;
+    "data-contextual-spacing"?: string;
+  } = {
+    "data-block-kind": "paragraph",
+    "data-block-id": block.blockId,
+    className: classes.join(" "),
+    style: hasStyleEntries(pStyle) ? pStyle : undefined,
+  };
+
+  if (headingLevel) attrs["data-heading-level"] = String(headingLevel);
+  if (block.numbering) attrs["data-numbered"] = "true";
+  if (block.contextualSpacing) attrs["data-contextual-spacing"] = "true";
+  if (block.bidi) attrs.dir = "rtl";
+
+  return (
+    <div {...attrs}>
+      {prefixSpan}
+      <span className="pm-paragraph-content">
+        {block.segments.map((seg) => renderSegment(seg))}
+      </span>
+    </div>
+  );
+}
+
+function RegionTable({
+  block,
+}: {
+  block: Extract<SurfaceBlockSnapshot, { kind: "table" }>;
+}): React.ReactElement {
+  const tableStyle: React.CSSProperties = {
+    borderCollapse: "collapse",
+    width: "100%",
+  };
+  if (block.alignment === "center") {
+    tableStyle.marginLeft = "auto";
+    tableStyle.marginRight = "auto";
+  }
+
+  // P6.a: emit a `<colgroup>` so column widths come from canonical
+  // `gridColumns` (twips), not intrinsic measurement.  Widths in pt per
+  // P13.a so they self-scale under CSS `zoom`.
+  const gridColumns = block.gridColumns ?? [];
+
+  return (
+    <table
+      data-block-kind="table"
+      data-block-id={block.blockId}
+      data-node-type="table"
+      style={tableStyle}
+    >
+      {gridColumns.length > 0 ? (
+        <colgroup>
+          {gridColumns.map((widthTwips, colIdx) => (
+            <col
+              key={colIdx}
+              style={{ width: `${widthTwips / 20}pt` }}
+            />
+          ))}
+        </colgroup>
+      ) : null}
+      <tbody>
+        {block.rows.map((row, rowIdx) => (
+          <tr
+            key={rowIdx}
+            style={
+              row.height != null && row.heightRule === "exact"
+                ? { height: `${row.height / 20}pt` }
+                : row.height != null && row.heightRule === "atLeast"
+                  ? { minHeight: `${row.height / 20}pt` }
+                  : undefined
+            }
+          >
+            {row.cells.map((cell, cellIdx) => {
+              if (cell.verticalMerge === "continue") {
+                return null;
+              }
+              const cellStyle: React.CSSProperties = {};
+              if (cell.backgroundColor) cellStyle.backgroundColor = `#${cell.backgroundColor}`;
+              if (cell.verticalAlign) cellStyle.verticalAlign = cell.verticalAlign;
+              if (cell.borderTop) cellStyle.borderTop = cell.borderTop;
+              if (cell.borderRight) cellStyle.borderRight = cell.borderRight;
+              if (cell.borderBottom) cellStyle.borderBottom = cell.borderBottom;
+              if (cell.borderLeft) cellStyle.borderLeft = cell.borderLeft;
+
+              return (
+                <td
+                  key={cellIdx}
+                  colSpan={cell.colspan > 1 ? cell.colspan : undefined}
+                  rowSpan={cell.rowspan > 1 ? cell.rowspan : undefined}
+                  style={Object.keys(cellStyle).length > 0 ? cellStyle : undefined}
+                >
+                  {cell.content.map((childBlock) => (
+                    <RegionBlockItem key={childBlock.blockId} block={childBlock} />
+                  ))}
+                </td>
+              );
+            })}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+function RegionOpaque({
+  block,
+}: {
+  block: Extract<SurfaceBlockSnapshot, { kind: "opaque_block" }>;
+}): React.ReactElement {
+  return (
+    <div
+      data-block-kind="opaque"
+      data-block-id={block.blockId}
+      data-node-type="opaque_block"
+      style={{
+        opacity: 0.5,
+        borderLeft: "3px solid #aaa",
+        paddingLeft: "8px",
+        margin: "4px 0",
+        fontSize: "0.85em",
+        color: "#666",
+      }}
+    >
+      {block.label || "[Locked content]"}
+    </div>
+  );
+}
+
+function RegionBlockItem({
+  block,
+}: {
+  block: SurfaceBlockSnapshot;
+}): React.ReactElement | null {
+  switch (block.kind) {
+    case "paragraph":
+      return <RegionParagraph block={block} />;
+    case "table":
+      return <RegionTable block={block} />;
+    case "sdt_block":
+      return (
+        <section
+          data-block-kind="sdt"
+          data-block-id={block.blockId}
+          data-node-type="sdt_block"
+          style={{ margin: "8px 0" }}
+        >
+          {block.children.map((child) => (
+            <RegionBlockItem key={child.blockId} block={child} />
+          ))}
+        </section>
+      );
+    case "opaque_block":
+      return <RegionOpaque block={block} />;
+    default:
+      return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public export
+// ---------------------------------------------------------------------------
+
+export interface TwRegionBlockRendererProps {
+  /** Blocks to render in document order. */
+  blocks: readonly SurfaceBlockSnapshot[];
+  /** Optional class name applied to the root wrapper. */
+  className?: string;
+}
+
+/**
+ * TwRegionBlockRenderer — read-only React renderer for a region's
+ * `SurfaceBlockSnapshot[]`.  Used by the header / footer / footnote /
+ * endnote bands that P8 mounts per page.
+ *
+ * The root wrapper is `contentEditable={false}` and carries
+ * `data-region-block-renderer` so region chrome overlays can target it.
+ * No PM decorations, no `contenteditable=true` — this renderer is pure
+ * presentational DOM.
+ */
+export function TwRegionBlockRenderer({
+  blocks,
+  className,
+}: TwRegionBlockRendererProps): React.ReactElement {
+  const rootClasses = ["ProseMirror"];
+  if (className) rootClasses.push(className);
+  return (
+    <div
+      className={rootClasses.join(" ")}
+      contentEditable={false}
+      data-region-block-renderer=""
+    >
+      {blocks.map((block) => (
+        <RegionBlockItem key={block.blockId} block={block} />
+      ))}
+    </div>
+  );
+}

package/src/ui-tailwind/page-stack/use-visible-block-range.ts

@@ -0,0 +1,157 @@
+import * as React from "react";
+
+/**
+ * Fallback estimate of blocks per page. Used ONLY when no page markers
+ * are available (pre-observer window or a degenerate empty-pageMarkers
+ * input). Once the observer fires, actual per-page spans are read from
+ * `data-page-first-block-index` / `data-page-last-block-index` markers.
+ * Short (title-only) or very long (large-table) pages deviate from this,
+ * but the fallback is transient and only affects the initial render.
+ */
+const ESTIMATED_BLOCKS_PER_PAGE_FALLBACK = 50;
+
+/**
+ * Block-range hook — returns the range of surface block indices that should
+ * be rendered in PM as "real" (non-placeholder) blocks.
+ *
+ * Sources of truth:
+ * 1. IntersectionObserver on `[data-page-frame]` markers in the PM DOM.
+ * 2. Selection head block-index — always included (selection-guard).
+ * 3. Overscan — ±N pages around the visible set to avoid jank when scrolling.
+ *
+ * If the selection is far off-screen, the returned range spans both the
+ * visible window AND the selection's page (with the gap between filled in).
+ * Gap-filling is a deliberate correctness choice: position preservation does
+ * NOT require continuous viewport coverage, but continuous coverage simplifies
+ * the snapshot-projection step downstream.
+ */
+export interface VisibleBlockRangeInput {
+  pageMarkers: readonly HTMLElement[];
+  overscanPages: number;
+  selectionBlockIndex: number | null;
+  totalBlockCount: number;
+}
+
+export interface BlockRange {
+  start: number; // inclusive
+  end: number; // exclusive
+}
+
+function readBlockIndex(el: HTMLElement, attr: string): number | null {
+  const v = el.getAttribute(attr);
+  if (v === null) return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+export function useVisibleBlockRange(input: VisibleBlockRangeInput): BlockRange {
+  const { pageMarkers, overscanPages, selectionBlockIndex, totalBlockCount } = input;
+  const [visiblePages, setVisiblePages] = React.useState<Set<number>>(() => new Set());
+
+  React.useEffect(() => {
+    // Reset: marker set changed (e.g. document reload). Stale page indices
+    // from the previous observer would look up against new markers and miss,
+    // falling through to the `Infinity` fallback and producing a transient
+    // over-wide range. Clear them now so the new observer's first callback
+    // is the single source of truth.
+    setVisiblePages(new Set());
+
+    if (pageMarkers.length === 0) return;
+    const view = pageMarkers[0].ownerDocument?.defaultView;
+    if (!view?.IntersectionObserver) return;
+
+    const observer = new view.IntersectionObserver(
+      (entries) => {
+        setVisiblePages((prev) => {
+          const next = new Set(prev);
+          let changed = false;
+          for (const entry of entries) {
+            const idx = readBlockIndex(entry.target as HTMLElement, "data-page-frame");
+            if (idx === null) continue;
+            const was = next.has(idx);
+            if (entry.isIntersecting && !was) {
+              next.add(idx);
+              changed = true;
+            } else if (!entry.isIntersecting && was) {
+              next.delete(idx);
+              changed = true;
+            }
+          }
+          return changed ? next : prev;
+        });
+      },
+      { root: null, rootMargin: "0px", threshold: 0 },
+    );
+
+    for (const marker of pageMarkers) observer.observe(marker);
+    return () => observer.disconnect();
+  }, [pageMarkers]);
+
+  return React.useMemo(() => {
+    if (totalBlockCount <= 0) return { start: 0, end: 0 };
+    if (visiblePages.size === 0 && selectionBlockIndex === null) {
+      // No visibility signal yet — return initial-load window (first 2 × overscanPages worth).
+      const initialEnd = Math.min(totalBlockCount, (overscanPages * 2 + 1) * ESTIMATED_BLOCKS_PER_PAGE_FALLBACK);
+      return { start: 0, end: initialEnd };
+    }
+
+    // Expand visiblePages by ±overscanPages.
+    const expanded = new Set<number>();
+    for (const p of visiblePages) {
+      for (let d = -overscanPages; d <= overscanPages; d++) expanded.add(p + d);
+    }
+
+    // Translate page indices → block indices using marker attrs.
+    let minBlock = Infinity;
+    let maxBlock = -Infinity;
+    for (const marker of pageMarkers) {
+      const idx = readBlockIndex(marker, "data-page-frame");
+      if (idx === null || !expanded.has(idx)) continue;
+      const first = readBlockIndex(marker, "data-page-first-block-index");
+      const last = readBlockIndex(marker, "data-page-last-block-index");
+      if (first !== null) minBlock = Math.min(minBlock, first);
+      if (last !== null) maxBlock = Math.max(maxBlock, last + 1);
+    }
+    if (minBlock === Infinity) {
+      minBlock = 0;
+      maxBlock = Math.min(totalBlockCount, (overscanPages * 2 + 1) * ESTIMATED_BLOCKS_PER_PAGE_FALLBACK);
+    }
+
+    // Selection-guard: if selection is outside [minBlock, maxBlock), extend to cover
+    // the entire page that contains the selection.
+    if (selectionBlockIndex !== null) {
+      if (selectionBlockIndex < minBlock) {
+        // Find the page that contains selectionBlockIndex and extend to its start.
+        for (const marker of pageMarkers) {
+          const first = readBlockIndex(marker, "data-page-first-block-index");
+          const last = readBlockIndex(marker, "data-page-last-block-index");
+          if (first !== null && last !== null && selectionBlockIndex >= first && selectionBlockIndex <= last) {
+            if (first < minBlock) minBlock = first;
+            break;
+          }
+        }
+        // Fallback: just include the block itself.
+        if (selectionBlockIndex < minBlock) minBlock = selectionBlockIndex;
+      }
+      if (selectionBlockIndex >= maxBlock) {
+        // Find the page that contains selectionBlockIndex and extend to its end.
+        for (const marker of pageMarkers) {
+          const first = readBlockIndex(marker, "data-page-first-block-index");
+          const last = readBlockIndex(marker, "data-page-last-block-index");
+          if (first !== null && last !== null && selectionBlockIndex >= first && selectionBlockIndex <= last) {
+            if (last + 1 > maxBlock) maxBlock = last + 1;
+            break;
+          }
+        }
+        // Fallback: just include the block itself.
+        if (selectionBlockIndex >= maxBlock) maxBlock = selectionBlockIndex + 1;
+      }
+    }
+
+    // Clamp to doc bounds.
+    return {
+      start: Math.max(0, minBlock),
+      end: Math.min(totalBlockCount, maxBlock),
+    };
+  }, [visiblePages, selectionBlockIndex, pageMarkers, overscanPages, totalBlockCount]);
+}

package/src/ui-tailwind/review/comment-markdown-renderer.tsx

@@ -0,0 +1,155 @@
+import React from "react";
+
+import type {
+  CommentAttachment,
+  CommentBody,
+  CommentMention,
+} from "../../api/comment-presentation-types";
+import { sanitizeMarkdown } from "../../runtime/markdown-sanitizer";
+
+export interface CommentMarkdownRendererProps {
+  body: CommentBody;
+  mentions?: CommentMention[];
+  attachments?: CommentAttachment[];
+  /**
+   * Resolves an attachment's OOXML `relationshipId` (from `word/_rels/`) to
+   * an object-URL / href that can be fed to an `<img src>`. Hosts that do
+   * not carry image attachments can omit this; the renderer then falls back
+   * to the attachment's display name or alt text.
+   */
+  resolveAttachmentHref?: (relationshipId: string) => string | undefined;
+  className?: string;
+}
+
+export function CommentMarkdownRenderer(props: CommentMarkdownRendererProps) {
+  const { body, mentions = [], attachments = [], resolveAttachmentHref } = props;
+  const { text, sanitized: sanitizedOnRender } = sanitizeMarkdown(body.text);
+  const wasSanitized = Boolean(body.sanitized) || sanitizedOnRender;
+
+  const paragraphs = text
+    .split(/\n\s*\n/)
+    .map((p) => p.trimEnd())
+    .filter((p) => p.length > 0);
+
+  return (
+    <div data-testid="comment-body" className={props.className}>
+      {paragraphs.map((paragraph, idx) => (
+        <p key={idx}>
+          {renderInline(paragraph, mentions, attachments, resolveAttachmentHref)}
+        </p>
+      ))}
+      {wasSanitized ? (
+        <span
+          data-testid="comment-body-sanitized-badge"
+          title="This content was sanitized on render for safety."
+          className="inline-block rounded px-1 py-px text-[9px] font-medium uppercase tracking-wide text-comment bg-warning-soft"
+        >
+          sanitized
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
+const INLINE_PATTERN =
+  /(`[^`\n]+`)|(!\[([^\]]*)\]\(([^)]+)\))|(\[([^\]]+)\]\(([^)]+)\))|(\*\*[^*\n]+\*\*)|(\*[^*\n]+\*)/g;
+
+function renderInline(
+  text: string,
+  mentions: readonly CommentMention[],
+  attachments: readonly CommentAttachment[],
+  resolveAttachmentHref?: (relationshipId: string) => string | undefined,
+): React.ReactNode[] {
+  const nodes: React.ReactNode[] = [];
+  let cursor = 0;
+  let key = 0;
+  INLINE_PATTERN.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = INLINE_PATTERN.exec(text)) !== null) {
+    if (match.index > cursor) {
+      nodes.push(text.slice(cursor, match.index));
+    }
+    const [
+      ,
+      codeMatch,
+      imageMatch,
+      imageAlt,
+      imageTarget,
+      linkMatch,
+      linkLabel,
+      linkTarget,
+      boldMatch,
+      italicMatch,
+    ] = match;
+
+    if (codeMatch) {
+      nodes.push(<code key={key++}>{codeMatch.slice(1, -1)}</code>);
+    } else if (imageMatch) {
+      nodes.push(
+        renderAttachmentImage(
+          key++,
+          imageAlt ?? "",
+          imageTarget ?? "",
+          attachments,
+          resolveAttachmentHref,
+        ),
+      );
+    } else if (linkMatch) {
+      nodes.push(
+        renderLinkOrMention(key++, linkLabel ?? "", linkTarget ?? "", mentions),
+      );
+    } else if (boldMatch) {
+      nodes.push(<strong key={key++}>{boldMatch.slice(2, -2)}</strong>);
+    } else if (italicMatch) {
+      nodes.push(<em key={key++}>{italicMatch.slice(1, -1)}</em>);
+    }
+    cursor = match.index + match[0].length;
+  }
+  if (cursor < text.length) nodes.push(text.slice(cursor));
+  return nodes;
+}
+
+function renderAttachmentImage(
+  key: number,
+  alt: string,
+  target: string,
+  attachments: readonly CommentAttachment[],
+  resolveAttachmentHref?: (relationshipId: string) => string | undefined,
+): React.ReactNode {
+  // Sanitizer enforces `bw:attachment:` scheme on images; anything else is
+  // already downgraded to a bare `[alt]` by the time we see it.
+  if (!target.startsWith("bw:attachment:")) {
+    return <span key={key}>{alt}</span>;
+  }
+  const attachmentId = target.slice("bw:attachment:".length);
+  const attachment = attachments.find((a) => a.id === attachmentId);
+  const relationshipId = attachment?.relationshipId;
+  const href = relationshipId ? resolveAttachmentHref?.(relationshipId) : undefined;
+  if (href) {
+    return <img key={key} src={href} alt={alt || attachment?.displayName || ""} />;
+  }
+  return <span key={key}>{alt || attachment?.displayName || ""}</span>;
+}
+
+function renderLinkOrMention(
+  key: number,
+  label: string,
+  target: string,
+  mentions: readonly CommentMention[],
+): React.ReactNode {
+  if (target.startsWith("bw:user:")) {
+    const userId = target.slice("bw:user:".length);
+    const mention = mentions.find((m) => m.userId === userId);
+    const text = label || `@${mention?.displayName ?? userId}`;
+    return (
+      <span key={key} data-testid={`comment-mention-${userId}`} className="font-medium text-accent">
+        {text}
+      </span>
+    );
+  }
+  return (
+    <a key={key} href={target} target="_blank" rel="noopener noreferrer">
+      {label}
+    </a>
+  );
+}