@adobe-commerce/elsie 1.0.0-alpha1

package/src/docs/Design/typography.mdx

@@ -0,0 +1,126 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+import { Block, TokenDefinitions } from './designBlocks.jsx';
+import typeData from '@adobe/storefront-design/base/typography/typography.json';
+import { getTokenData } from './getTokenData';
+export const tokenData = getTokenData(typeData);
+export const tokenNames = tokenData.map((token) => token.name);
+
+<Meta title="Design/Typography" />
+<Unstyled>
+
+export const SampleText = ({ font, spacing }) => {
+  return (
+    <div style={{ font: `var(${font})`, letterSpacing: `var(${spacing})` }}>
+      The quick brown fox jumps over the lazy dog
+    </div>
+  );
+};
+
+export const Typography = ({ prefix }) => (
+  <>
+    <TokenDefinitions
+      tokenData={tokenData.filter((data) => data.name.startsWith(prefix))}
+    />
+    <Block style={{ padding: 'var(--spacing-xsmall)' }}>
+      <SampleText
+        font={`${prefix}-font`}
+        spacing={`${prefix}-letter-spacing`}
+      />
+    </Block>
+  </>
+);
+
+# Typography
+
+Use typography scale set to present your design and content as clearly and efficiently as possible.
+These text style perfeclty fit for 4px grid and go well with each other.
+
+## Base
+
+<Typography prefix="--type-base-font-family" />
+
+## Display
+
+### Display 1
+
+<Typography prefix="--type-display-1" />
+
+### Display 2
+
+<Typography prefix="--type-display-2" />
+
+### Display 3
+
+<Typography prefix="--type-display-3" />
+
+## Headlines
+
+### Headline 1
+
+<Typography prefix="--type-headline-1" />
+
+### Headline 2
+
+#### Default
+
+<Typography prefix="--type-headline-2-default" />
+
+#### Strong
+
+<Typography prefix="--type-headline-2-strong" />
+
+## Body
+
+### Body 1
+
+#### Default
+
+<Typography prefix="--type-body-1-default" />
+
+#### Strong
+
+<Typography prefix="--type-body-1-strong" />
+
+#### Emphasized
+
+<Typography prefix="--type-body-1-emphasized" />
+
+### Body 2
+
+#### Default
+
+<Typography prefix="--type-body-2-default" />
+
+#### Strong
+
+<Typography prefix="--type-body-2-strong" />
+
+#### Emphasized
+
+<Typography prefix="--type-body-2-emphasized" />
+
+## Button
+
+### Button 1
+
+<Typography prefix="--type-button-1" />
+
+### Button 2
+
+<Typography prefix="--type-button-2" />
+
+## Details
+
+### Caption 1
+
+<Typography prefix="--type-details-caption-1" />
+
+### Caption 2
+
+<Typography prefix="--type-details-caption-2" />
+
+### Overline
+
+<Typography prefix="--type-details-overline" />
+
+</Unstyled>

package/src/docs/Utilities/classList.mdx

@@ -0,0 +1,52 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+
+<Meta title="Utilities/classList" />
+<Unstyled>
+
+# classes(classList)
+
+This function takes in an array of classes and returns a string of space separated entries that can be used for CSS classname assignments.
+
+## Params
+
+`classList`
+: An array containing strings or `<string,boolean>` arrays
+
+## Returns
+
+Returns a string of space separated entries that can be used for CSS classname assignments.
+
+## Examples
+
+```ts
+import { classes } from '@adobe/elsie/lib';
+
+type ClassList = Array<string | [string, boolean] | undefined>;
+
+const classList: ClassList = ['class-1', 'class-2', 'class-3'];
+
+const result = classes(classList);
+
+console.log(result); // "class-1 class-2 class-3"
+```
+
+You can use a `<string,boolean>` array to control whether a class should be included or omitted from the final classes list.
+
+```ts
+import { classes } from '@adobe/elsie/lib';
+
+type ClassList = Array<string | [string, boolean] | undefined>;
+
+const classList: ClassList = [
+  'class-1',
+  ['class-2', true],
+  ['class-3', false],
+  'class-4',
+];
+
+const result = classes(classList);
+
+console.log(result); // "class-1 class-2 class-4"
+```
+
+</Unstyled>

