@nationaldesignstudio/react 0.0.7 → 0.0.9

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

@@ -0,0 +1,154 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Button } from "../../atoms/button";
+import { Tout } from ".";
+
+const meta: Meta<typeof Tout> = {
+	title: "Sections/Tout",
+	component: Tout,
+	parameters: {
+		layout: "fullscreen",
+	},
+	argTypes: {
+		headline: {
+			control: "text",
+			description: "The headline text",
+		},
+		body: {
+			control: "text",
+			description: "The body text",
+		},
+	},
+} as Meta<typeof Tout>;
+
+export default meta;
+type Story = StoryObj<typeof Tout>;
+
+const PlaceholderBackground = () => (
+	<div className="absolute inset-0 bg-gradient-to-br from-gray-300 to-gray-400" />
+);
+
+const ImageBackground = () => (
+	<img
+		src="https://images.unsplash.com/photo-1557804506-669a67965ba0?w=1600&h=900&fit=crop"
+		alt=""
+		className="absolute inset-0 w-full h-full object-cover"
+	/>
+);
+
+export const Playground: Story = {
+	render: (args) => <Tout {...args} />,
+};
+Playground.args = {
+	headline: "Brand-Large/Headline/Small",
+	body: "A river pattern stacks content in a simple vertical flow: one clear heading, a short block of copy, then the next step. It's ideal for guiding citizens through a process or story, keeping focus moving straight down the page with minimal choices and well-timed calls to action.",
+	primaryAction: <Button>Primary</Button>,
+	secondaryAction: <Button variant="charcoalOutline">Secondary</Button>,
+	backgroundMedia: <PlaceholderBackground />,
+};
+
+// =============================================================================
+// Responsive Variants
+// =============================================================================
+
+export const Desktop: Story = {
+	render: () => (
+		<Tout
+			headline="Brand-Large/Headline/Small"
+			body="A river pattern stacks content in a simple vertical flow: one clear heading, a short block of copy, then the next step. It's ideal for guiding citizens through a process or story, keeping focus moving straight down the page with minimal choices and well-timed calls to action."
+			primaryAction={<Button>Primary</Button>}
+			secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+			backgroundMedia={<PlaceholderBackground />}
+		/>
+	),
+	globals: {
+		viewport: { value: "lg", isRotated: false },
+	},
+};
+
+export const Tablet: Story = {
+	render: () => (
+		<Tout
+			headline="Brand-Large/Headline/Small"
+			body="A river pattern stacks content in a simple vertical flow: one clear heading, a short block of copy, then the next step. It's ideal for guiding citizens through a process or story, keeping focus moving straight down the page with minimal choices and well-timed calls to action."
+			primaryAction={<Button>Primary</Button>}
+			secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+			backgroundMedia={<PlaceholderBackground />}
+		/>
+	),
+	globals: {
+		viewport: { value: "md", isRotated: false },
+	},
+};
+
+export const Mobile: Story = {
+	render: () => (
+		<Tout
+			headline="Brand-Large/Headline/Small"
+			body="A river pattern stacks content in a simple vertical flow: one clear heading, a short block of copy, then the next step. It's ideal for guiding citizens through a process or story, keeping focus moving straight down the page with minimal choices and well-timed calls to action."
+			primaryAction={<Button size="sm">Primary</Button>}
+			secondaryAction={
+				<Button size="sm" variant="charcoalOutline">
+					Secondary
+				</Button>
+			}
+			backgroundMedia={<PlaceholderBackground />}
+		/>
+	),
+	globals: {
+		viewport: { value: "sm", isRotated: false },
+	},
+};
+
+// =============================================================================
+// Examples
+// =============================================================================
+
+/**
+ * With actual background image
+ */
+export const WithImage: Story = {
+	render: () => (
+		<Tout
+			headline="Work with Purpose"
+			body="Join a team that's building the future of government services. We're looking for passionate individuals who want to make a difference."
+			primaryAction={<Button>View Careers</Button>}
+			secondaryAction={<Button variant="charcoalOutline">Learn More</Button>}
+			backgroundMedia={<ImageBackground />}
+		/>
+	),
+};
+
+/**
+ * Without secondary action
+ */
+export const SingleAction: Story = {
+	render: () => (
+		<Tout
+			headline="Get Started Today"
+			body="Begin your journey with our comprehensive onboarding process designed to help you succeed from day one."
+			primaryAction={<Button>Start Now</Button>}
+			backgroundMedia={<PlaceholderBackground />}
+		/>
+	),
+};
+
+/**
+ * With video background (placeholder)
+ */
+export const WithVideoPlaceholder: Story = {
+	render: () => (
+		<Tout
+			headline="Experience Innovation"
+			body="See how modern technology is transforming the way government serves its citizens."
+			primaryAction={<Button>Watch Video</Button>}
+			secondaryAction={<Button variant="charcoalOutline">Learn More</Button>}
+			backgroundMedia={
+				<div className="absolute inset-0 bg-gray-800 flex items-center justify-center">
+					<span className="text-gray-400 typography-body-small">
+						Video Background
+					</span>
+				</div>
+			}
+		/>
+	),
+};

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

