@asteby/metacore-runtime-react 18.17.3 → 18.18.0

package/dist/use-options-resolver.d.ts

@@ -41,6 +41,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.

package/dist/use-options-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-options-resolver.d.ts","sourceRoot":"","sources":["../src/use-options-resolver.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,cAAc;IAC3B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IACnB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,MAAM,WAAW,WAAW;IACxB,oEAAoE;IACpE,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAA;IACnC,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,sBAAsB;IACnC;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,wBAAwB;IACrC,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,IAAI,CAAA;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,wBAAwB,CAiHzF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,cAAc,CAatD"}
+{"version":3,"file":"use-options-resolver.d.ts","sourceRoot":"","sources":["../src/use-options-resolver.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,cAAc;IAC3B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IACnB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,MAAM,WAAW,WAAW;IACxB,oEAAoE;IACpE,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAA;IACnC,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,sBAAsB;IACnC;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,wBAAwB;IACrC,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,IAAI,CAAA;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,wBAAwB,CAsHzF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,cAAc,CAatD"}

package/dist/use-options-resolver.js

@@ -23,7 +23,7 @@ import { useApi } from './api-context';
  * compose this with TanStack Query in their own layer).
  */
 export function useOptionsResolver(args) {
-    const { modelKey, fieldKey, ref, query, limit, enabled = true, endpoint, } = args;
+    const { modelKey, fieldKey, ref, query, limit, enabled = true, endpoint, filterValue, } = args;
     const api = useApi();
     const [options, setOptions] = useState([]);
     const [meta, setMeta] = useState(null);
@@ -77,6 +77,11 @@ export function useOptionsResolver(args) {
             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) => {
             if (controller.signal.aborted)
@@ -117,7 +122,7 @@ export function useOptionsResolver(args) {
         return () => {
             controller.abort();
         };
-    }, [api, url, effectiveField, query, limit, enabled, refreshKey]);
+    }, [api, url, effectiveField, query, limit, enabled, filterValue, refreshKey]);
     return {
         options,
         meta,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "18.17.3",
+  "version": "18.18.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",

package/src/__tests__/dependent-options.test.tsx

@@ -0,0 +1,337 @@
+// @vitest-environment happy-dom
+//
+// Dependent (cascading) options contract:
+//   - resolveDependsValue (pure): a cell `dependsOn` resolves from the row
+//     (sibling) first, then the header form values; empty/unset → ''.
+//   - useOptionsResolver: a `filterValue` is forwarded as `&filter_value=` and
+//     re-fetches when it changes; an empty value omits the param.
+//   - DynamicLineItems → cell with `dependsOn`: the picker is disabled while the
+//     header field is empty, and once the header field has a value the options
+//     request carries that value as `filter_value` and re-fetches on change.
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, render, screen, waitFor } from '@testing-library/react'
+
+// Identity translator so any raw i18n keys surface verbatim.
+vi.mock('react-i18next', () => ({
+    useTranslation: () => ({ t: (k: string) => k }),
+}))
+
+import {
+    resolveDependsValue,
+    getDependsOn,
+    getOptionsConfig,
+    resolveOptionsSource,
+} from '../dynamic-form-schema'
+import { useOptionsResolver } from '../use-options-resolver'
+import { DynamicLineItems } from '../dynamic-line-items'
+import { ApiProvider, type ApiClient } from '../api-context'
+import type { ActionFieldDef } from '../types'
+import { useState } from 'react'
+
+afterEach(cleanup)
+
+// ---------------------------------------------------------------------------
+// Pure resolution
+// ---------------------------------------------------------------------------
+describe('getDependsOn / resolveDependsValue', () => {
+    const field = (over: Partial<ActionFieldDef>): ActionFieldDef =>
+        ({ key: 'product_id', label: 'Producto', type: 'dynamic_select', ...over })
+
+    it('reads camelCase dependsOn and snake_case depends_on', () => {
+        expect(getDependsOn(field({ dependsOn: 'wh' }))).toBe('wh')
+        expect(getDependsOn(field({ depends_on: 'wh' }))).toBe('wh')
+        expect(getDependsOn(field({}))).toBeUndefined()
+    })
+
+    it('resolves from header form values', () => {
+        const f = field({ depends_on: 'source_warehouse_id' })
+        expect(resolveDependsValue(f, { source_warehouse_id: 'W1' })).toBe('W1')
+    })
+
+    it('prefers a sibling row value over the header', () => {
+        const f = field({ dependsOn: 'warehouse_id' })
+        const out = resolveDependsValue(f, { warehouse_id: 'HEADER' }, { warehouse_id: 'ROW' })
+        expect(out).toBe('ROW')
+    })
+
+    it('falls back to header when the row value is blank', () => {
+        const f = field({ dependsOn: 'warehouse_id' })
+        const out = resolveDependsValue(f, { warehouse_id: 'HEADER' }, { warehouse_id: '' })
+        expect(out).toBe('HEADER')
+    })
+
+    it('returns empty string when the dependency is unset', () => {
+        const f = field({ dependsOn: 'warehouse_id' })
+        expect(resolveDependsValue(f, {})).toBe('')
+        expect(resolveDependsValue(field({}), { a: 1 })).toBe('')
+    })
+})
+
+describe('getOptionsConfig / resolveOptionsSource', () => {
+    const field = (over: Partial<ActionFieldDef>): ActionFieldDef =>
+        ({ key: 'product_id', label: 'Producto', type: 'dynamic_select', ...over })
+
+    it('reads camelCase optionsConfig and snake_case options_config', () => {
+        expect(getOptionsConfig(field({ optionsConfig: { source: 'stock' } }))?.source).toBe('stock')
+        expect(getOptionsConfig(field({ options_config: { source: 'stock' } }))?.source).toBe('stock')
+        expect(getOptionsConfig(field({}))).toBeUndefined()
+    })
+
+    it('routes to the source model with field=value when optionsConfig.source is present', () => {
+        const f = field({
+            ref: 'products.Product',
+            options_config: { source: 'stock', filter_by: 'warehouse_id', value: 'product_id', description: 'quantity' },
+        })
+        const out = resolveOptionsSource(f)
+        expect(out.endpoint).toBe('/options/stock')
+        expect(out.fieldKey).toBe('product_id')
+        // source wins over ref — the ref pointer is not used for routing.
+        expect(out.ref).toBeUndefined()
+    })
+
+    it('falls back to the field key when optionsConfig.value is absent', () => {
+        const f = field({ key: 'item_id', options_config: { source: 'stock' } })
+        const out = resolveOptionsSource(f)
+        expect(out.endpoint).toBe('/options/stock')
+        expect(out.fieldKey).toBe('item_id')
+    })
+
+    it('keeps ref-based resolution when there is no optionsConfig.source', () => {
+        const f = field({ ref: 'products.Product' })
+        const out = resolveOptionsSource(f)
+        expect(out.endpoint).toBeUndefined()
+        expect(out.ref).toBe('products.Product')
+        expect(out.fieldKey).toBe('id')
+    })
+})
+
+// ---------------------------------------------------------------------------
+// useOptionsResolver — filter_value forwarding + re-fetch
+// ---------------------------------------------------------------------------
+function Harness({ filterValue }: { filterValue?: string }) {
+    const { options } = useOptionsResolver({
+        modelKey: '',
+        fieldKey: 'id',
+        ref: 'products.Product',
+        filterValue,
+    })
+    return <div data-testid="count">{options.length}</div>
+}
+
+describe('useOptionsResolver filter_value', () => {
+    it('forwards a non-empty filter_value and re-fetches on change', async () => {
+        const get = vi.fn(async () => ({
+            data: { success: true, data: [{ id: '1', label: 'One' }], meta: { type: 'dynamic', count: 1 } },
+        }))
+        const client = { get } as unknown as ApiClient
+
+        const { rerender } = render(
+            <ApiProvider client={client}>
+                <Harness filterValue="W1" />
+            </ApiProvider>,
+        )
+        await waitFor(() => expect(screen.getByTestId('count').textContent).toBe('1'))
+
+        // First call carried filter_value=W1.
+        const firstParams = get.mock.calls[0][1]?.params
+        expect(firstParams.filter_value).toBe('W1')
+
+        // Change the parent value → a fresh request with the new filter_value.
+        rerender(
+            <ApiProvider client={client}>
+                <Harness filterValue="W2" />
+            </ApiProvider>,
+        )
+        await waitFor(() => expect(get.mock.calls.length).toBeGreaterThan(1))
+        const lastParams = get.mock.calls[get.mock.calls.length - 1][1]?.params
+        expect(lastParams.filter_value).toBe('W2')
+    })
+
+    it('omits filter_value when empty', async () => {
+        const get = vi.fn(async () => ({
+            data: { success: true, data: [], meta: { type: 'dynamic', count: 0 } },
+        }))
+        const client = { get } as unknown as ApiClient
+        render(
+            <ApiProvider client={client}>
+                <Harness filterValue="" />
+            </ApiProvider>,
+        )
+        await waitFor(() => expect(get).toHaveBeenCalled())
+        expect(get.mock.calls[0][1]?.params.filter_value).toBeUndefined()
+    })
+})
+
+// ---------------------------------------------------------------------------
+// DynamicLineItems — a cell that dependsOn a HEADER field
+// ---------------------------------------------------------------------------
+const lineItemsField: ActionFieldDef = {
+    key: 'items',
+    label: 'Renglones',
+    type: 'array',
+    itemFields: [
+        {
+            key: 'product_id',
+            label: 'Producto',
+            type: 'dynamic_select',
+            ref: 'products.Product',
+            // depends on the HEADER field, not a sibling row cell.
+            depends_on: 'source_warehouse_id',
+        },
+    ],
+}
+
+// Drives DynamicLineItems with one pre-existing row + a switchable header value.
+function LineItemsHost({ headerValue }: { headerValue: string }) {
+    const [rows, setRows] = useState<any[]>([{ product_id: '' }])
+    return (
+        <DynamicLineItems
+            field={lineItemsField}
+            value={rows}
+            onChange={setRows}
+            formValues={{ source_warehouse_id: headerValue }}
+        />
+    )
+}
+
+describe('DynamicLineItems cascading cell', () => {
+    it('disables the picker while the header field is empty', () => {
+        const get = vi.fn(async () => ({
+            data: { success: true, data: [], meta: { type: 'dynamic', count: 0 } },
+        }))
+        const client = { get } as unknown as ApiClient
+        render(
+            <ApiProvider client={client}>
+                <LineItemsHost headerValue="" />
+            </ApiProvider>,
+        )
+        // The combobox trigger is disabled and shows the dependency hint.
+        const trigger = screen.getByRole('combobox')
+        expect((trigger as HTMLButtonElement).disabled).toBe(true)
+        expect(trigger.getAttribute('data-depends-blocked')).toBe('')
+        // No options request fires while blocked.
+        expect(get).not.toHaveBeenCalled()
+    })
+
+    it('sends filter_value from the header field and re-fetches when it changes', async () => {
+        const get = vi.fn(async () => ({
+            data: {
+                success: true,
+                data: [{ id: 'p1', label: 'Tornillo', description: 'disp. 12' }],
+                meta: { type: 'dynamic', count: 1 },
+            },
+        }))
+        const client = { get } as unknown as ApiClient
+
+        const { rerender } = render(
+            <ApiProvider client={client}>
+                <LineItemsHost headerValue="W1" />
+            </ApiProvider>,
+        )
+
+        // Open the popover so the typeahead fetches.
+        const trigger = screen.getByRole('combobox')
+        expect((trigger as HTMLButtonElement).disabled).toBe(false)
+        await act(async () => {
+            trigger.click()
+        })
+        await waitFor(() => expect(get).toHaveBeenCalled())
+        const firstParams = get.mock.calls[0][1]?.params
+        expect(firstParams.filter_value).toBe('W1')
+
+        // Switch the header warehouse → the cell picker re-fetches scoped to W2.
+        rerender(
+            <ApiProvider client={client}>
+                <LineItemsHost headerValue="W2" />
+            </ApiProvider>,
+        )
+        await waitFor(() => {
+            const last = get.mock.calls[get.mock.calls.length - 1][1]?.params
+            expect(last.filter_value).toBe('W2')
+        })
+    })
+})
+
+// ---------------------------------------------------------------------------
+// optionsConfig.source routing — the picker queries the SOURCE model, not `ref`
+// ---------------------------------------------------------------------------
+const sourceLineItemsField: ActionFieldDef = {
+    key: 'items',
+    label: 'Renglones',
+    type: 'array',
+    itemFields: [
+        {
+            key: 'product_id',
+            label: 'Producto',
+            type: 'dynamic_select',
+            // A `ref` is present but optionsConfig.source MUST win for routing.
+            ref: 'products.Product',
+            depends_on: 'source_warehouse_id',
+            options_config: {
+                type: 'dynamic',
+                source: 'stock',
+                filter_by: 'warehouse_id',
+                value: 'product_id',
+                label_ref: 'products.Product',
+                description: 'quantity',
+            },
+        },
+    ],
+}
+
+function SourceLineItemsHost({ headerValue }: { headerValue: string }) {
+    const [rows, setRows] = useState<any[]>([{ product_id: '' }])
+    return (
+        <DynamicLineItems
+            field={sourceLineItemsField}
+            value={rows}
+            onChange={setRows}
+            formValues={{ source_warehouse_id: headerValue }}
+        />
+    )
+}
+
+describe('DynamicLineItems cell with optionsConfig.source', () => {
+    it('queries /options/<source>?field=<value>&filter_value=<dependsOn> and re-fetches on parent change', async () => {
+        const get = vi.fn(async () => ({
+            data: {
+                success: true,
+                data: [{ id: 'p1', label: 'Tornillo', description: 'disp. 12' }],
+                meta: { type: 'dynamic', count: 1 },
+            },
+        }))
+        const client = { get } as unknown as ApiClient
+
+        const { rerender } = render(
+            <ApiProvider client={client}>
+                <SourceLineItemsHost headerValue="W1" />
+            </ApiProvider>,
+        )
+
+        const trigger = screen.getByRole('combobox')
+        expect((trigger as HTMLButtonElement).disabled).toBe(false)
+        await act(async () => {
+            trigger.click()
+        })
+        await waitFor(() => expect(get).toHaveBeenCalled())
+
+        // URL hits the SOURCE model, not the `ref`.
+        const [firstUrl, firstCfg] = get.mock.calls[0]
+        expect(firstUrl).toBe('/options/stock')
+        expect(firstCfg?.params.field).toBe('product_id')
+        expect(firstCfg?.params.filter_value).toBe('W1')
+
+        // Parent change → re-fetch, still routed to the source, new filter_value.
+        rerender(
+            <ApiProvider client={client}>
+                <SourceLineItemsHost headerValue="W2" />
+            </ApiProvider>,
+        )
+        await waitFor(() => {
+            const [url, cfg] = get.mock.calls[get.mock.calls.length - 1]
+            expect(url).toBe('/options/stock')
+            expect(cfg?.params.field).toBe('product_id')
+            expect(cfg?.params.filter_value).toBe('W2')
+        })
+    })
+})

package/src/action-modal-dispatcher.tsx

@@ -42,7 +42,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'
 import type { ActionFieldDef } from './types'
 // Canonical registry lives in @asteby/metacore-sdk
 import {
@@ -292,7 +292,7 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
                                     {field.label}
                                     {field.required && <span className="text-red-500 ml-1">*</span>}
                                 </Label>
-                                {renderField(field, formData[field.key], (v: any) => updateField(field.key, v))}
+                                {renderField(field, formData[field.key], (v: any) => updateField(field.key, v), formData)}
                             </div>
                         )
                     })}
@@ -319,10 +319,16 @@ function renderField(
     field: ActionFieldDef,
     value: any,
     onChange: (value: any) => void,
+    // 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?: Record<string, any>,
 ) {
     // 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 <DynamicLineItems field={field} value={value} onChange={onChange} />
+        return <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
@@ -330,7 +336,12 @@ function renderField(
     // dropped `dynamic_select` to a plain text input.
     const widget = resolveWidget(field)
     if (widget === 'dynamic_select') {
-        return <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 <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/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`).