Custom Prompts Template Package Documentation

System Design Proposal for WordPress/gutenberg#67806

This documentation outlines a possible template package designed to test all possible scenarios for the @wordpress/create-block tool, focusing on adding custom prompts beyond the default ones.

Template Package Overview

This template serves as a baseline for testing scenarios where additional custom prompts are needed, including:

Modes: Standard and --no-plugin.
Variants: Default and custom.
CLI Argument Handling: Full and partial inputs.
Defaults: Using predefined defaultValues for prompts.

Structure of the Template

The package includes:

A configurable index.js file with defined custom prompts, defaults, and CLI handling.
Variant templates for custom scenarios.
A comprehensive testing mechanism to validate interactive and non-interactive flows.

Process Flow Diagram

graph TD
    A[Start] --> B{CLI Mode?}
    B -->|Standard| C[Load Standard Prompts]
    B -->|--no-plugin| D[Load Minimal Prompts]
    C --> E{Variant?}
    D --> F{Variant?}
    E -->|Yes| G[Load Variant-Specific Prompts]
    E -->|No| H[Use Default Template]
    F -->|Yes| G
    F -->|No| H
    G --> I[Merge CLI Inputs & Defaults]
    H --> I
    I --> J[Generate Files]
    J --> K[Done]

Custom Prompts

Mode	Prompt	Default Value	Variant Customization
Standard	CSS Framework	tailwind	Options: Tailwind CSS, Custom CSS
	Google Analytics ID		Optional, format: UA-XXXXX-Y
--no-plugin	Color Scheme	default	Options: Default Theme Colors, Custom Palette, Monochrome
	Custom CSS Prefix		Optional, must start with a letter
Custom Variant	Enable Debug Mode	false	Toggleable via CLI or prompts
	Custom API Endpoint		URL for custom API integration

Template File Structure

template-package/
├── index.js          # Main entry point
├── templates/
│   ├── default/      # Default template files
│   ├── custom/       # Custom variant template files

Sample index.js

const path = require('path');

module.exports = {
    defaultValues: {
        cssFramework: 'tailwind',
        analyticsId: '',
        colorScheme: 'default',
        customCssPrefix: '',
    },
    getPrompts: (mode, variant) => {
        const prompts = {
            cssFramework: {
                type: 'list',
                name: 'cssFramework',
                message: 'Choose a CSS framework for your plugin:',
                choices: [
                    { name: 'Tailwind CSS', value: 'tailwind' },
                    { name: 'Custom CSS', value: 'custom' }
                ],
                default: 'tailwind',
            },
            analyticsId: {
                type: 'input',
                name: 'analyticsId',
                message: 'Enter your Google Analytics ID (optional, format: UA-XXXXX-Y):',
                validate(input) {
                    if (!input) return true; // Optional
                    if (!/^UA-\d+-\d+$/.test(input)) {
                        return 'Invalid Google Analytics ID format. Should be like UA-XXXXX-Y';
                    }
                    return true;
                }
            },
            colorScheme: {
                type: 'list',
                name: 'colorScheme',
                message: 'Choose a color scheme for your block:',
                choices: [
                    { name: 'Default Theme Colors', value: 'default' },
                    { name: 'Custom Palette', value: 'custom' },
                    { name: 'Monochrome', value: 'mono' }
                ],
                default: 'default',
            },
            customCssPrefix: {
                type: 'input',
                name: 'customCssPrefix',
                message: 'Enter a custom CSS prefix for your block (optional):',
                validate(input) {
                    if (!input) return true; // Optional
                    if (!/^[a-z][a-z0-9-]*$/.test(input)) {
                        return 'CSS prefix must start with a letter and contain only lowercase letters, numbers, and hyphens';
                    }
                    return true;
                },
                filter(input) {
                    return input.toLowerCase();
                }
            }
        };

        if (mode === 'no-plugin') {
            // Remove plugin-wide prompts for no-plugin mode
            delete prompts.cssFramework;
            delete prompts.analyticsId;

            // Add block-specific prompts for no-plugin mode
            prompts.enableAdvancedFeatures = {
                type: 'confirm',
                name: 'enableAdvancedFeatures',
                message: 'Would you like to enable advanced block features?',
                default: false,
            };
        }

        if (variant === 'custom') {
            // Add or modify prompts specific to custom variants
            prompts.enableDebugMode = {
                type: 'confirm',
                name: 'enableDebugMode',
                message: 'Enable debug mode for development?',
                default: false,
            };
            prompts.customApiEndpoint = {
                type: 'input',
                name: 'customApiEndpoint',
                message: 'Enter the custom API endpoint URL:',
                validate(input) {
                    if (!input) return 'API endpoint URL is required';
                    if (!/^https?:\/\/[^\s]+$/.test(input)) {
                        return 'Invalid URL format';
                    }
                    return true;
                }
            };
        }

        return prompts;
    },
    templatesPath: path.join(__dirname, 'templates'),
};

