Skip to main content

Core Types

Todos os tipos exportados de @schema-forms-data/core. Zero dependências de runtime.

npm install @schema-forms-data/core

Hierarquia do schema​

FormSchema
  └── steps: FormStep[]
        └── containers: FormContainer[]
              └── campos: FormField[]

FormSchema​

Objeto raiz que define todo o formulário.

interface FormSchema {
  id: string;
  nome: string;
  status: FormSchemaStatus;   // 'rascunho' | 'ativo' | 'inativo'
  steps: FormStep[];
  descricao?: string;
  eventoId?: string;
  template?: string;          // ID do template visual padrão
  stepConfig?: FormStepConfig; // configurações visuais dos steps
  createdAt?: string;
  updatedAt?: string;
}

FormStep​

interface FormStep {
  id: string;
  titulo: string;
  ordem: number;
  descricao?: string;
  icone?: string;         // nome de ícone Lucide
  showLabel?: boolean;    // exibir cabeçalho do step (default: true)
  containers: FormContainer[];
}

FormContainer​

interface FormContainer {
  id: string;
  titulo?: string;
  descricao?: string;
  icone?: string;
  ordem: number;
  colunas?: 1 | 2 | 3 | 4;   // colunas internas do container
  tamanho?: number;            // span no grid de 12 colunas (default: 12)
  inicioColuna?: number;       // coluna de início (1-based)
  showLabel?: boolean;
  showAsCard?: boolean;
  repeatable?: boolean;        // container repetível (adiciona/remove linhas)
  minItems?: number;
  maxItems?: number;
  itemLabel?: string;          // label do botão "Adicionar"
  condicional?: FieldConditionalExpr; // visibilidade condicional do container inteiro
  campos: FormField[];
}

FormField​

interface FormField {
  id: string;
  nome: string;           // chave no objeto de values submetido
  label: string;
  tipo: FieldType;
  obrigatorio: boolean;
  tamanho: number;        // span no grid de 12 colunas (1–12)
  ordem: number;

  // Aparência
  inicioColuna?: number;
  placeholder?: string;
  hint?: string;

  // Valores
  defaultValue?: string | number | boolean;
  initialValue?: string | number | boolean; // suporta {{vars}}

  // Opções (select, radio, checkbox_group, autocomplete)
  opcoes?: FieldOption[];
  opcoesFromVar?: string; // chave em externalData para carregar opções dinamicamente

  // Validação
  validacao?: FieldValidation;           // regras nativas
  validate?: FieldValidatorConfig[];     // validadores customizados (bloqueiam submit)
  warn?: FieldValidatorConfig[];         // validadores de aviso (não bloqueiam)

  // Condicionais
  condicional?: FieldConditionalExpr;
  setValues?: ConditionalSetValue[];     // define valores em outros campos ao tornar-se visível
  clearedValue?: unknown;               // valor aplicado quando o campo é ocultado

  // Comportamento
  isReadOnly?: boolean;
  isDisabled?: boolean;
  locked?: boolean;            // bloqueado no builder (não pode ser deletado/movido)
  resolvePropsKey?: string;    // chave em fieldResolvers para props dinâmicas

  // Máscara
  mascara?: MaskType;          // 'cpf' | 'telefone' | 'cep' | 'custom'
  mascaraCustom?: string;

  // Campo de termos
  termoTexto?: string;
  termoPdfUrl?: string;
  termoPdfUploadId?: string;

  // field_array
  subFields?: FormField[];
  minItems?: number;
  maxItems?: number;
  itemLabel?: string;
  addLabel?: string;

  // sub_form
  subSchema?: SubFormSchema;

  // slider / rating
  minValue?: number;
  maxValue?: number;
  step?: number;
  maxRating?: number;

  // date_range
  dateRangeStartLabel?: string;
  dateRangeEndLabel?: string;

  // cep (preenchimento automático)
  cepFillMap?: Record<string, string>;

  // autocomplete
  relatedFieldName?: string;
}

