# Form Builder User Guide

## Overview

The Form Builder is a modern, intuitive drag-and-drop interface for creating dynamic forms. Featuring a smart collapsible settings panel, visual grid system, and intelligent component recommendations, it makes form creation accessible to both developers and non-technical users.

> For technical implementation details, see the [Technical Guide](TECHNICAL_GUIDE.md)

## Interface Overview

### Three-Panel Layout
- **Left Panel**: Component Library with categorized components
- **Center Panel**: Form Canvas with 12-column grid system
- **Right Panel**: Smart Collapsible Settings Panel

### Key Features
- **Smart Settings Panel**: Auto-opens when components are selected, collapses to save space
- **Visual Grid System**: Intuitive width selection with grid previews
- **Quick Settings**: Inline editing for common properties
- **Smart Recommendations**: Automatic width suggestions based on field type
- **Real-time Preview**: See changes instantly as you build

## Getting Started

### Creating Your First Form

1. **Start Building**
   - Navigate to the Form Builder
   - Click "New Form" or start with a template
   - The interface loads with an empty canvas

2. **Add Components**
   - **Drag & Drop**: Drag any component from the left panel to the canvas
   - **Click to Add**: Click a component to add it at the end of the form
   - **Smart Placement**: Components automatically find optimal grid positions

3. **Configure Components**
   - **Auto-Selection**: Click any component to select it
   - **Quick Settings**: The right panel automatically opens with common settings
   - **Inline Editing**: Edit labels, names, widths, and validation directly
   - **Full Settings**: Click "Full Settings" for advanced configuration

4. **Save & Preview**
   - **Auto-Save**: Changes are saved automatically
   - **Preview Mode**: Toggle to test your form as users will see it
   - **Form Management**: Access all saved forms from the header

## Smart Settings Panel System

### Panel Behavior
- **Auto-Open**: Automatically expands when you select a component
- **Collapsible**: Toggle between expanded (320px) and collapsed (48px) states
- **Quick Access**: Common settings available without opening full modal
- **Context-Aware**: Shows only relevant settings for each component type

### Quick Settings Available
- **Label**: Component display name
- **Field Name**: Internal identifier
- **Width**: S/M/L/XL quick sizing buttons
- **Required**: Toggle validation
- **Placeholder**: Hint text (where applicable)

### Collapsed State Features
- **Component Icon**: Visual indicator of selected component type
- **Type Badge**: Short identifier (TXT, BTN, SEL, etc.)
- **Toggle Button**: One-click expansion
- **Space-Efficient**: Only 48px wide when collapsed

## Enhanced Grid System

### Visual Width Selection
The new grid system replaces technical percentages with intuitive options:

#### Width Options
- **Narrow (25%)**: Small inputs like age, zip codes, short codes
- **Small (33%)**: Short text fields, city names, grouped inputs  
- **Medium (50%)**: Names, phone numbers, paired inputs
- **Wide (75%)**: Addresses, URLs, prominent fields
- **Full (100%)**: Text areas, headings, single-column layouts

#### Visual Grid Preview
- **12-Column Grid**: Mini preview shows exactly which columns your component will occupy
- **Active Columns**: Highlighted squares show component width
- **Current Selection**: Visual feedback shows your current choice
- **Grid Math**: Displays "6 of 12 columns" instead of technical details

### Smart Recommendations
The system automatically suggests optimal widths based on component type:

- **Narrow Recommended**: Number, Date, Time, Color, OTP fields
- **Small Recommended**: Text inputs
- **Medium Recommended**: Email, Phone, Password, Select, Masked inputs
- **Wide Recommended**: URL, File uploads
- **Full Recommended**: Text areas, Headings, Choice groups, Buttons

#### Visual Indicators
- **Green Ring**: Recommended options have green highlighting
- **Selection State**: Current choice highlighted in blue
- **Combined State**: Selected + recommended shows green background

## Component Library

### Basic Inputs
Perfect for collecting simple data:

**Text Field**
- Single-line text input
- Smart width: Small (33%)
- Use for: Names, titles, short answers
- Quick settings: Label, name, placeholder, required

