improve docs and add assets + asset-types flags, clearer

Author: chrisberthe

src/commands/theme/generate/component.ts

@@ -36,13 +36,16 @@ export default class GenerateComponent extends BaseCommand {
   static override description = 'Generate a new component with optional supporting files'
 
   static override examples = [
+    '<%= config.bin %> <%= command.id %>',
     '<%= config.bin %> <%= command.id %> element.button',
-    '<%= config.bin %> <%= command.id %> element.button --assets=css --files',
-    '<%= config.bin %> <%= command.id %> element.button --snippets=gift-form,upsell',
-    '<%= config.bin %> <%= command.id %> element.button --setup',
+    '<%= config.bin %> <%= command.id %> element.button --assets',
+    '<%= config.bin %> <%= command.id %> element.button --assets --asset-types=css',
+    '<%= config.bin %> <%= command.id %> section.hero --assets --files',
+    '<%= config.bin %> <%= command.id %> element.text --assets --snippets=body,heading,rte --setup'
   ]
 
   static override flags = Flags.getDefinitions([
+    Flags.ASSET_TYPES,
     Flags.ASSETS,
     Flags.FILES,
     Flags.FORCE,
@@ -172,10 +175,6 @@ export default class GenerateComponent extends BaseCommand {
     return { assets, component, snippets }
   }
 
-  private capitalizeFirst(str: string): string {
-    return str.charAt(0).toUpperCase() + str.slice(1)
-  }
-
   private createFiles(component: ComponentParts, filesToCreate: FileToCreate[]): void {
     const created: string[] = []
     const skipped: string[] = []
@@ -215,27 +214,33 @@ export default class GenerateComponent extends BaseCommand {
     return { name, type }
   }
 
-  private getAssetTypesFromFlag(assetsFlag: string): { css: boolean; js: boolean } {
-    const assetTypeMap = {
-      all: { css: true, js: true },
-      css: { css: true, js: false },
-      js: { css: false, js: true },
-    } as const
+  private getAssetTypesFromFlags(assetTypesFlag?: string): { css: boolean; js: boolean } {
+    // If no asset types specified, default to both
+    if (!assetTypesFlag) {
+      return { css: true, js: true }
+    }
 
-    return assetTypeMap[assetsFlag as keyof typeof assetTypeMap] || { css: false, js: false }
+    // Parse comma-separated values
+    const types = new Set(assetTypesFlag.toLowerCase().split(',').map(t => t.trim()))
+
+    return {
+      css: types.has('css'),
+      js: types.has('js')
+    }
   }
 
   private parseAssetTypes(): { css: boolean; inline: boolean; js: boolean } {
     const assetsFlag = this.flags[Flags.ASSETS]
+    const assetTypesFlag = this.flags[Flags.ASSET_TYPES]
     const filesFlag = this.flags[Flags.FILES]
 
-    this.validateAssetDependencies(assetsFlag, filesFlag)
+    this.validateAssetDependencies(assetsFlag, assetTypesFlag, filesFlag)
 
     if (!assetsFlag) {
       return { css: false, inline: true, js: false }
     }
 
-    const { css, js } = this.getAssetTypesFromFlag(assetsFlag)
+    const { css, js } = this.getAssetTypesFromFlags(assetTypesFlag)
 
     return {
       css,
@@ -280,10 +285,21 @@ export default class GenerateComponent extends BaseCommand {
   }
 
   private async promptForComponentType(): Promise<string> {
-    const componentTypes = ['block', 'element', 'form', 'layout', 'section', 'utility'] as const
+    const componentTypes = [
+      { description: 'Resource-specific blocks', name: 'block' },
+      { description: 'Basic UI primitives', name: 'element' },
+      { description: 'Form-specific components', name: 'form' },
+      { description: 'Structure and spacing primitives', name: 'layout' },
+      { description: 'Sections rendered in templates', name: 'section' },
+      { description: "Helper components that don't render UI elements", name: 'utility' },
+    ] as const
+
     const type = await renderSelectPrompt({
       choices: [
-        ...componentTypes.map(t => ({ label: this.capitalizeFirst(t), value: t })),
+        ...componentTypes.map(t => ({
+          label: `${t.name.charAt(0).toUpperCase() + t.name.slice(1)} - ${t.description}`,
+          value: t.name
+        })),
         { label: 'Other (specify custom type)', value: 'other' },
       ],
       message: 'What type of component?',
@@ -386,9 +402,13 @@ export default class GenerateComponent extends BaseCommand {
     }
   }
 
-  private validateAssetDependencies(assetsFlag: string | undefined, filesFlag: boolean): void {
+  private validateAssetDependencies(assetsFlag: boolean, assetTypesFlag: string | undefined, filesFlag: boolean): void {
     if (filesFlag && !assetsFlag) {
       this.error('The --files flag can only be used together with --assets')
     }
+
+    if (assetTypesFlag && !assetsFlag) {
+      this.error('The --asset-types flag can only be used together with --assets')
+    }
   }
 }

src/utilities/flags.ts

@@ -5,6 +5,7 @@ import { ComponentConfig } from './types.js'
 
 export default class Flags {
   [key: string]: any; // eslint-disable-line @typescript-eslint/no-explicit-any
+  static readonly ASSET_TYPES = 'asset-types';
   static readonly ASSETS = 'assets';
   static readonly CLEAN = 'clean';
   static readonly COLLECTION_NAME = 'collection-name';
@@ -56,13 +57,18 @@ export default class Flags {
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const flagDefinitions: Record<string, any> = {
-  [Flags.ASSETS]: OclifFlags.string({
-    char: 'a',
-    description: "Generate CSS and JS assets. Specify 'all', 'css', or 'js'",
-    helpValue: '[all|css|js]',
+  [Flags.ASSET_TYPES]: OclifFlags.string({
+    description: "The asset types to generate: 'css', 'js', or 'css,js' (defaults to both)",
+    helpValue: '[css|js|css,js]',
     required: false,
   }),
 
+  [Flags.ASSETS]: OclifFlags.boolean({
+    char: 'a',
+    default: false,
+    description: "Generate CSS and JS assets. Defaults to inline references in the component's Liquid file inside {% stylesheet %} and {% javascript %} tags",
+  }),
+
   [Flags.CLEAN]: OclifFlags.boolean({
     char: 'c',
     default: false,
@@ -86,7 +92,7 @@ export const flagDefinitions: Record<string, any> = {
   [Flags.FILES]: OclifFlags.boolean({
     char: 'f',
     default: false,
-    description: 'Create separate asset files instead of inline',
+    description: "Create separate CSS and JS files instead of inline references in the component's Liquid file",
   }),
 
   [Flags.FORCE]: OclifFlags.boolean({
@@ -172,7 +178,7 @@ export const flagDefinitions: Record<string, any> = {
   [Flags.SETUP]: OclifFlags.boolean({
     char: 's',
     default: false,
-    description: 'Generate setup files (sections and templates)',
+    description: 'Generate section and template files to preview component in component explorer',
   }),
 
   [Flags.SETUP_FILES]: OclifFlags.boolean({
@@ -183,7 +189,7 @@ export const flagDefinitions: Record<string, any> = {
   }),
 
   [Flags.SNIPPETS]: OclifFlags.string({
-    description: 'Comma-separated list of snippet names to generate',
+    description: 'Generate component snippets (e.g., "body,heading,rte")',
     multiple: true,
   }),