@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214-snapshot.20260528192313

package/src/hooks/.use-copy-to-clipboard.md

@@ -0,0 +1,42 @@
+<!-- source-hash: ef396b17d63aed7d69a637d3e4442715 -->
+React hook that wraps the browser Clipboard API, providing toast notifications on success or failure and a timed `copied` state reset.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `useCopyToClipboard` | Hook | Copies text to clipboard with toast feedback and `copied` state |
+| `UseCopyToClipboardOptions` | Interface | Configuration options for toast messages and reset delay |
+
+**Options:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `successTitle` | `'Copied'` | Toast title on success |
+| `successDescription` | `'Copied to clipboard'` | Toast body on success |
+| `errorTitle` | `'Copy failed'` | Toast title on failure |
+| `errorDescription` | `'Could not copy to clipboard'` | Toast body on failure |
+| `resetDelay` | `2000` | Milliseconds before `copied` resets to `false` |
+
+**Returns:** `{ copy, copied }` — the async copy function and a boolean state flag.
+
+## Usage Example
+
+```typescript
+import { useCopyToClipboard } from '@/hooks/use-copy-to-clipboard';
+
+function ApiKeyDisplay({ apiKey }: { apiKey: string }) {
+  const { copy, copied } = useCopyToClipboard({
+    successTitle: 'API Key Copied',
+    resetDelay: 3000,
+  });
+
+  return (
+    <button onClick={() => copy(apiKey)}>
+      {copied ? 'Copied!' : 'Copy API Key'}
+    </button>
+  );
+}
+```
+
+> **Note:** This hook is client-only (`'use client'`). It depends on `navigator.clipboard`, which requires a secure context (HTTPS or localhost). Failures are caught silently and surfaced via the destructive toast variant.

package/src/hooks/.use-near-viewport.md

@@ -0,0 +1,44 @@
+<!-- source-hash: 22dd3f53bc1b8db26b9d173ca6be7427 -->
+A React hook that detects when an element is approaching the viewport using a shared, module-level `IntersectionObserver` pool — one observer instance per unique `rootMargin` value, shared across all components using the hook.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `useNearViewport` | Hook | Main hook; returns `ref` and `isNear` state |
+| `UseNearViewportResult` | Interface | Return type generic over element type `T` |
+| `getObserverFor` | Internal | Lazily creates/retrieves a shared `IntersectionObserver` per `rootMargin` |
+| `observers` | `Map<string, IntersectionObserver>` | Module-level singleton pool keyed by `rootMargin` |
+| `subscribers` | `WeakMap<Element, () => void>` | Tracks per-element callbacks; auto-GC'd when elements are removed |
+
+## Usage Example
+
+```typescript
+import { useNearViewport } from './use-near-viewport';
+
+// Basic lazy-render pattern
+function MediaCard() {
+  const { ref, isNear } = useNearViewport('500px');
+  return (
+    <div ref={ref}>
+      {isNear ? <HeavyMediaComponent /> : <Placeholder />}
+    </div>
+  );
+}
+
+// Strict on-screen detection
+function AnalyticsTracker() {
+  const { ref, isNear } = useNearViewport('0px');
+  useEffect(() => {
+    if (isNear) trackImpression();
+  }, [isNear]);
+  return <div ref={ref} />;
+}
+```
+
+## Behavior Notes
+
+- **Fires once**: `isNear` flips to `true` on first intersection and never resets; the element is unobserved immediately after
+- **Shared observers**: All components using the same `rootMargin` share a single `IntersectionObserver` — efficient for grid/list pages with many cards
+- **StrictMode safe**: Cleanup uses callback identity checks to survive React's dev-mode double-mount cycle without dropping subscriptions
+- **Race safe**: IO callback re-reads `subscribers` at fire time so late-firing callbacks after unmount cannot invoke stale state setters

package/src/hooks/.use-og-placeholder.md

