@nationaldesignstudio/react 0.0.15 → 0.0.16

package/src/components/sections/card-grid/card-grid.stories.tsx

@@ -0,0 +1,351 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Button } from "../../atoms/button";
+import {
+	Card,
+	CardActions,
+	CardBody,
+	CardContent,
+	CardDescription,
+	CardEyebrow,
+	CardImage,
+	CardTitle,
+} from "../../organisms/card";
+import { CardGrid } from ".";
+
+const meta: Meta<typeof CardGrid> = {
+	title: "Sections/CardGrid",
+	component: CardGrid,
+	parameters: {
+		layout: "fullscreen",
+	},
+	argTypes: {
+		variant: {
+			control: "select",
+			options: ["A", "B"],
+			description:
+				"Layout variant: A = 3 cols on desktop, B = 2 cols on desktop",
+		},
+		title: {
+			control: "text",
+			description: "The title text displayed above the cards",
+		},
+	},
+} as Meta<typeof CardGrid>;
+
+export default meta;
+type Story = StoryObj<typeof CardGrid>;
+
+const SampleCard = ({
+	title,
+	description,
+}: {
+	title: string;
+	description: string;
+}) => (
+	<Card>
+		<CardImage src="https://images.unsplash.com/photo-1551434678-e076c223a692?w=800&h=450&fit=crop" />
+		<CardContent>
+			<CardBody>
+				<CardEyebrow>Category</CardEyebrow>
+				<CardTitle>{title}</CardTitle>
+				<CardDescription>{description}</CardDescription>
+			</CardBody>
+			<CardActions>
+				<Button size="sm">Learn More</Button>
+			</CardActions>
+		</CardContent>
+	</Card>
+);
+
+const PlaceholderCard = ({
+	title,
+	description,
+}: {
+	title: string;
+	description: string;
+}) => (
+	<Card>
+		<CardImage>
+			<div className="absolute inset-0 bg-gray-200 flex items-center justify-center">
+				<span className="text-gray-500 typography-body-small">
+					Image Placeholder
+				</span>
+			</div>
+		</CardImage>
+		<CardContent>
+			<CardBody>
+				<CardEyebrow>Category</CardEyebrow>
+				<CardTitle>{title}</CardTitle>
+				<CardDescription>{description}</CardDescription>
+			</CardBody>
+			<CardActions>
+				<Button size="sm">Learn More</Button>
+			</CardActions>
+		</CardContent>
+	</Card>
+);
+
+const sampleCards = [
+	<PlaceholderCard
+		key="1"
+		title="First Card"
+		description="This is a sample card description that provides context about the content."
+	/>,
+	<PlaceholderCard
+		key="2"
+		title="Second Card"
+		description="Another card with a brief description explaining its purpose."
+	/>,
+	<PlaceholderCard
+		key="3"
+		title="Third Card"
+		description="A third card to demonstrate the grid layout behavior."
+	/>,
+	<PlaceholderCard
+		key="4"
+		title="Fourth Card"
+		description="The final card in this example grid layout."
+	/>,
+];
+
+export const Playground: Story = {
+	render: (args) => <CardGrid {...args} />,
+};
+Playground.args = {
+	variant: "A",
+	title: "Featured Content",
+	cards: sampleCards,
+};
+
+// =============================================================================
+// Variants
+// =============================================================================
+
+/**
+ * Variant A: 3 columns on desktop, 2 on tablet, 1 on mobile
+ */
+export const VariantA: Story = {
+	render: () => (
+		<CardGrid
+			variant="A"
+			title="Our Services"
+			cards={sampleCards.slice(0, 4)}
+		/>
+	),
+};
+
+/**
+ * Variant B: 2 columns on desktop/tablet, 1 on mobile
+ */
+export const VariantB: Story = {
+	render: () => (
+		<CardGrid
+			variant="B"
+			title="Featured Articles"
+			cards={sampleCards.slice(0, 4)}
+		/>
+	),
+};
+
+export const VariantBDesktop: Story = {
+	render: () => (
+		<CardGrid
+			variant="B"
+			title="Desktop View (Variant B)"
+			cards={[
+				<PlaceholderCard
+					key="1"
+					title="Card One"
+					description="Variant B displays 2 columns on desktop instead of 3."
+				/>,
+				<PlaceholderCard
+					key="2"
+					title="Card Two"
+					description="This is useful for larger card layouts or featured content."
+				/>,
+			]}
+		/>
+	),
+	globals: {
+		viewport: { value: "lg", isRotated: false },
+	},
+};
+
+// =============================================================================
+// Responsive Variants
+// =============================================================================
+
+export const VariantADesktop: Story = {
+	render: () => (
+		<CardGrid
+			variant="A"
+			title="Desktop View"
+			cards={[
+				<PlaceholderCard
+					key="1"
+					title="Card One"
+					description="On desktop (lg, 1440px), cards are displayed in a 2-column grid with 12 columns each."
+				/>,
+				<PlaceholderCard
+					key="2"
+					title="Card Two"
+					description="The layout uses 128px vertical padding and 64px gap between title and cards."
+				/>,
+				<PlaceholderCard
+					key="3"
+					title="Card Three"
+					description="The layout uses 128px vertical padding and 64px gap between title and cards."
+				/>,
+			]}
+		/>
+	),
+	globals: {
+		viewport: { value: "lg", isRotated: false },
+	},
+};
+
+export const VariantATablet: Story = {
+	render: () => (
+		<CardGrid
+			variant="A"
+			title="Tablet View"
+			cards={[
+				<PlaceholderCard
+					key="1"
+					title="Card One"
+					description="On tablet (md, 768px), cards are in a 2-column layout with 56px gap from title."
+				/>,
+				<PlaceholderCard
+					key="2"
+					title="Card Two"
+					description="Cards maintain the 12/12 column split on tablet viewports."
+				/>,
+			]}
+		/>
+	),
+	globals: {
+		viewport: { value: "md", isRotated: false },
+	},
+};
+
+export const VariantAMobile: Story = {
+	render: () => (
+		<CardGrid
+			variant="A"
+			title="Mobile View"
+			cards={[
+				<PlaceholderCard
+					key="1"
+					title="Card One"
+					description="On mobile (sm, 320px), cards stack in a single column."
+				/>,
+				<PlaceholderCard
+					key="2"
+					title="Card Two"
+					description="Each card takes full width on mobile devices."
+				/>,
+			]}
+		/>
+	),
+	globals: {
+		viewport: { value: "sm", isRotated: false },
+	},
+};
+
+// =============================================================================
+// Examples
+// =============================================================================
+
+/**
+ * Two cards in grid
+ */
+export const TwoCards: Story = {
+	render: () => (
+		<CardGrid
+			variant="A"
+			title="Two Card Layout"
+			cards={sampleCards.slice(0, 2)}
+		/>
+	),
+};
+
+/**
+ * Four cards in grid (2 rows)
+ */
+export const FourCards: Story = {
+	render: () => (
+		<CardGrid variant="A" title="Four Card Layout" cards={sampleCards} />
+	),
+};
+
+/**
+ * Six cards in grid (3 rows)
+ */
+export const SixCards: Story = {
+	render: () => (
+		<CardGrid
+			variant="A"
+			title="Six Card Layout"
+			cards={[
+				...sampleCards,
+				<PlaceholderCard
+					key="5"
+					title="Fifth Card"
+					description="Additional card to show multiple rows."
+				/>,
+				<PlaceholderCard
+					key="6"
+					title="Sixth Card"
+					description="The grid handles any number of cards."
+				/>,
+			]}
+		/>
+	),
+};
+
+/**
+ * With actual images
+ */
+export const WithImages: Story = {
+	render: () => (
+		<CardGrid
+			variant="A"
+			title="Featured Resources"
+			cards={[
+				<SampleCard
+					key="1"
+					title="Getting Started Guide"
+					description="Learn the basics and get up and running quickly with our comprehensive guide."
+				/>,
+				<SampleCard
+					key="2"
+					title="Best Practices"
+					description="Discover proven strategies and techniques to maximize your results."
+				/>,
+				<SampleCard
+					key="3"
+					title="Advanced Topics"
+					description="Deep dive into advanced features and configurations."
+				/>,
+				<SampleCard
+					key="4"
+					title="Case Studies"
+					description="See how others have achieved success with real-world examples."
+				/>,
+			]}
+		/>
+	),
+};
+
+/**
+ * Odd number of cards
+ */
+export const OddNumberOfCards: Story = {
+	render: () => (
+		<CardGrid
+			variant="A"
+			title="Three Card Layout"
+			cards={sampleCards.slice(0, 3)}
+		/>
+	),
+};

