@effect-tui/core 0.1.0 → 0.1.4

package/src/colors.ts

@@ -0,0 +1,468 @@
+// colors.ts — Comprehensive color parsing and utilities
+// Supports indexed colors (0-255), RGB, hex, named colors, HSL, and alpha
+
+import { tailwindColors, type TailwindShade, type TailwindColorFamily } from "./tailwind-colors.js"
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Type-safe color types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Hex color string: #rgb, #rrggbb, #rgba, or #rrggbbaa
+ *
+ * Note: We use `#${string}` because enumerating all valid hex digit combinations
+ * (22^6 = 113M for 6-char hex) exceeds TypeScript's union type limits.
+ * The # prefix is validated at compile time; hex digits are validated at runtime.
+ */
+export type HexColor = `#${string}`
+
+/** Base ANSI terminal color names */
+export type BaseColorName =
+	| "black"
+	| "red"
+	| "green"
+	| "yellow"
+	| "blue"
+	| "magenta"
+	| "cyan"
+	| "white"
+	| "brightBlack"
+	| "brightRed"
+	| "brightGreen"
+	| "brightYellow"
+	| "brightBlue"
+	| "brightMagenta"
+	| "brightCyan"
+	| "brightWhite"
+
+/**
+ * Color input type - the main public type for color props.
+ *
+ * Accepts:
+ * - Palette index: 0-255
+ * - RGB object: { r, g, b }
+ * - Named color: "red", "brightBlue", etc. (type-checked)
+ * - Hex color: "#f00", "#ff0000" (# prefix required)
+ */
+export type Color = number | { r: number; g: number; b: number } | BaseColorName | HexColor
+
+/** RGBA color with alpha channel - used for color springs/interpolation */
+export type RGBA = { r: number; g: number; b: number; a: number }
+
+/** Color input for springs (includes alpha variants) */
+export type ColorInput = string | RGBA | { r: number; g: number; b: number }
+
+/** Standard ANSI color names mapped to 256-color indices */
+export const BASE_NAMES = {
+	black: 0,
+	red: 1,
+	green: 2,
+	yellow: 3,
+	blue: 4,
+	magenta: 5,
+	cyan: 6,
+	white: 7,
+	brightBlack: 8,
+	brightRed: 9,
+	brightGreen: 10,
+	brightYellow: 11,
+	brightBlue: 12,
+	brightMagenta: 13,
+	brightCyan: 14,
+	brightWhite: 15,
+} as const
+
+// ============================================================================
+// Utility functions
+// ============================================================================
+
+/** Clamp a number to 0-255 range */
+export function clamp255(n: number): number {
+	return n < 0 ? 0 : n > 255 ? 255 : n | 0
+}
+
+/** Clamp a number to 0-1 range */
+export function clamp1(n: number): number {
+	return n < 0 ? 0 : n > 1 ? 1 : n
+}
+
+// ============================================================================
+// parseColor - For Palette/styles (returns ColorValue)
+// ============================================================================
+
+/** Internal type for resolved colors (palette index or RGB) */
+type ColorValue = number | { r: number; g: number; b: number }
+
+/**
+ * Parse flexible color inputs into a resolved color value.
+ * Supports: number (0-255), {r,g,b}, "#rgb", "#rrggbb", base names, gray0-23.
+ * Used by Palette and style systems.
+ */
+export function parseColor(c: Color): ColorValue {
+	if (typeof c === "number") return c
+	if (typeof c === "object") return { r: c.r | 0, g: c.g | 0, b: c.b | 0 }
+	const s = String(c).trim()
+
+	// Hex color
+	if (s.startsWith("#")) {
+		const hex = s.slice(1)
+		if (hex.length === 3) {
+			// #rgb -> #rrggbb
+			return {
+				r: parseInt(hex[0] + hex[0], 16),
+				g: parseInt(hex[1] + hex[1], 16),
+				b: parseInt(hex[2] + hex[2], 16),
+			}
+		}
+		if (hex.length === 6) {
+			return {
+				r: parseInt(hex.slice(0, 2), 16),
+				g: parseInt(hex.slice(2, 4), 16),
+				b: parseInt(hex.slice(4, 6), 16),
+			}
+		}
+	}
+
+	// Named color
+	if (s in BASE_NAMES) return BASE_NAMES[s as keyof typeof BASE_NAMES]
+
+	// gray0-gray23
+	const m = /^(?:gray|grey)(\d{1,2})$/.exec(s)
+	if (m?.[1]) {
+		const n = Math.max(0, Math.min(23, parseInt(m[1], 10)))
+		return 232 + n
+	}
+
+	return 7 // default to white if unrecognized
+}
+
+// ============================================================================
+// parseColorRGBA - For color springs (returns RGBA with alpha)
+// ============================================================================
+
+/**
+ * Parse any supported color format to RGBA (with alpha).
+ * Supports: hex (#rgb, #rrggbb, #rgba, #rrggbbaa), rgb(), rgba(), hsl(), hsla(), {r,g,b,a}.
+ * Used by color springs for interpolation.
+ */
+export function parseColorRGBA(input: ColorInput): RGBA {
+	if (typeof input === "object") {
+		return {
+			r: input.r,
+			g: input.g,
+			b: input.b,
+			a: "a" in input ? input.a : 1,
+		}
+	}
+
+	const str = input.trim().toLowerCase()
+
+	// Hex: #rgb, #rrggbb, #rgba, #rrggbbaa
+	if (str.startsWith("#")) {
+		return parseHex(str)
+	}
+
+	// rgb(r, g, b) or rgba(r, g, b, a)
+	if (str.startsWith("rgb")) {
+		return parseRgb(str)
+	}
+
+	// hsl(h, s%, l%) or hsla(h, s%, l%, a)
+	if (str.startsWith("hsl")) {
+		return parseHsl(str)
+	}
+
+	// Unknown format, return black
+	return { r: 0, g: 0, b: 0, a: 1 }
+}
+
+function parseHex(hex: string): RGBA {
+	const h = hex.slice(1)
+
+	if (h.length === 3) {
+		return {
+			r: parseInt(h[0] + h[0], 16),
+			g: parseInt(h[1] + h[1], 16),
+			b: parseInt(h[2] + h[2], 16),
+			a: 1,
+		}
+	}
+
+	if (h.length === 4) {
+		return {
+			r: parseInt(h[0] + h[0], 16),
+			g: parseInt(h[1] + h[1], 16),
+			b: parseInt(h[2] + h[2], 16),
+			a: parseInt(h[3] + h[3], 16) / 255,
+		}
+	}
+
+	if (h.length === 6) {
+		return {
+			r: parseInt(h.slice(0, 2), 16),
+			g: parseInt(h.slice(2, 4), 16),
+			b: parseInt(h.slice(4, 6), 16),
+			a: 1,
+		}
+	}
+
+	if (h.length === 8) {
+		return {
+			r: parseInt(h.slice(0, 2), 16),
+			g: parseInt(h.slice(2, 4), 16),
+			b: parseInt(h.slice(4, 6), 16),
+			a: parseInt(h.slice(6, 8), 16) / 255,
+		}
+	}
+
+	return { r: 0, g: 0, b: 0, a: 1 }
+}
+
+function parseRgb(str: string): RGBA {
+	const match = str.match(/rgba?\(\s*(\d+)\s*[,\s]\s*(\d+)\s*[,\s]\s*(\d+)\s*(?:[,/]\s*([\d.]+))?\s*\)/)
+	if (match) {
+		return {
+			r: clamp255(parseInt(match[1], 10)),
+			g: clamp255(parseInt(match[2], 10)),
+			b: clamp255(parseInt(match[3], 10)),
+			a: match[4] ? clamp1(parseFloat(match[4])) : 1,
+		}
+	}
+	return { r: 0, g: 0, b: 0, a: 1 }
+}
+
+function parseHsl(str: string): RGBA {
+	const match = str.match(/hsla?\(\s*(\d+)\s*[,\s]\s*([\d.]+)%?\s*[,\s]\s*([\d.]+)%?\s*(?:[,/]\s*([\d.]+))?\s*\)/)
+	if (match) {
+		const h = parseFloat(match[1])
+		const s = parseFloat(match[2])
+		const l = parseFloat(match[3])
+		const a = match[4] ? clamp1(parseFloat(match[4])) : 1
+		return hslToRgba(h, s, l, a)
+	}
+	return { r: 0, g: 0, b: 0, a: 1 }
+}
+
+/**
+ * Convert HSL to RGBA.
+ * h: 0-360, s: 0-100, l: 0-100, a: 0-1
+ */
+export function hslToRgba(h: number, s: number, l: number, a: number): RGBA {
+	// Normalize
+	h = ((h % 360) + 360) % 360
+	s = clamp1(s / 100)
+	l = clamp1(l / 100)
+
+	const c = (1 - Math.abs(2 * l - 1)) * s
+	const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
+	const m = l - c / 2
+
+	let r = 0
+	let g = 0
+	let b = 0
+
+	if (h < 60) {
+		r = c
+		g = x
+		b = 0
+	} else if (h < 120) {
+		r = x
+		g = c
+		b = 0
+	} else if (h < 180) {
+		r = 0
+		g = c
+		b = x
+	} else if (h < 240) {
+		r = 0
+		g = x
+		b = c
+	} else if (h < 300) {
+		r = x
+		g = 0
+		b = c
+	} else {
+		r = c
+		g = 0
+		b = x
+	}
+
+	return {
+		r: Math.round((r + m) * 255),
+		g: Math.round((g + m) * 255),
+		b: Math.round((b + m) * 255),
+		a,
+	}
+}
+
+/**
+ * Convert a 256-color index to RGB values (approximate xterm palette).
+ * 0-15: Standard ANSI, 16-231: 6x6x6 RGB cube, 232-255: Grayscale ramp
+ */
+export function idxToRGB(idx: number): { r: number; g: number; b: number } {
+	if (idx < 0) idx = 0
+	if (idx > 255) idx = 255
+
+	// Standard ANSI colors (0-15)
+	if (idx < 16) {
+		const base: Array<[number, number, number]> = [
+			[0x00, 0x00, 0x00], // 0: black
+			[0x80, 0x00, 0x00], // 1: red
+			[0x00, 0x80, 0x00], // 2: green
+			[0x80, 0x80, 0x00], // 3: yellow
+			[0x00, 0x00, 0x80], // 4: blue
+			[0x80, 0x00, 0x80], // 5: magenta
+			[0x00, 0x80, 0x80], // 6: cyan
+			[0xc0, 0xc0, 0xc0], // 7: white
+			[0x80, 0x80, 0x80], // 8: bright black (gray)
+			[0xff, 0x00, 0x00], // 9: bright red
+			[0x00, 0xff, 0x00], // 10: bright green
+			[0xff, 0xff, 0x00], // 11: bright yellow
+			[0x00, 0x00, 0xff], // 12: bright blue
+			[0xff, 0x00, 0xff], // 13: bright magenta
+			[0x00, 0xff, 0xff], // 14: bright cyan
+			[0xff, 0xff, 0xff], // 15: bright white
+		]
+		const [r, g, b] = base[idx] ?? [0, 0, 0]
+		return { r, g, b }
+	}
+
+	// Grayscale ramp (232-255)
+	if (idx >= 232) {
+		const n = idx - 232 // 0..23
+		const v = 8 + n * 10
+		return { r: v, g: v, b: v }
+	}
+
+	// 6x6x6 RGB cube (16-231)
+	const n = idx - 16 // 0..215
+	const r = Math.floor(n / 36) % 6
+	const g = Math.floor(n / 6) % 6
+	const b = n % 6
+	const steps = [0, 95, 135, 175, 215, 255]
+	return { r: steps[r] ?? 0, g: steps[g] ?? 0, b: steps[b] ?? 0 }
+}
+
+/**
+ * Check if a value looks like a color input.
+ */
+export function isColorInput(value: unknown): value is ColorInput {
+	if (typeof value === "string") {
+		const s = value.trim().toLowerCase()
+		return s.startsWith("#") || s.startsWith("rgb") || s.startsWith("hsl")
+	}
+	if (typeof value === "object" && value !== null) {
+		const obj = value as Record<string, unknown>
+		return typeof obj.r === "number" && typeof obj.g === "number" && typeof obj.b === "number"
+	}
+	return false
+}
+
+// ============================================================================
+// Colors API - Convenience object for creating colors
+// ============================================================================
+
+type RGB = { r: number; g: number; b: number }
+
+/** Parse hex string to RGB */
+function hexToRgb(hex: string): RGB {
+	const h = hex.startsWith("#") ? hex.slice(1) : hex
+	return {
+		r: parseInt(h.slice(0, 2), 16),
+		g: parseInt(h.slice(2, 4), 16),
+		b: parseInt(h.slice(4, 6), 16),
+	}
+}
+
+/** Create a Tailwind color function for a given family */
+function makeTailwindColor(family: TailwindColorFamily): (shade: TailwindShade) => RGB {
+	const palette = tailwindColors[family]
+	return (shade: TailwindShade): RGB => {
+		const hex = palette[shade]
+		return hexToRgb(hex)
+	}
+}
+
+type TailwindColorFn = (shade: TailwindShade) => RGB
+
+type TailwindColors = {
+	slate: TailwindColorFn
+	gray: TailwindColorFn
+	zinc: TailwindColorFn
+	neutral: TailwindColorFn
+	stone: TailwindColorFn
+	red: TailwindColorFn
+	orange: TailwindColorFn
+	amber: TailwindColorFn
+	yellow: TailwindColorFn
+	lime: TailwindColorFn
+	green: TailwindColorFn
+	emerald: TailwindColorFn
+	teal: TailwindColorFn
+	cyan: TailwindColorFn
+	sky: TailwindColorFn
+	blue: TailwindColorFn
+	indigo: TailwindColorFn
+	violet: TailwindColorFn
+	purple: TailwindColorFn
+	fuchsia: TailwindColorFn
+	pink: TailwindColorFn
+	rose: TailwindColorFn
+}
+
+type ColorsApi = typeof BASE_NAMES & {
+	rgb(r: number, g: number, b: number): RGB
+	hex(hex: HexColor): RGB
+	/** Gray - 24-level grayscale palette (0-23) */
+	gray(level: number): number
+	/** Tailwind color palette */
+	tw: TailwindColors
+}
+
+/** Tailwind color palette under Colors.tw namespace */
+const tw: TailwindColors = {
+	slate: makeTailwindColor("slate"),
+	gray: makeTailwindColor("gray"),
+	zinc: makeTailwindColor("zinc"),
+	neutral: makeTailwindColor("neutral"),
+	stone: makeTailwindColor("stone"),
+	red: makeTailwindColor("red"),
+	orange: makeTailwindColor("orange"),
+	amber: makeTailwindColor("amber"),
+	yellow: makeTailwindColor("yellow"),
+	lime: makeTailwindColor("lime"),
+	green: makeTailwindColor("green"),
+	emerald: makeTailwindColor("emerald"),
+	teal: makeTailwindColor("teal"),
+	cyan: makeTailwindColor("cyan"),
+	sky: makeTailwindColor("sky"),
+	blue: makeTailwindColor("blue"),
+	indigo: makeTailwindColor("indigo"),
+	violet: makeTailwindColor("violet"),
+	purple: makeTailwindColor("purple"),
+	fuchsia: makeTailwindColor("fuchsia"),
+	pink: makeTailwindColor("pink"),
+	rose: makeTailwindColor("rose"),
+}
+
+/** Convenience API for creating color values */
+export const Colors: ColorsApi = Object.assign(
+	{
+		rgb(r: number, g: number, b: number): RGB {
+			return { r, g, b }
+		},
+		hex(hex: HexColor): RGB {
+			const result = parseColor(hex)
+			// parseColor returns number for named colors, but hex always returns RGB
+			return typeof result === "number" ? { r: 0, g: 0, b: 0 } : result
+		},
+		/** Gray - 24-level grayscale palette (0-23) */
+		gray(level: number): number {
+			const n = Math.max(0, Math.min(23, level | 0))
+			return 232 + n
+		},
+		/** Tailwind color palette */
+		tw,
+	},
+	BASE_NAMES,
+) as ColorsApi

