@asteby/metacore-runtime-react 46.4.0 → 47.1.0

package/src/document-form-dialog.tsx

@@ -0,0 +1,357 @@
+// DocumentFormDialog — alta guiada por tipo de documento (FAC-12, #1022).
+//
+// "Crear documento fiscal" era el mismo formulario genérico para factura, nota
+// de crédito, REP, global y traslado: los campos los dictaba el modelo, no el
+// tipo. Aquí el metadata (`document_forms`) o una prop declara los tipos; el
+// diálogo muestra tarjetas de tipo y, al elegir uno, SUS campos y (si lo declara)
+// el paso de renglones con el editor de renglones del SDK. Un solo tipo se salta
+// el selector; sin manifest el alta genérica sigue igual (DynamicCRUDPage decide).
+//
+// El SDK no hardcodea catálogos SAT: campos, valores fijos y el valor del tipo
+// vienen del manifest que sirve el kernel o el addon.
+import { useEffect, useMemo, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import {
+    Button,
+    Dialog,
+    DialogContent,
+    DialogDescription,
+    DialogFooter,
+    DialogHeader,
+    DialogTitle,
+} from '@asteby/metacore-ui/primitives'
+import { Loader2 } from 'lucide-react'
+import { toast } from 'sonner'
+import { useApi } from './api-context'
+import { DynamicIcon } from './dynamic-icon'
+import { FieldCell, FieldGrid, FieldLabel } from './field-grid'
+import { FormErrorBanner } from './business/feedback'
+import {
+    DocumentLinesGrid,
+    type DocumentLinesGridProps,
+    type LineItemsColumn,
+} from './business/line-items-editor'
+import { serializeLineItems, validateLineItems, type LineItem } from './business/line-items'
+import {
+    actionErrorBannerMessage,
+    buildFieldDefaults,
+    renderField,
+} from './action-modal-dispatcher'
+import { extractFieldErrors, localizeFieldErrorMap } from './server-error'
+import { validateValues, bagHasErrors } from './validator'
+import { clearFieldErrorTree } from './field-validation-ui'
+import { emitRecordMutation } from './record-mutation-events'
+import { isLineItemsField, resolveWidget } from './dynamic-form-schema'
+import type {
+    ActionFieldDef,
+    DocumentFormLines,
+    DocumentFormsManifest,
+    DocumentFormType,
+    TableMetadata,
+} from './types'
+
+export interface DocumentFormDialogProps {
+    open: boolean
+    onOpenChange: (open: boolean) => void
+    /** Modelo en el que se da de alta (p. ej. `fiscal_documents`). */
+    model: string
+    /** Endpoint de alta. Default `/dynamic/<model>`. */
+    endpoint?: string
+    forms: DocumentFormsManifest
+    /** Tipo preseleccionado (se salta el selector). */
+    initialType?: string
+    /** Se llama con el registro creado. */
+    onSaved?: (record?: unknown) => void
+    /** Buscador de productos para el editor de renglones (mismo contrato que ProductPicker). */
+    searchProducts?: DocumentLinesGridProps['search']
+    /** Moneda ISO para el editor de renglones (default: la de la org). */
+    currency?: string
+}
+
+/** Manifest efectivo: la prop gana sobre el metadata; sin tipos devuelve undefined. */
+export function resolveDocumentForms(
+    metadata?: Pick<TableMetadata, 'document_forms'> | null,
+    override?: DocumentFormsManifest | null,
+): DocumentFormsManifest | undefined {
+    const m = override ?? metadata?.document_forms
+    return m && Array.isArray(m.types) && m.types.length > 0 ? m : undefined
+}
+
+function linesConfig(type: DocumentFormType, forms: DocumentFormsManifest): (DocumentFormLines & { field: string }) | undefined {
+    if (!type.lines) return undefined
+    const cfg: DocumentFormLines = type.lines === true ? {} : type.lines
+    return { ...cfg, field: cfg.field ?? forms.lines_field ?? 'lines' }
+}
+
+type Step = 'type' | 'fields' | 'lines'
+
+export function DocumentFormDialog({
+    open,
+    onOpenChange,
+    model,
+    endpoint,
+    forms,
+    initialType,
+    onSaved,
+    searchProducts,
+    currency,
+}: DocumentFormDialogProps) {
+    const { t, i18n } = useTranslation()
+    const api = useApi()
+    const types = forms.types
+    const single = types.length === 1 ? types[0] : undefined
+
+    const [typeKey, setTypeKey] = useState<string | null>(initialType ?? single?.key ?? null)
+    const [step, setStep] = useState<Step>(initialType || single ? 'fields' : 'type')
+    const [formData, setFormData] = useState<Record<string, any>>({})
+    const [lines, setLines] = useState<LineItem[]>([])
+    const [fieldErrors, setFieldErrors] = useState<Record<string, string>>({})
+    const [serverLineErrors, setServerLineErrors] = useState<Record<string, string>>({})
+    const [formError, setFormError] = useState<string | undefined>()
+    const [saving, setSaving] = useState(false)
+
+    const type = useMemo(() => types.find((x) => x.key === typeKey) ?? null, [types, typeKey])
+    const lineCfg = type ? linesConfig(type, forms) : undefined
+
+    // Reset every time the dialog (re)opens.
+    useEffect(() => {
+        if (!open) return
+        const start = initialType ?? single?.key ?? null
+        setTypeKey(start)
+        setStep(start ? 'fields' : 'type')
+        setLines([])
+        setFieldErrors({})
+        setServerLineErrors({})
+        setFormError(undefined)
+    }, [open, initialType, single?.key])
+
+    // Seed field defaults for the chosen type.
+    useEffect(() => {
+        if (!type) return
+        setFormData({ ...buildFieldDefaults(type.fields, undefined), ...(type.defaults ?? {}) })
+        setFieldErrors({})
+        setFormError(undefined)
+    }, [type])
+
+    const updateField = (key: string, value: any) => {
+        setFormData((prev) => ({ ...prev, [key]: value }))
+        setFieldErrors((prev) => clearFieldErrorTree(prev, key))
+    }
+
+    const tl = (s: string) => t(s, { defaultValue: s })
+    const lang = i18n?.language
+
+    const chooseType = (k: string) => {
+        setTypeKey(k)
+        setStep('fields')
+    }
+
+    /** Validate the header fields; returns true when they pass. */
+    const validateHeader = (): boolean => {
+        if (!type) return false
+        const bag = validateValues(type.fields, formData)
+        if (!bagHasErrors(bag)) {
+            setFieldErrors({})
+            return true
+        }
+        const labels: Record<string, string> = {}
+        for (const f of type.fields) labels[f.key] = tl(f.label)
+        setFieldErrors(localizeFieldErrorMap(bag, t, { labels, language: lang }))
+        return false
+    }
+
+    const goNext = () => {
+        if (validateHeader()) setStep('lines')
+    }
+
+    const submit = async () => {
+        if (!type) return
+        if (!validateHeader()) {
+            setStep('fields')
+            return
+        }
+        if (lineCfg && (lineCfg.required ?? true)) {
+            const v = validateLineItems(lines, { requireItems: true })
+            if (!v.form && Object.keys(v.errors).length === 0) {
+                /* ok */
+            } else {
+                setServerLineErrors(v.errors)
+                setFormError(v.form ?? t('documentForm.lines_invalid', { defaultValue: 'Revisa los renglones del documento.' }))
+                setStep('lines')
+                return
+            }
+        }
+        setSaving(true)
+        setFormError(undefined)
+        try {
+            const payload: Record<string, unknown> = { ...(type.defaults ?? {}), ...formData }
+            if (forms.type_field) payload[forms.type_field] = type.value ?? type.key
+            if (lineCfg) payload[lineCfg.field] = serializeLineItems(lines)
+            const url = type.endpoint ?? endpoint ?? `/dynamic/${model}`
+            const res = await api.post(url, payload)
+            if (res.data?.success === false) {
+                handleError({ response: { data: res.data } })
+                return
+            }
+            toast.success(t('dynamic.create_success', { defaultValue: 'Registro creado correctamente' }))
+            emitRecordMutation(model, 'create')
+            onSaved?.(res.data?.data ?? res.data ?? undefined)
+            onOpenChange(false)
+        } catch (err) {
+            handleError(err)
+        } finally {
+            setSaving(false)
+        }
+    }
+
+    /** 422 → marks the fields and shows the banner INSIDE the dialog; stays open. */
+    const handleError = (err: unknown) => {
+        setFormError(actionErrorBannerMessage(err, type?.fields, t, lang))
+        const map = extractFieldErrors(err)
+        if (map) {
+            const labels: Record<string, string> = {}
+            for (const f of type?.fields ?? []) labels[f.key] = tl(f.label)
+            const localized = localizeFieldErrorMap(map, t, { labels, language: lang })
+            const header: Record<string, string> = {}
+            const lineErrs: Record<string, string> = {}
+            const prefix = lineCfg ? `${lineCfg.field}.` : null
+            for (const [k, v] of Object.entries(localized)) {
+                if (prefix && k.startsWith(prefix)) lineErrs[k.slice(prefix.length)] = v
+                else header[k] = v
+            }
+            setFieldErrors(header)
+            setServerLineErrors(lineErrs)
+        }
+    }
+
+    const canGoBackToTypes = types.length > 1 && !initialType
+    const stepLabel = (s: Step) =>
+        s === 'type'
+            ? t('documentForm.step_type', { defaultValue: 'Tipo de documento' })
+            : s === 'fields'
+              ? t('documentForm.step_data', { defaultValue: 'Datos' })
+              : tl(lineCfg?.title ?? 'Renglones')
+
+    return (
+        <Dialog open={open} onOpenChange={onOpenChange}>
+            <DialogContent
+                className="flex max-h-[90dvh] flex-col overflow-hidden sm:max-w-2xl"
+                style={{ maxHeight: '90dvh', ...(step === 'lines' ? { maxWidth: '980px', width: '95vw' } : {}) }}
+                data-slot="document-form-dialog"
+            >
+                <DialogHeader className="shrink-0">
+                    <DialogTitle>
+                        {type ? tl(type.label) : t('documentForm.title', { defaultValue: 'Nuevo documento' })}
+                    </DialogTitle>
+                    <DialogDescription>{stepLabel(step)}</DialogDescription>
+                </DialogHeader>
+
+                <div className="-mx-1 min-h-0 flex-1 space-y-3 overflow-y-auto px-1 py-3">
+                    <FormErrorBanner message={formError} />
+
+                    {step === 'type' && (
+                        <div role="radiogroup" className="grid gap-3 sm:grid-cols-2">
+                            {types.map((x) => (
+                                <button
+                                    key={x.key}
+                                    type="button"
+                                    role="radio"
+                                    aria-checked={x.key === typeKey}
+                                    data-type-card={x.key}
+                                    onClick={() => chooseType(x.key)}
+                                    className="flex items-start gap-3 rounded-lg border p-4 text-left transition-colors hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                                >
+                                    {x.icon && <DynamicIcon name={x.icon} className="mt-0.5 size-5 shrink-0 text-primary" />}
+                                    <span>
+                                        <span className="block text-sm font-medium">{tl(x.label)}</span>
+                                        {x.description && (
+                                            <span className="block text-xs text-muted-foreground">{tl(x.description)}</span>
+                                        )}
+                                    </span>
+                                </button>
+                            ))}
+                        </div>
+                    )}
+
+                    {step === 'fields' && type && (
+                        <FieldGrid>
+                            {type.fields.map((field: ActionFieldDef) => {
+                                const fullWidth =
+                                    isLineItemsField(field) ||
+                                    resolveWidget(field) === 'textarea' ||
+                                    resolveWidget(field) === 'richtext'
+                                return (
+                                    <FieldCell key={field.key} fullWidth={fullWidth}>
+                                        <FieldLabel htmlFor={field.key} required={field.required}>
+                                            {tl(field.label)}
+                                        </FieldLabel>
+                                        {renderField(
+                                            field,
+                                            formData[field.key],
+                                            (v: any) => updateField(field.key, v),
+                                            formData,
+                                            undefined,
+                                            fieldErrors,
+                                        )}
+                                        {fieldErrors[field.key] && (
+                                            <p className="mt-1 text-xs text-destructive">{fieldErrors[field.key]}</p>
+                                        )}
+                                    </FieldCell>
+                                )
+                            })}
+                        </FieldGrid>
+                    )}
+
+                    {step === 'lines' && type && lineCfg && (
+                        <DocumentLinesGrid
+                            value={lines}
+                            onChange={(next) => {
+                                setLines(next)
+                                setServerLineErrors({})
+                            }}
+                            columns={(lineCfg.columns as LineItemsColumn[] | undefined) ?? ['discount', 'tax']}
+                            priceSource={lineCfg.price_source ?? 'sale'}
+                            serverErrors={serverLineErrors}
+                            search={searchProducts}
+                            currency={currency}
+                        />
+                    )}
+                </div>
+
+                <DialogFooter className="shrink-0">
+                    {step === 'type' ? (
+                        <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+                            {t('common.cancel', { defaultValue: 'Cancelar' })}
+                        </Button>
+                    ) : (
+                        <Button
+                            type="button"
+                            variant="outline"
+                            disabled={saving}
+                            onClick={() => {
+                                if (step === 'lines') setStep('fields')
+                                else if (canGoBackToTypes) setStep('type')
+                                else onOpenChange(false)
+                            }}
+                        >
+                            {step === 'fields' && !canGoBackToTypes
+                                ? t('common.cancel', { defaultValue: 'Cancelar' })
+                                : t('common.back', { defaultValue: 'Atrás' })}
+                        </Button>
+                    )}
+                    {step === 'fields' && type && lineCfg && (
+                        <Button type="button" onClick={goNext}>
+                            {t('common.next', { defaultValue: 'Siguiente' })}
+                        </Button>
+                    )}
+                    {((step === 'fields' && type && !lineCfg) || step === 'lines') && (
+                        <Button type="button" onClick={submit} disabled={saving}>
+                            {saving && <Loader2 className="mr-2 size-4 animate-spin" aria-hidden />}
+                            {type?.submit_label ? tl(type.submit_label) : t('common.create', { defaultValue: 'Crear' })}
+                        </Button>
+                    )}
+                </DialogFooter>
+            </DialogContent>
+        </Dialog>
+    )
+}

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-crud-page.tsx

@@ -33,13 +33,14 @@ import { useApi } from './api-context'
 import { useMetadataCache } from './metadata-cache'
 import { DynamicTable } from './dynamic-table'
 import { DynamicRecordDialog } from './dialogs/dynamic-record'
+import { DocumentFormDialog, resolveDocumentForms } from './document-form-dialog'
 import { ExportDialog } from './dialogs/export'
 import { ImportDialog } from './dialogs/import'
 import { getModelExtension } from './model-extension-registry'
 import { ModelActionToolbar } from './model-action-toolbar'
 import { resolveListPrimaryAction } from './list-primary-action'
 import { useCan, modelCapability } from './permissions-context'
-import type { TableMetadata } from './types'
+import type { DocumentFormsManifest, TableMetadata } from './types'
 
 export interface DynamicCRUDPageStrings {
     refresh?: string
@@ -90,6 +91,11 @@ export interface DynamicCRUDPageProps {
     classes?: DynamicCRUDPageClasses
     /** Fired after a create/import/refresh successfully reloads the table. */
     onChange?: () => void
+    /**
+     * Guided create by document type (FAC-12). Wins over `metadata.document_forms`;
+     * with neither, the generic record dialog is used as before.
+     */
+    documentForms?: DocumentFormsManifest
 }
 
 /**
@@ -112,6 +118,7 @@ export function DynamicCRUDPage(props: DynamicCRUDPageProps) {
         toolbarExtras,
         classes,
         onChange,
+        documentForms,
     } = props
 
     const strings = { ...defaultStrings, ...(i18n ?? {}) }
@@ -186,6 +193,7 @@ export function DynamicCRUDPage(props: DynamicCRUDPageProps) {
     const showImport = enableCRUD && !effectiveHideImport && can(modelCapability(model, 'import'))
     const showExport = !effectiveHideExport && can(modelCapability(model, 'export'))
     const showRefresh = !effectiveHideRefresh
+    const guidedForms = resolveDocumentForms(metadata, documentForms)
 
     const handleRefresh = useCallback(() => {
         setRefreshKey((k) => k + 1)
@@ -274,7 +282,18 @@ export function DynamicCRUDPage(props: DynamicCRUDPageProps) {
                 </div>
             </div>
 
-            {showCreate && (
+            {showCreate && guidedForms && (
+                <DocumentFormDialog
+                    open={openCreate}
+                    onOpenChange={setOpenCreate}
+                    model={model}
+                    endpoint={dataEndpoint}
+                    forms={guidedForms}
+                    onSaved={handleRefresh}
+                />
+            )}
+
+            {showCreate && !guidedForms && (
                 <DynamicRecordDialog
                     open={openCreate}
                     onOpenChange={setOpenCreate}

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'
@@ -152,6 +156,7 @@ import { useFlipAnimation } from './use-flip-animation'
 import { PortalDragOverlay } from './portal-drag-overlay'
 import { objectLabel } from './dynamic-relation-helpers'
 import { useMetadataCache } from './metadata-cache'
+import { useRecordMutationTick } from './use-record-mutation-tick'
 import { useOptionsResolver } from './use-options-resolver'
 import { ActivityValueRenderer } from './activity-value-renderer'
 import { DynamicIcon } from './dynamic-icon'
@@ -923,6 +928,7 @@ function DynamicKanbanBoard({
     // Realtime refetch (opt-in) — debounced counter bumped by DATA_EVENTs for
     // this model; folded into the board refetch effect next to refreshTrigger.
     const realtimeDefault = useRealtimeDefault()
+    const mutationTick = useRecordMutationTick(model)
     const realtimeTick = useRealtimeTick({
         models: [model],
         enabled: realtimeProp ?? realtimeDefault,
@@ -1339,7 +1345,7 @@ function DynamicKanbanBoard({
         return () => clearTimeout(handle)
         // realtimeTick: data events for this model (see the `realtime` prop).
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [fetchData, metadata, refreshTrigger, realtimeTick])
+    }, [fetchData, metadata, refreshTrigger, realtimeTick, mutationTick])
 
     // Filterable fields for the toolbar, in metadata order (explicit filters
     // first, then filterable columns), each labeled from its metadata source.

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/dynamic-table.tsx

@@ -66,6 +66,7 @@ import { Inbox, Download, Upload, Trash2 } from 'lucide-react'
 import { toast } from 'sonner'
 import { Progress } from './dialogs/_primitives'
 import { useMetadataCache } from './metadata-cache'
+import { useRecordMutationTick } from './use-record-mutation-tick'
 import { useApi, useCurrentBranch } from './api-context'
 import { useReasonPrompt } from './reason-prompt'
 import type { ColumnFilterConfig, GetDynamicColumns } from './dynamic-columns-shim'
@@ -295,6 +296,9 @@ export function DynamicTable({
     // OrgRuntimeProvider (without it, money fell back to USD).
     const orgTimeZone = useTimeZone()
     const orgCurrency = useCurrency()
+    // Bumps when a dialog/modal anywhere creates, edits or deletes a record of
+    // this model, so the list reloads without the caller wiring refreshTrigger.
+    const mutationTick = useRecordMutationTick(model)
     const timeZone = timeZoneProp ?? orgTimeZone
     const currency = currencyProp ?? orgCurrency
     // The explicit `pagination` prop wins; the legacy `infiniteScroll` boolean
@@ -917,7 +921,7 @@ export function DynamicTable({
         } finally {
             setLoadingData(false)
         }
-    }, [model, metadata, pagination, buildFilterParams, refreshTrigger, endpoint, currentBranch?.id, api, enableUrlSync, relationInclude])
+    }, [model, metadata, pagination, buildFilterParams, refreshTrigger, mutationTick, endpoint, currentBranch?.id, api, enableUrlSync, relationInclude])
 
     // Columns whose metadata opts into a footer total (display_config.aggregate
     // → styleConfig.aggregate). When empty, no footer row is rendered and no
@@ -1098,7 +1102,7 @@ export function DynamicTable({
         // deps). Without it the comment above lied: infinite lists silently
         // failed to reload after a create ("a veces no recarga la tabla").
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [infiniteScroll, metadata, filterSignature, refreshTrigger])
+    }, [infiniteScroll, metadata, filterSignature, refreshTrigger, mutationTick])
 
     const handleRefresh = useCallback(() => {
         // Infinite mode owns its own list: refresh reloads page 1 and drops the

package/src/index.ts

@@ -196,6 +196,34 @@ export {
     type ListActionRef,
     type CreateMode,
 } from './list-primary-action'
+export {
+    emitRecordMutation,
+    subscribeRecordMutations,
+    RECORD_MUTATION_EVENT,
+    type RecordMutationKind,
+    type RecordMutationDetail,
+} from './record-mutation-events'
+export {
+    DocumentFormDialog,
+    resolveDocumentForms,
+    type DocumentFormDialogProps,
+} from './document-form-dialog'
+export {
+    modelFromNavUrl,
+    capabilityForNavItem,
+    isNavItemAllowed,
+    useNavItemVisible,
+    type NavLeafLike,
+} from './nav-permissions'
+export {
+    CfdiStampPanel,
+    CfdiStampResultDialog,
+    extractStampResult,
+    type CfdiStampResult,
+    type CfdiStampPanelProps,
+    type CfdiStampResultDialogProps,
+} from './cfdi-stamp-panel'
+export { useRecordMutationTick } from './use-record-mutation-tick'
 export * from './addon-loader'
 export {
     PURGE_ADDON_MESSAGE,
@@ -556,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,
@@ -633,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'