@asteby/metacore-runtime-react 45.0.0 → 45.3.0

package/src/document/document-timeline.tsx

@@ -0,0 +1,66 @@
+// DocumentTimeline — línea de tiempo de eventos de negocio del documento
+// («creó», «timbró», «envió a…», «abrió», «pagó», «solicitó cancelación»,
+// «respuesta del SAT»). Complementa a <RecordHistory> (que muestra diffs de
+// campos): aquí cada entrada es un hecho legible, con actor y hora.
+import { useTranslation } from 'react-i18next'
+import { Circle } from 'lucide-react'
+import { cn } from '@asteby/metacore-ui/lib'
+import { DynamicIcon } from '../dynamic-icon'
+import { formatFieldValue, type FieldFormatOptions } from './format'
+import type { StatusTone } from './types'
+
+export interface TimelineEntry {
+    id: string
+    at: string
+    /** Texto ya redactado («Timbró la factura»). */
+    label: string
+    actor?: string
+    detail?: string
+    icon?: string
+    tone?: StatusTone
+}
+
+export interface DocumentTimelineProps extends FieldFormatOptions {
+    entries: TimelineEntry[]
+    /** Texto del estado vacío; lleva `emptyAction` si el host da una acción. */
+    emptyText?: string
+    className?: string
+}
+
+const TONE_DOT: Record<StatusTone, string> = {
+    neutral: 'text-muted-foreground',
+    info: 'text-[var(--info,oklch(0.55_0.13_235))]',
+    success: 'text-[var(--success,oklch(0.6_0.15_155))]',
+    caution: 'text-[var(--warning,oklch(0.6_0.15_65))]',
+    warning: 'text-[var(--warning,oklch(0.6_0.15_65))]',
+    critical: 'text-destructive',
+}
+
+export function DocumentTimeline({ entries, emptyText, className, ...fmt }: DocumentTimelineProps) {
+    const { t } = useTranslation()
+    if (entries.length === 0) {
+        return (
+            <p className='rounded-md border border-dashed p-6 text-center text-sm text-muted-foreground'>
+                {emptyText ?? t('document.timeline_empty', { defaultValue: 'Aún no hay actividad en este documento.' })}
+            </p>
+        )
+    }
+    const sorted = [...entries].sort((a, b) => new Date(b.at).getTime() - new Date(a.at).getTime())
+    return (
+        <ol className={cn('relative flex flex-col gap-4 border-l pl-5', className)} data-document-timeline=''>
+            {sorted.map((e) => (
+                <li key={e.id} className='relative'>
+                    <span className={cn('absolute -left-[1.85rem] flex h-5 w-5 items-center justify-center rounded-full bg-card', TONE_DOT[e.tone ?? 'neutral'])}>
+                        {e.icon ? <DynamicIcon name={e.icon} className='h-4 w-4' /> : <Circle className='h-3 w-3 fill-current' />}
+                    </span>
+                    <p className='text-sm font-medium'>{t(e.label, { defaultValue: e.label })}</p>
+                    <p className='text-xs text-muted-foreground'>
+                        {formatFieldValue(e.at, 'datetime', fmt)}
+                        {e.actor ? ` · ${e.actor}` : ''}
+                    </p>
+                    {e.detail ? <p className='mt-1 whitespace-pre-wrap text-sm text-muted-foreground'>{e.detail}</p> : null}
+                </li>
+            ))}
+        </ol>
+    )
+}

package/src/document/evaluate.ts