package/src/components/sections/card-grid/card-grid.tsx

@@ -0,0 +1,116 @@
+import * as React from "react";
+import { tv, type VariantProps } from "tailwind-variants";
+import { cn } from "@/lib/utils";
+
+/**
+ * CardGrid component for displaying cards in a responsive grid layout
+ *
+ * Variants:
+ * - A: 3 columns on desktop, 2 on tablet, 1 on mobile
+ * - B: 2 columns on desktop/tablet, 1 on mobile
+ *
+ * Uses the 24-column grid system with grid-container as root.
+ */
+const cardGridVariants = tv({
+	// Base styles - grid-container for proper grid context - uses primitive spacing tokens
+	base: [
+		"grid-container",
+		// Small (mobile): 72px y padding
+		"py-spacing-72",
+		// Large (desktop): 128px y padding
+		"lg:py-spacing-128",
+	],
+	variants: {
+		variant: {
+			A: "",
+			B: "",
+		},
+	},
+	defaultVariants: {
+		variant: "A",
+	},
+});
+
+export interface CardGridProps
+	extends React.HTMLAttributes<HTMLElement>,
+		VariantProps<typeof cardGridVariants> {
+	/**
+	 * The title text displayed above the cards
+	 */
+	title: string;
+	/**
+	 * The card elements to display in the grid
+	 */
+	cards: React.ReactNode[];
+}
+
+/**
+ * CardGrid component for displaying cards in a responsive grid layout.
+ *
+ * Uses the 24-column grid system with grid-container as root.
+ *
+ * Layout (Variant A):
+ * - Mobile (sm): Single column, py-72
+ * - Tablet (md): 2 columns, gap-56 between title and cards, gap-y-20 between cards
+ * - Desktop (lg+): 3 columns, py-128, gap-64 between title and cards, gap-y-20 between cards
+ *
+ * Layout (Variant B):
+ * - Mobile (sm): Single column, py-72
+ * - Tablet (md): 2 columns, gap-56 between title and cards, gap-y-20 between cards
+ * - Desktop (lg+): 2 columns, py-128, gap-64 between title and cards, gap-y-20 between cards
+ *
+ * @example
+ * ```tsx
+ * <CardGrid
+ *   variant="A"
+ *   title="Featured Cards"
+ *   cards={[
+ *     <Card key="1">...</Card>,
+ *     <Card key="2">...</Card>,
+ *   ]}
+ * />
+ * ```
+ */
+const CardGrid = React.forwardRef<HTMLElement, CardGridProps>(
+	({ className, variant, title, cards, ...props }, ref) => {
+		return (
+			<section
+				ref={ref}
+				className={cardGridVariants({ variant, class: className })}
+				{...props}
+			>
+				{/* Title - col-full within grid - uses primitive spacing tokens */}
+				<h2
+					className={cn(
+						"col-full",
+						"typography-headline-small text-gray-900",
+						// Gap after title: mobile default, md: 56px, lg: 64px
+						"mb-spacing-36 md:mb-spacing-56 lg:mb-spacing-64",
+					)}
+				>
+					{title}
+				</h2>
+
+				{/* Inner grid for cards - uses primitive spacing tokens */}
+				<div
+					className={cn(
+						"col-full",
+						// Mobile: single column
+						"grid grid-cols-1 gap-spacing-20",
+						// Tablet: 2 columns
+						"md:grid-cols-2",
+						// Desktop: 3 columns for variant A, 2 columns for variant B
+						variant === "A" && "lg:grid-cols-3",
+					)}
+				>
+					{React.Children.toArray(cards).map((card) => (
+						<div key={(card as React.ReactElement).key}>{card}</div>
+					))}
+				</div>
+			</section>
+		);
+	},
+);
+CardGrid.displayName = "CardGrid";
+
+export { CardGrid, cardGridVariants };

package/src/components/sections/card-grid/index.ts

@@ -0,0 +1 @@
+export { CardGrid, type CardGridProps, cardGridVariants } from "./card-grid";