@asteby/metacore-runtime-react 45.0.0 → 45.2.0

package/src/document/smart-buttons.tsx

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

package/src/document/status-badge.tsx

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

package/src/document/types.ts

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

package/src/document/use-document-sources.ts

@@ -0,0 +1,91 @@
+import { useCallback, useEffect, useState } from 'react'
+import { useApi } from '../api-context'
+import { buildRelationFilterParams } from '../dynamic-relation-helpers'
+import type { DocumentSourceDef } from './types'
+
+const DEFAULT_LIMIT = 50
+// El kernel ≥ 0.139.2 acepta listas `in:` largas; se parte para no exceder la URL.
+const VIA_CHUNK = 40
+
+type Rows = Record<string, unknown>[]
+
+export interface DocumentSourcesState {
+    sources: Record<string, Record<string, unknown>[]>
+    loading: boolean
+    /** Vuelve a pedir todas las fuentes (tras ejecutar una acción). */
+    reload: () => void
+}
+
+/**
+ * Carga las filas relacionadas con el documento (pagos, REP, notas de crédito…)
+ * que alimentan contadores, pestañas y derivados. Un fallo en una fuente deja
+ * esa fuente vacía: la página sigue siendo usable.
+ */
+export function useDocumentSources(
+    defs: DocumentSourceDef[] | undefined,
+    recordId: string | number | undefined,
+): DocumentSourcesState {
+    const api = useApi()
+    const [sources, setSources] = useState<Record<string, Record<string, unknown>[]>>({})
+    const [loading, setLoading] = useState(false)
+    const [nonce, setNonce] = useState(0)
+    const reload = useCallback(() => setNonce((n) => n + 1), [])
+
+    useEffect(() => {
+        if (!defs || defs.length === 0 || recordId === undefined || recordId === null) {
+            setSources({})
+            return
+        }
+        let cancelled = false
+        setLoading(true)
+        const fetchRows = async (d: DocumentSourceDef, params: Record<string, string>): Promise<Rows> => {
+            try {
+                const res = await api.get(`/data/${d.model}`, {
+                    params: { ...params, page: 1, per_page: d.limit ?? DEFAULT_LIMIT },
+                })
+                const body = res.data
+                const rows = (body?.data ?? body) as unknown
+                return Array.isArray(rows) ? (rows as Rows) : []
+            } catch {
+                return []
+            }
+        }
+        const direct = defs.filter((d) => !d.via)
+        const hopped = defs.filter((d) => d.via)
+        ;(async () => {
+            const out: Record<string, Rows> = {}
+            await Promise.all(
+                direct.map(async (d) => {
+                    out[d.key] = await fetchRows(d, buildRelationFilterParams(d.foreignKey, recordId, d.where))
+                }),
+            )
+            // Segundo salto: depende de las filas del primero.
+            for (const d of hopped) {
+                const ids = Array.from(
+                    new Set((out[d.via!.source] ?? []).map((r) => r[d.via!.field]).filter((v) => v != null && v !== '').map(String)),
+                )
+                const chunks: string[][] = []
+                for (let i = 0; i < ids.length; i += VIA_CHUNK) chunks.push(ids.slice(i, i + VIA_CHUNK))
+                const parts = await Promise.all(
+                    chunks.map((c) => {
+                        const params: Record<string, string> = { [`f_${d.foreignKey}`]: `in:${c.join(',')}` }
+                        for (const [k, v] of Object.entries(d.where ?? {})) params[`f_${k}`] = `eq:${v}`
+                        return fetchRows(d, params)
+                    }),
+                )
+                out[d.key] = parts.flat()
+            }
+            return out
+        })()
+            .then((out) => {
+                if (cancelled) return
+                setSources(out)
+                setLoading(false)
+            })
+        return () => {
+            cancelled = true
+        }
+    }, [api, defs, recordId, nonce])
+
+    return { sources, loading, reload }
+}

package/src/index.ts

@@ -218,6 +218,25 @@ export {
     type CanFn,
     type PermissionsProviderProps,
 } from './permissions-context'
+export {
+    ApprovalPinDialog,
+    approvalErrorMessage,
+    type ApprovalPinDialogProps,
+    type ApprovalPinSubmit,
+} from './approval-pin-dialog'
+export {
+    ApprovalGateProvider,
+    useApprovalGate,
+    approvalCapability,
+    approvalRequiredInfo,
+    approvalGateAvailable,
+    APPROVAL_PARKED_EVENT,
+    APPROVAL_DECIDED_EVENT,
+    type ApprovalGateValue,
+    type ApprovalGrant,
+    type ApprovalRequiredInfo,
+    type RequestApprovalOptions,
+} from './approval-gate'
 export {
     useDynamicRowActions,
     type UseDynamicRowActionsParams,
@@ -282,6 +301,7 @@ export {
     type SidebarLayoutManagerProps,
 } from './sidebar-layout-manager'
 export * from './org-runtime-context'
+export * from './business'
 export * from './org-runtime-provider'
 export * from './navigation-builder'
 export * from './i18n-provider'
@@ -581,3 +601,6 @@ export {
     type AttributeClass,
     type AttributeClassSection,
 } from './attribute-classes'
+
+// Página de documento (benchmark §5/§6): cabecera, badges, acciones por estado, botones inteligentes.
+export * from './document'

package/src/server-error.ts

@@ -11,6 +11,7 @@
 // the toast description, in ONE place so every call site behaves identically.
 import { toast } from 'sonner'
 import { validationCatalog, validationMessageKey } from './validation-catalog'
+import { APPROVAL_PARKED_EVENT, approvalGateAvailable, approvalRequiredInfo } from './approval-events'
 
 /** Structured, display-ready view of an error: a headline + an optional cause. */
 export interface ExtractedError {
@@ -234,6 +235,25 @@ export function toastServerError(
     const t = opts?.t
     const lang = opts?.language
     const cat = validationCatalog(lang)
+    // A write parked for approval is not a failure: say so, and when an
+    // <ApprovalGateProvider> is mounted offer to approve it right now with a PIN.
+    const parked = approvalRequiredInfo(err)
+    if (parked) {
+        const title = parked.label || (t ? t('approvals.sent', { defaultValue: 'Enviado a aprobación' }) : 'Enviado a aprobación')
+        toast.info(title, {
+            description: parked.roles.length
+                ? (t ? t('approvals.waiting_for', { defaultValue: 'Lo decide: {{roles}}', roles: parked.roles.join(', ') }) : parked.roles.join(', '))
+                : undefined,
+            action:
+                parked.requestId && approvalGateAvailable()
+                    ? {
+                          label: t ? t('approvals.approve_with_pin', { defaultValue: 'Aprobar con PIN' }) : 'Aprobar con PIN',
+                          onClick: () => window.dispatchEvent(new CustomEvent(APPROVAL_PARKED_EVENT, { detail: parked })),
+                      }
+                    : undefined,
+        })
+        return
+    }
     const map = extractFieldErrors(err)
     if (map) {
         const localized = t