@arraypress/extension-kit 1.2.0 → 1.3.0

package/src/testing/time.js

@@ -0,0 +1,46 @@
+/**
+ * Time limits for tests that drive a real browser, where a page that stops
+ * responding would otherwise hold a run up forever.
+ *
+ * @module testing/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 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.
+ *
+ * @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,199 @@
+/**
+ * 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>;
+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;
+    /**
+     * Translations of {@link SITE_LIST_WORDS}.
+     */
+    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 {Partial<SiteListWords>} [words] Translations of {@link SITE_LIST_WORDS}.
+ */
+/**
+ * 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: [...settings.neverSites, host] }),
+ *   remove: (host) => save({ neverSites: settings.neverSites.filter((h) => h !== host) }),
+ *   words: { remove: t('optionsRemove'), removeLabel: (site) => t('optionsRemoveLabel', [site]) },
+ * });
+ * never.render(settings.neverSites);
+ */
+export declare function createSiteList({ list, empty, form, addButton, parse, add, remove, replace, invalid, label, maxLength, words, }: SiteListOptions): SiteList;

package/src/ui/site-list.js

@@ -0,0 +1,194 @@
+/**
+ * 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
+ */
+
+import { createMenu, moreActionsButton } from './menu.js';
+import { askText } from './text-dialog.js';
+import { MAX_HOST_LENGTH, siteLabel } from '../sites/sites.js';
+
+/**
+ * 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 const SITE_LIST_WORDS = Object.freeze({
+  add: 'Add',
+  addSite: 'Add site',
+  editSite: 'Edit site',
+  edit: 'Edit',
+  remove: 'Remove',
+  save: 'Save',
+  cancel: 'Cancel',
+  site: 'Site',
+  invalid: 'Enter a site, like example.com',
+  removeLabel: (/** @type {string} */ label) => `Remove “${label}”`,
+  moreActions: (/** @type {string} */ label) => `More actions for “${label}”`,
+});
+
+/**
+ * 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 {Partial<SiteListWords>} [words] Translations of {@link SITE_LIST_WORDS}.
+ */
+
+/**
+ * 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: [...settings.neverSites, host] }),
+ *   remove: (host) => save({ neverSites: settings.neverSites.filter((h) => h !== host) }),
+ *   words: { remove: t('optionsRemove'), removeLabel: (site) => t('optionsRemoveLabel', [site]) },
+ * });
+ * never.render(settings.neverSites);
+ */
+export function createSiteList({
+  list, empty, form, addButton, parse, add, remove, replace, invalid, label = siteLabel, maxLength = MAX_HOST_LENGTH, words,
+}) {
+  const doc = list.ownerDocument;
+  const w = { ...SITE_LIST_WORDS, ...words };
+  const menu = addButton ? createMenu({ doc }) : null;
+
+  /**
+   * Ask for a site in the dialog.
+   *
+   * @param {string} title - Its title.
+   * @param {string} action - Its action button.
+   * @param {string} [value] - The site to start with.
+   * @returns {Promise<string | null>} The site, parsed, or null when cancelled.
+   */
+  const ask = async (title, action, value) => {
+    const text = await askText({
+      title, label: w.site, value, action, cancel: w.cancel, maxLength, doc,
+      validate: (typed) => (parse(typed) ? null : w.invalid),
+    });
+    return text === null ? null : parse(text);
+  };
+
+  form?.addEventListener('submit', async (event) => {
+    event.preventDefault();
+    const input = /** @type {HTMLInputElement} */ (form.querySelector('input'));
+    const site = parse(input.value);
+    if (!site) invalid?.(input.value);
+    else if (await add(site) !== false) input.value = '';
+  });
+  addButton?.addEventListener('click', async () => {
+    const site = await ask(w.addSite, w.add);
+    if (site) await add(site);
+  });
+
+  /**
+   * The end of a site's row: its ⋮ button, or its Remove button.
+   *
+   * @param {string} site - The site.
+   * @param {string} name - How it reads.
+   * @returns {HTMLButtonElement} The button.
+   */
+  const rowEnd = (site, name) => {
+    if (menu) {
+      return moreActionsButton(name, {
+        label: w.moreActions(name), doc,
+        onClick: (anchor) => menu.open([
+          ...replace ? [{
+            label: w.edit,
+            run: async () => {
+              const edited = await ask(w.editSite, w.save, name);
+              if (edited && edited !== site) await replace(site, edited);
+            },
+          }] : [],
+          { label: w.remove, run: () => remove(site) },
+        ], { anchor }),
+      });
+    }
+    const button = doc.createElement('button');
+    button.type = 'button';
+    button.textContent = w.remove;
+    button.setAttribute('aria-label', w.removeLabel(name));
+    button.addEventListener('click', () => remove(site));
+    return button;
+  };
+
+  return {
+    render(sites) {
+      list.replaceChildren(...sites.map((site) => {
+        const row = doc.createElement('li');
+        row.className = 'row';
+        const name = doc.createElement('span');
+        name.className = 'label';
+        name.textContent = label(site);
+        row.append(name, rowEnd(site, name.textContent));
+        return row;
+      }));
+      if (empty) empty.hidden = sites.length > 0;
+    },
+  };
+}

