@newtonedev/configurator 0.1.0

package/src/bridge/toCSS.ts

@@ -0,0 +1,43 @@
+import type { ConfiguratorState } from '../types';
+import type { ColorMode } from '@newtonedev/components';
+import { computeTokens } from '@newtonedev/components';
+import { srgbToHex } from 'newtone';
+import { toThemeConfig } from './toThemeConfig';
+
+/**
+ * Generate CSS custom properties for both light and dark modes.
+ * Computes all 12 design tokens for the neutral theme at default elevation.
+ */
+export function toCSS(state: ConfiguratorState): string {
+  const config = toThemeConfig(state);
+  const modes: readonly ColorMode[] = ['light', 'dark'];
+
+  let css = '';
+  for (const mode of modes) {
+    const tokens = computeTokens(
+      config.colorSystem,
+      mode,
+      config.themes.neutral,
+      1,
+      config.elevation.offsets,
+    );
+
+    const selector = mode === 'light' ? ':root' : '[data-theme="dark"]';
+    css += `${selector} {\n`;
+    css += `  --newtone-background: ${srgbToHex(tokens.background.srgb)};\n`;
+    css += `  --newtone-background-elevated: ${srgbToHex(tokens.backgroundElevated.srgb)};\n`;
+    css += `  --newtone-background-sunken: ${srgbToHex(tokens.backgroundSunken.srgb)};\n`;
+    css += `  --newtone-text-primary: ${srgbToHex(tokens.textPrimary.srgb)};\n`;
+    css += `  --newtone-text-secondary: ${srgbToHex(tokens.textSecondary.srgb)};\n`;
+    css += `  --newtone-interactive: ${srgbToHex(tokens.interactive.srgb)};\n`;
+    css += `  --newtone-interactive-hover: ${srgbToHex(tokens.interactiveHover.srgb)};\n`;
+    css += `  --newtone-interactive-active: ${srgbToHex(tokens.interactiveActive.srgb)};\n`;
+    css += `  --newtone-border: ${srgbToHex(tokens.border.srgb)};\n`;
+    css += `  --newtone-success: ${srgbToHex(tokens.success.srgb)};\n`;
+    css += `  --newtone-warning: ${srgbToHex(tokens.warning.srgb)};\n`;
+    css += `  --newtone-error: ${srgbToHex(tokens.error.srgb)};\n`;
+    css += `}\n\n`;
+  }
+
+  return css;
+}

package/src/bridge/toJSON.ts

@@ -0,0 +1,24 @@
+import type { ConfiguratorState } from '../types';
+import type { NewtoneThemeConfig } from '@newtonedev/components';
+import { toThemeConfig } from './toThemeConfig';
+
+/** Serializable configurator export format */
+export interface ConfiguratorExport {
+  readonly version: '1.0';
+  readonly configuratorState: ConfiguratorState;
+  readonly themeConfig: NewtoneThemeConfig;
+}
+
+/**
+ * Export the configurator state as a JSON string.
+ * Includes both the human-readable state (for round-tripping)
+ * and the engine-ready theme config.
+ */
+export function toJSON(state: ConfiguratorState): string {
+  const output: ConfiguratorExport = {
+    version: '1.0',
+    configuratorState: state,
+    themeConfig: toThemeConfig(state),
+  };
+  return JSON.stringify(output, null, 2);
+}

package/src/bridge/toThemeConfig.ts

