@asteby/metacore-runtime-react 34.0.2 → 34.1.0

package/dist/use-dynamic-filters.js

@@ -14,6 +14,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useApi } from './api-context';
 import { DATE_CELL_TYPES } from './dynamic-columns';
 import { getSearchableColumnKeys } from './column-visibility';
+import { useDebouncedValue } from './use-debounced-value';
 import { useFacetLoaders, isLongTextColumn } from './use-facet-loaders';
 /**
  * Reads the model's filter metadata and returns the live filter state + the
@@ -26,6 +27,7 @@ export function useDynamicFilters(metadata, opts = {}) {
     const api = useApi();
     const [dynamicFilters, setDynamicFilters] = useState({});
     const [globalFilter, setGlobalFilter] = useState('');
+    const debouncedGlobalFilter = useDebouncedValue(globalFilter);
     const [filterOptionsMap, setFilterOptionsMap] = useState(new Map());
     // Where a `facet` filter loads its distinct values from. Explicit override
     // wins; otherwise `<endpoint>/facets` (same derivation as the aggregate
@@ -268,12 +270,12 @@ export function useDynamicFilters(metadata, opts = {}) {
     // DynamicTable.buildFilterParams (IN:/RANGE:/GTE:/LTE:/ILIKE:/plain).
     const filterParams = useMemo(() => {
         const params = {};
-        if (globalFilter) {
+        if (debouncedGlobalFilter) {
             if (searchableKeys === null) {
-                params.search = globalFilter;
+                params.search = debouncedGlobalFilter;
             }
             else if (searchableKeys.length > 0) {
-                params.search = globalFilter;
+                params.search = debouncedGlobalFilter;
                 params.search_columns = searchableKeys.join(',');
             }
             // searchableKeys === [] → no searchable column, skip the search param.
@@ -300,7 +302,7 @@ export function useDynamicFilters(metadata, opts = {}) {
                 params[`f_${key}`] = `IN:${values.join(',')}`;
         });
         return params;
-    }, [globalFilter, searchableKeys, defaultFilters, dynamicFilters]);
+    }, [debouncedGlobalFilter, searchableKeys, defaultFilters, dynamicFilters]);
     const activeFilterCount = useMemo(() => {
         let n = Object.values(dynamicFilters).filter((v) => v.length > 0).length;
         if (globalFilter)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "34.0.2",
+  "version": "34.1.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",

package/src/__tests__/image-stack.test.tsx

@@ -0,0 +1,52 @@
+// @vitest-environment happy-dom
+
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render } from '@testing-library/react'
+import { ImageStack } from '../display-value'
+import { ImageCell } from '../dynamic-columns'
+
+afterEach(cleanup)
+
+describe('ImageStack', () => {
+    it('renders landscape mark with label underneath and no padded plate', () => {
+        const { container, getByText } = render(
+            <ImageStack src="/brands/bridgestone.png" label="BRIDGESTONE" size="sm" />,
+        )
+        const img = container.querySelector('img')
+        expect(img).toBeTruthy()
+        expect(img?.getAttribute('src')).toBe('/brands/bridgestone.png')
+        expect(img?.className).toContain('object-contain')
+        expect(getByText('BRIDGESTONE')).toBeTruthy()
+        // Label comes after the image in DOM order (stack, not side-by-side).
+        const root = container.firstElementChild as HTMLElement
+        expect(root.className).toContain('flex-col')
+        // No muted card / ring wrapping the logo (row height tax).
+        expect(root.querySelector('.bg-muted\\/60')).toBeNull()
+        expect(root.innerHTML).not.toContain('bg-muted')
+    })
+
+    it('falls back to initials when src is missing', () => {
+        const { getByText } = render(<ImageStack label="PIRELLI" size="md" />)
+        // Single-token name → first letter only (getInitials).
+        expect(getByText('P')).toBeTruthy()
+        expect(getByText('PIRELLI')).toBeTruthy()
+    })
+})
+
+describe('ImageCell stack mode', () => {
+    const getImageUrl = (p: string) => p
+
+    it('stacks image above caption when stack=true', () => {
+        const { container, getByText } = render(
+            <ImageCell
+                value="/brands/michelin.png"
+                getImageUrl={getImageUrl}
+                label="MICHELIN"
+                stack
+            />,
+        )
+        expect(container.querySelector('img')?.className).toContain('object-contain')
+        expect(getByText('MICHELIN')).toBeTruthy()
+        expect((container.firstElementChild as HTMLElement).className).toContain('flex-col')
+    })
+})

package/src/__tests__/use-debounced-value.test.ts

@@ -0,0 +1,56 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { SEARCH_DEBOUNCE_MS, useDebouncedValue } from '../use-debounced-value'
+
+describe('useDebouncedValue', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('lags behind the live value by the default search debounce', () => {
+    const { result, rerender } = renderHook(
+      ({ value }: { value: string }) => useDebouncedValue(value),
+      { initialProps: { value: '' } },
+    )
+    expect(result.current).toBe('')
+
+    rerender({ value: 'pi' })
+    expect(result.current).toBe('')
+
+    act(() => {
+      vi.advanceTimersByTime(SEARCH_DEBOUNCE_MS - 1)
+    })
+    expect(result.current).toBe('')
+
+    act(() => {
+      vi.advanceTimersByTime(1)
+    })
+    expect(result.current).toBe('pi')
+  })
+
+  it('resets the timer when the value changes mid-debounce', () => {
+    const { result, rerender } = renderHook(
+      ({ value }: { value: string }) => useDebouncedValue(value, 300),
+      { initialProps: { value: 'a' } },
+    )
+
+    rerender({ value: 'ab' })
+    act(() => {
+      vi.advanceTimersByTime(200)
+    })
+    rerender({ value: 'abc' })
+    act(() => {
+      vi.advanceTimersByTime(200)
+    })
+    expect(result.current).toBe('a')
+
+    act(() => {
+      vi.advanceTimersByTime(100)
+    })
+    expect(result.current).toBe('abc')
+  })
+})

package/src/dialogs/dynamic-record.tsx

@@ -71,6 +71,7 @@ import { IconPickerField } from '../icon-picker-field'
 import { humanizeToken } from '../dynamic-columns-helpers'
 import { formatDateCell } from '../dynamic-columns'
 import {
+    ImageStack,
     OptionBadge,
     statusColorFor,
     useIsDarkTheme,
@@ -1243,7 +1244,7 @@ function ReadonlyRelationField({
 // RelationViewValue — read-only FK lead. Resolves the relation's label + image
 // from (1) the sibling object the table served, then (2) the canonical options
 // endpoint, and renders an OptionLead (thumbnail / icon / color dot) + label.
-function RelationViewValue({ field, value, record }: { field: FieldDef; value: any; record: any }) {
+function RelationViewValue({ field, value, record, stack = false }: { field: FieldDef; value: any; record: any; stack?: boolean }) {
     const getImageUrl = useContext(ImageUrlContext)
     const sib = relationSiblingValue(field, record)
     const sibLabel = typeof sib === 'string' ? sib : objectLabel(sib)
@@ -1278,6 +1279,19 @@ function RelationViewValue({ field, value, record }: { field: FieldDef; value: a
         return <p className="text-sm py-1 text-muted-foreground">—</p>
     }
 
+    if (stack) {
+        return (
+            <div className="py-1">
+                <ImageStack
+                    src={image || undefined}
+                    label={label}
+                    getImageUrl={getImageUrl}
+                    size="lg"
+                />
+            </div>
+        )
+    }
+
     const lead: Pick<ResolvedOption, 'image' | 'color' | 'icon' | 'label'> = {
         image: image ? getImageUrl(image) : null,
         color: resolved?.color ?? null,
@@ -1368,6 +1382,14 @@ export function ViewValue({
 
     const value = normalizeNilUuid(rawValue)
 
+    // Landscape stack on a relation FK (brand marks, product cards).
+    if (
+        renderAs === 'image_stack' &&
+        (isRelationField(field) || (typeof field.key === 'string' && field.key.endsWith('_id')))
+    ) {
+        return <RelationViewValue field={field} value={value} record={record} stack />
+    }
+
     // Relation (search / dynamic_select / ref / any *_id) → resolved thumbnail +
     // label. The *_id catch-all covers plain-typed FK columns not tagged as a
     // relation field.
@@ -1404,6 +1426,26 @@ export function ViewValue({
         )
     }
 
+    // Landscape stack for image/logo URL columns.
+    if (renderAs === 'image_stack') {
+        const caption =
+            (typeof field.styleConfig?.label_field === 'string' &&
+                record?.[field.styleConfig.label_field]) ||
+            (typeof field.styleConfig?.labelField === 'string' &&
+                record?.[field.styleConfig.labelField]) ||
+            undefined
+        return (
+            <div className="py-1">
+                <ImageStack
+                    src={value ? String(value) : undefined}
+                    label={caption ? String(caption) : field.label}
+                    getImageUrl={getImageUrl}
+                    size="lg"
+                />
+            </div>
+        )
+    }
+
     if (field.type === 'image') {
         if (isLucideIconName(value)) {
             return <IconNameViewValue name={value} />

package/src/display-value.tsx

@@ -78,24 +78,102 @@ export const RelationThumbnail: React.FC<{
     size?: number
 }> = ({ src, alt, getImageUrl, size = 20 }) => (
     <Avatar
-        className="shrink-0 rounded-md bg-muted/50 p-[3px] ring-1 ring-border/40"
+        className="shrink-0 rounded-md"
         style={{ width: size, height: size }}
     >
         {/* object-contain: brand logos are typically wide/rectangular, so
             object-cover (fills the square, cropping the sides) was cutting
-            them off. contain lets the whole mark show, letterboxed by the
-            padded neutral background above instead of clipped. */}
+            them off. contain shows the whole mark without a padded plate. */}
         <AvatarImage
             src={getImageUrl ? getImageUrl(src) : src}
             alt={alt}
             className="object-contain"
         />
