ima-claude 2.9.0

package/plugins/ima-claude/skills/ima-forms-expert/references/form-factory.md

@@ -0,0 +1,193 @@
+# Form Factory Pattern (v1.2.0) - Auto-Wired Validation
+
+## Contents
+
+- [Creating Forms with Auto-Validation](#creating-forms-with-auto-validation)
+- [Auto-Wiring Field Functions](#auto-wiring-field-functions)
+- [Extending with Custom Validation](#extending-with-custom-validation)
+- [Form Wrapper Functions](#form-wrapper-functions)
+- [Security Chokepoint Pattern](#security-chokepoint-pattern)
+
+---
+
+## Creating Forms with Auto-Validation
+
+The form factory pattern uses function composition to automatically wire validators to field types:
+
+```php
+// Create form with auto-wired validation
+['render' => $render, 'validate' => $validate] = ima_forms_create_form(
+    'contact-form',  // Form ID
+    function($register) use ($data, $errors) {
+        // Use auto-wiring field functions
+        ima_forms_email($register, [
+            'name' => 'email',
+            'label' => 'Email Address',
+            'required' => true,
+            'value' => $data['email'] ?? '',
+            'error' => $errors['email'] ?? '',
+        ]);
+
+        ima_forms_phone($register, [
+            'name' => 'phone',
+            'label' => 'Phone Number',
+            'required' => true,
+            'value' => $data['phone'] ?? '',
+            'error' => $errors['phone'] ?? '',
+        ]);
+
+        ima_forms_textarea($register, [
+            'name' => 'message',
+            'label' => 'Message',
+            'required' => true,
+            'value' => $data['message'] ?? '',
+            'error' => $errors['message'] ?? '',
+        ]);
+    }
+);
+
+// Render form
+$render();
+
+// Validate (in AJAX handler)
+$validation = $validate($sanitized_data);
+if (!$validation['valid']) {
+    wp_send_json_error(['errors' => $validation['errors']]);
+}
+```
+
+## Auto-Wiring Field Functions
+
+**Available auto-wiring functions** (automatically attach validators):
+
+| Function | Validator |
+|----------|-----------|
+| `ima_forms_text($register, $args)` | Required validator |
+| `ima_forms_email($register, $args)` | Format + enhanced validation |
+| `ima_forms_phone($register, $args)` | Format validation |
+| `ima_forms_url($register, $args)` | Format validation |
+| `ima_forms_textarea($register, $args)` | Required validator |
+| `ima_forms_select($register, $args)` | Required validator |
+| `ima_forms_checkbox($register, $args)` | Required validator |
+| `ima_forms_checkbox_group_field($register, $args)` | Required (array) |
+
+## Extending with Custom Validation
+
+```php
+// Compose auto-wired + custom validators
+$combined = ima_forms_compose_validators(
+    $validate,  // Auto-wired from form factory
+    function($data) {
+        $errors = [];
+        // Your custom validation
+        if ($data['password'] !== $data['password_confirm']) {
+            $errors['password_confirm'] = 'Passwords must match.';
+        }
+        return ['valid' => empty($errors), 'errors' => $errors];
+    }
+);
+```
+
+## Form Wrapper Functions
+
+### Standardized Form Container
+
+```php
+ima_forms_form([
+    'id' => 'my-form',
+    'action' => 'my_ajax_action',  // AJAX action name
+    'method' => 'post',
+    'class' => 'ima-form w-100',   // Default: full width
+    'nonce_action' => 'my_form_submit',
+    'nonce_name' => 'nonce',
+    'enqueue_base' => true,        // Auto-enqueue ima-forms-base.js
+], function() {
+    // Form fields here
+    ima_forms_text_field([...]);
+    ima_forms_email_field([...]);
+
+    // Standardized submit button
+    ima_forms_submit_button([
+        'text' => 'Submit Form',
+        'processing_text' => 'Submitting...',
+        'class' => 'btn btn-primary',
+        'show_spinner' => true,
+    ]);
+});
+```
+
+### Benefits
+
+- **Automatic error container**: `.ima-form-errors` populated by JavaScript
+- **Automatic success container**: `.ima-form-success` for success messages
+- **AJAX-ready**: `data-action` attribute for JavaScript handler
+- **Nonce included**: WordPress nonce field automatically added
+- **Loading states**: Submit button shows spinner and disables during submission
+
+## Security Chokepoint Pattern
+
+### AJAX Handler Factory (Classic Approach)
+
+```php
+// Create secure AJAX handler
+$handler = ima_forms_create_ajax_handler(
+    'listing_application',           // Form ID
+    'ima_form_listing_application',  // Nonce action
+    'ima_listing_sanitize',          // Sanitization function
+    'ima_listing_validate',          // Validation function
+    'ima_listing_process'            // Processing function
+);
+
+// Register AJAX hooks
+add_action('wp_ajax_ima_listing_submit', $handler);
+add_action('wp_ajax_nopriv_ima_listing_submit', $handler);
+```
+
+**Security layers** (automatic):
+1. **Nonce verification**: CSRF protection
+2. **Sanitization**: Context-appropriate cleaning
+3. **Validation**: Business rules enforcement
+4. **Processing**: Controlled side effects
+
+**Rate limiting**: Handled by infrastructure (WordFence, Akismet, WP Armour)
+
+### Modern Approach with Validation Engine
+
+```php
+function my_form_ajax_handler() {
+    // Security: Nonce verification
+    if (!wp_verify_nonce($_POST['nonce'], 'my_form_submit')) {
+        wp_send_json_error(['message' => 'Security check failed.'], 403);
+    }
+
+    // Validate + Sanitize (automatic via template)
+    $result = ima_forms_validate_form(
+        'templates/forms/my-form',
+        $_POST,
+        'my-form'
+    );
+
+    if (!$result['valid']) {
+        wp_send_json_error([
+            'message' => 'Please correct the errors.',
+            'errors' => $result['errors']
+        ], 400);
+    }
+
+    // Process validated data
+    $data = $result['sanitized'];
+    // ... your processing logic
+
+    wp_send_json_success(['message' => 'Success!']);
+}
+
+add_action('wp_ajax_my_form_submit', 'my_form_ajax_handler');
+```
+
+### When to Use Which Pattern
+
+| Pattern | Use When |
+|---------|----------|
+| **Validation Engine** (v1.3.0) | Simple forms, standard validation needs |
+| **Form Factory** (v1.2.0) | Programmatic field generation, dynamic forms |
+| **Classic AJAX Handler** | Legacy code, complex multi-step processing |

package/plugins/ima-claude/skills/ima-forms-expert/references/quick-reference.md

@@ -0,0 +1,153 @@
+# Quick Reference
+
+## Contents
+
+- [Field Components](#field-components-auto-registration)
+- [Container Components](#container-components)
+- [Validation Engine (v1.4.0)](#validation-engine-v140)
+- [Registry Functions](#registry-functions)
+- [Validators](#validators)
+- [Sanitizers](#sanitizers)
+- [Core Functions](#core-functions)
+- [Version Features](#version-features)
+- [Filters](#filters)
+
+---
+
+## Field Components (Auto-Registration)
+
+| Function | Purpose |
+|----------|---------|
+| `ima_forms_text_field()` | Text input with validation |
+| `ima_forms_email_field()` | Email with enhanced validation |
+| `ima_forms_password_field()` | Password input |
+| `ima_forms_hidden_field()` | Hidden field |
+| `ima_forms_textarea_field()` | Multi-line text |
+| `ima_forms_select_field()` | Dropdown select |
+| `ima_forms_state_select_field()` | US states dropdown |
+| `ima_forms_checkbox_field()` | Single checkbox |
+| `ima_forms_checkbox_group()` | Multiple checkboxes |
+| `ima_forms_phone_field()` | Phone with format validation |
+| `ima_forms_url_field()` | URL with format validation |
+| `ima_forms_address_fieldset()` | Composite address fields |
+| `ima_forms_consent_agreement_field()` | Scrollable agreement + signature |
+
+## Container Components
+
+| Function | Purpose |
+|----------|---------|
+| `ima_forms_form()` | Complete form wrapper with AJAX |
+| `ima_forms_submit_button()` | Standardized submit button |
+| `ima_forms_card()` | Bootstrap card wrapper |
+| `ima_forms_section()` | Section with heading |
+| `ima_forms_column_layout()` | Responsive columns |
+| `ima_forms_fieldset()` | Semantic fieldset |
+| `ima_forms_repeater()` | Dynamic row repeater |
+
+## Validation Engine (v1.4.0)
+
+| Function | Purpose |
+|----------|---------|
+| `ima_forms_validate_form($template, $data, $form_id, $args)` | Main validation entry |
+| `ima_forms_validate_against_specs($specs, $data)` | Validate data against specs |
+| `ima_forms_run_validators($specs, $sanitized)` | Run stored validators |
+| `ima_forms_sanitize_against_specs($specs, $data)` | Sanitize using specs |
+| `ima_forms_debug_validation_summary($specs)` | Debug: validation preview |
+
+## Registry Functions
+
+| Function | Purpose |
+|----------|---------|
+| `ima_forms_register_field_spec($name, $spec)` | Register field spec + validators |
+| `ima_forms_get_field_specs()` | Get all registered specs |
+| `ima_forms_clear_field_specs()` | Clear registry |
+| `ima_forms_has_field_spec($name)` | Check if field registered |
+| `ima_forms_get_field_spec($name)` | Get single spec |
+| `ima_forms_get_field_spec_count()` | Count registered specs |
+| `ima_forms_debug_field_specs()` | Human-readable spec dump |
+
+## Validators
+
+| Function | Purpose |
+|----------|---------|
+| `ima_forms_validate_required($value, $label)` | Required check |
+| `ima_forms_validate_email($email, $label)` | Basic RFC 5322 |
+| `ima_forms_validate_email_enhanced($email, $label, $enhanced)` | Full email validation |
+| `ima_forms_validate_phone($phone, $label)` | Phone format |
+| `ima_forms_validate_url($url, $label)` | URL format |
+| `ima_forms_validate_min_length($value, $min, $label)` | Min length |
+| `ima_forms_validate_max_length($value, $max, $label)` | Max length |
+| `ima_forms_validate_array_required($array, $label)` | Array not empty |
+| `ima_forms_validate_numeric($value, $label)` | Numeric check |
+| `ima_forms_validate_range($value, $min, $max, $label)` | Range check |
+| `ima_forms_create_email_validator($domains, $typos)` | Pre-compiled validator |
+
+## Sanitizers
+
+| Function | Purpose |
+|----------|---------|
+| `ima_forms_sanitize_field($type, $value)` | Single field |
+| `ima_forms_sanitize_data($data, $field_map)` | Multiple fields |
+| `ima_forms_sanitize_repeater($rows, $field_map)` | Repeater rows |
+| `ima_forms_sanitize_against_specs($specs, $data)` | Using specs (auto) |
+
+## Core Functions
+
+| Function | Purpose |
+|----------|---------|
+| `ima_forms_create_ajax_handler()` | Security chokepoint |
+| `ima_forms_create_renderer()` | Template rendering |
+| `ima_forms_load_field_template()` | Template hierarchy |
+| `ima_forms_get_us_states()` | US states data |
+
+## Version Features
+
+### v1.4.0 (Validators at Registration)
+- Validators built as closures at field registration
+- `spec['validators']` stores closure array
+- `ima_forms_run_validators()` just iterates and runs
+- No type switching in engine
+
+### v1.3.0 (Validation Engine)
+- Template-driven validation
+- Field spec registry
+- Automatic sanitization from specs
+- `ima_forms_validate_form()` as primary API
+
+### v1.2.0 (Form Factory)
+- Auto-wired validation via function composition
+- `ima_forms_create_form()` factory
+- `ima_forms_form()` and `ima_forms_submit_button()` wrappers
+- Password and hidden field types
+- Consent agreement component
+- Enhanced email validation with disposable domains
+
+### v1.1.0 (Container Components)
+- Card, section, column layout, fieldset components
+- Repeater with auto-enqueuing
+- Template override system
+
+### v1.0.0 (Foundation)
+- Basic field components
+- Pure validators and sanitizers
+- Security chokepoint pattern
+- Bootstrap 5 integration
+
+## Filters
+
+| Filter | Purpose |
+|--------|---------|
+| `ima_forms_validate_{form-id}` | Custom validation (cross-field, business rules) |
+| `ima_forms_bad_email_domains` | Add blocked email domains |
+| `ima_forms_email_typo_corrections` | Add typo corrections |
+
+## Default Nonce
+
+The default nonce action for `ima_forms_form()` is: `ima_forms_ajax`
+
+```php
+// In AJAX handler:
+if (!wp_verify_nonce($_POST['nonce'], 'ima_forms_ajax')) {
+    wp_send_json_error(['message' => 'Security check failed.'], 403);
+}
+```

package/plugins/ima-claude/skills/ima-forms-expert/references/validation-engine.md

@@ -0,0 +1,336 @@
+# Validation Engine - Validators-at-Registration Architecture
+
+## Contents
+
+- [Architecture Overview (v1.4.0)](#architecture-overview-v140)
+- [How Field Registration Works](#how-field-registration-works)
+- [Validation Flow](#validation-flow)
+- [Field Spec Structure](#field-spec-structure)
+- [Custom Validation via Filters](#custom-validation-via-filters)
+- [Pure Validators](#pure-validators)
+- [Enhanced Email Validator](#enhanced-email-validator)
+- [Function Factory for Performance](#function-factory-for-performance)
+- [Sanitization Patterns](#sanitization-patterns)
+- [Debug Helpers](#debug-helpers)
+
+---
+
+## Architecture Overview (v1.4.0)
+
+**Core concept**: Validators are built as closures at field registration time, not by the engine via type-switching.
+
+### Old Architecture (v1.3.0)
+```php
+// Field registered spec with type metadata
+ima_forms_register_field_spec('email', ['type' => 'email', 'required' => true, ...]);
+
+// Engine rebuilt validators based on type switching
+switch ($spec['type']) {
+    case 'email':
+        $error = ima_forms_validate_email_enhanced($value, ...);
+        // etc.
+}
+```
+
+### New Architecture (v1.4.0)
+```php
+// Field builds validators at registration time
+$validators = [];
+$validators[] = fn($v) => ima_forms_validate_required($v, $label);
+$validators[] = fn($v) => empty($v) ? null : ima_forms_validate_email_enhanced($v, $label, true);
+
+ima_forms_register_field_spec('email', [
+    'type' => 'email',
+    'validators' => $validators,  // Closures stored directly!
+]);
+
+// Engine simply iterates and runs
+foreach ($spec['validators'] as $validator) {
+    $error = $validator($value);
+    if ($error !== null) break;
+}
+```
+
+**Benefits**:
+- **Single source of truth**: Field function defines validation once
+- **No type switching**: Validators are closures, just iterate and run
+- **Testable**: Validators are pure functions captured at registration time
+- **Extensible**: Easy to add field-specific validators without touching engine
+
+---
+
+## How Field Registration Works
+
+Each field function has a `_register()` function that builds validators:
+
+```php
+function ima_forms_text_field_register(array $args): void {
+    $name = $args['name'] ?? '';
+    $label = $args['label'] ?? $name;
+    $required = $args['required'] ?? false;
+    $minlength = $args['minlength'] ?? null;
+    $maxlength = $args['maxlength'] ?? null;
+
+    // Build validators at registration time
+    $validators = [];
+
+    if ($required) {
+        $validators[] = fn($v) => ima_forms_validate_required($v, $label);
+    }
+
+    if ($minlength !== null) {
+        $validators[] = function($v) use ($label, $minlength) {
+            if (empty($v)) return null;
+            return ima_forms_validate_min_length((string) $v, (int) $minlength, $label);
+        };
+    }
+
+    if ($maxlength !== null) {
+        $validators[] = function($v) use ($label, $maxlength) {
+            if (empty($v)) return null;
+            return ima_forms_validate_max_length((string) $v, (int) $maxlength, $label);
+        };
+    }
+
+    ima_forms_register_field_spec($name, [
+        'type' => 'text',
+        'label' => $label,
+        'required' => $required,
+        'validators' => $validators,
+        'sanitize_type' => 'text',
+    ]);
+}
+```
+
+**Key insight**: The `$validators` array contains closures that capture the field's label and constraints via `use`. When the engine runs them, it just calls each closure with the value.
+
+---
+
+## Validation Flow
+
+```php
+// 1. Include template → field functions register specs + validators
+ima_forms_validate_form('templates/forms/my-form', $_POST, 'my-form');
+
+// Inside ima_forms_validate_form():
+// a) Clear registry (clean state)
+ima_forms_clear_field_specs();
+
+// b) Include template (fields register their specs + validators)
+ob_start();
+get_template_part($template_path, null, $template_args);
+ob_end_clean();
+
+// c) Get collected specs (with validators already built)
+$specs = ima_forms_get_field_specs();
+
+// d) Sanitize data based on specs
+$sanitized = ima_forms_sanitize_against_specs($specs, $data);
+
+// e) Run validators (simple iteration!)
+$errors = ima_forms_run_validators($specs, $sanitized);
+
+// f) Run custom validation filter
+$errors = apply_filters("ima_forms_validate_{$form_id}", $errors, $sanitized, $specs);
+
+// g) Return result
+return ['valid' => empty($errors), 'errors' => $errors, 'sanitized' => $sanitized];
+```
+
+---
+
+## Field Spec Structure
+
+```php
+[
+    'type' => 'email',                    // Field type (for sanitization fallback)
+    'label' => 'Email Address',           // For error messages
+    'required' => true,                   // Whether field is required
+    'enhanced_validation' => true,        // Email-specific: domain checking
+    'sanitize_type' => 'email',           // Sanitization type
+    'validators' => [                     // Array of closures!
+        fn($v) => ima_forms_validate_required($v, 'Email Address'),
+        fn($v) => empty($v) ? null : ima_forms_validate_email_enhanced($v, 'Email Address', true),
+    ],
+]
+```
+
+---
+
+## Custom Validation via Filters
+
+```php
+// Add custom validation logic (runs after field validators)
+add_filter('ima_forms_validate_my-form', function($errors, $sanitized, $specs) {
+    // Cross-field validation
+    if ($sanitized['password'] !== $sanitized['password_confirm']) {
+        $errors['password_confirm'] = 'Passwords must match.';
+    }
+
+    // Business rules
+    if (!empty($sanitized['age']) && $sanitized['age'] < 18) {
+        $errors['age'] = 'Must be 18 or older.';
+    }
+
+    return $errors;
+}, 10, 3);
+```
+
+---
+
+## Pure Validators
+
+All validators return `null` for valid, error string for invalid:
+
+```php
+function ima_forms_validate_required($value, string $label): ?string {
+    if (empty($value) && $value !== '0') {
+        return "{$label} is required.";
+    }
+    return null;
+}
+```
+
+**Available validators**:
+- `ima_forms_validate_required($value, $label)`
+- `ima_forms_validate_email($email, $label)` - Basic RFC 5322
+- `ima_forms_validate_email_enhanced($email, $label, $enhanced)` - With domain/typo checking
+- `ima_forms_validate_url($url, $label)`
+- `ima_forms_validate_phone($phone, $label)` - 10-15 digits, allows formatting
+- `ima_forms_validate_min_length($value, $min, $label)`
+- `ima_forms_validate_max_length($value, $max, $label)`
+- `ima_forms_validate_array_required($array, $label)`
+- `ima_forms_validate_numeric($value, $label)`
+- `ima_forms_validate_range($value, $min, $max, $label)`
+
+---
+
+## Enhanced Email Validator
+
+```php
+$error = ima_forms_validate_email_enhanced(
+    'user@gmial.com',  // Input
+    'Email Address',    // Label for error message
+    true               // Enable enhanced checks
+);
+// Returns: "Did you mean user@gmail.com? Please check your email address."
+```
+
+**Features**:
+- RFC 5322 format validation
+- Disposable domain blocking (20+ domains: mailinator, tempmail, etc.)
+- Common typo detection (gmial.com → gmail.com)
+
+**Customize blocked domains**:
+```php
+add_filter('ima_forms_bad_email_domains', function($domains) {
+    $domains[] = 'example-spam.com';
+    return $domains;
+});
+```
+
+**Customize typo corrections**:
+```php
+add_filter('ima_forms_email_typo_corrections', function($corrections) {
+    $corrections['customemail.co'] = 'customemail.com';
+    return $corrections;
+});
+```
+
+---
+
+## Function Factory for Performance
+
+**Pre-compile email validator** for repeated validations (2-5x faster in bulk operations):
+
+```php
+// Create validator once with configuration
+$validator = ima_forms_create_email_validator(
+    ['spam.com', 'tempmail.com'],  // Bad domains
+    ['gmial.com' => 'gmail.com']   // Typo corrections
+);
+
+// Use for multiple emails (hot path optimization)
+foreach ($emails as $email) {
+    $error = $validator($email, 'Email');
+}
+```
+
+---
+
+## Sanitization Patterns
+
+### Automatic Sanitization
+
+When using the Validation Engine, sanitization is automatic:
+
+```php
+$result = ima_forms_validate_form(...);
+// $result['sanitized'] contains sanitized data
+```
+
+### Sanitization Type Mapping
+
+```php
+function ima_forms_get_sanitize_type_for_field(array $spec): string {
+    return match ($spec['type']) {
+        'email' => 'email',
+        'url' => 'url',
+        'textarea' => 'textarea',
+        'checkbox' => 'boolean',
+        'checkbox_group' => 'checkbox_array',
+        'phone' => 'phone',
+        default => 'text',
+    };
+}
+```
+
+### Repeater Sanitization
+
+```php
+$sanitized_locations = ima_forms_sanitize_repeater(
+    $_POST['additional_locations'] ?? [],
+    ['location_name' => 'text', 'contact_email' => 'email']
+);
+```
+
+---
+
+## Debug Helpers
+
+### See Registered Specs
+
+```php
+echo ima_forms_debug_field_specs();
+// Output:
+// Registered Field Specs (4):
+//   - name: text [REQUIRED]
+//   - email: email [REQUIRED]
+//   - phone: phone
+//   - message: textarea [REQUIRED]
+```
+
+### See Validation Summary
+
+```php
+$specs = ima_forms_get_field_specs();
+echo ima_forms_debug_validation_summary($specs);
+// Output:
+// Validation Summary (4 fields):
+//   name (text, REQUIRED): [2 validator(s)]
+//   email (email, REQUIRED): [2 validator(s)]
+//   phone (phone, optional): [1 validator(s)]
+//   message (textarea, REQUIRED): [1 validator(s)]
+```
+
+### Registry Functions
+
+| Function | Purpose |
+|----------|---------|
+| `ima_forms_register_field_spec($name, $spec)` | Register a field spec |
+| `ima_forms_get_field_specs()` | Get all registered specs |
+| `ima_forms_clear_field_specs()` | Clear registry (used by engine) |
+| `ima_forms_has_field_spec($name)` | Check if field registered |
+| `ima_forms_get_field_spec($name)` | Get single spec |
+| `ima_forms_get_field_spec_count()` | Count registered specs |
+| `ima_forms_debug_field_specs()` | Human-readable spec dump |