Widget Definition

What Is a Widget Definition?

A Widget Definition is registered globally in App Studio's Widget Registry. It is not app-specific — it describes what a type of widget can do, not how it is configured in a particular app. Think of it as the blueprint for all instances of that widget type.

Widget Definition Structure

// TypeScript — WidgetDefinition interface
interface WidgetDefinition {
  // Identity
  widgetTypeId: string;        // e.g., "DataGrid"
  displayName: string;         // "Data Grid" — shown in palette
  description: string;         // One-line description for tooltip
  category: string;            // "Data Display", "Input", "Layout", etc.
  icon: string;                // Font Awesome icon name

  // Configuration schema
  configSchema: JsonSchema;    // JSON Schema defining allowed config properties
  defaultConfig: Record<string, unknown>; // Default values for all config properties

  // Events this widget can emit
  events: WidgetEventDefinition[]; // e.g., [{name: "onClick"}, {name: "onRowSelect"}]

  // Render
  component: React.ComponentType<WidgetRenderProps>;
  // OR for federated custom widgets:
  federationUrl?: string;      // URL of the remote module
  federationModule?: string;   // Module name in the remote
}

Config Schema

The configSchema is a JSON Schema document describing all configuration properties the widget accepts. The Properties Editor uses this schema to auto-generate the correct input controls (text field, dropdown, toggle, array editor, etc.) for each property.

// DataGrid configSchema (excerpt)
{
  "type": "object",
  "required": ["dataSource", "columns"],
  "properties": {
    "dataSource": {
      "type": "string",
      "title": "Data Source",
      "description": "AIExtension.Service method name"
    },
    "columns": {
      "type": "array",
      "title": "Columns",
      "items": {
        "type": "object",
        "properties": {
          "field": { "type": "string" },
          "header": { "type": "string" },
          "sortable": { "type": "boolean", "default": true },
          "width": { "type": "number" }
        }
      }
    },
    "pageSize": {
      "type": "number",
      "title": "Page Size",
      "default": 20
    },
    "selectable": {
      "type": "boolean",
      "title": "Row Selection",
      "default": false
    }
  }
}

Default Config

The defaultConfig object provides initial values for all config properties. When a widget is placed on the canvas for the first time, these defaults populate the configuration:

// DataGrid defaultConfig
{
  "pageSize": 20,
  "selectable": false,
  "sortable": true,
  "columns": []
}

Widget Events

Each Widget Definition declares the events it can emit — these are the events that appear in the Actions tab of the Properties Editor for that widget type: