@asteby/metacore-runtime-react 47.0.0 → 47.1.0

package/src/audit-info.tsx

@@ -0,0 +1,219 @@
+/**
+ * audit-info.tsx
+ *
+ * <AuditInfo> — discreet "when and who" footer for a record: created, modified
+ * and (if tombstoned) deleted, each with the actor and a relative + absolute
+ * date. Driven only by the kernel's `TableMetadata.audit` (column names) and
+ * the record row — manifests declare nothing.
+ *
+ * Actor resolution (no extra requests), in order:
+ *   1. the host's `resolveActor(id)` when it returns a name;
+ *   2. the record's expanded sibling (`created_by_id` → `row.created_by`,
+ *      `{ label | name | title }` or a plain string);
+ *   3. the system actor id → "Sistema" / "System";
+ *   4. a short id (first 8 chars) — never a long uuid.
+ *
+ * Renders nothing when `audit` is absent or the record has none of its values.
+ */
+import * as React from 'react'
+import { useTranslation } from 'react-i18next'
+import { formatDistanceToNow } from 'date-fns'
+import { es, enUS } from 'date-fns/locale'
+import { ChevronDown, ChevronRight, History } from 'lucide-react'
+import { cn } from '@asteby/metacore-ui/lib'
+import { formatDateCell } from './dynamic-columns'
+import { objectLabel } from './dynamic-relation-helpers'
+import { isNilUuid } from './nil-uuid'
+import { useTimeZone } from './org-runtime-context'
+import type { AuditMeta } from './types'
+
+/** The kernel's actor for unattended work (schedules, webhooks, connectors). */
+export const SYSTEM_ACTOR_ID = '00000000-0000-0000-0000-000000000001'
+
+const AUDIT_KEYS: (keyof AuditMeta)[] = [
+    'created_at',
+    'created_by',
+    'updated_at',
+    'updated_by',
+    'deleted_at',
+    'deleted_by',
+]
+
+/**
+ * Defensive reader for the served `audit` block: keeps only known keys whose
+ * value is a non-empty string; returns `undefined` when nothing usable remains.
+ */
+export function readAuditMeta(raw: unknown): AuditMeta | undefined {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined
+    const src = raw as Record<string, unknown>
+    const out: AuditMeta = {}
+    for (const k of AUDIT_KEYS) {
+        const v = src[k]
+        if (typeof v === 'string' && v.trim() !== '') out[k] = v
+    }
+    return Object.keys(out).length ? out : undefined
+}
+
+export interface AuditActor {
+    /** Display text. */
+    name: string
+    /** True when the name is a real resolved label (not a short id). */
+    resolved: boolean
+}
+
+/** Resolves the actor stored in `row[idColumn]` to something human. */
+export function resolveAuditActor(
+    row: Record<string, unknown>,
+    idColumn: string | undefined,
+    opts: { resolveActor?: (id: string) => string | undefined; systemLabel: string },
+): AuditActor | null {
+    if (!idColumn) return null
+    const raw = row[idColumn]
+    // The column itself may already be an expanded object.
+    const own = objectLabel(raw)
+    const id = typeof raw === 'string' ? raw.trim() : ''
+    if (!own && (!id || isNilUuid(id))) return null
+    if (id.toLowerCase() === SYSTEM_ACTOR_ID) return { name: opts.systemLabel, resolved: true }
+    if (id) {
+        const fromHost = opts.resolveActor?.(id)
+        if (fromHost) return { name: fromHost, resolved: true }
+    }
+    if (own) return { name: own, resolved: true }
+    const base = idColumn.endsWith('_id') ? idColumn.slice(0, -3) : idColumn
+    const sibling = base === idColumn ? undefined : row[base]
+    const siblingName =
+        objectLabel(sibling) ?? (typeof sibling === 'string' && sibling.trim() !== '' ? sibling : undefined)
+    if (siblingName) return { name: siblingName, resolved: true }
+    return { name: id.length > 8 ? id.slice(0, 8) : id, resolved: false }
+}
+
+const COPY = {
+    es: {
+        title: 'Historial del registro',
+        created: 'Creado por {{who}}',
+        updated: 'Modificado por {{who}}',
+        deleted: 'Eliminado por {{who}}',
+        createdAt: 'Creado',
+        updatedAt: 'Modificado',
+        deletedAt: 'Eliminado',
+        system: 'Sistema',
+    },
+    en: {
+        title: 'Record history',
+        created: 'Created by {{who}}',
+        updated: 'Modified by {{who}}',
+        deleted: 'Deleted by {{who}}',
+        createdAt: 'Created',
+        updatedAt: 'Modified',
+        deletedAt: 'Deleted',
+        system: 'System',
+    },
+} as const
+
+export interface AuditInfoProps {
+    /** The record row (keys are the column names `audit` points at). */
+    record: Record<string, unknown> | null | undefined
+    /** `TableMetadata.audit`. Absent → renders nothing. */
+    audit: AuditMeta | null | undefined
+    /** Optional host resolver uuid → display name (e.g. from a users cache). */
+    resolveActor?: (id: string) => string | undefined
+    /** IANA timezone; defaults to the org runtime timezone. */
+    timeZone?: string
+    /** BCP-47 locale; defaults to the i18n language. */
+    locale?: string
+    /** Start expanded. Default: collapsed. */
+    defaultOpen?: boolean
+    className?: string
+}
+
+interface Line {
+    key: string
+    text: string
+    absolute: string
+    title?: string
+    relative: string
+}
+
+export function AuditInfo({
+    record,
+    audit,
+    resolveActor,
+    timeZone,
+    locale,
+    defaultOpen = false,
+    className,
+}: AuditInfoProps) {
+    const { t, i18n } = useTranslation()
+    const ctxTz = useTimeZone()
+    const [open, setOpen] = React.useState(defaultOpen)
+
+    const meta = readAuditMeta(audit)
+    if (!meta || !record) return null
+
+    const lang = (locale || i18n?.language || 'es').toLowerCase().startsWith('en') ? 'en' : 'es'
+    const copy = COPY[lang]
+    const dfLocale = lang === 'en' ? enUS : es
+    const tz = timeZone ?? ctxTz
+    const tt = (key: keyof typeof copy, vars?: Record<string, string>) =>
+        t(`audit.${key}`, { defaultValue: copy[key], ...vars }) as string
+
+    const build = (
+        key: string,
+        atCol: string | undefined,
+        byCol: string | undefined,
+        whoKey: 'created' | 'updated' | 'deleted',
+        whenKey: 'createdAt' | 'updatedAt' | 'deletedAt',
+    ): Line | null => {
+        const f = atCol ? formatDateCell(record[atCol], undefined, dfLocale, tz) : null
+        if (!f) return null
+        const actor = resolveAuditActor(record, byCol, { resolveActor, systemLabel: tt('system') })
+        const date = new Date(record[atCol as string] as string)
+        const relative = formatDistanceToNow(date, { addSuffix: true, locale: dfLocale })
+        return {
+            key,
+            text: actor ? tt(whoKey, { who: actor.name }) : tt(whenKey),
+            absolute: f.display,
+            title: f.title,
+            relative,
+        }
+    }
+
+    const lines = [
+        build('created', meta.created_at, meta.created_by, 'created', 'createdAt'),
+        // Hide "modified" when it is the creation instant itself (never edited).
+        meta.updated_at && record[meta.updated_at] !== record[meta.created_at ?? '']
+            ? build('updated', meta.updated_at, meta.updated_by, 'updated', 'updatedAt')
+            : null,
+        build('deleted', meta.deleted_at, meta.deleted_by, 'deleted', 'deletedAt'),
+    ].filter((l): l is Line => l !== null)
+
+    if (lines.length === 0) return null
+
+    const Chevron = open ? ChevronDown : ChevronRight
+    return (
+        <div className={cn('text-xs text-muted-foreground', className)} data-testid="audit-info">
+            <button
+                type="button"
+                className="flex items-center gap-1.5 hover:text-foreground"
+                aria-expanded={open}
+                onClick={() => setOpen(o => !o)}
+            >
+                <Chevron className="h-3.5 w-3.5" />
+                <History className="h-3.5 w-3.5" />
+                <span>{tt('title')}</span>
+            </button>
+            {open && (
+                <ul className="mt-2 space-y-1 pl-6">
+                    {lines.map(l => (
+                        <li key={l.key} data-audit-line={l.key}>
+                            <span>{l.text}</span>
+                            {' · '}
+                            <time title={l.title}>{l.absolute}</time>
+                            <span className="opacity-70"> ({l.relative})</span>
+                        </li>
+                    ))}
+                </ul>
+            )}
+        </div>
+    )
+}

