@nationaldesignstudio/react 0.0.17 → 0.1.0

package/src/components/atoms/background/background.test.tsx

@@ -0,0 +1,213 @@
+import { describe, expect, test } from "vitest";
+import { page } from "vitest/browser";
+import { render } from "vitest-browser-react";
+import {
+	Background,
+	BackgroundGradient,
+	BackgroundImage,
+	BackgroundOverlay,
+	BackgroundVideo,
+} from "./background";
+
+describe("Background", () => {
+	describe("Background Container", () => {
+		test("renders as a div with absolute positioning", async () => {
+			render(<Background data-testid="bg-container">Content</Background>);
+			const container = page.getByTestId("bg-container");
+			await expect.element(container).toBeInTheDocument();
+			await expect.element(container).toHaveClass(/absolute/);
+			await expect.element(container).toHaveClass(/inset-0/);
+		});
+
+		test("has aria-hidden attribute", async () => {
+			render(<Background data-testid="bg-container" />);
+			await expect
+				.element(page.getByTestId("bg-container"))
+				.toHaveAttribute("aria-hidden", "true");
+		});
+
+		test("accepts custom className", async () => {
+			render(<Background data-testid="bg" className="custom-class" />);
+			await expect.element(page.getByTestId("bg")).toHaveClass(/custom-class/);
+		});
+	});
+
+	describe("BackgroundImage", () => {
+		test("renders an img element with src", async () => {
+			render(<BackgroundImage src="/test-image.jpg" data-testid="bg-img" />);
+			const img = page.getByTestId("bg-img");
+			await expect.element(img).toBeInTheDocument();
+			await expect.element(img).toHaveAttribute("src", "/test-image.jpg");
+		});
+
+		test("has object-cover class for proper fitting", async () => {
+			render(<BackgroundImage src="/test.jpg" data-testid="bg-img" />);
+			await expect
+				.element(page.getByTestId("bg-img"))
+				.toHaveClass(/object-cover/);
+		});
+
+		test("sets default alt to empty string for decorative images", async () => {
+			render(<BackgroundImage src="/test.jpg" data-testid="bg-img" />);
+			await expect
+				.element(page.getByTestId("bg-img"))
+				.toHaveAttribute("alt", "");
+		});
+
+		test("accepts custom alt text", async () => {
+			render(
+				<BackgroundImage
+					src="/test.jpg"
+					alt="Custom alt text"
+					data-testid="bg-img"
+				/>,
+			);
+			await expect
+				.element(page.getByTestId("bg-img"))
+				.toHaveAttribute("alt", "Custom alt text");
+		});
+
+		test("applies custom position via style", async () => {
+			render(
+				<BackgroundImage
+					src="/test.jpg"
+					position="top left"
+					data-testid="bg-img"
+				/>,
+			);
+			const img = page.getByTestId("bg-img");
+			// Check the style attribute contains the position
+			await expect.element(img).toHaveStyle({ objectPosition: "top left" });
+		});
+
+		test("supports render prop for custom element", async () => {
+			render(
+				<BackgroundImage
+					src="/test.jpg"
+					// biome-ignore lint/a11y/useAltText: Test case for custom element
+					render={<img className="custom-img-class" />}
+					data-testid="bg-img"
+				/>,
+			);
+			await expect
+				.element(page.getByTestId("bg-img"))
+				.toHaveClass(/custom-img-class/);
+		});
+	});
+
+	describe("BackgroundVideo", () => {
+		test("renders a video element", async () => {
+			render(<BackgroundVideo src="/test-video.mp4" data-testid="bg-video" />);
+			const video = page.getByTestId("bg-video");
+			await expect.element(video).toBeInTheDocument();
+		});
+
+		test("has autoplay, loop, and muted by default", async () => {
+			render(<BackgroundVideo src="/test.mp4" data-testid="bg-video" />);
+			const video = page.getByTestId("bg-video");
+			await expect.element(video).toHaveAttribute("autoplay");
+			await expect.element(video).toHaveAttribute("loop");
+			await expect.element(video).toHaveAttribute("muted");
+		});
+
+		test("has object-cover class", async () => {
+			render(<BackgroundVideo src="/test.mp4" data-testid="bg-video" />);
+			await expect
+				.element(page.getByTestId("bg-video"))
+				.toHaveClass(/object-cover/);
+		});
+
+		test("accepts poster prop", async () => {
+			render(
+				<BackgroundVideo
+					src="/test.mp4"
+					poster="/poster.jpg"
+					data-testid="bg-video"
+				/>,
+			);
+			await expect
+				.element(page.getByTestId("bg-video"))
+				.toHaveAttribute("poster", "/poster.jpg");
+		});
+	});
+
+	describe("BackgroundOverlay", () => {
+		test("renders with default opacity", async () => {
+			render(<BackgroundOverlay data-testid="bg-overlay" />);
+			const overlay = page.getByTestId("bg-overlay");
+			await expect.element(overlay).toBeInTheDocument();
+			await expect.element(overlay).toHaveStyle({ opacity: "0.4" });
+		});
+
+		test("accepts custom opacity", async () => {
+			render(<BackgroundOverlay opacity={0.7} data-testid="bg-overlay" />);
+			await expect
+				.element(page.getByTestId("bg-overlay"))
+				.toHaveStyle({ opacity: "0.7" });
+		});
+
+		test("has aria-hidden attribute", async () => {
+			render(<BackgroundOverlay data-testid="bg-overlay" />);
+			await expect
+				.element(page.getByTestId("bg-overlay"))
+				.toHaveAttribute("aria-hidden", "true");
+		});
+	});
+
+	describe("BackgroundGradient", () => {
+		test("renders with default gradient direction", async () => {
+			render(<BackgroundGradient data-testid="bg-gradient" />);
+			const gradient = page.getByTestId("bg-gradient");
+			await expect.element(gradient).toBeInTheDocument();
+		});
+
+		test("has aria-hidden attribute", async () => {
+			render(<BackgroundGradient data-testid="bg-gradient" />);
+			await expect
+				.element(page.getByTestId("bg-gradient"))
+				.toHaveAttribute("aria-hidden", "true");
+		});
+
+		test("accepts custom gradient via gradient prop", async () => {
+			render(
+				<BackgroundGradient
+					gradient="linear-gradient(45deg, red, blue)"
+					data-testid="bg-gradient"
+				/>,
+			);
+			await expect
+				.element(page.getByTestId("bg-gradient"))
+				.toHaveStyle({ backgroundImage: "linear-gradient(45deg, red, blue)" });
+		});
+	});
+
+	describe("Compound Component", () => {
+		test("Background.Image is accessible via dot notation", async () => {
+			render(
+				<Background data-testid="bg-container">
+					<Background.Image src="/test.jpg" data-testid="bg-img" />
+				</Background>,
+			);
+			await expect
+				.element(page.getByTestId("bg-container"))
+				.toBeInTheDocument();
+			await expect.element(page.getByTestId("bg-img")).toBeInTheDocument();
+		});
+
+		test("can compose multiple background layers", async () => {
+			render(
+				<Background data-testid="bg-container">
+					<Background.Image src="/test.jpg" data-testid="bg-img" />
+					<Background.Overlay data-testid="bg-overlay" />
+					<Background.Gradient data-testid="bg-gradient" />
+				</Background>,
+			);
+			await expect
+				.element(page.getByTestId("bg-container"))
+				.toBeInTheDocument();
+			await expect.element(page.getByTestId("bg-img")).toBeInTheDocument();
+			await expect.element(page.getByTestId("bg-overlay")).toBeInTheDocument();
+			await expect.element(page.getByTestId("bg-gradient")).toBeInTheDocument();
+		});
+	});
+});

