@arraypress/extension-kit 1.10.0 → 1.11.0

package/src/toolbar/theme.d.ts

@@ -132,9 +132,12 @@ export type OffscreenApi = {
  *
  * @param {OffscreenApi} api - `chrome.offscreen` and `chrome.runtime`.
  * @param {string} [url] - The document, from the extension's root. Default {@link OFFSCREEN_PATH}.
+ * @param {string} [justification] - What the document is for, when it does more than watch the
+ *   scheme (it answers for Chrome's on-device model too, `serveModelOffscreen`): Chrome keeps it
+ *   with the document, so it has to be the whole truth.
  * @returns {Promise<boolean>} Whether it opened one (false: already open).
  */
-export declare function watchFromOffscreen({ offscreen, runtime }: OffscreenApi, url?: string): Promise<boolean>;
+export declare function watchFromOffscreen({ offscreen, runtime }: OffscreenApi, url?: string, justification?: string): Promise<boolean>;
 export type ToolbarWorkerApi = {
     /**
      * `chrome.storage`.
@@ -179,9 +182,14 @@ export type ToolbarWorkerApi = {
  * worker wakes.
  *
  * @param {ToolbarWorkerApi} api - `chrome`, or a fake.
+ * @param {{url?: string, justification?: string}} [document] - The offscreen document and what
+ *   it's for, when it isn't the kit's defaults ({@link watchFromOffscreen}).
  * @returns {ToolbarTheme} The theme, for tests.
  * @example
  * // background.js
  * startToolbarTheme(chrome);
  */
-export declare function startToolbarTheme(api: ToolbarWorkerApi): ToolbarTheme;
+export declare function startToolbarTheme(api: ToolbarWorkerApi, { url, justification }?: {
+    url?: string;
+    justification?: string;
+}): ToolbarTheme;

package/src/toolbar/theme.js

@@ -116,6 +116,9 @@ export function createToolbarTheme({ storage, action, extensionId }) {
 /** @type {Promise<boolean> | null} */
 let opening = null;
 
+/** Why the offscreen document is open, as Chrome is told. */
+const SCHEME_JUSTIFICATION = 'Reads whether Chrome is in light or dark mode, to show the matching toolbar icon.';
+
 /**
  * Open the offscreen document that watches the scheme (reason MATCH_MEDIA),
  * unless it's open. It stays open: it's one small page in the extension's own
@@ -125,16 +128,19 @@ let opening = null;
  *
  * @param {OffscreenApi} api - `chrome.offscreen` and `chrome.runtime`.
  * @param {string} [url] - The document, from the extension's root. Default {@link OFFSCREEN_PATH}.
+ * @param {string} [justification] - What the document is for, when it does more than watch the
+ *   scheme (it answers for Chrome's on-device model too, `serveModelOffscreen`): Chrome keeps it
+ *   with the document, so it has to be the whole truth.
  * @returns {Promise<boolean>} Whether it opened one (false: already open).
  */
-export function watchFromOffscreen({ offscreen, runtime }, url = OFFSCREEN_PATH) {
+export function watchFromOffscreen({ offscreen, runtime }, url = OFFSCREEN_PATH, justification = SCHEME_JUSTIFICATION) {
   opening ??= (async () => {
     const open = await runtime.getContexts({ contextTypes: ['OFFSCREEN_DOCUMENT'] });
     if (open.length) return false;
     await offscreen.createDocument({
       url,
       reasons: [offscreen.Reason.MATCH_MEDIA],
-      justification: 'Reads whether Chrome is in light or dark mode, to show the matching toolbar icon.',
+      justification,
     });
     return true;
   })().finally(() => { opening = null; });
@@ -159,15 +165,17 @@ export function watchFromOffscreen({ offscreen, runtime }, url = OFFSCREEN_PATH)
  * worker wakes.
  *
  * @param {ToolbarWorkerApi} api - `chrome`, or a fake.
+ * @param {{url?: string, justification?: string}} [document] - The offscreen document and what
+ *   it's for, when it isn't the kit's defaults ({@link watchFromOffscreen}).
  * @returns {ToolbarTheme} The theme, for tests.
  * @example
  * // background.js
  * startToolbarTheme(chrome);
  */
-export function startToolbarTheme(api) {
+export function startToolbarTheme(api, { url, justification } = {}) {
   const theme = createToolbarTheme({ storage: api.storage.local, action: api.action, extensionId: api.runtime.id });
   theme.restore();
-  watchFromOffscreen(api).catch((error) => console.error('Opening the colour scheme watcher:', error));
+  watchFromOffscreen(api, url, justification).catch((error) => console.error('Opening the colour scheme watcher:', error));
   api.runtime.onMessage.addListener((message, sender) => {
     theme.onMessage(message, sender);
     return false;

package/src/ui/menu.d.ts

@@ -99,8 +99,10 @@ export type Box = {
  *
  * @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()});
@@ -112,11 +114,12 @@ export declare function menuPosition(size: {
 }, viewport: {
     width: number;
     height: number;
-}, { anchor, x, y, placement }: {
+}, { anchor, x, y, placement, rtl }: {
     anchor?: Box;
     x?: number;
     y?: number;
     placement?: 'over' | 'below';
+    rtl?: boolean;
 }): {
     left: number;
     top: number;
@@ -163,6 +166,11 @@ export type ActionMenu = {
      * Close it, if open, and return the focus.
      */
     close: () => void;
+    /**
+     * Take it off the page and stop listening to the window (a content
+     * script's overlay being removed).
+     */
+    destroy: () => void;
 };
 /**
  * What {@link createMenu} takes.
@@ -182,6 +190,8 @@ export type ActionMenu = {
  * @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).
  */
 /**
  * Make a page's action menu: one `<dialog class="menu">` that any number of

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/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);