@tangle-network/ui 11.12.0 → 11.13.1

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 /> };

package/src/primitives/card.test.tsx

@@ -0,0 +1,71 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type CardTitleProps } from "./card";
+
+describe("Card anatomy", () => {
+  it("keeps the existing default title tag and heading ref", () => {
+    const ref = createRef<HTMLHeadingElement>();
+    render(<CardTitle ref={ref} id="card-title">Details</CardTitle>);
+    expect(ref.current).toBe(screen.getByRole("heading", { level: 3 }));
+    expect(ref.current).toHaveAttribute("id", "card-title");
+  });
+
+  it.each([1, 2, 3, 4, 5, 6] as const)("allows an h%i without changing its visual treatment", (level) => {
+    const { rerender } = render(<CardTitle>Details</CardTitle>);
+    const classes = screen.getByRole("heading").className;
+    rerender(<CardTitle as={`h${level}` as CardTitleProps["as"]}>Details</CardTitle>);
+    expect(screen.getByRole("heading", { level }).className).toBe(classes);
+  });
+
+  it("preserves native attributes and caller classes", () => {
+    render(<CardTitle as="h2" role="presentation" className="text-xl" data-kind="summary">Summary</CardTitle>);
+    const title = screen.getByText("Summary");
+    expect(title).toHaveAttribute("role", "presentation");
+    expect(title).toHaveAttribute("data-kind", "summary");
+    expect(title).toHaveClass("text-xl");
+  });
+
+  it("uses the same gutter on every part and only removes subsequent top padding", () => {
+    render(<Card>
+      <CardHeader data-testid="header"><CardTitle>Details</CardTitle><CardDescription>Prose</CardDescription></CardHeader>
+      <CardContent data-testid="content">Body</CardContent>
+      <CardFooter data-testid="footer">Footer</CardFooter>
+    </Card>);
+    for (const part of ["header", "content", "footer"]) {
+      expect(screen.getByTestId(part)).toHaveClass("p-4");
+      expect(screen.getByTestId(part)).not.toHaveClass("p-6");
+    }
+    expect(screen.getByTestId("content")).toHaveClass("[&:not(:first-child)]:pt-0");
+    expect(screen.getByTestId("footer")).toHaveClass("[&:not(:first-child)]:pt-0");
+    // These are class/DOM contracts, not a browser-computed padding assertion.
+    expect(screen.getByText("Prose").tagName).toBe("P");
+  });
+
+  it("does not strip the top padding unconditionally from content-only cards", () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<Card><CardContent ref={ref}>Standalone</CardContent></Card>);
+    expect(ref.current).toHaveClass("p-4");
+    expect(ref.current).not.toHaveClass("pt-0");
+    expect(ref.current?.matches(":first-child")).toBe(true);
+  });
+
+  it("keeps hover decorative and leaves keyboard activation to a real button", async () => {
+    const user = userEvent.setup();
+    const activate = vi.fn();
+    const ref = createRef<HTMLDivElement>();
+    render(<Card ref={ref} hover>
+      <CardContent><button type="button" onClick={activate}>Open details</button></CardContent>
+    </Card>);
+    expect(ref.current?.tagName).toBe("DIV");
+    expect(ref.current).not.toHaveAttribute("tabindex");
+    expect(ref.current).not.toHaveAttribute("role");
+    expect(ref.current).not.toHaveClass("cursor-pointer");
+    await user.tab();
+    expect(screen.getByRole("button", { name: "Open details" })).toHaveFocus();
+    await user.keyboard("{Enter}");
+    await user.keyboard(" ");
+    expect(activate).toHaveBeenCalledTimes(2);
+  });
+});

package/src/primitives/card.tsx

@@ -1,10 +1,12 @@
 import * as React from "react";
 import { cn } from "../lib/utils";
