@silvery/theme 0.3.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@silvery/theme",
+  "version": "0.3.0",
+  "description": "Theming system with semantic color tokens for silvery",
+  "license": "MIT",
+  "author": "Bjørn Stabell <bjorn@stabell.org>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/beorn/silvery.git",
+    "directory": "packages/theme"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./ThemeContext": {
+      "types": "./src/ThemeContext.tsx",
+      "import": "./src/ThemeContext.tsx"
+    },
+    "./*": {
+      "types": "./src/*.ts",
+      "import": "./src/*.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {}
+}

package/src/ThemeContext.tsx

@@ -0,0 +1,62 @@
+/**
+ * ThemeContext — delivers a Theme to the component tree.
+ *
+ * Wrap your app (or a subtree) in `<ThemeProvider theme={…}>` to make
+ * `$token` color props resolve against that theme. Components call
+ * `useTheme()` to read the current theme.
+ *
+ * @example
+ * ```tsx
+ * import { ThemeProvider, defaultDarkTheme } from '@silvery/react'
+ *
+ * <ThemeProvider theme={defaultDarkTheme}>
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ */
+
+import React, { createContext, useContext } from "react"
+import type { Theme } from "./types"
+import { setActiveTheme } from "./state"
+import { defaultDarkTheme } from "./palettes/index"
+
+// ============================================================================
+// Context
+// ============================================================================
+
+const ThemeContext = createContext<Theme>(defaultDarkTheme)
+
+// ============================================================================
+// Provider
+// ============================================================================
+
+export interface ThemeProviderProps {
+  theme: Theme
+  children: React.ReactNode
+}
+
+/**
+ * Provide a theme to the subtree.
+ *
+ * Components beneath this provider can use `useTheme()` or `$token`
+ * color props (e.g. `color="$primary"`).
+ */
+export function ThemeProvider({ theme, children }: ThemeProviderProps): React.ReactElement {
+  // Set module-level active theme so parseColor() can resolve $token strings
+  // during the content phase without needing React context access.
+  setActiveTheme(theme)
+  return React.createElement(ThemeContext.Provider, { value: theme }, children)
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Read the current theme from context.
+ *
+ * Returns `defaultDarkTheme` when no `ThemeProvider` is present.
+ */
+export function useTheme(): Theme {
+  return useContext(ThemeContext)
+}

package/src/alias.ts

@@ -0,0 +1,94 @@
+/**
+ * Token aliasing — resolve token values that reference other tokens.
+ *
+ * Supports alias chains (e.g. $button -> $primary -> #EBCB8B) with a
+ * depth limit to prevent infinite loops from circular references.
+ */
+
+import type { Theme } from "./types"
+
+/** Maximum depth for alias chain resolution before treating as circular. */
+const MAX_ALIAS_DEPTH = 10
+
+/**
+ * Resolve all token aliases in a theme.
+ *
+ * Token values that start with `$` are treated as references to other tokens.
+ * Alias chains are followed until a concrete (non-$) value is reached.
+ * Circular references are detected via a depth limit and left unresolved.
+ *
+ * @param theme - A theme-like object where values may reference other tokens via `$name`
+ * @returns A new object with all aliases resolved to concrete values
+ *
+ * @example
+ * ```typescript
+ * const themed = resolveAliases({
+ *   ...baseTheme,
+ *   button: "$primary",      // resolves to the value of 'primary'
+ *   buttonHover: "$button",  // chain: buttonHover -> button -> primary -> hex
+ * })
+ * ```
+ */
+export function resolveAliases(theme: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {}
+
+  for (const key of Object.keys(theme)) {
+    result[key] = resolveAlias(key, theme, 0)
+  }
+
+  return result
+}
+
+/**
+ * Resolve a single token's alias chain.
+ *
+ * @param key - The token key to resolve
+ * @param tokens - The full token map
+ * @param depth - Current recursion depth (for loop detection)
+ * @returns The resolved concrete value, or the raw alias string if unresolvable
+ */
+function resolveAlias(key: string, tokens: Record<string, string>, depth: number): string {
+  if (depth >= MAX_ALIAS_DEPTH) return tokens[key] ?? ""
+
+  const value = tokens[key]
+  if (value === undefined) return ""
+
+  // Not an alias — return the concrete value
+  if (!value.startsWith("$")) return value
+
+  // Strip the `$` prefix and look up the referenced token
+  const refKey = value.slice(1)
+  if (!(refKey in tokens)) return value // Unknown reference, return as-is
+
+  return resolveAlias(refKey, tokens, depth + 1)
+}
+
+/**
+ * Resolve a single alias value against a Theme.
+ *
+ * Useful for resolving individual values without processing the entire theme.
+ *
+ * @param value - The value to resolve (may be "$tokenName" or a concrete value)
+ * @param theme - The theme to resolve against
+ * @returns The resolved concrete value
+ */
+export function resolveTokenAlias(value: string, theme: Theme): string {
+  if (!value.startsWith("$")) return value
+
+  const seen = new Set<string>()
+  let current = value
+
+  for (let i = 0; i < MAX_ALIAS_DEPTH; i++) {
+    if (!current.startsWith("$")) return current
+
+    const key = current.slice(1) as keyof Theme
+    if (seen.has(key)) return current // Circular reference
+    seen.add(key)
+
+    const resolved = theme[key]
+    if (typeof resolved !== "string") return current
+    current = resolved
+  }
+
+  return current
+}

package/src/auto-generate.ts

@@ -0,0 +1,126 @@
+/**
+ * Auto-generate themes — create a complete Theme from a single primary color.
+ *
+ * Uses HSL color manipulation to derive complementary and analogous colors
+ * for the full palette from one input color.
+ */
+
+import { hexToHsl, hslToHex, blend, contrastFg } from "./color"
+import { fromColors } from "./generators"
+import { deriveTheme } from "./derive"
+import type { Theme } from "./types"
+
+/**
+ * Generate a complete Theme from a single primary color.
+ *
+ * Derives a full ColorPalette using HSL color manipulation:
+ * - Background/foreground from lightness inversion
+ * - Complementary and analogous accent colors from hue rotation
+ * - Surface ramp from background blending
+ * - Status colors (error, warning, success, info) from standard hue positions
+ *
+ * @param primaryColor - A hex color string (e.g. "#5E81AC")
+ * @param mode - "dark" or "light" theme mode
+ * @returns A complete Theme with all 33 semantic tokens
+ *
+ * @example
+ * ```typescript
+ * const theme = autoGenerateTheme("#5E81AC", "dark")
+ * // Generates a full dark theme with blue as the primary accent
+ *
+ * const light = autoGenerateTheme("#E06C75", "light")
+ * // Generates a full light theme with red/rose as the primary accent
+ * ```
+ */
+export function autoGenerateTheme(primaryColor: string, mode: "dark" | "light"): Theme {
+  const hsl = hexToHsl(primaryColor)
+  if (!hsl) {
+    // Fallback: use default colors if input is not valid hex
+    const palette = fromColors({ dark: mode === "dark" })
+    return deriveTheme(palette)
+  }
+
+  const [h, s] = hsl
+  const dark = mode === "dark"
+
+  // Generate background and foreground based on mode
+  const bgL = dark ? 0.12 : 0.97
+  const fgL = dark ? 0.87 : 0.13
+  // Use low saturation for bg/fg to keep them neutral
+  const bgS = Math.min(s, 0.15)
+  const bg = hslToHex(h, bgS, bgL)
+  const fg = hslToHex(h, bgS * 0.5, fgL)
+
+  // Generate accent colors from hue rotations
+  // Standard hue positions for semantic colors
+  const redHue = 0
+  const yellowHue = 45
+  const greenHue = 130
+  const cyanHue = 185
+  const blueHue = 220
+  const magentaHue = 300
+
+  // Use the primary's saturation and adjust lightness for the mode
+  const accentL = dark ? 0.65 : 0.45
+  const accentS = Math.max(s, 0.5) // Ensure accents are reasonably saturated
+
+  const red = hslToHex(redHue, accentS, accentL)
+  const green = hslToHex(greenHue, accentS, accentL)
+  const yellow = hslToHex(yellowHue, accentS, accentL)
+  const blue = hslToHex(blueHue, accentS, accentL)
+  const magenta = hslToHex(magentaHue, accentS, accentL)
+  const cyan = hslToHex(cyanHue, accentS, accentL)
+
+  // Bright variants: increase lightness slightly
+  const brightOffset = dark ? 0.1 : -0.1
+  const brightL = accentL + brightOffset
+  const brightRed = hslToHex(30, accentS, brightL) // orange-ish
+  const brightGreen = hslToHex(greenHue, accentS, brightL)
+  const brightYellow = hslToHex(yellowHue, accentS, brightL)
+  const brightBlue = hslToHex(blueHue, accentS, brightL)
+  const brightMagenta = hslToHex(330, accentS, brightL) // pink-ish
+  const brightCyan = hslToHex(cyanHue, accentS, brightL)
+
+  // Surface colors from background
+  const black = dark ? hslToHex(h, bgS, bgL * 0.7) : hslToHex(h, bgS, bgL * 0.92)
+  const white = dark ? hslToHex(h, bgS * 0.3, 0.6) : hslToHex(h, bgS * 0.3, 0.35)
+  const brightBlack = dark ? hslToHex(h, bgS, bgL + 0.08) : hslToHex(h, bgS, bgL - 0.08)
+  const brightWhite = dark ? fg : hslToHex(h, bgS * 0.5, fgL - 0.05)
+
+  const palette = {
+    name: `generated-${mode}`,
+    dark,
+    black,
+    red,
+    green,
+    yellow,
+    blue,
+    magenta,
+    cyan,
+    white,
+    brightBlack,
+    brightRed,
+    brightGreen,
+    brightYellow,
+    brightBlue,
+    brightMagenta,
+    brightCyan,
+    brightWhite,
+    foreground: fg,
+    background: bg,
+    cursorColor: fg,
+    cursorText: bg,
+    selectionBackground: blend(bg, primaryColor, 0.3),
+    selectionForeground: fg,
+  }
+
+  // Derive the full theme, then override primary with the input color
+  const theme = deriveTheme(palette)
+
+  // Override primary to be exactly the input color
+  return {
+    ...theme,
+    primary: primaryColor,
+    primaryfg: contrastFg(primaryColor),
+  }
+}

package/src/builder.ts

@@ -0,0 +1,218 @@
+/**
+ * Chainable theme builder — create themes from minimal input.
+ *
+ * @example
+ * ```typescript
+ * // Just a background color
+ * const theme = createTheme().bg('#2E3440').build()
+ *
+ * // Primary + explicit dark mode
+ * const theme = createTheme().primary('#EBCB8B').dark().build()
+ *
+ * // Three-color input (dark/light inferred from bg luminance)
+ * const theme = createTheme()
+ *   .bg('#2E3440').fg('#ECEFF4').primary('#EBCB8B').build()
+ *
+ * // Preset with override
+ * const theme = createTheme().preset('nord').primary('#A3BE8C').build()
+ * ```
+ */
+
+import { hexToRgb } from "./color"
+import { deriveTheme } from "./derive"
+import { fromColors, assignPrimaryToSlot } from "./generators"
+import { getPaletteByName } from "./palettes/index"
+import type { Theme, ColorPalette, HueName } from "./types"
+
+// ============================================================================
+// Luminance
+// ============================================================================
+
+function isDarkColor(hex: string): boolean {
+  const rgb = hexToRgb(hex)
+  if (!rgb) return true
+  return (rgb[0] + rgb[1] + rgb[2]) / (255 * 3) < 0.5
+}
+
+// ============================================================================
+// Builder
+// ============================================================================
+
+interface ThemeBuilderState {
+  dark?: boolean
+  bgColor?: string
+  fgColor?: string
+  primaryColor?: string
+  colors: Partial<ColorPalette>
+  presetPalette?: ColorPalette
+}
+
+export interface ThemeBuilder {
+  /** Set background color. */
+  bg(color: string): ThemeBuilder
+  /** Set foreground color. */
+  fg(color: string): ThemeBuilder
+  /** Set primary accent color. */
+  primary(color: string): ThemeBuilder
+  /** Alias for `.primary()`. */
+  accent(color: string): ThemeBuilder
+  /** Force dark mode. */
+  dark(): ThemeBuilder
+  /** Force light mode. */
+  light(): ThemeBuilder
+  /** Set any palette color by name. */
+  color(name: keyof Omit<ColorPalette, "name" | "dark">, value: string): ThemeBuilder
+  /** Set full palette at once. */
+  palette(p: ColorPalette): ThemeBuilder
+  /** Load a built-in palette by name. */
+  preset(name: string): ThemeBuilder
+  /** Derive the final Theme from accumulated state. */
+  build(): Theme
+}
+
+/** Create a chainable theme builder. */
+export function createTheme(): ThemeBuilder {
+  const state: ThemeBuilderState = { colors: {} }
+
+  const builder: ThemeBuilder = {
+    bg(color) {
+      state.bgColor = color
+      return builder
+    },
+    fg(color) {
+      state.fgColor = color
+      return builder
+    },
+    primary(color) {
+      state.primaryColor = color
+      return builder
+    },
+    accent(color) {
+      return builder.primary(color)
+    },
+    dark() {
+      state.dark = true
+      return builder
+    },
+    light() {
+      state.dark = false
+      return builder
+    },
+    color(name, value) {
+      ;(state.colors as Record<string, string>)[name] = value
+      return builder
+    },
+    palette(p) {
+      state.presetPalette = p
+      return builder
+    },
+    preset(name) {
+      const p = getPaletteByName(name)
+      if (p) state.presetPalette = p
+      return builder
+    },
+
+    build(): Theme {
+      const isDark = state.dark ?? (state.bgColor ? isDarkColor(state.bgColor) : true)
+
+      let palette: ColorPalette
+
+      if (state.presetPalette) {
+        // Start from preset, apply overrides
+        palette = { ...state.presetPalette }
+        if (state.bgColor) palette.background = state.bgColor
+        if (state.fgColor) palette.foreground = state.fgColor
+        if (state.primaryColor) {
+          // Override the appropriate color slot
+          const slot = assignPrimaryToSlot(state.primaryColor)
+          const ansiName = hueToAnsiField(slot)
+          ;(palette as unknown as Record<string, string>)[ansiName] = state.primaryColor
+        }
+        palette.dark = isDark
+      } else {
+        // Generate from minimal input
+        palette = fromColors({
+          background: state.bgColor,
+          foreground: state.fgColor,
+          primary: state.primaryColor,
+          dark: isDark,
+        })
+      }
+
+      // Apply explicit color overrides
+      for (const [key, val] of Object.entries(state.colors)) {
+        if (val !== undefined && typeof val === "string") (palette as unknown as Record<string, string>)[key] = val
+      }
+
+      return deriveTheme(palette)
+    },
+  }
+
+  return builder
+}
+
+/** Map a HueName to the corresponding ColorPalette field. */
+function hueToAnsiField(hue: HueName): keyof ColorPalette {
+  const map: Record<HueName, keyof ColorPalette> = {
+    red: "red",
+    orange: "brightRed",
+    yellow: "yellow",
+    green: "green",
+    teal: "cyan",
+    blue: "blue",
+    purple: "magenta",
+    pink: "brightMagenta",
+  }
+  return map[hue]
+}
+
+// ============================================================================
+// Convenience Functions
+// ============================================================================
+
+/**
+ * Quick theme from a primary color or color name.
+ *
+ * @example
+ * ```typescript
+ * quickTheme('#EBCB8B', 'dark')  // yellow primary, dark mode
+ * quickTheme('blue')              // blue primary, default dark
+ * ```
+ */
+export function quickTheme(primaryOrHex: string, mode?: "dark" | "light"): Theme {
+  const b = createTheme()
+  if (primaryOrHex.startsWith("#")) {
+    b.primary(primaryOrHex)
+  } else {
+    const namedColors: Record<string, string> = {
+      red: "#BF616A",
+      orange: "#D08770",
+      yellow: "#EBCB8B",
+      green: "#A3BE8C",
+      teal: "#88C0D0",
+      cyan: "#88C0D0",
+      blue: "#5E81AC",
+      purple: "#B48EAD",
+      pink: "#D4879C",
+      magenta: "#B48EAD",
+      white: "#ECEFF4",
+    }
+    b.primary(namedColors[primaryOrHex] ?? "#5E81AC")
+  }
+  if (mode === "dark") b.dark()
+  else if (mode === "light") b.light()
+  return b.build()
+}
+
+/**
+ * Create a theme from a built-in preset name.
+ *
+ * @example
+ * ```typescript
+ * presetTheme('catppuccin-mocha')
+ * presetTheme('nord')
+ * ```
+ */
+export function presetTheme(name: string): Theme {
+  return createTheme().preset(name).build()
+}