@nationaldesignstudio/react 0.0.17 → 0.1.0

package/src/components/atoms/button/icon-button.test.tsx

@@ -0,0 +1,254 @@
+import { describe, expect, test, vi } from "vitest";
+import { page, userEvent } from "vitest/browser";
+import { render } from "vitest-browser-react";
+import { IconButton } from "./icon-button";
+
+// Simple icon for testing
+const TestIcon = () => (
+	// biome-ignore lint/a11y/noSvgWithoutTitle: Test component doesn't need accessibility title
+	<svg data-testid="test-icon" width="24" height="24" viewBox="0 0 24 24">
+		<path d="M12 2L2 7l10 5 10-5-10-5z" />
+	</svg>
+);
+
+describe("IconButton", () => {
+	describe("Accessibility", () => {
+		test("has correct button role", async () => {
+			render(
+				<IconButton aria-label="Test action">
+					<TestIcon />
+				</IconButton>,
+			);
+			await expect
+				.element(page.getByRole("button", { name: "Test action" }))
+				.toBeInTheDocument();
+		});
+
+		test("is focusable via keyboard", async () => {
+			render(
+				<IconButton aria-label="Focusable">
+					<TestIcon />
+				</IconButton>,
+			);
+			await userEvent.keyboard("{Tab}");
+			await expect
+				.element(page.getByRole("button", { name: "Focusable" }))
+				.toHaveFocus();
+		});
+
+		test("disabled button has disabled attribute", async () => {
+			render(
+				<IconButton disabled aria-label="Disabled">
+					<TestIcon />
+				</IconButton>,
+			);
+			await expect
+				.element(page.getByRole("button", { name: "Disabled" }))
+				.toBeDisabled();
+		});
+
+		test("disabled button is not focusable", async () => {
+			render(
+				<>
+					<IconButton disabled aria-label="Disabled">
+						<TestIcon />
+					</IconButton>
+					<IconButton aria-label="After">
+						<TestIcon />
+					</IconButton>
+				</>,
+			);
+			await userEvent.keyboard("{Tab}");
+			await expect
+				.element(page.getByRole("button", { name: "After" }))
+				.toHaveFocus();
+		});
+
+		test("renders icon inside button", async () => {
+			render(
+				<IconButton aria-label="With icon">
+					<TestIcon />
+				</IconButton>,
+			);
+			const icon = page.getByTestId("test-icon");
+			await expect.element(icon).toBeInTheDocument();
+		});
+	});
+
+	describe("Interactions", () => {
+		test("calls onClick when clicked", async () => {
+			const handleClick = vi.fn();
+			render(
+				<IconButton onClick={handleClick} aria-label="Clickable">
+					<TestIcon />
+				</IconButton>,
+			);
+			await page.getByRole("button", { name: "Clickable" }).click();
+			expect(handleClick).toHaveBeenCalledOnce();
+		});
+
+		test("responds to Enter key when focused", async () => {
+			const handleClick = vi.fn();
+			render(
+				<IconButton onClick={handleClick} aria-label="Enter key">
+					<TestIcon />
+				</IconButton>,
+			);
+			page.getByRole("button", { name: "Enter key" }).element().focus();
+			await userEvent.keyboard("{Enter}");
+			expect(handleClick).toHaveBeenCalledOnce();
+		});
+
+		test("responds to Space key when focused", async () => {
+			const handleClick = vi.fn();
+			render(
+				<IconButton onClick={handleClick} aria-label="Space key">
+					<TestIcon />
+				</IconButton>,
+			);
+			page.getByRole("button", { name: "Space key" }).element().focus();
+			await userEvent.keyboard(" ");
+			expect(handleClick).toHaveBeenCalledOnce();
+		});
+
+		test("does not fire onClick when disabled", async () => {
+			const handleClick = vi.fn();
+			render(
+				<IconButton disabled onClick={handleClick} aria-label="Disabled">
+					<TestIcon />
+				</IconButton>,
+			);
+			await page
+				.getByRole("button", { name: "Disabled" })
+				.click({ force: true });
+			expect(handleClick).not.toHaveBeenCalled();
+		});
+	});
+
+	describe("render prop", () => {
+		test("renders as anchor element when render prop is used", async () => {
+			render(
+				// biome-ignore lint/a11y/useAnchorContent: Content is provided via IconButton children
+				<IconButton render={<a href="/test" />} aria-label="Link button">
+					<TestIcon />
+				</IconButton>,
+			);
+			const element = page.getByRole("link", { name: "Link button" });
+			await expect.element(element).toBeInTheDocument();
+			await expect.element(element).toHaveAttribute("href", "/test");
+		});
+	});
+
+	describe("Data attributes", () => {
+		test("includes data-variant attribute", async () => {
+			render(
+				<IconButton variant="ghost" aria-label="Ghost variant">
+					<TestIcon />
+				</IconButton>,
+			);
+			await expect
+				.element(page.getByRole("button", { name: "Ghost variant" }))
+				.toHaveAttribute("data-variant", "ghost");
+		});
+
+		test("includes data-size attribute", async () => {
+			render(
+				<IconButton size="lg" aria-label="Large size">
+					<TestIcon />
+				</IconButton>,
+			);
+			await expect
+				.element(page.getByRole("button", { name: "Large size" }))
+				.toHaveAttribute("data-size", "lg");
+		});
+
+		test("includes data-color-scheme attribute", async () => {
+			render(
+				<IconButton colorScheme="light" aria-label="Light scheme">
+					<TestIcon />
+				</IconButton>,
+			);
+			await expect
+				.element(page.getByRole("button", { name: "Light scheme" }))
+				.toHaveAttribute("data-color-scheme", "light");
+		});
+
+		test("includes data-rounded attribute", async () => {
+			render(
+				<IconButton rounded="full" aria-label="Full rounded">
+					<TestIcon />
+				</IconButton>,
+			);
+			await expect
+				.element(page.getByRole("button", { name: "Full rounded" }))
+				.toHaveAttribute("data-rounded", "full");
+		});
+
+		test("has default data attributes when not specified", async () => {
+			render(
+				<IconButton aria-label="Defaults">
+					<TestIcon />
+				</IconButton>,
+			);
+			const button = page.getByRole("button", { name: "Defaults" });
+			await expect.element(button).toHaveAttribute("data-variant", "solid");
+			await expect.element(button).toHaveAttribute("data-size", "default");
+			await expect.element(button).toHaveAttribute("data-color-scheme", "dark");
+			await expect.element(button).toHaveAttribute("data-rounded", "default");
+		});
+	});
+
+	describe("Variants", () => {
+		test("applies solid variant classes by default", async () => {
+			render(
+				<IconButton aria-label="Default">
+					<TestIcon />
+				</IconButton>,
+			);
+			const button = page.getByRole("button", { name: "Default" });
+			await expect.element(button).toHaveClass(/bg-gray-1200/);
+		});
+
+		test("applies ghost variant classes", async () => {
+			render(
+				<IconButton variant="ghost" aria-label="Ghost">
+					<TestIcon />
+				</IconButton>,
+			);
+			const button = page.getByRole("button", { name: "Ghost" });
+			await expect.element(button).toHaveClass(/text-gray-700/);
+		});
+	});
+
+	describe("Sizes", () => {
+		test("applies small size classes", async () => {
+			render(
+				<IconButton size="sm" aria-label="Small">
+					<TestIcon />
+				</IconButton>,
+			);
+			const button = page.getByRole("button", { name: "Small" });
+			await expect.element(button).toHaveClass(/size-32/);
+		});
+
+		test("applies default size classes", async () => {
+			render(
+				<IconButton size="default" aria-label="Default">
+					<TestIcon />
+				</IconButton>,
+			);
+			const button = page.getByRole("button", { name: "Default" });
+			await expect.element(button).toHaveClass(/size-40/);
+		});
+
+		test("applies large size classes", async () => {
+			render(
+				<IconButton size="lg" aria-label="Large">
+					<TestIcon />
+				</IconButton>,
+			);
+			const button = page.getByRole("button", { name: "Large" });
+			await expect.element(button).toHaveClass(/size-48/);
+		});
+	});
+});

