@k3-tech/react-kit 0.0.60 → 0.0.62

package/dist/kit/components/data-table-headers/DataTableHeader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataTableHeader.d.ts","sourceRoot":"","sources":["../../../../src/kit/components/data-table-headers/DataTableHeader.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAyB,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAO3E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,EAC9B,MAAM,EACN,MAAM,EACN,QAAQ,EACR,WAAW,EACX,UAAgB,EAChB,GAAW,EACX,OAAY,EACZ,SAAS,EACT,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,gBAAgB,GACjB,EAAE,oBAAoB,2CA4GtB;AAED,eAAe,eAAe,CAAC"}

package/dist/kit/components/data-table-headers/DebouncedFilterField.d.ts

@@ -0,0 +1,23 @@
+import { Control, FieldValues } from 'react-hook-form';
+import { FilterFieldConfig } from './types';
+export interface DebouncedFilterFieldProps {
+    field: FilterFieldConfig;
+    /** External value (source of truth). */
+    value: unknown;
+    /** Push the (debounced) value upstream. */
+    onChange: (value: unknown) => void;
+    debounceMs: number;
+    control: Control<FieldValues>;
+    className?: string;
+}
+/**
+ * Wraps a free-typing field (text/email/password/number/textarea) with a local
+ * draft so keystrokes feel instant while the upstream `onChange` is debounced.
+ *
+ * The external `value` stays the single source of truth: the draft is only a
+ * typing buffer. When the external value changes for reasons other than this
+ * field's own push (URL hydration, programmatic clear), the draft resyncs and
+ * any in-flight debounced push is cancelled.
+ */
+export declare function DebouncedFilterField({ field, value, onChange, debounceMs, control, className, }: DebouncedFilterFieldProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=DebouncedFilterField.d.ts.map

package/dist/kit/components/data-table-headers/DebouncedFilterField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DebouncedFilterField.d.ts","sourceRoot":"","sources":["../../../../src/kit/components/data-table-headers/DebouncedFilterField.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAM5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,iBAAiB,CAAC;IACzB,wCAAwC;IACxC,KAAK,EAAE,OAAO,CAAC;IACf,2CAA2C;IAC3C,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,KAAK,EACL,KAAK,EACL,QAAQ,EACR,UAAU,EACV,OAAO,EACP,SAAS,GACV,EAAE,yBAAyB,2CA6C3B"}

package/dist/kit/components/data-table-headers/FilterFieldRenderer.d.ts

@@ -0,0 +1,19 @@
+import { Control, FieldValues } from 'react-hook-form';
+import { FilterFieldConfig } from './types';
+export interface FilterFieldRendererProps {
+    field: FilterFieldConfig;
+    /** Current value for this field (from the external values map). */
+    value: unknown;
+    /** Push a new value for this field upstream. */
+    onChange: (value: unknown) => void;
+    debounceMs: number;
+    /** Throwaway control shim so date fields' `useWatch` does not throw. */
+    control: Control<FieldValues>;
+}
+/**
+ * Renders a single filter field by mirroring FormBuilderField's type → component
+ * mapping, but WITHOUT react-hook-form's `useController`. Values flow in via
+ * props and out via `onChange`; the header owns no field state.
+ */
+export declare function FilterFieldRenderer({ field, value, onChange, debounceMs, control, }: FilterFieldRendererProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=FilterFieldRenderer.d.ts.map

package/dist/kit/components/data-table-headers/FilterFieldRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilterFieldRenderer.d.ts","sourceRoot":"","sources":["../../../../src/kit/components/data-table-headers/FilterFieldRenderer.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAsB5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AA8BjD,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,iBAAiB,CAAC;IACzB,mEAAmE;IACnE,KAAK,EAAE,OAAO,CAAC;IACf,gDAAgD;IAChD,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,KAAK,EACL,KAAK,EACL,QAAQ,EACR,UAAU,EACV,OAAO,GACR,EAAE,wBAAwB,kDAsH1B"}

package/dist/kit/components/data-table-headers/index.d.ts

@@ -0,0 +1,7 @@
+export * from './DataTableHeader';
+export * from './FilterFieldRenderer';
+export * from './DebouncedFilterField';
+export * from './useDataTableHeaderUrl';
+export * from './urlSerialization';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/kit/components/data-table-headers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/kit/components/data-table-headers/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC"}

package/dist/kit/components/data-table-headers/types.d.ts

@@ -0,0 +1,76 @@
+import { ReactNode } from 'react';
+import { DataTableAction } from '../../builder/data-table/types';
+import { FormBuilderFieldConfig } from '../../builder/form/types';
+/**
+ * A single filter field definition. Reuses {@link FormBuilderFieldConfig} so
+ * field definitions for the header work exactly like FormBuilder fields, but
+ * the header renders them WITHOUT react-hook-form and holds no value state.
+ *
+ * Supported `type`s: text, email, password, number (plain), textarea, select,
+ * autocomplete, checkbox, switch, radio, month, month_range, time, time_range,
+ * and the date family (date, date_picker, date_range, date_time,
+ * date_time_range).
+ *
+ * Unsupported in a filter header: object, array, custom_field, hidden — these
+ * are skipped with a dev warning.
+ */
+export type FilterFieldConfig = FormBuilderFieldConfig;
+/**
+ * Action shown on the right side of the header. Reuses the DataTable action
+ * shape and rendering, mirroring DataTable's `renderActionButton`.
+ */
+export type DataTableHeaderAction = DataTableAction;
+/**
+ * Adapter that lets the URL sync work against an arbitrary URL source instead
+ * of the browser History API. Provide this in environments with their own
+ * router (e.g. TanStack Router) so the header does not fight the router for
+ * control of the URL.
+ */
+export interface UrlSyncAdapter {
+    /** Read the current query params as a flat map (repeated keys -> string[]). */
+    read: () => Record<string, string | string[]>;
+    /** Write the given query params back to the URL. */
+    write: (params: Record<string, string | string[]>) => void;
+}
+/**
+ * URL sync option.
+ * - `false` / `undefined`: disabled.
+ * - `true`: use the native History API (URLSearchParams + replaceState).
+ * - `UrlSyncAdapter`: use the provided adapter (recommended when a router owns
+ *   the URL).
+ */
+export type UrlSyncOption = boolean | UrlSyncAdapter;
+export interface DataTableHeaderProps {
+    /** Filter field definitions (reuses FormBuilder field config). */
+    fields: FilterFieldConfig[];
+    /**
+     * Externally-owned filter values, keyed by `field.name`. This is the single
+     * source of truth — the header never holds its own copy.
+     */
+    values: Record<string, unknown>;
+    /** Called whenever a single field changes (debounced for free-typing inputs). */
+    onChange: (name: string, value: unknown) => void;
+    /**
+     * Bulk setter used to hydrate values from the URL on mount. If omitted, the
+     * header falls back to issuing one `onChange` per hydrated field.
+     */
+    onChangeAll?: (next: Record<string, unknown>) => void;
+    /** Debounce (ms) applied to free-typing inputs. Default 400. */
+    debounceMs?: number;
+    /** Enable URL sync. See {@link UrlSyncOption}. Default disabled. */
+    url?: UrlSyncOption;
+    /** Right-side action buttons. */
+    actions?: DataTableHeaderAction[];
+    /**
+     * Refresh handler. When provided, a default refresh button (mirroring the
+     * DataTable's standard refresh button) is rendered before the actions. Omit
+     * to hide it.
+     */
+    onRefresh?: () => void | Promise<void>;
+    /** Optional content rendered between filters and actions. */
+    children?: ReactNode;
+    className?: string;
+    filtersClassName?: string;
+    actionsClassName?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/kit/components/data-table-headers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/kit/components/data-table-headers/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvE;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GAAG,sBAAsB,CAAC;AAEvD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,eAAe,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC9C,oDAAoD;IACpD,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,KAAK,IAAI,CAAC;CAC5D;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,cAAc,CAAC;AAErD,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAE5B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhC,iFAAiF;IACjF,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAEjD;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAEtD,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,oEAAoE;IACpE,GAAG,CAAC,EAAE,aAAa,CAAC;IAEpB,iCAAiC;IACjC,OAAO,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAElC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B"}

package/dist/kit/components/data-table-headers/urlSerialization.d.ts

@@ -0,0 +1,12 @@
+import { FilterFieldConfig } from './types';
+/**
+ * Serialize a full values object into a query-param map. Repeated keys are
+ * represented as string[]; everything else as string.
+ */
+export declare function serializeAll(fields: FilterFieldConfig[], values: Record<string, unknown>): Record<string, string | string[]>;
+/**
+ * Deserialize a query-param map back into typed filter values, guided by field
+ * definitions. Only keys present in the params are included in the result.
+ */
+export declare function deserializeAll(fields: FilterFieldConfig[], params: Record<string, string | string[]>): Record<string, unknown>;
+//# sourceMappingURL=urlSerialization.d.ts.map

package/dist/kit/components/data-table-headers/urlSerialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"urlSerialization.d.ts","sourceRoot":"","sources":["../../../../src/kit/components/data-table-headers/urlSerialization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAwDjD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,iBAAiB,EAAE,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAqCnC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,iBAAiB,EAAE,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GACxC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA+DzB"}

package/dist/kit/components/data-table-headers/useDataTableHeaderUrl.d.ts

@@ -0,0 +1,36 @@
+import { Control, FieldValues } from 'react-hook-form';
+import { FilterFieldConfig, UrlSyncAdapter } from './types';
+/**
+ * Default URL adapter backed by the browser History API. Suitable for
+ * router-less contexts (plain apps, Storybook). In an app whose router owns the
+ * URL (e.g. TanStack Router), pass a custom {@link UrlSyncAdapter} instead so
+ * the header does not fight the router.
+ */
+export declare const nativeAdapter: UrlSyncAdapter;
+export interface UseDataTableHeaderUrlOptions {
+    enabled: boolean;
+    fields: FilterFieldConfig[];
+    values: Record<string, unknown>;
+    adapter: UrlSyncAdapter;
+    /** Bulk hydrate used on mount. */
+    onHydrate: (next: Record<string, unknown>) => void;
+}
+/**
+ * Two-way URL sync for the filter header:
+ * - On mount, reads params from the adapter and hydrates the external values.
+ * - On every values change, writes the serialized params back to the adapter.
+ *
+ * Holds no filter state of its own; the external `values` remain the single
+ * source of truth.
+ */
+export declare function useDataTableHeaderUrl({ enabled, fields, values, adapter, onHydrate, }: UseDataTableHeaderUrlOptions): void;
+/**
+ * A throwaway react-hook-form control used solely to satisfy date field
+ * components that call `useWatch({ control })`. It holds NO filter data —
+ * nothing ever writes to it — so it does not violate the "no internal state"
+ * rule. Cross-field date constraints (`minDateFromField`/`maxDateFromField`)
+ * resolve against this empty form and therefore won't apply in filters; static
+ * `minDate`/`maxDate` still work.
+ */
+export declare function useFilterControl(): Control<FieldValues>;
+//# sourceMappingURL=useDataTableHeaderUrl.d.ts.map

package/dist/kit/components/data-table-headers/useDataTableHeaderUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDataTableHeaderUrl.d.ts","sourceRoot":"","sources":["../../../../src/kit/components/data-table-headers/useDataTableHeaderUrl.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGjE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,cA4B3B,CAAC;AAEF,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,EAAE,cAAc,CAAC;IACxB,kCAAkC;IAClC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CACpD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,OAAO,EACP,MAAM,EACN,MAAM,EACN,OAAO,EACP,SAAS,GACV,EAAE,4BAA4B,GAAG,IAAI,CA4BrC;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAAC,WAAW,CAAC,CAGvD"}

package/dist/kit/themes/clean-slate.css

@@ -4604,6 +4604,10 @@
       display: flex;
     }
 
+    .sm\:w-auto {
+      width: auto;
+    }
+
     .sm\:max-w-lg {
       max-width: var(--container-lg);
     }
@@ -4612,6 +4616,10 @@
       max-width: var(--container-sm);
     }
 
+    .sm\:min-w-\[180px\] {
+      min-width: 180px;
+    }
+
     .sm\:grid-cols-1 {
       grid-template-columns: repeat(1, minmax(0, 1fr));
     }

package/dist/kit/themes/default.css

@@ -4611,6 +4611,10 @@
       display: flex;
     }
 
