@nationaldesignstudio/react 0.0.14 → 0.0.16

package/src/components/sections/two-column-section/two-column-section.stories.tsx

@@ -0,0 +1,285 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { TwoColumnSection } from ".";
+
+const meta: Meta<typeof TwoColumnSection> = {
+	title: "Sections/TwoColumnSection",
+	component: TwoColumnSection,
+	parameters: {
+		layout: "fullscreen",
+	},
+	argTypes: {
+		variant: {
+			control: "select",
+			options: ["dark", "light"],
+			description: "Color variant",
+		},
+		title: {
+			control: "text",
+			description: "The title text",
+		},
+		lead: {
+			control: "text",
+			description: "Lead content (prominent)",
+		},
+	},
+} as Meta<typeof TwoColumnSection>;
+
+export default meta;
+type Story = StoryObj<typeof TwoColumnSection>;
+
+// =============================================================================
+// Playground
+// =============================================================================
+
+export const Playground: Story = {
+	render: (args) => <TwoColumnSection {...args} />,
+};
+Playground.args = {
+	variant: "dark",
+	title: "US Tech Force",
+	lead: "The US Tech Force is recruiting an elite corps of engineers to build the next generation of government technology. Backed by the White House, Tech Force will tackle the most complex and large-scale civic and defense challenges of our era – from administering critical financial infrastructure at the Treasury Department to advancing cutting-edge programs at the Department of War – and everything in between.",
+	children: (
+		<>
+			<p>
+				Through a two-year program, participants will work in teams reporting
+				directly to agency leadership. In collaboration with leading technology
+				companies, participants will receive technical training, engage with
+				industry leaders, and work closely with senior managers from companies
+				partnering with the Tech Force.
+			</p>
+			<p>
+				Upon completing the program, engineers can seek employment with the
+				partnering private-sector companies for potential full-time roles –
+				demonstrating the value of combining civil service with technical
+				expertise.
+			</p>
+			<p>
+				If you are highly skilled in the areas of software engineering,
+				artificial intelligence, cybersecurity, data analytics, or technical
+				project management and want to build the future of American government
+				technology, join the Tech Force today.
+			</p>
+		</>
+	),
+};
+
+// =============================================================================
+// Variants
+// =============================================================================
+
+/**
+ * Dark variant (default) - dark background with light text
+ */
+export const DarkVariant: Story = {
+	render: () => (
+		<TwoColumnSection
+			variant="dark"
+			title="US Tech Force"
+			lead="The US Tech Force is recruiting an elite corps of engineers to build the next generation of government technology."
+		>
+			<p>
+				Through a two-year program, participants will work in teams reporting
+				directly to agency leadership.
+			</p>
+			<p>
+				Upon completing the program, engineers can seek employment with the
+				partnering private-sector companies for potential full-time roles.
+			</p>
+		</TwoColumnSection>
+	),
+};
+
+/**
+ * Light variant - light background with dark text
+ */
+export const LightVariant: Story = {
+	render: () => (
+		<TwoColumnSection
+			variant="light"
+			title="US Tech Force"
+			lead="The US Tech Force is recruiting an elite corps of engineers to build the next generation of government technology."
+		>
+			<p>
+				Through a two-year program, participants will work in teams reporting
+				directly to agency leadership.
+			</p>
+			<p>
+				Upon completing the program, engineers can seek employment with the
+				partnering private-sector companies for potential full-time roles.
+			</p>
+		</TwoColumnSection>
+	),
+};
+
+// =============================================================================
+// Responsive Variants
+// =============================================================================
+
+export const Desktop: Story = {
+	render: () => (
+		<TwoColumnSection
+			variant="dark"
+			title="US Tech Force"
+			lead="The US Tech Force is recruiting an elite corps of engineers to build the next generation of government technology. Backed by the White House, Tech Force will tackle the most complex and large-scale civic and defense challenges of our era."
+		>
+			<p>
+				Through a two-year program, participants will work in teams reporting
+				directly to agency leadership. In collaboration with leading technology
+				companies, participants will receive technical training, engage with
+				industry leaders, and work closely with senior managers from companies
+				partnering with the Tech Force.
+			</p>
+			<p>
+				Upon completing the program, engineers can seek employment with the
+				partnering private-sector companies for potential full-time roles –
+				demonstrating the value of combining civil service with technical
+				expertise.
+			</p>
+			<p>
+				If you are highly skilled in the areas of software engineering,
+				artificial intelligence, cybersecurity, data analytics, or technical
+				project management and want to build the future of American government
+				technology, join the Tech Force today.
+			</p>
+		</TwoColumnSection>
+	),
+	globals: {
+		viewport: { value: "lg", isRotated: false },
+	},
+};
+
+export const Tablet: Story = {
+	render: () => (
+		<TwoColumnSection
+			variant="dark"
+			title="US Tech Force"
+			lead="The US Tech Force is recruiting an elite corps of engineers to build the next generation of government technology. Backed by the White House, Tech Force will tackle the most complex and large-scale civic and defense challenges of our era."
+		>
+			<p>
+				Through a two-year program, participants will work in teams reporting
+				directly to agency leadership. In collaboration with leading technology
+				companies, participants will receive technical training, engage with
+				industry leaders, and work closely with senior managers from companies
+				partnering with the Tech Force.
+			</p>
+			<p>
+				Upon completing the program, engineers can seek employment with the
+				partnering private-sector companies for potential full-time roles –
+				demonstrating the value of combining civil service with technical
+				expertise.
+			</p>
+			<p>
+				If you are highly skilled in the areas of software engineering,
+				artificial intelligence, cybersecurity, data analytics, or technical
+				project management and want to build the future of American government
+				technology, join the Tech Force today.
+			</p>
+		</TwoColumnSection>
+	),
+	globals: {
+		viewport: { value: "md", isRotated: false },
+	},
+};
+
+export const Mobile: Story = {
+	render: () => (
+		<TwoColumnSection
+			variant="dark"
+			title="US Tech Force"
+			lead="The US Tech Force is recruiting an elite corps of engineers to build the next generation of government technology. Backed by the White House, Tech Force will tackle the most complex and large-scale civic and defense challenges of our era."
+		>
+			<p>
+				Through a two-year program, participants will work in teams reporting
+				directly to agency leadership. In collaboration with leading technology
+				companies, participants will receive technical training, engage with
+				industry leaders, and work closely with senior managers from companies
+				partnering with the Tech Force.
+			</p>
+			<p>
+				Upon completing the program, engineers can seek employment with the
+				partnering private-sector companies for potential full-time roles –
+				demonstrating the value of combining civil service with technical
+				expertise.
+			</p>
+			<p>
+				If you are highly skilled in the areas of software engineering,
+				artificial intelligence, cybersecurity, data analytics, or technical
+				project management and want to build the future of American government
+				technology, join the Tech Force today.
+			</p>
+		</TwoColumnSection>
+	),
+	globals: {
+		viewport: { value: "sm", isRotated: false },
+	},
+};
+
+// =============================================================================
+// Content Variations
+// =============================================================================
+
+/**
+ * Without lead content - just title and body
+ */
+export const WithoutLead: Story = {
+	render: () => (
+		<TwoColumnSection variant="dark" title="About the Program">
+			<p>
+				Through a two-year program, participants will work in teams reporting
+				directly to agency leadership. In collaboration with leading technology
+				companies, participants will receive technical training, engage with
+				industry leaders, and work closely with senior managers from companies
+				partnering with the Tech Force.
+			</p>
+			<p>
+				Upon completing the program, engineers can seek employment with the
+				partnering private-sector companies for potential full-time roles.
+			</p>
+		</TwoColumnSection>
+	),
+};
+
+/**
+ * With rich lead content (ReactNode)
+ */
+export const RichLeadContent: Story = {
+	render: () => (
+		<TwoColumnSection
+			variant="dark"
+			title="Our Mission"
+			lead={
+				<>
+					<p>
+						The US Tech Force is recruiting an elite corps of engineers to build
+						the next generation of government technology.
+					</p>
+					<p>
+						Backed by the White House, Tech Force will tackle the most complex
+						and large-scale civic and defense challenges of our era.
+					</p>
+				</>
+			}
+		>
+			<p>
+				From administering critical financial infrastructure at the Treasury
+				Department to advancing cutting-edge programs at the Department of War –
+				and everything in between.
+			</p>
+		</TwoColumnSection>
+	),
+};
+
+/**
+ * Short content example
+ */
+export const ShortContent: Story = {
+	render: () => (
+		<TwoColumnSection
+			variant="dark"
+			title="Join Us"
+			lead="Build the future of American government technology."
+		>
+			<p>Applications are now open for qualified engineers.</p>
+		</TwoColumnSection>
+	),
+};

