@wtfalch/design 0.3.1 → 0.4.0

package/dist/components/Command.d.ts

@@ -0,0 +1,57 @@
+import type { IconName } from './iconNames.js';
+/**
+ * Type what you want to do.
+ *
+ * The keyboard's front door: one field over the application, a list that
+ * narrows as you type, Enter to run the highlighted thing. It exists because
+ * the alternative to a palette is a menu bar, and a menu bar makes every
+ * action cost a guess about which of six menus somebody filed it under.
+ *
+ * **It is a search field over a listbox, not a text input with a div under
+ * it.** That distinction is the whole accessibility story here. React Aria's
+ * `Autocomplete` keeps focus in the field while the arrows move the *selection*
+ * in the list, sets `aria-activedescendant` so a screen reader reads the
+ * highlighted row without focus leaving the input, and wires `aria-controls`
+ * between the two. Hand-rolled palettes move real focus into the list, which
+ * means typing another letter goes nowhere and the whole thing dead-ends for
+ * anybody not using a mouse.
+ *
+ * **Filtering is substring, and deliberately not fuzzy.** A fuzzy match on a
+ * short list is a list that reorders itself under your hands: you type one
+ * more letter, the thing you were about to press moves, and you run the wrong
+ * command. `contains` with the locale's collation -- so `resume` finds
+ * `Résumé` -- keeps the order stable and the surprises out.
+ *
+ * **The empty state says the query.** "No commands match 'archve'" is a typo
+ * somebody can see; "No results" is a dead end that looks like a broken build.
+ */
+export interface Command {
+    id: string;
+    label: string;
+    /** What running it does, when the name does not say. */
+    description?: string;
+    icon?: IconName;
+    /** Shown, never bound. The app owns the binding. */
+    shortcut?: string;
+    /** Words that should find it but are not in its name -- "trash" for Delete,
+     *  "folder" for Mailbox. Searched, never displayed. */
+    keywords?: string[];
+    disabled?: boolean;
+    onRun?: () => void;
+}
+export interface Group {
+    title: string;
+    commands: Command[];
+}
+export interface Props {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Grouped, because a flat list of forty commands is a list nobody reads
+     *  the bottom of. */
+    groups: Group[];
+    /** The field's placeholder and its accessible name. */
+    placeholder?: string;
+    label?: string;
+    className?: string;
+}
+export default function Command({ open, onOpenChange, groups, placeholder, label, className, }: Props): import("react").JSX.Element;

package/dist/components/Command.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Modal as AriaModal, Autocomplete, Dialog, Header, Input, Keyboard, ListBox, ListBoxItem, ListBoxSection, ModalOverlay, SearchField, Text, useFilter, } from 'react-aria-components';
+import Icon from './Icon.js';
+export default function Command({ open, onOpenChange, groups, placeholder = 'Search commands…', label = 'Command palette', className, }) {
+    const [query, setQuery] = useState('');
+    /* The locale's collation, not `toLowerCase().includes()`: that answers no
+       for `Résumé` when you type `resume`, and for every language whose casing
+       is not English's. */
+    const { contains } = useFilter({ sensitivity: 'base' });
+    const matches = (command) => query === '' ||
+        contains(command.label, query) ||
+        (command.description !== undefined && contains(command.description, query)) ||
+        (command.keywords ?? []).some((word) => contains(word, query));
+    const shown = groups
+        .map((group) => ({ ...group, commands: group.commands.filter(matches) }))
+        .filter((group) => group.commands.length > 0);
+    const empty = shown.length === 0;
+    return (_jsx(ModalOverlay, { className: "cmd-scrim", isOpen: open, onOpenChange: (next) => {
+            onOpenChange(next);
+            /* Cleared on close, not on open: a palette that reopens with the last
+               query still in it shows a filtered list somebody has to notice and
+               delete before they can search for anything else. */
+            if (!next)
+                setQuery('');
+        }, isDismissable: true, children: _jsx(AriaModal, { className: `cmd${className ? ` ${className}` : ''}`, children: _jsx(Dialog, { className: "cmd-body", "aria-label": label, children: ({ close }) => (_jsxs(Autocomplete, { inputValue: query, onInputChange: setQuery, filter: () => true, children: [_jsxs(SearchField, { className: "cmd-field", "aria-label": label, autoFocus: true, children: [_jsx(Icon, { name: "chat", className: "cmd-mark" }), _jsx(Input, { className: "cmd-input", placeholder: placeholder })] }), empty ? (
+                        /* The query, quoted. A palette that says "No results" to a
+                           typo looks like a palette that is broken. */
+                        _jsxs("p", { className: "cmd-empty", children: ["Nothing matches ", _jsx("strong", { children: query }), "."] })) : (_jsx(ListBox, { className: "cmd-list", "aria-label": label, selectionMode: "none", children: shown.map((group) => (_jsxs(ListBoxSection, { className: "cmd-group", children: [_jsx(Header, { className: "cmd-group-title", children: group.title }), group.commands.map((command) => (_jsxs(ListBoxItem, { id: command.id, className: "cmd-item", textValue: command.label, isDisabled: command.disabled, onAction: () => {
+                                            command.onRun?.();
+                                            /* Closing is this component's job, not every
+                                               caller's. Forty `onRun`s that each remember to
+                                               close is thirty-nine chances to forget. */
+                                            close();
+                                        }, children: [command.icon && _jsx(Icon, { name: command.icon, className: "cmd-icon" }), _jsxs("span", { className: "cmd-text", children: [_jsx(Text, { slot: "label", className: "cmd-label", children: command.label }), command.description && (_jsx(Text, { slot: "description", className: "cmd-desc", children: command.description }))] }), command.shortcut && (_jsx(Keyboard, { className: "cmd-key", children: command.shortcut }))] }, command.id)))] }, group.title))) }))] })) }) }) }));
+}

