From b9d514e681781b756324151735687123918b81b4 Mon Sep 17 00:00:00 2001
From: adriancofie <38888889+adriancofie@users.noreply.github.com>
Date: Tue, 31 Mar 2026 16:25:03 -0400
Subject: [PATCH] (#62) Implement Collection component

- Adds Collection and CollectionItem components with NCIDS usa-collection classes
- Support configurable heading level, optional link, description, and children slot
- Includes unit tests
- Adds Storybook documentation
- Updates pnpm-lock.yaml to lockfile v9

Closes #62
---
 .storybook/preview.scss                       |   1 +
 .../ncids/Collection/Collection.stories.tsx   | 136 +++++++++++
 .../ncids/Collection/Collection.test.tsx      | 221 ++++++++++++++++++
 .../ncids/Collection/Collection.tsx           |  77 ++++++
 src/components/ncids/Collection/index.ts      |   2 +
 src/components/ncids/index.ts                 |   2 +
 6 files changed, 439 insertions(+)
 create mode 100644 src/components/ncids/Collection/Collection.stories.tsx
 create mode 100644 src/components/ncids/Collection/Collection.test.tsx
 create mode 100644 src/components/ncids/Collection/Collection.tsx
 create mode 100644 src/components/ncids/Collection/index.ts

diff --git a/.storybook/preview.scss b/.storybook/preview.scss
index 3c8ba78..92e0b24 100644
--- a/.storybook/preview.scss
+++ b/.storybook/preview.scss
@@ -7,3 +7,4 @@
 @forward 'uswds-global';
 @forward 'usa-pagination';
 @forward 'usa-icon';
+@forward 'usa-collection';
diff --git a/src/components/ncids/Collection/Collection.stories.tsx b/src/components/ncids/Collection/Collection.stories.tsx
new file mode 100644
index 0000000..859b99e
--- /dev/null
+++ b/src/components/ncids/Collection/Collection.stories.tsx
@@ -0,0 +1,136 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { fn } from '@storybook/test';
+import React from 'react';
+
+import { Collection, CollectionItem } from './Collection';
+
+const meta: Meta<typeof Collection> = {
+	title: 'NCIDS/Collection',
+	component: Collection,
+	tags: ['autodocs'],
+	argTypes: {
+		condensed: {
+			control: 'boolean',
+			description: 'Use condensed variant (headers only)',
+		},
+		className: {
+			control: 'text',
+			description: 'Additional CSS classes on the list',
+		},
+	},
+};
+
+export default meta;
+type Story = StoryObj<typeof Collection>;
+
+export const Default: Story = {
+	render: (args) => (
+		<Collection {...args}>
+			<CollectionItem
+				heading="Genomics and Cancer Research"
+				href="https://example.com/genomics"
+				description="Learn about the role of genomics in cancer diagnosis and treatment, including precision medicine approaches."
+			/>
+			<CollectionItem
+				heading="Clinical Trials Search"
+				href="https://example.com/trials"
+				description="Find NCI-supported clinical trials that are accepting participants. Search by cancer type, treatment, and location."
+			/>
+			<CollectionItem
+				heading="Cancer Statistics"
+				href="https://example.com/statistics"
+				description="Statistical data and trends for common cancer types in the United States."
+			/>
+		</Collection>
+	),
+};
+
+export const Condensed: Story = {
+	render: () => (
+		<Collection condensed>
+			<CollectionItem
+				heading="Genomics and Cancer Research"
+				href="https://example.com/genomics"
+			/>
+			<CollectionItem
+				heading="Clinical Trials Search"
+				href="https://example.com/trials"
+			/>
+			<CollectionItem
+				heading="Cancer Statistics"
+				href="https://example.com/statistics"
+			/>
+		</Collection>
+	),
+};
+
+export const WithExtraContent: Story = {
+	name: 'With Extra Content (Children)',
+	render: () => (
+		<Collection>
+			<CollectionItem
+				heading="Breast Cancer Treatment"
+				href="https://www.cancer.gov/types/breast"
+				description="Information about breast cancer treatment options including surgery, chemotherapy, and radiation."
+			>
+				<cite>https://www.cancer.gov/types/breast</cite>
+			</CollectionItem>
+			<CollectionItem
+				heading="Lung Cancer Prevention"
+				href="https://www.cancer.gov/types/lung"
+				description="Steps you can take to lower your risk of getting lung cancer."
+			>
+				<cite>https://www.cancer.gov/types/lung</cite>
+			</CollectionItem>
+		</Collection>
+	),
+};
+
+export const WithoutLinks: Story = {
+	name: 'Without Links (Plain Headings)',
+	render: () => (
+		<Collection>
+			<CollectionItem
+				heading="Important Announcement"
+				description="This item has a plain text heading without a link."
+			/>
+			<CollectionItem
+				heading="Another Announcement"
+				description="Another item with no navigation."
+			/>
+		</Collection>
+	),
+};
+
+export const CustomHeadingLevel: Story = {
+	name: 'Custom Heading Level (h4)',
+	render: () => (
+		<Collection>
+			<CollectionItem
+				heading="Section Result"
+				headingLevel="h4"
+				href="https://example.com"
+				description="This item uses an h4 heading level."
+			/>
+		</Collection>
+	),
+};
+
+export const Interactive: Story = {
+	render: () => {
+		const handleClick = fn();
+		return (
+			<Collection>
+				<CollectionItem
+					heading="Click to track"
+					href="https://example.com"
+					description="Clicking the heading link fires onHeadingClick."
+					onHeadingClick={(e) => {
+						e.preventDefault();
+						handleClick();
+					}}
+				/>
+			</Collection>
+		);
+	},
+};
diff --git a/src/components/ncids/Collection/Collection.test.tsx b/src/components/ncids/Collection/Collection.test.tsx
new file mode 100644
index 0000000..702374f
--- /dev/null
+++ b/src/components/ncids/Collection/Collection.test.tsx
@@ -0,0 +1,221 @@
+import React from 'react';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { axe } from 'vitest-axe';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { Collection, CollectionItem } from './Collection';
+
+describe('<Collection />', () => {
+	afterEach(() => {
+		cleanup();
+	});
+
+	it('should render a ul with usa-collection class', () => {
+		const { container } = render(
+			<Collection>
+				<CollectionItem heading="Item 1" />
+			</Collection>
+		);
+		const ul = container.querySelector('ul');
+		expect(ul).toHaveClass('usa-collection');
+	});
+
+	it('should apply usa-collection--condensed when condensed is true', () => {
+		const { container } = render(
+			<Collection condensed>
+				<CollectionItem heading="Item 1" />
+			</Collection>
+		);
+		const ul = container.querySelector('ul');
+		expect(ul).toHaveClass('usa-collection', 'usa-collection--condensed');
+	});
+
+	it('should not apply condensed class when condensed is false', () => {
+		const { container } = render(
+			<Collection>
+				<CollectionItem heading="Item 1" />
+			</Collection>
+		);
+		const ul = container.querySelector('ul');
+		expect(ul).not.toHaveClass('usa-collection--condensed');
+	});
+
+	it('should pass additional className to Collection ul', () => {
+		const { container } = render(
+			<Collection className="no-bullets custom-class">
+				<CollectionItem heading="Item 1" />
+			</Collection>
+		);
+		const ul = container.querySelector('ul');
+		expect(ul).toHaveClass('usa-collection', 'no-bullets', 'custom-class');
+	});
+});
+
+describe('<CollectionItem />', () => {
+	afterEach(() => {
+		cleanup();
+	});
+
+	it('should render an li with usa-collection__item class', () => {
+		render(
+			<Collection>
+				<CollectionItem heading="Test heading" />
+			</Collection>
+		);
+		const li = screen.getByRole('listitem');
+		expect(li).toHaveClass('usa-collection__item');
+	});
+
+	it('should render heading in h3 by default', () => {
+		render(
+			<Collection>
+				<CollectionItem heading="Test heading" />
+			</Collection>
+		);
+		expect(
+			screen.getByRole('heading', { level: 3, name: 'Test heading' })
+		).toBeInTheDocument();
+	});
+
+	it('should render heading with h2 level', () => {
+		render(
+			<Collection>
+				<CollectionItem heading="Test heading" headingLevel="h2" />
+			</Collection>
+		);
+		expect(
+			screen.getByRole('heading', { level: 2, name: 'Test heading' })
+		).toBeInTheDocument();
+	});
+
+	it('should render heading with h4 level', () => {
+		render(
+			<Collection>
+				<CollectionItem heading="Test heading" headingLevel="h4" />
+			</Collection>
+		);
+		expect(
+			screen.getByRole('heading', { level: 4, name: 'Test heading' })
+		).toBeInTheDocument();
+	});
+
+	it('should wrap heading in a link when href is provided', () => {
+		render(
+			<Collection>
+				<CollectionItem heading="Click me" href="https://example.com" />
+			</Collection>
+		);
+		const link = screen.getByRole('link', { name: 'Click me' });
+		expect(link).toHaveClass('usa-link');
+		expect(link).toHaveAttribute('href', 'https://example.com');
+	});
+
+	it('should render heading as plain text when no href', () => {
+		render(
+			<Collection>
+				<CollectionItem heading="Plain heading" />
+			</Collection>
+		);
+		expect(screen.getByText('Plain heading')).toBeInTheDocument();
+		expect(screen.queryByRole('link')).not.toBeInTheDocument();
+	});
+
+	it('should render description in a p element', () => {
+		const { container } = render(
+			<Collection>
+				<CollectionItem heading="Title" description="A description here" />
+			</Collection>
+		);
+		const desc = container.querySelector('.usa-collection__description');
+		expect(desc).toBeInTheDocument();
+		expect(desc?.tagName).toBe('P');
+		expect(desc).toHaveTextContent('A description here');
+	});
+
+	it('should not render description p when no description prop', () => {
+		const { container } = render(
+			<Collection>
+				<CollectionItem heading="Title" />
+			</Collection>
+		);
+		expect(
+			container.querySelector('.usa-collection__description')
+		).not.toBeInTheDocument();
+	});
+
+	it('should render children inside collection__body', () => {
+		const { container } = render(
+			<Collection>
+				<CollectionItem heading="Title">
+					<cite className="custom-cite">https://example.com</cite>
+				</CollectionItem>
+			</Collection>
+		);
+		const body = container.querySelector('.usa-collection__body');
+		const cite = body?.querySelector('cite.custom-cite');
+		expect(cite).toBeInTheDocument();
+		expect(cite).toHaveTextContent('https://example.com');
+	});
+
+	it('should pass additional className to li element', () => {
+		render(
+			<Collection>
+				<CollectionItem
+					heading="Title"
+					className="sws-results__list-item grid-container"
+				/>
+			</Collection>
+		);
+		const li = screen.getByRole('listitem');
+		expect(li).toHaveClass(
+			'usa-collection__item',
+			'sws-results__list-item',
+			'grid-container'
+		);
+	});
+
+	it('should call onHeadingClick when heading link is clicked', () => {
+		const handler = vi.fn();
+		render(
+			<Collection>
+				<CollectionItem
+					heading="Clickable"
+					href="https://example.com"
+					onHeadingClick={handler}
+				/>
+			</Collection>
+		);
+		fireEvent.click(screen.getByRole('link', { name: 'Clickable' }));
+		expect(handler).toHaveBeenCalledTimes(1);
+	});
+
+	it('should apply usa-collection__heading class to heading element', () => {
+		const { container } = render(
+			<Collection>
+				<CollectionItem heading="Title" />
+			</Collection>
+		);
+		expect(
+			container.querySelector('.usa-collection__heading')
+		).toBeInTheDocument();
+	});
+
+	it('should have no accessibility violations', async () => {
+		const { container } = render(
+			<Collection>
+				<CollectionItem
+					heading="Accessible item"
+					href="https://example.com"
+					description="This is a description"
+				/>
+				<CollectionItem
+					heading="Second item"
+					href="https://example.com/2"
+					description="Another description"
+				/>
+			</Collection>
+		);
+		const results = await axe(container);
+		expect(results).toHaveNoViolations();
+	});
+});
diff --git a/src/components/ncids/Collection/Collection.tsx b/src/components/ncids/Collection/Collection.tsx
new file mode 100644
index 0000000..6576eb4
--- /dev/null
+++ b/src/components/ncids/Collection/Collection.tsx
@@ -0,0 +1,77 @@
+import React from 'react';
+
+export interface CollectionItemProps {
+	/** Item heading content. */
+	heading: React.ReactNode;
+	/** URL for the heading link. If provided, heading is wrapped in an anchor. */
+	href?: string;
+	/** Heading element level. Defaults to 'h3'. */
+	headingLevel?: 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+	/** Item description text, rendered in a <p>. */
+	description?: React.ReactNode;
+	/** Click handler for the heading link. */
+	onHeadingClick?: (e: React.MouseEvent<HTMLAnchorElement>) => void;
+	/** Additional CSS classes on the <li>. */
+	className?: string;
+	/** Extra content rendered below description inside collection__body. */
+	children?: React.ReactNode;
+}
+
+export interface CollectionProps {
+	/** Collection items (should be CollectionItem elements). */
+	children: React.ReactNode;
+	/** Use condensed variant (headers only). */
+	condensed?: boolean;
+	/** Additional CSS classes on the <ul>. */
+	className?: string;
+}
+
+export const CollectionItem: React.FC<CollectionItemProps> = ({
+	heading,
+	href,
+	headingLevel = 'h3',
+	description,
+	onHeadingClick,
+	className,
+	children,
+}) => {
+	const HeadingTag = headingLevel;
+
+	return (
+		<li className={`usa-collection__item${className ? ` ${className}` : ''}`}>
+			<div className="usa-collection__body">
+				<HeadingTag className="usa-collection__heading">
+					{href ? (
+						<a className="usa-link" href={href} onClick={onHeadingClick}>
+							{heading}
+						</a>
+					) : (
+						heading
+					)}
+				</HeadingTag>
+				{description && (
+					<p className="usa-collection__description">{description}</p>
+				)}
+				{children}
+			</div>
+		</li>
+	);
+};
+
+export const Collection: React.FC<CollectionProps> = ({
+	children,
+	condensed = false,
+	className,
+}) => {
+	const classes = [
+		'usa-collection',
+		condensed ? 'usa-collection--condensed' : '',
+		className || '',
+	]
+		.filter(Boolean)
+		.join(' ');
+
+	return <ul className={classes}>{children}</ul>;
+};
+
+export default Collection;
diff --git a/src/components/ncids/Collection/index.ts b/src/components/ncids/Collection/index.ts
new file mode 100644
index 0000000..820ba7e
--- /dev/null
+++ b/src/components/ncids/Collection/index.ts
@@ -0,0 +1,2 @@
+export { Collection, CollectionItem, default } from './Collection';
+export type { CollectionProps, CollectionItemProps } from './Collection';
diff --git a/src/components/ncids/index.ts b/src/components/ncids/index.ts
index 69ce882..5ec3538 100644
--- a/src/components/ncids/index.ts
+++ b/src/components/ncids/index.ts
@@ -1,3 +1,5 @@
 // NCIDS components barrel export
 export { Pager } from './Pager';
 export type { PagerProps, PageChangeData } from './Pager';
+export { Collection, CollectionItem } from './Collection';
+export type { CollectionProps, CollectionItemProps } from './Collection';