@rblabs-dev/axiom 1.2.1 → 1.2.3

package/README.md

@@ -23,7 +23,8 @@ This README covers installing the package and wiring it into an app.
 npm install @rblabs-dev/axiom @angular/material@<major> @angular/cdk@<major>
 ```
 
-Inter Variable comes with the package (`@fontsource-variable/inter`). Nothing loads from a CDN.
+Inter Variable ships in the package's `fonts/` folder, and the app serves it (step 3). Nothing loads
+from a CDN.
 
 ## Set up an app
 
@@ -54,7 +55,25 @@ Run these steps from the folder that holds the app's `angular.json`.
    `NOTICE.txt`. `angular.json` must serve `public/` (`{ "glob": "**/*", "input": "public" }`, the
    Angular CLI default); no other asset entry is needed.
 
-3. **Global styles.** Call the entry mixin once, at the top of `src/styles.scss`, with the subset's
+3. **Inter.** Serve the package's Inter files at `/fonts/` with this entry in the build `assets` of
+   `angular.json`:
+
+   ```json
+   { "glob": "*.woff2", "input": "node_modules/@rblabs-dev/axiom/fonts", "output": "fonts" }
+   ```
+
+   Then preload the Latin file in the `<head>` of `src/index.html`:
+
+   ```html
+   <link rel="preload" href="/fonts/inter-latin-wght-normal.woff2" as="font" type="font/woff2" crossorigin />
+   ```
+
+   The kit declares Inter with `font-display: optional`, so a first visit gets Inter only if the
+   file arrives within about 100 ms of the first render; the preload starts it with the HTML instead
+   of after the global stylesheet. Keep `crossorigin`: without it the browser does not reuse the
+   preloaded file. `axiom verify-production-assets` fails the build when either step is missing.
+
+4. **Global styles.** Call the entry mixin once, at the top of `src/styles.scss`, with the subset's
    file name (later runs of `build:icon-font` update it):
 
    ```scss
@@ -67,7 +86,7 @@ Run these steps from the folder that holds the app's `angular.json`.
    `$scope: '.rb-scope'` applies the kit only inside that class, for an app that still has global
    styles of its own. The module also forwards `rb.below()`, `rb.above()` and `$breakpoints`.
 
-4. **Providers.** In `app.config.ts`:
+5. **Providers.** In `app.config.ts`:
 
    ```ts
    import { provideRbDesignSystem } from '@rblabs-dev/axiom';
@@ -81,7 +100,7 @@ Run these steps from the folder that holds the app's `angular.json`.
    `<mat-icon>` font. `provideRbDesignSystem({ forcedTheme: 'dark' })` keeps an app dark-only
    while it migrates, and `legacyStorageKeys` moves a theme choice stored under an older key.
 
-5. **Showcase route.** Route `/design-system` to the showcase, lazily, so it stays out of the
+6. **Showcase route.** Route `/design-system` to the showcase, lazily, so it stays out of the
    initial bundle:
 
    ```ts
@@ -93,7 +112,7 @@ Run these steps from the folder that holds the app's `angular.json`.
    }
    ```
 
-6. **Favicon and document head.** Write the app's favicon from the brand template, then reference
+7. **Favicon and document head.** Write the app's favicon from the brand template, then reference
    it in `index.html` with the theme colors:
 
    ```bash
