@beyondwork/docx-react-component 1.0.29 → 1.0.31

package/src/runtime/resolved-numbering-geometry.ts

@@ -0,0 +1,293 @@
+import type {
+  NumberingCatalog,
+  NumberingLevelDefinition,
+  NumberingLevelOverrideDefinition,
+  NumberingLevelParagraphGeometry,
+  ParagraphIndentation,
+  ParagraphNode,
+  ParagraphSpacing,
+  TabStop,
+} from "../model/canonical-document.ts";
+
+export const DEFAULT_NUMBERING_START_AT = 1;
+
+export interface ResolvedNumberingGeometry {
+  markerJustification?: NumberingLevelParagraphGeometry["justification"];
+  spacing?: ParagraphSpacing;
+  indentation?: ParagraphIndentation;
+  tabStops?: TabStop[];
+  markerLane?: {
+    start: number;
+    width: number;
+    textStart: number;
+  };
+  textColumn?: {
+    start: number;
+    right?: number;
+    firstLine?: number;
+    hanging?: number;
+  };
+}
+
+export interface ResolvedNumberingDefinitionSet {
+  instance: NumberingCatalog["instances"][string];
+  abstractDefinition: NumberingCatalog["abstractDefinitions"][string];
+  effectiveLevels: Map<number, NumberingLevelDefinition>;
+  effectiveLevel: NumberingLevelDefinition;
+  geometry: ResolvedNumberingGeometry;
+}
+
+export function resolveNumberingDefinitionSet(
+  catalog: NumberingCatalog,
+  numbering: ParagraphNode["numbering"] | undefined,
+  paragraph?: Pick<ParagraphNode, "spacing" | "indentation" | "tabStops">,
+): ResolvedNumberingDefinitionSet | null {
+  if (!numbering) {
+    return null;
+  }
+
+  const instance = catalog.instances[numbering.numberingInstanceId];
+  if (!instance) {
+    return null;
+  }
+
+  const abstractDefinition = catalog.abstractDefinitions[instance.abstractNumberingId];
+  if (!abstractDefinition) {
+    return null;
+  }
+
+  const effectiveLevels = buildEffectiveLevelDefinitions(abstractDefinition.levels, instance.overrides);
+  const effectiveLevel = effectiveLevels.get(numbering.level);
+  if (!effectiveLevel) {
+    return null;
+  }
+
+  return {
+    instance,
+    abstractDefinition,
+    effectiveLevels,
+    effectiveLevel,
+    geometry: resolveNumberingGeometry(effectiveLevel.paragraphGeometry, paragraph),
+  };
+}
+
+function buildEffectiveLevelDefinitions(
+  abstractLevels: readonly NumberingLevelDefinition[],
+  overrides: NumberingCatalog["instances"][string]["overrides"],
+): Map<number, NumberingLevelDefinition> {
+  const effectiveLevels = new Map<number, NumberingLevelDefinition>();
+
+  for (const level of abstractLevels) {
+    effectiveLevels.set(level.level, withDefaultStartAt(level));
+  }
+
+  for (const override of overrides) {
+    const base = effectiveLevels.get(override.level);
+    const merged = mergeLevelDefinition(base, override.levelDefinition, override.startAt, override.level);
+    if (merged) {
+      effectiveLevels.set(override.level, merged);
+    }
+  }
+
+  return effectiveLevels;
+}
+
+function mergeLevelDefinition(
+  base: NumberingLevelDefinition | undefined,
+  override: NumberingLevelOverrideDefinition | undefined,
+  startOverride: number | undefined,
+  fallbackLevel: number,
+): NumberingLevelDefinition | null {
+  if (!base && !override) {
+    return null;
+  }
+
+  const level = base?.level ?? override?.level ?? fallbackLevel;
+  const format = override?.format ?? base?.format ?? "decimal";
+  const text = override?.text ?? base?.text ?? `%${level + 1}.`;
+  const startAt = startOverride ?? override?.startAt ?? base?.startAt ?? DEFAULT_NUMBERING_START_AT;
+  const paragraphGeometry = mergeLevelParagraphGeometry(
+    base?.paragraphGeometry,
+    override?.paragraphGeometry,
+  );
+
+  return {
+    level,
+    format,
+    text,
+    startAt,
+    ...(override?.paragraphStyleId ?? base?.paragraphStyleId
+      ? { paragraphStyleId: override?.paragraphStyleId ?? base?.paragraphStyleId }
+      : {}),
+    ...((override?.isLegalNumbering ?? base?.isLegalNumbering) === true
+      ? { isLegalNumbering: true }
+      : {}),
+    ...(override?.suffix ?? base?.suffix ? { suffix: override?.suffix ?? base?.suffix } : {}),
+    ...(paragraphGeometry ? { paragraphGeometry } : {}),
+  };
+}
+
+function withDefaultStartAt(level: NumberingLevelDefinition): NumberingLevelDefinition {
+  return {
+    ...level,
+    startAt: level.startAt ?? DEFAULT_NUMBERING_START_AT,
+    ...(level.paragraphGeometry
+      ? { paragraphGeometry: cloneLevelParagraphGeometry(level.paragraphGeometry) }
+      : {}),
+  };
+}
+
+function cloneLevelParagraphGeometry(
+  geometry: NumberingLevelParagraphGeometry,
+): NumberingLevelParagraphGeometry {
+  return {
+    ...(geometry.justification ? { justification: geometry.justification } : {}),
+    ...(geometry.spacing ? { spacing: { ...geometry.spacing } } : {}),
+    ...(geometry.indentation ? { indentation: { ...geometry.indentation } } : {}),
+    ...(geometry.tabStops && geometry.tabStops.length > 0
+      ? { tabStops: cloneTabStops(geometry.tabStops) }
+      : {}),
+  };
+}
+
+function mergeLevelParagraphGeometry(
+  base: NumberingLevelParagraphGeometry | undefined,
+  override: NumberingLevelParagraphGeometry | undefined,
+): NumberingLevelParagraphGeometry | undefined {
+  if (!base && !override) {
+    return undefined;
+  }
+
+  const spacing = mergeParagraphSpacing(base?.spacing, override?.spacing);
+  const indentation = mergeParagraphIndentation(base?.indentation, override?.indentation);
+  const tabStops = override?.tabStops?.length
+    ? cloneTabStops(override.tabStops)
+    : base?.tabStops?.length
+      ? cloneTabStops(base.tabStops)
+      : undefined;
+
+  return {
+    ...(override?.justification ?? base?.justification
+      ? { justification: override?.justification ?? base?.justification }
+      : {}),
+    ...(spacing ? { spacing } : {}),
+    ...(indentation ? { indentation } : {}),
+    ...(tabStops && tabStops.length > 0 ? { tabStops } : {}),
+  };
+}
+
+function resolveNumberingGeometry(
+  levelGeometry: NumberingLevelParagraphGeometry | undefined,
+  paragraph: Pick<ParagraphNode, "spacing" | "indentation" | "tabStops"> | undefined,
+): ResolvedNumberingGeometry {
+  const spacing = mergeParagraphSpacing(levelGeometry?.spacing, paragraph?.spacing);
+  const indentation = mergeParagraphIndentation(levelGeometry?.indentation, paragraph?.indentation);
+  const tabStops = paragraph?.tabStops?.length
+    ? cloneTabStops(paragraph.tabStops)
+    : levelGeometry?.tabStops?.length
+      ? cloneTabStops(levelGeometry.tabStops)
+      : undefined;
+  const markerLane = deriveMarkerLane(indentation);
+  const textColumn = deriveTextColumn(indentation);
+
+  return {
+    ...(levelGeometry?.justification ? { markerJustification: levelGeometry.justification } : {}),
+    ...(spacing ? { spacing } : {}),
+    ...(indentation ? { indentation } : {}),
+    ...(tabStops && tabStops.length > 0 ? { tabStops } : {}),
+    ...(markerLane ? { markerLane } : {}),
+    ...(textColumn ? { textColumn } : {}),
+  };
+}
+
+function mergeParagraphSpacing(
+  base: ParagraphSpacing | undefined,
+  override: ParagraphSpacing | undefined,
+): ParagraphSpacing | undefined {
+  if (!base && !override) {
+    return undefined;
+  }
+
+  const spacing: ParagraphSpacing = {
+    ...(base ?? {}),
+    ...(override ?? {}),
+  };
+
+  return Object.keys(spacing).length > 0 ? spacing : undefined;
+}
+
+function mergeParagraphIndentation(
+  base: ParagraphIndentation | undefined,
+  override: ParagraphIndentation | undefined,
+): ParagraphIndentation | undefined {
+  if (!base && !override) {
+    return undefined;
+  }
+
+  const indentation: ParagraphIndentation = {
+    ...(base ?? {}),
+    ...(override ?? {}),
+  };
+
+  return Object.keys(indentation).length > 0 ? indentation : undefined;
+}
+
+function cloneTabStops(tabStops: readonly TabStop[]): TabStop[] {
+  return tabStops.map((tabStop) => ({ ...tabStop }));
+}
+
+function deriveMarkerLane(
+  indentation: ParagraphIndentation | undefined,
+): ResolvedNumberingGeometry["markerLane"] | undefined {
+  if (!indentation) {
+    return undefined;
+  }
+
+  const width = resolveHangingWidth(indentation);
+  if (width === undefined || width <= 0) {
+    return undefined;
+  }
+
+  const textStart = indentation.left ?? 0;
+  return {
+    start: textStart - width,
+    width,
+    textStart,
+  };
+}
+
+function deriveTextColumn(
+  indentation: ParagraphIndentation | undefined,
+): ResolvedNumberingGeometry["textColumn"] | undefined {
+  if (!indentation) {
+    return undefined;
+  }
+
+  const hanging = resolveHangingWidth(indentation);
+  const hasGeometry =
+    indentation.left !== undefined ||
+    indentation.right !== undefined ||
+    indentation.firstLine !== undefined ||
+    hanging !== undefined;
+
+  if (!hasGeometry) {
+    return undefined;
+  }
+
+  return {
+    start: indentation.left ?? 0,
+    ...(indentation.right !== undefined ? { right: indentation.right } : {}),
+    ...(indentation.firstLine !== undefined ? { firstLine: indentation.firstLine } : {}),
+    ...(hanging !== undefined ? { hanging } : {}),
+  };
+}
+
+function resolveHangingWidth(indentation: ParagraphIndentation): number | undefined {
+  if (indentation.hanging !== undefined) {
+    return indentation.hanging;
+  }
+  if (indentation.firstLine !== undefined && indentation.firstLine < 0) {
+    return Math.abs(indentation.firstLine);
+  }
+  return undefined;
+}

