@arraypress/extension-kit 1.1.0 → 1.3.0

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

@@ -0,0 +1,199 @@
+/**
+ * A settings card's list of sites (“Never on”, “Allowed sites”), in one of
+ * Chrome's two ways:
+ *
+ * - **With an add row** (`form`), as a short list in a chrome://settings
+ *   card: a row per site with a Remove button, and below them a field and an
+ *   Add button.
+ * - **With an Add button and a dialog** (`addButton`), as
+ *   chrome://settings/performance lists the sites Memory Saver keeps active:
+ *   the button asks for a site in the one-field dialog (“Add site”), and each
+ *   row has a ⋮ menu with Edit and Remove.
+ *
+ * Either way, an optional “No sites added” row shows while there are none.
+ * The page's markup holds the list, the empty row and the form or button (so
+ * they're localised with the rest of the page); this fills the list and wires
+ * them up.
+ *
+ * ```html
+ * <ul class="list" id="never-sites"></ul>
+ * <p class="row text" id="no-sites"><span class="label secondary">No sites added</span></p>
+ * <form class="row add" id="add-never">
+ *   <input type="text" placeholder="example.com" aria-label="Site" autocomplete="off" spellcheck="false">
+ *   <button type="submit">Add</button>
+ * </form>
+ * ```
+ *
+ * @module ui/site-list
+ */
+export type SiteListWords = {
+    /**
+     * The Add button in the dialog.
+     */
+    add: string;
+    /**
+     * The dialog's title when adding.
+     */
+    addSite: string;
+    /**
+     * The dialog's title when editing.
+     */
+    editSite: string;
+    /**
+     * The ⋮ menu's Edit item.
+     */
+    edit: string;
+    /**
+     * The Remove button, or the ⋮ menu's Remove item.
+     */
+    remove: string;
+    /**
+     * The dialog's action when editing.
+     */
+    save: string;
+    /**
+     * The dialog's Cancel button.
+     */
+    cancel: string;
+    /**
+     * The dialog's field label.
+     */
+    site: string;
+    /**
+     * Under the dialog's field while what's typed isn't a site.
+     */
+    invalid: string;
+    /**
+     * The Remove button's name for screen readers.
+     */
+    removeLabel: (label: string) => string;
+    /**
+     * The ⋮ button's name for screen readers.
+     */
+    moreActions: (label: string) => string;
+};
+/**
+ * The list's words, Chrome's English by default; a page passes its translations.
+ *
+ * @typedef {object} SiteListWords
+ * @property {string} add The Add button in the dialog.
+ * @property {string} addSite The dialog's title when adding.
+ * @property {string} editSite The dialog's title when editing.
+ * @property {string} edit The ⋮ menu's Edit item.
+ * @property {string} remove The Remove button, or the ⋮ menu's Remove item.
+ * @property {string} save The dialog's action when editing.
+ * @property {string} cancel The dialog's Cancel button.
+ * @property {string} site The dialog's field label.
+ * @property {string} invalid Under the dialog's field while what's typed isn't a site.
+ * @property {(label: string) => string} removeLabel The Remove button's name for screen readers.
+ * @property {(label: string) => string} moreActions The ⋮ button's name for screen readers.
+ */
+/** @type {Readonly<SiteListWords>} */
+export declare const SITE_LIST_WORDS: Readonly<SiteListWords>;
+export type SiteListOptions = {
+    /**
+     * The `<ul class="list">` to fill.
+     */
+    list: HTMLElement;
+    /**
+     * Shown while the list is empty.
+     */
+    empty?: HTMLElement;
+    /**
+     * An add row: a form with one text field and a submit button.
+     */
+    form?: HTMLFormElement;
+    /**
+     * Or an Add button that asks in the dialog; each row then has a
+     * ⋮ menu (Edit, Remove) instead of a Remove button.
+     */
+    addButton?: HTMLElement;
+    /**
+     * What was typed as the site the list keeps
+     * (`siteHost`, `siteOrigin`), or null when it isn't one.
+     */
+    parse: (text: string) => string | null;
+    /**
+     * Adds a parsed site (asking Chrome for access first, if
+     * the list needs it). Resolve to false to keep the text in the add row's field (access refused).
+     */
+    add: (site: string) => unknown;
+    /**
+     * Removes a site.
+     */
+    remove: (site: string) => unknown;
+    /**
+     * Puts an edited site in place of
+     * the old one (the ⋮ menu's Edit; without it, the menu has only Remove).
+     */
+    replace?: (site: string, edited: string) => unknown;
+    /**
+     * The add row: called with what was typed when it isn't a site.
+     */
+    invalid?: (text: string) => void;
+    /**
+     * How a site reads. Default {@link siteLabel}.
+     */
+    label?: (site: string) => string;
+    /**
+     * The dialog field's `maxlength`. Default {@link MAX_HOST_LENGTH}.
+     */
+    maxLength?: number;
+    /**
+     * Translations of {@link SITE_LIST_WORDS}.
+     */
+    words?: Partial<SiteListWords>;
+};
+export type SiteList = {
+    /**
+     * Show these sites (call it whenever they change).
+     */
+    render: (sites: readonly string[]) => void;
+};
+/**
+ * What {@link createSiteList} takes: the list, one way to add to it, and
+ * what adding, removing and editing do.
+ *
+ * @typedef {object} SiteListOptions
+ * @property {HTMLElement} list The `<ul class="list">` to fill.
+ * @property {HTMLElement} [empty] Shown while the list is empty.
+ * @property {HTMLFormElement} [form] An add row: a form with one text field and a submit button.
+ * @property {HTMLElement} [addButton] Or an Add button that asks in the dialog; each row then has a
+ *   ⋮ menu (Edit, Remove) instead of a Remove button.
+ * @property {(text: string) => string | null} parse What was typed as the site the list keeps
+ *   (`siteHost`, `siteOrigin`), or null when it isn't one.
+ * @property {(site: string) => unknown} add Adds a parsed site (asking Chrome for access first, if
+ *   the list needs it). Resolve to false to keep the text in the add row's field (access refused).
+ * @property {(site: string) => unknown} remove Removes a site.
+ * @property {(site: string, edited: string) => unknown} [replace] Puts an edited site in place of
+ *   the old one (the ⋮ menu's Edit; without it, the menu has only Remove).
+ * @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}.
+ */
+/**
+ * A site list.
+ *
+ * @typedef {object} SiteList
+ * @property {(sites: readonly string[]) => void} render Show these sites (call it whenever they change).
+ */
+/**
+ * Fill a site list and wire its way of adding: an add row (typing a site and
+ * pressing Enter or Add) or an Add button (the dialog, which keeps its Add off
+ * until what's typed is a site). A row's Remove (or its ⋮ menu's Remove and
+ * Edit) hands its site to `remove` (or `replace`).
+ *
+ * @param {SiteListOptions} options - The markup, the parser and what adding and removing do.
+ * @returns {SiteList} The list.
+ * @example
+ * 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]) },
+ * });
+ * never.render(settings.neverSites);
+ */
+export declare function createSiteList({ list, empty, form, addButton, parse, add, remove, replace, invalid, label, maxLength, words, }: SiteListOptions): SiteList;

