# @sonata-innovations/fiber-types — Agent Guide

The Fiber schema, as TypeScript types and as JSON Schema. Every other Fiber package depends on this one, which makes it the canonical home for the **Flow** (input) and **FlowData** (output) contracts.

Docs in this package are versioned with the code you installed. Read them from `node_modules/@sonata-innovations/fiber-types/docs/`.

## Documentation map

| Read this | When |
|---|---|
| `docs/fiber-concepts.md` | You are new to Fiber. The Flow/Screen/Component model, Flow vs FlowData, how builders and the render engine relate. |
| `docs/schema/flow-quick-reference.md` | **Start here to construct Flow JSON.** Compact reference: the 30 component types and their value shapes, conditions, validation, options, widths, markup. |
| `docs/schema/flow-schema.md` | Exhaustive per-property reference for every component type and config field. |
| `docs/schema/flow-schema.json` | Machine-validatable JSON Schema (draft 2020-12) for a Flow. Validate with `ajv`. |
| `docs/schema/flow-data-schema.md` | The shape of the data FBRE hands back: per-type value shapes, exclusion rules, containers, calculations. |
| `docs/schema/flow-data-schema.json` | Machine-validatable JSON Schema for FlowData. |

**Validate a Flow you generated** rather than trusting it by inspection:

```bash
npx ajv-cli validate --spec=draft2020 \
  -s node_modules/@sonata-innovations/fiber-types/docs/schema/flow-schema.json \
  -d my-flow.json
```

## What this package exports

- **Schema types** — `Flow`, `FlowScreen`, `Component` (a discriminated union keyed on `type`), `ComponentProperties`, `FlowMetadata`, `FlowConfiguration`, `ThemeConfig`, `NavigationConfig`, `ControlsConfig`, `ConfirmationConfig`
- **Output types** — `FlowData`, `ScreenData`, `ComponentData`, `CalculationData`, `FileUploadData`, `RangeValue`
- **Condition & validation types** — `FlowConditionConfig`, `ConditionRule`, `ConditionOperator` (19 operators), `FlowValidationConfig`, `ValidationRule` (17 validators)
- **Preset/template data** — `PresetData`, `TemplateData` (the serializable definitions FBT accepts)
- **Component manifest** — `COMPONENT_VARIANT_TYPES`, `ComponentType`, `ComponentOfType<K>`, `ComponentPropertiesByType`
- **Style families** — `FOCUSED_STYLES`, `styleFamily()`, `StyleFamily`. The four focused styles and the derivation from a `FlowStyleType` to `"form"` | `"focused"`
- **Utilities** — `generateUUID`, `regenerateComponentUUIDs`, `regenerateFlowUUIDs`, `normalizeConditionalOrder`, `getValidationConfig`, `getComponentDisplayLabel`

## Facts worth knowing before you generate a Flow

- **No `config.mode`.** Removed in 3.0.0. Presentation is `theme.style` (ten values, flat — four of them the `focused` family); behaviour is `navigation.autoAdvance` (default off) and `navigation.advanceOnEnter` (default on). Don't emit `mode`.
- **30 component types.** Display types (`header`, `text`, `divider`, `callout`, `table`) never appear in FlowData; `computed` does.
- **19 condition operators, 17 validators.** Exact lists are in the quick reference.
- **Validation `pattern` rules take `params.regex`**, not `params.pattern`. A `pattern` key is ignored and the rule silently always passes.
- **Options must be `{ label, value }` objects**, not bare strings. `value` may be a string or a number.
- **Option-bearing components do not default to their first option.** Initial value is `null` unless `properties.defaultValue` matches an option's `value`.
- **Never set runtime-only fields** (`value`, `valid`, `addedComponents`) in Flow JSON.
- **`theme.fontFamily` may be an object, not just a string.** `{ family, src }` names a font the renderer loads itself; a bare string assumes the host page already has it. Narrow before treating it as a stack.
- **`Component` is a discriminated union.** Narrow on `component.type` and `properties` narrows with it; use `ComponentOfType<"inputText">` to name one variant.
- **If an AI/LLM generated the flow**, run `normalizeConditionalOrder(flow)` before handing it to FBTL — it reorders conditionals to sit after their triggers, structurally only, and is idempotent.

## Companion packages

- `@sonata-innovations/fiber-fbre` — renders a Flow, returns FlowData
- `@sonata-innovations/fiber-fbt` — full drag-and-drop builder
- `@sonata-innovations/fiber-fbtl` — lite builder for non-technical end users
- `@sonata-innovations/fiber-shared` — the condition, validation, markup, and formula engines