@nationaldesignstudio/react 0.0.15 → 0.0.16

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

@@ -0,0 +1,453 @@
+import * as React from "react";
+import { tv, type VariantProps } from "tailwind-variants";
+import { type ComponentTheme, themeToStyleVars } from "@/lib/theme";
+import { cn } from "@/lib/utils";
+
+/**
+ * Hero variants based on Figma BaseKit / Heros
+ *
+ * Variants:
+ * - A1: Content aligned at bottom (default)
+ * - A2: Content aligned at top
+ * - A3: Content aligned at center
+ *
+ * Each variant is responsive across breakpoints:
+ * - sm (Mobile): 500px height, 20px padding
+ * - md (Tablet): 650px height, 56px padding
+ * - lg (Desktop): 700-850px height, 64-72px padding
+ */
+const heroVariants = tv({
+	base: [
+		"flex w-full",
+		// Mobile (sm) - uses primitive spacing tokens
+		"h-[500px] p-spacing-20",
+		// Tablet (md) - uses primitive spacing tokens
+		"md:h-[650px] md:p-spacing-56",
+	],
+	variants: {
+		variant: {
+			// A1: Content at bottom
+			A1: [
+				"items-end",
+				// Desktop (lg) - 800px height, uses primitive spacing tokens
+				"xl:h-[800px] xl:p-spacing-72",
+			],
+			// A2: Content at top
+			A2: [
+				"items-start",
+				// Desktop (lg) - 700px height, uses primitive spacing tokens
+				"xl:h-[700px] xl:p-spacing-64",
+			],
+			// A3: Content centered
+			A3: [
+				"items-center",
+				// Desktop (lg) - 800px height, uses primitive spacing tokens
+				"xl:h-[800px] xl:p-spacing-64",
+			],
+		},
+	},
+	defaultVariants: {
+		variant: "A1",
+	},
+});
+
+// =============================================================================
+// HeroBackground Components
+// =============================================================================
+
+export interface HeroBackgroundImageProps
+	extends React.HTMLAttributes<HTMLDivElement> {
+	/**
+	 * URL for the background image
+	 */
+	src: string;
+	/**
+	 * CSS background-position value (default: "center")
+	 */
+	position?: string;
+	/**
+	 * Alt text for accessibility (used in aria-label)
+	 */
+	alt?: string;
+}
+
+/**
+ * Background image component for Hero
+ */
+const HeroBackgroundImage = React.forwardRef<
+	HTMLDivElement,
+	HeroBackgroundImageProps
+>(({ className, src, position = "center", alt, ...props }, ref) => (
+	<div
+		ref={ref}
+		role="img"
+		aria-label={alt}
+		aria-hidden={!alt}
+		className={cn("absolute inset-0 bg-cover", className)}
+		style={{
+			backgroundImage: `url(${src})`,
+			backgroundPosition: position,
+		}}
+		{...props}
+	/>
+));
+HeroBackgroundImage.displayName = "HeroBackground.Image";
+
+export interface HeroBackgroundVideoProps
+	extends Omit<React.VideoHTMLAttributes<HTMLVideoElement>, "children"> {
+	/**
+	 * URL for the video source
+	 */
+	src: string;
+	/**
+	 * Video MIME type (default: auto-detected from src)
+	 */
+	type?: string;
+	/**
+	 * Poster image URL shown before video loads
+	 */
+	poster?: string;
+}
+
+/**
+ * Background video component for Hero (HTML5 video)
+ */
+const HeroBackgroundVideo = React.forwardRef<
+	HTMLVideoElement,
+	HeroBackgroundVideoProps
+>(
+	(
+		{
+			className,
+			src,
+			type,
+			poster,
+			autoPlay = true,
+			loop = true,
+			muted = true,
+			playsInline = true,
+			...props
+		},
+		ref,
+	) => (
+		<video
+			ref={ref}
+			autoPlay={autoPlay}
+			loop={loop}
+			muted={muted}
+			playsInline={playsInline}
+			poster={poster}
+			className={cn("absolute inset-0 h-full w-full object-cover", className)}
+			{...props}
+		>
+			<source src={src} type={type} />
+		</video>
+	),
+);
+HeroBackgroundVideo.displayName = "HeroBackground.Video";
+
+export interface HeroBackgroundStreamProps
+	extends React.IframeHTMLAttributes<HTMLIFrameElement> {
+	/**
+	 * Cloudflare Stream video ID
+	 */
+	videoId: string;
+	/**
+	 * Poster image URL (Cloudflare Stream thumbnail or custom)
+	 */
+	poster?: string;
+	/**
+	 * Whether the video should autoplay (default: true)
+	 */
+	autoplay?: boolean;
+	/**
+	 * Whether the video should loop (default: true)
+	 */
+	loop?: boolean;
+	/**
+	 * Whether the video should be muted (default: true)
+	 */
+	muted?: boolean;
+	/**
+	 * Whether to show playback controls (default: false)
+	 */
+	controls?: boolean;
+	/**
+	 * Custom Cloudflare customer subdomain (if using custom domains)
+	 */
+	customerSubdomain?: string;
+}
+
+/**
+ * Background video component for Hero using Cloudflare Stream
+ *
+ * @example
+ * ```tsx
+ * <HeroBackground.Stream videoId="5d5bc37ffcf54c9b82e996823bffbb81" />
+ *
+ * // With custom subdomain
+ * <HeroBackground.Stream
+ *   videoId="5d5bc37ffcf54c9b82e996823bffbb81"
+ *   customerSubdomain="customer-abc123"
+ * />
+ * ```
+ */
+const HeroBackgroundStream = React.forwardRef<
+	HTMLIFrameElement,
+	HeroBackgroundStreamProps
+>(
+	(
+		{
+			className,
+			videoId,
+			poster,
+			autoplay = true,
+			loop = true,
+			muted = true,
+			controls = false,
+			customerSubdomain,
+			title = "Background video",
+			...props
+		},
+		ref,
+	) => {
+		// Build Cloudflare Stream embed URL
+		const baseUrl = customerSubdomain
+			? `https://${customerSubdomain}.cloudflarestream.com`
+			: "https://iframe.videodelivery.net";
+
+		const params = new URLSearchParams();
+		if (autoplay) params.set("autoplay", "true");
+		if (loop) params.set("loop", "true");
+		if (muted) params.set("muted", "true");
+		if (!controls) params.set("controls", "false");
+		if (poster) params.set("poster", poster);
+		// Preload for better performance
+		params.set("preload", "auto");
+
+		const streamUrl = `${baseUrl}/${videoId}?${params.toString()}`;
+
+		return (
+			<iframe
+				ref={ref}
+				src={streamUrl}
+				title={title}
+				allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
+				allowFullScreen
+				className={cn(
+					"absolute inset-0 h-full w-full border-0",
+					// Scale up to hide letterboxing if video aspect doesn't match
+					"scale-[1.5] object-cover",
+					className,
+				)}
+				{...props}
+			/>
+		);
+	},
+);
+HeroBackgroundStream.displayName = "HeroBackground.Stream";
+
+/**
+ * Compound component for Hero backgrounds
+ *
+ * Provides sub-components for different background types:
+ * - `HeroBackground.Image` - Static image backgrounds
+ * - `HeroBackground.Video` - HTML5 video backgrounds
+ * - `HeroBackground.Stream` - Cloudflare Stream video backgrounds
+ *
+ * @example
+ * ```tsx
+ * // Image background
+ * <Hero
+ *   title="Welcome"
+ *   background={<HeroBackground.Image src="/hero.jpg" />}
+ * />
+ *
+ * // Video background
+ * <Hero
+ *   title="Welcome"
+ *   background={<HeroBackground.Video src="/hero.mp4" />}
+ * />
+ *
+ * // Cloudflare Stream background
+ * <Hero
+ *   title="Welcome"
+ *   background={<HeroBackground.Stream videoId="abc123" />}
+ * />
+ * ```
+ */
+const HeroBackground = {
+	Image: HeroBackgroundImage,
+	Video: HeroBackgroundVideo,
+	Stream: HeroBackgroundStream,
+};
+
+// =============================================================================
+// Hero Component
+// =============================================================================
+
+export interface HeroProps
+	extends React.HTMLAttributes<HTMLElement>,
+		VariantProps<typeof heroVariants> {
+	/**
+	 * The title text displayed in the hero
+	 */
+	title: string;
+	/**
+	 * Custom typography class for the title using primitive tokens.
+	 * Use primitive typography classes like "text-128 leading-128 tracking-128"
+	 * Default: "text-64 leading-64 tracking-64 md:text-128 md:leading-128 md:tracking-128 xl:text-192 xl:leading-192 xl:tracking-192"
+	 */
+	titleClassName?: string;
+	/**
+	 * Background for the hero. Can be:
+	 * - A color string (hex, rgb, etc.) for solid backgrounds
+	 * - A ReactNode (use HeroBackground.Image, HeroBackground.Video, or HeroBackground.Stream)
+	 */
+	background?: React.ReactNode | string;
+	/**
+	 * Opacity of the overlay (0-1, default: 0)
+	 * Only applies when using a background slot
+	 */
+	overlayOpacity?: number;
+	/**
+	 * Color of the overlay (default: "black")
+	 */
+	overlayColor?: string;
+	/**
+	 * Theme overrides for component styling via CSS custom properties
+	 */
+	theme?: ComponentTheme;
+}
+
+/**
+ * Checks if the background prop is a color string
+ */
+function isColorString(
+	background: React.ReactNode | string | undefined,
+): background is string {
+	return (
+		typeof background === "string" &&
+		(background.startsWith("#") ||
+			background.startsWith("rgb") ||
+			background.startsWith("hsl") ||
+			// Named colors or CSS variables
+			/^(var\(|[a-z]+$)/i.test(background))
+	);
+}
+
+/**
+ * Hero component for page headers with large display typography.
+ *
+ * Features responsive sizing across three variants:
+ * - A1: Content at bottom (default)
+ * - A2: Content at top
+ * - A3: Content centered
+ *
+ * Each variant responds to breakpoints:
+ * - Mobile: 500px height, 20px padding, 64px typography
+ * - Tablet (768px+): 650px height, 56px padding, 128-148px typography
+ * - Desktop (1440px+): 700-800px height, 64-72px padding, 148-192px typography
+ *
+ * @example
+ * ```tsx
+ * // Simple hero with solid color
+ * <Hero title="Welcome" variant="A1" background="#1a1a1a" />
+ *
+ * // With background image
+ * <Hero
+ *   title="Welcome"
+ *   variant="A1"
+ *   background={<HeroBackground.Image src="/hero.jpg" />}
+ *   overlayOpacity={0.4}
+ * />
+ *
+ * // With Cloudflare Stream video
+ * <Hero
+ *   title="Welcome"
+ *   variant="A1"
+ *   background={<HeroBackground.Stream videoId="abc123" />}
+ *   overlayOpacity={0.3}
+ * />
+ * ```
+ */
+/**
+ * Default responsive typography for hero title using primitive tokens
+ * Mobile: 64px, Tablet: 128px, Desktop: 192px
+ */
+const DEFAULT_TITLE_TYPOGRAPHY =
+	"text-64 leading-64 tracking-64 md:text-128 md:leading-128 md:tracking-128 xl:text-192 xl:leading-192 xl:tracking-192 font-medium";
+
+const Hero = React.forwardRef<HTMLElement, HeroProps>(
+	(
+		{
+			className,
+			title,
+			titleClassName,
+			variant,
+			background,
+			overlayOpacity = 0,
+			overlayColor = "black",
+			theme,
+			style,
+			...props
+		},
+		ref,
+	) => {
+		const isColor = isColorString(background);
+		const hasMediaBackground = background && !isColor;
+		const themeStyles = themeToStyleVars(theme);
+		const combinedStyles = {
+			...themeStyles,
+			...(isColor ? { backgroundColor: background } : {}),
+			...style,
+		};
+
+		return (
+			<section
+				ref={ref}
+				className={cn(
+					heroVariants({ variant }),
+					hasMediaBackground && "relative overflow-hidden",
+					// Default background color when no background is provided
+					!background && "bg-gray-1000",
+					className,
+				)}
+				style={
+					Object.keys(combinedStyles).length > 0 ? combinedStyles : undefined
+				}
+				{...props}
+			>
+				{/* Background slot (image, video, or stream) */}
+				{hasMediaBackground && background}
+
+				{/* Overlay */}
+				{hasMediaBackground && overlayOpacity > 0 && (
+					<div
+						aria-hidden="true"
+						className="absolute inset-0"
+						style={{
+							backgroundColor: overlayColor,
+							opacity: overlayOpacity,
+						}}
+					/>
+				)}
+
+				{/* Content */}
+				<h1
+					className={cn(
+						// Use primitive tokens instead of semantic typography
+						titleClassName || DEFAULT_TITLE_TYPOGRAPHY,
+						"text-gray-50",
+						hasMediaBackground && "relative z-10",
+					)}
+				>
+					{title}
+				</h1>
+			</section>
+		);
+	},
+);
+Hero.displayName = "Hero";
+
+export { Hero, HeroBackground, heroVariants, DEFAULT_TITLE_TYPOGRAPHY };

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

@@ -0,0 +1,140 @@
+import { describe, expect, test } from "vitest";
+import { page } from "vitest/browser";
+import { render } from "vitest-browser-react";
+import { Hero } from "./hero";
+
+describe("Hero Visual Regression", () => {
+	// =========================================================================
+	// Variant A1 (Content at bottom) - Default
+	// =========================================================================
+	describe("Variant A1", () => {
+		test("A1 desktop renders correctly", async () => {
+			await page.viewport(1440, 900);
+
+			render(<Hero data-testid="hero" variant="A1" title="Hero A1" />);
+
+			await expect(page.getByTestId("hero")).toMatchScreenshot(
+				"hero-a1-desktop",
+			);
+		});
+
+		test("A1 tablet renders correctly", async () => {
+			await page.viewport(834, 700);
+
+			render(<Hero data-testid="hero" variant="A1" title="Hero A1" />);
+
+			await expect(page.getByTestId("hero")).toMatchScreenshot(
+				"hero-a1-tablet",
+			);
+		});
+
+		test("A1 mobile renders correctly", async () => {
+			await page.viewport(393, 600);
+
+			render(<Hero data-testid="hero" variant="A1" title="Hero A1" />);
+
+			await expect(page.getByTestId("hero")).toMatchScreenshot(
+				"hero-a1-mobile",
+			);
+		});
+	});
+
+	// =========================================================================
+	// Variant A2 (Content at top)
+	// =========================================================================
+	describe("Variant A2", () => {
+		test("A2 desktop renders correctly", async () => {
+			await page.viewport(1440, 900);
+
+			render(<Hero data-testid="hero" variant="A2" title="Hero A2" />);
+
+			await expect(page.getByTestId("hero")).toMatchScreenshot(
+				"hero-a2-desktop",
+			);
+		});
+
+		test("A2 tablet renders correctly", async () => {
+			await page.viewport(834, 700);
+
+			render(<Hero data-testid="hero" variant="A2" title="Hero A2" />);
+
+			await expect(page.getByTestId("hero")).toMatchScreenshot(
+				"hero-a2-tablet",
+			);
+		});
+
+		test("A2 mobile renders correctly", async () => {
+			await page.viewport(393, 600);
+
+			render(<Hero data-testid="hero" variant="A2" title="Hero A2" />);
+
+			await expect(page.getByTestId("hero")).toMatchScreenshot(
+				"hero-a2-mobile",
+			);
+		});
+	});
+
+	// =========================================================================
+	// Variant A3 (Content centered)
+	// =========================================================================
+	describe("Variant A3", () => {
+		test("A3 desktop renders correctly", async () => {
+			await page.viewport(1440, 900);
+
+			render(<Hero data-testid="hero" variant="A3" title="Hero A3" />);
+
+			await expect(page.getByTestId("hero")).toMatchScreenshot(
+				"hero-a3-desktop",
+			);
+		});
+
+		test("A3 tablet renders correctly", async () => {
+			await page.viewport(834, 700);
+
+			render(<Hero data-testid="hero" variant="A3" title="Hero A3" />);
+
+			await expect(page.getByTestId("hero")).toMatchScreenshot(
+				"hero-a3-tablet",
+			);
+		});
+
+		test("A3 mobile renders correctly", async () => {
+			await page.viewport(393, 600);
+
+			render(<Hero data-testid="hero" variant="A3" title="Hero A3" />);
+
+			await expect(page.getByTestId("hero")).toMatchScreenshot(
+				"hero-a3-mobile",
+			);
+		});
+	});
+
+	// =========================================================================
+	// Additional tests
+	// =========================================================================
+	test("hero with long title renders correctly", async () => {
+		await page.viewport(1280, 800);
+
+		render(
+			<Hero data-testid="hero" title="A Much Longer Hero Title That Wraps" />,
+		);
+
+		await expect(page.getByTestId("hero")).toMatchScreenshot("hero-long-title");
+	});
+
+	test("hero with custom className renders correctly", async () => {
+		await page.viewport(1280, 800);
+
+		render(
+			<Hero
+				data-testid="hero"
+				title="Custom Background"
+				className="bg-blue-600"
+			/>,
+		);
+
+		await expect(page.getByTestId("hero")).toMatchScreenshot(
+			"hero-custom-class",
+		);
+	});
+});

package/src/components/sections/hero/index.ts

@@ -0,0 +1,10 @@
+export {
+	DEFAULT_TITLE_TYPOGRAPHY,
+	Hero,
+	HeroBackground,
+	type HeroBackgroundImageProps,
+	type HeroBackgroundStreamProps,
+	type HeroBackgroundVideoProps,
+	type HeroProps,
+	heroVariants,
+} from "./hero";

package/src/components/sections/prose/index.ts

@@ -0,0 +1,6 @@
+export {
+	Prose,
+	type ProseProps,
+	ProseSection,
+	type ProseSectionProps,
+} from "./prose";