package/src/components/atoms/button/icon-button.tsx

@@ -1,4 +1,6 @@
-import { Slot } from "@radix-ui/react-slot";
+"use client";
+
+import { useRender } from "@base-ui-components/react/use-render";
 import * as React from "react";
 import { tv, type VariantProps } from "tailwind-variants";
 
@@ -17,84 +19,174 @@ import { tv, type VariantProps } from "tailwind-variants";
  * <IconButton aria-label="Close menu">
  *   <CloseIcon />
  * </IconButton>
- *
- * // Correct usage with aria-labelledby
- * <IconButton aria-labelledby="close-label">
- *   <CloseIcon />
- * </IconButton>
- * <span id="close-label" className="sr-only">Close menu</span>
  * ```
  *
  * Variants:
- * - charcoal: Dark filled button (for light backgrounds)
- * - charcoalOutline: Dark outlined button (for light backgrounds)
- * - charcoalOutlineQuiet: Subtle dark outlined button (for light backgrounds)
- * - ghost: No background/border, just icon (for light backgrounds)
- * - ghostDark: No background/border, just icon (for dark backgrounds)
- * - ivory: Light filled button (for dark backgrounds)
- * - ivoryOutline: Light outlined button (for dark backgrounds)
- * - ivoryOutlineQuiet: Subtle light outlined button (for dark backgrounds)
+ * - solid: Filled button
+ * - outline: Outlined button
+ * - ghost: No background/border, just icon
+ * - subtle: Subtle outlined button
+ *
+ * Color Schemes:
+ * - dark: Dark colors for use on light backgrounds (default)
+ * - light: Light colors for use on dark backgrounds
  *
  * Sizes:
- * - lg: Large (46x46)
- * - default: Medium (36x36)
- * - sm: Small (29x29)
+ * - sm: Small (32x32)
+ * - default: Medium (40x40)
+ * - lg: Large (48x48)
+ *
+ * Rounded:
+ * - default: Standard border radius
+ * - sm: Smaller border radius
+ * - full: Fully circular
  */
 const iconButtonVariants = tv({
 	base: "inline-flex items-center justify-center whitespace-nowrap transition-colors duration-150 cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
 	variants: {
 		variant: {
-			// Charcoal (dark filled) - primary dark
-			charcoal:
+			solid: "",
+			outline: "border",
+			ghost: "",
+			subtle: "border",
+		},
+		colorScheme: {
+			dark: "",
+			light: "",
+		},
+		size: {
+			sm: "size-32",
+			default: "size-40",
+			lg: "size-48",
+		},
+		rounded: {
+			default: "rounded-radius-12",
+			sm: "rounded-radius-10",
+			full: "rounded-full",
+		},
+	},
+	compoundVariants: [
+		// Solid + Dark (for light backgrounds)
+		{
+			variant: "solid",
+			colorScheme: "dark",
+			class:
 				"bg-gray-1200 text-gray-100 hover:bg-gray-1100 active:bg-gray-1000 focus-visible:ring-gray-1000",
-			// Charcoal Outline - outlined dark (for light backgrounds)
-			charcoalOutline:
-				"border border-alpha-black-30 text-gray-1000 hover:bg-alpha-black-5 active:bg-alpha-black-10 focus-visible:ring-gray-1000",
-			// Charcoal Outline Quiet - subtle outlined dark (for light backgrounds)
-			charcoalOutlineQuiet:
-				"border border-alpha-black-20 text-alpha-black-60 hover:border-alpha-black-30 hover:text-alpha-black-80 active:bg-alpha-black-5 focus-visible:ring-gray-1000",
-			// Ghost - no background/border (for light backgrounds)
-			ghost:
+		},
+		// Solid + Light (for dark backgrounds)
+		{
+			variant: "solid",
+			colorScheme: "light",
+			class:
+				"bg-gray-50 text-gray-1000 hover:bg-gray-100 active:bg-gray-200 focus-visible:ring-gray-50 focus-visible:ring-offset-gray-1000",
+		},
+		// Outline + Dark (for light backgrounds)
+		{
+			variant: "outline",
+			colorScheme: "dark",
+			class:
+				"border-alpha-black-30 text-gray-1000 hover:bg-alpha-black-5 active:bg-alpha-black-10 focus-visible:ring-gray-1000",
+		},
+		// Outline + Light (for dark backgrounds)
+		{
+			variant: "outline",
+			colorScheme: "light",
+			class:
+				"border-gray-50 text-gray-50 hover:bg-alpha-white-10 active:bg-alpha-white-20 focus-visible:ring-gray-50 focus-visible:ring-offset-gray-1000",
+		},
+		// Ghost + Dark (for light backgrounds)
+		{
+			variant: "ghost",
+			colorScheme: "dark",
+			class:
 				"text-gray-700 hover:text-gray-900 hover:bg-alpha-black-5 active:bg-alpha-black-10 focus-visible:ring-gray-1000",
-			// Ghost Dark - no background/border (for dark backgrounds)
-			ghostDark:
+		},
+		// Ghost + Light (for dark backgrounds)
+		{
+			variant: "ghost",
+			colorScheme: "light",
+			class:
 				"text-gray-300 hover:text-gray-100 hover:bg-alpha-white-10 active:bg-alpha-white-20 focus-visible:ring-gray-50 focus-visible:ring-offset-gray-1000",
-			// Ivory (light filled) - primary light (for dark backgrounds)
-			ivory:
-				"bg-gray-50 text-gray-1000 hover:bg-gray-100 active:bg-gray-200 focus-visible:ring-gray-50 focus-visible:ring-offset-gray-1000",
-			// Ivory Outline - outlined light (for dark backgrounds)
-			ivoryOutline:
-				"border border-gray-50 text-gray-50 hover:bg-alpha-white-10 active:bg-alpha-white-20 focus-visible:ring-gray-50 focus-visible:ring-offset-gray-1000",
-			// Ivory Outline Quiet - subtle light outline (for dark backgrounds)
-			ivoryOutlineQuiet:
-				"border border-alpha-white-20 text-alpha-white-60 hover:border-alpha-white-30 hover:text-alpha-white-80 active:bg-alpha-white-5 focus-visible:ring-gray-50 focus-visible:ring-offset-gray-1000",
 		},
-		size: {
-			// Large (48x48) - uses primitive spacing tokens
-			lg: "rounded-radius-12 size-spacing-48",
-			// Medium (40x40) - default - uses primitive spacing tokens
-			default: "rounded-radius-12 size-spacing-40",
-			// Small (32x32) - uses primitive spacing tokens
-			sm: "rounded-radius-10 size-spacing-32",
+		// Subtle + Dark (for light backgrounds)
+		{
+			variant: "subtle",
+			colorScheme: "dark",
+			class:
+				"border-alpha-black-20 text-alpha-black-60 hover:border-alpha-black-30 hover:text-alpha-black-80 active:bg-alpha-black-5 focus-visible:ring-gray-1000",
 		},
-	},
+		// Subtle + Light (for dark backgrounds)
+		{
+			variant: "subtle",
+			colorScheme: "light",
+			class:
+				"border-alpha-white-20 text-alpha-white-60 hover:border-alpha-white-30 hover:text-alpha-white-80 active:bg-alpha-white-5 focus-visible:ring-gray-50 focus-visible:ring-offset-gray-1000",
+		},
+	],
 	defaultVariants: {
-		variant: "charcoal",
+		variant: "solid",
+		colorScheme: "dark",
 		size: "default",
+		rounded: "default",
 	},
 });
 
 export interface IconButtonProps
 	extends React.ButtonHTMLAttributes<HTMLButtonElement>,
 		VariantProps<typeof iconButtonVariants> {
+	/**
+	 * Custom render prop for element composition.
+	 * Accepts a React element or render function.
+	 * @example
+	 * ```tsx
+	 * // Render as a link
+	 * <IconButton render={<a href="/contact" />} aria-label="Contact">
+	 *   <LinkIcon />
+	 * </IconButton>
+	 *
+	 * // Render with custom element
+	 * <IconButton render={(props) => <Link {...props} to="/home" />} aria-label="Home">
+	 *   <HomeIcon />
+	 * </IconButton>
+	 * ```
+	 */
+	render?:
+		| React.ReactElement
+		| ((
+				props: React.ButtonHTMLAttributes<HTMLButtonElement>,
+		  ) => React.ReactElement);
+	/**
+	 * @deprecated Use `render` prop instead for element composition.
+	 * @example
+	 * ```tsx
+	 * // Old (deprecated)
+	 * <IconButton asChild><a href="/link">...</a></IconButton>
+	 *
+	 * // New (recommended)
+	 * <IconButton render={<a href="/link" />}>...</IconButton>
+	 * ```
+	 */
 	asChild?: boolean;
 }
 
 const IconButton = React.forwardRef<HTMLButtonElement, IconButtonProps>(
-	({ className, variant, size, asChild = false, ...props }, ref) => {
-		// Development warning for missing accessible label
+	(
+		{
+			className,
+			variant,
+			colorScheme,
+			size,
+			rounded,
+			render,
+			asChild,
+			...props
+		},
+		ref,
+	) => {
+		// Development warnings
 		React.useEffect(() => {
 			if (import.meta.env?.DEV) {
+				// Warn about missing accessible label
 				const hasAccessibleLabel =
 					props["aria-label"] || props["aria-labelledby"] || props.title;
 				if (!hasAccessibleLabel) {
@@ -102,17 +194,44 @@ const IconButton = React.forwardRef<HTMLButtonElement, IconButtonProps>(
 						"IconButton: Missing accessible label. Icon-only buttons must have an aria-label, aria-labelledby, or title attribute for screen reader users.",
 					);
 				}
+				// Warn about deprecated asChild prop
+				if (asChild !== undefined) {
+					console.warn(
+						'IconButton: The "asChild" prop is deprecated. Use the "render" prop instead for element composition.\n' +
+							'Example: <IconButton render={<a href="/link" />}>...</IconButton>',
+					);
+				}
 			}
-		}, [props["aria-label"], props["aria-labelledby"], props.title]);
+		}, [props["aria-label"], props["aria-labelledby"], props.title, asChild]);
+
+		// Resolve actual values for data attributes
+		const resolvedVariant = variant ?? "solid";
+		const resolvedColorScheme = colorScheme ?? "dark";
+		const resolvedSize = size ?? "default";
+		const resolvedRounded = rounded ?? "default";
+
+		const mergedProps = {
+			className: iconButtonVariants({
+				variant,
+				colorScheme,
+				size,
+				rounded,
+				class: className,
+			}),
+			"data-variant": resolvedVariant,
+			"data-color-scheme": resolvedColorScheme,
+			"data-size": resolvedSize,
+			"data-rounded": resolvedRounded,
+			...props,
+		};
+
+		const element = useRender({
+			render: render ?? <button type="button" />,
+			ref,
+			props: mergedProps,
+		});
 
-		const Comp = asChild ? Slot : "button";
-		return (
-			<Comp
-				className={iconButtonVariants({ variant, size, class: className })}
-				ref={ref}
-				{...props}
-			/>
-		);
+		return element;
 	},
 );
 IconButton.displayName = "IconButton";

package/src/components/atoms/pager-control/pager-control.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import * as React from "react";
 import { tv, type VariantProps } from "tailwind-variants";
 import { cn } from "@/lib/utils";
@@ -118,12 +120,39 @@ const PagerControl = React.forwardRef<HTMLDivElement, PagerControlProps>(
 			controlledIndex !== undefined ? controlledIndex : internalIndex;
 		const isControlled = controlledIndex !== undefined;
 
+		// Development warnings for common issues
+		React.useEffect(() => {
+			if (import.meta.env?.DEV) {
+				if (count < 1) {
+					console.warn("PagerControl: count must be at least 1");
+				}
+				if (controlledIndex !== undefined && controlledIndex >= count) {
+					console.warn(
+						`PagerControl: activeIndex (${controlledIndex}) is out of bounds. Must be less than count (${count}).`,
+					);
+				}
+				if (controlledIndex !== undefined && controlledIndex < 0) {
+					console.warn(
+						`PagerControl: activeIndex (${controlledIndex}) cannot be negative.`,
+					);
+				}
+				if (isControlled && onChange === undefined) {
+					console.warn(
+						"PagerControl: controlled mode (activeIndex provided) requires an onChange handler.",
+					);
+				}
+			}
+		}, [count, controlledIndex, isControlled, onChange]);
+
+		// Clamp activeIndex to valid bounds
+		const safeActiveIndex = Math.max(0, Math.min(activeIndex, count - 1));
+
 		const animationFrameRef = React.useRef<number | null>(null);
 		const startTimeRef = React.useRef<number | null>(null);
 		const pausedProgressRef = React.useRef<number>(0);
 
 		const goToNext = React.useCallback(() => {
-			const nextIndex = activeIndex + 1;
+			const nextIndex = safeActiveIndex + 1;
 			if (nextIndex >= count) {
 				if (loop) {
 					if (!isControlled) setInternalIndex(0);
@@ -133,7 +162,7 @@ const PagerControl = React.forwardRef<HTMLDivElement, PagerControlProps>(
 				if (!isControlled) setInternalIndex(nextIndex);
 				onChange?.(nextIndex);
 			}
-		}, [activeIndex, count, loop, isControlled, onChange]);
+		}, [safeActiveIndex, count, loop, isControlled, onChange]);
 
 		const goToIndex = React.useCallback(
 			(index: number) => {
@@ -268,7 +297,7 @@ const PagerControl = React.forwardRef<HTMLDivElement, PagerControlProps>(
 				{...props}
 			>
 				{Array.from({ length: count }, (_, index) => {
-					const isActive = index === activeIndex;
+					const isActive = index === safeActiveIndex;
 
 					if (isActive) {
 						// Active dot with progress fill

package/src/components/dev-tools/dev-toolbar/dev-toolbar.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { useCallback, useEffect, useRef, useState } from "react";
 import { GridOverlay } from "../grid-overlay";