@adobe-commerce/elsie 1.4.0-alpha1 → 1.4.0-alpha3

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.0-alpha1",
+  "version": "1.4.0-alpha3",
   "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/Button/Button.css

@@ -55,8 +55,8 @@
 }
 
 /* Primary */
-.dropin-button--primary,
-a.dropin-button--primary,
+button.dropin-button.dropin-button--primary,
+a.dropin-button.dropin-button--primary,
 .dropin-iconButton--primary {
   border: none;
   background: var(--color-brand-500) 0 0% no-repeat padding-box;
@@ -72,8 +72,8 @@ a.dropin-button--primary,
   padding: var(--spacing-xsmall);
 }
 
-.dropin-button--primary--disabled,
-a.dropin-button--primary--disabled,
+button.dropin-button.dropin-button--primary--disabled,
+a.dropin-button.dropin-button--primary--disabled,
 .dropin-iconButton--primary--disabled {
   background: var(--color-neutral-300) 0 0% no-repeat padding-box;
   color: var(--color-neutral-500);
@@ -82,21 +82,21 @@ a.dropin-button--primary--disabled,
   user-select: none;
 }
 
-.dropin-button--primary:hover,
-a.dropin-button--primary:hover,
+button.dropin-button.dropin-button--primary:hover,
+a.dropin-button.dropin-button--primary:hover,
 .dropin-iconButton--primary:hover,
-.dropin-button--primary:focus:hover,
+button.dropin-button.dropin-button--primary:focus:hover,
 .dropin-iconButton--primary:focus:hover {
   background-color: var(--color-button-hover);
   text-decoration: none;
 }
 
-.dropin-button--primary:focus,
+button.dropin-button.dropin-button--primary:focus,
 .dropin-iconButton--primary:focus {
   background-color: var(--color-brand-500);
 }
 
-.dropin-button--primary:hover:active,
+button.dropin-button.dropin-button--primary:hover:active,
 .dropin-iconButton--primary:hover:active {
   background-color: var(--color-button-active);
 }

package/src/components/Icon/Icon.tsx

@@ -2,9 +2,9 @@
  *  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. 
+ * NOTICE:  Adobe permits you to use, modify, and distribute this
+ * file in accordance with the terms of the Adobe license agreement
+ * accompanying it.
  *******************************************************************/
 
 import { FunctionComponent } from 'preact';
