@grackle-ai/web-components 0.107.2

package/src/hooks/useEventSelection.test.ts

@@ -0,0 +1,204 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useEventSelection } from "./useEventSelection.js";
+import type { DisplayEvent } from "../utils/sessionEvents.js";
+
+/** Build a minimal DisplayEvent. */
+function makeEvent(eventType: string, content: string = ""): DisplayEvent {
+  return {
+    sessionId: "sess-1",
+    eventType,
+    timestamp: "2026-01-15T14:34:00Z",
+    content,
+  };
+}
+
+/** Sample events: 5 content-bearing + 1 status (non-content). */
+const SAMPLE_EVENTS: DisplayEvent[] = [
+  makeEvent("user_input", "Hello"),          // 0
+  makeEvent("text", "Response 1"),            // 1
+  makeEvent("status", "running"),             // 2 (non-content)
+  makeEvent("tool_result", "file contents"),  // 3
+  makeEvent("text", "Response 2"),            // 4
+  makeEvent("error", "Something broke"),      // 5
+];
+
+const mockFormat = vi.fn((events: DisplayEvent[]) =>
+  events.map((e) => e.content).join("\n"),
+);
+
+function renderSelection(events: DisplayEvent[] = SAMPLE_EVENTS): ReturnType<typeof renderHook<ReturnType<typeof useEventSelection>, unknown>> {
+  return renderHook(() =>
+    useEventSelection({ events, formatForClipboard: mockFormat }),
+  );
+}
+
+describe("useEventSelection", () => {
+  beforeEach(() => {
+    mockFormat.mockClear();
+  });
+
+  it("starts in non-selecting mode with empty selection", () => {
+    const { result } = renderSelection();
+    expect(result.current.isSelecting).toBe(false);
+    expect(result.current.selectedCount).toBe(0);
+    expect(result.current.selectedIndices.size).toBe(0);
+  });
+
+  it("enters selection mode with an initial index", () => {
+    const { result } = renderSelection();
+    act(() => { result.current.enterSelectionMode(1); });
+    expect(result.current.isSelecting).toBe(true);
+    expect(result.current.selectedCount).toBe(1);
+    expect(result.current.selectedIndices.has(1)).toBe(true);
+  });
+
+  it("enters selection mode without an initial index", () => {
+    const { result } = renderSelection();
+    act(() => { result.current.enterSelectionMode(); });
+    expect(result.current.isSelecting).toBe(true);
+    expect(result.current.selectedCount).toBe(0);
+  });
+
+  it("cancels selection mode and clears selection", () => {
+    const { result } = renderSelection();
+    act(() => { result.current.enterSelectionMode(0); });
+    act(() => { result.current.toggleEvent(1); });
+    expect(result.current.selectedCount).toBe(2);
+
+    act(() => { result.current.cancelSelection(); });
+    expect(result.current.isSelecting).toBe(false);
+    expect(result.current.selectedCount).toBe(0);
+  });
+
+  it("toggles individual events on and off", () => {
+    const { result } = renderSelection();
+    act(() => { result.current.enterSelectionMode(0); });
+
+    // Toggle on index 3
+    act(() => { result.current.toggleEvent(3); });
+    expect(result.current.selectedIndices.has(0)).toBe(true);
+    expect(result.current.selectedIndices.has(3)).toBe(true);
+    expect(result.current.selectedCount).toBe(2);
+
+    // Toggle off index 0
+    act(() => { result.current.toggleEvent(0); });
+    expect(result.current.selectedIndices.has(0)).toBe(false);
+    expect(result.current.selectedCount).toBe(1);
+  });
+
+  it("shift-click selects a range of content-bearing events", () => {
+    const { result } = renderSelection();
+    act(() => { result.current.enterSelectionMode(0); });
+
+    // Shift-click index 4 should select 0, 1, 3, 4 (skip 2 which is status)
+    act(() => { result.current.toggleEvent(4, true); });
+    expect(result.current.selectedIndices.has(0)).toBe(true);
+    expect(result.current.selectedIndices.has(1)).toBe(true);
+    expect(result.current.selectedIndices.has(2)).toBe(false); // status event skipped
+    expect(result.current.selectedIndices.has(3)).toBe(true);
+    expect(result.current.selectedIndices.has(4)).toBe(true);
+    expect(result.current.selectedCount).toBe(4);
+  });
+
+  it("shift-click works in reverse direction", () => {
+    const { result } = renderSelection();
+    act(() => { result.current.enterSelectionMode(4); });
+
+    // Shift-click index 1 should select 1, 3, 4 (skip 2)
+    act(() => { result.current.toggleEvent(1, true); });
+    expect(result.current.selectedIndices.has(1)).toBe(true);
+    expect(result.current.selectedIndices.has(2)).toBe(false);
+    expect(result.current.selectedIndices.has(3)).toBe(true);
+    expect(result.current.selectedIndices.has(4)).toBe(true);
+  });
+
+  it("selectAll selects only content-bearing events", () => {
+    const { result } = renderSelection();
+    act(() => { result.current.enterSelectionMode(); });
+    act(() => { result.current.selectAll(); });
+
+    // Indices 0, 1, 3, 4, 5 are content-bearing; 2 is status
+    expect(result.current.selectedCount).toBe(5);
+    expect(result.current.selectedIndices.has(0)).toBe(true);
+    expect(result.current.selectedIndices.has(1)).toBe(true);
+    expect(result.current.selectedIndices.has(2)).toBe(false);
+    expect(result.current.selectedIndices.has(3)).toBe(true);
+    expect(result.current.selectedIndices.has(4)).toBe(true);
+    expect(result.current.selectedIndices.has(5)).toBe(true);
+  });
+
+  it("exits selection mode when last event is deselected", () => {
+    const { result } = renderSelection();
+    act(() => { result.current.enterSelectionMode(0); });
+    expect(result.current.isSelecting).toBe(true);
+    expect(result.current.selectedCount).toBe(1);
+
+    // Deselect the only selected event
+    act(() => { result.current.toggleEvent(0); });
+    expect(result.current.isSelecting).toBe(false);
+    expect(result.current.selectedCount).toBe(0);
+  });
+
+  it("deselectAll clears selection but stays in selection mode", () => {
+    const { result } = renderSelection();
+    act(() => { result.current.enterSelectionMode(0); });
+    act(() => { result.current.toggleEvent(1); });
+    expect(result.current.selectedCount).toBe(2);
+
+    act(() => { result.current.deselectAll(); });
+    expect(result.current.isSelecting).toBe(true);
+    expect(result.current.selectedCount).toBe(0);
+  });
+
+  it("copySelected calls formatForClipboard with selected events in order", async () => {
+    // Mock clipboard
+    Object.assign(navigator, {
+      clipboard: { writeText: vi.fn().mockResolvedValue(undefined) },
+    });
+
+    const { result } = renderSelection();
+    act(() => { result.current.enterSelectionMode(4); });
+    act(() => { result.current.toggleEvent(0); });
+
+    let success = false;
+    await act(async () => {
+      success = await result.current.copySelected();
+    });
+
+    expect(success).toBe(true);
+    expect(mockFormat).toHaveBeenCalledTimes(1);
+    // Events should be in index order (0 before 4), not selection order
+    const calledWith = mockFormat.mock.calls[0][0] as DisplayEvent[];
+    expect(calledWith[0].content).toBe("Hello");       // index 0
+    expect(calledWith[1].content).toBe("Response 2");   // index 4
+  });
+
+  it("copySelected returns false when clipboard fails", async () => {
+    Object.assign(navigator, {
+      clipboard: { writeText: vi.fn().mockRejectedValue(new Error("denied")) },
+    });
+
+    const { result } = renderSelection();
+    act(() => { result.current.enterSelectionMode(0); });
+
+    let success = true;
+    await act(async () => {
+      success = await result.current.copySelected();
+    });
+    expect(success).toBe(false);
+  });
+
+  it("copySelected returns false when nothing is selected", async () => {
+    const { result } = renderSelection();
+    act(() => { result.current.enterSelectionMode(); });
+
+    let success = true;
+    await act(async () => {
+      success = await result.current.copySelected();
+    });
+    expect(success).toBe(false);
+    expect(mockFormat).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useEventSelection.ts

@@ -0,0 +1,158 @@
+/**
+ * Selection state management for the multi-select feature in EventStream.
+ *
+ * Manages entering/exiting selection mode, toggling individual events,
+ * shift-click range selection, select all, and clipboard copy.
+ *
+ * @module
+ */
+
+import { useState, useRef, useCallback, useMemo } from "react";
+import type { DisplayEvent } from "../utils/sessionEvents.js";
+import { isContentBearingEvent } from "../utils/eventContent.js";
+
+/** Options for the useEventSelection hook. */
+export interface UseEventSelectionOptions {
+  /** All events currently in the stream. */
+  events: DisplayEvent[];
+  /** Formats events as text for the clipboard. */
+  formatForClipboard: (events: DisplayEvent[]) => string;
+}
+
+/** Return value of the useEventSelection hook. */
+export interface UseEventSelectionReturn {
+  /** Whether selection mode is active. */
+  isSelecting: boolean;
+  /** Set of selected event indices (from the events array). */
+  selectedIndices: ReadonlySet<number>;
+  /** Number of selected events. */
+  selectedCount: number;
+  /** Enter selection mode, optionally selecting an initial event. */
+  enterSelectionMode: (initialIndex?: number) => void;
+  /** Exit selection mode and clear all selections. */
+  cancelSelection: () => void;
+  /** Toggle an event at the given index. When shiftKey is true, selects the range from the last-toggled anchor. */
+  toggleEvent: (index: number, shiftKey?: boolean) => void;
+  /** Select all content-bearing events. */
+  selectAll: () => void;
+  /** Deselect all events but stay in selection mode. */
+  deselectAll: () => void;
+  /** Copy selected events to clipboard. Returns true on success. */
+  copySelected: () => Promise<boolean>;
+}
+
+/**
+ * Hook that manages event selection state for the EventStream multi-select feature.
+ *
+ * The caller is responsible for rendering checkboxes, highlights, and action bars
+ * based on the returned state. The `copySelected` method uses `navigator.clipboard`
+ * and will return `false` in environments where the Clipboard API is unavailable.
+ */
+export function useEventSelection({
+  events,
+  formatForClipboard,
+}: UseEventSelectionOptions): UseEventSelectionReturn {
+  const [isSelecting, setIsSelecting] = useState(false);
+  const [selectedIndices, setSelectedIndices] = useState<ReadonlySet<number>>(new Set());
+  /** Anchor index for shift-click range selection. */
+  const anchorRef = useRef<number | undefined>(undefined);
+
+  const selectedCount = useMemo(() => selectedIndices.size, [selectedIndices]);
+
+  const enterSelectionMode = useCallback((initialIndex?: number) => {
+    setIsSelecting(true);
+    if (initialIndex !== undefined) {
+      setSelectedIndices(new Set([initialIndex]));
+      anchorRef.current = initialIndex;
+    } else {
+      setSelectedIndices(new Set());
+      anchorRef.current = undefined;
+    }
+  }, []);
+
+  const cancelSelection = useCallback(() => {
+    setIsSelecting(false);
+    setSelectedIndices(new Set());
+    anchorRef.current = undefined;
+  }, []);
+
+  const toggleEvent = useCallback(
+    (index: number, shiftKey?: boolean) => {
+      if (shiftKey && anchorRef.current !== undefined) {
+        // Range selection: select all content-bearing events between anchor and index
+        const start = Math.min(anchorRef.current, index);
+        const end = Math.max(anchorRef.current, index);
+        setSelectedIndices((prev) => {
+          const next = new Set(prev);
+          for (let i = start; i <= end; i++) {
+            if (i < events.length && isContentBearingEvent(events[i])) {
+              next.add(i);
+            }
+          }
+          return next;
+        });
+      } else {
+        // Single toggle — exit selection mode if deselecting the last item
+        setSelectedIndices((prev) => {
+          const next = new Set(prev);
+          if (next.has(index)) {
+            next.delete(index);
+          } else {
+            next.add(index);
+          }
+          if (next.size === 0) {
+            setIsSelecting(false);
+            anchorRef.current = undefined;
+          } else {
+            anchorRef.current = index;
+          }
+          return next;
+        });
+      }
+    },
+    [events],
+  );
+
+  const selectAll = useCallback(() => {
+    const all = new Set<number>();
+    for (let i = 0; i < events.length; i++) {
+      if (isContentBearingEvent(events[i])) {
+        all.add(i);
+      }
+    }
+    setSelectedIndices(all);
+  }, [events]);
+
+  const deselectAll = useCallback(() => {
+    setSelectedIndices(new Set());
+  }, []);
+
+  const copySelected = useCallback(async (): Promise<boolean> => {
+    const sorted = [...selectedIndices].sort((a, b) => a - b);
+    const selectedEvents = sorted
+      .filter((i) => i < events.length)
+      .map((i) => events[i]);
+    if (selectedEvents.length === 0) {
+      return false;
+    }
+    const text = formatForClipboard(selectedEvents);
+    try {
+      await navigator.clipboard.writeText(text);
+      return true;
+    } catch {
+      return false;
+    }
+  }, [selectedIndices, events, formatForClipboard]);
+
+  return {
+    isSelecting,
+    selectedIndices,
+    selectedCount,
+    enterSelectionMode,
+    cancelSelection,
+    toggleEvent,
+    selectAll,
+    deselectAll,
+    copySelected,
+  };
+}

package/src/hooks/useSmartScroll.ts

@@ -0,0 +1,151 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, type RefObject } from "react";
+import { isNearAnchor, computeScrollCompensation, SCROLL_ANCHOR_THRESHOLD_PX } from "../utils/scrollUtils.js";
+
+/** Options for the useSmartScroll hook. */
+interface UseSmartScrollOptions {
+  /** Ref to the scrollable container element. */
+  // eslint-disable-next-line @rushstack/no-new-null
+  scrollRef: RefObject<HTMLDivElement | null>;
+  /** Length of the content list — triggers scroll checks on change. */
+  contentLength: number;
+  /** Whether newest-at-top mode is active (anchor is top instead of bottom). */
+  isReversed: boolean;
+  /** When true, auto-scroll is suppressed (e.g. during multi-select mode). */
+  paused?: boolean;
+}
+
+/** Return value from the useSmartScroll hook. */
+interface UseSmartScrollReturn {
+  /** Whether the user is currently at the anchor position (bottom or top). */
+  isAtAnchor: boolean;
+  /** Smooth-scrolls to the anchor and re-enables auto-scroll. */
+  scrollToAnchor: () => void;
+}
+
+/**
+ * Smart auto-scroll hook that respects user reading position.
+ *
+ * - Auto-scrolls to anchor (bottom or top) when new content arrives and user is at anchor.
+ * - Detects when user scrolls away from anchor and disables auto-scroll.
+ * - Provides a callback to manually scroll back to anchor.
+ * - In reverse mode, compensates scrollTop to prevent viewport shift from prepended content.
+ */
+export function useSmartScroll({
+  scrollRef,
+  contentLength,
+  isReversed,
+  paused,
+}: UseSmartScrollOptions): UseSmartScrollReturn {
+  const [isAtAnchor, setIsAtAnchor] = useState(true);
+  const prevScrollHeightRef = useRef<number>(0);
+  const mountedRef = useRef(false);
+  const rafIdRef = useRef<number>(0);
+
+  // Throttled scroll listener — uses rAF to avoid excessive React work during fast scrolling.
+  // Only calls setState when the boolean actually changes.
+  useEffect(() => {
+    const element = scrollRef.current;
+    if (!element) {
+      return;
+    }
+
+    let lastKnownValue: boolean = true;
+
+    const handleScroll = (): void => {
+      if (rafIdRef.current) {
+        return;
+      }
+      rafIdRef.current = requestAnimationFrame(() => {
+        rafIdRef.current = 0;
+        const near = isNearAnchor(
+          element.scrollTop,
+          element.scrollHeight,
+          element.clientHeight,
+          isReversed,
+          SCROLL_ANCHOR_THRESHOLD_PX,
+        );
+        if (near !== lastKnownValue) {
+          lastKnownValue = near;
+          setIsAtAnchor(near);
+        }
+      });
+    };
+
+    element.addEventListener("scroll", handleScroll, { passive: true });
+    return () => {
+      element.removeEventListener("scroll", handleScroll);
+      if (rafIdRef.current) {
+        cancelAnimationFrame(rafIdRef.current);
+        rafIdRef.current = 0;
+      }
+    };
+  }, [scrollRef, isReversed]);
+
+  // Initial scroll — useLayoutEffect to avoid flash before paint
+  useLayoutEffect(() => {
+    const element = scrollRef.current;
+    if (!element || mountedRef.current) {
+      return;
+    }
+    mountedRef.current = true;
+    if (isReversed) {
+      element.scrollTop = 0;
+    } else {
+      element.scrollTop = element.scrollHeight;
+    }
+    setIsAtAnchor(true);
+  }, [scrollRef, isReversed]);
+
+  // Auto-scroll on new content + reverse-mode compensation.
+  // prevScrollHeightRef is captured at the END of this effect so the NEXT
+  // invocation sees the prior commit's scrollHeight (not the current one).
+  useLayoutEffect(() => {
+    const element = scrollRef.current;
+    if (!element) {
+      return;
+    }
+
+    // Skip auto-scroll while paused (e.g. during multi-select mode) to avoid
+    // disrupting the user's selection. Still update prevScrollHeight so scroll
+    // compensation is correct when unpaused.
+    if (paused) {
+      prevScrollHeightRef.current = element.scrollHeight;
+      return;
+    }
+
+    if (isReversed && !isAtAnchor) {
+      // Compensate scrollTop to prevent viewport shift from prepended content
+      const compensation = computeScrollCompensation(
+        prevScrollHeightRef.current,
+        element.scrollHeight,
+      );
+      if (compensation > 0) {
+        element.scrollTop += compensation;
+      }
+    }
+
+    if (isAtAnchor) {
+      if (isReversed) {
+        element.scrollTo({ top: 0, behavior: "smooth" });
+      } else {
+        element.scrollTo({ top: element.scrollHeight, behavior: "smooth" });
+      }
+    }
+
+    // Update prevScrollHeight AFTER applying compensation/auto-scroll
+    // so the next render can compute the delta correctly.
+    prevScrollHeightRef.current = element.scrollHeight;
+  }, [contentLength, isAtAnchor, isReversed, paused, scrollRef]);
+
+  const scrollToAnchor = useCallback((): void => {
+    const element = scrollRef.current;
+    if (!element) {
+      return;
+    }
+    const target = isReversed ? 0 : element.scrollHeight;
+    element.scrollTo({ top: target, behavior: "smooth" });
+    setIsAtAnchor(true);
+  }, [scrollRef, isReversed]);
+
+  return { isAtAnchor, scrollToAnchor };
+}