@asteby/metacore-runtime-react 13.10.2 → 15.0.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @asteby/metacore-runtime-react
 
+## 15.0.0
+
+### Minor Changes
+
+- ab41d75: Make declarative dynamic-table option badges and relation chips feel alive.
+
+  Options/select/status badges that ship without an explicit `color` from the
+  backend now get a deterministic, cohesive color derived from the option value
+  (fallback label) instead of rendering as dead gray text. Same value always maps
+  to the same hue, and equal words share a color.
+  - `@asteby/metacore-ui/lib` adds `optionColor(key)` (curated 16-hue Tailwind-500
+    palette, FNV-1a hash, light/dark safe), plus `optionColorBadgeStyles`,
+    `relationChipStyles`, and the exported `OPTION_PALETTE`.
+  - `OptionBadge` uses the explicit `color` when present, otherwise derives one via
+    `optionColor`, and renders the option's lucide `icon` before the label.
+  - `RelationCell` (resolved FK chips for category/brand/supplier/…) now gets a
+    subtle deterministic color keyed on the related label — kept lighter than enum
+    badges (soft tint, no heavy fill) so the two remain distinguishable.
+
+  All colors come from hex-derived inline styles, so they render correctly
+  regardless of the host's tailwind safelist.
+
+### Patch Changes
+
+- Updated dependencies [ab41d75]
+  - @asteby/metacore-ui@2.3.0
+
+## 14.0.0
+
+### Minor Changes
+
+- 6299af7: Pro dynamic-table cells + relation/option multi-select filters
+
+  `DynamicTable` now renders resolved FK relations and option/type columns, and
+  filters them server-side — generically, for every declarative addon.
+
+  **Cells (`dynamic-columns.tsx`)**
+  - `relation` renderer: a column carrying a `ref` (belongs_to FK) or
+    `cellStyle: 'relation'` renders the backend-resolved sibling
+    `row[<key without _id>] = { value, label }` as a clean truncated chip
+    (e.g. `category_id` → `row.category.label`). Falls back to the raw id, then
+    to an empty marker. Mirrors how `created_by` ships as a `{ name, avatar }`
+    sibling for the `creator` renderer.
+  - option/type badge: a `select`-style column shipping inline localized
+    `options: [{ value, label, color, icon }]` renders the matched option's label
+    as a colored `OptionBadge` (e.g. `product_type: "storable"` → the
+    "Almacenable" badge), reusing the same badge path as `badge`/`status`.
+
+  **Filters (`dynamic-table.tsx` + `FilterableColumnHeader`)**
+  - New `dynamic_select` filter type: a `filterable` `ref` column loads its
+    options from `searchEndpoint = /options/<ref>` (prefetched + cached into
+    `filterOptionsMap`) and renders the same multi-value checkbox combobox as
+    `select`. The backend's explicit `column.filterType` wins; otherwise it is
+    inferred from the column shape.
+  - `select` and `dynamic_select` filters support MULTIPLE selected values
+    (already Set-based in the header; the gate/active-count/loading states were
+    generalized to cover `dynamic_select`).
+
+### Patch Changes
+
+- Updated dependencies [6299af7]
+  - @asteby/metacore-ui@2.2.0
+
 ## 13.10.2
 
 ### Patch Changes

package/dist/dynamic-columns.d.ts

