@asteby/metacore-runtime-react 20.1.7 → 21.0.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @asteby/metacore-runtime-react
 
+## 21.0.0
+
+### Minor Changes
+
+- 84aeaf2: feat(kanban): dynamic column filters on DynamicKanban
+
+  The board now filters like its DynamicTable sibling. A filter bar above the
+  lanes exposes a global search box plus one chip per filterable field (from
+  `metadata.filters[]` and every `filterable` column), driving the SAME
+  server-side `f_<key>=<op>:<value>` / `search` params — so a model's table and
+  kanban views filter identically.
+  - **ui**: extracted the per-column filter popover into a new, TanStack-agnostic
+    `ColumnFilterControl` (select/boolean/dynamic_select/text/number_range/
+    date_range). `FilterableColumnHeader` now delegates its filter UI to it
+    (behavior unchanged); it also powers the kanban's labeled filter chips.
+  - **runtime-react**: new `useDynamicFilters(metadata)` hook owning the filter
+    state, option prefetch, config derivation and param serialization (factored
+    out of DynamicTable's inline logic). `DynamicKanban` consumes it and gains a
+    `defaultFilters` prop for parity with DynamicTable.
+
+### Patch Changes
+
+- Updated dependencies [84aeaf2]
+  - @asteby/metacore-ui@2.7.0
+
 ## 20.1.7
 
 ### Patch Changes

package/dist/dynamic-kanban.d.ts

@@ -68,6 +68,11 @@ export interface DynamicKanbanProps {
     timeZone?: string;
     /** ISO 4217 currency for money card fields (org config). */
     currency?: string;
+    /**
+     * Static equality filters always applied to the board (never shown as a
+     * removable chip). Same contract as DynamicTable's `defaultFilters`.
+     */
+    defaultFilters?: Record<string, any>;
 }
-export declare function DynamicKanban({ model, endpoint, refreshTrigger, onCardClick, onAction, pageSize, timeZone, currency, }: DynamicKanbanProps): React.JSX.Element;
+export declare function DynamicKanban({ model, endpoint, refreshTrigger, onCardClick, onAction, pageSize, timeZone, currency, defaultFilters, }: DynamicKanbanProps): React.JSX.Element;
 //# sourceMappingURL=dynamic-kanban.d.ts.map

package/dist/dynamic-kanban.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-kanban.d.ts","sourceRoot":"","sources":["../src/dynamic-kanban.tsx"],"names":[],"mappings":"AA0BA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAoC9B,OAAO,KAAK,EACR,aAAa,EACb,gBAAgB,EAGhB,SAAS,EACT,eAAe,EAClB,MAAM,SAAS,CAAA;AAMhB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,EAAE,CAejE;AAQD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,mBAAmB,CAAA;AAE/C,wBAAgB,YAAY,CACxB,OAAO,EAAE,GAAG,EAAE,EACd,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,EAAE,GACpB,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAepB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAC/B,WAAW,EAAE,eAAe,EAAE,GAAG,SAAS,EAC1C,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACX,OAAO,CAOT;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAC/B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,EAC3B,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACnB,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAYpB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC7B,QAAQ,EAAE,aAAa,EACvB,SAAS,SAAI,GACd;IAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAkBhE;AA8BD,MAAM,WAAW,kBAAkB;IAC/B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kFAAkF;IAClF,cAAc,CAAC,EAAE,GAAG,CAAA;IACpB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAA;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAAA;IAC7C;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,wBAAgB,aAAa,CAAC,EAC1B,KAAK,EACL,QAAQ,EACR,cAAc,EACd,WAAW,EACX,QAAQ,EACR,QAAc,EACd,QAAQ,EACR,QAAQ,GACX,EAAE,kBAAkB,qBAqSpB"}
+{"version":3,"file":"dynamic-kanban.d.ts","sourceRoot":"","sources":["../src/dynamic-kanban.tsx"],"names":[],"mappings":"AA0BA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAuC9B,OAAO,KAAK,EACR,aAAa,EACb,gBAAgB,EAGhB,SAAS,EACT,eAAe,EAClB,MAAM,SAAS,CAAA;AAMhB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,EAAE,CAejE;AAQD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,mBAAmB,CAAA;AAE/C,wBAAgB,YAAY,CACxB,OAAO,EAAE,GAAG,EAAE,EACd,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,EAAE,GACpB,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAepB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAC/B,WAAW,EAAE,eAAe,EAAE,GAAG,SAAS,EAC1C,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACX,OAAO,CAOT;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAC/B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,EAC3B,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACnB,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAYpB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC7B,QAAQ,EAAE,aAAa,EACvB,SAAS,SAAI,GACd;IAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAkBhE;AA8BD,MAAM,WAAW,kBAAkB;IAC/B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kFAAkF;IAClF,cAAc,CAAC,EAAE,GAAG,CAAA;IACpB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAA;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAAA;IAC7C;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CACvC;AAED,wBAAgB,aAAa,CAAC,EAC1B,KAAK,EACL,QAAQ,EACR,cAAc,EACd,WAAW,EACX,QAAQ,EACR,QAAc,EACd,QAAQ,EACR,QAAQ,EACR,cAAc,GACjB,EAAE,kBAAkB,qBAsXpB"}

package/dist/dynamic-kanban.js

@@ -2,11 +2,13 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { DndContext, DragOverlay, PointerSensor, useSensor, useSensors, useDraggable, useDroppable, } from '@dnd-kit/core';
-import { MoreHorizontal } from 'lucide-react';
+import { MoreHorizontal, Search, X } from 'lucide-react';
 import { toast } from 'sonner';
-import { Badge, Button, Card, CardContent, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, Skeleton, } from '@asteby/metacore-ui/primitives';
+import { Badge, Button, Card, CardContent, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, Input, Skeleton, } from '@asteby/metacore-ui/primitives';
+import { ColumnFilterControl } from '@asteby/metacore-ui/data-table';
 import { generateBadgeStyles, optionColor } from '@asteby/metacore-ui/lib';
 import { useApi } from './api-context';
+import { useDynamicFilters } from './use-dynamic-filters';
 import { useMetadataCache } from './metadata-cache';
 import { ActivityValueRenderer } from './activity-value-renderer';
 import { DynamicIcon } from './dynamic-icon';
@@ -146,7 +148,7 @@ function useIsDarkTheme() {
     }, []);
     return isDark;
 }
