generator-white-label 5.0.1 → 8.0.0

package/package.json

@@ -1,37 +1,62 @@
 {
   "name": "generator-white-label",
-  "version": "5.0.1",
-  "description": "Scaffolding for developing and building static sites.",
+  "version": "8.0.0",
+  "description": "Framework-independent TypeScript project generator for accessible, SEO-friendly sites with progressive enhancement, optional JSX, and a provider-neutral serverless handler example.",
   "type": "module",
-  "main": "dist/generators/app/index.js",
+  "main": "dist/scaffold/index.js",
+  "bin": {
+    "generator-white-label": "dist/cli/index.js",
+    "white-label": "dist/cli/index.js"
+  },
   "engines": {
-    "node": "^22.18.0 || >=24.11.0",
-    "npm": ">=10.0"
+    "node": "^22.18.0 || >=24.11.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && node dist/scripts/build.js",
-    "test": "npm run compile && npm run test:types && npm run test:unit",
+    "test": "node --run compile && node --run test:types && node --run test:unit",
     "audit": "npm audit --audit-level=low",
     "compile": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test:unit": "node --test test/*.test.js",
-    "coverage": "npm run compile && npm run test:types && c8 npm run test:unit",
-    "prepack": "npm run compile",
-    "test:types": "tsc -p tsconfig.consumer.json"
+    "coverage": "node --run compile && node --run test:types && c8 node --run test:unit",
+    "prepack": "node --run compile",
+    "test:types": "tsc -p tsconfig.consumer.json",
+    "lint": "eslint \"cli/**/*.ts\" \"scripts/**/*.ts\" \"scaffold/**/*.ts\" \"server/**/*.ts\" \"app/**/*.{ts,tsx}\" --max-warnings=0",
+    "lint:fix": "node --run lint -- --fix"
   },
   "files": [
+    ".editorconfig",
+    ".yarnrc.yml",
+    "pnpm-workspace.yaml",
     "app",
-    "generators",
+    "cli",
+    "scaffold",
+    "server",
     "scripts",
+    "template-test",
     "README.md",
+    "CLI.md",
+    "PACKAGE_MANAGERS.md",
     "dist",
-    "tsconfig.site.json"
+    "tsconfig.site.json",
+    "tsconfig.site.no-jsx.json"
   ],
   "keywords": [
-    "handlebars",
-    "sass",
+    "typescript",
+    "project-generator",
+    "static-site-generator",
+    "web-development",
+    "framework-independent",
+    "accessibility",
+    "seo",
+    "progressive-enhancement",
+    "serverless",
     "esbuild",
-    "yeoman-generator"
+    "tailwindcss",
+    "jsx",
+    "cli",
+    "scaffolding",
+    "white-label"
   ],
   "author": "Bill Shackelford",
   "license": "MIT",
@@ -42,40 +67,38 @@
   "bugs": {
     "url": "https://github.com/bshack/white-label/issues"
   },
-  "homepage": "https://github.com/bshack/white-label",
-  "dependencies": {
-    "@types/node": "24.13.3",
-    "@yeoman/adapter": "5.0.0",
-    "bootstrap": "5.3.8",
-    "chalk": "6.0.0",
-    "esbuild": "0.28.2",
-    "events": "3.3.0",
-    "handlebars": "4.7.9",
-    "react": "19.2.8",
-    "react-dom": "19.2.8",
-    "sass": "1.104.0",
-    "white-label-model": "3.0.0",
-    "white-label-view": "4.0.0",
-    "yeoman-generator": "8.3.1",
-    "yosay": "3.0.0"
-  },
+  "homepage": "https://whitelabeljs.org/docs/generator/",
+  "dependencies": {},
   "devDependencies": {
-    "@types/react": "19.2.18",
-    "@types/react-dom": "19.2.7",
-    "@types/yosay": "2.0.3",
+    "@tailwindcss/cli": "4.3.3",
+    "@types/node": "24.13.3",
+    "axe-core": "4.13.0",
     "c8": "12.0.0",
+    "esbuild": "0.28.2",
+    "html-validate": "11.15.0",
     "jsdom": "30.0.1",
+    "tailwindcss": "4.3.3",
     "typescript": "7.0.2",
-    "yeoman-environment": "7.0.0"
+    "white-label-mediator": "4.0.0",
+    "white-label-model": "6.0.0",
+    "white-label-router": "5.0.0",
+    "white-label-view": "5.1.0",
+    "@babel/core": "8.0.5",
+    "@babel/eslint-parser": "8.0.5",
+    "@babel/plugin-syntax-jsx": "8.0.1",
+    "@babel/preset-typescript": "8.0.1",
+    "@eslint/js": "10.0.1",
+    "eslint": "10.10.0"
   },
-  "types": "dist/generators/app/index.d.ts",
+  "types": "dist/scaffold/index.d.ts",
   "c8": {
     "all": true,
     "include": [
+      "cli/**/*.ts",
       "scripts/**/*.ts",
-      "generators/**/*.ts",
-      "app/assets/script/**/*.ts",
-      "app/assets/script/**/*.tsx"
+      "scaffold/**/*.ts",
+      "app/**/*.ts",
+      "app/**/*.tsx"
     ],
     "reporter": [
       "text",
@@ -91,7 +114,21 @@
     "statements": 100,
     "perFile": true,
     "exclude": [
-      "**/*.d.ts"
+      "**/*.d.ts",
+      "app/assets/view/page-data.ts",
+      "scaffold/no-jsx/app/**"
     ]
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/scaffold/index.d.ts",
+      "import": "./dist/scaffold/index.js",
+      "default": "./dist/scaffold/index.js"
+    },
+    "./scaffold": {
+      "types": "./dist/scaffold/index.d.ts",
+      "import": "./dist/scaffold/index.js",
+      "default": "./dist/scaffold/index.js"
+    }
   }
 }