+    .sm\:w-auto {
+      width: auto;
+    }
+
     .sm\:max-w-lg {
       max-width: var(--container-lg);
     }
@@ -4619,6 +4623,10 @@
       max-width: var(--container-sm);
     }
 
+    .sm\:min-w-\[180px\] {
+      min-width: 180px;
+    }
+
     .sm\:grid-cols-1 {
       grid-template-columns: repeat(1, minmax(0, 1fr));
     }

package/dist/kit/themes/minimal-modern.css

@@ -4604,6 +4604,10 @@
       display: flex;
     }
 
+    .sm\:w-auto {
+      width: auto;
+    }
+
     .sm\:max-w-lg {
       max-width: var(--container-lg);
     }
@@ -4612,6 +4616,10 @@
       max-width: var(--container-sm);
     }
 
+    .sm\:min-w-\[180px\] {
+      min-width: 180px;
+    }
+
     .sm\:grid-cols-1 {
       grid-template-columns: repeat(1, minmax(0, 1fr));
     }

package/dist/kit/themes/spotify.css

@@ -4604,6 +4604,10 @@
       display: flex;
     }
 
+    .sm\:w-auto {
+      width: auto;
+    }
+
     .sm\:max-w-lg {
       max-width: var(--container-lg);
     }
@@ -4612,6 +4616,10 @@
       max-width: var(--container-sm);
     }
 
