@nationaldesignstudio/react 0.0.15 → 0.0.16

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} />
+		</>
+	),
+};

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

@@ -0,0 +1,196 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { GridOverlay } from "../grid-overlay";
+
+function GridIcon({ active }: { active?: boolean }) {
+	return (
+		<svg
+			width="20"
+			height="20"
+			viewBox="0 0 20 20"
+			fill="none"
+			stroke="currentColor"
+			strokeWidth={active ? "2" : "1.5"}
+			aria-hidden="true"
+		>
+			<rect x="2" y="2" width="16" height="16" rx="2" />
+			<line x1="7" y1="2" x2="7" y2="18" />
+			<line x1="13" y1="2" x2="13" y2="18" />
+		</svg>
+	);
+}
+
+export interface DevToolbarProps {
+	defaultExpanded?: boolean;
+}
+
+const DRAG_THRESHOLD = 3;
+
+export function DevToolbar({ defaultExpanded = false }: DevToolbarProps) {
+	const [isExpanded, setIsExpanded] = useState(defaultExpanded);
+	const [showGrid, setShowGrid] = useState(false);
+	const [position, setPosition] = useState({ x: 0, y: 0 });
+	const [isDragging, setIsDragging] = useState(false);
+	const hasDraggedRef = useRef(false);
+	const dragRef = useRef<{
+		startX: number;
+		startY: number;
+		startPosX: number;
+		startPosY: number;
+	} | null>(null);
+	const toolbarRef = useRef<HTMLDivElement>(null);
+
+	const toggleGrid = useCallback(() => setShowGrid((prev) => !prev), []);
+	const toggleExpanded = useCallback(() => setIsExpanded((prev) => !prev), []);
+
+	useEffect(() => {
+		const handleKeyDown = (e: KeyboardEvent) => {
+			if ((e.ctrlKey || e.metaKey) && e.key === "g") {
+				e.preventDefault();
+				toggleGrid();
+			}
+		};
+
+		window.addEventListener("keydown", handleKeyDown);
+		return () => window.removeEventListener("keydown", handleKeyDown);
+	}, [toggleGrid]);
+
+	const handleDragStart = useCallback(
+		(clientX: number, clientY: number) => {
+			setIsDragging(true);
+			hasDraggedRef.current = false;
+			dragRef.current = {
+				startX: clientX,
+				startY: clientY,
+				startPosX: position.x,
+				startPosY: position.y,
+			};
+		},
+		[position],
+	);
+
+	const handleDragMove = useCallback(
+		(clientX: number, clientY: number) => {
+			if (!isDragging || !dragRef.current) return;
+
+			const deltaX = clientX - dragRef.current.startX;
+			const deltaY = clientY - dragRef.current.startY;
+
+			if (
+				Math.abs(deltaX) > DRAG_THRESHOLD ||
+				Math.abs(deltaY) > DRAG_THRESHOLD
+			) {
+				hasDraggedRef.current = true;
+			}
+
+			setPosition({
+				x: dragRef.current.startPosX + deltaX,
+				y: dragRef.current.startPosY - deltaY,
+			});
+		},
+		[isDragging],
+	);
+
+	const handleDragEnd = useCallback(() => {
+		setIsDragging(false);
+		dragRef.current = null;
+	}, []);
+
+	useEffect(() => {
+		if (!isDragging) return;
+
+		const handleMouseMove = (e: MouseEvent) =>
+			handleDragMove(e.clientX, e.clientY);
+		const handleTouchMove = (e: TouchEvent) => {
+			if (e.touches[0])
+				handleDragMove(e.touches[0].clientX, e.touches[0].clientY);
+		};
+		const handleEnd = () => handleDragEnd();
+
+		window.addEventListener("mousemove", handleMouseMove);
+		window.addEventListener("mouseup", handleEnd);
+		window.addEventListener("touchmove", handleTouchMove);
+		window.addEventListener("touchend", handleEnd);
+
+		return () => {
+			window.removeEventListener("mousemove", handleMouseMove);
+			window.removeEventListener("mouseup", handleEnd);
+			window.removeEventListener("touchmove", handleTouchMove);
+			window.removeEventListener("touchend", handleEnd);
+		};
+	}, [isDragging, handleDragMove, handleDragEnd]);
+
+	const handleBarMouseDown = (e: React.MouseEvent) => {
+		e.preventDefault();
+		handleDragStart(e.clientX, e.clientY);
+	};
+
+	const handleBarTouchStart = (e: React.TouchEvent) => {
+		if (e.touches[0]) {
+			handleDragStart(e.touches[0].clientX, e.touches[0].clientY);
+		}
+	};
+
+	const handleBarClick = () => {
+		if (!hasDraggedRef.current) {
+			toggleExpanded();
+		}
+		hasDraggedRef.current = false;
+	};
+
+	return (
+		<>
+			{showGrid && <GridOverlay />}
+
+			<div
+				ref={toolbarRef}
+				className="fixed bottom-4 left-1/2 z-[9999]"
+				style={{
+					transform: `translate(calc(-50% + ${position.x}px), ${-position.y}px)`,
+				}}
+				data-testid="dev-toolbar"
+			>
+				<div
+					className={`bg-gray-1100 rounded-radius-16 shadow-lg flex flex-col items-center overflow-hidden px-spacing-12 py-spacing-8 ${isExpanded ? "gap-spacing-4" : ""}`}
+				>
+					<div
+						className={`
+							grid transition-all duration-300 ease-out
+							${isExpanded ? "grid-rows-[1fr] opacity-100" : "grid-rows-[0fr] opacity-0"}
+						`}
+					>
+						<div className="overflow-hidden">
+							<button
+								type="button"
+								onClick={toggleGrid}
+								className={`
+									size-spacing-40 rounded-full flex items-center justify-center transition-colors
+									${
+										showGrid
+											? "text-gray-50"
+											: "text-gray-400 hover:text-gray-50 hover:bg-alpha-white-10"
+									}
+								`}
+								title="Toggle Grid (⌘G)"
+								aria-label="Toggle grid overlay"
+							>
+								<GridIcon active={showGrid} />
+							</button>
+						</div>
+					</div>
+
+					<button
+						type="button"
+						onMouseDown={handleBarMouseDown}
+						onTouchStart={handleBarTouchStart}
+						onClick={handleBarClick}
+						className={`
+							w-spacing-32 h-spacing-4 bg-gray-50 rounded-full transition-opacity
+							${isDragging ? "opacity-100 cursor-grabbing" : "opacity-60 hover:opacity-100 cursor-grab"}
+						`}
+						aria-label={isExpanded ? "Close dev tools" : "Open dev tools"}
+					/>
+				</div>
+			</div>
+		</>
+	);
+}

