@lullabot/eleventy-decision-records 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Lullabot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# @lullabot/eleventy-decision-records
+
+An [Eleventy](https://www.11ty.dev/) (v3 or v4) theme plugin for documenting architectural decision records (ADRs).
+
+Install it into an Eleventy project and you get the listing pages, per-topic and per-contributor pages, search, and an Atom feed — without copying any of it into your repository.
+
+## Getting Started
+
+```bash
+npm install @lullabot/eleventy-decision-records
+```
+
+Eleventy is a peer dependency (3.x, or the 4.x prereleases), so install it too if you have not already:
+
+```bash
+npm install --save-dev @11ty/eleventy
+```
+
+Register the plugin in your Eleventy config:
+
+```js
+import decisionRecords from '@lullabot/eleventy-decision-records';
+
+export default function (eleventyConfig) {
+  eleventyConfig.addPlugin(decisionRecords, {
+    site: {
+      organization: 'Your Organization',
+      url: 'https://decisions.example.com/',
+    },
+  });
+
+  return {
+    markdownTemplateEngine: 'njk',
+    htmlTemplateEngine: 'njk',
+    dir: {
+      input: 'docs',
+    },
+  };
+}
+```
+
+Both template engines must be set to `njk` — the theme's pages and layouts are Nunjucks, including the markdown ones. Your project also needs `"type": "module"` in its `package.json`.
+
+Site metadata, navigation, and practice areas are configured through the plugin options only. The theme registers them as global data, which Eleventy merges _over_ any `_data/site.json`, `_data/navigation.json`, or `_data/practiceAreas.json` in your project.
+
+Then write decision records as markdown files in `docs/decisions/`, and build as usual:
+
+```bash
+npx eleventy --serve
+```
+
+The theme supplies a homepage and an about page until you add your own. Anything it provides can be replaced by putting a file of the same name in your project — see [Customizing](docs/customizing.md).
+
+## Documentation
+
+- [Customizing for your organization](docs/customizing.md) — plugin options, overriding templates, styles, and icons
+- [Writing ADRs](docs/writing-adrs.md) — naming convention and frontmatter fields
+- [Development](docs/development.md) — commands, testing, CI/deployment
+- [Architecture](docs/architecture.md) — how the plugin is put together
+
+## License
+
+See [LICENSE](LICENSE) for details.
+
+The Gabarito font files in `src/assets/fonts/` are licensed separately under the SIL Open Font License 1.1. See [src/assets/fonts/OFL.txt](src/assets/fonts/OFL.txt).

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@lullabot/eleventy-decision-records",
+  "version": "1.0.0",
+  "description": "An Eleventy theme plugin for documenting decision records",
+  "scripts": {
+    "start": "bash bin/link-fixture-site.sh && DECISION_RECORDS_DEV=1 npm --prefix tests/fixture-site run serve",
+    "lint": "eslint && prettier -c .",
+    "lint:fix": "eslint --fix && prettier -w .",
+    "lint-staged": "lint-staged",
+    "prepare": "husky",
+    "test": "bash bin/run-e2e.sh",
+    "test:config": "bash bin/prepare-fixture-site.sh && npm --prefix tests/fixture-site test",
+    "test:update": "bash bin/run-e2e.sh --update",
+    "test:local": "playwright test"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/index.js",
+    "src/config.js",
+    "src/defaultConfig.json",
+    "src/index.md",
+    "src/about.md",
+    "src/YYYYMMDD-decision-template.md",
+    "src/lib",
+    "src/templates",
+    "src/assets"
+  ],
+  "peerDependencies": {
+    "@11ty/eleventy": "^3.0.0 || ^4.0.0-0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "eleventy",
+    "eleventy-plugin",
+    "eleventy-theme",
+    "11ty",
+    "adr",
+    "architecture-decision-record",
+    "decision-records",
+    "documentation"
+  ],
+  "author": "Lullabot, Inc.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Lullabot/eleventy-decision-records"
+  },
+  "homepage": "https://github.com/Lullabot/eleventy-decision-records#readme",
+  "bugs": {
+    "url": "https://github.com/Lullabot/eleventy-decision-records/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "devDependencies": {
+    "@axe-core/playwright": "^4.13.0",
+    "@eslint/js": "^10.0.0",
+    "@lullabot/playwright-drupal": "^1.11.0",
+    "@playwright/test": "^1.62.1",
+    "eslint": "^10.0.3",
+    "eslint-config-prettier": "^10.0.3",
+    "eslint-plugin-prettier": "^5.2.1",
+    "globals": "^17.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.0.0",
+    "prettier": "^3.4.2"
+  },
+  "dependencies": {
+    "@11ty/eleventy-plugin-bundle": "^3.0.7",
+    "@11ty/eleventy-plugin-rss": "^3.0.0",
+    "@11ty/eleventy-plugin-syntaxhighlight": "^5.0.2",
+    "@11ty/eleventy-utils": "^2.0.7",
+    "@js-temporal/polyfill": "^0.5.1",
+    "@material-symbols/svg-400": "^0.47.0",
+    "@orama/orama": "^3.1.18",
+    "eleventy-plugin-toc": "^1.1.5",
+    "he": "^1.2.0",
+    "lightningcss": "^1.32.0",
+    "markdown-it": "^15.0.0",
+    "markdown-it-anchor": "^10.0.0",
+    "node-html-parser": "^9.0.0",
+    "prettier-plugin-jinja-template": "^2.1.0",
+    "striptags": "^3.2.0"
+  },
+  "lint-staged": {
+    "*.js": "eslint",
+    "*.{js,njk,json,md,css,yml,yaml}": "prettier --check"
+  }
+}

