@arraypress/extension-kit 1.2.0 → 1.4.0

package/src/build/vendor.d.ts

@@ -1,26 +1,96 @@
 /**
- * Copy the kit's browser half (the runtime modules and the stylesheet) into
- * an extension folder. A packaged extension can't load files from outside
- * itself, so an extension without a bundler loads the kit from a copy; the
- * copy is made from the installed package on `npm install` and is never
- * committed, so it can't drift from the version in package.json.
+ * Copy browser code from npm packages into an extension folder. A packaged
+ * extension can't load files from outside itself, so an extension without a
+ * bundler loads the kit (and any other library) from a copy in
+ * `extension/vendor/`; the copy is made from the installed package on
+ * `npm install` (`postinstall`) and is never committed.
+ *
+ * Each copy is stamped with the package's name and version
+ * ({@link VENDOR_STAMP}), so {@link checkVendored} can say when a copy no
+ * longer matches what's installed: `npm install some-package` installs
+ * without running the extension's own `postinstall`, and the copy goes stale
+ * without a word.
  *
  * An extension with a bundler imports the package instead and copies only
  * the stylesheet ({@link STYLESHEET}).
  *
  * @module build/vendor
  */
-/** What a vendored copy holds, relative to `src/`: everything an extension page or worker may load. */
+/** What a vendored copy of the kit holds, relative to `src/`: everything an extension page or worker may load. */
 export declare const RUNTIME_ENTRIES: readonly string[];
 /** The kit's stylesheet, an absolute path in the installed package. */
 export declare const STYLESHEET: string;
+/** The file in each vendored folder that names the package and version it was copied from (left out of the zip). */
+export declare const VENDOR_STAMP = "vendored.json";
+export type VendorStamp = {
+    /**
+     * The package's name.
+     */
+    package: string;
+    /**
+     * Its version when copied.
+     */
+    version: string;
+};
+/**
+ * Where a vendored copy came from.
+ *
+ * @typedef {object} VendorStamp
+ * @property {string} package The package's name.
+ * @property {string} version Its version when copied.
+ */
 /**
- * Replace `dest` with a fresh copy of the runtime modules and stylesheet.
+ * The folder of an installed package, found as Node finds it (the nearest
+ * `node_modules/<name>` up from `from`), read from disk so a package whose
+ * `exports` hide its `package.json` is found too.
+ *
+ * @param {string} name - The package's name, e.g. `@duckduckgo/autoconsent`.
+ * @param {string} [from] - Where to look up from. Default the current folder.
+ * @returns {Promise<string>} The package's folder.
+ * @throws {Error} When it isn't installed.
+ */
+export declare function packageDir(name: string, from?: string): Promise<string>;
+/**
+ * Replace `dest` with a fresh copy of the kit's runtime modules and stylesheet.
  *
  * @param {string} dest - The folder to fill, e.g. `extension/vendor/extension-kit`. Removed first.
  * @returns {Promise<string[]>} The entries copied, relative to `dest`.
  * @example
  * await vendorKit('extension/vendor/extension-kit');
- * // extension/vendor/extension-kit/index.js, …/styles/chrome-ui.css, …
+ * // extension/vendor/extension-kit/index.js, …/styles/chrome-ui.css, …, vendored.json
  */
 export declare function vendorKit(dest: string): Promise<string[]>;
