@opengeni/react 3.3.2 → 3.4.0

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,
   );

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

@@ -0,0 +1,245 @@
+import type { TimelineAnnotationSource } from "@opengeni/sdk";
+
+export const ANNOTATION_CHROME_SELECTOR =
+  "[data-og-annotation-chrome], [data-og-annotation-badge], [data-og-annotation-popover]";
+
+export function annotationHasNote(note: string): boolean {
+  return note.trim().length > 0;
+}
+
+export function annotationDisplayOrdinal(
+  annotation: { readonly id?: string; readonly ordinal?: number | undefined },
+  index: number,
+): number {
+  return typeof annotation.ordinal === "number" ? annotation.ordinal : index + 1;
+}
+
+export function sourceKindLabel(kind: TimelineAnnotationSource["kind"]): string {
+  switch (kind) {
+    case "user_message":
+      return "Your message";
+    case "assistant_message":
+      return "Assistant";
+    case "tool_output":
+      return "Tool output";
+  }
+}
+
+export function annotationSourceLabel(source: TimelineAnnotationSource): string {
+  return source.label?.trim() || sourceKindLabel(source.kind);
+}
+
+export function truncateAnnotationQuote(quote: string, maxChars = 160): string {
+  const normalized = quote.replace(/\s+/g, " ").trim();
+  if (normalized.length <= maxChars) return normalized;
+  return `${normalized.slice(0, Math.max(0, maxChars - 1)).trimEnd()}…`;
+}
+
+export function cssEscapeAttribute(value: string): string {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") return CSS.escape(value);
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+export function isAnnotationChromeNode(node: Node | null): boolean {
+  const element = node instanceof Element ? node : node?.parentElement;
+  return Boolean(element?.closest(ANNOTATION_CHROME_SELECTOR));
+}
+
+export function occurrenceOffsets(text: string, quote: string): number[] {
+  if (!quote) return [];
+  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 uniqueNonEmpty(values: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const value of values) {
+    if (!value || seen.has(value)) continue;
+    seen.add(value);
+    out.push(value);
+  }
+  return out;
+}
+
+export function matchingQuoteInSource(sourceText: string, quote: string): string | null {
+  for (const candidate of uniqueNonEmpty([quote, quote.trim()])) {
+    if (sourceText.includes(candidate)) return candidate;
+  }
+  const trimmed = quote.trim();
+  for (let length = trimmed.length; length >= 8; length--) {
+    const slice = trimmed.slice(0, length);
+    if (sourceText.includes(slice)) return slice;
+  }
+  for (let start = 1; start <= trimmed.length - 8; start++) {
+    const slice = trimmed.slice(start);
+    if (sourceText.includes(slice)) return slice;
+  }
+  return null;
+}
+
+type AnnotatableSpan = {
+  node: Text;
+  start: number;
+  length: number;
+};
+
+export function annotatableText(root: HTMLElement): { text: string; spans: AnnotatableSpan[] } {
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+    acceptNode(node) {
+      if (!(node instanceof Text) || node.data.length === 0) return NodeFilter.FILTER_REJECT;
+      if (isAnnotationChromeNode(node)) return NodeFilter.FILTER_REJECT;
+      return NodeFilter.FILTER_ACCEPT;
+    },
+  });
+  const spans: AnnotatableSpan[] = [];
+  let text = "";
+  let current: Node | null;
+  while ((current = walker.nextNode())) {
+    if (!(current instanceof Text)) continue;
+    spans.push({ node: current, start: text.length, length: current.data.length });
+    text += current.data;
+  }
+  return { text, spans };
+}
+
+function pointAt(
+  spans: AnnotatableSpan[],
+  offset: number,
+  stickEnd: boolean,
+): { node: Text; offset: number } | null {
+  if (spans.length === 0) return null;
+  for (let index = 0; index < spans.length; index++) {
+    const span = spans[index]!;
+    const local = offset - span.start;
+    if (local < 0) continue;
+    if (
+      local < span.length ||
+      (local === span.length && (stickEnd || index === spans.length - 1))
+    ) {
+      return { node: span.node, offset: local };
+    }
+  }
+  const last = spans[spans.length - 1]!;
+  return { node: last.node, offset: last.length };
+}
+
+export function rangeFromOffsets(
+  spans: AnnotatableSpan[],
+  startOffset: number,
+  endOffset: number,
+): Range | null {
+  const start = pointAt(spans, startOffset, false);
+  const end = pointAt(spans, endOffset, true);
+  if (!start || !end) return null;
+  const range = document.createRange();
+  range.setStart(start.node, start.offset);
+  range.setEnd(end.node, end.offset);
+  return range.collapsed ? null : range;
+}
+
+export function buildQuoteRange(
+  sourceEl: HTMLElement,
+  quote: string,
+  occurrenceIndex = 0,
+): Range | null {
+  if (!quote) return null;
+  const { text, spans } = annotatableText(sourceEl);
+  const offsets = occurrenceOffsets(text, quote);
+  if (offsets.length === 0) return null;
+  const start = offsets[Math.min(Math.max(0, occurrenceIndex), offsets.length - 1)]!;
+  return rangeFromOffsets(spans, start, start + quote.length);
+}
+
+export function quoteOccurrenceIndex(sourceEl: HTMLElement, range: Range, quote: string): number {
+  try {
+    const prefix = range.cloneRange();
+    prefix.selectNodeContents(sourceEl);
+    prefix.setEnd(range.startContainer, range.startOffset);
+    return occurrenceOffsets(prefix.toString(), quote).length;
+  } catch {
+    return 0;
+  }
+}
+
+export function clipRangeToSource(range: Range, sourceEl: HTMLElement): Range | null {
+  const startOk =
+    sourceEl.contains(range.startContainer) && !isAnnotationChromeNode(range.startContainer);
+  const endOk =
+    sourceEl.contains(range.endContainer) && !isAnnotationChromeNode(range.endContainer);
+  if (!startOk && !endOk) return null;
+  const { spans } = annotatableText(sourceEl);
+  if (spans.length === 0) return null;
+  const next = range.cloneRange();
+  const first = spans[0]!;
+  const last = spans[spans.length - 1]!;
+  if (!startOk) next.setStart(first.node, 0);
+  if (!endOk) next.setEnd(last.node, last.node.data.length);
+  return next.collapsed ? null : next;
+}
+
+export function visibleClientRect(range: Range): DOMRect | null {
+  try {
+    const bounding = range.getBoundingClientRect();
+    if (bounding.width > 0 || bounding.height > 0) return bounding;
+  } catch {
+    // jsdom ranges may omit layout geometry.
+  }
+  try {
+    const rects = range.getClientRects();
+    for (let index = 0; index < rects.length; index++) {
+      const rect = rects.item(index);
+      if (rect && (rect.width > 0 || rect.height > 0)) return rect;
+    }
+  } catch {
+    // jsdom ranges may omit client rects.
+  }
+  return null;
+}
+
+export function resolveAnnotationRevealRoot(from: Element | null | undefined): HTMLElement | null {
+  const conversation = from?.closest("[data-og-conversation]");
+  if (conversation instanceof HTMLElement) {
+    const nested = conversation.querySelector("[data-og-timeline-scroller]");
+    return nested instanceof HTMLElement ? nested : conversation;
+  }
+  const scroller = from?.closest("[data-og-timeline-scroller]");
+  return scroller instanceof HTMLElement ? scroller : null;
+}
+
+export function revealLoadedAnnotationSource(
+  source: TimelineAnnotationSource,
+  root?: ParentNode | null,
+): boolean {
+  if (typeof document === "undefined") return false;
+  // An explicit null root means the caller already scoped the search and found
+  // no owning timeline. Do not fall back to `document`, or a second mounted
+  // timeline with the same event id would steal the reveal.
+  if (root === null) return false;
+  const element = (root ?? document).querySelector(
+    `[data-og-annotation-source-key="${cssEscapeAttribute(source.eventId)}"]`,
+  );
+  if (!(element instanceof HTMLElement)) return false;
+  element.scrollIntoView({ block: "center", behavior: "smooth" });
+  element.animate?.(
+    [
+      {
+        boxShadow: "inset 0 0 0 2px color-mix(in oklch, var(--og-color-accent) 70%, transparent)",
+        backgroundColor: "color-mix(in oklch, var(--og-color-accent) 14%, transparent)",
+      },
+      {
+        boxShadow: "inset 0 0 0 2px transparent",
+        backgroundColor: "transparent",
+      },
+    ],
+    { duration: 1400, easing: "ease-out" },
+  );
+  return true;
+}