Schema

O que é um schema?

Um schema descreve declarativamente a estrutura visual e funcional de um DyonaForm. Importe o componente e seu tipo, defina um objeto e passe-o para schema:

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

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

<DyonaForm schema={schema} />

DyonaForm recebe um objeto JavaScript ou TypeScript com uma estrutura compatível com JSON; ele não recebe diretamente uma string JSON.

Estrutura raiz

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

• title é obrigatório, deve ser uma string não vazia e é o título geral do formulário.
• tabs é obrigatório, é um array de DyonaFormTab, deve conter pelo menos uma tab e contém a estrutura principal do formulário.
• hideSingleTab é opcional e booleano. Quando existe exatamente uma tab e seu valor é true, somente a barra visual de tabs é ocultada; seu conteúdo continua sendo renderizado. Com duas ou mais tabs, elas sempre são exibidas.
• actions é opcional e configura os próprios botões do formulário. Não é o Action Engine genérico do DYONA.

Hierarquia visual

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

Um schema contém tabs; cada tab contém rows; cada row contém columns; e cada item de columns é um field.

Tabs

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

• id é obrigatório, deve ser uma string não vazia e deve ser único dentro do schema.
• title é obrigatório, deve ser uma string não vazia e é o texto visível da tab.
• helpUrl é opcional, é uma string e permite definir acesso à ajuda dessa seção.
• rows é o array de linhas da tab.

Rows e columns

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

Uma row representa uma linha lógica do formulário. columns é obrigatório, é um array e uma row existente deve conter pelo menos um field. Cada item é um DyonaFormField.

O nome público da propriedade é columns, não fields.

rows: [
  {
    columns: [
      {name: 'firstName', label: 'Nome', type: 'text'},
      {name: 'lastName', label: 'Sobrenome', type: 'text'},
    ],
  },
]

Fields: estrutura básica

As propriedades específicas de fields são documentadas em Fields. Em Schema, a estrutura mínima é:

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

• name identifica o dado, deve ser uma string não vazia e deve ser único em todo o formulário.
• label é o texto visível do field.
• type define qual controle o DYONA Form renderiza.

Os field types atuais são text, number, date, datetime, select, autocomplete, checkbox, textarea, email, password, link e label. Suas propriedades específicas são documentadas em Fields.

Layout e grid

Um field pode definir sua largura responsiva com grid:

grid: {xs: 12, md: 6}

xs, sm, md, lg e xl usam valores de 1 a 12.

Actions do formulário

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: 'Salvar', icon: 'Save', shortcut: 'Alt+S', tooltip: 'Salvar alterações'},
  back: {label: 'Voltar', icon: 'ArrowBack'},
  custom: [{id: 'preview', label: 'Visualizar', validate: false}],
}

Estas actions configuram os botões próprios submit e back e os botões custom de DyonaForm. Elas não são instâncias de DyonaAction nem pertencem ao Action Engine genérico. Consulte Actions do formulário para handlers, validação, execução assíncrona, cancelamento, defaults e layout.

O que não pertence ao schema?

Estas são props de DyonaForm, não propriedades do schema: locale, initialValues, onSubmit, onBack, onAction, styles e dataSourceExecutor.

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

Isso separa a configuração declarativa do schema da integração React do componente.

Exemplo mínimo completo

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

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

Exemplo estrutural

const schema: DyonaFormSchema = {
  title: 'Editor de cliente',
  tabs: [
    {
      id: 'general', title: 'Geral',
      rows: [
        {columns: [
          {name: 'firstName', label: 'Nome', type: 'text', grid: {xs: 12, md: 6}},
          {name: 'lastName', label: 'Sobrenome', type: 'text', grid: {xs: 12, md: 6}},
        ]},
        {columns: [{name: 'email', label: 'Email', type: 'email'}]},
      ],
    },
    {
      id: 'preferences', title: 'Preferências',
      rows: [{columns: [{name: 'newsletter', label: 'Receber novidades', type: 'checkbox'}]}],
    },
  ],
  actions: {
    submit: {label: 'Salvar', icon: 'Save'},
    back: {label: 'Voltar', icon: 'ArrowBack'},
  },
};

Schema como JSON

A mesma estrutura básica pode ser representada com sintaxe JSON real:

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

A estrutura é compatível com JSON; a aplicação finalmente fornece o objeto resultante para schema.

Validação estrutural

O DYONA Form valida um schema antes da renderização normal. Regras estruturais úteis incluem title obrigatório, pelo menos uma tab, ids de tabs únicos, names de fields únicos em todo o formulário, field types suportados, columns válidas em rows e rejeição de propriedades incompatíveis. Códigos internos de validação não fazem parte deste guia.

Próximos passos

• Fields — tipos e propriedades de fields.
• Validation — validação declarativa e integrada.
• Conditions — visibilidade e obrigatoriedade condicional.
• Label — fields informativos visuais/no-data.