create-ng-tailwind 3.1.0 → 4.1.0

package/CHANGELOG.md

@@ -5,397 +5,152 @@ 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).
 
-## [3.1.0] - 2025-11-30
+## [4.1.0] - 2026-06-06
 
 ### ✨ New Features
 
-- **simple-git-hooks**: Added lightweight pre-commit hooks (~1KB vs Husky's ~40KB)
-  - Runs `npm run lint` before each commit
-  - Auto-setup via `prepare` script on `npm install`
-  - Config stored in package.json (no separate folder)
-  - Zero dependencies, much simpler than Husky
-
-### 🗑️ Removed
-
-- **Husky**: Replaced Husky and lint-staged with simple-git-hooks
-  - Removed `husky` and `lint-staged` dev dependencies
-  - Removed `setupHusky()` method
-  - Lighter alternative with same functionality
+- **Node.js / Angular auto-compatibility**: The CLI now detects the current Node.js runtime and automatically picks the highest compatible Angular CLI release instead of always pulling `@angular/cli@latest`. This fixes the common `EBADENGINE` failure when scaffolding on a Node version below Angular 22's minimum.
+- **`--ng-version <version>` flag**: New CLI flag to pin a specific Angular CLI major (e.g. `--ng-version=21`, `--ng-version=latest`). When omitted, the highest compatible version is selected automatically.
+- **Friendly preflight error**: If no supported Angular version matches the current Node.js, the CLI exits early with a formatted message listing supported Node↔Angular combinations and upgrade hints — instead of forwarding npm's cryptic engine warnings.
 
-## [3.0.0] - 2025-11-30
-
-### 💥 Breaking Changes
+### 📋 Supported Angular Versions
 
-- **Angular CLI Alignment**: Now fully relies on Angular CLI for project configuration
-  - Removed custom `ensureZoneJs()` method - Angular CLI handles zone.js natively
-  - Explicitly passes `--zoneless=false` or `--zoneless=true` to Angular CLI in non-interactive mode
-  - Projects now match exactly what `ng new` produces interactively
+| Angular CLI | Required Node.js |
+| ----------- | ---------------- |
+| 22 (latest) | `^22.22.3 \|\| ^24.15.0 \|\| >=26.0.0` |
+| 21          | `^20.19.0 \|\| ^22.12.0 \|\| >=24.0.0` |
+| 20          | `^20.11.1 \|\| ^22.0.0 \|\| ^24.0.0`   |
+| 19          | `^18.19.1 \|\| ^20.11.1 \|\| ^22.0.0`  |
 
-### 🐛 Bug Fixes
+### 🏗️ Internal
 
-- **zone.js Configuration**: Fixed issue where zone.js was not being properly configured when selecting "No" for zoneless application
-  - Fixes runtime error `NG0908: In this configuration Angular requires Zone.js`
-
-## [2.2.0] - 2025-11-01
+- New module `lib/utils/nodeCompat.js` containing the compatibility table, a tiny range matcher, and the resolver.
+- `ProjectManager` now reads `config.angularVersion` instead of hardcoding `@latest` in the scaffold command.
 
-### ✨ New Features - Comprehensive Tailwind v4 Theming System
-
-- **Complete Theme System using Tailwind v4 @theme directive**:
-  - Added comprehensive color theming with 7 semantic color scales (primary, secondary, accent, success, danger, warning, info)
-  - Each color includes full 50-950 scale for maximum flexibility
-  - All colors defined using modern `@theme` directive in `styles.css`
-  - Automatic utility class generation (bg-*, text-*, border-*, ring-*, etc.)
-
-- **Theme Customization**:
-  - Easy customization by editing CSS custom properties in `styles.css`
-  - Clear documentation and usage examples in theme configuration
-  - All components automatically update when theme colors change
-  - No JavaScript configuration needed - pure CSS approach
-
-- **Updated All Components to Use Theme Colors**:
-  - ButtonComponent: Uses primary, secondary, and danger theme colors
-  - ToastComponent: Uses success, danger, warning, and info colors
-  - LoadingSpinnerComponent: Supports all theme color variants
-  - Contact page: Gradient backgrounds using primary, secondary, and accent
-  - Header component: Navigation and active states use primary theme
-  - Home & About pages: Hero sections and feature cards use theme colors
-  - Auth pages: Login, Register, Forgot Password use primary theme
-  - Footer: Links use primary theme colors
-
-- **Developer Experience**:
-  - Comprehensive inline documentation in `styles.css`
-  - Usage examples for all theme colors
-  - Clear instructions for customization
-  - Consistent color usage across all generated components
-
-### 🎨 Design Improvements
-
-- Replaced all hardcoded blue, cyan, red, green colors with semantic theme colors
-- Updated gradients to use primary-secondary-accent combinations
-- Error states now use danger theme color instead of hardcoded red
-- Success states use success theme color instead of hardcoded green
-- Info messages use info theme color
-- Warning states use warning theme color
+---
 
-## [2.1.1] - 2025-10-30
+## [4.0.0] - 2025-12-25
 
-### 🐛 Fixed
+### ✨ New Template
 
-- **SSR Hydration Error in Contact Form**: Fixed NG0500 hydration mismatch in contact component textarea
-  - Removed whitespace between textarea opening and closing tags
-  - Prevents "Angular expected a text node but the node was not found" error
-  - Ensures proper SSR hydration when Server-Side Rendering is enabled
+- **Dashboard Template**: Complete admin dashboard with sidebar navigation, charts, data tables, and analytics
 
-- **AI Config Prettier Formatting**: All AI configuration templates (CLAUDE.md, .cursorrules, .windsurfrules) now pass Prettier formatting checks automatically
-  - Added empty lines before code blocks for proper markdown formatting
-  - Added parentheses around arrow function parameters (arrowParens: "always")
-  - Reordered Tailwind CSS classes according to prettier-plugin-tailwindcss
-  - Added trailing commas in objects and arrays per Prettier config
-  - Fixed HTML example indentation and structure
-  - Renamed Claude file to CLAUDE.md (uppercase) to match Angular CLI convention
-  - Scaffolded projects now pass `npm run format:check` without manual fixes
+### 📊 Template Count: 4 Total
 
-## [2.1.0] - 2025-10-28
+1. **Minimal** - Clean slate (Angular + Tailwind CSS only)
+2. **Starter** - Professional foundation with auth, i18n, SEO
+3. **Dashboard** - Admin panel with charts and analytics (NEW)
 
-### ✨ New Features - Simple SEO Solution
-
-- **Simple SEO Service** (Easy to use, easy to extend):
-  - ✅ Dynamic meta tags (title, description, keywords)
-  - ✅ Open Graph tags for social sharing (Facebook, LinkedIn)
-  - ✅ Twitter Card tags for optimized sharing
-  - ✅ Canonical URL management (auto-updated on route changes)
-  - ✅ Structured data (JSON-LD) support
-  - 🎯 **Only 2 methods**: `updateMeta()` and `addStructuredData()` - that's it!
-  - 📝 Well-documented with clear examples
-  - 🔧 Developers can easily extend with more features as needed
-
-- **Essential Structured Data**:
-  - ✅ Organization schema (company info, logo, social profiles)
-  - ✅ WebSite schema (site name, description)
-  - 💡 Comment in code shows how to add more schemas (Article, Product, FAQ, etc.)
-  - 🎯 Keep it simple - only what's actually being used
-
-- **SEO Assets**:
-  - `robots.txt` - Properly configured for Angular apps with sitemap reference
-  - Default Open Graph image (1200x630px SVG placeholder)
-  - Complete favicon set (SVG with project initial)
-  - Apple Touch Icon for iOS devices
-  - Android Chrome icons (192x192 and 512x512)
-  - Logo SVG with project branding
-  - All placeholders include clear instructions for replacement
-
-- **Pre-Integrated & Ready to Use**:
-  - ✅ All page components (Home, About, Contact) have SEO meta tags configured
-  - ✅ App component includes Organization and WebSite structured data
-  - ✅ SEO service auto-updates canonical URLs on navigation
-  - ✅ Works seamlessly with existing i18n system
-  - ✅ SSR-compatible for server-side rendering
-  - ✅ TypeScript interfaces for type safety
-  - ✅ Well-documented with JSDoc comments and usage examples
-
-### 🧹 Maintenance
-
-- **Package Cleanup**: Removed CLAUDE.md from published package (internal development file)
+### 🎨 Dashboard Features
 
-### 🐛 Fixed
+- **Layout**
+  - Collapsible sidebar navigation with icons
+  - Dashboard header with user profile dropdown
+  - Language switcher (EN/AR) with RTL support
+  - Dark mode ready
+  - Responsive mobile-first design
 
-- **LICENSE Link**: Fixed LICENSE link in README to work properly on npmjs.com (changed from relative link to descriptive text)
-- **Directory Overwrite Flow**: Ensured consistent behavior between local and npx usage. Directory existence check now always happens AFTER configuration questions in both cases.
+- **Components**
+  - Stats cards with icons and trend indicators
+  - Chart components (Bar, Line, Donut)
+  - Data table with sorting and pagination
+  - Breadcrumb navigation
 
-## [2.0.2] - 2025-10-24
+- **Pages**
+  - Overview - Dashboard home with stats and charts
+  - Analytics - Detailed metrics and visualizations
+  - Users - User management with data table
+  - Orders - Order tracking and management
+  - Settings - Application settings
 
-### 📝 Documentation
+- **i18n Support**
+  - English and Arabic translations
+  - RTL/LTR direction switching
+  - Language persistence
 
-- **CHANGELOG**: Added v2.0.1 and v2.0.2 entries to published package
-- **PUBLISHING.md**: Updated version references and simplified guidance
+### 🏗️ Architecture Improvements
 
-## [2.0.1] - 2025-10-24
+- **Modular Template Structure**: Templates now use modular file organization (app.js, layout.js, pages.js, components.js, charts.js, i18n.js)
+- **Base Template Refactored**: Split into focused modules (services, components, infrastructure, linting, pwa)
 
-### 📝 Documentation Improvements
-
-- **README Enhancements**: Removed "Related Projects" section, consolidated duplicate support sections, improved project structure documentation
-- **Terminal Output**: Simplified CLI output to be minimal and professional with green checkmarks and white text
-- **Accuracy Fixes**: Corrected pipe count from 4 to 2 (Truncate, TimeAgo) in all documentation and translations
-- **Better Organization**: Enhanced "Starter Template Features" section with detailed breakdown of core services, UI components, and utilities
-
-## [2.0.0] - 2025-01-20
+---
 
-**Major Release with Breaking Changes** - This release includes significant updates to the CLI architecture, template system, and development workflow. Review the breaking changes and migration guide below before upgrading.
+## [3.1.0] - 2025-11-30
 
-### 📈 Release Highlights
+### ✨ New Features
 
-- ✨ **Professional Starter Template** with 20+ production-ready features (i18n, auth UI, interceptors, services)
-- 🎨 **Simplified CSS-Only Approach** aligned with Tailwind v4 official recommendations
-- 🎯 **Enhanced User Experience** with interactive mode by default (like `ng new`)
-- 🔒 **Private Repository Model** focused on quality and stability
-- 🤖 **Advanced AI Integration** supporting 6 different AI development tools
-- 🎮 **Interactive UI Components** including Toast notifications, Modal dialogs, and custom directives
+- **simple-git-hooks**: Lightweight pre-commit hooks (~1KB vs Husky's ~40KB)
+  - Runs `npm run lint` before each commit
+  - Auto-setup via `prepare` script
+  - Config in package.json
 
-### 🚨 BREAKING CHANGES
+### 🗑️ Removed
 
-- **CSS-Only Approach**: Removed SCSS/Sass/Less support - CSS is now the only stylesheet option (aligns with Tailwind v4 official recommendations)
-- **Template System Redesign**: Changed template option from "none" to "minimal" for better clarity
-- **Interactive Mode is Default**: Removed `--interactive` flag - interactive mode is now default behavior (like `ng new`)
-- **Repository Now Private**: No longer accepting public contributions - package remains available on npm
+- **Husky**: Replaced with simple-git-hooks
 
-### 🎉 Major New Features
+---
 
-- 🤖 **AI Configuration Files (Tool-Specific)**
+## [3.0.0] - 2025-11-30
 
-  - Creates `.claude/claude.md` if Claude is selected
-  - Creates `.cursorrules` if Cursor is selected
-  - Creates `.windsurfrules` if Windsurf is selected
-  - Each config file includes comprehensive Angular + Tailwind guidelines
-  - Includes project structure, tech stack, coding patterns, and examples
-  - Works with Claude Code, Cursor, Copilot, Windsurf, Gemini, and JetBrains
-  - ~400 lines of context for AI assistants
+### 💥 Breaking Changes
 
-- ⚡ **HTTP Interceptors (Starter Template)**
+- **Angular CLI Alignment**: Explicitly passes `--zoneless` flag to Angular CLI
+  - Fixes NG0908 zone.js runtime error
 
-  - **Auth Interceptor** - Automatically adds JWT tokens to requests
-  - **Error Interceptor** - Global error handling with toast notifications
-  - **Loading Interceptor** - Shows/hides loading state automatically
-  - **Caching Interceptor** - Caches GET requests (5min TTL)
-  - All interceptors pre-configured in `app.config.ts`
+---
 
-- 🔔 **Toast/Notification System (Starter Template)**
+## [2.2.0] - 2025-11-01
 
-  - `ToastService` with success, error, warning, info methods
-  - Animated toast component with auto-dismiss
-  - Queue management for multiple toasts
-  - Fully integrated in root app component
+### ✨ Tailwind v4 Theming
 
-- 💬 **Modal/Dialog System (Starter Template)**
+- Complete color theming with `@theme` directive
+- 7 semantic color scales (primary, secondary, accent, success, danger, warning, info)
+- All components updated to use theme colors
 
-  - `ModalService` with confirm, alert, and custom modal support
-  - Promise-based API for easy async handling
-  - Configurable sizes (sm, md, lg, xl, full)
-  - Gray semi-transparent backdrop (bg-opacity-30) for better visibility
-  - Backdrop click and ESC key support
-  - Full keyboard accessibility (ARIA roles, tabindex)
+---
 
-- 🔧 **Truncate Pipe (Starter Template)**
+## [2.1.1] - 2025-10-30
 
-  - `TruncatePipe` - Text truncation with word boundaries and custom ellipsis
+### 🐛 Fixed
 
-- 🎮 **Interactive Examples on Home Page (Starter Template)**
+- SSR hydration error in contact form
+- AI config templates now pass Prettier checks
 
-  - Live Toast notification examples (Success, Error, Warning, Info)
-  - Modal dialog demonstrations (Confirm, Alert)
-  - Practical code examples showing ToastService and ModalService usage
-  - Helps users understand how to use included services
+---
 
-- ✨ **Custom Directives (Starter Template)**
+## [2.1.0] - 2025-10-28
 
-  - `ClickOutsideDirective` - Detect clicks outside element
-  - `TooltipDirective` - Beautiful tooltips with positioning
+### ✨ SEO Service
 
-- 🛠️ **Supporting Services (Starter Template)**
-  - `LoadingService` - Reactive loading state with signals
-  - `CacheService` - HTTP response caching with TTL
+- Dynamic meta tags, Open Graph, Twitter Cards
+- Structured data (JSON-LD) support
+- robots.txt, favicons, OG images
 
-### 🔧 Changed
+---
 
-- **Template Renamed**: "none" → "minimal" for better clarity
-- **Interactive Mode is Default**: CLI now prompts for all configuration options by default (like `ng new`)
-- **Repository Visibility**: Changed from public to private repository
-- **Package Structure**: Simplified to focus on core CLI functionality
-- **Documentation**: Updated all documentation to reflect private repository model
+## [2.0.0] - 2025-01-20
 
-### 🗑️ Removed
+### 🚨 Breaking Changes
 
-- **Test Suite**: Removed `test.js` and all test-related infrastructure
-- **Public Contributions**: Removed CONTRIBUTING.md and contribution workflow
-- **GitHub Integration**: Removed repository URLs and issue tracking references
-- **SCSS/Sass/Less Support**: Removed preprocessor support (CSS-only approach for Tailwind v4)
+- CSS-only approach (removed SCSS/Sass/Less)
+- Template renamed: "none" → "minimal"
+- Interactive mode is now default
 
-### 🐛 Fixed
+### ✨ Major Features
 
-- 🔧 **ESLint & TypeScript Compliance (Starter Template)**
-
-  - Created proper `ModalData` interface with typed properties
-  - Replaced `HttpResponse<any>` with `HttpResponse<unknown>` in CacheService
-  - Removed unused imports (createComponent, ApplicationRef, EnvironmentInjector)
-  - Fixed accessibility issues in ModalComponent (ARIA roles, keyboard handlers)
-  - Added helper methods (`getModalType()`, `getModalMessage()`) to avoid index signature issues
-  - Used `eslint-disable-next-line` for legitimate `any` use in Promise resolver
-  - **Fixed Angular v20 `app.ts` ESLint error** - Added "App" to allowed component class suffixes to support Angular v20's new naming convention
-  - All generated code now compiles and passes `ng lint` without errors
-
-- 📝 **Template Renamed: "none" → "minimal"**
-
-  - Better clarity: "Minimal" describes clean Angular + Tailwind starter
-  - Updated CLI descriptions to show feature differences
-  - All documentation and prompts updated
-
-- 🎨 **Starter Template Enhanced**
-
-  - Updated feature list in CLI with all new capabilities
-  - Now shows: "Professional foundation (routing, i18n, auth UI, components, services, interceptors)"
-  - Feature count increased from 15 to 20+ features
-
-- 🎯 **CSS-Only Approach (Tailwind v4 Official)** 🚨 **BREAKING CHANGE**
-
-  - **Removed SCSS/Sass/Less support** - CSS is now the only stylesheet option
-  - Aligns with **Tailwind CSS v4 official recommendations** (v4 doesn't support preprocessors)
-  - Removed `--style` CLI option
-  - Removed stylesheet format prompt from interactive mode
-  - Always uses CSS with modern features (nesting, variables)
-  - Simpler, faster builds with PostCSS + LightningCSS
-  - Migration note: If you need SCSS, use Tailwind CSS v3 or migrate to modern CSS
-
-- 🎯 **Interactive Mode is Now Default** (Like `ng new`)
-  - CLI now prompts for all configuration options by default
-  - Removed `--interactive` flag (interactive is now the default behavior)
-  - Questions asked in order:
-    1. Project name (if not provided)
-    2. Template (None or Starter)
-    3. Enable SSR? (Server-Side Rendering)
-    4. Enable Zoneless? (without zone.js)
-    5. AI tools to configure (None, Claude, Cursor, Gemini, Copilot, JetBrains, Windsurf) - **Multiple selection supported**
-  - All prompts can be skipped by providing values via CLI flags
-  - Example: `npx create-ng-tailwind my-app --template=starter`
-
-### Added
-
-- 🎨 **New CLI Options**:
-  - `--routing` / `--no-routing` - Enable/disable Angular routing
-  - `--ssr` - Enable Server-Side Rendering
-  - `--zoneless` - Create zoneless application
-  - `--ai-config <tools>` - Configure AI tools (delegated to Angular CLI)
-- 🌍 **i18n Translation Support** (Starter template)
-  - Full English and Arabic translations
-  - Reactive language switcher in header (desktop & mobile)
-  - RTL (Right-to-Left) support for Arabic
-  - Auto-detects browser language
-  - Saves language preference to localStorage
-  - Uses `@ngx-translate` with HTTP loader
-  - Translation files in `public/assets/i18n/`
-  - All components, pages, and UI elements translated
-- 📁 **Assets now in `public/assets/`** instead of `src/assets/`
-  - Translation files: `public/assets/i18n/`
-  - Images: `public/assets/images/`
-  - Removed empty `src/styles/` folder
-
-### Improved
-
-- Better user experience: Interactive prompts guide users through setup like `ng new`
-- More discoverable: Users see all available options during setup
-- Proper Angular project structure with assets in public folder
-- Fast mode available for CI/CD by providing all options via flags
-- AI configuration delegated to Angular CLI for native support and updates
-
-### 📊 Migration Guide from v1.x to v2.0
-
-#### Breaking Changes Impact:
-
-1. **CSS-Only Approach**:
-
-   - **Before (v1.x)**: `--style` flag supported css, scss, sass, less
-   - **After (v2.0)**: Only CSS is supported (--style flag removed)
-   - **Migration**: If you need SCSS, continue using v1.x or migrate to modern CSS
-
-2. **Template Names**:
-
-   - **Before (v1.x)**: `--template=none`
-   - **After (v2.0)**: `--template=minimal`
-   - **Migration**: Update scripts to use `minimal` instead of `none`
-
-3. **Interactive Mode**:
-
-   - **Before (v1.x)**: Non-interactive by default, `--interactive` flag to enable
-   - **After (v2.0)**: Interactive by default, provide all flags to skip prompts
-   - **Migration**: Add all required flags to CI/CD scripts for non-interactive mode
-
-4. **Repository & Support**:
-   - **Before (v1.x)**: Public repository accepting contributions
-   - **After (v2.0)**: Private repository, email-based support only
-   - **Migration**: Contact via email for support (tehseen_ullah786@hotmail.com)
-
-#### Recommended Update Command:
-
-```bash
-# Update to v2.0.0
-npx create-ng-tailwind@latest my-app --template=minimal
-
-# Or with starter template (recommended)
-npx create-ng-tailwind@latest my-app --template=starter
-```
+- AI configuration files (Claude, Cursor, Windsurf)
+- HTTP interceptors (Auth, Error, Loading, Caching)
+- Toast & Modal systems
+- i18n with RTL support
+- Custom directives (ClickOutside, Tooltip)
 
 ---
 
 ## [1.0.0] - 2025-09-03
 
-### Added
-
-- 🚀 Initial release of create-ng-tailwind CLI
-- ✨ Angular 20 project scaffolding with Tailwind preconfigured
-- 🎨 Modern Tailwind setup using `@tailwindcss/postcss`
-- 📋 Interactive mode (`--interactive`) with guided prompts
-- ⚡ Fast non-interactive mode with best practice defaults
-- 🛠️ Traditional Angular file naming (`*.component.*`)
-- 🔧 Comprehensive CLI options:
-  - Angular routing (enabled by default)
-  - Server-Side Rendering (SSR) support
-  - Zoneless application support
-  - AI tools configuration
-- 🎯 Beautiful starter templates with Tailwind examples
-- 📱 Responsive design examples
-- 📚 Professional documentation
-
-### Features
-
-- **Best Practice Defaults**: CSS + Routing + No AI tools
-- **Zero Configuration**: Works out of the box
-- **Professional Setup**: Traditional Angular file structure
-- **Modern Tooling**: Latest Angular and Tailwind versions
-- **Cross-Platform**: Windows, macOS, and Linux support
-
-## [Unreleased]
-
-### Planned
-
-- Angular schematic support (`ng add`)
-- UI library integrations
-- Authentication boilerplates
-- Docker setup
+### 🚀 Initial Release
+
+- Angular 20 + Tailwind CSS v4 scaffolding
+- Interactive CLI with guided prompts
+- SSR and zoneless support
+- AI tools configuration