@opengeni/react 1.0.1 → 1.0.2-canary.37202341988001

package/src/components/timeline-annotations.tsx

@@ -1,15 +1,114 @@
-import type {
-  DraftTimelineAnnotation,
-  TimelineAnnotation,
-  TimelineAnnotationSource,
-} from "@opengeni/sdk";
-import { Suspense, lazy, useRef, useState } from "react";
+import type { TimelineAnnotationSource } from "@opengeni/sdk";
+import { QuoteIcon, XIcon } from "lucide-react";
+import {
+  Suspense,
+  lazy,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ReactNode,
+  type RefObject,
+} from "react";
 import { cn } from "../lib/cn";
+import {
+  AnnotationAccentRow,
+  AnnotationNotePreview,
+  AnnotationQuoteSourceButton,
+  type TimelineAnnotationLike,
+} from "./timeline-annotation-chrome";
+import { ANNOTATION_CARD_STACK_SCROLL_AT } from "./timeline-annotation-layout";
+import {
+  TimelineAnnotationSourceRootContext,
+  useTimelineAnnotationSourceRoot,
+} from "./timeline-annotation-reveal-context";
+import {
+  annotationDisplayOrdinal,
+  annotationHasNote,
+  resolveAnnotationRevealRoot,
+} from "./timeline-annotation-shared";
 
-export type TimelineAnnotationLike = DraftTimelineAnnotation | TimelineAnnotation;
+export type { TimelineAnnotationLike } from "./timeline-annotation-chrome";
 
 const TimelineAnnotationsDialog = lazy(() => import("./timeline-annotations-dialog"));
 