@@ -0,0 +1,58 @@
+import type { ConfiguratorState } from '../types';
+import type { NewtoneThemeConfig } from '@newtonedev/components';
+import type { PaletteConfig, DynamicRange, HueGrading, HueGradingEndpoint } from 'newtone';
+import { traditionalHueToOklch } from '../hue-conversion';
+
+/**
+ * Convert configurator state (traditional hues, human-readable controls)
+ * to a NewtoneThemeConfig (OKLCH hues, engine-ready format).
+ */
+export function toThemeConfig(state: ConfiguratorState): NewtoneThemeConfig {
+  const palettes: readonly PaletteConfig[] = state.palettes.map(p => {
+    const oklchHue = traditionalHueToOklch(p.hue);
+
+    const desaturation = p.desaturationStrength !== 'none'
+      ? { direction: p.desaturationDirection, strength: p.desaturationStrength } as const
+      : undefined;
+
+    const paletteHueGrading = p.hueGradeStrength !== 'none'
+      ? {
+          hue: traditionalHueToOklch(p.hueGradeHue),
+          strength: p.hueGradeStrength,
+          direction: p.hueGradeDirection,
+        } as const
+      : undefined;
+
+    return { hue: oklchHue, saturation: p.saturation, desaturation, paletteHueGrading };
+  });
+
+  // Build global hue grading
+  const light: HueGradingEndpoint | undefined = state.globalHueGrading.light.strength !== 'none'
+    ? { hue: traditionalHueToOklch(state.globalHueGrading.light.hue), strength: state.globalHueGrading.light.strength }
+    : undefined;
+
+  const dark: HueGradingEndpoint | undefined = state.globalHueGrading.dark.strength !== 'none'
+    ? { hue: traditionalHueToOklch(state.globalHueGrading.dark.hue), strength: state.globalHueGrading.dark.strength }
+    : undefined;
+
+  const hueGrading: HueGrading | undefined = (light || dark) ? { light, dark } : undefined;
+
+  const dynamicRange: DynamicRange = {
+    lightest: state.dynamicRange.lightest,
+    darkest: state.dynamicRange.darkest,
+    ...(hueGrading ? { hueGrading } : {}),
+  };
+
+  return {
+    colorSystem: { dynamicRange, palettes },
+    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] as const,
+    },
+  };
+}

package/src/constants.ts

@@ -0,0 +1,16 @@
+/**
+ * Hue ranges for semantic palettes (traditional HSL hues).
+ * Indices 0 (Neutral) and 1 (Accent) are unconstrained.
+ *
+ * For wrapping ranges (e.g. Error crosses 0°), max exceeds 359.
+ * The HueSlider component normalizes values to [0, 359] via % 360.
+ *
+ * Gaps between ranges prevent adjacent semantics from overlapping:
+ * - 15–25: gap between Error (reds) and Warning (yellows)
+ * - 55–80: gap between Warning and Success (greens)
+ */
+export const SEMANTIC_HUE_RANGES: Readonly<Record<number, { readonly min: number; readonly max: number }>> = {
+  2: { min: 80, max: 160 },    // Success (greens)
+  3: { min: 25, max: 55 },     // Warning (yellow/orange)
+  4: { min: 345, max: 375 },   // Error (reds, wraps 0°)
+};

package/src/hooks/useConfigurator.ts

@@ -0,0 +1,30 @@
+import { useReducer, useCallback, useMemo } from 'react';
+import type { ConfiguratorState } from '../types';
+import type { ConfiguratorAction } from '../state/actions';
+import type { NewtoneThemeConfig } from '@newtonedev/components';
+import { configuratorReducer } from '../state/reducer';
+import { DEFAULT_CONFIGURATOR_STATE } from '../state/defaults';
+import { toThemeConfig } from '../bridge/toThemeConfig';
+
+export interface UseConfiguratorResult {
+  readonly state: ConfiguratorState;
+  readonly dispatch: (action: ConfiguratorAction) => void;
+  readonly themeConfig: NewtoneThemeConfig;
+  readonly reset: () => void;
+}
+
+export function useConfigurator(
+  initialState?: Partial<ConfiguratorState>,
+): UseConfiguratorResult {
+  const mergedInitial: ConfiguratorState = initialState
+    ? { ...DEFAULT_CONFIGURATOR_STATE, ...initialState }
+    : DEFAULT_CONFIGURATOR_STATE;
+
+  const [state, dispatch] = useReducer(configuratorReducer, mergedInitial);
+
+  const themeConfig = useMemo(() => toThemeConfig(state), [state]);
+
+  const reset = useCallback(() => dispatch({ type: 'RESET' }), []);
+
+  return { state, dispatch, themeConfig, reset };
+}

package/src/hooks/usePreviewColors.ts