package/src/ui/site-list.js

@@ -0,0 +1,194 @@
+/**
+ * A settings card's list of sites (“Never on”, “Allowed sites”), in one of
+ * Chrome's two ways:
+ *
+ * - **With an add row** (`form`), as a short list in a chrome://settings
+ *   card: a row per site with a Remove button, and below them a field and an
+ *   Add button.
+ * - **With an Add button and a dialog** (`addButton`), as
+ *   chrome://settings/performance lists the sites Memory Saver keeps active:
+ *   the button asks for a site in the one-field dialog (“Add site”), and each
+ *   row has a ⋮ menu with Edit and Remove.
+ *
+ * Either way, an optional “No sites added” row shows while there are none.
+ * The page's markup holds the list, the empty row and the form or button (so
+ * they're localised with the rest of the page); this fills the list and wires
+ * them up.
+ *
+ * ```html
+ * <ul class="list" id="never-sites"></ul>
+ * <p class="row text" id="no-sites"><span class="label secondary">No sites added</span></p>
+ * <form class="row add" id="add-never">
+ *   <input type="text" placeholder="example.com" aria-label="Site" autocomplete="off" spellcheck="false">
+ *   <button type="submit">Add</button>
+ * </form>
+ * ```
+ *
+ * @module ui/site-list
+ */
+
+import { createMenu, moreActionsButton } from './menu.js';
+import { askText } from './text-dialog.js';
+import { MAX_HOST_LENGTH, siteLabel } from '../sites/sites.js';
+
+/**
+ * The list's words, Chrome's English by default; a page passes its translations.
+ *
+ * @typedef {object} SiteListWords
+ * @property {string} add The Add button in the dialog.
+ * @property {string} addSite The dialog's title when adding.
+ * @property {string} editSite The dialog's title when editing.
+ * @property {string} edit The ⋮ menu's Edit item.
+ * @property {string} remove The Remove button, or the ⋮ menu's Remove item.
+ * @property {string} save The dialog's action when editing.
+ * @property {string} cancel The dialog's Cancel button.
+ * @property {string} site The dialog's field label.
+ * @property {string} invalid Under the dialog's field while what's typed isn't a site.
+ * @property {(label: string) => string} removeLabel The Remove button's name for screen readers.
+ * @property {(label: string) => string} moreActions The ⋮ button's name for screen readers.
+ */
+
+/** @type {Readonly<SiteListWords>} */
+export const SITE_LIST_WORDS = Object.freeze({
+  add: 'Add',
+  addSite: 'Add site',
+  editSite: 'Edit site',
+  edit: 'Edit',
+  remove: 'Remove',
+  save: 'Save',
+  cancel: 'Cancel',
+  site: 'Site',
+  invalid: 'Enter a site, like example.com',
+  removeLabel: (/** @type {string} */ label) => `Remove “${label}”`,
+  moreActions: (/** @type {string} */ label) => `More actions for “${label}”`,
+});
+
+/**
+ * What {@link createSiteList} takes: the list, one way to add to it, and
+ * what adding, removing and editing do.
+ *
+ * @typedef {object} SiteListOptions
+ * @property {HTMLElement} list The `<ul class="list">` to fill.
+ * @property {HTMLElement} [empty] Shown while the list is empty.
+ * @property {HTMLFormElement} [form] An add row: a form with one text field and a submit button.
+ * @property {HTMLElement} [addButton] Or an Add button that asks in the dialog; each row then has a
+ *   ⋮ menu (Edit, Remove) instead of a Remove button.
+ * @property {(text: string) => string | null} parse What was typed as the site the list keeps
+ *   (`siteHost`, `siteOrigin`), or null when it isn't one.
+ * @property {(site: string) => unknown} add Adds a parsed site (asking Chrome for access first, if
+ *   the list needs it). Resolve to false to keep the text in the add row's field (access refused).
+ * @property {(site: string) => unknown} remove Removes a site.
+ * @property {(site: string, edited: string) => unknown} [replace] Puts an edited site in place of
+ *   the old one (the ⋮ menu's Edit; without it, the menu has only Remove).
+ * @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}.
+ */
+
+/**
+ * A site list.
+ *
+ * @typedef {object} SiteList
+ * @property {(sites: readonly string[]) => void} render Show these sites (call it whenever they change).
+ */
+
+/**
+ * Fill a site list and wire its way of adding: an add row (typing a site and
+ * pressing Enter or Add) or an Add button (the dialog, which keeps its Add off
+ * until what's typed is a site). A row's Remove (or its ⋮ menu's Remove and
+ * Edit) hands its site to `remove` (or `replace`).
+ *
+ * @param {SiteListOptions} options - The markup, the parser and what adding and removing do.
+ * @returns {SiteList} The list.
+ * @example
+ * 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]) },
+ * });
+ * never.render(settings.neverSites);
+ */
+export function createSiteList({
+  list, empty, form, addButton, parse, add, remove, replace, invalid, label = siteLabel, maxLength = MAX_HOST_LENGTH, words,
+}) {
+  const doc = list.ownerDocument;
+  const w = { ...SITE_LIST_WORDS, ...words };
+  const menu = addButton ? createMenu({ doc }) : null;
+
+  /**
+   * Ask for a site in the dialog.
+   *
+   * @param {string} title - Its title.
+   * @param {string} action - Its action button.
+   * @param {string} [value] - The site to start with.
+   * @returns {Promise<string | null>} The site, parsed, or null when cancelled.
+   */
+  const ask = async (title, action, value) => {
+    const text = await askText({
+      title, label: w.site, value, action, cancel: w.cancel, maxLength, doc,
+      validate: (typed) => (parse(typed) ? null : w.invalid),
+    });
+    return text === null ? null : parse(text);
+  };
+
+  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 = '';
+  });
+  addButton?.addEventListener('click', async () => {
+    const site = await ask(w.addSite, w.add);
+    if (site) await add(site);
+  });
+
+  /**
+   * The end of a site's row: its ⋮ button, or its Remove button.
+   *
+   * @param {string} site - The site.
+   * @param {string} name - How it reads.
+   * @returns {HTMLButtonElement} The button.
+   */
+  const rowEnd = (site, name) => {
+    if (menu) {
+      return moreActionsButton(name, {
+        label: w.moreActions(name), doc,
+        onClick: (anchor) => menu.open([
+          ...replace ? [{
+            label: w.edit,
+            run: async () => {
+              const edited = await ask(w.editSite, w.save, name);
+              if (edited && edited !== site) await replace(site, edited);
+            },
+          }] : [],
+          { label: w.remove, run: () => remove(site) },
+        ], { anchor }),
+      });
+    }
+    const button = doc.createElement('button');
+    button.type = 'button';
+    button.textContent = w.remove;
+    button.setAttribute('aria-label', w.removeLabel(name));
+    button.addEventListener('click', () => remove(site));
+    return button;
+  };
+
+  return {
+    render(sites) {
+      list.replaceChildren(...sites.map((site) => {
+        const row = doc.createElement('li');
+        row.className = 'row';
+        const name = doc.createElement('span');
+        name.className = 'label';
+        name.textContent = label(site);
+        row.append(name, rowEnd(site, name.textContent));
+        return row;
+      }));
+      if (empty) empty.hidden = sites.length > 0;
+    },
+  };
+}

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

