@alumbwe/anvil 1.0.0

package/src/hooks/use-scroll-management.ts

@@ -0,0 +1,184 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import type { ScrollBoxRenderable } from '@opentui/core'
+
+// Scroll detection threshold - how close to bottom to consider "at bottom"
+const SCROLL_NEAR_BOTTOM_THRESHOLD = 1
+
+// Animation constants
+const ANIMATION_FRAME_INTERVAL_MS = 16 // ~60fps
+const DEFAULT_SCROLL_ANIMATION_DURATION_MS = 200
+
+// Page scroll amount (fraction of viewport height)
+const PAGE_SCROLL_FRACTION = 0.8
+
+// Delay before auto-scrolling after content changes
+const AUTO_SCROLL_DELAY_MS = 50
+
+const easeOutCubic = (t: number): number => {
+  return 1 - Math.pow(1 - t, 3)
+}
+
+/**
+ * Manages scroll behavior for the chat scrollbox with smooth animations and auto-scroll.
+ *
+ * @param scrollRef - Reference to the scrollbox component
+ * @param messages - Array of chat messages (triggers auto-scroll on change)
+ * @param isUserCollapsing - Callback to check if user is actively collapsing/expanding toggles.
+ *                          When true, auto-scroll is temporarily suppressed to prevent jarring UX.
+ * @returns Scroll management functions and state
+ */
+export const useChatScrollbox = (
+  scrollRef: React.RefObject<ScrollBoxRenderable | null>,
+  messages: any[],
+  isUserCollapsing: () => boolean,
+) => {
+  const autoScrollEnabledRef = useRef<boolean>(true)
+  const programmaticScrollRef = useRef<boolean>(false)
+  const animationFrameRef = useRef<number | null>(null)
+  const [isAtBottom, setIsAtBottom] = useState<boolean>(true)
+
+  const cancelAnimation = useCallback(() => {
+    if (animationFrameRef.current !== null) {
+      clearTimeout(animationFrameRef.current)
+      animationFrameRef.current = null
+    }
+  }, [])
+
+  const animateScrollTo = useCallback(
+    (targetScroll: number, duration = DEFAULT_SCROLL_ANIMATION_DURATION_MS) => {
+      const scrollbox = scrollRef.current
+      if (!scrollbox) return
+
+      cancelAnimation()
+
+      const startScroll = scrollbox.scrollTop
+      const distance = targetScroll - startScroll
+      const startTime = Date.now()
+      const frameInterval = ANIMATION_FRAME_INTERVAL_MS
+
+      const animate = () => {
+        const elapsed = Date.now() - startTime
+        const progress = Math.min(elapsed / duration, 1)
+        const easedProgress = easeOutCubic(progress)
+        const newScroll = startScroll + distance * easedProgress
+
+        programmaticScrollRef.current = true
+        scrollbox.scrollTop = newScroll
+
+        if (progress < 1) {
+          animationFrameRef.current = setTimeout(animate, frameInterval) as any
+        } else {
+          animationFrameRef.current = null
+        }
+      }
+
+      animate()
+    },
+    [scrollRef, cancelAnimation],
+  )
+
+  const scrollToLatest = useCallback((): void => {
+    const scrollbox = scrollRef.current
+    if (!scrollbox) return
+
+    const maxScroll = Math.max(
+      0,
+      scrollbox.scrollHeight - scrollbox.viewport.height,
+    )
+    animateScrollTo(maxScroll)
+  }, [scrollRef, animateScrollTo])
+
+  const scrollUp = useCallback((): void => {
+    const scrollbox = scrollRef.current
+    if (!scrollbox) return
+
+    const viewportHeight = scrollbox.viewport.height
+    const scrollAmount = Math.floor(viewportHeight * PAGE_SCROLL_FRACTION)
+    const targetScroll = Math.max(0, scrollbox.scrollTop - scrollAmount)
+    animateScrollTo(targetScroll)
+  }, [scrollRef, animateScrollTo])
+
+  const scrollDown = useCallback((): void => {
+    const scrollbox = scrollRef.current
+    if (!scrollbox) return
+
+    const viewportHeight = scrollbox.viewport.height
+    const maxScroll = Math.max(
+      0,
+      scrollbox.scrollHeight - viewportHeight,
+    )
+    const scrollAmount = Math.floor(viewportHeight * PAGE_SCROLL_FRACTION)
+    const targetScroll = Math.min(maxScroll, scrollbox.scrollTop + scrollAmount)
+    animateScrollTo(targetScroll)
+  }, [scrollRef, animateScrollTo])
+
+  useEffect(() => {
+    const scrollbox = scrollRef.current
+    if (!scrollbox) return
+
+    const handleScrollChange = () => {
+      const maxScroll = Math.max(
+        0,
+        scrollbox.scrollHeight - scrollbox.viewport.height,
+      )
+      const current = scrollbox.verticalScrollBar.scrollPosition
+      const isNearBottom =
+        Math.abs(maxScroll - current) <= SCROLL_NEAR_BOTTOM_THRESHOLD
+
+      if (programmaticScrollRef.current) {
+        programmaticScrollRef.current = false
+        autoScrollEnabledRef.current = true
+        setIsAtBottom(true)
+        return
+      }
+
+      cancelAnimation()
+      autoScrollEnabledRef.current = isNearBottom
+      setIsAtBottom((prev) => (prev === isNearBottom ? prev : isNearBottom))
+    }
+
+    scrollbox.verticalScrollBar.on('change', handleScrollChange)
+
+    return () => {
+      scrollbox.verticalScrollBar.off('change', handleScrollChange)
+    }
+  }, [scrollRef, cancelAnimation])
+
+  useEffect(() => {
+    const scrollbox = scrollRef.current
+    if (scrollbox) {
+      const timeoutId = setTimeout(() => {
+        const maxScroll = Math.max(
+          0,
+          scrollbox.scrollHeight - scrollbox.viewport.height,
+        )
+
+        if (scrollbox.scrollTop > maxScroll) {
+          programmaticScrollRef.current = true
+          scrollbox.scrollTop = maxScroll
+        } else if (autoScrollEnabledRef.current && !isUserCollapsing()) {
+          programmaticScrollRef.current = true
+          scrollbox.scrollTop = maxScroll
+        }
+      }, AUTO_SCROLL_DELAY_MS)
+
+      return () => clearTimeout(timeoutId)
+    }
+    return undefined
+  }, [messages, scrollToLatest, scrollRef, isUserCollapsing])
+
+  useEffect(() => {
+    return () => {
+      cancelAnimation()
+    }
+  }, [cancelAnimation])
+
+  return {
+    scrollToLatest,
+    scrollUp,
+    scrollDown,
+    scrollboxProps: {},
+    isAtBottom,
+  }
+}

