@cosxai/ui 1.0.0-alpha.1 → 1.0.0-alpha.11

package/src/components/BottomSheet.tsx

@@ -0,0 +1,151 @@
+import * as DialogPrimitive from '@radix-ui/react-dialog';
+import { useCallback, useEffect, useRef, useState, type ComponentProps, type PointerEvent as ReactPointerEvent, type ReactElement, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { useReducedMotion } from './status-motion';
+
+export type BottomSheetProps = Omit<ComponentProps<typeof DialogPrimitive.Content>, 'title' | 'children' | 'ref'> & {
+  /** Says what the sheet is for ("Switch workspace", "Language"). Labels the dialog. */
+  title: ReactNode;
+  /** Keep the title for screen readers only. @default false */
+  hideTitle?: boolean | undefined;
+  /** A line under the title, read out with it. */
+  description?: ReactNode;
+  children?: ReactNode;
+  open?: boolean | undefined;
+  defaultOpen?: boolean | undefined;
+  onOpenChange?: ((open: boolean) => void) | undefined;
+  /** The element that opens it (rendered asChild). Or control `open`. */
+  trigger?: ReactElement | undefined;
+  /** Accessible name of the screen-reader close button (touch readers have no Esc). @default "Close" */
+  closeLabel?: string | undefined;
+};
+
+// A drag past this share of the sheet's height, or a flick, closes it.
+const CLOSE_SHARE = 0.25;
+const CLOSE_MAX = 120;
+const FLICK = 0.6; // px per ms
+
+/**
+ * BottomSheet — the phone's light choice: a page-coloured sheet rising from
+ * the bottom with a drag handle and a title (Metaroom Agent phone: switch
+ * workspace, language). 20px top corners over the scrim; the bottom padding
+ * clears the home indicator (safe area). Drag the handle or the title down,
+ * or flick, to close; Esc, a tap on the scrim and the screen-reader close
+ * button close it too. Built on Radix Dialog: focus moves in, is trapped and
+ * returns to the opener.
+ *
+ * Compose with: BottomTabs (the Me tab opens it), rows of 48–56px buttons
+ * inside. On desktop use Popover or DialogContent instead.
+ */
+export function BottomSheet({
+  title,
+  hideTitle = false,
+  description,
+  children,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  trigger,
+  closeLabel = 'Close',
+  className,
+  style,
+  onOpenAutoFocus,
+  ...rest
+}: BottomSheetProps) {
+  const [openState, setOpenState] = useState(defaultOpen);
+  const open = openProp ?? openState;
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (openProp === undefined) setOpenState(next);
+      onOpenChange?.(next);
+    },
+    [openProp, onOpenChange],
+  );
+
+  const reduce = useReducedMotion();
+  const sheet = useRef<HTMLDivElement | null>(null);
+  const drag = useRef<{ y0: number; t0: number } | null>(null);
+  const [dy, setDy] = useState(0);
+  const [settling, setSettling] = useState(false);
+
+  useEffect(() => {
+    if (!open) setDy(0);
+  }, [open]);
+
+  const onDown = (e: ReactPointerEvent<HTMLDivElement>) => {
+    if (e.button !== 0) return;
+    drag.current = { y0: e.clientY, t0: performance.now() };
+    setSettling(false);
+    e.currentTarget.setPointerCapture?.(e.pointerId);
+  };
+  const onMove = (e: ReactPointerEvent<HTMLDivElement>) => {
+    if (drag.current) setDy(Math.max(0, e.clientY - drag.current.y0));
+  };
+  const onUp = (e: ReactPointerEvent<HTMLDivElement>) => {
+    const d = drag.current;
+    drag.current = null;
+    if (!d) return;
+    const dist = Math.max(0, e.clientY - d.y0);
+    const speed = dist / Math.max(1, performance.now() - d.t0);
+    const height = sheet.current?.offsetHeight ?? 0;
+    const limit = height > 0 ? Math.min(CLOSE_MAX, height * CLOSE_SHARE) : CLOSE_MAX;
+    setSettling(true);
+    if (dist > limit || (dist > 8 && speed > FLICK)) setOpen(false);
+    else setDy(0);
+  };
+
+  return (
+    <DialogPrimitive.Root open={open} onOpenChange={setOpen}>
+      {trigger && <DialogPrimitive.Trigger asChild>{trigger}</DialogPrimitive.Trigger>}
+      <DialogPrimitive.Portal>
+        <DialogPrimitive.Overlay className="fixed inset-0 z-50 bg-scrim" />
+        <DialogPrimitive.Content
+          ref={sheet}
+          {...(description ? {} : { 'aria-describedby': undefined })}
+          onOpenAutoFocus={(e) => {
+            onOpenAutoFocus?.(e);
+            if (e.defaultPrevented) return;
+            // The sheet itself takes focus (read out by its title), not the first row.
+            e.preventDefault();
+            const el = e.currentTarget as HTMLElement | null;
+            el?.focus();
+            if (!reduce && el && typeof el.animate === 'function') {
+              el.animate([{ transform: 'translateY(100%)' }, { transform: 'translateY(0)' }], { duration: 240, easing: 'cubic-bezier(.16,1,.3,1)' });
+            }
+          }}
+          className={cn(
+            'fixed inset-x-0 bottom-0 z-50 flex max-h-[90dvh] flex-col rounded-t-[20px] bg-page px-4 pt-2 font-sans text-fg outline-none',
+            settling && !reduce && 'transition-transform duration-200 ease-out',
+            className,
+          )}
+          style={{
+            paddingBottom: 'max(30px, calc(env(safe-area-inset-bottom, 0px) + 12px))',
+            ...(dy ? { transform: `translateY(${dy}px)` } : {}),
+            ...style,
+          }}
+          {...rest}
+        >
+          <div
+            data-sheet-drag=""
+            className="flex shrink-0 cursor-grab touch-none flex-col select-none active:cursor-grabbing"
+            onPointerDown={onDown}
+            onPointerMove={onMove}
+            onPointerUp={onUp}
+            onPointerCancel={() => {
+              drag.current = null;
+              setSettling(true);
+              setDy(0);
+            }}
+          >
+            <span aria-hidden className="mb-2.5 h-1 w-9 self-center rounded-pill bg-rule" />
+            <DialogPrimitive.Title className={cn('m-0 px-1 pb-2 text-[17px] leading-[1.3] font-medium', hideTitle && 'sr-only')}>{title}</DialogPrimitive.Title>
+            {description && <DialogPrimitive.Description className="m-0 px-1 pb-2 text-small text-fg-secondary">{description}</DialogPrimitive.Description>}
+          </div>
+          <div className="flex min-h-0 flex-1 flex-col gap-0.5 overflow-y-auto">{children}</div>
+          <DialogPrimitive.Close className="sr-only">{closeLabel}</DialogPrimitive.Close>
+        </DialogPrimitive.Content>
+      </DialogPrimitive.Portal>
+    </DialogPrimitive.Root>
+  );
+}

