@asteby/metacore-runtime-react 47.1.0 → 49.0.0

package/src/__tests__/catalog-product-search.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it, vi } from 'vitest'
+import { catalogRecordToProduct, createCatalogProductSearch } from '../business/catalog-product-search'
+import { applyProductToLine } from '../business/document-lines'
+import { makeLine, parseLineItems, serializeLineItems } from '../business/line-items'
+
+describe('catalogRecordToProduct', () => {
+    it('proyecta precio de venta, costo, unidad, SKU y claves de extensión', () => {
+        const p = catalogRecordToProduct(
+            { id: 'p1', name: 'Balanceo', sku: 'SRV-1', unit_price: '350.50', cost_price: 100, unit_of_measure: 'servicio', product_type: 'service', fiscal_data: '{"mx_clave_prod_serv":"78181500","vacio":""}' },
+            0.16,
+        )
+        expect(p).toEqual({
+            id: 'p1',
+            name: 'Balanceo',
+            sku: 'SRV-1',
+            barcode: undefined,
+            kind: 'service',
+            price: 350.5,
+            cost: 100,
+            tax_rate: 0.16,
+            unit: 'servicio',
+            extensions: { mx_clave_prod_serv: '78181500' },
+        })
+    })
+
+    it('la tasa del producto gana sobre la de la org (acepta 16 o 0.16)', () => {
+        expect(catalogRecordToProduct({ id: 'a', name: 'A', tax_rate: 8 }, 0.16).tax_rate).toBe(0.08)
+        expect(catalogRecordToProduct({ id: 'a', name: 'A', tax_rate: '0' }, 0.16).tax_rate).toBe(0)
+        expect(catalogRecordToProduct({ id: 'a', name: 'A' }).tax_rate).toBeUndefined()
+    })
+})
+
+describe('createCatalogProductSearch', () => {
+    it('consulta /data/<model> con search y omite productos inactivos', async () => {
+        const get = vi.fn().mockResolvedValue({ data: { success: true, data: [{ id: '1', name: 'A', unit_price: 10 }, { id: '2', name: 'B', is_active: false }] } })
+        const search = createCatalogProductSearch({ get }, { model: 'inventory.Item', limit: 5 })
+        const signal = new AbortController().signal
+        const res = await search({ kind: 'text', raw: ' a ', text: 'a' }, signal)
+        expect(get).toHaveBeenCalledWith('/data/inventory.Item', { params: { search: 'a', per_page: 5 }, signal })
+        expect(res.map((r) => r.id)).toEqual(['1'])
+    })
+})
+
+describe('cantidad del renglón de producto', () => {
+    it('elegir un producto sobre un renglón con cantidad 0 o vacía deja cantidad 1', () => {
+        const product = { id: 'p', name: 'P', price: 100 }
+        expect(applyProductToLine(makeLine({ quantity: 0 }), product).quantity).toBe(1)
+        expect(applyProductToLine(makeLine({ quantity: '' as unknown as number }), product).quantity).toBe(1)
+        expect(applyProductToLine(makeLine({ quantity: 3 }), product).quantity).toBe(3)
+    })
+
+    it('parseLineItems trata cantidad vacía como 1', () => {
+        expect(parseLineItems([{ description: 'x', quantity: '' }])[0].quantity).toBe(1)
+    })
+
+    it('las extensiones viajan como fiscal_data y regresan al parsear', () => {
+        const [row] = serializeLineItems([makeLine({ description: 'x', extensions: { mx_clave_unidad: 'H87' } })])
+        expect(row.fiscal_data).toEqual({ mx_clave_unidad: 'H87' })
+        expect(parseLineItems([row])[0].extensions).toEqual({ mx_clave_unidad: 'H87' })
+    })
+})

package/src/__tests__/document-editor-model.test.ts

