@asteby/metacore-runtime-react 28.4.1 → 28.6.0

package/src/dialogs/dynamic-record.tsx

@@ -54,6 +54,8 @@ import { DynamicRelations } from '../dynamic-relations'
 import { useOptionsResolver, type ResolvedOption } from '../use-options-resolver'
 import { getFieldRef, getVisibleWhen, evaluateVisibleWhen } from '../dynamic-form-schema'
 import type { VisibleWhen } from '../types'
+import { groupFieldsBySection, type FormLayout } from '../form-layout'
+import { FieldSection, WizardProgress } from '../form-layout-ui'
 import { FieldCell } from '../field-grid'
 import { isNilUuid, normalizeNilUuid } from '../nil-uuid'
 import { normalizeRefFieldsForSubmit } from './normalize-submit'
@@ -158,6 +160,12 @@ export interface FieldDef {
     visible_when?: VisibleWhen
     /** camelCase alias for `visible_when`. */
     visibleWhen?: VisibleWhen
+    /**
+     * Form-layout membership: the key of the `form_layout` section this field
+     * belongs to (kernel PR #230). Absent → the default group. See
+     * `groupFieldsBySection`.
+     */
+    section?: string
 }
 
 // Permissive shape: the wire payload may omit some fields (e.g. `title` is
