@asteby/metacore-runtime-react 47.1.0 → 48.0.0

package/src/primitives/allocation.ts

@@ -0,0 +1,104 @@
+// PaymentAllocator — reglas puras para aplicar un pago a varios documentos
+// abiertos (CxC: facturas del cliente; CxP: facturas del proveedor).
+//
+// Lo usan: cobro multi-factura + REP (customers / fiscal_mexico), CxC
+// «Registrar abono», CxP «Aplicar pago», abonos de apartado. Sin React y sin
+// host: la UI (PaymentAllocator) y el backend (wasm) pueden validar con lo mismo.
+import { roundMoney } from '../business/format'
+
+/** Documento abierto con saldo. `installments_paid` = parcialidades previas vigentes. */
+export interface OpenDocument {
+    id: string
+    number: string
+    issued_at: string // ISO date
+    due_at?: string | null
+    total: number
+    balance: number
+    currency: string
+    /** `PPD` / `PUE` u otro: el núcleo no lo interpreta; fiscal_mexico sí. */
+    payment_method?: string | null
+    installments_paid?: number
+    /** Extensiones de país (UUID, serie…). Pasan intactas a la línea. */
+    extra?: Record<string, unknown>
+}
+
+export interface Allocation {
+    document_id: string
+    amount: number
+    /** Saldo anterior / pagado / insoluto: lo que pide el DoctoRelacionado del REP y el estado de cuenta. */
+    balance_before: number
+    balance_after: number
+    /** Número de parcialidad de ESTE pago para el documento (1-based). */
+    installment: number
+}
+
+export type AllocationStrategy = 'oldest_due_first' | 'oldest_issued_first' | 'manual'
+
+export interface AllocationResult {
+    allocations: Allocation[]
+    applied: number
+    unapplied: number
+}
+
+function sortKey(d: OpenDocument, s: AllocationStrategy): string {
+    return s === 'oldest_issued_first' ? d.issued_at : (d.due_at ?? d.issued_at)
+}
+
+/** Reparte `amount` sobre `docs` según la estrategia. `manual` respeta `manual[id]`. */
+export function allocatePayment(
+    amount: number,
+    docs: readonly OpenDocument[],
+    strategy: AllocationStrategy = 'oldest_due_first',
+    manual: Readonly<Record<string, number>> = {},
+): AllocationResult {
+    let left = roundMoney(Math.max(0, amount))
+    const ordered = strategy === 'manual' ? [...docs] : [...docs].sort((a, b) => sortKey(a, strategy).localeCompare(sortKey(b, strategy)))
+    const allocations: Allocation[] = []
+    for (const d of ordered) {
+        if (left <= 0) break
+        const balance = roundMoney(d.balance)
+        if (balance <= 0) continue
+        const want = strategy === 'manual' ? roundMoney(manual[d.id] ?? 0) : balance
+        const pay = roundMoney(Math.min(want, balance, left))
+        if (pay <= 0) continue
+        allocations.push({
+            document_id: d.id,
+            amount: pay,
+            balance_before: balance,
+            balance_after: roundMoney(balance - pay),
+            installment: (d.installments_paid ?? 0) + 1,
+        })
+        left = roundMoney(left - pay)
+    }
+    const applied = roundMoney(allocations.reduce((s, a) => s + a.amount, 0))
+    return { allocations, applied, unapplied: roundMoney(Math.max(0, amount) - applied) }
+}
+
+export interface AllocationIssue {
+    code: 'over_balance' | 'over_amount' | 'currency_mismatch' | 'unapplied' | 'non_positive'
+    document_id?: string
+    severity: 'error' | 'warning'
+}
+
+/** Revisión previa a guardar (la UI la pinta en ValidationChecklist; el backend la repite). */
+export function validateAllocation(
+    amount: number,
+    currency: string,
+    docs: readonly OpenDocument[],
+    allocations: readonly Allocation[],
+    opts: { allowUnapplied?: boolean } = {},
+): AllocationIssue[] {
+    const byId = new Map(docs.map(d => [d.id, d]))
+    const issues: AllocationIssue[] = []
+    if (amount <= 0) issues.push({ code: 'non_positive', severity: 'error' })
+    for (const a of allocations) {
+        const d = byId.get(a.document_id)
+        if (!d) continue
+        if (a.amount > roundMoney(d.balance) + 0.005) issues.push({ code: 'over_balance', document_id: d.id, severity: 'error' })
+        if (d.currency !== currency) issues.push({ code: 'currency_mismatch', document_id: d.id, severity: 'error' })
+    }
+    const applied = roundMoney(allocations.reduce((s, a) => s + a.amount, 0))
+    if (applied > roundMoney(amount) + 0.005) issues.push({ code: 'over_amount', severity: 'error' })
+    else if (applied < roundMoney(amount) - 0.005) issues.push({ code: 'unapplied', severity: opts.allowUnapplied ? 'warning' : 'error' })
+    return issues
+}

