sfcc-dev-mcp 1.0.19 → 1.0.21

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

@@ -1,285 +0,0 @@
-# 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;
-    });
-}
-```

package/ai-instructions/skills/sfcc-sfra-client-side-js/references/BASE-MODULE-INDEX.md

@@ -1,206 +0,0 @@
-# Base Cartridge Module Index
-
-Complete index of SFRA base cartridge client-side modules available for extension via `paths` alias.
-
-**Total modules: 56**
-
-## Full File Listing
-
-```
-addressBook.js
-addressBook/addressBook.js
-campaignBanner.js
-carousel.js
-cart.js
-cart/cart.js
-checkout.js
-checkout/address.js
-checkout/billing.js
-checkout/checkout.js
-checkout/customer.js
-checkout/formErrors.js
-checkout/shipping.js
-checkout/summary.js
-checkoutRegistration.js
-components/cleave.js
-components/clientSideValidation.js
-components/collapsibleItem.js
-components/consentTracking.js
-components/cookie.js
-components/countrySelector.js
-components/errorNotification.js
-components/focus.js
-components/footer.js
-components/formValidation.js
-components/keyboardAccessibility.js
-components/menu.js
-components/miniCart.js
-components/scrollAnimate.js
-components/search.js
-components/spinner.js
-components/toolTip.js
-contactUs.js
-contactUs/contactUs.js
-einsteinCarousel.js
-login.js
-login/login.js
-main.js
-mobileGridLookBook.js
-orderHistory.js
-orderHistory/orderHistory.js
-paymentInstruments.js
-paymentInstruments/paymentInstruments.js
-product/base.js
-product/detail.js
-product/quickView.js
-productDetail.js
-productTile.js
-profile.js
-profile/profile.js
-search.js
-search/search.js
-storeLocator.js
-storeLocator/storeLocator.js
-thirdParty/bootstrap.js
-util.js
-```
-
-## By Category
-
-### Core Components (`components/`)
-| Module | Purpose |
-|--------|---------|
-| `cleave.js` | Input formatting (credit cards, phone) |
-| `clientSideValidation.js` | Form validation styling |
-| `collapsibleItem.js` | Accordion/collapsible UI |
-| `consentTracking.js` | Cookie consent |
-| `cookie.js` | Cookie utilities |
-| `countrySelector.js` | Country dropdown |
-| `errorNotification.js` | Error display |
-| `focus.js` | Focus management |
-| `footer.js` | Footer interactions |
-| `formValidation.js` | Form validation logic |
-| `keyboardAccessibility.js` | Keyboard navigation |
-| `menu.js` | Navigation menu |
-| `miniCart.js` | Mini cart interactions |
-| `scrollAnimate.js` | Scroll animations |
-| `search.js` | Search functionality |
-| `spinner.js` | Loading spinner |
-| `toolTip.js` | Tooltips |
-
-### Checkout (`checkout/`)
-| Module | Purpose |
-|--------|---------|
-| `address.js` | Address handling |
-| `billing.js` | Billing step |
-| `checkout.js` | Main checkout orchestrator |
-| `customer.js` | Customer info step |
-| `formErrors.js` | Checkout form errors |
-| `shipping.js` | Shipping step |
-| `summary.js` | Order summary |
-
-### Product (`product/`)
-| Module | Purpose |
-|--------|---------|
-| `base.js` | Shared product utilities |
-| `detail.js` | PDP interactions |
-| `quickView.js` | Quick view modal |
-
-### Account
-| Module | Purpose |
-|--------|---------|
-| `addressBook.js` / `addressBook/addressBook.js` | Address book management |
-| `login.js` / `login/login.js` | Login functionality |
-| `orderHistory.js` / `orderHistory/orderHistory.js` | Order history |
-| `paymentInstruments.js` / `paymentInstruments/paymentInstruments.js` | Saved payments |
-| `profile.js` / `profile/profile.js` | Profile management |
-
-### Search & Store
-| Module | Purpose |
-|--------|---------|
-| `search.js` / `search/search.js` | Search results page |
-| `storeLocator.js` / `storeLocator/storeLocator.js` | Store finder |
-
-### Cart
-| Module | Purpose |
-|--------|---------|
-| `cart.js` / `cart/cart.js` | Cart page |
-| `miniCart.js` | Mini cart dropdown |
-
-### Other
-| Module | Purpose |
-|--------|---------|
-| `campaignBanner.js` | Campaign banners |
-| `carousel.js` | Image carousels |
-| `checkoutRegistration.js` | Post-checkout registration |
-| `contactUs.js` / `contactUs/contactUs.js` | Contact form |
-| `einsteinCarousel.js` | Einstein recommendations |
-| `main.js` | Main entry point |
-| `mobileGridLookBook.js` | Mobile grid layout |
-| `productDetail.js` | PDP page orchestrator |
-| `productTile.js` | Product tile interactions |
-| `util.js` | Shared utilities |
-| `thirdParty/bootstrap.js` | Bootstrap integration |
-
-## Extension Examples
-
-### Extending a Component
-
-```javascript
-// custom/components/menu.js
-'use strict';
-var base = require('base/components/menu');
-
-var originalToggle = base.toggle;
-
-base.toggle = function () {
-    originalToggle.apply(this, arguments);
-    window.dispatchEvent(new CustomEvent('menu:toggled'));
-};
-
-module.exports = base;
-```
-
-### Extending PDP
-
-```javascript
-// custom/product/detail.js
-'use strict';
-var base = require('base/product/detail');
-
-base.customFeature = function () {
-    // New functionality
-};
-
-module.exports = base;
-```
-
-### Extending Checkout
-
-```javascript
-// custom/checkout/shipping.js
-'use strict';
-var base = require('base/checkout/shipping');
-
-var originalUpdateShippingMethod = base.updateShippingMethod;
-
-base.updateShippingMethod = function () {
-    originalUpdateShippingMethod.apply(this, arguments);
-    // Custom tracking
-};
-
-module.exports = base;
-```
-
-## Module Dependency Notes
-
-- `main.js` imports most components as the primary entry point
-- Checkout modules often import from each other
-- `product/base.js` provides shared utilities for all product modules
-- `util.js` contains helpers used across multiple modules
-
-## When NOT to Override
-
-- **Vendored code** (`thirdParty/bootstrap.js`): Wrap or extend via event hooks instead
-- **Minor changes**: Decorate after require instead of full file override
-- **Large function changes**: Extract to helper module rather than duplicating

package/ai-instructions/skills/sfcc-sfra-client-side-js/references/EXTENSION-PATTERNS.md

@@ -1,165 +0,0 @@
-# Client-Side Extension Patterns
-
-Detailed guide for extending SFRA client-side JavaScript modules using build-time composition.
-
-## The Extension Mechanism
-
-Client-side extension uses **build-time aliases**, not runtime inheritance. The `paths` configuration in `package.json` enables cross-cartridge module resolution during the webpack/sgmf-scripts build.
-
-### Critical Misconception: `module.superModule`
-
-`module.superModule` exists only on the **server** (Rhino engine) for controllers/scripts. It does **NOT** exist in browser bundles. Using it client-side throws an undefined reference error.
-
-## Extension Steps
-
-### 1. Configure `paths` Alias
-
-```jsonc
-// app_custom_mybrand/package.json
-{
-    "name": "app_custom_mybrand",
-    "scripts": {
-        "compile:js": "sgmf-scripts --compile js",
-        "compile:scss": "sgmf-scripts --compile css"
-    },
-    "paths": {
-        "base": "../storefront-reference-architecture/cartridges/app_storefront_base/"
-    }
-}
-```
-
-### 2. Require Base Module
-
-```javascript
-'use strict';
-var base = require('base/product/detail');
-```
-
-### 3. Decorate or Override
-
-Modify the `base` object by adding or replacing functions. If you need original logic, copy/refactor it—there is no automatic super call.
-
-### 4. Re-export
-
-```javascript
-module.exports = base;
-```
-
-## Full PDP Extension Example
-
-**Base (`app_storefront_base/.../product/detail.js`)**
-```javascript
-'use strict';
-function updateAddToCartButton(update) {
-    $('button.add-to-cart').attr('disabled', !update.readyToOrder || !update.available);
-}
-module.exports = { updateAddToCartButton: updateAddToCartButton };
-```
-
-**Custom (`app_custom_mybrand/.../product/detail.js`)**
-```javascript
-'use strict';
-var base = require('base/product/detail');
-
-function handleNotifyMe() {
-    console.log('Notify Me button clicked!');
-}
-
-function updateNotifyMeButton(update) {
-    if (!update.available && update.readyToOrder) {
-        $('.notify-me').show();
-    } else {
-        $('.notify-me').hide();
-    }
-}
-
-// Override base function
-base.updateAddToCartButton = function (update) {
-    $('button.add-to-cart').attr('disabled', !update.readyToOrder || !update.available);
-    updateNotifyMeButton(update);
-};
-
-// Add new function
-base.initializeNotifyMeEvent = function () {
-    $('body').on('click', '.notify-me', handleNotifyMe);
-};
-
-module.exports = base;
-```
-
-## `require()` Path Syntax Reference
-
-| Syntax       | Context                  | Purpose / Behavior                                              | Example |
-|--------------|--------------------------|------------------------------------------------------------------|---------|
-| `./` / `../` | Client & Server          | Relative to current file                                        | `require('./utils')` |
-| `~/`         | Server only (runtime)    | Current cartridge root in runtime path. Not for client build    | `require('~/cartridge/scripts/assets.js')` |
-| `*/`         | Server only (runtime)    | Searches entire cartridge path (left→right)                     | `require('*/cartridge/scripts/middleware/consentTracking')` |
-| `[alias]/`   | Client only (build-time) | Resolves via `package.json` `paths` mapping across cartridges   | `require('base/product/detail')` |
-
-## Module Design Pattern
-
-Design modules with a predictable lifecycle for clean composition:
-
-```javascript
-// product/favorites.js
-'use strict';
-var selectors = { container: '.favorites-container' };
-
-function bindEvents($root) {
-    $root.on('click.favoritesAdd', '.favorite-add', onAdd);
-}
-
-function unbindEvents($root) { 
-    $root.off('.favoritesAdd'); 
-}
-
-function onAdd(e) { 
-    /* feature logic */ 
-}
-
-module.exports = {
-    init: function () { bindEvents($(selectors.container)); },
-    destroy: function () { unbindEvents($(selectors.container)); }
-};
-```
-
-### Guidelines
-
-- Namespace every delegated event (`.featureNameAction`)
-- Export `init()` + optional `destroy()`; page orchestrator calls these
-- Keep pure logic (parsing, transforms) in separate files for unit tests
-- Avoid circular requires: one orchestrator imports leaf modules; leaves only export functions
-
-## Quick Start Template
-
-```javascript
-'use strict';
-var base = require('base/components/menu');
-
-// Preserve reference if you need original
-var originalToggle = base.toggle;
-
-base.toggle = function () {
-    originalToggle.apply(this, arguments);
-    // Custom enhancement
-    window.dispatchEvent(new CustomEvent('menu:toggled'));
-};
-
-module.exports = base;
-```
-
-## Extension Strategy by Module Type
-
-| Type | Recommended Strategy | Example |
-|------|----------------------|---------|
-| UI component (`components/*`) | Add feature then re-export base object | Override `base.open = customOpen` |
-| Page orchestrator (e.g. `product/detail.js`) | Override specific functions; add init hooks | Override `updateAddToCartButton` |
-| Form logic (`checkout/*.js`) | Split complex logic into helper modules first | Extract validation helper |
-| Accessibility (`keyboardAccessibility.js`) | Patch by progressive enhancement | Add new key handlers before export |
-| Bootstrap / vendor (`thirdParty/*`) | Avoid direct override; extend via event hooks | Wrap after requiring |
-
-## When NOT to Override
-
-- If a base module only needs minor event binding, prefer **decorating after require** instead of rewriting
-- Avoid duplicating large functions just to change a selector—refactor into a helper
-- Do not modify vendored third-party code directly—wrap or extend