@@ -0,0 +1,221 @@
+import { describe, expect, it } from 'vitest'
+import {
+    allocationAmountField,
+    allocationIssueMessages,
+    allocationPayload,
+    creditStatus,
+    editorLinesConfig,
+    friendlyOptionLabel,
+    isEditorLayout,
+    linesFromSource,
+    localIssues,
+    sourceLoadSummary,
+    sourceTracksRemaining,
+    overdueDays,
+    partyDefaults,
+    partySummaryRows,
+    splitEditorFields,
+    toOpenDocuments,
+} from '../business/document-editor-model'
+import { makeLine, serializeLineItems } from '../business/line-items'
+import { allocatePayment, validateAllocation } from '../primitives/allocation'
+import type { ActionFieldDef, DocumentFormOpenDocuments } from '../types'
+
+describe('divulgación progresiva (splitEditorFields)', () => {
+    const fields: ActionFieldDef[] = [
+        { key: 'customer_id', label: 'Cliente', type: 'dynamic_select', required: true },
+        { key: 'payment_form', label: 'Forma de pago', type: 'select', required: true, options: [{ value: '03', label: '03 · Transferencia' }] },
+        { key: 'method', label: 'Método', type: 'select', defaultValue: 'PUE', options: [{ value: 'PUE', label: 'PUE · Una exhibición' }] },
+        { key: 'series', label: 'Serie', type: 'text', section: 'fiscal' },
+        { key: 'notes', label: 'Notas', type: 'textarea' },
+    ]
+    const ext: ActionFieldDef[] = [{ key: 'fiscal_data.uso_cfdi', label: 'Uso CFDI', type: 'select' }]
+
+    it('a la vista: contraparte y lo obligatorio; plegado: extensiones, section fiscal y catálogos con default', () => {
+        const g = splitEditorFields(fields, { partyField: 'customer_id', extensionFields: ext })
+        expect(g.party?.key).toBe('customer_id')
+        expect(g.essential.map((f) => f.key)).toEqual(['payment_form'])
+        expect(g.advanced.map((f) => f.key)).toEqual(['method', 'series', 'fiscal_data.uso_cfdi'])
+        expect(g.notes.map((f) => f.key)).toEqual(['notes'])
+    })
+
+    it('essentialKeys gana (monto del cobro, campo de vínculo del origen)', () => {
+        const g = splitEditorFields(fields, { essentialKeys: ['method'] })
+        expect(g.essential.map((f) => f.key)).toContain('method')
+    })
+
+    it('el código SAT queda como dato secundario', () => {
+        expect(friendlyOptionLabel('03 · Transferencia electrónica')).toBe('Transferencia electrónica · 03')
+        expect(friendlyOptionLabel('G03 · Gastos en general')).toBe('Gastos en general · G03')
+        expect(friendlyOptionLabel('PUE · Pago en una sola exhibición')).toBe('PUE · Pago en una sola exhibición')
+        expect(friendlyOptionLabel('Efectivo')).toBe('Efectivo')
+    })
+})
+
+describe('layout y renglones', () => {
+    it('isEditorLayout solo con layout: editor', () => {
+        expect(isEditorLayout({ layout: 'editor' })).toBe(true)
+        expect(isEditorLayout({ layout: 'wizard' })).toBe(false)
+        expect(isEditorLayout({})).toBe(false)
+        // Un tipo con «Cargar desde…» usa el editor salvo wizard explícito.
+        const src = [{ key: 'sale', label: 'Venta', model: 'customers.SalesOrder', lines: 'items' }]
+        expect(isEditorLayout({ sources: src })).toBe(true)
+        expect(isEditorLayout({ layout: 'wizard', sources: src })).toBe(false)
+    })
+    it('allocation usa `allocations` por defecto; el manifest manda', () => {
+        const base = { key: 'p', label: 'P', fields: [] }
+        expect(editorLinesConfig({ ...base, lines: { kind: 'allocation' } }, {})?.field).toBe('allocations')
+        expect(editorLinesConfig({ ...base, lines: true }, { lines_field: 'items' })?.field).toBe('items')
+        expect(editorLinesConfig(base, {})).toBeUndefined()
+    })
+})
+
+describe('contraparte', () => {
+    const customer = { name: 'Llantas SA', currency_code: 'MXN', tax_id: 'XAXX010101000', fiscal_data: { uso_cfdi: 'G03', regimen: '601' } }
+    it('copia extensiones con la misma clave y no pisa lo capturado', () => {
+        const keys = ['customer_id', 'fiscal_data.uso_cfdi', 'fiscal_data.metodo_pago']
+        expect(partyDefaults(customer, keys, {})).toEqual({ 'fiscal_data.uso_cfdi': 'G03', currency_code: 'MXN' })
+        expect(partyDefaults(customer, keys, { 'fiscal_data.uso_cfdi': 'S01', currency_code: 'USD' })).toEqual({})
+    })
+    it('tarjeta: resumen + extensiones con etiqueta legible', () => {
+        const rows = partySummaryRows(customer, ['tax_id'], { 'fiscal_data.uso_cfdi': 'Uso CFDI' })
+        expect(rows.map((r) => r.key)).toEqual(['tax_id', 'fiscal_data.uso_cfdi', 'fiscal_data.regimen'])
+        expect(rows[1].label).toBe('Uso CFDI')
+    })
+    const cols = { limit: 'credit_limit', balance: 'balance_due', overdue: 'overdue_amount', hold_reason: 'credit_hold_reason' }
+    it('crédito: bloquea si el total supera lo disponible, avisa con vencido, null sin columnas', () => {
+        expect(creditStatus({ credit_limit: 10000, balance_due: 9000 }, cols, 2000)?.level).toBe('block')
+        expect(creditStatus({ credit_limit: 10000, balance_due: 100, overdue_amount: 50 }, cols, 100)?.level).toBe('warn')
+        expect(creditStatus({ name: 'x' }, cols, 1)).toBeNull()
+    })
+})
+
+describe('linesFromSource', () => {
+    it('SalesOrderItem: product_name → description y tasa derivada de tax/subtotal', () => {
+        const [l] = linesFromSource([{ product_id: 'p1', product_name: 'Llanta 205/55R16', quantity: 4, unit_price: 1500, subtotal: 6000, tax_amount: 960 }])
+        expect(l).toMatchObject({ description: 'Llanta 205/55R16', tax_rate: 0.16, quantity: 4, product_id: 'p1' })
+    })
+    it('map traduce nombres (discount_pct) y la tasa 16 se normaliza a 0.16', () => {
+        const [l] = linesFromSource([{ description: 'Balanceo', quantity: 1, unit_price: 100, discount_pct: 10, tax_rate: 16 }], { discount: 'discount_pct' })
+        expect(l.discount).toBe(10)
+        expect(l.tax_rate).toBe(0.16)
+    })
+    it('NC (credit): la cantidad queda topada en lo facturado', () => {
+        const [l] = linesFromSource([{ description: 'Llanta', quantity: 4, unit_price: 1500, tax_rate: 0.16 }], {}, { kind: 'credit' })
+        expect(l.max_quantity).toBe(4)
+    })
+})
+
+describe('localIssues', () => {
+    it('sin renglones es error; precio en cero es aviso; sin ruido por renglón libre', () => {
+        expect(localIssues([]).some((i) => i.severity === 'error')).toBe(true)
+        const w = localIssues([makeLine({ description: 'Servicio' })])
+        expect(w).toEqual([expect.objectContaining({ severity: 'warning', message: 'Renglón 1: precio en cero.' })])
+        expect(localIssues([], { requireLines: false })).toEqual([])
+    })
+})
+
+describe('cobro / REP (allocation)', () => {
+    const cfg: DocumentFormOpenDocuments = {
+        model: 'customers.Invoice',
+        party_field: 'customer_id',
+        balance_field: 'amount_due',
+        number_field: 'number',
+        total_field: 'total',
+        due_field: 'due_date',
+        issued_field: 'issue_date',
+        method_field: 'fiscal_data.metodo_pago',
+        line_document_field: 'invoice_id',
+        line_amount_field: 'amount',
+        option_filter: [{ field: 'status', not_in: ['cancelled'] }],
+    }
+    const rows = [
+        { id: 'a', number: 'A-2', total: 1000, amount_due: 1000, issue_date: '2026-09-01', due_date: '2026-10-01', status: 'open', fiscal_data: { metodo_pago: 'PPD' } },
+        { id: 'b', number: 'A-1', total: 500, amount_due: 300, issue_date: '2026-08-01', due_date: '2026-09-01', status: 'open' },
+        { id: 'c', number: 'A-0', total: 800, amount_due: 0, issue_date: '2026-07-01', status: 'paid' },
+        { id: 'd', number: 'A-9', total: 900, amount_due: 900, issue_date: '2026-07-01', status: 'cancelled' },
+    ]
+
+    it('toOpenDocuments: solo con saldo y que pasan el option_filter', () => {
+        const docs = toOpenDocuments(rows, cfg, 'MXN')
+        expect(docs.map((d) => d.id)).toEqual(['a', 'b'])
+        expect(docs[0]).toMatchObject({ number: 'A-2', balance: 1000, total: 1000, due_at: '2026-10-01', payment_method: 'PPD', currency: 'MXN' })
+    })
+
+    it('reparte del más vencido y arma el payload con los campos de la acción', () => {
+        const docs = toOpenDocuments(rows, cfg, 'MXN')
+        const r = allocatePayment(800, docs)
+        expect(r.allocations.map((a) => [a.document_id, a.amount])).toEqual([['b', 300], ['a', 500]])
+        expect(allocationPayload(r.allocations, cfg)).toEqual([
+            { invoice_id: 'b', amount: 300 },
+            { invoice_id: 'a', amount: 500 },
+        ])
+    })
+
+    it('mensajes claros con el número del documento', () => {
+        const docs = toOpenDocuments(rows, cfg, 'MXN')
+        const issues = validateAllocation(100, 'MXN', docs, [{ document_id: 'b', amount: 400, balance_before: 300, balance_after: 0, installment: 1 }])
+        const msgs = allocationIssueMessages(issues, docs).map((m) => m.message)
+        expect(msgs).toContain('A-1: Se aplica más que el saldo del documento.')
+        expect(msgs).toContain('Lo aplicado supera el monto recibido.')
+    })
+
+    it('campo del monto: `amount` o el primer numérico', () => {
+        expect(allocationAmountField([{ key: 'x', label: '', type: 'text' }, { key: 'amount', label: '', type: 'number' }])).toBe('amount')
+        expect(allocationAmountField([{ key: 'total_paid', label: '', type: 'number' }])).toBe('total_paid')
+    })
+
+    it('días de atraso', () => {
+        expect(overdueDays({ due_at: '2026-10-01' }, new Date(2026, 9, 6))).toBe(5)
+        expect(overdueDays({ due_at: '2026-10-30' }, new Date(2026, 9, 6))).toBe(0)
+        expect(overdueDays({ due_at: null })).toBe(0)
+    })
+})
+
+describe('linesFromSource con lo pendiente («crear desde»)', () => {
+    it('la cantidad sugerida y el tope son remaining_quantity; lo ya cubierto se omite; guarda el renglón origen', () => {
+        const rows = [
+            { id: 'a', source_line_id: 'a', product_id: 'p1', product_name: 'Llanta', quantity: 4, remaining_quantity: 1, unit_price: 1500, discount: 5, tax_rate: 0.16 },
+            { id: 'b', source_line_id: 'b', product_name: 'Balanceo', quantity: 2, remaining_quantity: 0, unit_price: 100 },
+        ]
+        const lines = linesFromSource(rows, { description: 'product_name' })
+        expect(lines).toHaveLength(1)
+        expect(lines[0]).toMatchObject({ product_id: 'p1', description: 'Llanta', quantity: 1, max_quantity: 1, unit_price: 1500, discount: 5, tax_rate: 0.16, source_line_id: 'a' })
+        expect(sourceLoadSummary(rows)).toEqual({ loaded: 1, covered: 1 })
+    })
+    it('sin remaining_quantity conserva la cantidad del origen y usa su id como vínculo', () => {
+        const [l] = linesFromSource([{ id: 'x', description: 'Servicio', quantity: 3, unit_price: 10 }])
+        expect(l.quantity).toBe(3)
+        expect(l.max_quantity).toBeUndefined()
+        expect(l.source_line_id).toBe('x')
+    })
+    it('localIssues marca la cantidad que excede lo pendiente', () => {
+        const l = { ...makeLine({ description: 'Llanta', quantity: 3, unit_price: 10 }), max_quantity: 2 }
+        expect(localIssues([l]).some((i) => i.severity === 'error' && i.message.includes('excede lo pendiente'))).toBe(true)
+    })
+    it('sourceTracksRemaining: solo con line_link_field, remaining_qty_field o remaining_endpoint', () => {
+        expect(sourceTracksRemaining({ line_link_field: 'sales_order_item_id' })).toBe(true)
+        expect(sourceTracksRemaining({ remaining_endpoint: '/x' })).toBe(true)
+        expect(sourceTracksRemaining({})).toBe(false)
+    })
+})
+
+
+describe('serializeLineItems con vínculo al renglón origen', () => {
+    it('escribe source_line_id en la columna line_link_field y no en renglones libres', () => {
+        const linked = { ...makeLine({ description: 'Llanta', quantity: 1, unit_price: 10 }), source_line_id: 'soi-1' }
+        const free = makeLine({ description: 'Flete', quantity: 1, unit_price: 50 })
+        const [a, b] = serializeLineItems([linked, free], { sourceLineField: 'sales_order_item_id' })
+        expect(a.sales_order_item_id).toBe('soi-1')
+        expect(b.sales_order_item_id).toBeUndefined()
+        expect(serializeLineItems([linked])[0].sales_order_item_id).toBeUndefined()
+    })
+    it('lleva subtotal e impuesto calculados (modelos de renglón sin tasa)', () => {
+        const l = { ...makeLine({ description: 'Llanta', quantity: 2, unit_price: 100, discount: 20, tax_rate: 0.16 }), discount_kind: 'amount' as const }
+        expect(serializeLineItems([l])[0]).toMatchObject({ subtotal: 180, tax_amount: 28.8, discount: 20, discount_kind: 'amount' })
+    })
+    it('linesFromSource con discount_mode amount conserva el descuento como importe', () => {
+        const [l] = linesFromSource([{ id: 'a', quantity: 2, unit_price: 100, discount: 20, remaining_quantity: 2 }], {}, { discountMode: 'amount' })
+        expect(l.discount_kind).toBe('amount')
+    })
+})

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