package/dist/components/Identity.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A person, said in one line.
+ *
+ * A name, an address and a coloured disc with their initials. It is a mail
+ * client's most repeated object -- every row of a thread list, every header of
+ * a message, every chip in a composer's To field -- and until there is one of
+ * these it is written by hand at each of those, slightly differently, and the
+ * initials are wrong in a different way at every site.
+ *
+ * **The colour is derived from the address, not chosen.** The same person is
+ * the same colour in the list, in the header and in the composer, across
+ * reloads and across machines, with nothing stored. That consistency is the
+ * only thing the colour is for: it is a second, weaker cue that two rows are
+ * from the same sender, which is worth something when scanning and worth
+ * nothing if it changes.
+ *
+ * **The disc is `aria-hidden` and the initials are never read out.** "A L" is
+ * not a name, and a screen reader that announces it before the name has made
+ * every row of the list longer to listen to for no information at all.
+ *
+ * **Initials come from the name when there is one, and from the address when
+ * there is not.** A contact with no display name is common -- most machine
+ * senders have none -- and falling through to the first letter of the local
+ * part beats an empty disc or a `?`.
+ */
+export interface Props {
+    /** The display name, when the message carried one. */
+    name?: string | null;
+    address: string;
+    /** How much to show. `chip` is the composer's pill, `line` is a list row,
+     *  `full` puts the address under the name for a message header. */
+    kind?: 'chip' | 'line' | 'full';
+    size?: 'sm' | 'md';
+    /** Something after the name -- a time, a count, a `Pill`. */
+    aside?: React.ReactNode;
+    /** For the composer: shows a remove button and calls this. */
+    onRemove?: () => void;
+    className?: string;
+}
+export default function Identity({ name, address, kind, size, aside, onRemove, className, }: Props): import("react").JSX.Element;

