@nationaldesignstudio/react 0.0.15 → 0.0.16

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

@@ -0,0 +1,144 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Prose, ProseSection } from ".";
+
+const meta: Meta<typeof Prose> = {
+	title: "Sections/Prose",
+	component: Prose,
+	parameters: {
+		layout: "centered",
+	},
+} as Meta<typeof Prose>;
+
+export default meta;
+type Story = StoryObj<typeof Prose>;
+
+const sampleIntro =
+	"On the modern web, typography is not decoration; it's the cognitive interface. Before a user understands your product, policy, or program, they're unconsciously reading the structure of your type: the hierarchy of headings, the discipline of your spacing, the confidence or hesitation in your line lengths.";
+
+const sampleParagraph1 =
+	"Style here isn't about clever fonts, it's about creating a system of visual cues that makes thinking easier. A consistent scale, clear contrast between roles, and careful use of weight and size become a kind of mental exoskeleton for the reader. Done well, typography lowers the friction of understanding to the point where attention can be spent on the content itself rather than on decoding the layout.";
+
+const sampleParagraph2 =
+	'Rhythm is where that structure turns into a voice. Online, people experience your text as a sequence of micro-moments: the way a headline sits in space, how paragraphs breathe, where the eye can rest. Tight, compressed leading and dense blocks say, "this is serious, pay attention." Generous white space and measured line lengths say, "you have room to think." Over time, those choices form a recognizable persona, just as surely as a writing style does. When the rhythm is intentional, your site speaks with a calm, authoritative cadence that users begin to trust. When it\'s sloppy or inconsistent, the voice fractures, and so does the sense that there\'s a clear, competent mind behind the interface.';
+
+// =============================================================================
+// Default
+// =============================================================================
+
+export const Default: Story = {
+	render: () => (
+		<Prose>
+			<ProseSection heading="Headline - Medium" as="h2">
+				<p>{sampleIntro}</p>
+			</ProseSection>
+			<ProseSection heading="Headline - Small" as="h3">
+				<p>{sampleParagraph1}</p>
+				<p>{sampleParagraph2}</p>
+			</ProseSection>
+		</Prose>
+	),
+};
+
+// =============================================================================
+// Responsive Variants
+// =============================================================================
+
+export const Desktop: Story = {
+	render: () => (
+		<Prose>
+			<ProseSection heading="Headline - Medium" as="h2">
+				<p>{sampleIntro}</p>
+			</ProseSection>
+			<ProseSection heading="Headline - Small" as="h3">
+				<p>{sampleParagraph1}</p>
+				<p>{sampleParagraph2}</p>
+			</ProseSection>
+		</Prose>
+	),
+	globals: {
+		viewport: { value: "lg", isRotated: false },
+	},
+};
+
+export const Tablet: Story = {
+	render: () => (
+		<Prose>
+			<ProseSection heading="Headline - Medium" as="h2">
+				<p>{sampleIntro}</p>
+			</ProseSection>
+			<ProseSection heading="Headline - Small" as="h3">
+				<p>{sampleParagraph1}</p>
+				<p>{sampleParagraph2}</p>
+			</ProseSection>
+		</Prose>
+	),
+	globals: {
+		viewport: { value: "md", isRotated: false },
+	},
+};
+
+export const Mobile: Story = {
+	render: () => (
+		<Prose>
+			<ProseSection heading="Headline - Medium" as="h2">
+				<p>{sampleIntro}</p>
+			</ProseSection>
+			<ProseSection heading="Headline - Small" as="h3">
+				<p>{sampleParagraph1}</p>
+				<p>{sampleParagraph2}</p>
+			</ProseSection>
+		</Prose>
+	),
+	globals: {
+		viewport: { value: "sm", isRotated: false },
+	},
+};
+
+// =============================================================================
+// Playground
+// =============================================================================
+
+export const Playground: Story = {
+	render: (args) => (
+		<Prose {...args}>
+			<ProseSection heading="Main Heading" as="h2">
+				<p>{sampleIntro}</p>
+			</ProseSection>
+			<ProseSection heading="Subheading" as="h3">
+				<p>{sampleParagraph1}</p>
+				<p>{sampleParagraph2}</p>
+			</ProseSection>
+		</Prose>
+	),
+};
+
+// =============================================================================
+// Examples
+// =============================================================================
+
+export const SingleSection: Story = {
+	render: () => (
+		<Prose>
+			<ProseSection heading="About Our Mission" as="h2">
+				<p>{sampleIntro}</p>
+				<p>{sampleParagraph1}</p>
+			</ProseSection>
+		</Prose>
+	),
+};
+
+export const MultipleSections: Story = {
+	render: () => (
+		<Prose>
+			<ProseSection heading="Introduction" as="h2">
+				<p>{sampleIntro}</p>
+			</ProseSection>
+			<ProseSection heading="The Importance of Style" as="h3">
+				<p>{sampleParagraph1}</p>
+			</ProseSection>
+			<ProseSection heading="Finding Your Rhythm" as="h3">
+				<p>{sampleParagraph2}</p>
+			</ProseSection>
+		</Prose>
+	),
+};

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

