@lostgradient/cinder 0.5.0 → 0.6.0

package/src/components/chat/container/use-chat-scroll-state.svelte.ts

@@ -1,417 +0,0 @@
-/**
- * Runes helper for chat scroll state management.
- *
- * Manages:
- * - atBottom state for auto-scroll decisions
- * - showJumpButton state for jump-to-latest visibility
- * - Scroll event listener attachment
- * - IntersectionObserver for bottom sentinel
- * - Imperative scroll methods
- */
-
-import type { Attachment } from 'svelte/attachments';
-import { useReducedMotion } from '../../../utilities/use-reduced-motion.svelte.ts';
-import type { ChatScrollStateChangeEvent } from './chat-events.ts';
-import {
-  isAtBottom as checkIsAtBottom,
-  DEFAULT_SCROLL_CONFIGURATION,
-  shouldShowJumpToLatest,
-} from './scroll-utilities';
-
-/**
- * Cleanup resources.
- *
- * No-op: this helper owns no long-lived resources. IntersectionObserver
- * cleanup is handled by the disconnect function returned from
- * `createSentinelObserver`. Exposed for API symmetry with consumers that
- * call `destroy()` unconditionally on teardown.
- */
-const destroy = (): void => {};
-
-// ==========================================================================
-// Types
-// ==========================================================================
-
-// Re-export the event type from chat.svelte for API consistency
-export type { ChatScrollStateChangeEvent as ScrollStateChangeEvent } from './chat-events.ts';
-
-/** Options for the scroll state helper */
-export interface UseChatScrollStateOptions {
-  /** Pixels from bottom to consider "at bottom" (default: 150) */
-  bottomThreshold?: number;
-  /** Getter for bottom threshold to avoid stale local references */
-  getBottomThreshold?: () => number;
-  /** Pixels scrolled before showing jump button (default: 200) */
-  jumpThreshold?: number;
-  /** Getter for jump threshold to avoid stale local references */
-  getJumpThreshold?: () => number;
-  /**
-   * Callback when scroll state changes.
-   *
-   * **Important:** Always read values from the event argument, not from bindings.
-   * The callback fires before bindable props are synchronized, so bindings may
-   * contain stale values during the callback.
-   */
-  onScrollStateChange?: (event: ChatScrollStateChangeEvent) => void;
-  /** Callback when scroll reaches bottom (for clearing unread state) */
-  onReachBottom?: () => void;
-}
-
-/** Return type for the scroll state helper */
-export interface UseChatScrollStateReturn {
-  /** Whether the viewport is at or near the bottom */
-  readonly atBottom: boolean;
-  /** Whether the jump-to-latest button should be visible */
-  readonly showJumpButton: boolean;
-  /** Whether user is in a smooth scroll animation (used by parent for auto-scroll logic) */
-  readonly isUserScrolling: boolean;
-  /** Set atBottom state directly */
-  setAtBottom(value: boolean): void;
-  /** Create a scroll event listener attachment for the viewport */
-  createScrollAttachment(): Attachment<HTMLElement>;
-  /**
-   * Create an IntersectionObserver for the bottom sentinel.
-   * Returns a cleanup function, or undefined if elements are missing.
-   */
-  createSentinelObserver(
-    viewport: HTMLElement | null,
-    sentinel: HTMLElement | null,
-  ): (() => void) | undefined;
-  /**
-   * IntersectionObserver callback for the bottom sentinel element.
-   * Use with useIntersection for attachment-based wiring:
-   * `{@attach useIntersection(scrollState.handleSentinelEntry, { root: viewport, ... })}`.
-   */
-  handleSentinelEntry(entry: IntersectionObserverEntry): void;
-  /** Scroll to the bottom of the viewport */
-  scrollToBottom(viewport: HTMLElement | null): void;
-  /** Scroll to the top of the viewport */
-  scrollToTop(viewport: HTMLElement | null): void;
-  /**
-   * Jump to the latest message with animation.
-   * Handles smooth scroll and focuses the last message after animation.
-   */
-  jumpToLatest(viewport: HTMLElement | null, onComplete?: () => void): void;
-  /** Get the appropriate scroll behavior based on user preference */
-  getScrollBehavior(): ScrollBehavior;
-  /** Cleanup resources */
-  destroy(): void;
-}
-
-// ==========================================================================
-// Utilities
-// ==========================================================================
-
-// ==========================================================================
-// Helper
-// ==========================================================================
-
-/**
- * Creates reactive state and methods for managing chat scroll behavior.
- *
- * @example
- * ```svelte
- * <script lang="ts">
- *   import { useChatScrollState } from './use-chat-scroll-state.svelte';
- *
- *   const scrollState = useChatScrollState({
- *     bottomThreshold: 150,
- *     jumpThreshold: 200,
- *     onScrollStateChange: (event) => console.log('Scroll:', event),
- *     onReachBottom: () => unreadState.markAllAsRead(),
- *   });
- *
- *   const scrollAttachment = scrollState.createScrollAttachment();
- *
- *   // Wire the bottom sentinel with useIntersection via {@attach}. Wrap in $derived so
- *   // the observer is stable across re-renders (recreated only when root/threshold change).
- *   const sentinelAttach = $derived(
- *     useIntersection(scrollState.handleSentinelEntry, {
- *       root: viewport,
- *       rootMargin: `0px 0px 150px 0px`,
- *     }),
- *   );
- * </script>
- *
- * <div bind:this={viewport} {@attach scrollAttachment}>
- *   <!-- content -->
- *   <div {@attach sentinelAttach}></div>
- * </div>
- *
- * {#if scrollState.showJumpButton}
- *   <button onclick={() => scrollState.jumpToLatest(viewport)}>
- *     Jump to latest
- *   </button>
- * {/if}
- * ```
- */
-export function useChatScrollState(options?: UseChatScrollStateOptions): UseChatScrollStateReturn {
-  const {
-    bottomThreshold = DEFAULT_SCROLL_CONFIGURATION.bottomThreshold,
-    getBottomThreshold,
-    jumpThreshold = DEFAULT_SCROLL_CONFIGURATION.jumpThreshold,
-    getJumpThreshold,
-    onScrollStateChange,
-    onReachBottom,
-  } = options ?? {};
-
-  // Shared reduced-motion preference (OVERLAY-POLICY: use the shared hook, not inline matchMedia).
-  const reducedMotion = useReducedMotion();
-
-  /**
-   * Returns the appropriate scroll behavior based on user preference.
-   * Respects prefers-reduced-motion by using 'auto' instead of 'smooth'.
-   */
-  function getScrollBehavior(): ScrollBehavior {
-    return reducedMotion.current ? 'auto' : 'smooth';
-  }
-
-  // Reactive state
-  let atBottom = $state(true);
-  let showJumpButton = $state(false);
-
-  // Non-reactive bookkeeping
-  let scrollTicking = false;
-  let isUserScrolling = false; // Prevents auto-scroll from interrupting user-initiated smooth scroll
-  // Cancel function for the in-flight withForcedLayout session, if any. A new
-  // session cancels the previous one's listeners/timer before starting its
-  // own — see withForcedLayout below for why this matters.
-  let activeForcedLayoutCancel: (() => void) | null = null;
-
-  /**
-   * Set atBottom state directly.
-   */
-  function setAtBottom(value: boolean): void {
-    atBottom = value;
-  }
-
-  /**
-   * Create a scroll event listener attachment for the viewport.
-   */
-  function createScrollAttachment(): Attachment<HTMLElement> {
-    return (element) => {
-      function handleScroll() {
-        if (scrollTicking) return;
-
-        scrollTicking = true;
-        requestAnimationFrame(() => {
-          const state = {
-            scrollTop: element.scrollTop,
-            scrollHeight: element.scrollHeight,
-            clientHeight: element.clientHeight,
-          };
-
-          const scrolledToBottom = checkIsAtBottom(
-            state,
-            getBottomThreshold?.() ?? bottomThreshold,
-          );
-          const shouldShowJump = shouldShowJumpToLatest(
-            state,
-            getJumpThreshold?.() ?? jumpThreshold,
-          );
-
-          // Update reactive state
-          atBottom = scrolledToBottom;
-          showJumpButton = shouldShowJump;
-
-          // Clear unread when scrolled to bottom
-          if (scrolledToBottom) {
-            onReachBottom?.();
-          }
-
-          // Emit scroll state change
-          onScrollStateChange?.({
-            atBottom: scrolledToBottom,
-            scrollTop: state.scrollTop,
-            scrollHeight: state.scrollHeight,
-          });
-
-          scrollTicking = false;
-        });
-      }
-
-      element.addEventListener('scroll', handleScroll, { passive: true });
-      return () => element.removeEventListener('scroll', handleScroll);
-    };
-  }
-
-  /**
-   * IntersectionObserver callback for the bottom sentinel element.
-   * Exposed for use with useIntersection attachment-based wiring.
-   */
-  function handleSentinelEntry(entry: IntersectionObserverEntry): void {
-    const sentinelVisible = entry.isIntersecting;
-    if (sentinelVisible && !atBottom) {
-      atBottom = true;
-      onReachBottom?.();
-    }
-  }
-
-  /**
-   * Create an IntersectionObserver for the bottom sentinel.
-   * @deprecated Prefer `{@attach useIntersection(scrollState.handleSentinelEntry, { root: viewport, rootMargin })}` on the sentinel element.
-   */
-  function createSentinelObserver(
-    viewport: HTMLElement | null,
-    sentinel: HTMLElement | null,
-  ): (() => void) | undefined {
-    if (!viewport || !sentinel) return;
-
-    const observer = new IntersectionObserver(
-      ([entry]) => {
-        if (!entry) return;
-        handleSentinelEntry(entry);
-      },
-      {
-        root: viewport,
-        threshold: 0,
-        rootMargin: `0px 0px ${getBottomThreshold?.() ?? bottomThreshold}px 0px`,
-      },
-    );
-
-    observer.observe(sentinel);
-    return () => observer.disconnect();
-  }
-
-  /**
-   * Forces every row to lay out at its real height before a programmatic
-   * scroll-to-bottom, then restores the content-visibility optimization once
-   * the scroll settles.
-   *
-   * Off-screen `.chat-message` rows use `content-visibility: auto` with a
-   * 180px estimate (`contain-intrinsic-size`) until they're painted. Calling
-   * `scrollTo({ top: viewport.scrollHeight, behavior: 'smooth' })` captures a
-   * target computed from those estimates; as the animation scrolls estimated
-   * rows into view, they resize to their real height, which shifts content
-   * under the fixed pixel target mid-flight — visible as a jerk right as the
-   * scroll finishes. Forcing layout up front (`data-cinder-force-visible`)
-   * makes the target accurate from the start.
-   *
-   * The `scrollend` listener restores the optimization as soon as the
-   * animation actually finishes. The timeout is a backstop for environments
-   * without `scrollend` support and for a zero-distance scroll (already at
-   * the bottom), where neither `scroll` nor `scrollend` ever fires — but it
-   * re-arms on every `scroll` tick rather than firing once on a fixed clock,
-   * so a scroll animation that legitimately runs longer than the backstop
-   * duration (a long transcript, a slower device) can never have the
-   * optimization restored out from under it mid-flight, which would let
-   * off-screen rows resize again before the scroll settles — the exact jerk
-   * this exists to prevent.
-   *
-   * A second call before the first session settles (e.g. a double-click on
-   * jump-to-latest, or auto-scroll firing while a prior scroll is still in
-   * flight) cancels the earlier session's listeners/timer first. Without
-   * this, the OLDER session's own scrollend/backstop could still fire and
-   * strip the attribute while the NEWER scroll animation is still running —
-   * the same jerk this whole mechanism exists to prevent, just reintroduced
-   * by an overlapping call instead of a single long one.
-   */
-  function withForcedLayout(viewport: HTMLElement, scroll: () => void): void {
-    activeForcedLayoutCancel?.();
-
-    viewport.setAttribute('data-cinder-force-visible', '');
-    // Force a synchronous layout so scrollHeight (read inside `scroll`)
-    // reflects every row's real height, not the content-visibility estimate.
-    void viewport.offsetHeight;
-
-    let settled = false;
-    let backstop: ReturnType<typeof setTimeout>;
-    const backstopDuration = reducedMotion.current ? 50 : 500;
-
-    function cancel() {
-      if (settled) return;
-      settled = true;
-      clearTimeout(backstop);
-      viewport.removeEventListener('scrollend', restore);
-      viewport.removeEventListener('scroll', armBackstop);
-    }
-
-    const restore = () => {
-      if (settled) return;
-      cancel();
-      activeForcedLayoutCancel = null;
-      viewport.removeAttribute('data-cinder-force-visible');
-    };
-
-    function armBackstop() {
-      clearTimeout(backstop);
-      backstop = setTimeout(restore, backstopDuration);
-    }
-
-    activeForcedLayoutCancel = cancel;
-    viewport.addEventListener('scrollend', restore, { once: true });
-    viewport.addEventListener('scroll', armBackstop, { passive: true });
-    // Covers the zero-distance case (already at bottom): no scroll/scrollend
-    // event will ever fire, so this is the only thing that restores it.
-    armBackstop();
-
-    scroll();
-  }
-
-  /**
-   * Scroll to the bottom of the viewport.
-   */
-  function scrollToBottom(viewport: HTMLElement | null): void {
-    if (!viewport) return;
-    withForcedLayout(viewport, () => {
-      viewport.scrollTo({ top: viewport.scrollHeight, behavior: getScrollBehavior() });
-    });
-  }
-
-  /**
-   * Scroll to the top of the viewport.
-   */
-  function scrollToTop(viewport: HTMLElement | null): void {
-    viewport?.scrollTo({ top: 0, behavior: getScrollBehavior() });
-  }
-
-  /**
-   * Jump to the latest message with animation.
-   */
-  function jumpToLatest(viewport: HTMLElement | null, onComplete?: () => void): void {
-    if (!viewport) return;
-
-    // Prevent auto-scroll from interrupting the smooth scroll animation
-    isUserScrolling = true;
-
-    withForcedLayout(viewport, () => {
-      viewport.scrollTo({ top: viewport.scrollHeight, behavior: getScrollBehavior() });
-    });
-    onReachBottom?.();
-    onComplete?.();
-
-    // Focus last message for keyboard users and clear the user scrolling flag
-    // after animation completes (typical smooth scroll takes ~300-500ms)
-    // For reduced motion, use minimal delay since scroll is instant
-    const scrollDuration = reducedMotion.current ? 50 : 500;
-    setTimeout(() => {
-      isUserScrolling = false;
-      const wrappers = viewport.querySelectorAll<HTMLElement>('.chat-message-wrapper');
-      const lastWrapper = wrappers.length > 0 ? wrappers[wrappers.length - 1] : null;
-      const lastMessage = lastWrapper?.querySelector<HTMLElement>('.chat-message') ?? null;
-      lastMessage?.focus();
-    }, scrollDuration);
-  }
-
-  return {
-    get atBottom() {
-      return atBottom;
-    },
-    get showJumpButton() {
-      return showJumpButton;
-    },
-    setAtBottom,
-    createScrollAttachment,
-    createSentinelObserver,
-    handleSentinelEntry,
-    scrollToBottom,
-    scrollToTop,
-    jumpToLatest,
-    getScrollBehavior,
-    destroy,
-    // Exposed helper for auto-scroll logic, used by the parent component
-    get isUserScrolling() {
-      return isUserScrolling;
-    },
-  };
-}

