@asteby/metacore-runtime-react 18.17.3 → 18.19.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @asteby/metacore-runtime-react
 
+## 18.19.0
+
+### Minor Changes
+
+- de0b4bb: Add a generic `CollectionCell` renderer for jsonb / array / object table-cell values.
+
+  Previously the `default:` branch of `defaultGetDynamicColumns` rendered such
+  values as raw `JSON.stringify(value)`, which was unreadable. Every jsonb column
+  now renders a compact, brand-neutral, dark-mode-friendly cell with no per-addon
+  config:
+  - **Array of objects** (e.g. line items): a count Badge (`2 ítems`) that opens a
+    Popover mini-table — columns are the prettified union of row keys, cells go
+    through a shared `formatScalar` (uuid/long strings truncated, booleans as
+    ✓/✗, nested shapes summarized).
+  - **Array of scalars**: first few joined inline with a `+N` overflow, full list
+    in the popover.
+  - **Plain object**: first few `key: value` pairs inline, all pairs in the popover.
+  - **null / empty**: muted `-`.
+  - JSON-string values are defensively parsed; unparseable strings are truncated.
+
+  Exports `CollectionCell`, `formatScalar`, `prettifyKey`, and `CollectionCellProps`.
+
+## 18.18.0
+
+### Minor Changes
+
+- be0d2b8: Dependent (cascading) options for declarative pickers. A field/item_field may
+  declare `dependsOn` (camelCase) / `depends_on` (snake_case) naming another field
+  in the same action form — a header field (e.g. `source_warehouse_id`) or a
+  sibling row cell — whose current value scopes this picker's options. The value
+  is forwarded to the options endpoint as `filter_value` (`useOptionsResolver`
+  gains a `filterValue` arg) and the picker re-fetches when it changes, clearing
+  the stale selection. While the depended-on field is empty the picker is disabled
+  with an overridable hint. Header form context flows down through
+  `DynamicLineItems` → `CellRenderer`/`RefCell` so a line-items cell can depend on
+  a header field, not just same-row values. Option `description` (e.g. available
+  qty) is now shown in the line-items `RefCell` select as well as
+  `DynamicSelectField`.
+
+  A field/item_field may also carry an `optionsConfig` (camelCase) /
+  `options_config` (snake_case) object — the kernel's enriched options routing,
+  shaped `{ type, source, filter_by, value, label_ref, description }`. When it
+  declares a `source`, the picker queries that SOURCE model instead of the field's
+  `ref`: URL `/options/<source>` with query field `<value ?? field.key>` and the
+  cascade `filter_value`. Without `optionsConfig.source` the picker keeps its
+  `ref`-based behaviour (retrocompat). New `getOptionsConfig` / `resolveOptionsSource`
+  helpers (and `FieldOptionsConfig` type) are exported. Fully generic — no domain
+  knowledge in the SDK.
+
 ## 18.17.3
 
 ### Patch Changes

package/dist/action-modal-dispatcher.js

@@ -18,7 +18,7 @@ import { DynamicLineItems } from './dynamic-line-items';
 import { DynamicSelectField } from './dynamic-select-field';
 import { DynamicDateField } from './dynamic-date-field';
 import { UploadField } from './upload-field';
-import { isLineItemsField, resolveWidget } from './dynamic-form-schema';
+import { isLineItemsField, resolveWidget, resolveDependsValue, getDependsOn } from './dynamic-form-schema';
 // Canonical registry lives in @asteby/metacore-sdk
 import { getActionComponent, } from '@asteby/metacore-sdk';
 export function ActionModalDispatcher({ open, onOpenChange, action, model, record, endpoint, onSuccess, }) {
@@ -149,13 +149,19 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
                         const fullWidth = isLineItemsField(field) ||
                             resolveWidget(field) === 'textarea' ||
                             resolveWidget(field) === 'richtext';
-                        return (_jsxs("div", { className: 'grid gap-2 ' + (fullWidth ? 'sm:col-span-2' : ''), children: [_jsxs(Label, { htmlFor: field.key, children: [field.label, field.required && _jsx("span", { className: "text-red-500 ml-1", children: "*" })] }), renderField(field, formData[field.key], (v) => updateField(field.key, v))] }, field.key));
+                        return (_jsxs("div", { className: 'grid gap-2 ' + (fullWidth ? 'sm:col-span-2' : ''), children: [_jsxs(Label, { htmlFor: field.key, children: [field.label, field.required && _jsx("span", { className: "text-red-500 ml-1", children: "*" })] }), renderField(field, formData[field.key], (v) => updateField(field.key, v), formData)] }, field.key));
                     }) }), _jsxs(DialogFooter, { className: "shrink-0", children: [_jsx(Button, { variant: "outline", onClick: () => onOpenChange(false), disabled: executing, children: t('common.cancel') }), _jsxs(Button, { onClick: execute, disabled: executing, style: action.color ? { backgroundColor: action.color, color: 'white' } : undefined, children: [executing ? _jsx(Loader2, { className: "mr-2 h-4 w-4 animate-spin" }) : _jsx(DynamicIcon, { name: action.icon, className: "mr-2 h-4 w-4" }), action.label] })] })] }) }));
 }
