@asteby/metacore-runtime-react 45.0.0 → 45.3.0

package/src/approval-pin-dialog.tsx

@@ -0,0 +1,162 @@
+// ApprovalPinDialog — the supervisor PIN prompt shared by every sensitive action
+// (POS sell-without-stock, discount above the cap, price below the floor, refund,
+// CFDI cancel, inventory adjust). Presentational: it collects a reason + a PIN and
+// hands them to `onSubmit`, which does the network call, so federated addons that
+// carry their own HTTP client reuse the same dialog as hosts with an ApiProvider.
+//
+// The reason is always required (audit trail: who asked, who authorized, why).
+// A rejected `onSubmit` keeps the dialog open and shows the error inline (wrong
+// PIN, locked, no permission) instead of a toast that can be missed.
+import { useEffect, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Loader2, ShieldCheck } from 'lucide-react'
+import {
+    Button,
+    Dialog,
+    DialogContent,
+    DialogDescription,
+    DialogFooter,
+    DialogHeader,
+    DialogTitle,
+    Input,
+    Textarea,
+} from '@asteby/metacore-ui/primitives'
+
+export interface ApprovalPinSubmit {
+    pin: string
+    reason: string
+}
+
+export interface ApprovalPinDialogProps {
+    open: boolean
+    /** Headline, e.g. "Venta sin existencias". */
+    title: string
+    /** What is being authorized, in the operator's words. */
+    description?: React.ReactNode
+    /** Called with the typed PIN + reason. Throw (or reject) to keep the dialog open. */
+    onSubmit: (v: ApprovalPinSubmit) => Promise<void>
+    onCancel: () => void
+    /** Optional secondary action, e.g. "Enviar a la bandeja" (async request). */
+    secondaryAction?: { label: string; onClick: () => void }
+}
+
+/** Best human message out of an axios-style error carrying the kernel envelope. */
+export function approvalErrorMessage(err: unknown, t: (k: string, o?: { defaultValue?: string }) => string): string {
+    const data = (err as { response?: { data?: { error?: { code?: string; message?: string }; message?: string } } })?.response?.data
+    switch (data?.error?.code) {
+        case 'approval_pin_invalid':
+            return t('approvals.pin_invalid', { defaultValue: 'PIN incorrecto o sin permiso para autorizar esto.' })
+        case 'approval_pin_locked':
+            return t('approvals.pin_locked', { defaultValue: 'Demasiados intentos. Espera unos minutos.' })
+        case 'approval_pin_unavailable':
+            return t('approvals.pin_unavailable', { defaultValue: 'La autorización con PIN no está disponible.' })
+        case 'approval_reason_required':
+            return t('approvals.reason_required', { defaultValue: 'Escribe el motivo.' })
+    }
+    return data?.error?.message || data?.message || (err as Error)?.message || t('common.error', { defaultValue: 'Algo salió mal' })
+}
+
+export function ApprovalPinDialog({ open, title, description, onSubmit, onCancel, secondaryAction }: ApprovalPinDialogProps) {
+    const { t } = useTranslation()
+    const [pin, setPin] = useState('')
+    const [reason, setReason] = useState('')
+    const [busy, setBusy] = useState(false)
+    const [error, setError] = useState<string | null>(null)
+
+    useEffect(() => {
+        if (open) {
+            setPin('')
+            setReason('')
+            setError(null)
+            setBusy(false)
+        }
+    }, [open])
+
+    const ready = /^\d{4,8}$/.test(pin) && reason.trim().length > 0
+
+    const submit = async () => {
+        if (!ready || busy) return
+        setBusy(true)
+        setError(null)
+        try {
+            await onSubmit({ pin, reason: reason.trim() })
+        } catch (err) {
+            setError(approvalErrorMessage(err, t as never))
+            setPin('')
+        } finally {
+            setBusy(false)
+        }
+    }
+
+    return (
+        <Dialog open={open} onOpenChange={(o) => { if (!o && !busy) onCancel() }}>
+            <DialogContent className="sm:max-w-md">
+                <DialogHeader>
+                    <DialogTitle className="flex items-center gap-2">
+                        <ShieldCheck className="h-5 w-5" />
+                        {title}
+                    </DialogTitle>
+                    <DialogDescription asChild>
+                        <div>
+                            {description ?? t('approvals.pin_prompt', { defaultValue: 'Requiere autorización de un supervisor.' })}
+                        </div>
+                    </DialogDescription>
+                </DialogHeader>
+                <form
+                    className="space-y-3"
+                    onSubmit={(e) => {
+                        e.preventDefault()
+                        void submit()
+                    }}
+                >
+                    <div className="space-y-1.5">
+                        <label className="text-sm font-medium" htmlFor="approval-reason">
+                            {t('approvals.reason', { defaultValue: 'Motivo' })}
+                        </label>
+                        <Textarea
+                            id="approval-reason"
+                            value={reason}
+                            onChange={(e) => setReason(e.target.value)}
+                            rows={2}
+                            placeholder={t('approvals.reason_placeholder', { defaultValue: 'Por qué se autoriza' })}
+                        />
+                    </div>
+                    <div className="space-y-1.5">
+                        <label className="text-sm font-medium" htmlFor="approval-pin">
+                            {t('approvals.pin', { defaultValue: 'PIN del supervisor' })}
+                        </label>
+                        <Input
+                            id="approval-pin"
+                            type="password"
+                            inputMode="numeric"
+                            autoComplete="off"
+                            maxLength={8}
+                            value={pin}
+                            onChange={(e) => setPin(e.target.value.replace(/\D/g, ''))}
+                            aria-invalid={error ? true : undefined}
+                        />
+                    </div>
+                    {error ? (
+                        <p role="alert" className="text-sm text-destructive">
+                            {error}
+                        </p>
+                    ) : null}
+                    <DialogFooter className="gap-2 sm:gap-2">
+                        {secondaryAction ? (
+                            <Button type="button" variant="ghost" onClick={secondaryAction.onClick} disabled={busy}>
+                                {secondaryAction.label}
+                            </Button>
+                        ) : null}
+                        <Button type="button" variant="outline" onClick={onCancel} disabled={busy}>
+                            {t('common.cancel', { defaultValue: 'Cancelar' })}
+                        </Button>
+                        <Button type="submit" disabled={!ready || busy}>
+                            {busy ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : null}
+                            {t('approvals.authorize', { defaultValue: 'Autorizar' })}
+                        </Button>
+                    </DialogFooter>
+                </form>
+            </DialogContent>
+        </Dialog>
+    )
+}