package/src/components/chat/container/use-chat-search.svelte.ts

@@ -1,178 +0,0 @@
-/**
- * Runes helper for in-conversation message search.
- *
- * Manages:
- * - Search query state
- * - Open/closed state for the search bar
- * - Derived list of matching messages (with their indices)
- * - Current match index for navigation
- */
-
-import type { Message } from '../conversation-model.ts';
-import { getMessageText } from '../utilities/utilities.js';
-
-// ==========================================================================
-// Types
-// ==========================================================================
-
-/** A single search result: message and its position in the messages array */
-export interface ChatSearchMatch {
-  /** The matching message */
-  message: Message;
-  /** Index of the message in the full messages array */
-  messageIndex: number;
-}
-
-/** Options for the search helper */
-export interface UseChatSearchOptions {
-  /** Getter for the current list of messages */
-  getMessages: () => Message[];
-}
-
-/** Return type for the search helper */
-export interface UseChatSearchReturn {
-  /** Current search query string */
-  readonly query: string;
-  /** Whether the search bar is open */
-  readonly isOpen: boolean;
-  /** All messages that match the current query */
-  readonly matches: ChatSearchMatch[];
-  /** Total number of matches */
-  readonly matchCount: number;
-  /** The currently highlighted match, or null if no matches */
-  readonly currentMatch: ChatSearchMatch | null;
-  /** Zero-based index of the current match within matches */
-  readonly currentMatchIndex: number;
-  /** Open the search bar */
-  open(): void;
-  /** Close the search bar and reset state */
-  close(): void;
-  /** Navigate to the next match (wraps around) */
-  nextMatch(): void;
-  /** Navigate to the previous match (wraps around) */
-  previousMatch(): void;
-  /** Update the search query and reset the current match to 0 */
-  setQuery(value: string): void;
-}
-
-// ==========================================================================
-// Helper
-// ==========================================================================
-
-/**
- * Creates reactive state and methods for in-conversation search.
- *
- * @example
- * ```svelte
- * <script lang="ts">
- *   import { useChatSearch } from './use-chat-search.svelte';
- *
- *   const searchState = useChatSearch({
- *     getMessages: () => messages,
- *   });
- *
- *   // Open with Ctrl/Cmd+F
- *   function handleKeyDown(event: KeyboardEvent) {
- *     if ((event.ctrlKey || event.metaKey) && event.key === 'f') {
- *       event.preventDefault();
- *       searchState.open();
- *     }
- *   }
- * </script>
- *
- * {#if searchState.isOpen}
- *   <ChatSearchBar
- *     query={searchState.query}
- *     matchCount={searchState.matchCount}
- *     currentMatchIndex={searchState.currentMatchIndex}
- *     onquerychange={searchState.setQuery}
- *     onnext={searchState.nextMatch}
- *     onprevious={searchState.previousMatch}
- *     onclose={searchState.close}
- *   />
- * {/if}
- * ```
- */
-export function useChatSearch(options: UseChatSearchOptions): UseChatSearchReturn {
-  const { getMessages } = options;
-
-  // Reactive state
-  let query = $state('');
-  let isOpen = $state(false);
-  let currentMatchIndex = $state(0);
-
-  const matches = $derived.by((): ChatSearchMatch[] => {
-    const trimmedQuery = query.trim();
-    if (!trimmedQuery) return [];
-
-    const lowercasedQuery = trimmedQuery.toLowerCase();
-    const messages = getMessages();
-
-    return messages
-      .map((message, messageIndex) => ({ message, messageIndex }))
-      .filter(({ message }) => getMessageText(message).toLowerCase().includes(lowercasedQuery));
-  });
-
-  const matchCount = $derived(matches.length);
-
-  // Clamp currentMatchIndex when the matches array shrinks (e.g., messages edited or deleted).
-  // Derived instead of $effect so this works outside component context (e.g., in unit tests).
-  const clampedMatchIndex = $derived(
-    matchCount > 0 ? Math.min(currentMatchIndex, matchCount - 1) : 0,
-  );
-
-  const currentMatch = $derived(matches[clampedMatchIndex] ?? null);
-
-  function open(): void {
-    isOpen = true;
-  }
-
-  function close(): void {
-    isOpen = false;
-    query = '';
-    currentMatchIndex = 0;
-  }
-
-  function nextMatch(): void {
-    if (matchCount > 0) {
-      currentMatchIndex = (clampedMatchIndex + 1) % matchCount;
-    }
-  }
-
-  function previousMatch(): void {
-    if (matchCount > 0) {
-      currentMatchIndex = (clampedMatchIndex - 1 + matchCount) % matchCount;
-    }
-  }
-
-  function setQuery(value: string): void {
-    query = value;
-    currentMatchIndex = 0;
-  }
-
-  return {
-    get query() {
-      return query;
-    },
-    get isOpen() {
-      return isOpen;
-    },
-    get matches() {
-      return matches;
-    },
-    get matchCount() {
-      return matchCount;
-    },
-    get currentMatch() {
-      return currentMatch;
-    },
-    get currentMatchIndex() {
-      return clampedMatchIndex;
-    },
-    open,
-    close,
-    nextMatch,
-    previousMatch,
-    setQuery,
-  };
-}