@sonata-innovations/fiber-fbtl

Fiber Tool Lite — an end-user-friendly Flow builder for non-technical authors embedded in parent apps.

FBTL is a stripped-down alternative to @sonata-innovations/fiber-fbt with a minimal, hand-holding UX. Both tools produce the same Flow JSON schema, so any Flow is portable between them. FBTL is designed to be dropped into a parent application so end users (clinicians, teachers, etc.) can author their own forms without needing developer knowledge.

Install

npm install @sonata-innovations/fiber-fbtl

@sonata-innovations/fiber-types, @sonata-innovations/fiber-shared, and @sonata-innovations/fiber-fbre are direct dependencies and will be installed automatically. react and react-dom (v18 or v19) are required as peer dependencies in the host app.

Usage

import { FBTL } from "@sonata-innovations/fiber-fbtl";
import "@sonata-innovations/fiber-fbtl/styles";
import type { Flow } from "@sonata-innovations/fiber-fbtl";

function App() {
  const [flow, setFlow] = useState<Flow>(initialFlow);
  return <FBTL flow={flow} onChange={setFlow} />;
}

Props

| Prop | Type | Description | |---|---|---| | flow | Flow | Required. Current flow. Controlled — parent owns state. | | onChange | (flow: Flow) => void | Called on every mutation. Parent persists. | | metadata | FlowMetadata | Read-only metadata shown in the UI. | | theme | ThemeConfig | Passed to the preview pane. | | navigation | NavigationConfig | Passed to the preview pane. | | controls | ControlsConfig | Passed to the preview pane. | | saveState | "idle" \| "saving" \| "saved" \| "error" | Drives the save pill. | | onSaveRetry | () => void | Retry button handler when saveState === "error". | | disabledQuestionTypes | string[] | Hide question types from the creation wizard. | | locale | string | i18n locale (future). | | className | string | Applied to the root container. |

Composable layout

For custom layouts, use sub-components directly instead of <FBTL>:

import {
  FBTLProvider,
  FBTLDndZone,
  FBTLStage,
  FBTLPreview,
  FBTLWizardHost,
  FBTLUndoToast,
} from "@sonata-innovations/fiber-fbtl";

<FBTLProvider flow={flow} onChange={onChange}>
  <div className="fbtl-container my-layout">
    <FBTLDndZone>
      <FBTLStage />
    </FBTLDndZone>
    <FBTLPreview />
    <FBTLWizardHost />
    <FBTLUndoToast />
  </div>
</FBTLProvider>

Styling

All visual values live in src/styles/tokens.css as CSS custom properties. Override at any selector above the FBTL root:

.my-app {
  --fbtl-primary: #4f46e5;
  --fbtl-primary-dark: #4338ca;
  --fbtl-radius-md: 8px;
}

Component styles live alongside their components and use only token variables — no hardcoded colors or pixel values. Design iteration happens in the tokens file.

Full token list: see src/styles/tokens.css.

Playground

fbtl/dev/ hosts a development playground for exercising FBTL against sample flows (empty, demo with conditions and information screens).

# From the workspace root:
npm run dev:fbtl

# Or from fbtl/:
npm run dev:playground

Component support

FBTL produces and consumes the full Flow JSON schema, but its authoring surface is intentionally smaller than the FBRE component registry. The matrix below is the authoritative answer to "can my end users build/edit this, or does it need to be pre-authored in FBT?" — useful when deciding what to preload into a flow.

Legend:

• Create — the end user can add this via the FBTL creation wizard.
• Edit — if present in a loaded flow, what the stage card exposes.
• Round-trip — survives load → emit unchanged (✓ for every registered FBRE component).

| FBRE component | Create | Edit surface | Round-trip | |---|---|---|---| | inputText | ✓ Short answer | label, required, format chip (read-only) | ✓ | | inputNumber | ✓ via Short answer → Number format | label, required, format chip (read-only) | ✓ | | inputTextArea | ✓ Long answer | label, required | ✓ | | dropDown, radio, cardSelect | ✓ Pick one | label, required, display switcher, options editor* | ✓ | | dropDownMulti, checkbox | ✓ Pick several | label, required, display switcher, options editor* | ✓ | | yesNo | ✓ (auto when Pick one has ≤2 options) | label, required, display switcher | ✓ | | confirm | ✓ Confirmation | label, required | ✓ | | header + text (wrapped in a group) | ✓ Information Screen | heading, paragraph | ✓ | | date, time, dateTime, dateRange, timeRange, dateTimeRange | — | label, required only | ✓ | | slider, rating, fileUpload, signature, colorPicker, toggleSwitch | — | label, required only | ✓ | | callout, divider, table | — | label, required (Required is usually nonsensical here) | ✓ | | computed | — | label, required + advanced badge (calculation is read-only) | ✓ | | repeater | — | label, required + advanced badge (inner components are read-only) | ✓ | | group (header/text only) | ✓ as Information Screen | heading, paragraph | ✓ | | group (mixed content) | — | — (renders as a read-only "Section" card) | ✓ |

* Options editor is disabled on components whose options carry metadata — those are treated as rich/advanced and get a badge instead.

Advanced-property preservation. When a loaded component has features FBTL can't edit — multi-rule conditions, cross-field validation, complex validators, reference markup ({{…}}), rich option metadata, calculations, or is a repeater / computed — it renders with a neutral "Has custom configuration" badge. The properties are round-tripped verbatim; FBTL is self-contained and does not offer an "Edit in FBT" link.

Guidance for integrators. If your end users need to author a given question type, prefer seeding flows with components from the ✓ Create rows above. Components from the "Edit" column work but only expose label/required, so pre-configure their properties (min/max, accept lists, range bounds, etc.) in FBT or at the data layer before handing the flow to FBTL.

Other v1 scope

Creation-side features beyond the component matrix:

• Required toggle on every question
• Short Answer format sub-choice (Any / Email / Phone / URL / Number)
• Single-rule conditions between top-level questions (drag-to-condition or Make Conditional button)
• Per-card page-break toggles (v1.2): the small pill between adjacent cards toggles whether the next card lands on its own screen or shares the screen above. New questions default to ending a screen, preserving the historical one-question-per-screen feel until the author opts in.

Not in FBTL v1:

• Editable screen labels or a first-class screen container concept (screen boundaries are expressed only via the page-break toggles)
• Custom component creation, calculations editor, reference markup editor
• Full undo/redo (only a delete-toast undo is implemented)