FieldType​

Enum com todos os tipos de campo disponíveis:

enum FieldType {
  TEXTO = "texto",
  TEXTAREA = "textarea",
  NUMBER = "number",
  EMAIL = "email",
  PASSWORD = "password",
  TELEFONE = "telefone",
  CPF = "cpf",
  CEP = "cep",
  DATE = "date",
  DATETIME = "datetime",
  TIME = "time",
  DATE_RANGE = "date_range",
  SELECT = "select",
  AUTOCOMPLETE = "autocomplete",
  RADIO = "radio",
  CHECKBOX = "checkbox",
  CHECKBOX_GROUP = "checkbox_group",
  SWITCH = "switch",
  SLIDER = "slider",
  RATING = "rating",
  COLOR = "color",
  FILE = "file",
  HIDDEN = "hidden",
  FIELD_ARRAY = "field_array",
  PARTICIPATION_TYPE = "participation_type",
  PAYMENT_METHOD = "payment_method",
  TERMS = "terms",
  SUB_FORM = "sub_form",
}

FieldOption​

interface FieldOption {
  valor: string;
  label: string;
  disabled?: boolean;
}

FieldValidation​

Regras de validação nativas configuradas diretamente no schema:

interface FieldValidation {
  minLength?: number;
  maxLength?: number;
  min?: number;           // mínimo numérico
  max?: number;           // máximo numérico
  regex?: string;         // padrão regex
  regexMessage?: string;  // mensagem quando o regex falha
  minDate?: string;       // data mínima (ISO string)
  maxDate?: string;
  fileTypes?: string[];   // ex: ['image/png', 'image/jpeg'] — validado antes do upload
  maxFileSize?: number;   // bytes — validado antes do upload
  minAge?: number;        // idade mínima em anos (campos DATE)
  maxAge?: number;
}

FieldValidatorConfig​

Referência a um validador customizado registrado no validatorMapper:

interface FieldValidatorConfig {
  type: string;            // chave no validatorMapper
  message?: string;        // sobrescreve a mensagem retornada pela função
  [key: string]: unknown;  // params extras passados à função
}

FieldConditional / FieldConditionGroup​

Expressões de condicionais:

// Folha — condição simples
interface FieldConditional {
  campo: string;        // nome do campo (ou 'evento.x' para externalData)
  operador: ConditionalOperator;
  valor?: unknown;
  source?: string;
}

// Nó lógico — AND / OR com grupos aninhados
interface FieldConditionGroup {
  and?: FieldConditionalExpr[];
  or?: FieldConditionalExpr[];
}

// Union recursiva
type FieldConditionalExpr = FieldConditional | FieldConditionGroup;

Operadores disponíveis: igual, diferente, vazio, naoVazio, contem, naoContem, maiorQue, menorQue, maiorOuIgual, menorOuIgual.

Veja o guia completo em Condicionais.

ConditionalSetValue​

Define o valor de outro campo quando uma condicional muda de falso para verdadeiro:

interface ConditionalSetValue {
  campo: string;
  valor: string | number | boolean | null;
}

SubFormSchema​

interface SubFormSchema {
  titulo?: string;
  fields: FormField[];
}

FormStepConfig​

Configurações visuais dos steps no nível do schema (sobrepõe as configurações do template):

interface FormStepConfig {
  showStepIndicators?: boolean;
  showProgressBar?: boolean;
  stepIndicatorVariant?: 'numbers' | 'icons' | 'icons-labeled';
  stepIndicatorPosition?: 'top-center' | 'top-left';
  stepIndicatorOrientation?: 'horizontal' | 'vertical';
}

Funções utilitárias​

import { generateId } from "@schema-forms-data/core";

// Gera um UUID v4
const id = generateId(); // "a1b2c3d4-..."

Constantes​

import { FIELD_TYPE_LABELS, FIELD_TYPE_ICONS } from "@schema-forms-data/core";