**Text Area**
- Multi-line text input  
- Smart width: Full (100%)
- Use for: Comments, descriptions, long text
- Features: Resizable, character limits

**Number Field**
- Numeric input with validation
- Smart width: Narrow (25%)
- Use for: Age, quantity, prices
- Features: Min/max limits, step values

**Email Field**
- Email input with validation
- Smart width: Medium (50%)
- Use for: Contact forms, registration
- Features: Built-in email format validation

**Password Field**
- Secure password input
- Smart width: Medium (50%)
- Use for: Authentication forms
- Features: Password masking, strength indicators

### Selection Components
For choosing from options:

**Select Dropdown**
- Single selection from options
- Smart width: Medium (50%)
- Use for: Countries, categories, status
- Features: Search, custom values, option groups

**Checkbox Group**
- Multiple selection options
- Smart width: Full (100%)
- Use for: Preferences, multiple choices
- Features: Select all option, layout control

**Radio Group**  
- Single choice from group
- Smart width: Full (100%)
- Use for: Exclusive choices, yes/no questions
- Features: Button or traditional styles

**Switch Toggle**
- Boolean on/off control
- Smart width: Full (100%)
- Use for: Settings, feature toggles
- Features: Custom labels, default states

### Date & Time Components
For temporal inputs:

**Date Picker**
- Date selection interface
- Smart width: Narrow (25%)
- Use for: Birthdays, deadlines, scheduling
- Features: Date ranges, format options, validation

**Time Picker**
- Time selection interface  
- Smart width: Narrow (25%)
- Use for: Appointments, schedules
- Features: 12/24 hour format, minute intervals

**Date & Time**
- Combined date and time picker
- Smart width: Medium (50%)
- Use for: Event scheduling, timestamps
- Features: Single field for both values

### Advanced Components
Specialized functionality:

**File Upload**
- Standard file input
- Smart width: Wide (75%)
- Use for: Document uploads, attachments
- Features: File type restrictions, size limits

**File Drop Zone**
- Drag & drop upload area
- Smart width: Wide (75%)
- Use for: Multiple files, intuitive uploads
- Features: Visual feedback, progress indicators

**OTP Input**
- One-time password entry
- Smart width: Narrow (25%)
- Use for: Two-factor authentication
- Features: Auto-focus, numeric only

**Masked Input**
- Formatted text input
- Smart width: Medium (50%)
- Use for: Phone numbers, SSN, custom formats
- Features: Real-time formatting, validation

### Layout Components
Form structure and organization:

**Heading**
- Section titles and organization
- Smart width: Full (100%)
- Use for: Form sections, categories
- Features: Multiple heading levels (H1-H6)

**Paragraph**
- Descriptive text content
- Smart width: Full (100%)
- Use for: Instructions, explanations
- Features: Rich text formatting options

**Divider**
- Visual section separator
- Smart width: Full (100%)
- Use for: Content organization
- Features: Various visual styles

**Button**
- Action triggers
- Smart width: Full (100%)
- Use for: Form submission, navigation
- Features: Custom styling, click handlers

## Form Configuration Workflows

### Quick Settings Workflow (80% of edits)
1. Click any component to select it
2. Settings panel auto-opens on the right
3. Edit common properties inline:
   - Change label text
   - Adjust field width with S/M/L/XL buttons
   - Toggle required validation
   - Set placeholder text
4. Changes apply immediately

### Full Settings Workflow (20% of edits)
1. Select component in quick settings panel
2. Click "Full Settings" button
3. Access comprehensive modal with:
   - All component properties
   - Advanced validation rules
   - Visual width selector with grid preview
   - Component-specific options
   - Reset to defaults option

### Bulk Operations
- **Duplicate**: Copy component with "Duplicate" button
- **Delete**: Remove component with "Delete" button  
- **Reorder**: Drag components to reposition
- **Multi-select**: Select multiple components for batch operations

## Form Templates & Management

### Template System
- **Blank Form**: Start from scratch
- **Contact Form**: Pre-built contact form
- **Survey Form**: Multi-question survey template
- **Registration Form**: User registration template
- **Custom Templates**: Save your own templates

