# ALS Forms Builder - Source Code Documentation

**This document provides complete source code documentation for the ALS Forms Builder** All source code is included in the `/als-js-forms-builder/` directory and is fully accessible for review, modification, and contribution.

### 📍 Quick Source Code Locations

| Component | Source Location | Purpose |
|-----------|----------------|---------|
| **Frontend Builder** | `/als-js-forms-builder/src/` | Vue.js form builder interface |
| **PHP Backend** | `/includes/` | Server-side form processing |
| **Build Config** | `/als-js-forms-builder/vite.config.js` | Build tool configuration |
| **Dependencies** | `/als-js-forms-builder/package.json` | All third-party libraries |

## 🏗️ Build Process & Source Code

The ALS Forms Builder frontend is located in `/als-js-forms-builder/` and uses modern build tools to compile and optimize the code. **All source code is included in this repository and is fully human-readable.**

### Source Code Structure

```
src/
├── App.vue                 # Main application component
├── main.js                 # Application entry point
├── style.css              # Global styles
├── components/            # Vue components
│   ├── FieldSettings.vue  # Field configuration panel
│   ├── FormCanvas.vue     # Drag-and-drop form builder
│   ├── LayoutSettings.vue # Layout configuration
│   ├── LayoutToolbar.vue  # Layout selection toolbar
│   ├── LivePreview.vue    # Real-time form preview
│   ├── Sidebar.vue        # Form elements sidebar
│   ├── Toolbar.vue        # Main toolbar
│   └── modals/
│       └── TemplatesModal.vue # Form templates modal
├── utils/
│   ├── fieldDefaults.js   # Default field configurations
│   └── templates.js       # Pre-built form templates
└── assets/
    └── vue.svg            # Vue logo
```

### Build Tools

- **Build System**: [Vite](https://vitejs.dev/) - Fast build tool and development server
- **Frontend Framework**: [Vue.js 3](https://vuejs.org/) - Progressive JavaScript framework
- **CSS Processing**: Native CSS with Vue SFC support
- **Font Processing**: FontAwesome icons processing

### Dependencies

#### Runtime Dependencies
- **Vue 3** (`^3.5.13`) - MIT License - Core framework
- **VueDraggable** (`^4.1.0`) - MIT License - Drag and drop functionality  
- **DOMPurify** (`^3.2.6`) - Apache/Mozilla - XSS protection for user input
- **FontAwesome Free** (`^6.7.2`) - CC BY 4.0 License - Icon fonts

#### Development Dependencies  
- **Vite** (`^6.3.1`) - MIT License - Build tool and dev server
- **@vitejs/plugin-vue** (`^5.2.2`) - MIT License - Vue support for Vite

All license information is available in the respective npm packages and can be reviewed via `npm ls --depth=0`.

## 🚀 Development Setup

### Prerequisites
- Node.js (v16 or higher)
- npm or yarn

## 📁 Generated/Compiled Files

The build process generates these files in `dist/assets/`:

- **`index-[hash].js`** - Compiled JavaScript (minified)
- **`index-[hash].css`** - Compiled CSS (minified)
- **`fonts/`** - FontAwesome font files

### Source-to-Build Mapping

| Source Files | Compiled Output | Purpose |
|-------------|----------------|---------|
| `src/**/*.vue` | `dist/assets/index-[hash].js` | Vue components |
| `src/**/*.js` | `dist/assets/index-[hash].js` | JavaScript utilities |
| `src/**/*.css` | `dist/assets/index-[hash].css` | Styles |
| `node_modules/@fortawesome/fontawesome-free/webfonts/` | `dist/assets/fonts/` | Icon fonts |

## 🔧 Build Configuration

### Vite Configuration (`vite.config.js`)
```javascript
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  build: {
    rollupOptions: {
      output: {
        assetFileNames: (assetInfo) => {
          if (assetInfo.name && assetInfo.name.includes('fa-')) {
            return 'assets/fonts/[name][extname]';
          }
          return 'assets/[name]-[hash][extname]';
        },
      },
    },
  },
});
```

## 🎨 Features

### Form Builder Components
- **Drag & Drop Interface** - Built with VueDraggable
- **Real-time Preview** - Live form rendering
- **Field Types** - Text, email, textarea, select, checkbox, radio, number, date, time, file upload
- **Layout System** - Multi-column layouts with responsive design
- **Styling Options** - Custom colors, borders, spacing
- **Template System** - Pre-built form templates

### Security Features
- **XSS Protection** - DOMPurify sanitization
- **Input Validation** - Client-side validation
- **Nonce Verification** - WordPress nonce integration

### WordPress Integration
- **AJAX Integration** - Uses WordPress admin-ajax.php
- **Media Library** - WordPress media picker integration
- **Responsive Design** - Works on all device sizes

## 🔐 Security Considerations

This frontend code includes several security measures:

1. **DOMPurify Integration** - Sanitizes user input to prevent XSS attacks
2. **WordPress Nonces** - CSRF protection for all AJAX requests
3. **Input Validation** - Client-side validation for all form fields
4. **Proper Escaping** - All user content is properly escaped before rendering

## 🌐 Browser Compatibility

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

## 📝 Development Notes

### Code Style
- Uses Vue 3 Composition API with `<script setup>`
- ESM modules throughout
- Reactive state management with Vue's reactivity system
- Component-based architecture

### WordPress Integration Points
- Uses `window.ALS_FORMS_BUILDER` global object for configuration
- Integrates with WordPress media library
- Uses WordPress admin-ajax.php for backend communication
- Respects WordPress nonce security

## 📄 WordPress.org Submission Compliance

### Source Code Accessibility ✅

This plugin fully complies with WordPress.org guidelines for human-readable code:

1. **All source code is included** in the `/als-js-forms-builder/src/` directory
2. **Build process is fully documented** with step-by-step instructions
3. **All third-party libraries are listed** with proper licenses
4. **No external dependencies** required for source code review
5. **Clear source-to-build mapping** provided in documentation

**Note:** This documentation is also referenced in the main plugin `readme.txt` file under "Source Code & Build Process" section.

## 📄 License
This project is part of the ALS Forms Builder Free WordPress plugin, licensed under GPL v2 or later.