@arraypress/extension-kit 1.9.0 → 1.10.0

package/src/content/elements.js

@@ -0,0 +1,88 @@
+/**
+ * A page's rendered elements, for a content script that reads them all: in
+ * document order, into open shadow roots and closed ones (where Chrome lets
+ * an extension see them, `chrome.dom.openOrClosedShadowRoot`), leaving out
+ * what Chrome doesn't render and what holds no page content (scripts,
+ * styles, templates, `<head>`).
+ *
+ * @module content/elements
+ */
+
+/** Elements that are never drawn as the page's content, nor anything inside them. */
+const NEVER_RENDERED = new Set(['script', 'style', 'noscript', 'template', 'head', 'title', 'meta', 'link']);
+
+/** The most elements read (a very long page's first ones). */
+export const MAX_ELEMENTS = 20_000;
+
+/**
+ * An element's shadow root, closed ones too where Chrome lets the extension see them.
+ *
+ * @param {Element} element - The element.
+ * @returns {ShadowRoot | null} Its shadow root.
+ * @example
+ * const root = shadowRootOf(host); // a closed root, from a content script
+ */
+export function shadowRootOf(element) {
+  const dom = /** @type {{dom?: {openOrClosedShadowRoot?: (element: HTMLElement) => ShadowRoot | null}}} */ (globalThis.chrome ?? {}).dom;
+  return (dom?.openOrClosedShadowRoot && element instanceof HTMLElement ? dom.openOrClosedShadowRoot(element) : element.shadowRoot) ?? null;
+}
+
+/**
+ * Every rendered element from the body down, in document order, a shadow root's elements before
+ * its host's children. An element Chrome doesn't draw (`visibility: hidden`) is left out, but
+ * what's inside it is still read (a child can be visible again), as is what's inside a
+ * `display: contents` element (a slot), which has no box of its own; nothing inside a
+ * `display: none` or `content-visibility: hidden` part is.
+ *
+ * @param {Document} doc - The page.
+ * @param {{skip?: (element: Element) => boolean, limit?: number}} [options] - `skip`: elements left
+ *   out with what's inside (the extension's overlay); `limit`: the most elements ({@link MAX_ELEMENTS}).
+ * @returns {Element[]} The elements.
+ * @example
+ * for (const element of renderedElements(document, { skip: isLayer })) read(element);
+ */
+export function renderedElements(doc, { skip = () => false, limit = MAX_ELEMENTS } = {}) {
+  /** @type {Element[]} */
+  const found = [];
+  /** @param {Element} element */
+  const visit = (element) => {
+    if (found.length >= limit || NEVER_RENDERED.has(element.localName) || skip(element)) return;
+    if (element.checkVisibility()) {
+      if (element.checkVisibility({ visibilityProperty: true })) found.push(element);
+    } else if (element.ownerDocument.defaultView?.getComputedStyle(element).display !== 'contents') {
+      return;
+    }
+    const shadow = shadowRootOf(element);
+    if (shadow) for (const child of shadow.children) visit(child);
+    for (const child of element.children) visit(child);
+  };
+  if (doc.body) visit(doc.body);
+  return found;
+}
+
+/**
+ * The origins of a page's frames that are another site's: their content isn't the page's to read,
+ * and an extension reads them only with that site's access (`chrome.permissions.request`, from a
+ * click). Frames inside shadow roots are found too.
+ *
+ * @param {Document} doc - The page.
+ * @param {Element[]} [elements] - Its elements, when already listed ({@link renderedElements}).
+ * @returns {string[]} Their origins (`https://ads.example.net`), each once.
+ * @example
+ * otherSiteFrames(document); // ['https://www.youtube.com']
+ */
+export function otherSiteFrames(doc, elements = renderedElements(doc)) {
+  const own = doc.location?.origin;
+  /** @type {Set<string>} */
+  const sites = new Set();
+  for (const frame of elements) {
+    if (frame.localName !== 'iframe' && frame.localName !== 'frame') continue;
+    try {
+      const url = new URL(/** @type {HTMLIFrameElement} */ (frame).src);
+      if (/^https?:$/.test(url.protocol) && url.origin !== own) sites.add(url.origin);
+    } catch {
+      // No address (srcdoc, about:blank): the page's own.
+    }
+  }
+  return [...sites];
+}