@@ -0,0 +1,51 @@
+<!-- source-hash: ef127df882f0312f1636164b044502e4 -->
+Thin client-side React hook that generates a branded OG placeholder image URL by delegating to a caller-supplied URL builder, keeping the lib layer free of hub-specific dependencies.
+
+## Key Components
+
+### `useOgPlaceholder`
+A memoized hook that wraps any `buildUrl` function to conditionally produce a placeholder image URL.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `buildUrl` | `(title, options) => string` | — | URL builder function (e.g. `buildOgPlaceholderUrl` from `lib/utils/entity-image.ts`) |
+| `title` | `string \| undefined \| null` | — | Text displayed on the placeholder image |
+| `siteName` | `string` | `''` | Optional site name shown below the title |
+| `enabled` | `boolean` | `true` | Gates URL generation; returns `null` when `false` |
+| `aspect` | `'wide' \| 'square'` | `'wide'` | `'wide'` = 1200×630 social card; `'square'` = 1024×1024 for compact chat-inline slots |
+
+**Returns:** `string | null` — the generated URL, or `null` if disabled or `title` is falsy.
+
+## Usage Example
+
+```typescript
+import { useOgPlaceholder } from './use-og-placeholder'
+import { buildOgPlaceholderUrl } from 'lib/utils/entity-image'
+
+function ArticleCard({ title, site }: { title: string; site: string }) {
+  // Wide social-card placeholder (default)
+  const placeholderUrl = useOgPlaceholder(
+    buildOgPlaceholderUrl,
+    title,
+    site,
+  )
+
+  // Square placeholder for compact chat-inline card slots
+  const squarePlaceholder = useOgPlaceholder(
+    buildOgPlaceholderUrl,
+    title,
+    site,
+    true,
+    'square',
+  )
+
+  return (
+    <img
+      src={placeholderUrl ?? '/fallback.png'}
+      alt={title}
+    />
+  )
+}
+```
+
+> **Architecture note:** The hook is intentionally a thin client wrapper — the URL-building logic lives in `lib/utils/entity-image.ts` and is injected via `buildUrl`, so embedded apps can substitute their own `/api/og-placeholder` route without pulling in hub dependencies.

package/src/hooks/.use-toast.md

@@ -1,50 +1,51 @@
-<!-- source-hash: 23b30723329d53fa3543f70a5de9f484 -->
-A custom toast notification wrapper built on top of the Sonner library, providing a simplified interface for displaying various types of toast messages with consistent styling and behavior.
+<!-- source-hash: 5d93c58eb240b757da31978ae31d869b -->
+A composable hook and utility for displaying toast notifications, wrapping the Sonner toast library with a custom `showToast` component and normalized variant system.
 
 ## Key Components
 
-- **`ToastOptions`** - Interface defining toast configuration options including title, description, variant, and duration
-- **`toast`** - Main function that accepts either a string message or options object to display notifications
-- **`useToast`** - React hook that returns the toast function along with direct access to underlying Sonner methods
+| Export | Type | Description |
+|--------|------|-------------|
+| `ToastOptions` | Interface | Configuration options for toast notifications |
+| `toast` | Function | Displays a toast notification; accepts a string or `ToastOptions` |
+| `useToast` | Function | Composable returning `toast`, `dismiss`, and `promise` helpers |
+| `normalizeVariant` | Internal | Maps `'destructive'` → `'error'` for internal variant compatibility |
+
+### `ToastOptions` Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | Toast heading text |
+| `description` | `string` | Optional body text |
+| `variant` | `string` | Visual style: `default`, `success`, `destructive`, `info`, `warning`, `error` |
+| `duration` | `number` | Display duration in milliseconds |
+| `dismissible` | `boolean` | Whether the user can manually dismiss the toast |
 
 ## Usage Example
 
 ```typescript
-import { toast, useToast } from './use-toast'
+import { useToast, toast } from '@/hooks/use-toast'
 
-// Simple string message
+// Direct usage
 toast('Operation completed successfully')
 
-// With options object
 toast({
-  title: 'Success!',
-  description: 'Your changes have been saved',
-  variant: 'success',
-  duration: 3000
+  title: 'Error',
+  description: 'Something went wrong.',
+  variant: 'destructive',
+  duration: 5000,
 })
 
-// In a React component
-function MyComponent() {
-  const { toast } = useToast()
-
-  const handleSave = async () => {
-    try {
-      await saveData()
-      toast({
-        title: 'Data saved',
-        variant: 'success'
-      })
-    } catch (error) {
-      toast({
-        title: 'Error saving data',
-        description: error.message,
-        variant: 'destructive'
-      })
-    }
-  }
-
-  return <button onClick={handleSave}>Save</button>
-}
+// Via composable
+const { toast, dismiss, promise } = useToast()
+
+toast({ title: 'Saved', variant: 'success' })
+
+// Promise-based toast
+promise(fetchData(), {
+  loading: 'Loading...',
+  success: 'Data loaded!',
+  error: 'Failed to load.',
+})
 ```
 
