@asteby/metacore-runtime-react 47.1.0 → 49.0.0

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-actions.ts

@@ -0,0 +1,101 @@
+// Acciones primarias / secundarias de un registro.
+//
+// Una pantalla de registro tiene UNA acción destacada (la primaria) y el resto
+// en su lugar: lo de compartir, imprimir, correo, chat, descargar PDF/XML es
+// secundario — va al pie del documento (DocumentSecondaryBar) y al «Más…» del
+// menú de fila, nunca compitiendo con la primaria.
+//
+// Dos fuentes, una misma clasificación:
+//   - acciones del modelo (metadata `actions[]`): manifest v3 `priority`, o la
+//     convención por clave si no la declara;
+//   - acciones aportadas por addons o por el host (registerRecordAction del
+//     store canónico de @asteby/metacore-sdk), filtradas por su proveedor
+//     instalado y activo (InstalledAddonsProvider).
+import { useMemo, useSyncExternalStore } from 'react'
+import {
+    listRecordActions,
+    subscribeActionComponents,
+    type ActionPriority,
+    type OwnedRecordAction,
+    type RecordActionContext,
+    type RecordActionContribution,
+} from '@asteby/metacore-sdk'
+import { useInstalledAddons, type InstalledAddonsValue } from './installed-addons-context'
+
+export * from './action-priority'
+export type { RecordActionContext, RecordActionContribution }
+
+export interface ResolvedRecordAction {
+    /** Id de la contribución (o `<id>:<item>` si viene de `expand`). */
+    key: string
+    label: string
+    icon?: string
+    priority: ActionPriority
+    owner?: string
+    run?: () => unknown
+    render?: RecordActionContribution['render']
+}
+
+function modelMatches(models: RecordActionContribution['models'], model: string): boolean {
+    if (!models || models === '*') return true
+    const m = model.toLowerCase()
+    return models.some((x) => {
+        const k = x.toLowerCase()
+        return k === m || k.endsWith(`.${m}`) || m.endsWith(`.${k}`)
+    })
+}
+
+/** ¿El proveedor de la contribución está instalado y activo? Sin provider: sí. */
+export function isRecordActionProviderActive(row: OwnedRecordAction, installed: InstalledAddonsValue | null): boolean {
+    if (!installed) return true
+    const req = row.contribution.requires
+    if (req?.addon && !installed.addons.has(req.addon)) return false
+    if (req?.capability && !installed.capabilities.has(req.capability)) return false
+    if (!req?.addon && !req?.capability && row.owner && !installed.addons.has(row.owner)) return false
+    return true
+}
+
+/** Contribuciones aplicables al registro, filtradas por proveedor y ordenadas. Pura. */
+export function resolveRecordActions(
+    rows: readonly OwnedRecordAction[],
+    ctx: RecordActionContext,
+    installed: InstalledAddonsValue | null,
+): ResolvedRecordAction[] {
+    const out: ResolvedRecordAction[] = []
+    const sorted = [...rows].sort(
+        (a, b) => (a.contribution.order ?? 0) - (b.contribution.order ?? 0) || a.contribution.id.localeCompare(b.contribution.id),
+    )
+    for (const row of sorted) {
+        const c = row.contribution
+        if (!modelMatches(c.models, ctx.model)) continue
+        if (!isRecordActionProviderActive(row, installed)) continue
+        if (c.when && !c.when(ctx)) continue
+        const priority = c.priority ?? 'secondary'
+        if (c.expand) {
+            for (const item of c.expand(ctx)) {
+                out.push({ key: `${c.id}:${item.key}`, label: item.label, icon: item.icon ?? c.icon, priority, owner: row.owner, run: item.run })
+            }
+            continue
+        }
+        out.push({
+            key: c.id,
+            label: c.label ?? c.id,
+            icon: c.icon,
+            priority,
+            owner: row.owner,
+            run: c.run ? () => c.run!(ctx) : undefined,
+            render: c.render,
+        })
+    }
+    return out
+}
+
+/** Acciones aportadas al registro (`model`, `record`), reactivas a register/unbind. */
+export function useRecordActions(model: string, record: Record<string, unknown> | null | undefined): ResolvedRecordAction[] {
+    const rows = useSyncExternalStore(subscribeActionComponents, listRecordActions, listRecordActions)
+    const installed = useInstalledAddons()
+    return useMemo(
+        () => (record ? resolveRecordActions(rows, { model, record }, installed) : []),
+        [rows, model, record, installed],
+    )
+}

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

package/src/row-actions-menu.tsx

