@nationaldesignstudio/react 0.0.19 → 0.2.0

package/src/components/atoms/background/background.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import * as React from "react";
 import { tv } from "tailwind-variants";
 
@@ -56,28 +58,69 @@ export interface BackgroundImageProps
 	 * Object position (default: "center")
 	 */
 	position?: string;
+	/**
+	 * Custom render prop for element composition.
+	 * Accepts a React element or render function.
+	 * @example
+	 * ```tsx
+	 * // Element pattern
+	 * <BackgroundImage render={<img className="custom" />} src="/bg.jpg" />
+	 *
+	 * // Callback pattern
+	 * <BackgroundImage render={(props) => <img {...props} />} src="/bg.jpg" />
+	 * ```
+	 */
+	render?:
+		| React.ReactElement
+		| ((
+				props: React.ImgHTMLAttributes<HTMLImageElement>,
+		  ) => React.ReactElement);
 }
 
 /**
  * Background image layer using an actual img element with object-cover.
  * Supports native lazy loading, srcset, and better accessibility.
+ * Supports render prop for element composition.
  */
 const BackgroundImage = React.forwardRef<
 	HTMLImageElement,
 	BackgroundImageProps
->(({ className, src, position = "center", alt = "", style, ...props }, ref) => (
-	<img
-		ref={ref}
-		src={src}
-		alt={alt}
-		className={backgroundImageVariants({ class: className })}
-		style={{
-			objectPosition: position,
-			...style,
-		}}
-		{...props}
-	/>
-));
+>(
+	(
+		{ className, src, position = "center", alt = "", style, render, ...props },
+		ref,
+	) => {
+		const imgClassName = backgroundImageVariants({ class: className });
+		const imgStyle = { objectPosition: position, ...style };
+		const imgProps = {
+			src,
+			alt,
+			className: imgClassName,
+			style: imgStyle,
+			...props,
+		};
+
+		// Handle render prop (element or function)
+		if (render) {
+			if (typeof render === "function") {
+				return render({
+					ref,
+					...imgProps,
+				} as React.ImgHTMLAttributes<HTMLImageElement>);
+			}
+			// Clone the render element with merged props
+			return React.cloneElement(render, {
+				ref,
+				...imgProps,
+				...(render.props as Record<string, unknown>),
+			});
+		}
+
+		// Default: render as img
+		// biome-ignore lint/a11y/useAltText: alt is provided via imgProps spread
+		return <img ref={ref} {...imgProps} />;
+	},
+);
 BackgroundImage.displayName = "Background.Image";
 
 // =============================================================================
@@ -102,10 +145,23 @@ export interface BackgroundVideoProps
 	 * Poster image URL shown before video loads
 	 */
 	poster?: string;
+	/**
+	 * Custom render prop for element composition.
+	 * @example
+	 * ```tsx
+	 * <BackgroundVideo render={<video className="custom" />} src="/bg.mp4" />
+	 * ```
+	 */
+	render?:
+		| React.ReactElement
+		| ((
+				props: React.VideoHTMLAttributes<HTMLVideoElement>,
+		  ) => React.ReactElement);
 }
 
 /**
  * Background video layer using HTML5 video element.
+ * Supports render prop for element composition.
  */
 const BackgroundVideo = React.forwardRef<
 	HTMLVideoElement,
@@ -121,23 +177,44 @@ const BackgroundVideo = React.forwardRef<
 			loop = true,
 			muted = true,
 			playsInline = true,
+			render,
 			...props
 		},
 		ref,
-	) => (
-		<video
-			ref={ref}
-			autoPlay={autoPlay}
-			loop={loop}
-			muted={muted}
-			playsInline={playsInline}
-			poster={poster}
-			className={backgroundVideoVariants({ class: className })}
-			{...props}
-		>
-			<source src={src} type={type} />
-		</video>
-	),
+	) => {
+		const videoClassName = backgroundVideoVariants({ class: className });
+		const videoProps = {
+			autoPlay,
+			loop,
+			muted,
+			playsInline,
+			poster,
+			className: videoClassName,
+			...props,
+		};
+
+		// Handle render prop (element or function)
+		if (render) {
+			if (typeof render === "function") {
+				return render({
+					ref,
+					...videoProps,
+				} as React.VideoHTMLAttributes<HTMLVideoElement>);
+			}
+			// Clone the render element with merged props
+			return React.cloneElement(render, {
+				...videoProps,
+				...(render.props as Record<string, unknown>),
+			});
+		}
+
+		// Default: render as video with source
+		return (
+			<video ref={ref} {...videoProps}>
+				<source src={src} type={type} />
+			</video>
+		);
+	},
 );
 BackgroundVideo.displayName = "Background.Video";
 

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