-The wrapper supports five variants: `default`, `success`, `destructive`, `info`, and `warning`, each mapping to appropriate Sonner toast methods for consistent visual feedback.
+> **Note:** The `'destructive'` variant is automatically normalized to `'error'` internally to align with the underlying `ToastVariant` type used by the `toaster` component.

package/src/hooks/state/.use-api-params.md

@@ -1,64 +1,47 @@
-<!-- source-hash: 100851283c714c4dc46cd6edc00f6173 -->
-A React hook that provides type-safe URL state management for REST API parameters without GraphQL dependencies. Handles URL synchronization, type coercion, and provides a clean API for managing search parameters.
+<!-- source-hash: 05189ee6bb31560bd75b396ab69f4552 -->
+Provides URL state management for REST APIs by syncing typed parameters to/from URL search params without requiring GraphQL schema introspection.
 
 ## Key Components
 
-- `useApiParams<TSchema>()` - Main hook for URL state management
-- `ParamSchema` - Type for defining parameter configurations
-- `defineParamSchema()` - Helper for creating typed schemas
-- `ParamConfig<T>` - Configuration interface for individual parameters
-- `UseApiParamsReturn<TSchema>` - Strongly typed return interface
+### Types & Interfaces
+- **`ParamConfig<T>`** — Defines type, default value, and required flag for a single URL parameter
+- **`ParamSchema`** — Record mapping parameter names to their `ParamConfig`
+- **`InferParamsFromSchema<TSchema>`** — Utility type that infers the typed output shape from a schema
+- **`InferInputParamsFromSchema<TSchema>`** — More permissive input variant allowing `null`/`undefined`
+- **`UseApiParamsReturn<TSchema>`** — Full return type including `params`, `setParam`, `setParams`, `clearParams`, `resetParams`, and `urlSearchParams`
+
+### Functions
+- **`defineParamSchema<T>`** — Identity helper that preserves literal types on schema definitions
+- **`useApiParams<TSchema>`** — Primary hook; reads, coerces, and syncs URL search params using a manual schema
+- **`useContentStable<T>`** *(internal)* — Stabilizes object references across renders using JSON key comparison
+- **`reuseIfShallowEqual<T>`** *(internal)* — Prevents array reference churn when content is unchanged
 
 ## Usage Example
 
 ```typescript
-import { useApiParams, defineParamSchema } from './use-api-params'
+import { defineParamSchema, useApiParams } from './use-api-params'
 
-// Define your parameter schema
-const searchSchema = defineParamSchema({
+const schema = defineParamSchema({
   search: { type: 'string', default: '' },
-  page: { type: 'number', default: 1 },
-  tags: { type: 'array', default: [] },
-  sortBy: { type: 'string', default: 'name' }
+  page:   { type: 'number', default: 1 },
+  tags:   { type: 'array',  default: [] },
 })
 
-function SearchComponent() {
-  const { params, setParam, setParams, urlSearchParams } = useApiParams(searchSchema)
-
-  // params is fully typed: { search: string, page: number, tags: string[], sortBy: string }
-  
-  // Fetch data using URLSearchParams
-  const fetchData = async () => {
-    const response = await fetch(`/api/items?${urlSearchParams}`)
-    return response.json()
-  }
-
-  // Type-safe parameter updates
-  const handleSearch = (query: string) => {
-    setParam('search', query)
-    setParam('page', 1) // Reset to first page
-  }
+function ProductList() {
+  const { params, setParam, setParams, urlSearchParams } = useApiParams(schema)
 
-  const handleMultipleUpdates = () => {
-    setParams({
-      search: 'laptop',
-      tags: ['electronics', 'sale'],
-      page: 1
-    })
-  }
+  // params is fully typed: { search: string; page: number; tags: string[] }
+  useEffect(() => {
+    fetch(`/api/products?${urlSearchParams}`)
+  }, [urlSearchParams])
 
   return (
-    <div>
-      <input 
-        value={params.search} 
-        onChange={(e) => handleSearch(e.target.value)}
-        placeholder="Search..."
-      />
-      <div>Page: {params.page}</div>
-      <div>Tags: {params.tags.join(', ')}</div>
-    </div>
+    <input
+      value={params.search}
+      onChange={e => setParam('search', e.target.value)}
+    />
   )
 }
 ```
 
-The hook automatically handles URL synchronization, type coercion from strings to the correct types, and preserves other URL parameters not managed by the schema.
+> **Reference stability:** Internal memoization ensures `params`, array fields, and setter callbacks keep stable references across renders unless the URL or schema content actually changes — safe to use directly in `useEffect` dependency arrays.