-        <AvatarFallback className="rounded-md bg-primary/10 text-[8px] font-bold text-primary">
+        <AvatarFallback className="rounded-md bg-transparent text-[8px] font-bold text-muted-foreground">
             {getInitials(alt)}
         </AvatarFallback>
     </Avatar>
 )
 
+/**
+ * Landscape-friendly identity block: wide image ON TOP, label (and optional
+ * subtitle) UNDERNEATH. Use for brand logos, product photos and any mark that
+ * is wider than it is tall — a square thumb next to text crops logos and
+ * wastes the cell. Declared via `display: "image_stack"` on a column (image
+ * URL or FK relation with a logo/photo sibling).
+ *
+ * No padded card / muted plate behind the mark — that ate table row height.
+ * The image is sized with max-width/max-height and `object-contain` only.
+ *
+ * Sizes (CSS, not Tailwind arbitrary — host safelists vary):
+ *   sm — compact table (~88×32)
+ *   md — default table (~112×40)
+ *   lg — detail/modal (~180×72)
+ */
+export const ImageStack: React.FC<{
+    src?: string | null
+    label?: string | null
+    subtitle?: string | null
+    getImageUrl?: (path: string) => string
+    size?: 'sm' | 'md' | 'lg'
+    className?: string
+}> = ({ src, label, subtitle, getImageUrl, size = 'md', className }) => {
+    const dims =
+        size === 'lg'
+            ? { w: 180, h: 72, text: 'text-sm' }
+            : size === 'sm'
+              ? { w: 88, h: 32, text: 'text-[11px]' }
+              : { w: 112, h: 40, text: 'text-xs' }
+    const alt = label || ''
+    const resolved = src
+        ? getImageUrl
+            ? getImageUrl(src)
+            : src
+        : undefined
+    const [broken, setBroken] = React.useState(false)
+    React.useEffect(() => {
+        setBroken(false)
+    }, [resolved])
+
+    return (
+        <span
+            className={`inline-flex max-w-[220px] flex-col items-start gap-0.5 ${className ?? ''}`}
+            title={subtitle ? `${alt} · ${subtitle}` : alt || undefined}
+        >
+            {resolved && !broken ? (
+                <img
+                    src={resolved}
+                    alt={alt}
+                    className="block object-contain"
+                    style={{ maxWidth: dims.w, maxHeight: dims.h, width: 'auto', height: 'auto' }}
+                    onError={() => setBroken(true)}
+                />
+            ) : (
+                <span
+                    className="flex items-center text-[10px] font-semibold tracking-wide text-muted-foreground"
+                    style={{ minHeight: Math.round(dims.h * 0.55) }}
+                >
+                    {getInitials(alt || '?')}
+                </span>
+            )}
+            {(label || subtitle) && (
+                <span className={`flex w-full min-w-0 flex-col items-start leading-tight ${dims.text}`}>
+                    {label ? (
+                        <span className="w-full truncate text-left font-medium text-foreground/90">
+                            {label}
+                        </span>
+                    ) : null}
+                    {subtitle ? (
+                        <span className="w-full truncate text-left text-[0.7em] text-muted-foreground">
+                            {subtitle}
+                        </span>
+                    ) : null}
+                </span>
+            )}
+        </span>
+    )
+}
+
 export interface DisplayOption {
     value: string
     label: string

package/src/dynamic-columns.tsx

@@ -44,7 +44,7 @@ import {
 import { Progress } from './dialogs/_primitives'
 import { humanizeToken } from './dynamic-columns-helpers'
 import { objectLabel } from './dynamic-relation-helpers'
-import {
+import { ImageStack,
     OptionBadge,
     RelationThumbnail,
     statusColorFor,
@@ -494,7 +494,7 @@ export const resolveRelationLabel = (col: ColumnDefinition, row: any): string =>
 export const resolveRelationImage = (col: ColumnDefinition, row: any): string => {
     const sibling = getNestedValue(row, relationKeyFor(col))
     if (sibling && typeof sibling === 'object') {
-        const img = sibling.image ?? sibling.avatar ?? sibling.photo
+        const img = sibling.image ?? sibling.avatar ?? sibling.photo ?? sibling.logo ?? sibling.thumbnail
         if (img !== undefined && img !== null && img !== '') return String(img)
     }
     return ''
@@ -608,11 +608,24 @@ const RelationCell: React.FC<{
     col: ColumnDefinition
     row: any
     getImageUrl?: (path: string) => string
-}> = ({ col, row, getImageUrl }) => {
+    /** Landscape stack: image above, text below (display: image_stack). */
+    stack?: boolean
+}> = ({ col, row, getImageUrl, stack = false }) => {
     const display = resolveRelationLabel(col, row)
     if (!display) return <EmptyCell />
     const image = resolveRelationImage(col, row)
     const subtitle = resolveRelationSubtitle(col, row)
+    if (stack) {
+        return (
+            <ImageStack
+                src={image || undefined}
+                label={display}
+                subtitle={subtitle || undefined}
+                getImageUrl={getImageUrl}
+                size="md"
+            />
+        )
+    }
     // FLAT reference cell: no tinted capsule around the pair. A reference is
     // data, not a status — the pill treatment (and its per-label tint) made a
     // products/warehouses listing read as a wall of badges. What identifies the
@@ -751,15 +764,29 @@ const AvatarCell: React.FC<{
 export const ImageCell: React.FC<{
     value: unknown
     getImageUrl: (path: string) => string
-}> = ({ value, getImageUrl }) => {
-    if (!value) return <span className="text-muted-foreground">-</span>
-    if (isLucideIconName(value)) {
+    /** Optional caption under the image (display: image_stack). */
+    label?: string
+    stack?: boolean
+}> = ({ value, getImageUrl, label, stack = false }) => {
+    if (!value && !label) return <span className="text-muted-foreground">-</span>
+    if (value && isLucideIconName(value)) {
         return (
             <div className="h-10 w-10 flex items-center justify-center rounded bg-muted">
                 <DynamicIcon name={value} className="h-5 w-5" />
             </div>
         )
     }
+    if (stack) {
+        return (
+            <ImageStack
+                src={value ? String(value) : undefined}
+                label={label}
+                getImageUrl={getImageUrl}
+                size="md"
+            />
+        )
+    }
+    if (!value) return <span className="text-muted-foreground">-</span>
     return (
         <div className="h-10 w-10 relative rounded overflow-hidden bg-muted flex items-center justify-center">
             <img
@@ -916,6 +943,37 @@ export function makeDefaultGetDynamicColumns(
                         return <ReferenceCell col={col} row={row.original} />
                     }
 
+                    // Landscape stack: wide image ON TOP, label UNDERNEATH.
+                    if (renderAs === 'image_stack') {
+                        const looksRelation =
+                            !!col.ref ||
+                            (typeof col.key === 'string' &&
+                                col.key.endsWith('_id') &&
+                                resolveRelationLabel(col, row.original) != null)
+                        if (looksRelation) {
+                            return (
+                                <RelationCell
+                                    col={col}
+                                    row={row.original}
+                                    getImageUrl={getImageUrl}
+                                    stack
+                                />
+                            )
+                        }
+                        const labelField = styleCfg(col, 'label_field', 'labelField')
+                        const caption = labelField
+                            ? String(getNestedValue(row.original, labelField) ?? '')
+                            : undefined
+                        return (
+                            <ImageCell
+                                value={value}
+                                getImageUrl={getImageUrl}
+                                label={caption || undefined}
+                                stack
+                            />
+                        )
+                    }
+
                     // Resolved FK relation chip. Triggers on an explicit
                     // `cellStyle: 'relation'` or on any column carrying a `ref`
                     // (a belongs_to FK) that isn't being rendered as an
@@ -1274,6 +1332,21 @@ export function makeDefaultGetDynamicColumns(
                             )
                         }
 
+                        case 'image_stack': {
+                            const imageValue =
+                                value ||
+                                (Array.isArray(row.original.media)
+                                    ? row.original.media.find((m: any) => m.type === 'image')?.url
+                                    : null)
+                            return (
+                                <ImageCell
+                                    value={imageValue}
+                                    getImageUrl={getImageUrl}
+                                    stack
+                                />
+                            )
+                        }
+
                         case 'image': {
                             const imageValue =
                                 value ||

package/src/dynamic-select-field.tsx

@@ -40,6 +40,7 @@ import { Check, ChevronsUpDown, Loader2, Plus, ScanLine } from 'lucide-react'
 import { resolveColorCss } from '@asteby/metacore-ui/lib'
 import { BarcodeScanner } from './barcode-scanner'
 import { DynamicIcon, isLucideIconName } from './dynamic-icon'
+import { useDebouncedValue } from './use-debounced-value'
 import { useOptionsResolver, type ResolvedOption } from './use-options-resolver'
 import { getDependsOn, getFieldRef, resolveOptionsSource } from './dynamic-form-schema'
 import type { ActionFieldDef } from './types'
@@ -140,12 +141,7 @@ export function OptionLead({
 }
 
 function useDebounced<T>(value: T, ms: number): T {
-    const [debounced, setDebounced] = useState(value)
-    useEffect(() => {
-        const t = setTimeout(() => setDebounced(value), ms)
-        return () => clearTimeout(t)
-    }, [value, ms])
-    return debounced
+    return useDebouncedValue(value, ms)
 }
 
 export interface DynamicSelectFieldProps {

package/src/dynamic-table.tsx

@@ -72,6 +72,7 @@ import { dedupeById, useInfiniteScrollSentinel } from './use-infinite-scroll'
 import { OptionsContext } from './options-context'
 import type { TableMetadata, ApiResponse } from './types'
 import { getSearchableColumnKeys } from './column-visibility'
+import { useDebouncedValue } from './use-debounced-value'
 import { useCan, usePermissionsActive, gateTableMetadata } from './permissions-context'
 import { useDynamicRowActions } from './dynamic-row-actions'
 import { ExportDialog } from './dialogs/export'
@@ -320,6 +321,8 @@ export function DynamicTable({
         pageSize: storedPageSizeRef.current ?? 10,
     })
     const [globalFilter, setGlobalFilter] = useState('')
+    // Debounce search → URL + fetch so each keystroke does not thrash the server.
+    const debouncedGlobalFilter = useDebouncedValue(globalFilter)
     const [rowCount, setRowCount] = useState(bootData?.rowCount ?? 0)
 
     const [dateRange, setDateRange] = useState<DateRange | undefined>(undefined)
@@ -474,7 +477,7 @@ export function DynamicTable({
             params.set('sortBy', sorting[0].id)
             params.set('order', sorting[0].desc ? 'desc' : 'asc')
         }
-        if (globalFilter) params.set('search', globalFilter)
+        if (debouncedGlobalFilter) params.set('search', debouncedGlobalFilter)
         Object.entries(dynamicFilters).forEach(([key, values]) => {
             if (values.length === 0) return
             if (defaultFilters && key in defaultFilters) return
@@ -495,7 +498,7 @@ export function DynamicTable({
         const newUrl = search ? `${window.location.pathname}?${search}` : window.location.pathname
         lastSelfSearch.current = search ? `?${search}` : ''
         window.history.replaceState(null, '', newUrl)
-    }, [enableUrlSync, urlSynced, pagination, sorting, globalFilter, dynamicFilters, defaultFilters])
+    }, [enableUrlSync, urlSynced, pagination, sorting, debouncedGlobalFilter, dynamicFilters, defaultFilters])
 
     // The host router can rewrite the query string WITHOUT remounting the
     // table — e.g. sidebar sibling entries deep-link different `f_` filters
@@ -670,11 +673,11 @@ export function DynamicTable({
             params.sortBy = sorting[0].id
             params.order = sorting[0].desc ? 'desc' : 'asc'
         }
-        if (globalFilter) {
+        if (debouncedGlobalFilter) {
             if (searchableKeys === null) {
-                params.search = globalFilter
+                params.search = debouncedGlobalFilter
             } else if (searchableKeys.length > 0) {
-                params.search = globalFilter
+                params.search = debouncedGlobalFilter
                 params.search_columns = searchableKeys.join(',')
             }
             // searchableKeys === [] → drop the search request entirely
@@ -700,7 +703,7 @@ export function DynamicTable({
             params['f_created_at'] = `${startDate}_${endDate}`
         }
         return params
-    }, [sorting, globalFilter, columnFilters, defaultFilters, dynamicFilters, dateRange, searchableKeys])
+    }, [sorting, debouncedGlobalFilter, columnFilters, defaultFilters, dynamicFilters, dateRange, searchableKeys])
 
     const hasActiveFilters = useMemo(() => {
         if (globalFilter) return true

package/src/index.ts

@@ -119,6 +119,7 @@ export {
     type UseDynamicFiltersOptions,
     type UseDynamicFiltersResult,
 } from './use-dynamic-filters'
+export { useDebouncedValue, SEARCH_DEBOUNCE_MS } from './use-debounced-value'
 export * from './dynamic-form'
 export {
     FilePickButton,
@@ -265,6 +266,12 @@ export {
     type UrlKind,
     type LinkifyOptions,
 } from './rich-url'
+export {
+    ImageStack,
+    OptionBadge,
+    statusColorFor,
+    useIsDarkTheme,
+} from './display-value'
 export {
     CollectionCell,
     formatScalar,

package/src/metadata-cache.ts

@@ -178,7 +178,14 @@ export const useMetadataCache = create<MetadataCacheState>()(
         }),
         {
             name: 'metacore-metadata-cache',
-            version: 3,
+            // Bump when display hints (e.g. image_stack) must wipe stale cache.
+            version: 4,
+            migrate: () => ({
+                cache: {},
+                modalCache: {},
+                metadataVersion: '',
+                prefetched: false,
+            }),
             partialize: (state) => ({
                 cache: state.cache,
                 modalCache: state.modalCache,

package/src/types.ts

@@ -252,6 +252,8 @@ export interface ColumnDefinition {
         | 'phone'
         | 'media-gallery'
         | 'image'
+        // Landscape stack: wide image on top, label underneath (logos/photos).
+        | 'image_stack'
         // Declarative pro cell renderers (resolved via `cellStyle ?? type`).
         | 'url'
         | 'link'

package/src/use-debounced-value.ts

@@ -0,0 +1,17 @@
+import { useEffect, useState } from 'react'
+
+/** Default delay for free-text search → server/URL (table, kanban, relation). */
+export const SEARCH_DEBOUNCE_MS = 350
+
+/**
+ * Returns `value` delayed by `ms`. The input stays live; only the returned
+ * value lags — use it for fetches and URL sync so typing does not thrash.
+ */
+export function useDebouncedValue<T>(value: T, ms: number = SEARCH_DEBOUNCE_MS): T {
+  const [debounced, setDebounced] = useState(value)
+  useEffect(() => {
+    const t = setTimeout(() => setDebounced(value), ms)
+    return () => clearTimeout(t)
+  }, [value, ms])
+  return debounced
+}

package/src/use-dynamic-filters.ts

@@ -14,6 +14,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useApi } from './api-context'
 import { DATE_CELL_TYPES } from './dynamic-columns'
 import { getSearchableColumnKeys } from './column-visibility'
+import { useDebouncedValue } from './use-debounced-value'
 import { useFacetLoaders, isLongTextColumn } from './use-facet-loaders'
 import type { ColumnFilterConfig, FilterOption } from './dynamic-columns-shim'
 import type { TableMetadata } from './types'
@@ -82,6 +83,7 @@ export function useDynamicFilters(
 
   const [dynamicFilters, setDynamicFilters] = useState<Record<string, string[]>>({})
   const [globalFilter, setGlobalFilter] = useState('')
+  const debouncedGlobalFilter = useDebouncedValue(globalFilter)
   const [filterOptionsMap, setFilterOptionsMap] = useState<
     Map<string, FilterOption[]>
   >(new Map())
@@ -343,11 +345,11 @@ export function useDynamicFilters(
   // DynamicTable.buildFilterParams (IN:/RANGE:/GTE:/LTE:/ILIKE:/plain).
   const filterParams = useMemo(() => {
     const params: Record<string, any> = {}
-    if (globalFilter) {
+    if (debouncedGlobalFilter) {
       if (searchableKeys === null) {
-        params.search = globalFilter
+        params.search = debouncedGlobalFilter
       } else if (searchableKeys.length > 0) {
-        params.search = globalFilter
+        params.search = debouncedGlobalFilter
         params.search_columns = searchableKeys.join(',')
       }
       // searchableKeys === [] → no searchable column, skip the search param.
@@ -371,7 +373,7 @@ export function useDynamicFilters(
       else params[`f_${key}`] = `IN:${values.join(',')}`
     })
     return params
-  }, [globalFilter, searchableKeys, defaultFilters, dynamicFilters])
+  }, [debouncedGlobalFilter, searchableKeys, defaultFilters, dynamicFilters])
 
   const activeFilterCount = useMemo(() => {
     let n = Object.values(dynamicFilters).filter((v) => v.length > 0).length