package/src/primitives/approvals.ts

@@ -0,0 +1,103 @@
+// ApprovalInbox — tipos y cliente de la bandeja de aprobaciones del kernel
+// (dynamic/approvals.go, rutas /approvals*). Una sola bandeja para TODO lo que
+// declare `supervisor_policy`, `approval` o un guard `on_violation:
+// request_approval`, sin importar el addon (descuentos, crédito, OC por monto,
+// cancelación CFDI, ajustes negativos…).
+import type { ApiClient } from '../api-context'
+
+/** Espejo de dynamic.ApprovalRequest (JSON). jsonb llega como string. */
+export interface ApprovalRequestDTO {
+    id: string
+    addon_key: string
+    model_key: string
+    record_id: string
+    action_key: string
+    constraint_key: string
+    kind: 'constraint' | 'action' | 'explicit' | 'pin'
+    label: string
+    status: 'pending' | 'approved' | 'applied' | 'failed' | 'rejected' | 'expired'
+    requested_by: string
+    requested_by_role: string
+    requested_at: string
+    expires_at: string | null
+    roles: string | string[]
+    reason_required: boolean
+    payload: string | Record<string, unknown>
+    snapshot: string | Record<string, unknown>
+    violation: string | Record<string, unknown>
+    decided_by: string | null
+    decided_at: string | null
+    reason: string
+    error: string
+}
+
+export interface ApprovalListQuery {
+    status?: ApprovalRequestDTO['status']
+    kind?: ApprovalRequestDTO['kind']
+    model?: string
+    /** Solo las que yo pedí. */
+    mine?: boolean
+    /** Solo las que mis roles pueden decidir (default de la bandeja). */
+    for_me?: boolean
+    page?: number
+    per_page?: number
+}
+
+/** Categoría visible en la bandeja. El mapeo policy → categoría es extensible por addons. */
+export interface ApprovalCategory {
+    key: string
+    label: string
+    icon?: string
+    /** Coincide si devuelve true (p. ej. por action_key, constraint_key o model_key). */
+    match: (r: ApprovalRequestDTO) => boolean
+}
+
+const categories: ApprovalCategory[] = []
+
+/** Los addons registran su categoría al cargar (purchases: «Compras», fiscal_mexico: «Cancelación CFDI»…). */
+export function registerApprovalCategory(c: ApprovalCategory): () => void {
+    categories.push(c)
+    return () => {
+        const i = categories.indexOf(c)
+        if (i >= 0) categories.splice(i, 1)
+    }
+}
+
+export function categorize(r: ApprovalRequestDTO): string {
+    return categories.find(c => c.match(r))?.key ?? 'other'
+}
+
+export function groupApprovals(items: readonly ApprovalRequestDTO[]): Record<string, ApprovalRequestDTO[]> {
+    const out: Record<string, ApprovalRequestDTO[]> = {}
+    for (const r of items) (out[categorize(r)] ??= []).push(r)
+    return out
+}
+
+export function parseJSONField<T = Record<string, unknown>>(v: string | T | null | undefined): T | null {
+    if (v == null || v === '') return null
+    if (typeof v !== 'string') return v
+    try {
+        return JSON.parse(v) as T
+    } catch {
+        return null
+    }
+}
+
+/** Cliente fino sobre las rutas del kernel; la UI lo usa vía useApi(). */
+export function approvalsClient(api: ApiClient) {
+    const qs = (q: ApprovalListQuery) =>
+        Object.entries(q)
+            .filter(([, v]) => v !== undefined && v !== '')
+            .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+            .join('&')
+    return {
+        list: async (q: ApprovalListQuery = { status: 'pending', for_me: true }) => {
+            const res = await api.get(`/approvals?${qs(q)}`)
+            return { items: (res.data?.data ?? []) as ApprovalRequestDTO[], total: Number(res.data?.meta?.total ?? 0) }
+        },
+        count: async () => Number((await api.get('/approvals/count')).data?.data?.count ?? 0),
+        approve: (id: string, reason?: string) => api.post(`/approvals/${id}/approve`, { reason }),
+        reject: (id: string, reason: string) => api.post(`/approvals/${id}/reject`, { reason }),
+        approveWithPin: (id: string, pin: string, reason: string) => api.post(`/approvals/${id}/approve-pin`, { pin, reason }),
+    }
+}

