@silvery/theme 0.3.0

package/src/theme.ts

@@ -0,0 +1,148 @@
+/**
+ * @silvery/theme — Universal color themes for any platform.
+ *
+ * Two-layer architecture:
+ *   Layer 1: ColorPalette (22 terminal colors — universal pivot format)
+ *   Layer 2: Theme (33 semantic tokens — what UI apps consume)
+ *
+ * Pipeline: Palette generators → ColorPalette → deriveTheme() → Theme
+ *
+ * @example
+ * ```typescript
+ * import { createTheme, catppuccinMocha, resolveThemeColor } from "@silvery/theme"
+ *
+ * const theme = createTheme().preset('catppuccin-mocha').build()
+ * const color = resolveThemeColor("$primary", theme) // → "#F9E2AF"
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// React integration
+export { ThemeProvider, useTheme } from "./ThemeContext"
+export type { ThemeProviderProps } from "./ThemeContext"
+
+// Core types
+export type { Theme, ColorPalette, HueName, AnsiPrimary, AnsiColorName } from "./types"
+export { COLOR_PALETTE_FIELDS } from "./types"
+
+// Derivation
+export { deriveTheme } from "./derive"
+
+// Color utilities
+export {
+  blend,
+  brighten,
+  darken,
+  contrastFg,
+  desaturate,
+  complement,
+  hexToRgb,
+  rgbToHex,
+  hexToHsl,
+  hslToHex,
+  rgbToHsl,
+} from "./color"
+export type { HSL } from "./color"
+
+// Token resolution
+export { resolveThemeColor } from "./resolve"
+
+// ANSI 16 theme generation
+export { generateTheme } from "./generate"
+
+// Builder API
+export { createTheme, quickTheme, presetTheme } from "./builder"
+
+// Palette generators
+export { fromBase16, fromColors, fromPreset } from "./generators"
+
+// Active theme state (side-effectful)
+export { setActiveTheme, getActiveTheme, pushContextTheme, popContextTheme } from "./state"
+
+// Validation
+export { validateColorPalette } from "./validate"
+export type { ValidationResult } from "./validate"
+export { validateTheme, THEME_TOKEN_KEYS } from "./validate-theme"
+export type { ThemeValidationResult } from "./validate-theme"
+
+// Contrast checking
+export { checkContrast } from "./contrast"
+export type { ContrastResult } from "./contrast"
+
+// Token aliasing
+export { resolveAliases, resolveTokenAlias } from "./alias"
+
+// CSS variables export
+export { themeToCSSVars } from "./css"
+
+// Auto-generate themes from a single color
+export { autoGenerateTheme } from "./auto-generate"
+
+// Base16 import/export
+export { importBase16 } from "./import/base16"
+export { exportBase16 } from "./export/base16"
+export type { Base16Scheme } from "./import/types"
+
+// Terminal detection
+export { detectTerminalPalette, detectTheme } from "./detect"
+export type { DetectedPalette, DetectThemeOptions } from "./detect"
+
+// Built-in themes (pre-derived)
+export {
+  ansi16DarkTheme,
+  ansi16LightTheme,
+  defaultDarkTheme,
+  defaultLightTheme,
+  builtinThemes,
+  getThemeByName,
+} from "./palettes/index"
+
+// Built-in palettes (45 palettes from 15 theme families)
+export {
+  builtinPalettes,
+  getPaletteByName,
+  catppuccinMocha,
+  catppuccinFrappe,
+  catppuccinMacchiato,
+  catppuccinLatte,
+  nord,
+  dracula,
+  oneDark,
+  solarizedDark,
+  solarizedLight,
+  gruvboxDark,
+  gruvboxLight,
+  tokyoNight,
+  tokyoNightStorm,
+  tokyoNightDay,
+  rosePine,
+  rosePineMoon,
+  rosePineDawn,
+  kanagawaWave,
+  kanagawaDragon,
+  kanagawaLotus,
+  everforestDark,
+  everforestLight,
+  nightfox,
+  dawnfox,
+  monokai,
+  monokaiPro,
+  snazzy,
+  materialDark,
+  materialLight,
+  palenight,
+  ayuDark,
+  ayuMirage,
+  ayuLight,
+  horizon,
+  moonfly,
+  nightfly,
+  oxocarbonDark,
+  oxocarbonLight,
+  sonokai,
+  edgeDark,
+  edgeLight,
+  modusVivendi,
+  modusOperandi,
+} from "./palettes/index"

package/src/types.ts

@@ -0,0 +1,223 @@
+/**
+ * Core type definitions for the swatch theme system.
+ *
+ * Two-layer architecture:
+ *   Layer 1: ColorPalette — 22 terminal colors (what palette generators produce)
+ *   Layer 2: Theme — 33 semantic tokens (what UI apps consume)
+ *
+ * Pipeline: Palette generators → ColorPalette (22) → deriveTheme() → Theme (33)
+ */
+
+// ============================================================================
+// ColorPalette — The 22-Color Terminal Standard
+// ============================================================================
+
+/**
+ * The 22-color format every modern terminal emulator uses
+ * (Ghostty, Kitty, Alacritty, iTerm2, WezTerm).
+ *
+ * 16 ANSI palette colors + 6 special colors = universal pivot format.
+ * All fields are required hex strings (#RRGGBB).
+ */
+export interface ColorPalette {
+  name?: string
+  dark?: boolean
+
+  // ── 16 ANSI palette ────────────────────────────────────────────
+  /** ANSI 0 — normal black */
+  black: string
+  /** ANSI 1 — normal red */
+  red: string
+  /** ANSI 2 — normal green */
+  green: string
+  /** ANSI 3 — normal yellow */
+  yellow: string
+  /** ANSI 4 — normal blue */
+  blue: string
+  /** ANSI 5 — normal magenta */
+  magenta: string
+  /** ANSI 6 — normal cyan */
+  cyan: string
+  /** ANSI 7 — normal white */
+  white: string
+  /** ANSI 8 — bright black */
+  brightBlack: string
+  /** ANSI 9 — bright red */
+  brightRed: string
+  /** ANSI 10 — bright green */
+  brightGreen: string
+  /** ANSI 11 — bright yellow */
+  brightYellow: string
+  /** ANSI 12 — bright blue */
+  brightBlue: string
+  /** ANSI 13 — bright magenta */
+  brightMagenta: string
+  /** ANSI 14 — bright cyan */
+  brightCyan: string
+  /** ANSI 15 — bright white */
+  brightWhite: string
+
+  // ── 6 special colors ────────────────────────────────────────────
+  /** Default text color */
+  foreground: string
+  /** Default background color */
+  background: string
+  /** Cursor block/line color */
+  cursorColor: string
+  /** Text rendered under the cursor */
+  cursorText: string
+  /** Background color of selected text */
+  selectionBackground: string
+  /** Text color of selected text */
+  selectionForeground: string
+}
+
+/** All 22 color field names on ColorPalette. */
+export const COLOR_PALETTE_FIELDS = [
+  "black",
+  "red",
+  "green",
+  "yellow",
+  "blue",
+  "magenta",
+  "cyan",
+  "white",
+  "brightBlack",
+  "brightRed",
+  "brightGreen",
+  "brightYellow",
+  "brightBlue",
+  "brightMagenta",
+  "brightCyan",
+  "brightWhite",
+  "foreground",
+  "background",
+  "cursorColor",
+  "cursorText",
+  "selectionBackground",
+  "selectionForeground",
+] as const
+
+/** Name of one of the 16 ANSI palette colors. */
+export type AnsiColorName =
+  | "black"
+  | "red"
+  | "green"
+  | "yellow"
+  | "blue"
+  | "magenta"
+  | "cyan"
+  | "white"
+  | "brightBlack"
+  | "brightRed"
+  | "brightGreen"
+  | "brightYellow"
+  | "brightBlue"
+  | "brightMagenta"
+  | "brightCyan"
+  | "brightWhite"
+
+// ============================================================================
+// Theme — 33 Semantic Tokens for UI Consumption
+// ============================================================================
+
+/**
+ * Semantic color token map (33 tokens + palette).
+ *
+ * Two pairing conventions:
+ *   Surface pairs: `$name` = text, `$name-bg` = background
+ *     (muted, surface, popover, inverse, cursor, selection)
+ *   Accent pairs: `$name` = area bg, `$name-fg` = text on area
+ *     (primary, secondary, accent, error, warning, success, info)
+ *
+ * Components reference tokens with a `$` prefix (e.g. `color="$primary"`).
+ * All property names are lowercase, no hyphens, no camelCase.
+ */
+export interface Theme {
+  /** Human-readable theme name */
+  name: string
+
+  // ── Root pair ───────────────────────────────────────────────────
+  /** Default background */
+  bg: string
+  /** Default text */
+  fg: string
+
+  // ── 6 surface pairs (base = text, *bg = background) ─────────────
+  /** Secondary/muted text (~70% contrast) */
+  muted: string
+  /** Muted area background (hover state) */
+  mutedbg: string
+  /** Text on elevated surface */
+  surface: string
+  /** Elevated content area background */
+  surfacebg: string
+  /** Text on floating content */
+  popover: string
+  /** Floating content background (popover, dropdown) */
+  popoverbg: string
+  /** Text on chrome area */
+  inverse: string
+  /** Chrome area (status/title bar) */
+  inversebg: string
+  /** Text under cursor */
+  cursor: string
+  /** Cursor color */
+  cursorbg: string
+  /** Text on selected items */
+  selection: string
+  /** Selected items background */
+  selectionbg: string
+
+  // ── 7 accent pairs (base = area bg, *fg = text on area) ─────────
+  /** Brand accent area */
+  primary: string
+  /** Text on primary accent area */
+  primaryfg: string
+  /** Alternate accent area */
+  secondary: string
+  /** Text on secondary accent area */
+  secondaryfg: string
+  /** Attention/pop accent area */
+  accent: string
+  /** Text on accent area */
+  accentfg: string
+  /** Error/destructive area */
+  error: string
+  /** Text on error area */
+  errorfg: string
+  /** Warning/caution area */
+  warning: string
+  /** Text on warning area */
+  warningfg: string
+  /** Success/positive area */
+  success: string
+  /** Text on success area */
+  successfg: string
+  /** Neutral info area */
+  info: string
+  /** Text on info area */
+  infofg: string
+
+  // ── 5 standalone tokens ─────────────────────────────────────────
+  /** Structural dividers, borders */
+  border: string
+  /** Interactive control borders (inputs, buttons) */
+  inputborder: string
+  /** Focus border (always blue) */
+  focusborder: string
+  /** Hyperlinks */
+  link: string
+  /** Disabled/placeholder text (~50% contrast) */
+  disabledfg: string
+
+  // ── 16 palette passthrough ──────────────────────────────────────
+  /** 16 ANSI colors ($color0–$color15) */
+  palette: string[]
+}
+
+/** Supported primary colors for ANSI 16 theme generation. */
+export type AnsiPrimary = "yellow" | "cyan" | "magenta" | "green" | "red" | "blue" | "white"
+
+/** Accent hue name — the 8 hue names for palette generators. */
+export type HueName = "red" | "orange" | "yellow" | "green" | "teal" | "blue" | "purple" | "pink"

