@adobe-commerce/elsie 1.4.1-alpha002 → 1.4.1-alpha007

package/bin/builders/gql/index.js

@@ -1,6 +1,7 @@
 const path = require('path');
 const createOrClearDirectory = require('./createOrClearDirectory');
 const getSchemaRef = require('./getSchemaRef');
+const validate = require('./validate');
 require('dotenv').config();
 
 const generate = require('@graphql-codegen/cli').generate;
@@ -67,5 +68,30 @@ module.exports = async function generateResourceBuilder(yargs) {
         },
       });
     })
-    .demandCommand(1, 1, 'choose a command: types or mocks');
+    .command(
+        'validate',
+        'Validate GraphQL operations',
+        async (yargs) => {
+            return yargs
+                .option('source', {
+                    alias: 's',
+                    describe: 'Path to the source code containing GraphQL operations',
+                    type: 'array',
+                    string: true,
+                    demandOption: true,
+                })
+                .option('endpoints', {
+                    alias: 'e',
+                    describe: 'Path to GraphQL endpoints',
+                    type: 'array',
+                    string: true,
+                    demandOption: true,
+                });
+        },
+        async (argv) => {
+            const { source, endpoints } = argv;
+            await validate(source, endpoints);
+        },
+    )
+    .demandCommand(1, 1, 'choose a command: types, mocks or validate');
 };

