🧩 Widget Builder Guide

Date: November 5, 2025
Status: ✅ Ready to Use
Purpose: Create reusable, modular widgets for your platform

🎯 What is Widget Builder?

Widget Builder is a visual tool for creating reusable UI components that can be:

• Used across multiple pages
• Packaged into modules
• Shared with other space-builders
• Customized via inputs/outputs
• Styled with theme variables

🚀 How to Access Widget Builder

Route:

/space/{space}/editor/widget-builder

Navigation:

1. Go to Editor (any page or blank canvas)
2. Navigate to: /space/{space}/editor/widget-builder
3. Or use navigation service:

   this.spaceNav.navigate('editor/widget-builder');
   

🏗️ Creating a New Widget

Step 1: Choose Template or Start Blank

Templates Available:

• Button Widget - Customizable button component
• Card Widget - Content card with header and actions
• Form Widget - Dynamic form with validation
• Data Table Widget - Sortable, filterable data table
• Chart Widget - Interactive chart visualization

Or: Click "Create Blank Widget" to start from scratch

Step 2: Design Your Widget

Use the Design Panel to:

• Add visual components
• Arrange layout
• Style elements

Step 3: Configure Inputs

Widget Inputs = Properties users can customize when using your widget

Example:

{
  name: 'title',
  type: 'string',
  required: true,
  defaultValue: 'My Title',
  description: 'The title text to display'
}

Common Input Types:

• string - Text values
• number - Numeric values
• boolean - True/false toggles
• array - Lists of items
• object - Complex data structures

Step 4: Configure Outputs

Widget Outputs = Events your widget can emit

Example:

{
  name: 'onClick',
  type: 'void',
  description: 'Emitted when widget is clicked'
}

Step 5: Apply Theme Variables

Map widget properties to theme variables for automatic theme support:

• --theme-surface → Background
• --theme-primary → Primary color
• --theme-text-primary → Text color
• --theme-border → Border color

Result: Widget automatically adapts to platform theme!

Step 6: Preview

Test your widget across breakpoints:

• Mobile (375px)
• Tablet (768px)
• Desktop (1920px)

Step 7: Export

Choose export format:

1. Save to Registry → Widget available in Editor widget palette
2. Export as Standalone Component → Single .ts file
3. Export as NX Library → Full library structure

📋 Widget Builder Interface

Left Sidebar - Panels:

1. Design - Visual widget designer
2. Inputs - Define widget properties
3. Theme - Map to theme variables
4. Preview - Test across breakpoints
5. Export - Save/export widget

Center - Preview:

Live preview of your widget with responsive breakpoint testing

Right Sidebar - Templates:

Quick-start templates for common widget types

🔄 Widget Lifecycle

Creation Flow:

1. Choose Template / Start Blank
   ↓
2. Design Widget Visually
   ↓
3. Configure Inputs/Outputs
   ↓
4. Apply Theme Variables
   ↓
5. Preview & Test
   ↓
6. Save to Registry / Export
   ↓
7. Widget Available in Editor Palette

💡 Best Practices

1. Reusability First

• Design widgets to work in multiple contexts
• Use inputs for customization, not hardcoded values
• Make outputs generic (emit data, not specific actions)

2. Theme Integration

• Always map colors to theme variables
• Don't hardcode colors (unless absolutely necessary)
• Support both light and dark themes

3. Responsive Design

• Test on all breakpoints
• Use relative units (rem, %, vw/vh)
• Consider mobile-first approach

4. Clear Documentation

• Descriptive input/output names
• Helpful descriptions
• Default values that make sense

5. Performance

• Keep widgets lightweight
• Use OnPush change detection
• Optimize images/assets

🎨 Example: Creating a "Product Card" Widget

Step 1: Choose "Card Widget" Template

Step 2: Configure Inputs:

[
  {
    name: 'product',
    type: 'object',
    required: true,
    description: 'Product data'
  },
  {
    name: 'showPrice',
    type: 'boolean',
    defaultValue: true,
    description: 'Show product price'
  },
  {
    name: 'showDescription',
    type: 'boolean',
    defaultValue: false,
    description: 'Show product description'
  }
]

Step 3: Configure Outputs:

[
  {
    name: 'onAddToCart',
    type: 'object',
    description: 'Emitted when "Add to Cart" is clicked'
  },
  {
    name: 'onViewDetails',
    type: 'void',
    description: 'Emitted when product is clicked'
  }
]

Step 4: Apply Theme:

• Background → --theme-surface
• Text → --theme-text-primary
• Border → --theme-border
• Button → --theme-primary

Step 5: Save to Registry

Widget is now available in Editor widget palette!

🔗 Integration with Editor

Once saved to registry, your widget:

• ✅ Appears in Editor widget library
• ✅ Can be dragged onto any page
• ✅ Accepts inputs via properties panel
• ✅ Emits outputs that can trigger flows
• ✅ Adapts to platform theme automatically

📚 File Locations

• Widget Builder Component: libs/editor-web-lib/src/lib/components/widget-builder/
• Widget Builder Service: libs/editor-web-lib/src/lib/services/widget-builder.service.ts
• Widget Types: libs/editor-web-lib/src/lib/types/widget-builder.types.ts
• Route: /space/{space}/editor/widget-builder

🚀 Next Steps

1. Create Your First Widget:

   • Navigate to Widget Builder
   • Choose a template or start blank
   • Follow the 7-step process

2. Use Your Widget:

   • Go to Editor
   • Open widget library
   • Drag your widget onto a page

3. Package Into Module:

   • Create a module in Modularity
   • Select pages that use your widgets
   • Package and deploy!

🎉 You're Ready!

Widget Builder is fully functional and ready to use. Start creating reusable widgets for your platform!