@rokkit/states 1.0.0-next.136 → 1.0.0-next.138

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/states",
-  "version": "1.0.0-next.136",
+  "version": "1.0.0-next.138",
   "description": "Contains generic data manipulation functions that can be used in various components.",
   "repository": {
     "type": "git",

package/src/derive.svelte.js

@@ -1,69 +1,103 @@
 import { getKeyFromPath, DEFAULT_FIELDS, getNestedFields } from '@rokkit/core'
+import { SvelteMap } from 'svelte/reactivity'
+
+/**
+ * @param {*} item
+ * @param {import('@rokkit/core').FieldMapping} fields
+ * @param {string} key
+ * @param {Set<string>|null} expandedKeys
+ * @returns {boolean}
+ */
+function isExpanded(item, fields, key, expandedKeys) {
+	const hasChildren = Array.isArray(item[fields.children]) && item[fields.children].length > 0
+	if (!hasChildren) return false
+	return expandedKeys ? expandedKeys.has(key) : item[fields.expanded]
+}
+
+/**
+ * @param {Array<*>} data  Accumulator array
+ * @param {{ item: *, index: number, fields: *, path: Array<number>, level: number, expandedKeys: Set<string>|null }} ctx
+ */
+function visitNode(data, ctx) {
+	const { item, index, fields, path, level, expandedKeys } = ctx
+	const itemPath = [...path, index]
+	const key = getKeyFromPath(itemPath)
+	const hasChildren = Array.isArray(item[fields.children]) && item[fields.children].length > 0
+	data.push({ key, value: item, level, hasChildren })
+	if (isExpanded(item, fields, key, expandedKeys)) {
+		data.push(...flatVisibleNodes(item[fields.children], getNestedFields(fields), itemPath, expandedKeys))
+	}
+}
+
 /**
- *
  * @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, level: number, hasChildren: boolean }>}
+ * @param {Set<string>|null} expandedKeys
+ * @returns {Array}
  */
-export function flatVisibleNodes(items, fields = DEFAULT_FIELDS, path = [], expandedKeys = null) {
+function collectVisibleNodes(items, fields, path, expandedKeys) {
 	const data = []
-	if (!items || !Array.isArray(items)) return data
-
 	const level = path.length
+	for (let i = 0; i < items.length; i++) {
+		visitNode(data, { item: items[i], index: i, fields, path, level, expandedKeys })
+	}
+	return data
+}
 
-	items.forEach((item, index) => {
-		const itemPath = [...path, index]
-		const key = getKeyFromPath(itemPath)
-		const hasChildren = Array.isArray(item[fields.children]) && item[fields.children].length > 0
-		const expanded = hasChildren && (expandedKeys ? expandedKeys.has(key) : item[fields.expanded])
+// eslint-disable-next-line complexity
+export function flatVisibleNodes(items, fields = DEFAULT_FIELDS, path = [], expandedKeys = null) {
+	if (!items || !Array.isArray(items)) return []
+	return collectVisibleNodes(items, fields, path, expandedKeys)
+}
 
-		data.push({ key, value: item, level, hasChildren })
+/**
+ * Merge child lookup entries into parent lookup.
+ * @param {SvelteMap} lookup
+ * @param {SvelteMap} childLookup
+ */
+function mergeChildLookup(lookup, childLookup) {
+	for (const [childKey, childValue] of childLookup.entries()) {
+		lookup.set(childKey, childValue)
+	}
+}
 
-		if (expanded) {
-			const childFields = getNestedFields(fields)
-			data.push(...flatVisibleNodes(item[fields.children], childFields, itemPath, expandedKeys))
-		}
-	})
-	return data
+/**
+ * Create a lookup entry for an item.
+ * @param {*} item
+ * @param {*} norm  Normalised item object
+ * @param {*} fields
+ * @returns {object}
+ */
+function makeLookupEntry(item, norm, fields) {
+	return {
+		value: item,
+		original: item,
+		label: String(norm[fields.label] ?? ''),
+		get: (fieldName) => norm[fields[fieldName] ?? fieldName]
+	}
 }
 
 /**
- * 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, { value: *, original: *, label: string, get: (f: string) => * }>}
+ * @param {SvelteMap} lookup  Accumulator map
+ * @param {{ item: *, index: number, fields: *, path: Array<number> }} ctx
  */
+// eslint-disable-next-line complexity
+function visitLookupNode(lookup, ctx) {
+	const { item, index, fields, path } = ctx
+	const itemPath = [...path, index]
+	const key = getKeyFromPath(itemPath)
+	const norm = typeof item === 'object' && item !== null ? item : { [fields.label]: item }
+	lookup.set(key, makeLookupEntry(item, norm, fields))
+	const children = norm[fields.children] ?? []
+	if (Array.isArray(children) && children.length > 0) {
+		mergeChildLookup(lookup, deriveLookupWithProxy(children, getNestedFields(fields), itemPath))
+	}
+}
+
 export function deriveLookupWithProxy(items, fields = DEFAULT_FIELDS, path = []) {
-	const lookup = new Map()
+	const lookup = new SvelteMap()
 	if (!items || !Array.isArray(items)) return lookup
-
-	items.forEach((item, index) => {
-		const itemPath = [...path, index]
-		const key = getKeyFromPath(itemPath)
-		const norm = typeof item === 'object' && item !== null ? item : { [fields.label]: item }
-		const entry = {
-			value: item,
-			original: item,
-			label: String(norm[fields.label] ?? ''),
-			get: (fieldName) => norm[fields[fieldName] ?? fieldName]
-		}
-
-		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()) {
-				lookup.set(childKey, childValue)
-			}
-		}
-	})
+	items.forEach((item, index) => visitLookupNode(lookup, { item, index, fields, path }))
 	return lookup
 }

