ima-claude 2.9.0

package/plugins/ima-claude/skills/js-fp-wordpress/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: "js-fp-wordpress"
+description: "FP patterns for JavaScript in WordPress/Bootstrap context - ecosystem-native patterns, jQuery guidance, pure business logic"
+---
+
+# JavaScript FP - WordPress/Bootstrap
+
+Functional programming patterns for JavaScript in WordPress environments where jQuery is already loaded and Bootstrap is the UI framework.
+
+## When to Use This Skill
+
+- Building WordPress plugin/theme JavaScript
+- Need guidance on jQuery vs Vanilla JS decisions
+- Implementing pure business logic in browser JavaScript
+- Working with Gravity Forms, ACF, or other jQuery-dependent plugins
+- Creating form handlers, AJAX operations, or DOM interactions
+
+## Core Philosophy
+
+**"Use what's simple and native to the ecosystem. In WordPress, jQuery IS native."**
+
+**Key Insight**: The js-fp principle "Native patterns > FP utilities" targets AI-generated abstractions like custom `pipe()` and `curry()` functions - it does NOT mean "avoid established ecosystem libraries like jQuery."
+
+**Foundation**: This skill builds on `js-fp` core principles. Reference `../js-fp/SKILL.md` for purity, composition, dependency injection, and testing patterns.
+
+## TL;DR Decision Matrix
+
+| Context | Recommendation | Rationale |
+|---------|---------------|-----------|
+| **New isolated component** | Vanilla JS | No jQuery event coupling needed |
+| **AJAX operations** | jQuery `$.ajax` | Cleaner than `fetch` + error handling |
+| **DOM event delegation** | Either | Both work well |
+| **Integrating with WP plugins** | jQuery | Match ecosystem patterns |
+| **Animation** | CSS transitions | Neither jQuery nor vanilla JS |
+| **Pure business logic** | Vanilla JS | No DOM, fully testable |
+
+## Critical Context: WordPress Reality Check
+
+**jQuery IS guaranteed available** in WordPress because:
+1. WordPress core depends on jQuery
+2. Bootstrap 5 JavaScript works with or without jQuery
+3. Gravity Forms, ACF, and most plugins use jQuery
+4. The overhead argument is **irrelevant** - it's already loaded (0 additional bytes)
+
+### Arguments That DON'T Apply Here
+
+| Common Argument | Why It Doesn't Apply |
+|-----------------|---------------------|
+| "jQuery adds bundle size" | Already loaded - 0 additional bytes |
+| "jQuery is a dependency" | Already a core WordPress dependency |
+| "Modern browsers don't need jQuery" | True, but jQuery is still there |
+| "jQuery is slower" | Negligible for DOM operations |
+
+## Practical Guidelines
+
+### 1. Don't Rewrite Working jQuery Code
+
+**YAGNI applies**. If existing code works, leave it:
+
+```javascript
+// KEEP: Working jQuery AJAX handler
+(function($) {
+    'use strict';
+
+    $('.ima-form').on('submit', function(e) {
+        e.preventDefault();
+        var $form = $(this);
+
+        $.ajax({
+            url: imaAjax.url,
+            type: 'POST',
+            data: $form.serialize(),
+            success: function(response) {
+                $form.find('.ima-response').html(response.message);
+            }
+        });
+    });
+
+})(jQuery);
+
+// DON'T: Rewrite to vanilla "just because" - No benefit, adds risk
+```
+
+### 2. New Code: Choose Based on Context
+
+```javascript
+// jQuery: When integrating with WordPress plugins
+(function($) {
+    'use strict';
+
+    // Gravity Forms event - MUST use jQuery
+    $(document).on('gform_post_render', function(event, formId) {
+        initImaFields($('#gform_' + formId));
+    });
+
+})(jQuery);
+
+// Vanilla JS: Isolated component with no WP plugin interaction
+(function() {
+    'use strict';
+
+    class RepeaterController {
+        constructor(element) {
+            this.container = element;
+            this.template = element.querySelector('[data-repeater-template]');
+            this.init();
+        }
+
+        init() {
+            this.container.addEventListener('click', this.handleClick.bind(this));
+        }
+
+        // Pure method - no DOM side effects
+        generateRowId() {
+            return 'row_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9);
+        }
+    }
+
+    document.querySelectorAll('[data-repeater-container]').forEach(function(el) {
+        new RepeaterController(el);
+    });
+
+})();
+```
+
+### 3. Prefer Consistency Within Files
+
+```javascript
+// AVOID: Mixing jQuery and vanilla in same file
+(function($) {
+    document.querySelectorAll('.foo').forEach(function(el) {  // Vanilla
+        $(el).on('click', handler);  // jQuery - inconsistent!
+    });
+})(jQuery);
+
+// GOOD: Consistent jQuery throughout
+(function($) {
+    'use strict';
+    $('.foo').each(function() {
+        $(this).on('click', handler);
+    });
+})(jQuery);
+
+// GOOD: Consistent vanilla throughout
+(function() {
+    'use strict';
+    document.querySelectorAll('.foo').forEach(function(el) {
+        el.addEventListener('click', handler);
+    });
+})();
+```
+
+## Pure Business Logic Pattern
+
+**Rule**: Extract pure JavaScript functions from DOM-dependent code.
+
+```javascript
+(function($) {
+    'use strict';
+
+    // Pure business logic (testable without DOM)
+    function calculatePricing(quantity, unitPrice, discountPercent) {
+        var subtotal = Math.max(0, quantity) * Math.max(0, unitPrice);
+        var discountAmount = subtotal * (Math.min(100, Math.max(0, discountPercent)) / 100);
+        return {
+            subtotal: subtotal,
+            discountAmount: discountAmount,
+            total: subtotal - discountAmount
+        };
+    }
+
+    function formatCurrency(amount) {
+        return '$' + amount.toFixed(2);
+    }
+
+    // DOM wrapper (side effects isolated here)
+    function PriceCalculator($container) {
+        this.$container = $container;
+        this.$container.on('change', 'input', this.update.bind(this));
+    }
+
+    PriceCalculator.prototype.update = function() {
+        var values = {
+            quantity: parseInt(this.$container.find('#quantity').val()) || 0,
+            unitPrice: parseFloat(this.$container.find('#unit-price').val()) || 0,
+            discount: parseFloat(this.$container.find('#discount').val()) || 0
+        };
+        var pricing = calculatePricing(values.quantity, values.unitPrice, values.discount);
+        this.$container.find('#total').text(formatCurrency(pricing.total));
+    };
+
+    // Export for testing
+    if (typeof module !== 'undefined' && module.exports) {
+        module.exports = { calculatePricing: calculatePricing, formatCurrency: formatCurrency };
+    }
+
+})(jQuery);
+```
+
+## Anti-Patterns (AVOID)
+
+### Rewriting Working jQuery for No Benefit
+
+```javascript
+// DON'T: Same functionality, more code, no benefit
+// Before (working): $('.btn').on('click', handler);
+// After (unnecessary):
+document.querySelectorAll('.btn').forEach(function(btn) {
+    btn.addEventListener('click', handler);
+});
+```
+
+### Fighting the WordPress Ecosystem
+
+```javascript
+// DON'T: Ignore GF jQuery events (this won't work!)
+document.addEventListener('gform_post_render', function() {});
+
+// DO: Use jQuery for GF integration
+$(document).on('gform_post_render', function(event, formId) {});
+```
+
+### Custom FP Utilities
+
+```javascript
+// NEVER: Create custom FP utilities
+const pipe = (...fns) => x => fns.reduce((v, f) => f(v), x)
+
+// INSTEAD: Direct function calls
+function processFormData(data) {
+    var sanitized = sanitizeData(data);
+    var validated = validateData(sanitized);
+    return formatData(validated);
+}
+```
+
+## Quality Gates
+
+Before implementing JavaScript in WordPress:
+
+1. **Ecosystem check**: Does this need to interact with jQuery-based plugins (GF, ACF)?
+2. **Existing code**: Is there working code that just needs enhancement?
+3. **Pure logic**: Is business logic separated from DOM operations?
+4. **Consistency**: Is the file using one approach consistently?
+5. **Testability**: Can pure functions be tested without DOM?
+6. **YAGNI**: Are we adding complexity without clear benefit?
+
+## Reference Files
+
+Load these as needed for detailed patterns:
+
+### AJAX Patterns
+**File**: [references/ajax-patterns.md](references/ajax-patterns.md)
+**When**: Need AJAX implementation patterns
+**Contains**: jQuery $.ajax, vanilla fetch, error handling, retry patterns
+
+### Event Patterns
+**File**: [references/event-patterns.md](references/event-patterns.md)
+**When**: Need event delegation or DOMContentLoaded patterns
+**Contains**: jQuery delegation, vanilla delegation, document ready patterns
+
+### WordPress Integration
+**File**: [references/wp-integration.md](references/wp-integration.md)
+**When**: Integrating with Gravity Forms, ACF, or WordPress admin
+**Contains**: GF hooks, ACF hooks, admin JS, pure logic extraction, testing
+
+### PHP Integration
+**File**: `../php-fp-wordpress/SKILL.md`
+**When**: Need server-side integration patterns
+**Contains**: WordPress AJAX handlers, security practices, PHP/JS coordination
+
+### Core FP Principles
+**File**: `../js-fp/SKILL.md`
+**When**: Need foundational FP patterns
+**Contains**: Purity, composition, dependency injection, immutability, testing
+
+## File Organization
+
+```
+plugin-name/
+└── assets/
+    └── js/
+        ├── plugin-base.js         # jQuery - AJAX, GF integration
+        ├── plugin-admin.js        # jQuery - Admin UI interactions
+        ├── plugin-repeater.js     # Vanilla - Isolated component
+        └── pure/
+            ├── formatting.js      # Pure functions (testable)
+            └── calculations.js    # Pure functions (testable)
+```
+
+## Success Metrics
+
+- **Ecosystem Fit**: JavaScript integrates smoothly with WordPress/plugins
+- **Consistency**: Files use one approach throughout
+- **Testability**: Pure business logic has unit tests
+- **Maintainability**: Clear separation of concerns
+- **Pragmatism**: Working code not rewritten without benefit
+
+## Philosophy
+
+*"In WordPress, jQuery IS native. Use what's simple and matches the ecosystem. Separate pure business logic for testability, but don't fight the platform. Working code > ideological purity."*