@@ -0,0 +1,180 @@
+import type {
+    ActionLayout,
+    DocumentActionDef,
+    DocumentContext,
+    DocumentSpec,
+    Predicate,
+    ResolvedAction,
+    ResolvedActionLayout,
+    StatusDef,
+    StatusMachine,
+    When,
+} from './types'
+
+/** Máximo de secundarias visibles; el resto pasa a «Más…» (§5.2 / §6.2). */
+export const MAX_VISIBLE_SECONDARY = 3
+
+/**
+ * Lee una ruta del contexto. `$.x` son los derivados; `sources.k.length` es el
+ * total de una fuente; el resto cuelga del registro (`record.x` o `x`).
+ */
+export function readPath(ctx: DocumentContext, path: string): unknown {
+    if (!path) return undefined
+    let parts = path.split('.')
+    let cur: unknown
+    if (parts[0] === '$') {
+        cur = ctx.derived
+        parts = parts.slice(1)
+    } else if (parts[0] === 'sources') {
+        cur = ctx.sources
+        parts = parts.slice(1)
+    } else {
+        cur = ctx.record
+        if (parts[0] === 'record') parts = parts.slice(1)
+    }
+    for (const p of parts) {
+        if (cur == null) return undefined
+        if (p === 'length' && Array.isArray(cur)) {
+            cur = cur.length
+            continue
+        }
+        cur = (cur as Record<string, unknown>)[p]
+    }
+    return cur
+}
+
+function sameValue(a: unknown, b: unknown): boolean {
+    if (a == null || b == null) return a == b
+    return String(a) === String(b)
+}
+
+function isTruthy(v: unknown): boolean {
+    if (v == null || v === false || v === '' || v === 0) return false
+    if (Array.isArray(v)) return v.length > 0
+    return true
+}
+
+function toNumber(v: unknown): number {
+    const n = typeof v === 'number' ? v : parseFloat(String(v))
+    return Number.isFinite(n) ? n : NaN
+}
+
+export function evaluatePredicate(p: Predicate, ctx: DocumentContext): boolean {
+    const v = readPath(ctx, p.field)
+    switch (p.op) {
+        case 'eq':
+            return sameValue(v, p.value)
+        case 'neq':
+            return !sameValue(v, p.value)
+        case 'in':
+            return Array.isArray(p.value) && p.value.some((x) => sameValue(v, x))
+        case 'not_in':
+            return !(Array.isArray(p.value) && p.value.some((x) => sameValue(v, x)))
+        case 'truthy':
+            return isTruthy(v)
+        case 'falsy':
+            return !isTruthy(v)
+        case 'gt':
+            return toNumber(v) > toNumber(p.value)
+        case 'gte':
+            return toNumber(v) >= toNumber(p.value)
+        case 'lt':
+            return toNumber(v) < toNumber(p.value)
+        case 'lte':
+            return toNumber(v) <= toNumber(p.value)
+        default:
+            return false
+    }
+}
+
+/** Un arreglo es un AND; sin condición siempre se cumple. */
+export function evaluateWhen(when: When | undefined, ctx: DocumentContext): boolean {
+    if (!when) return true
+    const list = Array.isArray(when) ? when : [when]
+    return list.every((p) => evaluatePredicate(p, ctx))
+}
+
+/** Estado actual de una máquina para el registro (o su fallback / un estado desconocido explícito). */
+export function resolveStatus(machine: StatusMachine, ctx: DocumentContext): StatusDef | undefined {
+    const raw = readPath(ctx, machine.field)
+    const value = raw == null ? '' : String(raw)
+    const found = machine.states.find((s) => s.value === value)
+    if (found) return found
+    if (machine.fallback) return machine.fallback
+    if (!value) return undefined
+    return { value, label: value, tone: 'neutral' }
+}
+
+/**
+ * Distribución de acciones para el estado actual. Una acción `hiddenWhen` se
+ * omite; una `blockedWhen` queda deshabilitada con motivo. Más de
+ * `MAX_VISIBLE_SECONDARY` secundarias se derraman a «Más…»; una acción marcada
+ * `destructive` siempre va a la zona destructiva aunque el layout la ponga en otro lado.
+ */
+export function resolveActions(spec: DocumentSpec, ctx: DocumentContext): ResolvedActionLayout {
+    const byKey = new Map<string, DocumentActionDef>(spec.actions.map((a) => [a.key, a]))
+    const layout: ActionLayout =
+        spec.layouts.find((r) => evaluateWhen(r.when, ctx))?.layout ?? spec.defaultLayout ?? {}
+
+    const resolve = (key: string | undefined): ResolvedAction | undefined => {
+        if (!key) return undefined
+        const def = byKey.get(key)
+        if (!def || (def.hiddenWhen && evaluateWhen(def.hiddenWhen, ctx))) return undefined
+        const rules = def.blockedWhen ? (Array.isArray(def.blockedWhen) ? def.blockedWhen : [def.blockedWhen]) : []
+        const hit = rules.find((r) => evaluateWhen(r.when, ctx))
+        return { def, blockedReason: hit?.reason }
+    }
+    const many = (keys: string[] | undefined) =>
+        (keys ?? []).map(resolve).filter((a): a is ResolvedAction => !!a)
+
+    const destructive = many(layout.destructive)
+    const secondary: ResolvedAction[] = []
+    const more: ResolvedAction[] = []
+    for (const a of [...many(layout.secondary)]) {
+        if (a.def.destructive) destructive.push(a)
+        else secondary.push(a)
+    }
+    for (const a of many(layout.more)) {
+        if (a.def.destructive) destructive.push(a)
+        else more.push(a)
+    }
+    const overflow = secondary.splice(MAX_VISIBLE_SECONDARY)
+    more.unshift(...overflow)
+
+    let primary = resolve(layout.primary)
+    if (primary?.def.destructive) {
+        destructive.unshift(primary)
+        primary = undefined
+    }
+    return { primary, secondary, more, destructive }
+}
+
+/** Interpola `{{campo}}` con valores del registro (sin evaluar código). */
+export function interpolate(template: string, ctx: DocumentContext): string {
+    return template.replace(/\{\{\s*([\w.$]+)\s*\}\}/g, (_, path: string) => {
+        const v = readPath(ctx, path)
+        return v == null ? '' : String(v)
+    })
+}
+
+/** Título: la interpolación puede dejar vacío el resultado; se prueban alternativas separadas por `||`. */
+export function resolveTitle(template: string, ctx: DocumentContext): string {
+    for (const alt of template.split('||')) {
+        const out = interpolate(alt.trim(), ctx).trim()
+        if (out) return out
+    }
+    return ''
+}
+
+/**
+ * Quita del spec las acciones que dependen de una acción del modelo que el
+ * backend (o el addon que la aporta) no declara: mejor un botón menos que uno
+ * que abre un modal vacío. Las que resuelve la propia página (`href`/`openUrl`/`tab`) siempre se conservan.
+ */
+export function pruneUnavailableActions(spec: DocumentSpec, availableModelActions: Iterable<string>): DocumentSpec {
+    const have = new Set(availableModelActions)
+    return {
+        ...spec,
+        actions: spec.actions.filter((a) => a.href || a.openUrl || a.tab || have.has(a.modelAction ?? a.key)),
+    }
+}

