@asteby/metacore-runtime-react 18.17.3 → 18.19.0

package/src/dynamic-form-schema.ts

@@ -2,7 +2,7 @@
 // callers (and unit tests) can use the zod schema without pulling in React or
 // metacore-ui primitives.
 import { z, type ZodTypeAny } from 'zod'
-import type { ActionFieldDef, FieldValidation } from './types'
+import type { ActionFieldDef, FieldValidation, FieldOptionsConfig } from './types'
 import { resolveValidatorToken } from './use-org-config-bridge'
 
 /**
@@ -252,6 +252,77 @@ export function fieldHasRef(field: ActionFieldDef): boolean {
     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: ActionFieldDef): string | undefined {
+    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: ActionFieldDef,
+    formValues?: Record<string, any> | null,
+    rowValues?: Record<string, any> | null,
+): string {
+    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: ActionFieldDef): FieldOptionsConfig | undefined {
+    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: ActionFieldDef): {
+    endpoint?: string
+    ref?: string
+    fieldKey: string
+} {
+    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/src/dynamic-line-items.tsx

@@ -18,6 +18,7 @@ import {
     SelectTrigger,
     SelectValue,
 } from '@asteby/metacore-ui/primitives'
+import { useEffect, useRef } from 'react'
 import { Plus, Trash2, Check } from 'lucide-react'
 import type { ActionFieldDef } from './types'
 import {
@@ -26,8 +27,12 @@ import {
     computeLineItemTotals,
     evaluateBalance,
     toNumber,
+    getDependsOn,
+    resolveDependsValue,
+    getOptionsConfig,
+    resolveOptionsSource,
 } from './dynamic-form-schema'
-import { DynamicSelectField } from './dynamic-select-field'
+import { DynamicSelectField, DEFAULT_DEPENDS_HINT } from './dynamic-select-field'
 import { useOptionsResolver, type ResolvedOption } from './use-options-resolver'
 
 export interface DynamicLineItemsProps {
@@ -35,6 +40,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>
 }
 
 const fmtNumber = (n: number): string =>
@@ -53,7 +64,7 @@ function emptyRow(itemFields: ActionFieldDef[]): Record<string, any> {
     return row
 }
 
-export function DynamicLineItems({ field, value, onChange, disabled = false }: DynamicLineItemsProps) {
+export function DynamicLineItems({ field, value, onChange, disabled = false, formValues }: DynamicLineItemsProps) {
     const itemFields = getItemFields(field)
     const rows: any[] = Array.isArray(value) ? value : []
 
@@ -137,6 +148,8 @@ export function DynamicLineItems({ field, value, onChange, disabled = false }: D
                                             value={row?.[col.key]}
                                             onChange={(v: any) => handleCell(idx, col.key, v)}
                                             disabled={disabled}
+                                            formValues={formValues}
+                                            rowValues={row}
                                         />
                                     </td>
                                 ))}
@@ -234,21 +247,39 @@ interface CellRendererProps {
     value: any
     onChange: (v: any) => void
     disabled?: boolean
+    /** Header form values — for resolving a cell's `dependsOn` to a header field. */
+    formValues?: Record<string, any>
+    /** This row's values — for resolving a cell's `dependsOn` to a sibling cell. */
+    rowValues?: Record<string, any>
 }
 
 // Per-cell widget. Mirrors the flat FieldRenderer in dynamic-form.tsx but
 // 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 }: CellRendererProps) {
+function CellRenderer({ field, value, onChange, disabled, formValues, rowValues }: CellRendererProps) {
     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 <DynamicSelectField field={field} value={value} onChange={onChange} />
+        return <DynamicSelectField field={field} value={value} onChange={onChange} dependsValue={dependsValue} />
     }
