Schema

¿Qué es un schema?

Un schema describe declarativamente la estructura visual y funcional de un DyonaForm. Importá el componente y su tipo, definí un objeto y pasalo a schema:

import {
  DyonaForm,
  type DyonaFormSchema,
} from '@typhonsoftware/dyona-form';

const schema: DyonaFormSchema = {
  // ...
};

<DyonaForm schema={schema} />

DyonaForm recibe un objeto JavaScript o TypeScript con una estructura compatible con JSON; no recibe directamente un string JSON.

Estructura raíz

type DyonaFormSchema = {
  title: string;
  actions?: DyonaFormActionsConfig;
  tabs: DyonaFormTab[];
  hideSingleTab?: boolean;
};

• title es obligatorio, debe ser un string no vacío y es el título general del formulario.
• tabs es obligatorio, es un array de DyonaFormTab, debe contener al menos una tab y contiene la estructura principal del formulario.
• hideSingleTab es opcional y boolean. Si existe exactamente una tab y vale true, oculta solamente la barra visual de tabs; su contenido continúa renderizándose. Con dos o más tabs, las tabs siempre se muestran.
• actions es opcional y configura los botones propios del formulario. No es el Action Engine genérico de DYONA.

Jerarquía visual

DyonaFormSchema
    ↓
tabs[]
    ↓
rows[]
    ↓
columns[]
    ↓
DyonaFormField

Un schema contiene tabs; cada tab contiene rows; cada row contiene columns; y cada elemento de columns es un field.

Tabs

type DyonaFormTab = {
  id: string;
  title: string;
  helpUrl?: string;
  rows: DyonaFormRow[];
};

• id es obligatorio, debe ser un string no vacío y debe ser único dentro del schema.
• title es obligatorio, debe ser un string no vacío y es el texto visible de la tab.
• helpUrl es opcional, es un string y permite definir acceso a ayuda para esa sección.
• rows es el array de filas de la tab.

Rows y columns

type DyonaFormRow = {
  columns: DyonaFormField[];
};

Una row representa una fila lógica del formulario. columns es obligatorio, es un array y una row existente debe contener al menos un field. Cada elemento es un DyonaFormField.

El nombre público de la propiedad es columns, no fields.

rows: [
  {
    columns: [
      {name: 'firstName', label: 'Nombre', type: 'text'},
      {name: 'lastName', label: 'Apellido', type: 'text'},
    ],
  },
]

Fields: estructura básica

Las propiedades específicas de fields se documentan en Fields. En Schema, la estructura mínima es:

{name: 'name', label: 'Nombre', type: 'text'}

• name identifica el dato, debe ser un string no vacío y debe ser único en todo el formulario.
• label es el texto visible del field.
• type define qué control renderiza DYONA Form.

Los field types actuales son text, number, date, datetime, select, autocomplete, checkbox, textarea, email, password, link y label. Sus propiedades específicas se documentan en Fields.

Layout y grid

Un field puede definir su ancho responsive con grid:

grid: {xs: 12, md: 6}

xs, sm, md, lg y xl usan valores de 1 a 12.

Actions del formulario

type DyonaFormActionsConfig = {
  submit?: DyonaFormActionButtonConfig;
  back?: DyonaFormActionButtonConfig;
  custom?: DyonaFormCustomActionConfig[];
  disableOtherActionsWhileRunning?: boolean;
  layout?: 'horizontal' | 'vertical';
  wrap?: boolean;
};

type DyonaFormActionButtonConfig = {
  label?: string;
  icon?: string;
  shortcut?: string;
  tooltip?: string;
  variant?: 'text' | 'outlined' | 'contained';
  loadingLabel?: string;
  showSpinner?: boolean;
  cancelable?: boolean;
};

type DyonaFormCustomActionConfig = DyonaFormActionButtonConfig & {
  id: string;
  label: string;
  validate?: boolean;
};

actions: {
  submit: {label: 'Guardar', icon: 'Save', shortcut: 'Alt+G', tooltip: 'Guardar cambios'},
  back: {label: 'Volver', icon: 'ArrowBack'},
  custom: [{id: 'preview', label: 'Vista previa', validate: false}],
}

Estas actions configuran los botones propios submit y back y los botones custom de DyonaForm. No son instancias de DyonaAction ni pertenecen al Action Engine genérico. Consultá Actions del formulario para handlers, validación, ejecución asíncrona, cancelación, defaults y layout.

¿Qué no pertenece al schema?

Estas son props de DyonaForm, no propiedades del schema: locale, initialValues, onSubmit, onBack, onAction, styles y dataSourceExecutor.

<DyonaForm
  locale="..."
  schema={schema}
  initialValues={{...}}
  onSubmit={...}
  onAction={...}
/>

Esto separa la configuración declarativa del schema de la integración React del componente.

Ejemplo mínimo completo

const schema: DyonaFormSchema = {
  title: 'Cliente',
  hideSingleTab: true,
  tabs: [{
    id: 'general',
    title: 'General',
    rows: [{
      columns: [{name: 'name', label: 'Nombre', type: 'text', required: true}],
    }],
  }],
};

<DyonaForm locale="es" schema={schema} />

Ejemplo estructural

const schema: DyonaFormSchema = {
  title: 'Editor de cliente',
  tabs: [
    {
      id: 'general', title: 'General',
      rows: [
        {columns: [
          {name: 'firstName', label: 'Nombre', type: 'text', grid: {xs: 12, md: 6}},
          {name: 'lastName', label: 'Apellido', type: 'text', grid: {xs: 12, md: 6}},
        ]},
        {columns: [{name: 'email', label: 'Email', type: 'email'}]},
      ],
    },
    {
      id: 'preferences', title: 'Preferencias',
      rows: [{columns: [{name: 'newsletter', label: 'Recibir novedades', type: 'checkbox'}]}],
    },
  ],
  actions: {
    submit: {label: 'Guardar', icon: 'Save'},
    back: {label: 'Volver', icon: 'ArrowBack'},
  },
};

Schema como JSON

La misma estructura básica puede representarse con sintaxis JSON real:

{
  "title": "Cliente",
  "tabs": [{
    "id": "general",
    "title": "General",
    "rows": [{
      "columns": [{"name": "name", "label": "Nombre", "type": "text"}]
    }]
  }]
}

La estructura es compatible con JSON; la aplicación finalmente entrega el objeto resultante a schema.

Validación estructural

DYONA Form valida un schema antes del renderizado normal. Reglas estructurales útiles incluyen title obligatorio, al menos una tab, ids de tabs únicos, names de fields únicos en todo el formulario, field types soportados, columns válidas en rows y rechazo de propiedades incompatibles. Los códigos internos de validación no forman parte de esta guía.

Próximos pasos

• Fields — tipos y propiedades de fields.
• Validation — validación declarativa e integrada.
• Conditions — visibilidad y obligatoriedad condicional.
• Label — fields informativos visuales/no-data.