package/src/lazy-wrapper.svelte.js

@@ -67,31 +67,37 @@ export class LazyWrapper extends Wrapper {
 		super.expand(_path)
 	}
 
+	/**
+	 * Fetch children for an unloaded lazy sentinel proxy and expand it.
+	 * @param {*} proxy
+	 */
+	#fetchAndExpand(proxy) {
+		proxy.fetch().then(() => {
+			proxy.expanded = true
+		})
+	}
+
+	/**
+	 * Resolve proxy for a path or focused key, or null if not found.
+	 * @param {string|null} path
+	 * @returns {*|null}
+	 */
+	#resolveProxy(path) {
+		const key = path ?? this.focusedKey
+		if (!key) return null
+		return this.lookup.get(key) ?? null
+	}
+
 	/**
 	 * 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)
+		const proxy = this.#resolveProxy(path)
 		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
-		}
-
+		if (proxy.hasChildren) return super.select(path)
+		if (proxy.loaded === false) return this.#fetchAndExpand(proxy)
 		super.select(path)
 	}
 
@@ -101,23 +107,9 @@ export class LazyWrapper extends Wrapper {
 	 * Otherwise delegates to Wrapper's toggle().
 	 */
 	toggle(path) {
-		const key = path ?? this.focusedKey
-		if (!key) return
-		const proxy = this.lookup.get(key)
+		const proxy = this.#resolveProxy(path)
 		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
-		}
+		if (proxy.hasChildren) return super.toggle(path)
+		if (proxy.loaded === false) this.#fetchAndExpand(proxy)
 	}
 }

package/src/list-controller.svelte.js

@@ -29,23 +29,36 @@ export class ListController {
 		this.init(value)
 	}
 
