@beyondwork/docx-react-component 1.0.18 → 1.0.20

package/src/runtime/document-search.ts

@@ -0,0 +1,145 @@
+import type {
+  DocumentNavigationSnapshot,
+  EditorStoryTarget,
+  SearchOptions,
+  SearchResultSnapshot,
+  SelectionSnapshot,
+} from "../api/public-types";
+import {
+  MAIN_STORY_TARGET,
+  storyTargetsEqual,
+} from "../core/selection/mapping.ts";
+import {
+  createSelectionSnapshot,
+  type CanonicalDocumentEnvelope,
+} from "../core/state/editor-state.ts";
+import {
+  searchSecondaryStories,
+  searchSurfaceBlocks,
+} from "../core/search/search-text.ts";
+import { findPageForOffset } from "./document-navigation.ts";
+import {
+  buildResolvedSections,
+  resolveSectionForStoryTarget,
+} from "./document-layout.ts";
+import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
+
+export function searchDocument(
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  activeStory: EditorStoryTarget,
+  navigation: DocumentNavigationSnapshot,
+  query: string,
+  options: SearchOptions = {},
+): SearchResultSnapshot[] {
+  const normalizedQuery = query.trim();
+  if (!normalizedQuery) {
+    return [];
+  }
+
+  const mainSurface = createEditorSurfaceSnapshot(
+    document,
+    createSelectionSnapshot(selection.anchor, selection.head),
+    MAIN_STORY_TARGET,
+  );
+  const sections = buildResolvedSections(document);
+  const combined: SearchResultSnapshot[] = [];
+
+  for (const match of searchSurfaceBlocks(mainSurface.blocks, normalizedQuery, options)) {
+    const pageIndex = findPageForOffset(navigation.pages, match.from);
+    combined.push({
+      resultId: `search-main-${combined.length}`,
+      anchor: {
+        kind: "range",
+        from: match.from,
+        to: match.to,
+        assoc: {
+          start: -1,
+          end: 1,
+        },
+      },
+      excerpt: match.excerpt,
+      isActive: false,
+      storyTarget: MAIN_STORY_TARGET,
+      sectionIndex: navigation.pages[pageIndex]?.sectionIndex ?? 0,
+      pageIndex,
+    });
+  }
+
+  for (const match of searchSecondaryStories(
+    mainSurface.secondaryStories,
+    normalizedQuery,
+    options,
+  )) {
+    const section = resolveSectionForStoryTarget(
+      document,
+      sections,
+      match.storyTarget,
+    );
+    const pageIndex =
+      section === undefined
+        ? undefined
+        : navigation.pages.find((page) => page.sectionIndex === section.index)
+          ?.pageIndex ?? 0;
+
+    combined.push({
+      resultId: `search-secondary-${combined.length}`,
+      anchor: {
+        kind: "range",
+        from: match.from,
+        to: match.to,
+        assoc: {
+          start: -1,
+          end: 1,
+        },
+      },
+      excerpt: match.excerpt,
+      isActive: false,
+      storyTarget: match.storyTarget,
+      ...(section ? { sectionIndex: section.index } : {}),
+      ...(pageIndex !== undefined ? { pageIndex } : {}),
+    });
+  }
+
+  const limited = combined.slice(0, options.limit ?? Number.POSITIVE_INFINITY);
+  const activeIndex = getActiveSearchResultIndex(limited, selection, activeStory);
+
+  return limited.map((result, index) => ({
+    ...result,
+    isActive: index === activeIndex,
+  }));
+}
+
+function getActiveSearchResultIndex(
+  results: readonly SearchResultSnapshot[],
+  selection: SelectionSnapshot,
+  activeStory: EditorStoryTarget,
+): number {
+  if (results.length === 0) {
+    return -1;
+  }
+
+  const selectionFrom = Math.min(selection.anchor, selection.head);
+  const selectionTo = Math.max(selection.anchor, selection.head);
+  const activeIndex = results.findIndex((result) => {
+    if (!result.storyTarget || !storyTargetsEqual(result.storyTarget, activeStory)) {
+      return false;
+    }
+
+    if (result.anchor.kind !== "range") {
+      return false;
+    }
+
+    if (selectionFrom === selectionTo) {
+      return (
+        selectionFrom >= result.anchor.from && selectionFrom <= result.anchor.to
+      );
+    }
+
+    return (
+      selectionFrom < result.anchor.to && selectionTo > result.anchor.from
+    );
+  });
+
+  return activeIndex >= 0 ? activeIndex : 0;
+}

