@nationaldesignstudio/react 0.0.14 → 0.0.16

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

@@ -0,0 +1,130 @@
+import { describe, expect, test, vi } from "vitest";
+import { page, userEvent } from "vitest/browser";
+import { render } from "vitest-browser-react";
+import { PagerControl } from "./pager-control";
+
+describe("PagerControl", () => {
+	describe("Accessibility", () => {
+		test("has correct tablist role", async () => {
+			render(<PagerControl count={4} autoPlay={false} />);
+			await expect
+				.element(page.getByRole("tablist", { name: "Page indicators" }))
+				.toBeInTheDocument();
+		});
+
+		test("renders correct number of tab buttons", async () => {
+			render(<PagerControl count={4} autoPlay={false} />);
+			const tabs = page.getByRole("tab").all();
+			expect(await tabs).toHaveLength(4);
+		});
+
+		test("active tab has aria-selected true", async () => {
+			render(<PagerControl count={4} activeIndex={1} autoPlay={false} />);
+			const tabs = page.getByRole("tab").all();
+			const tabElements = await tabs;
+			await expect
+				.element(tabElements[0])
+				.toHaveAttribute("aria-selected", "false");
+			await expect
+				.element(tabElements[1])
+				.toHaveAttribute("aria-selected", "true");
+		});
+
+		test("tabs have accessible labels", async () => {
+			render(<PagerControl count={3} activeIndex={0} autoPlay={false} />);
+			await expect
+				.element(page.getByRole("tab", { name: "Page 1 of 3, current" }))
+				.toBeInTheDocument();
+			await expect
+				.element(page.getByRole("tab", { name: "Go to page 2 of 3" }))
+				.toBeInTheDocument();
+		});
+
+		test("is focusable via keyboard", async () => {
+			render(<PagerControl count={4} autoPlay={false} />);
+			await userEvent.keyboard("{Tab}");
+			const firstTab = page.getByRole("tab").all();
+			await expect.element((await firstTab)[0]).toHaveFocus();
+		});
+	});
+
+	describe("Interactions", () => {
+		test("calls onChange when dot is clicked", async () => {
+			const handleChange = vi.fn();
+			render(
+				<PagerControl
+					count={4}
+					activeIndex={0}
+					onChange={handleChange}
+					autoPlay={false}
+				/>,
+			);
+			await page.getByRole("tab", { name: "Go to page 3 of 4" }).click();
+			expect(handleChange).toHaveBeenCalledWith(2);
+		});
+
+		test("clicking active dot calls onChange with same index", async () => {
+			const handleChange = vi.fn();
+			render(
+				<PagerControl
+					count={4}
+					activeIndex={1}
+					onChange={handleChange}
+					autoPlay={false}
+				/>,
+			);
+			await page.getByRole("tab", { name: "Page 2 of 4, current" }).click();
+			expect(handleChange).toHaveBeenCalledWith(1);
+		});
+
+		test("updates internal state when uncontrolled", async () => {
+			render(<PagerControl count={4} autoPlay={false} />);
+			// Initially first is active
+			await expect
+				.element(page.getByRole("tab", { name: "Page 1 of 4, current" }))
+				.toBeInTheDocument();
+
+			// Click third dot
+			await page.getByRole("tab", { name: "Go to page 3 of 4" }).click();
+
+			// Now third should be active
+			await expect
+				.element(page.getByRole("tab", { name: "Page 3 of 4, current" }))
+				.toBeInTheDocument();
+		});
+	});
+
+	describe("Variants", () => {
+		test("applies charcoal variant classes by default", async () => {
+			render(<PagerControl count={4} autoPlay={false} />);
+			const tabs = await page.getByRole("tab").all();
+			// Active dot track should have bg-alpha-black-30
+			await expect.element(tabs[0]).toHaveClass(/bg-alpha-black-30/);
+			// Inactive dots should have bg-alpha-black-30
+			await expect.element(tabs[1]).toHaveClass(/bg-alpha-black-30/);
+		});
+
+		test("applies ivory variant classes", async () => {
+			render(<PagerControl count={4} variant="ivory" autoPlay={false} />);
+			const tabs = await page.getByRole("tab").all();
+			// Active dot track should have bg-alpha-white-30
+			await expect.element(tabs[0]).toHaveClass(/bg-alpha-white-30/);
+			// Inactive dots should have bg-alpha-white-30
+			await expect.element(tabs[1]).toHaveClass(/bg-alpha-white-30/);
+		});
+	});
+
+	describe("Count", () => {
+		test("renders correct number of dots for count=2", async () => {
+			render(<PagerControl count={2} autoPlay={false} />);
+			const tabs = await page.getByRole("tab").all();
+			expect(tabs).toHaveLength(2);
+		});
+
+		test("renders correct number of dots for count=8", async () => {
+			render(<PagerControl count={8} autoPlay={false} />);
+			const tabs = await page.getByRole("tab").all();
+			expect(tabs).toHaveLength(8);
+		});
+	});
+});

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

