@nationaldesignstudio/react 0.0.7 → 0.0.8

package/src/components/organisms/us-gov-banner/us-gov-banner.visual.test.tsx

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "vitest";
+import { page } from "vitest/browser";
+import { render } from "vitest-browser-react";
+import { USGovBanner } from "./us-gov-banner";
+
+describe("USGovBanner Visual Regression", () => {
+	test("default banner renders correctly", async () => {
+		await page.viewport(1280, 800);
+
+		render(<USGovBanner data-testid="banner" />);
+
+		await expect(page.getByTestId("banner")).toMatchScreenshot(
+			"us-gov-banner-default",
+		);
+	});
+
+	test("banner with custom text renders correctly", async () => {
+		await page.viewport(1280, 800);
+
+		render(
+			<USGovBanner
+				data-testid="banner"
+				text="An official website of the State of California"
+			/>,
+		);
+
+		await expect(page.getByTestId("banner")).toMatchScreenshot(
+			"us-gov-banner-custom-text",
+		);
+	});
+
+	test("banner with custom flag icon renders correctly", async () => {
+		await page.viewport(1280, 800);
+
+		render(
+			<USGovBanner
+				data-testid="banner"
+				flagIcon={<span aria-hidden="true">🏛️</span>}
+			/>,
+		);
+
+		await expect(page.getByTestId("banner")).toMatchScreenshot(
+			"us-gov-banner-custom-icon",
+		);
+	});
+});

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

@@ -0,0 +1,150 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Button } from "../../atoms/button";
+import { Banner } from ".";
+
+const meta: Meta<typeof Banner> = {
+	title: "Sections/Banner",
+	component: Banner,
+	parameters: {
+		layout: "fullscreen",
+	},
+	argTypes: {
+		heading: {
+			control: "text",
+			description: "The heading text displayed in the banner",
+		},
+		description: {
+			control: "text",
+			description: "The description text displayed below the heading",
+		},
+	},
+} as Meta<typeof Banner>;
+
+export default meta;
+type Story = StoryObj<typeof Banner>;
+
+export const Playground: Story = {
+	render: (args) => <Banner {...args} />,
+};
+Playground.args = {
+	heading: "Important Update",
+	description:
+		"Use banners to surface short, important updates or a single key action without disrupting the main page content.",
+	action: <Button>Learn More</Button>,
+};
+
+// =============================================================================
+// Default
+// =============================================================================
+
+/**
+ * Default banner with heading, description, and action button.
+ * Responsive across all breakpoints.
+ */
+export const Default: Story = {
+	render: () => (
+		<Banner
+			heading="Important Update"
+			description="Use banners to surface short, important updates or a single key action without disrupting the main page content."
+			action={<Button>Learn More</Button>}
+		/>
+	),
+};
+
+/**
+ * Banner without an action button.
+ */
+export const WithoutAction: Story = {
+	render: () => (
+		<Banner
+			heading="Announcement"
+			description="Use banners to surface short, important updates or a single key action without disrupting the main page content."
+		/>
+	),
+};
+
+// =============================================================================
+// Responsive Variants
+// =============================================================================
+
+/**
+ * Desktop viewport (lg breakpoint, 1440px)
+ * Horizontal layout with 72px padding
+ */
+export const Desktop: Story = {
+	render: () => (
+		<Banner
+			heading="Desktop Banner"
+			description="Use banners to surface short, important updates or a single key action without disrupting the main page content."
+			action={<Button>Learn More</Button>}
+		/>
+	),
+	globals: {
+		viewport: { value: "lg", isRotated: false },
+	},
+};
+
+/**
+ * Tablet viewport (md breakpoint, 768px)
+ * Horizontal layout with 56px padding
+ */
+export const Tablet: Story = {
+	render: () => (
+		<Banner
+			heading="Tablet Banner"
+			description="Use banners to surface short, important updates or a single key action without disrupting the main page content."
+			action={<Button>Learn More</Button>}
+		/>
+	),
+	globals: {
+		viewport: { value: "md", isRotated: false },
+	},
+};
+
+/**
+ * Mobile viewport (sm breakpoint, 320px)
+ * Stacked layout with 20x32px padding
+ */
+export const Mobile: Story = {
+	render: () => (
+		<Banner
+			heading="Mobile Banner"
+			description="Use banners to surface short, important updates or a single key action without disruption."
+			action={<Button size="sm">Learn More</Button>}
+		/>
+	),
+	globals: {
+		viewport: { value: "sm", isRotated: false },
+	},
+};
+
+// =============================================================================
+// Examples
+// =============================================================================
+
+/**
+ * Banner with a longer description that wraps
+ */
+export const LongDescription: Story = {
+	render: () => (
+		<Banner
+			heading="New Features Available"
+			description="We've made significant improvements to our platform including enhanced security features, faster load times, improved accessibility across all components, and a redesigned dashboard experience. Check out the documentation for more details on how to take advantage of these updates."
+			action={<Button>View Documentation</Button>}
+		/>
+	),
+};
+
+/**
+ * Banner with custom styling
+ */
+export const CustomBackground: Story = {
+	render: () => (
+		<Banner
+			heading="Custom Styled Banner"
+			description="This banner has a custom background color applied via className."
+			action={<Button variant="ivory">Action</Button>}
+			className="bg-gray-1000 text-gray-50 [&_h2]:text-gray-50 [&_p]:text-gray-200"
+		/>
+	),
+};

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

