@newtonedev/components 0.1.0

package/src/theme/NewtoneProvider.tsx

@@ -0,0 +1,65 @@
+import React, { createContext, useState, useMemo, useContext } from 'react';
+import type { NewtoneThemeConfig, NewtoneThemeContext, ColorMode, ThemeName } from './types';
+import { DEFAULT_THEME_CONFIG } from './defaults';
+
+const ThemeContext = createContext<NewtoneThemeContext | null>(null);
+
+export interface NewtoneProviderProps {
+  readonly config?: NewtoneThemeConfig;
+  readonly initialMode?: ColorMode;
+  readonly initialTheme?: ThemeName;
+  readonly children: React.ReactNode;
+}
+
+/**
+ * NewtoneProvider - Provides theme context to all Newtone components
+ *
+ * Wrap your app with this provider to enable theme and mode switching.
+ *
+ * @example
+ * ```tsx
+ * <NewtoneProvider initialMode="light" initialTheme="neutral">
+ *   <App />
+ * </NewtoneProvider>
+ * ```
+ */
+export function NewtoneProvider({
+  config = DEFAULT_THEME_CONFIG,
+  initialMode = 'light',
+  initialTheme = 'neutral',
+  children,
+}: NewtoneProviderProps) {
+  const [mode, setMode] = useState<ColorMode>(initialMode);
+  const [theme, setTheme] = useState<ThemeName>(initialTheme);
+
+  const value = useMemo(
+    () => ({
+      config,
+      mode,
+      theme,
+      setMode,
+      setTheme,
+    }),
+    [config, mode, theme]
+  );
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+/**
+ * useNewtoneTheme - Hook to access theme context
+ *
+ * Must be used within a NewtoneProvider.
+ *
+ * @example
+ * ```tsx
+ * const { mode, theme, setMode, setTheme } = useNewtoneTheme();
+ * ```
+ */
+export function useNewtoneTheme(): NewtoneThemeContext {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error('useNewtoneTheme must be used within NewtoneProvider');
+  }
+  return context;
+}

package/src/theme/defaults.ts

@@ -0,0 +1,42 @@
+import type { NewtoneThemeConfig } from './types';
+import {
+  DEFAULT_NEUTRAL_HUE,
+  DEFAULT_NEUTRAL_SATURATION,
+  DEFAULT_ACCENT_HUE,
+  DEFAULT_ACCENT_SATURATION,
+  DEFAULT_SUCCESS_HUE,
+  DEFAULT_SUCCESS_SATURATION,
+  DEFAULT_WARNING_HUE,
+  DEFAULT_WARNING_SATURATION,
+  DEFAULT_ERROR_HUE,
+  DEFAULT_ERROR_SATURATION,
+} from 'newtone';
+
+/**
+ * Default theme configuration matching playground defaults.
+ * Palettes: [0] Neutral, [1] Accent, [2] Success, [3] Warning, [4] Error
+ */
+export const DEFAULT_THEME_CONFIG: NewtoneThemeConfig = {
+  colorSystem: {
+    dynamicRange: {
+      lightest: 1,
+      darkest: 1,
+    },
+    palettes: [
+      { hue: DEFAULT_NEUTRAL_HUE, saturation: DEFAULT_NEUTRAL_SATURATION },
+      { hue: DEFAULT_ACCENT_HUE, saturation: DEFAULT_ACCENT_SATURATION },
+      { hue: DEFAULT_SUCCESS_HUE, saturation: DEFAULT_SUCCESS_SATURATION },
+      { hue: DEFAULT_WARNING_HUE, saturation: DEFAULT_WARNING_SATURATION },
+      { hue: DEFAULT_ERROR_HUE, saturation: DEFAULT_ERROR_SATURATION },
+    ],
+  },
+  themes: {
+    neutral: { paletteIndex: 0, lightModeNv: 0.95, darkModeNv: 0.1 },
+    primary: { paletteIndex: 1, lightModeNv: 0.95, darkModeNv: 0.1 },
+    secondary: { paletteIndex: 1, lightModeNv: 0.85, darkModeNv: 0.15 },
+    strong: { paletteIndex: 0, lightModeNv: 0.1, darkModeNv: 0.95 },
+  },
+  elevation: {
+    offsets: [-0.02, 0, 0.04], // [sunken, default, elevated]
+  },
+};