@@ -0,0 +1,178 @@
+import { describe, expect, test } from "vitest";
+import { page } from "vitest/browser";
+import { render } from "vitest-browser-react";
+import { Prose, ProseSection } from "./prose";
+
+describe("Prose", () => {
+	describe("Accessibility", () => {
+		test("ProseSection renders as section landmark", async () => {
+			render(
+				<Prose>
+					<ProseSection heading="Test Section" data-testid="section">
+						<p>Content</p>
+					</ProseSection>
+				</Prose>,
+			);
+
+			const section = page.getByTestId("section");
+			await expect.element(section).toBeInTheDocument();
+		});
+
+		test("ProseSection heading renders as h2 by default", async () => {
+			render(
+				<Prose>
+					<ProseSection heading="Default Heading">
+						<p>Content</p>
+					</ProseSection>
+				</Prose>,
+			);
+
+			await expect
+				.element(
+					page.getByRole("heading", { level: 2, name: "Default Heading" }),
+				)
+				.toBeInTheDocument();
+		});
+
+		test("ProseSection heading renders as h3 when specified", async () => {
+			render(
+				<Prose>
+					<ProseSection heading="H3 Heading" as="h3">
+						<p>Content</p>
+					</ProseSection>
+				</Prose>,
+			);
+
+			await expect
+				.element(page.getByRole("heading", { level: 3, name: "H3 Heading" }))
+				.toBeInTheDocument();
+		});
+
+		test("prose content is readable", async () => {
+			render(
+				<Prose>
+					<ProseSection heading="Readable Content">
+						<p>This is some readable body text.</p>
+					</ProseSection>
+				</Prose>,
+			);
+
+			await expect
+				.element(page.getByText("This is some readable body text."))
+				.toBeInTheDocument();
+		});
+	});
+
+	describe("Props", () => {
+		test("Prose renders children", async () => {
+			render(
+				<Prose data-testid="prose">
+					<ProseSection heading="Child Section">
+						<p>Child content</p>
+					</ProseSection>
+				</Prose>,
+			);
+
+			await expect.element(page.getByText("Child content")).toBeInTheDocument();
+		});
+
+		test("Prose supports custom className", async () => {
+			render(
+				<Prose className="custom-prose" data-testid="prose">
+					<ProseSection heading="Test">
+						<p>Content</p>
+					</ProseSection>
+				</Prose>,
+			);
+
+			const prose = page.getByTestId("prose");
+			await expect.element(prose).toHaveClass(/custom-prose/);
+		});
+
+		test("ProseSection supports custom className", async () => {
+			render(
+				<Prose>
+					<ProseSection
+						heading="Test"
+						className="custom-section"
+						data-testid="section"
+					>
+						<p>Content</p>
+					</ProseSection>
+				</Prose>,
+			);
+
+			const section = page.getByTestId("section");
+			await expect.element(section).toHaveClass(/custom-section/);
+		});
+	});
+
+	describe("Styling", () => {
+		test("Prose has max-width constraint", async () => {
+			render(
+				<Prose data-testid="prose">
+					<ProseSection heading="Test">
+						<p>Content</p>
+					</ProseSection>
+				</Prose>,
+			);
+
+			const prose = page.getByTestId("prose");
+			await expect.element(prose).toHaveClass(/max-w-\[700px\]/);
+		});
+
+		test("h2 heading has correct typography class", async () => {
+			render(
+				<Prose>
+					<ProseSection heading="H2 Test">
+						<p>Content</p>
+					</ProseSection>
+				</Prose>,
+			);
+
+			const heading = page.getByRole("heading", { name: "H2 Test" });
+			await expect.element(heading).toHaveClass(/typography-headline-medium/);
+		});
+
+		test("h3 heading has correct typography class", async () => {
+			render(
+				<Prose>
+					<ProseSection heading="H3 Test" as="h3">
+						<p>Content</p>
+					</ProseSection>
+				</Prose>,
+			);
+
+			const heading = page.getByRole("heading", { name: "H3 Test" });
+			await expect.element(heading).toHaveClass(/typography-headline-small/);
+		});
+	});
+
+	describe("Composition", () => {
+		test("renders multiple sections", async () => {
+			render(
+				<Prose>
+					<ProseSection heading="First">
+						<p>First content</p>
+					</ProseSection>
+					<ProseSection heading="Second">
+						<p>Second content</p>
+					</ProseSection>
+					<ProseSection heading="Third">
+						<p>Third content</p>
+					</ProseSection>
+				</Prose>,
+			);
+
+			await expect
+				.element(page.getByRole("heading", { name: "First" }))
+				.toBeInTheDocument();
+			await expect
+				.element(page.getByRole("heading", { name: "Second" }))
+				.toBeInTheDocument();
+			await expect
+				.element(page.getByRole("heading", { name: "Third" }))
+				.toBeInTheDocument();
+		});
+	});
+});