// Nome amigável de cada tipo de campo
FIELD_TYPE_LABELS[FieldType.TEXTO]; // "Texto"
FIELD_TYPE_LABELS[FieldType.EMAIL]; // "E-mail"

// Nome do ícone Lucide de cada tipo
FIELD_TYPE_ICONS[FieldType.FILE]; // "Paperclip"

## FieldType

| Value                          | Description                                   |
| ------------------------------ | --------------------------------------------- |
| `FieldType.TEXTO`              | Single-line text                              |
| `FieldType.TEXTAREA`           | Multi-line text area                          |
| `FieldType.NUMBER`             | Numeric input                                 |
| `FieldType.EMAIL`              | Email                                         |
| `FieldType.PASSWORD`           | Password (masked)                             |
| `FieldType.TELEFONE`           | Phone with mask                               |
| `FieldType.CPF`                | Brazilian CPF with mask                       |
| `FieldType.CEP`                | Brazilian postal code with auto-fill          |
| `FieldType.DATE`               | Date picker                                   |
| `FieldType.DATETIME`           | Date + time picker                            |
| `FieldType.TIME`               | Time picker                                   |
| `FieldType.DATE_RANGE`         | Date range (start + end)                      |
| `FieldType.SELECT`             | Dropdown select                               |
| `FieldType.AUTOCOMPLETE`       | Searchable select                             |
| `FieldType.RADIO`              | Radio button group                            |
| `FieldType.CHECKBOX`           | Single checkbox                               |
| `FieldType.CHECKBOX_GROUP`     | Multiple checkboxes                           |
| `FieldType.SWITCH`             | Toggle switch                                 |
| `FieldType.SLIDER`             | Range slider                                  |
| `FieldType.RATING`             | Star rating                                   |
| `FieldType.COLOR`              | Color picker                                  |
| `FieldType.FILE`               | File upload                                   |
| `FieldType.HIDDEN`             | Hidden field (not visible, value stored)      |
| `FieldType.FIELD_ARRAY`        | Repeating group of sub-fields                 |
| `FieldType.SUB_FORM`           | Nested sub-form (values stored as object)     |
| `FieldType.PARTICIPATION_TYPE` | Participation type selector (domain-specific) |
| `FieldType.PAYMENT_METHOD`     | Payment method selector (domain-specific)     |
| `FieldType.TERMS`              | Terms of service with PDF viewer              |