@@ -175,6 +183,15 @@ interface ModalMetadata {
     createTitle?: string
     editTitle?: string
     fields?: FieldDef[]
+    /**
+     * Declarative form layout (kernel PR #230): groups the fields into named
+     * sections rendered stacked (`mode:"sections"`) or as a wizard
+     * (`mode:"steps"`). Absent → the legacy flat two-column grid. Tolerates the
+     * camelCase alias an app might author.
+     */
+    form_layout?: FormLayout
+    /** camelCase alias for `form_layout`. */
+    formLayout?: FormLayout
     /**
      * Backend-localized CRUD success messages (modal metadata). Preferred over
      * the raw response message which is not localized.
@@ -490,6 +507,29 @@ export function filterVisibleFields(
     })
 }
 
+// stripHiddenFieldValues drops from a flat form-values object the keys of any
+// declared field currently hidden by its `visible_when` predicate, so the
+// submit never POSTs a value the form isn't showing (e.g. a DiscountRule with
+// rule_scope=category must not send the product_id / customer_id it hides).
+// This mirrors dynamic-form.tsx, which builds its Zod schema only over the
+// visible fields — hidden fields are dropped from BOTH the render/required-gate
+// AND the submitted values. Keys with no matching declared field, or whose
+// field carries no `visible_when`, always pass through (retrocompat).
+export function stripHiddenFieldValues(
+    values: Record<string, any>,
+    fields: FieldDef[] | undefined,
+    mode: 'view' | 'edit' | 'create',
+): Record<string, any> {
+    const visibleKeys = new Set(filterVisibleFields(fields, mode, values).map(f => f.key))
+    const out: Record<string, any> = {}
+    for (const [key, value] of Object.entries(values)) {
+        const field = (fields ?? []).find(f => f.key === key)
+        if (field && !visibleKeys.has(key) && getVisibleWhen(field)) continue
+        out[key] = value
+    }
+    return out
+}
+
 export function DynamicRecordDialog({
     open,
     onOpenChange,
@@ -526,6 +566,8 @@ export function DynamicRecordDialog({
     const [loading, setLoading] = useState(false)
     const [saving, setSaving] = useState(false)
     const [deleting, setDeleting] = useState(false)
+    // Wizard step cursor (form_layout mode:"steps" only).
+    const [stepIndex, setStepIndex] = useState(0)
 
     const isCreate = mode === 'create'
     const isView = mode === 'view'
@@ -537,8 +579,10 @@ export function DynamicRecordDialog({
         if (!open) return
         if (!isCreate && !recordId) return
 
-        // Fresh open → drop any validation errors from a prior submit.
+        // Fresh open → drop any validation errors from a prior submit and reset
+        // the wizard to its first step.
         setFieldErrors({})
+        setStepIndex(0)
 
         let cancelled = false
 
@@ -752,9 +796,16 @@ export function DynamicRecordDialog({
         // Required check passed → clear any prior validation errors.
         setFieldErrors({})
 
+        // Fields hidden by their `visible_when` predicate must not be POSTed:
+        // the render, the required-gate and the payload all drive off the same
+        // filter, so a DiscountRule with scope=category never submits the
+        // product_id / customer_id it isn't showing. Mirrors dynamic-form.tsx,
+        // which builds its Zod only over visibleFields.
+        const submittedValues = stripHiddenFieldValues(formValues, modalMeta.fields, mode)
+
         // Empty reference pickers → null (not "" / nil-UUID) so nullable FK
         // columns accept them instead of raising a 23503 FK violation.
-        const payload = normalizeRefFieldsForSubmit(formValues, modalMeta.fields)
+        const payload = normalizeRefFieldsForSubmit(submittedValues, modalMeta.fields)
 
         setSaving(true)
         try {
@@ -829,6 +880,65 @@ export function DynamicRecordDialog({
 
     const visibleFields = filterVisibleFields(modalMeta?.fields, mode, formValues)
 
+    // Declarative form layout: group the (already visibility-filtered) fields by
+    // their section. Empty sections drop out for free. Steps mode only drives a
+    // wizard in editable modes — view mode always stacks the sections.
+    const formLayout = modalMeta?.form_layout ?? modalMeta?.formLayout
+    const groups = groupFieldsBySection(visibleFields, formLayout, formValues)
+    const isSteps = isEditable && formLayout?.mode === 'steps' && groups.length > 1
+    const clampedStep = Math.min(stepIndex, Math.max(groups.length - 1, 0))
+    const isLastStep = clampedStep === groups.length - 1
+
+    // Renders a list of fields into the shared two-column grid (each FieldCell
+    // gives min-w-0 so long values can't blow the columns past the dialog).
+    const renderFields = (groupFields: FieldDef[]) =>
+        groupFields.map(field => {
+            const isFullWidth =
+                field.type === 'textarea' ||
+                field.widget === 'textarea' ||
+                field.widget === 'richtext'
+            return (
+                <FieldCell key={field.key} fullWidth={isFullWidth}>
+                    <FieldRow
+                        field={field}
+                        record={record}
+                        value={formValues[field.key] ?? ''}
+                        mode={mode}
+                        error={fieldErrors[field.key]}
+                        onChange={val => {
+                            setFormValues((prev: Record<string, any>) => ({ ...prev, [field.key]: val }))
+                            setFieldErrors(prev => {
+                                if (!prev[field.key]) return prev
+                                const next = { ...prev }
+                                delete next[field.key]
+                                return next
+                            })
+                        }}
+                    />
+                </FieldCell>
+            )
+        })
+
+    // Wizard "Siguiente": gate only the CURRENT step's required (visible) fields,
+    // then advance. Mirrors handleSubmit's required check but scoped to the step.
+    const goNextStep = () => {
+        const step = groups[clampedStep]
+        const missing: Record<string, string> = {}
+        for (const field of step?.fields ?? []) {
+            if (field.required && !formValues[field.key] && formValues[field.key] !== 0 && formValues[field.key] !== false) {
+                missing[field.key] = localizeFieldIssue({ code: 'required' }, field.label, t)
+            }
+        }
+        if (Object.keys(missing).length) {
+            setFieldErrors(missing)
+            toast.error(t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }))
+            return
+        }
+        setFieldErrors({})
+        setStepIndex(Math.min(clampedStep + 1, groups.length - 1))
+    }
+    const goBackStep = () => setStepIndex(Math.max(clampedStep - 1, 0))
+
     return (
         <Dialog open={open} onOpenChange={onOpenChange}>
             <DialogContent className="sm:max-w-2xl max-h-[90vh] flex flex-col p-0 gap-0 overflow-hidden">
@@ -845,54 +955,42 @@ export function DynamicRecordDialog({
                         <ImageUrlContext.Provider value={getImageUrl}>
                         <TimeZoneContext.Provider value={timeZone}>
                         <CurrencyContext.Provider value={currency}>
-                            {/* The grid IS the form element (the footer submit
-                                button targets it by id). FieldCell gives each
+                            {/* The form element groups its fields by the declared
+                                form_layout (sections stacked, or the current
+                                wizard step). Without a layout this is a single
+                                default group rendered with no chrome — the legacy
+                                two-column grid, unchanged. FieldCell gives each
                                 cell `min-w-0` so a long select/input value can't
                                 blow the two columns past the dialog width. */}
                             <form
                                 id="dynamic-record-form"
                                 onSubmit={handleSubmit}