+/**
+ * Replace `dest` with named files and folders of an installed npm package.
+ * Each path is relative to the package's folder and lands in `dest` under
+ * its own name (`dist/lib.esm.js` → `dest/lib.esm.js`); a path ending in `/`
+ * has its contents copied into `dest` instead (`src/` → `dest/index.js`, …).
+ *
+ * @param {string} name - The package, as installed (`@arraypress/clean-link`).
+ * @param {readonly string[]} files - What to copy.
+ * @param {string} dest - The folder to fill, e.g. `extension/vendor/clean-link`. Removed first.
+ * @param {{from?: string}} [options] - `from`: where to look for `node_modules` from. Default the current folder.
+ * @returns {Promise<string[]>} The files and folders written, relative to `dest`.
+ * @throws {Error} When the package isn't installed, or a path isn't in it.
+ * @example
+ * await vendorPackage('@duckduckgo/autoconsent', ['dist/autoconsent.esm.js', 'rules/compact-rules.json', 'LICENSE'], 'extension/vendor/autoconsent');
+ * // or, from postinstall: extension-kit vendor extension/vendor/clean-link @arraypress/clean-link src/
+ */
+export declare function vendorPackage(name: string, files: readonly string[], dest: string, { from }?: {
+    from?: string;
+}): Promise<string[]>;
+/**
+ * Every vendored copy under `dir` (a folder with a {@link VENDOR_STAMP},
+ * searched to any depth) that no longer matches the package installed now:
+ * copied from another version, or from a package that's gone.
+ *
+ * @param {string} dir - The vendor folder, e.g. `extension/vendor`.
+ * @param {{from?: string}} [options] - `from`: where to look for `node_modules` from. Default the current folder.
+ * @returns {Promise<string[]>} One line per stale copy; empty when all match (or there are none).
+ * @example
+ * const stale = await checkVendored('extension/vendor');
+ * // ['extension/vendor/extension-kit is @arraypress/extension-kit 1.2.0; 1.3.0 is installed']
+ */
+export declare function checkVendored(dir: string, { from }?: {
+    from?: string;
+}): Promise<string[]>;

package/src/build/vendor.js

@@ -1,9 +1,15 @@
 /**
- * Copy the kit's browser half (the runtime modules and the stylesheet) into
- * an extension folder. A packaged extension can't load files from outside
- * itself, so an extension without a bundler loads the kit from a copy; the
- * copy is made from the installed package on `npm install` and is never
- * committed, so it can't drift from the version in package.json.
+ * Copy browser code from npm packages into an extension folder. A packaged
+ * extension can't load files from outside itself, so an extension without a
+ * bundler loads the kit (and any other library) from a copy in
+ * `extension/vendor/`; the copy is made from the installed package on
+ * `npm install` (`postinstall`) and is never committed.
+ *
+ * Each copy is stamped with the package's name and version
+ * ({@link VENDOR_STAMP}), so {@link checkVendored} can say when a copy no
+ * longer matches what's installed: `npm install some-package` installs
+ * without running the extension's own `postinstall`, and the copy goes stale
+ * without a word.
  *
  * An extension with a bundler imports the package instead and copies only
  * the stylesheet ({@link STYLESHEET}).
@@ -11,27 +17,80 @@
  * @module build/vendor
  */
 
