@rokkit/core 1.0.0-next.125 → 1.0.0-next.129

package/dist/utils.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Detects text direction based on HTML lang attribute
+ * @returns {'ltr' | 'rtl'}
+ */
+export function detectDirection(): "ltr" | "rtl";
+/**
+ * Checks if current document direction is RTL
+ * @returns {boolean}
+ */
+export function isRTL(): boolean;
 /**
  * Finds the closest ancestor of the given element that has the given attribute.
  *
@@ -67,6 +77,21 @@ export function getPathFromKey(key: string): string[];
  * @returns {Function|undefined}
  */
 export function getSnippet(obj: Object, key: string, defaultSnippet?: null | Function): Function | undefined;
+/**
+ * Resolve which snippet to render for a proxy item.
+ *
+ * Checks proxy.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 {string} [fallback]                  - fallback snippet name; defaults to ITEM_SNIPPET ('itemContent')
+ * @returns {Function | null}
+ */
+export function resolveSnippet(snippets: Record<string, unknown>, proxy: {
+    snippet?: string | null;
+}, fallback?: string): Function | null;
 /**
  * convert hex string to `{r} {g} {b}`
  * @param {string} hex
@@ -80,4 +105,3 @@ export function hex2rgb(hex: string): string;
  * @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 function importIcons(icons: Object): Object;

package/dist/vite/icon-collections.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Creates icon collection loaders for UnoCSS presetIcons from a simple config.
+ *
+ * This function transforms a map of collection names to JSON package paths
+ * into the format expected by UnoCSS's presetIcons.
+ *
+ * Supports three types of paths:
+ * - Package paths (e.g., '@rokkit/icons/ui.json') - resolved via require
+ * - Absolute paths (e.g., '/path/to/icons.json') - used directly
+ * - Relative paths (e.g., './static/icons.json') - resolved from process.cwd()
+ *
+ * @example
+ * // uno.config.js
+ * import { iconCollections } from '@rokkit/core/vite'
+ *
+ * export default defineConfig({
+ *   presets: [
+ *     presetIcons({
+ *       collections: iconCollections({
+ *         rokkit: '@rokkit/icons/ui.json',
+ *         logo: '@rokkit/icons/auth.json',
+ *         solar: '@iconify-json/solar/icons.json',
+ *         custom: './static/icons/custom.json'
+ *       })
+ *     })
+ *   ]
+ * })
+ *
+ * @param {Record<string, string>} config - Map of collection alias to JSON path
+ * @returns {Record<string, () => any>} Collections object for presetIcons
+ */
+export function iconCollections(config: Record<string, string>): Record<string, () => any>;

package/dist/vite/index.d.ts

@@ -0,0 +1 @@
+export { iconCollections } from "./icon-collections.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/core",
-  "version": "1.0.0-next.125",
+  "version": "1.0.0-next.129",
   "description": "Contains core utility functions and classes that can be used in various components.",
   "author": "Jerry Thomas <me@jerrythomas.name>",
   "license": "MIT",
@@ -27,10 +27,18 @@
       "types": "./dist/index.d.ts",
       "import": "./src/index.js",
       "svelte": "./src/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite/index.d.ts",
+      "import": "./src/vite/index.js"
     }
   },
   "dependencies": {
+    "@unocss/preset-mini": "^66.6.1",
     "date-fns": "^4.1.0",
-    "ramda": "^0.31.3"
+    "ramda": "^0.32.0"
+  },
+  "devDependencies": {
+    "@rokkit/icons": "1.0.0-next.129"
   }
 }

package/src/constants.js

@@ -1,9 +1,17 @@
-export { defaultColors, syntaxColors, shades, defaultPalette } from './colors/index.js'
+export { defaultColors, syntaxColors, shades, defaultPalette } from './colors/index'
 export const DATA_IMAGE_REGEX = /^data:image\/(jpeg|png|gif|bmp|webp|svg\+xml)/i
