@asteby/metacore-runtime-react 45.2.0 → 45.3.0

package/src/business/index.ts

@@ -11,3 +11,5 @@ export * from './product-search'
 export * from './product-picker'
 export * from './customer-picker'
 export * from './catalog'
+export * from './return'
+export * from './return-wizard'

package/src/business/refund-destination.tsx

@@ -103,9 +103,9 @@ export function RefundDestination({
                         />
                         {errors[`${i}.amount`] && <p className="mt-0.5 text-xs text-destructive">{errors[`${i}.amount`]}</p>}
                     </div>
-                    {(a.kind === 'card' || a.kind === 'credit_note') && (
+                    {(a.kind === 'card' || a.kind === 'transfer' || a.kind === 'credit_note') && (
                         <Input
-                            placeholder={a.kind === 'card' ? t('refund.cardRef', { defaultValue: 'Referencia' }) : t('refund.ncRef', { defaultValue: 'Folio / UUID relacionado' })}
+                            placeholder={a.kind === 'card' || a.kind === 'transfer' ? t('refund.cardRef', { defaultValue: 'Referencia' }) : t('refund.ncRef', { defaultValue: 'Folio / UUID relacionado' })}
                             value={a.reference ?? ''}
                             disabled={disabled}
                             onChange={(e) => emit(value.map((x, j) => (j === i ? { ...x, reference: e.target.value } : x)))}

package/src/business/refund.ts

@@ -2,7 +2,7 @@
 // Lógica pura de <RefundDestination>.
 import { roundMoney, toAmount } from './format'
 
-export type RefundDestinationKind = 'cash' | 'card' | 'wallet' | 'store_credit' | 'credit_note'
+export type RefundDestinationKind = 'cash' | 'card' | 'transfer' | 'wallet' | 'store_credit' | 'credit_note'
 
 export interface RefundDestinationOption {
     kind: RefundDestinationKind
@@ -25,6 +25,7 @@ export interface RefundAllocation {
 export const DEFAULT_REFUND_DESTINATIONS: RefundDestinationOption[] = [
     { kind: 'cash', label: 'Efectivo' },
     { kind: 'card', label: 'Tarjeta' },
+    { kind: 'transfer', label: 'Transferencia' },
     { kind: 'wallet', label: 'Monedero' },
     { kind: 'store_credit', label: 'Saldo a favor' },
     { kind: 'credit_note', label: 'Nota de crédito (CFDI)' },

package/src/business/return-wizard.tsx

@@ -0,0 +1,223 @@
+// ReturnWizard («Devolver mercancía») — un solo componente para POS, Pedido,
+// Factura, RMA y OT (benchmark §7, DEV-2). No conoce endpoints: recibe los
+// renglones devolvibles y entrega un payload por `onSubmit`.
+import { useMemo, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Button, Input } from '@asteby/metacore-ui'
+import { useFormatter } from './format'
+import { RefundDestination } from './refund-destination'
+import {
+    DEFAULT_REFUND_DESTINATIONS,
+    type RefundAllocation,
+    type RefundDestinationOption,
+} from './refund'
+import {
+    RETURN_CONDITION_DESTINATIONS,
+    computeReturnTotals,
+    creditNoteRelation,
+    defaultStockDestination,
+    returnSteps,
+    returnableQty,
+    serializeReturn,
+    validateReturnChoices,
+    validateReturnRefund,
+    type ReturnChoices,
+    type ReturnCondition,
+    type ReturnStep,
+    type ReturnStockDestination,
+    type ReturnSubmitPayload,
+    type ReturnableLine,
+} from './return'
+
+export interface ReturnWizardProps {
+    lines: ReturnableLine[]
+    /** ¿Hay un addon de almacén que confirma la recepción? Sin él, «Recibir» es un paso. */
+    warehouseConnected?: boolean
+    /** La venta está facturada: habilita la NC CFDI con relación 01/03 automática. */
+    invoiced?: boolean
+    /** Destinos de reembolso; `credit_note` se deshabilita solo si no está facturada. */
+    refundOptions?: RefundDestinationOption[]
+    reasons?: { value: string; label: string }[]
+    currency?: string
+    submitting?: boolean
+    /** Errores del servidor (`"<key>.<campo>"`). */
+    serverErrors?: Record<string, string>
+    onSubmit: (payload: ReturnSubmitPayload) => void | Promise<void>
+    onCancel?: () => void
+}
+
+const DEFAULT_REASONS = [
+    { value: 'not_wanted', label: 'No lo quiso' },
+    { value: 'defective', label: 'Defectuoso' },
+    { value: 'wrong_item', label: 'Producto equivocado' },
+    { value: 'warranty', label: 'Garantía' },
+]
+
+const STOCK_LABEL: Record<ReturnStockDestination, string> = { stock: 'Regresa a stock', scrap: 'Merma', warranty: 'Garantía con proveedor' }
+const STEP_LABEL: Record<ReturnStep, string> = { lines: 'Renglones', condition: 'Condición', receive: 'Recibir', refund: 'Reembolso' }
+
+export function ReturnWizard({
+    lines,
+    warehouseConnected = false,
+    invoiced = false,
+    refundOptions = DEFAULT_REFUND_DESTINATIONS,
+    reasons = DEFAULT_REASONS,
+    currency,
+    submitting,
+    serverErrors,
+    onSubmit,
+    onCancel,
+}: ReturnWizardProps) {
+    const { t } = useTranslation()
+    const fmt = useFormatter({ currency })
+    const steps = useMemo(() => returnSteps({ warehouseConnected }), [warehouseConnected])
+    const [stepIdx, setStepIdx] = useState(0)
+    const [choices, setChoices] = useState<ReturnChoices>({})
+    const [reason, setReason] = useState('')
+    const [notes, setNotes] = useState('')
+    const [received, setReceived] = useState(false)
+    const [refund, setRefund] = useState<RefundAllocation[]>([])
+
+    const step = steps[stepIdx]
+    const totals = useMemo(() => computeReturnTotals(lines, choices), [lines, choices])
+    const validation = useMemo(() => validateReturnChoices(lines, choices, reason), [lines, choices, reason])
+    const relation = useMemo(() => creditNoteRelation(lines, choices), [lines, choices])
+    const options = useMemo(
+        () =>
+            refundOptions.map((o) =>
+                o.kind === 'credit_note' && !invoiced
+                    ? { ...o, available: false, disabledReason: 'La venta no está facturada' }
+                    : o.kind === 'credit_note'
+                      ? { ...o, label: `${o.label} · relación ${relation}` }
+                      : o,
+            ),
+        [refundOptions, invoiced, relation],
+    )
+    const refundValidation = useMemo(() => validateReturnRefund(totals.total, refund, options), [totals.total, refund, options])
+    const errors = { ...validation.errors, ...serverErrors }
+
+    const setChoice = (key: string, patch: Partial<ReturnChoices[string]>) =>
+        setChoices((prev) => {
+            const cur = prev[key] ?? { quantity: 0, condition: 'sellable' as ReturnCondition, destination: 'stock' as ReturnStockDestination }
+            const next = { ...cur, ...patch }
+            if (patch.condition && !patch.destination) next.destination = defaultStockDestination(patch.condition)
+            return { ...prev, [key]: next }
+        })
+
+    const canNext =
+        step === 'lines' ? validation.valid
+        : step === 'condition' ? validation.valid
+        : step === 'receive' ? received
+        : refundValidation.valid
+
+    const submit = () =>
+        onSubmit(serializeReturn({ lines, choices, reason, notes, received: warehouseConnected ? false : received, refund }))
+
+    return (
+        <div data-slot="return-wizard" className="space-y-4">
+            <ol className="flex flex-wrap gap-2 text-xs">
+                {steps.map((s, i) => (
+                    <li key={s} aria-current={i === stepIdx ? 'step' : undefined} className={i === stepIdx ? 'font-semibold text-foreground' : 'text-muted-foreground'}>
+                        {i + 1}. {t(`returns.step.${s}`, { defaultValue: STEP_LABEL[s] })}
+                    </li>
+                ))}
+                {warehouseConnected && (
+                    <li className="text-muted-foreground">{t('returns.step.warehouse', { defaultValue: 'Almacén confirma la recepción' })}</li>
+                )}
+            </ol>
+
+            {(step === 'lines' || step === 'condition') && (
+                <div className="space-y-2">
+                    {lines.map((l) => {
+                        const c = choices[l.key]
+                        const max = returnableQty(l)
+                        return (
+                            <div key={l.key} className="grid gap-2 rounded-md border p-2 sm:grid-cols-[1fr_6rem_auto]">
+                                <div>
+                                    <p className="text-sm font-medium">{l.description}</p>
+                                    <p className="text-xs text-muted-foreground">
+                                        {t('returns.sold', { defaultValue: 'Vendido' })}: {l.sold} · {t('returns.returnable', { defaultValue: 'Por devolver' })}: {max} · {fmt.money(l.unit_price)}
+                                    </p>
+                                </div>
+                                {step === 'lines' ? (
+                                    <div>
+                                        <Input
+                                            inputMode="decimal"
+                                            className="text-right"
+                                            aria-label={l.description}
+                                            disabled={max === 0}
+                                            value={c ? String(c.quantity) : ''}
+                                            placeholder="0"
+                                            onChange={(e) => setChoice(l.key, { quantity: Number(e.target.value.replace(',', '.')) || 0 })}
+                                        />
+                                        {errors[`${l.key}.quantity`] && <p className="mt-0.5 text-xs text-destructive">{errors[`${l.key}.quantity`]}</p>}
+                                    </div>
+                                ) : (
+                                    (c?.quantity ?? 0) > 0 && (
+                                        <div className="sm:col-span-2 flex flex-wrap items-center gap-2">
+                                            {(['sellable', 'defective'] as ReturnCondition[]).map((cond) => (
+                                                <Button key={cond} type="button" size="sm" variant={c!.condition === cond ? 'default' : 'outline'} onClick={() => setChoice(l.key, { condition: cond })}>
+                                                    {cond === 'sellable' ? t('returns.sellable', { defaultValue: 'Vendible' }) : t('returns.defective', { defaultValue: 'Defectuoso' })}
+                                                </Button>
+                                            ))}
+                                            {RETURN_CONDITION_DESTINATIONS[c!.condition].length > 1 &&
+                                                RETURN_CONDITION_DESTINATIONS[c!.condition].map((d) => (
+                                                    <Button key={d} type="button" size="sm" variant={c!.destination === d ? 'secondary' : 'ghost'} onClick={() => setChoice(l.key, { destination: d })}>
+                                                        {STOCK_LABEL[d]}
+                                                    </Button>
+                                                ))}
+                                            {RETURN_CONDITION_DESTINATIONS[c!.condition].length === 1 && (
+                                                <span className="text-xs text-muted-foreground">{STOCK_LABEL[c!.destination]}</span>
+                                            )}
+                                            {errors[`${l.key}.destination`] && <p className="w-full text-xs text-destructive">{errors[`${l.key}.destination`]}</p>}
+                                        </div>
+                                    )
+                                )}
+                            </div>
+                        )
+                    })}
+                    {step === 'lines' && (
+                        <div className="grid gap-2 sm:grid-cols-2">
+                            <select className="h-9 rounded-md border bg-background px-2 text-sm" value={reason} onChange={(e) => setReason(e.target.value)} aria-label={t('returns.reason', { defaultValue: 'Motivo' })}>
+                                <option value="">{t('returns.reason', { defaultValue: 'Motivo' })}…</option>
+                                {reasons.map((r) => (
+                                    <option key={r.value} value={r.value}>{r.label}</option>
+                                ))}
+                            </select>
+                            <Input value={notes} onChange={(e) => setNotes(e.target.value)} placeholder={t('returns.notes', { defaultValue: 'Notas (opcional)' })} />
+                        </div>
+                    )}
+                    {validation.form && stepIdx === 0 && Object.keys(choices).length > 0 && <p role="alert" className="text-sm text-destructive">{validation.form}</p>}
+                </div>
+            )}
+
+            {step === 'receive' && (
+                <label className="flex items-start gap-2 rounded-md border p-3 text-sm">
+                    <input type="checkbox" className="mt-1" checked={received} onChange={(e) => setReceived(e.target.checked)} />
+                    <span>{t('returns.receiveHere', { defaultValue: 'Confirmo que la mercancía ya está en tienda. No hay almacén que la reciba, así que la recepción se registra aquí.' })}</span>
+                </label>
+            )}
+
+            {step === 'refund' && (
+                <RefundDestination total={totals.total} value={refund} onChange={setRefund} options={options} currency={currency} allowSplit serverErrors={serverErrors} />
+            )}
+
+            <div className="flex items-center justify-between gap-2 border-t pt-3">
+                <span className="text-sm">
+                    {t('returns.total', { defaultValue: 'Total a devolver' })}: <strong>{fmt.money(totals.total)}</strong>
+                </span>
+                <div className="flex gap-2">
+                    {onCancel && stepIdx === 0 && <Button type="button" variant="outline" onClick={onCancel}>{t('common.cancel', { defaultValue: 'Cancelar' })}</Button>}
+                    {stepIdx > 0 && <Button type="button" variant="outline" onClick={() => setStepIdx(stepIdx - 1)}>{t('common.back', { defaultValue: 'Atrás' })}</Button>}
+                    {stepIdx < steps.length - 1 ? (
+                        <Button type="button" disabled={!canNext} onClick={() => setStepIdx(stepIdx + 1)}>{t('common.next', { defaultValue: 'Siguiente' })}</Button>
+                    ) : (
+                        <Button type="button" disabled={!canNext || submitting} onClick={submit}>
+                            {t('returns.confirm', { defaultValue: 'Confirmar devolución' })} {fmt.money(totals.total)}
+                        </Button>
+                    )}
+                </div>
+            </div>
+        </div>
+    )
+}

package/src/business/return.ts

@@ -0,0 +1,181 @@
+// Devolución de mercancía (ReturnWizard: POS, Pedido, Factura, RMA, OT, devolución
+// a proveedor). Lógica pura, sin endpoints: cada consumidor cablea el envío.
+// Flujo (benchmark §8.2): renglones → condición y destino → recepción → reembolso o NC.
+import { roundMoney, toAmount } from './format'
+import { validateRefund, type RefundAllocation, type RefundDestinationOption } from './refund'
+
+/** Estado físico de lo que regresa. */
+export type ReturnCondition = 'sellable' | 'defective'
+/** A dónde va la mercancía: stock vendible, merma o garantía (reclamo al proveedor). */
+export type ReturnStockDestination = 'stock' | 'scrap' | 'warranty'
+
+export const RETURN_CONDITION_DESTINATIONS: Record<ReturnCondition, ReturnStockDestination[]> = {
+    sellable: ['stock'],
+    defective: ['scrap', 'warranty'],
+}
+
+/** Destino por defecto de una condición (vendible → stock, defectuoso → merma). */
+export function defaultStockDestination(condition: ReturnCondition): ReturnStockDestination {
+    return RETURN_CONDITION_DESTINATIONS[condition][0]
+}
+
+/** Renglón devolvible: lo vendido menos lo ya devuelto. */
+export interface ReturnableLine {
+    key: string
+    product_id?: string
+    description: string
+    sold: number
+    alreadyReturned?: number
+    /** Precio unitario neto de descuento tal como se vendió (congelado). */
+    unit_price: number
+    /** Fracción (0.16). */
+    tax_rate?: number
+}
+
+export interface ReturnLineChoice {
+    quantity: number
+    condition: ReturnCondition
+    destination: ReturnStockDestination
+}
+
+export type ReturnChoices = Record<string, ReturnLineChoice>
+
+export function returnableQty(l: ReturnableLine): number {
+    return Math.max(0, roundMoney(l.sold - (l.alreadyReturned ?? 0), 4))
+}
+
+export interface ReturnTotals {
+    base: number
+    tax: number
+    total: number
+    goodsLines: number
+}
+
+export function computeReturnTotals(lines: ReturnableLine[], choices: ReturnChoices): ReturnTotals {
+    let base = 0
+    let tax = 0
+    let goodsLines = 0
+    for (const l of lines) {
+        const c = choices[l.key]
+        const q = c ? toAmount(c.quantity) : 0
+        if (q <= 0) continue
+        goodsLines += 1
+        const b = roundMoney(q * l.unit_price)
+        base += b
+        tax += roundMoney(b * (l.tax_rate ?? 0))
+    }
+    base = roundMoney(base)
+    tax = roundMoney(tax)
+    return { base, tax, total: roundMoney(base + tax), goodsLines }
+}
+
+/**
+ * Relación SAT (c_TipoRelacion) de la NC: 03 «devolución de mercancía» si regresan
+ * renglones con producto; 01 «nota de crédito de los documentos relacionados» si es
+ * solo ajuste de importe. Misma regla que aplica el backend al proyectar la NC.
+ */
+export function creditNoteRelation(lines: ReturnableLine[], choices: ReturnChoices): '01' | '03' {
+    return lines.some((l) => !!l.product_id && toAmount(choices[l.key]?.quantity) > 0) ? '03' : '01'
+}
+
+export interface ReturnValidation {
+    errors: Record<string, string>
+    form?: string
+    valid: boolean
+}
+
+export function validateReturnChoices(lines: ReturnableLine[], choices: ReturnChoices, reason?: string, requireReason = true): ReturnValidation {
+    const errors: Record<string, string> = {}
+    let any = false
+    for (const l of lines) {
+        const c = choices[l.key]
+        const q = c ? toAmount(c.quantity) : 0
+        if (q === 0) continue
+        if (q < 0) errors[`${l.key}.quantity`] = 'La cantidad no puede ser negativa'
+        else if (q > returnableQty(l)) errors[`${l.key}.quantity`] = `Máximo ${returnableQty(l)} por devolver`
+        else any = true
+        if (c && !RETURN_CONDITION_DESTINATIONS[c.condition]?.includes(c.destination)) {
+            errors[`${l.key}.destination`] = 'Ese destino no aplica a la condición elegida'
+        }
+    }
+    let form: string | undefined
+    if (!any && Object.keys(errors).length === 0) form = 'Elige al menos un renglón a devolver'
+    else if (requireReason && !(reason ?? '').trim()) form = 'Indica el motivo de la devolución'
+    return { errors, form, valid: !form && Object.keys(errors).length === 0 }
+}
+
+/** Pasos visibles. Sin almacén, «Recibir» es un paso del mismo asistente (PIT-021). */
+export type ReturnStep = 'lines' | 'condition' | 'receive' | 'refund'
+
+export function returnSteps(opts: { warehouseConnected: boolean }): ReturnStep[] {
+    // Con almacén, la recepción la confirma almacén fuera del asistente: no es paso.
+    return opts.warehouseConnected ? ['lines', 'condition', 'refund'] : ['lines', 'condition', 'receive', 'refund']
+}
+
+export interface ReturnSubmitPayload {
+    reason: string
+    notes?: string
+    /** true cuando el asistente confirmó la recepción (sin almacén). */
+    received: boolean
+    lines: { key: string; product_id?: string; quantity: number; condition: ReturnCondition; destination: ReturnStockDestination }[]
+    refund: RefundAllocation[]
+    /** Presente solo si el reembolso incluye una NC CFDI. */
+    credit_note?: { relation: '01' | '03' }
+    totals: ReturnTotals
+}
+
+/** Única puerta de salida hacia el backend: solo renglones con cantidad > 0. */
+export function serializeReturn(args: {
+    lines: ReturnableLine[]
+    choices: ReturnChoices
+    reason: string
+    notes?: string
+    received: boolean
+    refund: RefundAllocation[]
+}): ReturnSubmitPayload {
+    const lines = args.lines
+        .filter((l) => toAmount(args.choices[l.key]?.quantity) > 0)
+        .map((l) => {
+            const c = args.choices[l.key]
+            return { key: l.key, ...(l.product_id ? { product_id: l.product_id } : {}), quantity: toAmount(c.quantity), condition: c.condition, destination: c.destination }
+        })
+    const notes = (args.notes ?? '').trim()
+    return {
+        reason: args.reason.trim(),
+        ...(notes ? { notes } : {}),
+        received: args.received,
+        lines,
+        refund: args.refund.map((a) => ({ ...a, amount: roundMoney(a.amount) })),
+        ...(args.refund.some((a) => a.kind === 'credit_note') ? { credit_note: { relation: creditNoteRelation(args.lines, args.choices) } } : {}),
+        totals: computeReturnTotals(args.lines, args.choices),
+    }
+}
+
+/** Valida el paso de reembolso contra el total de la devolución. */
+export function validateReturnRefund(total: number, refund: RefundAllocation[], options?: RefundDestinationOption[]) {
+    return validateRefund(total, refund, options)
+}
+
+// ---- Estados de la RMA ---------------------------------------------------------
+// Borrador → Autorizada → Recibida (total o parcial) → Liquidada → Cerrada, y
+// Rechazada o Cancelada con motivo obligatorio (benchmark §8.2).
+export type RmaState = 'draft' | 'authorized' | 'received' | 'settled' | 'closed' | 'rejected' | 'cancelled'
+
+export const RMA_TRANSITIONS: Record<RmaState, RmaState[]> = {
+    draft: ['authorized', 'rejected', 'cancelled'],
+    authorized: ['received', 'rejected', 'cancelled'],
+    received: ['settled', 'cancelled'],
+    settled: ['closed'],
+    closed: [],
+    rejected: [],
+    cancelled: [],
+}
+
+/** Estados a los que se llega con motivo obligatorio. */
+export const RMA_REASON_REQUIRED: RmaState[] = ['rejected', 'cancelled']
+
+export function canTransitionRma(from: RmaState, to: RmaState, reason?: string): { ok: boolean; error?: string } {
+    if (!RMA_TRANSITIONS[from]?.includes(to)) return { ok: false, error: `No se puede pasar de ${from} a ${to}` }
+    if (RMA_REASON_REQUIRED.includes(to) && !(reason ?? '').trim()) return { ok: false, error: 'Indica el motivo' }
+    return { ok: true }
+}

package/src/dynamic-columns.tsx

@@ -1312,7 +1312,11 @@ export function makeDefaultGetDynamicColumns(
 
                         case 'tags': {
                             const list: string[] = Array.isArray(value)
-                                ? value.map(String)
+                                ? value.map((v) =>
+                                      v && typeof v === 'object'
+                                          ? String((v as { label?: unknown; name?: unknown; key?: unknown }).label ?? (v as { name?: unknown }).name ?? (v as { key?: unknown }).key ?? '')
+                                          : String(v),
+                                  ).filter(Boolean)
                                 : value
                                   ? String(value)
                                         .split(',')

package/src/dynamic-relation.tsx

@@ -83,6 +83,10 @@ export {
 export interface DynamicRelationStrings {
     title: string
     emptyState: string
+    /** Sub-tabla sin permiso de lectura (HTTP 403). Default: "Sin permiso para ver estos registros." */
+    forbiddenState?: string
+    /** Falla al cargar la sub-tabla (no 403). Default: "No se pudieron cargar los registros relacionados." */
+    errorState?: string
     addLabel: string
     editLabel: string
     removeLabel: string
@@ -252,6 +256,9 @@ function OneToManyRelation({
     const [optionsMap, setOptionsMap] = useState<Map<string, any[]>>(new Map())
     const [rows, setRows] = useState<any[]>([])
     const [loading, setLoading] = useState(true)
+    // HTTP status of the last failed fetch (null = ok). Without it a 403/500
+    // rendered the empty state and read as "no related rows" (PIT-045).
+    const [fetchErrorStatus, setFetchErrorStatus] = useState<number | null>(null)
     // Paginación server-side + scroll infinito, igual que <DynamicTable>.
     const [total, setTotal] = useState(0)
     const [page, setPage] = useState(1)
@@ -341,6 +348,7 @@ function OneToManyRelation({
                 cacheMetadata(model, fresh)
             }
             const list = (dataRes as { data: ApiResponse<any[]> }).data
+            setFetchErrorStatus(null)
             if (list.success) {
                 const fetched = list.data || []
                 setRows((prev) => (append ? dedupeById(prev, fetched) : fetched))
@@ -351,6 +359,7 @@ function OneToManyRelation({
             }
         } catch (err) {
             console.error('DynamicRelation fetch error', err)
+            setFetchErrorStatus((err as { response?: { status?: number } })?.response?.status ?? 0)
         } finally {
             if (append) setLoadingMore(false)
             else setLoading(false)
@@ -555,7 +564,11 @@ function OneToManyRelation({
                 </div>
             ) : rows.length === 0 ? (
                 <div className="text-center text-sm text-muted-foreground py-8 border rounded-md bg-muted/30">
-                    {labels.emptyState}
+                    {fetchErrorStatus === 403
+                        ? (labels.forbiddenState ?? 'Sin permiso para ver estos registros.')
+                        : fetchErrorStatus !== null
+                          ? (labels.errorState ?? 'No se pudieron cargar los registros relacionados.')
+                          : labels.emptyState}
                 </div>
             ) : (
                 // Real metadata-driven table — same metacore-ui primitives and

package/src/dynamic-row-actions.tsx

@@ -34,6 +34,7 @@ import {
     AlertDialogTitle,
 } from '@asteby/metacore-ui/primitives'
 import { useApi } from './api-context'
+import { useReasonPrompt } from './reason-prompt'
 import { ActionModalDispatcher } from './action-modal-dispatcher'
 import { DynamicRecordDialog } from './dialogs/dynamic-record'
 import { RequiresAddonDialog, resolveRequiresAddon } from './requires-addon'
@@ -102,6 +103,9 @@ export function useDynamicRowActions({
 
     const [rowToDelete, setRowToDelete] = useState<any | null>(null)
     const [isDeleting, setIsDeleting] = useState(false)
+    // Models that declare `reason_required.delete` answer a bare DELETE with 422
+    // errors.reason; the prompt asks once and retries with `?reason=`.
+    const reasonPrompt = useReasonPrompt()
 
     const [actionModal, setActionModal] = useState<{
         open: boolean
@@ -157,7 +161,14 @@ export function useDynamicRowActions({
         setIsDeleting(true)
         try {
             const deleteEndpoint = writeBase ? `${writeBase}/${rowToDelete.id}` : `/data/${model}/${rowToDelete.id}`
-            const res = await api.delete(deleteEndpoint)
+            const res = await reasonPrompt.run({
+                title: t('dynamic.delete_reason_title', { defaultValue: 'Eliminar registro' }),
+                description: t('dynamic.delete_reason_desc', { defaultValue: 'Este modelo pide el motivo de la eliminación.' }),
+                confirmLabel: t('dynamic.delete_confirm', { defaultValue: 'Eliminar' }),
+                request: (reason) => api.delete(deleteEndpoint, reason ? { params: { reason } } : undefined),
+            })
+            // El operador canceló el motivo: no se eliminó nada.
+            if (!res) return
             // CRUD estándar: no usar res.data.message (el endpoint dinámico
             // devuelve texto en inglés que se filtraría al toast). String localizado.
             if (res.data.success) { toast.success(t('dynamic.delete_success', { defaultValue: 'Registro eliminado correctamente' })); onRefresh() }
@@ -173,6 +184,7 @@ export function useDynamicRowActions({
 
     const dialogs = (
         <>
+            {reasonPrompt.dialog}
             <AlertDialog open={!!rowToDelete} onOpenChange={(open: boolean) => !open && setRowToDelete(null)}>
                 <AlertDialogContent>
                     <AlertDialogHeader>

package/src/dynamic-table.tsx

@@ -67,6 +67,7 @@ import { toast } from 'sonner'
 import { Progress } from './dialogs/_primitives'
 import { useMetadataCache } from './metadata-cache'
 import { useApi, useCurrentBranch } from './api-context'
+import { useReasonPrompt } from './reason-prompt'
 import type { ColumnFilterConfig, GetDynamicColumns } from './dynamic-columns-shim'
 import { defaultGetDynamicColumns, DATE_CELL_TYPES, aggregateOf, formatAggregateTotal } from './dynamic-columns'
 import { useFacetLoaders, isLongTextColumn } from './use-facet-loaders'
@@ -1123,6 +1124,7 @@ export function DynamicTable({
         onRefresh: handleRefresh,
     })
 
+    const bulkReasonPrompt = useReasonPrompt()
     const confirmBulkDelete = async () => {
         const selectedRows = table.getFilteredSelectedRowModel().rows
         if (selectedRows.length === 0) return
@@ -1130,13 +1132,29 @@ export function DynamicTable({
         setBulkDeleteTotal(selectedRows.length)
         setBulkDeleteProgress(0)
         let successCount = 0, errorCount = 0
+        // One reason for the whole batch: asked the first time a row is refused
+        // for lacking it (model declares reason_required.delete), reused after.
+        let bulkReason: string | undefined
+        let bulkCancelled = false
         for (let i = 0; i < selectedRows.length; i++) {
             const row = selectedRows[i]
+            if (bulkCancelled) { errorCount++; setBulkDeleteProgress(i + 1); continue }
             try {
                 const writeBase = mutationEndpoint ?? endpoint
                 const deleteEndpoint = writeBase ? `${writeBase}/${row.original.id}` : `/data/${model}/${row.original.id}`
-                const res = await api.delete(deleteEndpoint)
-                if (res.data.success) successCount++; else errorCount++
+                const res = await bulkReasonPrompt.run({
+                    title: t('dynamic.bulk_delete_reason_title', { count: selectedRows.length, defaultValue: 'Eliminar {{count}} registro(s)' }),
+                    description: t('dynamic.delete_reason_desc', { defaultValue: 'Este modelo pide el motivo de la eliminación.' }),
+                    confirmLabel: t('dynamic.delete_confirm', { defaultValue: 'Eliminar' }),
+                    reason: bulkReason,
+                    request: (reason) => {
+                        if (reason) bulkReason = reason
+                        return api.delete(deleteEndpoint, reason ? { params: { reason } } : undefined)
+                    },
+                })
+                if (!res) { bulkCancelled = true; errorCount++ }
+                else if (res.data.success) successCount++
+                else errorCount++
             } catch (e) { console.error('Error al eliminar', e); errorCount++ }
             setBulkDeleteProgress(i + 1)
         }
@@ -1863,6 +1881,8 @@ export function DynamicTable({
                 </AlertDialogContent>
             </AlertDialog>
 
+            {bulkReasonPrompt.dialog}
+
             {exportEnabled && (
                 <ExportDialog open={exportOpen} onOpenChange={setExportOpen} model={model} metadata={metadata} currentFilters={buildFilterParams()} hasActiveFilters={hasActiveFilters} />
             )}

package/src/index.ts

@@ -237,6 +237,16 @@ export {
     type ApprovalRequiredInfo,
     type RequestApprovalOptions,
 } from './approval-gate'
+export {
+    ReasonPromptDialog,
+    useReasonPrompt,
+    reasonRequiredInfo,
+    DEFAULT_REASON_MIN,
+    type ReasonPromptDialogProps,
+    type ReasonPromptApi,
+    type ReasonRequiredInfo,
+    type RunWithReasonOptions,
+} from './reason-prompt'
 export {
     useDynamicRowActions,
     type UseDynamicRowActionsParams,