@rokkit/core 1.3.1 → 1.3.3

package/dist/index.d.ts

@@ -5,11 +5,11 @@ export * from "./utils.js";
 export * from "./nested.js";
 export * from "./string.js";
 export * from "./theme.js";
-export { ColorSpace } from "./color-space.js";
 export { FieldMapper } from "./field-mapper.js";
 export { createEmitter } from "./events.js";
 export { getLineTypes } from "./connector.js";
 export { generateTicks } from "./ticks.js";
 export { getNestedFields } from "./mapping.js";
+export { ColorSpace, relativeLuminance } from "./color-space.js";
 export { getItemAtIndex, getIndexForItem } from "./mapped-items.js";
 export { weekdays, getCalendarDays } from "./calendar.js";

package/dist/theme.d.ts

@@ -46,6 +46,34 @@ export declare function themeRules(mapping: {
  * @returns {Array} Array of shortcut definitions
  */
 export declare function contrastShortcuts(name: any, onColor?: string): (RegExp | (([, end]: [any, any]) => string))[][];
+/**
+ * Near-black / near-white on-color endpoints. Not pure #000/#fff — a hair of
+ * lift reads softer on a saturated fill while still clearing AA (near-black is
+ * dark enough that even a mid-bright vermillion 500 reaches ~5:1).
+ *
+ * Exported so consumers (e.g. the demo skin engine) reuse the EXACT library
+ * derivation rather than re-deriving on-colors and drifting from `Theme`.
+ */
+export declare const ON_COLOR_DARK = "#161616";
+export declare const ON_COLOR_LIGHT = "#fafafa";
+/**
+ * Fill luminance where ON_COLOR_DARK and ON_COLOR_LIGHT give equal WCAG contrast:
+ * solve (Yf+0.05)² = (Y_dark+0.05)(Y_light+0.05) with Y_dark≈0.0074, Y_light≈0.956
+ * → Yf ≈ 0.190. Fills at/above this take dark text; below take light text. (Truly
+ * mid-luminance fills near this point clear neither pair at AA — that's the
+ * palette author's choice to make, per "pick a 500 where black or white works".)
+ */
+export declare const ON_COLOR_Y_CROSSOVER = 0.19;
+/**
+ * Pick the readable on-color hex for a fill of relative luminance `y`.
+ * Bright fills (y at/above the crossover) take near-black text; dark fills take
+ * near-white. A null `y` means the fill couldn't be measured → near-white
+ * (matches the historical default).
+ *
+ * @param {number | null} y - relative luminance (0–1) of the fill, or null
+ * @returns {string} on-color hex
+ */
+export declare function pickOnColor(y: number | null): string;
 /**
  * Theme class for managing color palettes, mappings, and semantic shortcuts.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/core",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "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.3.1"
+    "@rokkit/icons": "1.3.3"
   }
 }

package/src/index.js

@@ -11,7 +11,7 @@ export * from './nested.js'
 export * from './string.js'
 // skipcq: JS-E1004 - Needed for exposing all functions
 export * from './theme.js'
-export { ColorSpace } from './color-space.js'
+export { ColorSpace, relativeLuminance } from './color-space.js'
 export { FieldMapper } from './field-mapper.js'
 export { getItemAtIndex, getIndexForItem } from './mapped-items.js'
 export { createEmitter } from './events.js'

package/src/theme.ts

@@ -95,9 +95,12 @@ export function contrastShortcuts(name, onColor = '#fafafa') {
  * Near-black / near-white on-color endpoints. Not pure #000/#fff — a hair of
  * lift reads softer on a saturated fill while still clearing AA (near-black is
  * dark enough that even a mid-bright vermillion 500 reaches ~5:1).
+ *
+ * Exported so consumers (e.g. the demo skin engine) reuse the EXACT library
+ * derivation rather than re-deriving on-colors and drifting from `Theme`.
  */
-const ON_COLOR_DARK = '#161616'
-const ON_COLOR_LIGHT = '#fafafa'
+export const ON_COLOR_DARK = '#161616'
+export const ON_COLOR_LIGHT = '#fafafa'
 /**
  * Fill luminance where ON_COLOR_DARK and ON_COLOR_LIGHT give equal WCAG contrast:
  * solve (Yf+0.05)² = (Y_dark+0.05)(Y_light+0.05) with Y_dark≈0.0074, Y_light≈0.956
@@ -105,7 +108,21 @@ const ON_COLOR_LIGHT = '#fafafa'
  * mid-luminance fills near this point clear neither pair at AA — that's the
  * palette author's choice to make, per "pick a 500 where black or white works".)
  */
-const ON_COLOR_Y_CROSSOVER = 0.19
+export const ON_COLOR_Y_CROSSOVER = 0.19
+
+/**
+ * Pick the readable on-color hex for a fill of relative luminance `y`.
+ * Bright fills (y at/above the crossover) take near-black text; dark fills take
+ * near-white. A null `y` means the fill couldn't be measured → near-white
+ * (matches the historical default).
+ *
+ * @param {number | null} y - relative luminance (0–1) of the fill, or null
+ * @returns {string} on-color hex
+ */
+export function pickOnColor(y: number | null): string {
+	if (y === null) return ON_COLOR_LIGHT
+	return y >= ON_COLOR_Y_CROSSOVER ? ON_COLOR_DARK : ON_COLOR_LIGHT
+}
 
 /**
  * Fallback chain for nullable color mappings.
@@ -284,8 +301,7 @@ export class Theme {
 		const palette = colors[this.#mapping[role]]
 		const fill = palette?.['500']
 		const y = fill !== undefined ? relativeLuminance(fill, this.#adapter.name) : null
-		if (y === null) return ON_COLOR_LIGHT
-		return y >= ON_COLOR_Y_CROSSOVER ? ON_COLOR_DARK : ON_COLOR_LIGHT
+		return pickOnColor(y)
 	}
 
 	#surfaceInkAlias(role: 'surface' | 'ink'): Record<string, string> {