create-stencil-components 1.0.0

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

@@ -0,0 +1,128 @@
+# Style Guide
+
+## 1. Component Architecture
+
+### Naming Conventions
+
+- **Tag Name:** The prefix has a major role when you are creating a collection of components intended to be used across different projects. Web Components are not scoped because they are globally declared within the webpage, which means an "unique" prefix is needed to prevent collisions. Must be lowercase and hyphenated (kebab-case). It must include at least one hyphen to comply with W3C Custom Element standards.
+  - *Good:* `my-data-table`, `ui-button`
+  - *Bad:* `myDataTable`, `uibutton`
+- **Class Name:** Use PascalCase for the TypeScript class name, matching the component tag without hyphens.
+  - *Example:* `<my-data-table>` becomes `class MyDataTable`.
+- **File Names:** Name files after the tag name.
+  - *Example:* `my-button.tsx`, `my-button.css`, `my-button.spec.ts`.
+
+### Directory Structure
+
+Each component should reside in its own folder within `src/components/`:
+
+```text
+src/components/my-component/
+│── test/
+│   ├── my-component.e2e.ts  (End-to-end tests
+│   └── my-component.spec.ts (Unit tests)
+├── my-component.scss
+├── my-component.tsx
+└── readme.md            (Auto-generated)
+```
+
+## 2. TypeScript Standards
+
+### Member Ordering
+
+Maintain a consistent order for class members to improve readability:
+
+1. **Properties:** `@Element()`, `@Prop()`, `@State()`
+2. **Internal Variables:** Private/Protected properties
+3. **Events:** `@Event()`
+4. **Watchers:** `@Watch()`
+5. **Lifecycle Hooks:** `connectedCallback`, `componentWillLoad`, etc.
+6. **Methods:** `@Listen()`, `@Method()`, then private helper methods
+7. **Render:** `render()`
+
+### Typing
+
+- **Strictness:** Always enable `strict: true` in `tsconfig.json`.
+- **Explicit Returns:** Define return types for all functions and `@Method()` calls.
+- **Interfaces:** Prefix interfaces with `I` (optional, based on preference) or place them in a shared `types.ts` file if used by multiple components.
+
+## 3. Stencil Decorator Usage
+
+### Props (@Prop)
+
+- Use **camelCase** for property names in TypeScript. Stencil automatically maps these to **kebab-case** attributes in HTML.
+- **Initialization:** Always provide a default value if a prop is not required.
+- **Immutability:** Set `mutable: true` only when the component needs to modify its own prop.
+
+### State (@State)
+
+- Use `@State()` for any internal data that should trigger a re-render.
+- For objects and arrays, use **immutable updates**:
+
+  ```typescript
+  // Good
+  this.items = [...this.items, 'new-item'];
+  // Bad
+  this.items.push('new-item');
+  ```
+
+### Events (@Event)
+
+- Use **camelCase** for event names (e.g., `todoCompleted`).
+- Provide specific types for the `EventEmitter` payload: `EventEmitter<ISearchResult>`.
+
+## 4. JSX & Rendering
+
+### The `<Host>` Element
+
+Always use the `<Host>` component as the top-level element in your `render()` function to manage attributes and classes on the custom element itself.
+
+```tsx
+render() {
+  return (
+    <Host class={{ 'is-active': this.isActive }}>
+      <slot />
+    </Host>
+  );
+}
+```
+
+### Conditional Rendering
+
+Use ternary operators or short-circuit evaluation for simple conditions. For complex logic, extract the JSX to a private method.
+
+```tsx
+render() {
+  return (
+    <div>
+      {this.isLoading ? <spinner-icon /> : <slot />}
+    </div>
+  );
+}
+```
+
+## 5. CSS & Styling
+
+### Shadow DOM
+
+- Use `shadow: true` by default.
+- Use **CSS Variables** for any values that need to be "themeable" from outside the component.
+- **Naming:** Follow BEM (Block Element Modifier) if not using scoped CSS, or simple descriptive classes if using Shadow DOM.
+
+### Selectors
+
+- Use `:host` to style the component container.
+- Use `:host-context(.dark-theme)` for theme-dependent styling.
+- Use `::slotted(selector)` to style elements passed into a slot.
+
+## 6. Performance
+
+- **Minimize @Watch:** Only use `@Watch` when you need to perform side effects (like fetching data) in response to a prop change. Avoid using it to sync state.
+- **Lazy Loading:** Keep component logic lean. If a library is large, consider dynamic imports inside `componentWillLoad`.
+- **Ref usage:** Avoid direct DOM manipulation. Use `ref={(el) => this.myElement = el}` only when absolutely necessary.
+
+## 7. Testing & Quality
+
+- **Unit Tests:** Test logic, formatting, and state changes in `.spec.ts`.
+- **E2E Tests:** Test DOM rendering and event firing in `.e2e.ts`.
+- **Comments:** Use JSDoc for all public `@Prop` and `@Method` members to ensure the generated `readme.md` is helpful for consumers.

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