-function renderField(field, value, onChange) {
+function renderField(field, value, onChange, 
+// Full current form values — lets a line-items grid (and any cascading
+// header picker) resolve a `dependsOn` reference against sibling header
+// fields. Omitted by callers that have no surrounding form (the field is
+// then treated as having no resolvable dependency).
+formValues) {
     // Repeatable line-items group → row grid (value is an array of row objects).
+    // The header form values flow in so a cell can depend on a header field.
     if (isLineItemsField(field)) {
-        return _jsx(DynamicLineItems, { field: field, value: value, onChange: onChange });
+        return _jsx(DynamicLineItems, { field: field, value: value, onChange: onChange, formValues: formValues });
     }
     // Resolve the widget the same way DynamicForm does (explicit widget wins,
     // else inferred from type) so action modals and the standalone form stay in
@@ -163,7 +169,12 @@ function renderField(field, value, onChange) {
     // dropped `dynamic_select` to a plain text input.
     const widget = resolveWidget(field);
     if (widget === 'dynamic_select') {
-        return _jsx(DynamicSelectField, { field: field, value: value, onChange: onChange });
+        // A header-level dynamic_select may itself depend on another header
+        // field; resolve its filter_value from the form context.
+        const dependsValue = getDependsOn(field)
+            ? resolveDependsValue(field, formValues)
+            : undefined;
+        return _jsx(DynamicSelectField, { field: field, value: value, onChange: onChange, dependsValue: dependsValue });
     }
     // File upload → themed picker that POSTs the file to the host upload
     // endpoint and stores the returned url/path. Kept in sync with DynamicForm.

package/dist/collection-cell.d.ts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+/** snake_case / dotted / kebab key → Title Case (`product_id` → "Product ID"). */
+export declare function prettifyKey(key: string): string;
+/**
+ * Render a single scalar (or near-scalar) value for compact display.
+ * - uuid-like or very long (32+ char) strings → first 8 chars + "…"
+ * - numbers / booleans → rendered as-is (booleans as ✓ / ✗)
+ * - nested object → "{…}", nested array → "[N]"
+ * - null / undefined / "" → "-"
+ */
+export declare function formatScalar(value: unknown): string;
+export interface CollectionCellProps {
+    value: unknown;
+    /** Max items previewed inline for scalar arrays. */
+    maxInline?: number;
+}
+/**
+ * Generic renderer for jsonb / array / object cell values. Brand-neutral,
+ * compact, dark-mode friendly. Never throws on unexpected shapes.
+ */
+export declare function CollectionCell({ value, maxInline }: CollectionCellProps): React.JSX.Element;
+//# sourceMappingURL=collection-cell.d.ts.map

package/dist/collection-cell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-cell.d.ts","sourceRoot":"","sources":["../src/collection-cell.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAoB9B,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG/C;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAYnD;AAyID,MAAM,WAAW,mBAAmB;IAChC,KAAK,EAAE,OAAO,CAAA;IACd,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAAE,KAAK,EAAE,SAAa,EAAE,EAAE,mBAAmB,qBA6E3E"}

package/dist/collection-cell.js

@@ -0,0 +1,141 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { List } from 'lucide-react';
+import { Badge, Popover, PopoverContent, PopoverTrigger, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, cn, } from '@asteby/metacore-ui';
+import { humanizeToken } from './dynamic-columns-helpers';
+const UUID_LIKE_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** snake_case / dotted / kebab key → Title Case (`product_id` → "Product ID"). */
+export function prettifyKey(key) {
+    const pretty = humanizeToken(key);
+    return pretty || key;
+}
+/**
+ * Render a single scalar (or near-scalar) value for compact display.
+ * - uuid-like or very long (32+ char) strings → first 8 chars + "…"
+ * - numbers / booleans → rendered as-is (booleans as ✓ / ✗)
+ * - nested object → "{…}", nested array → "[N]"
+ * - null / undefined / "" → "-"
+ */
+export function formatScalar(value) {
+    if (value === null || value === undefined)
+        return '-';
+    if (typeof value === 'boolean')
+        return value ? '✓' : '✗';
+    if (typeof value === 'number')
+        return String(value);
+    if (Array.isArray(value))
+        return `[${value.length}]`;
+    if (typeof value === 'object')
+        return '{…}';
+    const str = String(value);
+    if (str === '')
+        return '-';
+    if (UUID_LIKE_RE.test(str) || str.length >= 32) {
+        return `${str.slice(0, 8)}…`;
+    }
+    return str;
+}
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * Defensively coerce a raw cell value into something renderable. Strings that
+ * look like JSON (`[`/`{` start) are parsed; everything else is passed through.
+ */
+function parseValue(value) {
+    if (typeof value !== 'string')
+        return value;
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('[') && trimmed.endsWith(']')) ||
+        (trimmed.startsWith('{') && trimmed.endsWith('}'))) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return value;
+        }
+    }
+    return value;
+}
+/** Stable union of keys across an array of row objects, first-seen order. */
+function unionKeys(rows) {
+    const seen = [];
+    const set = new Set();
+    for (const row of rows) {
+        for (const key of Object.keys(row)) {
+            if (!set.has(key)) {
+                set.add(key);
+                seen.push(key);
+            }
+        }
+    }
+    return seen;
+}
+const PANEL_CLASS = 'w-auto max-w-[480px] max-h-[320px] overflow-auto p-0';
+function MiniTable({ rows }) {
+    const keys = unionKeys(rows);
+    if (keys.length === 0) {
+        return _jsx("div", { className: "p-3 text-xs text-muted-foreground", children: "-" });
+    }
+    return (_jsxs(Table, { children: [_jsx(TableHeader, { children: _jsx(TableRow, { children: keys.map((key) => (_jsx(TableHead, { className: "text-xs whitespace-nowrap", children: prettifyKey(key) }, key))) }) }), _jsx(TableBody, { children: rows.map((row, i) => (_jsx(TableRow, { children: keys.map((key) => (_jsx(TableCell, { className: "text-xs whitespace-nowrap", children: formatScalar(row[key]) }, key))) }, i))) })] }));
+}
+function ScalarList({ values }) {
+    return (_jsx("ul", { className: "p-3 space-y-1", children: values.map((v, i) => (_jsx("li", { className: "text-xs text-foreground", children: formatScalar(v) }, i))) }));
+}
+function PairList({ entries }) {
+    return (_jsx("ul", { className: "p-3 space-y-1", children: entries.map(([key, v]) => (_jsxs("li", { className: "text-xs", children: [_jsxs("span", { className: "text-muted-foreground", children: [prettifyKey(key), ":"] }), ' ', _jsx("span", { className: "text-foreground", children: formatScalar(v) })] }, key))) }));
+}
+/** Compact badge trigger that opens a popover panel. */
+function PopoverShell({ label, title, children, icon = true, }) {
+    return (_jsxs(Popover, { children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Badge, { variant: "secondary", className: "cursor-pointer gap-1 font-normal", title: title, children: [icon ? _jsx(List, { className: "h-3 w-3" }) : null, label] }) }), _jsx(PopoverContent, { align: "start", className: cn(PANEL_CLASS), children: children })] }));
+}
+/**
+ * Generic renderer for jsonb / array / object cell values. Brand-neutral,
+ * compact, dark-mode friendly. Never throws on unexpected shapes.
+ */
+export function CollectionCell({ value, maxInline = 3 }) {
+    const parsed = parseValue(value);
+    // Empty-ish → muted dash.
+    if (parsed === null ||
+        parsed === undefined ||
+        parsed === '' ||
+        (Array.isArray(parsed) && parsed.length === 0) ||
+        (isPlainObject(parsed) && Object.keys(parsed).length === 0)) {
+        return _jsx("span", { className: "text-muted-foreground text-xs", children: "-" });
+    }
+    // Non-collection scalar fell through here (e.g. unparseable string): truncate.
+    if (!Array.isArray(parsed) && !isPlainObject(parsed)) {
+        const str = String(parsed);
+        return (_jsx("span", { className: "text-muted-foreground text-xs truncate block max-w-[300px]", title: str, children: str.length > 80 ? `${str.slice(0, 80)}…` : str }));
+    }
+    // ARRAY ------------------------------------------------------------------
+    if (Array.isArray(parsed)) {
+        const allObjects = parsed.every((item) => isPlainObject(item));
+        if (allObjects) {
+            const rows = parsed;
+            const count = rows.length;
+            const label = count === 1 ? '1 ítem' : `${count} ítems`;
+            const title = rows
+                .map((row) => Object.entries(row)
+                .map(([k, v]) => `${prettifyKey(k)}: ${formatScalar(v)}`)
+                .join(', '))
+                .join(' | ');
+            return (_jsx(PopoverShell, { label: label, title: title, children: _jsx(MiniTable, { rows: rows }) }));
+        }
+        // Array of scalars (or mixed): preview first N joined, "+N" overflow.
+        const preview = parsed.slice(0, maxInline).map(formatScalar).join(', ');
+        const overflow = parsed.length - maxInline;
+        const label = overflow > 0 ? `${preview} +${overflow}` : preview;
+        const title = parsed.map(formatScalar).join(', ');
+        return (_jsx(PopoverShell, { label: label, title: title, icon: false, children: _jsx(ScalarList, { values: parsed }) }));
+    }
+    // PLAIN OBJECT -----------------------------------------------------------
+    const entries = Object.entries(parsed);
+    const inline = entries
+        .slice(0, maxInline)
+        .map(([k, v]) => `${prettifyKey(k)}: ${formatScalar(v)}`)
+        .join(', ');
+    const overflow = entries.length - maxInline;
+    const label = overflow > 0 ? `${inline} +${overflow}` : inline;
+    const title = entries
+        .map(([k, v]) => `${prettifyKey(k)}: ${formatScalar(v)}`)
+        .join(', ');
+    return (_jsx(PopoverShell, { label: label, title: title, icon: false, children: _jsx(PairList, { entries: entries }) }));
+}

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

