@justanarthur/modo-ui 0.5.0 → 0.6.0-canary.0

package/components/button/examples.mdx

@@ -0,0 +1,164 @@
+import Button, { buttonVariants } from './index'
+import LoadingDemo from './loading-demo'
+import { ArrowRight, Check, ChevronDown, Loader, Plus, RotateCcw, Search, Settings, Trash2 } from 'lucide-react'
+
+# Variants
+
+4 variants, inline or full width: add `className="w-full"` to stretch one
+to its container.
+
+<div className="flex w-fit max-w-full flex-col gap-8">
+  <div className="flex items-center gap-2">
+    <Button variant="primary">Primary</Button>
+    <Button variant="secondary">Secondary</Button>
+    <Button variant="tertiary">Tertiary</Button>
+    <Button variant="ghost">Ghost</Button>
+  </div>
+  <div className="flex flex-col gap-2">
+    <Button variant="primary" className="w-full">Primary</Button>
+    <Button variant="secondary" className="w-full">Secondary</Button>
+    <Button variant="tertiary" className="w-full">Tertiary</Button>
+    <Button variant="ghost" className="w-full">Ghost</Button>
+  </div>
+</div>
+
+# Destructive and success
+
+A status as an action: its hue as the label on a wash of itself, deepening on
+hover and press. Never a solid fill, so the view keeps one primary.
+
+<div className="flex flex-wrap items-center gap-2">
+  <Button variant="destructive" leadingIcon={Trash2}>Delete</Button>
+  <Button variant="success" leadingIcon={Check}>Approve</Button>
+  <Button variant="destructive" size="compact">Remove</Button>
+  <Button variant="success" size="compact">Accept</Button>
+</div>
+
+# Outline and link
+
+`outline` is `tertiary` under its shadcn name. `link` is text on the control
+height: its underline fades in on hover, so the label never moves, and it
+lines up with the buttons beside it.
+
+<div className="flex flex-wrap items-center gap-2">
+  <Button variant="outline">Outline</Button>
+  <Button variant="link">Forgot password?</Button>
+  <Button variant="link" trailingIcon={ArrowRight}>View all</Button>
+</div>
+
+# With Icons
+
+`leadingIcon` and `trailingIcon` take an icon component; it sits 4px
+closer to its edge than the label would.
+
+<div className="flex flex-wrap items-center gap-2">
+  <Button leadingIcon={Plus}>Create</Button>
+  <Button variant="secondary" trailingIcon={ArrowRight}>Next</Button>
+  <Button variant="tertiary" leadingIcon={Search} trailingIcon={ArrowRight}>
+    Search
+  </Button>
+</div>
+
+# Loading & Disabled
+
+`loading` folds the surface into a circle around a spinner and disables
+the button; the hidden label keeps its width.
+
+<div className="flex flex-wrap items-center gap-2">
+  <Button loading>Loading</Button>
+  <Button variant="secondary" loading leadingIcon={Loader}>Saving</Button>
+  <Button disabled>Disabled</Button>
+</div>
+
+# Loading morph
+
+Press one. The surface folds into a circle around the spinner while the
+button keeps its box, so its neighbors never move, and springs back when
+loading ends. It keeps focus while it loads (`aria-disabled`, not
+`disabled`), so press one with Enter and focus is still there when it is
+done; presses in between are ignored. `LoadingDemo` is a docs stage: a
+Button whose `loading` holds for two seconds after a press.
+
+<div className="flex w-fit max-w-full flex-col gap-3">
+  <div className="flex flex-wrap items-center gap-2">
+    <LoadingDemo leadingIcon={Check}>Save</LoadingDemo>
+    <LoadingDemo variant="secondary">Publish</LoadingDemo>
+    <LoadingDemo variant="tertiary" trailingIcon={ArrowRight}>Next</LoadingDemo>
+    <LoadingDemo variant="secondary" size="icon" aria-label="Refresh">
+      <RotateCcw />
+    </LoadingDemo>
+  </div>
+  <LoadingDemo className="w-full">Create account</LoadingDemo>
+</div>
+
+# Sizes
+
+The size ladder: `default` (36px) and `compact` (28px), plus square
+icon-only steps. There is no third height: `xs` and `sm` resolve to `compact`. Icon-only buttons take the icon as their child and need
+an `aria-label`.
+
+<div className="flex flex-col gap-3">
+  <div className="flex flex-wrap items-center gap-2">
+    <Button leadingIcon={Plus}>Default</Button>
+    <Button variant="secondary" size="icon" aria-label="Add">
+      <Plus />
+    </Button>
+    <Button variant="ghost" size="icon" aria-label="Settings">
+      <Settings />
+    </Button>
+  </div>
+  <div className="flex flex-wrap items-center gap-2">
+    <Button size="compact" leadingIcon={Plus}>Compact</Button>
+    <Button variant="secondary" size="icon-compact" aria-label="Add">
+      <Plus />
+    </Button>
+    <Button variant="ghost" size="icon-compact" aria-label="Settings">
+      <Settings />
+    </Button>
+  </div>
+</div>
+
+# Active
+
+`active` forces the pressed visual — for a button whose dropdown or
+popover is currently open.
+
+<div className="flex flex-wrap items-center gap-2">
+  <Button active>Primary</Button>
+  <Button variant="secondary" active>Secondary</Button>
+  <Button variant="tertiary" active trailingIcon={ChevronDown}>Tertiary</Button>
+  <Button variant="ghost" active>Ghost</Button>
+</div>
+
+# As child
+
+`asChild` merges the button's styling onto its single child element —
+here a link — instead of rendering a `<button>`.
+
+<Button asChild variant="tertiary" trailingIcon={ArrowRight}>
+  <a href="https://www.fluidfunctionalism.com" target="_blank" rel="noreferrer">
+    Fluid Functionalism
+  </a>
+</Button>
+
+# Surface classes
+
+For an element you can't render through `asChild` (a router's link that
+builds its own anchor, markup from a server template), `buttonVariants`
+with `surface: true` draws the fill, ring, hover, press and focus ring on
+the element itself. Without `surface` it returns only the root classes, and
+the fill lives on the Button's inner layer. It is static: no press shrink,
+no loading morph, so prefer `<Button asChild>` where you can. Size aliases
+(`sm`, `lg`, `icon-sm`, …) resolve as on the Button; `aria-disabled` dims it.
+
+<div className="flex flex-wrap items-center gap-2">
+  <a href="#surface-classes" className={buttonVariants({ surface: true })}>Primary</a>
+  <a href="#surface-classes" className={buttonVariants({ variant: 'secondary', surface: true })}>Secondary</a>
+  <a href="#surface-classes" className={buttonVariants({ variant: 'outline', surface: true })}>Outline</a>
+  <a href="#surface-classes" className={buttonVariants({ variant: 'ghost', surface: true })}>Ghost</a>
+  <a href="#surface-classes" className={buttonVariants({ variant: 'destructive', size: 'sm', surface: true })}>Remove</a>
+  <a href="#surface-classes" className={buttonVariants({ variant: 'secondary', size: 'icon-sm', surface: true })} aria-label="Add">
+    <Plus />
+  </a>
+  <a href="#surface-classes" aria-disabled="true" className={buttonVariants({ variant: 'secondary', surface: true })}>Disabled</a>
+</div>