package/src/docs/Utilities/debounce.mdx

@@ -0,0 +1,49 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+
+<Meta title="Utilities/debounce" />
+<Unstyled>
+
+# debounce(fn, ms)
+
+This function provides a way to delay callback execution or prevent overcalling a function until certain conditions are met.
+
+## Params
+
+`fn`
+: The callback function to be executed
+
+`ms`
+: Time(in milliseconds) to delay callback execution
+
+## Returns
+
+A debounce version of the original callback function.
+This function can be treated like the original callback, except when called, the delay timer resets.
+
+## Examples
+
+```ts
+import { debounce } from '@adobe/elsie/ore/lib';
+
+const debouncedLog = debounce(console.log, 500);
+
+debouncedLog('Do not log this string');
+
+// Wait 250ms
+
+debouncedLog('Do not log this string'); // Resets delay timer
+
+// Wait 250ms
+
+debouncedLog('Do not log this string'); // Resets delay timer
+
+// Wait 250ms
+
+debouncedLog('Log this string'); // Resets delay timer
+
+// Wait 500ms
+
+// 'Log this string' is logged to the console and no other messages have been logged
+```
+
+</Unstyled>

package/src/docs/Utilities/deepmerge.mdx

@@ -0,0 +1,12 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+
+<Meta title="Utilities/deepmerge" />
+<Unstyled>
+
+# deepmerge
+
+Merges the enumerable properties of two or more objects deeply.
+
+See: https://www.npmjs.com/package/deepmerge
+
+</Unstyled>

package/src/docs/Utilities/getFormErrors.mdx

@@ -0,0 +1,41 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+
+<Meta title="Utilities/getFormErrors" />
+<Unstyled>
+
+# getFormErrors(form)
+
+Returns every form error in an HTML form element.
+
+## Params
+
+`form`
+: An HTMLFormElement
+
+## Returns
+
+A JavaScript object containing the form errors
+
+## Examples
+
+```html
+<form>
+  <input name="foo" required value="Foo" />
+  <input name="bar" required />
+  <input name="age" type="number" value="uno" />
+  <input name="website" type="url" value="url" />
+  <input name="e-mail" type="email" value="email@" />
+</form>
+```
+
+```ts
+import { getFormErrors } from '@adobe/elsie/ore/lib';
+
+const formElement = container.querySelector('form') as HTMLFormElement;
+
+const errors = getFormErrors(formElement);
+
+console.log(errors); // { bar: 'Constraints not satisfied', website: 'Constraints not satisfied', 'e-mail': 'Constraints not satisfied', }
+```
+
+</Unstyled>

package/src/docs/Utilities/getFormValues.mdx

@@ -0,0 +1,38 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+
+<Meta title="Utilities/getFormValues" />
+<Unstyled>
+
+# getFormValues(form)
+
+Transforms the data in an HTML form element into a JavaScript object.
+
+## Params
+
+`form`
+: An HTMLFormElement
+
+## Returns
+
+A JavaScript object containing the form data
+
+## Examples
+
+```html
+<form>
+  <input name="foo" required value="Foo" />
+  <input name="bar" required value="Bar" />
+</form>
+```
+
+```ts
+import { getFormValues } from '@adobe/elsie/ore/lib';
+
+const formElement = container.querySelector('form') as HTMLFormElement;
+
+const values = getFormValues(formElement);
+
+console.log(values); // { bar: 'Bar', foo: 'Foo' }
+```
+
+</Unstyled>

package/src/docs/cli-usage.mdx

