@apliteni/apliteni-ui 0.40.0 → 0.41.1

package/README.md

@@ -144,6 +144,30 @@ Storybook. A stranger on the port is never composed — the "React components"
 section is absent instead, and the terminal says why. Details in
 [`react/README.md`](./react/README.md).
 
+### Updating a busy button
+
+Keep the factory-created element in place to animate its label:
+
+```js
+import { button, setButtonBusy } from '@apliteni/apliteni-ui';
+host.innerHTML = button({ label: 'Save changes', variant: 'primary' });
+const control = host.querySelector('button');
+setButtonBusy(control, { busy: true });
+// When the request completes:
+setButtonBusy(control, { busy: false });
+```
+
+The helper keeps focus on the button, uses `aria-disabled` and blocks clicks,
+Enter and Space while busy. Its sibling polite live region announces progress and completion.
+Explicit `disabled: true` stays natively disabled. Static `button({ busy: true })`
+markup uses native disabled until the helper wires it; call `setButtonBusy` to
+switch to the focus-preserving behavior. React `<Button busy={saving}>Save changes</Button>` uses the same treatment.
+The action label slides down, three dots take its place, and the label returns from below
+when complete. Its hidden label preserves the width and accessible name. React retains
+the last ready children while busy; changed children appear on completion. Reduced
+motion switches immediately to static dots.
+See Storybook's **Button / Busy Transition** for the live vanilla example.
+
 ## Theming
 
 Theme is a `data-theme="dark|light"` attribute on `<html>`; accent is an orthogonal
@@ -187,7 +211,7 @@ src/
   inline.js              # CSS as strings for server-render consumers (…/inline)
   assets/                # brand mark (seedling) + line-icon set
   components/            # HTML-string factories: button(), card(), badge(), topbar()…
-stories/                 # Storybook: Foundations, Components, Apps
+stories/                 # Storybook: Foundations, Components, Showcases
 site/                    # ui.apli.tech landing page (static site build)
 react/                   # React components — private workspace, built to react/dist/
   dist/                  #   tsup output; shipped as …/react and …/react/css

package/guidelines/component-choice.md

@@ -1,5 +1,17 @@
 # Component choice
 
+## Make the committing action stand out
+
+<!-- rule: paired-actions -->
+
+**Rule:** In a pair of actions, give the committing action more visual weight than the dismissing action.
+
+**Why:** Equal weight makes it harder to see which button commits the change.
+
+**Do:** Use a primary Save button beside a ghost Cancel button.
+
+**Don't:** Give Save and Cancel the same primary style.
+
 ## Interrupt with a question
 
 <!-- rule: interrupt -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.40.0",
+  "version": "0.41.1",
   "workspaces": [
     "react"
   ],

package/react/dist/index.d.ts

@@ -12,11 +12,11 @@ type ButtonProps = {
     iconRight?: string;
     iconOnly?: boolean;
     block?: boolean;
-    /** In flight: aria-busy, disabled, and the kit's indeterminate bars. */
+    /** In flight: keeps focus, blocks activation, announces progress, and shows dots. */
     busy?: boolean;
     children?: ReactNode;
 } & ButtonHTMLAttributes<HTMLButtonElement>;
