@adobe-commerce/elsie 1.0.0-alpha1

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

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

package/bin/builders/generate/index.js

@@ -0,0 +1,283 @@
+const path = require('path');
+const { toPascalCase, toCamelCase } = require('../../lib/string');
+const m = require('../../lib/log-message');
+const validateTypeOf = require('../../lib/validate-typeof');
+const config = require('../../lib/config')();
+
+module.exports = function generateResourceBuilder(yargs) {
+  yargs
+    .usage('usage: $0 generate <resource> [options]')
+
+    // Configuration
+    .command(
+      'config',
+      'Generate configuration file',
+      (yargs) => {
+        return yargs.options({
+          name: {
+            alias: 'n',
+            decription: 'Namespace of the project',
+            type: 'string',
+            demandOption: m('Missing project name.', 'error'),
+          },
+          force: {
+            description: 'Rewrite existing file',
+            type: 'boolean',
+          },
+        });
+      },
+      require('./config')
+    )
+
+    // New Api Function
+    .command(
+      'api',
+      'Generate a new API function',
+      (yargs) => {
+        return yargs
+          .options({
+            pathname: {
+              alias: 'n',
+              demandOption: true,
+              description: 'Resource pathname',
+              type: 'string',
+            },
+            force: {
+              description: 'Rewrite existing files',
+              type: 'boolean',
+            },
+          })
+          .check((args) => {
+            if (!config) {
+              throw new Error(
+                m(
+                  'Configuration file ".elsie.js" not found. Make sure you are in the root directory of your project or generate a new one.',
+                  'error'
+                )
+              );
+            }
+
+            if (!config.name) {
+              throw new Error(
+                m(`Missing \x1b[31mname\x1b[0m in "./.elsie.js".`, 'error')
+              );
+            }
+
+            const basename = path.basename(args.pathname);
+
+            // Is the configuration valid
+            const errors = validateTypeOf(config.api, {
+              root: { required: true, type: 'string' },
+              importAliasRoot: { type: 'string' },
+            });
+
+            if (errors.length) {
+              throw new Error(
+                errors
+                  .map((e) =>
+                    m(
+                      `Invalid \x1b[31mapi.${e}\x1b[0m value "${config.api[e]}" in "./.elsie.js".`,
+                      'error'
+                    )
+                  )
+                  .join('\n')
+              );
+            }
+
+            // Check the basename is camelCase
+            if (!/^[a-z]+([A-Z]|[a-z]|[0-9]+)+$/.test(basename)) {
+              throw new Error(
+                m(
+                  `\x1b[4m${basename}\x1b[0m is not a valid API function name. Try naming your API function with camel case. i.e. \x1b[4m${toCamelCase(
+                    basename
+                  )}\x1b[0m`,
+                  'error'
+                )
+              );
+            }
+
+            return true;
+          }, false);
+      },
+      require('./api')
+    )
+
+    // New Component
+    .command(
+      'component',
+      'Generate a new UI Component',
+      (yargs) => {
+        return yargs
+          .options({
+            group: {
+              alias: 'g',
+              default: config?.components?.find((x) => x.default)?.id,
+              description: 'Components group',
+              choices: config?.components?.map((x) => x.id) || undefined,
+            },
+            pathname: {
+              alias: 'n',
+              demandOption: true,
+              description: 'Resource pathname',
+              type: 'string',
+            },
+            force: {
+              description: 'Rewrite existing files',
+              type: 'boolean',
+            },
+          })
+          .check((args) => {
+            if (!config) {
+              throw new Error(
+                m(
+                  'Configuration file ".elsie.js" not found. Make sure you are in the root directory of your project or generate a new one.',
+                  'error'
+                )
+              );
+            }
+
+            if (!args.group) {
+              throw new Error(m('Missing component group name.', 'error'));
+            }
+
+            if (!config.name) {
+              throw new Error(
+                m(`Missing \x1b[31mname\x1b[0m in "./.elsie.js".`, 'error')
+              );
+            }
+
+            const group = config.components.find((x) => x.id === args.group);
+            const basename = path.basename(args.pathname);
+
+            // Is the configuration valid
+            const errors = validateTypeOf(group, {
+              root: { required: true, type: 'string' },
+              importAliasRoot: { type: 'string' },
+              cssPrefix: {
+                required: !group.skipCSS,
+                type: 'string',
+              },
+              skipCSS: { type: 'boolean' },
+              default: { type: 'boolean' },
+            });
+
+            if (errors.length) {
+              throw new Error(
+                errors
+                  .map((e) =>
+                    m(
+                      `Invalid \x1b[31mcomponents[${group.id}].${e}\x1b[0m value "${group[e]}" in "./.elsie.js".`,
+                      'error'
+                    )
+                  )
+                  .join('\n')
+              );
+            }
+
+            // Check the basename is PascalCase
+            if (!/^([A-Z][a-z0-9]+)*[A-Z][a-z0-9]*$/.test(basename)) {
+              throw new Error(
+                m(
+                  `\x1b[4m${basename}\x1b[0m is not a valid component name. Try naming your component with pascal case. i.e. \x1b[4m${toPascalCase(
+                    basename
+                  )}\x1b[0m`,
+                  'error'
+                )
+              );
+            }
+
+            return true;
+          }, false);
+      },
+      require('./component')
+    )
+
+    // New Container
+    .command(
+      'container',
+      'Generate a new Frontend Container',
+      (yargs) => {
+        return yargs
+          .options({
+            pathname: {
+              alias: 'n',
+              demandOption: true,
+              description: 'Resource pathname',
+              type: 'string',
+            },
+            force: {
+              description: 'Rewrite existing files',
+              type: 'boolean',
+            },
+          })
+          .check((args) => {
+            if (!config) {
+              throw new Error(
+                m(
+                  'Configuration file ".elsie.js" not found. Make sure you are in the root directory of your project or generate a new one.',
+                  'error'
+                )
+              );
+            }
+
+            if (!config.containers) {
+              throw new Error(
+                m(
+                  `Missing \x1b[31mcontainers\x1b[0m in "./.elsie.js".`,
+                  'error'
+                )
+              );
+            }
+
+            if (!config.name) {
+              throw new Error(
+                m(`Missing \x1b[31mname\x1b[0m in "./.elsie.js".`, 'error')
+              );
+            }
+
+            const basename = path.basename(args.pathname);
+
+            // Is the configuration valid
+            const errors = validateTypeOf(config.containers, {
+              root: { required: true, type: 'string' },
+              importAliasRoot: { type: 'string' },
+              default: { type: 'boolean' },
+            });
+
+            if (errors.length) {
+              throw new Error(
+                errors
+                  .map((e) =>
+                    m(
+                      `Invalid \x1b[31mcontainers.${e}\x1b[0m value "${config.containers[e]}" in "./.elsie.js".`,
+                      'error'
+                    )
+                  )
+                  .join('\n')
+              );
+            }
+
+            // Check the basename is PascalCase
+            if (!/^([A-Z][a-z0-9]+)*[A-Z][a-z0-9]*$/.test(basename)) {
+              throw new Error(
+                m(
+                  `\x1b[4m${basename}\x1b[0m is not a valid container name. Try naming your container with pascal case. i.e. \x1b[4m${toPascalCase(
+                    basename
+                  )}\x1b[0m`,
+                  'error'
+                )
+              );
+            }
+
+            return true;
+          }, false);
+      },
+      require('./container')
+    )
+
+    //
+    .updateStrings({
+      'Commands:': 'Tools & Resources:',
+    })
+    .demandCommand();
+};

