# Changelog — @sonata-innovations/fiber-types

All notable changes to the Fiber schema types. Dates are release dates.

## 4.0.0 — 2026-09-06

### Removed — BREAKING

- **The legacy flat `required` and `regex` component properties.** Both were documented as legacy and slated for migration since v2; they are now gone from the types and from `docs/schema/flow-schema.json`.

  `required?: boolean` was declared on six property types (`ComponentInputProperties`, `ComponentOptionProperties`, `ComponentSliderProperties`, `ComponentRatingProperties`, `ComponentFileUploadProperties`, `ComponentSignatureProperties`) and never on the other twenty-odd — an inconsistency the removal resolves. `regex?: string` was declared on `ComponentInputProperties` and was read by nothing in any package.

  Migrate before loading:

  ```
  { required: true }   → { validation: { rules: [{ type: "required" }] } }
  { regex: "..." }     → { validation: { rules: [{ type: "pattern", params: { regex: "..." } }] } }
  ```

  There is no auto-migration. An un-migrated field renders with no required marker and no enforcement — see `docs/schema/flow-schema.md` → **Removed flat properties**. Removing `required` is what lets FBRE 5.0.0 answer "is this field required?" from one key instead of two; see that changelog for the defect this closes.

## 3.0.1 — 2026-08-20

### Fixed

- **`README.md` and `AGENTS.md` did not list the exports 3.0.0 added.** Both files enumerate the package's public surface, and neither mentioned `FOCUSED_STYLES`, `styleFamily()` or the `StyleFamily` type — nor that `FlowConfiguration.mode` and `FlowModeType` had been removed. A consumer reading the README of the version they installed would have seen an API that no longer matched the package. Both now cover the flat style vocabulary, the focused family, and the removal.

  Documentation only; no code, type or schema change. `docs/features/style-families.md` shipped correct in 3.0.0 and is unchanged.

## 3.0.0 — 2026-08-20

### Removed — BREAKING

- **`FlowConfiguration.mode` and the `FlowModeType` type are gone.** One enum was doing three unrelated jobs: it selected a presentation, it partitioned which `FlowStyleType` values were legal, and it bundled two navigation behaviours. Each half now lives where it belongs — presentation on `theme.style`, behaviour on `navigation` — and the style vocabulary is flat.

  A stored flow with `mode: "conversational"` already carried a focused `theme.style`, so its **look is unchanged**; add `navigation.autoAdvance: true` to keep the auto-advance, which is now opt-in. A flow with `mode: "standard"` needs only the key deleted. `mode` is no longer read anywhere, so a stale key is inert — but the schema no longer describes it. Full migration: [`docs/features/style-families.md`](docs/features/style-families.md).

### Added

- **`FOCUSED_STYLES` and `styleFamily()`** — the four styles (`centered-minimal`, `stacked-cards`, `soft-float`, `bold-statement`) that share the focused presentation, and the derivation from a `FlowStyleType` to its family (`"form"` | `"focused"`). Also exported: the `StyleFamily` type.

  The family is derived and internal — it never appears in Flow JSON. It exists because ~32 CSS rules are shared by all four focused styles, and because deriving presentation from `theme.style` means every render path that carries the theme carries the presentation, the session protocol included. Exporting it replaces two hand-synced copies of the old style partition (one in FBT, one in the theme editor).

- **`NavigationConfig.autoAdvance`** (default `false`) — advance ~500ms after a single-select choice. Explicit and off by default: a form moving without a click is surprising and shifts content and focus, so it is now a deliberate choice rather than a side effect of a presentation mode.
- **`NavigationConfig.advanceOnEnter`** (default `true`) — advance on Enter in a single-line input. Previously gated behind conversational mode, which meant an ordinary one-question-per-screen form did not advance on Enter — a missing feature rather than a mode boundary.

### Changed

- `FlowStyleType` keeps all ten values and is now a **flat** vocabulary. Nothing partitions it; any style is valid on any flow.
- `flow-schema.json` / `flow-schema.md`: `mode` removed, the two `navigation` flags added, and the style description regrouped by family. The two sentences claiming conversational mode produced one question per screen are gone — it never did; it assumed the flow was already shaped that way.

## 2.5.0 — 2026-08-20

### Added

- **`ThemeConfig.fontFamily` now also accepts a loadable font config** — `{ family, src?, faces?, stack? }`, with the new `FontFamilyConfig`, `FontFaceConfig` and `FontSource` types exported. A plain family string still works and still means "the host page already loads this font"; the object form carries the sources a renderer needs to register the face itself. This is what makes a brand font work inside a shadow root, where an `@font-face` declared in the root's stylesheet is never registered at all. The schema (`flow-schema.json`) accepts either shape.

  Widening the type is source-compatible for anything that *sets* `fontFamily`, but code that *reads* it as a `string` needs to narrow. `isFontFamilyConfig` and `fontFamilyStack` are exported from `@sonata-innovations/fiber-fbre` for that.

