@beyondwork/docx-react-component 1.0.1 → 1.0.2

package/src/runtime/table-schema.ts

@@ -0,0 +1,140 @@
+/**
+ * ProseMirror table node specifications for first-class table editing.
+ *
+ * These specs define the structure required for tables in the ProseMirror schema,
+ * compatible with prosemirror-tables when used as a dependency, or standalone for
+ * basic cell-content editing.
+ *
+ * All four specs must be included together when merging into a schema because
+ * table_row references both table_cell and table_header_cell in its content model.
+ */
+
+import type { NodeSpec } from "prosemirror-model";
+
+function resolveRenderedColspan(attrs: {
+  colspan?: number | null;
+  gridSpan?: number | null;
+}): number {
+  if (typeof attrs.colspan === "number" && attrs.colspan > 1) {
+    return attrs.colspan;
+  }
+  if (typeof attrs.gridSpan === "number" && attrs.gridSpan > 1) {
+    return attrs.gridSpan;
+  }
+  return 1;
+}
+
+export const tableNodeSpec: NodeSpec = {
+  content: "table_row+",
+  tableRole: "table",
+  group: "block",
+  isolating: true,
+  attrs: {
+    styleId: { default: null },
+    propertiesXml: { default: null },
+    gridColumns: { default: [] },
+  },
+  parseDOM: [{ tag: "table" }],
+  toDOM() {
+    return ["table", { class: "border-collapse w-full my-2 text-sm" }, ["tbody", 0]];
+  },
+};
+
+export const tableRowNodeSpec: NodeSpec = {
+  content: "(table_cell | table_header_cell)+",
+  tableRole: "row",
+  attrs: {
+    propertiesXml: { default: null },
+  },
+  parseDOM: [{ tag: "tr" }],
+  toDOM() {
+    return ["tr", 0];
+  },
+};
+
+export const tableCellNodeSpec: NodeSpec = {
+  content: "paragraph+",
+  tableRole: "cell",
+  isolating: true,
+  attrs: {
+    propertiesXml: { default: null },
+    gridSpan: { default: 1 },
+    verticalMerge: { default: null },
+    colspan: { default: 1 },
+    rowspan: { default: 1 },
+    colwidth: { default: null },
+  },
+  parseDOM: [
+    {
+      tag: "td",
+      getAttrs(dom: HTMLElement) {
+        const colspan = dom.getAttribute("colspan");
+        const rowspan = dom.getAttribute("rowspan");
+        return {
+          colspan: colspan ? Number.parseInt(colspan, 10) : 1,
+          rowspan: rowspan ? Number.parseInt(rowspan, 10) : 1,
+        };
+      },
+    },
+  ],
+  toDOM(node) {
+    const attrs: Record<string, string> = {
+      class: "border border-primary/20 p-2 align-top",
+    };
+    const colspan = resolveRenderedColspan(node.attrs as { colspan?: number; gridSpan?: number });
+    if (colspan > 1) attrs.colspan = String(colspan);
+    if (node.attrs.rowspan > 1) attrs.rowspan = String(node.attrs.rowspan);
+    return ["td", attrs, 0];
+  },
+};
+
+export const tableHeaderCellNodeSpec: NodeSpec = {
+  content: "paragraph+",
+  tableRole: "header_cell",
+  isolating: true,
+  attrs: {
+    propertiesXml: { default: null },
+    gridSpan: { default: 1 },
+    verticalMerge: { default: null },
+    colspan: { default: 1 },
+    rowspan: { default: 1 },
+    colwidth: { default: null },
+  },
+  parseDOM: [
+    {
+      tag: "th",
+      getAttrs(dom: HTMLElement) {
+        const colspan = dom.getAttribute("colspan");
+        const rowspan = dom.getAttribute("rowspan");
+        return {
+          colspan: colspan ? Number.parseInt(colspan, 10) : 1,
+          rowspan: rowspan ? Number.parseInt(rowspan, 10) : 1,
+        };
+      },
+    },
+  ],
+  toDOM(node) {
+    const attrs: Record<string, string> = {
+      class: "border border-primary/20 p-2 align-top font-semibold bg-surface-raised",
+    };
+    const colspan = resolveRenderedColspan(node.attrs as { colspan?: number; gridSpan?: number });
+    if (colspan > 1) attrs.colspan = String(colspan);
+    if (node.attrs.rowspan > 1) attrs.rowspan = String(node.attrs.rowspan);
+    return ["th", attrs, 0];
+  },
+};
+
+/**
+ * Returns a record of all four table node specs to merge into an existing ProseMirror Schema.
+ *
+ * All four must be included together because table_row references both table_cell and
+ * table_header_cell in its content model.
+ */
+export function getTableNodeSpecs(): Record<string, NodeSpec> {
+  return {
+    table: tableNodeSpec,
+    table_row: tableRowNodeSpec,
+    table_cell: tableCellNodeSpec,
+    table_header_cell: tableHeaderCellNodeSpec,
+  };
+}

package/src/runtime/virtualized-rendering.ts