package/src/runtime/review-runtime.ts

@@ -0,0 +1,44 @@
+import type {
+  CommentThreadRecord,
+  EditorState,
+  EditorWarning,
+} from "../core/state/editor-state.ts";
+import type { TransactionMapping } from "../core/selection/mapping.ts";
+import { remapCommentThreads } from "../review/store/comment-remapping.ts";
+
+export interface ApplyReviewRuntimeMappingOptions {
+  state: Pick<EditorState, "document" | "warnings" | "runtime">;
+  mapping: TransactionMapping;
+  nextContent: unknown;
+}
+
+export interface ReviewRuntimeMappingResult {
+  comments: Record<string, CommentThreadRecord>;
+  warnings: EditorWarning[];
+  activeCommentId?: string;
+  detachedCommentIds: string[];
+}
+
+export function applyReviewRuntimeMapping(
+  options: ApplyReviewRuntimeMappingOptions,
+): ReviewRuntimeMappingResult {
+  const remapped = remapCommentThreads({
+    comments: options.state.document.review.comments,
+    mapping: options.mapping,
+    nextContent: options.nextContent,
+    existingWarnings: options.state.warnings,
+  });
+
+  const activeCommentId =
+    options.state.runtime.activeCommentId &&
+    remapped.comments[options.state.runtime.activeCommentId]
+      ? options.state.runtime.activeCommentId
+      : undefined;
+
+  return {
+    comments: remapped.comments,
+    warnings: remapped.warnings,
+    activeCommentId,
+    detachedCommentIds: remapped.detachedCommentIds,
+  };
+}

