create-template-html-css 2.0.3 → 2.1.0

package/CHANGELOG.md

@@ -5,6 +5,311 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [2.1.0] - 2026-02-08
+
+### ⚛️ React Support
+
+#### Added - React Component Generation
+- **React Component Templates** - Generate React components with JSX
+  - Created `templates-react/` directory with 6 React components:
+    - Button - Customizable button with variants and sizes
+    - Card - Display content in elegant cards
+    - Counter - Interactive counter with state management
+    - Form - Flexible form with validation
+    - Modal - Dialog modal with overlay
+    - Todo List - Complete CRUD operations
+  - All components use modern React Hooks (useState, useEffect)
+  - Full CSS styling with customizable colors
+  - Dark mode support with CSS media queries
+  - Example files for each component
+
+- **React Generator** - New `src/react-generator.js` module
+  - Generates complete React project structure with Vite
+  - Creates `src/components/` directory structure
+  - Generates `App.jsx`, `index.jsx`, and `index.html`
+  - Creates `package.json` with React 18 and Vite dependencies
+  - Generates `vite.config.js` for Vite configuration
+  - Generates `.gitignore` and `README.md`
+  - Supports color customization (schemes and custom colors)
+  - **Component-Only Mode**: New `addReactComponentOnly()` function
+    - Adds single React component (JSX + CSS) without full project structure
+    - Perfect for adding components to existing projects
+    - Validates component doesn't already exist
+    - Provides usage instructions after creation
+  - **Security**: Full input validation and sanitization
+    - Component name validation against whitelist
+    - Project name sanitization using `sanitizeFilename()`
+    - Protection against path traversal attacks
+    - Alphanumeric validation for project names
+  - Export functions: `generateReactTemplate()`, `addReactComponentOnly()`, `VALID_REACT_COMPONENTS`
+
+- **React CLI Support** - Enhanced CLI with React mode
+  - Added `--react` flag to `create` command
+  - Added `--component-only` flag for adding components without full project
+  - Interactive framework selection (HTML or React)
+  - Interactive project type selection (Full project or Component only)
+  - React component choices loaded dynamically
+  - Created `src/react-component-choices.js` with component descriptions
+  - Updated CLI help messages to mention React support
+  - Updated main CLI description to include React
+
+- **React Documentation**
+  - Created `templates-react/README.md` with usage guide
+
+#### Fixed
+- **JSX File Extension**: Changed `index.js` to `index.jsx` to properly support JSX syntax
+  - Vite requires `.jsx` extension for files containing JSX
+  - Updated generator to create `index.jsx` instead of `index.js`
+  - Updated `index.html` reference to `/src/index.jsx`
+  - Prevents "Failed to parse source for import analysis" errors
+  - Created `QUICKSTART-REACT.md` - Quick start guide for React
+  - Created `HTML-VS-REACT.md` - Comprehensive comparison guide
+  - Updated main `README.md` with React sections:
+    - "React Support" in What's New
+    - "Mode 1b: Create a React Component Project" usage guide
+    - React component descriptions and examples
+  - Added React keywords to `package.json`
+  - Updated version to 2.1.0
+
+#### Security Enhancements
+- **Enhanced Input Validation** - Strengthened security across all components
+  - All user inputs are validated and sanitized
+  - Path traversal protection (blocks ../, ..\, /../, \..\ patterns)
+  - Project name length validation (max 100 characters)
+  - Alphanumeric character requirement for names
+  - Dangerous character removal (<>:"|?*)
+### 🔧 Code Quality & Architecture Improvements
+
+#### Refactored - React Generator Module Split
+- **Major Refactoring**: Split `react-generator.js` (659 lines) into focused modules
+  - Reduced main file by **73%** (176 lines)
+  - Better separation of concerns and maintainability
+  
+- **New Module Structure**:
+  - `src/react-generator.js` (176 lines) - Main export functions and validation
+    - `generateReactTemplate()` - Full React project generation
+    - `addReactComponentOnly()` - Component-only mode
+    - `validateComponent()` - Component name validation
+    - Exports `VALID_REACT_COMPONENTS` constant
+  
+  - `src/react-templates.js` (303 lines) - Template generation functions
+    - `generateAppJsx()` - App component with examples
+    - `generateIndexJs()` - React entry point
+    - `generateIndexHtml()` - HTML template
+    - `generatePackageJson()` - Package configuration
+    - `generateGitignore()` - Git ignore file
+    - `generateViteConfig()` - Vite configuration
+    - `generateReadme()` - Project README
+    - Version constants: `REACT_VERSION`, `VITE_VERSION`, `VITE_REACT_PLUGIN_VERSION`
+  
+  - `src/react-file-operations.js` (148 lines) - File I/O and utilities
+    - `readComponentFiles()` - Read and process templates
+    - `writeComponentFiles()` - Write JSX and CSS files
+    - `createReactProjectStructure()` - Create project directories
+    - `toPascalCase()` - Convert names to PascalCase
+    - `resolveColors()` - Resolve color schemes
+    - Color constants: `DEFAULT_PRIMARY_COLOR`, `DEFAULT_SECONDARY_COLOR`
+
+- **Code Organization Improvements**:
+  - Extracted common helper functions to reduce duplication
+  - Simplified App.jsx template generation with `createAppTemplate()`
+  - Added clear section headers for better code navigation
+  - Extracted magic values into named constants
+  - Organized code into logical sections (CONSTANTS, UTILITIES, VALIDATORS, etc.)
+
+#### Benefits
+- **Maintainability**: Each module has single responsibility
+- **Testability**: Easier to test focused modules independently
+- **Readability**: Clear separation between templates, file operations, and main logic
+- **Performance**: Better tree-shaking with modular exports
+- **Developer Experience**: Easier to find and modify specific functionality
+
+#### Testing
+- ✅ All functionality preserved - no breaking changes
+- ✅ Full project generation tested and working
+- ✅ Component-only mode tested and working
+- ✅ All React components generate correctly
+- ✅ No syntax or runtime errors  - Component name whitelist validation
+  - Empty/null input rejection
+
+- **Secure File Operations** - Protected file system operations
+  - All file paths use `path.join()` to prevent traversal
+  - Directory creation with `recursive: true` safely
+  - Output directory restricted to `process.cwd()` subdirectories
+  - No arbitrary file system access allowed
+
+- **Example Usage:**
+  ```bash
+  # Interactive mode
+  create-template create --react
+  
+  # With flags
+  create-template create --react -c button -n my-button
+  create-template create --react -c counter -n my-counter --color-scheme ocean
+  
+  # Run the React project
+  cd my-counter
+  npm install
+  npm run dev
+  ```
+
+### 🏗️ Major Refactoring
+
+#### Changed - Code Deduplication
+
+#### Fixed - Template Consistency
+- **Standardized Template HTML Syntax** - Fixed inconsistencies across templates
+  - Fixed `skeleton` template to use HTML5 syntax instead of XHTML (removed `/` from void elements)
+  - Added missing `{{name}}` placeholder to 8 game templates:
+    - `blackjack`, `breakout`, `connect-four`, `dice-game`, `flappy-bird`, `pong`, `slot-machine`, `tetris`
+  - All 42 templates now consistently use HTML5 syntax
+  - All templates now support custom naming via `{{name}}` placeholder
+  - Improved template generation consistency
+
+- **Enhanced Template Documentation** - Improved templates/_shared directory
+  - Updated `README.md` with comprehensive philosophy and statistics
+  - Created `PATTERNS.md` documenting 15+ recurring code patterns
+  - Created `CONTRIBUTING.md` with complete template development guide
+  - Documented intentional CSS/JS duplication strategy (42 self-contained templates)
+  - Added statistics: 42 templates with CSS reset, 37 with gradient backgrounds
+  - Clarified that templates are intentionally standalone for copy-paste usage
+  - Better onboarding for contributors understanding template architecture
+
+- **Centralized String Utilities** - Eliminated duplicate string manipulation patterns
+  - Created `src/utils/string-utils.js` with reusable string functions
+  - Extracted functions:
+    - `textToId()` - Convert text to valid HTML/CSS ID (e.g., "My Item" → "my-item")
+    - `sanitizeForFilename()` - Remove invalid filename characters
+    - `parseCommaSeparated()` - Parse comma-separated lists with trimming
+    - `parseKeyValuePairs()` - Parse "key:value" comma-separated pairs
+  - Refactored `src/generators/html-generators.js` to use string utilities (23 lines net reduction)
+  - Refactored `src/generators/validation.js` to use string utilities
+  - Fixed `src/generator.js` to properly use `createComponentDirs()` (6 lines reduction)
+  - Eliminated 3 duplicate instances of `.toLowerCase().replace(/\s+/g, "-")` pattern
+  - More consistent string handling across codebase
+
+- **Centralized Template Loading** - Eliminated duplicate template file reading
+  - Created `src/utils/template-loader.js` with reusable template reading functions
+  - Extracted functions:
+    - `getTemplatePath()` - Get template directory path
+    - `readTemplateFile()` - Read any template file
+    - `readTemplateHtml()` - Read template HTML with fallback logic
+    - `readTemplateCss()` - Read template CSS with css/ subfolder support
+    - `readTemplateJs()` - Read template JS with js/ subfolder support
+    - `hasTemplateJs()` - Check if template has JavaScript
+  - Refactored `src/generator.js` to use template loader (12 lines net reduction)
+  - Refactored `src/inserters/component-loader.js` to use template loader (8 lines net reduction)
+  - Eliminated repetitive `fs.readFile()` and `path.join()` patterns
+  - More consistent template file handling across codebase
+
+- **Centralized File Operations** - Eliminated duplicate file system operations
+  - Created `src/utils/file-utils.js` with reusable file operation functions
+  - Extracted functions:
+    - `ensureDir()` - Create directory with parents
+    - `ensureDirs()` - Create multiple directories
+    - `writeHtmlFile()` - Write formatted HTML files
+    - `writeCssFile()` - Write formatted CSS files
+    - `writeJsFile()` - Write formatted JS files
+    - `createComponentDirs()` - Create component directory structure
+    - `writeComponentFiles()` - Write all component files atomically
+  - Refactored `src/generator.js` to use file utilities (reduced by 11 lines)
+  - Refactored `src/inserter.js` to use file utilities (reduced by 9 lines)
+  - Eliminated repetitive `fs.mkdir({recursive: true})` and `fs.writeFile()` patterns
+  - More consistent error handling and file formatting
+
+- **Centralized Indentation Logic** - Eliminated duplicate indentation handling
+  - Created `src/inserters/indentation-utils.js` with reusable indentation functions
+  - Extracted functions:
+    - `normalizeIndentation()` - Normalize content with base indentation
+    - `createInlineStyleTag()` - Generate inline style tags
+    - `createInlineScriptTag()` - Generate inline script tags
+    - `createStyleLink()` - Generate external stylesheet links
+    - `createScriptTag()` - Generate external script tags
+    - `createComponentInsertion()` - Generate component HTML with comment
+  - Refactored `src/inserter.js` to use utilities
+  - Reduced inserter.js from 206 to 163 lines (21% reduction)
+  - Eliminated ~40 lines of duplicate indentation normalization logic
+  - More maintainable and testable code
+
+- **Centralized Path Utilities** - Eliminated __dirname duplication in ES Modules
+  - Created `src/utils/path-utils.js` with `getDirname()` and `getFilename()` utilities
+  - Replaced repetitive `fileURLToPath` + `dirname` pattern in 3 files:
+    - `src/generator.js` - Now uses `getDirname(import.meta.url)`
+    - `src/inserters/component-loader.js` - Now uses `getDirname(import.meta.url)`
+    - `bin/commands/gallery.js` - Now uses `getDirname(import.meta.url)`
+  - Cleaner, more maintainable ES Modules __dirname handling
+  - Reduced boilerplate by ~15 lines
+
+- **Centralized Components Registry** - Eliminated duplicate component lists
+  - Created `src/components-registry.js` as single source of truth
+  - Contains `VALID_COMPONENTS` array (46 components, alphabetically sorted)
+  - Contains `COMPONENT_CHOICES` with categorized prompts
+  - Removed duplicates from:
+    - `src/generators/validation.js` - Now imports from registry
+    - `src/inserters/validation-utils.js` - Now imports from registry
+    - `src/component-choices.js` - Now re-exports from registry (deprecated)
+  - Reduced code duplication by ~130 lines
+  - Single maintenance point for component additions
+
+#### Changed - Inserter Module Architecture
+- **Modular Inserter Structure** - Split 327-line inserter.js into organized modules
+  - Main inserter.js reduced from 327 to 206 lines (37% reduction)
+  - New `src/inserters/` directory with specialized modules:
+    - `validation-utils.js` (93 lines) - Component validation, HTML structure validation
+    - `html-utils.js` (31 lines) - HTML indentation detection and manipulation
+    - `backup-utils.js` (19 lines) - File backup creation utilities
+    - `component-loader.js` (95 lines) - Template loading for HTML, CSS, and JS files
+  - Better separation of concerns and maintainability
+  - Security validation maintained throughout refactor
+
+#### Changed - Generator Module Architecture
+- **Modular Generator Structure** - Split massive 661-line generator.js into organized modules
+  - Main generator.js reduced from 661 to 166 lines (75% reduction!)
+  - New `src/generators/` directory with specialized modules:
+    - `color-schemes.js` (76 lines) - All color presets and scheme management
+    - `color-utils.js` (93 lines) - Color manipulation utilities and dark mode
+    - `component-filters.js` (135 lines) - Button, card, spinner variations filtering
+    - `html-generators.js` (171 lines) - Navigation and form field generation
+    - `validation.js` (61 lines) - Component validation and security utilities
+  - Better separation of concerns and maintainability
+  - Improved code organization and testability
+
+#### Changed - CLI Module Architecture
+- **ES Modules Migration** - Converted entire codebase from CommonJS to ES Modules
+  - All `require()` statements replaced with `import`
+  - All `module.exports` replaced with `export`
+  - Added `"type": "module"` to package.json
+  - Updated dynamic imports for optional dependencies (Prettier)
+  - Proper `__dirname` support using `fileURLToPath` and `dirname`
+
+- **Modular CLI Architecture** - Refactored CLI from single 618-line file to organized structure
+  - Main CLI file reduced from 618 to 85 lines (86% reduction!)
+  - Commands split into separate modules in `bin/commands/` directory
+  - `create.js` - 174 lines (handles template creation with prompts)
+  - `insert.js` - 123 lines (handles component insertion into HTML)
+  - `list.js` - 73 lines (displays all 46 available components)
+  - `gallery.js` - 42 lines (opens interactive component gallery)
+  - Total reduction: 618 lines → 497 lines across 5 files
+
+#### Added
+- **Enhanced Security** - Comprehensive input validation for component names
+  - Blocks path traversal attacks (`../`, `..\`, `/../`, `\..\`)
+  - Prevents path separator usage in component names (`/`, `\`)
+  - Validates both interactive prompts and command-line flags
+  - Maximum name length limit (100 characters)
+  - Allows legitimate names with dots (e.g., "my-component-2.0")
+  - Protects against directory traversal to parent/system directories
+
+#### Technical Improvements
+- Better code maintainability with modular architecture
+- Improved performance with ES Modules tree-shaking
+- Cleaner separation of concerns (each command in its own file)
+- Enhanced error handling and validation
+- All file imports include `.js` extension (ES Modules requirement)
+- Cross-platform `__dirname` support in ES Modules environment
+
 ## [2.0.2] - 2026-02-05
 
 ### Fixed

package/HTML-VS-REACT.md

@@ -0,0 +1,289 @@
+# HTML vs React - Which Should You Choose? 🤔
+
+This guide helps you decide whether to use HTML/CSS/JS templates or React components.
+
+## Quick Decision Tree
+
+```
+Do you need a static website or simple interactive page?
+├─ Yes → Use HTML/CSS/JS templates ✅
+└─ No → Continue
+
+Are you building a complex single-page application (SPA)?
+├─ Yes → Use React components ⚛️
+└─ No → Continue
+
+Do you need component reusability and state management?
+├─ Yes → Use React components ⚛️
+└─ No → Use HTML/CSS/JS templates ✅
+
+Do you already have a React project?
+├─ Yes → Use React components ⚛️
+└─ No → Use HTML/CSS/JS templates ✅
+```
+
+## HTML/CSS/JS Templates
+
+### ✅ Use When:
+
+- **Static Websites**: Landing pages, portfolios, blogs
+- **Simple Projects**: Small interactive pages without complex state
+- **Learning**: You're learning web development basics
+- **No Build Tools**: You want to avoid npm, webpack, vite, etc.
+- **Quick Prototypes**: Fast mockups and demos
+- **Direct Integration**: Adding to existing plain HTML projects
+- **SEO Priority**: Need server-side rendering without complexity
+
+### 📦 What You Get:
+
+```
+my-component/
+├── index.html       # Ready to open in browser
+├── css/
+│   └── style.css   # Styled and ready
+└── js/
+    └── script.js   # Vanilla JavaScript
+```
+
+### 🚀 Usage:
+
+```bash
+create-template create -c button -n my-button
+cd my-button
+# Just open index.html in browser - no build step!
+```
+
+### Example Use Cases:
+
+1. **Portfolio Website**: Use navigation, hero, footer templates
+2. **Landing Page**: Use hero, form, card templates
+3. **Documentation Site**: Use navigation, tabs, accordion
+4. **Business Website**: Use navigation, footer, form, card
+5. **Game Projects**: Use 16 interactive game templates
+6. **Prototyping**: Quick component mockups
+
+## React Components
+
+### ⚛️ Use When:
+
+- **Single Page Applications (SPAs)**: Complex interactive apps
+- **Component Reusability**: Need to use components multiple times
+- **State Management**: Complex data flows and state updates
+- **Modern Workflow**: Already using npm and build tools
+- **React Projects**: Integrating into existing React apps
+- **Team Collaboration**: Working with React-focused teams
+- **Scalability**: Building large applications
+
+### 📦 What You Get:
+
+```
+my-component/
+├── src/
+│   ├── components/
+│   │   └── Button/
+│   │       ├── Button.jsx
+│   │       └── Button.css
+│   ├── App.jsx
+│   └── index.js
+├── package.json
+├── vite.config.js
+└── index.html
+```
+
+### 🚀 Usage:
+
+```bash
+create-template create --react -c button -n my-button
+cd my-button
+npm install
+npm run dev
+```
+
+### Example Use Cases:
+
+1. **Dashboard Application**: Use counter, card, modal
+2. **Todo Application**: Use todo-list component
+3. **Form-Heavy Apps**: Use form component with validation
+4. **Admin Panels**: Use button, card, modal, form
+5. **Interactive UI**: Components with complex state
+6. **Component Libraries**: Building reusable component sets
+
+## Feature Comparison
+
+| Feature | HTML/CSS/JS | React |
+|---------|-------------|-------|
+| **Setup Time** | Instant | 2-3 minutes (npm install) |
+| **Learning Curve** | Beginner-friendly | Requires React knowledge |
+| **Build Tools** | None required | Vite (fast modern build) |
+| **File Size** | Smaller | Larger (includes React) |
+| **State Management** | Manual DOM | React hooks |
+| **SEO** | Excellent | Requires SSR/SSG |
+| **Browser Support** | All browsers | Modern browsers |
+| **Hot Reload** | Manual refresh | Automatic (HMR) |
+| **Component Reuse** | Copy/paste HTML | Import/export |
+| **TypeScript** | Not included | Easy to add |
+| **Testing** | Manual | Jest/Testing Library |
+| **Available Components** | 46 templates | 6 components |
+
+## Available Templates/Components
+
+### HTML Templates (46)
+
+**UI Components:**
+- button, card, form, navigation, modal, footer, hero
+- slider, table, login, register, skeleton, spinner
+- animated-card, typing-effect, fade-gallery
+- accordion, tabs, todo-list, counter
+
+**Layouts:**
+- grid-layout, flex-layout, flex-cards, flex-dashboard
+- dashboard-grid, masonry-grid
+
+**Games (16):**
+- tic-tac-toe, memory-game, snake-game, guess-number
+- game-2048, whack-a-mole, simon-says, rock-paper-scissors
+- breakout, tetris, flappy-bird, connect-four
+- blackjack, slot-machine, dice-game, pong
+
+### React Components (6)
+
+- Button, Card, Counter, Form, Modal, Todo List
+
+## Performance Considerations
+
+### HTML/CSS/JS:
+- ✅ Faster initial load (no framework)
+- ✅ Smaller file sizes
+- ✅ Better for static content
+- ⚠️ Manual DOM updates can be slow at scale
+
+### React:
+- ⚠️ Larger bundle size (React library)
+- ✅ Efficient updates with Virtual DOM
+- ✅ Better for dynamic content
+- ✅ Optimized rendering with reconciliation
+
+## Development Experience
+
+### HTML/CSS/JS:
+```bash
+# Create and run
+create-template create -c button -n my-button
+cd my-button
+# Open index.html - Done! ✅
+```
+
+**Pros:**
+- No installation time
+- Works everywhere
+- Easy to debug
+- Instant preview
+
+**Cons:**
+- Manual DOM manipulation
+- No component composition
+- Harder to maintain at scale
+
+### React:
+```bash
+# Create and run
+create-template create --react -c button -n my-button
+cd my-button
+npm install  # 30-60 seconds
+npm run dev  # Starts dev server
+```
+
+**Pros:**
+- Hot Module Replacement
+- Component composition
+- Easy state management
+- Better tooling
+
+**Cons:**
+- Requires Node.js
+- Build step needed
+- Steeper learning curve
+
+## Migration Path
+
+### Start with HTML, Move to React:
+
+1. **Learn basics with HTML templates**
+   ```bash
+   create-template create -c button -n html-button
+   ```
+
+2. **Get comfortable with React**
+   ```bash
+   create-template create --react -c button -n react-button
+   ```
+
+3. **Compare and learn the differences**
+
+4. **Choose based on project needs**
+
+## Recommendations by Project Type
+
+### Choose HTML/CSS/JS for:
+- 📄 Portfolio websites
+- 🎯 Landing pages
+- 📚 Documentation sites
+- 🎮 Simple games
+- 📧 Email templates
+- 🎨 Quick prototypes
+- 🏢 Small business sites
+
+### Choose React for:
+- 📱 Mobile-like web apps
+- 🎛️ Admin dashboards
+- 📊 Data visualization
+- ✅ Task management apps
+- 🛒 E-commerce apps
+- 💬 Chat applications
+- 🎮 Complex game interfaces
+
+## Cost Considerations
+
+### HTML/CSS/JS:
+- **Hosting**: Cheapest (static hosting)
+- **CDN**: Very affordable
+- **Bandwidth**: Minimal
+- **Servers**: No server-side logic needed
+
+### React:
+- **Hosting**: Static hosting (after build)
+- **CDN**: Same as HTML
+- **Bandwidth**: Slightly more (React bundle)
+- **Build Time**: Requires build step in CI/CD
+
+## Conclusion
+
+**Both options are great!** The choice depends on your:
+- Project complexity
+- Team expertise
+- Performance requirements
+- Development timeline
+- Maintenance needs
+
+**General Rule:**
+- Simple project? → HTML/CSS/JS ✅
+- Complex app? → React ⚛️
+- Not sure? → Start with HTML/CSS/JS, migrate if needed
+
+## Still Unsure?
+
+Try both and see which fits your workflow:
+
+```bash
+# Try HTML version
+create-template create -c counter -n counter-html
+
+# Try React version
+create-template create --react -c counter -n counter-react
+
+# Compare the code!
+```
+
+---
+
+**Need help deciding?** [Open an issue](https://github.com/benshabbat/create-template-html-css/issues) and we'll help you choose! 💡