@ng-zen/cli 19.0.0-alpha.5 → 19.1.0

package/DEVELOPMENT.md

@@ -0,0 +1,138 @@
+# Local Development Setup
+
+This guide details setting up a local development environment for **@ng-zen/cli**. It covers the necessary tools, the project's branching strategy, and the automated workflows in place.
+
+**For a step-by-step guide specifically for external contributors submitting Pull Requests, please refer to `CONTRIBUTING.md`.**
+
+**Key Technologies & Concepts:**
+
+- **pnpm:** The required package manager (version in `package.json`). Use Corepack (`corepack enable`).
+- **Storybook:** For UI component development and visualization.
+- **Conventional Commits:** **Mandatory format** for commit messages (https://www.conventionalcommits.org/). Crucial for automation.
+- **Automated Formatting/Linting:** `husky` + `nano-staged` apply formatting and basic fixes on commit.
+- **Automated CI:** GitHub Actions (`ci.yml`) validate Pull Requests.
+- **Automated Releases:** `semantic-release` manages releases based on commits.
+- **Branching Strategy:** Detailed below.
+
+## Table of Contents
+
+- [Prerequisites & Setup](#prerequisites--setup)
+- [Branching Strategy & Workflow](#branching-strategy--workflow)
+- [Commit Messages (Crucial!)](#commit-messages-crucial)
+- [Branch Synchronization (Maintainer Task)](#branch-synchronization-maintainer-task)
+- [Working with Storybook](#working-with-storybook)
+- [Running Tests and Linting](#running-tests-and-linting)
+- [Building the Library](#building-the-library)
+- [Optional: Local Testing with Verdaccio](#optional-local-testing-with-verdaccio)
+
+## Prerequisites & Setup
+
+1.  Ensure **Node.js** is installed (use a version compatible with the project's Angular version; check CI workflows for reference).
+2.  Enable **Corepack**: `corepack enable`.
+3.  Clone the repository.
+4.  Install dependencies using **pnpm**: `pnpm install`.
+
+## Branching Strategy & Workflow
+
+This project employs a branching model designed for stability and automated releases:
+
+- **`master`**: Contains only **stable, production-ready** code. Receives merges only from `next` during official releases or for critical hotfixes. Automated stable releases (`vX.Y.Z`) are triggered from here. **Direct work is forbidden.**
+- **`next`**: The **pre-release / release candidate** branch. Code merged here from `develop` should be stable enough for final testing. Merges trigger automated pre-releases (`vX.Y.Z-next.N`) published to NPM under the `next` dist-tag.
+- **`develop`**: The main **integration branch**. All feature branches are merged here first. This branch collects changes intended for the _next_ release cycle. **Target Pull Requests here.**
+- **Feature/Fix Branches (`feature/*`, `fix/*`, etc.)**: Used for individual tasks. Always branch **off `develop`**.
+
+**General Flow:** `Feature/Fix Branch` -> **`develop`** -> `next` -> `master`
+
+## Commit Messages (Crucial!)
+
+Strict adherence to the **Conventional Commits** specification (https://www.conventionalcommits.org/) is **required**.
+
+- **Why?** Commit messages directly control automatic version bumping (`semantic-release`) and `CHANGELOG.md` generation.
+- **Format:** `<type>(<scope>): <subject>` (e.g., `feat(button): add loading spinner`).
+- **Key Types & Impact (on Stable Release):**
+- `feat`: New feature -> `minor` version bump.
+- `fix`: Bug fix -> `patch` version bump.
+- `!` (e.g., `refactor(core)!:`) or `BREAKING CHANGE:` footer -> `major` version bump.
+- Other types (`docs`, `chore`, `style`, `test`, `ci`, `build`, `refactor`, `perf`) document changes but don't trigger version bumps alone.
+- **Validation:** `husky` + `commitlint` automatically check message format upon commit. Invalid messages will fail the commit.
+
+_(See `CONTRIBUTING.md` for a concise summary focused on the commit action itself)._
+
+## Branch Synchronization (Maintainer Task)
+
+Maintain consistency across `master`, `next`, and `develop` by merging release commits and hotfixes. **Performed by maintainers.**
+
+**General Update Step:** Fetch latest remote state:
+
+```bash
+git fetch origin --prune
+```
+
+### 1. Sync `next` with `master` (After Stable Release or Hotfix)
+
+This is the most comprehensive synchronization, ensuring all development branches are aligned with the latest production code.
+
+- **Purpose:** Incorporate stable changes into the release candidate branch.
+- **Flow:** `master` -> `next`.
+
+  ```bash
+  # Update local 'next', merge 'origin/master', push 'next'
+  git switch next && git pull origin next && git merge origin/master && git push origin next
+  ```
+
+  _(Note: Merge conflicts might occur at either merge step and need manual resolution before continuing/pushing.)_
+
+### 2. Sync `develop` with `next` (After Pre-release on next OR after syncing next with master)
+
+- **Purpose:** Keep `develop` aligned with the latest pre-release state or the latest stable code propagated through next. Includes release commits (`chore(release): ...`).
+- **Flow:** `next` -> `develop`.
+
+  ```bash
+  # Update local 'next', merge 'origin/master', push 'next'
+  git switch develop && git pull origin develop && git merge origin/next && git push origin develop
+  ```
+
+  _(Note: Resolve conflicts before pushing.)_
+
+---
+
+Contributors should regularly update their local `develop` branch (`git switch develop && git pull origin develop`).
+
+## Working with Storybook
+
+Develop and visualize components using Storybook.
+
+- **Start Storybook:**
+  ```bash
+  pnpm run storybook
+  ```
+- **Build Static Storybook:**
+  ```bash
+  pnpm run storybook:build
+  ```
+
+## Running Tests and Linting
+
+`nano-staged` auto-formats/fixes on commit, but manual verification is recommended before creating a PR. The CI (`ci.yml`) runs these checks automatically on PRs.
+
+- **Lint:** `pnpm run lint` (checks for errors not auto-fixed)
+- **Test:** `pnpm run test` (runs unit tests)
+
+## Building the Library
+
+Build the distributable library files:
+
+```bash
+pnpm run build
+```
+
+Output artifacts are placed in the `dist/` directory
+
+## Optional: Local Testing with Verdaccio
+
+Test your local build in a separate project before submitting a PR to develop.
+
+1. Install & Run Verdaccio: `npm install -g verdaccio` (or `pnpm add -g`), then `verdaccio`.\
+2. Build Library: `pnpm run build`.
+3. Publish Locally: `pnpm run publish:verdaccio`.
+4. Install in Test Project: `ng add @ng-zen/cli --registry http://localhost:4873/` (or pnpm add ...).

package/README.md

@@ -1,40 +1,155 @@
 # @ng-zen/cli
 
-## Overview
+[![Build Status (master)](https://img.shields.io/github/actions/workflow/status/kstepien3/ng-zen/ci.yml?branch=master&label=build-master)](https://github.com/kstepien3/ng-zen/actions/workflows/ci.yml)
+[![Build Status (next)](https://img.shields.io/github/actions/workflow/status/kstepien3/ng-zen/ci.yml?branch=next&label=build-next)](https://github.com/kstepien3/ng-zen/actions/workflows/ci.yml)
+[![NPM Version (latest)](https://img.shields.io/npm/v/@ng-zen/cli/latest?label=npm%40latest)](https://www.npmjs.com/package/@ng-zen/cli)
+[![NPM Version (next)](https://img.shields.io/npm/v/@ng-zen/cli/next?label=npm%40next)](https://www.npmjs.com/package/@ng-zen/cli)
+[![License](https://img.shields.io/github/license/kstepien3/ng-zen)](https://github.com/kstepien3/ng-zen/blob/master/LICENSE)
 
-The ng-zen CLI is a command-line tool designed to facilitate the generation of UI-kit elements for Angular applications using Angular schematics. It provides out-of-the-box components that can be quickly integrated into Angular projects.
+[![](https://img.shields.io/badge/-Repository-181818?style=flat&logo=github&logoColor=white)](https://github.com/kstepien3/ng-zen)
+[![](https://img.shields.io/badge/-Storybook%20Demo-FF4785?style=flat&logo=storybook&logoColor=white)](https://kstepien3.github.io/ng-zen/)
 
-## Installation
+Generate modern, customizable Angular UI components and elements directly into your project 🚀
+
+Built with best practices and developer experience in mind 💡
+
+## Table of Contents
+
+1. [Features](#features)
+2. [Ideal for](#ideal-for)
+3. [Quick Start](#quick-start)
+4. [Installation](#installation)
+5. [Usage](#usage)
+6. [Why @ng-zen/cli?](#why-ng-zencli)
+7. [Examples](#examples)
+8. [Documentation](#documentation)
+9. [Project Status](#project-status)
+10. [Contributing](#contributing)
+11. [License](#license)
+12. [Author](#author)
+13. [FAQ](#faq)
+
+## Features
+
+- 🧩 **Component Schematics:** Generates ready-to-use UI component code (`.ts`, `.html`, `.scss`).
+- 🎨 **Fully Customizable:** Easily theme and modify components via CSS variables and editable SCSS.
+- 📱 **Responsive Design:** Components designed to adapt across various screen sizes.
+- 📚 **Comprehensive Documentation:** Includes Storybook examples, JSDoc annotations, and `README.md` per component.
+- ✅ **Test Coverage:** Generated components include unit tests (`.spec.ts`).
+- 🚀 **Modern Angular:** Leverages standalone components, `OnPush` change detection, signals, and current best practices.
+- 🛠 **Extensible:** Planned support for generating directives, pipes, services, and more.
 
-To install ng-zen CLI, use the following command:
+## Ideal for
+
+- 🏢 **Enterprise UI Kits:** A great starting point for building consistent, internal component libraries.
+- 📈 **Custom Projects:** Accelerates development when custom UI elements are needed, avoiding vendor lock-in.
+- 👩‍💻 **Developers:** Speeds up UI creation and ensures adherence to modern Angular patterns.
+
+## Quick Start
+
+The easiest way to add `@ng-zen/cli` and its schematics to your project:
 
 ```bash
 ng add @ng-zen/cli
 ```
 
-This command will add the necessary dependencies and configurations to your Angular project.
+This command installs the package and performs initial setup.
 
-## Generating
+## Installation
 
-You can generate code using the ng-zen CLI.
+Alternatively, you can install it manually:
 
-#### Components
+```bash
+# For the latest stable version
+pnpm add -D @ng-zen/cli
+
+# For the latest pre-release version (includes newest features/fixes)
+pnpm add -D @ng-zen/cli@next
+```
+
+## Usage
+
+### Generating Components
+
+Use the Angular CLI schematic:
 
 ```bash
 ng generate @ng-zen/cli:component
 ```
 
+This interactive prompt guides you through selecting and configuring the desired component(s) 📊.
+
+To see available options without running interactively:
+
+```bash
+ng generate @ng-zen/cli:component --help
+```
+
+### Future Generators
+
+Support for generating other Angular building blocks is planned:
+
+- 📝 Directives
+- 💧 Pipes
+- 🛠 Services
+- ... and more!
+
+## Why @ng-zen/cli?
+
+Unlike pre-compiled UI libraries, `@ng-zen/cli`:
+
+- **Generates Source Code:** You get actual, editable component code in your project, not opaque `<library-button>` tags.
+- **Full Control:** Modify the generated code and styles freely to perfectly match your application's needs.
+- **Modern Foundation:** Built on current Angular features (standalone, signals, etc.).
+- **Transparency:** Understand exactly how components work and evolve them with your project.
+- **Developer Experience:** Focuses on ease of use, customization, and maintainability.
+
+## Examples
+
+Each generated component set includes:
+
+- Angular component code (`.ts`, `.html`, `.scss`)
+- Unit tests (`.spec.ts`)
+- Storybook stories (`.stories.ts`) for visual development and documentation.
+- An `index.ts` for easy exporting.
+- A component-specific `README.md` (generated from a template).
+
+## Documentation
+
+- **Storybook:** The primary source for visual examples and interactive demos: [View Storybook Demo](https://kstepien3.github.io/ng-zen/)
+- **JSDoc:** Code includes documentation comments.
+- **READMEs:** Project-level (`README.md`, `DEVELOPMENT.md`, `CONTRIBUTING.md`) and component-level READMEs.
+- **Changelog:** Automatically generated history of changes: [CHANGELOG.md](https://github.com/kstepien3/ng-zen/blob/master/CHANGELOG.md)
+
+## Project Status
+
+🚧 **Actively Developed** 🚧
+
+- The core schematics and existing components are functional but continuously improved.
+- New generators (directives, pipes, etc.) are planned.
+- The `master` branch represents the latest **stable** release.
+- The `next` branch contains **pre-release** versions with the newest features and fixes – use `@ng-zen/cli@next` to try them out.
+
+Since the tool generates code directly into your project, you own and control that code. Updates to `@ng-zen/cli` itself primarily bring new generator features or improvements to the generation process, not breaking changes to already generated components.
+
+## Contributing
+
+Contributions are highly welcome! If you'd like to help improve `@ng-zen/cli`, please read our **[Contribution Guidelines (CONTRIBUTING.md)](https://github.com/kstepien3/ng-zen/blob/master/CONTRIBUTING.md)** for details on the workflow, commit message requirements, and setup. 🤝
+
 ## License
 
-This project is licensed under the BSD 2-Clause License. For more details, refer to the LICENSE file in the repository.
+This project is licensed under the [BSD 2-Clause License](https://github.com/kstepien3/ng-zen/blob/master/LICENSE) 📜.
 
 ## Author
 
-**@ng-zen/cli** is maintained by Konrad Stępień.
+Maintained by Konrad Stępień.
 
-- Email: kord.stp@gmail.com
-- LinkedIn: [Konrad Stępień](https://www.linkedin.com/in/konradstepien/)
+- GitHub: [@kstepien3](https://github.com/kstepien3)
+- LinkedIn: [Konrad Stępień](https://www.linkedin.com/in/konradstepien/) 👥
+- Email: [kord.stp@gmail.com](mailto:kord.stp@gmail.com?subject=%5BNG-ZEN%5D%20Query) 📨
 
-## Documentation
+## FAQ
+
+### How do I customize a generated component?
 
-The ng-zen CLI is documented using Storybook for component examples and JSDoc, as well as Compodoc for Angular project documentation.
+Generated components reside entirely within your project's source code. You can directly edit the `.ts`, `.html`, and `.scss` files. Components are structured to use CSS variables and SCSS for easier theming and modification.

package/angular.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "cli": {
+    "packageManager": "pnpm",
+    "schematicCollections": ["angular-eslint"]
+  },
+  "newProjectRoot": "projects",
+  "schematics": {
+    "@schematics/angular:component": {
+      "style": "scss",
+      "changeDetection": "OnPush"
+    }
+  },
+  "projects": {
+    "cli": {
+      "projectType": "library",
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "zen",
+      "architect": {
+        "build": {
+          "builder": "./projects/schematic-builder:build",
+          "options": {
+            "files": ["src/**", "README.md", "package.json", "LICENSE", "CHANGELOG.md"],
+            "tsConfig": "tsconfig.schematics.json"
+          }
+        },
+        "test": {
+          "builder": "@angular-builders/jest:run",
+          "options": {
+            "configPath": "./jest.config.ts",
+            "tsConfig": "tsconfig.spec.json"
+          }
+        },
+        "lint": {
+          "builder": "@angular-eslint/builder:lint",
+          "options": {
+            "lintFilePatterns": ["src/**/*.ts", "src/**/*.html"],
+            "eslintConfig": "eslint.config.js"
+          }
+        },
+        "storybook": {
+          "builder": "@storybook/angular:start-storybook",
+          "options": {
+            "configDir": ".storybook",
+            "browserTarget": "cli:build",
+            "compodoc": true,
+            "compodocArgs": ["-e", "json", "-d", "./documentation/"],
+            "port": 6006
+          }
+        },
+        "build-storybook": {
+          "builder": "@storybook/angular:build-storybook",
+          "options": {
+            "configDir": ".storybook",
+            "browserTarget": "cli:build",
+            "compodoc": true,
+            "compodocArgs": ["-e", "json", "-d", "./documentation/"],
+            "outputDir": "dist/storybook"
+          }
+        }
+      }
+    }
+  }
+}

package/eslint.config.js

@@ -0,0 +1,40 @@
+// @ts-check
+const eslint = require('@eslint/js');
+const tseslint = require('typescript-eslint');
+const angular = require('angular-eslint');
+
+module.exports = tseslint.config(
+  {
+    files: ['**/*.ts'],
+    extends: [
+      eslint.configs.recommended,
+      ...tseslint.configs.recommended,
+      ...tseslint.configs.stylistic,
+      ...angular.configs.tsRecommended,
+    ],
+    processor: angular.processInlineTemplates,
+    rules: {
+      '@angular-eslint/directive-selector': [
+        'error',
+        {
+          type: 'attribute',
+          prefix: 'zen',
+          style: 'camelCase',
+        },
+      ],
+      '@angular-eslint/component-selector': [
+        'error',
+        {
+          type: 'element',
+          prefix: 'zen',
+          style: 'kebab-case',
+        },
+      ],
+    },
+  },
+  {
+    files: ['**/*.html'],
+    extends: [...angular.configs.templateRecommended, ...angular.configs.templateAccessibility],
+    rules: {},
+  }
+);

package/jest.config.ts

@@ -0,0 +1,20 @@
+/**
+ * For a detailed explanation regarding each configuration property, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+import type { Config } from 'jest';
+
+export default {
+  clearMocks: true,
+  collectCoverage: true,
+  coverageDirectory: 'coverage',
+  coverageProvider: 'v8',
+  moduleNameMapper: {
+    '^@ng-zen/cli/(.*)': '<rootDir>/src/$1',
+    '^ng-zen/components/(.*)': '<rootDir>/src/schematics/components/files/$1',
+    '^ng-zen/directives/(.*)': '<rootDir>/src/schematics/directives/files/$1',
+  },
+  preset: 'jest-preset-angular',
+  testEnvironment: 'jsdom',
+} satisfies Config;

package/package.json

@@ -1,37 +1,131 @@
 {
   "name": "@ng-zen/cli",
-  "version": "19.0.0-alpha.5",
-  "description": "A blank schematics",
+  "version": "19.1.0",
+  "description": "A CLI tool for generating customizable, modern Angular UI components using schematics.",
+  "scripts": {
+    "ng": "ng",
+    "start": "ng serve",
+    "build": "ng build",
+    "test": "ng test",
+    "lint": "ng lint",
+    "lint:fix": "ng lint --fix",
+    "prepare": "husky",
+    "storybook": "ng run cli:storybook",
+    "storybook:build": "ng run cli:build-storybook",
+    "storybook:doc": "compodoc -e json -p .storybook/tsconfig.json -t",
+    "verdaccio": "verdaccio",
+    "prepublish:verdaccio": "pnpm unpublish @ng-zen/cli --registry http://localhost:4873 --force && pnpm run build",
+    "publish:verdaccio": "cd dist/@ng-zen/cli && npm publish --registry http://localhost:4873/",
+    "semantic-release": "semantic-release"
+  },
   "license": "BSD-2-Clause",
   "private": false,
-  "builders": "./builders/builders.json",
   "repository": {
-    "url": "https://github.com/Kordrad/ng-zen",
-    "directory": "projects/cli"
+    "url": "https://github.com/kstepien3/ng-zen"
   },
   "bugs": {
-    "url": "https://github.com/Kordrad/ng-zen/issues"
+    "url": "https://github.com/kstepien3/ng-zen/issues"
   },
   "author": {
     "name": "Konrad Stępień",
     "email": "kord.stp@gmail.com",
     "url": "https://www.linkedin.com/in/KonradStepien/"
   },
+  "homepage": "https://kstepien3.github.io/ng-zen/",
   "keywords": [
-    "schematics"
+    "angular",
+    "schematics",
+    "ui-components",
+    "angular-cli",
+    "storybook",
+    "customizable-components",
+    "avatar",
+    "button",
+    "checkbox",
+    "input",
+    "textarea"
   ],
   "ng-add": {
     "save": "devDependencies"
   },
   "schematics": "./schematics/collection.json",
+  "packageManager": "pnpm@10.0.0",
   "peerDependencies": {
-    "@angular/common": "^19.1.6",
-    "@angular/core": "^19.1.6"
+    "@angular/common": ">=19.0.0",
+    "@angular/core": ">=19.0.0"
   },
   "dependencies": {
-    "@angular-devkit/core": "^19.1.6",
-    "@angular-devkit/schematics": "^19.1.6",
-    "tslib": "^2.3.0"
+    "@angular-devkit/core": "^19.1.7",
+    "@angular-devkit/schematics": "^19.1.7",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@angular-builders/jest": "^19.0.0",
+    "@angular-devkit/architect": "^0.1902.6",
+    "@angular-devkit/build-angular": "^19.1.5",
+    "@angular-devkit/core": "^19.1.7",
+    "@angular/animations": "^19.1.5",
+    "@angular/cli": "^19.1.7",
+    "@angular/common": "^19.1.5",
+    "@angular/compiler": "^19.1.5",
+    "@angular/compiler-cli": "^19.1.5",
+    "@angular/core": "^19.1.5",
+    "@angular/forms": "^19.1.5",
+    "@angular/platform-browser": "^19.1.5",
+    "@angular/platform-browser-dynamic": "^19.1.5",
+    "@angular/router": "^19.1.5",
+    "@chromatic-com/storybook": "^3.2.6",
+    "@commitlint/cli": "^19.7.1",
+    "@commitlint/config-conventional": "^19.8.0",
+    "@compodoc/compodoc": "^1.1.26",
+    "@eslint/js": "^9.22.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.1",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.3",
+    "@storybook/addon-docs": "^8.5.5",
+    "@storybook/addon-essentials": "^8.5.5",
+    "@storybook/addon-interactions": "^8.5.5",
+    "@storybook/addon-links": "^8.6.12",
+    "@storybook/addon-onboarding": "^8.5.5",
+    "@storybook/angular": "^8.5.3",
+    "@storybook/blocks": "^8.5.3",
+    "@storybook/test": "^8.5.5",
+    "@types/jest": "29.5.14",
+    "angular-eslint": "19.3.0",
+    "conventional-changelog-conventionalcommits": "^8.0.0",
+    "copyfiles": "^2.4.1",
+    "cpy": "^11.1.0",
+    "eslint": "^9.20.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-prettier": "^5.2.3",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "eslint-plugin-storybook": "^0.12.0",
+    "eslint-plugin-unicorn": "^57.0.0",
+    "eslint-plugin-unused-imports": "^4.1.4",
+    "execa": "^9.5.2",
+    "fs-extra": "^11.3.0",
+    "husky": "^9.1.7",
+    "jasmine-core": "~5.6.0",
+    "jest": "^29.7.0",
+    "jest-preset-angular": "^14.5.4",
+    "nano-staged": "^0.8.0",
+    "prettier": "^3.5.3",
+    "prettier-plugin-organize-attributes": "^1.0.0",
+    "rxjs": "~7.8.1",
+    "semantic-release": "^24.2.3",
+    "storybook": "^8.5.5",
+    "stylelint": "^16.17.0",
+    "stylelint-config-standard-scss": "^14.0.0",
+    "typescript": "~5.7.3",
+    "typescript-eslint": "8.29.1"
   },
-  "sideEffects": false
-}
+  "eslintConfig": {
+    "extends": [
+      "plugin:storybook/recommended"
+    ]
+  }
+}

package/projects/schematic-builder/builders/builders.json

@@ -0,0 +1,9 @@
+{
+  "builders": {
+    "build": {
+      "implementation": "./index.js",
+      "schema": "./schema.json",
+      "description": "Custom builder for angular schematics"
+    }
+  }
+}