@adobe-commerce/elsie 1.0.0-alpha1

package/.elsie.js

@@ -0,0 +1,12 @@
+module.exports = {
+  name: 'Base',
+  components: [
+    {
+      id: 'Components',
+      root: './src/components',
+      importAliasRoot: '@adobe/elsie/components',
+      cssPrefix: 'dropin',
+      default: true,
+    },
+  ],
+};

package/.eslintrc.js

@@ -0,0 +1,9 @@
+const baseConfig = require('./config/eslint');
+
+module.exports = {
+  ...baseConfig,
+  rules: {
+    ...baseConfig.rules,
+    'no-restricted-imports': 'off'
+  }
+};

package/README.md

@@ -0,0 +1,52 @@
+# Elsie
+
+## CLI Commands
+
+### Run Storybook and serve with hot reload
+
+```bash
+yarn dev
+```
+
+### Run tests with Jest
+
+```bash
+yarn test
+```
+
+### Link CLI (development mode)
+
+```bash
+yarn link --global
+```
+
+```bash
+elsie --help
+```
+
+### Generate a new UI Component
+
+```bash
+elsie generate component -n <ComponentName>
+```
+
+### Generate a new UI Patterns
+
+```bash
+elsie generate component -n <ComponentName> -g Patterns
+```
+
+# Dependencies
+
+These build dependencies are needed to develop your Storefront SDK project. Note: you may opt not to use it if you want to keep control of dependencies on your own.
+
+## Dependencies Included:
+
+- **Storybook** and addons
+- **Vite** and plugins
+- **TypeScript** and type definitions
+- **Jest** and presets
+- **rimraf**
+- **dotenv**
+
+For a detail manifest of dependencies see [/packages/elsie/package.json]

package/__mocks__/svg.js

@@ -0,0 +1 @@
+export * from '../src/icons';

package/bin/builders/build/index.js

@@ -0,0 +1,20 @@
+const path = require('path');
+
+module.exports = async function generateResourceBuilder({ argv }) {
+  const { build } = await import('vite');
+
+  const configFile =
+    argv?.config ?? path.resolve(__dirname, '../../../config/vite.mjs');
+
+  const outDir = argv?.outDir ?? 'dist';
+
+  const isProd = process.env.NODE_ENV !== 'development';
+
+  await build({
+    mode: isProd ? 'production' : 'development',
+    build: { emptyOutDir: true, outDir },
+    clearScreen: true,
+    configFile,
+  });
+  process.exit(0);
+};

package/bin/builders/generate/api/index.js