package/src/runtime/revision-runtime.ts

@@ -0,0 +1,107 @@
+import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
+import {
+  getReviewCommandIntent,
+  isSingleRevisionReviewCommand,
+  type ReviewCommand,
+} from "../core/commands/review-commands.ts";
+import type { TransactionMapping } from "../core/selection/mapping.ts";
+import {
+  applyRevisionAction,
+  type RevisionActionOutcome,
+} from "../review/store/revision-actions.ts";
+import { type RevisionStore } from "../review/store/revision-store.ts";
+
+export interface RevisionRuntimeState {
+  document: CanonicalDocumentEnvelope;
+  store: RevisionStore;
+}
+
+export interface ApplyRevisionRuntimeCommandOptions {
+  state: RevisionRuntimeState;
+  command: ReviewCommand;
+  timestamp: string;
+}
+
+export interface RevisionRuntimeCommandEffects {
+  appliedRevisionIds: string[];
+  skippedRevisions: RevisionActionOutcome[];
+  detachedRevisionIds: string[];
+}
+
+export interface RevisionRuntimeCommandResult extends RevisionRuntimeState {
+  outcomes: RevisionActionOutcome[];
+  mappings: Array<{ revisionId: string; mapping: TransactionMapping; steps: number }>;
+  effects: RevisionRuntimeCommandEffects;
+}
+
+export function applyRevisionRuntimeCommand(
+  options: ApplyRevisionRuntimeCommandOptions,
+): RevisionRuntimeCommandResult {
+  const revisionIds = isSingleRevisionReviewCommand(options.command)
+    ? [options.command.revisionId]
+    : listBatchRevisionIds(options.state.store);
+
+  const outcomes: RevisionActionOutcome[] = [];
+  const mappings: Array<{ revisionId: string; mapping: TransactionMapping; steps: number }> = [];
+  const appliedRevisionIds: string[] = [];
+  const detachedRevisionIds = new Set<string>();
+
+  let state = options.state;
+
+  for (const revisionId of revisionIds) {
+    const result = applyRevisionAction({
+      document: state.document,
+      store: state.store,
+      revisionId,
+      intent: getReviewCommandIntent(options.command),
+      timestamp: options.timestamp,
+    });
+
+    state = {
+      document: result.document,
+      store: result.store,
+    };
+    outcomes.push(result.outcome);
+    mappings.push({
+      revisionId,
+      mapping: result.mapping,
+      steps: result.mapping.steps.length,
+    });
+
+    if (result.outcome.kind === "applied") {
+      appliedRevisionIds.push(revisionId);
+    }
+
+    for (const detachedRevisionId of result.detachedRevisionIds) {
+      detachedRevisionIds.add(detachedRevisionId);
+    }
+  }
+
+  return {
+    ...state,
+    outcomes,
+    mappings,
+    effects: {
+      appliedRevisionIds,
+      skippedRevisions: outcomes.filter(
+        (outcome): outcome is Extract<RevisionActionOutcome, { kind: "skipped" }> =>
+          outcome.kind === "skipped",
+      ),
+      detachedRevisionIds: [...detachedRevisionIds],
+    },
+  };
+}
+
+function listBatchRevisionIds(store: RevisionStore): string[] {
+  return Object.values(store.revisions)
+    .filter((revision) => revision.status === "active")
+    .sort((left, right) => {
+      const createdAtDelta = left.createdAt.localeCompare(right.createdAt);
+      if (createdAtDelta !== 0) {
+        return createdAtDelta;
+      }
+
+      return left.revisionId.localeCompare(right.revisionId);
+    })
+    .map((revision) => revision.revisionId);
+}