@@ -0,0 +1,242 @@
+import { describe, expect, test } from "vitest";
+import { page } from "vitest/browser";
+import { render } from "vitest-browser-react";
+import { Tout } from "./tout";
+
+const PlaceholderBackground = () => (
+	<div data-testid="background" className="absolute inset-0 bg-gray-300" />
+);
+
+describe("Tout", () => {
+	describe("Accessibility", () => {
+		test("renders as section landmark", async () => {
+			render(
+				<Tout
+					headline="Test Headline"
+					body="Test body"
+					primaryAction={<button type="button">Action</button>}
+					backgroundMedia={<PlaceholderBackground />}
+					data-testid="tout"
+				/>,
+			);
+
+			const tout = page.getByTestId("tout");
+			await expect.element(tout).toBeInTheDocument();
+		});
+
+		test("headline renders as h2", async () => {
+			render(
+				<Tout
+					headline="Tout Headline"
+					body="Test body"
+					primaryAction={<button type="button">Action</button>}
+					backgroundMedia={<PlaceholderBackground />}
+				/>,
+			);
+
+			await expect
+				.element(page.getByRole("heading", { level: 2, name: "Tout Headline" }))
+				.toBeInTheDocument();
+		});
+
+		test("body text is accessible", async () => {
+			render(
+				<Tout
+					headline="Test"
+					body="Accessible body text"
+					primaryAction={<button type="button">Action</button>}
+					backgroundMedia={<PlaceholderBackground />}
+				/>,
+			);
+
+			await expect
+				.element(page.getByText("Accessible body text"))
+				.toBeInTheDocument();
+		});
+
+		test("background is hidden from screen readers", async () => {
+			render(
+				<Tout
+					headline="Test"
+					body="Test"
+					primaryAction={<button type="button">Action</button>}
+					backgroundMedia={<PlaceholderBackground />}
+					data-testid="tout"
+				/>,
+			);
+
+			const tout = page.getByTestId("tout");
+			await expect.element(tout).toBeInTheDocument();
+		});
+	});
+
+	describe("Props", () => {
+		test("renders with required props", async () => {
+			render(
+				<Tout
+					headline="Required Headline"
+					body="Required body"
+					primaryAction={<button type="button">Primary</button>}
+					backgroundMedia={<PlaceholderBackground />}
+				/>,
+			);
+
+			await expect
+				.element(page.getByText("Required Headline"))
+				.toBeInTheDocument();
+			await expect.element(page.getByText("Required body")).toBeInTheDocument();
+			await expect
+				.element(page.getByRole("button", { name: "Primary" }))
+				.toBeInTheDocument();
+			await expect.element(page.getByTestId("background")).toBeInTheDocument();
+		});
+
+		test("renders secondary action when provided", async () => {
+			render(
+				<Tout
+					headline="Test"
+					body="Test"
+					primaryAction={<button type="button">Primary</button>}
+					secondaryAction={<button type="button">Secondary</button>}
+					backgroundMedia={<PlaceholderBackground />}
+				/>,
+			);
+
+			await expect
+				.element(page.getByRole("button", { name: "Primary" }))
+				.toBeInTheDocument();
+			await expect
+				.element(page.getByRole("button", { name: "Secondary" }))
+				.toBeInTheDocument();
+		});
+
+		test("does not render secondary action when not provided", async () => {
+			render(
+				<Tout
+					headline="Test"
+					body="Test"
+					primaryAction={<button type="button">Primary</button>}
+					backgroundMedia={<PlaceholderBackground />}
+				/>,
+			);
+
+			await expect
+				.element(page.getByRole("button", { name: "Primary" }))
+				.toBeInTheDocument();
+			// Should only have one button
+			const buttons = page.getByRole("button");
+			await expect.element(buttons).toBeInTheDocument();
+		});
+
+		test("supports custom className", async () => {
+			render(
+				<Tout
+					headline="Test"
+					body="Test"
+					primaryAction={<button type="button">Action</button>}
+					backgroundMedia={<PlaceholderBackground />}
+					className="custom-class"
+					data-testid="tout"
+				/>,
+			);
+
+			const tout = page.getByTestId("tout");
+			await expect.element(tout).toHaveClass(/custom-class/);
+		});
+
+		test("spreads additional props to section element", async () => {
+			render(
+				<Tout
+					headline="Test"
+					body="Test"
+					primaryAction={<button type="button">Action</button>}
+					backgroundMedia={<PlaceholderBackground />}
+					data-testid="tout"
+					aria-label="Tout section"
+				/>,
+			);
+
+			const tout = page.getByTestId("tout");
+			await expect.element(tout).toHaveAttribute("aria-label", "Tout section");
+		});
+	});
+
+	describe("Styling", () => {
+		test("applies full width class", async () => {
+			render(
+				<Tout
+					headline="Test"
+					body="Test"
+					primaryAction={<button type="button">Action</button>}
+					backgroundMedia={<PlaceholderBackground />}
+					data-testid="tout"
+				/>,
+			);
+
+			const tout = page.getByTestId("tout");
+			await expect.element(tout).toHaveClass(/w-full/);
+		});
+
+		test("applies responsive height classes", async () => {
+			render(
+				<Tout
+					headline="Test"
+					body="Test"
+					primaryAction={<button type="button">Action</button>}
+					backgroundMedia={<PlaceholderBackground />}
+					data-testid="tout"
+				/>,
+			);
+
+			const tout = page.getByTestId("tout");
+			await expect.element(tout).toHaveClass(/h-\[600px\]/);
+		});
+
+		test("applies relative positioning for z-index context", async () => {
+			render(
+				<Tout
+					headline="Test"
+					body="Test"
+					primaryAction={<button type="button">Action</button>}
+					backgroundMedia={<PlaceholderBackground />}
+					data-testid="tout"
+				/>,
+			);
+
+			const tout = page.getByTestId("tout");
+			await expect.element(tout).toHaveClass(/relative/);
+		});
+	});
+
+	describe("Content", () => {
+		test("headline has correct styling", async () => {
+			render(
+				<Tout
+					headline="Styled Headline"
+					body="Test"
+					primaryAction={<button type="button">Action</button>}
+					backgroundMedia={<PlaceholderBackground />}
+				/>,
+			);
+
+			const headline = page.getByRole("heading", { level: 2 });
+			await expect.element(headline).toHaveClass(/typography-headline-small/);
+			await expect.element(headline).toHaveClass(/text-gray-900/);
+		});
+
+		test("body has correct styling", async () => {
+			render(
+				<Tout
+					headline="Test"
+					body="Styled body text"
+					primaryAction={<button type="button">Action</button>}
+					backgroundMedia={<PlaceholderBackground />}
+				/>,
+			);
+
+			const body = page.getByText("Styled body text");
+			await expect.element(body).toHaveClass(/typography-body-small/);
+			await expect.element(body).toHaveClass(/text-gray-800/);
+		});
+	});
+});

