create-template-project 1.5.24 → 1.6.0

package/dist/templates/base/files/README.md

@@ -4,7 +4,7 @@
 
 [![npm version](https://img.shields.io/npm/v/{{projectName}}.svg)](https://www.npmjs.com/package/{{projectName}})
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js CI](https://github.com/{{githubUsername}}/{{projectName}}/actions/workflows/node.js.yml/badge.svg)](https://github.com/{{githubUsername}}/{{projectName}}/actions/workflows/node.js.yml)
+[![CI](https://github.com/{{githubUsername}}/{{projectName}}/actions/workflows/ci.yml/badge.svg)](https://github.com/{{githubUsername}}/{{projectName}}/actions/workflows/ci.yml)
 [![Coverage Status](https://coveralls.io/repos/github/{{githubUsername}}/{{projectName}}/badge.svg?branch=main)](https://coveralls.io/github/{{githubUsername}}/{{projectName}}?branch=main)
 
 ## Development Workflow

package/dist/templates/base/files/_oxc.config.ts

@@ -20,32 +20,14 @@ import {configs as regexpConfigs} from 'eslint-plugin-regexp';
 /** Filter out core ESLint rules bundled into eslint-plugin-regexp recommended config */
 const regexpPluginRules = Object.fromEntries(Object.entries(regexpConfigs.recommended.rules).filter(([key]) => key.startsWith('regexp/')));
 
-const commonIgnore = [
-	'**/.*',
-	'node_modules/**',
-	'dist/**',
-	'build/**',
-	'coverage/**',
-	'temp/**',
-	'public/**',
-	'**/*.md',
-];
+const commonIgnore = ['**/.*', 'node_modules/**', 'dist/**', 'build/**', 'coverage/**', 'temp/**', 'public/**', '**/*.md'];
 
 export const linter = defineConfig({
 	options: {
 		typeAware: true,
 		typeCheck: true,
 	},
-	plugins: [
-		'unicorn',
-		'typescript',
-		'oxc',
-		'import',
-		'react',
-		'jsdoc',
-		'promise',
-		'vitest',
-	],
+	plugins: ['unicorn', 'typescript', 'oxc', 'import', 'react', 'jsdoc', 'promise', 'vitest'],
 	jsPlugins: ['eslint-plugin-regexp'],
 	categories: {
 		correctness: 'error',
@@ -100,7 +82,7 @@ export const linter = defineConfig({
 		'import/no-named-export': 'off',
 		'import/no-namespace': 'off', // TODO: consider enabling
 		'import/no-nodejs-modules': 'off',
-		'import/no-unassigned-import': ['error', {'allow': ['**/*.css']}],
+		'import/no-unassigned-import': ['error', {allow: ['**/*.css']}],
 		'import/prefer-default-export': 'off',
 		'import/no-default-export': 'off',
 		'jest/consistent-test-it': 'off',
@@ -169,7 +151,7 @@ export const linter = defineConfig({
 		'oxc/no-rest-spread-properties': 'off',
 		'unicorn/escape-case': 'off',
 		'unicorn/filename-case': 'off', // TODO: consider enabling
-		'unicorn/max-nested-calls': ['warn', {'max': 5}],
+		'unicorn/max-nested-calls': ['warn', {max: 5}],
 		'unicorn/no-array-reduce': 'off', // TODO: consider enabling
 		'unicorn/no-array-sort': 'off', // TODO: consider enabling
 		'unicorn/no-hex-escape': 'off',
@@ -231,19 +213,19 @@ export const linter = defineConfig({
 			linkComponents: [],
 			version: undefined,
 		},
-	jsdoc: {
-		ignorePrivate: false,
-		ignoreInternal: false,
-		ignoreReplacesDocs: true,
-		overrideReplacesDocs: true,
-		augmentsExtendsReplacesDocs: false,
-		implementsReplacesDocs: false,
-		exemptDestructuredRootsFromChecks: false,
-		tagNamePreference: {},
-	},
-	vitest: {
-		typecheck: false,
-	},
+		jsdoc: {
+			ignorePrivate: false,
+			ignoreInternal: false,
+			ignoreReplacesDocs: true,
+			overrideReplacesDocs: true,
+			augmentsExtendsReplacesDocs: false,
+			implementsReplacesDocs: false,
+			exemptDestructuredRootsFromChecks: false,
+			tagNamePreference: {},
+		},
+		vitest: {
+			typecheck: false,
+		},
 	},
 	env: {
 		builtin: true,

package/dist/templates/web-widget/files/.github/workflows/pages.yml

@@ -0,0 +1,36 @@
+name: GitHub Pages
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v7
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: 22.x
+          cache: "{{packageManager}}"
+      - name: Install dependencies
+        run: "{{installCommand}}"
+      - name: Build demo
+        run: "{{packageManager}} run build -- --base=/{{projectName}}/"
+      - name: Build API docs
+        run: "{{packageManager}} run docs:api"
+      - name: Stage API docs
+        run: mkdir -p dist-demo/docs && mv docs/api dist-demo/docs/api
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: dist-demo
+      - id: deployment
+        uses: actions/deploy-pages@v4

package/dist/templates/web-widget/files/index.html

@@ -0,0 +1,21 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>{{projectName}}</title>
+		<link rel="stylesheet" href="/src/styles/index.css" />
+		<link rel="stylesheet" href="/src/demo/demo-shell.css" />
+	</head>
+	<body>
+		<main class="demo-shell">
+			<section class="demo-hero" aria-labelledby="demo-title">
+				<p class="demo-eyebrow">Native TypeScript widget</p>
+				<h1 id="demo-title">{{projectName}}</h1>
+				<p class="demo-copy">A dependency-free widget package with a Vite demo, API docs, and npm-ready builds.</p>
+				<div id="widget-host" class="demo-card"></div>
+			</section>
+		</main>
+		<script type="module" src="/src/demo/app.ts"></script>
+	</body>
+</html>

package/dist/templates/web-widget/files/package.json

@@ -0,0 +1,53 @@
+{
+	"private": false,
+	"files": ["dist", "CHANGELOG.md"],
+	"main": "./dist/index.mjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.mts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.mts",
+			"import": "./dist/index.mjs",
+			"default": "./dist/index.mjs"
+		},
+		"./react": {
+			"types": "./dist/react.d.mts",
+			"import": "./dist/react.mjs",
+			"default": "./dist/react.mjs"
+		},
+		"./styles.css": "./dist/styles/index.css"
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"lint": "oxlint",
+		"lint:css": "stylelint 'src/{demo,styles}/**/*.css'",
+		"lint:css:fix": "stylelint --fix 'src/{demo,styles}/**/*.css'",
+		"format": "oxfmt --write && stylelint --fix 'src/{demo,styles}/**/*.css'",
+		"format:check": "oxfmt --check",
+		"ci": "{{packageManager}} run typecheck && {{packageManager}} run lint && {{packageManager}} run lint:css && {{packageManager}} run format:check && {{packageManager}} run build:lib && {{packageManager}} run build && {{packageManager}} run docs:api && {{packageManager}} run test",
+		"build:lib": "tsdown",
+		"build:demo": "vite build",
+		"docs:api": "typedoc",
+		"screenshot": "node scripts/screenshot.mjs"
+	},
+	"devDependencies": {
+		"vite": "",
+		"vitest": "",
+		"@vitest/browser": "",
+		"@vitest/browser-playwright": "",
+		"playwright": "",
+		"@playwright/test": "",
+		"tsdown": "",
+		"typedoc": "",
+		"stylelint": "",
+		"stylelint-config-standard": "",
+		"typescript": "6.0.3",
+		"react": "",
+		"react-dom": "",
+		"@types/react": "",
+		"@types/react-dom": ""
+	},
+	"peerDependencies": {
+		"react": ">=18.0.0"
+	}
+}

package/dist/templates/web-widget/files/playwright.config.ts

@@ -0,0 +1,29 @@
+import {defineConfig, devices} from '@playwright/test';
+import {env} from 'node:process';
+
+const isCi = env.CI !== undefined;
+
+export default defineConfig({
+	testDir: './tests/e2e',
+	testMatch: '**/*.e2e-test.ts',
+	fullyParallel: true,
+	forbidOnly: isCi,
+	retries: isCi ? 2 : 0,
+	workers: isCi ? 1 : undefined,
+	reporter: 'html',
+	use: {
+		baseURL: 'http://localhost:4173',
+		trace: 'on-first-retry',
+	},
+	projects: [
+		{
+			name: 'chromium',
+			use: {...devices['Desktop Chrome']},
+		},
+	],
+	webServer: {
+		command: '{{packageManager}} run build && {{packageManager}} run start',
+		url: 'http://localhost:4173',
+		reuseExistingServer: !isCi,
+	},
+});

package/dist/templates/web-widget/files/scripts/screenshot.mjs

@@ -0,0 +1,35 @@
+import {mkdir} from 'node:fs/promises';
+import path from 'node:path';
+import {cwd} from 'node:process';
+
+import {chromium} from 'playwright';
+import {createServer} from 'vite';
+
+const PORT = 4199;
+
+try {
+	const server = await createServer({
+		root: cwd(),
+		server: {port: PORT, strictPort: true},
+	});
+	await server.listen();
+
+	try {
+		const browser = await chromium.launch();
+		const page = await browser.newPage({viewport: {width: 1280, height: 800}});
+
+		await page.goto(`http://localhost:${PORT}`);
+		await page.waitForSelector('.widget');
+		const outputPath = path.resolve(cwd(), 'docs/images/widget-demo.png');
+		await mkdir(path.dirname(outputPath), {recursive: true});
+		await page.locator('.demo-hero').screenshot({path: outputPath, type: 'png'});
+
+		console.log(`Screenshot saved to ${outputPath}`);
+		await browser.close();
+	} finally {
+		await server.close();
+	}
+} catch (error) {
+	console.error(String(error));
+	throw error;
+}

package/dist/templates/web-widget/files/src/demo/app.ts

@@ -0,0 +1,22 @@
+import {createWidget} from '{{projectName}}';
+
+const init = (): void => {
+	const host = document.querySelector<HTMLElement>('#widget-host');
+	if (host === null) {
+		throw new Error('Missing #widget-host element');
+	}
+
+	createWidget(host, {
+		title: '{{projectName}}',
+		message: 'Built with TypeScript, tsdown, Vite, TypeDoc, and Playwright.',
+		onAction: (count) => {
+			console.info(`Widget action ${count}`);
+		},
+	});
+};
+
+if (document.readyState === 'loading') {
+	document.addEventListener('DOMContentLoaded', init);
+} else {
+	init();
+}

package/dist/templates/web-widget/files/src/demo/demo-shell.css

@@ -0,0 +1,50 @@
+body {
+	min-width: 320px;
+	min-height: 100vh;
+	margin: 0;
+	font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+	color: #0f172a;
+	background: #f8fafc;
+}
+
+.demo-shell {
+	display: grid;
+	min-height: 100vh;
+	place-items: center;
+	padding: 2rem;
+}
+
+.demo-hero {
+	display: grid;
+	gap: 1rem;
+	width: min(100%, 52rem);
+}
+
+.demo-eyebrow {
+	margin: 0;
+	font-size: 0.8rem;
+	font-weight: 800;
+	letter-spacing: 0.12em;
+	color: #7c3aed;
+	text-transform: uppercase;
+}
+
+.demo-hero h1 {
+	max-width: 11ch;
+	margin: 0;
+	font-size: clamp(3rem, 12vw, 6.5rem);
+	line-height: 0.9;
+	letter-spacing: -0.08em;
+}
+
+.demo-copy {
+	max-width: 42rem;
+	margin: 0;
+	font-size: 1.1rem;
+	line-height: 1.6;
+	color: #475569;
+}
+
+.demo-card {
+	margin-top: 1.5rem;
+}

package/dist/templates/web-widget/files/src/lib/index.ts

@@ -0,0 +1,2 @@
+export {createWidget, DemoWidget} from './widget.ts';
+export type {DemoWidgetInstance, DemoWidgetOptions} from './widget.ts';

package/dist/templates/web-widget/files/src/lib/react.tsx

@@ -0,0 +1,54 @@
+import {forwardRef, useEffect, useRef, type ForwardedRef, type ReactElement} from 'react';
+
+import {DemoWidget as NativeDemoWidget, type DemoWidgetInstance, type DemoWidgetOptions} from './widget.ts';
+
+export type DemoWidgetReactProps = DemoWidgetOptions & {
+	readonly message?: string;
+};
+
+const setForwardedRef = (ref: ForwardedRef<DemoWidgetInstance>, value: DemoWidgetInstance | null): void => {
+	if (typeof ref === 'function') {
+		ref(value);
+		return;
+	}
+	if (ref !== null) {
+		ref.current = value;
+	}
+};
+
+export const DemoWidget = forwardRef<DemoWidgetInstance, DemoWidgetReactProps>((props, ref): ReactElement => {
+	const {message, ...mountOptions} = props;
+	const hostRef = useRef<HTMLDivElement | null>(null);
+	const instanceRef = useRef<DemoWidgetInstance | null>(null);
+
+	useEffect(() => {
+		const host = hostRef.current;
+		if (host === null) {
+			return (): void => {
+				setForwardedRef(ref, null);
+			};
+		}
+
+		const instance = new NativeDemoWidget(host, {...mountOptions, ...(message === undefined ? {} : {message})});
+		instanceRef.current = instance;
+		setForwardedRef(ref, instance);
+
+		return (): void => {
+			instanceRef.current = null;
+			setForwardedRef(ref, null);
+			instance.destroy();
+		};
+		// Mount-only options are intentionally captured once. Mutable props are synced below through native setters.
+		// oxlint-disable-next-line react-hooks/exhaustive-deps
+	}, []);
+
+	useEffect(() => {
+		if (message !== undefined) {
+			instanceRef.current?.setMessage(message);
+		}
+	}, [message]);
+
+	return <div ref={hostRef} />;
+});
+
+DemoWidget.displayName = 'DemoWidget';

package/dist/templates/web-widget/files/src/lib/test-setup.ts

@@ -0,0 +1,7 @@
+declare global {
+	var IS_REACT_ACT_ENVIRONMENT: boolean;
+}
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+export const reactActEnvironmentConfigured = true;

package/dist/templates/web-widget/files/src/lib/widget.test.ts

@@ -0,0 +1,33 @@
+import {describe, expect, it} from 'vitest';
+import {createWidget} from './widget.ts';
+
+describe('DemoWidget', () => {
+	it('renders and handles actions', async () => {
+		const host = document.createElement('div');
+		const actions: number[] = [];
+		const widget = createWidget(host, {
+			title: 'Test Widget',
+			onAction: (count) => {
+				actions.push(count);
+			},
+		});
+
+		expect(host.querySelector('.widget__title')?.textContent).toBe('Test Widget');
+		await widget.increment();
+
+		expect(host.querySelector('.widget__message')?.textContent).toBe('Clicked 1 time.');
+		expect(actions).toStrictEqual([1]);
+	});
+
+	it('throws after destroy', () => {
+		const host = document.createElement('div');
+		const widget = createWidget(host);
+
+		widget.destroy();
+
+		expect(() => {
+			widget.setMessage('late update');
+		}).toThrow('Widget has been destroyed.');
+		expect(host.children).toHaveLength(0);
+	});
+});

package/dist/templates/web-widget/files/src/lib/widget.ts

@@ -0,0 +1,83 @@
+export type DemoWidgetOptions = {
+	readonly title?: string;
+	readonly message?: string;
+	readonly actionLabel?: string;
+	readonly onAction?: (count: number) => void | Promise<void>;
+};
+
+export type DemoWidgetInstance = {
+	readonly increment: () => Promise<void>;
+	readonly setMessage: (message: string) => void;
+	readonly destroy: () => void;
+};
+
+const DEFAULT_TITLE = 'Native Widget';
+const DEFAULT_MESSAGE = 'Ready to publish on npm.';
+const DEFAULT_ACTION_LABEL = 'Increment';
+
+export class DemoWidget implements DemoWidgetInstance {
+	readonly #host: HTMLElement;
+	readonly #root: HTMLDivElement;
+	readonly #message: HTMLParagraphElement;
+	readonly #button: HTMLButtonElement;
+	readonly #onAction: ((count: number) => void | Promise<void>) | undefined;
+	#count = 0;
+	#destroyed = false;
+
+	public constructor(host: HTMLElement, options: DemoWidgetOptions = {}) {
+		this.#host = host;
+		this.#onAction = options.onAction;
+		this.#root = document.createElement('div');
+		this.#root.className = 'widget';
+
+		const title = document.createElement('h2');
+		title.className = 'widget__title';
+		title.textContent = options.title ?? DEFAULT_TITLE;
+
+		this.#message = document.createElement('p');
+		this.#message.className = 'widget__message';
+		this.#message.textContent = options.message ?? DEFAULT_MESSAGE;
+
+		this.#button = document.createElement('button');
+		this.#button.className = 'widget__button';
+		this.#button.type = 'button';
+		this.#button.textContent = options.actionLabel ?? DEFAULT_ACTION_LABEL;
+		this.#button.addEventListener('click', this.#handleClick);
+
+		this.#root.append(title, this.#message, this.#button);
+		this.#host.append(this.#root);
+	}
+
+	public readonly increment = async (): Promise<void> => {
+		this.#assertActive();
+		this.#count += 1;
+		this.#message.textContent = `Clicked ${this.#count} time${this.#count === 1 ? '' : 's'}.`;
+		await this.#onAction?.(this.#count);
+	};
+
+	public readonly setMessage = (message: string): void => {
+		this.#assertActive();
+		this.#message.textContent = message;
+	};
+
+	public readonly destroy = (): void => {
+		if (this.#destroyed) {
+			return;
+		}
+		this.#button.removeEventListener('click', this.#handleClick);
+		this.#root.remove();
+		this.#destroyed = true;
+	};
+
+	readonly #handleClick = (): void => {
+		void this.increment();
+	};
+
+	#assertActive(): void {
+		if (this.#destroyed) {
+			throw new Error('Widget has been destroyed.');
+		}
+	}
+}
+
+export const createWidget = (host: HTMLElement, options?: DemoWidgetOptions): DemoWidgetInstance => new DemoWidget(host, options);

package/dist/templates/web-widget/files/src/styles/index.css

@@ -0,0 +1,42 @@
+.widget {
+	--widget-bg: #121826;
+	--widget-fg: #f8fafc;
+	--widget-muted: #a5b4fc;
+	--widget-accent: #8b5cf6;
+
+	display: grid;
+	gap: 0.85rem;
+	max-width: 28rem;
+	padding: 1.25rem;
+	color: var(--widget-fg);
+	background: linear-gradient(135deg, var(--widget-bg), #312e81);
+	border-radius: 1.25rem;
+	box-shadow: 0 1.25rem 3rem rgba(15, 23, 42, 0.24);
+}
+
+.widget__title {
+	margin: 0;
+	font-size: 1.5rem;
+	line-height: 1.1;
+}
+
+.widget__message {
+	margin: 0;
+	color: var(--widget-muted);
+}
+
+.widget__button {
+	justify-self: start;
+	padding: 0.7rem 1rem;
+	font: inherit;
+	font-weight: 700;
+	color: var(--widget-fg);
+	cursor: pointer;
+	background: var(--widget-accent);
+	border: 0;
+	border-radius: 999px;
+}
+
+.widget__button:hover {
+	background: #7c3aed;
+}

package/dist/templates/web-widget/files/stylelint.base.config.js

@@ -0,0 +1,16 @@
+/** @type {import('stylelint').Config} */
+const config = {
+	extends: ['stylelint-config-standard'],
+	rules: {
+		'alpha-value-notation': 'number',
+		'color-function-notation': 'legacy',
+		'declaration-empty-line-before': null,
+		'font-family-name-quotes': null,
+		'media-feature-range-notation': 'context',
+		'number-max-precision': 4,
+		'rule-empty-line-before': null,
+		'selector-not-notation': 'simple',
+	},
+};
+
+export default config;

package/dist/templates/web-widget/files/stylelint.config.js

@@ -0,0 +1,15 @@
+import baseConfig from './stylelint.base.config.js';
+
+const widgetCssPrefix = 'widget';
+
+/** @type {import('stylelint').Config} */
+const config = {
+	...baseConfig,
+	rules: {
+		...baseConfig.rules,
+		'custom-property-pattern': `^(${widgetCssPrefix}|demo)-[a-z][a-z0-9-]*$`,
+		'selector-class-pattern': [`^(${widgetCssPrefix}(?:[a-zA-Z0-9_-]+)?|demo-[a-zA-Z0-9_-]+)$`, {resolveNestedSelectors: true}],
+	},
+};
+
+export default config;

package/dist/templates/web-widget/files/tests/e2e/widget.e2e-test.ts

@@ -0,0 +1,16 @@
+import {expect, test} from '@playwright/test';
+
+test.describe('widget demo', () => {
+	test.beforeEach(async ({page}) => {
+		await page.goto('/');
+	});
+
+	test('renders the widget and increments from the demo', async ({page}) => {
+		await expect(page.locator('.widget')).toBeVisible();
+		await expect(page.locator('.widget__title')).toHaveText('{{projectName}}');
+
+		await page.locator('.widget__button').click();
+
+		await expect(page.locator('.widget__message')).toHaveText('Clicked 1 time.');
+	});
+});

package/dist/templates/web-widget/files/tsdown.config.ts

@@ -0,0 +1,20 @@
+import {defineConfig} from 'tsdown';
+
+export default defineConfig({
+	entry: {
+		index: 'src/lib/index.ts',
+		react: 'src/lib/react.tsx',
+	},
+	deps: {
+		neverBundle: ['react', 'react/jsx-runtime'],
+	},
+	format: ['esm'],
+	dts: true,
+	fixedExtension: true,
+	outDir: 'dist',
+	clean: true,
+	target: 'es2022',
+	platform: 'neutral',
+	sourcemap: true,
+	copy: [{from: 'src/styles/index.css', to: 'dist/styles', flatten: true}],
+});

package/dist/templates/web-widget/files/typedoc.json

@@ -0,0 +1,12 @@
+{
+	"entryPoints": ["src/lib/index.ts", "src/lib/react.tsx"],
+	"out": "docs/api",
+	"exclude": ["**/*.test.ts", "**/*.test.tsx", "tests/**", "src/demo/**"],
+	"excludeInternal": true,
+	"excludePrivate": true,
+	"excludeProtected": true,
+	"readme": "none",
+	"plugin": [],
+	"tsconfig": "tsconfig.json",
+	"logLevel": "Warn"
+}