@@ -0,0 +1,340 @@
+// @vitest-environment happy-dom
+// DocumentEditor (layout: "editor"): una pantalla por secciones, «Opciones
+// fiscales» plegadas, una sola acción primaria, prefill desde el origen y
+// reparto de cobros con PaymentAllocator.
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
+
+vi.mock('@tanstack/react-router', () => ({ useNavigate: () => () => {} }))
+vi.mock('react-i18next', () => {
+    const i18n = { language: 'es' }
+    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 }
+    return { useTranslation: () => value }
+})
+
+import { DocumentEditor } from '../business/document-editor'
+import { DocumentFormDialog } from '../document-form-dialog'
+import { ApiProvider, type ApiClient } from '../api-context'
+import { __resetContributions, registerDocumentContribution } from '../primitives/contributions'
+import type { DocumentFormsManifest, DocumentFormType } from '../types'
+
+afterEach(() => {
+    cleanup()
+    __resetContributions()
+})
+
+type Routes = Record<string, unknown>
+
+function makeApi(routes: Routes = {}, post = vi.fn().mockResolvedValue({ data: { success: true, data: { id: 'new-1' } } })) {
+    const get = vi.fn(async (url: string, cfg?: { params?: Record<string, unknown> }) => {
+        for (const [prefix, body] of Object.entries(routes)) {
+            if (url.startsWith(prefix)) return { data: typeof body === 'function' ? (body as any)(url, cfg) : body }
+        }
+        return { data: { data: [] } }
+    })
+    const client = { get, post, put: vi.fn().mockResolvedValue({ data: { success: true, data: { id: 'new-1' } } }), delete: vi.fn() }
+    return { client: client as unknown as ApiClient, get, post }
+}
+
+const invoice: DocumentFormType = {
+    key: 'invoice',
+    label: 'Factura',
+    value: 'I',
+    layout: 'editor',
+    fields: [
+        { key: 'customer_name', label: 'Cliente', type: 'text', required: true },
+        { key: 'payment_form', label: 'Forma de pago', type: 'select', required: true, defaultValue: '03', options: [{ value: '03', label: '03 · Transferencia' }, { value: '01', label: '01 · Efectivo' }] },
+        { key: 'payment_method', label: 'Método de pago', type: 'select', defaultValue: 'PUE', options: [{ value: 'PUE', label: 'PUE · Una exhibición' }, { value: 'PPD', label: 'PPD · Parcialidades' }] },
+        { key: 'sales_order_id', label: 'Venta', type: 'text' },
+    ],
+    lines: { columns: ['tax'] },
+    sources: [{ key: 'sales_order', label: 'Venta', model: 'customers.SalesOrder', lines: 'items', map: { description: 'product_name' }, link_field: 'sales_order_id' }],
+    preview: { action: 'preview_cfdi', label: 'Vista previa CFDI' },
+    submit_label: 'Guardar factura',
+}
+const forms: DocumentFormsManifest = { type_field: 'type', types: [invoice] }
+
+function renderEditor(type: DocumentFormType, api: ReturnType<typeof makeApi>, extra: Partial<Parameters<typeof DocumentEditor>[0]> = {}) {
+    const onSaved = vi.fn()
+    render(
+        <ApiProvider client={api.client}>
+            <DocumentEditor model="customers.Invoice" forms={{ ...forms, types: [type] }} type={type} onCancel={() => {}} onSaved={onSaved} currency="MXN" {...extra} />
+        </ApiProvider>,
+    )
+    return { onSaved }
+}
+
+describe('DocumentEditor — divulgación progresiva', () => {
+    it('«Opciones fiscales» arranca plegada: lo esencial a la vista, el método con default adentro', () => {
+        renderEditor(invoice, makeApi())
+        const toggle = screen.getByRole('button', { name: /Opciones fiscales/ })
+        expect(toggle.getAttribute('aria-expanded')).toBe('false')
+        const panel = document.getElementById(toggle.getAttribute('aria-controls')!)!
+        expect(panel.hidden).toBe(true)
+        expect(within(panel).getByText('Método de pago')).toBeTruthy()
+        // Esencial: fuera de la sección plegada.
+        const essentials = document.querySelector('[data-slot="editor-essentials"]')!
+        expect(within(essentials as HTMLElement).getByText('Cliente')).toBeTruthy()
+        expect(within(essentials as HTMLElement).getByText('Forma de pago')).toBeTruthy()
+        expect(within(essentials as HTMLElement).queryByText('Método de pago')).toBeNull()
+        // Resumen de los defaults sin abrir.
+        expect(toggle.textContent).toContain('PUE')
+        fireEvent.click(toggle)
+        expect(toggle.getAttribute('aria-expanded')).toBe('true')
+        expect(panel.hidden).toBe(false)
+    })
+
+    it('la vista previa es opcional y está cerrada por defecto', () => {
+        renderEditor(invoice, makeApi())
+        expect(screen.getByRole('button', { name: /Vista previa CFDI/ }).getAttribute('aria-expanded')).toBe('false')
+    })
+
+    it('las etiquetas muestran el código SAT como dato secundario', () => {
+        renderEditor(invoice, makeApi())
+        expect(screen.getAllByText('Transferencia · 03').length).toBeGreaterThan(0)
+    })
+
+    it('una contribución header.fields de otro addon entra en «Opciones fiscales»', () => {
+        registerDocumentContribution({
+            id: 'fiscal_mexico.header.cfdi',
+            kinds: ['invoice'],
+            region: 'header.fields',
+            requiresAddon: 'fiscal_mexico',
+            component: () => <p>Relación CFDI</p>,
+        })
+        renderEditor(invoice, makeApi())
+        const panel = document.querySelector('[data-slot="advanced-options"]')!
+        expect(within(panel as HTMLElement).getByText('Relación CFDI')).toBeTruthy()
+    })
+})
+
+describe('DocumentEditor — una sola acción primaria', () => {
+    it('un solo botón primario (submit_label) y sin «Siguiente»', () => {
+        renderEditor(invoice, makeApi())
+        const primaries = document.querySelectorAll('[data-slot="document-editor"] [data-primary="true"]')
+        expect(primaries.length).toBe(1)
+        expect(primaries[0].textContent).toBe('Guardar factura')
+        expect(screen.queryByRole('button', { name: 'Siguiente' })).toBeNull()
+    })
+
+    it('sin renglones no guarda: validación inline y revisión visible', async () => {
+        const api = makeApi()
+        renderEditor(invoice, api)
+        fireEvent.click(screen.getByRole('button', { name: 'Guardar factura' }))
+        await screen.findByText('Agrega al menos un renglón.')
+        expect(screen.getAllByText(/Cliente/).length).toBeGreaterThan(1) // etiqueta + error inline
+        expect(api.post).not.toHaveBeenCalled()
+    })
+})
+
+describe('DocumentEditor — prefill desde el documento origen', () => {
+    it('initialSource carga los renglones y el vínculo; guarda con el tipo y los renglones serializados', async () => {
+        const api = makeApi({
+            '/metadata/table/customers.SalesOrder': { data: { relations: [{ name: 'items', kind: 'one_to_many', through: 'customers.SalesOrderItem', foreign_key: 'sales_order_id' }] } },
+            '/data/customers.SalesOrderItem': { data: [{ product_id: 'p1', product_name: 'Llanta 205/55R16', quantity: 4, unit_price: 1500, tax_rate: 0.16 }] },
+            '/data/customers.SalesOrder': { data: [{ id: 'so-1', customer_name: 'ACME' }] },
+        })
+        const { onSaved } = renderEditor(
+            { ...invoice, sources: [{ ...invoice.sources![0], header: { customer_name: 'customer_name' } }] },
+            api,
+            { initialSource: { key: 'sales_order', id: 'so-1' } },
+        )
+        await screen.findByDisplayValue('Llanta 205/55R16')
+        await screen.findByDisplayValue('ACME')
+        expect(api.get).toHaveBeenCalledWith('/data/customers.SalesOrderItem', expect.objectContaining({ params: expect.objectContaining({ f_sales_order_id: 'eq:so-1' }) }))
+        fireEvent.click(screen.getByRole('button', { name: 'Guardar factura' }))
+        await waitFor(() => expect(api.post).toHaveBeenCalled())
+        const [url, body] = api.post.mock.calls[0] as [string, any]
+        expect(url).toBe('/dynamic/customers.Invoice')
+        expect(body).toMatchObject({ type: 'I', customer_name: 'ACME', sales_order_id: 'so-1', payment_method: 'PUE', payment_form: '03' })
+        expect(body.lines).toEqual([expect.objectContaining({ product_id: 'p1', description: 'Llanta 205/55R16', quantity: 4, unit_price: 1500 })])
+        await waitFor(() => expect(onSaved).toHaveBeenCalledWith(expect.objectContaining({ id: 'new-1' })))
+    })
+
+    it('default_from_record siembra el encabezado desde el registro de la acción', () => {
+        const type: DocumentFormType = {
+            ...invoice,
+            fields: [{ key: 'customer_name', label: 'Cliente', type: 'text', default_from_record: 'name' } as any],
+        }
+        renderEditor(type, makeApi(), { record: { id: 'c1', name: 'Taller Pérez' } })
+        expect(screen.getByDisplayValue('Taller Pérez')).toBeTruthy()
+    })
+})
+
+describe('DocumentEditor — cobro / REP (lines.kind: allocation)', () => {
+    const payment: DocumentFormType = {
+        key: 'payment',
+        label: 'Registrar cobro',
+        layout: 'editor',
+        submit_action: 'collect_multi_payment_create',
+        submit_label: 'Registrar cobro',
+        party: { field: 'customer_id', model: 'customers.Customer' },
+        fields: [
+            { key: 'customer_id', label: 'Cliente', type: 'text', required: true, default_from_record: 'customer_id' } as any,
+            { key: 'amount', label: 'Monto recibido', type: 'number', required: true },
+        ],
+        lines: {
+            kind: 'allocation',
+            open_documents: {
+                model: 'customers.Invoice',
+                party_field: 'customer_id',
+                balance_field: 'amount_due',
+                number_field: 'number',
+                due_field: 'due_date',
+                issued_field: 'issue_date',
+                line_document_field: 'invoice_id',
+                line_amount_field: 'amount',
+            },
+        },
+    }
+    const routes = {
+        '/data/customers.Customer': { data: [{ id: 'c1', name: 'Llantas SA' }] },
+        '/data/customers.Invoice': {
+            data: [
+                { id: 'inv-new', number: 'A-2', amount_due: 1000, issue_date: '2026-09-01', due_date: '2026-10-30' },
+                { id: 'inv-old', number: 'A-1', amount_due: 300, issue_date: '2026-08-01', due_date: '2026-09-01' },
+            ],
+        },
+    }
+
+    it('lista las facturas abiertas, reparte del más vencido y guarda por la acción con allocations', async () => {
+        const api = makeApi(routes)
+        renderEditor(payment, api, { record: { customer_id: 'c1' }, today: new Date(2026, 9, 6) })
+        await screen.findByText('A-1')
+        expect(api.get).toHaveBeenCalledWith('/data/customers.Invoice', expect.objectContaining({ params: expect.objectContaining({ f_customer_id: 'eq:c1' }) }))
+        expect(await screen.findByText('Llantas SA')).toBeTruthy()
+        fireEvent.change(document.querySelector('[data-slot="editor-essentials"] input[type=number]')!, { target: { value: '500' } })
+        await waitFor(() => expect((screen.getByLabelText('Aplicar a A-1') as HTMLInputElement).value).toBe('300'))
+        expect((screen.getByLabelText('Aplicar a A-2') as HTMLInputElement).value).toBe('200')
+        expect(screen.getByText(/Parcialidad 1/)).toBeTruthy()
+        fireEvent.click(screen.getByRole('button', { name: 'Registrar cobro' }))
+        await waitFor(() => expect(api.post).toHaveBeenCalled())
+        const [url, body] = api.post.mock.calls[0] as [string, any]
+        expect(url).toBe('/dynamic/customers.Invoice/action/collect_multi_payment_create')
+        expect(body).toMatchObject({ customer_id: 'c1', amount: 500 })
+        expect(body.allocations).toEqual([
+            { invoice_id: 'inv-old', amount: 300 },
+            { invoice_id: 'inv-new', amount: 200 },
+        ])
+        expect(body.type).toBeUndefined()
+    })
+
+    it('editar un monto pasa a reparto manual; «Autoaplicar» regresa al automático', async () => {
+        const api = makeApi(routes)
+        renderEditor(payment, api, { record: { customer_id: 'c1' } })
+        await screen.findByText('A-1')
+        fireEvent.click(screen.getByRole('button', { name: /Cobrar todo/ }))
+        await waitFor(() => expect((screen.getByLabelText('Aplicar a A-2') as HTMLInputElement).value).toBe('1000'))
+        fireEvent.change(screen.getByLabelText('Aplicar a A-2'), { target: { value: '400' } })
+        expect(screen.getByText('Reparto manual')).toBeTruthy()
+        expect((screen.getByLabelText('Aplicar a A-2') as HTMLInputElement).value).toBe('400')
+        expect(screen.getByText('Sin aplicar (saldo a favor)')).toBeTruthy()
+        fireEvent.click(screen.getByRole('button', { name: 'Autoaplicar' }))
+        expect((screen.getByLabelText('Aplicar a A-2') as HTMLInputElement).value).toBe('1000')
+    })
+})
+
+describe('DocumentFormDialog + layout: editor', () => {
+    it('con layout editor abre el DocumentEditor; sin él sigue el wizard', () => {
+        const api = makeApi()
+        const { unmount } = render(
+            <ApiProvider client={api.client}>
+                <DocumentFormDialog open onOpenChange={() => {}} model="customers.Invoice" forms={forms} />
+            </ApiProvider>,
+        )
+        expect(document.querySelector('[data-slot="document-editor"]')).toBeTruthy()
+        expect(screen.queryByRole('button', { name: 'Siguiente' })).toBeNull()
+        unmount()
+        render(
+            <ApiProvider client={api.client}>
+                <DocumentFormDialog open onOpenChange={() => {}} model="customers.Invoice" forms={{ ...forms, types: [{ ...invoice, layout: undefined, sources: undefined }] }} />
+            </ApiProvider>,
+        )
+        expect(document.querySelector('[data-slot="document-editor"]')).toBeNull()
+        expect(screen.getByRole('button', { name: 'Siguiente' })).toBeTruthy()
+    })
+
+    it('un tipo con sources usa el editor («Cargar desde…») salvo layout: wizard explícito', () => {
+        const api = makeApi()
+        const { unmount } = render(
+            <ApiProvider client={api.client}>
+                <DocumentFormDialog open onOpenChange={() => {}} model="customers.Invoice" forms={{ ...forms, types: [{ ...invoice, layout: undefined }] }} />
+            </ApiProvider>,
+        )
+        expect(document.querySelector('[data-slot="load-from-source"]')).toBeTruthy()
+        unmount()
+        render(
+            <ApiProvider client={api.client}>
+                <DocumentFormDialog open onOpenChange={() => {}} model="customers.Invoice" forms={{ ...forms, types: [{ ...invoice, layout: 'wizard' }] }} />
+            </ApiProvider>,
+        )
+        expect(document.querySelector('[data-slot="document-editor"]')).toBeNull()
+    })
+})
+
+describe('DocumentEditor — «crear desde» con lo pendiente del servidor', () => {
+    const tracked: DocumentFormType = {
+        ...invoice,
+        sources: [{ ...invoice.sources![0], line_link_field: 'sales_order_item_id', exclude_states: ['cancelled'] }],
+    }
+    const pendingRows = {
+        data: [
+            { id: 'soi-1', source_line_id: 'soi-1', product_id: 'p1', product_name: 'Llanta 205/55R16', quantity: 4, remaining_quantity: 1, unit_price: 1500, discount: 0, tax_rate: 0.16 },
+            { id: 'soi-2', source_line_id: 'soi-2', product_id: 'p2', product_name: 'Balanceo', quantity: 4, remaining_quantity: 0, unit_price: 100, tax_rate: 0.16 },
+        ],
+    }
+
+    it('precarga lo pendiente (no lo vendido), omite lo ya facturado y guarda el vínculo por renglón', async () => {
+        const api = makeApi({
+            '/dynamic/customers.Invoice/source-lines': pendingRows,
+            '/data/customers.SalesOrder': { data: [{ id: 'so-1' }] },
+        })
+        renderEditor(tracked, api, { initialSource: { key: 'sales_order', id: 'so-1' } })
+        await screen.findByDisplayValue('Llanta 205/55R16')
+        expect(screen.queryByDisplayValue('Balanceo')).toBeNull()
+        expect(api.get).toHaveBeenCalledWith('/dynamic/customers.Invoice/source-lines', { params: { source: 'sales_order', id: 'so-1' } })
+        expect(await screen.findByText('1 renglones con lo pendiente · 1 ya cubiertos se omitieron')).toBeTruthy()
+    })
+
+    it('si el host aún no sirve source-lines (404) cae a la relación del origen', async () => {
+        const api = makeApi({
+            '/dynamic/customers.Invoice/source-lines': () => {
+                throw { response: { status: 404 } }
+            },
+            '/metadata/table/customers.SalesOrder': { data: { relations: [{ name: 'items', kind: 'one_to_many', through: 'customers.SalesOrderItem', foreign_key: 'sales_order_id' }] } },
+            '/data/customers.SalesOrderItem': { data: [{ id: 'soi-1', product_id: 'p1', product_name: 'Llanta 205/55R16', quantity: 4, unit_price: 1500, tax_rate: 0.16 }] },
+        })
+        renderEditor(tracked, api, { initialSource: { key: 'sales_order', id: 'so-1' } })
+        await screen.findByDisplayValue('Llanta 205/55R16')
+    })
+
+    it('el rechazo del servidor por exceso se muestra con su mensaje en español', async () => {
+        const post = vi.fn().mockRejectedValue({
+            response: {
+                status: 422,
+                data: {
+                    success: false,
+                    message: 'validation failed',
+                    errors: { 'lines.0.quantity': [{ code: 'exceeds_remaining', message: 'Renglón 1: la cantidad 1 excede lo pendiente de «Venta» (0).' }] },
+                },
+            },
+        })
+        const api = makeApi({ '/dynamic/customers.Invoice/source-lines': pendingRows, '/data/customers.SalesOrder': { data: [{ id: 'so-1', customer_name: 'ACME' }] } }, post)
+        renderEditor(
+            { ...tracked, sources: [{ ...tracked.sources![0], header: { customer_name: 'customer_name' } }] },
+            api,
+            { initialSource: { key: 'sales_order', id: 'so-1' } },
+        )
+        await screen.findByDisplayValue('ACME')
+        fireEvent.click(screen.getByRole('button', { name: 'Guardar factura' }))
+        await waitFor(() => expect(post).toHaveBeenCalled())
+        const [, body] = post.mock.calls[0] as [string, any]
+        expect(body.lines).toEqual([expect.objectContaining({ product_id: 'p1', quantity: 1, sales_order_item_id: 'soi-1' })])
+        expect(await screen.findByText(/excede lo pendiente de «Venta»/)).toBeTruthy()
+    })
+})