```ts
import { FieldType } from "@schema-forms-data/core";

const field: FormField = {
  id: "f1",
  nome: "email",
  label: "Email",
  tipo: FieldType.EMAIL,
  obrigatorio: true,
  tamanho: 6,
  ordem: 1,
};

FieldValidation​

Built-in validation rules (no mapper needed):

interface FieldValidation {
  minLength?: number;
  maxLength?: number;
  min?: number; // min numeric value
  max?: number; // max numeric value
  regex?: string; // regex pattern string
  regexMessage?: string; // error message when regex fails
  minDate?: string; // ISO date string
  maxDate?: string;
  fileTypes?: string[]; // accepted MIME types
  maxFileSize?: number; // bytes
  minAge?: number; // minimum age in years (DATE fields)
  maxAge?: number;
}

FieldValidatorConfig​

Reference to a custom validator registered in validatorMapper:

interface FieldValidatorConfig {
  type: string; // key in validatorMapper
  message?: string; // overrides the function's return message
  [key: string]: unknown; // extra params passed to the function
}

See Validation for full usage.

FieldConditionalExpr​

Conditional visibility for a field or container:

// Single condition (leaf)
interface FieldConditional {
  campoId: string;
  operador:
    | "igual"
    | "diferente"
    | "contem"
    | "naoContem"
    | "vazio"
    | "naoVazio"
    | "maiorQue"
    | "menorQue"
    | "maiorOuIgual"
    | "menorOuIgual";
  valor?: string | number | boolean;
  source?: "campo" | "evento"; // 'evento' reads from externalData
}

// Group with AND / OR logic
interface FieldConditionGroup {
  and?: FieldConditionalExpr[];
  or?: FieldConditionalExpr[];
}

type FieldConditionalExpr = FieldConditional | FieldConditionGroup;

See Conditionals for full usage.

FieldOption​

interface FieldOption {
  valor: string; // stored value
  label: string; // display label
  disabled?: boolean;
}

SubFormSchema​

interface SubFormSchema {
  titulo?: string;
  fields: FormField[];
}

ConditionalSetValue​

Set other field values when a condition becomes true:

interface ConditionalSetValue {
  campo: string; // target field name
  valor: string | number | boolean | null; // value to set (supports {{vars}})
}

FormSchema​

Top-level schema object that defines the entire form.

interface FormSchema {
  id: string;
  name: string;
  steps: FormStep[];
  version?: number;
}

FormStep​

A step (page) inside the multi-step form.

interface FormStep {
  id: string;
  title: string;
  containers: FormContainer[];
}

FormContainer​

A layout container inside a step — groups fields visually.

interface FormContainer {
  id: string;
  title?: string;
  fields: FormField[];
  columns?: 1 | 2 | 3;
}

FormField​

Individual field definition.

interface FormField {
  id: string;
  name: string;
  label: string;
  type: FieldType;
  required?: boolean;
  placeholder?: string;
  defaultValue?: unknown;
  helperText?: string;
  validation?: FieldValidation;
  conditional?: FieldConditional;
  options?: FieldOption[];
  mask?: MaskType;
  // upload-specific
  accept?: string;
  multiple?: boolean;
  // terms-specific
  uploadId?: string;
  termsText?: string;
  // cep-specific
  fillFields?: Record<string, string>;
}

FieldType​

Enum of all supported field types.

ValueDescription
TEXTSingle-line text input
TEXTAREAMulti-line text area
NUMBERNumeric input
EMAILEmail input with validation
PHONEPhone input with mask
DATEDate picker
TIMETime picker
DATETIMEDate + time picker
SELECTDropdown select
MULTISELECTMultiple options select
RADIORadio button group
CHECKBOXSingle checkbox
CHECKBOX_GROUPMultiple checkboxes
FILEFile upload
IMAGEImage upload with preview
CEPBrazilian postal code with auto-fill
CURRENCYBRL currency input
TERMSTerms of service with PDF viewer
HEADERDisplay-only text block
import { FieldType } from "@schema-forms-data/core";

const field: FormField = {
  id: "f1",
  name: "email",
  label: "Email",
  type: FieldType.EMAIL,
  required: true,
};

FieldValidation​

interface FieldValidation {
  minLength?: number;
  maxLength?: number;
  min?: number;
  max?: number;
  pattern?: string; // regex string
  patternMessage?: string; // error message shown when pattern fails
}

FieldConditional​

Show/hide a field based on another field's value.

interface FieldConditional {
  dependsOn: string; // field name to watch
  operator: "eq" | "neq" | "contains" | "notContains" | "gt" | "lt";
  value: unknown; // the comparison value
}

Example: Show a "Details" textarea only when "Category" equals "other":

{
  id: 'f2',
  name: 'details',
  label: 'Please describe',
  type: FieldType.TEXTAREA,
  conditional: {
    dependsOn: 'category',
    operator: 'eq',
    value: 'other',
  },
}

FieldOption​

Used for SELECT, RADIO, MULTISELECT, and CHECKBOX_GROUP.

interface FieldOption {
  label: string;
  value: string;
}

MaskType​

Input masks applied to TEXT fields.

type MaskType =
  | "cpf" // 000.000.000-00
  | "cnpj" // 00.000.000/0000-00
  | "phone" // (00) 00000-0000
  | "cep" // 00000-000
  | "date" // 00/00/0000
  | "time" // 00:00
  | "currency" // R$ 0.000,00
  | string; // custom mask pattern

Utility Functions​

import { generateId } from "@schema-forms-data/core";

// Generates a unique field/container/step ID
const id = generateId(); // e.g. "fld_xk29a"