@nationaldesignstudio/react 0.0.6 → 0.0.8

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

@@ -0,0 +1,212 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import * as React from "react";
+import { PagerControl } from ".";
+
+const meta: Meta<typeof PagerControl> = {
+	title: "Atoms/PagerControl",
+} as Meta<typeof PagerControl>;
+
+export default meta;
+type Story = StoryObj<typeof PagerControl>;
+
+export const Playground: Story = {
+	render: (args) => <PagerControl {...args} />,
+};
+Playground.argTypes = {
+	count: {
+		control: {
+			type: "number",
+			min: 1,
+			max: 10,
+		},
+	},
+	activeIndex: {
+		control: {
+			type: "number",
+			min: 0,
+		},
+	},
+	duration: {
+		control: {
+			type: "number",
+			min: 0,
+			max: 10000,
+			step: 500,
+		},
+	},
+	autoPlay: {
+		control: {
+			type: "boolean",
+		},
+	},
+	pauseOnHover: {
+		control: {
+			type: "boolean",
+		},
+	},
+	loop: {
+		control: {
+			type: "boolean",
+		},
+	},
+	size: {
+		control: {
+			type: "radio",
+		},
+		options: ["sm", "default", "lg"],
+	},
+	variant: {
+		control: {
+			type: "radio",
+		},
+		options: ["charcoal", "ivory"],
+	},
+};
+Playground.args = {
+	count: 4,
+	duration: 5000,
+	autoPlay: true,
+	pauseOnHover: true,
+	loop: true,
+	size: "default",
+	variant: "charcoal",
+};
+
+// =============================================================================
+// Variants
+// =============================================================================
+
+export const Charcoal = () => <PagerControl count={4} variant="charcoal" />;
+
+export const Ivory = () => <PagerControl count={4} variant="ivory" />;
+Ivory.parameters = {
+	backgrounds: { default: "dark" },
+};
+
+// =============================================================================
+// Sizes
+// =============================================================================
+
+export const Small = () => <PagerControl count={4} size="sm" />;
+
+export const Default = () => <PagerControl count={4} size="default" />;
+
+export const Large = () => <PagerControl count={4} size="lg" />;
+
+// =============================================================================
+// Counts
+// =============================================================================
+
+export const TwoPages = () => <PagerControl count={2} />;
+
+export const FivePages = () => <PagerControl count={5} />;
+
+export const EightPages = () => <PagerControl count={8} />;
+
+// =============================================================================
+// Durations
+// =============================================================================
+
+export const FastDuration = () => <PagerControl count={4} duration={2000} />;
+
+export const SlowDuration = () => <PagerControl count={4} duration={8000} />;
+
+// =============================================================================
+// Controls
+// =============================================================================
+
+export const NoAutoPlay = () => <PagerControl count={4} autoPlay={false} />;
+
+export const NoLoop = () => (
+	<PagerControl count={4} loop={false} duration={3000} />
+);
+
+export const NoPauseOnHover = () => (
+	<PagerControl count={4} pauseOnHover={false} />
+);
+
+// =============================================================================
+// Controlled
+// =============================================================================
+
+export const Controlled = () => {
+	const [activeIndex, setActiveIndex] = React.useState(0);
+
+	return (
+		<div className="flex flex-col items-center gap-spacing-24">
+			<PagerControl
+				count={4}
+				activeIndex={activeIndex}
+				onChange={setActiveIndex}
+				autoPlay={false}
+			/>
+			<div className="flex gap-spacing-10">
+				<button
+					type="button"
+					onClick={() => setActiveIndex((prev) => Math.max(0, prev - 1))}
+					className="rounded bg-gray-200 px-spacing-12 py-spacing-6"
+				>
+					Previous
+				</button>
+				<span className="px-spacing-12 py-spacing-6">
+					Page {activeIndex + 1} of 4
+				</span>
+				<button
+					type="button"
+					onClick={() => setActiveIndex((prev) => Math.min(3, prev + 1))}
+					className="rounded bg-gray-200 px-spacing-12 py-spacing-6"
+				>
+					Next
+				</button>
+			</div>
+		</div>
+	);
+};
+
+// =============================================================================
+// Integration Example
+// =============================================================================
+
+export const WithCarousel = () => {
+	const [activeIndex, setActiveIndex] = React.useState(0);
+	const slides = [
+		{ id: 1, color: "bg-blue-100", title: "Slide 1" },
+		{ id: 2, color: "bg-green-100", title: "Slide 2" },
+		{ id: 3, color: "bg-yellow-100", title: "Slide 3" },
+		{ id: 4, color: "bg-purple-100", title: "Slide 4" },
+	];
+
+	return (
+		<div className="flex w-[400px] flex-col gap-spacing-16">
+			<div className="relative h-[200px] overflow-hidden rounded-[12px]">
+				{slides.map((slide, index) => (
+					<div
+						key={slide.id}
+						className={cn(
+							"absolute inset-0 flex items-center justify-center transition-transform duration-500",
+							slide.color,
+						)}
+						style={{
+							transform: `translateX(${(index - activeIndex) * 100}%)`,
+						}}
+					>
+						<span className="text-xl font-semibold">{slide.title}</span>
+					</div>
+				))}
+			</div>
+			<div className="flex justify-center">
+				<PagerControl
+					count={slides.length}
+					activeIndex={activeIndex}
+					onChange={setActiveIndex}
+					duration={5000}
+				/>
+			</div>
+		</div>
+	);
+};
+
+// Helper for carousel story
+function cn(...classes: (string | boolean | undefined)[]) {
+	return classes.filter(Boolean).join(" ");
+}

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

