@arraypress/extension-kit 1.3.0 → 1.5.0

package/README.md

@@ -10,8 +10,8 @@ The pieces ArrayPress's Chrome extensions share, so each is written once:
   service worker shows the matching icon.
 - **About links**: README, Issues and PRIVACY.md in the extension's GitHub repository, plus
   package-time warnings for placeholder links.
-- **Chrome's page components**: the ⋮ action menu and its row button, the one-field dialog
-  ("Rename folder"), the toast with Undo and a settings card's site list, built on the
+- **Chrome's page components**: the ⋮ action menu and its row button, the text dialog
+  ("Rename folder", or several fields as "Add site search"), the toast with Undo and a settings card's site list, built on the
   stylesheet's classes; they work in a content script's shadow root too.
 - **Sites**: what people type into a per-site list, and whether a page is on one.
 - **Build and test helpers** (Node): icon rendering, vendoring npm packages (with a staleness
@@ -159,13 +159,25 @@ be public before the store listing goes live.
 ## Page start-up
 
 ```js
-const t = setUpPage(chrome, { title: 'optionsTitle', substitutions: [name] });
+const t = setUpPage(chrome, { title: 'optionsTitle' });
 ```
 
 Reports the page's colour scheme for the toolbar glyph (`watchColorScheme`; a failure is only
 logged), fills its `data-i18n` text (`localize`), sets its title from a message, and returns the
 page's `t`.
 
+The extension's name lives in one message, `extShortName`. A message that names the extension
+takes it as a placeholder whose content is `$1`, and every lookup without substitutions (`t(key)`,
+`data-i18n`, `data-i18n-*`, the title) fills it in:
+
+```json
+"optionsAbout": { "message": "About $NAME$", "placeholders": { "name": { "content": "$1" } } }
+```
+
+```html
+<h2 class="section-title" data-i18n="optionsAbout"></h2> <!-- About Upright -->
+```
+
 ## Sites
 
 ```js
@@ -175,11 +187,22 @@ onSite(siteHost(location.href), neverSites); // on a listed site or a subdomain
 hostPatterns('github.com');                  // ['*://github.com/*', '*://*.github.com/*'] (excludeMatches)
 originPattern('https://bit.ly/x');           // 'https://bit.ly/*' (permissions.request)
 siteLabel('https://example.com');            // 'example.com', as a list shows it
+withSite(['a.com', 'b.com'], 'a.com');       // ['b.com', 'a.com'], what a list keeps after Add (also withoutSite, withSiteReplaced)
 ```
 
 A site is http or https with a dot in its host (or `localhost`); text without a scheme is https;
 `localhost:8080` is a host and port. Pure, so a content script can load `sites/sites.js` alone.
 