-import { cp, mkdir, rm } from 'node:fs/promises';
+import { access, cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 
 /** The package's `src/` folder. */
 const SOURCE = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 
-/** What a vendored copy holds, relative to `src/`: everything an extension page or worker may load. */
-export const RUNTIME_ENTRIES = Object.freeze(['index.js', 'index.d.ts', 'about', 'commands', 'dom', 'settings', 'styles', 'toolbar', 'ui']);
+/** The kit's package name. */
+const KIT = '@arraypress/extension-kit';
+
+/** What a vendored copy of the kit holds, relative to `src/`: everything an extension page or worker may load. */
+export const RUNTIME_ENTRIES = Object.freeze(['index.js', 'index.d.ts', 'about', 'commands', 'dom', 'settings', 'sites', 'styles', 'time', 'toolbar', 'ui']);
 
 /** The kit's stylesheet, an absolute path in the installed package. */
 export const STYLESHEET = path.join(SOURCE, 'styles', 'chrome-ui.css');
 
+/** The file in each vendored folder that names the package and version it was copied from (left out of the zip). */
+export const VENDOR_STAMP = 'vendored.json';
+
+/**
+ * Where a vendored copy came from.
+ *
+ * @typedef {object} VendorStamp
+ * @property {string} package The package's name.
+ * @property {string} version Its version when copied.
+ */
+
+/**
+ * The folder of an installed package, found as Node finds it (the nearest
+ * `node_modules/<name>` up from `from`), read from disk so a package whose
+ * `exports` hide its `package.json` is found too.
+ *
+ * @param {string} name - The package's name, e.g. `@duckduckgo/autoconsent`.
+ * @param {string} [from] - Where to look up from. Default the current folder.
+ * @returns {Promise<string>} The package's folder.
+ * @throws {Error} When it isn't installed.
+ */
+export async function packageDir(name, from = process.cwd()) {
+  for (let dir = path.resolve(from); ; dir = path.dirname(dir)) {
+    const candidate = path.join(dir, 'node_modules', name);
+    if (await access(path.join(candidate, 'package.json')).then(() => true, () => false)) return candidate;
+    if (path.dirname(dir) === dir) throw new Error(`${name} isn't installed (no node_modules/${name} up from ${from})`);
+  }
+}
+
+/**
+ * A package's version, from its `package.json`.
+ *
+ * @param {string} dir - The package's folder.
+ * @returns {Promise<string>} Its version.
+ */
+async function versionOf(dir) {
+  return JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf8')).version;
+}
+
 /**
- * Replace `dest` with a fresh copy of the runtime modules and stylesheet.
+ * Write a folder's {@link VENDOR_STAMP}.
+ *
+ * @param {string} dest - The vendored folder.
+ * @param {VendorStamp} source - Where the copy came from.
+ * @returns {Promise<void>}
+ */
+async function stamp(dest, source) {
+  await writeFile(path.join(dest, VENDOR_STAMP), `${JSON.stringify(source, null, 2)}\n`);
+}
+
+/**
+ * Replace `dest` with a fresh copy of the kit's runtime modules and stylesheet.
  *
  * @param {string} dest - The folder to fill, e.g. `extension/vendor/extension-kit`. Removed first.
  * @returns {Promise<string[]>} The entries copied, relative to `dest`.
  * @example
  * await vendorKit('extension/vendor/extension-kit');
- * // extension/vendor/extension-kit/index.js, …/styles/chrome-ui.css, …
+ * // extension/vendor/extension-kit/index.js, …/styles/chrome-ui.css, …, vendored.json
  */
 export async function vendorKit(dest) {
   await rm(dest, { recursive: true, force: true });
@@ -39,5 +98,69 @@ export async function vendorKit(dest) {
   for (const entry of RUNTIME_ENTRIES) {
     await cp(path.join(SOURCE, entry), path.join(dest, entry), { recursive: true });
   }
+  await stamp(dest, { package: KIT, version: await versionOf(path.dirname(SOURCE)) });
   return [...RUNTIME_ENTRIES];
 }
+
+/**
+ * Replace `dest` with named files and folders of an installed npm package.
+ * Each path is relative to the package's folder and lands in `dest` under
+ * its own name (`dist/lib.esm.js` → `dest/lib.esm.js`); a path ending in `/`
+ * has its contents copied into `dest` instead (`src/` → `dest/index.js`, …).
+ *
+ * @param {string} name - The package, as installed (`@arraypress/clean-link`).
+ * @param {readonly string[]} files - What to copy.
+ * @param {string} dest - The folder to fill, e.g. `extension/vendor/clean-link`. Removed first.
+ * @param {{from?: string}} [options] - `from`: where to look for `node_modules` from. Default the current folder.
+ * @returns {Promise<string[]>} The files and folders written, relative to `dest`.
+ * @throws {Error} When the package isn't installed, or a path isn't in it.
+ * @example
+ * await vendorPackage('@duckduckgo/autoconsent', ['dist/autoconsent.esm.js', 'rules/compact-rules.json', 'LICENSE'], 'extension/vendor/autoconsent');
+ * // or, from postinstall: extension-kit vendor extension/vendor/clean-link @arraypress/clean-link src/
+ */
+export async function vendorPackage(name, files, dest, { from } = {}) {
+  const dir = await packageDir(name, from);
+  await rm(dest, { recursive: true, force: true });
+  await mkdir(dest, { recursive: true });
+  /** @type {string[]} */
+  const written = [];
+  for (const file of files) {
+    const source = path.join(dir, file);
+    if (file.endsWith('/')) {
+      await cp(source, dest, { recursive: true });
+      written.push(...await readdir(source));
+    } else {
+      await cp(source, path.join(dest, path.basename(file)), { recursive: true });
+      written.push(path.basename(file));
+    }
+  }
+  await stamp(dest, { package: name, version: await versionOf(dir) });
+  return written;
+}
+
+/**
+ * Every vendored copy under `dir` (a folder with a {@link VENDOR_STAMP},
+ * searched to any depth) that no longer matches the package installed now:
+ * copied from another version, or from a package that's gone.
+ *
+ * @param {string} dir - The vendor folder, e.g. `extension/vendor`.
+ * @param {{from?: string}} [options] - `from`: where to look for `node_modules` from. Default the current folder.
+ * @returns {Promise<string[]>} One line per stale copy; empty when all match (or there are none).
+ * @example
+ * const stale = await checkVendored('extension/vendor');
+ * // ['extension/vendor/extension-kit is @arraypress/extension-kit 1.2.0; 1.3.0 is installed']
+ */
+export async function checkVendored(dir, { from } = {}) {
+  const entries = await readdir(dir, { recursive: true }).catch(() => /** @type {string[]} */ ([]));
+  /** @type {string[]} */
+  const stale = [];
+  for (const entry of entries.filter((file) => path.basename(file) === VENDOR_STAMP).sort()) {
+    const folder = path.join(dir, path.dirname(entry));
+    /** @type {VendorStamp} */
+    const copied = JSON.parse(await readFile(path.join(dir, entry), 'utf8'));
+    const installed = await packageDir(copied.package, from).then(versionOf, () => null);
+    if (installed === null) stale.push(`${folder} is ${copied.package} ${copied.version}, which isn't installed`);
+    else if (installed !== copied.version) stale.push(`${folder} is ${copied.package} ${copied.version}; ${installed} is installed`);
+  }
+  return stale;
+}

package/src/build/zip.d.ts

@@ -6,7 +6,8 @@
  */
 /**
  * `zip -x` patterns left out by default (a `*` crosses folders): SVG sources
- * of rendered icons, type declarations that only editors read, and Finder's
+ * of rendered icons, type declarations that only editors read, the stamps
+ * of vendored copies (`vendored.json`, build/vendor.js), and Finder's
  * `.DS_Store` files.
  */
 export declare const ZIP_EXCLUDE: readonly string[];
@@ -15,7 +16,7 @@ export declare const ZIP_EXCLUDE: readonly string[];
  * {@link ZIP_EXCLUDE}: for tests that compare the zip with the folder.
  *
  * @param {string} file - Path relative to the extension folder, forward slashes.
- * @returns {boolean} False for `icons/**.svg`, `*.d.ts` and `.DS_Store`.
+ * @returns {boolean} False for `icons/**.svg`, `*.d.ts`, a vendored copy's `vendored.json` and `.DS_Store`.
  */
 export declare function shipsFile(file: string): boolean;
 /**

package/src/build/zip.js

@@ -11,20 +11,22 @@ import path from 'node:path';
 
 /**
  * `zip -x` patterns left out by default (a `*` crosses folders): SVG sources
- * of rendered icons, type declarations that only editors read, and Finder's
+ * of rendered icons, type declarations that only editors read, the stamps
+ * of vendored copies (`vendored.json`, build/vendor.js), and Finder's
  * `.DS_Store` files.
  */
-export const ZIP_EXCLUDE = Object.freeze(['icons/*.svg', '*.d.ts', '*.DS_Store']);
+export const ZIP_EXCLUDE = Object.freeze(['icons/*.svg', '*.d.ts', '*/vendored.json', '*.DS_Store']);
 
 /**
  * Whether a file under an extension folder ships, by the same rules as
  * {@link ZIP_EXCLUDE}: for tests that compare the zip with the folder.
  *
  * @param {string} file - Path relative to the extension folder, forward slashes.
- * @returns {boolean} False for `icons/**.svg`, `*.d.ts` and `.DS_Store`.
+ * @returns {boolean} False for `icons/**.svg`, `*.d.ts`, a vendored copy's `vendored.json` and `.DS_Store`.
  */
 export function shipsFile(file) {
-  return !/^icons\/.*\.svg$/.test(file) && !file.endsWith('.d.ts') && path.posix.basename(file) !== '.DS_Store';
+  return !/^icons\/.*\.svg$/.test(file) && !file.endsWith('.d.ts') && !/\/vendored\.json$/.test(file)
+    && path.posix.basename(file) !== '.DS_Store';
 }
 
 /**

package/src/dom/focus.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The focus and the document, seen through shadow roots: what the page
+ * components need to work inside a content script's shadow root as well as
+ * in a page of their own. A shadow root's focused element shows outside it
+ * as the host, so `document.activeElement` alone can't say which item of a
+ * menu in a shadow root has the focus.
+ *
+ * @module dom/focus
+ */
+/**
+ * The element that really has the focus: the document's `activeElement`,
+ * followed into each open shadow root it's the host of.
+ *
+ * @param {Document | ShadowRoot} [root] - Where to start. Default `document`.
+ * @returns {Element | null} The focused element, or null when nothing has it.
+ * @example
+ * // A button focused in a content script's shadow root:
+ * document.activeElement; // → the shadow root's host
+ * focusedElement();       // → the button
+ */
+export declare function focusedElement(root?: Document | ShadowRoot): Element | null;
+/**
+ * The document a component is made in: `root`'s, or the page's.
+ *
+ * @param {ParentNode} [root] - Where the component goes (an element or a shadow root), if given.
+ * @returns {Document} Its document, else `document`.
+ */
+export declare function rootDocument(root?: ParentNode): Document;

package/src/dom/focus.js

@@ -0,0 +1,36 @@
+/**
+ * The focus and the document, seen through shadow roots: what the page
+ * components need to work inside a content script's shadow root as well as
+ * in a page of their own. A shadow root's focused element shows outside it
+ * as the host, so `document.activeElement` alone can't say which item of a
+ * menu in a shadow root has the focus.
+ *
+ * @module dom/focus
+ */
+
+/**
+ * The element that really has the focus: the document's `activeElement`,
+ * followed into each open shadow root it's the host of.
+ *
+ * @param {Document | ShadowRoot} [root] - Where to start. Default `document`.
+ * @returns {Element | null} The focused element, or null when nothing has it.
+ * @example
+ * // A button focused in a content script's shadow root:
+ * document.activeElement; // → the shadow root's host
+ * focusedElement();       // → the button
+ */
+export function focusedElement(root = document) {
+  let active = root.activeElement;
+  while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement;
+  return active;
+}
+
+/**
+ * The document a component is made in: `root`'s, or the page's.
+ *
+ * @param {ParentNode} [root] - Where the component goes (an element or a shadow root), if given.
+ * @returns {Document} Its document, else `document`.
+ */
+export function rootDocument(root) {
+  return root ? /** @type {Node} */ (/** @type {unknown} */ (root)).ownerDocument ?? document : document;
+}

package/src/dom/i18n.d.ts

@@ -4,6 +4,11 @@
  * `data-i18n-<attribute>="key"` (sets that attribute, e.g.
  * `data-i18n-placeholder`, `data-i18n-aria-label`).
  *
+ * The extension's name lives in one message, `extShortName`; a message that
+ * names the extension takes it as a placeholder whose content is `$1`
+ * (`"About $NAME$"`), and every lookup made without substitutions fills it
+ * in, in markup and script alike.
+ *
  * @module dom/i18n
  */
 export type I18nApi = {
@@ -19,18 +24,21 @@ export type I18nApi = {
  */
 /**
  * A message lookup that never comes back blank: a missing key shows as
- * itself, so a typo is visible on screen instead of an empty label.
+ * itself, so a typo is visible on screen instead of an empty label. Without
+ * substitutions, `$1` is the extension's name (`extShortName`).
  *
  * @param {Pick<I18nApi, 'getMessage'>} i18n - `chrome.i18n`.
  * @returns {(key: string, substitutions?: string | string[]) => string} Looks a key up.
  * @example
  * const t = translator(chrome.i18n);
  * t('optionsVersion', ['1.0.0']); // 'Version 1.0.0'
+ * t('optionsAbout');              // 'About Upright', from "About $NAME$"
  */
 export declare function translator(i18n: Pick<I18nApi, 'getMessage'>): (key: string, substitutions?: string | string[]) => string;
 /**
- * Fill every `data-i18n*` attribute under `root`, and, for a whole document,
- * set its `lang` to Chrome's UI language.
+ * Fill every `data-i18n*` attribute under `root` (a message that names the
+ * extension gets its name), and, for a whole document, set its `lang` to
+ * Chrome's UI language.
  *
  * @param {ParentNode} root - A document or an element.
  * @param {I18nApi} i18n - `chrome.i18n`.

package/src/dom/i18n.js

@@ -4,9 +4,17 @@
  * `data-i18n-<attribute>="key"` (sets that attribute, e.g.
  * `data-i18n-placeholder`, `data-i18n-aria-label`).
  *
+ * The extension's name lives in one message, `extShortName`; a message that
+ * names the extension takes it as a placeholder whose content is `$1`
+ * (`"About $NAME$"`), and every lookup made without substitutions fills it
+ * in, in markup and script alike.
+ *
  * @module dom/i18n
  */
 
+/** The message that holds the extension's name. */
+const NAME_MESSAGE = 'extShortName';
+
 /**
  * `chrome.i18n`, as far as pages need it.
  *
@@ -17,21 +25,26 @@
 
 /**
  * A message lookup that never comes back blank: a missing key shows as
- * itself, so a typo is visible on screen instead of an empty label.
+ * itself, so a typo is visible on screen instead of an empty label. Without
+ * substitutions, `$1` is the extension's name (`extShortName`).
  *
  * @param {Pick<I18nApi, 'getMessage'>} i18n - `chrome.i18n`.
  * @returns {(key: string, substitutions?: string | string[]) => string} Looks a key up.
  * @example
  * const t = translator(chrome.i18n);
  * t('optionsVersion', ['1.0.0']); // 'Version 1.0.0'
+ * t('optionsAbout');              // 'About Upright', from "About $NAME$"
  */
 export function translator(i18n) {
-  return (key, substitutions) => i18n.getMessage(key, substitutions) || key;
+  const name = i18n.getMessage(NAME_MESSAGE);
+  const named = name ? [name] : undefined;
+  return (key, substitutions = named) => i18n.getMessage(key, substitutions) || key;
 }
 
 /**
- * Fill every `data-i18n*` attribute under `root`, and, for a whole document,
- * set its `lang` to Chrome's UI language.
+ * Fill every `data-i18n*` attribute under `root` (a message that names the
+ * extension gets its name), and, for a whole document, set its `lang` to
+ * Chrome's UI language.
  *
  * @param {ParentNode} root - A document or an element.
  * @param {I18nApi} i18n - `chrome.i18n`.

package/src/dom/setup.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What every extension page does first: report its light or dark scheme
+ * for the toolbar glyph, fill its `data-i18n` text, and set its title.
+ * Browser only.
+ *
+ * @module dom/setup
+ */
+import type { I18nApi } from './i18n.js';
+import type { SchemeApi, SchemeMedia } from '../toolbar/scheme.js';
+export type PageSetup = {
+    /**
+     * The title's message (“optionsTitle”). Default: the title is left as it is.
+     */
+    title?: string;
+    /**
+     * The title's placeholders. Default: the extension's name (`translator`).
+     */
+    substitutions?: string | string[];
+    /**
+     * The page. Default `document`.
+     */
+    doc?: Document;
+    /**
+     * The scheme to report. Default the page's `matchMedia(DARK_QUERY)`.
+     */
+    media?: SchemeMedia;
+};
+/** @import { I18nApi } from './i18n.js' */
+/** @import { SchemeApi, SchemeMedia } from '../toolbar/scheme.js' */
+/**
+ * What {@link setUpPage} takes besides `chrome`.
+ *
+ * @typedef {object} PageSetup
+ * @property {string} [title] The title's message (“optionsTitle”). Default: the title is left as it is.
+ * @property {string | string[]} [substitutions] The title's placeholders. Default: the extension's name (`translator`).
+ * @property {Document} [doc] The page. Default `document`.
+ * @property {SchemeMedia} [media] The scheme to report. Default the page's `matchMedia(DARK_QUERY)`.
+ */
+/**
+ * Set up an extension page: start reporting its colour scheme (a failure is
+ * only logged: the glyph is cosmetic), localise it, and set its title.
+ *
+ * @param {SchemeApi & {i18n: I18nApi}} api - `chrome`.
+ * @param {PageSetup} [options] - The title's message, and the page.
+ * @returns {(key: string, substitutions?: string | string[]) => string} The page's message lookup
+ *   (`translator(chrome.i18n)`).
+ * @example
+ * const t = setUpPage(chrome, { title: 'optionsTitle' }); // "$NAME$ settings": 'Upright settings'
+ * t('optionsGetHelp');                                     // "Get help with $NAME$": 'Get help with Upright'
+ * // The popup, whose title Chrome doesn't show:
+ * const t = setUpPage(chrome);
+ */
+export declare function setUpPage(api: SchemeApi & {
+    i18n: I18nApi;
+}, { title, substitutions, doc, media }?: PageSetup): (key: string, substitutions?: string | string[]) => string;

package/src/dom/setup.js

@@ -0,0 +1,47 @@
+/**
+ * What every extension page does first: report its light or dark scheme
+ * for the toolbar glyph, fill its `data-i18n` text, and set its title.
+ * Browser only.
+ *
+ * @module dom/setup
+ */
+
+import { localize, translator } from './i18n.js';
+import { DARK_QUERY, watchColorScheme } from '../toolbar/scheme.js';
+
+/** @import { I18nApi } from './i18n.js' */
+/** @import { SchemeApi, SchemeMedia } from '../toolbar/scheme.js' */
+
+/**
+ * What {@link setUpPage} takes besides `chrome`.
+ *
+ * @typedef {object} PageSetup
+ * @property {string} [title] The title's message (“optionsTitle”). Default: the title is left as it is.
+ * @property {string | string[]} [substitutions] The title's placeholders. Default: the extension's name (`translator`).
+ * @property {Document} [doc] The page. Default `document`.
+ * @property {SchemeMedia} [media] The scheme to report. Default the page's `matchMedia(DARK_QUERY)`.
+ */
+
+/**
+ * Set up an extension page: start reporting its colour scheme (a failure is
+ * only logged: the glyph is cosmetic), localise it, and set its title.
+ *
+ * @param {SchemeApi & {i18n: I18nApi}} api - `chrome`.
+ * @param {PageSetup} [options] - The title's message, and the page.
+ * @returns {(key: string, substitutions?: string | string[]) => string} The page's message lookup
+ *   (`translator(chrome.i18n)`).
+ * @example
+ * const t = setUpPage(chrome, { title: 'optionsTitle' }); // "$NAME$ settings": 'Upright settings'
+ * t('optionsGetHelp');                                     // "Get help with $NAME$": 'Get help with Upright'
+ * // The popup, whose title Chrome doesn't show:
+ * const t = setUpPage(chrome);
+ */
+export function setUpPage(api, { title, substitutions, doc = document, media } = {}) {
+  const t = translator(api.i18n);
+  // The toolbar glyph follows this page's light or dark scheme.
+  watchColorScheme(api, media ?? /** @type {Window} */ (doc.defaultView).matchMedia(DARK_QUERY))
+    .catch((error) => console.debug('Reporting the colour scheme:', error));
+  localize(doc, api.i18n);
+  if (title) doc.title = t(title, substitutions);
+  return t;
+}

package/src/index.d.ts

@@ -1,7 +1,8 @@
 /**
  * The kit's browser half: what an extension's pages, offscreen document and
  * service worker load, Chrome's page components (the ⋮ menu, the one-field
- * dialog, the toast with Undo) included. Every function takes the `chrome`
+ * dialog, the toast with Undo, a settings card's site list) and per-site
+ * lists' sites included. Every function takes the `chrome`
  * APIs it uses as arguments, so tests run the real logic against fakes.
  *
  * Build-time helpers are in `@arraypress/extension-kit/build`, test helpers
@@ -12,21 +13,27 @@
  */
 export { githubAboutLinks, isPlaceholder } from './about/links.js';
 export { setShortcuts } from './commands/shortcuts.js';
+export { focusedElement } from './dom/focus.js';
 export { localize, translator } from './dom/i18n.js';
 export { byId, setAboutLinks, statusFlasher, valueRow } from './dom/page.js';
+export { setUpPage } from './dom/setup.js';
 export { createSettingsSaver } from './settings/saver.js';
 export { MAX_SYNC_ITEM_BYTES } from './settings/storage.js';
 export { createSettingsStore } from './settings/store.js';
+export { MAX_HOST_LENGTH, hostPatterns, onSite, originPattern, siteHost, siteLabel, siteOrigin, withSite, withSiteReplaced, withoutSite, } from './sites/sites.js';
+export { within } from './time/time.js';
 export { POLL_MS, watchSchemeOffscreen } from './toolbar/offscreen.js';
 export { DARK_QUERY, TOOLBAR_DARK_KEY, TOOLBAR_SCHEME, reportColorScheme, schemeSender, watchColorScheme } from './toolbar/scheme.js';
 export { OFFSCREEN_PATH, TOOLBAR_ICON_DIR, createToolbarTheme, startToolbarTheme, toolbarIcon, watchFromOffscreen, } from './toolbar/theme.js';
 export { MENU_EDGE, createMenu, isInside, menuPosition, moreActionsButton } from './ui/menu.js';
+export { SITE_LIST_MESSAGES, SITE_LIST_WORDS, createSiteList } from './ui/site-list.js';
 export { askText, checkText } from './ui/text-dialog.js';
 export { TOAST_MS, createToast } from './ui/toast.js';
 export type ActionMenu = import('./ui/menu.js').ActionMenu;
 export type MenuEntry = import('./ui/menu.js').MenuEntry;
 export type MenuItem = import('./ui/menu.js').MenuItem;
 export type MenuPlace = import('./ui/menu.js').MenuPlace;
+export type SiteList = import('./ui/site-list.js').SiteList;
 export type TextRequest = import('./ui/text-dialog.js').TextRequest;
 export type Toast = import('./ui/toast.js').Toast;
 /**
@@ -36,6 +43,7 @@ export type Toast = import('./ui/toast.js').Toast;
  * @typedef {import('./ui/menu.js').MenuEntry} MenuEntry
  * @typedef {import('./ui/menu.js').MenuItem} MenuItem
  * @typedef {import('./ui/menu.js').MenuPlace} MenuPlace
+ * @typedef {import('./ui/site-list.js').SiteList} SiteList
  * @typedef {import('./ui/text-dialog.js').TextRequest} TextRequest
  * @typedef {import('./ui/toast.js').Toast} Toast
  */