@asteby/metacore-runtime-react 13.3.0 → 13.4.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @asteby/metacore-runtime-react
 
+## 13.4.0
+
+### Minor Changes
+
+- 23d737f: feat(runtime-react): rich declarative line-items — column totals, balance rule, pro layout
+
+  Makes the declarative form/modal renderer rich enough to replace a custom
+  federated modal for line-items entry (e.g. a journal entry's debit/credit grid),
+  driven entirely from the manifest:
+  - **Totals footer** — any `item_fields` column flagged `total: true` is summed
+    across rows and shown in a footer row (`computeLineItemTotals`). Numeric
+    columns render right-aligned with `tabular-nums`.
+  - **Balance rule** — a `type: "array"` field can declare
+    `balance: { debit_column, credit_column, message?, require_nonzero? }`. The
+    grid shows a live "Cuadrado" / "Descuadre: N" badge and the form blocks submit
+    until `Σ(debit_column) === Σ(credit_column)` (and, by default, > 0). Fully
+    generic — debit/credit are just the two column keys to reconcile. Typing a
+    value into one reconciled column clears its sibling on the same row.
+  - **Pro layout** — `DynamicForm` flows scalar header fields through a responsive
+    2-column grid while line-items grids and textareas span full width, matching
+    the look of the hand-written federated journal modal without any custom React.
+
+  New pure helpers (`computeLineItemTotals`, `evaluateBalance`, `getBalanceRule`,
+  `toNumber`) are exported and unit-tested so hosts can reuse the math. Mirrors the
+  kernel v3 `ActionField.total` / `ActionField.balance` contract additions.
+
 ## 13.3.0
 
 ### Minor Changes

package/dist/dynamic-form-schema.d.ts

@@ -17,5 +17,41 @@ export declare function buildZodSchema(fields: ActionFieldDef[]): z.ZodObject<{
 export declare function getItemFields(field: ActionFieldDef): ActionFieldDef[];
 /** A field is a repeatable line-items group when it declares item columns. */
 export declare function isLineItemsField(field: ActionFieldDef): boolean;
+/**
+ * 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 declare function getBalanceRule(field: ActionFieldDef): {
+    debitColumn: string;
+    creditColumn: string;
+    message?: string;
+    requireNonzero: boolean;
+} | undefined;
+/** Coerces a cell value to a finite number, treating blanks/garbage as 0. */
+export declare function toNumber(v: unknown): number;
+/**
+ * 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 declare function computeLineItemTotals(field: ActionFieldDef, rows: any[] | undefined): Record<string, number>;
+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 declare function evaluateBalance(field: ActionFieldDef, rows: any[] | undefined): BalanceState | undefined;
 export declare function resolveWidget(field: ActionFieldDef): string;
 //# sourceMappingURL=dynamic-form-schema.d.ts.map

package/dist/dynamic-form-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-form-schema.d.ts","sourceRoot":"","sources":["../src/dynamic-form-schema.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAmB,MAAM,KAAK,CAAA;AACxC,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,SAAS,CAAA;AAiB9D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS,GAAG,IAAI,CAEzF;AAcD,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE;;kBAMtD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,cAAc,EAAE,CAGrE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAE/D;AAqDD,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAa3D"}
+{"version":3,"file":"dynamic-form-schema.d.ts","sourceRoot":"","sources":["../src/dynamic-form-schema.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAmB,MAAM,KAAK,CAAA;AACxC,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,SAAS,CAAA;AAiB9D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS,GAAG,IAAI,CAEzF;AAcD,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE;;kBAMtD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,cAAc,EAAE,CAGrE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,cAAc,GACtB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAatG;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAO3C;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACjC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,GAAG,EAAE,GAAG,SAAS,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB;AAED,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,OAAO,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC3B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,GAAG,EAAE,GAAG,SAAS,GACxB,YAAY,GAAG,SAAS,CAgB1B;AAqDD,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAa3D"}

package/dist/dynamic-form-schema.js

@@ -57,6 +57,83 @@ export function getItemFields(field) {
 export function isLineItemsField(field) {
     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) {
+    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) {
+    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, rows) {
+    const cols = getItemFields(field).filter((c) => c.total);
+    const totals = {};
+    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;
+}
+/**
+ * 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, rows) {
+    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) {
     // Repeatable line-items group → array of row objects, each row built from
     // the item field columns. Required keeps at least one row.

package/dist/dynamic-form.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-form.d.ts","sourceRoot":"","sources":["../src/dynamic-form.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,aAAa,EAAoB,MAAM,uBAAuB,CAAA;AAKvF,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,CAAA;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAE3D,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACnC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,wBAAgB,WAAW,CAAC,EACxB,MAAM,EACN,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,WAAuB,EACvB,WAAwB,EACxB,QAAgB,GACnB,EAAE,gBAAgB,2CAoElB"}
+{"version":3,"file":"dynamic-form.d.ts","sourceRoot":"","sources":["../src/dynamic-form.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC7C,OAAO,EACH,cAAc,EACd,aAAa,EAGhB,MAAM,uBAAuB,CAAA;AAK9B,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,CAAA;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAE3D,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACnC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,wBAAgB,WAAW,CAAC,EACxB,MAAM,EACN,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,WAAuB,EACvB,WAAwB,EACxB,QAAgB,GACnB,EAAE,gBAAgB,2CAkGlB"}

package/dist/dynamic-form.js

@@ -4,7 +4,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // outside the full record-edit modal.
 import { useEffect, useMemo, useState } from 'react';
 import { Input, Textarea, Label, Switch, Button, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from '@asteby/metacore-ui/primitives';
-import { buildZodSchema, resolveWidget, isLineItemsField } from './dynamic-form-schema';
+import { buildZodSchema, resolveWidget, isLineItemsField, evaluateBalance, } from './dynamic-form-schema';
 import { useOptionsResolver } from './use-options-resolver';
 import { DynamicLineItems } from './dynamic-line-items';
 import { DynamicSelectField } from './dynamic-select-field';
@@ -16,6 +16,18 @@ export function DynamicForm({ fields, initialValues, onSubmit, onCancel, submitL
     const [errors, setErrors] = useState({});
     const [submitting, setSubmitting] = useState(false);
     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 = {};
         for (const f of fields) {
@@ -31,6 +43,8 @@ export function DynamicForm({ fields, initialValues, onSubmit, onCancel, submitL
     const update = (k, v) => setValues((prev) => ({ ...prev, [k]: v }));
     const handleSubmit = async (e) => {
         e.preventDefault();
+        if (balanceBlocked)
+            return;
         const result = schema.safeParse(values);
         if (!result.success) {
             const next = {};
@@ -51,7 +65,16 @@ export function DynamicForm({ fields, initialValues, onSubmit, onCancel, submitL
             setSubmitting(false);
         }
     };
-    return (_jsxs("form", { onSubmit: handleSubmit, className: "grid gap-4", children: [fields.map((field) => (_jsxs("div", { className: "grid gap-2", children: [_jsxs(Label, { htmlFor: field.key, children: [field.label, field.required && _jsx("span", { className: "text-red-500 ml-1", children: "*" })] }), _jsx(FieldRenderer, { field: field, value: values[field.key], onChange: (v) => update(field.key, v) }), errors[field.key] && (_jsx("span", { className: "text-red-500 text-sm", role: "alert", children: errors[field.key] }))] }, field.key))), _jsxs("div", { className: "flex justify-end gap-2 pt-2", children: [onCancel && (_jsx(Button, { type: "button", variant: "outline", onClick: onCancel, disabled: submitting || disabled, children: cancelLabel })), _jsx(Button, { type: "submit", disabled: submitting || disabled, children: submitLabel })] })] }));
+    // 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 (_jsxs("form", { onSubmit: handleSubmit, className: "grid gap-4", children: [_jsx("div", { className: "grid gap-4 sm:grid-cols-2", children: fields.map((field) => {
+                    const fullWidth = isLineItemsField(field) ||
+                        resolveWidget(field) === 'textarea' ||
+                        resolveWidget(field) === 'richtext';
+                    return (_jsxs("div", { className: 'grid gap-2 ' + (fullWidth ? 'sm:col-span-2' : ''), children: [_jsxs(Label, { htmlFor: field.key, children: [field.label, field.required && _jsx("span", { className: "text-red-500 ml-1", children: "*" })] }), _jsx(FieldRenderer, { field: field, value: values[field.key], onChange: (v) => update(field.key, v) }), errors[field.key] && (_jsx("span", { className: "text-red-500 text-sm", role: "alert", children: errors[field.key] }))] }, field.key));
+                }) }), _jsxs("div", { className: "flex justify-end gap-2 pt-2", children: [onCancel && (_jsx(Button, { type: "button", variant: "outline", onClick: onCancel, disabled: submitting || disabled, children: cancelLabel })), _jsx(Button, { type: "submit", disabled: submitting || disabled || balanceBlocked, children: submitLabel })] })] }));
 }
 function FieldRenderer({ field, value, onChange }) {
     // Repeatable line-items group → render the row grid. Its value is an array

package/dist/dynamic-line-items.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-line-items.d.ts","sourceRoot":"","sources":["../src/dynamic-line-items.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAK7C,MAAM,WAAW,qBAAqB;IAClC,KAAK,EAAE,cAAc,CAAA;IACrB,KAAK,EAAE,GAAG,EAAE,GAAG,SAAS,CAAA;IACxB,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAA;CACrB;AAUD,wBAAgB,gBAAgB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAgB,EAAE,EAAE,qBAAqB,2CAwEnG"}
+{"version":3,"file":"dynamic-line-items.d.ts","sourceRoot":"","sources":["../src/dynamic-line-items.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAW7C,MAAM,WAAW,qBAAqB;IAClC,KAAK,EAAE,cAAc,CAAA;IACrB,KAAK,EAAE,GAAG,EAAE,GAAG,SAAS,CAAA;IACxB,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAA;CACrB;AAkBD,wBAAgB,gBAAgB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAgB,EAAE,EAAE,qBAAqB,2CAiJnG"}

package/dist/dynamic-line-items.js

@@ -9,10 +9,15 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // row controls mutate the array; each cell is a widget resolved via
 // `resolveWidget`, matching the flat-field renderer in dynamic-form.tsx.
 import { Input, Textarea, Switch, Button, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from '@asteby/metacore-ui/primitives';
-import { Plus, Trash2 } from 'lucide-react';
-import { resolveWidget, getItemFields } from './dynamic-form-schema';
+import { Plus, Trash2, Check } from 'lucide-react';
+import { resolveWidget, getItemFields, computeLineItemTotals, evaluateBalance, toNumber, } from './dynamic-form-schema';
 import { DynamicSelectField } from './dynamic-select-field';
 import { useOptionsResolver } from './use-options-resolver';
+const fmtNumber = (n) => n.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+/** Numeric columns render right-aligned (debit/credit/amount feel). */
+function isNumericCol(col) {
+    return resolveWidget(col) === 'number';
+}
 function emptyRow(itemFields) {
     const row = {};
     for (const f of itemFields) {
@@ -23,10 +28,53 @@ function emptyRow(itemFields) {
 export function DynamicLineItems({ field, value, onChange, disabled = false }) {
     const itemFields = getItemFields(field);
     const rows = 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) => onChange(rows.filter((_, i) => i !== idx));
     const updateCell = (idx, key, cellValue) => onChange(rows.map((r, i) => (i === idx ? { ...r, [key]: cellValue } : r)));
-    return (_jsxs("div", { className: "grid gap-2", "data-widget": "line_items", children: [_jsx("div", { className: "overflow-x-auto rounded-md border", children: _jsxs("table", { className: "w-full text-sm", children: [_jsx("thead", { className: "bg-muted/50", children: _jsxs("tr", { children: [itemFields.map((col) => (_jsxs("th", { className: "px-3 py-2 text-left font-medium", children: [col.label, col.required && _jsx("span", { className: "text-red-500 ml-1", children: "*" })] }, col.key))), _jsx("th", { className: "w-12 px-3 py-2", "aria-label": "acciones" })] }) }), _jsxs("tbody", { children: [rows.length === 0 && (_jsx("tr", { children: _jsx("td", { colSpan: itemFields.length + 1, className: "px-3 py-4 text-center text-muted-foreground", children: "Sin renglones" }) })), rows.map((row, idx) => (_jsxs("tr", { className: "border-t align-top", children: [itemFields.map((col) => (_jsx("td", { className: "px-2 py-1.5", children: _jsx(CellRenderer, { field: col, value: row?.[col.key], onChange: (v) => updateCell(idx, col.key, v), disabled: disabled }) }, col.key))), _jsx("td", { className: "px-2 py-1.5 text-center", children: _jsx(Button, { type: "button", variant: "ghost", size: "icon", onClick: () => removeRow(idx), disabled: disabled, "aria-label": "Eliminar rengl\u00F3n", children: _jsx(Trash2, { className: "h-4 w-4 text-red-500" }) }) })] }, idx)))] })] }) }), _jsx("div", { children: _jsxs(Button, { type: "button", variant: "outline", size: "sm", onClick: addRow, disabled: disabled, children: [_jsx(Plus, { className: "mr-1 h-4 w-4" }), "Agregar rengl\u00F3n"] }) })] }));
+    // 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 = 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, key, cellValue) => {
+        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 (_jsxs("div", { className: "grid gap-2", "data-widget": "line_items", children: [_jsx("div", { className: "overflow-x-auto rounded-md border", children: _jsxs("table", { className: "w-full text-sm", children: [_jsx("thead", { className: "bg-muted/50", children: _jsxs("tr", { children: [itemFields.map((col) => (_jsxs("th", { className: 'px-3 py-2 font-medium ' +
+                                            (isNumericCol(col) ? 'text-right' : 'text-left'), children: [col.label, col.required && _jsx("span", { className: "text-red-500 ml-1", children: "*" })] }, col.key))), _jsx("th", { className: "w-12 px-3 py-2", "aria-label": "acciones" })] }) }), _jsxs("tbody", { children: [rows.length === 0 && (_jsx("tr", { children: _jsx("td", { colSpan: itemFields.length + 1, className: "px-3 py-4 text-center text-muted-foreground", children: "Sin renglones" }) })), rows.map((row, idx) => (_jsxs("tr", { className: "border-t align-top", children: [itemFields.map((col) => (_jsx("td", { className: "px-2 py-1.5", children: _jsx(CellRenderer, { field: col, value: row?.[col.key], onChange: (v) => handleCell(idx, col.key, v), disabled: disabled }) }, col.key))), _jsx("td", { className: "px-2 py-1.5 text-center", children: _jsx(Button, { type: "button", variant: "ghost", size: "icon", onClick: () => removeRow(idx), disabled: disabled, "aria-label": "Eliminar rengl\u00F3n", children: _jsx(Trash2, { className: "h-4 w-4 text-red-500" }) }) })] }, idx)))] }), hasTotals && rows.length > 0 && (_jsx("tfoot", { className: "border-t bg-muted/30", children: _jsxs("tr", { children: [itemFields.map((col, ci) => {
+                                        if (ci === 0) {
+                                            return (_jsx("td", { className: "px-3 py-2 text-left font-medium text-muted-foreground", children: "Totales" }, col.key));
+                                        }
+                                        return (_jsx("td", { className: 'px-3 py-2 ' +
+                                                (col.total
+                                                    ? 'text-right font-semibold tabular-nums'
+                                                    : ''), children: col.total ? fmtNumber(totals[col.key] ?? 0) : null }, col.key));
+                                    }), _jsx("td", {})] }) }))] }) }), _jsxs("div", { className: "flex items-center justify-between gap-2", children: [_jsxs(Button, { type: "button", variant: "outline", size: "sm", onClick: addRow, disabled: disabled, children: [_jsx(Plus, { className: "mr-1 h-4 w-4" }), "Agregar rengl\u00F3n"] }), balance && _jsx(BalanceBadge, { state: balance })] })] }));
+}
+function BalanceBadge({ state, }) {
+    if (state.balanced) {
+        return (_jsxs("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", children: [_jsx(Check, { className: "h-4 w-4" }), "Cuadrado"] }));
+    }
+    const diff = Math.abs(state.diff);
+    return (_jsx("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", children: state.message ?? `Descuadre: ${fmtNumber(diff)}` }));
 }
 // Per-cell widget. Mirrors the flat FieldRenderer in dynamic-form.tsx but
 // without the per-field Label (the column header is the label) and sized for a

package/dist/types.d.ts

@@ -131,6 +131,39 @@ export interface ActionFieldDef {
      * keyed by these item field keys. Rendered by `DynamicLineItems`.
      */
     itemFields?: ActionFieldDef[];
+    /**
+     * On an `itemFields` column: flags the column for summation in the
+     * line-items footer. The SDK renders a totals row summing every numeric
+     * column marked `total` (e.g. the debit and credit columns of a journal
+     * entry). Ignored on flat fields. Mirrors kernel v3 `ActionField.total`.
+     */
+    total?: boolean;
+    /**
+     * On a line-items (`type: "array"`) field: declares an optional, generic
+     * balance constraint between two summed columns. The SDK shows a balanced /
+     * out-of-balance indicator and blocks submit until the two sides match.
+     * Domain-agnostic — "debit"/"credit" are just the two column keys to
+     * reconcile. Mirrors kernel v3 `ActionField.balance`.
+     */
+    balance?: FieldBalanceRule;
+}
+/**
+ * Declarative reconciliation constraint on a line-items field: the summed value
+ * of `debitColumn` across all rows must equal the summed value of
+ * `creditColumn`. Tolerates the snake_case shape the kernel serves
+ * (`debit_column` / `credit_column` / `require_nonzero`). Generic by design.
+ */
+export interface FieldBalanceRule {
+    debitColumn?: string;
+    creditColumn?: string;
+    /** snake_case alias served by the kernel manifest. */
+    debit_column?: string;
+    /** snake_case alias served by the kernel manifest. */
+    credit_column?: string;
+    message?: string;
+    /** When true (default) an all-zero entry is treated as out of balance. */
+    requireNonzero?: boolean;
+    require_nonzero?: boolean;
 }
 export interface ActionDefinition {
     key: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "13.3.0",
+  "version": "13.4.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",

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.

package/src/dynamic-form.tsx

@@ -15,7 +15,12 @@ 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'
@@ -49,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) {
@@ -67,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> = {}
@@ -82,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>
     )

package/src/dynamic-line-items.tsx

@@ -18,9 +18,15 @@ 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'
 
@@ -31,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) {
@@ -43,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">
@@ -55,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>
@@ -81,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>
@@ -101,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

package/src/types.ts

@@ -146,6 +146,40 @@ export interface ActionFieldDef {
      * keyed by these item field keys. Rendered by `DynamicLineItems`.
      */
     itemFields?: ActionFieldDef[]
+    /**
+     * On an `itemFields` column: flags the column for summation in the
+     * line-items footer. The SDK renders a totals row summing every numeric
+     * column marked `total` (e.g. the debit and credit columns of a journal
+     * entry). Ignored on flat fields. Mirrors kernel v3 `ActionField.total`.
+     */
+    total?: boolean
+    /**
+     * On a line-items (`type: "array"`) field: declares an optional, generic
+     * balance constraint between two summed columns. The SDK shows a balanced /
+     * out-of-balance indicator and blocks submit until the two sides match.
+     * Domain-agnostic — "debit"/"credit" are just the two column keys to
+     * reconcile. Mirrors kernel v3 `ActionField.balance`.
+     */
+    balance?: FieldBalanceRule
+}
+
+/**
+ * Declarative reconciliation constraint on a line-items field: the summed value
+ * of `debitColumn` across all rows must equal the summed value of
+ * `creditColumn`. Tolerates the snake_case shape the kernel serves
+ * (`debit_column` / `credit_column` / `require_nonzero`). Generic by design.
+ */
+export interface FieldBalanceRule {
+    debitColumn?: string
+    creditColumn?: string
+    /** snake_case alias served by the kernel manifest. */
+    debit_column?: string
+    /** snake_case alias served by the kernel manifest. */
+    credit_column?: string
+    message?: string
+    /** When true (default) an all-zero entry is treated as out of balance. */
+    requireNonzero?: boolean
+    require_nonzero?: boolean
 }
 
 export interface ActionDefinition {