@@ -0,0 +1,185 @@
+import { describe, expect, test } from "vitest";
+import { page } from "vitest/browser";
+import { render } from "vitest-browser-react";
+import { Banner } from "./banner";
+
+describe("Banner", () => {
+	describe("Accessibility", () => {
+		test("renders as section landmark", async () => {
+			render(
+				<Banner
+					heading="Test Banner"
+					description="Test description"
+					data-testid="banner"
+				/>,
+			);
+
+			const banner = page.getByTestId("banner");
+			await expect.element(banner).toBeInTheDocument();
+		});
+
+		test("heading renders as h2", async () => {
+			render(
+				<Banner heading="Banner Heading" description="Test description" />,
+			);
+
+			await expect
+				.element(
+					page.getByRole("heading", { level: 2, name: "Banner Heading" }),
+				)
+				.toBeInTheDocument();
+		});
+
+		test("description is accessible to screen readers", async () => {
+			render(
+				<Banner heading="Test" description="Accessible description text" />,
+			);
+
+			await expect
+				.element(page.getByText("Accessible description text"))
+				.toBeInTheDocument();
+		});
+	});
+
+	describe("Props", () => {
+		test("renders with required heading and description props", async () => {
+			render(
+				<Banner
+					heading="Required Heading"
+					description="Required description"
+				/>,
+			);
+
+			await expect
+				.element(page.getByText("Required Heading"))
+				.toBeInTheDocument();
+			await expect
+				.element(page.getByText("Required description"))
+				.toBeInTheDocument();
+		});
+
+		test("renders action when provided", async () => {
+			render(
+				<Banner
+					heading="With Action"
+					description="Description"
+					action={<button type="button">Click Me</button>}
+				/>,
+			);
+
+			await expect
+				.element(page.getByRole("button", { name: "Click Me" }))
+				.toBeInTheDocument();
+		});
+
+		test("does not render action slot when not provided", async () => {
+			render(
+				<Banner
+					heading="Without Action"
+					description="Description"
+					data-testid="banner"
+				/>,
+			);
+
+			const banner = page.getByTestId("banner");
+			await expect.element(banner).toBeInTheDocument();
+			// Only heading and description should be present
+			await expect.element(page.getByRole("button")).not.toBeInTheDocument();
+		});
+
+		test("supports custom className", async () => {
+			render(
+				<Banner
+					heading="Custom"
+					description="Description"
+					className="custom-class"
+					data-testid="banner"
+				/>,
+			);
+
+			const banner = page.getByTestId("banner");
+			await expect.element(banner).toHaveClass(/custom-class/);
+		});
+
+		test("spreads additional props to section element", async () => {
+			render(
+				<Banner
+					heading="Props Test"
+					description="Description"
+					data-testid="banner"
+					aria-label="Banner section"
+				/>,
+			);
+
+			const banner = page.getByTestId("banner");
+			await expect
+				.element(banner)
+				.toHaveAttribute("aria-label", "Banner section");
+		});
+	});
+
+	describe("Styling", () => {
+		test("applies default background color", async () => {
+			render(
+				<Banner
+					heading="Default"
+					description="Description"
+					data-testid="banner"
+				/>,
+			);
+
+			const banner = page.getByTestId("banner");
+			await expect.element(banner).toHaveClass(/bg-gray-50/);
+		});
+
+		test("applies col-full for grid alignment", async () => {
+			render(
+				<Banner
+					heading="Grid Test"
+					description="Description"
+					data-testid="banner"
+				/>,
+			);
+
+			const banner = page.getByTestId("banner");
+			await expect.element(banner).toHaveClass(/col-full/);
+		});
+
+		test("applies responsive padding classes", async () => {
+			render(
+				<Banner
+					heading="Responsive"
+					description="Description"
+					data-testid="banner"
+				/>,
+			);
+
+			const banner = page.getByTestId("banner");
+			// Mobile padding
+			await expect.element(banner).toHaveClass(/px-spacing-20/);
+			await expect.element(banner).toHaveClass(/py-spacing-32/);
+		});
+	});
+
+	describe("Content", () => {
+		test("heading has correct text color", async () => {
+			render(<Banner heading="Styled Heading" description="Description" />);
+
+			const heading = page.getByRole("heading", { level: 2 });
+			await expect.element(heading).toHaveClass(/text-gray-900/);
+		});
+
+		test("description has correct text color", async () => {
+			render(
+				<Banner
+					heading="Test"
+					description="Styled description"
+					data-testid="banner"
+				/>,
+			);
+
+			const description = page.getByText("Styled description");
+			await expect.element(description).toHaveClass(/text-gray-800/);
+		});
+	});
+});

