@asteby/metacore-runtime-react 44.0.0 → 45.2.0

package/src/document/action-bar.tsx

@@ -0,0 +1,140 @@
+// ActionBar — barra de acciones de un documento (benchmark §5.4 / §6.2):
+// una primaria (verbo + sustantivo), 2–3 secundarias visibles, el resto en
+// «Más…» y las destructivas separadas (divisor) y en rojo. Una acción bloqueada se ve
+// deshabilitada con su motivo (no desaparece: el operador entiende por qué).
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Loader2, MoreHorizontal } from 'lucide-react'
+import {
+    Button,
+    DropdownMenu,
+    DropdownMenuContent,
+    DropdownMenuItem,
+    DropdownMenuTrigger,
+    Tooltip,
+    TooltipContent,
+    TooltipProvider,
+    TooltipTrigger,
+} from '@asteby/metacore-ui/primitives'
+import { cn } from '@asteby/metacore-ui/lib'
+import { DynamicIcon } from '../dynamic-icon'
+import type { ResolvedAction, ResolvedActionLayout } from './types'
+
+export interface ActionBarProps {
+    layout: ResolvedActionLayout
+    /**
+     * Ejecuta la acción. Si devuelve una promesa, el botón muestra `loading`
+     * hasta que se resuelve (acciones asíncronas, §6.2).
+     */
+    onAction: (action: ResolvedAction) => void | Promise<unknown>
+    className?: string
+}
+
+export function ActionBar({ layout, onAction, className }: ActionBarProps) {
+    const { t } = useTranslation()
+    const [busy, setBusy] = useState<string | null>(null)
+
+    const run = async (a: ResolvedAction) => {
+        if (a.blockedReason || busy) return
+        setBusy(a.def.key)
+        try {
+            await onAction(a)
+        } finally {
+            setBusy(null)
+        }
+    }
+
+    const label = (a: ResolvedAction) => t(a.def.label, { defaultValue: a.def.label })
+    const { primary, secondary, more, destructive } = layout
+    const hasMenu = more.length > 0
+
+    const button = (a: ResolvedAction, variant: 'default' | 'outline' | 'destructive') => {
+        const loading = busy === a.def.key
+        const btn = (
+            <Button
+                key={a.def.key}
+                type='button'
+                size='sm'
+                variant={variant === 'destructive' ? 'outline' : variant}
+                disabled={!!a.blockedReason || (!!busy && !loading)}
+                aria-disabled={!!a.blockedReason}
+                data-action={a.def.key}
+                onClick={() => run(a)}
+                className={cn(
+                    variant === 'destructive' &&
+                        'border-destructive/40 text-destructive hover:bg-destructive/10 hover:text-destructive',
+                )}
+            >
+                {loading ? (
+                    <Loader2 className='mr-1.5 h-4 w-4 animate-spin' />
+                ) : a.def.icon ? (
+                    <span className='mr-1.5 inline-flex h-4 w-4 items-center'>
+                        <DynamicIcon name={a.def.icon} className='h-4 w-4' />
+                    </span>
+                ) : null}
+                {label(a)}
+            </Button>
+        )
+        if (!a.blockedReason) return btn
+        return (
+            <Tooltip key={a.def.key}>
+                <TooltipTrigger asChild>
+                    {/* span: un botón disabled no dispara el tooltip */}
+                    <span tabIndex={0}>{btn}</span>
+                </TooltipTrigger>
+                <TooltipContent className='max-w-xs'>{t(a.blockedReason, { defaultValue: a.blockedReason })}</TooltipContent>
+            </Tooltip>
+        )
+    }
+
+    const item = (a: ResolvedAction) => (
+        <DropdownMenuItem
+            key={a.def.key}
+            disabled={!!a.blockedReason}
+            data-action={a.def.key}
+            onSelect={() => run(a)}
+        >
+            {a.def.icon ? (
+                <span className='mr-2 inline-flex h-4 w-4 items-center'>
+                    <DynamicIcon name={a.def.icon} className='h-4 w-4' />
+                </span>
+            ) : null}
+            <span className='flex flex-col'>
+                {label(a)}
+                {a.blockedReason ? (
+                    <span className='text-xs font-normal text-muted-foreground'>
+                        {t(a.blockedReason, { defaultValue: a.blockedReason })}
+                    </span>
+                ) : null}
+            </span>
+        </DropdownMenuItem>
+    )
+
+    return (
+        <TooltipProvider delayDuration={150}>
+            <div className={cn('flex flex-wrap items-center gap-2', className)} data-document-actions=''>
+                {primary ? button(primary, primary.def.destructive ? 'destructive' : 'default') : null}
+                {secondary.map((a) => button(a, 'outline'))}
+                {hasMenu ? (
+                    <DropdownMenu>
+                        <DropdownMenuTrigger asChild>
+                            <Button type='button' size='sm' variant='outline' aria-label={t('document.more', { defaultValue: 'Más…' })}>
+                                <MoreHorizontal className='mr-1.5 h-4 w-4' />
+                                {t('document.more', { defaultValue: 'Más…' })}
+                            </Button>
+                        </DropdownMenuTrigger>
+                        <DropdownMenuContent align='end' className='min-w-56'>
+                            {more.map((a) => item(a))}
+                        </DropdownMenuContent>
+                    </DropdownMenu>
+                ) : null}
+                {destructive.length > 0 ? (
+                    <>
+                        <span aria-hidden className='mx-1 h-6 w-px bg-border' />
+                        {destructive.map((a) => button(a, 'destructive'))}
+                    </>
+                ) : null}
+            </div>
+        </TooltipProvider>
+    )
+}