package/src/theme/types.ts

@@ -0,0 +1,62 @@
+import type { DynamicRange, PaletteConfig } from 'newtone';
+
+/**
+ * Color mode: light or dark
+ */
+export type ColorMode = 'light' | 'dark';
+
+/**
+ * Theme names for different UI contexts
+ */
+export type ThemeName = 'neutral' | 'primary' | 'secondary' | 'strong';
+
+/**
+ * Elevation levels for surfaces
+ * 0 = sunken, 1 = default, 2 = elevated
+ */
+export type ElevationLevel = 0 | 1 | 2;
+
+/**
+ * Theme mapping: which palette and normalizedValue to use for backgrounds/text
+ * Based on playground theme preview logic
+ */
+export interface ThemeMapping {
+  readonly paletteIndex: number;    // Index into ColorSystemConfig.palettes
+  readonly lightModeNv: number;     // normalizedValue for light mode background
+  readonly darkModeNv: number;      // normalizedValue for dark mode background
+}
+
+/**
+ * Complete color system configuration
+ */
+export interface ColorSystemConfig {
+  readonly dynamicRange: DynamicRange;
+  readonly palettes: ReadonlyArray<PaletteConfig>;
+}
+
+/**
+ * Newtone theme configuration
+ */
+export interface NewtoneThemeConfig {
+  readonly colorSystem: ColorSystemConfig;
+  readonly themes: {
+    readonly neutral: ThemeMapping;
+    readonly primary: ThemeMapping;
+    readonly secondary: ThemeMapping;
+    readonly strong: ThemeMapping;
+  };
+  readonly elevation: {
+    readonly offsets: readonly [number, number, number]; // NV offsets for [sunken, default, elevated]
+  };
+}
+
+/**
+ * Current theme context state
+ */
+export interface NewtoneThemeContext {
+  readonly config: NewtoneThemeConfig;
+  readonly mode: ColorMode;
+  readonly theme: ThemeName;
+  readonly setMode: (mode: ColorMode) => void;
+  readonly setTheme: (theme: ThemeName) => void;
+}

package/src/tokens/computeTokens.ts

