@sonata-innovations/fiber-fbre 3.3.0 → 3.4.0

package/AGENTS.md

@@ -0,0 +1,58 @@
+# @sonata-innovations/fiber-fbre — Agent Guide
+
+Fiber Render Engine. Consumes **Flow** JSON, renders the form (conditions, validation, screen transitions), returns collected **FlowData** to the parent app. A standard React component — no iframe, no external service.
+
+Docs in this package are versioned with the code you installed. Read them from `node_modules/@sonata-innovations/fiber-fbre/docs/`.
+
+## Documentation map
+
+| Read this | When |
+|---|---|
+| `docs/fiber-concepts.md` | You are new to Fiber. The Flow/Screen/Component model, Flow vs FlowData, how builders and the render engine relate. |
+| `docs/integration/fbre.md` | **The main reference.** Props for all three modes, the `onFlowComplete` contract, store access, events, pre-populating data, pitfalls. |
+| `docs/features/fbre-theming.md` | Theming beyond a one-line accent change: precedence model, palette knobs, the full `--fbre-*` token catalog. |
+| `docs/features/confirmation-screen.md` | The post-submit "thank you" screen and its dynamic `${...}` content. |
+| `@sonata-innovations/fiber-types/docs/schema/flow-quick-reference.md` | Constructing or reading Flow JSON: component types, conditions, validation, widths. |
+| `@sonata-innovations/fiber-types/docs/schema/flow-schema.md` | Exhaustive per-property schema reference. |
+| `@sonata-innovations/fiber-types/docs/schema/flow-data-schema.md` | The shape of the data FBRE hands back. |
+
+Schema docs live in `fiber-types` (a direct dependency of this package), so they are always present in `node_modules` and never drift from the version you installed.
+
+## Minimal usage
+
+```tsx
+import { FBRE } from "@sonata-innovations/fiber-fbre";
+import "@sonata-innovations/fiber-fbre/styles"; // required — styles are not bundled with the JS
+
+<FBRE flow={myFlow} onFlowComplete={(data) => console.log(data)} />;
+```
+
+## The three modes
+
+Mutually exclusive; selected by which props you pass.
+
+- **Local** — you hold the Flow: `<FBRE flow={flow} onFlowComplete={fn} />`
+- **Remote** — fetch a published flow: `<FBRE flowId="…" apiEndpoint="…" onFlowComplete={fn} />`
+- **Server-driven** — the server evaluates conditions/validation, one screen at a time: `<FBRE sessionEndpoint="…" flowId="…" onFlowComplete={fn} />`
+
+## Rules that are easy to get wrong
+
+- **Import the stylesheet separately.** `import "@sonata-innovations/fiber-fbre/styles";` Without it the form renders unstyled.
+- **`data` is not reactive.** It is applied when the flow loads. Changing `data` alone does nothing — change `flow.uuid` or call `loadFlow(flow, data)` through `storeRef`.
+- **`flow.uuid` change ⇒ full reload.** Keep it stable unless you intend to reset.
+- **Never set `value`, `valid`, or `addedComponents` in Flow JSON.** They are runtime-only.
+- **Display components are excluded from FlowData** (`header`, `text`, `divider`, `callout`, `table`), as are condition-hidden components and screens. `computed` **is** included.
+- **`getMaxScreenIndex()` returns the max screen _index_** (count − 1). The last screen is `getMaxScreenIndex()`. (Renamed from the misleadingly-named `getMaxScreenCount`.)
+- **There is no screen-validity callback prop.** Subscribe through `storeRef` and read `getScreenValidity(i)`. (`onScreenValidationChange` never fired and has been removed.)
+- **The file-upload event bus is module-global**, not per-instance: one listener sees uploads from every mounted `<FBRE />`, distinguished only by component UUID.
+- **Server-driven mode renders a terminal confirmation on completion** (from `config.confirmation`, else a generic "Thank you") and resets the submit button. `onFlowComplete` still fires with the server result if you want to drive your own post-completion UI.
+
+## Types
+
+`Flow`, `FlowData`, `ScreenData`, `ComponentData`, `FileUploadData`, `ThemeConfig`, `NavigationConfig`, `ControlsConfig`, `ConfirmationConfig`, `ConfirmationResult`, `FBREStoreState`, and the condition/validation types are all re-exported from this package. You do not need to depend on `fiber-types` directly.
+
+## Companion packages
+
+- `@sonata-innovations/fiber-fbt` — full drag-and-drop builder that authors Flow JSON
+- `@sonata-innovations/fiber-fbtl` — lite builder for non-technical end users
+- `@sonata-innovations/fiber-theme-editor` — visual theme editor that emits a `ThemeConfig`

