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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/states",
-  "version": "1.0.0-next.127",
+  "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,8 +30,8 @@
     }
   },
   "dependencies": {
-    "@rokkit/core": "1.0.0-next.127",
-    "@rokkit/data": "1.0.0-next.127",
+    "@rokkit/core": "1.0.0-next.128",
+    "@rokkit/data": "1.0.0-next.128",
     "d3-array": "^3.2.4",
     "ramda": "^0.32.0",
     "svelte": "^5.53.5"

package/src/derive.svelte.js

@@ -1,17 +1,18 @@
-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
  * @param {Set<string>|null} expandedKeys - When provided, expansion is determined by key membership; falls back to item field
- * @returns {Array<{ key: string, value: any }>}
+ * @returns {Array<{ key: string, value: any, level: number, hasChildren: boolean }>}
  */
-export function flatVisibleNodes(items, fields = defaultFields, path = [], expandedKeys = null) {
+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)
@@ -19,7 +20,7 @@ export function flatVisibleNodes(items, fields = defaultFields, path = [], expan
 			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)
@@ -30,26 +31,34 @@ export function flatVisibleNodes(items, fields = defaultFields, path = [], expan
 }
 
 /**
- * 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,6 +1,9 @@
 export { TableController } from './table-controller.svelte.js'
-export { Proxy } from './proxy.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,11 +1,11 @@
-import { FieldMapper, defaultFields, getKeyFromPath, getNestedFields } 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()
@@ -22,7 +22,7 @@ export class ListController {
 
 	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)
@@ -282,8 +282,8 @@ export class ListController {
 		for (let i = 0; i < this.data.length; i++) {
 			const idx = (startIndex + i) % this.data.length
 			if (this.#isDisabled(idx)) continue
-			const proxy = this.lookup.get(this.data[idx].key)
-			const text = proxy?.get('text') ?? ''
+			const entry = this.lookup.get(this.data[idx].key)
+			const text = entry?.label ?? ''
 			if (String(text).toLowerCase().startsWith(q)) {
 				return this.data[idx].key
 			}

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

@@ -8,7 +8,25 @@ const defaultMessages = {
 	loading: 'Loading...',
 	noResults: 'No results found',
 	select: 'Select an option',
-	search: 'Search...'
+	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' }
 }
 
 /**
@@ -31,7 +49,15 @@ class MessagesStore {
 	 * @param {Partial<import('./types').Messages>} custom
 	 */
 	set(custom) {
-		this.#messages = { ...defaultMessages, ...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
 	}
 
 	/**

package/src/proxy-item.svelte.js

@@ -0,0 +1,320 @@
+/**
+ * ProxyItem
+ *
+ * Wraps a raw item (object or primitive) and provides uniform field access.
+ *
+ * #raw   — always the original input, never mutated.
+ * #item  — the object used for all field accesses:
+ *            for objects: same reference as #raw
+ *            for primitives: { [fields.text]: raw, [fields.value]: raw }
+ *          This normalisation means get() and all getters work through the
+ *          same field-mapping path with no special-casing.
+ * #key   — path-based identifier ('0', '0-1', '0-1-2', …) assigned by
+ *          ProxyTree and propagated into children automatically.
+ * #level — nesting depth: always equals key.split('-').length.
+ *          (1 = root, 2 = first-level children, 3 = grandchildren, …)
+ *
+ * get(fieldName)  — maps semantic name → raw key → #item value.
+ *                   For field-mapped attributes only (text, value, icon, …).
+ *                   Structural props (key, level) and control state
+ *                   (expanded, selected) are accessed directly as properties.
+ *
+ * Direct getters: label, value, id — primary access.
+ *   All other fields via get(fieldName).
+ *
+ * children — auto-wrapped as ProxyItem instances via $derived, with their
+ *            keys and levels already set. Stable references so
+ *            $derived correctly tracks nested expanded state.
+ *
+ * Control state (expanded / selected) — two modes:
+ *   external: item has the field → proxy reads/writes through to #item
+ *   internal: item lacks the field → proxy owns it as $state
+ *   Primitive items always use internal mode (their #item has no state fields).
+ *
+ * ProxyItems are created once and never recreated — this keeps $state
+ * signals stable so $derived computations track them correctly.
+ */
+
+import { BASE_FIELDS, normalizeFields } from '@rokkit/core'
+export { BASE_FIELDS }
+
+// Auto-increment counter for generating stable unique IDs.
+let _nextId = 1
+
+// ─── ProxyItem ────────────────────────────────────────────────────────────────
+
+export class ProxyItem {
+	#raw // original input — never touched after construction
+	#item // normalised object used for all field accesses
+	#fields
+	#id // stable unique identifier — from item field or auto-generated
+	#key // path-based key e.g. '0', '0-1', '0-1-2'
+	#level // nesting depth: 1 = root
+
+	// Control state — always read from here so $derived tracks changes.
+	// Initialised from #item field when present (external mode).
+	#expanded = $state(false)
+	#selected = $state(false)
+
+	// Version counter — incremented by set() to trigger #children recomputation.
+	// $derived reads this so it re-derives when set('children', ...) is called.
+	#version = $state(0)
+
+	// Children auto-wrapped as ProxyItem instances with keys + levels assigned.
+	// $derived ensures stable references: same ProxyItem instances returned on
+	// every access, so $derived can track their expanded state.
+	#children = $derived(this.#buildChildren())
+
+	/**
+	 * @param {*} raw   Raw item — object or primitive (string, number, …)
+	 * @param {Partial<typeof BASE_FIELDS>} [fields]
+	 * @param {string} [key]    Path-based key assigned by ProxyTree
+	 * @param {number} [level]  Nesting depth (1 = root)
+	 */
+	constructor(raw, fields = {}, key = '', level = 0) {
+		this.#fields = { ...BASE_FIELDS, ...normalizeFields(fields) }
+		this.#raw = raw
+		this.#key = key
+		this.#level = level
+
+		// Normalise primitives: #item is always an object.
+		// Both text and value fields point to the primitive so all accessors work uniformly.
+		this.#item =
+			raw !== null && typeof raw === 'object'
+				? raw
+				: { [this.#fields.label]: raw, [this.#fields.value]: raw }
+
+		// Stable unique id: read from item field, or auto-generate
+		this.#id = this.#item[this.#fields.id] ?? `proxy-${_nextId++}`
+
+		// Sync initial control state from #item fields when present
+		const ef = this.#fields.expanded
+		const sf = this.#fields.selected
+		if (ef in this.#item) this.#expanded = Boolean(this.#item[ef])
+		if (sf in this.#item) this.#selected = Boolean(this.#item[sf])
+	}
+
+	// ─── Internal: build wrapped children ────────────────────────────────────
+
+	#buildChildren() {
+		void this.#version // reactive dependency — triggers recompute after set()
+		const raw = this.#item[this.#fields.children]
+		if (!Array.isArray(raw) || raw.length === 0) return []
+		return raw.map(
+			(child, i) =>
+				this._createChild(
+					child,
+					this.#fields,
+					this.#key ? `${this.#key}-${i}` : String(i),
+					this.#level + 1
+				)
+		)
+	}
+
+	/**
+	 * Factory method for creating child proxies. Override in subclasses
+	 * to produce specialised children (e.g. LazyProxyItem).
+	 * @param {*} raw
+	 * @param {Partial<typeof BASE_FIELDS>} fields
+	 * @param {string} key
+	 * @param {number} level
+	 * @returns {ProxyItem}
+	 */
+	_createChild(raw, fields, key, level) {
+		return new ProxyItem(raw, fields, key, level)
+	}
+
+	// ─── Structural props ─────────────────────────────────────────────────────
+
+	get key() {
+		return this.#key
+	}
+	get level() {
+		return this.#level
+	}
+	/** Stable unique identifier — from item's id field, or auto-generated. */
+	get id() {
+		return this.#id
+	}
+	/** The original input passed to the constructor — never mutated. */
+	get original() {
+		return this.#raw
+	}
+	/** The merged field-mapping configuration. */
+	get fields() {
+		return this.#fields
+	}
+
+	// ─── Generic field accessor ───────────────────────────────────────────────
+	//
+	// Maps a semantic field name to the #item value via the fields config.
+	// For field-mapped attributes only: text, value, icon, href, description, …
+	// Falls back to using fieldName directly as a raw key when not in config.
+
+	/**
+	 * @param {string} fieldName  Semantic name, e.g. 'icon', 'href', 'description'
+	 * @returns {*}
+	 */
+	get(fieldName) {
+		const rawKey = this.#fields[fieldName] ?? fieldName
+		return this.#item[rawKey]
+	}
+
+	/**
+	 * Write a value back to the underlying item through the field mapping.
+	 * For object items, this modifies the original raw item (since #item === #raw).
+	 * Increments the version counter so $derived(#buildChildren()) re-computes.
+	 *
+	 * @param {string} fieldName  Semantic name, e.g. 'children', 'text'
+	 * @param {*} value
+	 */
+	set(fieldName, value) {
+		const rawKey = this.#fields[fieldName] ?? fieldName
+		this.#item[rawKey] = value
+		this.#version++
+	}
+
+	/**
+	 * Write directly to the original raw item, bypassing field mapping.
+	 * Advanced operation for when the caller needs to update the source data.
+	 * Accepts either (field, value) or an object for batch updates.
+	 * Increments version so $derived(#buildChildren()) re-computes.
+	 *
+	 * @param {string|object} fieldOrBatch  Raw key name, or { key: value, … }
+	 * @param {*} [value]
+	 */
+	mutate(fieldOrBatch, value) {
+		if (typeof fieldOrBatch === 'object' && fieldOrBatch !== null) {
+			for (const [k, v] of Object.entries(fieldOrBatch)) {
+				this.#raw[k] = v
+			}
+		} else {
+			this.#raw[fieldOrBatch] = value
+		}
+		this.#version++
+	}
+
+	// ─── Field-mapped accessors ───────────────────────────────────────────────
+
+	get label() {
+		return this.#item[this.#fields.label] ?? ''
+	}
+	get value() {
+		return this.#item[this.#fields.value] ?? this.#raw
+	}
+	// All other fields via get('icon'), get('href'), get('snippet'), etc.
+
+	// ─── Computed props ───────────────────────────────────────────────────────
+
+	get disabled() {
+		return this.#item[this.#fields.disabled] === true
+	}
+
+	/** True only for object items with a non-empty children array. */
+	get hasChildren() {
+		return (
+			this.#raw !== null &&
+			typeof this.#raw === 'object' &&
+			Array.isArray(this.#item[this.#fields.children]) &&
+			this.#item[this.#fields.children].length > 0
+		)
+	}
+
+	/** Returns wrapped ProxyItem children (empty array for primitives and leaf items). */
+	get children() {
+		return this.#children
+	}
+
+	get type() {
+		const t = this.#item[this.#fields.type]
+		if (t === 'separator' || t === 'spacer') return t
+		return this.hasChildren ? 'group' : 'item'
+	}
+
+	// ─── Control state (expanded / selected) ─────────────────────────────────
+
+	get expanded() {
+		return this.#expanded
+	}
+	set expanded(v) {
+		this.#expanded = v
+		const ef = this.#fields.expanded
+		if (ef in this.#item) this.#item[ef] = v
+	}
+
+	get selected() {
+		return this.#selected
+	}
+	set selected(v) {
+		this.#selected = v
+		const sf = this.#fields.selected
+		if (sf in this.#item) this.#item[sf] = v
+	}
+}
+
+// ─── LazyProxyItem ───────────────────────────────────────────────────────────
+
+/**
+ * LazyProxyItem
+ *
+ * Extends ProxyItem with lazy-loading support. When a lazyLoad function
+ * is provided, children are fetched on demand via fetch().
+ *
+ * #lazyLoad  — async function (value, raw) => children[] — null when not lazy
+ * #loaded    — true when: lazyLoad is null, or node already has children array,
+ *              or after successful fetch(). false only for sentinel nodes
+ *              (children === true) that need fetching.
+ * #loading   — true during async fetch(), false otherwise. Used for spinner UI.
+ *
+ * After fetch(), uses set('children', result) to update the underlying item
+ * and trigger #children recomputation via the version counter.
+ *
+ * The lazyLoad function is propagated to all children automatically via
+ * _createChild override.
+ */
+export class LazyProxyItem extends ProxyItem {
+	#lazyLoad
+	#loaded = $state(true)
+	#loading = $state(false)
+
+	/**
+	 * @param {*} raw
+	 * @param {Partial<typeof BASE_FIELDS>} [fields]
+	 * @param {string} [key]
+	 * @param {number} [level]
+	 * @param {((value: unknown, raw: unknown) => Promise<unknown[]>) | null} [lazyLoad]
+	 */
+	constructor(raw, fields = {}, key = '', level = 0, lazyLoad = null) {
+		super(raw, fields, key, level)
+		this.#lazyLoad = lazyLoad
+		// Loaded if: no lazyLoad function, children already exist as an array, or no children field (leaf)
+		// Only sentinel nodes (children: true) are considered unloaded
+		this.#loaded = lazyLoad === null || this.get('children') !== true
+	}
+
+	get loaded() { return this.#loaded }
+	get loading() { return this.#loading }
+
+	/**
+	 * Fetch children via the lazyLoad function.
+	 * No-op if lazyLoad is null, already loaded, or currently loading.
+	 * After fetching, writes children to the underlying item via set().
+	 */
+	async fetch() {
+		if (!this.#lazyLoad || this.#loaded || this.#loading) return
+		this.#loading = true
+		try {
+			const children = await this.#lazyLoad(this.value, this.original)
+			this.set('children', children)
+			this.#loaded = true
+		} finally {
+			this.#loading = false
+		}
+	}
+
+	/** @override — propagate lazyLoad to children */
+	_createChild(raw, fields, key, level) {
+		return new LazyProxyItem(raw, fields, key, level, this.#lazyLoad)
+	}
+}
+

package/src/proxy-tree.svelte.js

@@ -0,0 +1,158 @@
+/**
+ * ProxyTree
+ *
+ * Reactive data layer that manages a tree of ProxyItem instances.
+ * Derives flatView (for rendering) and lookup (for O(1) access) reactively
+ * from the root proxies and their children.
+ *
+ * Used by both Wrapper and LazyWrapper as the shared data model.
+ *
+ * Key design:
+ *   #rootProxies is $state([]) — reassigned (not mutated) so $derived re-computes.
+ *   flatView and lookup are $derived from #rootProxies, reading proxy.children
+ *   and proxy.expanded recursively, so they automatically re-derive on any
+ *   expansion or children change anywhere in the tree.
+ */
+
+import { BASE_FIELDS, normalizeFields } from '@rokkit/core'
+import { ProxyItem } from './proxy-item.svelte.js'
+
+// ─── Tree line type computation ────────────────────────────────────────────────
+
+// Maps a parent's line type to the continuation type shown at the same column
+// in child rows below it. 'child'→'sibling' (line continues), 'last'→'empty' (branch ended).
+const NEXT_LINE = { child: 'sibling', last: 'empty', sibling: 'sibling', empty: 'empty', icon: 'empty' }
+
+// ─── Reactive tree traversal utilities ─────────────────────────────────────────
+
+/**
+ * Build flat view by walking proxy.children ($derived) recursively.
+ * Reads proxy.expanded ($state) and proxy.children ($derived), so any
+ * $derived wrapping this function re-computes on expansion or children changes.
+ *
+ * Computes lineTypes per node during the walk — no second pass needed.
+ * lineTypes is an array of connector types for rendering tree lines:
+ *   'child'   — branch connector
+ *   'last'    — last branch connector
+ *   'sibling' — vertical continuation line
+ *   'empty'   — (blank space)
+ *   'icon'    — expand/collapse toggle slot
+ *
+ * @param {ProxyItem[]} proxies
+ * @param {string[]} [parentLineTypes]  Line types of the parent node (for computing inherited connectors)
+ * @returns {{ key: string, proxy: ProxyItem, level: number, hasChildren: boolean, isExpandable: boolean, type: string, lineTypes: string[] }[]}
+ */
+function buildReactiveFlatView(proxies, parentLineTypes = []) {
+	const result = []
+	for (let i = 0; i < proxies.length; i++) {
+		const proxy = proxies[i]
+		const children = proxy.children // reads $derived — registers dependency
+		const hasChildren = children.length > 0
+		const isExpandable = hasChildren || proxy.get('children') === true // sentinel: lazy-loadable
+		const isLast = i === proxies.length - 1
+		const position = isLast ? 'last' : 'child'
+
+		// Compute line types: inherit parent's continuations + current position + icon/empty
+		const inherited = parentLineTypes.slice(0, -1).map((t) => NEXT_LINE[t] ?? 'empty')
+		if (parentLineTypes.length > 0) inherited.push(position)
+		const lineTypes = isExpandable ? [...inherited, 'icon'] : inherited
+
+		result.push({
+			key: proxy.key,
+			proxy,
+			level: proxy.level,
+			hasChildren,
+			isExpandable,
+			type: proxy.type,
+			lineTypes
+		})
+		if (hasChildren && proxy.expanded) {
+			result.push(...buildReactiveFlatView(children, lineTypes))
+		}
+	}
+	return result
+}
+
+/**
+ * Build lookup Map by walking proxy.children ($derived) recursively.
+ * Traverses ALL children (not just expanded) so keys are available
+ * for selection and navigation even before a group is opened.
+ *
+ * @param {ProxyItem[]} proxies
+ * @param {Map<string, ProxyItem>} [map]
+ * @returns {Map<string, ProxyItem>}
+ */
+function buildReactiveLookup(proxies, map = new Map()) {
+	for (const proxy of proxies) {
+		map.set(proxy.key, proxy)
+		const children = proxy.children
+		if (children.length > 0) {
+			buildReactiveLookup(children, map)
+		}
+	}
+	return map
+}
+
+// ─── ProxyTree ─────────────────────────────────────────────────────────────────
+
+export class ProxyTree {
+	#fields
+	#factory
+
+	// Root proxies — $state so reassignment triggers $derived recomputation.
+	#rootProxies = $state([])
+
+	// Reactive flatView: re-derives when proxy.expanded OR proxy.children changes.
+	flatView = $derived(buildReactiveFlatView(this.#rootProxies))
+
+	// Reactive lookup: re-derives when proxy.children changes anywhere in the tree.
+	#lookup = $derived(buildReactiveLookup(this.#rootProxies))
+
+	/**
+	 * @param {unknown[]} [items]
+	 * @param {Partial<typeof BASE_FIELDS>} [fields]
+	 * @param {{ createProxy?: (raw: *, fields: object, key: string, level: number) => ProxyItem }} [options]
+	 */
+	constructor(items = [], fields = {}, options = {}) {
+		this.#fields = { ...BASE_FIELDS, ...normalizeFields(fields) }
+		this.#factory = options.createProxy ?? ((raw, f, key, level) => new ProxyItem(raw, f, key, level))
+		this.#rootProxies = (items ?? []).map((raw, i) => this.#factory(raw, this.#fields, String(i), 1))
+	}
+
+	// ─── Read accessors ──────────────────────────────────────────────────────
+
+	/** @returns {ProxyItem[]} Root proxy array */
+	get roots() { return this.#rootProxies }
+
+	/** @returns {Map<string, ProxyItem>} Lookup map of all proxies by key */
+	get lookup() { return this.#lookup }
+
+	// ─── Mutation methods ────────────────────────────────────────────────────
+
+	/**
+	 * Append new root items. Creates proxies with keys continuing from
+	 * the current length. Reassigns #rootProxies to trigger $derived.
+	 *
+	 * @param {unknown[]} items  Raw items to append as roots
+	 */
+	append(items) {
+		const start = this.#rootProxies.length
+		const newProxies = items.map((raw, i) =>
+			this.#factory(raw, this.#fields, String(start + i), 1)
+		)
+		this.#rootProxies = [...this.#rootProxies, ...newProxies]
+	}
+
+	/**
+	 * Add children to an existing proxy node.
+	 * Uses proxy.set('children', rawItems) so ProxyItem's version counter
+	 * triggers #buildChildren() recomputation. The flatView and lookup
+	 * derive from proxy.children reactively.
+	 *
+	 * @param {ProxyItem} proxy  The proxy to add children to
+	 * @param {unknown[]} items  Raw child items
+	 */
+	addChildren(proxy, items) {
+		proxy.set('children', items)
+	}
+}

package/src/vibe.svelte.js

@@ -2,7 +2,7 @@
 /** @typedef {'cozy' | 'compact' | 'comfortable'} Density */
 /** @typedef {'ltr' | 'rtl'} Direction */
 
-import { defaultColors, defaultThemeMapping, themeRules, detectDirection } from '@rokkit/core'
+import { defaultColors, DEFAULT_THEME_MAPPING, themeRules, detectDirection } from '@rokkit/core'
 import { DEFAULT_STYLES, VALID_DENSITIES, VALID_MODES, VALID_DIRECTIONS } from './constants'
 import { has } from 'ramda'
 
@@ -27,7 +27,7 @@ class Vibe {
 	#colors = $state(defaultColors)
 	#density = $state('comfortable')
 	#direction = $state(detectDirection())
-	#colorMap = $state(defaultThemeMapping)
+	#colorMap = $state(DEFAULT_THEME_MAPPING)
 	#palette = $derived.by(() => themeRules(this.#colorMap, this.#colors))
 
 	/**
@@ -63,7 +63,7 @@ class Vibe {
 			if (missing.length > 0) {
 				throw new Error(`Did you forget to define "${missing.join(', ')}"?`)
 			}
-			this.#colorMap = { ...defaultThemeMapping, ...value }
+			this.#colorMap = { ...DEFAULT_THEME_MAPPING, ...value }
 		}
 	}
 

package/src/wrapper.svelte.js

@@ -0,0 +1,231 @@
+/**
+ * Wrapper
+ *
+ * Navigation controller for persistent list/tree/sidebar components.
+ * Accepts a ProxyTree instance for reactive data (flatView, lookup),
+ * and provides full navigation, expansion, selection, and typeahead logic.
+ *
+ * ProxyTree owns the data layer: items -> proxies -> flatView + lookup.
+ * Wrapper owns the navigation layer: focusedKey, movement, selection callbacks.
+ *
+ * Designed for any persistent (always-visible) component:
+ *   - Sidebar navigation (links, collapsible groups)
+ *   - List / Tree components
+ *   - Any option list rendered inline
+ *
+ * Dropdown variants (Select, Menu) extend this class and override cancel() / blur()
+ * to close the dropdown and return focus to the trigger.
+ */
+
+export class Wrapper {
+	// ─── Data ──────────────────────────────────────────────────────────────────
+
+	#proxyTree
+
+	// flatView: re-derives from proxyTree's flatView, which itself re-derives
+	// when any proxy.expanded or proxy.children changes.
+	flatView = $derived(this.#proxyTree.flatView)
+
+	// Navigable items: exclude separators, spacers, and disabled items.
+	// This is the subset that keyboard navigation moves through.
+	#navigable = $derived(
+		this.flatView.filter(
+			(n) => n.type !== 'separator' && n.type !== 'spacer' && !n.proxy.disabled
+		)
+	)
+
+	// ─── State ──────────────────────────────────────────────────────────────────
+
+	#focusedKey = $state(null)
+
+	// ─── Callbacks ──────────────────────────────────────────────────────────────
+
+	#onselect
+	#onchange
+	#selectedValue = $state(undefined)
+
+	/**
+	 * @param {import('./proxy-tree.svelte.js').ProxyTree} proxyTree
+	 * @param {{ onselect?: Function, onchange?: Function }} [options]
+	 */
+	constructor(proxyTree, options = {}) {
+		this.#proxyTree = proxyTree
+		this.#onselect = options.onselect
+		this.#onchange = options.onchange
+	}
+
+	// ─── IWrapper: state read by Navigator ─────────────────────────────────────
+
+	get focusedKey() { return this.#focusedKey }
+
+	// ─── IWrapper: movement (path passed through but ignored) ──────────────────
+
+	/** Move focus to the next navigable item; clamp at end. */
+	next(_path) {
+		const nav = this.#navigable
+		if (!nav.length) return
+		const idx = nav.findIndex((n) => n.key === this.#focusedKey)
+		if (idx < nav.length - 1) this.#focusedKey = nav[idx + 1].key
+	}
+
+	/** Move focus to the previous navigable item; clamp at start. */
+	prev(_path) {
+		const nav = this.#navigable
+		if (!nav.length) return
+		const idx = nav.findIndex((n) => n.key === this.#focusedKey)
+		if (idx > 0) this.#focusedKey = nav[idx - 1].key
+	}
+
+	/** Move focus to the first navigable item. */
+	first(_path) {
+		const nav = this.#navigable
+		if (nav.length) this.#focusedKey = nav[0].key
+	}
+
+	/** Move focus to the last navigable item. */
+	last(_path) {
+		const nav = this.#navigable
+		if (nav.length) this.#focusedKey = nav[nav.length - 1].key
+	}
+
+	/**
+	 * Expand focused group, or move focus into it if already open.
+	 * No-op on leaf items.
+	 */
+	expand(_path) {
+		if (!this.#focusedKey) return
+		const node = this.flatView.find((n) => n.key === this.#focusedKey)
+		if (!node || !node.hasChildren) return
+		if (!node.proxy.expanded) {
+			node.proxy.expanded = true
+		} else {
+			// Already open — advance focus to first visible child
+			this.next(null)
+		}
+	}
+
+	/**
+	 * Collapse focused group, or move focus to parent if already collapsed / leaf.
+	 * At root level with no parent: no-op.
+	 */
+	collapse(_path) {
+		if (!this.#focusedKey) return
+		const node = this.flatView.find((n) => n.key === this.#focusedKey)
+		if (!node) return
+		if (node.hasChildren && node.proxy.expanded) {
+			node.proxy.expanded = false
+		} else {
+			// Move to parent: strip the last segment from the key
+			const parts = this.#focusedKey.split('-')
+			if (parts.length > 1) {
+				parts.pop()
+				this.#focusedKey = parts.join('-')
+			}
+			// At root level (no '-'): no-op — already at root
+		}
+	}
+
+	// ─── IWrapper: selection actions ───────────────────────────────────────────
+
+	/**
+	 * Select item at path (or focusedKey when path is null).
+	 * Groups toggle expanded. Leaves fire onchange (value differs) and onselect callbacks.
+	 */
+	select(path) {
+		const key = path ?? this.#focusedKey
+		if (!key) return
+		this.#focusedKey = key
+		const proxy = this.#proxyTree.lookup.get(key)
+		if (!proxy) return
+		if (proxy.hasChildren) {
+			proxy.expanded = !proxy.expanded
+		} else {
+			if (proxy.value !== this.#selectedValue) {
+				this.#selectedValue = proxy.value
+				this.#onchange?.(proxy.value, proxy)
+			}
+			this.#onselect?.(proxy.value, proxy)
+		}
+	}
+
+	/**
+	 * Toggle expansion of group at path — called by Navigator for accordion-trigger clicks.
+	 * Unlike select(), this only applies to groups and never fires onselect.
+	 */
+	toggle(path) {
+		const key = path ?? this.#focusedKey
+		if (!key) return
+		const proxy = this.#proxyTree.lookup.get(key)
+		if (proxy?.hasChildren) proxy.expanded = !proxy.expanded
+	}
+
+	/**
+	 * Sync focused state to path — called by Navigator on focusin and typeahead match.
+	 */
+	moveTo(path) {
+		if (path !== null) this.#focusedKey = path
+	}
+
+	/**
+	 * Sync focused key to the item matching this semantic value.
+	 * Used by controlled components (Toggle, Select) to keep navigation
+	 * in sync when the bound value changes externally.
+	 *
+	 * @param {unknown} v
+	 */
+	moveToValue(v) {
+		if (v === undefined || v === null) return
+		for (const [key, proxy] of this.#proxyTree.lookup) {
+			if (proxy.value === v) {
+				this.#focusedKey = key
+				this.#selectedValue = v
+				return
+			}
+		}
+	}
+
+	/** Persistent list: no dropdown to close. Override in dropdown wrappers. */
+	cancel(_path) {}
+
+	/** Persistent list: no-op. Override in dropdown wrappers to close + restore trigger focus. */
+	blur() {}
+
+	/** Multiselect toggle — not yet implemented. */
+	extend(_path) {}
+
+	/** Multiselect range — not yet implemented. */
+	range(_path) {}
+
+	// ─── IWrapper: typeahead ───────────────────────────────────────────────────
+
+	/**
+	 * Return the key of the first navigable item whose text starts with query
+	 * (case-insensitive). Wraps around. startAfterKey enables cycling.
+	 * Returns null if no match.
+	 *
+	 * @param {string} query
+	 * @param {string|null} [startAfterKey]
+	 * @returns {string|null}
+	 */
+	findByText(query, startAfterKey = null) {
+		const nav = this.#navigable
+		if (!nav.length) return null
+		const q = query.toLowerCase()
+		const startIdx = startAfterKey
+			? nav.findIndex((n) => n.key === startAfterKey) + 1
+			: 0
+		for (let i = 0; i < nav.length; i++) {
+			const node = nav[(startIdx + i) % nav.length]
+			if (node.proxy.label.toLowerCase().startsWith(q)) return node.key
+		}
+		return null
+	}
+
+	// ─── Helpers for the component ─────────────────────────────────────────────
+
+	/** @returns {Map<string, import('./proxy-item.svelte.js').ProxyItem>} */
+	get lookup() { return this.#proxyTree.lookup }
+
+	/** @returns {import('./proxy-tree.svelte.js').ProxyTree} */
+	get proxyTree() { return this.#proxyTree }
+}

package/src/nested-controller.svelte.js

@@ -1,94 +0,0 @@
-import { getKeyFromPath, getPathFromKey } from '@rokkit/core'
-import { equals } from 'ramda'
-import { ListController } from './list-controller.svelte'
-
-export class NestedController extends ListController {
-	/**
-	 * @protected
-	 * @param {Object} [value]
-	 */
-	init(value) {
-		if (value) {
-			this.ensureVisible(value)
-			this.moveToValue(value)
-		}
-	}
-
-	/**
-	 * Mark parents as expanded so that item is visible
-	 * @param {*} value
-	 * @returns
-	 */
-	ensureVisible(value) {
-		const result = this.lookup.entries().find((entry) => equals(entry[1].value, value))
-		if (!result) return false
-		const path = getPathFromKey(result[0])
-
-		for (let i = 1; i < path.length; i++) {
-			const nodeKey = getKeyFromPath(path.slice(0, i))
-			this.expandedKeys.add(nodeKey)
-		}
-		return true
-	}
-
-	/**
-	 * Toggle expansion of item
-	 * @param {string} key
-	 * @returns {boolean}
-	 */
-	toggleExpansion(key) {
-		if (!this.lookup.has(key)) return false
-		if (this.expandedKeys.has(key)) {
-			this.expandedKeys.delete(key)
-		} else {
-			this.expandedKeys.add(key)
-		}
-		return true
-	}
-
-	/**
-	 * Expand item. If already expanded, move focus to first child.
-	 * @param {string} [key]
-	 * @returns {boolean}
-	 */
-	expand(key) {
-		const actualKey = key ?? this.focusedKey
-		if (!this.lookup.has(actualKey)) return false
-
-		const firstChildKey = `${actualKey}-0`
-		const hasChildren = this.lookup.has(firstChildKey)
-
-		if (!hasChildren) return false
-
-		if (this.expandedKeys.has(actualKey)) {
-			// Already expanded → move to first child
-			return this.moveTo(firstChildKey)
-		}
-
-		this.expandedKeys.add(actualKey)
-		return true
-	}
-
-	/**
-	 * Collapse item. If not expandable (leaf or already collapsed), move focus to parent.
-	 * @param {string} [key]
-	 * @returns {boolean}
-	 */
-	collapse(key) {
-		const actualKey = key ?? this.focusedKey
-		if (!this.lookup.has(actualKey)) return false
-
-		if (this.expandedKeys.has(actualKey)) {
-			this.expandedKeys.delete(actualKey)
-			return true
-		}
-
-		// Leaf or collapsed group → move to parent
-		const path = getPathFromKey(actualKey)
-		if (path.length > 1) {
-			const parentKey = getKeyFromPath(path.slice(0, -1))
-			return this.lookup.has(parentKey) ? this.moveTo(parentKey) : false
-		}
-		return false
-	}
-}

package/src/proxy.svelte.js

@@ -1,120 +0,0 @@
-import { defaultFields, id, toString, getNestedFields } from '@rokkit/core'
-import { isNil, has } from 'ramda'
-
-export class Proxy {
-	#original = null
-	#value = $state(null)
-	#fields = defaultFields
-	#id = null
-
-	#children = $derived(this.#processChildren())
-
-	constructor(value, fields) {
-		this.fields = fields
-		this.#original = value
-		this.#value = typeof value === 'object' ? value : { [this.fields.text]: value }
-		this.id = typeof value === 'object' ? (this.get('id') ?? id()) : value
-	}
-
-	#processChildren() {
-		if (isNil(this.#value)) return []
-
-		const children = this.#value[this.fields.children] ?? []
-		if (Array.isArray(children)) {
-			const fields = getNestedFields(this.fields)
-			return children.map((child) => new Proxy(child, fields))
-		}
-		return []
-	}
-
-	get id() {
-		return this.#id
-	}
-	set id(new_id) {
-		this.#id = typeof new_id === 'string' ? new_id : toString(new_id)
-	}
-	get children() {
-		return this.#children
-	}
-	get fields() {
-		return this.#fields
-	}
-	set fields(value) {
-		this.#fields = { ...defaultFields, ...value }
-	}
-
-	get value() {
-		return typeof this.#original === 'object' ? this.#value : this.#original
-	}
-
-	set value(value) {
-		if (typeof value === 'object') {
-			const removedKeys = Object.keys(this.#value).filter(
-				(key) => !Object.keys(value).includes(key)
-			)
-			Object.entries(value).forEach(([k, v]) => {
-				this.#value[k] = v
-			})
-			removedKeys.forEach((key) => {
-				delete this.#value[key]
-			})
-		} else {
-			this.#value = { [this.fields.text]: value }
-			this.#original = value
-		}
-	}
-
-	/**
-	 * Gets a mapped attribute from the original item
-	 *
-	 * @param {string} fieldName - Name of the field to get
-	 * @param {any}   [defaultValue] - Default value to return if not found
-	 * @returns {any|undefined} - The attribute value or null if not found
-	 */
-	get(fieldName, defaultValue) {
-		return this.has(fieldName) ? this.#value[this.fields[fieldName]] : defaultValue
-	}
-
-	/**
-	 * Checks if a mapped attribute exists in the original item
-	 * @param {string} fieldName - Name of the field to check
-	 * @returns boolean
-	 */
-	has(fieldName) {
-		const mappedField = this.fields[fieldName]
-		return !isNil(mappedField) && has(mappedField, this.#value)
-	}
-
-	/**
-	 * Gets the appropriate snippet for rendering this item:
-	 * - Uses the 'snippet' field from the current item to find the snippet key
-	 * - Finds a matching snippet in the provided collection using this key
-	 * - Falls back to the defaultSnippet if:
-	 *   - No snippet key is configured for this item
-	 *   - The configured snippet key doesn't exist in the snippets collection
-	 * @param {Object} snippets
-	 * @param {import('svelte').Snippet|undefined} [defaultSnippet]
-	 * @returns {import('svelte').Snippet|undefined}
-	 */
-	getSnippet(snippets, defaultSnippet) {
-		const snippetKey = this.get('snippet')
-		const snippet = has(snippetKey, snippets) ? snippets[snippetKey] : undefined
-		return snippet ?? defaultSnippet
-	}
-
-	/**
-	 * Identifies if the item has children
-	 */
-	get hasChildren() {
-		return (
-			typeof this.#original === 'object' &&
-			has(this.fields.children, this.#value) &&
-			Array.isArray(this.#value[this.fields.children]) &&
-			this.#value[this.fields.children].length > 0
-		)
-	}
-
-	get expanded() {
-		return this.has('expanded') ? this.#value[this.fields.expanded] : false
-	}
-}