@asteby/metacore-runtime-react 37.0.2 → 37.0.4

package/src/dialogs/dynamic-record.tsx

@@ -9,7 +9,7 @@
 // flows through <ApiProvider> from runtime-react. Host-specific runtime values —
 // the image-url resolver and the org IANA timezone — are passed as props so the
 // SDK stays transport- and host-agnostic.
-import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react'
+import { createContext, useCallback, useContext, useEffect, useId, useRef, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import type { ModelSchema } from './types'
 
@@ -53,7 +53,7 @@ import { es } from 'date-fns/locale'
 import { ExternalLink, Loader2, CalendarIcon, ChevronDown, Check, Upload, X as XIcon, ScanLine } from 'lucide-react'
 import { BarcodeScanner } from '../barcode-scanner'
 import { useApi } from '../api-context'
-import { toastServerError, extractFieldErrors, localizeFieldIssue } from '../server-error'
+import { toastServerError, extractFieldErrors, localizeFieldIssue, localizeFieldErrorMap } from '../server-error'
 import { DynamicSelectField, OptionLead, OptionThumb } from '../dynamic-select-field'
 import { DynamicRelations } from '../dynamic-relations'
 import { useOptionsResolver, type ResolvedOption } from '../use-options-resolver'
@@ -64,6 +64,7 @@ import { FieldSection, WizardProgress } from '../form-layout-ui'
 import { FieldCell } from '../field-grid'
 import { isNilUuid, normalizeNilUuid } from '../nil-uuid'
 import { normalizeRefFieldsForSubmit } from './normalize-submit'
+import { validateValues, bagHasErrors } from '../validator'
 import { DynamicIcon, isLucideIconName } from '../dynamic-icon'
 import { IconPickerField } from '../icon-picker-field'
 import { humanizeToken } from '../dynamic-columns-helpers'
@@ -224,6 +225,12 @@ export interface DynamicRecordDialogProps {
      * lets it close while the depth lock is held.
      */
     nestedInlineCreateSelf?: boolean
+    /**
+     * Fields merged into the modal schema after load (by key). Existing keys are
+     * shallow-merged; missing keys are prepended. Hosts use this to inject
+     * required scope fields (e.g. branch_id) omitted from compiled DefineModal.
+     */
+    ensureFields?: FieldDef[]
     mode: 'view' | 'edit' | 'create'
     model: string
     recordId?: string | null
@@ -567,10 +574,26 @@ export function stripHiddenFieldValues(
     return out
 }
 
+function applyEnsureFields(meta: ModalMetadata | null | undefined, ensureFields?: FieldDef[]): ModalMetadata | null {
+    if (!meta) return meta ?? null
+    if (!ensureFields?.length) return meta
+    const fields = Array.isArray(meta.fields) ? [...meta.fields] : []
+    for (const ensure of ensureFields) {
+        const idx = fields.findIndex((f) => f?.key === ensure.key)
+        if (idx >= 0) {
+            fields[idx] = { ...fields[idx], ...ensure }
+        } else {
+            fields.unshift(ensure)
+        }
+    }
+    return { ...meta, fields }
+}
+
 export function DynamicRecordDialog({
     open,
     onOpenChange,
     nestedInlineCreateSelf,
+    ensureFields,
     mode,
     model,
     recordId,
@@ -602,6 +625,9 @@ export function DynamicRecordDialog({
     // inline under each input; populated from a 422 `errors` map or the client
     // required-field check, cleared per-field on change and wholesale on reopen.
     const [fieldErrors, setFieldErrors] = useState<Record<string, string>>({})
+    // Unique form id per dialog instance — nested create must not share
+    // id={formId} or the child footer submits the parent.
+    const formId = useId()
     const [loading, setLoading] = useState(false)
     const [saving, setSaving] = useState(false)
     const [deleting, setDeleting] = useState(false)
@@ -663,6 +689,7 @@ export function DynamicRecordDialog({
                     if (cancelled) return
                     meta = metaRes.data?.data ?? metaRes.data
                 }
+                meta = applyEnsureFields(meta, ensureFields)
                 setModalMeta(meta)
 
                 if (isCreate) {
@@ -710,7 +737,7 @@ export function DynamicRecordDialog({
     // initialRecord intentionally omitted: the row identity is captured per open
     // via recordId; re-seeding mid-open would clobber edits.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [open, recordId, model, endpoint, isCreate, schema])
+    }, [open, recordId, model, endpoint, isCreate, schema, ensureFields])
 
     // Reset when closed
     useEffect(() => {
@@ -807,7 +834,17 @@ export function DynamicRecordDialog({
                 next[key] = localizeFieldIssue(issues[0], labelForKey(key), t)
             }
             setFieldErrors(next)
-            toast.error(t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }))
+            const visibleKeys = new Set(
+                filterVisibleFields(modalMeta?.fields ?? [], mode, formValues).map(f => f.key),
+            )
+            const orphans = Object.entries(next).filter(([k]) => !visibleKeys.has(k))
+            const description = orphans.length
+                ? orphans.map(([k, msg]) => `${labelForKey(k)}: ${msg}`).join(' · ')
+                : undefined
+            toast.error(
+                t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }),
+                description ? { description } : undefined,
+            )
             return
         }
         toastServerError(err, { t, fallback: t('dynamic.save_error', { defaultValue: 'No se pudo guardar' }) })
@@ -818,20 +855,24 @@ export function DynamicRecordDialog({
         if (!modalMeta) return
 
         if (isEditable) {
-            // Collect ALL missing required fields (not just the first) and mark
-            // each inline instead of a single toast. Only CURRENTLY-VISIBLE
-            // fields are gated: a field hidden by its `visible_when` predicate
-            // must not block submit even when it is declared required (matching
-            // the render, which drops it via the same filter).
-            const missing: Record<string, string> = {}
-            for (const field of filterVisibleFields(modalMeta.fields, mode, formValues)) {
-                if (field.required && !formValues[field.key] && formValues[field.key] !== 0 && formValues[field.key] !== false) {
-                    missing[field.key] = localizeFieldIssue({ code: 'required' }, field.label, t)
-                }
-            }
-            if (Object.keys(missing).length) {
-                setFieldErrors(missing)
-                toast.error(t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }))
+            // Laravel-style: collect every issue from the shared validator
+            // (required + rule strings / min/max / email…) on visible fields only.
+            const visible = filterVisibleFields(modalMeta.fields, mode, formValues)
+            const bag = validateValues(visible as ActionFieldDef[], formValues)
+            if (bagHasErrors(bag)) {
+                const labels: Record<string, string> = {}
+                for (const f of visible) labels[f.key] = f.label
+                const next = localizeFieldErrorMap(bag, t, { labels })
+                setFieldErrors(next)
+                const visibleKeys = new Set(visible.map(f => f.key))
+                const orphans = Object.entries(next).filter(([k]) => !visibleKeys.has(k))
+                const description = orphans.length
+                    ? orphans.map(([k, msg]) => `${labelForKey(k)}: ${msg}`).join(' · ')
+                    : undefined
+                toast.error(
+                    t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }),
+                    description ? { description } : undefined,
+                )
                 return
             }
         }
@@ -973,14 +1014,12 @@ export function DynamicRecordDialog({
     // then advance. Mirrors handleSubmit's required check but scoped to the step.
     const goNextStep = () => {
         const step = groups[clampedStep]
-        const missing: Record<string, string> = {}
-        for (const field of step?.fields ?? []) {
-            if (field.required && !formValues[field.key] && formValues[field.key] !== 0 && formValues[field.key] !== false) {
-                missing[field.key] = localizeFieldIssue({ code: 'required' }, field.label, t)
-            }
-        }
-        if (Object.keys(missing).length) {
-            setFieldErrors(missing)
+        const stepFields = step?.fields ?? []
+        const bag = validateValues(stepFields as ActionFieldDef[], formValues)
+        if (bagHasErrors(bag)) {
+            const labels: Record<string, string> = {}
+            for (const f of stepFields) labels[f.key] = f.label
+            setFieldErrors(localizeFieldErrorMap(bag, t, { labels }))
             toast.error(t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }))
             return
         }
@@ -1014,7 +1053,7 @@ export function DynamicRecordDialog({
                                 cell `min-w-0` so a long select/input value can't
                                 blow the two columns past the dialog width. */}
                             <form
-                                id="dynamic-record-form"
+                                id={formId}
                                 onSubmit={handleSubmit}
                                 className="grid gap-y-4"
                             >
@@ -1124,7 +1163,7 @@ export function DynamicRecordDialog({
                         {isEditable && (!isSteps || isLastStep) && (
                             <Button
                                 type="submit"
-                                form="dynamic-record-form"
+                                form={formId}
                                 disabled={saving || loading}
                             >
                                 {saving && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
@@ -1193,7 +1232,7 @@ function FieldRow({ field, record, value, mode, onChange, error, locked }: Field
             ) : isEditReadonly ? (
                 <ReadonlyEditField field={field} value={value} />
             ) : (
-                <EditField field={field} value={value} onChange={onChange} record={record} />
+                <EditField field={field} value={value} onChange={onChange} record={record} invalid={!!error} />
             )}
 
             {error && mode !== 'view' && (
@@ -1836,13 +1875,19 @@ function JsonObjectViewValue({ value }: { value: Record<string, unknown> }) {
     )
 }
 
-export function EditField({ field, value, onChange, record }: {
+export function EditField({ field, value, onChange, record, invalid }: {
     field: FieldDef
     value: any
     onChange: (val: any) => void
     /** The full record being edited — supplies FK relation siblings + line-items. */
     record?: any
+    /** When true, paint the control with a destructive border (Laravel-style). */
+    invalid?: boolean
 }) {
+    const invalidCls = invalid
+        ? 'border-destructive ring-1 ring-destructive/30 focus-visible:ring-destructive aria-invalid:border-destructive'
+        : undefined
+
     const { t, i18n } = useTranslation()
     const editFieldImageUrl = useContext(ImageUrlContext)
     const dialogModel = useContext(RecordDialogModelContext)
@@ -1892,6 +1937,8 @@ export function EditField({ field, value, onChange, record }: {
                 onChange={(e: React.ChangeEvent<HTMLTextAreaElement>) => onChange(e.target.value)}
                 placeholder={field.placeholder}
                 rows={4}
+                aria-invalid={invalid || undefined}
+                className={invalidCls}
             />
         )
     }
@@ -1952,6 +1999,7 @@ export function EditField({ field, value, onChange, record }: {
                 // for the popover to open and fetch a page.
                 seedOption={fkSeedOption(field, value, record)}
                 hideCreate={hideSelfCreate}
+                invalid={invalid}
             />
         )
     }
@@ -1967,7 +2015,7 @@ export function EditField({ field, value, onChange, record }: {
     if (field.type === 'select' && field.options?.length) {
         return (
             <Select value={String(value ?? '')} onValueChange={onChange}>
-                <SelectTrigger className="w-full">
+                <SelectTrigger className={cn("w-full", invalidCls)} aria-invalid={invalid || undefined}>
                     <SelectValue placeholder="Seleccionar..." />
                 </SelectTrigger>
                 <SelectContent>
@@ -2043,7 +2091,7 @@ export function EditField({ field, value, onChange, record }: {
             ? 'email'
             : 'text'
 
-    return <ScannableRecordInput field={field} value={value} onChange={onChange} inputType={inputType} />
+    return <ScannableRecordInput field={field} value={value} onChange={onChange} inputType={inputType} invalid={invalid} className={invalidCls} />
 }
 
 /**
@@ -2062,11 +2110,15 @@ function ScannableRecordInput({
     value,
     onChange,
     inputType,
+    invalid,
+    className,
 }: {
     field: FieldDef
     value: any
     onChange: (val: any) => void
     inputType: string
+    invalid?: boolean
+    className?: string
 }) {
     const [scanOpen, setScanOpen] = useState(false)
     // El botón de escaneo aparece siempre que el campo declara `scan` (como el
@@ -2086,6 +2138,8 @@ function ScannableRecordInput({
                 )
             }
             placeholder={field.placeholder}
+            aria-invalid={invalid || undefined}
+            className={className}
         />
     )
     if (!scanEnabled) return input

package/src/dynamic-form-schema.ts

@@ -382,6 +382,87 @@ export function evaluateVisibleWhen(
     return true
 }
 
+/**
+ * Strip a DynamicTable / URL filter token down to the comparable scalar the
+ * kernel `visible_when.equals` / `.in` predicates expect.
+ *
+ * `eq:customer` → `customer`, bare `customer` stays, `in:a,b` keeps the raw
+ * multi-value (list-scope only gates on known single-eq scopes today).
+ */
+export function scopeValueFromFilterToken(raw: unknown): string {
+    if (raw == null) return ''
+    const s = String(raw)
+    const i = s.indexOf(':')
+    if (i <= 0) return s
+    const op = s.slice(0, i).toLowerCase()
+    const rest = s.slice(i + 1)
+    if (
+        op === 'eq' ||
+        op === 'neq' ||
+        op === 'gt' ||
+        op === 'gte' ||
+        op === 'lt' ||
+        op === 'lte' ||
+        op === 'like' ||
+        op === 'ilike' ||
+        op === 'contains'
+    ) {
+        return rest
+    }
+    return s
+}
+
+/**
+ * Flat "known field → value" map for list/board surfaces. Built from locked
+ * `defaultFilters` (nav / branch scope) plus active `dynamicFilters`. Only
+ * fields present here are considered known — see
+ * `evaluateVisibleWhenForListScope`.
+ */
+export function buildListScopeValues(
+    defaultFilters?: Record<string, unknown> | null,
+    dynamicFilters?: Record<string, string[] | undefined> | null,
+): Record<string, string> {
+    const out: Record<string, string> = {}
+    if (defaultFilters) {
+        for (const [key, value] of Object.entries(defaultFilters)) {
+            const v = scopeValueFromFilterToken(value)
+            if (v !== '') out[key] = v
+        }
+    }
+    if (dynamicFilters) {
+        for (const [key, values] of Object.entries(dynamicFilters)) {
+            if (defaultFilters && key in defaultFilters) continue
+            if (!values || values.length !== 1) continue
+            const v = scopeValueFromFilterToken(values[0])
+            if (v !== '') out[key] = v
+        }
+    }
+    return out
+}
+
+/**
+ * List/board variant of `evaluateVisibleWhen`.
+ *
+ * Forms always have a live sibling value (or ''). Lists often do not — a
+ * mixed AccountStatement table has no single `party_type`. Hiding every
+ * `visible_when` column when the governing field is unknown would wipe both
+ * Cliente and Proveedor on the unscoped view. Rule: if the governing field is
+ * not in `scope` (or is empty), keep the column; once the scope pins it
+ * (sidebar locked_scope / defaultFilters / a single-eq chip), apply the same
+ * predicate as the form.
+ */
+export function evaluateVisibleWhenForListScope(
+    cond: VisibleWhen | null | undefined,
+    scope: Record<string, any> | null | undefined,
+): boolean {
+    if (!cond || typeof cond.field !== 'string' || cond.field.trim() === '') return true
+    const key = cond.field.trim()
+    if (!scope || !(key in scope)) return true
+    const raw = scope[key]
+    if (raw == null || String(raw) === '') return true
+    return evaluateVisibleWhen(cond, scope)
+}
+
 /**
  * Reads a field's enriched options-resolution config, tolerating the camelCase
  * `optionsConfig` (authored SDK shape) and the snake_case `options_config` the

package/src/dynamic-select-field.tsx

@@ -204,6 +204,8 @@ export interface DynamicSelectFieldProps {
      * host's create modal renders them locked. Pairs with `createDefaults`.
      */
     createLockedFields?: string[]
+    /** Paint trigger with destructive border when validation failed. */
+    invalid?: boolean
 }
 
 export function DynamicSelectField({
@@ -219,6 +221,7 @@ export function DynamicSelectField({
     hideCreate = false,
     createDefaults,
     createLockedFields,
+    invalid = false,
 }: DynamicSelectFieldProps) {
     const { t } = useTranslation()
     const ph = (fallback: string) =>
@@ -398,7 +401,11 @@ export function DynamicSelectField({
                     aria-expanded={open}
                     id={field.key}
                     disabled={blockedByDependency}
-                    className="min-w-0 flex-1 justify-between font-normal"
+                    aria-invalid={invalid || undefined}
+                    className={
+                        'min-w-0 flex-1 justify-between font-normal' +
+                        (invalid ? ' border-destructive ring-1 ring-destructive/30' : '')
+                    }
                     data-empty={!value}
                     data-depends-blocked={blockedByDependency ? '' : undefined}
                 >

package/src/dynamic-table.tsx

@@ -64,20 +64,25 @@ import { toast } from 'sonner'
 import { Progress } from './dialogs/_primitives'
 import { useMetadataCache } from './metadata-cache'
 import { useApi, useCurrentBranch } from './api-context'
-import { useRealtimeDefault, useRealtimeTick } from './realtime-context'
 import type { ColumnFilterConfig, GetDynamicColumns } from './dynamic-columns-shim'
 import { defaultGetDynamicColumns, DATE_CELL_TYPES, aggregateOf, formatAggregateTotal } from './dynamic-columns'
 import { useFacetLoaders, isLongTextColumn } from './use-facet-loaders'
 import { translateOptionLabels } from './filter-chips'
 import { dedupeById, useInfiniteScrollSentinel } from './use-infinite-scroll'
 import { OptionsContext } from './options-context'
-import type { TableMetadata, ApiResponse } from './types'
+import type { TableMetadata, ApiResponse, ColumnDefinition } from './types'
 import { getSearchableColumnKeys } from './column-visibility'
 import { useDebouncedValue } from './use-debounced-value'
 import { useCan, usePermissionsActive, gateTableMetadata } from './permissions-context'
 import { useDynamicRowActions } from './dynamic-row-actions'
 import { ExportDialog } from './dialogs/export'
 import { ImportDialog } from './dialogs/import'
+import {
+    buildListScopeValues,
+    evaluateVisibleWhenForListScope,
+    getVisibleWhen,
+    scopeValueFromFilterToken,
+} from './dynamic-form-schema'
 
 // ---------------------------------------------------------------------------
 // Row-data cache (perceived performance).
@@ -197,13 +202,6 @@ export interface DynamicTableProps {
      */
     onRowClick?: (row: any) => void
     refreshTrigger?: any
-    /**
-     * Refetch when the host's realtime client reports a data event for this
-     * model (created/updated/deleted by anyone in the org, or a `resync`).
-     * Off by default; `<RealtimeProvider defaultRealtime>` turns it on for
-     * every table, and an explicit prop always wins. No-op without a client.
-     */
-    realtime?: boolean
     defaultFilters?: Record<string, any>
     extraColumns?: ColumnDef<any>[]
     /**
@@ -261,7 +259,6 @@ export function DynamicTable({
     onAction,
     onRowClick,
     refreshTrigger,
-    realtime: realtimeProp,
     defaultFilters,
     extraColumns = [],
     getDynamicColumns = defaultGetDynamicColumns,
@@ -276,13 +273,6 @@ export function DynamicTable({
     const { t, i18n } = useTranslation()
     const api = useApi()
     const currentBranch = useCurrentBranch()
-    // Realtime refetch (opt-in): a debounced counter that bumps on every
-    // DATA_EVENT for this model and rides the same deps as `refreshTrigger`.
-    const realtimeDefault = useRealtimeDefault()
-    const realtimeTick = useRealtimeTick({
-        models: [model],
-        enabled: realtimeProp ?? realtimeDefault,
-    })
 
     const prevBranchId = useRef(currentBranch?.id)
 
@@ -512,6 +502,22 @@ export function DynamicTable({
             if (values.length === 1) params.set(`f_${key}`, internalValueToUrl(values[0]))
             else params.set(`f_${key}`, `in:${values.join(',')}`)
         })
+        // Re-pin locked scope into the URL so sidebar matching + deep-links keep
+        // working after "Limpiar filtros" (those keys are not in dynamicFilters).
+        if (defaultFilters) {
+            Object.entries(defaultFilters).forEach(([key, value]) => {
+                params.set(`f_${key}`, internalValueToUrl(String(value ?? '')))
+            })
+        }
+        // Preserve f_* already in the location that we did not rebuild above.
+        // Sidebar deep-links (CxC→CxP) push f_party_type=eq:supplier before React
+        // re-renders with matching defaultFilters; without this carry-through the
+        // write effect races and strips the filter down to bare ?view=list.
+        current.forEach((value, key) => {
+            if (!key.startsWith('f_')) return
+            if (params.has(key)) return
+            params.set(key, value)
+        })
         const search = params.toString()
         // If what we'd write is semantically identical to what's already in the
         // bar (only key order / colon-encoding differ from the router's form),
@@ -695,6 +701,52 @@ export function DynamicTable({
         !hideImport && (viewMetadata?.canImport ?? Boolean(viewMetadata?.import?.columns?.length))
     const exportEnabled = !hideExport && Boolean(viewMetadata?.canExport)
 
+    const listScopeValues = useMemo(() => {
+        const base = buildListScopeValues(defaultFilters, dynamicFilters)
+        // Deep-links pin f_* in the URL before defaultFilters / nav matching
+        // catch up; adopt single-eq scope values so visible_when columns hide
+        // on first paint (CxC hides Proveedor without waiting for navFilter).
+        if (!enableUrlSync || typeof window === 'undefined') return base
+        const params = new URLSearchParams(window.location.search)
+        const fromUrl: Record<string, string> = {}
+        params.forEach((raw, key) => {
+            if (!key.startsWith('f_')) return
+            const col = key.slice(2)
+            if (!col || col in base) return
+            const v = scopeValueFromFilterToken(raw)
+            if (!v) return
+            // Multi-value / range tokens are not a single list-scope pin.
+            if (v.includes(',') || /^(in|not_in|range|gte|lte):/i.test(String(raw))) return
+            fromUrl[col] = v
+        })
+        return Object.keys(fromUrl).length === 0 ? base : { ...fromUrl, ...base }
+    }, [defaultFilters, dynamicFilters, enableUrlSync, urlSynced])
+
+    // Columns whose kernel `visible_when` fails against the known list scope
+    // (locked nav defaultFilters, single-eq chips). Host `hiddenColumns` still
+    // wins; this is the scalable path so CxC hides Proveedor without each nav
+    // item re-listing every allowed column.
+    const scopeHiddenColumns = useMemo(() => {
+        const cols = (viewMetadata?.columns ?? metadata?.columns ?? []) as ColumnDefinition[]
+        if (cols.length === 0 || Object.keys(listScopeValues).length === 0) return [] as string[]
+        const hidden: string[] = []
+        for (const col of cols) {
+            const key = col.key
+            if (!key) continue
+            if (!evaluateVisibleWhenForListScope(getVisibleWhen(col), listScopeValues)) {
+                hidden.push(key)
+            }
+        }
+        return hidden
+    }, [metadata, viewMetadata, listScopeValues])
+
+    const effectiveHiddenColumns = useMemo(() => {
+        if (scopeHiddenColumns.length === 0) return hiddenColumns
+        const set = new Set(hiddenColumns)
+        for (const k of scopeHiddenColumns) set.add(k)
+        return Array.from(set)
+    }, [hiddenColumns, scopeHiddenColumns])
+
     const buildFilterParams = useCallback(() => {
         const params: Record<string, any> = {}
         if (sorting.length > 0) {
@@ -710,9 +762,12 @@ export function DynamicTable({
             }
             // searchableKeys === [] → drop the search request entirely
         }
-        columnFilters.forEach((filter: { id: string; value: unknown }) => { params[`f_${filter.id}`] = filter.value })
-        if (defaultFilters) Object.entries(defaultFilters).forEach(([key, value]) => { params[`f_${key}`] = value })
+        columnFilters.forEach((filter: { id: string; value: unknown }) => {
+            if (defaultFilters && filter.id in defaultFilters) return
+            params[`f_${filter.id}`] = filter.value
+        })
         Object.entries(dynamicFilters).forEach(([key, values]) => {
+            if (defaultFilters && key in defaultFilters) return
             if (values.length === 0) return
             const gteVal = values.find(v => v.startsWith('GTE:'))
             const lteVal = values.find(v => v.startsWith('LTE:'))
@@ -725,6 +780,8 @@ export function DynamicTable({
             if (values.length === 1) params[`f_${key}`] = values[0]
             else params[`f_${key}`] = `IN:${values.join(',')}`
         })
+        // Locked scope last so it always wins over stale dynamic/column filters.
+        if (defaultFilters) Object.entries(defaultFilters).forEach(([key, value]) => { params[`f_${key}`] = value })
         if (dateRange?.from) {
             const startDate = format(dateRange.from, 'yyyy-MM-dd')
             const endDate = dateRange.to ? format(dateRange.to, 'yyyy-MM-dd') : startDate
@@ -770,8 +827,7 @@ export function DynamicTable({
         } finally {
             setLoadingData(false)
         }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [model, metadata, pagination, buildFilterParams, refreshTrigger, realtimeTick, endpoint, currentBranch?.id, api, enableUrlSync])
+    }, [model, metadata, pagination, buildFilterParams, refreshTrigger, endpoint, currentBranch?.id, api, enableUrlSync])
 
     // Columns whose metadata opts into a footer total (display_config.aggregate
     // → styleConfig.aggregate). When empty, no footer row is rendered and no
@@ -940,9 +996,8 @@ export function DynamicTable({
         // matching the classic path (fetchData carries refreshTrigger in its
         // deps). Without it the comment above lied: infinite lists silently
         // failed to reload after a create ("a veces no recarga la tabla").
-        // realtimeTick plays the same role for data events (see the `realtime` prop).
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [infiniteScroll, metadata, filterSignature, refreshTrigger, realtimeTick])
+    }, [infiniteScroll, metadata, filterSignature, refreshTrigger])
 
     const handleRefresh = useCallback(() => {
         // Infinite mode owns its own list: refresh reloads page 1 and drops the
@@ -997,9 +1052,11 @@ export function DynamicTable({
     }
 
     const handleDynamicFilterChange = useCallback((filterKey: string, values: string[]) => {
+        // Locked scope (nav / branch defaultFilters) cannot be changed from the UI.
+        if (defaultFilters && filterKey in defaultFilters) return
         setDynamicFilters((prev: Record<string, string[]>) => ({ ...prev, [filterKey]: values }))
         setPagination((prev: PaginationState) => ({ ...prev, pageIndex: 0 }))
-    }, [])
+    }, [defaultFilters])
 
     // Same facet loader machinery the board uses, so a text column filters
     // identically in the table header and the kanban Sheet (the host's
@@ -1026,6 +1083,9 @@ export function DynamicTable({
         // `filterable: true` — keeps the kernel API minimal (one flag on the
         // column) while still rendering the FilterableColumnHeader.
         for (const f of metadata.filters ?? []) {
+            const filterCol = f.column || f.key
+            if (defaultFilters && filterCol in defaultFilters) continue
+            if (effectiveHiddenColumns.includes(filterCol)) continue
             let fType = f.type as ColumnFilterConfig['filterType']
             let options: { label: string; value: string; icon?: string; color?: string }[] = []
             if (f.options && f.options.length > 0) {
@@ -1069,6 +1129,8 @@ export function DynamicTable({
         }
         for (const c of metadata.columns ?? []) {
             if (!c.filterable || map.has(c.key)) continue
+            if (defaultFilters && c.key in defaultFilters) continue
+            if (effectiveHiddenColumns.includes(c.key)) continue
             const hasStaticOptions = (c.options?.length ?? 0) > 0
             const hasEndpoint = !!c.searchEndpoint
             const isRelation = !!c.ref || c.filterType === 'dynamic_select'
@@ -1133,7 +1195,7 @@ export function DynamicTable({
             })
         }
         return map
-    }, [metadata, filterOptionsMap, dynamicFilters, handleDynamicFilterChange, facetsBase, getFacetLoader, facetOptions, t])
+    }, [metadata, filterOptionsMap, dynamicFilters, handleDynamicFilterChange, facetsBase, getFacetLoader, facetOptions, t, defaultFilters, effectiveHiddenColumns])
 
     // Prewarm every facet field once the configs settle, so a text column's
     // header filter opens instantly with values + counts (same as the kanban).
@@ -1170,11 +1232,11 @@ export function DynamicTable({
             return actions === viewMetadata.actions ? viewMetadata : { ...viewMetadata, actions }
         })()
         const baseColumns = getDynamicColumns(rowMetadata, handleInternalAction, t, i18n.language, columnFilterConfigs, timeZone, currency)
-        const filteredBase = baseColumns.filter((col: ColumnDef<any>) => !hiddenColumns.includes(col.id as string))
+        const filteredBase = baseColumns.filter((col: ColumnDef<any>) => !effectiveHiddenColumns.includes(col.id as string))
         const actionsCol = filteredBase.find((c: ColumnDef<any>) => c.id === 'actions')
         const otherCols = filteredBase.filter((c: ColumnDef<any>) => c.id !== 'actions')
         return [...otherCols, ...extraColumns, ...(actionsCol ? [actionsCol] : [])]
-    }, [viewMetadata, handleInternalAction, hiddenColumns, allowedActionKeys, extraColumns, t, i18n.language, columnFilterConfigs, getDynamicColumns, timeZone, currency])
+    }, [viewMetadata, handleInternalAction, effectiveHiddenColumns, allowedActionKeys, extraColumns, t, i18n.language, columnFilterConfigs, getDynamicColumns, timeZone, currency])
 
     const filters = useMemo(() => [], [])
 

package/src/index.ts

@@ -375,6 +375,9 @@ export {
     resolveOptionsSource,
     getVisibleWhen,
     evaluateVisibleWhen,
+    scopeValueFromFilterToken,
+    buildListScopeValues,
+    evaluateVisibleWhenForListScope,
 } from './dynamic-form-schema'
 export {
     ActivityValueRenderer,

package/src/types.ts

@@ -337,12 +337,13 @@ export interface ColumnDefinition {
     /** snake_case alias served by the kernel for `itemFields`. */
     item_fields?: ColumnItemField[]
     /**
-     * Conditional visibility in the create/edit modal: render this field only
-     * when a sibling field's current value matches the predicate. Mirrors the
-     * kernel v3 `Column.visible_when` (projected onto the served ColumnDef).
-     * Tolerates the camelCase alias. Absent = always visible; a hidden field is
-     * skipped by the required-gate so it never blocks submit. See
-     * `evaluateVisibleWhen`.
+     * Conditional visibility (kernel v3 `Column.visible_when`):
+     *   - create/edit modal → `evaluateVisibleWhen` against live form values
+     *   - list/board → `evaluateVisibleWhenForListScope` against known filter
+     *     scope (`defaultFilters` / single-eq chips), so a locked nav scope
+     *     like `party_type=customer` hides `supplier_id` without each nav
+     *     item re-declaring a full column allowlist.
+     * Tolerates the camelCase alias. Absent = always visible.
      */
     visible_when?: VisibleWhen
     /** camelCase alias for `visible_when`. */