@asteby/metacore-runtime-react 49.5.0 → 49.7.0

package/src/business/customer-picker.tsx

@@ -1,16 +1,14 @@
 // 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
+// o VIN; muestra saldo, crédito y alertas (benchmark §7). Configuración del
+// <RecordPicker> compartido: el alta rápida (y la edición del elegido) 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 { Badge } from '@asteby/metacore-ui'
+import { RecordPicker, useLatestSearch } from '../record-picker'
+import { useRecordPickerDialog } from '../record-picker-dialog'
 import { useCan } from '../permissions-context'
 import { useFormatter } from './format'
-import { useAsyncSearch } from './use-async-search'
-import { EmptyState } from './feedback'
 
 export interface CustomerResult {
     id: string
@@ -32,7 +30,7 @@ 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). */
+    /** Búsqueda (nombre, ID fiscal, teléfono, placa, VIN). */
     search: (q: string, signal: AbortSignal) => Promise<CustomerResult[]>
     /** Modelo del kernel para el alta rápida. Default `Customer`. */
     model?: string
@@ -44,6 +42,8 @@ export interface CustomerPickerProps {
     validateTaxId?: (taxId: string) => string | undefined
     /** Overrides de permiso (default `<model>.create` con useCan). */
     canCreate?: boolean
+    /** Override de permiso para editar al elegido (default `<model>.update`). */
+    canEdit?: boolean
     /** Valores iniciales del alta rápida (p. ej. el texto buscado como nombre). */
     createDefaults?: Record<string, unknown>
     currency?: string
@@ -55,6 +55,12 @@ function snake(model: string): string {
     return model.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()
 }
 
+const customerLine = (c: CustomerResult) => [c.tax_id, c.phone, c.plate, c.vin].filter(Boolean).join(' · ')
+
+/**
+ * @deprecated Configuración fina de {@link RecordPicker}; se conserva para no
+ * romper consumidores.
+ */
 export function CustomerPicker({
     value,
     onChange,
@@ -64,26 +70,22 @@ export function CustomerPicker({
     mapRecord,
     validateTaxId,
     canCreate,
+    canEdit,
     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 [open, setOpen] = useState(false)
+    const searchFn = useLatestSearch(search)
     const mayCreate = canCreate ?? can(`${snake(model)}.create`)
-    const base = endpoint ?? `/data/${model}/me`
+    const mayEdit = canEdit ?? can(`${snake(model)}.update`)
     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
@@ -96,24 +98,23 @@ export function CustomerPicker({
                   },
         [mapRecord],
     )
+    const { openCreate, openEdit, dialog } = useRecordPickerDialog({
+        model,
+        endpoint,
+        prefillField: 'name',
+        createDefaults,
+        onSaved: (rec, kind) => {
+            const next = toResult(rec)
+            // Al editar se conservan saldo/crédito/alertas que el registro no trae.
+            onChange(kind === 'edit' && value ? { ...value, ...next } : next)
+            setText('')
+        },
+    })
 
-    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>
+    const overLimit = !!value && value.credit_limit != null && (value.balance ?? 0) > value.credit_limit
+    const below = value ? (
+        <>
+            {(value.balance != null && value.balance !== 0) || value.credit_limit != null || value.alerts?.length ? (
                 <div className="flex flex-wrap gap-1.5">
                     {value.balance != null && value.balance !== 0 && (
                         <Badge variant={overLimit ? 'danger' : 'warning'}>
@@ -129,73 +130,61 @@ export function CustomerPicker({
                         <Badge key={a} variant="danger">{a}</Badge>
                     ))}
                 </div>
-                {taxIdError && <p role="alert" className="text-xs text-destructive">{taxIdError}</p>}
-            </div>
-        )
-    }
+            ) : null}
+            {taxIdError && <p role="alert" className="text-xs text-destructive">{taxIdError}</p>}
+        </>
+    ) : null
 
     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>
+        <>
+            <RecordPicker<CustomerResult>
+                trigger="input"
+                slot="customer-picker"
+                search={searchFn}
+                minChars={2}
+                query={text}
+                onQueryChange={setText}
+                open={open}
+                onOpenChange={setOpen}
+                getKey={(c) => c.id}
+                getLabel={(c) => c.name}
+                renderItem={(c) => (
+                    <span className="flex w-full min-w-0 items-center justify-between gap-2">
+                        <span className="min-w-0">
+                            <span className="block truncate font-medium">{c.name}</span>
+                            <span className="block truncate text-xs text-muted-foreground">{customerLine(c)}</span>
+                        </span>
+                        {c.balance != null && c.balance > 0 && <Badge variant="warning">{fmt.money(c.balance)}</Badge>}
+                    </span>
                 )}
-            </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>
+                value={value?.id ?? null}
+                selected={value}
+                onSelect={(c) => onChange(c)}
+                onClear={disabled ? undefined : () => onChange(null)}
+                clearLabel={t('customerPicker.clear', { defaultValue: 'Quitar cliente' })}
+                renderValue={(c) =>
+                    c ? (
+                        <span className="block min-w-0">
+                            <span className="block truncate text-sm font-medium">{c.name}</span>
+                            {customerLine(c) && <span className="block truncate text-xs text-muted-foreground">{customerLine(c)}</span>}
+                        </span>
+                    ) : null
+                }
+                below={below}
+                disabled={disabled}
+                placeholder={placeholder ?? t('customerPicker.placeholder', { defaultValue: 'Nombre, RFC, teléfono, placa o VIN' })}
+                loadingText={t('common.searching', { defaultValue: 'Buscando…' })}
+                errorText={t('customerPicker.error', { defaultValue: 'No se pudo buscar clientes. Inténtalo de nuevo.' })}
+                emptyText={t('customerPicker.empty', { defaultValue: 'No encontramos a ese cliente' })}
+                entityLabel={t('customerPicker.entity', { defaultValue: 'cliente' })}
+                createLabel={t('customerPicker.create', { defaultValue: 'Nuevo cliente' })}
+                editLabel={t('customerPicker.edit', { defaultValue: 'Editar cliente' })}
+                createFooter="empty"
+                createFooterLabel={() => t('customerPicker.createAction', { defaultValue: 'Crear cliente' })}
+                onCreate={mayCreate ? (q) => openCreate(q) : undefined}
+                onEdit={mayEdit && value ? () => openEdit(value.id) : undefined}
+            />
+            {dialog}
+        </>
     )
 }

package/src/business/index.ts

@@ -11,6 +11,7 @@ export * from './refund'
 export * from './refund-destination'
 export * from './product-search'
 export * from './product-picker'
+export * from './product-options'
 export * from './customer-picker'
 export * from './catalog'
 export * from './return'

package/src/business/line-product-cell.tsx

@@ -1,27 +1,30 @@
 // LineProductCell — buscador de producto DENTRO de la celda «Descripción» de un
-// renglón (patrón de editor de facturas pro: Odoo/Holded/Linear). Ocupa solo su
-// celda; la lista de resultados va en un portal (Popover de Radix anclado al
-// input): nunca la recorta el overflow de la tabla ni del modal, queda por
-// encima del diálogo y se abre hacia arriba si abajo no hay espacio.
+// renglón (patrón de editor de facturas pro: Odoo/Holded/Linear). Es una
+// configuración del <RecordPicker> compartido (trigger «input», texto libre,
+// variante celda): ocupa solo su celda y la lista va en un portal — nunca la
+// recorta el overflow de la tabla ni del modal, queda por encima del diálogo y
+// se abre hacia arriba si abajo no hay espacio.
 //
 // Teclado: ↑/↓ recorren, Enter elige (el grid pasa el foco a «Cant.»), Esc
 // cierra, Tab cierra y avanza normal. El texto escrito sin elegir queda como
 // descripción libre (el renglón libre sigue funcionando igual).
-import { forwardRef, useId, useMemo, useRef, useState, type KeyboardEvent } from 'react'
+import { forwardRef, useState, type KeyboardEvent } from 'react'
 import { useTranslation } from 'react-i18next'
-import { Loader2, Search } from 'lucide-react'
-import { Badge, Input, Popover, PopoverAnchor, PopoverContent } from '@asteby/metacore-ui/primitives'
-import { useFormatter } from './format'
-import { useAsyncSearch } from './use-async-search'
-import { useDebouncedValue } from '../use-debounced-value'
-import { availableStock, parseProductQuery, type ProductQuery, type ProductResult, type ProductVariant } from './product-search'
+import { RecordPicker } from '../record-picker'
+import {
+    ProductHitRow,
+    productHitKey,
+    productHitLabel,
+    useProductSearch,
+    type ProductHit,
+    type ProductSearchFn,
+} from './product-options'
+import type { ProductResult, ProductVariant } from './product-search'
 
-export type LineProductSearch = (query: Exclude<ProductQuery, { kind: 'empty' }>, signal: AbortSignal) => Promise<ProductResult[]>
+export type LineProductSearch = ProductSearchFn
 
-export interface LineProductHit {
-    product: ProductResult
-    variant?: ProductVariant
-}
+/** @deprecated Alias de {@link ProductHit}. */
+export type LineProductHit = ProductHit
 
 export interface LineProductCellProps {
     search: LineProductSearch
@@ -30,8 +33,9 @@ export interface LineProductCellProps {
     onTextChange: (text: string) => void
     onPick: (product: ProductResult, variant?: ProductVariant) => void
     /**
-     * Teclas que el buscador no consume (lista cerrada): el grid aplica sus
-     * comandos (Enter agrega, Supr en celda vacía borra…).
+     * Teclas que el buscador no consume (lista cerrada, Enter sin
+     * coincidencias…): el grid aplica sus comandos (Enter agrega, Supr en
+     * celda vacía borra…).
      */
     onKeyDownClosed?: (e: KeyboardEvent<HTMLInputElement>) => void
     warehouseId?: string
@@ -50,170 +54,41 @@ export const LineProductCell = forwardRef<HTMLInputElement, LineProductCellProps
     ref,
 ) {
     const { t } = useTranslation()
-    const fmt = useFormatter({ currency })
-    const listId = useId()
-    const anchorRef = useRef<HTMLDivElement>(null)
-    // Solo se abre mientras se escribe: enfocar un renglón libre ya capturado no
-    // despliega «sin resultados» encima de la tabla.
+    // Solo se busca/abre mientras se escribe: enfocar un renglón libre ya
+    // capturado no despliega «sin resultados» encima de la tabla.
     const [typing, setTyping] = useState(false)
-    const [active, setActive] = useState(0)
-    const parsed = parseProductQuery(text)
-    const run = useMemo(
-        () => (q: string, signal: AbortSignal) => {
-            const p = parseProductQuery(q)
-            return p.kind === 'empty' ? Promise.resolve([]) : search(p, signal)
-        },
-        [search],
-    )
-    const minChars = parsed.kind === 'barcode' ? 8 : 2
-    const delay = parsed.kind === 'barcode' ? 0 : 250
-    const { results, loading: fetching } = useAsyncSearch(typing ? text : '', run, { minChars, delay })
-    // Mientras el debounce no alcanza lo escrito, la lista dice «Buscando…» y no
-    // un «sin coincidencias» prematuro.
-    const settled = useDebouncedValue(text.trim(), delay) === text.trim()
-    const loading = fetching || !settled
-    const flat = useMemo<LineProductHit[]>(
-        () =>
-            results.flatMap((p) =>
-                (p.variants?.length ?? 0) > 0 ? p.variants!.map((v) => ({ product: p, variant: v })) : [{ product: p }],
-            ),
-        [results],
-    )
-    const queryReady = typing && text.trim().length >= minChars
-    const open = queryReady && (loading || flat.length > 0 || text.trim().length >= 2)
-    const hasHits = flat.length > 0
-
-    const close = () => {
-        setTyping(false)
-        setActive(0)
-    }
-    const choose = (idx: number) => {
-        const hit = flat[idx]
-        if (!hit) return
-        close()
-        onPick(hit.product, hit.variant)
-    }
-
-    const onKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
-        if (open && hasHits) {
-            if (e.key === 'ArrowDown') {
-                e.preventDefault()
-                setActive((n) => Math.min(flat.length - 1, n + 1))
-                return
-            }
-            if (e.key === 'ArrowUp') {
-                e.preventDefault()
-                setActive((n) => Math.max(0, n - 1))
-                return
-            }
-            if (e.key === 'Enter') {
-                e.preventDefault()
-                choose(active)
-                return
-            }
-        }
-        if (open && e.key === 'Escape') {
-            // Cierra la lista sin cerrar el diálogo que la contiene.
-            e.preventDefault()
-            e.stopPropagation()
-            close()
-            return
-        }
-        if (e.key === 'Tab') close()
-        onKeyDownClosed?.(e)
-    }
+    const { hits, loading, minChars } = useProductSearch(typing ? text : '', search, typing)
 
     return (
-        <Popover open={open} onOpenChange={(o) => !o && close()}>
-            <PopoverAnchor asChild>
-                <div ref={anchorRef} className="relative w-full min-w-0" data-slot="line-product-cell">
-                    <Search className="pointer-events-none absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" aria-hidden />
-                    <Input
-                        ref={ref}
-                        value={text}
-                        disabled={disabled}
-                        role="combobox"
-                        aria-autocomplete="list"
-                        aria-expanded={open}
-                        aria-controls={open ? listId : undefined}
-                        aria-activedescendant={open && hasHits ? `${listId}-${active}` : undefined}
-                        aria-label={ariaLabel}
-                        aria-invalid={invalid || undefined}
-                        autoComplete="off"
-                        data-cell={dataCell}
-                        placeholder={placeholder ?? t('lineItems.searchPlaceholder', { defaultValue: 'Producto, medida (205/55R16), SKU o código de barras' })}
-                        className={'h-8 pl-8 ' + (className ?? '')}
-                        onChange={(e) => {
-                            onTextChange(e.target.value)
-                            setTyping(true)
-                            setActive(0)
-                        }}
-                        onBlur={() => close()}
-                        onKeyDown={onKeyDown}
-                    />
-                </div>
-            </PopoverAnchor>
-            <PopoverContent
-                align="start"
-                sideOffset={4}
-                collisionPadding={8}
-                className="p-1"
-                data-slot="line-product-results"
-                // El foco se queda en la celda: se sigue escribiendo mientras se ve la lista.
-                onOpenAutoFocus={(e) => e.preventDefault()}
-                onCloseAutoFocus={(e) => e.preventDefault()}
-                onInteractOutside={(e) => {
-                    if (anchorRef.current?.contains(e.target as Node)) e.preventDefault()
-                }}
-                style={{ width: 'max(var(--radix-popover-trigger-width), 22rem)', maxWidth: 'calc(100vw - 1rem)' }}
-            >
-                {hasHits ? (
-                    <ul id={listId} role="listbox" aria-label={ariaLabel} className="max-h-72 overflow-auto">
-                        {flat.map((hit, idx) => {
-                            const price = hit.variant?.price ?? hit.product.price
-                            const stock = availableStock(hit.variant ?? hit.product, warehouseId)
-                            const meta = [hit.variant?.sku ?? hit.product.sku, hit.product.tire?.normalized].filter(Boolean).join(' · ')
-                            return (
-                                <li key={`${hit.product.id}:${hit.variant?.id ?? ''}`} id={`${listId}-${idx}`} role="option" aria-selected={idx === active}>
-                                    <button
-                                        type="button"
-                                        tabIndex={-1}
-                                        className={
-                                            'flex w-full items-center justify-between gap-3 rounded-sm px-2 py-1.5 text-left text-sm outline-none hover:bg-accent hover:text-accent-foreground ' +
-                                            (idx === active ? 'bg-accent text-accent-foreground' : '')
-                                        }
-                                        onMouseDown={(e) => e.preventDefault()}
-                                        onMouseEnter={() => setActive(idx)}
-                                        onClick={() => choose(idx)}
-                                    >
-                                        <span className="min-w-0">
-                                            <span className="block truncate font-medium">{hit.variant ? `${hit.product.name} · ${hit.variant.label}` : hit.product.name}</span>
-                                            {meta && <span className="block truncate text-xs text-muted-foreground">{meta}</span>}
-                                        </span>
-                                        <span className="flex shrink-0 items-center gap-2">
-                                            {stock != null && (
-                                                <Badge variant="secondary" className="font-normal tabular-nums">
-                                                    {stock}
-                                                </Badge>
-                                            )}
-                                            {price != null && <span className="tabular-nums">{fmt.money(price)}</span>}
-                                        </span>
-                                    </button>
-                                </li>
-                            )
-                        })}
-                    </ul>
-                ) : loading ? (
-                    <p className="flex items-center justify-center gap-2 py-4 text-sm text-muted-foreground">
-                        <Loader2 className="size-4 animate-spin" aria-hidden />
-                        {t('common.searching', { defaultValue: 'Buscando…' })}
-                    </p>
-                ) : (
-                    <p className="px-2 py-3 text-sm text-muted-foreground">
-                        {t('lineItems.noProduct', { defaultValue: 'Sin coincidencias. Se usará como descripción libre.' })}
-                    </p>
-                )}
-            </PopoverContent>
-        </Popover>
+        <RecordPicker<ProductHit>
+            trigger="input"
+            variant="cell"
+            freeText
+            anchorSlot="line-product-cell"
+            contentSlot="line-product-results"
+            minListWidth="22rem"
+            items={hits}
+            loading={loading}
+            minChars={minChars}
+            query={text}
+            onQueryChange={onTextChange}
+            open={typing}
+            onOpenChange={setTyping}
+            getKey={productHitKey}
+            getLabel={productHitLabel}
+            renderItem={(hit) => <ProductHitRow hit={hit} warehouseId={warehouseId} currency={currency} compact />}
+            onSelect={(hit) => onPick(hit.product, hit.variant)}
+            onUnhandledKeyDown={onKeyDownClosed}
+            inputRef={ref}
+            ariaLabel={ariaLabel}
+            listLabel={ariaLabel}
+            disabled={disabled}
+            invalid={invalid}
+            triggerClassName={className}
+            triggerProps={{ 'data-cell': dataCell }}
+            placeholder={placeholder ?? t('lineItems.searchPlaceholder', { defaultValue: 'Producto, medida (205/55R16), SKU o código de barras' })}
+            loadingText={t('common.searching', { defaultValue: 'Buscando…' })}
+            emptyText={t('lineItems.noProduct', { defaultValue: 'Sin coincidencias. Se usará como descripción libre.' })}
+        />
     )
 })

package/src/business/product-options.tsx

@@ -0,0 +1,119 @@
+// Product options for <RecordPicker>: one search (products, tires, variants)
+// and one option row (name · variant, SKU / tire size / supplier code, stock and
+// price on the right) shared by ProductPicker and the DocumentEditor's
+// LineProductCell — so both product pickers are configurations of the same
+// primitive instead of two hand-rolled lists.
+import { useMemo } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Badge } from '@asteby/metacore-ui/primitives'
+import { useLatestSearch, useRecordSearch } from '../record-picker'
+import { useFormatter } from './format'
+import {
+    availableStock,
+    parseProductQuery,
+    type ProductQuery,
+    type ProductResult,
+    type ProductVariant,
+} from './product-search'
+
+/** A pickable row: a product, or one concrete variant of it. */
+export interface ProductHit {
+    product: ProductResult
+    variant?: ProductVariant
+}
+
+export type ProductSearchFn = (
+    query: Exclude<ProductQuery, { kind: 'empty' }>,
+    signal: AbortSignal,
+) => Promise<ProductResult[]>
+
+/** Products with variants expand to one row per variant. */
+export function flattenProductHits(results: readonly ProductResult[]): ProductHit[] {
+    return results.flatMap((p) =>
+        (p.variants?.length ?? 0) > 0 ? p.variants!.map((v) => ({ product: p, variant: v })) : [{ product: p }],
+    )
+}
+
+export const productHitKey = (h: ProductHit): string => `${h.product.id}:${h.variant?.id ?? ''}`
+export const productHitLabel = (h: ProductHit): string =>
+    h.variant ? `${h.product.name} · ${h.variant.label}` : h.product.name
+export const productHitMeta = (h: ProductHit): string =>
+    [
+        h.variant?.sku ?? h.product.sku,
+        h.product.tire?.normalized,
+        h.product.supplier_sku && `Prov. ${h.product.supplier_sku}`,
+    ]
+        .filter(Boolean)
+        .join(' · ')
+
+/**
+ * Classified product search: a barcode is exact (8+ digits, no debounce), the
+ * rest waits for 2 characters and 250ms. `search` needn't be memoized.
+ */
+export function useProductSearch(text: string, search: ProductSearchFn, enabled = true) {
+    const stable = useLatestSearch(search)
+    const parsed = parseProductQuery(text)
+    const run = useMemo(
+        () => (q: string, signal: AbortSignal) => {
+            const p = parseProductQuery(q)
+            return p.kind === 'empty' ? Promise.resolve([] as ProductResult[]) : stable(p, signal)
+        },
+        [stable],
+    )
+    const minChars = parsed.kind === 'barcode' ? 8 : 2
+    const delay = parsed.kind === 'barcode' ? 0 : 250
+    const { results, loading, error, pending } = useRecordSearch(text, run, { minChars, delay, enabled })
+    const hits = useMemo(() => flattenProductHits(results), [results])
+    return { parsed, results, hits, loading: loading || pending, error, minChars }
+}
+
+/** Stock + price at the right of a product row. `compact` → bare stock count (table cell). */
+export function ProductHitTrailing({
+    hit,
+    warehouseId,
+    currency,
+    compact = false,
+}: {
+    hit: ProductHit
+    warehouseId?: string
+    currency?: string
+    compact?: boolean
+}) {
+    const { t } = useTranslation()
+    const fmt = useFormatter({ currency })
+    const price = hit.variant?.price ?? hit.product.price
+    const stock = availableStock(hit.variant ?? hit.product, warehouseId)
+    return (
+        <>
+            {stock != null &&
+                (compact ? (
+                    <Badge variant="secondary" className="font-normal tabular-nums">
+                        {stock}
+                    </Badge>
+                ) : (
+                    <Badge variant={stock > 0 ? 'success' : 'danger'}>
+                        {stock > 0
+                            ? t('productPicker.inStock', { defaultValue: '{{n}} disp.', n: stock })
+                            : t('productPicker.outOfStock', { defaultValue: 'Sin existencia' })}
+                    </Badge>
+                ))}
+            {price != null && <span className="tabular-nums">{fmt.money(price)}</span>}
+        </>
+    )
+}
+
+/** Option body: bold name (· variant), muted meta line, stock/price right. */
+export function ProductHitRow({ hit, warehouseId, currency, compact }: { hit: ProductHit; warehouseId?: string; currency?: string; compact?: boolean }) {
+    const meta = productHitMeta(hit)
+    return (
+        <span className="flex w-full min-w-0 items-center justify-between gap-3">
+            <span className="min-w-0">
+                <span className="block truncate font-medium">{productHitLabel(hit)}</span>
+                {meta && <span className="block truncate text-xs text-muted-foreground">{meta}</span>}
+            </span>
+            <span className="flex shrink-0 items-center gap-2">
+                <ProductHitTrailing hit={hit} warehouseId={warehouseId} currency={currency} compact={compact} />
+            </span>
+        </span>
+    )
+}