@arraypress/extension-kit 1.2.0 → 1.4.0

package/src/testing/index.js

@@ -1,12 +1,18 @@
 /**
  * The kit's test helpers: a fake `chrome.storage`, Playwright helpers for
- * end-to-end tests and a server for their pages, Chrome's install warnings
- * and saved tab groups, and checks for a packaging test. Node only.
+ * end-to-end tests (time limits, a pool, a browser that passes for a
+ * person's) and a server for their pages, Chrome's install warnings and
+ * saved tab groups, and checks for a packaging test. Node only.
  *
  * @module testing
  */
 
-export { checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until } from './e2e.js';
+export { TEST_BUILDS_ENV, testBuildDir } from '../build/test-build.js';
+export { chromeUserAgent, closeOnSignal, realisticBrowser } from './browser.js';
+export {
+  CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until,
+} from './e2e.js';
+export { eachLimited } from './pool.js';
 export { serve } from './server.js';
 export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';

package/src/testing/pool.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Working through a list a few at a time: a live check of many sites, each
+ * in one of a few browsers.
+ *
+ * @module testing/pool
+ */
+/**
+ * Run `work` on every item, at most `limit` at once, each slot taking the
+ * next item as it finishes one. Errors are `work`'s to handle: one that
+ * throws stops its slot, and the returned promise rejects once the others
+ * are done.
+ *
+ * @template T
+ * @param {readonly T[]} items - The items.
+ * @param {number} limit - At most this many at once.
+ * @param {(item: T, slot: number, index: number) => Promise<void>} work - Deals with one item;
+ *   `slot` (0 to limit − 1) is the same for everything one slot does, for per-slot resources
+ *   (a browser each).
+ * @returns {Promise<void>} Once every item is done.
+ * @example
+ * await eachLimited(sites, 3, async (site, slot) => check(site, browsers[slot]));
+ */
+export declare function eachLimited<T>(items: readonly T[], limit: number, work: (item: T, slot: number, index: number) => Promise<void>): Promise<void>;

package/src/testing/pool.js

@@ -0,0 +1,33 @@
+/**
+ * Working through a list a few at a time: a live check of many sites, each
+ * in one of a few browsers.
+ *
+ * @module testing/pool
+ */
+
+/**
+ * Run `work` on every item, at most `limit` at once, each slot taking the
+ * next item as it finishes one. Errors are `work`'s to handle: one that
+ * throws stops its slot, and the returned promise rejects once the others
+ * are done.
+ *
+ * @template T
+ * @param {readonly T[]} items - The items.
+ * @param {number} limit - At most this many at once.
+ * @param {(item: T, slot: number, index: number) => Promise<void>} work - Deals with one item;
+ *   `slot` (0 to limit − 1) is the same for everything one slot does, for per-slot resources
+ *   (a browser each).
+ * @returns {Promise<void>} Once every item is done.
+ * @example
+ * await eachLimited(sites, 3, async (site, slot) => check(site, browsers[slot]));
+ */
+export async function eachLimited(items, limit, work) {
+  let next = 0;
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async (_, slot) => {
+    while (next < items.length) {
+      const index = next;
+      next += 1;
+      await work(items[index], slot, index);
+    }
+  }));
+}

package/src/time/time.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Time limits for work that may never finish: a Chrome call a service worker
+ * shouldn't wait on forever, or, in tests that drive a real browser, a page
+ * that stops responding. Runs anywhere (worker, page, Node).
+ *
+ * @module time/time
+ */
+/**
+ * Settle `promise` within `ms`, or settle the way `late` says. The timer is
+ * cleared as soon as either happens, so a finished run isn't kept waiting
+ * for it. The work itself isn't stopped.
+ *
+ * @template T
+ * @param {Promise<T>} promise - The work.
+ * @param {number} ms - The limit.
+ * @param {(resolve: (value: T) => void, reject: (error: Error) => void) => void} late - Runs when the
+ *   limit passes first.
+ * @returns {Promise<T>} The work's outcome, or `late`'s.
+ */
+export declare function deadline<T>(promise: Promise<T>, ms: number, late: (resolve: (value: T) => void, reject: (error: Error) => void) => void): Promise<T>;
+/**
+ * A promise's value within a time limit, or `fallback` when it's late or
+ * fails: for a step to give up on and go past (a Chrome call that never
+ * answers, a renderer that stopped responding, a close that never returns).
+ * The work itself isn't stopped; the timer is cleared once it settles.
+ *
+ * @template T
+ * @param {Promise<T>} promise - The work.
+ * @param {number} ms - The limit.
+ * @param {T} fallback - What to give if it's late or fails.
+ * @returns {Promise<T>} Its value, or the fallback. Never rejects.
+ * @example
+ * const list = await within(handled(worker, page), 8000, []);
+ * await within(page.close(), 15000, undefined);
+ */
+export declare function within<T>(promise: Promise<T>, ms: number, fallback: T): Promise<T>;

