@arraypress/extension-kit 1.2.0 → 1.3.0

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,