@sonata-innovations/fiber-types 2.2.0 → 2.5.0

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

@@ -0,0 +1,428 @@
+---
+title: Custom Presets & Templates (FBT)
+applies-to:
+  - "@sonata-innovations/fiber-fbt@^2.2"
+  - "@sonata-innovations/fiber-types@^2.2"
+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.