@haruhimemoe/ui 0.2.0 → 0.4.0

package/dist/components/actions/AsyncButton.js

@@ -0,0 +1,48 @@
+/**
+ * @file src/components/actions/AsyncButton.tsx
+ * @desc A button that runs an async action and says how it went in an <output> beside it (a
+ *       polite live region), like the apps' refresh and retry buttons. While the action runs the
+ *       button stays focusable but ignores presses (aria-disabled), and can show a pending label.
+ *       A rejected action shows the failure message in rose.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useState } from "react";
+import { cx } from "../../utils/cx.js";
+import { Button } from "../basics/Button.js";
+import { StatusOutput } from "./StatusOutput.js";
+import { useLatestStatus } from "./useLatestStatus.js";
+/**
+ * @function AsyncButton
+ * @param props {AsyncButtonProps} the action, an optional pending label and failure message, plus
+ *        Button props (`className` and `ref` go on the button)
+ * @returns {JSX.Element} the button and an `<output>` that announces the action's result
+ */
+export function AsyncButton({ action, pendingLabel, failedMessage = "Something went wrong. Try again.", wrapperClassName, className, children, ...props }) {
+    const [pending, setPending] = useState(false);
+    // `pending` reaches the button only after a render; two presses in one frame must not both run.
+    const running = useRef(false);
+    const { status, start, settle } = useLatestStatus();
+    const run = async () => {
+        if (running.current)
+            return;
+        running.current = true;
+        setPending(true);
+        const id = start();
+        try {
+            settle(id, { message: await action(), failed: false });
+        }
+        catch (error) {
+            const message = typeof failedMessage === "function" ? failedMessage(error) : failedMessage;
+            settle(id, { message, failed: true });
+        }
+        finally {
+            running.current = false;
+            setPending(false);
+        }
+    };
+    return (_jsxs("div", { className: cx("flex flex-wrap items-center gap-3", wrapperClassName), children: [_jsx(Button, { "aria-disabled": pending || undefined, onClick: run, className: cx("aria-disabled:cursor-wait aria-disabled:opacity-70", className), ...props, children: pending && pendingLabel !== undefined ? pendingLabel : children }), _jsx(StatusOutput, { run: status?.run ?? null, children: status?.result.failed ? (_jsx("span", { className: "text-rose-300", children: status.result.message })) : (status?.result.message) })] }));
+}

package/dist/components/actions/CopyButton.d.ts

@@ -4,12 +4,12 @@
  *       it (a polite live region), like the packs export and doc pages. If the clipboard is
  *       missing or refuses, it says so and tells the reader to copy by hand. Each press empties
  *       the status first and then writes the result as a new node, so a second copy is announced
- *       too.
+ *       too. Only the latest press reports: a slow earlier copy that settles later is ignored.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
-import { type ReactNode } from "react";
+import type { ReactNode } from "react";
 import { type ButtonProps } from "../basics/Button.js";
 /** Every Button prop (native button props, variant, size) except children and onClick. */
 export type CopyButtonProps = Omit<ButtonProps, "children" | "onClick"> & {

package/dist/components/actions/CopyButton.js

@@ -4,16 +4,17 @@
  *       it (a polite live region), like the packs export and doc pages. If the clipboard is
  *       missing or refuses, it says so and tells the reader to copy by hand. Each press empties
  *       the status first and then writes the result as a new node, so a second copy is announced
- *       too.
+ *       too. Only the latest press reports: a slow earlier copy that settles later is ignored.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useRef, useState } from "react";
 import { cx } from "../../utils/cx.js";
 import { Button } from "../basics/Button.js";
