@adobe-commerce/elsie 1.0.0-alpha1

package/src/docs/quick-start.mdx

@@ -0,0 +1,245 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+import { Steps } from '@adobe/elsie/config/storybook/components/Steps';
+import { FileTree } from '@adobe/elsie/config/storybook/components/FileTree';
+import { Screenshot } from '@adobe/elsie/config/storybook/components/Screenshot';
+import dropinDevEnv from '../../static/dropin.png';
+
+<Meta title="Quick start" />
+<Unstyled>
+
+# Quick start
+
+Use the steps below to build your first composable drop-in using this SDK.
+
+<Steps>
+
+### Create your composable drop-in project
+
+The first step is visiting our GitHub Enterprise drop-in project template. You must be logged into Adobe's VPN for this link to work: [Commerce-Storefront/my-dropin](https://git.corp.adobe.com/Commerce-Storefront/my-dropin).
+
+From the GitHub page, click the **Use this template** button. You can name your new drop-in repo whatever you want, but we recommend naming it to reflect the drop-in you want to build. For example, if you want to build a drop-in to show a customer's purchase history, naming your drop-in project/repo `purchase-history` would be reasonable.
+
+### Clone your new project
+
+Follow the standard process: Click your repo's **Code** button, copy the SSH link, open your terminal, change directories to where you want it on your workstation, and run:
+
+```bash
+git clone <your-repository-ssh-url>
+```
+
+### Install the project dependencies
+
+Open your project and install dependencies with your choice of package managers.
+
+```bash
+yarn
+npm install
+pnpm install
+```
+
+### Generate the project config file
+
+Before you can start developing, you need to generate the `.elsie.js` config file. The elsie CLI uses this file to generate new components, containers, and API functions to specified directories within your projects. Run the following command, replacing `<your-dropin-name>` with the name of your drop-in component. For example, `npx elsie generate config --name purchase-history`.
+
+```bash
+npx elsie generate config --name <your-dropin-name>
+```
+
+After generating the `.elsie.js` config, open it and take a look. Below is an annotated version describing the main properties:
+
+```js
+module.exports = {
+  name: 'purchase-history', // The name of your drop-in. This name can be changed at any time.
+  api: {
+    root: './src/api', // Directory where the CLI will add all your generated API functions.
+    importAliasRoot: '@/purchase-history/api',
+  },
+  components: [
+    {
+      id: 'Components',
+      root: './src/components', // Directory where the CLI will add all your generated components.
+      importAliasRoot: '@/purchase-history/components',
+      cssPrefix: 'dropin',
+      default: true,
+    },
+  ],
+  containers: {
+    root: './src/containers', // Directory where the CLI will add all your generated containers.
+    importAliasRoot: '@/purchase-history/containers',
+  },
+};
+```
+
+### Explore the project structure
+
+In future versions of the docs, we will provide a detailed explanation of each folder and file in the project structure. For now, these are the highlights:
+
+<FileTree>
+  <FileTree.Folder
+    name=".storybook"
+    description="— Best-practice Storybook configurations right out of the box"
+  />
+  <FileTree.Folder name="examples" defaultOpen>
+    <FileTree.Folder
+      name="html-host"
+      defaultOpen
+      description="— Preconfigured HTML UI for testing your composable drop-in"
+    >
+      <FileTree.File name="example.css" />
+      <FileTree.File name="favicon.ico" />
+      <FileTree.File name="index.html" />
+      <FileTree.File name="styles.css" />
+    </FileTree.Folder>
+  </FileTree.Folder>
+  <FileTree.Folder name="src" defaultOpen>
+    <FileTree.Folder
+      name="api"
+      description="— By default, the elsie CLI adds your API functions here"
+    />
+    <FileTree.Folder
+      name="docs"
+      description="— Provides an MDX template to document your drop-in"
+    />
+    <FileTree.Folder
+      name="i18n"
+      description="— Internationalization setup with starter en_US.json file"
+    />
+    <FileTree.Folder name="render" />
+  </FileTree.Folder>
+  <FileTree.File
+    name=".elsie.js"
+    description="— Configuration file for creating components, containers and functions"
+  />
+  <FileTree.File
+    name=".env.local"
+    description="— Preconfigured settings for a development-only mesh endpoint"
+  />
+  <FileTree.File name=".eslintrc.js" description="— Preconfigured linting" />
+  <FileTree.File name=".gitignore" />
+  <FileTree.File
+    name=".jest.config.js"
+    description="— Preconfigured unit testing"
+  />
+  <FileTree.File
+    name="package.json"
+    description="— Preconfigured dependencies"
+  />
+  <FileTree.File
+    name="prettier.config.js"
+    description="— Preconfigured formatting"
+  />
+  <FileTree.File
+    name="README.md"
+    description="— Quick instructional overview of drop-in development tasks"
+  />
+  <FileTree.File
+    name="storybook-stories.js"
+    description="— A few more storybook settings"
+  />
+  <FileTree.File
+    name="tsconfig.js"
+    description="— Preconfigured for TypeScript!"
+  />
+  <FileTree.File name="vite.config.mjs" />
+</FileTree>
+
+### Update the mesh endpoint
+
+By default, the drop-in project is configured to use a development-only mesh endpoint. This endpoint is only available when running the project locally. To use a different mesh endpoint, update the following file:
+
+```bash
+.env.local
+```
+
+### Launch development environment
+
+Let's take it for a spin! Run the following command to launch your project's development environment in its default state:
+
+```bash
+yarn dev
+npm run dev
+pnpm run dev
+```
+
+Congrats! You just launched your first composable drop-in! Actually, no... What you're seeing is our drop-in development environment. It's a preconfigured HTML page (`examples > html-host > index.html`) that loads your drop-in for testing during development.
+
+<Screenshot src={dropinDevEnv} alt={'Drop-in development environment'} />
+
+Now we're ready to start building a composable drop-in. Stop the server with `ctrl + c` and let's get started.
+
+### Generate a new UI Component
+
+Start by executing the following command, replacing `<MyUiComponent>` with the name of the component you want to add. For example, if you were building a drop-in for a customer's purchase history, you might want a part of the drop-in to show a list of date ranges to filter their product purchases. In that case, you might generate something like this: `npx elsie generate component --pathname DateFilter` to create the scaffolding for a component called `DateFilter`, in which you would implement the UI component as a list of buttons representing data-range filters that would filter a customer's product purchases when clicked: last month, last three months, last year, and so on.
+
+```bash
+npx elsie generate component --pathname <MyUiComponent>
+```
+
+After running this command, the drop-in CLI generates the following files:
+
+```console
+🆕 src/components/DateFilter/DateFilter.css created
+🆕 src/components/DateFilter/DateFilter.stories.tsx created
+🆕 src/components/DateFilter/DateFilter.test.tsx created
+🆕 src/components/DateFilter/DateFilter.tsx created
+🆕 src/components/DateFilter/index.ts created
+🆕 src/components/index.ts created
+~/purchase-history [main] »
+```
+
+These files are not only generated with the appropriate names, but they are completely preconfigured to work together as a unit. For example, the `DateFilter` component is automatically imported into `src/components/index.ts` so you can start referencing the component throughout your project.
+
+And if you run `npm run dev` again, you'll see your new component in the Storybook UI, configured with an example and best practices to help you get started with Storybook.
+
+### Generate a new API Function
+
+Start by executing the following command, replacing `<myApiFunction>` with the name of the API function you want to add:
+
+```bash
+npx elsie generate api --pathname <myApiFunction>
+```
+
+For the `purchase-history` example drop-in, you might want to add a filter function that handles filtering the purchase history by date-ranges, such as `filterByDateRange`. In this case, you would run the following command:
+
+
+```bash
+npx elsie generate api --pathname filterByDateRange
+```
+
+This generates a new API function in the `src/api` directory, preconfigured with a test file and a default implementation. Full details about API function development will be documented as soon as possible.
+
+### Generate a drop-in Container
+
+Start by executing the following command, replacing `<MyDropinContainer>` with the name of the container you want to add:
+
+```bash
+npx elsie generate container --pathname <MyDropinContainer>
+```
+
+For the `purchase-history` example drop-in, the command used to generate its container could be: `npx elsie generate container --pathname PurchaseHistoryContainer`.
+
+This generates a new Container in the `src/containers` directory, preconfigured with a test file and a default implementation. Full details about container development will be documented as soon as possible.
+
+### Run unit tests
+
+Unit tests are also preconfigured for you. Run the following command to execute the basic default tests, and add to them as you build your frontend.
+
+```bash
+yarn test
+npm run test
+pnpm run test
+```
+
+### Build production bundles
+
+When you're ready to deploy your frontend, run the following command to build production bundles. Like everything else in the SDK, the basic process is configured for you, but you can customize it as you develop.
+
+```bash
+yarn build
+npm run build
+pnpm run build
+```
+
+</Steps>
+
+</Unstyled>