## 2.4.0 — 2026-07-11 (never published)

> The version bump landed in the repo but was never tagged, so npm went 2.3.0 → 2.5.0. The change below ships as part of 2.5.0.


### Added

- `ComponentInputType` (`"text" | "email" | "tel" | "url" | "password"`) is now exported from the package index. It is the declared type of the `inputText` component's `inputType` property and was the only property-level union not re-exported — every sibling (`ComponentWidth`, `DateFormat`, `ComponentCalloutVariant`, `SignatureMode`, …) already was. Consumers can now type a helper against it directly instead of restating the string union. No runtime or schema change: the `inputType` values are unchanged and were already documented in `flow-schema.json`.

## 2.3.0 — 2026-07-10

### Added

- Documentation now ships inside the package under `docs/`, plus an `AGENTS.md` routing guide at the package root. This package is the canonical home of the schema docs (`docs/schema/`), including the machine-validatable `flow-schema.json` and `flow-data-schema.json` — every other Fiber package depends on this one, so the schema is always present in `node_modules`.

### Fixed

- `flow-data-schema.json` rejected output that FBRE actually emits: `confirm` was missing from the component type enum, `value` was required on entries that legitimately have no `value` key (containers, and a confirm that was ticked then unticked), and the base64 file-upload shape did not match the wire format. It now validates real FlowData.
- Documentation corrections: there are **30** component types (not 24) and **19** condition operators (not 20); option-bearing components such as `radio` do **not** default to their first option (the initial value is `null` unless `defaultValue` matches an option); `pattern` validation rules take `params.regex`, not `params.pattern`; the undocumented `showBorder` property on group and repeater is now in the schema; `${...}` references resolve against calculations, then component values, then context.
- `FileUploadBase64Data` declared a required field `lastModifiedData` — a typo for `lastModifiedDate` that was never emitted, so reading it always yielded `undefined`. It is now an optional `lastModifiedDate?: string`, matching the wire format and `flow-data-schema.json`. FBRE now emits the value as an ISO-8601 string rather than passing the deprecated `Date` object through unchanged. Code that read `lastModifiedData` will no longer type-check; it was reading a field that never existed at runtime.
- `FlowScreen.conditions` was typed `FlowConditionConfig | {}`, so an empty object `{}` type-checked even though the schema requires `action` and `when` and rejects it at validation. The `| {}` is removed; the field now matches `Component.conditions` (`FlowConditionConfig | undefined`), so a malformed `{}` is caught at compile time instead of at ajv validation.

## 2.2.0 — 2026-07-03

### Added

- `ConfirmationConfig` on `FlowConfiguration` — the terminal "thank you" screen (`show`, `title`, `body`).

## 2.1.0 — 2026-06-10

### Added

- `ThemeConfig` palette knobs: `background`, `surface`, `text`, `border`, `radius`, `fontFamily`, `error`, `success`, `warning`.
- `stepperStyle` on `ControlsConfig`.

### Changed

- **`colorScheme: "light" | "dark"` replaces the `darkMode` boolean.** There is no runtime fallback — pre-migrate stored flows.

## 2.0.1 — 2026-06-09

### Fixed

- The package emits explicit `.js` import extensions (NodeNext resolution), so it resolves under native Node ESM and server-side rendering.

## 2.0.0 — 2026-05-19

### Changed — breaking

- **`Component` is a discriminated union keyed on `type`.** `component.properties` narrows to the matching `Component*Properties` shape after a `type` check. The Flow JSON itself is unchanged; this is a TypeScript-surface change.
- Added `ComponentOfType<K>` and `ComponentPropertiesByType`.
- A single component manifest is now the source of component metadata, with `assertManifestTypeMapParity` guarding it at build time.
- `generateUUID` has a single export site.
- Removed the dead `ComponentInputType` export.

### Added

- `getValidationConfig` and `getComponentDisplayLabel` accessors for narrowed access.

## 1.0.6 — 2026-05-18

### Added

- `normalizeConditionalOrder(flow)` — a pure structural reorder that moves each top-level conditional to sit immediately after its trigger, so generator-authored (AI/LLM) flows group correctly in FBTL. Never rewrites conditions, properties, uuids, or labels; idempotent; leaves cycles and dangling sources in place.

## 1.0.4 — 2026-03-20

### Added

- Calculation results in the FlowData output (`FlowData.calculations`).

## 1.0.1 – 1.0.3 — 2026-03-04

### Added

- `FlowModeType` (`"standard" | "conversational"`) and the four conversational styles.
- Four additional standard styles; `stepperStyle` as independent config.
- `signature` and `computed` component types.
- Computation layer: `repeater` component, `Flow.calculations`, and rich option metadata (`OptionItem.metadata`).
- `cardSelect` component; optional `label` on `table`.