package/src/document/format.ts

@@ -0,0 +1,59 @@
+import type { DocumentFieldDef } from './types'
+
+export interface FieldFormatOptions {
+    locale?: string
+    currency?: string
+    timeZone?: string
+}
+
+/** Formatea un valor de campo; vacío → «—». Moneda y zona horaria son config de la org, no se hardcodean. */
+export function formatFieldValue(
+    value: unknown,
+    format: DocumentFieldDef['format'] = 'text',
+    opts: FieldFormatOptions = {},
+): string {
+    if (value === null || value === undefined || value === '') return '—'
+    const locale = opts.locale || 'es-MX'
+    // Relación resuelta por el kernel: `{value,label}` o un objeto con `name`.
+    if (typeof value === 'object' && !(value instanceof Date)) {
+        const o = value as Record<string, unknown>
+        const text = o.label ?? o.name ?? o.title
+        return text == null || text === '' ? '—' : String(text)
+    }
+    switch (format) {
+        case 'money': {
+            const n = typeof value === 'number' ? value : parseFloat(String(value))
+            if (!Number.isFinite(n)) return '—'
+            try {
+                return new Intl.NumberFormat(locale, {
+                    style: 'currency',
+                    currency: opts.currency || 'USD',
+                }).format(n)
+            } catch {
+                return n.toFixed(2)
+            }
+        }
+        case 'percent': {
+            const n = typeof value === 'number' ? value : parseFloat(String(value))
+            return Number.isFinite(n) ? `${n}%` : '—'
+        }
+        case 'date':
+        case 'datetime': {
+            const d = new Date(String(value))
+            if (Number.isNaN(d.getTime())) return String(value)
+            try {
+                return new Intl.DateTimeFormat(locale, {
+                    dateStyle: 'medium',
+                    ...(format === 'datetime' ? { timeStyle: 'short' } : {}),
+                    timeZone: opts.timeZone || undefined,
+                }).format(d)
+            } catch {
+                return d.toISOString()
+            }
+        }
+        case 'boolean':
+            return value ? 'Sí' : 'No'
+        default:
+            return String(value)
+    }
+}