+	/**
+	 * Process a group item's children for expanded key initialization.
+	 * @private
+	 */
+	#initExpandedGroup(item, itemPath, children, fields) {
+		if (item[fields.expanded]) {
+			this.expandedKeys.add(getKeyFromPath(itemPath))
+		}
+		this.#initExpandedKeys(children, getNestedFields(fields), itemPath)
+	}
+
+	/**
+	 * Process a single item for expanded key initialization.
+	 * @private
+	 */
+	// eslint-disable-next-line complexity
+	#initExpandedItem(item, index, fields, path) {
+		if (item === null || item === undefined || typeof item !== 'object') return
+		const children = item[fields.children]
+		if (!Array.isArray(children) || children.length === 0) return
+		this.#initExpandedGroup(item, [...path, index], children, fields)
+	}
+
 	/**
 	 * 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)
-			}
-		})
+		items.forEach((item, index) => this.#initExpandedItem(item, index, fields, path))
 	}
 
 	/**
@@ -233,6 +246,45 @@ export class ListController {
 		}
 	}
 
+	/**
+	 * Select non-disabled items in index range [start, end] inclusive.
+	 * @private
+	 */
+	#selectIndexRange(start, end, targetIndex) {
+		this.selectedKeys.clear()
+		for (let i = start; i <= end; i++) {
+			if (!this.#isDisabled(i)) {
+				this.selectedKeys.add(this.data[i].key)
+			}
+		}
+		this.moveToIndex(targetIndex)
+	}
+
+	/**
+	 * Find indices for anchor and target keys. Returns null if either is missing.
+	 * @private
+	 */
+	#findRangeIndices(anchorKey, targetKey) {
+		const anchorIndex = this.data.findIndex((row) => row.key === anchorKey)
+		const targetIndex = this.data.findIndex((row) => row.key === targetKey)
+		if (anchorIndex < 0 || targetIndex < 0) return null
+		return { anchorIndex, targetIndex }
+	}
+
+	/**
+	 * Apply range selection using pre-computed anchor and target indices.
+	 * @private
+	 */
+	#applyRangeSelection(key) {
+		const anchorKey = this.#anchorKey ?? this.focusedKey
+		if (!anchorKey) return this.select(key)
+		const indices = this.#findRangeIndices(anchorKey, key)
+		if (!indices) return false
+		const { anchorIndex, targetIndex } = indices
+		this.#selectIndexRange(Math.min(anchorIndex, targetIndex), Math.max(anchorIndex, targetIndex), targetIndex)
+		return true
+	}
+
 	/**
 	 * Select all non-disabled items between the anchor and the given key (inclusive).
 	 * Used for Shift+click range selection in multiselect mode.
@@ -242,29 +294,29 @@ export class ListController {
 	selectRange(selectedKey) {
 		const key = selectedKey ?? this.focusedKey
 		if (!this.lookup.has(key)) return false
-
 		if (!this.#options.multiselect) return this.select(key)
+		return this.#applyRangeSelection(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)
-			}
-		}
+	/**
+	 * Compute the start index for a findByText search.
+	 * @private
+	 */
+	#findStartIndex(startAfterKey) {
+		if (startAfterKey === null) return 0
+		const idx = this.data.findIndex((row) => row.key === startAfterKey)
+		return idx >= 0 ? idx + 1 : 0
+	}
 
-		// Move focus but don't change anchor (anchor stays for subsequent Shift+clicks)
-		this.moveToIndex(targetIndex)
-		return true
+	/**
+	 * Check if an item at idx matches the query prefix.
+	 * @private
+	 */
+	#matchesText(idx, q) {
+		if (this.#isDisabled(idx)) return false
+		const entry = this.lookup.get(this.data[idx].key)
+		const text = entry?.label ?? ''
+		return String(text).toLowerCase().startsWith(q)
 	}
 
 	/**
@@ -277,19 +329,10 @@ export class ListController {
 	 */
 	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
-		}
+		const startIndex = this.#findStartIndex(startAfterKey)
 		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
-			}
+			if (this.#matchesText(idx, q)) return this.data[idx].key
 		}
 		return null
 	}

package/src/messages.svelte.js

@@ -61,6 +61,21 @@ class MessagesStore {
 		return this.#messages
 	}
 