@@ -0,0 +1,65 @@
+const path = require('path');
+const fs = require('fs');
+const writeFile = require('../../../lib/write-file');
+const writeParentIndex = require('../../../lib/write-parent-index');
+const config = require('../../../lib/config');
+const m = require('../../../lib/log-message');
+
+// Templates
+const templateFunction = require('./templates/function');
+const templateStory = require('./templates/story');
+const templateTest = require('./templates/unit-test');
+const templateIndex = require('./templates/index');
+
+module.exports = async function newApiBuilder({ pathname, force }) {
+  try {
+    const { name, api } = config();
+
+    const { root, importAliasRoot } = api;
+
+    const basename = path.basename(pathname);
+
+    const importPath = importAliasRoot && `${importAliasRoot}/${basename}`;
+
+    const dir = path.resolve(process.cwd(), root, pathname.replace(/^\//, ''));
+
+    // Create new directory
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    // Write Storybook Story file
+    await writeFile(
+      path.resolve(dir, `${basename}.mdx`),
+      templateStory({ name, basename, pathname, importPath }),
+      force
+    );
+
+    // Write Jest Test file
+    await writeFile(
+      path.resolve(dir, `${basename}.test.ts`),
+      templateTest({ name, basename, pathname, importPath }),
+      force
+    );
+
+    // Write Function file
+    await writeFile(
+      path.resolve(dir, `${basename}.ts`),
+      templateFunction({ basename, importPath }),
+      force
+    );
+
+    // Write Index file
+    await writeFile(
+      path.resolve(dir, 'index.ts'),
+      templateIndex({ importPath, basename }),
+      force
+    );
+
+    // Update parent index.ts
+    writeParentIndex(path.resolve(dir, '../index.ts'), {
+      pathname,
+      importAliasRoot,
+    });
+  } catch (error) {
+    console.error(m(error, 'error'));
+  }
+};

package/bin/builders/generate/api/templates/function.js

@@ -0,0 +1,9 @@
+const { stripIndent } = require('common-tags');
+
+module.exports = ({ basename }) => {
+  return `${stripIndent`      
+      export const ${basename} = () => { 
+        return 'Howdy!';
+      } 
+  `}\n`;
+};

package/bin/builders/generate/api/templates/index.js

@@ -0,0 +1,7 @@
+const { source } = require('common-tags');
+
+module.exports = ({ basename, importPath = '.' }) => {
+  return `${source`
+    export * from '${importPath}/${basename}';
+  `}\n`;
+};

package/bin/builders/generate/api/templates/story.js

@@ -0,0 +1,23 @@
+const { source } = require('common-tags');
+
+module.exports = ({ pathname, basename, importPath = '.' }) => {
+  return `${source`
+    import { Meta } from '@storybook/blocks';
+
+    <Meta title="API/${pathname}" />
+    
+    # ${basename}
+
+    A function that returns "Howdy World!".
+
+    \`\`\`ts
+    import { ${basename} } from '${importPath}';
+    \`\`\`
+
+    ## Usage
+
+    \`\`\`ts
+    ${basename}();
+    \`\`\`
+  `}\n`;
+};

package/bin/builders/generate/api/templates/unit-test.js

@@ -0,0 +1,15 @@
+const { source } = require('common-tags');
+
+module.exports = ({ name, basename, pathname, importPath = '.' }) => {
+  return `${source`
+        import { ${basename} } from '${importPath}';
+
+        describe('${name}/api/${pathname}', () => {
+          test('returns value', () => {
+            const value = ${basename}();
+
+            expect(value).toEqual('Howdy!');
+          });
+        });
+    `}\n`;
+};

package/bin/builders/generate/component/index.js

@@ -0,0 +1,87 @@
+const path = require('path');
+const fs = require('fs');
+const writeFile = require('../../../lib/write-file');
+const writeParentIndex = require('../../../lib/write-parent-index');
+const config = require('../../../lib/config')();
+const m = require('../../../lib/log-message');
+
+// Templates
+const templateComponent = require('./templates/Component');
+const templateStyles = require('./templates/css');
+const templateStory = require('./templates/stories');
+const templateTest = require('./templates/unit-test');
+const templateIndex = require('./templates/index');
+
+module.exports = async function newComponentBuilder({
+  pathname,
+  group,
+  force,
+}) {
+  try {
+    const componentGroup = config.components.find((x) => x.id === group);
+
+    if (!componentGroup) return null;
+
+    const name = config.name;
+
+    const { root, importAliasRoot, skipCSS } = componentGroup;
+
+    const cssPrefix = componentGroup.cssPrefix
+      ? `${componentGroup.cssPrefix}-`
+      : '';
+
+    const basename = path.basename(pathname);
+
+    const importPath = importAliasRoot && `${importAliasRoot}/${basename}`;
+
+    const dir = path.resolve(process.cwd(), root, pathname.replace(/^\//, ''));
+
+    // Create new directory
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    if (!skipCSS) {
+      // Write CSS
+      await writeFile(
+        path.resolve(dir, `${basename}.css`),
+        templateStyles({ basename, cssPrefix }),
+        force
+      );
+    }
+
+    // Write Storybook Stories file
+    await writeFile(
+      path.resolve(dir, `${basename}.stories.tsx`),
+      templateStory({ name, basename, pathname, group, importPath }),
+      force
+    );
+
+    // Write Jest Test file
+    await writeFile(
+      path.resolve(dir, `${basename}.test.tsx`),
+      templateTest({ name, basename, pathname, group, importPath, cssPrefix }),
+      force
+    );
+
+    // Write Component file
+    await writeFile(
+      path.resolve(dir, `${basename}.tsx`),
+      templateComponent({ basename, importPath, skipCSS, cssPrefix }),
+      force
+    );
+
+    // Write Index file
+    await writeFile(
+      path.resolve(dir, 'index.ts'),
+      templateIndex({ basename, importPath }),
+      force
+    );
+
+    // Update parent index.ts
+    writeParentIndex(path.resolve(dir, '../index.ts'), {
+      pathname,
+      importAliasRoot,
+    });
+  } catch (error) {
+    console.error(m(error, 'error'));
+  }
+};

package/bin/builders/generate/component/templates/Component.js

@@ -0,0 +1,43 @@
+const { stripIndent } = require('common-tags');
+const { hyphenatedName } = require('../../../../lib/string');
+
+module.exports = ({ basename, importPath = '.', skipCSS, cssPrefix }) => {
+  const _name = hyphenatedName(basename);
+
+  if (skipCSS)
+    return `${stripIndent`
+      import { FunctionComponent } from 'preact';
+      import { HTMLAttributes } from 'preact/compat';
+
+      export interface ${basename}Props extends HTMLAttributes<HTMLDivElement> {}
+      
+      export const ${basename}: FunctionComponent<${basename}Props> = ({ children, ...props }) => {
+        return (
+          <div {...props}>
+            {children}
+          </div>
+        );
+      };    
+  `}\n`;
+
+  return `${stripIndent`
+      import { FunctionComponent } from 'preact';
+      import { HTMLAttributes } from 'preact/compat';
+      import { classes } from '@adobe/elsie/lib';
+      import '${importPath}/${basename}.css';
+
+      export interface ${basename}Props extends HTMLAttributes<HTMLDivElement> {}
+      
+      export const ${basename}: FunctionComponent<${basename}Props> = ({
+        className,
+        children,
+        ...props
+      }) => {
+        return (
+          <div {...props} className={classes(['${cssPrefix}${_name}', className])}>
+            {children}
+          </div>
+        );
+      };    
+  `}\n`;
+};

package/bin/builders/generate/component/templates/css.js

@@ -0,0 +1,24 @@
+const { source } = require('common-tags');
+const { hyphenatedName } = require('../../../../lib/string');
+
+module.exports = ({ basename, cssPrefix }) => {
+  const _name = hyphenatedName(basename);
+
+  return `${source`
+      /* https://cssguidelin.es/#bem-like-naming */
+
+      /* .${cssPrefix}${_name} { } */
+      
+      /* Medium (portrait tablets and large phones, 768px and up) */
+      /* @media only screen and (min-width: 768px) { } */
+      
+      /* Large (landscape tablets, 1024px and up) */
+      /* @media only screen and (min-width: 1024px) { } */
+      
+      /* XLarge (laptops/desktops, 1366px and up) */
+      /* @media only screen and (min-width: 1366px) { } */
+      
+      /* XXlarge (large laptops and desktops, 1920px and up) */
+      /* @media only screen and (min-width: 1920px) { } */
+  `}\n`;
+};

package/bin/builders/generate/component/templates/index.js

@@ -0,0 +1,8 @@
+const { source } = require('common-tags');
+
+module.exports = ({ basename, importPath = '.' }) => {
+  return `${source`
+    export * from '${importPath}/${basename}';
+    export { ${basename} as default } from '${importPath}/${basename}';
+  `}\n`;
+};

package/bin/builders/generate/component/templates/stories.js

@@ -0,0 +1,46 @@
+const { source } = require('common-tags');
+
+module.exports = ({ name, pathname, basename, group, importPath = '.' }) => {
+  return `${source`
+    // https://storybook.js.org/docs/7.0/preact/writing-stories/introduction
+    import type { Meta, StoryObj } from '@storybook/preact';
+    import { ${basename} as component, ${basename}Props } from '${importPath}';
+    
+    /**
+     * Use ${basename}s to [replace this text with components purpose].
+     */
+    const meta: Meta<${basename}Props> = {
+      title: '${`${group}/`}${pathname}',
+      component,
+      argTypes: {
+        children: {
+          description: 'Add text to the ${basename}.',
+          table: {
+            type: { summary: 'string' },
+            defaultValue: { summary: '${basename} defaultValue for children.' },
+          },
+        },
+        onClick: {
+          description: 'Add a click handler.',
+          table: {
+            type: { summary: 'function' },
+          },
+          action: 'onClick',
+        },
+      },
+    };
+
+    export default meta;
+
+    type Story = StoryObj<${basename}Props>;
+
+    /**
+     * <${basename}>👋 Hello from your new ${basename} story!</${basename}>
+     */
+    export const ${basename}: Story = {
+      args: {
+        children: "👋 Hello from your new ${basename} story!",
+      },
+    };
+  `}\n`;
+};

package/bin/builders/generate/component/templates/unit-test.js

@@ -0,0 +1,19 @@
+const { source } = require('common-tags');
+
+module.exports = ({ name, basename, pathname, group, importPath = '.' }) => {
+  return `${source`
+        /** https://preactjs.com/guide/v10/preact-testing-library/ */
+
+        import { render } from '@adobe/elsie/lib/tests';
+
+        import { ${basename} } from '${importPath}';
+
+        describe('${name}/${group}/${pathname}', () => {
+          test('renders', () => {
+            const { container } = render(<${basename} />);
+
+            expect(!!container).toEqual(true);
+          });
+        });
+    `}\n`;
+};

package/bin/builders/generate/config/index.js

@@ -0,0 +1,54 @@
+const path = require('path');
+const fs = require('fs/promises');
+const m = require('../../../lib/log-message');
+const writeFile = require('../../../lib/write-file');
+
+const configTemplate = require('./templates/elsie');
+
+module.exports = async function newConfigBuilder({ name, force }) {
+  const filename = path.resolve(process.cwd(), './.elsie.js');
+
+  const importPath = `@/${name.toLowerCase()}`;
+
+  const content = configTemplate({ name, importPath });
+
+  const value = `${importPath}/*`;
+
+  const fileWritten = await writeFile(filename, content, force);
+
+  if (!fileWritten) return;
+
+  // Update tsconfig.json alias
+  try {
+    const tsconfigPath = path.resolve(process.cwd(), './tsconfig.json');
+
+    const file = await fs.open(tsconfigPath, 'r+');
+
+    const fileBuffer = await fs.readFile(file, 'utf-8');
+    const tsconfig = JSON.parse(fileBuffer);
+
+    if (tsconfig.compilerOptions?.paths[value]) {
+      console.log(m(`\x1b[33m$tsconfig.json \x1b[0mis up to date`, 'success'));
+      return;
+    }
+
+    const newTsConfig = {
+      ...tsconfig,
+      compilerOptions: {
+        ...tsconfig.compilerOptions,
+        paths: { ...tsconfig.compilerOptions?.paths, [value]: ['./src/*'] },
+      },
+    };
+
+    await fs.writeFile(tsconfigPath, JSON.stringify(newTsConfig, null, 2));
+
+    console.log(m(`\x1b[33mtsconfig.json \x1b[0mupdated`, 'updated'));
+  } catch {
+    console.log(
+      m(
+        `Update your \x1b[33mtsconfig.json\x1b[0m to include path \x1b[33m"paths": { "${value}": ["./src/*'] }\x1b[0m`,
+        'warning'
+      )
+    );
+  }
+};

package/bin/builders/generate/config/templates/elsie.js

@@ -0,0 +1,29 @@
+const { source } = require('common-tags');
+
+module.exports = ({ name, importPath }) =>
+  `${source`
+    module.exports = {
+      name: '${name}',
+      api: {
+        root: './src/api',
+        importAliasRoot: '${importPath}/api',
+      },
+      components: [
+        {
+          id: 'Components',
+          root: './src/components',
+          importAliasRoot: '${importPath}/components',
+          cssPrefix: '${name.toLowerCase()}',
+          default: true,
+        },
+      ],
+      containers: {
+        root: './src/containers',
+        importAliasRoot: '${importPath}/containers',
+      },
+      schema: {
+        endpoint: process.env.ENDPOINT,
+        headers: {}
+      }
+    };
+`}\n`;

package/bin/builders/generate/container/index.js

@@ -0,0 +1,65 @@
+const path = require('path');
+const fs = require('fs');
+const writeFile = require('../../../lib/write-file');
+const writeParentIndex = require('../../../lib/write-parent-index');
+const config = require('../../../lib/config')();
+const m = require('../../../lib/log-message');
+
+// Templates
+const templateComponent = require('./templates/Component');
+const templateStory = require('./templates/stories');
+const templateTest = require('./templates/unit-test');
+const templateIndex = require('./templates/index');
+
+module.exports = async function newContainerBuilder({ pathname, force }) {
+  try {
+    const name = config.name;
+
+    const { root, importAliasRoot } = config.containers;
+
+    const basename = path.basename(pathname);
+
+    const importPath = importAliasRoot && `${importAliasRoot}/${basename}`;
+
+    const dir = path.resolve(process.cwd(), root, pathname.replace(/^\//, ''));
+
+    // Create new directory
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    // Write Storybook Stories file
+    await writeFile(
+      path.resolve(dir, `${basename}.stories.tsx`),
+      templateStory({ basename, pathname, importPath }),
+      force
+    );
+
+    // Write Jest Test file
+    await writeFile(
+      path.resolve(dir, `${basename}.test.tsx`),
+      templateTest({ name, basename, pathname, importPath }),
+      force
+    );
+
+    // Write Container file
+    await writeFile(
+      path.resolve(dir, `${basename}.tsx`),
+      templateComponent({ basename, importPath }),
+      force
+    );
+
+    // Write Index file
+    await writeFile(
+      path.resolve(dir, 'index.ts'),
+      templateIndex({ basename, importPath }),
+      force
+    );
+
+    // Update parent index.ts
+    writeParentIndex(path.resolve(dir, '../index.ts'), {
+      pathname,
+      importAliasRoot,
+    });
+  } catch (error) {
+    console.error(m(error, 'error'));
+  }
+};

package/bin/builders/generate/container/templates/Component.js

@@ -0,0 +1,18 @@
+const { stripIndent } = require('common-tags');
+
+module.exports = ({ basename }) => {
+  return `${stripIndent`
+    import { HTMLAttributes } from 'preact/compat';
+    import { Container } from '@adobe/elsie/lib';
+
+    export interface ${basename}Props extends HTMLAttributes<HTMLDivElement> {}
+        
+    export const ${basename}: Container<${basename}Props> = ({ children, ...props }) => {
+      return (
+        <div {...props}>
+          {children}
+        </div>
+      );
+    };    
+  `}\n`;
+};

package/bin/builders/generate/container/templates/index.js

@@ -0,0 +1,8 @@
+const { source } = require('common-tags');
+
+module.exports = ({ basename, importPath = '.' }) => {
+  return `${source`
+    export * from '${importPath}/${basename}';
+    export { ${basename} as default } from '${importPath}/${basename}';
+  `}\n`;
+};

package/bin/builders/generate/container/templates/stories.js

@@ -0,0 +1,34 @@
+const { source } = require('common-tags');
+
+module.exports = ({ pathname, basename, importPath = '.' }) => {
+  return `${source`
+    // https://storybook.js.org/docs/7.0/preact/writing-stories/introduction
+    import type { Meta, StoryObj } from '@storybook/preact';
+    import { ${basename} as component, ${basename}Props } from '${importPath}';
+
+    const meta: Meta<${basename}Props> = {
+      title: 'Containers/${pathname}',
+      component,
+      tags: ['autodocs'],
+      parameters: {
+        layout: 'centered', // centered | fullscreen
+      },
+    };
+
+    export default meta;
+
+    type Story = StoryObj<${basename}Props>;
+
+    /**
+     * \`\`\`ts
+     * import { ${basename} } from '${importPath}';
+     * \`\`\`
+     */
+
+    export const ${basename}: Story = {
+      args: {
+        children: "👋 Howdy, I'm Howdy!",
+      },
+    };
+  `}\n`;
+};