package/src/time/time.js

@@ -0,0 +1,47 @@
+/**
+ * Time limits for work that may never finish: a Chrome call a service worker
+ * shouldn't wait on forever, or, in tests that drive a real browser, a page
+ * that stops responding. Runs anywhere (worker, page, Node).
+ *
+ * @module time/time
+ */
+
+/**
+ * Settle `promise` within `ms`, or settle the way `late` says. The timer is
+ * cleared as soon as either happens, so a finished run isn't kept waiting
+ * for it. The work itself isn't stopped.
+ *
+ * @template T
+ * @param {Promise<T>} promise - The work.
+ * @param {number} ms - The limit.
+ * @param {(resolve: (value: T) => void, reject: (error: Error) => void) => void} late - Runs when the
+ *   limit passes first.
+ * @returns {Promise<T>} The work's outcome, or `late`'s.
+ */
+export function deadline(promise, ms, late) {
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  const limit = new Promise((resolve, reject) => {
+    timer = setTimeout(() => late(resolve, reject), ms);
+  });
+  return /** @type {Promise<T>} */ (Promise.race([promise, limit])).finally(() => clearTimeout(timer));
+}
+
+/**
+ * A promise's value within a time limit, or `fallback` when it's late or
+ * fails: for a step to give up on and go past (a Chrome call that never
+ * answers, a renderer that stopped responding, a close that never returns).
+ * The work itself isn't stopped; the timer is cleared once it settles.
+ *
+ * @template T
+ * @param {Promise<T>} promise - The work.
+ * @param {number} ms - The limit.
+ * @param {T} fallback - What to give if it's late or fails.
+ * @returns {Promise<T>} Its value, or the fallback. Never rejects.
+ * @example
+ * const list = await within(handled(worker, page), 8000, []);
+ * await within(page.close(), 15000, undefined);
+ */
+export function within(promise, ms, fallback) {
+  return deadline(promise.catch(() => fallback), ms, (resolve) => resolve(fallback));
+}

package/src/ui/menu.d.ts

