@plannotator/ui 0.54.0 → 0.55.0

package/utils/annotationHelpers.ts

@@ -60,13 +60,41 @@ export interface TocItem {
   annotationCount: number;
 }
 
+/**
+ * The headings a Contents list shows, in document order: levels 1 to
+ * `maxLevel` (3 by default, plan review's list). The one place that picks
+ * them: `TableOfContents`, plan review's "has entries" check and the contents
+ * rail (`MarkdownContentsRail`, levels 1 to 4) all read it.
+ */
+export function tocHeadings(blocks: readonly Block[], maxLevel = 3): Block[] {
+  return blocks
+    .filter(b => b.type === 'heading' && (b.level ?? 0) <= maxLevel)
+    .sort((a, b) => a.order - b.order);
+}
+
+/** The contents rail lists headings of levels 1 to this (`MarkdownContentsRail`). */
+export const CONTENTS_RAIL_MAX_LEVEL = 4;
+/** The contents rail shows for a document with at least this many of them. */
+export const CONTENTS_RAIL_MIN_HEADINGS = 4;
+/** The contents rail shows in a scroll element at least this wide (and with a 68 px gutter). */
+export const CONTENTS_RAIL_MIN_PANE_WIDTH = 480;
+
+/**
+ * Whether a document gets the contents rail: at least
+ * `CONTENTS_RAIL_MIN_HEADINGS` headings of levels 1 to
+ * `CONTENTS_RAIL_MAX_LEVEL`. Kept out of the rail's own module, so a host can
+ * decide without loading the (lazy) rail.
+ */
+export function hasContentsRailHeadings(blocks: readonly Block[]): boolean {
+  return tocHeadings(blocks, CONTENTS_RAIL_MAX_LEVEL).length >= CONTENTS_RAIL_MIN_HEADINGS;
+}
+
 export function buildTocHierarchy(
   blocks: Block[],
-  annotationCounts: Map<string, number>
+  annotationCounts: Map<string, number>,
+  maxLevel = 3
 ): TocItem[] {
-  const headings = blocks
-    .filter(b => b.type === 'heading' && (b.level ?? 0) <= 3)
-    .sort((a, b) => a.order - b.order);
+  const headings = tocHeadings(blocks, maxLevel);
   
   const root: TocItem[] = [];
   const stack: TocItem[] = [];

package/utils/blockParse.ts

@@ -0,0 +1,45 @@
+// Moved from the Workspaces app's `block-parse.ts` with its contents rail
+// (MarkdownContentsRail, approved 2026-10-03). Port: none; the module-level
+// cache is the same.
+
+import type { Block } from '../types';
+import { parseMarkdownToBlocks } from './parser';
+
+/**
+ * ONE parse per document body, shared across consumers: a host's Viewer and
+ * its contents rail render from the same body string, and each would
+ * otherwise run its own full `parseMarkdownToBlocks`. This module-level cache
+ * keys on the content string (value equality: the call sites derive `content`
+ * independently via `extractFrontmatter`), so whoever parses first feeds
+ * everyone.
+ *
+ * Sharing one blocks array is safe: the consumers treat the parser output as
+ * immutable.
+ *
+ * Capacity 4 with hit-refresh recency: a page holds at most a couple of live
+ * bodies at once; the cap only exists so navigating across documents cannot
+ * grow it without bound.
+ */
+const MAX_ENTRIES = 4;
+const cache = new Map<string, Block[]>();
+
+/** Test probe: counts real parses (cache misses). */
+export const blockParseProbe = { parses: 0 };
+
+export function parseBlocksShared(content: string): Block[] {
+  const hit = cache.get(content);
+  if (hit !== undefined) {
+    // Refresh recency (Map preserves insertion order; oldest is evicted).
+    cache.delete(content);
+    cache.set(content, hit);
+    return hit;
+  }
+  blockParseProbe.parses += 1;
+  const blocks = parseMarkdownToBlocks(content);
+  cache.set(content, blocks);
+  if (cache.size > MAX_ENTRIES) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== undefined) cache.delete(oldest);
+  }
+  return blocks;
+}

