UI Components

UI components define how data is displayed and collected in your client-facing scripts. CANScript provides a rich library of pre-built components and supports custom component configurations.

Component Structure

interface UINode {
  id: string
  type: "input" | "select" | "display" | "container" | "composite" | "multi_select" | "search" | "dynamic"
  dataOperation?: DataOperation
  uiConfig: UIConfig
  validation?: ValidationRule[]
  conditional?: ConditionalLogic
  children?: UINode[]
}

interface UIConfig {
  component: string
  props: Record<string, any>
}

Core Component Types

1. Input Components

Text Input

{
  "id": "customer_name",
  "type": "input",
  "dataOperation": {
    "type": "update",
    "target": "customer_name"
  },
  "uiConfig": {
    "component": "text_input",
    "props": {
      "label": "Full Name",
      "placeholder": "Enter your full name",
      "required": true,
      "maxLength": 100,
      "helpText": "Name as it appears on your order",
      "icon": "user"
    }
  }
}

Email Input

{
  "id": "email_field",
  "type": "input",
  "uiConfig": {
    "component": "email_input",
    "props": {
      "label": "Email Address",
      "placeholder": "you@example.com",
      "required": true,
      "autocomplete": "email",
      "validateOnBlur": true
    }
  }
}

Phone Input

{
  "id": "phone_field",
  "type": "input",
  "uiConfig": {
    "component": "phone_input",
    "props": {
      "label": "Phone Number",
      "placeholder": "(555) 123-4567",
      "countryCode": "US",
      "formatAsYouType": true,
      "required": false
    }
  }
}

Textarea

{
  "id": "notes_field",
  "type": "input",
  "uiConfig": {
    "component": "textarea",
    "props": {
      "label": "Additional Notes",
      "placeholder": "Any additional information...",
      "rows": 4,
      "maxLength": 1000,
      "showCharacterCount": true,
      "resizable": true
    }
  }
}

Number Input

{
  "id": "quantity_field",
  "type": "input",
  "uiConfig": {
    "component": "number_input",
    "props": {
      "label": "Quantity",
      "min": 1,
      "max": 10,
      "step": 1,
      "required": true,
      "showButtons": true
    }
  }
}

Date Input

{
  "id": "preferred_date",
  "type": "input",
  "uiConfig": {
    "component": "date_input",
    "props": {
      "label": "Preferred Return Date",
      "minDate": "today",
      "maxDate": "+30days",
      "format": "MM/DD/YYYY",
      "showCalendar": true
    }
  }
}

2. Selection Components

{
  "id": "return_reason",
  "type": "select",
  "uiConfig": {
    "component": "dropdown_select",
    "props": {
      "label": "Reason for Return",
      "options": [
        {"value": "defect", "label": "Product Defect"},
        {"value": "sizing", "label": "Wrong Size"},
        {"value": "description", "label": "Not as Described"},
        {"value": "other", "label": "Other"}
      ],
      "placeholder": "Select a reason",
      "searchable": true,
      "required": true
    }
  }
}

Radio Button Group

{
  "id": "refund_method",
  "type": "select",
  "uiConfig": {
    "component": "radio_group",
    "props": {
      "label": "Refund Method",
      "options": "instanceData.refund_methods",
      "displayField": "label",
      "valueField": "value",
      "imageField": "image",
      "layout": "horizontal",
      "required": true
    }
  }
}

Checkbox Group

{
  "id": "notification_preferences",
  "type": "multi_select",
  "uiConfig": {
    "component": "checkbox_group",
    "props": {
      "label": "Notification Preferences",
      "options": [
        {"value": "email", "label": "Email Updates"},
        {"value": "sms", "label": "SMS Notifications"},
        {"value": "push", "label": "Push Notifications"}
      ],
      "layout": "vertical",
      "allowSelectAll": true
    }
  }
}

Single Checkbox

{
  "id": "terms_agreement",
  "type": "input",
  "uiConfig": {
    "component": "checkbox",
    "props": {
      "label": "I agree to the return policy",
      "required": true,
      "linkText": "View full policy",
      "linkUrl": "/return-policy",
      "linkTarget": "_blank"
    }
  }
}

3. Display Components

Info Card

{
  "id": "welcome_message",
  "type": "display",
  "uiConfig": {
    "component": "info_card",
    "props": {
      "type": "info",
      "title": "Welcome Back!",
      "message": "We found your order and are ready to help with your return.",
      "icon": "check-circle",
      "dismissible": false
    }
  }
}

Alert

{
  "id": "warning_message",
  "type": "display",
  "uiConfig": {
    "component": "alert",
    "props": {
      "type": "warning",
      "title": "Return Window Ending Soon",
      "message": "You have 5 days left to return items from this order.",
      "showIcon": true,
      "dismissible": true
    }
  }
}

Progress Bar

