@arraypress/extension-kit 1.3.0 → 1.5.0

package/src/ui/site-list.d.ts

@@ -90,6 +90,14 @@ export type SiteListWords = {
  */
 /** @type {Readonly<SiteListWords>} */
 export declare const SITE_LIST_WORDS: Readonly<SiteListWords>;
+/**
+ * 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 declare const SITE_LIST_MESSAGES: Readonly<Record<keyof SiteListWords, string>>;
 export type SiteListOptions = {
     /**
      * The `<ul class="list">` to fill.
@@ -140,7 +148,13 @@ export type SiteListOptions = {
      */
     maxLength?: number;
     /**
-     * Translations of {@link SITE_LIST_WORDS}.
+     * 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}).
+     */
+    t?: (key: string, substitutions?: string | string[]) => string;
+    /**
+     * Words that differ from those, by name.
      */
     words?: Partial<SiteListWords>;
 };
@@ -170,7 +184,10 @@ export type SiteList = {
  * @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 {Partial<SiteListWords>} [words] Translations of {@link SITE_LIST_WORDS}.
+ * @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.
@@ -190,10 +207,10 @@ export type SiteList = {
  * const never = createSiteList({
  *   list: byId('never-sites'), form: byId('add-never', HTMLFormElement), empty: byId('no-sites'),
  *   parse: siteHost,
- *   add: (host) => save({ neverSites: [...settings.neverSites, host] }),
- *   remove: (host) => save({ neverSites: settings.neverSites.filter((h) => h !== host) }),
- *   words: { remove: t('optionsRemove'), removeLabel: (site) => t('optionsRemoveLabel', [site]) },
+ *   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 declare function createSiteList({ list, empty, form, addButton, parse, add, remove, replace, invalid, label, maxLength, words, }: SiteListOptions): SiteList;
+export declare function createSiteList({ list, empty, form, addButton, parse, add, remove, replace, invalid, label, maxLength, t, words, }: SiteListOptions): SiteList;

package/src/ui/site-list.js

@@ -63,6 +63,43 @@ export const SITE_LIST_WORDS = Object.freeze({
   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.
@@ -83,7 +120,10 @@ export const SITE_LIST_WORDS = Object.freeze({
  * @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 {Partial<SiteListWords>} [words] Translations of {@link SITE_LIST_WORDS}.
+ * @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.
  */
 
 /**
@@ -105,17 +145,17 @@ export const SITE_LIST_WORDS = Object.freeze({
  * const never = createSiteList({
  *   list: byId('never-sites'), form: byId('add-never', HTMLFormElement), empty: byId('no-sites'),
  *   parse: siteHost,
- *   add: (host) => save({ neverSites: [...settings.neverSites, host] }),
- *   remove: (host) => save({ neverSites: settings.neverSites.filter((h) => h !== host) }),
- *   words: { remove: t('optionsRemove'), removeLabel: (site) => t('optionsRemoveLabel', [site]) },
+ *   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, words,
+  list, empty, form, addButton, parse, add, remove, replace, invalid, label = siteLabel, maxLength = MAX_HOST_LENGTH, t, words,
 }) {
   const doc = list.ownerDocument;
-  const w = { ...SITE_LIST_WORDS, ...words };
+  const w = { ...(t ? translatedWords(t) : SITE_LIST_WORDS), ...words };
   const menu = addButton ? createMenu({ doc }) : null;
 
   /**

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

@@ -1,43 +1,55 @@
 /**
- * Chrome's one-field dialog (cr-dialog with a cr-input), as chrome://bookmarks
- * asks for a folder's name: a title, a labelled field, Cancel and an action
- * button. The action button stays disabled while the text is blank or isn't
- * valid, with the reason under the 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 made the first time.
+ * Chrome's text dialog (cr-dialog with cr-inputs): a title, labelled fields,
+ * Cancel and an action button. One field, as chrome://bookmarks asks for a
+ * 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
+ * made the first time, its fields each time it's asked.
  *
  * @module ui/text-dialog
  */
-export type TextRequest = {
+export type FieldRequest = {
     /**
-     * The dialog's title ("Rename folder").
+     * Its key in the answer ("folder"), and part of its id.
      */
-    title: string;
+    name: string;
     /**
-     * The field's label ("Name").
+     * Its label ("Folder").
      */
     label: string;
     /**
-     * The text to start with (selected). Default ''.
+     * The text to start with. Default ''.
      */
     value?: string;
     /**
-     * The action button's text. Default "Save".
-     */
-    action?: string;
-    /**
-     * The cancel button's text. Default "Cancel".
+     * Shown while it's empty. Default none.
      */
-    cancel?: string;
+    placeholder?: string;
     /**
      * Why the (non-blank) text can't be used,
      * shown under the field; null when it can. Default: anything but blank.
      */
     validate?: (text: string) => string | null;
     /**
-     * The field's `maxlength`. Default none.
+     * Its `maxlength`. Default none.
      */
     maxLength?: number;
+};
+export type DialogRequest = {
+    /**
+     * The dialog's title ("Rename folder").
+     */
+    title: string;
+    /**
+     * The action button's text. Default "Save".
+     */
+    action?: string;
+    /**
+     * The cancel button's text. Default "Cancel".
+     */
+    cancel?: string;
     /**
      * Where the focus
      * goes when it closes, or a function that says (asked then, so it can pick a row drawn since).
@@ -49,23 +61,44 @@ export type TextRequest = {
      */
     doc?: Document;
 };
+export type TextRequest = DialogRequest & Omit<FieldRequest, 'name'>;
+export type FieldsRequest = DialogRequest & {
+    fields: FieldRequest[];
+};
 /**
- * What the dialog asks.
+ * One field of the dialog.
  *
- * @typedef {object} TextRequest
+ * @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} [placeholder] Shown while it's empty. 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.
+ */
+/**
+ * What the dialog asks, whatever its fields.
+ *
+ * @typedef {object} DialogRequest
  * @property {string} title The dialog's title ("Rename folder").
- * @property {string} label The field's label ("Name").
- * @property {string} [value] The text to start with (selected). Default ''.
  * @property {string} [action] The action button's text. Default "Save".
  * @property {string} [cancel] The cancel button's text. Default "Cancel".
- * @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] The field's `maxlength`. Default none.
  * @property {HTMLElement | (() => HTMLElement | null | undefined) | null} [returnTo] Where the focus
  *   goes when it closes, or a function that says (asked then, so it can pick a row drawn since).
  *   Default what had the focus when it opened.
  * @property {Document} [doc] The page. Default `document`.
  */
+/**
+ * What the one-field dialog asks.
+ *
+ * @typedef {DialogRequest & Omit<FieldRequest, 'name'>} TextRequest
+ */
+/**
+ * What the dialog with several fields asks.
+ *
+ * @typedef {DialogRequest & {fields: FieldRequest[]}} FieldsRequest
+ */
 /**
  * Whether a text can be used, and the reason to show when it can't. Pure.
  *
@@ -81,6 +114,20 @@ export declare function checkText(text: string, validate?: (text: string) => str
     ok: boolean;
     reason: string;
 };
+/**
+ * A field's element ids. A one-field dialog's are `text-dialog-input` and `text-dialog-error`;
+ * with several, each is named: `text-dialog-<name>` and `text-dialog-<name>-error`. Pure.
+ *
+ * @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.
+ * @example
+ * fieldIds('folder', false); // → {input: 'text-dialog-folder', error: 'text-dialog-folder-error'}
+ */
+export declare function fieldIds(name: string, only: boolean): {
+    input: string;
+    error: string;
+};
 export type Parts = {
     /**
      * The `<dialog>`.
@@ -95,17 +142,9 @@ export type Parts = {
      */
     title: HTMLElement;
     /**
-     * The field's label.
-     */
-    label: HTMLLabelElement;
-    /**
-     * The field.
-     */
-    input: HTMLInputElement;
-    /**
-     * The reason under the field.
+     * Where the fields go.
      */
-    error: HTMLElement;
+    body: HTMLElement;
     /**
      * The cancel button.
      */
@@ -115,8 +154,39 @@ export type Parts = {
      */
     confirm: HTMLButtonElement;
 };
+export type Field = {
+    /**
+     * What was asked.
+     */
+    request: FieldRequest;
+    /**
+     * Its input.
+     */
+    input: HTMLInputElement;
+    /**
+     * The reason under it.
+     */
+    error: HTMLElement;
+};
+/**
+ * Ask for several pieces of text in the page's dialog, one field each.
+ *
+ * @param {FieldsRequest} request - What to ask.
+ * @returns {Promise<Record<string, string> | null>} Each field's text by its name, trimmed; null
+ *   when cancelled.
+ * @example
+ * const rule = await askFields({
+ *   title: 'Add folder rule', action: 'Add',
+ *   fields: [
+ *     {name: 'from', label: 'Downloads from', placeholder: 'example.com or .pdf', validate: checkFrom},
+ *     {name: 'folder', label: 'Folder', placeholder: 'Receipts'},
+ *   ],
+ * });
+ * if (rule) addRule(rule.from, rule.folder);
+ */
+export declare function askFields({ title, fields: requests, action, cancel, returnTo, doc, }: FieldsRequest): Promise<Record<string, string> | null>;
 /**
- * Ask for a piece of text in the page's one-field dialog.
+ * Ask for a piece of text in the page's dialog, with one field.
  *
  * @param {TextRequest} request - What to ask.
  * @returns {Promise<string | null>} The text, trimmed; null when cancelled.
@@ -129,4 +199,4 @@ export type Parts = {
  *   validate: (text) => (siteFromInput(text) ? null : 'Enter a site, like example.com'),
  * });
  */
-export declare function askText({ title, label, value, action, cancel, validate, maxLength, returnTo, doc, }: TextRequest): Promise<string | null>;
+export declare function askText({ label, value, placeholder, validate, maxLength, ...dialog }: TextRequest): Promise<string | null>;