package/src/primitives/contributions.ts

@@ -0,0 +1,208 @@
+// Registro de contribuciones federadas — cómo un addon mete secciones,
+// columnas, modales, fuentes de «Cargar desde» y vistas previas en la pantalla
+// de OTRO addon sin que ese addon lo conozca.
+//
+// Se monta sobre slotRegistry (slot.tsx) — no es un segundo sistema: cada
+// contribución es un SlotEntry con id canónico `doc:<kind>:<region>` — y añade
+// lo que slot no tiene: `requiresAddon` (se oculta solo si el addon no está
+// instalado o se desinstala en caliente), orden estable, `when` por documento y
+// carga perezosa del componente (import() del remote federado).
+//
+// Contrato estable para remotes federados: los tipos de este archivo. Todo
+// `register*` devuelve un disposer; el AddonLoader lo llama al desmontar o
+// recargar el remote y la contribución desaparece sin recargar la página.
+import { createElement, lazy, Suspense, type ComponentType } from 'react'
+import { slotRegistry } from '../slot'
+
+/** Regiones del DocumentEditor/DocumentPage donde se puede contribuir. */
+export type DocumentRegion =
+    | 'header.fields' // campos extra del encabezado (Uso CFDI, Método, Forma…)
+    | 'party.card' // filas extra en PartyCard (RFC, régimen, CP, CSF)
+    | 'lines.columns' // columnas de LinesGrid (clave SAT, DOT, almacén)
+    | 'side.panels' // paneles laterales (Revisión, PreviewPanel, crédito)
+    | 'body.sections' // secciones bajo los renglones (Reingreso a stock, Relación CFDI)
+    | 'footer.actions' // botones del ActionBar (Timbrar, Pedir autorización)
+
+export interface DocumentEditorContext {
+    kind: string // 'invoice' | 'credit_note' | 'payment' | 'purchase_order' | …
+    model: string // 'customers.Invoice'
+    values: Record<string, unknown>
+    mode: 'create' | 'edit' | 'view'
+}
+
+export interface DocumentContribution<P = DocumentContributionProps> {
+    /** Id estable `addon.region.name` (dedupe y orden). Re-registrar el mismo id reemplaza. */
+    id: string
+    kinds: string[] | '*'
+    region: DocumentRegion
+    /** Addon dueño. Si no está instalado, no se renderiza (y el server revalida). */
+    requiresAddon?: string
+    /** Mayor = primero. Default 0. */
+    priority?: number
+    when?: (ctx: DocumentEditorContext) => boolean
+    /** Componente o loader perezoso del remote (`() => import('fiscal_mexico/CfdiSection')`). */
+    component?: ComponentType<P>
+    load?: () => Promise<{ default: ComponentType<P> }>
+}
+
+/**
+ * Contribución resuelta: `component` siempre presente (si se registró con
+ * `load`, es un envoltorio lazy + Suspense que no pinta nada mientras carga).
+ */
+export type ResolvedDocumentContribution<P = DocumentContributionProps> = DocumentContribution<P> & {
+    component: ComponentType<P>
+}
+
+export interface DocumentContributionProps {
+    ctx: DocumentEditorContext
+    setValue: (key: string, value: unknown) => void
+    issues: { report: (key: string, issue: { severity: 'error' | 'warning'; message: string }) => void }
+}
+
+/** Predicado «¿está instalado?»; `useInstalledAddons` lo arma en React. */
+export type IsAddonInstalled = (addonKey: string) => boolean
+
+interface Entry {
+    c: ResolvedDocumentContribution<any>
+    dispose: () => void
+}
+
+const contribs = new Map<string, Entry>()
+const listeners = new Set<() => void>()
+let version = 0
+
+function notify() {
+    version += 1
+    for (const l of [...listeners]) l()
+}
+
+/** Suscripción para useSyncExternalStore (contribuciones y modales). */
+export function subscribeContributions(listener: () => void): () => void {
+    listeners.add(listener)
+    return () => {
+        listeners.delete(listener)
+    }
+}
+
+/** Versión monotónica: cambia en cada register/dispose. */
+export function contributionsVersion(): number {
+    return version
+}
+
+export function slotIdFor(kind: string, region: DocumentRegion): string {
+    return `doc:${kind}:${region}`
+}
+
+/** `load` → componente lazy envuelto en Suspense (fallback vacío: sin saltos de layout). */
+function lazyComponent<P>(load: () => Promise<{ default: ComponentType<P> }>): ComponentType<P> {
+    const Lazy = lazy(load) as unknown as ComponentType<any>
+    return (props: P) => createElement(Suspense, { fallback: null }, createElement(Lazy, props as any))
+}
+
+/**
+ * Registra la contribución y la publica en slotRegistry bajo cada `doc:<kind>:<region>`
+ * (kinds '*' → `doc:*:<region>`). Devuelve el disposer: AddonLoader lo llama al
+ * desmontar o recargar el remote (fiber), así la sección desaparece al desinstalar.
+ * Re-registrar el mismo `id` (recarga en caliente) reemplaza la anterior.
+ */
+export function registerDocumentContribution<P = DocumentContributionProps>(c: DocumentContribution<P>, source?: string): () => void {
+    if (!c.component && !c.load) throw new Error(`contribution ${c.id}: component o load es obligatorio`)
+    contribs.get(c.id)?.dispose()
+    const resolved = { ...c, component: c.component ?? lazyComponent(c.load!) } as ResolvedDocumentContribution<any>
+    const kinds = c.kinds === '*' ? ['*'] : c.kinds
+    const slotDisposers = kinds.map(k =>
+        slotRegistry.register(slotIdFor(k, c.region), resolved.component as ComponentType, {
+            priority: c.priority ?? 0,
+            source: source ?? c.requiresAddon ?? c.id,
+        }),
+    )
+    let disposed = false
+    const entry: Entry = {
+        c: resolved,
+        dispose: () => {
+            if (disposed) return
+            disposed = true
+            slotDisposers.forEach(d => d())
+            if (contribs.get(c.id) === entry) contribs.delete(c.id)
+            notify()
+        },
+    }
+    contribs.set(c.id, entry)
+    notify()
+    return entry.dispose
+}
+
+/**
+ * Contribuciones aplicables a `region` para el documento `ctx`, ordenadas por
+ * prioridad (desc) y luego id. Pura: no lee React; `useDocumentContributions`
+ * la envuelve con useInstalledAddons.
+ */
+export function resolveContributions(
+    ctx: DocumentEditorContext,
+    region: DocumentRegion,
+    isInstalled: IsAddonInstalled,
+): ResolvedDocumentContribution<any>[] {
+    return [...contribs.values()]
+        .map(e => e.c)
+        .filter(c => c.region === region)
+        .filter(c => c.kinds === '*' || c.kinds.includes(ctx.kind))
+        .filter(c => !c.requiresAddon || isInstalled(c.requiresAddon))
+        .filter(c => !c.when || c.when(ctx))
+        .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0) || a.id.localeCompare(b.id))
+}
+
+// ---- Modales federados ------------------------------------------------------
+// ActionModalDispatcher resuelve `modal: "returns.settle_method"` con
+// requestFederatedAction (espera hasta 20 s). Este registro es su contraparte
+// declarativa: el addon registra la clave al cargar. Si el addon dueño no está
+// instalado, resolveFederatedModal devuelve null de inmediato y el dispatcher
+// usa el formulario genérico de la acción en vez de colgarse esperando.
+
+export interface FederatedModal<P = any> {
+    /** Clave `<addon>.<nombre>`, la misma que `modal` en el manifest. */
+    key: string // 'fiscal_mexico.import_cfdi'
+    addon: string
+    /** El dispatcher le pasa ActionModalProps (open, onOpenChange, action, model, record…). */
+    load: () => Promise<{ default: ComponentType<P> }>
+}
+
+const modals = new Map<string, FederatedModal>()
+const modalComponents = new WeakMap<FederatedModal, ComponentType<any>>()
+
+export function registerFederatedModal(m: FederatedModal): () => void {
+    modals.set(m.key, m)
+    notify()
+    return () => {
+        if (modals.get(m.key) === m) {
+            modals.delete(m.key)
+            notify()
+        }
+    }
+}
+
+/** null si el modal no está registrado o su addon no está instalado. Nunca espera. */
+export function resolveFederatedModal(key: string, isInstalled: IsAddonInstalled): FederatedModal | null {
+    const m = modals.get(key)
+    return m && isInstalled(m.addon) ? m : null
+}
+
+/**
+ * Componente `React.lazy` del modal resuelto, memoizado por registro (no se
+ * re-crea en cada render). Quien lo pinta lo envuelve en `<Suspense>`.
+ */
+export function federatedModalComponent<P = any>(m: FederatedModal<P>): ComponentType<P> {
+    let C = modalComponents.get(m)
+    if (!C) {
+        C = lazy(m.load) as unknown as ComponentType<any>
+        modalComponents.set(m, C)
+    }
+    return C as ComponentType<P>
+}
+
+/** Solo para tests. */
+export function __resetContributions(): void {
+    for (const e of [...contribs.values()]) e.dispose()
+    contribs.clear()
+    modals.clear()
+    notify()
+}