+import { Heading } from "./heading";
 
 const Card = React.forwardRef<
   HTMLDivElement,
   React.HTMLAttributes<HTMLDivElement> & {
     variant?: "default" | "glass" | "sandbox" | "elevated";
+    /** Decorative border feedback only. Put actions in a native button or link. */
     hover?: boolean;
   }
 >(({ className, variant = "default", hover = false, ...props }, ref) => {
@@ -22,7 +24,7 @@ const Card = React.forwardRef<
         "rounded-[var(--radius-lg)] border text-card-foreground transition-[border-color,box-shadow]",
         "duration-[var(--transition-default)]",
         variants[variant],
-        hover && "cursor-pointer hover:border-[var(--border-strong)]",
+        hover && "hover:border-[var(--border-strong)]",
         className,
       )}
       {...props}
@@ -43,16 +45,22 @@ const CardHeader = React.forwardRef<
 ));
 CardHeader.displayName = "CardHeader";
 
-const CardTitle = React.forwardRef<
-  HTMLHeadingElement,
-  React.HTMLAttributes<HTMLHeadingElement>
->(({ className, ...props }, ref) => (
-  <h3
-    ref={ref}
-    className={cn("font-semibold leading-none tracking-tight", className)}
-    {...props}
-  />
-));
+export interface CardTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
+  /** Heading level appropriate to the surrounding document; h3 remains the default. */
+  as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+}
+
+const CardTitle = React.forwardRef<HTMLHeadingElement, CardTitleProps>(
+  ({ className, as = "h3", ...props }, ref) => (
+    <Heading
+      ref={ref}
+      variant="subsection"
+      as={as}
+      className={className}
+      {...props}
+    />
+  ),
+);
 CardTitle.displayName = "CardTitle";
 
 const CardDescription = React.forwardRef<
@@ -71,7 +79,11 @@ const CardContent = React.forwardRef<
   HTMLDivElement,
   React.HTMLAttributes<HTMLDivElement>
 >(({ className, ...props }, ref) => (
-  <div ref={ref} className={cn("p-4 pt-0", className)} {...props} />
+  <div
+    ref={ref}
+    className={cn("p-4 [&:not(:first-child)]:pt-0", className)}
+    {...props}
+  />
 ));
 CardContent.displayName = "CardContent";
 
@@ -81,7 +93,7 @@ const CardFooter = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn("flex items-center p-6 pt-0", className)}
+    className={cn("flex flex-wrap items-center gap-2 p-4 [&:not(:first-child)]:pt-0", className)}
     {...props}
   />
 ));

package/src/primitives/heading.stories.tsx

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Heading } from "./heading";
+
+const meta = {
+  title: "Primitives/Heading",
+  component: Heading,
+  parameters: { layout: "padded" },
+  args: { variant: "page", children: "Activity across your workspace" },
+  argTypes: {
+    variant: { control: "select", options: ["display", "hero", "page", "section", "subsection", "eyebrow"] },
+    as: { control: "select", options: ["h1", "h2", "h3", "h4", "h5", "h6", "p"] },
+  },
+} satisfies Meta<typeof Heading>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+export const IndependentSemantics: Story = {
+  args: { variant: "page", as: "h2", children: "Page-sized title in a nested surface" },
+};
+export const Hierarchy: Story = {
+  render: () => <main className="space-y-6">
+    <Heading variant="eyebrow">Workspace</Heading>
+    <Heading variant="page">Activity</Heading>
+    <section className="space-y-4">
+      <Heading variant="section">Recent items</Heading>
+      <Heading variant="subsection">Build details</Heading>
+      <p className="text-muted-foreground">Eyebrows are labels, not extra headings.</p>
+    </section>
+  </main>,
+  play: ({ canvasElement }) => {
+    const tags = Array.from(canvasElement.querySelectorAll("h1,h2,h3,h4,h5,h6")).map((node) => node.tagName).join(",");
+    if (tags !== "H1,H2,H3") throw new Error(`Unexpected heading hierarchy: ${tags}`);
+  },
+};

package/src/primitives/heading.test.tsx

