@rokkit/states 1.0.0-next.125 → 1.0.0-next.128

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/states",
-  "version": "1.0.0-next.125",
+  "version": "1.0.0-next.128",
   "description": "Contains generic data manipulation functions that can be used in various components.",
   "author": "Jerry Thomas <me@jerrythomas.name>",
   "license": "MIT",
@@ -30,11 +30,10 @@
     }
   },
   "dependencies": {
-    "@lukeed/uuid": "^2.0.1",
-    "@rokkit/core": "1.0.0-next.125",
+    "@rokkit/core": "1.0.0-next.128",
+    "@rokkit/data": "1.0.0-next.128",
     "d3-array": "^3.2.4",
-    "d3-collection": "^1.0.7",
-    "ramda": "^0.31.3",
-    "svelte": "^5.39.2"
+    "ramda": "^0.32.0",
+    "svelte": "^5.53.5"
   }
 }

package/src/constants.js

@@ -9,6 +9,7 @@ export const DEFAULT_EVENTS = {
 
 export const VALID_DENSITIES = ['compact', 'comfortable', 'cozy']
 export const VALID_MODES = ['light', 'dark']
+export const VALID_DIRECTIONS = ['ltr', 'rtl']
 /** @type {string[]} */
 export const DEFAULT_STYLES = ['rokkit', 'minimal', 'material']
 

package/src/derive.svelte.js

@@ -1,52 +1,64 @@
-import { getKeyFromPath, defaultFields, getNestedFields } from '@rokkit/core'
-import { Proxy } from './proxy.svelte'
+import { getKeyFromPath, DEFAULT_FIELDS, getNestedFields } from '@rokkit/core'
 /**
  *
  * @param {Array<*>} items
  * @param {import('@rokkit/core').FieldMapping} fields
  * @param {Array<number>} path
- * @returns {Array<{ key: string, value: any }>}
+ * @param {Set<string>|null} expandedKeys - When provided, expansion is determined by key membership; falls back to item field
+ * @returns {Array<{ key: string, value: any, level: number, hasChildren: boolean }>}
  */
-export function flatVisibleNodes(items, fields = defaultFields, path = []) {
+export function flatVisibleNodes(items, fields = DEFAULT_FIELDS, path = [], expandedKeys = null) {
 	const data = []
+	if (!items || !Array.isArray(items)) return data
+
+	const level = path.length
+
 	items.forEach((item, index) => {
 		const itemPath = [...path, index]
 		const key = getKeyFromPath(itemPath)
-		const expanded =
-			Array.isArray(item[fields.children]) &&
-			item[fields.children].length > 0 &&
-			item[fields.expanded]
+		const hasChildren =
+			Array.isArray(item[fields.children]) && item[fields.children].length > 0
+		const expanded = hasChildren && (expandedKeys ? expandedKeys.has(key) : item[fields.expanded])
 
-		data.push({ key, value: item })
+		data.push({ key, value: item, level, hasChildren })
 
 		if (expanded) {
 			const childFields = getNestedFields(fields)
-			data.push(...flatVisibleNodes(item[fields.children], childFields, itemPath))
+			data.push(...flatVisibleNodes(item[fields.children], childFields, itemPath, expandedKeys))
 		}
 	})
 	return data
 }
 
 /**
- * Derives a flat lookup table for the given items, using index paths as keys
- * Each value is a Proxy instance for convenient manipulation
+ * Derives a flat lookup table for the given items, using index paths as keys.
+ * Each value is a lightweight wrapper exposing the original item as both
+ * `.value` and `.original` for backward compatibility, plus a `.get(field)`
+ * method that reads from the item via field mapping.
  *
  * @param {Array<*>} items - Source items array
  * @param {import('@rokkit/core').FieldMapping} fields - Field mappings configuration
  * @param {Array<number>} path - Current path in the tree
- * @returns {Map<string, Proxy>} - Map of path keys to Proxy instances
+ * @returns {Map<string, { value: *, original: *, label: string, get: (f: string) => * }>}
  */
-export function deriveLookupWithProxy(items, fields = defaultFields, path = []) {
+export function deriveLookupWithProxy(items, fields = DEFAULT_FIELDS, path = []) {
 	const lookup = new Map()
+	if (!items || !Array.isArray(items)) return lookup
 
 	items.forEach((item, index) => {
 		const itemPath = [...path, index]
 		const key = getKeyFromPath(itemPath)
-		const proxy = new Proxy(item, fields)
+		const norm = typeof item === 'object' && item !== null ? item : { [fields.text]: item }
+		const entry = {
+			value: item,
+			original: item,
+			label: String(norm[fields.text] ?? ''),
+			get: (fieldName) => norm[fields[fieldName] ?? fieldName]
+		}
 
-		lookup.set(key, proxy)
-		const children = proxy.value[proxy.fields.children] ?? []
-		if (children.length > 0) {
+		lookup.set(key, entry)
+		const children = norm[fields.children] ?? []
+		if (Array.isArray(children) && children.length > 0) {
 			const childFields = getNestedFields(fields)
 			const childLookup = deriveLookupWithProxy(children, childFields, itemPath)
 			for (const [childKey, childValue] of childLookup.entries()) {

package/src/index.js

@@ -1,5 +1,9 @@
-export { TableWrapper } from './tabular.svelte.js'
-export { Proxy } from './proxy.svelte.js'
+export { TableController } from './table-controller.svelte.js'
 export { vibe } from './vibe.svelte.js'
 export { ListController } from './list-controller.svelte.js'
-export { NestedController } from './nested-controller.svelte.js'
+export { messages } from './messages.svelte.js'
+export { ProxyItem, LazyProxyItem, BASE_FIELDS } from './proxy-item.svelte.js'
+export { ProxyTree } from './proxy-tree.svelte.js'
+export { Wrapper } from './wrapper.svelte.js'
+export { LazyWrapper } from './lazy-wrapper.svelte.js'
+export { watchMedia, defaultBreakpoints } from './media.svelte.js'

package/src/lazy-wrapper.svelte.js

@@ -0,0 +1,119 @@
+/**
+ * LazyWrapper
+ *
+ * Extends Wrapper with lazy-loading support for tree nodes that use
+ * LazyProxyItem. Overrides expand(), select(), and toggle() to detect
+ * unloaded sentinel nodes (proxy.loaded === false) and trigger fetch()
+ * before delegating to the base Wrapper behavior.
+ *
+ * Also provides loadMore() for root-level pagination via onlazyload callback.
+ *
+ * All navigation logic (next, prev, first, last, collapse, moveTo,
+ * moveToValue, findByText, cancel, blur, extend, range) is inherited
+ * from Wrapper — no duplication.
+ */
+
+import { Wrapper } from './wrapper.svelte.js'
+
+// ─── LazyWrapper ───────────────────────────────────────────────────────────────
+
+export class LazyWrapper extends Wrapper {
+	#onlazyload
+
+	/**
+	 * @param {import('./proxy-tree.svelte.js').ProxyTree} proxyTree
+	 * @param {{ onselect?: Function, onchange?: Function, onlazyload?: Function }} [options]
+	 */
+	constructor(proxyTree, options = {}) {
+		super(proxyTree, options)
+		this.#onlazyload = options.onlazyload
+	}
+
+	// ─── Root-level pagination ──────────────────────────────────────────────────
+
+	/**
+	 * Load more root-level items via the onlazyload callback.
+	 * Appends results to the proxy tree.
+	 */
+	async loadMore() {
+		if (!this.#onlazyload) return
+		const result = await this.#onlazyload()
+		if (Array.isArray(result) && result.length > 0) {
+			this.proxyTree.append(result)
+		}
+	}
+
+	// ─── Overrides: lazy sentinel detection ─────────────────────────────────────
+
+	/**
+	 * Expand focused group. If the node is an unloaded lazy sentinel
+	 * (proxy.loaded === false), fetch children first then expand.
+	 * Otherwise delegates to Wrapper's expand().
+	 */
+	expand(_path) {
+		const key = this.focusedKey
+		if (!key) return
+		const node = this.flatView.find((n) => n.key === key)
+		if (!node) return
+
+		// Lazy unloaded node: fetch children, then expand
+		if (!node.hasChildren && node.proxy.loaded === false) {
+			node.proxy.fetch().then(() => {
+				node.proxy.expanded = true
+			})
+			return
+		}
+
+		super.expand(_path)
+	}
+
+	/**
+	 * Select item at path (or focusedKey). If the target is a group/expandable
+	 * node with proxy.loaded === false, fetch children first then expand.
+	 * Otherwise delegates to Wrapper's select().
+	 */
+	select(path) {
+		const key = path ?? this.focusedKey
+		if (!key) return
+		const proxy = this.lookup.get(key)
+		if (!proxy) return
+
+		// Group with children: delegate to super (toggle expansion)
+		if (proxy.hasChildren) {
+			super.select(path)
+			return
+		}
+
+		// Lazy sentinel: fetch children, then expand
+		if (proxy.loaded === false) {
+			proxy.fetch().then(() => { proxy.expanded = true })
+			return
+		}
+
+		super.select(path)
+	}
+
+	/**
+	 * Toggle expansion of group at path. If the node is an unloaded lazy
+	 * sentinel, fetch children first then expand.
+	 * Otherwise delegates to Wrapper's toggle().
+	 */
+	toggle(path) {
+		const key = path ?? this.focusedKey
+		if (!key) return
+		const proxy = this.lookup.get(key)
+		if (!proxy) return
+
+		// Group with children: normal toggle
+		if (proxy.hasChildren) {
+			super.toggle(path)
+			return
+		}
+
+		// Lazy sentinel: fetch children, then expand
+		if (proxy.loaded === false) {
+			proxy.fetch().then(() => { proxy.expanded = true })
+			return
+		}
+	}
+}

package/src/list-controller.svelte.js

@@ -1,31 +1,53 @@
-import { FieldMapper, defaultFields } from '@rokkit/core'
+import { FieldMapper, DEFAULT_FIELDS, getKeyFromPath, getNestedFields } from '@rokkit/core'
 import { equals } from 'ramda'
 import { SvelteSet } from 'svelte/reactivity'
 import { deriveLookupWithProxy, flatVisibleNodes } from './derive.svelte'
 
 export class ListController {
 	items = $state(null)
-	fields = defaultFields
+	fields = DEFAULT_FIELDS
 	mappers = []
 	#options = $state({})
 	// lookup = new Map()
 	selectedKeys = new SvelteSet()
+	expandedKeys = new SvelteSet()
 	focusedKey = $state(null)
 	#currentIndex = -1
+	#anchorKey = null
 
 	selected = $derived(Array.from(this.selectedKeys).map((key) => this.lookup.get(key).value))
 	focused = $derived(this.lookup.get(this.focusedKey)?.value)
-	data = $derived(flatVisibleNodes(this.items, this.fields))
+	data = $derived(flatVisibleNodes(this.items, this.fields, [], this.expandedKeys))
 	lookup = $derived(deriveLookupWithProxy(this.items, this.fields))
 
 	constructor(items, value, fields, options) {
 		this.items = items
-		this.fields = { ...defaultFields, ...fields }
+		this.fields = { ...DEFAULT_FIELDS, ...fields }
 		this.mappers.push(new FieldMapper(fields))
 		this.#options = { multiselect: false, ...options }
+		this.#initExpandedKeys(items, this.fields)
 		this.init(value)
 	}
 
+	/**
+	 * Scan items for pre-existing expanded flags and populate expandedKeys
+	 * @private
+	 */
+	#initExpandedKeys(items, fields, path = []) {
+		if (!items || !Array.isArray(items)) return
+		items.forEach((item, index) => {
+			if (item === null || item === undefined || typeof item !== 'object') return
+			const itemPath = [...path, index]
+			const children = item[fields.children]
+			if (Array.isArray(children) && children.length > 0) {
+				if (item[fields.expanded]) {
+					this.expandedKeys.add(getKeyFromPath(itemPath))
+				}
+				this.#initExpandedKeys(children, getNestedFields(fields), itemPath)
+			}
+		})
+	}
+
 	/**
 	 * @private
 	 * @param {Array<*>} items
@@ -54,7 +76,17 @@ export class ListController {
 	 * @returns
 	 */
 	findByValue(value) {
-		const index = this.data.findIndex((row) => equals(row.value, value))
+		// Try exact match first (full object comparison)
+		let index = this.data.findIndex((row) => equals(row.value, value))
+
+		// Fallback: match by extracted value field (e.g. primitive 'a' against { text: 'A', value: 'a' })
+		if (index < 0) {
+			const valueField = this.fields.value
+			index = this.data.findIndex(
+				(row) => typeof row.value === 'object' && row.value !== null && equals(row.value[valueField], value)
+			)
+		}
+
 		return index < 0 ? { index } : { index, ...this.data[index] }
 	}
 
@@ -79,12 +111,13 @@ export class ListController {
 
 	/**
 	 *
-	 * @param {string} path
+	 * @param {string|number} path - path key string (e.g. "0", "1-0", "2-1-3")
 	 * @returns
 	 */
 	moveTo(path) {
-		const index = Number(path)
-		return this.moveToIndex(index)
+		const key = String(path)
+		const index = this.data.findIndex((row) => row.key === key)
+		return index >= 0 ? this.moveToIndex(index) : false
 	}
 
 	/**
@@ -100,28 +133,44 @@ export class ListController {
 		return false
 	}
 
+	/**
+	 * @private
+	 * @param {number} index
+	 * @returns {boolean}
+	 */
+	#isDisabled(index) {
+		const item = this.data[index]?.value
+		if (item === null || item === undefined || typeof item !== 'object') return false
+		return item[this.fields.disabled] === true
+	}
+
 	movePrev() {
-		if (this.#currentIndex > 0) {
-			return this.moveToIndex(this.#currentIndex - 1)
-		} else if (this.#currentIndex < 0) {
-			return this.moveLast()
+		if (this.#currentIndex < 0) return this.moveLast()
+		for (let i = this.#currentIndex - 1; i >= 0; i--) {
+			if (!this.#isDisabled(i)) return this.moveToIndex(i)
 		}
 		return false
 	}
 
 	moveNext() {
-		if (this.#currentIndex < this.data.length - 1) {
-			return this.moveToIndex(this.#currentIndex + 1)
+		for (let i = this.#currentIndex + 1; i < this.data.length; i++) {
+			if (!this.#isDisabled(i)) return this.moveToIndex(i)
 		}
 		return false
 	}
 
 	moveFirst() {
-		return this.moveToIndex(0)
+		for (let i = 0; i < this.data.length; i++) {
+			if (!this.#isDisabled(i)) return this.moveToIndex(i)
+		}
+		return false
 	}
 
 	moveLast() {
-		return this.moveToIndex(this.data.length - 1)
+		for (let i = this.data.length - 1; i >= 0; i--) {
+			if (!this.#isDisabled(i)) return this.moveToIndex(i)
+		}
+		return false
 	}
 
 	/**
@@ -159,6 +208,7 @@ export class ListController {
 			this.selectedKeys.add(key)
 		}
 
+		this.#anchorKey = key
 		return true
 	}
 
@@ -173,12 +223,74 @@ export class ListController {
 		if (!this.lookup.has(key)) return false
 
 		if (this.#options.multiselect) {
+			this.#anchorKey = key
 			return this.toggleSelection(key)
 		} else {
 			return this.select(key)
 		}
 	}
 
+	/**
+	 * Select all non-disabled items between the anchor and the given key (inclusive).
+	 * Used for Shift+click range selection in multiselect mode.
+	 * @param {string} selectedKey
+	 * @returns {boolean}
+	 */
+	selectRange(selectedKey) {
+		const key = selectedKey ?? this.focusedKey
+		if (!this.lookup.has(key)) return false
+
+		if (!this.#options.multiselect) return this.select(key)
+
+		const anchorKey = this.#anchorKey ?? this.focusedKey
+		if (!anchorKey) return this.select(key)
+
+		const anchorIndex = this.data.findIndex((row) => row.key === anchorKey)
+		const targetIndex = this.data.findIndex((row) => row.key === key)
+		if (anchorIndex < 0 || targetIndex < 0) return false
+
+		const start = Math.min(anchorIndex, targetIndex)
+		const end = Math.max(anchorIndex, targetIndex)
+
+		this.selectedKeys.clear()
+		for (let i = start; i <= end; i++) {
+			if (!this.#isDisabled(i)) {
+				this.selectedKeys.add(this.data[i].key)
+			}
+		}
+
+		// Move focus but don't change anchor (anchor stays for subsequent Shift+clicks)
+		this.moveToIndex(targetIndex)
+		return true
+	}
+
+	/**
+	 * Find the first visible, non-disabled item whose text starts with `query`.
+	 * Search wraps around and starts after `startAfterKey` for cycling.
+	 *
+	 * @param {string} query - Prefix to match (case-insensitive)
+	 * @param {string|null} [startAfterKey] - Key to start searching after (for cycling)
+	 * @returns {string|null} The matching item's key, or null
+	 */
+	findByText(query, startAfterKey = null) {
+		const q = query.toLowerCase()
+		let startIndex = 0
+		if (startAfterKey !== null) {
+			const idx = this.data.findIndex((row) => row.key === startAfterKey)
+			if (idx >= 0) startIndex = idx + 1
+		}
+		for (let i = 0; i < this.data.length; i++) {
+			const idx = (startIndex + i) % this.data.length
+			if (this.#isDisabled(idx)) continue
+			const entry = this.lookup.get(this.data[idx].key)
+			const text = entry?.label ?? ''
+			if (String(text).toLowerCase().startsWith(q)) {
+				return this.data[idx].key
+			}
+		}
+		return null
+	}
+
 	update(items) {
 		this.items = items
 	}

package/src/media.svelte.js

@@ -0,0 +1,24 @@
+import { MediaQuery } from 'svelte/reactivity'
+
+/** @type {Record<string, string>} */
+export const defaultBreakpoints = {
+	small: '(max-width: 767px)',
+	medium: '(min-width: 768px) and (max-width: 1023px)',
+	large: '(min-width: 1024px)',
+	extraLarge: '(min-width: 1280px)',
+	short: '(max-height: 399px)',
+	landscape: '(orientation: landscape)',
+	tiny: '(orientation: portrait) and (max-height: 599px)',
+	dark: '(prefers-color-scheme: dark)',
+	noanimations: '(prefers-reduced-motion: reduce)'
+}
+
+/** @param {Record<string, string>} breakpoints */
+export function watchMedia(breakpoints = defaultBreakpoints) {
+	/** @type {Record<string, MediaQuery>} */
+	const current = {}
+	for (const [key, query] of Object.entries(breakpoints)) {
+		current[key] = new MediaQuery(query)
+	}
+	return current
+}

package/src/messages.svelte.js

@@ -0,0 +1,71 @@
+/**
+ * Default messages for UI components
+ * @type {import('./types').Messages}
+ */
+const defaultMessages = {
+	emptyList: 'No items found',
+	emptyTree: 'No data available',
+	loading: 'Loading...',
+	noResults: 'No results found',
+	select: 'Select an option',
+	search: 'Search...',
+	list: { label: 'List' },
+	tree: { label: 'Tree', expand: 'Expand', collapse: 'Collapse', loading: 'Loading', loadMore: 'Load More' },
+	toolbar: { label: 'Toolbar' },
+	menu: { label: 'Menu' },
+	toggle: { label: 'Selection' },
+	rating: { label: 'Rating' },
+	stepper: { label: 'Progress' },
+	breadcrumbs: { label: 'Breadcrumb' },
+	carousel: { label: 'Carousel', prev: 'Previous slide', next: 'Next slide', slides: 'Slide navigation' },
+	tabs: { add: 'Add tab', remove: 'Remove tab' },
+	code: { copy: 'Copy code', copied: 'Copied!' },
+	range: { lower: 'Lower bound', upper: 'Upper bound', value: 'Value' },
+	search_: { clear: 'Clear search' },
+	filter: { remove: 'Remove filter' },
+	grid: { label: 'Grid' },
+	uploadProgress: { label: 'Upload progress', clear: 'Clear all', cancel: 'Cancel', retry: 'Retry', remove: 'Remove' },
+	floatingNav: { label: 'Page navigation', pin: 'Pin navigation', unpin: 'Unpin navigation' },
+	mode: { system: 'System', light: 'Light', dark: 'Dark' }
+}
+
+/**
+ * Messages store for localized UI strings
+ */
+class MessagesStore {
+	/** @type {import('./types').Messages} */
+	#messages = $state({ ...defaultMessages })
+
+	/**
+	 * Get the current messages
+	 * @returns {import('./types').Messages}
+	 */
+	get current() {
+		return this.#messages
+	}
+
+	/**
+	 * Set custom messages (merges with defaults)
+	 * @param {Partial<import('./types').Messages>} custom
+	 */
+	set(custom) {
+		const merged = { ...defaultMessages }
+		for (const key of Object.keys(custom)) {
+			if (typeof custom[key] === 'object' && custom[key] !== null && typeof merged[key] === 'object' && merged[key] !== null) {
+				merged[key] = { ...merged[key], ...custom[key] }
+			} else {
+				merged[key] = custom[key]
+			}
+		}
+		this.#messages = merged
+	}
+
+	/**
+	 * Reset to default messages
+	 */
+	reset() {
+		this.#messages = { ...defaultMessages }
+	}
+}
+
+export const messages = new MessagesStore()