package/src/document/index.ts

@@ -0,0 +1,28 @@
+export * from './types'
+export {
+    MAX_VISIBLE_SECONDARY,
+    evaluatePredicate,
+    evaluateWhen,
+    interpolate,
+    pruneUnavailableActions,
+    readPath,
+    resolveActions,
+    resolveStatus,
+    resolveTitle,
+} from './evaluate'
+export { formatFieldValue, type FieldFormatOptions } from './format'
+export { StatusBadge, STATUS_TONE_STYLE, type StatusBadgeProps } from './status-badge'
+export { ActionBar, type ActionBarProps } from './action-bar'
+export { DocumentHeader, type DocumentHeaderProps, type HeaderBadge, type HeaderMetric } from './document-header'
+export { SmartButtons, type SmartButtonItem, type SmartButtonsProps } from './smart-buttons'
+export { DocumentTimeline, type DocumentTimelineProps, type TimelineEntry } from './document-timeline'
+export { CancelWithReason, type CancelPayload, type CancelReason, type CancelWithReasonProps } from './cancel-with-reason'
+export { DocumentPage, type DocumentPageProps } from './document-page'
+export { useDocumentSources, type DocumentSourcesState } from './use-document-sources'
+export {
+    clearDocumentPages,
+    findStatusMachine,
+    getDocumentPage,
+    registerDocumentPage,
+    type DocumentPageRegistration,
+} from './registry'

package/src/document/registry.ts

@@ -0,0 +1,39 @@
+// Registro por modelo de la «página de documento». Igual que
+// `registerModelExtension`: singleton de módulo, se registra una vez al arrancar
+// (o desde el `register()` federado de un addon) y la ruta de detalle del host
+// compone la página sin código por modelo.
+import type { DocumentContext, DocumentSpec, StatusMachine } from './types'
+
+export interface DocumentPageRegistration {
+    spec: DocumentSpec
+    /**
+     * Calcula derivados (`$.x`) a partir del registro y las fuentes cargadas —
+     * p. ej. el estado fiscal a partir de fiscal_documents y el de cobro a
+     * partir de saldo y vencimiento. Función pura, sin efectos.
+     */
+    derive?: (ctx: Omit<DocumentContext, 'derived'>) => Record<string, unknown>
+}
+
+const registry = new Map<string, DocumentPageRegistration>()
+
+/**
+ * Registra la página bajo `spec.model` y, opcionalmente, bajo alias (la ruta
+ * `/m/<model>` puede llegar como `invoices` o `Invoice` según el enlace).
+ */
+export function registerDocumentPage(reg: DocumentPageRegistration, aliases: string[] = []): void {
+    registry.set(reg.spec.model, reg)
+    for (const a of aliases) registry.set(a, reg)
+}
+
+export function getDocumentPage(model: string): DocumentPageRegistration | undefined {
+    return registry.get(model)
+}
+
+export function clearDocumentPages(): void {
+    registry.clear()
+}
+
+/** Catálogo compartido de estados por id de máquina (lo usan las columnas `status` de las pestañas). */
+export function findStatusMachine(spec: DocumentSpec, id: string): StatusMachine | undefined {
+    return spec.statuses.find((s) => s.id === id) ?? spec.catalogs?.find((s) => s.id === id)
+}

package/src/document/smart-buttons.tsx

