@nationaldesignstudio/react 0.5.6 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nationaldesignstudio/react",
-	"version": "0.5.6",
+	"version": "0.6.0",
 	"type": "module",
 	"sideEffects": [
 		"*.css"
@@ -45,7 +45,8 @@
 		"test:visual": "PW_TEST_CONNECT_WS_ENDPOINT=ws://127.0.0.1:3100 vitest run --config vitest.visual.config.ts",
 		"test:visual:update": "PW_TEST_CONNECT_WS_ENDPOINT=ws://127.0.0.1:3100 vitest run --config vitest.visual.config.ts --update",
 		"docker:playwright": "docker compose up playwright",
-		"docker:playwright:down": "docker compose down"
+		"docker:playwright:down": "docker compose down",
+		"release": "release-it"
 	},
 	"peerDependencies": {
 		"@cloudflare/stream-react": "^1.0.0",
@@ -74,11 +75,9 @@
 		"tailwind-variants": "^0.3.1"
 	},
 	"devDependencies": {
-		"@cloudflare/stream-react": "^1.9.1",
 		"@chromatic-com/storybook": "catalog:",
+		"@cloudflare/stream-react": "^1.9.1",
 		"@figma/code-connect": "^1.3.12",
-		"hls.js": "^1.5.17",
-		"lucide-react": "^0.511.0",
 		"@nds-design-system/tailwind-token-generator": "workspace:*",
 		"@nds-design-system/tokens": "workspace:*",
 		"@nds-design-system/tools": "workspace:*",
@@ -99,9 +98,12 @@
 		"@vitest/browser-playwright": "catalog:",
 		"@vitest/coverage-v8": "catalog:",
 		"globals": "catalog:",
+		"hls.js": "^1.5.17",
+		"lucide-react": "^0.511.0",
 		"playwright": "catalog:",
 		"react": "catalog:",
 		"react-dom": "catalog:",
+		"release-it": "^19.2.4",
 		"storybook": "catalog:",
 		"tailwindcss": "catalog:",
 		"tsup": "^8.5.1",

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

@@ -12,6 +12,16 @@ const cardVariants = tv({
 			 * Use with Background components for images/gradients.
 			 */
 			overlay: "w-full flex-col",
+			/**
+			 * Profile layout - square image with stacked content below.
+			 * Ideal for team member cards, user profiles, testimonials.
+			 */
+			profile: "w-full flex-col",
+			/**
+			 * Compact layout - small thumbnail with condensed horizontal content.
+			 * Ideal for news items, article previews, resource lists.
+			 */
+			compact: "w-full flex-row items-center gap-16",
 		},
 	},
 	defaultVariants: {
@@ -48,16 +58,26 @@ const Card = React.forwardRef<HTMLDivElement, CardProps>(
 Card.displayName = "Card";
 
 const cardImageVariants = tv({
-	base: [
-		"relative shrink-0 bg-bg-muted",
-		// 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",
-	],
+	base: "relative shrink-0 bg-bg-muted",
+	variants: {
+		layout: {
+			vertical: "aspect-video w-full",
+			horizontal: "aspect-auto w-2/5 self-stretch",
+			overlay: "aspect-video w-full",
+			/** Profile: square aspect ratio for headshots/avatars */
+			profile: "aspect-square w-full",
+			/** Compact: fixed small size for thumbnails */
+			compact: "size-80 rounded-8",
+		},
+	},
+	defaultVariants: {
+		layout: "vertical",
+	},
 });
 
-export interface CardImageProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface CardImageProps
+	extends React.HTMLAttributes<HTMLDivElement>,
+		VariantProps<typeof cardImageVariants> {
 	/**
 	 * The image source URL
 	 */
@@ -69,15 +89,18 @@ export interface CardImageProps extends React.HTMLAttributes<HTMLDivElement> {
 }
 
 /**
- * Card image area. For vertical layout, displays with 16:9 aspect ratio.
- * For horizontal layout, takes up ~40% width and stretches to content height.
+ * Card image area with layout-specific styling.
+ * - vertical: 16:9 aspect ratio, full width
+ * - horizontal: ~40% width, stretches to content height
+ * - profile: square aspect ratio for headshots/avatars
+ * - compact: fixed small size for thumbnails
  */
 const CardImage = React.forwardRef<HTMLDivElement, CardImageProps>(
-	({ className, src, alt = "", ...props }, ref) => {
+	({ className, src, alt = "", layout, ...props }, ref) => {
 		return (
 			<div
 				ref={ref}
-				className={cardImageVariants({ class: className })}
+				className={cardImageVariants({ layout, class: className })}
 				{...props}
 			>
 				{src && (
@@ -263,6 +286,56 @@ const CardActions = React.forwardRef<HTMLDivElement, CardActionsProps>(
 );
 CardActions.displayName = "CardActions";
 
+const cardLinkVariants = tv({
+	base: "group/link flex items-center gap-4 text-text-muted transition-colors duration-200 hover:text-text-primary",
+});
+
+export interface CardLinkProps extends React.HTMLAttributes<HTMLSpanElement> {
+	/**
+	 * Whether to show the arrow indicator
+	 * @default true
+	 */
+	showArrow?: boolean;
+}
+
+/**
+ * Inline link element for cards with optional animated arrow.
+ * Commonly used for "Read More →" or "Learn More →" patterns.
+ *
+ * @example
+ * ```tsx
+ * <Card layout="compact">
+ *   <CardImage src="/thumb.jpg" layout="compact" />
+ *   <CardContent>
+ *     <CardTitle>Article Title</CardTitle>
+ *     <CardLink>Read More</CardLink>
+ *   </CardContent>
+ * </Card>
+ * ```
+ */
+const CardLink = React.forwardRef<HTMLSpanElement, CardLinkProps>(
+	({ className, children, showArrow = true, ...props }, ref) => {
+		return (
+			<span
+				ref={ref}
+				className={cardLinkVariants({ class: className })}
+				{...props}
+			>
+				<span>{children}</span>
+				{showArrow && (
+					<span
+						aria-hidden="true"
+						className="inline-block transition-transform duration-200 ease-out group-hover/link:translate-x-4"
+					>
+						→
+					</span>
+				)}
+			</span>
+		);
+	},
+);
+CardLink.displayName = "CardLink";
+
 export {
 	Card,
 	cardVariants,
@@ -280,4 +353,6 @@ export {
 	cardBodyVariants,
 	CardActions,
 	cardActionsVariants,
+	CardLink,
+	cardLinkVariants,
 };

package/src/components/sections/hero/hero.tsx

@@ -30,6 +30,7 @@ const heroVariants = tv({
 			"md:p-56",
 		],
 		title: DEFAULT_TITLE_TYPOGRAPHY,
+		indicator: "absolute inset-x-0 bottom-0 z-10 flex justify-center pb-24",
 	},
 	variants: {
 		variant: {
@@ -46,6 +47,21 @@ const heroVariants = tv({
 				content: ["items-center justify-center", "lg:p-64"],
 			},
 		},
+		/**
+		 * Vertical alignment of content within the hero.
+		 * Provides a simpler API than variant for basic alignment needs.
+		 */
+		contentAlign: {
+			top: {
+				content: "justify-start",
+			},
+			center: {
+				content: "items-center justify-center",
+			},
+			bottom: {
+				content: "justify-end",
+			},
+		},
 		colorScheme: {
 			dark: {
 				root: "bg-bg-page",
@@ -144,11 +160,24 @@ export interface HeroProps
 	 * - light: Light text for use on dark backgrounds
 	 */
 	colorScheme?: "dark" | "light";
+	// Note: contentAlign is provided by VariantProps<typeof heroVariants>
+	// Options: "top" | "center" | "bottom"
 	/**
 	 * Content for the top slot (full-width, no padding).
 	 * Use for USGovBanner, Navigation, etc.
 	 */
 	top?: React.ReactNode;
+	/**
+	 * Indicator slot for scroll hints, arrows, or other visual cues.
+	 * Rendered at the bottom of the hero, below the main content.
+	 * @example
+	 * ```tsx
+	 * <Hero indicator={<ChevronDown className="animate-bounce" />}>
+	 *   <h1>Welcome</h1>
+	 * </Hero>
+	 * ```
+	 */
+	indicator?: React.ReactNode;
 	/**
 	 * Background for the hero. Can be:
 	 * - A color string (hex, rgb, etc.) for solid backgrounds
@@ -235,7 +264,9 @@ const Hero = React.forwardRef<HTMLElement, HeroProps>(
 			title,
 			titleClassName,
 			colorScheme = "dark",
+			contentAlign,
 			top,
+			indicator,
 			variant,
 			background,
 			overlayOpacity = 0,
@@ -251,6 +282,7 @@ const Hero = React.forwardRef<HTMLElement, HeroProps>(
 		const hasMediaBackground = background && !isColor;
 		const styles = heroVariants({
 			variant,
+			contentAlign,
 			colorScheme,
 			hasBackground: !!background,
 		});
@@ -295,6 +327,9 @@ const Hero = React.forwardRef<HTMLElement, HeroProps>(
 					{/* Children - always render if provided */}
 					{children}
 				</div>
+
+				{/* Indicator slot - scroll hints, arrows, etc. */}
+				{indicator && <div className={styles.indicator()}>{indicator}</div>}
 			</section>
 		);
 	},

package/src/theme/index.ts

@@ -11,13 +11,17 @@ export type {
 	ColorThemeName,
 	CSSVariableMap,
 	NestedStringRecord,
+	ResolvedProjectTheme,
 	SurfaceThemeName,
 	ThemeComposition,
 } from "@nds-design-system/tokens";
+// Re-export project theme utilities for convenience
 // Re-export theme registries for programmatic access
 export {
 	colorThemeNames,
 	colorThemes,
+	defineTheme,
+	generateThemeCSS,
 	surfaceThemeNames,
 	surfaceThemes,
 } from "@nds-design-system/tokens";

package/src/theme/theme-provider.tsx

@@ -9,6 +9,7 @@ import type {
 	ColorThemeName,
 	CSSVariableMap,
 	NestedStringRecord,
+	ResolvedProjectTheme,
 	SurfaceThemeName,
 	TokenModule,
 } from "@nds-design-system/tokens";
@@ -46,6 +47,11 @@ export interface ThemeProviderProps {
 	color?: ColorThemeName;
 	/** Surface theme name (defaults to "base") */
 	surface?: SurfaceThemeName;
+	/**
+	 * Custom project theme created with defineTheme()
+	 * When provided, overrides color/surface props with custom theme tokens
+	 */
+	customTheme?: ResolvedProjectTheme;
 	/** Children to render */
 	children: ReactNode;
 	/** Optional className for the wrapper div */
@@ -239,8 +245,23 @@ function deepMerge(
  *   <App />
  * </ThemeProvider>
  *
- * // Mix and match
- * <ThemeProvider color="institution" surface="soft">
+ * // Use a custom project theme
+ * import { defineTheme, srgb } from "@nds-design-system/tokens";
+ *
+ * const myTheme = defineTheme({
+ *   name: "my-project",
+ *   extends: "base",
+ *   tokens: {
+ *     semantic: {
+ *       color: {
+ *         bg: { page: srgb("#FEFDF9") },
+ *         accent: { brand: srgb("#A68B5E") },
+ *       },
+ *     },
+ *   },
+ * });
+ *
+ * <ThemeProvider customTheme={myTheme}>
  *   <App />
  * </ThemeProvider>
  * ```
@@ -248,6 +269,7 @@ function deepMerge(
 export function ThemeProvider({
 	color = "base",
 	surface = "base",
+	customTheme,
 	children,
 	className,
 	applyStyles = true,
@@ -255,12 +277,17 @@ export function ThemeProvider({
 	const { tokens, cssVars } = useMemo(() => {
 		const flatTokens: Record<string, string> = {};
 
-		// Get color theme (merge with base if not base)
+		// Get base color theme
 		const baseColorModule = colorThemes.base;
-		const colorModule = colorThemes[color];
+
+		// If customTheme is provided, use its base theme; otherwise use the color prop
+		const effectiveColor = customTheme ? customTheme.extends : color;
+		const colorModule =
+			colorThemes[effectiveColor as keyof typeof colorThemes] ??
+			colorThemes.base;
 
 		const mergedColor =
-			color === "base"
+			effectiveColor === "base"
 				? (baseColorModule as Record<string, unknown>)
 				: mergeTokenModules(baseColorModule, colorModule);
 
@@ -287,15 +314,28 @@ export function ThemeProvider({
 
 		// Use shared utilities from tokens package
 		const nestedTokens = flatToNested(flatTokens);
-		const cssVariables = flatToCSSVars(flatTokens);
+		let cssVariables = flatToCSSVars(flatTokens);
+
+		// If customTheme provided, merge its CSS variables (overriding base values)
+		if (customTheme) {
+			cssVariables = {
+				...cssVariables,
+				...Object.fromEntries(
+					Object.entries(customTheme.cssVars).map(([key, value]) => [
+						key.startsWith("--") ? key : `--${key}`,
+						value,
+					]),
+				),
+			};
+		}
 
 		return { tokens: nestedTokens, cssVars: cssVariables };
-	}, [color, surface]);
+	}, [color, surface, customTheme]);
 
 	const contextValue: ThemeContextValue = {
 		cssVars,
 		tokens,
-		colorTheme: color,
+		colorTheme: customTheme ? (customTheme.extends as ColorThemeName) : color,
 		surfaceTheme: surface,
 	};