package/src/validate-theme.ts

@@ -0,0 +1,100 @@
+/**
+ * Theme validation — checks that all required semantic tokens are present.
+ *
+ * Complements validateColorPalette() which validates the lower-level
+ * ColorPalette. This validates the derived Theme object.
+ */
+
+/** All 33 required semantic token keys on Theme (excludes `name` and `palette`). */
+export const THEME_TOKEN_KEYS: readonly string[] = [
+  // Root pair
+  "bg",
+  "fg",
+  // 6 surface pairs (base = text, *bg = background)
+  "muted",
+  "mutedbg",
+  "surface",
+  "surfacebg",
+  "popover",
+  "popoverbg",
+  "inverse",
+  "inversebg",
+  "cursor",
+  "cursorbg",
+  "selection",
+  "selectionbg",
+  // 7 accent pairs (base = area bg, *fg = text on area)
+  "primary",
+  "primaryfg",
+  "secondary",
+  "secondaryfg",
+  "accent",
+  "accentfg",
+  "error",
+  "errorfg",
+  "warning",
+  "warningfg",
+  "success",
+  "successfg",
+  "info",
+  "infofg",
+  // 5 standalone tokens
+  "border",
+  "inputborder",
+  "focusborder",
+  "link",
+  "disabledfg",
+] as const
+
+/** Result of theme validation. */
+export interface ThemeValidationResult {
+  /** Whether the theme has all required tokens. */
+  valid: boolean
+  /** Token keys that are required but missing or empty. */
+  missing: string[]
+  /** Token keys that exist on the object but are not recognized theme tokens. */
+  extra: string[]
+}
+
+/** All recognized keys on Theme (tokens + metadata). */
+const ALL_KNOWN_KEYS = new Set([...THEME_TOKEN_KEYS, "name", "palette"])
+
+/**
+ * Validate a Theme object — check that all required tokens are present.
+ *
+ * @param theme - The theme object to validate
+ * @returns Validation result with missing and extra token lists
+ *
+ * @example
+ * ```typescript
+ * const result = validateTheme(myTheme)
+ * if (!result.valid) {
+ *   console.log("Missing tokens:", result.missing)
+ * }
+ * ```
+ */
+export function validateTheme(theme: Record<string, unknown>): ThemeValidationResult {
+  const missing: string[] = []
+  const extra: string[] = []
+
+  // Check for missing or empty required tokens
+  for (const key of THEME_TOKEN_KEYS) {
+    const val = theme[key]
+    if (val === undefined || val === null || val === "") {
+      missing.push(key)
+    }
+  }
+
+  // Check for unrecognized keys (exclude prototype properties)
+  for (const key of Object.keys(theme)) {
+    if (!ALL_KNOWN_KEYS.has(key)) {
+      extra.push(key)
+    }
+  }
+
+  return {
+    valid: missing.length === 0,
+    missing,
+    extra,
+  }
+}

