@opengeni/react 3.1.0 → 3.1.2

package/src/components/timeline-annotation-chrome.tsx

@@ -0,0 +1,196 @@
+import type {
+  DraftTimelineAnnotation,
+  TimelineAnnotation,
+  TimelineAnnotationSource,
+} from "@opengeni/sdk";
+import { useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { annotationNoteNeedsDisclosure } from "./timeline-annotation-layout";
+import { useTimelineAnnotationSourceRoot } from "./timeline-annotation-reveal-context";
+import {
+  annotationSourceLabel,
+  revealLoadedAnnotationSource,
+  truncateAnnotationQuote,
+} from "./timeline-annotation-shared";
+
+export type TimelineAnnotationLike = DraftTimelineAnnotation | TimelineAnnotation;
+
+const NOTE_MAX_HEIGHT_PX = 160;
+
+function autosizeNote(textarea: HTMLTextAreaElement | null): void {
+  if (!textarea) return;
+  textarea.style.height = "auto";
+  textarea.style.height = `${Math.min(Math.max(textarea.scrollHeight, 32), NOTE_MAX_HEIGHT_PX)}px`;
+}
+
+function quotePreview(quote: string): { text: string; multiline: boolean } {
+  const trimmed = quote.trim();
+  const multiline = trimmed.includes("\n");
+  return {
+    text: multiline ? trimmed : trimmed.replace(/\s+/g, " "),
+    multiline,
+  };
+}
+
+export function AnnotationQuoteSourceButton({
+  annotation,
+  lines = 2,
+  onRevealSource,
+  onUnavailable,
+}: {
+  annotation: TimelineAnnotationLike;
+  lines?: 2 | 3;
+  onRevealSource?: ((source: TimelineAnnotationSource) => boolean) | undefined;
+  onUnavailable: (id: string | null) => void;
+}) {
+  const preview = quotePreview(annotation.quote);
+  const sourceLabel = annotationSourceLabel(annotation.source);
+  const sourceRoot = useTimelineAnnotationSourceRoot();
+  return (
+    <button
+      type="button"
+      title={annotation.quote}
+      aria-label={`View ${sourceLabel} source: ${truncateAnnotationQuote(annotation.quote, 88)}`}
+      className="block w-full min-w-0 rounded-sm border-0 bg-transparent text-left text-og-sm leading-5 text-og-fg-muted outline-hidden transition-colors hover:text-og-fg focus-visible:ring-2 focus-visible:ring-og-accent pointer-coarse:min-h-[44px]"
+      onClick={() => {
+        const revealed =
+          onRevealSource?.(annotation.source) ??
+          (sourceRoot
+            ? revealLoadedAnnotationSource(annotation.source, sourceRoot.current)
+            : revealLoadedAnnotationSource(annotation.source));
+        onUnavailable(revealed ? null : annotation.id);
+      }}
+    >
+      <span
+        className={cn(
+          "block min-w-0 max-w-full break-words",
+          preview.multiline ? "whitespace-pre-wrap" : "whitespace-normal",
+          lines === 3 ? "line-clamp-3" : "line-clamp-2",
+        )}
+      >
+        {preview.text}
+      </span>
+      <span className="sr-only"> view source</span>
+    </button>
+  );
+}
+
+export function AnnotationAccentRow({
+  children,
+  className,
+}: {
+  children: ReactNode;
+  className?: string | undefined;
+}) {
+  return (
+    <div className={cn("flex gap-2.5", className)}>
+      <div aria-hidden="true" className="w-0.5 shrink-0 rounded-full bg-og-accent/55" />
+      <div className="min-w-0 flex-1">{children}</div>
+    </div>
+  );
+}
+
+export function AnnotationNotePreview({
+  note,
+  annotationId,
+  ordinal,
+  className,
+}: {
+  note: string;
+  annotationId: string;
+  ordinal: number;
+  className?: string | undefined;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  if (!note) return null;
+  const collapsible = annotationNoteNeedsDisclosure(note);
+  const contentId = `og-annotation-note-${annotationId}`;
+  return (
+    <div className={className}>
+      <p
+        id={contentId}
+        data-og-annotation-note=""
+        data-og-annotation-note-expanded={expanded ? "true" : "false"}
+        className={cn(
+          "mt-0.5 break-words whitespace-pre-wrap text-og-sm leading-5 text-og-fg",
+          !expanded && "line-clamp-4",
+        )}
+      >
+        {note}
+      </p>
+      {collapsible ? (
+        <button
+          type="button"
+          className="mt-0.5 inline-flex min-h-7 items-center rounded-og-sm px-1 text-og-xs font-medium text-og-fg-muted outline-hidden hover:text-og-fg focus-visible:ring-2 focus-visible:ring-og-accent pointer-coarse:min-h-11"
+          aria-expanded={expanded}
+          aria-controls={contentId}
+          aria-label={
+            expanded ? `Show less annotation ${ordinal}` : `Show more annotation ${ordinal}`
+          }
+          onClick={() => setExpanded((current) => !current)}
+        >
+          {expanded ? "Show less" : "Show more"}
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+export function AnnotationNoteField({
+  annotation,
+  inputRef,
+  onUpdate,
+  onCommit,
+}: {
+  annotation: TimelineAnnotationLike;
+  inputRef?: ((node: HTMLTextAreaElement | null) => void) | undefined;
+  onUpdate: (id: string, note: string) => void;
+  onCommit?: (() => void) | undefined;
+}) {
+  const localRef = useRef<HTMLTextAreaElement | null>(null);
+  const setRef = (node: HTMLTextAreaElement | null) => {
+    localRef.current = node;
+    inputRef?.(node);
+  };
+
+  useLayoutEffect(() => {
+    const textarea = localRef.current;
+    if (!textarea) return;
+    // Ref callbacks can reattach on every scroll-driven parent render. Reflowing
+    // unchanged notes there interrupts native scrolling, particularly in WebKit.
+    autosizeNote(textarea);
+    if (typeof ResizeObserver === "undefined") return;
+    let width = textarea.getBoundingClientRect().width;
+    const observer = new ResizeObserver(() => {
+      const nextWidth = textarea.getBoundingClientRect().width;
+      if (nextWidth === width) return;
+      width = nextWidth;
+      autosizeNote(textarea);
+    });
+    observer.observe(textarea);
+    return () => observer.disconnect();
+  }, [annotation.note]);
+
+  return (
+    <textarea
+      ref={setRef}
+      value={annotation.note}
+      rows={1}
+      maxLength={2048}
+      placeholder="Add a note…"
+      aria-label="Note"
+      className="mt-0.5 max-h-40 min-h-8 w-full resize-none overflow-y-auto break-words border-0 bg-transparent px-0 py-1 text-og-sm leading-5 text-og-fg outline-hidden placeholder:text-og-fg-subtle focus-visible:ring-0"
+      onInput={(event) => {
+        autosizeNote(event.currentTarget);
+        onUpdate(annotation.id, event.currentTarget.value);
+      }}
+      onKeyDown={(event) => {
+        if (event.key !== "Enter" || event.shiftKey || event.nativeEvent.isComposing) return;
+        event.preventDefault();
+        event.stopPropagation();
+        if (event.currentTarget.value.trim().length === 0) return;
+        onCommit?.();
+      }}
+    />
+  );
+}

package/src/components/timeline-annotation-layout.ts

@@ -0,0 +1,268 @@
+export type AnnotationBox = {
+  left: number;
+  right: number;
+  top: number;
+  bottom: number;
+};
+
+export type AnnotationBadgeAnchor = {
+  id: string;
+  ordinal: number;
+  left: number;
+  top: number;
+  incomplete: boolean;
+};
+
+export const ANNOTATION_BADGE_GAP_PX = 32;
+export const ANNOTATION_BADGE_MIN_GAP_PX = 12;
+export const ANNOTATION_REVIEW_DIALOG_WIDTH_PX = 400;
+export const ANNOTATION_REVIEW_DIALOG_MAX_HEIGHT_PX = 32 * 16;
+export const ANNOTATION_REVIEW_DIALOG_MIN_HEIGHT_PX = 160;
+export const ANNOTATION_REVIEW_DIALOG_FLOOR_HEIGHT_PX = 80;
+export const ANNOTATION_REVIEW_MARGIN_PX = 12;
+export const ANNOTATION_NOTE_PREVIEW_CHARS = 280;
+export const ANNOTATION_CARD_STACK_SCROLL_AT = 4;
+
+function clampAnnotationAxis(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), Math.max(min, max));
+}
+
+export function annotationBoxIntersects(a: AnnotationBox, b: AnnotationBox): boolean {
+  return a.left <= b.right && a.right >= b.left && a.top <= b.bottom && a.bottom >= b.top;
+}
+
+export function annotationViewportBox(
+  viewportWidth: number,
+  viewportHeight: number,
+  scroller?: AnnotationBox | null,
+): AnnotationBox {
+  const viewport: AnnotationBox = {
+    left: 0,
+    top: 0,
+    right: Math.max(1, viewportWidth),
+    bottom: Math.max(1, viewportHeight),
+  };
+  if (!scroller || scroller.right - scroller.left <= 0 || scroller.bottom - scroller.top <= 0) {
+    return viewport;
+  }
+  return {
+    left: Math.max(viewport.left, scroller.left),
+    top: Math.max(viewport.top, scroller.top),
+    right: Math.min(viewport.right, scroller.right),
+    bottom: Math.min(viewport.bottom, scroller.bottom),
+  };
+}
+
+export function annotationNoteNeedsDisclosure(note: string): boolean {
+  const trimmed = note.trim();
+  if (trimmed.length === 0) return false;
+  return trimmed.length > ANNOTATION_NOTE_PREVIEW_CHARS || trimmed.split("\n").length > 4;
+}
+
+function annotationAxisStops(min: number, max: number, gap: number): number[] {
+  if (max <= min) return [min];
+  const stops: number[] = [];
+  for (let value = min; value <= max + 1e-6; value += gap) {
+    stops.push(value);
+  }
+  return stops;
+}
+
+function annotationPointKey(left: number, top: number): string {
+  return `${Math.round(left * 100) / 100},${Math.round(top * 100) / 100}`;
+}
+
+function annotationPointFree(
+  left: number,
+  top: number,
+  placed: readonly AnnotationBadgeAnchor[],
+  gap: number,
+): boolean {
+  return placed.every((other) => Math.hypot(left - other.left, top - other.top) >= gap);
+}
+
+export function annotationBadgePackGap(
+  viewport: AnnotationBox,
+  count: number,
+  preferred = ANNOTATION_BADGE_GAP_PX,
+): number {
+  if (count <= 1) return preferred;
+  const width = Math.max(
+    1,
+    viewport.right - ANNOTATION_REVIEW_MARGIN_PX - (viewport.left + ANNOTATION_REVIEW_MARGIN_PX),
+  );
+  const height = Math.max(1, viewport.bottom - ANNOTATION_REVIEW_MARGIN_PX - (viewport.top + 8));
+  let gap = preferred;
+  const capacity = (step: number) =>
+    (Math.floor(width / step) + 1) * (Math.floor(height / step) + 1);
+  while (gap > ANNOTATION_BADGE_MIN_GAP_PX && capacity(gap) < count) {
+    gap -= 1;
+  }
+  return gap;
+}
+
+const ANNOTATION_BADGE_SHIFT_DIRS: Array<[number, number]> = [
+  [1, 0],
+  [1, 1],
+  [0, 1],
+  [-1, 1],
+  [-1, 0],
+  [-1, -1],
+  [0, -1],
+  [1, -1],
+];
+
+export function layoutAnnotationBadges(
+  anchors: readonly AnnotationBadgeAnchor[],
+  viewport: AnnotationBox,
+  preferredGap = ANNOTATION_BADGE_GAP_PX,
+): AnnotationBadgeAnchor[] {
+  const minLeft = viewport.left + ANNOTATION_REVIEW_MARGIN_PX;
+  const maxLeft = viewport.right - ANNOTATION_REVIEW_MARGIN_PX;
+  const minTop = viewport.top + 8;
+  const maxTop = viewport.bottom - ANNOTATION_REVIEW_MARGIN_PX;
+  const gap = annotationBadgePackGap(viewport, anchors.length, preferredGap);
+  const cells = annotationAxisStops(minLeft, maxLeft, gap).flatMap((left) =>
+    annotationAxisStops(minTop, maxTop, gap).map((top) => ({ left, top })),
+  );
+  const placed: AnnotationBadgeAnchor[] = [];
+  for (const anchor of [...anchors].sort((left, right) => left.ordinal - right.ordinal)) {
+    const originLeft = clampAnnotationAxis(anchor.left, minLeft, maxLeft);
+    const originTop = clampAnnotationAxis(anchor.top, minTop, maxTop);
+    const seen = new Set<string>();
+    const candidates: Array<{ left: number; top: number }> = [];
+    const pushCandidate = (left: number, top: number) => {
+      if (left < minLeft || left > maxLeft || top < minTop || top > maxTop) return;
+      const key = annotationPointKey(left, top);
+      if (seen.has(key)) return;
+      seen.add(key);
+      candidates.push({ left, top });
+    };
+    pushCandidate(originLeft, originTop);
+    for (const [dx, dy] of ANNOTATION_BADGE_SHIFT_DIRS) {
+      const colliders = [...placed].sort(
+        (left, right) => right.left * dx + right.top * dy - (left.left * dx + left.top * dy),
+      );
+      for (const collider of colliders) {
+        pushCandidate(collider.left + dx * gap, collider.top + dy * gap);
+      }
+    }
+    const maxRadius =
+      Math.ceil(Math.max(maxLeft - minLeft, maxTop - minTop) / Math.max(gap, 1)) + 1;
+    for (let radius = 1; radius <= maxRadius; radius++) {
+      const ring: Array<[number, number]> = [];
+      for (let dx = -radius; dx <= radius; dx++) {
+        for (let dy = -radius; dy <= radius; dy++) {
+          if (Math.max(Math.abs(dx), Math.abs(dy)) !== radius) continue;
+          ring.push([dx, dy]);
+        }
+      }
+      ring.sort((left, right) => {
+        const leftDir = (left[0] < 0 ? 2 : 0) + (left[1] < 0 ? 1 : 0);
+        const rightDir = (right[0] < 0 ? 2 : 0) + (right[1] < 0 ? 1 : 0);
+        if (leftDir !== rightDir) return leftDir - rightDir;
+        const hypot = Math.hypot(left[0], left[1]) - Math.hypot(right[0], right[1]);
+        if (hypot !== 0) return hypot;
+        if (left[0] !== right[0]) return right[0] - left[0];
+        return left[1] - right[1];
+      });
+      for (const [dx, dy] of ring) {
+        pushCandidate(originLeft + dx * gap, originTop + dy * gap);
+      }
+    }
+    for (const cell of cells) {
+      pushCandidate(cell.left, cell.top);
+    }
+    const free = candidates.find((point) =>
+      annotationPointFree(point.left, point.top, placed, gap),
+    );
+    let chosen = free ?? candidates[0]!;
+    if (!free && placed.length > 0) {
+      let bestMin = Number.NEGATIVE_INFINITY;
+      for (const point of candidates) {
+        const minDist = placed.reduce(
+          (current, other) =>
+            Math.min(current, Math.hypot(point.left - other.left, point.top - other.top)),
+          Number.POSITIVE_INFINITY,
+        );
+        if (minDist > bestMin) {
+          bestMin = minDist;
+          chosen = point;
+        }
+      }
+    }
+    placed.push({ ...anchor, left: chosen.left, top: chosen.top });
+  }
+  return placed;
+}
+
+export function scrollAnnotationRowIntoList(
+  list: HTMLElement | null | undefined,
+  row: HTMLElement | null | undefined,
+): void {
+  if (!list || !row || !list.contains(row)) return;
+  const listRect = list.getBoundingClientRect();
+  const rowRect = row.getBoundingClientRect();
+  if (rowRect.top < listRect.top) {
+    list.scrollTop -= listRect.top - rowRect.top;
+    return;
+  }
+  if (rowRect.bottom > listRect.bottom) {
+    list.scrollTop += rowRect.bottom - listRect.bottom;
+  }
+}
+
+export function clampAnnotationDialogPlacement(input: {
+  triggerLeft: number;
+  triggerTop: number;
+  triggerBottom: number;
+  contentHeight: number;
+  viewportWidth: number;
+  viewportHeight: number;
+  panelWidth?: number;
+}): {
+  left: number;
+  top: number;
+  maxHeight: number;
+  above: boolean;
+} {
+  const margin = ANNOTATION_REVIEW_MARGIN_PX;
+  const panelWidth = Math.min(
+    input.panelWidth ?? ANNOTATION_REVIEW_DIALOG_WIDTH_PX,
+    Math.max(1, input.viewportWidth - margin * 2),
+  );
+  const left = Math.min(
+    Math.max(margin, input.triggerLeft),
+    Math.max(margin, input.viewportWidth - panelWidth - margin),
+  );
+  const spaceBelow = input.viewportHeight - input.triggerBottom - margin;
+  const spaceAbove = input.triggerTop - margin;
+  const above = spaceBelow < Math.min(input.contentHeight, 200) && spaceAbove > spaceBelow;
+  const viewportBudget = Math.max(
+    ANNOTATION_REVIEW_DIALOG_FLOOR_HEIGHT_PX,
+    input.viewportHeight - margin * 2,
+  );
+  const available = Math.max(
+    Math.min(ANNOTATION_REVIEW_DIALOG_MIN_HEIGHT_PX, viewportBudget),
+    above ? spaceAbove : spaceBelow,
+  );
+  let maxHeight = Math.min(
+    Math.max(input.contentHeight, Math.min(ANNOTATION_REVIEW_DIALOG_MIN_HEIGHT_PX, viewportBudget)),
+    available,
+    Math.floor(input.viewportHeight * 0.7) || viewportBudget,
+    ANNOTATION_REVIEW_DIALOG_MAX_HEIGHT_PX,
+    viewportBudget,
+  );
+  let top = above
+    ? Math.max(margin, input.triggerTop - 8 - maxHeight)
+    : Math.min(
+        input.triggerBottom + 8,
+        Math.max(margin, input.viewportHeight - margin - maxHeight),
+      );
+  top = Math.max(margin, top);
+  maxHeight = Math.min(
+    maxHeight,
+    Math.max(ANNOTATION_REVIEW_DIALOG_FLOOR_HEIGHT_PX, input.viewportHeight - margin - top),
+  );
+  return { left, top, maxHeight, above };
+}

package/src/components/timeline-annotation-markers.tsx

@@ -0,0 +1,185 @@
+import type { DraftTimelineAnnotation } from "@opengeni/sdk";
+import { useLayoutEffect, useState, type RefObject } from "react";
+import { createPortal } from "react-dom";
+import { cn } from "../lib/cn";
+import {
+  annotationBoxIntersects,
+  annotationViewportBox,
+  layoutAnnotationBadges,
+  type AnnotationBadgeAnchor,
+  type AnnotationBox,
+} from "./timeline-annotation-layout";
+import {
+  annotationDisplayOrdinal,
+  annotationHasNote,
+  annotatableText,
+  buildQuoteRange,
+  cssEscapeAttribute,
+  matchingQuoteInSource,
+  occurrenceOffsets,
+} from "./timeline-annotation-shared";
+
+function lastVisibleRect(range: Range): DOMRect | null {
+  try {
+    const rects = range.getClientRects();
+    for (let index = rects.length - 1; index >= 0; index--) {
+      const rect = rects.item(index);
+      if (rect && (rect.width > 0 || rect.height > 0)) return rect;
+    }
+  } catch {
+    // jsdom ranges may omit client rects.
+  }
+  try {
+    const bounding = range.getBoundingClientRect();
+    if (bounding.width > 0 || bounding.height > 0) return bounding;
+  } catch {
+    // jsdom ranges may omit layout geometry.
+  }
+  return null;
+}
+
+function occurrenceForAnnotation(
+  sourceEl: HTMLElement,
+  annotation: DraftTimelineAnnotation,
+): number {
+  const { text } = annotatableText(sourceEl);
+  const quote = matchingQuoteInSource(text, annotation.quote) ?? annotation.quote;
+  const offsets = occurrenceOffsets(text, quote);
+  if (offsets.length <= 1) return 0;
+  let best = 0;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  offsets.forEach((offset, index) => {
+    const distance = Math.abs(offset - annotation.source.startOffset);
+    if (distance < bestDistance) {
+      best = index;
+      bestDistance = distance;
+    }
+  });
+  return best;
+}
+
+function timelineScroller(root: HTMLElement): HTMLElement {
+  if (root.matches("[data-og-timeline-scroller]")) return root;
+  const nested = root.querySelector("[data-og-timeline-scroller]");
+  return nested instanceof HTMLElement ? nested : root;
+}
+
+function currentAnnotationViewport(root: HTMLElement): AnnotationBox {
+  const scroller = timelineScroller(root);
+  const rect = scroller.getBoundingClientRect();
+  const scrollerBox = {
+    left: rect.left,
+    right: rect.right,
+    top: rect.top,
+    bottom: rect.bottom,
+  } satisfies AnnotationBox;
+  return annotationViewportBox(window.innerWidth || 1024, window.innerHeight || 768, scrollerBox);
+}
+
+function sourceInTimeline(root: HTMLElement, eventId: string): HTMLElement | null {
+  const source = root.querySelector(
+    `[data-og-annotation-source-key="${cssEscapeAttribute(eventId)}"]`,
+  );
+  return source instanceof HTMLElement ? source : null;
+}
+
+function collectMarkers(
+  root: HTMLElement | null,
+  annotations: readonly DraftTimelineAnnotation[],
+): AnnotationBadgeAnchor[] {
+  if (!root) return [];
+  const viewport = currentAnnotationViewport(root);
+  const next: AnnotationBadgeAnchor[] = [];
+  for (const [index, annotation] of annotations.entries()) {
+    const source = sourceInTimeline(root, annotation.source.eventId);
+    if (!source) continue;
+    const quote =
+      matchingQuoteInSource(annotatableText(source).text, annotation.quote) ?? annotation.quote;
+    const range = buildQuoteRange(source, quote, occurrenceForAnnotation(source, annotation));
+    if (!range) continue;
+    const rect = lastVisibleRect(range);
+    if (!rect) continue;
+    if (
+      !annotationBoxIntersects(
+        { left: rect.left, right: rect.right, top: rect.top, bottom: rect.bottom },
+        viewport,
+      )
+    ) {
+      continue;
+    }
+    next.push({
+      id: annotation.id,
+      ordinal: annotationDisplayOrdinal(annotation, index),
+      left: rect.right,
+      top: rect.top,
+      incomplete: !annotationHasNote(annotation.note),
+    });
+  }
+  return layoutAnnotationBadges(next, viewport);
+}
+
+export function TimelineAnnotationMarkers({
+  annotations,
+  onSelect,
+  rootRef,
+}: {
+  annotations: readonly DraftTimelineAnnotation[];
+  onSelect?: ((id: string) => void) | undefined;
+  rootRef: RefObject<HTMLElement | null>;
+}) {
+  const [markers, setMarkers] = useState<AnnotationBadgeAnchor[]>([]);
+
+  useLayoutEffect(() => {
+    const root = rootRef.current;
+    if (!root || annotations.length === 0) {
+      setMarkers([]);
+      return;
+    }
+    const update = () => setMarkers(collectMarkers(root, annotations));
+    update();
+    window.addEventListener("resize", update);
+    window.addEventListener("scroll", update, true);
+    const observer = typeof ResizeObserver === "function" ? new ResizeObserver(update) : null;
+    observer?.observe(root);
+    for (const annotation of annotations) {
+      const source = sourceInTimeline(root, annotation.source.eventId);
+      if (source) observer?.observe(source);
+    }
+    return () => {
+      window.removeEventListener("resize", update);
+      window.removeEventListener("scroll", update, true);
+      observer?.disconnect();
+    };
+  }, [annotations, rootRef]);
+
+  if (markers.length === 0 || typeof document === "undefined") return null;
+  return createPortal(
+    <div className="og-root pointer-events-none fixed inset-0 z-[35]">
+      {markers.map((marker) => (
+        <button
+          key={marker.id}
+          type="button"
+          data-og-annotation-badge=""
+          data-og-annotation-badge-ordinal={marker.ordinal}
+          style={{ left: marker.left, top: marker.top, zIndex: marker.ordinal }}
+          className={cn(
+            "pointer-events-auto absolute flex h-4 min-w-4 -translate-x-1/2 -translate-y-[110%] items-center justify-center rounded-full bg-og-accent px-0.5 text-[10px] font-semibold tabular-nums text-og-accent-fg shadow-sm outline-hidden select-none after:absolute after:-inset-2 after:content-[''] focus-visible:ring-2 focus-visible:ring-og-accent pointer-coarse:after:-inset-2.5",
+            marker.incomplete && "ring-1 ring-og-accent-fg/35",
+          )}
+          aria-label={`Annotation ${marker.ordinal}`}
+          onMouseDown={(event) => event.preventDefault()}
+          onClick={(event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            onSelect?.(marker.id);
+          }}
+        >
+          {marker.ordinal}
+        </button>
+      ))}
+    </div>,
+    document.body,
+  );
+}
+
+export default TimelineAnnotationMarkers;

package/src/components/timeline-annotation-reveal-context.ts

@@ -0,0 +1,9 @@
+import { createContext, useContext, type RefObject } from "react";
+
+/** Owning timeline scroller for quote-source navigation. */
+export const TimelineAnnotationSourceRootContext =
+  createContext<RefObject<HTMLElement | null> | null>(null);
+
+export function useTimelineAnnotationSourceRoot(): RefObject<HTMLElement | null> | null {
+  return useContext(TimelineAnnotationSourceRootContext);
+}