create-stencil-components 1.0.0

package/dist/templates/base/AGENTS.md

@@ -0,0 +1,118 @@
+# Agent Instructions for this repository
+
+This repository is an Nx monorepo that utilizes StencilJS, TypeScript, and SCSS for building web components.
+
+You are an expert in Nx, StencilJS, TypeScript, SCSS and scalable web application development. You write functional, maintainable, performant, and
+accessible code following StencilJS, TypeScript, and SCSS best practices. When assisting with this codebase, adhere to these standards to ensure
+compatibility, performance, and type safety.
+
+## 1. Project Overview
+
+- **Framework:** StencilJS (latest)
+- **Language:** TypeScript
+- **Styling:** CSS/SASS (Shadow DOM enabled by default)
+- **Testing:** Vitest / Jest / Puppeteer
+
+## 2. Component Structure
+
+Always follow the standard Stencil component decorator pattern:
+
+```tsx
+import { Component, Host, h, Prop, State, Event, EventEmitter } from '@stencil/core';
+
+@Component({
+  tag: 'my-component',
+  styleUrl: 'my-component.scss',
+  shadow: true,
+})
+export class MyComponent {
+  /** Public properties */
+  @Prop() label: string;
+
+  /** Internal state */
+  @State() isActive: boolean = false;
+
+  /** Custom events */
+  @Event() clicked: EventEmitter<void>;
+
+  private handleClick = () => {
+    this.isActive = !this.isActive;
+    this.clicked.emit();
+  };
+
+  render() {
+    return (
+      <Host>
+        <button onClick={this.handleClick}>
+          {this.label} - {this.isActive ? 'Active' : 'Inactive'}
+        </button>
+      </Host>
+    );
+  }
+}
+```
+
+## 3. TypeScript Guidelines
+
+- **Strict Typing:** Avoid `any`. Define interfaces for all complex Prop types.
+- **Decorators:** Use `@Prop()`, `@State()`, `@Method()`, `@Watch()`, and `@Listen()` correctly.
+- **Null Safety:** Use optional chaining `?.` and nullish coalescing `??`.
+- **Enums:** Use `const enum` for performance or literal types for simplicity in Props.
+
+## 4. Best Practices
+
+- **Shadow DOM:** Use `shadow: true` unless there is a specific requirement to use scoped or global CSS.
+- **Functional Components:** Use simple functional components (returning JSX) for UI-only elements that don't need the Stencil lifecycle.
+- **Reactivity:** Remember that Stencil only tracks changes to `@State` and `@Prop`. Arrays and objects must be reassigned (immutable patterns) to trigger a re-render:
+
+  ```typescript
+  // Correct
+  this.items = [...this.items, newItem];
+  // Incorrect
+  this.items.push(newItem);
+  ```
+
+- **Performance:** Minimize use of `@Watch` to avoid unnecessary renders. Use the `render()` method efficiently.
+
+## 5. Styling Rules
+
+- Use CSS Variables for theming to allow consumers to style components from outside the Shadow DOM.
+- Prefer the `:host` selector for base component styling.
+- Use the `<Host>` functional component in the `render()` method to apply classes or attributes to the component container itself.
+
+## 6. Testing
+
+- **Spec Tests:** Focus on logic and rendering.
+- **E2E Tests:** Use for interaction and cross-browser behavior.
+- Ensure all new components include a `.spec.ts` file.
+
+## 7. Documentation
+
+- Use JSDoc comments for all `@Prop`, `@Method`, and `@Event` definitions. Stencil's compiler uses these to generate the `readme.md` files.
+
+## 8. Useful Commands
+
+| Command                 | Description                                 |
+| ----------------------- | ------------------------------------------- |
+| `npx run-many -t clean` | Deletes build outputs for all the packages. |
+| `npx run-many -t build` | Builds all the packages.                    |
+| `npx run-many -t lint`  | Validates the code for all the packages.    |
+| `npx run-many -t test`  | Performs a test run for all the packages.   |
+
+## When stuck
+
+- Ask a clarifying question, propose a short plan, or open a draft PR with notes
+
+<!-- nx configuration start-->
+<!-- Leave the start & end comments to automatically receive updates. -->
+
+## General Guidelines for working with Nx
+
+- When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through `nx` (i.e. `nx run`, `nx run-many`, `nx affected`) instead of using the underlying tooling directly
+- You have access to the Nx MCP server and its tools, use them to help the user
+- When answering questions about the repository, use the `nx_workspace` tool first to gain an understanding of the workspace architecture where applicable.
+- When working in individual projects, use the `nx_project_details` mcp tool to analyze and understand the specific project structure and dependencies
+- For questions around nx configuration, best practices or if you're unsure, use the `nx_docs` tool to get relevant, up-to-date docs. Always use this instead of assuming things about nx configuration
+- If the user needs help with an Nx configuration or project graph error, use the `nx_workspace` tool to get any errors
+
+<!-- nx configuration end-->

