@asteby/metacore-runtime-react 28.4.1 → 28.5.0

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),
+        [visibleFields, formLayout],
+    )
+    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>
+    )
+}

package/src/form-layout.ts

@@ -0,0 +1,116 @@
+// Declarative form layout (kernel PR #230): a model's create/edit form can
+// declare `form_layout` to group its fields into named sections, rendered either
+// as stacked (optionally collapsible) SECTIONS or as a multi-step WIZARD.
+//
+// Wire shape served on the table/modal metadata:
+//   form_layout: {
+//     mode: "sections" | "steps",              // default "sections"
+//     sections: [{ key, title?, description?, collapsed? }]
+//   }
+// and, per field/column: `section: "<key>"` referencing a section key.
+//
+// This module owns the PURE grouping logic (no React), so the two renderers
+// (`dynamic-form.tsx`, `dialogs/dynamic-record.tsx`) share one tested
+// implementation and the modal-render machinery never has to be booted under
+// happy-dom just to assert the grouping (same approach as PR #673).
+
+/** One declared section of a model form. `title`/`description` arrive already
+ * localized from the kernel and are rendered verbatim. */
+export interface FormSection {
+    key: string
+    title?: string
+    description?: string
+    /** Sections mode only: render this section collapsed on first paint. */
+    collapsed?: boolean
+}
+
+/** Model-level layout directive. `mode` defaults to `"sections"`. */
+export interface FormLayout {
+    mode?: 'sections' | 'steps'
+    sections?: FormSection[]
+}
+
+/** A resolved group of fields ready to render: a section plus the (already
+ * visibility-filtered) fields that belong to it. */
+export interface FieldGroup<F> {
+    /** Section key, or `__default__` for the orphan group. */
+    key: string
+    title?: string
+    description?: string
+    collapsed?: boolean
+    /** True for the synthetic group holding section-less / unknown-section fields. */
+    isDefault: boolean
+    fields: F[]
+}
+
+/** The synthetic key of the orphan group (fields with no / unknown `section`). */
+export const DEFAULT_SECTION_KEY = '__default__'
+
+/** Reads a field's `section` reference, tolerating a camelCase alias. */
+export function getFieldSection(
+    field: { section?: string; Section?: string } | null | undefined,
+): string | undefined {
+    if (!field) return undefined
+    const s = field.section ?? (field as { Section?: string }).Section
+    return typeof s === 'string' && s !== '' ? s : undefined
+}
+
+/**
+ * Groups already-filtered (visible) fields by their `section`, honoring the
+ * order of `layout.sections`.
+ *
+ * Contract:
+ *  - No `layout` (or no `sections`) → a single default group carrying every
+ *    field in its original order. Callers render this exactly like the legacy
+ *    flat list, so the layout-less path is byte-for-byte the current behaviour.
+ *  - Fields whose `section` is empty or references an UNKNOWN section key are
+ *    collected into ONE default group placed FIRST (before any declared
+ *    section) — the consistent, documented choice: general/uncategorized fields
+ *    lead, declared sections follow in their authored order.
+ *  - A declared section with zero visible fields is OMITTED entirely, so a
+ *    section whose only members are hidden by `visible_when` never renders an
+ *    empty shell (and never yields an empty wizard step). Because the caller
+ *    passes the already visibility-filtered list, this falls out for free.
+ */
+export function groupFieldsBySection<F extends { section?: string }>(
+    fields: F[],
+    layout: FormLayout | undefined,
+): FieldGroup<F>[] {
+    if (!layout?.sections?.length) {
+        return [{ key: DEFAULT_SECTION_KEY, isDefault: true, fields }]
+    }
+
+    const known = new Set(layout.sections.map((s) => s.key))
+    const bySection = new Map<string, F[]>()
+    const orphans: F[] = []
+
+    for (const f of fields) {
+        const sec = getFieldSection(f)
+        if (sec && known.has(sec)) {
+            const arr = bySection.get(sec)
+            if (arr) arr.push(f)
+            else bySection.set(sec, [f])
+        } else {
+            orphans.push(f)
+        }
+    }
+
+    const groups: FieldGroup<F>[] = []
+    // Orphan/default group leads (fields with no / unknown section).
+    if (orphans.length) {
+        groups.push({ key: DEFAULT_SECTION_KEY, isDefault: true, fields: orphans })
+    }
+    for (const s of layout.sections) {
+        const secFields = bySection.get(s.key)
+        if (!secFields || secFields.length === 0) continue // hide empty section
+        groups.push({
+            key: s.key,
+            title: s.title,
+            description: s.description,
+            collapsed: s.collapsed,
+            isDefault: false,
+            fields: secFields,
+        })
+    }
+    return groups
+}

package/src/index.ts

@@ -107,6 +107,8 @@ export {
     type UseDynamicFiltersResult,
 } from './use-dynamic-filters'
 export * from './dynamic-form'
+export * from './form-layout'
+export * from './form-layout-ui'
 export { FieldGrid, FieldCell, FieldLabel } from './field-grid'
 export {
     ActionModalDispatcher,

package/src/types.ts

@@ -306,6 +306,12 @@ export interface ColumnDefinition {
     visible_when?: VisibleWhen
     /** camelCase alias for `visible_when`. */
     visibleWhen?: VisibleWhen
+    /**
+     * Form-layout membership: the key of the `form_layout` section this column's
+     * modal field belongs to (kernel PR #230). Absent → the default group. See
+     * `groupFieldsBySection`.
+     */
+    section?: string
 }
 
 /**
@@ -529,6 +535,12 @@ export interface ActionFieldDef {
     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 field lands in the default
+     * group. See `groupFieldsBySection`.
+     */
+    section?: string
 }
 
 /**