package/src/index.ts

@@ -1,21 +1,35 @@
-// Re-export core modules
+// Core types
+export * from "./types.js"
+
+// Rendering primitives
 export * from "./render/surface.js"
 export * from "./render/buffer.js"
+export * from "./render/palette.js"
 export * from "./render/measure.js"
-export * from "./anim.js"
+
+// Colors - additional exports not in surface.js (RGBA, parseColorRGBA for springs)
+export {
+	parseColorRGBA,
+	hslToRgba,
+	idxToRGB,
+	isColorInput,
+	clamp255,
+	clamp1,
+	type RGBA,
+	type ColorInput,
+} from "./colors.js"
+
+// Input handling
 export * from "./keys.js"
 
-// UI (canonical View and curated exports)
-export { View } from "./ui/index.js"
-export { ShinyText } from "./ui/index.js"
-export { TextInput, TextInputState, editTextInput } from "./ui/index.js"
-export { Markdown } from "./ui/index.js"
-export type { TextInputStateLike, TextInputStatePlain, TextInputGeom, TextInputOptions } from "./ui/index.js"
-export type { MarkdownOptions } from "./ui/index.js"
-// Geometry store (last-known layout)
-export { geometryStore } from "./ui/core/geometry-store.js"
-export type { ViewId, Rect as GeometryRect, InputGeom } from "./ui/core/geometry-store.js"
+// ANSI escape sequences
+export * from "./ansi.js"
+
+// Output helpers (buffer diffing and emission)
+export * from "./output.js"
+
+// Layout utilities
+export * from "./layout/axis-helpers.js"
 
-// Renderers (optional public API)
-export * from "./present/display.js"
+// Terminal backend (optional)
 export type { TerminalBackend } from "./runtime/backend_node.js"