package/src/business/business.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it } from 'vitest'
+import { createFormatter, formatDate, formatDateTime, formatMoney, roundMoney, toAmount } from './format'
+import { mapApiError } from './field-errors'
+import {
+    computeTotals,
+    makeLine,
+    parseLineItems,
+    serializeLineItems,
+    validateLineItems,
+} from './line-items'
+import { newTender, serializePayment, summarizePayment, validatePayment, type PaymentMethodOption } from './payment'
+import { singleDestination, validateRefund } from './refund'
+import { parseProductQuery, parseTireSize, productToLine } from './product-search'
+
+const nbsp = (s: string) => s.replace(/ /g, ' ')
+
+describe('format', () => {
+    it('formatea moneda es-MX con símbolo corto y sin mezclar locale (PIT-023)', () => {
+        expect(nbsp(formatMoney(1060, { currency: 'MXN' }))).toBe('$1,060.00')
+        expect(nbsp(formatMoney(1.06, { currency: 'MXN' }))).toBe('$1.06')
+        expect(formatMoney('abc')).toBe('$0.00')
+        expect(formatMoney(NaN)).toBe('')
+    })
+    it('usa la moneda dada, con USD solo como último recurso', () => {
+        expect(nbsp(formatMoney(5, { currency: 'EUR' }))).toContain('€')
+        expect(nbsp(formatMoney(5))).toBe('US$5.00'.replace('US', ''))
+    })
+    it('una fecha de calendario no retrocede un día (PIT-025)', () => {
+        expect(formatDate('2026-09-29', { timeZone: 'America/Mexico_City' })).toContain('29')
+        expect(formatDateTime('2026-09-29T02:00:00Z', { timeZone: 'America/Mexico_City' })).toContain('28')
+    })
+    it('createFormatter fija locale, moneda y zona', () => {
+        const f = createFormatter({ currency: 'MXN', timeZone: 'America/Mexico_City' })
+        expect(nbsp(f.money(10))).toBe('$10.00')
+        expect(f.locale).toBe('es-MX')
+    })
+    it('roundMoney y toAmount', () => {
+        expect(roundMoney(1.005)).toBe(1.01)
+        expect(toAmount('$1,234.50')).toBe(1234.5)
+        expect(toAmount('1.234,50')).toBe(1234.5)
+    })
+})
+
+describe('mapApiError', () => {
+    const axiosErr = (status: number, data: unknown) => ({ response: { status, data } })
+    it('422 con errors → mensajes por campo', () => {
+        const m = mapApiError(axiosErr(422, { errors: { sku: [{ code: 'duplicate' }] } }), { labels: { sku: 'SKU' } })
+        expect(m.hasFieldErrors).toBe(true)
+        expect(m.fields.sku).toContain('SKU')
+    })
+    it('409 duplicado que nombra el campo → error del campo', () => {
+        const m = mapApiError(axiosErr(409, { message: 'conflict', details: 'Key (sku)=(A1) already exists' }), {
+            knownFields: ['sku', 'name'],
+            labels: { sku: 'SKU' },
+        })
+        expect(m.status).toBe(409)
+        expect(m.fields.sku).toBe('Ya existe un registro con ese SKU')
+    })
+    it('409 sin campo → banner general', () => {
+        const m = mapApiError(axiosErr(409, { message: 'Estado inválido' }))
+        expect(m.hasFieldErrors).toBe(false)
+        expect(m.form).toBe('Estado inválido')
+    })
+    it('red caída → fallback', () => {
+        expect(mapApiError(new Error('Network Error'), { fallback: 'Falló' }).form).toContain('Falló')
+    })
+})
+
+describe('line items', () => {
+    it('calcula totales con descuento e impuesto', () => {
+        const lines = [makeLine({ quantity: 2, unit_price: 100, discount: 10, tax_rate: 0.16 }), makeLine({ kind: 'section', description: 'Mano de obra' })]
+        expect(computeTotals(lines)).toMatchObject({ subtotal: 200, discount: 20, tax: 28.8, total: 208.8, units: 2 })
+    })
+    it('valida negativos, descuento y sobreventa según política', () => {
+        const l = makeLine({ description: 'x', quantity: -1, unit_price: -5, discount: 120 })
+        const v = validateLineItems([l])
+        expect(v.valid).toBe(false)
+        expect(Object.keys(v.errors)).toEqual(expect.arrayContaining(['0.quantity', '0.unit_price', '0.discount']))
+        const over = makeLine({ description: 'x', quantity: 5, available: 2 })
+        expect(validateLineItems([over], { stockPolicy: 'warn' })).toMatchObject({ valid: true })
+        expect(validateLineItems([over], { stockPolicy: 'warn' }).warnings['0.quantity']).toBeTruthy()
+        expect(validateLineItems([over], { stockPolicy: 'block' }).valid).toBe(false)
+        expect(validateLineItems([over], { stockPolicy: 'allow' }).warnings).toEqual({})
+    })
+    it('exige al menos un renglón', () => {
+        expect(validateLineItems([]).form).toBeTruthy()
+        expect(validateLineItems([], { requireItems: false }).valid).toBe(true)
+    })
+    it('serializa sin cadenas vacías ni claves de UI y round-trip (PIT-018)', () => {
+        const out = serializeLineItems([
+            makeLine({ description: ' Llanta ', quantity: '2' as unknown as number, unit_price: '' as unknown as number, sku: '', lot: ' L1 ' }),
+            makeLine({ kind: 'note', description: 'Nota' }),
+        ])
+        expect(out[0]).toEqual({ position: 1, kind: 'item', description: 'Llanta', quantity: 2, unit_price: 0, discount: 0, tax_rate: 0, lot: 'L1' })
+        expect(out[1]).toEqual({ position: 2, kind: 'note', description: 'Nota' })
+        expect(out[0]).not.toHaveProperty('key')
+        expect(parseLineItems(out)).toHaveLength(2)
+    })
+})
+
+describe('payment', () => {
+    const methods: PaymentMethodOption[] = [
+        { id: 'cash', label: 'Efectivo', cash: true },
+        { id: 'card', label: 'Tarjeta', requiresReference: true },
+    ]
+    it('cambio solo sobre efectivo', () => {
+        const s = summarizePayment(100, [newTender('cash', 150)], methods)
+        expect(s).toMatchObject({ paid: 150, change: 50, remaining: 0, overpaid: 0, settled: true })
+        const o = summarizePayment(100, [newTender('card', 130)], methods)
+        expect(o).toMatchObject({ change: 0, overpaid: 30 })
+    })
+    it('mixto: la tarjeta pide referencia y no se puede exceder', () => {
+        const t = [newTender('cash', 40), newTender('card', 60)]
+        const v = validatePayment(100, t, methods)
+        expect(v.errors['1.reference']).toBeTruthy()
+        t[1]!.reference = 'AUTH1'
+        expect(validatePayment(100, t, methods).valid).toBe(true)
+        expect(validatePayment(100, [newTender('card', 130)], methods).form).toMatch(/efectivo/)
+    })
+    it('parcial solo con política', () => {
+        const t = [newTender('cash', 30)]
+        expect(validatePayment(100, t, methods).valid).toBe(false)
+        expect(validatePayment(100, t, methods, { allowPartial: true }).valid).toBe(true)
+        expect(serializePayment(t, methods, 100)).toMatchObject({ paid: 30, remaining: 70, change: 0 })
+    })
+})
+
+describe('refund', () => {
+    it('un destino cubre todo', () => {
+        expect(validateRefund(100, singleDestination('cash', 100)).valid).toBe(true)
+    })
+    it('respeta topes, no repite destino y exige cuadrar', () => {
+        const opts = [
+            { kind: 'card' as const, label: 'Tarjeta', maxAmount: 60 },
+            { kind: 'cash' as const, label: 'Efectivo' },
+            { kind: 'credit_note' as const, label: 'NC', available: false, disabledReason: 'Sin CFDI' },
+        ]
+        expect(validateRefund(100, [{ kind: 'card', amount: 80 }], opts).errors['0.amount']).toBeTruthy()
+        expect(validateRefund(100, [{ kind: 'card', amount: 60 }, { kind: 'cash', amount: 40 }], opts).valid).toBe(true)
+        expect(validateRefund(100, [{ kind: 'card', amount: 60 }], opts).form).toMatch(/Falta/)
+        expect(validateRefund(100, [{ kind: 'credit_note', amount: 100 }], opts).errors['0.kind']).toBe('Sin CFDI')
+    })
+})
+
+describe('product search', () => {
+    it('clasifica medida, código de barras, y texto', () => {
+        expect(parseTireSize('205/55R16')?.normalized).toBe('205/55R16')
+        expect(parseTireSize('205 55 16')?.normalized).toBe('205/55R16')
+        expect(parseTireSize('225-45-ZR17')?.normalized).toBe('225/45R17')
+        expect(parseTireSize('999/99R99')).toBeNull()
+        expect(parseProductQuery('7501234567890')).toMatchObject({ kind: 'barcode' })
+        expect(parseProductQuery('205/55R16')).toMatchObject({ kind: 'tire_size' })
+        expect(parseProductQuery('  ')).toMatchObject({ kind: 'empty' })
+        expect(parseProductQuery('michelin')).toMatchObject({ kind: 'text', text: 'michelin' })
+    })
+    it('producto + variante → renglón con existencia por almacén', () => {
+        const line = productToLine(
+            { id: 'p1', name: 'Llanta X', price: 1000, tax_rate: 0.16, variants: [] },
+            { id: 'v1', label: '205/55R16', price: 1200, stock: [{ warehouse_id: 'a', available: 3 }, { warehouse_id: 'b', available: 9 }] },
+            { warehouseId: 'a' },
+        )
+        expect(line).toMatchObject({ product_id: 'v1', unit_price: 1200, tax_rate: 0.16, available: 3, description: 'Llanta X · 205/55R16' })
+    })
+})
+
+import { canTransitionRma, computeReturnTotals, creditNoteRelation, returnSteps, serializeReturn, validateReturnChoices, type ReturnableLine } from './return'
+
+describe('return', () => {
+    const lines: ReturnableLine[] = [
+        { key: 'a', product_id: 'p1', description: 'Llanta', sold: 4, alreadyReturned: 1, unit_price: 1000, tax_rate: 0.16 },
+        { key: 'b', description: 'Servicio', sold: 1, unit_price: 200 },
+    ]
+    const ch = (q: number) => ({ a: { quantity: q, condition: 'sellable' as const, destination: 'stock' as const } })
+    it('tope por devolver = vendido − ya devuelto', () => {
+        expect(validateReturnChoices(lines, ch(4), 'x').errors['a.quantity']).toBeTruthy()
+        expect(validateReturnChoices(lines, ch(3), 'x').valid).toBe(true)
+    })
+    it('exige renglón y motivo; destino coherente con la condición', () => {
+        expect(validateReturnChoices(lines, {}, 'x').valid).toBe(false)
+        expect(validateReturnChoices(lines, ch(1), '').valid).toBe(false)
+        const bad = { a: { quantity: 1, condition: 'sellable' as const, destination: 'scrap' as const } }
+        expect(validateReturnChoices(lines, bad, 'x').errors['a.destination']).toBeTruthy()
+    })
+    it('totales con IVA y relación 03/01', () => {
+        expect(computeReturnTotals(lines, ch(2)).total).toBe(2320)
+        expect(creditNoteRelation(lines, ch(2))).toBe('03')
+        expect(creditNoteRelation(lines, { b: { quantity: 1, condition: 'sellable', destination: 'stock' } })).toBe('01')
+    })
+    it('sin almacén, Recibir es un paso; con almacén no', () => {
+        expect(returnSteps({ warehouseConnected: false })).toContain('receive')
+        expect(returnSteps({ warehouseConnected: true })).not.toContain('receive')
+    })
+    it('serializeReturn omite renglones en 0 y añade NC solo si hay reembolso a NC', () => {
+        const p = serializeReturn({ lines, choices: ch(2), reason: ' defecto ', received: true, refund: [{ kind: 'credit_note', amount: 2320 }] })
+        expect(p.lines).toHaveLength(1)
+        expect(p.reason).toBe('defecto')
+        expect(p.credit_note).toEqual({ relation: '03' })
+        expect(serializeReturn({ lines, choices: ch(2), reason: 'x', received: true, refund: [{ kind: 'cash', amount: 2320 }] }).credit_note).toBeUndefined()
+    })
+})
+
+describe('rma states', () => {
+    it('flujo feliz y motivo obligatorio al rechazar/cancelar', () => {
+        expect(canTransitionRma('draft', 'authorized').ok).toBe(true)
+        expect(canTransitionRma('received', 'settled').ok).toBe(true)
+        expect(canTransitionRma('authorized', 'rejected').ok).toBe(false)
+        expect(canTransitionRma('authorized', 'rejected', 'no aplica').ok).toBe(true)
+        expect(canTransitionRma('closed', 'draft').ok).toBe(false)
+    })
+})