package/src/YYYYMMDD-decision-template.md

@@ -0,0 +1,41 @@
+---
+# In the metadata section, # is a comment, not a heading.
+# If other ADRs are added before this one is finished, set the date to
+# today's date to push it to the top of the list.
+date: YYYY-MM-DD
+
+# New ADRs start at accepted, and no longer relevant ADRs are deprecated.
+status: accepted
+
+# Practice area - one of: Design, Engineering, Project Management, Strategy
+practiceArea: Engineering
+
+# Topics are freeform - see existing ADRs for ideas
+topics:
+  - development
+  - testing
+
+# Include anyone who was involved in the decision or discussions. The goal
+# is to have a list for the future so the team has a starting point to ask
+# for any missing historical context. This list should be sorted alphabetically
+# by first name.
+contributors:
+  - Individual A
+  - Individual B
+  - Individual C
+
+title: A simple statement describing the decision
+context: A sentence or two describing the context of the decision.
+---
+
+<!-- Begin Markdown and HTML -->
+
+## Decision
+
+<!-- Write the decision here -->
+<!-- Headings will be shown in a table of contents with links -->
+
+## Consequences
+
+<!-- What has to be done now that we've made the decision? -->
+<!-- How will this impact us or our clients? -->

package/src/about.md

@@ -0,0 +1,36 @@
+---
+title: About
+description: What are architectural decision records and how we use them
+permalink: /about/
+eleventyExcludeFromCollections: true
+---
+
+# {{ title }}
+
+## What is an ADR?
+
+An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architectural Decision Record (ADR) captures a single AD — the collection of ADRs created and maintained in a project constitutes its decision log.
+
+An ADR is immutable once accepted, beyond simple fixes and improvements that don't change the substance of the decision. Otherwise, only its status can change (i.e., become deprecated or superseded). Team members can become familiar with the whole history of decisions by reading the decision log in chronological order.
+
+## Why keep decision records?
+
+- **Onboarding** — New team members can quickly understand why things are built the way they are
+- **Accountability** — Avoid blindly accepting or reversing past decisions without understanding the original context
+- **Process** — Formalize how the team evaluates and agrees on architectural choices
+
+## How to contribute
+
+Create a new markdown file in the `{{ dirs.decisions }}/` directory using the naming convention `YYYYMMDD-url-friendly-name.md`. Use the decision template as a starting point and fill in the required frontmatter fields:
+
+- **date** — When the decision was made
+- **status** — `accepted` or `deprecated`
+- **practiceArea** — One of: Design, Engineering, Project Management, Strategy
+- **topics** — Freeform tags describing what the decision covers
+- **contributors** — Team members involved in making the decision
+- **title** — A concise summary of the decision
+- **context** — Brief description of the problem or situation
+
+## License
+
+This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).