package/src/document/cancel-with-reason.tsx

@@ -0,0 +1,214 @@
+// CancelWithReason — cancelación guiada de 2 pasos (benchmark §5.5 / §7): motivo
+// del catálogo del tipo de documento → (documento sustituto si el motivo lo
+// exige) → confirmación con consecuencias. Genérico: el catálogo de motivos, las
+// consecuencias y la política de aceptación las declara el llamador; el
+// componente no sabe de CFDI. Solo una acción primaria por paso (verbo +
+// sustantivo) y, si la acción falla, el modal sigue abierto con el error.
+import { useEffect, useState, type ReactNode } from 'react'
+import { useTranslation } from 'react-i18next'
+import { AlertTriangle, Loader2 } from 'lucide-react'
+import {
+    Button,
+    Dialog,
+    DialogContent,
+    DialogDescription,
+    DialogFooter,
+    DialogHeader,
+    DialogTitle,
+    Input,
+    Label,
+    RadioGroup,
+    RadioGroupItem,
+} from '@asteby/metacore-ui/primitives'
+
+export interface CancelReason {
+    value: string
+    label: string
+    /** Ayuda corta bajo el motivo. */
+    hint?: string
+    /** Exige apuntar a un documento sustituto (motivo 01 del SAT). */
+    requiresSubstitute?: boolean
+    /** El motivo no aplica a este documento (se ve deshabilitado con `disabledReason`). */
+    disabled?: boolean
+    disabledReason?: string
+}
+
+export interface CancelPayload {
+    reason: string
+    substitute?: string
+}
+
+export interface CancelWithReasonProps {
+    open: boolean
+    onOpenChange: (open: boolean) => void
+    /** Identificación del documento («Factura A-1042»). */
+    documentLabel: string
+    title?: string
+    reasons: CancelReason[]
+    /** Consecuencias que se muestran en el paso de confirmación (§6.2). */
+    consequences: string[]
+    /**
+     * Aviso según el motivo elegido, p. ej. «requiere aceptación del receptor».
+     * Devuelve `undefined` si no hay.
+     */
+    notice?: (reason: CancelReason) => string | undefined
+    /** Formato del identificador del sustituto; si se define, valida en línea. */
+    substitutePattern?: RegExp
+    substituteLabel?: string
+    substituteHelp?: string
+    /** Zona para crear el sustituto desde el mismo asistente (el host la implementa). */
+    substituteSlot?: (props: { value: string; onChange: (v: string) => void }) => ReactNode
+    /** Ejecuta la cancelación; debe lanzar con `message` si falla. */
+    onConfirm: (payload: CancelPayload) => Promise<unknown>
+    /** Se llama tras un éxito, antes de cerrar. */
+    onDone?: () => void
+    confirmLabel?: string
+}
+
+type Step = 'reason' | 'confirm'
+
+export function CancelWithReason(props: CancelWithReasonProps) {
+    const { open, onOpenChange, reasons, consequences, onConfirm, onDone } = props
+    const { t } = useTranslation()
+    const [step, setStep] = useState<Step>('reason')
+    const [reasonValue, setReasonValue] = useState('')
+    const [substitute, setSubstitute] = useState('')
+    const [busy, setBusy] = useState(false)
+    const [error, setError] = useState<string | null>(null)
+
+    useEffect(() => {
+        if (open) {
+            setStep('reason')
+            setReasonValue('')
+            setSubstitute('')
+            setError(null)
+            setBusy(false)
+        }
+    }, [open])
+
+    const reason = reasons.find((r) => r.value === reasonValue)
+    const substituteValid =
+        !reason?.requiresSubstitute ||
+        (substitute.trim().length > 0 && (!props.substitutePattern || props.substitutePattern.test(substitute.trim())))
+    const notice = reason ? props.notice?.(reason) : undefined
+    const tr = (s: string) => t(s, { defaultValue: s })
+
+    const confirm = async () => {
+        if (!reason) return
+        setBusy(true)
+        setError(null)
+        try {
+            await onConfirm({ reason: reason.value, substitute: reason.requiresSubstitute ? substitute.trim() : undefined })
+            onDone?.()
+            onOpenChange(false)
+        } catch (e) {
+            setError((e as { message?: string })?.message || t('document.cancel.failed', { defaultValue: 'No se pudo cancelar. Revisa el detalle e intenta de nuevo.' }))
+            setBusy(false)
+        }
+    }
+
+    return (
+        <Dialog open={open} onOpenChange={(o) => (!busy ? onOpenChange(o) : undefined)}>
+            <DialogContent className='sm:max-w-lg'>
+                <DialogHeader>
+                    <DialogTitle>{props.title ?? t('document.cancel.title', { defaultValue: 'Solicitar cancelación' })}</DialogTitle>
+                    <DialogDescription>
+                        {props.documentLabel} ·{' '}
+                        {step === 'reason'
+                            ? t('document.cancel.step_reason', { defaultValue: 'Paso 1 de 2: elige el motivo' })
+                            : t('document.cancel.step_confirm', { defaultValue: 'Paso 2 de 2: confirma' })}
+                    </DialogDescription>
+                </DialogHeader>
+
+                {step === 'reason' ? (
+                    <div className='flex flex-col gap-4'>
+                        <RadioGroup value={reasonValue} onValueChange={setReasonValue} className='gap-2'>
+                            {reasons.map((r) => (
+                                <label
+                                    key={r.value}
+                                    className='flex cursor-pointer items-start gap-3 rounded-md border p-3 has-[:disabled]:cursor-not-allowed has-[:disabled]:opacity-50 has-[[data-state=checked]]:border-primary'
+                                >
+                                    <RadioGroupItem value={r.value} disabled={r.disabled} className='mt-0.5' />
+                                    <span className='flex flex-col'>
+                                        <span className='text-sm font-medium'>{tr(r.label)}</span>
+                                        {r.disabled && r.disabledReason ? (
+                                            <span className='text-xs text-muted-foreground'>{tr(r.disabledReason)}</span>
+                                        ) : r.hint ? (
+                                            <span className='text-xs text-muted-foreground'>{tr(r.hint)}</span>
+                                        ) : null}
+                                    </span>
+                                </label>
+                            ))}
+                        </RadioGroup>
+
+                        {reason?.requiresSubstitute ? (
+                            props.substituteSlot ? (
+                                props.substituteSlot({ value: substitute, onChange: setSubstitute })
+                            ) : (
+                                <div className='grid gap-2'>
+                                    <Label>{props.substituteLabel ?? t('document.cancel.substitute', { defaultValue: 'Documento sustituto' })}</Label>
+                                    <Input value={substitute} onChange={(e) => setSubstitute(e.target.value)} className='font-mono text-sm' />
+                                    {props.substituteHelp ? <p className='text-xs text-muted-foreground'>{tr(props.substituteHelp)}</p> : null}
+                                    {substitute && !substituteValid ? (
+                                        <p className='text-xs text-destructive'>{t('document.cancel.substitute_invalid', { defaultValue: 'El formato del identificador no es válido.' })}</p>
+                                    ) : null}
+                                </div>
+                            )
+                        ) : null}
+                        {notice ? <p className='rounded-md bg-muted p-3 text-sm'>{tr(notice)}</p> : null}
+                    </div>
+                ) : (
+                    <div className='flex flex-col gap-3'>
+                        <div className='flex items-start gap-2 rounded-md border border-destructive/30 bg-destructive/5 p-3 text-sm text-destructive'>
+                            <AlertTriangle className='mt-0.5 h-4 w-4 shrink-0' />
+                            <ul className='list-disc pl-4'>
+                                {consequences.map((c) => (
+                                    <li key={c}>{tr(c)}</li>
+                                ))}
+                            </ul>
+                        </div>
+                        <dl className='grid grid-cols-[auto_1fr] gap-x-3 gap-y-1 text-sm'>
+                            <dt className='text-muted-foreground'>{t('document.cancel.reason', { defaultValue: 'Motivo' })}</dt>
+                            <dd className='font-medium'>{reason ? tr(reason.label) : ''}</dd>
+                            {reason?.requiresSubstitute ? (
+                                <>
+                                    <dt className='text-muted-foreground'>{t('document.cancel.substitute_short', { defaultValue: 'Sustituto' })}</dt>
+                                    <dd className='break-all font-mono text-xs'>{substitute}</dd>
+                                </>
+                            ) : null}
+                        </dl>
+                        {notice ? <p className='text-sm text-muted-foreground'>{tr(notice)}</p> : null}
+                        {error ? (
+                            <p role='alert' className='rounded-md border border-destructive/40 bg-destructive/10 p-3 text-sm text-destructive'>
+                                {error}
+                            </p>
+                        ) : null}
+                    </div>
+                )}
+
+                <DialogFooter>
+                    {step === 'reason' ? (
+                        <>
+                            <Button type='button' variant='outline' onClick={() => onOpenChange(false)}>
+                                {t('document.cancel.keep', { defaultValue: 'Conservar documento' })}
+                            </Button>
+                            <Button type='button' disabled={!reason || !substituteValid} onClick={() => setStep('confirm')}>
+                                {t('document.cancel.continue', { defaultValue: 'Continuar' })}
+                            </Button>
+                        </>
+                    ) : (
+                        <>
+                            <Button type='button' variant='outline' disabled={busy} onClick={() => setStep('reason')}>
+                                {t('document.cancel.back', { defaultValue: 'Volver al motivo' })}
+                            </Button>
+                            <Button type='button' variant='destructive' disabled={busy} onClick={confirm}>
+                                {busy ? <Loader2 className='mr-1.5 h-4 w-4 animate-spin' /> : null}
+                                {props.confirmLabel ?? t('document.cancel.confirm', { defaultValue: 'Solicitar cancelación' })}
+                            </Button>
+                        </>
+                    )}
+                </DialogFooter>
+            </DialogContent>
+        </Dialog>
+    )
+}