package/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+onlyBuiltDependencies:
+  - '@parcel/watcher'
+  - esbuild
+  - white-label-view

package/scaffold/index.ts

@@ -0,0 +1,127 @@
+/** @module scaffold */
+import {cp, mkdir, writeFile} from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+
+export interface ScaffoldFileSystem {
+    copy(source: string, destination: string): void | Promise<void>;
+    writeJSON(destination: string, value: unknown): void | Promise<void>;
+}
+
+export interface CreateProjectOptions {
+    destination: string;
+    fileSystem?: ScaffoldFileSystem;
+    jsx?: boolean;
+}
+
+const nodeFileSystem: ScaffoldFileSystem = {
+    async copy(source, destination) {
+        await mkdir(path.dirname(destination), {recursive: true});
+        await cp(source, destination, {recursive: true});
+    },
+    async writeJSON(destination, value) {
+        await mkdir(path.dirname(destination), {recursive: true});
+        await writeFile(destination, `${JSON.stringify(value, null, 2)}\n`);
+    }
+};
+
+/** Return the package manifest used by generated White Label projects. */
+export function createSiteManifest() {
+    return {
+        name: 'white-label-site',
+        version: '1.0.0',
+        private: true,
+        type: 'module',
+        engines: {node: '^22.18.0 || >=24.11.0'},
+        scripts: {
+            build: 'tsc -p tsconfig.json && node dist/scripts/build.js',
+            typecheck: 'tsc -p tsconfig.json --noEmit',
+            test: 'node --run typecheck && node --run build -- --version=test --production=true --site-url=https://example.com && node --test --experimental-test-coverage --test-coverage-include=dist/app/assets/script/index.js --test-coverage-lines=100 --test-coverage-functions=100 --test-coverage-branches=100 test/*.test.js'
+        },
+        allowScripts: {
+            '@parcel/watcher@2.5.1': true,
+            'esbuild@0.28.2': true,
+            'white-label-view@5.1.0': true
+        },
+        dependenciesMeta: {
+            '@parcel/watcher@2.5.1': {built: true},
+            'esbuild@0.28.2': {built: true},
+            'white-label-view@5.1.0': {built: true}
+        },
+        devDependencies: {
+            '@tailwindcss/cli': '4.3.3',
+            '@types/node': '24.13.3',
+            'axe-core': '4.13.0',
+            'esbuild': '0.28.2',
+            'html-validate': '11.15.0',
+            'jsdom': '30.0.1',
+            'tailwindcss': '4.3.3',
+            'typescript': '7.0.2'
+        },
+        dependencies: {
+            'white-label-mediator': '4.0.0',
+            'white-label-model': '6.0.0',
+            'white-label-router': '5.0.0',
+            'white-label-view': '5.1.0'
+        }
+    };
+}
+
+const commonNoJsxCopies = [
+    ['app/assets/data', 'app/assets/data'],
+    ['app/assets/style', 'app/assets/style'],
+    ['app/assets/script/tasks/TaskApplication.ts', 'app/assets/script/tasks/TaskApplication.ts'],
+    ['app/assets/script/tasks/TaskMediator.ts', 'app/assets/script/tasks/TaskMediator.ts'],
+    ['app/assets/script/tasks/TaskModel.ts', 'app/assets/script/tasks/TaskModel.ts'],
+    ['app/assets/script/tasks/TaskRouter.ts', 'app/assets/script/tasks/TaskRouter.ts'],
+    ['app/assets/view/examples/tasks/task-state.ts', 'app/assets/view/examples/tasks/task-state.ts'],
+    ['app/package.json', 'app/package.json']
+] as const;
+
+const noJsxTemplateCopies = [
+    ['scaffold/no-jsx/app/index.ts', 'app/index.ts'],
+    ['scaffold/no-jsx/app/404.ts', 'app/404.ts'],
+    ['scaffold/no-jsx/app/assets/script/index.ts', 'app/assets/script/index.ts'],
+    ['scaffold/no-jsx/app/assets/script/tasks/TaskView.ts', 'app/assets/script/tasks/TaskView.ts'],
+    ['scaffold/no-jsx/app/assets/view/examples/tasks/TaskExample.ts', 'app/assets/view/examples/tasks/TaskExample.ts'],
+    ['scaffold/no-jsx/README.md', 'README.md'],
+    ['tsconfig.site.no-jsx.json', 'tsconfig.json']
+] as const;
+
+/**
+ * Create a White Label project.
+ *
+ * This is the shared implementation behind every creation interface. Adapters
+ * translate their environment into these options instead of owning templates or
+ * project-generation behavior themselves.
+ */
+export async function createProject({destination, fileSystem = nodeFileSystem, jsx = true}: CreateProjectOptions) {
+    const copies = jsx ? [
+        ['.editorconfig', '.editorconfig'],
+        ['.yarnrc.yml', '.yarnrc.yml'],
+        ['pnpm-workspace.yaml', 'pnpm-workspace.yaml'],
+        ['app', 'app'],
+        ['app/README.md', 'README.md'],
+        ['server', 'server'],
+        ['scripts', 'scripts'],
+        ['template-test', 'test'],
+        ['tsconfig.site.json', 'tsconfig.json']
+    ] as const : [
+        ['.editorconfig', '.editorconfig'],
+        ['.yarnrc.yml', '.yarnrc.yml'],
+        ['pnpm-workspace.yaml', 'pnpm-workspace.yaml'],
+        ...commonNoJsxCopies,
+        ...noJsxTemplateCopies,
+        ['server', 'server'],
+        ['scripts', 'scripts'],
+        ['template-test', 'test']
+    ] as const;
+
+    for (const [source, target] of copies) {
+        await fileSystem.copy(path.join(packageRoot, source), path.join(destination, target));
+    }
+
+    await fileSystem.writeJSON(path.join(destination, 'package.json'), createSiteManifest());
+}

