zabi-components 8.0.0 → 8.1.0

package/dist/util/stepper.d.ts

@@ -0,0 +1,39 @@
+/** Types and pure helpers for `Stepper`. Kept out of the component so they can be tested without a DOM. */
+/** One step: a label, and optionally a line under it. A plain string is a step with only a label. */
+export interface StepperStep {
+    label: string;
+    /** A short line under the label in the full layout, and under the current step's name in the compact one. */
+    description?: string;
+}
+/** A step as the `steps` prop takes it. */
+export type StepperItem = string | StepperStep;
+/** Where a step is in the flow. */
+export type StepperStepState = "completed" | "current" | "upcoming";
+export type StepperLayout = "auto" | "full" | "compact";
+/**
+ * Every built-in string. Pass a partial object to `strings` to translate.
+ * `step` is counted from 1 in all of them.
+ */
+export interface StepperStrings {
+    /** The visible start of the compact line: "Step 2 of 3". */
+    position: (step: number, total: number) => string;
+    /**
+     * What a screen reader reads for a step, and the name of its button when
+     * the step is one: "Step 1 of 3: Details, completed".
+     */
+    stepLabel: (step: number, total: number, label: string, state: StepperStepState) => string;
+    /** Read out, politely, when the current step changes: "Step 2 of 3: Ratings". */
+    announcement: (step: number, total: number, label: string) => string;
+}
+export declare const STEPPER_STRINGS: StepperStrings;
+/** Strings and objects alike, as objects. */
+export declare function normalizeSteps(steps: readonly StepperItem[] | null | undefined): StepperStep[];
+/**
+ * The index of the step that is shown as current: `current` as a whole number
+ * held within the steps. Below the first step it is the first, past the last
+ * it is the last, and something that is not a number is the first. `-1` when
+ * there are no steps.
+ */
+export declare function clampStep(current: number | null | undefined, total: number): number;
+/** The state of the step at `index` when the step at `current` is the current one. */
+export declare function stepState(index: number, current: number): StepperStepState;

package/dist/util/stepper.js

@@ -0,0 +1,38 @@
+/** Types and pure helpers for `Stepper`. Kept out of the component so they can be tested without a DOM. */
+const STATE_WORDS = {
+    completed: "completed",
+    current: "current",
+    upcoming: "upcoming",
+};
+export const STEPPER_STRINGS = {
+    position: (step, total) => `Step ${step} of ${total}`,
+    stepLabel: (step, total, label, state) => `Step ${step} of ${total}: ${label}, ${STATE_WORDS[state]}`,
+    announcement: (step, total, label) => `Step ${step} of ${total}: ${label}`,
+};
+/** Strings and objects alike, as objects. */
+export function normalizeSteps(steps) {
+    return (steps ?? []).map((step) => (typeof step === "string" ? { label: step } : step));
+}
+/**
+ * The index of the step that is shown as current: `current` as a whole number
+ * held within the steps. Below the first step it is the first, past the last
+ * it is the last, and something that is not a number is the first. `-1` when
+ * there are no steps.
+ */
+export function clampStep(current, total) {
+    if (total <= 0)
+        return -1;
+    if (current === null || current === undefined || Number.isNaN(current))
+        return 0;
+    if (current === Infinity)
+        return total - 1;
+    if (current === -Infinity)
+        return 0;
+    return Math.max(0, Math.min(total - 1, Math.trunc(current)));
+}
+/** The state of the step at `index` when the step at `current` is the current one. */
+export function stepState(index, current) {
+    if (index < current)
+        return "completed";
+    return index === current ? "current" : "upcoming";
+}

package/dist/util/swipeable-list-item.d.ts

