The ControlPlugin Interface

ControlPlugin Interface

interface ControlPlugin {
  // Required
  type: string;              // Unique type key (namespace:name recommended)
  label: string;             // Palette display name

  // Optional metadata
  group?: string;            // Palette group: 'input' | 'display' | 'layout' | 'chart' | 'media' | 'advanced'
  icon?: string;             // Font Awesome icon name
  description?: string;      // Tooltip / palette description

  // Default configuration applied when control is dropped
  defaultConfig?: Record<string, any>;

  // JSON Schema for the control's settings (used by property panel)
  schema?: ControlPropertySchema;

  // Validation
  supportedValidators?: string[];  // Which built-in validator names this control supports
}

type — The Unique Identifier

The type string is the most important field. It must be globally unique across all installed control libraries. Use the same namespacing convention as action types:

// Good — namespaced
type: 'myorg:phone-input'
type: 'acme:address-picker'
type: '@myorg/crm:account-lookup'

// Bad — could conflict with built-ins or other libraries
type: 'phone'
type: 'address'
type: 'lookup'

group — Palette Grouping

The group field determines which palette section your control appears in:

defaultConfig

Configuration values applied automatically when the control is dropped onto the canvas. These map to the settings field of FormControl:

defaultConfig: {
  defaultCountry: 'US',
  showFlag: true,
  format: 'international',
  allowedCountries: null  // null = all countries
}

schema — Property Panel Definition

The schema field defines the control-specific properties that appear in the Form Studio property panel's Advanced tab. It uses a simplified JSON Schema-like structure:

schema: {
  properties: {
    defaultCountry: {
      type: 'string',
      label: 'Default Country',
      widget: 'select',
      options: [
        { value: 'US', label: 'United States' },
        { value: 'GB', label: 'United Kingdom' },
        { value: 'AU', label: 'Australia' }
      ]
    },
    showFlag: {
      type: 'boolean',
      label: 'Show Country Flag'
    },
    format: {
      type: 'string',
      label: 'Phone Format',
      widget: 'select',
      options: [
        { value: 'international', label: 'International (+1 555 000 0000)' },
        { value: 'national', label: 'National (555) 000-0000)' }
      ]
    }
  }
}