@@ -86,7 +86,13 @@ function isValidUrl(source: string): boolean { // check for URL from same domain
     if (source.startsWith('//')) {
       const absoluteUrl = `${window.location.protocol}${source}`;
       const url = new URL(absoluteUrl);
-      return url.hostname === window.location.hostname;
+      if (url.hostname !== window.location.hostname) {
+        console.error(
+          `[Icon] External URL rejected for security: ${source} - Only same-domain URLs are allowed`
+        );
+        return false;
+      }
+      return true;
     }
     const url = new URL(source);
     
@@ -225,7 +231,14 @@ export function Icon({
     viewBox,
   };
 
-  if (typeof Source === 'string' && isValidUrl(Source)) {
+  // Only validate strings that look like URLs (start with http, //, or /)
+  const isLikelyUrl =
+    typeof Source === 'string' &&
+    (Source.startsWith('http') ||
+      Source.startsWith('//') ||
+      Source.startsWith('/'));
+
+  if (isLikelyUrl && isValidUrl(Source)) {
     return (
       <Suspense fallback={<svg {...props} {...defaultProps} />}>
         <UrlSvgLoader url={Source} {...props} {...defaultProps}/>
@@ -237,8 +250,7 @@ export function Icon({
     ? lazyIcons[Source as IconType]
     : null;
 
-  const isRejectedUrl = typeof Source === 'string' && 
-    (Source.startsWith('http') || Source.startsWith('//') || Source.startsWith('/'));
+  const isRejectedUrl = isLikelyUrl && !isValidUrl(Source);
 
   return (
     <Suspense fallback={<svg {...props} {...defaultProps} />}>

package/src/components/Modal/Modal.stories.tsx

@@ -12,6 +12,7 @@ import { Modal as component, ModalProps } from './Modal';
 import { useState } from 'preact/hooks';
 import { Button } from '../Button';
 import { expect, userEvent, within, waitFor } from '@storybook/test';
+import { useText } from '@adobe-commerce/elsie/i18n';
 
 const meta: Meta<ModalProps> = {
   title: 'Components/Modal',
@@ -269,4 +270,65 @@ export const OverflowingTitle: Story = {
   },
 };
 
+const LocalizedContent = () => {
+  const translations = useText({
+    label: 'Dropin.ExampleComponentName.item.label',
+  });
+
+  console.log(translations.label);
+  return <div>{translations.label}</div>;
+};
+
+/**
+ * ```ts
+ * import { Modal } from '@/elsie/components/Modal';
+ * import { useText } from '@adobe-commerce/elsie/i18n';
+ *
+ * const label = useText(`Dropin.ExampleComponentName.item.label`).label;
+ *
+ * <Modal size="medium" title={<h3>Localized Modal</h3>}>
+ *      <div>{label}</div>
+ * </Modal>
+ * ```
+ */
+
+export const LocalizedModal: Story = {
+  args: {
+    size: 'medium',
+    children: <LocalizedContent />,
+    title: <h3>Localized Modal</h3>,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole('button'));
+
+    const portalRoot = await waitFor(() => {
+      const root = document.querySelector('[data-portal-root]') as HTMLDivElement;
+      expect(root).toBeTruthy();
+      return root;
+    });
+
+    await expect(portalRoot).toBeVisible();
+
+    const modal = document.querySelector(
+      '.dropin-modal__body'
+    ) as HTMLDivElement;
+
+    await expect(modal).toBeVisible();
+
+    expect(portalRoot.querySelector('h3')?.innerText).toBe('Localized Modal');
+    expect((portalRoot.querySelector('.dropin-modal__body') as HTMLElement)?.innerText).toContain('string');
+
+    const closeButton = document.querySelector(
+      '.dropin-modal__header-close-button'
+    ) as HTMLButtonElement;
+
+    await userEvent.click(closeButton);
+
+    await expect(modal).not.toBeVisible();
+
+    await expect(canvas.getByText('Open Modal')).toBeVisible();
+  },
+};
+
 export default meta;

package/src/components/Portal/Portal.tsx

@@ -7,8 +7,8 @@
  * accompanying it. 
  *******************************************************************/
 
-import { ComponentChildren, render } from 'preact';
-import { FunctionComponent, useEffect, useRef } from 'preact/compat';
+import { ComponentChildren } from 'preact';
+import { FunctionComponent, useLayoutEffect, useRef } from 'preact/compat';
 
 interface PortalProps {
   children: ComponentChildren;
@@ -16,28 +16,34 @@ interface PortalProps {
 
 export const Portal: FunctionComponent<PortalProps> = ({ children }) => {
   const portalRoot = useRef<HTMLDivElement | null>(null);
+  const contentRef = useRef<HTMLDivElement | null>(null);
 
-  useEffect(() => {
+  useLayoutEffect(() => {
     // Create portal root if it doesn't exist
     if (!portalRoot.current) {
       portalRoot.current = document.createElement('div');
       portalRoot.current.setAttribute('data-portal-root', '');
-      portalRoot.current.classList.add('dropin-design');
       document.body.appendChild(portalRoot.current);
     }
 
-    // Render children into portal root
-    render(children, portalRoot.current);
+    // Move content to portal root
+    if (contentRef.current && portalRoot.current) {
+      portalRoot.current.appendChild(contentRef.current);
+    }
 
     // Cleanup
     return () => {
       if (portalRoot.current) {
-        render(null, portalRoot.current);
         portalRoot.current.remove();
         portalRoot.current = null;
       }
     };
-  }, [children]);
+  }, []);
 
-  return null;
+  // Return a div that contains the children
+  return (
+    <div ref={contentRef} className="dropin-design">
+      {children}
+    </div>
+  );
 }; 

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/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/aem/assets.ts

@@ -1,56 +1,102 @@
-import { provider as UI, Image } from '@adobe-commerce/elsie/components';
+import {
+  provider as UI,
+  Image,
+  type ImageProps,
+} from '@adobe-commerce/elsie/components';
+
 import { getConfigValue } from '@adobe-commerce/elsie/lib/aem/configs';
+import type { ResolveImageUrlOptions } from '../resolve-image';
 
-interface AemAssetsParams {
-  quality?: number;
-  format?: string;
-  crop?: {
-    xOrigin?: number;
-    yOrigin?: number;
-    width?: number;
-    height?: number;
-  };
-  size?: {
-    width?: number;
-    height?: number;
-  };
+const AEM_ASSETS_FORMATS = ['gif', 'jpg', 'jpeg', 'png', 'webp'] as const;
+const AEM_ASSETS_ALLOWED_ROTATIONS = [90, 180, 270] as const;
+const AEM_ASSETS_ALLOWED_FLIPS = ['h', 'v', 'hv'] as const;
+
+/** The allowed formats for the `AEM Assets` image optimization API. */
+export type AemAssetsFormat = (typeof AEM_ASSETS_FORMATS)[number];
+
+/** The allowed rotations for the `AEM Assets` image optimization API. */
+export type AemAssetsRotation = (typeof AEM_ASSETS_ALLOWED_ROTATIONS)[number];
+
+/** The allowed flips for the `AEM Assets` image optimization API. */
+export type AemAssetsFlip = (typeof AEM_ASSETS_ALLOWED_FLIPS)[number];
+
+/**
+ * Defines a crop region of an image.
+ * @example
+ * ```ts
+ * // Crop the image to a 80% width and height, starting at 10% from the top and left.
+ * const cropSettings: AemAssetsCropSettings = {
+ *   xOrigin: 10,
+ *   yOrigin: 10,
+ *   width: 80,
+ *   height: 80,
+ * };
+ */
+export interface AemAssetsCropSettings {
+  /** The (relative) x origin of the crop (between 0 and 100) */
+  xOrigin?: number;
+
+  /** The (relative) y origin of the crop (between 0 and 100) */
+  yOrigin?: number;
+
+  /** The width of the crop (between 0 and 100) */
   width?: number;
+
+  /** The height of the crop (between 0 and 100) */
   height?: number;
-  [key: string]: any;
 }
 
-interface AemAssetsImageConfig {
-  wrapper?: HTMLElement;
+/**
+ * The parameters accepted by the `AEM Assets` image optimization API.
+ * @see https://adobe-aem-assets-delivery-experimental.redoc.ly/
+ */
+export interface AemAssetsParams {
+  format: AemAssetsFormat;
+  rotate?: AemAssetsRotation;
+  flip?: AemAssetsFlip;
+  crop?: AemAssetsCropSettings;
+
+  width?: number;
+  height?: number;
+  quality?: number;
+
+  attachment?: boolean;
+  sharpen?: boolean;
+  blur?: number;
+  dpr?: number;
+  smartCrop?: string;
+
+  // For future updates we may miss.
+  [key: string]: unknown;
+}
+
+type WithRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] };
+
+/** The parameters to be applied to the asset (known width required when using a slot) */
+export type AemAssetsImageSlotConfigParams = WithRequired<
+  Partial<AemAssetsParams>,
+  'width'
+>;
+
+/** The configuration for an image slot. */
+export interface AemAssetsImageSlotConfig {
+  /** The alias (i.e. seoName) of the image */
   alias: string;
-  params: AemAssetsParams;
-  imageProps: {
+
+  /** The props to be applied to the underlying {@link Image} component */
+  imageProps: Partial<Omit<ImageProps, 'params' | 'width' | 'height'>> & {
     src: string;
-    width?: number;
-    height?: number;
-    [key: string]: any;
   };
-  src?: string;
-}
-
-interface RenderContext {
-  replaceWith: (element: HTMLElement) => void;
-}
 
-export function isAemAssetsEnabled(): boolean {
-  const config = getConfigValue('commerce-assets-enabled');
+  /** The parameters to be applied to the asset (known width required when using a slot) */
+  params: AemAssetsImageSlotConfigParams;
 
-  return config && (
-    (typeof config === 'string' && config.toLowerCase() === 'true')
-    || (typeof config === 'boolean' && config === true)
-  );
+  /** The element that will contain the image in the slot */
+  wrapper?: HTMLElement;
 }
 
-export function getDefaultAemAssetsOptimizationParams(): { quality: number; format: string } {
-  // See: https://adobe-aem-assets-delivery-experimental.redoc.ly/
-  return {
-    quality: 80,
-    format: 'webp',
-  };
+interface RenderContext {
+  replaceWith: (element: HTMLElement) => void;
 }
 
 /**
@@ -64,13 +110,59 @@ function normalizeUrl(url: string): string {
   if (imageUrl.startsWith('//')) {
     // Use current window's protocol.
     const { protocol } = window.location;
-    console.log('protocol', protocol);
     imageUrl = protocol + imageUrl;
   }
 
   return imageUrl;
 }
 
+/** Returns whether the given value is a valid flip. */
+function isValidFlip(flip: unknown): flip is AemAssetsFlip {
+  return AEM_ASSETS_ALLOWED_FLIPS.includes(flip as AemAssetsFlip);
+}
+
+/** Returns whether the given value is a valid rotation. */
+function isValidRotation(rotation: unknown): rotation is AemAssetsRotation {
+  return AEM_ASSETS_ALLOWED_ROTATIONS.includes(rotation as AemAssetsRotation);
+}
+
+/** Returns whether the given value is a valid format. */
+function isValidFormat(format: unknown): format is AemAssetsFormat {
+  return AEM_ASSETS_FORMATS.includes(format as AemAssetsFormat);
+}
+
+/** Asserts that the given value is valid. */
+function assertUnionParameter(
+  value: unknown,
+  validator: (value: unknown) => boolean,
+  errorMessage: string
+): void {
+  if (value !== undefined && !validator(value)) {
+    throw new Error(errorMessage);
+  }
+}
+
+/** Returns whether AEM Assets is enabled in the Storefront. */
+export function isAemAssetsEnabled(): boolean {
+  const config = getConfigValue('commerce-assets-enabled');
+
+  return (
+    config &&
+    ((typeof config === 'string' && config.toLowerCase() === 'true') ||
+      (typeof config === 'boolean' && config === true))
+  );
+}
+
+/** The default optimization parameters used globally, unless overriden (per use). */
+export function getDefaultAemAssetsOptimizationParams(): AemAssetsParams {
+  // See: https://adobe-aem-assets-delivery-experimental.redoc.ly/
+  return {
+    quality: 80,
+    format: 'webp',
+  };
+}
+
+/** Returns true if the given URL is an AEM Assets URL. */
 export function isAemAssetsUrl(url: string | URL): boolean {
   const assetsUrl = typeof url === 'string' ? new URL(normalizeUrl(url)) : url;
 
@@ -81,19 +173,30 @@ export function isAemAssetsUrl(url: string | URL): boolean {
   return true;
 }
 
-export function generateAemAssetsOptimizedUrl(url: string, alias: string, params: AemAssetsParams = {}): string {
+/** Generates an optimized URL for AEM Assets. */
+export function generateAemAssetsOptimizedUrl(
+  assetUrl: string,
+  alias: string,
+  params: Partial<AemAssetsParams> = {}
+): string {
   const defaultParams = getDefaultAemAssetsOptimizationParams();
   const mergedParams: AemAssetsParams = { ...defaultParams, ...params };
 
-  // Destructure the ones that need special handling
-  const {
-    format,
-    crop,
-    size,
-    ...optimizedParams
-  } = mergedParams;
+  // Destructure the ones that need special handling/validation.
+  const { format, crop, ...optimizedParams } = mergedParams;
+  assertUnionParameter(format, isValidFormat, 'Invalid format');
+  assertUnionParameter(optimizedParams.flip, isValidFlip, 'Invalid flip');
+  assertUnionParameter(
+    optimizedParams.rotate,
+    isValidRotation,
+    'Invalid rotation'
+  );
+
+  const stringifiedParams = Object.fromEntries(
+    Object.entries(optimizedParams).map(([key, value]) => [key, String(value)])
+  );
 
-  const searchParams = new URLSearchParams(optimizedParams);
+  const searchParams = new URLSearchParams(stringifiedParams);
 
   if (crop) {
     const [xOrigin, yOrigin] = [crop.xOrigin || 0, crop.yOrigin || 0];
@@ -103,87 +206,112 @@ export function generateAemAssetsOptimizedUrl(url: string, alias: string, params
     searchParams.set('crop', cropTransform);
   }
 
-  // Both values must be present
-  if (size && size.width && size.height) {
-    searchParams.set('size', `${size.width},${size.height}`);
-  }
-
-  return `${url}/as/${alias}.${format}?${searchParams.toString()}`;
+  return `${assetUrl}/as/${alias}.${format}?${searchParams.toString()}`;
 }
 
-export function tryGenerateAemAssetsOptimizedUrl(url: string, alias: string, params: AemAssetsParams = {}): string {
+/**
+ * Tries to generate an optimized URL for AEM Assets. Returns the given
+ * url if AEM Assets is not enabled or is not an AEM Assets URL.
+ */
+export function tryGenerateAemAssetsOptimizedUrl(
+  assetUrl: string,
+  alias: string,
+  params: Partial<AemAssetsParams> = {}
+): string {
   const assetsEnabled = isAemAssetsEnabled();
 
-  if (!(assetsEnabled)) {
+  if (!assetsEnabled) {
     // No-op, doesn't do anything.
-    return url;
+    return assetUrl;
   }
 
-  const assetsUrl = new URL(normalizeUrl(url));
+  const assetsUrl = new URL(normalizeUrl(assetUrl));
 
   if (!isAemAssetsUrl(assetsUrl)) {
     // Not an AEM Assets URL, so no-op.
-    return url;
+    return assetUrl;
   }
 
   const base = assetsUrl.origin + assetsUrl.pathname;
   return generateAemAssetsOptimizedUrl(base, alias, params);
 }
 
-export function makeAemAssetsImageSlot(
-  config: AemAssetsImageConfig,
-) {
+/** Creates a slot that renders an AEM Assets image. */
+export function makeAemAssetsImageSlot(config: AemAssetsImageSlotConfig) {
   return (ctx: RenderContext) => {
-    const {
-      wrapper,
-      alias,
-      params,
-      imageProps,
-      src,
-    } = config;
+    const { wrapper, alias, params, imageProps } = config;
+
+    if (!imageProps.src) {
+      throw new Error(
+        'An image source is required. Please provide a `src` or `imageProps.src`.'
+      );
+    }
 
     const container = wrapper ?? document.createElement('div');
-    const imageSrc = generateAemAssetsOptimizedUrl(src || imageProps.src, alias, params);
+    const imageSrc = generateAemAssetsOptimizedUrl(
+      imageProps.src,
+      alias,
+      params
+    );
+
+    const imageComponentParams: ResolveImageUrlOptions = {
+      width: params.width,
+      height: params.height,
 
-    UI.render(Image as any, {
+      // If this is not done, they will be applied by default.
+      // And they are not compatible with the AEM Assets API.
+      crop: undefined,
+      fit: undefined,
+      auto: undefined,
+    };
+
+    const imageComponentProps: ImageProps = {
       ...imageProps,
+      width: params.width,
+      height: params.height,
 
       src: imageSrc,
-      params: {
-        width: params.width,
-
-        // If not null, they will be applied by default.
-        // And they are not compatible with the AEM Assets API.
-        crop: null,
-        fit: null,
-        auto: null,
-      },
-    })(container);
+      params: imageComponentParams,
+    };
 
+    UI.render(Image, imageComponentProps)(container);
     ctx.replaceWith(container);
   };
 }
 
-export function tryRenderAemAssetsImage(ctx: RenderContext, config: AemAssetsImageConfig): void {
+export function tryRenderAemAssetsImage(
+  ctx: RenderContext,
+  config: AemAssetsImageSlotConfig
+): void {
   // Renders an equivalent of the default image.
   function renderDefaultImage(): void {
     const container = config.wrapper ?? document.createElement('div');
-    const { imageProps } = config;
+    const { imageProps, params } = config;
+    const imageComponentProps: ImageProps = {
+      ...imageProps,
+      width: params.width,
+      height: params.height,
+    };
 
-    (UI.render as any)(Image, imageProps)(container);
+    UI.render(Image, imageComponentProps)(container);
     ctx.replaceWith(container);
   }
 
   const assetsEnabled = isAemAssetsEnabled();
 
-  if (!(assetsEnabled)) {
+  if (!assetsEnabled) {
     // No-op, render the default image.
     renderDefaultImage();
     return;
   }
 
-  const { imageProps, src, ...slotConfig } = config;
-  const assetsUrl = new URL(normalizeUrl(src ?? imageProps.src));
+  if (!config.imageProps.src) {
+    throw new Error(
+      'An image source is required. Please provide a `src` or `imageProps.src`.'
+    );
+  }
+
+  const assetsUrl = new URL(normalizeUrl(config.imageProps.src));
 
   if (!isAemAssetsUrl(assetsUrl)) {
     // Not an AEM Assets URL, so render the default image.
@@ -191,17 +319,5 @@ export function tryRenderAemAssetsImage(ctx: RenderContext, config: AemAssetsIma
     return;
   }
 
-  makeAemAssetsImageSlot({
-    // Use the default image props for params and src.
-    // Unless overriden by the slot config.
-    src: assetsUrl.toString(),
-    params: {
-      width: imageProps.width,
-      height: imageProps.height,
-      ...slotConfig.params,
-    },
-    imageProps,
-    alias: slotConfig.alias,
-    wrapper: slotConfig.wrapper,
-  })(ctx);
+  makeAemAssetsImageSlot(config)(ctx);
 }

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();