package/src/components/sections/tout/tout.tsx

@@ -0,0 +1,206 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+/**
+ * Tout component based on Figma BaseKit / Touts
+ *
+ * A full-bleed section with a background image and overlaid content.
+ * Content can be positioned on the left side or centered.
+ *
+ * Responsive behavior:
+ * - Mobile (sm): 600px height, 4 columns with gap-20, content spans all 4 cols
+ * - Tablet (md): 750px height, 12 columns with gap-20, content spans 9 cols (left) or centered
+ * - Desktop (lg): 900px height, 24 columns with gap-20, content spans 9 cols (left) or centered
+ *
+ * This component is self-contained - do NOT wrap in a grid-container.
+ */
+export interface ToutProps extends React.HTMLAttributes<HTMLElement> {
+	/**
+	 * The headline displayed in the tout
+	 */
+	headline: React.ReactNode;
+	/**
+	 * The body text displayed below the headline (optional)
+	 */
+	body?: string;
+	/**
+	 * Primary action button (required)
+	 */
+	primaryAction: React.ReactNode;
+	/**
+	 * Secondary action button (optional)
+	 */
+	secondaryAction?: React.ReactNode;
+	/**
+	 * Background media (image or video element)
+	 * Should be a full-bleed element that covers the entire section
+	 */
+	backgroundMedia: React.ReactNode;
+	/**
+	 * Content alignment: left (default) or center
+	 */
+	align?: "left" | "center";
+	/**
+	 * Show National Design Studio footer link at the bottom of the section
+	 */
+	ndstudioFooter?: boolean;
+}
+
+/**
+ * Tout component for hero-like sections with background media and overlaid content.
+ *
+ * This component is self-contained with its own grid.
+ * Grid setup:
+ * - Desktop (lg): 24 columns, gap-spacing-20, content spans 9 cols
+ * - Tablet (md): 12 columns, gap-spacing-20, content spans 9 cols
+ * - Mobile: 4 columns, gap-spacing-20, content spans all 4 cols
+ *
+ * @example
+ * ```tsx
+ * <Tout
+ *   headline="Feature Headline"
+ *   body="Description of the feature..."
+ *   primaryAction={<Button>Primary</Button>}
+ *   secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+ *   backgroundMedia={
+ *     <img
+ *       src="/background.jpg"
+ *       alt=""
+ *       className="absolute inset-0 w-full h-full object-cover"
+ *     />
+ *   }
+ * />
+ * ```
+ */
+const Tout = React.forwardRef<HTMLElement, ToutProps>(
+	(
+		{
+			className,
+			headline,
+			body,
+			primaryAction,
+			secondaryAction,
+			backgroundMedia,
+			align = "left",
+			ndstudioFooter,
+			...props
+		},
+		ref,
+	) => {
+		const isCentered = align === "center";
+
+		return (
+			<section
+				ref={ref}
+				className={cn(
+					// Full width
+					"w-full",
+					// Positioning context for background
+					"relative overflow-hidden",
+					// Responsive height: 600px mobile, 750px tablet, 900px desktop
+					"h-[600px] md:h-[750px] lg:h-[900px]",
+					className,
+				)}
+				{...props}
+			>
+				{/* Background layer - full bleed */}
+				<div
+					aria-hidden="true"
+					className="absolute inset-0 pointer-events-none"
+				>
+					{/* Fallback background color */}
+					<div className="absolute inset-0 bg-gray-500" />
+					{/* Background media */}
+					{backgroundMedia}
+				</div>
+
+				{/* Inner grid for content alignment */}
+				<div
+					className={cn(
+						// Position above background
+						"relative z-10",
+						// Grid setup with responsive columns
+						"grid w-full h-full",
+						// Mobile: 4 columns with gap-20
+						"grid-cols-4 gap-spacing-20",
+						// Tablet (md): 12 columns
+						"md:grid-cols-12",
+						// Desktop (lg): 24 columns
+						"lg:grid-cols-24",
+						// Max width and centering like grid-container
+						"max-w-[var(--breakpoint-lg)] mx-auto",
+						// Responsive margins matching grid-container
+						"px-spacing-20 md:px-spacing-56 lg:px-spacing-72",
+						// Vertical padding to position content at bottom
+						"py-spacing-36 md:py-spacing-56 lg:py-spacing-72",
+					)}
+				>
+					{/* Content column - aligned to grid */}
+					<div
+						className={cn(
+							// Flex container for content
+							"flex flex-col",
+							isCentered ? "justify-start items-center" : "justify-end",
+							// Responsive gap between text and buttons
+							"gap-spacing-28 md:gap-spacing-36",
+							// Mobile: all 4 cols
+							"col-span-4",
+							// Tablet & Desktop: 9 cols left-aligned, full width centered
+							isCentered ? "md:col-span-12 lg:col-span-24" : "md:col-span-9",
+						)}
+					>
+						{/* Text content stack */}
+						<div
+							className={cn(
+								"flex flex-col gap-spacing-16",
+								isCentered && "items-center text-center",
+							)}
+						>
+							<h2 className="typography-headline-small text-gray-900">
+								{headline}
+							</h2>
+							{body && (
+								<p className="typography-body-small text-gray-800">{body}</p>
+							)}
+						</div>
+
+						{/* CTA buttons */}
+						<div
+							className={cn(
+								"flex flex-row",
+								isCentered ? "justify-center" : "items-start",
+								// Responsive gap between buttons
+								"gap-spacing-8 md:gap-spacing-12",
+								"[&>*]:flex-shrink-0",
+							)}
+						>
+							{primaryAction}
+							{secondaryAction}
+						</div>
+					</div>
+				</div>
+
+				{/* National Design Studio footer */}
+				{ndstudioFooter && (
+					<div className="absolute bottom-6 md:bottom-8 left-0 right-0 z-10 text-center">
+						<p className="typography-label-large uppercase text-ivory-alpha-75">
+							Designed and Engineered in DC by{" "}
+							<a
+								href="https://ndstudio.gov"
+								target="_blank"
+								rel="noopener noreferrer"
+								className="hover:underline"
+							>
+								National Design Studio
+								<span className="sr-only"> (opens in new tab)</span>
+							</a>
+						</p>
+					</div>
+				)}
+			</section>
+		);
+	},
+);
+Tout.displayName = "Tout";
+
+export { Tout };

package/src/components/sections/two-column-section/index.ts

@@ -0,0 +1,5 @@
+export {
+	TwoColumnSection,
+	type TwoColumnSectionProps,
+	twoColumnSectionVariants,
+} from "./two-column-section";