package/src/components/sections/prose/prose.tsx

@@ -0,0 +1,88 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+export interface ProseProps extends React.HTMLAttributes<HTMLDivElement> {
+	children: React.ReactNode;
+}
+
+/**
+ * Prose container for long-form content with proper typography and spacing.
+ *
+ * Provides responsive spacing between content blocks:
+ * - Desktop (1440px+): 96px gap
+ * - Tablet (768px+): 72px gap
+ * - Mobile: 56px gap
+ *
+ * Use with ProseSection components for proper content structure.
+ */
+const Prose = React.forwardRef<HTMLDivElement, ProseProps>(
+	({ className, children, ...props }, ref) => {
+		return (
+			<div
+				ref={ref}
+				className={cn(
+					"flex w-full max-w-[700px] flex-col overflow-hidden",
+					// Responsive gap between sections
+					"gap-spacing-56 md:gap-spacing-72 xl:gap-spacing-96",
+					className,
+				)}
+				{...props}
+			>
+				{children}
+			</div>
+		);
+	},
+);
+Prose.displayName = "Prose";
+
+export interface ProseSectionProps extends React.HTMLAttributes<HTMLElement> {
+	/**
+	 * The heading text for this section
+	 */
+	heading: string;
+	/**
+	 * The heading level to render (h2 or h3)
+	 * @default "h2"
+	 */
+	as?: "h2" | "h3";
+	children: React.ReactNode;
+}
+
+/**
+ * A section within Prose content, containing a heading and body text.
+ *
+ * Responsive typography:
+ * - h2: Uses typography-headline-medium (42px mobile → 56px tablet → 72px desktop)
+ * - h3: Uses typography-headline-small (32px mobile → 42px tablet → 56px desktop)
+ * - Body: Uses typography-body-medium (16px mobile/tablet → 18px desktop)
+ */
+const ProseSection = React.forwardRef<HTMLElement, ProseSectionProps>(
+	({ className, heading, as = "h2", children, ...props }, ref) => {
+		const Heading = as;
+		const headingClass =
+			as === "h2" ? "typography-headline-medium" : "typography-headline-small";
+
+		return (
+			<section
+				ref={ref}
+				className={cn(
+					"flex w-full flex-col",
+					// Responsive gap between heading and body
+					"gap-spacing-24 md:gap-spacing-40",
+					className,
+				)}
+				{...props}
+			>
+				<Heading className={cn(headingClass, "text-gray-900")}>
+					{heading}
+				</Heading>
+				<div className="typography-body-medium flex flex-col gap-[1em] text-gray-800 break-words">
+					{children}
+				</div>
+			</section>
+		);
+	},
+);
+ProseSection.displayName = "ProseSection";
+
+export { Prose, ProseSection };

