@asteby/metacore-runtime-react 13.2.0 → 13.4.0

package/src/__tests__/line-item-totals.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest'
+import {
+    computeLineItemTotals,
+    evaluateBalance,
+    getBalanceRule,
+} from '../dynamic-form-schema'
+import type { ActionFieldDef } from '../types'
+
+// A journal-entry-style line-items field: debit/credit columns flagged for
+// summation, reconciled by a balance rule. The functions are domain-agnostic;
+// this just exercises the canonical use case.
+const journalField = (overrides: Partial<ActionFieldDef> = {}): ActionFieldDef => ({
+    key: 'journal_entry_lines',
+    label: 'Renglones',
+    type: 'array',
+    required: true,
+    itemFields: [
+        { key: 'account_id', label: 'Cuenta', type: 'dynamic_select', ref: 'Account', required: true },
+        { key: 'description', label: 'Descripción', type: 'string' },
+        { key: 'debit', label: 'Débito', type: 'number', total: true },
+        { key: 'credit', label: 'Crédito', type: 'number', total: true },
+    ],
+    balance: { debit_column: 'debit', credit_column: 'credit' },
+    ...overrides,
+})
+
+describe('computeLineItemTotals', () => {
+    it('suma solo las columnas marcadas con total', () => {
+        const rows = [
+            { account_id: 'a', debit: '100', credit: '' },
+            { account_id: 'b', debit: '50.50', credit: '' },
+            { account_id: 'c', debit: '', credit: '150.50' },
+        ]
+        const totals = computeLineItemTotals(journalField(), rows)
+        expect(totals).toEqual({ debit: 150.5, credit: 150.5 })
+    })
+
+    it('trata blancos y basura como 0 y redondea a centavos', () => {
+        const rows = [
+            { debit: '0.1', credit: '' },
+            { debit: '0.2', credit: 'abc' },
+        ]
+        const totals = computeLineItemTotals(journalField(), rows)
+        expect(totals.debit).toBe(0.3) // sin float drift (0.30000000000000004)
+        expect(totals.credit).toBe(0)
+    })
+
+    it('devuelve {} cuando ninguna columna está marcada', () => {
+        const field = journalField({
+            itemFields: [{ key: 'x', label: 'X', type: 'number' }],
+        })
+        expect(computeLineItemTotals(field, [{ x: '5' }])).toEqual({})
+    })
+})
+
+describe('getBalanceRule', () => {
+    it('normaliza snake_case del kernel a camelCase', () => {
+        const rule = getBalanceRule(journalField())
+        expect(rule).toEqual({
+            debitColumn: 'debit',
+            creditColumn: 'credit',
+            message: undefined,
+            requireNonzero: true,
+        })
+    })
+
+    it('respeta camelCase explícito y require_nonzero=false', () => {
+        const rule = getBalanceRule(
+            journalField({ balance: { debitColumn: 'd', creditColumn: 'c', require_nonzero: false } }),
+        )
+        expect(rule?.debitColumn).toBe('d')
+        expect(rule?.requireNonzero).toBe(false)
+    })
+
+    it('devuelve undefined sin regla', () => {
+        expect(getBalanceRule(journalField({ balance: undefined }))).toBeUndefined()
+    })
+})
+
+describe('evaluateBalance', () => {
+    it('marca balanced cuando Σdébito == Σcrédito y > 0', () => {
+        const rows = [
+            { debit: '100', credit: '' },
+            { debit: '', credit: '100' },
+        ]
+        const state = evaluateBalance(journalField(), rows)
+        expect(state).toMatchObject({ debit: 100, credit: 100, diff: 0, balanced: true })
+    })
+
+    it('marca unbalanced con descuadre y reporta el diff', () => {
+        const rows = [
+            { debit: '100', credit: '' },
+            { debit: '', credit: '70' },
+        ]
+        const state = evaluateBalance(journalField(), rows)
+        expect(state?.balanced).toBe(false)
+        expect(state?.diff).toBe(-30) // credit - debit
+    })
+
+    it('un asiento todo en cero NO está cuadrado (require_nonzero por defecto)', () => {
+        const state = evaluateBalance(journalField(), [{ debit: '', credit: '' }])
+        expect(state?.balanced).toBe(false)
+    })
+
+    it('con require_nonzero=false, cero == cero está cuadrado', () => {
+        const field = journalField({
+            balance: { debit_column: 'debit', credit_column: 'credit', require_nonzero: false },
+        })
+        const state = evaluateBalance(field, [{ debit: '', credit: '' }])
+        expect(state?.balanced).toBe(true)
+    })
+
+    it('devuelve undefined cuando el campo no declara balance', () => {
+        expect(evaluateBalance(journalField({ balance: undefined }), [])).toBeUndefined()
+    })
+})