package/utils/headingScrollSpy.ts

@@ -0,0 +1,92 @@
+/**
+ * The contents rail's scroll-spy: which heading is being read, from the
+ * headings' cached tops and the scroll position, on every scroll frame.
+ *
+ * Moved as it was from the Workspaces app's
+ * `apps/web/src/plannotator/MarkdownContentsRail.tsx` (approved 2026-10-03):
+ * `topInsideViewport`, `currentBinding` (the binary search) and the rule that
+ * the last heading is the current one at the document's end. One change: the
+ * activation line is 80 px below the top (it was 52), plan review's
+ * `TableOfContents` scroll offset, so a pick lands where plan review's does.
+ *
+ * Plan review's own list keeps `hooks/useActiveSection` (an
+ * IntersectionObserver band). One mechanism per surface: the rail, and a
+ * Contents list on the rail's surface (`DocumentContents`), use this one.
+ */
+
+/** How far below the scroll element's top a heading becomes the current one. */
+export const CONTENTS_ACTIVATION_OFFSET = 80;
+
+/** A heading drawn in the scroll element, with its top inside the scrolled content. */
+export interface HeadingBinding {
+  /** The heading's index in the caller's own list. */
+  readonly itemIndex: number;
+  readonly node: HTMLElement;
+  readonly top: number;
+}
+
+export function topInsideViewport(node: HTMLElement, viewport: HTMLElement): number {
+  const viewportRect = viewport.getBoundingClientRect();
+  return node.getBoundingClientRect().top - viewportRect.top + viewport.scrollTop;
+}
+
+/**
+ * Bind each listed heading id to its drawn heading (`[data-block-type="heading"]`
+ * with that `data-block-id`), sorted by top. Only the caller's own ids are
+ * bound, so a heading of an embedded document (its ids are namespaced) is never
+ * read; when an id is drawn twice, the first one in document order is.
+ */
+export function bindHeadings(
+  viewport: HTMLElement,
+  blockIds: readonly string[],
+): HeadingBinding[] {
+  const nodesByBlockId = new Map<string, HTMLElement>();
+  for (const node of viewport.querySelectorAll<HTMLElement>('[data-block-type="heading"]')) {
+    const id = node.dataset.blockId ?? '';
+    if (!nodesByBlockId.has(id)) nodesByBlockId.set(id, node);
+  }
+  const bindings = blockIds.flatMap<HeadingBinding>((blockId, itemIndex) => {
+    const node = nodesByBlockId.get(blockId);
+    return node === undefined ? [] : [{ itemIndex, node, top: topInsideViewport(node, viewport) }];
+  });
+  bindings.sort((left, right) => left.top - right.top);
+  return bindings;
+}
+
+/** The last binding whose top is at or above `activationTop`, else the first. */
+export function currentBinding(
+  bindings: readonly HeadingBinding[],
+  activationTop: number,
+): HeadingBinding {
+  let low = 0;
+  let high = bindings.length - 1;
+  let result = bindings[0]!;
+  while (low <= high) {
+    const middle = (low + high) >> 1;
+    const candidate = bindings[middle]!;
+    if (candidate.top <= activationTop) {
+      result = candidate;
+      low = middle + 1;
+    } else {
+      high = middle - 1;
+    }
+  }
+  return result;
+}
+
+/**
+ * The heading being read: the last one at or above the activation line, or
+ * the last heading once the document is scrolled to its end. `null` with no
+ * bindings.
+ */
+export function activeHeadingBinding(
+  bindings: readonly HeadingBinding[],
+  viewport: HTMLElement,
+): HeadingBinding | null {
+  if (bindings.length === 0) return null;
+  const maxScrollTop = Math.max(0, viewport.scrollHeight - viewport.clientHeight);
+  const atDocumentEnd = maxScrollTop > 0 && viewport.scrollTop >= maxScrollTop - 1;
+  return atDocumentEnd
+    ? bindings.at(-1)!
+    : currentBinding(bindings, viewport.scrollTop + CONTENTS_ACTIVATION_OFFSET);
+}