package/src/components/atoms/background/background.tsx

@@ -0,0 +1,435 @@
+"use client";
+
+import { useRender } from "@base-ui-components/react/use-render";
+import * as React from "react";
+import { tv } from "tailwind-variants";
+
+// =============================================================================
+// Background Atomic Component
+// =============================================================================
+
+const backgroundVariants = tv({
+	base: "absolute inset-0",
+});
+
+/**
+ * Base container for background composition.
+ * Use as a wrapper to compose multiple background layers (image, video, overlay, gradient).
+ *
+ * @example
+ * ```tsx
+ * <Background>
+ *   <Background.Image src="/hero.jpg" />
+ *   <Background.Overlay opacity={0.4} />
+ *   <Background.Gradient direction="to-t" from="black" to="transparent" />
+ * </Background>
+ * ```
+ */
+export interface BackgroundProps extends React.HTMLAttributes<HTMLDivElement> {}
+
+const Background = React.forwardRef<HTMLDivElement, BackgroundProps>(
+	({ className, children, ...props }, ref) => (
+		<div
+			ref={ref}
+			aria-hidden="true"
+			className={backgroundVariants({ class: className })}
+			{...props}
+		>
+			{children}
+		</div>
+	),
+);
+Background.displayName = "Background";
+
+// =============================================================================
+// Background.Image
+// =============================================================================
+
+const backgroundImageVariants = tv({
+	base: "absolute inset-0 size-full object-cover",
+});
+
+export interface BackgroundImageProps
+	extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src"> {
+	/**
+	 * URL for the background image
+	 */
+	src: string;
+	/**
+	 * Object position (default: "center")
+	 */
+	position?: string;
+	/**
+	 * Custom render prop for element composition.
+	 * Accepts a React element or render function.
+	 * @example
+	 * ```tsx
+	 * // Element pattern
+	 * <BackgroundImage render={<img className="custom" />} src="/bg.jpg" />
+	 *
+	 * // Callback pattern
+	 * <BackgroundImage render={(props) => <img {...props} />} src="/bg.jpg" />
+	 * ```
+	 */
+	render?:
+		| React.ReactElement
+		| ((
+				props: React.ImgHTMLAttributes<HTMLImageElement>,
+		  ) => React.ReactElement);
+}
+
+/**
+ * Background image layer using an actual img element with object-cover.
+ * Supports native lazy loading, srcset, and better accessibility.
+ * Supports render prop for element composition.
+ */
+const BackgroundImage = React.forwardRef<
+	HTMLImageElement,
+	BackgroundImageProps
+>(
+	(
+		{ className, src, position = "center", alt = "", style, render, ...props },
+		ref,
+	) => {
+		const mergedProps = {
+			src,
+			alt,
+			className: backgroundImageVariants({ class: className }),
+			style: {
+				objectPosition: position,
+				...style,
+			},
+			...props,
+		};
+
+		const element = useRender({
+			// biome-ignore lint/a11y/useAltText: alt is provided via mergedProps
+			render: render ?? <img />,
+			ref,
+			props: mergedProps,
+		});
+
+		return element;
+	},
+);
+BackgroundImage.displayName = "Background.Image";
+
+// =============================================================================
+// Background.Video
+// =============================================================================
+
+const backgroundVideoVariants = tv({
+	base: "absolute inset-0 size-full object-cover",
+});
+
+export interface BackgroundVideoProps
+	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;
+	/**
+	 * Custom render prop for element composition.
+	 * @example
+	 * ```tsx
+	 * <BackgroundVideo render={<video className="custom" />} src="/bg.mp4" />
+	 * ```
+	 */
+	render?:
+		| React.ReactElement
+		| ((
+				props: React.VideoHTMLAttributes<HTMLVideoElement>,
+		  ) => React.ReactElement);
+}
+
+/**
+ * Background video layer using HTML5 video element.
+ * Supports render prop for element composition.
+ */
+const BackgroundVideo = React.forwardRef<
+	HTMLVideoElement,
+	BackgroundVideoProps
+>(
+	(
+		{
+			className,
+			src,
+			type,
+			poster,
+			autoPlay = true,
+			loop = true,
+			muted = true,
+			playsInline = true,
+			render,
+			...props
+		},
+		ref,
+	) => {
+		const mergedProps = {
+			autoPlay,
+			loop,
+			muted,
+			playsInline,
+			poster,
+			className: backgroundVideoVariants({ class: className }),
+			...props,
+		};
+
+		const element = useRender({
+			render: render ?? (
+				// biome-ignore lint/a11y/useMediaCaption: Background videos are decorative and shouldn't have captions
+				<video>
+					<source src={src} type={type} />
+				</video>
+			),
+			ref,
+			props: mergedProps,
+		});
+
+		return element;
+	},
+);
+BackgroundVideo.displayName = "Background.Video";
+
+// =============================================================================
+// Background.Stream
+// =============================================================================
+
+const backgroundStreamVariants = tv({
+	base: "absolute inset-0 size-full border-0 scale-[1.5] object-cover",
+});
+
+export interface BackgroundStreamProps
+	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 layer using Cloudflare Stream.
+ */
+const BackgroundStream = React.forwardRef<
+	HTMLIFrameElement,
+	BackgroundStreamProps
+>(
+	(
+		{
+			className,
+			videoId,
+			poster,
+			autoplay = true,
+			loop = true,
+			muted = true,
+			controls = false,
+			customerSubdomain,
+			title = "Background video",
+			...props
+		},
+		ref,
+	) => {
+		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);
+		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={backgroundStreamVariants({ class: className })}
+				{...props}
+			/>
+		);
+	},
+);
+BackgroundStream.displayName = "Background.Stream";
+
+// =============================================================================
+// Background.Overlay
+// =============================================================================
+
+const backgroundOverlayVariants = tv({
+	base: "absolute inset-0 bg-bg-overlay",
+});
+
+export interface BackgroundOverlayProps
+	extends React.HTMLAttributes<HTMLDivElement> {
+	/**
+	 * Overlay opacity (0-1)
+	 */
+	opacity?: number;
+}
+
+/**
+ * Solid color overlay layer. Uses semantic bg-overlay token by default.
+ * Override with className for different colors.
+ */
+const BackgroundOverlay = React.forwardRef<
+	HTMLDivElement,
+	BackgroundOverlayProps
+>(({ className, opacity = 0.4, style, ...props }, ref) => (
+	<div
+		ref={ref}
+		aria-hidden="true"
+		className={backgroundOverlayVariants({ class: className })}
+		style={{
+			opacity,
+			...style,
+		}}
+		{...props}
+	/>
+));
+BackgroundOverlay.displayName = "Background.Overlay";
+
+// =============================================================================
+// Background.Gradient
+// =============================================================================
+
+const backgroundGradientVariants = tv({
+	base: "absolute inset-0",
+});
+
+export interface BackgroundGradientProps
+	extends React.HTMLAttributes<HTMLDivElement> {
+	/**
+	 * Gradient direction (Tailwind convention: to-t, to-b, to-l, to-r, etc.)
+	 * Or CSS gradient direction (to top, to bottom, 45deg, etc.)
+	 */
+	direction?: string;
+	/**
+	 * Starting color (from)
+	 */
+	from?: string;
+	/**
+	 * Optional middle color (via)
+	 */
+	via?: string;
+	/**
+	 * Ending color (to)
+	 */
+	to?: string;
+	/**
+	 * Full custom gradient string (overrides from/via/to)
+	 */
+	gradient?: string;
+}
+
+/**
+ * Gradient overlay layer. Use for fading backgrounds or creating depth.
+ */
+const BackgroundGradient = React.forwardRef<
+	HTMLDivElement,
+	BackgroundGradientProps
+>(
+	(
+		{
+			className,
+			direction = "to-b",
+			from = "transparent",
+			via,
+			to = "black",
+			gradient,
+			style,
+			...props
+		},
+		ref,
+	) => {
+		// Convert Tailwind-style direction to CSS
+		const cssDirection = direction.startsWith("to-")
+			? direction.replace("to-", "to ")
+			: direction;
+
+		const gradientValue =
+			gradient ||
+			(via
+				? `linear-gradient(${cssDirection}, ${from}, ${via}, ${to})`
+				: `linear-gradient(${cssDirection}, ${from}, ${to})`);
+
+		return (
+			<div
+				ref={ref}
+				aria-hidden="true"
+				className={backgroundGradientVariants({ class: className })}
+				style={{
+					backgroundImage: gradientValue,
+					...style,
+				}}
+				{...props}
+			/>
+		);
+	},
+);
+BackgroundGradient.displayName = "Background.Gradient";
+
+// =============================================================================
+// Compound Export
+// =============================================================================
+
+const BackgroundCompound = Object.assign(Background, {
+	Image: BackgroundImage,
+	Video: BackgroundVideo,
+	Stream: BackgroundStream,
+	Overlay: BackgroundOverlay,
+	Gradient: BackgroundGradient,
+});
+
+export {
+	BackgroundCompound as Background,
+	BackgroundImage,
+	BackgroundVideo,
+	BackgroundStream,
+	BackgroundOverlay,
+	BackgroundGradient,
+	backgroundVariants,
+	backgroundImageVariants,
+	backgroundVideoVariants,
+	backgroundStreamVariants,
+	backgroundOverlayVariants,
+	backgroundGradientVariants,
+};

package/src/components/atoms/background/index.ts

@@ -0,0 +1,22 @@
+export type {
+	BackgroundGradientProps,
+	BackgroundImageProps,
+	BackgroundOverlayProps,
+	BackgroundProps,
+	BackgroundStreamProps,
+	BackgroundVideoProps,
+} from "./background";
+export {
+	Background,
+	BackgroundGradient,
+	BackgroundImage,
+	BackgroundOverlay,
+	BackgroundStream,
+	BackgroundVideo,
+	backgroundGradientVariants,
+	backgroundImageVariants,
+	backgroundOverlayVariants,
+	backgroundStreamVariants,
+	backgroundVariants,
+	backgroundVideoVariants,
+} from "./background";