@@ -0,0 +1,37 @@
+import eslint from '@eslint/js';
+import globals from "globals";
+import { defineConfig } from 'eslint/config';
+import tseslint from 'typescript-eslint';
+import sonarlint from 'eslint-plugin-sonarjs';
+import tsParser from '@typescript-eslint/parser';
+
+export default defineConfig({
+	extends: [
+		eslint.configs.recommended,
+		sonarlint.configs.recommended,
+		tseslint.configs.recommended,
+		tseslint.configs.strict,
+		tseslint.configs.stylistic
+	],
+	files: ['**/**.{ts,tsx}'],
+	languageOptions: {
+		ecmaVersion: 2022,
+		globals: {
+			...globals.browser,
+			...globals.jest
+		},
+    parser: tsParser
+	},
+	plugins: {
+		sonarlint: sonarlint
+	},
+	rules: {
+		"sonarjs/unused-import": "off",
+		"@typescript-eslint/no-unused-vars": [
+			"warn",
+			{
+				"varsIgnorePattern": "^(h|Fragment)$"
+			}
+		],
+	}
+});

package/dist/templates/base/gitignore

@@ -0,0 +1,32 @@
+dist/
+www/
+loader/
+generated/
+
+*~
+*.sw[mnpcod]
+*.log
+*.lock
+*.tmp
+*.tmp.*
+log.txt
+*.sublime-project
+*.sublime-workspace
+
+.stencil/
+.idea/
+.vscode/
+.sass-cache/
+.versions/
+node_modules/
+$RECYCLE.BIN/
+
+.DS_Store
+Thumbs.db
+UserInterfaceState.xcuserstate
+.env
+
+.nx/cache
+.nx/workspace-data
+.cursor/rules/nx-rules.mdc
+.github/instructions/nx.instructions.md

package/dist/templates/base/nx.json

@@ -0,0 +1,36 @@
+{
+  "extends": "./node_modules/nx/presets/npm.json",
+  "$schema": "./node_modules/nx/schemas/nx-schema.json",
+  "defaultBase": "master",
+  "release": {
+    "changelog": {
+      "projectChangelogs": {
+        "renderOptions": {
+          "authors": false,
+          "applyUsernameToAuthors": false,
+          "commitReferences": false,
+          "versionTitleDate": false
+        }
+      },
+      "workspaceChangelog": false
+    },
+    "git": {
+      "commit": false,
+      "tag": false
+    },
+    "groups": {
+      "components": {
+        "projects": ["packages/*"],
+        "projectsRelationship": "fixed"
+      }
+    },
+    "version": {
+      "conventionalCommits": false,
+      "preVersionCommand": "npx nx run-many -t clean,build",
+      "versionPrefix": ""
+    }
+  },
+  "tui": {
+    "enabled": true
+  }
+}

package/dist/templates/base/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@{{ORGANIZATION_NAME}}/{{PROJECT_NAME_KEBAB}}",
+  "version": "0.0.0",
+  "description": "Build modern, lightning-fast web applications for any platform using a single codebase",
+  "license": "{{LICENSE}}",
+  "keywords": [
+    "agnostic",
+    "stencil",
+    "stenciljs",
+    "web components"
+  ],
+  "scripts": {
+    "prepare": "node .husky/install.mjs"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "20.2.0",
+    "@commitlint/config-conventional": "20.2.0",
+    "@eslint/js": "9.39.2",
+    "@nx/js": "22.3.3",
+    "eslint": "9.39.2",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-prettier": "5.5.4",
+    "eslint-plugin-sonarjs": "3.0.5",
+    "husky": "9.1.7",
+    "nx": "22.3.3",
+    "rimraf": "6.1.2",
+    "stylelint": "16.26.1",
+    "stylelint-config-standard": "39.0.1",
+    "stylelint-config-standard-scss": "16.0.0",
+    "stylelint-use-logical": "2.1.2",
+    "ts-node": "10.9.2",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.50.1"
+  },
+  "nx": {},
+  "volta": {
+    "node": "25.2.1"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "dependencies": {}
+}