package/bin/builders/gql/createOrClearDirectory.js

@@ -0,0 +1,33 @@
+const path = require('path');
+const fsPromises = require('node:fs/promises');
+
+module.exports = async function createOrClearDirectory(fileName) {
+  const directoryPath = path.join(process.cwd(), 'src/__generated__');
+
+  try {
+    // Check if the directory exists
+    const dirStats = await fsPromises.stat(directoryPath);
+
+    if (dirStats.isDirectory()) {
+      // If it's a directory, remove all files and subdirectories
+      const entries = await fsPromises.readdir(directoryPath);
+      for (const entry of entries) {
+        // If fileName is provided and it matches the current entry, remove it
+        // If fileName is not provided, remove all entries
+        if (!fileName || fileName === entry) {
+          const entryPath = path.join(directoryPath, entry);
+          await fsPromises.rm(entryPath, { recursive: true });
+        }
+      }
+    } else {
+      await fsPromises.mkdir(directoryPath, { recursive: true });
+    }
+  } catch (error) {
+    // If the directory doesn't exist, create it
+    if (error.code === 'ENOENT') {
+      await fsPromises.mkdir(directoryPath, { recursive: true });
+    } else {
+      throw error; // Re-throw any unexpected errors
+    }
+  }
+};

package/bin/builders/gql/getSchemaRef.js