package/bin/builders/gql/validate.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+const fsPromises = require('node:fs/promises');
+const path = require('node:path');
+const parser = require('@babel/parser');
+const traverse = require('@babel/traverse');
+const { getIntrospectionQuery, buildClientSchema, parse, validate } = require('graphql');
+
+async function walk(dir, collected = []) {
+    const dirents = await fsPromises.readdir(dir, { withFileTypes: true });
+
+    for (const d of dirents) {
+        const full = path.resolve(dir, d.name);
+
+        if (d.isDirectory()) {
+            // skip node_modules and “hidden” folders such as .git
+            if (d.name === 'node_modules' || d.name.startsWith('.')) continue;
+            await walk(full, collected);
+        } else if (/\.(c?m?js|ts|tsx)$/.test(d.name)) {
+            collected.push(full);
+        }
+    }
+    return collected;
+}
+
+function extractConstants(code) {
+    const ast = parser.parse(code, {
+        sourceType: 'unambiguous',
+        plugins: [
+            'typescript',
+            'jsx',
+            'classProperties',
+            'objectRestSpread',
+            'dynamicImport',
+            'optionalChaining',
+            'nullishCoalescingOperator',
+        ],
+    });
+    const found = [];
+    traverse.default(ast, {
+        VariableDeclaration(path) {
+            if (path.node.kind !== 'const') return;
+            for (const decl of path.node.declarations) {
+                const { id, init } = decl;
+                if (!init || id.type !== 'Identifier') continue;
+                let text = null;
+                switch (init.type) {
+                    case 'TemplateLiteral': {
+                        // join all raw chunks; ignores embedded ${expr} for simplicity
+                        text = init.quasis.map(q => q.value.cooked).join('');
+                        break;
+                    }
+                    case 'StringLiteral':
+                        text = init.value;
+                        break;
+                }
+                if (text) {
+                    const match = text.match(/\b(query|mutation|fragment)\b/i);
+                    if (match) {
+                        found.push(text.trim());
+                    }
+                }
+            }
+        },
+    });
+
+    return found;
+}
+
+async function fetchSchema(endpoint) {
+    const body = JSON.stringify({ query: getIntrospectionQuery() });
+    const res  = await fetch(endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body
+    });
+    if (!res.ok) throw new Error(`Introspection query failed: ${res.statusText}`);
+    const { data, errors } = await res.json();
+    if (errors?.length) throw new Error(`Server returned errors: ${JSON.stringify(errors)}`);
+    return buildClientSchema(data);
+}
+
+async function validateGqlOperations(endpoint, operation) {
+    console.log(`\nValidating against endpoint: ${endpoint}`);
+    try {
+        const document = parse(operation);
+        const errors = validate(await fetchSchema(endpoint), document);
+        if (errors.length) {
+            console.error('❌  Operation is NOT valid for this schema:');
+            errors.forEach(e => console.error('-', e.message));
+            process.exitCode = 1;
+        } else {
+            console.log('✅  Operation is valid!');
+        }
+    } catch (e) {
+        console.error(e);
+        process.exitCode = 1;
+    }
+}
+
+async function getAllOperations(directories) {
+    let fullContent = '';
+    for (const directory of directories) {
+        const files = await walk(path.resolve(directory));
+        for (const f of files) {
+            const code = await fsPromises.readFile(f, 'utf8');
+
+            let extracted;
+            try {
+                extracted = extractConstants(code);      // may throw on bad syntax
+            } catch (err) {
+                console.error(
+                    `⚠️  Skipping ${path.relative(process.cwd(), f)}\n` +
+                    `    ${err.message}`
+                );
+                continue;
+            }
+            fullContent += extracted;
+        }
+    }
+    return fullContent;
+}
+
+
+
+module.exports = async function main(sources, endpoints) {
+    for (const endpoint of endpoints) {
+        const operations = await getAllOperations(sources);
+        if (!operations) {
+            console.error('No GraphQL operations found in the specified directories.');
+            process.exitCode = 0;
+            return;
+        }
+        await validateGqlOperations(endpoint, operations);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe-commerce/elsie",
-  "version": "1.4.1-alpha002",
+  "version": "1.4.1-alpha007",
   "license": "SEE LICENSE IN LICENSE.md",
   "description": "Domain Package SDK",
   "engines": {
@@ -36,8 +36,10 @@
   },
   "dependencies": {
     "@babel/core": "^7.24.9",
+    "@babel/parser": "^7.24.0",
     "@babel/preset-env": "^7.24.8",
     "@babel/preset-typescript": "^7.24.7",
+    "@babel/traverse": "^7.24.0",
     "@chromatic-com/storybook": "^1",
     "@graphql-codegen/cli": "^5.0.0",
     "@graphql-codegen/client-preset": "^4.1.0",

package/src/components/Price/Price.tsx

@@ -9,13 +9,13 @@
 
 import { FunctionComponent } from 'preact';
 import { HTMLAttributes, useMemo } from 'preact/compat';
-import { classes } from '@adobe-commerce/elsie/lib';
+import { classes, getGlobalLocale } from '@adobe-commerce/elsie/lib';
 import '@adobe-commerce/elsie/components/Price/Price.css';
 
 export interface PriceProps
   extends Omit<HTMLAttributes<HTMLSpanElement>, 'size'> {
   amount?: number;
-  currency?: string;
+  currency?: string | null;
   locale?: string;
   formatOptions?: {
     [key: string]: any;
@@ -29,7 +29,7 @@ export interface PriceProps
 export const Price: FunctionComponent<PriceProps> = ({
   amount = 0,
   currency,
-  locale = process.env.LOCALE ?? undefined,
+  locale,
   variant = 'default',
   weight = 'bold',
   className,
@@ -39,17 +39,37 @@ export const Price: FunctionComponent<PriceProps> = ({
   size = 'small',
   ...props
 }) => {
+  // Determine the locale to use: prop locale > global locale > browser locale
+  const effectiveLocale = useMemo(() => {
+    if (locale) {
+      return locale;
+    }
+    const globalLocale = getGlobalLocale();
+    if (globalLocale) {
+      return globalLocale;
+    }
+    // Fallback to browser locale or default
+    return process.env.LOCALE && process.env.LOCALE !== 'undefined' ? process.env.LOCALE : 'en-US';
+  }, [locale]);
+
   const formatter = useMemo(
-    () =>
-      new Intl.NumberFormat(locale, {
+    () => {
+      const params: Intl.NumberFormatOptions = {
         style: 'currency',
         currency: currency || 'USD',
         // These options are needed to round to whole numbers if that's what you want.
         minimumFractionDigits: 2, // (this suffices for whole numbers, but will print 2500.10 as $2,500.1)
         maximumFractionDigits: 2, // (causes 2500.99 to be printed as $2,501)
         ...formatOptions,
-      }),
-    [locale, currency, formatOptions]
+      }
+      try {
+        return new Intl.NumberFormat(effectiveLocale, params);
+      } catch (error) {
+        console.error(`Error creating Intl.NumberFormat instance for locale ${effectiveLocale}. Falling back to en-US.`, error);
+        return new Intl.NumberFormat('en-US', params);
+      }
+    },
+    [effectiveLocale, currency, formatOptions]
   );
 
   const formattedAmount = useMemo(

package/src/components/ProductItemCard/ProductItemCard.css

@@ -23,7 +23,7 @@
 }
 
 .dropin-product-item-card__image-container {
-  overflow: visible;
+  overflow: hidden;
   width: 100%;
   height: auto;
 }
@@ -74,27 +74,6 @@
   width: 100%;
 }
 
-.dropin-product-item-card__image a:focus {
-  outline: 1px solid var(--color-neutral-400);
-  outline-offset: 1px;
-}
-
-.dropin-product-item-card__image {
-  display: inline-block;
-  border-radius: var(--border-radius-xsmall, 4px);
-  outline: none;
-}
-
-.dropin-product-item-card__image:focus-visible {
-  outline: 2px solid var(--color-interactive-focus, #005fcc);
-  outline-offset: 2px;
-  z-index: 2;
-}
-
-.dropin-product-item-card__image-container {
-  overflow: visible;
-}
-
 /* Medium (portrait tablets and large phones, 768px and up) */
 /* @media only screen and (min-width: 768px) { } */
 

package/src/docs/API/event-bus.mdx

@@ -5,48 +5,265 @@ import { Meta, Unstyled } from '@storybook/blocks';
 
 # Event Bus
 
-## Usage
+The Event Bus provides a communication system for different parts of your application to exchange messages and stay synchronized. It enables event-driven architecture for drop-ins, allowing Containers to react to changes from other Containers and communicate data changes to the storefront.
+
+## Import
+
+From drop-in project using the SDK
 
 ```ts
-// from drop-in project (SDK)
 import { events } from '@adobe-commerce/elsie/lib';
+```
+
 
-// from host site
+From integration project (storefront)
+
+```js
 import { events } from '@dropins/tools/event-bus.js';
 ```
 
-## Methods
+## Core Methods
+
+### Subscribe to Events
+
+Subscribe to events and receive notifications when they occur.
+
+```ts
+const eventListener = events.on('<event>', (payload) => {
+  // Handle the event payload
+  console.log('Event received:', payload);
+});
+
+// Stop listening to the event
+eventListener.off();
+```
 
-### Listener
+**Example:**
 ```ts
-const onEvent = events.on('<event>', (payload) => {
-  //...handle payload
+// Listen for cart updates
+const cartListener = events.on('cart/data', (cartData) => {
+  if (cartData) {
+    console.log(`Cart has ${cartData.totalQuantity} items`);
+    updateCartUI(cartData);
+  } else {
+    console.log('Cart is empty');
+    showEmptyCart();
+  }
 });
 
-// Stop listening to event
-onEvent.off();
+// Later, when you want to stop listening
+cartListener.off();
+```
+
+### Emit Events
+
+Broadcast events to all listeners across your application.
+
+```ts
+events.emit('<event>', payload);
+```
+
+**Examples:**
+```ts
+// Emit cart data
+const cartData = {
+  id: 'cart-123',
+  totalQuantity: 2,
+  items: [
+    { uid: 'item-1', quantity: 1, sku: 'PROD-001', name: 'Product Name' }
+  ]
+};
+
+events.emit('cart/data', cartData);
 ```
 
-### Emit
+### Get Last Event Payload
+
+Retrieve the most recent payload for a specific event.
+
+```ts
+const lastPayload = events.lastPayload('<event>');
+```
 
+**Example:**
 ```ts
-events.emit('<event>', <payload>);
+// Get the current cart state without waiting for an event
+const currentCart = events.lastPayload('cart/data');
+
+if (currentCart) {
+  console.log('Current cart total:', currentCart.totalQuantity);
+}
 ```
 
-### Logging
+### Enable Debug Logging
+
+Turn on console logging to debug event flow.
 
 ```ts
-// Enable logging
+// Enable logging to see all events in console
 events.enableLogger(true);
+```
 
-// Disable logging
-events.enableLogger(false);
+## Advanced Features
+
+### Eager Loading
+
+Execute the event handler immediately with the last known payload when subscribing. This is useful for getting the current state without waiting for the next event.
+
+```ts
+// Handler will execute immediately if there's a previous payload
+const listener = events.on('cart/data', (cartData) => {
+  console.log('Cart data received:', cartData);
+}, { eager: true });
 ```
 
-### Get Latest Payload
+**Use Cases:**
+- Initialize UI components with current state
+- Avoid waiting for the first event emission
+- Ensure components have the latest data on mount
+
+### Event Scoping
+
+Create namespaced events to avoid conflicts between different parts of your application.
+
+```ts
+// Subscribe to a scoped event
+const scopedListener = events.on('data/update', (data) => {
+  console.log('Scoped data received:', data);
+}, { scope: 'feature-a' });
+
+// Emit a scoped event
+events.emit('data/update', payload, { scope: 'feature-a' });
+
+// Get last payload for a scoped event
+const lastScopedData = events.lastPayload('data/update', { scope: 'feature-a' });
+```
+
+**Scoped Event Names:**
+When using scopes, the actual event name becomes `scope/event`. For example:
+- `'feature-a/data/update'` instead of `'data/update'`
+- `'module-b/user/action'` instead of `'user/action'`
+
+**Use Cases:**
+- Separate different features or modules
+- Different contexts within the same application
+- Component-specific event handling
+
+### Combining Options
+
+Use both eager loading and scoping together for powerful event handling.
 
 ```ts
-events.lastPayload('<event>'): EventPayload | undefined;
+// Subscribe to a scoped event with eager loading
+const listener = events.on('locale', (locale) => {
+  console.log('Current locale:', locale);
+}, { 
+  eager: true, 
+  scope: 'user-preferences' 
+});
 ```
 
+## Event-Driven Drop-ins
+
+The Event Bus enables drop-ins to be truly event-driven, allowing for loose coupling between components and seamless communication across the application.
+
+### Container-to-Container Communication
+
+Containers can react to changes from other Containers, enabling complex interactions without direct dependencies.
+
+```ts
+// Product Container: Emits when a product is added to cart
+function ProductContainer() {
+  const handleAddToCart = (product) => {
+    // Add to cart logic...
+    
+    // Notify other containers about the cart change
+    events.emit('cart/data', updatedCartData);
+  };
+  
+  return (
+    <button onClick={() => handleAddToCart(product)}>
+      Add to Cart
+    </button>
+  );
+}
+
+// Cart Container: Reacts to cart changes from any source
+function CartContainer() {
+  useEffect(() => {
+    const cartListener = events.on('cart/data', (cartData) => {
+      updateCartDisplay(cartData);
+      updateCartBadge(cartData.totalQuantity);
+    }, { eager: true });
+    
+    return () => cartListener.off();
+  }, []);
+  
+  return <CartDisplay />;
+}
+
+// Mini Cart Container: Also reacts to the same cart changes
+function MiniCartContainer() {
+  useEffect(() => {
+    const cartListener = events.on('cart/data', (cartData) => {
+      updateMiniCart(cartData);
+    }, { eager: true });
+    
+    return () => cartListener.off();
+  }, []);
+  
+  return <MiniCart />;
+}
+```
+
+### Storefront Communication
+
+Drop-ins can communicate data changes to the storefront, enabling seamless integration with the host application.
+
+```ts
+// Authentication Container: Notifies storefront of login/logout
+function AuthContainer() {
+  const handleLogin = (userData) => {
+    // Login logic...
+    
+    // Notify storefront of authentication change
+    events.emit('authenticated', true);
+  };
+  
+  const handleLogout = () => {
+    // Logout logic...
+    
+    // Notify storefront of authentication change
+    events.emit('authenticated', false);
+  };
+  
+  return <AuthForm onLogin={handleLogin} onLogout={handleLogout} />;
+}
+
+// Storefront can listen for authentication changes
+// This would be in the host application
+const authListener = events.on('authenticated', (isAuthenticated) => {
+  if (isAuthenticated) {
+    showUserMenu();
+    enableCheckout();
+  } else {
+    hideUserMenu();
+    disableCheckout();
+  }
+}, { eager: true });
+```
+
+
+
+## Best Practices
+
+1. **Always unsubscribe** from events when components unmount to prevent memory leaks
+2. **Use scopes** to organize events by feature or component
+3. **Enable eager loading** when you need immediate access to current state
+4. **Use descriptive event names** that clearly indicate what data they contain
+5. **Handle null/undefined payloads** gracefully in your event handlers
+6. **Enable logging during development** to debug event flow
+7. **Keep event payloads lightweight** to avoid performance issues
+8. **Document your event contracts** so other developers know what to expect
+
 </Unstyled>

package/src/docs/API/initializer.mdx

@@ -81,13 +81,9 @@ initializers.setImageParamKeys({
   extraParam: () => ['extraParam', 'extraValue'],
 });
 
-// Register Initializers
-initializers.register(pkg.initialize, {
-  langDefinitions,
+initializers.mountImmediately(pkg.initialize, {
+  langDefinitions
 });
-
-// Mount Initializers
-initializers.mount();
 ```
 
 Now, when a dropin uses the Image component to render an image with a width of 300 pixels and quality value of 0.8:
@@ -116,4 +112,70 @@ It renders the following image element:
 />
 ```
 
-In this example, the width parameter is mapped to imgWidth and the value of the quality parameter is modified and mapped to imgQuality.
+In this example, the width parameter is mapped to imgWidth and the value of the quality parameter is modified and mapped to imgQuality.
+
+## `setGlobalLocale(locale)`
+
+The `setGlobalLocale` method is part of the initializers module in the `@dropins/tools` package.
+It allows you to set a global locale for all drop-ins that use locale-sensitive components like the Price component.
+
+### Default Behavior
+
+By default, components use the browser's locale or fallback to 'en-US' if no global locale is set.
+
+### Parameters
+
+- `locale` - `string` - The locale string (e.g., 'en-US', 'es-MX', 'fr-FR', 'de-DE').
+
+### Functionality
+
+- If a global locale is set via `setGlobalLocale`, it will be used by components that support locale configuration.
+- Component-specific locale props will take precedence over the global locale.
+- If no global locale is set, components will fall back to the browser's locale or a default locale.
+
+### Usage
+
+Call the `setGlobalLocale()` function before the `mountImmediately()` function in the application layer.
+
+```javascript
+// Set global locale for consistent formatting across all drop-ins
+initializers.setGlobalLocale('fr-FR');
+
+// Register and Mount Initializers immediately
+initializers.mountImmediately(pkg.initialize, {});
+```
+
+Now, when a dropin uses the Price component without specifying a locale prop:
+
+```jsx
+<Price
+  amount={100}
+  currency="EUR"
+/>
+```
+
+It will render with the global locale (fr-FR) formatting:
+
+```html
+<span class="dropin-price dropin-price--default dropin-price--small dropin-price--bold">
+  100,00 €
+</span>
+```
+
+If the same component is used with a specific locale prop, that will take precedence:
+
+```jsx
+<Price
+  amount={100}
+  currency="EUR"
+  locale="en-US"
+/>
+```
+
+It will render with the specified locale (en-US) formatting:
+
+```html
+<span class="dropin-price dropin-price--default dropin-price--small dropin-price--bold">
+  €100.00
+</span>
+```

package/src/lib/index.ts

@@ -20,6 +20,7 @@ export * from '@adobe-commerce/elsie/lib/types';
 export * from '@adobe-commerce/elsie/lib/slot';
 export * from '@adobe-commerce/elsie/lib/vcomponent';
 export * from '@adobe-commerce/elsie/lib/image-params-keymap';
+export * from '@adobe-commerce/elsie/lib/locale-config';
 export * from '@adobe-commerce/elsie/lib/is-number';
 export * from '@adobe-commerce/elsie/lib/deviceUtils';
 export * from '@adobe-commerce/elsie/lib/get-path-value';

package/src/lib/initializer.ts

@@ -10,6 +10,7 @@
 import {
   Config,
   setImageParamsKeyMap,
+  setGlobalLocale,
 } from '@adobe-commerce/elsie/lib';
 
 type Listener = { off(): void };
@@ -51,10 +52,11 @@ export class Initializer<T> {
     };
 
     this.init = (options) => {
-      const { imageParamsKeyMap, ...rest } =
+      const { imageParamsKeyMap, globalLocale, ...rest } =
         options as any;
       this.config.setConfig({ ...this.config.getConfig(), ...rest });
       setImageParamsKeyMap(imageParamsKeyMap);
+      setGlobalLocale(globalLocale);
       return init(options);
     };
   }
@@ -75,6 +77,7 @@ export class initializers {
   static _initializers: Initializers = [];
   static _mounted: boolean = false;
   static _imageParamsKeyMap: { [key: string]: string } | undefined = undefined;
+  static _globalLocale: string | undefined = undefined;
   /**
    * Registers a new initializer. If the initializers have already been mounted,it immediately binds the event listeners and initializes the API for the new initializer.
    * @param initializer - The initializer to register.
@@ -99,10 +102,11 @@ export class initializers {
     options?: { [key: string]: any }
   ) {
     initializer.listeners?.(options);
-    await initializer.init?.({
-      imageParamsKeyMap: initializers._imageParamsKeyMap,
-      ...options,
-    });
+          await initializer.init?.({
+        imageParamsKeyMap: initializers._imageParamsKeyMap,
+        globalLocale: initializers._globalLocale,
+        ...options,
+      });
   }
 
   /**
@@ -120,6 +124,7 @@ export class initializers {
     initializers._initializers?.forEach(([initializer, options]) => {
       initializer.init?.({
         imageParamsKeyMap: initializers._imageParamsKeyMap,
+        globalLocale: initializers._globalLocale,
         ...options,
       });
     });
@@ -131,4 +136,12 @@ export class initializers {
   static setImageParamKeys(params: { [key: string]: any }) {
     initializers._imageParamsKeyMap = params;
   }
+
+  /**
+   * Sets the global locale. This locale is used by components that need consistent formatting regardless of the user's browser locale.
+   * @param locale - The locale string (e.g., 'en-US', 'es-MX', 'fr-FR').
+   */
+  static setGlobalLocale(locale: string) {
+    initializers._globalLocale = locale;
+  }
 }

package/src/lib/locale-config.ts

@@ -0,0 +1,34 @@
+/********************************************************************
+ *  Copyright 2024 Adobe
+ *  All Rights Reserved.
+ *
+ * NOTICE:  Adobe permits you to use, modify, and distribute this 
+ * file in accordance with the terms of the Adobe license agreement 
+ * accompanying it. 
+ *******************************************************************/
+
+class LocaleConfig {
+  private _locale?: string | undefined;
+
+  get locale() {
+    return this._locale;
+  }
+
+  set locale(value: typeof this._locale) {
+    this._locale = value;
+  }
+
+  public getMethods() {
+    return {
+      setLocale: (value: typeof this._locale) => {
+        this.locale = value;
+      },
+      getLocale: () => this.locale,
+    };
+  }
+}
+
+const localeConfig = new LocaleConfig();
+
+export const { setLocale: setGlobalLocale, getLocale: getGlobalLocale } =
+  localeConfig.getMethods();