@@ -0,0 +1,329 @@
+import * as React from "react";
+import { tv, type VariantProps } from "tailwind-variants";
+import { cn } from "@/lib/utils";
+
+const pagerControlVariants = tv({
+	base: "flex items-center",
+	variants: {
+		size: {
+			// Uses primitive spacing tokens
+			sm: "gap-spacing-2",
+			default: "gap-spacing-2",
+			lg: "gap-spacing-4",
+		},
+	},
+	defaultVariants: {
+		size: "default",
+	},
+});
+
+const dotBaseVariants = tv({
+	base: "cursor-pointer rounded-full transition-all duration-500 ease-[cubic-bezier(0.23,1,0.32,1)]",
+	variants: {
+		size: {
+			// Uses primitive spacing tokens
+			sm: "h-spacing-6",
+			default: "h-spacing-10",
+			lg: "h-spacing-16",
+		},
+		variant: {
+			charcoal: "",
+			ivory: "",
+		},
+	},
+	defaultVariants: {
+		size: "default",
+		variant: "charcoal",
+	},
+});
+
+export interface PagerControlProps
+	extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange">,
+		VariantProps<typeof pagerControlVariants>,
+		VariantProps<typeof dotBaseVariants> {
+	/**
+	 * Total number of pages/items
+	 */
+	count: number;
+	/**
+	 * Current active page index (0-based)
+	 */
+	activeIndex?: number;
+	/**
+	 * Duration in milliseconds for each page before auto-advancing
+	 * Set to 0 to disable auto-advance
+	 * @default 5000
+	 */
+	duration?: number;
+	/**
+	 * Whether the pager should auto-advance
+	 * @default true
+	 */
+	autoPlay?: boolean;
+	/**
+	 * Callback when the active page changes
+	 */
+	onChange?: (index: number) => void;
+	/**
+	 * Whether to pause auto-advance on hover
+	 * @default true
+	 */
+	pauseOnHover?: boolean;
+	/**
+	 * Whether to loop back to the first page after the last
+	 * @default true
+	 */
+	loop?: boolean;
+}
+
+/**
+ * PagerControl component for indicating progress through a series of pages/slides.
+ *
+ * Features smooth width transitions when switching between dots and an animated
+ * progress fill on the active dot that shows time remaining before auto-advancing
+ * (similar to Apple's carousel indicators).
+ *
+ * Variants:
+ * - charcoal: Dark dots (for light backgrounds)
+ * - ivory: Light dots (for dark backgrounds)
+ *
+ * Sizes:
+ * - sm: Small dots (6px height)
+ * - default: Medium dots (10px height)
+ * - lg: Large dots (16px height)
+ */
+const PagerControl = React.forwardRef<HTMLDivElement, PagerControlProps>(
+	(
+		{
+			className,
+			size,
+			variant,
+			count,
+			activeIndex: controlledIndex,
+			duration = 5000,
+			autoPlay = true,
+			onChange,
+			pauseOnHover = true,
+			loop = true,
+			...props
+		},
+		ref,
+	) => {
+		const [internalIndex, setInternalIndex] = React.useState(0);
+		const [isPaused, setIsPaused] = React.useState(false);
+		const [progress, setProgress] = React.useState(0);
+
+		// Use controlled index if provided, otherwise use internal state
+		const activeIndex =
+			controlledIndex !== undefined ? controlledIndex : internalIndex;
+		const isControlled = controlledIndex !== undefined;
+
+		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;
+			if (nextIndex >= count) {
+				if (loop) {
+					if (!isControlled) setInternalIndex(0);
+					onChange?.(0);
+				}
+			} else {
+				if (!isControlled) setInternalIndex(nextIndex);
+				onChange?.(nextIndex);
+			}
+		}, [activeIndex, count, loop, isControlled, onChange]);
+
+		const goToIndex = React.useCallback(
+			(index: number) => {
+				if (!isControlled) setInternalIndex(index);
+				onChange?.(index);
+				// Reset progress when manually changing
+				setProgress(0);
+				pausedProgressRef.current = 0;
+				startTimeRef.current = null;
+			},
+			[isControlled, onChange],
+		);
+
+		// Animation loop for smooth progress fill
+		React.useEffect(() => {
+			if (!autoPlay || duration <= 0 || isPaused) {
+				if (animationFrameRef.current) {
+					cancelAnimationFrame(animationFrameRef.current);
+					animationFrameRef.current = null;
+				}
+				return;
+			}
+
+			const animate = (timestamp: number) => {
+				if (startTimeRef.current === null) {
+					startTimeRef.current =
+						timestamp - (pausedProgressRef.current / 100) * duration;
+				}
+
+				const elapsed = timestamp - startTimeRef.current;
+				const newProgress = Math.min((elapsed / duration) * 100, 100);
+				setProgress(newProgress);
+
+				if (newProgress >= 100) {
+					goToNext();
+					// Reset for next cycle
+					setProgress(0);
+					pausedProgressRef.current = 0;
+					startTimeRef.current = null;
+				} else {
+					animationFrameRef.current = requestAnimationFrame(animate);
+				}
+			};
+
+			animationFrameRef.current = requestAnimationFrame(animate);
+
+			return () => {
+				if (animationFrameRef.current) {
+					cancelAnimationFrame(animationFrameRef.current);
+				}
+			};
+		}, [autoPlay, duration, isPaused, goToNext]);
+
+		// Handle pause/resume
+		const handleMouseEnter = React.useCallback(() => {
+			if (pauseOnHover) {
+				pausedProgressRef.current = progress;
+				startTimeRef.current = null;
+				setIsPaused(true);
+			}
+		}, [pauseOnHover, progress]);
+
+		const handleMouseLeave = React.useCallback(() => {
+			if (pauseOnHover) {
+				setIsPaused(false);
+			}
+		}, [pauseOnHover]);
+
+		// Reset progress when activeIndex changes externally (controlled mode)
+		React.useEffect(() => {
+			if (isControlled) {
+				setProgress(0);
+				pausedProgressRef.current = 0;
+				startTimeRef.current = null;
+			}
+		}, [isControlled]);
+
+		// Get dot dimensions based on size - uses primitive spacing tokens
+		const getDotWidth = (isActive: boolean) => {
+			if (isActive) {
+				switch (size) {
+					case "sm":
+						return "w-spacing-16";
+					case "lg":
+						return "w-spacing-36";
+					default:
+						return "w-spacing-28";
+				}
+			}
+			switch (size) {
+				case "sm":
+					return "w-spacing-6";
+				case "lg":
+					return "w-spacing-16";
+				default:
+					return "w-spacing-10";
+			}
+		};
+
+		// Get background classes for inactive dots
+		const getInactiveClasses = () => {
+			if (variant === "ivory") {
+				return "bg-alpha-white-30 hover:bg-alpha-white-60";
+			}
+			return "bg-alpha-black-30 hover:bg-alpha-black-60";
+		};
+
+		// Get background class for active dot (the track/background)
+		const getActiveTrackClass = () => {
+			if (variant === "ivory") {
+				return "bg-alpha-white-30";
+			}
+			return "bg-alpha-black-30";
+		};
+
+		// Get fill color for the progress indicator
+		const getProgressFillClass = () => {
+			if (variant === "ivory") {
+				return "bg-gray-50";
+			}
+			return "bg-gray-1200";
+		};
+
+		return (
+			<div
+				ref={ref}
+				role="tablist"
+				aria-label="Page indicators"
+				className={pagerControlVariants({ size, class: className })}
+				onMouseEnter={handleMouseEnter}
+				onMouseLeave={handleMouseLeave}
+				{...props}
+			>
+				{Array.from({ length: count }, (_, index) => {
+					const isActive = index === activeIndex;
+
+					if (isActive) {
+						// Active dot with progress fill
+						return (
+							<button
+								// biome-ignore lint/suspicious/noArrayIndexKey: Pagination dots have fixed order based on count
+								key={index}
+								type="button"
+								role="tab"
+								aria-selected={true}
+								aria-label={`Page ${index + 1} of ${count}, current`}
+								className={cn(
+									"relative cursor-pointer overflow-hidden rounded-full transition-all duration-500 ease-[cubic-bezier(0.23,1,0.32,1)]",
+									dotBaseVariants({ size, variant }),
+									getDotWidth(true),
+									getActiveTrackClass(),
+								)}
+								onClick={() => goToIndex(index)}
+							>
+								{/* Progress fill */}
+								<div
+									className={cn(
+										"absolute top-0 bottom-0 left-0 h-full rounded-full",
+										getProgressFillClass(),
+									)}
+									style={{
+										width: autoPlay && duration > 0 ? `${progress}%` : "100%",
+									}}
+								/>
+							</button>
+						);
+					}
+
+					// Inactive dot
+					return (
+						<button
+							// biome-ignore lint/suspicious/noArrayIndexKey: Pagination dots have fixed order based on count
+							key={index}
+							type="button"
+							role="tab"
+							aria-selected={false}
+							aria-label={`Go to page ${index + 1} of ${count}`}
+							className={cn(
+								dotBaseVariants({ size, variant }),
+								getDotWidth(false),
+								getInactiveClasses(),
+							)}
+							onClick={() => goToIndex(index)}
+						/>
+					);
+				})}
+			</div>
+		);
+	},
+);
+PagerControl.displayName = "PagerControl";
+
+export { PagerControl, pagerControlVariants };

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