package/src/components/sections/two-column-section/two-column-section.tsx

@@ -0,0 +1,162 @@
+import * as React from "react";
+import { tv, type VariantProps } from "tailwind-variants";
+import { cn } from "@/lib/utils";
+
+/**
+ * TwoColumnSection component for text-heavy content sections
+ *
+ * Layout:
+ * - Desktop (lg+): Title left, content right with border-top divider
+ * - Mobile/Tablet: Stacked vertically
+ *
+ * Uses the 24-column grid system.
+ */
+const twoColumnSectionVariants = tv({
+	// Base styles - responsive padding using primitive spacing tokens
+	base: [
+		"w-full",
+		// Small (mobile): 20px x, 56px top, 20px bottom
+		"px-spacing-20 pt-spacing-56 pb-spacing-20",
+		// Medium (tablet): 56px x, 56px y
+		"md:px-spacing-56 md:py-spacing-56",
+		// Large (desktop): 72px x, 72px top, 112px bottom
+		"lg:px-spacing-72 lg:pt-spacing-72 lg:pb-spacing-112",
+	],
+	variants: {
+		variant: {
+			dark: "bg-gray-1200",
+			light: "bg-white",
+		},
+		layout: {
+			/** Default 24-column grid with asymmetric split (title: 9, content: 15) */
+			asymmetric: "",
+			/** Equal 2-column layout at md+ breakpoints */
+			equal: "",
+		},
+	},
+	defaultVariants: {
+		variant: "dark",
+		layout: "asymmetric",
+	},
+});
+
+export interface TwoColumnSectionProps
+	extends React.HTMLAttributes<HTMLElement>,
+		VariantProps<typeof twoColumnSectionVariants> {
+	/**
+	 * The title text displayed in the left column
+	 */
+	title: string;
+	/**
+	 * Lead content - prominently styled (brighter text)
+	 * Can be a string or ReactNode for rich content
+	 */
+	lead?: React.ReactNode;
+	/**
+	 * Body content - secondary styled (muted text)
+	 * Can be a string or ReactNode for rich content
+	 */
+	children: React.ReactNode;
+	/**
+	 * Layout style for the columns
+	 * - "asymmetric" (default): Uses 24-column grid with ~40/60 split (title: 9, content: 15)
+	 * - "equal": Simple 2-column equal-width layout at md+ breakpoints
+	 */
+	layout?: "asymmetric" | "equal";
+}
+
+/**
+ * TwoColumnSection component for text-heavy content with title/content split.
+ *
+ * Layout:
+ * - Mobile/Tablet: Stacked (title above content)
+ * - Desktop (lg+): Title left (~40%), Content right (~60%)
+ *
+ * @example
+ * ```tsx
+ * <TwoColumnSection
+ *   title="US Tech Force"
+ *   lead="The US Tech Force is recruiting an elite corps of engineers..."
+ *   variant="dark"
+ * >
+ *   <p>Through a two-year program, participants will work...</p>
+ *   <p>Upon completing the program, engineers can seek...</p>
+ * </TwoColumnSection>
+ * ```
+ */
+const TwoColumnSection = React.forwardRef<HTMLElement, TwoColumnSectionProps>(
+	(
+		{ className, variant = "dark", layout, title, lead, children, ...props },
+		ref,
+	) => {
+		return (
+			<section
+				ref={ref}
+				className={twoColumnSectionVariants({
+					variant,
+					layout,
+					class: className,
+				})}
+				{...props}
+			>
+				{/* Inner container with border-top - uses primitive spacing tokens */}
+				<div
+					className={cn(
+						"border-t pt-spacing-36",
+						variant === "dark" ? "border-gray-700" : "border-gray-300",
+						// Grid layout - uses primitive spacing tokens
+						"grid grid-cols-1 gap-spacing-56",
+						layout === "equal"
+							? "md:grid-cols-2"
+							: "lg:grid-cols-24 lg:gap-spacing-56",
+					)}
+				>
+					{/* Title column */}
+					<h2
+						className={cn(
+							"typography-subheading-medium",
+							variant === "dark" ? "text-gray-100" : "text-gray-900",
+							// Column span based on layout
+							layout !== "equal" && "lg:col-span-9",
+						)}
+					>
+						{title}
+					</h2>
+
+					{/* Content column - uses primitive spacing tokens */}
+					<div
+						className={cn(
+							"flex flex-col gap-spacing-56",
+							layout !== "equal" && "lg:col-span-15",
+						)}
+					>
+						{/* Lead content - brighter/prominent */}
+						{lead && (
+							<div
+								className={cn(
+									"typography-body-large",
+									variant === "dark" ? "text-gray-100" : "text-gray-900",
+								)}
+							>
+								{typeof lead === "string" ? <p>{lead}</p> : lead}
+							</div>
+						)}
+
+						{/* Body content - muted */}
+						<div
+							className={cn(
+								"typography-body-medium flex flex-col gap-[1em]",
+								variant === "dark" ? "text-gray-400" : "text-gray-600",
+							)}
+						>
+							{children}
+						</div>
+					</div>
+				</div>
+			</section>
+		);
+	},
+);
+TwoColumnSection.displayName = "TwoColumnSection";
+
+export { TwoColumnSection, twoColumnSectionVariants };

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export { useEventListener } from "./use-event-listener";

