@nationaldesignstudio/react 0.5.4 → 0.5.6

package/src/hooks/use-breakpoint.ts

@@ -0,0 +1,145 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Design system breakpoint values in pixels.
+ * These match the primitive breakpoint tokens from packages/tokens.
+ */
+export const BREAKPOINTS = {
+	sm: 320,
+	md: 768,
+	lg: 1440,
+} as const;
+
+export type Breakpoint = keyof typeof BREAKPOINTS;
+
+/**
+ * Get the current breakpoint based on viewport width.
+ */
+function getCurrentBreakpoint(width: number): Breakpoint {
+	if (width >= BREAKPOINTS.lg) return "lg";
+	if (width >= BREAKPOINTS.md) return "md";
+	return "sm";
+}
+
+/**
+ * Hook to get the current responsive breakpoint.
+ * Returns the active breakpoint name based on viewport width.
+ *
+ * @returns The current breakpoint: 'sm' | 'md' | 'lg'
+ *
+ * @example
+ * ```tsx
+ * function Component() {
+ *   const breakpoint = useBreakpoint();
+ *
+ *   return (
+ *     <div>
+ *       {breakpoint === 'sm' && <MobileLayout />}
+ *       {breakpoint === 'md' && <TabletLayout />}
+ *       {breakpoint === 'lg' && <DesktopLayout />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useBreakpoint(): Breakpoint {
+	const [breakpoint, setBreakpoint] = React.useState<Breakpoint>(() => {
+		if (typeof window === "undefined") return "sm";
+		return getCurrentBreakpoint(window.innerWidth);
+	});
+
+	React.useEffect(() => {
+		const handleResize = () => {
+			setBreakpoint(getCurrentBreakpoint(window.innerWidth));
+		};
+
+		// Set initial value
+		handleResize();
+
+		window.addEventListener("resize", handleResize);
+		return () => window.removeEventListener("resize", handleResize);
+	}, []);
+
+	return breakpoint;
+}
+
+/**
+ * Hook to check if viewport is at or above a specific breakpoint.
+ *
+ * @param breakpoint - The minimum breakpoint to check against
+ * @returns boolean indicating if viewport is at or above the breakpoint
+ *
+ * @example
+ * ```tsx
+ * function Component() {
+ *   const isDesktop = useMinBreakpoint('lg');
+ *   const isTabletUp = useMinBreakpoint('md');
+ *
+ *   return isDesktop ? <DesktopView /> : <MobileView />;
+ * }
+ * ```
+ */
+export function useMinBreakpoint(breakpoint: Breakpoint): boolean {
+	const [matches, setMatches] = React.useState<boolean>(() => {
+		if (typeof window === "undefined") return false;
+		return window.innerWidth >= BREAKPOINTS[breakpoint];
+	});
+
+	React.useEffect(() => {
+		const mediaQuery = window.matchMedia(
+			`(min-width: ${BREAKPOINTS[breakpoint]}px)`,
+		);
+
+		setMatches(mediaQuery.matches);
+
+		const handleChange = (event: MediaQueryListEvent) => {
+			setMatches(event.matches);
+		};
+
+		mediaQuery.addEventListener("change", handleChange);
+		return () => mediaQuery.removeEventListener("change", handleChange);
+	}, [breakpoint]);
+
+	return matches;
+}
+
+/**
+ * Hook to check if viewport is below a specific breakpoint.
+ *
+ * @param breakpoint - The breakpoint to check against
+ * @returns boolean indicating if viewport is below the breakpoint
+ *
+ * @example
+ * ```tsx
+ * function Component() {
+ *   const isMobile = useMaxBreakpoint('md'); // Below tablet
+ *
+ *   return isMobile ? <MobileNav /> : <DesktopNav />;
+ * }
+ * ```
+ */
+export function useMaxBreakpoint(breakpoint: Breakpoint): boolean {
+	const [matches, setMatches] = React.useState<boolean>(() => {
+		if (typeof window === "undefined") return false;
+		return window.innerWidth < BREAKPOINTS[breakpoint];
+	});
+
+	React.useEffect(() => {
+		const mediaQuery = window.matchMedia(
+			`(max-width: ${BREAKPOINTS[breakpoint] - 1}px)`,
+		);
+
+		setMatches(mediaQuery.matches);
+
+		const handleChange = (event: MediaQueryListEvent) => {
+			setMatches(event.matches);
+		};
+
+		mediaQuery.addEventListener("change", handleChange);
+		return () => mediaQuery.removeEventListener("change", handleChange);
+	}, [breakpoint]);
+
+	return matches;
+}