+	/**
+	 * Merge a single key from custom into merged target.
+	 * @param {Record<string, unknown>} merged
+	 * @param {Record<string, unknown>} custom
+	 * @param {string} key
+	 */
+	#mergeKey(merged, custom, key) {
+		const isObject = (v) => typeof v === 'object' && v !== null
+		if (isObject(custom[key]) && isObject(merged[key])) {
+			merged[key] = { ...merged[key], ...custom[key] }
+		} else {
+			merged[key] = custom[key]
+		}
+	}
+
 	/**
 	 * Set custom messages (merges with defaults)
 	 * @param {Partial<import('./types').Messages>} custom
@@ -68,16 +83,7 @@ class MessagesStore {
 	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.#mergeKey(merged, custom, key)
 		}
 		this.#messages = merged
 	}

package/src/proxy-item.svelte.js

@@ -65,6 +65,27 @@ export class ProxyItem {
 	// every access, so $derived can track their expanded state.
 	#children = $derived(this.#buildChildren())
 
+	/**
+	 * Normalise a raw value to an object for uniform field access.
+	 * @param {*} raw
+	 * @returns {object}
+	 */
+	#normalizeItem(raw) {
+		return raw !== null && typeof raw === 'object'
+			? raw
+			: { [this.#fields.label]: raw, [this.#fields.value]: raw }
+	}
+
+	/**
+	 * Sync initial control state from item fields when present.
+	 */
+	#syncControlState() {
+		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])
+	}
+
 	/**
 	 * @param {*} raw   Raw item — object or primitive (string, number, …)
 	 * @param {Partial<typeof BASE_FIELDS>} [fields]
@@ -76,22 +97,9 @@ export class ProxyItem {
 		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.#item = this.#normalizeItem(raw)
 		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])
+		this.#syncControlState()
 	}
 
 	// ─── Internal: build wrapped children ────────────────────────────────────
@@ -283,12 +291,21 @@ export class LazyProxyItem extends ProxyItem {
 	 * @param {number} [level]
 	 * @param {((value: unknown, raw: unknown) => Promise<unknown[]>) | null} [lazyLoad]
 	 */
+	// eslint-disable-next-line max-params
 	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
+		this.#loaded = this.#resolveLoaded(lazyLoad)
+	}
+
+	/**
+	 * Determine initial loaded state.
+	 * Loaded if no lazyLoad function, or children is not a sentinel (true).
+	 * @param {Function|null} lazyLoad
+	 * @returns {boolean}
+	 */
+	#resolveLoaded(lazyLoad) {
+		return lazyLoad === null || this.get('children') !== true
 	}
 
 	get loaded() {

package/src/proxy-tree.svelte.js

@@ -15,6 +15,7 @@
  */
 
 import { BASE_FIELDS, normalizeFields } from '@rokkit/core'
+import { SvelteMap } from 'svelte/reactivity'
 import { ProxyItem } from './proxy-item.svelte.js'
 
 // ─── Tree line type computation ────────────────────────────────────────────────
@@ -31,6 +32,19 @@ const NEXT_LINE = {
 
 // ─── Reactive tree traversal utilities ─────────────────────────────────────────
 
+/**
+ * Compute the lineTypes array for a single node.
+ * @param {string[]} parentLineTypes
+ * @param {string} position - 'child' or 'last'
+ * @param {boolean} isExpandable
+ * @returns {string[]}
+ */
+function computeLineTypes(parentLineTypes, position, isExpandable) {
+	const inherited = parentLineTypes.slice(0, -1).map((t) => NEXT_LINE[t] ?? 'empty')
+	if (parentLineTypes.length > 0) inherited.push(position)
+	return isExpandable ? [...inherited, 'icon'] : inherited
+}
+
 /**
  * Build flat view by walking proxy.children ($derived) recursively.
  * Reads proxy.expanded ($state) and proxy.children ($derived), so any
@@ -48,33 +62,28 @@ const NEXT_LINE = {
  * @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[] }[]}
  */
+/**
+ * Visit a single proxy node and push entries to result.
+ * @param {Array} result
+ * @param {ProxyItem} proxy
+ * @param {string[]} parentLineTypes
+ * @param {string} position - 'child' or 'last'
+ */
+function visitProxy(result, proxy, parentLineTypes, position) {
+	const children = proxy.children // reads $derived — registers dependency
+	const hasChildren = children.length > 0
+	const isExpandable = hasChildren || proxy.get('children') === true // sentinel: lazy-loadable
+	const lineTypes = computeLineTypes(parentLineTypes, position, isExpandable)
+	result.push({ key: proxy.key, proxy, level: proxy.level, hasChildren, isExpandable, type: proxy.type, lineTypes })
+	if (hasChildren && proxy.expanded) {
+		result.push(...buildReactiveFlatView(children, lineTypes))
+	}
+}
+
 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))
