@asteby/metacore-runtime-react 46.3.0 → 47.0.0

package/src/cfdi-stamp-panel.tsx

@@ -0,0 +1,146 @@
+// CfdiStampPanel — human-readable result of stamping (timbrar) a CFDI.
+//
+// A stamp action answers `{ document_id, fiscal_uuid, pdf_url, xml_url }`. The
+// dialog used to dump that JSON; this panel shows the fiscal UUID as text and
+// the PDF / XML as download links instead (#1024, FAC-3 / PIT-051). The SDK
+// invents nothing: only the keys the server actually returned are rendered.
+import { useTranslation } from 'react-i18next'
+import {
+    Dialog,
+    DialogContent,
+    DialogDescription,
+    DialogFooter,
+    DialogHeader,
+    DialogTitle,
+    Button,
+} from '@asteby/metacore-ui/primitives'
+import { CheckCircle2, FileCode2, FileText } from 'lucide-react'
+
+export interface CfdiStampResult {
+    fiscalUuid?: string
+    pdfUrl?: string
+    xmlUrl?: string
+    /** Optional human folio (`serie-folio`) when the server sends it. */
+    folio?: string
+    documentId?: string
+}
+
+const str = (v: unknown): string | undefined =>
+    typeof v === 'string' && v.trim() ? v.trim() : undefined
+
+const isSafeUrl = (u: string) => /^(https?:)?\/\//i.test(u) || u.startsWith('/') || u.startsWith('blob:')
+
+/**
+ * Reads a stamp result out of a successful action response body. Looks at
+ * `body.data`, `body.result` and the body itself. Returns `undefined` unless
+ * the payload carries `fiscal_uuid` and/or `pdf_url` / `xml_url` — a response
+ * without those keys is never turned into a fiscal result.
+ */
+export function extractStampResult(body: unknown): CfdiStampResult | undefined {
+    if (!body || typeof body !== 'object') return undefined
+    const b = body as Record<string, unknown>
+    const candidates = [b.data, b.result, b]
+    for (const c of candidates) {
+        if (!c || typeof c !== 'object' || Array.isArray(c)) continue
+        const o = c as Record<string, unknown>
+        const fiscalUuid = str(o.fiscal_uuid) ?? str(o.fiscalUuid) ?? str(o.uuid)
+        const pdf = str(o.pdf_url) ?? str(o.pdfUrl)
+        const xml = str(o.xml_url) ?? str(o.xmlUrl)
+        // A bare `uuid` is too generic to call a fiscal result on its own.
+        const hasFiscal = !!str(o.fiscal_uuid) || !!str(o.fiscalUuid) || !!pdf || !!xml
+        if (!hasFiscal) continue
+        return {
+            fiscalUuid,
+            pdfUrl: pdf && isSafeUrl(pdf) ? pdf : undefined,
+            xmlUrl: xml && isSafeUrl(xml) ? xml : undefined,
+            folio: str(o.folio) ?? str(o.number),
+            documentId: str(o.document_id) ?? str(o.documentId),
+        }
+    }
+    return undefined
+}
+
+export interface CfdiStampPanelProps {
+    result: CfdiStampResult
+    className?: string
+}
+
+export function CfdiStampPanel({ result, className }: CfdiStampPanelProps) {
+    const { t } = useTranslation()
+    return (
+        <div data-slot="cfdi-stamp-panel" className={`space-y-4 ${className ?? ''}`}>
+            <div className="flex items-center gap-2 text-sm font-medium text-emerald-600 dark:text-emerald-400">
+                <CheckCircle2 className="size-5" aria-hidden />
+                {t('cfdi.stamp.success', { defaultValue: 'CFDI timbrado correctamente' })}
+            </div>
+            <dl className="space-y-2 rounded-md border bg-muted/40 p-3 text-sm">
+                {result.folio && (
+                    <div className="flex flex-col gap-0.5">
+                        <dt className="text-xs uppercase tracking-wide text-muted-foreground">
+                            {t('cfdi.stamp.folio', { defaultValue: 'Folio' })}
+                        </dt>
+                        <dd>{result.folio}</dd>
+                    </div>
+                )}
+                {result.fiscalUuid && (
+                    <div className="flex flex-col gap-0.5">
+                        <dt className="text-xs uppercase tracking-wide text-muted-foreground">
+                            {t('cfdi.stamp.uuid', { defaultValue: 'UUID fiscal' })}
+                        </dt>
+                        <dd className="break-all font-mono" data-slot="cfdi-stamp-uuid">
+                            {result.fiscalUuid}
+                        </dd>
+                    </div>
+                )}
+            </dl>
+            {(result.pdfUrl || result.xmlUrl) && (
+                <div className="flex flex-wrap gap-2">
+                    {result.pdfUrl && (
+                        <Button asChild variant="outline" size="sm">
+                            <a href={result.pdfUrl} target="_blank" rel="noopener noreferrer" data-slot="cfdi-stamp-pdf">
+                                <FileText className="mr-2 size-4" aria-hidden />
+                                {t('cfdi.stamp.pdf', { defaultValue: 'Descargar PDF' })}
+                            </a>
+                        </Button>
+                    )}
+                    {result.xmlUrl && (
+                        <Button asChild variant="outline" size="sm">
+                            <a href={result.xmlUrl} target="_blank" rel="noopener noreferrer" data-slot="cfdi-stamp-xml">
+                                <FileCode2 className="mr-2 size-4" aria-hidden />
+                                {t('cfdi.stamp.xml', { defaultValue: 'Descargar XML' })}
+                            </a>
+                        </Button>
+                    )}
+                </div>
+            )}
+        </div>
+    )
+}
+
+export interface CfdiStampResultDialogProps {
+    open: boolean
+    onOpenChange: (open: boolean) => void
+    result: CfdiStampResult
+    title?: string
+}
+
+/** Dialog shell used by the action modals after a successful stamp. */
+export function CfdiStampResultDialog({ open, onOpenChange, result, title }: CfdiStampResultDialogProps) {
+    const { t } = useTranslation()
+    return (
+        <Dialog open={open} onOpenChange={onOpenChange}>
+            <DialogContent className="sm:max-w-md">
+                <DialogHeader>
+                    <DialogTitle>{title ?? t('cfdi.stamp.title', { defaultValue: 'Resultado del timbrado' })}</DialogTitle>
+                    <DialogDescription className="sr-only">
+                        {t('cfdi.stamp.desc', { defaultValue: 'UUID fiscal y archivos del CFDI timbrado' })}
+                    </DialogDescription>
+                </DialogHeader>
+                <CfdiStampPanel result={result} />
+                <DialogFooter>
+                    <Button onClick={() => onOpenChange(false)}>{t('common.close', { defaultValue: 'Cerrar' })}</Button>
+                </DialogFooter>
+            </DialogContent>
+        </Dialog>
+    )
+}

