Widget Registry Reference

SDK API reference for the widget registry — the canonical source of truth for all field widget types.

Location

Package: @biloxistudios/studiobrain-sdk Source: packages/sdk/src/templates/widget-registry.ts Import: import { registerWidget, getWidget, ... } from '@biloxistudios/studiobrain-sdk'

Types

WidgetDefinition

interface WidgetDefinition {
  /** Unique widget identifier (e.g., 'color-palette', 'entity-selector') */
  id: string;
  /** Human-readable label */
  label: string;
  /** Short description of what this widget does */
  description: string;
  /** Grouping category for UI organization */
  category: WidgetCategory;
  /** Where this widget comes from */
  source: 'builtin' | 'plugin' | 'community';
  /** The JSON Schema type of the value this widget produces */
  value_type?: 'string' | 'number' | 'boolean' | 'array' | 'object';
  /** Whether this widget accepts an options list (for select/radio/checkbox) */
  accepts_options?: boolean;
  /**
   * Name patterns for inference. When inferWidgetFromName() sees a field name
   * matching any of these patterns, it suggests this widget. Patterns are
   * case-insensitive regex fragments tested against the field name.
   */
  name_patterns?: string[];
}

WidgetCategory

type WidgetCategory =
  | 'text'
  | 'number'
  | 'selection'
  | 'date'
  | 'color'
  | 'entity'
  | 'array'
  | 'media'
  | 'document'
  | 'spatial'
  | 'layout'
  | string; // extensible for plugins

The string union member allows plugins to introduce custom categories without modifying the SDK.

Functions

registerWidget(widget)

Register a single widget definition. If a widget with the same id already exists, it is replaced.

function registerWidget(widget: WidgetDefinition): void

Example:

import { registerWidget } from '@biloxistudios/studiobrain-sdk';
 
registerWidget({
  id: 'recipe-timer',
  label: 'Recipe Timer',
  description: 'Duration input with cooking presets',
  category: 'number',
  source: 'plugin',
  value_type: 'number',
  name_patterns: ['cook_time', 'prep_time', 'bake_time', 'timer'],
});

registerWidgets(widgets)

Batch-register multiple widgets. Used by plugin loaders to register all widgets from a plugin manifest at once.

function registerWidgets(widgets: WidgetDefinition[]): void

Example:

import { registerWidgets } from '@biloxistudios/studiobrain-sdk';
 
// Called by the plugin loader after parsing plugin.json
registerWidgets([
  {
    id: 'music-key',
    label: 'Musical Key',
    description: 'Key signature selector with circle-of-fifths UI',
    category: 'selection',
    source: 'plugin',
    value_type: 'string',
    accepts_options: false,
    name_patterns: ['key_signature', 'musical_key', 'song_key'],
  },
  {
    id: 'bpm-input',
    label: 'BPM Input',
    description: 'Tempo input with tap-to-set and common presets',
    category: 'number',
    source: 'plugin',
    value_type: 'number',
    name_patterns: ['bpm', 'tempo'],
  },
]);

getWidget(id)

Look up a widget definition by ID. Returns undefined for unknown widgets.

Unknown widgets are valid — field_config.widget passes through verbatim. This function is for metadata lookup, not gatekeeping.

function getWidget(id: string): WidgetDefinition | undefined

getWidgetValueType(id)

Get the value_type for a widget ID. Returns 'string' for unknown widgets.

function getWidgetValueType(id: string): string

This is the function used by inferField() and templateToEntitySchema() to determine the JSON Schema type when a widget is resolved.

getAllWidgets()

Get all registered widgets (builtins + plugins). Returns a copy of the internal array.

function getAllWidgets(): WidgetDefinition[]

getWidgetsByCategory()

Get all registered widgets grouped by their category value.

function getWidgetsByCategory(): Record<string, WidgetDefinition[]>

inferWidgetFromName(fieldName)

Match a field name against all registered name_patterns. Returns the first matching widget, or undefined if no pattern matches.

function inferWidgetFromName(fieldName: string): WidgetDefinition | undefined

Patterns are compiled once on registration and cached. Each widget’s name_patterns array is joined with | into a single case-insensitive regex.

resetRegistry()

Reset the registry to builtins only. This is a test utility — do not call in production code.

function resetRegistry(): void

field_config.widget Pass-Through

The registry does not restrict what widget IDs can appear in field_config.widget. Any string is valid:

field_config:
  my_field:
    widget: some-future-widget-that-doesnt-exist-yet

When the frontend encounters an unknown widget ID, it falls back to rendering a text input. The registry is consulted only for:

1. Value type inference — getWidgetValueType() returns 'string' for unknown IDs
2. Name pattern inference — only registered widgets participate in inferWidgetFromName()
3. Layout Designer UI — the widget picker shows registered widgets with labels and categories

This design means templates can reference plugin widgets before the plugin is installed. The field simply renders as a text input until the plugin is loaded.

Integration with Other SDK Functions

templateToFormFields()

Located in src/templates/form-fields.ts. Converts template YAML into form field descriptors. Checks field_config.widget first, then falls back to the TYPE_MAP for the template field type. Does not call the widget registry directly — it trusts the widget string from field_config.

templateToEntitySchema()

Located in src/schemas/entity-schema.ts. Builds a full EntitySchema from a template. For each field:

1. Calls inferField(key, value) which internally calls inferWidgetFromName(key) from the registry
2. If field_config[key].widget exists, it overrides the inferred ui_component

inferField()

Located in src/templates/field-inference.ts. Infers field type and UI widget from a field name and sample value. Priority:

1. Array with string elements -> multi-select
2. Boolean -> boolean
3. Number -> check registry patterns, fallback to number
4. String -> check registry patterns, length-based heuristic fallback
5. Object -> check registry patterns, fallback to textarea

Built-in Widget Table

The complete set of 48 built-in widgets with their registry metadata:

Text & Content (9)

Numbers & Ranges (7)

Selection (7)

Date & Time (5)

Color (3)

Entity References (2)

Arrays & Structures (7)

Media References (6)

Spatial (2)

Layout (1)

Document (2)

Related Documentation

• Widget System Architecture — resolution pipeline, extension model
• Field Widgets Reference — per-widget options, value formats, YAML examples
• Building Field Widgets — plugin development tutorial