sfcc-dev-mcp 1.0.15 → 1.0.19

package/ai-instructions/skills/sfcc-sfra-client-side-js/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: sfcc-sfra-client-side-js
+description: Guide for extending, structuring, validating, and optimizing client-side JavaScript in SFRA storefronts. Use when asked to build AJAX flows, form validation, DOM interactions, or client-side customizations.
+---
+
+# SFRA Client-Side JavaScript
+
+Guide for building and extending client-side functionality in SFRA storefronts.
+
+## Quick Checklist
+
+```text
+[ ] Use `paths` alias for base extension, never edit app_storefront_base
+[ ] Register assets in main request context, not remote includes
+[ ] Compose client overrides—no `module.superModule` (server-only)
+[ ] Generate controller URLs server-side; pass via `data-*`
+[ ] Always include CSRF token on POST (form.serialize() or manual)
+[ ] Cache selectors & delegate events for dynamic regions
+[ ] Batch DOM updates; debounce high-frequency handlers
+[ ] Escape dynamic data inserted into DOM (XSS prevention)
+[ ] Provide keyboard & screen reader accessible interactions
+[ ] Namespace events for clean teardown
+```
+
+## Architecture Overview
+
+SFRA separates:
+- **Server runtime resolution** (cartridge path in BM) – affects controllers, scripts, ISML
+- **Client build resolution** (compile-time `paths` aliases) – affects `client/default/`
+
+Client behavior is determined **at build time**, not by the live cartridge path.
+
+## Directory Structure
+
+```
+app_custom_mybrand/
+    cartridge/
+        client/
+            default/
+                js/           # Feature modules
+                scss/         # Sass source
+```
+
+Guidelines:
+- Never modify `app_storefront_base` directly
+- Mirror base file locations when extending
+- Group by domain (`product/`, `checkout/`)
+
+## Build Process
+
+```bash
+npm run compile:js
+npm run compile:scss
+```
+
+**Key distinction:** Changing the BM cartridge path does not affect already compiled bundles. Recompile after structural changes.
+
+## Asset Loading
+
+Register assets in ISML:
+```javascript
+assets.addJs('/js/product/detail.js');
+assets.addCss('/css/product.css');
+```
+
+**Caveat:** Assets added inside remote includes live only in that request and won't appear in the parent page.
+
+## Client-Side Extension
+
+Extension uses **build-time composition**, not runtime inheritance.
+
+### 1. Configure `paths` in `package.json`
+
+```json
+{
+    "paths": {
+        "base": "../storefront-reference-architecture/cartridges/app_storefront_base/"
+    }
+}
+```
+
+### 2. Require, Decorate, Export
+
+```javascript
+'use strict';
+var base = require('base/product/detail');
+
+// Override existing
+base.updateAddToCartButton = function (update) {
+    $('button.add-to-cart').attr('disabled', !update.readyToOrder);
+    // Custom enhancement
+};
+
+// Add new
+base.initNotifyMe = function () {
+    $('body').on('click', '.notify-me', handleNotifyMe);
+};
+
+module.exports = base;
+```
+
+**Note:** `module.superModule` does NOT exist client-side.
+
+## jQuery Best Practices
+
+### Selector Caching
+```javascript
+var $price = $('.product-price');
+$price.text('$99.99');
+$price.addClass('updated');
+```
+
+### Event Delegation
+```javascript
+// Robust (survives DOM replacement)
+$('.product-grid').on('click', '.add-to-cart', handler);
+```
+
+### Batch DOM Writes
+```javascript
+var html = products.map(p => `<li>${escapeHtml(p.name)}</li>`).join('');
+$('#product-list').html(html);
+```
+
+## AJAX Pattern
+
+```javascript
+$('#newsletter-form').on('submit', function (e) {
+    e.preventDefault();
+    var $form = $(this);
+    
+    $form.spinner().start();
+    
+    $.ajax({
+        url: $form.data('action-url'),
+        type: 'post',
+        data: $form.serialize(),  // Includes CSRF
+        success: function (data) {
+            $form.spinner().stop();
+            showMessage(data.success ? 'success' : 'danger', data.message);
+        },
+        error: function (err) {
+            $form.spinner().stop();
+            var msg = (err.responseJSON && err.responseJSON.message) || 'Error occurred';
+            showMessage('danger', msg);
+        }
+    });
+});
+```
+
+## Performance
+
+| Technique | Benefit |
+|-----------|---------|
+| Debounce typing | Reduces AJAX bursts (250-400ms) |
+| Cache selectors | Lower DOM traversal cost |
+| Build HTML in memory | Fewer reflows |
+| Event delegation | Handles dynamic content |
+
+```javascript
+function debounce(fn, wait) {
+    var t;
+    return function () {
+        clearTimeout(t);
+        var args = arguments, ctx = this;
+        t = setTimeout(function () { fn.apply(ctx, args); }, wait);
+    };
+}
+
+$('#search').on('input', debounce(fetchSuggestions, 300));
+```
+
+## Accessibility
+
+- Use semantic elements (`<button>`, `<nav>`)
+- Add `aria-live="polite"` to AJAX-updated regions
+- Manage focus on modal open/close
+- Maintain keyboard operability
+- Reflect state with ARIA (`aria-expanded`, `aria-pressed`)
+
+```javascript
+$('.filter-toggle').on('click', function () {
+    var $panel = $('#filter-panel');
+    var expanded = $(this).attr('aria-expanded') === 'true';
+    $(this).attr('aria-expanded', !expanded);
+    $panel.toggleClass('is-open', !expanded);
+    if (!expanded) { 
+        $panel.find('input,button,a').first().focus(); 
+    }
+});
+```
+
+## Security: XSS Prevention
+
+Always escape dynamic data:
+
+```javascript
+function escapeHtml(str) {
+    return String(str)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+
+// Or use jQuery
+$('<div>').text(userInput);  // Auto-escapes
+```
+
+Never trust: query params, form inputs, server-returned user data.
+
+## Module Design Pattern
+
+```javascript
+'use strict';
+var selectors = { container: '.favorites-container' };
+
+function bindEvents($root) {
+    $root.on('click.favoritesAdd', '.favorite-add', onAdd);
+}
+
+function unbindEvents($root) { 
+    $root.off('.favoritesAdd'); 
+}
+
+module.exports = {
+    init: function () { bindEvents($(selectors.container)); },
+    destroy: function () { unbindEvents($(selectors.container)); }
+};
+```
+
+Guidelines:
+- Namespace every delegated event (`.featureAction`)
+- Export `init()` + optional `destroy()`
+- Keep pure logic in separate files for testing
+
+## Form Validation Flow
+
+```text
+User Input → HTML5 check → (fail) prevent + style
+→ (pass) AJAX submit → Server re-validate → Success OR Error JSON
+→ Error: map messages → show per-field + global feedback
+```
+
+Always validate both client (UX) and server (authority).
+
+## Internationalization
+
+- Never concatenate partial Resource strings
+- Use `Resource.msgf` with placeholders
+- Avoid hard-coded punctuation in code
+
+```javascript
+var template = $('#banner').data('welcome-template'); // "Welcome, {name}!"
+$('#banner .text').text(template.replace('{name}', firstName));
+```
+
+## Testing Strategy
+
+1. **Pure utilities**: Jest unit tests (no DOM)
+2. **DOM behavior**: jsdom + jQuery
+3. **Contract tests**: Ensure extended module exports required API
+4. **A11y smoke**: Test live regions, keyboard access
+
+## Detailed References
+
+- [Extension Patterns](references/EXTENSION-PATTERNS.md) - Build-time composition, require syntax, module lifecycle
+- [AJAX, CSRF & Validation](references/AJAX-CSRF-VALIDATION.md) - Full AJAX patterns, form framework, error handling
+- [Plugin Patterns](references/PLUGIN-PATTERNS.md) - Anti-patterns, toast service, code review checklist
+- [Base Module Index](references/BASE-MODULE-INDEX.md) - All 56 base modules available for extension

