@sonata-innovations/fiber-types 2.5.0 → 3.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +2 -0
- package/CHANGELOG.md +30 -0
- package/README.md +4 -0
- package/dist/flow.d.ts +19 -2
- package/dist/flow.d.ts.map +1 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/style-family.d.ts +8 -0
- package/dist/style-family.d.ts.map +1 -0
- package/dist/style-family.js +27 -0
- package/docs/features/custom-presets-and-templates.md +2 -2
- package/docs/features/style-families.md +217 -0
- package/docs/fiber-concepts.md +18 -9
- package/docs/schema/flow-data-schema.md +2 -2
- package/docs/schema/flow-quick-reference.md +2 -3
- package/docs/schema/flow-schema.json +9 -6
- package/docs/schema/flow-schema.md +62 -28
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -30,10 +30,12 @@ npx ajv-cli validate --spec=draft2020 \
|
|
|
30
30
|
- **Condition & validation types** — `FlowConditionConfig`, `ConditionRule`, `ConditionOperator` (19 operators), `FlowValidationConfig`, `ValidationRule` (17 validators)
|
|
31
31
|
- **Preset/template data** — `PresetData`, `TemplateData` (the serializable definitions FBT accepts)
|
|
32
32
|
- **Component manifest** — `COMPONENT_VARIANT_TYPES`, `ComponentType`, `ComponentOfType<K>`, `ComponentPropertiesByType`
|
|
33
|
+
- **Style families** — `FOCUSED_STYLES`, `styleFamily()`, `StyleFamily`. The four focused styles and the derivation from a `FlowStyleType` to `"form"` | `"focused"`
|
|
33
34
|
- **Utilities** — `generateUUID`, `regenerateComponentUUIDs`, `regenerateFlowUUIDs`, `normalizeConditionalOrder`, `getValidationConfig`, `getComponentDisplayLabel`
|
|
34
35
|
|
|
35
36
|
## Facts worth knowing before you generate a Flow
|
|
36
37
|
|
|
38
|
+
- **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`.
|
|
37
39
|
- **30 component types.** Display types (`header`, `text`, `divider`, `callout`, `table`) never appear in FlowData; `computed` does.
|
|
38
40
|
- **19 condition operators, 17 validators.** Exact lists are in the quick reference.
|
|
39
41
|
- **Validation `pattern` rules take `params.regex`**, not `params.pattern`. A `pattern` key is ignored and the rule silently always passes.
|
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,36 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to the Fiber schema types. Dates are release dates.
|
|
4
4
|
|
|
5
|
+
## 3.0.1 — 2026-08-20
|
|
6
|
+
|
|
7
|
+
### Fixed
|
|
8
|
+
|
|
9
|
+
- **`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.
|
|
10
|
+
|
|
11
|
+
Documentation only; no code, type or schema change. `docs/features/style-families.md` shipped correct in 3.0.0 and is unchanged.
|
|
12
|
+
|
|
13
|
+
## 3.0.0 — 2026-08-20
|
|
14
|
+
|
|
15
|
+
### Removed — BREAKING
|
|
16
|
+
|
|
17
|
+
- **`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.
|
|
18
|
+
|
|
19
|
+
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).
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
- **`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.
|
|
24
|
+
|
|
25
|
+
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).
|
|
26
|
+
|
|
27
|
+
- **`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.
|
|
28
|
+
- **`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.
|
|
29
|
+
|
|
30
|
+
### Changed
|
|
31
|
+
|
|
32
|
+
- `FlowStyleType` keeps all ten values and is now a **flat** vocabulary. Nothing partitions it; any style is valid on any flow.
|
|
33
|
+
- `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.
|
|
34
|
+
|
|
5
35
|
## 2.5.0 — 2026-08-20
|
|
6
36
|
|
|
7
37
|
### Added
|
package/README.md
CHANGED
|
@@ -53,6 +53,7 @@ import type {
|
|
|
53
53
|
FlowValidationConfig, ValidationRule,
|
|
54
54
|
PresetData, TemplateData,
|
|
55
55
|
ComponentType, ComponentOfType, ComponentPropertiesByType,
|
|
56
|
+
FlowStyleType, StyleFamily,
|
|
56
57
|
} from "@sonata-innovations/fiber-types";
|
|
57
58
|
|
|
58
59
|
import {
|
|
@@ -63,6 +64,8 @@ import {
|
|
|
63
64
|
getValidationConfig,
|
|
64
65
|
getComponentDisplayLabel,
|
|
65
66
|
COMPONENT_VARIANT_TYPES,
|
|
67
|
+
FOCUSED_STYLES,
|
|
68
|
+
styleFamily,
|
|
66
69
|
} from "@sonata-innovations/fiber-types";
|
|
67
70
|
```
|
|
68
71
|
|
|
@@ -82,6 +85,7 @@ if (component.type === "inputText") {
|
|
|
82
85
|
|
|
83
86
|
## Gotchas
|
|
84
87
|
|
|
88
|
+
- **`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`.
|
|
85
89
|
- **`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.
|
|
86
90
|
- **30 component types.** Display types (`header`, `text`, `divider`, `callout`, `table`) never appear in FlowData; `computed` does.
|
|
87
91
|
- **`pattern` validation rules take `params.regex`**, not `params.pattern`. A `pattern` key is silently ignored and the rule always passes.
|
package/dist/flow.d.ts
CHANGED
|
@@ -5,7 +5,6 @@ export type ScreenTransitionType = "none" | "slide" | "fade" | "slideFade" | "ri
|
|
|
5
5
|
export type FlowStyleType = "clean" | "outlined" | "refined-clean" | "airy-clean" | "soft-outlined" | "defined-outlined" | "centered-minimal" | "stacked-cards" | "soft-float" | "bold-statement";
|
|
6
6
|
export type ControlsLayout = "default" | "centered" | "inline-full" | "stacked";
|
|
7
7
|
export type StepperStyle = "default" | "dots" | "pill" | "glow" | "bar" | "text";
|
|
8
|
-
export type FlowModeType = "standard" | "conversational";
|
|
9
8
|
export type FlowMetadata = Record<string, string> & {
|
|
10
9
|
name?: string;
|
|
11
10
|
description?: string;
|
|
@@ -99,6 +98,25 @@ export type ThemeConfig = {
|
|
|
99
98
|
export type NavigationConfig = {
|
|
100
99
|
transition?: ScreenTransitionType;
|
|
101
100
|
allowInvalidTransition?: boolean;
|
|
101
|
+
/**
|
|
102
|
+
* Advance to the next screen ~500ms after a single-select choice
|
|
103
|
+
* (radio, yesNo, cardSelect, dropDown). Default `false` — a form that
|
|
104
|
+
* moves without a click is surprising, and the content shift carries an
|
|
105
|
+
* accessibility cost, so it is opt-in. The builders' focused presets turn
|
|
106
|
+
* it on.
|
|
107
|
+
*
|
|
108
|
+
* Only ever fires on a screen with exactly one visible input; a shared
|
|
109
|
+
* screen behaves like a normal form so later components aren't skipped.
|
|
110
|
+
*/
|
|
111
|
+
autoAdvance?: boolean;
|
|
112
|
+
/**
|
|
113
|
+
* Advance to the next screen when Enter is pressed in a single-line input
|
|
114
|
+
* (`inputText`, `inputNumber`). Default `true` — Enter-to-advance is a form
|
|
115
|
+
* convention, not a flourish. Never fires in a textarea, inside an open
|
|
116
|
+
* popup, on the last screen, on an invalid screen, or on a screen with more
|
|
117
|
+
* than one visible input.
|
|
118
|
+
*/
|
|
119
|
+
advanceOnEnter?: boolean;
|
|
102
120
|
};
|
|
103
121
|
export type ControlsConfig = {
|
|
104
122
|
show?: boolean;
|
|
@@ -126,7 +144,6 @@ export type ConfirmationConfig = {
|
|
|
126
144
|
body?: string;
|
|
127
145
|
};
|
|
128
146
|
export type FlowConfiguration = {
|
|
129
|
-
mode?: FlowModeType;
|
|
130
147
|
theme?: ThemeConfig;
|
|
131
148
|
navigation?: NavigationConfig;
|
|
132
149
|
controls?: ControlsConfig;
|
package/dist/flow.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../src/flow.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EACV,yBAAyB,EACzB,aAAa,EACd,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,oBAAoB,GAC5B,MAAM,GACN,OAAO,GACP,MAAM,GACN,WAAW,GACX,MAAM,GACN,WAAW,CAAC;AAEhB,MAAM,MAAM,aAAa,GACrB,OAAO,GACP,UAAU,GACV,eAAe,GACf,YAAY,GACZ,eAAe,GACf,kBAAkB,GAClB,kBAAkB,GAClB,eAAe,GACf,YAAY,GACZ,gBAAgB,CAAC;AAErB,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,CAAC;AAEhF,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAEjF,MAAM,MAAM,YAAY,GAAG,
|
|
1
|
+
{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../src/flow.ts"],"names":[],"mappings":"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"}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
|
-
export type { Flow, FlowScreen, FlowConfiguration, ThemeConfig, ColorScheme, NavigationConfig, ControlsConfig, FontSource, FontFaceConfig, FontFamilyConfig, ConfirmationConfig, FlowMetadata, Component, ComponentOfType, ComponentProperties, ScreenTransitionType, FlowStyleType, ControlsLayout, StepperStyle,
|
|
1
|
+
export type { Flow, FlowScreen, FlowConfiguration, ThemeConfig, ColorScheme, NavigationConfig, ControlsConfig, FontSource, FontFaceConfig, FontFamilyConfig, ConfirmationConfig, FlowMetadata, Component, ComponentOfType, ComponentProperties, ScreenTransitionType, FlowStyleType, ControlsLayout, StepperStyle, } from "./flow.js";
|
|
2
2
|
export type { ComponentType, ComponentPropertiesByType, } from "./component-variants.js";
|
|
3
3
|
export { COMPONENT_VARIANT_TYPES, assertManifestTypeMapParity, } from "./component-variants.js";
|
|
4
4
|
export type { ConditionAction, ConditionLogic, ConditionOperator, ConditionRule, ConditionRuleSource, ConditionGroup, FlowConditionConfig, } from "./conditions.js";
|
|
5
5
|
export type { ValidationRuleType, ValidationRule, FlowValidationConfig, } from "./validation.js";
|
|
6
6
|
export { generateUUID } from "./uuid.js";
|
|
7
7
|
export { normalizeOptions } from "./normalize-options.js";
|
|
8
|
+
export { FOCUSED_STYLES, styleFamily } from "./style-family.js";
|
|
9
|
+
export type { StyleFamily } from "./style-family.js";
|
|
8
10
|
export type { FlowData, ScreenData, ComponentData, CalculationData, FileUploadData, FileUploadBase64Data, FileUploadS3Data, RangeValue, } from "./flow-data.js";
|
|
9
11
|
export { regenerateComponentUUIDs, regenerateFlowUUIDs, } from "./uuid-regeneration.js";
|
|
10
12
|
export { normalizeConditionalOrder } from "./normalize-conditional-order.js";
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,IAAI,EACJ,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,cAAc,EACd,YAAY,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,IAAI,EACJ,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,cAAc,EACd,YAAY,GACb,MAAM,WAAW,CAAC;AAEnB,YAAY,EACV,aAAa,EACb,yBAAyB,GAC1B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EACV,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,cAAc,EACd,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,YAAY,EACV,QAAQ,EACR,UAAU,EACV,aAAa,EACb,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,GACX,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAE7E,OAAO,EACL,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE1E,YAAY,EACV,iBAAiB,EACjB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EACV,cAAc,EACd,UAAU,EACV,0BAA0B,EAC1B,0BAA0B,EAC1B,kBAAkB,EAClB,wBAAwB,EACxB,UAAU,EACV,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,6BAA6B,EAC7B,wBAAwB,EACxB,2BAA2B,EAC3B,uBAAuB,EACvB,uBAAuB,EACvB,2BAA2B,EAC3B,4BAA4B,EAC5B,4BAA4B,EAC5B,gCAAgC,EAChC,wBAAwB,EACxB,0BAA0B,EAC1B,8BAA8B,EAC9B,gBAAgB,EAChB,6BAA6B,EAC7B,uBAAuB,EACvB,0BAA0B,EAC1B,WAAW,EACX,QAAQ,EACR,wBAAwB,EACxB,aAAa,EACb,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
export { COMPONENT_VARIANT_TYPES, assertManifestTypeMapParity, } from "./component-variants.js";
|
|
2
2
|
export { generateUUID } from "./uuid.js";
|
|
3
3
|
export { normalizeOptions } from "./normalize-options.js";
|
|
4
|
+
export { FOCUSED_STYLES, styleFamily } from "./style-family.js";
|
|
4
5
|
export { regenerateComponentUUIDs, regenerateFlowUUIDs, } from "./uuid-regeneration.js";
|
|
5
6
|
export { normalizeConditionalOrder } from "./normalize-conditional-order.js";
|
|
6
7
|
export { getValidationConfig, getComponentDisplayLabel, } from "./component-accessors.js";
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { FlowStyleType } from "./flow.js";
|
|
2
|
+
/** The four styles whose presentation is the focused treatment. */
|
|
3
|
+
export declare const FOCUSED_STYLES: ReadonlySet<FlowStyleType>;
|
|
4
|
+
export type StyleFamily = "form" | "focused";
|
|
5
|
+
/** Which family a style belongs to. Unset styles are `"form"` (the `clean`
|
|
6
|
+
* default). */
|
|
7
|
+
export declare function styleFamily(style?: FlowStyleType): StyleFamily;
|
|
8
|
+
//# sourceMappingURL=style-family.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"style-family.d.ts","sourceRoot":"","sources":["../src/style-family.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,mEAAmE;AACnE,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,aAAa,CAKpD,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,CAAC;AAE7C;gBACgB;AAChB,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,WAAW,CAE9D"}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/* ==========================================================================
|
|
2
|
+
Style families
|
|
3
|
+
Spec: docs/features/style-families.md
|
|
4
|
+
|
|
5
|
+
The ten `FlowStyleType` values form a flat vocabulary, but four of them
|
|
6
|
+
share a presentation treatment — vertical centering, staggered component
|
|
7
|
+
entry, enlarged tap targets, bolder type. That shared half is the
|
|
8
|
+
`"focused"` family; everything else is `"form"`.
|
|
9
|
+
|
|
10
|
+
The family is *derived*, never authored: no flow JSON carries it and no
|
|
11
|
+
author types it. FBRE emits it as `data-style-family` so the shared rules
|
|
12
|
+
have one selector instead of a repeated four-way list. Because it derives
|
|
13
|
+
from `theme.style`, every render path that carries the theme carries the
|
|
14
|
+
presentation with it — including the session protocol.
|
|
15
|
+
========================================================================== */
|
|
16
|
+
/** The four styles whose presentation is the focused treatment. */
|
|
17
|
+
export const FOCUSED_STYLES = new Set([
|
|
18
|
+
"centered-minimal",
|
|
19
|
+
"stacked-cards",
|
|
20
|
+
"soft-float",
|
|
21
|
+
"bold-statement",
|
|
22
|
+
]);
|
|
23
|
+
/** Which family a style belongs to. Unset styles are `"form"` (the `clean`
|
|
24
|
+
* default). */
|
|
25
|
+
export function styleFamily(style) {
|
|
26
|
+
return style && FOCUSED_STYLES.has(style) ? "focused" : "form";
|
|
27
|
+
}
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Custom Presets & Templates (FBT)
|
|
3
3
|
applies-to:
|
|
4
|
-
- "@sonata-innovations/fiber-fbt@^
|
|
5
|
-
- "@sonata-innovations/fiber-types@^
|
|
4
|
+
- "@sonata-innovations/fiber-fbt@^3.0"
|
|
5
|
+
- "@sonata-innovations/fiber-types@^3.0"
|
|
6
6
|
read-when: "Extending FBT's pool with custom presets/templates: data-based vs factory definitions, icon catalog, collision rules, server-stored definitions."
|
|
7
7
|
---
|
|
8
8
|
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Style Families & Advance Behaviors
|
|
3
|
+
applies-to:
|
|
4
|
+
- "@sonata-innovations/fiber-fbre@^4.0"
|
|
5
|
+
- "@sonata-innovations/fiber-types@^3.0"
|
|
6
|
+
- "@sonata-innovations/fiber-fbt@^3.0"
|
|
7
|
+
- "@sonata-innovations/fiber-fbtl@^3.0"
|
|
8
|
+
- "@sonata-innovations/fiber-theme-editor@^2.0"
|
|
9
|
+
read-when: "Choosing a form style, understanding the focused presentation, or turning auto-advance / Enter-to-advance on and off. Also: migrating off config.mode."
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
<!-- Generated from the Fiber repo's docs/ tree by project/scripts/sync-package-docs.mjs. Do not edit here. -->
|
|
13
|
+
# Style Families & Advance Behaviors
|
|
14
|
+
|
|
15
|
+
A Fiber form's presentation is decided by one setting — `config.theme.style` —
|
|
16
|
+
and its two advance behaviors by two more — `config.navigation.autoAdvance` and
|
|
17
|
+
`config.navigation.advanceOnEnter`. That is the whole model. There is no
|
|
18
|
+
presentation mode.
|
|
19
|
+
|
|
20
|
+
> **Migrating from an earlier version?** `config.mode` (`"standard"` /
|
|
21
|
+
> `"conversational"`) was removed. Jump to [Migrating off `config.mode`](#migrating-off-configmode).
|
|
22
|
+
|
|
23
|
+
## The ten styles are one flat vocabulary
|
|
24
|
+
|
|
25
|
+
Any style is valid on any flow. Four of them share an extra presentation
|
|
26
|
+
treatment, and that shared half is called a **family**:
|
|
27
|
+
|
|
28
|
+
| Family | Styles |
|
|
29
|
+
| --- | --- |
|
|
30
|
+
| `"form"` | `clean`, `outlined`, `refined-clean`, `airy-clean`, `soft-outlined`, `defined-outlined` |
|
|
31
|
+
| `"focused"` | `centered-minimal`, `stacked-cards`, `soft-float`, `bold-statement` |
|
|
32
|
+
|
|
33
|
+
On top of whichever of the four you pick, the focused family adds:
|
|
34
|
+
|
|
35
|
+
| Treatment | What it does |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| **Vertical centering** | Content sits centered in a narrow column, falling back to top-aligned and scrollable when a screen is taller than the viewport |
|
|
38
|
+
| **Animated entry** | Components fade and scale in with staggered delays. Respects `prefers-reduced-motion` |
|
|
39
|
+
| **Larger tap targets** | Option items, Yes/No buttons, card-select cards and inputs are enlarged |
|
|
40
|
+
| **Bolder type** | Headers, labels, prompts and inputs step up in size |
|
|
41
|
+
|
|
42
|
+
Each of the four styles then applies its own look — underline inputs, filled
|
|
43
|
+
cards, pill options, heavy borders — exactly as each of the six form styles
|
|
44
|
+
does.
|
|
45
|
+
|
|
46
|
+
### The family is derived, never authored
|
|
47
|
+
|
|
48
|
+
It does not appear in Flow JSON. FBRE computes it from `theme.style` and emits
|
|
49
|
+
it on the container as `data-style-family`, next to `data-style`:
|
|
50
|
+
|
|
51
|
+
```html
|
|
52
|
+
<div class="fbre-container" data-style="soft-float" data-style-family="focused">
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
That is what lets the ~32 shared rules live under one selector instead of a
|
|
56
|
+
repeated four-way list. If you write custom CSS against a focused form, target
|
|
57
|
+
`[data-style-family="focused"]` for anything that should apply to all four and
|
|
58
|
+
`[data-style="…"]` for one style.
|
|
59
|
+
|
|
60
|
+
`fiber-types` (and `fiber-fbre`, which re-exports it) publishes the derivation
|
|
61
|
+
so a builder can group its own style picker from one list:
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
import { FOCUSED_STYLES, styleFamily } from "@sonata-innovations/fiber-types";
|
|
65
|
+
|
|
66
|
+
styleFamily("bold-statement"); // "focused"
|
|
67
|
+
styleFamily("clean"); // "form"
|
|
68
|
+
styleFamily(undefined); // "form" — the `clean` default
|
|
69
|
+
|
|
70
|
+
FOCUSED_STYLES.has("soft-float"); // true
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Why this matters for server-driven rendering
|
|
74
|
+
|
|
75
|
+
The session protocol sends `config.theme`. Because presentation is *derived
|
|
76
|
+
from* `theme.style`, a focused-styled flow renders identically whether it is
|
|
77
|
+
rendered locally, fetched remotely, or served one screen at a time by a
|
|
78
|
+
session — no extra field has to be carried, and none can be forgotten.
|
|
79
|
+
|
|
80
|
+
## Advance behaviors
|
|
81
|
+
|
|
82
|
+
Auto-advance and Enter-to-advance are independent `navigation` flags. Neither is
|
|
83
|
+
tied to a style: a `clean` form with one question per screen advances on Enter,
|
|
84
|
+
and a `bold-statement` flow only auto-advances if it asks to.
|
|
85
|
+
|
|
86
|
+
| Flag | Default | Behavior |
|
|
87
|
+
| --- | --- | --- |
|
|
88
|
+
| `navigation.autoAdvance` | `false` | Advance to the next screen ~500ms after a single-select choice — `radio`, `yesNo`, `cardSelect`, `dropDown`. Multi-select (`checkbox`, `dropDownMulti`) never auto-advances |
|
|
89
|
+
| `navigation.advanceOnEnter` | `true` | Advance when Enter is pressed in an `inputText` or `inputNumber`. `inputTextArea` is excluded — Enter inserts a newline there |
|
|
90
|
+
|
|
91
|
+
```jsonc
|
|
92
|
+
{
|
|
93
|
+
"config": {
|
|
94
|
+
"theme": { "style": "centered-minimal" },
|
|
95
|
+
"navigation": {
|
|
96
|
+
"transition": "scaleFade",
|
|
97
|
+
"autoAdvance": true,
|
|
98
|
+
"advanceOnEnter": true
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
The defaults are deliberately asymmetric. A form that moves without a click is
|
|
105
|
+
surprising, and shifting content and focus ~500ms after a selection carries a
|
|
106
|
+
real accessibility cost — so `autoAdvance` is opt-in. Enter-to-advance is an
|
|
107
|
+
ordinary form convention, so it is on.
|
|
108
|
+
|
|
109
|
+
### Guards
|
|
110
|
+
|
|
111
|
+
Both behaviors share the same guards. None of them are configurable — they are
|
|
112
|
+
correctness guards, not policy:
|
|
113
|
+
|
|
114
|
+
- Neither fires on a screen with **more than one visible input**. A shared
|
|
115
|
+
screen behaves like a normal form, so components after the first are never
|
|
116
|
+
skipped. (Conditionally hidden inputs don't count toward the total.)
|
|
117
|
+
- Neither fires on the last screen — so Enter can never submit the form.
|
|
118
|
+
- Neither fires when the screen fails validation.
|
|
119
|
+
- Both respect condition-hidden screens, skipping to the next reachable one.
|
|
120
|
+
- Auto-advance does not fire during an active screen transition.
|
|
121
|
+
- Enter-to-advance stands down inside an open popup (`.fbre-popup`), so Enter
|
|
122
|
+
there commits the value rather than skipping the screen. Today this affects
|
|
123
|
+
one component: the colour picker's hex field is the only `<input>` rendered
|
|
124
|
+
inside an overlay. The date/time pickers and both dropdowns use buttons and
|
|
125
|
+
`role="option"` elements, which Enter-to-advance already ignores.
|
|
126
|
+
|
|
127
|
+
The single-visible-input guard is worth designing around: turning `autoAdvance`
|
|
128
|
+
on for a flow whose screens hold several questions each does nothing at all.
|
|
129
|
+
Both builders say so — FBT warns on a multi-input screen tab, FBTL notes it on
|
|
130
|
+
the divider that merges two cards onto one screen.
|
|
131
|
+
|
|
132
|
+
## In the builders
|
|
133
|
+
|
|
134
|
+
Neither builder stores a mode. Each offers a preset that writes the settings the
|
|
135
|
+
focused look is made of, after which every one of them stays individually
|
|
136
|
+
editable:
|
|
137
|
+
|
|
138
|
+
- **FBT** — a *Focused presentation* preset in the Appearance section writes
|
|
139
|
+
`theme.style: "centered-minimal"` and `navigation: { transition: "scaleFade",
|
|
140
|
+
autoAdvance: true }`. The style picker lists all ten styles, captioned *Form*
|
|
141
|
+
and *Focused*.
|
|
142
|
+
- **FBTL** — its default config already uses `centered-minimal` with
|
|
143
|
+
`autoAdvance: true`. Pacing (one question per screen vs all on one page) is a
|
|
144
|
+
separate concern there: see `screenModel` in the
|
|
145
|
+
[FBTL Integration Guide](@sonata-innovations/fiber-fbtl/docs/integration/fbtl.md#screen-model).
|
|
146
|
+
- **Theme Editor** — the style dropdown lists all ten, grouped under *Form* and
|
|
147
|
+
*Focused* headings. Its value is `{ theme }`.
|
|
148
|
+
|
|
149
|
+
## Migrating off `config.mode`
|
|
150
|
+
|
|
151
|
+
`FlowConfiguration.mode`, the `FlowModeType` type, and FBRE's `mode` prop are
|
|
152
|
+
gone. Each of `mode`'s jobs moved somewhere it belongs:
|
|
153
|
+
|
|
154
|
+
| Was | Now |
|
|
155
|
+
| --- | --- |
|
|
156
|
+
| `mode: "conversational"` for the centered, animated presentation | the focused **style** already on the flow — nothing to set |
|
|
157
|
+
| `mode: "conversational"` for auto-advance | `navigation.autoAdvance: true` |
|
|
158
|
+
| `mode: "conversational"` for Enter-to-advance | `navigation.advanceOnEnter` — on by default now, for every flow |
|
|
159
|
+
| `mode` deciding which styles were legal | nothing — the vocabulary is flat |
|
|
160
|
+
|
|
161
|
+
### Updating a stored flow
|
|
162
|
+
|
|
163
|
+
A flow that had `mode: "conversational"` already carried a focused
|
|
164
|
+
`theme.style`, so **its look survives untouched**. The only behavior that
|
|
165
|
+
changes is auto-advance, which is now off unless asked for:
|
|
166
|
+
|
|
167
|
+
```jsonc
|
|
168
|
+
// before
|
|
169
|
+
{ "config": {
|
|
170
|
+
"mode": "conversational",
|
|
171
|
+
"theme": { "style": "centered-minimal" },
|
|
172
|
+
"navigation": { "transition": "scaleFade" }
|
|
173
|
+
} }
|
|
174
|
+
|
|
175
|
+
// after
|
|
176
|
+
{ "config": {
|
|
177
|
+
"theme": { "style": "centered-minimal" },
|
|
178
|
+
"navigation": { "transition": "scaleFade", "autoAdvance": true }
|
|
179
|
+
} }
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
A flow that had `mode: "standard"` (or no `mode` at all) needs only the field
|
|
183
|
+
deleted. It gains Enter-to-advance on its one-question screens, which was
|
|
184
|
+
previously withheld for no reason anyone could see.
|
|
185
|
+
|
|
186
|
+
`mode` is not read anywhere any more, so leaving a stale `"mode"` key in stored
|
|
187
|
+
JSON is inert rather than harmful — but the schema no longer describes it, and
|
|
188
|
+
`npm run validate` will not vouch for it.
|
|
189
|
+
|
|
190
|
+
### Updating code
|
|
191
|
+
|
|
192
|
+
```diff
|
|
193
|
+
-<FBRE flow={flow} mode="conversational" onFlowComplete={done} />
|
|
194
|
+
+<FBRE
|
|
195
|
+
+ flow={flow}
|
|
196
|
+
+ theme={{ style: "centered-minimal" }}
|
|
197
|
+
+ navigation={{ autoAdvance: true }}
|
|
198
|
+
+ onFlowComplete={done}
|
|
199
|
+
+/>
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
```diff
|
|
203
|
+
-<ThemeEditor mode={value.mode} theme={value.theme} onChange={setValue} />
|
|
204
|
+
+<ThemeEditor theme={value.theme} onChange={setValue} />
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
The theme editor's `STANDARD_STYLE_OPTIONS`, `CONVERSATIONAL_STYLE_OPTIONS`,
|
|
208
|
+
`styleOptionsForMode` and `reconcileStyle` exports are replaced by a single
|
|
209
|
+
`STYLE_OPTIONS` array; use `styleFamily()` from `fiber-types` if you need the
|
|
210
|
+
partition.
|
|
211
|
+
|
|
212
|
+
## Related
|
|
213
|
+
|
|
214
|
+
- [Flow Schema → Style Families](../schema/flow-schema.md#style-families)
|
|
215
|
+
- [FBRE Theming Guide](@sonata-innovations/fiber-fbre/docs/features/fbre-theming.md) — palette tokens, brand fonts, and how a
|
|
216
|
+
style's preset interacts with the knobs
|
|
217
|
+
- [FBRE Integration Guide → Focused Presentation](@sonata-innovations/fiber-fbre/docs/integration/fbre.md#focused-presentation)
|
package/docs/fiber-concepts.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Fiber Concepts
|
|
3
3
|
applies-to:
|
|
4
|
-
- "@sonata-innovations/fiber-types@^
|
|
5
|
-
- "@sonata-innovations/fiber-shared@^1.
|
|
6
|
-
- "@sonata-innovations/fiber-fbre@^
|
|
7
|
-
- "@sonata-innovations/fiber-fbt@^
|
|
8
|
-
- "@sonata-innovations/fiber-fbtl@^
|
|
9
|
-
- "@sonata-innovations/fiber-theme-editor@^
|
|
4
|
+
- "@sonata-innovations/fiber-types@^3.0"
|
|
5
|
+
- "@sonata-innovations/fiber-shared@^1.2"
|
|
6
|
+
- "@sonata-innovations/fiber-fbre@^4.0"
|
|
7
|
+
- "@sonata-innovations/fiber-fbt@^3.0"
|
|
8
|
+
- "@sonata-innovations/fiber-fbtl@^3.0"
|
|
9
|
+
- "@sonata-innovations/fiber-theme-editor@^2.0"
|
|
10
10
|
read-when: "First contact with Fiber: the Flow/Screen/Component model, FlowData, builders vs render engine, conditions/validation/calculations concepts."
|
|
11
11
|
---
|
|
12
12
|
|
|
@@ -89,7 +89,6 @@ The optional `config` object controls runtime behavior, organized into semantic
|
|
|
89
89
|
|
|
90
90
|
| Group | Setting | Purpose |
|
|
91
91
|
|-------|---------|---------|
|
|
92
|
-
| _(flat)_ | `mode` | Presentation mode: `"standard"` (default) or `"conversational"` (one question at a time) |
|
|
93
92
|
| `theme` | `color` | Primary accent color (CSS value) |
|
|
94
93
|
| `theme` | `colorScheme` | Built-in palette preset: `"light"` (default) or `"dark"` (replaces the former `darkMode` boolean) |
|
|
95
94
|
| `theme` | `style` | Visual style (`"clean"`, `"outlined"`, …) |
|
|
@@ -98,6 +97,8 @@ The optional `config` object controls runtime behavior, organized into semantic
|
|
|
98
97
|
| `theme` | `error` / `success` / `warning` | Semantic state color knobs |
|
|
99
98
|
| `navigation` | `transition` | Screen transition animation type |
|
|
100
99
|
| `navigation` | `allowInvalidTransition` | Allow navigating past screens with validation errors |
|
|
100
|
+
| `navigation` | `autoAdvance` | Advance ~500ms after a single-select choice (default off) |
|
|
101
|
+
| `navigation` | `advanceOnEnter` | Advance on Enter in a single-line input (default on) |
|
|
101
102
|
| `controls` | `show` | Show/hide built-in next/back buttons |
|
|
102
103
|
| `controls` | `layout` | Controls layout (`"default"`, `"centered"`, `"inline-full"`, or `"stacked"`) |
|
|
103
104
|
| `controls` | `showStepper` | Show/hide the step indicator |
|
|
@@ -452,9 +453,17 @@ FBRE accepts a flow through one of three mutually exclusive prop shapes:
|
|
|
452
453
|
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.
|
|
453
454
|
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.
|
|
454
455
|
|
|
455
|
-
###
|
|
456
|
+
### Style Families
|
|
456
457
|
|
|
457
|
-
|
|
458
|
+
`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.
|
|
459
|
+
|
|
460
|
+
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.
|
|
461
|
+
|
|
462
|
+
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.
|
|
463
|
+
|
|
464
|
+
### Advance Behaviors
|
|
465
|
+
|
|
466
|
+
`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.
|
|
458
467
|
|
|
459
468
|
### Confirmation Screen
|
|
460
469
|
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: FlowData Schema
|
|
3
3
|
applies-to:
|
|
4
|
-
- "@sonata-innovations/fiber-types@^
|
|
5
|
-
- "@sonata-innovations/fiber-fbre@^
|
|
4
|
+
- "@sonata-innovations/fiber-types@^3.0"
|
|
5
|
+
- "@sonata-innovations/fiber-fbre@^4.0"
|
|
6
6
|
read-when: "Consuming FlowData output from FBRE: structure, per-type value shapes, exclusion rules, containers, calculations."
|
|
7
7
|
---
|
|
8
8
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Flow JSON Quick Reference
|
|
3
3
|
applies-to:
|
|
4
|
-
- "@sonata-innovations/fiber-types@^
|
|
4
|
+
- "@sonata-innovations/fiber-types@^3.0"
|
|
5
5
|
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."
|
|
6
6
|
---
|
|
7
7
|
|
|
@@ -36,9 +36,8 @@ Flow
|
|
|
36
36
|
|
|
37
37
|
| Field | Type | Default | Description |
|
|
38
38
|
|-------|------|---------|-------------|
|
|
39
|
-
| `mode` | `FlowModeType` | `"standard"` | `"standard"` or `"conversational"` — conversational mode centers content, auto-advances on selection, and Enter-advances on text inputs |
|
|
40
39
|
| `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 |
|
|
41
|
-
| `navigation` | `NavigationConfig` | — | `{ transition?, allowInvalidTransition? }` — screen navigation settings |
|
|
40
|
+
| `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 |
|
|
42
41
|
| `controls` | `ControlsConfig` | — | `{ show?, layout?, showStepper?, stepperStyle? }` — navigation controls settings |
|
|
43
42
|
| `confirmation` | `ConfirmationConfig` | — | `{ show?, title?, body? }` — terminal thank-you screen (see [Confirmation Screen](@sonata-innovations/fiber-fbre/docs/integration/fbre.md#confirmation-screen)) |
|
|
44
43
|
| `summary` | `boolean` | `false` | Show summary screen before completion |
|
|
@@ -90,7 +90,7 @@
|
|
|
90
90
|
},
|
|
91
91
|
"style": {
|
|
92
92
|
"type": "string",
|
|
93
|
-
"description": "Visual style for form elements.
|
|
93
|
+
"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).",
|
|
94
94
|
"enum": ["clean", "outlined", "refined-clean", "airy-clean", "soft-outlined", "defined-outlined", "centered-minimal", "stacked-cards", "soft-float", "bold-statement"]
|
|
95
95
|
}
|
|
96
96
|
}
|
|
@@ -175,6 +175,14 @@
|
|
|
175
175
|
"allowInvalidTransition": {
|
|
176
176
|
"type": "boolean",
|
|
177
177
|
"description": "Allow navigating forward even when the screen has validation errors."
|
|
178
|
+
},
|
|
179
|
+
"autoAdvance": {
|
|
180
|
+
"type": "boolean",
|
|
181
|
+
"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."
|
|
182
|
+
},
|
|
183
|
+
"advanceOnEnter": {
|
|
184
|
+
"type": "boolean",
|
|
185
|
+
"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."
|
|
178
186
|
}
|
|
179
187
|
}
|
|
180
188
|
},
|
|
@@ -227,11 +235,6 @@
|
|
|
227
235
|
"type": "object",
|
|
228
236
|
"description": "Runtime configuration for the flow.",
|
|
229
237
|
"properties": {
|
|
230
|
-
"mode": {
|
|
231
|
-
"type": "string",
|
|
232
|
-
"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.",
|
|
233
|
-
"enum": ["standard", "conversational"]
|
|
234
|
-
},
|
|
235
238
|
"theme": { "$ref": "#/$defs/ThemeConfig" },
|
|
236
239
|
"navigation": { "$ref": "#/$defs/NavigationConfig" },
|
|
237
240
|
"controls": { "$ref": "#/$defs/ControlsConfig" },
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Flow JSON Schema Reference
|
|
3
3
|
applies-to:
|
|
4
|
-
- "@sonata-innovations/fiber-types@^
|
|
4
|
+
- "@sonata-innovations/fiber-types@^3.0"
|
|
5
5
|
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."
|
|
6
6
|
---
|
|
7
7
|
|
|
@@ -45,7 +45,6 @@ Runtime configuration for the flow, organized into semantic groups.
|
|
|
45
45
|
|
|
46
46
|
| Field | Type | Required | Description |
|
|
47
47
|
| ------------ | ------------------ | -------- | ------------------------------------ |
|
|
48
|
-
| `mode` | `FlowModeType` | No | Form presentation mode. See [Conversational Mode](#conversational-mode) |
|
|
49
48
|
| `theme` | `ThemeConfig` | No | Visual theme settings |
|
|
50
49
|
| `navigation` | `NavigationConfig` | No | Screen navigation settings |
|
|
51
50
|
| `controls` | `ControlsConfig` | No | Navigation controls settings |
|
|
@@ -102,7 +101,9 @@ See [FBRE Theming Guide → Loading a brand font](@sonata-innovations/fiber-fbre
|
|
|
102
101
|
|
|
103
102
|
#### Style Types
|
|
104
103
|
|
|
105
|
-
|
|
104
|
+
Ten values, one flat vocabulary. Any style may be used on any flow.
|
|
105
|
+
|
|
106
|
+
**Form family** (6):
|
|
106
107
|
|
|
107
108
|
| Value | Description |
|
|
108
109
|
| --- | --- |
|
|
@@ -113,7 +114,7 @@ See [FBRE Theming Guide → Loading a brand font](@sonata-innovations/fiber-fbre
|
|
|
113
114
|
| `"soft-outlined"` | Full-border 8px radius with shadow-ring focus |
|
|
114
115
|
| `"defined-outlined"` | Filled-background inputs with top-accent groups |
|
|
115
116
|
|
|
116
|
-
**
|
|
117
|
+
**Focused family** (4):
|
|
117
118
|
|
|
118
119
|
| Value | Description |
|
|
119
120
|
| --- | --- |
|
|
@@ -122,7 +123,9 @@ See [FBRE Theming Guide → Loading a brand font](@sonata-innovations/fiber-fbre
|
|
|
122
123
|
| `"soft-float"` | Pill-shaped options (24px radius) with shadow lift on hover, rounded inputs and buttons |
|
|
123
124
|
| `"bold-statement"` | 2px borders, 700-weight 24px headers, inverted selection (dark fill + white text), filled input backgrounds |
|
|
124
125
|
|
|
125
|
-
|
|
126
|
+
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).
|
|
127
|
+
|
|
128
|
+
Each style has a default stepper visual (see `stepperStyle`).
|
|
126
129
|
|
|
127
130
|
### NavigationConfig
|
|
128
131
|
|
|
@@ -130,6 +133,8 @@ Each style has a default stepper visual (see `stepperStyle`). When switching for
|
|
|
130
133
|
| ------------------------ | ---------------------- | -------- | --------------------------------------------------------------------------- |
|
|
131
134
|
| `transition` | `ScreenTransitionType` | No | Screen transition animation type. See [Screen Transitions](#screen-transitions) |
|
|
132
135
|
| `allowInvalidTransition` | `boolean` | No | Allow navigating forward even when the screen has validation errors |
|
|
136
|
+
| `autoAdvance` | `boolean` | No | Advance ~500ms after a single-select choice. Default `false`. See [Advance Behaviors](#advance-behaviors) |
|
|
137
|
+
| `advanceOnEnter` | `boolean` | No | Advance when Enter is pressed in a single-line input. Default `true`. See [Advance Behaviors](#advance-behaviors) |
|
|
133
138
|
|
|
134
139
|
### ControlsConfig
|
|
135
140
|
|
|
@@ -154,42 +159,71 @@ A terminal "thank you" screen shown after the flow is submitted (once `onFlowCom
|
|
|
154
159
|
|
|
155
160
|
---
|
|
156
161
|
|
|
157
|
-
##
|
|
162
|
+
## Style Families
|
|
158
163
|
|
|
159
|
-
|
|
164
|
+
The ten `FlowStyleType` values are a flat vocabulary — any style is valid on any
|
|
165
|
+
flow — but four of them share a presentation treatment. That shared half is a
|
|
166
|
+
**family**, derived from the style itself:
|
|
160
167
|
|
|
161
|
-
|
|
168
|
+
| Family | Styles |
|
|
169
|
+
| --- | --- |
|
|
170
|
+
| `"form"` | `clean`, `outlined`, `refined-clean`, `airy-clean`, `soft-outlined`, `defined-outlined` |
|
|
171
|
+
| `"focused"` | `centered-minimal`, `stacked-cards`, `soft-float`, `bold-statement` |
|
|
162
172
|
|
|
163
|
-
|
|
173
|
+
The focused family adds, on top of whichever of the four styles is selected:
|
|
164
174
|
|
|
165
|
-
|
|
|
175
|
+
| Treatment | Description |
|
|
166
176
|
| --- | --- |
|
|
167
|
-
| **Vertical centering** | Content is vertically and horizontally centered within
|
|
168
|
-
| **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 |
|
|
169
|
-
| **Enter-to-advance** | Pressing Enter on `inputText` / `inputNumber` advances to the next screen. `inputTextArea` is excluded (Enter inserts newlines) |
|
|
177
|
+
| **Vertical centering** | Content is vertically and horizontally centered within a narrow column |
|
|
170
178
|
| **Animated entry** | Components fade + scale in with staggered delays on screen transitions. Respects `prefers-reduced-motion` |
|
|
171
|
-
| **Larger tap targets** | Yes/No buttons, option items, card-select cards
|
|
179
|
+
| **Larger tap targets** | Yes/No buttons, option items, card-select cards and input fields are enlarged for easier tapping |
|
|
180
|
+
| **Bolder type** | Headers, labels, prompts and inputs step up in size |
|
|
172
181
|
|
|
173
|
-
|
|
182
|
+
The family is **never authored** — it does not appear in Flow JSON. FBRE derives
|
|
183
|
+
it and emits it as `data-style-family` alongside `data-style`. `fiber-types`
|
|
184
|
+
exports the derivation for builders that want to group a style picker by family:
|
|
174
185
|
|
|
175
|
-
|
|
186
|
+
```ts
|
|
187
|
+
import { FOCUSED_STYLES, styleFamily } from "@sonata-innovations/fiber-types";
|
|
176
188
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
189
|
+
styleFamily("bold-statement"); // "focused"
|
|
190
|
+
styleFamily("clean"); // "form"
|
|
191
|
+
styleFamily(undefined); // "form"
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Because the family derives from `theme.style`, presentation travels with the
|
|
195
|
+
theme through every render path — local, remote and server-driven alike.
|
|
183
196
|
|
|
184
|
-
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## Advance Behaviors
|
|
200
|
+
|
|
201
|
+
Auto-advance and Enter-to-advance are independent `navigation` flags. They are
|
|
202
|
+
**not** tied to a style or a family: a `clean` form with one question per screen
|
|
203
|
+
gets Enter-to-advance, and a `bold-statement` flow only auto-advances if it asks
|
|
204
|
+
to.
|
|
205
|
+
|
|
206
|
+
| Flag | Default | Behavior |
|
|
207
|
+
| --- | --- | --- |
|
|
208
|
+
| `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 |
|
|
209
|
+
| `navigation.advanceOnEnter` | `true` | Pressing Enter in an `inputText` / `inputNumber` advances to the next screen. `inputTextArea` is excluded (Enter inserts newlines) |
|
|
210
|
+
|
|
211
|
+
`autoAdvance` defaults off because a form that moves without a click is
|
|
212
|
+
surprising and shifts content ~500ms after a selection. `advanceOnEnter`
|
|
213
|
+
defaults on because Enter-to-advance is an ordinary form convention.
|
|
185
214
|
|
|
186
215
|
### Guards
|
|
187
216
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
-
|
|
191
|
-
|
|
192
|
-
-
|
|
217
|
+
Both behaviors share the same guards, and they are not configurable:
|
|
218
|
+
|
|
219
|
+
- Neither fires on a screen with **more than one visible input** — a shared
|
|
220
|
+
screen behaves like a normal form so later components aren't skipped
|
|
221
|
+
- Neither fires on the last screen (so Enter can never submit)
|
|
222
|
+
- Neither fires if the screen fails validation
|
|
223
|
+
- Both respect condition-hidden screens (they skip them)
|
|
224
|
+
- Auto-advance does not fire during an active transition
|
|
225
|
+
- Enter-to-advance does not fire inside an open popup (date picker, colour
|
|
226
|
+
picker, dropdown panel) — the overlay keeps its Enter
|
|
193
227
|
|
|
194
228
|
---
|
|
195
229
|
|