@snowcone-app/ui 0.1.42 → 0.2.0

package/src/themes/getThemeStyles.ts

@@ -0,0 +1,454 @@
+/**
+ * Get Theme Styles
+ *
+ * Generates inline CSS styles (as a Record) from a theme configuration.
+ * This is useful for isolated previews where you can't set CSS classes
+ * on the document root (like LivePreview iframes or sandboxed components).
+ *
+ * OKLCH-BASED COLOR GENERATION:
+ * -----------------------------
+ * When an OKLCH theme preset is available, colors are generated using OKLCH
+ * color space for consistent contrast ratios and mathematically correct
+ * color relationships.
+ *
+ * @example
+ * ```tsx
+ * const styles = getThemeStyles(currentTheme);
+ * return <div style={styles}>{children}</div>;
+ * ```
+ */
+
+import type { ThemeConfig, RadiusConfig, RadiusPresetId, RadiusSize } from './types';
+import { RADIUS_PRESETS } from './types';
+import { getOklchThemeStyles } from './oklch-theme';
+import { findOklchTheme } from './presets';
+
+/**
+ * Primitive radius tokens (CSS variable values)
+ */
+const RADIUS_VALUES: Record<RadiusSize, string> = {
+  none: '0',
+  sm: '2px',
+  md: '4px',
+  lg: '6px',
+  xl: '8px',
+  '2xl': '12px',
+  '3xl': '20px',
+  '4xl': '24px',
+  full: '9999px',
+};
+
+/**
+ * Font family presets mapping
+ * Inter is loaded from rsms.me in layout.tsx for docs site
+ */
+const FONT_FAMILY_MAP: Record<string, string> = {
+  sans: '"Inter", "InterVariable", ui-sans-serif, system-ui, sans-serif',
+  serif: 'ui-serif, Georgia, Cambria, "Times New Roman", Times, serif',
+  mono: 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace',
+  display: '"Inter", "InterVariable", ui-sans-serif, system-ui, sans-serif',
+  mixed: '"Inter", "InterVariable", ui-sans-serif, system-ui, sans-serif',
+  'montserrat-combo': '"Inter", "InterVariable", ui-sans-serif, system-ui, sans-serif',
+  'playfair-combo': '"Inter", "InterVariable", ui-sans-serif, system-ui, sans-serif',
+  'helvetica-combo': '"Inter", "InterVariable", "Helvetica Neue", Helvetica, Arial, ui-sans-serif, system-ui, sans-serif',
+};
+
+/**
+ * Default font weights
+ */
+const DEFAULT_WEIGHTS = {
+  body: '400',
+  heading: '600',
+  button: '500',
+  label: '500',
+  caption: '400',
+  display: '700',
+};
+
+/**
+ * Map legacy borderRadius to a radius preset
+ */
+function legacyBorderRadiusToPreset(borderRadius: string | undefined): RadiusPresetId {
+  switch (borderRadius) {
+    case 'none': return 'brutalist';
+    case 'sm': return 'sharp';
+    case 'full': return 'soft';
+    case 'xl': return 'playful';
+    case 'md':
+    case 'lg':
+    default:
+      return 'default';
+  }
+}
+
+/**
+ * Resolve radius preset to a config object
+ */
+function resolveRadiusConfig(preset: RadiusPresetId | RadiusConfig | undefined): Required<RadiusConfig> {
+  if (!preset) return RADIUS_PRESETS.default;
+  if (typeof preset === 'string') return RADIUS_PRESETS[preset] || RADIUS_PRESETS.default;
+  return { ...RADIUS_PRESETS.default, ...preset };
+}
+
+/**
+ * Get heading font for a font family preset
+ */
+function getHeadingFont(fontFamily: string | undefined, bodyFont: string): string {
+  switch (fontFamily) {
+    case 'mixed':
+    case 'playfair-combo':
+      return 'ui-serif, Georgia, Cambria, serif';
+    case 'serif':
+      return 'ui-serif, Georgia, Cambria, "Times New Roman", Times, serif';
+    default:
+      return bodyFont;
+  }
+}
+
+/**
+ * Generate inline CSS styles from a theme configuration
+ *
+ * Returns a Record of CSS variable names to values that can be spread into
+ * a style prop for isolated theme previews.
+ *
+ * @param config - Theme configuration
+ * @returns Record of CSS variable names to values
+ */
+export function getThemeStyles(config: ThemeConfig): Record<string, string> {
+  // Try to find OKLCH config for this theme
+  const oklchConfig = config.name ? findOklchTheme(config.name) : undefined;
+
+  if (oklchConfig) {
+    // Use OKLCH-based style generation (preferred path)
+    return getOklchBasedStyles(oklchConfig, config);
+  }
+
+  // Fall back to legacy hex-based generation
+  return getLegacyStyles(config);
+}
+
+/**
+ * Generate styles using OKLCH color generation
+ */
+function getOklchBasedStyles(
+  oklchConfig: ReturnType<typeof findOklchTheme>,
+  legacyConfig: ThemeConfig
+): Record<string, string> {
+  if (!oklchConfig) {
+    return getLegacyStyles(legacyConfig);
+  }
+
+  // Get OKLCH-generated color variables
+  const colorStyles = getOklchThemeStyles(oklchConfig);
+
+  const styles: Record<string, string> = {
+    ...colorStyles,
+  };
+
+  // =========================================================================
+  // PRIMITIVE RADIUS TOKENS
+  // =========================================================================
+  styles['--radius-sm'] = RADIUS_VALUES.sm;
+  styles['--radius-md'] = RADIUS_VALUES.md;
+  styles['--radius-lg'] = RADIUS_VALUES.lg;
+  styles['--radius-xl'] = RADIUS_VALUES.xl;
+  styles['--radius-2xl'] = RADIUS_VALUES['2xl'];
+  styles['--radius-3xl'] = RADIUS_VALUES['3xl'];
+  styles['--radius-4xl'] = RADIUS_VALUES['4xl'];
+  styles['--radius-full'] = RADIUS_VALUES.full;
+
+  // =========================================================================
+  // SEMANTIC RADIUS
+  // =========================================================================
+  const radiusConfig = resolveRadiusConfig(oklchConfig.radiusPreset);
+  styles['--radius-button'] = RADIUS_VALUES[radiusConfig.button];
+  styles['--radius-input'] = RADIUS_VALUES[radiusConfig.input];
+  styles['--radius-card'] = RADIUS_VALUES[radiusConfig.card];
+  styles['--radius-modal'] = RADIUS_VALUES[radiusConfig.modal];
+  styles['--radius-badge'] = RADIUS_VALUES[radiusConfig.badge];
+  styles['--radius-avatar'] = RADIUS_VALUES[radiusConfig.avatar];
+  styles['--radius-tooltip'] = RADIUS_VALUES[radiusConfig.tooltip];
+  styles['--radius-image'] = RADIUS_VALUES[radiusConfig.image];
+
+  // =========================================================================
+  // FONTS
+  // =========================================================================
+  const fontPairing = oklchConfig.fontPairing || legacyConfig.fontPairing;
+  const fontFamily = oklchConfig.fontFamily || legacyConfig.fontFamily;
+
+  if (fontPairing) {
+    styles['--font-heading'] = fontPairing.headingFont;
+    styles['--font-body'] = fontPairing.bodyFont;
+    styles['--font-label'] = fontPairing.labelFont || fontPairing.bodyFont;
+    styles['--font-button'] = fontPairing.buttonFont || fontPairing.bodyFont;
+    styles['--font-caption'] = fontPairing.captionFont || fontPairing.bodyFont;
+    styles['--font-display'] = fontPairing.displayFont || fontPairing.headingFont;
+    styles['--font-accent'] = fontPairing.accentFont || fontPairing.headingFont;
+
+    const weights = fontPairing.weights;
+    styles['--font-weight-body'] = weights?.bodyWeight || DEFAULT_WEIGHTS.body;
+    styles['--font-weight-heading'] = weights?.headingWeight || DEFAULT_WEIGHTS.heading;
+    styles['--font-weight-button'] = weights?.buttonWeight || DEFAULT_WEIGHTS.button;
+    styles['--font-weight-label'] = weights?.labelWeight || DEFAULT_WEIGHTS.label;
+    styles['--font-weight-caption'] = weights?.captionWeight || DEFAULT_WEIGHTS.caption;
+    styles['--font-weight-display'] = weights?.displayWeight || DEFAULT_WEIGHTS.display;
+
+  } else {
+    const bodyFont = FONT_FAMILY_MAP[fontFamily || 'sans'] || FONT_FAMILY_MAP.sans;
+    const headingFont = getHeadingFont(fontFamily, bodyFont);
+
+    styles['--font-heading'] = headingFont;
+    styles['--font-body'] = bodyFont;
+    styles['--font-label'] = bodyFont;
+    styles['--font-button'] = bodyFont;
+    styles['--font-caption'] = bodyFont;
+    styles['--font-display'] = headingFont;
+    styles['--font-accent'] = headingFont;
+
+    styles['--font-weight-body'] = DEFAULT_WEIGHTS.body;
+    styles['--font-weight-heading'] = DEFAULT_WEIGHTS.heading;
+    styles['--font-weight-button'] = DEFAULT_WEIGHTS.button;
+    styles['--font-weight-label'] = DEFAULT_WEIGHTS.label;
+    styles['--font-weight-caption'] = DEFAULT_WEIGHTS.caption;
+    styles['--font-weight-display'] = DEFAULT_WEIGHTS.display;
+  }
+
+  // =========================================================================
+  // ICON STROKE WIDTH
+  // =========================================================================
+  const strokeWidthMap: Record<string, string> = {
+    thin: '1',
+    normal: '1.5',
+    thick: '2',
+    'extra-thick': '2.5',
+  };
+  const iconStrokeWidth = oklchConfig.iconStrokeWidth || legacyConfig.iconStrokeWidth;
+  styles['--icon-stroke-width'] = strokeWidthMap[iconStrokeWidth || 'normal'];
+
+  // Allow explicit primaryColor to override the OKLCH-generated value
+  if (legacyConfig.primaryColor) {
+    styles['--primary'] = legacyConfig.primaryColor;
+    styles['--color-primary'] = legacyConfig.primaryColor;
+    const hex = legacyConfig.primaryColor.replace('#', '');
+    const r = parseInt(hex.substr(0, 2), 16);
+    const g = parseInt(hex.substr(2, 2), 16);
+    const b = parseInt(hex.substr(4, 2), 16);
+    const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+    const primaryForeground = luminance > 0.6 ? '#0a0a0a' : '#ffffff';
+    styles['--primary-foreground'] = primaryForeground;
+    styles['--color-primary-foreground'] = primaryForeground;
+    styles['--accent'] = legacyConfig.primaryColor;
+    styles['--color-accent'] = legacyConfig.primaryColor;
+    styles['--color-ring'] = legacyConfig.primaryColor;
+  }
+
+  return styles;
+}
+
+/**
+ * Generate legacy hex-based styles (fallback)
+ */
+function getLegacyStyles(config: ThemeConfig): Record<string, string> {
+  const styles: Record<string, string> = {};
+
+  // =========================================================================
+  // COLOR VARIABLES
+  // =========================================================================
+
+  const backgroundColor = config.backgroundColor || '#ffffff';
+  const surfaceColor = config.isDark ? '#18181b' : '#ffffff';
+
+  if (backgroundColor) {
+    styles['backgroundColor'] = backgroundColor;
+    styles['--background'] = backgroundColor;
+    styles['--color-background'] = backgroundColor;
+    styles['--surface'] = surfaceColor;
+    styles['--color-card'] = surfaceColor;
+  }
+
+  // IMPORTANT: Use neutral foreground colors for maximum readability
+  const textColor = config.isDark ? '#fafafa' : '#171717';
+  styles['color'] = textColor;
+  // ALL foreground variables should be the same for consistency
+  styles['--foreground'] = textColor;
+  styles['--color-foreground'] = textColor;
+  styles['--color-heading'] = textColor;
+  styles['--color-card-foreground'] = textColor;
+  styles['--default-foreground'] = textColor;
+  styles['--color-default-foreground'] = textColor;
+  styles['--surface-foreground'] = textColor;
+  styles['--color-popover-foreground'] = textColor;
+  styles['--field-foreground'] = textColor;
+
+  // Color scheme for proper dark mode styling
+  if (config.isDark !== undefined) {
+    styles['colorScheme'] = config.isDark ? 'dark' : 'light';
+  }
+
+  if (config.primaryColor) {
+    styles['--primary'] = config.primaryColor;
+    styles['--color-primary'] = config.primaryColor;
+    // Calculate primary foreground based on luminance
+    const hex = config.primaryColor.replace('#', '');
+    const r = parseInt(hex.substr(0, 2), 16);
+    const g = parseInt(hex.substr(2, 2), 16);
+    const b = parseInt(hex.substr(4, 2), 16);
+    const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+    const primaryForeground = luminance > 0.6 ? '#0a0a0a' : '#ffffff';
+    styles['--primary-foreground'] = primaryForeground;
+    styles['--color-primary-foreground'] = primaryForeground;
+    styles['--accent'] = config.primaryColor;
+    styles['--color-accent'] = config.primaryColor;
+    styles['--accent-foreground'] = primaryForeground;
+    styles['--color-accent-foreground'] = primaryForeground;
+    styles['--color-ring'] = config.primaryColor;
+  }
+
+  if (config.secondaryColor) {
+    styles['--secondary'] = config.secondaryColor;
+    styles['--color-secondary'] = config.secondaryColor;
+  }
+
+  // Icon color
+  const iconColor = config.iconColor || config.primaryColor;
+  if (iconColor) {
+    styles['--color-icon'] = iconColor;
+  }
+
+  // Accent text colors
+  if (config.accentTextDark) {
+    styles['--color-accent-text-overlay'] = config.accentTextDark;
+  } else {
+    styles['--color-accent-text-overlay'] = config.isDark ? '#d6d3d1' : '#737373';
+  }
+  if (config.accentTextLight) {
+    styles['--color-accent-text-page'] = config.accentTextLight;
+  } else {
+    styles['--color-accent-text-page'] = config.isDark ? '#a1a1aa' : '#57534e';
+  }
+
+  // Derived colors
+  if (backgroundColor && config.textColor) {
+    const mutedBg = `color-mix(in srgb, ${surfaceColor} 97%, ${config.textColor})`;
+    styles['--default'] = `color-mix(in srgb, ${surfaceColor} 94%, ${config.textColor})`;
+    styles['--color-default'] = styles['--default'];
+    styles['--muted'] = mutedBg;
+    styles['--color-muted'] = mutedBg;
+
+    const mutedForeground = `color-mix(in srgb, ${config.textColor} 60%, transparent)`;
+    styles['--muted-foreground'] = mutedForeground;
+    styles['--color-muted-foreground'] = mutedForeground;
+
+    const dividerColor = config.isDark
+      ? `color-mix(in srgb, ${config.textColor} 30%, transparent)`
+      : `color-mix(in srgb, ${config.textColor} 20%, transparent)`;
+    styles['--color-border'] = dividerColor;
+    styles['--border'] = dividerColor;
+    styles['--divider'] = dividerColor;
+    styles['--color-divider'] = dividerColor;
+
+    // Semantic surface layers (replaces legacy content1-4)
+    styles['--color-surface-raised'] = config.isDark
+      ? `color-mix(in srgb, ${surfaceColor} 85%, ${config.textColor})`
+      : `color-mix(in srgb, ${backgroundColor} 97%, ${config.textColor})`;
+  }
+
+  // Form field colors (context-aware)
+  styles['--color-field'] = config.isDark ? surfaceColor : '#ffffff';
+  styles['--field-background'] = config.isDark ? surfaceColor : '#ffffff';
+  styles['--color-field-on-surface'] = config.isDark
+    ? `color-mix(in srgb, ${surfaceColor} 80%, ${config.textColor})`
+    : `color-mix(in srgb, ${backgroundColor} 96%, ${config.textColor})`;
+  styles['--color-popover'] = surfaceColor;
+  styles['--overlay'] = surfaceColor;
+
+  // =========================================================================
+  // PRIMITIVE RADIUS TOKENS
+  // =========================================================================
+  styles['--radius-sm'] = RADIUS_VALUES.sm;
+  styles['--radius-md'] = RADIUS_VALUES.md;
+  styles['--radius-lg'] = RADIUS_VALUES.lg;
+  styles['--radius-xl'] = RADIUS_VALUES.xl;
+  styles['--radius-2xl'] = RADIUS_VALUES['2xl'];
+  styles['--radius-3xl'] = RADIUS_VALUES['3xl'];
+  styles['--radius-4xl'] = RADIUS_VALUES['4xl'];
+  styles['--radius-full'] = RADIUS_VALUES.full;
+
+  // =========================================================================
+  // SEMANTIC RADIUS
+  // =========================================================================
+  let radiusConfig: Required<RadiusConfig>;
+  if (config.radiusPreset) {
+    radiusConfig = resolveRadiusConfig(config.radiusPreset);
+  } else if (config.borderRadius) {
+    const presetId = legacyBorderRadiusToPreset(config.borderRadius);
+    radiusConfig = RADIUS_PRESETS[presetId];
+  } else {
+    radiusConfig = RADIUS_PRESETS.default;
+  }
+
+  styles['--radius-button'] = RADIUS_VALUES[radiusConfig.button];
+  styles['--radius-input'] = RADIUS_VALUES[radiusConfig.input];
+  styles['--radius-card'] = RADIUS_VALUES[radiusConfig.card];
+  styles['--radius-modal'] = RADIUS_VALUES[radiusConfig.modal];
+  styles['--radius-badge'] = RADIUS_VALUES[radiusConfig.badge];
+  styles['--radius-avatar'] = RADIUS_VALUES[radiusConfig.avatar];
+  styles['--radius-tooltip'] = RADIUS_VALUES[radiusConfig.tooltip];
+  styles['--radius-image'] = RADIUS_VALUES[radiusConfig.image];
+
+  // =========================================================================
+  // FONTS
+  // =========================================================================
+  const bodyFont = FONT_FAMILY_MAP[config.fontFamily || 'sans'] || FONT_FAMILY_MAP.sans;
+  const headingFont = config.fontPairing?.headingFont || getHeadingFont(config.fontFamily, bodyFont);
+
+  // Core fonts
+  styles['--font-heading'] = headingFont;
+  styles['--font-body'] = config.fontPairing?.bodyFont || bodyFont;
+
+  // Semantic font roles
+  styles['--font-label'] = config.fontPairing?.labelFont || bodyFont;
+  styles['--font-button'] = config.fontPairing?.buttonFont || bodyFont;
+  styles['--font-caption'] = config.fontPairing?.captionFont || bodyFont;
+  styles['--font-display'] = config.fontPairing?.displayFont || headingFont;
+  styles['--font-accent'] = config.fontPairing?.accentFont || headingFont;
+
+  // Font weights
+  const weights = config.fontPairing?.weights;
+  styles['--font-weight-body'] = weights?.bodyWeight || DEFAULT_WEIGHTS.body;
+  styles['--font-weight-heading'] = weights?.headingWeight || DEFAULT_WEIGHTS.heading;
+  styles['--font-weight-button'] = weights?.buttonWeight || DEFAULT_WEIGHTS.button;
+  styles['--font-weight-label'] = weights?.labelWeight || DEFAULT_WEIGHTS.label;
+  styles['--font-weight-caption'] = weights?.captionWeight || DEFAULT_WEIGHTS.caption;
+  styles['--font-weight-display'] = weights?.displayWeight || DEFAULT_WEIGHTS.display;
+
+  // =========================================================================
+  // ICON STROKE WIDTH
+  // =========================================================================
+  const strokeWidthMap: Record<string, string> = {
+    thin: '1',
+    normal: '1.5',
+    thick: '2',
+    'extra-thick': '2.5',
+  };
+  styles['--icon-stroke-width'] = strokeWidthMap[config.iconStrokeWidth || 'normal'];
+
+  return styles;
+}
+
+/**
+ * Convert theme styles to a CSS string
+ *
+ * Useful for injecting styles into a <style> tag or style attribute.
+ *
+ * @param config - Theme configuration
+ * @param selector - CSS selector to scope the styles (default: ':root')
+ * @returns CSS string
+ */
+export function getThemeStylesCSS(config: ThemeConfig, selector = ':root'): string {
+  const styles = getThemeStyles(config);
+  const rules = Object.entries(styles)
+    .map(([key, value]) => `  ${key}: ${value};`)
+    .join('\n');
+  return `${selector} {\n${rules}\n}`;
+}