@@ -0,0 +1,258 @@
+import type {
+  EditorSurfaceSnapshot,
+  SurfaceBlockSnapshot,
+} from "../api/public-types";
+
+export interface VirtualizedRenderingMetrics {
+  blockId: string;
+  index: number;
+  top: number;
+  height: number;
+  bottom: number;
+}
+
+export interface VirtualizedRenderingSession {
+  blocks: SurfaceBlockSnapshot[];
+  metrics: VirtualizedRenderingMetrics[];
+  totalHeight: number;
+  averageBlockHeight: number;
+  estimatedPageCount: number;
+}
+
+export interface CreateVirtualizedRenderingSessionOptions {
+  averagePageHeight?: number;
+  paragraphBaseHeight?: number;
+  paragraphLineHeight?: number;
+  segmentWrapWidth?: number;
+  tableRowHeight?: number;
+  opaqueBlockHeight?: number;
+  sdtPaddingHeight?: number;
+}
+
+export interface VirtualizedViewport {
+  scrollTop: number;
+  viewportHeight: number;
+  overscanHeight?: number;
+}
+
+export interface VirtualizedWindow {
+  startIndex: number;
+  endIndex: number;
+  totalHeight: number;
+  offsetTop: number;
+  offsetBottom: number;
+  visibleBlocks: SurfaceBlockSnapshot[];
+  visibleMetrics: VirtualizedRenderingMetrics[];
+}
+
+const DEFAULT_PAGE_HEIGHT = 1120;
+const DEFAULT_PARAGRAPH_BASE_HEIGHT = 28;
+const DEFAULT_PARAGRAPH_LINE_HEIGHT = 18;
+const DEFAULT_SEGMENT_WRAP_WIDTH = 96;
+const DEFAULT_TABLE_ROW_HEIGHT = 44;
+const DEFAULT_OPAQUE_BLOCK_HEIGHT = 72;
+const DEFAULT_SDT_PADDING_HEIGHT = 24;
+
+export function createVirtualizedRenderingSession(
+  surface: EditorSurfaceSnapshot,
+  previous: VirtualizedRenderingSession | undefined = undefined,
+  options: CreateVirtualizedRenderingSessionOptions = {},
+): VirtualizedRenderingSession {
+  const blocks = surface.blocks;
+  const metrics = previous?.metrics ?? [];
+
+  if (metrics.length > blocks.length) {
+    metrics.length = blocks.length;
+  }
+
+  let cursor = 0;
+  for (let index = 0; index < blocks.length; index += 1) {
+    const block = blocks[index]!;
+    const height = estimateBlockHeight(block, options);
+    const top = cursor;
+    const bottom = top + height;
+    const metric = metrics[index];
+    if (metric) {
+      metric.blockId = block.blockId;
+      metric.index = index;
+      metric.top = top;
+      metric.height = height;
+      metric.bottom = bottom;
+    } else {
+      metrics.push({
+        blockId: block.blockId,
+        index,
+        top,
+        height,
+        bottom,
+      });
+    }
+    cursor = bottom;
+  }
+
+  const totalHeight = cursor;
+  const averageBlockHeight = blocks.length > 0 ? totalHeight / blocks.length : 0;
+  const estimatedPageCount =
+    totalHeight > 0
+      ? Math.max(
+          1,
+          Math.ceil(totalHeight / (options.averagePageHeight ?? DEFAULT_PAGE_HEIGHT)),
+        )
+      : 0;
+
+  if (previous) {
+    previous.blocks = blocks;
+    previous.metrics = metrics;
+    previous.totalHeight = totalHeight;
+    previous.averageBlockHeight = averageBlockHeight;
+    previous.estimatedPageCount = estimatedPageCount;
+    return previous;
+  }
+
+  return {
+    blocks,
+    metrics,
+    totalHeight,
+    averageBlockHeight,
+    estimatedPageCount,
+  };
+}
+
+export function computeVirtualizedWindow(
+  session: VirtualizedRenderingSession,
+  viewport: VirtualizedViewport,
+): VirtualizedWindow {
+  if (session.metrics.length === 0) {
+    return {
+      startIndex: 0,
+      endIndex: 0,
+      totalHeight: 0,
+      offsetTop: 0,
+      offsetBottom: 0,
+      visibleBlocks: [],
+      visibleMetrics: [],
+    };
+  }
+
+  const overscanHeight = Math.max(0, viewport.overscanHeight ?? viewport.viewportHeight * 0.5);
+  const windowTop = Math.max(0, viewport.scrollTop - overscanHeight);
+  const windowBottom = Math.min(
+    session.totalHeight,
+    viewport.scrollTop + viewport.viewportHeight + overscanHeight,
+  );
+  const startIndex = findFirstVisibleIndex(session.metrics, windowTop);
+  const endIndexExclusive = findLastVisibleIndex(session.metrics, windowBottom) + 1;
+  const safeEndIndex = Math.max(startIndex + 1, endIndexExclusive);
+  const visibleMetrics = session.metrics.slice(startIndex, safeEndIndex);
+  const visibleBlocks = session.blocks.slice(startIndex, safeEndIndex);
+  const lastMetric = visibleMetrics[visibleMetrics.length - 1]!;
+
+  return {
+    startIndex,
+    endIndex: safeEndIndex,
+    totalHeight: session.totalHeight,
+    offsetTop: visibleMetrics[0]?.top ?? 0,
+    offsetBottom: Math.max(0, session.totalHeight - lastMetric.bottom),
+    visibleBlocks,
+    visibleMetrics,
+  };
+}
+
+function findFirstVisibleIndex(
+  metrics: VirtualizedRenderingMetrics[],
+  top: number,
+): number {
+  let low = 0;
+  let high = metrics.length - 1;
+  let result = 0;
+
+  while (low <= high) {
+    const middle = (low + high) >> 1;
+    const metric = metrics[middle]!;
+    if (metric.bottom >= top) {
+      result = middle;
+      high = middle - 1;
+    } else {
+      low = middle + 1;
+    }
+  }
+
+  return result;
+}
+
+function findLastVisibleIndex(
+  metrics: VirtualizedRenderingMetrics[],
+  bottom: number,
+): number {
+  let low = 0;
+  let high = metrics.length - 1;
+  let result = metrics.length - 1;
+
+  while (low <= high) {
+    const middle = (low + high) >> 1;
+    const metric = metrics[middle]!;
+    if (metric.top <= bottom) {
+      result = middle;
+      low = middle + 1;
+    } else {
+      high = middle - 1;
+    }
+  }
+
+  return result;
+}
+
+function estimateBlockHeight(
+  block: SurfaceBlockSnapshot,
+  options: CreateVirtualizedRenderingSessionOptions,
+): number {
+  switch (block.kind) {
+    case "paragraph":
+      return estimateParagraphHeight(block, options);
+    case "table":
+      return Math.max(
+        options.tableRowHeight ?? DEFAULT_TABLE_ROW_HEIGHT,
+        block.rows.length * (options.tableRowHeight ?? DEFAULT_TABLE_ROW_HEIGHT),
+      );
+    case "opaque_block":
+      return options.opaqueBlockHeight ?? DEFAULT_OPAQUE_BLOCK_HEIGHT;
+    case "sdt_block":
+      return (
+        (options.sdtPaddingHeight ?? DEFAULT_SDT_PADDING_HEIGHT) +
+        block.children.reduce(
+          (total, child) => total + estimateBlockHeight(child, options),
+          0,
+        )
+      );
+    default:
+      return options.paragraphBaseHeight ?? DEFAULT_PARAGRAPH_BASE_HEIGHT;
+  }
+}
+
+function estimateParagraphHeight(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+  options: CreateVirtualizedRenderingSessionOptions,
+): number {
+  const wrapWidth = options.segmentWrapWidth ?? DEFAULT_SEGMENT_WRAP_WIDTH;
+  let consumedCharacters = 0;
+
+  for (const segment of block.segments) {
+    switch (segment.kind) {
+      case "text":
+        consumedCharacters += segment.text.length;
+        break;
+      case "image":
+        consumedCharacters += wrapWidth;
+        break;
+      default:
+        consumedCharacters += 4;
+        break;
+    }
+  }
+
+  const estimatedLines = Math.max(1, Math.ceil(consumedCharacters / wrapWidth));
+  return (
+    (options.paragraphBaseHeight ?? DEFAULT_PARAGRAPH_BASE_HEIGHT) +
+    estimatedLines * (options.paragraphLineHeight ?? DEFAULT_PARAGRAPH_LINE_HEIGHT)
+  );
+}

