quick-ui

A command-line tool for launching browsers and loading HTML templates for user interaction.

Features

• 🚀 Quick browser interface launch
• 📋 Support for multiple HTML templates
• 🔧 Flexible JSON configuration
• 🎨 Beautiful default form template
• 📝 Automated user interaction handling
• 🛡️ Type-safe TypeScript implementation

Technical Implementation

Template Management System

Template Copying Mechanism

• Built-in Templates: quick-ui includes built-in templates in the project's templates/ directory
• Automatic Copying: When quick-ui initializes, it automatically checks if templates exist in the user's ~/.quick-ui/html-templates/ directory
• Template Installation: If templates don't exist, they are automatically copied from the project's templates/ directory to the user's directory
• One-time Setup: This copying process only happens once during initialization, ensuring fast startup for subsequent uses

Getting HTML Template List

• Command Execution: Execute quick-ui template-list command in the command line
• Scanning Process: The quick-ui program automatically scans all subdirectories in the .quick-ui/html-templates/ folder under the user directory
• Template Recognition: Each subdirectory name is recognized as an available HTML template name
• Result Display: The program clearly outputs all detected template names in a list format to the command line interface

Launching HTML Interface with Specified Template

• Configuration Preparation: User selects an appropriate HTML template based on needs, and creates a JSON configuration file that complies with the specification by referencing the requestJsonSchema.json file in that template directory, saving it as quickUiRequest.json
• Launch Command: Execute quick-ui path/to/quickUiRequest.json in the command line
• Configuration Reading: The quick-ui program reads the specified JSON configuration file and extracts the htmlTemplate attribute value
• Template Loading: Based on the htmlTemplate attribute value, the program loads the corresponding HTML file from .quick-ui/html-templates/<htmlTemplate>/index.html under the user directory
• Service Startup: The quick-ui program internally starts an HTTP server, using the .quick-ui/html-templates/<htmlTemplate> directory as the static file root directory, and automatically assigns an available port number
• Interface Display: The program automatically opens a browser to display the user interface
• User Interaction: User performs required interaction operations in the browser interface
• Result Submission: When the user clicks buttons like OK or Cancel, the browser sends a POST request to /submit, submitting the user operation results to the HTTP server
• Result Processing: After receiving the user operation results, the HTTP server returns them to the quick-ui program
• Resource Cleanup: After obtaining the results, the quick-ui program automatically closes the HTTP server
• Result Output: Finally, the program formats and outputs the user's operation results to the command line

Installation

npm install -g quick-ui

Or local installation:

npm install quick-ui

Quick Start

1. Get Available Template List

quick-ui --template-list

2. Create Request Configuration File

Create a quickUiRequest.json file:

{
    "width": 800,
    "height": 600,
    "htmlTemplate": "default-form",
    "htmlRequest": {
        "form": {
            "title": "User Information",
            "items": [
                {
                    "type": "textInput",
                    "id": "username",
                    "label": "Username",
                    "required": true,
                    "placeholder": "Please enter username"
                },
                {
                    "type": "textInput",
                    "id": "email",
                    "label": "Email",
                    "required": true,
                    "placeholder": "Please enter email address"
                },
                {
                    "type": "select",
                    "id": "role",
                    "label": "Role",
                    "options": [
                        { "label": "Administrator", "value": "admin" },
                        { "label": "Regular User", "value": "user" }
                    ]
                }
            ]
        }
    }
}

3. Launch Interface

quick-ui ./quickUiRequest.json

Command Line Options

• quick-ui --template-list - List all available HTML templates
• quick-ui --template-update - Update built-in templates in user directory (preserving custom templates)
• quick-ui <requestPath> - Launch interface with specified configuration file
• quick-ui --template <templateName> --request '<jsonRequest>' - Launch interface with specified template and request data
• quick-ui --template <templateName> --request '<jsonRequest>' --width <width> --height <height> - Launch interface with custom window size
• quick-ui --request-file <requestPath> - Launch interface with specified configuration file (equivalent to passing file path directly)
• quick-ui --help - Display help information
• quick-ui --version - Display version information

Command Line Usage Examples

Using Template and Request Directly

# Launch default form with basic fields
quick-ui --template default-form --request '{"form":{"title":"User Info","items":[{"type":"textInput","id":"name","label":"Name","required":true}]}}'

# Launch file picker for images
quick-ui --template file-picker --request '{"title":"Select Images","accept":"image/*","multiple":true}'

# Launch confirmation dialog
quick-ui --template quick-confirm --request '{"title":"Confirm","message":"Are you sure?"}'

# Launch with custom window size
quick-ui --template default-form --request '{"form":{"title":"Settings","items":[{"type":"textInput","id":"name","label":"Name"}]}}' --width 800 --height 600

