Section Definitions

Section definitions are the component library — reusable types that templates reference.

Creating a Definition

POST /api/v1/admin/sdui/section-definitions
{
  "type": "HeroSection",
  "name": "Hero Section",
  "description": "Full-width hero banner with CTA buttons",
  "category": "layout",
  "platforms": "ALL",
  "maxBlocks": 3,
  "settings": [
    {
      "id": "title",
      "type": "TEXT",
      "label": "Title",
      "defaultValue": "Welcome"
    },
    {
      "id": "bgColor",
      "type": "COLOR",
      "label": "Background Color",
      "defaultValue": "#FFFFFF"
    },
    {
      "id": "bgImage",
      "type": "IMAGE",
      "label": "Background Image"
    }
  ],
  "blocks": [
    {
      "type": "Button",
      "name": "CTA Button",
      "limit": 2,
      "settings": [
        {
          "id": "label",
          "type": "TEXT",
          "label": "Label",
          "defaultValue": "Click Me"
        },
        {
          "id": "variant",
          "type": "SELECT",
          "label": "Style",
          "defaultValue": "primary",
          "options": [
            { "value": "primary", "label": "Primary" },
            { "value": "secondary", "label": "Secondary" }
          ]
        }
      ]
    }
  ]
}

Setting Types

Type	Description	Example
TEXT	Single-line text	Title, label
TEXTAREA	Multi-line text	Description
RICHTEXT	HTML content	Body text
NUMBER	Integer/decimal	Column count
RANGE	Slider	Opacity
CHECKBOX	Boolean toggle	Show/hide
SELECT	Dropdown	Style variant
COLOR	Color picker	#1a1a2e
IMAGE	Image URL	Banner image
VIDEO	Video URL	Background video
URL	Link URL	CTA link
HTML	Raw HTML	Embed code

Setting Constraints

Settings can have constraints depending on their type:

Field	Applicable Types	Description
defaultValue	All	Default when template doesn't override
placeholder	TEXT, TEXTAREA, URL	Placeholder text
info	All	Help tooltip in admin UI
min / max	NUMBER, RANGE	Numeric bounds
step	NUMBER, RANGE	Increment step
unit	NUMBER, RANGE	Display unit (px, %, em)
options	SELECT	Dropdown options: [{ value, label, group }]

Block Schemas

Blocks are child components within a section. Each block schema defines:

{
  "type": "Button",
  "name": "CTA Button",
  "limit": 2,
  "settings": [
    { "id": "label", "type": "TEXT", "defaultValue": "Click Me" },
    { "id": "url", "type": "URL" },
    { "id": "variant", "type": "SELECT", "options": [
      { "value": "primary", "label": "Primary" },
      { "value": "secondary", "label": "Secondary" }
    ]}
  ]
}

• limit: max number of this block type in one section (0 = unlimited)
• Each block type has its own settings with defaults
• Block settings are merged the same way as section settings

Presets

Presets are pre-configured section templates for quick creation in the admin UI:

{
  "presets": [
    {
      "name": "Hero with CTA",
      "settings": { "title": "Welcome", "bgColor": "#1a1a2e" },
      "blocks": [
        { "type": "Button", "settings": { "label": "Explore", "variant": "primary" } }
      ]
    },
    {
      "name": "Hero minimal",
      "settings": { "title": "Welcome" },
      "blocks": []
    }
  ]
}

When an admin selects a preset, the section is pre-filled with those settings and blocks. They can then customize further.

Definition Status

Status	Meaning
ACTIVE	Available for use in templates. Rendered at runtime.
DRAFT	Work in progress. Not available in template editor dropdown.
DEPRECATED	Still renders in existing templates, but hidden from new template creation.

Full Field Reference

SectionDef

Field	Type	Required	Description
type	string	Yes	Unique identifier (e.g., HeroSection)
name	string	Yes	Display name
description	string	No	Human-readable description
category	string	No	Grouping in admin UI (e.g., layout, content)
icon	string	No	Icon identifier or URL
platforms	string	No	ALL, WEB, MOBILE, TABLET (default: ALL)
tag	string	No	Metadata tag
maxBlocks	int	No	Max child blocks (0 = unlimited)
settings	SettingDefinition[]	No	Configurable settings with defaults
blocks	BlockSchema[]	No	Allowed child block types
presets	Preset[]	No	Pre-configured templates
status	string	No	ACTIVE, DRAFT, DEPRECATED (default: ACTIVE)