@@ -0,0 +1,25 @@
+/**
+ * Returns the schema reference as defined in implementation's .elsie.js
+ *
+ * @see https://the-guild.dev/graphql/codegen/docs/config-reference/schema-field
+ * @returns [graphql-config.SchemaPointer] or [graphql-config.SchemaPointer[]]
+ */
+
+const config = require('../../lib/config');
+
+module.exports = function getSchemaRef() {
+  const { schema } = config();
+  if (!schema || !schema.endpoint) {
+    throw new Error('Missing schema.endpoint in .elsie.js');
+  }
+
+  return [
+    {
+      [schema.endpoint]: {
+        headers: {
+          ...(schema.headers || {}),
+        },
+      },
+    },
+  ];
+};

package/bin/builders/gql/index.js

@@ -0,0 +1,71 @@
+const path = require('path');
+const createOrClearDirectory = require('./createOrClearDirectory');
+const getSchemaRef = require('./getSchemaRef');
+require('dotenv').config();
+
+const generate = require('@graphql-codegen/cli').generate;
+
+module.exports = async function generateResourceBuilder(yargs) {
+  yargs
+    .command('types', 'Generate types', async () => {
+      await createOrClearDirectory('types.ts');
+      await generate(
+        {
+          schema: getSchemaRef(),
+          ignoreNoDocuments: true,
+          documents: [
+            `${path.resolve(process.cwd(), './src/**/*.graphql.ts')}`,
+            `!${path.resolve(process.cwd(), './src/__generated__/**')}`,
+          ],
+          generates: {
+            [`${path.resolve(process.cwd(), './src/__generated__/types.ts')}`]:
+              {
+                plugins: [
+                  '@graphql-codegen/typescript',
+                  '@graphql-codegen/typescript-operations',
+                ],
+                hooks: { afterOneFileWrite: ['prettier --write'] },
+              },
+          },
+        },
+        true
+      );
+    })
+    .command('mocks', 'Generate mocks and types', async () => {
+      await createOrClearDirectory();
+      await generate({
+        schema: getSchemaRef(),
+        ignoreNoDocuments: true,
+        documents: [
+          `${path.resolve(process.cwd(), './src/**/*.graphql.ts')}`,
+          `!${path.resolve(process.cwd(), './src/__generated__/**')}`,
+        ],
+        generates: {
+          [`${path.resolve(process.cwd(), './src/__generated__/types.ts')}`]: {
+            plugins: [
+              '@graphql-codegen/typescript',
+              '@graphql-codegen/typescript-operations',
+            ],
+            hooks: { afterOneFileWrite: ['prettier --write'] },
+          },
+          [`${path.resolve(process.cwd(), './src/__generated__/mocks.ts')}`]: {
+            plugins: [
+              {
+                'typescript-mock-data': {
+                  addTypename: true,
+                  prefix: 'mock',
+                  scalars: {
+                    Date: 'date',
+                  },
+                  // relative to the mocks.ts file
+                  typesFile: './types.ts',
+                  terminateCircularRelationships: true,
+                },
+              },
+            ],
+          },
+        },
+      });
+    })
+    .demandCommand(1, 1, 'choose a command: types or mocks');
+};