### Form Management
- **Auto-Save**: Changes saved automatically every 30 seconds
- **Version History**: Track form changes over time
- **Duplicate Forms**: Copy existing forms as starting points
- **Export/Import**: JSON format for form portability
- **Form Library**: Organize forms by category or project

## Process Builder Integration

### Workflow Integration
Forms integrate seamlessly with the Process Builder for automated workflows:

1. **Create Form**: Design your form in Form Builder
2. **Save Form**: Forms must be saved before use in processes  
3. **Add to Process**: Select saved form in Process Builder Form Task
4. **Data Flow**: Form submissions become process variables
5. **Decision Logic**: Use form data in process gateways and conditions

### Advanced Integration Features
- **URL Parameters**: Pre-populate form fields from process variables
- **Conditional Logic**: Show/hide fields based on process state
- **Multi-Step Forms**: Split complex forms across multiple process steps
- **Data Validation**: Cross-reference form data with process requirements

## Best Practices

### Form Design
1. **Start Simple**: Begin with essential fields only
2. **Use Smart Widths**: Trust the width recommendations
3. **Group Related Fields**: Use consistent widths for grouped fields
4. **Logical Flow**: Order fields in a natural sequence
5. **Mobile-First**: Test forms on mobile devices

### Grid Layout Optimization
1. **Mix Widths**: Combine narrow and wide fields effectively
2. **Visual Balance**: Avoid too many full-width fields in sequence  
3. **Logical Grouping**: Use similar widths for related fields
4. **Space Efficiency**: Let the system auto-optimize grid placement

### User Experience  
1. **Clear Labels**: Use descriptive, action-oriented labels
2. **Helpful Placeholders**: Provide examples in placeholder text
3. **Progressive Disclosure**: Use sections for complex forms
4. **Validation Feedback**: Set appropriate validation rules
5. **Success States**: Configure clear success messages

### Performance Optimization
1. **Component Limits**: Keep forms under 50 components when possible
2. **Conditional Logic**: Use sparingly to maintain performance
3. **File Uploads**: Set reasonable file size limits
4. **Auto-Save**: Leverage automatic saving features

## Accessibility Features

### Built-in Accessibility
- **Keyboard Navigation**: Full keyboard support
- **Screen Reader Support**: Proper ARIA labels and descriptions
- **Focus Management**: Clear focus indicators
- **High Contrast**: Accessible color combinations
- **Touch Targets**: Mobile-friendly touch targets

### Accessibility Best Practices
1. **Descriptive Labels**: Always provide clear field labels
2. **Help Text**: Use help text for complex fields
3. **Error Messages**: Provide clear, actionable error messages
4. **Logical Order**: Ensure tab order follows visual layout
5. **Alternative Text**: Provide alt text for any images

## Troubleshooting

### Common Issues

**Panel Not Opening**
- Ensure component is properly selected
- Check browser console for JavaScript errors
- Refresh page if panel state becomes stuck

**Grid Layout Issues**
- Use the optimize layout feature
- Check for invalid width values
- Reset component to default width

**Components Not Saving**
- Verify internet connection
- Check browser local storage limits
- Try manual save if auto-save fails

**Performance Issues**  
- Reduce number of components
- Simplify conditional logic
- Clear browser cache

### Getting Help
- **Documentation**: Complete technical guides available
- **Examples**: Sample forms and templates provided
- **Support**: Contact support team for assistance
- **Community**: Join user community forums

## Advanced Features

### Custom Components
- **Component Extensions**: Add custom component types
- **Styling Overrides**: Custom CSS for branded forms
- **Validation Rules**: Create custom validation logic
- **Integration Hooks**: Connect to external services

### API Integration
- **Form Data API**: Programmatic access to form submissions
- **Component API**: Dynamically modify form components
- **Validation API**: Custom server-side validation
- **Webhook Support**: Real-time form submission notifications

### Enterprise Features
- **Team Collaboration**: Multi-user form editing
- **Permission Management**: Role-based access control
- **Audit Logging**: Track all form changes
- **White Labeling**: Custom branding options

---

*This documentation reflects all current features including the smart collapsible settings panel, enhanced grid system with visual previews, intelligent width recommendations, and comprehensive UX improvements implemented in the latest version.*

Last updated: December 2024