@@ -0,0 +1,54 @@
+// SmartButtons — accesos con contador al estilo Odoo (Pagos (2) · REP (1) ·
+// Notas de crédito (0)…). Un botón sin registros se ve atenuado, no oculto,
+// salvo que la definición pida `hideWhenEmpty`.
+import { useTranslation } from 'react-i18next'
+import { cn } from '@asteby/metacore-ui/lib'
+import { DynamicIcon } from '../dynamic-icon'
+
+export interface SmartButtonItem {
+    key: string
+    label: string
+    icon?: string
+    /** undefined = botón sin contador (p. ej. «Pedido origen»). */
+    count?: number
+    /** Deshabilitado (sin destino / vacío). */
+    disabled?: boolean
+    onClick?: () => void
+}
+
+export interface SmartButtonsProps {
+    items: SmartButtonItem[]
+    className?: string
+}
+
+export function SmartButtons({ items, className }: SmartButtonsProps) {
+    const { t } = useTranslation()
+    if (items.length === 0) return null
+    return (
+        <nav aria-label={t('document.related', { defaultValue: 'Relacionados' })} className={cn('flex flex-wrap gap-2', className)} data-smart-buttons=''>
+            {items.map((it) => {
+                const empty = it.count === 0
+                return (
+                    <button
+                        key={it.key}
+                        type='button'
+                        disabled={it.disabled}
+                        onClick={it.onClick}
+                        data-smart-button={it.key}
+                        className={cn(
+                            'inline-flex items-center gap-2 rounded-md border bg-card px-3 py-1.5 text-sm transition-colors',
+                            'hover:bg-accent disabled:cursor-default disabled:opacity-50 disabled:hover:bg-card',
+                            empty && 'text-muted-foreground',
+                        )}
+                    >
+                        {it.icon ? <DynamicIcon name={it.icon} className='h-4 w-4' /> : null}
+                        <span>{t(it.label, { defaultValue: it.label })}</span>
+                        {it.count !== undefined ? (
+                            <span className='rounded-full bg-muted px-1.5 text-xs font-semibold tabular-nums'>{it.count}</span>
+                        ) : null}
+                    </button>
+                )
+            })}
+        </nav>
+    )
+}

package/src/document/status-badge.tsx

@@ -0,0 +1,44 @@
+// StatusBadge — badge semántico con texto explícito e ícono por tono: el color
+// nunca es la única señal (benchmark §6.3). El catálogo de estados de cada
+// documento vive en su `StatusMachine`; aquí solo se pinta.
+import { useTranslation } from 'react-i18next'
+import { AlertOctagon, AlertTriangle, CheckCircle2, Circle, Clock, Info, type LucideIcon } from 'lucide-react'
+import { Badge } from '@asteby/metacore-ui/primitives'
+import { cn } from '@asteby/metacore-ui/lib'
+import type { StatusDef, StatusTone } from './types'
+
+type BadgeVariant = 'muted' | 'info' | 'success' | 'warning' | 'danger'
+
+export const STATUS_TONE_STYLE: Record<StatusTone, { variant: BadgeVariant; icon: LucideIcon }> = {
+    neutral: { variant: 'muted', icon: Circle },
+    info: { variant: 'info', icon: Info },
+    success: { variant: 'success', icon: CheckCircle2 },
+    caution: { variant: 'warning', icon: Clock },
+    warning: { variant: 'warning', icon: AlertTriangle },
+    critical: { variant: 'danger', icon: AlertOctagon },
+}
+
+export interface StatusBadgeProps {
+    status: Pick<StatusDef, 'label' | 'tone' | 'strike'>
+    /** Descripción para lectores de pantalla («Estado fiscal»). */
+    srLabel?: string
+    className?: string
+}
+
+export function StatusBadge({ status, srLabel, className }: StatusBadgeProps) {
+    const { t } = useTranslation()
+    const style = STATUS_TONE_STYLE[status.tone] ?? STATUS_TONE_STYLE.neutral
+    const Icon = style.icon
+    const text = t(status.label, { defaultValue: status.label })
+    return (
+        <Badge
+            variant={style.variant}
+            data-tone={status.tone}
+            className={cn(status.strike && 'line-through', className)}
+        >
+            <Icon aria-hidden />
+            {srLabel ? <span className='sr-only'>{srLabel}: </span> : null}
+            {text}
+        </Badge>
+    )
+}

package/src/document/types.ts