package/src/dynamic-form-schema.ts

@@ -63,6 +63,97 @@ export function isLineItemsField(field: ActionFieldDef): boolean {
     return getItemFields(field).length > 0
 }
 
+/**
+ * Resolves the balance rule of a line-items field, tolerating both the
+ * camelCase authored shape and the snake_case the kernel serves. Returns
+ * normalized `{ debitColumn, creditColumn, message, requireNonzero }` or
+ * `undefined` when the field declares no balance constraint.
+ */
+export function getBalanceRule(
+    field: ActionFieldDef,
+): { debitColumn: string; creditColumn: string; message?: string; requireNonzero: boolean } | undefined {
+    const b = field.balance
+    if (!b) return undefined
+    const debitColumn = b.debitColumn ?? b.debit_column ?? ''
+    const creditColumn = b.creditColumn ?? b.credit_column ?? ''
+    if (!debitColumn || !creditColumn) return undefined
+    const reqRaw = b.requireNonzero ?? b.require_nonzero
+    return {
+        debitColumn,
+        creditColumn,
+        message: b.message,
+        requireNonzero: reqRaw === undefined ? true : !!reqRaw,
+    }
+}
+
+/** Coerces a cell value to a finite number, treating blanks/garbage as 0. */
+export function toNumber(v: unknown): number {
+    if (typeof v === 'number') return Number.isFinite(v) ? v : 0
+    if (typeof v === 'string') {
+        const n = parseFloat(v)
+        return Number.isFinite(n) ? n : 0
+    }
+    return 0
+}
+
+/**
+ * Sums each `total`-flagged column of a line-items field across its rows.
+ * Pure — no React — so the renderer and unit tests share one implementation.
+ * Returns a map of column key → summed value. Rounds to cents to avoid float
+ * drift (0.1 + 0.2 noise) that would make a genuinely balanced entry look off.
+ */
+export function computeLineItemTotals(
+    field: ActionFieldDef,
+    rows: any[] | undefined,
+): Record<string, number> {
+    const cols = getItemFields(field).filter((c) => c.total)
+    const totals: Record<string, number> = {}
+    for (const c of cols) totals[c.key] = 0
+    if (Array.isArray(rows)) {
+        for (const row of rows) {
+            for (const c of cols) totals[c.key] += toNumber(row?.[c.key])
+        }
+    }
+    for (const k of Object.keys(totals)) totals[k] = Math.round(totals[k] * 100) / 100
+    return totals
+}
+
+export interface BalanceState {
+    debit: number
+    credit: number
+    /** credit − debit, rounded to cents. Zero when balanced. */
+    diff: number
+    balanced: boolean
+    message?: string
+}
+
+/**
+ * Evaluates a line-items field's balance rule against its rows. Returns
+ * `undefined` when the field declares no balance rule. `balanced` is true when
+ * the two summed columns are equal (and, unless `requireNonzero` is false,
+ * strictly positive). Pure — drives both the indicator and the submit gate.
+ */
+export function evaluateBalance(
+    field: ActionFieldDef,
+    rows: any[] | undefined,
+): BalanceState | undefined {
+    const rule = getBalanceRule(field)
+    if (!rule) return undefined
+    let debit = 0
+    let credit = 0
+    if (Array.isArray(rows)) {
+        for (const row of rows) {
+            debit += toNumber(row?.[rule.debitColumn])
+            credit += toNumber(row?.[rule.creditColumn])
+        }
+    }
+    debit = Math.round(debit * 100) / 100
+    credit = Math.round(credit * 100) / 100
+    const diff = Math.round((credit - debit) * 100) / 100
+    const balanced = diff === 0 && (!rule.requireNonzero || debit > 0)
+    return { debit, credit, diff, balanced, message: rule.message }
+}
+
 function fieldToZod(field: ActionFieldDef): ZodTypeAny {
     // Repeatable line-items group → array of row objects, each row built from
     // the item field columns. Required keeps at least one row.
@@ -119,6 +210,9 @@ export function resolveWidget(field: ActionFieldDef): string {
     switch (field.type) {
         case 'textarea': return 'textarea'
         case 'select': return 'select'
+        // Async searchable single-select against /api/options/<ref>. The
+        // declarative replacement for typing a raw FK UUID.
+        case 'dynamic_select': return 'dynamic_select'
         case 'boolean': return 'switch'
         case 'number': return 'number'
         case 'date': return 'date'

package/src/dynamic-form.tsx

@@ -15,12 +15,19 @@ import {
     SelectValue,
 } from '@asteby/metacore-ui/primitives'
 import type { ActionFieldDef } from './types'
-import { buildZodSchema, resolveWidget, isLineItemsField } from './dynamic-form-schema'
+import {
+    buildZodSchema,
+    resolveWidget,
+    isLineItemsField,
+    evaluateBalance,
+} from './dynamic-form-schema'
 import { useOptionsResolver, type ResolvedOption } from './use-options-resolver'
 import { DynamicLineItems } from './dynamic-line-items'
+import { DynamicSelectField } from './dynamic-select-field'
 
 export { buildZodSchema, resolveWidget }
 export { DynamicLineItems } from './dynamic-line-items'
+export { DynamicSelectField } from './dynamic-select-field'
 
 export interface DynamicFormProps {
     fields: ActionFieldDef[]
@@ -47,6 +54,18 @@ export function DynamicForm({
 
     const schema = useMemo(() => buildZodSchema(fields), [fields])
 
+    // Line-items fields carrying a balance rule gate submit: an unbalanced entry
+    // (Σdebit ≠ Σcredit, or all-zero when require_nonzero) can't be saved. This
+    // is fully declarative — `evaluateBalance` returns undefined for fields with
+    // no rule, so non-balanced forms are unaffected.
+    const balanceBlocked = useMemo(() => {
+        for (const f of fields) {
+            const state = evaluateBalance(f, values[f.key])
+            if (state && !state.balanced) return true
+        }
+        return false
+    }, [fields, values])
+
     useEffect(() => {
         const defaults: Record<string, any> = {}
         for (const f of fields) {
@@ -65,6 +84,7 @@ export function DynamicForm({
 
     const handleSubmit = async (e: React.FormEvent) => {
         e.preventDefault()
+        if (balanceBlocked) return
         const result = schema.safeParse(values)
         if (!result.success) {
             const next: Record<string, string> = {}
@@ -80,31 +100,48 @@ export function DynamicForm({
         try { await onSubmit(result.data as Record<string, any>) } finally { setSubmitting(false) }
     }
 
+    // Layout: scalar header fields flow through a responsive 2-column grid;
+    // line-items grids (and textareas) span the full width so the row table /
+    // memo gets room. Mirrors the pro look of the federated journal modal but
+    // stays fully declarative — driven only by field shape.
     return (
         <form onSubmit={handleSubmit} className="grid gap-4">
-            {fields.map((field) => (
-                <div key={field.key} className="grid gap-2">
-                    <Label htmlFor={field.key}>
-                        {field.label}
-                        {field.required && <span className="text-red-500 ml-1">*</span>}
-                    </Label>
-                    <FieldRenderer
-                        field={field}
-                        value={values[field.key]}
-                        onChange={(v: any) => update(field.key, v)}
-                    />
-                    {errors[field.key] && (
-                        <span className="text-red-500 text-sm" role="alert">{errors[field.key]}</span>
-                    )}
-                </div>
-            ))}
+            <div className="grid gap-4 sm:grid-cols-2">
+                {fields.map((field) => {
+                    const fullWidth =
+                        isLineItemsField(field) ||
+                        resolveWidget(field) === 'textarea' ||
+                        resolveWidget(field) === 'richtext'
+                    return (
+                        <div
+                            key={field.key}
+                            className={'grid gap-2 ' + (fullWidth ? 'sm:col-span-2' : '')}
+                        >
+                            <Label htmlFor={field.key}>
+                                {field.label}
+                                {field.required && <span className="text-red-500 ml-1">*</span>}
+                            </Label>
+                            <FieldRenderer
+                                field={field}
+                                value={values[field.key]}
+                                onChange={(v: any) => update(field.key, v)}
+                            />
+                            {errors[field.key] && (
+                                <span className="text-red-500 text-sm" role="alert">{errors[field.key]}</span>
+                            )}
+                        </div>
+                    )
+                })}
+            </div>
             <div className="flex justify-end gap-2 pt-2">
                 {onCancel && (
                     <Button type="button" variant="outline" onClick={onCancel} disabled={submitting || disabled}>
                         {cancelLabel}
                     </Button>
                 )}
-                <Button type="submit" disabled={submitting || disabled}>{submitLabel}</Button>
+                <Button type="submit" disabled={submitting || disabled || balanceBlocked}>
+                    {submitLabel}
+                </Button>
             </div>
         </form>
     )
@@ -123,6 +160,12 @@ function FieldRenderer({ field, value, onChange }: FieldRendererProps) {
         return <DynamicLineItems field={field} value={value} onChange={onChange} />
     }
     const widget = resolveWidget(field)
+    // Async searchable picker (typeahead against /api/options/<ref>?q=…).
+    // Preferred for FK fields with large option sets — no UUID typing, no
+    // dumping every row into a plain <select>.
+    if (widget === 'dynamic_select') {
+        return <DynamicSelectField field={field} value={value} onChange={onChange} />
+    }
     // Ref-driven select: hook into useOptionsResolver so the canonical
     // /api/options/<ref>?field=id endpoint feeds the dropdown. This is
     // the path the kernel auto-derives for FK columns; legacy callers

package/src/dynamic-line-items.tsx

@@ -18,9 +18,16 @@ import {
     SelectTrigger,
     SelectValue,
 } from '@asteby/metacore-ui/primitives'
-import { Plus, Trash2 } from 'lucide-react'
+import { Plus, Trash2, Check } from 'lucide-react'
 import type { ActionFieldDef } from './types'
-import { resolveWidget, getItemFields } from './dynamic-form-schema'
+import {
+    resolveWidget,
+    getItemFields,
+    computeLineItemTotals,
+    evaluateBalance,
+    toNumber,
+} from './dynamic-form-schema'
+import { DynamicSelectField } from './dynamic-select-field'
 import { useOptionsResolver, type ResolvedOption } from './use-options-resolver'
 
 export interface DynamicLineItemsProps {
@@ -30,6 +37,14 @@ export interface DynamicLineItemsProps {
     disabled?: boolean
 }
 
+const fmtNumber = (n: number): string =>
+    n.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 })
+
+/** Numeric columns render right-aligned (debit/credit/amount feel). */
+function isNumericCol(col: ActionFieldDef): boolean {
+    return resolveWidget(col) === 'number'
+}
+
 function emptyRow(itemFields: ActionFieldDef[]): Record<string, any> {
     const row: Record<string, any> = {}
     for (const f of itemFields) {
@@ -42,11 +57,45 @@ export function DynamicLineItems({ field, value, onChange, disabled = false }: D
     const itemFields = getItemFields(field)
     const rows: any[] = Array.isArray(value) ? value : []
 
+    // Columns flagged `total` get a per-column sum in the footer; the balance
+    // rule (if any) reconciles two of them. Both are declarative & generic.
+    const totals = computeLineItemTotals(field, rows)
+    const totalKeys = itemFields.filter((c) => c.total).map((c) => c.key)
+    const hasTotals = totalKeys.length > 0
+    const balance = evaluateBalance(field, rows)
+
     const addRow = () => onChange([...rows, emptyRow(itemFields)])
     const removeRow = (idx: number) => onChange(rows.filter((_, i) => i !== idx))
     const updateCell = (idx: number, key: string, cellValue: any) =>
         onChange(rows.map((r, i) => (i === idx ? { ...r, [key]: cellValue } : r)))
 
+    // When a balance rule reconciles two columns (e.g. debit ↔ credit), typing
+    // into one clears the sibling on the same row — mirrors the federated modal
+    // UX so a line is never both a debit and a credit.
+    const balancePair: [string, string] | null = balance
+        ? (() => {
+              const f = getItemFields(field)
+              void f
+              const d = field.balance?.debitColumn ?? field.balance?.debit_column
+              const c = field.balance?.creditColumn ?? field.balance?.credit_column
+              return d && c ? [d, c] : null
+          })()
+        : null
+
+    const handleCell = (idx: number, key: string, cellValue: any) => {
+        if (balancePair && (key === balancePair[0] || key === balancePair[1])) {
+            const sibling = key === balancePair[0] ? balancePair[1] : balancePair[0]
+            const hasValue = toNumber(cellValue) > 0
+            onChange(
+                rows.map((r, i) =>
+                    i === idx ? { ...r, [key]: cellValue, ...(hasValue ? { [sibling]: '' } : {}) } : r,
+                ),
+            )
+            return
+        }
+        updateCell(idx, key, cellValue)
+    }
+
     return (
         <div className="grid gap-2" data-widget="line_items">
             <div className="overflow-x-auto rounded-md border">
@@ -54,7 +103,13 @@ export function DynamicLineItems({ field, value, onChange, disabled = false }: D
                     <thead className="bg-muted/50">
                         <tr>
                             {itemFields.map((col) => (
-                                <th key={col.key} className="px-3 py-2 text-left font-medium">
+                                <th
+                                    key={col.key}
+                                    className={
+                                        'px-3 py-2 font-medium ' +
+                                        (isNumericCol(col) ? 'text-right' : 'text-left')
+                                    }
+                                >
                                     {col.label}
                                     {col.required && <span className="text-red-500 ml-1">*</span>}
                                 </th>
@@ -80,7 +135,7 @@ export function DynamicLineItems({ field, value, onChange, disabled = false }: D
                                         <CellRenderer
                                             field={col}
                                             value={row?.[col.key]}
-                                            onChange={(v: any) => updateCell(idx, col.key, v)}
+                                            onChange={(v: any) => handleCell(idx, col.key, v)}
                                             disabled={disabled}
                                         />
                                     </td>
@@ -100,18 +155,80 @@ export function DynamicLineItems({ field, value, onChange, disabled = false }: D
                             </tr>
                         ))}
                     </tbody>
+                    {hasTotals && rows.length > 0 && (
+                        <tfoot className="border-t bg-muted/30">
+                            <tr>
+                                {itemFields.map((col, ci) => {
+                                    if (ci === 0) {
+                                        return (
+                                            <td
+                                                key={col.key}
+                                                className="px-3 py-2 text-left font-medium text-muted-foreground"
+                                            >
+                                                Totales
+                                            </td>
+                                        )
+                                    }
+                                    return (
+                                        <td
+                                            key={col.key}
+                                            className={
+                                                'px-3 py-2 ' +
+                                                (col.total
+                                                    ? 'text-right font-semibold tabular-nums'
+                                                    : '')
+                                            }
+                                        >
+                                            {col.total ? fmtNumber(totals[col.key] ?? 0) : null}
+                                        </td>
+                                    )
+                                })}
+                                <td />
+                            </tr>
+                        </tfoot>
+                    )}
                 </table>
             </div>
-            <div>
+            <div className="flex items-center justify-between gap-2">
                 <Button type="button" variant="outline" size="sm" onClick={addRow} disabled={disabled}>
                     <Plus className="mr-1 h-4 w-4" />
                     Agregar renglón
                 </Button>
+                {balance && <BalanceBadge state={balance} />}
             </div>
         </div>
     )
 }
 
+function BalanceBadge({
+    state,
+}: {
+    state: NonNullable<ReturnType<typeof evaluateBalance>>
+}) {
+    if (state.balanced) {
+        return (
+            <span
+                className="inline-flex items-center gap-1.5 rounded-md bg-primary/10 px-2.5 py-1 text-sm font-medium text-primary"
+                data-balance="balanced"
+                role="status"
+            >
+                <Check className="h-4 w-4" />
+                Cuadrado
+            </span>
+        )
+    }
+    const diff = Math.abs(state.diff)
+    return (
+        <span
+            className="inline-flex items-center gap-1.5 rounded-md bg-destructive/10 px-2.5 py-1 text-sm font-medium text-destructive"
+            data-balance="unbalanced"
+            role="status"
+        >
+            {state.message ?? `Descuadre: ${fmtNumber(diff)}`}
+        </span>
+    )
+}
+
 interface CellRendererProps {
     field: ActionFieldDef
     value: any
@@ -125,6 +242,11 @@ interface CellRendererProps {
 // a scalar widget).
 function CellRenderer({ field, value, onChange, disabled }: CellRendererProps) {
     const widget = resolveWidget(field)
+    // Async searchable picker per row cell — e.g. the account_id column of a
+    // journal entry's debit/credit lines. Same widget as the flat form.
+    if (widget === 'dynamic_select') {
+        return <DynamicSelectField field={field} value={value} onChange={onChange} />
+    }
     if (widget === 'select' && field.ref) {
         return <RefCell field={field} value={value} onChange={onChange} disabled={disabled} />
     }