@asteby/metacore-runtime-react 21.1.0 → 22.0.0

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

@@ -6,6 +6,25 @@ export interface UseDynamicFiltersOptions {
      * Mirrors DynamicTable's `defaultFilters` — e.g. scoping a board to one owner.
      */
     defaultFilters?: Record<string, any>;
+    /**
+     * Model key — the fallback base for the per-field `facets` endpoint when no
+     * `endpoint` is given. Omit all of `endpoint`/`model`/`facetsEndpoint` to keep
+     * text filters as bare "Contiene..." boxes.
+     */
+    model?: string;
+    /**
+     * The org-scoped LIST endpoint (e.g. `/data/<model>/me`). The facets base is
+     * derived from it EXACTLY like DynamicTable derives the aggregate endpoint —
+     * `<endpoint>/facets` — so the board and its table sibling hit the same route
+     * (the backend registers both `/data/:model/facets` and
+     * `/data/:model/me/facets`).
+     */
+    endpoint?: string;
+    /**
+     * Explicit `facets` endpoint override — wins over `endpoint`/`model`. The
+     * loader appends `?field=<key>&q=<text>&limit=50`.
+     */
+    facetsEndpoint?: string;
 }
 export interface UseDynamicFiltersResult {
     /** Per-field selected values, `filterKey → values[]` (empty = inactive). */

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

@@ -1 +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"}
+{"version":3,"file":"use-dynamic-filters.d.ts","sourceRoot":"","sources":["../src/use-dynamic-filters.ts"],"names":[],"mappings":"AAiBA,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;IACpC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;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,CAgSzB"}

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 { useFacetLoaders, isLongTextColumn } from './use-facet-loaders';
 /**
  * Reads the model's filter metadata and returns the live filter state + the
  * serialized request params. Pure of any view concern — DynamicTable adds its
@@ -21,11 +22,21 @@ import { getSearchableColumnKeys } from './column-visibility';
  * straight onto its single-page fetch.
  */
 export function useDynamicFilters(metadata, opts = {}) {
-    const { defaultFilters } = opts;
+    const { defaultFilters, model, endpoint, facetsEndpoint } = opts;
     const api = useApi();
     const [dynamicFilters, setDynamicFilters] = useState({});
     const [globalFilter, setGlobalFilter] = useState('');
     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
+    // endpoint), falling back to the model. Null → text filters stay plain.
+    const facetsBase = facetsEndpoint ??
+        (endpoint
+            ? `${endpoint}/facets`
+            : model
+                ? `/data/${model}/facets`
+                : null);
+    const getFacetLoader = useFacetLoaders(facetsBase);
     // 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
@@ -100,8 +111,17 @@ export function useDynamicFilters(metadata, opts = {}) {
         const map = new Map();
         if (!metadata)
             return map;
+        const stages = metadata.stages ?? [];
+        const groupBy = metadata.group_by;
+        // Stage options derived once from the pipeline machine, reused wherever a
+        // stage column has no inline options of its own (A).
+        const stageOptions = stages.map((s) => ({
+            label: s.label,
+            value: s.key,
+            color: s.color,
+        }));
         for (const f of metadata.filters ?? []) {
-            const fType = f.type;
+            let fType = f.type;
             let options = [];
             if (f.options && f.options.length > 0) {
                 options = f.options.map((o) => ({
@@ -114,6 +134,26 @@ export function useDynamicFilters(metadata, opts = {}) {
             if (f.searchEndpoint && filterOptionsMap.has(f.searchEndpoint)) {
                 options = filterOptionsMap.get(f.searchEndpoint) || [];
             }
+            // (A) Stage column with no options of its own → project the pipeline
+            // stages (with their colors) into a real select instead of leaving it as
+            // a text box.
+            if (options.length === 0 &&
+                !f.searchEndpoint &&
+                (f.column || f.key) === groupBy &&
+                stageOptions.length > 0) {
+                fType = 'select';
+                options = stageOptions;
+            }
+            // (B) A plain text filter becomes a facet value-picker when a facets
+            // endpoint is available.
+            let loadOptions;
+            if (fType === 'text' && facetsBase) {
+                const loader = getFacetLoader(f.column || f.key);
+                if (loader) {
+                    fType = 'facet';
+                    loadOptions = loader;
+                }
+            }
             if (fType === 'select' && options.length === 0 && !f.searchEndpoint)
                 continue;
             map.set(f.key, {
@@ -124,6 +164,7 @@ export function useDynamicFilters(metadata, opts = {}) {
                 onFilterChange: handleDynamicFilterChange,
                 loading: f.searchEndpoint ? !filterOptionsMap.has(f.searchEndpoint) : false,
                 searchEndpoint: f.searchEndpoint,
+                loadOptions,
             });
         }
         for (const c of metadata.columns ?? []) {
@@ -132,8 +173,17 @@ export function useDynamicFilters(metadata, opts = {}) {
             const hasStaticOptions = (c.options?.length ?? 0) > 0;
             const hasEndpoint = !!c.searchEndpoint;
             const isRelation = !!c.ref || c.filterType === 'dynamic_select';
+            // (A) A stage column with no options of its own inherits the pipeline's
+            // stages — so "Stage" becomes a colored select, not a text box.
+            const isStageColumn = c.key === groupBy &&
+                !hasStaticOptions &&
+                !hasEndpoint &&
+                !c.filterType &&
+                stageOptions.length > 0;
             let filterType;
-            if (c.filterType)
+            if (isStageColumn)
+                filterType = 'select';
+            else if (c.filterType)
                 filterType = c.filterType;
             else if (isRelation && hasEndpoint)
                 filterType = 'dynamic_select';
@@ -147,7 +197,7 @@ export function useDynamicFilters(metadata, opts = {}) {
                 filterType = 'date_range';
             else
                 filterType = 'text';
-            const options = hasStaticOptions
+            let options = hasStaticOptions
                 ? c.options.map((o) => ({
                     label: o.label,
                     value: String(o.value),
@@ -157,6 +207,18 @@ export function useDynamicFilters(metadata, opts = {}) {
                 : hasEndpoint && filterOptionsMap.has(c.searchEndpoint)
                     ? filterOptionsMap.get(c.searchEndpoint) || []
                     : [];
+            if (isStageColumn)
+                options = stageOptions;
+            // (B) Upgrade a plain text filter to a facet value-picker (unless it's a
+            // long-text/body column — too many unique values to enumerate).
+            let loadOptions;
+            if (filterType === 'text' && facetsBase && !isLongTextColumn(c)) {
+                const loader = getFacetLoader(c.key);
+                if (loader) {
+                    filterType = 'facet';
+                    loadOptions = loader;
+                }
+            }
             map.set(c.key, {
                 filterType,
                 filterKey: c.key,
@@ -165,10 +227,18 @@ export function useDynamicFilters(metadata, opts = {}) {
                 onFilterChange: handleDynamicFilterChange,
                 loading: hasEndpoint && !filterOptionsMap.has(c.searchEndpoint),
                 searchEndpoint: c.searchEndpoint,
+                loadOptions,
             });
         }
         return map;
-    }, [metadata, filterOptionsMap, dynamicFilters, handleDynamicFilterChange]);
+    }, [
+        metadata,
+        filterOptionsMap,
+        dynamicFilters,
+        handleDynamicFilterChange,
+        facetsBase,
+        getFacetLoader,
+    ]);
     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).

package/dist/use-facet-loaders.d.ts

@@ -0,0 +1,22 @@
+import type { FilterOption } from './dynamic-columns-shim';
+/**
+ * Long-text / body columns aren't worth faceting (thousands of unique values,
+ * each a paragraph). Heuristic on the metadata, not a hardcoded name list:
+ * a truncate-text/widget cell or a json/long-text SQL type are the strong
+ * signals; the name pattern is only a last-resort fallback.
+ */
+export declare function isLongTextColumn(c: {
+    key: string;
+    type?: string;
+    cellStyle?: string;
+}): boolean;
+/**
+ * Returns `getFacetLoader(field)` — a stable per-field loader that resolves the
+ * column's distinct values + counts from `<facetsBase>?field=&q=&limit=`. Loader
+ * identity is memoized per field (so it doesn't churn the config memo that
+ * depends on it) and results are cached per `field+query`. Both caches reset
+ * when `facetsBase` changes (model switch). A null `facetsBase` returns a
+ * factory that yields `undefined` — the caller keeps the column as plain text.
+ */
+export declare function useFacetLoaders(facetsBase: string | null): (field: string) => ((q?: string) => Promise<FilterOption[]>) | undefined;
+//# sourceMappingURL=use-facet-loaders.d.ts.map

package/dist/use-facet-loaders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-facet-loaders.d.ts","sourceRoot":"","sources":["../src/use-facet-loaders.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAE1D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE;IAClC,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,OAAO,CAQV;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,WAa7C,MAAM,WAVG,MAAM,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,cAqCtD"}

package/dist/use-facet-loaders.js

@@ -0,0 +1,67 @@
+// useFacetLoaders — the shared machinery that turns a plain text filter into a
+// `facet` value-picker. Both DynamicKanban (via useDynamicFilters) and
+// DynamicTable derive their filter configs independently, so the lazy
+// per-field option loader + result cache lives here to guarantee they facet
+// identically (one board and its table sibling hit the same `/facets` endpoint
+// with the same caching).
+import { useCallback, useEffect, useRef } from 'react';
+import { useApi } from './api-context';
+/**
+ * Long-text / body columns aren't worth faceting (thousands of unique values,
+ * each a paragraph). Heuristic on the metadata, not a hardcoded name list:
+ * a truncate-text/widget cell or a json/long-text SQL type are the strong
+ * signals; the name pattern is only a last-resort fallback.
+ */
+export function isLongTextColumn(c) {
+    if (c.cellStyle === 'truncate-text' || c.cellStyle === 'widget')
+        return true;
+    const t = (c.type || '').toLowerCase();
+    if (t === 'json' || t === 'long_text' || t === 'text_long' || t === 'widget')
+        return true;
+    return /^(body|description|content|notes?|comment|message|summary)$/i.test(c.key);
+}
+/**
+ * Returns `getFacetLoader(field)` — a stable per-field loader that resolves the
+ * column's distinct values + counts from `<facetsBase>?field=&q=&limit=`. Loader
+ * identity is memoized per field (so it doesn't churn the config memo that
+ * depends on it) and results are cached per `field+query`. Both caches reset
+ * when `facetsBase` changes (model switch). A null `facetsBase` returns a
+ * factory that yields `undefined` — the caller keeps the column as plain text.
+ */
+export function useFacetLoaders(facetsBase) {
+    const api = useApi();
+    const loaderCache = useRef(new Map());
+    const resultCache = useRef(new Map());
+    useEffect(() => {
+        loaderCache.current.clear();
+        resultCache.current.clear();
+    }, [facetsBase]);
+    return useCallback((field) => {
+        if (!facetsBase)
+            return undefined;
+        const existing = loaderCache.current.get(field);
+        if (existing)
+            return existing;
+        const loader = async (q) => {
+            const term = q?.trim() || '';
+            const cacheKey = `${field}::${term}`;
+            const cached = resultCache.current.get(cacheKey);
+            if (cached)
+                return cached;
+            const res = await api.get(facetsBase, {
+                params: { field, q: term || undefined, limit: 50 },
+            });
+            const body = res.data;
+            const rows = body?.success ? body.data || [] : [];
+            const opts = rows.map((r) => ({
+                value: String(r.value ?? ''),
+                label: String(r.label ?? r.value ?? ''),
+                count: typeof r.count === 'number' ? r.count : undefined,
+            }));
+            resultCache.current.set(cacheKey, opts);
+            return opts;
+        };
+        loaderCache.current.set(field, loader);
+        return loader;
+    }, [api, facetsBase]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "21.1.0",
+  "version": "22.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.7.0"
+    "@asteby/metacore-ui": "^2.8.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.7.0"
+    "@asteby/metacore-ui": "2.8.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

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

@@ -38,6 +38,8 @@ import {
     isTransitionAllowed,
     applyOptimisticMove,
     selectCardColumns,
+    cardMatchesLaneQuery,
+    summarizeFilterValues,
     UNASSIGNED_LANE,
     DynamicKanban,
 } from '../dynamic-kanban'
@@ -208,6 +210,54 @@ describe('selectCardColumns', () => {
     })
 })
 
+describe('cardMatchesLaneQuery', () => {
+    const cols = [
+        { key: 'title', label: 'Title', type: 'text', sortable: false, filterable: false },
+        { key: 'assignee', label: 'Assignee', type: 'text', sortable: false, filterable: false },
+    ] as any
+
+    it('matches on the title (case-insensitive)', () => {
+        expect(cardMatchesLaneQuery(CARDS[0], cols, 'LOGIN')).toBe(true)
+        expect(cardMatchesLaneQuery(CARDS[0], cols, 'dark')).toBe(false)
+    })
+
+    it('matches on any visible field value, not just the title', () => {
+        // card 1: title "Fix login bug", assignee "ana"
+        expect(cardMatchesLaneQuery(CARDS[0], cols, 'ana')).toBe(true)
+    })
+
+    it('an empty query matches everything', () => {
+        expect(cardMatchesLaneQuery(CARDS[0], cols, '')).toBe(true)
+        expect(cardMatchesLaneQuery(CARDS[0], cols, '   ')).toBe(true)
+    })
+})
+
+describe('summarizeFilterValues', () => {
+    const opts = [
+        { value: 'backlog', label: 'Backlog' },
+        { value: 'done', label: 'Done' },
+        { value: 'review', label: 'Review' },
+    ]
+    it('resolves a single value to its option label', () => {
+        expect(summarizeFilterValues(['done'], opts)).toBe('Done')
+    })
+    it('unwraps IN: and caps at 2 with a +n overflow', () => {
+        expect(summarizeFilterValues(['IN:backlog,done,review'], opts)).toBe(
+            'Backlog, Done +1',
+        )
+    })
+    it('renders a free-text ILIKE: match quoted', () => {
+        expect(summarizeFilterValues(['ILIKE:urgent'], opts)).toBe('"urgent"')
+    })
+    it('renders a numeric GTE/LTE range', () => {
+        expect(summarizeFilterValues(['GTE:10', 'LTE:20'], opts)).toBe('10 – 20')
+    })
+    it('is empty for no selection', () => {
+        expect(summarizeFilterValues([], opts)).toBe('')
+        expect(summarizeFilterValues(undefined, opts)).toBe('')
+    })
+})
+
 // ---------------------------------------------------------------------------
 // 2. Render smoke + 3. optimistic PUT contract
 // ---------------------------------------------------------------------------
@@ -332,3 +382,49 @@ describe('DynamicKanban filter bar', () => {
         )
     })
 })
+
+// ---------------------------------------------------------------------------
+// 5. Per-lane search — the inline lane header search narrows ONLY that lane's
+//    already-fetched cards, client-side, by title + field values.
+// ---------------------------------------------------------------------------
+
+describe('DynamicKanban lane search', () => {
+    it('filters a single lane by card title, leaving the card set narrowed', async () => {
+        useMetadataCache.getState().setMetadata('issue', meta())
+        render(
+            <ApiProvider client={fakeApi()}>
+                <DynamicKanban model="issue" />
+            </ApiProvider>,
+        )
+        // all backlog cards present up front
+        expect(await screen.findByText('Fix login bug')).toBeTruthy()
+        expect(screen.getByText('Dark mode')).toBeTruthy()
+
+        // open the first lane's (backlog) inline search and type
+        const searchButtons = screen.getAllByLabelText('Buscar en la columna')
+        fireEvent.click(searchButtons[0])
+        const input = await screen.findByPlaceholderText('Buscar tarjetas...')
+        fireEvent.change(input, { target: { value: 'dark' } })
+
+        // backlog now shows only "Dark mode"; the other backlog cards are hidden
+        await waitFor(() => expect(screen.queryByText('Fix login bug')).toBeNull())
+        expect(screen.getByText('Dark mode')).toBeTruthy()
+    })
+
+    it('matches on a field value, not only the title', async () => {
+        useMetadataCache.getState().setMetadata('issue', meta())
+        render(
+            <ApiProvider client={fakeApi()}>
+                <DynamicKanban model="issue" />
+            </ApiProvider>,
+        )
+        expect(await screen.findByText('Fix login bug')).toBeTruthy()
+        const searchButtons = screen.getAllByLabelText('Buscar en la columna')
+        fireEvent.click(searchButtons[0])
+        const input = await screen.findByPlaceholderText('Buscar tarjetas...')
+        // card 1 (backlog) has assignee "ana"; card 2/3 do not.
+        fireEvent.change(input, { target: { value: 'ana' } })
+        await waitFor(() => expect(screen.queryByText('Dark mode')).toBeNull())
+        expect(screen.getByText('Fix login bug')).toBeTruthy()
+    })
+})

package/src/__tests__/use-dynamic-filters.test.tsx

@@ -0,0 +1,182 @@
+// @vitest-environment happy-dom
+//
+// useDynamicFilters — the metadata-driven filter engine. Coverage for the
+// "pro filters" upgrades:
+//   A. A stage column with no options of its own inherits the pipeline stages
+//      (colored) as a real `select` instead of falling back to a text box.
+//   B. A plain text filterable column becomes a `facet` value-picker when a
+//      facets endpoint is derivable (model), with a `loadOptions` loader that
+//      hits `/data/<model>/facets`; long-text/body columns and the
+//      no-model case stay a plain `text` filter (the graceful fallback).
+import { describe, expect, it, vi } from 'vitest'
+import { renderHook, waitFor } from '@testing-library/react'
+import * as React from 'react'
+import { useDynamicFilters } from '../use-dynamic-filters'
+import { ApiProvider, type ApiClient } from '../api-context'
+import type { TableMetadata } from '../types'
+
+const STAGES = [
+    { key: 'backlog', label: 'Backlog', color: 'slate', order: 0 },
+    { key: 'in_progress', label: 'In Progress', color: 'blue', order: 1 },
+    { key: 'done', label: 'Done', color: 'green', order: 2 },
+]
+
+function meta(over: Partial<TableMetadata> = {}): TableMetadata {
+    return {
+        title: 'Issues',
+        endpoint: '/data/issue',
+        view_type: 'kanban',
+        group_by: 'stage',
+        stages: STAGES,
+        columns: [
+            { key: 'title', label: 'Title', type: 'text', sortable: true, filterable: true, searchable: true },
+            { key: 'body', label: 'Body', type: 'text', sortable: false, filterable: true, cellStyle: 'truncate-text' },
+            {
+                key: 'stage',
+                label: 'Stage',
+                type: 'status',
+                sortable: false,
+                filterable: true,
+            },
+        ],
+        actions: [],
+        perPageOptions: [50],
+        defaultPerPage: 50,
+        searchPlaceholder: 'Buscar...',
+        enableCRUDActions: true,
+        hasActions: false,
+        ...over,
+    }
+}
+
+function fakeApi(over: Partial<ApiClient> = {}): ApiClient {
+    return {
+        get: vi.fn(async () => ({
+            data: {
+                success: true,
+                data: [
+                    { value: 'ana', label: 'Ana', count: 3 },
+                    { value: 'beto', label: 'Beto', count: 1 },
+                ],
+            },
+        })),
+        post: vi.fn(async () => ({ data: { success: true, data: null } })),
+        put: vi.fn(async () => ({ data: { success: true, data: null } })),
+        delete: vi.fn(async () => ({ data: { success: true, data: null } })),
+        ...over,
+    }
+}
+
+function wrapper(api: ApiClient) {
+    return ({ children }: { children: React.ReactNode }) => (
+        <ApiProvider client={api}>{children}</ApiProvider>
+    )
+}
+
+describe('useDynamicFilters — stage as select (A)', () => {
+    it('projects the pipeline stages (with colors) onto the stage column', () => {
+        const { result } = renderHook(
+            () => useDynamicFilters(meta(), { model: 'issue' }),
+            { wrapper: wrapper(fakeApi()) },
+        )
+        const cfg = result.current.columnFilterConfigs.get('stage')
+        expect(cfg?.filterType).toBe('select')
+        expect(cfg?.options.map((o) => o.value)).toEqual([
+            'backlog',
+            'in_progress',
+            'done',
+        ])
+        expect(cfg?.options.map((o) => o.color)).toEqual(['slate', 'blue', 'green'])
+    })
+
+    it('leaves the stage column as text when there are no stages', () => {
+        const { result } = renderHook(
+            () => useDynamicFilters(meta({ stages: [] }), { model: 'issue' }),
+            { wrapper: wrapper(fakeApi()) },
+        )
+        // No stages and no options → text (upgraded to facet since a model is set).
+        expect(result.current.columnFilterConfigs.get('stage')?.filterType).toBe(
+            'facet',
+        )
+    })
+})
+
+describe('useDynamicFilters — facet upgrade + fallback (B)', () => {
+    it('upgrades a plain text column to a facet with a working loader', async () => {
+        const api = fakeApi()
+        const { result } = renderHook(
+            () => useDynamicFilters(meta(), { model: 'issue' }),
+            { wrapper: wrapper(api) },
+        )
+        const cfg = result.current.columnFilterConfigs.get('title')
+        expect(cfg?.filterType).toBe('facet')
+        expect(typeof cfg?.loadOptions).toBe('function')
+
+        const opts = await cfg!.loadOptions!('an')
+        expect(api.get).toHaveBeenCalledWith(
+            '/data/issue/facets',
+            expect.objectContaining({
+                params: expect.objectContaining({ field: 'title', q: 'an', limit: 50 }),
+            }),
+        )
+        expect(opts).toEqual([
+            { value: 'ana', label: 'Ana', count: 3 },
+            { value: 'beto', label: 'Beto', count: 1 },
+        ])
+    })
+
+    it('derives the facets URL from the list endpoint (like the aggregate endpoint)', async () => {
+        const api = fakeApi()
+        const { result } = renderHook(
+            () =>
+                useDynamicFilters(meta(), {
+                    model: 'issue',
+                    endpoint: '/data/issue/me',
+                }),
+            { wrapper: wrapper(api) },
+        )
+        await result.current.columnFilterConfigs.get('title')!.loadOptions!()
+        expect(api.get).toHaveBeenCalledWith(
+            '/data/issue/me/facets',
+            expect.objectContaining({
+                params: expect.objectContaining({ field: 'title', limit: 50 }),
+            }),
+        )
+    })
+
+    it('keeps long-text/body columns as a plain text filter (no faceting)', () => {
+        const { result } = renderHook(
+            () => useDynamicFilters(meta(), { model: 'issue' }),
+            { wrapper: wrapper(fakeApi()) },
+        )
+        const cfg = result.current.columnFilterConfigs.get('body')
+        expect(cfg?.filterType).toBe('text')
+        expect(cfg?.loadOptions).toBeUndefined()
+    })
+
+    it('falls back to a plain text filter when no facets endpoint is derivable', () => {
+        const { result } = renderHook(() => useDynamicFilters(meta()), {
+            wrapper: wrapper(fakeApi()),
+        })
+        const cfg = result.current.columnFilterConfigs.get('title')
+        expect(cfg?.filterType).toBe('text')
+        expect(cfg?.loadOptions).toBeUndefined()
+    })
+
+    it('caches loader results per field+query (no refetch on reopen)', async () => {
+        const api = fakeApi()
+        const { result } = renderHook(
+            () => useDynamicFilters(meta(), { model: 'issue' }),
+            { wrapper: wrapper(api) },
+        )
+        const load = result.current.columnFilterConfigs.get('title')!.loadOptions!
+        await load('')
+        await load('')
+        // Second call served from cache → only one network hit for that key.
+        await waitFor(() =>
+            expect((api.get as any).mock.calls.filter((c: any[]) =>
+                String(c[0]).endsWith('/facets'),
+            ).length).toBe(1),
+        )
+    })
+})

package/src/dynamic-columns-shim.ts

@@ -11,16 +11,24 @@ export interface FilterOption {
     value: string
     icon?: string
     color?: string
+    /** Occurrence count for `facet` options (rendered muted, right-aligned). */
+    count?: number
 }
 
 export interface ColumnFilterConfig {
-    filterType: 'select' | 'boolean' | 'date_range' | 'number_range' | 'text' | string
+    filterType: 'select' | 'boolean' | 'date_range' | 'number_range' | 'text' | 'facet' | string
     filterKey: string
     options: FilterOption[]
     selectedValues: string[]
     onFilterChange: (filterKey: string, values: string[]) => void
     loading?: boolean
     searchEndpoint?: string
+    /**
+     * Lazy option loader for `facet` filters — resolves the column's distinct
+     * values + counts from the `/facets` endpoint. Passed straight through to
+     * `ColumnFilterControl.loadOptions`.
+     */
+    loadOptions?: (q?: string) => Promise<FilterOption[]>
 }
 
 /** Signature for the host-provided `getDynamicColumns` factory. */

package/src/dynamic-columns.tsx

@@ -757,6 +757,7 @@ export function makeDefaultGetDynamicColumns(
                     filterSearchEndpoint: filterConfig.searchEndpoint,
                     selectedValues: filterConfig.selectedValues,
                     onFilterChange: filterConfig.onFilterChange,
+                    loadOptions: filterConfig.loadOptions,
                 }
                 Object.assign(columnMeta, fm)
             }