@nationaldesignstudio/react 0.0.17 → 0.1.0

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

@@ -1,49 +1,69 @@
 import * as React from "react";
 import { tv, type VariantProps } from "tailwind-variants";
+import { BackgroundOverlay } from "@/components/atoms/background";
 import { type ComponentTheme, themeToStyleVars } from "@/lib/theme";
-import { cn } from "@/lib/utils";
+
+// Re-export Background components for convenience as HeroBackground
+export {
+	Background as HeroBackground,
+	BackgroundGradient as HeroGradient,
+	type BackgroundGradientProps as HeroGradientProps,
+	BackgroundImage as HeroBackgroundImage,
+	type BackgroundImageProps as HeroBackgroundImageProps,
+	BackgroundOverlay as HeroOverlay,
+	type BackgroundOverlayProps as HeroOverlayProps,
+	BackgroundStream as HeroBackgroundStream,
+	type BackgroundStreamProps as HeroBackgroundStreamProps,
+	BackgroundVideo as HeroBackgroundVideo,
+	type BackgroundVideoProps as HeroBackgroundVideoProps,
+} from "@/components/atoms/background";
+
+// =============================================================================
+// Hero Variants
+// =============================================================================
 
 /**
  * Hero variants based on Figma BaseKit / Heros
  *
+ * Slots:
+ * - root: The outer container
+ * - top: Full-width slot at top for banners/nav (no padding)
+ * - content: Padded content area with alignment
+ *
  * 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
+ * - A3: Content centered
  */
 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",
-	],
+	slots: {
+		root: "relative flex w-full flex-col overflow-hidden",
+		top: "relative z-10 w-full",
+		content: [
+			"relative z-10 mx-auto flex w-full max-w-screen-xl flex-1 flex-col",
+			// Mobile padding
+			"p-spacing-20",
+			// Tablet padding
+			"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",
-			],
+			A1: {
+				root: "min-h-[80vh]",
+				content: ["justify-end", "lg: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",
-			],
+			A2: {
+				root: "min-h-[80vh]",
+				content: ["justify-start", "lg:p-spacing-64"],
+			},
 			// A3: Content centered
-			A3: [
-				"items-center",
-				// Desktop (lg) - 800px height, uses primitive spacing tokens
-				"xl:h-[800px] xl:p-spacing-64",
-			],
+			A3: {
+				root: "min-h-[80vh]",
+				content: ["items-center justify-center", "lg:p-spacing-64"],
+			},
 		},
 	},
 	defaultVariants: {
@@ -52,253 +72,80 @@ const heroVariants = tv({
 });
 
 // =============================================================================
-// HeroBackground Components
+// Standalone variants for sub-components (for external use)
 // =============================================================================
 
-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;
-}
+const heroHeaderVariants = tv({
+	base: "relative z-10 w-full",
+});
 
-/**
- * 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";
+const heroContentVariants = tv({
+	base: [
+		"relative z-10 mx-auto flex w-full max-w-screen-xl flex-1 flex-col",
+		"p-spacing-20",
+		"md:p-spacing-56",
+		"lg:p-spacing-72",
+	],
+});
 
-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;
-}
+export interface HeroHeaderProps extends React.HTMLAttributes<HTMLDivElement> {}
 
 /**
- * Background video component for Hero (HTML5 video)
+ * Header slot for Hero - used for navigation, gov banners, etc.
+ * Full-width with no padding, sits at the top of the hero.
  */