-export function DynamicKanban({ model, endpoint, refreshTrigger, onCardClick, onAction, pageSize = 200, timeZone, currency, }) {
+export function DynamicKanban({ model, endpoint, refreshTrigger, onCardClick, onAction, pageSize = 200, timeZone, currency, defaultFilters, }) {
     const { t, i18n } = useTranslation();
     const api = useApi();
     const isDark = useIsDarkTheme();
@@ -194,6 +196,10 @@ export function DynamicKanban({ model, endpoint, refreshTrigger, onCardClick, on
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [model]);
+    // Shared metadata-driven filter engine — the SAME configs, option prefetch
+    // and `f_<key>` serialization DynamicTable uses, so the board filters
+    // identically to its table sibling.
+    const { globalFilter, setGlobalFilter, columnFilterConfigs, filterParams, activeFilterCount, clearAll, } = useDynamicFilters(metadata, { defaultFilters });
     // ---- records fetch (same path as DynamicTable, single large page) ----
     const fetchData = useCallback(async () => {
         if (!metadata)
@@ -201,7 +207,7 @@ export function DynamicKanban({ model, endpoint, refreshTrigger, onCardClick, on
         setLoadingData(true);
         try {
             const res = (await api.get(endpoint || `/data/${model}`, {
-                params: { page: 1, per_page: pageSize },
+                params: { page: 1, per_page: pageSize, ...filterParams },
             }));
             if (res.data.success)
                 setRecords(res.data.data || []);
@@ -212,12 +218,33 @@ export function DynamicKanban({ model, endpoint, refreshTrigger, onCardClick, on
         finally {
             setLoadingData(false);
         }
-    }, [api, endpoint, model, metadata, pageSize]);
+    }, [api, endpoint, model, metadata, pageSize, filterParams]);
+    // Refetch when metadata resolves, on an explicit refresh, or when the
+    // filters change. `fetchData` is stable while `filterParams` is unchanged
+    // (both memoized), so this only re-runs on real input changes. Debounced so
+    // typing in the search box doesn't fire a request per keystroke.
     useEffect(() => {
-        if (metadata)
+        if (!metadata)
+            return;
+        const handle = setTimeout(() => {
             void fetchData();
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [metadata, refreshTrigger]);
+        }, 200);
+        return () => clearTimeout(handle);
+    }, [fetchData, metadata, refreshTrigger]);
+    // Filterable fields for the toolbar, in metadata order (explicit filters
+    // first, then filterable columns), each labeled from its metadata source.
+    const filterFields = useMemo(() => {
+        if (!metadata)
+            return [];
+        const out = [];
+        for (const [key, config] of columnFilterConfigs) {
+            const f = metadata.filters?.find((x) => x.key === key);
+            const c = metadata.columns.find((x) => x.key === key);
+            const rawLabel = f?.label || c?.label || key;
+            out.push({ key, label: t(rawLabel, { defaultValue: rawLabel }), config });
+        }
+        return out;
+    }, [metadata, columnFilterConfigs, t]);
     const stages = useMemo(() => (metadata ? deriveStages(metadata) : []), [metadata]);
     const groupByKey = metadata?.group_by || '';
     const transitions = metadata?.transitions;
@@ -318,13 +345,13 @@ export function DynamicKanban({ model, endpoint, refreshTrigger, onCardClick, on
             order: Number.MAX_SAFE_INTEGER,
         });
     }
-    return (_jsxs(DndContext, { sensors: sensors, onDragStart: onDragStart, onDragEnd: onDragEnd, children: [_jsx("div", { className: "flex min-w-0 gap-4 overflow-x-auto p-1", "data-testid": "kanban-board", children: lanes.map((stage) => {
-                    const cards = grouped.get(stage.key) ?? [];
-                    const droppableAllowed = !activeId ||
-                        stage.key === activeStage ||
-                        isTransitionAllowed(transitions, activeStage, stage.key);
-                    return (_jsx(KanbanLane, { stage: stage, count: cards.length, isDark: isDark, dimmed: !!activeId && !droppableAllowed, disabled: !!activeId && !droppableAllowed, children: loadingData && cards.length === 0 ? (_jsxs(_Fragment, { children: [_jsx(Skeleton, { className: "h-20 w-full" }), _jsx(Skeleton, { className: "h-20 w-full" })] })) : cards.length === 0 ? (_jsx("p", { className: "px-1 py-6 text-center text-xs text-muted-foreground", children: t('kanban.emptyLane', { defaultValue: 'Sin tarjetas' }) })) : (cards.map((card) => (_jsx(KanbanCard, { card: card, titleCol: titleCol, fieldCols: fieldCols, actions: rowActions, locale: i18n.language, timeZone: timeZone, currency: currency, onClick: onCardClick, onAction: handleInternalAction }, String(card.id))))) }, stage.key));
-                }) }), _jsx(DragOverlay, { children: activeCard ? (_jsx(CardPreview, { card: activeCard, titleCol: titleCol, fieldCols: fieldCols, locale: i18n.language, timeZone: timeZone, currency: currency })) : null }), rowActionDialogs] }));
+    return (_jsxs("div", { className: "flex flex-col gap-3", children: [_jsxs("div", { className: "flex flex-wrap items-center gap-2", "data-testid": "kanban-filters", children: [_jsxs("div", { className: "relative", children: [_jsx(Search, { className: "pointer-events-none absolute left-2.5 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground" }), _jsx(Input, { value: globalFilter, onChange: (e) => setGlobalFilter(e.target.value), placeholder: t('kanban.searchPlaceholder', { defaultValue: 'Buscar...' }), className: "h-8 w-52 pl-8 text-sm" })] }), filterFields.map((field) => (_jsx(ColumnFilterControl, { showLabel: true, label: field.label, filterKey: field.config.filterKey, filterType: field.config.filterType, filterOptions: field.config.options, filterLoading: field.config.loading, filterSearchEndpoint: field.config.searchEndpoint, selectedValues: field.config.selectedValues, onFilterChange: field.config.onFilterChange }, field.key))), activeFilterCount > 0 && (_jsxs(Button, { variant: "ghost", size: "sm", className: "h-8 gap-1 text-xs text-muted-foreground", onClick: clearAll, children: [_jsx(X, { className: "h-3.5 w-3.5" }), t('kanban.clearFilters', { defaultValue: 'Limpiar' }), ` (${activeFilterCount})`] }))] }), _jsxs(DndContext, { sensors: sensors, onDragStart: onDragStart, onDragEnd: onDragEnd, children: [_jsx("div", { className: "flex min-w-0 gap-4 overflow-x-auto p-1", "data-testid": "kanban-board", children: lanes.map((stage) => {
+                            const cards = grouped.get(stage.key) ?? [];
+                            const droppableAllowed = !activeId ||
+                                stage.key === activeStage ||
+                                isTransitionAllowed(transitions, activeStage, stage.key);
+                            return (_jsx(KanbanLane, { stage: stage, count: cards.length, isDark: isDark, dimmed: !!activeId && !droppableAllowed, disabled: !!activeId && !droppableAllowed, children: loadingData && cards.length === 0 ? (_jsxs(_Fragment, { children: [_jsx(Skeleton, { className: "h-20 w-full" }), _jsx(Skeleton, { className: "h-20 w-full" })] })) : cards.length === 0 ? (_jsx("p", { className: "px-1 py-6 text-center text-xs text-muted-foreground", children: t('kanban.emptyLane', { defaultValue: 'Sin tarjetas' }) })) : (cards.map((card) => (_jsx(KanbanCard, { card: card, titleCol: titleCol, fieldCols: fieldCols, actions: rowActions, locale: i18n.language, timeZone: timeZone, currency: currency, onClick: onCardClick, onAction: handleInternalAction }, String(card.id))))) }, stage.key));
+                        }) }), _jsx(DragOverlay, { children: activeCard ? (_jsx(CardPreview, { card: activeCard, titleCol: titleCol, fieldCols: fieldCols, locale: i18n.language, timeZone: timeZone, currency: currency })) : null }), rowActionDialogs] })] }));
 }
 function KanbanLane({ stage, count, isDark, dimmed, disabled, children }) {
     const { t } = useTranslation();

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from './options-context';
 export * from './dynamic-table';
 export { DynamicKanban, type DynamicKanbanProps, deriveStages, groupByStage, isTransitionAllowed, applyOptimisticMove, selectCardColumns, UNASSIGNED_LANE, } from './dynamic-kanban';
 export { DynamicView, resolveViewRenderer, readViewFromSearch, resolveActiveView, type DynamicViewProps, } from './dynamic-view';
+export { useDynamicFilters, type UseDynamicFiltersOptions, type UseDynamicFiltersResult, } from './use-dynamic-filters';
 export * from './dynamic-form';
 export { ActionModalDispatcher, type ActionModalProps, } from './action-modal-dispatcher';
 export { ModelActionToolbar, useModelActions, type ModelActionToolbarProps, type ActionPlacement, } from './model-action-toolbar';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,SAAS,CAAA;AACvB,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,OAAO,EACH,aAAa,EACb,KAAK,kBAAkB,EACvB,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,GAClB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACH,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,gBAAgB,GACxB,MAAM,gBAAgB,CAAA;AACvB,cAAc,gBAAgB,CAAA;AAC9B,OAAO,EACH,qBAAqB,EACrB,KAAK,gBAAgB,GACxB,MAAM,2BAA2B,CAAA;AAClC,OAAO,EACH,kBAAkB,EAClB,eAAe,EACf,KAAK,uBAAuB,EAC5B,KAAK,eAAe,GACvB,MAAM,wBAAwB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,OAAO,EACH,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,WAAW,EAChB,KAAK,wBAAwB,GAChC,MAAM,wBAAwB,CAAA;AAC/B,cAAc,QAAQ,CAAA;AACtB,cAAc,mBAAmB,CAAA;AACjC,OAAO,EACH,mBAAmB,EACnB,MAAM,EACN,oBAAoB,EACpB,OAAO,EACP,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,KAAK,EACV,KAAK,wBAAwB,GAChC,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACH,oBAAoB,EACpB,KAAK,0BAA0B,EAC/B,KAAK,iBAAiB,GACzB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACH,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,EACb,kBAAkB,EAClB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,OAAO,EACZ,KAAK,SAAS,GACjB,MAAM,uBAAuB,CAAA;AAC9B,cAAc,uBAAuB,CAAA;AACrC,cAAc,wBAAwB,CAAA;AACtC,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,OAAO,EACH,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,KAAK,2BAA2B,EAChC,KAAK,qBAAqB,EAC1B,KAAK,8BAA8B,GACtC,MAAM,+BAA+B,CAAA;AACtC,OAAO,EACH,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,wBAAwB,EACxB,WAAW,EACX,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,GAC9B,MAAM,yBAAyB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,YAAY,EACR,kBAAkB,EAClB,YAAY,IAAI,yBAAyB,EACzC,iBAAiB,EACjB,oBAAoB,GACvB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACH,wBAAwB,EACxB,4BAA4B,EAC5B,cAAc,EACd,oBAAoB,EACpB,KAAK,qBAAqB,GAC7B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EACH,cAAc,EACd,YAAY,EACZ,WAAW,EACX,UAAU,EACV,KAAK,mBAAmB,EACxB,KAAK,SAAS,IAAI,uBAAuB,GAC5C,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAClE,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACzE,YAAY,EAAE,wBAAwB,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAC5G,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AAC/D,YAAY,EACR,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,GACxB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EACH,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,GAC9B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACH,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,GACjB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACH,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,KAAK,qBAAqB,GAC7B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACH,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GAC3B,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACH,sBAAsB,EACtB,uBAAuB,GAC1B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACH,kBAAkB,EAClB,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,GAChC,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACH,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,eAAe,GACvB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACH,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,GACvB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACH,qBAAqB,EACrB,KAAK,0BAA0B,GAClC,MAAM,2BAA2B,CAAA;AAClC,OAAO,EACH,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,iBAAiB,GACzB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACH,aAAa,EACb,KAAK,kBAAkB,GAC1B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACH,gBAAgB,EAChB,KAAK,qBAAqB,GAC7B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACH,aAAa,EACb,eAAe,GAClB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EACR,UAAU,EACV,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,iBAAiB,EACjB,UAAU,EACV,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,oBAAoB,GACvB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACH,UAAU,EACV,SAAS,EACT,UAAU,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,cAAc,EACd,KAAK,iBAAiB,GACzB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACH,cAAc,EACd,cAAc,EACd,SAAS,EACT,UAAU,EACV,KAAK,mBAAmB,GAC3B,MAAM,2BAA2B,CAAA;AAClC,OAAO,EACH,UAAU,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,KAAK,eAAe,GACvB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACH,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,aAAa,EACb,YAAY,EACZ,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,eAAe,GACvB,MAAM,yBAAyB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -8,6 +8,7 @@ export * from './options-context';
 export * from './dynamic-table';
 export { DynamicKanban, deriveStages, groupByStage, isTransitionAllowed, applyOptimisticMove, selectCardColumns, UNASSIGNED_LANE, } from './dynamic-kanban';
 export { DynamicView, resolveViewRenderer, readViewFromSearch, resolveActiveView, } from './dynamic-view';
+export { useDynamicFilters, } from './use-dynamic-filters';
 export * from './dynamic-form';
 export { ActionModalDispatcher, } from './action-modal-dispatcher';
 export { ModelActionToolbar, useModelActions, } from './model-action-toolbar';

package/dist/use-dynamic-filters.d.ts

@@ -0,0 +1,38 @@
+import type { ColumnFilterConfig } from './dynamic-columns-shim';
+import type { TableMetadata } from './types';
+export interface UseDynamicFiltersOptions {
+    /**
+     * Static equality filters always applied (never shown as removable chips).
+     * Mirrors DynamicTable's `defaultFilters` — e.g. scoping a board to one owner.
+     */
+    defaultFilters?: Record<string, any>;
+}
+export interface UseDynamicFiltersResult {
+    /** Per-field selected values, `filterKey → values[]` (empty = inactive). */
+    dynamicFilters: Record<string, string[]>;
+    /** Free-text search term (the toolbar search box). */
+    globalFilter: string;
+    setGlobalFilter: (v: string) => void;
+    /** Config for each filterable field, keyed by the metadata filter/column key. */
+    columnFilterConfigs: Map<string, ColumnFilterConfig>;
+    /**
+     * The serialized query params (`f_<key>`, `search`, `search_columns`) ready to
+     * spread into a `/data/:model` request. Stable object identity while inputs
+     * are unchanged so a consumer can safely depend on it in a fetch effect.
+     */
+    filterParams: Record<string, any>;
+    /** Apply a field's selection (replaces its values). */
+    handleDynamicFilterChange: (filterKey: string, values: string[]) => void;
+    /** Count of fields with an active selection + the search term. */
+    activeFilterCount: number;
+    /** Clear every field filter and the search term. */
+    clearAll: () => void;
+}
+/**
+ * Reads the model's filter metadata and returns the live filter state + the
+ * serialized request params. Pure of any view concern — DynamicTable adds its
+ * own sort/pagination/`columnFilters`; DynamicKanban spreads `filterParams`
+ * straight onto its single-page fetch.
+ */
+export declare function useDynamicFilters(metadata: TableMetadata | null, opts?: UseDynamicFiltersOptions): UseDynamicFiltersResult;
+//# sourceMappingURL=use-dynamic-filters.d.ts.map

package/dist/use-dynamic-filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-dynamic-filters.d.ts","sourceRoot":"","sources":["../src/use-dynamic-filters.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,kBAAkB,EAAgB,MAAM,wBAAwB,CAAA;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CACrC;AAED,MAAM,WAAW,uBAAuB;IACtC,4EAA4E;IAC5E,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;IACxC,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAA;IACpB,eAAe,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IACpC,iFAAiF;IACjF,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;IACpD;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACjC,uDAAuD;IACvD,yBAAyB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,CAAA;IACxE,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,CAAA;IACzB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,IAAI,CAAA;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,aAAa,GAAG,IAAI,EAC9B,IAAI,GAAE,wBAA6B,GAClC,uBAAuB,CAqNzB"}

package/dist/use-dynamic-filters.js

@@ -0,0 +1,226 @@
+// useDynamicFilters — the metadata-driven filter engine shared by DynamicTable
+// and DynamicKanban. It owns nothing view-specific: given a model's
+// `TableMetadata`, it derives the per-field filter configs (from
+// `metadata.filters[]` + every `metadata.columns[].filterable` column),
+// prefetches the server-side option lists for relation/select filters, tracks
+// the selected values + global search, and serializes them into the exact
+// `f_<key>=<op>:<value>` / `search` query params the `/data/:model` endpoint
+// already understands.
+//
+// DynamicTable historically inlined this; DynamicKanban now needs the SAME
+// filtering (RFC: a board is just another view of the model), so the logic is
+// factored here to guarantee both surfaces filter identically.
+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';
+/**
+ * Reads the model's filter metadata and returns the live filter state + the
+ * serialized request params. Pure of any view concern — DynamicTable adds its
+ * own sort/pagination/`columnFilters`; DynamicKanban spreads `filterParams`
+ * straight onto its single-page fetch.
+ */
+export function useDynamicFilters(metadata, opts = {}) {
+    const { defaultFilters } = opts;
+    const api = useApi();
+    const [dynamicFilters, setDynamicFilters] = useState({});
+    const [globalFilter, setGlobalFilter] = useState('');
+    const [filterOptionsMap, setFilterOptionsMap] = useState(new Map());
+    // Prefetch the option lists for relation/select filters (once per model). The
+    // combobox needs these before the user opens it; mirrors DynamicTable's
+    // metadata-init option prefetch, narrowed to the FILTER endpoints only (the
+    // kanban renders card cells through ActivityValueRenderer, not the cell
+    // options map, so we skip that half).
+    const prefetchedSig = useRef(null);
+    useEffect(() => {
+        if (!metadata)
+            return;
+        const filterEndpoints = (metadata.filters || [])
+            .filter((f) => f.searchEndpoint &&
+            (f.type === 'select' ||
+                f.type === 'dynamic_select' ||
+                f.type === 'boolean'))
+            .map((f) => f.searchEndpoint);
+        const columnFilterEndpoints = (metadata.columns || [])
+            .filter((c) => c.filterable && c.searchEndpoint)
+            .map((c) => c.searchEndpoint);
+        const endpoints = Array.from(new Set([...filterEndpoints, ...columnFilterEndpoints]));
+        if (endpoints.length === 0)
+            return;
+        // Dedup on the endpoint set, not model identity (TableMetadata carries no
+        // name) — the same board re-rendering shouldn't refetch its options.
+        const sig = endpoints.join('|');
+        if (prefetchedSig.current === sig)
+            return;
+        prefetchedSig.current = sig;
+        let cancelled = false;
+        Promise.all(endpoints.map(async (ep) => {
+            try {
+                const res = await api.get(ep);
+                return {
+                    endpoint: ep,
+                    data: res.data?.success ? res.data.data : [],
+                };
+            }
+            catch (e) {
+                console.error(`Failed to fetch filter options for ${ep}`, e);
+                return { endpoint: ep, data: [] };
+            }
+        })).then((results) => {
+            if (cancelled)
+                return;
+            const fMap = new Map();
+            for (const r of results) {
+                fMap.set(r.endpoint, (r.data || []).map((item) => ({
+                    label: item.label || item.name || '',
+                    value: String(item.value ?? item.id ?? ''),
+                    icon: item.icon,
+                    color: item.color || item.class,
+                })));
+            }
+            setFilterOptionsMap(fMap);
+        });
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [metadata]);
+    const handleDynamicFilterChange = useCallback((filterKey, values) => {
+        setDynamicFilters((prev) => ({ ...prev, [filterKey]: values }));
+    }, []);
+    const clearAll = useCallback(() => {
+        setDynamicFilters({});
+        setGlobalFilter('');
+    }, []);
+    // Derive one ColumnFilterConfig per filterable field. Explicit
+    // `metadata.filters[]` wins; otherwise every `filterable` column yields a
+    // config with its UI inferred from the column shape. Copied 1:1 from
+    // DynamicTable so table and board build identical configs.
+    const columnFilterConfigs = useMemo(() => {
+        const map = new Map();
+        if (!metadata)
+            return map;
+        for (const f of metadata.filters ?? []) {
+            const fType = f.type;
+            let options = [];
+            if (f.options && f.options.length > 0) {
+                options = f.options.map((o) => ({
+                    label: o.label,
+                    value: String(o.value),
+                    icon: o.icon,
+                    color: o.color,
+                }));
+            }
+            if (f.searchEndpoint && filterOptionsMap.has(f.searchEndpoint)) {
+                options = filterOptionsMap.get(f.searchEndpoint) || [];
+            }
+            if (fType === 'select' && options.length === 0 && !f.searchEndpoint)
+                continue;
+            map.set(f.key, {
+                filterType: fType,
+                filterKey: f.column || f.key,
+                options,
+                selectedValues: dynamicFilters[f.column || f.key] || [],
+                onFilterChange: handleDynamicFilterChange,
+                loading: f.searchEndpoint ? !filterOptionsMap.has(f.searchEndpoint) : false,
+                searchEndpoint: f.searchEndpoint,
+            });
+        }
+        for (const c of metadata.columns ?? []) {
+            if (!c.filterable || map.has(c.key))
+                continue;
+            const hasStaticOptions = (c.options?.length ?? 0) > 0;
+            const hasEndpoint = !!c.searchEndpoint;
+            const isRelation = !!c.ref || c.filterType === 'dynamic_select';
+            let filterType;
+            if (c.filterType)
+                filterType = c.filterType;
+            else if (isRelation && hasEndpoint)
+                filterType = 'dynamic_select';
+            else if (hasStaticOptions || hasEndpoint)
+                filterType = 'select';
+            else if (c.type === 'boolean')
+                filterType = 'boolean';
+            else if (c.type === 'number')
+                filterType = 'number_range';
+            else if (DATE_CELL_TYPES.includes(c.type))
+                filterType = 'date_range';
+            else
+                filterType = 'text';
+            const options = hasStaticOptions
+                ? c.options.map((o) => ({
+                    label: o.label,
+                    value: String(o.value),
+                    icon: o.icon,
+                    color: o.color,
+                }))
+                : hasEndpoint && filterOptionsMap.has(c.searchEndpoint)
+                    ? filterOptionsMap.get(c.searchEndpoint) || []
+                    : [];
+            map.set(c.key, {
+                filterType,
+                filterKey: c.key,
+                options,
+                selectedValues: dynamicFilters[c.key] || [],
+                onFilterChange: handleDynamicFilterChange,
+                loading: hasEndpoint && !filterOptionsMap.has(c.searchEndpoint),
+                searchEndpoint: c.searchEndpoint,
+            });
+        }
+        return map;
+    }, [metadata, filterOptionsMap, dynamicFilters, handleDynamicFilterChange]);
+    const searchableKeys = useMemo(() => (metadata ? getSearchableColumnKeys(metadata) : null), [metadata]);
+    // Serialize to `/data/:model` query params — identical operator encoding to
+    // DynamicTable.buildFilterParams (IN:/RANGE:/GTE:/LTE:/ILIKE:/plain).
+    const filterParams = useMemo(() => {
+        const params = {};
+        if (globalFilter) {
+            if (searchableKeys === null) {
+                params.search = globalFilter;
+            }
+            else if (searchableKeys.length > 0) {
+                params.search = globalFilter;
+                params.search_columns = searchableKeys.join(',');
+            }
+            // searchableKeys === [] → no searchable column, skip the search param.
+        }
+        if (defaultFilters) {
+            Object.entries(defaultFilters).forEach(([key, value]) => {
+                params[`f_${key}`] = value;
+            });
+        }
+        Object.entries(dynamicFilters).forEach(([key, values]) => {
+            if (values.length === 0)
+                return;
+            const gteVal = values.find((v) => v.startsWith('GTE:'));
+            const lteVal = values.find((v) => v.startsWith('LTE:'));
+            if (gteVal || lteVal) {
+                const min = gteVal ? gteVal.replace('GTE:', '') : '';
+                const max = lteVal ? lteVal.replace('LTE:', '') : '';
+                params[`f_${key}`] = `RANGE:${min},${max}`;
+                return;
+            }
+            if (values.length === 1)
+                params[`f_${key}`] = values[0];
+            else
+                params[`f_${key}`] = `IN:${values.join(',')}`;
+        });
+        return params;
+    }, [globalFilter, searchableKeys, defaultFilters, dynamicFilters]);
+    const activeFilterCount = useMemo(() => {
+        let n = Object.values(dynamicFilters).filter((v) => v.length > 0).length;
+        if (globalFilter)
+            n += 1;
+        return n;
+    }, [dynamicFilters, globalFilter]);
+    return {
+        dynamicFilters,
+        globalFilter,
+        setGlobalFilter,
+        columnFilterConfigs,
+        filterParams,
+        handleDynamicFilterChange,
+        activeFilterCount,
+        clearAll,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "20.1.7",
+  "version": "21.0.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",
@@ -38,7 +38,7 @@
     "sonner": ">=1.7",
     "zustand": ">=5",
     "@asteby/metacore-sdk": "^3.2.0",
-    "@asteby/metacore-ui": "^2.6.2"
+    "@asteby/metacore-ui": "^2.7.0"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-router": {
@@ -68,7 +68,7 @@
     "vitest": "^4.0.0",
     "zustand": "^5.0.0",
     "@asteby/metacore-sdk": "3.2.0",
-    "@asteby/metacore-ui": "2.6.2"
+    "@asteby/metacore-ui": "2.7.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/__tests__/dynamic-kanban.test.tsx

@@ -11,7 +11,7 @@
 //      and the destination payload is `{ <group_by>: <dest> }`; an invalid
 //      transition is rejected before any PUT.
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { cleanup, render, screen } from '@testing-library/react'
+import { cleanup, render, screen, fireEvent, waitFor } from '@testing-library/react'
 
 // react-i18next: identity translator returning the defaultValue so card field
 // labels and lane labels surface verbatim. The `t`/`i18n` references are STABLE
@@ -276,3 +276,54 @@ describe('optimistic drag contract', () => {
         // handler returns early — no applyOptimisticMove, no PUT.
     })
 })
+
+// ---------------------------------------------------------------------------
+// 4. Filter bar — the DynamicKanban parity with DynamicTable column filters.
+//    The bar renders a search box + one chip per filterable field, and any
+//    control refetches the board server-side through useDynamicFilters
+//    (debounced), carrying the same `f_<key>` / `search` params.
+// ---------------------------------------------------------------------------
+
+describe('DynamicKanban filter bar', () => {
+    it('renders a search box and a chip for each filterable field', async () => {
+        useMetadataCache.getState().setMetadata('issue', meta())
+        render(
+            <ApiProvider client={fakeApi()}>
+                <DynamicKanban model="issue" />
+            </ApiProvider>,
+        )
+        // search box
+        expect(await screen.findByPlaceholderText('Buscar...')).toBeTruthy()
+        // the only `filterable: true` column is `stage` → a "Stage" filter chip.
+        // (Lane headers use the STAGE labels Backlog/In Progress/… — never "Stage".)
+        expect(screen.getByText('Stage')).toBeTruthy()
+    })
+
+    it('typing in the search box refetches the board with the search param', async () => {
+        useMetadataCache.getState().setMetadata('issue', meta())
+        const get = vi.fn(async (url: string) => {
+            if (url.startsWith('/metadata/table/'))
+                return { data: { success: true, data: meta() } }
+            return { data: { success: true, data: CARDS } }
+        })
+        render(
+            <ApiProvider client={fakeApi({ get })}>
+                <DynamicKanban model="issue" />
+            </ApiProvider>,
+        )
+        const box = await screen.findByPlaceholderText('Buscar...')
+        fireEvent.change(box, { target: { value: 'login' } })
+        await waitFor(() =>
+            expect(get).toHaveBeenCalledWith(
+                '/data/issue',
+                expect.objectContaining({
+                    params: expect.objectContaining({
+                        search: 'login',
+                        // `title` is the only `searchable: true` column in the fixture.
+                        search_columns: 'title',
+                    }),
+                }),
+            ),
+        )
+    })
+})

package/src/dynamic-kanban.tsx

@@ -38,7 +38,7 @@ import {
     type DragStartEvent,
     type DragEndEvent,
 } from '@dnd-kit/core'
-import { MoreHorizontal } from 'lucide-react'
+import { MoreHorizontal, Search, X } from 'lucide-react'
 import { toast } from 'sonner'
 import {
     Badge,
@@ -49,10 +49,13 @@ import {
     DropdownMenuContent,
     DropdownMenuItem,
     DropdownMenuTrigger,
+    Input,
     Skeleton,
 } from '@asteby/metacore-ui/primitives'
+import { ColumnFilterControl, type ColumnFilterType } from '@asteby/metacore-ui/data-table'
 import { generateBadgeStyles, optionColor } from '@asteby/metacore-ui/lib'
 import { useApi } from './api-context'
+import { useDynamicFilters } from './use-dynamic-filters'
 import { useMetadataCache } from './metadata-cache'
 import { ActivityValueRenderer } from './activity-value-renderer'
 import { DynamicIcon } from './dynamic-icon'
@@ -262,6 +265,11 @@ export interface DynamicKanbanProps {
     timeZone?: string
     /** ISO 4217 currency for money card fields (org config). */
     currency?: string
+    /**
+     * Static equality filters always applied to the board (never shown as a
+     * removable chip). Same contract as DynamicTable's `defaultFilters`.
+     */
+    defaultFilters?: Record<string, any>
 }
 
 export function DynamicKanban({
@@ -273,6 +281,7 @@ export function DynamicKanban({
     pageSize = 200,
     timeZone,
     currency,
+    defaultFilters,
 }: DynamicKanbanProps) {
     const { t, i18n } = useTranslation()
     const api = useApi()
@@ -326,13 +335,25 @@ export function DynamicKanban({
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [model])
 
+    // Shared metadata-driven filter engine — the SAME configs, option prefetch
+    // and `f_<key>` serialization DynamicTable uses, so the board filters
+    // identically to its table sibling.
+    const {
+        globalFilter,
+        setGlobalFilter,
+        columnFilterConfigs,
+        filterParams,
+        activeFilterCount,
+        clearAll,
+    } = useDynamicFilters(metadata, { defaultFilters })
+
     // ---- records fetch (same path as DynamicTable, single large page) ----
     const fetchData = useCallback(async () => {
         if (!metadata) return
         setLoadingData(true)
         try {
             const res = (await api.get(endpoint || `/data/${model}`, {
-                params: { page: 1, per_page: pageSize },
+                params: { page: 1, per_page: pageSize, ...filterParams },
             })) as { data: ApiResponse<any[]> }
             if (res.data.success) setRecords(res.data.data || [])
         } catch (err) {
@@ -340,12 +361,37 @@ export function DynamicKanban({
         } finally {
             setLoadingData(false)
         }
-    }, [api, endpoint, model, metadata, pageSize])
+    }, [api, endpoint, model, metadata, pageSize, filterParams])
 
+    // Refetch when metadata resolves, on an explicit refresh, or when the
+    // filters change. `fetchData` is stable while `filterParams` is unchanged
+    // (both memoized), so this only re-runs on real input changes. Debounced so
+    // typing in the search box doesn't fire a request per keystroke.
     useEffect(() => {
-        if (metadata) void fetchData()
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [metadata, refreshTrigger])
+        if (!metadata) return
+        const handle = setTimeout(() => {
+            void fetchData()
+        }, 200)
+        return () => clearTimeout(handle)
+    }, [fetchData, metadata, refreshTrigger])
+
+    // Filterable fields for the toolbar, in metadata order (explicit filters
+    // first, then filterable columns), each labeled from its metadata source.
+    const filterFields = useMemo(() => {
+        if (!metadata) return []
+        const out: {
+            key: string
+            label: string
+            config: NonNullable<ReturnType<typeof columnFilterConfigs.get>>
+        }[] = []
+        for (const [key, config] of columnFilterConfigs) {
+            const f = metadata.filters?.find((x) => x.key === key)
+            const c = metadata.columns.find((x) => x.key === key)
+            const rawLabel = f?.label || c?.label || key
+            out.push({ key, label: t(rawLabel, { defaultValue: rawLabel }), config })
+        }
+        return out
+    }, [metadata, columnFilterConfigs, t])
 
     const stages = useMemo(
         () => (metadata ? deriveStages(metadata) : []),
@@ -503,8 +549,51 @@ export function DynamicKanban({
     }
 
     return (
-        <DndContext sensors={sensors} onDragStart={onDragStart} onDragEnd={onDragEnd}>
-            <div className="flex min-w-0 gap-4 overflow-x-auto p-1" data-testid="kanban-board">
+        <div className="flex flex-col gap-3">
+            {/* Filter bar — global search + one chip per filterable field, the
+                SAME set the DynamicTable exposes in its column headers. Changing
+                any control refetches the board server-side (debounced) via the
+                shared useDynamicFilters engine. */}
+            <div className="flex flex-wrap items-center gap-2" data-testid="kanban-filters">
+                <div className="relative">
+                    <Search className="pointer-events-none absolute left-2.5 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground" />
+                    <Input
+                        value={globalFilter}
+                        onChange={(e) => setGlobalFilter(e.target.value)}
+                        placeholder={t('kanban.searchPlaceholder', { defaultValue: 'Buscar...' })}
+                        className="h-8 w-52 pl-8 text-sm"
+                    />
+                </div>
+                {filterFields.map((field) => (
+                    <ColumnFilterControl
+                        key={field.key}
+                        showLabel
+                        label={field.label}
+                        filterKey={field.config.filterKey}
+                        filterType={field.config.filterType as ColumnFilterType}
+                        filterOptions={field.config.options}
+                        filterLoading={field.config.loading}
+                        filterSearchEndpoint={field.config.searchEndpoint}
+                        selectedValues={field.config.selectedValues}
+                        onFilterChange={field.config.onFilterChange}
+                    />
+                ))}
+                {activeFilterCount > 0 && (
+                    <Button
+                        variant="ghost"
+                        size="sm"
+                        className="h-8 gap-1 text-xs text-muted-foreground"
+                        onClick={clearAll}
+                    >
+                        <X className="h-3.5 w-3.5" />
+                        {t('kanban.clearFilters', { defaultValue: 'Limpiar' })}
+                        {` (${activeFilterCount})`}
+                    </Button>
+                )}
+            </div>
+
+            <DndContext sensors={sensors} onDragStart={onDragStart} onDragEnd={onDragEnd}>
+                <div className="flex min-w-0 gap-4 overflow-x-auto p-1" data-testid="kanban-board">
                 {lanes.map((stage) => {
                     const cards = grouped.get(stage.key) ?? []
                     const droppableAllowed =
@@ -564,7 +653,8 @@ export function DynamicKanban({
             </DragOverlay>
 
             {rowActionDialogs}
-        </DndContext>
+            </DndContext>
+        </div>
     )
 }
 

package/src/index.ts

@@ -23,6 +23,11 @@ export {
     resolveActiveView,
     type DynamicViewProps,
 } from './dynamic-view'
+export {
+    useDynamicFilters,
+    type UseDynamicFiltersOptions,
+    type UseDynamicFiltersResult,
+} from './use-dynamic-filters'
 export * from './dynamic-form'
 export {
     ActionModalDispatcher,

package/src/use-dynamic-filters.ts

@@ -0,0 +1,272 @@
+// useDynamicFilters — the metadata-driven filter engine shared by DynamicTable
+// and DynamicKanban. It owns nothing view-specific: given a model's
+// `TableMetadata`, it derives the per-field filter configs (from
+// `metadata.filters[]` + every `metadata.columns[].filterable` column),
+// prefetches the server-side option lists for relation/select filters, tracks
+// the selected values + global search, and serializes them into the exact
+// `f_<key>=<op>:<value>` / `search` query params the `/data/:model` endpoint
+// already understands.
+//
+// DynamicTable historically inlined this; DynamicKanban now needs the SAME
+// filtering (RFC: a board is just another view of the model), so the logic is
+// factored here to guarantee both surfaces filter identically.
+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 type { ColumnFilterConfig, FilterOption } from './dynamic-columns-shim'
+import type { TableMetadata } from './types'
+
+export interface UseDynamicFiltersOptions {
+  /**
+   * Static equality filters always applied (never shown as removable chips).
+   * Mirrors DynamicTable's `defaultFilters` — e.g. scoping a board to one owner.
+   */
+  defaultFilters?: Record<string, any>
+}
+
+export interface UseDynamicFiltersResult {
+  /** Per-field selected values, `filterKey → values[]` (empty = inactive). */
+  dynamicFilters: Record<string, string[]>
+  /** Free-text search term (the toolbar search box). */
+  globalFilter: string
+  setGlobalFilter: (v: string) => void
+  /** Config for each filterable field, keyed by the metadata filter/column key. */
+  columnFilterConfigs: Map<string, ColumnFilterConfig>
+  /**
+   * The serialized query params (`f_<key>`, `search`, `search_columns`) ready to
+   * spread into a `/data/:model` request. Stable object identity while inputs
+   * are unchanged so a consumer can safely depend on it in a fetch effect.
+   */
+  filterParams: Record<string, any>
+  /** Apply a field's selection (replaces its values). */
+  handleDynamicFilterChange: (filterKey: string, values: string[]) => void
+  /** Count of fields with an active selection + the search term. */
+  activeFilterCount: number
+  /** Clear every field filter and the search term. */
+  clearAll: () => void
+}
+
+/**
+ * Reads the model's filter metadata and returns the live filter state + the
+ * serialized request params. Pure of any view concern — DynamicTable adds its
+ * own sort/pagination/`columnFilters`; DynamicKanban spreads `filterParams`
+ * straight onto its single-page fetch.
+ */
+export function useDynamicFilters(
+  metadata: TableMetadata | null,
+  opts: UseDynamicFiltersOptions = {},
+): UseDynamicFiltersResult {
+  const { defaultFilters } = opts
+  const api = useApi()
+
+  const [dynamicFilters, setDynamicFilters] = useState<Record<string, string[]>>({})
+  const [globalFilter, setGlobalFilter] = useState('')
+  const [filterOptionsMap, setFilterOptionsMap] = useState<
+    Map<string, FilterOption[]>
+  >(new Map())
+
+  // Prefetch the option lists for relation/select filters (once per model). The
+  // combobox needs these before the user opens it; mirrors DynamicTable's
+  // metadata-init option prefetch, narrowed to the FILTER endpoints only (the
+  // kanban renders card cells through ActivityValueRenderer, not the cell
+  // options map, so we skip that half).
+  const prefetchedSig = useRef<string | null>(null)
+  useEffect(() => {
+    if (!metadata) return
+    const filterEndpoints = (metadata.filters || [])
+      .filter(
+        (f) =>
+          f.searchEndpoint &&
+          (f.type === 'select' ||
+            f.type === 'dynamic_select' ||
+            f.type === 'boolean'),
+      )
+      .map((f) => f.searchEndpoint!)
+    const columnFilterEndpoints = (metadata.columns || [])
+      .filter((c) => c.filterable && c.searchEndpoint)
+      .map((c) => c.searchEndpoint!)
+    const endpoints = Array.from(
+      new Set([...filterEndpoints, ...columnFilterEndpoints]),
+    )
+    if (endpoints.length === 0) return
+    // Dedup on the endpoint set, not model identity (TableMetadata carries no
+    // name) — the same board re-rendering shouldn't refetch its options.
+    const sig = endpoints.join('|')
+    if (prefetchedSig.current === sig) return
+    prefetchedSig.current = sig
+
+    let cancelled = false
+    Promise.all(
+      endpoints.map(async (ep) => {
+        try {
+          const res = await api.get(ep)
+          return {
+            endpoint: ep,
+            data: res.data?.success ? res.data.data : [],
+          }
+        } catch (e) {
+          console.error(`Failed to fetch filter options for ${ep}`, e)
+          return { endpoint: ep, data: [] as any[] }
+        }
+      }),
+    ).then((results) => {
+      if (cancelled) return
+      const fMap = new Map<string, FilterOption[]>()
+      for (const r of results) {
+        fMap.set(
+          r.endpoint,
+          (r.data || []).map((item: any) => ({
+            label: item.label || item.name || '',
+            value: String(item.value ?? item.id ?? ''),
+            icon: item.icon,
+            color: item.color || item.class,
+          })),
+        )
+      }
+      setFilterOptionsMap(fMap)
+    })
+    return () => {
+      cancelled = true
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [metadata])
+
+  const handleDynamicFilterChange = useCallback(
+    (filterKey: string, values: string[]) => {
+      setDynamicFilters((prev) => ({ ...prev, [filterKey]: values }))
+    },
+    [],
+  )
+
+  const clearAll = useCallback(() => {
+    setDynamicFilters({})
+    setGlobalFilter('')
+  }, [])
+
+  // Derive one ColumnFilterConfig per filterable field. Explicit
+  // `metadata.filters[]` wins; otherwise every `filterable` column yields a
+  // config with its UI inferred from the column shape. Copied 1:1 from
+  // DynamicTable so table and board build identical configs.
+  const columnFilterConfigs = useMemo(() => {
+    const map = new Map<string, ColumnFilterConfig>()
+    if (!metadata) return map
+    for (const f of metadata.filters ?? []) {
+      const fType = f.type as ColumnFilterConfig['filterType']
+      let options: FilterOption[] = []
+      if (f.options && f.options.length > 0) {
+        options = f.options.map((o) => ({
+          label: o.label,
+          value: String(o.value),
+          icon: o.icon,
+          color: o.color,
+        }))
+      }
+      if (f.searchEndpoint && filterOptionsMap.has(f.searchEndpoint)) {
+        options = filterOptionsMap.get(f.searchEndpoint) || []
+      }
+      if (fType === 'select' && options.length === 0 && !f.searchEndpoint) continue
+      map.set(f.key, {
+        filterType: fType,
+        filterKey: f.column || f.key,
+        options,
+        selectedValues: dynamicFilters[f.column || f.key] || [],
+        onFilterChange: handleDynamicFilterChange,
+        loading: f.searchEndpoint ? !filterOptionsMap.has(f.searchEndpoint) : false,
+        searchEndpoint: f.searchEndpoint,
+      })
+    }
+    for (const c of metadata.columns ?? []) {
+      if (!c.filterable || map.has(c.key)) continue
+      const hasStaticOptions = (c.options?.length ?? 0) > 0
+      const hasEndpoint = !!c.searchEndpoint
+      const isRelation = !!c.ref || c.filterType === 'dynamic_select'
+      let filterType: ColumnFilterConfig['filterType']
+      if (c.filterType) filterType = c.filterType
+      else if (isRelation && hasEndpoint) filterType = 'dynamic_select'
+      else if (hasStaticOptions || hasEndpoint) filterType = 'select'
+      else if (c.type === 'boolean') filterType = 'boolean'
+      else if (c.type === 'number') filterType = 'number_range'
+      else if ((DATE_CELL_TYPES as readonly string[]).includes(c.type))
+        filterType = 'date_range'
+      else filterType = 'text'
+
+      const options = hasStaticOptions
+        ? c.options!.map((o) => ({
+            label: o.label,
+            value: String(o.value),
+            icon: o.icon,
+            color: o.color,
+          }))
+        : hasEndpoint && filterOptionsMap.has(c.searchEndpoint!)
+          ? filterOptionsMap.get(c.searchEndpoint!) || []
+          : []
+      map.set(c.key, {
+        filterType,
+        filterKey: c.key,
+        options,
+        selectedValues: dynamicFilters[c.key] || [],
+        onFilterChange: handleDynamicFilterChange,
+        loading: hasEndpoint && !filterOptionsMap.has(c.searchEndpoint!),
+        searchEndpoint: c.searchEndpoint,
+      })
+    }
+    return map
+  }, [metadata, filterOptionsMap, dynamicFilters, handleDynamicFilterChange])
+
+  const searchableKeys = useMemo(
+    () => (metadata ? getSearchableColumnKeys(metadata) : null),
+    [metadata],
+  )
+
+  // Serialize to `/data/:model` query params — identical operator encoding to
+  // DynamicTable.buildFilterParams (IN:/RANGE:/GTE:/LTE:/ILIKE:/plain).
+  const filterParams = useMemo(() => {
+    const params: Record<string, any> = {}
+    if (globalFilter) {
+      if (searchableKeys === null) {
+        params.search = globalFilter
+      } else if (searchableKeys.length > 0) {
+        params.search = globalFilter
+        params.search_columns = searchableKeys.join(',')
+      }
+      // searchableKeys === [] → no searchable column, skip the search param.
+    }
+    if (defaultFilters) {
+      Object.entries(defaultFilters).forEach(([key, value]) => {
+        params[`f_${key}`] = value
+      })
+    }
+    Object.entries(dynamicFilters).forEach(([key, values]) => {
+      if (values.length === 0) return
+      const gteVal = values.find((v) => v.startsWith('GTE:'))
+      const lteVal = values.find((v) => v.startsWith('LTE:'))
+      if (gteVal || lteVal) {
+        const min = gteVal ? gteVal.replace('GTE:', '') : ''
+        const max = lteVal ? lteVal.replace('LTE:', '') : ''
+        params[`f_${key}`] = `RANGE:${min},${max}`
+        return
+      }
+      if (values.length === 1) params[`f_${key}`] = values[0]
+      else params[`f_${key}`] = `IN:${values.join(',')}`
+    })
+    return params
+  }, [globalFilter, searchableKeys, defaultFilters, dynamicFilters])
+
+  const activeFilterCount = useMemo(() => {
+    let n = Object.values(dynamicFilters).filter((v) => v.length > 0).length
+    if (globalFilter) n += 1
+    return n
+  }, [dynamicFilters, globalFilter])
+
+  return {
+    dynamicFilters,
+    globalFilter,
+    setGlobalFilter,
+    columnFilterConfigs,
+    filterParams,
+    handleDynamicFilterChange,
+    activeFilterCount,
+    clearAll,
+  }
+}