@nationaldesignstudio/react 0.0.14 → 0.0.16

package/src/components/organisms/card/card.test.tsx

@@ -0,0 +1,245 @@
+import { describe, expect, test } from "vitest";
+import { page } from "vitest/browser";
+import { render } from "vitest-browser-react";
+import { Button } from "../../atoms/button";
+import {
+	Card,
+	CardActions,
+	CardBody,
+	CardContent,
+	CardDescription,
+	CardEyebrow,
+	CardImage,
+	CardTitle,
+} from "./card";
+
+describe("Card", () => {
+	describe("Accessibility", () => {
+		test("CardTitle renders as h3 heading by default", async () => {
+			render(
+				<Card>
+					<CardContent>
+						<CardBody>
+							<CardTitle>Test Title</CardTitle>
+						</CardBody>
+					</CardContent>
+				</Card>,
+			);
+
+			await expect
+				.element(page.getByRole("heading", { level: 3, name: "Test Title" }))
+				.toBeInTheDocument();
+		});
+
+		test("CardTitle supports as prop to change heading level", async () => {
+			render(
+				<Card>
+					<CardContent>
+						<CardBody>
+							<CardTitle as="h2">H2 Title</CardTitle>
+						</CardBody>
+					</CardContent>
+				</Card>,
+			);
+
+			await expect
+				.element(page.getByRole("heading", { level: 2, name: "H2 Title" }))
+				.toBeInTheDocument();
+		});
+
+		test("CardImage renders img with alt text when src provided", async () => {
+			render(
+				<Card>
+					<CardImage
+						src="https://example.com/image.jpg"
+						alt="Test image description"
+					/>
+					<CardContent>
+						<CardBody>
+							<CardTitle>Card with Image</CardTitle>
+						</CardBody>
+					</CardContent>
+				</Card>,
+			);
+
+			await expect
+				.element(page.getByRole("img", { name: "Test image description" }))
+				.toBeInTheDocument();
+		});
+
+		test("CardImage does not render img when no src provided", async () => {
+			render(
+				<Card>
+					<CardImage />
+					<CardContent>
+						<CardBody>
+							<CardTitle>Card without Image Source</CardTitle>
+						</CardBody>
+					</CardContent>
+				</Card>,
+			);
+
+			// Should not have an img element
+			const images = page.getByRole("img");
+			await expect.element(images).not.toBeInTheDocument();
+		});
+
+		test("buttons in CardActions are accessible", async () => {
+			render(
+				<Card>
+					<CardContent>
+						<CardBody>
+							<CardTitle>Card with Actions</CardTitle>
+						</CardBody>
+						<CardActions>
+							<Button>Primary Action</Button>
+							<Button variant="charcoalOutline">Secondary Action</Button>
+						</CardActions>
+					</CardContent>
+				</Card>,
+			);
+
+			await expect
+				.element(page.getByRole("button", { name: "Primary Action" }))
+				.toBeInTheDocument();
+			await expect
+				.element(page.getByRole("button", { name: "Secondary Action" }))
+				.toBeInTheDocument();
+		});
+
+		test("Card structure is semantically correct", async () => {
+			render(
+				<Card data-testid="card">
+					<CardContent>
+						<CardBody>
+							<CardEyebrow>Eyebrow Text</CardEyebrow>
+							<CardTitle>Card Title</CardTitle>
+							<CardDescription>Card description text</CardDescription>
+						</CardBody>
+					</CardContent>
+				</Card>,
+			);
+
+			// Verify all text content is present and readable
+			await expect.element(page.getByText("Eyebrow Text")).toBeInTheDocument();
+			await expect.element(page.getByText("Card Title")).toBeInTheDocument();
+			await expect
+				.element(page.getByText("Card description text"))
+				.toBeInTheDocument();
+		});
+	});
+
+	describe("Layout Variants", () => {
+		test("vertical layout applies correct classes", async () => {
+			render(
+				<Card layout="vertical" data-testid="card">
+					<CardContent>
+						<CardBody>
+							<CardTitle>Vertical Card</CardTitle>
+						</CardBody>
+					</CardContent>
+				</Card>,
+			);
+
+			const card = page.getByTestId("card");
+			await expect.element(card).toHaveClass(/flex-col/);
+		});
+
+		test("horizontal layout applies correct classes", async () => {
+			render(
+				<Card layout="horizontal" data-testid="card">
+					<CardContent>
+						<CardBody>
+							<CardTitle>Horizontal Card</CardTitle>
+						</CardBody>
+					</CardContent>
+				</Card>,
+			);
+
+			const card = page.getByTestId("card");
+			await expect.element(card).toHaveClass(/flex-row/);
+		});
+
+		test("default layout is vertical", async () => {
+			render(
+				<Card data-testid="card">
+					<CardContent>
+						<CardBody>
+							<CardTitle>Default Card</CardTitle>
+						</CardBody>
+					</CardContent>
+				</Card>,
+			);
+
+			const card = page.getByTestId("card");
+			await expect.element(card).toHaveClass(/flex-col/);
+		});
+	});
+
+	describe("Component Composition", () => {
+		test("renders complete card with all sub-components", async () => {
+			render(
+				<Card>
+					<CardImage src="https://example.com/test.jpg" alt="Test" />
+					<CardContent>
+						<CardBody>
+							<CardEyebrow>Category</CardEyebrow>
+							<CardTitle>Full Card Example</CardTitle>
+							<CardDescription>
+								This is a complete card with all components.
+							</CardDescription>
+						</CardBody>
+						<CardActions>
+							<Button>Action</Button>
+						</CardActions>
+					</CardContent>
+				</Card>,
+			);
+
+			await expect
+				.element(page.getByRole("img", { name: "Test" }))
+				.toBeInTheDocument();
+			await expect.element(page.getByText("Category")).toBeInTheDocument();
+			await expect
+				.element(page.getByRole("heading", { name: "Full Card Example" }))
+				.toBeInTheDocument();
+			await expect
+				.element(page.getByText("This is a complete card with all components."))
+				.toBeInTheDocument();
+			await expect
+				.element(page.getByRole("button", { name: "Action" }))
+				.toBeInTheDocument();
+		});
+
+		test("renders minimal card with only required components", async () => {
+			render(
+				<Card>
+					<CardContent>
+						<CardBody>
+							<CardTitle>Minimal</CardTitle>
+						</CardBody>
+					</CardContent>
+				</Card>,
+			);
+
+			await expect
+				.element(page.getByRole("heading", { name: "Minimal" }))
+				.toBeInTheDocument();
+		});
+
+		test("supports custom className on Card", async () => {
+			render(
+				<Card className="custom-class" data-testid="card">
+					<CardContent>
+						<CardBody>
+							<CardTitle>Custom Card</CardTitle>
+						</CardBody>
+					</CardContent>
+				</Card>,
+			);
+
+			const card = page.getByTestId("card");
+			await expect.element(card).toHaveClass(/custom-class/);
+		});
+	});
+});