package/src/components/sections/banner/banner.tsx

@@ -0,0 +1,132 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+/**
+ * Banner component based on Figma BaseKit / Banners
+ *
+ * Used to surface short, important updates or a single key action
+ * without disrupting the main page content.
+ *
+ * Responsive behavior using 24-column grid:
+ * - Mobile (sm): Stacked layout, 20px horizontal / 32px vertical padding
+ * - Tablet (md): Horizontal layout, 56px padding
+ * - Desktop (lg): Horizontal layout, 72px padding
+ *
+ * Must be placed inside a `grid-container`. Uses `col-full` to span all columns.
+ */
+const bannerVariants = cva(
+	[
+		// Grid alignment - full width
+		"col-full",
+		// Responsive padding: mobile -> tablet -> desktop
+		"px-spacing-20 py-spacing-32",
+		"md:p-spacing-56",
+		"lg:px-spacing-72 lg:pb-spacing-72 lg:pt-0",
+	],
+	{
+		variants: {
+			theme: {
+				light: "bg-gray-50",
+				dark: "bg-gray-1200",
+			},
+		},
+		defaultVariants: {
+			theme: "light",
+		},
+	},
+);
+
+export interface BannerProps
+	extends React.HTMLAttributes<HTMLElement>,
+		VariantProps<typeof bannerVariants> {
+	/**
+	 * The heading text displayed in the banner
+	 */
+	heading: string;
+	/**
+	 * The description text displayed below the heading
+	 */
+	description: string;
+	/**
+	 * Optional action element (typically a Button component)
+	 */
+	action?: React.ReactNode;
+}
+
+/**
+ * Banner component for surfacing important updates or CTAs.
+ *
+ * Uses the 24-column grid system - must be placed inside a `grid-container`.
+ * Spans full width with `col-full`.
+ *
+ * Responsive across breakpoints:
+ * - Mobile: Stacked layout with smaller padding
+ * - Tablet: Horizontal layout with medium padding
+ * - Desktop: Horizontal layout with larger padding
+ *
+ * @example
+ * ```tsx
+ * <div className="grid-container">
+ *   <Banner
+ *     heading="Important Update"
+ *     description="Check out our new features."
+ *     action={<Button>Learn More</Button>}
+ *   />
+ * </div>
+ *
+ * // Dark theme
+ * <Banner
+ *   theme="dark"
+ *   heading="Still Have Questions?"
+ *   description="Contact us at support@example.com"
+ *   action={<Button variant="secondary">Email Us</Button>}
+ * />
+ * ```
+ */
+const Banner = React.forwardRef<HTMLElement, BannerProps>(
+	({ className, theme, heading, description, action, ...props }, ref) => {
+		const isDark = theme === "dark";
+
+		return (
+			<section
+				ref={ref}
+				className={cn(bannerVariants({ theme }), className)}
+				{...props}
+			>
+				{/* Inner container with border-top for dark theme */}
+				<div
+					className={cn(
+						"flex flex-col md:flex-row gap-spacing-20 items-start md:items-center md:justify-between",
+						isDark && "border-t border-gray-700 py-spacing-36",
+					)}
+				>
+					{/* Copy section */}
+					<div className="flex flex-col gap-spacing-6 items-start">
+						<h2
+							className={cn(
+								"typography-subheading-small",
+								isDark ? "text-gray-100" : "text-gray-900",
+							)}
+						>
+							{heading}
+						</h2>
+						<p
+							className={cn(
+								"typography-body-small",
+								isDark ? "text-gray-500" : "text-gray-800",
+							)}
+						>
+							{description}
+						</p>
+					</div>
+					{/* Action slot */}
+					{action}
+				</div>
+			</section>
+		);
+	},
+);
+Banner.displayName = "Banner";
+
+export { Banner, bannerVariants };

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

@@ -0,0 +1,2 @@
+export type { BannerProps } from "./banner";
+export { Banner, bannerVariants } from "./banner";