package/src/ui/text-dialog.js

@@ -9,6 +9,8 @@
  * @module ui/text-dialog
  */
 
+import { focusedElement } from '../dom/focus.js';
+
 /**
  * What the dialog asks.
  *
@@ -126,7 +128,7 @@ export function askText({
 }) {
   const parts = partsFor(doc);
   pending.get(doc)?.(null);
-  const active = doc.activeElement;
+  const active = focusedElement(doc);
   const back = returnTo === undefined ? (active instanceof /** @type {Window & typeof globalThis} */ (doc.defaultView).HTMLElement ? active : null) : returnTo;
 
   parts.title.textContent = title;

package/src/ui/toast.d.ts

@@ -3,6 +3,10 @@
  * after a delete: "Deleted “Research”  Undo". One per page, made by
  * {@link createToast}; a new message replaces the last and restarts the wait.
  *
+ * It's a manual `popover`, so it shows in the top layer: over anything the
+ * page stacks (a content script's toast over a site's own fixed bars), and
+ * never clipped by an ancestor.
+ *
  * @module ui/toast
  */
 /** How long chrome://bookmarks shows a toast (its cr-toast-manager's `duration`), in ms. */
@@ -21,13 +25,19 @@ export type ToastOptions = {
      */
     undoDuration?: number;
     /**
-     * The page. Default `document`.
+     * Where the toast goes: an element, or a shadow root (a content
+     * script's). Default the page's `body`.
+     */
+    root?: ParentNode;
+    /**
+     * The page. Default `root`'s document, else `document`.
      */
     doc?: Document;
 };
 export type Toast = {
     /**
-     * The `#toast` element (`role="status"`), in the page's body.
+     * The `#toast` element (`role="status"`, `popover="manual"`), in
+     * `root`; `:popover-open` while it shows.
      */
     element: HTMLElement;
     /**
@@ -47,27 +57,33 @@ export type Toast = {
  * @property {string} [undoLabel] The undo button's text. Default "Undo".
  * @property {number} [duration] How long a toast stays, in ms. Default {@link TOAST_MS}.
  * @property {number} [undoDuration] How long one with Undo stays. Default `duration`.
- * @property {Document} [doc] The page. Default `document`.
+ * @property {ParentNode} [root] Where the toast goes: an element, or a shadow root (a content
+ *   script's). Default the page's `body`.
+ * @property {Document} [doc] The page. Default `root`'s document, else `document`.
  */
 /**
  * A page's toast.
  *
  * @typedef {object} Toast
- * @property {HTMLElement} element The `#toast` element (`role="status"`), in the page's body.
+ * @property {HTMLElement} element The `#toast` element (`role="status"`, `popover="manual"`), in
+ *   `root`; `:popover-open` while it shows.
  * @property {(text: string, undo?: (() => unknown) | null) => void} show Show `text`, with an Undo
  *   button that hides the toast and runs `undo` when one is given.
  * @property {() => void} hide Take it down (and its Undo with it).
  */
 /**
- * Make the page's toast: `<div id="toast" class="toast" role="status">` with
- * `#toast-text` and an Undo button `#toast-undo`, hidden until shown. Make it
- * when the page loads, so screen readers know the live region before it speaks.
+ * Make the page's toast: `<div id="toast" class="toast" role="status"
+ * popover="manual">` with `#toast-text` and an Undo button `#toast-undo`,
+ * closed until shown. Make it when the page loads, so screen readers know the
+ * live region before it speaks.
  *
- * @param {ToastOptions} [options] - The Undo text, how long it stays, and the page.
+ * @param {ToastOptions} [options] - The Undo text, how long it stays, and where it goes.
  * @returns {Toast} The toast.
  * @example
  * const toast = createToast();
  * await deleteWorkspace(workspace);
  * toast.show(`Deleted “${workspace.name}”`, () => restore(workspace));
+ * // In a content script's shadow root:
+ * createToast({ root: host.attachShadow({ mode: 'open' }), duration: 4000 });
  */
-export declare function createToast({ undoLabel, duration, undoDuration, doc }?: ToastOptions): Toast;
+export declare function createToast({ undoLabel, duration, undoDuration, root, doc }?: ToastOptions): Toast;