package/src/hooks/use-captions.ts

@@ -0,0 +1,247 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Represents a single caption cue parsed from VTT.
+ */
+export interface CaptionCue {
+	/** Unique identifier for the cue */
+	id: string;
+	/** Start time in seconds */
+	startTime: number;
+	/** End time in seconds */
+	endTime: number;
+	/** Caption text content */
+	text: string;
+}
+
+/**
+ * Parse VTT timestamp to seconds.
+ * Handles formats: HH:MM:SS.mmm or MM:SS.mmm
+ */
+function parseVttTimestamp(timestamp: string): number {
+	const parts = timestamp.trim().split(":");
+	let hours = 0;
+	let minutes = 0;
+	let seconds = 0;
+
+	if (parts.length === 3) {
+		hours = Number.parseInt(parts[0], 10);
+		minutes = Number.parseInt(parts[1], 10);
+		seconds = Number.parseFloat(parts[2]);
+	} else if (parts.length === 2) {
+		minutes = Number.parseInt(parts[0], 10);
+		seconds = Number.parseFloat(parts[1]);
+	}
+
+	return hours * 3600 + minutes * 60 + seconds;
+}
+
+/**
+ * Parse VTT content string into an array of caption cues.
+ */
+function parseVtt(vttContent: string): CaptionCue[] {
+	const cues: CaptionCue[] = [];
+	const lines = vttContent.trim().split("\n");
+
+	let i = 0;
+
+	// Skip WEBVTT header and any metadata
+	while (i < lines.length && !lines[i].includes("-->")) {
+		i++;
+	}
+
+	while (i < lines.length) {
+		const line = lines[i].trim();
+
+		// Look for timestamp line (contains -->)
+		if (line.includes("-->")) {
+			const [startStr, endStr] = line.split("-->").map((s) => s.trim());
+
+			// Handle optional cue settings after timestamp
+			const endParts = endStr.split(" ");
+			const endTime = parseVttTimestamp(endParts[0]);
+			const startTime = parseVttTimestamp(startStr);
+
+			// Collect text lines until empty line or next timestamp
+			const textLines: string[] = [];
+			i++;
+			while (
+				i < lines.length &&
+				lines[i].trim() !== "" &&
+				!lines[i].includes("-->")
+			) {
+				// Skip cue identifier lines (numbers only)
+				if (!/^\d+$/.test(lines[i].trim())) {
+					textLines.push(lines[i].trim());
+				}
+				i++;
+			}
+
+			if (textLines.length > 0) {
+				cues.push({
+					id: `cue-${cues.length}`,
+					startTime,
+					endTime,
+					text: textLines.join("\n"),
+				});
+			}
+		} else {
+			i++;
+		}
+	}
+
+	return cues;
+}
+
+/**
+ * Strip VTT formatting tags from text.
+ * Removes <v>, <c>, <i>, <b>, <u>, etc.
+ */
+function stripVttTags(text: string): string {
+	return text
+		.replace(/<\/?[^>]+(>|$)/g, "") // Remove HTML-like tags
+		.replace(/&nbsp;/g, " ")
+		.replace(/&amp;/g, "&")
+		.replace(/&lt;/g, "<")
+		.replace(/&gt;/g, ">")
+		.trim();
+}
+
+interface UseCaptionsOptions {
+	/** VTT file URL to fetch */
+	src?: string;
+	/** Pre-loaded VTT content string */
+	content?: string;
+	/** Strip VTT formatting tags from caption text */
+	stripTags?: boolean;
+	/** Current playback time in seconds (alternative to setCurrentTime) */
+	currentTime?: number;
+}
+
+interface UseCaptionsReturn {
+	/** All parsed caption cues */
+	cues: CaptionCue[];
+	/** Currently active cue based on current time */
+	activeCue: CaptionCue | null;
+	/** Update the current playback time to get active cue */
+	setCurrentTime: (time: number) => void;
+	/** Loading state */
+	isLoading: boolean;
+	/** Error state */
+	error: Error | null;
+}
+
+/**
+ * Hook for parsing VTT captions and tracking the active cue.
+ *
+ * @param options - Caption source options
+ * @returns Parsed cues, active cue, and state
+ *
+ * @example
+ * ```tsx
+ * function VideoPlayer() {
+ *   const videoRef = React.useRef<HTMLVideoElement>(null);
+ *   const { activeCue, setCurrentTime } = useCaptions({
+ *     src: '/captions.vtt',
+ *   });
+ *
+ *   // Sync with video time
+ *   React.useEffect(() => {
+ *     const video = videoRef.current;
+ *     if (!video) return;
+ *
+ *     const handleTimeUpdate = () => setCurrentTime(video.currentTime);
+ *     video.addEventListener('timeupdate', handleTimeUpdate);
+ *     return () => video.removeEventListener('timeupdate', handleTimeUpdate);
+ *   }, [setCurrentTime]);
+ *
+ *   return (
+ *     <div>
+ *       <video ref={videoRef} src="/video.mp4" />
+ *       {activeCue && <div className="caption">{activeCue.text}</div>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useCaptions(
+	options: UseCaptionsOptions = {},
+): UseCaptionsReturn {
+	const { src, content, stripTags = true, currentTime: externalTime } = options;
+
+	const [cues, setCues] = React.useState<CaptionCue[]>([]);
+	const [internalTime, setInternalTime] = React.useState(0);
+	const [isLoading, setIsLoading] = React.useState(false);
+	const [error, setError] = React.useState<Error | null>(null);
+
+	// Use external time if provided, otherwise use internal state
+	const currentTime = externalTime ?? internalTime;
+
+	// Parse content or fetch from URL
+	React.useEffect(() => {
+		if (content) {
+			// Use provided content directly
+			const parsed = parseVtt(content);
+			setCues(
+				stripTags
+					? parsed.map((cue) => ({ ...cue, text: stripVttTags(cue.text) }))
+					: parsed,
+			);
+			return;
+		}
+
+		if (!src) {
+			setCues([]);
+			return;
+		}
+
+		setIsLoading(true);
+		setError(null);
+
+		fetch(src)
+			.then((response) => {
+				if (!response.ok) {
+					throw new Error(`Failed to fetch captions: ${response.status}`);
+				}
+				return response.text();
+			})
+			.then((vttContent) => {
+				const parsed = parseVtt(vttContent);
+				setCues(
+					stripTags
+						? parsed.map((cue) => ({ ...cue, text: stripVttTags(cue.text) }))
+						: parsed,
+				);
+			})
+			.catch((err) => {
+				setError(err instanceof Error ? err : new Error(String(err)));
+			})
+			.finally(() => {
+				setIsLoading(false);
+			});
+	}, [src, content, stripTags]);
+
+	// Find active cue for current time
+	const activeCue = React.useMemo(() => {
+		return (
+			cues.find(
+				(cue) => currentTime >= cue.startTime && currentTime <= cue.endTime,
+			) ?? null
+		);
+	}, [cues, currentTime]);
+
+	// Memoize setCurrentTime to avoid unnecessary re-renders
+	const handleSetCurrentTime = React.useCallback((time: number) => {
+		setInternalTime(time);
+	}, []);
+
+	return {
+		cues,
+		activeCue,
+		setCurrentTime: handleSetCurrentTime,
+		isLoading,
+		error,
+	};
+}

package/src/hooks/use-video-keyboard.ts

@@ -0,0 +1,230 @@
+import * as React from "react";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface UseVideoKeyboardOptions {
+	/** Ref to the video element */
+	videoRef: React.RefObject<HTMLVideoElement | null>;
+	/** Whether keyboard handling is enabled (default: true) */
+	enabled?: boolean;
+	/** Seek amount in seconds for arrow keys (default: 5) */
+	seekAmount?: number;
+	/** Volume change amount for arrow keys (default: 0.1) */
+	volumeStep?: number;
+	/** Callback when play/pause is toggled */
+	onTogglePlay?: () => void;
+	/** Callback when fullscreen is toggled */
+	onToggleFullscreen?: () => void;
+	/** Callback when captions are toggled */
+	onToggleCaptions?: () => void;
+	/** Callback when controls should be shown */
+	onShowControls?: () => void;
+}
+
+export interface UseVideoKeyboardReturn {
+	/** Key down handler to attach to container element */
+	handleKeyDown: (e: React.KeyboardEvent) => void;
+	/** Props to spread on the container element */
+	containerProps: {
+		onKeyDown: (e: React.KeyboardEvent) => void;
+		tabIndex: number;
+		role: string;
+		"aria-label": string;
+	};
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Hook for handling keyboard shortcuts in a video player.
+ *
+ * Supported shortcuts:
+ * - Space: Play/pause
+ * - Left Arrow: Seek backward
+ * - Right Arrow: Seek forward
+ * - Up Arrow: Volume up
+ * - Down Arrow: Volume down
+ * - M: Toggle mute
+ * - F: Toggle fullscreen
+ * - C: Toggle captions
+ *
+ * @example
+ * ```tsx
+ * const { containerProps } = useVideoKeyboard({
+ *   videoRef,
+ *   onTogglePlay: () => video.paused ? video.play() : video.pause(),
+ *   onToggleFullscreen: () => toggleFullscreen(),
+ *   onShowControls: () => setControlsVisible(true),
+ * });
+ *
+ * return <div {...containerProps}>...</div>;
+ * ```
+ */
+export function useVideoKeyboard({
+	videoRef,
+	enabled = true,
+	seekAmount = 5,
+	volumeStep = 0.1,
+	onTogglePlay,
+	onToggleFullscreen,
+	onToggleCaptions,
+	onShowControls,
+}: UseVideoKeyboardOptions): UseVideoKeyboardReturn {
+	const handleKeyDown = React.useCallback(
+		(e: React.KeyboardEvent) => {
+			if (!enabled) return;
+
+			const video = videoRef.current;
+			if (!video) return;
+
+			// Don't handle if focus is on interactive elements
+			const target = e.target as HTMLElement;
+			if (
+				target.tagName === "BUTTON" ||
+				target.tagName === "INPUT" ||
+				target.tagName === "TEXTAREA" ||
+				target.closest("button") ||
+				target.closest("input") ||
+				target.closest("[role='slider']")
+			) {
+				return;
+			}
+
+			let handled = false;
+
+			switch (e.key) {
+				// Play/Pause
+				case " ":
+				case "Spacebar":
+				case "k": // YouTube-style shortcut
+					if (onTogglePlay) {
+						onTogglePlay();
+					} else {
+						if (video.paused) {
+							video.play().catch(() => {});
+						} else {
+							video.pause();
+						}
+					}
+					handled = true;
+					break;
+
+				// Seek backward
+				case "ArrowLeft":
+				case "j": // YouTube-style shortcut
+					video.currentTime = Math.max(0, video.currentTime - seekAmount);
+					handled = true;
+					break;
+
+				// Seek forward
+				case "ArrowRight":
+				case "l": // YouTube-style shortcut
+					video.currentTime = Math.min(
+						video.duration || 0,
+						video.currentTime + seekAmount,
+					);
+					handled = true;
+					break;
+
+				// Volume up
+				case "ArrowUp":
+					video.volume = Math.min(1, video.volume + volumeStep);
+					video.muted = false;
+					handled = true;
+					break;
+
+				// Volume down
+				case "ArrowDown":
+					video.volume = Math.max(0, video.volume - volumeStep);
+					handled = true;
+					break;
+
+				// Toggle mute
+				case "m":
+				case "M":
+					video.muted = !video.muted;
+					handled = true;
+					break;
+
+				// Toggle fullscreen
+				case "f":
+				case "F":
+					onToggleFullscreen?.();
+					handled = true;
+					break;
+
+				// Toggle captions
+				case "c":
+				case "C":
+					onToggleCaptions?.();
+					handled = true;
+					break;
+
+				// Jump to start
+				case "Home":
+					video.currentTime = 0;
+					handled = true;
+					break;
+
+				// Jump to end
+				case "End":
+					video.currentTime = video.duration || 0;
+					handled = true;
+					break;
+
+				// Number keys for percentage seeking (0-9)
+				case "0":
+				case "1":
+				case "2":
+				case "3":
+				case "4":
+				case "5":
+				case "6":
+				case "7":
+				case "8":
+				case "9":
+					if (video.duration) {
+						const percent = parseInt(e.key, 10) / 10;
+						video.currentTime = video.duration * percent;
+						handled = true;
+					}
+					break;
+			}
+
+			if (handled) {
+				e.preventDefault();
+				e.stopPropagation();
+				onShowControls?.();
+			}
+		},
+		[
+			enabled,
+			videoRef,
+			seekAmount,
+			volumeStep,
+			onTogglePlay,
+			onToggleFullscreen,
+			onToggleCaptions,
+			onShowControls,
+		],
+	);
+
+	const containerProps = React.useMemo(
+		() => ({
+			onKeyDown: handleKeyDown,
+			tabIndex: 0,
+			role: "application" as const,
+			"aria-label": "Video player, press space to play or pause",
+		}),
+		[handleKeyDown],
+	);
+
+	return {
+		handleKeyDown,
+		containerProps,
+	};
+}

package/src/lib/utils.ts

@@ -1 +1,8 @@
-export { cnBase as cn } from "tailwind-variants";
+import { type ClassValue, clsx } from "clsx";
+import { cnBase as twMerge } from "tailwind-variants";
+
+export { twMerge };
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}