@@ -0,0 +1,159 @@
+// RowActionsMenu — el «…» de una fila: la acción primaria (si hay) arriba y
+// destacada, las principales debajo y las secundarias (compartir, imprimir,
+// correo, chat, PDF/XML y lo que aporten addons vía registerRecordAction)
+// agrupadas en un «Más…» discreto. Una acción por capacidad sin proveedor
+// activo, o una contribución cuyo addon no está instalado, no aparece.
+//
+// DynamicTable lo usa por defecto (getDynamicColumns) y los hosts que arman su
+// propia columna de acciones lo reutilizan en vez de duplicar el menú.
+import * as React from 'react'
+import { useTranslation } from 'react-i18next'
+import { MoreHorizontal } from 'lucide-react'
+// Root entry on purpose (not '/primitives'): see dropdown-menu-entry.test.ts.
+import {
+    Button,
+    DropdownMenu,
+    DropdownMenuContent,
+    DropdownMenuItem,
+    DropdownMenuSeparator,
+    DropdownMenuSub,
+    DropdownMenuSubContent,
+    DropdownMenuSubTrigger,
+    DropdownMenuTrigger,
+} from '@asteby/metacore-ui'
+import { DynamicIcon } from './dynamic-icon'
+import { translateMetadataLabel } from './dynamic-columns-helpers'
+import { RequiresAddonLock, resolveRequiresAddon, useRequiresAddonLabel } from './requires-addon'
+import { useInstalledAddons } from './installed-addons-context'
+import { isActionProviderActive, splitActionsByPriority, useRecordActions, type ResolvedRecordAction } from './record-actions'
+
+/**
+ * One entry of the row "…" menu. An action gated by a missing optional addon
+ * (`requiresAddon`) stays listed with a lock + tooltip; the click still goes to
+ * `onAction`, whose shared handler (useDynamicRowActions) opens the
+ * requires-addon dialog instead of executing.
+ */
+export function RowActionMenuItem({
+    action,
+    label,
+    onSelect,
+    className,
+}: {
+    action: any
+    label: React.ReactNode
+    onSelect: (e: React.MouseEvent) => void
+    className?: string
+}) {
+    const requirement = resolveRequiresAddon(action)
+    const requiresAddonLabel = useRequiresAddonLabel()
+    return (
+        <DropdownMenuItem
+            onClick={onSelect}
+            title={requirement ? requiresAddonLabel(requirement) : undefined}
+            data-requires-addon={requirement?.key}
+            data-action={action.key}
+            className={className}
+        >
+            <DynamicIcon name={action.icon || 'Zap'} className="mr-2 h-4 w-4" />
+            {label}
+            {requirement && <RequiresAddonLock requirement={requirement} />}
+        </DropdownMenuItem>
+    )
+}
+
+export interface RowActionsMenuProps {
+    /** Acciones de metadata ya filtradas por estado/condición de la fila. */
+    actions: any[]
+    row: Record<string, any>
+    /** Modelo de la fila: resuelve las acciones aportadas por addons. */
+    model?: string
+    onAction?: (actionKey: string, row: any) => void
+    /** Sustituye el ícono del disparador (p. ej. un spinner mientras imprime). */
+    triggerIcon?: React.ReactNode
+    disabled?: boolean
+}
+
+/**
+ * Modelo de las filas que pinta la tabla. DynamicTable lo provee: la factoría
+ * de columnas (getDynamicColumns) no recibe el modelo y el menú lo necesita
+ * para resolver las acciones aportadas por addons.
+ */
+export const RowActionsModelContext = React.createContext<string | undefined>(undefined)
+
+type MenuEntry =
+    | { kind: 'action'; action: any }
+    | { kind: 'contribution'; item: ResolvedRecordAction }
+
+export function RowActionsMenu({ actions, row, model, onAction, triggerIcon, disabled }: RowActionsMenuProps) {
+    const { t } = useTranslation()
+    const installed = useInstalledAddons()
+    const ctxModel = React.useContext(RowActionsModelContext)
+    const recordModel = model ?? ctxModel
+    const contributed = useRecordActions(recordModel ?? '', recordModel ? row : null).filter((c) => !!c.run)
+
+    const available = actions.filter((a) => isActionProviderActive(a, installed))
+    const { primary, main, secondary } = splitActionsByPriority(available)
+    const mainEntries: MenuEntry[] = main.map((action) => ({ kind: 'action', action }))
+    const secondaryEntries: MenuEntry[] = secondary.map((action) => ({ kind: 'action', action }))
+    for (const item of contributed) {
+        ;(item.priority === 'primary' ? mainEntries : secondaryEntries).push({ kind: 'contribution', item })
+    }
+
+    if (!primary && mainEntries.length === 0 && secondaryEntries.length === 0) return null
+
+    const renderEntry = (e: MenuEntry) =>
+        e.kind === 'action' ? (
+            <RowActionMenuItem
+                key={e.action.key}
+                action={e.action}
+                label={translateMetadataLabel(e.action.label, t)}
+                onSelect={() => onAction?.(e.action.key, row)}
+            />
+        ) : (
+            <DropdownMenuItem key={e.item.key} data-action={e.item.key} onClick={() => void e.item.run?.()}>
+                <DynamicIcon name={e.item.icon || 'Share2'} className="mr-2 h-4 w-4" />
+                {t(e.item.label, { defaultValue: e.item.label })}
+            </DropdownMenuItem>
+        )
+
+    const hasMain = !!primary || mainEntries.length > 0
+    const moreLabel = t('datatable.more_actions', { defaultValue: 'Más…' })
+
+    return (
+        <div className="flex items-center justify-end">
+            <DropdownMenu>
+                <DropdownMenuTrigger asChild>
+                    <Button variant="ghost" className="h-8 w-8 p-0" disabled={disabled} onClick={(e: React.MouseEvent) => e.stopPropagation()}>
+                        <span className="sr-only">{t('datatable.open_menu', { defaultValue: 'Abrir menú' })}</span>
+                        {triggerIcon ?? <MoreHorizontal className="h-4 w-4" />}
+                    </Button>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent align="end" onClick={(e: React.MouseEvent) => e.stopPropagation()}>
+                    {primary ? (
+                        <RowActionMenuItem
+                            action={primary}
+                            label={translateMetadataLabel(primary.label, t)}
+                            onSelect={() => onAction?.(primary.key, row)}
+                            className="font-semibold"
+                        />
+                    ) : null}
+                    {mainEntries.map(renderEntry)}
+                    {secondaryEntries.length > 0 && hasMain ? (
+                        <>
+                            <DropdownMenuSeparator />
+                            <DropdownMenuSub>
+                                <DropdownMenuSubTrigger data-row-more="" className="text-muted-foreground">
+                                    {moreLabel}
+                                </DropdownMenuSubTrigger>
+                                <DropdownMenuSubContent data-row-secondary="">{secondaryEntries.map(renderEntry)}</DropdownMenuSubContent>
+                            </DropdownMenuSub>
+                        </>
+                    ) : (
+                        // Sin principales no hay con qué competir: lista plana.
+                        secondaryEntries.map(renderEntry)
+                    )}
+                </DropdownMenuContent>
+            </DropdownMenu>
+        </div>
+    )
+}