{
  "id": "progress_indicator",
  "type": "display",
  "uiConfig": {
    "component": "progress_bar",
    "props": {
      "value": 60,
      "max": 100,
      "label": "Return Progress",
      "showPercentage": true,
      "color": "primary"
    }
  }
}

4. Composite Components

Product Multi-Select

{
  "id": "item_selector",
  "type": "multi_select",
  "uiConfig": {
    "component": "product_multi_select",
    "props": {
      "label": "Select Items to Return",
      "dataSource": "line_items",
      "displayFields": ["title", "variant_title", "price"],
      "imageField": "image",
      "required": true,
      "minSelections": 1,
      "maxSelections": 10,
      "showQuantitySelector": true,
      "allowPartialQuantity": true
    }
  }
}

Address Form

{
  "id": "shipping_address",
  "type": "composite",
  "uiConfig": {
    "component": "address_form",
    "props": {
      "label": "Return Shipping Address",
      "fields": {
        "firstName": {"required": true, "placeholder": "First Name"},
        "lastName": {"required": true, "placeholder": "Last Name"},
        "street1": {"required": true, "placeholder": "Street Address"},
        "street2": {"required": false, "placeholder": "Apt, Suite, etc."},
        "city": {"required": true, "placeholder": "City"},
        "state": {"required": true, "type": "select"},
        "postalCode": {"required": true, "placeholder": "ZIP Code"},
        "country": {"required": true, "type": "select", "default": "US"}
      },
      "allowInternational": false,
      "validateAddress": true,
      "suggestCorrections": true
    }
  }
}

Product Search

{
  "id": "product_search",
  "type": "search",
  "uiConfig": {
    "component": "product_search",
    "props": {
      "label": "Search for Products",
      "placeholder": "Search by name, SKU, or category",
      "dataSource": "products",
      "searchFields": ["title", "sku", "tags"],
      "displayFields": ["title", "price", "availability"],
      "imageField": "featured_image",
      "resultsPerPage": 20,
      "showFilters": true,
      "filters": [
        {"field": "product_type", "label": "Category"},
        {"field": "price", "label": "Price Range", "type": "range"}
      ]
    }
  }
}

File Upload

{
  "id": "photo_upload",
  "type": "input",
  "uiConfig": {
    "component": "file_upload",
    "props": {
      "label": "Upload Photos",
      "accept": "image/*",
      "multiple": true,
      "maxFiles": 5,
      "maxFileSize": "5MB",
      "showPreview": true,
      "uploadUrl": "/upload",
      "required": false,
      "helpText": "Photos help us process your return faster"
    }
  }
}

5. Container Components

Card Container

{
  "id": "summary_card",
  "type": "container",
  "uiConfig": {
    "component": "card",
    "props": {
      "title": "Return Summary",
      "subtitle": "Review your return details",
      "padding": "large",
      "shadow": true,
      "border": true
    }
  },
  "children": [
    {
      "id": "summary_content",
      "type": "display",
      "uiConfig": {
        "component": "summary_list"
      }
    }
  ]
}

Column Layout

{
  "id": "two_column_layout",
  "type": "container",
  "uiConfig": {
    "component": "columns",
    "props": {
      "columns": 2,
      "gap": "medium",
      "responsive": true
    }
  },
  "children": [
    {
      "id": "left_column",
      "type": "container",
      "uiConfig": {
        "component": "column",
        "props": {"width": "60%"}
      }
    },
    {
      "id": "right_column", 
      "type": "container",
      "uiConfig": {
        "component": "column",
        "props": {"width": "40%"}
      }
    }
  ]
}

Tabs Container

{
  "id": "return_options_tabs",
  "type": "container",
  "uiConfig": {
    "component": "tabs",
    "props": {
      "defaultTab": "refund",
      "tabs": [
        {"id": "refund", "label": "Refund", "icon": "dollar-sign"},
        {"id": "exchange", "label": "Exchange", "icon": "refresh-cw"},
        {"id": "store_credit", "label": "Store Credit", "icon": "gift"}
      ]
    }
  },
  "children": [
    {
      "id": "refund_tab_content",
      "conditional": {
        "showIf": {
          "field": "activeTab",
          "operator": "equals", 
          "value": "refund"
        }
      }
    }
  ]
}

Custom Components

Defining Custom Components

{
  "custom_ui_components_config": {
    "return_summary_card": {
      "type": "display",
      "template": "custom_return_summary",
      "props": {
        "showTotals": true,
        "allowEditing": false,
        "theme": "minimal"
      },
      "styling": {
        "backgroundColor": "#f8f9fa",
        "border": "1px solid #dee2e6",
        "borderRadius": "8px",
        "padding": "1.5rem"
      }
    },
    "interactive_product_card": {
      "type": "composite",
      "template": "product_interaction_card",
      "props": {
        "showAddToCart": true,
        "showWishlist": true,
        "showQuickView": true,
        "enableZoom": true
      },
      "events": {
        "onAddToCart": "handleAddToCart",
        "onWishlist": "handleWishlist"
      }
    }
  }
}

