@arraypress/extension-kit 1.9.0 → 1.11.0

package/src/ui/menu.js

@@ -14,7 +14,7 @@
  * @module ui/menu
  */
 
-import { focusedElement, rootDocument } from '../dom/focus.js';
+import { focusedElement, focusedIn, rootDocument } from '../dom/focus.js';
 
 /** The gap kept between a menu and the window's edges, in px. */
 export const MENU_EDGE = 8;
@@ -67,19 +67,21 @@ const BELOW_GAP = 4;
  *
  * @param {{width: number, height: number}} size - The menu's size.
  * @param {{width: number, height: number}} viewport - The window's (`innerWidth`, `innerHeight`).
- * @param {{anchor?: Box, x?: number, y?: number, placement?: 'over' | 'below'}} where - The anchor's
- *   box, or a point; `placement` says where it goes from an anchor (default `'over'`).
+ * @param {{anchor?: Box, x?: number, y?: number, placement?: 'over' | 'below', rtl?: boolean}} where - The
+ *   anchor's box, or a point; `placement` says where it goes from an anchor (default `'over'`); `rtl`
+ *   (a right-to-left page) lines its start up with the anchor's left edge and opens leftwards from a
+ *   point, as Chrome mirrors its own.
  * @returns {{left: number, top: number}} The menu's top-left, in px.
  * @example
  * menuPosition({width: 160, height: 120}, {width: 800, height: 600}, {anchor: button.getBoundingClientRect()});
  * // → {left: anchor.right - 160, top: anchor.top}
  */
