@beyondwork/docx-react-component 1.0.36 → 1.0.37

package/src/runtime/layout/resolved-formatting-document.ts

@@ -0,0 +1,317 @@
+/**
+ * Document-level ResolvedFormattingState.
+ *
+ * Per the architecture spec (runtime-owned-paginated-layout-engine.md §1), the
+ * layout engine needs a single inspectable surface that aggregates every
+ * formatting input required for page composition:
+ *
+ *   paragraphs, runs, fonts, tabs, numbering geometry, document settings
+ *
+ * This module builds that aggregate once per document snapshot and hands it to
+ * the engine. Per-block lookups become O(1) map reads instead of re-deriving
+ * the same resolution from multiple sources.
+ *
+ * Important:
+ *   - This state is derived entirely from the canonical envelope; it never
+ *     reads DOM or PM state.
+ *   - It is read-only once constructed. Mutations produce a new instance.
+ *   - The canonical model here carries limited style/run metadata; the
+ *     resolver therefore synthesizes per-segment `ResolvedRunFormatting` from
+ *     the surface snapshot's `markAttrs` plus theme minor/major fonts.
+ */
+
+import type {
+  EditorSurfaceSnapshot,
+  SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
+} from "../../api/public-types";
+import type {
+  CanonicalDocumentEnvelope,
+} from "../../core/state/editor-state.ts";
+import type {
+  DocumentSettings,
+  NumberingInstance,
+  ResolvedTheme,
+  SubPartsCatalog,
+} from "../../model/canonical-document.ts";
+import {
+  resolveBlockFormatting,
+  type ResolvedParagraphFormatting,
+} from "./resolved-formatting-state.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Stable run id: `${blockId}:${segmentId}`. */
+export type RunId = string;
+
+export interface ResolvedRunFormatting {
+  fontFamily?: string;
+  /** Resolved font size in half-points. */
+  fontSizeHalfPoints?: number;
+  bold: boolean;
+  italic: boolean;
+  underline: boolean;
+  strikethrough: boolean;
+  color?: string;
+  highlight?: string;
+  verticalAlign: "baseline" | "superscript" | "subscript";
+}
+
+export interface ResolvedFontDescriptor {
+  family: string;
+  /** Which heading tier, if any, this family represents in the theme. */
+  themeRole?: "major" | "minor";
+}
+
+export interface ResolvedFontCatalog {
+  families: Map<string, ResolvedFontDescriptor>;
+  /** Theme minor (body) font, if the package declares one. */
+  minorFont?: string;
+  /** Theme major (heading) font, if the package declares one. */
+  majorFont?: string;
+}
+
+export interface ResolvedTabSettings {
+  /** Document default tab interval in twips. */
+  defaultTabInterval: number;
+}
+
+export interface NumberingInstanceMetadata {
+  instanceId: string;
+  abstractId: string | undefined;
+  maxLevels: number;
+}
+
+export interface ResolvedNumberingGeometry {
+  instances: Map<string, NumberingInstanceMetadata>;
+}
+
+export interface ResolvedDocumentSettings {
+  /** Whether odd/even header/footer rendering is active. */
+  evenAndOddHeaders: boolean;
+  /** Widow/orphan default (always true in the current model). */
+  widowControlDefault: boolean;
+}
+
+export interface ResolvedFormattingState {
+  paragraphs: Map<string, ResolvedParagraphFormatting>;
+  runs: Map<RunId, ResolvedRunFormatting>;
+  fonts: ResolvedFontCatalog;
+  tabs: ResolvedTabSettings;
+  numbering: ResolvedNumberingGeometry;
+  settings: ResolvedDocumentSettings;
+  revision: number;
+}
+
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+
+let revisionCounter = 0;
+
+export function buildResolvedFormattingState(
+  document: CanonicalDocumentEnvelope,
+  mainSurface: EditorSurfaceSnapshot,
+): ResolvedFormattingState {
+  revisionCounter += 1;
+
+  const paragraphs = new Map<string, ResolvedParagraphFormatting>();
+  const runs = new Map<RunId, ResolvedRunFormatting>();
+  const usedFamilies = new Set<string>();
+
+  const theme = document.subParts?.resolvedTheme;
+  collectFormatting(mainSurface.blocks, paragraphs, runs, usedFamilies, theme);
+
+  return {
+    paragraphs,
+    runs,
+    fonts: buildFontCatalog(usedFamilies, document.subParts),
+    tabs: buildTabSettings(),
+    numbering: buildNumberingGeometry(document.subParts),
+    settings: buildDocumentSettings(document.subParts?.settings),
+    revision: revisionCounter,
+  };
+}
+
+function collectFormatting(
+  blocks: readonly SurfaceBlockSnapshot[],
+  paragraphs: Map<string, ResolvedParagraphFormatting>,
+  runs: Map<RunId, ResolvedRunFormatting>,
+  usedFamilies: Set<string>,
+  theme: ResolvedTheme | undefined,
+): void {
+  for (const block of blocks) {
+    switch (block.kind) {
+      case "paragraph": {
+        const formatting = resolveBlockFormatting(block);
+        if (formatting) {
+          paragraphs.set(block.blockId, formatting);
+        }
+        for (const segment of block.segments) {
+          if (segment.kind !== "text") continue;
+          const runId = `${block.blockId}:${segment.segmentId}`;
+          const resolved = resolveRunFormattingFromSegment(segment, theme);
+          runs.set(runId, resolved);
+          if (resolved.fontFamily) {
+            usedFamilies.add(resolved.fontFamily);
+          }
+        }
+        break;
+      }
+      case "table":
+        for (const row of block.rows) {
+          for (const cell of row.cells) {
+            collectFormatting(cell.content, paragraphs, runs, usedFamilies, theme);
+          }
+        }
+        break;
+      case "sdt_block":
+        collectFormatting(block.children, paragraphs, runs, usedFamilies, theme);
+        break;
+    }
+  }
+}
+
+function resolveRunFormattingFromSegment(
+  segment: Extract<SurfaceInlineSegment, { kind: "text" }>,
+  theme: ResolvedTheme | undefined,
+): ResolvedRunFormatting {
+  const markAttrs = segment.markAttrs ?? {};
+  const markSet = new Set(segment.marks ?? []);
+  const explicitFamily =
+    typeof markAttrs.fontFamily === "string" ? markAttrs.fontFamily : undefined;
+  // When an explicit family isn't present, fall back to theme minor font as
+  // per OOXML default (body text uses the minor font from the theme).
+  const fontFamily = explicitFamily ?? theme?.minorFont;
+
+  return {
+    ...(fontFamily ? { fontFamily } : {}),
+    ...(typeof markAttrs.fontSize === "number"
+      ? { fontSizeHalfPoints: markAttrs.fontSize }
+      : {}),
+    bold: markSet.has("bold"),
+    italic: markSet.has("italic"),
+    underline: markSet.has("underline"),
+    strikethrough: markSet.has("strikethrough") || markSet.has("doubleStrikethrough"),
+    ...(typeof markAttrs.textColor === "string" ? { color: markAttrs.textColor } : {}),
+    ...(typeof markAttrs.backgroundColor === "string"
+      ? { highlight: markAttrs.backgroundColor }
+      : {}),
+    verticalAlign: markSet.has("superscript")
+      ? "superscript"
+      : markSet.has("subscript")
+        ? "subscript"
+        : "baseline",
+  };
+}
+
+function buildFontCatalog(
+  usedFamilies: ReadonlySet<string>,
+  subParts: SubPartsCatalog | undefined,
+): ResolvedFontCatalog {
+  const families = new Map<string, ResolvedFontDescriptor>();
+  const theme = subParts?.resolvedTheme;
+  for (const family of usedFamilies) {
+    const normalized = family.toLowerCase();
+    const isMinor =
+      theme?.minorFont !== undefined && family === theme.minorFont;
+    const isMajor =
+      theme?.majorFont !== undefined && family === theme.majorFont;
+    families.set(normalized, {
+      family,
+      ...(isMinor ? { themeRole: "minor" as const } : {}),
+      ...(isMajor ? { themeRole: "major" as const } : {}),
+    });
+  }
+  if (theme?.minorFont && !families.has(theme.minorFont.toLowerCase())) {
+    families.set(theme.minorFont.toLowerCase(), {
+      family: theme.minorFont,
+      themeRole: "minor",
+    });
+  }
+  if (theme?.majorFont && !families.has(theme.majorFont.toLowerCase())) {
+    families.set(theme.majorFont.toLowerCase(), {
+      family: theme.majorFont,
+      themeRole: "major",
+    });
+  }
+  return {
+    families,
+    ...(theme?.minorFont ? { minorFont: theme.minorFont } : {}),
+    ...(theme?.majorFont ? { majorFont: theme.majorFont } : {}),
+  };
+}
+
+function buildTabSettings(): ResolvedTabSettings {
+  // Current DocumentSettings model does not carry `defaultTabStop`.
+  // Word's default is 720 twips (0.5"); retain that until settings exposes one.
+  return {
+    defaultTabInterval: 720,
+  };
+}
+
+function buildNumberingGeometry(
+  subParts: SubPartsCatalog | undefined,
+): ResolvedNumberingGeometry {
+  // Numbering is imported separately into runtime state (not on subParts);
+  // for layout we only need instance metadata, which is sufficient to dirty
+  // layout when a numbering instance changes.
+  const instances = new Map<string, NumberingInstanceMetadata>();
+  // `subParts` presence check keeps the parameter used for future expansion.
+  if (!subParts) return { instances };
+  return { instances };
+}
+
+function buildDocumentSettings(
+  settings: DocumentSettings | undefined,
+): ResolvedDocumentSettings {
+  return {
+    evenAndOddHeaders: Boolean(settings?.evenAndOddHeaders),
+    widowControlDefault: true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helper: cheap lookup
+// ---------------------------------------------------------------------------
+
+export function getResolvedParagraph(
+  state: ResolvedFormattingState,
+  blockId: string,
+): ResolvedParagraphFormatting | undefined {
+  return state.paragraphs.get(blockId);
+}
+
+export function getResolvedRun(
+  state: ResolvedFormattingState,
+  runId: RunId,
+): ResolvedRunFormatting | undefined {
+  return state.runs.get(runId);
+}
+
+/** Collect the set of font families actually used anywhere in the document. */
+export function collectUsedFontFamilies(
+  state: ResolvedFormattingState,
+): readonly string[] {
+  const out = new Set<string>();
+  for (const descriptor of state.fonts.families.values()) {
+    out.add(descriptor.family);
+  }
+  return Array.from(out);
+}
+
+/** Accumulate `NumberingInstance` metadata from runtime numbering state. */
+export function populateNumberingInstances(
+  state: ResolvedFormattingState,
+  instances: ReadonlyArray<NumberingInstance>,
+): void {
+  for (const instance of instances) {
+    state.numbering.instances.set(instance.numberingInstanceId, {
+      instanceId: instance.numberingInstanceId,
+      abstractId: instance.abstractNumberingId,
+      maxLevels: instance.overrides?.length ?? 0,
+    });
+  }
+}