@@ -106,7 +125,7 @@ Run these steps from the folder that holds the app's `angular.json`.
    <meta name="theme-color" content="#08111d" media="(prefers-color-scheme: dark)" />
    ```
 
-7. **Build.** `npm run build` builds the app and runs `axiom verify-production-assets`.
+8. **Build.** `npm run build` builds the app and runs `axiom verify-production-assets`.
 
 Then use the components and kit classes in templates:
 
@@ -130,19 +149,26 @@ each pull request needs.
 | `@rblabs-dev/axiom/showcase`           | `DesignSystemShowcaseComponent`, the `/design-system` page                                                                               |
 | `@use '@rblabs-dev/axiom'` (SCSS)      | `rb.design-system()`, `rb.below()`, `rb.above()`, `$breakpoints` and `$version`; emits no CSS until the mixin is called                  |
 | `axiom` (command)                      | The four commands below                                                                                                                  |
+| `fonts/`                               | Inter Variable (Latin and Latin Extended WOFF2) and its license, served by the app at `/fonts/`                                          |
 | `brand/`, `material-symbols-icons.txt` | Brand templates and the kit's icon inventory, read by the commands                                                                       |
 
+Import the TypeScript API from `@rblabs-dev/axiom`. Inside the package, each component, shell and
+brand component is its own secondary entry point (`@rblabs-dev/axiom/panel`, …), so your bundler
+puts it, with the Material code it uses, in the lazy chunk of the routes that use it, and only
+`provideRbDesignSystem()` and the theme service join your initial bundle. Those entry points are
+how the package is laid out, not an API: a release may rename, merge or split them.
+
 ## The `axiom` command
 
 Each command reads the app's source root, `public/` folder and build output from `angular.json`.
 With several applications in one workspace, pass `--project <name>`. `npx axiom help` lists them.
 
-| Command                                                   | What it does                                                                                                                                                  |
-| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `axiom build-icon-font [--output <dir>]`                  | Downloads the Material Symbols subset for the kit's and the app's icons, replaces the previous one in `public/fonts/` and updates its name in `src/**/*.scss` |
-| `axiom build-brand-assets --app <name> [--out-dir <dir>]` | Writes `public/favicon.svg`. With `--og-image <out.svg> --description <text> --domain <host>`, also writes the social preview SVG                             |
-| `axiom verify-production-assets [--scan <dir>]...`        | After a production build, fails on Google Fonts references, a missing favicon or icon font, or an icon used in `src/` that no inventory lists                 |
-| `axiom check-style-literals`                              | Fails on hex, `rgb()` or `hsl()` color literals in `src/**/*.scss` that `style-literals.allowlist.json` does not list                                         |
+| Command                                                   | What it does                                                                                                                                                                      |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `axiom build-icon-font [--output <dir>]`                  | Downloads the Material Symbols subset for the kit's and the app's icons, replaces the previous one in `public/fonts/` and updates its name in `src/**/*.scss`                     |
+| `axiom build-brand-assets --app <name> [--out-dir <dir>]` | Writes `public/favicon.svg`. With `--og-image <out.svg> --description <text> --domain <host>`, also writes the social preview SVG                                                 |
+| `axiom verify-production-assets [--scan <dir>]...`        | After a production build, fails on Google Fonts references, a missing favicon, Inter preload or font file, a missing icon font, or an icon used in `src/` that no inventory lists |
+| `axiom check-style-literals`                              | Fails on hex, `rgb()` or `hsl()` color literals in `src/**/*.scss` that `style-literals.allowlist.json` does not list                                                             |
 
 ## Versions
 
@@ -153,4 +179,4 @@ showcase and `RB_DESIGN_SYSTEM_VERSION` report. Release notes are on the
 ## License
 
 MIT. The icon font that `axiom build-icon-font` downloads is Material Symbols (Apache License 2.0),
-and Inter Variable is licensed under the SIL Open Font License 1.1.
+and Inter Variable, in `fonts/`, is licensed under the SIL Open Font License 1.1 (`fonts/LICENSE`).

package/app-shell/package.json

@@ -0,0 +1,4 @@
+{
+  "module": "../fesm2022/rblabs-dev-axiom-app-shell.mjs",
+  "typings": "../types/rblabs-dev-axiom-app-shell.d.ts"
+}

package/brand-lockup/package.json

@@ -0,0 +1,4 @@
+{
+  "module": "../fesm2022/rblabs-dev-axiom-brand-lockup.mjs",
+  "typings": "../types/rblabs-dev-axiom-brand-lockup.d.ts"
+}

package/central-sign-in/package.json

@@ -0,0 +1,4 @@
+{
+  "module": "../fesm2022/rblabs-dev-axiom-central-sign-in.mjs",
+  "typings": "../types/rblabs-dev-axiom-central-sign-in.d.ts"
+}

package/cli/build-brand-assets.mjs

@@ -8,19 +8,23 @@
 //
 //   ... --og-image <out.svg> --description "<at most 60 characters>" --domain <host>
 //       also writes the filled social preview template to <out.svg>, for export to the app's
-//       public/og-image.png (1200x630). The SVG loads Inter from node_modules, so export it on the
-//       machine that generated it.
+//       public/og-image.png (1200x630). The SVG loads Inter from this package's fonts/ folder, so
+//       export it on the machine that generated it.
 //
 // The output is per-app and lives in the app; commit its public/favicon.svg and og-image.png.
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 
-import { brandDir, parseOptions, relativeToCwd, resolveProject } from './project.mjs';
-
-const require = createRequire(import.meta.url);
+import {
+  brandDir,
+  fontsDir,
+  interFontFiles,
+  parseOptions,
+  relativeToCwd,
+  resolveProject,
+} from './project.mjs';
 
 // Section 12.3. Badge colors exist only in favicons; they are not UI tokens.
 export const RB_APPS = {
@@ -55,15 +59,6 @@ function readTemplate(name) {
   return readFileSync(path.join(brandDir, name), 'utf8');
 }
 
-// The variable Inter file the og-image template embeds, from this package's dependency.
-function interFontPath() {
-  try {
-    return require.resolve('@fontsource-variable/inter/files/inter-latin-wght-normal.woff2');
-  } catch {
-    throw new Error('Cannot find @fontsource-variable/inter; run npm install first.');
-  }
-}
-
 export function run(argv) {
   const options = parseOptions(argv);
   const app = RB_APPS[options.app];
@@ -77,7 +72,6 @@ export function run(argv) {
     ? path.resolve(options['out-dir'])
     : resolveProject(options.project).publicDir;
   if (!existsSync(outDir)) throw new Error(`${relativeToCwd(outDir)} does not exist.`);
-  let interFont;
   if (options['og-image']) {
     if (!description || !domain) {
       throw new Error('--og-image needs --description and --domain.');
@@ -87,7 +81,6 @@ export function run(argv) {
         `--description has ${description.length} characters; the limit is ${maxDescriptionLength}.`,
       );
     }
-    interFont = interFontPath();
   }
 
   const faviconPath = path.join(outDir, 'favicon.svg');
@@ -108,7 +101,8 @@ export function run(argv) {
       appName: app.name,
       description,
       domain,
-      interFontUrl: pathToFileURL(interFont).href,
+      // The Latin file covers the template's text.
+      interFontUrl: pathToFileURL(path.join(fontsDir, interFontFiles[0])).href,
     }),
   );
   console.log(`Wrote ${relativeToCwd(ogPath)}; export it to public/og-image.png at 1200x630.`);

package/cli/project.mjs

@@ -11,6 +11,12 @@ import { fileURLToPath } from 'node:url';
 export const kitDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 export const kitInventoryPath = path.join(kitDir, 'material-symbols-icons.txt');
 export const brandDir = path.join(kitDir, 'brand');
+// The Inter Variable files the kit's @font-face rules load from /fonts/<name> (section 6.1).
+export const fontsDir = path.join(kitDir, 'fonts');
+export const interFontFiles = [
+  'inter-latin-wght-normal.woff2',
+  'inter-latin-ext-wght-normal.woff2',
+];
 
 // Parses `--name value` pairs. Options listed in `repeatable` collect every value in an array.
 export function parseOptions(argv, { repeatable = [] } = {}) {

package/cli/verify-production-assets.mjs

@@ -7,6 +7,9 @@
 //
 // - the built index.html references Google Fonts;
 // - the favicon is missing or not referenced;
+// - the built index.html does not preload /fonts/inter-latin-wght-normal.woff2 (as="font",
+//   type="font/woff2", crossorigin), the build output does not hold the kit's Inter files at
+//   /fonts/ unchanged, or the built stylesheet does not load Inter from there (section 6.1);
 // - the app's public/fonts/ does not hold exactly one Material Symbols subset, the built
 //   stylesheet does not reference it, its name's content hash does not match its bytes, or it
 //   exceeds 16 KB;
@@ -22,7 +25,20 @@ import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 
-import { parseOptions, readIconInventories, relativeToCwd, resolveProject } from './project.mjs';
+import {
+  fontsDir,
+  interFontFiles,
+  parseOptions,
+  readIconInventories,
+  relativeToCwd,
+  resolveProject,
+} from './project.mjs';
+
+const interPreloadUrl = `/fonts/${interFontFiles[0]}`;
+const interPreloadTag = `<link rel="preload" href="${interPreloadUrl}" as="font" type="font/woff2" crossorigin />`;
+
+const linkTagPattern = /<link\b[^>]*>/giu;
+const attributePattern = /([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/gu;
 
 const fontPattern = /^material-symbols-outlined-.+\.woff2$/u;
 const hashedFontPattern = /\.([0-9a-f]{8})\.woff2$/u;
@@ -51,6 +67,33 @@ function listFiles(directory, predicate) {
   return files;
 }
 
+// The attributes of every <link> in an HTML document outside comments, as name → value maps
+// (lowercase names; an attribute without a value maps to '').
+export function linkTags(html) {
+  const markup = html.replace(/<!--[\s\S]*?-->/gu, '');
+  return [...markup.matchAll(linkTagPattern)].map(([tag]) => {
+    const attributes = new Map();
+    for (const match of tag.slice('<link'.length).matchAll(attributePattern)) {
+      attributes.set(match[1].toLowerCase(), match[2] ?? match[3] ?? match[4] ?? '');
+    }
+    return attributes;
+  });
+}
+
+// Whether an HTML document preloads the Latin Inter file so that the kit's @font-face rule reuses
+// the request: same URL, as="font", type="font/woff2" and an anonymous CORS request, which is how
+// browsers fetch fonts.
+export function preloadsInter(html) {
+  return linkTags(html).some(
+    (link) =>
+      link.get('rel')?.toLowerCase().split(/\s+/u).includes('preload') &&
+      link.get('href') === interPreloadUrl &&
+      link.get('as')?.toLowerCase() === 'font' &&
+      link.get('type')?.toLowerCase() === 'font/woff2' &&
+      ['', 'anonymous'].includes(link.get('crossorigin')?.toLowerCase()),
+  );
+}
+
 // Icon names used by one template or component source.
 export function iconNamesInSource(source) {
   const names = new Set();
@@ -97,6 +140,24 @@ export function run(argv) {
   if (!existsSync(path.join(browserDir, 'favicon.svg')))
     fail(`Missing favicon asset in ${relativeToCwd(browserDir)}.`);
 
+  if (!preloadsInter(indexHtml)) {
+    fail(
+      `Production index does not preload Inter. Add to the app's index.html: ${interPreloadTag}`,
+    );
+  }
+  for (const name of interFontFiles) {
+    const interPath = path.join(browserDir, 'fonts', name);
+    if (!existsSync(interPath)) {
+      fail(
+        `Missing ${relativeToCwd(interPath)}. Copy the kit's Inter files with this angular.json ` +
+          'assets entry: { "glob": "*.woff2", "input": "node_modules/@rblabs-dev/axiom/fonts", "output": "fonts" }',
+      );
+    }
+    if (!readFileSync(interPath).equals(readFileSync(path.join(fontsDir, name)))) {
+      fail(`${relativeToCwd(interPath)} differs from the kit's copy; serve the package's file.`);
+    }
+  }
+
   const publicFontsDir = path.join(project.publicDir, 'fonts');
   if (!existsSync(publicFontsDir))
     fail(`Missing ${relativeToCwd(publicFontsDir)}; run axiom build-icon-font.`);