package/src/slot.tsx

@@ -1,56 +1,19 @@
-// Slot / SlotRegistry — named extension points the host renders and addons
-// contribute to at register() time. Keyed by a slot id (e.g. "dashboard.widgets",
+// Slot — named extension points the host renders and addons contribute to at
+// register() time. Keyed by a slot id (e.g. "dashboard.widgets",
 // "invoice.footer"). Each contribution is an arbitrary React element factory.
+//
+// El store es `slotStore` de @asteby/metacore-sdk: el mismo donde escribe
+// `api.registry.registerSlot` (AddonAPI) y `registerDocumentContribution`, así
+// que hay una sola lista por slot. Una entrada con addon dueño (`owner`) que
+// consta como NO instalado (InstalledAddonsProvider) no se pinta.
 import React, { useSyncExternalStore } from 'react'
+import { slotStore, type SlotComponent, type SlotEntry } from '@asteby/metacore-sdk'
+import { useInstalledAddons } from './installed-addons-context'
 
-export type SlotComponent<P = any> = React.ComponentType<P>
+export type { SlotComponent, SlotEntry }
 
-interface SlotEntry {
-    id: string
-    component: SlotComponent
-    priority: number
-    source?: string
-}
-
-type Listener = () => void
-
-class SlotRegistryImpl {
-    private slots = new Map<string, SlotEntry[]>()
-    private listeners = new Set<Listener>()
-
-    register(slotId: string, component: SlotComponent, opts?: { priority?: number; source?: string }): () => void {
-        const entry: SlotEntry = { id: slotId, component, priority: opts?.priority ?? 0, source: opts?.source }
-        const list = this.slots.get(slotId) ?? []
-        list.push(entry)
-        // Higher priority renders first — canonical across SDK and runtime-react.
-        // See docs/slot-priority.md.
-        list.sort((a, b) => b.priority - a.priority)
-        this.slots.set(slotId, list)
-        this.emit()
-        return () => {
-            const arr = this.slots.get(slotId)
-            if (!arr) return
-            const idx = arr.indexOf(entry)
-            if (idx >= 0) {
-                arr.splice(idx, 1)
-                this.emit()
-            }
-        }
-    }
-
-    get(slotId: string): SlotEntry[] {
-        return this.slots.get(slotId) ?? []
-    }
-
-    subscribe(listener: Listener): () => void {
-        this.listeners.add(listener)
-        return () => { this.listeners.delete(listener) }
-    }
-
-    private emit() { this.listeners.forEach(l => l()) }
-}
-
-export const slotRegistry = new SlotRegistryImpl()
+/** Alias histórico del store canónico (`slotRegistry.register/get/subscribe`). */
+export const slotRegistry = slotStore
 
 export interface SlotProps {
     /** Slot id. */
@@ -62,11 +25,13 @@ export interface SlotProps {
 }
 
 export function Slot({ name, props, fallback = null }: SlotProps) {
-    const entries = useSyncExternalStore(
-        (cb) => slotRegistry.subscribe(cb),
-        () => slotRegistry.get(name),
-        () => slotRegistry.get(name),
+    const all = useSyncExternalStore(
+        (cb) => slotStore.subscribe(cb),
+        () => slotStore.get(name),
+        () => slotStore.get(name),
     )
+    const installed = useInstalledAddons()
+    const entries = installed ? all.filter((e) => !e.owner || installed.addons.has(e.owner)) : all
     if (entries.length === 0) return <>{fallback}</>
     return (
         <>