@@ -0,0 +1,56 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Heading, type HeadingVariant } from "./heading";
+
+const roles: [HeadingVariant, string][] = [
+  ["display", "H1"], ["hero", "H2"], ["page", "H1"],
+  ["section", "H2"], ["subsection", "H3"], ["eyebrow", "P"],
+];
+
+describe("Heading", () => {
+  it.each(roles)("gives %s its existing default element", (variant, tag) => {
+    render(<Heading variant={variant}>Title</Heading>);
+    expect(screen.getByText("Title").tagName).toBe(tag);
+  });
+
+  it.each(roles)("maps Sandbox's %s role without emitting an invalid ARIA role", (role, tag) => {
+    render(<Heading role={role}>Title</Heading>);
+    const title = screen.getByText("Title");
+    expect(title.tagName).toBe(tag);
+    expect(title).not.toHaveAttribute("role");
+  });
+
+  it("changes semantics without changing the visual variant", () => {
+    const { rerender } = render(<Heading variant="page">Title</Heading>);
+    const classes = screen.getByRole("heading", { level: 1 }).className;
+    rerender(<Heading variant="page" as="h4">Title</Heading>);
+    expect(screen.getByRole("heading", { level: 4 }).className).toBe(classes);
+    expect(screen.queryByRole("heading", { level: 1 })).toBeNull();
+  });
+
+  it("lets an explicit variant win over the existing visual-role input", () => {
+    render(<Heading variant="section" role="page">Title</Heading>);
+    expect(screen.getByRole("heading", { level: 2 })).not.toHaveAttribute("role");
+  });
+
+  it("forwards native roles, refs and HTML attributes", () => {
+    const ref = createRef<HTMLElement>();
+    render(<Heading ref={ref} variant="eyebrow" as="div" role="note" id="scope" className="custom" data-scope="all">Scope</Heading>);
+    const note = screen.getByRole("note");
+    expect(ref.current).toBe(note);
+    expect(note).toHaveAttribute("id", "scope");
+    expect(note).toHaveAttribute("data-scope", "all");
+    expect(note).toHaveClass("custom");
+  });
+
+  it("keeps a page, section and nested title in document order", () => {
+    render(<main>
+      <Heading variant="page">Activity</Heading>
+      <Heading variant="eyebrow">Last day</Heading>
+      <Heading variant="section">Recent activity</Heading>
+      <Heading variant="subsection">Details</Heading>
+    </main>);
+    expect(screen.getAllByRole("heading").map((node) => node.tagName)).toEqual(["H1", "H2", "H3"]);
+  });
+});

package/src/primitives/heading.tsx

