# @sonata-innovations/fiber-types

TypeScript types and JSON Schema for **Fiber** — a system for building and rendering data-collection forms.

This package defines the two contracts every other Fiber package speaks:

- **Flow** — the JSON document a builder produces and the render engine consumes
- **FlowData** — the collected responses the render engine hands back

It has no runtime dependencies and is the foundation of the Fiber dependency graph, which makes it the canonical home for the schema documentation.

## Install

```bash
npm install @sonata-innovations/fiber-types
```

Most consumers get this package transitively — it is a dependency of `fiber-fbre`, `fiber-fbt`, `fiber-fbtl`, and `fiber-shared`. Install it directly when you generate or inspect Flow JSON without rendering it.

## Documentation

Full docs ship inside this package under `docs/`, so they always match the version you installed. Start with `AGENTS.md` at the package root, or read them online at **[github.com/sonata-innovations/fiber-docs](https://github.com/sonata-innovations/fiber-docs)**.

| Document | What it covers |
|---|---|
| `docs/fiber-concepts.md` | The Flow/Screen/Component model, Flow vs FlowData |
| `docs/schema/flow-quick-reference.md` | Compact reference: 30 component types and their value shapes, conditions, validation, widths, markup |
| `docs/schema/flow-schema.md` | Exhaustive per-property reference |
| `docs/schema/flow-schema.json` | Machine-validatable JSON Schema (draft 2020-12) for a Flow |
| `docs/schema/flow-data-schema.md` | The shape of the data the render engine returns |
| `docs/schema/flow-data-schema.json` | Machine-validatable JSON Schema for FlowData |

## Validate a Flow

The JSON Schema is the enforceable contract. Validate anything you generate 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's exported

```ts
import type {
  Flow, FlowScreen, Component, ComponentProperties,
  FlowMetadata, FlowConfiguration, ThemeConfig, NavigationConfig,
  ControlsConfig, ConfirmationConfig, FontFamilyConfig,
  FlowData, ScreenData, ComponentData, CalculationData,
  FileUploadData, RangeValue,
  FlowConditionConfig, ConditionRule, ConditionOperator,
  FlowValidationConfig, ValidationRule,
  PresetData, TemplateData,
  ComponentType, ComponentOfType, ComponentPropertiesByType,
  FlowStyleType, StyleFamily,
} from "@sonata-innovations/fiber-types";

import {
  generateUUID,
  regenerateComponentUUIDs,
  regenerateFlowUUIDs,
  normalizeConditionalOrder,
  getValidationConfig,
  getComponentDisplayLabel,
  COMPONENT_VARIANT_TYPES,
  FOCUSED_STYLES,
  styleFamily,
} from "@sonata-innovations/fiber-types";
```

Those are the headline types. Every **per-component property shape**
(`ComponentInputProperties`, `ComponentOptionProperties`, `ComponentRepeaterProperties`, …)
and every **property-level union** (`ComponentWidth`, `DateFormat`, `ComponentInputType`,
`ComponentCalloutVariant`, `SignatureMode`, `OptionItem`, `TableColumn`, …) is exported too —
import them when you need to type a helper against a single property rather than a whole component.

`Component` is a **discriminated union keyed on `type`** — narrow on `component.type` and `component.properties` narrows with it:

```ts
if (component.type === "inputText") {
  component.properties.placeholder; // typed, no cast
}
```

## Gotchas

- **`theme.style` carries the presentation; there is no `config.mode`.** `FlowStyleType` is a flat vocabulary of ten. Four of them — `centered-minimal`, `stacked-cards`, `soft-float`, `bold-statement` — form the **focused** family, which adds a centered narrow column, animated entry and larger targets; the other six are the **form** family. `styleFamily(style)` and `FOCUSED_STYLES` expose that partition so a builder groups its style picker from one list instead of copying a constant. The family is derived and never appears in Flow JSON. `FlowConfiguration.mode` and `FlowModeType` were removed in 3.0.0 — see `docs/features/style-families.md`.
- **`ThemeConfig.fontFamily` is `string | FontFamilyConfig`.** A plain string is a CSS stack and means "the host page already loads this font"; `{ family, src }` carries the sources a renderer registers itself. Code that reads the knob as a `string` has to narrow — `isFontFamilyConfig` / `fontFamilyStack` are exported from `@sonata-innovations/fiber-fbre` for that.
- **30 component types.** Display types (`header`, `text`, `divider`, `callout`, `table`) never appear in FlowData; `computed` does.
- **`pattern` validation rules take `params.regex`**, not `params.pattern`. A `pattern` key is silently ignored and the rule 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.** The initial value is `null` unless `properties.defaultValue` matches an option's `value`.
- **Never set runtime-only fields** (`value`, `valid`, `addedComponents`) in Flow JSON.
- **AI-generated flows** should be passed through `normalizeConditionalOrder(flow)` before being loaded into FBTL. It reorders conditionals to follow their triggers — a pure structural reorder, idempotent, and it never rewrites a condition, property, uuid, or label.

## Companion packages

| Package | What it is |
|---|---|
| [`@sonata-innovations/fiber-fbre`](https://www.npmjs.com/package/@sonata-innovations/fiber-fbre) | Render engine — renders a Flow, returns FlowData |
| [`@sonata-innovations/fiber-fbt`](https://www.npmjs.com/package/@sonata-innovations/fiber-fbt) | Full drag-and-drop builder |
| [`@sonata-innovations/fiber-fbtl`](https://www.npmjs.com/package/@sonata-innovations/fiber-fbtl) | Lite builder for non-technical end users |
| [`@sonata-innovations/fiber-shared`](https://www.npmjs.com/package/@sonata-innovations/fiber-shared) | Condition, validation, markup, and formula engines |
| [`@sonata-innovations/fiber-theme-editor`](https://www.npmjs.com/package/@sonata-innovations/fiber-theme-editor) | Visual theme editor widget |

## License

MIT