@beyondwork/docx-react-component 1.0.29 → 1.0.31

package/src/runtime/view-state.ts

@@ -0,0 +1,493 @@
+/**
+ * Runtime-owned view state — non-canonical interaction model.
+ *
+ * This module owns the editor's interaction and measurement state that is
+ * separate from the canonical document model. View state is never serialized
+ * into persisted snapshots or exported DOCX; it exists only while the editor
+ * session is live.
+ *
+ * Design boundaries:
+ * - Canonical document state lives in EditorState / CanonicalDocumentEnvelope.
+ * - View state is runtime-owned, non-canonical, non-exported.
+ * - Builds on Wave 35's activeStory and PageLayoutSnapshot model.
+ * - Runtime viewMode models editor posture ("editing" | "review" | "view").
+ * - Workspace mode and zoom are runtime-owned so hosts and the mounted shell
+ *   share one view-state contract.
+ */
+
+import type {
+  ActiveListContext,
+  ActiveNoteContext,
+  CaretAffinity,
+  DocumentMode,
+  EditorStoryTarget,
+  EditorSurfaceSnapshot,
+  EditorViewStateSnapshot,
+  LayoutMeasurement,
+  PageLayoutSnapshot,
+  PageRegionHitTest,
+  SelectionSnapshot,
+  SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
+  ViewMode,
+  WorkspaceMode,
+  ZoomLevel,
+} from "../api/public-types";
+import type { NumberingCatalog } from "../model/canonical-document.ts";
+
+export interface ViewState {
+  viewMode: ViewMode;
+  documentMode: DocumentMode;
+  workspaceMode: WorkspaceMode;
+  zoomLevel: ZoomLevel;
+  isFocused: boolean;
+  caretAffinity: CaretAffinity;
+  activePageRegion: PageRegionHitTest | null;
+  activeObjectFrame: LayoutMeasurement["objectFrame"] | null;
+}
+
+const MIN_ZOOM_PERCENT = 50;
+const MAX_ZOOM_PERCENT = 200;
+
+const DEFAULT_VIEW_STATE: ViewState = {
+  viewMode: "editing",
+  documentMode: "editing",
+  workspaceMode: "canvas",
+  zoomLevel: 100,
+  isFocused: false,
+  caretAffinity: "none",
+  activePageRegion: null,
+  activeObjectFrame: null,
+};
+
+export function createViewState(initial?: Partial<ViewState>): ViewState {
+  return { ...DEFAULT_VIEW_STATE, ...initial };
+}
+
+export function setViewMode(state: ViewState, mode: ViewMode): ViewState {
+  if (state.viewMode === mode) return state;
+  return { ...state, viewMode: mode };
+}
+
+export function setDocumentMode(state: ViewState, mode: DocumentMode): ViewState {
+  if (state.documentMode === mode) return state;
+  return { ...state, documentMode: mode };
+}
+
+export function setWorkspaceMode(
+  state: ViewState,
+  workspaceMode: WorkspaceMode,
+): ViewState {
+  if (state.workspaceMode === workspaceMode) {
+    return state;
+  }
+  return { ...state, workspaceMode };
+}
+
+export function setZoomLevel(state: ViewState, zoomLevel: ZoomLevel): ViewState {
+  const normalizedZoom = normalizeZoomLevel(zoomLevel, state.zoomLevel);
+  if (state.zoomLevel === normalizedZoom) {
+    return state;
+  }
+  return { ...state, zoomLevel: normalizedZoom };
+}
+
+export function setFocused(state: ViewState, focused: boolean): ViewState {
+  if (state.isFocused === focused) return state;
+  return { ...state, isFocused: focused };
+}
+
+export function setCaretAffinity(state: ViewState, affinity: CaretAffinity): ViewState {
+  if (state.caretAffinity === affinity) return state;
+  return { ...state, caretAffinity: affinity };
+}
+
+export function setActivePageRegion(state: ViewState, region: PageRegionHitTest | null): ViewState {
+  return { ...state, activePageRegion: region };
+}
+
+export function setActiveObjectFrame(
+  state: ViewState,
+  frame: LayoutMeasurement["objectFrame"] | null,
+): ViewState {
+  return { ...state, activeObjectFrame: frame };
+}
+
+/**
+ * Derive list context from the surface block at the current selection head.
+ */
+export function deriveActiveListContext(
+  surface: EditorSurfaceSnapshot | undefined,
+  selectionHead: number,
+  numberingCatalog?: NumberingCatalog,
+): ActiveListContext | null {
+  if (!surface) return null;
+  const block = findBlockAtPosition(surface.blocks, selectionHead);
+  if (!block || block.kind !== "paragraph" || !block.numbering) return null;
+
+  const isOrdered = resolveListOrdering(block.numbering, numberingCatalog);
+  return {
+    numberingInstanceId: block.numbering.numberingInstanceId,
+    level: block.numbering.level,
+    isOrdered,
+    ...(block.numberingPrefix ? { markerText: block.numberingPrefix } : {}),
+  };
+}
+
+/**
+ * Derive note context when the active story targets a footnote or endnote.
+ */
+export function deriveActiveNoteContext(
+  activeStory: EditorStoryTarget,
+  mainSurface: EditorSurfaceSnapshot | undefined,
+): ActiveNoteContext | null {
+  if (activeStory.kind !== "footnote" && activeStory.kind !== "endnote") {
+    return null;
+  }
+
+  const referencePosition = findNoteReferencePosition(mainSurface, activeStory);
+  return {
+    noteKind: activeStory.kind,
+    noteId: activeStory.noteId,
+    referencePosition,
+  };
+}
+
+/**
+ * Derive layout measurement from the surface at the current selection.
+ */
+export function deriveLayoutMeasurement(
+  surface: EditorSurfaceSnapshot | undefined,
+  selectionOrPosition: SelectionSnapshot | number,
+  viewState: ViewState,
+): LayoutMeasurement {
+  const selectionHead =
+    typeof selectionOrPosition === "number"
+      ? selectionOrPosition
+      : selectionOrPosition.activeRange.kind === "node"
+        ? selectionOrPosition.activeRange.at
+        : selectionOrPosition.head;
+  const block = surface ? findBlockAtPosition(surface.blocks, selectionHead) : null;
+  const tabStops = resolveMeasurementTabStops(block);
+  const listMarkerLane = deriveListMarkerLane(block);
+
+  return {
+    pageRegions: viewState.activePageRegion ? [viewState.activePageRegion] : [],
+    caretAffinity: viewState.caretAffinity,
+    tabStops,
+    listMarkerLane: listMarkerLane ?? undefined,
+    objectFrame: viewState.activeObjectFrame ?? undefined,
+  };
+}
+
+/**
+ * Build the full EditorViewStateSnapshot from runtime + surface state.
+ */
+export function createEditorViewStateSnapshot(
+  viewState: ViewState,
+  activeStory: EditorStoryTarget,
+  selection: SelectionSnapshot,
+  surface: EditorSurfaceSnapshot | undefined,
+  mainSurface: EditorSurfaceSnapshot | undefined,
+  pageLayout: PageLayoutSnapshot | null | undefined,
+  numberingCatalog?: NumberingCatalog,
+): EditorViewStateSnapshot {
+  const selectionPosition =
+    selection.activeRange.kind === "node" ? selection.activeRange.at : selection.head;
+  const derivedViewState = deriveInteractionViewState(
+    viewState,
+    activeStory,
+    selection,
+    surface,
+    pageLayout,
+  );
+  const activeListContext = deriveActiveListContext(surface, selectionPosition, numberingCatalog);
+  const activeNoteContext = deriveActiveNoteContext(activeStory, mainSurface);
+  const measurement = deriveLayoutMeasurement(surface, selection, derivedViewState);
+
+  return {
+    viewMode: derivedViewState.viewMode,
+    documentMode: derivedViewState.documentMode,
+    workspaceMode: derivedViewState.workspaceMode,
+    zoomLevel: derivedViewState.zoomLevel,
+    activeStory,
+    selection,
+    caretAffinity: derivedViewState.caretAffinity,
+    activeListContext,
+    activeNoteContext,
+    activePageRegion: derivedViewState.activePageRegion,
+    activeObjectFrame: derivedViewState.activeObjectFrame,
+    measurement,
+    isFocused: derivedViewState.isFocused,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function findBlockAtPosition(
+  blocks: readonly SurfaceBlockSnapshot[],
+  position: number,
+): SurfaceBlockSnapshot | null {
+  for (const block of blocks) {
+    if (position >= block.from && position <= block.to) {
+      if (block.kind === "sdt_block") {
+        const inner = findBlockAtPosition(block.children, position);
+        if (inner) return inner;
+      }
+      if (block.kind === "table") {
+        for (const row of block.rows) {
+          for (const cell of row.cells) {
+            const inner = findBlockAtPosition(cell.content, position);
+            if (inner) return inner;
+          }
+        }
+      }
+      return block;
+    }
+  }
+  return null;
+}
+
+function resolveListOrdering(
+  numbering: NonNullable<Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>["numbering"]>,
+  numberingCatalog?: NumberingCatalog,
+): boolean {
+  if (!numberingCatalog) {
+    return true;
+  }
+
+  const instance = numberingCatalog.instances[numbering.numberingInstanceId];
+  const definition = instance
+    ? numberingCatalog.abstractDefinitions[instance.abstractNumberingId]
+    : undefined;
+  const levelDefinition = definition?.levels.find((level) => level.level === numbering.level);
+
+  if (!levelDefinition) {
+    return true;
+  }
+
+  return levelDefinition.format !== "bullet";
+}
+
+function deriveInteractionViewState(
+  viewState: ViewState,
+  activeStory: EditorStoryTarget,
+  selection: SelectionSnapshot,
+  surface: EditorSurfaceSnapshot | undefined,
+  pageLayout: PageLayoutSnapshot | null | undefined,
+): ViewState {
+  const activePageRegion = deriveActivePageRegion(activeStory, pageLayout) ?? viewState.activePageRegion;
+  const activeObjectFrame = deriveActiveObjectFrame(surface, selection);
+  const caretAffinity = deriveCaretAffinity(surface, selection);
+
+  return {
+    ...viewState,
+    caretAffinity,
+    activePageRegion,
+    activeObjectFrame,
+  };
+}
+
+function deriveActivePageRegion(
+  activeStory: EditorStoryTarget,
+  pageLayout: PageLayoutSnapshot | null | undefined,
+): PageRegionHitTest | null {
+  if (!pageLayout) {
+    return null;
+  }
+  const sectionIndex = pageLayout?.sectionIndex ?? 0;
+  switch (activeStory.kind) {
+    case "header":
+      return { region: "header", sectionIndex, columnIndex: 0 };
+    case "footer":
+      return { region: "footer", sectionIndex, columnIndex: 0 };
+    default:
+      return { region: "body", sectionIndex, columnIndex: 0 };
+  }
+}
+
+function deriveActiveObjectFrame(
+  surface: EditorSurfaceSnapshot | undefined,
+  selection: SelectionSnapshot,
+): LayoutMeasurement["objectFrame"] | null {
+  if (!surface) {
+    return null;
+  }
+
+  const position =
+    selection.activeRange.kind === "node" ? selection.activeRange.at : selection.head;
+  const block = findBlockAtPosition(surface.blocks, position);
+  if (!block || block.kind !== "paragraph") {
+    return null;
+  }
+
+  const segment = findObjectSegmentAtPosition(block.segments, position);
+  if (!segment) {
+    return null;
+  }
+
+  if (segment.kind === "image") {
+    return {
+      kind: "image",
+      anchorPos: segment.from,
+      display: segment.display === "floating" ? "floating" : "inline",
+    };
+  }
+
+  const objectKind = inferOpaqueObjectKind(segment);
+  if (!objectKind) {
+    return null;
+  }
+
+  return {
+    kind: objectKind,
+    anchorPos: segment.from,
+    display: "inline",
+  };
+}
+
+function deriveCaretAffinity(
+  surface: EditorSurfaceSnapshot | undefined,
+  selection: SelectionSnapshot,
+): CaretAffinity {
+  if (selection.activeRange.kind === "node") {
+    return selection.activeRange.assoc < 0 ? "backward" : "forward";
+  }
+  if (!selection.isCollapsed || !surface) {
+    return "none";
+  }
+  const block = findBlockAtPosition(surface.blocks, selection.head);
+  if (!block || block.kind !== "paragraph") {
+    return "none";
+  }
+  for (const segment of block.segments) {
+    if (!isObjectLikeSegment(segment)) {
+      continue;
+    }
+    if (selection.head === segment.from) {
+      return "forward";
+    }
+    if (selection.head === segment.to) {
+      return "backward";
+    }
+  }
+  return "none";
+}
+
+export function findNoteReferencePosition(
+  mainSurface: EditorSurfaceSnapshot | undefined,
+  target: EditorStoryTarget & { kind: "footnote" | "endnote" },
+): number {
+  if (!mainSurface) return 0;
+  for (const block of mainSurface.blocks) {
+    if (block.kind === "paragraph") {
+      for (const segment of block.segments) {
+        if (
+          segment.kind === "note_ref" &&
+          segment.noteKind === target.kind &&
+          segment.noteId === target.noteId
+        ) {
+          return segment.from;
+        }
+        // Fallback: opaque_inline references from older surface projections
+        if (
+          segment.kind === "opaque_inline" &&
+          segment.label.toLowerCase().includes(target.kind) &&
+          segment.detail.includes(target.noteId)
+        ) {
+          return segment.from;
+        }
+      }
+    }
+  }
+  return 0;
+}
+
+function normalizeZoomLevel(
+  zoomLevel: ZoomLevel,
+  currentZoom: ZoomLevel,
+): ZoomLevel {
+  if (zoomLevel === "pageWidth" || zoomLevel === "onePage") {
+    return zoomLevel;
+  }
+  if (!Number.isFinite(zoomLevel) || zoomLevel <= 0) {
+    return currentZoom;
+  }
+  return Math.max(
+    MIN_ZOOM_PERCENT,
+    Math.min(MAX_ZOOM_PERCENT, Math.round(zoomLevel)),
+  );
+}
+
+function findObjectSegmentAtPosition(
+  segments: readonly SurfaceInlineSegment[],
+  position: number,
+): Extract<SurfaceInlineSegment, { kind: "image" | "opaque_inline" }> | null {
+  for (const segment of segments) {
+    if (!isObjectLikeSegment(segment)) {
+      continue;
+    }
+    if (position >= segment.from && position <= segment.to) {
+      return segment;
+    }
+  }
+  return null;
+}
+
+function isObjectLikeSegment(
+  segment: SurfaceInlineSegment,
+): segment is Extract<SurfaceInlineSegment, { kind: "image" | "opaque_inline" }> {
+  if (segment.kind === "image") {
+    return true;
+  }
+  if (segment.kind !== "opaque_inline") {
+    return false;
+  }
+  return inferOpaqueObjectKind(segment) !== null;
+}
+
+function inferOpaqueObjectKind(
+  segment: Extract<SurfaceInlineSegment, { kind: "opaque_inline" }>,
+): "textbox" | "shape" | null {
+  if (segment.label === "Text box") {
+    return "textbox";
+  }
+  if (segment.label === "Drawing shape") {
+    return "shape";
+  }
+  if (segment.label === "Legacy VML drawing") {
+    return segment.detail.includes("#_x0000_t202")
+      ? "textbox"
+      : "shape";
+  }
+  return null;
+}
+
+function deriveListMarkerLane(
+  block: SurfaceBlockSnapshot | null,
+): { indent: number; markerWidth: number } | null {
+  if (!block || block.kind !== "paragraph" || !block.numbering) return null;
+  const resolvedMarkerLane = block.resolvedNumbering?.geometry.markerLane;
+  if (resolvedMarkerLane) {
+    return {
+      indent: resolvedMarkerLane.textStart,
+      markerWidth: resolvedMarkerLane.width,
+    };
+  }
+  const indent = block.indentation?.hanging ?? block.indentation?.left ?? 360;
+  return {
+    indent,
+    markerWidth: Math.min(indent, 360),
+  };
+}
+
+function resolveMeasurementTabStops(
+  block: SurfaceBlockSnapshot | null,
+): Array<{ pos: number; val?: string; leader?: string }> {
+  if (!block || block.kind !== "paragraph") {
+    return [];
+  }
+  return block.resolvedNumbering?.geometry.tabStops ?? block.tabStops ?? [];
+}