@adobe-commerce/elsie 1.0.0-alpha04071347

package/src/docs/API/graphql.mdx

@@ -0,0 +1,214 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+
+<Meta title="Build Tools/GraphQL API" />
+<Unstyled>
+
+# GraphQL Extensibility API
+
+The GraphQL Extensibility API allows developers to extend existing GraphQL operations used by a Drop-in to meet additional data requirements without increasing code complexity or negatively impacting performance. 
+This API provides a flexible and efficient way to customize GraphQL Fragments by integrating build-time modifications into the storefront's development pipeline.
+
+## Extend your Drop-in GraphQL Fragments
+
+To enable GraphQL Fragments to be extensible in your Drop-in, follow these steps:
+
+### Step 1: Define Your Fragments
+
+Create the content for the fragments you are exporting.
+
+```ts
+// ./src/api/fragments/MyFragment.ts
+
+export const MY_FRAGMENT = `
+  fragment MY_FRAGMENT on FragmentInterface {
+    firstname
+    lastname
+    
+    favorites {
+      uid
+      name
+    }
+  }
+`;
+```
+
+### Step 2: Create Fragments Manifest File
+
+Next, create a new file for your project to list all the fragments you want to expose.
+
+```ts
+// ./src/api/fragments.ts
+
+export { MY_FRAGMENT } from '@/my-dropin/api/graphql/MyFragment';
+```
+
+## Step 3: Update the API Configuration
+
+Finally, add the new file reference to the API configuration in `./.elsie.js`.
+
+```js
+// ./.elsie.js
+
+module.exports = {
+  name: 'MyDropin',
+  api: {
+    root: './src/api',
+    importAliasRoot: '@/my-dropin/api',
+    fragments: './fragments.ts', // 👈 add this line
+  },
+  components: [
+    {
+      id: 'Components',
+      root: './src/components',
+      importAliasRoot: '@/my-dropin/components',
+      cssPrefix: 'my-dropin',
+      default: true,
+    },
+  ],
+  containers: {
+    root: './src/containers',
+    importAliasRoot: '@/my-dropin/containers',
+  },
+  schema: {
+    endpoint: process.env.ENDPOINT,
+    headers: {}
+  }
+};
+```
+
+## Extend the Data module
+
+Now that we have made our fragments extensible, we must extend the data model used in our Drop-ins.
+
+### Step 1: Define Typing to the Initializer API
+
+First, add the typing to your initializer API in `./src/api/initialize/initialize.ts`.
+
+```ts
+// ./src/api/initialize/initialize.ts
+
+import { Initializer, Model } from '@adobe-commerce/elsie/lib';
+import { Lang } from '@adobe-commerce/elsie/i18n';
+import { MyModel } from '@/my-dropin/data/models';
+
+type ConfigProps = {
+  langDefinitions?: Lang;
+
+  // 👇 add your models configuration
+  models?: {
+    MyModel?: Model<MyModel>;
+  },
+};
+
+export const initialize = new Initializer<ConfigProps>({
+  init: async (config) => {
+    const defaultConfig = {};
+    initialize.config.setConfig({ ...defaultConfig, ...config });
+  },
+
+  listeners: () => [],
+});
+
+export const config = initialize.config;
+```
+
+### Step 2: Extend the Data Transformer
+
+Then, use the configuration to extend the data transformer the model uses by deep merging the existing data transformation with the new configuration.
+
+```ts
+// ./src/data/transforms/transform-my-model.ts
+import { merge } from '@adobe-commerce/elsie/lib';
+import { MyModel } from '@/my-dropin/data/models';
+
+export function transformMyModel(data: any): MyModel {
+  const model = {
+    name: `${data.firstname} ${data.lastname}`,
+    favorites: data.favorites,
+  };
+
+  // Merge custom transformer, if provided
+  return merge(
+    model, // default transformer
+    config.getConfig().models?.MyModel?.transformer?.(data) // custom transformer
+  );
+}
+```
+
+---
+
+# Using the GraphQL Extensibility Feature in Your Storefront
+
+By extending the GraphQL Fragments and Models of drop-ins, you can leverage the drop-in's existing GraphQL operations and add extra fields needed to meet your specific business requirements. 
+This approach enhances the user experience while maintaining code simplicity and performance efficiency since all modifications are integrated into the storefront's development build-time pipeline.
+
+## Extend Drop-in's Fragments and Models
+
+Follow these steps to extend the GraphQL Fragment and Model in your Drop-in:
+
+### Step 1: Extend the GraphQL Fragment
+
+Use the `overrideGQLOperations` function to extend the existing GraphQL Fragment, allowing you to add fields to the fragment as needed.
+
+The `overrideGQLOperations` functions accept an array of configuration objects where you must specify:
+
+#### npm: string
+
+The node module name of the drop-in. i.e. "@dropins/my-dropin".
+
+#### operations: string[] 
+
+An array of string or template literal with operations. 
+
+- Only one definition can be provided in the operation.
+- These must match the operation name as provided by the drop-in. i.e. `MY_FRAGMENT`.
+- The operations must be valid GraphQL operations, such as Fragment. i.e. `fragment MY_FRAGMENT on FragmentInterface { ... }`.
+- In the case of a Fragment, the fragment name must match the same interface as the drop-in. i.e. `FragmentInterface`.
+- If an existing field that has variables is used:
+    - If not variables are provided, the existing variables will be used. i.e. `favorites(page: 1) { ... }`.
+    - If new variables are provided, the new variable will be added. i.e. `favorites(page: 1, offset: 5) { ... }`.
+    - If the existing variables are changed, the new variables will be used. i.e. `favorites(page: 2) { ... }`.
+
+
+```js
+import overrideGQLOperations from '@dropins/build-tools/gql-extend.js';
+
+overrideGQLOperations([
+  {
+    npm: '@dropins/my-dropin',
+    operations: [`
+      fragment MY_FRAGMENT on FragmentInterface {
+        age
+        
+        favorites {
+          quantity
+        }
+      }
+    `],
+  },
+]);
+```
+
+### Step 2: Extend the Data Model
+
+Next, update the data models to include the new fields added to the fragment, ensuring that the additional data is correctly processed and available for use in the drop-in. i.e., Slots, Event Bus, etc.
+
+```js
+import * as api from '@dropins/storefront-cart/api.js';
+
+initializers.register(api.initialize, {
+  models: {
+    MyModel: {
+      transformer: (data) => ({
+        age: data?.age,
+        favorites: data.favorites.map((favorite) => ({ 
+          quantity: favorite.quantity,
+        })),
+      }),
+    },
+  },
+});
+
+```
+
+</Unstyled>