package/src/hooks/use-event-listener.ts

@@ -0,0 +1,73 @@
+"use client";
+
+import * as React from "react";
+
+type EventMap<T> = T extends Window
+	? WindowEventMap
+	: T extends Document
+		? DocumentEventMap
+		: T extends HTMLElement
+			? HTMLElementEventMap
+			: never;
+
+/**
+ * Custom hook that attaches an event listener to a specified element.
+ * Automatically handles cleanup on unmount and when dependencies change.
+ *
+ * @param eventName - The name of the event to listen for
+ * @param handler - The callback function to execute when the event fires
+ * @param element - The element to attach the listener to (defaults to window)
+ * @param options - Optional event listener options
+ *
+ * @example
+ * ```tsx
+ * // Listen to window resize
+ * useEventListener('resize', handleResize);
+ *
+ * // Listen to element scroll
+ * useEventListener('scroll', handleScroll, containerRef.current);
+ *
+ * // With options
+ * useEventListener('scroll', handleScroll, window, { passive: true });
+ * ```
+ */
+export function useEventListener<
+	T extends Window | Document | HTMLElement,
+	K extends keyof EventMap<T>,
+>(
+	eventName: K,
+	handler: (event: EventMap<T>[K]) => void,
+	element?: T | null,
+	options?: boolean | AddEventListenerOptions,
+): void {
+	// Store the handler in a ref to avoid re-subscribing on every render
+	const savedHandler = React.useRef(handler);
+
+	// Update ref when handler changes
+	React.useLayoutEffect(() => {
+		savedHandler.current = handler;
+	}, [handler]);
+
+	React.useEffect(() => {
+		// Default to window if no element is provided
+		const targetElement = element ?? window;
+
+		if (!targetElement?.addEventListener) {
+			return;
+		}
+
+		const eventListener = (event: Event) => {
+			savedHandler.current(event as EventMap<T>[K]);
+		};
+
+		targetElement.addEventListener(eventName as string, eventListener, options);
+
+		return () => {
+			targetElement.removeEventListener(
+				eventName as string,
+				eventListener,
+				options,
+			);
+		};
+	}, [eventName, element, options]);
+}