Testing Scenarios

#	Test	Input	Expected Output
1	Standard Mode (Interactive)	Prompts for CSS framework and Google Analytics ID	Generates plugin files with custom configurations
2	Standard Mode (Non-Interactive)	`--cssFramework="custom"`	Generates files with provided inputs and defaults
3	--no-plugin Mode (Interactive)	Prompts for color scheme and custom CSS prefix	Generates only block files with custom configurations
4	--no-plugin Mode (Non-Interactive)	`--colorScheme="custom"`	Uses default CSS prefix, generates block files only
5	Custom Variant	Prompts for debug mode and custom API endpoint	Generates files with variant-specific configurations
6	CLI with Custom Variant	`--enableDebugMode --customApiEndpoint="https://api.example.com"`	Generates files using CLI inputs and default settings

CLI Prompt Examples

1. Standard Mode (Interactive)

❯ npx @wordpress/create-block --template ./my-template

Let's customize your WordPress plugin with blocks:
? The block slug used for identification (also the output folder name): example
? The internal namespace for the block name (something unique for your products): create-block
? The display title for your block: My Template
? The short description for your block (optional): My Template Description
? The dashicon to make it easier to identify your block (optional): 
? The category name to help users browse and discover your block: widgets
? Choose a CSS framework for your plugin: Tailwind CSS
? Enter your Google Analytics ID (optional, format: UA-XXXXX-Y): UA-11222-2

2. Standard Mode (Non-Interactive)

❯ npx @wordpress/create-block --template ./my-template --cssFramework="custom"

Using provided inputs and defaults:
- CSS Framework: Custom CSS
- Google Analytics ID: (default)

3. --no-plugin Mode (Interactive)

❯ npx @wordpress/create-block --template ./my-template --no-plugin

Let's customize your WordPress block:
? The block slug used for identification (also the output folder name): example
? The internal namespace for the block name (something unique for your products): create-block
? The display title for your block: My Template
? The short description for your block (optional): My Template Description
? The dashicon to make it easier to identify your block (optional): 
? The category name to help users browse and discover your block: widgets
? Choose a color scheme for your block: Custom Palette
? Enter a custom CSS prefix for your block (optional): default-prefix-
? Would you like to enable advanced block features? Yes

4. --no-plugin Mode (Non-Interactive)

❯ npx @wordpress/create-block --template ./my-template --no-plugin --colorScheme="custom"

Using provided inputs and defaults:
- Color Scheme: Custom Palette
- Custom CSS Prefix: (default)

5. Custom Variant

❯ npx @wordpress/create-block --template ./my-template --variant=custom

Let's customize your WordPress block with custom variant:
? The block slug used for identification (also the output folder name): example
? The internal namespace for the block name (something unique for your products): create-block
? The display title for your block: My Template
? The short description for your block (optional): My Template Description
? The dashicon to make it easier to identify your block (optional): 
? The category name to help users browse and discover your block: widgets
? Enable debug mode for development? Yes
? Enter the custom API endpoint URL: https://api.example.com

6. CLI with Custom Variant

❯ npx @wordpress/create-block --template ./my-template --variant=custom --enableDebugMode --customApiEndpoint="https://api.example.com"

Using provided inputs and defaults:
- Debug Mode: Enabled
- Custom API Endpoint: https://api.example.com

eduwass/custom-prompts-template-design.md