@@ -140,13 +140,18 @@ export type MenuOptions = {
      */
     placement?: 'over' | 'below';
     /**
-     * The page. Default `document`.
+     * Where the menu goes: an element, or a shadow root (a content
+     * script's, so the page's styles never reach it). Default the page's `body`.
+     */
+    root?: ParentNode;
+    /**
+     * The page. Default `root`'s document, else `document`.
      */
     doc?: Document;
 };
 export type ActionMenu = {
     /**
-     * The `<dialog class="menu" role="menu">`, in the page's body.
+     * The `<dialog class="menu" role="menu">`, in `root`.
      */
     element: HTMLDialogElement;
     /**
@@ -165,13 +170,15 @@ export type ActionMenu = {
  * @typedef {object} MenuOptions
  * @property {string} [id] The menu element's id.
  * @property {'over' | 'below'} [placement] Where it opens from a button. Default `'over'`, as Chrome's.
- * @property {Document} [doc] The page. Default `document`.
+ * @property {ParentNode} [root] Where the menu goes: an element, or a shadow root (a content
+ *   script's, so the page's styles never reach it). Default the page's `body`.
+ * @property {Document} [doc] The page. Default `root`'s document, else `document`.
  */
 /**
  * A page's action menu.
  *
  * @typedef {object} ActionMenu
- * @property {HTMLDialogElement} element The `<dialog class="menu" role="menu">`, in the page's body.
+ * @property {HTMLDialogElement} element The `<dialog class="menu" role="menu">`, in `root`.
  * @property {(entries: readonly MenuEntry[], where: MenuPlace) => void} open Fill it with `entries`
  *   and open it (closing it first if it's open).
  * @property {() => void} close Close it, if open, and return the focus.
@@ -180,7 +187,7 @@ export type ActionMenu = {
  * Make a page's action menu: one `<dialog class="menu">` that any number of
  * ⋮ buttons (or right-clicks) open with their own items.
  *
- * @param {MenuOptions} [options] - Its id, placement and page.
+ * @param {MenuOptions} [options] - Its id, placement, and where it goes.
  * @returns {ActionMenu} The menu.
  * @example
  * const menu = createMenu();
@@ -192,7 +199,7 @@ export type ActionMenu = {
  *   ], {anchor: button}),
  * }));
  */
-export declare function createMenu({ id, placement, doc }?: MenuOptions): ActionMenu;
+export declare function createMenu({ id, placement, root, doc }?: MenuOptions): ActionMenu;
 export type MoreActionsOptions = {
     /**
      * The whole label, for a page that translates it. Default

package/src/ui/menu.js

@@ -14,6 +14,8 @@
  * @module ui/menu
  */
 
+import { focusedElement, rootDocument } from '../dom/focus.js';
+
 /** The gap kept between a menu and the window's edges, in px. */
 export const MENU_EDGE = 8;
 
@@ -103,14 +105,16 @@ export function isInside(box, x, y) {
  * @typedef {object} MenuOptions
  * @property {string} [id] The menu element's id.
  * @property {'over' | 'below'} [placement] Where it opens from a button. Default `'over'`, as Chrome's.
- * @property {Document} [doc] The page. Default `document`.
+ * @property {ParentNode} [root] Where the menu goes: an element, or a shadow root (a content
+ *   script's, so the page's styles never reach it). Default the page's `body`.
+ * @property {Document} [doc] The page. Default `root`'s document, else `document`.
  */
 
 /**
  * A page's action menu.
  *
  * @typedef {object} ActionMenu
- * @property {HTMLDialogElement} element The `<dialog class="menu" role="menu">`, in the page's body.
+ * @property {HTMLDialogElement} element The `<dialog class="menu" role="menu">`, in `root`.
  * @property {(entries: readonly MenuEntry[], where: MenuPlace) => void} open Fill it with `entries`
  *   and open it (closing it first if it's open).
  * @property {() => void} close Close it, if open, and return the focus.
@@ -120,7 +124,7 @@ export function isInside(box, x, y) {
  * Make a page's action menu: one `<dialog class="menu">` that any number of
  * ⋮ buttons (or right-clicks) open with their own items.
  *
- * @param {MenuOptions} [options] - Its id, placement and page.
+ * @param {MenuOptions} [options] - Its id, placement, and where it goes.
  * @returns {ActionMenu} The menu.
  * @example
  * const menu = createMenu();
@@ -132,13 +136,13 @@ export function isInside(box, x, y) {
  *   ], {anchor: button}),
  * }));
  */
-export function createMenu({ id, placement = 'over', doc = document } = {}) {
+export function createMenu({ id, placement = 'over', root, doc = rootDocument(root) } = {}) {
   const view = /** @type {Window & typeof globalThis} */ (doc.defaultView);
   const menu = doc.createElement('dialog');
   menu.className = 'menu';
   menu.setAttribute('role', 'menu');
   if (id) menu.id = id;
-  doc.body.append(menu);
+  (root ?? doc.body).append(menu);
 
   /** @type {HTMLElement | null} */
   let returnFocus = null;
@@ -164,7 +168,7 @@ export function createMenu({ id, placement = 'over', doc = document } = {}) {
 
   menu.addEventListener('keydown', (event) => {
     const list = items();
-    const at = list.indexOf(/** @type {HTMLButtonElement} */ (doc.activeElement));
+    const at = list.indexOf(/** @type {HTMLButtonElement} */ (focusedElement(doc)));
     /** @param {number} index */
     const go = (index) => {
       event.preventDefault();
@@ -215,7 +219,7 @@ export function createMenu({ id, placement = 'over', doc = document } = {}) {
       if (label) menu.setAttribute('aria-label', label);
       else menu.removeAttribute('aria-label');
 
-      const active = doc.activeElement;
+      const active = focusedElement(doc);
       returnFocus = focusTo ?? anchor ?? (active instanceof view.HTMLElement ? active : null);
       if (anchor?.hasAttribute('aria-haspopup')) {
         anchor.setAttribute('aria-expanded', 'true');

package/src/ui/site-list.d.ts

@@ -0,0 +1,216 @@
+/**
+ * A settings card's list of sites (“Never on”, “Allowed sites”), in one of
+ * Chrome's two ways:
+ *
+ * - **With an add row** (`form`), as a short list in a chrome://settings
+ *   card: a row per site with a Remove button, and below them a field and an
+ *   Add button.
+ * - **With an Add button and a dialog** (`addButton`), as
+ *   chrome://settings/performance lists the sites Memory Saver keeps active:
+ *   the button asks for a site in the one-field dialog (“Add site”), and each
+ *   row has a ⋮ menu with Edit and Remove.
+ *
+ * Either way, an optional “No sites added” row shows while there are none.
+ * The page's markup holds the list, the empty row and the form or button (so
+ * they're localised with the rest of the page); this fills the list and wires
+ * them up.
+ *
+ * ```html
+ * <ul class="list" id="never-sites"></ul>
+ * <p class="row text" id="no-sites"><span class="label secondary">No sites added</span></p>
+ * <form class="row add" id="add-never">
+ *   <input type="text" placeholder="example.com" aria-label="Site" autocomplete="off" spellcheck="false">
+ *   <button type="submit">Add</button>
+ * </form>
+ * ```
+ *
+ * @module ui/site-list
+ */
+export type SiteListWords = {
+    /**
+     * The Add button in the dialog.
+     */
+    add: string;
+    /**
+     * The dialog's title when adding.
+     */
+    addSite: string;
+    /**
+     * The dialog's title when editing.
+     */
+    editSite: string;
+    /**
+     * The ⋮ menu's Edit item.
+     */
+    edit: string;
+    /**
+     * The Remove button, or the ⋮ menu's Remove item.
+     */
+    remove: string;
+    /**
+     * The dialog's action when editing.
+     */
+    save: string;
+    /**
+     * The dialog's Cancel button.
+     */
+    cancel: string;
+    /**
+     * The dialog's field label.
+     */
+    site: string;
+    /**
+     * Under the dialog's field while what's typed isn't a site.
+     */
+    invalid: string;
+    /**
+     * The Remove button's name for screen readers.
+     */
+    removeLabel: (label: string) => string;
+    /**
+     * The ⋮ button's name for screen readers.
+     */
+    moreActions: (label: string) => string;
+};
+/**
+ * The list's words, Chrome's English by default; a page passes its translations.
+ *
+ * @typedef {object} SiteListWords
+ * @property {string} add The Add button in the dialog.
+ * @property {string} addSite The dialog's title when adding.
+ * @property {string} editSite The dialog's title when editing.
+ * @property {string} edit The ⋮ menu's Edit item.
+ * @property {string} remove The Remove button, or the ⋮ menu's Remove item.
+ * @property {string} save The dialog's action when editing.
+ * @property {string} cancel The dialog's Cancel button.
+ * @property {string} site The dialog's field label.
+ * @property {string} invalid Under the dialog's field while what's typed isn't a site.
+ * @property {(label: string) => string} removeLabel The Remove button's name for screen readers.
+ * @property {(label: string) => string} moreActions The ⋮ button's name for screen readers.
+ */
+/** @type {Readonly<SiteListWords>} */
+export declare const SITE_LIST_WORDS: Readonly<SiteListWords>;
+/**
+ * The message key each word is read from when a page passes its `t`, so
+ * every extension's `_locales` names them alike. `removeLabel` and
+ * `moreActions` take the site as `$1` (`"More actions for $SITE$"`).
+ *
+ * @type {Readonly<Record<keyof SiteListWords, string>>}
+ */
+export declare const SITE_LIST_MESSAGES: Readonly<Record<keyof SiteListWords, string>>;
+export type SiteListOptions = {
+    /**
+     * The `<ul class="list">` to fill.
+     */
+    list: HTMLElement;
+    /**
+     * Shown while the list is empty.
+     */
+    empty?: HTMLElement;
+    /**
+     * An add row: a form with one text field and a submit button.
+     */
+    form?: HTMLFormElement;
+    /**
+     * Or an Add button that asks in the dialog; each row then has a
+     * ⋮ menu (Edit, Remove) instead of a Remove button.
+     */
+    addButton?: HTMLElement;
+    /**
+     * What was typed as the site the list keeps
+     * (`siteHost`, `siteOrigin`), or null when it isn't one.
+     */
+    parse: (text: string) => string | null;
+    /**
+     * Adds a parsed site (asking Chrome for access first, if
+     * the list needs it). Resolve to false to keep the text in the add row's field (access refused).
+     */
+    add: (site: string) => unknown;
+    /**
+     * Removes a site.
+     */
+    remove: (site: string) => unknown;
+    /**
+     * Puts an edited site in place of
+     * the old one (the ⋮ menu's Edit; without it, the menu has only Remove).
+     */
+    replace?: (site: string, edited: string) => unknown;
+    /**
+     * The add row: called with what was typed when it isn't a site.
+     */
+    invalid?: (text: string) => void;
+    /**
+     * How a site reads. Default {@link siteLabel}.
+     */
+    label?: (site: string) => string;
+    /**
+     * The dialog field's `maxlength`. Default {@link MAX_HOST_LENGTH}.
+     */
+    maxLength?: number;
+    /**
+     * The page's message lookup
+     * (`setUpPage`'s): the words are then its messages under {@link SITE_LIST_MESSAGES}. Without it,
+     * Chrome's English ({@link SITE_LIST_WORDS}).
+     */
+    t?: (key: string, substitutions?: string | string[]) => string;
+    /**
+     * Words that differ from those, by name.
+     */
+    words?: Partial<SiteListWords>;
+};
+export type SiteList = {
+    /**
+     * Show these sites (call it whenever they change).
+     */
+    render: (sites: readonly string[]) => void;
+};
+/**
+ * What {@link createSiteList} takes: the list, one way to add to it, and
+ * what adding, removing and editing do.
+ *
+ * @typedef {object} SiteListOptions
+ * @property {HTMLElement} list The `<ul class="list">` to fill.
+ * @property {HTMLElement} [empty] Shown while the list is empty.
+ * @property {HTMLFormElement} [form] An add row: a form with one text field and a submit button.
+ * @property {HTMLElement} [addButton] Or an Add button that asks in the dialog; each row then has a
+ *   ⋮ menu (Edit, Remove) instead of a Remove button.
+ * @property {(text: string) => string | null} parse What was typed as the site the list keeps
+ *   (`siteHost`, `siteOrigin`), or null when it isn't one.
+ * @property {(site: string) => unknown} add Adds a parsed site (asking Chrome for access first, if
+ *   the list needs it). Resolve to false to keep the text in the add row's field (access refused).
+ * @property {(site: string) => unknown} remove Removes a site.
+ * @property {(site: string, edited: string) => unknown} [replace] Puts an edited site in place of
+ *   the old one (the ⋮ menu's Edit; without it, the menu has only Remove).
+ * @property {(text: string) => void} [invalid] The add row: called with what was typed when it isn't a site.
+ * @property {(site: string) => string} [label] How a site reads. Default {@link siteLabel}.
+ * @property {number} [maxLength] The dialog field's `maxlength`. Default {@link MAX_HOST_LENGTH}.
+ * @property {(key: string, substitutions?: string | string[]) => string} [t] The page's message lookup
+ *   (`setUpPage`'s): the words are then its messages under {@link SITE_LIST_MESSAGES}. Without it,
+ *   Chrome's English ({@link SITE_LIST_WORDS}).
+ * @property {Partial<SiteListWords>} [words] Words that differ from those, by name.
+ */
+/**
+ * A site list.
+ *
+ * @typedef {object} SiteList
+ * @property {(sites: readonly string[]) => void} render Show these sites (call it whenever they change).
+ */
+/**
+ * Fill a site list and wire its way of adding: an add row (typing a site and
+ * pressing Enter or Add) or an Add button (the dialog, which keeps its Add off
+ * until what's typed is a site). A row's Remove (or its ⋮ menu's Remove and
+ * Edit) hands its site to `remove` (or `replace`).
+ *
+ * @param {SiteListOptions} options - The markup, the parser and what adding and removing do.
+ * @returns {SiteList} The list.
+ * @example
+ * const never = createSiteList({
+ *   list: byId('never-sites'), form: byId('add-never', HTMLFormElement), empty: byId('no-sites'),
+ *   parse: siteHost,
+ *   add: (host) => save({ neverSites: withSite(settings.neverSites, host) }),
+ *   remove: (host) => save({ neverSites: withoutSite(settings.neverSites, host) }),
+ *   t, // its words from optionsAdd, optionsRemove, …
+ * });
+ * never.render(settings.neverSites);
+ */
+export declare function createSiteList({ list, empty, form, addButton, parse, add, remove, replace, invalid, label, maxLength, t, words, }: SiteListOptions): SiteList;