Fields

Each field maps one application property.

type ImporterField = {
  key: string;
  label: string;
  type: "string" | "number" | "date" | "email" | "enum" | "boolean" | "url";
  required?: boolean;
  unique?: boolean; // when true, values must be unique across rows in the file
  enumValues?: string[]; // required for meaningful enum validation
  aliases?: string[]; // extra header names for auto-map
  valueMap?: Record<string, string>; // cell aliases before coercion (Premium → pro)
  transform?: (raw: string) => string; // local schema only
  validate?: (value: unknown, row: Record<string, unknown>) => string | null; // local, sync
  dependsOn?: string[]; // sibling keys this validate reads
};

Use aliases when customers routinely export headers that do not match your key or label (for example E-mail or Email Address for email).

Use valueMap to normalize cell text before type checks. Unknown enum values that still missenumValues after valueMap can be remapped on the preview step (canonical option or leave invalid). That is not a spreadsheet cell editor.

transform and validate are functions, so they work on a local fields schema only. Hosted JSON cannot ship functions. validate runs after coercion and receives the full coerced row, so cross-field checks belong there. dependsOn documents those siblings; the widget always revalidates the whole row.

Use duplicateKey on the component (or hosted config) to detect repeated values across rows for one field. Use field-level unique when several fields must be unique independently.

Locale helpers on <Importer />: dateOrder (MDY | DMY), numberLocale (us | eu | auto), and dir (ltr | rtl).

Related: Validation · Duplicates · Column mapping