@beyondwork/docx-react-component 1.0.36 → 1.0.38

package/src/runtime/layout/page-format-catalog.ts

@@ -0,0 +1,233 @@
+/**
+ * Page-format catalog — named page sizes that back the section page-size
+ * picker and the real-dimension page frame.
+ *
+ * The canonical storage of page geometry remains
+ * `SectionProperties.pageSize` in twips.  This catalog adds a layer of
+ * semantic naming on top so the UI can render "A4" or "US Letter" and
+ * the render kernel can pick a sensible default per locale.
+ *
+ * Unit reference (OOXML):
+ *   - 1 inch = 1440 twips
+ *   - 1 mm   = 56.6929 twips
+ *
+ * The catalog deliberately ships a single default match tolerance (1 twip)
+ * so legacy documents whose page sizes were round-tripped through third-
+ * party tools still identify as the named format they were authored at.
+ */
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type PageFormatId =
+  | "letter"
+  | "legal"
+  | "tabloid"
+  | "executive"
+  | "a3"
+  | "a4"
+  | "a5"
+  | "b4-iso"
+  | "b5-iso"
+  | "custom";
+
+export type PageFormatRegion = "us" | "iso" | "jp" | "custom";
+
+export type PageFormatLocaleDefault = "en-us" | "en-gb" | "eu" | "jp";
+
+export interface PageFormatDisplay {
+  inches?: string;
+  millimeters?: string;
+}
+
+export interface PageFormatDefinition {
+  /** Stable identifier. */
+  id: PageFormatId;
+  /** Human-facing label used in pickers. */
+  label: string;
+  /** Locale or region hint. */
+  region: PageFormatRegion;
+  /** Width in twips at portrait orientation. */
+  portraitWidthTwips: number;
+  /** Height in twips at portrait orientation. */
+  portraitHeightTwips: number;
+  /** Default-for-locale hint so consumers can pick a sensible default. */
+  localeDefault?: PageFormatLocaleDefault;
+  /** Pre-computed inches/millimeters strings for the picker. */
+  display: PageFormatDisplay;
+}
+
+export interface ActivePageFormat {
+  sectionIndex: number;
+  format: PageFormatDefinition;
+  orientation: "portrait" | "landscape";
+  /** True when the section matches a catalog format within the match tolerance. */
+  matchesCatalog: boolean;
+  /** When matchesCatalog is false, the raw twips (custom format). */
+  customTwips?: { width: number; height: number };
+}
+
+// ---------------------------------------------------------------------------
+// Catalog
+// ---------------------------------------------------------------------------
+
+/**
+ * Pre-defined named page formats.  Ordering intentionally puts the most
+ * common sizes (Letter, A4) first because UI dropdowns render in list order.
+ */
+export const PAGE_FORMAT_CATALOG: readonly PageFormatDefinition[] = Object.freeze([
+  {
+    id: "letter",
+    label: "US Letter",
+    region: "us",
+    portraitWidthTwips: 12240,
+    portraitHeightTwips: 15840,
+    localeDefault: "en-us",
+    display: { inches: "8.5 × 11 in", millimeters: "215.9 × 279.4 mm" },
+  },
+  {
+    id: "a4",
+    label: "A4",
+    region: "iso",
+    portraitWidthTwips: 11906,
+    portraitHeightTwips: 16838,
+    localeDefault: "eu",
+    display: { inches: "8.27 × 11.69 in", millimeters: "210 × 297 mm" },
+  },
+  {
+    id: "legal",
+    label: "US Legal",
+    region: "us",
+    portraitWidthTwips: 12240,
+    portraitHeightTwips: 20160,
+    display: { inches: "8.5 × 14 in", millimeters: "215.9 × 355.6 mm" },
+  },
+  {
+    id: "tabloid",
+    label: "Tabloid / Ledger",
+    region: "us",
+    portraitWidthTwips: 15840,
+    portraitHeightTwips: 24480,
+    display: { inches: "11 × 17 in", millimeters: "279.4 × 431.8 mm" },
+  },
+  {
+    id: "executive",
+    label: "Executive",
+    region: "us",
+    portraitWidthTwips: 10440,
+    portraitHeightTwips: 15120,
+    display: { inches: "7.25 × 10.5 in", millimeters: "184.1 × 266.7 mm" },
+  },
+  {
+    id: "a3",
+    label: "A3",
+    region: "iso",
+    portraitWidthTwips: 16838,
+    portraitHeightTwips: 23811,
+    display: { inches: "11.69 × 16.54 in", millimeters: "297 × 420 mm" },
+  },
+  {
+    id: "a5",
+    label: "A5",
+    region: "iso",
+    portraitWidthTwips: 8391,
+    portraitHeightTwips: 11906,
+    display: { inches: "5.83 × 8.27 in", millimeters: "148 × 210 mm" },
+  },
+  {
+    id: "b4-iso",
+    label: "B4 (ISO)",
+    region: "iso",
+    portraitWidthTwips: 14173,
+    portraitHeightTwips: 20016,
+    display: { inches: "9.84 × 13.90 in", millimeters: "250 × 353 mm" },
+  },
+  {
+    id: "b5-iso",
+    label: "B5 (ISO)",
+    region: "iso",
+    portraitWidthTwips: 9977,
+    portraitHeightTwips: 14173,
+    display: { inches: "6.93 × 9.84 in", millimeters: "176 × 250 mm" },
+  },
+  {
+    id: "custom",
+    label: "Custom",
+    region: "custom",
+    portraitWidthTwips: 0,
+    portraitHeightTwips: 0,
+    display: {},
+  },
+]);
+
+/**
+ * Match tolerance in twips.  Historic round-trips through third-party tools
+ * sometimes drift by sub-twip amounts; a 1-twip window catches those while
+ * keeping intentionally custom sizes genuinely custom.
+ */
+const MATCH_TOLERANCE_TWIPS = 1;
+
+// ---------------------------------------------------------------------------
+// Matching
+// ---------------------------------------------------------------------------
+
+export interface MatchPageFormatInput {
+  sectionIndex: number;
+  widthTwips: number;
+  heightTwips: number;
+}
+
+/**
+ * Match a section's page dimensions against the catalog.
+ *
+ * The matcher tolerates either orientation — if the supplied (width, height)
+ * match a catalog entry rotated by 90°, the active format is reported as
+ * `landscape`.  Custom sizes fall through to the `custom` entry.
+ */
+export function matchPageFormat(input: MatchPageFormatInput): ActivePageFormat {
+  const { sectionIndex, widthTwips, heightTwips } = input;
+
+  for (const format of PAGE_FORMAT_CATALOG) {
+    if (format.id === "custom") continue;
+
+    const portraitMatch =
+      near(widthTwips, format.portraitWidthTwips) &&
+      near(heightTwips, format.portraitHeightTwips);
+    const landscapeMatch =
+      near(widthTwips, format.portraitHeightTwips) &&
+      near(heightTwips, format.portraitWidthTwips);
+
+    if (portraitMatch || landscapeMatch) {
+      return {
+        sectionIndex,
+        format,
+        orientation: portraitMatch ? "portrait" : "landscape",
+        matchesCatalog: true,
+      };
+    }
+  }
+
+  const custom = PAGE_FORMAT_CATALOG.find((f) => f.id === "custom")!;
+  return {
+    sectionIndex,
+    format: custom,
+    orientation: widthTwips > heightTwips ? "landscape" : "portrait",
+    matchesCatalog: false,
+    customTwips: { width: widthTwips, height: heightTwips },
+  };
+}
+
+function near(a: number, b: number): boolean {
+  return Math.abs(a - b) <= MATCH_TOLERANCE_TWIPS;
+}
+
+/**
+ * Look up a format by id.  Returns the `custom` entry for unknown ids so
+ * callers can chain `.format` reads without null-checking.
+ */
+export function getPageFormatById(id: string): PageFormatDefinition {
+  const found = PAGE_FORMAT_CATALOG.find((f) => f.id === id);
+  if (found) return found;
+  return PAGE_FORMAT_CATALOG.find((f) => f.id === "custom")!;
+}