package/src/primitives/document-kinds.ts

@@ -0,0 +1,62 @@
+// DocumentKind — un registro de tipos de documento comercial para que
+// factura, cotización, pedido, OC, NC, cobro/REP, factura de proveedor y OT usen
+// el MISMO DocumentEditor / DocumentPage. Cada addon declara su tipo (desde el
+// manifest `document_forms` o con registerDocumentKind) y el editor arma:
+// contraparte, renglones, fuentes de «Cargar desde», totales y vista previa.
+import type { DocumentFormPreview, DocumentFormSource } from '../types'
+
+export type PartyRole = 'customer' | 'supplier' | 'none'
+export type LinesMode =
+    | 'sale' // precio de venta, descuento, impuesto (factura, cotización, pedido)
+    | 'purchase' // costo, recepción pendiente (OC, factura de proveedor)
+    | 'credit' // cantidades ≤ facturado − acreditado (NC, devolución)
+    | 'allocation' // documentos abiertos a pagar (cobro / REP / pago a proveedor)
+    | 'workorder' // servicio + refacción, técnico, horas (OT)
+    | 'none'
+
+export interface DocumentKind {
+    key: string
+    label: string
+    model: string // ModelKey canónico ('customers.Invoice')
+    party: PartyRole
+    partyModel?: string // 'customers.Customer' | 'purchases.Supplier'
+    lines: LinesMode
+    /** Campo de renglones del modelo (one_to_many) o del payload de la acción. */
+    linesField?: string
+    sources?: DocumentFormSource[]
+    preview?: DocumentFormPreview
+    /** Estados del documento (StageMachine): los muestra StageStepper. */
+    stages?: string[]
+    /** Addon dueño del tipo (si no está, el tipo no se ofrece). */
+    addon: string
+}
+
+const kinds = new Map<string, DocumentKind>()
+
+export function registerDocumentKind(k: DocumentKind): () => void {
+    kinds.set(k.key, k)
+    return () => {
+        if (kinds.get(k.key) === k) kinds.delete(k.key)
+    }
+}
+
+export function getDocumentKind(key: string): DocumentKind | undefined {
+    return kinds.get(key)
+}
+
+export function listDocumentKinds(isInstalled: (addon: string) => boolean): DocumentKind[] {
+    return [...kinds.values()].filter(k => isInstalled(k.addon))
+}
+
+/** Tipos base que el core ya tiene (modelos verificados en addons main 9cd69bde). */
+export const CORE_DOCUMENT_KINDS: DocumentKind[] = [
+    { key: 'invoice', label: 'Factura', model: 'customers.Invoice', party: 'customer', partyModel: 'customers.Customer', lines: 'sale', linesField: 'items', addon: 'customers' },
+    { key: 'quote', label: 'Cotización', model: 'quotes.Quote', party: 'customer', partyModel: 'customers.Customer', lines: 'sale', linesField: 'items', addon: 'quotes' },
+    { key: 'sales_order', label: 'Pedido', model: 'customers.SalesOrder', party: 'customer', partyModel: 'customers.Customer', lines: 'sale', linesField: 'items', addon: 'customers' },
+    { key: 'payment', label: 'Cobro', model: 'customers.Payment', party: 'customer', partyModel: 'customers.Customer', lines: 'allocation', linesField: 'allocations', addon: 'customers' },
+    { key: 'credit_note', label: 'Nota de crédito', model: 'fiscal_mexico.CreditNote', party: 'customer', partyModel: 'customers.Customer', lines: 'credit', linesField: 'lines', addon: 'fiscal_mexico' },
+    { key: 'purchase_order', label: 'Orden de compra', model: 'purchases.PurchaseOrder', party: 'supplier', partyModel: 'purchases.Supplier', lines: 'purchase', linesField: 'items', addon: 'purchases' },
+    { key: 'supplier_invoice', label: 'Factura de proveedor', model: 'purchases.SupplierInvoice', party: 'supplier', partyModel: 'purchases.Supplier', lines: 'purchase', addon: 'purchases' },
+    { key: 'supplier_payment', label: 'Pago a proveedor', model: 'purchases.PurchasePayment', party: 'supplier', partyModel: 'purchases.Supplier', lines: 'allocation', addon: 'purchases' },
+    { key: 'work_order', label: 'Orden de trabajo', model: 'workshop.WorkOrder', party: 'customer', partyModel: 'customers.Customer', lines: 'workorder', linesField: 'items', addon: 'workshop' },
+]

