@arraypress/extension-kit 1.0.0 → 1.2.0

package/src/ui/menu.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Chrome's action menu (cr-action-menu), the ⋮ menu of chrome://bookmarks and
+ * chrome://settings: a `<dialog class="menu">` of `role="menuitem"` buttons,
+ * shown modally over the button that opened it (or at the pointer, for a
+ * right-click) and kept on screen. A click outside it, Esc, Tab or the window
+ * losing focus closes it; ↑/↓ (wrapping), Home and End move between its
+ * items; and focus goes back to where it came from. Also the rows' ⋮ button,
+ * labelled "More actions for …" as Chrome labels its own.
+ *
+ * Sources: ui/webui/resources/cr_elements/cr_action_menu/cr_action_menu.ts
+ * (a modal `<dialog>`; a click on its backdrop closes it; the anchor gets the
+ * focus back; ↑/↓ wrap) and cr_icon_button with cr:more-vert.
+ *
+ * @module ui/menu
+ */
+/** The gap kept between a menu and the window's edges, in px. */
+export declare const MENU_EDGE = 8;
+export type MenuItem = {
+    /**
+     * Its text ("Rename").
+     */
+    label: string;
+    /**
+     * Runs once the menu has closed.
+     */
+    run: () => unknown;
+    /**
+     * Greyed out, and skipped by the arrow keys.
+     */
+    disabled?: boolean;
+};
+export type MenuEntry = MenuItem | 'separator';
+export type MenuPlace = {
+    /**
+     * The button that opened it.
+     */
+    anchor?: HTMLElement;
+    /**
+     * Without an anchor: the pointer's x (a right-click's `clientX`).
+     */
+    x?: number;
+    /**
+     * Without an anchor: the pointer's y.
+     */
+    y?: number;
+    /**
+     * The menu's name for screen readers ("Actions for Research").
+     */
+    label?: string;
+    /**
+     * Where focus goes when it closes. Default the anchor, else what had focus.
+     */
+    focusTo?: HTMLElement;
+};
+export type Box = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+/**
+ * One item: its text, what it does, and whether it's greyed out.
+ *
+ * @typedef {object} MenuItem
+ * @property {string} label Its text ("Rename").
+ * @property {() => unknown} run Runs once the menu has closed.
+ * @property {boolean} [disabled] Greyed out, and skipped by the arrow keys.
+ */
+/**
+ * An item, or `'separator'` for a line between groups of items.
+ *
+ * @typedef {MenuItem | 'separator'} MenuEntry
+ */
+/**
+ * Where a menu opens: over (or below) the button that opened it, or at a
+ * pointer position.
+ *
+ * @typedef {object} MenuPlace
+ * @property {HTMLElement} [anchor] The button that opened it.
+ * @property {number} [x] Without an anchor: the pointer's x (a right-click's `clientX`).
+ * @property {number} [y] Without an anchor: the pointer's y.
+ * @property {string} [label] The menu's name for screen readers ("Actions for Research").
+ * @property {HTMLElement} [focusTo] Where focus goes when it closes. Default the anchor, else what had focus.
+ */
+/**
+ * A rectangle in the window, as `getBoundingClientRect()` gives it.
+ *
+ * @typedef {{left: number, top: number, right: number, bottom: number}} Box
+ */
+/**
+ * Where to put a menu, so it stays on screen. Pure.
+ *
+ * Over an anchor (Chrome's way): the menu's top at the anchor's top and its
+ * end at the anchor's end; moved up to end at the anchor's bottom when it
+ * would leave the window below. Below an anchor: 4px under it, or above it
+ * when there's no room. At a point: its top-left there, or its bottom-left
+ * when there's no room below. Always at least {@link MENU_EDGE} from the
+ * window's edges.
+ *
+ * @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'`).
+ * @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 declare function menuPosition(size: {
+    width: number;
+    height: number;
+}, viewport: {
+    width: number;
+    height: number;
+}, { anchor, x, y, placement }: {
+    anchor?: Box;
+    x?: number;
+    y?: number;
+    placement?: 'over' | 'below';
+}): {
+    left: number;
+    top: number;
+};
+/**
+ * Whether a point is inside a box (edges included). Pure.
+ *
+ * @param {Box} box - The box.
+ * @param {number} x - The point's x.
+ * @param {number} y - The point's y.
+ * @returns {boolean} True when inside.
+ */
+export declare function isInside(box: Box, x: number, y: number): boolean;
+export type MenuOptions = {
+    /**
+     * The menu element's id.
+     */
+    id?: string;
+    /**
+     * Where it opens from a button. Default `'over'`, as Chrome's.
+     */
+    placement?: 'over' | 'below';
+    /**
+     * The page. Default `document`.
+     */
+    doc?: Document;
+};
+export type ActionMenu = {
+    /**
+     * The `<dialog class="menu" role="menu">`, in the page's body.
+     */
+    element: HTMLDialogElement;
+    /**
+     * Fill it with `entries`
+     * and open it (closing it first if it's open).
+     */
+    open: (entries: readonly MenuEntry[], where: MenuPlace) => void;
+    /**
+     * Close it, if open, and return the focus.
+     */
+    close: () => void;
+};
+/**
+ * What {@link createMenu} takes.
+ *
+ * @typedef {object} MenuOptions
+ * @property {string} [id] The menu element's id.
+ * @property {'over' | 'below'} [placement] Where it opens from a button. Default `'over'`, as Chrome's.
+ * @property {Document} [doc] The page. Default `document`.
+ */
+/**
+ * A page's action menu.
+ *
+ * @typedef {object} ActionMenu
+ * @property {HTMLDialogElement} element The `<dialog class="menu" role="menu">`, in the page's body.
+ * @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.
+ */
+/**
+ * Make a page's action menu: one `<dialog class="menu">` that any number of
+ * ⋮ buttons (or right-clicks) open with their own items.
+ *
+ * @param {MenuOptions} [options] - Its id, placement and page.
+ * @returns {ActionMenu} The menu.
+ * @example
+ * const menu = createMenu();
+ * row.append(moreActionsButton(workspace.name, {
+ *   onClick: (button) => menu.open([
+ *     {label: 'Rename', run: () => rename(workspace)},
+ *     'separator',
+ *     {label: 'Delete', run: () => remove(workspace)},
+ *   ], {anchor: button}),
+ * }));
+ */
+export declare function createMenu({ id, placement, doc }?: MenuOptions): ActionMenu;
+export type MoreActionsOptions = {
+    /**
+     * The whole label, for a page that translates it. Default
+     * `More actions for “<name>”`, Chrome's words.
+     */
+    label?: string;
+    /**
+     * More classes, after `icon-button`.
+     */
+    className?: string;
+    /**
+     * In the tab order. Default true; false for a row that takes the
+     * focus itself and opens the menu from the keyboard.
+     */
+    focusable?: boolean;
+    /**
+     * Show the label on hover too (`title`). Default false.
+     */
+    tooltip?: boolean;
+    /**
+     * Opens its menu.
+     */
+    onClick?: (button: HTMLButtonElement, event: MouseEvent) => void;
+    /**
+     * The page. Default `document`.
+     */
+    doc?: Document;
+};
+/**
+ * What {@link moreActionsButton} takes.
+ *
+ * @typedef {object} MoreActionsOptions
+ * @property {string} [label] The whole label, for a page that translates it. Default
+ *   `More actions for “<name>”`, Chrome's words.
+ * @property {string} [className] More classes, after `icon-button`.
+ * @property {boolean} [focusable] In the tab order. Default true; false for a row that takes the
+ *   focus itself and opens the menu from the keyboard.
+ * @property {boolean} [tooltip] Show the label on hover too (`title`). Default false.
+ * @property {(button: HTMLButtonElement, event: MouseEvent) => void} [onClick] Opens its menu.
+ * @property {Document} [doc] The page. Default `document`.
+ */
+/**
+ * A row's ⋮ button: a 32px cr-icon-button with cr:more-vert (the
+ * stylesheet's `--icon-more-vert`, so the page needs no sprite), labelled for
+ * screen readers as Chrome labels its own.
+ *
+ * @param {string} name - What the row is ("Research"), for "More actions for “Research”".
+ * @param {MoreActionsOptions} [options] - Its label, classes, tab stop, tooltip and click.
+ * @returns {HTMLButtonElement} The button.
+ * @example
+ * row.append(moreActionsButton(site, {onClick: (button) => menu.open(siteItems(site), {anchor: button})}));
+ * // A translated label:
+ * moreActionsButton(name, {label: t('rowActions', name), className: 'row-menu', focusable: false});
+ */
+export declare function moreActionsButton(name: string, { label, className, focusable, tooltip, onClick, doc }?: MoreActionsOptions): HTMLButtonElement;