package/src/content/highlight.d.ts

@@ -0,0 +1,54 @@
+/**
+ * “Show on page”: boxes in Chrome's blue (DevTools' highlight) around a set of
+ * elements, kept on them as the page scrolls or resizes, until cleared (the
+ * extension's button again, another set, or Esc). The first can be scrolled
+ * into view. The boxes go in the extension's own overlay (`pageOverlay`), so
+ * the page's styles can't touch them.
+ *
+ * @module content/highlight
+ */
+/** The most elements boxed at once. */
+export declare const MAX_BOXES = 500;
+/** The boxes' styles, for the overlay's stylesheet. @type {string} */
+export declare const HIGHLIGHT_CSS: string;
+export type Highlighter = {
+    /**
+     * Box elements (the
+     * ones still in the page, the first {@link MAX_BOXES}), clearing any boxed before; `reveal`
+     * scrolls the first into view. Returns how many are boxed.
+     */
+    show: (elements: Element[], options?: {
+        reveal?: boolean;
+    }) => number;
+    /**
+     * Take the boxes away.
+     */
+    clear: () => void;
+};
+/**
+ * A page's highlight: one set of elements boxed at a time.
+ *
+ * @typedef {object} Highlighter
+ * @property {(elements: Element[], options?: {reveal?: boolean}) => number} show Box elements (the
+ *   ones still in the page, the first {@link MAX_BOXES}), clearing any boxed before; `reveal`
+ *   scrolls the first into view. Returns how many are boxed.
+ * @property {() => void} clear Take the boxes away.
+ */
+/**
+ * A highlighter for a page.
+ *
+ * @param {Document} doc - The page.
+ * @param {object} options
+ * @param {() => ParentNode} options.root - Where boxes go: the overlay's shadow root, made when first needed.
+ * @param {() => void} [options.onClear] - After the boxes go (take an empty overlay away).
+ * @param {number} [options.max] - The most elements boxed. Default {@link MAX_BOXES}.
+ * @returns {Highlighter} It.
+ * @example
+ * const highlight = createHighlighter(document, { root: () => layer(document), onClear: tidyLayer });
+ * highlight.show(elements, { reveal: true });
+ */
+export declare function createHighlighter(doc: Document, { root, onClear, max }: {
+    root: () => ParentNode;
+    onClear?: () => void;
+    max?: number;
+}): Highlighter;

package/src/content/highlight.js

