@beyondwork/docx-react-component 1.0.18 → 1.0.19

package/src/runtime/document-navigation.ts

@@ -0,0 +1,564 @@
+/**
+ * Runtime-owned document navigation model.
+ *
+ * Derives the page stack, heading outline, and navigation context entirely
+ * from canonical document state and section properties.  DOM scroll position,
+ * CSS layout, and shell-local state are never consulted — the runtime is the
+ * source of pagination truth.
+ *
+ * This module owns read models only.  Section authoring commands live in
+ * `src/core/commands/section-layout-commands.ts` (owned by A3).
+ */
+
+import type {
+  DocumentHeadingSnapshot,
+  DocumentNavigationSnapshot,
+  DocumentPageSnapshot,
+  EditorStoryTarget,
+  EditorSurfaceSnapshot,
+  SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
+} from "../api/public-types";
+import type {
+  FootnoteCollection,
+} from "../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
+import { createSelectionSnapshot } from "../core/state/editor-state.ts";
+import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
+import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
+import {
+  estimateBlockHeight,
+  estimateParagraphHeight,
+  getUsableColumnMetrics,
+  getUsableColumnWidth,
+  getUsablePageHeight,
+} from "./page-layout-estimation.ts";
+import {
+  buildPageLayoutSnapshot,
+  buildResolvedSections,
+  findSectionForPosition as resolveSectionForPosition,
+  resolveSectionForStoryTarget,
+  type ResolvedDocumentSection,
+} from "./document-layout.ts";
+import { findNoteReferencePosition } from "./view-state.ts";
+
+const MIN_BLOCK_HEIGHT_TWIPS = 240;
+const FOOTNOTE_REFERENCE_RESERVATION_TWIPS = 180;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the full document navigation snapshot from canonical state.
+ *
+ * The page stack is derived from structured block layout, section geometry,
+ * and bounded pagination rules. DOM scroll position and CSS layout are never
+ * consulted.
+ */
+export function createDocumentNavigationSnapshot(
+  document: CanonicalDocumentEnvelope,
+  selectionHead: number,
+  activeStory: EditorStoryTarget,
+): DocumentNavigationSnapshot {
+  const mainSurface = createEditorSurfaceSnapshot(
+    document,
+    createSelectionSnapshot(0, 0),
+    MAIN_STORY_TARGET,
+  );
+
+  const sections = buildResolvedSections(document);
+  const pages = buildPageStack(document, sections, mainSurface);
+  const headings = buildHeadingOutline(document, mainSurface, sections, pages);
+  const navigationContext = resolveActiveNavigationContext(
+    document,
+    pages,
+    sections,
+    mainSurface,
+    selectionHead,
+    activeStory,
+  );
+
+  return {
+    pageCount: pages.length,
+    pages,
+    headings,
+    activePageIndex: navigationContext.activePageIndex,
+    activeSectionIndex: navigationContext.activeSectionIndex,
+  };
+}
+
+/**
+ * Find the page index that contains a given main-story character offset.
+ */
+export function findPageForOffset(
+  pages: readonly DocumentPageSnapshot[],
+  offset: number,
+): number {
+  for (let i = 0; i < pages.length; i++) {
+    if (offset < pages[i]!.endOffset) {
+      return i;
+    }
+  }
+  return Math.max(0, pages.length - 1);
+}
+
+/**
+ * Find the section index that contains a given main-story character offset.
+ */
+export function findSectionForOffset(
+  sections: readonly ResolvedDocumentSection[],
+  offset: number,
+): number {
+  return sections.length > 0 ? resolveSectionForPosition(sections, offset).index : 0;
+}
+
+function buildPageStack(
+  document: CanonicalDocumentEnvelope,
+  sections: ResolvedDocumentSection[],
+  mainSurface: EditorSurfaceSnapshot,
+): DocumentPageSnapshot[] {
+  const pages: DocumentPageSnapshot[] = [];
+  let globalPageIndex = 0;
+
+  for (const section of sections) {
+    const layout = buildPageLayoutSnapshot(
+      section.index,
+      section.properties ?? document.subParts?.finalSectionProperties,
+      document.subParts,
+    );
+    const sectionBlocks = collectSectionBlocks(mainSurface.blocks, section.start, section.end);
+    const paginated = paginateSectionBlocks(
+      section,
+      sectionBlocks,
+      layout,
+      document.subParts?.footnoteCollection,
+    );
+
+    for (const page of paginated) {
+      pages.push({
+        ...page,
+        pageIndex: globalPageIndex,
+      });
+      globalPageIndex += 1;
+    }
+  }
+
+  // Guarantee at least one page
+  if (pages.length === 0) {
+    pages.push({
+      pageIndex: 0,
+      sectionIndex: 0,
+      pageInSection: 0,
+      startOffset: 0,
+      endOffset: mainSurface.storySize,
+      layout: buildPageLayoutSnapshot(
+        0,
+        document.subParts?.finalSectionProperties,
+        document.subParts,
+      ),
+    });
+  }
+
+  return pages;
+}
+
+function collectSectionBlocks(
+  blocks: readonly SurfaceBlockSnapshot[],
+  start: number,
+  end: number,
+): SurfaceBlockSnapshot[] {
+  return blocks.filter((block) => block.to > start && block.from < end);
+}
+
+function paginateSectionBlocks(
+  section: ResolvedDocumentSection,
+  blocks: readonly SurfaceBlockSnapshot[],
+  layout: DocumentPageSnapshot["layout"],
+  footnotes: FootnoteCollection | undefined,
+): Omit<DocumentPageSnapshot, "pageIndex">[] {
+  if (blocks.length === 0) {
+    return [
+      {
+        sectionIndex: section.index,
+        pageInSection: 0,
+        startOffset: section.start,
+        endOffset: section.end,
+        layout,
+      },
+    ];
+  }
+
+  const pages: Omit<DocumentPageSnapshot, "pageIndex">[] = [];
+  const usableHeight = getUsablePageHeight(layout);
+  const columnMetrics = getUsableColumnMetrics(layout);
+  const maxColumns = Math.max(1, columnMetrics.length);
+  let pageStart = section.start;
+  let columnHeight = 0;
+  let columnIndex = 0;
+  let pageInSection = 0;
+  let reservedNoteHeight = 0;
+  const reservedNotes = new Set<string>();
+
+  const pushPage = (endOffset: number): void => {
+    const boundedEnd = Math.max(pageStart, Math.min(endOffset, section.end));
+    if (boundedEnd === pageStart && pages.length > 0) {
+      return;
+    }
+    pages.push({
+      sectionIndex: section.index,
+      pageInSection,
+      startOffset: pageStart,
+      endOffset: boundedEnd,
+      layout,
+    });
+    pageInSection += 1;
+    pageStart = boundedEnd;
+    columnHeight = 0;
+    columnIndex = 0;
+    reservedNoteHeight = 0;
+    reservedNotes.clear();
+  };
+
+  for (let index = 0; index < blocks.length; index += 1) {
+    const block = blocks[index]!;
+    const nextBoundary = blocks[index + 1]?.from ?? section.end;
+    while (true) {
+      const columnWidth =
+        columnMetrics[Math.min(columnIndex, columnMetrics.length - 1)]?.width ??
+        getUsableColumnWidth(layout);
+      const baseHeight = estimateBlockHeight(block, columnWidth);
+      const keepWithNextHeight =
+        block.kind === "paragraph" && block.keepNext
+          ? baseHeight + estimateBlockHeight(blocks[index + 1], columnWidth)
+          : baseHeight;
+      const noteHeight = estimateFootnoteReservation(block, footnotes, columnWidth, reservedNotes);
+      const projectedHeight = columnHeight + keepWithNextHeight + reservedNoteHeight + noteHeight;
+
+      if (block.kind === "paragraph" && block.pageBreakBefore && pageStart < block.from) {
+        pushPage(block.from);
+        continue;
+      }
+      if (projectedHeight > usableHeight && pageStart < block.from) {
+        if (columnIndex < maxColumns - 1) {
+          columnIndex += 1;
+          columnHeight = 0;
+          reservedNoteHeight = 0;
+          reservedNotes.clear();
+          continue;
+        }
+        pushPage(block.from);
+        continue;
+      }
+
+      const effectiveNoteHeight = estimateFootnoteReservation(
+        block,
+        footnotes,
+        columnWidth,
+        reservedNotes,
+      );
+      columnHeight += baseHeight;
+      reservedNoteHeight += effectiveNoteHeight;
+      currentPageNoteIds(block).forEach((noteKey) => reservedNotes.add(noteKey));
+
+      if (hasColumnBreak(block)) {
+        if (columnIndex < maxColumns - 1) {
+          columnIndex += 1;
+          columnHeight = 0;
+          reservedNoteHeight = 0;
+          reservedNotes.clear();
+        } else {
+          pushPage(nextBoundary);
+        }
+        break;
+      }
+
+      if (index === blocks.length - 1) {
+        pushPage(section.end);
+      }
+      break;
+    }
+  }
+
+  return pages.length > 0
+    ? pages
+    : [
+        {
+          sectionIndex: section.index,
+          pageInSection: 0,
+          startOffset: section.start,
+          endOffset: section.end,
+          layout,
+        },
+      ];
+}
+
+function resolveActiveNavigationContext(
+  document: CanonicalDocumentEnvelope,
+  pages: readonly DocumentPageSnapshot[],
+  sections: readonly ResolvedDocumentSection[],
+  mainSurface: EditorSurfaceSnapshot,
+  selectionHead: number,
+  activeStory: EditorStoryTarget,
+): { activePageIndex: number; activeSectionIndex: number } {
+  if (activeStory.kind === "main") {
+    const activePageIndex = findPageForOffset(pages, selectionHead);
+    return {
+      activePageIndex,
+      activeSectionIndex: pages[activePageIndex]?.sectionIndex ?? 0,
+    };
+  }
+
+  if (activeStory.kind === "header" || activeStory.kind === "footer") {
+    const section = resolveSectionForStoryTarget(document, sections, activeStory);
+    if (section) {
+      return {
+        activePageIndex: findFirstPageIndexForSection(pages, section.index),
+        activeSectionIndex: section.index,
+      };
+    }
+  }
+
+  if (activeStory.kind === "footnote" || activeStory.kind === "endnote") {
+    const referencePosition = findNoteReferencePosition(mainSurface, activeStory);
+    const activePageIndex = findPageForOffset(pages, referencePosition);
+    return {
+      activePageIndex,
+      activeSectionIndex:
+        pages[activePageIndex]?.sectionIndex ??
+        findSectionForOffset(sections, referencePosition),
+    };
+  }
+
+  return {
+    activePageIndex: 0,
+    activeSectionIndex: 0,
+  };
+}
+
+function findFirstPageIndexForSection(
+  pages: readonly DocumentPageSnapshot[],
+  sectionIndex: number,
+): number {
+  const match = pages.findIndex((page) => page.sectionIndex === sectionIndex);
+  return match >= 0 ? match : 0;
+}
+
+function estimateFootnoteReservation(
+  block: SurfaceBlockSnapshot,
+  footnotes: FootnoteCollection | undefined,
+  columnWidth: number,
+  reservedNotes: ReadonlySet<string>,
+): number {
+  if (!footnotes || block.kind !== "paragraph") {
+    return 0;
+  }
+
+  let reservation = 0;
+  for (const noteKey of currentPageNoteIds(block)) {
+    if (reservedNotes.has(noteKey)) {
+      continue;
+    }
+
+    const [noteKind, noteId] = noteKey.split(":");
+    const noteCollection =
+      noteKind === "endnote" ? footnotes.endnotes : footnotes.footnotes;
+    const note = noteCollection[noteId];
+    reservation += FOOTNOTE_REFERENCE_RESERVATION_TWIPS;
+    if (note) {
+      reservation += note.blocks.reduce(
+        (total, child) => total + estimateCanonicalNoteBlockHeight(child, columnWidth),
+        0,
+      );
+    }
+  }
+
+  return reservation;
+}
+
+function estimateCanonicalNoteBlockHeight(
+  block: FootnoteCollection["footnotes"][string]["blocks"][number],
+  columnWidth: number,
+): number {
+  switch (block.type) {
+    case "paragraph":
+      return estimateParagraphHeight(
+        {
+          blockId: "note",
+          kind: "paragraph",
+          from: 0,
+          to: 0,
+          ...(block.styleId ? { styleId: block.styleId } : {}),
+          segments: createEstimatedNoteSegments(block.children),
+        },
+        columnWidth,
+      );
+    case "table":
+      return MIN_BLOCK_HEIGHT_TWIPS * Math.max(1, block.rows.length);
+    default:
+      return MIN_BLOCK_HEIGHT_TWIPS;
+  }
+}
+
+function createEstimatedNoteSegments(
+  children: Extract<FootnoteCollection["footnotes"][string]["blocks"][number], { type: "paragraph" }>["children"],
+): SurfaceInlineSegment[] {
+  const segments: SurfaceInlineSegment[] = [];
+
+  children.forEach((child, index) => {
+    if (child.type === "text") {
+      segments.push({
+        segmentId: `note-${index}`,
+        kind: "text",
+        from: 0,
+        to: Array.from(child.text).length,
+        text: child.text,
+      });
+      return;
+    }
+
+    if (child.type === "hard_break" || child.type === "tab") {
+      segments.push({
+        segmentId: `note-${index}`,
+        kind: child.type,
+        from: 0,
+        to: 1,
+      });
+    }
+  });
+
+  return segments;
+}
+
+function currentPageNoteIds(
+  block: SurfaceBlockSnapshot,
+): Set<string> {
+  const notes = new Set<string>();
+  if (block.kind !== "paragraph") {
+    return notes;
+  }
+
+  for (const segment of block.segments) {
+    if (segment.kind === "note_ref" && segment.noteId) {
+      notes.add(`${segment.noteKind}:${segment.noteId}`);
+    }
+  }
+  return notes;
+}
+
+function hasColumnBreak(block: SurfaceBlockSnapshot): boolean {
+  return block.kind === "paragraph" && block.segments.some(
+    (segment) =>
+      segment.kind === "opaque_inline" &&
+      segment.label === "Column break",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Heading outline
+// ---------------------------------------------------------------------------
+
+/** Style IDs that map to heading levels by convention. */
+const HEADING_STYLE_PATTERN = /^heading\s*(\d+)$/i;
+
+function headingLevelFromStyleId(styleId?: string): number | null {
+  if (!styleId) return null;
+  const match = HEADING_STYLE_PATTERN.exec(styleId);
+  if (match) {
+    const level = parseInt(match[1]!, 10);
+    return level >= 1 && level <= 9 ? level : null;
+  }
+  return null;
+}
+
+function buildHeadingOutline(
+  document: CanonicalDocumentEnvelope,
+  mainSurface: EditorSurfaceSnapshot,
+  sections: ResolvedDocumentSection[],
+  pages: DocumentPageSnapshot[],
+): DocumentHeadingSnapshot[] {
+  const headings: DocumentHeadingSnapshot[] = [];
+
+  for (const block of mainSurface.blocks) {
+    if (block.kind !== "paragraph") continue;
+
+    // Check explicit outlineLevel first, then style-based heading detection
+    const outlineLevel = block.outlineLevel;
+    const styleLevel = resolveHeadingLevelFromStyle(document, block.styleId);
+    const level =
+      outlineLevel !== undefined && outlineLevel >= 0
+        ? outlineLevel + 1
+        : styleLevel;
+
+    if (level === null) continue;
+
+    const text = extractParagraphText(block);
+    if (!text.trim()) continue;
+
+    const offset = block.from;
+    const pageIndex = findPageForOffset(pages, offset);
+    const sectionIndex = findSectionForOffset(sections, offset);
+
+    headings.push({
+      headingId: `heading-${block.blockId}-${offset}`,
+      level,
+      text: text.trim(),
+      offset,
+      pageIndex,
+      sectionIndex,
+    });
+  }
+
+  return headings;
+}
+
+function resolveHeadingLevelFromStyle(
+  document: CanonicalDocumentEnvelope,
+  styleId?: string,
+): number | null {
+  if (!styleId) {
+    return null;
+  }
+
+  const visited = new Set<string>();
+  let currentStyleId: string | undefined = styleId;
+  while (currentStyleId && !visited.has(currentStyleId)) {
+    visited.add(currentStyleId);
+    const style:
+      | { outlineLevel?: number; basedOn?: string }
+      | undefined = document.styles.paragraphs[currentStyleId];
+    if (!style) {
+      break;
+    }
+    if (
+      typeof style.outlineLevel === "number" &&
+      style.outlineLevel >= 0 &&
+      style.outlineLevel <= 8
+    ) {
+      return style.outlineLevel + 1;
+    }
+    currentStyleId = style.basedOn;
+  }
+
+  return headingLevelFromStyleId(styleId);
+}
+
+function extractParagraphText(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): string {
+  let text = "";
+  for (const segment of block.segments) {
+    switch (segment.kind) {
+      case "text":
+        text += segment.text;
+        break;
+      case "tab":
+        text += "\t";
+        break;
+      case "hard_break":
+        text += "\n";
+        break;
+    }
+  }
+  return text;
+}