@@ -0,0 +1,35 @@
+import type { Component } from "svelte";
+/** Public types and shared state for `SwipeableListItem`. */
+/** One action behind a row, such as Delete. */
+export interface SwipeableListItemAction {
+    id: string;
+    /** The button's text, and its accessible name. */
+    label: string;
+    /** Drawn above the label. */
+    icon?: Component<{
+        size?: number;
+        class?: string;
+    }>;
+    /** `danger` for an action that destroys something. */
+    tone?: "default" | "danger";
+    /** Runs when the button is pressed. The row closes afterwards. */
+    onselect: () => void;
+}
+/** The words a `SwipeableListItem` says by itself. */
+export interface SwipeableListItemStrings {
+    /** Accessible name of the button that opens the row's actions, and of the group they are in. */
+    actions: string;
+}
+export declare const DEFAULT_SWIPEABLE_LIST_ITEM_STRINGS: SwipeableListItemStrings;
+/**
+ * Says that a row has opened: every other open row in the same list closes.
+ * Returns what to call when this row closes or goes away.
+ */
+export declare function registerOpenRow(root: HTMLElement, close: () => void): () => void;
+/**
+ * Where a swipe ends: open or closed. A flick decides by its direction,
+ * whatever the distance; otherwise the row goes to whichever is nearer.
+ * `revealed` and `width` are px of the actions; `velocity` is px per ms,
+ * positive towards revealing.
+ */
+export declare function settleSwipe(revealed: number, width: number, velocity: number, flick: number): boolean;

package/dist/util/swipeable-list-item.js

@@ -0,0 +1,32 @@
+export const DEFAULT_SWIPEABLE_LIST_ITEM_STRINGS = {
+    actions: "Actions",
+};
+/** What groups rows: the nearest list around a row. Rows with none are each on their own. */
+const LIST = 'ul, ol, [role="list"], [role="listbox"]';
+/** The rows that are open now. */
+const openRows = new Set();
+/**
+ * Says that a row has opened: every other open row in the same list closes.
+ * Returns what to call when this row closes or goes away.
+ */
+export function registerOpenRow(root, close) {
+    const list = root.closest(LIST);
+    for (const other of [...openRows]) {
+        if (other.root !== root && list && other.root.closest(LIST) === list)
+            other.close();
+    }
+    const entry = { root, close };
+    openRows.add(entry);
+    return () => openRows.delete(entry);
+}
+/**
+ * Where a swipe ends: open or closed. A flick decides by its direction,
+ * whatever the distance; otherwise the row goes to whichever is nearer.
+ * `revealed` and `width` are px of the actions; `velocity` is px per ms,
+ * positive towards revealing.
+ */
+export function settleSwipe(revealed, width, velocity, flick) {
+    if (Math.abs(velocity) > flick)
+        return velocity > 0;
+    return revealed > width / 2;
+}