package/src/dialogs/dynamic-record.tsx

@@ -60,6 +60,8 @@ import { toastServerError, extractFieldErrors, localizeFieldIssue, localizeField
 import { DynamicSelectField, OptionLead, OptionThumb } from '../dynamic-select-field'
 import { DynamicMultiSelectField } from '../dynamic-multi-select-field'
 import { DynamicRelations } from '../dynamic-relations'
+import { AuditInfo, readAuditMeta } from '../audit-info'
+import type { AuditMeta } from '../types'
 import { useOptionsResolver, type ResolvedOption } from '../use-options-resolver'
 import { getFieldRef, getVisibleWhen, evaluateVisibleWhen, ATTRIBUTE_CLASSES_KEY } from '../dynamic-form-schema'
 import { useAttributeClasses, type AttributeClass } from '../attribute-classes'
@@ -643,6 +645,7 @@ export function DynamicRecordDialog({
         schema ? (schema as ModalMetadata) : null,
     )
     const [relations, setRelations] = useState<RelationMeta[]>([])
+    const [audit, setAudit] = useState<AuditMeta | undefined>(undefined)
     const [record, setRecord] = useState<any | null>(null)
     const [formValues, setFormValues] = useState<Record<string, any>>({})
     // Classes of the record's category (plus those its saved data carries), for
@@ -784,6 +787,7 @@ export function DynamicRecordDialog({
     useEffect(() => {
         if (!open || mode === 'create' || !recordId) {
             setRelations([])
+            setAudit(undefined)
             return
         }
         let cancelled = false
@@ -792,6 +796,7 @@ export function DynamicRecordDialog({
                 if (cancelled) return
                 const meta = res.data?.data ?? res.data
                 const rels: RelationMeta[] = Array.isArray(meta?.relations) ? meta.relations : []
+                setAudit(readAuditMeta(meta?.audit))
                 // Localize each panel header: the backend serves `label` as an
                 // i18n key (addon bundle, loaded live) and the SDK renders it verbatim.
                 setRelations(
@@ -1189,6 +1194,14 @@ export function DynamicRecordDialog({
                                     />
                                 </div>
                             )}
+                            {!isCreate && record && audit && (
+                                <AuditInfo
+                                    record={record}
+                                    audit={audit}
+                                    timeZone={timeZone}
+                                    className="mt-6 border-t pt-3"
+                                />
+                            )}
                         </CurrencyContext.Provider>
                         </TimeZoneContext.Provider>
                         </ImageUrlContext.Provider>

package/src/dropdown-menu-entry.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+// Radix context guard: a component that renders RowActionMenuItem (whose
+// DropdownMenuItem is imported from the ROOT '@asteby/metacore-ui' entry) must
+// import its DropdownMenu shell from the root entry too. Hosts share the root
+// entry as a Module Federation singleton but bundle '/primitives' locally, so
+// mixing entries creates two Menu contexts → "`MenuItem` must be used within
+// `Menu`" at runtime (Pitsline kanban card menu crash, 2026-10-05).
+describe('dropdown menu entry consistency', () => {
+    const dir = join(__dirname)
+    const files = readdirSync(dir).filter((f) => f.endsWith('.tsx'))
+    for (const f of files) {
+        const src = readFileSync(join(dir, f), 'utf8')
+        if (!src.includes('<RowActionMenuItem')) continue
+        it(`${f} imports DropdownMenu from the root ui entry`, () => {
+            const primitivesImport = src.match(/import\s*{([^}]*)}\s*from\s*'@asteby\/metacore-ui\/primitives'/)
+            const fromPrimitives = primitivesImport ? primitivesImport[1] : ''
+            expect(fromPrimitives).not.toMatch(/\bDropdownMenu(Content|Trigger)?\b/)
+        })
+    }
+})

package/src/dynamic-form.tsx

@@ -30,6 +30,7 @@ import {
 } from './dynamic-form-schema'
 import { ScanLine } from 'lucide-react'
 import { BarcodeScanner } from './barcode-scanner'
+import { getOptionFilter } from './option-filter'
 import { useOptionsResolver, type ResolvedOption } from './use-options-resolver'
 import { DynamicLineItems } from './dynamic-line-items'
 import { DynamicSelectField } from './dynamic-select-field'
@@ -530,6 +531,8 @@ function RefSelect({ field, value, onChange }: FieldRendererProps) {
         modelKey: '',          // unused — `ref` drives the URL
         fieldKey: 'id',
         ref: field.ref,
+        optionFilter: getOptionFilter(field),
+        keepValue: value,
     })
     return (
         <Select value={value || ''} onValueChange={onChange} disabled={loading}>

package/src/dynamic-kanban.tsx

@@ -94,9 +94,6 @@ import {
     Button,
     Card,
     CardContent,
-    DropdownMenu,
-    DropdownMenuContent,
-    DropdownMenuTrigger,
     Input,
     Popover,
     PopoverContent,
@@ -113,6 +110,13 @@ import {
     SheetTrigger,
     Skeleton,
 } from '@asteby/metacore-ui/primitives'
+// The card "…" menu renders RowActionMenuItem (dynamic-columns), whose
+// DropdownMenuItem comes from the ROOT '@asteby/metacore-ui' entry. The menu
+// shell MUST come from that same entry: hosts share the root entry as a Module
+// Federation singleton while '/primitives' is bundled locally, so mixing them
+// yields two Radix Menu contexts and the click crashes the app with
+// "`MenuItem` must be used within `Menu`" (Pitsline taller kanban, 2026-10-05).
+import { DropdownMenu, DropdownMenuContent, DropdownMenuTrigger } from '@asteby/metacore-ui'
 import { ColumnFilterControl, FilterValueCombobox, type ColumnFilterType } from '@asteby/metacore-ui/data-table'
 import { generateBadgeStyles, optionColor } from '@asteby/metacore-ui/lib'
 import { useApi } from './api-context'

package/src/dynamic-line-items.tsx

@@ -36,6 +36,7 @@ import {
     applyOptionWhen,
 } from './dynamic-form-schema'
 import { DynamicSelectField, DEFAULT_DEPENDS_HINT } from './dynamic-select-field'
+import { getOptionFilter } from './option-filter'
 import { useOptionsResolver, type ResolvedOption } from './use-options-resolver'
 
 export interface DynamicLineItemsProps {
@@ -575,6 +576,8 @@ function RefCell({ field, value, onChange, onPick, disabled, formValues, rowValu
         ref: optSource.ref,
         endpoint: optSource.endpoint,
         filterValue: dependsOn ? scope : undefined,
+        optionFilter: getOptionFilter(field),
+        keepValue: value,
         enabled: !blockedByDependency,
     })
 

package/src/dynamic-multi-select-field.tsx

@@ -19,6 +19,7 @@
 // value instead.
 import { useMemo } from 'react'
 import { MultiSelect } from '@asteby/metacore-ui/primitives'
+import { getOptionFilter } from './option-filter'
 import { useOptionsResolver } from './use-options-resolver'
 import { getFieldRef } from './dynamic-form-schema'
 import type { ActionFieldDef } from './types'
@@ -38,6 +39,7 @@ export function DynamicMultiSelectField({ field, value, onChange }: DynamicMulti
         ref,
         endpoint: !ref && field.searchEndpoint ? field.searchEndpoint : undefined,
         limit: 200,
+        optionFilter: getOptionFilter(field),
     })
 
     const selected = useMemo(() => (Array.isArray(value) ? value.map(String) : []), [value])

package/src/dynamic-select-field.tsx

@@ -22,6 +22,7 @@
 // value). A dedicated `?ids=` lookup is a follow-up; create flows — the common
 // case — start empty and never hit this.
 import { useEffect, useRef, useState } from 'react'
+import { getOptionFilter } from './option-filter'
 import { useTranslation } from 'react-i18next'
 import {
     Badge,
@@ -266,6 +267,7 @@ export function DynamicSelectField({
     const blockedByDependency = !!dependsOn && scope === ''
 
     const useStatic = Array.isArray(staticOptions)
+    const optionFilter = getOptionFilter(field)
 
     const { options: fetchedOptions, loading: fetchLoading } = useOptionsResolver({
         modelKey: '',
@@ -280,6 +282,8 @@ export function DynamicSelectField({
         // Cascade scope forwarded as filter_value (only when this field
         // declares a dependency). Re-fetches when the parent value changes.
         filterValue: dependsOn ? scope : undefined,
+        optionFilter,
+        keepValue: value,
         // Don't fetch until the popover opens (and keep fetching as the query
         // changes while open). A picker blocked by an unset dependency never
         // fetches. A readonly cell fetches eagerly so its value's label resolves

package/src/index.ts

@@ -584,6 +584,14 @@ export {
     type ActivityEvent,
     type ActivityDiffProps,
 } from './activity-diff'
+export {
+    AuditInfo,
+    readAuditMeta,
+    resolveAuditActor,
+    SYSTEM_ACTOR_ID,
+    type AuditInfoProps,
+    type AuditActor,
+} from './audit-info'
 export {
     RecordHistory,
     type RecordHistoryProps,
@@ -661,3 +669,8 @@ export {
 
 // Página de documento (benchmark §5/§6): cabecera, badges, acciones por estado, botones inteligentes.
 export * from './document'
+
+// Option filter — hide options of a relation / dynamic picker from the manifest
+// (`option_filter` / `optionFilter` on the field).
+export { getOptionFilter, applyOptionFilter, optionPassesRule } from './option-filter'
+export type { OptionFilter, OptionFilterRule } from './option-filter'

package/src/option-filter.ts

@@ -0,0 +1,88 @@
+// Option filter — lets a manifest HIDE options of a relation / dynamic picker
+// (e.g. keep cancelled invoices out of the "abonos" invoice selector, PIT-059).
+//
+// The filter runs client-side over the options the resolver already fetched, so
+// it needs no kernel change: it reads the extra scalar columns the options
+// endpoint returns (they land in `option.meta`) plus the standard `label`,
+// `name`, `description`, `color`, `icon` keys. Fully opt-in: a field without
+// `option_filter` / `optionFilter` behaves exactly as before.
+import type { ResolvedOption } from './use-options-resolver'
+
+export interface OptionFilterRule {
+    /** Option property to test: a `meta` key (e.g. `status`) or `id`/`value`/`label`/`name`/`description`/`color`/`icon`. */
+    field: string
+    /** Keep only options whose value equals this. */
+    equals?: string | number | boolean
+    /** snake_case alias of `notEquals`. */
+    not_equals?: string | number | boolean
+    /** Hide options whose value equals this. */
+    notEquals?: string | number | boolean
+    /** Keep only options whose value is one of these. */
+    in?: Array<string | number | boolean>
+    /** Hide options whose value is one of these. */
+    not_in?: Array<string | number | boolean>
+    /** camelCase alias of `not_in`. */
+    notIn?: Array<string | number | boolean>
+}
+
+/** One rule, or a list of rules that must ALL pass (AND). */
+export type OptionFilter = OptionFilterRule | OptionFilterRule[]
+
+type FilterCarrier = { optionFilter?: unknown; option_filter?: unknown }
+
+/** Reads the filter from a field (camelCase or the snake_case the kernel serves). */
+export function getOptionFilter(field: unknown): OptionFilterRule[] {
+    if (!field || typeof field !== 'object') return []
+    const f = field as FilterCarrier
+    const raw = f.optionFilter ?? f.option_filter
+    const list = Array.isArray(raw) ? raw : raw && typeof raw === 'object' ? [raw] : []
+    return list.filter(
+        (r): r is OptionFilterRule =>
+            !!r && typeof r === 'object' && typeof (r as OptionFilterRule).field === 'string' && (r as OptionFilterRule).field !== '',
+    )
+}
+
+function norm(v: unknown): string {
+    return String(v).trim().toLowerCase()
+}
+
+function readProp(opt: ResolvedOption, key: string): unknown {
+    if (key === 'id' || key === 'value' || key === 'label' || key === 'name' || key === 'description' || key === 'color' || key === 'icon' || key === 'image') {
+        return (opt as unknown as Record<string, unknown>)[key]
+    }
+    return opt.meta?.[key]
+}
+
+/** True when the option satisfies the rule. Comparison is trimmed + case-insensitive. */
+export function optionPassesRule(opt: ResolvedOption, rule: OptionFilterRule): boolean {
+    const raw = readProp(opt, rule.field)
+    const known = raw !== undefined && raw !== null
+    const v = known ? norm(raw) : ''
+    const notEquals = rule.notEquals ?? rule.not_equals
+    const notIn = rule.notIn ?? rule.not_in
+    // Positive rules need the property to exist; negative rules cannot exclude
+    // what they cannot see, so an option lacking the property is kept.
+    if (rule.equals !== undefined && !(known && v === norm(rule.equals))) return false
+    if (Array.isArray(rule.in) && !(known && rule.in.some((x) => norm(x) === v))) return false
+    if (notEquals !== undefined && known && v === norm(notEquals)) return false
+    if (Array.isArray(notIn) && known && notIn.some((x) => norm(x) === v)) return false
+    return true
+}
+
+/**
+ * Applies the field's filter to resolved options. Returns the SAME array when
+ * there is nothing to filter. `keepValue` (the current selection) is never
+ * hidden, so an existing record keeps showing its label after the option
+ * became ineligible.
+ */
+export function applyOptionFilter(
+    options: ResolvedOption[],
+    rules: OptionFilterRule[],
+    keepValue?: unknown,
+): ResolvedOption[] {
+    if (rules.length === 0) return options
+    const keep = keepValue === undefined || keepValue === null || keepValue === '' ? null : String(keepValue)
+    return options.filter(
+        (o) => (keep !== null && String(o.id) === keep) || rules.every((r) => optionPassesRule(o, r)),
+    )
+}

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { OptionFilter } from './option-filter'
 // Shared metadata shape consumed by every host. Some hosts add a `link`
 // action type with a `linkUrl` template — represented here as part of the
 // `type` union so the SDK can render it uniformly.
@@ -64,6 +65,21 @@ export interface DocumentFormsManifest {
     types: DocumentFormType[]
 }
 
+/**
+ * Audit columns of a model, served by the kernel (>= v0.188) on the table
+ * metadata. Each value is the COLUMN NAME (the key in the row), not a value;
+ * a key is omitted when the model lacks that column (append-only ledgers have
+ * only `created_*`). Purely additive — older kernels omit `audit` entirely.
+ */
+export interface AuditMeta {
+    created_at?: string
+    created_by?: string
+    updated_at?: string
+    updated_by?: string
+    deleted_at?: string
+    deleted_by?: string
+}
+
 export interface TableMetadata {
     title: string
     endpoint: string
@@ -78,6 +94,11 @@ export interface TableMetadata {
     canExport?: boolean
     canImport?: boolean
     canCreate?: boolean
+    /**
+     * Audit columns (when/who) of the model. Feeds `<AuditInfo>`; absent on
+     * older kernels or models without audit columns.
+     */
+    audit?: AuditMeta
     /**
      * Formularios de alta guiados por tipo de documento (FAC-12). Cuando trae
      * al menos un tipo, `DynamicCRUDPage` abre `DocumentFormDialog` en lugar del
@@ -380,6 +401,16 @@ export interface ColumnDefinition {
      * widgets — `searchEndpoint` stays as the legacy escape hatch.
      */
     ref?: string
+    /**
+     * Hides options of this relation/dynamic picker (e.g. cancelled invoices in
+     * the payments selector). One rule or a list (AND), tested client-side
+     * against the option's extra columns (`meta`): `{ field: 'status', not_in:
+     * ['cancelada'] }`. The options endpoint must return that column. Absent →
+     * the picker lists everything (retrocompat). See `option-filter.ts`.
+     */
+    optionFilter?: OptionFilter
+    /** snake_case alias served by the kernel manifest for `optionFilter`. */
+    option_filter?: OptionFilter
     /**
      * Write-time rules the SDK also pre-flights. Object form `{regex,min,max,custom}`
      * or a Laravel / go-playground string (`required|min:2|email`).
@@ -546,6 +577,16 @@ export interface ActionFieldDef {
      * `useOptionsResolver` against `/api/options/<ref>?field=id`.
      */
     ref?: string
+    /**
+     * Hides options of this relation/dynamic picker (e.g. cancelled invoices in
+     * the payments selector). One rule or a list (AND), tested client-side
+     * against the option's extra columns (`meta`): `{ field: 'status', not_in:
+     * ['cancelada'] }`. The options endpoint must return that column. Absent →
+     * the picker lists everything (retrocompat). See `option-filter.ts`.
+     */
+    optionFilter?: OptionFilter
+    /** snake_case alias served by the kernel manifest for `optionFilter`. */
+    option_filter?: OptionFilter
     /**
      * snake_case aliases the kernel manifest may serve for a belongs_to FK
      * target instead of `ref`. Treated as equivalent to `ref` by the SDK so a

package/src/use-options-resolver.ts

@@ -12,6 +12,7 @@
 // free; legacy callers that still ship `searchEndpoint` keep working.
 import { useEffect, useMemo, useRef, useState } from 'react'
 import { useApi } from './api-context'
+import { applyOptionFilter, type OptionFilterRule } from './option-filter'
 import { loadQueryPart, optionsBatchToken, optionsModelFromUrl } from './query-batch'
 
 export interface ResolvedOption {
@@ -90,6 +91,13 @@ export interface UseOptionsResolverArgs {
      * `fieldKey` / `query` / `limit` exactly the same way.
      */
     endpoint?: string
+    /**
+     * Client-side rules that hide fetched options (see `option-filter.ts`).
+     * Empty/undefined → no filtering (retrocompat).
+     */
+    optionFilter?: OptionFilterRule[]
+    /** Current selection: never hidden by `optionFilter`, so its label survives. */
+    keepValue?: unknown
 }
 
 export interface UseOptionsResolverResult {
@@ -182,6 +190,8 @@ export function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsReso
         enabled = true,
         endpoint,
         filterValue,
+        optionFilter,
+        keepValue,
     } = args
 
     const api = useApi()
@@ -322,8 +332,16 @@ export function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsReso
         }
     }, [api, url, effectiveField, query, limit, enabled, filterValue, refreshKey])
 
+    // Rules arrive as a fresh array each render; key on their content.
+    const filterKey = optionFilter && optionFilter.length > 0 ? JSON.stringify(optionFilter) : ''
+    const visibleOptions = useMemo(
+        () => (filterKey ? applyOptionFilter(options, optionFilter ?? [], keepValue) : options),
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [options, filterKey, keepValue],
+    )
+
     return {
-        options,
+        options: visibleOptions,
         meta,
         loading,
         error,

package/vitest.config.ts

@@ -5,5 +5,6 @@ export default defineConfig({
         environment: 'node',
         include: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
         setupFiles: ['./vitest.setup.ts'],
+        testTimeout: 15000,
     },
 })

package/vitest.setup.ts

@@ -27,3 +27,10 @@ function installMemoryStorage(name: 'localStorage' | 'sessionStorage') {
 
 installMemoryStorage('localStorage')
 installMemoryStorage('sessionStorage')
+
+// `waitFor` defaults to 1s; the DynamicTable/DynamicKanban suites render large
+// trees and miss it when the whole monorepo's tests run in parallel (turbo).
+// A longer ceiling only affects failing waits, passing tests return immediately.
+import { configure } from '@testing-library/react'
+
+configure({ asyncUtilTimeout: 5000 })