@@ -0,0 +1,203 @@
+// Patrón «página de documento» (benchmark §5.2 / §6 / §7): cabecera con badges,
+// barra de acciones por estado, botones inteligentes con contador, pestañas e
+// historial. Todo se describe con un `DocumentSpec` de datos puros (sin
+// funciones) para que cualquier modelo lo declare y, más adelante, un manifest
+// pueda proyectarlo sin cambiar los componentes.
+import type { ReactNode } from 'react'
+
+/** Tono semántico de un estado. El color nunca es la única señal: cada tono trae ícono y texto. */
+export type StatusTone = 'neutral' | 'info' | 'success' | 'caution' | 'warning' | 'critical'
+
+/** Un estado del catálogo de un documento. */
+export interface StatusDef {
+    value: string
+    /** Texto explícito (o clave i18n; se traduce con `t`). */
+    label: string
+    tone: StatusTone
+    /** Texto tachado (Cancelada, Anulada): conserva el rastro sin alarmar. */
+    strike?: boolean
+}
+
+/** Una máquina de estados con su propio badge (p. ej. fiscal y cobro, independientes). */
+export interface StatusMachine {
+    id: string
+    /** Etiqueta accesible del badge («Estado fiscal»). */
+    label?: string
+    /** Ruta del valor en el contexto de evaluación (`record.x`, `$.x`). */
+    field: string
+    states: StatusDef[]
+    /** Estado a mostrar cuando el valor no está en el catálogo. */
+    fallback?: StatusDef
+}
+
+export type PredicateOp = 'eq' | 'neq' | 'in' | 'not_in' | 'truthy' | 'falsy' | 'gt' | 'gte' | 'lt' | 'lte'
+
+/** Condición sobre una ruta del contexto. Un arreglo de predicados es un AND. */
+export interface Predicate {
+    field: string
+    op: PredicateOp
+    value?: unknown
+}
+export type When = Predicate | Predicate[]
+
+/** Regla de bloqueo: si `when` se cumple, la acción se ve deshabilitada y `reason` explica qué hacer antes. */
+export interface BlockRule {
+    when: When
+    reason: string
+}
+
+/** Un botón del documento (acción). `key` enlaza con `ActionDefinition.key` del modelo si existe. */
+export interface DocumentActionDef {
+    key: string
+    label: string
+    /** Nombre de ícono lucide. */
+    icon?: string
+    /** Acción del modelo (metadata) que se dispara; por defecto `key`. */
+    modelAction?: string
+    /**
+     * Acciones que resuelve la propia página sin acción del modelo (las plantillas
+     * interpolan `{{campo}}` / `{{$.derivado}}`):
+     *  - `href`: navega dentro de la app (`onNavigate` del host).
+     *  - `openUrl`: abre una URL en otra pestaña (descargar PDF/XML).
+     *  - `tab`: selecciona una pestaña (ver detalle del error, ver pagos).
+     */
+    href?: string
+    openUrl?: string
+    tab?: string
+    /** Estilo crítico: siempre va en la zona destructiva. */
+    destructive?: boolean
+    /** Se muestra deshabilitada con el motivo en lugar de desaparecer. */
+    blockedWhen?: BlockRule | BlockRule[]
+    /** Se oculta por completo cuando se cumple (p. ej. sin permiso o sin conector). */
+    hiddenWhen?: When
+}
+
+/** Distribución de acciones para un estado (§5.4): 1 primaria, 2–3 secundarias, resto en «Más…». */
+export interface ActionLayout {
+    primary?: string
+    secondary?: string[]
+    more?: string[]
+    destructive?: string[]
+}
+
+/** Regla: si `when` se cumple, se usa `layout`. Gana la primera que coincide. */
+export interface ActionLayoutRule {
+    when: When
+    layout: ActionLayout
+}
+
+/** Botón inteligente con contador (estilo Odoo): navega a lo relacionado. */
+export interface SmartButtonDef {
+    key: string
+    label: string
+    icon?: string
+    /** Fuente (`DocumentSourceDef.key`) cuyo total alimenta el contador; sin ella no hay contador. */
+    source?: string
+    /** Ruta de un valor del registro cuyo truthy activa el botón sin fuente (p. ej. «Pedido origen»). */
+    field?: string
+    /** Modelo destino para navegar a la lista filtrada. */
+    href?: string
+    /** No se muestra cuando el contador es 0 (por defecto se muestra deshabilitado). */
+    hideWhenEmpty?: boolean
+    /** Selecciona esta pestaña al hacer clic. */
+    tab?: string
+}
+
+/** Consulta a un modelo relacionado con el registro (`{{id}}` se interpola). */
+export interface DocumentSourceDef {
+    key: string
+    model: string
+    /** Columna del modelo relacionado que apunta al registro. */
+    foreignKey: string
+    /** Filtros estáticos extra (`f_<col>=eq:<val>`). */
+    where?: Record<string, string>
+    limit?: number
+    /**
+     * Relación de dos saltos: en vez de filtrar por el id del registro, filtra
+     * `foreignKey` con los valores de `field` de las filas de otra fuente ya
+     * cargada (`via.source`). Ej.: los REP de una factura cuelgan del pago
+     * (`source_id = payment_id`), y los pagos salen de las aplicaciones.
+     */
+    via?: { source: string; field: string }
+}
+
+export interface DocumentFieldDef {
+    label: string
+    /** Ruta en el contexto. */
+    path: string
+    format?: 'text' | 'money' | 'date' | 'datetime' | 'mono' | 'percent' | 'boolean'
+    /** Ancho completo de la rejilla. */
+    wide?: boolean
+    /** Oculta el campo cuando el valor está vacío. */
+    hideEmpty?: boolean
+}
+
+export interface DocumentFieldGroup {
+    title?: string
+    fields: DocumentFieldDef[]
+}
+
+export interface DocumentColumnDef {
+    label: string
+    path: string
+    format?: DocumentFieldDef['format']
+    /** Catálogo de estados (id de máquina registrada) para pintar un badge. */
+    status?: string
+}
+
+export type DocumentTabDef =
+    | { key: string; label: string; kind: 'fields'; groups: DocumentFieldGroup[] }
+    | { key: string; label: string; kind: 'records'; source: string; columns: DocumentColumnDef[]; empty?: string }
+    | { key: string; label: string; kind: 'slot'; slot: string; count?: string }
+
+/** Métrica del encabezado (total, saldo, fechas…). */
+export interface DocumentMetricDef extends DocumentFieldDef {
+    tone?: 'default' | 'critical'
+}
+
+export interface DocumentSpec {
+    /** Clave del modelo (`invoices`). */
+    model: string
+    /** Rutas candidatas para el título, en orden; `{{a}}{{b}}` se interpola. */
+    title: string
+    /** Texto bajo el título (cliente…). */
+    subtitle?: DocumentFieldDef
+    /** Campo que se copia con botón (UUID). */
+    copyable?: DocumentFieldDef
+    /** Badges independientes (fiscal, cobro…). */
+    statuses: StatusMachine[]
+    /** Catálogos extra que solo pintan celdas de pestañas (`column.status`), sin badge en la cabecera. */
+    catalogs?: StatusMachine[]
+    metrics?: DocumentMetricDef[]
+    actions: DocumentActionDef[]
+    layouts: ActionLayoutRule[]
+    /** Layout si ninguna regla coincide. */
+    defaultLayout?: ActionLayout
+    smartButtons?: SmartButtonDef[]
+    sources?: DocumentSourceDef[]
+    tabs: DocumentTabDef[]
+}
+
+/** Contexto de evaluación: registro, fuentes cargadas y derivados. */
+export interface DocumentContext {
+    record: Record<string, unknown>
+    /** Filas por fuente (`sources[key]`). */
+    sources: Record<string, Record<string, unknown>[]>
+    /** Derivados (`$`). */
+    derived: Record<string, unknown>
+}
+
+export interface ResolvedAction {
+    def: DocumentActionDef
+    /** Motivo cuando la acción está bloqueada. */
+    blockedReason?: string
+}
+
+export interface ResolvedActionLayout {
+    primary?: ResolvedAction
+    secondary: ResolvedAction[]
+    more: ResolvedAction[]
+    destructive: ResolvedAction[]
+}
+
+export type DocumentSlotRenderer = (ctx: DocumentContext) => ReactNode