+import { StatusOutput } from "./StatusOutput.js";
+import { useLatestStatus } from "./useLatestStatus.js";
 /**
  * @function CopyButton
  * @param props {CopyButtonProps} the text to copy, optional label and status messages, plus
@@ -21,20 +22,16 @@ import { Button } from "../basics/Button.js";
  * @returns {JSX.Element} the button and an `<output>` that announces "Copied." or the failure
  */
 export function CopyButton({ text, label = "Copy", copiedMessage = "Copied.", failedMessage = "Couldn't copy. Select the text and copy it by hand.", wrapperClassName, variant = "secondary", ...props }) {
-    const [status, setStatus] = useState(null);
-    const presses = useRef(0);
+    const { status, start, settle } = useLatestStatus();
     const copy = async () => {
-        // Empty the live region, then fill it with a fresh node: a status that never changes (the
-        // same "Copied." twice) is not announced again.
-        setStatus(null);
-        const press = ++presses.current;
+        const run = start();
         try {
             await navigator.clipboard.writeText(text);
-            setStatus({ result: "copied", press });
+            settle(run, "copied");
         }
         catch {
-            setStatus({ result: "failed", press });
+            settle(run, "failed");
         }
     };
-    return (_jsxs("div", { className: cx("flex flex-wrap items-center gap-3", wrapperClassName), children: [_jsx(Button, { variant: variant, onClick: copy, ...props, children: label }), _jsx("output", { className: "text-c3 text-sm", children: status ? (_jsx("span", { children: status.result === "copied" ? copiedMessage : failedMessage }, status.press)) : null })] }));
+    return (_jsxs("div", { className: cx("flex flex-wrap items-center gap-3", wrapperClassName), children: [_jsx(Button, { variant: variant, onClick: copy, ...props, children: label }), _jsx(StatusOutput, { run: status?.run ?? null, children: status?.result === "copied" ? copiedMessage : failedMessage })] }));
 }

package/dist/components/actions/InlineConfirm.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @file src/components/actions/InlineConfirm.tsx
+ * @desc A two-step confirm in the page, no dialog: a trigger button, then the question with a
+ *       cancel and a confirm button in its place. Focus never falls to the page body: opening
+ *       moves it to cancel (the safe choice), and cancelling or Escape puts it back on the
+ *       trigger. The open confirm is a fieldset named by the question, so screen readers hear it.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { type ComponentProps, type ReactNode } from "react";
+import { type ButtonProps } from "../basics/Button.js";
+import type { ButtonVariant } from "../basics/buttonStyles.js";
+/**
+ * Every native `<div>` prop except children and ref (the wrapper is a `<div>` closed and a
+ * `<fieldset>` open), plus the two steps' text and the action.
+ */
+export type InlineConfirmProps = Omit<ComponentProps<"div">, "children" | "ref"> & {
+    /** The first button's text, e.g. "Delete". */
+    trigger: ReactNode;
+    /** Shown once the trigger is pressed, e.g. "Delete this pack for good?". Names the group. */
+    question: ReactNode;
+    /** The confirm button's text (default "Confirm"). */
+    confirmLabel?: ReactNode;
+    /** The cancel button's text (default "Cancel"). */
+    cancelLabel?: ReactNode;
+    /** The confirm button's text while `onConfirm` runs. Defaults to `confirmLabel`. */
+    pendingLabel?: ReactNode;
+    /** Runs on confirm. If it throws or rejects, the confirm stays open: show the error yourself. */
+    onConfirm: () => void | Promise<void>;
+    /** Called when the confirm closes without confirming (Cancel or Escape). */
+    onCancel?: (() => void) | undefined;
+    /** Props for the trigger button (`aria-label`, `variant`, `disabled`...). Variant "secondary". */
+    triggerProps?: Omit<ButtonProps, "onClick" | "children" | "ref"> | undefined;
+    /** The confirm button's variant (default "secondary"). Cancel is always "ghost". */
+    confirmVariant?: ButtonVariant | undefined;
+};
+/**
+ * @function InlineConfirm
+ * @param props {InlineConfirmProps} the trigger, question and button texts, the confirm action,
+ *        plus native div props for the wrapper
+ * @returns {JSX.Element} the trigger, or the question with cancel and confirm buttons. After a
+ *          confirm that resolves, the trigger comes back and takes focus.
+ */
+export declare function InlineConfirm({ trigger, question, confirmLabel, cancelLabel, pendingLabel, onConfirm, onCancel, triggerProps, confirmVariant, className, ...props }: InlineConfirmProps): import("react").JSX.Element;

package/dist/components/actions/InlineConfirm.js