package/src/docs/slots.mdx

@@ -0,0 +1,211 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+
+<Meta title="Utilities/Slots" />
+<Unstyled>
+
+# Slots
+
+A Slot is a high-level interface for developers to define and manage dynamic content insertion within drop-in components.
+
+## Context
+
+The context is defined during implementation of a drop-in and can be used to pass data and functions to the slot.
+
+### Pre-built Methods
+
+- **dictionary**: The dictionary of the selected language.
+- **replaceWith**: A function to replace the slot's content with a new HTML element.
+- **appendChild**: A function to append a new HTML element to the slot's content.
+- **prependChild**: A function to prepend a new HTML element to the slot's content.
+- **appendSibling**: A function to append a new HTML element after the slot's content.
+- **prependSibling**: A function to prepend a new HTML element **before** the slot's content.
+- **getSlotElement**: A function to get a slot element.
+- **onChange**: A function to listen to changes in the slot's context.
+
+---
+
+## Implementing a new slot
+
+The `<Slot />` component is used to define a slot in a container. It receives a name and a slot object with the following properties:
+
+### name
+
+The name of the slot in _PascalCase_. `string` (required).
+
+### slot (required)
+
+- `ctx`: An object representing the context of the slot, including methods for manipulating the slot's content.
+
+The slot property, which is implemented as a promise function, provides developers with the flexibility to dynamically generate and manipulate content within slots. 
+However, it's important to note that this promise is render-blocking, meaning that the component will not render until the promise is resolved.
+
+### context
+
+The context property in the Slot component lets developers pass extra information or functionality to customize how the slot
+behaves or interacts with the application. This information is accessible within the slot's rendering logic, allowing for
+tailored slot behavior based on specific needs or application states.
+
+### render
+
+The render property in the Slot component lets developers define how the content within the slot should be displayed and should be used when developers
+need fine-grained control over what content appears within the slot.
+It's particularly useful when using custom slot methods (see Privates below) in scenarios where the content to be displayed within the slot is dynamic and may depend on
+properties passed to another component.
+
+### children
+
+The children property in the Slot component represents the content that is passed directly within the opening and closing tags of the Slot component.
+It allows developers to include static content directly within the slot, which will be rendered as part of the slot's contents.
+This property is useful for cases where the content within the slot is static or does not need to be dynamically generated by the slot.
+
+```tsx
+// MyContainer.tsx (Drop-in)
+
+import { HTMLAttributes } from 'preact/compat';
+import { Container, Slot, SlotProps } from '@adobe/elsie/lib';
+
+export interface MyContainerProps extends HTMLAttributes<HTMLDivElement> {
+  slots?: {
+    MyOpenSlot?: SlotProps<{
+      // MyOpenSlot Context
+      data: MyContainerData;
+    }>;
+  };
+}
+
+export const MyContainer: Container<MyContainerProps> = ({
+  slots,
+  children,
+  ...props
+}) => {
+  // ...
+
+  return (
+    <div {...props}>
+      <Slot name="MyOpenSlot" slot={slots?.MyOpenSlot} context={{ data }} />
+    </div>
+  );
+};
+```
+
+&nbsp;
+
+```js
+// blocks/my-block.js (storefront)
+
+provider.render(MyContainer, {
+  slots: {
+    MyOpenSlot: async (ctx) => {
+      // create a new HTML element
+      const element = document.createElement('div');
+      // set the innerHTML of the new element to the text from the context's data
+      element.innerHTML = ctx.data.text;
+
+      // append the new element to the slot's content
+      ctx.appendChild(element);
+
+      // ...or you could also use any of the other slot methods to manipulate the slot's content
+      // ctx.replaceWith(element);
+      // ctx.prependChild(element);
+      // ctx.appendSibling(element);
+      // ctx.prependSibling(element);
+
+      // to listen and react to changes in the slot's context (lifecycle)
+      ctx.onChange((next) => {
+        // update the innerHTML of the new element to the new text from the context's data
+        element.innerHTML = ctx.data.text;
+      });
+    },
+  },
+});
+```
+
+## Privates
+
+The `<Slot />` component has a private interface that serves as a mechanism for managing internal
+complexity and promoting clean, modular design within the Slot component or related components.
+
+### \_registerMethod
+
+The `_registerMethod` private function is used to register a method in the slot's context which is particularly helpful in scenarios
+where dynamic behavior or interactions need to be incorporated into the Slot component.
+
+Slot Methods also include the ability to modify the slot's state or content based on external interactions or changes in application state.
+
+### \_setProps
+
+The `_setProps` private function within the Slot component is responsible for dynamically updating the properties of the slot.
+It allows developers to modify the slot's state or content based on external interactions or changes in application state,
+triggering re-renders of the slot component with updated properties.
+
+### \_htmlElementToVNode
+
+The `_htmlElementToVNode` private function in the Slot component converts HTML elements into virtual DOM nodes (VNodes),
+enabling their integration into Preact components. This conversion facilitates the dynamic insertion of HTML content
+into slots while benefiting from Preact's virtual DOM reconciliation and rendering.
+
+```tsx
+// MyContainer.tsx (Drop-in)
+
+<Slot
+  name="MyOpenSlot"
+  slot={slots?.MyOpenSlot}
+  context={{
+    // custom slot method
+    appendButton(callback) {
+      // use _registerMethod to register a method in the slot's context
+      this._registerMethod((...attrs) => {
+        // callback return the values provided by the storefront developer
+        const { text, ...buttonProps } = callback(...attrs);
+
+        const button = (
+          <Button type="button" {...buttonProps}>
+            {text}
+          </Button>
+        );
+
+        // use _setProps to update the slot's properties
+        this._setProps((prev: any) => ({
+          children: [...(prev.children || []), button],
+        }));
+      });
+    },
+  }}
+  render={(props) => {
+    // render the slot's content using props mutated by the slot's methods
+    return <Buttons>{props.children}</Buttons>;
+  }}
+/>
+```
+
+&nbsp;
+
+```js
+// blocks/my-block.js (storefront)
+
+provider.render(MyContainer, {
+  slots: {
+    // Available Slots
+    MyOpenSlot: (ctx) => {
+      ctx.appendButton: (next, state) => {
+        // use state to get the current state of the slot
+        const loading = state.get('loading');
+
+        return {
+          text: loading ? 'Loading' : 'Click me!',
+          onClick: async () => {
+            // use state to update the state of the slot
+            state.set('loading', true);
+
+            await doSomething().finally(() => {
+              state.set('loading', false);
+            });
+          },
+        };
+      },
+    },
+  },
+});
+```
+
+</Unstyled>

