sfcc-dev-mcp 1.0.15 → 1.0.19

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

@@ -0,0 +1,206 @@
+# 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

@@ -0,0 +1,165 @@
+# 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

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

@@ -0,0 +1,185 @@
+# Plugin Cartridge Patterns & Anti-Patterns
+
+Analysis of real patterns from plugin cartridges with concrete guidance for creating maintainable, secure, and accessible client-side code.
+
+## Observed Anti-Patterns & Risks
+
+| Category | Issue | Why It Matters | Recommended Fix |
+|----------|-------|----------------|-----------------|
+| Message UI | Repeated ad-hoc containers: `$('body').append('<div class="messages"></div>')` | Duplicated logic, memory churn, inconsistent roles, XSS risk | Centralize via `toastService.show(type, message)` with single managed region |
+| String HTML | Concatenating user data into HTML | XSS vulnerability if data not sanitized | Use `escapeHtml()` or build DOM with jQuery `.text()` |
+| Oversized Module | Single file ~600 lines exporting giant object | Hard to test, cognitive overload, hidden coupling | Split by concern into focused modules |
+| Global Delegation | Universal `$('body').on('click', '.selector', ...)` | Higher event dispatch cost; collision risk | Delegate from closest stable container |
+| No Event Namespaces | Triggers without namespaces | Difficult selective unbinding, collision risk | Use `$('...').on('click.wishlistRemove', ...)` |
+| Unscoped Spinners | `$.spinner().start()` without container scoping | Flicker, race conditions | Use `$container.spinner().start()` with `try/finally` |
+| Manual Modal Assembly | String concatenation for full modal markup | Drift vs. base styles, missing a11y attributes | Provide reusable `createModalShell()` helper |
+| Clipboard | Direct `navigator.clipboard.writeText` | Fails silently on insecure origins | Add feature detect & fallback |
+| Uncached Selectors | Repeated `$('.class')` inside loops | Performance waste | Cache at module scope before loops |
+| Icon Toggle | Direct class swap without state semantics | No accessibility state conveyed | Add `aria-pressed` or `aria-label` update |
+| Error Handling | Passing entire `err` object expecting `{success,msg}` | `undefined` outputs; user confusion | Normalize with `extractMessage(xhr)` utility |
+
+## Improved Architecture
+
+Break monolithic modules by concern:
+
+```javascript
+// wishlist/index.js (page orchestrator)
+'use strict';
+var initModal = require('./modal');
+var initPublicStatus = require('./publicStatus');
+var initItems = require('./items');
+var initSearch = require('./search');
+var toast = require('./toast');
+
+module.exports = function () {
+    toast.init();
+    initModal();
+    initPublicStatus();
+    initItems();
+    initSearch();
+};
+```
+
+## Central Toast Service
+
+```javascript
+// utils/toast.js
+'use strict';
+var REGION_SELECTOR = '#global-toast-region';
+
+function ensureRegion() {
+    if (!$(REGION_SELECTOR).length) {
+        $('body').append(
+            '<div id="global-toast-region" class="toast-region" ' +
+            'aria-live="polite" aria-atomic="true"></div>'
+        );
+    }
+}
+
+function escapeHtml(str) {
+    return String(str)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
+function show(type, message, opts) {
+    ensureRegion();
+    var safe = escapeHtml(message);
+    var $r = $(REGION_SELECTOR);
+    var $toast = $('<div class="alert alert-' + (type || 'info') + '" role="alert"></div>')
+        .html(safe);
+    $r.append($toast);
+    
+    setTimeout(function () { 
+        $toast.fadeOut(150, function () { $(this).remove(); }); 
+    }, (opts && opts.duration) || 3000);
+}
+
+module.exports = { init: ensureRegion, show: show };
+```
+
+Usage:
+```javascript
+var toast = require('./toast');
+toast.show(data.success ? 'success' : 'danger', data.msg);
+```
+
+## Namespaced Events & Scoped Delegation
+
+```javascript
+// Instead of $('body').on('click', '.remove-item', handler)
+$('.wishlist-container').on('click.wishlistRemove', '.remove-item', handler);
+
+// Add cleanup
+function destroy() { 
+    $('.wishlist-container').off('.wishlistRemove'); 
+}
+```
+
+## AJAX Utility Wrapper
+
+```javascript
+// utils/ajax.js
+module.exports = function request(opts) {
+    var d = $.Deferred();
+    
+    $.ajax(opts)
+        .done(d.resolve)
+        .fail(function (xhr) {
+            var msg = (xhr.responseJSON && (xhr.responseJSON.msg || xhr.responseJSON.message)) 
+                      || 'Unexpected error';
+            d.reject({ success: false, msg: msg });
+        });
+    
+    return d.promise();
+};
+```
+
+## Safer Dynamic List Rendering
+
+```javascript
+function renderHits(hits) {
+    var html = hits.map(function (h) {
+        var name = escapeHtml(h.firstName + ' ' + h.lastName);
+        var urlText = escapeHtml(h.urlText);
+        
+        return '<div class="row hit">' +
+            '<div class="col-6">' + name + '</div>' +
+            '<div class="col-6">' +
+            '<a href="' + h.url + '" ' +
+            'title="' + escapeHtml(h.urlTitle) + '" ' +
+            'data-id="' + h.id + '">' + urlText + '</a>' +
+            '</div></div>';
+    }).join('');
+    
+    $('.hits-container').html(html);
+}
+```
+
+## Accessibility Enhancements
+
+| Pattern | Upgrade |
+|---------|---------|
+| Heart toggle icon changes class only | Add `aria-pressed` state + label update |
+| Toasts missing live region | Use single `aria-live="polite"` container |
+| Modal close sets focus implicitly | Explicitly return focus to invoking control |
+| Copy link success only visual | Append visually-hidden status text for screen readers |
+
+## Performance & Maintainability Payoffs
+
+| Refactor | Benefit |
+|----------|---------|
+| Split mega file into 6 modules | Lower merge conflict risk; targeted test surfaces |
+| Central toast service | One place for styling, timing, a11y |
+| Namespaced events | Predictable teardown preventing memory leaks |
+| Escaping utility | Mitigates XSS across all dynamic insertions |
+| AJAX wrapper | Consistent error contract for UI handlers |
+
+## Code Review Checklist
+
+Before finalizing a new client feature:
+
+1. Does any module exceed ~200 LOC? If yes, split
+2. Are all dynamic string insertions encoded? (Search for `+` around user data)
+3. Do events have namespaces for teardown? (Search: `.on('[^']+\.`)
+4. Are repeated UX patterns (toast, modal, spinner) abstracted?
+5. Are POSTs including CSRF token & handling both transport + business errors?
+6. Is there at least one accessibility enhancement (live region, focus management, ARIA state)?
+
+## Escaping Utility
+
+```javascript
+function escapeHtml(str) {
+    return String(str)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+```
+
+Always use when inserting: query params, form input values, server-returned text fields that originated from users.