package/src/components/sections/prose/prose.visual.test.tsx

@@ -0,0 +1,105 @@
+import { render } from "@testing-library/react";
+import { describe, expect, test } from "vitest";
+import { page } from "vitest/browser";
+import { Prose, ProseSection } from "./prose";
+
+describe("Prose Visual Regression", () => {
+	test("prose with single section renders correctly", async () => {
+		render(
+			<div
+				style={{ width: "800px", backgroundColor: "#ffffff", padding: "40px" }}
+			>
+				<Prose data-testid="prose">
+					<ProseSection heading="Section Heading">
+						<p>
+							This is a paragraph of body text that demonstrates the prose
+							component's typography and spacing. It should be easy to read and
+							properly formatted.
+						</p>
+					</ProseSection>
+				</Prose>
+			</div>,
+		);
+
+		await expect(page.getByTestId("prose")).toMatchScreenshot(
+			"prose-single-section",
+		);
+	});
+
+	test("prose with multiple sections renders correctly", async () => {
+		render(
+			<div
+				style={{ width: "800px", backgroundColor: "#ffffff", padding: "40px" }}
+			>
+				<Prose data-testid="prose">
+					<ProseSection heading="First Section">
+						<p>
+							This is the first section of content with some body text to
+							demonstrate spacing between sections.
+						</p>
+					</ProseSection>
+					<ProseSection heading="Second Section">
+						<p>
+							This is the second section showing how multiple sections stack
+							with proper gaps between them.
+						</p>
+					</ProseSection>
+				</Prose>
+			</div>,
+		);
+
+		await expect(page.getByTestId("prose")).toMatchScreenshot(
+			"prose-multiple-sections",
+		);
+	});
+
+	test("prose with h3 heading renders correctly", async () => {
+		render(
+			<div
+				style={{ width: "800px", backgroundColor: "#ffffff", padding: "40px" }}
+			>
+				<Prose data-testid="prose">
+					<ProseSection heading="H3 Heading" as="h3">
+						<p>
+							This section uses an h3 heading which has smaller typography than
+							the default h2.
+						</p>
+					</ProseSection>
+				</Prose>
+			</div>,
+		);
+
+		await expect(page.getByTestId("prose")).toMatchScreenshot(
+			"prose-h3-heading",
+		);
+	});
+
+	test("prose with multiple paragraphs renders correctly", async () => {
+		render(
+			<div
+				style={{ width: "800px", backgroundColor: "#ffffff", padding: "40px" }}
+			>
+				<Prose data-testid="prose">
+					<ProseSection heading="Long Content">
+						<p>
+							First paragraph with some content to show how multiple paragraphs
+							are spaced within a prose section.
+						</p>
+						<p>
+							Second paragraph demonstrating the gap between paragraphs in the
+							prose component.
+						</p>
+						<p>
+							Third paragraph to show consistent spacing throughout the content
+							area.
+						</p>
+					</ProseSection>
+				</Prose>
+			</div>,
+		);
+
+		await expect(page.getByTestId("prose")).toMatchScreenshot(
+			"prose-multiple-paragraphs",
+		);
+	});
+});

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

@@ -0,0 +1 @@
+export { River, type RiverProps, riverVariants } from "./river";