@@ -0,0 +1,80 @@
+/**
+ * @file src/components/actions/InlineConfirm.tsx
+ * @desc A two-step confirm in the page, no dialog: a trigger button, then the question with a
+ *       cancel and a confirm button in its place. Focus never falls to the page body: opening
+ *       moves it to cancel (the safe choice), and cancelling or Escape puts it back on the
+ *       trigger. The open confirm is a fieldset named by the question, so screen readers hear it.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState, } from "react";
+import { cx } from "../../utils/cx.js";
+import { Button } from "../basics/Button.js";
+/**
+ * @function InlineConfirm
+ * @param props {InlineConfirmProps} the trigger, question and button texts, the confirm action,
+ *        plus native div props for the wrapper
+ * @returns {JSX.Element} the trigger, or the question with cancel and confirm buttons. After a
+ *          confirm that resolves, the trigger comes back and takes focus.
+ */
+export function InlineConfirm({ trigger, question, confirmLabel = "Confirm", cancelLabel = "Cancel", pendingLabel, onConfirm, onCancel, triggerProps, confirmVariant = "secondary", className, ...props }) {
+    const questionId = useId();
+    const [open, setOpen] = useState(false);
+    const [pending, setPending] = useState(false);
+    const running = useRef(false);
+    const triggerRef = useRef(null);
+    const cancelRef = useRef(null);
+    // Whether the next render should move focus: set only by the person's own open or close.
+    const moveFocus = useRef(false);
+    useEffect(() => {
+        if (!moveFocus.current)
+            return;
+        moveFocus.current = false;
+        (open ? cancelRef : triggerRef).current?.focus();
+    }, [open]);
+    const toggle = (next) => {
+        moveFocus.current = true;
+        setOpen(next);
+    };
+    const cancel = () => {
+        if (running.current)
+            return;
+        toggle(false);
+        onCancel?.();
+    };
+    const confirm = async () => {
+        // `pending` reaches the buttons only after a render; two presses must not both run.
+        if (running.current)
+            return;
+        running.current = true;
+        setPending(true);
+        try {
+            await onConfirm();
+            toggle(false);
+        }
+        catch {
+            // Stay open, with focus where it is, so the person can try again or cancel.
+        }
+        finally {
+            running.current = false;
+            setPending(false);
+        }
+    };
+    const wrapper = cx("flex flex-wrap items-center gap-2", className);
+    if (!open) {
+        return (_jsx("div", { className: wrapper, ...props, children: _jsx(Button, { variant: "secondary", ...triggerProps, ref: triggerRef, onClick: () => toggle(true), children: trigger }) }));
+    }
+    // While the action runs the buttons ignore presses but keep focus (aria-disabled, not
+    // disabled, which would drop focus to the body).
+    const busy = pending || undefined;
+    const onEscape = (event) => {
+        if (event.key !== "Escape")
+            return;
+        event.preventDefault();
+        cancel();
+    };
+    return (_jsxs("fieldset", { "aria-labelledby": questionId, className: wrapper, ...props, children: [_jsx("span", { id: questionId, className: "text-c3 text-sm", children: question }), _jsx(Button, { ref: cancelRef, variant: "ghost", "aria-disabled": busy, onClick: cancel, onKeyDown: onEscape, children: cancelLabel }), _jsx(Button, { variant: confirmVariant, "aria-disabled": busy, onClick: confirm, onKeyDown: onEscape, children: pending && pendingLabel !== undefined ? pendingLabel : confirmLabel })] }));
+}

package/dist/components/actions/Pagination.d.ts