-const HeroBackgroundVideo = React.forwardRef<
-	HTMLVideoElement,
-	HeroBackgroundVideoProps
->(
-	(
-		{
-			className,
-			src,
-			type,
-			poster,
-			autoPlay = true,
-			loop = true,
-			muted = true,
-			playsInline = true,
-			...props
-		},
-		ref,
-	) => (
-		<video
+const HeroHeader = React.forwardRef<HTMLDivElement, HeroHeaderProps>(
+	({ className, ...props }, ref) => (
+		<div
 			ref={ref}
-			autoPlay={autoPlay}
-			loop={loop}
-			muted={muted}
-			playsInline={playsInline}
-			poster={poster}
-			className={cn("absolute inset-0 h-full w-full object-cover", className)}
+			className={heroHeaderVariants({ class: className })}
 			{...props}
-		>
-			<source src={src} type={type} />
-		</video>
+		/>
 	),
 );
-HeroBackgroundVideo.displayName = "HeroBackground.Video";
+HeroHeader.displayName = "Hero.Header";
 
-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;
-}
+export interface HeroContentProps
+	extends React.HTMLAttributes<HTMLDivElement> {}
 
 /**
- * Background video component for Hero using Cloudflare Stream
- *
- * @example
- * ```tsx
- * <HeroBackground.Stream videoId="5d5bc37ffcf54c9b82e996823bffbb81" />
- *
- * // With custom subdomain
- * <HeroBackground.Stream
- *   videoId="5d5bc37ffcf54c9b82e996823bffbb81"
- *   customerSubdomain="customer-abc123"
- * />
- * ```
+ * Content container for Hero - use for main content.
+ * Has padding and sits above backgrounds with z-10.
  */
-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}
-			/>
-		);
-	},
+const HeroContent = React.forwardRef<HTMLDivElement, HeroContentProps>(
+	({ className, ...props }, ref) => (
+		<div
+			ref={ref}
+			className={heroContentVariants({ class: 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,
-};
+HeroContent.displayName = "Hero.Content";
 
 // =============================================================================
 // Hero Component
 // =============================================================================
 
 export interface HeroProps
-	extends React.HTMLAttributes<HTMLElement>,
+	extends Omit<React.HTMLAttributes<HTMLElement>, "title">,
 		VariantProps<typeof heroVariants> {
 	/**
-	 * The title text displayed in the hero
+	 * The title text displayed in the hero.
+	 * If provided, renders an h1 with default typography.
+	 * Omit to use children for custom content composition.
 	 */
-	title: string;
+	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"
+	 * Default: "text-64 leading-64 tracking-64 md:text-128 md:leading-128 md:tracking-128 lg:text-192 lg:leading-192 lg:tracking-192"
 	 */
 	titleClassName?: string;
+	/**
+	 * Content for the top slot (full-width, no padding).
+	 * Use for USGovBanner, Navigation, etc.
+	 */
+	top?: React.ReactNode;
 	/**
 	 * Background for the hero. Can be:
 	 * - A color string (hex, rgb, etc.) for solid backgrounds
@@ -314,12 +161,24 @@ export interface HeroProps
 	 * Color of the overlay (default: "black")
 	 */
 	overlayColor?: string;
+	/**
+	 * Border radius for the hero container
+	 * Useful for designs with rounded bottom corners
+	 */
+	borderRadius?: string;
 	/**
 	 * Theme overrides for component styling via CSS custom properties
 	 */
 	theme?: ComponentTheme;
 }
 
+/**
+ * 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 lg:text-192 lg:leading-192 lg:tracking-192 font-medium";
+
 /**
  * Checks if the background prop is a color string
  */
@@ -331,7 +190,6 @@ function isColorString(
 		(background.startsWith("#") ||
 			background.startsWith("rgb") ||
 			background.startsWith("hsl") ||
-			// Named colors or CSS variables
 			/^(var\(|[a-z]+$)/i.test(background))
 	);
 }
@@ -339,80 +197,80 @@ function isColorString(
 /**
  * Hero component for page headers with large display typography.
  *
- * Features responsive sizing across three variants:
+ * Slots:
+ * - `top`: Full-width slot at top for USGovBanner, Navigation (no padding)
+ * - `children`: Main content slot with padding and alignment
+ *
+ * The `title` prop is a convenience for simple heroes - it renders an h1 with
+ * responsive typography. Children are always rendered, so you can use both
+ * or just children for full control.
+ *
+ * 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" />
+ * // Simple - just title and background
+ * <Hero title="Welcome" background="#1a1a1a" />
  *
- * // With background image
+ * // With top slot for banner/nav
  * <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}
- * />
+ *   top={
+ *     <>
+ *       <USGovBanner variant="inverted" />
+ *       <Navigation />
+ *     </>
+ *   }
+ * >
+ *   <h1>Board of Peace</h1>
+ *   <p>Subtitle goes here</p>
+ * </Hero>
  * ```
  */
-/**
- * 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,
+			children,
 			title,
 			titleClassName,
+			top,
 			variant,
 			background,
 			overlayOpacity = 0,
 			overlayColor = "black",
+			borderRadius,
 			theme,
 			style,
 			...props
 		},
 		ref,
 	) => {
+		const styles = heroVariants({ variant });
 		const isColor = isColorString(background);
 		const hasMediaBackground = background && !isColor;
 		const themeStyles = themeToStyleVars(theme);
 		const combinedStyles = {
 			...themeStyles,
 			...(isColor ? { backgroundColor: background } : {}),
+			...(borderRadius ? { borderRadius } : {}),
 			...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,
-				)}
+				className={styles.root({
+					class: [
+						// Default background color when no background is provided
+						!background && "bg-bg-overlay",
+						className,
+					],
+				})}
 				style={
 					Object.keys(combinedStyles).length > 0 ? combinedStyles : undefined
 				}
@@ -423,31 +281,60 @@ const Hero = React.forwardRef<HTMLElement, HeroProps>(
 
 				{/* Overlay */}
 				{hasMediaBackground && overlayOpacity > 0 && (
-					<div
-						aria-hidden="true"
-						className="absolute inset-0"
-						style={{
-							backgroundColor: overlayColor,
-							opacity: overlayOpacity,
-						}}
+					<BackgroundOverlay
+						opacity={overlayOpacity}
+						className={overlayColor !== "black" ? undefined : "bg-black"}
+						style={
+							overlayColor !== "black"
+								? { backgroundColor: overlayColor }
+								: undefined
+						}
 					/>
 				)}
 
-				{/* Content */}
-				<h1
-					className={cn(
-						// Use primitive tokens instead of semantic typography
-						titleClassName || DEFAULT_TITLE_TYPOGRAPHY,
-						"text-gray-50",
-						hasMediaBackground && "relative z-10",
+				{/* Top slot - full width, no padding (for banners, nav) */}
+				{top && <div className={styles.top()}>{top}</div>}
+
+				{/* Content slot - padded area with alignment */}
+				<div className={styles.content()}>
+					{/* Title - convenience prop, renders h1 with default typography */}
+					{title && (
+						<h1
+							className={[
+								titleClassName || DEFAULT_TITLE_TYPOGRAPHY,
+								"text-text-inverted",
+							]
+								.filter(Boolean)
+								.join(" ")}
+						>
+							{title}
+						</h1>
 					)}
-				>
-					{title}
-				</h1>
+
+					{/* Children - always render if provided */}
+					{children}
+				</div>
 			</section>
 		);
 	},
-);
+) as React.ForwardRefExoticComponent<
+	HeroProps & React.RefAttributes<HTMLElement>
+> & {
+	Header: typeof HeroHeader;
+	Content: typeof HeroContent;
+};
 Hero.displayName = "Hero";
 
-export { Hero, HeroBackground, heroVariants, DEFAULT_TITLE_TYPOGRAPHY };
+// Attach sub-components
+Hero.Header = HeroHeader;
+Hero.Content = HeroContent;
+
+export {
+	Hero,
+	heroVariants,
+	heroContentVariants,
+	heroHeaderVariants,
+	DEFAULT_TITLE_TYPOGRAPHY,
+	HeroHeader,
+	HeroContent,
+};

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

@@ -2,9 +2,22 @@ export {
 	DEFAULT_TITLE_TYPOGRAPHY,
 	Hero,
 	HeroBackground,
+	HeroBackgroundImage,
 	type HeroBackgroundImageProps,
+	HeroBackgroundStream,
 	type HeroBackgroundStreamProps,
+	HeroBackgroundVideo,
 	type HeroBackgroundVideoProps,
+	HeroContent,
+	type HeroContentProps,
+	HeroGradient,
+	type HeroGradientProps,
+	HeroHeader,
+	type HeroHeaderProps,
+	HeroOverlay,
+	type HeroOverlayProps,
 	type HeroProps,
+	heroContentVariants,
+	heroHeaderVariants,
 	heroVariants,
 } from "./hero";

package/src/components/sections/quote-block/index.ts

@@ -0,0 +1,5 @@
+export {
+	QuoteBlock,
+	type QuoteBlockProps,
+	quoteBlockVariants,
+} from "./quote-block";