package/src/components/organisms/card/card.tsx

@@ -0,0 +1,225 @@
+import * as React from "react";
+import { tv, type VariantProps } from "tailwind-variants";
+import { cn } from "@/lib/utils";
+
+const cardVariants = tv({
+	base: "flex overflow-hidden rounded-surface-card bg-card-background stroke-surface-card border-border-subtle border-solid",
+	variants: {
+		layout: {
+			vertical: "w-full flex-col",
+			horizontal: "w-full flex-row",
+		},
+	},
+	defaultVariants: {
+		layout: "vertical",
+	},
+});
+
+export interface CardProps
+	extends React.HTMLAttributes<HTMLDivElement>,
+		VariantProps<typeof cardVariants> {}
+
+/**
+ * Card component for displaying content in a contained, scannable format.
+ *
+ * Layouts:
+ * - vertical: Image on top, content below (default)
+ * - horizontal: Image on left, content on right
+ *
+ * Use with CardImage, CardContent, CardEyebrow, CardTitle, CardDescription, and CardActions.
+ */
+const Card = React.forwardRef<HTMLDivElement, CardProps>(
+	({ className, layout, ...props }, ref) => {
+		return (
+			<div
+				ref={ref}
+				className={cardVariants({ layout, class: className })}
+				{...props}
+			/>
+		);
+	},
+);
+Card.displayName = "Card";
+
+export interface CardImageProps extends React.HTMLAttributes<HTMLDivElement> {
+	/**
+	 * The image source URL
+	 */
+	src?: string;
+	/**
+	 * Alt text for the image
+	 */
+	alt?: string;
+}
+
+/**
+ * Card image area. For vertical layout, displays with 16:9 aspect ratio.
+ * For horizontal layout, takes up ~40% width and stretches to content height.
+ */
+const CardImage = React.forwardRef<HTMLDivElement, CardImageProps>(
+	({ className, src, alt = "", ...props }, ref) => {
+		return (
+			<div
+				ref={ref}
+				className={cn(
+					"relative shrink-0 bg-gray-500",
+					// Vertical: full width with aspect ratio
+					"aspect-video w-full",
+					// When in horizontal card (parent has flex-row), override
+					"[.flex-row>&]:aspect-auto [.flex-row>&]:w-2/5 [.flex-row>&]:self-stretch",
+					className,
+				)}
+				{...props}
+			>
+				{src && (
+					<img
+						src={src}
+						alt={alt}
+						className="absolute inset-0 size-full object-cover"
+					/>
+				)}
+			</div>
+		);
+	},
+);
+CardImage.displayName = "CardImage";
+
+export interface CardContentProps
+	extends React.HTMLAttributes<HTMLDivElement> {}
+
+/**
+ * Card content container with proper padding and spacing.
+ * Uses spatial card tokens for consistent sizing.
+ */
+const CardContent = React.forwardRef<HTMLDivElement, CardContentProps>(
+	({ className, ...props }, ref) => {
+		return (
+			<div
+				ref={ref}
+				className={cn(
+					"flex w-full flex-1 flex-col gap-spatial-card-large-gap p-spatial-card-large-padding",
+					className,
+				)}
+				{...props}
+			/>
+		);
+	},
+);
+CardContent.displayName = "CardContent";
+
+export interface CardEyebrowProps
+	extends React.HTMLAttributes<HTMLParagraphElement> {}
+
+/**
+ * Optional eyebrow text above the card title.
+ */
+const CardEyebrow = React.forwardRef<HTMLParagraphElement, CardEyebrowProps>(
+	({ className, ...props }, ref) => {
+		return (
+			<p
+				ref={ref}
+				className={cn("typography-caption-large text-gray-500", className)}
+				{...props}
+			/>
+		);
+	},
+);
+CardEyebrow.displayName = "CardEyebrow";
+
+export interface CardTitleProps
+	extends React.HTMLAttributes<HTMLHeadingElement> {
+	/**
+	 * The heading level to render (h1-h6). Defaults to h3.
+	 */
+	as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+}
+
+/**
+ * Card title/heading. Use the `as` prop to change the heading level.
+ */
+const CardTitle = React.forwardRef<HTMLHeadingElement, CardTitleProps>(
+	({ className, as: Component = "h3", ...props }, ref) => {
+		return (
+			<Component
+				ref={ref}
+				className={cn("typography-subheading-small text-gray-1100", className)}
+				{...props}
+			/>
+		);
+	},
+);
+CardTitle.displayName = "CardTitle";
+
+export interface CardDescriptionProps
+	extends React.HTMLAttributes<HTMLParagraphElement> {}
+
+/**
+ * Card body/description text.
+ */
+const CardDescription = React.forwardRef<
+	HTMLParagraphElement,
+	CardDescriptionProps
+>(({ className, ...props }, ref) => {
+	return (
+		<p
+			ref={ref}
+			className={cn("typography-body-small text-gray-800", className)}
+			{...props}
+		/>
+	);
+});
+CardDescription.displayName = "CardDescription";
+
+export interface CardBodyProps extends React.HTMLAttributes<HTMLDivElement> {}
+
+/**
+ * Container for card text content (eyebrow, title, description).
+ * Uses spatial card tokens for consistent sizing.
+ */
+const CardBody = React.forwardRef<HTMLDivElement, CardBodyProps>(
+	({ className, ...props }, ref) => {
+		return (
+			<div
+				ref={ref}
+				className={cn(
+					"flex w-full flex-col gap-spatial-card-small-gap",
+					className,
+				)}
+				{...props}
+			/>
+		);
+	},
+);
+CardBody.displayName = "CardBody";
+
+export interface CardActionsProps
+	extends React.HTMLAttributes<HTMLDivElement> {}
+
+/**
+ * Container for card action buttons.
+ * Uses primitive spacing tokens.
+ */
+const CardActions = React.forwardRef<HTMLDivElement, CardActionsProps>(
+	({ className, ...props }, ref) => {
+		return (
+			<div
+				ref={ref}
+				className={cn("flex gap-spacing-12", className)}
+				{...props}
+			/>
+		);
+	},
+);
+CardActions.displayName = "CardActions";
+
+export {
+	Card,
+	cardVariants,
+	CardImage,
+	CardContent,
+	CardEyebrow,
+	CardTitle,
+	CardDescription,
+	CardBody,
+	CardActions,
+};

