@asteby/metacore-runtime-react 45.0.0 → 45.2.0

package/src/document/document-page.tsx

@@ -0,0 +1,268 @@
+// DocumentPage — «página de documento» declarativa (benchmark §5.2 / §6.1):
+// cabecera + badges + barra de acciones por estado + botones inteligentes +
+// pestañas. Se alimenta de un `DocumentSpec` (datos puros) y de un registro;
+// las pestañas de campos y de registros relacionados se resuelven solas, y lo
+// que necesita UI del host (historial, archivos, PDF) entra por `slots`.
+import { useMemo, useState, type ReactNode } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@asteby/metacore-ui/primitives'
+import { cn } from '@asteby/metacore-ui/lib'
+import { ActionBar } from './action-bar'
+import { DocumentHeader, type HeaderBadge, type HeaderMetric } from './document-header'
+import { SmartButtons, type SmartButtonItem } from './smart-buttons'
+import { StatusBadge } from './status-badge'
+import { interpolate, readPath, resolveActions, resolveStatus, resolveTitle } from './evaluate'
+import { formatFieldValue, type FieldFormatOptions } from './format'
+import { findStatusMachine, type DocumentPageRegistration } from './registry'
+import { useDocumentSources } from './use-document-sources'
+import type {
+    DocumentColumnDef,
+    DocumentContext,
+    DocumentFieldDef,
+    DocumentSlotRenderer,
+    DocumentSpec,
+    DocumentTabDef,
+    ResolvedAction,
+} from './types'
+
+export interface DocumentPageProps extends FieldFormatOptions {
+    registration: DocumentPageRegistration
+    record: Record<string, unknown>
+    /**
+     * Ejecuta una acción. El host decide: abrir el modal de la acción del
+     * modelo (`def.modelAction ?? def.key`), navegar (`def.href`), etc. La
+     * promesa mantiene el botón en `loading`.
+     */
+    onAction: (action: ResolvedAction, ctx: DocumentContext) => void | Promise<unknown>
+    /** UI del host para pestañas `kind: 'slot'` (historial, archivos, vista previa PDF…). */
+    slots?: Record<string, DocumentSlotRenderer>
+    /** Navegación del host (botones inteligentes, cliente). */
+    onNavigate?: (href: string) => void
+    renderLink?: (props: { href: string; children: ReactNode; className?: string }) => ReactNode
+    /** Botón «Volver» u otro contenido antes del título. */
+    leading?: ReactNode
+    /** Pestaña inicial (`?tab=`). */
+    defaultTab?: string
+    /** Pestaña controlada por el host (p. ej. «Ver detalle del error» abre Datos fiscales). */
+    tab?: string
+    onTabChange?: (tab: string) => void
+    /** Ruta base para el enlace del subtítulo (`/m/customers/{{customer_id}}`). */
+    subtitleHrefTemplate?: string
+    /** Cambia para forzar recarga de las fuentes tras una acción. */
+    reloadKey?: number
+    className?: string
+}
+
+export function DocumentPage(props: DocumentPageProps) {
+    const { registration, record, onAction, slots, onNavigate, renderLink, leading, defaultTab, className } = props
+    const { spec } = registration
+    const { t } = useTranslation()
+    const fmt: FieldFormatOptions = { locale: props.locale, currency: props.currency, timeZone: props.timeZone }
+
+    const recordId = record.id as string | number | undefined
+    const { sources, reload } = useDocumentSources(spec.sources, recordId)
+
+    const ctx: DocumentContext = useMemo(() => {
+        const base = { record, sources }
+        return { ...base, derived: registration.derive?.(base) ?? {} }
+    }, [record, sources, registration])
+
+    // Recarga las fuentes cuando el host avisa de un cambio (acción ejecutada).
+    const [lastReload, setLastReload] = useState(props.reloadKey ?? 0)
+    if ((props.reloadKey ?? 0) !== lastReload) {
+        setLastReload(props.reloadKey ?? 0)
+        reload()
+    }
+
+    const handleAction = (a: ResolvedAction) => {
+        const { tab: targetTab, openUrl, href } = a.def
+        if (targetTab) return setTab(targetTab)
+        if (openUrl) {
+            const url = interpolate(openUrl, ctx)
+            if (url) window.open(url, '_blank', 'noopener,noreferrer')
+            return
+        }
+        if (href) return onNavigate?.(interpolate(href, ctx))
+        return onAction(a, ctx)
+    }
+
+    const layout = useMemo(() => resolveActions(spec, ctx), [spec, ctx])
+
+    const badges: HeaderBadge[] = spec.statuses
+        .map((m): HeaderBadge | null => {
+            const status = resolveStatus(m, ctx)
+            return status ? { id: m.id, label: m.label, status } : null
+        })
+        .filter((b): b is HeaderBadge => !!b)
+
+    const metrics: HeaderMetric[] = (spec.metrics ?? [])
+        .filter((m) => !m.hideEmpty || readPath(ctx, m.path) != null)
+        .map((m) => ({
+            label: t(m.label, { defaultValue: m.label }),
+            value: formatFieldValue(readPath(ctx, m.path), m.format, fmt),
+            tone: m.tone,
+            mono: m.format === 'mono',
+        }))
+
+    const subtitleRaw = spec.subtitle ? readPath(ctx, spec.subtitle.path) : undefined
+    const subtitleText = subtitleRaw == null || subtitleRaw === '' ? '—' : formatFieldValue(subtitleRaw, 'text', fmt)
+    const subtitle = subtitleText === '—' ? undefined : subtitleText
+    const subtitleHref = subtitle && props.subtitleHrefTemplate ? interpolate(props.subtitleHrefTemplate, ctx) : undefined
+
+    const copyValue = spec.copyable ? readPath(ctx, spec.copyable.path) : undefined
+
+    const [innerTab, setInnerTab] = useState(defaultTab ?? spec.tabs[0]?.key)
+    const tab = props.tab ?? innerTab
+    const setTab = (key: string) => {
+        setInnerTab(key)
+        props.onTabChange?.(key)
+    }
+
+    const smart: SmartButtonItem[] = (spec.smartButtons ?? [])
+        .map((b): SmartButtonItem | null => {
+            const count = b.source ? sources[b.source]?.length ?? 0 : undefined
+            const active = b.source ? (count ?? 0) > 0 : b.field ? !!readPath(ctx, b.field) : true
+            if (b.hideWhenEmpty && !active) return null
+            const href = b.href ? interpolate(b.href, ctx) : undefined
+            return {
+                key: b.key,
+                label: b.label,
+                icon: b.icon,
+                count,
+                disabled: !active && !b.tab,
+                onClick: () => {
+                    if (b.tab) setTab(b.tab)
+                    else if (href) onNavigate?.(href)
+                },
+            }
+        })
+        .filter((b): b is SmartButtonItem => !!b)
+
+    return (
+        <div className={cn('flex flex-col gap-4', className)} data-document-page={spec.model}>
+            <DocumentHeader
+                title={resolveTitle(spec.title, ctx) || t('document.untitled', { defaultValue: 'Documento' })}
+                subtitle={subtitle}
+                subtitleHref={subtitleHref}
+                badges={badges}
+                metrics={metrics}
+                copyable={
+                    spec.copyable && copyValue
+                        ? { label: t(spec.copyable.label, { defaultValue: spec.copyable.label }), value: String(copyValue) }
+                        : undefined
+                }
+                leading={leading}
+                renderLink={renderLink}
+                actions={<ActionBar layout={layout} onAction={(a) => handleAction(a)} />}
+            />
+
+            <SmartButtons items={smart} />
+
+            <Tabs value={tab} onValueChange={setTab} className='flex flex-col gap-4'>
+                <TabsList className='w-fit'>
+                    {spec.tabs.map((tb) => (
+                        <TabsTrigger key={tb.key} value={tb.key}>
+                            {t(tb.label, { defaultValue: tb.label })}
+                            {tabCount(tb, ctx) !== undefined ? (
+                                <span className='ml-1.5 rounded-full bg-muted px-1.5 text-xs tabular-nums'>{tabCount(tb, ctx)}</span>
+                            ) : null}
+                        </TabsTrigger>
+                    ))}
+                </TabsList>
+                {spec.tabs.map((tb) => (
+                    <TabsContent key={tb.key} value={tb.key} className='mt-0'>
+                        {renderTab(tb, spec, ctx, fmt, slots)}
+                    </TabsContent>
+                ))}
+            </Tabs>
+        </div>
+    )
+}
+
+function tabCount(tb: DocumentTabDef, ctx: DocumentContext): number | undefined {
+    if (tb.kind === 'records') return ctx.sources[tb.source]?.length
+    if (tb.kind === 'slot' && tb.count) {
+        const v = readPath(ctx, tb.count)
+        return typeof v === 'number' ? v : undefined
+    }
+    return undefined
+}
+
+function renderTab(
+    tb: DocumentTabDef,
+    spec: DocumentSpec,
+    ctx: DocumentContext,
+    fmt: FieldFormatOptions,
+    slots: Record<string, DocumentSlotRenderer> | undefined,
+): ReactNode {
+    if (tb.kind === 'slot') return slots?.[tb.slot]?.(ctx) ?? null
+    if (tb.kind === 'fields') {
+        return (
+            <div className='flex flex-col gap-4'>
+                {tb.groups.map((g, i) => {
+                    const fields = g.fields.filter((f: DocumentFieldDef) => !f.hideEmpty || readPath(ctx, f.path) != null)
+                    if (fields.length === 0) return null
+                    return (
+                        <section key={g.title ?? i} className='rounded-lg border bg-card p-5'>
+                            {g.title ? <h2 className='mb-3 text-sm font-semibold'>{g.title}</h2> : null}
+                            <dl className='grid grid-cols-1 gap-x-6 gap-y-3 sm:grid-cols-2 lg:grid-cols-3'>
+                                {fields.map((f) => (
+                                    <div key={f.path} className={cn(f.wide && 'sm:col-span-2 lg:col-span-3')}>
+                                        <dt className='text-xs uppercase tracking-wide text-muted-foreground'>{f.label}</dt>
+                                        <dd className={cn('break-words font-medium', f.format === 'mono' && 'font-mono text-xs')}>
+                                            {formatFieldValue(readPath(ctx, f.path), f.format, fmt)}
+                                        </dd>
+                                    </div>
+                                ))}
+                            </dl>
+                        </section>
+                    )
+                })}
+            </div>
+        )
+    }
+    const rows = ctx.sources[tb.source] ?? []
+    if (rows.length === 0) {
+        return (
+            <p className='rounded-md border border-dashed p-6 text-center text-sm text-muted-foreground'>
+                {tb.empty ?? 'Sin registros.'}
+            </p>
+        )
+    }
+    return (
+        <div className='overflow-x-auto rounded-lg border bg-card'>
+            <table className='w-full text-sm'>
+                <thead className='bg-muted/40 text-left text-xs uppercase tracking-wide text-muted-foreground'>
+                    <tr>
+                        {tb.columns.map((c) => (
+                            <th key={c.path} className='px-3 py-2 font-medium'>{c.label}</th>
+                        ))}
+                    </tr>
+                </thead>
+                <tbody>
+                    {rows.map((row, i) => (
+                        <tr key={String(row.id ?? i)} className='border-t'>
+                            {tb.columns.map((c) => (
+                                <td key={c.path} className='px-3 py-2'>{renderCell(c, row, spec, fmt)}</td>
+                            ))}
+                        </tr>
+                    ))}
+                </tbody>
+            </table>
+        </div>
+    )
+}
+
+function renderCell(col: DocumentColumnDef, row: Record<string, unknown>, spec: DocumentSpec, fmt: FieldFormatOptions): ReactNode {
+    const v = row[col.path]
+    if (col.status) {
+        const machine = findStatusMachine(spec, col.status)
+        const st = machine?.states.find((s) => s.value === String(v))
+        if (st) return <StatusBadge status={st} />
+    }
+    return (
+        <span className={cn(col.format === 'mono' && 'font-mono text-xs', 'tabular-nums')}>
+            {formatFieldValue(v, col.format, fmt)}
+        </span>
+    )
+}

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)
+}