@@ -0,0 +1,132 @@
+/**
+ * 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.
+ *
+ * @module ui/text-dialog
+ */
+export type TextRequest = {
+    /**
+     * The dialog's title ("Rename folder").
+     */
+    title: string;
+    /**
+     * The field's label ("Name").
+     */
+    label: string;
+    /**
+     * The text to start with (selected). Default ''.
+     */
+    value?: string;
+    /**
+     * The action button's text. Default "Save".
+     */
+    action?: string;
+    /**
+     * The cancel button's text. Default "Cancel".
+     */
+    cancel?: 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.
+     */
+    maxLength?: number;
+    /**
+     * 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.
+     */
+    returnTo?: HTMLElement | (() => HTMLElement | null | undefined) | null;
+    /**
+     * The page. Default `document`.
+     */
+    doc?: Document;
+};
+/**
+ * What the dialog asks.
+ *
+ * @typedef {object} TextRequest
+ * @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`.
+ */
+/**
+ * Whether a text can be used, and the reason to show when it can't. Pure.
+ *
+ * @param {string} text - What's typed.
+ * @param {(text: string) => string | null} [validate] - Why a non-blank text can't be used, or null.
+ * @returns {{ok: boolean, reason: string}} `ok` when it can be used; `reason` is '' for blank text
+ *   (nothing to say yet) and for a usable one.
+ * @example
+ * checkText('  ');                         // → {ok: false, reason: ''}
+ * checkText('x', () => 'Enter a site');    // → {ok: false, reason: 'Enter a site'}
+ */
+export declare function checkText(text: string, validate?: (text: string) => string | null): {
+    ok: boolean;
+    reason: string;
+};
+export type Parts = {
+    /**
+     * The `<dialog>`.
+     */
+    dialog: HTMLDialogElement;
+    /**
+     * Its form.
+     */
+    form: HTMLFormElement;
+    /**
+     * The title.
+     */
+    title: HTMLElement;
+    /**
+     * The field's label.
+     */
+    label: HTMLLabelElement;
+    /**
+     * The field.
+     */
+    input: HTMLInputElement;
+    /**
+     * The reason under the field.
+     */
+    error: HTMLElement;
+    /**
+     * The cancel button.
+     */
+    cancel: HTMLButtonElement;
+    /**
+     * The action button.
+     */
+    confirm: HTMLButtonElement;
+};
+/**
+ * Ask for a piece of text in the page's one-field dialog.
+ *
+ * @param {TextRequest} request - What to ask.
+ * @returns {Promise<string | null>} The text, trimmed; null when cancelled.
+ * @example
+ * const name = await askText({title: 'Rename workspace', label: 'Name', value: workspace.name, maxLength: 200});
+ * if (name) rename(workspace, name);
+ *
+ * const site = await askText({
+ *   title: 'Add site', label: 'Site', action: 'Add',
+ *   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>;