@chassis-ui/docs 0.7.0 → 0.9.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @chassis-ui/docs
 
+## 0.9.0-next.0
+
+### Minor Changes
+
+- **Breaking.** The package needs `@chassis-ui/css` 0.10.0 or later: the peer range was `>=0.6.0`. css 0.10 names the font families by their job and holds every text role in one group, and it removes the old Sass names without a deprecation step, so the styles of the package read `$font-lead` in place of `$font-context-lead`, and the footer and the docs sidebar use `.font-h6` and `.font-h5` in place of `.h6` and `.h5`, which css 0.10 deprecates. The roles keep their values, so the pages look as before. css 0.10 reads its tokens from the `@chassis-ui/tokens` that a site installs, which must be 0.10 too. See [UPGRADING.md](https://github.com/chassis-ui/website/blob/main/packages/docs/UPGRADING.md#from-08-to-09) for the dependencies and the names to replace in a site's own pages and styles: `.h1` to `.h6`, `.font-text`, the `--cx-*-text-*` and `--cx-*-html-*` properties and the `$font-context-*` maps.
+
+## 0.8.0
+
+### Minor Changes
+
+- **Breaking.** The pages load their fonts from the site's own static files, no longer from Google Fonts. `Head.astro` links `fonts/text.css`, `fonts/display.css` and `fonts/code.css` under the static path, `/static/` by default, in place of the Google Fonts stylesheet and the `preconnect` links to `fonts.googleapis.com` and `fonts.gstatic.com`. The three stylesheets and the font files they load are in the docs build of `chassis-assets`, which a site copies into `static/` already. A site moves its `vendor/assets` submodule to `acb5d2e` of `app/docs` or later, with `pnpm sync-submodules`: there the stylesheets declare Inter, Archivo Narrow and Fira Code as variable fonts, with every weight the styles use. With a commit before `77912ed` they declare four weights of each family. The Inter of the assets has an optical size axis, which the font of Google Fonts had not, and a browser follows it: text above 14 pixels is narrower, 7% at 57 pixels. A site keeps the look it had by building the assets with `--subset` of `chassis-docs vendor`, which fixes the axis at 14 from `acb5d2e` on, or by setting `font-optical-sizing: none` in its styles. A site that does not copy the docs build provides the three stylesheets itself.
+- `chassis-docs vendor` and `chassis-docs sync-submodules` take `--subset <range>`, repeatable, and `--split` or `--no-split` with it. With `--subset` the fonts of the docs build of `chassis-assets` are written with the characters of the ranges only, such as `--subset latin --subset latin-ext`, and the optical size axis of Inter is fixed at 14, as `chassis-assets` sets it for the `chassis` brand. With `--split` each font is also written in a file per range, and its stylesheet names them with a `unicode-range`, so a page loads a range only when it has a character of it; without `--split` and `--no-split` the setting of `chassis-assets` decides, which is one file. With the two ranges and the split, a page in English loads `text-latin.woff2`, 69 KB, where the whole `text.woff2` is 349 KB, and `code-latin.woff2`, 43 KB, where `code.woff2` is 109 KB. A character outside the ranges is drawn with the next font of the font stack. With `--subset` the commands run `pnpm install --filter ./packages/assets --prod` in the submodule, in place of `pnpm install --ignore-workspace`, since the build loads a package to subset a font. The options need `vendor/assets` at `acb5d2e` of `app/docs` or later. Without them nothing changes.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -10,7 +10,7 @@
 
 > [!NOTE] This package is developed inside the [`chassis-website`](https://github.com/chassis-ui/website) monorepo at `packages/docs/` and published to npm. Source, issues, and pull requests live in that repository.
 
-Coming from 0.5? See [UPGRADING.md](UPGRADING.md).
+Coming from an earlier version? See [UPGRADING.md](UPGRADING.md).
 
 ## Installation
 
@@ -23,7 +23,7 @@ pnpm add @chassis-ui/docs
 ```json
 {
   "@astrojs/markdown-remark": "^7.0.0",
-  "@chassis-ui/css": ">=0.6.0",
+  "@chassis-ui/css": ">=0.10.0-next.0",
   "@pagefind/component-ui": "^1.0.0",
   "@shikijs/transformers": "^4.3.1",
   "astro": "^7.0.0",
@@ -184,18 +184,43 @@ export const collections = {
 
 The layouts link to files under `/static/`, which the site puts into `static/` of its `public` directory:
 
-| URL                                                                  | From                                      |
-| -------------------------------------------------------------------- | ----------------------------------------- |
-| `/static/css/chassis.css`, `/static/css/chassis.min.css`             | the `dist` folder of `@chassis-ui/css`    |
-| `/static/icons/chassis-icons.svg`, `/static/icons/chassis-icons.css` | the `icons` folder of `@chassis-ui/icons` |
-| `/static/images/*`: logo, favicons, social image                     | the docs build of `chassis-assets`        |
+| URL                                                                                                                                | From                                                     |
+| ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `/static/css/chassis.css`, `/static/css/chassis.min.css`                                                                           | the `dist` folder of `@chassis-ui/css`                   |
+| `/static/icons/chassis-icons.svg`, `/static/icons/chassis-icons.css`                                                               | the `icons` folder of `@chassis-ui/icons`                |
+| `/static/images/site-logo.svg`, the logo of the navigation bar and the footer                                                      | the docs build of `chassis-assets`                       |
+| `/static/images/favicon.png`, `favicon-16x16.png`, `favicon-32x32.png` and `apple-touch-icon.png`                                  | the docs build of `chassis-assets`                       |
+| `/static/images/social-image.png`, the image of a page without a `thumbnail`. The build reads its size, and fails without the file | the docs build of `chassis-assets`                       |
+| `/static/fonts/text.css`, `/static/fonts/display.css`, `/static/fonts/code.css`, and the font files they load                      | the docs build of `chassis-assets`                       |
+| `/static/images/manifest.json`, the web app manifest                                                                               | the site itself. The starter has one in `static/images/` |
 
 `chassis-docs vendor` builds the docs build of `chassis-assets` in the `vendor/assets` submodule. See [Commands](#commands).
 
+Nothing else of the docs build is read by the package. A site copies the whole build into `static/`, and its own pages may read more of it.
+
 These helpers find the folders, whether `node_modules` is in the site's root or in the root of the repository: `getChassisCSSFsPath()`, `getChassisIconsFsPath()`, `getChassisAssetsFsPath()` and `getChassisTokensFsPath()`. Each takes `{ root, dir }`.
 
 A site that type-checks with `astro check` declares the `@chassis-ui/css` module, which has no types: `declare module '@chassis-ui/css'`.
 
+#### What the Chassis sites read from the docs build
+
+The sites of the Chassis projects read these files besides, by name, from the docs build of the `chassis` brand:
+
+| File of the docs build                                                   | Read by                                                                                                         |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `icons/cx-sprite.svg`                                                    | The home page of each of the seven sites, which imports it. The build fails without it                          |
+| `images/apple-touch-icon.png`, `images/favicon.png`                      | Each of the seven sites, which copies them to `/apple-touch-icon.png` and `/favicon.ico`                        |
+| `images/android-chrome-192x192.png`, `images/android-chrome-512x512.png` | The `manifest.json` of each of the seven sites                                                                  |
+| `images/home/`                                                           | The home page of the website. The home page of chassis-tokens reads `comp-gallery-*` of it                      |
+| `images/logo/chassis-{logo,icon}-{brand,white}-banner.svg`               | The about page of the website                                                                                   |
+| `images/social-image.png`                                                | The blog of the website, for a post without an image                                                            |
+| `images/site-logo.svg`                                                   | The examples of the navbar page of chassis-css. The README of `@chassis-ui/react`, by its URL on chassis-ui.com |
+| `images/figma/components/`                                               | The component pages of chassis-figma                                                                            |
+
+The vanilla HTML example, in the `vanilla-example` repository, builds the assets itself from a `vendor/assets` submodule of its own, for the brand of each of its sites, and takes `fonts/text.css`, `fonts/display.css` and `fonts/code.css`, the font files they load, the license of each font and `images/logo/chassis-icon-brand.svg`.
+
+`contracts` in `chassis.checks.json` of `chassis-assets` names the files that a site reads, with the code that reads each, and `pnpm assets:contract` there checks a build against it.
+
 #### A site under a prefix
 
 A site that is served under a path of another host, such as `chassis-ui.com/css`, cannot use `/static/` there: that path belongs to the host's own site. It loads its static files under a path of its own instead:
@@ -292,6 +317,22 @@ The package installs a `chassis-docs` command with the build steps that every Ch
 
 `vendor` and `sync-submodules` work from any folder of the repository. They need Git, Git LFS and pnpm. `sync-submodules --branch <name>`, or the `SUBMODULE_BRANCH` variable, follows another branch.
 
+Both take `--subset <range>`, which writes the fonts of the build with the characters of the range only, so that a page downloads smaller font files. A range is a name that `chassis-assets` knows, such as `latin` or `latin-ext`, or a range written as `U+0370-03FF`, and the option is repeatable:
+
+```json
+{
+  "scripts": {
+    "vendor": "chassis-docs vendor --subset latin --subset latin-ext --split"
+  }
+}
+```
+
+A character outside the ranges is drawn with the next font of the font stack. With the option, the commands install the package of the build in the submodule, `pnpm install --filter ./packages/assets --prod`, in place of `pnpm install --ignore-workspace`: it holds the package that subsets a font.
+
+`--subset` also fixes the axes of a variable font that `chassis-assets` names for the brand: the optical size of Inter at 14, so that text has the width it had with Google Fonts. A site that builds without `--subset` sets `font-optical-sizing: none` in its styles for the same look.
+
+`--split`, with `--subset`, writes each font in a file per range as well, such as `text-latin.woff2` and `text-latin-ext.woff2`, and the stylesheets name them with a `unicode-range`: a page loads the file of a range only when it has a character of it. `--no-split` writes one file per font. Without either, the setting of `chassis-assets` decides, which is one file.
+
 Each command exits with 1 when it fails, so a script or CI job stops there.
 
 ### Validating HTML
@@ -376,6 +417,7 @@ The integration provides five modules: `virtual:chassis-docs/config`, `virtual:c
 
 | `@chassis-ui/docs` | Requires Astro             | Requires `@chassis-ui/css` | Requires Node | Built with                           |
 | ------------------ | -------------------------- | -------------------------- | ------------- | ------------------------------------ |
+| 0.8.0              | `^7.0.0`                   | `>=0.6.0`                  | `>=22.12.0`   | Astro 7.3.5, css 0.7.1, tokens 0.7.0 |
 | 0.7.0              | `^7.0.0`                   | `>=0.6.0`                  | `>=22.12.0`   | Astro 7.3.5, css 0.6.0, tokens 0.6.0 |
 | 0.6.3              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |
 | 0.6.2              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |
@@ -387,7 +429,7 @@ The integration provides five modules: `virtual:chassis-docs/config`, `virtual:c
 | 0.3.0 to 0.3.10    | `^7.0.0`                   | `>=0.3.1` to `>=0.3.4`     | not declared  | not recorded                         |
 | 0.1.0 to 0.2.0     | `^5.0.0`, 0.1.0–0.1.1 `^4` | not declared               | not declared  | not recorded                         |
 
-`@chassis-ui/tokens` is not a dependency of the package. The styles take the design tokens that `@chassis-ui/css` carries: css 0.5 is built on tokens 0.5, css 0.4 on tokens 0.4. A site's own version of `@chassis-ui/tokens` matters only when the site puts it on the Sass load path in place of those. Tokens 0.6 renamed and removed some tokens, listed in its changelog.
+`@chassis-ui/tokens` is not a dependency of the package, but a site installs it: the default token source of `@chassis-ui/css`, `scss/vendor/_chassis-tokens.scss`, forwards `@chassis-ui/tokens/dist/web/docs/chassis/main` from the site's `node_modules`, so the site needs the tokens that its css is built on: css 0.10 on tokens 0.10, css 0.7 on tokens 0.7. A site with tokens of its own puts them on the Sass load path in place of those, as [Styles](#styles) says.
 
 Before a release, the [canary](https://github.com/chassis-ui/website/blob/main/build/canary.js) builds the site of each Chassis repository whose range accepts the new version.
 

package/UPGRADING.md

@@ -1,5 +1,128 @@
 # Upgrading @chassis-ui/docs
 
+## From 0.8 to 0.9
+
+0.9.0 needs `@chassis-ui/css` 0.10.0 or later. css 0.10 names the font families by their
+job, `ui` in place of `text`, and holds every text role in one group, so `$font-context-lead`
+is `$font-lead` now, and `.font-h1` to `.font-h6` are the classes of the heading roles. The
+styles and the layouts of the package read the new names.
+
+### 1. Update the dependencies
+
+```sh
+pnpm add -D @chassis-ui/docs@^0.9.0 @chassis-ui/css@^0.10.0 @chassis-ui/tokens@^0.10.0
+```
+
+The default token source of css, `scss/vendor/_chassis-tokens.scss`, forwards the
+`@chassis-ui/tokens` that your site installs, and css 0.10 reads tokens that only tokens 0.10
+has, so the three move together. css 0.10.0 has changes of its own. Read its
+[changelog](https://github.com/chassis-ui/css/blob/main/packages/css/CHANGELOG.md) first.
+
+### 2. Rename the typography names in your own pages and styles
+
+css 0.10 keeps `.h1` to `.h6`, `.font-text` and `--cx-font-family-text` in this minor as
+deprecated names, so a site builds and looks as before without this step. The next breaking
+minor of css removes them. The other old names are gone in css 0.10.
+
+| Old                                                                                                      | New                                                                                                                    |
+| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `.h1` to `.h6`                                                                                           | `.font-h1` to `.font-h6`                                                                                               |
+| `.font-text`                                                                                             | `.font-ui`                                                                                                             |
+| `--cx-font-family-text`                                                                                  | `--cx-font-family-ui`                                                                                                  |
+| `--cx-font-size-text-lg`, `--cx-line-height-text-lg`, `--cx-font-weight-text-strong` and the other steps | `--cx-font-size-ui-lg`, `--cx-line-height-ui-lg`, `--cx-font-weight-ui-strong`                                         |
+| `--cx-font-size-html-h1`, `--cx-line-height-html-h1` and the other `--cx-*-html-*` properties            | `--cx-font-size-h1`, `--cx-line-height-h1`; `--cx-font-family-heading` and `--cx-font-weight-heading` for the headings |
+| `.font-display.font-lg` and the other display sizes                                                      | removed: a text role such as `.font-h2`, or `.font-prose.font-lg`                                                      |
+| `$font-context-lead`, `$font-context-title-large` and the other `$font-context-*` maps                   | `$font-lead`, `$font-title-large` and the others                                                                       |
+| `$font-family-text`                                                                                      | `$font-family-ui`                                                                                                      |
+
+### What changes in the package
+
+- **The footer and the docs sidebar use `.font-h6` and `.font-h5`.** The three column
+  titles of the footer and the "On this page" label were `h6`, the section titles of the
+  sidebar `h5`. A rule of your own that matched them by class matches the new class.
+- **`.cxd-subtitle` reads `$font-lead`,** the role that `$font-context-lead` was.
+
+### Check the result
+
+Build the site before and after the upgrade and compare the pages in a browser. The roles
+keep their values, so nothing of the package moves.
+
+## From 0.7 to 0.8
+
+0.8.0 loads the fonts from the site's own static files, no longer from Google Fonts. The
+head of every page links `fonts/text.css`, `fonts/display.css` and `fonts/code.css` under
+the static path, `/static/` by default. The three stylesheets and the font files they load
+are in the docs build of `chassis-assets`, which a site copies into `static/` already.
+
+### 1. Update the dependency
+
+```sh
+pnpm add -D @chassis-ui/docs@^0.8.0
+```
+
+### 2. Move the `vendor/assets` submodule
+
+```sh
+pnpm sync-submodules
+```
+
+The pages need `vendor/assets` at `acb5d2e` of `app/docs` or later: there the stylesheets
+declare Inter, Archivo Narrow and Fira Code as variable fonts, with every weight the styles
+use. With a commit before `77912ed` they declare four weights of each family. Commit the
+new pointer.
+
+A site that does not copy the docs build provides the three stylesheets itself, at the
+same paths.
+
+### 3. Subset the fonts
+
+Add `--subset` and `--split` to the `vendor` and `sync-submodules` scripts:
+
+```json
+{
+  "scripts": {
+    "vendor": "chassis-docs vendor --subset latin --subset latin-ext --split",
+    "sync-submodules": "chassis-docs sync-submodules --subset latin --subset latin-ext --split"
+  }
+}
+```
+
+The step is optional, and it does two things:
+
+- The fonts hold the characters of the ranges only, each range in a file of its own that a
+  page loads when it has a character of it. A page in English loads `text-latin.woff2`,
+  69 KB, where the whole `text.woff2` is 349 KB. A character outside the ranges is drawn
+  with the next font of the font stack, so name the range of every script your pages use:
+  a name that `chassis-assets` knows, or a range written as `U+0370-03FF`. See
+  [Commands](README.md#commands) in the README.
+- The optical size axis of Inter is fixed at 14. See "What changes on the pages" below.
+
+With `--subset` the commands install the package of the build in the submodule, which
+holds the package that subsets a font.
+
+### 4. Remove Google Fonts from your policy and your privacy page
+
+No page requests `fonts.googleapis.com` or `fonts.gstatic.com` any more. Remove the two
+hosts from a content security policy of your own, and a sentence about Google Fonts from a
+privacy page. The sites under chassis-ui.com have the policy of the website, which no
+longer allows the two hosts.
+
+### What changes on the pages
+
+- **Inter follows its optical size axis.** The Inter of the assets has the axis, which the
+  font of Google Fonts had not, and a browser follows it: text above 14 pixels is narrower,
+  7% at 57 pixels. Step 3 fixes the axis at 14, so text has the width it had. A site that
+  builds without `--subset` sets `font-optical-sizing: none` in its styles for the same
+  look.
+- **Inter has an italic file.** Italic text was drawn by slanting the upright font.
+- **The head has no `preconnect` links** to the two hosts of Google Fonts.
+
+### Check the result
+
+Build the site before and after the upgrade and compare the pages in a browser. With
+step 3 the text keeps its width, so nothing moves. Check in the network panel that no
+request goes to `fonts.googleapis.com` or `fonts.gstatic.com`.
+
 ## From 0.6 to 0.7
 
 0.7.0 needs `@chassis-ui/css` 0.6.0 or later. The layouts use the CSS grid of that version,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chassis-ui/docs",
   "description": "Shared Astro components and layouts for Chassis documentation sites.",
-  "version": "0.7.0",
+  "version": "0.9.0-next.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -65,12 +65,9 @@
   "engines": {
     "node": ">=22.12.0"
   },
-  "scripts": {
-    "astro": "astro"
-  },
   "peerDependencies": {
     "@astrojs/markdown-remark": "^7.0.0",
-    "@chassis-ui/css": ">=0.6.0",
+    "@chassis-ui/css": ">=0.10.0-next.0",
     "@pagefind/component-ui": "^1.0.0",
     "@shikijs/transformers": "^4.3.1",
     "astro": "^7.0.0",
@@ -95,8 +92,8 @@
     "clipboard": "^2.0.11",
     "github-slugger": "^2.0.0",
     "image-size": "^2.0.4",
-    "js-yaml": "^5.4.2",
-    "mdast-util-from-markdown": "^2.0.3",
+    "js-yaml": "^5.4.3",
+    "mdast-util-from-markdown": "^2.1.0",
     "mdast-util-mdx-jsx": "^3.2.0",
     "mdast-util-to-string": "^4.0.0",
     "medium-zoom": "^1.1.0",
@@ -106,16 +103,19 @@
     "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
-    "@astrojs/markdown-remark": "^7.3.1",
-    "@chassis-ui/css": "^0.6.0",
+    "@astrojs/markdown-remark": "^7.3.2",
+    "@chassis-ui/css": "0.10.0-next.0",
     "@pagefind/component-ui": "^1.5.2",
     "@shikijs/transformers": "^4.5.0",
-    "astro": "^7.3.5",
-    "html-validate": "^11.16.1",
+    "astro": "^7.3.8",
+    "html-validate": "^11.16.2",
     "rehype-autolink-headings": "^7.1.0",
     "remark-mdx": "^3.1.1",
     "sass": "^1.105.1",
     "vfile": "^6.0.3",
-    "vnu-jar": "^26.10.2"
+    "vnu-jar": "^26.10.9"
+  },
+  "scripts": {
+    "astro": "astro"
   }
-}
+}

package/src/cli/assets.js

@@ -11,6 +11,9 @@ export const ASSETS_OUTPUT = 'dist/web/docs/chassis'
 /** The branch of chassis-assets that the docs sites follow. */
 export const DEFAULT_BRANCH = 'app/docs'
 
+/** The package of the build inside the submodule, which names the packages its options load. */
+export const ASSETS_PACKAGE = './packages/assets'
+
 /**
  * The root of the repository that contains the working directory, so that the commands
  * work from a site's folder too.
@@ -22,24 +25,34 @@ function repositoryRoot(run) {
 
 /**
  * Checks out `vendor/assets` at the commit that the repository pins, and builds it.
- * @param {{ root?: string, run?: typeof defaultRun }} [options]
+ * @param {{ root?: string, subset?: string[], split?: boolean, run?: typeof defaultRun }} [options]
  */
-export function buildAssets({ run = defaultRun, root = repositoryRoot(run) } = {}) {
+export function buildAssets({
+  run = defaultRun,
+  root = repositoryRoot(run),
+  subset = [],
+  split
+} = {}) {
+  const fonts = fontOptions(subset, split)
+
   log(`Building ${ASSETS_PATH} at the pinned commit`)
   run('git', ['submodule', 'update', '--init', ASSETS_PATH], { cwd: root })
-  buildCheckout(root, run)
+  buildCheckout(root, run, fonts)
 }
 
 /**
  * Moves `vendor/assets` to the latest commit of `branch`, and builds it. The repository
  * then has a changed submodule pointer to commit.
- * @param {{ root?: string, branch?: string, run?: typeof defaultRun }} [options]
+ * @param {{ root?: string, branch?: string, subset?: string[], split?: boolean, run?: typeof defaultRun }} [options]
  */
 export function syncAssets({
   run = defaultRun,
   root = repositoryRoot(run),
-  branch = DEFAULT_BRANCH
+  branch = DEFAULT_BRANCH,
+  subset = [],
+  split
 } = {}) {
+  const fonts = fontOptions(subset, split)
   const dir = path.join(root, ASSETS_PATH)
   const git = (args, quiet = true) => run('git', args, { cwd: dir, quiet })
 
@@ -68,7 +81,7 @@ export function syncAssets({
   }
 
   git(['pull', '--ff-only', 'origin', branch])
-  buildCheckout(root, run)
+  buildCheckout(root, run, fonts)
 
   const commit = git(['rev-parse', '--short', 'HEAD']).trim()
   const moved = run('git', ['status', '--porcelain', '--', ASSETS_PATH], {
@@ -92,14 +105,49 @@ function hasLocalBranch(git, branch) {
   }
 }
 
-function buildCheckout(root, run) {
+/**
+ * The options of the build for the fonts: the ranges of `--subset`, then `--split` or
+ * `--no-split` when the site decides it, and nothing when the fonts stay whole. Without
+ * either of the two, the build takes `split` of `chassis.subset` of chassis-assets.
+ * @param {string[]} subset
+ * @param {boolean} [split]
+ * @returns {string[]}
+ */
+function fontOptions(subset, split) {
+  if (subset.length === 0) {
+    if (split !== undefined) {
+      throw new CommandError('--split and --no-split need --subset: a font is split by its ranges.')
+    }
+
+    return []
+  }
+
+  const decided = split === undefined ? [] : [split ? '--split' : '--no-split']
+
+  return ['--subset', ...subset, ...decided]
+}
+
+function buildCheckout(root, run, fonts = []) {
   const dir = path.join(root, ASSETS_PATH)
 
   // The images are stored with Git LFS. Without it they are pointer files.
   run('git', ['lfs', 'install', '--local'], { cwd: dir, quiet: true })
   run('git', ['lfs', 'pull'], { cwd: dir })
-  run('pnpm', ['install', '--ignore-workspace'], { cwd: dir })
-  run('pnpm', ['assets:site'], { cwd: dir })
+
+  if (fonts.length > 0) {
+    // The subsetter is a package that the build loads, so the package of the build is
+    // installed, without the tools of its tests. Where an install without the workspace
+    // ran before, pnpm removes its modules first, and would ask.
+    run(
+      'pnpm',
+      ['install', '--filter', ASSETS_PACKAGE, '--prod', '--config.confirmModulesPurge=false'],
+      { cwd: dir }
+    )
+    run('pnpm', ['assets:site', ...fonts], { cwd: dir })
+  } else {
+    run('pnpm', ['install', '--ignore-workspace'], { cwd: dir })
+    run('pnpm', ['assets:site'], { cwd: dir })
+  }
 
   const output = path.join(dir, ASSETS_OUTPUT)
 

package/src/cli/main.js

@@ -14,6 +14,14 @@ Commands:
   vendor                 Build vendor/assets at the commit that the repository pins
   sync-submodules        Move vendor/assets to the latest commit of a branch, and build it
       --branch <name>    The branch of chassis-assets (default: $SUBMODULE_BRANCH or ${DEFAULT_BRANCH})
+
+  Both builds:
+      --subset <range>   Write the web fonts with the characters of a range only, such as
+                         latin or U+0370-03FF. Repeatable
+      --split            With --subset, write a font in a file per range, which a page
+                         loads when it has a character of the range
+      --no-split         With --subset, write a font in one file (default: the setting
+                         of chassis-assets)
   html-validate [paths]  Validate the HTML files in paths (default: _site) with html-validate
       --config <file>    A JSON config of html-validate, added to the defaults
   vnu [paths]            Validate paths (default: _site) with the Nu Html Checker. Needs Java
@@ -27,6 +35,21 @@ Commands:
 
 html-validate and vnu need the html-validate and vnu-jar packages in the site's devDependencies.`
 
+const fontOptions = {
+  subset: { type: 'string', multiple: true },
+  split: { type: 'boolean' },
+  'no-split': { type: 'boolean' }
+}
+
+// `--split` is true and `--no-split` is false. Neither leaves the decision to chassis-assets.
+function splitOf(values) {
+  if (values.split && values['no-split']) {
+    throw new CommandError('Give --split or --no-split, not both.')
+  }
+
+  return values.split ? true : values['no-split'] ? false : undefined
+}
+
 const ignoreOptions = {
   ignore: { type: 'string', multiple: true },
   'no-default-ignore': { type: 'boolean' }
@@ -39,16 +62,20 @@ function ignoresOf(values, paths) {
 
 const commands = {
   vendor: {
-    options: {},
-    run: () => {
-      buildAssets()
+    options: { ...fontOptions },
+    run: ({ values }) => {
+      buildAssets({ subset: values.subset, split: splitOf(values) })
       return 0
     }
   },
   'sync-submodules': {
-    options: { branch: { type: 'string' } },
+    options: { branch: { type: 'string' }, ...fontOptions },
     run: ({ values }) => {
-      syncAssets({ branch: values.branch ?? process.env.SUBMODULE_BRANCH ?? DEFAULT_BRANCH })
+      syncAssets({
+        branch: values.branch ?? process.env.SUBMODULE_BRANCH ?? DEFAULT_BRANCH,
+        subset: values.subset,
+        split: splitOf(values)
+      })
       return 0
     }
   },