package/ai-instructions/skills/sfcc-sfra-client-side-js/references/AJAX-CSRF-VALIDATION.md

@@ -0,0 +1,285 @@
+# AJAX, CSRF & Form Validation
+
+Comprehensive guide for AJAX patterns, CSRF token handling, and form validation in SFRA client-side JavaScript.
+
+## AJAX Architecture
+
+### Core Components
+
+1. **Controller route** (`server.post('Route', ...)`) returns JSON via `res.json()`
+2. **Client module** uses `$.ajax()` (or `fetch`) with serialized form data
+3. **URL generation** via `URLUtils.url('Controller-Route')` passed through `data-*` attributes
+4. **CSRF token** injected as hidden inputs; included automatically when using `form.serialize()`
+5. **Error handling**: differentiate transport errors vs. business validation (`success: false`)
+
+### Controller Example
+
+```javascript
+'use strict';
+var server = require('server');
+var Resource = require('dw/web/Resource');
+
+server.post('Subscribe', function (req, res, next) {
+    var email = req.form.email;
+    var success = !!email;
+    var message = success
+        ? Resource.msg('subscribe.success.message', 'newsletter', null)
+        : Resource.msg('subscribe.error.invalidemail', 'newsletter', null);
+
+    res.json({ success: success, message: message, submittedEmail: email });
+    return next();
+});
+
+module.exports = server.exports();
+```
+
+### ISML Form Template
+
+```html
+<form id="newsletter-form"
+      action="${URLUtils.url('Newsletter-Subscribe')}"
+      method="POST"
+      data-action-url="${URLUtils.url('Newsletter-Subscribe')}">
+    <div class="form-group">
+        <label for="newsletter-email">${Resource.msg('label.input.email', 'forms', null)}</label>
+        <input type="email" id="newsletter-email" name="email" required>
+        <div class="invalid-feedback"></div>
+    </div>
+    <input type="hidden" name="${pdict.csrf.tokenName}" value="${pdict.csrf.tokenValue}" />
+    <button type="submit" class="btn btn-primary">${Resource.msg('button.subscribe', 'newsletter', null)}</button>
+</form>
+<div class="newsletter-message" role="alert"></div>
+```
+
+### Client Module
+
+```javascript
+'use strict';
+module.exports = function () {
+    $('#newsletter-form').on('submit', function (e) {
+        e.preventDefault();
+        var $form = $(this);
+        var url = $form.data('action-url');
+        var $msg = $('.newsletter-message');
+        var $email = $('#newsletter-email');
+        
+        $form.spinner().start();
+        
+        $.ajax({
+            url: url,
+            type: 'post',
+            dataType: 'json',
+            data: $form.serialize(),
+            success: function (data) {
+                $form.spinner().stop();
+                $msg.removeClass('alert-danger')
+                    .addClass('alert-success')
+                    .text(data.message)
+                    .show();
+                $email.val('');
+            },
+            error: function (err) {
+                $form.spinner().stop();
+                var text = (err.responseJSON && err.responseJSON.message) || 'An unexpected error occurred.';
+                $msg.removeClass('alert-success')
+                    .addClass('alert-danger')
+                    .text(text)
+                    .show();
+            }
+        });
+    });
+};
+```
+
+## Concurrency & Abort
+
+Maintain reference to last in-flight XHR to avoid race conditions:
+
+```javascript
+var lastXhr = null;
+
+function fetchSuggestions(query) {
+    if (lastXhr) {
+        lastXhr.abort();
+    }
+    
+    lastXhr = $.ajax({
+        url: suggestUrl,
+        data: { q: query },
+        success: function (data) {
+            renderSuggestions(data);
+        }
+    });
+}
+```
+
+For libraries that swallow abort errors, use request tokens:
+
+```javascript
+var requestId = 0;
+
+function fetchData() {
+    var currentRequest = ++requestId;
+    
+    $.ajax({
+        url: endpoint,
+        success: function (data) {
+            if (currentRequest !== requestId) return; // Stale response
+            handleData(data);
+        }
+    });
+}
+```
+
+## Double-Click Prevention
+
+```javascript
+$('.add-to-cart').on('click', function (e) {
+    var $btn = $(this);
+    if ($btn.data('processing')) return;
+    
+    $btn.data('processing', true);
+    
+    $.ajax({
+        url: addToCartUrl,
+        // ...
+        complete: function () {
+            $btn.data('processing', false);
+        }
+    });
+});
+```
+
+## Standardized AJAX Wrapper
+
+```javascript
+function requestJSON(opts) {
+    var d = $.Deferred();
+    var xhr = $.ajax(opts);
+    
+    xhr.done(function (data) { 
+        d.resolve(normalize(data)); 
+    })
+    .fail(function (xhr) { 
+        d.reject(normalizeError(xhr)); 
+    });
+    
+    d.abort = function () { 
+        if (xhr && xhr.readyState !== 4) { 
+            xhr.abort(); 
+        } 
+    };
+    
+    return d;
+}
+
+function normalize(data) {
+    return {
+        success: data.success !== false,
+        payload: data,
+        msg: data.message || data.msg || ''
+    };
+}
+
+function normalizeError(xhr) {
+    var msg = (xhr.responseJSON && (xhr.responseJSON.msg || xhr.responseJSON.message)) 
+              || 'Unexpected error';
+    return { success: false, msg: msg };
+}
+```
+
+## Retry Decision Matrix
+
+| Failure | Retry? | Strategy |
+|---------|--------|----------|
+| Network timeout | Yes (1-2x) | Exponential backoff (300ms, 900ms) |
+| 5xx server error | Optional | Single retry; log event for monitoring |
+| 4xx validation | No | Surface messages; focus first invalid field |
+| 403 CSRF | Yes (once) | Refresh token then replay |
+
+## Form Framework & Validation
+
+### Server XML Definitions
+
+Forms are defined in `forms/default/` as the single source of truth:
+
+```xml
+<form formid="newsletter">
+    <field formid="email" 
+           type="string" 
+           mandatory="true" 
+           max-length="120" 
+           regexp="^[^@]+@[^@]+\.[^@]+$"
+           parse-error="error.parse.email" 
+           missing-error="error.missing.email" />
+</form>
+```
+
+### Validation Flow
+
+```text
+Load → User Input → HTML5 check → (If fail) prevent submit + style
+→ If pass: AJAX submit → Server re-validate → Success OR Error JSON
+→ On error: map messages → show per-field + global feedback
+```
+
+### Client & Server Synergy
+
+1. Controller: `server.forms.getForm('newsletter')` loads + binds definition
+2. Template: injects metadata (often via `data-*`)
+3. Browser: native HTML5 validation (type / required / maxlength)
+4. `clientSideValidation.js`: intercepts invalid events, adds `is-invalid` styling
+5. `form-validation.js`: enforces XML-derived rules client-side
+6. AJAX submit → server re-validates
+7. Failure: JSON payload enumerates field errors; client maps & displays
+
+### Error Display Pattern
+
+```javascript
+function displayErrors(errors, $form) {
+    // Clear previous errors
+    $form.find('.is-invalid').removeClass('is-invalid');
+    $form.find('.invalid-feedback').empty();
+    
+    // Display new errors
+    Object.keys(errors).forEach(function (fieldId) {
+        var $field = $form.find('[name="' + fieldId + '"]');
+        var $feedback = $field.siblings('.invalid-feedback');
+        
+        $field.addClass('is-invalid');
+        $feedback.text(errors[fieldId]);
+    });
+    
+    // Focus first invalid field
+    $form.find('.is-invalid:first').focus();
+}
+```
+
+## CSRF Token Handling
+
+CSRF tokens are typically injected as hidden inputs. When using `form.serialize()`, they're included automatically.
+
+For manual AJAX requests:
+
+```javascript
+var csrfToken = $('input[name="csrf_token"]').val();
+
+$.ajax({
+    url: endpoint,
+    type: 'POST',
+    data: {
+        csrf_token: csrfToken,
+        // other data
+    }
+});
+```
+
+Or fetch fresh token:
+
+```javascript
+function refreshCsrfToken() {
+    return $.get('/CSRF-Generate').then(function (data) {
+        return data.csrf;
+    });
+}
+```