@@ -0,0 +1,217 @@
+import { getColor, getColorByContrast } from 'newtone';
+import type { ColorSystemConfig, ColorMode, ThemeMapping, ElevationLevel } from '../theme/types';
+import type { ResolvedTokens } from './types';
+
+/**
+ * Compute design tokens for a specific mode/theme/elevation combination.
+ *
+ * This function calls the Newtone engine to generate all necessary color tokens
+ * based on the current theme context. All colors are computed on-demand using
+ * the pure functions from the engine.
+ *
+ * @param config - Complete color system configuration (dynamic range + palettes)
+ * @param mode - Current color mode ('light' or 'dark')
+ * @param themeMapping - Theme configuration (which palette and NV to use)
+ * @param elevation - Elevation level (0=sunken, 1=default, 2=elevated)
+ * @param elevationOffsets - NV offsets for each elevation level
+ * @returns Resolved design tokens with all necessary colors
+ *
+ * @example
+ * ```typescript
+ * const tokens = computeTokens(
+ *   config.colorSystem,
+ *   'light',
+ *   config.themes.neutral,
+ *   1,
+ *   config.elevation.offsets
+ * );
+ * console.log(tokens.background.srgb); // { r: 0.95, g: 0.95, b: 0.95 }
+ * ```
+ */
+export function computeTokens(
+  config: ColorSystemConfig,
+  mode: ColorMode,
+  themeMapping: ThemeMapping,
+  elevation: ElevationLevel,
+  elevationOffsets: readonly [number, number, number]
+): ResolvedTokens {
+  const { dynamicRange, palettes } = config;
+  const palette = palettes[themeMapping.paletteIndex];
+
+  if (!palette) {
+    throw new Error(`Palette at index ${themeMapping.paletteIndex} not found`);
+  }
+
+  // Determine base NV for this mode + elevation
+  const baseNv = mode === 'light' ? themeMapping.lightModeNv : themeMapping.darkModeNv;
+  const elevationOffset = elevationOffsets[elevation];
+  const backgroundNv = Math.max(0, Math.min(1, baseNv + elevationOffset));
+
+  // Derive effective text mode from actual background lightness.
+  // This handles inverted themes (e.g., strong: dark bg in light mode)
+  // where the mode flag doesn't match the background's visual lightness.
+  const effectiveTextMode: ColorMode = backgroundNv >= 0.5 ? 'light' : 'dark';
+
+  // Compute background colors for current elevation
+  const background = getColor(
+    palette.hue,
+    palette.saturation,
+    dynamicRange,
+    backgroundNv,
+    palette.desaturation,
+    palette.paletteHueGrading
+  );
+
+  // Compute elevated surface (always at elevation 2 offset)
+  const elevatedNv = Math.max(0, Math.min(1, baseNv + elevationOffsets[2]));
+  const backgroundElevated = getColor(
+    palette.hue,
+    palette.saturation,
+    dynamicRange,
+    elevatedNv,
+    palette.desaturation,
+    palette.paletteHueGrading
+  );
+
+  // Compute sunken surface (always at elevation 0 offset)
+  const sunkenNv = Math.max(0, Math.min(1, baseNv + elevationOffsets[0]));
+  const backgroundSunken = getColor(
+    palette.hue,
+    palette.saturation,
+    dynamicRange,
+    sunkenNv,
+    palette.desaturation,
+    palette.paletteHueGrading
+  );
+
+  // Compute text colors with WCAG contrast requirements
+  // Primary text: WCAG AA (4.5:1 for body text)
+  const textPrimary = getColorByContrast(
+    palette.hue,
+    palette.saturation,
+    dynamicRange,
+    4.5,
+    effectiveTextMode,
+    palette.desaturation,
+    palette.paletteHueGrading
+  );
+
+  // Secondary text: Lower contrast (3.0:1 for captions)
+  const textSecondary = getColorByContrast(
+    palette.hue,
+    palette.saturation,
+    dynamicRange,
+    3.0,
+    effectiveTextMode,
+    palette.desaturation,
+    palette.paletteHueGrading
+  );
+
+  // Interactive colors: Use accent palette (index 1)
+  const accentPalette = palettes[1];
+
+  if (!accentPalette) {
+    throw new Error('Accent palette (index 1) not found');
+  }
+
+  // Interactive base: WCAG AA contrast against current background
+  const interactive = getColorByContrast(
+    accentPalette.hue,
+    accentPalette.saturation,
+    dynamicRange,
+    4.5,
+    effectiveTextMode,
+    accentPalette.desaturation,
+    accentPalette.paletteHueGrading
+  );
+
+  // Hover/active states: Shift NV slightly from interactive base
+  // In light mode (light bg), go darker; in dark mode (dark bg), go lighter
+  const interactiveNv = effectiveTextMode === 'light' ? 0.3 : 0.7;
+
+  const interactiveHover = getColor(
+    accentPalette.hue,
+    accentPalette.saturation,
+    dynamicRange,
+    interactiveNv + (effectiveTextMode === 'light' ? -0.05 : 0.05),
+    accentPalette.desaturation,
+    accentPalette.paletteHueGrading
+  );
+
+  const interactiveActive = getColor(
+    accentPalette.hue,
+    accentPalette.saturation,
+    dynamicRange,
+    interactiveNv + (effectiveTextMode === 'light' ? -0.1 : 0.1),
+    accentPalette.desaturation,
+    accentPalette.paletteHueGrading
+  );
+
+  // Border: Subtle contrast from background
+  const borderNv = effectiveTextMode === 'light' ? backgroundNv - 0.1 : backgroundNv + 0.1;
+  const border = getColor(
+    palette.hue,
+    palette.saturation,
+    dynamicRange,
+    Math.max(0, Math.min(1, borderNv)),
+    palette.desaturation,
+    palette.paletteHueGrading
+  );
+
+  // Semantic status colors: success (palette 2), warning (palette 3), error (palette 4)
+  // Each computed at WCAG AA contrast against the mode background, same as interactive
+  const successPalette = palettes[2];
+  const warningPalette = palettes[3];
+  const errorPalette = palettes[4];
+
+  const success = successPalette
+    ? getColorByContrast(
+        successPalette.hue,
+        successPalette.saturation,
+        dynamicRange,
+        4.5,
+        effectiveTextMode,
+        successPalette.desaturation,
+        successPalette.paletteHueGrading
+      )
+    : interactive; // Fallback to interactive if palette missing
+
+  const warning = warningPalette
+    ? getColorByContrast(
+        warningPalette.hue,
+        warningPalette.saturation,
+        dynamicRange,
+        4.5,
+        effectiveTextMode,
+        warningPalette.desaturation,
+        warningPalette.paletteHueGrading
+      )
+    : interactive;
+
+  const error = errorPalette
+    ? getColorByContrast(
+        errorPalette.hue,
+        errorPalette.saturation,
+        dynamicRange,
+        4.5,
+        effectiveTextMode,
+        errorPalette.desaturation,
+        errorPalette.paletteHueGrading
+      )
+    : interactive;
+
+  return {
+    background,
+    backgroundElevated,
+    backgroundSunken,
+    textPrimary,
+    textSecondary,
+    interactive,
+    interactiveHover,
+    interactiveActive,
+    border,
+    success,
+    warning,
+    error,
+  };
+}