@@ -0,0 +1,92 @@
+/**
+ * “Show on page”: boxes in Chrome's blue (DevTools' highlight) around a set of
+ * elements, kept on them as the page scrolls or resizes, until cleared (the
+ * extension's button again, another set, or Esc). The first can be scrolled
+ * into view. The boxes go in the extension's own overlay (`pageOverlay`), so
+ * the page's styles can't touch them.
+ *
+ * @module content/highlight
+ */
+
+/** The most elements boxed at once. */
+export const MAX_BOXES = 500;
+
+/** The boxes' styles, for the overlay's stylesheet. @type {string} */
+export const HIGHLIGHT_CSS = '.box { position: fixed; box-sizing: border-box; border: 2px solid rgb(26 115 232); background: rgb(26 115 232 / 0.12); border-radius: 2px; pointer-events: none; }';
+
+/**
+ * A page's highlight: one set of elements boxed at a time.
+ *
+ * @typedef {object} Highlighter
+ * @property {(elements: Element[], options?: {reveal?: boolean}) => number} show Box elements (the
+ *   ones still in the page, the first {@link MAX_BOXES}), clearing any boxed before; `reveal`
+ *   scrolls the first into view. Returns how many are boxed.
+ * @property {() => void} clear Take the boxes away.
+ */
+
+/**
+ * A highlighter for a page.
+ *
+ * @param {Document} doc - The page.
+ * @param {object} options
+ * @param {() => ParentNode} options.root - Where boxes go: the overlay's shadow root, made when first needed.
+ * @param {() => void} [options.onClear] - After the boxes go (take an empty overlay away).
+ * @param {number} [options.max] - The most elements boxed. Default {@link MAX_BOXES}.
+ * @returns {Highlighter} It.
+ * @example
+ * const highlight = createHighlighter(document, { root: () => layer(document), onClear: tidyLayer });
+ * highlight.show(elements, { reveal: true });
+ */
+export function createHighlighter(doc, { root, onClear = () => {}, max = MAX_BOXES }) {
+  const view = /** @type {Window} */ (doc.defaultView);
+  /** @type {{elements: Element[], boxes: HTMLElement[]} | null} */
+  let shown = null;
+  let pending = 0;
+
+  const draw = () => {
+    pending = 0;
+    if (!shown) return;
+    for (const box of shown.boxes) box.remove();
+    shown.boxes = shown.elements.flatMap((element) => [...element.getClientRects()].filter((rect) => rect.width && rect.height
+      && rect.bottom > 0 && rect.top < view.innerHeight && rect.right > 0 && rect.left < view.innerWidth).map((rect) => {
+      const box = doc.createElement('div');
+      box.className = 'box';
+      Object.assign(box.style, { left: `${rect.left - 2}px`, top: `${rect.top - 2}px`, width: `${rect.width + 4}px`, height: `${rect.height + 4}px` });
+      return box;
+    }));
+    root().append(...shown.boxes);
+  };
+  const update = () => {
+    if (!pending) pending = view.requestAnimationFrame(draw);
+  };
+  /** @param {KeyboardEvent} event */
+  const key = (event) => {
+    if (event.key === 'Escape') clear();
+  };
+
+  function clear() {
+    if (!shown) return;
+    view.removeEventListener('scroll', update, true);
+    view.removeEventListener('resize', update);
+    view.removeEventListener('keydown', key, true);
+    for (const box of shown.boxes) box.remove();
+    shown = null;
+    onClear();
+  }
+
+  /** @type {Highlighter['show']} */
+  function show(elements, { reveal = false } = {}) {
+    clear();
+    const some = elements.filter((element) => element.isConnected).slice(0, max);
+    if (!some.length) return 0;
+    if (reveal) some[0].scrollIntoView({ block: 'center', inline: 'nearest' });
+    shown = { elements: some, boxes: [] };
+    view.addEventListener('scroll', update, { capture: true, passive: true });
+    view.addEventListener('resize', update, { passive: true });
+    view.addEventListener('keydown', key, true);
+    draw();
+    return some.length;
+  }
+
+  return { show, clear };
+}

package/src/content/overlay.d.ts