package/src/hooks/use-searchable-list.ts

@@ -0,0 +1,98 @@
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+  type Dispatch,
+  type SetStateAction,
+} from 'react'
+
+interface SearchableItem {
+  id: string
+  label: string
+}
+
+export interface UseSearchableListOptions<T extends SearchableItem> {
+  /** Items to filter */
+  items: T[]
+  /** Key that triggers reset of search and focus (e.g., currentPath) */
+  resetKey?: string
+  /** Custom filter function (defaults to case-insensitive label matching) */
+  filterFn?: (item: T, query: string) => boolean
+}
+
+export interface UseSearchableListReturn<T extends SearchableItem> {
+  /** Current search query */
+  searchQuery: string
+  /** Set the search query */
+  setSearchQuery: (query: string) => void
+  /** Currently focused item index */
+  focusedIndex: number
+  /** Set the focused index */
+  setFocusedIndex: Dispatch<SetStateAction<number>>
+  /** Filtered items based on search query */
+  filteredItems: T[]
+  /** Handle focus change from hover */
+  handleFocusChange: (index: number) => void
+}
+
+/**
+ * Hook for managing searchable list state.
+ * Handles search filtering, focus management, and automatic index clamping.
+ */
+export function useSearchableList<T extends SearchableItem>({
+  items,
+  resetKey,
+  filterFn,
+}: UseSearchableListOptions<T>): UseSearchableListReturn<T> {
+  const [searchQuery, setSearchQuery] = useState('')
+  const [focusedIndex, setFocusedIndex] = useState(0)
+
+  // Default filter function: case-insensitive label matching
+  const defaultFilterFn = useCallback(
+    (item: T, query: string) =>
+      item.label.toLowerCase().includes(query.toLowerCase()),
+    [],
+  )
+
+  const filterFunction = filterFn ?? defaultFilterFn
+
+  // Filter items based on search query
+  // Skip filtering for path-like queries (starting with / or ~) - those are for navigation, not filtering
+  const filteredItems = useMemo(() => {
+    const trimmedQuery = searchQuery.trim()
+    if (!trimmedQuery) return items
+    // Path-like queries should not filter the directory list
+    if (trimmedQuery.startsWith('/') || trimmedQuery.startsWith('~')) return items
+    // Always keep parent directory entry (..) visible, filter others
+    return items.filter((item) => 
+      item.label === '..' || filterFunction(item, trimmedQuery)
+    )
+  }, [items, searchQuery, filterFunction])
+
+  // Reset focus when resetKey changes (but keep search query)
+  useEffect(() => {
+    setFocusedIndex(0)
+  }, [resetKey])
+
+  // Clamp focused index when filtered list changes
+  useEffect(() => {
+    if (focusedIndex >= filteredItems.length) {
+      setFocusedIndex(Math.max(0, filteredItems.length - 1))
+    }
+  }, [filteredItems.length, focusedIndex])
+
+  // Handle focus change from hover
+  const handleFocusChange = useCallback((index: number) => {
+    setFocusedIndex(index)
+  }, [])
+
+  return {
+    searchQuery,
+    setSearchQuery,
+    focusedIndex,
+    setFocusedIndex,
+    filteredItems,
+    handleFocusChange,
+  }
+}