@nationaldesignstudio/react 0.0.7 → 0.0.9

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

@@ -0,0 +1,145 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Hero } from ".";
+
+const meta: Meta<typeof Hero> = {
+	title: "Sections/Hero",
+	component: Hero,
+	parameters: {
+		layout: "fullscreen",
+	},
+	argTypes: {
+		variant: {
+			control: "select",
+			options: ["A1", "A2", "A3"],
+			description: "Hero variant controlling content alignment",
+		},
+		title: {
+			control: "text",
+			description: "The title text displayed in the hero",
+		},
+	},
+} as Meta<typeof Hero>;
+
+export default meta;
+type Story = StoryObj<typeof Hero>;
+
+export const Playground: Story = {
+	render: (args) => <Hero {...args} />,
+};
+Playground.args = {
+	title: "Hero Title",
+	variant: "A1",
+};
+
+// =============================================================================
+// Variants
+// =============================================================================
+
+/**
+ * A1 variant: Content aligned at the bottom of the hero.
+ * This is the default variant.
+ */
+export const A1: Story = {
+	render: () => <Hero variant="A1" title="Hero A1" />,
+};
+
+/**
+ * A2 variant: Content aligned at the top of the hero.
+ */
+export const A2: Story = {
+	render: () => <Hero variant="A2" title="Hero A2" />,
+};
+
+/**
+ * A3 variant: Content centered vertically in the hero.
+ */
+export const A3: Story = {
+	render: () => <Hero variant="A3" title="Hero A3" />,
+};
+
+// =============================================================================
+// Responsive Variants - A1 (Content at bottom)
+// =============================================================================
+
+export const A1Desktop: Story = {
+	render: () => <Hero variant="A1" title="Hero A1" />,
+	globals: {
+		viewport: { value: "lg", isRotated: false },
+	},
+};
+
+export const A1Tablet: Story = {
+	render: () => <Hero variant="A1" title="Hero A1" />,
+	globals: {
+		viewport: { value: "md", isRotated: false },
+	},
+};
+
+export const A1Mobile: Story = {
+	render: () => <Hero variant="A1" title="Hero A1" />,
+	globals: {
+		viewport: { value: "sm", isRotated: false },
+	},
+};
+
+// =============================================================================
+// Responsive Variants - A2 (Content at top)
+// =============================================================================
+
+export const A2Desktop: Story = {
+	render: () => <Hero variant="A2" title="Hero A2" />,
+	globals: {
+		viewport: { value: "lg", isRotated: false },
+	},
+};
+
+export const A2Tablet: Story = {
+	render: () => <Hero variant="A2" title="Hero A2" />,
+	globals: {
+		viewport: { value: "md", isRotated: false },
+	},
+};
+
+export const A2Mobile: Story = {
+	render: () => <Hero variant="A2" title="Hero A2" />,
+	globals: {
+		viewport: { value: "sm", isRotated: false },
+	},
+};
+
+// =============================================================================
+// Responsive Variants - A3 (Content centered)
+// =============================================================================
+
+export const A3Desktop: Story = {
+	render: () => <Hero variant="A3" title="Hero A3" />,
+	globals: {
+		viewport: { value: "lg", isRotated: false },
+	},
+};
+
+export const A3Tablet: Story = {
+	render: () => <Hero variant="A3" title="Hero A3" />,
+	globals: {
+		viewport: { value: "md", isRotated: false },
+	},
+};
+
+export const A3Mobile: Story = {
+	render: () => <Hero variant="A3" title="Hero A3" />,
+	globals: {
+		viewport: { value: "sm", isRotated: false },
+	},
+};
+
+// =============================================================================
+// Examples
+// =============================================================================
+
+export const WithLongTitle: Story = {
+	render: () => <Hero title="A Much Longer Hero Title That Wraps" />,
+};
+
+export const WithCustomClassName: Story = {
+	render: () => <Hero title="Custom Background" className="bg-blue-600" />,
+};

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

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "vitest";
+import { page } from "vitest/browser";
+import { render } from "vitest-browser-react";
+import { Hero } from "./hero";
+
+describe("Hero", () => {
+	describe("Accessibility", () => {
+		test("renders as section landmark", async () => {
+			render(<Hero title="Test Hero" data-testid="hero" />);
+
+			// Section is a region landmark when it has an accessible name
+			const hero = page.getByTestId("hero");
+			await expect.element(hero).toBeInTheDocument();
+		});
+
+		test("title renders as h1 heading", async () => {
+			render(<Hero title="Hero Title" />);
+
+			await expect
+				.element(page.getByRole("heading", { level: 1, name: "Hero Title" }))
+				.toBeInTheDocument();
+		});
+
+		test("title is accessible to screen readers", async () => {
+			render(<Hero title="Accessible Title" />);
+
+			await expect
+				.element(page.getByText("Accessible Title"))
+				.toBeInTheDocument();
+		});
+	});
+
+	describe("Props", () => {
+		test("renders with required title prop", async () => {
+			render(<Hero title="Required Title" />);
+
+			await expect
+				.element(page.getByText("Required Title"))
+				.toBeInTheDocument();
+		});
+
+		test("supports custom className", async () => {
+			render(
+				<Hero title="Custom" className="custom-class" data-testid="hero" />,
+			);
+
+			const hero = page.getByTestId("hero");
+			await expect.element(hero).toHaveClass(/custom-class/);
+		});
+
+		test("spreads additional props to section element", async () => {
+			render(
+				<Hero
+					title="Props Test"
+					data-testid="hero"
+					aria-label="Hero section"
+				/>,
+			);
+
+			const hero = page.getByTestId("hero");
+			await expect.element(hero).toHaveAttribute("aria-label", "Hero section");
+		});
+	});
+
+	describe("Styling", () => {
+		test("applies default background color", async () => {
+			render(<Hero title="Default" data-testid="hero" />);
+
+			const hero = page.getByTestId("hero");
+			await expect.element(hero).toHaveClass(/bg-gray-1000/);
+		});
+
+		test("applies responsive height classes", async () => {
+			render(<Hero title="Responsive" data-testid="hero" />);
+
+			const hero = page.getByTestId("hero");
+			// Mobile height
+			await expect.element(hero).toHaveClass(/h-\[500px\]/);
+		});
+	});
+
+	describe("Variants", () => {
+		test("A1 variant applies items-end alignment (default)", async () => {
+			render(<Hero title="A1 Hero" variant="A1" data-testid="hero" />);
+
+			const hero = page.getByTestId("hero");
+			await expect.element(hero).toHaveClass(/items-end/);
+		});
+
+		test("A1 variant is default when no variant specified", async () => {
+			render(<Hero title="Default Hero" data-testid="hero" />);
+
+			const hero = page.getByTestId("hero");
+			await expect.element(hero).toHaveClass(/items-end/);
+		});
+
+		test("A2 variant applies items-start alignment", async () => {
+			render(<Hero title="A2 Hero" variant="A2" data-testid="hero" />);
+
+			const hero = page.getByTestId("hero");
+			await expect.element(hero).toHaveClass(/items-start/);
+		});
+
+		test("A3 variant applies items-center alignment", async () => {
+			render(<Hero title="A3 Hero" variant="A3" data-testid="hero" />);
+
+			const hero = page.getByTestId("hero");
+			await expect.element(hero).toHaveClass(/items-center/);
+		});
+
+		test("A1 variant maintains common styles", async () => {
+			render(<Hero title="A1 Hero" variant="A1" data-testid="hero" />);
+
+			const hero = page.getByTestId("hero");
+			await expect.element(hero).toHaveClass(/bg-gray-1000/);
+			await expect.element(hero).toHaveClass(/h-\[500px\]/);
+		});
+
+		test("A2 variant maintains common styles", async () => {
+			render(<Hero title="A2 Hero" variant="A2" data-testid="hero" />);
+
+			const hero = page.getByTestId("hero");
+			await expect.element(hero).toHaveClass(/bg-gray-1000/);
+			await expect.element(hero).toHaveClass(/h-\[500px\]/);
+		});
+
+		test("A3 variant maintains common styles", async () => {
+			render(<Hero title="A3 Hero" variant="A3" data-testid="hero" />);
+
+			const hero = page.getByTestId("hero");
+			await expect.element(hero).toHaveClass(/bg-gray-1000/);
+			await expect.element(hero).toHaveClass(/h-\[500px\]/);
+		});
+	});
+});

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