package/src/primitives/index.ts

@@ -0,0 +1,23 @@
+// Primitivos de negocio — contrato estable para hosts y remotes federados.
+// Las funciones son puras (sin React ni host) salvo use-contributions; la UI y
+// el backend (wasm) pueden validar con las mismas reglas.
+//
+//  allocation       PaymentAllocator: allocatePayment / validateAllocation
+//                   (cobro multi-factura, REP, CxC «Registrar abono», CxP «Aplicar pago»).
+//  aging            AgingTable: computeAging / daysOverdue / bucketFor (antigüedad de saldos).
+//  approvals        ApprovalInbox: approvalsClient (rutas /approvals del kernel),
+//                   registerApprovalCategory / groupApprovals.
+//  contributions    Secciones y modales federados: registerDocumentContribution,
+//                   resolveContributions (pura), registerFederatedModal /
+//                   resolveFederatedModal. Todo register* devuelve su disposer.
+//  document-kinds   registerDocumentKind / listDocumentKinds / CORE_DOCUMENT_KINDS.
+//  panels           Tipos de PartyCard / TotalsPanel / PreviewPanel /
+//                   ValidationChecklist / LoadFromDocument + blockingChecks.
+//  use-contributions  Hooks: useDocumentContributions, useIsAddonInstalled.
+export * from './allocation'
+export * from './aging'
+export * from './approvals'
+export * from './contributions'
+export * from './document-kinds'
+export * from './panels'
+export * from './use-contributions'

