@nationaldesignstudio/react 0.0.15 → 0.0.16

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

@@ -0,0 +1,171 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Button } from "../../atoms/button";
+import { NdstudioFooter } from "../../atoms/ndstudio-footer";
+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>
+			}
+		/>
+	),
+};
+
+/**
+ * With NdstudioFooter - shows the National Design Studio branding at the bottom
+ */
+export const WithNdstudioFooter: 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 />}
+			footer={<NdstudioFooter />}
+		/>
+	),
+};

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,270 @@
+import * as React from "react";
+import { tv, type VariantProps } from "tailwind-variants";
+import { type ComponentTheme, themeToStyleVars } from "@/lib/theme";
+import { cn } from "@/lib/utils";
+
+/**
+ * Tout variants for background and content styling
+ */
+const toutVariants = tv({
+	base: [
+		// 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]",
+	],
+	variants: {
+		variant: {
+			// Default light content styling
+			light: "",
+			// Dark content styling
+			dark: "",
+		},
+		align: {
+			left: "",
+			center: "",
+		},
+	},
+	defaultVariants: {
+		variant: "light",
+		align: "left",
+	},
+});
+
+/**
+ * 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.
+ *
+ * Variants:
+ * - light: Light text styling (default)
+ * - dark: Dark text styling
+ *
+ * Alignment:
+ * - left: Content aligned to the left (default)
+ * - center: Content 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>,
+		VariantProps<typeof toutVariants> {
+	/**
+	 * 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;
+	/**
+	 * Optional footer content to display at the bottom of the section.
+	 * Use with NdstudioFooter component for the branded footer.
+	 */
+	footer?: React.ReactNode;
+	/**
+	 * Component-level theme overrides.
+	 * Allows customization of colors, spacing, and surface properties.
+	 */
+	theme?: ComponentTheme;
+}
+
+/**
+ * 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"
+ *     />
+ *   }
+ *   footer={<NdstudioFooter />}
+ * />
+ * ```
+ */
+const Tout = React.forwardRef<HTMLElement, ToutProps>(
+	(
+		{
+			className,
+			variant = "light",
+			align = "left",
+			headline,
+			body,
+			primaryAction,
+			secondaryAction,
+			backgroundMedia,
+			footer,
+			theme,
+			style,
+			...props
+		},
+		ref,
+	) => {
+		const isCentered = align === "center";
+		const isDark = variant === "dark";
+		const themeStyles = themeToStyleVars(theme);
+
+		return (
+			<section
+				ref={ref}
+				className={toutVariants({ variant, align, class: className })}
+				style={{ ...themeStyles, ...style }}
+				{...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 - uses primitive spacing tokens */}
+				<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 - uses primitive spacing tokens
+						"px-spacing-20 md:px-spacing-56 lg:px-spacing-72",
+						// Vertical padding to position content at bottom - uses primitive spacing tokens
+						"py-spacing-36 md:py-spacing-56 lg:py-spacing-72",
+					)}
+					style={{
+						// Grid spacing theme overrides
+						...(theme?.spatial?.gridSmallMargin && {
+							paddingLeft: "var(--theme-grid-small-margin)",
+							paddingRight: "var(--theme-grid-small-margin)",
+						}),
+						...(theme?.spatial?.gridSmallGutter && {
+							gap: "var(--theme-grid-small-gutter)",
+						}),
+					}}
+				>
+					{/* 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 - uses primitive spacing tokens
+							"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 - uses primitive spacing tokens */}
+						<div
+							className={cn(
+								"flex flex-col gap-spacing-16",
+								isCentered && "items-center text-center",
+							)}
+						>
+							<h2
+								className={cn(
+									"typography-headline-small",
+									isDark ? "text-gray-100" : "text-gray-900",
+								)}
+								style={{
+									color: theme?.colors?.textPrimary
+										? "var(--theme-text-primary)"
+										: undefined,
+								}}
+							>
+								{headline}
+							</h2>
+							{body && (
+								<p
+									className={cn(
+										"typography-body-small",
+										isDark ? "text-gray-400" : "text-gray-800",
+									)}
+									style={{
+										color: theme?.colors?.textSecondary
+											? "var(--theme-text-secondary)"
+											: undefined,
+									}}
+								>
+									{body}
+								</p>
+							)}
+						</div>
+
+						{/* CTA buttons - uses primitive spacing tokens */}
+						<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>
+
+				{/* Footer slot */}
+				{footer && (
+					<div className="absolute bottom-6 md:bottom-8 left-0 right-0 z-10">
+						{footer}
+					</div>
+				)}
+			</section>
+		);
+	},
+);
+Tout.displayName = "Tout";
+
+export { Tout, toutVariants };

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

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