@@ -0,0 +1,82 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { DevToolbar } from "./dev-toolbar";
+
+const meta = {
+	title: "Dev Tools/DevToolbar",
+	component: DevToolbar,
+	parameters: {
+		layout: "fullscreen",
+	},
+	argTypes: {
+		defaultExpanded: {
+			control: "boolean",
+		},
+	},
+} satisfies Meta<typeof DevToolbar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const DemoContent = () => (
+	<div className="min-h-screen bg-gray-100 py-spacing-64">
+		<div className="w-full max-w-[90rem] mx-auto px-[var(--spatial-grid-small-margin)] md:px-[var(--spatial-grid-medium-margin)] lg:px-[var(--spatial-grid-large-margin)]">
+			<h1 className="typography-headline-large mb-spacing-16">
+				Dev Toolbar Demo
+			</h1>
+			<p className="typography-body-medium text-gray-600 mb-spacing-8">
+				Click the bar at the bottom to expand, then toggle the Grid overlay.
+			</p>
+			<p className="typography-body-medium text-gray-600 mb-spacing-32">
+				Keyboard shortcut:{" "}
+				<kbd className="px-spacing-8 py-spacing-4 bg-gray-200 rounded-radius-8">
+					⌘G
+				</kbd>{" "}
+				or{" "}
+				<kbd className="px-spacing-8 py-spacing-4 bg-gray-200 rounded-radius-8">
+					Ctrl+G
+				</kbd>
+			</p>
+
+			<div className="grid grid-cols-4 md:grid-cols-12 lg:grid-cols-24 gap-[var(--spatial-grid-small-gutter)] md:gap-[var(--spatial-grid-medium-gutter)] lg:gap-[var(--spatial-grid-large-gutter)]">
+				{["alpha", "beta", "gamma", "delta", "epsilon", "zeta"].map((id) => (
+					<div
+						key={id}
+						className="col-span-4 md:col-span-4 lg:col-span-8 bg-white p-spacing-16 rounded-radius-12 shadow"
+					>
+						<h3 className="typography-headline-small mb-spacing-8">
+							Card {id}
+						</h3>
+						<p className="typography-body-small text-gray-500">
+							Sample content to visualize how the grid overlay aligns with your
+							layout.
+						</p>
+					</div>
+				))}
+			</div>
+		</div>
+	</div>
+);
+
+export const Default: Story = {
+	args: {
+		defaultExpanded: false,
+	},
+	render: (args) => (
+		<>
+			<DemoContent />
+			<DevToolbar {...args} />
+		</>
+	),
+};
+
+export const Expanded: Story = {
+	args: {
+		defaultExpanded: true,
+	},
+	render: (args) => (
+		<>
+			<DemoContent />
+			<DevToolbar {...args} />
+		</>
+	),
+};