-                                className="grid grid-cols-1 gap-x-6 gap-y-4 sm:grid-cols-2"
+                                className="grid gap-y-4"
                             >
-                                {visibleFields.map(field => {
-                                    const isFullWidth =
-                                        field.type === 'textarea' ||
-                                        field.widget === 'textarea' ||
-                                        field.widget === 'richtext'
-                                    return (
-                                        <FieldCell key={field.key} fullWidth={isFullWidth}>
-                                            <FieldRow
-                                                field={field}
-                                                record={record}
-                                                value={formValues[field.key] ?? ''}
-                                                mode={mode}
-                                                error={fieldErrors[field.key]}
-                                                onChange={val => {
-                                                    setFormValues((prev: Record<string, any>) => ({ ...prev, [field.key]: val }))
-                                                    // Clear this field's error as soon as the user edits it.
-                                                    setFieldErrors(prev => {
-                                                        if (!prev[field.key]) return prev
-                                                        const next = { ...prev }
-                                                        delete next[field.key]
-                                                        return next
-                                                    })
-                                                }}
-                                            />
-                                        </FieldCell>
-                                    )
-                                })}
+                                {isSteps && (
+                                    <WizardProgress groups={groups} stepIndex={clampedStep} />
+                                )}
+                                {(isSteps ? [groups[clampedStep]] : groups).map(group => (
+                                    <FieldSection key={group.key} group={group}>
+                                        <div className="grid grid-cols-1 gap-x-6 gap-y-4 sm:grid-cols-2">
+                                            {renderFields(group.fields)}
+                                        </div>
+                                    </FieldSection>
+                                ))}
 
                                 {record?.external_url && (
-                                    <div className="sm:col-span-2 min-w-0">
-                                        <a
-                                            href={record.external_url}
-                                            target="_blank"
-                                            rel="noreferrer"
-                                            className="inline-flex items-center gap-1.5 text-sm text-primary hover:underline mt-1"
-                                        >
-                                            <ExternalLink className="h-3.5 w-3.5" />
-                                            Ver en {record.external_provider ?? 'proveedor externo'}
-                                        </a>
+                                    <div className="grid grid-cols-1 sm:grid-cols-2">
+                                        <div className="sm:col-span-2 min-w-0">
+                                            <a
+                                                href={record.external_url}
+                                                target="_blank"
+                                                rel="noreferrer"
+                                                className="inline-flex items-center gap-1.5 text-sm text-primary hover:underline mt-1"
+                                            >
+                                                <ExternalLink className="h-3.5 w-3.5" />
+                                                Ver en {record.external_provider ?? 'proveedor externo'}
+                                            </a>
+                                        </div>
                                     </div>
                                 )}
                             </form>
@@ -933,9 +1031,17 @@ export function DynamicRecordDialog({
                         </Button>
                     ) : <span />}
                     <div className="flex items-center gap-2">