package/src/tokens/types.ts

@@ -0,0 +1,31 @@
+import type { ColorResult } from 'newtone';
+
+/**
+ * Resolved design tokens for a specific mode/theme/elevation combination
+ */
+export interface ResolvedTokens {
+  /** Background color for the current surface */
+  readonly background: ColorResult;
+  /** Background color for elevated surfaces (cards, modals) */
+  readonly backgroundElevated: ColorResult;
+  /** Background color for sunken surfaces (input fields, wells) */
+  readonly backgroundSunken: ColorResult;
+  /** Primary text color (high contrast for body text) */
+  readonly textPrimary: ColorResult;
+  /** Secondary text color (lower contrast for captions, labels) */
+  readonly textSecondary: ColorResult;
+  /** Interactive element color (buttons, links) */
+  readonly interactive: ColorResult;
+  /** Interactive element hover state */
+  readonly interactiveHover: ColorResult;
+  /** Interactive element active/pressed state */
+  readonly interactiveActive: ColorResult;
+  /** Border color for subtle separators */
+  readonly border: ColorResult;
+  /** Success state color (from success palette, index 2) */
+  readonly success: ColorResult;
+  /** Warning state color (from warning palette, index 3) */
+  readonly warning: ColorResult;
+  /** Error/destructive state color (from error palette, index 4) */
+  readonly error: ColorResult;
+}

package/src/tokens/useTokens.ts

@@ -0,0 +1,42 @@
+import { useMemo } from 'react';
+import { useNewtoneTheme } from '../theme/NewtoneProvider';
+import { computeTokens } from './computeTokens';
+import type { ElevationLevel } from '../theme/types';
+import type { ResolvedTokens } from './types';
+
+/**
+ * Hook to compute design tokens for the current theme/mode/elevation.
+ *
+ * This hook automatically recomputes tokens when the theme configuration,
+ * mode, theme name, or elevation changes. Results are memoized to avoid
+ * unnecessary computation.
+ *
+ * @param elevation - Elevation level (0=sunken, 1=default, 2=elevated)
+ * @returns Resolved design tokens with all necessary colors
+ *
+ * @example
+ * ```tsx
+ * function Button() {
+ *   const tokens = useTokens(1); // Default elevation
+ *   return (
+ *     <button style={{ backgroundColor: srgbToHex(tokens.interactive.srgb) }}>
+ *       Click me
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function useTokens(elevation: ElevationLevel = 1): ResolvedTokens {
+  const { config, mode, theme } = useNewtoneTheme();
+
+  return useMemo(() => {
+    const themeMapping = config.themes[theme];
+    return computeTokens(
+      config.colorSystem,
+      mode,
+      themeMapping,
+      elevation,
+      config.elevation.offsets
+    );
+  }, [config, mode, theme, elevation]);
+}