Using Request File

# Using file path directly (legacy format)
quick-ui ./quickUiRequest.json

# Using --request-file parameter (recommended format)
quick-ui --request-file ./quickUiRequest.json

Configuration File Format

quickUiRequest.json

{
    "width": 800,                    // Browser window width
    "height": 600,                   // Browser window height
    "htmlTemplate": "default-form",  // HTML template name
    "htmlRequest": {                 // Template-specific request data
        // Specific format depends on the template used
    }
}

quickUiResponse.json

{
    "success": true,                 // Whether the request was successful
    "htmlResponse": {                // Template-specific response data
        // Specific format depends on the template used
    }
}

Supported Form Item Types

The default-form template supports the following form item types:

| Type | Description | Required Properties | |------|-------------|---------------------| | textInput | Text input box | id, label | | passwordInput | Password input box | id, label | | colorInput | Color picker | id, label | | textArea | Multi-line text box | id, label | | dateInput | Date picker | id, label | | radioSelect | Radio button group | id, label, options | | dropdownSelect | Dropdown selection box | id, label, options | | checkboxSelect | Checkbox group | id, label, options |

Form Item Properties

• id: Unique identifier for the form item, used as the key name when collecting data
• label: Display label for the form item
• placeholder: Placeholder text for the input box (optional)
• required: Whether the field is required (optional, default is false)
• options: List of options (only required for radioSelect, dropdownSelect, checkboxSelect types)
  • label: Option display text
  • value: Option value

Development

Install Dependencies

npm install

Build Project

npm run build

Development Mode

npm run dev

Run Tests

npm test

Project Structure

quick-ui/
├── src/
│   ├── browser.ts          # Browser management
│   ├── cli.ts              # Command line interface
│   ├── core.ts             # Core business logic
│   ├── server.ts           # HTTP server
│   ├── templates/          # Template management
│   ├── types/              # Type definitions
│   └── utils/              # Utility functions
├── templates/              # Template files
│   └── default-form/       # Default form template
├── examples/               # Example configuration files
├── dist/                   # Build output
└── .vtxf/ai/              # Project documentation and task records

Custom Templates

You can create your own HTML templates:

1. Create a new directory under ~/.quick-ui/html-templates/
2. Add required files:
   • index.html - Main page
   • requestJsonSchema.json - Request format definition
   • responseJsonSchema.json - Response format definition

Error Handling

• If the specified template does not exist, the quick-ui program should output an error message and exit
• If the quickUiRequest.json format is incorrect, the quick-ui program should output specific format error information and exit
• If the browser cannot be launched, the quick-ui program should output an error message and exit
• If the HTTP server fails to start, the quick-ui program should output an error message and exit

Examples

User Registration Form

{
    "width": 800,
    "height": 600,
    "htmlTemplate": "default-form",
    "htmlRequest": {
        "form": {
            "title": "User Registration",
            "items": [
                {
                    "type": "textInput",
                    "id": "username",
                    "label": "Username",
                    "required": true,
                    "placeholder": "Please enter username"
                },
                {
                    "type": "emailInput",
                    "id": "email",
                    "label": "Email Address",
                    "required": true,
                    "placeholder": "Please enter email address"
                },
                {
                    "type": "passwordInput",
                    "id": "password",
                    "label": "Password",
                    "required": true,
                    "placeholder": "Please enter password"
                },
                {
                    "type": "select",
                    "id": "role",
                    "label": "User Role",
                    "required": true,
                    "options": [
                        { "label": "Regular User", "value": "user" },
                        { "label": "Administrator", "value": "admin" }
                    ]
                }
            ]
        }
    }
}

Contact Us Form

{
    "width": 600,
    "height": 500,
    "htmlTemplate": "default-form",
    "htmlRequest": {
        "form": {
            "title": "Contact Us",
            "items": [
                {
                    "type": "textInput",
                    "id": "name",
                    "label": "Name",
                    "required": true,
                    "placeholder": "Please enter your name"
                },
                {
                    "type": "emailInput",
                    "id": "email",
                    "label": "Email",
                    "required": true,
                    "placeholder": "Please enter your email address"
                },
                {
                    "type": "select",
                    "id": "subject",
                    "label": "Inquiry Type",
                    "required": true,
                    "options": [
                        { "label": "Technical Support", "value": "support" },
                        { "label": "Business Cooperation", "value": "business" },
                        { "label": "Product Feedback", "value": "feedback" }
                    ]
                },
                {
                    "type": "textarea",
                    "id": "message",
                    "label": "Message Content",
                    "required": true,
                    "placeholder": "Please describe your question or requirements in detail..."
                }
            ]
        }
    }
}

License

MIT License

Author

vtxf [email protected]