package/src/runtime/numbering-prefix.ts

@@ -9,8 +9,14 @@ interface NumberingSequenceState {
   lastLevel: number | null;
 }
 
+export interface NumberingPrefixResult {
+  text: string;
+  suffix?: "tab" | "space" | "nothing";
+}
+
 export interface NumberingPrefixResolver {
   resolve(numbering: ParagraphNode["numbering"] | undefined): string | null;
+  resolveDetailed(numbering: ParagraphNode["numbering"] | undefined): NumberingPrefixResult | null;
 }
 
 const DEFAULT_START_AT = 1;
@@ -20,34 +26,49 @@ export function createNumberingPrefixResolver(
 ): NumberingPrefixResolver {
   const sequenceStates = new Map<string, NumberingSequenceState>();
 
+  function resolveInternal(numbering: ParagraphNode["numbering"] | undefined): NumberingPrefixResult | null {
+    if (!numbering) {
+      return null;
+    }
+
+    const instance = catalog.instances[numbering.numberingInstanceId];
+    if (!instance) {
+      return null;
+    }
+
+    const definition = catalog.abstractDefinitions[instance.abstractNumberingId];
+    if (!definition) {
+      return null;
+    }
+
+    const levelDefinitions = new Map(
+      definition.levels.map((level) => [level.level, level] as const),
+    );
+    const levelDefinition = levelDefinitions.get(numbering.level);
+    if (!levelDefinition || levelDefinition.format === "none") {
+      return null;
+    }
+
+    const sequenceState = getSequenceState(sequenceStates, numbering.numberingInstanceId);
+    advanceSequence(sequenceState, numbering.level, levelDefinitions, instance.overrides);
+
+    // When isLegalNumbering is true, use decimal format for all referenced levels
+    const effectiveLevelDefs = levelDefinition.isLegalNumbering
+      ? new Map(Array.from(levelDefinitions.entries()).map(([k, v]) => [k, { ...v, format: "decimal" }]))
+      : levelDefinitions;
+
+    const text = renderLevelText(levelDefinition.text, sequenceState.counters, effectiveLevelDefs);
+    if (text === null) return null;
+    return { text, suffix: levelDefinition.suffix };
+  }
+
   return {
     resolve(numbering) {
-      if (!numbering) {
-        return null;
-      }
-
-      const instance = catalog.instances[numbering.numberingInstanceId];
-      if (!instance) {
-        return null;
-      }
-
-      const definition = catalog.abstractDefinitions[instance.abstractNumberingId];
-      if (!definition) {
-        return null;
-      }
-
-      const levelDefinitions = new Map(
-        definition.levels.map((level) => [level.level, level] as const),
-      );
-      const levelDefinition = levelDefinitions.get(numbering.level);
-      if (!levelDefinition || levelDefinition.format === "none") {
-        return null;
-      }
-
-      const sequenceState = getSequenceState(sequenceStates, numbering.numberingInstanceId);
-      advanceSequence(sequenceState, numbering.level, levelDefinitions, instance.overrides);
-
-      return renderLevelText(levelDefinition.text, sequenceState.counters, levelDefinitions);
+      const result = resolveInternal(numbering);
+      return result?.text ?? null;
+    },
+    resolveDetailed(numbering) {
+      return resolveInternal(numbering);
     },
   };
 }

package/src/runtime/page-layout-estimation.ts

