@adobe-commerce/elsie 1.4.0-beta2 → 1.4.0-beta4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe-commerce/elsie",
-  "version": "1.4.0-beta2",
+  "version": "1.4.0-beta4",
   "license": "SEE LICENSE IN LICENSE.md",
   "description": "Domain Package SDK",
   "engines": {
@@ -26,7 +26,7 @@
     "cleanup": "rimraf dist"
   },
   "devDependencies": {
-    "@adobe-commerce/event-bus": "~1.0.0",
+    "@adobe-commerce/event-bus": "1.0.1-beta1",
     "@adobe-commerce/fetch-graphql": "~1.1.0",
     "@adobe-commerce/recaptcha": "~1.0.1",
     "@adobe-commerce/storefront-design": "~1.0.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/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();