@rokkit/core 1.8.0 → 1.8.1

package/src/oklch.js

@@ -0,0 +1,124 @@
+/** Colour conversion: hex ↔ `r,g,b` and hex ↔ OKLCH (CSS Color Level 4, via XYZ D65). */
+
+/**
+ * convert hex string to `{r},{g},{b}`
+ * @param {string} hex
+ * @return {string}
+ */
+export function hex2rgb(hex) {
+	const [r, g, b] = hex.match(/\w\w/g).map((x) => parseInt(x, 16))
+	return `${r},${g},${b}`
+}
+
+/**
+ * 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])}`
+}

package/src/snippets.js

@@ -0,0 +1,45 @@
+/** Snippet lookup for data-driven rendering. */
+import { has } from 'ramda'
+import { ITEM_SNIPPET } from './constants'
+
+/**
+ * Get snippet function from an object
+ * @param {Object} obj
+ * @param {string} key
+ * @param {null|Function} defaultSnippet
+ * @returns {Function|undefined}
+ */
+export function getSnippet(obj, key, defaultSnippet = null) {
+	if (has(key, obj) && typeof obj[key] === 'function') {
+		return obj[key]
+	}
+	return defaultSnippet
+}
+
+/**
+ * @param {unknown} value
+ * @returns {Function|null}
+ */
+function asSnippet(value) {
+	return typeof value === 'function' ? value : null
+}
+
+/**
+ * Resolve which snippet to render for a proxy item.
+ *
+ * Reads the proxy's `snippet` field (via proxy.get('snippet'), honoring fields.snippet)
+ * for a per-item named override first (e.g. item.snippet = 'highlighted').
+ * Falls back to the component-level fallback snippet name (e.g. 'itemContent' / 'groupContent').
+ * Returns null if neither is found.
+ *
+ * @param {Record<string, unknown>} snippets  - snippets passed to the component
+ * @param {{ get: (key: string) => unknown }} proxy  - a ProxyItem; its snippet field is read via proxy.get('snippet')
+ * @param {string} [fallback]                  - fallback snippet name; defaults to ITEM_SNIPPET ('itemContent')
+ * @returns {Function | null}
+ */
+export function resolveSnippet(snippets, proxy, fallback = ITEM_SNIPPET) {
+	// `snippet` is a field-mapped prop like icon/href — read it via the proxy's
+	// field accessor (honors fields.snippet), not as a direct property.
+	const name = proxy?.get('snippet')
+	return asSnippet(name && snippets[name]) || asSnippet(snippets[fallback])
+}

package/src/theme.ts

@@ -1,5 +1,3 @@
-// eslint-disable-next-line @typescript-eslint/ban-ts-comment
-// @ts-nocheck
 import { DEFAULT_THEME_MAPPING, defaultColors } from './constants'
 import { shades } from './colors/index'
 import { ColorSpace, relativeLuminance } from './color-space'
@@ -8,6 +6,23 @@ import {
   NAMED_TOKEN_SHADE_MAP,
   NAMED_TOKEN_ROLE_MAP
 } from './named-tokens'
+import type { NamedToken } from './named-tokens'
+
+/** One palette: shade (`'50'`…`'950'`, `'DEFAULT'`) → colour value in the adapter's notation. */
+type Palette = Record<string, string>
+/** Palette name → palette. */
+type Colors = Record<string, Palette>
+/** Role (`primary`, `surface`…) → palette name. */
+type Mapping = Record<string, string>
+type Adapter = ReturnType<typeof ColorSpace.create>
+
+/**
+ * The default colours seen as palettes only. preset-mini's map also holds keyword entries
+ * (`inherit`, `current`, `transparent`…) that are plain strings, but a Theme only reaches a
+ * colour through a role mapping, and roles map to palette names — so the keyword entries are
+ * never indexed by shade here.
+ */
+const DEFAULT_COLORS = defaultColors as unknown as Colors
 
 /**
  * Generate shades for a color using css variable and a ColorSpace adapter.
@@ -16,10 +31,10 @@ import {
  * @param {string|import('./color-space').ColorSpace} space - color space name or adapter instance
  * @returns {Record<string|number, string>}
  */