@@ -0,0 +1,181 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+
+<Meta title="CLI usage" />
+<Unstyled>
+
+# CLI usage
+
+To see all the available CLI commands in the terminal, use the `--help` flag:
+
+```bash
+npx elsie --help
+```
+
+## `gql`
+
+The `gql` command can generate types and mocks for your GraphQL API and Operations. Files will
+be generated in `<domain package root>/src/__generated__/`.
+
+To use it, you must first configure your `.elsie.js` with the necessary values:
+
+```js
+// For Adobe Commerce Catalog Service
+schema: {
+    endpoint: "https://catalog-service-sandbox.adobe.io/graphql",
+    headers: {
+        "MAGENTO-ENVIRONMENT-ID": "..."
+        "MAGENTO-STORE-VIEW-CODE": "..."
+        "MAGENTO-WEBSITE-CODE": "..."
+        "MAGENTO-STORE-CODE": "..."
+        "MAGENTO-CUSTOMER-GROUP": "..."
+        "API-KEY": "..."
+    }
+}
+```
+
+```js
+// For Adobe Mesh API
+schema: {
+    endpoint: "https://graph.adobe.io/api/.../graphql?api_key=...",
+    headers: {
+        "some-mesh-specific-header": "mesh-header-value"
+    }
+}
+```
+
+```js
+// For Adobe Commerce (non-Mesh)
+schema: {
+    endpoint: "https://commerce-backend-url.test.graphql",
+    headers: {}
+}
+```
+
+Then the following commands will generate to `src/__generated__/`:
+
+```bash
+npx elsie gql types
+```
+
+```bash
+npx elsie gql mocks
+```
+
+**Note**: In order to generate types for your _client_ operations you **must** have your operations in files using the \*.graphql.ts extension, and you **must** prepend the query string with `/\* graphql \*/` (the [magic comment](https://the-guild.dev/graphql/codegen/docs/config-reference/documents-field#graphql-tag-pluck) is case insensitive).
+
+Example:
+
+```
+export const CREATE_CART = /* graphql */ `
+  mutation createCart {
+    cartId: createEmptyCart
+  }
+`;
+```
+
+## `generate`
+
+Summary list of commands for quick copy/paste.
+
+```bash
+npx elsie generate config --name <Domain>
+```
+
+```bash
+npx elsie generate component --pathname <MyUIComponent>
+```
+
+```bash
+npx elsie generate container --pathname <MyContainer>
+```
+
+```bash
+npx elsie generate api --pathname <myApiFunction>
+```
+
+## Add Config
+
+Generate a new `.elsie.js` configuration file for the project.
+
+```bash
+npx elsie generate config --name <Domain>
+```
+
+```javascript
+module.exports = {
+  name: '<Domain>',
+  api: {
+    root: './src/api',
+    importAliasRoot: '@/<Domain>/api',
+  },
+  components: [
+    {
+      id: 'Components',
+      root: './src/components',
+      importAliasRoot: '@/<Domain>/components',
+      cssPrefix: 'dropin',
+      default: true,
+    },
+  ],
+  containers: {
+    root: './src/containers',
+    importAliasRoot: '@/<Domain>/containers',
+  },
+  schema: {
+    endpoint: process.env.ENDPOINT,
+    // Add necessary headers
+    headers: {},
+  },
+};
+```
+
+## Add Component
+
+Generate a new UI Component for the project.
+
+```bash
+npx elsie generate component --pathname <MyUIComponent>
+```
+
+```bash
+🆕 src/components/LoginForm/LoginForm.css created
+🆕 src/components/LoginForm/LoginForm.stories.tsx created
+🆕 src/components/LoginForm/LoginForm.test.tsx created
+🆕 src/components/LoginForm/LoginForm.tsx created
+🆕 src/components/LoginForm/index.ts created
+✍️ src/components/index.ts updated
+```
+
+## Add Container
+
+Generate a new Frontend Container for the project.
+
+```bash
+npx elsie generate container --pathname <MyContainer>
+```
+
+```bash
+🆕 src/containers/Login/Login.stories.tsx created
+🆕 src/containers/Login/Login.test.tsx created
+🆕 src/containers/Login/Login.tsx created
+🆕 src/containers/Login/index.ts created
+✍️ src/containers/index.ts updated
+```
+
+## Add Function
+
+Generate a new API function for the project.
+
+```bash
+npx elsie generate api --pathname <myApiFunction>
+```
+
+```console
+🆕 src/api/login/login.mdx created
+🆕 src/api/login/login.test.ts created
+🆕 src/api/login/login.ts created
+🆕 src/api/login/index.ts created
+✍️ src/api/index.ts updated
+```
+
+</Unstyled>

package/src/docs/components/overview.mdx

@@ -0,0 +1,124 @@
+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 {
+  Button,
+  ActionButton,
+  Picker,
+  Divider,
+  Card,
+  Field,
+  Incrementer,
+  Input,
+  Checkbox,
+} from '@adobe/elsie/src/components';
+
+<Meta title="Components/Overview" />
+<Unstyled>
+
+# Drop-in component library
+
+The component library provides a flexible set of interactive building blocks, such as actions, containment,
+navigation, text, and selection elements, thought to create unique tailored
+commerce user interfaces.
+
+**NOTE**: Not all components are listed below. Refer to the left-side navigation for a complete list of components.
+
+## Actions
+
+<Flex>
+<Panel header footer>
+<ActionButton>Action Button</ActionButton>
+### Action Button
+Action buttons allow users to perform an action or mark a selection in task-based options, and are ideal for buttons that aren't meant to draw a lot of attention.
+
+[Learn more](/docs/components-actionbutton--overview)
+</Panel>
+
+<Panel header footer>
+<Button variant="primary">Button</Button>
+### Button
+Buttons allow users to perform actions or to navigate to another page. They have multiple styles for each need, and call user attention to move forward in a flow.
+
+[Learn more](/docs/components-button--overview)
+</Panel>
+</Flex>
+
+## Containment
+
+<Flex>
+<Panel header footer>
+<Card variant='secondary' style={{width: '250px'}}>
+  <p style={{ font: 'var(--type-body-2-default-font)' }}>
+    This is a short description of the item and should be kept to two or
+    three lines as maximum.
+  </p>
+</Card>
+### Card
+Card is a general purpose container with different combination of semantics that can be used to hold and create related groups of information and actions.
+
+[Learn more](/docs/components-card--overview)
+</Panel>
+
+<Panel header footer>
+<div style={{ width: '200px' }}>
+  <Divider variant="secondary" />
+</div>
+### Divider
+Dividers bring clarity to a layout by grouping and dividing content by proximity, establish rhythm, and creating hierarchy.
+
+[Learn more](/docs/components-divider--overview)
+</Panel>
+</Flex>
+
+## Selection controls
+
+<Flex>
+<Panel header footer>
+<Checkbox name="checkboxField" label="Option" width="auto" />
+### Checkbox
+Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected.
+
+[Learn more](/docs/components-checkbox--overview)
+</Panel>
+
+<Panel header footer>
+<Field size="medium" label="Label" hint="Helper text">
+  <Input variant="primary" />
+</Field>
+### Field
+Form fields allow users to combine input entries with various displayed options to communicate field requirements.
+
+[Learn more](/docs/components-field--overview)
+</Panel>
+
+<Panel header footer>
+<Incrementer defaultValue="1" min={0} max={100} size="medium" />
+### Incrementer
+Incrementer enable users to make selections for numerical values in a specific range by clicking on the component or by typing a value.
+
+[Learn more](/docs/components-incrementer--overview)
+</Panel>
+
+<Panel header footer>
+<Picker options={[]} />
+### Picker
+Pickers, also known as "dropdowns" or "selects", allow users to choose from a list of options in a limited space. The list of options can change based on the context.
+
+[Learn more](/docs/components-picker--overview)
+</Panel>
+</Flex>
+
+## Text inputs
+
+<Flex>
+<Panel header footer>
+<Input variant="primary" placeholder="Placeholder" />
+### Text field
+Text fields allow users to input custom text entries with a keyboard.
+
+[Learn more](/docs/components-input--overview)
+</Panel>
+</Flex>
+
+</Unstyled>