@stencil/templates 5.0.0-alpha.9 → 5.0.0-beta.1

package/README.md

@@ -0,0 +1,149 @@
+# @stencil/templates
+
+Boilerplate generators and project templates for Stencil — used internally by `stencil generate` and `stencil init`.
+
+## Install
+
+```bash
+npm install --save-dev @stencil/templates
+```
+
+## API
+
+### `getComponentBoilerplate(tagName, styleExtension?)` — component TSX
+
+Generates the `.tsx` file content for a new Stencil component:
+
+```ts
+import { getComponentBoilerplate } from '@stencil/templates';
+
+// With a stylesheet
+const tsx = getComponentBoilerplate('my-button', 'css');
+
+// Without (no styleUrl in @Component decorator)
+const bare = getComponentBoilerplate('my-button');
+```
+
+`styleExtension` accepts `'css'`, `'scss'`, `'sass'`, or `'less'`.
+
+Output for `getComponentBoilerplate('my-button', 'css')`:
+
+```tsx
+import { Component, Host } from '@stencil/core';
+
+@Component({
+  tag: 'my-button',
+  styleUrl: 'my-button.css',
+  encapsulation: { type: 'shadow' },
+})
+export class MyButton {
+  render() {
+    return (
+      <Host>
+        <slot></slot>
+      </Host>
+    );
+  }
+}
+```
+
+---
+
+### `getStyleBoilerplate(ext)` — stylesheet
+
+Generates the initial stylesheet content. Pass the file extension — not the tag name:
+
+```ts
+import { getStyleBoilerplate } from '@stencil/templates';
+
+const css  = getStyleBoilerplate('css');   // :host {\n  display: block;\n}
+const scss = getStyleBoilerplate('scss');  // same, brace syntax
+const sass = getStyleBoilerplate('sass'); // :host\n  display: block  (indented syntax)
+```
+
+---
+
+### `toPascalCase(str)` — tag name to class name
+
+Converts a dash-case tag name to a PascalCase class name:
+
+```ts
+import { toPascalCase } from '@stencil/templates';
+
+toPascalCase('my-button');       // 'MyButton'
+toPascalCase('ui-card-header');  // 'UiCardHeader'
+```
+
+---
+
+### `generateStencilConfig(selections)` — `stencil.config.ts` source
+
+Generates the content for a `stencil.config.ts` file based on wizard selections. Returns `null` when the default zero-config covers everything (loader-bundle only, no signals, no docs):
+
+```ts
+import { generateStencilConfig } from '@stencil/templates';
+import type { ConfigSelections } from '@stencil/templates';
+
+const sel: ConfigSelections = {
+  namespace: 'MyLib',
+  outputs: ['loader', 'standalone'],
+  signals: false,
+  docs: ['cem'],
+};
+
+const src = generateStencilConfig(sel);
+// null if only loader + no signals + no docs (zero-config case)
+// otherwise: TypeScript source string ready to write to stencil.config.ts
+```
+
+**`ConfigSelections` shape:**
+
+| Field | Type | Description |
+|---|---|---|
+| `namespace` | `string` | Component library namespace (e.g. `'MyLib'`) |
+| `outputs` | `OutputKey[]` | Output targets to enable |
+| `signals` | `boolean` | Enable `signalBacking: true` |
+| `docs` | `DocKey[]` | Documentation targets to include |
+
+**`OutputKey` values:** `'loader'` \| `'standalone'` \| `'ssr'` \| `'ssr-wasm'` \| `'www'`
+
+**`DocKey` values:** `'cem'` \| `'json'` \| `'vscode'`
+
+---
+
+### `generatePackageJsonFields(outputs)` — `package.json` distributable fields
+
+Returns the `module`, `types`, and `type` fields to merge into `package.json` for a given set of output targets. Returns an empty object for `'www'`-only (non-publishable app mode):
+
+```ts
+import { generatePackageJsonFields } from '@stencil/templates';
+
+generatePackageJsonFields([]);             // loader-bundle (default)
+// { type: 'module', module: './dist/loader-bundle/index.js', types: './dist/types/loader.d.ts' }
+
+generatePackageJsonFields(['standalone']);
+// { type: 'module', module: './dist/standalone/index.js', types: './dist/types/standalone.d.ts' }
+
+generatePackageJsonFields(['www']);
+// {}  — www is an app, not a publishable package
+```
+
+Priority when multiple outputs are selected: `loader` > `standalone` > `ssr` > `ssr-wasm`.
+
+---
+
+### `getTemplatePath(templateId)` — project template directory
+
+Returns the absolute path to a project template directory, ready to copy into a new project:
+
+```ts
+import { getTemplatePath, PROJECT_TEMPLATES } from '@stencil/templates';
+
+// Currently: ['component-starter']
+console.log(PROJECT_TEMPLATES);
+
+const dir = getTemplatePath('component-starter');
+// → /absolute/path/to/@stencil/templates/templates/project/component-starter
+```
+
+The `component-starter` template includes a `stencil.config.ts`, `tsconfig.json`, `package.json`, `.gitignore`, a sample component, and a utility file.

