@asteby/metacore-runtime-react 49.0.0 → 49.2.0

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

@@ -0,0 +1,267 @@
+// @vitest-environment happy-dom
+// Facturas → Crear (P0 UX Acxel, 2026-10-06): el tipo factura con
+// `layout: "editor"` abre el DocumentEditor a pantalla completa, no el wizard
+// «Datos → Siguiente». A la vista solo cliente (con su tarjeta fiscal), método
+// y forma de pago, renglones y totales; lo demás en «Opciones fiscales»
+// plegada, una sola acción primaria y la vista previa plegada. «Cargar desde»
+// OT de taller y cotización precarga lo que queda por facturar.
+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 dict: Record<string, string> = { 'customers.field.tax_id': 'RFC' }
+    const t = (k: string, o?: Record<string, any>) => {
+        let s: string = dict[k] ?? 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 { DocumentFormDialog } from '../document-form-dialog'
+import { ApiProvider, type ApiClient } from '../api-context'
+import { TaxRateContext } from '../org-runtime-context'
+import { linesFromSource, splitEditorFields } from '../business/document-editor-model'
+import type { DocumentFormsManifest, DocumentFormType } from '../types'
+
+afterEach(cleanup)
+
+// Espejo del tipo `invoice` de customers.Invoice (addons, manifest.json).
+const invoice: DocumentFormType = {
+    key: 'invoice',
+    label: 'Factura',
+    value: 'I',
+    layout: 'editor',
+    party: {
+        field: 'customer_id',
+        model: 'customers.Customer',
+        summary: ['tax_id', 'fiscal_data.regimen_receptor', 'fiscal_data.codigo_postal', 'fiscal_data.uso_cfdi'],
+        credit: { limit: 'credit_limit', balance: 'balance_due', overdue: 'overdue_amount', hold_reason: 'credit_hold_reason' },
+    },
+    fields: [
+        { key: 'customer_id', label: 'Cliente', type: 'text', required: true },
+        { key: 'invoice_date', label: 'Fecha de emisión', type: 'date', required: true, defaultValue: '$today' },
+        { key: 'due_date', label: 'Vencimiento', type: 'date' },
+        { key: 'currency_code', label: 'Moneda', type: 'select', defaultValue: 'MXN', options: [{ value: 'MXN', label: 'Peso mexicano · MXN' }, { value: 'USD', label: 'Dólar · USD' }] },
+        { key: 'fiscal_data.metodo_pago', label: 'Método de pago', type: 'select', required: true, defaultValue: 'PUE', options: [{ value: 'PUE', label: 'Pago en una sola exhibición · PUE' }, { value: 'PPD', label: 'Pago en parcialidades o diferido · PPD' }] },
+        { key: 'fiscal_data.forma_pago', label: 'Forma de pago', type: 'select', required: true, defaultValue: '01', options: [{ value: '01', label: 'Efectivo · 01' }, { value: '03', label: 'Transferencia electrónica · 03' }] },
+        { key: 'notes', label: 'Notas', type: 'textarea' },
+    ],
+    lines: { columns: ['discount', 'tax'], discount_mode: 'amount', title: 'Renglones' },
+    sources: [
+        { key: 'sales_order', label: 'Venta', model: 'customers.SalesOrder', lines: 'items', map: { description: 'product_name' }, header: { customer_id: 'customer_id' }, link_field: 'sales_order_id', line_link_field: 'sales_order_item_id', exclude_states: ['cancelled', 'void'] },
+        { key: 'work_order', label: 'Orden de trabajo', model: 'workshop.WorkOrder', lines: 'items', header: { customer_id: 'customer_id' }, link_field: 'work_order_id', line_link_field: 'work_order_item_id', exclude_states: ['cancelled', 'void'] },
+        { key: 'quote', label: 'Cotización', model: 'quotes.Quote', lines: 'items', map: { discount: 'discount_amount' }, header: { customer_id: 'customer_id', currency_code: 'currency_code' }, link_field: 'quote_id', line_link_field: 'quote_item_id', exclude_states: ['cancelled', 'void'] },
+    ],
+    submit_label: 'Crear factura',
+}
+const forms: DocumentFormsManifest = { lines_field: 'items', types: [invoice] }
+
+const customer = {
+    id: 'c-1',
+    name: 'Transportes del Bajío',
+    tax_id: 'TBA850312KJ9',
+    credit_limit: 100000,
+    balance_due: 15750,
+    fiscal_data: { regimen_receptor: '601', codigo_postal: '37000', uso_cfdi: 'G03' },
+}
+
+// Lo pendiente lo sirve el runtime (kernel source-lines): cantidad − lo ya facturado.
+const workOrderLines = {
+    data: [
+        { id: 'woi-1', source_line_id: 'woi-1', kind: 'labor', description: 'Alineación eje direccional', quantity: 1, remaining_quantity: 1, unit_price: 650 },
+        { id: 'woi-2', source_line_id: 'woi-2', kind: 'part', product_id: 'p-valv', description: 'Válvula de alta presión', quantity: 6, remaining_quantity: 2, unit_price: 95 },
+        { id: 'woi-3', source_line_id: 'woi-3', kind: 'labor', description: 'Montaje y balanceo', quantity: 6, remaining_quantity: 0, unit_price: 180 },
+    ],
+}
+const quoteLines = {
+    data: [
+        { id: 'qi-1', source_line_id: 'qi-1', product_id: 'p-llanta', description: 'Llanta 295/80R22.5', quantity: 6, remaining_quantity: 4, unit_price: 5890, discount_amount: 1200, tax_rate: 0.16, tax_amount: 5462.4, subtotal: 34140 },
+    ],
+}
+
+function makeApi(sourceLines: Record<string, unknown> = {}, post = vi.fn().mockResolvedValue({ data: { success: true, data: { id: 'inv-1' } } })) {
+    const get = vi.fn(async (url: string, cfg?: { params?: Record<string, any> }) => {
+        if (url === '/metadata/modal/customers.Customer') {
+            return { data: { data: { fields: [{ key: 'tax_id', label: 'customers.field.tax_id' }, { key: 'fiscal_data.regimen_receptor', label: 'Régimen fiscal' }, { key: 'fiscal_data.codigo_postal', label: 'CP fiscal' }, { key: 'fiscal_data.uso_cfdi', label: 'Uso CFDI' }] } } }
+        }
+        if (url === '/data/customers.Customer') return { data: { data: [customer] } }
+        if (url.endsWith('/source-lines')) return { data: sourceLines[cfg?.params?.source] ?? { data: [] } }
+        if (url === '/data/workshop.WorkOrder') return { data: { data: [{ id: 'wo-1', customer_id: 'c-1' }] } }
+        if (url === '/data/quotes.Quote') return { data: { data: [{ id: 'q-1', customer_id: 'c-1', currency_code: 'MXN' }] } }
+        return { data: { data: [] } }
+    })
+    const client = { get, post, put: vi.fn().mockResolvedValue({ data: { success: true, data: { id: 'inv-1' } } }), delete: vi.fn() }
+    return { client: client as unknown as ApiClient, get, post }
+}
+
+function renderInvoice(api: ReturnType<typeof makeApi>, initialSource?: { key: string; id: string }) {
+    return render(
+        <ApiProvider client={api.client}>
+            <TaxRateContext.Provider value={0.16}>
+                <DocumentFormDialog
+                    open
+                    onOpenChange={() => {}}
+                    model="customers.Invoice"
+                    forms={forms}
+                    initialType={initialSource ? 'invoice' : undefined}
+                    initialSource={initialSource}
+                    currency="MXN"
+                />
+            </TaxRateContext.Provider>
+        </ApiProvider>,
+    )
+}
+
+const slot = (name: string) => document.querySelector(`[data-slot="${name}"]`) as HTMLElement
+
+describe('Factura con layout editor — pantalla única', () => {
+    it('abre el DocumentEditor a pantalla completa, no el wizard', () => {
+        renderInvoice(makeApi())
+        const dialog = slot('document-editor-dialog')
+        expect(dialog.getAttribute('data-fullscreen')).toBe('true')
+        expect(dialog.style.height).toBe('calc(100dvh - 2rem)')
+        expect(slot('document-editor').getAttribute('data-layout')).toBe('fullscreen')
+        expect(screen.queryByRole('button', { name: 'Siguiente' })).toBeNull()
+        expect(document.querySelector('[data-slot="document-form-dialog"]')).toBeNull()
+    })
+
+    it('secciones: lo esencial a la vista, «Opciones fiscales» plegada, totales y vista previa al lado', () => {
+        renderInvoice(makeApi())
+        const main = slot('editor-main')
+        const essentials = within(slot('editor-essentials'))
+        for (const label of ['Cliente', 'Fecha de emisión', 'Vencimiento', 'Método de pago', 'Forma de pago']) {
+            expect(essentials.getByText(label)).toBeTruthy()
+        }
+        // Etiqueta clara con el código SAT como dato secundario.
+        expect(screen.getAllByText('Pago en una sola exhibición · PUE').length).toBeGreaterThan(0)
+        expect(within(main).getByText('Cargar desde…')).toBeTruthy()
+        expect(within(main).getByText('Renglones')).toBeTruthy()
+
+        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('Moneda')).toBeTruthy()
+        expect(essentials.queryByText('Moneda')).toBeNull()
+
+        const aside = within(slot('editor-aside'))
+        const totals = slot('editor-aside').querySelector(':scope > div > [data-slot="totals"]') as HTMLElement
+        expect(within(totals).getByText('Total')).toBeTruthy()
+        const preview = aside.getByRole('button', { name: /Vista previa/ })
+        expect(preview.getAttribute('aria-expanded')).toBe('false')
+    })
+
+    it('una sola acción primaria: «Crear factura»', () => {
+        renderInvoice(makeApi())
+        const primaries = document.querySelectorAll('[data-slot="document-editor"] [data-primary="true"]')
+        expect(primaries.length).toBe(1)
+        expect(primaries[0].textContent).toBe('Crear factura')
+    })
+
+    it('«Cargar desde» ofrece venta, OT y cotización como opciones', () => {
+        renderInvoice(makeApi())
+        const group = screen.getByRole('radiogroup', { name: 'Tipo de documento origen' })
+        expect(within(group).getAllByRole('radio').map((r) => r.textContent)).toEqual(['Venta', 'Orden de trabajo', 'Cotización'])
+        fireEvent.click(within(group).getByRole('radio', { name: 'Orden de trabajo' }))
+        expect(within(group).getByRole('radio', { name: 'Orden de trabajo' }).getAttribute('aria-checked')).toBe('true')
+        expect(document.querySelector('[data-source="work_order"]')).toBeTruthy()
+    })
+})
+
+describe('Factura — «Cargar desde» OT y cotización con lo restante', () => {
+    it('OT: cliente, renglones con lo pendiente (omite lo ya facturado), IVA de la org y vínculos', async () => {
+        const api = makeApi({ work_order: workOrderLines })
+        renderInvoice(api, { key: 'work_order', id: 'wo-1' })
+        await screen.findByDisplayValue('Válvula de alta presión')
+        expect(screen.getByDisplayValue('Alineación eje direccional')).toBeTruthy()
+        expect(screen.queryByDisplayValue('Montaje y balanceo')).toBeNull()
+        expect(api.get).toHaveBeenCalledWith('/dynamic/customers.Invoice/source-lines', { params: { source: 'work_order', id: 'wo-1' } })
+        expect(await screen.findByText('2 renglones con lo pendiente · 1 ya cubiertos se omitieron')).toBeTruthy()
+
+        // La tarjeta del cliente: datos fiscales con etiquetas del modelo.
+        await waitFor(() => expect(slot('party-card')).toBeTruthy())
+        const card = slot('party-card')
+        expect(within(card).getByText('Transportes del Bajío')).toBeTruthy()
+        expect(within(card).getByText('RFC')).toBeTruthy()
+        expect(within(card).getByText('TBA850312KJ9')).toBeTruthy()
+        expect(within(card).getByText('Uso CFDI')).toBeTruthy()
+        expect(within(card).getByText('G03')).toBeTruthy()
+
+        fireEvent.click(screen.getByRole('button', { name: 'Crear 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.customer_id).toBe('c-1')
+        expect(body.work_order_id).toBe('wo-1')
+        expect(body['fiscal_data.metodo_pago']).toBe('PUE')
+        expect(body['fiscal_data.forma_pago']).toBe('01')
+        expect(body.items).toEqual([
+            expect.objectContaining({ description: 'Alineación eje direccional', quantity: 1, unit_price: 650, tax_rate: 0.16, work_order_item_id: 'woi-1' }),
+            expect.objectContaining({ product_id: 'p-valv', quantity: 2, unit_price: 95, tax_rate: 0.16, work_order_item_id: 'woi-2' }),
+        ])
+    })
+
+    it('cotización: lo pendiente, su IVA y descuento, moneda y vínculo', async () => {
+        const api = makeApi({ quote: quoteLines })
+        renderInvoice(api, { key: 'quote', id: 'q-1' })
+        await screen.findByDisplayValue('Llanta 295/80R22.5')
+        fireEvent.click(screen.getByRole('button', { name: 'Crear factura' }))
+        await waitFor(() => expect(api.post).toHaveBeenCalled())
+        const [, body] = api.post.mock.calls[0] as [string, any]
+        expect(body.quote_id).toBe('q-1')
+        expect(body.currency_code).toBe('MXN')
+        expect(body.items).toEqual([
+            expect.objectContaining({ product_id: 'p-llanta', quantity: 4, unit_price: 5890, discount: 1200, tax_rate: 0.16, quote_item_id: 'qi-1' }),
+        ])
+        expect(body.items[0]).not.toHaveProperty('work_order_item_id')
+    })
+
+    it('exceso: la cantidad no pasa de lo pendiente y el rechazo del servidor se muestra inline', async () => {
+        const post = vi.fn().mockRejectedValue({
+            response: {
+                status: 422,
+                data: {
+                    success: false,
+                    message: 'validation failed',
+                    errors: { 'items.1.quantity': [{ code: 'exceeds_remaining', message: 'Renglón 2: la cantidad 2 excede lo pendiente de «Orden de trabajo» (1). Ajusta la cantidad; lo demás ya está registrado en otro documento.' }] },
+                },
+            },
+        })
+        const api = makeApi({ work_order: workOrderLines }, post)
+        renderInvoice(api, { key: 'work_order', id: 'wo-1' })
+        await screen.findByDisplayValue('Válvula de alta presión')
+        // El editor topa la cantidad en lo pendiente (2 de 6).
+        const qty = screen.getAllByLabelText('Cant.').filter((el) => el.tagName === 'INPUT')[1] as HTMLInputElement
+        fireEvent.change(qty, { target: { value: '5' } })
+        expect(qty.value).toBe('2')
+        // Si otro documento consumió lo pendiente mientras tanto, el servidor rechaza.
+        fireEvent.click(screen.getByRole('button', { name: 'Crear factura' }))
+        await waitFor(() => expect(post).toHaveBeenCalled())
+        expect(await screen.findByText(/excede lo pendiente de «Orden de trabajo»/)).toBeTruthy()
+        expect(slot('document-editor-dialog')).toBeTruthy()
+    })
+})
+
+describe('reglas puras del editor de factura', () => {
+    it('lo obligatorio que el tipo declara queda a la vista aunque sea fiscal_data.*; las extensiones del metadata se pliegan', () => {
+        const g = splitEditorFields(invoice.fields, {
+            partyField: 'customer_id',
+            extensionFields: [{ key: 'fiscal_data.uso_cfdi', label: 'Uso CFDI', type: 'select', required: true, options: [{ value: 'G03', label: 'G03' }] }],
+        })
+        expect(g.party?.key).toBe('customer_id')
+        expect(g.essential.map((f) => f.key)).toEqual(['invoice_date', 'due_date', 'fiscal_data.metodo_pago', 'fiscal_data.forma_pago'])
+        expect(g.advanced.map((f) => f.key)).toEqual(['currency_code', 'fiscal_data.uso_cfdi'])
+        expect(g.notes.map((f) => f.key)).toEqual(['notes'])
+    })
+
+    it('un origen sin dato de impuesto toma la tasa de la org; uno con impuesto conserva el suyo', () => {
+        const [wo] = linesFromSource([{ id: 'a', description: 'Mano de obra', quantity: 1, unit_price: 100 }], {}, { defaultTaxRate: 0.16 })
+        expect(wo.tax_rate).toBe(0.16)
+        const [exempt] = linesFromSource([{ id: 'b', description: 'Exento', quantity: 1, unit_price: 100, subtotal: 100, tax_amount: 0 }], {}, { defaultTaxRate: 0.16 })
+        expect(exempt.tax_rate).toBe(0)
+    })
+})

package/src/__tests__/r5-self-label-settled.test.ts

@@ -0,0 +1,57 @@
+// @vitest-environment happy-dom
+// Retest Pitsline r5: «Registrar pago» desde la factura mostraba el UUID en
+// «Factura a abonar», y la lista / la pestaña REP no se refrescaban con lo que
+// el servidor escribe después de la acción (estado tras timbrar, REP tras pagar).
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { seedOptionFromRecord } from '../action-modal-dispatcher'
+import { emitRecordMutationSettled, subscribeRecordMutations, RECORD_MUTATION_SETTLE_DELAYS } from '../record-mutation-events'
+import type { ActionFieldDef } from '../types'
+
+const invoiceField = {
+    key: 'invoice_id',
+    type: 'dynamic_select',
+    ref: 'Invoice',
+    options: { source: 'Invoice', value: 'id', label: 'number' },
+} as unknown as ActionFieldDef
+
+describe('seedOptionFromRecord — la propia fila', () => {
+    it('un selector sembrado con el id de la fila muestra su folio, no el UUID', () => {
+        const record = { id: '68a02222-855e-4af9-b086-31526f0dceb5', number: 'FAC-00015', total: 823.6 }
+        expect(seedOptionFromRecord(invoiceField, record.id, record)).toEqual(
+            expect.objectContaining({ id: record.id, value: record.id, label: 'FAC-00015' }),
+        )
+    })
+    it('sin options.label usa la primera columna de nombre', () => {
+        const field = { key: 'invoice_id', type: 'dynamic_select', ref: 'Invoice' } as unknown as ActionFieldDef
+        expect(seedOptionFromRecord(field, 'i1', { id: 'i1', folio: 'A-7' })?.label).toBe('A-7')
+    })
+    it('otro valor (no la propia fila) sigue resolviendo por el objeto hermano', () => {
+        const record = { id: 'pay-1', invoice: { value: 'i9', label: 'FAC-00009' } }
+        expect(seedOptionFromRecord(invoiceField, 'i9', record)?.label).toBe('FAC-00009')
+        expect(seedOptionFromRecord(invoiceField, 'i8', { id: 'pay-1' })).toBeUndefined()
+    })
+})
+
+describe('emitRecordMutationSettled', () => {
+    afterEach(() => vi.useRealTimers())
+    it('anuncia ahora y otra vez cuando el servidor ya escribió lo derivado', () => {
+        vi.useFakeTimers()
+        const seen = vi.fn()
+        const off = subscribeRecordMutations('invoices', seen)
+        emitRecordMutationSettled('invoices', 'update')
+        expect(seen).toHaveBeenCalledTimes(1)
+        vi.advanceTimersByTime(RECORD_MUTATION_SETTLE_DELAYS[RECORD_MUTATION_SETTLE_DELAYS.length - 1])
+        expect(seen).toHaveBeenCalledTimes(1 + RECORD_MUTATION_SETTLE_DELAYS.length)
+        off()
+    })
+    it('se puede cancelar', () => {
+        vi.useFakeTimers()
+        const seen = vi.fn()
+        const off = subscribeRecordMutations('invoices', seen)
+        const cancel = emitRecordMutationSettled('invoices', 'update')
+        cancel()
+        vi.advanceTimersByTime(10_000)
+        expect(seen).toHaveBeenCalledTimes(1)
+        off()
+    })
+})

package/src/action-modal-dispatcher.tsx

@@ -14,7 +14,7 @@
 //
 // The host injects its axios-like client via <ApiProvider>; we no longer
 // depend on a bundler alias to `@/lib/api`.
-import { emitRecordMutation } from './record-mutation-events'
+import { emitRecordMutationSettled } from './record-mutation-events'
 import { Suspense, useState, useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react'
 import { useTranslation } from 'react-i18next'
 import {
@@ -93,6 +93,8 @@ import { requestFederatedAction } from './federated-action-loader'
 import { useInstalledAddons } from './installed-addons-context'
 import { federatedModalComponent, resolveFederatedModal } from './primitives/contributions'
 import { installedPredicate, useContributionsVersion } from './primitives/use-contributions'
+import { isTodayToken, todayInZone } from './calendar-date'
+import { useTimeZone } from './org-runtime-context'
 
 export type { ActionMetadata, ActionModalProps }
 
@@ -413,9 +415,11 @@ export function ActionModalDispatcher({
 }: ActionModalProps) {
     // Every successful action may have created/updated/deleted a record of
     // `model` (federated component, wizard, generic form or confirmation), so
-    // announce it: mounted lists of the model reload on their own (#1020).
+    // announce it: mounted lists of the model reload on their own (#1020) —
+    // and again once the server's event subscribers had time to write what the
+    // action triggers (estado tras timbrar, REP tras un pago).
     const onSuccess = useCallback(() => {
-        emitRecordMutation(model, 'update')
+        emitRecordMutationSettled(model, 'update')
         onSuccessProp?.()
     }, [model, onSuccessProp])
     // Reactive read: a federated remote usually registers AFTER the first
@@ -1021,6 +1025,7 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
     const reasonPrompt = useReasonPrompt()
     const supervisor = useSupervisor()
     const branchGate = useBranchCreateGate()
+    const orgTimeZone = useTimeZone()
     const [formData, setFormData] = useState<Record<string, any>>({})
     const [executing, setExecuting] = useState(false)
     // Per-field validation errors (localized), shown inline under each input.
@@ -1058,11 +1063,11 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
 
     useEffect(() => {
         if (open && action.fields) {
-            setFormData(buildFieldDefaults(action.fields, record, model))
+            setFormData(buildFieldDefaults(action.fields, record, model, { timeZone: orgTimeZone }))
             setFieldErrors({})
             setFormError(undefined)
         }
-    }, [open, action.fields, record, model])
+    }, [open, action.fields, record, model, orgTimeZone])
 
     // Lines the list row does not carry: load them from the declared relation
     // (see prefillRelationRequests) and seed the line-items grid.
@@ -1353,10 +1358,44 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
     )
 }
 
+/** Context a declared field default is resolved against. */
+export interface FieldDefaultContext {
+    /** Org IANA timezone: `$today` is the org's day, not the browser's or UTC's. */
+    timeZone?: string
+    /** Clock (tests). */
+    now?: Date
+}
+
+const DATE_FIELD_TYPES = new Set(['date', 'datetime', 'timestamp', 'timestamptz'])
+
+/**
+ * The declared scalar default of a field, resolved: `defaultValue` (host
+ * camelCase) or `default` (raw manifest, the kernel serves action/document-form
+ * fields without renaming it). A date field may declare `$today` / `today` and
+ * gets the org's calendar day. An unknown `$token` never lands in a date field
+ * (undefined): a literal "$today" posted as invoice_date is a 422, an empty
+ * field is just a required field to fill.
+ */
+export function resolveFieldDefault(field: ActionFieldDef, ctx: FieldDefaultContext = {}): unknown {
+    const f = field as { defaultValue?: unknown; default?: unknown }
+    const raw = f.defaultValue ?? f.default
+    if (raw === undefined || raw === null) return undefined
+    if (DATE_FIELD_TYPES.has(String(field.type ?? '').toLowerCase()) && typeof raw === 'string') {
+        if (isTodayToken(raw)) return todayInZone(ctx.timeZone, ctx.now)
+        if (raw.trim().startsWith('$')) return undefined
+    }
+    return raw
+}
+
 // buildFieldDefaults seeds formData for a set of action fields, honoring the
 // same line-items prefill spec + boolean/empty rules GenericActionModal uses, so
 // wizard steps and single-page forms initialize identically.
-export function buildFieldDefaults(fields: ActionFieldDef[], record: any, model?: string): Record<string, any> {
+export function buildFieldDefaults(
+    fields: ActionFieldDef[],
+    record: any,
+    model?: string,
+    ctx: FieldDefaultContext = {},
+): Record<string, any> {
     const defaults: Record<string, any> = {}
     for (const field of fields) {
         if (isLineItemsField(field)) {
@@ -1373,7 +1412,7 @@ export function buildFieldDefaults(fields: ActionFieldDef[], record: any, model?
             defaults[field.key] = fromRecord
             continue
         }
-        defaults[field.key] = field.defaultValue ?? (field.type === 'boolean' ? false : '')
+        defaults[field.key] = resolveFieldDefault(field, ctx) ?? (field.type === 'boolean' ? false : '')
     }
     return defaults
 }
@@ -1404,6 +1443,7 @@ function WizardActionModal({ open, onOpenChange, action, model, record, endpoint
     const api = useApi()
     const reasonPrompt = useReasonPrompt()
     const supervisor = useSupervisor()
+    const orgTimeZone = useTimeZone()
     const steps = action.steps ?? []
     const [stepIndex, setStepIndex] = useState(0)
     const [formData, setFormData] = useState<Record<string, any>>({})
@@ -1416,10 +1456,10 @@ function WizardActionModal({ open, onOpenChange, action, model, record, endpoint
     useEffect(() => {
         if (!open) return
         const allFields = steps.flatMap((s) => s.fields ?? [])
-        setFormData(buildFieldDefaults(allFields, record, model))
+        setFormData(buildFieldDefaults(allFields, record, model, { timeZone: orgTimeZone }))
         setStepIndex(0)
         setFormError(undefined)
-    }, [open, action.steps, record, model])
+    }, [open, action.steps, record, model, orgTimeZone])
 
     const updateField = (key: string, value: any) =>
         setFormData((prev: Record<string, any>) => ({ ...prev, [key]: value }))
@@ -1602,12 +1642,39 @@ function WizardActionModal({ open, onOpenChange, action, model, record, endpoint
     )
 }
 
-function seedOptionFromRecord(
+/** Columnas con las que se nombra una fila cuando el selector no declara `options.label`. */
+const RECORD_LABEL_COLUMNS = ['number', 'folio', 'name', 'title', 'code', 'label']
+
+/**
+ * La etiqueta de la PROPIA fila cuando el campo se sembró con su id
+ * («Factura a abonar» al registrar un pago desde la factura): la columna que el
+ * selector usa de etiqueta (`options.label`) o la primera de nombre que tenga.
+ * Sin esto el selector mostraba el UUID crudo (retest Pitsline r5).
+ */
+function selfLabel(field: ActionFieldDef, record: Record<string, any>): string {
+    const opts = (field as { options?: unknown }).options
+    const declared =
+        opts && !Array.isArray(opts) && typeof opts === 'object' ? (opts as { label?: unknown }).label : undefined
+    const cols = typeof declared === 'string' && declared ? [declared, ...RECORD_LABEL_COLUMNS] : RECORD_LABEL_COLUMNS
+    for (const c of cols) {
+        const v = unwrapRecordScalar(record[c])
+        if ((typeof v === 'string' && v.trim()) || typeof v === 'number') return String(v)
+    }
+    return ''
+}
+
+export function seedOptionFromRecord(
     field: ActionFieldDef,
     value: any,
     record?: Record<string, any>,
 ): import('./use-options-resolver').ResolvedOption | undefined {
-    if (!record || !field.key.endsWith('_id')) return undefined
+    if (!record) return undefined
+    const selfId = unwrapRecordScalar(record.id)
+    if (value != null && value !== '' && selfId != null && String(selfId) === String(value)) {
+        const label = selfLabel(field, record)
+        if (label) return { id: String(value), value: String(value), label, name: label }
+    }
+    if (!field.key.endsWith('_id')) return undefined
     const siblingKey = field.key.replace(/_id$/, '')
     const sib = record[siblingKey]
     if (!sib || typeof sib !== 'object') return undefined

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

@@ -54,7 +54,9 @@ function declaredDefault(f: ActionFieldDef): unknown {
 
 /**
  * Divulgación progresiva: ¿el campo va plegado en «Opciones fiscales»?
- *  - campos de extensión (`fiscal_data.*`) que aportan otros addons;
+ *  - campos de extensión (`fiscal_data.*`) que aportan otros addons (los que
+ *    el propio tipo declara obligatorios, p. ej. método y forma de pago de la
+ *    factura, se marcan esenciales en splitEditorFields);
  *  - `section: "fiscal" | "advanced"`;
  *  - catálogos opcionales que ya traen un default (método, serie, relación…):
  *    el usuario no necesita tocarlos para guardar.
@@ -84,7 +86,10 @@ export function splitEditorFields(
     fields: readonly ActionFieldDef[],
     opts: { partyField?: string; essentialKeys?: readonly string[]; extensionFields?: readonly ActionFieldDef[] } = {},
 ): EditorFieldGroups {
-    const essentialKeys = new Set(opts.essentialKeys ?? [])
+    // Lo obligatorio que el tipo declara siempre está a la vista, aunque sea de
+    // extensión (`fiscal_data.metodo_pago`): es lo que el usuario debe decidir.
+    // Las extensiones que llegan del metadata (no declaradas) siguen plegadas.
+    const essentialKeys = new Set([...(opts.essentialKeys ?? []), ...fields.filter((f) => f.required).map((f) => f.key)])
     const out: EditorFieldGroups = { essential: [], advanced: [], notes: [] }
     const seen = new Set<string>()
     for (const f of [...fields, ...(opts.extensionFields ?? [])]) {
@@ -200,7 +205,7 @@ export function creditStatus(
 export function linesFromSource(
     rows: unknown,
     map: Record<string, string> = {},
-    opts: { kind?: DocumentFormLines['kind']; discountMode?: DocumentFormLines['discount_mode'] } = {},
+    opts: { kind?: DocumentFormLines['kind']; discountMode?: DocumentFormLines['discount_mode']; defaultTaxRate?: number } = {},
 ): LineItem[] {
     if (!Array.isArray(rows)) return []
     return rows.filter((raw) => !isFullyConsumed(raw)).map((raw) => {
@@ -212,13 +217,18 @@ export function linesFromSource(
         if (!hasValue(rate)) {
             const sub = toAmount(get('subtotal'))
             const tax = toAmount(get('tax_amount'))
-            rate = sub > 0 ? Math.round((tax / sub) * 10000) / 10000 : 0
+            // Un origen sin dato de impuesto (p. ej. una OT de taller: solo
+            // cantidad y precio) toma la tasa de la org, como un renglón nuevo.
+            rate = hasValue(get('tax_amount'))
+                ? sub > 0 ? Math.round((tax / sub) * 10000) / 10000 : 0
+                : opts.defaultTaxRate ?? 0
         }
         const r2 = toAmount(rate)
+        const product = get('product_id')
         const line = makeLine({
-            product_id: get('product_id') ?? undefined,
+            product_id: refValue(product),
             sku: get('sku') ?? undefined,
-            description: String(get('description') ?? get('product_name') ?? ''),
+            description: String(get('description') ?? get('product_name') ?? refLabel(product) ?? refLabel(r.product) ?? ''),
             quantity: qty,
             unit_price: toAmount(get('unit_price')),
             discount: toAmount(get('discount') ?? 0),
@@ -236,11 +246,40 @@ export function linesFromSource(
     })
 }
 
+/** Id de una celda de relación (`{value,label}`, `{id,name}` o el id plano). */
+function refValue(v: unknown): string | undefined {
+    if (v == null || v === '') return undefined
+    if (typeof v === 'object') {
+        const o = v as Record<string, unknown>
+        const id = o.value ?? o.id
+        return id == null || id === '' ? undefined : String(id)
+    }
+    return String(v)
+}
+
+/**
+ * Nombre de una celda de relación ya resuelta por el host (`{label}`/`{name}`).
+ * Un renglón de origen sin descripción propia (InvoiceItem solo lleva el
+ * producto) se nombra con su producto en vez de entrar en blanco.
+ */
+function refLabel(v: unknown): string | undefined {
+    if (!v || typeof v !== 'object') return undefined
+    const o = v as Record<string, unknown>
+    const l = o.label ?? o.name
+    return typeof l === 'string' && l.trim() ? l : undefined
+}
+
 function isFullyConsumed(raw: unknown): boolean {
     const r = (raw ?? {}) as Record<string, any>
     return hasValue(r.remaining_quantity) && toAmount(r.remaining_quantity) <= 0
 }
 
+/** El editor ocupa toda la pantalla: documentos comerciales con renglones (factura, cotización, pedido, OC). */
+export function isFullscreenEditor(type: DocumentFormType, forms: Pick<DocumentFormsManifest, 'lines_field'>): boolean {
+    const kind = editorLinesConfig(type, forms)?.kind ?? 'sale'
+    return !!type.lines && (kind === 'sale' || kind === 'purchase')
+}
+
 /** Cuántos renglones del origen se cargaron y cuántos se omitieron por estar ya cubiertos. */
 export function sourceLoadSummary(rows: unknown): { loaded: number; covered: number } {
     if (!Array.isArray(rows)) return { loaded: 0, covered: 0 }
@@ -267,7 +306,11 @@ export function localIssues(lines: LineItem[], opts: { requireLines?: boolean; r
         issues.push({ field: 'lines', severity: 'error', message: 'Agrega al menos un renglón.' })
     }
     items.forEach((l, i) => {
-        if (!l.description.trim()) issues.push({ field: `lines.${i}`, severity: 'error', message: `Renglón ${i + 1}: falta la descripción.` })
+        // Un renglón con producto se describe con él (el servidor lo nombra
+        // desde el catálogo): solo un renglón libre exige texto, como en el
+        // editor de renglones (validateLineItems).
+        if (!l.description.trim() && !l.product_id)
+            issues.push({ field: `lines.${i}`, severity: 'error', message: `Renglón ${i + 1}: elige un producto o escribe la descripción.` })
         if (toAmount(l.unit_price) <= 0) issues.push({ field: `lines.${i}`, severity: 'warning', message: `Renglón ${i + 1}: precio en cero.` })
         if (l.max_quantity != null && toAmount(l.quantity) > toAmount(l.max_quantity)) {
             issues.push({