package/bin/builders/lint/index.js

@@ -0,0 +1,5 @@
+const cli = require('../../lib/cli');
+
+module.exports = function generateResourceBuilder() {
+  cli('eslint "*/**/*.{ts,tsx}"');
+};

package/bin/builders/serve/index.js

@@ -0,0 +1,44 @@
+const fs = require('fs');
+const path = require('path');
+
+module.exports = async function generateResourceBuilder({ argv }) {
+  const { build, preview } = await import('vite');
+
+  const configFile = argv?.config ?? path.resolve(__dirname, '../../../config/vite.mjs');
+
+  let built = false;
+
+  return build({
+    build: { watch: { buildDelay: 200 }, emptyOutDir: false },
+    logLevel: 'error',
+    clearScreen: true,
+    configFile,
+  })
+    .then((buildWatcher) => {
+      return new Promise((resolve) => {
+        buildWatcher.on('event', async ({ code }) => {
+          if (code === 'END') {
+            fs.writeFileSync(
+              path.resolve(process.cwd(), './dist/reload'),
+              JSON.stringify({
+                at: Date.now(),
+              })
+            );
+
+            console.log('\n📦 Dropin assets built\n');
+
+            if (!built) {
+              built = true;
+              resolve();
+            }
+          }
+        });
+      });
+    })
+    .then(async () => {
+      const previewServer = await preview({ configFile });
+      console.log('\n📡 Serving dropin assets:');
+      previewServer.printUrls();
+      console.log('\n');
+    });
+};

package/bin/builders/storybook/index.js

@@ -0,0 +1,5 @@
+const cli = require('../../lib/cli');
+
+module.exports = function generateResourceBuilder() {
+  cli('storybook dev -h localhost -p 6006 --disable-telemetry --quiet');
+};

package/bin/builders/test/index.js

@@ -0,0 +1,5 @@
+const cli = require('../../lib/cli');
+
+module.exports = function generateResourceBuilder() {
+  cli('jest');
+};

package/bin/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+const yargs = require('yargs');
+
+yargs
+  .usage('usage: $0 <command>')
+  .showHelpOnFail(true)
+  .command('storybook', 'Launch Storybook', require('./builders/storybook'))
+  .command('serve', 'Serve bundles', require('./builders/serve'))
+  .command(
+    'gql',
+    'Generates types or mocks for your API',
+    require('./builders/gql')
+  )
+  .command('build', 'Build bundles', require('./builders/build'))
+  .command('test', 'Run Jest tests', require('./builders/test'))
+  .command('lint', 'Run ESLint code analysis', require('./builders/lint'))
+  .command(
+    'generate',
+    'Generate a new <resource>',
+    require('./builders/generate')
+  )
+
+  .help('help')
+
+  .demandCommand().argv;

package/bin/lib/cli.js

@@ -0,0 +1,8 @@
+const { spawn } = require('child_process');
+
+module.exports = function cli(command) {
+  let cmd = command;
+  const argvs = process.argv.slice(3).join(' ');
+  if (argvs) cmd += ` ${argvs}`;
+  return spawn(cmd, { shell: true, stdio: 'inherit' });
+};

package/bin/lib/config.js

@@ -0,0 +1,12 @@
+const path = require('path');
+const fs = require('fs');
+
+module.exports = function getConfig() {
+  const configPath = path.resolve(process.cwd(), './.elsie.js');
+
+  if (!fs.existsSync(configPath)) {
+    return null;
+  }
+
+  return require(configPath);
+};

package/bin/lib/log-message.js

