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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe-commerce/elsie",
-  "version": "1.3.1-alpha013",
+  "version": "1.3.1-alpha014",
   "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-beta1",
-    "@adobe-commerce/recaptcha": "1.0.1-beta2",
+    "@adobe-commerce/fetch-graphql": "~1.1.0",
+    "@adobe-commerce/recaptcha": "~1.0.1",
     "@adobe-commerce/storefront-design": "~1.0.0",
-    "@dropins/build-tools": "1.0.1-beta1",
+    "@dropins/build-tools": "~1.0.1",
     "preact": "~10.22.1",
     "vite-plugin-banner": "^0.8.0"
   },

package/src/components/Button/Button.css

@@ -55,8 +55,8 @@
 }
 
 /* Primary */
-button.dropin-button.dropin-button--primary,
-a.dropin-button.dropin-button--primary,
+.dropin-button--primary,
+a.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.dropin-button--primary,
   padding: var(--spacing-xsmall);
 }
 
-button.dropin-button.dropin-button--primary--disabled,
-a.dropin-button.dropin-button--primary--disabled,
+.dropin-button--primary--disabled,
+a.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.dropin-button--primary--disabled,
   user-select: none;
 }
 
-button.dropin-button.dropin-button--primary:hover,
-a.dropin-button.dropin-button--primary:hover,
+.dropin-button--primary:hover,
+a.dropin-button--primary:hover,
 .dropin-iconButton--primary:hover,
-button.dropin-button.dropin-button--primary:focus:hover,
+.dropin-button--primary:focus:hover,
 .dropin-iconButton--primary:focus:hover {
   background-color: var(--color-button-hover);
   text-decoration: none;
 }
 
-button.dropin-button.dropin-button--primary:focus,
+.dropin-button--primary:focus,
 .dropin-iconButton--primary:focus {
   background-color: var(--color-brand-500);
 }
 
-button.dropin-button.dropin-button--primary:hover:active,
+.dropin-button--primary:hover:active,
 .dropin-iconButton--primary:hover:active {
   background-color: var(--color-button-active);
 }

package/src/components/Icon/Icon.stories.tsx

@@ -14,8 +14,13 @@ import * as Icons from '@adobe-commerce/elsie/icons';
 
 /**
  * Use Icons as symbols or metaphors to communicate and enhance the user experience.
+ * 
+ * The Icon component supports three source types:
+ * - Direct component imports
+ * - Icon names from the built-in icon set
+ * - SVGs from URLs (supports URLs that match the host domain)
  */
