@sonata-innovations/fiber-types 2.3.0 → 3.0.0

package/docs/features/custom-presets-and-templates.md

@@ -0,0 +1,428 @@
+---
+title: Custom Presets & Templates (FBT)
+applies-to:
+  - "@sonata-innovations/fiber-fbt@^3.0"
+  - "@sonata-innovations/fiber-types@^3.0"
+read-when: "Extending FBT's pool with custom presets/templates: data-based vs factory definitions, icon catalog, collision rules, server-stored definitions."
+---
+
+<!-- Generated from the Fiber repo's docs/ tree by project/scripts/sync-package-docs.mjs. Do not edit here. -->
+# Custom Presets & Templates
+
+Parent applications extend FBT's pool with custom **presets** and **templates** via the optional `customPresets` and `customTemplates` props. This is the deep-dive companion to the short "Custom Presets & Templates" section in `docs/integration/fbt.md`.
+
+## Concepts
+
+- A **preset** is one or more pre-configured components. Dropping it onto the stage batch-adds those components to the **current screen** (at the drop position if dropped over an existing component, otherwise appended).
+- A **template** is a complete `Flow`. Dropping it **merges** into the current flow: its screens are **appended** to the existing screen list via `mergeFlow`, and the first appended screen becomes the active screen. Nothing is replaced — the existing screens, metadata, and config are untouched, and the template's own `metadata`/`config` are ignored by the merge (only its screens are ingested).
+
+Whether a definition is treated as a preset or a template is determined by **which prop array it arrives in** (`customPresets` vs `customTemplates`), not by its `type` string.
+
+## Two definition kinds, one set of props
+
+Both props accept a union type:
+
+```ts
+// fbt/src/types/custom.ts
+export type AnyPresetDefinition = CustomPresetDefinition | PresetData;
+export type AnyTemplateDefinition = CustomTemplateDefinition | TemplateData;
+```
+
+- **Data-based** (`PresetData` / `TemplateData`, exported from `@sonata-innovations/fiber-types`) — plain serializable JSON. **Preferred**: it can be stored in a database, sent over the wire, and edited without code. FBT regenerates UUIDs automatically on every drop.
+- **Factory-based** (`CustomPresetDefinition` / `CustomTemplateDefinition`, exported from `@sonata-innovations/fiber-fbt`) — a `factory()` function called on every drop. Kept for backward compatibility.
+
+FBT distinguishes the two kinds structurally (`"factory" in definition`), so you can mix both kinds in the same array.
+
+## Data-based definitions (primary)
+
+### Shapes
+
+```ts
+// @sonata-innovations/fiber-types
+export type PresetData = {
+  type: string;       // unique identifier (see collision rules below)
+  label: string;      // display name in the pool
+  icon: string;       // key into FBT's ICON_MAP (see icon catalog below)
+  components: Component[];
+};
+
+export type TemplateData = {
+  type: string;
+  label: string;
+  icon: string;
+  flow: Flow;
+};
+```
+
+### UUID regeneration semantics
+
+The UUIDs you write into a data-based definition are **placeholders**. On every drop, FBT calls `regenerateComponentUUIDs` (presets) or `regenerateFlowUUIDs` (templates) from `@sonata-innovations/fiber-types`:
+
+- Every component gets a fresh UUID; `properties` are deep-cloned (`structuredClone`), and nested `components` arrays (groups) are regenerated recursively.
+- For templates, the flow UUID and every screen UUID are also replaced.
+- The original definition object is never mutated, so the same definition can be dropped any number of times without duplicate-UUID bugs.
+
+This means placeholder UUIDs only need to be unique **within** the definition (so group nesting is unambiguous); any string works.
+
+### Full preset example
+
+`Component` is a discriminated union keyed on `type` — `properties` is checked against the shape for that `type` (e.g. `label` is required for `"inputText"`, `value` for `"header"`, `options` for `"dropDown"`). Group children live on the component's top-level `components` field, not inside `properties`.
+
+```ts
+import type { PresetData } from "@sonata-innovations/fiber-types";
+
+const ssnPreset: PresetData = {
+  type: "custom-ssn",
+  label: "SSN",
+  icon: "ssn",
+  components: [
+    {
+      uuid: "ssn-field",
+      type: "inputText",
+      properties: {
+        label: "Social Security Number",
+        placeholder: "XXX-XX-XXXX",
+        validation: {
+          rules: [
+            { type: "required" },
+            // NOTE: the param key is `regex`, not `pattern`
+            { type: "pattern", params: { regex: "^\\d{3}-\\d{2}-\\d{4}$" } },
+          ],
+        },
+      },
+    },
+  ],
+};
+
+const emergencyContactPreset: PresetData = {
+  type: "custom-emergencyContact",
+  label: "Emergency Contact",
+  icon: "emergencyContact",
+  components: [
+    {
+      uuid: "ec-group",
+      type: "group",
+      properties: { label: "Emergency Contact", showLabel: true },
+      components: [
+        {
+          uuid: "ec-name",
+          type: "inputText",
+          properties: {
+            label: "Contact Name",
+            width: "half",
+            validation: { rules: [{ type: "required" }] },
+          },
+        },
+        {
+          uuid: "ec-phone",
+          type: "inputText",
+          properties: {
+            label: "Contact Phone",
+            placeholder: "(555) 555-5555",
+            inputType: "tel",
+            width: "half",
+            validation: { rules: [{ type: "required" }, { type: "phone" }] },
+          },
+        },
+        {
+          uuid: "ec-relationship",
+          type: "dropDown",
+          properties: {
+            label: "Relationship",
+            options: [
+              { label: "Spouse", value: "spouse" },
+              { label: "Parent", value: "parent" },
+              { label: "Sibling", value: "sibling" },
+              { label: "Friend", value: "friend" },
+              { label: "Other", value: "other" },
+            ],
+            validation: { rules: [{ type: "required" }] },
+          },
+        },
+      ],
+    },
+  ],
+};
+```
+
+### Full template example
+
+```ts
+import type { TemplateData } from "@sonata-innovations/fiber-types";
+
+const onboardingTemplate: TemplateData = {
+  type: "custom-employeeOnboarding",
+  label: "Employee Onboarding",
+  icon: "employeeOnboarding",
+  flow: {
+    uuid: "onboarding-flow",
+    metadata: { name: "Employee Onboarding" },
+    config: {},
+    screens: [
+      {
+        uuid: "onboarding-screen-1",
+        label: "Personal Info",
+        components: [
+          {
+            uuid: "ob-header-1",
+            type: "header",
+            properties: { value: "Employee Information" },
+          },
+          {
+            uuid: "ob-first-name",
+            type: "inputText",
+            properties: {
+              label: "First Name",
+              width: "half",
+              validation: { rules: [{ type: "required" }] },
+            },
+          },
+          {
+            uuid: "ob-last-name",
+            type: "inputText",
+            properties: {
+              label: "Last Name",
+              width: "half",
+              validation: { rules: [{ type: "required" }] },
+            },
+          },
+          {
+            uuid: "ob-email",
+            type: "inputText",
+            properties: {
+              label: "Email Address",
+              placeholder: "name@company.com",
+              inputType: "email",
+              validation: { rules: [{ type: "required" }, { type: "email" }] },
+            },
+          },
+        ],
+      },
+      {
+        uuid: "onboarding-screen-2",
+        label: "Employment Details",
+        components: [
+          {
+            uuid: "ob-header-2",
+            type: "header",
+            properties: { value: "Employment Details" },
+          },
+          {
+            uuid: "ob-job-title",
+            type: "inputText",
+            properties: {
+              label: "Job Title",
+              validation: { rules: [{ type: "required" }] },
+            },
+          },
+          {
+            uuid: "ob-employment-type",
+            type: "dropDown",
+            properties: {
+              label: "Employment Type",
+              options: [
+                { label: "Full-Time", value: "full-time" },
+                { label: "Part-Time", value: "part-time" },
+                { label: "Contract", value: "contract" },
+                { label: "Intern", value: "intern" },
+              ],
+              validation: { rules: [{ type: "required" }] },
+            },
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+Remember: dropping this template does **not** overwrite the builder's current flow — its two screens are appended after the existing ones, and "Personal Info" becomes the active screen. The `metadata.name` above documents the template but is not merged into the current flow.
+
+### Passing to FBT
+
+```tsx
+import { FBT } from "@sonata-innovations/fiber-fbt";
+import "@sonata-innovations/fiber-fbt/styles";
+import type { AnyPresetDefinition, AnyTemplateDefinition } from "@sonata-innovations/fiber-fbt";
+
+const MY_PRESETS: AnyPresetDefinition[] = [ssnPreset, emergencyContactPreset];
+const MY_TEMPLATES: AnyTemplateDefinition[] = [onboardingTemplate];
+
+function App() {
+  return (
+    <FBT
+      flow={existingFlow}
+      onFlowChange={handleFlowChange}
+      customPresets={MY_PRESETS}
+      customTemplates={MY_TEMPLATES}
+    />
+  );
+}
+```
+
+Both props are optional; if omitted, FBT shows only its built-in items. Keep the arrays referentially stable (module constants or memoized) — the context memoizes its lookup maps on the array identities.
+
+## Factory-based definitions (back-compat)
+
+```ts
+// @sonata-innovations/fiber-fbt
+export type CustomPresetDefinition = {
+  type: string;
+  label: string;
+  icon: string;
+  factory: () => Component[];
+};
+
+export type CustomTemplateDefinition = {
+  type: string;
+  label: string;
+  icon: string;
+  factory: () => Flow;
+};
+```
+
+With a factory, **you** are responsible for returning fresh UUIDs on every call — FBT does not regenerate UUIDs for factory-based definitions. You would still use a factory when the definition must be computed at drop time (e.g. injecting the current date, user data, or environment-dependent options):
+
+```ts
+import type { CustomPresetDefinition } from "@sonata-innovations/fiber-fbt";
+
+const visitDatePreset: CustomPresetDefinition = {
+  type: "custom-visitDate",
+  label: "Visit Date",
+  icon: "date",
+  factory: () => [
+    {
+      uuid: crypto.randomUUID(),
+      type: "date",
+      properties: {
+        label: "Visit Date",
+        min: new Date().toISOString().slice(0, 10), // today, computed at drop
+        validation: { rules: [{ type: "required" }] },
+      },
+    },
+  ],
+};
+```
+
+For anything static, prefer `PresetData`/`TemplateData`.
+
+## How resolution works
+
+1. **Context injection** — the FBT provider builds `presetMap` / `templateMap` (`Map<string, () => Component[] | Flow>`) from the prop arrays, keyed by `type`. Factory definitions map to their `factory`; data definitions map to a wrapper that regenerates UUIDs. If two custom definitions share a `type`, the later one in the array wins (plain `Map.set` overwrite).
+2. **Kind by prop array** — items from `customPresets` are tagged `kind: "preset"`, items from `customTemplates` are tagged `kind: "template"` when the pool renders them. The `type` string plays no part in this.
+3. **Built-in-first lookup at drop** — the DnD handler resolves the dropped `type` against the **built-in** definitions first, and only falls back to the custom map if that returns nothing:
+
+   ```ts
+   // fbt/src/ui/dnd/dnd-wrapper.tsx
+   const flow = createTemplate(item.type) ?? templateMap.get(item.type)?.();
+   const components = createPreset(item.type) ?? presetMap.get(item.type)?.();
+   ```
+
+### Collision rules
+
+There is **no required prefix** on custom `type` strings — FBT accepts any string. But because built-in lookup runs first, a custom definition whose `type` equals a built-in key is **silently shadowed**: your pool entry shows your label and icon, but dropping it produces the built-in content.
+
+Built-in keys to avoid — presets: `preset-phone`, `preset-email`, `preset-date`, `preset-url`, `preset-fullName`, `preset-dollarAmount`, `preset-password`, `preset-addressBlock`, `preset-contactInfo`, `preset-nameFields`, `preset-agreement`; templates: `template-contactForm`, `template-signUp`, `template-patientIntake`, `template-feedbackSurvey`.
+
+**Recommendation:** use a distinct namespace such as `custom-*`. No built-in uses it, and it matches what the Fiber server enforces for stored definitions (see below).
+
+## Icon catalog
+
+`icon` is a key into FBT's `ICON_MAP` (`fbt/src/lib/icons.tsx`) — 46 built-in SVG icons. Icon keys are their own namespace: they often mirror component types but are not the same set (e.g. the paragraph-text icon is `descriptionText` while the component type is `text`; `select` is the dropdown icon). If the key is unknown, the item renders with an empty icon slot — no error, graceful fallback.
+
+### Display & structure
+
+| Key | Glyph |
+|-----|-------|
+| `header` | Heading lines |
+| `descriptionText` | Paragraph lines |
+| `divider` | Horizontal rule |
+| `callout` | Info box |
+| `table` | Grid |
+
+### Text & number inputs
+
+| Key | Glyph |
+|-----|-------|
+| `textInput` | Single-line field |
+| `textArea` | Multi-line field |
+| `numberInput` | Field with `#` |
+| `dollarAmount` | Field with `$` |
+| `phone` | Phone handset/device |
+| `email` | Envelope |
+| `url` | Chain link |
+| `password` | Padlock |
+
+### Selection
+
+| Key | Glyph |
+|-----|-------|
+| `select` | Dropdown |
+| `multiSelect` | Checked list |
+| `checkbox` | Checked box |
+| `radio` | Radio dot |
+| `toggleSwitch` | Switch |
+| `yesNo` | Check/cross pair |
+| `confirm` | Checked box (shares the `checkbox` glyph) |
+| `cardSelect` | Card grid |
+
+### Date & time
+
+| Key | Glyph |
+|-----|-------|
+| `date` | Calendar |
+| `time` | Clock |
+| `dateTime` | Calendar + clock |
+| `dateRange` | Two calendars |
+| `timeRange` | Two clocks |
+| `dateTimeRange` | Two calendar+clock pairs |
+
+### Interactive & special
+
+| Key | Glyph |
+|-----|-------|
+| `fileUpload` | Upload arrow |
+| `rating` | Star |
+| `slider` | Slider track |
+| `colorPicker` | Color wheel |
+| `signature` | Signature stroke |
+| `repeater` | Stacked dashed rows |
+| `calculated` | `fx` in a box |
+
+### People & preset-flavored
+
+| Key | Glyph |
+|-----|-------|
+| `fullName` | Person |
+| `addressBlock` | Map pin |
+| `contactInfo` | Contact card |
+| `nameFields` | Paired fields |
+| `agreement` | Document with check |
+| `ssn` | Masked field (`***`) |
+| `emergencyContact` | Person with plus |
+
+### Template-flavored
+
+| Key | Glyph |
+|-----|-------|
+| `signUpForm` | Form with avatar |
+| `patientIntake` | Bulleted form |
+| `feedbackSurvey` | Form with star |
+| `contactForm` | Form lines |
+| `employeeOnboarding` | Document lines |
+
+## Server-stored definitions
+
+The Fiber server (private package, not published) provides tenant-scoped storage for data-based definitions:
+
+- CRUD endpoints at `/api/v1/presets` and `/api/v1/templates`, storing `PresetData` / `TemplateData` JSON per tenant.
+- The server **rejects** any stored definition whose `type` does not start with `custom-` — this prefix guarantees no collision with built-in keys.
+- The portal provides management pages for presets and templates, and its flow editor fetches the tenant's custom definitions on mount.
+
+From FBT's perspective there is nothing special about server-stored definitions: the parent app fetches them and passes them through the same `customPresets` / `customTemplates` props as data-based definitions.
+
+## UI behavior
+
+- When either prop array is non-empty, the corresponding pool tab (Presets or Templates) appends a **CUSTOM** section after the built-in sections, containing one item per definition.
+- Custom items carry a **star badge** in place of the colored accent that built-in preset/template items get; search results label them with a "Custom" badge.
+- Items are drag-and-drop onto the stage. Icon resolution is `ICON_MAP[item.icon]` guarded by `{Icon && <Icon />}` — an unknown key renders nothing.