package/src/assets/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright (c) 2023, The Gabarito Project Authors (https://github.com/naipefoundry/gabarito).
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/src/assets/icons/facebook.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M9.101 23.691v-7.98H6.627v-3.667h2.474v-1.58c0-4.085 1.848-5.978 5.858-5.978.401 0 .955.042 1.468.103a8.68 8.68 0 0 1 1.141.195v3.325a8.623 8.623 0 0 0-.653-.036 26.805 26.805 0 0 0-.733-.009c-.707 0-1.259.096-1.675.309a1.686 1.686 0 0 0-.679.622c-.258.42-.374.995-.374 1.752v1.297h3.919l-.386 2.103-.287 1.564h-3.246v8.245C19.396 23.238 24 18.179 24 12.044c0-6.627-5.373-12-12-12s-12 5.373-12 12c0 5.628 3.874 10.35 9.101 11.647Z"/></svg>

package/src/assets/icons/github.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>

package/src/assets/icons/linkedin.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="96 96 448 448"><path d="M512 96L127.9 96C110.3 96 96 110.5 96 128.3L96 511.7C96 529.5 110.3 544 127.9 544L512 544C529.6 544 544 529.5 544 511.7L544 128.3C544 110.5 529.6 96 512 96zM231.4 480L165 480L165 266.2L231.5 266.2L231.5 480L231.4 480zM198.2 160C219.5 160 236.7 177.2 236.7 198.5C236.7 219.8 219.5 237 198.2 237C176.9 237 159.7 219.8 159.7 198.5C159.7 177.2 176.9 160 198.2 160zM480.3 480L413.9 480L413.9 376C413.9 351.2 413.4 319.3 379.4 319.3C344.8 319.3 339.5 346.3 339.5 374.2L339.5 480L273.1 480L273.1 266.2L336.8 266.2L336.8 295.4L337.7 295.4C346.6 278.6 368.3 260.9 400.6 260.9C467.8 260.9 480.3 305.2 480.3 362.8L480.3 480z"/></svg>

package/src/assets/icons/mastodon.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M23.268 5.313c-.35-2.578-2.617-4.61-5.304-5.004C17.51.242 15.792 0 11.813 0h-.03c-3.98 0-4.835.242-5.288.309C3.882.692 1.496 2.518.917 5.127.64 6.412.61 7.837.661 9.143c.074 1.874.088 3.745.26 5.611.118 1.24.325 2.47.62 3.68.55 2.237 2.777 4.098 4.96 4.857 2.336.792 4.849.923 7.256.38.265-.061.527-.132.786-.213.585-.184 1.27-.39 1.774-.753a.057.057 0 0 0 .023-.043v-1.809a.052.052 0 0 0-.02-.041.053.053 0 0 0-.046-.01 20.282 20.282 0 0 1-4.709.545c-2.73 0-3.463-1.284-3.674-1.818a5.593 5.593 0 0 1-.319-1.433.053.053 0 0 1 .066-.054c1.517.363 3.072.546 4.632.546.376 0 .75 0 1.125-.01 1.57-.044 3.224-.124 4.768-.422.038-.008.077-.015.11-.024 2.435-.464 4.753-1.92 4.989-5.604.008-.145.03-1.52.03-1.67.002-.512.167-3.63-.024-5.545zm-3.748 9.195h-2.561V8.29c0-1.309-.55-1.976-1.67-1.976-1.23 0-1.846.79-1.846 2.35v3.403h-2.546V8.663c0-1.56-.617-2.35-1.848-2.35-1.112 0-1.668.668-1.67 1.977v6.218H4.822V8.102c0-1.31.337-2.35 1.011-3.12.696-.77 1.608-1.164 2.74-1.164 1.311 0 2.302.5 2.962 1.498l.638 1.06.638-1.06c.66-.999 1.65-1.498 2.96-1.498 1.13 0 2.043.395 2.74 1.164.675.77 1.012 1.81 1.012 3.12z"/></svg>

package/src/assets/icons/x.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M14.234 10.162 22.977 0h-2.072l-7.591 8.824L7.251 0H.258l9.168 13.343L.258 24H2.33l8.016-9.318L16.749 24h6.993zm-2.837 3.299-.929-1.329L3.076 1.56h3.182l5.965 8.532.929 1.329 7.754 11.09h-3.182z"/></svg>

package/src/assets/icons/youtube.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M23.498 6.186a3.016 3.016 0 0 0-2.122-2.136C19.505 3.545 12 3.545 12 3.545s-7.505 0-9.377.505A3.017 3.017 0 0 0 .502 6.186C0 8.07 0 12 0 12s0 3.93.502 5.814a3.016 3.016 0 0 0 2.122 2.136c1.871.505 9.376.505 9.376.505s7.505 0 9.377-.505a3.015 3.015 0 0 0 2.122-2.136C24 15.93 24 12 24 12s0-3.93-.502-5.814zM9.545 15.568V8.432L15.818 12l-6.273 3.568z"/></svg>

package/src/assets/js/scrollable.js

@@ -0,0 +1,49 @@
+// Scroll boxes with nothing focusable inside cannot be scrolled from the
+// keyboard in WebKit, so each one gets a tab stop while, and only while,
+// its content overflows. Tables also become a named region so the stop
+// is announced.
+const boxes = document.querySelectorAll(
+  '.adr-content pre, .adr-content .table-scroll',
+);
+
+let captionCount = 0;
+
+function label(box) {
+  const caption = box.querySelector('caption');
+  if (!caption) {
+    box.setAttribute('aria-label', 'Scrollable table');
+    return;
+  }
+  caption.id ||= `scrollable-caption-${++captionCount}`;
+  box.setAttribute('aria-labelledby', caption.id);
+}
+
+function update(box) {
+  const overflows = box.scrollWidth > box.clientWidth;
+  if (overflows === box.hasAttribute('tabindex')) return;
+
+  if (overflows) {
+    box.setAttribute('tabindex', '0');
+    if (box.matches('.table-scroll')) {
+      box.setAttribute('role', 'region');
+      label(box);
+    }
+  } else {
+    for (const name of ['tabindex', 'role', 'aria-label', 'aria-labelledby']) {
+      box.removeAttribute(name);
+    }
+  }
+}
+
+// The content is observed as well as the box, since a late web font can
+// widen a table without the box itself changing size.
+const observer = new ResizeObserver((entries) => {
+  for (const { target } of entries) {
+    update(target.closest('pre, .table-scroll'));
+  }
+});
+
+for (const box of boxes) {
+  observer.observe(box);
+  if (box.firstElementChild) observer.observe(box.firstElementChild);
+}

package/src/assets/js/search.js

@@ -0,0 +1,189 @@
+import { create, load, search } from '/js/orama/index.js';
+import { timeSince } from './time-since.js';
+
+function highlightTerms(text, terms) {
+  const escaped = text.replace(/&/g, '&amp;').replace(/</g, '&lt;');
+  const pattern = terms
+    .map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('|');
+  return escaped.replace(new RegExp(`(${pattern})`, 'gi'), '<mark>$1</mark>');
+}
+
+function getSnippet(text, terms, contextChars = 80) {
+  const lowerText = text.toLowerCase();
+  let bestIndex = -1;
+
+  for (const term of terms) {
+    const idx = lowerText.indexOf(term);
+    if (idx !== -1) {
+      bestIndex = idx;
+      break;
+    }
+  }
+
+  if (bestIndex === -1) {
+    return '';
+  }
+
+  const start = Math.max(0, bestIndex - contextChars);
+  const end = Math.min(text.length, bestIndex + contextChars);
+  let snippet = text.slice(start, end).trim();
+  if (start > 0) {
+    snippet = `\u2026${snippet}`;
+  }
+  if (end < text.length) {
+    snippet = `${snippet}\u2026`;
+  }
+
+  return highlightTerms(snippet, terms);
+}
+
+(async () => {
+  const dialog = document.getElementById('search-dialog');
+  const searchInput = dialog.querySelector('input[type="search"]');
+  const resultsList = dialog.querySelector('ol');
+  const summary = dialog.querySelector('.results-summary');
+  const status = dialog.querySelector('[aria-live="polite"]');
+
+  // Debounce announcements past the typing echo (VoiceOver's echo preempts
+  // polite announcements rather than queueing behind them), and write in a
+  // single mutation — every region mutation can cancel in-flight speech.
+  let announceTimer;
+  function announce(text) {
+    summary.textContent = text;
+    clearTimeout(announceTimer);
+    announceTimer = setTimeout(() => {
+      status.textContent = text;
+    }, 150);
+  }
+  const resultTemplate = dialog.querySelector('template').content;
+
+  let db;
+  let initPromise = null;
+
+  const SCHEMA = {
+    url: 'string',
+    title: 'string',
+    topics: 'string[]',
+    context: 'string',
+    content: 'string',
+    status: 'string',
+    date: 'string',
+  };
+
+  function initializeSearch() {
+    initPromise ??= (async () => {
+      const response = await fetch('/searchindex.json');
+      if (!response.ok) {
+        throw new Error(`Search index returned ${response.status}`);
+      }
+      const rawData = await response.json();
+
+      db = create({ schema: SCHEMA });
+      load(db, rawData);
+    })().catch((error) => {
+      // Allow the next search to retry the fetch.
+      initPromise = null;
+      throw error;
+    });
+    return initPromise;
+  }
+
+  async function doSearch() {
+    const query = searchInput.value.trim();
+    if (!query) {
+      resultsList.innerHTML = '';
+      clearTimeout(announceTimer);
+      summary.textContent = '';
+      status.textContent = '';
+      return;
+    }
+
+    resultsList.innerHTML = '';
+    const loading = document.createElement('li');
+    loading.textContent = 'Loading search\u2026';
+    resultsList.append(loading);
+
+    try {
+      await initializeSearch();
+    } catch {
+      resultsList.innerHTML = '';
+      announce('Search is unavailable right now — please try again.');
+      return;
+    }
+
+    const { hits } = search(db, {
+      term: query,
+      properties: ['title', 'topics', 'context', 'content'],
+      boost: { title: 3, topics: 2, context: 1.5 },
+      tolerance: 1,
+      threshold: 0.6,
+      limit: 50,
+    });
+
+    const queryTerms = query
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((t) => t.length > 0);
+
+    let results = hits.map((hit) => ({
+      ...hit.document,
+      href: hit.document.url,
+      snippet: getSnippet(hit.document.content, queryTerms),
+    }));
+
+    results.sort((a, b) => {
+      if (a.status === b.status) return 0;
+      if (a.status === 'deprecated') return 1;
+      if (b.status === 'deprecated') return -1;
+      return 0;
+    });
+
+    results = results.map((result, i) => {
+      const entry = resultTemplate.cloneNode(true);
+
+      const li = entry.querySelector('li');
+      li.style.animationDelay = `${i * 50}ms`;
+
+      entry.querySelector('a').innerHTML = highlightTerms(
+        result.title,
+        queryTerms,
+      );
+      entry.querySelector('a').href = result.href;
+      entry.querySelector('.snippet').innerHTML = result.snippet;
+      entry.querySelector('.status').textContent = result.status;
+      entry.querySelector('.age').textContent = timeSince(result.date);
+
+      const tagsEl = entry.querySelector('.tags');
+      for (const tag of result.topics) {
+        const span = document.createElement('span');
+        span.textContent = tag;
+        tagsEl.append(span);
+      }
+
+      return entry;
+    });
+
+    resultsList.innerHTML = '';
+    resultsList.append(...results);
+    if (results.length) {
+      const s = results.length === 1 ? '' : 's';
+      announce(`${results.length} result${s} for \u201c${query}\u201d`);
+    } else {
+      announce(`No results found for \u201c${query}\u201d`);
+    }
+  }
+
+  // Start fetching the index on the first keystroke, ahead of the debounce.
+  searchInput.addEventListener(
+    'input',
+    () => initializeSearch().catch(() => {}),
+    { once: true },
+  );
+
+  let debounceTimer;
+  searchInput.addEventListener('input', () => {
+    clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(doSearch, 250);
+  });
+})();

package/src/assets/js/time-since.js

@@ -0,0 +1,31 @@
+// TODO: Replace with Temporal (matching src/lib/filters/dates.js) once
+// browser support is baseline:
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#browser_compatibility
+export function timeSince(isoDate) {
+  const then = new Date(isoDate);
+  const now = new Date();
+  let years = now.getUTCFullYear() - then.getUTCFullYear();
+  let months = now.getUTCMonth() - then.getUTCMonth();
+  let days = now.getUTCDate() - then.getUTCDate();
+
+  if (days < 0) {
+    months -= 1;
+    days += new Date(now.getUTCFullYear(), now.getUTCMonth(), 0).getDate();
+  }
+  if (months < 0) {
+    years -= 1;
+    months += 12;
+  }
+
+  const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'always' });
+  if (years > 0) {
+    return rtf.format(-years, 'year');
+  }
+  if (months > 0) {
+    return rtf.format(-months, 'month');
+  }
+  if (days > 0) {
+    return rtf.format(-days, 'day');
+  }
+  return 'today';
+}