@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/runtime/formatting/resolve-effective.ts

@@ -0,0 +1,407 @@
+/**
+ * Layer 03 — `resolveEffectiveFormatting` façade over `FormattingContext`.
+ *
+ * Architecture contract F1: there is exactly one Layer-03 production
+ * boundary. That boundary is `FormattingContext` (see
+ * `./formatting-context.ts`) — production consumers (`surface-projection`,
+ * layout public-facet, etc.) construct one context per projection pass
+ * and call its methods directly for amortized per-document resolver
+ * reuse.
+ *
+ * `resolveEffectiveFormatting(doc, nodeRef, opts?)` is the external-API
+ * façade over that boundary. It constructs a per-call context from the
+ * inputs and delegates every dispatch branch to the context. Tests +
+ * agents + any caller that does not have a long-lived projection pass
+ * use this entry; production hot paths go through the context directly.
+ *
+ * The façade is PURE with respect to `doc` — it never mutates the
+ * document, never reads DOM geometry, and never schedules side effects
+ * outside the optional `opts.emitFormattingTelemetry` callback.
+ */
+
+import type {
+  CanonicalDocument,
+  CanonicalFontTable,
+  FieldNode,
+  FieldRegistryEntry,
+  ParagraphNode,
+  RevisionRecord,
+} from "../../model/canonical-document.ts";
+import type { FieldPageGraph, FieldResolver } from "./field/resolver.ts";
+import type { ThemeColorResolver } from "./theme-color.ts";
+import type { NumberingPrefixResolver } from "./numbering/prefix.ts";
+import {
+  createFormattingContext,
+  type FormattingContext,
+} from "./formatting-context.ts";
+import {
+  findParagraphByBlockId,
+  findTableByBlockId,
+  findInlineBySegmentIndex,
+  parseSegmentIndex,
+  resolveDirectRunFormattingAtSegment,
+} from "./document-lookup.ts";
+import type {
+  EffectiveFieldDisplay,
+  EffectiveFormatting,
+} from "./formatting-types.ts";
+
+/**
+ * Telemetry event shape emitted on the `formatting` channel when
+ * `opts.emitFormattingTelemetry` is provided.
+ */
+export type FormattingTelemetryEvent =
+  | {
+      readonly type: "formatting.resolution_sampled";
+      readonly payload: {
+        readonly kind: NodeRef["kind"];
+        readonly blockId: string;
+        readonly hasDirect: boolean;
+        readonly hasTheme: boolean;
+        readonly hasNumbering: boolean;
+      };
+    }
+  | {
+      readonly type: "formatting.cache.invalidated";
+      readonly payload: {
+        readonly reason:
+          | "theme-resolver-built"
+          | "numbering-resolver-built"
+          | "field-resolver-built";
+      };
+    }
+  | {
+      /**
+       * Emitted when numbering resolution resolves a paragraph to a level
+       * whose `format` is not in `SUPPORTED_NUMBERING_FORMATS`. Exposes
+       * the L03 Task-A3 format-coverage gap observably without changing
+       * rendered output (the fallback path still produces `String(value)`
+       * so users see digits). Deduplication is expected to happen at the
+       * emit site — a surface-projection pass emits at most once per
+       * `(numberingInstanceId, level, format)` tuple.
+       */
+      readonly type: "formatting.numbering_format_unsupported";
+      readonly payload: {
+        readonly format: string;
+        readonly numberingInstanceId: string;
+        readonly level: number;
+      };
+    };
+
+export type NodeRef =
+  | { kind: "paragraph"; blockId: string }
+  | { kind: "run"; blockId: string; runId: string }
+  | { kind: "table"; blockId: string }
+  | {
+      kind: "table-cell";
+      blockId: string;
+      rowIndex: number;
+      cellIndex: number;
+    }
+  | {
+      kind: "field";
+      blockId: string;
+      runId: string;
+      pageGraph?: FieldPageGraph;
+    }
+  | { kind: "drawing-frame"; blockId: string; inlineId: string };
+
+export interface ResolveEffectiveFormattingOptions {
+  /** Active markup mode. When set together with `revision`, the
+   *  returned run is decorated with `revisionDisplay` flags. */
+  readonly revisionMarkupMode?: "clean" | "simple" | "all";
+  /** Pre-built theme resolver. Passing one through avoids building
+   *  a fresh `ThemeColorResolver` inside the façade; pass `undefined`
+   *  to let the façade build from `doc.subParts.canonicalTheme`. */
+  readonly themeResolver?: ThemeColorResolver;
+  /** Pre-built numbering prefix resolver. When absent, the façade
+   *  constructs one from `doc.numbering` per call. */
+  readonly numberingPrefixResolver?: NumberingPrefixResolver;
+  /** Font table reference (for ECMA-376 §17.3.2.26 substitution). */
+  readonly fontTable?: CanonicalFontTable;
+  /** Pre-built field resolver. Required for PAGE / NUMPAGES / REF /
+   *  STYLEREF resolution. */
+  readonly fieldResolver?: FieldResolver;
+  /** Attached revision for `run` / `field` dispatch. */
+  readonly revision?: RevisionRecord;
+  /** Author-id → color palette for revision-display posture. */
+  readonly authorColorPalette?: ReadonlyMap<string, string>;
+  /** Probability-gated telemetry emit callback. */
+  readonly emitFormattingTelemetry?: (event: FormattingTelemetryEvent) => void;
+}
+
+export function resolveEffectiveFormatting(
+  doc: CanonicalDocument,
+  nodeRef: NodeRef,
+  opts?: ResolveEffectiveFormattingOptions,
+): EffectiveFormatting {
+  // Build a per-call façade context. Production consumers with a
+  // long-lived projection pass construct their own `FormattingContext`
+  // once and use it directly; the façade exists for external callers
+  // + tests that prefer the `(doc, nodeRef, opts)` entry shape.
+  const ctx = buildFacadeContext(doc, nodeRef, opts);
+  emitSampled(opts, {
+    type: "formatting.resolution_sampled",
+    payload: {
+      kind: nodeRef.kind,
+      blockId: nodeRef.blockId,
+      hasDirect: nodeRef.kind === "run" || nodeRef.kind === "field" || nodeRef.kind === "drawing-frame",
+      hasTheme: Boolean(opts?.themeResolver ?? doc.subParts?.canonicalTheme),
+      hasNumbering: Boolean(opts?.numberingPrefixResolver ?? doc.numbering),
+    },
+  });
+
+  switch (nodeRef.kind) {
+    case "paragraph":
+      return resolveParagraph(ctx, nodeRef.blockId);
+    case "run":
+      return resolveRun(ctx, doc, nodeRef.blockId, nodeRef.runId, opts);
+    case "table":
+      return resolveTable(ctx, nodeRef.blockId);
+    case "table-cell": {
+      const found = findTableByBlockId(doc, nodeRef.blockId);
+      if (!found) return { kind: "table-cell", paragraph: {}, run: {} };
+      // Resolve conditional regions for this cell so the floor cascade
+      // layers tblStylePr pPr/rPr for header rows, banded rows, first
+      // columns, etc. (L03 A1). Out-of-bounds row/cell indices fall
+      // back to no region info (same output as pre-A1).
+      const resolved = ctx.resolveTable(found.table);
+      const activeRegions =
+        resolved.rows[nodeRef.rowIndex]?.cells[nodeRef.cellIndex]
+          ?.activeConditionalRegions;
+      const { paragraph, run } = ctx.resolveTableCellFloor(
+        found.table.styleId,
+        activeRegions,
+      );
+      return { kind: "table-cell", paragraph, run };
+    }
+    case "field":
+      return resolveField(ctx, doc, nodeRef, opts);
+    case "drawing-frame":
+      return resolveDrawingFrame(ctx, doc, nodeRef.blockId, nodeRef.inlineId, opts);
+  }
+}
+
+function buildFacadeContext(
+  doc: CanonicalDocument,
+  nodeRef: NodeRef,
+  opts: ResolveEffectiveFormattingOptions | undefined,
+): FormattingContext {
+  const pageGraph =
+    nodeRef.kind === "field" ? nodeRef.pageGraph : undefined;
+  return createFormattingContext(doc, {
+    revisionMarkupMode: opts?.revisionMarkupMode,
+    authorColorPalette: opts?.authorColorPalette,
+    fontTable: opts?.fontTable,
+    pageGraph,
+  });
+}
+
+function resolveParagraph(
+  ctx: FormattingContext,
+  blockId: string,
+): Extract<EffectiveFormatting, { kind: "paragraph" }> {
+  const found = findParagraphByBlockId(ctx.doc, blockId);
+  if (!found) return { kind: "paragraph", paragraph: {} };
+  return { kind: "paragraph", paragraph: ctx.resolveParagraph(found.paragraph) };
+}
+
+function resolveRun(
+  ctx: FormattingContext,
+  doc: CanonicalDocument,
+  blockId: string,
+  runId: string,
+  opts: ResolveEffectiveFormattingOptions | undefined,
+): Extract<EffectiveFormatting, { kind: "run" }> {
+  void doc;
+  const found = findParagraphByBlockId(ctx.doc, blockId);
+  if (!found) return { kind: "run", run: {} };
+  const para = found.paragraph;
+  const direct = resolveDirectRunFormattingAtSegment(para, runId);
+  const run = ctx.resolveRunFromCanonicalInline({
+    paragraphStyleId: para.styleId,
+    characterStyleId: direct?.characterStyleId,
+    direct,
+    inHyperlink: detectHyperlinkContext(para, runId),
+    ...(opts?.revision ? { revision: opts.revision } : {}),
+  });
+  return { kind: "run", run };
+}
+
+function resolveTable(
+  ctx: FormattingContext,
+  blockId: string,
+): Extract<EffectiveFormatting, { kind: "table" }> {
+  const found = findTableByBlockId(ctx.doc, blockId);
+  if (!found) {
+    return {
+      kind: "table",
+      table: {
+        effectiveTblLook: {},
+        tableResolved: {},
+        rows: [],
+      },
+    };
+  }
+  return { kind: "table", table: ctx.resolveTable(found.table) };
+}
+
+function resolveField(
+  ctx: FormattingContext,
+  doc: CanonicalDocument,
+  nodeRef: Extract<NodeRef, { kind: "field" }>,
+  opts: ResolveEffectiveFormattingOptions | undefined,
+): Extract<EffectiveFormatting, { kind: "field" }> {
+  const found = findParagraphByBlockId(doc, nodeRef.blockId);
+  if (!found) {
+    return {
+      kind: "field",
+      run: {},
+      field: { refreshStatus: "unresolved" },
+    };
+  }
+
+  const para = found.paragraph;
+  const direct = resolveDirectRunFormattingAtSegment(para, nodeRef.runId);
+  const run = ctx.resolveRunFromCanonicalInline({
+    paragraphStyleId: para.styleId,
+    characterStyleId: undefined,
+    direct,
+    inHyperlink: false,
+    ...(opts?.revision ? { revision: opts.revision } : {}),
+  });
+
+  const fieldInline = findFieldNodeAtSegment(para, nodeRef.runId);
+  const registryEntry = fieldInline
+    ? findFieldRegistryEntryForParagraph(doc, found.paragraphIndex, fieldInline)
+    : undefined;
+
+  // The façade resolver was built with `nodeRef.pageGraph` threaded in,
+  // so `ctx.field` is present iff the caller supplied a page graph.
+  let field: EffectiveFieldDisplay;
+  if (!registryEntry) {
+    field = { refreshStatus: "unresolved" };
+  } else if (opts?.fieldResolver) {
+    // Honor an explicit pre-built fieldResolver over the context's own
+    // (preserves the opts-threading contract for external callers).
+    const resolved = opts.fieldResolver.resolve(registryEntry);
+    field = mapResolvedField(resolved, registryEntry);
+  } else {
+    field = ctx.resolveFieldDisplay(registryEntry, registryEntry.displayText);
+  }
+
+  return { kind: "field", run, field };
+}
+
+function resolveDrawingFrame(
+  ctx: FormattingContext,
+  doc: CanonicalDocument,
+  blockId: string,
+  inlineId: string,
+  opts: ResolveEffectiveFormattingOptions | undefined,
+): Extract<EffectiveFormatting, { kind: "drawing-frame" }> {
+  void doc;
+  const found = findParagraphByBlockId(ctx.doc, blockId);
+  if (!found) return { kind: "drawing-frame", run: {} };
+  const para = found.paragraph;
+  const direct = resolveDirectRunFormattingAtSegment(para, inlineId);
+  const run = ctx.resolveRunFromCanonicalInline({
+    paragraphStyleId: para.styleId,
+    characterStyleId: undefined,
+    direct,
+    inHyperlink: false,
+    ...(opts?.revision ? { revision: opts.revision } : {}),
+  });
+  return { kind: "drawing-frame", run };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function detectHyperlinkContext(para: ParagraphNode, runId: string): boolean {
+  const segmentIndex = parseSegmentIndex(runId);
+  if (segmentIndex === undefined) return false;
+  let s = 0;
+  for (const inline of para.children) {
+    if (inline.type === "hyperlink") {
+      for (let i = 0; i < inline.children.length; i += 1) {
+        if (s === segmentIndex) return true;
+        s += 1;
+      }
+      continue;
+    }
+    if (
+      inline.type === "bookmark_start" ||
+      inline.type === "bookmark_end" ||
+      inline.type === "scope_marker_start" ||
+      inline.type === "scope_marker_end"
+    ) {
+      continue;
+    }
+    if (s === segmentIndex) return false;
+    s += 1;
+  }
+  return false;
+}
+
+function findFieldNodeAtSegment(
+  para: ParagraphNode,
+  runId: string,
+): FieldNode | undefined {
+  const segmentIndex = parseSegmentIndex(runId);
+  if (segmentIndex === undefined) return undefined;
+  const found = findInlineBySegmentIndex(para, segmentIndex);
+  if (!found) return undefined;
+  return found.inline.type === "field" ? (found.inline as FieldNode) : undefined;
+}
+
+function findFieldRegistryEntryForParagraph(
+  doc: CanonicalDocument,
+  paragraphIndex: number,
+  fieldInline: FieldNode,
+): FieldRegistryEntry | undefined {
+  const registry = doc.fieldRegistry;
+  if (!registry) return undefined;
+  const all = [...registry.supported, ...registry.preserveOnly];
+  return all.find(
+    (entry) =>
+      entry.paragraphIndex === paragraphIndex &&
+      entry.fieldFamily === fieldInline.fieldFamily &&
+      entry.instruction === fieldInline.instruction,
+  );
+}
+
+function mapResolvedField(
+  resolved: { displayText?: string; refreshStatus: string } | undefined,
+  registry: FieldRegistryEntry,
+): EffectiveFieldDisplay {
+  if (!resolved) {
+    return {
+      refreshStatus: "unresolved",
+      ...(registry.displayText ? { displayText: registry.displayText } : {}),
+    };
+  }
+  const status: EffectiveFieldDisplay["refreshStatus"] =
+    resolved.refreshStatus === "current" || resolved.refreshStatus === "stale"
+      ? "resolved"
+      : resolved.refreshStatus === "unresolvable"
+        ? "unresolvable"
+        : "unresolved";
+  return {
+    refreshStatus: status,
+    ...(resolved.displayText !== undefined
+      ? { displayText: resolved.displayText }
+      : registry.displayText
+        ? { displayText: registry.displayText }
+        : {}),
+  };
+}
+
+function emitSampled(
+  opts: ResolveEffectiveFormattingOptions | undefined,
+  event: FormattingTelemetryEvent,
+): void {
+  if (!opts?.emitFormattingTelemetry) return;
+  opts.emitFormattingTelemetry(event);
+}

package/src/runtime/formatting/revision-display.ts

@@ -0,0 +1,105 @@
+/**
+ * Layer 03 — revision-display posture application.
+ *
+ * UI / session capabilities decide which markup mode is active. This
+ * module owns the *application* of that mode to a run with an attached
+ * revision; it does NOT decide the mode. Reference: contract F6 in
+ * `docs/architecture/03-formatting-semantics.md` §52.
+ *
+ * Mode semantics:
+ *   - "clean"  — open deletions are hidden; insertions + accepted/rejected
+ *                revisions render as final content.
+ *   - "simple" — content visible but de-emphasized; simple inline markup.
+ *   - "all"    — strikethrough on open deletions; insertion-underline on
+ *                insertions; formatting/property/move changes surface only
+ *                via author color + change bars (owned by paragraph
+ *                projection).
+ *
+ * `applyRevisionDisplay(run, revision, markupMode, authorColor?)` is pure
+ * and deterministic: same inputs → same output, no hidden state. That
+ * determinism lets downstream render code memoize on
+ * `(run, revision, markupMode)` identity.
+ *
+ * The `run: CanonicalRunFormatting` parameter lets this function inspect
+ * the already-cascaded run state to avoid redundant flags — e.g. a
+ * deletion run that already carries `strikethrough: true` via direct
+ * formatting skips the `all`-mode strikethrough flag so the rendered
+ * glyph is not double-struck.
+ */
+
+import type {
+  CanonicalRunFormatting,
+  RevisionRecord,
+} from "../../model/canonical-document.ts";
+import type { RevisionDisplayFlags } from "./formatting-types.ts";
+
+export type RevisionMarkupMode = "clean" | "simple" | "all";
+
+export function applyRevisionDisplay(
+  run: CanonicalRunFormatting,
+  revision: RevisionRecord,
+  markupMode: RevisionMarkupMode,
+  authorColor?: string,
+): RevisionDisplayFlags {
+  switch (markupMode) {
+    case "clean": {
+      if (revision.kind === "deletion" && revision.status === "open") {
+        return buildFlags(markupMode, authorColor, { hidden: true });
+      }
+      return buildFlags(markupMode, authorColor);
+    }
+
+    case "simple": {
+      // Content visible, de-emphasized. No strikethrough / underline
+      // markers — the consumer renders a muted style (opacity /
+      // secondary color) uniformly.
+      return buildFlags(markupMode, authorColor, { deemphasize: true });
+    }
+
+    case "all": {
+      switch (revision.kind) {
+        case "deletion": {
+          // Short-circuit: if the run already carries strikethrough via
+          // direct formatting (uncommon but possible: a deletion whose
+          // source already had strikethrough as authoring style), do NOT
+          // add the revision strikethrough flag — avoids double-struck
+          // glyphs in render.
+          if (run.strikethrough === true) {
+            return buildFlags(markupMode, authorColor);
+          }
+          return buildFlags(markupMode, authorColor, { strikethrough: true });
+        }
+        case "insertion": {
+          // Mirror short-circuit for insertions. If the run already carries
+          // a single-underline via direct formatting, skip the insertion
+          // underline so the render doesn't over-paint.
+          if (run.underline === "single") {
+            return buildFlags(markupMode, authorColor);
+          }
+          return buildFlags(markupMode, authorColor, { insertionUnderline: true });
+        }
+        case "formatting":
+        case "property-change":
+        case "move": {
+          // Paragraph-level markers (change-bar, move-from/to arrows) are
+          // owned by the paragraph projection. For runs that carry these
+          // revision kinds, fall through to the author-color-only posture.
+          return buildFlags(markupMode, authorColor);
+        }
+      }
+      return buildFlags(markupMode, authorColor);
+    }
+  }
+}
+
+function buildFlags(
+  markupMode: RevisionMarkupMode,
+  authorColor: string | undefined,
+  extras: Omit<RevisionDisplayFlags, "markupMode" | "authorColor"> = {},
+): RevisionDisplayFlags {
+  return {
+    markupMode,
+    ...(authorColor !== undefined ? { authorColor } : {}),
+    ...extras,
+  };
+}