@@ -1 +1 @@
-{"version":3,"file":"dynamic-columns.d.ts","sourceRoot":"","sources":["../src/dynamic-columns.tsx"],"names":[],"mappings":"AAgBA,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,UAAU,CAAA;AAgC9C,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;AA0BD;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,gBAAgB,EAAE,cAAc,MAAM,KAAG,MACzB,CAAA;AAQrD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,gBAAgB,KAAG,MAAM,GAAG,SAG5D,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAC7B,KAAK,gBAAgB,EACrB,OAAO,OAAO,EACd,WAAW,MAAM,EACjB,SAAS,MAAM,KAChB,MAyBF,CAAA;AA8DD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,GAAI,QAAQ,GAAG,EAAE,KAAK,GAAG,KAAG,OAMlE,CAAA;AAqKD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,KAAG,MAGnE,CAAA;AAED,6EAA6E;AAC7E,eAAO,MAAM,eAAe,2DAA4D,CAAA;AAExF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,GAClB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA6C5C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,gBAAgB,EAAE,KAAK,GAAG,KAAG,MAWtE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,gBAAgB,EAAE,KAAK,GAAG,KAAG,MAOtE,CAAA;AAsID;;;;GAIG;AACH,wBAAgB,4BAA4B,CACxC,OAAO,GAAE,qBAA0B,GACpC,iBAAiB,CA2nBnB;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBACL,CAAA"}
+{"version":3,"file":"dynamic-columns.d.ts","sourceRoot":"","sources":["../src/dynamic-columns.tsx"],"names":[],"mappings":"AAgBA,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,UAAU,CAAA;AAiC9C,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;AA0BD;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,gBAAgB,EAAE,cAAc,MAAM,KAAG,MACzB,CAAA;AAQrD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,gBAAgB,KAAG,MAAM,GAAG,SAG5D,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAC7B,KAAK,gBAAgB,EACrB,OAAO,OAAO,EACd,WAAW,MAAM,EACjB,SAAS,MAAM,KAChB,MAyBF,CAAA;AA8DD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,GAAI,QAAQ,GAAG,EAAE,KAAK,GAAG,KAAG,OAMlE,CAAA;AAqKD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,KAAG,MAGnE,CAAA;AAED,6EAA6E;AAC7E,eAAO,MAAM,eAAe,2DAA4D,CAAA;AAExF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,GAClB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA6C5C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,gBAAgB,EAAE,KAAK,GAAG,KAAG,MAWtE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,gBAAgB,EAAE,KAAK,GAAG,KAAG,MAOtE,CAAA;AAsID;;;;GAIG;AACH,wBAAgB,4BAA4B,CACxC,OAAO,GAAE,qBAA0B,GACpC,iBAAiB,CAunBnB;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBACL,CAAA"}

