@arraypress/extension-kit 1.2.0 → 1.4.0

package/src/ui/site-list.js

@@ -0,0 +1,234 @@
+/**
+ * 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}”`,
+});
+
+/**
+ * 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 const SITE_LIST_MESSAGES = Object.freeze({
+  add: 'optionsAdd',
+  addSite: 'optionsAddSite',
+  editSite: 'optionsEditSite',
+  edit: 'optionsEdit',
+  remove: 'optionsRemove',
+  save: 'optionsSave',
+  cancel: 'optionsCancel',
+  site: 'optionsSiteLabel',
+  invalid: 'optionsSiteInvalid',
+  removeLabel: 'optionsRemoveLabel',
+  moreActions: 'optionsMoreActions',
+});
+
+/**
+ * The list's words from a page's messages, under {@link SITE_LIST_MESSAGES}.
+ *
+ * @param {(key: string, substitutions?: string | string[]) => string} t - The page's message lookup.
+ * @returns {SiteListWords} The words.
+ */
+function translatedWords(t) {
+  const m = SITE_LIST_MESSAGES;
+  return {
+    add: t(m.add), addSite: t(m.addSite), editSite: t(m.editSite), edit: t(m.edit), remove: t(m.remove),
+    save: t(m.save), cancel: t(m.cancel), site: t(m.site), invalid: t(m.invalid),
+    removeLabel: (label) => t(m.removeLabel, [label]),
+    moreActions: (label) => t(m.moreActions, [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 {(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 function createSiteList({
+  list, empty, form, addButton, parse, add, remove, replace, invalid, label = siteLabel, maxLength = MAX_HOST_LENGTH, t, words,
+}) {
+  const doc = list.ownerDocument;
+  const w = { ...(t ? translatedWords(t) : 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;

package/src/ui/toast.js

@@ -3,9 +3,15 @@
  * 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
  */
 
+import { rootDocument } from '../dom/focus.js';
+
 /** How long chrome://bookmarks shows a toast (its cr-toast-manager's `duration`), in ms. */
 export const TOAST_MS = 10_000;
 
@@ -16,38 +22,44 @@ export const TOAST_MS = 10_000;
  * @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 function createToast({ undoLabel = 'Undo', duration = TOAST_MS, undoDuration = duration, doc = document } = {}) {
+export function createToast({ undoLabel = 'Undo', duration = TOAST_MS, undoDuration = duration, root, doc = rootDocument(root) } = {}) {
   const toast = doc.createElement('div');
   toast.id = 'toast';
   toast.className = 'toast';
   toast.setAttribute('role', 'status');
   toast.setAttribute('aria-live', 'polite');
-  toast.hidden = true;
+  toast.popover = 'manual';
   const text = doc.createElement('span');
   text.id = 'toast-text';
   const undoButton = doc.createElement('button');
@@ -56,7 +68,7 @@ export function createToast({ undoLabel = 'Undo', duration = TOAST_MS, undoDurat
   undoButton.textContent = undoLabel;
   undoButton.hidden = true;
   toast.append(text, undoButton);
-  doc.body.append(toast);
+  (root ?? doc.body).append(toast);
 
   /** @type {ReturnType<typeof setTimeout> | undefined} */
   let timer;
@@ -65,7 +77,7 @@ export function createToast({ undoLabel = 'Undo', duration = TOAST_MS, undoDurat
 
   const hide = () => {
     clearTimeout(timer);
-    toast.hidden = true;
+    toast.togglePopover(false);
     undoLast = null;
   };
   undoButton.addEventListener('click', () => {
@@ -81,7 +93,9 @@ export function createToast({ undoLabel = 'Undo', duration = TOAST_MS, undoDurat
       text.textContent = message;
       undoButton.hidden = !undo;
       undoLast = undo;
-      toast.hidden = false;
+      // Hidden and shown again, so it's the newest in the top layer (over a popover since).
+      toast.togglePopover(false);
+      toast.togglePopover(true);
       timer = setTimeout(hide, undo ? undoDuration : duration);
     },
     hide,