@@ -1,3 +1,4 @@
+import type { ColumnDefinition } from './types';
 import type { GetDynamicColumns } from './dynamic-columns-shim';
 /** Host-supplied helpers consumed by avatar/image cell renderers. */
 export interface DynamicColumnsHelpers {
@@ -27,6 +28,24 @@ export interface DynamicColumnsHelpers {
  *   - row with no `status` field                      → all actions shown.
  */
 export declare const isActionAllowedForRowState: (action: any, row: any) => boolean;
+/**
+ * Resolves the relation sibling object a backend serves alongside an FK column.
+ * For a column keyed `category_id` the data row also carries
+ * `row.category = { value, label }` (the FK key with the trailing `_id`
+ * stripped) — mirroring how `created_by` ships as a `{ name, avatar, email }`
+ * sibling consumed by the `creator` renderer. Returns the relation key so the
+ * cell can read `row[relationKeyFor(col)]`.
+ */
+export declare const relationKeyFor: (col: Pick<ColumnDefinition, "key">) => string;
+/**
+ * Reads the resolved relation/option label a backend serves for an FK or
+ * option column, falling back to the raw value. Pure so the cell renderers and
+ * tests share one resolution path:
+ *   - relation: prefer the sibling `{ value, label }` object's label.
+ *   - option:   prefer the matched `options[].label` (value compared as string).
+ *   - else:     the raw value coerced to string ('' when nullish).
+ */
+export declare const resolveRelationLabel: (col: ColumnDefinition, row: any) => string;
 /**
  * Builds the canonical column factory used by `<DynamicTable>` when the host
  * does not supply its own. Pass `{ getImageUrl, apiBaseUrl }` to wire avatar

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

@@ -1 +1 @@
-{"version":3,"file":"dynamic-columns.d.ts","sourceRoot":"","sources":["../src/dynamic-columns.tsx"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAER,iBAAiB,EACpB,MAAM,wBAAwB,CAAA;AAE/B,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAgGD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,GAAI,QAAQ,GAAG,EAAE,KAAK,GAAG,KAAG,OAMlE,CAAA;AAuJD;;;;GAIG;AACH,wBAAgB,4BAA4B,CACxC,OAAO,GAAE,qBAA0B,GACpC,iBAAiB,CAokBnB;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBACL,CAAA"}
+{"version":3,"file":"dynamic-columns.d.ts","sourceRoot":"","sources":["../src/dynamic-columns.tsx"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EAAiB,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE9D,OAAO,KAAK,EAER,iBAAiB,EACpB,MAAM,wBAAwB,CAAA;AAE/B,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAgGD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,GAAI,QAAQ,GAAG,EAAE,KAAK,GAAG,KAAG,OAMlE,CAAA;AAwHD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,KAAG,MAGnE,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,gBAAgB,EAAE,KAAK,GAAG,KAAG,MAStE,CAAA;AAiED;;;;GAIG;AACH,wBAAgB,4BAA4B,CACxC,OAAO,GAAE,qBAA0B,GACpC,iBAAiB,CAgmBnB;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBACL,CAAA"}

package/dist/dynamic-columns.js

@@ -4,8 +4,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // badge (static + endpoint-loaded options), avatar/search, creator/user,
 // phone, date, boolean, relation-badge-list, media-gallery, image, plus the
 // declarative pro renderers url/link, email, currency, number, percent/
-// progress, status, tags, color, code/truncate-text, and a generic text
-// fallback. The renderer resolves `cellStyle ?? type` for each column.
+// progress, status, tags, color, code/truncate-text, relation (resolved FK
+// chip), option/select badges, and a generic text fallback. The renderer
+// resolves `cellStyle ?? type` for each column.
 //
 // The implementation was previously duplicated across multiple host apps
 // (~550 LOC each, drifting). It now lives here so a single fix propagates
@@ -18,7 +19,7 @@ import * as icons from 'lucide-react';
 import { MoreHorizontal } from 'lucide-react';
 import { Avatar, AvatarFallback, AvatarImage, Badge, Button, Checkbox, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, } from '@asteby/metacore-ui';
 import { DataTableColumnHeader, FilterableColumnHeader, } from '@asteby/metacore-ui/data-table';
-import { generateBadgeStyles, getInitials } from '@asteby/metacore-ui/lib';
+import { generateBadgeStyles, getInitials, optionColor, relationChipStyles, } from '@asteby/metacore-ui/lib';
 import { Progress } from './dialogs/_primitives';
 import { OptionsContext } from './options-context';
 import { DynamicIcon } from './dynamic-icon';
@@ -168,7 +169,12 @@ const renderRelationBadges = (items, col) => {
 };
 const OptionBadge = ({ option }) => {
     const isDark = useIsDarkTheme();
-    const colorStyles = option.color ? generateBadgeStyles(option.color, { isDark }) : {};
+    // Explicit backend color wins; otherwise derive a stable, cohesive color
+    // from the option's value (fallback label) so "dead" gray badges come
+    // alive. Inline style (hex-derived) so it works regardless of the host's
+    // tailwind safelist — addon-arbitrary classes aren't in the host scan.
+    const colorSource = option.color || optionColor(option.value || option.label);
+    const colorStyles = generateBadgeStyles(colorSource, { isDark });
     return (_jsxs(Badge, { variant: "outline", className: "flex items-center gap-1 border-0", style: colorStyles, children: [option.icon && _jsx(DynamicIcon, { name: option.icon, className: "h-3.5 w-3.5" }), _jsx("span", { children: option.label })] }));
 };
 const BadgeWithEndpointOptions = ({ endpoint, value }) => {
@@ -179,6 +185,55 @@ const BadgeWithEndpointOptions = ({ endpoint, value }) => {
         return _jsx(OptionBadge, { option: option, fallback: String(value) });
     return _jsx(Badge, { variant: "outline", children: String(value) });
 };
+/**
+ * Resolves the relation sibling object a backend serves alongside an FK column.
+ * For a column keyed `category_id` the data row also carries
+ * `row.category = { value, label }` (the FK key with the trailing `_id`
+ * stripped) — mirroring how `created_by` ships as a `{ name, avatar, email }`
+ * sibling consumed by the `creator` renderer. Returns the relation key so the
+ * cell can read `row[relationKeyFor(col)]`.
+ */
+export const relationKeyFor = (col) => {
+    const k = col.key;
+    return k.endsWith('_id') ? k.slice(0, -3) : k;
+};
+/**
+ * Reads the resolved relation/option label a backend serves for an FK or
+ * option column, falling back to the raw value. Pure so the cell renderers and
+ * tests share one resolution path:
+ *   - relation: prefer the sibling `{ value, label }` object's label.
+ *   - option:   prefer the matched `options[].label` (value compared as string).
+ *   - else:     the raw value coerced to string ('' when nullish).
+ */
+export const resolveRelationLabel = (col, row) => {
+    const sibling = getNestedValue(row, relationKeyFor(col));
+    const label = sibling && typeof sibling === 'object'
+        ? sibling.label ?? sibling.name
+        : undefined;
+    if (label !== undefined && label !== null && label !== '')
+        return String(label);
+    const raw = getNestedValue(row, col.key);
+    return raw !== undefined && raw !== null ? String(raw) : '';
+};
+/**
+ * Renders a resolved FK relation as a clean, truncated chip. Reads the
+ * backend-resolved sibling `{ value, label }` (see `relationKeyFor`) and shows
+ * its `label`. Falls back to the raw id when no sibling was resolved, and to an
+ * empty marker when there is no value at all. Domain-agnostic: works for every
+ * `belongs_to` column (category, supplier, warehouse, …) without per-addon code.
+ */
+const RelationCell = ({ col, row }) => {
+    const isDark = useIsDarkTheme();
+    const display = resolveRelationLabel(col, row);
+    if (!display)
+        return _jsx(EmptyCell, {});
+    // Deterministic, SUBTLE color keyed on the resolved label — lighter than
+    // enum badges (soft tint, no heavy fill) so category/brand chips read as
+    // alive yet stay visually distinct from option/status badges. Inline style
+    // (hex-derived) bypasses the host tailwind safelist.
+    const chipStyles = relationChipStyles(display, { isDark });
+    return (_jsx("span", { className: "inline-flex max-w-[220px] items-center truncate rounded-md px-2 py-0.5 text-sm font-medium", style: chipStyles, title: display, children: _jsx("span", { className: "truncate", children: display }) }));
+};
 /**
  * Generic avatar-style cell: round/rounded photo (or initials fallback) +
  * primary name + optional subtitle. Backs the `avatar`/`search` columns as
@@ -277,6 +332,30 @@ export function makeDefaultGetDynamicColumns(helpers = {}) {
                         const styles = generateBadgeStyles(statusColorFor(sv), { isDark });
                         return (_jsx(Badge, { variant: "outline", className: "border-0 capitalize", style: styles, children: sv }));
                     }
+                    // Resolved FK relation chip. Triggers on an explicit
+                    // `cellStyle: 'relation'` or on any column carrying a `ref`
+                    // (a belongs_to FK) that isn't being rendered as an
+                    // option/badge. Reads the backend-resolved
+                    // `row[<key w/o _id>] = { value, label }` sibling.
+                    if (renderAs === 'relation' ||
+                        (col.ref && !col.options?.length && renderAs !== 'badge' && renderAs !== 'status')) {
+                        return _jsx(RelationCell, { col: col, row: row.original });
+                    }
+                    // Option/type column: a `select`-style column ships its
+                    // localized `options: [{value,label,color,icon}]` inline and
+                    // the cell value is the raw option value (e.g. "storable").
+                    // Render the matched option's label as a colored badge —
+                    // same OptionBadge the `badge`/`status` cells use.
+                    if ((renderAs === 'select' || renderAs === 'option' || col.type === 'select') &&
+                        col.options &&
+                        col.options.length > 0) {
+                        if (!value && value !== 0)
+                            return _jsx(EmptyCell, {});
+                        const option = col.options.find((o) => o.value === String(value));
+                        if (option)
+                            return _jsx(OptionBadge, { option: option, fallback: String(value) });
+                        return _jsx(Badge, { variant: "outline", children: String(value) });
+                    }
                     switch (renderAs) {
                         case 'date': {
                             if (!value)

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

@@ -1 +1 @@
-{"version":3,"file":"dynamic-table.d.ts","sourceRoot":"","sources":["../src/dynamic-table.tsx"],"names":[],"mappings":"AAiBA,OAAO,EAKH,KAAK,SAAS,EAajB,MAAM,uBAAuB,CAAA;AA+B9B,OAAO,KAAK,EAAsB,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAUnF,UAAU,iBAAiB;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAAA;IAC7C,cAAc,CAAC,EAAE,GAAG,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACpC,YAAY,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAA;IAC/B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;CACxC;AAED,wBAAgB,YAAY,CAAC,EACzB,KAAK,EACL,QAAQ,EACR,aAAoB,EACpB,aAAkB,EAClB,QAAQ,EACR,cAAc,EACd,cAAc,EACd,YAAiB,EACjB,iBAA4C,GAC/C,EAAE,iBAAiB,2CAixBnB"}
+{"version":3,"file":"dynamic-table.d.ts","sourceRoot":"","sources":["../src/dynamic-table.tsx"],"names":[],"mappings":"AAiBA,OAAO,EAKH,KAAK,SAAS,EAajB,MAAM,uBAAuB,CAAA;AA+B9B,OAAO,KAAK,EAAsB,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAUnF,UAAU,iBAAiB;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAAA;IAC7C,cAAc,CAAC,EAAE,GAAG,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACpC,YAAY,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAA;IAC/B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;CACxC;AAED,wBAAgB,YAAY,CAAC,EACzB,KAAK,EACL,QAAQ,EACR,aAAoB,EACpB,aAAkB,EAClB,QAAQ,EACR,cAAc,EACd,cAAc,EACd,YAAiB,EACjB,iBAA4C,GAC/C,EAAE,iBAAiB,2CA+xBnB"}

package/dist/dynamic-table.js

@@ -229,8 +229,15 @@ export function DynamicTable({ model, endpoint, enableUrlSync = true, hiddenColu
             if (!meta)
                 return;
             const columnEndpoints = meta.columns.filter(c => c.useOptions && c.searchEndpoint).map(c => c.searchEndpoint);
-            const filterEndpoints = (meta.filters || []).filter(f => f.searchEndpoint && (f.type === 'select' || f.type === 'boolean')).map(f => f.searchEndpoint);
-            const allEndpoints = [...columnEndpoints, ...filterEndpoints];
+            const filterEndpoints = (meta.filters || []).filter(f => f.searchEndpoint && (f.type === 'select' || f.type === 'dynamic_select' || f.type === 'boolean')).map(f => f.searchEndpoint);
+            // Relation (`ref`/`dynamic_select`) columns flagged `filterable`
+            // also need their options preloaded so the per-column multi-select
+            // combobox has something to show. Mirrors the explicit-filter path
+            // above for columns that drive their filter off the column def.
+            const columnFilterEndpoints = meta.columns
+                .filter(c => c.filterable && c.searchEndpoint)
+                .map(c => c.searchEndpoint);
+            const allEndpoints = [...columnEndpoints, ...filterEndpoints, ...columnFilterEndpoints];
             if (allEndpoints.length > 0) {
                 prefetchOptions(allEndpoints).then(fetchedMap => {
                     const colMap = new Map();
@@ -238,16 +245,18 @@ export function DynamicTable({ model, endpoint, enableUrlSync = true, hiddenColu
                         colMap.set(ep, fetchedMap.get(ep)); });
                     setOptionsMap(colMap);
                     const fMap = new Map();
-                    filterEndpoints.forEach(ep => {
-                        if (fetchedMap.has(ep)) {
-                            fMap.set(ep, (fetchedMap.get(ep) || []).map((item) => ({
-                                label: item.label || item.name || '',
-                                value: String(item.value ?? item.id ?? ''),
-                                icon: item.icon,
-                                color: item.color || item.class,
-                            })));
-                        }
-                    });
+                    const projectFilterOptions = (ep) => {
+                        if (!fetchedMap.has(ep) || fMap.has(ep))
+                            return;
+                        fMap.set(ep, (fetchedMap.get(ep) || []).map((item) => ({
+                            label: item.label || item.name || '',
+                            value: String(item.value ?? item.id ?? ''),
+                            icon: item.icon,
+                            color: item.color || item.class,
+                        })));
+                    };
+                    filterEndpoints.forEach(projectFilterOptions);
+                    columnFilterEndpoints.forEach(projectFilterOptions);
                     setFilterOptionsMap(fMap);
                 });
             }
@@ -490,14 +499,22 @@ export function DynamicTable({ model, endpoint, enableUrlSync = true, hiddenColu
                 continue;
             const hasStaticOptions = (c.options?.length ?? 0) > 0;
             const hasEndpoint = !!c.searchEndpoint;
-            // Pick the filter UI from column type:
-            //   - explicit options or searchEndpoint → multi-select dropdown
+            const isRelation = !!c.ref || c.filterType === 'dynamic_select';
+            // Pick the filter UI. The backend's explicit `filterType` wins; when
+            // absent we infer it from the column shape:
+            //   - ref/dynamic_select column        → relation multi-select
+            //     (options stream from searchEndpoint = /options/<ref>)
+            //   - inline options or searchEndpoint  → static multi-select
             //   - boolean → boolean toggle (renders as select under the hood)
             //   - number / number_range / numeric → number range
             //   - date → date range picker (start/end calendar)
             //   - everything else (text, email, phone, tags…) → text contains
-            let filterType = 'select';
-            if (hasStaticOptions || hasEndpoint)
+            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';

package/dist/index.d.ts

@@ -16,7 +16,7 @@ export { ADDON_MANIFEST_CHANGED_TYPE, wireHotSwapInvalidation, useManifestHotSwa
 export { useHotSwapReload, applyHotSwapReload, withVersionParam, clearFederationContainer, shortenHash, type HotSwapReloadStrategy, type HotSwapReloadConfig, type HotSwapReloadAction, type HotSwapReloadDeps, type UseHotSwapReloadResult, } from './hotswap-reload-policy';
 export * from './dynamic-icon';
 export type { ColumnFilterConfig, FilterOption as DynamicColumnFilterOption, GetDynamicColumns, DynamicIconComponent, } from './dynamic-columns-shim';
-export { defaultGetDynamicColumns, makeDefaultGetDynamicColumns, type DynamicColumnsHelpers, } from './dynamic-columns';
+export { defaultGetDynamicColumns, makeDefaultGetDynamicColumns, relationKeyFor, resolveRelationLabel, type DynamicColumnsHelpers, } from './dynamic-columns';
 export { DynamicRecordDialog } from './dialogs/dynamic-record';
 export { CreateRecordDialog } from './dialogs/create-record-dialog';
 export { ViewRecordDialog } from './dialogs/view-record-dialog';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -20,7 +20,7 @@ export * from './metadata-cache';
 export { ADDON_MANIFEST_CHANGED_TYPE, wireHotSwapInvalidation, useManifestHotSwapSubscriber, } from './manifest-hotswap-subscriber';
 export { useHotSwapReload, applyHotSwapReload, withVersionParam, clearFederationContainer, shortenHash, } from './hotswap-reload-policy';
 export * from './dynamic-icon';
-export { defaultGetDynamicColumns, makeDefaultGetDynamicColumns, } from './dynamic-columns';
+export { defaultGetDynamicColumns, makeDefaultGetDynamicColumns, relationKeyFor, resolveRelationLabel, } from './dynamic-columns';
 export { DynamicRecordDialog } from './dialogs/dynamic-record';
 export { CreateRecordDialog } from './dialogs/create-record-dialog';
 export { ViewRecordDialog } from './dialogs/view-record-dialog';

package/dist/types.d.ts

@@ -51,7 +51,13 @@ export interface RelationMeta {
 export interface FilterDefinition {
     key: string;
     label: string;
-    type: 'select' | 'boolean' | 'date_range' | 'number_range' | 'text';
+    /**
+     * `dynamic_select` resolves its options server-side from a relation
+     * (`searchEndpoint = /options/<ref>`) and renders the same multi-value
+     * combobox as `select`. The host loads + caches the options before they
+     * surface in the dropdown.
+     */
+    type: 'select' | 'dynamic_select' | 'boolean' | 'date_range' | 'number_range' | 'text';
     column: string;
     options?: {
         value: string | boolean;
@@ -75,9 +81,17 @@ export type ColumnVisibility = 'all' | 'table' | 'modal' | 'list' | (string & {}
 export interface ColumnDefinition {
     key: string;
     label: string;
-    type: 'text' | 'number' | 'date' | 'select' | 'search' | 'relation-badge-list' | 'avatar' | 'boolean' | 'phone' | 'media-gallery' | 'image' | 'url' | 'link' | 'email' | 'currency' | 'percent' | 'progress' | 'badge' | 'status' | 'tags' | 'color' | 'code' | 'truncate-text' | 'creator' | 'user';
+    type: 'text' | 'number' | 'date' | 'select' | 'search' | 'relation-badge-list' | 'avatar' | 'boolean' | 'phone' | 'media-gallery' | 'image' | 'url' | 'link' | 'email' | 'currency' | 'percent' | 'progress' | 'badge' | 'status' | 'tags' | 'color' | 'code' | 'truncate-text' | 'creator' | 'user' | 'relation';
     sortable: boolean;
     filterable: boolean;
+    /**
+     * Explicit filter UI the backend wants for this column when `filterable`.
+     * When absent the SDK infers it from the column shape (options/endpoint →
+     * `select`, boolean/number/date → their range pickers, else `text`). A
+     * `ref` (belongs_to FK) column is served as `dynamic_select` so its options
+     * stream from `searchEndpoint = /options/<ref>` into a multi-value combobox.
+     */
+    filterType?: 'select' | 'dynamic_select' | 'boolean' | 'date_range' | 'number_range' | 'text';
     hidden?: boolean;
     /**
      * Scopes where this column is rendered. When `'modal'` (or `'list'`) the

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "13.10.2",
+  "version": "15.0.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "date-fns": ">=3",
     "react-day-picker": ">=8",
     "@asteby/metacore-sdk": "^3.1.0",
-    "@asteby/metacore-ui": "^2.1.2"
+    "@asteby/metacore-ui": "^2.3.0"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-router": {
@@ -61,8 +61,8 @@
     "typescript": "^6.0.0",
     "vitest": "^4.0.0",
     "zustand": "^5.0.0",
-    "@asteby/metacore-ui": "2.1.2",
-    "@asteby/metacore-sdk": "3.1.0"
+    "@asteby/metacore-sdk": "3.1.0",
+    "@asteby/metacore-ui": "2.3.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/__tests__/option-color.test.ts

@@ -0,0 +1,61 @@
+// Determinism + spread coverage for the curated option-color palette that
+// makes option/relation badges "alive" instead of dead gray. These utilities
+// live in @asteby/metacore-ui/lib and are consumed by the OptionBadge and
+// RelationCell renderers in dynamic-columns.tsx.
+import { describe, it, expect } from 'vitest'
+import { optionColor, OPTION_PALETTE } from '@asteby/metacore-ui/lib'
+
+describe('optionColor', () => {
+    it('is deterministic — same input always yields the same color', () => {
+        const a = optionColor('storable')
+        const b = optionColor('storable')
+        expect(a).toBe(b)
+        // Stable across many repeats (no Math.random / time dependence).
+        for (let i = 0; i < 50; i++) {
+            expect(optionColor('in_progress')).toBe(optionColor('in_progress'))
+        }
+    })
+
+    it('normalizes case/whitespace so equal words collapse to one color', () => {
+        expect(optionColor('Active')).toBe(optionColor('active'))
+        expect(optionColor('  active  ')).toBe(optionColor('active'))
+    })
+
+    it('always returns a color from the curated palette', () => {
+        const keys = [
+            'storable', 'consumable', 'service', 'active', 'inactive', 'pending',
+            'frenos', 'llantas', 'suspension', 'aceite', 'filtros', 'baterias',
+            'uuid-1234', 'category', 'brand', 'supplier', 'warehouse', '',
+        ]
+        for (const key of keys) {
+            expect(OPTION_PALETTE).toContain(optionColor(key))
+        }
+    })
+
+    it('returns a 6-digit hex with no leading #', () => {
+        expect(optionColor('anything')).toMatch(/^[0-9a-f]{6}$/)
+    })
+
+    it('falls back to a stable palette color for empty/nullish input', () => {
+        expect(optionColor('')).toBe(OPTION_PALETTE[0])
+        // @ts-expect-error exercising the nullish guard
+        expect(optionColor(undefined)).toBe(OPTION_PALETTE[0])
+    })
+
+    it('spreads distinct inputs across the palette (not one color for all)', () => {
+        const inputs = Array.from({ length: 200 }, (_, i) => `option_${i}`)
+        const used = new Set(inputs.map(optionColor))
+        // With 16 hues and 200 distinct keys we expect broad coverage; require
+        // at least half the palette to be exercised so a degenerate hash that
+        // collapses everything is caught.
+        expect(used.size).toBeGreaterThanOrEqual(OPTION_PALETTE.length / 2)
+    })
+
+    it('different similar inputs do not all collide to one hue', () => {
+        const c1 = optionColor('red')
+        const c2 = optionColor('blue')
+        const c3 = optionColor('green')
+        const distinct = new Set([c1, c2, c3])
+        expect(distinct.size).toBeGreaterThan(1)
+    })
+})

package/src/__tests__/relation-option-cells.test.ts

@@ -0,0 +1,53 @@
+// Pure-logic coverage for the relation/option cell resolution path used by
+// `defaultGetDynamicColumns`. The renderers themselves are JSX (covered in the
+// host's render tests); here we lock the value-resolution contract that drives
+// them so a backend shape change is caught without a DOM.
+import { describe, it, expect } from 'vitest'
+import { relationKeyFor, resolveRelationLabel } from '../dynamic-columns'
+import type { ColumnDefinition } from '../types'
+
+const col = (over: Partial<ColumnDefinition>): ColumnDefinition => ({
+    key: 'category_id',
+    label: 'Categoría',
+    type: 'text',
+    sortable: true,
+    filterable: true,
+    ...over,
+})
+
+describe('relationKeyFor', () => {
+    it('strips the trailing _id (FK key → relation sibling key)', () => {
+        expect(relationKeyFor({ key: 'category_id' })).toBe('category')
+        expect(relationKeyFor({ key: 'supplier_id' })).toBe('supplier')
+    })
+
+    it('leaves keys without _id untouched', () => {
+        expect(relationKeyFor({ key: 'category' })).toBe('category')
+        expect(relationKeyFor({ key: 'parent_uid' })).toBe('parent_uid')
+    })
+})
+
+describe('resolveRelationLabel', () => {
+    it('prefers the backend-resolved sibling label', () => {
+        const row = {
+            category_id: 'uuid-1',
+            category: { value: 'uuid-1', label: 'Llantas' },
+        }
+        expect(resolveRelationLabel(col({ ref: 'categories' }), row)).toBe('Llantas')
+    })
+
+    it('accepts a sibling that uses { name } instead of { label }', () => {
+        const row = { category_id: 'uuid-2', category: { value: 'uuid-2', name: 'Frenos' } }
+        expect(resolveRelationLabel(col({ ref: 'categories' }), row)).toBe('Frenos')
+    })
+
+    it('falls back to the raw id when no sibling was resolved', () => {
+        const row = { category_id: 'uuid-3' }
+        expect(resolveRelationLabel(col({ ref: 'categories' }), row)).toBe('uuid-3')
+    })
+
+    it('returns empty string when there is no value at all', () => {
+        expect(resolveRelationLabel(col({ ref: 'categories' }), {})).toBe('')
+        expect(resolveRelationLabel(col({ ref: 'categories' }), { category_id: null })).toBe('')
+    })
+})

package/src/dynamic-columns.tsx

@@ -3,8 +3,9 @@
 // badge (static + endpoint-loaded options), avatar/search, creator/user,
 // phone, date, boolean, relation-badge-list, media-gallery, image, plus the
 // declarative pro renderers url/link, email, currency, number, percent/
-// progress, status, tags, color, code/truncate-text, and a generic text
-// fallback. The renderer resolves `cellStyle ?? type` for each column.
+// progress, status, tags, color, code/truncate-text, relation (resolved FK
+// chip), option/select badges, and a generic text fallback. The renderer
+// resolves `cellStyle ?? type` for each column.
 //
 // The implementation was previously duplicated across multiple host apps
 // (~550 LOC each, drifting). It now lives here so a single fix propagates
@@ -34,7 +35,12 @@ import {
     FilterableColumnHeader,
     type ColumnFilterMeta,
 } from '@asteby/metacore-ui/data-table'
-import { generateBadgeStyles, getInitials } from '@asteby/metacore-ui/lib'
+import {
+    generateBadgeStyles,
+    getInitials,
+    optionColor,
+    relationChipStyles,
+} from '@asteby/metacore-ui/lib'
 import { Progress } from './dialogs/_primitives'
 import { OptionsContext } from './options-context'
 import { DynamicIcon } from './dynamic-icon'
@@ -271,7 +277,12 @@ interface OptionBadgeProps {
 
 const OptionBadge: React.FC<OptionBadgeProps> = ({ option }) => {
     const isDark = useIsDarkTheme()
-    const colorStyles = option.color ? generateBadgeStyles(option.color, { isDark }) : {}
+    // Explicit backend color wins; otherwise derive a stable, cohesive color
+    // from the option's value (fallback label) so "dead" gray badges come
+    // alive. Inline style (hex-derived) so it works regardless of the host's
+    // tailwind safelist — addon-arbitrary classes aren't in the host scan.
+    const colorSource = option.color || optionColor(option.value || option.label)
+    const colorStyles = generateBadgeStyles(colorSource, { isDark })
     return (
         <Badge variant="outline" className="flex items-center gap-1 border-0" style={colorStyles}>
             {option.icon && <DynamicIcon name={option.icon} className="h-3.5 w-3.5" />}
@@ -288,6 +299,65 @@ const BadgeWithEndpointOptions: React.FC<{ endpoint: string; value: any }> = ({
     return <Badge variant="outline">{String(value)}</Badge>
 }
 
+/**
+ * Resolves the relation sibling object a backend serves alongside an FK column.
+ * For a column keyed `category_id` the data row also carries
+ * `row.category = { value, label }` (the FK key with the trailing `_id`
+ * stripped) — mirroring how `created_by` ships as a `{ name, avatar, email }`
+ * sibling consumed by the `creator` renderer. Returns the relation key so the
+ * cell can read `row[relationKeyFor(col)]`.
+ */
+export const relationKeyFor = (col: Pick<ColumnDefinition, 'key'>): string => {
+    const k = col.key
+    return k.endsWith('_id') ? k.slice(0, -3) : k
+}
+
+/**
+ * Reads the resolved relation/option label a backend serves for an FK or
+ * option column, falling back to the raw value. Pure so the cell renderers and
+ * tests share one resolution path:
+ *   - relation: prefer the sibling `{ value, label }` object's label.
+ *   - option:   prefer the matched `options[].label` (value compared as string).
+ *   - else:     the raw value coerced to string ('' when nullish).
+ */
+export const resolveRelationLabel = (col: ColumnDefinition, row: any): string => {
+    const sibling = getNestedValue(row, relationKeyFor(col))
+    const label =
+        sibling && typeof sibling === 'object'
+            ? sibling.label ?? sibling.name
+            : undefined
+    if (label !== undefined && label !== null && label !== '') return String(label)
+    const raw = getNestedValue(row, col.key)
+    return raw !== undefined && raw !== null ? String(raw) : ''
+}
+
+/**
+ * Renders a resolved FK relation as a clean, truncated chip. Reads the
+ * backend-resolved sibling `{ value, label }` (see `relationKeyFor`) and shows
+ * its `label`. Falls back to the raw id when no sibling was resolved, and to an
+ * empty marker when there is no value at all. Domain-agnostic: works for every
+ * `belongs_to` column (category, supplier, warehouse, …) without per-addon code.
+ */
+const RelationCell: React.FC<{ col: ColumnDefinition; row: any }> = ({ col, row }) => {
+    const isDark = useIsDarkTheme()
+    const display = resolveRelationLabel(col, row)
+    if (!display) return <EmptyCell />
+    // Deterministic, SUBTLE color keyed on the resolved label — lighter than
+    // enum badges (soft tint, no heavy fill) so category/brand chips read as
+    // alive yet stay visually distinct from option/status badges. Inline style
+    // (hex-derived) bypasses the host tailwind safelist.
+    const chipStyles = relationChipStyles(display, { isDark })
+    return (
+        <span
+            className="inline-flex max-w-[220px] items-center truncate rounded-md px-2 py-0.5 text-sm font-medium"
+            style={chipStyles}
+            title={display}
+        >
+            <span className="truncate">{display}</span>
+        </span>
+    )
+}
+
 /**
  * Generic avatar-style cell: round/rounded photo (or initials fallback) +
  * primary name + optional subtitle. Backs the `avatar`/`search` columns as
@@ -453,6 +523,34 @@ export function makeDefaultGetDynamicColumns(
                         )
                     }
 
+                    // Resolved FK relation chip. Triggers on an explicit
+                    // `cellStyle: 'relation'` or on any column carrying a `ref`
+                    // (a belongs_to FK) that isn't being rendered as an
+                    // option/badge. Reads the backend-resolved
+                    // `row[<key w/o _id>] = { value, label }` sibling.
+                    if (
+                        renderAs === 'relation' ||
+                        (col.ref && !col.options?.length && renderAs !== 'badge' && renderAs !== 'status')
+                    ) {
+                        return <RelationCell col={col} row={row.original} />
+                    }
+
+                    // Option/type column: a `select`-style column ships its
+                    // localized `options: [{value,label,color,icon}]` inline and
+                    // the cell value is the raw option value (e.g. "storable").
+                    // Render the matched option's label as a colored badge —
+                    // same OptionBadge the `badge`/`status` cells use.
+                    if (
+                        (renderAs === 'select' || renderAs === 'option' || col.type === 'select') &&
+                        col.options &&
+                        col.options.length > 0
+                    ) {
+                        if (!value && value !== 0) return <EmptyCell />
+                        const option = col.options.find((o) => o.value === String(value))
+                        if (option) return <OptionBadge option={option} fallback={String(value)} />
+                        return <Badge variant="outline">{String(value)}</Badge>
+                    }
+
                     switch (renderAs) {
                         case 'date': {
                             if (!value) return <span className="text-muted-foreground">-</span>

package/src/dynamic-table.tsx

@@ -300,24 +300,32 @@ export function DynamicTable({
             }
             if (!meta) return
             const columnEndpoints = meta.columns.filter(c => c.useOptions && c.searchEndpoint).map(c => c.searchEndpoint!)
-            const filterEndpoints = (meta.filters || []).filter(f => f.searchEndpoint && (f.type === 'select' || f.type === 'boolean')).map(f => f.searchEndpoint!)
-            const allEndpoints = [...columnEndpoints, ...filterEndpoints]
+            const filterEndpoints = (meta.filters || []).filter(f => f.searchEndpoint && (f.type === 'select' || f.type === 'dynamic_select' || f.type === 'boolean')).map(f => f.searchEndpoint!)
+            // Relation (`ref`/`dynamic_select`) columns flagged `filterable`
+            // also need their options preloaded so the per-column multi-select
+            // combobox has something to show. Mirrors the explicit-filter path
+            // above for columns that drive their filter off the column def.
+            const columnFilterEndpoints = meta.columns
+                .filter(c => c.filterable && c.searchEndpoint)
+                .map(c => c.searchEndpoint!)
+            const allEndpoints = [...columnEndpoints, ...filterEndpoints, ...columnFilterEndpoints]
             if (allEndpoints.length > 0) {
                 prefetchOptions(allEndpoints).then(fetchedMap => {
                     const colMap = new Map<string, any[]>()
                     columnEndpoints.forEach(ep => { if (fetchedMap.has(ep)) colMap.set(ep, fetchedMap.get(ep)!) })
                     setOptionsMap(colMap)
                     const fMap = new Map<string, DynamicFilterOption[]>()
-                    filterEndpoints.forEach(ep => {
-                        if (fetchedMap.has(ep)) {
-                            fMap.set(ep, (fetchedMap.get(ep) || []).map((item: any) => ({
-                                label: item.label || item.name || '',
-                                value: String(item.value ?? item.id ?? ''),
-                                icon: item.icon,
-                                color: item.color || item.class,
-                            })))
-                        }
-                    })
+                    const projectFilterOptions = (ep: string) => {
+                        if (!fetchedMap.has(ep) || fMap.has(ep)) return
+                        fMap.set(ep, (fetchedMap.get(ep) || []).map((item: any) => ({
+                            label: item.label || item.name || '',
+                            value: String(item.value ?? item.id ?? ''),
+                            icon: item.icon,
+                            color: item.color || item.class,
+                        })))
+                    }
+                    filterEndpoints.forEach(projectFilterOptions)
+                    columnFilterEndpoints.forEach(projectFilterOptions)
                     setFilterOptionsMap(fMap)
                 })
             }
@@ -531,14 +539,20 @@ export function DynamicTable({
             if (!c.filterable || map.has(c.key)) continue
             const hasStaticOptions = (c.options?.length ?? 0) > 0
             const hasEndpoint = !!c.searchEndpoint
-            // Pick the filter UI from column type:
-            //   - explicit options or searchEndpoint → multi-select dropdown
+            const isRelation = !!c.ref || c.filterType === 'dynamic_select'
+            // Pick the filter UI. The backend's explicit `filterType` wins; when
+            // absent we infer it from the column shape:
+            //   - ref/dynamic_select column        → relation multi-select
+            //     (options stream from searchEndpoint = /options/<ref>)
+            //   - inline options or searchEndpoint  → static multi-select
             //   - boolean → boolean toggle (renders as select under the hood)
             //   - number / number_range / numeric → number range
             //   - date → date range picker (start/end calendar)
             //   - everything else (text, email, phone, tags…) → text contains
-            let filterType: ColumnFilterConfig['filterType'] = 'select'
-            if (hasStaticOptions || hasEndpoint) filterType = '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 (c.type === 'date') filterType = 'date_range'

package/src/index.ts

@@ -62,6 +62,8 @@ export type {
 export {
     defaultGetDynamicColumns,
     makeDefaultGetDynamicColumns,
+    relationKeyFor,
+    resolveRelationLabel,
     type DynamicColumnsHelpers,
 } from './dynamic-columns'
 export { DynamicRecordDialog } from './dialogs/dynamic-record'

package/src/types.ts

@@ -56,7 +56,13 @@ export interface RelationMeta {
 export interface FilterDefinition {
     key: string
     label: string
-    type: 'select' | 'boolean' | 'date_range' | 'number_range' | 'text'
+    /**
+     * `dynamic_select` resolves its options server-side from a relation
+     * (`searchEndpoint = /options/<ref>`) and renders the same multi-value
+     * combobox as `select`. The host loads + caches the options before they
+     * surface in the dropdown.
+     */
+    type: 'select' | 'dynamic_select' | 'boolean' | 'date_range' | 'number_range' | 'text'
     column: string
     options?: { value: string | boolean; label: string; icon?: string; color?: string }[]
     searchEndpoint?: string
@@ -104,8 +110,21 @@ export interface ColumnDefinition {
         | 'truncate-text'
         | 'creator'
         | 'user'
+        // Resolved FK relation chip. The data row carries a sibling
+        // `{ value, label }` object keyed by the column key with the trailing
+        // `_id` stripped (e.g. `category_id` → `row.category`). Also triggered
+        // implicitly whenever the column carries a `ref` (belongs_to FK).
+        | 'relation'
     sortable: boolean
     filterable: boolean
+    /**
+     * Explicit filter UI the backend wants for this column when `filterable`.
+     * When absent the SDK infers it from the column shape (options/endpoint →
+     * `select`, boolean/number/date → their range pickers, else `text`). A
+     * `ref` (belongs_to FK) column is served as `dynamic_select` so its options
+     * stream from `searchEndpoint = /options/<ref>` into a multi-value combobox.
+     */
+    filterType?: 'select' | 'dynamic_select' | 'boolean' | 'date_range' | 'number_range' | 'text'
     hidden?: boolean
     /**
      * Scopes where this column is rendered. When `'modal'` (or `'list'`) the