package/src/themes/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Theme System
+ *
+ * TWO APPROACHES — pick one:
+ *
+ * 1. CSS-ONLY (recommended for new apps):
+ *    Import defaults.css, override variables in your CSS. No JS needed.
+ *    See CUSTOMIZATION.md.
+ *
+ *      @import "@snowcone-app/ui/styles/defaults.css";
+ *      @import "@snowcone-app/ui/styles/base.css";
+ *      :root { --color-primary: #4f46e5; }
+ *
+ * 2. RUNTIME (for Storybook, theme picker UIs, dynamic switching):
+ *    Use ThemeProvider + applyTheme() + ne-themes.css.
+ *    This is used by Storybook configs and the canvas package.
+ */
+
+// Types
+export type {
+  ThemeConfig,
+  ThemePreset,
+  FontPairing,
+  FontWeights,
+  RadiusSize,
+  RadiusPresetId,
+  RadiusConfig,
+} from './types';
+export { RADIUS_PRESETS } from './types';
+
+// Presets & lookup
+export {
+  presetThemes,
+  baseThemes,
+  getThemeVariant,
+  findTheme,
+  findThemeById,
+  getBaseThemeName,
+} from './presets';
+
+// Runtime theme application
+export { applyTheme, clearTheme, toThemeId, getCurrentThemeId } from './apply-theme';
+
+// React context for runtime theme state
+export { ThemeProvider, useTheme, useThemeStandalone, type ThemeContextValue, type ThemeProviderProps } from './useTheme';
+
+// Style generation (for SSR inline styles)
+export { getThemeStyles, getThemeStylesCSS } from './getThemeStyles';