package/src/dialogs/dynamic-record.tsx

@@ -9,6 +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 { emitRecordMutation } from '../record-mutation-events'
 import { createContext, useCallback, useContext, useEffect, useId, useRef, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import type { ModelSchema } from './types'
@@ -945,6 +946,7 @@ export function DynamicRecordDialog({
             if (isCreate && onCreate) {
                 const created = await onCreate(payload)
                 toast.success(modalMeta?.messages?.created || t('dynamic.create_success', { defaultValue: 'Registro creado correctamente' }))
+                emitRecordMutation(model, 'create')
                 onSaved?.(created ?? undefined)
                 onOpenChange(false)
                 return
@@ -953,6 +955,7 @@ export function DynamicRecordDialog({
             if (!isCreate && recordId && onUpdate) {
                 const updated = await onUpdate(String(recordId), payload)
                 toast.success(modalMeta?.messages?.updated || t('dynamic.update_success', { defaultValue: 'Guardado correctamente' }))
+                emitRecordMutation(model, 'update')
                 onSaved?.(updated ?? undefined)
                 onOpenChange(false)
                 return
@@ -980,6 +983,7 @@ export function DynamicRecordDialog({
                             : t('dynamic.update_success', { defaultValue: 'Guardado correctamente' })),
                 )
                 // Hand the persisted record back so callers can auto-select it.
+                emitRecordMutation(model, isCreate ? 'create' : 'update')
                 onSaved?.(res.data?.data ?? res.data ?? undefined)
                 onOpenChange(false)
             } else {
@@ -1000,6 +1004,7 @@ export function DynamicRecordDialog({
         setDeleting(true)
         try {
             await onDelete()
+            emitRecordMutation(model, 'delete')
             onOpenChange(false)
         } catch (err: any) {
             console.error('[DynamicRecordDialog] delete error:', err)

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

@@ -33,12 +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
@@ -89,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
 }
 
 /**
@@ -111,6 +118,7 @@ export function DynamicCRUDPage(props: DynamicCRUDPageProps) {
         toolbarExtras,
         classes,
         onChange,
+        documentForms,
     } = props
 
     const strings = { ...defaultStrings, ...(i18n ?? {}) }
@@ -159,10 +167,17 @@ export function DynamicCRUDPage(props: DynamicCRUDPageProps) {
     }, [title])
 
     const enableCRUD = metadata?.enableCRUDActions ?? false
-    // A "create"-placement action ships a custom create experience — it
-    // replaces the generic create button (the ModelActionToolbar renders it).
-    const hasCreateAction = metadata?.actions?.some((a) => a.placement === 'create') ?? false
-    const effectiveHideCreate = hideCreate || ext?.hideCreate || hasCreateAction
+    // Una sola primaria: placement create, replaces_create, create_mode o la
+    // extensión del modelo ocultan el Crear genérico. El shell de ops debe
+    // usar el mismo resolveListPrimaryAction.
+    const primary = resolveListPrimaryAction({
+        enableCRUD,
+        canCreate: metadata?.canCreate,
+        hideCreate: hideCreate || ext?.hideCreate,
+        createMode: ext?.createMode ?? metadata?.create_mode,
+        primaryActionKey: ext?.primaryActionKey,
+        actions: metadata?.actions,
+    })
     const effectiveHideExport = hideExport || ext?.hideExport
     const effectiveHideImport = hideImport || ext?.hideImport
     // Refresh defaults to hidden in the page header — <DynamicTable> ships
@@ -174,10 +189,11 @@ export function DynamicCRUDPage(props: DynamicCRUDPageProps) {
     // (useCan defaults to always-true), in which case create/export/import
     // require `lowercase(model).create|export|import`.
     const can = useCan()
-    const showCreate = enableCRUD && !effectiveHideCreate && can(modelCapability(model, 'create'))
+    const showCreate = primary.showGenericCreate && can(modelCapability(model, 'create'))
     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)
@@ -239,11 +255,13 @@ export function DynamicCRUDPage(props: DynamicCRUDPageProps) {
                             model={model}
                             endpoint={dataEndpoint}
                             actions={metadata?.actions}
+                            primaryActionKey={ext?.primaryActionKey}
                             onChange={handleRefresh}
                         />
                         {showCreate && (
                             <button
                                 type='button'
+                                data-primary='true'
                                 onClick={() => setOpenCreate(true)}
                                 className='inline-flex items-center gap-2 h-9 px-3 rounded-md bg-primary text-primary-foreground hover:opacity-90 text-sm font-medium'
                             >
@@ -264,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-kanban.tsx

@@ -152,6 +152,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 +924,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 +1341,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.