+
+// ─── Snippet names ────────────────────────────────────────────────────────────
+
+export const ITEM_SNIPPET = 'itemContent'
+export const GROUP_SNIPPET = 'groupContent'
 /**
+ * @deprecated Use BASE_FIELDS from @rokkit/core instead.
+ * Retained for legacy ListController/FieldMapper/Proxy consumers (Toolbar, Table).
+ * Will be removed when those components migrate to Wrapper+Navigator.
  * @type {import('./types).FieldMapping} Fields
  */
-export const defaultFields = {
+export const DEFAULT_FIELDS = {
 	id: 'id',
 	href: 'href',
 	icon: 'icon',
@@ -24,26 +32,83 @@ export const defaultFields = {
 	label: 'label',
 	component: 'component', // to be deprecated in favour of snippet
 	snippet: 'snippet',
+	disabled: 'disabled',
 	/* flag fields  */
 	deleted: '_deleted',
 	expanded: '_expanded',
 	selected: '_selected'
 }
 
-export const defaultIcons = [
+// ─── BASE_FIELDS ─────────────────────────────────────────────────────────────
+// Canonical field mapping for ProxyItem and all Wrapper+Navigator components.
+// Semantic keys map to common raw data keys for backward compatibility.
+
+export const BASE_FIELDS = {
+	// Identity
+	id: 'id',
+	value: 'value',
+	// Display
+	label: 'label',
+	icon: 'icon',
+	avatar: 'image',
+	subtext: 'description',
+	tooltip: 'title',
+	badge: 'badge',
+	shortcut: 'shortcut',
+	// Structure
+	children: 'children',
+	type: 'type',
+	snippet: 'snippet',
+	href: 'href',
+	hrefTarget: 'target',
+	// State
+	disabled: 'disabled',
+	expanded: 'expanded',
+	selected: 'selected',
+}
+
+const LEGACY_KEY_MAP = { description: 'subtext', title: 'tooltip', image: 'avatar', target: 'hrefTarget' }
+
+/**
+ * Remap legacy field-override keys to their BASE_FIELDS semantic equivalents.
+ * e.g. { text: 'name' } → { label: 'name' }
+ *
+ * @param {Record<string, string> | null | undefined} fields
+ * @returns {Record<string, string>}
+ */
+export function normalizeFields(fields) {
+	if (!fields || typeof fields !== 'object') return {}
+	const result = {}
+	for (const [key, value] of Object.entries(fields)) {
+		result[LEGACY_KEY_MAP[key] ?? key] = value
+	}
+	return result
+}
+
+export const DEFAULT_ICONS = [
 	'accordion-opened',
 	'accordion-closed',
 	'action-remove',
+	'action-cancel',
+	'action-retry',
 	'action-add',
 	'action-clear',
 	'action-search',
 	'action-close',
 	'action-copy',
 	'action-copysuccess',
+	'action-check',
+	'action-pin',
+	'action-save',
+	'action-unpin',
 	'node-opened',
 	'node-closed',
+	'folder-opened',
+	'folder-closed',
 	'selector-opened',
 	'selector-closed',
+	'menu-opened',
+	'menu-closed',
 	'checkbox-checked',
 	'checkbox-unchecked',
 	'checkbox-unknown',
@@ -54,10 +119,13 @@ export const defaultIcons = [
 	'radio-on',
 	'mode-dark',
 	'mode-light',
+	'mode-system',
 	'navigate-left',
 	'navigate-right',
 	'navigate-up',
 	'navigate-down',
+	'palette-hex',
+	'palette-presets',
 	'state-error',
 	'state-warning',
 	'state-success',
@@ -84,14 +152,14 @@ export const defaultIcons = [
 	'align-vertical-middle'
 ]
 
-export const defaultOptions = {
+export const DEFAULT_OPTIONS = {
 	id: 'id',
 	label: 'label',
 	value: 'value',
 	checked: 'checked'
 }
 
-export const defaultKeyMap = {
+export const DEFAULT_KEYMAP = {
 	ArrowRight: 'open',
 	ArrowLeft: 'close',
 	ArrowDown: 'down',
@@ -100,7 +168,7 @@ export const defaultKeyMap = {
 	Escape: 'deselect'
 }
 
-export const defaultThemeMapping = {
+export const DEFAULT_THEME_MAPPING = {
 	surface: 'slate',
 	primary: 'orange',
 	secondary: 'pink',
@@ -124,15 +192,6 @@ export const TONE_MAP = {
 	z8: 800,
 	z9: 900,
 	z10: 950
-	// base: 50,
-	// inset: 100,
-	// subtle: 200,
-	// muted: 300,
-	// raised: 400,
-	// elevated: 600,
-	// floating: 700,
-	// contrast: 800,
-	// overlay: 900
 }
 /**
  * Splits an icon name into its group and key components.
@@ -161,4 +220,4 @@ export function stateIconsFromNames(icons) {
 	)
 }
 
-export const defaultStateIcons = stateIconsFromNames(defaultIcons)
+export const DEFAULT_STATE_ICONS = stateIconsFromNames(DEFAULT_ICONS)

package/src/field-mapper.js

@@ -1,12 +1,12 @@
 import { isNil, has, omit } from 'ramda'
-import { defaultFields } from './constants.js'
+import { DEFAULT_FIELDS } from './constants.js'
 import { isObject } from './utils.js'
 
 export class FieldMapper {
-	#fields = { ...defaultFields }
+	#fields = { ...DEFAULT_FIELDS }
 	#childMapper = null
 
-	constructor(fields = defaultFields) {
+	constructor(fields = DEFAULT_FIELDS) {
 		this.#updateFields(fields)
 	}
 
@@ -16,7 +16,6 @@ export class FieldMapper {
 		})
 		this.hasIcon = has(this.#fields.icon)
 		this.hasImage = has(this.#fields.image)
-		this.hasText = has(this.#fields.text)
 		this.hasValue = has(this.#fields.value)
 		this.hasLabel = has(this.#fields.label)
 		this.hasComponent = has(this.#fields.component)
@@ -47,7 +46,7 @@ export class FieldMapper {
 			return value[this.fields[fieldName]]
 		}
 
-		return fieldName === 'text' ? value : null
+		return fieldName === 'label' ? value : null
 	}
 
 	/**
@@ -83,7 +82,7 @@ export class FieldMapper {
 	}
 
 	getFormattedText(value, formatter) {
-		const text = this.get('text', value)
+		const text = this.get('label', value)
 
 		if (isNil(text)) return ''
 

package/src/index.js

@@ -16,4 +16,4 @@ export { createEmitter } from './events.js'
 export { getLineTypes } from './connector.js'
 export { weekdays, getCalendarDays } from './calendar.js'
 export { generateTicks } from './ticks.js'
-export { getValue, getNestedFields, hasChildren, isExpanded } from './mapping.js'
+export { getNestedFields } from './mapping.js'

package/src/key-event-map.js

@@ -26,7 +26,7 @@ export class KeyEventMap {
 	 * @returns {string|null} - The event name or null if no match is found.
 	 */
 	getEventForKey(key) {
-		// eslint-disable-next-line no-unused-vars
+		 
 		const matchEvent = ([_, keys]) =>
 			(Array.isArray(keys) && keys.includes(key)) || (keys instanceof RegExp && keys.test(key))
 

package/src/mapping.js

@@ -1,73 +1,4 @@
-import { defaultFields } from './constants.js'
-import { toString, isObject } from './utils.js'
-import { has } from 'ramda'
-/**
- * Get the component to be used to render the item.
- * If the component is null or undefined, it will return the default component.
- *
- * @param {object|string}                     value
- * @param {import('./types.js').FieldMapping} fields
- * @param {import('./types.js').ComponentMap} using
- */
-export function getComponent(value, fields, using) {
-	return fields.component && isObject(value)
-		? (using[value[fields.component]] ?? using.default)
-		: using.default
-}
-
-/**
- * Get the icon for the item. If the icon is an object, it will use the state to determine which icon to use.
- *
- * @param {object}                            value
- * @param {import('./types.js').FieldMapping} fields
- * @returns {string}
- */
-function getIconFromObject(value, fields) {
-	if (!value) return null
-	if (typeof value[fields.icon] === 'object') return value[fields.icon][value[fields.state]]
-	return value[fields.icon]
-}
-
-/**
- * Get the icon for the item. If the icon is an object, it will use the state to determine which icon to use.
- *
- * @param {object|string}                     value
- * @param {import('./types.js').FieldMapping} fields
- * @returns {string}
- */
-export function getIcon(value, fields = defaultFields) {
-	if (fields.icon === undefined || typeof value !== 'object') return null
-
-	const name = getIconFromObject(value, fields)
-	return name ? [fields.iconPrefix, name].join('-').replace(/^-+/g, '') : null
-}
-
-/**
- * Get the value for the item. If the value is an object,
- * it will use the field mapping to determine which attribute to get.
- *
- * @param {*}                              node
- * @param {import('./types').FieldMapping} fields
- * @returns {*}
- */
-export function getValue(node, fields = defaultFields) {
-	return typeof node === 'object' && node !== null
-		? (node[fields.value] ?? node[fields.text])
-		: node
-}
-
-/**
- * Get the text for the item. If the text is an object,
- * it will use the field mapping to determine which attribute to get.
- *
- * @param {*}                              node
- * @param {import('./types').FieldMapping} fields
- * @returns {string}
- */
-export function getText(node, fields = defaultFields) {
-	const value = isObject(node) ? node[fields.text] : node
-	return value
-}
+import { DEFAULT_FIELDS } from './constants.js'
 
 /**
  * Gets the attribute from the node
@@ -79,50 +10,6 @@ export function getAttribute(node, attr) {
 	return typeof node === 'object' && node !== null && attr !== null ? node[attr] : null
 }
 
-/**
- * Get the formatted text for the item. If the text is an object, use the field mapping to determine
- * which attribute to get currency. Use the formatter or identity function to format the text.
- *
- * @param {*}                              node
- * @param {import('./types').FieldMapping} fields
- * @param {Function}                       formatter
- * @returns {Function}
- */
-export function getFormattedText(node, fields = defaultFields, formatter = toString) {
-	const value = getText(node, fields)
-	const currency = getAttribute(node, fields.currency)
-	const formatValue = typeof formatter === 'function' ? formatter : toString
-
-	return currency ? formatValue(value, currency) : formatValue(value)
-}
-
-/**
- * Check if the current item is a parent
- *
- * @param {*}                              item
- * @param {import('./types').FieldMapping} fields
- * @returns {boolean}
- */
-export function hasChildren(item, fields) {
-	return has(fields.children, item) && Array.isArray(item[fields.children])
-}
-
-/**
- * Check if the current item is a parent and is expanded
- *
- * @param {*}                              item
- * @param {import('./types').FieldMapping} fields
- * @returns {boolean}
- */
-export function isExpanded(item, fields) {
-	if (item === null) return false
-	if (!hasChildren(item, fields)) return false
-	if (has(fields.expanded, item)) {
-		return item[fields.expanded]
-	}
-	return false
-}
-
 /**
  * Fetches the fieldmapping for a child node
  *
@@ -130,5 +17,5 @@ export function isExpanded(item, fields) {
  * @returns {import('./types').FieldMapping}
  */
 export function getNestedFields(fields) {
-	return { ...defaultFields, ...(fields.fields ?? fields) }
+	return { ...DEFAULT_FIELDS, ...(fields.fields ?? fields) }
 }

package/src/nested.js

@@ -1,5 +1,5 @@
 import { omit } from 'ramda'
-import { defaultFields } from './constants.js'
+import { DEFAULT_FIELDS } from './constants.js'
 
 /**
  * Flattens a nested list of items
@@ -9,8 +9,8 @@ import { defaultFields } from './constants.js'
  * @param {number}                        level
  * @returns {Array}
  */
-export function flattenNestedList(items, fields = defaultFields, level = 0) {
-	fields = { ...defaultFields, ...fields }
+export function flattenNestedList(items, fields = DEFAULT_FIELDS, level = 0) {
+	fields = { ...DEFAULT_FIELDS, ...fields }
 	let data = []
 	items.forEach((item) => {
 		const children = item[fields.children] ?? []
@@ -26,31 +26,3 @@ export function flattenNestedList(items, fields = defaultFields, level = 0) {
 	})
 	return data
 }
-
-/**
- * Matches a path slug to a value in the menu
- *
- * @param {string}                         slug
- * @param {Array}                          data
- * @param {import('./types').FieldMapping} fields
- * @returns {any}
- */
-export function findValueFromPath(slug, data, fields) {
-	fields = { ...defaultFields, ...fields }
-	const keys = slug.split('/')
-	let items = data
-	let value = null
-
-	keys.forEach((key, index) => {
-		const match = items.find((item) => item[fields.key] === key)
-		if (match) {
-			if (index < keys.length - 1) {
-				match[fields.isOpen] = true
-				items = match[fields.children]
-			} else {
-				value = match
-			}
-		}
-	})
-	return value
-}

package/src/utils.js

@@ -1,7 +1,54 @@
 import { has, isNil } from 'ramda'
-import { DATA_IMAGE_REGEX } from './constants'
+import { DATA_IMAGE_REGEX, ITEM_SNIPPET } from './constants'
 
 let idCounter = 0
+
+/**
+ * RTL language codes (ISO 639-1)
+ * @type {string[]}
+ */
+const RTL_LANGUAGES = [
+	'ar', // Arabic
+	'he', // Hebrew
+	'fa', // Persian/Farsi
+	'ur', // Urdu
+	'yi', // Yiddish
+	'ps', // Pashto
+	'sd', // Sindhi
+	'ug', // Uyghur
+	'ku', // Kurdish (Sorani)
+	'dv' // Divehi/Maldivian
+]
+
+/**
+ * Detects text direction based on HTML lang attribute
+ * @returns {'ltr' | 'rtl'}
+ */
+export function detectDirection() {
+	if (typeof document === 'undefined') return 'ltr'
+
+	// Check dir attribute first (explicit override)
+	const htmlDir = document.documentElement.getAttribute('dir')
+	if (htmlDir === 'rtl' || htmlDir === 'ltr') return htmlDir
+
+	// Detect from lang attribute
+	const lang = document.documentElement.getAttribute('lang')
+	if (lang) {
+		// Extract primary language code (e.g., 'ar-SA' -> 'ar')
+		const primaryLang = lang.split('-')[0].toLowerCase()
+		if (RTL_LANGUAGES.includes(primaryLang)) return 'rtl'
+	}
+
+	return 'ltr'
+}
+
+/**
+ * Checks if current document direction is RTL
+ * @returns {boolean}
+ */
+export function isRTL() {
+	return detectDirection() === 'rtl'
+}
 /**
  * Finds the closest ancestor of the given element that has the given attribute.
  *
@@ -123,19 +170,22 @@ export function getSnippet(obj, key, defaultSnippet = null) {
 }
 
 /**
- * Creates a collection of icon import functions based on an icons dictionary
+ * Resolve which snippet to render for a proxy item.
  *
- * @param {Object} icons - Dictionary mapping collection names to file paths
- * @returns {Object} Collections object with functions that dynamically import icon files
+ * Checks proxy.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 {string} [fallback]                  - fallback snippet name; defaults to ITEM_SNIPPET ('itemContent')
+ * @returns {Function | null}
  */
-export const importIcons = (icons) => {
-	if (!icons) return {}
-
-	return Object.entries(icons).reduce((acc, [key, value]) => {
-		acc[key] = () =>
-			import(/* @vite-ignore */ value, { with: { type: 'json' } }).then((i) => i.default)
-		return acc
-	}, {})
+export function resolveSnippet(snippets, proxy, fallback = ITEM_SNIPPET) {
+	const name = proxy?.snippet
+	if (name && typeof snippets[name] === 'function') return snippets[name]
+	const fb = snippets[fallback]
+	return typeof fb === 'function' ? fb : null
 }
 
 /**
@@ -178,8 +228,8 @@ function isImageUrl(str) {
 
 		// Fallback if URL constructor is not available
 		return fallbackValidation()
-		// eslint-disable-next-line no-unused-vars
-	} catch (e) {
+		 
+	} catch {
 		// Fallback if URL constructor fails
 		return fallbackValidation()
 	}

package/src/vite/icon-collections.js

@@ -0,0 +1,73 @@
+import { createRequire } from 'module'
+import { resolve, isAbsolute } from 'path'
+import { readFileSync } from 'fs'
+
+// Two require contexts: CWD (for site-specific packages like @iconify-json/*)
+// and the module's own location (for workspace packages like @rokkit/icons).
+const requireFromCwd = createRequire(resolve(process.cwd(), 'package.json'))
+const requireFromModule = createRequire(import.meta.url)
+
+function requirePackage(jsonPath) {
+	try {
+		return requireFromCwd(jsonPath)
+	} catch {
+		return requireFromModule(jsonPath)
+	}
+}
+
+/**
+ * Creates icon collection loaders for UnoCSS presetIcons from a simple config.
+ *
+ * This function transforms a map of collection names to JSON package paths
+ * into the format expected by UnoCSS's presetIcons.
+ *
+ * Supports three types of paths:
+ * - Package paths (e.g., '@rokkit/icons/ui.json') - resolved via require
+ * - Absolute paths (e.g., '/path/to/icons.json') - used directly
+ * - Relative paths (e.g., './static/icons.json') - resolved from process.cwd()
+ *
+ * @example
+ * // uno.config.js
+ * import { iconCollections } from '@rokkit/core/vite'
+ *
+ * export default defineConfig({
+ *   presets: [
+ *     presetIcons({
+ *       collections: iconCollections({
+ *         rokkit: '@rokkit/icons/ui.json',
+ *         logo: '@rokkit/icons/auth.json',
+ *         solar: '@iconify-json/solar/icons.json',
+ *         custom: './static/icons/custom.json'
+ *       })
+ *     })
+ *   ]
+ * })
+ *
+ * @param {Record<string, string>} config - Map of collection alias to JSON path
+ * @returns {Record<string, () => any>} Collections object for presetIcons
+ */
+export function iconCollections(config) {
+	if (!config || typeof config !== 'object') {
+		return {}
+	}
+
+	return Object.entries(config).reduce((acc, [alias, jsonPath]) => {
+		acc[alias] = () => {
+			// Check if it's a relative path (starts with ./ or ../)
+			if (jsonPath.startsWith('./') || jsonPath.startsWith('../')) {
+				// Resolve relative to current working directory (where the config is)
+				const absolutePath = resolve(process.cwd(), jsonPath)
+				return JSON.parse(readFileSync(absolutePath, 'utf-8'))
+			}
+
+			// Check if it's an absolute path
+			if (isAbsolute(jsonPath)) {
+				return JSON.parse(readFileSync(jsonPath, 'utf-8'))
+			}
+
+			// Otherwise treat as a package path; try CWD first (site packages), then module location
+			return requirePackage(jsonPath)
+		}
+		return acc
+	}, {})
+}

package/src/vite/index.js

@@ -0,0 +1 @@
+export { iconCollections } from './icon-collections.js'