package/scaffold/no-jsx/README.md

@@ -0,0 +1,47 @@
+# White Label generated site
+
+This project was generated with the **plain TypeScript / no-JSX** template option.
+
+- Pages and views are `.ts` files.
+- Templates return HTML strings instead of using JSX/TSX syntax.
+- React is not required.
+- White Label Model, View, Router, and Mediator are used the same way as in the JSX template.
+- npm, Yarn, and pnpm are supported.
+
+This scaffold is also the right starting point when you want a third-party template engine. Install the renderer your application uses, then call it from the View `template` function instead of returning a hand-built string. White Label does not require a renderer adapter or change the rest of the application architecture.
+
+See [Template engines and JSX options](https://whitelabeljs.org/docs/view/#template-engines) for the tested third-party engines, examples, rendering contract, and escaping/security guidance.
+
+## Commands
+
+Use the package manager you prefer:
+
+```sh
+npm install
+npm run build
+npm test
+```
+
+```sh
+yarn install
+yarn build
+yarn test
+```
+
+```sh
+pnpm install
+pnpm build
+pnpm test
+```
+
+## Serverless / function runtimes
+
+`server/handler.ts` is the same provider-neutral serverless example included in the JSX scaffold. It uses Web `Request` and `Response`, request-scoped Model/View/Router/Mediator instances, and the server View entrypoint; it does not require JSX or a provider SDK.
+
+Keep immutable configuration at module scope when useful, but create mutable White Label instances per request unless shared state is explicitly intended. Warm serverless processes may handle many requests, so module-level mutable application state can leak data between invocations.
+
+Use a thin cloud adapter around the handler when a platform does not expose Web `Request`/`Response` directly. The generated tests exercise repeated and concurrent requests, browser-global absence, Web-target bundling, and serverless bundle/startup budgets.
+
+The Web-target bundle check is a portability smoke test, not a blanket claim of compatibility with every edge runtime. Verify the provider runtime you deploy to.
+
+If you prefer JSX syntax for templates, generate a new project with `--jsx` or answer **Yes** to the generator's JSX question. JSX and no-JSX projects provide equivalent White Label functionality; the choice is about template syntax and renderer ownership.

package/scaffold/no-jsx/app/404.ts

@@ -0,0 +1,10 @@
+interface PageData {cdn: string; siteUrl: string; title: string; version: string}
+
+function escapeHtml(value: unknown): string {
+    return String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&#39;');
+}
+
+export default function NotFoundPage(data: Record<string, unknown>): string {
+    const page = data as unknown as PageData;
+    return `<html lang="en-US"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Page not found | ${escapeHtml(page.title)}</title><meta name="robots" content="noindex,follow"><link rel="stylesheet" href="${escapeHtml(page.cdn)}release/${escapeHtml(page.version)}/assets/style/global.css"></head><body><a class="skip-link" href="#main">Skip to the message</a><main id="main" tabindex="-1"><h1>Page not found</h1><p>The requested page could not be found.</p><p><a href="${escapeHtml(page.siteUrl)}/">Return home</a></p></main></body></html>`;
+}

package/scaffold/no-jsx/app/assets/script/index.ts

@@ -0,0 +1,7 @@
+/** @module app/assets/script/index */
+import {initializeTaskApplication} from './tasks/TaskApplication.js';
+
+export {initializeTaskApplication} from './tasks/TaskApplication.js';
+export {normalizeTaskFilter} from './tasks/TaskRouter.js';
+
+initializeTaskApplication(document);

package/scaffold/no-jsx/app/assets/script/tasks/TaskView.ts

@@ -0,0 +1,19 @@
+import View from 'white-label-view';
+import TaskExample from '../../view/examples/tasks/TaskExample.js';
+import type {TaskState} from '../../view/examples/tasks/task-state.js';
+import type TaskModel from './TaskModel.js';
+
+/** Create the task view without JSX/TSX syntax. */
+export function createTaskView(parentElement: HTMLElement, model: TaskModel): View {
+    const element = parentElement.querySelector<HTMLElement>('[data-task-app]');
+    if (!element) {throw new TypeError('Task example requires its static task-app root');}
+
+    return new View({
+        element,
+        model,
+        parentElement,
+        template(data) {
+            return TaskExample({state: data as TaskState});
+        }
+    }).initialize();
+}

package/scaffold/no-jsx/app/assets/view/examples/tasks/TaskExample.ts

@@ -0,0 +1,39 @@
+import {getVisibleTasks, type TaskFilter, type TaskState} from './task-state.js';
+
+const filters: TaskFilter[] = ['all', 'active', 'completed'];
+
+function escapeHtml(value: unknown): string {
+    return String(value)
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+}
+
+/** Render the task example with plain TypeScript and HTML strings. */
+export default function TaskExample({state}: {state: TaskState}): string {
+    const visibleTasks = getVisibleTasks(state);
+    const completed = state.tasks.filter(task => task.complete).length;
+    const filterLinks = filters.map(filter => `
+        <a href="/?tasks=${filter}#example" data-task-filter="${filter}" data-pushstate aria-current="${state.filter === filter ? 'page' : 'false'}">${filter.charAt(0).toUpperCase()}${filter.slice(1)}</a>
+    `).join('');
+    const tasks = visibleTasks.map(task => `
+        <li><label><input type="checkbox" ${task.complete ? 'checked ' : ''}data-task-toggle data-task-id="${task.id}"><span>${escapeHtml(task.title)}</span></label></li>
+    `).join('');
+
+    return `<section class="task-app" data-task-app aria-label="Interactive task example">
+        <form class="task-form" data-task-form action="#example" method="get">
+            <label for="task-title">New task</label>
+            <div class="task-form__controls"><input id="task-title" name="task" type="text" autocomplete="off" required><button type="submit">Add task</button></div>
+        </form>
+        <nav class="task-filters" aria-label="Filter tasks">${filterLinks}</nav>
+        <ul class="task-list">${tasks}</ul>
+        <dl class="demo__trace">
+            <div><dt>Router</dt><dd>/?tasks=${state.filter}</dd></div>
+            <div><dt>Mediator</dt><dd>task:* application events</dd></div>
+            <div><dt>Model</dt><dd>${state.tasks.length} tasks · ${completed} complete</dd></div>
+            <div><dt>View</dt><dd>${visibleTasks.length} tasks rendered</dd></div>
+        </dl>
+    </section>`;
+}

package/scaffold/no-jsx/app/index.ts

@@ -0,0 +1,58 @@
+import TaskExample from './assets/view/examples/tasks/TaskExample.js';
+import {createInitialTaskState, describeTaskStatus} from './assets/view/examples/tasks/task-state.js';
+
+interface PageData {
+    cdn: string;
+    meta: {description: string};
+    siteUrl: string;
+    structuredData: Record<string, unknown>;
+    title: string;
+    version: string;
+}
+
+function escapeHtml(value: unknown): string {
+    return String(value)
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+}
+
+/** Render the generated starter using plain TypeScript and HTML strings. */
+export default function IndexPage(data: Record<string, unknown>): string {
+    const page = data as unknown as PageData;
+    const taskState = createInitialTaskState();
+    const taskExample = TaskExample({state: taskState});
+    const taskStatus = describeTaskStatus(taskState);
+    const structuredData = JSON.stringify(page.structuredData).replaceAll('<', '\\u003c');
+
+    return `<html id="index" lang="en-US" dir="ltr">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(page.title)}</title>
+<meta name="description" content="${escapeHtml(page.meta.description)}">
+<meta name="robots" content="index,follow,max-image-preview:large,max-snippet:-1,max-video-preview:-1">
+<link rel="canonical" href="${escapeHtml(page.siteUrl)}/">
+<meta property="og:title" content="${escapeHtml(page.title)}">
+<meta property="og:description" content="${escapeHtml(page.meta.description)}">
+<meta property="og:type" content="website">
+<meta property="og:url" content="${escapeHtml(page.siteUrl)}/">
+<link rel="stylesheet" href="${escapeHtml(page.cdn)}release/${escapeHtml(page.version)}/assets/style/global.css" media="all">
+<link rel="stylesheet" href="${escapeHtml(page.cdn)}release/${escapeHtml(page.version)}/assets/style/print.css" media="print">
+<script type="application/ld+json">${structuredData}</script>
+</head>
+<body itemscope itemtype="https://schema.org/WebPage">
+<a class="skip-link" href="#main">Skip to content</a>
+<header><nav aria-label="Primary"><a href="/">White Label</a></nav></header>
+<main id="main" tabindex="-1">
+<section class="hero"><p class="eyebrow">White Label starter</p><h1>Composable web primitives without a framework lock-in.</h1><p>State, rendering, routing, and application events stay small, explicit, and independently understandable.</p></section>
+<section id="example" data-task-example><h2>Interactive task example</h2>${taskExample}<p class="visually-hidden" role="status" aria-live="polite" aria-atomic="true" data-task-status>${escapeHtml(taskStatus)}</p></section>
+<section><h2>Plain TypeScript templates</h2><p>This project was generated without JSX. Pages and views return HTML strings from ordinary TypeScript functions.</p></section>
+</main>
+<footer><p>Built with White Label.</p></footer>
+<script src="${escapeHtml(page.cdn)}release/${escapeHtml(page.version)}/assets/script/index.compiled.js" defer></script>
+</body>
+</html>`;
+}