package/src/docs/API/initializer.mdx

@@ -0,0 +1,119 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+
+<Meta title="API/Initializer" />
+<Unstyled>
+
+# Initializer
+
+```typescript
+// my-dropin/initializer.ts
+
+import { Initializer } from '@adobe-commerce/elsie/lib';
+// import { events } from '@adobe-commerce/event-bus';
+
+type ConfigProps = {};
+
+export const initialize = new Initializer<ConfigProps>({
+  init: async (config) => {
+    const defaultConfig = {};
+    initialize.config.setConfig({ ...defaultConfig, ...config });
+  },
+
+  listeners: () => [
+    // events.on('authenticated', (authenticated) => {
+    //   console.log('authenticated', authenticated);
+    // }),
+  ],
+});
+
+export const config = initialize.config;
+```
+
+```typescript
+// Host Site
+import { initializers } from '@dropins/tools/initializer.js';
+import { initialize as pkg } from 'my-dropin/initializer.js';
+
+// Register Packages
+initializers.register(pkg, { ...config });
+
+// Mount Initializers
+window.addEventListener('load', initializers.mount);
+```
+
+</Unstyled>
+
+## `setImageParamKeys(params)`
+
+The `setImageParamKeys` method is part of the initializers module in the `@dropins/tools` package.
+It allows you to set image parameters globally for all drop-ins that use the Image component.
+
+### Default Behavior
+
+By default, Fastly parameters are used if `setImageParamKeys` is not called or if no parameters are provided.
+
+### Parameters
+
+- `params` - `{ [key: string]: string | ((data: any) => [string, string]) }`
+  - An object of key-value pairs to map image parameters to their respective keys in the URL.
+  - The value can be a string or a function that takes the parameter value as an argument and returns a tuple of the new key and transformed value.
+
+### Functionality
+
+- If a parameter key is provided via `setImageParamKeys`, it is used in generating image URLs instead of the default Fastly parameters.
+- If a parameter key is not provided via `setImageParamKeys`, it is omitted from the generated image URLs.
+- If a mapped key is a function and it is not specified as a parameter in the Image component, it is called with `null`. It should return a tuple of the key and value.
+- If a mapping callback is provided, the callback is called with the parameter value (if it exists) and should return a tuple of the new key and transformed value.
+- If a mapping callback returns `null`, the parameter is omitted from the generated image URLs.
+
+### Usage
+
+Call the setImageParamKeys() function before the register() and mount() functions in the application layer.
+
+```javascript
+// Set global image parameters
+initializers.setImageParamKeys({
+  // Re-map the width parameter to imgWidth
+  width: 'imgWidth',
+  // Transform the quality parameter
+  quality: (value) => ['imgQuality', value * 100],
+  // Add an additional parameter to the image URL
+  extraParam: () => ['extraParam', 'extraValue'],
+});
+
+// Register Initializers
+initializers.register(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:
+
+```jsx
+<Image
+  loading={'lazy'}
+  src={'https://example.com/image.jpg'}
+  alt={'Example Image'}
+  width="300"
+  height="300"
+  params={{ width: 300, quality: 0.8 }}
+/>
+```
+
+It renders the following image element:
+
+```html
+<img
+  loading="lazy"
+  src="https://example.com/image.jpg"
+  srcset="https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 768w, https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 1024w, https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 1366w, https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 1920w"
+  alt="Example Image"
+  width="300"
+  height="300"
+/>
+```
+
+In this example, the width parameter is mapped to imgWidth and the value of the quality parameter is modified and mapped to imgQuality.

package/src/docs/API/render.mdx

@@ -0,0 +1,125 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+
+<Meta title="API/Render" />
+<Unstyled>
+
+# Render
+
+## Implementing a new render in your dropin
+
+To implement a new render in your dropin, you must create an instance of the `Render` class from the `@adobe-commerce/elsie/lib` library, passing in a `Provider` component. 
+This setup initializes the rendering context with the specified provider, which can manage state, context, or other dependencies required by your components. 
+By exporting this `render` instance, you enable different parts of your application to render components within the defined context, ensuring consistent behavior and integration across your application.
+
+```ts
+// Dropin
+
+import { Render } from '@adobe-commerce/elsie/lib';
+import { Provider } from './Provider';
+
+export const render = new Render(<Provider />);
+```
+
+## Rendering a dropin's container in a storefront
+
+The render function mounts a drop-in container or component into the DOM and manages its lifecycle. 
+It returns a Promise that resolves to an object containing methods for updating and removing the component instance.
+
+```js
+// Storefront
+import { render as provider } from 'my-domain-pkg/render.js';
+import { MyContainer } from 'my-domain-pkg/containers/MyContainer.js';
+
+const wrapper = document.getElementById('my-container-root');
+
+provider.render(MyContainer, { ...props })(wrapper);
+```
+
+### Using VNode as a property
+
+Some components may require VNodes as properties. If you are using another component from the library, provide the VNode by executing the component as a function.
+
+```js
+// Storefront
+
+import { Button, Icon, provider } from '@dropins/tools/components.js';
+
+const wrapper = document.getElementById('my-container-root');
+
+provider.render(Button, { 
+    children: 'My Button', 
+    icon: Icon({ source: 'Heart' }), 
+})(wrapper);
+```
+
+You may also create your VNode using the `h` function from the Preact library. 
+
+```js
+// Storefront
+
+import { Button, provider } from '@dropins/tools/components.js';
+import { h } from '@dropins/tools/preact.js';
+
+const wrapper = document.getElementById('my-container-root');
+
+provider.render(Button, { icon: h('div', { id: 'my-vnode' }) })(wrapper);
+```
+
+### Update properties of a rendered component
+
+The `setProps` method is provided by the instance returned from the `render` function. 
+It allows for dynamic updates to the properties of a rendered component. 
+By accepting an updater function, `setProps` lets you modify the component's props based on its previous state. 
+This method is particularly useful for making incremental changes or responding to user interactions 
+without re-rendering the entire component. It ensures that the component's state remains consistent
+and up-to-date with the latest data or user inputs.
+
+#### Example
+
+```js
+// Storefront
+
+import { render as provider } from 'my-domain-pkg/render.js';
+import { MyContainer } from 'my-domain-pkg/containers/MyContainer.js';
+
+const wrapper = document.getElementById('my-container-root');
+const myContainer = await provider.render(MyContainer, { ...props })(wrapper);
+
+const button = document.getElementById('my-button');
+
+button.addEventListener('click', () => {
+    // Update the component's props
+    myContainer.setProps((prevProps) => ({
+    ...prevProps,
+    newProp: 'new value',
+    }));
+});
+```
+
+### Remove a rendered component from the DOM
+
+The `remove` method is provided by the instance returned from the `render` function. 
+It allows for the complete removal of a rendered component from the DOM. 
+When invoked, `remove` ensures that the component and its associated resources are properly cleaned up, 
+preventing memory leaks and maintaining the application's overall performance. 
+This method is essential for managing the lifecycle of dynamic components, 
+especially in applications where components need to be frequently added and removed based 
+on user interactions or other events.
+
+```js
+import { render as provider } from 'my-domain-pkg/render.js';
+import { MyContainer } from 'my-domain-pkg/containers/MyContainer.js';
+
+const wrapper = document.getElementById('my-container-root');
+const myContainer = await provider.render(MyContainer, { ...props })(wrapper);
+
+const button = document.getElementById('my-button');
+
+button.addEventListener('click', () => {
+    // Remove the component from the DOM
+    myContainer.remove();
+});
+```
+
+</Unstyled>
+

package/src/docs/Design/colors.mdx

@@ -0,0 +1,202 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+import { Block, DesignSwatchGroup, TokenDefinitions } from './designBlocks';
+import colorsData from '@adobe-commerce/storefront-design/base/colors/colors.json';
+import { getTokenData } from './getTokenData';
+
+export const tokenData = getTokenData(colorsData);
+export const tokenNames = tokenData.map((token) => token.name);
+
+<Meta title="Design/Colors" />
+
+
+<Unstyled>
+
+# Color Design tokens
+
+Use color to create meaningful experiences while also expressing hierarchy, state, and brand identity.
+Add as many colors and shades as you need, here you have the basics.
+
+## Available Design tokens
+
+### Brand
+
+export const colorBrandPrefix = '--color-brand';
+
+<TokenDefinitions
+  tokenData={tokenData.filter((data) => data.name.startsWith(colorBrandPrefix))}
+/>
+
+<Block>
+  <DesignSwatchGroup
+    property="background"
+    prefix={colorBrandPrefix}
+    tokens={tokenNames}
+    groupStyles={{ margin: 'none' }}
+    swatchStyles={{ border: 'none' }}
+  />
+</Block>
+
+### Neutrals
+
+export const colorNeutralPrefix = '--color-neutral';
+
+<TokenDefinitions
+  tokenData={tokenData.filter((data) =>
+    data.name.startsWith(colorNeutralPrefix)
+  )}
+/>
+
+<Block>
+  <DesignSwatchGroup
+    property="background"
+    prefix={colorNeutralPrefix}
+    tokens={tokenNames}
+    groupStyles={{ margin: 'none' }}
+    swatchStyles={{ border: 'none' }}
+  />
+</Block>
+
+### Positive
+
+export const colorPositivePrefix = '--color-positive';
+
+<TokenDefinitions
+  tokenData={tokenData.filter((data) =>
+    data.name.startsWith(colorPositivePrefix)
+  )}
+/>
+
+<Block>
+  <DesignSwatchGroup
+    property="background"
+    prefix={colorPositivePrefix}
+    tokens={tokenNames}
+    groupStyles={{ margin: 'none' }}
+    swatchStyles={{ border: 'none' }}
+  />
+</Block>
+
+### Informational
+
+export const colorInformationalPrefix = '--color-informational';
+
+<TokenDefinitions
+  tokenData={tokenData.filter((data) =>
+    data.name.startsWith(colorInformationalPrefix)
+  )}
+/>
+
+<Block>
+  <DesignSwatchGroup
+    property="background"
+    prefix={colorInformationalPrefix}
+    tokens={tokenNames}
+    groupStyles={{ margin: 'none' }}
+    swatchStyles={{ border: 'none' }}
+  />
+</Block>
+
+### Warning
+
+export const colorWarningPrefix = '--color-warning';
+
+<TokenDefinitions
+  tokenData={tokenData.filter((data) =>
+    data.name.startsWith(colorWarningPrefix)
+  )}
+/>
+
+<Block>
+  <DesignSwatchGroup
+    property="background"
+    prefix={colorWarningPrefix}
+    tokens={tokenNames}
+    groupStyles={{ margin: 'none' }}
+    swatchStyles={{ border: 'none' }}
+  />
+</Block>
+
+### Alert
+
+export const colorAlertPrefix = '--color-alert';
+
+<TokenDefinitions
+  tokenData={tokenData.filter((data) => data.name.startsWith(colorAlertPrefix))}
+/>
+
+<Block>
+  <DesignSwatchGroup
+    property="background"
+    prefix={colorAlertPrefix}
+    tokens={tokenNames}
+    groupStyles={{ margin: 'none' }}
+    swatchStyles={{ border: 'none' }}
+  />
+</Block>
+
+### Opacity
+
+export const colorOpacityPrefix = '--color-opacity';
+
+<TokenDefinitions
+  tokenData={tokenData.filter((data) =>
+    data.name.startsWith(colorOpacityPrefix)
+  )}
+/>
+
+<Block
+  style={{
+    background: 'var(--color-neutral-900)',
+    color: 'var(--color-neutral-50)',
+  }}
+>
+  <DesignSwatchGroup
+    property="background"
+    prefix={colorOpacityPrefix}
+    tokens={tokenNames}
+    groupStyles={{ margin: 'none' }}
+    swatchStyles={{ border: 'none' }}
+  />
+</Block>
+
+### Button States
+
+export const colorButtonState = '--color-button';
+
+<TokenDefinitions
+  tokenData={tokenData.filter((data) =>
+    data.name.startsWith(colorButtonState)
+  )}
+/>
+
+<Block>
+  <DesignSwatchGroup
+    property="background"
+    prefix={colorButtonState}
+    tokens={tokenNames}
+    groupStyles={{ margin: 'none' }}
+    swatchStyles={{ border: 'none' }}
+  />
+</Block>
+
+### Action Button States
+
+export const colorActionButtonState = '--color-action-button';
+
+<TokenDefinitions
+  tokenData={tokenData.filter((data) =>
+    data.name.startsWith(colorActionButtonState)
+  )}
+/>
+
+<Block>
+  <DesignSwatchGroup
+    property="background"
+    prefix={colorActionButtonState}
+    tokens={tokenNames}
+    groupStyles={{ margin: 'none' }}
+    swatchStyles={{ border: 'none' }}
+  />
+</Block>
+
+</Unstyled>