@chassis-ui/docs 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @chassis-ui/docs
 
+## 0.6.1
+
+### Patch Changes
+
+- A code block can take focus, so that a keyboard can scroll one that is wider than the page. The Google Fonts stylesheet is linked from the head instead of imported by the styles, so the browser requests it with the page, not after the stylesheet that imported it.
+- Google Analytics loads only after the visitor accepts. When `analytics.googleId` is set, production builds show a consent banner at the bottom of the page, and nothing is sent to Google and no cookie is set before the visitor accepts. The choice is kept in `localStorage`, so the sites served from one host share it. The footer has a "Cookie settings" button that opens the banner again, and a "Privacy" link to `/privacy/`. Declining stops Google Analytics and deletes its cookies.
+- The head no longer links `safari-pinned-tab.svg` as a `mask-icon`. The docs build of chassis-assets has no such file, so every page asked for one that returned 404. Safari has used the regular favicon for pinned tabs since version 12.
+- The header and the footer link Chassis React: "React" in the navigation of the header, "React Components" among the docs of the footer and "Chassis React" among its GitHub links. The footer lists the projects in the order of the header. The "Privacy" link and the "Cookie settings" button moved from the last column of the footer to below the license.
+- The package installs a `chassis-docs` command with the build steps that every Chassis site shares, so that a site no longer needs its own copies of them. `chassis-docs vendor` builds the `vendor/assets` submodule at the pinned commit. `chassis-docs sync-submodules` moves it to the latest `app/docs` and builds it, and works on a fresh CI checkout too. `chassis-docs html-validate` and `chassis-docs vnu` validate the built HTML. The two validators need `html-validate` and `vnu-jar`, which are optional peer dependencies. See [Commands](https://github.com/chassis-ui/website/tree/main/packages/docs#commands) in the README.
+- The "Skip to main content" link of the header has a target on every page. `BaseLayout` gives its `<main>` the id `content`, which only the docs layout had set, on its title. A page that fills the `main` slot of `BaseLayout` sets the id on an element of its own.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -34,6 +34,8 @@ pnpm add @chassis-ui/docs
 }
 ```
 
+Two more are optional. They are needed by the [commands](#commands) that validate HTML: `html-validate` `^11.0.0` and `vnu-jar` `>=26.0.0`.
+
 A site also installs `@astrojs/mdx` and the rest of the Chassis stack, `@chassis-ui/tokens` and `@chassis-ui/icons`.
 
 ## Setup
@@ -114,7 +116,7 @@ currentVersion: '0.5.2'
 | `githubOrg`                                   | no       | GitHub organisation name, not a URL. The header links to it                                       |
 | `figmaHandle`                                 | no       | Figma Community handle. The header links to it                                                    |
 | `xUsername`                                   | no       | X handle. Used in the social meta tags                                                            |
-| `analytics.googleId`                          | no       | Google Analytics ID. Loaded in production builds only                                             |
+| `analytics.googleId`                          | no       | Google Analytics ID. In production builds, loaded after the visitor accepts in a consent banner   |
 | `anchors.min`, `anchors.max`                  | no       | Heading levels that get an anchor link. Default 2 to 5                                            |
 | `toc.min`, `toc.max`                          | no       | Heading levels in the table of contents. Default 2 to 6                                           |
 | `sourceDir`                                   | no       | Directory that `file` props are relative to, from the site's root, e.g. `"../css"`. Default `"."` |
@@ -187,6 +189,8 @@ The layouts link to files under `/static/`, which the site puts into its `public
 | `/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`        |
 