package/src/components/BottomTabs.tsx

@@ -0,0 +1,102 @@
+import type { LucideIcon } from 'lucide-react';
+import { forwardRef, type ComponentProps, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { formatCount } from './Button';
+import { Icon } from './Icon';
+
+export type BottomTabItem = {
+  key: string;
+  /** A Lucide icon. Ignored when `avatar` is set. */
+  icon?: LucideIcon | undefined;
+  label: string;
+  /** A count on the corner; hidden at zero (and on a disabled tab), 99+ above 99. */
+  count?: number | undefined;
+  /** Not available yet: 40% opacity, aria-disabled; a press calls `onDisabledSelect`. */
+  disabled?: boolean | undefined;
+  /** Shown in place of the icon — the person's Avatar (size 24) on the Me tab. */
+  avatar?: ReactNode;
+};
+
+export type BottomTabsProps = Omit<ComponentProps<'nav'>, 'onChange' | 'children'> & {
+  items: BottomTabItem[];
+  /** The current tab's key. */
+  value: string;
+  onChange: (key: string) => void;
+  /** A disabled tab was pressed — say why (a toast: "Coming soon"). */
+  onDisabledSelect?: ((key: string) => void) | undefined;
+  /** The landmark's accessible name ("Modules"). */
+  label: string;
+};
+
+/**
+ * BottomTabs — the phone's tab bar (Metaroom Agent phone): an icon in a
+ * 48×28 pill over an 11px label; the current tab's pill takes the
+ * workspace's field colour (--brand-field), a person's avatar gets an ink
+ * ring. Tabs not built yet stay visible at 40% opacity (aria-disabled, still
+ * focusable, so a press can explain). The bottom padding clears the home
+ * indicator.
+ *
+ * Compose with: Avatar (size 24) for the Me tab, BottomSheet opened from
+ * it; AppRail is the same navigation on desktop.
+ *
+ * A nav landmark of buttons; the current one has aria-current="page".
+ * Forwards ref to the <nav>; spreads `...rest` onto it.
+ */
+export const BottomTabs = forwardRef<HTMLElement, BottomTabsProps>(function BottomTabs(
+  { items, value, onChange, onDisabledSelect, label, className, style, ...rest },
+  ref,
+) {
+  return (
+    <nav
+      ref={ref}
+      aria-label={label}
+      className={cn('flex shrink-0 border-t border-rule bg-page px-2 pt-1.5 font-sans text-fg', className)}
+      style={{ paddingBottom: 'max(22px, env(safe-area-inset-bottom, 0px))', ...style }}
+      {...rest}
+    >
+      {items.map((it) => {
+        const on = it.key === value;
+        const count = it.disabled || it.count === undefined ? null : formatCount(it.count);
+        return (
+          <button
+            key={it.key}
+            type="button"
+            aria-current={on ? 'page' : undefined}
+            aria-disabled={it.disabled || undefined}
+            aria-label={count ? `${it.label} (${count})` : undefined}
+            onClick={() => (it.disabled ? onDisabledSelect?.(it.key) : onChange(it.key))}
+            className={cn(
+              'relative flex min-h-12 flex-1 cursor-pointer flex-col items-center justify-center gap-[3px] rounded-md border-0 bg-transparent p-0 text-fg outline-none focus-visible:shadow-(--focus-ring)',
+              it.disabled && 'cursor-not-allowed opacity-40',
+            )}
+          >
+            <span
+              className={cn(
+                'grid h-7 w-12 place-items-center rounded-pill transition-colors duration-[120ms] ease-standard',
+                on && 'bg-brand-field text-ink',
+              )}
+            >
+              {it.avatar ? (
+                <span aria-hidden className={cn('inline-flex rounded-pill', on && 'shadow-[0_0_0_1.5px_var(--text-primary)]')}>
+                  {it.avatar}
+                </span>
+              ) : (
+                it.icon && <Icon icon={it.icon} size={18} />
+              )}
+            </span>
+            <span className="text-[11px] leading-none font-medium">{it.label}</span>
+            {count && (
+              <span
+                aria-hidden
+                className="absolute top-0.5 left-1/2 ml-2 h-3.5 min-w-3.5 rounded-pill bg-brand-mark px-[3px] text-center text-[9px] leading-[14px] font-bold text-ink tabular-nums"
+              >
+                {count}
+              </span>
+            )}
+          </button>
+        );
+      })}
+    </nav>
+  );
+});

package/src/components/BrandLoader.tsx

@@ -0,0 +1,122 @@
+import { useEffect, useId, useRef } from 'react';
+
+import { LOOP } from './logo-art';
+
+/**
+ * BrandLoader — the COSX loop as a loading indicator (Claude Design, COSX
+ * Loader). A short stroke runs along the loop, blooms into the full mark,
+ * holds 0.6 s, gathers back and runs again: 3.4 s a round, the head's
+ * speed continuous. At rest it is the logo itself — the fill is the logo
+ * path, the stroke only a mask over it.
+ *
+ * For whole-page and start-up waits, where the brand belongs. Buttons,
+ * rows, inputs and anything under 24 px wide keep Spinner or a skeleton.
+ * Reduced motion: the full mark, still.
+ */
+export type BrandLoaderProps = {
+  /** Width in px (height follows the mark: 106 / 202). Default 48; 24 at least. */
+  size?: number | undefined;
+  /**
+   * ink on paper and yellow; linen or accent on ink; current follows the
+   * text colour (light and dark themes alike). The mark is never yellow on paper.
+   */
+  tone?: 'ink' | 'linen' | 'accent' | 'current' | undefined;
+  /** The faint full mark under the stroke (default on), so it always reads as COSX. */
+  track?: boolean | undefined;
+  /** 1 = a 3.4 s round. */
+  speed?: number | undefined;
+  /** What is loading, for assistive tech. Default "Loading". */
+  label?: string | undefined;
+  className?: string | undefined;
+};
+
+const TONES = {
+  ink: ['#111111', 'rgba(17,17,17,.12)'],
+  linen: ['#F5F2EC', 'rgba(245,242,236,.16)'],
+  accent: ['#FFD166', 'rgba(255,209,102,.18)'],
+  current: ['currentColor', 'currentColor'],
+} as const;
+
+// The stroke's centre line: the C counter-clockwise, the diagonal, the O
+// clockwise, then back across the open gap.
+const R = 38.3;
+const LC = [96.12, 144.62] as const;
+const RC = [193.32, 144.62] as const;
+const pt = (c: readonly [number, number], deg: number) => {
+  const a = (deg * Math.PI) / 180;
+  return `${(c[0] + R * Math.cos(a)).toFixed(2)},${(c[1] + R * Math.sin(a)).toFixed(2)}`;
+};
+const CENTRE = `M${pt(LC, -42)} A${R},${R} 0 1,0 ${pt(LC, 48)} L${pt(RC, 214)} A${R},${R} 0 0,1 ${pt(RC, 34)} A${R},${R} 0 0,1 ${pt(RC, 214)} L${pt(LC, -42)} Z`;
+
+// Seconds: run, bloom, hold, gather; SEG = the running stroke's share of the loop.
+const RUN = 1.5;
+const GROW = 0.7;
+const HOLD = 0.6;
+const SHRINK = 0.6;
+const T = RUN + GROW + HOLD + SHRINK;
+const SEG = 0.14;
+const easeOut = (x: number) => 1 - (1 - x) ** 3;
+const easeInOut = (x: number) => (x < 0.5 ? 4 * x ** 3 : 1 - (-2 * x + 2) ** 3 / 2);
+
+/** Head position h (in loop lengths) and visible share s (0..1) at t seconds. */
+export function loaderState(t: number): { h: number; s: number } {
+  const c = Math.floor(t / T);
+  let u = t - c * T;
+  const base = c * (RUN + GROW / 2 + SHRINK / 2);
+  if (u < RUN) return { h: base + u, s: SEG };
+  u -= RUN;
+  if (u < GROW) {
+    const g = u / GROW;
+    return { h: base + RUN + GROW * (g - (g * g) / 2), s: SEG + (1 - SEG) * easeOut(g) };
+  }
+  u -= GROW;
+  if (u < HOLD) return { h: base + RUN + GROW / 2, s: 1 };
+  u -= HOLD;
+  const k = u / SHRINK;
+  return { h: base + RUN + GROW / 2 + (SHRINK * k * k) / 2, s: 1 - (1 - SEG) * easeInOut(k) };
+}
+
+export function BrandLoader({ size = 48, tone = 'ink', track = true, speed = 1, label = 'Loading', className }: BrandLoaderProps) {
+  const maskId = `cosx-loader-${useId().replace(/[^a-zA-Z0-9-]/g, '')}`;
+  const stroke = useRef<SVGPathElement>(null);
+  const [fill, faint] = TONES[tone];
+
+  useEffect(() => {
+    const c = stroke.current;
+    if (!c || typeof c.getTotalLength !== 'function') return undefined;
+    const L = c.getTotalLength();
+    const still = window.matchMedia?.('(prefers-reduced-motion: reduce)');
+    const t0 = performance.now();
+    let raf = 0;
+    const frame = (now: number) => {
+      const st = still?.matches ? { h: 0, s: 1 } : loaderState(((now - t0) / 1000) * speed);
+      const s = Math.min(1, st.s);
+      const tail = (((st.h - s) % 1) + 1) % 1;
+      c.setAttribute('stroke-dasharray', s >= 0.999 ? `${L} 0` : `${(s * L).toFixed(2)} ${((1 - s) * L).toFixed(2)}`);
+      c.setAttribute('stroke-dashoffset', (-tail * L).toFixed(2));
+      raf = requestAnimationFrame(frame);
+    };
+    raf = requestAnimationFrame(frame);
+    return () => cancelAnimationFrame(raf);
+  }, [speed]);
+
+  return (
+    <svg
+      role="img"
+      aria-label={label}
+      viewBox="44 92 202 106"
+      width={size}
+      height={Number(((size * 106) / 202).toFixed(1))}
+      className={className}
+      style={{ display: 'block', overflow: 'visible' }}
+    >
+      <defs>
+        <mask id={maskId} maskUnits="userSpaceOnUse" x="30" y="80" width="230" height="130">
+          <path ref={stroke} d={CENTRE} fill="none" stroke="#fff" strokeWidth="21" strokeLinecap="round" strokeLinejoin="round" />
+        </mask>
+      </defs>
+      {track && <path d={LOOP.paths[0]} fill={faint} fillOpacity={tone === 'current' ? 0.12 : undefined} />}
+      <path d={LOOP.paths[0]} fill={fill} mask={`url(#${maskId})`} />
+    </svg>
+  );
+}

package/src/components/Breadcrumb.tsx

@@ -0,0 +1,129 @@
+import * as DropdownMenu from '@radix-ui/react-dropdown-menu';
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+
+export type BreadcrumbItem = {
+  label: ReactNode;
+  /** A link; or use onSelect for in-app navigation. */
+  href?: string | undefined;
+  onSelect?: (() => void) | undefined;
+  /** A trailing tag on the current page: its format (PDF). */
+  tag?: ReactNode;
+};
+
+export type BreadcrumbProps = Omit<ComponentProps<'nav'>, 'children'> & {
+  items: BreadcrumbItem[];
+  /** What starts the trail — the workspace brand (on a customer domain it replaces the platform name). */
+  root?: ReactNode;
+  /** Beyond this many segments the middle folds into a menu. @default 4 */
+  max?: number | undefined;
+  /** @default "Breadcrumb" */
+  label?: string | undefined;
+  /** Accessible name of the fold button. @default "Show hidden folders" */
+  foldLabel?: string | undefined;
+  /** A line under the trail: the current item's status. */
+  status?: ReactNode;
+};
+
+const linkClass = 'cursor-pointer text-fg-secondary outline-none hover:text-fg hover:underline underline-offset-2 focus-visible:shadow-(--focus-ring) rounded-xs';
+
+function Crumb({ item }: { item: BreadcrumbItem }) {
+  if (item.href)
+    return (
+      <a href={item.href} onClick={item.onSelect} className={linkClass}>
+        {item.label}
+      </a>
+    );
+  if (item.onSelect)
+    return (
+      <button type="button" onClick={item.onSelect} className={linkClass}>
+        {item.label}
+      </button>
+    );
+  return <span className="text-fg-secondary">{item.label}</span>;
+}
+
+const Sep = () => (
+  <span aria-hidden className="text-fg-secondary">
+    /
+  </span>
+);
+
+/**
+ * Breadcrumb — where this page sits. The current page is the last segment
+ * and not a link; beyond four segments the middle folds into a menu. On a
+ * customer domain the trail starts at the workspace brand (root).
+ */
+export function Breadcrumb({ items, root, max = 4, label = 'Breadcrumb', foldLabel = 'Show hidden folders', status, className, ...rest }: BreadcrumbProps) {
+  const last = items[items.length - 1];
+  const before = items.slice(0, -1);
+  const total = items.length + (root ? 1 : 0);
+  const fold = total > max && before.length > 1;
+  // Folded: [root or the first ancestor] / … / parent / current.
+  const head = fold ? (root ? [] : before.slice(0, 1)) : before;
+  const folded = fold ? before.slice(root ? 0 : 1, -1) : [];
+  const tail = fold ? before.slice(-1) : [];
+  const segment = 'flex items-center gap-2';
+
+  return (
+    <nav aria-label={label} className={cn('flex flex-col gap-1.5', className)} {...rest}>
+      <ol className="m-0 flex list-none flex-wrap items-center gap-x-2 gap-y-1 p-0 text-ui">
+        {root && (
+          <li className={segment}>
+            {root}
+            {items.length > 0 && <Sep />}
+          </li>
+        )}
+        {head.map((it, i) => (
+          <li key={`h${i}`} className={segment}>
+            <Crumb item={it} />
+            <Sep />
+          </li>
+        ))}
+        {folded.length > 0 && (
+          <li className={segment}>
+            <DropdownMenu.Root>
+              <DropdownMenu.Trigger
+                aria-label={foldLabel}
+                className="inline-grid h-6 min-w-6 cursor-pointer place-items-center rounded-sm bg-sunk px-1.5 text-meta font-semibold text-fg outline-none hover:bg-well focus-visible:shadow-(--focus-ring)"
+              >
+                …
+              </DropdownMenu.Trigger>
+              <DropdownMenu.Portal>
+                <DropdownMenu.Content align="start" sideOffset={6} className="z-50 min-w-[180px] rounded-lg border border-rule bg-page p-1.5 text-ui text-fg">
+                  {folded.map((it, i) => (
+                    <DropdownMenu.Item
+                      key={i}
+                      onSelect={() => {
+                        if (it.href) window.location.assign(it.href);
+                        else it.onSelect?.();
+                      }}
+                      className="flex h-8 cursor-pointer items-center rounded-md px-2.5 outline-none data-[highlighted]:bg-hover"
+                    >
+                      {it.label}
+                    </DropdownMenu.Item>
+                  ))}
+                </DropdownMenu.Content>
+              </DropdownMenu.Portal>
+            </DropdownMenu.Root>
+            <Sep />
+          </li>
+        )}
+        {tail.map((it, i) => (
+          <li key={`t${i}`} className={segment}>
+            <Crumb item={it} />
+            <Sep />
+          </li>
+        ))}
+        {last && (
+          <li aria-current="page" className="flex items-center gap-2 font-medium text-fg">
+            {last.label}
+            {last.tag && <span className="rounded-sm bg-sunk px-1.5 py-0.5 text-[11px] font-semibold text-fg">{last.tag}</span>}
+          </li>
+        )}
+      </ol>
+      {status && <div className="text-meta text-fg-secondary">{status}</div>}
+    </nav>
+  );
+}

package/src/components/Button.tsx

@@ -1,7 +1,7 @@
 import { Slot } from '@radix-ui/react-slot';
 import { cva } from 'class-variance-authority';
 import { Check } from 'lucide-react';
-import { useLayoutEffect, useRef, useState, type ComponentProps, type ReactNode } from 'react';
+import type { ComponentProps, ReactNode } from 'react';
 
 import { cn } from '../lib/cn';
 import { Spinner } from './Spinner';
@@ -17,7 +17,9 @@ const button = cva(
     'rounded-md border border-transparent font-sans font-semibold leading-none',
     'transition-[background-color,border-color,color] duration-[120ms] ease-standard',
     'cursor-pointer outline-none focus-visible:shadow-(--focus-ring)',
-    'disabled:cursor-not-allowed disabled:opacity-40 aria-disabled:cursor-not-allowed aria-disabled:opacity-40',
+    // Disabled sinks: the well with grey text (3.0 readme and design.cosx.co;
+    // the 3.0 Button source used opacity). "!" so hover never lifts it back.
+    'disabled:cursor-not-allowed aria-disabled:cursor-not-allowed',
   ],
   {
     variants: {
@@ -45,6 +47,17 @@ const button = cva(
       // Focus ring follows the ground.
       { ground: 'yellow', class: 'focus-visible:shadow-[0_0_0_3px_var(--yellow),0_0_0_5px_var(--ink)]' },
       { ground: 'ink', class: 'focus-visible:shadow-[0_0_0_3px_var(--ink),0_0_0_5px_var(--yellow)]' },
+      // Disabled: filled types sink into the well; outlined and text-only turn grey.
+      {
+        variant: ['primary', 'yellow', 'ink', 'danger'],
+        class:
+          'disabled:border-transparent! disabled:bg-well! disabled:text-fg-secondary! aria-disabled:border-transparent! aria-disabled:bg-well! aria-disabled:text-fg-secondary!',
+      },
+      {
+        variant: ['secondary', 'ghost'],
+        class:
+          'disabled:bg-transparent! disabled:text-fg-secondary! aria-disabled:bg-transparent! aria-disabled:text-fg-secondary! disabled:hover:border-[rgba(17,17,17,.18)] aria-disabled:hover:border-[rgba(17,17,17,.18)]',
+      },
     ],
     defaultVariants: { size: 'md', variant: 'primary', ground: 'auto' },
   },
@@ -63,7 +76,7 @@ export type ButtonProps = Omit<ComponentProps<'button'>, 'disabled'> & {
   shortcut?: string | undefined;
   /** A count at the end (Comments 12). Hidden at zero, 99+ above 99. */
   count?: number | undefined;
-  /** Async state: busy locks the width and shows a spinner; done confirms in place. See useButtonAction. */
+  /** Async state: busy shows a spinner, done confirms in place; the width never changes. See useButtonAction. */
   state?: ButtonState | undefined;
   /** Label shown while state="done". @default the children */
   doneLabel?: ReactNode;
@@ -106,15 +119,6 @@ export function Button({
   ref,
   ...rest
 }: ButtonProps) {
-  const inner = useRef<HTMLButtonElement | null>(null);
-  const [lockedWidth, setLockedWidth] = useState<number | null>(null);
-
-  // Lock the idle width so busy / done never resize the button.
-  useLayoutEffect(() => {
-    if (state === 'idle') setLockedWidth(null);
-    else if (lockedWidth === null && inner.current) setLockedWidth(inner.current.getBoundingClientRect().width);
-  }, [state, lockedWidth]);
-
   const classes = cn(button({ variant, size, ground: ground ?? 'auto' }), className);
   if (asChild) {
     return (
@@ -125,23 +129,22 @@ export function Button({
   }
 
   const busy = state === 'busy';
+  // Busy and done keep the idle content in place (hidden) and draw on top of
+  // it, so the button never resizes — also when it first renders busy.
+  const overlaid = state !== 'idle';
   const blocked = Boolean(disabledReason) && disabled;
   const shownCount = count === undefined ? null : formatCount(count);
-  const setRefs = (el: HTMLButtonElement | null) => {
-    inner.current = el;
-    if (typeof ref === 'function') ref(el);
-    else if (ref) ref.current = el;
-  };
-
   return (
     <button
       type="button"
       {...rest}
-      ref={setRefs}
+      ref={ref}
       className={classes}
-      style={lockedWidth ? { ...style, width: lockedWidth } : style}
+      style={style}
       disabled={disabled && !disabledReason ? true : undefined}
-      aria-disabled={blocked || busy ? true : undefined}
+      // Busy is not disabled (spec: "busy and disabled are different states"):
+      // it keeps its look; aria-busy says so and repeat clicks are ignored below.
+      aria-disabled={blocked ? true : undefined}
       aria-busy={busy || undefined}
       title={blocked ? disabledReason : rest.title}
       onClick={(e) => {
@@ -152,27 +155,32 @@ export function Button({
         onClick?.(e);
       }}
     >
-      {busy ? (
-        <Spinner />
-      ) : state === 'done' ? (
-        <>
-          <Check size={14} strokeWidth={2} aria-hidden />
-          {doneLabel ?? children}
-        </>
-      ) : (
-        <>
-          {iconLeft}
-          {children}
-          {iconRight}
-          {shownCount && <span className="font-medium tabular-nums opacity-70">{shownCount}</span>}
-          {shortcut && (
-            <kbd className="ml-0.5 font-sans text-[12px] font-medium opacity-60" aria-hidden>
-              {shortcut}
-            </kbd>
+      <span className={cn('contents', overlaid && 'invisible')} aria-hidden={overlaid || undefined} data-button-content="">
+        {iconLeft}
+        {children}
+        {iconRight}
+        {shownCount && <span className="font-medium tabular-nums opacity-70">{shownCount}</span>}
+        {shortcut && (
+          <kbd className="ml-0.5 font-sans text-[12px] font-medium opacity-60" aria-hidden>
+            {shortcut}
+          </kbd>
+        )}
+      </span>
+      {overlaid && (
+        <span className="absolute inset-0 flex items-center justify-center gap-2" data-button-overlay="">
+          {busy ? (
+            <>
+              <Spinner />
+              <span className="sr-only">{children}</span>
+            </>
+          ) : (
+            <>
+              <Check size={14} strokeWidth={2} aria-hidden />
+              {doneLabel ?? children}
+            </>
           )}
-        </>
+        </span>
       )}
-      {busy && <span className="sr-only">{children}</span>}
     </button>
   );
 }