@asteby/metacore-runtime-react 47.1.0 → 48.0.0

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

@@ -0,0 +1,325 @@
+// Reglas puras del DocumentEditor (sin React ni host): qué se ve a primera
+// vista y qué va en «Opciones fiscales», qué copiar de la contraparte, cómo
+// traer renglones de un documento origen, cómo repartir un cobro entre los
+// documentos abiertos y qué revisar antes de guardar. Genérico: factura,
+// cotización, pedido, OC, nota de crédito y cobro/REP. El SDK no conoce CFDI.
+import { roundMoney, toAmount } from './format'
+import { computeTotals, makeLine, type LineItem } from './line-items'
+import { optionPassesRule, getOptionFilter } from '../option-filter'
+import type { ResolvedOption } from '../use-options-resolver'
+import type { Allocation, AllocationIssue, OpenDocument } from '../primitives/allocation'
+import type {
+    ActionFieldDef,
+    DocumentFormLines,
+    DocumentFormOpenDocuments,
+    DocumentFormsManifest,
+    DocumentFormType,
+} from '../types'
+
+export const EXTENSION_PREFIX = 'fiscal_data.'
+
+/** Secciones de campo que el editor pliega en «Opciones fiscales». */
+const ADVANCED_SECTIONS = new Set(['fiscal', 'advanced'])
+
+export type EditorLinesConfig = DocumentFormLines & { field: string }
+
+/** true si el tipo se abre en el DocumentEditor (`layout: "editor"`). */
+export function isEditorLayout(type: Pick<DocumentFormType, 'layout'> | null | undefined): boolean {
+    return type?.layout === 'editor'
+}
+
+/** Paso de renglones efectivo del tipo (o undefined si no tiene). */
+export function editorLinesConfig(type: DocumentFormType, forms: Pick<DocumentFormsManifest, 'lines_field'>): EditorLinesConfig | undefined {
+    if (!type.lines) return undefined
+    const cfg: DocumentFormLines = type.lines === true ? {} : type.lines
+    const fallback = cfg.kind === 'allocation' ? 'allocations' : 'lines'
+    return { ...cfg, field: cfg.field ?? forms.lines_field ?? fallback }
+}
+
+/** Lee `a.b.c` de un registro (incluye `fiscal_data.x` dentro del jsonb). */
+function readPath(rec: Record<string, any> | null | undefined, path: string): unknown {
+    if (!rec) return undefined
+    if (path in rec) return rec[path]
+    return path.split('.').reduce<any>((acc, k) => (acc == null ? undefined : acc[k]), rec)
+}
+
+const hasValue = (v: unknown) => v !== undefined && v !== null && v !== ''
+
+function declaredDefault(f: ActionFieldDef): unknown {
+    return (f as { defaultValue?: unknown; default?: unknown }).defaultValue ?? (f as { default?: unknown }).default
+}
+
+/**
+ * Divulgación progresiva: ¿el campo va plegado en «Opciones fiscales»?
+ *  - campos de extensión (`fiscal_data.*`) que aportan otros addons;
+ *  - `section: "fiscal" | "advanced"`;
+ *  - catálogos opcionales que ya traen un default (método, serie, relación…):
+ *    el usuario no necesita tocarlos para guardar.
+ * Lo obligatorio sin default, la contraparte y el monto siempre están a la vista.
+ */
+export function isAdvancedField(f: ActionFieldDef, essentialKeys: ReadonlySet<string> = new Set()): boolean {
+    if (essentialKeys.has(f.key)) return false
+    if (f.key.startsWith(EXTENSION_PREFIX)) return true
+    if (f.section && ADVANCED_SECTIONS.has(f.section)) return true
+    const hasOptions = Array.isArray(f.options) && f.options.length > 0
+    return !f.required && hasOptions && hasValue(declaredDefault(f))
+}
+
+export interface EditorFieldGroups {
+    /** Campo que elige la contraparte (cliente/proveedor), si el tipo la declara. */
+    party?: ActionFieldDef
+    /** A la vista: lo esencial del encabezado. */
+    essential: ActionFieldDef[]
+    /** Plegados en «Opciones fiscales». */
+    advanced: ActionFieldDef[]
+    /** Notas largas (textarea): al final. */
+    notes: ActionFieldDef[]
+}
+
+/** Reparte los campos del tipo (más los de extensión) en grupos de pantalla. */
+export function splitEditorFields(
+    fields: readonly ActionFieldDef[],
+    opts: { partyField?: string; essentialKeys?: readonly string[]; extensionFields?: readonly ActionFieldDef[] } = {},
+): EditorFieldGroups {
+    const essentialKeys = new Set(opts.essentialKeys ?? [])
+    const out: EditorFieldGroups = { essential: [], advanced: [], notes: [] }
+    const seen = new Set<string>()
+    for (const f of [...fields, ...(opts.extensionFields ?? [])]) {
+        if (seen.has(f.key)) continue
+        seen.add(f.key)
+        if (opts.partyField && f.key === opts.partyField) out.party = f
+        else if (f.type === 'textarea' || f.widget === 'textarea') out.notes.push(f)
+        else if (isAdvancedField(f, essentialKeys)) out.advanced.push(f)
+        else out.essential.push(f)
+    }
+    return out
+}
+
+/**
+ * Etiqueta clara con el código como dato secundario:
+ * `03 · Transferencia electrónica` → `Transferencia electrónica · 03`.
+ * Solo reordena el patrón «CÓDIGO · texto»; cualquier otra etiqueta pasa igual.
+ */
+export function friendlyOptionLabel(label: string): string {
+    const m = /^\s*([A-Z0-9]{1,5})\s*[·\-–]\s*(.+)$/.exec(label)
+    return m && /\d/.test(m[1]) ? `${m[2].trim()} · ${m[1]}` : label
+}
+
+/** El mismo campo con sus opciones en formato «texto · código». */
+export function withFriendlyOptions(f: ActionFieldDef): ActionFieldDef {
+    if (!Array.isArray(f.options) || f.options.length === 0) return f
+    return { ...f, options: f.options.map((o) => ({ ...o, label: friendlyOptionLabel(String(o.label ?? o.value)) })) }
+}
+
+/**
+ * Defaults del encabezado que salen de la contraparte: los campos de extensión
+ * con la MISMA clave en ambos modelos (p. ej. `fiscal_data.uso_cfdi` de Customer
+ * → `fiscal_data.uso_cfdi` del documento) y la moneda.
+ * Solo llena lo que está vacío: nunca pisa lo que el usuario ya capturó.
+ */
+export function partyDefaults(
+    party: Record<string, any> | null,
+    documentFieldKeys: readonly string[],
+    current: Record<string, unknown>,
+): Record<string, unknown> {
+    if (!party) return {}
+    const out: Record<string, unknown> = {}
+    for (const key of documentFieldKeys) {
+        if (!key.startsWith(EXTENSION_PREFIX) || hasValue(current[key])) continue
+        const v = readPath(party, key)
+        if (hasValue(v)) out[key] = v
+    }
+    if (!hasValue(current.currency_code) && typeof party.currency_code === 'string' && party.currency_code) {
+        out.currency_code = party.currency_code
+    }
+    return out
+}
+
+/** Filas de la tarjeta de contraparte: resumen declarado + extensiones (máximo `limit`). */
+export function partySummaryRows(
+    party: Record<string, any> | null,
+    summary: readonly string[] = [],
+    labels: Record<string, string> = {},
+    limit = 6,
+): Array<{ key: string; label: string; value: string }> {
+    if (!party) return []
+    const keys = new Set<string>(summary)
+    const fd = party.fiscal_data
+    if (fd && typeof fd === 'object') for (const k of Object.keys(fd)) keys.add(EXTENSION_PREFIX + k)
+    const rows: Array<{ key: string; label: string; value: string }> = []
+    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) })
+    }
+    return rows.slice(0, limit)
+}
+
+export interface CreditStatus {
+    limit?: number
+    balance?: number
+    overdue?: number
+    available?: number
+    holdReason?: string
+    /** `ok` | `warn` (supera 80 % o hay vencido) | `block` (retenido o sin crédito disponible). */
+    level: 'ok' | 'warn' | 'block'
+}
+
+export function creditStatus(
+    party: Record<string, any> | null,
+    cols: { limit?: string; balance?: string; overdue?: string; hold_reason?: string } | undefined,
+    documentTotal: number,
+): CreditStatus | null {
+    if (!party || !cols) return null
+    const n = (k?: string) => (k && hasValue(party[k]) ? toAmount(party[k]) : undefined)
+    const limit = n(cols.limit)
+    const balance = n(cols.balance)
+    const overdue = n(cols.overdue)
+    const holdReason = cols.hold_reason ? (party[cols.hold_reason] as string | undefined) || undefined : undefined
+    if (limit == null && balance == null && overdue == null && !holdReason) return null
+    const available = limit != null ? roundMoney(limit - (balance ?? 0)) : undefined
+    let level: CreditStatus['level'] = 'ok'
+    if (holdReason || (available != null && limit! > 0 && available < documentTotal)) level = 'block'
+    else if ((overdue ?? 0) > 0 || (limit != null && limit > 0 && (balance ?? 0) + documentTotal > 0.8 * limit)) level = 'warn'
+    return { limit, balance, overdue, available, holdReason, level }
+}
+
+/**
+ * Renglones de un documento origen → LineItem. `map` traduce nombres
+ * (`description: product_name`, `discount: discount_pct`). Si el origen trae
+ * `tax_amount` y `subtotal` pero no la tasa, la deriva. `credit` (NC) topa la
+ * cantidad en lo facturado (o en `max_quantity` si el origen la trae).
+ */
+export function linesFromSource(rows: unknown, map: Record<string, string> = {}, opts: { kind?: DocumentFormLines['kind'] } = {}): LineItem[] {
+    if (!Array.isArray(rows)) return []
+    return rows.map((raw) => {
+        const r = (raw ?? {}) as Record<string, any>
+        const get = (k: string) => r[map[k] ?? k]
+        const qty = toAmount(get('quantity') ?? 1)
+        let rate = get('tax_rate')
+        if (!hasValue(rate)) {
+            const sub = toAmount(get('subtotal'))
+            const tax = toAmount(get('tax_amount'))
+            rate = sub > 0 ? Math.round((tax / sub) * 10000) / 10000 : 0
+        }
+        const r2 = toAmount(rate)
+        const line = makeLine({
+            product_id: get('product_id') ?? undefined,
+            sku: get('sku') ?? undefined,
+            description: String(get('description') ?? get('product_name') ?? ''),
+            quantity: qty,
+            unit_price: toAmount(get('unit_price')),
+            discount: toAmount(get('discount') ?? 0),
+            tax_rate: r2 > 1 ? r2 / 100 : r2,
+            unit: get('unit') ?? undefined,
+        })
+        if (opts.kind === 'credit') line.max_quantity = hasValue(get('max_quantity')) ? toAmount(get('max_quantity')) : qty
+        return line
+    })
+}
+
+export interface EditorIssue {
+    field?: string
+    severity: 'error' | 'warning'
+    message: string
+}
+
+/** Revisión local (instantánea) de los renglones. Sin ruido: solo lo que hay que mirar. */
+export function localIssues(lines: LineItem[], opts: { requireLines?: boolean; requireTax?: boolean } = {}): EditorIssue[] {
+    const issues: EditorIssue[] = []
+    const items = lines.filter((l) => l.kind === 'item')
+    if ((opts.requireLines ?? true) && items.length === 0) {
+        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.` })
+        if (toAmount(l.unit_price) <= 0) issues.push({ field: `lines.${i}`, severity: 'warning', message: `Renglón ${i + 1}: precio en cero.` })
+        if (opts.requireTax && toAmount(l.tax_rate) === 0) {
+            issues.push({ field: `lines.${i}`, severity: 'warning', message: `Renglón ${i + 1}: sin impuesto.` })
+        }
+    })
+    if (computeTotals(lines).total < 0) issues.push({ severity: 'error', message: 'El total no puede ser negativo.' })
+    return issues
+}
+
+// ---- Cobro / REP (lines.kind = allocation) ----------------------------------
+
+/** Documento abierto (fila de /data) → OpenDocument para PaymentAllocator. */
+export function toOpenDocuments(rows: unknown, cfg: DocumentFormOpenDocuments, currency: string): OpenDocument[] {
+    if (!Array.isArray(rows)) return []
+    const rules = getOptionFilter(cfg)
+    const out: OpenDocument[] = []
+    for (const raw of rows) {
+        if (!raw || typeof raw !== 'object') continue
+        const r = raw as Record<string, any>
+        if (rules.length) {
+            const opt = { id: r.id, value: r.id, label: String(r[cfg.number_field] ?? ''), name: '', meta: r } as unknown as ResolvedOption
+            if (!rules.every((rule) => optionPassesRule(opt, rule))) continue
+        }
+        const balance = roundMoney(toAmount(readPath(r, cfg.balance_field)))
+        if (balance <= 0) continue
+        out.push({
+            id: String(r.id),
+            number: String(readPath(r, cfg.number_field) ?? r.id),
+            issued_at: String(readPath(r, cfg.issued_field ?? 'issued_at') ?? r.created_at ?? ''),
+            due_at: (cfg.due_field ? (readPath(r, cfg.due_field) as string | null) : null) ?? null,
+            total: roundMoney(toAmount(cfg.total_field ? readPath(r, cfg.total_field) : balance)),
+            balance,
+            currency: String(r.currency_code ?? r.currency ?? currency),
+            payment_method: cfg.method_field ? ((readPath(r, cfg.method_field) as string | null) ?? null) : null,
+            installments_paid: hasValue(r.installments_paid) ? toAmount(r.installments_paid) : undefined,
+        })
+    }
+    return out
+}
+
+/** Monto actual de cada documento, para pasar a modo manual sin perder lo repartido. */
+export function manualFromAllocations(allocations: readonly Allocation[]): Record<string, number> {
+    return Object.fromEntries(allocations.map((a) => [a.document_id, a.amount]))
+}
+
+/** Renglones del payload: solo los dos campos que declara la acción (`invoice_id`, `amount`). */
+export function allocationPayload(allocations: readonly Allocation[], cfg: DocumentFormOpenDocuments): Array<Record<string, unknown>> {
+    return allocations.filter((a) => a.amount > 0).map((a) => ({ [cfg.line_document_field]: a.document_id, [cfg.line_amount_field]: a.amount }))
+}
+
+/**
+ * Campo del encabezado con el monto recibido: `amount` si existe; si no, el
+ * primer campo numérico/moneda. Convención documentada (el schema no lo nombra).
+ */
+export function allocationAmountField(fields: readonly ActionFieldDef[]): string | undefined {
+    return (
+        fields.find((f) => f.key === 'amount')?.key ??
+        fields.find((f) => ['number', 'numeric', 'decimal', 'currency', 'money'].includes(f.type) || f.widget === 'currency')?.key
+    )
+}
+
+const ALLOCATION_MESSAGES: Record<AllocationIssue['code'], string> = {
+    non_positive: 'Captura el monto recibido.',
+    over_balance: 'Se aplica más que el saldo del documento.',
+    over_amount: 'Lo aplicado supera el monto recibido.',
+    currency_mismatch: 'El documento está en otra moneda.',
+    unapplied: 'Queda monto sin aplicar.',
+}
+
+/** AllocationIssue → mensaje en español claro (con el número del documento). */
+export function allocationIssueMessages(issues: readonly AllocationIssue[], docs: readonly OpenDocument[]): EditorIssue[] {
+    const byId = new Map(docs.map((d) => [d.id, d]))
+    return issues.map((i) => {
+        const doc = i.document_id ? byId.get(i.document_id) : undefined
+        return {
+            field: i.code === 'non_positive' ? 'amount' : 'allocations',
+            severity: i.severity,
+            message: doc ? `${doc.number}: ${ALLOCATION_MESSAGES[i.code]}` : ALLOCATION_MESSAGES[i.code],
+        }
+    })
+}
+
+/** Días de atraso de un documento abierto (0 si no está vencido o no tiene vencimiento). */
+export function overdueDays(doc: Pick<OpenDocument, 'due_at'>, today: Date = new Date()): number {
+    if (!doc.due_at) return 0
+    const due = new Date(doc.due_at)
+    if (Number.isNaN(due.getTime())) return 0
+    const ms = Date.UTC(today.getFullYear(), today.getMonth(), today.getDate()) - Date.UTC(due.getUTCFullYear(), due.getUTCMonth(), due.getUTCDate())
+    return Math.max(0, Math.floor(ms / 86_400_000))
+}

package/src/business/document-editor-panels.tsx

@@ -0,0 +1,164 @@
+// Piezas visuales del DocumentEditor: secciones, sección plegable, tarjeta de
+// contraparte, totales, revisión y vista previa. Sin estado de negocio: el
+// editor (o un remote federado) les pasa los datos ya calculados. Los contratos
+// de datos viven en primitives/panels.ts.
+import { useId, useState, type ReactNode } from 'react'
+import { Badge } from '@asteby/metacore-ui/primitives'
+import { AlertTriangle, ChevronDown, XCircle } from 'lucide-react'
+import type { CreditStatus, EditorIssue } from './document-editor-model'
+import type { Formatter } from './format'
+
+/** Bloque con título discreto y espaciado generoso (sin bordes pesados). */
+export function EditorSection({ title, hint, children, slot }: { title?: ReactNode; hint?: ReactNode; children: ReactNode; slot?: string }) {
+    return (
+        <section className="space-y-3" data-slot={slot}>
+            {(title || hint) && (
+                <header className="flex items-baseline justify-between gap-3">
+                    {title && <h3 className="text-sm font-semibold">{title}</h3>}
+                    {hint && <span className="text-xs text-muted-foreground">{hint}</span>}
+                </header>
+            )}
+            {children}
+        </section>
+    )
+}
+
+export interface CollapsibleSectionProps {
+    title: ReactNode
+    /** Resumen de una línea cuando está cerrada (p. ej. «G03 · PUE»). */
+    summary?: ReactNode
+    open?: boolean
+    defaultOpen?: boolean
+    onOpenChange?: (open: boolean) => void
+    children: ReactNode
+    slot?: string
+}
+
+/**
+ * Sección plegable. El contenido queda MONTADO aunque esté cerrada (`hidden`):
+ * las contribuciones de otros addons siguen aplicando defaults y reportando
+ * revisiones sin que el usuario abra la sección.
+ */
+export function CollapsibleSection({ title, summary, open, defaultOpen = false, onOpenChange, children, slot }: CollapsibleSectionProps) {
+    const [inner, setInner] = useState(defaultOpen)
+    const isOpen = open ?? inner
+    const id = useId()
+    const toggle = () => {
+        setInner(!isOpen)
+        onOpenChange?.(!isOpen)
+    }
+    return (
+        <section className="rounded-lg border border-dashed" data-slot={slot} data-state={isOpen ? 'open' : 'closed'}>
+            <button
+                type="button"
+                aria-expanded={isOpen}
+                aria-controls={id}
+                onClick={toggle}
+                className="flex w-full items-center justify-between gap-3 px-4 py-3 text-left text-sm"
+            >
+                <span className="font-medium">{title}</span>
+                <span className="flex min-w-0 items-center gap-2 text-xs text-muted-foreground">
+                    {!isOpen && summary && <span className="truncate">{summary}</span>}
+                    <ChevronDown className={`size-4 shrink-0 transition-transform ${isOpen ? 'rotate-180' : ''}`} aria-hidden />
+                </span>
+            </button>
+            <div id={id} hidden={!isOpen} className="space-y-4 px-4 pb-4">
+                {children}
+            </div>
+        </section>
+    )
+}
+
+export interface PartyCardProps {
+    name?: string
+    rows: Array<{ key: string; label: string; value: string }>
+    credit?: CreditStatus | null
+    fmt: Formatter
+    children?: ReactNode
+}
+
+/** Tarjeta compacta de la contraparte: nombre, 3-6 datos clave y estado de crédito. */
+export function PartyCard({ name, rows, credit, fmt, children }: PartyCardProps) {
+    return (
+        <div className="rounded-md bg-muted/40 px-4 py-3 text-sm" data-slot="party-card">
+            <div className="flex flex-wrap items-center justify-between gap-2">
+                {name && <span className="font-medium">{name}</span>}
+                {credit && (
+                    <Badge variant={credit.level === 'block' ? 'destructive' : credit.level === 'warn' ? 'secondary' : 'outline'} data-slot="party-credit">
+                        {credit.holdReason
+                            ? credit.holdReason
+                            : credit.available != null
+                              ? `Crédito disponible ${fmt.money(credit.available)}`
+                              : `Saldo ${fmt.money(credit.balance ?? 0)}`}
+                    </Badge>
+                )}
+            </div>
+            {rows.length > 0 && (
+                <dl className="mt-2 grid grid-cols-2 gap-x-6 gap-y-1 sm:grid-cols-3">
+                    {rows.map((r) => (
+                        <div key={r.key} className="min-w-0">
+                            <dt className="text-xs text-muted-foreground">{r.label}</dt>
+                            <dd className="truncate">{r.value}</dd>
+                        </div>
+                    ))}
+                </dl>
+            )}
+            {children}
+        </div>
+    )
+}
+
+export interface TotalsRow {
+    label: string
+    value: string
+    emphasis?: boolean
+}
+
+/** Totales alineados a la derecha; la última fila con `emphasis` es el total. */
+export function TotalsPanel({ rows }: { rows: TotalsRow[] }) {
+    return (
+        <dl className="ml-auto w-full max-w-xs space-y-1 text-sm tabular-nums" data-slot="totals">
+            {rows.map((r) => (
+                <div key={r.label} className={`flex justify-between gap-6 ${r.emphasis ? 'border-t pt-2 text-base font-semibold' : ''}`}>
+                    <dt className={r.emphasis ? '' : 'text-muted-foreground'}>{r.label}</dt>
+                    <dd>{r.value}</dd>
+                </div>
+            ))}
+        </dl>
+    )
+}
+
+/** Lista de revisión: errores (rojo) y avisos (ámbar). Vacía → no pinta nada. */
+export function ValidationChecklist({ issues, title = 'Revisa antes de guardar' }: { issues: EditorIssue[]; title?: string }) {
+    if (issues.length === 0) return null
+    return (
+        <div className="rounded-md bg-muted/30 px-4 py-3" data-slot="validation-checklist" role="status">
+            <p className="mb-1 text-xs font-medium text-muted-foreground">{title}</p>
+            <ul className="space-y-1 text-sm">
+                {issues.map((i, k) => (
+                    <li key={`${i.field ?? ''}:${k}`} className={`flex items-start gap-2 ${i.severity === 'error' ? 'text-destructive' : 'text-amber-700'}`}>
+                        {i.severity === 'error' ? <XCircle className="mt-0.5 size-4 shrink-0" aria-hidden /> : <AlertTriangle className="mt-0.5 size-4 shrink-0" aria-hidden />}
+                        {i.message}
+                    </li>
+                ))}
+            </ul>
+        </div>
+    )
+}
+
+export interface PreviewContent {
+    xml?: string
+    html?: string
+    pdf_url?: string
+    pdf_base64?: string
+}
+
+/** Contenido de la vista previa (PDF, HTML o XML, en ese orden de preferencia). */
+export function PreviewPanel({ preview }: { preview: PreviewContent | null }) {
+    if (!preview) return null
+    const pdf = preview.pdf_url ?? (preview.pdf_base64 ? `data:application/pdf;base64,${preview.pdf_base64}` : undefined)
+    if (pdf) return <iframe title="Vista previa" src={pdf} className="h-96 w-full rounded border" data-slot="preview-pdf" />
+    if (preview.html) return <iframe title="Vista previa" srcDoc={preview.html} className="h-96 w-full rounded border" data-slot="preview-html" />
+    if (preview.xml) return <pre className="max-h-96 overflow-auto rounded bg-muted p-3 text-[11px] leading-tight" data-slot="preview-xml">{preview.xml}</pre>
+    return null
+}