@nationaldesignstudio/react 0.5.5 → 0.6.0

package/src/components/organisms/card/card.tsx

@@ -12,6 +12,16 @@ const cardVariants = tv({
 			 * Use with Background components for images/gradients.
 			 */
 			overlay: "w-full flex-col",
+			/**
+			 * Profile layout - square image with stacked content below.
+			 * Ideal for team member cards, user profiles, testimonials.
+			 */
+			profile: "w-full flex-col",
+			/**
+			 * Compact layout - small thumbnail with condensed horizontal content.
+			 * Ideal for news items, article previews, resource lists.
+			 */
+			compact: "w-full flex-row items-center gap-16",
 		},
 	},
 	defaultVariants: {
@@ -48,16 +58,26 @@ const Card = React.forwardRef<HTMLDivElement, CardProps>(
 Card.displayName = "Card";
 
 const cardImageVariants = tv({
-	base: [
-		"relative shrink-0 bg-bg-muted",
-		// Vertical: full width with aspect ratio
-		"aspect-video w-full",
-		// When in horizontal card (parent has flex-row), override
-		"[.flex-row>&]:aspect-auto [.flex-row>&]:w-2/5 [.flex-row>&]:self-stretch",
-	],
+	base: "relative shrink-0 bg-bg-muted",
+	variants: {
+		layout: {
+			vertical: "aspect-video w-full",
+			horizontal: "aspect-auto w-2/5 self-stretch",
+			overlay: "aspect-video w-full",
+			/** Profile: square aspect ratio for headshots/avatars */
+			profile: "aspect-square w-full",
+			/** Compact: fixed small size for thumbnails */
+			compact: "size-80 rounded-8",
+		},
+	},
+	defaultVariants: {
+		layout: "vertical",
+	},
 });
 
-export interface CardImageProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface CardImageProps
+	extends React.HTMLAttributes<HTMLDivElement>,
+		VariantProps<typeof cardImageVariants> {
 	/**
 	 * The image source URL
 	 */
@@ -69,15 +89,18 @@ export interface CardImageProps extends React.HTMLAttributes<HTMLDivElement> {
 }
 
 /**
- * Card image area. For vertical layout, displays with 16:9 aspect ratio.
- * For horizontal layout, takes up ~40% width and stretches to content height.
+ * Card image area with layout-specific styling.
+ * - vertical: 16:9 aspect ratio, full width
+ * - horizontal: ~40% width, stretches to content height
+ * - profile: square aspect ratio for headshots/avatars
+ * - compact: fixed small size for thumbnails
  */
 const CardImage = React.forwardRef<HTMLDivElement, CardImageProps>(
-	({ className, src, alt = "", ...props }, ref) => {
+	({ className, src, alt = "", layout, ...props }, ref) => {
 		return (
 			<div
 				ref={ref}
-				className={cardImageVariants({ class: className })}
+				className={cardImageVariants({ layout, class: className })}
 				{...props}
 			>
 				{src && (
@@ -263,6 +286,56 @@ const CardActions = React.forwardRef<HTMLDivElement, CardActionsProps>(
 );
 CardActions.displayName = "CardActions";
 
+const cardLinkVariants = tv({
+	base: "group/link flex items-center gap-4 text-text-muted transition-colors duration-200 hover:text-text-primary",
+});
+
+export interface CardLinkProps extends React.HTMLAttributes<HTMLSpanElement> {
+	/**
+	 * Whether to show the arrow indicator
+	 * @default true
+	 */
+	showArrow?: boolean;
+}
+
+/**
+ * Inline link element for cards with optional animated arrow.
+ * Commonly used for "Read More →" or "Learn More →" patterns.
+ *
+ * @example
+ * ```tsx
+ * <Card layout="compact">
+ *   <CardImage src="/thumb.jpg" layout="compact" />
+ *   <CardContent>
+ *     <CardTitle>Article Title</CardTitle>
+ *     <CardLink>Read More</CardLink>
+ *   </CardContent>
+ * </Card>
+ * ```
+ */
+const CardLink = React.forwardRef<HTMLSpanElement, CardLinkProps>(
+	({ className, children, showArrow = true, ...props }, ref) => {
+		return (
+			<span
+				ref={ref}
+				className={cardLinkVariants({ class: className })}
+				{...props}
+			>
+				<span>{children}</span>
+				{showArrow && (
+					<span
+						aria-hidden="true"
+						className="inline-block transition-transform duration-200 ease-out group-hover/link:translate-x-4"
+					>
+						→
+					</span>
+				)}
+			</span>
+		);
+	},
+);
+CardLink.displayName = "CardLink";
+
 export {
 	Card,
 	cardVariants,
@@ -280,4 +353,6 @@ export {
 	cardBodyVariants,
 	CardActions,
 	cardActionsVariants,
+	CardLink,
+	cardLinkVariants,
 };

package/src/components/sections/hero/hero.tsx

@@ -30,6 +30,7 @@ const heroVariants = tv({
 			"md:p-56",
 		],
 		title: DEFAULT_TITLE_TYPOGRAPHY,
+		indicator: "absolute inset-x-0 bottom-0 z-10 flex justify-center pb-24",
 	},
 	variants: {
 		variant: {
@@ -46,6 +47,21 @@ const heroVariants = tv({
 				content: ["items-center justify-center", "lg:p-64"],
 			},
 		},
+		/**
+		 * Vertical alignment of content within the hero.
+		 * Provides a simpler API than variant for basic alignment needs.
+		 */
+		contentAlign: {
+			top: {
+				content: "justify-start",
+			},
+			center: {
+				content: "items-center justify-center",
+			},
+			bottom: {
+				content: "justify-end",
+			},
+		},
 		colorScheme: {
 			dark: {
 				root: "bg-bg-page",
@@ -144,11 +160,24 @@ export interface HeroProps
 	 * - light: Light text for use on dark backgrounds
 	 */
 	colorScheme?: "dark" | "light";
+	// Note: contentAlign is provided by VariantProps<typeof heroVariants>
+	// Options: "top" | "center" | "bottom"
 	/**
 	 * Content for the top slot (full-width, no padding).
 	 * Use for USGovBanner, Navigation, etc.
 	 */
 	top?: React.ReactNode;
+	/**
+	 * Indicator slot for scroll hints, arrows, or other visual cues.
+	 * Rendered at the bottom of the hero, below the main content.
+	 * @example
+	 * ```tsx
+	 * <Hero indicator={<ChevronDown className="animate-bounce" />}>
+	 *   <h1>Welcome</h1>
+	 * </Hero>
+	 * ```
+	 */
+	indicator?: React.ReactNode;
 	/**
 	 * Background for the hero. Can be:
 	 * - A color string (hex, rgb, etc.) for solid backgrounds
@@ -235,7 +264,9 @@ const Hero = React.forwardRef<HTMLElement, HeroProps>(
 			title,
 			titleClassName,
 			colorScheme = "dark",
+			contentAlign,
 			top,
+			indicator,
 			variant,
 			background,
 			overlayOpacity = 0,
@@ -251,6 +282,7 @@ const Hero = React.forwardRef<HTMLElement, HeroProps>(
 		const hasMediaBackground = background && !isColor;
 		const styles = heroVariants({
 			variant,
+			contentAlign,
 			colorScheme,
 			hasBackground: !!background,
 		});
@@ -295,6 +327,9 @@ const Hero = React.forwardRef<HTMLElement, HeroProps>(
 					{/* Children - always render if provided */}
 					{children}
 				</div>
+
+				{/* Indicator slot - scroll hints, arrows, etc. */}
+				{indicator && <div className={styles.indicator()}>{indicator}</div>}
 			</section>
 		);
 	},

package/src/hooks/index.ts

@@ -1 +1,17 @@
+// Utility hooks
+
+export {
+	BREAKPOINTS,
+	type Breakpoint,
+	useBreakpoint,
+	useMaxBreakpoint,
+	useMinBreakpoint,
+} from "./use-breakpoint";
+// Video player hooks
+export { type CaptionCue, useCaptions } from "./use-captions";
 export { useEventListener } from "./use-event-listener";
+export {
+	type UseVideoKeyboardOptions,
+	type UseVideoKeyboardReturn,
+	useVideoKeyboard,
+} from "./use-video-keyboard";

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