@@ -0,0 +1,11 @@
+module.exports = function logMessage(message, type = 'default') {
+  const TYPES = {
+    default: '',
+    warning: '⚠️ ',
+    error: '⛔️ ',
+    success: '👌 ',
+    created: '🆕 ',
+    updated: '✍️ ',
+  };
+  return `${TYPES[type]}${message}`;
+};

package/bin/lib/string.js

@@ -0,0 +1,26 @@
+function toPascalCase(str) {
+  return str
+    .match(/[A-Z]{2,}(?=[A-Z][a-z]+[0-9]*|\b)|[A-Z]?[a-z]+[0-9]*|[A-Z]|[0-9]+/g)
+    .map((x) => x.charAt(0).toUpperCase() + x.slice(1).toLowerCase())
+    .join('');
+}
+
+function hyphenatedName(str) {
+  return str
+    .replace(/([A-Z])/g, (g) => `-${g.toLowerCase()}`)
+    .replace(/^-/, '');
+}
+
+function toCamelCase(str) {
+  return toPascalCase(str)
+    .replace(/(?:^\w|[A-Z]|\b\w)/g, (word, index) => {
+      return index === 0 ? word.toLowerCase() : word.toUpperCase();
+    })
+    .replace(/\s+/g, '');
+}
+
+module.exports = {
+  toPascalCase,
+  hyphenatedName,
+  toCamelCase,
+};

package/bin/lib/validate-typeof.js

@@ -0,0 +1,19 @@
+module.exports = function validateTypeOf(values, rules) {
+  if (!values || !rules) return null;
+
+  return Object.entries(rules).reduce((result, [key, itemRules]) => {
+    if (itemRules.required && typeof values[key] === 'undefined') {
+      return [...result, key];
+    }
+
+    if (
+      itemRules.type &&
+      typeof values[key] !== 'undefined' &&
+      typeof values[key] !== itemRules.type
+    ) {
+      return [...result, key];
+    }
+
+    return [...result];
+  }, []);
+};

package/bin/lib/write-file.js

@@ -0,0 +1,21 @@
+const path = require('path');
+const fs = require('fs');
+const m = require('./log-message');
+
+module.exports = async function writeFile(filePath, content, force = false) {
+  const relativePath = path.relative('.', filePath);
+
+  if (force !== true && fs.existsSync(filePath)) {
+    console.error(m(`\x1b[31m${relativePath} \x1b[0malready exists`, 'error'));
+    return false;
+  } else {
+    await fs.promises.writeFile(filePath, content);
+
+    if (force) {
+      console.log(m(`\x1b[33m${relativePath} \x1b[0mupdated`, 'updated'));
+    } else {
+      console.log(m(`\x1b[33m${relativePath} \x1b[0mcreated`, 'created'));
+    }
+    return true;
+  }
+};

package/bin/lib/write-parent-index.js

@@ -0,0 +1,36 @@
+const path = require('path');
+const fs = require('fs');
+const m = require('./log-message');
+
+module.exports = function writeParentIndex(
+  filePath,
+  { pathname, importAliasRoot = '.' }
+) {
+  const relativePath = path.relative('.', filePath);
+
+  const existing = fs.existsSync(filePath);
+
+  const file = fs.openSync(filePath, 'a+');
+
+  const line = `export * from '${importAliasRoot}/${pathname}';`;
+
+  const content = fs.readFileSync(file);
+
+  if (content.includes(line)) {
+    console.log(m(`\x1b[33m${relativePath} \x1b[0mis up to date`, 'success'));
+    return;
+  }
+
+  const isLastNewLine =
+    content.toString().length === 0 || /[\n]$/.test(content.toString());
+
+  fs.appendFileSync(file, isLastNewLine ? `${line}\n` : `\n${line}\n`);
+
+  if (existing) {
+    console.log(m(`\x1b[33m${relativePath} \x1b[0mupdated`, 'updated'));
+  } else {
+    console.log(m(`\x1b[33m${relativePath} \x1b[0mcreated`, 'created'));
+  }
+
+  fs.closeSync(file);
+};