package/dist/util/theme-mode.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The page's theme mode, read and written in one place.
+ *
+ * The theme is switched on `<html>`: `data-theme="auto" | "light" | "dark"`,
+ * or the older `dark` class (THEMING.md, "Light, dark and auto"). ThemeToggle
+ * uses these helpers, and so can an app that renders a control of its own, a
+ * SegmentedControl with three options for instance: both then read and write
+ * the same attribute, and ThemeToggle follows whatever the other one sets.
+ *
+ * Everything here is safe to call on the server: without a document the
+ * readers return the default and the writers do nothing.
+ */
+/** `"auto"` follows the system; the other two are a choice. */
+export type ThemeMode = "auto" | "light" | "dark";
+/** The modes in the order a three-way ThemeToggle steps through them. */
+export declare const THEME_MODES: readonly ThemeMode[];
+/** Where the choice is kept in `localStorage` unless a key is given. The key ThemeToggle has always used. */
+export declare const DEFAULT_THEME_STORAGE_KEY = "theme";
+/** The texts ThemeToggle builds its accessible name from. Pass any of them as `labels`. */
+export interface ThemeToggleLabels {
+    /** What `"auto"` is called, with three modes. Default `"system"`. */
+    auto: string;
+    /** Default `"light"`. */
+    light: string;
+    /** Default `"dark"`. */
+    dark: string;
+    /**
+     * The name with three modes, from the current mode's word and the next
+     * one's. Default: "Theme: system. Switch to light".
+     */
+    describe: (current: string, next: string) => string;
+    /**
+     * The name with two modes. It does not change: the button is a switch, and
+     * `aria-pressed` says whether dark is on. Default "Dark mode".
+     */
+    darkMode: string;
+    /** The name before the button mounts, when the mode is not known yet. Default "Theme toggle". */
+    beforeMount: string;
+}
+export declare function isThemeMode(value: unknown): value is ThemeMode;
+/**
+ * The mode the page is in. `data-theme` says it outright; a page without the
+ * attribute is dark with the `dark` class and light without it (such a page
+ * does not follow the system, so it is never `"auto"`).
+ */
+export declare function getThemeMode(): ThemeMode;
+/** Whether the page is dark right now: by the class, by `data-theme="dark"`, or by `auto` on a dark system. */
+export declare function isThemeDark(): boolean;
+export interface SetThemeModeOptions {
+    /**
+     * Where to keep the choice in `localStorage`. Default `"theme"`; `null`
+     * keeps nothing (an app that stores the choice in its own backend).
+     */
+    storageKey?: string | null;
+}
+/**
+ * Puts the page in `mode` by writing `data-theme` on `<html>`, and remembers
+ * it. A leftover `dark` class and an inline `color-scheme` are removed: either
+ * would hold the page dark, or its native controls, under another mode. The
+ * theme sets `color-scheme` for each value of the attribute.
+ */
+export declare function setThemeMode(mode: ThemeMode, options?: SetThemeModeOptions): void;
+/** The stored choice, or `null` when there is none, it is not a mode, or `storageKey` is `null`. */
+export declare function getStoredThemeMode(storageKey?: string | null): ThemeMode | null;
+/** Remembers `mode` under `storageKey` (default `"theme"`); `null` keeps nothing. */
+export declare function storeThemeMode(mode: ThemeMode, storageKey?: string | null): void;
+/**
+ * A script for `<head>` that applies the stored mode before the first paint,
+ * so a returning visitor does not see the other theme flash by. Returns the
+ * source as a string; it has no dependencies and can be inlined as it is.
+ *
+ * It writes to whichever mechanism the page uses, as ThemeToggle does:
+ * `data-theme` when `<html>` already has the attribute or the stored mode is
+ * `"auto"`, and the `dark` class otherwise. With nothing stored it does
+ * nothing, and the markup's own `data-theme` (or its absence) stands.
+ *
+ * The key is written into the script as a JSON string, so any key is safe.
+ */
+export declare function themeInitScript(storageKey?: string): string;

package/dist/util/theme-mode.js