-		}
+		visitProxy(result, proxies[i], parentLineTypes, i === proxies.length - 1 ? 'last' : 'child')
 	}
 	return result
 }
@@ -88,7 +97,7 @@ function buildReactiveFlatView(proxies, parentLineTypes = []) {
  * @param {Map<string, ProxyItem>} [map]
  * @returns {Map<string, ProxyItem>}
  */
-function buildReactiveLookup(proxies, map = new Map()) {
+function buildReactiveLookup(proxies, map = new SvelteMap()) {
 	for (const proxy of proxies) {
 		map.set(proxy.key, proxy)
 		const children = proxy.children
@@ -121,13 +130,20 @@ export class ProxyTree {
 	 */
 	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.#factory = this.#resolveFactory(options.createProxy)
 		this.#rootProxies = (items ?? []).map((raw, i) =>
 			this.#factory(raw, this.#fields, String(i), 1)
 		)
 	}
 
+	/**
+	 * @param {Function|undefined} createProxy
+	 * @returns {Function}
+	 */
+	#resolveFactory(createProxy) {
+		return createProxy ?? ((raw, f, key, level) => new ProxyItem(raw, f, key, level))
+	}
+
 	// ─── Read accessors ──────────────────────────────────────────────────────
 
 	/** @returns {ProxyItem[]} Root proxy array */

package/src/table-controller.svelte.js

@@ -39,46 +39,67 @@ export class TableController {
 	// =========================================================================
 
 	/**
-	 * Toggle sort on a column. Cycles: none → ascending → descending → none.
-	 * @param {string} columnName - Column to sort by
-	 * @param {boolean} [extend=false] - If true (Shift+click), add to sort stack
+	 * Compute the next sort state for multi-column (extend) mode.
+	 * @param {string} columnName
+	 * @param {string} nextDirection
+	 * @returns {Array}
 	 */
-	sortBy(columnName, extend = false) {
-		const col = this.columns.find((c) => c.name === columnName)
-		if (!col || col.sortable === false) return
-
-		// Determine next direction
-		const cycle = { none: 'ascending', ascending: 'descending', descending: 'none' }
-		const nextDirection = cycle[col.sorted ?? 'none']
-
-		if (extend) {
-			// Multi-column sort: add/update/remove this column in the sort stack
-			const existing = this.sortState.findIndex((s) => s.column === columnName)
-			if (nextDirection === 'none') {
-				// Remove from stack
-				this.sortState = this.sortState.filter((s) => s.column !== columnName)
-			} else if (existing >= 0) {
-				// Update direction in place
-				this.sortState = this.sortState.map((s) =>
-					s.column === columnName ? { ...s, direction: nextDirection } : s
-				)
-			} else {
-				// Add to stack
-				this.sortState = [...this.sortState, { column: columnName, direction: nextDirection }]
-			}
-		} else {
-			// Single column sort: replace entire sort state
-			this.sortState =
-				nextDirection === 'none' ? [] : [{ column: columnName, direction: nextDirection }]
+	#extendSortState(columnName, nextDirection) {
+		const existing = this.sortState.findIndex((s) => s.column === columnName)
+		if (nextDirection === 'none') {
+			return this.sortState.filter((s) => s.column !== columnName)
+		}
+		if (existing >= 0) {
+			return this.sortState.map((s) =>
+				s.column === columnName ? { ...s, direction: nextDirection } : s
+			)
 		}
+		return [...this.sortState, { column: columnName, direction: nextDirection }]
+	}
+
+	/**
+	 * Compute new sort state for a single-column sort.
+	 * @param {string} columnName
+	 * @param {string} nextDirection
+	 * @returns {Array}
+	 */
+	#singleSortState(columnName, nextDirection) {
+		return nextDirection === 'none' ? [] : [{ column: columnName, direction: nextDirection }]
+	}
 
-		// Update column sorted flags
+	/**
+	 * Sync column sorted flags from current sortState.
+	 */
+	#syncColumnFlags() {
 		this.columns = this.columns.map((c) => {
 			const sort = this.sortState.find((s) => s.column === c.name)
 			return { ...c, sorted: sort ? sort.direction : 'none' }
 		})
+	}
+
+	/**
+	 * Determine the next sort direction for a column by cycling.
+	 * @param {object} col  Column object with sorted property
+	 * @returns {string}
+	 */
+	#nextSortDirection(col) {
+		const cycle = { none: 'ascending', ascending: 'descending', descending: 'none' }
+		return cycle[col.sorted ?? 'none']
+	}
 
-		// Apply sort and update list
+	/**
+	 * Toggle sort on a column. Cycles: none → ascending → descending → none.
+	 * @param {string} columnName - Column to sort by
+	 * @param {boolean} [extend=false] - If true (Shift+click), add to sort stack
+	 */
+	sortBy(columnName, extend = false) {
+		const col = this.columns.find((c) => c.name === columnName)
+		if (!col || col.sortable === false) return
+		const nextDirection = this.#nextSortDirection(col)
+		this.sortState = extend
+			? this.#extendSortState(columnName, nextDirection)
+			: this.#singleSortState(columnName, nextDirection)
+		this.#syncColumnFlags()
 		this.#applySortAndUpdate()
 	}
 

package/src/wrapper.svelte.js

@@ -104,6 +104,18 @@ export class Wrapper {
 		}
 	}
 