package/dist/components/Identity.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A person, said in one line.
+ *
+ * A name, an address and a coloured disc with their initials. It is a mail
+ * client's most repeated object -- every row of a thread list, every header of
+ * a message, every chip in a composer's To field -- and until there is one of
+ * these it is written by hand at each of those, slightly differently, and the
+ * initials are wrong in a different way at every site.
+ *
+ * **The colour is derived from the address, not chosen.** The same person is
+ * the same colour in the list, in the header and in the composer, across
+ * reloads and across machines, with nothing stored. That consistency is the
+ * only thing the colour is for: it is a second, weaker cue that two rows are
+ * from the same sender, which is worth something when scanning and worth
+ * nothing if it changes.
+ *
+ * **The disc is `aria-hidden` and the initials are never read out.** "A L" is
+ * not a name, and a screen reader that announces it before the name has made
+ * every row of the list longer to listen to for no information at all.
+ *
+ * **Initials come from the name when there is one, and from the address when
+ * there is not.** A contact with no display name is common -- most machine
+ * senders have none -- and falling through to the first letter of the local
+ * part beats an empty disc or a `?`.
+ */
+import { hueOf, initialsOf } from './initials.js';
+export default function Identity({ name, address, kind = 'line', size = 'md', aside, onRemove, className, }) {
+    const initials = initialsOf(name, address);
+    const shown = name?.trim() || address;
+    return (_jsxs("span", { className: `ident kind-${kind} size-${size}${className ? ` ${className}` : ''}`, 
+        /* The hue is a variable and the stylesheet decides what to do with it:
+           a `background` written here would be a colour the theme cannot reach,
+           and the discs would stay saturated on Paper. */
+        style: { '--ident-hue': hueOf(address) }, children: [_jsx("span", { className: "ident-disc", "aria-hidden": "true", children: initials }), _jsxs("span", { className: "ident-text", children: [_jsx("span", { className: "ident-name", children: shown }), kind === 'full' && shown !== address && _jsx("span", { className: "ident-address", children: address })] }), aside && _jsx("span", { className: "ident-aside", children: aside }), onRemove && (_jsx("button", { type: "button", className: "ident-remove", onClick: onRemove, "aria-label": `Remove ${shown}`, children: _jsx("svg", { viewBox: "0 0 24 24", width: "12", height: "12", "aria-hidden": "true", children: _jsx("path", { fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", d: "M6 6l12 12M18 6L6 18" }) }) }))] }));
+}

package/dist/components/Markdown.d.ts

@@ -4,6 +4,14 @@ import DOMPurify from 'dompurify';
  *
  * Sanitised without exception: this is text produced by a model, which may be
  * echoing content it read from a file, so it is never trusted HTML.
+ *
+ * **On the server, the text itself.** DOMPurify sanitises through a DOM, and a
+ * server rendering React has none: `sanitize` is not even a function there,
+ * and the first app to server-render a comment found out. Rather than a second
+ * sanitiser for the server, which would be two behaviours for one string, the
+ * server (and the first client paint, so hydration agrees) renders the text
+ * escaped by React, and the sanitised HTML takes its place once mounted. What
+ * reaches a browser is never HTML that DOMPurify has not seen.
  */
 export default function Markdown({ text, sanitize, className, }: {
     text: string;

package/dist/components/Markdown.js

@@ -1,18 +1,28 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import DOMPurify from 'dompurify';
 import { marked } from 'marked';
-import { useMemo } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 marked.setOptions({ gfm: true, breaks: true });
 /**
  * Render model output as markdown.
  *
  * Sanitised without exception: this is text produced by a model, which may be
  * echoing content it read from a file, so it is never trusted HTML.
+ *
+ * **On the server, the text itself.** DOMPurify sanitises through a DOM, and a
+ * server rendering React has none: `sanitize` is not even a function there,
+ * and the first app to server-render a comment found out. Rather than a second
+ * sanitiser for the server, which would be two behaviours for one string, the
+ * server (and the first client paint, so hydration agrees) renders the text
+ * escaped by React, and the sanitised HTML takes its place once mounted. What
+ * reaches a browser is never HTML that DOMPurify has not seen.
  */
 export default function Markdown({ text, sanitize, className, }) {
+    const [mounted, setMounted] = useState(false);
+    useEffect(() => setMounted(true), []);
     const html = useMemo(() => {
-        if (!text)
-            return '';
+        if (!text || !mounted)
+            return null;
         const raw = marked.parse(text, { async: false });
         return DOMPurify.sanitize(raw, {
             // No iframes, no forms, no event handlers -- prose, code and tables only.
@@ -20,10 +30,15 @@ export default function Markdown({ text, sanitize, className, }) {
             FORBID_ATTR: ['style', 'onerror', 'onload', 'onclick'],
             ...sanitize,
         });
-    }, [text, sanitize]);
+    }, [text, mounted, sanitize]);
     if (!text)
         return null;
-    return (_jsx("div", { className: `md${className ? ` ${className}` : ''}`, 
+    const classes = `md${className ? ` ${className}` : ''}`;
+    if (html === null) {
+        // The server, and the client until its first effect: the words, escaped.
+        return (_jsx("div", { className: classes, "data-md": "plain", children: _jsx("p", { children: text }) }));
+    }
+    return (_jsx("div", { className: classes, 
         // biome-ignore lint/security/noDangerouslySetInnerHtml: the string is DOMPurify output, with the config above.
         dangerouslySetInnerHTML: { __html: html } }));
 }

package/dist/components/Menu.d.ts

@@ -0,0 +1,62 @@
+import { type Placement } from 'react-aria-components';
+import type { IconName } from './iconNames.js';
+/**
+ * A list of things you can do to something.
+ *
+ * Not `Select`. That is a *value* -- one of a set, one of them currently true,
+ * and the control shows which. A menu is a set of *verbs*, none of them a
+ * state, and nothing is selected when it closes. Building one out of the other
+ * gets you a listbox that announces "selected" after somebody archives a
+ * message, which is a small lie told by a screen reader at the exact moment
+ * accuracy matters.
+ *
+ * **Destructive items are marked and last.** `danger` tints the row, and the
+ * caller puts it below a separator. Delete beside Reply, in the same weight,
+ * one row apart, is a design that is going to lose somebody's mail. Same
+ * vocabulary as `DangerZone`, one surface smaller.
+ *
+ * **Shortcuts are shown, not hidden.** An item that also has a key binding
+ * says so on its right; that is the only place most people will ever learn the
+ * binding exists, and a menu is where they are already looking.
+ *
+ * The keyboard, typeahead, submenu timing, outside press and focus restore are
+ * React Aria's. The submenu delay in particular is worth not rewriting: a
+ * submenu that closes the instant the pointer leaves its parent row is
+ * unusable with a mouse, because the diagonal path to it passes over the row
+ * below.
+ */
+export interface Item {
+    id: string;
+    label: React.ReactNode;
+    /** A second line, for an action whose consequence is not obvious from its
+     *  name. Most items should not have one. */
+    description?: string;
+    icon?: IconName;
+    /** The key binding, written the way the platform writes it. Shown, never
+     *  bound -- this draws the reminder, the app owns the shortcut. */
+    shortcut?: string;
+    disabled?: boolean;
+    /** Tints the row and gives it the destructive colour. For the one item that
+     *  cannot be undone. */
+    danger?: boolean;
+    /** A rule above this item. Groups a menu without giving each group a name. */
+    separated?: boolean;
+    onAction?: () => void;
+    /** Items under this one, opened by hovering or by the right arrow. */
+    items?: Item[];
+}
+export interface Section {
+    /** The group's name. A section with no title is a `separated` item's job. */
+    title: string;
+    items: Item[];
+}
+export interface Props {
+    /** What opens it. */
+    trigger: React.ReactNode;
+    items: (Item | Section)[];
+    placement?: Placement;
+    /** Names the menu for a screen reader. */
+    label: string;
+    className?: string;
+}
+export default function Menu({ trigger, items, placement, label, className, }: Props): import("react").JSX.Element;

package/dist/components/Menu.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Menu as AriaMenu, Popover as AriaPopover, Header, Keyboard, MenuItem, MenuSection, MenuTrigger, Separator, SubmenuTrigger, Text, } from 'react-aria-components';
+import Icon from './Icon.js';
+function isSection(entry) {
+    return 'title' in entry && Array.isArray(entry.items);
+}
+function renderItem(item) {
+    const row = (_jsxs(MenuItem, { id: item.id, className: `menu-item${item.danger ? ' danger' : ''}`, isDisabled: item.disabled, onAction: item.onAction, 
+        /* Typeahead needs a string, and `label` may be a node. Without this,
+           typing the first letter of an item whose label is markup matches
+           nothing and the menu looks broken. */
+        textValue: typeof item.label === 'string' ? item.label : item.id, children: [item.icon && _jsx(Icon, { name: item.icon, className: "menu-icon" }), _jsxs("span", { className: "menu-text", children: [_jsx(Text, { slot: "label", className: "menu-label", children: item.label }), item.description && (_jsx(Text, { slot: "description", className: "menu-desc", children: item.description }))] }), item.shortcut && _jsx(Keyboard, { className: "menu-key", children: item.shortcut }), item.items && (_jsx("svg", { className: "menu-more", viewBox: "0 0 24 24", width: "12", height: "12", "aria-hidden": "true", children: _jsx("path", { fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", d: "m9 6 6 6-6 6" }) }))] }, item.id));
+    const body = item.items ? (_jsxs(SubmenuTrigger, { children: [row, _jsx(AriaPopover, { className: "menu-sheet", children: _jsx(AriaMenu, { className: "menu-list", children: item.items.map(renderItem) }) })] }, item.id)) : (row);
+    if (!item.separated)
+        return body;
+    return [_jsx(Separator, { className: "menu-rule" }, `${item.id}-rule`), body];
+}
+export default function Menu({ trigger, items, placement = 'bottom start', label, className, }) {
+    return (_jsxs(MenuTrigger, { children: [trigger, _jsx(AriaPopover, { className: `menu-sheet${className ? ` ${className}` : ''}`, placement: placement, offset: 6, children: _jsx(AriaMenu, { className: "menu-list", "aria-label": label, children: items.map((entry) => isSection(entry) ? (_jsxs(MenuSection, { className: "menu-section", children: [_jsx(Header, { className: "menu-section-title", children: entry.title }), entry.items.map(renderItem)] }, entry.title)) : (renderItem(entry))) }) })] }));
+}

package/dist/components/Modal.d.ts

@@ -22,8 +22,16 @@
  * this -- same trap, same restore, stricter about the scrim, because for "may
  * this applet write to your files" a stray click on the background is a way of
  * answering by accident.
+ *
+ * **A sheet is this with `edge` set, not a second component.** A drawer from
+ * the side of the window differs from a window in the middle of it by where it
+ * is anchored and which way it slides -- and in nothing else. Same focus trap,
+ * same restore, same scrim, same header, body and footer. Writing a `Sheet`
+ * that duplicates all of that to change two CSS properties is how a design
+ * system ends up with two windows that drift: one of them gets the fix and
+ * nobody notices which.
  */
-export default function Modal({ title, description, subtitle, head, children, footer, footerClass, onClose, closeDisabled, width, bodyClass, className, dismissOnScrim, closeButton, labelledBy, }: {
+export default function Modal({ title, description, subtitle, head, children, footer, footerClass, onClose, closeDisabled, width, edge, bodyClass, className, dismissOnScrim, closeButton, labelledBy, }: {
     /** The window's name. Rendered as the heading and announced on open. */
     title?: React.ReactNode;
     /** A line under the title, saying what the window is for. The same slot
@@ -45,6 +53,17 @@ export default function Modal({ title, description, subtitle, head, children, fo
     /** While something is saving, closing would abandon it mid-flight. */
     closeDisabled?: boolean;
     width?: string;
+    /**
+     * Anchor it to an edge of the window and slide it in from there, rather
+     * than centring it. This is the sheet.
+     *
+     * `right` and `left` run the full height at `width`; `bottom` runs the full
+     * width and is as tall as its content, which is the shape a phone expects.
+     * Use one where the window is a *side panel* on the thing behind it --
+     * message details, a filter pane -- and leave it off where the window
+     * replaces what is behind it.
+     */
+    edge?: 'left' | 'right' | 'bottom';
     /** For a body that is not a single column -- Settings' rail and pane. */
     bodyClass?: string;
     className?: string;

package/dist/components/Modal.js

@@ -23,6 +23,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * this -- same trap, same restore, stricter about the scrim, because for "may
  * this applet write to your files" a stray click on the background is a way of
  * answering by accident.
+ *
+ * **A sheet is this with `edge` set, not a second component.** A drawer from
+ * the side of the window differs from a window in the middle of it by where it
+ * is anchored and which way it slides -- and in nothing else. Same focus trap,
+ * same restore, same scrim, same header, body and footer. Writing a `Sheet`
+ * that duplicates all of that to change two CSS properties is how a design
+ * system ends up with two windows that drift: one of them gets the fix and
+ * nobody notices which.
  */
 import { useEffect, useId, useRef } from 'react';
 import { Modal as AriaModal, Dialog, Heading, ModalOverlay } from 'react-aria-components';
@@ -30,7 +38,7 @@ import Button from './Button.js';
 import Icon from './Icon.js';
 /* The trap is the same obligation wherever it applies, and the studio needs it
    without being shaped like this, so it lives in a hook rather than here. */
-export default function Modal({ title, description, subtitle, head, children, footer, footerClass, onClose, closeDisabled = false, width, bodyClass, className, dismissOnScrim = true, closeButton = true, labelledBy, }) {
+export default function Modal({ title, description, subtitle, head, children, footer, footerClass, onClose, closeDisabled = false, width, edge, bodyClass, className, dismissOnScrim = true, closeButton = true, labelledBy, }) {
     const headingId = useId();
     const canClose = Boolean(onClose) && !closeDisabled;
     /* React Aria owns the three things every hand-built modal here got wrong.
@@ -57,10 +65,10 @@ export default function Modal({ title, description, subtitle, head, children, fo
     useEffect(() => {
         dialogRef.current?.setAttribute('aria-modal', 'true');
     });
-    return (_jsx(ModalOverlay, { className: "backdrop", isOpen: true, isDismissable: canClose && dismissOnScrim, isKeyboardDismissDisabled: !canClose, onOpenChange: (open) => {
+    return (_jsx(ModalOverlay, { className: `backdrop${edge ? ` sheeted from-${edge}` : ''}`, isOpen: true, isDismissable: canClose && dismissOnScrim, isKeyboardDismissDisabled: !canClose, onOpenChange: (open) => {
             if (!open && canClose)
                 onClose?.();
-        }, children: _jsx(AriaModal, { className: `modal${className ? ` ${className}` : ''}`, style: width ? { width } : undefined, children: _jsxs(Dialog, { ref: dialogRef, className: "modal-dialog", "aria-labelledby": labelledBy ?? (title ? headingId : undefined), children: [(title || head || (onClose && closeButton)) && (_jsxs("header", { className: "modal-head", children: [title && (
+        }, children: _jsx(AriaModal, { className: `modal${edge ? ` sheet from-${edge}` : ''}${className ? ` ${className}` : ''}`, style: width ? { width } : undefined, children: _jsxs(Dialog, { ref: dialogRef, className: "modal-dialog", "aria-labelledby": labelledBy ?? (title ? headingId : undefined), children: [(title || head || (onClose && closeButton)) && (_jsxs("header", { className: "modal-head", children: [title && (
                             /* `Heading` is what React Aria labels the dialog by, and it
                                renders an `<h2>` -- which the browser gives its own margins
                                and its own size (17px above and below, 21px type). The old

package/dist/components/Pagination.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Moving through a list that does not fit.
+ *
+ * **It counts in items, not in pages**, because that is what the server
+ * answers and what the reader asks. A JMAP query returns a position, a limit
+ * and a total; a mailbox is "51–100 of 1,284", not "page 2 of 26". Page
+ * numbers are this component's arithmetic, done once here rather than at every
+ * call site -- which is where the off-by-one lives, and where it becomes an
+ * empty last page.
+ *
+ * **The count is the point, and it is said out loud.** "51–100 of 1,284" tells
+ * you how far in you are and how much is left; two arrows tell you neither. A
+ * pager with no count is a pager you navigate by feel.
+ *
+ * **A total is optional, because a server may refuse to count.** JMAP's
+ * `calculateTotal` is a request, not a promise, and a large mailbox is exactly
+ * where it gets declined. Without one this shows the range and keeps Next
+ * enabled while a full page came back, which is the only honest thing it can
+ * do: a page shorter than the limit is the end.
+ *
+ * **The ellipsis is a field, not punctuation.** It stands for the pages you
+ * cannot see, so it is where you say which one you want: type a number, press
+ * Enter, and you are there. Drawn as a ghost -- no border, no background, the
+ * `…` as its placeholder -- so at rest the row looks exactly like a row of
+ * page buttons with an elision in it, and it becomes a control when you touch
+ * it. Without this, reaching page 17 of 26 is eleven presses of Next, and the
+ * middle of a row of live buttons is a dead spot.
+ *
+ * **`nav` with a name**, so a screen reader can jump to it and so two pagers
+ * on a page are distinguishable. The current page's button is
+ * `aria-current="page"`, which is what tells a reader where they are without
+ * relying on the colour that says it visually.
+ */
+export interface Props {
+    /** Index of the first item shown, counting from zero -- the same number the
+     *  query was given, so caller and component never disagree about the origin. */
+    position: number;
+    /** How many are shown per page. */
+    limit: number;
+    /** How many there are in total, when the server was willing to say. */
+    total?: number;
+    /** How many actually came back. A short page is the end of the list, which
+     *  is how Next is decided when there is no total. */
+    count?: number;
+    onChange: (position: number) => void;
+    /** Names this pager. "Mailbox pages", not "Pagination". */
+    label: string;
+    /** What is being counted, for the summary: "of 1,284 messages". */
+    unit?: string;
+    className?: string;
+}
+export default function Pagination({ position, limit, total, count, onChange, label, unit, className, }: Props): import("react").JSX.Element;

package/dist/components/Pagination.js

@@ -0,0 +1,101 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Moving through a list that does not fit.
+ *
+ * **It counts in items, not in pages**, because that is what the server
+ * answers and what the reader asks. A JMAP query returns a position, a limit
+ * and a total; a mailbox is "51–100 of 1,284", not "page 2 of 26". Page
+ * numbers are this component's arithmetic, done once here rather than at every
+ * call site -- which is where the off-by-one lives, and where it becomes an
+ * empty last page.
+ *
+ * **The count is the point, and it is said out loud.** "51–100 of 1,284" tells
+ * you how far in you are and how much is left; two arrows tell you neither. A
+ * pager with no count is a pager you navigate by feel.
+ *
+ * **A total is optional, because a server may refuse to count.** JMAP's
+ * `calculateTotal` is a request, not a promise, and a large mailbox is exactly
+ * where it gets declined. Without one this shows the range and keeps Next
+ * enabled while a full page came back, which is the only honest thing it can
+ * do: a page shorter than the limit is the end.
+ *
+ * **The ellipsis is a field, not punctuation.** It stands for the pages you
+ * cannot see, so it is where you say which one you want: type a number, press
+ * Enter, and you are there. Drawn as a ghost -- no border, no background, the
+ * `…` as its placeholder -- so at rest the row looks exactly like a row of
+ * page buttons with an elision in it, and it becomes a control when you touch
+ * it. Without this, reaching page 17 of 26 is eleven presses of Next, and the
+ * middle of a row of live buttons is a dead spot.
+ *
+ * **`nav` with a name**, so a screen reader can jump to it and so two pagers
+ * on a page are distinguishable. The current page's button is
+ * `aria-current="page"`, which is what tells a reader where they are without
+ * relying on the colour that says it visually.
+ */
+import { useState } from 'react';
+import { pageWindow } from './pageWindow.js';
+/** Group digits so a five-figure count can be read at a glance. */
+const group = (n) => n.toLocaleString('en-GB');
+/**
+ * The gap: a field you type a page into.
+ *
+ * Its own state, because a window can hold two of these and they are
+ * independent -- one for the pages before the current run and one for the
+ * pages after it. Hoisting the draft into `Pagination` would mean tracking
+ * which of the two is being edited, for no gain.
+ *
+ * Empty when it is not being typed into, so the placeholder shows and it
+ * reads as an elision. Escape and blur abandon; only Enter commits, because a
+ * pager that navigates while you are still typing takes you to page 1 on the
+ * way to page 17.
+ */
+function JumpField({ pages, onGo }) {
+    const [draft, setDraft] = useState('');
+    const commit = () => {
+        const wanted = Number.parseInt(draft, 10);
+        setDraft('');
+        if (!Number.isFinite(wanted))
+            return;
+        // Clamped rather than refused: somebody typing 400 into a 26-page list
+        // wants the end, and an error message here would be a bigger interruption
+        // than the thing it is guarding.
+        onGo(Math.min(pages, Math.max(1, wanted)));
+    };
+    return (_jsx("input", { className: "pager-jump", type: "number", inputMode: "numeric", min: 1, max: pages, value: draft, placeholder: "\u2026", 
+        /* The width is set from how many digits the largest page has, so the
+           row does not change size when the field is typed into -- the same
+           reason `pageWindow` holds seven slots at the ends. */
+        style: { '--digits': String(pages).length }, "aria-label": `Go to page, 1 to ${pages}`, onChange: (event) => setDraft(event.target.value), onKeyDown: (event) => {
+            if (event.key === 'Enter') {
+                event.preventDefault();
+                commit();
+                event.currentTarget.blur();
+            }
+            else if (event.key === 'Escape') {
+                setDraft('');
+                event.currentTarget.blur();
+            }
+        }, onBlur: () => setDraft('') }));
+}
+function Chevron({ back }) {
+    return (_jsx("svg", { viewBox: "0 0 24 24", width: "14", height: "14", "aria-hidden": "true", children: _jsx("path", { fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", d: back ? 'm15 6-6 6 6 6' : 'm9 6 6 6-6 6' }) }));
+}
+export default function Pagination({ position, limit, total, count, onChange, label, unit = 'items', className, }) {
+    const page = Math.floor(position / limit) + 1;
+    const pages = total === undefined ? undefined : Math.max(1, Math.ceil(total / limit));
+    const shown = count ?? limit;
+    const first = shown === 0 ? 0 : position + 1;
+    const last = position + shown;
+    const canGoBack = position > 0;
+    /* With a total, the last page is known. Without one, a full page means there
+       is probably more and a short one means there is not -- which is wrong
+       exactly once, on a list whose length is a multiple of the limit, and costs
+       one empty page rather than a hidden remainder. */
+    const canGoOn = pages === undefined ? shown >= limit : page < pages;
+    return (_jsxs("nav", { className: `pager${className ? ` ${className}` : ''}`, "aria-label": label, children: [_jsx("p", { className: "pager-count", children: shown === 0 ? (`No ${unit}`) : (_jsxs(_Fragment, { children: [_jsxs("strong", { children: [group(first), "\u2013", group(last)] }), total === undefined ? ` ${unit}` : ` of ${group(total)} ${unit}`] })) }), _jsxs("div", { className: "pager-controls", children: [_jsx("button", { type: "button", className: "pager-step", onClick: () => onChange(Math.max(0, position - limit)), disabled: !canGoBack, "aria-label": "Previous page", children: _jsx(Chevron, { back: true }) }), pages !== undefined && (_jsx("ol", { className: "pager-pages", children: pageWindow(page, pages).map((slot, index, slots) => slot === 'gap' ? (
+                        /* Keyed by the page it follows rather than by its index: a
+                           window holds at most two gaps and they elide different runs,
+                           and an index key makes React reuse the wrong one -- which
+                           would carry a half-typed page number from one to the other. */
+                        _jsx("li", { children: _jsx(JumpField, { pages: pages, onGo: (wanted) => onChange((wanted - 1) * limit) }) }, `gap-after-${slots[index - 1]}`)) : (_jsx("li", { children: _jsx("button", { type: "button", className: `pager-page${slot === page ? ' on' : ''}`, "aria-current": slot === page ? 'page' : undefined, "aria-label": `Page ${slot}`, onClick: () => onChange((slot - 1) * limit), children: slot }) }, slot))) })), _jsx("button", { type: "button", className: "pager-step", onClick: () => onChange(position + limit), disabled: !canGoOn, "aria-label": "Next page", children: _jsx(Chevron, {}) })] })] }));
+}

package/dist/components/Popover.d.ts

@@ -0,0 +1,46 @@
+import { type Placement } from 'react-aria-components';
+/**
+ * A small surface anchored to the thing that opened it.
+ *
+ * The middle term between `Tooltip` and `Modal`, and the distinction is what
+ * it contains rather than how big it is. A tooltip *says* something and you
+ * cannot touch it. A modal takes the application away until it is answered. A
+ * popover holds controls -- a filter, a colour, a signature picker -- and the
+ * page behind it stays live, because the whole point is to adjust something
+ * and watch it change.
+ *
+ * **It is a dialog, not a div.** Focus moves into it on open, comes back to the
+ * trigger on close, Escape closes it and an outside press closes it. Every one
+ * of those is what people expect from something that appeared over the page,
+ * and every one is missing from the `position: absolute` panel that gets
+ * written instead. The panel is worse in a way that is hard to see and easy to
+ * hit: tab out of it and you are behind it, operating the page it is covering.
+ *
+ * **It flips.** `placement` is a preference, not an instruction. React Aria
+ * measures the space and moves the surface to the other side when the edge is
+ * near, which is the failure the hand-rolled version always ships with -- it
+ * works everywhere except at the bottom of the window, where the content
+ * appears off screen.
+ *
+ * Uncontrolled by default: hand it a trigger and children, and it opens and
+ * closes itself. `open`/`onOpenChange` are for the case where something else
+ * has to close it -- a keyboard shortcut, a route change.
+ */
+export interface Props {
+    /** What opens it. Any focusable element; a `Button` is the usual one. */
+    trigger: React.ReactNode;
+    /** The contents. A render function receives `close` for a surface whose own
+     *  controls dismiss it -- picking a colour, applying a filter. */
+    children: React.ReactNode | ((close: () => void) => React.ReactNode);
+    /** Which side it prefers. It will use another if this one does not fit. */
+    placement?: Placement;
+    /** Names the surface. A dialog owes an accessible name; without one a
+     *  screen reader announces "dialog" and nothing else. */
+    label: string;
+    /** Gap between the trigger and the surface. */
+    offset?: number;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    className?: string;
+}
+export default function Popover({ trigger, children, placement, label, offset, open, onOpenChange, className, }: Props): import("react").JSX.Element;

package/dist/components/Popover.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Popover as AriaPopover, Dialog, DialogTrigger, } from 'react-aria-components';
+export default function Popover({ trigger, children, placement = 'bottom start', label, offset = 6, open, onOpenChange, className, }) {
+    return (_jsxs(DialogTrigger, { isOpen: open, onOpenChange: onOpenChange, children: [trigger, _jsx(AriaPopover, { className: `pop${className ? ` ${className}` : ''}`, placement: placement, offset: offset, children: _jsx(Dialog, { className: "pop-body", "aria-label": label, children: ({ close }) => (typeof children === 'function' ? children(close) : children) }) })] }));
+}