-export function shadesOf(name, space = 'rgb') {
+export function shadesOf(name: string, space: string | Adapter = 'rgb'): Record<string, string> {
 	const adapter = typeof space === 'string' ? ColorSpace.create(space) : space
 
-	return shades.reduce(
+	return shades.reduce<Record<string, string>>(
 		(result, shade) => ({
 			...result,
 			[shade]: adapter.themeColor(`--color-${name}-${shade}`)
@@ -39,7 +54,7 @@ export function shadesOf(name, space = 'rgb') {
  * @param {import('./color-space').ColorSpace} adapter - ColorSpace adapter instance.
  * @returns {import('./types').ShadeMappings} An array containing the color rules for both light and dark modes.
  */
-function generateColorRules(variant, colors, mapping, adapter) {
+function generateColorRules(variant: string, colors: Colors, mapping: Mapping, adapter: Adapter) {
 	return ['DEFAULT', ...shades].flatMap((shade) => [
 		{
 			key: shade === 'DEFAULT' ? `--color-${variant}` : `--color-${variant}-${shade}`,
@@ -56,14 +71,18 @@ function generateColorRules(variant, colors, mapping, adapter) {
  * @param {string} [colorSpace] - Color space name 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, colorSpace) {
+export function themeRules(
+	mapping: Mapping = DEFAULT_THEME_MAPPING,
+	colors: Colors = DEFAULT_COLORS,
+	colorSpace?: string
+): Record<string, string> {
 	mapping = { ...DEFAULT_THEME_MAPPING, ...mapping }
-	colors = { ...defaultColors, ...colors }
+	colors = { ...(DEFAULT_COLORS), ...colors }
 	const adapter = ColorSpace.create(colorSpace || 'rgb')
 	const variants = Object.keys(mapping)
 	const rules = variants
 		.flatMap((variant) => generateColorRules(variant, colors, mapping, adapter))
-		.reduce((acc, { key, value }) => ({ ...acc, [key]: value }), {})
+		.reduce<Record<string, string>>((acc, { key, value }) => ({ ...acc, [key]: value }), {})
 
 	return rules
 }
@@ -84,10 +103,13 @@ export function themeRules(mapping = DEFAULT_THEME_MAPPING, colors = defaultColo
  * @param {string} [onColor='#fafafa'] - resolved on-color hex for this role
  * @returns {Array} Array of shortcut definitions
  */
-export function contrastShortcuts(name, onColor = '#fafafa') {
+export function contrastShortcuts(name: string, onColor = '#fafafa') {
 	return [
-		[new RegExp(`^text-on-${name}(\\/\\d+)?$`), ([, end]) => `text-[${onColor}]${end || ''}`],
-		[new RegExp(`^text-on-${name}-muted(\\/\\d+)?$`), ([, end]) => `text-[${onColor}]${end || ''}`]
+		[new RegExp(`^text-on-${name}(\\/\\d+)?$`), ([, end]: string[]) => `text-[${onColor}]${end || ''}`],
+		[
+			new RegExp(`^text-on-${name}-muted(\\/\\d+)?$`),
+			([, end]: string[]) => `text-[${onColor}]${end || ''}`
+		]
 	]
 }
 
@@ -128,7 +150,7 @@ export function pickOnColor(y: number | null): string {
  * Fallback chain for nullable color mappings.
  * If a semantic color is null, it inherits from another semantic color.
  */
-const COLOR_FALLBACKS = {
+const COLOR_FALLBACKS: Record<string, keyof typeof DEFAULT_THEME_MAPPING> = {
 	ink: 'surface',
 	tertiary: 'primary',
 	secondary: 'primary',
@@ -141,30 +163,34 @@ const COLOR_FALLBACKS = {
  * @param {Record<string, string | null>} mapping
  * @returns {Record<string, string>}
  */
-function resolveColors(mapping) {
+function resolveColors(mapping: Record<string, string | null | undefined>): 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
+	return resolved as Mapping
 }
 
 /**
  * Theme class for managing color palettes, mappings, and semantic shortcuts.
  */
 export class Theme {
-	#colors
-	#mapping
-	#adapter
+	#colors: Colors
+	#mapping: Mapping
+	#adapter: Adapter
 
 	/**
 	 *
 	 * @param {import('./types.js').ColorTheme & { colorSpace?: string }} param0
 	 */
-	constructor({ colors = defaultColors, mapping = DEFAULT_THEME_MAPPING, colorSpace = 'rgb' } = {}) {
-		this.#colors = { ...defaultColors, ...colors }
+	constructor({
+		colors = DEFAULT_COLORS,
+		mapping = DEFAULT_THEME_MAPPING as Record<string, string | null>,
+		colorSpace = 'rgb'
+	}: { colors?: Colors; mapping?: Record<string, string | null>; colorSpace?: string } = {}) {
+		this.#colors = { ...(DEFAULT_COLORS), ...colors }
 		this.#mapping = resolveColors({ ...DEFAULT_THEME_MAPPING, ...mapping })
 		this.#adapter = ColorSpace.create(colorSpace)
 	}
@@ -172,26 +198,26 @@ export class Theme {
 	get colors() {
 		return this.#colors
 	}
-	set colors(colors) {
+	set colors(colors: Colors) {
 		this.#colors = { ...colors }
 	}
 
 	get mapping() {
 		return this.#mapping
 	}
-	set mapping(mapping) {
+	set mapping(mapping: Record<string, string | null>) {
 		this.#mapping = resolveColors({ ...mapping })
 	}
 
 	get colorSpace() {
 		return this.#adapter.name
 	}
-	set colorSpace(colorSpace) {
+	set colorSpace(colorSpace: string) {
 		this.#adapter = ColorSpace.create(colorSpace)
 	}
 
-	mapVariant(color, variant) {
-		return Object.keys(color).reduce(
+	mapVariant(color: Palette, variant: string): Record<string, string> {
+		return Object.keys(color).reduce<Record<string, string>>(
 			(acc, key) => ({
 				...acc,
 				[key]:
@@ -203,9 +229,9 @@ export class Theme {
 		)
 	}
 
-	getColorRules(mapping = null) {
+	getColorRules(mapping: Mapping | null = null): Record<string, Record<string, string>> {
 		const variants = Object.entries({ ...this.#mapping, ...mapping })
-		return variants.reduce(
+		return variants.reduce<Record<string, Record<string, string>>>(
 			(acc, [variant, key]) => ({
 				...acc,
 				[variant]: this.mapVariant(this.#colors[key], variant)
@@ -214,13 +240,13 @@ export class Theme {
 		)
 	}
 
-	getPalette(mapping = null) {
+	getPalette(mapping: Mapping | null = null): Record<string, string> {
 		const useMapping = { ...this.#mapping, ...mapping }
-		const useColors = { ...defaultColors, ...this.#colors }
+		const useColors = { ...(DEFAULT_COLORS), ...this.#colors }
 		const variants = Object.keys(useMapping)
 		const rules = variants
 			.flatMap((variant) => generateColorRules(variant, useColors, useMapping, this.#adapter))
-			.reduce((acc, { key, value }) => ({ ...acc, [key]: value }), {})
+			.reduce<Record<string, string>>((acc, { key, value }) => ({ ...acc, [key]: value }), {})
 		return rules
 	}
 
@@ -245,7 +271,7 @@ export class Theme {
 	 *   (and for the whole map when undefined).
 	 */
 	getNamedTokens(_mode = 'light', perRoleModes?: Record<string, 'core' | 'extended'>) {
-		const colors = { ...defaultColors, ...this.#colors }
+		const colors: Colors = { ...(DEFAULT_COLORS), ...this.#colors }
 		const result: Record<string, string> = {}
 		for (const name of NAMED_TOKENS) {
 			const value = this.#resolveNamedToken(name, colors, perRoleModes)
@@ -258,7 +284,7 @@ export class Theme {
 	 * Resolves a single named token to its CSS value, respecting per-role mode.
 	 * Returns undefined when the role's palette is missing.
 	 */
-	#resolveNamedToken(name: string, colors: Record<string, Record<string, string>>, perRoleModes?: Record<string, 'core' | 'extended'>): string | undefined {
+	#resolveNamedToken(name: NamedToken, colors: Record<string, Record<string, string>>, perRoleModes?: Record<string, 'core' | 'extended'>): string | undefined {
 		const role = NAMED_TOKEN_ROLE_MAP[name]
 		const shadeOrDerived = NAMED_TOKEN_SHADE_MAP[name]
 		const paletteName = this.#mapping[role]
@@ -330,7 +356,7 @@ export class Theme {
 	 * or near-white), matching the core-mode derivation.
 	 */
 	getZAliasesForExtended(): Record<string, string> {
-		const colors = { ...defaultColors, ...this.#colors }
+		const colors: Colors = { ...(DEFAULT_COLORS), ...this.#colors }
 		const result: Record<string, string> = {}
 		for (const name of NAMED_TOKENS) {
 			const role = NAMED_TOKEN_ROLE_MAP[name]
@@ -350,7 +376,7 @@ export class Theme {
 	 * Mirrors what getPalette does for all roles, but scoped to one.
 	 */
 	getPaletteForRole(role: string): Record<string, string> {
-		const colors = { ...defaultColors, ...this.#colors }
+		const colors: Colors = { ...(DEFAULT_COLORS), ...this.#colors }
 		const paletteName = this.#mapping[role]
 		if (!paletteName || !colors[paletteName]) return {}
 		const palette = colors[paletteName]
@@ -363,8 +389,8 @@ export class Theme {
 		return result
 	}
 
-	getShortcuts(name) {
-		const colors = { ...defaultColors, ...this.#colors }
+	getShortcuts(name: string) {
+		const colors: Colors = { ...(DEFAULT_COLORS), ...this.#colors }
 		return contrastShortcuts(name, this.#onColorHex(name, colors))
 	}