@arraypress/extension-kit 1.6.0 → 1.7.0

package/src/testing/messages.js

@@ -0,0 +1,51 @@
+/**
+ * Chrome's message lookup for an extension's unit tests: its real `_locales`
+ * files, a locale's messages over `en`'s, named placeholders ("$SITE$" →
+ * `{site: {content: '$1'}}`) filled from substitutions as
+ * `chrome.i18n.getMessage` fills them. Node only. From the copies in Better
+ * Prices, Better Downloads, Better Saves and Clean Links (`test/helpers/i18n.js`).
+ *
+ * @module testing/messages
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * One locale's messages.json.
+ *
+ * @typedef {Record<string, {message: string, description?: string, placeholders?: Record<string, {content: string}>}>} Messages
+ */
+
+/**
+ * Read a locale's messages.
+ *
+ * @param {string} extensionDir - The extension's folder (with `_locales/`).
+ * @param {string} locale - "en" or "en_GB".
+ * @returns {Messages} Its messages.
+ * @example
+ * readMessages('extension', 'en_GB').optionsColour.message;
+ */
+export function readMessages(extensionDir, locale) {
+  return JSON.parse(readFileSync(path.join(extensionDir, '_locales', locale, 'messages.json'), 'utf8'));
+}
+
+/**
+ * `chrome.i18n.getMessage` over a locale's real messages ('' for a missing key, as Chrome gives).
+ *
+ * @param {string} extensionDir - The extension's folder.
+ * @param {string} [locale] - Default "en"; another locale is read over en.
+ * @returns {(key: string, substitutions?: string | string[]) => string} The lookup.
+ * @example
+ * const t = messageLookup('extension');
+ * t('optionsMoreActions', ['example.com']); // 'More actions for example.com'
+ */
+export function messageLookup(extensionDir, locale = 'en') {
+  const messages = { ...readMessages(extensionDir, 'en'), ...(locale === 'en' ? {} : readMessages(extensionDir, locale)) };
+  return (key, substitutions = []) => {
+    const entry = messages[key];
+    if (!entry) return '';
+    const subs = [substitutions].flat();
+    return entry.message.replace(/\$([A-Za-z_]+)\$/g, (_, name) => (entry.placeholders?.[name.toLowerCase()]?.content ?? '')
+      .replace(/\$(\d)/g, (/** @type {string} */ __, /** @type {string} */ n) => subs[Number(n) - 1] ?? ''));
+  };
+}

