@rokkit/core 1.3.0 → 1.3.2

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.0",
+  "version": "1.3.2",
   "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.0"
+    "@rokkit/icons": "1.3.2"
   }
 }

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.
@@ -270,6 +287,7 @@ export class Theme {
 		if (name === 'on-primary') {
 			return this.#adapter.wrap(this.#onColorHex('primary', colors))
 		}
+		/* v8 ignore next -- on-primary is the only 'derived' token, so this default is unreachable */
 		return undefined
 	}
 
@@ -283,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> {

package/src/utils.js

@@ -172,12 +172,13 @@ export function getSnippet(obj, key, defaultSnippet = null) {
 /**
  * Resolve which snippet to render for a proxy item.
  *
- * Checks proxy.snippet for a per-item named override first (e.g. item.snippet = 'highlighted').
+ * 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 {{ snippet?: string | null }} proxy  - any object with an optional .snippet property
+ * @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}
  */
@@ -190,7 +191,9 @@ function asSnippet(value) {
 }
 
 export function resolveSnippet(snippets, proxy, fallback = ITEM_SNIPPET) {
-	const name = proxy && proxy.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])
 }