package/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog — @sonata-innovations/fiber-fbre
+
+All notable changes to the Fiber Render Engine. Dates are release dates.
+
+## 3.4.0 — 2026-07-10
+
+### Added
+
+- Documentation now ships inside the package under `docs/`, plus an `AGENTS.md` routing guide at the package root. The docs you read are always the ones matching the version you installed.
+
+### Fixed
+
+- Corrected several documentation errors: the theming token catalog's font stack, the claim that legacy `required`/`regex` properties are auto-migrated (they are not — pre-migrate them), the calculation formula example (single braces `{uuid}`, not double), and the conversational style list (styles partition by mode: 6 standard, 4 conversational).
+- Base64 file uploads now emit the deprecated `File.lastModifiedDate` property as an ISO-8601 string instead of passing the raw `Date` object through, so `FlowData` survives a JSON round-trip unchanged. The field remains optional and is only present in browsers that still expose the property.
+- Server-driven mode no longer stays stuck on "Submitting…" after a successful completion. It now resets the submit button and renders a terminal confirmation screen — the flow's configured `config.confirmation` message when present, otherwise a generic "Thank you". `onFlowComplete` still fires with the server result.
+
+### Changed
+
+- Renamed the store method `getMaxScreenCount()` to `getMaxScreenIndex()`. It always returned the maximum screen *index* (count − 1), not a count, so the name was misleading; the behavior is unchanged. Update `storeRef` call sites to the new name.
+
+### Removed
+
+- The `onScreenValidationChange` prop, which was never invoked in any released version — it was accepted, threaded down, and dropped. To react to screen validity, subscribe through `storeRef` and read `getScreenValidity(i)`, which is what the prop's documentation has recommended as a workaround all along.
+
+## 3.3.0 — 2026-07-03
+
+### Added
+
+- **Confirmation ("thank you") screen.** A terminal screen configured via `flow.config.confirmation` (`show`, `title`, `body`), supporting `${...}` references to collected values, calculation results, and context. `onFlowComplete` gained a return contract: return `void` to show it optimistically, a `Promise` to hold the submit button in its in-flight state, or a `ConfirmationResult` (sync or resolved) to override the message with content known only after submit — e.g. a server reference number. A rejected promise surfaces a completion error and suppresses the confirmation.
+- Exports `ConfirmationConfig` and `ConfirmationResult`.
+
+## 3.2.1 — 2026-06-16
+
+### Fixed
+
+- Tall conversational screens no longer have their tops clipped.
+
+## 3.2.0 — 2026-06-10
+
+### Added
+
+- **Theme palette knobs.** `ThemeConfig` accepts `background`, `surface`, `text`, `border`, `radius`, `fontFamily`, `error`, `success`, and `warning`. Each sets a primary `--fbre-*` token and derives its related tokens, so a single value yields a coherent result. Unset knobs fall through to the preset.
+- New input, label, success, and warning tokens.
+
+### Changed
+
+- **`colorScheme: "light" | "dark"` replaces the `darkMode` boolean** on both `ThemeConfig` and the FBRE props. There is no runtime fallback — pre-migrate stored flows.
+
+## 3.1.0 — 2026-05-28
+
+### Added
+
+- Keyboard accessibility: correct tab order across a screen, and focus management on screen transitions.
+
+## 3.0.0 — 2026-05-19
+
+### Changed — breaking
+
+- **`Component` is now a discriminated union keyed on `type`.** After narrowing on `component.type`, `component.properties` narrows to the matching properties shape. Consumers with `properties` casts will need to update. Requires `@sonata-innovations/fiber-types` v2.
+- Component metadata is derived from a single manifest in `fiber-types`, with a build-time parity guard.
+
+### Added
+
+- Complete public exports for the per-component property types.
+
+### Fixed
+
+- The repeater's minimum-iteration count now reads `properties.minIterations`.
+- Markup conversion moved into `@sonata-innovations/fiber-shared`, so the browser and the server render markup identically.
+
+## 2.1.1 — 2026-05-14
+
+### Fixed
+
+- A dropdown panel is no longer clipped by the next component in conversational mode.
+
+## 2.1.0 — 2026-05-14
+
+### Added
+
+- Pick-one components honour `properties.defaultValue`.
+
+### Fixed
+
+- `cardSelect` stacks 1–3 options and equalizes card heights from 4 options up.
+
+## 2.0.6 — 2026-04-29
+
+### Fixed
+
+- Conversational auto-advance now only fires when the screen has a single visible input.
+
+## 2.0.5 — 2026-04-18
+
+### Added
+
+- **Controls layout overhaul**: a solo-wide default plus `centered`, `inline-full`, and `stacked` variants.
+- `showBorder` on group and repeater containers.
+
+### Fixed
+
+- Conversational mode centers vertically via a dedicated screen slot.
+
+## 2.0.4 — 2026-03-20
+
+### Added
+
+- Calculation results are included in the FlowData output.
+
+### Fixed
+
+- Component renderers are no longer tree-shaken out of the published bundle.
+- Conversational mode no longer clips overflowing content.
+
+## 2.0.1 – 2.0.3 — 2026-03-04
+
+### Added
+
+- **Conversational mode** with four dedicated styles (`centered-minimal`, `stacked-cards`, `soft-float`, `bold-statement`).
+- Four additional standard styles: `refined-clean`, `airy-clean`, `soft-outlined`, `defined-outlined`.
+- `stepperStyle` as an independent config value.
+- Signature component; expanded read-only support; formula engine enhancements.
+- `computed` component type with per-iteration formula evaluation.
+- Computation layer: repeater component, calculations, and rich option metadata.
+- `cardSelect` component; icon picker for callout and rating.
+
+### Fixed
+
+- The bar stepper no longer breaks for flows with more than six screens.