@adobe-commerce/elsie 1.0.0-alpha1

package/src/lib/i18n.ts

@@ -0,0 +1,9 @@
+/**
+ * Convert locale from Magento standard to react-intl BCP 47 language tag
+ *
+ * @param {string} locale - A locale (e.g. `fr_FR`).
+ * @returns {string} A BCP 47 language tag (e.g. `fr-FR`).
+ */
+export const toLanguageTag = (locale: string) => {
+  return locale.replace('_', '-');
+};

package/src/lib/image-params-keymap.ts

@@ -0,0 +1,25 @@
+class ImageParamsKeyMap {
+  private _map?: { [key: string]: string } | undefined;
+
+  get map() {
+    return this._map;
+  }
+
+  set map(value: typeof this._map) {
+    this._map = value;
+  }
+
+  public getMethods() {
+    return {
+      setMap: (value: typeof this._map) => {
+        this.map = value;
+      },
+      getMap: () => this.map,
+    };
+  }
+}
+
+const keyMap = new ImageParamsKeyMap();
+
+export const { setMap: setImageParamsKeyMap, getMap: getImageParamsKeyMap } =
+  keyMap.getMethods();

package/src/lib/index.ts

@@ -0,0 +1,15 @@
+export * from '@adobe/elsie/lib/form-values';
+export * from '@adobe/elsie/lib/classes';
+export * from '@adobe/elsie/lib/deepmerge';
+export * from '@adobe/elsie/lib/debounce';
+export * from '@adobe/elsie/lib/resolve-image';
+export * from '@adobe/elsie/lib/render';
+export * from '@adobe/elsie/lib/i18n';
+export * from '@adobe/elsie/lib/initializer';
+export * from '@adobe/elsie/lib/config';
+export * from '@adobe/elsie/lib/types';
+export * from '@adobe/elsie/lib/slot';
+export * from '@adobe/elsie/lib/vcomponent';
+export * from '@adobe/elsie/lib/image-params-keymap';
+export * from '@adobe/elsie/lib/is-number';
+export * from '@adobe/elsie/lib/deviceUtils';

package/src/lib/initializer.ts