package/src/runtime/session-capabilities.ts

@@ -0,0 +1,192 @@
+import type { RuntimeRenderSnapshot, WorkflowScopeSnapshot } from "../api/public-types";
+import {
+  createDetachedAnchor,
+  createNodeAnchor,
+  createRangeAnchor,
+} from "../core/selection/mapping.ts";
+import { canCreateDocxCommentAnchor } from "../core/selection/review-anchors";
+
+/**
+ * Session capabilities derived from the runtime snapshot.
+ *
+ * All fields are computed from `RuntimeRenderSnapshot` — no local component
+ * state. The UI reads these to decide what controls to enable/disable, what
+ * chrome to show, and what mode the editor is in.
+ */
+export interface SessionCapabilities {
+  // ── Session phase ──
+  /** Current lifecycle phase of the editor session. */
+  phase: "loading" | "ready" | "diagnostics" | "error";
+
+  /** 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;
+  canEdit: boolean;
+  canAddComment: boolean;
+  canExport: boolean;
+  canAcceptChange: boolean;
+  canRejectChange: boolean;
+  canAcceptAll: boolean;
+  canRejectAll: boolean;
+
+  // ── Review visibility ──
+  /** Whether the review rail should be visible by default. */
+  reviewRailVisible: boolean;
+
+  /** Whether tracked changes exist in the document (display toggle is meaningful). */
+  trackChangesSupported: boolean;
+
+  // ── Trust posture ──
+  exportBlocked: boolean;
+  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;
+  hasFatalError: boolean;
+}
+
+/**
+ * Derive UI capabilities from the runtime snapshot and requested review mode.
+ *
+ * This is a pure function with no side effects. Call it on every render to
+ * get the current capability state.
+ */
+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
+    ? "loading"
+    : hasFatalError
+      ? "diagnostics"
+      : "ready";
+
+  // Mode derivation: if diagnostics or read-only, override the requested mode
+  const mode: SessionCapabilities["mode"] =
+    phase === "diagnostics"
+      ? "read-only-diagnostics"
+      : reviewMode;
+
+  // 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));
+  const canExport = isReady && !exportBlocked && !hasFatalError;
+
+  // Revision capabilities
+  const actionableRevisions = snapshot.trackedChanges.revisions.filter(
+    (r) => r.status === "active" && r.actionability === "actionable",
+  );
+  const canAcceptChange = canEdit && actionableRevisions.some((r) => r.canAccept);
+  const canRejectChange = canEdit && actionableRevisions.some((r) => r.canReject);
+  const canAcceptAll = canEdit && actionableRevisions.length > 0;
+  const canRejectAll = canEdit && actionableRevisions.length > 0;
+
+  // Trust posture (computed before review visibility since it depends on these)
+  const preserveOnlyCount = snapshot.compatibility.featureEntries.filter(
+    (e) => e.featureClass === "preserve-only",
+  ).length;
+  const unsupportedFatalCount = snapshot.compatibility.featureEntries.filter(
+    (e) => e.featureClass === "unsupported-fatal",
+  ).length;
+  const workflowOverlayPresent = workflowScope?.overlayPresent ?? false;
+  const workflowBlocked = (workflowScope?.blockedReasons?.length ?? 0) > 0;
+
+  // Review visibility
+  const trackChangesSupported = snapshot.trackedChanges.totalCount > 0;
+  // Rail visible in review/diagnostics mode always.
+  // In editing mode, rail stays visible when there are trust/health concerns
+  // that the user must be able to reach (per DESIGN.md: health/trust info
+  // stays reachable in both modes).
+  const hasTrustConcerns = exportBlocked || preserveOnlyCount > 0 || unsupportedFatalCount > 0
+    || snapshot.warnings.length > 0 || hasFatalError;
+  const reviewRailVisible = isReady && (workflowOverlayPresent
+    ? false
+    : mode === "review" || mode === "read-only-diagnostics"
+      || (mode === "editing" && hasTrustConcerns));
+
+  const healthIssueCount = preserveOnlyCount + unsupportedFatalCount + snapshot.warnings.length;
+
+  const protection = snapshot.protectionSnapshot;
+  const hasDocumentProtection = protection?.hasDocumentProtection ?? false;
+  const protectedRangeCount = protection?.ranges?.length ?? 0;
+
+  return {
+    phase,
+    mode,
+    documentMode,
+    canUndo,
+    canRedo,
+    canEdit,
+    canAddComment,
+    canExport,
+    canAcceptChange,
+    canRejectChange,
+    canAcceptAll,
+    canRejectAll,
+    reviewRailVisible,
+    trackChangesSupported,
+    exportBlocked,
+    preserveOnlyCount,
+    unsupportedFatalCount,
+    hasDocumentProtection,
+    protectedRangeCount,
+    healthIssueCount,
+    workflowOverlayPresent,
+    workflowBlocked,
+    isDirty: snapshot.isDirty,
+    isReady,
+    hasFatalError,
+  };
+}
+
+function toRuntimeAnchor(anchor: RuntimeRenderSnapshot["selection"]["activeRange"]) {
+  switch (anchor.kind) {
+    case "range":
+      return createRangeAnchor(anchor.from, anchor.to, anchor.assoc);
+    case "node":
+      return createNodeAnchor(anchor.at, anchor.assoc);
+    case "detached":
+      return createDetachedAnchor(anchor.lastKnownRange, anchor.reason);
+  }
+}