Builder Controls Technical Specification

Technical schema specifications for all 11 field controls supported in the Deal Wizard Builder.

---

Field Schema Data Structures

Each field in a StepSchema adheres to the FieldSchema discriminated union:

export interface FieldSchemaBase {
  id: string;          // UUID v4
  label: string;       // UI display label
  order: number;       // Display sequence within step (0-indexed)
  required: boolean;   // Form validation flag
  helpText?: string;   // Contextual helper text
  defaultValue?: string;
  isDynamic?: boolean;
}

---

Control Configuration Bags

Control Type	Discriminated Config Type	Key Parameters
text	TextConfig	placeholder: string, minLength: number, maxLength: number
textarea	TextAreaConfig	placeholder: string, minLength: number, maxLength: number, rows: number
url	UrlConfig	placeholder: string
file	FileConfig	acceptedFormats: string, maxFileSize: number (MB), maxFiles: number, buttonLabel: string
image	ImageConfig	acceptedFormats: string, maxFileSize: number (MB), enableCamera: boolean, buttonLabel: string
date	DateConfig	format: string (default DD/MM/YYYY)
toggle	ToggleConfig	defaultChecked: boolean
dropdown	DropdownConfig	options: FieldOption[], placeholder: string, allowMultiple: boolean
checkbox	CheckboxGroupConfig	options: FieldOption[], allowMultiple: boolean
radio	RadioGroupConfig	options: FieldOption[]
button	ButtonConfig	action: string, style: string, buttonLabel: string

---

Step and Wizard Schemas

StepSchema (Canvas Steps)

export interface StepSchema {
  id: string;              // UUID
  title: string;           // Step title displayed on tab
  order: number;           // 0-indexed sequence
  isFixed: boolean;        // Whether step is permanently locked
  isVisible: boolean;      // Visibility flag
  checkpointId?: string;   // Deal Checkpoint ID mapped from Org Settings
  checkpointName?: string; // Human-readable checkpoint milestone label
  fields: FieldSchema[];   // Form fields belonging to this step
}

WizardSchema (Root Template Document)

export interface WizardSchema {
  id: string;                      // Template UUID
  name: string;                    // Template title
  description?: string;            // Operational notes
  isActive: boolean;               // Live execution flag
  itemCategoryId?: string;         // Assigned category ID
  itemCategoryName?: string;       // Assigned category label
  itemCategorySlug?: string;       // Taxonomy slug
  itemCategoryConditionId?: string;// Condition filter: All (-1), New (0), Used (1)
  shopId?: string;                 // Branch assignment: 'GLOBAL' or specific shop ID
  shopName?: string;               // Assigned branch display name
  steps: StepSchema[];             // Ordered sequence of custom steps
}