@sonata-innovations/fiber-types 2.3.0 → 3.0.0

package/docs/fiber-concepts.md

@@ -1,10 +1,12 @@
 ---
 title: Fiber Concepts
 applies-to:
-  - "@sonata-innovations/fiber-types@^2.2"
-  - "@sonata-innovations/fiber-fbre@^3.3"
-  - "@sonata-innovations/fiber-fbt@^2.2"
-  - "@sonata-innovations/fiber-fbtl@^2.2"
+  - "@sonata-innovations/fiber-types@^3.0"
+  - "@sonata-innovations/fiber-shared@^1.2"
+  - "@sonata-innovations/fiber-fbre@^4.0"
+  - "@sonata-innovations/fiber-fbt@^3.0"
+  - "@sonata-innovations/fiber-fbtl@^3.0"
+  - "@sonata-innovations/fiber-theme-editor@^2.0"
 read-when: "First contact with Fiber: the Flow/Screen/Component model, FlowData, builders vs render engine, conditions/validation/calculations concepts."
 ---
 
@@ -22,7 +24,7 @@ read-when: "First contact with Fiber: the Flow/Screen/Component model, FlowData,
 Fiber is a system for building and rendering data-collection forms. It splits authoring from rendering and offers two authoring surfaces targeted at different audiences:
 
 - **FBT (Fiber Tool)** — A visual drag-and-drop builder for power users / form designers. Full feature surface: screens, multi-rule conditions, validation, calculations, reference markup, the complete 30-type component palette. See the [FBT integration guide](@sonata-innovations/fiber-fbt/docs/integration/fbt.md).
-- **FBTL (Fiber Tool Lite)** — A stripped-down, end-user-friendly builder designed to be embedded in parent apps so non-technical end users (clinicians, teachers, etc.) can author their own forms. Five question types + Information Screens + single-rule conditions. Preserves advanced properties from loaded flows without editing them. See the [FBTL integration guide](@sonata-innovations/fiber-fbtl/docs/integration/fbtl.md).
+- **FBTL (Fiber Tool Lite)** — A stripped-down, end-user-friendly builder designed to be embedded in parent apps so non-technical end users (clinicians, teachers, etc.) can author their own forms. Seven question types + Information Screens + single-rule conditions. Preserves advanced properties from loaded flows without editing them. See the [FBTL integration guide](@sonata-innovations/fiber-fbtl/docs/integration/fbtl.md).
 - **FBRE (Fiber Render Engine)** — A render engine that consumes Flow JSON, renders the interactive form for end users, and outputs collected data ("FlowData") back to the parent application. See the [FBRE integration guide](@sonata-innovations/fiber-fbre/docs/integration/fbre.md).
 
 A fourth library, the **Theme Editor**, is a plug-and-play widget that lets end users visually customize a flow's theme (color scheme, style, palette knobs) and emits the resulting `ThemeConfig`. See the [Theme Editor integration guide](@sonata-innovations/fiber-theme-editor/docs/integration/theme-editor.md).
@@ -87,15 +89,16 @@ The optional `config` object controls runtime behavior, organized into semantic
 
 | Group | Setting | Purpose |
 |-------|---------|---------|
-| _(flat)_ | `mode` | Presentation mode: `"standard"` (default) or `"conversational"` (one question at a time) |
 | `theme` | `color` | Primary accent color (CSS value) |
 | `theme` | `colorScheme` | Built-in palette preset: `"light"` (default) or `"dark"` (replaces the former `darkMode` boolean) |
 | `theme` | `style` | Visual style (`"clean"`, `"outlined"`, …) |
 | `theme` | `background` / `surface` / `text` / `border` | Palette knobs overriding the preset tokens |
-| `theme` | `radius` / `fontFamily` | Corner radius and font family knobs |
+| `theme` | `radius` / `fontFamily` | Corner radius and font family knobs. `fontFamily` also accepts `{ family, src }`, which FBRE loads itself rather than assuming the host page already has the font |
 | `theme` | `error` / `success` / `warning` | Semantic state color knobs |
 | `navigation` | `transition` | Screen transition animation type |
 | `navigation` | `allowInvalidTransition` | Allow navigating past screens with validation errors |