package/src/ui/menu.js

@@ -0,0 +1,279 @@
+/**
+ * Chrome's action menu (cr-action-menu), the ⋮ menu of chrome://bookmarks and
+ * chrome://settings: a `<dialog class="menu">` of `role="menuitem"` buttons,
+ * shown modally over the button that opened it (or at the pointer, for a
+ * right-click) and kept on screen. A click outside it, Esc, Tab or the window
+ * losing focus closes it; ↑/↓ (wrapping), Home and End move between its
+ * items; and focus goes back to where it came from. Also the rows' ⋮ button,
+ * labelled "More actions for …" as Chrome labels its own.
+ *
+ * Sources: ui/webui/resources/cr_elements/cr_action_menu/cr_action_menu.ts
+ * (a modal `<dialog>`; a click on its backdrop closes it; the anchor gets the
+ * focus back; ↑/↓ wrap) and cr_icon_button with cr:more-vert.
+ *
+ * @module ui/menu
+ */
+
+/** The gap kept between a menu and the window's edges, in px. */
+export const MENU_EDGE = 8;
+
+/** The gap between a button and a menu placed below it, in px. */
+const BELOW_GAP = 4;
+
+/**
+ * One item: its text, what it does, and whether it's greyed out.
+ *
+ * @typedef {object} MenuItem
+ * @property {string} label Its text ("Rename").
+ * @property {() => unknown} run Runs once the menu has closed.
+ * @property {boolean} [disabled] Greyed out, and skipped by the arrow keys.
+ */
+
+/**
+ * An item, or `'separator'` for a line between groups of items.
+ *
+ * @typedef {MenuItem | 'separator'} MenuEntry
+ */
+
+/**
+ * Where a menu opens: over (or below) the button that opened it, or at a
+ * pointer position.
+ *
+ * @typedef {object} MenuPlace
+ * @property {HTMLElement} [anchor] The button that opened it.
+ * @property {number} [x] Without an anchor: the pointer's x (a right-click's `clientX`).
+ * @property {number} [y] Without an anchor: the pointer's y.
+ * @property {string} [label] The menu's name for screen readers ("Actions for Research").
+ * @property {HTMLElement} [focusTo] Where focus goes when it closes. Default the anchor, else what had focus.
+ */
+
+/**
+ * A rectangle in the window, as `getBoundingClientRect()` gives it.
+ *
+ * @typedef {{left: number, top: number, right: number, bottom: number}} Box
+ */
+
+/**
+ * Where to put a menu, so it stays on screen. Pure.
+ *
+ * Over an anchor (Chrome's way): the menu's top at the anchor's top and its
+ * end at the anchor's end; moved up to end at the anchor's bottom when it
+ * would leave the window below. Below an anchor: 4px under it, or above it
+ * when there's no room. At a point: its top-left there, or its bottom-left
+ * when there's no room below. Always at least {@link MENU_EDGE} from the
+ * window's edges.
+ *
+ * @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'`).
+ * @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' }) {
+  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 (placement === 'below') {
+    const below = anchor.bottom + BELOW_GAP;
+    return { left: start, top: Math.max(MENU_EDGE, room(below) ? below : anchor.top - height - BELOW_GAP) };
+  }
+  return { left: start, top: Math.max(MENU_EDGE, room(anchor.top) ? anchor.top : anchor.bottom - height) };
+}
+
+/**
+ * Whether a point is inside a box (edges included). Pure.
+ *
+ * @param {Box} box - The box.
+ * @param {number} x - The point's x.
+ * @param {number} y - The point's y.
+ * @returns {boolean} True when inside.
+ */
+export function isInside(box, x, y) {
+  return x >= box.left && x <= box.right && y >= box.top && y <= box.bottom;
+}
+
+/**
+ * What {@link createMenu} takes.
+ *
+ * @typedef {object} MenuOptions
+ * @property {string} [id] The menu element's id.
+ * @property {'over' | 'below'} [placement] Where it opens from a button. Default `'over'`, as Chrome's.
+ * @property {Document} [doc] The page. Default `document`.
+ */
+
+/**
+ * A page's action menu.
+ *
+ * @typedef {object} ActionMenu
+ * @property {HTMLDialogElement} element The `<dialog class="menu" role="menu">`, in the page's body.
+ * @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.
+ */
+
+/**
+ * Make a page's action menu: one `<dialog class="menu">` that any number of
+ * ⋮ buttons (or right-clicks) open with their own items.
+ *
+ * @param {MenuOptions} [options] - Its id, placement and page.
+ * @returns {ActionMenu} The menu.
+ * @example
+ * const menu = createMenu();
+ * row.append(moreActionsButton(workspace.name, {
+ *   onClick: (button) => menu.open([
+ *     {label: 'Rename', run: () => rename(workspace)},
+ *     'separator',
+ *     {label: 'Delete', run: () => remove(workspace)},
+ *   ], {anchor: button}),
+ * }));
+ */
+export function createMenu({ id, placement = 'over', doc = document } = {}) {
+  const view = /** @type {Window & typeof globalThis} */ (doc.defaultView);
+  const menu = doc.createElement('dialog');
+  menu.className = 'menu';
+  menu.setAttribute('role', 'menu');
+  if (id) menu.id = id;
+  doc.body.append(menu);
+
+  /** @type {HTMLElement | null} */
+  let returnFocus = null;
+  /** @type {HTMLElement | null} */
+  let expanded = null;
+
+  const items = () => /** @type {HTMLButtonElement[]} */ ([...menu.querySelectorAll('[role="menuitem"]:not(:disabled)')]);
+
+  /** Close without returning the focus (another open follows at once). */
+  const shut = () => {
+    if (menu.open) menu.close();
+    expanded?.setAttribute('aria-expanded', 'false');
+    expanded = null;
+  };
+
+  const close = () => {
+    if (!menu.open) return;
+    const target = returnFocus;
+    returnFocus = null;
+    shut();
+    if (target?.isConnected) target.focus();
+  };
+
+  menu.addEventListener('keydown', (event) => {
+    const list = items();
+    const at = list.indexOf(/** @type {HTMLButtonElement} */ (doc.activeElement));
+    /** @param {number} index */
+    const go = (index) => {
+      event.preventDefault();
+      list[(index + list.length) % list.length]?.focus();
+    };
+    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();
+      close();
+    }
+  });
+  // Esc the browser handles itself (when the keydown above didn't see it).
+  menu.addEventListener('cancel', (event) => {
+    event.preventDefault();
+    close();
+  });
+  // A modal dialog's backdrop is part of it: a click there targets the dialog, outside its box.
+  menu.addEventListener('click', (event) => {
+    if (event.target === menu && !isInside(menu.getBoundingClientRect(), event.clientX, event.clientY)) close();
+  });
+  view.addEventListener('blur', close);
+
+  return {
+    element: menu,
+    open(entries, { anchor, x, y, label, focusTo }) {
+      shut();
+      menu.replaceChildren(...entries.map((entry) => {
+        if (entry === 'separator') {
+          const line = doc.createElement('hr');
+          line.setAttribute('role', 'separator');
+          return line;
+        }
+        const button = doc.createElement('button');
+        button.type = 'button';
+        button.setAttribute('role', 'menuitem');
+        button.tabIndex = -1;
+        button.textContent = entry.label;
+        button.disabled = Boolean(entry.disabled);
+        button.addEventListener('click', () => {
+          close();
+          entry.run();
+        });
+        return button;
+      }));
+      if (label) menu.setAttribute('aria-label', label);
+      else menu.removeAttribute('aria-label');
+
+      const active = doc.activeElement;
+      returnFocus = focusTo ?? anchor ?? (active instanceof view.HTMLElement ? active : null);
+      if (anchor?.hasAttribute('aria-haspopup')) {
+        anchor.setAttribute('aria-expanded', 'true');
+        expanded = anchor;
+      }
+      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,
+      });
+      menu.style.left = `${left}px`;
+      menu.style.top = `${top}px`;
+      items()[0]?.focus();
+    },
+    close,
+  };
+}
+
+/**
+ * What {@link moreActionsButton} takes.
+ *
+ * @typedef {object} MoreActionsOptions
+ * @property {string} [label] The whole label, for a page that translates it. Default
+ *   `More actions for “<name>”`, Chrome's words.
+ * @property {string} [className] More classes, after `icon-button`.
+ * @property {boolean} [focusable] In the tab order. Default true; false for a row that takes the
+ *   focus itself and opens the menu from the keyboard.
+ * @property {boolean} [tooltip] Show the label on hover too (`title`). Default false.
+ * @property {(button: HTMLButtonElement, event: MouseEvent) => void} [onClick] Opens its menu.
+ * @property {Document} [doc] The page. Default `document`.
+ */
+
+/**
+ * A row's ⋮ button: a 32px cr-icon-button with cr:more-vert (the
+ * stylesheet's `--icon-more-vert`, so the page needs no sprite), labelled for
+ * screen readers as Chrome labels its own.
+ *
+ * @param {string} name - What the row is ("Research"), for "More actions for “Research”".
+ * @param {MoreActionsOptions} [options] - Its label, classes, tab stop, tooltip and click.
+ * @returns {HTMLButtonElement} The button.
+ * @example
+ * row.append(moreActionsButton(site, {onClick: (button) => menu.open(siteItems(site), {anchor: button})}));
+ * // A translated label:
+ * moreActionsButton(name, {label: t('rowActions', name), className: 'row-menu', focusable: false});
+ */
+export function moreActionsButton(name, { label, className, focusable = true, tooltip = false, onClick, doc = document } = {}) {
+  const text = label ?? `More actions for “${name}”`;
+  const button = doc.createElement('button');
+  button.type = 'button';
+  button.className = className ? `icon-button ${className}` : 'icon-button';
+  button.setAttribute('aria-label', text);
+  button.setAttribute('aria-haspopup', 'menu');
+  if (tooltip) button.title = text;
+  if (!focusable) button.tabIndex = -1;
+  const icon = doc.createElement('span');
+  icon.className = 'icon icon-more-vert';
+  icon.setAttribute('aria-hidden', 'true');
+  button.append(icon);
+  if (onClick) button.addEventListener('click', (event) => onClick(button, event));
+  return button;
+}

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