generator-white-label 3.0.0 → 5.0.0

package/README.md

@@ -1,136 +1,195 @@
-# white label
+# white-label
 
-[![Build Status](https://travis-ci.org/bshack/white-label.svg?branch=master)](https://travis-ci.org/bshack/white-label)
+`white-label` is a Yeoman generator and build system for creating static websites. It provides a working project structure with Handlebars templates, Sass styles, Bootstrap, responsive images, and TypeScript sources compiled to bundled JavaScript.
 
-Scaffolding for developing and deploying sites.
+Use it when you want a small, understandable static-site foundation that you can brand and extend without adopting a full application framework.
 
-## Key Libraries
+## What it builds
 
-- Babel
-- Foundation
-- Browserify
-- Browsersync
-- Gulp
-- Handlebars
-- Jasmine
-- Modernizr
-- Node Events
-- Karma
-- ReactJS
-- SCSS
-- [White Label Model](https://github.com/bshack/white-label-model)
+The project separates source files by responsibility:
 
-## Install Dependancies
+- `app/*.hbs` contains pages.
+- `app/assets/markup` contains reusable Handlebars partials.
+- `app/assets/data/view` contains global and page-specific JSON data.
+- `app/assets/style` contains Sass entry points and partials.
+- `app/assets/script` contains TypeScript and TSX entry points.
+- `app/assets/image` and `app/assets/font` contain static assets.
+- `scripts/build.ts` turns those sources into a deployable `_deploy` directory.
 
-IMPORTANT: Verify you have the latest versions of each of these if you have previously installed them.
+The build renders Handlebars pages, compiles Sass, bundles JavaScript with esbuild, copies static assets, and writes the deployment configuration to `assets/data/config.json`. `global.css` includes the complete compiled Bootstrap CSS followed by the project's styles.
 
-### Nodejs
+Generated formatting utilities use native `Intl` and `Date` APIs, so new projects do not need Lodash, Moment, or Numeral for the included examples.
 
-http://nodejs.org
+## Requirements
 
-_This project works with 'LTS' or 'Current'_
+- Node.js 20 or newer
+- npm 10 or newer
 
-### Gulp
+## Generate a new site
 
-http://gulpjs.com
+Install Yeoman and the generator, then run it in an empty project directory:
 
-### Other
-
-Debian/Ubuntu Users:
-build-essential package
+```sh
+npm install --global yo generator-white-label
+mkdir my-site
+cd my-site
+yo white-label
+```
 
-### Node Modules
+The generator copies the `app` and `scripts` directories and creates a project `package.json`. It intentionally does not install dependencies automatically, so you can review that manifest first:
 
-```
-npm install;
+```sh
+npm install
+npm test
 ```
 
-### Text Editor Config
+## Build the site
 
-Install the correct plugin for your text editor here:
+A build with defaults is enough for local inspection:
 
-http://editorconfig.org/#download
-
-This will normalize settings like what tab character(s) to use and will avoid linting errors.
+```sh
+npm run build
+```
 
-## Gulp Tasks
+The generated site is written to `_deploy`. Each asset build is placed under `_deploy/release/<version>/assets`; when no version is supplied, the build uses the current Unix timestamp.
 
-### Watch
+For a deployment build, pass explicit values after `--`:
 
-```
-gulp watch;
+```sh
+npm run build -- \
+  --www=https://www.example.com \
+  --cdn=https://cdn.example.com \
+  --service=https://api.example.com \
+  --version=2026.09.06 \
+  --production=true
 ```
 
-This will create a Browsersync server and reload your browser window(s) as you make code changes.
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `--www` | `/` | Public website base URL exposed to templates and configuration. |
+| `--cdn` | `/` | Asset base URL exposed to templates and configuration. |
+| `--service` | `/service-endpoint` | Backend service URL exposed to the site. |
+| `--version` | Current Unix timestamp | Directory name used for versioned assets. |
+| `--production` | `false` | Minifies CSS and JavaScript when set to `true`. |
 
-Learn more about Browsersync here: https://www.browsersync.io
+The version may contain only letters, numbers, dots, underscores, and hyphens. This prevents it from escaping the deployment directory.
 
-### Deploy
+## Add a page
 
-This compiles and bundles everything into a deploy ready package outputted in the '\_deploy' directory.
+Create `app/about.hbs`:
 
+```handlebars
+{{> element/head}}
+<main>
+    <h1>{{title}}</h1>
+    <p>{{introduction}}</p>
+</main>
 ```
-gulp deploy --www=(www domain - required) --cdn=(cdn domain - required) --service=(service domain - required) --production=(true|false - optional) --version=(unique deploy version - optional);
+
+Then create matching data at `app/assets/data/view/about.json`:
+
+```json
+{
+  "title": "About us",
+  "introduction": "A short description of the organization."
+}
 ```
 
-_The 'version' argument defaults to an epoch timestamp and the 'production' argument defaults to 'false'._
+Global data from `app/assets/data/view/global.json`, page data, and build options are merged before the template is rendered. Page-specific values take precedence over global values, and build options take precedence over both.
 
-#### Example
+## Responsive images
 
-```
-gulp deploy --www=//www.example.com --cdn=//cdn.example.com --service=//service.example.com --version=123456789 --production=true;
+The included `picture` partial supports AVIF and WebP sources at each responsive breakpoint, with an ordinary image as the final fallback:
+
+```handlebars
+{{> element/picture
+    imageFallback='assets/image/hero/fallback.jpg'
+    imageSmallAvif='assets/image/hero/small.avif'
+    imageSmallWebp='assets/image/hero/small.webp'
+    imageLargeAvif='assets/image/hero/large.avif'
+    imageLargeWebp='assets/image/hero/large.webp'
+    width='2048'
+    height='1600'
+    loading='lazy'
+    decoding='async'
+    alt='A human-readable description of the image'
+}}
 ```
 
-### Unit Tests
+Browsers choose the first supported source whose media query matches. Browsers without AVIF or WebP support use `imageFallback`. Supplying width and height also reserves layout space and helps avoid content movement while the image loads.
 
-watch:
+## Development checks
 
-```
-gulp unitWatch;
+Run the same basic checks before proposing a change:
+
+```sh
+npm run build
+npm run typecheck
+npm test
+npm run coverage
+npm run audit
 ```
 
-single run:
+## Version 4 migration notes
 
-```
-gulp unit;
-```
+Version 4 intentionally replaced the unsupported Gulp 3, Babel 6, PhantomJS, Karma, Bower, and legacy plugin pipeline. It also replaced Foundation with Bootstrap 5.3.8 and migrated the grid markup to Bootstrap `row` and responsive `col-*` classes. Projects upgrading from an older major version should treat the build tooling, supported Node.js versions, CSS framework, and generated markup as breaking changes.
 
-### More
+Version 4.1 removes Lodash, Moment, and Numeral from generated projects. If application code added its own imports from those packages, either retain the dependency in that application or migrate those calls before upgrading.
 
-These in additional to other tasks run as dependencies of the 'watch' and 'deploy' tasks.
+## Related packages
 
-```
-gulp markup;
-gulp style;
-gulp script;
-gulp accessibility;
-gulp documentation;
-```
+- [`white-label-model`](https://github.com/bshack/white-label-model) provides event-emitting models and collections.
+- [`white-label-view`](https://github.com/bshack/white-label-view) renders templates and manages delegated DOM events.
+- [`white-label-router`](https://github.com/bshack/white-label-router) provides History API navigation.
+- [`white-label-mediator`](https://github.com/bshack/white-label-mediator) provides shared application messaging.
+- [`white-label-service`](https://github.com/bshack/white-label-service) provides an authenticated JSON service backed by MySQL.
 
-## Test If Your Project Will Build
+## TypeScript development and version 5.0.0 migration
 
-Run this when you want to verify your changes will build properly on the CI server before pushing:
+Implementation code now uses strict TypeScript. Builds emit JavaScript, source maps with embedded source, and `.d.ts` declarations into `dist`. JavaScript callers can still use the package without compiling TypeScript themselves. JSDoc comments describe parameters, return values, lifecycle behavior, and validation at the implementation, and are retained in declarations.
 
-```
-npm test;
+```ts
+// app/assets/script/profile.ts
+import User from './model/user.js';
+
+const profile = new User({name: 'Ada'});
+console.log(profile.get().name);
 ```
 
-## NPM Shrinkwrap
+Write implementation files as `.ts`, or `.tsx` for React markup. Keep `.js` extensions on relative imports: TypeScript resolves them to source files and emits imports usable by Node. Every top-level script entry is bundled, except declaration-only `.d.ts` files. The build checks all sample modules, including modules not imported by an entry point.
 
-This project uses npm shrinkwrap to freeze npm module versions for improved project stability. More information here: https://docs.npmjs.com/cli/shrinkwrap.
+The `types.d.ts` file documents the subset of older published white-label dependencies used by the scaffold. It also declares optional SDK callbacks on `window`. These are explicit compatibility declarations, not unrestricted `any` modules. New releases of the related packages are not required from npm until they are actually published.
 
-## Using it with Yeoman
+Version 5 is a major release because generated projects now contain TypeScript and use a two-stage TypeScript/esbuild pipeline. Use Node.js 24 for development and CI. Existing generated sites are not changed automatically: migrate their script files, copy the new build configuration, and resolve strict type errors before deploying. The small `generators/app/index.js` file is only Yeoman's discovery bridge to compiled TypeScript.
 
-Install as a node module:
+The generated project includes its own README. Full Bootstrap CSS remains included. Old inactive Gulp and Karma configuration has been removed; all historical share-URL assertions now run in the active Node test suite.
 
-```
-npm install generator-white-label -g;
-```
+### Sample utility reference
 
-Then in an empty directory:
+| Module | Functionality and example |
+| --- | --- |
+| `utility/ajax.ts` | `getScript('/sdk.js')` appends an asynchronous script; call it only when needed. |
+| `utility/form.ts` | Read multiselect values, select or find an option, decorate/split metadata, and build named options: `buildOptions([{id: 1, name: 'Ada'}], 1)`. Metadata helpers mutate their supplied arrays. |
+| `utility/string.ts` | Parse trusted HTML, read query values, format local dates, numbers and USD currency, and create phone/email links: `formatCurrency(12.5)` returns `$12.50`. `getQueryStringParamater` retains its historical spelling. |
+| `utility/share.ts` | Construct encoded Facebook, Twitter, LinkedIn and email URLs. Missing required values return `false`. Twitter retains its legacy 140-character rule; Google Plus support is a deprecated URL formatter for a discontinued service. |
+| `utility/regex.ts` | Legacy presentation-validation expressions for dates, passwords, phone numbers, ZIP codes, length and currency. These are not substitutes for server validation or a modern password policy. |
+| `model/user.ts` | An extendable observable object model. Country/state singletons contain the bundled JSON data. The global model starts with local URL defaults; the build separately writes deployment settings to `assets/data/config.json`. |
+| `api/facebook.ts`, `api/youtube.ts` | Optional SDK adapters that emit readiness events through the shared mediator. They are tested with local browser doubles, not live provider accounts. Review provider configuration before enabling them in a real site. |
+| `view/default.tsx` | A React greeting component: `<HelloMessage name="Ada" />`. |
+| `view/toolkit/youtube-player-1.ts` | An extension skeleton for a concrete player, with the legacy `removeListners` hook retained. |
 
+### Verification and coverage
+
+```sh
+npm ci --ignore-scripts
+npm run typecheck
+npm test
+npm run coverage
+npm pack --dry-run
 ```
-yo white-label;
-```
 
-Learn more about Yeoman here: https://yeoman.io
+`npm test` builds the code, checks TypeScript consumer examples against the emitted declarations, and runs the tests. `npm run coverage` additionally enforces **100% statements, branches, functions, and lines for each implementation file**. Unexecuted implementation files count toward the result; declaration-only files contain no executable code and are excluded. Reports are written to `coverage`, including `lcov.info` for coverage viewers. CI runs the same gate and checks committed build output for drift.
+
+Tests exercise the compiled JavaScript interface used by downstream callers. Coverage is an execution metric, not proof that all possible inputs or external integrations are correct. Tests for third-party SDKs use local doubles. No live provider requests are needed.
+
+To undo this migration, revert its commit and run `npm ci` from the restored lockfile. No npm release, database migration, or production deployment is performed by these development changes.

package/app/404.hbs

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html id="error-404" lang="en-US" dir="ltr">
+    {{> element/head}}
+    <body itemscope itemtype="http://schema.org/WebPage">
+        <div id="wrapper">
+            <main id="main" tabindex="-1" class="container">
+                <p>Sorry, but the page you were trying to view does not exist.</p>
+            </main>
+        </div>
+        {{#if scripts.global}}
+        {{> element/script script=scripts.global}}
+        {{/if}}
+        {{#if scripts.section}}
+        {{> element/script script=scripts.section}}
+        {{/if}}
+        {{#if scripts.page}}
+        {{> element/script script=scripts.page}}
+        {{/if}}
+    </body>
+</html>

package/app/README.md

@@ -0,0 +1,19 @@
+# Your white-label site
+
+This site uses TypeScript for application code, Handlebars for pages, and Sass plus full Bootstrap CSS for styling.
+
+## Start developing
+
+Use Node.js 24. Run `npm install`, then `npm run typecheck` and `npm run build`. The build output is `_deploy`; serve that directory with your preferred static server. `npm test` runs the generated site's build check. The generator repository has the broader unit and coverage suites; add application-specific tests as your site grows.
+
+Edit `.ts` files under `app/assets/script`, and use `.tsx` for React components. Keep `.js` extensions in relative imports, for example `import User from './model/user.js'`. TypeScript resolves the source and emits valid JavaScript imports. Do not edit `dist`, which is generated by the compiler.
+
+Pages live in `app/*.hbs`, partials in `app/assets/markup`, and page data in `app/assets/data/view`. Add shared styles in `app/assets/style`. The full Bootstrap stylesheet is included before the project styles.
+
+```sh
+npm run build -- --version=release-1 --production=true
+```
+
+Optional flags are `--www`, `--cdn`, and `--service`. Their defaults are `/`, `/`, and `/service-endpoint`. The version selects `_deploy/release/<version>/assets`; without a version, the current timestamp is used. Each build replaces `_deploy`.
+
+Document new functions with JSDoc comments explaining behavior, parameters, return values, and meaningful errors. Keep strict type checking enabled. Templates accept trusted HTML, so validate or escape external content before rendering it. Optional SDK adapters need real provider configuration before use.

package/app/assets/data/view/toolkit/colors.json

@@ -0,0 +1,17 @@
+{
+    "title":"Colors - Toolkit",
+    "webRepo": "https://github.com/bshack/white-label",
+    "styles":{
+        "all":{
+            "global":"assets/style/global.css",
+            "section":"assets/style/toolkit.css"
+        },
+        "print":{
+            "global":"assets/style/print.css"
+        }
+    },
+    "scripts":{
+        "global":"assets/script/global.compiled.js",
+        "section":"assets/script/toolkit.compiled.js"
+    }
+}

package/app/assets/data/view/toolkit/components.json

@@ -0,0 +1,39 @@
+{
+    "title":"Components - Toolkit",
+    "webRepo": "https://github.com/bshack/white-label",
+    "styles":{
+        "all":{
+            "global":"assets/style/global.css",
+            "section":"assets/style/toolkit.css"
+        },
+        "print":{
+            "global":"assets/style/print.css"
+        }
+    },
+    "accessible-ajax-1":"New content has been added to the page, now the screen reader will read it.",
+    "select-1":{
+        "data":[
+            {
+                "value":"",
+                "name":"choose",
+                "selected":true
+            },
+            {
+                "value":"option-1",
+                "name":"car"
+            },
+            {
+                "value":"option-2",
+                "name":"truck"
+            },
+            {
+                "value":"option-3",
+                "name":"suv"
+            }
+        ]
+    },
+    "scripts":{
+        "global":"assets/script/global.compiled.js",
+        "section":"assets/script/toolkit.compiled.js"
+    }
+}

package/app/assets/data/view/toolkit/elements.json

@@ -0,0 +1,119 @@
+{
+    "title":"Elements - Toolkit",
+    "webRepo": "https://github.com/bshack/white-label",
+    "styles":{
+        "all":{
+            "global":"assets/style/global.css",
+            "section":"assets/style/toolkit.css"
+        },
+        "print":{
+            "global":"assets/style/print.css"
+        }
+    },
+    "elements":{
+        "list-1":{
+            "items":[
+                {
+                    "text":"eggs"
+                },
+                {
+                    "text":"milk"
+                },
+                {
+                    "text":"flour"
+                }
+            ]
+        },
+        "table-1":{
+            "caption":"percent of people in the group",
+            "head":[
+                {
+                    "text":""
+                },
+                {
+                    "text":"males"
+                },
+                {
+                    "text":"females"
+                }
+            ],
+            "body":[
+                [
+                    {
+                        "text":"decided",
+                        "isHead":true
+                    },
+                    {
+                        "text":"50%"
+                    },
+                    {
+                        "text":"25%"
+                    }
+                ],
+                [
+                    {
+                        "text":"undecided",
+                        "isHead":true
+                    },
+                    {
+                        "text":"25%"
+                    },
+                    {
+                        "text":"50%"
+                    }
+                ],
+                [
+                    {
+                        "text":"did not respond",
+                        "isHead":true
+                    },
+                    {
+                        "text":"25%"
+                    },
+                    {
+                        "text":"25%"
+                    }
+                ]
+            ],
+            "foot":[
+                [
+                    {
+                        "text":"totals",
+                        "isHead":true
+                    },
+                    {
+                        "text":"100%"
+                    },
+                    {
+                        "text":"100%"
+                    }
+                ]
+            ]
+        },
+        "select-1":{
+            "data":[
+                {
+                    "value":"",
+                    "name":"choose",
+                    "selected":true
+                },
+                {
+                    "value":"option-1",
+                    "name":"car"
+                },
+                {
+                    "value":"option-2",
+                    "name":"truck"
+                },
+                {
+                    "value":"option-3",
+                    "name":"suv"
+                }
+            ]
+        }
+    },
+    "scripts":{
+        "global":"assets/script/global.compiled.js",
+        "section":"assets/script/toolkit.compiled.js"
+    }
+}

package/app/assets/data/view/toolkit/grids.json

@@ -0,0 +1,17 @@
+{
+    "title":"Grids - Toolkit",
+    "webRepo": "https://github.com/bshack/white-label",
+    "styles":{
+        "all":{
+            "global":"assets/style/global.css",
+            "section":"assets/style/toolkit.css"
+        },
+        "print":{
+            "global":"assets/style/print.css"
+        }
+    },
+    "scripts":{
+        "global":"assets/script/global.compiled.js",
+        "section":"assets/script/toolkit.compiled.js"
+    }
+}

package/app/assets/data/view/toolkit/icons.json

@@ -0,0 +1,17 @@
+{
+    "title":"Icons - Toolkit",
+    "webRepo": "https://github.com/bshack/white-label",
+    "styles":{
+        "all":{
+            "global":"assets/style/global.css",
+            "section":"assets/style/toolkit.css"
+        },
+        "print":{
+            "global":"assets/style/print.css"
+        }
+    },
+    "scripts":{
+        "global":"assets/script/global.compiled.js",
+        "section":"assets/script/toolkit.compiled.js"
+    }
+}

package/app/assets/data/view/toolkit/index.json

@@ -0,0 +1,17 @@
+{
+    "title":"Toolkit",
+    "webRepo": "https://github.com/bshack/white-label",
+    "styles":{
+        "all":{
+            "global":"assets/style/global.css",
+            "section":"assets/style/toolkit.css"
+        },
+        "print":{
+            "global":"assets/style/print.css"
+        }
+    },
+    "scripts":{
+        "global":"assets/script/global.compiled.js",
+        "section":"assets/script/toolkit.compiled.js"
+    }
+}

package/app/assets/data/view/toolkit/type.json

@@ -0,0 +1,17 @@
+{
+    "title":"Type - Toolkit",
+    "webRepo": "https://github.com/bshack/white-label",
+    "styles":{
+        "all":{
+            "global":"assets/style/global.css",
+            "section":"assets/style/toolkit.css"
+        },
+        "print":{
+            "global":"assets/style/print.css"
+        }
+    },
+    "scripts":{
+        "global":"assets/script/global.compiled.js",
+        "section":"assets/script/toolkit.compiled.js"
+    }
+}