@beyondwork/docx-react-component 1.0.29 → 1.0.30

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/runtime/workflow-markup.ts

@@ -0,0 +1,393 @@
+import type {
+  CommentSidebarSnapshot,
+  EditorAnchorProjection,
+  EditorStoryTarget,
+  FieldSnapshot,
+  ProtectionSnapshot,
+  RuntimeRenderSnapshot,
+  SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
+  TrackedChangesSnapshot,
+  WorkflowCandidateRange,
+  WorkflowCandidateRangeOptions,
+  WorkflowFieldMarkup,
+  WorkflowHighlightMarkup,
+  WorkflowMetadataMarkup,
+  WorkflowMetadataSnapshot,
+  WorkflowMarkupItem,
+  WorkflowMarkupSnapshot,
+  WorkflowOpaqueFragmentMarkup,
+  WorkflowProtectedRangeMarkup,
+  WorkflowRevisionMarkup,
+  WorkflowCommentMarkup,
+} from "../api/public-types";
+import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
+import { searchSurfaceBlocks } from "../core/search/search-text.ts";
+import { describeOpaqueFragment, isBlockedImportFeatureKey } from "../preservation/store.ts";
+import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
+
+export function collectWorkflowMarkupSnapshot(input: {
+  renderSnapshot: RuntimeRenderSnapshot;
+  fieldSnapshot: FieldSnapshot;
+  protectionSnapshot: ProtectionSnapshot;
+  preservation: CanonicalDocumentEnvelope["preservation"];
+  workflowMetadataSnapshot?: WorkflowMetadataSnapshot;
+}): WorkflowMarkupSnapshot {
+  const highlights: WorkflowHighlightMarkup[] = [];
+  const metadata = collectWorkflowMetadataMarkup(input.workflowMetadataSnapshot);
+  const fields: WorkflowFieldMarkup[] = [];
+  const opaqueFragments: WorkflowOpaqueFragmentMarkup[] = [];
+  const surface = input.renderSnapshot.surface;
+
+  if (surface) {
+    collectSurfaceMarkup(
+      surface.blocks,
+      MAIN_STORY_TARGET,
+      input.preservation,
+      highlights,
+      opaqueFragments,
+    );
+    for (const story of surface.secondaryStories) {
+      collectSurfaceMarkup(
+        story.blocks,
+        story.target,
+        input.preservation,
+        highlights,
+        opaqueFragments,
+      );
+    }
+
+    fields.push(...collectFieldMarkup(surface, input.fieldSnapshot));
+  }
+  opaqueFragments.push(...collectOpaqueFragmentMarkup(input.preservation, opaqueFragments));
+
+  const comments = input.renderSnapshot.comments.threads.map((thread): WorkflowCommentMarkup => ({
+    markupId: `comment:${thread.commentId}`,
+    kind: "comment",
+    commentId: thread.commentId,
+    anchor: thread.anchor,
+    label: thread.anchorLabel,
+    excerpt: thread.excerpt,
+    status: thread.status,
+    warningCount: thread.warningCount,
+    entryCount: thread.entryCount,
+    createdAt: thread.createdAt,
+    createdBy: thread.createdBy,
+  }));
+
+  const revisions = input.renderSnapshot.trackedChanges.revisions.map(
+    (revision): WorkflowRevisionMarkup => ({
+      markupId: `revision:${revision.revisionId}`,
+      kind: "revision",
+      revisionId: revision.revisionId,
+      revisionKind: revision.kind,
+      anchor: revision.anchor,
+      label: revision.label,
+      excerpt: revision.excerpt,
+      status: revision.status,
+      actionability: revision.actionability,
+      authorId: revision.authorId,
+      createdAt: revision.createdAt,
+      preserveOnlyReason: revision.preserveOnlyReason,
+    }),
+  );
+
+  const protectedRanges = input.protectionSnapshot.ranges
+    .filter(
+      (range): range is typeof range & { start: number; end: number } =>
+        typeof range.start === "number" && typeof range.end === "number",
+    )
+    .map(
+      (range): WorkflowProtectedRangeMarkup => ({
+        markupId: `protected-range:${range.rangeId}`,
+        kind: "protected_range",
+        rangeId: range.rangeId,
+        anchor: createRangeAnchor(range.start, range.end),
+        storyTarget: MAIN_STORY_TARGET,
+        label: `Protected range ${range.rangeId}`,
+        excerpt: range.enforcementReason,
+        enforced: range.enforced,
+        enforcementReason: range.enforcementReason,
+        editorGroup: range.editorGroup,
+        editor: range.editor,
+      }),
+    );
+
+  const items: WorkflowMarkupItem[] = [
+    ...highlights,
+    ...metadata,
+    ...comments,
+    ...revisions,
+    ...fields,
+    ...protectedRanges,
+    ...opaqueFragments,
+  ];
+
+  return {
+    totalCount: items.length,
+    items,
+    highlights,
+    metadata,
+    comments,
+    revisions,
+    fields,
+    protectedRanges,
+    opaqueFragments,
+  };
+}
+
+function collectWorkflowMetadataMarkup(
+  snapshot?: WorkflowMetadataSnapshot,
+): WorkflowMetadataMarkup[] {
+  if (!snapshot) {
+    return [];
+  }
+
+  const definitionsById = new Map(
+    snapshot.definitions.map((definition) => [definition.metadataId, definition] as const),
+  );
+
+  return snapshot.entries.flatMap((entry) => {
+    const definition = definitionsById.get(entry.metadataId);
+    if (!definition) {
+      return [];
+    }
+
+    return [{
+      markupId: `metadata:${entry.entryId}`,
+      kind: "metadata",
+      entryId: entry.entryId,
+      metadataId: entry.metadataId,
+      anchor: entry.anchor,
+      storyTarget: entry.storyTarget,
+      label: definition.label,
+      excerpt: definition.kind,
+      color: definition.color,
+      icon: definition.icon,
+      persistence: definition.persistence,
+      value: entry.value,
+      scopeId: entry.scopeId,
+      workItemId: entry.workItemId,
+    } satisfies WorkflowMetadataMarkup];
+  });
+}
+
+export function deriveWorkflowCandidateRangesFromMarkup(
+  snapshot: WorkflowMarkupSnapshot,
+  options: WorkflowCandidateRangeOptions = {},
+): WorkflowCandidateRange[] {
+  const allowedKinds = options.kinds ? new Set(options.kinds) : null;
+  const includeDetached = options.includeDetached === true;
+
+  return snapshot.items
+    .filter((item) => (allowedKinds ? allowedKinds.has(item.kind) : true))
+    .filter((item) => includeDetached || item.anchor.kind !== "detached")
+    .map(
+      (item): WorkflowCandidateRange => ({
+        candidateId: item.markupId,
+        storyTarget: item.storyTarget,
+        anchor: item.anchor,
+        label: item.label,
+        source: options.source ?? "host",
+      }),
+    );
+}
+
+function collectSurfaceMarkup(
+  blocks: readonly SurfaceBlockSnapshot[],
+  storyTarget: EditorStoryTarget,
+  preservation: CanonicalDocumentEnvelope["preservation"],
+  highlights: WorkflowHighlightMarkup[],
+  opaqueFragments: WorkflowOpaqueFragmentMarkup[],
+): void {
+  for (const block of blocks) {
+    if (block.kind === "paragraph") {
+      for (const segment of block.segments) {
+        collectSegmentMarkup(segment, storyTarget, preservation, highlights, opaqueFragments);
+      }
+      continue;
+    }
+
+    if (block.kind === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          collectSurfaceMarkup(cell.content, storyTarget, preservation, highlights, opaqueFragments);
+        }
+      }
+      continue;
+    }
+
+    if (block.kind === "sdt_block") {
+      collectSurfaceMarkup(block.children, storyTarget, preservation, highlights, opaqueFragments);
+      continue;
+    }
+
+    const fragment = preservation.opaqueFragments[block.fragmentId];
+    const descriptor = fragment ? describeOpaqueFragment(fragment) : null;
+    opaqueFragments.push({
+      markupId: `opaque:${block.fragmentId}`,
+      kind: "opaque_fragment",
+      fragmentId: block.fragmentId,
+      warningId: block.warningId,
+      anchor: createRangeAnchor(block.from, block.to),
+      storyTarget,
+      label: block.label,
+      excerpt: block.detail,
+      detail: block.detail,
+      blockedReasonCode:
+        block.blockedReasonCode ??
+        (fragment && descriptor && isBlockedImportFeatureKey(descriptor.featureKey)
+          ? "workflow_blocked_import"
+          : "workflow_preserve_only"),
+    });
+  }
+}
+
+function collectSegmentMarkup(
+  segment: SurfaceInlineSegment,
+  storyTarget: EditorStoryTarget,
+  preservation: CanonicalDocumentEnvelope["preservation"],
+  highlights: WorkflowHighlightMarkup[],
+  opaqueFragments: WorkflowOpaqueFragmentMarkup[],
+): void {
+  if (segment.kind === "text" && segment.markAttrs?.backgroundColor) {
+    highlights.push({
+      markupId: `highlight:${storyTargetKey(storyTarget)}:${segment.from}:${segment.to}:${segment.markAttrs.backgroundColor}`,
+      kind: "highlight",
+      anchor: createRangeAnchor(segment.from, segment.to),
+      storyTarget,
+      label: `Highlight ${segment.markAttrs.backgroundColor}`,
+      excerpt: segment.text,
+      color: segment.markAttrs.backgroundColor,
+      text: segment.text,
+    });
+    return;
+  }
+
+  if (segment.kind === "opaque_inline") {
+    const fragment = preservation.opaqueFragments[segment.fragmentId];
+    const descriptor = fragment ? describeOpaqueFragment(fragment) : null;
+    opaqueFragments.push({
+      markupId: `opaque:${segment.fragmentId}`,
+      kind: "opaque_fragment",
+      fragmentId: segment.fragmentId,
+      warningId: segment.warningId,
+      anchor: createRangeAnchor(segment.from, segment.to),
+      storyTarget,
+      label: segment.label,
+      excerpt: segment.detail,
+      detail: segment.detail,
+      blockedReasonCode:
+        segment.blockedReasonCode ??
+        (fragment && descriptor && isBlockedImportFeatureKey(descriptor.featureKey)
+          ? "workflow_blocked_import"
+          : "workflow_preserve_only"),
+    });
+  }
+}
+
+function collectFieldMarkup(
+  surface: RuntimeRenderSnapshot["surface"],
+  fieldSnapshot: FieldSnapshot,
+): WorkflowFieldMarkup[] {
+  if (!surface) {
+    return [];
+  }
+
+  const stories = [
+    { blocks: surface.blocks, storyTarget: MAIN_STORY_TARGET },
+    ...surface.secondaryStories.map((story) => ({
+      blocks: story.blocks,
+      storyTarget: story.target,
+    })),
+  ];
+
+  return fieldSnapshot.fields.flatMap((field) => {
+    const displayText = field.displayText.trim();
+    if (!displayText) {
+      return [];
+    }
+
+    for (const story of stories) {
+      const matches = searchSurfaceBlocks(story.blocks, displayText, { limit: 2 });
+      if (matches.length === 1) {
+        const match = matches[0]!;
+        return [
+          {
+            markupId: `field:${field.index}`,
+            kind: "field",
+            anchor: createRangeAnchor(match.from, match.to),
+            storyTarget: story.storyTarget,
+            label: displayText,
+            excerpt: field.instruction,
+            fieldIndex: field.index,
+            fieldFamily: field.fieldFamily,
+            fieldTarget: field.fieldTarget,
+            refreshStatus: field.refreshStatus,
+            displayText: field.displayText,
+          } satisfies WorkflowFieldMarkup,
+        ];
+      }
+    }
+
+    return [];
+  });
+}
+
+function collectOpaqueFragmentMarkup(
+  preservation: CanonicalDocumentEnvelope["preservation"],
+  existing: WorkflowOpaqueFragmentMarkup[],
+): WorkflowOpaqueFragmentMarkup[] {
+  const seen = new Set(existing.map((item) => item.fragmentId));
+
+  return Object.values(preservation.opaqueFragments)
+    .filter(
+      (fragment) =>
+        !seen.has(fragment.fragmentId)
+        && fragment.packagePartName === "/word/document.xml",
+    )
+    .map((fragment) => {
+      const descriptor = describeOpaqueFragment(fragment);
+      const blockedReasonCode = isBlockedImportFeatureKey(descriptor.featureKey)
+        ? "workflow_blocked_import"
+        : "workflow_preserve_only";
+
+      return {
+        markupId: `opaque:${fragment.fragmentId}`,
+        kind: "opaque_fragment",
+        fragmentId: fragment.fragmentId,
+        warningId: fragment.warningId,
+        anchor: createRangeAnchor(fragment.lastKnownRange.from, fragment.lastKnownRange.to),
+        storyTarget: MAIN_STORY_TARGET,
+        label: descriptor.label,
+        excerpt: descriptor.detail,
+        detail: descriptor.detail,
+        blockedReasonCode,
+      } satisfies WorkflowOpaqueFragmentMarkup;
+    });
+}
+
+function createRangeAnchor(from: number, to: number): EditorAnchorProjection {
+  return {
+    kind: "range",
+    from,
+    to,
+    assoc: {
+      start: -1,
+      end: 1,
+    },
+  };
+}
+
+function storyTargetKey(storyTarget: EditorStoryTarget): string {
+  switch (storyTarget.kind) {
+    case "main":
+      return "main";
+    case "header":
+    case "footer":
+      return `${storyTarget.kind}:${storyTarget.relationshipId}:${storyTarget.variant}:${storyTarget.sectionIndex ?? "none"}`;
+    case "footnote":
+    case "endnote":
+      return `${storyTarget.kind}:${storyTarget.noteId}`;
+  }
+}

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.