@beyondwork/docx-react-component 1.0.27 → 1.0.29

package/src/runtime/document-navigation.ts

@@ -1,603 +0,0 @@
-/**
- * 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;
-
-interface NavigationBaseSnapshot {
-  mainSurface: EditorSurfaceSnapshot;
-  sections: ResolvedDocumentSection[];
-  pages: DocumentPageSnapshot[];
-  headings: DocumentHeadingSnapshot[];
-}
-
-const navigationBaseCache = new WeakMap<
-  CanonicalDocumentEnvelope["content"],
-  NavigationBaseSnapshot & {
-    styles: CanonicalDocumentEnvelope["styles"];
-    subParts: CanonicalDocumentEnvelope["subParts"];
-  }
->();
-
-// ---------------------------------------------------------------------------
-// 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 base = getNavigationBaseSnapshot(document);
-  const navigationContext = resolveActiveNavigationContext(
-    document,
-    base.pages,
-    base.sections,
-    base.mainSurface,
-    selectionHead,
-    activeStory,
-  );
-
-  return {
-    pageCount: base.pages.length,
-    pages: base.pages,
-    headings: base.headings,
-    activePageIndex: navigationContext.activePageIndex,
-    activeSectionIndex: navigationContext.activeSectionIndex,
-  };
-}
-
-function getNavigationBaseSnapshot(
-  document: CanonicalDocumentEnvelope,
-): NavigationBaseSnapshot {
-  const cached = navigationBaseCache.get(document.content);
-  if (
-    cached &&
-    cached.styles === document.styles &&
-    cached.subParts === document.subParts
-  ) {
-    return cached;
-  }
-
-  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 next = {
-    mainSurface,
-    sections,
-    pages,
-    headings,
-    styles: document.styles,
-    subParts: document.subParts,
-  };
-  navigationBaseCache.set(document.content, next);
-  return next;
-}
-
-/**
- * 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;
-}