package/src/document/document-header.tsx

@@ -0,0 +1,140 @@
+// DocumentHeader — cabecera estándar (benchmark §5.2): serie/folio, badges de
+// cada máquina de estado, cliente enlazable, métricas (total, saldo, fechas) y
+// un identificador copiable (UUID).
+import { useState, type ReactNode } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Check, Copy } from 'lucide-react'
+import { Button } from '@asteby/metacore-ui/primitives'
+import { cn } from '@asteby/metacore-ui/lib'
+import { StatusBadge } from './status-badge'
+import { formatFieldValue, type FieldFormatOptions } from './format'
+import type { StatusDef } from './types'
+
+export interface HeaderBadge {
+    id: string
+    label?: string
+    status: StatusDef
+}
+
+export interface HeaderMetric {
+    label: string
+    value: string
+    tone?: 'default' | 'critical'
+    mono?: boolean
+}
+
+export interface DocumentHeaderProps {
+    title: string
+    /** Texto bajo el título; si `subtitleHref` viene, es un enlace (ficha del cliente). */
+    subtitle?: string
+    subtitleHref?: string
+    badges: HeaderBadge[]
+    metrics?: HeaderMetric[]
+    copyable?: { label: string; value: string }
+    /** Zona de acciones (normalmente `<ActionBar/>`). */
+    actions?: ReactNode
+    /** Slot antes del título (botón «Volver»). */
+    leading?: ReactNode
+    /** Renderiza el subtítulo como enlace del router del host. */
+    renderLink?: (props: { href: string; children: ReactNode; className?: string }) => ReactNode
+    className?: string
+}
+
+export function DocumentHeader({
+    title,
+    subtitle,
+    subtitleHref,
+    badges,
+    metrics,
+    copyable,
+    actions,
+    leading,
+    renderLink,
+    className,
+}: DocumentHeaderProps) {
+    const { t } = useTranslation()
+    const [copied, setCopied] = useState(false)
+
+    const copy = async () => {
+        if (!copyable?.value) return
+        try {
+            await navigator.clipboard.writeText(copyable.value)
+            setCopied(true)
+            setTimeout(() => setCopied(false), 1500)
+        } catch {
+            /* sin portapapeles (contexto inseguro): el valor sigue seleccionable */
+        }
+    }
+
+    const subtitleNode = subtitle ? (
+        subtitleHref ? (
+            renderLink ? (
+                renderLink({ href: subtitleHref, children: subtitle, className: 'text-sm text-primary hover:underline' })
+            ) : (
+                <a href={subtitleHref} className='text-sm text-primary hover:underline'>
+                    {subtitle}
+                </a>
+            )
+        ) : (
+            <span className='text-sm text-muted-foreground'>{subtitle}</span>
+        )
+    ) : null
+
+    return (
+        <header className={cn('flex flex-col gap-4 rounded-lg border bg-card p-5 text-card-foreground', className)} data-document-header=''>
+            {leading}
+            <div className='flex flex-wrap items-start justify-between gap-4'>
+                <div className='flex min-w-0 flex-col gap-2'>
+                    <div className='flex flex-wrap items-center gap-2'>
+                        <h1 className='text-2xl font-bold tracking-tight'>{title}</h1>
+                        {badges.map((b) => (
+                            <StatusBadge key={b.id} status={b.status} srLabel={b.label ? t(b.label, { defaultValue: b.label }) : undefined} />
+                        ))}
+                    </div>
+                    {subtitleNode}
+                </div>
+                {actions}
+            </div>
+
+            {metrics && metrics.length > 0 ? (
+                <dl className='grid grid-cols-2 gap-x-6 gap-y-3 sm:grid-cols-3 lg:grid-cols-5'>
+                    {metrics.map((m) => (
+                        <div key={m.label}>
+                            <dt className='text-xs uppercase tracking-wide text-muted-foreground'>{m.label}</dt>
+                            <dd
+                                className={cn(
+                                    'font-medium tabular-nums',
+                                    m.mono && 'font-mono text-xs',
+                                    m.tone === 'critical' && 'text-destructive',
+                                )}
+                            >
+                                {m.value}
+                            </dd>
+                        </div>
+                    ))}
+                </dl>
+            ) : null}
+
+            {copyable?.value ? (
+                <div className='flex flex-wrap items-center gap-2 text-xs text-muted-foreground'>
+                    <span className='uppercase tracking-wide'>{copyable.label}</span>
+                    <code className='break-all font-mono text-foreground'>{copyable.value}</code>
+                    <Button
+                        type='button'
+                        size='sm'
+                        variant='ghost'
+                        className='h-6 px-1.5'
+                        onClick={copy}
+                        aria-label={t('document.copy', { defaultValue: 'Copiar' })}
+                    >
+                        {copied ? <Check className='h-3.5 w-3.5' /> : <Copy className='h-3.5 w-3.5' />}
+                        <span className='ml-1'>{copied ? t('document.copied', { defaultValue: 'Copiado' }) : t('document.copy', { defaultValue: 'Copiar' })}</span>
+                    </Button>
+                </div>
+            ) : null}
+        </header>
+    )
+}
+
+export { formatFieldValue }
+export type { FieldFormatOptions }