+## Time limits
+
+```js
+const groups = await within(chrome.tabGroups.query({}), 2000, []); // a Chrome call that may never answer
+```
+
+`within(promise, ms, fallback)`: the value in time, or the fallback (late or failed); never
+rejects; its timer cleared once the work settles (the work itself isn't stopped). In the runtime
+half, so a service worker or page can use it; the test helpers use it too.
+
 ## Page components
 
 Chrome's own components, made in the page by script (no markup to copy), styled by `chrome-ui.css`.
@@ -215,7 +238,7 @@ opens it below the button instead. `menuPosition` and `isInside` are the pure ge
 `tooltip` (a `title`) and `focusable: false` (out of the tab order, for a row that takes the focus)
 cover the rest.
 
-### One-field dialog (cr-dialog)
+### Text dialog (cr-dialog)
 
 ```js
 const name = await askText({ title: 'Rename workspace', label: 'Name', value: workspace.name, maxLength: 200 });
@@ -231,6 +254,26 @@ disabled while the text is blank or `validate` gives a reason, which shows under
 focus goes back to what had it, or to `returnTo` (an element, or a function asked at the end).
 One `#text-dialog` per page, made on first use.
 
+### Dialog with several fields
+
+```js
+const rule = await askFields({
+  title: 'Add folder rule', action: 'Add',
+  fields: [
+    { name: 'from', label: 'Downloads from', placeholder: 'example.com or .pdf', validate: checkFrom },
+    { name: 'folder', label: 'Folder', value: 'Receipts' },
+  ],
+});
+if (rule) addRule(rule.from, rule.folder);
+```
+
+The same dialog as chrome://settings/searchEngines asks for a site search: a field each, in
+order. Resolves to each field's text by its `name`, trimmed, or `null` when cancelled. The action
+button stays disabled until every field is filled in and valid, each field's reason under it; the
+focus starts in the first empty field. `askText` is this with one field. A one-field dialog's ids
+are `text-dialog-input` and `text-dialog-error`; with several, `text-dialog-<name>` and
+`text-dialog-<name>-error` (`fieldIds`), for a test to find them.
+
 ### Toast with Undo (cr-toast)
 
 ```js
@@ -247,25 +290,50 @@ restarts the wait: 10 seconds, as chrome://bookmarks's (`TOAST_MS`), or `duratio
 ### Site list
 
 ```js
-// A short list with an add row (chrome://settings), the markup in the page:
-// <ul class="list" id="sites"></ul> <p class="row text" id="no-sites">…</p>
-// <form class="row add" id="add-site"><input type="text" …><button type="submit">Add</button></form>
+// Memory Saver's way (chrome://settings/performance): an Add button and the dialog, ⋮ Edit/Remove.
+// <div class="row"><span class="label secondary">…</span><button id="add-site" type="button">Add</button></div>
+// <p class="row text" id="no-sites"><span class="label">No sites added</span></p> <ul class="list" id="sites"></ul>
 const sites = createSiteList({
-  list: byId('sites'), empty: byId('no-sites'), form: byId('add-site', HTMLFormElement),
-  parse: siteOrigin,
-  add: async (origin) => (await chrome.permissions.request({ origins: [originPattern(origin)] })) && save(origin),
-  remove: (origin) => unsave(origin),
-  words: { remove: t('optionsRemove'), removeLabel: (site) => t('optionsRemoveLabel', [site]) },
+  list: byId('sites'), empty: byId('no-sites'), addButton: byId('add-site'),
+  parse: siteHost,
+  add: (site) => save({ sites: withSite(settings.sites, site) }),
+  remove: (site) => save({ sites: withoutSite(settings.sites, site) }),
+  replace: (site, edited) => save({ sites: withSiteReplaced(settings.sites, site, edited) }),
+  t, // the page's messages, under the standard keys below
 });
 sites.render(settings.sites);
 
-// Memory Saver's way (chrome://settings/performance): an Add button and the dialog, ⋮ Edit/Remove.
-createSiteList({ list, empty, addButton: byId('add-site'), parse: siteHost, add, remove, replace: (old, edited) => … });
+// A short list with an add row (chrome://settings): `form` instead of `addButton`.
+// <form class="row add" id="add-site"><input type="text" …><button type="submit">Add</button></form>
 ```
 
-`add` resolving to false keeps the typed text (access refused); `invalid(text)` hears what isn't
-a site in the add row; the dialog keeps its Add off with “Enter a site, like example.com” under
-the field. `words` translates `SITE_LIST_WORDS`.
+`withSite` adds a site at the end, once (added again, it moves there); `withoutSite` takes it out;
+`withSiteReplaced` edits it in place, merging it with a duplicate. A list that needs site access
+asks for it in `add`/`replace` (the dialog's click still counts as the person's) and gives it back
+in `remove`. `add` resolving to false keeps the add row's text (access refused); `invalid(text)`
+hears what isn't a site in the add row; the dialog keeps its Add off with “Enter a site, like
+example.com” under the field.
+
+The words: Chrome's English (`SITE_LIST_WORDS`) without `t`; with it, the page's messages under
+these keys (`SITE_LIST_MESSAGES`), so every extension's `_locales` names them alike. `words`
+overrides only those that differ.
+
+| Word | Key | English |
+|---|---|---|
+| `add` | `optionsAdd` | Add |
+| `addSite` | `optionsAddSite` | Add site |
+| `editSite` | `optionsEditSite` | Edit site |
+| `edit` | `optionsEdit` | Edit |
+| `remove` | `optionsRemove` | Remove |
+| `save` | `optionsSave` | Save |
+| `cancel` | `optionsCancel` | Cancel |
+| `site` | `optionsSiteLabel` | Site |
+| `invalid` | `optionsSiteInvalid` | Enter a site, like example.com |
+| `moreActions` | `optionsMoreActions` | More actions for `$SITE$` (content `$1`; the ⋮ button) |
+| `removeLabel` | `optionsRemoveLabel` | Remove `$SITE$` (content `$1`; the add row's Remove button) |
+
+A list with an Add button needs every key but `optionsRemoveLabel`; one with an add row needs
+`optionsRemove` and `optionsRemoveLabel`. A locale test can check them against `SITE_LIST_MESSAGES`.
 
 ## Build helpers (`@arraypress/extension-kit/build`)
 
@@ -300,7 +368,6 @@ except those listed, each with a reason:
 | `launchExtension(chromium, dir, options)` | Load an unpacked extension into a fresh profile; `{context, worker, extensionId, url(page), profile, close()}`. |
 | `extensionProfile(chromium, dir, options)` | A profile to start the browser on more than once (a restart, a first start with a changed manifest): `{dir, launch(), remove()}`. |
 | `checkRunner({timeout})` | Named checks that report and go on: `check(name, fn, {timeout})`, `fail(name)` for an error found outside a check, `finish()`. A check that runs past its limit (`CHECK_MS`, 60 s) fails, and the run goes on. |
-| `within(promise, ms, fallback)` | The value in time, or the fallback (late or failed); never rejects; its timer cleared. |
 | `eachLimited(items, limit, work)` | Work through a list at most `limit` at once, `work(item, slot, index)`. |
 | `realisticBrowser(options)`, `chromeUserAgent(browser)` | Launch options and a user agent for a browser that doesn't say it's automated, for live checks. |
 | `closeOnSignal(close)` | On Ctrl-C or a kill, close the run's browsers, then exit. |
@@ -340,7 +407,7 @@ except those listed, each with a reason:
 | Manager layout | `.manager`/`.layout`, `.sidebar` with `.tree` > `.tree-item`, `.main` with `.list-card` |
 | Menu (cr-action-menu) | `<dialog class="menu">` of `button[role="menuitem"]`, `hr` (or `createMenu`) |
 | ⋮ icon | `<span class="icon icon-more-vert" aria-hidden="true">` (or `moreActionsButton`) |
-| Dialog (cr-dialog) | `<dialog class="dialog"><form method="dialog">` `.dialog-title`, `.dialog-body`, `.dialog-buttons` (one field: `askText`) |
+| Dialog (cr-dialog) | `<dialog class="dialog"><form method="dialog">` `.dialog-title`, `.dialog-body`, `.dialog-buttons` (`askText`, `askFields`) |
 | Toast (cr-toast) | `<div class="toast" popover="manual">text <button>Undo</button></div>` (or `createToast`); with `hidden` instead of `popover`, it shows over the page but not the top layer |
 | Drawer (cr-drawer) | `<dialog class="drawer">` with `.drawer-head` and a `.nav` |
 | Side panel page | `<body class="side-panel">`: the panel's colours, a column 100vh high |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arraypress/extension-kit",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Shared pieces for Chrome extensions: Chrome's own page styles, a Chrome Sync settings store, the light/dark toolbar glyph, About links, and build and test helpers.",
   "type": "module",
   "main": "src/index.js",

package/src/build/vendor.js

@@ -28,7 +28,7 @@ const SOURCE = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 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', 'toolbar', 'ui']);
+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');

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

@@ -13,7 +13,7 @@ export type PageSetup = {
      */
     title?: string;
     /**
-     * The title's placeholders (the extension's name).
+     * The title's placeholders. Default: the extension's name (`translator`).
      */
     substitutions?: string | string[];
     /**
@@ -32,7 +32,7 @@ export type PageSetup = {
  *
  * @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 (the extension's name).
+ * @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)`.
  */
@@ -45,7 +45,8 @@ export type PageSetup = {
  * @returns {(key: string, substitutions?: string | string[]) => string} The page's message lookup
  *   (`translator(chrome.i18n)`).
  * @example
- * const t = setUpPage(chrome, { title: 'optionsTitle', substitutions: [t('extShortName')] });
+ * 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);
  */

package/src/dom/setup.js

@@ -17,7 +17,7 @@ import { DARK_QUERY, watchColorScheme } from '../toolbar/scheme.js';
  *
  * @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 (the extension's name).
+ * @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)`.
  */
@@ -31,7 +31,8 @@ import { DARK_QUERY, watchColorScheme } from '../toolbar/scheme.js';
  * @returns {(key: string, substitutions?: string | string[]) => string} The page's message lookup
  *   (`translator(chrome.i18n)`).
  * @example
- * const t = setUpPage(chrome, { title: 'optionsTitle', substitutions: [t('extShortName')] });
+ * 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);
  */

package/src/index.d.ts

@@ -20,19 +20,22 @@ 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 } from './sites/sites.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 { createSiteList } from './ui/site-list.js';
-export { askText, checkText } from './ui/text-dialog.js';
+export { SITE_LIST_MESSAGES, SITE_LIST_WORDS, createSiteList } from './ui/site-list.js';
+export { askFields, askText, checkText, fieldIds } 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 FieldRequest = import('./ui/text-dialog.js').FieldRequest;
+export type FieldsRequest = import('./ui/text-dialog.js').FieldsRequest;
 export type TextRequest = import('./ui/text-dialog.js').TextRequest;
 export type Toast = import('./ui/toast.js').Toast;
 /**
@@ -43,6 +46,8 @@ export type Toast = import('./ui/toast.js').Toast;
  * @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').FieldRequest} FieldRequest
+ * @typedef {import('./ui/text-dialog.js').FieldsRequest} FieldsRequest
  * @typedef {import('./ui/text-dialog.js').TextRequest} TextRequest
  * @typedef {import('./ui/toast.js').Toast} Toast
  */

package/src/index.js

@@ -21,15 +21,18 @@ 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 } from './sites/sites.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 { createSiteList } from './ui/site-list.js';
-export { askText, checkText } from './ui/text-dialog.js';
+export { SITE_LIST_MESSAGES, SITE_LIST_WORDS, createSiteList } from './ui/site-list.js';
+export { askFields, askText, checkText, fieldIds } from './ui/text-dialog.js';
 export { TOAST_MS, createToast } from './ui/toast.js';
 
 /**
@@ -40,6 +43,8 @@ export { TOAST_MS, createToast } from './ui/toast.js';
  * @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').FieldRequest} FieldRequest
+ * @typedef {import('./ui/text-dialog.js').FieldsRequest} FieldsRequest
  * @typedef {import('./ui/text-dialog.js').TextRequest} TextRequest
  * @typedef {import('./ui/toast.js').Toast} Toast
  */

package/src/sites/sites.d.ts

@@ -3,7 +3,8 @@
  * "https://www.Example.com/shop") and as pages report them (`location.href`):
  * the origin an extension asks Chrome for access to, the host a per-site
  * on/off list keeps, whether a page is on a listed site (subdomains
- * included), and the match patterns for both. Pure.
+ * included), the match patterns for both, and a list with a site added,
+ * taken out or edited. Pure.
  *
  * A site is a web host: http or https, with a dot in its name (or
  * `localhost`). Text without a scheme is read as https.
@@ -80,3 +81,34 @@ export declare function originPattern(url: string): string;
  * siteLabel('http://example.com');  // 'http://example.com'
  */
 export declare function siteLabel(site: string): string;
+/**
+ * A site list with `site` added: at the end, once (a site added again moves
+ * there).
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site to add.
+ * @returns {string[]} A new list.
+ * @example
+ * withSite(['a.com', 'b.com'], 'a.com'); // ['b.com', 'a.com']
+ */
+export declare function withSite(sites: readonly string[], site: string): string[];
+/**
+ * A site list without `site`.
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site to take out.
+ * @returns {string[]} A new list.
+ */
+export declare function withoutSite(sites: readonly string[], site: string): string[];
+/**
+ * A site list with `site` edited to `edited`, in its place, once (an edit
+ * to a site already listed merges the two).
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site as it was.
+ * @param {string} edited - What it was edited to.
+ * @returns {string[]} A new list.
+ * @example
+ * withSiteReplaced(['a.com', 'b.com'], 'a.com', 'b.com'); // ['b.com']
+ */
+export declare function withSiteReplaced(sites: readonly string[], site: string, edited: string): string[];

package/src/sites/sites.js

@@ -3,7 +3,8 @@
  * "https://www.Example.com/shop") and as pages report them (`location.href`):
  * the origin an extension asks Chrome for access to, the host a per-site
  * on/off list keeps, whether a page is on a listed site (subdomains
- * included), and the match patterns for both. Pure.
+ * included), the match patterns for both, and a list with a site added,
+ * taken out or edited. Pure.
  *
  * A site is a web host: http or https, with a dot in its name (or
  * `localhost`). Text without a scheme is read as https.
@@ -126,3 +127,43 @@ export function originPattern(url) {
 export function siteLabel(site) {
   return site.replace(/^https:\/\//, '');
 }
+
+/**
+ * A site list with `site` added: at the end, once (a site added again moves
+ * there).
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site to add.
+ * @returns {string[]} A new list.
+ * @example
+ * withSite(['a.com', 'b.com'], 'a.com'); // ['b.com', 'a.com']
+ */
+export function withSite(sites, site) {
+  return [...withoutSite(sites, site), site];
+}
+
+/**
+ * A site list without `site`.
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site to take out.
+ * @returns {string[]} A new list.
+ */
+export function withoutSite(sites, site) {
+  return sites.filter((s) => s !== site);
+}
+
+/**
+ * A site list with `site` edited to `edited`, in its place, once (an edit
+ * to a site already listed merges the two).
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site as it was.
+ * @param {string} edited - What it was edited to.
+ * @returns {string[]} A new list.
+ * @example
+ * withSiteReplaced(['a.com', 'b.com'], 'a.com', 'b.com'); // ['b.com']
+ */
+export function withSiteReplaced(sites, site, edited) {
+  return [...new Set(sites.map((s) => (s === site ? edited : s)))];
+}

package/src/testing/browser.js

@@ -8,7 +8,7 @@
  * @module testing/browser
  */
 
-import { within } from './time.js';
+import { within } from '../time/time.js';
 
 /** @import { Browser } from 'playwright' */
 

package/src/testing/e2e.js

@@ -12,7 +12,7 @@ import assert from 'node:assert/strict';
 import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { deadline } from './time.js';
+import { deadline } from '../time/time.js';
 
 /** @import { BrowserContext, BrowserType, CDPSession, Page, Worker } from 'playwright' */
 

package/src/testing/index.d.ts

@@ -10,7 +10,6 @@ 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 { within } from './time.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/index.js

@@ -13,7 +13,6 @@ export {
   CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until,
 } from './e2e.js';
 export { eachLimited } from './pool.js';
-export { within } from './time.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 → time}/time.d.ts

@@ -1,8 +1,9 @@
 /**
- * Time limits for tests that drive a real browser, where a page that stops
- * responding would otherwise hold a run up forever.
+ * 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 testing/time
+ * @module time/time
  */
 /**
  * Settle `promise` within `ms`, or settle the way `late` says. The timer is
@@ -19,9 +20,9 @@
 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 a live run should give up on and go past (a renderer
- * that stopped responding, a close that never returns). The work itself
- * isn't stopped; the timer is cleared once it settles.
+ * 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.

package/src/{testing → time}/time.js

@@ -1,8 +1,9 @@
 /**
- * Time limits for tests that drive a real browser, where a page that stops
- * responding would otherwise hold a run up forever.
+ * 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 testing/time
+ * @module time/time
  */
 
 /**
@@ -28,9 +29,9 @@ export function deadline(promise, ms, late) {
 
 /**
  * A promise's value within a time limit, or `fallback` when it's late or
- * fails: for a step a live run should give up on and go past (a renderer
- * that stopped responding, a close that never returns). The work itself
- * isn't stopped; the timer is cleared once it settles.
+ * 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.