@@ -0,0 +1,76 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/** Visual roles ported from sandbox-ui/src/primitives/heading.tsx. */
+export type HeadingVariant =
+  | "display"
+  | "hero"
+  | "page"
+  | "section"
+  | "subsection"
+  | "eyebrow";
+
+// Keep Brand's existing size, leading, tracking and weight tokens. The literal
+// fallbacks are the existing Sandbox treatment, not a second type scale.
+const VARIANT_CLASS: Record<HeadingVariant, string> = {
+  display:
+    "font-display font-bold text-foreground text-[length:var(--font-size-display,3rem)] leading-[var(--line-height-display,1.05)] tracking-[var(--tracking-tight,-0.02em)]",
+  hero: "font-display font-bold text-foreground text-[length:var(--font-size-hero,2.5rem)] leading-[1.1] tracking-[var(--tracking-tight,-0.02em)]",
+  page: "font-display font-semibold text-foreground text-[length:var(--font-size-3xl,1.875rem)] leading-[var(--line-height-heading,1.15)] tracking-[var(--tracking-tight,-0.02em)]",
+  section:
+    "font-display font-semibold text-foreground text-[length:var(--font-size-xl,1.25rem)] leading-[1.3] tracking-[var(--tracking-snug,-0.01em)]",
+  subsection:
+    "font-semibold text-foreground text-[length:var(--font-size-lg,1rem)] leading-[1.4]",
+  eyebrow:
+    "font-semibold uppercase text-muted-foreground text-[length:var(--font-size-sm,0.75rem)] leading-none tracking-[var(--tracking-wide,0.08em)]",
+};
+
+const DEFAULT_TAG: Record<HeadingVariant, React.ElementType> = {
+  display: "h1",
+  hero: "h2",
+  page: "h1",
+  section: "h2",
+  subsection: "h3",
+  eyebrow: "p",
+};
+
+export interface HeadingProps
+  extends Omit<React.HTMLAttributes<HTMLElement>, "role"> {
+  /** Visual treatment, independent of the rendered element. Defaults to section. */
+  variant?: HeadingVariant;
+  /** Semantic element; changing it does not change the visual variant. */
+  as?: React.ElementType;
+  /**
+   * Native ARIA role, or Sandbox's existing visual-role input. Only the six
+   * legacy visual values are consumed; they are never emitted as ARIA roles.
+   * Prefer variant for new code. An explicit variant wins over a legacy role.
+   */
+  role?: React.AriaRole | HeadingVariant;
+}
+
+/**
+ * One renderer for page, section and card titles. Use at most one default
+ * display/page h1 per page; choose `as` according to the document hierarchy.
+ */
+const Heading = React.forwardRef<HTMLElement, HeadingProps>(
+  ({ variant, role, as, className, ...props }, ref) => {
+    const legacyVariant =
+      role && Object.prototype.hasOwnProperty.call(VARIANT_CLASS, role)
+        ? (role as HeadingVariant)
+        : undefined;
+    const visualVariant = variant ?? legacyVariant ?? "section";
+    const Tag = as ?? DEFAULT_TAG[visualVariant];
+
+    return (
+      <Tag
+        ref={ref}
+        className={cn("[overflow-wrap:anywhere]", VARIANT_CLASS[visualVariant], className)}
+        role={legacyVariant ? undefined : role}
+        {...props}
+      />
+    );
+  },
+);
+Heading.displayName = "Heading";
+
+export { Heading };

package/src/primitives/index.ts

@@ -9,6 +9,7 @@ export {
   CardDescription,
   CardContent,
 } from "./card";
+export type { CardTitleProps } from "./card";
 
 export {
   Dialog,
@@ -72,6 +73,7 @@ export {
   TableCell,
   TableCaption,
 } from "./table";
+export type { TableProps } from "./table";
 
 export { Tabs, TabsList, TabsTrigger, TabsContent } from "./tabs";
 
@@ -122,6 +124,12 @@ export type { CodeBlockProps, InlineCodeProps } from "./code-block";
 
 export { ThemeToggle, useTheme } from "./theme-toggle";
 
+export { Heading } from "./heading";
+export type { HeadingProps, HeadingVariant } from "./heading";
+
+export { PageShell } from "./page-shell";
+export type { PageShellProps } from "./page-shell";
+
 export { PageHeader } from "./page-header";
 export type { PageHeaderProps } from "./page-header";
 

package/src/primitives/input.stories.tsx

@@ -1,5 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react'
+import { useId } from 'react'
 import { Input, Textarea } from './input'
+import { Label } from './label'
 
 const meta: Meta<typeof Input> = {
   title: 'Primitives/Input',
@@ -111,3 +113,29 @@ export const Overview: Story = {
     </div>
   ),
 }
+
+export const FieldRelationships: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Repeated labels must focus their own fields. Inspect accessible descriptions: caller help, hints, and errors coexist. The final field uses an explicit ID and the standalone shared Label.',
+      },
+    },
+  },
+  render: function FieldRelationships() {
+    const id = useId()
+    const descriptionId = `${id}-instructions`
+    return (
+      <div className="flex w-96 flex-col gap-4">
+        <p id={descriptionId}>Shared instructions: choose a descriptive name.</p>
+        <Input label="Name" hint="First name." aria-describedby={descriptionId} />
+        <Input label="Name" hint="Second name." error="A name is required." aria-describedby={descriptionId} />
+        <Textarea label="Name" hint="Explain the name." error="More detail is needed." aria-describedby={descriptionId} />
+        <div className="space-y-1.5">
+          <Label htmlFor={`${id}-explicit`}>External label</Label>
+          <Input id={`${id}-explicit`} hint="Explicit field ID is preserved." />
+        </div>
+      </div>
+    )
+  },
+}