@tangle-network/ui 11.12.0 → 11.13.0

package/src/markdown/code-block.test.tsx

@@ -1,7 +1,51 @@
-import { describe, it, expect } from "vitest";
-import { render } from "@testing-library/react";
+import { cleanup, render, screen } from "@testing-library/react";
+import { renderToString } from "react-dom/server";
+import { afterEach, describe, expect, it } from "vitest";
 import { CodeBlock, CopyButton } from "./code-block";
 
+afterEach(cleanup);
+
+describe("CodeBlock scoped semantic colors", () => {
+  it("emits live CSS variables through the real highlighter, not sampled root colors", () => {
+    const { container } = render(<CodeBlock code={'const message = "hello";'} language="javascript" showLineNumbers />);
+    expect(container.innerHTML).toContain("var(--syntax-keyword, currentColor)");
+    expect(container.innerHTML).toContain("var(--syntax-string, currentColor)");
+    expect(container.innerHTML).toContain("var(--syntax-comment, currentColor)");
+  });
+
+  it("inherits a named scope by default without inserting its own mode", () => {
+    const { container } = render(<section data-theme="arena-light"><CodeBlock data-testid="code" code="const x = 1" language="javascript" /></section>);
+    const code = screen.getByTestId("code");
+    expect(code.hasAttribute("data-theme")).toBe(false);
+    const before = code.innerHTML;
+    container.querySelector("section")!.setAttribute("data-theme", "arena");
+    expect(code.innerHTML).toBe(before); // References stay live; the browser fixture checks the computed colors.
+  });
+
+  it.each([true, false])("preserves explicit light=%s as an opposite nested mode", (light) => {
+    render(<section data-theme={light ? "dark" : "light"}><CodeBlock data-testid="code" code="x" light={light} /></section>);
+    expect(screen.getByTestId("code").getAttribute("data-theme")).toBe(light ? "light" : "dark");
+  });
+
+  it("preserves caller attributes, labels, children and custom scopes", () => {
+    render(<CodeBlock data-testid="code" data-theme="aubergine" className="caller" code="echo hello" language="bash" label="BASHRC"><button>Copy example</button></CodeBlock>);
+    expect(screen.getByTestId("code").getAttribute("data-theme")).toBe("aubergine");
+    expect(screen.getByTestId("code").classList.contains("caller")).toBe(true);
+    expect(screen.getByText("BASHRC")).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Copy example" })).toBeTruthy();
+  });
+
+  it("server-renders the same semantic references independent of document theme", () => {
+    const source = <CodeBlock code="const x = 1" language="javascript" />;
+    document.documentElement.className = "dark";
+    const dark = renderToString(source);
+    document.documentElement.className = "light";
+    expect(renderToString(source)).toBe(dark);
+    document.documentElement.removeAttribute("class");
+  });
+});
+
+// Retain the existing header/label/copy-slot contracts alongside theme coverage.
 describe("CodeBlock", () => {
   it("renders the code through the syntax highlighter", () => {
     const { container } = render(<CodeBlock code={"const x = 1;"} language="typescript" />);

package/src/markdown/code-block.tsx

@@ -12,23 +12,19 @@ import { Check, Copy } from "lucide-react";
 import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
 
-// Theme-aware syntax highlighting — reads CSS custom properties at render time.
-// Override --syntax-* tokens in tokens.css per theme.
-function getSyntaxTheme(): { [key: string]: React.CSSProperties } {
-  const el = typeof document !== "undefined" ? document.documentElement : null;
-  const v = (name: string, fallback: string) =>
-    el ? getComputedStyle(el).getPropertyValue(name).trim() || fallback : fallback;
-
-  const comment  = v("--syntax-comment", "#6B7094");
-  const keyword  = v("--syntax-keyword", "#A78FFF");
-  const string   = v("--syntax-string", "#10b981");
-  const fn       = v("--syntax-function", "#6D9FFF");
-  const number   = v("--syntax-number", "#FFB347");
-  const meta     = v("--syntax-meta", "#8263FF");
-  const error    = v("--syntax-error", "#FF4D6D");
-  const variable = v("--syntax-variable", "#C4C0D8");
-  const fg       = v("--syntax-foreground", "#E8E6F6");
-
+// Leave variables unresolved: the browser resolves them on each token span,
+// including nested themes, inline overrides and CSS/media changes. No document
+// sampling, observers, layout reads or React re-render are needed to recolor code.
+const syntaxTheme: { [key: string]: React.CSSProperties } = (() => {
+  const comment = "var(--syntax-comment, currentColor)";
+  const keyword = "var(--syntax-keyword, currentColor)";
+  const string = "var(--syntax-string, currentColor)";
+  const fn = "var(--syntax-function, currentColor)";
+  const number = "var(--syntax-number, currentColor)";
+  const meta = "var(--syntax-meta, currentColor)";
+  const error = "var(--syntax-error, currentColor)";
+  const variable = "var(--syntax-variable, currentColor)";
+  const fg = "var(--syntax-foreground, currentColor)";
   return {
     "hljs-comment":           { color: comment, fontStyle: "italic" },
     "hljs-quote":             { color: comment, fontStyle: "italic" },
@@ -67,10 +63,7 @@ function getSyntaxTheme(): { [key: string]: React.CSSProperties } {
     "hljs-emphasis":          { fontStyle: "italic" },
     "hljs":                   { color: fg, background: "transparent" },
   };
-}
-
-// tangleLight removed — getSyntaxTheme() reads --syntax-* CSS vars which are overridden
-// per theme in tokens.css (vault, dawn themes set light values).
+})();
 
 export interface CodeBlockProps extends HTMLAttributes<HTMLDivElement> {
   code: string;
@@ -82,55 +75,25 @@ export interface CodeBlockProps extends HTMLAttributes<HTMLDivElement> {
    */
   label?: string;
   showLineNumbers?: boolean;
-  /** Force light theme; defaults to dark */
+  /** Force light (true) or dark (false); omitted inherits the nearest theme. */
   light?: boolean;
   children?: ReactNode;
 }
 
-const LIGHT_THEMES = new Set(["vault", "dawn"]);
-
-function detectLightTheme() {
-  return (
-    typeof document !== "undefined" &&
-    LIGHT_THEMES.has(document.documentElement.getAttribute("data-sandbox-theme") ?? "")
-  );
-}
-
-function useIsLightTheme(): boolean {
-  const [isLight, setIsLight] = useState(detectLightTheme);
-
-  useEffect(() => {
-    if (typeof document === "undefined") return;
-    setIsLight(detectLightTheme());
-    const observer = new MutationObserver(() => setIsLight(detectLightTheme()));
-    observer.observe(document.documentElement, {
-      attributes: true,
-      attributeFilter: ["data-sandbox-theme"],
-    });
-    return () => observer.disconnect();
-  }, []);
-
-  return isLight;
-}
-
 export const CodeBlock = memo(
-  ({ code, language, label, showLineNumbers = false, light: lightProp, className, children, ...props }: CodeBlockProps) => {
-    const isLight = useIsLightTheme();
-    const light = lightProp ?? isLight;
-    const theme = getSyntaxTheme();
-    const bg = "bg-card border-border";
-    const headerBg = light ? "bg-muted/50 border-border" : "bg-background border-border";
-    const langColor = "text-muted-foreground";
+  ({ code, language, label, showLineNumbers = false, light, className, children, ...props }: CodeBlockProps) => {
     const headerLabel = label ?? language;
+    const mode = light === undefined ? {} : { "data-theme": light ? "light" : "dark" };
 
     return (
       <div
-        className={cn("group relative overflow-hidden rounded-lg border font-mono", bg, className)}
+        className={cn("group relative overflow-hidden rounded-lg border font-mono", "bg-card border-border", className)}
         {...props}
+        {...mode}
       >
         {headerLabel && (
-          <div className={cn("flex items-center justify-between border-b px-3 py-1", headerBg)}>
-            <span className={cn("text-[calc(var(--font-size-xs)-1px)] font-mono font-medium uppercase tracking-widest", langColor)}>
+          <div className="flex items-center justify-between border-b border-border px-3 py-1 bg-[var(--code-header-bg,hsl(var(--background)))]">
+            <span className="text-[calc(var(--font-size-xs)-1px)] font-mono font-medium uppercase tracking-widest text-muted-foreground">
               {headerLabel}
             </span>
             {children}
@@ -143,10 +106,10 @@ export const CodeBlock = memo(
         )}
         <SyntaxHighlighter
           language={language ?? "text"}
-          style={theme}
+          style={syntaxTheme}
           showLineNumbers={showLineNumbers}
           lineNumberStyle={{
-            color: light ? "#8B92B8" : "#4A4D6A",
+            color: "var(--syntax-comment, currentColor)",
             minWidth: "2.5em",
             paddingRight: "1em",
           }}

package/src/primitives/button.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react'
+import { useId, useState } from 'react'
 import { Button } from './button'
 
 const meta: Meta<typeof Button> = {
@@ -17,7 +18,7 @@ export const Secondary: Story = { args: { variant: 'secondary' } }
 export const Outline: Story = { args: { variant: 'outline' } }
 export const Ghost: Story = { args: { variant: 'ghost' } }
 export const Destructive: Story = { args: { variant: 'destructive', children: 'Delete' } }
-export const Loading: Story = { args: { loading: true, children: 'Loading...' } }
+export const Loading: Story = { args: { loading: true, children: 'Save changes' } }
 
 export const AllSizes: Story = {
   name: 'All Sizes',
@@ -46,3 +47,38 @@ export const AllVariants: Story = {
     </div>
   ),
 }
+
+export const ActionContracts: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Toggle disabled/loading, then try pointer, Enter and Space activation. Native buttons retain their submit default; links keep their action name while unavailable. Emulate prefers-reduced-motion to check the spinner and press effect.',
+      },
+    },
+  },
+  render: function ActionContracts() {
+    const resultId = useId()
+    const [disabled, setDisabled] = useState(false)
+    const [loading, setLoading] = useState(false)
+    const [submits, setSubmits] = useState(0)
+    const [opens, setOpens] = useState(0)
+    return (
+      <div className="flex max-w-lg flex-col gap-4">
+        <div className="flex gap-4">
+          <label><input type="checkbox" checked={disabled} onChange={event => setDisabled(event.target.checked)} /> Disabled</label>
+          <label><input type="checkbox" checked={loading} onChange={event => setLoading(event.target.checked)} /> Loading</label>
+        </div>
+        <form className="flex flex-wrap gap-3" onSubmit={event => { event.preventDefault(); setSubmits(value => value + 1) }}>
+          <Button disabled={disabled} loading={loading}>Save changes</Button>
+          <Button asChild disabled={disabled} loading={loading}>
+            <button disabled={false} aria-busy={false}>Submit slotted button</button>
+          </Button>
+          <Button asChild disabled={disabled} loading={loading}>
+            <a href={`#${resultId}`} onClick={() => setOpens(value => value + 1)}>Open result</a>
+          </Button>
+        </form>
+        <p id={resultId} role="status">Submissions: {submits}. Link activations: {opens}.</p>
+      </div>
+    )
+  },
+}

package/src/primitives/button.test.tsx

@@ -0,0 +1,230 @@
+import * as React from "react";
+import { act, cleanup, fireEvent, render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { hydrateRoot, type Root } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Button } from "./button";
+
+afterEach(cleanup);
+
+describe.each(["disabled", "loading"] as const)("%s controls", (state) => {
+  it.each([false, true])("natively disables button elements (asChild=%s)", async (asChild) => {
+    const user = userEvent.setup();
+    const click = vi.fn();
+    const submit = vi.fn((event: React.FormEvent) => event.preventDefault());
+    render(<form onSubmit={submit}>
+      <Button {...{ [state]: true }} asChild={asChild} onClick={click}>
+        {asChild ? <button disabled={false} aria-busy={false}>Save</button> : "Save"}
+      </Button>
+      <input aria-label="Next field" />
+    </form>);
+    const button = screen.getByRole("button", { name: "Save" });
+    expect(button).toBeDisabled();
+    expect(button).toHaveAccessibleName("Save");
+    if (state === "loading") expect(button).toHaveAttribute("aria-busy", "true");
+    await user.click(button);
+    button.click();
+    button.focus();
+    expect(button).not.toHaveFocus();
+    await user.keyboard("{Enter} ");
+    expect(click).not.toHaveBeenCalled();
+    expect(submit).not.toHaveBeenCalled();
+    await user.tab();
+    expect(screen.getByRole("textbox")).toHaveFocus();
+  });
+
+  it("blocks slotted anchor activation before child AND slot capture/bubble handlers", async () => {
+    const user = userEvent.setup();
+    const activation = vi.fn();
+    const handlers = {
+      onClick: activation, onClickCapture: activation,
+      onAuxClick: activation, onAuxClickCapture: activation,
+      onDoubleClick: activation, onDoubleClickCapture: activation,
+      onPointerDown: activation, onPointerDownCapture: activation,
+      onPointerUp: activation, onPointerUpCapture: activation,
+      onMouseDown: activation, onMouseDownCapture: activation,
+      onMouseUp: activation, onMouseUpCapture: activation,
+      onKeyDown: activation, onKeyDownCapture: activation,
+      onKeyUp: activation, onKeyUpCapture: activation,
+    };
+    render(<div onClick={activation}>
+      <Button asChild {...{ [state]: true }} aria-busy={false} {...handlers}>
+        <a href="#destination" tabIndex={0} aria-disabled={false} aria-busy={false} {...handlers}>
+          <span>Open account</span>
+        </a>
+      </Button>
+      <button>Next action</button>
+    </div>);
+    const link = screen.getByRole("link", { name: "Open account" });
+    expect(link).toHaveAttribute("aria-disabled", "true");
+    expect(link).toHaveAttribute("tabindex", "-1");
+    expect(link).not.toHaveAttribute("disabled");
+    expect(link).not.toHaveAttribute("href");
+    if (state === "loading") expect(link).toHaveAttribute("aria-busy", "true");
+    const target = screen.getByText("Open account");
+    expect(fireEvent.click(target)).toBe(false);
+    expect(fireEvent.doubleClick(target)).toBe(false);
+    expect(fireEvent(target, new MouseEvent("auxclick", { bubbles: true, cancelable: true, button: 1 }))).toBe(false);
+    expect(fireEvent.pointerDown(target)).toBe(false);
+    expect(fireEvent.pointerUp(target)).toBe(false);
+    expect(fireEvent.mouseDown(target)).toBe(false);
+    expect(fireEvent.mouseUp(target)).toBe(false);
+    for (const key of ["Enter", " "]) {
+      expect(fireEvent.keyDown(link, { key })).toBe(false);
+      expect(fireEvent.keyUp(link, { key })).toBe(false);
+    }
+    await user.click(target);
+    link.click();
+    // Even programmatically focused, a disabled link cannot activate by keyboard.
+    link.focus();
+    await user.keyboard("{Enter} ");
+    expect(activation).not.toHaveBeenCalled();
+    link.blur();
+    await user.tab();
+    expect(screen.getByRole("button", { name: "Next action" })).toHaveFocus();
+  });
+});
+
+it("retains the action name and hides the reduced-motion spinner from accessibility", () => {
+  const { rerender } = render(<Button loading aria-busy={false}>Save changes</Button>);
+  const button = screen.getByRole("button", { name: "Save changes" });
+  expect(button).toHaveAttribute("aria-busy", "true");
+  const spinner = button.querySelector("svg");
+  expect(spinner).toHaveAttribute("aria-hidden", "true");
+  expect(spinner).toHaveAttribute("focusable", "false");
+  expect(spinner).toHaveClass("motion-reduce:animate-none");
+  expect(button).toHaveClass("motion-reduce:transition-none", "motion-reduce:active:scale-100");
+  expect(button.querySelector("title")).toBeNull();
+  rerender(<Button loading size="icon" aria-label="Refresh reports"><span aria-hidden="true">↻</span></Button>);
+  expect(screen.getByRole("button")).toHaveAccessibleName("Refresh reports");
+});
+
+it.each(["disabled", "loading"] as const)("restores link attributes and original Slot handler order when %s ends", async (state) => {
+  const user = userEvent.setup();
+  const calls: string[] = [];
+  const ui = (unavailable: boolean) => <Button asChild {...{ [state]: unavailable }} onClick={() => calls.push("slot")}>
+    <a href="#destination" tabIndex={2} onClick={(event) => { event.preventDefault(); calls.push("child"); }}>Open</a>
+  </Button>;
+  const { rerender } = render(ui(true));
+  const link = screen.getByRole("link");
+  rerender(ui(false));
+  expect(link).toHaveAttribute("href", "#destination");
+  expect(link).toHaveAttribute("tabindex", "2");
+  expect(link).not.toHaveAttribute("aria-disabled");
+  expect(link).not.toHaveAttribute("aria-busy");
+  expect(link).not.toHaveAttribute("role");
+  await user.click(link);
+  expect(calls).toEqual(["child", "slot"]);
+  calls.length = 0;
+  link.focus();
+  await user.keyboard("{Enter}");
+  expect(calls).toEqual(["child", "slot"]);
+});
+
+it("preserves non-activation keyboard handlers on disabled links", () => {
+  const calls: string[] = [];
+  render(<Button asChild disabled onKeyDownCapture={() => calls.push("slot capture")} onKeyDown={() => calls.push("slot bubble")}>
+    <a href="#destination" onKeyDownCapture={() => calls.push("child capture")} onKeyDown={() => calls.push("child bubble")}>Open</a>
+  </Button>);
+  expect(fireEvent.keyDown(screen.getByRole("link"), { key: "ArrowRight" })).toBe(true);
+  expect(calls).toEqual(["child capture", "slot capture", "child bubble", "slot bubble"]);
+});
+
+it("respects a native child's own disabled state", () => {
+  render(<Button asChild disabled={false}><button disabled>Save</button></Button>);
+  expect(screen.getByRole("button")).toBeDisabled();
+});
+
+it("composes refs on a slotted native button", () => {
+  const outerRef = React.createRef<HTMLButtonElement>();
+  const childRef = React.createRef<HTMLButtonElement>();
+  const { unmount } = render(<Button asChild ref={outerRef}><button ref={childRef}>Save</button></Button>);
+  expect(outerRef.current).toBe(screen.getByRole("button"));
+  expect(childRef.current).toBe(outerRef.current);
+  unmount();
+  expect(outerRef.current).toBeNull();
+  expect(childRef.current).toBeNull();
+});
+
+it("preserves caller busy state when Button is not loading", () => {
+  render(<><Button aria-busy>Save</Button><Button asChild aria-busy><a href="#destination">Open</a></Button></>);
+  expect(screen.getByRole("button")).toHaveAttribute("aria-busy", "true");
+  expect(screen.getByRole("link")).toHaveAttribute("aria-busy", "true");
+});
+
+it("preserves implicit submission, explicit types, and enabled keyboard activation", async () => {
+  const user = userEvent.setup();
+  const submit = vi.fn((event: React.FormEvent) => event.preventDefault());
+  render(<form onSubmit={submit}>
+    <Button>Implicit submit</Button>
+    <Button asChild><button>Slotted submit</button></Button>
+    <Button type="button">Explicit button</Button>
+    <Button type="submit">Explicit submit</Button>
+    <Button asChild type="submit"><button type="button">Child button</button></Button>
+  </form>);
+  const implicit = screen.getByRole("button", { name: "Implicit submit" });
+  expect(implicit).not.toHaveAttribute("type");
+  await user.click(implicit);
+  await user.click(screen.getByRole("button", { name: "Slotted submit" }));
+  await user.click(screen.getByRole("button", { name: "Explicit submit" }));
+  expect(submit).toHaveBeenCalledTimes(3);
+  await user.click(screen.getByRole("button", { name: "Explicit button" }));
+  await user.click(screen.getByRole("button", { name: "Child button" }));
+  expect(submit).toHaveBeenCalledTimes(3);
+  implicit.focus();
+  await user.keyboard("{Enter} ");
+  expect(submit).toHaveBeenCalledTimes(5);
+});
+
+it("forwards native refs and composes both refs on a slotted anchor", () => {
+  const nativeRef = React.createRef<HTMLButtonElement>();
+  const anchorRef = React.createRef<HTMLAnchorElement>();
+  const slotRef = vi.fn();
+  const { rerender, unmount } = render(<>
+    <Button ref={nativeRef}>Save</Button>
+    <Button asChild loading ref={slotRef}><a ref={anchorRef} href="#destination">Open</a></Button>
+  </>);
+  const link = screen.getByRole("link");
+  expect(nativeRef.current).toBe(screen.getByRole("button"));
+  expect(anchorRef.current).toBe(link);
+  expect(slotRef).toHaveBeenLastCalledWith(link);
+  rerender(<>
+    <Button ref={nativeRef}>Save</Button>
+    <Button asChild ref={slotRef}><a ref={anchorRef} href="#destination">Open</a></Button>
+  </>);
+  expect(anchorRef.current).toBe(link);
+  expect(slotRef).toHaveBeenLastCalledWith(link);
+  unmount();
+  expect(nativeRef.current).toBeNull();
+  expect(anchorRef.current).toBeNull();
+  expect(slotRef).toHaveBeenLastCalledWith(null);
+});
+
+it("hydrates disabled/loading native and slotted controls without changing their names", async () => {
+  const ui = <>
+    <Button loading>Save</Button>
+    <Button asChild loading><button>Submit</button></Button>
+    <Button asChild disabled><a href="#destination">Open</a></Button>
+  </>;
+  const container = document.createElement("div");
+  container.innerHTML = renderToString(ui);
+  document.body.appendChild(container);
+  const html = container.innerHTML;
+  const recoverableError = vi.fn();
+  const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+  let root: Root | undefined;
+  try {
+    await act(async () => { root = hydrateRoot(container, ui, { onRecoverableError: recoverableError }); });
+    expect(container.innerHTML).toBe(html);
+    expect(within(container).getByRole("button", { name: "Save" })).toBeDisabled();
+    expect(within(container).getByRole("button", { name: "Submit" })).toBeDisabled();
+    expect(within(container).getByRole("link", { name: "Open" })).not.toHaveAttribute("href");
+    expect(recoverableError).not.toHaveBeenCalled();
+    expect(consoleError).not.toHaveBeenCalled();
+  } finally {
+    await act(async () => { root?.unmount(); });
+    consoleError.mockRestore();
+    container.remove();
+  }
+});

package/src/primitives/button.tsx

@@ -1,11 +1,11 @@
 import { Slot } from "@radix-ui/react-slot";
-import { cva, type VariantProps } from "class-variance-authority";
+import { cva } from "class-variance-authority";
 import * as React from "react";
 import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
 
 const buttonVariants = cva(
-  `inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-lg font-medium text-sm transition-all ${focusRing} disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0`,
+  `inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-lg font-medium text-sm transition-all ${focusRing} disabled:pointer-events-none disabled:opacity-50 aria-disabled:cursor-not-allowed aria-disabled:opacity-50 motion-reduce:transition-none motion-reduce:active:scale-100 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0`,
   {
     variants: {
       variant: {
@@ -47,6 +47,36 @@ export interface ButtonProps
   children?: React.ReactNode;
 }
 
+type ButtonChildProps = React.HTMLAttributes<HTMLElement> & {
+  disabled?: boolean;
+  href?: string;
+};
+
+function preventActivation(event: React.SyntheticEvent) {
+  event.preventDefault();
+  event.stopPropagation();
+}
+
+function disabledHandlers(props: React.HTMLAttributes<HTMLElement>) {
+  const guardKey = (handler?: React.KeyboardEventHandler<HTMLElement>) =>
+    (event: React.KeyboardEvent<HTMLElement>) => {
+      if (event.key === "Enter" || event.key === " ") preventActivation(event);
+      else handler?.(event);
+    };
+
+  return {
+    onClickCapture: preventActivation,
+    onAuxClickCapture: preventActivation,
+    onDoubleClickCapture: preventActivation,
+    onPointerDownCapture: preventActivation,
+    onPointerUpCapture: preventActivation,
+    onMouseDownCapture: preventActivation,
+    onMouseUpCapture: preventActivation,
+    onKeyDownCapture: guardKey(props.onKeyDownCapture),
+    onKeyUpCapture: guardKey(props.onKeyUpCapture),
+  };
+}
+
 const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
   (
     {
@@ -61,36 +91,54 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
     },
     ref,
   ) => {
-    const Comp = asChild ? Slot : "button";
-
-    // When using asChild, we can't add the loading spinner as it would create multiple children
-    // which breaks Slot's single-child requirement
     if (asChild) {
+      const child = React.isValidElement<ButtonChildProps>(children) ? children : null;
+      const isDisabled = disabled || loading || child?.props.disabled;
+
+      // Slot composes child handlers first. Guard BOTH capture paths so neither
+      // child nor Button activation handlers run, without changing enabled order.
+      // Keep slotted content intact: its action name must survive loading too.
       return (
-        <Comp
+        <Slot
           className={cn(buttonVariants({ variant, size, className }))}
           ref={ref}
           {...props}
+          {...(isDisabled ? disabledHandlers(props) : {})}
         >
-          {children}
-        </Comp>
+          {child ? React.cloneElement(child, {
+            ...(loading ? { "aria-busy": true } : {}),
+            ...(isDisabled ? {
+              "aria-disabled": true,
+              ...(child.type === "button" ? { disabled: true } : { tabIndex: -1 }),
+              // Removing href also prevents native context-menu / middle-click
+              // navigation. Keep link semantics while it is unavailable.
+              ...(child.type === "a" ? {
+                href: undefined,
+                role: child.props.role ?? props.role ?? "link",
+              } : {}),
+              ...disabledHandlers(child.props),
+            } : {}),
+          }) : children}
+        </Slot>
       );
     }
 
     return (
-      <Comp
+      <button
         className={cn(buttonVariants({ variant, size, className }))}
         ref={ref}
-        disabled={disabled || loading}
         {...props}
+        disabled={disabled || loading}
+        aria-busy={loading || props["aria-busy"]}
       >
         {loading && (
           <svg
-            className="mr-2 -ml-1 h-4 w-4 animate-spin"
+            className="mr-2 -ml-1 h-4 w-4 animate-spin motion-reduce:animate-none"
+            aria-hidden="true"
+            focusable="false"
             fill="none"
             viewBox="0 0 24 24"
           >
-            <title>Loading spinner</title>
             <circle
               className="opacity-25"
               cx="12"
@@ -107,7 +155,7 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
           </svg>
         )}
         {children}
-      </Comp>
+      </button>
     );
   },
 );

package/src/primitives/card-anatomy.stories.tsx

@@ -0,0 +1,51 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "./button";
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "./card";
+import { Heading } from "./heading";
+
+const meta = {
+  title: "Primitives/Card/Anatomy",
+  component: Card,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Card>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const AlignedParts: Story = {
+  render: () => <div className="max-w-lg space-y-6">
+    <Heading variant="page">Activity details</Heading>
+    <Card data-anatomy="full">
+      <CardHeader data-part="header"><CardTitle as="h2">Latest result</CardTitle><CardDescription>One heading level below the page.</CardDescription></CardHeader>
+      <CardContent data-part="content">The header, body and footer share one horizontal gutter.</CardContent>
+      <CardFooter data-part="footer"><Button type="button" variant="outline">View result</Button></CardFooter>
+    </Card>
+    <Card data-anatomy="standalone"><CardContent data-part="content">Content-only cards retain their top padding.</CardContent></Card>
+  </div>,
+  play: ({ canvasElement }) => {
+    const parts = Array.from(canvasElement.querySelectorAll<HTMLElement>('[data-anatomy="full"] > [data-part]'));
+    const styles = parts.map((part) => getComputedStyle(part));
+    const gutter = styles[0]?.paddingLeft;
+    if (!gutter || parseFloat(gutter) <= 0 || styles.some((style) => style.paddingLeft !== gutter || style.paddingRight !== gutter)) {
+      throw new Error("Card parts do not share a nonzero horizontal gutter");
+    }
+    if (parseFloat(styles[1]!.paddingTop) !== 0 || parseFloat(styles[2]!.paddingTop) !== 0) {
+      throw new Error("Stacked card parts duplicate top padding");
+    }
+    const standalone = canvasElement.querySelector<HTMLElement>('[data-anatomy="standalone"] > [data-part]')!;
+    const style = getComputedStyle(standalone);
+    if (parseFloat(style.paddingTop) <= 0 || style.paddingTop !== style.paddingBottom) {
+      throw new Error("Content-only card lost its top padding");
+    }
+  },
+};
+
+function ActionCard() {
+  const [count, setCount] = useState(0);
+  return <Card hover className="max-w-sm">
+    <CardHeader><CardTitle as="h2">Decorative hover, native action</CardTitle><CardDescription>Tab to the button; Enter and Space both work.</CardDescription></CardHeader>
+    <CardContent><p role="status">Opened {count} times</p></CardContent>
+    <CardFooter><Button type="button" onClick={() => setCount((value) => value + 1)}>Open details</Button></CardFooter>
+  </Card>;
+}
+export const KeyboardAction: Story = { render: () => <ActionCard /> };