package/src/ui/model-row.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The settings row “Chrome’s built-in AI”: how the on-device model stands,
+ * what that means, and Download when it can be had, with Chrome's progress.
+ * The download starts from the click (Chrome only downloads from a user
+ * gesture): nothing is awaited in the click before `create()`. The words are
+ * the page's messages under {@link MODEL_MESSAGES}' keys.
+ *
+ * Markup it fills (the page's, so it sits in any card):
+ *
+ * ```html
+ * <div class="row two-line">
+ *   <span class="label">
+ *     <span data-i18n="optionsModel">Chrome’s built-in AI</span>
+ *     <span class="secondary"><span id="model-status"></span> <span id="model-help" hidden></span></span>
+ *     <progress id="model-progress" max="1" value="0" hidden></progress>
+ *   </span>
+ *   <button id="model-download" type="button" data-i18n="optionsModelDownload" hidden>Download</button>
+ * </div>
+ * ```
+ *
+ * @module ui/model-row
+ */
+import type { Availability, LanguageModelOptions, LanguageModelStatic, ModelStatus } from '../ai/model.js';
+export type ModelRowParts = {
+    /**
+     * The state's words.
+     */
+    status: HTMLElement;
+    /**
+     * What it means, or why a download failed.
+     */
+    help: HTMLElement;
+    /**
+     * Download.
+     */
+    download: HTMLButtonElement;
+    /**
+     * The download's progress, 0–1.
+     */
+    progress: HTMLProgressElement;
+};
+export type ModelRowOptions = {
+    /**
+     * What sessions are made with (a download is for these).
+     */
+    options: LanguageModelOptions;
+    /**
+     * The model's state as the code that uses it sees it (the
+     * worker's, asked by message, when the worker uses it).
+     */
+    state: () => Promise<Availability>;
+    /**
+     * The page's messages.
+     */
+    t: (key: string, substitutions?: string | string[]) => string;
+    /**
+     * The Prompt API in this page. Default Chrome's.
+     */
+    model?: () => LanguageModelStatic | undefined;
+    /**
+     * Hears each state shown
+     * (to turn the switches that need the model on or off).
+     */
+    onShown?: (status: ModelStatus, availability: Availability) => void;
+};
+export type ModelRow = {
+    /**
+     * Ask the state again and show it.
+     */
+    refresh: () => Promise<Availability>;
+    /**
+     * The state last shown (null before the first).
+     */
+    current: () => Availability | null;
+};
+/** @import { Availability, LanguageModelOptions, LanguageModelStatic, ModelStatus } from '../ai/model.js' */
+/**
+ * @typedef {object} ModelRowParts
+ * @property {HTMLElement} status The state's words.
+ * @property {HTMLElement} help What it means, or why a download failed.
+ * @property {HTMLButtonElement} download Download.
+ * @property {HTMLProgressElement} progress The download's progress, 0–1.
+ */
+/**
+ * @typedef {object} ModelRowOptions
+ * @property {LanguageModelOptions} options What sessions are made with (a download is for these).
+ * @property {() => Promise<Availability>} state The model's state as the code that uses it sees it (the
+ *   worker's, asked by message, when the worker uses it).
+ * @property {(key: string, substitutions?: string | string[]) => string} t The page's messages.
+ * @property {() => LanguageModelStatic | undefined} [model] The Prompt API in this page. Default Chrome's.
+ * @property {(status: ModelStatus, availability: Availability) => void} [onShown] Hears each state shown
+ *   (to turn the switches that need the model on or off).
+ */
+/**
+ * @typedef {object} ModelRow
+ * @property {() => Promise<Availability>} refresh Ask the state again and show it.
+ * @property {() => Availability | null} current The state last shown (null before the first).
+ */
+/**
+ * Wire the row up and show the model's state.
+ *
+ * @param {ModelRowParts} parts - The row's elements.
+ * @param {ModelRowOptions} setup - What to ask, and the words.
+ * @returns {ModelRow} The row.
+ * @example
+ * const row = createModelRow({ status: byId('model-status'), help: byId('model-help'),
+ *   download: byId('model-download', HTMLButtonElement), progress: byId('model-progress', HTMLProgressElement) },
+ *   { options: SESSION_OPTIONS, state: () => ask(MESSAGES.modelState), t, onShown: ({ state }) => { useAi.disabled = state === 'off'; } });
+ * await row.refresh();
+ */
+export declare function createModelRow({ status, help, download, progress }: ModelRowParts, { options, state, t, model, onShown }: ModelRowOptions): ModelRow;

package/src/ui/model-row.js

@@ -0,0 +1,108 @@
+/**
+ * The settings row “Chrome’s built-in AI”: how the on-device model stands,
+ * what that means, and Download when it can be had, with Chrome's progress.
+ * The download starts from the click (Chrome only downloads from a user
+ * gesture): nothing is awaited in the click before `create()`. The words are
+ * the page's messages under {@link MODEL_MESSAGES}' keys.
+ *
+ * Markup it fills (the page's, so it sits in any card):
+ *
+ * ```html
+ * <div class="row two-line">
+ *   <span class="label">
+ *     <span data-i18n="optionsModel">Chrome’s built-in AI</span>
+ *     <span class="secondary"><span id="model-status"></span> <span id="model-help" hidden></span></span>
+ *     <progress id="model-progress" max="1" value="0" hidden></progress>
+ *   </span>
+ *   <button id="model-download" type="button" data-i18n="optionsModelDownload" hidden>Download</button>
+ * </div>
+ * ```
+ *
+ * @module ui/model-row
+ */
+
+import { MODEL_MESSAGES, chromeLanguageModel, describeModel, downloadModel } from '../ai/model.js';
+
+/** @import { Availability, LanguageModelOptions, LanguageModelStatic, ModelStatus } from '../ai/model.js' */
+
+/**
+ * @typedef {object} ModelRowParts
+ * @property {HTMLElement} status The state's words.
+ * @property {HTMLElement} help What it means, or why a download failed.
+ * @property {HTMLButtonElement} download Download.
+ * @property {HTMLProgressElement} progress The download's progress, 0–1.
+ */
+
+/**
+ * @typedef {object} ModelRowOptions
+ * @property {LanguageModelOptions} options What sessions are made with (a download is for these).
+ * @property {() => Promise<Availability>} state The model's state as the code that uses it sees it (the
+ *   worker's, asked by message, when the worker uses it).
+ * @property {(key: string, substitutions?: string | string[]) => string} t The page's messages.
+ * @property {() => LanguageModelStatic | undefined} [model] The Prompt API in this page. Default Chrome's.
+ * @property {(status: ModelStatus, availability: Availability) => void} [onShown] Hears each state shown
+ *   (to turn the switches that need the model on or off).
+ */
+
+/**
+ * @typedef {object} ModelRow
+ * @property {() => Promise<Availability>} refresh Ask the state again and show it.
+ * @property {() => Availability | null} current The state last shown (null before the first).
+ */
+
+/**
+ * Wire the row up and show the model's state.
+ *
+ * @param {ModelRowParts} parts - The row's elements.
+ * @param {ModelRowOptions} setup - What to ask, and the words.
+ * @returns {ModelRow} The row.
+ * @example
+ * const row = createModelRow({ status: byId('model-status'), help: byId('model-help'),
+ *   download: byId('model-download', HTMLButtonElement), progress: byId('model-progress', HTMLProgressElement) },
+ *   { options: SESSION_OPTIONS, state: () => ask(MESSAGES.modelState), t, onShown: ({ state }) => { useAi.disabled = state === 'off'; } });
+ * await row.refresh();
+ */
+export function createModelRow({ status, help, download, progress }, { options, state, t, model = chromeLanguageModel, onShown }) {
+  /** @type {Availability | null} */
+  let shown = null;
+
+  /**
+   * Show a state, or why the last download failed.
+   *
+   * @param {Availability} availability - The model's.
+   * @param {string} [problem] - What went wrong.
+   */
+  function show(availability, problem = '') {
+    const described = describeModel(availability);
+    shown = availability;
+    status.dataset.state = described.state;
+    status.textContent = t(described.status);
+    help.textContent = problem || (described.help ? t(described.help) : '');
+    help.hidden = !help.textContent;
+    download.hidden = !described.canDownload;
+    download.disabled = false;
+    progress.hidden = true;
+    onShown?.(described, availability);
+  }
+
+  download.addEventListener('click', () => {
+    download.disabled = true;
+    progress.hidden = false;
+    progress.value = 0;
+    downloadModel(model(), options, {
+      onProgress: (loaded) => {
+        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)));
+  });
+
+  return {
+    async refresh() {
+      const availability = await state();
+      show(availability);
+      return availability;
+    },
+    current: () => shown,
+  };
+}

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

@@ -20,13 +20,33 @@ export type FieldRequest = {
      */
     label: string;
     /**
-     * The text to start with. Default ''.
+     * The text to start with. Default ''. A promise is text
+     * still being worked out (an on-device model's suggestion): the field waits, disabled, with
+     * `waiting` under it, and takes the text when it comes ('' if it fails).
      */
-    value?: string;
+    value?: string | Promise<string>;
+    /**
+     * What the field says while its `value` is worked out ("Finding words…").
+     */
+    waiting?: string;
     /**
      * Shown while it's empty. Default none.
      */
     placeholder?: string;
+    /**
+     * A `<textarea>` (cr-textarea) rather than one line: Enter starts a new
+     * line, and only the action button saves. Default false.
+     */
+    multiline?: boolean;
+    /**
+     * A multi-line field's height in lines. Default 6.
+     */
+    rows?: number;
+    /**
+     * Help under the field (cr-input's
+     * description), or a function of its text, kept up as it's typed ("12 words"). Default none.
+     */
+    hint?: string | ((text: string) => string);
     /**
      * Why the (non-blank) text can't be used,
      * shown under the field; null when it can. Default: anything but blank.
@@ -71,8 +91,16 @@ export type FieldsRequest = DialogRequest & {
  * @typedef {object} FieldRequest
  * @property {string} name Its key in the answer ("folder"), and part of its id.
  * @property {string} label Its label ("Folder").
- * @property {string} [value] The text to start with. Default ''.
+ * @property {string | Promise<string>} [value] The text to start with. Default ''. A promise is text
+ *   still being worked out (an on-device model's suggestion): the field waits, disabled, with
+ *   `waiting` under it, and takes the text when it comes ('' if it fails).
+ * @property {string} [waiting] What the field says while its `value` is worked out ("Finding words…").
  * @property {string} [placeholder] Shown while it's empty. Default none.
+ * @property {boolean} [multiline] A `<textarea>` (cr-textarea) rather than one line: Enter starts a new
+ *   line, and only the action button saves. Default false.
+ * @property {number} [rows] A multi-line field's height in lines. Default 6.
+ * @property {string | ((text: string) => string)} [hint] Help under the field (cr-input's
+ *   description), or a function of its text, kept up as it's typed ("12 words"). Default none.
  * @property {(text: string) => string | null} [validate] Why the (non-blank) text can't be used,
  *   shown under the field; null when it can. Default: anything but blank.
  * @property {number} [maxLength] Its `maxlength`. Default none.
@@ -120,13 +148,14 @@ export declare function checkText(text: string, validate?: (text: string) => str
  *
  * @param {string} name - The field's name.
  * @param {boolean} only - Whether it's the dialog's only field.
- * @returns {{input: string, error: string}} The ids.
+ * @returns {{input: string, error: string, hint: string}} The ids.
  * @example
- * fieldIds('folder', false); // → {input: 'text-dialog-folder', error: 'text-dialog-folder-error'}
+ * fieldIds('folder', false); // → {input: 'text-dialog-folder', error: 'text-dialog-folder-error', hint: 'text-dialog-folder-hint'}
  */
 export declare function fieldIds(name: string, only: boolean): {
     input: string;
     error: string;
+    hint: string;
 };
 export type Parts = {
     /**
@@ -162,11 +191,19 @@ export type Field = {
     /**
      * Its input.
      */
-    input: HTMLInputElement;
+    input: HTMLInputElement | HTMLTextAreaElement;
     /**
      * The reason under it.
      */
     error: HTMLElement;
+    /**
+     * The help under it.
+     */
+    hint: HTMLElement;
+    /**
+     * Whether its value is still being worked out.
+     */
+    waiting: boolean;
 };
 /**
  * Ask for several pieces of text in the page's dialog, one field each.
@@ -199,4 +236,4 @@ export declare function askFields({ title, fields: requests, action, cancel, ret
  *   validate: (text) => (siteFromInput(text) ? null : 'Enter a site, like example.com'),
  * });
  */
-export declare function askText({ label, value, placeholder, validate, maxLength, ...dialog }: TextRequest): Promise<string | null>;
+export declare function askText({ label, value, placeholder, validate, maxLength, multiline, rows, hint, waiting, ...dialog }: TextRequest): Promise<string | null>;

package/src/ui/text-dialog.js

@@ -19,8 +19,16 @@ import { focusedElement } from '../dom/focus.js';
  * @typedef {object} FieldRequest
  * @property {string} name Its key in the answer ("folder"), and part of its id.
  * @property {string} label Its label ("Folder").
- * @property {string} [value] The text to start with. Default ''.
+ * @property {string | Promise<string>} [value] The text to start with. Default ''. A promise is text
+ *   still being worked out (an on-device model's suggestion): the field waits, disabled, with
+ *   `waiting` under it, and takes the text when it comes ('' if it fails).
+ * @property {string} [waiting] What the field says while its `value` is worked out ("Finding words…").
  * @property {string} [placeholder] Shown while it's empty. Default none.
+ * @property {boolean} [multiline] A `<textarea>` (cr-textarea) rather than one line: Enter starts a new
+ *   line, and only the action button saves. Default false.
+ * @property {number} [rows] A multi-line field's height in lines. Default 6.
+ * @property {string | ((text: string) => string)} [hint] Help under the field (cr-input's
+ *   description), or a function of its text, kept up as it's typed ("12 words"). Default none.
  * @property {(text: string) => string | null} [validate] Why the (non-blank) text can't be used,
  *   shown under the field; null when it can. Default: anything but blank.
  * @property {number} [maxLength] Its `maxlength`. Default none.
@@ -74,14 +82,14 @@ export function checkText(text, validate = () => null) {
  *
  * @param {string} name - The field's name.
  * @param {boolean} only - Whether it's the dialog's only field.
- * @returns {{input: string, error: string}} The ids.
+ * @returns {{input: string, error: string, hint: string}} The ids.
  * @example
- * fieldIds('folder', false); // → {input: 'text-dialog-folder', error: 'text-dialog-folder-error'}
+ * fieldIds('folder', false); // → {input: 'text-dialog-folder', error: 'text-dialog-folder-error', hint: 'text-dialog-folder-hint'}
  */
 export function fieldIds(name, only) {
   return only
-    ? { input: 'text-dialog-input', error: 'text-dialog-error' }
-    : { input: `text-dialog-${name}`, error: `text-dialog-${name}-error` };
+    ? { input: 'text-dialog-input', error: 'text-dialog-error', hint: 'text-dialog-hint' }
+    : { input: `text-dialog-${name}`, error: `text-dialog-${name}-error`, hint: `text-dialog-${name}-hint` };
 }
 
 /**
@@ -101,8 +109,10 @@ export function fieldIds(name, only) {
  *
  * @typedef {object} Field
  * @property {FieldRequest} request What was asked.
- * @property {HTMLInputElement} input Its input.
+ * @property {HTMLInputElement | HTMLTextAreaElement} input Its input.
  * @property {HTMLElement} error The reason under it.
+ * @property {HTMLElement} hint The help under it.
+ * @property {boolean} waiting Whether its value is still being worked out.
  */
 
 /** Each page's dialog, made on first use. @type {WeakMap<Document, Parts>} */
@@ -161,14 +171,19 @@ function fieldFor(doc, request, only) {
   const row = element(doc, 'div', { class: 'field' });
   const label = element(doc, 'label', { for: ids.input });
   label.textContent = request.label;
-  const input = element(doc, 'input', { id: ids.input, type: 'text', autocomplete: 'off', 'aria-describedby': ids.error });
-  input.value = request.value ?? '';
+  const described = `${ids.error} ${ids.hint}`;
+  const input = request.multiline
+    ? element(doc, 'textarea', { id: ids.input, rows: String(request.rows ?? 6), 'aria-describedby': described })
+    : element(doc, 'input', { id: ids.input, type: 'text', autocomplete: 'off', 'aria-describedby': described });
+  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' });
   error.hidden = true;
-  row.append(label, input, error);
-  return { row, field: { request, input, error } };
+  const hint = element(doc, 'span', { id: ids.hint, class: 'hint secondary' });
+  hint.hidden = true;
+  row.append(label, input, error, hint);
+  return { row, field: { request, input, error, hint, waiting: false } };
 }
 
 /** The open dialog's settle function, per page. @type {WeakMap<Document, (answer: Record<string, string> | null) => void>} */
@@ -205,12 +220,14 @@ export function askFields({
   parts.confirm.textContent = action;
   parts.cancel.textContent = cancel;
 
-  const allOk = () => fields.every(({ input, request }) => checkText(input.value, request.validate).ok);
+  const allOk = () => fields.every(({ input, request, waiting }) => !waiting && checkText(input.value, request.validate).ok);
   /** @param {Field} field */
-  const refresh = ({ input, error, request }) => {
-    const { reason } = checkText(input.value, request.validate);
+  const refresh = ({ input, error, hint, request, waiting }) => {
+    const { reason } = waiting ? { reason: '' } : checkText(input.value, request.validate);
     error.textContent = reason;
     error.hidden = !reason;
+    hint.textContent = waiting ? request.waiting ?? '' : typeof request.hint === 'function' ? request.hint(input.value) : request.hint ?? '';
+    hint.hidden = !hint.textContent;
   };
   for (const field of fields) refresh(field);
   parts.confirm.disabled = !allOk();
@@ -232,8 +249,29 @@ export function askFields({
       });
     };
     pending.set(doc, settle);
+    let typed = false;
+    // A value still being worked out: the field waits, then takes it, unless the dialog has moved on.
+    for (const field of fields) {
+      const { value } = field.request;
+      if (typeof value !== 'object' || !value) continue;
+      field.waiting = true;
+      field.input.disabled = true;
+      refresh(field);
+      value.catch(() => '').then((text) => {
+        if (signal.aborted) return;
+        field.waiting = false;
+        field.input.disabled = false;
+        field.input.value = text;
+        refresh(field);
+        parts.confirm.disabled = !allOk();
+        // The person was waiting for it: the focus moves in, unless they've been typing meanwhile.
+        if (!typed) field.input.focus();
+      });
+    }
+    parts.confirm.disabled = !allOk();
     for (const field of fields) {
       field.input.addEventListener('input', () => {
+        typed = true;
         refresh(field);
         parts.confirm.disabled = !allOk();
       }, { signal });
@@ -256,7 +294,7 @@ export function askFields({
 
     parts.dialog.showModal();
     // The first field still to fill in, or the first, its text selected to type over.
-    (fields.find(({ input }) => !input.value) ?? fields[0])?.input.select();
+    (fields.find(({ input }) => !input.value && !input.disabled) ?? fields[0])?.input.select();
   });
 }
 
@@ -275,8 +313,8 @@ export function askFields({
  * });
  */
 export async function askText({
-  label, value, placeholder, validate, maxLength, ...dialog
+  label, value, placeholder, validate, maxLength, multiline, rows, hint, waiting, ...dialog
 }) {
-  const answer = await askFields({ ...dialog, fields: [{ name: 'input', label, value, placeholder, validate, maxLength }] });
+  const answer = await askFields({ ...dialog, fields: [{ name: 'input', label, value, placeholder, validate, maxLength, multiline, rows, hint, waiting }] });
   return answer?.input ?? null;
 }