ima-claude 2.9.0

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

@@ -0,0 +1,328 @@
+# Complete Form Examples
+
+## Contents
+
+- [Understanding Validators-at-Registration](#understanding-validators-at-registration)
+- [Contact Form with Validation Engine](#contact-form-with-validation-engine)
+- [Form with Custom Cross-Field Validation](#form-with-custom-cross-field-validation)
+- [Testing Patterns](#testing-patterns)
+- [Anti-Patterns to Avoid](#anti-patterns-to-avoid)
+
+---
+
+## Understanding Validators-at-Registration
+
+**Key v1.4.0 Architecture**: When you call `ima_forms_email_field()`, the field's `_register()` function builds validators as closures and stores them:
+
+```php
+// What happens inside ima_forms_email_field_register():
+$validators = [];
+
+if ($required) {
+    // Validator closure captures $label via use()
+    $validators[] = fn($v) => ima_forms_validate_required($v, $label);
+}
+
+// Email format validator (only runs if value provided)
+$validators[] = function($v) use ($label, $enhanced) {
+    if (empty($v)) return null;
+    return ima_forms_validate_email_enhanced((string) $v, $label, $enhanced);
+};
+
+// Spec stores the closures directly
+ima_forms_register_field_spec($name, [
+    'type' => 'email',
+    'validators' => $validators,  // Array of closures!
+]);
+```
+
+**When validation runs** (inside `ima_forms_run_validators()`):
+```php
+foreach ($specs as $field_name => $spec) {
+    $value = $sanitized[$field_name] ?? null;
+
+    foreach ($spec['validators'] as $validator) {
+        $error = $validator($value);  // Just call the closure!
+        if ($error !== null) {
+            $errors[$field_name] = $error;
+            break;
+        }
+    }
+}
+```
+
+**Benefits**:
+- No type switching - validators are already built
+- Single source of truth - field function defines validation once
+- Testable - validators are pure functions
+
+---
+
+## Contact Form with Validation Engine
+
+### Template File
+
+```php
+// Theme: templates/forms/contact-form.php
+<?php
+if (!defined('ABSPATH')) exit;
+
+$errors = $args['errors'] ?? [];
+$data = $args['data'] ?? [];
+?>
+
+<?php
+ima_forms_form([
+    'id' => 'contact-form',
+    'action' => 'contact_form_submit',
+], function() use ($data, $errors) {
+
+    ima_forms_card(['title' => 'Contact Us'], function() use ($data, $errors) {
+
+        ima_forms_text_field([
+            'name' => 'name',
+            'label' => 'Your Name',
+            'required' => true,
+            'value' => $data['name'] ?? '',
+            'error' => $errors['name'] ?? '',
+        ]);
+
+        ima_forms_email_field([
+            'name' => 'email',
+            'label' => 'Email Address',
+            'required' => true,
+            'enhanced_validation' => true,
+            'value' => $data['email'] ?? '',
+            'error' => $errors['email'] ?? '',
+        ]);
+
+        ima_forms_textarea_field([
+            'name' => 'message',
+            'label' => 'Message',
+            'required' => true,
+            'rows' => 5,
+            'maxlength' => 1000,
+            'value' => $data['message'] ?? '',
+            'error' => $errors['message'] ?? '',
+        ]);
+
+        ima_forms_submit_button([
+            'text' => 'Send Message',
+            'processing_text' => 'Sending...',
+        ]);
+    });
+});
+?>
+```
+
+### AJAX Handler
+
+```php
+// Theme: inc/forms/contact-form.php
+
+function contact_form_ajax_handler() {
+    // Nonce verification
+    if (!wp_verify_nonce($_POST['nonce'], 'ima_forms_ajax')) {
+        wp_send_json_error(['message' => 'Security check failed.'], 403);
+    }
+
+    // Validate using template
+    $result = ima_forms_validate_form(
+        'templates/forms/contact-form',
+        $_POST,
+        'contact-form'
+    );
+
+    if (!$result['valid']) {
+        wp_send_json_error([
+            'message' => 'Please correct the errors below.',
+            'errors' => $result['errors']
+        ], 400);
+    }
+
+    // Process validated data
+    $data = $result['sanitized'];
+
+    $sent = wp_mail(
+        get_option('admin_email'),
+        'New Contact Form Submission',
+        "Name: {$data['name']}\nEmail: {$data['email']}\n\n{$data['message']}"
+    );
+
+    if (!$sent) {
+        wp_send_json_error(['message' => 'Failed to send message.'], 500);
+    }
+
+    wp_send_json_success([
+        'message' => 'Thank you! Your message has been sent.',
+        'redirect' => home_url('/thank-you/')
+    ]);
+}
+
+add_action('wp_ajax_contact_form_submit', 'contact_form_ajax_handler');
+add_action('wp_ajax_nopriv_contact_form_submit', 'contact_form_ajax_handler');
+
+// Shortcode
+add_shortcode('contact_form', function() {
+    ob_start();
+    get_template_part('templates/forms/contact-form');
+    return ob_get_clean();
+});
+```
+
+## Form with Custom Cross-Field Validation
+
+```php
+// Add custom validation via filter
+add_filter('ima_forms_validate_registration-form', function($errors, $sanitized, $specs) {
+    // Cross-field validation: passwords must match
+    if ($sanitized['password'] !== $sanitized['password_confirm']) {
+        $errors['password_confirm'] = 'Passwords must match.';
+    }
+
+    // Business rule: age requirement
+    if (!empty($sanitized['age']) && $sanitized['age'] < 18) {
+        $errors['age'] = 'Must be 18 or older to register.';
+    }
+
+    // Conditional requirement
+    if ($sanitized['specialty'] === 'Other' && empty($sanitized['specialty_other'])) {
+        $errors['specialty_other'] = 'Please specify your specialty.';
+    }
+
+    return $errors;
+}, 10, 3);
+```
+
+## Testing Patterns
+
+### Unit Tests for Validators
+
+```php
+<?php
+declare(strict_types=1);
+
+use PHPUnit\Framework\TestCase;
+
+class ValidatorTest extends TestCase {
+    /**
+     * @dataProvider emailProvider
+     */
+    public function test_validate_email_enhanced($email, $expected_valid, $expected_message) {
+        $result = ima_forms_validate_email_enhanced($email, 'Email', true);
+
+        if ($expected_valid) {
+            $this->assertNull($result);
+        } else {
+            $this->assertIsString($result);
+            if ($expected_message) {
+                $this->assertStringContainsString($expected_message, $result);
+            }
+        }
+    }
+
+    public function emailProvider() {
+        return [
+            'valid email' => ['test@example.com', true, null],
+            'disposable domain' => ['test@mailinator.com', false, 'not allowed'],
+            'gmail typo' => ['test@gmial.com', false, 'gmail.com'],
+            'invalid format' => ['not-an-email', false, 'valid'],
+        ];
+    }
+}
+```
+
+### Testing Validation Engine
+
+```php
+public function test_validation_engine_with_template() {
+    $_POST = [
+        'name' => 'Test User',
+        'email' => 'test@example.com',
+        'message' => 'Test message',
+    ];
+
+    $result = ima_forms_validate_form(
+        'templates/forms/contact-form',
+        $_POST,
+        'contact-form'
+    );
+
+    $this->assertTrue($result['valid']);
+    $this->assertEmpty($result['errors']);
+    $this->assertEquals('Test User', $result['sanitized']['name']);
+}
+```
+
+## Anti-Patterns to Avoid
+
+### ❌ Don't Skip Template-Driven Validation
+
+```php
+// ❌ WRONG - Manual field map creation
+$field_map = [
+    'name' => 'text',
+    'email' => 'email',
+    'phone' => 'phone',
+];
+$sanitized = ima_forms_sanitize_data($_POST, $field_map);
+$validation = my_manual_validation($sanitized);
+
+// ✅ CORRECT - Use Validation Engine
+$result = ima_forms_validate_form('templates/forms/my-form', $_POST, 'my-form');
+```
+
+### ❌ Don't Duplicate Validation Logic
+
+```php
+// ❌ WRONG - Manual validators when field already registers specs
+function my_form_validate($data) {
+    $errors = [];
+    if (empty($data['email'])) {
+        $errors['email'] = 'Email is required.';
+    }
+    if (!filter_var($data['email'], FILTER_VALIDATE_EMAIL)) {
+        $errors['email'] = 'Invalid email format.';
+    }
+    // ... more duplicated validation
+}
+
+// ✅ CORRECT - Let field registration handle it
+$result = ima_forms_validate_form('templates/forms/my-form', $_POST, 'my-form');
+
+// Add ONLY custom cross-field validation via filter
+add_filter('ima_forms_validate_my-form', function($errors, $data) {
+    if ($data['password'] !== $data['password_confirm']) {
+        $errors['password_confirm'] = 'Passwords must match.';
+    }
+    return $errors;
+}, 10, 2);
+```
+
+### ❌ Don't Forget Enhanced Validation
+
+```php
+// ❌ WRONG - Basic email validation for user-facing forms
+ima_forms_email_field([
+    'name' => 'email',
+    'enhanced_validation' => false,  // Misses disposable domains!
+]);
+
+// ✅ CORRECT - Use enhanced validation (default)
+ima_forms_email_field([
+    'name' => 'email',
+    'enhanced_validation' => true,  // Blocks spam domains, detects typos
+]);
+```
+
+### ❌ Don't Use Old Factory Pattern for Simple Forms
+
+```php
+// ❌ WRONG - Unnecessary factory pattern complexity
+['render' => $render, 'validate' => $validate] = ima_forms_create_form(...);
+
+// ✅ CORRECT - Use Validation Engine for simpler approach
+$result = ima_forms_validate_form('templates/forms/my-form', $_POST, 'my-form');
+```
+
+**Note**: Form factory pattern is still useful for programmatic field generation or complex dynamic validation composition.

package/plugins/ima-claude/skills/ima-forms-expert/references/field-components.md

@@ -0,0 +1,298 @@
+# Field Components Reference
+
+## Contents
+
+- [Text Input Field](#text-input-field)
+- [Email Field](#email-field)
+- [Password Field](#password-field)
+- [Hidden Field](#hidden-field)
+- [Textarea Field](#textarea-field)
+- [Select Field](#select-field)
+- [Checkbox Field](#checkbox-field)
+- [Checkbox Group](#checkbox-group)
+- [Phone Field](#phone-field)
+- [URL Field](#url-field)
+- [Address Fieldset](#address-fieldset)
+- [Consent Agreement Field](#consent-agreement-field)
+- [Repeater (Dynamic Rows)](#repeater-dynamic-rows)
+
+---
+
+All field components auto-register validation specs when rendered. Use `required => true` to enable required validation.
+
+## Text Input Field
+
+```php
+ima_forms_text_field([
+    'name' => 'field_name',
+    'label' => 'Field Label',
+    'value' => $data['field_name'] ?? '',
+    'required' => true,
+    'placeholder' => 'Enter value...',
+    'maxlength' => 100,
+    'minlength' => 3,
+    'pattern' => '[A-Za-z]+',       // HTML5 pattern
+    'wrapper_class' => 'mb-3',
+    'input_class' => 'form-control',
+    'help_text' => 'Additional guidance',
+    'error' => $errors['field_name'] ?? '',
+]);
+
+// Auto-registers: type, required, minlength, maxlength validation
+```
+
+## Email Field
+
+```php
+ima_forms_email_field([
+    'name' => 'email',
+    'label' => 'Email Address',
+    'value' => $data['email'] ?? '',
+    'required' => true,
+    'placeholder' => 'user@example.com',
+    'enhanced_validation' => true,  // Disposable domains + typo detection
+    'wrapper_class' => 'mb-3',
+    'help_text' => 'We will never share your email',
+    'error' => $errors['email'] ?? '',
+]);
+```
+
+**Enhanced validation includes**:
+- RFC 5322 format validation
+- Disposable domain blocking (mailinator, tempmail, etc.)
+- Common typo detection (gmial.com → gmail.com)
+
+## Password Field
+
+```php
+ima_forms_password_field([
+    'name' => 'password',
+    'label' => 'Password',
+    'required' => true,
+    'minlength' => 8,
+    'placeholder' => 'Enter password',
+    'wrapper_class' => 'mb-3',
+    'help_text' => 'Minimum 8 characters',
+    'error' => $errors['password'] ?? '',
+    'attributes' => [
+        'autocomplete' => 'new-password',
+    ],
+]);
+```
+
+## Hidden Field
+
+```php
+ima_forms_hidden_field([
+    'name' => 'form_id',
+    'value' => 'contact-form',
+    'label' => 'Form ID',  // For debugging only
+]);
+```
+
+## Textarea Field
+
+```php
+ima_forms_textarea_field([
+    'name' => 'message',
+    'label' => 'Message',
+    'value' => $data['message'] ?? '',
+    'required' => true,
+    'rows' => 5,
+    'maxlength' => 1000,
+    'placeholder' => 'Enter your message...',
+    'wrapper_class' => 'mb-3',
+    'error' => $errors['message'] ?? '',
+]);
+```
+
+## Select Field
+
+```php
+ima_forms_select_field([
+    'name' => 'category',
+    'label' => 'Category',
+    'value' => $data['category'] ?? '',
+    'required' => true,
+    'options' => [
+        '' => 'Select a category...',
+        'general' => 'General Inquiry',
+        'support' => 'Technical Support',
+        'sales' => 'Sales Question',
+    ],
+    'wrapper_class' => 'mb-3',
+    'error' => $errors['category'] ?? '',
+]);
+```
+
+### State Select (Pre-populated)
+
+```php
+ima_forms_state_select_field([
+    'name' => 'state',
+    'label' => 'State',
+    'value' => $data['state'] ?? '',
+    'required' => true,
+    'wrapper_class' => 'mb-3',
+    'error' => $errors['state'] ?? '',
+]);
+
+// Uses ima_forms_get_us_states() for options
+```
+
+## Checkbox Field
+
+```php
+ima_forms_checkbox_field([
+    'name' => 'subscribe',
+    'label' => 'Subscribe to newsletter',
+    'checked' => !empty($data['subscribe']),
+    'required' => false,
+    'wrapper_class' => 'mb-3',
+    'error' => $errors['subscribe'] ?? '',
+]);
+```
+
+## Checkbox Group
+
+```php
+ima_forms_checkbox_group([
+    'name' => 'interests',
+    'label' => 'Areas of Interest',
+    'values' => $data['interests'] ?? [],
+    'required' => true,
+    'options' => [
+        'web' => 'Web Development',
+        'mobile' => 'Mobile Apps',
+        'design' => 'UI/UX Design',
+        'marketing' => 'Digital Marketing',
+    ],
+    'wrapper_class' => 'mb-3',
+    'errors' => $errors['interests'] ?? '',
+]);
+```
+
+## Phone Field
+
+```php
+ima_forms_phone_field([
+    'name' => 'phone',
+    'label' => 'Phone Number',
+    'value' => $data['phone'] ?? '',
+    'required' => true,
+    'placeholder' => '(555) 123-4567',
+    'wrapper_class' => 'mb-3',
+    'error' => $errors['phone'] ?? '',
+]);
+
+// Validates: 10-15 digits, allows common formatting
+```
+
+## URL Field
+
+```php
+ima_forms_url_field([
+    'name' => 'website',
+    'label' => 'Website URL',
+    'value' => $data['website'] ?? '',
+    'required' => false,
+    'placeholder' => 'https://example.com',
+    'wrapper_class' => 'mb-3',
+    'error' => $errors['website'] ?? '',
+]);
+```
+
+## Address Fieldset
+
+Composite field that registers multiple validation specs:
+
+```php
+ima_forms_address_fieldset([
+    'name_prefix' => 'billing',  // Creates: billing_street, billing_city, etc.
+    'label' => 'Billing Address',
+    'values' => [
+        'street' => $data['billing_street'] ?? '',
+        'line2' => $data['billing_line2'] ?? '',
+        'city' => $data['billing_city'] ?? '',
+        'state' => $data['billing_state'] ?? '',
+        'zip' => $data['billing_zip'] ?? '',
+        'country' => $data['billing_country'] ?? 'United States',
+    ],
+    'required' => true,
+    'wrapper_class' => 'mb-3',
+    'errors' => $errors,  // Pass all errors, fieldset extracts relevant ones
+]);
+
+// Registers 4 specs: {prefix}_street, {prefix}_city, {prefix}_state, {prefix}_zip
+```
+
+## Consent Agreement Field
+
+Complex component with scrollable content, checkbox, and signature:
+
+```php
+// Load agreement content
+ob_start();
+include get_template_directory() . '/templates/agreements/terms-of-service.php';
+$agreement_html = ob_get_clean();
+
+ima_forms_consent_agreement_field([
+    'content_html' => $agreement_html,
+    'checkbox_name' => 'agree_to_terms',
+    'checkbox_label' => 'I have read and agree to the terms',
+    'signature_name' => 'signature',
+    'signature_label' => 'Type your full name as signature',
+    'scroll_height' => '350px',
+    'required' => true,
+    'wrapper_class' => 'mb-4',
+    'errors' => [
+        'agree_to_terms' => $errors['agree_to_terms'] ?? '',
+        'signature' => $errors['signature'] ?? '',
+    ],
+    'checkbox_value' => $_POST['agree_to_terms'] ?? null,
+    'signature_value' => $_POST['signature'] ?? '',
+]);
+```
+
+**Features**:
+- Checkbox disabled until user scrolls to bottom
+- Signature field disabled until checkbox checked
+- Auto-enqueues `ima-forms-consent.js`
+- Registers TWO validation specs (checkbox + signature)
+
+## Repeater (Dynamic Rows)
+
+```php
+ima_forms_repeater([
+    'name' => 'additional_locations',
+    'label' => 'Additional Locations',
+    'description' => 'Add multiple practice locations',
+    'min_rows' => 0,
+    'max_rows' => 10,
+    'add_button_text' => 'Add Location',
+    'values' => $data['additional_locations'] ?? [],
+    'errors' => $errors['additional_locations'] ?? [],
+], function($index, $row_data, $row_errors) {
+    // Row template - use array bracket notation
+    ima_forms_text_field([
+        'name' => "additional_locations[{$index}][location_name]",
+        'label' => 'Location Name',
+        'value' => $row_data['location_name'] ?? '',
+        'error' => $row_errors['location_name'] ?? '',
+        'wrapper_class' => 'mb-3',
+    ]);
+
+    ima_forms_text_field([
+        'name' => "additional_locations[{$index}][address]",
+        'label' => 'Address',
+        'value' => $row_data['address'] ?? '',
+        'error' => $row_errors['address'] ?? '',
+        'wrapper_class' => 'mb-3',
+    ]);
+});
+```
+
+**Features**:
+- Auto-enqueues `ima-forms-repeater.js`
+- Template placeholder uses `__INDEX__` (skipped during validation)
+- Vanilla JavaScript (no jQuery dependency)