package/dist/dynamic-columns.js

@@ -24,6 +24,7 @@ import { Progress } from './dialogs/_primitives';
 import { humanizeToken } from './dynamic-columns-helpers';
 import { OptionsContext } from './options-context';
 import { DynamicIcon, isLucideIconName } from './dynamic-icon';
+import { CollectionCell } from './collection-cell';
 import { isNilUuid, normalizeNilUuid } from './nil-uuid';
 import { isColumnVisibleInTable } from './column-visibility';
 const defaultGetImageUrl = (path) => path;
@@ -735,7 +736,7 @@ export function makeDefaultGetDynamicColumns(helpers = {}) {
                         }
                         default: {
                             if (typeof value === 'object' && value !== null) {
-                                return (_jsx("span", { className: "text-muted-foreground text-xs", children: JSON.stringify(value) }));
+                                return _jsx(CollectionCell, { value: value });
                             }
                             if (col.key === 'description' ||
                                 col.key === 'features' ||

package/dist/dynamic-form-schema.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { ActionFieldDef } from './types';
+import type { ActionFieldDef, FieldOptionsConfig } from './types';
 /**
  * Apps register validator implementations by slug. The slug is the value
  * `OrgConfig.validators[<key>]` returns for a $org.<key> reference.
@@ -63,6 +63,46 @@ export declare function resolveWidget(field: ActionFieldDef): string;
 export declare function getFieldRef(field: ActionFieldDef): string | undefined;
 /** True when a field declares an FK target the SDK can resolve options against. */
 export declare function fieldHasRef(field: ActionFieldDef): boolean;
+/**
+ * Resolves a field's cascade dependency — the key of another form field whose
+ * current value scopes this picker's options (`filter_value`). Tolerates the
+ * camelCase `dependsOn` (authored SDK shape) and the snake_case `depends_on`
+ * the kernel manifest serves. Returns the trimmed field key, or `undefined`
+ * when the field declares no dependency.
+ */
+export declare function getDependsOn(field: ActionFieldDef): string | undefined;
+/**
+ * Resolves the cascade `filter_value` for a field from the surrounding form
+ * context. The depended-on key is matched against the current row first (a
+ * sibling item-field on the same line) and then the header form values, so a
+ * line-items cell can depend on either a sibling cell OR a header field (e.g.
+ * `source_warehouse_id`). Returns the stringified value, or `''` when the
+ * field has no dependency or the depended-on value is empty/unset.
+ */
+export declare function resolveDependsValue(field: ActionFieldDef, formValues?: Record<string, any> | null, rowValues?: Record<string, any> | null): string;
+/**
+ * Reads a field's enriched options-resolution config, tolerating the camelCase
+ * `optionsConfig` (authored SDK shape) and the snake_case `options_config` the
+ * kernel manifest serves. Returns `undefined` when the field declares none.
+ */
+export declare function getOptionsConfig(field: ActionFieldDef): FieldOptionsConfig | undefined;
+/**
+ * Resolves where a picker should fetch its options from, honouring an
+ * `optionsConfig.source` (the dependent/scoped routing the kernel serves) and
+ * falling back to the field's `ref` for retrocompat.
+ *
+ * - With `optionsConfig.source`: query the SOURCE model →
+ *   `{ endpoint: '/options/<source>', fieldKey: <value ?? field.key> }`.
+ * - Without it: keep `ref`-based resolution → `{ ref }` (the hook's canonical
+ *   path), `fieldKey` defaulting to `'id'`.
+ *
+ * The returned shape feeds straight into `useOptionsResolver` args.
+ */
+export declare function resolveOptionsSource(field: ActionFieldDef): {
+    endpoint?: string;
+    ref?: string;
+    fieldKey: string;
+};
 /**
  * Normalizes an upload field's config, tolerating both the camelCase authored
  * SDK shape and the snake_case the kernel serves (`max_size`, `storage_path`).

package/dist/dynamic-form-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-form-schema.d.ts","sourceRoot":"","sources":["../src/dynamic-form-schema.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAmB,MAAM,KAAK,CAAA;AACxC,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,SAAS,CAAA;AAiB9D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS,GAAG,IAAI,CAEzF;AAcD,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE;;kBAMtD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,cAAc,EAAE,CAGrE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,cAAc,GACtB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAatG;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAO3C;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACjC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,GAAG,EAAE,GAAG,SAAS,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB;AAED,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,OAAO,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC3B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,GAAG,EAAE,GAAG,SAAS,GACxB,YAAY,GAAG,SAAS,CAgB1B;AAqDD,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CA4B3D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAIrE;AAED,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG;IACpD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB,CAaA"}
+{"version":3,"file":"dynamic-form-schema.d.ts","sourceRoot":"","sources":["../src/dynamic-form-schema.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAmB,MAAM,KAAK,CAAA;AACxC,OAAO,KAAK,EAAE,cAAc,EAAmB,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAiBlF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS,GAAG,IAAI,CAEzF;AAcD,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE;;kBAMtD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,cAAc,EAAE,CAGrE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,cAAc,GACtB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAatG;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAO3C;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACjC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,GAAG,EAAE,GAAG,SAAS,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB;AAED,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,OAAO,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC3B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,GAAG,EAAE,GAAG,SAAS,GACxB,YAAY,GAAG,SAAS,CAgB1B;AAqDD,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CA4B3D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAIrE;AAED,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAItE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAC/B,KAAK,EAAE,cAAc,EACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,EACvC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GACvC,MAAM,CAQR;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,kBAAkB,GAAG,SAAS,CAGtF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;CACnB,CAQA;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG;IACpD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB,CAaA"}

package/dist/dynamic-form-schema.js

@@ -234,6 +234,67 @@ export function getFieldRef(field) {
 export function fieldHasRef(field) {
     return getFieldRef(field) !== undefined;
 }
+/**
+ * Resolves a field's cascade dependency — the key of another form field whose
+ * current value scopes this picker's options (`filter_value`). Tolerates the
+ * camelCase `dependsOn` (authored SDK shape) and the snake_case `depends_on`
+ * the kernel manifest serves. Returns the trimmed field key, or `undefined`
+ * when the field declares no dependency.
+ */
+export function getDependsOn(field) {
+    const dep = field.dependsOn ?? field.depends_on;
+    if (typeof dep === 'string' && dep.trim() !== '')
+        return dep.trim();
+    return undefined;
+}
+/**
+ * Resolves the cascade `filter_value` for a field from the surrounding form
+ * context. The depended-on key is matched against the current row first (a
+ * sibling item-field on the same line) and then the header form values, so a
+ * line-items cell can depend on either a sibling cell OR a header field (e.g.
+ * `source_warehouse_id`). Returns the stringified value, or `''` when the
+ * field has no dependency or the depended-on value is empty/unset.
+ */
+export function resolveDependsValue(field, formValues, rowValues) {
+    const dep = getDependsOn(field);
+    if (!dep)
+        return '';
+    const raw = (rowValues && rowValues[dep] != null && rowValues[dep] !== '' ? rowValues[dep] : undefined) ??
+        (formValues ? formValues[dep] : undefined);
+    if (raw == null || raw === '')
+        return '';
+    return String(raw);
+}
+/**
+ * Reads a field's enriched options-resolution config, tolerating the camelCase
+ * `optionsConfig` (authored SDK shape) and the snake_case `options_config` the
+ * kernel manifest serves. Returns `undefined` when the field declares none.
+ */
+export function getOptionsConfig(field) {
+    const cfg = field.optionsConfig ?? field.options_config;
+    return cfg && typeof cfg === 'object' ? cfg : undefined;
+}
+/**
+ * Resolves where a picker should fetch its options from, honouring an
+ * `optionsConfig.source` (the dependent/scoped routing the kernel serves) and
+ * falling back to the field's `ref` for retrocompat.
+ *
+ * - With `optionsConfig.source`: query the SOURCE model →
+ *   `{ endpoint: '/options/<source>', fieldKey: <value ?? field.key> }`.
+ * - Without it: keep `ref`-based resolution → `{ ref }` (the hook's canonical
+ *   path), `fieldKey` defaulting to `'id'`.
+ *
+ * The returned shape feeds straight into `useOptionsResolver` args.
+ */
+export function resolveOptionsSource(field) {
+    const cfg = getOptionsConfig(field);
+    const source = typeof cfg?.source === 'string' ? cfg.source.trim() : '';
+    if (source) {
+        const value = typeof cfg?.value === 'string' && cfg.value.trim() !== '' ? cfg.value.trim() : field.key;
+        return { endpoint: `/options/${source}`, fieldKey: value };
+    }
+    return { ref: getFieldRef(field), fieldKey: 'id' };
+}
 /**
  * Normalizes an upload field's config, tolerating both the camelCase authored
  * SDK shape and the snake_case the kernel serves (`max_size`, `storage_path`).

package/dist/dynamic-line-items.d.ts

@@ -4,6 +4,12 @@ export interface DynamicLineItemsProps {
     value: any[] | undefined;
     onChange: (rows: any[]) => void;
     disabled?: boolean;
+    /**
+     * Current values of the surrounding (header) form. Threaded into each cell
+     * so a cell field with `dependsOn` can scope its options by a HEADER field
+     * (e.g. `source_warehouse_id`), not just a sibling cell on the same row.
+     */
+    formValues?: Record<string, any>;
 }
-export declare function DynamicLineItems({ field, value, onChange, disabled }: DynamicLineItemsProps): import("react").JSX.Element;
+export declare function DynamicLineItems({ field, value, onChange, disabled, formValues }: DynamicLineItemsProps): import("react").JSX.Element;
 //# sourceMappingURL=dynamic-line-items.d.ts.map

package/dist/dynamic-line-items.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-line-items.d.ts","sourceRoot":"","sources":["../src/dynamic-line-items.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAW7C,MAAM,WAAW,qBAAqB;IAClC,KAAK,EAAE,cAAc,CAAA;IACrB,KAAK,EAAE,GAAG,EAAE,GAAG,SAAS,CAAA;IACxB,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAA;CACrB;AAkBD,wBAAgB,gBAAgB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAgB,EAAE,EAAE,qBAAqB,+BAiJnG"}
+{"version":3,"file":"dynamic-line-items.d.ts","sourceRoot":"","sources":["../src/dynamic-line-items.tsx"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAe7C,MAAM,WAAW,qBAAqB;IAClC,KAAK,EAAE,cAAc,CAAA;IACrB,KAAK,EAAE,GAAG,EAAE,GAAG,SAAS,CAAA;IACxB,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CACnC;AAkBD,wBAAgB,gBAAgB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAgB,EAAE,UAAU,EAAE,EAAE,qBAAqB,+BAmJ/G"}

package/dist/dynamic-line-items.js

@@ -9,9 +9,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // row controls mutate the array; each cell is a widget resolved via
 // `resolveWidget`, matching the flat-field renderer in dynamic-form.tsx.
 import { Input, Textarea, Switch, Button, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from '@asteby/metacore-ui/primitives';
+import { useEffect, useRef } from 'react';
 import { Plus, Trash2, Check } from 'lucide-react';
-import { resolveWidget, getItemFields, computeLineItemTotals, evaluateBalance, toNumber, } from './dynamic-form-schema';
-import { DynamicSelectField } from './dynamic-select-field';
+import { resolveWidget, getItemFields, computeLineItemTotals, evaluateBalance, toNumber, getDependsOn, resolveDependsValue, getOptionsConfig, resolveOptionsSource, } from './dynamic-form-schema';
+import { DynamicSelectField, DEFAULT_DEPENDS_HINT } from './dynamic-select-field';
 import { useOptionsResolver } from './use-options-resolver';
 const fmtNumber = (n) => n.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 });
 /** Numeric columns render right-aligned (debit/credit/amount feel). */
@@ -25,7 +26,7 @@ function emptyRow(itemFields) {
     }
     return row;
 }
-export function DynamicLineItems({ field, value, onChange, disabled = false }) {
+export function DynamicLineItems({ field, value, onChange, disabled = false, formValues }) {
     const itemFields = getItemFields(field);
     const rows = Array.isArray(value) ? value : [];
     // Columns flagged `total` get a per-column sum in the footer; the balance
@@ -59,7 +60,7 @@ export function DynamicLineItems({ field, value, onChange, disabled = false }) {
         updateCell(idx, key, cellValue);
     };
     return (_jsxs("div", { className: "grid gap-2", "data-widget": "line_items", children: [_jsx("div", { className: "overflow-x-auto rounded-md border", children: _jsxs("table", { className: "w-full text-sm", children: [_jsx("thead", { className: "bg-muted/50", children: _jsxs("tr", { children: [itemFields.map((col) => (_jsxs("th", { className: 'px-3 py-2 font-medium ' +
-                                            (isNumericCol(col) ? 'text-right' : 'text-left'), children: [col.label, col.required && _jsx("span", { className: "text-red-500 ml-1", children: "*" })] }, col.key))), _jsx("th", { className: "w-12 px-3 py-2", "aria-label": "acciones" })] }) }), _jsxs("tbody", { children: [rows.length === 0 && (_jsx("tr", { children: _jsx("td", { colSpan: itemFields.length + 1, className: "px-3 py-4 text-center text-muted-foreground", children: "Sin renglones" }) })), rows.map((row, idx) => (_jsxs("tr", { className: "border-t align-top", children: [itemFields.map((col) => (_jsx("td", { className: "px-2 py-1.5", children: _jsx(CellRenderer, { field: col, value: row?.[col.key], onChange: (v) => handleCell(idx, col.key, v), disabled: disabled }) }, col.key))), _jsx("td", { className: "px-2 py-1.5 text-center", children: _jsx(Button, { type: "button", variant: "ghost", size: "icon", onClick: () => removeRow(idx), disabled: disabled, "aria-label": "Eliminar rengl\u00F3n", children: _jsx(Trash2, { className: "h-4 w-4 text-red-500" }) }) })] }, idx)))] }), hasTotals && rows.length > 0 && (_jsx("tfoot", { className: "border-t bg-muted/30", children: _jsxs("tr", { children: [itemFields.map((col, ci) => {
+                                            (isNumericCol(col) ? 'text-right' : 'text-left'), children: [col.label, col.required && _jsx("span", { className: "text-red-500 ml-1", children: "*" })] }, col.key))), _jsx("th", { className: "w-12 px-3 py-2", "aria-label": "acciones" })] }) }), _jsxs("tbody", { children: [rows.length === 0 && (_jsx("tr", { children: _jsx("td", { colSpan: itemFields.length + 1, className: "px-3 py-4 text-center text-muted-foreground", children: "Sin renglones" }) })), rows.map((row, idx) => (_jsxs("tr", { className: "border-t align-top", children: [itemFields.map((col) => (_jsx("td", { className: "px-2 py-1.5", children: _jsx(CellRenderer, { field: col, value: row?.[col.key], onChange: (v) => handleCell(idx, col.key, v), disabled: disabled, formValues: formValues, rowValues: row }) }, col.key))), _jsx("td", { className: "px-2 py-1.5 text-center", children: _jsx(Button, { type: "button", variant: "ghost", size: "icon", onClick: () => removeRow(idx), disabled: disabled, "aria-label": "Eliminar rengl\u00F3n", children: _jsx(Trash2, { className: "h-4 w-4 text-red-500" }) }) })] }, idx)))] }), hasTotals && rows.length > 0 && (_jsx("tfoot", { className: "border-t bg-muted/30", children: _jsxs("tr", { children: [itemFields.map((col, ci) => {
                                         if (ci === 0) {
                                             return (_jsx("td", { className: "px-3 py-2 text-left font-medium text-muted-foreground", children: "Totales" }, col.key));
                                         }
@@ -80,15 +81,20 @@ function BalanceBadge({ state, }) {
 // without the per-field Label (the column header is the label) and sized for a
 // table cell. Nested line-items inside a row are not supported (a row column is
 // a scalar widget).
-function CellRenderer({ field, value, onChange, disabled }) {
+function CellRenderer({ field, value, onChange, disabled, formValues, rowValues }) {
     const widget = resolveWidget(field);
+    // Cascade scope for a cell with `dependsOn`: resolved from this row first
+    // (a sibling cell) then the header form (e.g. `source_warehouse_id`).
+    const dependsValue = getDependsOn(field)
+        ? resolveDependsValue(field, formValues, rowValues)
+        : undefined;
     // Async searchable picker per row cell — e.g. the account_id column of a
     // journal entry's debit/credit lines. Same widget as the flat form.
     if (widget === 'dynamic_select') {
-        return _jsx(DynamicSelectField, { field: field, value: value, onChange: onChange });
+        return _jsx(DynamicSelectField, { field: field, value: value, onChange: onChange, dependsValue: dependsValue });
     }
-    if (widget === 'select' && field.ref) {
-        return _jsx(RefCell, { field: field, value: value, onChange: onChange, disabled: disabled });
+    if (widget === 'select' && (field.ref || getOptionsConfig(field)?.source)) {
+        return (_jsx(RefCell, { field: field, value: value, onChange: onChange, disabled: disabled, formValues: formValues, rowValues: rowValues }));
     }
     switch (widget) {
         case 'textarea':
@@ -108,11 +114,39 @@ function CellRenderer({ field, value, onChange, disabled }) {
             return (_jsx(Input, { type: field.type === 'email' ? 'email' : field.type === 'url' ? 'url' : 'text', value: value || '', onChange: (e) => onChange(e.target.value), placeholder: field.placeholder, disabled: disabled }));
     }
 }
-function RefCell({ field, value, onChange, disabled }) {
+function RefCell({ field, value, onChange, disabled, formValues, rowValues }) {
+    // Cascade: resolve the value of the field this cell `dependsOn` from the
+    // row (sibling) first, then the header form. While empty, the picker is
+    // disabled with a hint instead of listing the whole (unscoped) table.
+    const dependsOn = getDependsOn(field);
+    const scope = dependsOn ? resolveDependsValue(field, formValues, rowValues) : '';
+    const blockedByDependency = !!dependsOn && scope === '';
+    // optionsConfig.source → query the source model (`/options/<source>` with
+    // `field=<value>`); else fall back to the field's `ref`.
+    const optSource = resolveOptionsSource(field);
     const { options, loading } = useOptionsResolver({
         modelKey: '',
-        fieldKey: 'id',
-        ref: field.ref,
+        fieldKey: optSource.fieldKey,
+        ref: optSource.ref,
+        endpoint: optSource.endpoint,
+        filterValue: dependsOn ? scope : undefined,
+        enabled: !blockedByDependency,
     });
-    return (_jsxs(Select, { value: value || '', onValueChange: onChange, disabled: disabled || loading, children: [_jsx(SelectTrigger, { className: "w-full", children: _jsx(SelectValue, { placeholder: loading ? 'Cargando…' : field.placeholder || 'Seleccionar...' }) }), _jsx(SelectContent, { children: options.map((opt) => (_jsx(SelectItem, { value: String(opt.id), children: opt.label }, String(opt.id)))) })] }));
+    // Clear the selection when the parent scope changes (skip initial mount).
+    const prevScopeRef = useRef(scope);
+    useEffect(() => {
+        if (!dependsOn)
+            return;
+        if (prevScopeRef.current !== scope) {
+            prevScopeRef.current = scope;
+            if (value)
+                onChange('');
+        }
+    }, [dependsOn, scope, value, onChange]);
+    const placeholder = blockedByDependency
+        ? DEFAULT_DEPENDS_HINT
+        : loading
+            ? 'Cargando…'
+            : field.placeholder || 'Seleccionar...';
+    return (_jsxs(Select, { value: value || '', onValueChange: onChange, disabled: disabled || loading || blockedByDependency, children: [_jsx(SelectTrigger, { className: "w-full", "data-depends-blocked": blockedByDependency ? '' : undefined, children: _jsx(SelectValue, { placeholder: placeholder }) }), _jsx(SelectContent, { children: options.map((opt) => (_jsx(SelectItem, { value: String(opt.id), children: _jsxs("span", { className: "flex flex-col", children: [_jsx("span", { className: "truncate", children: opt.label }), opt.description && (_jsx("span", { className: "text-muted-foreground truncate text-xs", children: opt.description }))] }) }, String(opt.id)))) })] }));
 }

package/dist/dynamic-select-field.d.ts

@@ -1,5 +1,11 @@
 import { type ResolvedOption } from './use-options-resolver';
 import type { ActionFieldDef } from './types';
+/**
+ * Default hint shown when a cascading picker's depended-on field is still
+ * empty. Domain-neutral on purpose; a caller may override it per field via
+ * `dependsHint`.
+ */
+export declare const DEFAULT_DEPENDS_HINT = "Selecciona primero el campo del que depende";
 /**
  * Small square thumbnail for an option's `image`. Falls back to a neutral
  * placeholder icon when the option has no image so rows/triggers stay aligned.
@@ -31,7 +37,17 @@ export interface DynamicSelectFieldProps {
      * a lookup (which only loads once the popover opens). Matched by id == value.
      */
     seedOption?: ResolvedOption | null;
+    /**
+     * Cascade scope: the current value of the field this picker `dependsOn`
+     * (the caller resolves it from the form context). Forwarded as
+     * `filter_value`. When the field declares a `dependsOn` and this is empty,
+     * the picker is disabled with `dependsHint` and the current selection is
+     * cleared. Changing it re-fetches and clears the selection.
+     */
+    dependsValue?: string;
+    /** Overrides the disabled-state hint shown while `dependsValue` is empty. */
+    dependsHint?: string;
 }
-export declare function DynamicSelectField({ field, value, onChange, seedOption }: DynamicSelectFieldProps): import("react").JSX.Element;
+export declare function DynamicSelectField({ field, value, onChange, seedOption, dependsValue, dependsHint, }: DynamicSelectFieldProps): import("react").JSX.Element;
 export default DynamicSelectField;
 //# sourceMappingURL=dynamic-select-field.d.ts.map

package/dist/dynamic-select-field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-select-field.d.ts","sourceRoot":"","sources":["../src/dynamic-select-field.tsx"],"names":[],"mappings":"AAuCA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAEhF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE7C;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EAAE,KAAK,EAAE,IAAS,EAAE,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,+BA4BzF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,EACvB,MAAM,EACN,IAAS,GACZ,EAAE;IACC,MAAM,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC,GAAG,IAAI,CAAA;IAChE,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB,sCAwBA;AAqBD,MAAM,WAAW,uBAAuB;IACpC,KAAK,EAAE,cAAc,CAAA;IACrB,KAAK,EAAE,GAAG,CAAA;IACV,QAAQ,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,CAAA;IAC1B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI,CAAA;CACrC;AAED,wBAAgB,kBAAkB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,uBAAuB,+BA2KjG;AAED,eAAe,kBAAkB,CAAA"}
+{"version":3,"file":"dynamic-select-field.d.ts","sourceRoot":"","sources":["../src/dynamic-select-field.tsx"],"names":[],"mappings":"AAuCA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAEhF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE7C;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,gDAAgD,CAAA;AAEjF;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EAAE,KAAK,EAAE,IAAS,EAAE,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,+BA4BzF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,EACvB,MAAM,EACN,IAAS,GACZ,EAAE;IACC,MAAM,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC,GAAG,IAAI,CAAA;IAChE,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB,sCAwBA;AAqBD,MAAM,WAAW,uBAAuB;IACpC,KAAK,EAAE,cAAc,CAAA;IACrB,KAAK,EAAE,GAAG,CAAA;IACV,QAAQ,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,CAAA;IAC1B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI,CAAA;IAClC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,wBAAgB,kBAAkB,CAAC,EAC/B,KAAK,EACL,KAAK,EACL,QAAQ,EACR,UAAU,EACV,YAAY,EACZ,WAAW,GACd,EAAE,uBAAuB,+BA4MzB;AAED,eAAe,kBAAkB,CAAA"}