@sonata-innovations/fiber-theme-editor

A plug-and-play theming widget for Fiber. It is a controlled editor for the theme slice of a flow's configuration — pick a light/dark scheme, accent color, style, and (optionally) every palette token — beside a live FBRE preview that renders the real form with the chosen theme.

The editor's value is { theme } — the ThemeConfig that lives on FlowConfiguration.theme. Splice it back into your flow with flow.config.theme = value.theme.

Upgrading from 1.x: the value and the mode prop no longer carry mode; FlowConfiguration.mode was removed. Drop the prop and stop writing flow.config.mode — the style a flow already uses carries its own presentation.

Install

npm install @sonata-innovations/fiber-theme-editor

Peer dependencies

Install these alongside it (the editor renders a real FBRE preview, so it shares your app's FBRE and types instances rather than bundling its own):

npm install react react-dom @sonata-innovations/fiber-fbre @sonata-innovations/fiber-types

Peer version ranges: react / react-dom ^18.0.0 || ^19.0.0, @sonata-innovations/fiber-fbre ^3.2.1, @sonata-innovations/fiber-types ^2.0.0.

Documentation

Full docs ship inside this package under docs/, so they land in node_modules/@sonata-innovations/fiber-theme-editor/docs/ at the exact version you installed. AGENTS.md at the package root is the routing guide — start there when pointing an AI agent at the package. The same docs are browsable in the public mirror.

| Doc | In package | Browse | |-----|------------|--------| | Fiber concepts (Flow → Screen → Component) | docs/fiber-concepts.md | mirror | | Theme editor integration guide | docs/integration/theme-editor.md | mirror | | Flow JSON schema | ships in @sonata-innovations/fiber-types under docs/schema/ | schema · quick ref |

Styles

Import the editor's stylesheet and FBRE's stylesheet (the preview needs it):

import "@sonata-innovations/fiber-theme-editor/styles";
import "@sonata-innovations/fiber-fbre/styles";

Usage

The widget is fully controlled — hold { mode, theme } in your own state:

import { useState } from "react";
import {
  ThemeEditor,
  FBTL_KNOBS,
  type ThemeEditorValue,
} from "@sonata-innovations/fiber-theme-editor";
import "@sonata-innovations/fiber-theme-editor/styles";
import "@sonata-innovations/fiber-fbre/styles";

function ThemePanel() {
  const [value, setValue] = useState<ThemeEditorValue>({
    theme: { colorScheme: "light" },
  });

  return (
    <ThemeEditor theme={value.theme} onChange={setValue} knobs={FBTL_KNOBS} />
  );
}

Props

| Prop | Type | Default | Description | | ------------- | -------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------- | | theme | ThemeConfig | — | Current theme. Any subset of knobs may be set; unset knobs fall through to the scheme/style preset. | | onChange | (next: ThemeEditorValue) => void | — | Fired on every change with the full { theme }. | | defaultTab | "settings" \| "palette" | "settings" | Which pane is open on mount. | | knobs | ThemeKnob[] | full set | Which palette knobs the Palette tab exposes. Use the FBTL_KNOBS / FBT_KNOBS presets. | | defaults | ThemeConfig | FBRE built-ins | Baseline shown as placeholder/swatch for unset knobs, and merged under theme in the preview. | | previewFlow | Flow | kitchen sink | Flow rendered in the live preview. | | className | string | — | Extra class on the root element. |

Knob presets

• FBTL_KNOBS — background, surface, text, border, radius, fontFamily, error.
• FBT_KNOBS — the above plus success, warning (the callout-only colors).

The font knob edits a CSS stack, not a font file. On a theme whose fontFamily is a loadable config ({ family, src }), the field shows the stack it resolves to and editing rewrites the stack while keeping the sources; clearing drops the whole key.

Exports

• ThemeEditor — the widget.
• FBTL_KNOBS, FBT_KNOBS, KNOB_DEFS — knob sets and metadata.
• LIGHT_THEME_DEFAULTS, DARK_THEME_DEFAULTS, resolveThemeDefaults — the built-in default values shown as placeholders.
• buildGlossary, SETTINGS_GLOSSARY, KNOB_GLOSSARY — the in-widget glossary copy.
• STYLE_OPTIONS — the style dropdown's option list (all ten, in picker order). The dropdown groups them under Form / Focused headings; styleFamily() from fiber-types is the source of truth for that partition.
• buildPreviewFlow, defaultPreviewFlow — the default preview flow.
• Types: ThemeEditorProps, ThemeEditorValue, ThemeEditorTab, ThemeKnob, GlossaryEntry, KnobDef, KnobKind, StyleOption.

License

MIT