+    .sm\:min-w-\[180px\] {
+      min-width: 180px;
+    }
+
     .sm\:grid-cols-1 {
       grid-template-columns: repeat(1, minmax(0, 1fr));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k3-tech/react-kit",
-  "version": "0.0.60",
+  "version": "0.0.62",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/index.ts

@@ -25,6 +25,7 @@ export * from './kit/components/fileuploader';
 export * from './kit/components/numpad';
 export * from './kit/components/keyboard';
 export * from './kit/components/timepicker';
+export * from './kit/components/data-table-headers';
 
 // -----------------------------
 // KIT: layouts (admin)

package/src/kit/builder/data-table/components/DataTable.tsx

@@ -14,6 +14,7 @@ import {
 } from '@tanstack/react-table';
 import { Loader2, RefreshCw } from 'lucide-react';
 import * as React from 'react';
+import type { UseFormReturn } from 'react-hook-form';
 import { cn } from '../../../../shadcn/lib/utils';
 import {
   Accordion,
@@ -65,10 +66,11 @@ export interface DataTableProps<TData, TValue> {
   // UI
   className?: string;
   emptyText?: string;
-  // Filters UI (section-based or simple)
+  // Filters UI (section-based or simple) // what's so simple about this
   formFilters?: DataTableFiltersProp;
   formFilterValues?: Record<string, unknown> | null;
   onFormFilterChange?: (values: Record<string, unknown>) => void;
+  formFilterForm?: UseFormReturn<any>;
   // Selection & Actions
   selectable?: boolean;
   actions?: DataTableAction[];
@@ -111,6 +113,7 @@ export function DataTable<TData, TValue>({
   onTable,
   className,
   emptyText = 'No results.',
+  formFilterForm,
   formFilters,
   formFilterValues,
   onFormFilterChange,
@@ -385,7 +388,7 @@ export function DataTable<TData, TValue>({
                     </AccordionTrigger>
                     <AccordionContent className="px-4 pb-4 pt-5">
                       <FormBuilder
-                        key={JSON.stringify(formFilterValues ?? {})}
+                        form={formFilterForm}
                         sections={formFilters as FormBuilderSectionConfig[]}
                         defaultValues={formFilterValues}
                         onSubmit={(data) =>

package/src/kit/builder/form/components/fields/NumberField.tsx

@@ -10,7 +10,7 @@ export function NumberField({
 }: FieldRenderProps) {
   const innerValue = value as number;
   const [displayValue, setDisplayValue] = useState(
-    innerValue.toLocaleString('id-ID'),
+    (Number(innerValue) || "").toLocaleString('id-ID'),
   );
 
   if (field.numberMode === 'currency') {

package/src/kit/components/data-table-headers/DataTableHeader.tsx

@@ -0,0 +1,158 @@
+import React, { useCallback } from 'react';
+import { RefreshCw } from 'lucide-react';
+import { cn } from '@/shadcn/lib/utils';
+import { Button } from '@/shadcn/ui/button';
+import { FilterFieldRenderer } from './FilterFieldRenderer';
+import type { DataTableHeaderAction, DataTableHeaderProps } from './types';
+import {
+  nativeAdapter,
+  useDataTableHeaderUrl,
+  useFilterControl,
+} from './useDataTableHeaderUrl';
+
+/**
+ * A plug-in replacement for the DataTable's default filter + actions header.
+ *
+ * Plug it into `DataTable`'s `CustomHeaderComponent`:
+ *```
+ *   <DataTable
+ *     CustomHeaderComponent={() => (
+ *       <DataTableHeader
+ *         fields={filterFields}
+ *         values={filtersState} // owned by your list hook
+ *         onChange={setFilter} // updates that same state
+ *         actions={[addAction, refreshAction]}
+ *       />
+ *     )}
+ *   />
+ *```
+ * Unlike the default FormBuilder-based filter, this header holds NO filter data
+ * of its own — `values` is the single source of truth, so the UI can never
+ * drift from what is sent to the API. Filters apply on every change (no
+ * Apply/Clear); free-typing inputs are debounced internally.
+ */
+export function DataTableHeader({
+  fields,
+  values,
+  onChange,
+  onChangeAll,
+  debounceMs = 400,
+  url = false,
+  actions = [],
+  onRefresh,
+  children,
+  className,
+  filtersClassName,
+  actionsClassName,
+}: DataTableHeaderProps) {
+  const control = useFilterControl();
+
+  const adapter = url === true ? nativeAdapter : url || nativeAdapter;
+
+  // biome-ignore lint: see below
+  const handleHydrate = useCallback(
+    (next: Record<string, unknown>) => {
+      if (onChangeAll) {
+        onChangeAll({ ...values, ...next });
+        return;
+      }
+      for (const [name, value] of Object.entries(next)) onChange(name, value);
+    },
+    // `values` intentionally omitted: hydration runs once on mount and we don't
+    // want to re-bind to every value change.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [onChange, onChangeAll],
+  );
+
+  useDataTableHeaderUrl({
+    enabled: url !== false,
+    fields,
+    values,
+    adapter,
+    onHydrate: handleHydrate,
+  });
+
+  const renderActionButton = (action: DataTableHeaderAction, key: React.Key) => {
+    if (action.element)
+      return <React.Fragment key={key}>{action.element}</React.Fragment>;
+
+    const content = (
+      <div className="flex items-center gap-x-2">
+        {action.icon && (
+          <span
+            className={cn(action.iconPosition === 'right' ? 'order-last' : '')}
+          >
+            {action.icon}
+          </span>
+        )}
+        {action.label}
+      </div>
+    );
+
+    return (
+      <Button
+        key={key}
+        size="sm"
+        variant={action.variant ?? 'default'}
+        disabled={action.disabled}
+        onClick={action.onClick}
+        className="h-8"
+      >
+        {content}
+      </Button>
+    );
+  };
+
+  return (
+    <div
+      className={cn('flex items-start justify-between gap-3', className)}
+    >
+      {/* Filters: grow + wrap */}
+      <div
+        className={cn(
+          'flex min-w-0 flex-1 flex-wrap items-end gap-2',
+          filtersClassName,
+        )}
+      >
+        {fields.map((field) => (
+          <FilterFieldRenderer
+            key={field.name}
+            field={field}
+            value={values[field.name]}
+            onChange={(value) => onChange(field.name, value)}
+            debounceMs={debounceMs}
+            control={control}
+          />
+        ))}
+      </div>
+
+      {children}
+
+      {/* Actions: pinned right, no wrap */}
+      {(actions.length > 0 || onRefresh) && (
+        <div
+          className={cn(
+            'flex shrink-0 flex-nowrap items-center gap-2',
+            actionsClassName,
+          )}
+        >
+          {onRefresh && (
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={onRefresh}
+              className="h-8"
+              title="Refresh"
+            >
+              <RefreshCw className="h-4 w-4" />
+              <span>Refresh</span>
+            </Button>
+          )}
+          {actions.map((action) => renderActionButton(action, action.key))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default DataTableHeader;

package/src/kit/components/data-table-headers/DebouncedFilterField.tsx

@@ -0,0 +1,83 @@
+import { useEffect, useRef, useState } from 'react';
+import { useDebouncedCallback } from 'use-debounce';
+import type { Control, FieldValues } from 'react-hook-form';
+import {
+  NumberField,
+  TextField,
+  TextareaField,
+} from '@/kit/builder/form/components/fields';
+import type { FilterFieldConfig } from './types';
+
+export interface DebouncedFilterFieldProps {
+  field: FilterFieldConfig;
+  /** External value (source of truth). */
+  value: unknown;
+  /** Push the (debounced) value upstream. */
+  onChange: (value: unknown) => void;
+  debounceMs: number;
+  control: Control<FieldValues>;
+  className?: string;
+}
+
+/**
+ * Wraps a free-typing field (text/email/password/number/textarea) with a local
+ * draft so keystrokes feel instant while the upstream `onChange` is debounced.
+ *
+ * The external `value` stays the single source of truth: the draft is only a
+ * typing buffer. When the external value changes for reasons other than this
+ * field's own push (URL hydration, programmatic clear), the draft resyncs and
+ * any in-flight debounced push is cancelled.
+ */
+export function DebouncedFilterField({
+  field,
+  value,
+  onChange,
+  debounceMs,
+  control,
+  className,
+}: DebouncedFilterFieldProps) {
+  const [draft, setDraft] = useState<unknown>(value);
+  const lastPushedRef = useRef<unknown>(value);
+
+  const debounced = useDebouncedCallback((v: unknown) => {
+    lastPushedRef.current = v;
+    onChange(v);
+  }, debounceMs);
+
+  const handleChange = (v: unknown) => {
+    setDraft(v);
+    debounced(v);
+  };
+
+  // Resync the draft when the external value changes for a reason other than
+  // this field's own debounced push (e.g. URL hydration or external clear).
+  useEffect(() => {
+    if (!Object.is(value, lastPushedRef.current)) {
+      debounced.cancel();
+      lastPushedRef.current = value;
+      setDraft(value);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [value]);
+
+  // Flush a pending value on unmount so a half-typed filter isn't lost.
+  useEffect(
+    () => () => {
+      debounced.flush();
+    },
+    [debounced],
+  );
+
+  const common = {
+    field,
+    control,
+    fieldPath: field.name,
+    value: draft,
+    onChange: handleChange,
+    className,
+  };
+
+  if (field.type === 'textarea') return <TextareaField {...common} />;
+  if (field.type === 'number') return <NumberField {...common} />;
+  return <TextField {...common} />;
+}