package/src/components/dev-tools/dev-toolbar/index.ts

@@ -0,0 +1 @@
+export { DevToolbar, type DevToolbarProps } from "./dev-toolbar";

package/src/components/dev-tools/grid-overlay/grid-overlay.tsx

@@ -0,0 +1,41 @@
+export interface GridOverlayProps {
+	columnOpacity?: number;
+	borderOpacity?: number;
+	visible?: boolean;
+}
+
+export function GridOverlay({
+	columnOpacity = 0.15,
+	borderOpacity = 0.3,
+	visible = true,
+}: GridOverlayProps) {
+	const columns = Array.from({ length: 24 }, (_, i) => i);
+
+	return (
+		<div
+			className={`
+				fixed inset-0 z-[9998] pointer-events-none overflow-hidden
+				transition-opacity duration-300 ease-out
+				${visible ? "opacity-100" : "opacity-0"}
+			`}
+			aria-hidden="true"
+			data-testid="grid-overlay"
+		>
+			<div className="h-full 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)]">
+				<div className="h-full 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)]">
+					{columns.map((index) => (
+						<div
+							key={index}
+							className="h-full border border-red-500"
+							style={{
+								backgroundColor: `rgb(239 68 68 / ${columnOpacity})`,
+								borderColor: `rgb(239 68 68 / ${borderOpacity})`,
+							}}
+							data-column={index + 1}
+						/>
+					))}
+				</div>
+			</div>
+		</div>
+	);
+}

package/src/components/dev-tools/grid-overlay/index.ts

@@ -0,0 +1 @@
+export { GridOverlay, type GridOverlayProps } from "./grid-overlay";

package/src/components/dev-tools/index.ts

@@ -0,0 +1,2 @@
+export { DevToolbar, type DevToolbarProps } from "./dev-toolbar";
+export { GridOverlay, type GridOverlayProps } from "./grid-overlay";