package/src/hooks/state/.use-query-params.md

@@ -1,12 +1,27 @@
-<!-- source-hash: 54cf48fb6f20215fad89615814ecc138 -->
-A React hook that automatically generates URL state management from GraphQL queries by parsing query ASTs and syncing parameters with the URL.
+<!-- source-hash: 3c17907a5e162575a9da5189c583b2d4 -->
+Bidirectional URL state management hook that automatically generates GraphQL-compatible variables from URL search parameters by parsing a GraphQL `DocumentNode` AST, optionally enriching it via schema introspection, and flattening nested input types into flat URL params.
 
 ## Key Components
 
-- **`useQueryParams`** - Main hook that converts GraphQL query variables to URL parameters
-- **`UseQueryParamsOptions`** - Configuration interface for customizing behavior
-- **`UseQueryParamsReturn`** - Hook return type with variables, setters, and state
-- **`applyParamMapping`** - Helper to customize URL parameter names
+| Export | Type | Description |
+|--------|------|-------------|
+| `useQueryParams` | Hook | Core hook — parses query AST, fetches schema, syncs URL ↔ GraphQL variables |
+| `UseQueryParamsOptions` | Interface | Configuration: defaults, introspection endpoint/headers, param mapping, debug |
+| `UseQueryParamsReturn` | Interface | Hook return shape: `variables`, `params`, `schema`, setters, state flags |
+| `applyParamMapping` | Function (internal) | Remaps flattened schema keys using a custom `paramMapping` record |
+
+### Initialization Flow
+
+```mermaid
+graph TD
+    A["Parse Query AST"] --> B{"skipIntrospection?"}
+    B -- No --> C["Fetch GraphQL Schema"]
+    B -- Yes --> D["Flatten Schema"]
+    C --> D
+    D --> E["Apply paramMapping"]
+    E --> F["Merge Defaults"]
+    F --> G["setSchema / setIsReady"]
+```
 
 ## Usage Example
 
@@ -25,37 +40,26 @@ const LOGS_QUERY = gql`
 `
 
 function LogsPage() {
-  // Hook automatically parses query and manages URL state
-  const { variables, setParam, setParams, isReady } = useQueryParams(LOGS_QUERY, {
-    defaultValues: { search: '', filter: { severity: [] } },
-    debug: true
-  })
-
-  const { data, loading } = useQuery(LOGS_QUERY, { variables })
+  const { variables, setParam, setParams, clearParams, resetParams, isReady } =
+    useQueryParams(LOGS_QUERY, {
+      defaultValues: { filter: { severity: ['info'] } },
+      introspectionEndpoint: 'https://api.example.com/graphql',
+      introspectionHeaders: { Authorization: 'Bearer token' },
+      debug: true,
+    })
 
-  if (!isReady) return <div>Loading schema...</div>
+  const { data } = useQuery(LOGS_QUERY, { variables, skip: !isReady })
 
   return (
-    <div>
-      <input 
-        value={variables.search || ''} 
-        onChange={(e) => setParam('search', e.target.value)}
-        placeholder="Search logs..."
-      />
-      
-      <select 
-        onChange={(e) => setParam('filter.severity', [e.target.value])}
-      >
-        <option value="info">Info</option>
-        <option value="warning">Warning</option>
-        <option value="error">Error</option>
-      </select>
-      
-      {/* URL automatically updates: /logs?search=error&filter.severity=critical */}
-      {data?.logs?.map(log => <div key={log.id}>{log.message}</div>)}
-    </div>
+    <>
+      {/* URL: /logs?search=error&severity=critical */}
+      {/* variables: { search: 'error', filter: { severity: ['critical'] } } */}
+      <input onChange={e => setParam('search', e.target.value)} />
+      <button onClick={() => clearParams(['search'])}>Clear</button>
+      <button onClick={resetParams}>Reset All</button>
+    </>
   )
 }
 ```
 
-The hook performs GraphQL schema introspection, flattens nested input types to URL parameters, and provides bidirectional sync between URL state and GraphQL variables.
+> **Note:** Schema introspection results are cached via `introspector` — subsequent calls with the same endpoint skip the network fetch. Set `skipIntrospection: true` if your input types are shallow (no nested objects) to avoid the extra request.

package/src/hooks/ui/.index.md

@@ -1,40 +1,41 @@
-<!-- source-hash: 81fe3636c8cef1310edc610fe96643be -->
-A barrel file that consolidates and re-exports all UI-related React hooks from the current module, providing a single import entry point for consuming components.
+<!-- source-hash: fc4a9d5f3d9a97f43016324c6310b828 -->
+Barrel export file that re-exports all UI hooks from the hooks package, providing a single entry point for consuming hook utilities across the application.
 
 ## Key Components
 
-This index file exports the following custom React hooks:
-
-- **use-debounce** - Delays function execution until after a specified wait time
-- **use-local-storage** - Manages state persistence in browser's localStorage
-- **use-media-query** - Responds to CSS media query changes for responsive design
-- **use-memoized-callback** - Optimizes callback function memoization
-- **use-onboarding-state** - Manages user onboarding flow state
-- **use-table-pagination** - Handles table pagination logic and state
-- **use-throttle** - Limits function execution frequency to improve performance
-- **use-window-size** - Tracks browser window dimensions and resize events
+| Hook | Description |
+|------|-------------|
+| `use-debounce` | Delays value updates until after a specified wait period |
+| `use-local-storage` | Persists and retrieves state from browser local storage |
+| `use-media-query` | Evaluates CSS media queries reactively |
+| `use-memoized-callback` | Memoizes callback functions to prevent unnecessary re-renders |
+| `use-onboarding-state` | Manages onboarding flow state and progress |
+| `use-table-pagination` | Handles pagination logic for data tables |
+| `use-throttle` | Limits function call frequency to a specified interval |
+| `use-window-size` | Tracks browser window dimensions reactively |
+| `use-horizontal-scrollbar` | Detects and manages horizontal scrollbar visibility |
+| `use-image-edge-color` | Extracts dominant edge color from an image |
+| `use-search` | Manages search input state and filtering logic |
+| `use-auto-limit-tags` | Automatically limits visible tags based on available space |
 
 ## Usage Example
 
 ```typescript