@@ -0,0 +1,122 @@
+import { Config, setImageParamsKeyMap } from '@adobe/elsie/lib';
+
+type Listener = { off(): void };
+
+type Listeners<T> = (config?: T) => Array<Listener | undefined>;
+
+type Init<T> = (config?: T) => Promise<void>;
+
+type Options<T> = { init: Init<T>; listeners: Listeners<T> };
+
+export type Model<T = any, D = any> = {
+  transformer?: (data: D) => T & { [key: string]: any };
+};
+
+/**
+ * The `Initializer` class is responsible for setting up event listeners and initializing a module with the given configuration.
+ *
+ * @template T - The type of the configuration object.
+ * @class
+ */
+export class Initializer<T> {
+  private _listeners: Listener[] = [];
+  listeners: Listeners<T>;
+  init: Init<T>;
+  config = new Config<T>({} as T);
+
+  /**
+   * Creates an instance of Initializer.
+   * @param options - The initialization options.
+   * @param options.init - A function that initializes the module.
+   * @param options.listeners - A function that sets up event listeners.
+   */
+  constructor({ init, listeners }: Options<T>) {
+    this.listeners = (config) => {
+      // Unbind existing listeners
+      this._listeners.forEach((listener) => listener.off());
+      // Bind new listeners
+      return (this._listeners = listeners(config) as Listener[]);
+    };
+
+    this.init = (options) => {
+      const { imageParamsKeyMap, ...rest } = options as any;
+      this.config.setConfig({ ...this.config.getConfig(), ...rest });
+      setImageParamsKeyMap(imageParamsKeyMap);
+      return init(options);
+    };
+  }
+}
+
+type Initializers = [Initializer<any>, { [key: string]: any } | undefined][];
+
+/**
+ * The Initializers class provides methods to register, mount, and configure initializers.
+ *
+ * @class
+ *
+ * @method register - 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.
+ * @method mount - Mounts all registered initializers. This involves binding the event listeners and initializing the APIs for each initializer, in that order.
+ * @method setImageParamKeys - Sets the image parameter keys. These keys are used when initializing the APIs for the initializers.
+ */
+export class initializers {
+  static _initializers: Initializers = [];
+  static _mounted: boolean = false;
+  static _imageParamsKeyMap: { [key: string]: 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.
+   * @param options - Optional configuration for the initializer.
+   */
+  static register(
+    initializer: Initializer<any>,
+    options?: { [key: string]: any }
+  ) {
+    if (initializers._mounted) {
+      initializer.listeners?.(options);
+      initializer.init?.(options);
+    }
+    initializers._initializers.push([initializer, options]);
+  }
+
+  /**
+   * Mounts the provided initializer immediately. This involves binding the event listeners and initializing the API for the initializer.
+   */
+  static async mountImmediately(
+    initializer: Initializer<any>,
+    options?: { [key: string]: any }
+  ) {
+    initializer.listeners?.(options);
+    await initializer.init?.({
+      imageParamsKeyMap: initializers._imageParamsKeyMap,
+      ...options
+    });
+  }
+
+  /**
+   * Mounts all registered initializers. This involves binding the event listeners and initializing the APIs for each initializer, in that order.
+   */
+  static mount() {
+    initializers._mounted = true;
+    // In this specific order
+    // 1. Bind events
+    initializers._initializers?.forEach(([initializer, options]) => {
+      initializer.listeners?.(options);
+    });
+
+    // 2. Initialize APIs
+    initializers._initializers?.forEach(([initializer, options]) => {
+      initializer.init?.({
+        imageParamsKeyMap: initializers._imageParamsKeyMap,
+        ...options,
+      });
+    });
+  }
+  /**
+   * Sets the image parameter keys. These keys are used when initializing the APIs for the initializers.
+   * @param params - The image parameter keys.
+   */
+  static setImageParamKeys(params: { [key: string]: any }) {
+    initializers._imageParamsKeyMap = params;
+  }
+}

package/src/lib/is-number.ts

@@ -0,0 +1,3 @@
+export const isNumber = (value: number | string): value is number => {
+  return typeof value === 'number';
+};

package/src/lib/render.tsx

@@ -0,0 +1,129 @@
+import { render, VNode, createContext } from 'preact';
+import renderToString from 'preact-render-to-string';
+import { Container, VComponent } from '@adobe/elsie/lib';
+import { Signal, signal } from '@adobe/elsie/lib/signals';
+
+export const SlotQueueContext = createContext<Signal<Set<string>> | null>(null);
+
+type RenderAPI = {
+  remove: () => void;
+  setProps: (cb: (prev: any) => any) => void;
+};
+
+/**
+ * The `Render` class provides methods to render and unmount components, as well as to render components to a string.
+ * @class
+ *
+ * @property {Function} render - Renders a component to a root element.
+ * @property {Function} toString - Renders a component to a string.
+ */
+export class Render {
+  private _provider: VNode<any>;
+
+  constructor(provider: VNode<any>) {
+    this._provider = provider;
+  }
+
+  /**
+   * Renders a container to a root element.
+   * @param Container - The container to render.
+   * @param props - The container parameters.
+   * @returns A function to render the component to a root element.
+   */
+  render<T>(Component: Container<T>, props: T) {
+    /**
+     * Renders a component to a root element.
+     * @param rootElement - The root element to render the component to.
+     * @returns A promise that resolves to an object with methods to control the rendered component.
+     */
+    return async (rootElement: HTMLElement): Promise<RenderAPI> => {
+      if (!Component) throw new Error('Component is not defined');
+      if (!rootElement) throw new Error('Root element is not defined');
+
+      const initialData = (await Component.getInitialData?.(props)) ?? {};
+
+      const state = signal<T>({ ...props });
+
+      const queue = signal<Set<string>>(new Set());
+
+      const provider = this._provider;
+
+      const Root = ({ next }: { next: Signal<T> }) => {
+        return (
+          <SlotQueueContext.Provider value={queue}>
+            <VComponent node={provider} {...provider.props}>
+              <Component {...next.value} initialData={initialData} />
+            </VComponent>
+          </SlotQueueContext.Provider>
+        );
+      };
+
+      // clear the root element
+      rootElement.innerHTML = '';
+
+      // clone the root element to initialize rendering on the background
+      const tmp = document.createElement('div');
+
+      // apply base design tokens and global styles to the root element
+      rootElement.classList.add('dropin-design');
+
+      render(<Root next={state} />, tmp);
+
+      // API object to control the rendered component
+      const API: RenderAPI = {
+        remove: () => {
+          render(null, tmp);
+        },
+        setProps: (cb: (prev: T) => T) => {
+          const next = cb(state.peek());
+          state.value = next;
+        },
+      };
+
+      // wait for all slots to be resolved
+      return new Promise((resolve) => {
+        queue.subscribe((pending) => {
+          if (pending.size === 0) {
+            // apply base design tokens and global styles to the root element
+            rootElement.classList.add('dropin-design');
+
+            // append the rendered component to the DOM only when all slots are resolved
+            rootElement.appendChild(tmp.firstChild ?? tmp);
+
+            return resolve(API);
+          }
+        });
+      });
+    };
+  }
+
+  /**
+   * UnRenders a component from a root element.
+   * @param rootElement - The root element to unmount the component from.
+   * @deprecated Use `remove` method from the returned object of the `mount` method instead.
+   */
+  unmount(rootElement: HTMLElement) {
+    if (!rootElement) throw new Error('Root element is not defined');
+    rootElement.firstChild?.remove();
+  }
+
+  /**
+   * Renders a component to a string.
+   * @param Component - The component to render.
+   * @param props - The component props.
+   * @param options - Optional rendering options.
+   */
+  async toString<T>(Component: Container<T>, props: T, options?: T) {
+    if (!Component) throw new Error('Component is not defined');
+
+    const initialData = (await Component.getInitialData?.(props)) ?? {};
+
+    return renderToString(
+      <VComponent node={this._provider} {...this._provider.props}>
+        <Component {...props} initialData={initialData} />
+      </VComponent>,
+      {},
+      { ...options }
+    );
+  }
+}

package/src/lib/resolve-image.ts

@@ -0,0 +1,77 @@
+import { getImageParamsKeyMap } from '@adobe/elsie/lib/';
+
+const BREAKPOINTS = {
+  medium: 768,
+  large: 1024,
+  xlarge: 1366,
+  xxlarge: 1920,
+};
+
+export interface ResolveImageUrlOptions {
+  width: number;
+  height?: number;
+  auto?: string;
+  quality?: number;
+  crop?: boolean;
+  fit?: string;
+}
+
+const resolveImageUrl = (url: string, _opts?: ResolveImageUrlOptions) => {
+  const [base, query] = url.split('?');
+  const params = new URLSearchParams(query);
+
+  const keyMapping = getImageParamsKeyMap();
+
+  let opts = {};
+
+  if (keyMapping && Object.keys(keyMapping).length > 0 && _opts) {
+    opts = Object.entries(_opts).reduce((acc, [key, value]) => {
+      const newKey = keyMapping[key];
+      if (newKey) {
+        acc[newKey] = value;
+      }
+      return acc;
+    }, {} as { [key: string]: any });
+  } else {
+    opts = {
+      auto: 'webp',
+      quality: 80,
+      crop: false,
+      fit: 'cover',
+      ..._opts,
+    };
+  }
+  // Append image optimization parameters
+  Object.entries(opts).forEach(([key, value]) => {
+    if (value !== undefined && value !== null) {
+      params.set(key, String(value));
+    }
+  });
+
+  return `${base}?${params.toString()}`;
+};
+
+export const generateSrcset = (
+  imageURL: string,
+  options: ResolveImageUrlOptions
+) => {
+  if (!imageURL || !options?.width) return;
+
+  const generateSrcsetUrl = (options: ResolveImageUrlOptions) => {
+    return resolveImageUrl(imageURL, {
+      ...options,
+    });
+  };
+
+  return Object.entries(BREAKPOINTS)
+    .map(([, value]) => {
+      // calculate breakpoints width
+      const relativeWidth = (options.width * value) / BREAKPOINTS.xxlarge;
+
+      return `${generateSrcsetUrl({
+        ...options,
+        width: relativeWidth,
+      })} ${value}w`;
+    })
+    .join(',\n');
+};

package/src/lib/signals.ts

@@ -0,0 +1,2 @@
+// eslint-disable-next-line no-restricted-imports
+export * from '@preact/signals';