@@ -0,0 +1,40 @@
+import { useMemo } from 'react';
+import { generatePreview } from 'newtone';
+import type { ColorResult, DynamicRange } from 'newtone';
+import type { ConfiguratorState } from '../types';
+import { traditionalHueToOklch } from '../hue-conversion';
+
+const PREVIEW_STEPS = 26;
+
+/**
+ * Compute preview swatches for all palettes.
+ * Returns an array of arrays: one preview row per palette.
+ */
+export function usePreviewColors(state: ConfiguratorState): readonly (readonly ColorResult[])[] {
+  return useMemo(() => {
+    const light = state.globalHueGrading.light.strength !== 'none'
+      ? { hue: traditionalHueToOklch(state.globalHueGrading.light.hue), strength: state.globalHueGrading.light.strength }
+      : undefined;
+    const dark = state.globalHueGrading.dark.strength !== 'none'
+      ? { hue: traditionalHueToOklch(state.globalHueGrading.dark.hue), strength: state.globalHueGrading.dark.strength }
+      : undefined;
+    const hueGrading = (light || dark) ? { light, dark } : undefined;
+
+    const dynamicRange: DynamicRange = {
+      lightest: state.dynamicRange.lightest,
+      darkest: state.dynamicRange.darkest,
+      ...(hueGrading ? { hueGrading } : {}),
+    };
+
+    return state.palettes.map(p => {
+      const oklchHue = traditionalHueToOklch(p.hue);
+      const desat = p.desaturationStrength !== 'none'
+        ? { direction: p.desaturationDirection, strength: p.desaturationStrength } as const
+        : undefined;
+      const phg = p.hueGradeStrength !== 'none'
+        ? { hue: traditionalHueToOklch(p.hueGradeHue), strength: p.hueGradeStrength, direction: p.hueGradeDirection } as const
+        : undefined;
+      return generatePreview(oklchHue, p.saturation, dynamicRange, PREVIEW_STEPS, desat, phg);
+    });
+  }, [state]);
+}

package/src/hue-conversion.ts

@@ -0,0 +1,25 @@
+import { srgbToOklch } from 'newtone';
+import type { Srgb } from 'newtone';
+
+/**
+ * Convert a traditional HSL color wheel hue (0-359) to its equivalent OKLCH hue.
+ *
+ * Uses the fully saturated HSL color (S=1, L=0.5) at the given hue,
+ * converts to sRGB, then extracts the OKLCH hue component.
+ *
+ * Traditional hues: 0=red, 60=yellow, 120=green, 180=cyan, 240=blue, 300=magenta.
+ */
+export function traditionalHueToOklch(hue: number): number {
+  const h = ((hue % 360) + 360) % 360;
+  const x = 1 - Math.abs((h / 60) % 2 - 1);
+
+  let r: number, g: number, b: number;
+  if (h < 60)       { r = 1; g = x; b = 0; }
+  else if (h < 120) { r = x; g = 1; b = 0; }
+  else if (h < 180) { r = 0; g = 1; b = x; }
+  else if (h < 240) { r = 0; g = x; b = 1; }
+  else if (h < 300) { r = x; g = 0; b = 1; }
+  else              { r = 1; g = 0; b = x; }
+
+  return srgbToOklch({ r, g, b } as Srgb).h;
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+// Main component
+export { Configurator } from './Configurator';
+export type { ConfiguratorProps } from './Configurator.types';
+
+// State types
+export type { ConfiguratorState, PaletteState, HueGradingEndpointState } from './types';
+export type { ConfiguratorAction } from './state/actions';
+
+// Bridge functions (for headless usage)
+export { toThemeConfig } from './bridge/toThemeConfig';
+export { toCSS } from './bridge/toCSS';
+export { toJSON } from './bridge/toJSON';
+export type { ConfiguratorExport } from './bridge/toJSON';
+
+// Hue conversion utility
+export { traditionalHueToOklch } from './hue-conversion';
+
+// Defaults
+export { DEFAULT_CONFIGURATOR_STATE } from './state/defaults';
+
+// Hooks (for custom configurator UIs)
+export { useConfigurator } from './hooks/useConfigurator';
+export type { UseConfiguratorResult } from './hooks/useConfigurator';
+export { usePreviewColors } from './hooks/usePreviewColors';

package/src/panels/CanvasPanel.tsx

@@ -0,0 +1,90 @@
+import React from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { Card, useTokens } from '@newtonedev/components';
+import { srgbToHex } from 'newtone';
+import type { ColorResult } from 'newtone';
+import type { ConfiguratorState } from '../types';
+import { usePreviewColors } from '../hooks/usePreviewColors';
+
+interface CanvasPanelProps {
+  readonly state: ConfiguratorState;
+}
+
+function SwatchRow({ name, colors }: { readonly name: string; readonly colors: readonly ColorResult[] }) {
+  const tokens = useTokens(1);
+
+  return (
+    <View style={styles.paletteRow}>
+      <Text style={[styles.label, { color: srgbToHex(tokens.textSecondary.srgb) }]}>
+        {name}
+      </Text>
+      <View style={styles.swatches}>
+        {colors.map((color, i) => {
+          const hex = srgbToHex(color.srgb);
+          const textColor = color.oklch.L > 0.6 ? '#000000' : '#ffffff';
+          return (
+            <View
+              key={i}
+              style={[styles.swatch, { backgroundColor: hex }]}
+            >
+              <Text style={[styles.swatchText, { color: textColor }]}>
+                {hex}
+              </Text>
+            </View>
+          );
+        })}
+      </View>
+    </View>
+  );
+}
+
+export function CanvasPanel({ state }: CanvasPanelProps) {
+  const previews = usePreviewColors(state);
+  const tokens = useTokens(1);
+
+  return (
+    <Card elevation={0} style={styles.container}>
+      <Text style={[styles.title, { color: srgbToHex(tokens.textPrimary.srgb) }]}>
+        Color Swatches
+      </Text>
+      {state.palettes.map((palette, i) => (
+        <SwatchRow key={i} name={palette.name} colors={previews[i]} />
+      ))}
+    </Card>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    gap: 12,
+    marginBottom: 12,
+  },
+  title: {
+    fontSize: 16,
+    fontWeight: '700',
+  },
+  paletteRow: {
+    gap: 4,
+  },
+  label: {
+    fontSize: 12,
+    fontWeight: '600',
+  },
+  swatches: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    gap: 2,
+  },
+  swatch: {
+    width: 56,
+    height: 32,
+    borderRadius: 4,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  swatchText: {
+    fontSize: 7,
+    fontWeight: '500',
+    fontFamily: 'monospace',
+  },
+});