package/src/business/catalog.ts

@@ -0,0 +1,68 @@
+// Catálogo formal de componentes de negocio compartidos (benchmark §7).
+// Es metadato legible por máquina: el contrato estable (props, eventos,
+// permisos) que los addons consumen. Ver docs/business-components.md.
+export interface BusinessComponentSpec {
+    /** Nombre exportado desde `@asteby/metacore-runtime-react`. */
+    name: string
+    /** Prop de datos principal y su tipo. */
+    value: string
+    /** Eventos (props `on*`) que emite. */
+    events: string[]
+    /** Capabilities que consulta con `useCan` (formato `<modelo>.<acción>`). */
+    permissions: string[]
+    /** Módulos donde el benchmark dice que se usa. */
+    usedBy: string[]
+    /** Utilidades puras exportadas junto al componente. */
+    helpers: string[]
+}
+
+export const BUSINESS_COMPONENTS: readonly BusinessComponentSpec[] = [
+    {
+        name: 'CustomerPicker',
+        value: 'value: CustomerResult | null',
+        events: ['onChange'],
+        permissions: ['<model>.create (alta rápida; default Customer → customer.create)'],
+        usedBy: ['POS', 'Cotización', 'Pedido', 'Apartado', 'Factura', 'OT', 'RMA', 'Cobranza'],
+        helpers: [],
+    },
+    {
+        name: 'ProductPicker',
+        value: '(sin estado: search + onSelect)',
+        events: ['onSelect'],
+        permissions: [],
+        usedBy: ['POS', 'Cotización', 'Pedido', 'OC', 'Recepción', 'Traspaso', 'Ajuste', 'OT'],
+        helpers: ['parseProductQuery', 'parseTireSize', 'availableStock', 'productToLine'],
+    },
+    {
+        name: 'LineItemsEditor',
+        value: 'value: LineItem[]',
+        events: ['onChange', 'onValidate', 'onRequestProduct'],
+        permissions: ['editPermission (prop, opcional)'],
+        usedBy: ['Cotización', 'Pedido', 'Factura', 'OC', 'Recepción', 'OT', 'RMA', 'NC'],
+        helpers: ['makeLine', 'computeLine', 'computeTotals', 'validateLineItems', 'serializeLineItems', 'parseLineItems'],
+    },
+    {
+        name: 'PaymentCapture',
+        value: 'value: PaymentTender[]',
+        events: ['onChange', 'onSubmit'],
+        permissions: ['submitPermission (prop, opcional)'],
+        usedBy: ['POS/Caja', 'Apartado', 'Cobranza', 'Factura (Registrar pago)', 'OT'],
+        helpers: ['newTender', 'summarizePayment', 'validatePayment', 'serializePayment'],
+    },
+    {
+        name: 'RefundDestination',
+        value: 'value: RefundAllocation[]',
+        events: ['onChange', 'onValidate'],
+        permissions: [],
+        usedBy: ['ReturnWizard', 'Cancelación de apartado', 'Anticipos'],
+        helpers: ['validateRefund', 'singleDestination', 'DEFAULT_REFUND_DESTINATIONS'],
+    },
+    {
+        name: 'ReturnWizard',
+        value: 'lines: ReturnableLine[]',
+        events: ['onSubmit', 'onCancel'],
+        permissions: [],
+        usedBy: ['POS', 'Pedido', 'Factura', 'RMA', 'OT'],
+        helpers: ['computeReturnTotals', 'validateReturnChoices', 'creditNoteRelation', 'returnSteps', 'serializeReturn'],
+    },
+] as const

