@nationaldesignstudio/react 0.5.5 → 0.6.0

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

package/src/theme/index.ts

@@ -11,13 +11,17 @@ export type {
 	ColorThemeName,
 	CSSVariableMap,
 	NestedStringRecord,
+	ResolvedProjectTheme,
 	SurfaceThemeName,
 	ThemeComposition,
 } from "@nds-design-system/tokens";
+// Re-export project theme utilities for convenience
 // Re-export theme registries for programmatic access
 export {
 	colorThemeNames,
 	colorThemes,
+	defineTheme,
+	generateThemeCSS,
 	surfaceThemeNames,
 	surfaceThemes,
 } from "@nds-design-system/tokens";

package/src/theme/theme-provider.tsx

@@ -9,6 +9,7 @@ import type {
 	ColorThemeName,
 	CSSVariableMap,
 	NestedStringRecord,
+	ResolvedProjectTheme,
 	SurfaceThemeName,
 	TokenModule,
 } from "@nds-design-system/tokens";
@@ -46,6 +47,11 @@ export interface ThemeProviderProps {
 	color?: ColorThemeName;
 	/** Surface theme name (defaults to "base") */
 	surface?: SurfaceThemeName;
+	/**
+	 * Custom project theme created with defineTheme()
+	 * When provided, overrides color/surface props with custom theme tokens
+	 */
+	customTheme?: ResolvedProjectTheme;
 	/** Children to render */
 	children: ReactNode;
 	/** Optional className for the wrapper div */
@@ -239,8 +245,23 @@ function deepMerge(
  *   <App />
  * </ThemeProvider>
  *
- * // Mix and match
- * <ThemeProvider color="institution" surface="soft">
+ * // Use a custom project theme
+ * import { defineTheme, srgb } from "@nds-design-system/tokens";
+ *
+ * const myTheme = defineTheme({
+ *   name: "my-project",
+ *   extends: "base",
+ *   tokens: {
+ *     semantic: {
+ *       color: {
+ *         bg: { page: srgb("#FEFDF9") },
+ *         accent: { brand: srgb("#A68B5E") },
+ *       },
+ *     },
+ *   },
+ * });
+ *
+ * <ThemeProvider customTheme={myTheme}>
  *   <App />
  * </ThemeProvider>
  * ```
@@ -248,6 +269,7 @@ function deepMerge(
 export function ThemeProvider({
 	color = "base",
 	surface = "base",
+	customTheme,
 	children,
 	className,
 	applyStyles = true,
@@ -255,12 +277,17 @@ export function ThemeProvider({
 	const { tokens, cssVars } = useMemo(() => {
 		const flatTokens: Record<string, string> = {};
 
-		// Get color theme (merge with base if not base)
+		// Get base color theme
 		const baseColorModule = colorThemes.base;
-		const colorModule = colorThemes[color];
+
+		// If customTheme is provided, use its base theme; otherwise use the color prop
+		const effectiveColor = customTheme ? customTheme.extends : color;
+		const colorModule =
+			colorThemes[effectiveColor as keyof typeof colorThemes] ??
+			colorThemes.base;
 
 		const mergedColor =
-			color === "base"
+			effectiveColor === "base"
 				? (baseColorModule as Record<string, unknown>)
 				: mergeTokenModules(baseColorModule, colorModule);
 
@@ -287,15 +314,28 @@ export function ThemeProvider({
 
 		// Use shared utilities from tokens package
 		const nestedTokens = flatToNested(flatTokens);
-		const cssVariables = flatToCSSVars(flatTokens);
+		let cssVariables = flatToCSSVars(flatTokens);
+
+		// If customTheme provided, merge its CSS variables (overriding base values)
+		if (customTheme) {
+			cssVariables = {
+				...cssVariables,
+				...Object.fromEntries(
+					Object.entries(customTheme.cssVars).map(([key, value]) => [
+						key.startsWith("--") ? key : `--${key}`,
+						value,
+					]),
+				),
+			};
+		}
 
 		return { tokens: nestedTokens, cssVars: cssVariables };
-	}, [color, surface]);
+	}, [color, surface, customTheme]);
 
 	const contextValue: ThemeContextValue = {
 		cssVars,
 		tokens,
-		colorTheme: color,
+		colorTheme: customTheme ? (customTheme.extends as ColorThemeName) : color,
 		surfaceTheme: surface,
 	};