package/src/components/organisms/card/card.visual.test.tsx

@@ -0,0 +1,197 @@
+import { render } from "@testing-library/react";
+import { describe, expect, test } from "vitest";
+import { page } from "vitest/browser";
+import { Button } from "../../atoms/button";
+import {
+	Card,
+	CardActions,
+	CardBody,
+	CardContent,
+	CardDescription,
+	CardEyebrow,
+	CardImage,
+	CardTitle,
+} from "./card";
+
+describe("Card Visual Regression", () => {
+	test("default vertical layout renders correctly", async () => {
+		render(
+			<div
+				style={{ width: "418px", backgroundColor: "#1a1a1a", padding: "20px" }}
+			>
+				<Card data-testid="card">
+					<CardImage />
+					<CardContent>
+						<CardBody>
+							<CardEyebrow>Optional Eyebrow</CardEyebrow>
+							<div className="flex flex-col gap-[6px]">
+								<CardTitle>Card Title</CardTitle>
+								<CardDescription>
+									Use cards when citizens need to scan items at a glance.
+								</CardDescription>
+							</div>
+						</CardBody>
+						<CardActions>
+							<Button size="default" variant="charcoal">
+								Primary
+							</Button>
+							<Button size="default" variant="charcoalOutline">
+								Secondary
+							</Button>
+						</CardActions>
+					</CardContent>
+				</Card>
+			</div>,
+		);
+
+		await expect(page.getByTestId("card")).toMatchScreenshot(
+			"card-default-vertical",
+		);
+	});
+
+	test("horizontal layout renders correctly", async () => {
+		render(
+			<div
+				style={{ width: "700px", backgroundColor: "#1a1a1a", padding: "20px" }}
+			>
+				<Card layout="horizontal" data-testid="card">
+					<CardImage />
+					<CardContent>
+						<CardBody>
+							<CardEyebrow>Eyebrow</CardEyebrow>
+							<div className="flex flex-col gap-[9px]">
+								<CardTitle>
+									Cards can support multi line headings easily.
+								</CardTitle>
+								<CardDescription>
+									Use cards when citizens need to scan items at a glance.
+								</CardDescription>
+							</div>
+						</CardBody>
+						<CardActions>
+							<Button size="sm" variant="charcoal">
+								Primary
+							</Button>
+							<Button size="sm" variant="charcoalOutline">
+								Secondary
+							</Button>
+						</CardActions>
+					</CardContent>
+				</Card>
+			</div>,
+		);
+
+		await expect(page.getByTestId("card")).toMatchScreenshot("card-horizontal");
+	});
+
+	test("without image renders correctly", async () => {
+		render(
+			<div
+				style={{ width: "418px", backgroundColor: "#1a1a1a", padding: "20px" }}
+			>
+				<Card data-testid="card">
+					<CardContent>
+						<CardBody>
+							<CardEyebrow>Category</CardEyebrow>
+							<div className="flex flex-col gap-[6px]">
+								<CardTitle>Card Without Image</CardTitle>
+								<CardDescription>
+									Cards can be used without images for text-focused content.
+								</CardDescription>
+							</div>
+						</CardBody>
+						<CardActions>
+							<Button size="default" variant="charcoal">
+								Learn More
+							</Button>
+						</CardActions>
+					</CardContent>
+				</Card>
+			</div>,
+		);
+
+		await expect(page.getByTestId("card")).toMatchScreenshot(
+			"card-without-image",
+		);
+	});
+
+	test("without eyebrow renders correctly", async () => {
+		render(
+			<div
+				style={{ width: "418px", backgroundColor: "#1a1a1a", padding: "20px" }}
+			>
+				<Card data-testid="card">
+					<CardImage />
+					<CardContent>
+						<CardBody>
+							<div className="flex flex-col gap-[6px]">
+								<CardTitle>Card Title</CardTitle>
+								<CardDescription>
+									The eyebrow is optional and can be omitted when not needed.
+								</CardDescription>
+							</div>
+						</CardBody>
+						<CardActions>
+							<Button size="default" variant="charcoal">
+								Primary
+							</Button>
+						</CardActions>
+					</CardContent>
+				</Card>
+			</div>,
+		);
+
+		await expect(page.getByTestId("card")).toMatchScreenshot(
+			"card-without-eyebrow",
+		);
+	});
+
+	test("without actions renders correctly", async () => {
+		render(
+			<div
+				style={{ width: "418px", backgroundColor: "#1a1a1a", padding: "20px" }}
+			>
+				<Card data-testid="card">
+					<CardImage />
+					<CardContent>
+						<CardBody>
+							<CardEyebrow>Information</CardEyebrow>
+							<div className="flex flex-col gap-[6px]">
+								<CardTitle>Informational Card</CardTitle>
+								<CardDescription>
+									Cards without actions can be used for purely informational
+									content.
+								</CardDescription>
+							</div>
+						</CardBody>
+					</CardContent>
+				</Card>
+			</div>,
+		);
+
+		await expect(page.getByTestId("card")).toMatchScreenshot(
+			"card-without-actions",
+		);
+	});
+
+	test("minimal card renders correctly", async () => {
+		render(
+			<div
+				style={{ width: "418px", backgroundColor: "#1a1a1a", padding: "20px" }}
+			>
+				<Card data-testid="card">
+					<CardContent>
+						<CardBody>
+							<CardTitle>Minimal Card</CardTitle>
+							<CardDescription>
+								A minimal card with just title and description.
+							</CardDescription>
+						</CardBody>
+					</CardContent>
+				</Card>
+			</div>,
+		);
+
+		await expect(page.getByTestId("card")).toMatchScreenshot("card-minimal");
+	});
+});

package/src/components/organisms/card/index.ts

@@ -0,0 +1,19 @@
+export {
+	Card,
+	CardActions,
+	type CardActionsProps,
+	CardBody,
+	type CardBodyProps,
+	CardContent,
+	type CardContentProps,
+	CardDescription,
+	type CardDescriptionProps,
+	CardEyebrow,
+	type CardEyebrowProps,
+	CardImage,
+	type CardImageProps,
+	type CardProps,
+	CardTitle,
+	type CardTitleProps,
+	cardVariants,
+} from "./card";