package/components/button/index.tsx

@@ -0,0 +1,416 @@
+// biome-ignore-all lint: vendored upstream code keeps its own patterns (see the header)
+/*
+ * Ported from Fluid Functionalism — github.com/mickadesign/fluid-functionalism
+ * `registry/base/button.tsx` @ b3587bdbd83fc66c2a6aae3817ffb856cb09260b
+ * MIT License © 2026 Micka Touillaud — fluidfunctionalism.com (notice: LICENSE.fluid-functionalism)
+ * Local modifications:
+ * - `"use client"` directive dropped (no RSC here).
+ * - `@/lib/{icon-context,utils,shape-context,size-context}` imports rewritten to `../../lib/*`.
+ * - `ButtonProps`: `variant`, `disabled` and `children` re-declared in the interface body (modo's
+ *   parser lists only members declared there); member docs replaced by the FF docs API-table text
+ *   (upstream's size-alias and `active` notes folded in).
+ * - modo item: TSDoc (from the FF "Button" docs page, plus Sizes / Active / As child examples for
+ *   the API-table props the page has no section for) and a default export.
+ * - Also the modo docs-chrome Button (`modo.config.ts` shell.Button): the chrome renders its
+ *   icon buttons as `<Button variant="ghost" size="icon-sm">`, served by upstream's legacy
+ *   `icon-sm` → `icon-compact` alias.
+ * - Styling reads DS tokens (AGENTS.md styling): `text-[Npx]` →
+ *   `text-<role>[-compact]`; the hex focus-ring fallback →
+ *   `ring-focus-ring` / `border-focus-ring`; `duration-80|120|160` and
+ *   tier-length JS durations → `duration-<tier>` / `spring.*`.
+ * - `loading` morphs (local, in the morph layer's language): the surface layer contracts into
+ *   a circle around the spinner on `spring.moderate` and springs back when loading ends, while
+ *   the button's own box keeps its size; the label and the spinner crossfade instead of
+ *   swapping. The spinner centres on the button, not on the label. `aria-busy` while loading.
+ *   The root's `transition-colors` → `transition-[color,opacity]`, so the disabled dim fades
+ *   in step instead of jumping (the root draws no background or border of its own).
+ *   A loading button stays focusable (Base UI's `focusableWhenDisabled`, so
+ *   `aria-disabled`, not `disabled`) and ignores presses; with `asChild` it
+ *   sets `aria-disabled` and swallows clicks itself.
+ * - `buttonVariants` and the size aliases moved to `variants.ts` (server-callable, no
+ *   JSX or hooks) and re-exported from here; it resolves the size aliases itself and
+ *   takes `surface` (the fill as root classes, for an anchor host; see `variants.ts`).
+ * - Variants added for hosts with a shadcn-style API (local, under DESIGN.md): `outline`
+ *   renders exactly as `tertiary` (both are the transparent 1px-ring button);
+ *   `destructive` and `success` are their hue as text (`--destructive-strong`,
+ *   `--success-strong`) on a translucent wash of it that deepens on hover and press,
+ *   never a solid fill; `link` is foreground text on the control height with no padding,
+ *   whose always-drawn underline fades in on hover (and shows while `active`). Size `xs`
+ *   resolves to `compact`: the ladder has two steps.
+ */
+
+import { Button as ButtonPrimitive } from '@base-ui/react/button'
+import type { VariantProps } from 'class-variance-authority'
+import { AnimatePresence, animate, motion, useMotionValue } from 'motion/react'
+import {
+  type ButtonHTMLAttributes,
+  cloneElement,
+  forwardRef,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+  useLayoutEffect,
+  useRef,
+} from 'react'
+import type { IconComponent } from '../../lib/icon-context'
+import { useReduceMotion } from '../../lib/reduced-motion'
+import { useShape } from '../../lib/shape-context'
+import { useSizeVariant } from '../../lib/size-context'
+import { spring } from '../../lib/springs'
+import { cn } from '../../lib/utils'
+import {
+  type ButtonSize,
+  type ButtonSizeCanonical,
+  type ButtonVariant,
+  buttonVariants,
+  legacySizeAliases,
+} from './variants'
+
+interface ButtonProps
+  extends ButtonHTMLAttributes<HTMLButtonElement>,
+    Omit<VariantProps<typeof buttonVariants>, 'size' | 'surface'> {
+  /** Visual style of the button. `outline` is `tertiary` under its shadcn name; `destructive` and `success` tint the label and a wash of their hue; `link` is underlined text on the control height. Defaults to `"primary"`. */
+  variant?: 'primary' | 'secondary' | 'tertiary' | 'outline' | 'ghost' | 'destructive' | 'success' | 'link'
+  /** Step on the size ladder (36px default, 28px compact — see Sizes): `"default"` | `"compact"` | `"icon"` | `"icon-compact"`. Omitted, the button follows the surrounding SizeProvider. Aliases resolve onto the ladder (xs, sm → compact; md/lg → default; icon-sm → icon-compact; icon-lg → icon). */
+  size?: 'default' | 'compact' | 'icon' | 'icon-compact' | 'xs' | 'sm' | 'md' | 'lg' | 'icon-sm' | 'icon-lg'
+  /** Merge props onto the child element instead of rendering a `<button>` — the single React-element child becomes the rendered element (slot-style). Defaults to `false`. */
+  asChild?: boolean
+  /** Folds the button into a circle around a spinner and blocks presses; the button keeps its box, so nothing around it moves, and keeps focus (`aria-disabled`, not `disabled`). Defaults to `false`. */
+  loading?: boolean
+  /** Icon displayed before the label. */
+  leadingIcon?: IconComponent
+  /** Icon displayed after the label. */
+  trailingIcon?: IconComponent
+  /** Forces the pressed/held visual — e.g. while a dropdown or popover the button opened is showing. Defaults to `false`. */
+  active?: boolean
+  /** Disables the button. Defaults to `false`. */
+  disabled?: boolean
+  /** The label. With `size="icon"` / `"icon-compact"`, the icon itself (give the button an `aria-label`). */
+  children?: ReactNode
+}
+
+/* Press effect: the surface layer sits 1px inside the button and a
+   same-color box-shadow spread fills it back out to the full bounds.
+   Pressing collapses the spread, shrinking the surface by exactly 1px per
+   side at any width — a scale would warp (2% of a 400px button is 8px
+   sideways but under 1px vertically). Fill colors are opaque color-mix()es
+   rather than alpha so the fill and its spread ring never seam. */
+const bgVariants: Record<string, string> = {
+  primary:
+    '[--btn-bg:var(--foreground)] group-hover:[--btn-bg:color-mix(in_oklab,var(--foreground)_90%,var(--background))] group-active:[--btn-bg:color-mix(in_oklab,var(--foreground)_80%,var(--background))] bg-[var(--btn-bg)] shadow-[0_0_0_1px_var(--btn-bg)] group-active:shadow-[0_0_0_0px_var(--btn-bg)]',
+  secondary:
+    '[--btn-bg:var(--accent)] group-hover:[--btn-bg:color-mix(in_oklab,var(--accent)_80%,var(--background))] group-active:[--btn-bg:var(--accent)] bg-[var(--btn-bg)] shadow-[0_0_0_1px_var(--btn-bg)] group-active:shadow-[0_0_0_0px_var(--btn-bg)]',
+  // The border ring is an outer 1px shadow at rest that hands off to an
+  // inset 1px shadow when pressed, so the ring moves inward with the
+  // surface. The translucent fill only ever reaches the ring's inner edge
+  // (exactly the surface box), so it needs no spread of its own.
+  tertiary:
+    'bg-transparent shadow-[0_0_0_1px_var(--border),inset_0_0_0_0px_var(--border)] group-hover:bg-hover group-active:bg-active group-active:shadow-[0_0_0_0px_var(--border),inset_0_0_0_1px_var(--border)]',
+  // Translucent fill + same-color spread never double up: outer shadows
+  // render only outside the surface box.
+  ghost:
+    'bg-transparent shadow-[0_0_0_1px_transparent] group-hover:bg-hover group-hover:shadow-[0_0_0_1px_var(--hover)] group-active:bg-active group-active:shadow-[0_0_0_0px_var(--active)]',
+  // A status as an action: a translucent wash of its hue (the ghost recipe),
+  // deepening on hover and press.
+  // The fill reads the wash utilities; `--btn-bg` only feeds the spread.
+  destructive:
+    'bg-destructive-wash group-hover:bg-destructive-wash-hover group-active:bg-destructive-wash-active [--btn-bg:var(--destructive-wash)] group-hover:[--btn-bg:var(--destructive-wash-hover)] group-active:[--btn-bg:var(--destructive-wash-active)] shadow-[0_0_0_1px_var(--btn-bg)] group-active:shadow-[0_0_0_0px_var(--btn-bg)]',
+  success:
+    'bg-success-wash group-hover:bg-success-wash-hover group-active:bg-success-wash-active [--btn-bg:var(--success-wash)] group-hover:[--btn-bg:var(--success-wash-hover)] group-active:[--btn-bg:var(--success-wash-active)] shadow-[0_0_0_1px_var(--btn-bg)] group-active:shadow-[0_0_0_0px_var(--btn-bg)]',
+  link: 'bg-transparent',
+}
+
+/* Forced-active (`active` prop): pressed colors at full size; the
+   geometric press-collapse still reacts on top. */
+const activeBgVariants: Record<string, string> = {
+  primary:
+    '[--btn-bg:color-mix(in_oklab,var(--foreground)_80%,var(--background))] bg-[var(--btn-bg)] shadow-[0_0_0_1px_var(--btn-bg)] group-active:shadow-[0_0_0_0px_var(--btn-bg)]',
+  secondary:
+    '[--btn-bg:var(--accent)] bg-[var(--btn-bg)] shadow-[0_0_0_1px_var(--btn-bg)] group-active:shadow-[0_0_0_0px_var(--btn-bg)]',
+  tertiary:
+    'bg-active shadow-[0_0_0_1px_var(--border),inset_0_0_0_0px_var(--border)] group-active:shadow-[0_0_0_0px_var(--border),inset_0_0_0_1px_var(--border)]',
+  ghost: 'bg-active shadow-[0_0_0_1px_var(--active)] group-active:shadow-[0_0_0_0px_var(--active)]',
+  destructive:
+    'bg-destructive-wash-active [--btn-bg:var(--destructive-wash-active)] shadow-[0_0_0_1px_var(--btn-bg)] group-active:shadow-[0_0_0_0px_var(--btn-bg)]',
+  success:
+    'bg-success-wash-active [--btn-bg:var(--success-wash-active)] shadow-[0_0_0_1px_var(--btn-bg)] group-active:shadow-[0_0_0_0px_var(--btn-bg)]',
+  // A held link shows its underline.
+  link: 'bg-transparent',
+}
+
+const { exit: _exit, ...enter } = spring.moderate
+
+/* Loading morph (local): the surface layer contracts from the button's box
+   into a circle one control tall around the spinner, on one progress value
+   like the morph layer (lib/use-morph.ts). The button's own box never
+   changes, so nothing around it moves. Left and right mix a share of the
+   button's width with pixels, so a stretched (w-full) button keeps the
+   circle centred without measuring its width. At rest the inline geometry
+   is dropped and the classes (inset-px, the inherited radius) take over. */
+function useLoadingMorph(loading: boolean) {
+  const surface = useRef<HTMLSpanElement>(null)
+  const progress = useMotionValue(loading ? 1 : 0)
+  const reduced = useReduceMotion()
+
+  useLayoutEffect(() => {
+    const el = surface.current
+    const root = el?.parentElement
+    if (!el || !root || (!loading && progress.get() === 0)) return
+    const height = root.offsetHeight
+    // The surface sits 1px inside the button (its spread fills that pixel back out).
+    const circle = height / 2 - 1
+    const rest = Math.min(Number.parseFloat(getComputedStyle(root).borderTopLeftRadius) || 0, circle)
+    const render = (p: number) => {
+      const side = `calc(${50 * p}% + ${1 - (height / 2) * p}px)`
+      el.style.left = side
+      el.style.right = side
+      el.style.borderRadius = `${rest + (circle - rest) * p}px`
+    }
+    const settle = () => el.removeAttribute('style')
+    const target = loading ? 1 : 0
+    if (reduced || progress.get() === target) {
+      progress.jump(target)
+      return loading ? render(1) : settle()
+    }
+    const controls = animate(progress, target, {
+      ...enter,
+      onUpdate: render,
+      onComplete: loading ? undefined : settle,
+    })
+    return () => controls.stop()
+  }, [loading, reduced])
+
+  return surface
+}
+
+/**
+ * Versatile button with variants, sizes, loading state, and icon support.
+ *
+ * Four variants (primary, secondary, tertiary, ghost) on the two-step size
+ * ladder: 36px by default, 28px compact — an explicit `size` wins, otherwise
+ * the button follows the surrounding SizeProvider. For hosts with a
+ * shadcn-style API there are four more: `outline` (tertiary by its other
+ * name), `destructive` and `success` (the hue as the label on a wash of
+ * itself, never a solid fill, so a view keeps one primary) and `link`
+ * (underlined text on the control height). The press effect shrinks
+ * the fill by exactly 1px per side at any width, icons thicken their stroke
+ * on hover, and `loading` folds the surface into a circle around a spinner
+ * (and back when it ends) while the button keeps its box, so nothing around
+ * it moves. Built on Base UI's Button; `asChild` renders your own
+ * element (e.g. a link) with the button's styling instead.
+ *
+ * Also exported from this item:
+ * - `buttonVariants` — the class recipe (also from `button/variants`, safe in
+ *   server code): `variant`, `size` (aliases included), `iconLeft`,
+ *   `iconRight`, `surface`. On its own it gives the root classes, and the fill
+ *   lives on the Button's inner layer; `surface: true` puts the fill, ring,
+ *   hover, press and `aria-disabled` look on the element itself, for an
+ *   anchor you can't render through `asChild`. Prefer `<Button asChild>`
+ *   where you can: it keeps the press shrink, the icon stroke and `loading`.
+ *
+ * @example {@include ./examples.mdx}
+ */
+const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  (
+    {
+      className,
+      variant,
+      size,
+      asChild = false,
+      loading = false,
+      leadingIcon: LeadingIcon,
+      trailingIcon: TrailingIcon,
+      active = false,
+      disabled,
+      children,
+      style,
+      ...props
+    },
+    ref,
+  ) => {
+    // asChild: the user's element becomes the root while the button's internal
+    // structure (bg layer, content wrapper, spinner, icons) survives as its
+    // children — the element's own children become the label. We clone the
+    // element directly instead of routing through ButtonPrimitive's `render`:
+    // Base UI would bolt button semantics (role="button", Space activation)
+    // onto e.g. a link, where plain-link output is wanted.
+    const asChildElement =
+      asChild && isValidElement(children)
+        ? (children as ReactElement<{
+            children?: ReactNode
+            className?: string
+            style?: React.CSSProperties
+            ref?: React.Ref<HTMLButtonElement>
+            'aria-busy'?: boolean
+            'aria-disabled'?: boolean | 'true' | 'false'
+            onClick?: React.MouseEventHandler<HTMLButtonElement>
+          }>)
+        : null
+    const label = asChildElement ? asChildElement.props.children : children
+    // Resolve the size: explicit prop (legacy aliases mapped onto the
+    // canonical ladder) > surrounding SizeProvider > default.
+    const contextSize = useSizeVariant()
+    const resolvedSize: ButtonSizeCanonical = size
+      ? (legacySizeAliases[size] ?? (size as ButtonSizeCanonical))
+      : contextSize === 'compact'
+        ? 'compact'
+        : 'default'
+    const isIconOnly = resolvedSize === 'icon' || resolvedSize === 'icon-compact'
+    const isCompact = resolvedSize === 'compact' || resolvedSize === 'icon-compact'
+    const iconSize = isCompact ? 14 : 16
+    // Spinner box tracks the button height so the loading glyph stays
+    // proportionate across sizes.
+    const spinnerSizeClass = isCompact ? 'h-7 w-7' : 'h-9 w-9'
+    const shape = useShape()
+    // `outline` is tertiary by its shadcn name.
+    const surfaceVariant = variant === 'outline' ? 'tertiary' : (variant ?? 'primary')
+    const bgClass = active ? activeBgVariants[surfaceVariant] : bgVariants[surfaceVariant]
+
+    const surface = useLoadingMorph(loading)
+
+    const internals = (
+      <>
+        <span
+          ref={surface}
+          aria-hidden
+          className={cn(
+            'absolute inset-px rounded-[inherit] transition-[box-shadow,background-color] [transition-duration:180ms,80ms] [transition-timing-function:cubic-bezier(0.23,1,0.32,1),ease] group-active:[transition-duration:80ms,80ms]',
+            bgClass,
+          )}
+        />
+        {/* The label keeps its place while loading, so the button keeps its
+            box. Whatever leaves goes on the fast exit, so the label and the
+            spinner barely overlap while the surface folds or unfolds. */}
+        <motion.span
+          className="relative inline-flex items-center justify-center gap-[inherit]"
+          initial={false}
+          animate={{ opacity: loading ? 0 : 1 }}
+          transition={loading ? spring.fast.exit : enter}
+        >
+          {isIconOnly ? (
+            <span className="[&_svg]:stroke-[1.5] [&_svg]:transition-[stroke-width] [&_svg]:duration-fast group-hover:[&_svg]:stroke-[2]">
+              {label}
+            </span>
+          ) : (
+            <>
+              {LeadingIcon && (
+                <LeadingIcon
+                  size={iconSize}
+                  strokeWidth={1.5}
+                  className="transition-[stroke-width] duration-fast group-hover:stroke-[2]"
+                />
+              )}
+              {/* text-box only applies to block containers, so the trim lives
+                  on the label span (a blockified flex item), not the flex root.
+                  The button's height is fixed (h-*), so this doesn't change
+                  layout — it just centers the cap-to-baseline box optically. */}
+              <span className="[text-box:trim-both_cap_alphabetic]">{label}</span>
+              {TrailingIcon && (
+                <TrailingIcon
+                  size={iconSize}
+                  strokeWidth={1.5}
+                  className="transition-[stroke-width] duration-fast group-hover:stroke-[2]"
+                />
+              )}
+            </>
+          )}
+        </motion.span>
+        <AnimatePresence initial={false}>
+          {loading && (
+            <motion.span
+              key="spinner"
+              aria-hidden
+              className="absolute inset-0 flex items-center justify-center"
+              initial={{ opacity: 0, scale: 0.6 }}
+              animate={{ opacity: 1, scale: 1 }}
+              exit={{ opacity: 0, scale: 0.6, transition: spring.fast.exit }}
+              transition={enter}
+            >
+              <svg className={spinnerSizeClass} viewBox="0 0 24 24" fill="none">
+                <path
+                  d="M 12 12 C 14 8.5 19 8.5 19 12 C 19 15.5 14 15.5 12 12 C 10 8.5 5 8.5 5 12 C 5 15.5 10 15.5 12 12 Z"
+                  stroke="currentColor"
+                  strokeWidth="1.125"
+                  strokeLinecap="round"
+                  pathLength="100"
+                  style={{
+                    strokeDasharray: '15 85',
+                    animation: 'spinner-move 2s linear infinite, spinner-dash 4s ease-in-out infinite',
+                  }}
+                />
+              </svg>
+            </motion.span>
+          )}
+        </AnimatePresence>
+      </>
+    )
+
+    const rootClassName = cn(
+      buttonVariants({
+        variant,
+        size: resolvedSize,
+        iconLeft: !isIconOnly && !!LeadingIcon,
+        iconRight: !isIconOnly && !!TrailingIcon,
+      }),
+      shape.button,
+      // A loading button is disabled through aria-disabled (it keeps focus),
+      // which the variants' `disabled:` styles don't see.
+      'aria-disabled:opacity-50 aria-disabled:pointer-events-none',
+      active && variant === 'link' && 'decoration-current',
+      className,
+    )
+
+    if (asChildElement) {
+      const childProps = asChildElement.props
+      const onClick = props.onClick ?? childProps.onClick
+      return cloneElement(
+        asChildElement,
+        {
+          ...props,
+          ref,
+          'aria-busy': loading || undefined,
+          'aria-disabled': loading || props['aria-disabled'] || childProps['aria-disabled'],
+          // A pending action blocks a second press (and a link's navigation).
+          onClick: (event: React.MouseEvent<HTMLButtonElement>) => {
+            if (loading) {
+              event.preventDefault()
+              event.stopPropagation()
+              return
+            }
+            onClick?.(event)
+          },
+          className: cn(rootClassName, childProps.className),
+          style: { ...style, ...childProps.style },
+        },
+        internals,
+      )
+    }
+
+    return (
+      <ButtonPrimitive
+        // Base UI's `ButtonPrimitive` forwards to an HTMLButtonElement;
+        // keep the public ref type narrow so consumers see the right type.
+        ref={ref as React.Ref<HTMLButtonElement>}
+        className={rootClassName}
+        disabled={disabled || loading}
+        // While loading, Base UI disables it with aria-disabled instead of
+        // the attribute, so a keyboard user keeps focus on it; it still
+        // ignores presses.
+        focusableWhenDisabled={loading}
+        aria-busy={loading || undefined}
+        style={style}
+        {...props}
+      >
+        {internals}
+      </ButtonPrimitive>
+    )
+  },
+)
+
+Button.displayName = 'Button'
+
+export type { ButtonSizeCanonical, ButtonVariantsOptions } from './variants'
+export type { ButtonProps, ButtonSize, ButtonVariant }
+export { Button, buttonVariants }
+
+export default Button

package/components/button/loading-demo.tsx

@@ -0,0 +1,25 @@
+/*
+ * Local addition (not part of Fluid Functionalism): the docs stage of the
+ * Button page's loading morph. A Button that loads for a moment when pressed,
+ * so the example stays hook-free.
+ */
+
+import { useEffect, useState } from 'react'
+import Button, { type ButtonProps } from './index'
+
+interface LoadingDemoProps extends ButtonProps {
+  /** How long a press keeps the button loading, in ms. */
+  duration?: number
+}
+
+export default function LoadingDemo({ duration = 2000, ...props }: LoadingDemoProps) {
+  const [loading, setLoading] = useState(false)
+
+  useEffect(() => {
+    if (!loading) return
+    const timer = setTimeout(() => setLoading(false), duration)
+    return () => clearTimeout(timer)
+  }, [loading, duration])
+
+  return <Button {...props} loading={loading} onClick={() => setLoading(true)} />
+}