@@ -0,0 +1,212 @@
+import type {
+  PageLayoutSnapshot,
+  SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
+} from "../api/public-types";
+
+const DEFAULT_FONT_SIZE_POINTS = 12;
+const DEFAULT_LINE_HEIGHT_TWIPS = 280;
+const MIN_BLOCK_HEIGHT_TWIPS = 240;
+const TABLE_ROW_PADDING_TWIPS = 120;
+
+export const DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP = 1 / 15;
+
+export function estimateBlockHeight(
+  block: SurfaceBlockSnapshot | undefined,
+  columnWidth: number,
+): number {
+  if (!block) {
+    return 0;
+  }
+
+  switch (block.kind) {
+    case "paragraph":
+      return estimateParagraphHeight(block, columnWidth);
+    case "table":
+      return estimateTableHeight(block, columnWidth);
+    case "sdt_block":
+      return Math.max(
+        MIN_BLOCK_HEIGHT_TWIPS,
+        block.children.reduce((total, child) => total + estimateBlockHeight(child, columnWidth), 0),
+      );
+    case "opaque_block":
+      return block.label === "Section break" ? 0 : MIN_BLOCK_HEIGHT_TWIPS;
+  }
+}
+
+export function estimateParagraphHeight(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+  columnWidth: number,
+): number {
+  const lineHeight = estimateParagraphLineHeight(block);
+  const lineCount = estimateParagraphLineCount(block, columnWidth);
+  const spacingBefore = block.spacing?.before ?? 0;
+  const spacingAfter = block.spacing?.after ?? 0;
+  return Math.max(
+    MIN_BLOCK_HEIGHT_TWIPS,
+    lineHeight * lineCount + spacingBefore + spacingAfter,
+  );
+}
+
+export function estimateParagraphLineHeight(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): number {
+  const explicitLine = block.spacing?.line;
+  if (typeof explicitLine === "number" && explicitLine > 0) {
+    return explicitLine;
+  }
+
+  const fontSizeHalfPoints = block.segments.find(
+    (segment): segment is Extract<SurfaceInlineSegment, { kind: "text" }> =>
+      segment.kind === "text" && typeof segment.markAttrs?.fontSize === "number",
+  )?.markAttrs?.fontSize;
+  const fontSizePoints =
+    typeof fontSizeHalfPoints === "number"
+      ? fontSizeHalfPoints / 2
+      : DEFAULT_FONT_SIZE_POINTS;
+  return Math.max(
+    DEFAULT_LINE_HEIGHT_TWIPS,
+    Math.round(fontSizePoints * 20 * 1.35),
+  );
+}
+
+export function estimateParagraphLineCount(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+  columnWidth: number,
+): number {
+  const averageCharWidth = estimateAverageCharWidth(block);
+  const charsPerLine = Math.max(12, Math.floor(columnWidth / averageCharWidth));
+  let lineCount = 1;
+  let currentLineChars = estimatedPrefixLength(block);
+
+  for (const segment of block.segments) {
+    switch (segment.kind) {
+      case "text":
+        currentLineChars += Array.from(segment.text).length;
+        while (currentLineChars > charsPerLine) {
+          lineCount += 1;
+          currentLineChars -= charsPerLine;
+        }
+        break;
+      case "tab":
+        currentLineChars += 4;
+        break;
+      case "hard_break":
+        lineCount += 1;
+        currentLineChars = 0;
+        break;
+      case "image":
+        lineCount += Math.max(1, Math.round(segment.display === "floating" ? 2 : 1));
+        currentLineChars = 0;
+        break;
+      case "note_ref":
+        currentLineChars += 1;
+        break;
+      case "opaque_inline":
+        if (segment.presentation !== "quiet-marker") {
+          currentLineChars += segment.label.length > 0 ? 1 : 0;
+        }
+        break;
+    }
+  }
+
+  return Math.max(1, lineCount);
+}
+
+export function getUsablePageHeight(layout: PageLayoutSnapshot): number {
+  return Math.max(
+    1440,
+    layout.pageHeight - layout.marginTop - layout.marginBottom,
+  );
+}
+
+export interface PageColumnMetric {
+  width: number;
+  space: number;
+}
+
+export function getUsableColumnMetrics(
+  layout: PageLayoutSnapshot,
+): PageColumnMetric[] {
+  const usableWidth = Math.max(
+    1440,
+    layout.pageWidth - layout.marginLeft - layout.marginRight - layout.gutter,
+  );
+  const columnCount = Math.max(1, layout.columns);
+  if (
+    !layout.equalWidthColumns &&
+    layout.columnDefinitions.length > 0
+  ) {
+    return layout.columnDefinitions.map((column, index) => ({
+      width: Math.max(720, column.width),
+      space:
+        index < layout.columnDefinitions.length - 1
+          ? Math.max(0, column.space ?? 0)
+          : 0,
+    }));
+  }
+
+  const width = columnCount <= 1
+    ? usableWidth
+    : Math.max(720, Math.floor(usableWidth / columnCount));
+  return Array.from({ length: columnCount }, () => ({
+    width,
+    space: 0,
+  }));
+}
+
+export function getUsableColumnWidth(layout: PageLayoutSnapshot): number {
+  return getUsableColumnMetrics(layout)[0]?.width ?? 1440;
+}
+
+function estimateTableHeight(
+  block: Extract<SurfaceBlockSnapshot, { kind: "table" }>,
+  columnWidth: number,
+): number {
+  let totalHeight = 0;
+  for (const row of block.rows) {
+    const explicitHeight = row.height ?? 0;
+    if (explicitHeight > 0) {
+      totalHeight += explicitHeight;
+      continue;
+    }
+
+    let rowHeight = MIN_BLOCK_HEIGHT_TWIPS;
+    for (const cell of row.cells) {
+      const cellHeight = cell.content.reduce(
+        (total, child) => total + estimateBlockHeight(child, columnWidth),
+        0,
+      );
+      rowHeight = Math.max(rowHeight, cellHeight + TABLE_ROW_PADDING_TWIPS);
+    }
+    totalHeight += rowHeight;
+  }
+  return Math.max(MIN_BLOCK_HEIGHT_TWIPS, totalHeight);
+}
+
+function estimateAverageCharWidth(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): number {
+  const fontSizeHalfPoints = block.segments.find(
+    (segment): segment is Extract<SurfaceInlineSegment, { kind: "text" }> =>
+      segment.kind === "text" && typeof segment.markAttrs?.fontSize === "number",
+  )?.markAttrs?.fontSize;
+  const fontSizePoints =
+    typeof fontSizeHalfPoints === "number"
+      ? fontSizeHalfPoints / 2
+      : DEFAULT_FONT_SIZE_POINTS;
+  return Math.max(96, Math.round(fontSizePoints * 12));
+}
+
+function estimatedPrefixLength(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): number {
+  const prefix = block.numberingPrefix ?? "";
+  const suffix =
+    block.numberingSuffix === "space"
+      ? 1
+      : block.numberingSuffix === "tab"
+        ? 4
+        : 0;
+  return prefix.length + suffix;
+}