package/dist/index.d.mts

@@ -43,7 +43,7 @@ declare function getTemplatePath(templateId: ProjectTemplateId): string;
 //#endregion
 //#region src/project/config.d.ts
 type OutputKey = 'loader' | 'standalone' | 'ssr' | 'ssr-wasm' | 'www';
-type DocKey = 'cem' | 'json' | 'vscode';
+type DocKey = 'cem' | 'json' | 'skill' | 'vscode';
 interface PackageJsonFields {
   type?: 'module';
   module?: string;
@@ -72,4 +72,42 @@ declare function generateStencilConfig(sel: ConfigSelections): string | null;
  */
 declare function generatePackageJsonFields(outputs: ReadonlyArray<OutputKey>): PackageJsonFields;
 //#endregion
-export { type ConfigSelections, type DocKey, type OutputKey, PROJECT_TEMPLATES, type PackageJsonFields, type ProjectTemplateId, type StyleExtension, generatePackageJsonFields, generateStencilConfig, getComponentBoilerplate, getStyleBoilerplate, getTemplatePath, toPascalCase };
+//#region src/project/index-html.d.ts
+interface IndexHtmlSelections {
+  projectName: string;
+  namespace: string;
+  globalStyle: boolean;
+}
+/**
+ * Returns src/index.html source for a `www`-output project: entry <script> tag pointing
+ * at the compiled bundle, and a <link> to the global stylesheet if one was selected.
+ *
+ * @param sel - Wizard selections to encode into the HTML file.
+ * @returns HTML source string.
+ */
+declare function generateIndexHtml(sel: IndexHtmlSelections): string;
+//#endregion
+//#region src/generate/preview.d.ts
+/**
+ * Returns the `usage/example.md` boilerplate for `stencil generate`. Read by the docs
+ * pipeline (readme / docs-json / custom-elements-manifest demos) and by the dev server's
+ * live component preview.
+ *
+ * @param tagName - Dash-case custom element tag name.
+ * @returns Markdown source string.
+ */
+declare function getUsageExampleBoilerplate(tagName: string): string;
+/**
+ * Returns a standalone index.html boilerplate for `stencil generate`, scoped to a single
+ * component's own directory. Its presence opts that directory out of the dev server's
+ * auto-generated preview, trading it for a hand-authored demo page.
+ *
+ * @param tagName - Dash-case custom element tag name.
+ * @param entryScriptSrc - Resolved src for the project's browser entry bundle (see
+ * `resolveEntryScriptSrc` in the CLI package), or `null` if the project has no browser-loadable
+ * output target (e.g. an SSR-only project) - the script tag is omitted in that case.
+ * @returns HTML source string.
+ */
+declare function getPreviewHtmlBoilerplate(tagName: string, entryScriptSrc: string | null): string;
+//#endregion
+export { type ConfigSelections, type DocKey, type IndexHtmlSelections, type OutputKey, PROJECT_TEMPLATES, type PackageJsonFields, type ProjectTemplateId, type StyleExtension, generateIndexHtml, generatePackageJsonFields, generateStencilConfig, getComponentBoilerplate, getPreviewHtmlBoilerplate, getStyleBoilerplate, getTemplatePath, getUsageExampleBoilerplate, toPascalCase };

package/dist/index.mjs

@@ -83,6 +83,7 @@ function generateStencilConfig(sel) {
 	if (sel.outputs.includes("www")) outputLines.push(`    { type: 'www' },`);
 	if (sel.docs.includes("cem")) outputLines.push(`    { type: 'docs-custom-elements-manifest', file: 'custom-elements.json' },`);
 	if (sel.docs.includes("json")) outputLines.push(`    { type: 'docs-json', file: 'docs/api.json' },`);
+	if (sel.docs.includes("skill")) outputLines.push(`    { type: 'docs-agent-skill' },`);
 	if (sel.docs.includes("vscode")) outputLines.push(`    { type: 'docs-vscode', file: 'vscode-data.json' },`);
 	const parts = [
 		`import type { Config } from '@stencil/core';`,
@@ -133,4 +134,78 @@ function generatePackageJsonFields(outputs) {
 	return {};
 }
 //#endregion
-export { PROJECT_TEMPLATES, generatePackageJsonFields, generateStencilConfig, getComponentBoilerplate, getStyleBoilerplate, getTemplatePath, toPascalCase };
+//#region src/project/index-html.ts
+/**
+* Returns src/index.html source for a `www`-output project: entry <script> tag pointing
+* at the compiled bundle, and a <link> to the global stylesheet if one was selected.
+*
+* @param sel - Wizard selections to encode into the HTML file.
+* @returns HTML source string.
+*/
+function generateIndexHtml(sel) {
+	const fsNamespace = sel.namespace.toLowerCase();
+	const headLines = [
+		`    <meta charset="UTF-8" />`,
+		`    <title>${sel.projectName}</title>`,
+		`    <meta name="viewport" content="width=device-width, initial-scale=1" />`
+	];
+	if (sel.globalStyle) headLines.push(`    <link rel="stylesheet" href="/build/${fsNamespace}.css" />`);
+	headLines.push(`    <script type="module" src="/build/${fsNamespace}.js"><\/script>`);
+	return [
+		`<!doctype html>`,
+		`<html lang="en">`,
+		`  <head>`,
+		...headLines,
+		`  </head>`,
+		`  <body>`,
+		`    <my-component first="Stencil" last="'Don't call me a framework' JS"></my-component>`,
+		`  </body>`,
+		`</html>`,
+		``
+	].join("\n");
+}
+//#endregion
+//#region src/generate/preview.ts
+/**
+* Returns the `usage/example.md` boilerplate for `stencil generate`. Read by the docs
+* pipeline (readme / docs-json / custom-elements-manifest demos) and by the dev server's
+* live component preview.
+*
+* @param tagName - Dash-case custom element tag name.
+* @returns Markdown source string.
+*/
+function getUsageExampleBoilerplate(tagName) {
+	return `# Example
+
+\`\`\`html
+<${tagName}></${tagName}>
+\`\`\`
+`;
+}
+/**
+* Returns a standalone index.html boilerplate for `stencil generate`, scoped to a single
+* component's own directory. Its presence opts that directory out of the dev server's
+* auto-generated preview, trading it for a hand-authored demo page.
+*
+* @param tagName - Dash-case custom element tag name.
+* @param entryScriptSrc - Resolved src for the project's browser entry bundle (see
+* `resolveEntryScriptSrc` in the CLI package), or `null` if the project has no browser-loadable
+* output target (e.g. an SSR-only project) - the script tag is omitted in that case.
+* @returns HTML source string.
+*/
+function getPreviewHtmlBoilerplate(tagName, entryScriptSrc) {
+	return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>${tagName}</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+${entryScriptSrc ? `    <script type="module" src="${entryScriptSrc}"><\/script>\n` : `    <!-- no browser-loadable output target configured - add your own entry script -->\n`}  </head>
+  <body>
+    <${tagName}></${tagName}>
+  </body>
+</html>
+`;
+}
+//#endregion
+export { PROJECT_TEMPLATES, generateIndexHtml, generatePackageJsonFields, generateStencilConfig, getComponentBoilerplate, getPreviewHtmlBoilerplate, getStyleBoilerplate, getTemplatePath, getUsageExampleBoilerplate, toPascalCase };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stencil/templates",
-  "version": "5.0.0-alpha.9",
+  "version": "5.0.0-beta.1",
   "description": "Project and generate templates for Stencil",
   "keywords": [
     "scaffolding",
@@ -28,9 +28,12 @@
     }
   },
   "devDependencies": {
-    "tsdown": ">=0.21.0 <1.0.0",
-    "typescript": ">4.0.0 <7.0.0",
-    "vitest": "^4.1.7"
+    "tsdown": "^0.22.14",
+    "typescript": ">5.0.0 <7.0.0",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "@stencil/core": "^5.0.0 || 5.0.0-beta.1"
   },
   "volta": {
     "extends": "../../package.json"

package/templates/project/component-starter/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.stencil/
+www/

package/templates/project/component-starter/package.json

@@ -11,7 +11,7 @@
     "dev": "stencil build --dev --watch --serve",
     "generate": "stencil generate"
   },
-  "devDependencies": {
+  "dependencies": {
     "@stencil/core": "{{STENCIL_VERSION}}"
   },
   "collection": "./dist/collection/collection-manifest.json"

package/templates/project/component-starter/src/components/my-component/usage/example.md

@@ -0,0 +1,5 @@
+# Example
+
+```html
+<my-component first="Stencil" last="'Don't call me a framework' JS"></my-component>
+```

package/templates/project/component-starter/tsconfig.json

@@ -2,6 +2,7 @@
   "compilerOptions": {
     "strictPropertyInitialization": false,
     "experimentalDecorators": true,
+    "skipLibCheck": true,
     "target": "ES2022",
     "module": "ESNext",
     "moduleResolution": "bundler",