package/docs/features/style-families.md

@@ -0,0 +1,217 @@
+---
+title: Style Families & Advance Behaviors
+applies-to:
+  - "@sonata-innovations/fiber-fbre@^4.0"
+  - "@sonata-innovations/fiber-types@^3.0"
+  - "@sonata-innovations/fiber-fbt@^3.0"
+  - "@sonata-innovations/fiber-fbtl@^3.0"
+  - "@sonata-innovations/fiber-theme-editor@^2.0"
+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."
+---
+
+<!-- Generated from the Fiber repo's docs/ tree by project/scripts/sync-package-docs.mjs. Do not edit here. -->
+# Style Families & Advance Behaviors
+
+A Fiber form's presentation is decided by one setting — `config.theme.style` —
+and its two advance behaviors by two more — `config.navigation.autoAdvance` and
+`config.navigation.advanceOnEnter`. That is the whole model. There is no
+presentation mode.
+
+> **Migrating from an earlier version?** `config.mode` (`"standard"` /
+> `"conversational"`) was removed. Jump to [Migrating off `config.mode`](#migrating-off-configmode).
+
+## The ten styles are one flat vocabulary
+
+Any style is valid on any flow. Four of them share an extra presentation
+treatment, and that shared half is called a **family**:
+
+| Family | Styles |
+| --- | --- |
+| `"form"` | `clean`, `outlined`, `refined-clean`, `airy-clean`, `soft-outlined`, `defined-outlined` |
+| `"focused"` | `centered-minimal`, `stacked-cards`, `soft-float`, `bold-statement` |
+
+On top of whichever of the four you pick, the focused family adds:
+
+| Treatment | What it does |
+| --- | --- |
+| **Vertical centering** | Content sits centered in a narrow column, falling back to top-aligned and scrollable when a screen is taller than the viewport |
+| **Animated entry** | Components fade and scale in with staggered delays. Respects `prefers-reduced-motion` |
+| **Larger tap targets** | Option items, Yes/No buttons, card-select cards and inputs are enlarged |
+| **Bolder type** | Headers, labels, prompts and inputs step up in size |
+
+Each of the four styles then applies its own look — underline inputs, filled
+cards, pill options, heavy borders — exactly as each of the six form styles
+does.
+
+### The family is derived, never authored
+
+It does not appear in Flow JSON. FBRE computes it from `theme.style` and emits
+it on the container as `data-style-family`, next to `data-style`:
+
+```html
+<div class="fbre-container" data-style="soft-float" data-style-family="focused">
+```
+
+That is what lets the ~32 shared rules live under one selector instead of a
+repeated four-way list. If you write custom CSS against a focused form, target
+`[data-style-family="focused"]` for anything that should apply to all four and
+`[data-style="…"]` for one style.
+
+`fiber-types` (and `fiber-fbre`, which re-exports it) publishes the derivation
+so a builder can group its own style picker from one list:
+
+```ts
+import { FOCUSED_STYLES, styleFamily } from "@sonata-innovations/fiber-types";
+
+styleFamily("bold-statement"); // "focused"
+styleFamily("clean");          // "form"
+styleFamily(undefined);        // "form"  — the `clean` default
+
+FOCUSED_STYLES.has("soft-float"); // true
+```
+
+### Why this matters for server-driven rendering
+
+The session protocol sends `config.theme`. Because presentation is *derived
+from* `theme.style`, a focused-styled flow renders identically whether it is
+rendered locally, fetched remotely, or served one screen at a time by a
+session — no extra field has to be carried, and none can be forgotten.
+
+## Advance behaviors
+
+Auto-advance and Enter-to-advance are independent `navigation` flags. Neither is
+tied to a style: a `clean` form with one question per screen advances on Enter,
+and a `bold-statement` flow only auto-advances if it asks to.
+
+| Flag | Default | Behavior |
+| --- | --- | --- |
+| `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 |
+| `navigation.advanceOnEnter` | `true` | Advance when Enter is pressed in an `inputText` or `inputNumber`. `inputTextArea` is excluded — Enter inserts a newline there |
+
+```jsonc
+{
+  "config": {
+    "theme": { "style": "centered-minimal" },
+    "navigation": {
+      "transition": "scaleFade",
+      "autoAdvance": true,
+      "advanceOnEnter": true
+    }
+  }
+}
+```
+
+The defaults are deliberately asymmetric. A form that moves without a click is
+surprising, and shifting content and focus ~500ms after a selection carries a
+real accessibility cost — so `autoAdvance` is opt-in. Enter-to-advance is an
+ordinary form convention, so it is on.
+
+### Guards
+
+Both behaviors share the same guards. None of them are configurable — they are
+correctness guards, not policy:
+
+- Neither fires on a screen with **more than one visible input**. A shared
+  screen behaves like a normal form, so components after the first are never
+  skipped. (Conditionally hidden inputs don't count toward the total.)
+- Neither fires on the last screen — so Enter can never submit the form.
+- Neither fires when the screen fails validation.
+- Both respect condition-hidden screens, skipping to the next reachable one.
+- Auto-advance does not fire during an active screen transition.
+- Enter-to-advance stands down inside an open popup (`.fbre-popup`), so Enter
+  there commits the value rather than skipping the screen. Today this affects
+  one component: the colour picker's hex field is the only `<input>` rendered
+  inside an overlay. The date/time pickers and both dropdowns use buttons and
+  `role="option"` elements, which Enter-to-advance already ignores.
+
+The single-visible-input guard is worth designing around: turning `autoAdvance`
+on for a flow whose screens hold several questions each does nothing at all.
+Both builders say so — FBT warns on a multi-input screen tab, FBTL notes it on
+the divider that merges two cards onto one screen.
+
+## In the builders
+
+Neither builder stores a mode. Each offers a preset that writes the settings the
+focused look is made of, after which every one of them stays individually
+editable:
+
+- **FBT** — a *Focused presentation* preset in the Appearance section writes
+  `theme.style: "centered-minimal"` and `navigation: { transition: "scaleFade",
+  autoAdvance: true }`. The style picker lists all ten styles, captioned *Form*
+  and *Focused*.
+- **FBTL** — its default config already uses `centered-minimal` with
+  `autoAdvance: true`. Pacing (one question per screen vs all on one page) is a
+  separate concern there: see `screenModel` in the
+  [FBTL Integration Guide](@sonata-innovations/fiber-fbtl/docs/integration/fbtl.md#screen-model).
+- **Theme Editor** — the style dropdown lists all ten, grouped under *Form* and
+  *Focused* headings. Its value is `{ theme }`.
+
+## Migrating off `config.mode`
+
+`FlowConfiguration.mode`, the `FlowModeType` type, and FBRE's `mode` prop are
+gone. Each of `mode`'s jobs moved somewhere it belongs:
+
+| Was | Now |
+| --- | --- |
+| `mode: "conversational"` for the centered, animated presentation | the focused **style** already on the flow — nothing to set |
+| `mode: "conversational"` for auto-advance | `navigation.autoAdvance: true` |
+| `mode: "conversational"` for Enter-to-advance | `navigation.advanceOnEnter` — on by default now, for every flow |
+| `mode` deciding which styles were legal | nothing — the vocabulary is flat |
+
+### Updating a stored flow
+
+A flow that had `mode: "conversational"` already carried a focused
+`theme.style`, so **its look survives untouched**. The only behavior that
+changes is auto-advance, which is now off unless asked for:
+
+```jsonc
+// before
+{ "config": {
+    "mode": "conversational",
+    "theme": { "style": "centered-minimal" },
+    "navigation": { "transition": "scaleFade" }
+} }
+
+// after
+{ "config": {
+    "theme": { "style": "centered-minimal" },
+    "navigation": { "transition": "scaleFade", "autoAdvance": true }
+} }
+```
+
+A flow that had `mode: "standard"` (or no `mode` at all) needs only the field
+deleted. It gains Enter-to-advance on its one-question screens, which was
+previously withheld for no reason anyone could see.
+
+`mode` is not read anywhere any more, so leaving a stale `"mode"` key in stored
+JSON is inert rather than harmful — but the schema no longer describes it, and
+`npm run validate` will not vouch for it.
+
+### Updating code
+
+```diff
+-<FBRE flow={flow} mode="conversational" onFlowComplete={done} />
++<FBRE
++  flow={flow}
++  theme={{ style: "centered-minimal" }}
++  navigation={{ autoAdvance: true }}
++  onFlowComplete={done}
++/>
+```
+
+```diff
+-<ThemeEditor mode={value.mode} theme={value.theme} onChange={setValue} />
++<ThemeEditor theme={value.theme} onChange={setValue} />
+```
+
+The theme editor's `STANDARD_STYLE_OPTIONS`, `CONVERSATIONAL_STYLE_OPTIONS`,
+`styleOptionsForMode` and `reconcileStyle` exports are replaced by a single
+`STYLE_OPTIONS` array; use `styleFamily()` from `fiber-types` if you need the
+partition.
+
+## Related
+
+- [Flow Schema → Style Families](../schema/flow-schema.md#style-families)
+- [FBRE Theming Guide](@sonata-innovations/fiber-fbre/docs/features/fbre-theming.md) — palette tokens, brand fonts, and how a
+  style's preset interacts with the knobs
+- [FBRE Integration Guide → Focused Presentation](@sonata-innovations/fiber-fbre/docs/integration/fbre.md#focused-presentation)