generator-white-label 9.0.0 → 10.0.0

package/CLI.md

@@ -7,7 +7,7 @@ CLI ──────> createProject() ──────> project
 Node API ─┘
 ```
 
-`createProject()` owns the scaffold, including destination safety. The CLI translates command-line input into that API.
+`createProject()` owns the canonical tagged-template scaffold, including destination safety. The CLI translates command-line input into that API; it does not maintain a second generation path.
 
 ## Create a project
 
@@ -36,23 +36,21 @@ npm install && npm test
 # or: pnpm install && pnpm test
 ```
 
-When run interactively, the CLI asks whether page and view templates should use JSX/TSX. JSX is optional: choose **Yes** for White Label's first-party JSX syntax such as `<section>...</section>`, or **No** for plain TypeScript functions that return HTML strings. Both choices produce the same working starter application and features.
+The generated project uses ordinary `.ts` files and White Label View's first-party tagged HTML templates:
 
-Choose **No** when you want plain string templates or plan to use a third-party renderer. Install that renderer in the generated application and call it from the View `template` function; White Label does not require an adapter. See [Template engines and JSX options](https://whitelabeljs.org/docs/view/#template-engines) for the tested third-party engines and rendering contract.
+```ts
+import {html} from 'white-label-view/html';
 
-For scripts and non-interactive use, choose explicitly:
-
-```sh
-white-label create my-project --jsx
-white-label create my-project --no-jsx
-
-npx generator-white-label create my-project --jsx
-npx generator-white-label create my-project --no-jsx
+export default function Page(data: {title: string}) {
+    return html`<main><h1>${data.title}</h1></main>`;
+}
 ```
 
-The same `--jsx` and `--no-jsx` flags work through `yarn dlx` and `pnpm dlx`.
+Dynamic text and quoted-attribute values are escaped by the tagged-template runtime. Use `attributes()` for conditional/opening-tag attributes and reserve `unsafeHTML()` for application-owned content that is already trusted or sanitized.
 
-If no choice can be asked interactively and neither flag is supplied, JSX is the default.
+There is no generator renderer prompt and no `--jsx` or `--no-jsx` flag. If a project prefers JSX, Handlebars, Eta, EJS, Mustache, Nunjucks, Pug, or another renderer, add it as an application dependency and return its rendered output from View's `template` function. JSX remains a tested third-party option rather than a generator-owned runtime.
+
+See [Template engines](https://whitelabeljs.org/docs/view/#template-engines) for tested integrations and trust boundaries.
 
 Run `white-label --help` for usage. See [`PACKAGE_MANAGERS.md`](PACKAGE_MANAGERS.md) for package-manager compatibility details.
 
@@ -62,13 +60,10 @@ Run `white-label --help` for usage. See [`PACKAGE_MANAGERS.md`](PACKAGE_MANAGERS
 import {createProject} from 'generator-white-label';
 
 await createProject({
-    destination: '/absolute/path/to/my-project',
-    jsx: false
+    destination: '/absolute/path/to/my-project'
 });
 ```
 
-Set `jsx: true` for JSX/TSX templates or `jsx: false` for plain TypeScript and HTML strings. Use `jsx: false` as the starting point when another template engine should own rendering. Omitting `jsx` defaults to `true`.
-
 `createProject()` uses the same destination-safety rule as the CLI: missing and empty directories are allowed; non-empty directories are rejected before project content is written.
 
 ## Read the implementation
@@ -77,6 +72,7 @@ The source is intentionally small enough to teach the design:
 
 - `scaffold/index.ts` — project creation and destination-safety boundary
 - `cli/index.ts` — command-line adapter
+- `app/` — canonical TypeScript/tagged-template starter
 - `test/` — executable contracts
 
 Creation behavior belongs in one place. Future integrations should call `createProject()` rather than copy templates or reimplement generation logic.

package/EXISTING_APPLICATIONS.md

@@ -0,0 +1,155 @@
+# Adopt White Label in an existing server-rendered application
+
+White Label does not require a rewrite. Existing applications should install only the runtime packages a feature needs and integrate them at explicit boundaries.
+
+The **generator is intentionally for new projects** and refuses to scaffold over a non-empty destination. If an application already exists—SFCC/SFRA, a CMS, Rails, PHP, Java, .NET, another server-rendered stack, or a long-lived frontend—do not regenerate the host application. Add White Label to one feature or DOM region at a time.
+
+This is one of the strongest White Label use cases: modern TypeScript structure and lifecycle where it helps, while the existing platform keeps ownership of routing, business rules, initial HTML, and the rest of the page.
+
+## When this pattern fits
+
+Incremental adoption is a good fit when:
+
+- the server or CMS already renders meaningful HTML;
+- public URLs, SEO, accessibility, or no-JavaScript behavior matter;
+- a rewrite would be disproportionate to the feature being added;
+- teams want observable state, lifecycle, application events, or URL-backed interaction without introducing a full frontend framework;
+- multiple teams/features need clear ownership boundaries on the same page;
+- commerce/account/content flows must keep authoritative business logic on the server.
+
+It is less compelling for experiences that are intentionally fully client-owned and deeply stateful across most of the viewport, such as editors, design tools, complex collaborative workspaces, or other applications where a component framework already provides valuable shared conventions.
+
+## Install only the needed primitives
+
+Start with the actual responsibility the feature needs:
+
+```sh
+npm install white-label-view white-label-model
+```
+
+Add Router or Mediator only when the feature genuinely needs URL state or cross-module events:
+
+```sh
+npm install white-label-router white-label-mediator
+```
+
+White Label packages do not require the generator at runtime and do not require one another unless the application chooses to compose them.
+
+A useful rule is:
+
+```text
+existing platform owns the page
+        +
+White Label owns a deliberate feature boundary
+```
+
+## Adopt existing server-rendered markup
+
+`white-label-view` can own lifecycle around an element that already exists instead of replacing the host application's rendering system.
+
+```ts
+import {Model} from 'white-label-model';
+import View from 'white-label-view';
+
+const status = document.querySelector<HTMLElement>('[data-filter-status]')!;
+const filters = new Model({color: ''});
+
+const statusView = new View({
+    parentElement: status.parentElement!,
+    element: status,
+    model: filters,
+    update(element, data) {
+        const state = data as {color: string};
+        element.textContent = state.color
+            ? `Color filter: ${state.color}`
+            : 'No color filter selected';
+        return true;
+    }
+}).initialize();
+```
+
+No client template is required when an attached existing element can be updated in place. The host remains responsible for the initial HTML; View owns only the adopted root and its lifecycle.
+
+Keep ownership narrow. Unrelated server-rendered siblings, headers, forms, navigation, and page chrome should remain outside the View unless the feature genuinely owns them.
+
+`destroy()` removes the root the View owns. If the host application expects that element to remain after enhancement teardown, choose an ownership boundary that can be removed safely rather than treating host-owned markup as disposable.
+
+## Scope progressive routing to one enhanced region
+
+By default, Router listens for opted-in `data-pushstate` links across the document. An embedded or incrementally adopted feature can limit that interception to its own DOM region:
+
+```ts
+import Router from 'white-label-router';
+
+const refinementArea = document.querySelector<HTMLElement>('[data-refinements]')!;
+const router = new Router();
+
+router.navigationRoot = refinementArea;
+router.routes = {
+    '/search': (_scope, location) => {
+        filters.update({color: location.data.query.prefv1 || ''});
+    }
+};
+router.initialize();
+```
+
+Only eligible links whose click event reaches that navigation root are enhanced by that Router. Other page links retain the host application's normal behavior. Multiple independently owned regions can therefore coexist without every Router claiming document-wide link handling.
+
+`navigationRoot` controls click-listener ownership. It is deliberately separate from `router.scope`, which remains the value passed to route handlers.
+
+## Add state and events only where needed
+
+A feature does not need the full White Label stack.
+
+Use `white-label-model` when the feature needs observable state. Load data through the application's existing fetch/client/service layer, validate it at that boundary when appropriate, then apply it to Model. Model should not replace a backend API, persistence layer, or framework store solely for architectural symmetry.
+
+Use `white-label-mediator` when separate modules need to exchange intent without importing one another. Direct function calls are clearer when there is already an ownership relationship. Avoid turning a mediator into an unstructured global event namespace.
+
+## Preserve the host application's server contract
+
+White Label should not duplicate or bypass server-owned responsibilities. Keep these in the existing platform when it already owns them:
+
+- authentication and authorization;
+- pricing, inventory, tax, promotions, checkout, and other authoritative business rules;
+- canonical URLs and directly requestable public routes;
+- initial semantic content and crawlable navigation;
+- CSRF/session protections and trusted API boundaries;
+- CMS/content governance and server-side personalization rules;
+- persistence, queues, retries, and cross-process workflows.
+
+Use White Label where a client-side state, lifecycle, event, or URL boundary adds value. Normal server navigation is still the right choice when enhancement does not materially improve the interaction.
+
+## SEO and accessibility boundary
+
+For public content, keep the important information in the initial response. Progressive enhancement should improve interaction rather than become a prerequisite for discovery or comprehension.
+
+Prefer:
+
+- real `href` values and directly requestable routes;
+- semantic headings, forms, controls, landmarks, and status regions in initial HTML;
+- server/static ownership of canonical URLs, titles, descriptions, robots directives, and structured data;
+- deliberate focus handling after meaningful client-side navigation or content replacement;
+- client behavior that preserves keyboard, context-menu, modified-click, and no-JavaScript behavior.
+
+Do not treat source-level metadata as proof of search-engine indexing. Validate deployed behavior and indexing with actual production/search-console evidence.
+
+## Teardown
+
+Long-lived shells and dynamically mounted regions should release the objects they own:
+
+```ts
+statusView.destroy();
+router.destroy();
+filters.destroy();
+```
+
+Also destroy a feature-owned Mediator when that event boundary leaves the application lifecycle.
+
+## Commerce and SFCC example
+
+The White Label demo repository contains a concrete Salesforce B2C Commerce / SFRA example using the same incremental boundary:
+
+- [SFCC / SFRA progressive enhancement recipe](https://github.com/bshack/white-label-demo-site/blob/main/docs/recipes/sfcc-sfra-progressive-enhancement.md)
+- [Incremental JavaScript for server-rendered applications](https://whitelabeljs.org/guides/incremental-javascript-for-server-rendered-apps/)
+
+The same pattern applies to other server-rendered stacks: keep the server as the source of truth, then adopt only the client-side regions that need richer behavior.

package/PACKAGE_MANAGERS.md

@@ -10,9 +10,9 @@ yarn dlx generator-white-label create my-project
 pnpm dlx generator-white-label create my-project
 ```
 
-The same `--jsx` and `--no-jsx` options are available through every invocation path. JSX is optional: use `--jsx` for the first-party White Label JSX runtime, or `--no-jsx` for plain TypeScript templates and as the starting point for a third-party template engine.
+Every invocation creates the same canonical TypeScript/tagged-template starter. There are no renderer-selection flags.
 
-See [Template engines and JSX options](https://whitelabeljs.org/docs/view/#template-engines) for tested third-party renderers and the View rendering contract.
+White Label View remains template-engine agnostic. Projects that prefer JSX or a third-party renderer can install it after generation and return its rendered output from View's `template` function. See [Template engines](https://whitelabeljs.org/docs/view/#template-engines) for tested integrations and trust boundaries.
 
 ## Work with a generated project
 
@@ -26,10 +26,12 @@ pnpm install && pnpm test
 
 Generated manifests require the supported Node.js runtime but do not require a specific package manager. Nested scripts use Node's `--run` support instead of invoking npm internally.
 
-Generated projects use exact npm versions for the four first-party White Label packages. They also carry narrow install-script approvals for the dependencies that actually need lifecycle builds: `esbuild`, `@parcel/watcher`, and `white-label-view`. npm uses pinned `allowScripts` entries, Yarn uses pinned `dependenciesMeta` build permissions, and pnpm uses `onlyBuiltDependencies`.
+Generated projects use exact npm versions for the four first-party White Label packages. Install/build lifecycle approvals are limited to dependencies that need native or generated artifacts during installation: `esbuild` and `@parcel/watcher`. npm uses pinned `allowScripts` entries, Yarn uses pinned `dependenciesMeta` build permissions, and pnpm uses `onlyBuiltDependencies`. Published White Label runtime packages include their built output and do not receive lifecycle-script approval in generated projects.
 
-Yarn's package-age security gate is left enabled for ordinary dependencies. The generated `.yarnrc.yml` preapproves only `white-label-mediator`, `white-label-model`, `white-label-router`, and `white-label-view` so a newly published White Label release can be installed immediately without disabling Yarn's protection for the rest of the dependency graph.
+Yarn's package-age security gate is left enabled for ordinary dependencies. The generated `.yarnrc.yml` preapproves only `white-label-mediator`, `white-label-model`, `white-label-router`, and `white-label-view` so a newly published coordinated White Label release can be installed immediately without disabling Yarn's protection for the rest of the dependency graph. Package-age preapproval does not grant lifecycle-script execution.
 
 ## Repository development
 
 The committed `package-lock.json` remains the generator repository's canonical dependency lockfile and npm remains the maintenance/audit path used by primary CI. Compatibility CI packs the real generator artifact and verifies its API and CLI under npm, Yarn, and pnpm. Alternate lockfiles are not committed merely for compatibility testing.
+
+Generator 10 depends on `white-label-view@7`. View 7's implementation is merged but not yet published, so coordinated CI temporarily builds and injects the exact merged View 7 revision for integration testing. The release lockfile remains registry-based; do not replace it with a Git dependency or treat the temporary packed artifact as a published dependency. Normal registry installation remains a release gate until View 7 is published.