@@ -1,3 +1,5 @@
+"use client";
+
 import {
 	Button as BaseButton,
 	type ButtonProps as BaseButtonProps,
@@ -72,7 +74,7 @@ const buttonVariants = tv({
 			variant: "outline",
 			colorScheme: "dark",
 			class:
-				"border-border-strong text-gray-1000 hover:bg-alpha-black-5 active:bg-alpha-black-10 focus-visible:ring-gray-1000",
+				"border-border-subtle text-gray-1000 hover:bg-alpha-black-5 active:bg-alpha-black-10 focus-visible:ring-gray-1000",
 		},
 		// Outline + Light (for dark backgrounds)
 		{
@@ -159,6 +161,11 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
 		const themeStyles = buttonThemeToStyleVars(theme);
 		const combinedStyles = hasTheme ? { ...themeStyles, ...style } : style;
 
+		// Resolve actual values for data attributes
+		const resolvedVariant = effectiveVariant ?? "solid";
+		const resolvedColorScheme = colorScheme ?? "dark";
+		const resolvedSize = size ?? "default";
+
 		return (
 			<BaseButton
 				className={buttonVariants({
@@ -171,6 +178,9 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
 				render={render}
 				nativeButton={isNativeButton}
 				style={combinedStyles}
+				data-variant={resolvedVariant}
+				data-color-scheme={resolvedColorScheme}
+				data-size={resolvedSize}
 				{...props}
 			/>
 		);

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,3 +1,5 @@
+"use client";
+
 import { Slot } from "@radix-ui/react-slot";
 import * as React from "react";
 import { tv, type VariantProps } from "tailwind-variants";
@@ -30,9 +32,9 @@ import { tv, type VariantProps } from "tailwind-variants";
  * - light: Light colors for use on dark backgrounds
  *
  * Sizes:
- * - lg: Large (48x48)
- * - default: Medium (40x40)
  * - sm: Small (32x32)
+ * - default: Medium (40x40)
+ * - lg: Large (48x48)
  *
  * Rounded:
  * - default: Standard border radius
@@ -53,9 +55,9 @@ const iconButtonVariants = tv({
 			light: "",
 		},
 		size: {
-			lg: "size-48",
-			default: "size-40",
 			sm: "size-32",
+			default: "size-40",
+			lg: "size-48",
 		},
 		rounded: {
 			default: "rounded-radius-12",
@@ -132,6 +134,38 @@ const iconButtonVariants = tv({
 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;
 }
 
@@ -143,14 +177,16 @@ const IconButton = React.forwardRef<HTMLButtonElement, IconButtonProps>(
 			colorScheme,
 			size,
 			rounded,
-			asChild = false,
+			render,
+			asChild,
 			...props
 		},
 		ref,
 	) => {
-		// Development warning for missing accessible label
+		// 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) {
@@ -158,20 +194,76 @@ 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 buttonClassName = iconButtonVariants({
+			variant,
+			colorScheme,
+			size,
+			rounded,
+			class: className,
+		});
+
+		const dataAttributes = {
+			"data-variant": resolvedVariant,
+			"data-color-scheme": resolvedColorScheme,
+			"data-size": resolvedSize,
+			"data-rounded": resolvedRounded,
+		};
+
+		// Handle render prop (element or function)
+		if (render) {
+			if (typeof render === "function") {
+				return render({
+					ref,
+					className: buttonClassName,
+					...dataAttributes,
+					...props,
+				} as React.ButtonHTMLAttributes<HTMLButtonElement>);
+			}
+			// Clone the render element with merged props
+			return React.cloneElement(render, {
+				ref,
+				className: buttonClassName,
+				...dataAttributes,
+				...props,
+				...(render.props as Record<string, unknown>),
+			});
+		}
+
+		// Handle deprecated asChild prop
+		if (asChild) {
+			return (
+				<Slot
+					ref={ref}
+					className={buttonClassName}
+					{...dataAttributes}
+					{...props}
+				/>
+			);
+		}
 
-		const Comp = asChild ? Slot : "button";
+		// Default: render as button
 		return (
-			<Comp
-				className={iconButtonVariants({
-					variant,
-					colorScheme,
-					size,
-					rounded,
-					class: className,
-				})}
+			<button
 				ref={ref}
+				type="button"
+				className={buttonClassName}
+				{...dataAttributes}
 				{...props}
 			/>
 		);

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";