@sonata-innovations/fiber-fbre 3.2.1 → 3.4.0

package/dist/index.d.ts

@@ -31,6 +31,7 @@ import { ComponentYesNoProperties } from '@sonata-innovations/fiber-types';
 import { ConditionGroup } from '@sonata-innovations/fiber-types';
 import { ConditionOperator } from '@sonata-innovations/fiber-types';
 import { ConditionRule } from '@sonata-innovations/fiber-types';
+import { ConfirmationConfig } from '@sonata-innovations/fiber-types';
 import { ControlsConfig } from '@sonata-innovations/fiber-types';
 import { DateFormat } from '@sonata-innovations/fiber-types';
 import { FC } from 'react';
@@ -143,6 +144,22 @@ export { ConditionOperator }
 
 export { ConditionRule }
 
+export { ConfirmationConfig }
+
+/**
+ * Parent-supplied override for the terminal confirmation screen.
+ *
+ * Returned (directly or via a resolved Promise) from `onFlowComplete`. When an
+ * object is returned it replaces the flow's configured `confirmation` message —
+ * useful for content only known after submit, e.g. a server-generated
+ * reference number. `title`/`body` support the same `${...}` reference markup
+ * as the configured message.
+ */
+export declare type ConfirmationResult = {
+    title?: string;
+    body?: string;
+};
+
 export { ControlsConfig }
 
 export { DateFormat }