@@ -30,18 +30,28 @@ export type PageOverlay = {
  */
 /**
  * Put an overlay on the page, replacing one of the same name a run before left.
- * The host's own styles are reset (`all: initial`) before `css`, so the page's
- * rules for unknown elements can't move or hide it; `css` styles `:host` and what's inside.
+ *
+ * The host's own styles are reset inline (`all: initial !important`), so the page's rules for
+ * unknown elements can't move or hide it. That reset also beats a plain `:host { … }` rule in
+ * `css` and an inline `host.style.x = …`: give the host's own styles as `hostStyle`, set inline
+ * with `!important` after the reset. `css` styles what's inside (and `:host` custom properties,
+ * which the reset doesn't touch).
  *
  * @param {Document} doc - The page.
- * @param {{name: string, css: string}} options - `name`: the host's element name, with a hyphen
- *   (never registered: a plain element); `css`: the overlay's styles.
+ * @param {{name: string, css: string, hostStyle?: Record<string, string>}} options - `name`: the
+ *   host's element name, with a hyphen (never registered: a plain element); `css`: the overlay's
+ *   styles; `hostStyle`: the host's own styles by CSS property name (`'z-index'`), each `!important`.
  * @returns {PageOverlay} The overlay.
  * @example
- * const { root, remove } = pageOverlay(document, { name: 'better-fonts-inspector', css: ':host { position: fixed; inset: 0; pointer-events: none; }' });
+ * const { root, remove } = pageOverlay(document, {
+ *   name: 'better-fonts-inspector',
+ *   hostStyle: { position: 'fixed', inset: '0', 'z-index': '2147483647', 'pointer-events': 'none' },
+ *   css: '.card { position: absolute; }',
+ * });
  * root.append(card);
  */
-export declare function pageOverlay(doc: Document, { name, css }: {
+export declare function pageOverlay(doc: Document, { name, css, hostStyle }: {
     name: string;
     css: string;
+    hostStyle?: Record<string, string>;
 }): PageOverlay;

package/src/content/overlay.js

@@ -18,21 +18,31 @@
 
 /**
  * Put an overlay on the page, replacing one of the same name a run before left.
- * The host's own styles are reset (`all: initial`) before `css`, so the page's
- * rules for unknown elements can't move or hide it; `css` styles `:host` and what's inside.
+ *
+ * The host's own styles are reset inline (`all: initial !important`), so the page's rules for
+ * unknown elements can't move or hide it. That reset also beats a plain `:host { … }` rule in
+ * `css` and an inline `host.style.x = …`: give the host's own styles as `hostStyle`, set inline
+ * with `!important` after the reset. `css` styles what's inside (and `:host` custom properties,
+ * which the reset doesn't touch).
  *
  * @param {Document} doc - The page.
- * @param {{name: string, css: string}} options - `name`: the host's element name, with a hyphen
- *   (never registered: a plain element); `css`: the overlay's styles.
+ * @param {{name: string, css: string, hostStyle?: Record<string, string>}} options - `name`: the
+ *   host's element name, with a hyphen (never registered: a plain element); `css`: the overlay's
+ *   styles; `hostStyle`: the host's own styles by CSS property name (`'z-index'`), each `!important`.
  * @returns {PageOverlay} The overlay.
  * @example
- * const { root, remove } = pageOverlay(document, { name: 'better-fonts-inspector', css: ':host { position: fixed; inset: 0; pointer-events: none; }' });
+ * const { root, remove } = pageOverlay(document, {
+ *   name: 'better-fonts-inspector',
+ *   hostStyle: { position: 'fixed', inset: '0', 'z-index': '2147483647', 'pointer-events': 'none' },
+ *   css: '.card { position: absolute; }',
+ * });
  * root.append(card);
  */
-export function pageOverlay(doc, { name, css }) {
+export function pageOverlay(doc, { name, css, hostStyle = {} }) {
   for (const old of doc.querySelectorAll(name)) old.remove();
   const host = doc.createElement(name);
   host.style.setProperty('all', 'initial', 'important');
+  for (const [property, value] of Object.entries(hostStyle)) host.style.setProperty(property, value, 'important');
   const root = host.attachShadow({ mode: 'closed' });
   const style = doc.createElement('style');
   style.textContent = css;

package/src/content/page-toast.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Chrome's own confirmation in a web page: the dark pill with a check mark that Chrome shows at
+ * the bottom of the window for “Link copied”, for a content script that just did something the
+ * person asked for from a menu or a shortcut. In a closed shadow root (the kit's `pageOverlay`)
+ * the page can't style, as a popover in the top layer, over anything the page stacks; light on
+ * a dark system. One at a time: a new one replaces the last.
+ *
+ * @module content/page-toast
+ */
+/** How long it shows, in ms (as Chrome's “Link copied”). */
+export declare const PAGE_TOAST_MS = 4000;
+/**
+ * Show Chrome's confirmation toast in a page.
+ *
+ * @param {Document} doc - The page.
+ * @param {string} text - What it says (“Link copied”).
+ * @param {{name?: string, ms?: number}} [options] - `name`: the overlay's element name (the
+ *   extension's own, with a hyphen); `ms`: how long it shows. Defaults `extension-toast`, {@link PAGE_TOAST_MS}.
+ * @returns {() => void} Takes it away now.
+ * @example
+ * showPageToast(document, chrome.i18n.getMessage('copied'), { name: 'better-copy-toast' });
+ */
+export declare function showPageToast(doc: Document, text: string, { name, ms }?: {
+    name?: string;
+    ms?: number;
+}): () => void;

package/src/content/page-toast.js

@@ -0,0 +1,72 @@
+/**
+ * Chrome's own confirmation in a web page: the dark pill with a check mark that Chrome shows at
+ * the bottom of the window for “Link copied”, for a content script that just did something the
+ * person asked for from a menu or a shortcut. In a closed shadow root (the kit's `pageOverlay`)
+ * the page can't style, as a popover in the top layer, over anything the page stacks; light on
+ * a dark system. One at a time: a new one replaces the last.
+ *
+ * @module content/page-toast
+ */
+
+import { pageOverlay } from './overlay.js';
+
+/** How long it shows, in ms (as Chrome's “Link copied”). */
+export const PAGE_TOAST_MS = 4000;
+
+/** The toast's look: Chrome's cr-toast colours, its 48px pill, the check mark. */
+const CSS = `
+  .toast { position: fixed; inset: auto auto 24px 50%; margin: 0; transform: translateX(-50%); z-index: 2147483647;
+    display: flex; align-items: center; gap: 12px; min-height: 48px; max-width: calc(100vw - 48px);
+    box-sizing: border-box; padding: 0 20px 0 16px; border: 0; border-radius: 24px; overflow: hidden;
+    background: rgb(48 48 48); color: rgb(242 242 242); box-shadow: 0 2px 4px 0 rgb(0 0 0 / 0.28);
+    font: 13px/20px system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; letter-spacing: normal; text-align: start;
+    animation: in 150ms ease-out; }
+  .toast:not(:popover-open)[popover] { display: none; }
+  .text { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  svg { width: 20px; height: 20px; fill: currentColor; flex: none; }
+  @media (prefers-color-scheme: dark) { .toast { background: rgb(227 227 227); color: rgb(31 31 31); } }
+  @keyframes in { from { opacity: 0; translate: 0 8px; } }
+  @media (prefers-reduced-motion: reduce) { .toast { animation: none; } }`;
+
+/** Chrome's check mark (Material “check”). */
+const CHECK = 'M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z';
+
+/**
+ * Show Chrome's confirmation toast in a page.
+ *
+ * @param {Document} doc - The page.
+ * @param {string} text - What it says (“Link copied”).
+ * @param {{name?: string, ms?: number}} [options] - `name`: the overlay's element name (the
+ *   extension's own, with a hyphen); `ms`: how long it shows. Defaults `extension-toast`, {@link PAGE_TOAST_MS}.
+ * @returns {() => void} Takes it away now.
+ * @example
+ * showPageToast(document, chrome.i18n.getMessage('copied'), { name: 'better-copy-toast' });
+ */
+export function showPageToast(doc, text, { name = 'extension-toast', ms = PAGE_TOAST_MS } = {}) {
+  const { root, remove } = pageOverlay(doc, { name, css: CSS });
+  const toast = doc.createElement('div');
+  toast.className = 'toast';
+  toast.setAttribute('role', 'status');
+  const NS = 'http://www.w3.org/2000/svg';
+  const svg = doc.createElementNS(NS, 'svg');
+  svg.setAttribute('viewBox', '0 0 24 24');
+  svg.setAttribute('aria-hidden', 'true');
+  const path = doc.createElementNS(NS, 'path');
+  path.setAttribute('d', CHECK);
+  svg.append(path);
+  const words = doc.createElement('span');
+  words.className = 'text';
+  words.textContent = text;
+  toast.append(svg, words);
+  root.append(toast);
+  // The top layer, over the page's own fixed bars and open dialogs, where popovers exist.
+  if (typeof toast.showPopover === 'function') {
+    toast.popover = 'manual';
+    toast.showPopover();
+  }
+  const timer = setTimeout(remove, ms);
+  return () => {
+    clearTimeout(timer);
+    remove();
+  };
+}

package/src/dom/copy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Copying in several formats at once: plain text, and HTML for apps that paste it rich (a link
+ * with its title in Google Docs, Slack or Notion), from a page, a popup or a content script.
+ * Says whether it worked, so a caller can offer another way when the page won't let it.
+ *
+ * Chrome lets the focused page write without a click (it grants clipboard-write to the active
+ * tab), so a content script can copy from a context-menu click or a keyboard shortcut; a page
+ * served over plain HTTP has no clipboard API, and one with `Permissions-Policy:
+ * clipboard-write=()` refuses it: there the copy command is tried, which needs a click in the page.
+ *
+ * @module dom/copy
+ */
+export type ClipboardFormats = {
+    /**
+     * Plain text, for every app.
+     */
+    text: string;
+    /**
+     * HTML, for apps that paste formatted text.
+     */
+    html?: string;
+};
+/**
+ * Put text, and HTML when given, on the clipboard: the clipboard API (one item holding both
+ * formats), else the copy command.
+ *
+ * @param {Document} doc - The page, popup or content script's document.
+ * @param {ClipboardFormats} formats - Plain text, and HTML for rich pasting.
+ * @returns {Promise<boolean>} Whether it's on the clipboard.
+ * @example
+ * const link = document.createElement('a');
+ * link.href = url;
+ * link.textContent = title;
+ * if (!(await copyFormats(document, { text: `${title} – ${url}`, html: link.outerHTML }))) offerCopyButton();
+ */
+export declare function copyFormats(doc: Document, { text, html }: ClipboardFormats): Promise<boolean>;

package/src/dom/copy.js

@@ -0,0 +1,84 @@
+/**
+ * Copying in several formats at once: plain text, and HTML for apps that paste it rich (a link
+ * with its title in Google Docs, Slack or Notion), from a page, a popup or a content script.
+ * Says whether it worked, so a caller can offer another way when the page won't let it.
+ *
+ * Chrome lets the focused page write without a click (it grants clipboard-write to the active
+ * tab), so a content script can copy from a context-menu click or a keyboard shortcut; a page
+ * served over plain HTTP has no clipboard API, and one with `Permissions-Policy:
+ * clipboard-write=()` refuses it: there the copy command is tried, which needs a click in the page.
+ *
+ * @module dom/copy
+ */
+
+/**
+ * What to put on the clipboard.
+ *
+ * @typedef {object} ClipboardFormats
+ * @property {string} text Plain text, for every app.
+ * @property {string} [html] HTML, for apps that paste formatted text.
+ */
+
+/**
+ * The copy command, with a copy listener that writes the formats: it runs first (capture, on the
+ * window) and stops the page's own listeners from changing what's copied.
+ *
+ * @param {Document} doc - The page.
+ * @param {ClipboardFormats} formats - What to copy.
+ * @returns {boolean} Whether the command ran and wrote them.
+ */
+function copyCommand(doc, { text, html }) {
+  const view = doc.defaultView;
+  if (!view) return false;
+  let wrote = false;
+  /** @param {ClipboardEvent} event */
+  const onCopy = (event) => {
+    if (!event.clipboardData) return;
+    event.clipboardData.setData('text/plain', text);
+    if (html !== undefined) event.clipboardData.setData('text/html', html);
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    wrote = true;
+  };
+  view.addEventListener('copy', onCopy, true);
+  try {
+    return doc.execCommand('copy') && wrote;
+  } catch {
+    return false;
+  } finally {
+    view.removeEventListener('copy', onCopy, true);
+  }
+}
+
+/**
+ * Put text, and HTML when given, on the clipboard: the clipboard API (one item holding both
+ * formats), else the copy command.
+ *
+ * @param {Document} doc - The page, popup or content script's document.
+ * @param {ClipboardFormats} formats - Plain text, and HTML for rich pasting.
+ * @returns {Promise<boolean>} Whether it's on the clipboard.
+ * @example
+ * const link = document.createElement('a');
+ * link.href = url;
+ * link.textContent = title;
+ * if (!(await copyFormats(document, { text: `${title} – ${url}`, html: link.outerHTML }))) offerCopyButton();
+ */
+export async function copyFormats(doc, { text, html }) {
+  const view = doc.defaultView;
+  const clipboard = view?.navigator.clipboard;
+  if (view && clipboard) {
+    try {
+      if (html === undefined) await clipboard.writeText(text);
+      else {
+        await clipboard.write([new view.ClipboardItem({
+          'text/plain': new view.Blob([text], { type: 'text/plain' }),
+          'text/html': new view.Blob([html], { type: 'text/html' }),
+        })]);
+      }
+      return true;
+    } catch {
+      // No focus, or the page's permissions policy: the copy command below.
+    }
+  }
+  return copyCommand(doc, { text, html });
+}

package/src/dom/i18n.d.ts

@@ -45,3 +45,20 @@ export declare function translator(i18n: Pick<I18nApi, 'getMessage'>): (key: str
  * @returns {void}
  */
 export declare function localize(root: ParentNode, i18n: I18nApi): void;
+/**
+ * A count in words, its number written as the person's language writes numbers: one message for
+ * one, another (with the number as `$1`) for any other count.
+ *
+ * @param {number} count - How many.
+ * @param {string} one - The message for one (`"1 colour"`).
+ * @param {string} many - The message for others (`"$COUNT$ colours"`, its placeholder `$1`).
+ * @param {{t: (key: string, substitutions?: string | string[]) => string, lang: string}} words - The
+ *   page's message lookup and the UI language.
+ * @returns {string} The words.
+ * @example
+ * counted(1200, 'panelColoursOne', 'panelColours', { t, lang: 'en-GB' }); // '1,200 colours'
+ */
+export declare const counted: (count: number, one: string, many: string, { t, lang }: {
+    t: (key: string, substitutions?: string | string[]) => string;
+    lang: string;
+}) => string;

package/src/dom/i18n.js

@@ -60,3 +60,18 @@ export function localize(root, i18n) {
   }
   if ('documentElement' in root) /** @type {Document} */ (root).documentElement.lang = i18n.getUILanguage();
 }
+
+/**
+ * A count in words, its number written as the person's language writes numbers: one message for
+ * one, another (with the number as `$1`) for any other count.
+ *
+ * @param {number} count - How many.
+ * @param {string} one - The message for one (`"1 colour"`).
+ * @param {string} many - The message for others (`"$COUNT$ colours"`, its placeholder `$1`).
+ * @param {{t: (key: string, substitutions?: string | string[]) => string, lang: string}} words - The
+ *   page's message lookup and the UI language.
+ * @returns {string} The words.
+ * @example
+ * counted(1200, 'panelColoursOne', 'panelColours', { t, lang: 'en-GB' }); // '1,200 colours'
+ */
+export const counted = (count, one, many, { t, lang }) => (count === 1 ? t(one) : t(many, [count.toLocaleString(lang)]));

package/src/dom/make.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Making a page's elements in a line: an element with its class and text, an
+ * icon from the page's SVG sprite, and Chrome's 24px icon button with its
+ * tooltip. For extension pages and content-script overlays alike (pass the
+ * document the element belongs to).
+ *
+ * @module dom/make
+ */
+/**
+ * An element with a class and text.
+ *
+ * @template {keyof HTMLElementTagNameMap} K
+ * @param {K} tag - Its tag.
+ * @param {string} [className] - Its class.
+ * @param {string} [text] - Its text.
+ * @param {Document} [doc] - Its document. Default `document`.
+ * @returns {HTMLElementTagNameMap[K]} It.
+ * @example
+ * make('span', 'meta', '12 colours');
+ */
+export declare function make<K extends keyof HTMLElementTagNameMap>(tag: K, className?: string, text?: string, doc?: Document): HTMLElementTagNameMap[K];
+/**
+ * An icon from the page's SVG sprite (`<symbol id="i-copy">`), hidden from screen readers.
+ *
+ * @param {string} id - The symbol's id, without `#`.
+ * @param {string} [className] - More classes beside `icon`.
+ * @param {Document} [doc] - Its document. Default `document`.
+ * @returns {SVGSVGElement} The icon.
+ * @example
+ * button.append(spriteIcon('i-copy'));
+ */
+export declare function spriteIcon(id: string, className?: string, doc?: Document): SVGSVGElement;
+/**
+ * Chrome's icon button (chrome-ui.css `.icon-button`): an icon, its label as tooltip and for
+ * screen readers.
+ *
+ * @param {object} options
+ * @param {string} options.icon - The sprite symbol's id.
+ * @param {string} options.label - What it does.
+ * @param {() => void} options.onClick - Doing it.
+ * @param {string} [options.className] - More classes.
+ * @param {Document} [options.doc] - Its document. Default `document`.
+ * @returns {HTMLButtonElement} The button.
+ * @example
+ * iconButton({ icon: 'i-copy', label: 'Copy', onClick: () => copy(hex) });
+ */
+export declare function iconButton({ icon, label, onClick, className, doc }: {
+    icon: string;
+    label: string;
+    onClick: () => void;
+    className?: string;
+    doc?: Document;
+}): HTMLButtonElement;