@@ -0,0 +1,149 @@
+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/);
+		});
+
+		test("applies size classes correctly", async () => {
+			render(<PagerControl count={4} size="lg" autoPlay={false} />);
+			const tabs = await page.getByRole("tab").all();
+			// All dots should have lg height
+			await expect.element(tabs[0]).toHaveClass(/h-\[14px\]/);
+			await expect.element(tabs[1]).toHaveClass(/h-\[14px\]/);
+		});
+	});
+
+	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);
+		});
+	});
+
+	describe("Active dot width", () => {
+		test("active dot is wider than inactive dots", async () => {
+			render(<PagerControl count={4} autoPlay={false} />);
+			const tabs = await page.getByRole("tab").all();
+			// Active dot (first) should have wider width class
+			await expect.element(tabs[0]).toHaveClass(/w-\[26px\]/);
+			// Inactive dots should have smaller width
+			await expect.element(tabs[1]).toHaveClass(/w-\[10px\]/);
+		});
+	});
+});

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

@@ -0,0 +1,328 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+const pagerControlVariants = cva("flex items-center", {
+	variants: {
+		size: {
+			sm: "gap-[1px]",
+			default: "gap-[2px]",
+			lg: "gap-[3px]",
+		},
+	},
+	defaultVariants: {
+		size: "default",
+	},
+});
+
+const dotBaseVariants = cva(
+	"cursor-pointer rounded-full transition-all duration-500 ease-[cubic-bezier(0.23,1,0.32,1)]",
+	{
+		variants: {
+			size: {
+				sm: "h-[6px]",
+				default: "h-[10px]",
+				lg: "h-[14px]",
+			},
+			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 (14px 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
+		const getDotWidth = (isActive: boolean) => {
+			if (isActive) {
+				switch (size) {
+					case "sm":
+						return "w-[16px]";
+					case "lg":
+						return "w-[36px]";
+					default:
+						return "w-[26px]";
+				}
+			}
+			switch (size) {
+				case "sm":
+					return "w-[6px]";
+				case "lg":
+					return "w-[14px]";
+				default:
+					return "w-[10px]";
+			}
+		};
+
+		// 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={cn(pagerControlVariants({ size, 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 };