+| `navigation` | `autoAdvance` | Advance ~500ms after a single-select choice (default off) |
+| `navigation` | `advanceOnEnter` | Advance on Enter in a single-line input (default on) |
 | `controls` | `show` | Show/hide built-in next/back buttons |
 | `controls` | `layout` | Controls layout (`"default"`, `"centered"`, `"inline-full"`, or `"stacked"`) |
 | `controls` | `showStepper` | Show/hide the step indicator |
@@ -291,11 +294,11 @@ The formula engine lives in `@sonata-innovations/fiber-shared`, so calculations
 ### Authoring Phase (FBT or FBTL)
 
 1. A form author opens **FBT** (power users) or **FBTL** (non-technical end users) in a parent application
-2. They assemble the flow — FBT via multi-screen drag-and-drop with the full component palette; FBTL via a flat, one-question-per-screen list limited to five question types plus Information Screens
+2. They assemble the flow — FBT via multi-screen drag-and-drop with the full component palette; FBTL via a flat, one-question-per-screen list limited to seven question types plus Information Screens
 3. The builder produces a Flow JSON object via the `onFlowChange` callback (FBT also exposes `exportFlow()` on the store)
 4. The parent application saves the Flow JSON (to a database, file, API, etc.)
 
-FBTL emits a flow with one component per screen (conversational mode) and promotes component-level conditions to screen-level conditions on emit. Loading a multi-screen flow into FBTL flattens it into the one-per-screen shape on the next save, while preserving all advanced properties (calculations, reference markup, multi-rule conditions, etc.) that FBTL itself cannot edit. The resulting JSON remains fully interoperable with FBT.
+FBTL uses a **page-break model**: each stage card carries a break-after flag, so a freshly authored flow is one question per screen until the author merges cards onto a shared screen. Screen structure round-trips — a loaded multi-screen flow's boundaries become break flags rather than being flattened away — and the host can switch the builder to a single-screen model entirely (`options.screenModel`). A component-level condition is promoted to a screen-level condition only when its screen ends up holding exactly one component; otherwise it stays on the component as an in-place show/hide. Advanced properties FBTL cannot edit (calculations, reference markup, multi-rule conditions, and so on) are preserved untouched, and the resulting JSON remains fully interoperable with FBT.
 
 ### Rendering Phase (FBRE)
 