@@ -124,10 +185,14 @@ export function run(argv) {
 
   const stylesheets = readdirSync(browserDir).filter((name) => /^styles-[^/]+\.css$/u.test(name));
   if (stylesheets.length === 0) fail('Missing hashed production stylesheet.');
-  const referenced = stylesheets.some((name) =>
-    readFileSync(path.join(browserDir, name), 'utf8').includes(`/fonts/${fontName}`),
+  const stylesheetSources = stylesheets.map((name) =>
+    readFileSync(path.join(browserDir, name), 'utf8'),
   );
-  if (!referenced) fail(`Production stylesheet does not reference /fonts/${fontName}.`);
+  for (const url of [`/fonts/${fontName}`, interPreloadUrl]) {
+    if (!stylesheetSources.some((source) => source.includes(url))) {
+      fail(`Production stylesheet does not reference ${url}.`);
+    }
+  }
 
   const inventory = new Set(readIconInventories(project).names);
   const scanned = [project.sourceDir, ...options.scan.map((directory) => path.resolve(directory))];
@@ -140,7 +205,7 @@ export function run(argv) {
   }
 
   console.log(
-    `Production asset verification passed: favicon present, ${inventory.size} icon names tracked, ` +
-      `icon font ${fontName} is ${statSync(fontPath).size} bytes.`,
+    `Production asset verification passed: favicon present, Inter preloaded, ` +
+      `${inventory.size} icon names tracked, icon font ${fontName} is ${statSync(fontPath).size} bytes.`,
   );
 }

package/confirm-dialog/package.json

@@ -0,0 +1,4 @@
+{
+  "module": "../fesm2022/rblabs-dev-axiom-confirm-dialog.mjs",
+  "typings": "../types/rblabs-dev-axiom-confirm-dialog.d.ts"
+}

package/core/package.json

@@ -0,0 +1,4 @@
+{
+  "module": "../fesm2022/rblabs-dev-axiom-core.mjs",
+  "typings": "../types/rblabs-dev-axiom-core.d.ts"
+}

package/empty-state/package.json

@@ -0,0 +1,4 @@
+{
+  "module": "../fesm2022/rblabs-dev-axiom-empty-state.mjs",
+  "typings": "../types/rblabs-dev-axiom-empty-state.d.ts"
+}