package/src/business/customer-picker.tsx

@@ -0,0 +1,201 @@
+// CustomerPicker + alta rápida — busca por nombre, RFC/ID fiscal, teléfono, placa
+// o VIN; muestra saldo, crédito y alertas (benchmark §7). El alta rápida reutiliza
+// el <CreateRecordDialog> dinámico del modelo (formulario desde metadata).
+import { useCallback, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Plus, Search, X } from 'lucide-react'
+import { Badge, Button, Input } from '@asteby/metacore-ui'
+import { CreateRecordDialog } from '../dialogs/create-record-dialog'
+import { useApi } from '../api-context'
+import { useCan } from '../permissions-context'
+import { useFormatter } from './format'
+import { useAsyncSearch } from './use-async-search'
+import { EmptyState } from './feedback'
+
+export interface CustomerResult {
+    id: string
+    name: string
+    /** Identificador fiscal (RFC u homólogo): dato de la org, sin formato hardcodeado. */
+    tax_id?: string
+    phone?: string
+    email?: string
+    plate?: string
+    vin?: string
+    /** Saldo por cobrar (adeudo). */
+    balance?: number
+    credit_limit?: number
+    /** Alertas visibles: «Cliente con adeudo vencido», «Lista negra». */
+    alerts?: string[]
+}
+
+export interface CustomerPickerProps {
+    value: CustomerResult | null
+    /** Evento único de cambio: cliente elegido/creado, o `null` al limpiar. */
+    onChange: (customer: CustomerResult | null) => void
+    /** Búsqueda (nombre, ID fiscal, teléfono, placa, VIN). Estable (useCallback). */
+    search: (q: string, signal: AbortSignal) => Promise<CustomerResult[]>
+    /** Modelo del kernel para el alta rápida. Default `Customer`. */
+    model?: string
+    /** Endpoint CRUD del alta. Default `/data/<model>/me`. */
+    endpoint?: string
+    /** Convierte el registro guardado a `CustomerResult`. Default: id + name. */
+    mapRecord?: (rec: Record<string, unknown>) => CustomerResult
+    /** Valida el ID fiscal según la config de la org; devuelve el mensaje o undefined. */
+    validateTaxId?: (taxId: string) => string | undefined
+    /** Overrides de permiso (default `<model>.create` con useCan). */
+    canCreate?: boolean
+    /** Valores iniciales del alta rápida (p. ej. el texto buscado como nombre). */
+    createDefaults?: Record<string, unknown>
+    currency?: string
+    disabled?: boolean
+    placeholder?: string
+}
+
+function snake(model: string): string {
+    return model.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()
+}
+
+export function CustomerPicker({
+    value,
+    onChange,
+    search,
+    model = 'Customer',
+    endpoint,
+    mapRecord,
+    validateTaxId,
+    canCreate,
+    createDefaults,
+    currency,
+    disabled,
+    placeholder,
+}: CustomerPickerProps) {
+    const { t } = useTranslation()
+    const api = useApi()
+    const can = useCan()
+    const fmt = useFormatter({ currency })
+    const [text, setText] = useState('')
+    const [creating, setCreating] = useState(false)
+    const { results, loading, error } = useAsyncSearch(text, search, { minChars: 2 })
+    const mayCreate = canCreate ?? can(`${snake(model)}.create`)
+    const base = endpoint ?? `/data/${model}/me`
+    const taxIdError = value?.tax_id && validateTaxId ? validateTaxId(value.tax_id) : undefined
+
+    const pick = (c: CustomerResult) => {
+        onChange(c)
+        setText('')
+    }
+    const toResult = useCallback(
+        (rec: Record<string, unknown>): CustomerResult =>
+            mapRecord
+                ? mapRecord(rec)
+                : {
+                      id: String(rec.id ?? ''),
+                      name: String(rec.name ?? ''),
+                      tax_id: typeof rec.tax_id === 'string' ? rec.tax_id : undefined,
+                      phone: typeof rec.phone === 'string' ? rec.phone : undefined,
+                  },
+        [mapRecord],
+    )
+
+    if (value) {
+        const overLimit = value.credit_limit != null && (value.balance ?? 0) > value.credit_limit
+        return (
+            <div data-slot="customer-picker" className="space-y-1 rounded-md border p-2">
+                <div className="flex items-start justify-between gap-2">
+                    <div>
+                        <p className="text-sm font-medium">{value.name}</p>
+                        <p className="text-xs text-muted-foreground">
+                            {[value.tax_id, value.phone, value.plate, value.vin].filter(Boolean).join(' · ')}
+                        </p>
+                    </div>
+                    {!disabled && (
+                        <Button type="button" size="icon" variant="ghost" onClick={() => onChange(null)} aria-label={t('customerPicker.clear', { defaultValue: 'Quitar cliente' })}>
+                            <X className="size-4" />
+                        </Button>
+                    )}
+                </div>
+                <div className="flex flex-wrap gap-1.5">
+                    {value.balance != null && value.balance !== 0 && (
+                        <Badge variant={overLimit ? 'danger' : 'warning'}>
+                            {t('customerPicker.balance', { defaultValue: 'Adeudo' })} {fmt.money(value.balance)}
+                        </Badge>
+                    )}
+                    {value.credit_limit != null && (
+                        <Badge variant="muted">
+                            {t('customerPicker.credit', { defaultValue: 'Crédito' })} {fmt.money(value.credit_limit)}
+                        </Badge>
+                    )}
+                    {value.alerts?.map((a) => (
+                        <Badge key={a} variant="danger">{a}</Badge>
+                    ))}
+                </div>
+                {taxIdError && <p role="alert" className="text-xs text-destructive">{taxIdError}</p>}
+            </div>
+        )
+    }
+
+    return (
+        <div data-slot="customer-picker" className="space-y-2">
+            <div className="flex items-center gap-1.5">
+                <div className="relative flex-1">
+                    <Search className="pointer-events-none absolute left-2.5 top-2.5 size-4 text-muted-foreground" aria-hidden />
+                    <Input
+                        className="pl-8"
+                        disabled={disabled}
+                        value={text}
+                        placeholder={placeholder ?? t('customerPicker.placeholder', { defaultValue: 'Nombre, RFC, teléfono, placa o VIN' })}
+                        onChange={(e) => setText(e.target.value)}
+                    />
+                </div>
+                {mayCreate && (
+                    <Button type="button" variant="outline" size="icon" disabled={disabled} onClick={() => setCreating(true)} aria-label={t('customerPicker.create', { defaultValue: 'Nuevo cliente' })}>
+                        <Plus className="size-4" />
+                    </Button>
+                )}
+            </div>
+            {loading && <p className="text-sm text-muted-foreground">{t('common.searching', { defaultValue: 'Buscando…' })}</p>}
+            {error && !loading && (
+                <p role="alert" className="text-sm text-destructive">
+                    {t('customerPicker.error', { defaultValue: 'No se pudo buscar clientes. Inténtalo de nuevo.' })}
+                </p>
+            )}
+            {!loading && !error && text.trim().length >= 2 && results.length === 0 && (
+                <EmptyState
+                    title={t('customerPicker.empty', { defaultValue: 'No encontramos a ese cliente' })}
+                    action={mayCreate ? { label: t('customerPicker.createAction', { defaultValue: 'Crear cliente' }), onClick: () => setCreating(true) } : undefined}
+                />
+            )}
+            {results.length > 0 && (
+                <ul role="listbox" className="max-h-64 divide-y overflow-auto rounded-md border">
+                    {results.map((c) => (
+                        <li key={c.id} role="option" aria-selected={false}>
+                            <button type="button" className="flex w-full items-center justify-between gap-2 px-2 py-1.5 text-left hover:bg-accent" onClick={() => pick(c)}>
+                                <span>
+                                    <span className="block text-sm font-medium">{c.name}</span>
+                                    <span className="block text-xs text-muted-foreground">{[c.tax_id, c.phone, c.plate, c.vin].filter(Boolean).join(' · ')}</span>
+                                </span>
+                                {c.balance != null && c.balance > 0 && <Badge variant="warning">{fmt.money(c.balance)}</Badge>}
+                            </button>
+                        </li>
+                    ))}
+                </ul>
+            )}
+
+            {creating && (
+                <CreateRecordDialog
+                    modelKey={model}
+                    open={creating}
+                    onOpenChange={setCreating}
+                    endpoint={base}
+                    defaults={createDefaults ?? (text.trim() ? { name: text.trim() } : undefined)}
+                    onCreate={async (data) => {
+                        const res = await api.post(base, data)
+                        const rec = (res.data?.data ?? res.data) as Record<string, unknown>
+                        pick(toResult(rec))
+                        return rec.id != null ? { id: String(rec.id) } : undefined
+                    }}
+                />
+            )}
+        </div>
+    )
+}