package/src/primitives/panels.ts

@@ -0,0 +1,59 @@
+// Contratos de los paneles del DocumentEditor. Los componentes viven en
+// business/ (PartyCard, LinesGrid = DocumentLinesGrid, TotalsPanel,
+// PreviewPanel, LoadFromDocument); aquí solo los tipos para que cualquier
+// addon remoto los use sin depender de la implementación.
+import type { LineItemsTotals } from '../business/line-items'
+
+/** PartyCard: lo que se muestra de la contraparte. */
+export interface PartySummary {
+    id: string
+    name: string
+    tax_id?: string
+    email?: string
+    phone?: string
+    currency?: string
+    /** Filas extra (incluye las de extensiones `fiscal_data.*`). */
+    rows: Array<{ key: string; label: string; value: string; tone?: 'ok' | 'warn' | 'err' }>
+    credit?: { limit: number; balance: number; available: number; overdue: number; status?: 'active' | 'suspended' | 'delinquent'; hold_reason?: string }
+}
+
+/** TotalsPanel: desglose; los impuestos por tasa los aporta el addon fiscal o el core. */
+export interface TotalsBreakdown extends LineItemsTotals {
+    taxes: Array<{ label: string; base: number; amount: number }>
+    /** Renglones extra (aplicaciones, saldo a favor, sin aplicar…). */
+    extra?: Array<{ label: string; amount: number; emphasis?: boolean }>
+    amount_in_words?: string
+}
+
+/** PreviewPanel: resultado de la acción de vista previa (`analyze: true`, no escribe). */
+export interface PreviewResult {
+    pdf_base64?: string
+    xml?: string
+    html?: string
+    checks: ValidationCheck[]
+}
+
+/** ValidationChecklist: una revisión (local o del servidor). */
+export interface ValidationCheck {
+    key: string
+    severity: 'ok' | 'warning' | 'error'
+    message: string
+    /** Campo a enfocar al hacer clic. */
+    field?: string
+    /** Si es error y `approval_policy` está, el botón ofrece «Pedir autorización». */
+    approval_policy?: string
+}
+
+/** LoadFromDocument: candidato a cargar (venta, cotización, ticket, OT, factura origen de NC). */
+export interface LoadCandidate {
+    source: string // DocumentFormSource.key
+    id: string
+    label: string
+    party_id?: string
+    total?: number
+    state?: string
+}
+
+export function blockingChecks(checks: readonly ValidationCheck[]): ValidationCheck[] {
+    return checks.filter(c => c.severity === 'error' && !c.approval_policy)
+}