+`chassis-docs vendor` builds the docs build of `chassis-assets` in the `vendor/assets` submodule. See [Commands](#commands).
+
 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'`.
@@ -238,6 +242,88 @@ chassisDocs({
 
 Code that runs while Astro loads its configuration uses the library functions of the root entry instead: `loadConfig()`, `loadData()`, `loadSidebar()` and the path helpers.
 
+## Commands
+
+The package installs a `chassis-docs` command with the build steps that every Chassis site shares. Call it from the scripts of `package.json`:
+
+```json
+{
+  "scripts": {
+    "vendor": "chassis-docs vendor",
+    "sync-submodules": "chassis-docs sync-submodules",
+    "lint:html": "chassis-docs html-validate _site",
+    "lint:vnu": "chassis-docs vnu _site"
+  }
+}
+```
+
+| Command                              | What it does                                                                                                                                                        |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chassis-docs vendor`                | Checks out the `vendor/assets` submodule at the commit that the repository pins, pulls its Git LFS files, installs its dependencies and runs its `pnpm assets:site` |
+| `chassis-docs sync-submodules`       | Moves `vendor/assets` to the latest commit of the `app/docs` branch and builds it. Commit the new pointer afterwards                                                |
+| `chassis-docs html-validate [paths]` | Validates the HTML files in `paths` with [html-validate](https://html-validate.org)                                                                                 |
+| `chassis-docs vnu [paths]`           | Validates `paths` with the [Nu Html Checker](https://validator.github.io/validator/). Skipped, with a warning, when Java is missing                                 |
+| `chassis-docs help`                  | Lists the commands and their options                                                                                                                                |
+
+`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.
+
+Each command exits with 1 when it fails, so a script or CI job stops there.
+
+### Validating HTML
+
+`html-validate` and `vnu` take any number of files and folders, `_site` when none is given. Paths are relative to the folder the script runs in, which for a site in `packages/site` is that folder when the script is in its `package.json`, and the repository root when it is in the root one.
+
+What a site can change:
+
+| To                                  | Use                                   | Validator     | Adds to the defaults or replaces them |
+| ----------------------------------- | ------------------------------------- | ------------- | ------------------------------------- |
+| Skip a file or folder               | `--ignore <path>`, repeatable         | both          | adds                                  |
+| Check `static/icons` too            | `--no-default-ignore`                 | both          | removes the default                   |
+| Turn a rule off or change it        | `rules` in the file of `--config`     | html-validate | overrides the rule                    |
+| Use more presets or plugins         | `extends` in the file of `--config`   | html-validate | adds                                  |
+| Allow custom elements or attributes | `elements` in the file of `--config`  | html-validate | replaces                              |
+| Leave out a message                 | `--filter <regex>` or `--filter-file` | vnu           | adds                                  |
+
+The defaults:
+
+- Both skip `static/icons` in each path, where a site copies `@chassis-ui/icons`, whose preview page is not the site's.
+- `html-validate` extends `html-validate:recommended` and `html-validate:document`. It turns off `void-style`, since Astro writes void elements with a slash, `no-inline-style`, since Shiki writes inline styles, and `require-sri`. `heading-level` lets a page start at `h2`, as the dialogs of the layouts do.
+- `vnu` fails on warnings as well as errors, and leaves out "Trailing slash on void elements", which Astro writes.
+
+A site with its own exceptions keeps them in files next to its `package.json`, and names them in its scripts:
+
+```json
+{
+  "scripts": {
+    "lint:html": "chassis-docs html-validate _site --ignore _site/examples --config html-validate.json",
+    "lint:vnu": "chassis-docs vnu _site --ignore _site/examples --filter-file vnu-filters.txt"
+  }
+}
+```
+
+`html-validate.json`:
+
+```json
+{
+  "rules": {
+    "prefer-native-element": ["error", { "exclude": ["region"] }],
+    "prefer-button": "off"
+  }
+}
+```
+
+`vnu-filters.txt`, one regular expression per line, where a line that starts with `#` is a comment:
+
+```text
+# The docs show autocomplete on inputs of every type
+Attribute “autocomplete” is only allowed when the input type is.*
+Bad value “heading” for attribute “role” on element “summary”.
+```
+
+A filter is matched against the message as the output shows it, curly quotes included: `“role”`. A line copied from the output works.
+
+A rule or filter applies to every file that the command checks. To make an exception for one page only, skip the page with `--ignore`, or disable the rule inside the page's markup with a comment of html-validate, such as `<!-- [html-validate-disable-next prefer-button] -->`.
+
 ## Exports
 
 These import paths are the public API.
@@ -259,6 +345,24 @@ No other path resolves: `exports` in `package.json` lists these and nothing else
 
 The integration provides four modules: `virtual:chassis-docs/config`, `virtual:chassis-docs/sidebar`, `virtual:chassis-docs/paths` and `virtual:chassis-docs/styles`. Use the functions of `@chassis-ui/docs/site` instead of importing them.
 
+## Compatibility
+
+"Requires" is what `package.json` of each version declares. "Built with" is what the website in this repository resolved and built when the version was released. CI also builds the [starter site](starter/) with the newest versions that its ranges accept.
+
+| `@chassis-ui/docs` | Requires Astro             | Requires `@chassis-ui/css` | Requires Node | Built with                           |
+| ------------------ | -------------------------- | -------------------------- | ------------- | ------------------------------------ |
+| 0.6.1              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |
+| 0.6.0              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.5.3 |
+| 0.5.1              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.5.3 |
+| 0.5.0              | `^7.0.0`                   | `^0.5.0-0`                 | not declared  | not recorded                         |
+| 0.4.0              | `^7.0.0`                   | `^0.4.0`                   | not declared  | not recorded                         |
+| 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.
+
+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.
+
 ## Versioning
 
 The package follows [Semantic Versioning](https://semver.org/). Before 1.0 that means:
@@ -270,6 +374,7 @@ A change is breaking when it changes something that this README documents:
 
 - the import paths listed under [Exports](#exports), and what they export
 - the options of the integration
+- the commands of `chassis-docs`, their options and their defaults
 - the keys of `config.yml`, and the schemas of the sidebar and the content collections
 - the props and slots of the layouts, components and shortcodes
 - the `[[config:]]` and `[[docsref:]]` syntax

package/bin/chassis-docs.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+// The build and validation commands that every Chassis site shares. Run `chassis-docs help`.
+import { main } from '../src/cli/main.js'
+
+process.exitCode = await main(process.argv.slice(2))

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chassis-ui/docs",
   "description": "Shared Astro components and layouts for Chassis documentation sites.",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "type": "module",
   "repository": {
     "type": "git",
@@ -23,6 +23,7 @@
     "design-system"
   ],
   "files": [
+    "bin",
     "src",
     "index.ts",
     "virtual.d.ts",
@@ -31,6 +32,9 @@
     "LICENSE",
     "CHANGELOG.md"
   ],
+  "bin": {
+    "chassis-docs": "./bin/chassis-docs.js"
+  },
   "main": "index.ts",
   "exports": {
     ".": "./index.ts",
@@ -70,10 +74,20 @@
     "@pagefind/component-ui": "^1.0.0",
     "@shikijs/transformers": "^4.3.1",
     "astro": "^7.0.0",
+    "html-validate": "^11.0.0",
     "htmlparser2": "^12.0.0",
     "rehype-autolink-headings": "^7.0.0",
     "sass": "^1.101.0",
-    "shiki": "^4.3.1"
+    "shiki": "^4.3.1",
+    "vnu-jar": ">=26.0.0"
+  },
+  "peerDependenciesMeta": {
+    "html-validate": {
+      "optional": true
+    },
+    "vnu-jar": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@types/hast": "^3.0.5",

package/src/cli/assets.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { CommandError, log, run as defaultRun } from './shared.js'
+
+/** Where every Chassis site has chassis-assets as a submodule. */
+export const ASSETS_PATH = 'vendor/assets'
+
+/** The docs build of chassis-assets, inside the submodule. `getChassisAssetsFsPath()` reads it. */
+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 root of the repository that contains the working directory, so that the commands
+ * work from a site's folder too.
+ * @param {typeof defaultRun} run
+ */
+function repositoryRoot(run) {
+  return run('git', ['rev-parse', '--show-toplevel'], { quiet: true }).trim()
+}
+
+/**
+ * Checks out `vendor/assets` at the commit that the repository pins, and builds it.
+ * @param {{ root?: string, run?: typeof defaultRun }} [options]
+ */
+export function buildAssets({ run = defaultRun, root = repositoryRoot(run) } = {}) {
+  log(`Building ${ASSETS_PATH} at the pinned commit`)
+  run('git', ['submodule', 'update', '--init', ASSETS_PATH], { cwd: root })
+  buildCheckout(root, run)
+}
+
+/**
+ * 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]
+ */
+export function syncAssets({
+  run = defaultRun,
+  root = repositoryRoot(run),
+  branch = DEFAULT_BRANCH
+} = {}) {
+  const dir = path.join(root, ASSETS_PATH)
+  const git = (args, quiet = true) => run('git', args, { cwd: dir, quiet })
+
+  log(`Moving ${ASSETS_PATH} to the latest ${branch}`)
+
+  if (!fs.existsSync(path.join(dir, '.git'))) {
+    run('git', ['submodule', 'update', '--init', ASSETS_PATH], { cwd: root })
+  }
+
+  if (git(['rev-parse', '--abbrev-ref', 'HEAD']).trim() !== branch) {
+    if (git(['status', '--porcelain']).trim()) {
+      throw new CommandError(
+        `${ASSETS_PATH} has uncommitted changes. Commit or discard them, then run the command again.`
+      )
+    }
+
+    // A fresh checkout, as on CI, has the submodule at a detached HEAD, fetched for the
+    // pinned commit only: there is neither a local branch nor a remote-tracking one.
+    git(['fetch', 'origin', branch])
+
+    if (hasLocalBranch(git, branch)) {
+      git(['checkout', branch])
+    } else {
+      git(['checkout', '-b', branch, 'FETCH_HEAD'])
+    }
+  }
+
+  git(['pull', '--ff-only', 'origin', branch])
+  buildCheckout(root, run)
+
+  const commit = git(['rev-parse', '--short', 'HEAD']).trim()
+  const moved = run('git', ['status', '--porcelain', '--', ASSETS_PATH], {
+    cwd: root,
+    quiet: true
+  }).trim()
+
+  if (moved) {
+    log(`${ASSETS_PATH} is at ${commit}. Check the site, then commit ${ASSETS_PATH} on its own.`)
+  } else {
+    log(`${ASSETS_PATH} is already at the latest ${branch}, ${commit}.`, 'success')
+  }
+}
+
+function hasLocalBranch(git, branch) {
+  try {
+    git(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`])
+    return true
+  } catch {
+    return false
+  }
+}
+
+function buildCheckout(root, run) {
+  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 })
+
+  const output = path.join(dir, ASSETS_OUTPUT)
+
+  if (!fs.existsSync(output)) {
+    throw new CommandError(`The build of ${ASSETS_PATH} wrote nothing to ${ASSETS_OUTPUT}.`)
+  }
+
+  log(`Built ${path.join(ASSETS_PATH, ASSETS_OUTPUT)}`, 'success')
+}

package/src/cli/files.js

@@ -0,0 +1,97 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { CommandError } from './shared.js'
+
+/** The default output folder of a Chassis site. */
+export const DEFAULT_PATHS = ['_site']
+
+/**
+ * The folders to skip when no `--ignore` is given: `static/icons` of each path, the files
+ * that a site copies from `@chassis-ui/icons`. They include a preview page of their own.
+ * @param {string[]} paths
+ */
+export function defaultIgnores(paths) {
+  return paths.map((dir) => path.join(dir, 'static/icons'))
+}
+
+/**
+ * Whether `file` is one of `ignores` or inside one of them.
+ * @param {string} file
+ * @param {string[]} ignores
+ */
+export function isIgnored(file, ignores) {
+  const target = path.resolve(file)
+
+  return ignores.some((ignore) => isInside(target, path.resolve(ignore)))
+}
+
+function isInside(target, dir) {
+  const relative = path.relative(dir, target)
+
+  return relative === '' || (relative.split(path.sep)[0] !== '..' && !path.isAbsolute(relative))
+}
+
+function checkExists(paths) {
+  for (const entry of paths) {
+    if (!fs.existsSync(entry)) {
+      throw new CommandError(`${entry} does not exist. Build the site first.`)
+    }
+  }
+}
+
+/**
+ * Lists the HTML files in `paths`, which are files or folders, leaving out `ignores` and
+ * `node_modules`.
+ * @param {string[]} paths
+ * @param {string[]} ignores
+ * @returns {string[]}
+ */
+export function findHtmlFiles(paths, ignores) {
+  const files = []
+
+  const visit = (entry) => {
+    if (isIgnored(entry, ignores)) return
+
+    if (fs.statSync(entry).isDirectory()) {
+      for (const name of fs.readdirSync(entry).sort()) {
+        if (name !== 'node_modules') visit(path.join(entry, name))
+      }
+    } else if (entry.endsWith('.html')) {
+      files.push(entry)
+    }
+  }
+
+  checkExists(paths)
+  paths.forEach(visit)
+
+  return files
+}
+
+/**
+ * Returns `paths` with `ignores` taken out. A folder that contains an ignored path is
+ * replaced by its entries, so that a checker that walks folders never reaches it.
+ * @param {string[]} paths
+ * @param {string[]} ignores
+ * @returns {string[]}
+ */
+export function expandPaths(paths, ignores) {
+  const result = []
+
+  const visit = (entry) => {
+    if (isIgnored(entry, ignores)) return
+
+    const target = path.resolve(entry)
+    const containsIgnored = ignores.some((ignore) => isInside(path.resolve(ignore), target))
+
+    if (containsIgnored && fs.statSync(entry).isDirectory()) {
+      for (const name of fs.readdirSync(entry).sort()) visit(path.join(entry, name))
+    } else {
+      result.push(entry)
+    }
+  }
+
+  checkExists(paths)
+  paths.forEach(visit)
+
+  return result
+}

package/src/cli/html-validate.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs'
+import { CommandError, importPeer, log } from './shared.js'
+import { findHtmlFiles } from './files.js'
+
+/** What the layouts and shortcodes of the package need. A site adds its own on top. */
+export const defaultConfig = {
+  extends: ['html-validate:recommended', 'html-validate:document'],
+  rules: {
+    // Astro writes void elements with a trailing slash
+    'void-style': 'off',
+    // Shiki highlights code with inline styles
+    'no-inline-style': 'off',
+    // The dialogs start at h2, and the `document` preset expects h1 in each sectioning root
+    'heading-level': ['error', { minInitialRank: 'h2', sectioningRoots: [] }],
+    // The layouts load their files from the site itself
+    'require-sri': 'off'
+  }
+}
+
+/**
+ * Adds a site's config to the default one: `extends` is appended, `rules` are merged,
+ * and `elements` is replaced.
+ * @param {Record<string, any>} base
+ * @param {Record<string, any>} [extra]
+ * @returns {Record<string, any>}
+ */
+export function mergeConfig(base, extra = {}) {
+  return {
+    ...base,
+    ...extra,
+    extends: [...(base.extends ?? []), ...(extra.extends ?? [])],
+    rules: { ...base.rules, ...extra.rules }
+  }
+}
+
+/**
+ * Reads a config file of html-validate.
+ * @param {string} file
+ */
+export function readConfig(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new CommandError(`Could not read ${file}: ${error.message}`, { cause: error })
+  }
+}
+
+// Validating hundreds of files at once runs out of file descriptors.
+async function mapWithConcurrency(limit, items, fn) {
+  const results = []
+  const running = new Set()
+
+  for (const item of items) {
+    const promise = fn(item).finally(() => running.delete(promise))
+
+    running.add(promise)
+    results.push(promise)
+
+    if (running.size >= limit) await Promise.race(running)
+  }
+
+  return Promise.all(results)
+}
+
+/**
+ * Validates the HTML files in `paths` with html-validate. Returns the exit code.
+ * @param {{ paths: string[], ignores: string[], config?: string }} options
+ */
+export async function htmlValidate({ paths, ignores, config }) {
+  const { HtmlValidate, Severity } = await importPeer('html-validate')
+  const validator = new HtmlValidate(mergeConfig(defaultConfig, config && readConfig(config)))
+  const files = findHtmlFiles(paths, ignores)
+
+  log(`Validating ${files.length} HTML files with html-validate`)
+
+  const reports = await mapWithConcurrency(10, files, async (file) => ({
+    file,
+    report: await validator.validateFile(file)
+  }))
+
+  let issueCount = 0
+  let fileCount = 0
+
+  for (const { file, report } of reports) {
+    const messages = (report.results[0]?.messages ?? []).filter(
+      (message) => message.severity >= Severity.WARN
+    )
+
+    if (messages.length === 0) continue
+
+    fileCount++
+    issueCount += messages.length
+    console.error(`\n${file}`)
+
+    for (const message of messages) {
+      const level = message.severity === Severity.ERROR ? 'error' : 'warning'
+
+      console.error(
+        `  ${message.line}:${message.column}  ${level}  ${message.message}  (${message.ruleId})`
+      )
+    }
+  }
+
+  if (issueCount > 0) {
+    log(`\n${issueCount} issues in ${fileCount} files.`, 'error')
+    return 1
+  }
+
+  log('Every HTML file is valid.', 'success')
+  return 0
+}

package/src/cli/main.js

@@ -0,0 +1,131 @@
+import { parseArgs } from 'node:util'
+import { DEFAULT_BRANCH, buildAssets, syncAssets } from './assets.js'
+import { DEFAULT_PATHS, defaultIgnores } from './files.js'
+import { htmlValidate } from './html-validate.js'
+import { CommandError, log } from './shared.js'
+import { vnu } from './vnu.js'
+
+export const usage = `Usage: chassis-docs <command> [options]
+
+Paths are relative to the working directory. vendor and sync-submodules work from any
+folder of the repository.
+
+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})
+  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
+      --filter <regex>   Leave out the messages that match. Repeatable
+      --filter-file <f>  Read filters from a file, one per line
+
+  Both validators:
+      --ignore <path>        Skip a file or folder as well. Repeatable
+      --no-default-ignore    Check static/icons of each path, which is skipped by default
+  help                   Show this message
+
+html-validate and vnu need the html-validate and vnu-jar packages in the site's devDependencies.`
+
+const ignoreOptions = {
+  ignore: { type: 'string', multiple: true },
+  'no-default-ignore': { type: 'boolean' }
+}
+
+// The static/icons folder of each path, unless left out, and the paths of --ignore.
+function ignoresOf(values, paths) {
+  return [...(values['no-default-ignore'] ? [] : defaultIgnores(paths)), ...(values.ignore ?? [])]
+}
+
+const commands = {
+  vendor: {
+    options: {},
+    run: () => {
+      buildAssets()
+      return 0
+    }
+  },
+  'sync-submodules': {
+    options: { branch: { type: 'string' } },
+    run: ({ values }) => {
+      syncAssets({ branch: values.branch ?? process.env.SUBMODULE_BRANCH ?? DEFAULT_BRANCH })
+      return 0
+    }
+  },
+  'html-validate': {
+    options: { config: { type: 'string' }, ...ignoreOptions },
+    positionals: true,
+    run: ({ values, paths }) =>
+      htmlValidate({
+        paths,
+        ignores: ignoresOf(values, paths),
+        config: values.config
+      })
+  },
+  vnu: {
+    options: {
+      filter: { type: 'string', multiple: true },
+      'filter-file': { type: 'string' },
+      ...ignoreOptions
+    },
+    positionals: true,
+    run: ({ values, paths }) =>
+      vnu({
+        paths,
+        ignores: ignoresOf(values, paths),
+        filters: values.filter,
+        filterFile: values['filter-file']
+      })
+  }
+}
+
+/**
+ * Runs a command and returns its exit code.
+ * @param {string[]} argv The arguments after `chassis-docs`
+ * @returns {Promise<number>}
+ */
+export async function main(argv) {
+  const [name, ...args] = argv
+
+  if (!name || ['help', '--help', '-h'].includes(name)) {
+    console.log(usage)
+    return 0
+  }
+
+  const command = commands[name]
+
+  try {
+    if (!Object.hasOwn(commands, name)) {
+      throw new CommandError(`Unknown command '${name}'. Run chassis-docs help for the list.`)
+    }
+
+    let parsed
+
+    try {
+      parsed = parseArgs({
+        args,
+        options: { ...command.options, help: { type: 'boolean', short: 'h' } },
+        allowPositionals: command.positionals ?? false,
+        strict: true
+      })
+    } catch (error) {
+      throw new CommandError(`${error.message}. Run chassis-docs help for the options.`, {
+        cause: error
+      })
+    }
+
+    if (parsed.values.help) {
+      console.log(usage)
+      return 0
+    }
+
+    const paths = parsed.positionals.length > 0 ? parsed.positionals : DEFAULT_PATHS
+
+    return await command.run({ values: parsed.values, paths })
+  } catch (error) {
+    if (!(error instanceof CommandError)) throw error
+
+    log(error.message, 'error')
+    return 1
+  }
+}

package/src/cli/shared.js

@@ -0,0 +1,69 @@
+import { execFileSync } from 'node:child_process'
+import { styleText } from 'node:util'
+
+/** An error that the command reports in one line, without a stack trace. */
+export class CommandError extends Error {}
+
+const colors = { info: 'cyan', success: 'green', warning: 'yellow', error: 'red' }
+
+/**
+ * Prints a message in the colour of its type. Errors and warnings go to stderr.
+ * @param {string} message
+ * @param {'info' | 'success' | 'warning' | 'error'} [type]
+ */
+export function log(message, type = 'info') {
+  const stream = type === 'error' || type === 'warning' ? process.stderr : process.stdout
+
+  stream.write(`${styleText(colors[type], message)}\n`)
+}
+
+/**
+ * Runs a program without a shell, except on Windows, where `pnpm` is a `.cmd` file.
+ * Returns what it printed when `quiet` is set, and prints it otherwise.
+ * @param {string} command
+ * @param {string[]} args
+ * @param {{ cwd?: string, quiet?: boolean }} [options]
+ * @returns {string}
+ */
+export function run(command, args, { cwd = process.cwd(), quiet = false } = {}) {
+  if (!quiet) {
+    log(`$ ${[command, ...args].join(' ')}`)
+  }
+
+  try {
+    return (
+      execFileSync(command, args, {
+        cwd,
+        encoding: 'utf8',
+        stdio: quiet ? 'pipe' : 'inherit',
+        shell: process.platform === 'win32'
+      }) ?? ''
+    )
+  } catch (error) {
+    const stderr = typeof error.stderr === 'string' ? error.stderr.trim() : ''
+
+    throw new CommandError(
+      `${[command, ...args].join(' ')} failed${stderr ? `:\n${stderr}` : ''}`,
+      { cause: error }
+    )
+  }
+}
+
+/**
+ * Imports an optional peer dependency, or says how to install it.
+ * @param {string} name
+ */
+export async function importPeer(name) {
+  try {
+    return await import(name)
+  } catch (error) {
+    if (error.code === 'ERR_MODULE_NOT_FOUND' && error.message.includes(`'${name}'`)) {
+      throw new CommandError(
+        `${name} is not installed. Add it to the devDependencies of the site: pnpm add -D ${name}`,
+        { cause: error }
+      )
+    }
+
+    throw error
+  }
+}

package/src/cli/vnu.js

@@ -0,0 +1,94 @@
+import { execFile, spawn } from 'node:child_process'
+import fs from 'node:fs'
+import { CommandError, importPeer, log } from './shared.js'
+import { expandPaths } from './files.js'
+
+/** Messages that every Chassis site produces. Astro writes void elements with a slash. */
+export const DEFAULT_FILTERS = ['Trailing slash on void elements.*']
+
+/**
+ * Reads a filter file: one regular expression per line. Blank lines and lines that start
+ * with `#` are skipped.
+ * @param {string} file
+ */
+export function readFilterFile(file) {
+  let text
+
+  try {
+    text = fs.readFileSync(file, 'utf8')
+  } catch (error) {
+    throw new CommandError(`Could not read ${file}: ${error.message}`, { cause: error })
+  }
+
+  return text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('#'))
+}
+
+/**
+ * The arguments for `java`.
+ * @param {{ jar: string, paths: string[], filters: string[], is32bit?: boolean }} options
+ */
+export function vnuArgs({ jar, paths, filters, is32bit = false }) {
+  return [
+    // 32-bit Java needs a smaller thread stack
+    ...(is32bit ? ['-Xss512k'] : []),
+    '-jar',
+    jar,
+    '--skip-non-html',
+    '--Werror',
+    '--filterpattern',
+    filters.join('|'),
+    ...paths
+  ]
+}
+
+function javaVersion() {
+  return new Promise((resolve) => {
+    // `java -version` prints to stderr
+    execFile('java', ['-version'], (error, _stdout, stderr) => resolve(error ? null : stderr))
+  })
+}
+
+/**
+ * Validates `paths` with the Nu Html Checker. Skips, and succeeds, when Java is missing.
+ * Returns the exit code.
+ * @param {{ paths: string[], ignores: string[], filters?: string[], filterFile?: string }} options
+ */
+export async function vnu({ paths, ignores, filters = [], filterFile }) {
+  const { default: jar } = await importPeer('vnu-jar')
+  const allFilters = [
+    ...DEFAULT_FILTERS,
+    ...filters,
+    ...(filterFile ? readFilterFile(filterFile) : [])
+  ]
+  const targets = expandPaths(paths, ignores)
+  const version = await javaVersion()
+
+  if (version === null) {
+    log('Java is not installed. Skipping the Nu Html Checker.', 'warning')
+    return 0
+  }
+
+  log('Validating HTML with the Nu Html Checker')
+
+  const args = vnuArgs({
+    jar,
+    paths: targets,
+    filters: allFilters,
+    is32bit: !/64-Bit/.test(version)
+  })
+
+  const code = await new Promise((resolve) => {
+    spawn('java', args, { stdio: 'inherit' }).on('exit', (exitCode) => resolve(exitCode ?? 1))
+  })
+
+  if (code === 0) {
+    log('Every HTML file is valid.', 'success')
+  } else {
+    log('The Nu Html Checker found errors.', 'error')
+  }
+
+  return code
+}

package/src/components/shortcodes/Code.astro

@@ -226,7 +226,7 @@ if (codeToDisplay && detectedLang) {
       ) : (
         <div class:list={['cxd-code', { 'line-numbers': lineNumbers }]}>
           {/* prettier-ignore */}
-          <pre class={className}><slot /></pre>
+          <pre class={className} tabindex="0"><slot /></pre>
         </div>
       )}
     </>
@@ -279,7 +279,7 @@ if (codeToDisplay && detectedLang) {
       ) : (
         <div class:list={['cxd-code', { 'line-numbers': lineNumbers }]}>
           {/* prettier-ignore */}
-          <pre class={className}><slot /></pre>
+          <pre class={className} tabindex="0"><slot /></pre>
         </div>
       )}
     </div>

package/src/layouts/BaseLayout.astro

@@ -12,6 +12,7 @@ import Head from './head/Head.astro'
 import Header from './header/Header.astro'
 import Scripts from './footer/Scripts.astro'
 import Footer from './footer/Footer.astro'
+import Consent from './footer/Consent.astro'
 import { stripMarkdown } from '../libs/utils'
 
 // The following props can be directly passed to the base layout component from any page or layout extending it,
@@ -25,7 +26,8 @@ type Props = {
   overrides?: {
     body?: LayoutOverridesHTMLAttributes<'body'>
     // Note that main can also be overridden by the Astro slot named "main" and that the slot will take precedence over
-    // any override.
+    // any override. `<main>` has `id="content"`, the target of the skip link in the header. A page that fills the "main"
+    // slot gives that id to an element of its own.
     main?: LayoutOverridesHTMLAttributes<'main'>
   }
   // An override for the page title. If not defined, the title will either be the content of the `title` frontmatter
@@ -61,7 +63,7 @@ const thumbnail = frontmatter?.thumbnail
   : 'static/images/social-image.png'
 
 const bodyProps = overrides?.body ?? {}
-const mainProps = overrides?.main ?? {}
+const mainProps = { id: 'content', ...overrides?.main }
 ---
 
 <!doctype html>
@@ -90,6 +92,7 @@ const mainProps = overrides?.main ?? {}
     }
 
     <Footer />
+    <Consent />
 
     <Scripts layout={layout}>
       <slot name="scripts" slot="scripts" />

package/src/layouts/footer/Consent.astro

@@ -0,0 +1,135 @@
+---
+/**
+ * Consent
+ *
+ * Asks before Google Analytics loads. Rendered in production builds, when
+ * `analytics.googleId` is set in `config.yml`. Nothing is loaded and no cookie is set until
+ * the visitor accepts. The choice is kept in `localStorage`, so every Chassis site served
+ * from the same host shares it. The "Cookie settings" button of the footer opens the
+ * banner again.
+ */
+
+import { getConfig } from '../../site'
+
+const isProd = import.meta.env.PROD
+const { googleId } = getConfig().analytics
+---
+
+{
+  isProd && googleId && (
+    <section class="cxd-consent" aria-label="Cookie consent" data-google-id={googleId} hidden>
+      <div class="container 2xl">
+        <div class="notification default shadow-lg d-flex flex-wrap align-items-center gap-md p-md">
+          <p class="mb-0 flex-grow-1">
+            We would like to count visits with Google Analytics, which sets cookies. Nothing is sent
+            to Google unless you accept. <a href="/privacy/">Privacy notice</a>
+          </p>
+          <div class="d-flex gap-sm">
+            <button type="button" class="button primary" data-consent="granted">
+              Accept
+            </button>
+            <button type="button" class="button default" data-consent="denied">
+              Decline
+            </button>
+          </div>
+        </div>
+      </div>
+    </section>
+  )
+}
+
+<script>
+  type AnalyticsWindow = Window &
+    Record<`ga-disable-${string}`, boolean> & {
+      dataLayer?: unknown[]
+      gtag?: (...args: unknown[]) => void
+    }
+
+  const KEY = 'chassis-analytics-consent'
+  const analytics = window as unknown as AnalyticsWindow
+  const banner = document.querySelector<HTMLElement>('.cxd-consent')
+  const googleId = banner?.dataset.googleId
+
+  function readChoice(): string | null {
+    try {
+      return localStorage.getItem(KEY)
+    } catch {
+      return null
+    }
+  }
+
+  function saveChoice(choice: string) {
+    try {
+      localStorage.setItem(KEY, choice)
+    } catch {
+      // Without storage the banner shows again on the next page
+    }
+  }
+
+  function loadAnalytics(id: string) {
+    analytics[`ga-disable-${id}`] = false
+    if (analytics.gtag) return
+
+    analytics.dataLayer ??= []
+    analytics.gtag = function () {
+      // gtag.js reads the `arguments` object, not an array
+      // eslint-disable-next-line prefer-rest-params
+      analytics.dataLayer!.push(arguments)
+    }
+    analytics.gtag('js', new Date())
+    analytics.gtag('config', id)
+
+    const script = document.createElement('script')
+    script.async = true
+    script.src = `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(id)}`
+    document.head.append(script)
+  }
+
+  // Stops Google Analytics on this page and deletes its cookies, which it sets on the
+  // registrable domain, such as `.chassis-ui.com`
+  function stopAnalytics(id: string) {
+    analytics[`ga-disable-${id}`] = true
+
+    const labels = location.hostname.split('.')
+    const domains = labels.slice(0, -1).map((_, index) => labels.slice(index).join('.'))
+
+    for (const cookie of document.cookie.split(';')) {
+      const name = cookie.split('=')[0].trim()
+
+      if (!name.startsWith('_ga')) continue
+
+      for (const domain of ['', ...domains.map((d) => `; domain=.${d}`)]) {
+        document.cookie = `${name}=; max-age=0; path=/${domain}`
+      }
+    }
+  }
+
+  if (banner && googleId) {
+    const choice = readChoice()
+
+    if (choice === 'granted') loadAnalytics(googleId)
+    else if (choice !== 'denied') banner.hidden = false
+
+    banner.addEventListener('click', (event) => {
+      const button = (event.target as Element).closest<HTMLElement>('[data-consent]')
+
+      if (!button) return
+
+      const decision = button.dataset.consent!
+
+      saveChoice(decision)
+      banner.hidden = true
+
+      if (decision === 'granted') loadAnalytics(googleId)
+      else stopAnalytics(googleId)
+    })
+
+    for (const opener of document.querySelectorAll<HTMLElement>('[data-consent-open]')) {
+      opener.hidden = false
+      opener.addEventListener('click', () => {
+        banner.hidden = false
+        banner.querySelector<HTMLElement>('[data-consent]')?.focus()
+      })
+    }
+  }
+</script>

package/src/layouts/footer/Footer.astro

@@ -17,18 +17,25 @@
         >
           <img src="/static/images/site-logo.svg" alt="Chassis UI" height="32" />
         </a>
-        <p>
+        <p class="mb-xs">
           This project is licensed under the MIT License, which allows for free use, modification,
           and distribution of the software.
         </p>
+        <p>
+          <a href="/privacy/" class="fg-main">Privacy</a>
+          <button hidden data-consent-open type="button" class="cxd-footer-link fg-main ms-md"
+            >Cookie settings</button
+          >
+        </p>
       </div>
       <div class="sm:col-4 lg:col-2 lg:offset-1 mb-md">
         <p class="h6 mb-xs">Docs</p>
         <ul class="nav">
           <li><a href="/tokens">Design Tokens</a></li>
-          <li><a href="/assets">Asset Distributor</a></li>
           <li><a href="/figma">Figma Library</a></li>
           <li><a href="/css">CSS Framework</a></li>
+          <li><a href="/react">React Components</a></li>
+          <li><a href="/assets">Asset Distributor</a></li>
           <li><a href="/icons">Icon Generator</a></li>
         </ul>
       </div>
@@ -36,9 +43,10 @@
         <p class="h6 mb-xs">Github</p>
         <ul class="nav">
           <li><a href="https://github.com/chassis-ui/tokens">Chassis Tokens</a></li>
-          <li><a href="https://github.com/chassis-ui/assets">Chassis Assets</a></li>
           <li><a href="https://github.com/chassis-ui/figma">Chassis Figma</a></li>
           <li><a href="https://github.com/chassis-ui/css">Chassis CSS</a></li>
+          <li><a href="https://github.com/chassis-ui/react">Chassis React</a></li>
+          <li><a href="https://github.com/chassis-ui/assets">Chassis Assets</a></li>
           <li><a href="https://github.com/chassis-ui/icons">Chassis Icons</a></li>
         </ul>
       </div>

package/src/layouts/head/Favicons.astro

@@ -10,6 +10,5 @@
 <link rel="icon" href={'/static/images/favicon-32x32.png'} sizes="32x32" type="image/png" />
 <link rel="icon" href={'/static/images/favicon-16x16.png'} sizes="16x16" type="image/png" />
 <link rel="manifest" href={'/static/images/manifest.json'} />
-<link rel="mask-icon" href={'/static/images/safari-pinned-tab.svg'} color="#712cf9" />
 <link rel="icon" href={'/static/images/favicon.png'} />
 <meta name="theme-color" content="#00A4CC" />

package/src/layouts/head/Head.astro

@@ -10,7 +10,6 @@ import type { Layout } from '../../libs/layout'
 import Stylesheet from './Stylesheet.astro'
 import Favicons from './Favicons.astro'
 import Social from './Social.astro'
-import Analytics from './Analytics.astro'
 import 'virtual:chassis-docs/styles'
 
 interface Props {
@@ -41,6 +40,14 @@ const pageTitle = isHome
 
 <link rel="preconnect" href="https://fonts.googleapis.com" />
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<!--
+  A link, not an `@import` in the styles, so that the browser finds it with the page and
+  not after the stylesheet that imports it
+-->
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@300..700&family=Inter:wght@100..900&family=Archivo+Narrow:ital,wght@0,400..700;1,400..700&display=swap"
+/>
 
 <meta name="description" content={description} />
 
@@ -59,4 +66,3 @@ const pageTitle = isHome
 <slot name="styles" />
 <Favicons />
 <Social description={description} layout={layout} thumbnail={thumbnail} title={title} />
-<Analytics />

package/src/layouts/header/Navigation.astro

@@ -94,6 +94,7 @@ const isActive = (path: string) => {
           <NavLink active={isActive('/tokens')} href="/tokens">Tokens</NavLink>
           <NavLink active={isActive('/figma')} href="/figma">Figma</NavLink>
           <NavLink active={isActive('/css')} href="/css">CSS</NavLink>
+          <NavLink active={isActive('/react')} href="/react">React</NavLink>
           <NavLink active={isActive('/assets')} href="/assets">Assets</NavLink>
           <NavLink active={isActive('/icons')} href="/icons">Icons</NavLink>
           <li class="nav-item col-12 lg:col-auto lg:d-flex">

package/src/libs/highlight.ts

@@ -1,5 +1,5 @@
 import { codeToHtml, type ShikiTransformer } from 'shiki'
-import { DOCS_SHIKI_THEMES } from './markdown'
+import { DOCS_SHIKI_THEMES, focusableTransformer } from './markdown'
 
 /**
  * Shiki transformer that renames the `shiki` CSS class on `<pre>` elements to
@@ -44,7 +44,7 @@ export async function highlightCode(
     lang,
     themes: DOCS_SHIKI_THEMES,
     defaultColor: false,
-    transformers: [...extraTransformers, classTransformer]
+    transformers: [...extraTransformers, classTransformer, focusableTransformer]
   })
 
   return { html: replaceShikiClasses(highlighted) }

package/src/libs/markdown.ts

@@ -35,6 +35,17 @@ const addLanguageAttributeTransformer: ShikiTransformer = {
   }
 }
 
+/**
+ * Shiki transformer that puts `<pre>` in the tab order. A code block that is wider than the
+ * page scrolls sideways, and a keyboard can scroll it only when it can take focus.
+ */
+export const focusableTransformer: ShikiTransformer = {
+  name: 'focusable-pre',
+  pre(node) {
+    node.properties['tabindex'] = '0'
+  }
+}
+
 /**
  * Options accepted by `getDocsMarkdownConfig`.
  */
@@ -121,7 +132,8 @@ export function getDocsMarkdownConfig(options: DocsMarkdownConfigOptions): Markd
       transformers: [
         transformerNotationDiff(),
         transformerNotationHighlight(),
-        addLanguageAttributeTransformer
+        addLanguageAttributeTransformer,
+        focusableTransformer
       ]
     }
   }

package/src/libs/schema.ts

@@ -38,7 +38,7 @@ const zHeadingRange = z.object({
  * ```
  */
 export const configSchema = z.strictObject({
-  /** Google Analytics is loaded in production builds when `googleId` is set. */
+  /** Google Analytics is offered in production builds when `googleId` is set, and loads after the visitor accepts. */
   analytics: z.strictObject({ googleId: z.string().optional() }).default({}),
   /** Heading levels that get an anchor link. */
   anchors: zHeadingRange.default({ min: 2, max: 5 }),

package/src/scss/_consent.scss

@@ -0,0 +1,14 @@
+//
+// Consent
+//
+
+@layer custom {
+  // Above the sticky header, below dialogs and drawers
+  .cxd-consent {
+    position: fixed;
+    inset-block-end: 0;
+    inset-inline: 0;
+    z-index: 1030;
+    padding-block: var(--cx-space-md);
+  }
+}

package/src/scss/_footer.scss

@@ -14,7 +14,8 @@
       }
     }
 
-    a {
+    a,
+    .cxd-footer-link {
       color: var(--cx-fg-color);
       text-decoration: none;
 
@@ -24,5 +25,14 @@
         text-decoration: underline;
       }
     }
+
+    // A button that looks like the links next to it
+    .cxd-footer-link {
+      padding: 0;
+      font: inherit;
+      cursor: pointer;
+      background: none;
+      border: 0;
+    }
   }
 }

package/src/scss/main.scss

@@ -1,6 +1,5 @@
 @use "@chassis-ui/css/scss/mixins" as *;
 
-@forward "./fonts";
 @forward "./navbar";
 @forward "./content";
 @forward "./skippy";
@@ -8,6 +7,7 @@
 @forward "./layout";
 @forward "./toc";
 @forward "./footer";
+@forward "./consent";
 @forward "./snippets";
 @forward "./callouts";
 @forward "./placeholder-img";

package/src/layouts/head/Analytics.astro

@@ -1,31 +0,0 @@
----
-/**
- * Analytics
- *
- * Google Analytics script tags. Rendered in production builds, when `analytics.googleId` is
- * set in `config.yml`.
- */
-
-import { getConfig } from '../../site'
-
-const isProd = import.meta.env.PROD
-const { googleId } = getConfig().analytics
----
-
-{
-  isProd && googleId && (
-    <>
-      <script is:inline async src={`https://www.googletagmanager.com/gtag/js?id=${googleId}`} />
-      <script
-        is:inline
-        set:html={`
-  window.dataLayer = window.dataLayer || [];
-  function gtag(){dataLayer.push(arguments);}
-  gtag('js', new Date());
-
-  gtag('config', '${googleId}');
-`}
-      />
-    </>
-  )
-}

package/src/scss/fonts.scss

@@ -1 +0,0 @@
-@import "https://fonts.googleapis.com/css2?family=Fira+Code:wght@300..700&family=Inter:wght@100..900&family=Archivo+Narrow:ital,wght@0,400..700;1,400..700&display=swap";