@@ -0,0 +1,191 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import * as React from "react";
+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 = cva(
+	[
+		"flex w-full bg-gray-1000",
+		// Mobile (sm)
+		"h-[500px] p-spacing-20",
+		// Tablet (md)
+		"md:h-[650px] md:p-spacing-56",
+	],
+	{
+		variants: {
+			variant: {
+				// A1: Content at bottom
+				A1: [
+					"items-end",
+					// Desktop (lg) - 800px height, 72px padding
+					"xl:h-[800px] xl:p-spacing-72",
+				],
+				// A2: Content at top
+				A2: [
+					"items-start",
+					// Desktop (lg) - 700px height, 64px padding
+					"xl:h-[700px] xl:p-spacing-64",
+				],
+				// A3: Content centered
+				A3: [
+					"items-center",
+					// Desktop (lg) - 800px height, 64px padding
+					"xl:h-[800px] xl:p-spacing-64",
+				],
+			},
+		},
+		defaultVariants: {
+			variant: "A1",
+		},
+	},
+);
+
+export interface HeroProps
+	extends React.HTMLAttributes<HTMLElement>,
+		VariantProps<typeof heroVariants> {
+	/**
+	 * The title text displayed in the hero
+	 */
+	title: string;
+	/**
+	 * URL for the background image
+	 */
+	backgroundImage?: string;
+	/**
+	 * URL for a background video (takes precedence over backgroundImage)
+	 */
+	backgroundVideo?: string;
+	/**
+	 * Opacity of the dark overlay (0-1, default: 0)
+	 */
+	overlayOpacity?: number;
+	/**
+	 * Color of the overlay (default: "black")
+	 */
+	overlayColor?: string;
+	/**
+	 * CSS background-position value (default: "center")
+	 */
+	backgroundPosition?: string;
+}
+
+/**
+ * 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
+ * <Hero title="Welcome" variant="A1" />
+ *
+ * // With background image and overlay
+ * <Hero
+ *   title="Welcome"
+ *   variant="A1"
+ *   backgroundImage="/hero.jpg"
+ *   overlayOpacity={0.4}
+ * />
+ * ```
+ */
+const Hero = React.forwardRef<HTMLElement, HeroProps>(
+	(
+		{
+			className,
+			title,
+			variant,
+			backgroundImage,
+			backgroundVideo,
+			overlayOpacity = 0,
+			overlayColor = "black",
+			backgroundPosition = "center",
+			...props
+		},
+		ref,
+	) => {
+		const hasBackground = backgroundImage || backgroundVideo;
+
+		return (
+			<section
+				ref={ref}
+				className={cn(
+					heroVariants({ variant }),
+					hasBackground && "relative overflow-hidden",
+					className,
+				)}
+				{...props}
+			>
+				{/* Background image */}
+				{backgroundImage && !backgroundVideo && (
+					<div
+						aria-hidden="true"
+						className="absolute inset-0 bg-cover"
+						style={{
+							backgroundImage: `url(${backgroundImage})`,
+							backgroundPosition,
+						}}
+					/>
+				)}
+
+				{/* Background video */}
+				{backgroundVideo && (
+					<video
+						autoPlay
+						loop
+						muted
+						playsInline
+						aria-hidden="true"
+						className="absolute inset-0 h-full w-full object-cover"
+					>
+						<source src={backgroundVideo} />
+					</video>
+				)}
+
+				{/* Overlay */}
+				{hasBackground && overlayOpacity > 0 && (
+					<div
+						aria-hidden="true"
+						className="absolute inset-0"
+						style={{
+							backgroundColor: overlayColor,
+							opacity: overlayOpacity,
+						}}
+					/>
+				)}
+
+				{/* Content */}
+				<h1
+					className={cn(
+						"typography-display-large text-gray-50",
+						hasBackground && "relative z-10",
+					)}
+				>
+					{title}
+				</h1>
+			</section>
+		);
+	},
+);
+Hero.displayName = "Hero";
+
+export { Hero, heroVariants };

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 @@
+export { Hero, 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";