+function AnnotationSourceRootBridge({
+  triggerRef,
+  children,
+}: {
+  triggerRef: RefObject<HTMLElement | null>;
+  children: ReactNode;
+}) {
+  const inheritedRoot = useTimelineAnnotationSourceRoot();
+  const conversationRootRef = useRef<HTMLElement | null>(null);
+  if (!inheritedRoot) {
+    conversationRootRef.current = resolveAnnotationRevealRoot(triggerRef.current);
+  }
+  useLayoutEffect(() => {
+    if (inheritedRoot) return;
+    conversationRootRef.current = resolveAnnotationRevealRoot(triggerRef.current);
+  });
+  if (inheritedRoot) return children;
+  return (
+    <TimelineAnnotationSourceRootContext.Provider value={conversationRootRef}>
+      {children}
+    </TimelineAnnotationSourceRootContext.Provider>
+  );
+}
+
+export function TimelineAnnotationCards({
+  annotations,
+  onRevealSource,
+  className,
+}: {
+  annotations: readonly TimelineAnnotationLike[];
+  onRevealSource?: ((source: TimelineAnnotationSource) => boolean) | undefined;
+  className?: string | undefined;
+}) {
+  const [unavailableId, setUnavailableId] = useState<string | null>(null);
+  if (annotations.length === 0) return null;
+  return (
+    <div
+      data-og-annotation-cards=""
+      className={cn(
+        "grid gap-2",
+        annotations.length >= ANNOTATION_CARD_STACK_SCROLL_AT &&
+          "max-h-[min(28rem,55vh)] overflow-x-hidden overflow-y-auto overscroll-contain pr-1",
+        className,
+      )}
+    >
+      {annotations.map((annotation, index) => {
+        const ordinal = annotationDisplayOrdinal(annotation, index);
+        return (
+          <section key={annotation.id} aria-label={`Annotation ${ordinal}`}>
+            <AnnotationAccentRow>
+              <p className="mb-0.5 text-og-xs font-medium tabular-nums text-og-fg-subtle">
+                Annotation {ordinal}
+              </p>
+              <AnnotationQuoteSourceButton
+                annotation={annotation}
+                lines={2}
+                onRevealSource={onRevealSource}
+                onUnavailable={setUnavailableId}
+              />
+              {unavailableId === annotation.id ? (
+                <p role="status" className="text-og-xs text-og-status-waiting">
+                  Source is outside the loaded timeline window.
+                </p>
+              ) : null}
+              <AnnotationNotePreview
+                note={annotation.note}
+                annotationId={annotation.id}
+                ordinal={ordinal}
+              />
+            </AnnotationAccentRow>
+          </section>
+        );
+      })}
+    </div>
+  );
+}
+
 export function TimelineAnnotationsChip({
   annotations,
   editable = false,
@@ -19,6 +118,8 @@ export function TimelineAnnotationsChip({
   onRemove,
   onRevealSource,
   className,
+  compact = false,
+  onCommit,
 }: {
   annotations: readonly TimelineAnnotationLike[];
   editable?: boolean | undefined;
@@ -26,58 +127,101 @@ export function TimelineAnnotationsChip({
   onFocusConsumed?: (() => void) | undefined;
   onUpdate?: ((id: string, note: string) => void) | undefined;
   onRemove?: ((id: string) => void) | undefined;
+  /** Return focus to the owning input after all notes are completed with Enter. */
+  onCommit?: (() => void) | undefined;
   onRevealSource?: ((source: TimelineAnnotationSource) => boolean) | undefined;
   className?: string | undefined;
+  /** Dense trigger for single-line rows such as the compact queue dock. */
+  compact?: boolean | undefined;
 }) {
-  const [open, setOpen] = useState(false);
-  const triggerRef = useRef<HTMLButtonElement | null>(null);
-
-  if (annotations.length === 0) return null;
   const focusRequested = Boolean(
     focusAnnotationId && annotations.some((item) => item.id === focusAnnotationId),
   );
-  const visible = open || focusRequested;
+  const [open, setOpen] = useState(focusRequested);
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const openedFocusId = useRef<string | null>(focusRequested ? (focusAnnotationId ?? null) : null);
+
+  useEffect(() => {
+    if (!focusRequested || !focusAnnotationId) {
+      if (!focusRequested) openedFocusId.current = null;
+      return;
+    }
+    if (openedFocusId.current === focusAnnotationId) return;
+    openedFocusId.current = focusAnnotationId;
+    setOpen(true);
+  }, [focusAnnotationId, focusRequested]);
+
+  if (annotations.length === 0) return null;
   const countLabel = `${annotations.length} ${annotations.length === 1 ? "annotation" : "annotations"}`;
+  const incomplete = annotations.some((annotation) => !annotationHasNote(annotation.note));
+  const canClear = Boolean(editable && onRemove);
+
+  const dismiss = (restoreFocus: boolean) => {
+    setOpen(false);
+    onFocusConsumed?.();
+    if (restoreFocus) triggerRef.current?.focus();
+  };
 
   return (
-    <>
-      <button
-        ref={triggerRef}
-        type="button"
+    <span className={cn("inline-flex max-w-full items-center", className)}>
+      <span
         className={cn(
-          "inline-flex min-h-8 items-center gap-1.5 rounded-full border border-og-border bg-og-surface-1 px-2.5 py-1 text-og-sm font-medium text-og-fg-muted outline-hidden transition hover:bg-og-surface-2 hover:text-og-fg focus-visible:ring-2 focus-visible:ring-og-accent pointer-coarse:min-h-[44px]",
-          className,
+          "inline-flex max-w-full items-center rounded-full border bg-og-surface-1 text-og-fg-muted",
+          incomplete ? "border-og-accent/45 bg-og-accent-soft/50" : "border-og-border",
         )}
-        aria-label={`Review ${countLabel}`}
-        aria-haspopup="dialog"
-        aria-expanded={visible}
-        onClick={() => setOpen((current) => !current)}
       >
-        {countLabel}
-      </button>
-      {visible ? (
-        <Suspense fallback={null}>
-          <TimelineAnnotationsDialog
-            annotations={annotations}
-            editable={editable}
-            focusAnnotationId={focusAnnotationId}
-            onFocusConsumed={() => {
-              setOpen(true);
-              onFocusConsumed?.();
-            }}
-            onUpdate={onUpdate}
-            onRemove={onRemove}
-            onRevealSource={onRevealSource}
-            triggerRef={triggerRef}
-            countLabel={countLabel}
-            onDismiss={(restoreFocus) => {
-              setOpen(false);
-              if (restoreFocus) triggerRef.current?.focus();
+        <button
+          ref={triggerRef}
+          type="button"
+          className={cn(
+            "inline-flex min-w-0 max-w-full items-center gap-1.5 rounded-full border-0 bg-transparent font-medium outline-hidden transition hover:text-og-fg focus-visible:ring-2 focus-visible:ring-og-accent pointer-coarse:min-h-[44px]",
+            compact ? "min-h-6 py-0.5 text-og-xs" : "min-h-8 py-1 text-og-sm",
+            canClear ? "pr-1 pl-2.5" : "px-2.5",
+          )}
+          aria-label={`Review ${countLabel}`}
+          aria-haspopup="dialog"
+          aria-expanded={open}
+          onClick={() => setOpen((current) => !current)}
+        >
+          <QuoteIcon className="size-3.5 shrink-0 text-og-accent" aria-hidden="true" />
+          <span className="min-w-0 truncate">{countLabel}</span>
+        </button>
+        {canClear ? (
+          <button
+            type="button"
+            className="inline-flex size-7 shrink-0 items-center justify-center rounded-full border-0 bg-transparent text-og-fg-subtle outline-hidden hover:text-og-status-failed focus-visible:ring-2 focus-visible:ring-og-accent pointer-coarse:size-11"
+            aria-label="Remove all annotations"
+            onClick={() => {
+              for (const annotation of annotations) onRemove?.(annotation.id);
             }}
-          />
-        </Suspense>
+          >
+            <XIcon className="size-3.5" aria-hidden="true" />
+          </button>
+        ) : null}
+      </span>
+      {open ? (
+        <AnnotationSourceRootBridge triggerRef={triggerRef}>
+          <Suspense fallback={null}>
+            <TimelineAnnotationsDialog
+              annotations={annotations}
+              editable={editable}
+              focusAnnotationId={focusAnnotationId}
+              onFocusConsumed={onFocusConsumed}
+              onUpdate={onUpdate}
+              onRemove={onRemove}
+              onRevealSource={onRevealSource}
+              triggerRef={triggerRef}
+              countLabel={countLabel}
+              onDismiss={dismiss}
+              onCommit={() => {
+                dismiss(!onCommit);
+                onCommit?.();
+              }}
+            />
+          </Suspense>
+        </AnnotationSourceRootBridge>
       ) : null}
-    </>
+    </span>
   );
 }
 

package/src/components/timeline-reading-progress.ts

@@ -0,0 +1,80 @@
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from "react";
+import type { TimelineGroup } from "../timeline/types";
+import { timelineHasReader } from "./timeline-anchor";
+
+/**
+ * Settlement may compact history, but cannot remove prose beneath a reader.
+ * Keep only progress that was already primary on the preceding commit; loading
+ * settled history never expands it. An explicit work toggle or tip return ends
+ * the protection. Keeping the original sibling keys also preserves selection.
+ */
+export function useReadingProgress(
+  projected: TimelineGroup[],
+  pinned: boolean,
+  scroller: HTMLElement | null,
+) {
+  const following = pinned && !timelineHasReader(scroller);
+  const previous = useRef<TimelineGroup[]>([]);
+  const [released, setReleased] = useState<ReadonlySet<string>>(() => new Set());
+  const groups = useMemo(() => {
+    if (following) return projected;
+    const key = (group: TimelineGroup) => (group.kind === "item" ? group.item.id : group.id);
+    const visible = new Set(previous.current.map(key));
+    const retained = new Map<string, TimelineGroup>();
+    const compact = projected.map((group): TimelineGroup => {
+      if (group.kind !== "activity" || !group.work?.endedAt || released.has(group.id)) {
+        return group;
+      }
+      const progress = group.work.details.filter(
+        (child) =>
+          child.kind === "item" &&
+          child.item.kind === "agent-message" &&
+          visible.has(child.item.id),
+      );
+      if (!progress.length) return group;
+      for (const child of progress) retained.set(key(child), child);
+      return {
+        ...group,
+        work: {
+          ...group.work,
+          details: group.work.details.filter((child) => !retained.has(key(child))),
+        },
+      };
+    });
+    if (!retained.size) return compact;
+    // Keep prose before the same retained sibling, including attention rows.
+    // Merely hoisting it before Work would still move its DOM across those rows
+    // and invalidate a browser selection despite retaining React keys.
+    const current = new Set(compact.map(key));
+    const before = new Map<string | null, TimelineGroup[]>();
+    let next: string | null = null;
+    for (let index = previous.current.length - 1; index >= 0; index--) {
+      const id = key(previous.current[index]!);
+      const child = retained.get(id);
+      if (child) before.set(next, [child, ...(before.get(next) ?? [])]);
+      else if (current.has(id)) next = id;
+    }
+    return [
+      ...compact.flatMap((group) => [...(before.get(key(group)) ?? []), group]),
+      ...(before.get(null) ?? []),
+    ];
+  }, [projected, following, released]);
+  useLayoutEffect(() => {
+    previous.current = groups;
+    if (following && released.size) setReleased(new Set());
+  }, [groups, following, released]);
+  const release = useCallback(
+    (id: string | null) => {
+      if (
+        !id ||
+        !projected.some(
+          (group) => group.kind === "activity" && group.id === id && group.work?.endedAt,
+        )
+      )
+        return;
+      setReleased((current) => (current.has(id) ? current : new Set([...current, id])));
+    },
+    [projected],
+  );
+  return { groups, release };
+}

package/src/components/timeline-search.tsx

@@ -0,0 +1,168 @@
+import { createContext, useContext, useLayoutEffect, useRef, type RefObject } from "react";
+import type { TimelineItem } from "../timeline/types";
+import { annotatableText, rangeFromOffsets, visibleClientRect } from "./timeline-annotation-shared";
+
+export type TimelineSearchTarget = {
+  sequence: number;
+  eventId?: string | undefined;
+  /** Literal, case-insensitive text. No regex interpretation. */
+  query: string;
+  /** Zero-based occurrence within the source message. Defaults to zero. */
+  occurrence?: number | undefined;
+  /**
+   * Zero-based UTF-16 offset of the match in the original message text, as
+   * reported by backend all-occurrence search (messageMatchOffset). When set
+   * it takes precedence over `occurrence` and is validated against `query`,
+   * so a stale offset degrades to no highlight rather than a wrong one.
+   */
+  offset?: number | undefined;
+};
+
+/** Scoped to the target's group; disclosure expansion persists after closing find. */
+export const TimelineSearchRevealContext = createContext<string | null>(null);
+export const useTimelineSearchReveal = () => useContext(TimelineSearchRevealContext);
+
+export function isTimelineSearchTarget(item: TimelineItem, target: TimelineSearchTarget): boolean {
+  const sources =
+    item.sourceEvents ??
+    ("annotationSource" in item && item.annotationSource ? [item.annotationSource] : []);
+  return sources.some(
+    (source) =>
+      source.sequence === target.sequence && (!target.eventId || source.eventId === target.eventId),
+  );
+}
+
+/** Scan without allocating an offset array proportional to a huge message. */
+export function literalSearchOffset(text: string, query: string, occurrence = 0): number {
+  if (!query || !Number.isSafeInteger(occurrence) || occurrence < 0) return -1;
+  // Regex escaping preserves UTF-16 offsets even for case folds whose lowercase
+  // string representation changes length (for example dotted capital I).
+  const pattern = new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "giu");
+  let match: RegExpExecArray | null;
+  let index = 0;
+  while ((match = pattern.exec(text))) {
+    if (index++ === occurrence) return match.index;
+  }
+  return -1;
+}
+
+/**
+ * Validate a caller-supplied UTF-16 offset against the text and query. The
+ * sticky flag pins the match to exactly `offset`; like literalSearchOffset,
+ * regex escaping keeps offsets in UTF-16 units even for length-changing case
+ * folds. Returns -1 when the offset is stale or the text no longer matches.
+ */
+export function matchAtOffset(text: string, query: string, offset: number): number {
+  if (!query || !Number.isSafeInteger(offset) || offset < 0 || offset > text.length) return -1;
+  const pattern = new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "iyu");
+  pattern.lastIndex = offset;
+  // Unicode regex engines may rewind a lastIndex inside a surrogate pair.
+  return pattern.exec(text)?.index === offset ? offset : -1;
+}
+
+/** Resolve a target to a UTF-16 offset: explicit offset wins, else the ordinal scan. */
+export function searchMatchOffset(text: string, target: TimelineSearchTarget): number {
+  if (target.offset != null) return matchAtOffset(text, target.query, target.offset);
+  return literalSearchOffset(text, target.query, target.occurrence);
+}
+
+type HighlightRegistry = { set(name: string, value: unknown): void; delete(name: string): void };
+let nextHighlightId = 0;
+
+/** Range highlighting does not mutate React-owned text or its layout. */
+export function useTimelineSearchNavigation(
+  root: RefObject<HTMLDivElement | null>,
+  itemId: string | undefined,
+  target: TimelineSearchTarget | null | undefined,
+  releasePin: () => void,
+  revision: unknown,
+) {
+  const highlightName = useRef("");
+  if (!highlightName.current) highlightName.current = `og-search-${++nextHighlightId}`;
+  const key = target
+    ? JSON.stringify([
+        itemId,
+        target.sequence,
+        target.eventId,
+        target.query,
+        target.occurrence ?? 0,
+        target.offset ?? null,
+      ])
+    : null;
+  const navigated = useRef<string | null>(null);
+  useLayoutEffect(() => {
+    if (!key) navigated.current = null;
+    if (!key || !target || !itemId || !root.current) return;
+    releasePin();
+    const scroller = root.current;
+    const registry = (
+      globalThis.CSS as (typeof CSS & { highlights?: HighlightRegistry }) | undefined
+    )?.highlights;
+    const HighlightClass = (
+      globalThis as unknown as { Highlight?: new (...ranges: Range[]) => unknown }
+    ).Highlight;
+    const style = document.createElement("style");
+    style.textContent = `::highlight(${highlightName.current}) { background: var(--og-color-accent-deep); color: var(--og-color-accent-fg); }`;
+    scroller.append(style);
+    let frame = 0;
+    const update = () => {
+      const source = [...scroller.querySelectorAll<HTMLElement>("[data-og-search-item]")].find(
+        (element) => element.dataset.ogSearchItem === itemId,
+      );
+      if (!source) return;
+      // A virtualized renderer can explicitly identify the selected occurrence
+      // when earlier occurrences are not mounted. Never accept a stale marker
+      // belonging to a different sequence, occurrence, or query.
+      const materialized = [
+        ...source.querySelectorAll<HTMLElement>("[data-og-search-occurrence]"),
+      ].find(
+        (element) =>
+          element.dataset.ogSearchSequence === String(target.sequence) &&
+          element.dataset.ogSearchQuery === target.query &&
+          (target.offset != null
+            ? element.dataset.ogSearchOffset === String(target.offset)
+            : element.dataset.ogSearchOccurrence === String(target.occurrence ?? 0)),
+      );
+      const { text, spans } = annotatableText(materialized ?? source);
+      // Inside a materialized chunk the match starts at the chunk start.
+      // Raw source offsets must NEVER be interpreted as rendered DOM offsets:
+      // even matching characters can identify a different repeated occurrence.
+      const offset = materialized
+        ? matchAtOffset(text, target.query, 0)
+        : target.offset != null
+          ? -1
+          : searchMatchOffset(text, target);
+      const range =
+        offset < 0 ? null : rangeFromOffsets(spans, offset, offset + target.query.length);
+      if (range && registry && HighlightClass)
+        registry.set(highlightName.current, new HighlightClass(range));
+      else registry?.delete(highlightName.current);
+      const rect = range ? visibleClientRect(range) : null;
+      // A custom renderer may mount the message body later (or materialize a
+      // virtualized chunk in response to renderMessageText's search context).
+      // Finding its empty shell is not proof that the occurrence was revealed.
+      if (navigated.current === key || !range || !rect) return;
+      const box = rect;
+      if (!box.height && !box.width) return;
+      scroller.scrollTop +=
+        box.top - scroller.getBoundingClientRect().top - scroller.clientHeight / 2;
+      navigated.current = key;
+    };
+    const schedule = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(update);
+    };
+    const observer = new MutationObserver(schedule);
+    observer.observe(scroller, { childList: true, subtree: true, characterData: true });
+    const resize = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(schedule);
+    resize?.observe(scroller);
+    schedule();
+    return () => {
+      observer.disconnect();
+      resize?.disconnect();
+      cancelAnimationFrame(frame);
+      registry?.delete(highlightName.current);
+      style.remove();
+    };
+  }, [key, root, itemId, target, releasePin, revision]);
+}

package/src/components/timeline-settlement.ts

@@ -0,0 +1,60 @@
+import type { TimelineGroup } from "../timeline/types";
+import { timelineHasReader } from "./timeline-anchor";
+
+export type TimelineSettlement = { element: HTMLElement; top: number };
+
+/** Capture only a retained answer at a real live→settled boundary, never history load. */
+export function captureTimelineSettlement(
+  scroller: HTMLElement,
+  groups: readonly { key: string; group: TimelineGroup }[],
+): TimelineSettlement | null {
+  // Selectionchange can arrive after this commit. Inspect ownership directly
+  // as well as the caller's pin latch so that race cannot move selected text.
+  if (timelineHasReader(scroller)) return null;
+  const live = Array.from(
+    scroller.querySelectorAll(
+      '[data-og-exchange-status="working"], [data-og-exchange-status="waiting"]',
+    ),
+  );
+  // At the live tip the newest retained answer owns the transition. An older
+  // waiting/incomplete row must not mask it, including batched settlements.
+  for (const status of live.reverse()) {
+    const row = status.closest<HTMLElement>("[data-og-group-key]");
+    const index = groups.findIndex(({ key }) => key === row?.dataset.ogGroupKey);
+    const work = groups[index]?.group;
+    const answer = groups[index + 1];
+    if (
+      work?.kind !== "activity" ||
+      !work.work?.endedAt ||
+      answer?.group.kind !== "item" ||
+      answer.group.item.kind !== "agent-message"
+    )
+      continue;
+    const element = Array.from(scroller.querySelectorAll<HTMLElement>("[data-og-group-key]")).find(
+      (node) => node.dataset.ogGroupKey === answer.key,
+    );
+    if (element) return { element, top: element.getBoundingClientRect().top };
+  }
+  return null;
+}
+
+/**
+ * Folding earlier prose can clamp scrollTop before paint. Keep the retained
+ * answer visually continuous after the normal scroll authority has run. This
+ * is one local position transition, not a new scroll writer or a presence tree.
+ */
+export function animateTimelineSettlement(snapshot: TimelineSettlement): Animation | null {
+  const { element, top } = snapshot;
+  if (!element.isConnected || typeof element.animate !== "function") return null;
+  const delta = top - element.getBoundingClientRect().top;
+  if (Math.abs(delta) < 1) return null;
+  return element.animate(
+    [{ transform: `translateY(${delta}px)` }, { transform: "translateY(0)" }],
+    {
+      id: "og-timeline-settlement",
+      // Match the existing activity-rail collapse; reduced motion is gated by the caller.
+      duration: 320,
+      easing: "cubic-bezier(0.22, 1, 0.36, 1)",
+    },
+  );
+}