package/src/docs/welcome.mdx

@@ -0,0 +1,52 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+import { Flex } from '@adobe/elsie/config/storybook/components/Flex';
+import { Panel } from '@adobe/elsie/config/storybook/components/Panel';
+import { Screenshot } from '@adobe/elsie/config/storybook/components/Screenshot';
+import { Summary } from '@adobe/elsie/config/storybook/components/Summary';
+import banner from './assets/DropinBanner.png';
+
+<Meta title="Welcome" />
+<Unstyled>
+
+<Screenshot src={banner} alt="dropin SDK Banner" />
+
+<Summary>
+The **drop-in SDK** is deployed as a set of **npm packages** assembled into a completely pre-configured **starter template** to provide everything you need to build **composable** Commerce frontends. 
+</Summary>
+
+**For the frontend**, the drop-in SDK includes our design system, which provides the components and design tokens that make merchant rebranding quick and easy.
+
+**For everything else**, the drop-in SDK provides a complete framework for mounting, rendering, eventing, testing, and hydrating drop-ins with data from the Commerce backend.
+
+## Get started
+
+<Summary>
+Use our [Quick-Start tutorial](/docs/quick-start--overview) to create a fully-configured drop-in and render it in less than 10 minutes.
+</Summary>
+
+## Get to know drop-ins
+
+<Flex itemsPerRow={3}>
+<Panel footer>
+### Quick start
+Follow the quick-start guide to start building a new Commerce drop-in.
+
+[Read more](/docs/quick-start--overview)
+</Panel>
+
+<Panel footer>
+### Drop-in library components
+Explore the library of components available for your drop-in user interface.
+
+[Read more](/docs/components-overview--overview)
+</Panel>
+
+<Panel footer>
+### Drop-in Design System
+Learn how to rebrand your drop-ins using the drop-in design system.
+
+[Read more](/docs/design-overview--overview)
+</Panel>
+</Flex>
+
+</Unstyled>

