@nationaldesignstudio/react 0.0.15 → 0.0.16

package/src/styles.css

@@ -0,0 +1,11 @@
+@import "tailwindcss";
+@import "../../tailwind-token-generator/dist/tokens.css";
+
+@font-face {
+	font-family: "PP Neue Montreal";
+	src: url("./assets/fonts/PPNeueMontreal-Variable.woff2")
+		format("woff2-variations");
+	font-weight: 100 900;
+	font-style: normal;
+	font-display: swap;
+}

package/src/theme/ThemeProvider.tsx

@@ -0,0 +1,297 @@
+/**
+ * ThemeProvider
+ *
+ * React context provider for applying theme tokens as CSS variables.
+ * Use string theme names for type-safe selection, with "base" as default.
+ */
+
+import type {
+	ColorThemeName,
+	CSSVariableMap,
+	NestedStringRecord,
+	SurfaceThemeName,
+	TokenModule,
+} from "@nds-design-system/tokens";
+import {
+	colorThemes,
+	flatToCSSVars,
+	flatToNested,
+	isColorValue,
+	isDimensionValue,
+	surfaceThemes,
+} from "@nds-design-system/tokens";
+import { createContext, type ReactNode, useMemo } from "react";
+
+/**
+ * Theme context value
+ */
+export interface ThemeContextValue {
+	/** CSS variables map for inline styles */
+	cssVars: CSSVariableMap;
+	/** Resolved nested tokens */
+	tokens: NestedStringRecord;
+	/** Current color theme name */
+	colorTheme: ColorThemeName;
+	/** Current surface theme name */
+	surfaceTheme: SurfaceThemeName;
+}
+
+export const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+/**
+ * Props for ThemeProvider
+ */
+export interface ThemeProviderProps {
+	/** Color theme name (defaults to "base") */
+	color?: ColorThemeName;
+	/** Surface theme name (defaults to "base") */
+	surface?: SurfaceThemeName;
+	/** Children to render */
+	children: ReactNode;
+}
+
+/**
+ * Convert a color value to CSS string
+ */
+function colorToCSS(color: { components: number[]; alpha: number }): string {
+	const [r, g, b] = color.components;
+	if (color.alpha < 1) {
+		return `color(srgb ${r} ${g} ${b} / ${color.alpha})`;
+	}
+	return `color(srgb ${r} ${g} ${b})`;
+}
+
+/**
+ * Convert a token value to CSS string
+ */
+function tokenValueToCSS(value: unknown): string {
+	if (isColorValue(value)) {
+		return colorToCSS(value);
+	}
+	if (isDimensionValue(value)) {
+		return `${value.value}${value.unit}`;
+	}
+	if (typeof value === "string") {
+		return value;
+	}
+	if (typeof value === "number") {
+		return String(value);
+	}
+	return String(value);
+}
+
+/**
+ * Process color tokens to flat key-value pairs (without -- prefix)
+ */
+function processColorTokens(
+	colorObj: Record<string, unknown>,
+	path: string[] = [],
+): Record<string, string> {
+	const result: Record<string, string> = {};
+
+	for (const [key, value] of Object.entries(colorObj)) {
+		if (key.startsWith("$")) continue;
+
+		const currentPath = [...path, key];
+
+		if (typeof value === "object" && value !== null) {
+			const record = value as Record<string, unknown>;
+
+			if ("$value" in record) {
+				// This is a token - key without -- prefix
+				const varName = `color-${currentPath.join("-")}`;
+				const tokenValue = record.$value;
+
+				if (typeof tokenValue === "string" && tokenValue.startsWith("{")) {
+					// Alias reference - resolve to CSS var
+					let refPath = tokenValue.slice(1, -1).replace(/\./g, "-");
+					refPath = refPath.replace(/^semantic-color-/, "color-");
+					result[varName] = `var(--${refPath})`;
+				} else {
+					result[varName] = tokenValueToCSS(tokenValue);
+				}
+			} else {
+				// Nested object - recurse
+				Object.assign(result, processColorTokens(record, currentPath));
+			}
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Process surface tokens to flat key-value pairs (without -- prefix)
+ */
+function processSurfaceTokens(
+	surfaceObj: Record<string, unknown>,
+	path: string[] = [],
+): Record<string, string> {
+	const result: Record<string, string> = {};
+
+	for (const [key, value] of Object.entries(surfaceObj)) {
+		if (key.startsWith("$")) continue;
+
+		const currentPath = [...path, key];
+
+		if (typeof value === "object" && value !== null) {
+			const record = value as Record<string, unknown>;
+
+			if ("$value" in record) {
+				// This is a token
+				const tokenValue = record.$value;
+				let varName: string;
+				let cssValue: string;
+
+				// Determine variable name based on token type (without -- prefix)
+				if (currentPath[currentPath.length - 1] === "radius") {
+					// e.g., button.radius -> radius-surface-button
+					const componentName = currentPath[0];
+					varName = `radius-surface-${componentName}`;
+				} else if (currentPath[currentPath.length - 1] === "stroke") {
+					// e.g., button.stroke -> surface-button-stroke
+					const componentName = currentPath[0];
+					varName = `surface-${componentName}-stroke`;
+				} else {
+					varName = `surface-${currentPath.join("-")}`;
+				}
+
+				// Resolve value
+				if (typeof tokenValue === "string" && tokenValue.startsWith("{")) {
+					// Alias reference
+					let refPath = tokenValue.slice(1, -1).replace(/\./g, "-");
+					refPath = refPath.replace(/^primitive-radii-/, "radius-");
+					cssValue = `var(--${refPath})`;
+				} else {
+					cssValue = tokenValueToCSS(tokenValue);
+				}
+
+				result[varName] = cssValue;
+			} else {
+				// Nested object - recurse
+				Object.assign(result, processSurfaceTokens(record, currentPath));
+			}
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Deep merge two token modules
+ */
+function mergeTokenModules(
+	base: TokenModule,
+	override: TokenModule,
+): Record<string, unknown> {
+	const result: Record<string, unknown> = JSON.parse(JSON.stringify(base));
+	deepMerge(result, override as Record<string, unknown>);
+	return result;
+}
+
+/**
+ * Deep merge objects
+ */
+function deepMerge(
+	target: Record<string, unknown>,
+	source: Record<string, unknown>,
+): void {
+	for (const [key, value] of Object.entries(source)) {
+		if (
+			typeof value === "object" &&
+			value !== null &&
+			!Array.isArray(value) &&
+			typeof target[key] === "object" &&
+			target[key] !== null
+		) {
+			deepMerge(
+				target[key] as Record<string, unknown>,
+				value as Record<string, unknown>,
+			);
+		} else {
+			target[key] = value;
+		}
+	}
+}
+
+/**
+ * ThemeProvider component
+ *
+ * Applies theme tokens as CSS variables using type-safe theme names.
+ *
+ * @example
+ * ```tsx
+ * // Use default base themes
+ * <ThemeProvider>
+ *   <App />
+ * </ThemeProvider>
+ *
+ * // Use specific themes by name
+ * <ThemeProvider color="civic" surface="sharp">
+ *   <App />
+ * </ThemeProvider>
+ *
+ * // Mix and match
+ * <ThemeProvider color="institution" surface="soft">
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ */
+export function ThemeProvider({
+	color = "base",
+	surface = "base",
+	children,
+}: ThemeProviderProps) {
+	const { tokens, cssVars } = useMemo(() => {
+		const flatTokens: Record<string, string> = {};
+
+		// Get color theme (merge with base if not base)
+		const baseColorModule = colorThemes.base;
+		const colorModule = colorThemes[color];
+
+		const mergedColor =
+			color === "base"
+				? (baseColorModule as Record<string, unknown>)
+				: mergeTokenModules(baseColorModule, colorModule);
+
+		// Navigate to semantic.color
+		const colorTokens =
+			(mergedColor as { semantic?: { color?: Record<string, unknown> } })
+				?.semantic?.color ?? mergedColor;
+		Object.assign(flatTokens, processColorTokens(colorTokens));
+
+		// Get surface theme (merge with base if not base)
+		const baseSurfaceModule = surfaceThemes.base;
+		const surfaceModule = surfaceThemes[surface];
+
+		const mergedSurface =
+			surface === "base"
+				? (baseSurfaceModule as Record<string, unknown>)
+				: mergeTokenModules(baseSurfaceModule, surfaceModule);
+
+		// Navigate to semantic.surface
+		const surfaceTokens =
+			(mergedSurface as { semantic?: { surface?: Record<string, unknown> } })
+				?.semantic?.surface ?? mergedSurface;
+		Object.assign(flatTokens, processSurfaceTokens(surfaceTokens));
+
+		// Use shared utilities from tokens package
+		const nestedTokens = flatToNested(flatTokens);
+		const cssVariables = flatToCSSVars(flatTokens);
+
+		return { tokens: nestedTokens, cssVars: cssVariables };
+	}, [color, surface]);
+
+	const contextValue: ThemeContextValue = {
+		cssVars,
+		tokens,
+		colorTheme: color,
+		surfaceTheme: surface,
+	};
+
+	return (
+		<ThemeContext.Provider value={contextValue}>
+			{children}
+		</ThemeContext.Provider>
+	);
+}

package/src/theme/hooks.ts

@@ -0,0 +1,40 @@
+/**
+ * Theme Hooks
+ *
+ * React hooks for accessing theme context.
+ */
+
+import type {
+	CSSVariableMap,
+	NestedStringRecord,
+} from "@nds-design-system/tokens";
+import { useContext } from "react";
+import { ThemeContext, type ThemeContextValue } from "./ThemeProvider";
+
+/**
+ * Hook to access the theme context
+ * @throws Error if used outside of ThemeProvider
+ */
+export function useTheme(): ThemeContextValue {
+	const context = useContext(ThemeContext);
+	if (!context) {
+		throw new Error("useTheme must be used within a ThemeProvider");
+	}
+	return context;
+}
+
+/**
+ * Hook to get just the nested tokens
+ */
+export function useThemeTokens(): NestedStringRecord {
+	const { tokens } = useTheme();
+	return tokens;
+}
+
+/**
+ * Hook to get CSS variables for inline styles
+ */
+export function useCSSVars(): CSSVariableMap {
+	const { cssVars } = useTheme();
+	return cssVars;
+}

package/src/theme/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Theme Module
+ *
+ * React components and utilities for theme composition and CSS variable application.
+ */
+
+// Re-export types from tokens package for convenience
+export type {
+	APICollection,
+	CollectionDefinition,
+	ColorThemeName,
+	CSSVariableMap,
+	NestedStringRecord,
+	SurfaceThemeName,
+	ThemeComposition,
+} from "@nds-design-system/tokens";
+// Re-export theme registries for programmatic access
+export {
+	colorThemeNames,
+	colorThemes,
+	surfaceThemeNames,
+	surfaceThemes,
+} from "@nds-design-system/tokens";
+
+// Hooks
+export { useCSSVars, useTheme, useThemeTokens } from "./hooks";
+// Provider
+export {
+	ThemeContext,
+	type ThemeContextValue,
+	ThemeProvider,
+	type ThemeProviderProps,
+} from "./ThemeProvider";
+// Utilities
+export {
+	applyTheme,
+	createThemeStyle,
+	filterCSSVars,
+	getToken,
+	mergeCSSVars,
+	removeTheme,
+	toCSSVars,
+} from "./utils";

package/src/theme/utils.ts

@@ -0,0 +1,104 @@
+/**
+ * Theme Utilities
+ *
+ * Helper functions for working with theme tokens and CSS variables.
+ */
+
+import type {
+	CSSVariableMap,
+	NestedStringRecord,
+} from "@nds-design-system/tokens";
+import { nestedToCSSVars } from "@nds-design-system/tokens";
+
+/**
+ * Convert nested token object to CSS variable map
+ * @example
+ * toCSSVars({ color: { bg: { page: '#fff' } } })
+ * // Returns: { '--color-bg-page': '#fff' }
+ */
+export function toCSSVars(tokens: NestedStringRecord): CSSVariableMap {
+	return nestedToCSSVars(tokens);
+}
+
+/**
+ * Apply CSS variables to an element
+ * @example
+ * applyTheme(document.body, { '--color-bg-page': '#fff' })
+ */
+export function applyTheme(
+	element: HTMLElement,
+	cssVars: CSSVariableMap,
+): void {
+	for (const [name, value] of Object.entries(cssVars)) {
+		element.style.setProperty(name, value);
+	}
+}
+
+/**
+ * Remove CSS variables from an element
+ */
+export function removeTheme(
+	element: HTMLElement,
+	cssVars: CSSVariableMap,
+): void {
+	for (const name of Object.keys(cssVars)) {
+		element.style.removeProperty(name);
+	}
+}
+
+/**
+ * Get a specific token value from nested tokens using dot notation
+ * @example
+ * getToken({ color: { bg: { page: '#fff' } } }, 'color.bg.page')
+ * // Returns: '#fff'
+ */
+export function getToken(
+	tokens: NestedStringRecord,
+	path: string,
+): string | undefined {
+	const parts = path.split(".");
+	let current: NestedStringRecord | string = tokens;
+
+	for (const part of parts) {
+		if (typeof current === "string") return undefined;
+		current = current[part];
+		if (current === undefined) return undefined;
+	}
+
+	return typeof current === "string" ? current : undefined;
+}
+
+/**
+ * Create a style object with CSS variables for React inline styles
+ * @example
+ * <div style={createThemeStyle(cssVars)}>...</div>
+ */
+export function createThemeStyle(cssVars: CSSVariableMap): React.CSSProperties {
+	return cssVars as React.CSSProperties;
+}
+
+/**
+ * Merge multiple CSS variable maps
+ */
+export function mergeCSSVars(...maps: CSSVariableMap[]): CSSVariableMap {
+	return Object.assign({}, ...maps);
+}
+
+/**
+ * Filter CSS variables by prefix
+ * @example
+ * filterCSSVars(cssVars, '--color-')
+ * // Returns only variables starting with --color-
+ */
+export function filterCSSVars(
+	cssVars: CSSVariableMap,
+	prefix: string,
+): CSSVariableMap {
+	const result: CSSVariableMap = {};
+	for (const [name, value] of Object.entries(cssVars)) {
+		if (name.startsWith(prefix)) {
+			result[name] = value;
+		}
+	}
+	return result;
+}