@@ -386,6 +389,8 @@ The markup → HTML converter lives in `@sonata-innovations/fiber-shared`, share
 
 `${...}` tokens interpolate live values into text. A token is resolved in order against: **calculations** (by UUID) → **component values** (by UUID) → **context** (by key, from FBRE's `context` prop). Unresolvable references render as empty. This powers dynamic text like "Your total is ${calc-uuid}" or "Welcome back, ${userName}".
 
+Writing one means knowing a UUID, so builders offer a picker. `resolvableReferences(flow)` from `@sonata-innovations/fiber-shared` returns every reference a flow can resolve, in that same order — use it rather than re-walking the flow, so a picker cannot drift from what the renderer will actually resolve. See [Confirmation Screen → Building your own picker](@sonata-innovations/fiber-fbre/docs/features/confirmation-screen.md#building-your-own-picker).
+
 ---
 
 ## 11. Extension Points
@@ -406,7 +411,7 @@ A template is likewise data — a `TemplateData` object (`{ type, label, icon, f
 
 Presets and templates being plain data (rather than code) is what enables server-side storage: the hosted platform stores tenant-scoped custom presets and templates in the database and serves them to FBT at load time. Older factory-function definitions (functions returning fresh `Component`/`Flow` objects) are still accepted for back-compat, but data-based definitions are the current model.
 
-See [`custom-presets-and-templates.md`](@sonata-innovations/fiber-fbt/docs/features/custom-presets-and-templates.md) for the full authoring guide.
+See [`custom-presets-and-templates.md`](features/custom-presets-and-templates.md) for the full authoring guide.
 
 ---
 
@@ -448,9 +453,17 @@ FBRE accepts a flow through one of three mutually exclusive prop shapes:
 2. **Remote flow** — `<FBRE flowId="..." apiEndpoint="..." />`. FBRE fetches a published flow from a Fiber server and renders it client-side. All evaluation (conditions, validation, calculations) still happens in the browser.
 3. **Server-driven** — `<FBRE flowId="..." sessionEndpoint="..." />`. FBRE starts a session and receives one screen at a time; the server evaluates conditions and validation between screens (using the same `fiber-shared` engines) and assembles the final FlowData. The full flow definition never reaches the client — useful for sensitive branching logic and server-side integrations between screens.
 
-### Conversational Mode
+### Style Families
+
+`theme.style` is one flat vocabulary of ten values, but four of them — `centered-minimal`, `stacked-cards`, `soft-float`, `bold-statement` — share a presentation treatment: a vertically centered narrow column, staggered component entry, enlarged tap targets and bolder type. That shared half is the **focused** family; the other six are the **form** family.
+
+The family is derived from the style, never authored — it does not appear in Flow JSON. FBRE emits it as `data-style-family`, and `fiber-types` exports `styleFamily()` / `FOCUSED_STYLES` for builders grouping a style picker. Because it derives from `theme.style`, the presentation travels with the theme through every render path, server-driven included.
+
+A focused style is a *look*. Pacing — how many questions land on a screen — is a property of the flow's structure (see FBTL's `screenModel`), and the two advance behaviors below are separate `navigation` flags. FBTL authors focused-styled flows by default.
+
+### Advance Behaviors
 
-Setting `config.mode: "conversational"` (or the FBRE `mode` prop) renders the flow one question at a time in a chat-like presentation instead of the standard screen-per-page layout. Same Flow JSON, same condition/validation/FlowData behavior — only the presentation changes. FBTL authors flows in this shape by default.
+`navigation.autoAdvance` (default `false`) advances ~500ms after a single-select choice; `navigation.advanceOnEnter` (default `true`) advances when Enter is pressed in a single-line input. Both only ever fire on a screen with exactly one visible input, never on the last screen, and never on an invalid screen. Neither is tied to a style — a `clean` form with one question per screen advances on Enter just like a focused one.
 
 ### Confirmation Screen
 

package/docs/schema/flow-data-schema.md

@@ -1,8 +1,8 @@
 ---
 title: FlowData Schema
 applies-to:
-  - "@sonata-innovations/fiber-types@^2.2"
-  - "@sonata-innovations/fiber-fbre@^3.3"
+  - "@sonata-innovations/fiber-types@^3.0"
+  - "@sonata-innovations/fiber-fbre@^4.0"
 read-when: "Consuming FlowData output from FBRE: structure, per-type value shapes, exclusion rules, containers, calculations."
 ---
 

package/docs/schema/flow-quick-reference.md

@@ -1,7 +1,7 @@
 ---
 title: Flow JSON Quick Reference
 applies-to:
-  - "@sonata-innovations/fiber-types@^2.2"
+  - "@sonata-innovations/fiber-types@^3.0"
 read-when: "Constructing or interpreting Flow JSON: structure, component types and value types, options, conditions, validation, widths, inline markup. For exhaustive per-property detail, use flow-schema.md instead."
 ---
 
@@ -36,9 +36,8 @@ Flow
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `mode` | `FlowModeType` | `"standard"` | `"standard"` or `"conversational"` — conversational mode centers content, auto-advances on selection, and Enter-advances on text inputs |
-| `theme` | `ThemeConfig` | — | `{ color?, colorScheme?, style?, background?, surface?, text?, border?, radius?, fontFamily?, error?, success?, warning? }` — visual theme settings (palette knobs + preset) |
-| `navigation` | `NavigationConfig` | — | `{ transition?, allowInvalidTransition? }` — screen navigation settings |
+| `theme` | `ThemeConfig` | — | `{ color?, colorScheme?, style?, background?, surface?, text?, border?, radius?, fontFamily?, error?, success?, warning? }` — visual theme settings (palette knobs + preset). `fontFamily` is a CSS stack string **or** `{ family, src }` for a font FBRE loads itself |
+| `navigation` | `NavigationConfig` | — | `{ transition?, allowInvalidTransition?, autoAdvance?, advanceOnEnter? }` — screen navigation settings. `autoAdvance` (default `false`) advances ~500ms after a single-select choice; `advanceOnEnter` (default `true`) advances on Enter in a single-line input. Both only fire on a screen with exactly one visible input |
 | `controls` | `ControlsConfig` | — | `{ show?, layout?, showStepper?, stepperStyle? }` — navigation controls settings |
 | `confirmation` | `ConfirmationConfig` | — | `{ show?, title?, body? }` — terminal thank-you screen (see [Confirmation Screen](@sonata-innovations/fiber-fbre/docs/integration/fbre.md#confirmation-screen)) |
 | `summary` | `boolean` | `false` | Show summary screen before completion |

package/docs/schema/flow-schema.json

@@ -70,8 +70,11 @@
           "description": "Corner radius as a CSS length (--fbre-radius), e.g. '3px'."
         },
         "fontFamily": {
-          "type": "string",
-          "description": "Font family stack (--fbre-font)."
+          "description": "Font family (--fbre-font). A plain CSS stack string uses whatever font the host page already provides; an object additionally carries the sources FBRE registers itself via ensureFontLoaded, which is what makes a brand font work inside a shadow root.",
+          "oneOf": [
+            { "type": "string" },
+            { "$ref": "#/$defs/FontFamilyConfig" }
+          ]
         },
         "error": {
           "type": "string",
@@ -87,12 +90,79 @@
         },
         "style": {
           "type": "string",
-          "description": "Visual style for form elements. Standard mode styles: 'clean' = bottom-border inputs with uppercase labels (default). 'outlined' = full-border inputs with normal-case labels. 'refined-clean' = animated underline focus with left-accent groups. 'airy-clean' = spacious layout with tinted focus and pill buttons. 'soft-outlined' = full-border 8px radius with shadow-ring focus. 'defined-outlined' = filled-background inputs with top-accent groups. Conversational mode styles: 'centered-minimal' = thin underline inputs, bordered option cards, uppercase labels. 'stacked-cards' = filled background cards with left accent, keyboard shortcut badges. 'soft-float' = pill-shaped options with shadow lift on hover. 'bold-statement' = heavy borders, bold typography, inverted selection. Each style has a default stepper visual (see stepperStyle).",
+          "description": "Visual style for form elements. One flat vocabulary of ten, in two families. Form family: 'clean' = bottom-border inputs with uppercase labels (default). 'outlined' = full-border inputs with normal-case labels. 'refined-clean' = animated underline focus with left-accent groups. 'airy-clean' = spacious layout with tinted focus and pill buttons. 'soft-outlined' = full-border 8px radius with shadow-ring focus. 'defined-outlined' = filled-background inputs with top-accent groups. Focused family (adds vertical centering, staggered component entry, enlarged tap targets and bolder type): 'centered-minimal' = thin underline inputs, bordered option cards, uppercase labels. 'stacked-cards' = filled background cards with left accent, keyboard shortcut badges. 'soft-float' = pill-shaped options with shadow lift on hover. 'bold-statement' = heavy borders, bold typography, inverted selection. Each style has a default stepper visual (see stepperStyle).",
           "enum": ["clean", "outlined", "refined-clean", "airy-clean", "soft-outlined", "defined-outlined", "centered-minimal", "stacked-cards", "soft-float", "bold-statement"]
         }
       }
     },
 
+    "FontSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["url"],
+      "properties": {
+        "url": {
+          "type": "string",
+          "description": "Where the font file is served from."
+        },
+        "format": {
+          "type": "string",
+          "description": "CSS format() hint, e.g. 'woff2'."
+        }
+      }
+    },
+    "FontFaceConfig": {
+      "type": "object",
+      "description": "One @font-face — a single weight/style of the family.",
+      "additionalProperties": false,
+      "required": ["src"],
+      "properties": {
+        "src": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/FontSource" },
+          "minItems": 1
+        },
+        "weight": {
+          "type": "string",
+          "description": "CSS font-weight: '400', '700', or a variable range like '100 900'."
+        },
+        "style": {
+          "type": "string",
+          "enum": ["normal", "italic", "oblique"]
+        },
+        "display": {
+          "type": "string",
+          "enum": ["auto", "block", "swap", "fallback", "optional"]
+        },
+        "unicodeRange": { "type": "string" }
+      }
+    },
+    "FontFamilyConfig": {
+      "type": "object",
+      "description": "A brand font the renderer can load, rather than a family name it can only hope the host page already has.",
+      "additionalProperties": false,
+      "required": ["family"],
+      "properties": {
+        "family": {
+          "type": "string",
+          "description": "CSS family name, used for both the @font-face and the token value."
+        },
+        "src": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/FontSource" },
+          "description": "Shorthand for a single regular face. Merged with faces."
+        },
+        "faces": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/FontFaceConfig" },
+          "description": "Additional faces — a second weight, an italic."
+        },
+        "stack": {
+          "type": "string",
+          "description": "Full CSS stack written to --fbre-font. Defaults to the family plus a system fallback."
+        }
+      }
+    },
     "NavigationConfig": {
       "type": "object",
       "description": "Screen navigation settings.",
@@ -105,6 +175,14 @@
         "allowInvalidTransition": {
           "type": "boolean",
           "description": "Allow navigating forward even when the screen has validation errors."
+        },
+        "autoAdvance": {
+          "type": "boolean",
+          "description": "Advance to the next screen ~500ms after a single-select choice (radio, yesNo, cardSelect, dropDown). Default false. Only fires on a screen with exactly one visible input."
+        },
+        "advanceOnEnter": {
+          "type": "boolean",
+          "description": "Advance to the next screen when Enter is pressed in a single-line input (inputText, inputNumber). Default true. Never fires in a textarea, inside an open popup, on the last screen, on an invalid screen, or on a screen with more than one visible input."
         }
       }
     },
@@ -136,7 +214,7 @@
 
     "ConfirmationConfig": {
       "type": "object",
-      "description": "Terminal 'thank you' / confirmation screen shown after the flow is submitted. Presentation-only, so it lives on the config rather than as a Screen. Renders only when 'show' is not false and 'title' or 'body' has content (or the parent supplies an override via the onFlowComplete return value).",
+      "description": "Terminal 'thank you' / confirmation screen shown after the flow is submitted. Presentation-only, so it lives on the config rather than as a Screen. In local and remote modes it renders only when 'show' is not false and 'title' or 'body' has content (or the parent supplies an override via the onFlowComplete return value); server-driven mode falls back to a generic 'Thank you' when nothing is configured. An explicit 'show': false renders nothing in every mode.",
       "properties": {
         "show": {
           "type": "boolean",
@@ -157,11 +235,6 @@
       "type": "object",
       "description": "Runtime configuration for the flow.",
       "properties": {
-        "mode": {
-          "type": "string",
-          "description": "Form presentation mode. 'standard' = multi-field screens (default). 'conversational' = one-question-per-screen, vertically centered, with auto-advance on selection, Enter-to-advance on text inputs, and animated component entry.",
-          "enum": ["standard", "conversational"]
-        },
         "theme": { "$ref": "#/$defs/ThemeConfig" },
         "navigation": { "$ref": "#/$defs/NavigationConfig" },
         "controls": { "$ref": "#/$defs/ControlsConfig" },
@@ -250,7 +323,7 @@
           ]
         },
         "properties": {
-          "description": "Type-specific properties. JSON schema is the open ComponentProperties shape below; TypeScript narrows it per-type via the variant map in fiber-types/src/component-variants.ts.",
+          "description": "Type-specific properties. JSON schema is the open ComponentProperties shape below; TypeScript narrows it per-type via the variant map in types/src/component-variants.ts.",
           "$ref": "#/$defs/ComponentProperties"
         },
         "conditions": { "$ref": "#/$defs/FlowConditionConfig" },

package/docs/schema/flow-schema.md

@@ -1,7 +1,7 @@
 ---
 title: Flow JSON Schema Reference
 applies-to:
-  - "@sonata-innovations/fiber-types@^2.2"
+  - "@sonata-innovations/fiber-types@^3.0"
 read-when: "Exhaustive per-property reference for Flow JSON: every component type, property, condition, validation rule, calculation, and config field. For a compact overview use flow-quick-reference.md."
 ---
 
@@ -45,7 +45,6 @@ Runtime configuration for the flow, organized into semantic groups.
 
 | Field        | Type               | Required | Description                          |
 | ------------ | ------------------ | -------- | ------------------------------------ |
-| `mode`       | `FlowModeType`     | No       | Form presentation mode. See [Conversational Mode](#conversational-mode) |
 | `theme`      | `ThemeConfig`      | No       | Visual theme settings                |
 | `navigation` | `NavigationConfig` | No       | Screen navigation settings           |
 | `controls`   | `ControlsConfig`   | No       | Navigation controls settings         |
@@ -66,14 +65,45 @@ The theme has two layers: `colorScheme` + `style` pick built-in presets (the see
 | `text`       | `string`        | No       | Primary text color (`--fbre-text`); derives secondary/placeholder/label    |
 | `border`     | `string`        | No       | Border/rule color (`--fbre-border`); derives hover/light/subtle            |
 | `radius`     | `string`        | No       | Corner radius, any CSS length (`--fbre-radius`), e.g. `"3px"`               |
-| `fontFamily` | `string`        | No       | Font family stack (`--fbre-font`)                                           |
+| `fontFamily` | `string \| FontFamilyConfig` | No | Font family (`--fbre-font`). See [FontFamilyConfig](#fontfamilyconfig)   |
 | `error`      | `string`        | No       | Error state color (`--fbre-error`)                                          |
 | `success`    | `string`        | No       | Success state color (`--fbre-success`)                                      |
 | `warning`    | `string`        | No       | Warning state color (`--fbre-warning`)                                      |
 
+#### FontFamilyConfig
+
+A plain string is a CSS stack and nothing more: the form renders in that family only if the host page already loaded it, and falls back to `system-ui` otherwise — silently, and to something that looks approximately fine. Passing an object instead gives the renderer the sources, and FBRE registers the faces in the owning document itself.
+
+That matters most where the host cannot patch around it. FBRE is designed to mount inside a shadow root, and `@font-face` rules declared inside a shadow root's stylesheet are never registered — faces resolve at document level only.
+
+| Field    | Type               | Required | Description                                                        |
+| -------- | ------------------ | -------- | ------------------------------------------------------------------ |
+| `family` | `string`           | Yes      | CSS family name, used for both the `@font-face` and the token value |
+| `src`    | `FontSource[]`     | No       | Shorthand for a single regular face. Merged with `faces`            |
+| `faces`  | `FontFaceConfig[]` | No       | Additional faces — a second weight, an italic                       |
+| `stack`  | `string`           | No       | Full stack written to `--fbre-font`. Defaults to the family plus a system fallback |
+
+`FontSource` is `{ url, format? }`; `FontFaceConfig` is `{ src, weight?, style?, display?, unicodeRange? }`.
+
+```json
+{
+  "fontFamily": {
+    "family": "Brand Sans",
+    "src": [{ "url": "https://cdn.example.com/brand.woff2", "format": "woff2" }],
+    "faces": [
+      { "src": [{ "url": "https://cdn.example.com/brand-bold.woff2", "format": "woff2" }], "weight": "700" }
+    ]
+  }
+}
+```
+
+See [FBRE Theming Guide → Loading a brand font](@sonata-innovations/fiber-fbre/docs/features/fbre-theming.md#loading-a-brand-font).
+
 #### Style Types
 
-**Standard mode styles** (6):
+Ten values, one flat vocabulary. Any style may be used on any flow.
+
+**Form family** (6):
 
 | Value | Description |
 | --- | --- |
@@ -84,7 +114,7 @@ The theme has two layers: `colorScheme` + `style` pick built-in presets (the see
 | `"soft-outlined"` | Full-border 8px radius with shadow-ring focus |
 | `"defined-outlined"` | Filled-background inputs with top-accent groups |
 
-**Conversational mode styles** (4):
+**Focused family** (4):
 
 | Value | Description |
 | --- | --- |
@@ -93,7 +123,9 @@ The theme has two layers: `colorScheme` + `style` pick built-in presets (the see
 | `"soft-float"` | Pill-shaped options (24px radius) with shadow lift on hover, rounded inputs and buttons |
 | `"bold-statement"` | 2px borders, 700-weight 24px headers, inverted selection (dark fill + white text), filled input backgrounds |
 
-Each style has a default stepper visual (see `stepperStyle`). When switching form mode in FBT, the style auto-switches to the first style of the target mode.
+The four focused styles additionally share a presentation treatment — vertical centering, a narrow column, staggered component entry, enlarged tap targets and bolder type. That shared half is the **focused family**; see [Style Families](#style-families).
+
+Each style has a default stepper visual (see `stepperStyle`).
 
 ### NavigationConfig
 
@@ -101,6 +133,8 @@ Each style has a default stepper visual (see `stepperStyle`). When switching for
 | ------------------------ | ---------------------- | -------- | --------------------------------------------------------------------------- |
 | `transition`             | `ScreenTransitionType` | No       | Screen transition animation type. See [Screen Transitions](#screen-transitions) |
 | `allowInvalidTransition` | `boolean`              | No       | Allow navigating forward even when the screen has validation errors         |
+| `autoAdvance`            | `boolean`              | No       | Advance ~500ms after a single-select choice. Default `false`. See [Advance Behaviors](#advance-behaviors) |
+| `advanceOnEnter`         | `boolean`              | No       | Advance when Enter is pressed in a single-line input. Default `true`. See [Advance Behaviors](#advance-behaviors) |
 
 ### ControlsConfig
 
@@ -113,7 +147,7 @@ Each style has a default stepper visual (see `stepperStyle`). When switching for
 
 ### ConfirmationConfig
 
-A terminal "thank you" screen shown after the flow is submitted (once `onFlowComplete` resolves). It is presentation-only — not a data-collection `Screen` — so it lives on the config. The screen renders only when `show` is not `false` **and** `title` or `body` has content. When shown, it replaces the final screen and the navigation controls/stepper are hidden.
+A terminal "thank you" screen shown after the flow is submitted (once `onFlowComplete` resolves). It is presentation-only — not a data-collection `Screen` — so it lives on the config. In local and remote modes the screen renders only when `show` is not `false` **and** `title` or `body` has content; server-driven mode falls back to a generic "Thank you" when nothing is configured, and renders nothing on an explicit `show: false` (see [Per-mode behavior](@sonata-innovations/fiber-fbre/docs/features/confirmation-screen.md#per-mode-behavior)). When shown, it replaces the final screen and the navigation controls/stepper are hidden.
 
 `title` and `body` support the same `${...}` reference markup as display components — references resolve against collected field values, calculations, and external `context` values (by name). A parent application can also override the configured message at runtime by returning (or resolving with) a `{ title?, body? }` object from `onFlowComplete` — useful for post-submit data such as a server-generated reference number.
 
@@ -125,42 +159,71 @@ A terminal "thank you" screen shown after the flow is submitted (once `onFlowCom
 
 ---
 
-## Conversational Mode
+## Style Families
 
-Set `config.mode` to `"conversational"` to transform FBRE into a one-question-per-screen experience optimized for completion rates.
+The ten `FlowStyleType` values are a flat vocabulary — any style is valid on any
+flow — but four of them share a presentation treatment. That shared half is a
+**family**, derived from the style itself:
 
-**`FlowModeType`**: `"standard"` | `"conversational"` (default: `"standard"`)
+| Family | Styles |
+| --- | --- |
+| `"form"` | `clean`, `outlined`, `refined-clean`, `airy-clean`, `soft-outlined`, `defined-outlined` |
+| `"focused"` | `centered-minimal`, `stacked-cards`, `soft-float`, `bold-statement` |
 
-### Behaviors
+The focused family adds, on top of whichever of the four styles is selected:
 
-| Behavior | Description |
+| Treatment | Description |
 | --- | --- |
-| **Vertical centering** | Content is vertically and horizontally centered within the viewport |
-| **Auto-advance** | Single-select components (`radio`, `yesNo`, `cardSelect`, `dropDown`) advance to the next screen ~500ms after selection. Multi-select (`checkbox`, `dropDownMulti`) does NOT auto-advance |
-| **Enter-to-advance** | Pressing Enter on `inputText` / `inputNumber` advances to the next screen. `inputTextArea` is excluded (Enter inserts newlines) |
+| **Vertical centering** | Content is vertically and horizontally centered within a narrow column |
 | **Animated entry** | Components fade + scale in with staggered delays on screen transitions. Respects `prefers-reduced-motion` |
-| **Larger tap targets** | Yes/No buttons, option items, card-select cards, and input fields are enlarged for easier tapping |
+| **Larger tap targets** | Yes/No buttons, option items, card-select cards and input fields are enlarged for easier tapping |
+| **Bolder type** | Headers, labels, prompts and inputs step up in size |
 
-### Conversational styles
+The family is **never authored** — it does not appear in Flow JSON. FBRE derives
+it and emits it as `data-style-family` alongside `data-style`. `fiber-types`
+exports the derivation for builders that want to group a style picker by family:
 
-Conversational mode has 4 dedicated styles (separate from the 6 standard styles):
+```ts
+import { FOCUSED_STYLES, styleFamily } from "@sonata-innovations/fiber-types";
 
-| Style | Personality |
-| --- | --- |
-| `centered-minimal` | Thin underline inputs, bordered option cards, uppercase labels, theme-tinted hover/selected |
-| `stacked-cards` | Filled background cards with left accent bar, keyboard shortcut badges (A, B, C, D) on options |
-| `soft-float` | Pill-shaped options with shadow lift on hover, rounded inputs and buttons |
-| `bold-statement` | Heavy borders, bold typography, inverted selection (dark fill + white text) |
+styleFamily("bold-statement"); // "focused"
+styleFamily("clean");          // "form"
+styleFamily(undefined);        // "form"
+```
+
+Because the family derives from `theme.style`, presentation travels with the
+theme through every render path — local, remote and server-driven alike.
 
-When switching to conversational mode in FBT, the style auto-switches to `"centered-minimal"` and the transition to `"scaleFade"`.
+---
+
+## Advance Behaviors
+
+Auto-advance and Enter-to-advance are independent `navigation` flags. They are
+**not** tied to a style or a family: a `clean` form with one question per screen
+gets Enter-to-advance, and a `bold-statement` flow only auto-advances if it asks
+to.
+
+| Flag | Default | Behavior |
+| --- | --- | --- |
+| `navigation.autoAdvance` | `false` | Single-select components (`radio`, `yesNo`, `cardSelect`, `dropDown`) advance to the next screen ~500ms after selection. Multi-select (`checkbox`, `dropDownMulti`) never auto-advances |
+| `navigation.advanceOnEnter` | `true` | Pressing Enter in an `inputText` / `inputNumber` advances to the next screen. `inputTextArea` is excluded (Enter inserts newlines) |
+
+`autoAdvance` defaults off because a form that moves without a click is
+surprising and shifts content ~500ms after a selection. `advanceOnEnter`
+defaults on because Enter-to-advance is an ordinary form convention.
 
 ### Guards
 
-- Auto-advance does **not** fire on the last screen
-- Auto-advance does **not** fire if the screen fails validation
-- Auto-advance respects condition-hidden screens (skips them)
-- Auto-advance does **not** fire during an active transition
-- Enter-to-advance validates the screen before advancing
+Both behaviors share the same guards, and they are not configurable:
+
+- Neither fires on a screen with **more than one visible input** — a shared
+  screen behaves like a normal form so later components aren't skipped
+- Neither fires on the last screen (so Enter can never submit)
+- Neither fires if the screen fails validation
+- Both respect condition-hidden screens (they skip them)
+- Auto-advance does not fire during an active transition
+- Enter-to-advance does not fire inside an open popup (date picker, colour
+  picker, dropdown panel) — the overlay keeps its Enter
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sonata-innovations/fiber-types",
-	"version": "2.3.0",
+	"version": "3.0.0",
 	"description": "TypeScript type definitions for the Fiber form builder system",
 	"keywords": [
 		"fiber",