-// Import individual hooks
-import { useDebounce, useLocalStorage, useMediaQuery } from './hooks'
-
-// Or import all hooks
-import * as UIHooks from './hooks'
-
-function MyComponent() {
-  // Use debounced search input
-  const debouncedSearch = useDebounce(searchTerm, 300)
-  
-  // Persist theme preference
-  const [theme, setTheme] = useLocalStorage('theme', 'light')
-  
-  // Responsive design
-  const isMobile = useMediaQuery('(max-width: 768px)')
-  
-  return <div>...</div>
+import {
+  useDebounce,
+  useLocalStorage,
+  useWindowSize,
+  useSearch,
+  useTablePagination,
+} from '@your-package/hooks'
+
+const MyComponent = () => {
+  const { width, height } = useWindowSize()
+  const [query, setQuery] = useLocalStorage('search-query', '')
+  const debouncedQuery = useDebounce(query, 300)
+  const { results } = useSearch(debouncedQuery, items)
+  const { page, pageSize, onPageChange } = useTablePagination()
+
+  return <Table data={results} page={page} pageSize={pageSize} />
 }
-```
-
-This barrel export pattern simplifies imports and provides a clean API surface for the UI hooks library.
+```

package/src/hooks/ui/.use-auto-limit-tags.md

@@ -0,0 +1,54 @@
+<!-- source-hash: 4ddac380d848a0dcab830bec82a667f6 -->
+Calculates how many tags fit within a single-line container using real DOM measurements, supporting both a fixed numeric limit and an automatic layout-aware mode.
+
+## Key Components
+
+### `useAutoLimitTags(options)`
+Main hook that returns layout refs and the computed `visibleCount`.
+
+**Options**
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `count` | `number` | — | Total number of tags |
+| `limitTags` | `number \| "auto"` | `"auto"` | Fixed cap or DOM-measured auto mode |
+| `placeholder` | `string` | `""` | Input placeholder used to reserve width |
+
+**Returns (`UseAutoLimitTagsReturn`)**
+| Ref | Element | Purpose |
+|---|---|---|
+| `middleRef` | `HTMLDivElement` | Container with tags + input (reads padding/gap from here) |
+| `measureRef` | `HTMLDivElement` | Off-screen container holding copies of all tags |
+| `textMeasureRef` | `HTMLSpanElement` | Hidden span measuring placeholder text width |
+| `badgeRef` | `HTMLButtonElement` | The `+N` overflow badge (measures its width) |
+| `inputRef` | `HTMLInputElement` | The text input (reads its `min-width`) |
+| `visibleCount` | `number` | How many tags to render visibly |
+
+## Usage Example
+
+```typescript
+const { visibleCount, middleRef, measureRef, textMeasureRef, badgeRef, inputRef } =
+  useAutoLimitTags({ count: tags.length, placeholder: "Search..." })
+
+return (
+  <>
+    {/* Off-screen measurement container */}
+    <div ref={measureRef} style={{ position: "absolute", visibility: "hidden" }}>
+      {tags.map((tag) => <TagChip key={tag.id} tag={tag} />)}
+    </div>
+    <span ref={textMeasureRef} style={{ visibility: "hidden", position: "absolute" }}>
+      Search...
+    </span>
+
+    {/* Visible tag zone */}
+    <div ref={middleRef} className="flex overflow-hidden gap-1 px-2">
+      {tags.slice(0, visibleCount).map((tag) => <TagChip key={tag.id} tag={tag} />)}
+      {visibleCount < tags.length && (
+        <button ref={badgeRef}>+{tags.length - visibleCount}</button>
+      )}
+      <input ref={inputRef} placeholder="Search..." />
+    </div>
+  </>
+)
+```
+
+> **Note:** `middleRef` must have `overflow-hidden`, explicit `gap`, and `padding` set via CSS — the hook reads these values directly with `getComputedStyle` and uses a `ResizeObserver` to recalculate on container width changes.

package/src/hooks/ui/.use-horizontal-scrollbar.md

@@ -0,0 +1,74 @@
+<!-- source-hash: 9f63d7c2dd408b85d0a130f82da97780 -->
+Custom React hook for building a fully controlled horizontal scrollbar with drag, click-to-seek, wheel forwarding, edge-fade indicators, and RAF-throttled sync — all driven directly against the DOM without relying on native scrollbar styling.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `useHorizontalScrollbar` | Hook | Main hook returning all refs, state, and event handlers |
+| `scrollRef` | Callback ref | Attach to the scrollable container; auto-sets up `ResizeObserver` |
+| `trackRef` | `RefObject<HTMLDivElement>` | Attach to the scrollbar track element |
+| `thumbRef` | `RefObject<HTMLDivElement>` | Attach to the draggable thumb element |
+| `thumbRatio` | `number` | Thumb width as a fraction of track width (`0` = hidden) |
+| `canScrollLeft` | `boolean` | Whether content can scroll further left (for edge fades) |
+| `canScrollRight` | `boolean` | Whether content can scroll further right (for edge fades) |
+
+**Event Handlers Returned:**
+
+| Handler | Attach To |
+|---------|-----------|
+| `onScroll` | Scrollable container `onScroll` |
+| `onTrackClick` | Track element `onClick` |
+| `onTrackWheel` | Track element `onWheel` |
+| `onThumbPointerDown` | Thumb `onPointerDown` |
+| `onThumbPointerMove` | Thumb `onPointerMove` |
+| `onThumbPointerUp` | Thumb `onPointerUp` |
+
+## Usage Example
+
+```typescript
+import { useHorizontalScrollbar } from './use-horizontal-scrollbar'
+
+function ScrollableTable() {
+  const {
+    scrollRef, trackRef, thumbRef,
+    thumbRatio, canScrollLeft, canScrollRight,
+    onScroll, onTrackClick, onTrackWheel,
+    onThumbPointerDown, onThumbPointerMove, onThumbPointerUp,
+  } = useHorizontalScrollbar()
+
+  return (
+    <div>
+      {canScrollLeft && <div className="fade-left" />}
+
+      {/* Scrollable content */}
+      <div ref={scrollRef} onScroll={onScroll} style={{ overflowX: 'auto' }}>
+        <table>{/* wide content */}</table>
+      </div>
+
+      {canScrollRight && <div className="fade-right" />}
+
+      {/* Custom scrollbar */}
+      {thumbRatio > 0 && (
+        <div
+          ref={trackRef}
+          onClick={onTrackClick}
+          onWheel={onTrackWheel}
+          style={{ position: 'relative', height: 8 }}
+        >
+          <div
+            ref={thumbRef}
+            data-scrollbar-thumb
+            onPointerDown={onThumbPointerDown}
+            onPointerMove={onThumbPointerMove}
+            onPointerUp={onThumbPointerUp}
+            style={{ position: 'absolute', width: `${thumbRatio * 100}%`, cursor: 'grab' }}
+          />
+        </div>
+      )}
+    </div>
+  )
+}
+```
+
+> **Performance note:** Thumb position is written directly to `thumb.style.left` via `requestAnimationFrame`, bypassing React re-renders on every scroll event. Only `thumbRatio`, `canScrollLeft`, and `canScrollRight` trigger state updates.