package/src/primitives/use-contributions.ts

@@ -0,0 +1,42 @@
+// Hooks de React sobre el registro de contribuciones (contributions.ts).
+// La lógica vive en las funciones puras; aquí solo se conecta con
+// useInstalledAddons y con la suscripción para re-pintar cuando un remote
+// registra o se desmonta.
+import { useMemo, useSyncExternalStore } from 'react'
+import { useInstalledAddons, type InstalledAddonsValue } from '../installed-addons-context'
+import {
+    contributionsVersion,
+    resolveContributions,
+    subscribeContributions,
+    type DocumentEditorContext,
+    type DocumentRegion,
+    type IsAddonInstalled,
+    type ResolvedDocumentContribution,
+} from './contributions'
+
+/**
+ * Predicado de instalación a partir del InstalledAddonsProvider. Sin provider
+ * devuelve siempre true: el host solo carga remotes de addons instalados, así
+ * que si la contribución existe, su addon está (el servidor revalida igual).
+ */
+export function installedPredicate(value: InstalledAddonsValue | null): IsAddonInstalled {
+    return value ? (key: string) => value.addons.has(key) : () => true
+}
+
+/** `installedPredicate(useInstalledAddons())`, estable entre renders. */
+export function useIsAddonInstalled(): IsAddonInstalled {
+    const value = useInstalledAddons()
+    return useMemo(() => installedPredicate(value), [value])
+}
+
+/** Re-pinta en cada register/dispose de contribuciones o modales federados. */
+export function useContributionsVersion(): number {
+    return useSyncExternalStore(subscribeContributions, contributionsVersion, contributionsVersion)
+}
+
+/** Contribuciones aplicables a `region` del documento `ctx` (ya filtradas y ordenadas). */
+export function useDocumentContributions(ctx: DocumentEditorContext, region: DocumentRegion): ResolvedDocumentContribution<any>[] {
+    useContributionsVersion()
+    const isInstalled = useIsAddonInstalled()
+    return resolveContributions(ctx, region, isInstalled)
+}

