@asteby/metacore-runtime-react 49.7.0 → 49.9.0

package/src/__tests__/document-editor-inline-selects.test.tsx

@@ -47,10 +47,17 @@ describe('DocumentLinesGrid — select de producto en la celda', () => {
         const input = screen.getByRole('combobox', { name: 'Buscar producto' })
         const td = input.closest('td')!
         expect(td).toBeTruthy()
-        // Ocupa solo su celda: no hay colSpan sobre toda la fila.
-        expect(td.colSpan).toBe(1)
-        expect(td.closest('tr')!.getAttribute('data-slot')).toBe('line-draft-row')
-        expect(td.closest('tr')!.children.length).toBeGreaterThan(1)
+        // No es una barra a todo lo ancho: el renglón vacío conserva las celdas
+        // de «Importe» y acciones; el buscador usa el ancho de las columnas que
+        // ese renglón aún no llena (cantidad, precio…), así no se corta.
+        const row = td.closest('tr')!
+        expect(row.getAttribute('data-slot')).toBe('line-draft-row')
+        const columns = document.querySelectorAll('[data-slot="line-items-editor"] thead th').length
+        expect(td.colSpan).toBe(columns - 2)
+        expect(row.children.length).toBe(3)
+        // Placeholder corto que cabe; el detalle va como ayuda.
+        expect(input.getAttribute('placeholder')).toBe('Buscar producto…')
+        expect(input.getAttribute('title')).toMatch(/SKU o código de barras/)
     })
 
     it('la lista sale en un portal fuera del contenedor con overflow y Enter elige y pasa a «Cant.»', async () => {

package/src/__tests__/line-row-create-edit.test.tsx

@@ -0,0 +1,312 @@
+// @vitest-environment happy-dom
+//
+// Renglón del DocumentEditor «como las apps top»:
+//   - crear el producto desde la celda («Crear producto «texto»» / «+»): el
+//     producto nuevo entra en ESE renglón y lo llena igual que al elegirlo;
+//   - editar el producto del renglón (lápiz en la celda): el renglón toma los
+//     valores nuevos salvo lo que el usuario sobrescribió, con aviso «aplicar»;
+//   - la tarjeta de la contraparte con etiquetas y catálogos legibles;
+//   - placeholder corto y unidad con su etiqueta (nunca la clave cruda).
+import { useState } from 'react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
+
+vi.mock('@tanstack/react-router', () => ({ useNavigate: () => () => {} }))
+vi.mock('react-i18next', () => {
+    const t = (k: string, o?: Record<string, any>) => {
+        let s: string = o?.defaultValue ?? k
+        for (const [key, v] of Object.entries(o ?? {})) s = s.replace(`{{${key}}}`, String(v))
+        return s
+    }
+    const value = { t, i18n: { language: 'es' } }
+    return { useTranslation: () => value }
+})
+
+import { DocumentLinesGrid } from '../business/line-items-editor'
+import { DocumentEditor } from '../business/document-editor'
+import { makeLine, serializeLineItems, type LineItem } from '../business/line-items'
+import { applyCatalogPending, applyProductToLine, lineOverrides, refreshLineFromProduct } from '../business/document-lines'
+import { fieldDisplayMeta, formatOptionValue, linesFromSource, partySummaryRows } from '../business/document-editor-model'
+import type { ProductResult } from '../business/product-search'
+import { ApiProvider, type ApiClient } from '../api-context'
+import type { DocumentFormType } from '../types'
+
+afterEach(cleanup)
+
+const tire: ProductResult = { id: 'p1', name: 'Llanta 205/55R16', sku: 'LL-205', price: 1500, tax_rate: 0.16, unit: 'unit' }
+
+function Grid(props: { initial?: LineItem[]; onCreateProduct?: any; onEditProduct?: any; unitLabel?: (u: string) => string | undefined }) {
+    const [lines, setLines] = useState(props.initial ?? [])
+    return (
+        <>
+            <DocumentLinesGrid
+                value={lines}
+                onChange={setLines}
+                search={vi.fn(async () => [])}
+                columns={['discount', 'tax']}
+                currency="MXN"
+                onCreateProduct={props.onCreateProduct}
+                onEditProduct={props.onEditProduct}
+                unitLabel={props.unitLabel}
+            />
+            <output data-testid="state">{JSON.stringify(lines)}</output>
+        </>
+    )
+}
+const state = () => JSON.parse(screen.getByTestId('state').textContent ?? '[]') as LineItem[]
+
+async function typeAndCreate(input: HTMLElement, text: string) {
+    input.focus()
+    fireEvent.change(input, { target: { value: text } })
+    const create = await waitFor(() => {
+        const el = document.querySelector('[data-slot="picker-create"]') as HTMLElement | null
+        if (!el) throw new Error('sin pie «Crear»')
+        return el
+    }, { timeout: 2000 })
+    expect(create.textContent).toContain('Crear producto')
+    expect(create.textContent).toContain(`«${text}»`)
+    fireEvent.click(create)
+}
+
+describe('renglón — crear producto desde la celda', () => {
+    it('el renglón vacío del final: «Crear producto «texto»» abre el alta prellenada y el producto nuevo llena el renglón', async () => {
+        let resolve!: (p: ProductResult) => void
+        const onCreate = vi.fn(() => new Promise<ProductResult>((r) => (resolve = r)))
+        render(<Grid onCreateProduct={onCreate} unitLabel={(u) => (u === 'unit' ? 'pza' : undefined)} />)
+        await typeAndCreate(screen.getByRole('combobox', { name: 'Buscar producto' }), 'Llanta nueva')
+        expect(onCreate).toHaveBeenCalledWith('Llanta nueva')
+        // Mientras el modal está abierto no se agrega nada.
+        expect(state()).toHaveLength(0)
+        await act(async () => resolve({ ...tire, id: 'p9', name: 'Llanta nueva', sku: 'LL-NEW', price: 2450 }))
+        await waitFor(() => expect(state()).toHaveLength(1))
+        expect(state()[0]).toMatchObject({ product_id: 'p9', description: 'Llanta nueva', sku: 'LL-NEW', unit_price: 2450, catalog_price: 2450, tax_rate: 0.16, unit: 'unit', quantity: 1 })
+        // La unidad con su etiqueta, nunca la clave cruda.
+        const row = document.querySelector(`[data-line-key="${state()[0].key}"]`)!
+        expect(row.textContent).toContain('LL-NEW · pza')
+        expect(row.textContent).not.toContain('· unit')
+        await waitFor(() => expect((document.activeElement as HTMLElement | null)?.getAttribute('data-cell')).toBe('quantity'))
+    })
+
+    it('un renglón libre (sin producto): el producto creado queda en ESE renglón, no en uno nuevo', async () => {
+        const free = makeLine({ description: '', quantity: 3 })
+        const onCreate = vi.fn(async () => ({ ...tire, id: 'p7', name: 'Rin 16' }))
+        render(<Grid initial={[free]} onCreateProduct={onCreate} />)
+        const cell = screen.getAllByRole('combobox', { name: 'Descripción' })[0]
+        await typeAndCreate(cell, 'Rin 16')
+        await waitFor(() => expect(state()[0].product_id).toBe('p7'))
+        expect(state()).toHaveLength(1)
+        expect(state()[0]).toMatchObject({ key: free.key, description: 'Rin 16', quantity: 3, unit_price: 1500 })
+    })
+
+    it('el «+» unido al buscador también abre el alta', async () => {
+        const onCreate = vi.fn(() => new Promise<ProductResult>(() => {}))
+        render(<Grid onCreateProduct={onCreate} />)
+        const draft = document.querySelector('[data-slot="line-draft-row"]') as HTMLElement
+        fireEvent.click(within(draft).getByRole('button', { name: 'Crear producto' }))
+        expect(onCreate).toHaveBeenCalledWith('')
+    })
+
+    it('sin `onCreateProduct` no hay pie ni «+» (otros usos del grid quedan igual)', () => {
+        render(<Grid />)
+        const draft = document.querySelector('[data-slot="line-draft-row"]') as HTMLElement
+        expect(within(draft).queryByRole('button', { name: 'Crear producto' })).toBeNull()
+    })
+})
+
+describe('renglón — editar el producto desde la celda', () => {
+    it('lápiz accesible por teclado; al guardar actualiza lo que sigue igual al catálogo y respeta el precio capturado con aviso «aplicar»', async () => {
+        const picked = applyProductToLine(makeLine({ quantity: 2 }), tire)
+        let resolve!: (p: ProductResult) => void
+        const onEdit = vi.fn(() => new Promise<ProductResult>((r) => (resolve = r)))
+        render(<Grid initial={[picked]} onEditProduct={onEdit} />)
+        // El usuario cambia el precio a mano (override).
+        const price = screen.getByRole('textbox', { name: 'Precio' })
+        fireEvent.change(price, { target: { value: '1400' } })
+        const pencil = screen.getByRole('button', { name: 'Editar producto' })
+        expect(pencil.tagName).toBe('BUTTON')
+        expect(pencil.getAttribute('tabindex')).not.toBe('-1')
+        fireEvent.click(pencil)
+        expect(onEdit).toHaveBeenCalledWith(expect.objectContaining({ product_id: 'p1' }))
+        await act(async () => resolve({ ...tire, name: 'Llanta 205/55R16 XL', sku: 'LL-205XL', price: 1650, tax_rate: 0.08, unit: 'set' }))
+        await waitFor(() => expect(state()[0].description).toBe('Llanta 205/55R16 XL'))
+        const l = state()[0]
+        expect(l).toMatchObject({ sku: 'LL-205XL', tax_rate: 0.08, unit: 'set', catalog_price: 1650, quantity: 2 })
+        // Override respetado.
+        expect(l.unit_price).toBe(1400)
+        const notice = document.querySelector('[data-slot="catalog-pending"]') as HTMLElement
+        expect(notice.textContent).toMatch(/Precio de catálogo cambió a .*1,650\.00/)
+        fireEvent.click(within(notice).getByRole('button', { name: 'aplicar' }))
+        await waitFor(() => expect(state()[0].unit_price).toBe(1650))
+        expect(document.querySelector('[data-slot="catalog-pending"]')).toBeNull()
+    })
+
+    it('sin overrides no hay aviso: todo el renglón toma el catálogo nuevo', async () => {
+        const picked = applyProductToLine(makeLine(), tire)
+        render(<Grid initial={[picked]} onEditProduct={vi.fn(async () => ({ ...tire, price: 1800 }))} />)
+        fireEvent.click(screen.getByRole('button', { name: 'Editar producto' }))
+        await waitFor(() => expect(state()[0].unit_price).toBe(1800))
+        expect(document.querySelector('[data-slot="catalog-pending"]')).toBeNull()
+    })
+
+    it('sin `onEditProduct` no hay lápiz', () => {
+        render(<Grid initial={[applyProductToLine(makeLine(), tire)]} />)
+        expect(screen.queryByRole('button', { name: 'Editar producto' })).toBeNull()
+    })
+})
+
+describe('refreshLineFromProduct (puro)', () => {
+    it('dirty por campo: solo pisa lo que sigue igual a la foto del catálogo', () => {
+        const line = { ...applyProductToLine(makeLine(), tire), description: 'Llanta con nombre del cliente' }
+        expect([...lineOverrides(line)]).toEqual(['description'])
+        const next = refreshLineFromProduct(line, { ...tire, name: 'Llanta nueva', price: 1600 })
+        expect(next.description).toBe('Llanta con nombre del cliente')
+        expect(next.unit_price).toBe(1600)
+        expect(next.catalog_pending).toEqual({ description: 'Llanta nueva' })
+        // La foto avanza: el override sigue siéndolo, lo demás queda limpio.
+        expect([...lineOverrides(next)]).toEqual(['description'])
+        expect(applyCatalogPending(next).description).toBe('Llanta nueva')
+    })
+
+    it('renglón de un documento origen: no cambia cantidad, tope ni vínculo, ni pisa los precios del origen', () => {
+        const [src] = linesFromSource([{ id: 'sol-1', product_id: 'p1', product_name: 'Llanta', quantity: 4, remaining_quantity: 2, unit_price: 1300, tax_rate: 0.16 }])
+        const next = refreshLineFromProduct(src, { ...tire, price: 1700 })
+        expect(next).toMatchObject({ quantity: 2, max_quantity: 2, source_line_id: 'sol-1', unit_price: 1300, description: 'Llanta', product_id: 'p1' })
+        expect(next.catalog_pending?.unit_price).toBe(1700)
+    })
+
+    it('la foto y el aviso no viajan al backend', () => {
+        const next = refreshLineFromProduct({ ...applyProductToLine(makeLine(), tire), unit_price: 1 }, { ...tire, price: 2 })
+        const [row] = serializeLineItems([next])
+        expect(row).not.toHaveProperty('catalog')
+        expect(row).not.toHaveProperty('catalog_pending')
+    })
+})
+
+describe('tarjeta de la contraparte', () => {
+    it('etiqueta del campo, valores de catálogo «código · texto» y sin vacíos ni claves crudas', () => {
+        const meta = fieldDisplayMeta([
+            [{ key: 'tax_id', label: 'customers.field.tax_id' }, { key: 'email', label: 'Correo' }],
+            [{ key: 'fiscal_data.uso_cfdi', label: 'Uso del CFDI', options: [{ value: 'G03', label: 'Gastos en general' }] }],
+        ], (s) => (s === 'customers.field.tax_id' ? 'RFC' : s))
+        const rows = partySummaryRows(
+            { tax_id: 'TBA850312KJ9', email: '  ', fiscal_data: { uso_cfdi: 'G03', regimen: '601' } },
+            ['tax_id', 'email'],
+            {},
+            6,
+            meta,
+        )
+        expect(rows).toEqual([
+            { key: 'tax_id', label: 'RFC', value: 'TBA850312KJ9' },
+            { key: 'fiscal_data.uso_cfdi', label: 'Uso del CFDI', value: 'G03 · Gastos en general' },
+            { key: 'fiscal_data.regimen', label: 'Regimen', value: '601' },
+        ])
+    })
+
+    it('formatOptionValue: la etiqueta que ya trae el código va tal cual; sin opción, el valor', () => {
+        expect(formatOptionValue('G03', [{ value: 'G03', label: 'G03 · Gastos en general' }])).toBe('G03 · Gastos en general')
+        expect(formatOptionValue('active', [{ value: 'active', label: 'Activo' }])).toBe('Activo')
+        expect(formatOptionValue('X', [])).toBe('X')
+    })
+})
+
+// ---- DocumentEditor: el puente con el host ----------------------------------
+
+const invoice: DocumentFormType = {
+    key: 'invoice',
+    label: 'Factura',
+    value: 'I',
+    layout: 'editor',
+    party: { field: 'customer_id', model: 'customers.Customer', summary: ['tax_id', 'email'] },
+    fields: [{ key: 'customer_id', label: 'Cliente', type: 'text', required: true }],
+    lines: { columns: ['tax'] },
+    submit_label: 'Guardar factura',
+}
+
+function makeApi(routes: Record<string, (url: string, cfg?: any) => unknown>) {
+    const get = vi.fn(async (url: string, cfg?: any) => {
+        for (const [prefix, fn] of Object.entries(routes)) if (url === prefix || url.startsWith(prefix + '?')) return { data: fn(url, cfg) }
+        if (url.startsWith('/metadata')) throw Object.assign(new Error('404'), { response: { status: 404 } })
+        return { data: { data: [] } }
+    })
+    return { get, post: vi.fn(), put: vi.fn(), delete: vi.fn() } as unknown as ApiClient & { get: typeof get }
+}
+
+describe('DocumentEditor — crear/editar el producto del renglón por el host', () => {
+    it('crear: dispara metacore:create-record prellenado y llena el renglón con el registro leído del catálogo', async () => {
+        const created = { id: 'p9', name: 'Válvula nueva', sku: 'VAL-N', unit_price: 120, unit_of_measure: 'unit', is_active: true }
+        const api = makeApi({
+            '/data/products.Product': () => ({ data: [created] }),
+            '/metadata/modal/products.Product': () => ({ data: { fields: [{ key: 'unit_of_measure', label: 'Unidad', options: [{ value: 'unit', label: 'pza' }] }] } }),
+        })
+        const events: any[] = []
+        const onEvt = (e: Event) => events.push((e as CustomEvent).detail)
+        window.addEventListener('metacore:create-record', onEvt)
+        render(
+            <ApiProvider client={api} batch={false}>
+                <DocumentEditor model="customers.Invoice" forms={{ types: [invoice] }} type={invoice} onCancel={() => {}} currency="MXN" defaultTaxRate={0.16} />
+            </ApiProvider>,
+        )
+        await typeAndCreate(screen.getByRole('combobox', { name: 'Buscar producto' }), 'Válvula nueva')
+        window.removeEventListener('metacore:create-record', onEvt)
+        expect(events).toHaveLength(1)
+        expect(events[0]).toMatchObject({ model: 'products.Product', defaults: { name: 'Válvula nueva' } })
+        await act(async () => events[0].onCreated({ id: 'p9' }))
+        const row = await waitFor(() => {
+            const r = document.querySelector('[data-slot="editor-lines"] tr[data-line-key]') as HTMLElement | null
+            if (!r) throw new Error('sin renglón')
+            return r
+        })
+        expect((within(row).getByRole('textbox', { name: 'Descripción' }) as HTMLInputElement).value).toBe('Válvula nueva')
+        expect((within(row).getByRole('textbox', { name: 'Precio' }) as HTMLInputElement).value).toBe('120')
+        await waitFor(() => expect(row.textContent).toContain('VAL-N · pza'))
+    })
+
+    it('editar: el lápiz dispara metacore:edit-record con el id del producto del renglón', async () => {
+        const rec = { id: 'p1', name: 'Llanta', sku: 'LL', unit_price: 1500, is_active: true }
+        const api = makeApi({ '/data/products.Product': () => ({ data: [rec] }) })
+        render(
+            <ApiProvider client={api} batch={false}>
+                <DocumentEditor model="customers.Invoice" forms={{ types: [invoice] }} type={invoice} onCancel={() => {}} currency="MXN" defaultTaxRate={0.16} />
+            </ApiProvider>,
+        )
+        const input = screen.getByRole('combobox', { name: 'Buscar producto' })
+        input.focus()
+        fireEvent.change(input, { target: { value: 'Llan' } })
+        await waitFor(() => expect(screen.getAllByRole('option').length).toBeGreaterThan(0), { timeout: 2000 })
+        fireEvent.keyDown(input, { key: 'Enter' })
+        const events: any[] = []
+        const onEvt = (e: Event) => events.push((e as CustomEvent).detail)
+        window.addEventListener('metacore:edit-record', onEvt)
+        fireEvent.click(await screen.findByRole('button', { name: 'Editar producto' }))
+        window.removeEventListener('metacore:edit-record', onEvt)
+        expect(events[0]).toMatchObject({ model: 'products.Product', recordId: 'p1' })
+        rec.unit_price = 1999
+        rec.name = 'Llanta XL'
+        await act(async () => events[0].onSaved(rec))
+        await waitFor(() => expect((screen.getByRole('textbox', { name: 'Precio' }) as HTMLInputElement).value).toBe('1999'))
+        expect((screen.getByRole('textbox', { name: 'Descripción' }) as HTMLInputElement).value).toBe('Llanta XL')
+    })
+
+    it('tarjeta: si la clave con módulo no resuelve, usa la corta; etiquetas y catálogos legibles', async () => {
+        const api = makeApi({
+            '/data/customers.Customer': () => ({ data: [{ id: 'c1', name: 'ACME', tax_id: 'AAA010101AAA', email: '', fiscal_data: { uso_cfdi: 'G03' } }] }),
+            '/metadata/modal/Customer': () => ({ data: { fields: [{ key: 'tax_id', label: 'RFC' }, { key: 'fiscal_data.uso_cfdi', label: 'Uso del CFDI', options: [{ value: 'G03', label: 'Gastos en general' }] }] } }),
+        })
+        render(
+            <ApiProvider client={api} batch={false}>
+                <DocumentEditor model="customers.Invoice" forms={{ types: [invoice] }} type={invoice} onCancel={() => {}} currency="MXN" />
+            </ApiProvider>,
+        )
+        fireEvent.change(document.getElementById('customer_id')!, { target: { value: 'c1' } })
+        const card = await waitFor(() => {
+            const c = document.querySelector('[data-slot="party-card"]') as HTMLElement | null
+            if (!c || !c.textContent?.includes('RFC') || !c.textContent.includes('Gastos')) throw new Error('tarjeta sin etiquetas')
+            return c
+        })
+        expect(card.textContent).toContain('G03 · Gastos en general')
+        expect(card.textContent).not.toContain('tax_id')
+        expect(card.textContent).not.toContain('uso_cfdi')
+        // El correo vacío no aparece.
+        expect(within(card).queryByText(/email|Correo/i)).toBeNull()
+    })
+})

package/src/__tests__/option-display.test.tsx

@@ -0,0 +1,241 @@
+// @vitest-environment happy-dom
+//
+// Declarative option display (kernel `option_display`): the picker paints the
+// row the server resolved — avatar, title, subtitle, toned metrics (price,
+// stock «Agotado»), badges — and keeps the plain row when there is none.
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, render, screen, waitFor } from '@testing-library/react'
+
+vi.mock('react-i18next', () => {
+    const value = { t: (k: string, o?: Record<string, any>) => o?.defaultValue ?? k, i18n: { language: 'es' } }
+    return { useTranslation: () => value }
+})
+
+import { DynamicSelectField } from '../dynamic-select-field'
+import { ApiProvider, type ApiClient } from '../api-context'
+import { CurrencyContext } from '../org-runtime-context'
+import { invalidateOptionsCache, projectOption, optionsRequestKey } from '../use-options-resolver'
+import { optionsBatchToken } from '../query-batch'
+import {
+    OptionDisplayRow,
+    formatRelativeDate,
+    formatTrailingValue,
+    getOptionDisplay,
+    toneVariant,
+    type OptionDisplayData,
+} from '../option-display'
+import { createFormatter } from '../business/format'
+import { withOptionDisplays } from '../business/product-display'
+import { ProductHitRow } from '../business/product-options'
+import type { ActionFieldDef } from '../types'
+
+afterEach(() => {
+    cleanup()
+    invalidateOptionsCache()
+})
+
+const tire: OptionDisplayData = {
+    title: 'Llanta Michelin Primacy 4 205/55R16 91V',
+    subtitle: 'MIC-2055516 · 205/55R16',
+    image: null,
+    trailing: [
+        { key: 'price', label: 'Precio', value: 1899.5, format: 'money' },
+        { key: 'stock', label: 'Disp.', value: 8, format: 'number', tone: 'success' },
+    ],
+    badges: [],
+    tone: 'success',
+}
+const oil: OptionDisplayData = {
+    title: 'Aceite 5W30',
+    subtitle: 'ACE-530',
+    trailing: [
+        { key: 'price', label: 'Precio', value: 250, format: 'money' },
+        { key: 'stock', label: 'Disp.', value: 0, format: 'number', tone: 'danger', text: 'Agotado' },
+    ],
+    badges: [{ text: 'Servicio', tone: 'info' }],
+    tone: 'danger',
+    dimmed: true,
+}
+
+describe('formatTrailingValue', () => {
+    const fmt = createFormatter({ currency: 'MXN' })
+    it('money with the org currency (or the item own)', () => {
+        expect(formatTrailingValue({ key: 'p', value: 1899.5, format: 'money' }, fmt)).toBe('$1,899.50')
+        expect(formatTrailingValue({ key: 'p', value: 10, format: 'money', currency: 'USD' }, fmt)).toBe('$10.00')
+    })
+    it('number, integer, percent, text', () => {
+        expect(formatTrailingValue({ key: 'n', value: 1234.5, format: 'number' }, fmt)).toBe('1,234.5')
+        expect(formatTrailingValue({ key: 'n', value: '7.6', format: 'integer' }, fmt)).toBe('8')
+        expect(formatTrailingValue({ key: 'n', value: 0.16, format: 'percent' }, fmt)).toBe('16%')
+        expect(formatTrailingValue({ key: 'n', value: 16, format: 'percent' }, fmt)).toBe('16%')
+        expect(formatTrailingValue({ key: 'n', value: 'ACEPTADA', format: 'text' }, fmt)).toBe('ACEPTADA')
+        expect(formatTrailingValue({ key: 'n', value: null, format: 'money' }, fmt)).toBe('')
+    })
+    it('relative dates', () => {
+        const now = new Date('2026-10-07T12:00:00Z')
+        expect(formatRelativeDate('2026-10-04T12:00:00Z', 'es-MX', now)).toBe('hace 3 días')
+        expect(formatRelativeDate('2026-10-21T12:00:00Z', 'es-MX', now)).toBe('dentro de 2 semanas')
+    })
+    it('tone → badge variant', () => {
+        expect(toneVariant('danger')).toBe('danger')
+        expect(toneVariant('neutral')).toBe('muted')
+        expect(toneVariant(undefined)).toBe('muted')
+    })
+})
+
+describe('OptionDisplayRow', () => {
+    it('paints title, subtitle, metrics aligned with tabular numbers and the toned chip', () => {
+        render(
+            <CurrencyContext.Provider value="MXN">
+                <OptionDisplayRow display={oil} />
+            </CurrencyContext.Provider>,
+        )
+        expect(screen.getByText('Aceite 5W30')).toBeTruthy()
+        expect(screen.getByText('ACE-530')).toBeTruthy()
+        expect(screen.getByText('$250.00').className).toContain('tabular-nums')
+        const chip = screen.getByText('Agotado')
+        expect(chip.getAttribute('data-tone')).toBe('danger')
+        expect(screen.getByText('Servicio')).toBeTruthy()
+        const row = document.querySelector('[data-slot="option-display"]')!
+        expect(row.getAttribute('data-dimmed')).toBe('true')
+        expect(document.querySelectorAll('[data-slot="option-metric"]')).toHaveLength(1)
+        expect(document.querySelectorAll('[data-slot="option-metric-chip"]')).toHaveLength(1)
+        // Title clamps to two lines instead of truncating to one.
+        expect(document.querySelector('[data-slot="option-display-title"]')!.className).toContain('line-clamp-2')
+    })
+})
+
+describe('options wire: display + context', () => {
+    it('projectOption keeps display and leaves it out of meta', () => {
+        const o = projectOption({ id: 'p1', label: 'Llanta', display: tire, sku: 'X' })
+        expect(getOptionDisplay(o)).toEqual(tire)
+        expect(o.meta).toEqual({ sku: 'X' })
+        expect(getOptionDisplay(projectOption({ id: 'p2', label: 'Plain' }))).toBeNull()
+    })
+    it('context is part of the cache key and the batch token', () => {
+        const a = optionsRequestKey('s', '/options/p', 'id', '', 20, undefined, { warehouse_id: 'W1' })
+        const b = optionsRequestKey('s', '/options/p', 'id', '', 20, undefined, { warehouse_id: 'W2' })
+        expect(a).not.toBe(b)
+        expect(optionsRequestKey('s', '/options/p', 'id', '', 20, undefined)).toBe(['s', '/options/p', 'id', '', '20', ''].join('\n'))
+        expect(optionsBatchToken('products.Product', 'id', 'll', 20, undefined, { warehouse_id: 'W1' })).toBe(
+            'o:products.Product?field=id&q=ll&limit=20&ctx.warehouse_id=W1',
+        )
+    })
+})
+
+function host(rows: unknown[]) {
+    const get = vi.fn(async (_url: string, config?: { params?: Record<string, unknown> }) => {
+        const ids = config?.params?.ids
+        const data = typeof ids === 'string' ? rows.filter((r: any) => ids.split(',').includes(r.id)) : rows
+        return { data: { success: true, data, meta: { type: 'dynamic' } } }
+    })
+    const api = { get, post: vi.fn(async () => ({ data: {} })), put: vi.fn(), delete: vi.fn() } as unknown as ApiClient
+    return { api, get }
+}
+
+const product: ActionFieldDef = { key: 'product_id', label: 'Producto', type: 'dynamic_select', ref: 'products.Product' }
+
+describe('DynamicSelectField with option_display', () => {
+    it('lists rich rows, sends the picker context and summarizes the selection in the trigger', async () => {
+        const h = host([
+            { id: 'p1', value: 'p1', label: 'Llanta', display: tire },
+            { id: 'p2', value: 'p2', label: 'Aceite', display: oil },
+        ])
+        const onChange = vi.fn()
+        render(
+            <ApiProvider client={h.api}>
+                <DynamicSelectField field={product} value="" onChange={onChange} optionsContext={{ warehouse_id: 'W1', branch_id: '' }} />
+            </ApiProvider>,
+        )
+        await act(async () => {
+            ;(screen.getByRole('combobox') as HTMLButtonElement).click()
+        })
+        await screen.findByText('Llanta Michelin Primacy 4 205/55R16 91V')
+        const params = h.get.mock.calls[0][1]?.params as Record<string, unknown>
+        expect(params['ctx.warehouse_id']).toBe('W1')
+        expect('ctx.branch_id' in params).toBe(false)
+        expect(screen.getByText('Agotado')).toBeTruthy()
+        // «Agotado» is dimmed but still selectable (not blocked).
+        const options = screen.getAllByRole('option')
+        expect(options[1].getAttribute('aria-disabled')).toBeNull()
+        await act(async () => {
+            options[1].click()
+        })
+        expect(onChange).toHaveBeenCalledWith('p2')
+    })
+
+    it('a blocked option cannot be picked', async () => {
+        const h = host([{ id: 'p3', value: 'p3', label: 'Bloqueado', display: { ...oil, title: 'Bloqueado', blocked: true } }])
+        const onChange = vi.fn()
+        render(
+            <ApiProvider client={h.api}>
+                <DynamicSelectField field={product} value="" onChange={onChange} />
+            </ApiProvider>,
+        )
+        await act(async () => {
+            ;(screen.getByRole('combobox') as HTMLButtonElement).click()
+        })
+        const opt = (await screen.findByText('Bloqueado')).closest('[role="option"]') as HTMLElement
+        expect(opt.getAttribute('aria-disabled')).toBe('true')
+        await act(async () => {
+            opt.click()
+        })
+        expect(onChange).not.toHaveBeenCalled()
+    })
+
+    it('a held value shows the compact summary (title + toned metric)', async () => {
+        const h = host([{ id: 'p2', value: 'p2', label: 'Aceite', display: oil }])
+        render(
+            <ApiProvider client={h.api}>
+                <DynamicSelectField field={product} value="p2" onChange={vi.fn()} />
+            </ApiProvider>,
+        )
+        await waitFor(() => expect(document.querySelector('[data-slot="option-display-value"]')).toBeTruthy())
+        expect(screen.getByText('Aceite 5W30')).toBeTruthy()
+        expect(screen.getByText('Agotado')).toBeTruthy()
+    })
+
+    it('without display the plain row stays', async () => {
+        const h = host([{ id: 'b1', value: 'b1', label: 'Michelin' }])
+        render(
+            <ApiProvider client={h.api}>
+                <DynamicSelectField field={{ ...product, ref: 'Brand' }} value="" onChange={vi.fn()} />
+            </ApiProvider>,
+        )
+        await act(async () => {
+            ;(screen.getByRole('combobox') as HTMLButtonElement).click()
+        })
+        await screen.findByText('Michelin')
+        expect(document.querySelector('[data-slot="option-display"]')).toBeNull()
+    })
+})
+
+describe('withOptionDisplays (product line search)', () => {
+    const search = vi.fn(async () => [
+        { id: 'P1', name: 'Llanta', price: 1899.5 },
+        { id: 'p2', name: 'Aceite', price: 250 },
+    ])
+    it('one ids lookup with the context, displays merged by id (case-insensitive)', async () => {
+        const h = host([{ id: 'p1', display: tire }, { id: 'p2', display: oil }])
+        const wrapped = withOptionDisplays(search, h.api as any, { model: 'products.Product', context: { warehouse_id: 'W1', branch_id: null } })
+        const out = await wrapped({ kind: 'text', raw: 'a', text: 'a' } as any, new AbortController().signal)
+        expect(h.get).toHaveBeenCalledTimes(1)
+        expect(h.get.mock.calls[0][0]).toBe('/options/products.Product')
+        expect(h.get.mock.calls[0][1]?.params).toEqual({ field: 'id', ids: 'P1,p2', 'ctx.warehouse_id': 'W1' })
+        expect(out[1].display).toEqual(oil)
+        expect(out[0].price).toBe(1899.5)
+    })
+    it('a failing lookup returns the results untouched', async () => {
+        const api = { get: vi.fn(async () => Promise.reject(new Error('501'))) }
+        const out = await withOptionDisplays(search, api as any, { model: 'products.Product' })({} as any, new AbortController().signal)
+        expect(out.map((r) => r.display)).toEqual([undefined, undefined])
+    })
+    it('ProductHitRow paints the display when the product carries one', () => {
+        render(<ProductHitRow hit={{ product: { id: 'p2', name: 'Aceite', display: oil } }} currency="MXN" />)
+        expect(screen.getByText('Agotado')).toBeTruthy()
+        cleanup()
+        render(<ProductHitRow hit={{ product: { id: 'p2', name: 'Aceite plano', sku: 'ACE' } }} currency="MXN" />)
+        expect(screen.getByText('Aceite plano')).toBeTruthy()
+        expect(document.querySelector('[data-slot="option-display"]')).toBeNull()
+    })
+})

package/src/business/document-editor-model.ts

@@ -178,12 +178,68 @@ export function partyDefaults(
     return out
 }
 
-/** Filas de la tarjeta de contraparte: resumen declarado + extensiones (máximo `limit`). */
+/** Etiqueta y opciones de catálogo de un campo (de la metadata del modelo o del propio tipo). */
+export interface FieldDisplayMeta {
+    label?: string
+    options?: ReadonlyArray<{ value: unknown; label?: unknown }>
+}
+
+/**
+ * Metadata de pantalla por clave a partir de listas de campos/columnas
+ * (`/metadata/modal` → fields, `/metadata/table` → columns, campos del tipo).
+ * La primera lista que trae etiqueta u opciones para una clave gana.
+ */
+export function fieldDisplayMeta(
+    lists: ReadonlyArray<ReadonlyArray<unknown> | null | undefined>,
+    translate: (s: string) => string = (s) => s,
+): Record<string, FieldDisplayMeta> {
+    const out: Record<string, FieldDisplayMeta> = {}
+    for (const list of lists) {
+        for (const raw of list ?? []) {
+            const f = raw as { key?: unknown; name?: unknown; label?: unknown; options?: unknown }
+            const key = typeof f?.key === 'string' ? f.key : typeof f?.name === 'string' ? f.name : undefined
+            if (!key) continue
+            const cur = (out[key] ??= {})
+            if (!cur.label && typeof f.label === 'string' && f.label) cur.label = translate(f.label)
+            if (!cur.options && Array.isArray(f.options) && f.options.length > 0) {
+                cur.options = f.options.map((o: any) => ({ value: o?.value, label: typeof o?.label === 'string' ? translate(o.label) : o?.label }))
+            }
+        }
+    }
+    return out
+}
+
+/** `tax_id` → «Tax id»: último recurso cuando ningún metadata etiqueta la columna. */
+export function humanizeKey(key: string): string {
+    const base = key.replace(EXTENSION_PREFIX, '').replace(/[_.]+/g, ' ').trim()
+    return base ? base.charAt(0).toUpperCase() + base.slice(1) : key
+}
+
+/**
+ * Valor de catálogo legible: `G03` con la opción «Gastos en general» →
+ * «G03 · Gastos en general» (si la etiqueta ya trae el código, tal cual).
+ */
+export function formatOptionValue(value: unknown, options?: FieldDisplayMeta['options']): string {
+    const raw = String(value)
+    const opt = options?.find((o) => String(o.value) === raw)
+    const label = opt && typeof opt.label === 'string' ? opt.label.trim() : ''
+    if (!label || label === raw) return raw
+    if (label.includes(raw)) return label
+    const codeLike = /^[A-Z0-9]{1,5}$/.test(raw) && /\d/.test(raw)
+    return codeLike ? `${raw} · ${label}` : label
+}
+
+/**
+ * Filas de la tarjeta de contraparte: resumen declarado + extensiones (máximo
+ * `limit`). Etiqueta del campo (metadata / labels declarados, ya traducidos),
+ * valores de catálogo con su texto y nunca claves crudas ni vacíos.
+ */
 export function partySummaryRows(
     party: Record<string, any> | null,
     summary: readonly string[] = [],
     labels: Record<string, string> = {},
     limit = 6,
+    meta: Record<string, FieldDisplayMeta> = {},
 ): Array<{ key: string; label: string; value: string }> {
     if (!party) return []
     const keys = new Set<string>(summary)
@@ -193,7 +249,9 @@ export function partySummaryRows(
     for (const key of keys) {
         const v = readPath(party, key)
         if (!hasValue(v) || typeof v === 'object') continue
-        rows.push({ key, label: labels[key] ?? key.replace(EXTENSION_PREFIX, ''), value: String(v) })
+        if (typeof v === 'string' && !v.trim()) continue
+        const m = meta[key]
+        rows.push({ key, label: labels[key] ?? m?.label ?? humanizeKey(key), value: formatOptionValue(v, m?.options) })
     }
     return rows.slice(0, limit)
 }