@@ -173,9 +190,16 @@ declare interface FBRECallbackProps {
     screenIndex?: number;
     context?: Record<string, string | boolean | number>;
     storeRef?: React.MutableRefObject<StoreApi<FBREStoreState> | null>;
-    onFlowComplete: (data: any) => void | Promise<void>;
+    /**
+     * Called when the flow is submitted, with the collected {@link FlowData}.
+     * Return (or resolve with) a {@link ConfirmationResult} to override the
+     * flow's configured confirmation message — e.g. with a server-generated
+     * reference number. Returning a Promise keeps the submit button in its
+     * in-flight state until it settles; a rejection surfaces as a completion
+     * error and the confirmation is not shown.
+     */
+    onFlowComplete: (data: FlowData) => void | ConfirmationResult | Promise<void | ConfirmationResult>;
     onScreenChange?: (index: number, data: any) => void;
-    onScreenValidationChange?: (index: number, data: any) => void;
 }
 
 export declare interface FBRELocalProps extends FBRECallbackProps {
@@ -248,7 +272,7 @@ export declare type FBREStoreState = {
     getValidationErrors: (uuid: string) => string[];
     updateContext: (context: Record<string, string | boolean | number>) => void;
     evaluateFlowValidation: () => boolean;
-    getMaxScreenCount: () => number;
+    getMaxScreenIndex: () => number;
     getCalculationResult: (uuid: string) => number | null;
 };
 

package/docs/features/confirmation-screen.md

@@ -0,0 +1,125 @@
+---
+title: Confirmation ("Thank You") Screen
+applies-to:
+  - "@sonata-innovations/fiber-fbre@^3.3"
+  - "@sonata-innovations/fiber-fbt@^2.2"
+read-when: "Configuring the post-submit thank-you screen: config.confirmation, dynamic ${...} content, and the onFlowComplete return contract."
+---
+
+<!-- Generated from the Fiber repo's docs/ tree by project/scripts/sync-package-docs.mjs. Do not edit here. -->
+<!-- Spec: consumed by FBRE (fbre/src/ui/confirmation), FBT (editor-settings), fiber-types (ConfirmationConfig) -->
+
+# Confirmation ("Thank You") Screen
+
+A terminal screen shown **after** a form is submitted — a centered, formatted thank-you message. It is a flow-level setting, **not** a data-collection screen, so it never appears in the FBT/FBTL stage editor and never collects input.
+
+- **Where it lives:** `flow.config.confirmation` (a serializable config group, alongside `theme` / `navigation` / `controls` / `summary`).
+- **When it shows:** once the flow is submitted and `onFlowComplete` settles.
+- **What it renders:** `title` + `body`, centered, with the controls and stepper hidden.
+
+## Quick start
+
+```ts
+const flow = {
+  ...myFlow,
+  config: {
+    ...myFlow.config,
+    confirmation: {
+      show: true,
+      title: "Thank you!",
+      body: "Your response has been submitted.",
+    },
+  },
+};
+
+<FBRE flow={flow} onFlowComplete={handleComplete} />;
+```
+
+It renders **only** when `show` is not `false` **and** `title` or `body` has content. There is no built-in default copy — an enabled-but-empty confirmation shows nothing and the flow behaves as before.
+
+### `ConfirmationConfig`
+
+| Field   | Type      | Description                                                     |
+| ------- | --------- | -------------------------------------------------------------- |
+| `show`  | `boolean` | Explicit off-switch. Content presence is the positive gate.    |
+| `title` | `string`  | Heading. Supports `${...}` references and text formatting.     |
+| `body`  | `string`  | Message. Supports `${...}` references and text formatting.     |
+
+## Dynamic content
+
+`title` and `body` run through the same `${...}` reference markup as `text` / `header` / `callout` components. References resolve, in order, against:
+
+1. **Calculations** — `${<calculationUuid>}`
+2. **Collected field values** — `${<componentUuid>}` (what the user just entered)
+3. **External context** — `${<contextKey>}` (values the parent passed via the `context` prop, by name)
+
+```ts
+// config.confirmation.body — mixes a collected field and a context value
+"Thanks ${q_name}! A copy is on its way to ${q_email}. Our team at ${support_email} will follow up.";
+```
+
+```tsx
+// q_name / q_email are component UUIDs; support_email comes from context
+<FBRE flow={flow} context={{ support_email: "support@acme.com" }} onFlowComplete={handleComplete} />
+```
+
+> In FBT, the reference picker inserts field/calculation UUIDs for you. Context keys aren't in the picker yet — type `${key}` by hand for those. Resolved values are HTML-escaped (safe against injection).
+
+## Deciding *when* it shows: the `onFlowComplete` contract
+
+The confirmation appears when `onFlowComplete` settles. Its return value drives the behavior:
+
+```ts
+onFlowComplete: (data: FlowData) =>
+  void | ConfirmationResult | Promise<void | ConfirmationResult>;
+```
+
+| You return… | What happens |
+| --- | --- |
+| `void` | Confirmation shows immediately (optimistic). |
+| `Promise<void>` | Submit button stays in its **in-flight / loading** state until the promise settles. Resolve → confirmation shows. **Reject → a completion error renders and the confirmation is _not_ shown.** |
+| `ConfirmationResult` (`{ title?, body? }`), synchronously or as the resolved value of a Promise | **Overrides** the configured message. Use for content only known after submit — e.g. a server reference number. |
+
+### Wait for the backend, then confirm with its reference number
+
+```tsx
+import type { FlowData, ConfirmationResult } from "@sonata-innovations/fiber-fbre";
+
+const handleComplete = async (data: FlowData): Promise<ConfirmationResult> => {
+  const { referenceId } = await saveToBackend(data); // rejects → FBRE shows the error, no confirmation
+  return { title: "All done!", body: `Your reference number is ${referenceId}.` };
+};
+
+<FBRE flow={flow} onFlowComplete={handleComplete} />;
+```
+
+If you don't need a runtime override, just author the message in `config.confirmation` and return `void` (or a `Promise<void>` to get the in-flight state while your save runs).
+
+## Authoring in FBT
+
+Open **Flow Settings → Confirmation Screen**, toggle it on, and fill in the title and message. This writes `config.confirmation` — it is intentionally separate from the stage/question editor. The message fields accept `${...}` references.
+
+## FBTL
+
+FBTL doesn't edit this config, but it **carries it through untouched** on load and export. A flow authored with a confirmation in FBT (or by hand) keeps it when round-tripped through FBTL, and FBTL's live FBRE preview renders it.
+
+## Try it
+
+FBRE playground → **Confirmation Demo** fixture:
+
+```bash
+cd fbre && npm run dev:playground
+```
+
+Fill in name + email and submit: the demo simulates a ~1.2s server round-trip (showing the in-flight submit state), then renders the confirmation with the field values and a context value interpolated in.
+
+## Exports & schema
+
+- Types: `ConfirmationConfig`, `ConfirmationResult` — exported from `@sonata-innovations/fiber-fbre` (and `@sonata-innovations/fiber-types`).
+- Schema: [`flow-schema.md` → ConfirmationConfig](@sonata-innovations/fiber-types/docs/schema/flow-schema.md#confirmationconfig).
+- Integration reference: [FBRE Integration Guide → Confirmation Screen](../integration/fbre.md#confirmation-screen).
+
+## Edge cases
+
+- A non-empty `ConfirmationResult` returned from `onFlowComplete` forces the confirmation to render even when `config.confirmation.show` is `false` (the override path bypasses the config gate). An empty object (`{}`) is ignored and does not count as an override.
+- The confirmation screen exists only in local and remote modes. In **server-driven mode** it is not rendered — the parent should present its own terminal state from `onFlowComplete`.

package/docs/features/fbre-theming.md

@@ -0,0 +1,264 @@
+---
+title: FBRE Theming Guide
+applies-to:
+  - "@sonata-innovations/fiber-fbre@^3.3"
+read-when: "Theming FBRE-rendered forms: colorScheme presets, palette knobs, raw --fbre-* token overrides, precedence model, full token catalog."
+---
+
+<!-- Generated from the Fiber repo's docs/ tree by project/scripts/sync-package-docs.mjs. Do not edit here. -->
+# FBRE Theming Guide
+
+How to theme a form rendered by **FBRE** (`@sonata-innovations/fiber-fbre`) — from a one-line accent change to a full custom brand palette, light or dark.
+
+> This is the canonical theming reference. It ships inside the `@sonata-innovations/fiber-fbre` package (`docs/features/fbre-theming.md`), so the copy you are reading matches the version you installed. `fbre/README.md` carries a condensed summary; this document is authoritative.
+
+---
+
+## The mental model
+
+FBRE's appearance is driven entirely by **CSS custom properties** (the `--fbre-*` tokens). Everything you see — every fill, border, label, and state color — resolves from one of these tokens. Theming is the act of supplying values for them.
+
+There are **two independent axes**:
+
+| Axis | Controls | Set via |
+| --- | --- | --- |
+| **`style`** (FlowStyleType) | the *shape*: borders vs. underlines, fills, spacing, radius rhythm | `theme.style` (e.g. `"clean"`, `"defined-outlined"`) |
+| **palette** | the *colors*: ground, surfaces, text, borders, accent, state colors | `colorScheme` + the palette knobs, or raw `--fbre-*` overrides |
+
+`style` and palette are orthogonal: any style works with any palette. This guide is about the **palette** axis. (For the list of styles, see the [Flow Schema](@sonata-innovations/fiber-types/docs/schema/flow-schema.md#style-types).)
+
+---
+
+## The precedence chain
+
+Palette values resolve through four layers. Each layer overrides the ones above it, so you only specify what you want to change:
+
+```
+1.  Light defaults                    base.css  .fbre-container            (lowest)
+2.  Preset:  colorScheme: "dark"      base.css  .fbre-container[data-mode="dark"]
+3.  Knobs:   theme.{surface,text,…}   inline custom properties on the container
+4.  Raw CSS: your own --fbre-* rules   your stylesheet
+```
+
+- **Layer 1–2 (presets)** seed the *entire* token set with a coherent light or dark palette. Picking `colorScheme` swaps which one is active.
+- **Layer 3 (knobs)** are written as **inline** custom properties on the container, so they beat any stylesheet rule targeting the same element — no selector can out-specify an inline declaration.
+- **Layer 4 (raw CSS)** beats the presets and is the escape hatch for every token no knob touches. For a token a knob *has* set, a stylesheet rule on `.fbre-container` loses to the inline knob — to override a knob-set token you need `!important`, or set the token on a **descendant** element so it takes effect lower in the tree.
+
+This is why you can set `colorScheme: "dark"` and then override just `surface` and `text` — the rest of the form stays coherent with the dark preset, and your two knobs take effect on top.
+
+---
+
+## 1. Color scheme (presets)
+
+`theme.colorScheme` selects the built-in starter palette. Default is `"light"`.
+
+```tsx
+// Via the theme prop (takes precedence over flow config)
+<FBRE flow={flow} theme={{ colorScheme: "dark" }} onFlowComplete={done} />
+
+// Via the flow config
+const flow = { ...base, config: { ...base.config, theme: { colorScheme: "dark" } } };
+```
+
+It applies `data-mode="light" | "dark"` on the `.fbre-container` and seeds all `--fbre-*` tokens with light- or dark-appropriate values.
+
+> **Migration:** `colorScheme` replaces the former `darkMode: boolean`. `darkMode: true` → `colorScheme: "dark"`; `darkMode: false`/absent → `colorScheme: "light"`. There is no runtime fallback — pre-migrate stored flows.
+
+There is intentionally **no `"auto"`** scheme yet (following the viewer's `prefers-color-scheme`). It is an additive future option; today a flow renders one chosen scheme for every viewer.
+
+---
+
+## 2. Palette knobs
+
+Knobs live on `theme` and override individual tokens **on top of** the active preset. Set any subset; unset knobs fall through.
+
+```tsx
+<FBRE
+  flow={flow}
+  theme={{
+    colorScheme: "dark",
+    color: "#bcd3cd",       // accent
+    background: "#1a2a3a",  // form ground
+    surface: "#243244",     // input fills / cards
+    text: "#e8ede9",
+    border: "#2e4158",
+    radius: "3px",
+    fontFamily: '"Inter", system-ui, sans-serif',
+  }}
+  onFlowComplete={done}
+/>
+```
+
+Each knob sets a **primary token** and **derives** the related tokens from it, so you get a coherent result from a single value:
+
+| Knob | Primary token | Also derives |
+| --- | --- | --- |
+| `color` | `--fbre-theme-color` | `--fbre-theme-light`, `--fbre-theme-dark` |
+| `background` | `--fbre-bg` | — |
+| `surface` | `--fbre-surface` | `--fbre-surface-hover/-alt/-subtle`, `--fbre-control-surface`, `--fbre-input-bg`, `--fbre-input-bg-focus` |
+| `text` | `--fbre-text` | `--fbre-text-secondary/-placeholder/-disabled`, `--fbre-label` |
+| `border` | `--fbre-border` | `--fbre-border-hover/-light/-subtle` |
+| `radius` | `--fbre-radius` | — |
+| `fontFamily` | `--fbre-font` | — |
+| `error` | `--fbre-error` | `--fbre-error-light` |
+| `success` | `--fbre-success` | `--fbre-success-bg`, `--fbre-success-border` |
+| `warning` | `--fbre-warning` | `--fbre-warning-bg`, `--fbre-warning-border` |
+
+### How derivation works
+
+Knobs are applied as inline custom properties on the container; derived tokens are emitted as `color-mix()` expressions that reference other tokens rather than literal colors — e.g. `--fbre-text-secondary` is roughly `color-mix(in srgb, var(--fbre-text) 64%, var(--fbre-bg))`. Because the inputs are *tokens*, derivations stay **mode-aware**: if you set only `surface`, its derived hover/alt surfaces still mix against the active scheme's `--fbre-bg`/`--fbre-text`. A knob's derived tokens are emitted **only when that knob is set**, so an unset knob leaves the preset's values untouched. The mapping lives in one place: `buildThemeVars()` in `fbre/src/lib/theme-vars.ts`.
+
+> Knobs are *colors and a few scalars*, not shape. To change borders-vs-underlines, fills, or spacing rhythm, choose a different `theme.style` — see the orthogonal-axes note above.
+
+---
+
+## 3. Raw CSS escape hatch
+
+For anything not exposed as a knob — or for surgical control — override the `--fbre-*` tokens directly in your own stylesheet. Scope to your wrapper so you out-specify the engine's defaults regardless of load order:
+
+```css
+.my-form-wrapper .fbre-container {
+  --fbre-surface: #243244;
+  --fbre-star-filled: #bcd3cd;   /* not a knob — set it raw */
+  --fbre-shadow-color: rgba(0, 0, 0, 0.4);
+}
+```
+
+Knobs are applied inline on the container, so a knob and a raw stylesheet rule targeting the *same* token on the same element will see the knob win regardless of selector specificity — override a knob-set token with `!important` or by setting it on a descendant element. In practice: use knobs for the common palette, raw CSS for the long tail of tokens no knob touches.
+
+---
+
+## Token catalog
+
+Every themeable value, with light and dark preset defaults. Tokens marked **(derived)** are produced from a knob when that knob is set; you can also set any of them raw.
+
+### Accent
+
+| Token | Light | Dark | Knob |
+| --- | --- | --- | --- |
+| `--fbre-theme-color` | `#1976d2` | `#42a5f5` | `color` |
+| `--fbre-theme-light` | `#e3f2fd` | `#1a2332` | (derived) |
+| `--fbre-theme-dark` | `#1565c0` | `#1e88e5` | (derived) |
+| `--fbre-on-primary` | `#fff` | `#fff` | — |
+
+### Ground & surfaces
+
+| Token | Light | Dark | Knob |
+| --- | --- | --- | --- |
+| `--fbre-bg` | `#fff` | `#121212` | `background` |
+| `--fbre-surface` | `#fff` | `#1e1e1e` | `surface` |
+| `--fbre-surface-hover` | `#f5f5f5` | `#2a2a2a` | (derived) |
+| `--fbre-surface-alt` | `#e0e0e0` | `#333` | (derived) |
+| `--fbre-surface-subtle` | `#e8e8e8` | `#2a2a2a` | (derived) |
+| `--fbre-control-surface` | `#fff` | `#e0e0e0` | (derived) |
+| `--fbre-input-bg` | `var(--fbre-surface)` | `var(--fbre-surface)` | (derived) |
+| `--fbre-input-bg-focus` | `var(--fbre-bg)` | `var(--fbre-bg)` | (derived) |
+
+> Note: some style variants override tokens inside their `[data-style]` block: `defined-outlined` overrides `--fbre-input-bg` and `--fbre-label`, `soft-outlined` overrides `--fbre-input-bg`, and `airy-clean` overrides `--fbre-label`; the outlined variants also adjust `--fbre-layout-gap`. A knob still wins over all of these, because knobs are inline. (Their dark-mode blocks reset input-bg/label back to surface-derived values.)
+
+### Text
+
+| Token | Light | Dark | Knob |
+| --- | --- | --- | --- |
+| `--fbre-text` | `#212121` | `#e0e0e0` | `text` |
+| `--fbre-text-secondary` | `#666` | `#9e9e9e` | (derived) |
+| `--fbre-text-placeholder` | `#aaa` | `#666` | (derived) |
+| `--fbre-text-disabled` | `#bbb` | `#555` | (derived) |
+| `--fbre-label` | `var(--fbre-text-secondary)` | `var(--fbre-text-secondary)` | (derived) |
+
+### Borders
+
+| Token | Light | Dark | Knob |
+| --- | --- | --- | --- |
+| `--fbre-border` | `#ccc` | `#444` | `border` |
+| `--fbre-border-hover` | `#999` | `#666` | (derived) |
+| `--fbre-border-light` | `#ddd` | `#444` | (derived) |
+| `--fbre-border-subtle` | `#eee` | `#333` | (derived) |
+
+### State colors
+
+| Token | Light | Dark | Knob |
+| --- | --- | --- | --- |
+| `--fbre-error` | `#d32f2f` | `#ef5350` | `error` |
+| `--fbre-error-light` | `#fdecea` | `#2c1b1b` | (derived) |
+| `--fbre-success` | `#2d6a28` | `#a8e6a0` | `success` |
+| `--fbre-success-bg` | `#ddffda` | `#1a3318` | (derived) |
+| `--fbre-success-border` | `#b8e6b4` | `#2d5a28` | (derived) |
+| `--fbre-warning` | `#7a5900` | `#ffe082` | `warning` |
+| `--fbre-warning-bg` | `#fff8e1` | `#332b00` | (derived) |
+| `--fbre-warning-border` | `#ffe082` | `#665500` | (derived) |
+
+### Controls
+
+| Token | Light | Dark | Knob |
+| --- | --- | --- | --- |
+| `--fbre-toggle-track` | `#ccc` | `#555` | — |
+| `--fbre-star-empty` | `#ddd` | `#444` | — |
+| `--fbre-star-filled` | `#ffc107` | `#ffca28` | — |
+| `--fbre-slider-track` | `#ddd` | `#444` | — |
+| `--fbre-shadow-color` | `rgba(0,0,0,.12)` | `rgba(0,0,0,.4)` | — |
+
+### Shape & motion
+
+| Token | Default | Knob |
+| --- | --- | --- |
+| `--fbre-radius` | `4px` | `radius` |
+| `--fbre-font` | `"Segoe UI", system-ui, -apple-system, sans-serif` | `fontFamily` |
+| `--fbre-layout-gap` | `4px` (varies by style) | — |
+| `--fbre-transition-duration` | `250ms` | — |
+| `--fbre-transition-easing` | `cubic-bezier(0.4, 0, 0.2, 1)` | — |
+
+The control and motion tokens above have **no dedicated knob** — set them raw if you need to. (Tokens are defined in `fbre/src/styles/base.css`; transition tokens in `transitions.css`.)
+
+---
+
+## Worked example: a dark brand form
+
+Goal: a sage-on-navy intake form using the `defined-outlined` style. Two equivalent ways to express it.
+
+**With knobs (recommended)** — the engine derives the supporting tokens and keeps the dark scheme coherent:
+
+```tsx
+<FBRE
+  flow={flow}
+  theme={{
+    style: "defined-outlined",
+    colorScheme: "dark",
+    color: "#bcd3cd",
+    background: "#1a2a3a",
+    surface: "#243244",
+    text: "#e8ede9",
+    border: "#2e4158",
+    radius: "3px",
+    fontFamily: '"Inter", system-ui, sans-serif',
+  }}
+  onFlowComplete={done}
+/>
+```
+
+**With raw CSS** — equivalent for these tokens, and the only option for non-knob tokens (e.g. recoloring rating stars):
+
+```css
+.brand .fbre-container {
+  --fbre-bg: #1a2a3a;
+  --fbre-surface: #243244;
+  --fbre-input-bg: #243244;
+  --fbre-text: #e8ede9;
+  --fbre-text-secondary: #8fa899;
+  --fbre-label: #8fa899;
+  --fbre-border: #2e4158;
+  --fbre-theme-color: #bcd3cd;
+  --fbre-radius: 3px;
+  --fbre-font: "Inter", system-ui, sans-serif;
+}
+```
+
+The knob form needs no `data-mode` gymnastics and no per-element selector overrides — input fills, labels, and focus states all follow the tokens.
+
+---
+
+## See also
+
+- [Flow Schema — ThemeConfig](@sonata-innovations/fiber-types/docs/schema/flow-schema.md) — the `theme` object's fields and types
+- [FBRE Integration Guide](../integration/fbre.md) — embedding FBRE in a parent app
+- `fbre/README.md` — FBRE props and a condensed theming summary