package/src/record-prefill-bar.tsx

@@ -0,0 +1,62 @@
+// RecordPrefillBar — pinta los ayudantes de captura (record-prefill-registry de
+// @asteby/metacore-sdk) arriba del formulario genérico de un modelo.
+//
+// El formulario no conoce a los addons: sólo pregunta "¿quién aporta prefill
+// para <model> en <mode>?". Hoy: fiscal_mexico → «Cargar constancia» en
+// Customer/Supplier. Mañana: un vertical restaurante aporta «Importar menú» en
+// Product, un vertical ferretería «Leer código de proveedor», etc.
+//
+// Seguridad del patch: sólo se aplican claves que el formulario declara
+// (allowedKeys) — un addon no puede inyectar columnas ocultas (organization_id,
+// created_by…) por esta vía; el backend sigue validando como siempre.
+import { useCallback, useSyncExternalStore } from 'react'
+import {
+    getRecordPrefills,
+    recordPrefillsVersion,
+    subscribeRecordPrefills,
+    type RecordFormMode,
+} from '@asteby/metacore-sdk'
+import { useCan } from './permissions-context'
+
+export interface RecordPrefillBarProps {
+    model: string
+    mode: RecordFormMode
+    recordId?: string | null
+    values: Record<string, any>
+    allowedKeys: ReadonlySet<string>
+    onApply: (patch: Record<string, any>) => void
+}
+
+export function RecordPrefillBar({ model, mode, recordId, values, allowedKeys, onApply }: RecordPrefillBarProps) {
+    // Re-render cuando un remote registra/des-registra (carga tardía o unbind).
+    useSyncExternalStore(subscribeRecordPrefills, recordPrefillsVersion, recordPrefillsVersion)
+    const can = useCan()
+    const items = getRecordPrefills(model, mode).filter(c => !c.permission || can(c.permission))
+
+    const applyValues = useCallback(
+        (patch: Record<string, unknown>) => {
+            const safe: Record<string, any> = {}
+            for (const [k, v] of Object.entries(patch ?? {})) {
+                if (allowedKeys.has(k)) safe[k] = v
+            }
+            if (Object.keys(safe).length > 0) onApply(safe)
+        },
+        [allowedKeys, onApply],
+    )
+
+    if (items.length === 0) return null
+    return (
+        <div className="flex flex-wrap items-center gap-2" data-aby-record-prefill="">
+            {items.map(({ id, component: C }) => (
+                <C
+                    key={id}
+                    model={model}
+                    mode={mode}
+                    recordId={recordId ?? undefined}
+                    values={values}
+                    applyValues={applyValues}
+                />
+            ))}
+        </div>
+    )
+}