package/src/index.ts

@@ -0,0 +1,155 @@
+// =============================================================================
+// Atoms
+// =============================================================================
+export type {
+	AccordionItemProps,
+	AccordionProps,
+} from "./components/atoms/accordion";
+export { Accordion, AccordionItem } from "./components/atoms/accordion";
+export type { ButtonProps, IconButtonProps } from "./components/atoms/button";
+export {
+	Button,
+	buttonVariants,
+	IconButton,
+	iconButtonVariants,
+} from "./components/atoms/button";
+export type { NdstudioFooterProps } from "./components/atoms/ndstudio-footer";
+export { NdstudioFooter } from "./components/atoms/ndstudio-footer";
+export type { PagerControlProps } from "./components/atoms/pager-control";
+export {
+	PagerControl,
+	pagerControlVariants,
+} from "./components/atoms/pager-control";
+// =============================================================================
+// Dev Tools
+// =============================================================================
+export type { DevToolbarProps, GridOverlayProps } from "./components/dev-tools";
+export { DevToolbar, GridOverlay } from "./components/dev-tools";
+// =============================================================================
+// Organisms
+// =============================================================================
+export type {
+	CardActionsProps,
+	CardBodyProps,
+	CardContentProps,
+	CardDescriptionProps,
+	CardEyebrowProps,
+	CardImageProps,
+	CardProps,
+	CardTitleProps,
+} from "./components/organisms/card";
+export {
+	Card,
+	CardActions,
+	CardBody,
+	CardContent,
+	CardDescription,
+	CardEyebrow,
+	CardImage,
+	CardTitle,
+	cardVariants,
+} from "./components/organisms/card";
+export type {
+	NavbarActionsProps,
+	NavbarBrandProps,
+	NavbarLinkProps,
+	NavbarLinksProps,
+	NavbarMobileMenuButtonProps,
+	NavbarMobileMenuLinkProps,
+	NavbarMobileMenuProps,
+	NavbarProps,
+} from "./components/organisms/navbar";
+export {
+	Navbar,
+	NavbarActions,
+	NavbarBrand,
+	NavbarLink,
+	NavbarLinks,
+	NavbarMobileMenu,
+	NavbarMobileMenuButton,
+	NavbarMobileMenuLink,
+} from "./components/organisms/navbar";
+export type { USGovBannerProps } from "./components/organisms/us-gov-banner";
+export { USGovBanner } from "./components/organisms/us-gov-banner";
+// =============================================================================
+// Sections
+// =============================================================================
+export type { BannerProps } from "./components/sections/banner";
+export { Banner, bannerVariants } from "./components/sections/banner";
+export type { CardGridProps } from "./components/sections/card-grid";
+export { CardGrid, cardGridVariants } from "./components/sections/card-grid";
+export type { FaqSectionProps } from "./components/sections/faq-section";
+export { FaqSection } from "./components/sections/faq-section";
+export type {
+	HeroBackgroundImageProps,
+	HeroBackgroundStreamProps,
+	HeroBackgroundVideoProps,
+	HeroProps,
+} from "./components/sections/hero";
+export {
+	DEFAULT_TITLE_TYPOGRAPHY,
+	Hero,
+	HeroBackground,
+	heroVariants,
+} from "./components/sections/hero";
+export type {
+	ProseProps,
+	ProseSectionProps,
+} from "./components/sections/prose";
+export { Prose, ProseSection } from "./components/sections/prose";
+export type { RiverProps } from "./components/sections/river";
+export { River, riverVariants } from "./components/sections/river";
+export type { ToutProps } from "./components/sections/tout";
+export { Tout } from "./components/sections/tout";
+export type { TwoColumnSectionProps } from "./components/sections/two-column-section";
+export {
+	TwoColumnSection,
+	twoColumnSectionVariants,
+} from "./components/sections/two-column-section";
+// =============================================================================
+// Theme
+// =============================================================================
+export type {
+	ButtonTheme,
+	ColorToken,
+	ComponentTheme,
+	ComponentThemeColors,
+	ComponentThemeSpatial,
+	ComponentThemeSurface,
+	FontSizeToken,
+	RadiusToken,
+	SpacingToken,
+} from "./lib/theme";
+export {
+	buttonThemeToStyleVars,
+	FONT_SIZES,
+	fontSizeToClass,
+	responsiveTypographyClass,
+	themeToStyleVars,
+} from "./lib/theme";
+
+// =============================================================================
+// Utilities
+// =============================================================================
+export { cn } from "./lib/utils";
+
+// =============================================================================
+// Theme
+// =============================================================================
+export {
+	applyTheme,
+	createThemeStyle,
+	filterCSSVars,
+	getToken,
+	mergeCSSVars,
+	removeTheme,
+	type ThemeContextValue,
+	// Provider and hooks
+	ThemeProvider,
+	type ThemeProviderProps,
+	// Utilities
+	toCSSVars,
+	useCSSVars,
+	useTheme,
+	useThemeTokens,
+} from "./theme";