package/src/panels/ExportPanel.tsx

@@ -0,0 +1,95 @@
+import React, { useMemo, useState, useCallback } from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { Card, Button, useTokens } from '@newtonedev/components';
+import { srgbToHex } from 'newtone';
+import type { ConfiguratorState } from '../types';
+import { toCSS } from '../bridge/toCSS';
+import { toJSON } from '../bridge/toJSON';
+
+interface ExportPanelProps {
+  readonly state: ConfiguratorState;
+}
+
+type ExportFormat = 'css' | 'json';
+
+export function ExportPanel({ state }: ExportPanelProps) {
+  const tokens = useTokens(1);
+  const [format, setFormat] = useState<ExportFormat>('css');
+  const [copied, setCopied] = useState(false);
+
+  const output = useMemo(() => {
+    return format === 'css' ? toCSS(state) : toJSON(state);
+  }, [state, format]);
+
+  const handleCopy = useCallback(() => {
+    if (typeof navigator !== 'undefined' && navigator.clipboard) {
+      navigator.clipboard.writeText(output).then(() => {
+        setCopied(true);
+        setTimeout(() => setCopied(false), 2000);
+      });
+    }
+  }, [output]);
+
+  return (
+    <Card elevation={1} style={styles.container}>
+      <Text style={[styles.title, { color: srgbToHex(tokens.textPrimary.srgb) }]}>
+        Export
+      </Text>
+
+      <View style={styles.tabs}>
+        <Button
+          variant={format === 'css' ? 'primary' : 'ghost'}
+          size="sm"
+          onPress={() => setFormat('css')}
+        >
+          CSS Variables
+        </Button>
+        <Button
+          variant={format === 'json' ? 'primary' : 'ghost'}
+          size="sm"
+          onPress={() => setFormat('json')}
+        >
+          JSON
+        </Button>
+        <Button variant="outline" size="sm" onPress={handleCopy}>
+          {copied ? 'Copied!' : 'Copy'}
+        </Button>
+      </View>
+
+      <View style={[styles.codeBlock, { backgroundColor: srgbToHex(tokens.backgroundSunken.srgb) }]}>
+        <Text
+          style={[styles.code, { color: srgbToHex(tokens.textPrimary.srgb) }]}
+          selectable
+        >
+          {output}
+        </Text>
+      </View>
+    </Card>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    gap: 12,
+    marginBottom: 12,
+  },
+  title: {
+    fontSize: 16,
+    fontWeight: '700',
+  },
+  tabs: {
+    flexDirection: 'row',
+    gap: 8,
+  },
+  codeBlock: {
+    borderRadius: 6,
+    padding: 12,
+    maxHeight: 300,
+    overflow: 'scroll' as unknown as 'visible',
+  },
+  code: {
+    fontSize: 11,
+    fontFamily: 'monospace',
+    lineHeight: 16,
+  },
+});