@@ -1,33 +1,56 @@
 /**
  * @file src/components/actions/Pagination.tsx
- * @desc Previous / next links around "Page X of Y". Renders nothing for a single page. The
- *       caller builds each page's URL, so it works with any query string or route shape. When
- *       the link a keyboard user pressed goes away (Next on the last page), focus moves to the
- *       status text instead of the page body.
+ * @desc Previous / next around "Page X of Y". Renders nothing for a single page. Two modes: links
+ *       (`hrefFor`, the caller builds each page's URL, so it works with any query string or route
+ *       shape) or buttons (`onPageChange`, for results fetched in place, where the page count may
+ *       be unknown). When a link a keyboard user pressed goes away (Next on the last page), focus
+ *       moves to the status text instead of the page body; buttons stay and ignore presses. A page
+ *       or count from a URL is normalized first: NaN reads as page 1, and a page past either end
+ *       is pulled back inside. A server component; button mode needs client code for its handler.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
 import type { ComponentProps, ReactNode } from "react";
-/** Every native `<nav>` prop except children, plus the page state and the link builder. */
-export type PaginationProps = Omit<ComponentProps<"nav">, "children"> & {
-    /** The current page, 1-based. */
+type PaginationBase = Omit<ComponentProps<"nav">, "children"> & {
+    /** The current page, 1-based. NaN reads as 1; a page past either end is pulled back inside. */
     page: number;
-    /** How many pages there are. At 1 or fewer, nothing renders. */
+    /** Text of the control for the page before. Defaults to "Previous". */
+    previousLabel?: ReactNode | undefined;
+    /** Text of the control for the page after. Defaults to "Next". */
+    nextLabel?: ReactNode | undefined;
+};
+/** Link mode: each page has a URL. */
+type PaginationLinkProps = PaginationBase & {
+    /** How many pages there are. At 1 or fewer (or NaN), nothing renders. */
     pageCount: number;
     /** Builds the URL for a page number, e.g. `(p) => \`/packs?page=${p}\``. */
     hrefFor: (page: number) => string;
-    /** Text of the link to the page before. Defaults to "Previous". */
-    previousLabel?: ReactNode | undefined;
-    /** Text of the link to the page after. Defaults to "Next". */
-    nextLabel?: ReactNode | undefined;
+    onPageChange?: undefined;
+    hasNext?: undefined;
     /** The middle text. Defaults to "Page X of Y". */
     formatStatus?: ((page: number, pageCount: number) => ReactNode) | undefined;
 };
+/** Button mode: the caller changes the page in place. */
+type PaginationButtonModeProps = PaginationBase & {
+    /** How many pages there are, or null when that isn't known (then `hasNext` says if there's more). */
+    pageCount: number | null;
+    /** Called with the page to show (from client code). */
+    onPageChange: (page: number) => void;
+    hrefFor?: undefined;
+    /** With a null `pageCount`: whether there is a page after this one. Default false. */
+    hasNext?: boolean | undefined;
+    /** The middle text. Defaults to "Page X of Y", or "Page X" with a null `pageCount`. */
+    formatStatus?: ((page: number, pageCount: number | null) => ReactNode) | undefined;
+};
+/** Every native `<nav>` prop except children, the page state, and `hrefFor` or `onPageChange`. */
+export type PaginationProps = PaginationLinkProps | PaginationButtonModeProps;
 /**
  * @function Pagination
- * @param props {PaginationProps} page, pageCount and hrefFor, optional labels, plus native nav
- *        props (`aria-label` defaults to "Pages")
- * @returns {JSX.Element | null} a `<nav>` with previous / next pill links, or null for one page
+ * @param props {PaginationProps} page, pageCount, and hrefFor (links) or onPageChange (buttons),
+ *        optional labels, plus native nav props (`aria-label` defaults to "Pages")
+ * @returns {JSX.Element | null} a `<nav>` with previous / next pills around the status, or null
+ *          when there is only one page
  */
-export declare function Pagination({ page, pageCount, hrefFor, previousLabel, nextLabel, formatStatus, className, ...props }: PaginationProps): import("react").JSX.Element | null;
+export declare function Pagination(props: PaginationProps): import("react").JSX.Element | null;
+export {};

package/dist/components/actions/Pagination.js

@@ -1,27 +1,34 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/**
- * @file src/components/actions/Pagination.tsx
- * @desc Previous / next links around "Page X of Y". Renders nothing for a single page. The
- *       caller builds each page's URL, so it works with any query string or route shape. When
- *       the link a keyboard user pressed goes away (Next on the last page), focus moves to the
- *       status text instead of the page body.
- * @author David @dvhsh (https://dvh.sh)
- * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
- */
-import Link from "next/link.js";
 import { cx } from "../../utils/cx.js";
+import { ButtonLink } from "../basics/ButtonLink.js";
 import { buttonClasses } from "../basics/buttonStyles.js";
+import { PaginationButton } from "./PaginationButton.js";
 import { PaginationStatus } from "./PaginationStatus.js";
-const defaultStatus = (page, pageCount) => `Page ${page} of ${pageCount}`;
+import { normalizePages } from "./pages.js";
+const defaultStatus = (page, pageCount) => pageCount === null ? `Page ${page}` : `Page ${page} of ${pageCount}`;
+// Button mode's ends stay in place, dimmed, and keep focus.
+const BUTTON = buttonClasses({
+    variant: "secondary",
+    className: "aria-disabled:cursor-not-allowed aria-disabled:opacity-50",
+});
 /**
  * @function Pagination
- * @param props {PaginationProps} page, pageCount and hrefFor, optional labels, plus native nav
- *        props (`aria-label` defaults to "Pages")
- * @returns {JSX.Element | null} a `<nav>` with previous / next pill links, or null for one page
+ * @param props {PaginationProps} page, pageCount, and hrefFor (links) or onPageChange (buttons),
+ *        optional labels, plus native nav props (`aria-label` defaults to "Pages")
+ * @returns {JSX.Element | null} a `<nav>` with previous / next pills around the status, or null
+ *          when there is only one page
  */
-export function Pagination({ page, pageCount, hrefFor, previousLabel = "Previous", nextLabel = "Next", formatStatus = defaultStatus, className, ...props }) {
-    if (pageCount <= 1)
+export function Pagination(props) {
+    const { page: rawPage, pageCount: rawPageCount, hrefFor, onPageChange, hasNext = false, previousLabel = "Previous", nextLabel = "Next", formatStatus = defaultStatus, className, ...rest } = props;
+    const { page, pageCount } = normalizePages(rawPage, rawPageCount);
+    const more = pageCount === null ? hasNext : page < pageCount;
+    if (page <= 1 && !more)
         return null;
-    return (_jsxs("nav", { "aria-label": "Pages", className: cx("flex items-center justify-between gap-3 text-sm", className), ...props, children: [page > 1 ? (_jsx(Link, { href: hrefFor(page - 1), rel: "prev", className: buttonClasses({ variant: "secondary" }), children: previousLabel })) : (_jsx("span", {})), _jsx(PaginationStatus, { children: formatStatus(page, pageCount) }), page < pageCount ? (_jsx(Link, { href: hrefFor(page + 1), rel: "next", className: buttonClasses({ variant: "secondary" }), children: nextLabel })) : (_jsx("span", {}))] }));
+    // Link mode never has a null count, so both status formatters take this call.
+    const status = formatStatus(page, pageCount);
+    const nav = cx("flex items-center justify-between gap-3 text-sm", className);
+    if (onPageChange) {
+        return (_jsxs("nav", { "aria-label": "Pages", className: nav, ...rest, children: [_jsx(PaginationButton, { page: page - 1, off: page <= 1, onPageChange: onPageChange, className: BUTTON, children: previousLabel }), _jsx(PaginationStatus, { live: true, children: status }), _jsx(PaginationButton, { page: page + 1, off: !more, onPageChange: onPageChange, className: BUTTON, children: nextLabel })] }));
+    }
+    return (_jsxs("nav", { "aria-label": "Pages", className: nav, ...rest, children: [page > 1 && hrefFor ? (_jsx(ButtonLink, { href: hrefFor(page - 1), rel: "prev", variant: "secondary", children: previousLabel })) : (_jsx("span", {})), _jsx(PaginationStatus, { children: status }), more && hrefFor ? (_jsx(ButtonLink, { href: hrefFor(page + 1), rel: "next", variant: "secondary", children: nextLabel })) : (_jsx("span", {}))] }));
 }

package/dist/components/actions/PaginationButton.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file src/components/actions/PaginationButton.tsx
+ * @desc Pagination's Previous or Next button in button mode (internal). At the first or last page
+ *       it stays in place and keeps focus, but ignores presses (aria-disabled). Its classes arrive
+ *       finished from Pagination, so it imports no class merging.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import type { ReactNode } from "react";
+/** The page it goes to, whether it's off, the handler, finished classes and its text. */
+export type PaginationButtonProps = {
+    page: number;
+    off: boolean;
+    onPageChange: (page: number) => void;
+    className: string;
+    children: ReactNode;
+};
+/**
+ * @function PaginationButton
+ * @param props {PaginationButtonProps} the target page, whether there is none, the page handler,
+ *        classes and text
+ * @returns {JSX.Element} a `<button type="button">` that calls `onPageChange(page)` unless it's off
+ */
+export declare function PaginationButton({ page, off, onPageChange, className, children, }: PaginationButtonProps): import("react").JSX.Element;

package/dist/components/actions/PaginationButton.js

@@ -0,0 +1,23 @@
+/**
+ * @file src/components/actions/PaginationButton.tsx
+ * @desc Pagination's Previous or Next button in button mode (internal). At the first or last page
+ *       it stays in place and keeps focus, but ignores presses (aria-disabled). Its classes arrive
+ *       finished from Pagination, so it imports no class merging.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @function PaginationButton
+ * @param props {PaginationButtonProps} the target page, whether there is none, the page handler,
+ *        classes and text
+ * @returns {JSX.Element} a `<button type="button">` that calls `onPageChange(page)` unless it's off
+ */
+export function PaginationButton({ page, off, onPageChange, className, children, }) {
+    return (_jsx("button", { type: "button", "aria-disabled": off || undefined, className: className, onClick: () => {
+            if (!off)
+                onPageChange(page);
+        }, children: children }));
+}

package/dist/components/actions/PaginationStatus.d.ts

@@ -2,18 +2,21 @@
  * @file src/components/actions/PaginationStatus.tsx
  * @desc Pagination's "Page X of Y" text (internal). It also keeps keyboard focus in place: when
  *       the link that had focus goes away (Next on the last page, Previous on the first), focus
- *       moves here instead of falling back to the page body.
+ *       moves here instead of falling back to the page body. In button mode it is a polite live
+ *       region, since the page changes without a navigation.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
 import { type ReactNode } from "react";
 /**
  * @function PaginationStatus
- * @param props {{ children: ReactNode }} the status text
+ * @param props {{ children: ReactNode; live?: boolean }} the status text, and whether to announce
+ *        its changes
  * @returns {JSX.Element} a `<span aria-current="page">` that script can focus (tabIndex -1), so
  *          it stays out of the tab order
  */
-export declare function PaginationStatus({ children }: {
+export declare function PaginationStatus({ children, live, }: {
     children: ReactNode;
+    live?: boolean;
 }): import("react").JSX.Element;

package/dist/components/actions/PaginationStatus.js

@@ -2,21 +2,23 @@
  * @file src/components/actions/PaginationStatus.tsx
  * @desc Pagination's "Page X of Y" text (internal). It also keeps keyboard focus in place: when
  *       the link that had focus goes away (Next on the last page, Previous on the first), focus
- *       moves here instead of falling back to the page body.
+ *       moves here instead of falling back to the page body. In button mode it is a polite live
+ *       region, since the page changes without a navigation.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef } from "react";
 /**
  * @function PaginationStatus
- * @param props {{ children: ReactNode }} the status text
+ * @param props {{ children: ReactNode; live?: boolean }} the status text, and whether to announce
+ *        its changes
  * @returns {JSX.Element} a `<span aria-current="page">` that script can focus (tabIndex -1), so
  *          it stays out of the tab order
  */
-export function PaginationStatus({ children }) {
+export function PaginationStatus({ children, live = false, }) {
     const ref = useRef(null);
     const lastFocused = useRef(null);
     // Remember what last had focus inside the nav.
@@ -40,5 +42,5 @@ export function PaginationStatus({ children }) {
         if (active === null || active === document.body)
             ref.current?.focus();
     });
-    return (_jsx("span", { ref: ref, tabIndex: -1, "aria-current": "page", className: "text-c4", children: children }));
+    return (_jsx("span", { ref: ref, tabIndex: -1, "aria-current": "page", "aria-live": live ? "polite" : undefined, className: "text-c4", children: children }));
 }

package/dist/components/actions/StatusOutput.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file src/components/actions/StatusOutput.tsx
+ * @desc The `<output>` beside CopyButton and AsyncButton (internal): a polite live region whose
+ *       message mounts as a new node on every run, so the same text twice is announced twice.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import type { ReactNode } from "react";
+/** The run the message belongs to (null for none), and the message. */
+export type StatusOutputProps = {
+    run: number | null;
+    children?: ReactNode;
+};
+/**
+ * @function StatusOutput
+ * @param props {StatusOutputProps} the run's number and its message
+ * @returns {JSX.Element} an `<output>` in c3 at text-sm, holding the message keyed by its run
+ */
+export declare function StatusOutput({ run, children }: StatusOutputProps): import("react").JSX.Element;

package/dist/components/actions/StatusOutput.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @function StatusOutput
+ * @param props {StatusOutputProps} the run's number and its message
+ * @returns {JSX.Element} an `<output>` in c3 at text-sm, holding the message keyed by its run
+ */
+export function StatusOutput({ run, children }) {
+    return (_jsx("output", { className: "text-c3 text-sm", children: run === null ? null : _jsx("span", { children: children }, run) }));
+}

package/dist/components/actions/pages.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file src/components/actions/pages.ts
+ * @desc Pagination's page math (internal): what to do with a page and page count that came from
+ *       a URL or an API, where they can be NaN, fractional or out of range.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** A page and a page count after normalizing. `pageCount` is null when it isn't known. */
+export type PageState = {
+    page: number;
+    pageCount: number | null;
+};
+/**
+ * @function normalizePages
+ * @param page {number} the current page, 1-based, as the caller has it
+ * @param pageCount {number | null} how many pages there are, or null when it isn't known
+ * @returns {PageState} whole numbers: a non-finite count is 1 and a negative one 0, and the page
+ *          sits between 1 and the count (at least 1), with a non-finite page read as 1
+ */
+export declare const normalizePages: (page: number, pageCount: number | null) => PageState;

package/dist/components/actions/pages.js

@@ -0,0 +1,21 @@
+/**
+ * @file src/components/actions/pages.ts
+ * @desc Pagination's page math (internal): what to do with a page and page count that came from
+ *       a URL or an API, where they can be NaN, fractional or out of range.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/**
+ * @function normalizePages
+ * @param page {number} the current page, 1-based, as the caller has it
+ * @param pageCount {number | null} how many pages there are, or null when it isn't known
+ * @returns {PageState} whole numbers: a non-finite count is 1 and a negative one 0, and the page
+ *          sits between 1 and the count (at least 1), with a non-finite page read as 1
+ */
+export const normalizePages = (page, pageCount) => {
+    const count = pageCount === null ? null : Number.isFinite(pageCount) ? Math.max(Math.floor(pageCount), 0) : 1;
+    const last = count === null ? Number.POSITIVE_INFINITY : Math.max(count, 1);
+    const current = Number.isFinite(page) ? Math.min(Math.max(Math.floor(page), 1), last) : 1;
+    return { page: current, pageCount: count };
+};

package/dist/components/actions/useLatestStatus.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file src/components/actions/useLatestStatus.ts
+ * @desc The status that CopyButton and AsyncButton report (internal): each run empties it first,
+ *       and only the latest run may fill it, so a slow earlier run can't overwrite a newer result.
+ *       Each result carries its run's number, so StatusOutput mounts it as a fresh node and a
+ *       repeated message is announced again.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** The latest run's result and its number, or null while nothing is to be said. */
+export type LatestStatus<T> = {
+    result: T;
+    run: number;
+} | null;
+/**
+ * @function useLatestStatus
+ * @returns {{ status: LatestStatus<T>; start: () => number; settle: (run: number, result: T) =>
+ *          void }} the status, `start` (empties it and returns the new run's number) and `settle`
+ *          (sets a run's result, unless a later run has started since)
+ */
+export declare function useLatestStatus<T>(): {
+    status: LatestStatus<T>;
+    start: () => number;
+    settle: (run: number, result: T) => void;
+};

package/dist/components/actions/useLatestStatus.js

@@ -0,0 +1,32 @@
+/**
+ * @file src/components/actions/useLatestStatus.ts
+ * @desc The status that CopyButton and AsyncButton report (internal): each run empties it first,
+ *       and only the latest run may fill it, so a slow earlier run can't overwrite a newer result.
+ *       Each result carries its run's number, so StatusOutput mounts it as a fresh node and a
+ *       repeated message is announced again.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+"use client";
+import { useRef, useState } from "react";
+/**
+ * @function useLatestStatus
+ * @returns {{ status: LatestStatus<T>; start: () => number; settle: (run: number, result: T) =>
+ *          void }} the status, `start` (empties it and returns the new run's number) and `settle`
+ *          (sets a run's result, unless a later run has started since)
+ */
+export function useLatestStatus() {
+    const [status, setStatus] = useState(null);
+    const runs = useRef(0);
+    const start = () => {
+        setStatus(null);
+        runs.current += 1;
+        return runs.current;
+    };
+    const settle = (run, result) => {
+        if (run === runs.current)
+            setStatus({ result, run });
+    };
+    return { status, start, settle };
+}