package/src/i18n/en_US.json

@@ -0,0 +1,146 @@
+{
+  "Dropin": {
+    "ExampleComponentName": {
+      "item": {
+        "label": "string"
+      }
+    },
+    "Pagination": {
+      "backwardButton": {
+        "ariaLabel": "Go to previous page"
+      },
+      "forwardButton": {
+        "ariaLabel": "Go to next page"
+      }
+    },
+    "Incrementer": {
+      "decreaseLabel": "Decrease Quantity",
+      "increaseLabel": "Increase Quantity",
+      "label": "Quantity",
+      "errorMessage": "Enter a valid quantity",
+      "minQuantityMessage": "Enter at least {{minQuantity}}",
+      "maxQuantityMessage": "Maximum quantity is {{maxQuantity}}"
+    },
+    "Modal": {
+      "Close": {
+        "label": "Close"
+      }
+    },
+    "InputPassword": {
+      "placeholder": "Password",
+      "floatingLabel": "Password",
+      "buttonShowTitle": "Click to show password",
+      "buttonHideTitle": "Click to hide password"
+    },
+    "PasswordStatusIndicator": {
+      "chartTwoSymbols": "Use characters and numbers or symbols",
+      "chartThreeSymbols": "Use characters, numbers and symbols",
+      "chartFourSymbols": "Use uppercase characters, lowercase characters, numbers and symbols",
+      "messageLengthPassword": "At least {minLength} characters long"
+    },
+    "InlineAlert": {
+      "dismissLabel": "Dismiss Alert"
+    },
+    "PriceSummary": {
+      "subTotal": {
+        "label": "Subtotal",
+        "withTaxes": "Including taxes",
+        "withoutTaxes": "excluding taxes"
+      },
+      "shipping": {
+        "label": "Shipping",
+        "editZipAction": "Apply",
+        "estimated": "Estimated Shipping",
+        "estimatedDestination": "Estimated Shipping to ",
+        "destinationLinkAriaLabel": "Change destination",
+        "zipPlaceholder": "Zip Code",
+        "withTaxes": "Including taxes",
+        "withoutTaxes": "excluding taxes",
+        "alternateField": {
+          "zip": "Estimate using country/zip",
+          "state": "Estimate using country/state"
+        }
+      },
+      "taxes": {
+        "total": "Tax Total",
+        "totalOnly": "Tax",
+        "breakdown": "Taxes",
+        "showBreakdown": "Show Tax Breakdown",
+        "hideBreakdown": "Hide Tax Breakdown",
+        "estimated": "Estimated Tax"
+      },
+      "total": {
+        "estimated": "Estimated Total",
+        "label": "Total",
+        "withoutTax": "Total excluding taxes"
+      }
+    },
+    "ProgressSpinner": {
+      "updating": {
+        "label": "Item is updating"
+      },
+      "updatingChildren": {
+        "label": "Items are updating"
+      }
+    },
+    "PriceRange": {
+      "from": {
+        "label": "From"
+      },
+      "to": {
+        "label": "to"
+      },
+      "asLowAs": {
+        "label": "As low as"
+      }
+    },
+    "Swatches": {
+      "outOfStock": {
+        "label": "out of stock swatch"
+      },
+      "selected": {
+        "label": "swatch selected"
+      },
+      "swatch": {
+        "label": "swatch"
+      }
+    },
+    "Accordion": {
+      "open": {
+        "label": "Open"
+      },
+      "close": {
+        "label": "Close"
+      }
+    },
+    "CartItem": {
+      "each": {
+        "label": "each"
+      },
+      "pricePerItem": {
+        "label": "price per item"
+      },
+      "quantity": {
+        "label": "Quantity"
+      },
+      "remove": {
+        "label": "Remove {product} from the cart"
+      },
+      "removeDefault": {
+        "label": "Remove item from the cart"
+      },
+      "taxIncluded": {
+        "label": "incl. VAT"
+      },
+      "taxExcluded": {
+        "label": "excl. tax"
+      },
+      "updating": {
+        "label": "{product} is updating"
+      }
+    },
+    "InputDate": {
+      "picker": "Select a date"
+    }
+  }
+}

