Generator Aspect (bit create) (teambit#3978)

Enable creating new components from a pre-defined templates.
See teambit#3940 for details.

Co-authored-by: David First <[email protected]>

Author: ranm8

scopes/generator/generator/component-template.ts

@@ -0,0 +1,50 @@
+import { ComponentID } from '@teambit/component-id';
+
+export interface File {
+  /**
+   * relative path of the file within the component.
+   */
+  relativePath: string;
+
+  /**
+   * file content
+   */
+  content: string;
+
+  /**
+   * whether this file will be tracked as the main file
+   */
+  isMain?: boolean;
+}
+
+export interface GeneratorContext {
+  /**
+   * component name of the generating component. e.g. `button` or `use-date`.
+   * without the scope and the namespace.
+   */
+  componentName: string;
+
+  /**
+   * e.g. `use-date` becomes `useDate`.
+   * useful when generating the file content, for example for a function name.
+   */
+  componentNameCamelCase: string;
+
+  /**
+   * component id.
+   * the name is the name+namespace. the scope is the scope entered by --scope flag or the defaultScope
+   */
+  componentId: ComponentID;
+}
+
+export interface ComponentTemplate {
+  /**
+   * name of the component template. for example: `hook`, `react-component` or `module`.
+   */
+  name: string;
+
+  /**
+   * template function for generating the file of a certain component.,
+   */
+  generateFiles(context: GeneratorContext): File[];
+}

scopes/generator/generator/create.cmd.ts

@@ -0,0 +1,39 @@
+import { Command, CommandOptions } from '@teambit/cli';
+import chalk from 'chalk';
+import { GeneratorMain } from './generator.main.runtime';
+
+export type GeneratorOptions = {
+  namespace?: string;
+  aspect?: string;
+  scope?: string;
+};
+
+export class CreateCmd implements Command {
+  name = 'create <templateName> <componentNames...>';
+  description = 'create a new component from a template';
+  shortDescription = '';
+  alias = '';
+  loader = true;
+  group = 'development';
+  options = [
+    ['n', 'namespace <string>', `sets the component's namespace and nested dirs inside the scope`],
+    ['s', 'scope <string>', `sets the component's scope-name. if not entered, the default-scope will be used`],
+    ['a', 'aspect <string>', 'aspect-id of the template. helpful when multiple aspects use the same template name'],
+  ] as CommandOptions;
+
+  constructor(private generator: GeneratorMain) {}
+
+  async report([templateName, componentNames]: [string, string[]], options: GeneratorOptions) {
+    const results = await this.generator.generateComponentTemplate(componentNames, templateName, options);
+    const title = `the following ${results.length} component(s) were created`;
+
+    const componentsData = results
+      .map((result) => {
+        const compTitle = `${chalk.bold(result.id.toString())} at ${result.dir}`;
+        const compFiles = result.files.map((file) => `    ${file}`).join('\n');
+        return `${compTitle}\n${compFiles}`;
+      })
+      .join('\n');
+    return `${chalk.green(title)}\n\n${componentsData}`;
+  }
+}

scopes/generator/generator/create.cmd.tsx

@@ -1,7 +1,5 @@
 import { Aspect } from '@teambit/harmony';
 
-export const CreateAspect = Aspect.create({
+export const GeneratorAspect = Aspect.create({
   id: 'teambit.generator/generator',
-  dependencies: [],
-  defaultConfig: {},
 });

scopes/generator/generator/create.main.runtime.ts

@@ -1,25 +1,69 @@
-Create extension enable generating new components by a default template or extensions registered to this extension.
+Generator extension enable generating new components by pre-defined templates
+
+### Component location
+
+Component location in the workspace directory tree is defined with the `bit create` command (see below). For example, a component named `ShoppingCart` created in the `acme.shopper` and the namespace `ui` will be generated in the following directory:
 
-### Configuration
-Add to your config the following:
 ```
-"create": {
-  "template": "your-extension"
-}
+acme.shopper/ui/shopping-cart
 ```
 
-### How to extend
-First, add this extension as a dependency to your extension.
-Then, in the provider, register to this extension and provide a function that returns the template files.
-Here is an example:
+### Component name
+
+When using templates Bit will use CamelCasing for passing the component-name to the template, but generated file structure should be in kebab-case, for better cross-operating-system compatibility of the component.
+
+### Automatically `add` component
+
+Bit should automatically register the new component to the `.bitmap` file with a symmetrical name to the component-location in the workspace.
+
+## Register a template
+Any aspect (include envs) can register templates. Each template should have a name and a list of files. Each file has a relative-path to the component-dir and template content. See the `component-template.ts` file for more info about the exact API.
+
+* Component name should be available as a param for the file-content-template.
+* TBD: An environment must have a default template (if not set, use first template in array?).
+
+To register a template, use the Generator API: `registerComponentTemplate(templates: ComponentTemplate[])`.
+
+To make the templates of an aspect available on a workspace, they need to be added to the workspace.jsonc. For example:
+```json
+"teambit.generator/generator": {
+    "aspects": [
+      "teambit.harmony/aspect"
+    ]
+  },
 ```
-create.register({ name: 'extensions/gulp-ts' }, (name) => {
-  return {
-    files: [
-      { path: `${name}.js`, content: `export default function ${name}() { console.log('hello'); }` },
-      { path: `${name}.spec.js`, content: `export default function ${name}() { console.log('hello from spec'); }` }
-    ],
-    main: `${name}.js`
-  };
-});
+In the example above, the aspect `teambit.harmony/aspect` is configured to be available for the generator.
+
+## Show all available templates
+
+Introduce a new command `bit templates`, which groups all available templates by aspects.
+
+## Generate a template from CLI
+
+Introduce a `create` command to use templates.
+
+```sh
+bit create <template-name> <component-name...> [--scope | -s] [--namespace | -n] [--aspect | -a]
 ```
+
+### Args
+
+#### `<component name>`
+
+Name of the component to create. Will be used as the component's dir name and fed to the component template.
+
+**generated file structure should use kebab-case, while the template itself be in camel case**.
+
+### Options
+
+#### `[--scope | -s]`
+
+Sets the component's scope and base directory. If not defined, use the `defaultScope` from `teambit.workspace/workspace` config.
+
+#### `[--namespace | -n]`
+
+Sets the component's namespace and nested dirs inside the scope. If not define, use empty string.
+
+#### `[--aspect | -a]`
+
+Aspect ID that registered this template, required only if there are two templates with the same name from several aspects in the workspace.