@beyondwork/docx-react-component 1.0.81 → 1.0.82

package/src/ui-tailwind/page-stack/use-visible-block-range.ts

@@ -15,9 +15,10 @@ const ESTIMATED_BLOCKS_PER_PAGE_FALLBACK = 50;
  * rendered in PM as "real" (non-placeholder) blocks.
  *
  * Sources of truth:
- * 1. IntersectionObserver on `[data-page-frame]` markers in the PM DOM.
- * 2. Selection head block-index — always included (selection-guard).
- * 3. Overscan — ±N pages around the visible set to avoid jank when scrolling.
+ * 1. Warm path: geometry page frames + layout page offsets.
+ * 2. Degraded path: IntersectionObserver on `[data-page-frame]` markers.
+ * 3. Selection head block-index — always included (selection-guard).
+ * 4. Overscan — ±N pages around the visible set to avoid jank when scrolling.
  *
  * Contract: the hook returns a **list of disjoint intervals**, not a single
  * contiguous range. When the caret is far off-screen the hook emits the
@@ -60,6 +61,21 @@ export interface VisiblePageIndexRange {
   end: number; // exclusive
 }
 
+export interface PageFrameForVisibility {
+  topPx: number;
+  heightPx: number;
+}
+
+export interface PageOffsetsForVisibility {
+  startOffset: number;
+  endOffset: number;
+}
+
+export interface BlockOffsetsForVisibility {
+  from: number;
+  to: number;
+}
+
 function readBlockIndex(el: HTMLElement, attr: string): number | null {
   const v = el.getAttribute(attr);
   if (v === null) return null;
@@ -67,6 +83,309 @@ function readBlockIndex(el: HTMLElement, attr: string): number | null {
   return Number.isFinite(n) ? n : null;
 }
 
+function clampPageRange(
+  range: VisiblePageIndexRange,
+  pageCount: number,
+): VisiblePageIndexRange | null {
+  const start = Math.max(0, Math.min(range.start, pageCount));
+  const end = Math.max(start, Math.min(range.end, pageCount));
+  return start < end ? { start, end } : null;
+}
+
+function initialLoadRange(totalBlockCount: number, overscanPages: number): readonly BlockRange[] {
+  const initialEnd = Math.min(
+    totalBlockCount,
+    (overscanPages * 2 + 1) * ESTIMATED_BLOCKS_PER_PAGE_FALLBACK,
+  );
+  return initialEnd > 0 ? [{ start: 0, end: initialEnd }] : [];
+}
+
+function resolveBlockRangeForPageRange(input: {
+  pageMarkers: readonly HTMLElement[];
+  visiblePageIndexRange: VisiblePageIndexRange;
+  totalBlockCount: number;
+}): BlockRange | null {
+  const { pageMarkers, visiblePageIndexRange, totalBlockCount } = input;
+  const normalized = clampPageRange(visiblePageIndexRange, pageMarkers.length);
+  if (!normalized) return null;
+
+  let minBlock = Infinity;
+  let maxBlock = -Infinity;
+  for (let pageIndex = normalized.start; pageIndex < normalized.end; pageIndex += 1) {
+    const marker = pageMarkers[pageIndex];
+    if (!marker) continue;
+    const first = readBlockIndex(marker, "data-page-first-block-index");
+    const last = readBlockIndex(marker, "data-page-last-block-index");
+    if (first !== null) minBlock = Math.min(minBlock, first);
+    if (last !== null) maxBlock = Math.max(maxBlock, last + 1);
+  }
+
+  if (minBlock === Infinity) return null;
+  const range = {
+    start: Math.max(0, minBlock),
+    end: Math.min(totalBlockCount, maxBlock),
+  };
+  return range.end > range.start ? range : null;
+}
+
+function resolveSelectionRange(input: {
+  pageMarkers: readonly HTMLElement[];
+  selectionBlockIndex: number;
+  totalBlockCount: number;
+}): BlockRange {
+  const { pageMarkers, selectionBlockIndex, totalBlockCount } = input;
+  let selStart = selectionBlockIndex;
+  let selEnd = selectionBlockIndex + 1;
+  for (const marker of pageMarkers) {
+    const first = readBlockIndex(marker, "data-page-first-block-index");
+    const last = readBlockIndex(marker, "data-page-last-block-index");
+    if (
+      first !== null &&
+      last !== null &&
+      selectionBlockIndex >= first &&
+      selectionBlockIndex <= last
+    ) {
+      selStart = first;
+      selEnd = last + 1;
+      break;
+    }
+  }
+  return {
+    start: Math.max(0, selStart),
+    end: Math.min(totalBlockCount, selEnd),
+  };
+}
+
+function resolveBlockRangeFromOffsetSpan(input: {
+  blocks: readonly BlockOffsetsForVisibility[];
+  startOffset: number;
+  endOffset: number;
+  totalBlockCount: number;
+}): BlockRange | null {
+  const { blocks, startOffset, endOffset, totalBlockCount } = input;
+  if (endOffset <= startOffset) return null;
+
+  let first = -1;
+  let last = -1;
+  const scanCount = Math.min(blocks.length, totalBlockCount);
+  for (let index = 0; index < scanCount; index += 1) {
+    const block = blocks[index];
+    if (!block) continue;
+    if (block.from >= endOffset) break;
+    if (block.from >= startOffset && block.from < endOffset) {
+      if (first < 0) first = index;
+      last = index;
+    }
+  }
+  if (first < 0 || last < first) return null;
+  return { start: first, end: last + 1 };
+}
+
+function resolveSelectionRangeFromPageOffsets(input: {
+  blocks: readonly BlockOffsetsForVisibility[];
+  pageCount: number;
+  getPageOffsets: (pageIndex: number) => PageOffsetsForVisibility | null;
+  selectionBlockIndex: number;
+  totalBlockCount: number;
+}): BlockRange {
+  const {
+    blocks,
+    pageCount,
+    getPageOffsets,
+    selectionBlockIndex,
+    totalBlockCount,
+  } = input;
+  const selectionBlock = blocks[selectionBlockIndex];
+  if (!selectionBlock) {
+    return {
+      start: Math.max(0, selectionBlockIndex),
+      end: Math.min(totalBlockCount, selectionBlockIndex + 1),
+    };
+  }
+
+  for (let pageIndex = 0; pageIndex < pageCount; pageIndex += 1) {
+    const page = getPageOffsets(pageIndex);
+    if (!page) continue;
+    if (selectionBlock.from >= page.startOffset && selectionBlock.from < page.endOffset) {
+      const pageRange = resolveBlockRangeFromOffsetSpan({
+        blocks,
+        startOffset: page.startOffset,
+        endOffset: page.endOffset,
+        totalBlockCount,
+      });
+      if (pageRange) return pageRange;
+      break;
+    }
+  }
+
+  return {
+    start: Math.max(0, selectionBlockIndex),
+    end: Math.min(totalBlockCount, selectionBlockIndex + 1),
+  };
+}
+
+function withSelectionGuard(input: {
+  viewportRange: BlockRange;
+  selectionBlockIndex: number | null;
+  resolveSelectionRange: (selectionBlockIndex: number) => BlockRange;
+}): readonly BlockRange[] {
+  const {
+    viewportRange,
+    selectionBlockIndex,
+    resolveSelectionRange: resolveSelectionRangeForIndex,
+  } = input;
+  if (
+    selectionBlockIndex === null ||
+    (selectionBlockIndex >= viewportRange.start && selectionBlockIndex < viewportRange.end)
+  ) {
+    return viewportRange.end > viewportRange.start ? [viewportRange] : [];
+  }
+
+  const selectionRange = resolveSelectionRangeForIndex(selectionBlockIndex);
+  if (selectionRange.end <= selectionRange.start) {
+    return viewportRange.end > viewportRange.start ? [viewportRange] : [];
+  }
+
+  return selectionRange.start < viewportRange.start
+    ? [selectionRange, viewportRange]
+    : [viewportRange, selectionRange];
+}
+
+export function resolveVisibleBlockRangesFromPageRange(input: {
+  pageMarkers: readonly HTMLElement[];
+  visiblePageIndexRange: VisiblePageIndexRange;
+  selectionBlockIndex: number | null;
+  totalBlockCount: number;
+}): readonly BlockRange[] | null {
+  if (input.totalBlockCount <= 0) return [];
+  const viewportRange = resolveBlockRangeForPageRange(input);
+  if (!viewportRange) return null;
+  return withSelectionGuard({
+    viewportRange,
+    selectionBlockIndex: input.selectionBlockIndex,
+    resolveSelectionRange: (selectionBlockIndex) =>
+      resolveSelectionRange({
+        pageMarkers: input.pageMarkers,
+        selectionBlockIndex,
+        totalBlockCount: input.totalBlockCount,
+      }),
+  });
+}
+
+export function resolveVisibleBlockRangesFromPageOffsets(input: {
+  blocks: readonly BlockOffsetsForVisibility[];
+  pageCount: number;
+  visiblePageIndexRange: VisiblePageIndexRange;
+  selectionBlockIndex: number | null;
+  totalBlockCount: number;
+  getPageOffsets: (pageIndex: number) => PageOffsetsForVisibility | null;
+}): readonly BlockRange[] | null {
+  const {
+    blocks,
+    pageCount,
+    visiblePageIndexRange,
+    selectionBlockIndex,
+    totalBlockCount,
+    getPageOffsets,
+  } = input;
+  if (totalBlockCount <= 0) return [];
+  const normalized = clampPageRange(visiblePageIndexRange, pageCount);
+  if (!normalized) return null;
+
+  let startOffset = Infinity;
+  let endOffset = -Infinity;
+  for (let pageIndex = normalized.start; pageIndex < normalized.end; pageIndex += 1) {
+    const page = getPageOffsets(pageIndex);
+    if (!page) continue;
+    if (page.endOffset <= page.startOffset) continue;
+    startOffset = Math.min(startOffset, page.startOffset);
+    endOffset = Math.max(endOffset, page.endOffset);
+  }
+
+  if (startOffset === Infinity || endOffset <= startOffset) return null;
+  const viewportRange = resolveBlockRangeFromOffsetSpan({
+    blocks,
+    startOffset,
+    endOffset,
+    totalBlockCount,
+  });
+  if (!viewportRange) return null;
+
+  return withSelectionGuard({
+    viewportRange,
+    selectionBlockIndex,
+    resolveSelectionRange: (selectionBlockIndexForGuard) =>
+      resolveSelectionRangeFromPageOffsets({
+        blocks,
+        pageCount,
+        getPageOffsets,
+        selectionBlockIndex: selectionBlockIndexForGuard,
+        totalBlockCount,
+      }),
+  });
+}
+
+export function resolveVisiblePageIndexRangeFromViewport(input: {
+  pageCount: number;
+  viewportTopPx: number;
+  viewportHeightPx: number;
+  overscanPages: number;
+  getPageFrame: (pageIndex: number) => PageFrameForVisibility | null;
+}): VisiblePageIndexRange | null {
+  const { pageCount, viewportTopPx, viewportHeightPx, overscanPages, getPageFrame } = input;
+  if (pageCount <= 0 || viewportHeightPx <= 0) return null;
+
+  const viewportBottomPx = viewportTopPx + viewportHeightPx;
+  let firstVisible = Infinity;
+  let lastVisible = -Infinity;
+  let nearestPageAfterViewport = -1;
+  let nearestPageAfterDistance = Infinity;
+  let lastPageBeforeViewport = -1;
+  let lastPageBeforeDistance = Infinity;
+
+  for (let pageIndex = 0; pageIndex < pageCount; pageIndex += 1) {
+    const frame = getPageFrame(pageIndex);
+    if (!frame) continue;
+    const pageTopPx = frame.topPx;
+    const pageBottomPx = frame.topPx + frame.heightPx;
+    if (pageBottomPx >= viewportTopPx && pageTopPx <= viewportBottomPx) {
+      firstVisible = Math.min(firstVisible, pageIndex);
+      lastVisible = Math.max(lastVisible, pageIndex);
+    }
+    if (pageBottomPx < viewportTopPx) {
+      lastPageBeforeViewport = pageIndex;
+      lastPageBeforeDistance = viewportTopPx - pageBottomPx;
+    } else if (nearestPageAfterViewport < 0 && pageTopPx > viewportBottomPx) {
+      nearestPageAfterViewport = pageIndex;
+      nearestPageAfterDistance = pageTopPx - viewportBottomPx;
+    }
+  }
+
+  if (firstVisible === Infinity) {
+    const fallbackPage =
+      nearestPageAfterViewport >= 0 && lastPageBeforeViewport >= 0
+        ? nearestPageAfterDistance < lastPageBeforeDistance
+          ? nearestPageAfterViewport
+          : lastPageBeforeViewport
+        : nearestPageAfterViewport >= 0
+          ? nearestPageAfterViewport
+          : lastPageBeforeViewport >= 0
+            ? lastPageBeforeViewport
+            : -1;
+    if (fallbackPage < 0) return null;
+    firstVisible = fallbackPage;
+    lastVisible = fallbackPage;
+  }
+
+  return clampPageRange(
+    {
+      start: firstVisible - overscanPages,
+      end: lastVisible + overscanPages + 1,
+    },
+    pageCount,
+  );
+}
+
 /**
  * Multi-interval hook. Returns the list of non-overlapping block-index
  * intervals that should be real in the surface projection. Typical output:
@@ -121,8 +440,7 @@ export function useVisibleBlockRanges(input: VisibleBlockRangeInput): readonly B
     if (totalBlockCount <= 0) return [];
     if (visiblePages.size === 0 && selectionBlockIndex === null) {
       // No visibility signal yet — return initial-load window (first 2 × overscanPages worth).
-      const initialEnd = Math.min(totalBlockCount, (overscanPages * 2 + 1) * ESTIMATED_BLOCKS_PER_PAGE_FALLBACK);
-      return initialEnd > 0 ? [{ start: 0, end: initialEnd }] : [];
+      return initialLoadRange(totalBlockCount, overscanPages);
     }
 
     // Expand visiblePages by ±overscanPages.
@@ -158,48 +476,20 @@ export function useVisibleBlockRanges(input: VisibleBlockRangeInput): readonly B
     // to cover the gap. On long documents with the caret far from the
     // viewport this avoids realizing the entire gap as real blocks (the
     // pre-fix behavior that dominated steady-state scroll cost).
-    if (
-      selectionBlockIndex === null ||
-      (selectionBlockIndex >= viewportRange.start &&
-        selectionBlockIndex < viewportRange.end)
-    ) {
-      return viewportRange.end > viewportRange.start ? [viewportRange] : [];
-    }
-
-    // Resolve the page that contains the selection.
-    let selStart = selectionBlockIndex;
-    let selEnd = selectionBlockIndex + 1;
-    for (const marker of pageMarkers) {
-      const first = readBlockIndex(marker, "data-page-first-block-index");
-      const last = readBlockIndex(marker, "data-page-last-block-index");
-      if (
-        first !== null &&
-        last !== null &&
-        selectionBlockIndex >= first &&
-        selectionBlockIndex <= last
-      ) {
-        selStart = first;
-        selEnd = last + 1;
-        break;
-      }
-    }
-    const selectionRange: BlockRange = {
-      start: Math.max(0, selStart),
-      end: Math.min(totalBlockCount, selEnd),
-    };
-    if (selectionRange.end <= selectionRange.start) {
-      return viewportRange.end > viewportRange.start ? [viewportRange] : [];
-    }
-
     // Sort ascending by `start` so the facet layer sees a canonical order
     // and can dedupe with a simple serialization. Runtime's
     // `normalizeViewportRanges` merges touching/overlapping intervals, so
     // we don't need to handle that here.
-    const ranges: BlockRange[] =
-      selectionRange.start < viewportRange.start
-        ? [selectionRange, viewportRange]
-        : [viewportRange, selectionRange];
-    return ranges;
+    return withSelectionGuard({
+      viewportRange,
+      selectionBlockIndex,
+      resolveSelectionRange: (selectionBlockIndexForGuard) =>
+        resolveSelectionRange({
+          pageMarkers,
+          selectionBlockIndex: selectionBlockIndexForGuard,
+          totalBlockCount,
+        }),
+    });
   }, [visiblePages, selectionBlockIndex, pageMarkers, overscanPages, totalBlockCount]);
 }