package/src/i18n/index.ts

@@ -0,0 +1,17 @@
+import { deepmerge } from '@adobe/elsie/lib';
+import en_US from '@adobe/elsie/i18n/en_US.json';
+
+export type Lang = 'en_US';
+
+export const definition = {
+  default: en_US,
+  en_US,
+};
+
+// https://github.com/synacor/preact-i18n
+// eslint-disable-next-line no-restricted-imports
+export * from 'preact-i18n';
+
+export const getDefinitionByLanguage = (lang: Lang) => {
+  return deepmerge(definition.default, definition[lang] || {});
+};

package/src/icons/Add.svg

@@ -0,0 +1,9 @@
+<svg id="Icon_Add_Base" data-name="Icon – Add – Base" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <g id="Large">
+    <rect id="Placement_area" data-name="Placement area" width="24" height="24" fill="#fff" opacity="0"/>
+    <g id="Add_icon" data-name="Add icon" transform="translate(9.734 9.737)">
+      <line vector-effect="non-scaling-stroke" id="Line_579" data-name="Line 579" y2="12.7" transform="translate(2.216 -4.087)" fill="none" stroke="currentColor"/>
+      <line vector-effect="non-scaling-stroke" id="Line_580" data-name="Line 580" x2="12.7" transform="translate(-4.079 2.263)" fill="none" stroke="currentColor"/>
+    </g>
+  </g>
+</svg>