package/dist/templates/base/packages/components-{{PROJECT_NAME_KEBAB}}-core/README.md

@@ -0,0 +1,74 @@
+# @{{ORGANIZATION_NAME}}/components-{{PROJECT_NAME_KEBAB}}-core
+
+## Overview
+
+A framework-agnostic collection of  [web components](https://www.webcomponents.org/introduction) built for maximum compatibility. These components integrate seamlessly with popular libraries like React, Angular, and Vue, or can function entirely on their own using standard browser JavaScript.
+
+## Tasks
+
+The following is a list of available command line tasks:
+
+| Task          | Description                                     |
+| ------------- | ----------------------------------------------- |
+| clean         | Deletes build outputs of the package.           |
+| build         | Builds the package.                             |
+| format        | Validates the form of the package.              |
+| format:fix    | Performs a format fix of the package.           |
+| generate      | Creates a stencil component.                    |
+| lint          | Validates the code of the package.              |
+| lint:fix      | Performs a validation fix of the package.       |
+| server:dev    | Run a standalone stencil server of the code.    |
+| test          | Performs a test run of the package.             |
+| test:e2e      | Performs end-to-end test run of the package.    |
+| test:watch    | Performs a watch of the test run of the package |
+
+You can execute tasks within an [Nx](https://nx.dev) workspace using several methods. Here are the most common approaches:
+
+**From the `workspace` root:**
+
+Use the full project target path to run tasks:
+
+```sh
+npx nx run components-{{PROJECT_NAME_KEBAB}}-core:[task]
+npx nx run components-{{PROJECT_NAME_KEBAB}}-core:build
+```
+
+**From within the package directory:**
+
+Navigate to packages/components-{{PROJECT_NAME_KEBAB}}-core and run the task directly:
+
+```sh
+npx nx run [task]
+npx nx run build
+```
+
+## Output Targets
+
+- **dist**: Generate the component(s) as a reusable library that can be self-lazy loading.
+  - **cjs and esm**: Bundler ready javascript file for commonjs and modules.
+  - **collection**: Stencil files transpiled to simple javascript.  Those are the files used if
+  you import your library into another stencil distribution.
+  - **loader**: Bundler entry for lazy loaded builds (used for example to register all components
+  at once in the web component registry with defineCustomElements function).
+  - **output-target-stencils (app workspace name)**: Browser ready component.
+  - **types**: Typescript types with d.ts files.
+- **dist-custom-elements**: Custom elements that directly extend HTMLElement and provides simple utility functions for easily defining these elements on the Custom Element Registry.
+- **www**: Oriented for web apps and websites, hosted from an http server.
+
+## Folder Hierarchy
+
+The package structure is organized as follows:
+
+```text
+├── src/               # Source code
+│   ├── components/    # Stencil components
+│   │   └── [name]/    # Component files (*.tsx, *.css, *.spec.ts, *.e2e.ts)
+│   ├── index.html     # Dev server entry
+│   └── index.ts       # Library export entry point
+├── package.json       # Root configuration: workspaces, dependencies, and scripts
+├── project.json       # Project Nx build system configuration
+├── stencil.config.ts  # Stencil build configuration
+├── tsconfig.json      # TypeScript configuration
+├── CHANGELOG.md       # Changelog documentation
+└── README.md          # Package documentation
+```

package/dist/templates/base/packages/components-{{PROJECT_NAME_KEBAB}}-core/project.json

@@ -0,0 +1,144 @@
+{
+  "name": "components-{{PROJECT_NAME_KEBAB}}-core",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "namedInputs": {
+    "default": ["{projectRoot}/**/*"]
+  },
+  "targets": {
+    "clean": {
+      "cache": false,
+      "executor": "nx:run-script",
+      "inputs": [
+        {
+          "externalDependencies": ["rimraf"]
+        }
+      ],
+      "options": {
+        "script": "clean",
+        "cwd": "{projectRoot}"
+      }
+    },
+    "build": {
+      "cache": false,
+      "dependsOn": [
+        "^lint"
+      ],
+      "executor": "nx:run-script",
+      "inputs": [
+        "default",
+        {
+          "externalDependencies": ["@stencil/core"]
+        }
+      ],
+      "options": {
+        "script": "build",
+        "cwd": "{projectRoot}"
+      },
+      "outputs": ["{projectRoot}/dist"]
+    },
+    "format": {
+      "cache": false,
+      "executor": "nx:run-script",
+      "options": {
+        "script": "format",
+        "cwd": "{projectRoot}"
+      }
+    },
+    "format:fix": {
+      "cache": false,
+      "executor": "nx:run-script",
+      "options": {
+        "script": "format:fix",
+        "cwd": "{projectRoot}"
+      }
+    },
+    "generate": {
+      "cache": false,
+      "executor": "nx:run-script",
+      "inputs": [
+        "default",
+        {
+          "externalDependencies": ["@stencil/core"]
+        }
+      ],
+      "options": {
+        "script": "generate",
+        "cwd": "{projectRoot}"
+      }
+    },
+    "lint": {
+      "cache": false,
+      "executor": "nx:run-commands",
+      "options": {
+        "commands": ["npm run lint:eslint", "npm run lint:stylelint"],
+        "cwd": "{projectRoot}",
+        "parallel": true
+      }
+    },
+    "lint:fix": {
+      "cache": false,
+      "executor": "nx:run-commands",
+      "options": {
+        "commands": ["npm run lint:eslint:fix", "npm run lint:stylelint:fix"],
+        "cwd": "{projectRoot}",
+        "parallel": true
+      }
+    },
+    "server:dev": {
+      "cache": false,
+      "executor": "nx:run-script",
+      "inputs": [
+        "default",
+        {
+          "externalDependencies": ["@stencil/core"]
+        }
+      ],
+      "options": {
+        "script": "server:dev",
+        "cwd": "{projectRoot}"
+      }
+    },
+    "test": {
+      "cache": false,
+      "executor": "nx:run-script",
+      "inputs": [
+        "default",
+        {
+          "externalDependencies": ["@stencil/core"]
+        }
+      ],
+      "options": {
+        "script": "test",
+        "cwd": "{projectRoot}"
+      }
+    },
+    "test:e2e": {
+      "cache": false,
+      "executor": "nx:run-script",
+      "inputs": [
+        "default",
+        {
+          "externalDependencies": ["@stencil/core"]
+        }
+      ],
+      "options": {
+        "script": "test:e2e",
+        "cwd": "{projectRoot}"
+      }
+    },
+    "test:watch": {
+      "cache": false,
+      "executor": "nx:run-script",
+      "inputs": [
+        "default",
+        {
+          "externalDependencies": ["@stencil/core"]
+        }
+      ],
+      "options": {
+        "script": "test:watch",
+        "cwd": "{projectRoot}"
+      }
+    }
+  }
+}

package/dist/templates/base/packages/components-{{PROJECT_NAME_KEBAB}}-core/src/components/my-component/my-component.scss

@@ -0,0 +1,3 @@
+:host {
+  display: block;
+}

package/dist/templates/base/packages/components-{{PROJECT_NAME_KEBAB}}-core/src/components/my-component/my-component.tsx

@@ -0,0 +1,32 @@
+import { Component, ComponentInterface, Prop, h } from '@stencil/core';
+import { format } from '../../utils/utils';
+
+@Component({
+  tag: 'my-component',
+  styleUrl: 'my-component.scss',
+  shadow: true,
+})
+export class MyComponent implements ComponentInterface {
+  /**
+   * The first name
+   */
+  @Prop() first: string;
+
+  /**
+   * The middle name
+   */
+  @Prop() middle: string;
+
+  /**
+   * The last name
+   */
+  @Prop() last: string;
+
+  private getText(): string {
+    return format(this.first, this.middle, this.last);
+  }
+
+  render() {
+    return <div>Hello, World! I'm {this.getText()}</div>;
+  }
+}

package/dist/templates/base/packages/components-{{PROJECT_NAME_KEBAB}}-core/src/components/my-component/readme.md

@@ -0,0 +1,19 @@
+# my-component
+
+
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property | Attribute | Description     | Type     | Default     |
+| -------- | --------- | --------------- | -------- | ----------- |
+| `first`  | `first`   | The first name  | `string` | `undefined` |
+| `last`   | `last`    | The last name   | `string` | `undefined` |
+| `middle` | `middle`  | The middle name | `string` | `undefined` |
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/templates/base/packages/components-{{PROJECT_NAME_KEBAB}}-core/src/components/my-component/test/my-component.e2e.ts

@@ -0,0 +1,32 @@
+import { newE2EPage } from '@stencil/core/testing';
+
+describe('my-component', () => {
+  it('renders', async () => {
+    const page = await newE2EPage();
+
+    await page.setContent('<my-component></my-component>');
+    const element = await page.find('my-component');
+    expect(element).toHaveClass('hydrated');
+  });
+
+  it('renders changes to the name data', async () => {
+    const page = await newE2EPage();
+
+    await page.setContent('<my-component></my-component>');
+    const component = await page.find('my-component');
+    const element = await page.find('my-component >>> div');
+    expect(element.textContent).toEqual(`Hello, World! I'm `);
+
+    component.setProperty('first', 'James');
+    await page.waitForChanges();
+    expect(element.textContent).toEqual(`Hello, World! I'm James`);
+
+    component.setProperty('last', 'Quincy');
+    await page.waitForChanges();
+    expect(element.textContent).toEqual(`Hello, World! I'm James Quincy`);
+
+    component.setProperty('middle', 'Earl');
+    await page.waitForChanges();
+    expect(element.textContent).toEqual(`Hello, World! I'm James Earl Quincy`);
+  });
+});

package/dist/templates/base/packages/components-{{PROJECT_NAME_KEBAB}}-core/src/components/my-component/test/my-component.spec.ts

@@ -0,0 +1,36 @@
+import { newSpecPage } from '@stencil/core/testing';
+import { MyComponent } from '../my-component';
+
+describe('my-component', () => {
+  it('renders', async () => {
+    const { root } = await newSpecPage({
+      components: [MyComponent],
+      html: '<my-component></my-component>',
+    });
+    expect(root).toEqualHtml(`
+      <my-component>
+        <mock:shadow-root>
+          <div>
+            Hello, World! I'm
+          </div>
+        </mock:shadow-root>
+      </my-component>
+    `);
+  });
+
+  it('renders with values', async () => {
+    const { root } = await newSpecPage({
+      components: [MyComponent],
+      html: `<my-component first="Stencil" middle="'Don't call me a framework'" last="JS"></my-component>`,
+    });
+    expect(root).toEqualHtml(`
+      <my-component first="Stencil" middle="'Don't call me a framework'" last="JS">
+        <mock:shadow-root>
+          <div>
+            Hello, World! I'm Stencil 'Don't call me a framework' JS
+          </div>
+        </mock:shadow-root>
+      </my-component>
+    `);
+  });
+});

package/dist/templates/base/packages/components-{{PROJECT_NAME_KEBAB}}-core/src/components.d.ts

@@ -0,0 +1,61 @@
+/* eslint-disable */
+/* tslint:disable */
+/**
+ * This is an autogenerated file created by the Stencil compiler.
+ * It contains typing information for all components that exist in this project.
+ */
+import { HTMLStencilElement, JSXBase } from "@stencil/core/internal";
+export namespace Components {
+    interface MyComponent {
+        /**
+          * The first name
+         */
+        "first": string;
+        /**
+          * The last name
+         */
+        "last": string;
+        /**
+          * The middle name
+         */
+        "middle": string;
+    }
+}
+declare global {
+    interface HTMLMyComponentElement extends Components.MyComponent, HTMLStencilElement {
+    }
+    var HTMLMyComponentElement: {
+        prototype: HTMLMyComponentElement;
+        new (): HTMLMyComponentElement;
+    };
+    interface HTMLElementTagNameMap {
+        "my-component": HTMLMyComponentElement;
+    }
+}
+declare namespace LocalJSX {
+    interface MyComponent {
+        /**
+          * The first name
+         */
+        "first"?: string;
+        /**
+          * The last name
+         */
+        "last"?: string;
+        /**
+          * The middle name
+         */
+        "middle"?: string;
+    }
+    interface IntrinsicElements {
+        "my-component": MyComponent;
+    }
+}
+export { LocalJSX as JSX };
+declare module "@stencil/core" {
+    export namespace JSX {
+        interface IntrinsicElements {
+            "my-component": LocalJSX.MyComponent & JSXBase.HTMLAttributes<HTMLMyComponentElement>;
+        }
+    }
+}