@adobe-commerce/elsie 1.3.1-alpha012 → 1.3.1-alpha013

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe-commerce/elsie",
-  "version": "1.3.1-alpha012",
+  "version": "1.3.1-alpha013",
   "license": "SEE LICENSE IN LICENSE.md",
   "description": "Domain Package SDK",
   "engines": {
@@ -27,10 +27,10 @@
   },
   "devDependencies": {
     "@adobe-commerce/event-bus": "~1.0.0",
-    "@adobe-commerce/fetch-graphql": "~1.1.0",
-    "@adobe-commerce/recaptcha": "~1.0.1",
+    "@adobe-commerce/fetch-graphql": "1.1.0-beta1",
+    "@adobe-commerce/recaptcha": "1.0.1-beta2",
     "@adobe-commerce/storefront-design": "~1.0.0",
-    "@dropins/build-tools": "~1.0.1",
+    "@dropins/build-tools": "1.0.1-beta1",
     "preact": "~10.22.1",
     "vite-plugin-banner": "^0.8.0"
   },

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/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);
 }