@asteby/metacore-runtime-react 47.0.0 → 48.0.0

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

package/src/row-action-stage-gate.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import { isActionAllowedForRowState, isRowActionVisible, lifecycleStageField } from './dynamic-columns'
+
+// Pitsline taller: WorkOrder has a stage machine (stage_field "stage") and its
+// row actions declare requiresState with STAGE keys. The kernel gates on the
+// stage column; the UI must do the same or every action is hidden (the OT
+// row/kanban menu showed only Ver/Editar/Eliminar).
+describe('requiresState gate with a stage machine', () => {
+    const process = { key: 'process', requiresState: ['reception', 'diagnosis', 'in_process'] }
+    const row = { id: '1', status: 'open', stage: 'diagnosis' }
+
+    it('reads the stage field when the model declares one', () => {
+        expect(isActionAllowedForRowState(process, row, 'stage')).toBe(true)
+        expect(isRowActionVisible(process, row, 'stage')).toBe(true)
+        expect(isActionAllowedForRowState(process, { ...row, stage: 'delivered' }, 'stage')).toBe(false)
+    })
+
+    it('keeps the historical status/state lookup without a stage field', () => {
+        expect(isActionAllowedForRowState(process, row)).toBe(false)
+        expect(isActionAllowedForRowState({ requiresState: ['open'] }, row)).toBe(true)
+    })
+
+    it('falls back to status when the stage value is blank', () => {
+        expect(isActionAllowedForRowState({ requiresState: ['open'] }, { status: 'open', stage: '' }, 'stage')).toBe(true)
+    })
+
+    it('resolves the stage field from metadata', () => {
+        expect(lifecycleStageField({ stage_field: 'stage' })).toBe('stage')
+        expect(lifecycleStageField({ stages: [{ key: 'a' }], group_by: 'stage' })).toBe('stage')
+        expect(lifecycleStageField({ group_by: 'status' })).toBeUndefined()
+        expect(lifecycleStageField(undefined)).toBeUndefined()
+    })
+})