package/dist/templates/base/CLAUDE.md

@@ -0,0 +1,16 @@
+
+Strictly follow the rules in ./AGENTS.md
+
+<!-- nx configuration start-->
+<!-- Leave the start & end comments to automatically receive updates. -->
+
+# General Guidelines for working with Nx
+
+- When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through `nx` (i.e. `nx run`, `nx run-many`, `nx affected`) instead of using the underlying tooling directly
+- You have access to the Nx MCP server and its tools, use them to help the user
+- When answering questions about the repository, use the `nx_workspace` tool first to gain an understanding of the workspace architecture where applicable.
+- When working in individual projects, use the `nx_project_details` mcp tool to analyze and understand the specific project structure and dependencies
+- For questions around nx configuration, best practices or if you're unsure, use the `nx_docs` tool to get relevant, up-to-date docs. Always use this instead of assuming things about nx configuration
+- If the user needs help with an Nx configuration or project graph error, use the `nx_workspace` tool to get any errors
+
+<!-- nx configuration end-->

package/dist/templates/base/README.md

@@ -0,0 +1,83 @@
+# @{{ORGANIZATION_NAME}}/{{PROJECT_NAME_KEBAB}}
+
+## Overview
+
+Build modern, lightning-fast web applications for any platform using a single codebase. This toolkit utilizes [web components](https://www.webcomponents.org/introduction) to ensure premium quality and streamlined development.
+
+Stencil is a specialized compiler designed to generate standards-compliant Web Components (Custom Elements) compatible with any browser. By integrating premium features from modern frontend frameworks—including TypeScript, JSX, a virtual DOM, and reactive one-way data binding—into a compile-time engine, Stencil produces high-performance components. These components are framework-agnostic, allowing them to integrate seamlessly with any existing stack or operate as standalone elements.
+
+**Core Tech Stack:**
+
+- **Stencil**: The underlying Web Component compiler.
+- **TypeScript**: Ensures type safety and robust development.
+- **Nx**: Manages the build system and monorepo architecture.
+- **Sass**: Handles advanced, scalable CSS styling.
+- **Eslint & Stylelint**: Maintain code quality through static analysis for scripts and styles.
+- **Prettier**: Enforces consistent code formatting across the project.
+
+## Build / Setup
+
+Follow these steps to set up and run the project locally.
+
+### Prerequisites
+
+- **Volta:** The workspace uses [volta](https://volta.sh) to manage its npm and Node versions. [Install it](https://docs.volta.sh/guide/getting-started) before proceeding.
+  - There's no need to install a specific version of npm or Node right now, it shall be done automatically for you.
+- **IDE:** We recommend [VS Code](https://code.visualstudio.com/) with the [Stencil Tools](https://marketplace.visualstudio.com/items?itemName=ionic.stencil-helper) extension.
+
+### Installation & Running
+
+1. **Install dependencies:**
+
+    ```bash
+    npm install
+    ```
+
+2. **Build for production:**
+
+    ```bash
+    npx nx run-many -t build
+    ```
+
+3. **Run unit tests:**
+
+    ```bash
+    npx nx run-many -t test
+    ```
+
+## Folder Hierarchy
+
+The repository structure is organized as follows:
+
+```text
+├── .eslintignore/            # ESLint ignore rules
+├── .gitignore                # Git ignore rules
+├── .husky/                   # Git hooks configuration
+├── .mcp.json                 # MCP configuration
+├── .nvmrc                    # NVM configuration
+├── .prettierignore           # Prettier ignore rules
+├── .stylelintignore          # Stylelint ignore rules
+├── docs/                     # Documentation files
+│   ├── CONTRIBUTING.md       # Contributing guidelines
+│   ├── CODE_OF_CONDUCT.md    # Contributor Code of Conduct
+|   ├── LICENSE.md            # License file
+│   └── STYLE_GUIDE.md        # Stencil Style Guide
+├── packages/                 # Directory for npm workspaces
+│   └── [package-name]/       # Individual Stencil component library
+├── AGENTS.md                 # AI context and guidelines for Nx
+├── CLAUDE.md                 # AI context and guidelines for Nx
+├── commitlint.config.mjs     # Commitlint configuration
+├── eslint.config.mjs         # ESLint configuration
+├── nx.json                   # Nx build system configuration
+├── package-lock.json         # NPM lock file
+├── package.json              # Root configuration: workspaces, dependencies, and scripts
+├── prettier.config.mjs       # Prettier configuration
+├── stylelint.config.mjs      # Stylelint configuration
+├── tsconfig.base.json        # Base TypeScript configuration
+└── README.md                 # Project documentation
+```
+
+## Contributing
+
+Thanks for your interest in contributing!
+Please take a moment to read up on our guidelines for [contributing](/docs/CONTRIBUTING.md). Please note that this project is released with a [Contributor Code of Conduct](/docs/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.

package/dist/templates/base/commitlint.config.mjs

@@ -0,0 +1 @@
+export default { extends: ['@commitlint/config-conventional'] };

package/dist/templates/base/docs/CODE_OF_CONDUCT.md

@@ -0,0 +1,122 @@
+# Contributor Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include the ability to:
+
+* Demonstrate empathy and kindness towards people
+* Be respectful of differing opinions, viewpoints, and experiences
+* Give and gracefully accept constructive feedback
+* Accept responsibility and apologize to those affected by our mistakes,
+  and learn from the experience
+* Focus on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.0, available at [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html).
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+For answers to common questions about this code of conduct, see the [FAQ](https://www.contributor-covenant.org/faq). Translations are available [at](https://www.contributor-covenant.org/translations).

package/dist/templates/base/docs/CONTRIBUTING.md

@@ -0,0 +1,103 @@
+# Contributing
+
+First off, thank you for considering contributing! It is people like you who make this a great tool for the community.
+
+## 1. Development Environment
+
+### Prerequisites
+
+- **Volta:** The workspace uses [volta](https://volta.sh) to manage its npm and Node versions. [Install it](https://docs.volta.sh/guide/getting-started) before proceeding.
+  - There's no need to install a specific version of npm or Node right now, it shall be done automatically for you.
+- **IDE:** We recommend [VS Code](https://code.visualstudio.com/) with the [Stencil Tools](https://marketplace.visualstudio.com/items?itemName=ionic.stencil-helper) extension.
+
+### Setup
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/your-repo/project-name.git
+   cd project-name
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+3. Build:
+
+   ```bash
+   npx nx run-many -t build
+   ```
+
+   This will open a browser window with your component library's collection.
+
+## 2. Creating a New Component
+
+To maintain consistency, please use the Stencil CLI to generate new components:
+
+```bash
+npx nx run components-{{PROJECT_NAME_KEBAB}}-core:generate
+```
+
+*(Enter the component name in kebab-case, e.g., `my-new-button`)*
+
+Ensure your new component includes:
+
+- A `.tsx` file for logic and rendering.
+- A `.css` or `.scss` file for styling.
+- A `.spec.ts` file for unit tests.
+- A `.e2e.ts` file for end-to-end tests.
+
+## 3. Standards & Style
+
+Please review our [STYLE_GUIDE.md](./STYLE_GUIDE.md) before submitting code. Key highlights include:
+
+- **TypeScript:** Use strict typing; avoid `any`.
+- **Naming:** Components must be `kebab-case`.
+- **Documentation:** Use JSDoc comments on `@Prop`, `@State`, and `@Event`. Stencil uses these to auto-generate `readme.md` files. **Do not manually edit the `readme.md` files in component folders.**
+
+## 4. Testing Requirements
+
+We cannot accept pull requests without passing tests.
+
+- **Run Unit Tests:**
+
+  ```bash
+  npx nx run-many -t test
+  ```
+
+- **Run E2E Tests:**
+
+  ```bash
+   npx nx run-many -t test:e2e
+  ```
+
+- **Build Verification:**
+
+  ```bash
+   npx nx run-many -t build
+  ```
+
+Ensure that your component remains accessible (A11y). Use tools like Axe to verify that your web components meet WCAG standards.
+
+## 5. Pull Request Process
+
+1. **Branching:** Create a feature branch from `main` (e.g., `feat/add-datepicker` or `fix/button-alignment`).
+2. **Commits:** Follow [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat: added shadow-dom support`).
+3. **Draft PR:** If your work is in progress, open it as a "Draft".
+4. **Review:** At least one maintainer must review and approve your PR before it can be merged.
+5. **CI:** Ensure the Github Actions (or CI of choice) pass successfully.
+
+## 6. Code of Conduct
+
+By contributing, you agree to uphold our [Code of Conduct](./CODE_OF_CONDUCT.md). Please be respectful and professional in all interactions.
+
+## 7. Useful Scripts
+
+- `npx nx run-many -t build`: Production build of the components.
+- `npx nx run-many -t test`: Runs unit tests.
+
+---
+Questions? Feel free to open an issue or reach out to the maintainers!

package/dist/templates/base/docs/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/templates/base/docs/RELEASE.md

@@ -0,0 +1,95 @@
+# Release Process
+
+This project uses [Nx Release](https://nx.dev/features/manage-releases) to manage versioning, changelog generation, and publishing of our StencilJS components.
+
+## 1. Prerequisites
+
+Before initiating a release, ensure you have the following:
+
+- Permissions to push to the `main` branch.
+- A valid `NPM_TOKEN` if publishing to a registry.
+- Clean working directory (all changes committed).
+
+## 2. Standard Release Workflow (Dry Run)
+
+Always perform a dry run first to inspect what Nx will do without making permanent changes.
+
+```bash
+npx nx release --dry-run
+```
+
+This command will:
+
+1. **Version:** Determine the next version based on [Conventional Commits](https://www.conventionalcommits.org/).
+2. **Changelog:** Generate or update `CHANGELOG.md` files.
+3. **Plan:** Show the summary of changes without committing or tagging.
+
+## 3. Executing a Full Release
+
+If the dry run looks correct, execute the release. By default, this handles versioning, changelogs, and committing.
+
+```bash
+npx nx release
+```
+
+### What happens during execution:
+
+- **Versioning:** Updates `package.json` in individual component projects and the root.
+- **Changelog:** Updates the root and per-project `CHANGELOG.md` files.
+- **Git:** Commits the changes and creates a Git tag (e.g., `v1.2.3`).
+- **Build:** Nx automatically triggers the `build` target for all affected projects.
+- **Publish:** Uploads the built artifacts to the NPM registry.
+
+## 4. Specific Release Scenarios
+
+### Preview/Prerelease
+
+To create an alpha or beta release:
+
+```bash
+npx nx release --specifier next --preid alpha
+```
+
+### Versioning without Publishing
+
+If you want to version the code but manually handle the publish step later:
+
+```bash
+npx nx release version
+```
+
+### Publishing Only
+
+If the versions are already bumped and you just need to push to the registry:
+
+```bash
+npx nx release publish
+```
+
+## 5. Continuous Integration (CI)
+
+Our CI pipeline (GitHub Actions) is configured to handle releases automatically when code is merged into `main`. 
+
+1. **Validation:** CI runs `lint`, `test`, and `build`.
+2. **Release:** If validation passes, `nx release` is called.
+3. **Provenance:** We use `--first-release` or standard flags to ensure NPM provenance is recorded where supported.
+
+## 6. StencilJS Specifics
+
+When releasing Stencil components in an Nx monorepo:
+
+- **Distribution Folder:** Ensure the `dist` and `www` folders are correctly defined in each project's `project.json`.
+- **Peer Dependencies:** Nx Release correctly handles internal dependency updates. If `component-a` depends on `component-b`, it will ensure versions remain in sync according to your `nx.json` release configuration.
+
+## 7. Troubleshooting
+
+- **Version Mismatch:** If versions get out of sync, check the `release` configuration in `nx.json`. We typically use "fixed" versioning (all packages share one version).
+- **Build Failures:** Stencil builds may fail if TypeScript types are missing. Ensure `nx build` passes locally for all affected components before running the release.
+- **OTP:** If your NPM account requires 2FA, use:
+
+  ```bash
+  npx nx release --otp 123456
+  ```
+
+---
+*For details on configuring the release logic, see the `release` object in `nx.json`.*