-                        <Button variant="outline" onClick={() => onOpenChange(false)} disabled={saving || deleting}>
-                            {config.cancelLabel}
-                        </Button>
+                        {/* Wizard "Anterior" replaces Cancel from the second step
+                            on; the first step still shows Cancel. */}
+                        {isSteps && clampedStep > 0 ? (
+                            <Button variant="outline" onClick={goBackStep} disabled={saving || deleting}>
+                                Anterior
+                            </Button>
+                        ) : (
+                            <Button variant="outline" onClick={() => onOpenChange(false)} disabled={saving || deleting}>
+                                {config.cancelLabel}
+                            </Button>
+                        )}
                         {isView && onDelete && (
                             <Button
                                 variant="destructive"
@@ -951,7 +1057,15 @@ export function DynamicRecordDialog({
                                 Editar
                             </Button>
                         )}
-                        {isEditable && (
+                        {/* Non-final wizard step → "Siguiente" validates the step
+                            and advances instead of submitting. The last step (and
+                            every non-wizard form) keeps the real submit button. */}
+                        {isEditable && isSteps && !isLastStep && (
+                            <Button type="button" onClick={goNextStep} disabled={saving || loading}>
+                                Siguiente
+                            </Button>
+                        )}
+                        {isEditable && (!isSteps || isLastStep) && (
                             <Button
                                 type="submit"
                                 form="dynamic-record-form"

package/src/dynamic-form.tsx

@@ -2,6 +2,8 @@
 // pattern + ActionFieldDef renderer so callers can reuse the form layout
 // outside the full record-edit modal.
 import { useEffect, useMemo, useState } from 'react'
+import { groupFieldsBySection, type FormLayout } from './form-layout'
+import { FieldSection, WizardProgress } from './form-layout-ui'
 import {
     Input,
     Textarea,
@@ -47,6 +49,14 @@ export interface DynamicFormProps {
     submitLabel?: string
     cancelLabel?: string
     disabled?: boolean
+    /**
+     * Declarative form layout served on the model metadata (kernel PR #230).
+     * When present the visible fields are grouped by their `section` respecting
+     * `sections` order: `mode:"sections"` stacks (optionally collapsible)
+     * sections; `mode:"steps"` renders a Anterior/Siguiente wizard. Absent → the
+     * legacy flat list (unchanged).
+     */
+    formLayout?: FormLayout
 }
 
 export function DynamicForm({
@@ -57,6 +67,7 @@ export function DynamicForm({
     submitLabel = 'Guardar',
     cancelLabel = 'Cancelar',
     disabled = false,
+    formLayout,
 }: DynamicFormProps) {
     const [values, setValues] = useState<Record<string, any>>({})
     const [errors, setErrors] = useState<Record<string, string>>({})
@@ -97,6 +108,23 @@ export function DynamicForm({
         return false
     }, [visibleFields, values])
 
+    // Group visible fields by their form_layout section (empty sections drop out
+    // because visibleFields is already visibility-filtered). Without a layout
+    // this is a single default group → the render below collapses to the legacy
+    // flat grid, byte-for-byte.
+    const groups = useMemo(
+        () => groupFieldsBySection(visibleFields, formLayout, values),
+        [visibleFields, formLayout, values],
+    )
+    const isSteps = formLayout?.mode === 'steps' && groups.length > 1
+
+    // Wizard step cursor (steps mode only). Clamped whenever the group count
+    // shrinks (a visible_when flip can empty a trailing step's section).
+    const [stepIndex, setStepIndex] = useState(0)
+    useEffect(() => {
+        setStepIndex((i) => Math.min(i, Math.max(groups.length - 1, 0)))
+    }, [groups.length])
+
     useEffect(() => {
         const defaults: Record<string, any> = {}
         for (const f of editableFields) {
@@ -131,25 +159,93 @@ export function DynamicForm({
         try { await onSubmit(result.data as Record<string, any>) } finally { setSubmitting(false) }
     }
 
+    // Renders one group's fields into the responsive 2-column grid: scalar
+    // header fields flow through it; line-items grids (and textareas) span full
+    // width so the row table / memo gets room. Shared by every layout mode.
+    const renderGrid = (groupFields: ActionFieldDef[]) => (
+        <div className="grid gap-4 sm:grid-cols-2">
+            {groupFields.map((field) => (
+                <FieldRow
+                    key={field.key}
+                    field={field}
+                    value={values[field.key]}
+                    onChange={(v: any) => update(field.key, v)}
+                    values={values}
+                    error={errors[field.key]}
+                    initialValues={initialValues}
+                />
+            ))}
+        </div>
+    )
+
+    // ── Steps (wizard) mode ────────────────────────────────────────────────
+    // One step per section; Anterior/Siguiente navigate, submit only on the
+    // last step. Advancing validates just the current step's fields so a later
+    // step can't be blocked by an earlier untouched one and vice-versa.
+    if (isSteps) {
+        const step = groups[stepIndex]
+        const isLast = stepIndex === groups.length - 1
+
+        const goNext = () => {
+            const stepSchema = buildZodSchema(step.fields)
+            const result = stepSchema.safeParse(values)
+            if (!result.success) {
+                const next: Record<string, string> = {}
+                for (const issue of result.error.issues) {
+                    const key = issue.path[0]
+                    if (typeof key === 'string' && !next[key]) next[key] = issue.message
+                }
+                setErrors(next)
+                return
+            }
+            setErrors({})
+            setStepIndex((i) => Math.min(i + 1, groups.length - 1))
+        }
+        const goBack = () => setStepIndex((i) => Math.max(i - 1, 0))
+
+        return (
+            <form onSubmit={handleSubmit} className="grid gap-4">
+                <WizardProgress groups={groups} stepIndex={stepIndex} />
+                {renderGrid(step.fields)}
+                <div className="flex justify-between gap-2 pt-2">
+                    {stepIndex > 0 ? (
+                        <Button type="button" variant="outline" onClick={goBack} disabled={submitting || disabled}>
+                            Anterior
+                        </Button>
+                    ) : onCancel ? (
+                        <Button type="button" variant="outline" onClick={onCancel} disabled={submitting || disabled}>
+                            {cancelLabel}
+                        </Button>
+                    ) : (
+                        <span />
+                    )}
+                    {isLast ? (
+                        <Button type="submit" disabled={submitting || disabled || balanceBlocked}>
+                            {submitLabel}
+                        </Button>
+                    ) : (
+                        <Button type="button" onClick={goNext} disabled={submitting || disabled}>
+                            Siguiente
+                        </Button>
+                    )}
+                </div>
+            </form>
+        )
+    }
+
+    // ── Sections / flat mode ───────────────────────────────────────────────
     // 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.
+    // stays fully declarative — driven only by field shape. With no layout this
+    // is a single default group rendered without section chrome (unchanged).
     return (
         <form onSubmit={handleSubmit} className="grid gap-4">
-            <div className="grid gap-4 sm:grid-cols-2">
-                {visibleFields.map((field) => (
-                    <FieldRow
-                        key={field.key}
-                        field={field}
-                        value={values[field.key]}
-                        onChange={(v: any) => update(field.key, v)}
-                        values={values}
-                        error={errors[field.key]}
-                        initialValues={initialValues}
-                    />
-                ))}
-            </div>
+            {groups.map((group) => (
+                <FieldSection key={group.key} group={group}>
+                    {renderGrid(group.fields)}
+                </FieldSection>
+            ))}
             <div className="flex justify-end gap-2 pt-2">
                 {onCancel && (
                     <Button type="button" variant="outline" onClick={onCancel} disabled={submitting || disabled}>

package/src/form-layout-ui.tsx

@@ -0,0 +1,117 @@
+// Presentational chrome for declarative form layouts (see `form-layout.ts`).
+// Kept apart from the grouping logic so the pure helper stays React-free and the
+// two renderers (`dynamic-form.tsx`, `dialogs/dynamic-record.tsx`) share one
+// look for sections and the wizard progress bar.
+import { useState } from 'react'
+import {
+    Collapsible,
+    CollapsibleContent,
+    CollapsibleTrigger,
+    Button,
+} from '@asteby/metacore-ui/primitives'
+import { ChevronDown } from 'lucide-react'
+import type { FieldGroup } from './form-layout'
+
+/**
+ * Section chrome for `mode: "sections"`. Wraps a group's (already gridded)
+ * fields in a titled block.
+ *  - The default/orphan group renders with NO chrome, so a layout-less form (one
+ *    default group) is visually identical to the legacy flat list.
+ *  - A section whose `collapsed` is defined (true/false) is rendered COLLAPSIBLE,
+ *    starting collapsed when `collapsed === true`. A section with no `collapsed`
+ *    flag renders as a plain, always-open titled block.
+ */
+export function FieldSection({
+    group,
+    children,
+}: {
+    group: FieldGroup<unknown>
+    children: React.ReactNode
+}) {
+    const collapsible = group.collapsed !== undefined
+    const [open, setOpen] = useState(!group.collapsed)
+
+    if (group.isDefault) return <>{children}</>
+
+    const header = (
+        <div className="min-w-0 text-left">
+            {group.title && (
+                <h3 className="text-sm font-semibold leading-none">{group.title}</h3>
+            )}
+            {group.description && (
+                <p className="pt-1 text-sm text-muted-foreground">{group.description}</p>
+            )}
+        </div>
+    )
+
+    if (!collapsible) {
+        return (
+            <section className="grid gap-3">
+                {(group.title || group.description) && header}
+                {children}
+            </section>
+        )
+    }
+
+    return (
+        <Collapsible open={open} onOpenChange={setOpen} className="grid gap-3">
+            <CollapsibleTrigger asChild>
+                <Button
+                    type="button"
+                    variant="ghost"
+                    className="h-auto w-full justify-between px-0 py-1 hover:bg-transparent"
+                >
+                    {header}
+                    <ChevronDown
+                        className={
+                            'h-4 w-4 shrink-0 transition-transform ' + (open ? 'rotate-180' : '')
+                        }
+                    />
+                </Button>
+            </CollapsibleTrigger>
+            <CollapsibleContent className="grid gap-3">{children}</CollapsibleContent>
+        </Collapsible>
+    )
+}
+
+/**
+ * Progress bar for `mode: "steps"`: one filled segment per completed/current
+ * step plus a "Paso i/n · <title>" caption. Mirrors the WizardActionModal look
+ * so a model wizard and an action wizard read the same.
+ */
+export function WizardProgress({
+    groups,
+    stepIndex,
+    stepLabel = 'Paso',
+}: {
+    groups: FieldGroup<unknown>[]
+    stepIndex: number
+    stepLabel?: string
+}) {
+    const current = groups[stepIndex]
+    return (
+        <div className="pt-2">
+            <div className="flex items-center gap-1.5" role="list" aria-label="progress">
+                {groups.map((g, i) => (
+                    <div
+                        key={g.key}
+                        role="listitem"
+                        aria-current={i === stepIndex ? 'step' : undefined}
+                        className="h-1.5 flex-1 rounded-full"
+                        style={{
+                            backgroundColor:
+                                i <= stepIndex ? 'hsl(var(--primary))' : 'hsl(var(--muted))',
+                        }}
+                    />
+                ))}
+            </div>
+            <p className="pt-2 text-sm text-muted-foreground">
+                {stepLabel} {stepIndex + 1}/{groups.length}
+                {current?.title ? ` · ${current.title}` : ''}
+            </p>
+            {current?.description && (
+                <p className="pt-1 text-sm text-muted-foreground">{current.description}</p>
+            )}
+        </div>
+    )
+}