-declare function Button({ variant, size, icon, iconRight, iconOnly, block, busy, children, type, disabled, ...rest }: ButtonProps): react.JSX.Element;
+declare function Button({ variant, size, icon, iconRight, iconOnly, block, busy, children, type, disabled, onClick, onClickCapture, onKeyDown, onKeyDownCapture, onKeyUp, onKeyUpCapture, ...rest }: ButtonProps): react.JSX.Element;
 
 declare function Badge({ variant, children }: {
     variant?: string;

package/react/dist/index.js

@@ -15,7 +15,38 @@ function Icon({ name }) {
 }
 
 // src/primitives/Button.tsx
+import { useLayoutEffect, useRef } from "react";
 import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+var announcers = /* @__PURE__ */ new WeakMap();
+function acquireAnnouncer(doc) {
+  let entry = announcers.get(doc);
+  if (!entry) {
+    const node = doc.createElement("span");
+    node.className = "ui-sr ui-btn__status";
+    node.setAttribute("role", "status");
+    node.setAttribute("aria-live", "polite");
+    doc.body.append(node);
+    entry = { node, users: 0 };
+    announcers.set(doc, entry);
+  }
+  const current = entry;
+  current.users++;
+  return {
+    announce(text2) {
+      clearTimeout(current.timer);
+      current.timer = setTimeout(() => {
+        current.node.textContent = text2;
+      }, 0);
+    },
+    release() {
+      if (--current.users === 0) {
+        clearTimeout(current.timer);
+        current.node.remove();
+        announcers.delete(doc);
+      }
+    }
+  };
+}
 var cx = (...a) => a.filter(Boolean).join(" ");
 function Button({
   variant = "secondary",
@@ -28,8 +59,45 @@ function Button({
   children,
   type = "button",
   disabled,
+  onClick,
+  onClickCapture,
+  onKeyDown,
+  onKeyDownCapture,
+  onKeyUp,
+  onKeyUpCapture,
   ...rest
 }) {
+  const buttonRef = useRef(null);
+  const labelRef = useRef(null);
+  const announcer = useRef(null);
+  const hasBeenBusy = useRef(false);
+  if (busy) hasBeenBusy.current = true;
+  const readyChildren = useRef(children);
+  if (!busy) readyChildren.current = children;
+  const renderedChildren = busy ? readyChildren.current : children;
+  const previous = useRef(null);
+  useLayoutEffect(() => {
+    const label = labelRef.current;
+    const text2 = label?.textContent ?? buttonRef.current?.getAttribute("aria-label") ?? "";
+    const prior = previous.current;
+    if ((busy || prior?.busy) && (!prior || prior.text !== text2 || prior.busy !== busy)) {
+      announcer.current ?? (announcer.current = acquireAnnouncer(buttonRef.current.ownerDocument));
+      announcer.current.announce(`${text2}: ${busy ? "in progress" : "complete"}`);
+    }
+    previous.current = { text: text2, busy };
+  });
+  useLayoutEffect(() => () => {
+    announcer.current?.release();
+    announcer.current = null;
+    previous.current = null;
+  }, []);
+  const blockActivation = (event) => {
+    if (!busy) return false;
+    event.preventDefault();
+    event.stopPropagation();
+    return true;
+  };
+  const blockKey = (event) => (event.key === "Enter" || event.key === " ") && blockActivation(event);
   const cls = cx(
     "ui-btn",
     variant && `ui-btn--${variant}`,
@@ -43,18 +111,40 @@ function Button({
   return /* @__PURE__ */ jsxs(
     "button",
     {
+      ref: buttonRef,
+      "data-btn-wired": "",
+      "data-btn-ready": !busy && hasBeenBusy.current ? "" : void 0,
       type,
       className: cls,
-      disabled: disabled || busy,
+      disabled,
       "aria-disabled": disabled || busy ? true : void 0,
       "aria-busy": busy ? true : void 0,
       ...rest,
       ...named,
+      onClickCapture: (event) => {
+        if (!blockActivation(event)) onClickCapture?.(event);
+      },
+      onClick: (event) => {
+        if (!blockActivation(event)) onClick?.(event);
+      },
+      onKeyDownCapture: (event) => {
+        if (!blockKey(event)) onKeyDownCapture?.(event);
+      },
+      onKeyDown: (event) => {
+        if (!blockKey(event)) onKeyDown?.(event);
+      },
+      onKeyUpCapture: (event) => {
+        if (!blockKey(event)) onKeyUpCapture?.(event);
+      },
+      onKeyUp: (event) => {
+        if (!blockKey(event)) onKeyUp?.(event);
+      },
       children: [
         icon4 && /* @__PURE__ */ jsx2(Icon, { name: icon4 }),
-        !iconOnly && children != null && /* @__PURE__ */ jsx2("span", { children }),
+        !iconOnly && renderedChildren != null && /* @__PURE__ */ jsx2("span", { className: "ui-btn__label-slot", children: /* @__PURE__ */ jsx2("span", { className: "ui-btn__label", ref: labelRef, children: renderedChildren }) }),
         iconRight && /* @__PURE__ */ jsx2(Icon, { name: iconRight }),
-        busy && /* @__PURE__ */ jsxs("span", { className: "ui-btn__bars", children: [
+        busy && /* @__PURE__ */ jsxs("span", { className: "ui-btn__dots", "aria-hidden": "true", children: [
+          /* @__PURE__ */ jsx2("i", {}),
           /* @__PURE__ */ jsx2("i", {}),
           /* @__PURE__ */ jsx2("i", {})
         ] })
@@ -127,7 +217,7 @@ function StatBand({ stats, variant = "tiles", basis, label, id }) {
 }
 
 // src/Modal.tsx
-import { useRef as useRef2 } from "react";
+import { useRef as useRef3 } from "react";
 import { createPortal } from "react-dom";
 
 // src/dialog.ts
@@ -135,8 +225,8 @@ import {
   createContext,
   useContext,
   useEffect,
-  useLayoutEffect,
-  useRef,
+  useLayoutEffect as useLayoutEffect2,
+  useRef as useRef2,
   useState
 } from "react";
 var FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]), details > summary:first-of-type';
@@ -158,7 +248,7 @@ var dismissOnScrim = (onClose) => (e) => {
   e.preventDefault();
   onClose();
 };
-var useIsoLayoutEffect = typeof document === "undefined" ? useEffect : useLayoutEffect;
+var useIsoLayoutEffect = typeof document === "undefined" ? useEffect : useLayoutEffect2;
 function transitionMs(el) {
   const cs = getComputedStyle(el);
   const times = (list) => list.split(",").map((t) => {
@@ -318,7 +408,7 @@ function usePresence(open, root, panel) {
 function useDialog(active, { root, panel, body }, onClose) {
   const parent = useContext(DialogScope);
   const [scope] = useState(() => ({ parent }));
-  const close = useRef(onClose);
+  const close = useRef2(onClose);
   useIsoLayoutEffect(() => {
     close.current = onClose;
   });
@@ -342,9 +432,9 @@ function useDialog(active, { root, panel, body }, onClose) {
 // src/Modal.tsx
 import { jsx as jsx6, jsxs as jsxs4 } from "react/jsx-runtime";
 function Modal({ open, title, onClose, footer, children }) {
-  const root = useRef2(null);
-  const panel = useRef2(null);
-  const body = useRef2(null);
+  const root = useRef3(null);
+  const panel = useRef3(null);
+  const body = useRef3(null);
   const { mounted, shown } = usePresence(open, root, panel);
   const scope = useDialog(shown, { root, panel, body }, onClose);
   if (!mounted) return null;
@@ -362,7 +452,7 @@ function Modal({ open, title, onClose, footer, children }) {
 }
 
 // src/Drawer.tsx
-import { useId as useId2, useRef as useRef3 } from "react";
+import { useId as useId2, useRef as useRef4 } from "react";
 import { createPortal as createPortal2 } from "react-dom";
 import { jsx as jsx7, jsxs as jsxs5 } from "react/jsx-runtime";
 function Drawer({
@@ -375,9 +465,9 @@ function Drawer({
   children,
   closeLabel = "Close"
 }) {
-  const root = useRef3(null);
-  const panel = useRef3(null);
-  const body = useRef3(null);
+  const root = useRef4(null);
+  const panel = useRef4(null);
+  const body = useRef4(null);
   const titleId = useId2();
   const { mounted, shown } = usePresence(open, root, panel);
   const scope = useDialog(shown, { root, panel, body }, onClose);
@@ -411,7 +501,7 @@ function Drawer({
 }
 
 // src/CommandPalette.tsx
-import { useCallback, useEffect as useEffect2, useId as useId3, useMemo, useRef as useRef4, useState as useState2 } from "react";
+import { useCallback, useEffect as useEffect2, useId as useId3, useMemo, useRef as useRef5, useState as useState2 } from "react";
 import { createPortal as createPortal3 } from "react-dom";
 import { rankGroups, icon as icon2 } from "@apliteni/apliteni-ui";
 import { jsx as jsx8, jsxs as jsxs6 } from "react/jsx-runtime";
@@ -432,9 +522,9 @@ function CommandPalette({
   onQueryChange
 }) {
   const uid = useId3().replace(/:/g, "");
-  const root = useRef4(null);
-  const panel = useRef4(null);
-  const search = useRef4(null);
+  const root = useRef5(null);
+  const panel = useRef5(null);
+  const search = useRef5(null);
   const [query, setQuery] = useState2("");
   const [at, setAt] = useState2(0);
   useEffect2(() => {
@@ -608,7 +698,7 @@ import { useMemo as useMemo2, useState as useState4 } from "react";
 import { DEFAULT_PAGE_SIZE as DEFAULT_PAGE_SIZE2 } from "@apliteni/apliteni-ui";
 
 // src/Pagination.tsx
-import { useEffect as useEffect3, useId as useId4, useRef as useRef5, useState as useState3 } from "react";
+import { useEffect as useEffect3, useId as useId4, useRef as useRef6, useState as useState3 } from "react";
 import { DEFAULT_PAGE_SIZE } from "@apliteni/apliteni-ui";
 import { jsx as jsx9, jsxs as jsxs7 } from "react/jsx-runtime";
 var GHOST_SM = "ui-btn ui-btn--ghost ui-btn--sm";
@@ -655,8 +745,8 @@ function Pagination({
   const auto = useId4();
   const [draft, setDraft] = useState3("");
   const [drafting, setDrafting] = useState3(false);
-  const nav = useRef5(null);
-  const pressed = useRef5(null);
+  const nav = useRef6(null);
+  const pressed = useRef6(null);
   const uid = id ?? auto;
   const kind = VARIANTS.includes(variant) ? variant : "steps";
   const size = sizeOf(pageSize, DEFAULT_PAGE_SIZE);
@@ -1081,7 +1171,7 @@ import {
   useCallback as useCallback2,
   useEffect as useEffect4,
   useId as useId5,
-  useRef as useRef6,
+  useRef as useRef7,
   useState as useState5
 } from "react";
 import { icon as icon3, dropdownMatch, dropdownFiltering } from "@apliteni/apliteni-ui";
@@ -1142,19 +1232,19 @@ function Dropdown({
   const [pick, setPick] = useState5(null);
   const [query, setQuery] = useState5(() => search && search !== true ? search.query || "" : "");
   const [activeKey, setActiveKey] = useState5(null);
-  const root = useRef6(null);
-  const panel = useRef6(null);
-  const trigger = useRef6(null);
-  const field = useRef6(null);
-  const landOn = useRef6(null);
-  const at = useRef6("");
+  const root = useRef7(null);
+  const panel = useRef7(null);
+  const trigger = useRef7(null);
+  const field = useRef7(null);
+  const landOn = useRef7(null);
+  const at = useRef7("");
   const auto = useId5().replace(/:/g, "");
   const uid = id ?? auto;
   const setOpen = useCallback2((next) => {
     if (openProp === void 0) setSelfOpen(next);
     onOpenChange?.(next);
   }, [openProp, onOpenChange]);
-  const close = useRef6(setOpen);
+  const close = useRef7(setOpen);
   useIsoLayoutEffect(() => {
     close.current = setOpen;
   });
@@ -1561,16 +1651,16 @@ function Segmented({ options, value, onChange, label, appearance = "pill", disab
 }
 
 // src/FilterBar.tsx
-import { useLayoutEffect as useLayoutEffect2, useRef as useRef7 } from "react";
+import { useLayoutEffect as useLayoutEffect3, useRef as useRef8 } from "react";
 import { filterBar, initFilterBar } from "@apliteni/apliteni-ui";
 import { jsx as jsx16 } from "react/jsx-runtime";
 function FilterBar(props) {
-  const host = useRef7(null);
-  const latest = useRef7(props);
+  const host = useRef8(null);
+  const latest = useRef8(props);
   latest.current = props;
-  const controller = useRef7(null);
-  const initial = useRef7({ __html: filterBar(props) });
-  useLayoutEffect2(() => {
+  const controller = useRef8(null);
+  const initial = useRef8({ __html: filterBar(props) });
+  useLayoutEffect3(() => {
     const el = host.current;
     controller.current = initFilterBar(el, latest.current);
     const remove = (e) => latest.current.onRemove(e.detail.id);
@@ -1589,7 +1679,7 @@ function FilterBar(props) {
       el.removeEventListener("ui-filter-change", change);
     };
   }, []);
-  useLayoutEffect2(() => {
+  useLayoutEffect3(() => {
     controller.current?.update(props);
   }, [props.filters, props.label, props.clearLabel, props.disabled, props.busy]);
   return /* @__PURE__ */ jsx16("div", { ref: host, dangerouslySetInnerHTML: initial.current });

package/src/components/button-busy.js

@@ -0,0 +1,69 @@
+const disabledBeforeBusy = new WeakMap();
+const wired = new WeakSet();
+
+function wireActivationGuard(element) {
+  if (wired.has(element)) return;
+  const block = event => {
+    if (element.getAttribute('aria-busy') !== 'true') return;
+    if (event.type !== 'click' && event.key !== 'Enter' && event.key !== ' ') return;
+    event.preventDefault();
+    event.stopImmediatePropagation();
+  };
+  for (const type of ['click', 'keydown', 'keyup']) element.addEventListener(type, block, true);
+  element.setAttribute('data-btn-wired', '');
+  wired.add(element);
+}
+
+/** Update a factory button in place, preserving its icons and prior disabled state. */
+export function setButtonBusy(element, { busy } = {}) {
+  wireActivationGuard(element);
+  const wasBusy = element.getAttribute('aria-busy') === 'true';
+  if ((busy || wasBusy) && !disabledBeforeBusy.has(element)) disabledBeforeBusy.set(element, {
+    disabled: wasBusy ? element.hasAttribute('data-btn-disabled') : element.hasAttribute('disabled'),
+    ariaDisabled: wasBusy && !element.hasAttribute('data-btn-disabled') ? null : element.getAttribute('aria-disabled'),
+  });
+  if (busy) {
+    element.removeAttribute('data-btn-ready');
+    element.setAttribute('aria-busy', 'true');
+    element.toggleAttribute('disabled', disabledBeforeBusy.get(element).disabled);
+    element.setAttribute('aria-disabled', 'true');
+    if (!element.querySelector('.ui-btn__dots')) {
+      const dots = element.ownerDocument.createElement('span');
+      dots.className = 'ui-btn__dots';
+      dots.setAttribute('aria-hidden', 'true');
+      dots.innerHTML = '<i></i><i></i><i></i>';
+      element.append(dots);
+    }
+  } else if (wasBusy) {
+    element.setAttribute('data-btn-ready', '');
+    element.removeAttribute('aria-busy');
+    element.querySelector('.ui-btn__dots')?.remove();
+    const prior = disabledBeforeBusy.get(element);
+    element.toggleAttribute('disabled', prior?.disabled ?? false);
+    if (prior?.ariaDisabled != null) element.setAttribute('aria-disabled', prior.ariaDisabled);
+    else element.removeAttribute('aria-disabled');
+    disabledBeforeBusy.delete(element);
+  }
+  if (busy || wasBusy) {
+    let status = element.nextElementSibling;
+    if (!status?.classList.contains('ui-btn__status')) {
+      status = element.ownerDocument.createElement('span');
+      status.className = 'ui-sr ui-btn__status';
+      status.setAttribute('role', 'status');
+      status.setAttribute('aria-live', 'polite');
+      element.after(status);
+      // Register the empty live region before its first text update.
+      setTimeout(() => {
+        status.textContent = messageFor(element);
+      }, 0);
+    } else {
+      const message = messageFor(element);
+      if (status.textContent !== message) status.textContent = message;
+    }
+  }
+}
+
+function messageFor(element) {
+  const name = element.querySelector('.ui-btn__label')?.textContent ?? element.getAttribute('aria-label') ?? 'Button';
+  return `${name}: ${element.getAttribute('aria-busy') === 'true' ? 'in progress' : 'complete'}`;
+}

package/src/components/index.js

@@ -31,16 +31,17 @@ export function button({
     block && 'ui-btn--block',
     iconOnly && 'ui-btn--icon',
   );
-  const bars = busy ? '<span class="ui-btn__bars"><i></i><i></i></span>' : '';
+  const dots = busy ? '<span class="ui-btn__dots" aria-hidden="true"><i></i><i></i><i></i></span>' : '';
   const lead = iconSvg || (ic ? icon(ic) : '');
-  const inner = `${lead}${iconOnly ? '' : `<span>${esc(label)}</span>`}${iconRight ? icon(iconRight) : ''}${bars}`;
-  // busy ⇒ disabled (not clickable while it works)
+  const inner = `${lead}${iconOnly ? '' : `<span class="ui-btn__label-slot"><span class="ui-btn__label">${esc(label)}</span></span>`}${iconRight ? icon(iconRight) : ''}${dots}`;
+  // Static busy ⇒ disabled; setButtonBusy wires focus-preserving activation guards.
   const name = String(label == null ? '' : label).trim() || ic || 'Button';
   const named = iconOnly ? ` aria-label="${esc(name)}" title="${esc(name)}"` : '';
-  const attrs = `class="${cls}"${disabled || busy ? ' disabled aria-disabled="true"' : ''}${busy ? ' aria-busy="true"' : ''}${named}`;
-  return href
+  const attrs = `class="${cls}"${disabled || busy ? ' disabled aria-disabled="true"' : ''}${busy ? ' aria-busy="true"' : ''}${disabled && busy ? ' data-btn-disabled' : ''}${named}`;
+  const control = href
     ? `<a href="${href}" ${attrs}>${inner}</a>`
     : `<button type="${type}" ${attrs}>${inner}</button>`;
+  return busy ? `${control}<span class="ui-sr ui-btn__status" role="status" aria-live="polite"></span>` : control;
 }
 
 // ---- Badge / Pill --------------------------------------------------------

package/src/index.js

@@ -21,6 +21,7 @@ export * from './components/stat.js';
 export * from './assets/icons.js';
 export * from './assets/brand.js';
 export * from './motion.js';
+export { setButtonBusy } from './components/button-busy.js';
 
 export * from './components/table-values.js';
 export * from './components/segmented.js';

package/src/styles/button.css

@@ -79,9 +79,9 @@
 .ui-btn--lg { --btn-pad-y: 13px; --btn-pad-x: 24px; --btn-font: var(--text-md); border-radius: var(--radius-md); }
 
 /* Icon-only */
-.ui-btn--icon { padding: 9px; border-radius: var(--radius-sm); }
-.ui-btn--icon.ui-btn--xs { padding: 4.5px; }
-.ui-btn--icon.ui-btn--sm { padding: 6px; }
+.ui-btn--icon { --btn-pad-y: 9px; padding: 9px; border-radius: var(--radius-sm); }
+.ui-btn--icon.ui-btn--xs { --btn-pad-y: 4.5px; padding: 4.5px; }
+.ui-btn--icon.ui-btn--sm { --btn-pad-y: 6px; padding: 6px; }
 
 .ui-btn--block { width: 100%; }
 
@@ -121,60 +121,108 @@
    contrast table shows that. The box was reverted and this ink shipped.
    Held by src/styles/button-disabled.test.js. */
 
-/* Busy: keep the label, run an indeterminate accent shimmer along the base, and
-   the button is disabled (not clickable). Pass busy + the .ui-btn__bars markup.
-   The track is inset into a rounded pill so it sits INSIDE the button — not
-   flush against the clipped corners — and tints from the live --accent so it
-   reads as an intentional progress element in every theme (and mutes uniformly
-   with the button in the disabled state). */
-.ui-btn[aria-busy="true"] {
+/* why: docs/specification.md#busy-button-labels */
+.ui-btn { position: relative; }
+.ui-btn[aria-busy="true"] { pointer-events: none; }
+.ui-btn[aria-busy="true"][data-btn-wired] {
+  pointer-events: auto;
+  filter: none;
+  transform: none;
+}
+/* Busy keeps the resting variant paint. The disabled selector above owns the
+   ordinary unavailable state; a wired busy control remains focused and must
+   not flatten its action identity while work is in flight. */
+.ui-btn[aria-busy="true"],
+.ui-btn[aria-busy="true"]:hover,
+.ui-btn[aria-busy="true"]:active {
+  background: var(--surface-2); /* ring-gap: inherit — busy paint retains the button's containing gap. */
+  border-color: var(--border);
+  color: var(--text);
+  filter: none;
+  transform: none;
+}
+.ui-btn[aria-busy="true"].ui-btn--primary,
+.ui-btn[aria-busy="true"].ui-btn--primary:hover,
+.ui-btn[aria-busy="true"].ui-btn--primary:active {
+  background: var(--accent-strong); /* ring-gap: inherit — busy paint retains the button's containing gap. */
+  border-color: var(--accent-strong);
+  color: var(--accent-contrast);
+}
+.ui-btn[aria-busy="true"].ui-btn--ghost,
+.ui-btn[aria-busy="true"].ui-btn--ghost:hover,
+.ui-btn[aria-busy="true"].ui-btn--ghost:active {
+  background: transparent; /* ring-gap: inherit — busy paint retains the button's containing gap. */
+  border-color: transparent;
+  color: var(--text);
+}
+.ui-btn[aria-busy="true"].ui-btn--danger,
+.ui-btn[aria-busy="true"].ui-btn--danger:hover,
+.ui-btn[aria-busy="true"].ui-btn--danger:active {
+  background: var(--surface-2); /* ring-gap: inherit — busy paint retains the button's containing gap. */
+  border-color: var(--border);
+  color: var(--text);
+}
+/* A caller can mark a control both busy and unavailable. The explicit marker
+   keeps that ordinary disabled state from inheriting the busy variant paint. */
+.ui-btn[aria-busy="true"][data-btn-disabled] {
+  background: var(--disabled-surface); /* ring-gap: inherit — busy+disabled keeps its containing gap. */
+  border-color: var(--disabled-border);
+  /* muted-ink: state — busy+disabled control */ color: var(--disabled-ink);
+  cursor: not-allowed;
   pointer-events: none;
-  position: relative;
-  overflow: hidden;
 }
-.ui-btn__bars {
+.ui-btn--ghost[aria-busy="true"][data-btn-disabled] {
+  background: transparent; /* ring-gap: inherit — busy+disabled keeps its containing gap. */
+  border-color: transparent;
+  /* muted-ink: state — busy+disabled ghost */ color: var(--disabled-ink-bare);
+}
+.ui-btn__label-slot { display: inline-grid; overflow: hidden; }
+.ui-btn__label {
+  grid-area: 1 / 1;
+  transform: translateY(0);
+
+}
+.ui-btn[data-btn-ready] .ui-btn__label { animation: ui-btn-label-in var(--dur-med) var(--ease-out) both; }
+.ui-btn[aria-busy="true"] .ui-btn__label {
+  transform: translateY(100%);
+  animation: ui-btn-label-out var(--dur-med) var(--ease-in) both;
+}
+.ui-btn[aria-busy="true"] > svg,
+.ui-btn[aria-busy="true"] > span[aria-hidden="true"]:not(.ui-btn__dots) { visibility: hidden; }
+.ui-btn__dots {
   position: absolute;
-  left: 10px; right: 10px; bottom: 5px;
-  height: 3px;
-  border-radius: 999px;
-  background: color-mix(in srgb, var(--accent) 22%, transparent); /* ring-gap: inherit — decorative paint has no nested focus target. */
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
   overflow: hidden;
-  /* Clean entrance: grow + fade in on state change, once. */
-  transform-origin: center;
-  animation: ui-bars-in var(--dur-fast) var(--ease) both;
-}
-.ui-btn--xs .ui-btn__bars { left: 4px; right: 4px; bottom: 2px; height: 2px; }
-.ui-btn--sm .ui-btn__bars { left: 7px; right: 7px; bottom: 4px; }
-.ui-btn--lg .ui-btn__bars { left: 14px; right: 14px; bottom: 7px; }
-.ui-btn__bars i {
-  position: absolute;
-  height: 100%;
-  border-radius: 999px;
-  background: linear-gradient(90deg,
-    color-mix(in srgb, var(--accent) 30%, transparent), var(--accent));
-}
-/* On the filled primary the surface IS the accent, so shimmer in the contrast
-   colour instead — otherwise the bars vanish into the button. */
-.ui-btn--primary .ui-btn__bars {
-  background: color-mix(in srgb, var(--accent-contrast) 26%, transparent); /* ring-gap: inherit — decorative paint has no nested focus target. */
-}
-.ui-btn--primary .ui-btn__bars i {
-  background: linear-gradient(90deg,
-    color-mix(in srgb, var(--accent-contrast) 35%, transparent),
-    var(--accent-contrast));
-}
-.ui-btn__bars i:nth-child(1) { width: 38%; animation: ui-bars1 2s cubic-bezier(0.65, 0.05, 0.35, 1) infinite; } /* motion: ambient — an indeterminate loader loops until the work returns; its period is not a response time */
-.ui-btn__bars i:nth-child(2) { width: 22%; animation: ui-bars2 2s cubic-bezier(0.65, 0.05, 0.35, 1) 0.8s infinite; } /* motion: ambient — the second bar runs the same loop 0.8s out of phase */
-@keyframes ui-bars1 { 0% { left: -45%; } 100% { left: 110%; } }
-@keyframes ui-bars2 { 0% { left: -28%; } 100% { left: 120%; } }
-@keyframes ui-bars-in { from { opacity: 0; transform: scaleX(0.72); } to { opacity: 1; transform: scaleX(1); } }
-/* Reduced motion: no entrance, no sweep — just a static, intentional accent
-   fill so the busy state still reads clearly. */
+  pointer-events: none;
+}
+.ui-btn__dots i {
+  width: 5px;
+  height: 5px;
+  border-radius: 50%;
+  background: currentColor;
+  animation: ui-btn-dot-in var(--dur-med) var(--ease-out) both, ui-btn-dot-pulse 1.4s ease-in-out infinite; /* motion: ambient — dots pulse until the request completes */
+}
+.ui-btn--xs .ui-btn__dots { gap: 2px; }
+.ui-btn--xs .ui-btn__dots i { width: 3px; height: 3px; }
+.ui-btn--sm .ui-btn__dots { gap: 3px; }
+.ui-btn--sm .ui-btn__dots i { width: 4px; height: 4px; }
+.ui-btn--lg .ui-btn__dots { gap: 5px; }
+.ui-btn--lg .ui-btn__dots i { width: 6px; height: 6px; }
+.ui-btn__dots i:nth-child(2) { animation-delay: 0s, 0.2s; } /* motion: ambient — stagger the second pulse */
+.ui-btn__dots i:nth-child(3) { animation-delay: 0s, 0.4s; } /* motion: ambient — stagger the third pulse */
+@keyframes ui-btn-label-in { from { transform: translateY(100%); } to { transform: translateY(0); } }
+@keyframes ui-btn-label-out { from { transform: translateY(0); } 45%, to { transform: translateY(100%); } }
+@keyframes ui-btn-dot-in { from, 45% { translate: 0 24px; } to { translate: 0 0; } }
+@keyframes ui-btn-dot-pulse { 0%, 100% { opacity: 1; scale: 1; } 50% { opacity: 0.3; scale: 0.8; } }
 @media (prefers-reduced-motion: reduce) {
-  .ui-btn__bars { animation: none; opacity: 1; transform: none; }
-  .ui-btn__bars i { animation: none; }
-  .ui-btn__bars i:nth-child(1) { left: 0; width: 100%; }
-  .ui-btn__bars i:nth-child(2) { display: none; }
+  .ui-btn, .ui-btn__label { transition: none; }
+  .ui-btn[data-btn-ready] .ui-btn__label,
+  .ui-btn[aria-busy="true"] .ui-btn__label { animation: none; }
+  .ui-btn__dots i { animation: none; }
 }
 
 @keyframes ui-spin { to { transform: rotate(360deg); } }