package/src/validate.ts

@@ -0,0 +1,56 @@
+/**
+ * Palette validation — checks ColorPalette fields and contrast.
+ */
+
+import { hexToRgb } from "./color"
+import { COLOR_PALETTE_FIELDS, type ColorPalette } from "./types"
+
+/** Validation result from validateColorPalette(). */
+export interface ValidationResult {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+}
+
+/**
+ * Validate a ColorPalette.
+ *
+ * Checks:
+ * - All 22 color fields are present and non-empty hex strings
+ * - Warns on low-contrast foreground/background combinations
+ */
+export function validateColorPalette(p: ColorPalette): ValidationResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  // Required color fields
+  for (const field of COLOR_PALETTE_FIELDS) {
+    const val = p[field]
+    if (!val || typeof val !== "string") {
+      errors.push(`${field} is required and must be a non-empty string`)
+    }
+  }
+
+  // Contrast warnings (only for hex colors)
+  if (p.foreground && p.background) {
+    const fgRgb = hexToRgb(p.foreground)
+    const bgRgb = hexToRgb(p.background)
+    if (fgRgb && bgRgb) {
+      const fgSum = fgRgb[0] + fgRgb[1] + fgRgb[2]
+      const bgSum = bgRgb[0] + bgRgb[1] + bgRgb[2]
+      const fgIsLight = fgSum > 384
+      const bgIsLight = bgSum > 384
+      if (fgIsLight === bgIsLight) {
+        warnings.push(
+          `Low contrast: foreground (${p.foreground}) and background (${p.background}) have similar lightness`,
+        )
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  }
+}