package/src/panels/GlobalPanel.tsx

@@ -0,0 +1,126 @@
+import React from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { Card, Slider, Select, HueSlider, useTokens } from '@newtonedev/components';
+import { srgbToHex } from 'newtone';
+import type { ConfiguratorState } from '../types';
+import type { ConfiguratorAction } from '../state/actions';
+import type { HueGradingStrength } from 'newtone';
+
+const STRENGTH_OPTIONS = [
+  { label: 'None', value: 'none' },
+  { label: 'Low', value: 'low' },
+  { label: 'Medium', value: 'medium' },
+  { label: 'Hard', value: 'hard' },
+];
+
+interface GlobalPanelProps {
+  readonly state: ConfiguratorState;
+  readonly dispatch: (action: ConfiguratorAction) => void;
+}
+
+export function GlobalPanel({ state, dispatch }: GlobalPanelProps) {
+  const tokens = useTokens(1);
+
+  return (
+    <Card elevation={1} style={styles.container}>
+      <Text style={[styles.title, { color: srgbToHex(tokens.textPrimary.srgb) }]}>
+        Dynamic Range
+      </Text>
+
+      <View style={styles.row}>
+        <View style={styles.flex}>
+          <Slider
+            value={Math.round(state.dynamicRange.lightest * 100)}
+            onValueChange={(v) => dispatch({ type: 'SET_LIGHTEST', value: v / 100 })}
+            min={0}
+            max={100}
+            label="Lightest"
+            showValue
+          />
+        </View>
+        <View style={styles.flex}>
+          <Slider
+            value={Math.round(state.dynamicRange.darkest * 100)}
+            onValueChange={(v) => dispatch({ type: 'SET_DARKEST', value: v / 100 })}
+            min={0}
+            max={100}
+            label="Darkest"
+            showValue
+          />
+        </View>
+      </View>
+
+      <Text style={[styles.subtitle, { color: srgbToHex(tokens.textSecondary.srgb) }]}>
+        Global Hue Grading — Light End
+      </Text>
+
+      <View style={styles.row}>
+        <View style={styles.flex}>
+          <Select
+            options={STRENGTH_OPTIONS}
+            value={state.globalHueGrading.light.strength}
+            onValueChange={(s) => dispatch({ type: 'SET_GLOBAL_GRADE_LIGHT_STRENGTH', strength: s as HueGradingStrength })}
+            label="Strength"
+          />
+        </View>
+        {state.globalHueGrading.light.strength !== 'none' && (
+          <View style={styles.flex}>
+            <HueSlider
+              value={state.globalHueGrading.light.hue}
+              onValueChange={(hue) => dispatch({ type: 'SET_GLOBAL_GRADE_LIGHT_HUE', hue })}
+              label="Target Hue"
+              showValue
+            />
+          </View>
+        )}
+      </View>
+
+      <Text style={[styles.subtitle, { color: srgbToHex(tokens.textSecondary.srgb) }]}>
+        Global Hue Grading — Dark End
+      </Text>
+
+      <View style={styles.row}>
+        <View style={styles.flex}>
+          <Select
+            options={STRENGTH_OPTIONS}
+            value={state.globalHueGrading.dark.strength}
+            onValueChange={(s) => dispatch({ type: 'SET_GLOBAL_GRADE_DARK_STRENGTH', strength: s as HueGradingStrength })}
+            label="Strength"
+          />
+        </View>
+        {state.globalHueGrading.dark.strength !== 'none' && (
+          <View style={styles.flex}>
+            <HueSlider
+              value={state.globalHueGrading.dark.hue}
+              onValueChange={(hue) => dispatch({ type: 'SET_GLOBAL_GRADE_DARK_HUE', hue })}
+              label="Target Hue"
+              showValue
+            />
+          </View>
+        )}
+      </View>
+    </Card>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    gap: 12,
+  },
+  title: {
+    fontSize: 16,
+    fontWeight: '700',
+  },
+  subtitle: {
+    fontSize: 13,
+    fontWeight: '600',
+    marginTop: 4,
+  },
+  row: {
+    flexDirection: 'row',
+    gap: 12,
+  },
+  flex: {
+    flex: 1,
+  },
+});