+	/**
+	 * Move focus to the parent key by stripping the last segment.
+	 * No-op at root level.
+	 */
+	#focusParent() {
+		const parts = this.#focusedKey.split('-')
+		if (parts.length > 1) {
+			parts.pop()
+			this.#focusedKey = parts.join('-')
+		}
+	}
+
 	/**
 	 * Collapse focused group, or move focus to parent if already collapsed / leaf.
 	 * At root level with no parent: no-op.
@@ -115,18 +127,24 @@ export class Wrapper {
 		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
+			this.#focusParent()
 		}
 	}
 
 	// ─── IWrapper: selection actions ───────────────────────────────────────────
 
+	/**
+	 * Fire value-change callbacks for a leaf selection.
+	 * @param {*} proxy
+	 */
+	#selectLeaf(proxy) {
+		if (proxy.value !== this.#selectedValue) {
+			this.#selectedValue = proxy.value
+			this.#onchange?.(proxy.value, proxy)
+		}
+		this.#onselect?.(proxy.value, proxy)
+	}
+
 	/**
 	 * Select item at path (or focusedKey when path is null).
 	 * Groups toggle expanded. Leaves fire onchange (value differs) and onselect callbacks.
@@ -140,11 +158,7 @@ export class Wrapper {
 		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)
+			this.#selectLeaf(proxy)
 		}
 	}
 
@@ -212,6 +226,17 @@ export class Wrapper {
 		if (!nav.length) return null
 		const q = query.toLowerCase()
 		const startIdx = startAfterKey ? nav.findIndex((n) => n.key === startAfterKey) + 1 : 0
+		return this.#searchNav(nav, q, startIdx)
+	}
+
+	/**
+	 * Search navigable items for a text prefix match starting from startIdx.
+	 * @param {Array} nav
+	 * @param {string} q
+	 * @param {number} startIdx
+	 * @returns {string|null}
+	 */
+	#searchNav(nav, q, startIdx) {
 		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