-export function menuPosition(size, viewport, { anchor, x = 0, y = 0, placement = 'over' }) {
+export function menuPosition(size, viewport, { anchor, x = 0, y = 0, placement = 'over', rtl = false }) {
   const { width, height } = size;
   const left = (/** @type {number} */ start) => Math.max(MENU_EDGE, Math.min(start, viewport.width - width - MENU_EDGE));
   const room = (/** @type {number} */ top) => top + height <= viewport.height - MENU_EDGE;
-  if (!anchor) return { left: left(x), top: Math.max(MENU_EDGE, room(y) ? y : y - height) };
-  const start = left(anchor.right - width);
+  if (!anchor) return { left: left(rtl ? x - width : x), top: Math.max(MENU_EDGE, room(y) ? y : y - height) };
+  const start = left(rtl ? anchor.left : anchor.right - width);
   if (placement === 'below') {
     const below = anchor.bottom + BELOW_GAP;
     return { left: start, top: Math.max(MENU_EDGE, room(below) ? below : anchor.top - height - BELOW_GAP) };
@@ -118,6 +120,8 @@ export function isInside(box, x, y) {
  * @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.
+ * @property {() => void} destroy Take it off the page and stop listening to the window (a content
+ *   script's overlay being removed).
  */
 
 /**
@@ -168,21 +172,32 @@ export function createMenu({ id, placement = 'over', root, doc = rootDocument(ro
 
   menu.addEventListener('keydown', (event) => {
     const list = items();
-    const at = list.indexOf(/** @type {HTMLButtonElement} */ (focusedElement(doc)));
+    // Asked of the menu's own root: a closed shadow root's focused element can't be seen from the document.
+    const at = list.indexOf(/** @type {HTMLButtonElement} */ (focusedIn(menu)));
     /** @param {number} index */
     const go = (index) => {
-      event.preventDefault();
+      handled();
       list[(index + list.length) % list.length]?.focus();
     };
+    /** The key is the menu's: the page under a content script's menu doesn't act on it too (its own shortcuts). */
+    const handled = () => {
+      event.preventDefault();
+      event.stopPropagation();
+    };
     if (event.key === 'ArrowDown') go(at + 1);
     else if (event.key === 'ArrowUp') go(at < 0 ? -1 : at - 1);
     else if (event.key === 'Home') go(0);
     else if (event.key === 'End') go(-1);
     else if (event.key === 'Escape' || event.key === 'Tab') {
-      event.preventDefault();
+      handled();
       close();
     }
   });
+  // Closed any other way (the browser's own close, another script): the button no longer says it's open.
+  menu.addEventListener('close', () => {
+    expanded?.setAttribute('aria-expanded', 'false');
+    expanded = null;
+  });
   // Esc the browser handles itself (when the keydown above didn't see it).
   menu.addEventListener('cancel', (event) => {
     event.preventDefault();
@@ -219,7 +234,7 @@ export function createMenu({ id, placement = 'over', root, doc = rootDocument(ro
       if (label) menu.setAttribute('aria-label', label);
       else menu.removeAttribute('aria-label');
 
-      const active = focusedElement(doc);
+      const active = focusedIn(menu) ?? focusedElement(doc);
       returnFocus = focusTo ?? anchor ?? (active instanceof view.HTMLElement ? active : null);
       if (anchor?.hasAttribute('aria-haspopup')) {
         anchor.setAttribute('aria-expanded', 'true');
@@ -228,13 +243,18 @@ export function createMenu({ id, placement = 'over', root, doc = rootDocument(ro
       menu.showModal();
       const { width, height } = menu.getBoundingClientRect();
       const { left, top } = menuPosition({ width, height }, { width: view.innerWidth, height: view.innerHeight }, {
-        anchor: anchor?.getBoundingClientRect(), x, y, placement,
+        anchor: anchor?.getBoundingClientRect(), x, y, placement, rtl: view.getComputedStyle(menu).direction === 'rtl',
       });
       menu.style.left = `${left}px`;
       menu.style.top = `${top}px`;
       items()[0]?.focus();
     },
     close,
+    destroy() {
+      shut();
+      view.removeEventListener('blur', close);
+      menu.remove();
+    },
   };
 }
 

package/src/ui/model-row.js

@@ -94,7 +94,11 @@ export function createModelRow({ status, help, download, progress }, { options,
         progress.value = loaded;
         status.textContent = t(MODEL_MESSAGES.downloading, [String(Math.round(loaded * 100))]);
       },
-    }).then(async () => show(await state()), () => show('downloadable', t(MODEL_MESSAGES.downloadFailed)));
+    }).then(
+      // The state as the code that uses it sees it; if it can't be asked (the worker didn't answer), as this page does.
+      async (here) => show(await state().catch(() => here)),
+      () => show('downloadable', t(MODEL_MESSAGES.downloadFailed)),
+    );
   });
 
   return {

package/src/ui/notice.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A notice in a side panel's list (chrome-ui.css `.sp-notice`): a card with an icon, a heading,
+ * a line, buttons beside the heading and actions under the line. For what a list leaves out or
+ * can't do: frames from other sites to allow, a web font that didn't load.
+ *
+ * @module ui/notice
+ */
+export type Notice = {
+    /**
+     * Its sprite symbol's id.
+     */
+    icon: string;
+    /**
+     * An information's icon is grey, a warning's red. Default `warning`.
+     */
+    tone?: 'info' | 'warning';
+    /**
+     * The heading.
+     */
+    title: string;
+    /**
+     * The line under it.
+     */
+    text: string;
+    /**
+     * Icon buttons at the heading's end.
+     */
+    buttons?: HTMLElement[];
+    /**
+     * Buttons under the line, at the end (“Allow”).
+     */
+    actions?: HTMLElement[];
+    /**
+     * The page. Default `document`.
+     */
+    doc?: Document;
+};
+/**
+ * A notice's parts.
+ *
+ * @typedef {object} Notice
+ * @property {string} icon Its sprite symbol's id.
+ * @property {'info' | 'warning'} [tone] An information's icon is grey, a warning's red. Default `warning`.
+ * @property {string} title The heading.
+ * @property {string} text The line under it.
+ * @property {HTMLElement[]} [buttons] Icon buttons at the heading's end.
+ * @property {HTMLElement[]} [actions] Buttons under the line, at the end (“Allow”).
+ * @property {Document} [doc] The page. Default `document`.
+ */
+/**
+ * A notice card.
+ *
+ * @param {Notice} notice - Its parts.
+ * @returns {HTMLElement} The card.
+ * @example
+ * notices.append(noticeCard({ icon: 'i-frame', tone: 'info', title: t('panelFrames'), text, actions: [allow] }));
+ */
+export declare function noticeCard({ icon, tone, title, text, buttons, actions, doc }: Notice): HTMLElement;

package/src/ui/notice.js

@@ -0,0 +1,43 @@
+/**
+ * A notice in a side panel's list (chrome-ui.css `.sp-notice`): a card with an icon, a heading,
+ * a line, buttons beside the heading and actions under the line. For what a list leaves out or
+ * can't do: frames from other sites to allow, a web font that didn't load.
+ *
+ * @module ui/notice
+ */
+
+import { make, spriteIcon } from '../dom/make.js';
+
+/**
+ * A notice's parts.
+ *
+ * @typedef {object} Notice
+ * @property {string} icon Its sprite symbol's id.
+ * @property {'info' | 'warning'} [tone] An information's icon is grey, a warning's red. Default `warning`.
+ * @property {string} title The heading.
+ * @property {string} text The line under it.
+ * @property {HTMLElement[]} [buttons] Icon buttons at the heading's end.
+ * @property {HTMLElement[]} [actions] Buttons under the line, at the end (“Allow”).
+ * @property {Document} [doc] The page. Default `document`.
+ */
+
+/**
+ * A notice card.
+ *
+ * @param {Notice} notice - Its parts.
+ * @returns {HTMLElement} The card.
+ * @example
+ * notices.append(noticeCard({ icon: 'i-frame', tone: 'info', title: t('panelFrames'), text, actions: [allow] }));
+ */
+export function noticeCard({ icon, tone = 'warning', title, text, buttons = [], actions = [], doc = document }) {
+  const card = make('section', `sp-card sp-notice ${tone}`, '', doc);
+  const heading = make('div', 'sp-heading', '', doc);
+  heading.append(spriteIcon(icon, '', doc), make('h2', '', title, doc), ...buttons);
+  card.append(heading, make('p', 'sp-notice-text', text, doc));
+  if (actions.length) {
+    const row = make('div', 'sp-notice-actions', '', doc);
+    row.append(...actions);
+    card.append(row);
+  }
+  return card;
+}

package/src/ui/site-list.js

@@ -27,6 +27,7 @@
  * @module ui/site-list
  */
 
+import { focusedIn } from '../dom/focus.js';
 import { createMenu, moreActionsButton } from './menu.js';
 import { askText } from './text-dialog.js';
 import { MAX_HOST_LENGTH, siteLabel } from '../sites/sites.js';
@@ -177,9 +178,11 @@ export function createSiteList({
   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 = '';
+    const typed = input.value;
+    const site = parse(typed);
+    if (!site) invalid?.(typed);
+    // Cleared only if it's still what was added: adding can wait on Chrome (a permission prompt), and the next site may be typed meanwhile.
+    else if (await add(site) !== false && input.value === typed) input.value = '';
   });
   addButton?.addEventListener('click', async () => {
     const site = await ask(w.addSite, w.add);
@@ -219,6 +222,11 @@ export function createSiteList({
 
   return {
     render(sites) {
+      // The focus stays in the list across a redraw: on the same row's button (the one after a removed
+      // row, the last after the last), or on the way to add when no row is left. Without this, the
+      // row's button a dialog or menu gave the focus back to is replaced and the focus falls to the page.
+      const focused = focusedIn(list);
+      const at = focused && list.contains(focused) ? [...list.children].findIndex((row) => row.contains(focused)) : -1;
       list.replaceChildren(...sites.map((site) => {
         const row = doc.createElement('li');
         row.className = 'row';
@@ -229,6 +237,7 @@ export function createSiteList({
         return row;
       }));
       if (empty) empty.hidden = sites.length > 0;
+      if (at >= 0) (list.children[Math.min(at, sites.length - 1)]?.querySelector('button') ?? addButton ?? form?.querySelector('input'))?.focus();
     },
   };
 }

package/src/ui/text-dialog.d.ts

@@ -4,8 +4,9 @@
  * folder's name (`askText`); several, as chrome://settings/searchEngines asks
  * for a site search (`askFields`). The action button stays disabled while a
  * field is blank or isn't valid, with the reason under that field. Enter
- * means the action button, Esc and Cancel cancel, and the focus goes back to
- * what opened it. The page needs no markup: the dialog (`#text-dialog`) is
+ * means the action button, Esc and Cancel cancel (as does the dialog being
+ * closed any other way), and the focus goes back to what opened it. A reason
+ * is announced as it appears, and its field marked invalid. The page needs no markup: the dialog (`#text-dialog`) is
  * made the first time, its fields each time it's asked.
  *
  * @module ui/text-dialog

package/src/ui/text-dialog.js

@@ -4,8 +4,9 @@
  * folder's name (`askText`); several, as chrome://settings/searchEngines asks
  * for a site search (`askFields`). The action button stays disabled while a
  * field is blank or isn't valid, with the reason under that field. Enter
- * means the action button, Esc and Cancel cancel, and the focus goes back to
- * what opened it. The page needs no markup: the dialog (`#text-dialog`) is
+ * means the action button, Esc and Cancel cancel (as does the dialog being
+ * closed any other way), and the focus goes back to what opened it. A reason
+ * is announced as it appears, and its field marked invalid. The page needs no markup: the dialog (`#text-dialog`) is
  * made the first time, its fields each time it's asked.
  *
  * @module ui/text-dialog
@@ -178,7 +179,7 @@ function fieldFor(doc, request, only) {
   input.value = typeof request.value === 'string' ? request.value : '';
   if (request.placeholder) input.placeholder = request.placeholder;
   if (request.maxLength !== undefined) input.maxLength = request.maxLength;
-  const error = element(doc, 'span', { id: ids.error, class: 'hint error' });
+  const error = element(doc, 'span', { id: ids.error, class: 'hint error', 'aria-live': 'polite' });
   error.hidden = true;
   const hint = element(doc, 'span', { id: ids.hint, class: 'hint secondary' });
   hint.hidden = true;
@@ -226,6 +227,9 @@ export function askFields({
     const { reason } = waiting ? { reason: '' } : checkText(input.value, request.validate);
     error.textContent = reason;
     error.hidden = !reason;
+    // Said to a screen reader as it appears, and the field marked (the stylesheet turns its underline red).
+    if (reason) input.setAttribute('aria-invalid', 'true');
+    else input.removeAttribute('aria-invalid');
     hint.textContent = waiting ? request.waiting ?? '' : typeof request.hint === 'function' ? request.hint(input.value) : request.hint ?? '';
     hint.hidden = !hint.textContent;
   };
@@ -291,6 +295,9 @@ export function askFields({
       event.preventDefault();
       settle(null);
     }, { signal });
+    // Closed any other way (the browser's own close after a second Esc, another script): cancelled, not left unanswered.
+    // (The event comes a task after the closing: one from the ask before this, already answered, finds the dialog open again.)
+    parts.dialog.addEventListener('close', () => { if (!parts.dialog.open) settle(null); }, { signal });
 
     parts.dialog.showModal();
     // The first field still to fill in, or the first, its text selected to type over.

package/src/ui/toast.js

@@ -93,6 +93,8 @@ export function createToast({ undoLabel = 'Undo', duration = TOAST_MS, undoDurat
       text.textContent = message;
       undoButton.hidden = !undo;
       undoLast = undo;
+      // Taken off the page since (a single-page site replaced its body): put back, or showing it would throw.
+      if (!toast.isConnected) (root?.isConnected === false ? doc.body : root ?? doc.body).append(toast);
       // Hidden and shown again, so it's the newest in the top layer (over a popover since).
       toast.togglePopover(false);
       toast.togglePopover(true);