-    if (widget === 'select' && field.ref) {
-        return <RefCell field={field} value={value} onChange={onChange} disabled={disabled} />
+    if (widget === 'select' && (field.ref || getOptionsConfig(field)?.source)) {
+        return (
+            <RefCell
+                field={field}
+                value={value}
+                onChange={onChange}
+                disabled={disabled}
+                formValues={formValues}
+                rowValues={rowValues}
+            />
+        )
     }
     switch (widget) {
         case 'textarea':
@@ -320,21 +351,63 @@ function CellRenderer({ field, value, onChange, disabled }: CellRendererProps) {
     }
 }
 
-function RefCell({ field, value, onChange, disabled }: CellRendererProps) {
+function RefCell({ field, value, onChange, disabled, formValues, rowValues }: CellRendererProps) {
+    // 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,
     })
+
+    // Clear the selection when the parent scope changes (skip initial mount).
+    const prevScopeRef = useRef<string>(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 (
-        <Select value={value || ''} onValueChange={onChange} disabled={disabled || loading}>
-            <SelectTrigger className="w-full">
-                <SelectValue placeholder={loading ? 'Cargando…' : field.placeholder || 'Seleccionar...'} />
+        <Select
+            value={value || ''}
+            onValueChange={onChange}
+            disabled={disabled || loading || blockedByDependency}
+        >
+            <SelectTrigger className="w-full" data-depends-blocked={blockedByDependency ? '' : undefined}>
+                <SelectValue placeholder={placeholder} />
             </SelectTrigger>
             <SelectContent>
                 {options.map((opt: ResolvedOption) => (
                     <SelectItem key={String(opt.id)} value={String(opt.id)}>
-                        {opt.label}
+                        <span className="flex flex-col">
+                            <span className="truncate">{opt.label}</span>
+                            {opt.description && (
+                                <span className="text-muted-foreground truncate text-xs">
+                                    {opt.description}
+                                </span>
+                            )}
+                        </span>
                     </SelectItem>
                 ))}
             </SelectContent>

package/src/dynamic-select-field.tsx

@@ -21,7 +21,7 @@
 // in a fetched page (we match by id against loaded options, else show the raw
 // value). A dedicated `?ids=` lookup is a follow-up; create flows — the common
 // case — start empty and never hit this.
-import { useEffect, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import {
     Button,
     Command,
@@ -38,9 +38,16 @@ import { Check, ChevronsUpDown, ImageIcon, Loader2, Plus } from 'lucide-react'
 import { resolveColorCss } from '@asteby/metacore-ui/lib'
 import { DynamicIcon } from './dynamic-icon'
 import { useOptionsResolver, type ResolvedOption } from './use-options-resolver'
-import { getFieldRef } from './dynamic-form-schema'
+import { getDependsOn, getFieldRef, resolveOptionsSource } from './dynamic-form-schema'
 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 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.
@@ -145,9 +152,26 @@ 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 function DynamicSelectField({ field, value, onChange, seedOption }: DynamicSelectFieldProps) {
+export function DynamicSelectField({
+    field,
+    value,
+    onChange,
+    seedOption,
+    dependsValue,
+    dependsHint,
+}: DynamicSelectFieldProps) {
     const [open, setOpen] = useState(false)
     const [search, setSearch] = useState('')
     const debounced = useDebounced(search, 250)
@@ -159,20 +183,49 @@ export function DynamicSelectField({ field, value, onChange, seedOption }: Dynam
     // for the FK target, not just camelCase `ref`.
     const fieldRef = getFieldRef(field)
 
+    // Options routing: an `optionsConfig.source` (dependent/scoped picker) wins
+    // over the field's `ref` — query the SOURCE model with `field=<value>`;
+    // otherwise keep the canonical `ref`-based resolution.
+    const source = resolveOptionsSource(field)
+
+    // Cascade: a `dependsOn` field whose value is still empty leaves this
+    // picker disabled until the parent is set. `dependsValue` is the resolved
+    // value the caller threaded from the form context.
+    const dependsOn = getDependsOn(field)
+    const scope = dependsValue ? String(dependsValue) : ''
+    const blockedByDependency = !!dependsOn && scope === ''
+
     const { options, loading } = useOptionsResolver({
         modelKey: '',
-        fieldKey: 'id',
-        ref: fieldRef,
-        // searchEndpoint only drives the URL when there's no ref — ref is the
-        // canonical, kernel-derived path and wins.
-        endpoint: fieldRef ? undefined : field.searchEndpoint,
+        fieldKey: source.fieldKey,
+        ref: source.ref,
+        // optionsConfig.source → `/options/<source>`. Else searchEndpoint only
+        // drives the URL when there's no ref — ref is the canonical,
+        // kernel-derived path and wins.
+        endpoint: source.endpoint ?? (source.ref ? undefined : field.searchEndpoint),
         query: debounced,
         limit: 20,
+        // Cascade scope forwarded as filter_value (only when this field
+        // declares a dependency). Re-fetches when the parent value changes.
+        filterValue: dependsOn ? scope : undefined,
         // Don't fetch until the popover opens (and keep fetching as the query
-        // changes while open).
-        enabled: open,
+        // changes while open). A picker blocked by an unset dependency never
+        // fetches.
+        enabled: open && !blockedByDependency,
     })
 
+    // When the depended-on value changes, the previously-picked option no longer
+    // belongs to the new scope, so clear the selection (skip the initial mount).
+    const prevScopeRef = useRef<string>(scope)
+    useEffect(() => {
+        if (!dependsOn) return
+        if (prevScopeRef.current !== scope) {
+            prevScopeRef.current = scope
+            setPicked(null)
+            if (value) onChange('')
+        }
+    }, [dependsOn, scope, value, onChange])
+
     // The currently-selected option, resolved either from what the user picked
     // (cached in `picked`) or from the loaded page. Drives both the trigger
     // label and its thumbnail.
@@ -225,7 +278,7 @@ export function DynamicSelectField({ field, value, onChange, seedOption }: Dynam
     // "+" off-screen — it only "fit" once a short value was selected.
     return (
         <div className="flex w-full min-w-0 items-center gap-1.5">
-            <Popover open={open} onOpenChange={setOpen}>
+            <Popover open={open && !blockedByDependency} onOpenChange={(o: boolean) => { if (!blockedByDependency) setOpen(o) }}>
             <PopoverTrigger asChild>
                 <Button
                     type="button"
@@ -233,15 +286,19 @@ export function DynamicSelectField({ field, value, onChange, seedOption }: Dynam
                     role="combobox"
                     aria-expanded={open}
                     id={field.key}
+                    disabled={blockedByDependency}
                     className="min-w-0 flex-1 justify-between font-normal"
                     data-empty={!value}
+                    data-depends-blocked={blockedByDependency ? '' : undefined}
                 >
                     <span className="flex min-w-0 flex-1 items-center gap-2 text-left">
                         {hasVisual && value ? (
                             <OptionLead option={selectedOption} size={20} />
                         ) : null}
                         <span className={'min-w-0 flex-1 truncate ' + (selectedLabel ? '' : 'text-muted-foreground')}>
-                            {selectedLabel || field.placeholder || 'Buscar…'}
+                            {blockedByDependency
+                                ? (dependsHint || DEFAULT_DEPENDS_HINT)
+                                : selectedLabel || field.placeholder || 'Buscar…'}
                         </span>
                     </span>
                     <ChevronsUpDown className="ml-2 size-4 shrink-0 opacity-50" />

package/src/index.ts

@@ -101,6 +101,12 @@ export {
     type DynamicColumnsHelpers,
 } from './dynamic-columns'
 export { humanizeToken } from './dynamic-columns-helpers'
+export {
+    CollectionCell,
+    formatScalar,
+    prettifyKey,
+    type CollectionCellProps,
+} from './collection-cell'
 export { NIL_UUID, isNilUuid, normalizeNilUuid } from './nil-uuid'
 export { DynamicRecordDialog, ViewValue } from './dialogs/dynamic-record'
 export type { DynamicRecordDialogProps, FieldDef, FieldOption, GetImageUrl } from './dialogs/dynamic-record'
@@ -163,7 +169,13 @@ export {
     resolveValidatorToken,
     type OrgConfigBridge,
 } from './use-org-config-bridge'
-export { registerValidator } from './dynamic-form-schema'
+export {
+    registerValidator,
+    getDependsOn,
+    resolveDependsValue,
+    getOptionsConfig,
+    resolveOptionsSource,
+} from './dynamic-form-schema'
 export {
     ActivityValueRenderer,
     type ActivityValueRendererProps,

package/src/types.ts

@@ -231,6 +231,30 @@ export interface ActionFieldDef {
      */
     source?: string
     relation?: string
+    /**
+     * Cascade dependency: the key of ANOTHER field in the same action form
+     * (a header field or a sibling item-field) whose current value supplies
+     * this picker's `filter_value`. While the depended-on field is empty the
+     * picker is disabled with a hint; once it has a value the picker fetches
+     * options scoped by it and re-fetches whenever it changes (clearing the
+     * current selection). Without `dependsOn` the picker lists everything
+     * (retrocompat). Tolerates the snake_case `depends_on` the kernel serves.
+     */
+    dependsOn?: string
+    /** snake_case alias served by the kernel manifest for `dependsOn`. */
+    depends_on?: string
+    /**
+     * Enriched options routing the kernel serves for a dependent/scoped picker.
+     * When it carries a `source`, the picker queries that source MODEL (not the
+     * field's `ref`): URL `/options/<source>`, query field = `value` (falling
+     * back to the field's own key), and the cascade `filter_value` is the value
+     * of the `dependsOn` field. `description` is projected into the option
+     * subtitle. Tolerates the snake_case `options_config` the kernel emits.
+     * Absent → the picker keeps its `ref`-based behaviour (retrocompat).
+     */
+    optionsConfig?: FieldOptionsConfig
+    /** snake_case alias served by the kernel manifest for `optionsConfig`. */
+    options_config?: FieldOptionsConfig
     /**
      * Columns of a repeatable line-items group. Mirrors the kernel v3
      * `ActionField.item_fields` (json `item_fields`). Present on a field
@@ -298,6 +322,31 @@ export interface FieldBalanceRule {
     require_nonzero?: boolean
 }
 
+/**
+ * Enriched options-resolution config the kernel attaches to a dependent/scoped
+ * picker field (json `options_config`). When `source` is present the SDK queries
+ * the source model instead of the field's `ref`. All keys are snake_case as the
+ * kernel serves them; the SDK reads them as-is via `getOptionsConfig`.
+ */
+export interface FieldOptionsConfig {
+    /** Discriminator the kernel sets (e.g. `'dynamic'`). Informational. */
+    type?: string
+    /** Source MODEL the candidates come from → URL `/options/<source>`. */
+    source?: string
+    /** Column of `source` compared against the cascade `filter_value`. */
+    filter_by?: string
+    /** Column of `source` used as the option value → query `?field=<value>`. */
+    value?: string
+    /** Related model used to resolve the option label by id (host-side enrich). */
+    label_ref?: string
+    /** Column of `source` projected into `option.description` (e.g. qty). */
+    description?: string
+    /** Optional ordering column. */
+    order_by?: string
+    /** Optional column projected into `option.image`. */
+    image?: string
+}
+
 export interface ActionDefinition {
     key: string
     name: string

package/src/use-options-resolver.ts

@@ -58,6 +58,15 @@ export interface UseOptionsResolverArgs {
      * server returns the first page unfiltered.
      */
     query?: string
+    /**
+     * Cascade scope forwarded as `?filter_value=`. Set by a dependent picker
+     * from the current value of the field it `dependsOn` (e.g. a product
+     * picker scoped to the header's `source_warehouse_id`). When empty/undefined
+     * the param is omitted (no scope — the picker lists everything). Changing it
+     * re-fetches; an empty string is treated as "not set" so a cleared parent
+     * does not query for the empty-string scope.
+     */
+    filterValue?: string
     /**
      * Server-side pagination cap. Defaults to 50 (kernel
      * DefaultOptionsLimit) if omitted.
@@ -105,6 +114,7 @@ export function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsReso
         limit,
         enabled = true,
         endpoint,
+        filterValue,
     } = args
 
     const api = useApi()
@@ -159,6 +169,10 @@ export function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsReso
         const params: Record<string, string | number> = { field: effectiveField }
         if (query) params.q = query
         if (typeof limit === 'number' && limit > 0) params.limit = limit
+        // Cascade scope: a dependent picker passes the value of the field it
+        // `dependsOn`. Skip empty strings so a cleared parent omits the param
+        // (no scope) rather than querying for the empty-string filter_value.
+        if (filterValue) params.filter_value = filterValue
 
         api.get(url, { params, signal: controller.signal })
             .then((res) => {
@@ -200,7 +214,7 @@ export function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsReso
         return () => {
             controller.abort()
         }
-    }, [api, url, effectiveField, query, limit, enabled, refreshKey])
+    }, [api, url, effectiveField, query, limit, enabled, filterValue, refreshKey])
 
     return {
         options,