@@ -0,0 +1,121 @@
+/**
+ * The page's theme mode, read and written in one place.
+ *
+ * The theme is switched on `<html>`: `data-theme="auto" | "light" | "dark"`,
+ * or the older `dark` class (THEMING.md, "Light, dark and auto"). ThemeToggle
+ * uses these helpers, and so can an app that renders a control of its own, a
+ * SegmentedControl with three options for instance: both then read and write
+ * the same attribute, and ThemeToggle follows whatever the other one sets.
+ *
+ * Everything here is safe to call on the server: without a document the
+ * readers return the default and the writers do nothing.
+ */
+/** The modes in the order a three-way ThemeToggle steps through them. */
+export const THEME_MODES = ["auto", "light", "dark"];
+/** Where the choice is kept in `localStorage` unless a key is given. The key ThemeToggle has always used. */
+export const DEFAULT_THEME_STORAGE_KEY = "theme";
+export function isThemeMode(value) {
+    return value === "auto" || value === "light" || value === "dark";
+}
+function root() {
+    return typeof document === "undefined" ? undefined : document.documentElement;
+}
+function storage() {
+    try {
+        return typeof localStorage === "undefined" ? undefined : localStorage;
+    }
+    catch {
+        // Reading `localStorage` throws where storage is blocked.
+        return undefined;
+    }
+}
+/**
+ * The mode the page is in. `data-theme` says it outright; a page without the
+ * attribute is dark with the `dark` class and light without it (such a page
+ * does not follow the system, so it is never `"auto"`).
+ */
+export function getThemeMode() {
+    const html = root();
+    if (!html)
+        return "light";
+    const attribute = html.getAttribute("data-theme");
+    if (isThemeMode(attribute))
+        return attribute;
+    return html.classList.contains("dark") ? "dark" : "light";
+}
+/** Whether the page is dark right now: by the class, by `data-theme="dark"`, or by `auto` on a dark system. */
+export function isThemeDark() {
+    const html = root();
+    if (!html)
+        return false;
+    // The class brings the dark tokens whatever the attribute says.
+    if (html.classList.contains("dark"))
+        return true;
+    const mode = getThemeMode();
+    if (mode === "auto") {
+        return typeof window !== "undefined" && !!window.matchMedia?.("(prefers-color-scheme: dark)").matches;
+    }
+    return mode === "dark";
+}
+/**
+ * Puts the page in `mode` by writing `data-theme` on `<html>`, and remembers
+ * it. A leftover `dark` class and an inline `color-scheme` are removed: either
+ * would hold the page dark, or its native controls, under another mode. The
+ * theme sets `color-scheme` for each value of the attribute.
+ */
+export function setThemeMode(mode, options = {}) {
+    if (!isThemeMode(mode))
+        return;
+    const html = root();
+    if (!html)
+        return;
+    html.setAttribute("data-theme", mode);
+    html.classList.remove("dark");
+    html.style.removeProperty("color-scheme");
+    storeThemeMode(mode, options.storageKey);
+}
+/** The stored choice, or `null` when there is none, it is not a mode, or `storageKey` is `null`. */
+export function getStoredThemeMode(storageKey = DEFAULT_THEME_STORAGE_KEY) {
+    if (storageKey === null)
+        return null;
+    try {
+        const stored = storage()?.getItem(storageKey);
+        return isThemeMode(stored) ? stored : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Remembers `mode` under `storageKey` (default `"theme"`); `null` keeps nothing. */
+export function storeThemeMode(mode, storageKey = DEFAULT_THEME_STORAGE_KEY) {
+    if (storageKey === null)
+        return;
+    try {
+        storage()?.setItem(storageKey, mode);
+    }
+    catch {
+        // Storage full or blocked: the page is still switched.
+    }
+}
+/**
+ * A script for `<head>` that applies the stored mode before the first paint,
+ * so a returning visitor does not see the other theme flash by. Returns the
+ * source as a string; it has no dependencies and can be inlined as it is.
+ *
+ * It writes to whichever mechanism the page uses, as ThemeToggle does:
+ * `data-theme` when `<html>` already has the attribute or the stored mode is
+ * `"auto"`, and the `dark` class otherwise. With nothing stored it does
+ * nothing, and the markup's own `data-theme` (or its absence) stands.
+ *
+ * The key is written into the script as a JSON string, so any key is safe.
+ */
+export function themeInitScript(storageKey = DEFAULT_THEME_STORAGE_KEY) {
+    const key = JSON.stringify(String(storageKey)).replace(/</g, "\\u003c");
+    return ("(function(){try{" +
+        `var m=localStorage.getItem(${key});` +
+        'if(m!=="auto"&&m!=="light"&&m!=="dark")return;' +
+        "var r=document.documentElement;" +
+        'if(r.hasAttribute("data-theme")||m==="auto"){r.setAttribute("data-theme",m);r.classList.remove("dark")}' +
+        'else{r.classList.toggle("dark",m==="dark")}' +
+        "}catch(e){}})();");
+}

package/dist/util/toaster.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Every word a `Toaster` says by itself. An app in another language passes
+ * its own through `strings`; what it leaves out stays as it is here.
+ */
+export interface ToasterStrings {
+    /** Accessible name of the region the toasts are in. */
+    regionLabel: string;
+    /**
+     * What a toast says when it was pushed with neither a `title` nor a
+     * `message`, by type. A toast with a message shows the message.
+     */
+    successTitle: string;
+    errorTitle: string;
+    warningTitle: string;
+    infoTitle: string;
+    /** The time a toast has left, while its timer runs. */
+    closesIn: (seconds: number) => string;
+    /** The same, while a pointer, a finger or focus holds the timer. */
+    pausedClosesIn: (seconds: number) => string;
+    /** The button that stops the timer; shown with `showCountdown`. */
+    stop: string;
+    /** The button under a toast's opened details, which closes them again. */
+    okay: string;
+    /** Accessible name of the button that opens a toast's details. */
+    expand: string;
+    /** The same button, once they are open. */
+    collapse: string;
+    /** Accessible name of the button that dismisses a toast. */
+    dismiss: string;
+    /**
+     * Read after a toast's text when it has an action, so a screen reader
+     * user hears that there is one. `label` is the action's own.
+     */
+    actionAvailable: (label: string) => string;
+}
+export declare const DEFAULT_TOASTER_STRINGS: ToasterStrings;
+/**
+ * The three lengths a toast can be given by name, in milliseconds.
+ *
+ * `short` (3 s) is for a few words that need no reading time ("Saved").
+ * Anything a person has to read is `medium` (7 s) or `long` (14 s). What
+ * they have to act on, and an error, should stay: `"persistent"`.
+ */
+export declare const TOAST_DURATIONS: {
+    readonly short: 3000;
+    readonly medium: 7000;
+    readonly long: 14000;
+};
+/**
+ * How long a toast stays: one of the named lengths, `"persistent"` (until it
+ * is dismissed), or a number of milliseconds, where `0` is persistent too.
+ */
+export type ToastDuration = keyof typeof TOAST_DURATIONS | "persistent" | number;
+/**
+ * A toast with more visible text than this (title and message together) gets
+ * `long` when the app gave it no duration.
+ */
+export declare const TOAST_LONG_TEXT_LENGTH = 120;
+/**
+ * And one with more than this stays until it is dismissed: `long` was
+ * measured as too short to read it in, and nothing longer has a name.
+ */
+export declare const TOAST_PERSISTENT_TEXT_LENGTH = 240;
+/**
+ * How long a toast stays, in milliseconds; `0` is until it is dismissed.
+ *
+ * What the app said for the toast wins, whatever the toast is. When it said
+ * nothing: an error stays, and so does a toast with an action, since the user
+ * has to be able to reach the button. So does a text longer than
+ * `TOAST_PERSISTENT_TEXT_LENGTH`, whatever the Toaster's default. Everything
+ * else gets the Toaster's `defaultDuration`, or `medium` without one; a text
+ * longer than `TOAST_LONG_TEXT_LENGTH` gets `long`, unless the default is
+ * longer still.
+ */
+export declare function resolveToastDuration(toast: {
+    duration?: ToastDuration;
+    type: string;
+    hasAction: boolean;
+    textLength: number;
+}, defaultDuration?: ToastDuration): number;
+/**
+ * The least a toast has left when a finger that held it lifts, in seconds.
+ * As long as `short`: holding a short toast starts it again, in effect.
+ */
+export declare const TOAST_SECONDS_AFTER_HOLD = 3;
+/** What `onpausechange` of a `Toaster` is called with. */
+export interface ToastPauseChange {
+    /** The id of the toast, as `pushToast` returned it. */
+    id: string;
+    /** True while a pointer is over the toast, a finger is on it, or focus is inside it. */
+    paused: boolean;
+}

package/dist/util/toaster.js

@@ -0,0 +1,75 @@
+export const DEFAULT_TOASTER_STRINGS = {
+    regionLabel: "Notifications",
+    successTitle: "Changes saved",
+    errorTitle: "Something went wrong",
+    warningTitle: "Please review",
+    infoTitle: "Notice",
+    closesIn: (seconds) => `This message will close in ${seconds} ${seconds === 1 ? "second" : "seconds"}.`,
+    pausedClosesIn: (seconds) => `Paused — closes in ${seconds} ${seconds === 1 ? "second" : "seconds"}.`,
+    stop: "Click to stop",
+    okay: "Okay",
+    expand: "Expand details",
+    collapse: "Collapse details",
+    dismiss: "Dismiss notification",
+    actionAvailable: (label) => `${label} available.`,
+};
+/**
+ * The three lengths a toast can be given by name, in milliseconds.
+ *
+ * `short` (3 s) is for a few words that need no reading time ("Saved").
+ * Anything a person has to read is `medium` (7 s) or `long` (14 s). What
+ * they have to act on, and an error, should stay: `"persistent"`.
+ */
+export const TOAST_DURATIONS = { short: 3000, medium: 7000, long: 14000 };
+/**
+ * A toast with more visible text than this (title and message together) gets
+ * `long` when the app gave it no duration.
+ */
+export const TOAST_LONG_TEXT_LENGTH = 120;
+/**
+ * And one with more than this stays until it is dismissed: `long` was
+ * measured as too short to read it in, and nothing longer has a name.
+ */
+export const TOAST_PERSISTENT_TEXT_LENGTH = 240;
+/** The milliseconds of a duration, `0` for one that stays; `undefined` for what is not a duration. */
+function toastDurationMs(duration) {
+    if (duration === "persistent")
+        return 0;
+    if (typeof duration === "string") {
+        return Object.prototype.hasOwnProperty.call(TOAST_DURATIONS, duration)
+            ? TOAST_DURATIONS[duration]
+            : undefined;
+    }
+    if (typeof duration !== "number" || Number.isNaN(duration))
+        return undefined;
+    return duration <= 0 ? 0 : duration;
+}
+/**
+ * How long a toast stays, in milliseconds; `0` is until it is dismissed.
+ *
+ * What the app said for the toast wins, whatever the toast is. When it said
+ * nothing: an error stays, and so does a toast with an action, since the user
+ * has to be able to reach the button. So does a text longer than
+ * `TOAST_PERSISTENT_TEXT_LENGTH`, whatever the Toaster's default. Everything
+ * else gets the Toaster's `defaultDuration`, or `medium` without one; a text
+ * longer than `TOAST_LONG_TEXT_LENGTH` gets `long`, unless the default is
+ * longer still.
+ */
+export function resolveToastDuration(toast, defaultDuration) {
+    const said = toastDurationMs(toast.duration);
+    if (said !== undefined)
+        return said;
+    if (toast.type === "error" || toast.hasAction)
+        return 0;
+    if (toast.textLength > TOAST_PERSISTENT_TEXT_LENGTH)
+        return 0;
+    const base = toastDurationMs(defaultDuration) ?? TOAST_DURATIONS.medium;
+    if (base === 0 || toast.textLength <= TOAST_LONG_TEXT_LENGTH)
+        return base;
+    return Math.max(base, TOAST_DURATIONS.long);
+}
+/**
+ * The least a toast has left when a finger that held it lifts, in seconds.
+ * As long as `short`: holding a short toast starts it again, in effect.
+ */
+export const TOAST_SECONDS_AFTER_HOLD = 3;

package/dist/util/tooltip.d.ts

@@ -0,0 +1,9 @@
+/**
+ * One tooltip at a time. A tooltip that opens closes the one that was open: a
+ * mouse resting on one trigger while Tab moves focus to another would
+ * otherwise show both, one of them stale.
+ */
+/** Called by a tooltip as it opens, with what closes it. Closes any other. */
+export declare function claimOpenTooltip(close: () => void): void;
+/** Called by a tooltip as it closes or goes. */
+export declare function releaseOpenTooltip(close: () => void): void;

package/dist/util/tooltip.js

@@ -0,0 +1,18 @@
+/**
+ * One tooltip at a time. A tooltip that opens closes the one that was open: a
+ * mouse resting on one trigger while Tab moves focus to another would
+ * otherwise show both, one of them stale.
+ */
+/** The tooltip that is open, as the function that closes it. */
+let closeOpen = null;
+/** Called by a tooltip as it opens, with what closes it. Closes any other. */
+export function claimOpenTooltip(close) {
+    if (closeOpen && closeOpen !== close)
+        closeOpen();
+    closeOpen = close;
+}
+/** Called by a tooltip as it closes or goes. */
+export function releaseOpenTooltip(close) {
+    if (closeOpen === close)
+        closeOpen = null;
+}

package/dist/util/top-navbar.d.ts

@@ -0,0 +1,10 @@
+/** The words `TopNavbar` says by itself. Pass any of them as `strings`. */
+export interface TopNavbarStrings {
+    /** Accessible name of the phone menu's button while the menu is closed. */
+    openMenu: string;
+    /** The same button, while the menu is open. */
+    closeMenu: string;
+    /** Read after the label of a link that opens in a new tab. */
+    opensInNewTab: string;
+}
+export declare const DEFAULT_TOP_NAVBAR_STRINGS: TopNavbarStrings;

package/dist/util/top-navbar.js

@@ -0,0 +1,5 @@
+export const DEFAULT_TOP_NAVBAR_STRINGS = {
+    openMenu: "Open menu",
+    closeMenu: "Close menu",
+    opensInNewTab: "(opens in a new tab)",
+};

package/dist/util/touch-target.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Touch targets: 44 by 44px on a coarse pointer, nothing changed on a fine one.
+ *
+ * There are two ways to get there, and which one a control takes depends on
+ * what stands beside it.
+ *
+ * 1. The control itself grows: `pointer-coarse:min-h-11` (and `min-w-11` for a
+ *    square one), written where the size is. Button, IconButton, Input and
+ *    Select do this at `sm` and `md`, so a row of them still lines up; so does
+ *    any control that has a neighbour close by (the handle and the move
+ *    buttons of a SortableList row). `scripts/check-control-geometry.js` holds
+ *    the shared controls to it.
+ *
+ * 2. The control keeps its size and an invisible layer around it takes the
+ *    touch: `TOUCH_HIT_AREA` below. Only for a control that stands alone, with
+ *    nothing pressable within about 10px: a close button in the corner of an
+ *    Alert or in the header of a Modal, the switch of a Toggle. The layer
+ *    reaches past the visible box, so beside another control it would cover
+ *    that control's edge and a tap there would fire the wrong one. An `xs`
+ *    IconButton had such a layer and lost it for that reason. A Toggle is
+ *    stacked in settings lists, so its row is 44px tall on a coarse pointer:
+ *    the layer of one switch then never reaches the switch above or below.
+ */
+/**
+ * An invisible hit area of at least 44 by 44px, centred on the element, on a
+ * coarse pointer only. The element must be positioned (`relative`, `absolute`
+ * or `fixed`; `pointer-coarse:relative` where it was not positioned before, so
+ * a fine pointer sees no change) and must not clip its overflow.
+ */
+export declare const TOUCH_HIT_AREA = "pointer-coarse:before:absolute pointer-coarse:before:top-1/2 pointer-coarse:before:left-1/2 pointer-coarse:before:size-full pointer-coarse:before:min-h-11 pointer-coarse:before:min-w-11 pointer-coarse:before:-translate-x-1/2 pointer-coarse:before:-translate-y-1/2 pointer-coarse:before:content-['']";

package/dist/util/touch-target.js

@@ -0,0 +1,30 @@
+/**
+ * Touch targets: 44 by 44px on a coarse pointer, nothing changed on a fine one.
+ *
+ * There are two ways to get there, and which one a control takes depends on
+ * what stands beside it.
+ *
+ * 1. The control itself grows: `pointer-coarse:min-h-11` (and `min-w-11` for a
+ *    square one), written where the size is. Button, IconButton, Input and
+ *    Select do this at `sm` and `md`, so a row of them still lines up; so does
+ *    any control that has a neighbour close by (the handle and the move
+ *    buttons of a SortableList row). `scripts/check-control-geometry.js` holds
+ *    the shared controls to it.
+ *
+ * 2. The control keeps its size and an invisible layer around it takes the
+ *    touch: `TOUCH_HIT_AREA` below. Only for a control that stands alone, with
+ *    nothing pressable within about 10px: a close button in the corner of an
+ *    Alert or in the header of a Modal, the switch of a Toggle. The layer
+ *    reaches past the visible box, so beside another control it would cover
+ *    that control's edge and a tap there would fire the wrong one. An `xs`
+ *    IconButton had such a layer and lost it for that reason. A Toggle is
+ *    stacked in settings lists, so its row is 44px tall on a coarse pointer:
+ *    the layer of one switch then never reaches the switch above or below.
+ */
+/**
+ * An invisible hit area of at least 44 by 44px, centred on the element, on a
+ * coarse pointer only. The element must be positioned (`relative`, `absolute`
+ * or `fixed`; `pointer-coarse:relative` where it was not positioned before, so
+ * a fine pointer sees no change) and must not clip its overflow.
+ */
+export const TOUCH_HIT_AREA = "pointer-coarse:before:absolute pointer-coarse:before:top-1/2 pointer-coarse:before:left-1/2 pointer-coarse:before:size-full pointer-coarse:before:min-h-11 pointer-coarse:before:min-w-11 pointer-coarse:before:-translate-x-1/2 pointer-coarse:before:-translate-y-1/2 pointer-coarse:before:content-['']";