component.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://formspec.org/schemas/component/1.0",
  "title": "Formspec Component Document",
  "description": "A Formspec Component Document per the Component Specification v1.0. Defines a Tier 3 parallel presentation tree of UI components bound to a Formspec Definition's items via slot binding. The component tree controls layout and widget selection but cannot override core behavioral semantics (required, relevant, readonly, calculate, constraint) from the Definition. Multiple Component Documents MAY target the same Definition for platform-specific presentations.",
  "type": "object",
  "required": [
    "$formspecComponent",
    "version",
    "targetDefinition",
    "tree"
  ],
  "patternProperties": {
    "^x-": true
  },
  "additionalProperties": false,
  "properties": {
    "$formspecComponent": {
      "type": "string",
      "const": "1.0",
      "description": "Component specification version. MUST be '1.0'.",
      "examples": ["1.0"],
      "x-lm": {
        "critical": true,
        "intent": "Version pin for component document compatibility."
      }
    },
    "url": {
      "type": "string",
      "format": "uri",
      "description": "Canonical URI identifier for this Component Document."
    },
    "name": {
      "type": "string",
      "description": "Machine-friendly short identifier."
    },
    "title": {
      "type": "string",
      "description": "Human-readable name."
    },
    "description": {
      "type": "string",
      "description": "Human-readable description."
    },
    "version": {
      "type": "string",
      "minLength": 1,
      "description": "Version of this Component Document.",
      "examples": ["1.0.0"],
      "x-lm": {
        "critical": true,
        "intent": "Revision identifier for the component tree document."
      }
    },
    "targetDefinition": {
      "$ref": "#/$defs/TargetDefinition",
      "description": "Binding to the target Formspec Definition and optional compatibility range.",
      "examples": [
        { "url": "https://agency.gov/forms/budget", "compatibleVersions": ">=1.0.0 <2.0.0" }
      ],
      "x-lm": {
        "critical": true,
        "intent": "Declares which definition this component tree is designed to render."
      }
    },
    "breakpoints": {
      "$ref": "#/$defs/Breakpoints",
      "description": "Named viewport breakpoints for responsive prop overrides. Keys are breakpoint names; values are minimum viewport widths in pixels. Mobile-first cascade: base props apply to all widths, then overrides merge in ascending order.",
      "examples": [
        { "sm": 576, "md": 768, "lg": 1024 }
      ]
    },
    "tokens": {
      "$ref": "#/$defs/Tokens",
      "description": "Flat key-value map of design tokens. Referenced in style objects and token-able props via $token.key syntax. Tier 3 tokens override Tier 2 theme tokens of the same key.",
      "examples": [
        { "color.primary": "#0057B7", "spacing.md": "16px", "border.radius": "6px" }
      ]
    },
    "components": {
      "type": "object",
      "description": "Registry of custom component templates. Keys are PascalCase names (MUST NOT collide with built-in names). Each template has params and a tree that is instantiated with {param} interpolation.",
      "patternProperties": {
        "^[A-Z][a-zA-Z0-9]*$": {
          "$ref": "#/$defs/CustomComponentDef"
        }
      },
      "additionalProperties": false,
      "examples": [
        {
          "LabeledField": {
            "params": ["field", "label"],
            "tree": {
              "component": "Stack",
              "gap": "$token.spacing.sm",
              "children": [
                { "component": "Heading", "level": 4, "text": "{label}" },
                { "component": "TextInput", "bind": "{field}" }
              ]
            }
          }
        }
      ]
    },
    "tree": {
      "$ref": "#/$defs/AnyComponent",
      "description": "Root component node of the presentation tree. MUST be a single component object (wrap multiple children in Stack or Page).",
      "examples": [
        {
          "component": "Stack",
          "children": [
            { "component": "TextInput", "bind": "name" }
          ]
        }
      ],
      "x-lm": {
        "critical": true,
        "intent": "Entry point for all component layout and binding declarations."
      }
    },
    "extensions": {
      "type": "object",
      "propertyNames": { "pattern": "^x-" },
      "description": "Document-level extension properties. All keys MUST be prefixed with 'x-'."
    }
  },

  "$defs": {
    "TargetDefinition": {
      "type": "object",
      "required": ["url"],
      "additionalProperties": false,
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Canonical URL of the target Definition (its url property)."
        },
        "compatibleVersions": {
          "type": "string",
          "description": "Semver range expression using node/npm-style range syntax describing which Definition versions this document supports. When absent, compatible with any version."
        }
      }
    },

    "Tokens": {
      "type": "object",
      "description": "Flat design token map. Keys are dot-delimited names (e.g. color.primary, spacing.md). Values are strings or numbers. Referenced via $token.key syntax. MUST NOT contain nested objects, arrays, booleans, or null.",
      "additionalProperties": {
        "oneOf": [
          { "type": "string" },
          { "type": "number" }
        ]
      }
    },

    "Breakpoints": {
      "type": "object",
      "description": "Named viewport breakpoints. Keys are breakpoint names; values are minimum viewport widths in pixels (non-negative integers).",
      "additionalProperties": {
        "type": "integer",
        "minimum": 0
      }
    },

    "StyleMap": {
      "type": "object",
      "description": "Flat style map. Values MAY contain $token.path references (e.g. $token.color.primary). Not CSS — renderers map to platform equivalents.",
      "additionalProperties": {
        "oneOf": [
          { "type": "string" },
          { "type": "number" }
        ]
      }
    },

    "AccessibilityBlock": {
      "type": "object",
      "description": "Accessibility overrides applied to the component's root element. Supplements or replaces renderer defaults.",
      "additionalProperties": false,
      "properties": {
        "role": {
          "type": "string",
          "description": "ARIA role override (e.g. 'region', 'group', 'status'). Replaces renderer-default role."
        },
        "description": {
          "type": "string",
          "description": "Accessible description text. Renderers SHOULD wire to aria-describedby."
        },
        "liveRegion": {
          "type": "string",
          "enum": ["off", "polite", "assertive"],
          "description": "Sets aria-live on root element. Renderers MUST NOT apply live-region semantics unless explicitly set."
        }
      }
    },

    "ResponsiveOverrides": {
      "type": "object",
      "description": "Breakpoint-keyed prop overrides. Keys are breakpoint names; values are objects of component-specific props to shallow-merge at that breakpoint. MUST NOT contain component, bind, when, children, or responsive.",
      "additionalProperties": {
        "type": "object"
      }
    },

    "ChildrenArray": {
      "type": "array",
      "description": "Ordered list of child components. Renderers MUST preserve array order.",
      "items": {
        "$ref": "#/$defs/AnyComponent"
      }
    },

    "CustomComponentDef": {
      "type": "object",
      "description": "A reusable component template. Instantiated by using the registry key as the component value and providing params. Templates MUST NOT reference themselves (directly or indirectly).",
      "required": ["tree"],
      "additionalProperties": false,
      "properties": {
        "params": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Parameter names accepted by this template. Each name MUST match [a-zA-Z][a-zA-Z0-9_]*. Referenced in allowed string props via {paramName} interpolation."
        },
        "tree": {
          "$ref": "#/$defs/AnyComponent",
          "description": "Component subtree instantiated when this custom component is used."
        }
      }
    },

    "ComponentBase": {
      "type": "object",
      "description": "Base properties shared by all component objects. Every component inherits these via $ref.",
      "required": ["component"],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-zA-Z][a-zA-Z0-9_\\-]*$",
          "description": "Optional unique identifier for this node within the component tree. Used for locale string addressing ($component.<id>.prop), test selectors, and accessibility anchoring. When present, MUST be unique across the entire component tree document. Inside repeat templates (DataTable, Accordion), the id identifies the template node — all rendered instances share the same id."
        },
        "component": {
          "type": "string",
          "minLength": 1,
          "description": "Component type name. MUST be a built-in name or a key in the components registry."
        },
        "when": {
          "type": "string",
          "description": "FEL boolean expression for conditional rendering. false/null hides the component and all children. Presentation-only — does NOT affect data (unlike Bind relevant which may clear data). When BOTH when and relevant apply: relevant=false always wins; when=false hides but preserves data."
        },
        "responsive": {
          "$ref": "#/$defs/ResponsiveOverrides",
          "description": "Breakpoint-keyed prop overrides for responsive design. Mobile-first cascade."
        },
        "style": {
          "$ref": "#/$defs/StyleMap",
          "description": "Flat style map. Values MAY contain $token.path references."
        },
        "accessibility": {
          "$ref": "#/$defs/AccessibilityBlock",
          "description": "Accessibility overrides for the component's root element."
        },
        "cssClass": {
          "oneOf": [
            { "type": "string" },
            { "type": "array", "items": { "type": "string" } }
          ],
          "description": "CSS class name(s) applied to root element. Additive to renderer-generated classes. Non-web renderers MAY ignore. Values MAY contain $token. references."
        }
      }
    },

    "AnyComponent": {
      "type": "object",
      "required": ["component"],
      "properties": {
        "component": { "type": "string", "minLength": 1 }
      },
      "oneOf": [
        { "$ref": "#/$defs/Page" },
        { "$ref": "#/$defs/Stack" },
        { "$ref": "#/$defs/Grid" },
        { "$ref": "#/$defs/Spacer" },
        { "$ref": "#/$defs/TextInput" },
        { "$ref": "#/$defs/NumberInput" },
        { "$ref": "#/$defs/DatePicker" },
        { "$ref": "#/$defs/Select" },
        { "$ref": "#/$defs/CheckboxGroup" },
        { "$ref": "#/$defs/Toggle" },
        { "$ref": "#/$defs/FileUpload" },
        { "$ref": "#/$defs/Heading" },
        { "$ref": "#/$defs/Text" },
        { "$ref": "#/$defs/Divider" },
        { "$ref": "#/$defs/Card" },
        { "$ref": "#/$defs/Collapsible" },
        { "$ref": "#/$defs/ConditionalGroup" },
        { "$ref": "#/$defs/Columns" },
        { "$ref": "#/$defs/Tabs" },
        { "$ref": "#/$defs/SubmitButton" },
        { "$ref": "#/$defs/Accordion" },
        { "$ref": "#/$defs/RadioGroup" },
        { "$ref": "#/$defs/MoneyInput" },
        { "$ref": "#/$defs/Slider" },
        { "$ref": "#/$defs/Rating" },
        { "$ref": "#/$defs/Signature" },
        { "$ref": "#/$defs/Alert" },
        { "$ref": "#/$defs/Badge" },
        { "$ref": "#/$defs/ProgressBar" },
        { "$ref": "#/$defs/Summary" },
        { "$ref": "#/$defs/ValidationSummary" },
        { "$ref": "#/$defs/DataTable" },
        { "$ref": "#/$defs/Panel" },
        { "$ref": "#/$defs/Modal" },
        { "$ref": "#/$defs/Popover" },
        { "$ref": "#/$defs/CustomComponentRef" }
      ]
    },

    "Page": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Top-level page/section container. In a multi-step form, each Page is one step. Pages MAY also be used standalone within a Stack for sectioned single-page forms.",
      "x-lm": {
        "category": "layout",
        "level": "core",
        "children": true,
        "bind": "forbidden"
      },
      "properties": {
        "component": { "const": "Page" },
        "title": {
          "type": "string",
          "description": "Page heading displayed at the top of the section."
        },
        "description": {
          "type": "string",
          "description": "Subtitle or description text rendered below the title."
        },
        "children": { "$ref": "#/$defs/ChildrenArray" }
      },
      "unevaluatedProperties": false,
      "examples": [
        {
          "component": "Page",
          "title": "Project Information",
          "description": "Enter basic details about your project.",
          "children": [
            { "component": "TextInput", "bind": "projectName" }
          ]
        }
      ]
    },

    "Stack": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Flexbox stacking container arranging children vertically or horizontally. The most common layout primitive — typically used as the root component.",
      "x-lm": {
        "category": "layout",
        "level": "core",
        "children": true,
        "bind": "forbidden"
      },
      "properties": {
        "component": { "const": "Stack" },
        "direction": {
          "type": "string",
          "enum": ["vertical", "horizontal"],
          "default": "vertical",
          "description": "Stack axis."
        },
        "gap": {
          "oneOf": [{ "type": "string" }, { "type": "number" }],
          "description": "Spacing between children. String for CSS values or $token refs, number for pixels."
        },
        "align": {
          "type": "string",
          "enum": ["start", "center", "end", "stretch"],
          "description": "Cross-axis alignment."
        },
        "wrap": {
          "type": "boolean",
          "description": "Whether children wrap to new lines when direction is horizontal."
        },
        "children": { "$ref": "#/$defs/ChildrenArray" }
      },
      "unevaluatedProperties": false,
      "examples": [
        {
          "component": "Stack", "direction": "vertical", "gap": "$token.spacing.md",
          "children": [
            { "component": "TextInput", "bind": "firstName" },
            { "component": "TextInput", "bind": "lastName" }
          ]
        }
      ]
    },

    "Grid": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Multi-column grid layout distributing children across columns in source order, wrapping to new rows as needed.",
      "x-lm": {
        "category": "layout",
        "level": "core",
        "children": true,
        "bind": "forbidden"
      },
      "properties": {
        "component": { "const": "Grid" },
        "columns": {
          "oneOf": [{ "type": "string" }, { "type": "integer", "minimum": 1 }],
          "description": "Column count (integer) or CSS grid-template-columns value (string, e.g. '1fr 2fr 1fr')."
        },
        "gap": {
          "oneOf": [{ "type": "string" }, { "type": "number" }],
          "description": "Spacing between grid cells."
        },
        "rowGap": {
          "oneOf": [{ "type": "string" }, { "type": "number" }],
          "description": "Vertical spacing between rows. Inherits gap if absent."
        },
        "children": { "$ref": "#/$defs/ChildrenArray" }
      },
      "unevaluatedProperties": false,
      "examples": [
        {
          "component": "Grid", "columns": 3, "gap": "$token.spacing.md",
          "children": [
            { "component": "TextInput", "bind": "firstName" },
            { "component": "TextInput", "bind": "middleName" },
            { "component": "TextInput", "bind": "lastName" }
          ]
        }
      ]
    },

    "Spacer": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Empty spacing element inserting visual space between siblings. Leaf component — no children, no binding.",
      "x-lm": {
        "category": "layout",
        "level": "core",
        "children": false,
        "bind": "forbidden"
      },
      "properties": {
        "component": { "const": "Spacer" },
        "size": {
          "oneOf": [{ "type": "string" }, { "type": "number" }],
          "description": "Space amount. String for CSS/$token values, number for pixels."
        }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "Spacer", "size": "$token.spacing.lg" }
      ]
    },

    "TextInput": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Single-line or multi-line text input. Default input for string-type fields. When maxLines > 1, renders as textarea.",
      "required": ["component", "bind"],
      "x-lm": {
        "category": "input",
        "level": "core",
        "children": false,
        "bind": "required",
        "compatibleDataTypes": ["string"]
      },
      "properties": {
        "component": { "const": "TextInput" },
        "bind": {
          "type": "string",
          "description": "Item key from the target Definition. Renderer inherits label, required, readonly, relevant, and validation."
        },
        "placeholder": {
          "type": "string",
          "description": "Placeholder text displayed when the field is empty."
        },
        "maxLines": {
          "type": "integer",
          "minimum": 1,
          "default": 1,
          "description": "Maximum visible lines. 1 = single-line input, >1 = multi-line textarea."
        },
        "inputMode": {
          "type": "string",
          "enum": ["text", "email", "tel", "url", "search"],
          "description": "Input mode hint for virtual keyboards."
        },
        "prefix": {
          "type": "string",
          "description": "Static text rendered before the input (e.g. 'https://')."
        },
        "suffix": {
          "type": "string",
          "description": "Static text rendered after the input (e.g. '.com')."
        },
        "variant": {
          "type": "string",
          "enum": ["plain", "richtext", "markdown", "latex"],
          "default": "plain",
          "description": "Content-type variant. `plain` (default) accepts unstyled text. `richtext` accepts formatted text with runtime-defined serialization. `markdown` accepts Markdown source — portable, diffable, degrades gracefully. `latex` accepts LaTeX source — authoritative for math and scientific documents; degrades to raw source. All formatted variants (`richtext`, `markdown`, `latex`) MUST bind to a field whose `dataType` is `string` or `text`."
        }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "TextInput", "bind": "email", "placeholder": "you@example.com", "inputMode": "email" },
        { "component": "TextInput", "bind": "notes", "variant": "richtext", "maxLines": 8 }
      ]
    },

    "NumberInput": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Numeric input with optional step controls. Suitable for integers, decimals, and monetary values (when paired with prefix/suffix).",
      "required": ["component", "bind"],
      "x-lm": {
        "category": "input",
        "level": "core",
        "children": false,
        "bind": "required",
        "compatibleDataTypes": ["integer", "number"]
      },
      "properties": {
        "component": { "const": "NumberInput" },
        "bind": { "type": "string", "description": "Item key from the target Definition." },
        "placeholder": { "type": "string", "description": "Placeholder text displayed when the field is empty." },
        "step": { "type": "number", "description": "Increment/decrement step value." },
        "min": { "type": "number", "description": "Minimum allowed value." },
        "max": { "type": "number", "description": "Maximum allowed value." },
        "showStepper": { "type": "boolean", "description": "Whether to show increment/decrement buttons." },
        "locale": { "type": "string", "description": "Locale for number formatting (e.g. 'en-US')." }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "NumberInput", "bind": "quantity", "min": 1, "max": 100, "step": 1, "showStepper": true, "placeholder": "0" }
      ]
    },

    "DatePicker": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Date, datetime, or time picker. Mode is automatically determined by the bound item's dataType (date → date picker, dateTime → date+time, time → time picker).",
      "required": ["component", "bind"],
      "x-lm": {
        "category": "input",
        "level": "core",
        "children": false,
        "bind": "required",
        "compatibleDataTypes": ["date", "dateTime", "time"]
      },
      "properties": {
        "component": { "const": "DatePicker" },
        "bind": { "type": "string", "description": "Item key from the target Definition." },
        "placeholder": { "type": "string", "description": "Placeholder text displayed when the field is empty, when the host platform exposes placeholders for date/time controls." },
        "format": { "type": "string", "description": "Display format hint (e.g. 'MM/DD/YYYY'). Does not affect stored value (always ISO 8601)." },
        "minDate": { "type": "string", "description": "Earliest selectable date (ISO 8601)." },
        "maxDate": { "type": "string", "description": "Latest selectable date (ISO 8601)." },
        "showTime": { "type": "boolean", "description": "Whether to include time selection (relevant for dateTime)." }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "DatePicker", "bind": "startDate", "format": "MM/DD/YYYY", "placeholder": "YYYY-MM-DD", "minDate": "2025-01-01" }
      ]
    },

    "Select": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Dropdown selection control. Options are read from the bound item's options array or optionSet reference in the Definition.",
      "required": ["component", "bind"],
      "x-lm": {
        "category": "input",
        "level": "core",
        "children": false,
        "bind": "required",
        "compatibleDataTypes": ["choice", "multiChoice"]
      },
      "properties": {
        "component": { "const": "Select" },
        "bind": { "type": "string", "description": "Item key from the target Definition." },
        "searchable": { "type": "boolean", "description": "Use a combobox (text input + listbox) with optional type-ahead filtering. When false and multiple is false, a native <select> is used." },
        "multiple": { "type": "boolean", "description": "Allow multiple values (array). Bind to a multiChoice field. Implies a combobox list with checkboxes; combine with searchable for filtering." },
        "placeholder": { "type": "string", "description": "Placeholder text when no option is selected." },
        "clearable": { "type": "boolean", "description": "Whether the user can clear the selection to null." }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "Select", "bind": "department", "searchable": true, "placeholder": "Choose a department" },
        { "component": "Select", "bind": "tags", "multiple": true, "searchable": true }
      ]
    },

    "CheckboxGroup": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Group of checkboxes for multi-select fields. Options are read from the bound item's options or optionSet.",
      "required": ["component", "bind"],
      "x-lm": {
        "category": "input",
        "level": "core",
        "children": false,
        "bind": "required",
        "compatibleDataTypes": ["multiChoice"]
      },
      "properties": {
        "component": { "const": "CheckboxGroup" },
        "bind": { "type": "string", "description": "Item key from the target Definition." },
        "columns": { "type": "integer", "minimum": 1, "description": "Number of columns to arrange checkboxes in." },
        "selectAll": { "type": "boolean", "description": "Whether to display a 'Select All' control." }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "CheckboxGroup", "bind": "interests", "columns": 2, "selectAll": true }
      ]
    },

    "Toggle": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Boolean switch/toggle control for yes/no, on/off, or true/false fields.",
      "required": ["component", "bind"],
      "x-lm": {
        "category": "input",
        "level": "core",
        "children": false,
        "bind": "required",
        "compatibleDataTypes": ["boolean"]
      },
      "properties": {
        "component": { "const": "Toggle" },
        "bind": { "type": "string", "description": "Item key from the target Definition." },
        "onLabel": { "type": "string", "description": "Label displayed when toggle is true." },
        "offLabel": { "type": "string", "description": "Label displayed when toggle is false." }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "Toggle", "bind": "agreeToTerms", "onLabel": "I agree", "offLabel": "I do not agree" }
      ]
    },

    "FileUpload": {
      "$ref": "#/$defs/ComponentBase",
      "description": "File upload control for attachment-type fields. Supports single or multiple file selection with optional type and size constraints.",
      "required": ["component", "bind"],
      "x-lm": {
        "category": "input",
        "level": "core",
        "children": false,
        "bind": "required",
        "compatibleDataTypes": ["attachment"]
      },
      "properties": {
        "component": { "const": "FileUpload" },
        "bind": { "type": "string", "description": "Item key from the target Definition." },
        "accept": { "type": "string", "description": "Accepted MIME types (comma-separated, e.g. 'image/*,application/pdf')." },
        "maxSize": { "type": "integer", "description": "Maximum file size in bytes." },
        "multiple": { "type": "boolean", "description": "Whether multiple files may be uploaded." },
        "dragDrop": { "type": "boolean", "description": "Whether to display a drag-and-drop zone." }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "FileUpload", "bind": "supportingDocs", "accept": "application/pdf,image/*", "maxSize": 10485760, "multiple": true }
      ]
    },

    "Heading": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Section heading element for visual hierarchy. Purely presentational — does not bind to data.",
      "required": ["component", "level", "text"],
      "x-lm": {
        "category": "display",
        "level": "core",
        "children": false,
        "bind": "forbidden"
      },
      "properties": {
        "component": { "const": "Heading" },
        "level": {
          "type": "integer",
          "minimum": 1,
          "maximum": 6,
          "description": "Heading level 1–6. Corresponds to HTML <h1>–<h6> semantics."
        },
        "text": {
          "type": "string",
          "description": "Heading text content."
        }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "Heading", "level": 2, "text": "Budget Details" }
      ]
    },

    "Text": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Static or data-bound text block. When bind is present, displays the bound item's current value as read-only. When absent, displays the static text prop.",
      "x-lm": {
        "category": "display",
        "level": "core",
        "children": false,
        "bind": "optional"
      },
      "properties": {
        "component": { "const": "Text" },
        "bind": { "type": "string", "description": "Item key. When present, displays the bound item's formatted value (read-only)." },
        "text": { "type": "string", "description": "Static text content. Ignored when bind is present." },
        "format": {
          "type": "string",
          "enum": ["plain", "markdown"],
          "description": "Text format. 'markdown' enables basic Markdown rendering (bold, italic, links, lists). Renderers MUST sanitize to prevent script injection."
        }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "Text", "text": "Please review before submitting.", "format": "markdown" },
        { "component": "Text", "bind": "totalBudget" }
      ]
    },

    "Divider": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Horizontal rule separating sections of the form.",
      "x-lm": {
        "category": "display",
        "level": "core",
        "children": false,
        "bind": "forbidden"
      },
      "properties": {
        "component": { "const": "Divider" },
        "label": { "type": "string", "description": "Optional label text centered on the divider line." }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "Divider", "label": "Section Break" }
      ]
    },

    "Card": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Bordered surface that visually groups related content with optional header.",
      "x-lm": {
        "category": "container",
        "level": "core",
        "children": true,
        "bind": "forbidden"
      },
      "properties": {
        "component": { "const": "Card" },
        "title": { "type": "string", "description": "Card header title." },
        "subtitle": { "type": "string", "description": "Card header subtitle, rendered below the title." },
        "elevation": { "type": "integer", "minimum": 0, "description": "Shadow depth level." },
        "children": { "$ref": "#/$defs/ChildrenArray" }
      },
      "unevaluatedProperties": false,
      "examples": [
        {
          "component": "Card", "title": "Contact Information",
          "children": [
            { "component": "TextInput", "bind": "email" },
            { "component": "TextInput", "bind": "phone" }
          ]
        }
      ]
    },

    "Collapsible": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Expandable/collapsible section. User toggles child visibility via clickable header. Collapsed children stay in DOM — bound data is preserved.",
      "required": ["component", "title"],
      "x-lm": {
        "category": "container",
        "level": "core",
        "children": true,
        "bind": "forbidden"
      },
      "properties": {
        "component": { "const": "Collapsible" },
        "title": { "type": "string", "description": "Collapsible section header. Visible regardless of open/closed state." },
        "defaultOpen": { "type": "boolean", "description": "Whether the section is initially expanded." },
        "children": { "$ref": "#/$defs/ChildrenArray" }
      },
      "unevaluatedProperties": false,
      "examples": [
        {
          "component": "Collapsible", "title": "Advanced Options", "defaultOpen": false,
          "children": [
            { "component": "Toggle", "bind": "enableNotifications" }
          ]
        }
      ]
    },

    "ConditionalGroup": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Container whose visibility is controlled by a REQUIRED when expression. Exists solely to conditionally show/hide a group of children. Data-bound children retain values when hidden (unlike Bind relevant).",
      "required": ["component", "when"],
      "x-lm": {
        "category": "container",
        "level": "core",
        "children": true,
        "bind": "forbidden"
      },
      "properties": {
        "component": { "const": "ConditionalGroup" },
        "fallback": { "type": "string", "description": "Text displayed when the condition is false." },
        "children": { "$ref": "#/$defs/ChildrenArray" }
      },
      "unevaluatedProperties": false,
      "examples": [
        {
          "component": "ConditionalGroup",
          "when": "$hasEmployer = true",
          "fallback": "Employer details not required for this application type.",
          "children": [
            { "component": "TextInput", "bind": "employerName" }
          ]
        }
      ]
    },

    "Columns": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Explicit multi-column layout with per-child column widths. Unlike Grid which auto-distributes into equal cells, Columns gives precise per-column sizing.",
      "x-lm": {
        "category": "layout",
        "level": "progressive",
        "children": true,
        "bind": "forbidden",
        "fallback": "Grid",
        "fallbackNotes": "columns set to child count; gap preserved."
      },
      "properties": {
        "component": { "const": "Columns" },
        "widths": {
          "type": "array",
          "items": { "oneOf": [{ "type": "string" }, { "type": "number" }] },
          "description": "Per-child column widths as CSS values (e.g. ['1fr', '2fr', '1fr']). Array length SHOULD match child count."
        },
        "gap": {
          "oneOf": [{ "type": "string" }, { "type": "number" }],
          "description": "Spacing between columns."
        },
        "children": { "$ref": "#/$defs/ChildrenArray" }
      },
      "unevaluatedProperties": false,
      "examples": [
        {
          "component": "Columns", "widths": ["2fr", "1fr"], "gap": "$token.spacing.md",
          "children": [
            { "component": "TextInput", "bind": "address" },
            { "component": "TextInput", "bind": "zipCode" }
          ]
        }
      ]
    },

    "Tabs": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Tabbed navigation container. Each child is one tab's content. Tab labels from child Page titles or tabLabels array. All children stay mounted — switching changes visibility, not lifecycle.",
      "x-lm": {
        "category": "layout",
        "level": "progressive",
        "children": true,
        "bind": "forbidden",
        "fallback": "Stack",
        "fallbackNotes": "Each child preceded by a Heading (level 3) with tab label. All children rendered visibly."
      },
      "properties": {
        "component": { "const": "Tabs" },
        "position": {
          "type": "string",
          "enum": ["top", "bottom", "left", "right"],
          "default": "top",
          "description": "Tab bar position."
        },
        "tabLabels": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Explicit tab labels. When absent, reads title from each child Page."
        },
        "defaultTab": {
          "type": "integer",
          "minimum": 0,
          "description": "Zero-based index of the initially active tab."
        },
        "children": { "$ref": "#/$defs/ChildrenArray" }
      },
      "unevaluatedProperties": false,
      "examples": [
        {
          "component": "Tabs", "tabLabels": ["Personal", "Employment"],
          "children": [
            { "component": "Stack", "children": [{ "component": "TextInput", "bind": "firstName" }] },
            { "component": "Stack", "children": [{ "component": "TextInput", "bind": "employer" }] }
          ]
        }
      ]
    },

    "SubmitButton": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Button that triggers renderer submission. Calls the host renderer's submit API and can optionally emit the formspec-submit event.",
      "x-lm": {
        "category": "display",
        "level": "core",
        "children": false,
        "bind": "forbidden"
      },
      "properties": {
        "component": { "const": "SubmitButton" },
        "label": {
          "type": "string",
          "description": "Button label text."
        },
        "mode": {
          "type": "string",
          "enum": ["continuous", "submit"],
          "description": "Validation mode used for response/report generation when clicked."
        },
        "emitEvent": {
          "type": "boolean",
          "description": "Whether clicking the button dispatches the formspec-submit CustomEvent."
        },
        "pendingLabel": {
          "type": "string",
          "description": "Label text shown while shared submit pending state is true."
        },
        "disableWhenPending": {
          "type": "boolean",
          "default": true,
          "description": "Whether the button is disabled while shared submit pending state is true."
        }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "SubmitButton", "label": "Submit Application", "mode": "submit", "emitEvent": true, "pendingLabel": "Submitting…" }
      ]
    },

    "Accordion": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Vertical list of collapsible sections. By default only one expanded at a time. Children SHOULD have title props (Page, Card, Collapsible) for section headers.",
      "x-lm": {
        "category": "layout",
        "level": "progressive",
        "children": true,
        "bind": "optional",
        "fallback": "Stack",
        "fallbackNotes": "Each child wrapped in Collapsible. First defaults open; rest closed."
      },
      "properties": {
        "component": { "const": "Accordion" },
        "bind": {
          "type": "string",
          "description": "Optional bind path to a repeating group. When provided, each instance becomes one accordion section."
        },
        "allowMultiple": {
          "type": "boolean",
          "description": "Whether multiple sections may be expanded simultaneously. When false, expanding one collapses others."
        },
        "defaultOpen": {
          "type": "integer",
          "minimum": 0,
          "description": "Zero-based index of the initially expanded section."
        },
        "labels": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Section header labels. labels[i] is the summary text for children[i]. Falls back to 'Section {i+1}' when absent."
        },
        "children": { "$ref": "#/$defs/ChildrenArray" }
      },
      "unevaluatedProperties": false,
      "examples": [
        {
          "component": "Accordion", "allowMultiple": false,
          "children": [
            { "component": "Page", "title": "Section A", "children": [{ "component": "TextInput", "bind": "fieldA" }] },
            { "component": "Page", "title": "Section B", "children": [{ "component": "TextInput", "bind": "fieldB" }] }
          ]
        }
      ]
    },

    "RadioGroup": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Radio buttons for single-select choice fields. All options visible simultaneously — suitable for short lists (typically ≤7 items).",
      "required": ["component", "bind"],
      "x-lm": {
        "category": "input",
        "level": "progressive",
        "children": false,
        "bind": "required",
        "compatibleDataTypes": ["choice"],
        "fallback": "Select",
        "fallbackNotes": "columns discarded."
      },
      "properties": {
        "component": { "const": "RadioGroup" },
        "bind": { "type": "string", "description": "Item key from the target Definition." },
        "columns": { "type": "integer", "minimum": 1, "description": "Number of columns to arrange radio buttons in." },
        "orientation": {
          "type": "string",
          "enum": ["horizontal", "vertical"],
          "description": "Layout direction of the radio buttons."
        }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "RadioGroup", "bind": "priority", "columns": 3, "orientation": "horizontal" }
      ]
    },

    "MoneyInput": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Currency-aware numeric input displaying currency symbol and formatted number. Stores raw numeric value without formatting.",
      "required": ["component", "bind"],
      "x-lm": {
        "category": "input",
        "level": "progressive",
        "children": false,
        "bind": "required",
        "compatibleDataTypes": ["money"],
        "fallback": "NumberInput",
        "fallbackNotes": "Currency symbol rendered as prefix if bound item has prefix hint."
      },
      "properties": {
        "component": { "const": "MoneyInput" },
        "bind": { "type": "string", "description": "Item key from the target Definition." },
        "placeholder": { "type": "string", "description": "Placeholder text displayed in the amount input when the field is empty." },
        "step": { "type": "number", "description": "Increment/decrement step value (applies to amount)." },
        "min": { "type": "number", "description": "Minimum allowed amount." },
        "max": { "type": "number", "description": "Maximum allowed amount." },
        "showStepper": { "type": "boolean", "description": "Whether to show increment/decrement buttons (amount input)." },
        "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code (e.g. 'USD', 'EUR', 'GBP')." },
        "showCurrency": { "type": "boolean", "description": "Whether to display the currency symbol." },
        "locale": { "type": "string", "description": "Locale for number/currency formatting (e.g. 'en-US')." }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "MoneyInput", "bind": "totalBudget", "currency": "USD", "showCurrency": true, "placeholder": "0.00", "min": 0, "step": 0.01 }
      ]
    },

    "Slider": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Range slider for selecting a numeric value within a continuous range.",
      "required": ["component", "bind"],
      "x-lm": {
        "category": "input",
        "level": "progressive",
        "children": false,
        "bind": "required",
        "compatibleDataTypes": ["integer", "number"],
        "fallback": "NumberInput",
        "fallbackNotes": "min, max, step preserved."
      },
      "properties": {
        "component": { "const": "Slider" },
        "bind": { "type": "string", "description": "Item key from the target Definition." },
        "min": { "type": "number", "description": "Minimum value." },
        "max": { "type": "number", "description": "Maximum value." },
        "step": { "type": "number", "description": "Step increment." },
        "showValue": { "type": "boolean", "description": "Whether to display the current numeric value adjacent to the slider." },
        "showTicks": { "type": "boolean", "description": "Whether to display tick marks at step intervals." }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "Slider", "bind": "satisfaction", "min": 1, "max": 10, "step": 1, "showValue": true }
      ]
    },

    "Rating": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Star (or icon) rating control for selecting an integer value within a small range (typically 1–5 or 1–10).",
      "required": ["component", "bind"],
      "x-lm": {
        "category": "input",
        "level": "progressive",
        "children": false,
        "bind": "required",
        "compatibleDataTypes": ["integer"],
        "fallback": "NumberInput",
        "fallbackNotes": "min: 1, max preserved, step: 1."
      },
      "properties": {
        "component": { "const": "Rating" },
        "bind": { "type": "string", "description": "Item key from the target Definition." },
        "max": { "type": "integer", "minimum": 1, "description": "Maximum rating value (number of icons)." },
        "icon": {
          "type": "string",
          "enum": ["star", "heart", "circle"],
          "description": "Icon type. Renderers MAY support additional icons."
        },
        "allowHalf": { "type": "boolean", "description": "Whether half-values are allowed (stored as decimal, e.g. 3.5)." }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "Rating", "bind": "serviceRating", "max": 5, "icon": "star" }
      ]
    },

    "Signature": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Signature capture pad recording a drawn signature as an image attachment.",
      "required": ["component", "bind"],
      "x-lm": {
        "category": "input",
        "level": "progressive",
        "children": false,
        "bind": "required",
        "compatibleDataTypes": ["attachment"],
        "fallback": "FileUpload",
        "fallbackNotes": "accept set to 'image/*'."
      },
      "properties": {
        "component": { "const": "Signature" },
        "bind": { "type": "string", "description": "Item key from the target Definition." },
        "strokeColor": { "type": "string", "description": "Stroke color for the signature pen (e.g. '#000000')." },
        "height": {
          "oneOf": [{ "type": "string" }, { "type": "number" }],
          "description": "Height of the signature pad. Number for pixels, string for CSS value."
        },
        "penWidth": { "type": "number", "description": "Stroke width in pixels." },
        "clearable": { "type": "boolean", "description": "Whether to show a clear/reset control." }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "Signature", "bind": "approverSignature", "strokeColor": "#000", "height": 200 }
      ]
    },

    "Alert": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Status message block for informational banners, warnings, error summaries, or success messages.",
      "required": ["component", "severity", "text"],
      "x-lm": {
        "category": "display",
        "level": "progressive",
        "children": false,
        "bind": "forbidden",
        "fallback": "Text",
        "fallbackNotes": "Text prefixed with severity in brackets (e.g. '[Warning] ...')."
      },
      "properties": {
        "component": { "const": "Alert" },
        "severity": {
          "type": "string",
          "enum": ["info", "success", "warning", "error"],
          "description": "Alert severity. Determines visual styling and ARIA role (alert for error/warning, status for info/success)."
        },
        "text": { "type": "string", "description": "Alert message text." },
        "dismissible": { "type": "boolean", "description": "Whether the user can dismiss the alert." }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "Alert", "severity": "warning", "text": "Budget exceeds department limit. Approval required." }
      ]
    },

    "Badge": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Small label badge for status indicators, counts, or tags.",
      "required": ["component", "text"],
      "x-lm": {
        "category": "display",
        "level": "progressive",
        "children": false,
        "bind": "forbidden",
        "fallback": "Text",
        "fallbackNotes": "Same text prop."
      },
      "properties": {
        "component": { "const": "Badge" },
        "text": { "type": "string", "description": "Badge label text." },
        "variant": {
          "type": "string",
          "enum": ["default", "primary", "success", "warning", "error"],
          "description": "Visual variant controlling color/style."
        }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "Badge", "text": "Draft", "variant": "warning" }
      ]
    },

    "ProgressBar": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Visual progress indicator. When bound, reads value from data. When unbound, uses static value prop.",
      "x-lm": {
        "category": "display",
        "level": "progressive",
        "children": false,
        "bind": "optional",
        "fallback": "Text",
        "fallbackNotes": "Shows '<value> / <max> (<percent>%)'."
      },
      "properties": {
        "component": { "const": "ProgressBar" },
        "bind": { "type": "string", "description": "Item key. When present, reads current value from data." },
        "value": { "type": "number", "description": "Current progress value. Ignored when bind is present." },
        "max": { "type": "number", "description": "Maximum value (100% completion)." },
        "label": { "type": "string", "description": "Accessible label for the progress bar." },
        "showPercent": { "type": "boolean", "description": "Whether to display percentage text." }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "ProgressBar", "bind": "completionScore", "max": 100, "label": "Form completion" }
      ]
    },

    "Summary": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Key-value summary display showing multiple field labels and current values. Useful for review pages.",
      "x-lm": {
        "category": "display",
        "level": "progressive",
        "children": false,
        "bind": "forbidden",
        "fallback": "Stack",
        "fallbackNotes": "One Text per item showing '<label>: <value>'."
      },
      "properties": {
        "component": { "const": "Summary" },
        "items": {
          "type": "array",
          "description": "Array of summary entries. Each has a display label, a bind key for the value, and optional optionSet for resolving choice values to labels.",
          "items": {
            "type": "object",
            "required": ["label", "bind"],
            "additionalProperties": false,
            "properties": {
              "label": { "type": "string", "description": "Display label shown next to the value." },
              "bind": { "type": "string", "description": "Item key whose current value to display." },
              "optionSet": {
                "type": "string",
                "description": "Named option set from the Definition. When set, the raw bound value is resolved to its display label."
              }
            }
          }
        }
      },
      "unevaluatedProperties": false,
      "examples": [
        {
          "component": "Summary",
          "items": [
            { "label": "Project Name", "bind": "projectName" },
            { "label": "Organization Type", "bind": "orgType", "optionSet": "orgTypes" }
          ]
        }
      ]
    },

    "ValidationSummary": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Validation message panel for live validation or the latest submit result. Can render jump links to focus affected fields.",
      "x-lm": {
        "category": "display",
        "level": "progressive",
        "children": false,
        "bind": "forbidden",
        "fallback": "Alert",
        "fallbackNotes": "severity + message rows shown as warning/error alerts."
      },
      "properties": {
        "component": { "const": "ValidationSummary" },
        "source": {
          "type": "string",
          "enum": ["live", "submit"],
          "default": "live",
          "description": "Validation source. 'live' reads continuous engine state; 'submit' reads the latest formspec-submit event detail."
        },
        "mode": {
          "type": "string",
          "enum": ["continuous", "submit"],
          "default": "continuous",
          "description": "Validation mode used when source is 'live'."
        },
        "showFieldErrors": {
          "type": "boolean",
          "default": false,
          "description": "Whether to include bind-level field errors in addition to shape-level findings."
        },
        "jumpLinks": {
          "type": "boolean",
          "default": false,
          "description": "Whether to render clickable links/buttons that call focusField(path) for jumpable targets."
        },
        "dedupe": {
          "type": "boolean",
          "default": true,
          "description": "Whether duplicate messages (same severity/path/message) are collapsed."
        }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "ValidationSummary", "source": "submit", "jumpLinks": true, "showFieldErrors": true }
      ]
    },

    "DataTable": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Tabular display of repeatable group data. Each repeat instance becomes a row; each column displays a field within the repeat. One of the few components that MAY bind to a repeatable group.",
      "x-lm": {
        "category": "display",
        "level": "progressive",
        "children": false,
        "bind": "optional",
        "bindNote": "Binds to a repeatable group key, not a field key.",
        "fallback": "Stack",
        "fallbackNotes": "One Card per repeat instance with child inputs."
      },
      "properties": {
        "component": { "const": "DataTable" },
        "bind": { "type": "string", "description": "Repeatable group item key. Each repeat instance becomes a table row." },
        "columns": {
          "type": "array",
          "description": "Column definitions. Each specifies a header label and a field key within the repeat group.",
          "items": {
            "type": "object",
            "required": ["header", "bind"],
            "additionalProperties": false,
            "properties": {
              "header": { "type": "string", "description": "Column header text." },
              "bind": { "type": "string", "description": "Item key within the repeat group." },
              "min": { "type": "number", "description": "Optional minimum value for numeric inputs." },
              "max": { "type": "number", "description": "Optional maximum value for numeric inputs." },
              "step": { "type": "number", "description": "Optional step for numeric inputs." }
            }
          }
        },
        "showRowNumbers": { "type": "boolean", "description": "Whether to display row numbers." },
        "allowAdd": { "type": "boolean", "description": "Whether to show an 'Add row' control." },
        "allowRemove": { "type": "boolean", "description": "Whether to show per-row 'Remove' controls." }
      },
      "unevaluatedProperties": false,
      "examples": [
        {
          "component": "DataTable", "bind": "lineItems",
          "columns": [
            { "header": "Description", "bind": "description" },
            { "header": "Amount", "bind": "amount" }
          ]
        }
      ]
    },

    "Panel": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Side panel for supplementary content, help text, or contextual actions. Positioned alongside the main content.",
      "x-lm": {
        "category": "container",
        "level": "progressive",
        "children": true,
        "bind": "forbidden",
        "fallback": "Card",
        "fallbackNotes": "title preserved; position and width discarded."
      },
      "properties": {
        "component": { "const": "Panel" },
        "position": {
          "type": "string",
          "enum": ["left", "right"],
          "default": "left",
          "description": "Panel position relative to main content."
        },
        "title": { "type": "string", "description": "Panel header title." },
        "width": {
          "oneOf": [{ "type": "string" }, { "type": "number" }],
          "description": "Panel width. String for CSS value, number for pixels."
        },
        "children": { "$ref": "#/$defs/ChildrenArray" }
      },
      "unevaluatedProperties": false,
      "examples": [
        {
          "component": "Panel", "position": "left", "title": "Help", "width": "280px",
          "children": [{ "component": "Text", "text": "Need help? Contact support." }]
        }
      ]
    },

    "Modal": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Dialog overlay displaying content above the main form. Requires explicit user action to open/close. Traps focus while open.",
      "required": ["component", "title"],
      "x-lm": {
        "category": "container",
        "level": "progressive",
        "children": true,
        "bind": "forbidden",
        "fallback": "Collapsible",
        "fallbackNotes": "title preserved; defaultOpen: false."
      },
      "properties": {
        "component": { "const": "Modal" },
        "title": { "type": "string", "description": "Modal dialog title." },
        "size": {
          "type": "string",
          "enum": ["sm", "md", "lg", "xl", "full"],
          "description": "Modal size."
        },
        "trigger": {
          "type": "string",
          "enum": ["button", "auto"],
          "description": "'button': dedicated open button. 'auto': opens automatically based on when."
        },
        "triggerLabel": { "type": "string", "description": "Label for the trigger button when trigger is 'button'." },
        "closable": { "type": "boolean", "description": "Whether the modal can be dismissed by the user." },
        "headingLevel": {
          "type": "integer",
          "minimum": 1,
          "maximum": 6,
          "description": "Heading level for the modal title (default 2)."
        },
        "placement": {
          "type": "string",
          "enum": ["top", "right", "bottom", "left"],
          "description": "When set, anchors the opened dialog near the trigger with fixed positioning; omit for native centered modal."
        },
        "children": { "$ref": "#/$defs/ChildrenArray" }
      },
      "unevaluatedProperties": false,
      "examples": [
        {
          "component": "Modal", "title": "Terms and Conditions", "trigger": "button", "triggerLabel": "View Terms",
          "children": [{ "component": "Text", "text": "By submitting, you agree to...", "format": "markdown" }]
        }
      ]
    },

    "Popover": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Lightweight anchored overlay showing contextual content when trigger is activated.",
      "x-lm": {
        "category": "container",
        "level": "progressive",
        "children": true,
        "bind": "forbidden",
        "fallback": "Collapsible",
        "fallbackNotes": "triggerLabel mapped to title; placement discarded."
      },
      "properties": {
        "component": { "const": "Popover" },
        "triggerBind": {
          "type": "string",
          "description": "Bind key whose live value is used as trigger text."
        },
        "triggerLabel": {
          "type": "string",
          "description": "Fallback label for the trigger control."
        },
        "placement": {
          "type": "string",
          "enum": ["top", "right", "bottom", "left"],
          "default": "bottom",
          "description": "Preferred popover placement relative to the trigger."
        },
        "children": { "$ref": "#/$defs/ChildrenArray" }
      },
      "unevaluatedProperties": false,
      "examples": [
        {
          "component": "Popover", "triggerLabel": "Show details", "placement": "right",
          "children": [{ "component": "Text", "text": "Additional context." }]
        }
      ]
    },

    "CustomComponentRef": {
      "$ref": "#/$defs/ComponentBase",
      "description": "Reference to a custom component defined in the components registry. The component name is looked up in the registry, params are interpolated into the template, and the resolved subtree replaces this reference.",
      "x-lm": {
        "category": "custom",
        "level": "core"
      },
      "properties": {
        "component": {
          "type": "string",
          "not": {
            "enum": [
              "Page", "Stack", "Grid", "Spacer",
              "TextInput", "NumberInput", "DatePicker", "Select", "CheckboxGroup", "Toggle", "FileUpload",
              "Heading", "Text", "Divider",
              "Card", "Collapsible", "ConditionalGroup",
              "Columns", "Tabs", "SubmitButton", "Accordion",
              "RadioGroup", "MoneyInput", "Slider", "Rating", "Signature",
              "Alert", "Badge", "ProgressBar", "Summary", "ValidationSummary", "DataTable",
              "Panel", "Modal", "Popover"
            ]
          },
          "description": "Custom component name. MUST be a key in the components registry. MUST NOT be a built-in component name."
        },
        "params": {
          "type": "object",
          "additionalProperties": { "type": "string" },
          "description": "Parameter values to interpolate into the template. Keys MUST match the template's declared params. Values MUST be strings."
        }
      },
      "unevaluatedProperties": false,
      "examples": [
        { "component": "AddressBlock", "params": { "prefix": "home", "title": "Home Address" } }
      ]
    }
  }
}