package/plugins/ima-claude/skills/js-fp-wordpress/references/ajax-patterns.md

@@ -0,0 +1,192 @@
+# AJAX Patterns for WordPress
+
+WordPress AJAX patterns with jQuery and vanilla JS approaches.
+
+## Table of Contents
+
+1. [jQuery AJAX (Recommended)](#jquery-ajax-recommended)
+2. [Vanilla fetch Alternative](#vanilla-fetch-alternative)
+3. [Error Handling Patterns](#error-handling-patterns)
+
+---
+
+## jQuery AJAX (Recommended)
+
+Standard WordPress AJAX pattern with jQuery:
+
+```javascript
+(function($) {
+    'use strict';
+
+    function submitForm($form, successCallback, errorCallback) {
+        $.ajax({
+            url: imaAjax.url,
+            type: 'POST',
+            data: {
+                action: 'ima_process_form',
+                nonce: imaAjax.nonce,
+                form_data: $form.serialize()
+            },
+            beforeSend: function() {
+                $form.find('button[type="submit"]').prop('disabled', true);
+                $form.find('.ima-loading').show();
+            },
+            success: function(response) {
+                if (response.success) {
+                    successCallback(response.data);
+                } else {
+                    errorCallback(response.data || 'Unknown error');
+                }
+            },
+            error: function(xhr, status, error) {
+                errorCallback('Network error: ' + error);
+            },
+            complete: function() {
+                $form.find('button[type="submit"]').prop('disabled', false);
+                $form.find('.ima-loading').hide();
+            }
+        });
+    }
+
+    // Usage
+    $('.ima-ajax-form').on('submit', function(e) {
+        e.preventDefault();
+        var $form = $(this);
+
+        submitForm(
+            $form,
+            function(data) {
+                $form.find('.ima-response').html(data.message).removeClass('error').addClass('success');
+            },
+            function(error) {
+                $form.find('.ima-response').html(error).removeClass('success').addClass('error');
+            }
+        );
+    });
+
+})(jQuery);
+```
+
+---
+
+## Vanilla fetch Alternative
+
+Use when building isolated components without WP plugin interaction:
+
+```javascript
+(function() {
+    'use strict';
+
+    // Pure function - formats data for WordPress AJAX
+    function buildFormData(action, nonce, data) {
+        var formData = new FormData();
+        formData.append('action', action);
+        formData.append('nonce', nonce);
+
+        Object.keys(data).forEach(function(key) {
+            formData.append(key, data[key]);
+        });
+
+        return formData;
+    }
+
+    // Wrapper with side effects
+    function submitToWordPress(action, data) {
+        return fetch(imaAjax.url, {
+            method: 'POST',
+            credentials: 'same-origin',
+            body: buildFormData(action, imaAjax.nonce, data)
+        })
+        .then(function(response) {
+            if (!response.ok) {
+                throw new Error('Network response was not ok');
+            }
+            return response.json();
+        })
+        .then(function(data) {
+            if (!data.success) {
+                throw new Error(data.data || 'Unknown error');
+            }
+            return data.data;
+        });
+    }
+
+    // Usage
+    document.querySelectorAll('.ima-fetch-form').forEach(function(form) {
+        form.addEventListener('submit', function(e) {
+            e.preventDefault();
+
+            var formData = new FormData(form);
+            var data = {};
+            formData.forEach(function(value, key) {
+                data[key] = value;
+            });
+
+            submitToWordPress('ima_process_form', data)
+                .then(function(result) {
+                    form.querySelector('.ima-response').textContent = result.message;
+                })
+                .catch(function(error) {
+                    form.querySelector('.ima-response').textContent = error.message;
+                });
+        });
+    });
+
+})();
+```
+
+---
+
+## Error Handling Patterns
+
+### Centralized Error Handler
+
+```javascript
+(function($) {
+    'use strict';
+
+    var AjaxHandler = {
+        handleError: function(error, $container) {
+            var message = typeof error === 'string' ? error : 'An error occurred';
+            $container.find('.ima-response')
+                .html(message)
+                .removeClass('success')
+                .addClass('error');
+        },
+
+        handleSuccess: function(data, $container) {
+            $container.find('.ima-response')
+                .html(data.message || 'Success')
+                .removeClass('error')
+                .addClass('success');
+        }
+    };
+
+    window.ImaAjaxHandler = AjaxHandler;
+
+})(jQuery);
+```
+
+### Retry Pattern
+
+```javascript
+function ajaxWithRetry($form, maxRetries) {
+    var attempts = 0;
+
+    function attempt() {
+        attempts++;
+        return $.ajax({
+            url: imaAjax.url,
+            type: 'POST',
+            data: $form.serialize()
+        }).fail(function(xhr, status, error) {
+            if (attempts < maxRetries && status === 'timeout') {
+                return attempt();
+            }
+            throw error;
+        });
+    }
+
+    return attempt();
+}
+```

package/plugins/ima-claude/skills/js-fp-wordpress/references/event-patterns.md

@@ -0,0 +1,136 @@
+# Event Delegation Patterns
+
+Event handling patterns for WordPress JavaScript.
+
+## Table of Contents
+
+1. [jQuery Event Delegation](#jquery-event-delegation)
+2. [Vanilla Event Delegation](#vanilla-event-delegation)
+3. [DOMContentLoaded Patterns](#domcontentloaded-patterns)
+
+---
+
+## jQuery Event Delegation
+
+### Document-Level Delegation
+
+For dynamically added elements:
+
+```javascript
+(function($) {
+    'use strict';
+
+    // Delegated events - works with dynamically added elements
+    $(document).on('click', '.ima-toggle-btn', function(e) {
+        e.preventDefault();
+        var $target = $($(this).data('target'));
+        $target.toggleClass('is-visible');
+    });
+
+})(jQuery);
+```
+
+### Scoped Delegation (More Efficient)
+
+```javascript
+(function($) {
+    'use strict';
+
+    // Scoped delegation - better performance
+    $('.ima-component').on('click', '.ima-action-btn', function(e) {
+        e.preventDefault();
+        handleAction($(this).data('action'), $(this).closest('.ima-item'));
+    });
+
+})(jQuery);
+```
+
+---
+
+## Vanilla Event Delegation
+
+### Document-Level Pattern
+
+```javascript
+(function() {
+    'use strict';
+
+    // Delegated events using event bubbling
+    document.addEventListener('click', function(e) {
+        // Toggle button delegation
+        if (e.target.matches('.ima-toggle-btn') || e.target.closest('.ima-toggle-btn')) {
+            e.preventDefault();
+            var btn = e.target.closest('.ima-toggle-btn');
+            var target = document.querySelector(btn.dataset.target);
+            if (target) {
+                target.classList.toggle('is-visible');
+            }
+        }
+    });
+
+})();
+```
+
+### Scoped Delegation Pattern
+
+```javascript
+(function() {
+    'use strict';
+
+    // Scoped delegation
+    document.querySelectorAll('.ima-component').forEach(function(component) {
+        component.addEventListener('click', function(e) {
+            var actionBtn = e.target.closest('.ima-action-btn');
+            if (actionBtn) {
+                e.preventDefault();
+                var action = actionBtn.dataset.action;
+                var item = actionBtn.closest('.ima-item');
+                handleAction(action, item);
+            }
+        });
+    });
+
+})();
+```
+
+---
+
+## DOMContentLoaded Patterns
+
+### jQuery Document Ready
+
+```javascript
+// Standard WordPress pattern
+(function($) {
+    $(document).ready(function() {
+        // DOM is ready
+        initComponents();
+    });
+})(jQuery);
+
+// Shorthand (equivalent)
+jQuery(function($) {
+    initComponents();
+});
+```
+
+### Vanilla DOMContentLoaded
+
+```javascript
+(function() {
+    'use strict';
+
+    function init() {
+        initComponents();
+    }
+
+    // Handle both loading states
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', init);
+    } else {
+        // DOM already loaded (script loaded with defer or at bottom)
+        init();
+    }
+
+})();
+```