package/src/runtime/read-only-diagnostics-runtime.ts

@@ -155,6 +155,7 @@ function createDiagnosticsRenderSnapshot(
     isDirty: false,
     readOnly: true,
     selection: collapsedSelection(),
+    activeStory: { kind: "main" },
     documentStats: {
       storyLength: 0,
       commentCount: 0,
@@ -192,6 +193,14 @@ function createDiagnosticsRenderSnapshot(
       canRedo: false,
       readOnly: true,
     },
+    documentMode: "viewing",
+    protectionSnapshot: {
+      hasDocumentProtection: false,
+      enforcementActive: false,
+      ranges: [],
+      enforcedRangeCount: 0,
+      preservedRangeCount: 0,
+    },
   };
 }
 

package/src/runtime/session-capabilities.ts

@@ -1,4 +1,4 @@
-import type { RuntimeRenderSnapshot } from "../api/public-types";
+import type { RuntimeRenderSnapshot, WorkflowScopeSnapshot } from "../api/public-types";
 import {
   createDetachedAnchor,
   createNodeAnchor,
@@ -21,6 +21,10 @@ export interface SessionCapabilities {
   /** Effective editor mode after accounting for runtime state. */
   mode: "editing" | "review" | "read-only-diagnostics";
 
+  // ── Document mode ──
+  /** Runtime document mode — editing authority, distinct from view/workspace mode. */
+  documentMode: "editing" | "suggesting" | "viewing";
+
   // ── Command capabilities ──
   canUndo: boolean;
   canRedo: boolean;
@@ -44,10 +48,22 @@ export interface SessionCapabilities {
   preserveOnlyCount: number;
   unsupportedFatalCount: number;
 
+  // ── Protection posture ──
+  /** Whether the source package declares document-level protection. */
+  hasDocumentProtection: boolean;
+  /** Count of permission ranges from the source package. */
+  protectedRangeCount: number;
+
   // ── Health ──
   /** Total count of health issues (preserve-only + unsupported-fatal + warnings). */
   healthIssueCount: number;
 
+  // ── Workflow ──
+  /** Whether a workflow overlay is currently applied. */
+  workflowOverlayPresent: boolean;
+  /** Whether the current selection is blocked by workflow scope enforcement. */
+  workflowBlocked: boolean;
+
   // ── Status ──
   isDirty: boolean;
   isReady: boolean;
@@ -63,11 +79,14 @@ export interface SessionCapabilities {
 export function deriveCapabilities(
   snapshot: RuntimeRenderSnapshot,
   reviewMode: "editing" | "review",
+  workflowScope?: WorkflowScopeSnapshot | null,
 ): SessionCapabilities {
   const hasFatalError = Boolean(snapshot.fatalError);
   const isReady = snapshot.isReady;
   const isReadOnly = snapshot.readOnly;
   const exportBlocked = snapshot.compatibility.blockExport;
+  const activeStory = snapshot.activeStory ?? { kind: "main" as const };
+  const documentMode = snapshot.documentMode ?? "editing";
 
   // Phase derivation
   const phase: SessionCapabilities["phase"] = !isReady
@@ -82,12 +101,13 @@ export function deriveCapabilities(
       ? "read-only-diagnostics"
       : reviewMode;
 
-  // Command capabilities
-  const canEdit = isReady && !isReadOnly && !hasFatalError;
+  // Command capabilities — document mode "viewing" disables editing
+  const canEdit = isReady && !isReadOnly && !hasFatalError && documentMode !== "viewing";
   const canUndo = snapshot.commandState.canUndo && canEdit;
   const canRedo = snapshot.commandState.canRedo && canEdit;
   const canAddComment =
     canEdit &&
+    activeStory.kind === "main" &&
     !snapshot.selection.isCollapsed &&
     Boolean(snapshot.surface) &&
     canCreateDocxCommentAnchor(snapshot.surface, toRuntimeAnchor(snapshot.selection.activeRange));
@@ -123,9 +143,17 @@ export function deriveCapabilities(
 
   const healthIssueCount = preserveOnlyCount + unsupportedFatalCount + snapshot.warnings.length;
 
+  const protection = snapshot.protectionSnapshot;
+  const hasDocumentProtection = protection?.hasDocumentProtection ?? false;
+  const protectedRangeCount = protection?.ranges?.length ?? 0;
+
+  const workflowOverlayPresent = workflowScope?.overlayPresent ?? false;
+  const workflowBlocked = (workflowScope?.blockedReasons?.length ?? 0) > 0;
+
   return {
     phase,
     mode,
+    documentMode,
     canUndo,
     canRedo,
     canEdit,
@@ -140,7 +168,11 @@ export function deriveCapabilities(
     exportBlocked,
     preserveOnlyCount,
     unsupportedFatalCount,
+    hasDocumentProtection,
+    protectedRangeCount,
     healthIssueCount,
+    workflowOverlayPresent,
+    workflowBlocked,
     isDirty: snapshot.isDirty,
     isReady,
     hasFatalError,