Using Custom Components

{
  "id": "custom_summary",
  "type": "display",
  "uiConfig": {
    "component": "return_summary_card",
    "props": {
      "data": "instanceData.return_details",
      "showEditButton": true
    }
  }
}

Component Props Reference

Common Props

All components support these basic properties:

{
  "label": "Field Label",
  "required": true,
  "disabled": false,
  "hidden": false,
  "placeholder": "Placeholder text",
  "helpText": "Additional help information",
  "className": "custom-css-class",
  "style": {
    "marginTop": "1rem",
    "fontSize": "0.9rem"
  }
}

Validation Props

{
  "validation": {
    "validateOnChange": true,
    "validateOnBlur": true,
    "showValidationIcon": true,
    "validationDelay": 500
  }
}

Accessibility Props

{
  "accessibility": {
    "ariaLabel": "Custom aria label",
    "ariaDescribedBy": "help-text-id",
    "tabIndex": 0,
    "role": "button"
  }
}

Responsive Design

Responsive Props

{
  "responsive": {
    "breakpoints": {
      "mobile": {
        "columns": 1,
        "fontSize": "0.9rem"
      },
      "tablet": {
        "columns": 2,
        "fontSize": "1rem"
      },
      "desktop": {
        "columns": 3,
        "fontSize": "1.1rem"
      }
    }
  }
}

Mobile-Specific Components

{
  "id": "mobile_stepper",
  "type": "display",
  "conditional": {
    "showIf": {
      "field": "deviceType",
      "operator": "equals",
      "value": "mobile"
    }
  },
  "uiConfig": {
    "component": "mobile_progress_stepper",
    "props": {
      "steps": ["Verify", "Select", "Review", "Submit"],
      "currentStep": 2,
      "showLabels": false,
      "compact": true
    }
  }
}

Component Styling

Theme Integration

{
  "uiConfig": {
    "component": "button",
    "props": {
      "variant": "primary",
      "size": "large",
      "theme": {
        "colors": {
          "primary": "#E07A5F",
          "secondary": "#3D405B"
        },
        "borderRadius": "8px",
        "fontFamily": "Inter, sans-serif"
      }
    }
  }
}

Custom Styling

{
  "uiConfig": {
    "component": "card",
    "props": {
      "customStyles": {
        "container": {
          "boxShadow": "0 4px 6px rgba(0, 0, 0, 0.1)",
          "borderRadius": "12px"
        },
        "header": {
          "backgroundColor": "#f8f9fa",
          "borderBottom": "1px solid #dee2e6"
        },
        "content": {
          "padding": "2rem"
        }
      }
    }
  }
}

Interactive Behavior

Event Handling

{
  "uiConfig": {
    "component": "button",
    "props": {
      "onClick": {
        "type": "updateInstanceData",
        "target": "selectedAction",
        "value": "proceed"
      },
      "onHover": {
        "type": "showTooltip",
        "message": "Click to continue"
      }
    }
  }
}

Animation and Transitions

{
  "uiConfig": {
    "component": "slide_panel",
    "props": {
      "animation": {
        "enter": "slideInRight",
        "exit": "slideOutLeft",
        "duration": 300
      },
      "transition": "ease-in-out"
    }
  }
}

Best Practices

1. Consistency

Use consistent spacing and sizing across components
Maintain consistent color schemes and typography
Apply consistent validation and error handling patterns

2. Accessibility

Always provide appropriate labels and help text
Use proper ARIA attributes for screen readers
Ensure keyboard navigation works properly
Maintain adequate color contrast ratios

3. Performance

Use conditional rendering to avoid unnecessary DOM elements
Implement lazy loading for heavy components
Minimize the number of re-renders with proper data binding

4. User Experience

Provide immediate feedback for user actions
Use loading states for async operations
Implement proper error boundaries
Test on various devices and screen sizes

Next Steps

Data Operations - API calls and transformations

Component Structure​

Core Component Types​

1. Input Components​

Text Input​

Email Input​

Phone Input​

Textarea​

Number Input​

Date Input​

2. Selection Components​

Dropdown Select​

Radio Button Group​

Checkbox Group​

Single Checkbox​

3. Display Components​

Info Card​

Alert​

Progress Bar​

4. Composite Components​

Product Multi-Select​

Address Form​

Product Search​

File Upload​

5. Container Components​

Card Container​

Column Layout​

Tabs Container​

Custom Components​

Defining Custom Components​

Using Custom Components​

Component Props Reference​

Common Props​

Validation Props​

Accessibility Props​

Responsive Design​

Responsive Props​

Mobile-Specific Components​

Component Styling​

Theme Integration​

Custom Styling​

Interactive Behavior​

Event Handling​

Animation and Transitions​

Best Practices​

1. Consistency​

2. Accessibility​

3. Performance​

4. User Experience​

Next Steps​