-const meta: Meta<IconProps> = {
+const meta: Meta<StoryIconProps> = {
   title: 'Components/Icon',
   component: Icon,
   argTypes: {
@@ -25,6 +30,13 @@ const meta: Meta<IconProps> = {
       control: {
         type: 'select',
       },
+      description: 'Select a built-in icon',
+    },
+    url: {
+      control: {
+        type: 'text',
+      },
+      description: 'Or enter a URL to an external SVG (this takes priority over icon selection)',
     },
     size: {
       control: 'select',
@@ -33,6 +45,7 @@ const meta: Meta<IconProps> = {
     stroke: {
       control: 'select',
       options: ['1', '2', '3', '4'],
+      description: 'Stroke width. Works only for stroke-based icons.',
     },
     title: {
       control: 'text',
@@ -43,7 +56,11 @@ const meta: Meta<IconProps> = {
 
 export default meta;
 
-type Story = StoryObj<IconProps>;
+type Story = StoryObj<StoryIconProps>;
+
+interface StoryIconProps extends IconProps {
+  url?: string;
+}
 
 /**
  * ```ts
@@ -52,23 +69,26 @@ type Story = StoryObj<IconProps>;
  */
 
 export const Primary: Story = {
+  render: ({ url, source, ...args }: StoryIconProps) => {
+    const iconSource = url || source;
+    return <Icon {...args} source={iconSource as any} />;
+  },
   args: {
     source: Cart,
   },
 };
 
 export const Lazy: Story = {
-  argTypes: {
-    source: {
-      mapping: Object.keys(Icons),
-    },
+  render: ({ url, source, ...args }: StoryIconProps) => {
+    const iconSource = url || source;
+    return <Icon {...args} source={iconSource as any} />;
   },
   args: {
     source: 'Cart',
   },
 };
 
-export const AllIcons: Story = {
+export const AllBuiltInIcons: Story = {
   argTypes: {
     style: Object
   },
@@ -96,3 +116,72 @@ export const AllIcons: Story = {
     </div>
   ),
 };
+
+
+export const UrlExamples: Story = {
+  render: ({ url, ...args }: StoryIconProps) => (
+    <div style={{ 
+      display: 'grid', 
+      gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))', 
+      gap: '2rem',
+      padding: '1rem'
+    }}>
+      <div style={{
+        border: '1px solid #e1e5e9',
+        borderRadius: '8px',
+        padding: '1.5rem',
+        textAlign: 'center',
+        backgroundColor: '#f8f9fa'
+      }}>
+        <h3 style={{ margin: '0 0 1rem 0', color: '#2c3e50' }}>✅ Valid URL</h3>
+        <Icon 
+          source={url || `${window.location.origin}/favicon.svg`}
+          size="12"
+          title="logo icon from common domain"
+          aria-label="Star icon loaded from external URL"
+          {...args}
+        />
+        <p style={{ 
+          fontSize: '12px', 
+          color: '#495057',
+          margin: '0.5rem 0 0 0',
+          wordBreak: 'break-all'
+        }}>
+          {url ? `Displays icon from: ${url}` : 'Displays icon from SVG'}
+        </p>
+      </div>
+      
+      <div style={{
+        border: '1px solid #f8d7da',
+        borderRadius: '8px',
+        padding: '1.5rem',
+        textAlign: 'center',
+        backgroundColor: '#f8d7da'
+      }}>
+        <h3 style={{ margin: '0 0 1rem 0', color: '#721c24' }}>❌ Invalid URL</h3>
+        <Icon 
+          source="https://invalid-url.com/icon.svg" 
+          size="32"
+          title="Failed to load icon"
+          aria-label="Icon that failed to load"
+        />
+        <p style={{ 
+          fontSize: '12px', 
+          color: '#721c24',
+          margin: '0.5rem 0 0 0',
+          wordBreak: 'break-all'
+        }}>
+          Shows empty SVG
+        </p>
+      </div>
+      
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Examples of different URL formats supported by the Icon component.',
+      },
+    },
+  },
+};

package/src/components/Icon/Icon.tsx

@@ -10,6 +10,7 @@
 import { FunctionComponent } from 'preact';
 import { classes } from '@adobe-commerce/elsie/lib/classes';
 import { lazy, Suspense, SVGProps } from 'preact/compat';
+import { useState, useEffect } from 'preact/hooks';
 
 import '@adobe-commerce/elsie/components/Icon/Icon.css';
 
@@ -66,9 +67,10 @@ const lazyIcons = {
 };
 
 export interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'size'> {
-  source:
-    | FunctionComponent<SVGProps<SVGSVGElement> & { title?: string }>
-    | IconType;
+  source?:
+  | FunctionComponent<SVGProps<SVGSVGElement> & { title?: string }>
+  | IconType
+  | string;
   size?: '12' | '16' | '24' | '32' | '64' | '80';
   stroke?: '1' | '2' | '3' | '4';
   className?: string;
@@ -79,6 +81,115 @@ export type IconNode = FunctionComponent<
   SVGProps<SVGSVGElement> & { title?: string }
 >;
 
+function isValidUrl(source: string): boolean { // check for URL from same domain
+  try {
+    if (source.startsWith('//')) {
+      const absoluteUrl = `${window.location.protocol}${source}`;
+      const url = new URL(absoluteUrl);
+      return url.hostname === window.location.hostname;
+    }
+    const url = new URL(source);
+    
+    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;
+  } catch {
+    console.error(`[Icon] Invalid URL format: ${source}`);
+    return false;
+  }
+}
+
+function UrlSvgLoader({
+  url,
+  ...props
+}: SVGProps<SVGSVGElement> & { url: string }) {
+  const [svgContent, setSvgContent] = useState<string>('');
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(false);
+
+  useEffect(() => {
+    fetch(url)
+      .then(response => {
+        if (!response.ok) {
+          console.error(`[Icon] Failed to fetch SVG: ${response.status} ${response.statusText}`);
+          throw error;
+        }
+        return response.text();
+      })
+      .then(content => {
+        // Check if content is valid SVG
+        if (!content.trim().toLowerCase().startsWith('<?xml') && 
+            !content.trim().toLowerCase().startsWith('<svg')) {
+          console.error(`[Icon] Invalid SVG content from ${url} - Content must be a valid SVG file`);
+          setError(true);
+          setLoading(false);
+          return;
+        }
+
+        // Process SVG content to ensure proper sizing and accessibility
+        let processedContent = content;
+
+        if (props.width) {
+          processedContent = processedContent.replace(
+            /<svg([^>]*)\s+width\s*=\s*["'][^"']*["']/gi,
+            '<svg$1'
+          );
+          processedContent = processedContent.replace(
+            /<svg/i,
+            `<svg width="${props.width}"`
+          );
+        }
+
+        if (props.height) {
+          processedContent = processedContent.replace(
+            /<svg([^>]*)\s+height\s*=\s*["'][^"']*["']/gi,
+            '<svg$1'
+          );
+          processedContent = processedContent.replace(
+            /<svg/i,
+            `<svg height="${props.height}"`
+          );
+        }
+        
+        if (props.title) {
+          processedContent = processedContent.replace(/<title[^>]*>.*?<\/title>/gi, '');
+          processedContent = processedContent.replace(
+            /<svg([^>]*)>/i,
+            `<svg$1><title>${props.title}</title>`
+          );
+        }
+        
+        setSvgContent(processedContent);
+        setLoading(false);
+      })
+      .catch((error) => {
+        console.error(`[Icon] ${error.message}`);
+        setError(true);
+        setLoading(false);
+      });
+  }, [url, props.width, props.height, props.title]);
+
+  if (loading || error) {
+    return <svg {...props} />;
+  }
+
+  return (
+    <div
+      className={props.className}
+      style={{
+        width: String(props.width),
+        height: String(props.height),
+        display: 'inline-block',
+        lineHeight: 0,
+      }}
+      dangerouslySetInnerHTML={{ __html: svgContent }}
+    />
+  );
+}
+
 export function Icon({
   source: Source,
   size = '24',
@@ -87,7 +198,6 @@ export function Icon({
   className,
   ...props
 }: IconProps) {
-  const LazyIcon = typeof Source === 'string' ? lazyIcons[Source] : null;
 
   const defaultProps = {
     className: classes([
@@ -100,10 +210,27 @@ export function Icon({
     viewBox,
   };
 
+  if (typeof Source === 'string' && isValidUrl(Source)) {
+    return (
+      <Suspense fallback={<svg {...props} {...defaultProps} />}>
+        <UrlSvgLoader url={Source} {...props} {...defaultProps}/>
+      </Suspense>
+    );
+  }
+
+  const LazyIcon = typeof Source === 'string' && Source in lazyIcons
+    ? lazyIcons[Source as IconType]
+    : null;
+
+  const isRejectedUrl = typeof Source === 'string' && 
+    (Source.startsWith('http') || Source.startsWith('//') || Source.startsWith('/'));
+
   return (
     <Suspense fallback={<svg {...props} {...defaultProps} />}>
       {LazyIcon ? (
         <LazyIcon {...props} {...defaultProps} />
+      ) : isRejectedUrl ? (
+        <svg {...props} {...defaultProps} />
       ) : (
         // @ts-ignore
         <Source {...props} {...defaultProps} />

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

@@ -12,7 +12,6 @@ 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',
@@ -270,65 +269,4 @@ 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 } from 'preact';
-import { FunctionComponent, useLayoutEffect, useRef } from 'preact/compat';
+import { ComponentChildren, render } from 'preact';
+import { FunctionComponent, useEffect, useRef } from 'preact/compat';
 
 interface PortalProps {
   children: ComponentChildren;
@@ -16,34 +16,28 @@ interface PortalProps {
 
 export const Portal: FunctionComponent<PortalProps> = ({ children }) => {
   const portalRoot = useRef<HTMLDivElement | null>(null);
-  const contentRef = useRef<HTMLDivElement | null>(null);
 
-  useLayoutEffect(() => {
+  useEffect(() => {
     // 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);
     }
 
-    // Move content to portal root
-    if (contentRef.current && portalRoot.current) {
-      portalRoot.current.appendChild(contentRef.current);
-    }
+    // Render children into portal root
+    render(children, portalRoot.current);
 
     // Cleanup
     return () => {
       if (portalRoot.current) {
+        render(null, portalRoot.current);
         portalRoot.current.remove();
         portalRoot.current = null;
       }
     };
-  }, []);
+  }, [children]);
 
-  // Return a div that contains the children
-  return (
-    <div ref={contentRef} className="dropin-design">
-      {children}
-    </div>
-  );
+  return null;
 }; 

package/src/lib/aem/assets.ts

@@ -1,104 +1,58 @@
-import {
-  provider as UI,
-  Image,
-  type ImageProps,
-} from '@adobe-commerce/elsie/components';
-
+import { provider as UI, Image } from '@adobe-commerce/elsie/components';
 import { getConfigValue } from '@adobe-commerce/elsie/lib/aem/configs';
-import type { ResolveImageUrlOptions } from '../resolve-image';
-
-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) */
+interface AemAssetsParams {
+  quality?: number;
+  format?: string;
+  crop?: {
+    xOrigin?: number;
+    yOrigin?: number;
+    width?: number;
+    height?: number;
+  };
+  size?: {
+    width?: number;
+    height?: number;
+  };
   width?: number;
-
-  /** The height of the crop (between 0 and 100) */
   height?: number;
+  [key: string]: any;
 }
 
-/**
- * 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 */
+interface AemAssetsImageConfig {
+  wrapper?: HTMLElement;
   alias: string;
-
-  /** The props to be applied to the underlying {@link Image} component */
-  imageProps: Partial<Omit<ImageProps, 'params' | 'width' | 'height'>> & {
+  params: AemAssetsParams;
+  imageProps: {
     src: string;
+    width?: number;
+    height?: number;
+    [key: string]: any;
   };
-
-  /** The parameters to be applied to the asset (known width required when using a slot) */
-  params: AemAssetsImageSlotConfigParams;
-
-  /** The element that will contain the image in the slot */
-  wrapper?: HTMLElement;
+  src?: string;
 }
 
 interface RenderContext {
   replaceWith: (element: HTMLElement) => void;
 }
 
+export function isAemAssetsEnabled(): boolean {
+  const config = getConfigValue('commerce-assets-enabled');
+
+  return config && (
+    (typeof config === 'string' && config.toLowerCase() === 'true')
+    || (typeof config === 'boolean' && config === true)
+  );
+}
+
+export function getDefaultAemAssetsOptimizationParams(): { quality: number; format: string } {
+  // See: https://adobe-aem-assets-delivery-experimental.redoc.ly/
+  return {
+    quality: 80,
+    format: 'webp',
+  };
+}
+
 /**
  * Normalizes the given URL to ensure it is a valid URL.
  * @param {string} url - The URL to normalize.
@@ -110,59 +64,13 @@ 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;
 
@@ -173,30 +81,19 @@ export function isAemAssetsUrl(url: string | URL): boolean {
   return true;
 }
 
-/** Generates an optimized URL for AEM Assets. */
-export function generateAemAssetsOptimizedUrl(
-  assetUrl: string,
-  alias: string,
-  params: Partial<AemAssetsParams> = {}
-): string {
+export function generateAemAssetsOptimizedUrl(url: string, alias: string, params: AemAssetsParams = {}): string {
   const defaultParams = getDefaultAemAssetsOptimizationParams();
   const mergedParams: AemAssetsParams = { ...defaultParams, ...params };
 
-  // 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)])
-  );
+  // Destructure the ones that need special handling
+  const {
+    format,
+    crop,
+    size,
+    ...optimizedParams
+  } = mergedParams;
 
-  const searchParams = new URLSearchParams(stringifiedParams);
+  const searchParams = new URLSearchParams(optimizedParams);
 
   if (crop) {
     const [xOrigin, yOrigin] = [crop.xOrigin || 0, crop.yOrigin || 0];
@@ -206,112 +103,87 @@ export function generateAemAssetsOptimizedUrl(
     searchParams.set('crop', cropTransform);
   }
 
-  return `${assetUrl}/as/${alias}.${format}?${searchParams.toString()}`;
+  // 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()}`;
 }
 
-/**
- * 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 {
+export function tryGenerateAemAssetsOptimizedUrl(url: string, alias: string, params: AemAssetsParams = {}): string {
   const assetsEnabled = isAemAssetsEnabled();
 
-  if (!assetsEnabled) {
+  if (!(assetsEnabled)) {
     // No-op, doesn't do anything.
-    return assetUrl;
+    return url;
   }
 
-  const assetsUrl = new URL(normalizeUrl(assetUrl));
+  const assetsUrl = new URL(normalizeUrl(url));
 
   if (!isAemAssetsUrl(assetsUrl)) {
     // Not an AEM Assets URL, so no-op.
-    return assetUrl;
+    return url;
   }
 
   const base = assetsUrl.origin + assetsUrl.pathname;
   return generateAemAssetsOptimizedUrl(base, alias, params);
 }
 
-/** Creates a slot that renders an AEM Assets image. */
-export function makeAemAssetsImageSlot(config: AemAssetsImageSlotConfig) {
+export function makeAemAssetsImageSlot(
+  config: AemAssetsImageConfig,
+) {
   return (ctx: RenderContext) => {
-    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(
-      imageProps.src,
+    const {
+      wrapper,
       alias,
-      params
-    );
-
-    const imageComponentParams: ResolveImageUrlOptions = {
-      width: params.width,
-      height: params.height,
+      params,
+      imageProps,
+      src,
+    } = config;
 
-      // 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 container = wrapper ?? document.createElement('div');
+    const imageSrc = generateAemAssetsOptimizedUrl(src || imageProps.src, alias, params);
 
-    const imageComponentProps: ImageProps = {
+    UI.render(Image as any, {
       ...imageProps,
-      width: params.width,
-      height: params.height,
 
       src: imageSrc,
-      params: imageComponentParams,
-    };
+      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);
 
-    UI.render(Image, imageComponentProps)(container);
     ctx.replaceWith(container);
   };
 }
 
-export function tryRenderAemAssetsImage(
-  ctx: RenderContext,
-  config: AemAssetsImageSlotConfig
-): void {
+export function tryRenderAemAssetsImage(ctx: RenderContext, config: AemAssetsImageConfig): void {
   // Renders an equivalent of the default image.
   function renderDefaultImage(): void {
     const container = config.wrapper ?? document.createElement('div');
-    const { imageProps, params } = config;
-    const imageComponentProps: ImageProps = {
-      ...imageProps,
-      width: params.width,
-      height: params.height,
-    };
+    const { imageProps } = config;
 
-    UI.render(Image, imageComponentProps)(container);
+    (UI.render as any)(Image, imageProps)(container);
     ctx.replaceWith(container);
   }
 
   const assetsEnabled = isAemAssetsEnabled();
 
-  if (!assetsEnabled) {
+  if (!(assetsEnabled)) {
     // No-op, render the default image.
     renderDefaultImage();
     return;
   }
 
-  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));
+  const { imageProps, src, ...slotConfig } = config;
+  const assetsUrl = new URL(normalizeUrl(src ?? imageProps.src));
 
   if (!isAemAssetsUrl(assetsUrl)) {
     // Not an AEM Assets URL, so render the default image.
@@ -319,5 +191,17 @@ export function tryRenderAemAssetsImage(
     return;
   }
 
-  makeAemAssetsImageSlot(config)(ctx);
+  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);
 }