package/src/ui/README.md

@@ -0,0 +1,30 @@
+# UI
+
+This directory contains the public entry point and shared headless logic for the editor UI.
+
+## Entry Point
+
+`WordReviewEditor.tsx` is the public component. It bridges the `DocumentRuntime` to the Tailwind rendering layer in `src/ui-tailwind/`.
+
+## Headless Logic
+
+`headless/` contains pure, framework-free utilities shared across implementations:
+
+- `use-editor-keyboard.ts` — Keyboard event handler factory
+- `comment-decoration-model.ts` — Comment anchor → highlight class computation
+- `revision-decoration-model.ts` — Revision anchor → highlight class computation
+- `selection-helpers.ts` — Selection snapshot utilities
+
+## Session Capabilities
+
+`src/runtime/session-capabilities.ts` derives all UI control states from `RuntimeRenderSnapshot`. The `deriveCapabilities(snapshot, reviewMode)` function is called on every render in `WordReviewEditor.tsx` and the result is passed to the workspace components.
+
+## Shared Utilities
+
+`shared/revision-filters.ts` — Shared revision filtering and empty state helpers.
+
+## Rendering
+
+All visual rendering is in `src/ui-tailwind/`. See `docs/reference/word-review-editor-frontend-architecture.md` for the canonical architecture.
+
+Legacy inline-CSSProperties components have been removed.