package/src/runtime/layout/page-fragment-mapper.ts

@@ -0,0 +1,179 @@
+/**
+ * PageFragmentMapper — offset ↔ fragment ↔ region mapping.
+ *
+ * Per runtime-owned-paginated-layout-engine.md §6, this is the missing layer
+ * between `pm-position-map.ts` and `DocumentNavigationSnapshot`:
+ *
+ *   runtime position → page fragment → visible page region
+ *
+ * The mapper is a pure query service over a RuntimePageGraph.  It does not
+ * mutate state and does not consult DOM or PM.
+ */
+
+import type { EditorStoryTarget, SelectionSnapshot } from "../../api/public-types";
+import type {
+  RuntimeBlockFragment,
+  RuntimePageGraph,
+  RuntimePageNode,
+} from "./page-graph.ts";
+
+export interface PageFragmentLocation {
+  pageId: string;
+  pageIndex: number;
+  fragmentId: string;
+  regionKind: "body" | "header" | "footer" | "column" | "footnote-area";
+  /** Zero-based index of the line box within the fragment, if line boxes are available. */
+  lineBoxIndex?: number;
+}
+
+export interface PageSpan {
+  firstPageIndex: number;
+  lastPageIndex: number;
+  pageCount: number;
+}
+
+export interface PageFragmentMapper {
+  mapOffsetToFragment(offset: number, story?: EditorStoryTarget): PageFragmentLocation | null;
+  mapFragmentToOffsetRange(fragmentId: string): { from: number; to: number } | null;
+  mapSelectionToPageSpan(selection: SelectionSnapshot): PageSpan | null;
+  /**
+   * Resolve a page-local anchor for the given offset.  Returns the offset
+   * unchanged today; retained as a seam for future semantic anchors.
+   */
+  getAnchorForOffset(offset: number, story?: EditorStoryTarget): { offset: number; pageId: string } | null;
+}
+
+export function createPageFragmentMapper(graph: RuntimePageGraph): PageFragmentMapper {
+  const fragmentsById = new Map<string, RuntimeBlockFragment>();
+  for (const fragment of graph.fragments) {
+    fragmentsById.set(fragment.fragmentId, fragment);
+  }
+
+  const pagesById = new Map<string, RuntimePageNode>();
+  for (const page of graph.pages) {
+    pagesById.set(page.pageId, page);
+  }
+
+  function findFragmentAt(offset: number): RuntimeBlockFragment | undefined {
+    // Fragments sort naturally by page then order; a linear scan is O(n) but
+    // page counts are small (legal docs rarely exceed a few hundred pages).
+    for (const fragment of graph.fragments) {
+      if (offset >= fragment.from && offset < fragment.to) {
+        return fragment;
+      }
+    }
+    // fall back to the last fragment that starts at or before the offset
+    let best: RuntimeBlockFragment | undefined;
+    for (const fragment of graph.fragments) {
+      if (fragment.from <= offset) {
+        if (!best || fragment.from > best.from) best = fragment;
+      }
+    }
+    return best;
+  }
+
+  return {
+    mapOffsetToFragment(offset, _story) {
+      const fragment = findFragmentAt(offset);
+      if (!fragment) {
+        // Fallback to coarse page lookup
+        const page = findPageForOffsetInternal(graph, offset);
+        if (!page) return null;
+        return {
+          pageId: page.pageId,
+          pageIndex: page.pageIndex,
+          fragmentId: `${page.pageId}-synthetic`,
+          regionKind: "body",
+        };
+      }
+      const page = pagesById.get(fragment.pageId);
+      if (!page) return null;
+
+      // Locate a line box if any
+      let lineBoxIndex: number | undefined;
+      for (let i = 0; i < page.lineBoxes.length; i += 1) {
+        if (page.lineBoxes[i]!.fragmentId === fragment.fragmentId) {
+          lineBoxIndex = i;
+          break;
+        }
+      }
+
+      return {
+        pageId: page.pageId,
+        pageIndex: page.pageIndex,
+        fragmentId: fragment.fragmentId,
+        regionKind: fragment.regionKind,
+        ...(lineBoxIndex !== undefined ? { lineBoxIndex } : {}),
+      };
+    },
+
+    mapFragmentToOffsetRange(fragmentId) {
+      const fragment = fragmentsById.get(fragmentId);
+      if (!fragment) return null;
+      return { from: fragment.from, to: fragment.to };
+    },
+
+    mapSelectionToPageSpan(selection) {
+      const from = Math.min(selection.anchor, selection.head);
+      const to = Math.max(selection.anchor, selection.head);
+      const firstPage = findPageForOffsetInternal(graph, from);
+      const lastPage = findPageForOffsetInternal(graph, to);
+      if (!firstPage || !lastPage) return null;
+      return {
+        firstPageIndex: firstPage.pageIndex,
+        lastPageIndex: lastPage.pageIndex,
+        pageCount: Math.max(1, lastPage.pageIndex - firstPage.pageIndex + 1),
+      };
+    },
+
+    getAnchorForOffset(offset, _story) {
+      const page = findPageForOffsetInternal(graph, offset);
+      if (!page) return null;
+      return { offset, pageId: page.pageId };
+    },
+  };
+}
+
+function findPageForOffsetInternal(
+  graph: RuntimePageGraph,
+  offset: number,
+): RuntimePageNode | undefined {
+  for (const page of graph.pages) {
+    if (!page.isBlankFiller && offset < page.endOffset) {
+      return page;
+    }
+  }
+  return graph.pages[graph.pages.length - 1];
+}
+
+/**
+ * Rebuild the mapper for a spliced graph.
+ *
+ * Correctness baseline: the simplest safe implementation is to fully rebuild
+ * the mapper from the new graph. The `prior` and `firstDirtyPage` arguments
+ * are accepted for forward compatibility with a future optimization that
+ * retains fragment-id indexes for unaffected pages. Today rebuilding is
+ * cheap (linear in fragment count) so the naive path is the right trade-off.
+ *
+ * Renamed from `updateMapperIncremental` (§6 E.5) now that the body is an
+ * unconditional full rebuild — the old name implied an incremental strategy
+ * that never actually existed in the shipped runtime.
+ */
+export function rebuildMapper(
+  prior: PageFragmentMapper,
+  splicedGraph: RuntimePageGraph,
+  firstDirtyPage: number,
+): PageFragmentMapper {
+  // Parameters are intentionally unused by the current implementation;
+  // retained as a seam for a future bounded update path.
+  void prior;
+  void firstDirtyPage;
+  return createPageFragmentMapper(splicedGraph);
+}
+
+/**
+ * @deprecated Renamed to `rebuildMapper` in §6 E.5. Retained as a
+ * one-release compatibility alias so external consumers are not broken by
+ * the rename; schedule removal after the next published API pin refresh.
+ */
+export const updateMapperIncremental = rebuildMapper;