@rokkit/core 1.0.3 → 1.0.4

package/dist/constants.d.ts

@@ -56,6 +56,7 @@ export namespace DEFAULT_THEME_MAPPING {
     let surface: string;
     let primary: string;
     let secondary: string;
+    let tertiary: string;
     let accent: string;
     let success: string;
     let warning: string;

package/dist/theme.d.ts

@@ -13,19 +13,21 @@ export declare function shadesOf(name: any, modifier?: string): {
  *
  * @param {Object} [mapping=DEFAULT_THEME_MAPPING] - An object mapping variant names to color property names.
  * @param {Object} [colors=defaultColors]        - The object containing default color definitions.
+ * @param {import('./utils').ColorSpace} [colorSpace] - Color space for CSS variable values.
  * @returns {Array<Array>} An array containing two arrays, one for the light theme variant and another for the dark theme.
  */
-export declare function themeRules(mapping?: {
+export declare function themeRules(mapping: {
     surface: string;
     primary: string;
     secondary: string;
+    tertiary: string;
     accent: string;
     success: string;
     warning: string;
     danger: string;
     error: string;
     info: string;
-}, colors?: any): {};
+} | undefined, colors: any, colorSpace: any): {};
 /**
  * Generates UnoCSS shortcut definitions for semantic tones with bg, border, text.
  * @param {string} name - Color name (e.g., 'primary')
@@ -49,14 +51,15 @@ export declare class Theme {
     #private;
     /**
      *
-     * @param {import('./types.js').ColorTheme} param0
+     * @param {import('./types.js').ColorTheme & { colorSpace?: import('./utils').ColorSpace }} param0
      */
-    constructor({ colors, mapping }?: {
+    constructor({ colors, mapping, colorSpace }?: {
         colors?: any;
         mapping?: {
             surface: string;
             primary: string;
             secondary: string;
+            tertiary: string;
             accent: string;
             success: string;
             warning: string;
@@ -64,31 +67,14 @@ export declare class Theme {
             error: string;
             info: string;
         } | undefined;
+        colorSpace?: string | undefined;
     });
     get colors(): any;
     set colors(colors: any);
-    get mapping(): {
-        surface: string;
-        primary: string;
-        secondary: string;
-        accent: string;
-        success: string;
-        warning: string;
-        danger: string;
-        error: string;
-        info: string;
-    };
-    set mapping(mapping: {
-        surface: string;
-        primary: string;
-        secondary: string;
-        accent: string;
-        success: string;
-        warning: string;
-        danger: string;
-        error: string;
-        info: string;
-    });
+    get mapping(): any;
+    set mapping(mapping: any);
+    get colorSpace(): string;
+    set colorSpace(colorSpace: string);
     mapVariant(color: any, variant: any): {};
     getColorRules(mapping?: null): {};
     getPalette(mapping?: null): {};

package/dist/types.d.ts

@@ -286,6 +286,7 @@ export type ColorMapping = {
      */
     error?: string | undefined;
 };
+export type ColorSpace = "rgb" | "hsl" | "oklch";
 export type ColorTheme = {
     /**
      * - The color mapping.
@@ -297,4 +298,8 @@ export type ColorTheme = {
     colors?: {
         [x: string]: ColorPalette;
     } | undefined;
+    /**
+     * - Color space for CSS variable values ('rgb', 'hsl', or 'oklch').
+     */
+    colorSpace?: ColorSpace | undefined;
 };

package/dist/utils.d.ts

@@ -79,22 +79,64 @@ export function getPathFromKey(key: string): string[];
 export function getSnippet(obj: Object, key: string, defaultSnippet?: null | Function): Function | undefined;
 export function resolveSnippet(snippets: any, proxy: any, fallback?: string): Function | null;
 /**
- * convert hex string to `{r} {g} {b}`
+ * convert hex string to `{r},{g},{b}`
  * @param {string} hex
  * @return {string}
  */
 export function hex2rgb(hex: string): string;
 /**
- * Convert a CSS color value to r,g,b for use in CSS variables.
- * Hex values (#rrggbb) are converted to "r,g,b" for rgba() support.
- * All other CSS color formats (oklch, hsl, named) are returned as-is.
- * Non-string values are returned unchanged.
- * Note: non-hex values will NOT work with UnoCSS opacity utilities like bg-primary/50.
+ * Convert hex string to OKLCH components: `{L} {C} {H}`
+ * Uses CSS Color Level 4 two-step conversion via XYZ D65 for precision.
+ * @param {string} hex - 6-digit hex color (with or without #)
+ * @returns {string} space-separated OKLCH components for CSS `oklch(L C H / alpha)`
+ */
+export function hex2oklch(hex: string): string;
+/**
+ * Convert OKLCH components back to hex string.
+ * Uses CSS Color Level 4 two-step conversion via XYZ D65 for precision.
+ * @param {number} L - Lightness 0-1
+ * @param {number} C - Chroma >= 0
+ * @param {number} H - Hue 0-360 degrees
+ * @returns {string} hex color string (#rrggbb)
+ */
+export function oklch2hex(L: number, C: number, H: number): string;
+/**
+ * Convert hex string to HSL components: `{H} {S}% {L}%`
+ * @param {string} hex - 6-digit hex color (with or without #)
+ * @returns {string} space-separated HSL components for CSS `hsl(H S% L% / alpha)`
+ */
+export function hex2hsl(hex: string): string;
+/** @typedef {'rgb' | 'hsl' | 'oklch'} ColorSpace */
+/**
+ * Convert a hex color to the component format for a given color space.
+ * - rgb:   "r,g,b"          → for `rgba(var(--x), alpha)`
+ * - hsl:   "H S% L%"        → for `hsl(var(--x) / alpha)`
+ * - oklch: "L C H"           → for `oklch(var(--x) / alpha)`
+ *
+ * @param {string} hex - 6-digit hex color (#rrggbb)
+ * @param {ColorSpace} space
+ * @returns {string}
+ */
+export function hexToComponents(hex: string, space: ColorSpace): string;
+/**
+ * Convert a CSS color value to components for use in CSS variables.
+ *
+ * - Hex (#rrggbb): converted to space-appropriate components via hexToComponents.
+ * - oklch(...) strings: inner components extracted (e.g. "0.58 0.15 35") so the
+ *   value is compatible with the oklch(var(--x) / alpha) wrapper pattern.
+ * - All other formats: returned as-is (no opacity-modifier support).
  *
  * @param {unknown} value
+ * @param {ColorSpace} [space]
  * @returns {unknown}
  */
-export function colorToRgb(value: unknown): unknown;
+export function colorToRgb(value: unknown, space?: ColorSpace): unknown;
+/**
+ * Detects whether an icon value is a CSS class (i-*) or literal text (kanji, emoji, etc.)
+ * @param {string | null | undefined} icon
+ * @returns {boolean} true if icon is a CSS class string
+ */
+export function isIconClass(icon: string | null | undefined): boolean;
 /**
  * A utility function that detects if a string is an image URL or image data (base64)
  *
@@ -102,3 +144,4 @@ export function colorToRgb(value: unknown): unknown;
  * @returns {string|null} - Returns the original string if it's an image URL or image data, otherwise null
  */
 export function getImage(str: string): string | null;
+export type ColorSpace = "rgb" | "hsl" | "oklch";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/core",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Contains core utility functions and classes that can be used in various components.",
   "repository": {
     "type": "git",
@@ -46,6 +46,6 @@
     "ramda": "^0.32.0"
   },
   "devDependencies": {
-    "@rokkit/icons": "1.0.3"
+    "@rokkit/icons": "1.0.4"
   }
 }

package/src/colors/index.ts

@@ -10,6 +10,7 @@ export const defaultPalette = [
 	'surface',
 	'primary',
 	'secondary',
+	'tertiary',
 	'accent',
 	'success',
 	'warning',

package/src/constants.js

@@ -156,6 +156,7 @@ export const DEFAULT_THEME_MAPPING = {
 	surface: 'slate',
 	primary: 'orange',
 	secondary: 'pink',
+	tertiary: 'violet',
 	accent: 'sky',
 	success: 'green',
 	warning: 'yellow',

package/src/theme.ts

@@ -7,9 +7,21 @@ import { colorToRgb } from './utils'
 const modifiers = {
 	hsl: (value) => `hsl(${value} / <alpha-value>)`,
 	rgb: (value) => `rgb(${value} / <alpha-value>)`,
+	oklch: (value) => `oklch(${value} / <alpha-value>)`,
 	none: (value) => value
 }
 
+/**
+ * CSS function wrappers for each color space, used by mapVariant().
+ * rgb uses legacy rgba() comma syntax for broad compatibility.
+ * hsl/oklch use modern space-separated syntax with / for alpha.
+ */
+const COLOR_SPACE_WRAPPERS = {
+	rgb: (varRef) => `rgba(${varRef},<alpha-value>)`,
+	hsl: (varRef) => `hsl(${varRef} / <alpha-value>)`,
+	oklch: (varRef) => `oklch(${varRef} / <alpha-value>)`
+}
+
 /**
  * Generate shades for a color using css varuable
  *
@@ -37,13 +49,14 @@ export function shadesOf(name, modifier = 'none') {
  * @param {string} variant - The name of the variant to generate rules for.
  * @param {Object} colors - The object containing color definitions.
  * @param {Object} mapping - An object that maps variant names to color property names.
+ * @param {import('./utils').ColorSpace} [colorSpace] - Color space for component format.
  * @returns {import('./types').ShadeMappings} An array containing the color rules for both light and dark modes.
  */
-function generateColorRules(variant, colors, mapping) {
+function generateColorRules(variant, colors, mapping, colorSpace) {
 	return ['DEFAULT', ...shades].flatMap((shade) => [
 		{
 			key: shade === 'DEFAULT' ? `--color-${variant}` : `--color-${variant}-${shade}`,
-			value: colorToRgb(colors[mapping[variant]][`${shade}`])
+			value: colorToRgb(colors[mapping[variant]][`${shade}`], colorSpace)
 		}
 	])
 }
@@ -53,14 +66,15 @@ function generateColorRules(variant, colors, mapping) {
  *
  * @param {Object} [mapping=DEFAULT_THEME_MAPPING] - An object mapping variant names to color property names.
  * @param {Object} [colors=defaultColors]        - The object containing default color definitions.
+ * @param {import('./utils').ColorSpace} [colorSpace] - Color space for CSS variable values.
  * @returns {Array<Array>} An array containing two arrays, one for the light theme variant and another for the dark theme.
  */
-export function themeRules(mapping = DEFAULT_THEME_MAPPING, colors = defaultColors) {
+export function themeRules(mapping = DEFAULT_THEME_MAPPING, colors = defaultColors, colorSpace) {
 	mapping = { ...DEFAULT_THEME_MAPPING, ...mapping }
 	colors = { ...defaultColors, ...colors }
 	const variants = Object.keys(mapping)
 	const rules = variants
-		.flatMap((variant) => generateColorRules(variant, colors, mapping))
+		.flatMap((variant) => generateColorRules(variant, colors, mapping, colorSpace))
 		.reduce((acc, { key, value }) => ({ ...acc, [key]: value }), {})
 
 	return rules
@@ -144,20 +158,48 @@ export function contrastShortcuts(name) {
 	]
 }
 
+/**
+ * Fallback chain for nullable color mappings.
+ * If a semantic color is null, it inherits from another semantic color.
+ */
+const COLOR_FALLBACKS = {
+	tertiary: 'primary',
+	secondary: 'primary',
+	accent: 'primary',
+	error: 'danger'
+}
+
+/**
+ * Resolves null values in a color mapping by following the fallback chain.
+ * @param {Record<string, string | null>} mapping
+ * @returns {Record<string, string>}
+ */
+function resolveColors(mapping) {
+	const resolved = { ...mapping }
+	for (const [key, fallbackKey] of Object.entries(COLOR_FALLBACKS)) {
+		if (resolved[key] === null || resolved[key] === undefined) {
+			resolved[key] = resolved[fallbackKey] ?? DEFAULT_THEME_MAPPING[fallbackKey]
+		}
+	}
+	return resolved
+}
+
 /**
  * Theme class for managing color palettes, mappings, and semantic shortcuts.
  */
 export class Theme {
 	#colors
 	#mapping
+	#colorSpace
 
 	/**
 	 *
-	 * @param {import('./types.js').ColorTheme} param0
+	 * @param {import('./types.js').ColorTheme & { colorSpace?: import('./utils').ColorSpace }} param0
 	 */
-	constructor({ colors = defaultColors, mapping = DEFAULT_THEME_MAPPING } = {}) {
+	constructor({ colors = defaultColors, mapping = DEFAULT_THEME_MAPPING, colorSpace = 'rgb' } = {}) {
 		this.#colors = { ...defaultColors, ...colors }
-		this.#mapping = { ...DEFAULT_THEME_MAPPING, ...mapping }
+		this.#mapping = resolveColors({ ...DEFAULT_THEME_MAPPING, ...mapping })
+		this.#colorSpace = colorSpace
 	}
 
 	get colors() {
@@ -171,17 +213,25 @@ export class Theme {
 		return this.#mapping
 	}
 	set mapping(mapping) {
-		this.#mapping = { ...mapping }
+		this.#mapping = resolveColors({ ...mapping })
+	}
+
+	get colorSpace() {
+		return this.#colorSpace
+	}
+	set colorSpace(colorSpace) {
+		this.#colorSpace = colorSpace
 	}
 
 	mapVariant(color, variant) {
+		const wrap = COLOR_SPACE_WRAPPERS[this.#colorSpace] || COLOR_SPACE_WRAPPERS.rgb
 		return Object.keys(color).reduce(
 			(acc, key) => ({
 				...acc,
 				[key]:
 					key === 'DEFAULT'
-						? `rgba(var(--color-${variant}),<alpha-value>)`
-						: `rgba(var(--color-${variant}-${key}),<alpha-value>)`
+						? wrap(`var(--color-${variant})`)
+						: wrap(`var(--color-${variant}-${key})`)
 			}),
 			{}
 		)
@@ -203,7 +253,7 @@ export class Theme {
 		const useColors = { ...defaultColors, ...this.#colors }
 		const variants = Object.keys(useMapping)
 		const rules = variants
-			.flatMap((variant) => generateColorRules(variant, useColors, useMapping))
+			.flatMap((variant) => generateColorRules(variant, useColors, useMapping, this.#colorSpace))
 			.reduce((acc, { key, value }) => ({ ...acc, [key]: value }), {})
 		return rules
 	}

package/src/types.js

@@ -152,9 +152,14 @@
  * @property {string} [error]     - The error color.
  */
 
+/**
+ * @typedef {'rgb' | 'hsl' | 'oklch'} ColorSpace
+ */
+
 /**
  * @typedef {Object} ColorTheme
  * @property {ColorMapping} [mapping] - The color mapping.
  * @property {ColorCollection} [colors] - The color collection.
+ * @property {ColorSpace} [colorSpace] - Color space for CSS variable values ('rgb', 'hsl', or 'oklch').
  */
 export default {}

package/src/utils.js

@@ -195,7 +195,7 @@ export function resolveSnippet(snippets, proxy, fallback = ITEM_SNIPPET) {
 }
 
 /**
- * convert hex string to `{r} {g} {b}`
+ * convert hex string to `{r},{g},{b}`
  * @param {string} hex
  * @return {string}
  */
@@ -205,22 +205,208 @@ export function hex2rgb(hex) {
 }
 
 /**
- * Convert a CSS color value to r,g,b for use in CSS variables.
- * Hex values (#rrggbb) are converted to "r,g,b" for rgba() support.
- * All other CSS color formats (oklch, hsl, named) are returned as-is.
- * Non-string values are returned unchanged.
- * Note: non-hex values will NOT work with UnoCSS opacity utilities like bg-primary/50.
+ * Convert sRGB component (0-255) to linear RGB.
+ * @param {number} c - sRGB value 0-255
+ * @returns {number}
+ */
+function srgbToLinear(c) {
+	const s = c / 255
+	return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4)
+}
+
+/**
+ * Convert linear RGB to sRGB component (0-255).
+ * @param {number} c - linear value 0-1
+ * @returns {number}
+ */
+function linearToSrgb(c) {
+	const s = c <= 0.0031308 ? c * 12.92 : 1.055 * Math.pow(c, 1 / 2.4) - 0.055
+	return Math.round(Math.max(0, Math.min(255, s * 255)))
+}
+
+// CSS Color Level 4 two-step matrices (via XYZ D65) for round-trip fidelity.
+// Linear sRGB → XYZ D65
+const SRGB_TO_XYZ = [
+	[0.4123907993, 0.3575843394, 0.1804807884],
+	[0.2126390059, 0.7151686788, 0.0721923154],
+	[0.0193308187, 0.1191947798, 0.9505321522]
+]
+// XYZ D65 → LMS
+const XYZ_TO_LMS = [
+	[0.8189330101, 0.3618667424, -0.1288597137],
+	[0.0329845436, 0.9293118715, 0.0361456387],
+	[0.0482003018, 0.2643662691, 0.633851707]
+]
+// LMS^(1/3) → OKLab
+const LMS3_TO_OKLAB = [
+	[0.2104542553, 0.793617785, -0.0040720468],
+	[1.9779984951, -2.428592205, 0.4505937099],
+	[0.0259040371, 0.7827717662, -0.808675766]
+]
+// OKLab → LMS^(1/3)
+const OKLAB_TO_LMS3 = [
+	[1.0, 0.3963377774, 0.2158037573],
+	[1.0, -0.1055613458, -0.0638541728],
+	[1.0, -0.0894841775, -1.291485548]
+]
+// LMS → XYZ D65
+const LMS_TO_XYZ = [
+	[1.2270138511, -0.5577999807, 0.281256149],
+	[-0.0405801784, 1.1122568696, -0.0716766787],
+	[-0.0763812845, -0.4214819784, 1.5861632204]
+]
+// XYZ D65 → linear sRGB
+const XYZ_TO_SRGB = [
+	[3.2409699419, -1.5373831776, -0.4986107603],
+	[-0.9692436363, 1.8759675015, 0.0415550574],
+	[0.0556300797, -0.2039769589, 1.0569715142]
+]
+
+/** @param {number[][]} m @param {number[]} v */
+function matMul(m, v) {
+	return m.map((row) => row[0] * v[0] + row[1] * v[1] + row[2] * v[2])
+}
+
+/**
+ * Convert hex string to OKLCH components: `{L} {C} {H}`
+ * Uses CSS Color Level 4 two-step conversion via XYZ D65 for precision.
+ * @param {string} hex - 6-digit hex color (with or without #)
+ * @returns {string} space-separated OKLCH components for CSS `oklch(L C H / alpha)`
+ */
+export function hex2oklch(hex) {
+	const [r, g, b] = hex.match(/\w\w/g).map((x) => parseInt(x, 16))
+	const lin = [srgbToLinear(r), srgbToLinear(g), srgbToLinear(b)]
+
+	const xyz = matMul(SRGB_TO_XYZ, lin)
+	const lms = matMul(XYZ_TO_LMS, xyz)
+	const lms3 = [Math.cbrt(lms[0]), Math.cbrt(lms[1]), Math.cbrt(lms[2])]
+	const [L, a, bk] = matMul(LMS3_TO_OKLAB, lms3)
+
+	const C = Math.sqrt(a * a + bk * bk)
+	let H = (Math.atan2(bk, a) * 180) / Math.PI
+	if (H < 0) H += 360
+
+	const Lr = Math.round(L * 1000000) / 1000000
+	const Cr = Math.round(C * 1000000) / 1000000
+	const Hr = Math.round(H * 10000) / 10000
+
+	return `${Lr} ${Cr} ${Hr}`
+}
+
+/**
+ * Convert OKLCH components back to hex string.
+ * Uses CSS Color Level 4 two-step conversion via XYZ D65 for precision.
+ * @param {number} L - Lightness 0-1
+ * @param {number} C - Chroma >= 0
+ * @param {number} H - Hue 0-360 degrees
+ * @returns {string} hex color string (#rrggbb)
+ */
+export function oklch2hex(L, C, H) {
+	const hRad = (H * Math.PI) / 180
+	const lab = [L, C * Math.cos(hRad), C * Math.sin(hRad)]
+
+	const lms3 = matMul(OKLAB_TO_LMS3, lab)
+	const lms = [lms3[0] ** 3, lms3[1] ** 3, lms3[2] ** 3]
+	const xyz = matMul(LMS_TO_XYZ, lms)
+	const lin = matMul(XYZ_TO_SRGB, xyz)
+
+	const toHex = (n) => {
+		const hex = linearToSrgb(n).toString(16)
+		return hex.length === 1 ? `0${hex}` : hex
+	}
+	return `#${toHex(lin[0])}${toHex(lin[1])}${toHex(lin[2])}`
+}
+
+/**
+ * Convert hex string to HSL components: `{H} {S}% {L}%`
+ * @param {string} hex - 6-digit hex color (with or without #)
+ * @returns {string} space-separated HSL components for CSS `hsl(H S% L% / alpha)`
+ */
+export function hex2hsl(hex) {
+	const [r, g, b] = hex.match(/\w\w/g).map((x) => parseInt(x, 16))
+
+	const rn = r / 255
+	const gn = g / 255
+	const bn = b / 255
+	const max = Math.max(rn, gn, bn)
+	const min = Math.min(rn, gn, bn)
+	const l = (max + min) / 2
+
+	if (max === min) return `0 0% ${Math.round(l * 100)}%`
+
+	const d = max - min
+	const s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
+
+	let h = 0
+	if (max === rn) h = ((gn - bn) / d + (gn < bn ? 6 : 0)) / 6
+	else if (max === gn) h = ((bn - rn) / d + 2) / 6
+	else h = ((rn - gn) / d + 4) / 6
+
+	const Hr = Math.round(h * 360)
+	const Sr = Math.round(s * 100)
+	const Lr = Math.round(l * 100)
+
+	return `${Hr} ${Sr}% ${Lr}%`
+}
+
+/** @typedef {'rgb' | 'hsl' | 'oklch'} ColorSpace */
+
+/**
+ * Convert a hex color to the component format for a given color space.
+ * - rgb:   "r,g,b"          → for `rgba(var(--x), alpha)`
+ * - hsl:   "H S% L%"        → for `hsl(var(--x) / alpha)`
+ * - oklch: "L C H"           → for `oklch(var(--x) / alpha)`
+ *
+ * @param {string} hex - 6-digit hex color (#rrggbb)
+ * @param {ColorSpace} space
+ * @returns {string}
+ */
+export function hexToComponents(hex, space) {
+	switch (space) {
+		case 'hsl':
+			return hex2hsl(hex)
+		case 'oklch':
+			return hex2oklch(hex)
+		case 'rgb':
+		default:
+			return hex2rgb(hex)
+	}
+}
+
+/**
+ * Convert a CSS color value to components for use in CSS variables.
+ *
+ * - Hex (#rrggbb): converted to space-appropriate components via hexToComponents.
+ * - oklch(...) strings: inner components extracted (e.g. "0.58 0.15 35") so the
+ *   value is compatible with the oklch(var(--x) / alpha) wrapper pattern.
+ * - All other formats: returned as-is (no opacity-modifier support).
  *
  * @param {unknown} value
+ * @param {ColorSpace} [space]
  * @returns {unknown}
  */
-export function colorToRgb(value) {
-	if (typeof value === 'string' && /^#[0-9a-fA-F]{6}$/.test(value)) {
-		return hex2rgb(value)
+export function colorToRgb(value, space) {
+	if (typeof value !== 'string') return value
+	if (/^#[0-9a-fA-F]{6}$/.test(value)) {
+		return space ? hexToComponents(value, space) : hex2rgb(value)
 	}
+	// oklch(...) — extract inner components so the var can be used in oklch(var(--x) / alpha)
+	const oklchMatch = value.match(/^oklch\(\s*([^)]+?)\s*\)$/)
+	if (oklchMatch) return oklchMatch[1]
 	return value
 }
 
+
+/**
+ * Detects whether an icon value is a CSS class (i-*) or literal text (kanji, emoji, etc.)
+ * @param {string | null | undefined} icon
+ * @returns {boolean} true if icon is a CSS class string
+ */
+export function isIconClass(icon) {
+	if (!icon || typeof icon !== 'string') return false
+	return icon.startsWith('i-')
+}
+
 /**
  * Checks if a string is a valid image URL
  *