@opengeni/react 0.57.0 → 1.0.2-canary.37191796234001

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);
+}

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

@@ -1,7 +1,17 @@
 import type { DraftTimelineAnnotation } from "@opengeni/sdk";
+import { QuoteIcon } from "lucide-react";
 import { useEffect, useRef, useState, type RefObject } from "react";
 import { createPortal } from "react-dom";
+import { usePortalTokenStyle } from "../lib/use-portal-token-style";
 import type { TimelineAnnotationSourceDescriptor } from "../timeline";
+import {
+  clipRangeToSource,
+  matchingQuoteInSource,
+  occurrenceOffsets,
+  quoteOccurrenceIndex,
+  truncateAnnotationQuote,
+  visibleClientRect,
+} from "./timeline-annotation-shared";
 
 type SelectionCandidate = {
   annotation: DraftTimelineAnnotation;
@@ -10,10 +20,11 @@ type SelectionCandidate = {
   keyboard: boolean;
 };
 
-const INTERACTIVE_SELECTOR =
-  'a,button,input,textarea,select,summary,[role="button"],[contenteditable="true"],[tabindex]:not([tabindex="-1"])';
+const CONTROL_SELECTOR = "button,input,textarea,select,summary,[contenteditable='true']";
 const SOURCE_CONTEXT_BYTES = 160;
 const MAX_QUOTE_BYTES = 16 * 1024;
+const POPOVER_WIDTH = 280;
+const POPOVER_HEIGHT = 64;
 
 function utf8Prefix(value: string, maxBytes: number): string {
   let output = "";
@@ -49,33 +60,21 @@ function containingSource(node: Node | null): HTMLElement | null {
   return source instanceof HTMLElement ? source : null;
 }
 
-function isInteractiveSelection(node: Node | null, boundary: HTMLElement): boolean {
-  const element = selectionElement(node);
-  const interactive = element?.closest(INTERACTIVE_SELECTOR);
-  return interactive instanceof Element && boundary.contains(interactive);
-}
-
-function occurrenceOffsets(text: string, quote: string): number[] {
-  const offsets: number[] = [];
-  let cursor = 0;
-  while (cursor <= text.length - quote.length) {
-    const offset = text.indexOf(quote, cursor);
-    if (offset < 0) break;
-    offsets.push(offset);
-    cursor = offset + 1;
-  }
-  return offsets;
+function resolveSourceBoundary(range: Range, root: HTMLElement): HTMLElement | null {
+  const start = containingSource(range.startContainer);
+  const end = containingSource(range.endContainer);
+  if (start && end && start !== end) return null;
+  const boundary = start ?? end;
+  if (!boundary || !root.contains(boundary)) return null;
+  return boundary;
 }
 
-function selectedOccurrence(boundary: HTMLElement, range: Range, quote: string): number {
-  try {
-    const prefix = range.cloneRange();
-    prefix.selectNodeContents(boundary);
-    prefix.setEnd(range.startContainer, range.startOffset);
-    return occurrenceOffsets(prefix.toString(), quote).length;
-  } catch {
-    return 0;
-  }
+function isWhollyInsideControl(range: Range, boundary: HTMLElement): boolean {
+  const start = selectionElement(range.startContainer)?.closest(CONTROL_SELECTOR);
+  const end = selectionElement(range.endContainer)?.closest(CONTROL_SELECTOR);
+  return (
+    start instanceof Element && start === end && boundary.contains(start) && start !== boundary
+  );
 }
 
 function annotationId(): string {
@@ -85,6 +84,18 @@ function annotationId(): string {
   return `annotation-${Date.now()}-${Math.random().toString(16).slice(2)}`;
 }
 
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+function popoverPosition(rect: DOMRect): { left: number; top: number } {
+  const half = POPOVER_WIDTH / 2;
+  const left = clamp(rect.left + rect.width / 2, 12 + half, window.innerWidth - 12 - half);
+  const preferBelow = rect.bottom + 8 + POPOVER_HEIGHT <= window.innerHeight - 12;
+  const top = preferBelow ? rect.bottom + 8 : Math.max(12, rect.top - POPOVER_HEIGHT - 8);
+  return { left, top };
+}
+
 function buildCandidate(
   root: HTMLElement,
   sources: ReadonlyMap<string, TimelineAnnotationSourceDescriptor>,
@@ -93,18 +104,15 @@ function buildCandidate(
   const selection = document.getSelection();
   if (!selection || selection.rangeCount !== 1 || selection.isCollapsed) return null;
   const range = selection.getRangeAt(0);
-  const startBoundary = containingSource(range.startContainer);
-  const endBoundary = containingSource(range.endContainer);
-  if (!startBoundary || startBoundary !== endBoundary || !root.contains(startBoundary)) return null;
-  if (
-    isInteractiveSelection(range.startContainer, startBoundary) ||
-    isInteractiveSelection(range.endContainer, startBoundary)
-  ) {
-    return null;
-  }
+  const startBoundary = resolveSourceBoundary(range, root);
+  if (!startBoundary) return null;
+  if (isWhollyInsideControl(range, startBoundary)) return null;
+  const clipped = clipRangeToSource(range, startBoundary);
+  if (!clipped) return null;
   const sourceKey = startBoundary.dataset.ogAnnotationSourceKey;
   const source = sourceKey ? sources.get(sourceKey) : undefined;
-  const quote = selection.toString();
+  const rawQuote = clipped.toString();
+  const quote = (source ? matchingQuoteInSource(source.text, rawQuote) : null) ?? rawQuote;
   if (
     !source ||
     quote.trim().length === 0 ||
@@ -114,11 +122,12 @@ function buildCandidate(
   }
   const sourceOffsets = occurrenceOffsets(source.text, quote);
   if (sourceOffsets.length === 0) return null;
-  const occurrence = selectedOccurrence(startBoundary, range, quote);
+  const occurrence = quoteOccurrenceIndex(startBoundary, clipped, quote);
   const startOffset = sourceOffsets[Math.min(occurrence, sourceOffsets.length - 1)]!;
   const endOffset = startOffset + quote.length;
-  const rect = range.getBoundingClientRect();
-  if (rect.width === 0 && rect.height === 0) return null;
+  const rect = visibleClientRect(range) ?? visibleClientRect(clipped);
+  if (!rect) return null;
+  const position = popoverPosition(rect);
   return {
     annotation: {
       id: annotationId(),
@@ -137,8 +146,8 @@ function buildCandidate(
         ...(source.label ? { label: source.label } : {}),
       },
     },
-    left: Math.min(Math.max(12, rect.left + rect.width / 2), window.innerWidth - 12),
-    top: rect.bottom + 48 <= window.innerHeight ? rect.bottom + 8 : Math.max(12, rect.top - 40),
+    left: position.left,
+    top: position.top,
     keyboard,
   };
 }
@@ -154,6 +163,9 @@ export function TimelineAnnotationSelection({
 }) {
   const [candidate, setCandidate] = useState<SelectionCandidate | null>(null);
   const buttonRef = useRef<HTMLButtonElement | null>(null);
+  const initialSelectionObservedRef = useRef(false);
+  const pointerOriginRef = useRef<"unset" | "inside" | "outside">("unset");
+  const portalStyle = usePortalTokenStyle(rootRef.current);
 
   useEffect(() => {
     const root = rootRef.current;
@@ -164,7 +176,26 @@ export function TimelineAnnotationSelection({
     const update = (keyboard: boolean) => {
       setCandidate(buildCandidate(root, sources, keyboard));
     };
-    const onPointerUp = () => window.setTimeout(() => update(false), 0);
+    // A user may finish selecting text before this lazy component arrives.
+    // Reconcile once; later prop changes must not revive dismissed selections.
+    if (!initialSelectionObservedRef.current) {
+      initialSelectionObservedRef.current = true;
+      update(false);
+    }
+    const onRootPointerUp = (event: PointerEvent) => {
+      if (event.target instanceof Node && buttonRef.current?.contains(event.target)) return;
+      // Tests may fire only pointerup on the source. A real click that started
+      // outside the timeline must not resurrect leftover selection.
+      if (pointerOriginRef.current === "outside") return;
+      window.setTimeout(() => update(false), 0);
+    };
+    const onDocumentPointerUp = (event: PointerEvent) => {
+      if (event.target instanceof Node && buttonRef.current?.contains(event.target)) return;
+      const startedInRoot = pointerOriginRef.current === "inside";
+      pointerOriginRef.current = "unset";
+      if (!startedInRoot) return;
+      window.setTimeout(() => update(false), 0);
+    };
     const onKeyUp = (event: KeyboardEvent) => {
       if (event.key === "Escape") {
         setCandidate(null);
@@ -173,46 +204,67 @@ export function TimelineAnnotationSelection({
       window.setTimeout(() => update(true), 0);
     };
     const onPointerDown = (event: PointerEvent) => {
-      if (
-        candidate &&
-        !(event.target instanceof Node && buttonRef.current?.contains(event.target))
-      ) {
-        setCandidate(null);
+      if (event.target instanceof Node && buttonRef.current?.contains(event.target)) {
+        event.preventDefault();
+        return;
       }
+      pointerOriginRef.current =
+        event.target instanceof Node && root.contains(event.target) ? "inside" : "outside";
+      setCandidate(null);
     };
     const onDocumentKeyDown = (event: KeyboardEvent) => {
       if (event.key === "Escape") setCandidate(null);
     };
-    root.addEventListener("pointerup", onPointerUp);
+    const onSelectionChange = () => {
+      if (buttonRef.current && document.activeElement === buttonRef.current) return;
+      const selection = document.getSelection();
+      if (!selection || selection.isCollapsed) setCandidate(null);
+    };
+    root.addEventListener("pointerup", onRootPointerUp);
     root.addEventListener("keyup", onKeyUp);
+    document.addEventListener("pointerup", onDocumentPointerUp);
     document.addEventListener("pointerdown", onPointerDown);
     document.addEventListener("keydown", onDocumentKeyDown);
+    document.addEventListener("selectionchange", onSelectionChange);
     return () => {
-      root.removeEventListener("pointerup", onPointerUp);
+      root.removeEventListener("pointerup", onRootPointerUp);
       root.removeEventListener("keyup", onKeyUp);
+      document.removeEventListener("pointerup", onDocumentPointerUp);
       document.removeEventListener("pointerdown", onPointerDown);
       document.removeEventListener("keydown", onDocumentKeyDown);
+      document.removeEventListener("selectionchange", onSelectionChange);
     };
-  }, [candidate, onAnnotate, rootRef, sources]);
+  }, [onAnnotate, rootRef, sources]);
 
   useEffect(() => {
     if (candidate?.keyboard) buttonRef.current?.focus();
   }, [candidate]);
 
   if (!candidate || !onAnnotate || typeof document === "undefined") return null;
+  const preview = truncateAnnotationQuote(candidate.annotation.quote, 72);
   return createPortal(
     <button
       ref={buttonRef}
       type="button"
-      style={{ left: candidate.left, top: candidate.top }}
-      className="og-root fixed z-[80] -translate-x-1/2 rounded-full border border-og-border bg-og-surface-1 px-3 py-1.5 text-og-sm font-medium text-og-fg shadow-lg outline-hidden transition hover:bg-og-surface-2 focus-visible:ring-2 focus-visible:ring-og-accent pointer-coarse:min-h-[44px]"
+      data-og-annotation-popover=""
+      style={{ left: candidate.left, top: candidate.top, ...portalStyle }}
+      className="og-root fixed z-[80] flex max-w-[min(18rem,calc(100vw-1.5rem))] -translate-x-1/2 items-start gap-2 rounded-2xl border border-og-border bg-og-surface-1 px-3 py-2 text-og-sm font-medium text-og-fg shadow-xl outline-hidden transition hover:border-og-accent/40 hover:bg-og-surface-2 focus-visible:ring-2 focus-visible:ring-og-accent pointer-coarse:min-h-[44px]"
+      aria-label={`Add a note about “${preview}”`}
+      title={candidate.annotation.quote}
+      onPointerDown={(event) => event.preventDefault()}
       onClick={() => {
         onAnnotate(candidate.annotation);
         document.getSelection()?.removeAllRanges();
         setCandidate(null);
       }}
     >
-      Annotate
+      <QuoteIcon className="mt-0.5 size-3.5 shrink-0 text-og-accent" aria-hidden="true" />
+      <span className="min-w-0 text-left">
+        <span className="block leading-5">Add note</span>
+        <span className="mt-0.5 block truncate text-og-xs font-normal text-og-fg-muted">
+          {preview}
+        </span>
+      </span>
     </button>,
     document.body,
   );