@rokkit/states 1.1.1 → 1.1.5

package/README.md

@@ -1,6 +1,6 @@
 # @rokkit/states
 
-Reactive state management for Rokkit UI components — ProxyItem, ProxyTree, Wrapper, ListController.
+Reactive state management for Rokkit UI components — ProxyItem, ProxyTree, ProxyTable, Wrapper, LazyWrapper.
 
 ## Installation
 
@@ -16,7 +16,7 @@ bun add @rokkit/states
 
 - **ProxyItem / ProxyTree** — normalize arbitrary data objects into a unified, field-mapped interface for rendering
 - **Wrapper** — navigation controller for persistent components (List, Tree, Tabs). Owns focus, movement, selection, and expansion state
-- **ListController** — lower-level reactive base for selection and expansion state
+- **ProxyTable** — tabular data layer that adds columns + sort to a flat ProxyTree
 - **Utilities** — i18n messages, theme mode tracking, media query breakpoints
 
 These classes are used internally by `@rokkit/ui` components. You can also use them directly to build custom components or drive navigation logic outside of the standard components.
@@ -86,17 +86,20 @@ wrapper.collapse(pathKey)
 wrapper.moveToValue(value) // sync focus to match an external value
 ```
 
-### ListController — base reactive state
+### ProxyTable — tabular data layer
 
 ```js
-import { ListController } from '@rokkit/states'
+import { ProxyTable, Wrapper } from '@rokkit/states'
 
-const ctrl = new ListController()
+const table = new ProxyTable(rows, { columns, fields, onsort })
+const wrapper = new Wrapper(table, { onselect, multiselect, collapsible: false })
 
-ctrl.selectedKeys // SvelteSet of selected path keys
-ctrl.expandedKeys // SvelteSet of expanded path keys
-ctrl.focusedKey // currently focused key
-ctrl.data // flat array of visible nodes
+table.columns // [{ name, label, sortable, sorted }, …]
+table.sortState // [{ column, direction }, …] in priority order
+table.sortBy('name', false) // cycle: none → ascending → descending → none
+table.sortBy('age', true) // multi-column sort (Shift+click)
+table.clearSort() // restore original order
+table.update(newRows) // re-applies any active sort
 ```
 
 ### vibe — reactive theme mode

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/states",
-  "version": "1.1.1",
+  "version": "1.1.5",
   "description": "Contains generic data manipulation functions that can be used in various components.",
   "repository": {
     "type": "git",
@@ -37,8 +37,8 @@
     }
   },
   "dependencies": {
-    "@rokkit/core": "1.1.1",
-    "@rokkit/data": "1.1.1",
+    "@rokkit/core": "1.1.5",
+    "@rokkit/data": "1.1.5",
     "d3-array": "^3.2.4",
     "ramda": "^0.32.0",
     "svelte": "^5.53.5"

package/src/index.js

@@ -1,10 +1,10 @@
 export { alerts } from './alerts.svelte.js'
-export { TableController } from './table-controller.svelte.js'
 export { vibe } from './vibe.svelte.js'
-export { ListController } from './list-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 { ProxyTable } from './proxy-table.svelte.js'
+export { ProxyTableTree } from './proxy-table-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/proxy-table-tree.svelte.js

@@ -0,0 +1,54 @@
+/**
+ * ProxyTableTree
+ *
+ * Hierarchical analog of ProxyTable. Accepts nested rows (each row may
+ * carry a `children: []` array) and exposes the same columns + sortState
+ * API as ProxyTable.
+ *
+ * Sort semantics differ from the flat case: sorting is applied within
+ * each parent's children array, so the parent/child structure is
+ * preserved. A single top-level sort by 'name' reorders siblings at
+ * every depth but never lifts a child out of its parent.
+ *
+ * Use the `nestByPath` / `nestByColumns` helpers from `@rokkit/data`
+ * to convert path-string or column-array flat shapes into the nested
+ * shape this class consumes.
+ */
+
+import { BASE_FIELDS } from '@rokkit/core'
+import { ProxyTable } from './proxy-table.svelte.js'
+
+export class ProxyTableTree extends ProxyTable {
+	#childField
+
+	/**
+	 * @param {Array<Record<string, unknown>>} [data]  Nested rows.
+	 * @param {{ columns?: Array, fields?: object, onsort?: Function }} [options]
+	 */
+	constructor(data = [], options = {}) {
+		super(data, options)
+		const fields = options.fields ?? {}
+		this.#childField = fields.children ?? BASE_FIELDS.children
+	}
+
+	/**
+	 * Recursively apply the current sortState to a nested row array.
+	 * Sorts siblings within each parent — children stay attached to their
+	 * own parent regardless of the sort order chosen.
+	 *
+	 * @param {Array<Record<string, unknown>>} rows
+	 * @returns {Array<Record<string, unknown>>}
+	 */
+	_sortedData(rows) {
+		if (this.sortState.length === 0) return rows
+		const sorted = [...rows].sort((a, b) => this._compareRows(a, b))
+		const field = this.#childField
+		return sorted.map((row) => {
+			const children = row[field]
+			if (Array.isArray(children) && children.length > 0) {
+				return { ...row, [field]: this._sortedData(children) }
+			}
+			return row
+		})
+	}
+}

package/src/proxy-table.svelte.js

@@ -0,0 +1,175 @@
+/**
+ * ProxyTable
+ *
+ * Tabular analog of ProxyTree. Owns flat row data plus column metadata and
+ * sort state. Composes ProxyTree's reactive data layer (flatView + lookup)
+ * so a plain Wrapper can navigate over a ProxyTable without modification.
+ *
+ * Splits cleanly into:
+ *   ProxyTree — owns rows-as-proxies + flatView + lookup
+ *   ProxyTable adds columns + sortState + sortBy/clearSort/update
+ *   Wrapper navigates over either
+ *
+ * Sort semantics:
+ *   - sortBy(name)        single-column sort (clears any prior sort)
+ *   - sortBy(name, true)  multi-column sort (extends the sort stack;
+ *                         repeat with same name to cycle the direction;
+ *                         direction 'none' removes that column from the stack)
+ *   - Three-state cycle per column: none → ascending → descending → none
+ *   - clearSort()         resets to original data order
+ */
+
+import { ascending, descending } from 'd3-array'
+import { deriveColumns } from '@rokkit/data'
+import { ProxyTree } from './proxy-tree.svelte.js'
+
+// ─── ProxyTable ───────────────────────────────────────────────────────────────
+
+export class ProxyTable extends ProxyTree {
+	columns = $state([])
+	sortState = $state([])
+
+	#rawData
+	#onsort
+
+	/**
+	 * @param {Array<Record<string, unknown>>} [data]
+	 * @param {{ columns?: Array, fields?: object, onsort?: Function }} [options]
+	 */
+	constructor(data = [], options = {}) {
+		super(data, options.fields)
+		this.#rawData = data
+		this.#onsort = options.onsort
+		this.columns = options.columns?.length
+			? options.columns.map((c) => ({ sortable: true, sorted: 'none', ...c }))
+			: deriveColumns(data)
+	}
+
+	// ─── Updates ─────────────────────────────────────────────────────────────
+
+	/**
+	 * Replace underlying data. Re-applies any active sort so the visible
+	 * rows stay in their sorted order.
+	 * @param {Array<Record<string, unknown>>} data
+	 */
+	update(data) {
+		this.#rawData = data
+		if (this.sortState.length === 0) {
+			this.replace(data)
+		} else {
+			this.replace(this._sortedData(this.#rawData))
+		}
+	}
+
+	/**
+	 * Protected accessor for subclasses that need to re-sort the underlying
+	 * data (e.g. ProxyTableTree on column-update).
+	 */
+	get _rawData() {
+		return this.#rawData
+	}
+
+	/**
+	 * Replace column definitions. Preserves any existing sort indicators
+	 * for columns that survive the rename.
+	 * @param {Array} columns
+	 */
+	updateColumns(columns) {
+		const prior = Object.fromEntries(this.columns.map((c) => [c.name, c.sorted ?? 'none']))
+		this.columns = columns.map((c) => ({
+			sortable: true,
+			sorted: prior[c.name] ?? 'none',
+			...c
+		}))
+	}
+
+	// ─── Sort API ────────────────────────────────────────────────────────────
+
+	/**
+	 * Toggle sort on a column. Direction cycle: none → ascending → descending → none.
+	 * Pass `extend=true` (Shift+click) to push onto the multi-column stack.
+	 * Fires the `onsort` callback after applying.
+	 *
+	 * @param {string} columnName
+	 * @param {boolean} [extend]
+	 */
+	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.replace(this._sortedData(this.#rawData))
+		this.#onsort?.(this.sortState)
+	}
+
+	/** Clear all sort state and restore the original data order. */
+	clearSort() {
+		this.sortState = []
+		this.columns = this.columns.map((c) => ({ ...c, sorted: 'none' }))
+		this.replace(this.#rawData)
+		this.#onsort?.(this.sortState)
+	}
+
+	// ─── Sort internals ──────────────────────────────────────────────────────
+
+	#nextSortDirection(col) {
+		const cycle = { none: 'ascending', ascending: 'descending', descending: 'none' }
+		return cycle[col.sorted ?? 'none']
+	}
+
+	#singleSortState(columnName, nextDirection) {
+		return 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 }]
+	}
+
+	#syncColumnFlags() {
+		this.columns = this.columns.map((c) => {
+			const sort = this.sortState.find((s) => s.column === c.name)
+			return { ...c, sorted: sort ? sort.direction : 'none' }
+		})
+	}
+
+	/**
+	 * Apply the current sortState to a row array. Subclasses (ProxyTableTree)
+	 * override to walk hierarchical structures.
+	 *
+	 * @param {Array<Record<string, unknown>>} rows
+	 * @returns {Array<Record<string, unknown>>}
+	 */
+	_sortedData(rows) {
+		if (this.sortState.length === 0) return rows
+		return [...rows].sort((a, b) => this._compareRows(a, b))
+	}
+
+	/**
+	 * Compare two rows under the current sortState. Used by `_sortedData()`
+	 * and by subclasses that sort over a hierarchical row tree.
+	 *
+	 * @param {Record<string, unknown>} a
+	 * @param {Record<string, unknown>} b
+	 * @returns {number}
+	 */
+	_compareRows(a, b) {
+		for (const { column, direction } of this.sortState) {
+			const cmp = direction === 'ascending' ? ascending : descending
+			const result = cmp(a[column], b[column])
+			if (result !== 0) return result
+		}
+		return 0
+	}
+}

package/src/proxy-tree.svelte.js

@@ -182,6 +182,19 @@ export class ProxyTree {
 		this.#rootProxies = [...this.#rootProxies, ...newProxies]
 	}
 
+	/**
+	 * Replace all root items. Reassigns #rootProxies to trigger $derived.
+	 * Keys are regenerated from the new item positions — focusedKey
+	 * continuity across replace is the caller's concern.
+	 *
+	 * @param {unknown[]} items  Raw items to use as new roots
+	 */
+	replace(items) {
+		this.#rootProxies = (items ?? []).map((raw, i) =>
+			this.#factory(raw, this.#fields, String(i), 1)
+		)
+	}
+
 	/**
 	 * Add children to an existing proxy node.
 	 * Uses proxy.set('children', rawItems) so ProxyItem's version counter

package/src/wrapper.svelte.js

@@ -15,8 +15,15 @@
  *
  * Dropdown variants (Select, Menu) extend this class and override cancel() / blur()
  * to close the dropdown and return focus to the trigger.
+ *
+ * Multi-select opt-in: pass `multiselect: true` to enable extend(path) and
+ * range(path) — ctrl/cmd-click and shift-click respectively. When false
+ * (default), both methods are no-ops so existing single-select consumers
+ * are unaffected.
  */
 
+import { SvelteSet } from 'svelte/reactivity'
+
 export class Wrapper {
 	// ─── Data ──────────────────────────────────────────────────────────────────
 
@@ -44,15 +51,22 @@ export class Wrapper {
 
 	#collapsible
 
+	// ─── Multi-select ──────────────────────────────────────────────────────────
+
+	#multiselect
+	#selectedKeys = new SvelteSet()
+	#anchorKey = $state(null)
+
 	/**
 	 * @param {import('./proxy-tree.svelte.js').ProxyTree} proxyTree
-	 * @param {{ onselect?: Function, onchange?: Function, collapsible?: boolean }} [options]
+	 * @param {{ onselect?: Function, onchange?: Function, collapsible?: boolean, multiselect?: boolean }} [options]
 	 */
 	constructor(proxyTree, options = {}) {
 		this.#proxyTree = proxyTree
 		this.#onselect = options.onselect
 		this.#onchange = options.onchange
 		this.#collapsible = options.collapsible ?? true
+		this.#multiselect = options.multiselect ?? false
 	}
 
 	// ─── IWrapper: state read by Navigator ─────────────────────────────────────
@@ -142,9 +156,16 @@ export class Wrapper {
 
 	/**
 	 * Fire value-change callbacks for a leaf selection.
+	 * In multi-select mode, replaces selectedKeys with just this key
+	 * (matching ListController's single-click semantics).
 	 * @param {*} proxy
+	 * @param {string} key
 	 */
-	#selectLeaf(proxy) {
+	#selectLeaf(proxy, key) {
+		if (this.#multiselect) {
+			this.#selectedKeys.clear()
+			this.#selectedKeys.add(key)
+		}
 		if (proxy.value !== this.#selectedValue) {
 			this.#selectedValue = proxy.value
 			this.#onchange?.(proxy.value, proxy)
@@ -156,11 +177,11 @@ export class Wrapper {
 	 * Select item at path (or focusedKey when path is null).
 	 * Groups toggle expanded (only when collapsible=true). Leaves fire onchange and onselect callbacks.
 	 */
-	#selectProxy(proxy) {
+	#selectProxy(proxy, key) {
 		if (proxy.hasChildren) {
 			if (this.#collapsible) proxy.expanded = !proxy.expanded
 		} else {
-			this.#selectLeaf(proxy)
+			this.#selectLeaf(proxy, key)
 		}
 	}
 
@@ -168,8 +189,9 @@ export class Wrapper {
 		const key = path ?? this.#focusedKey
 		if (!key) return
 		this.#focusedKey = key
+		this.#anchorKey = key
 		const proxy = this.#proxyTree.lookup.get(key)
-		if (proxy) this.#selectProxy(proxy)
+		if (proxy) this.#selectProxy(proxy, key)
 	}
 
 	/**
@@ -218,11 +240,74 @@ export class Wrapper {
 	/** Persistent list: no-op. Override in dropdown wrappers to close + restore trigger focus. */
 	blur() {}
 
-	/** Multiselect toggle — not yet implemented. */
-	extend(_path) {}
+	/**
+	 * Multi-select toggle — Ctrl/Cmd-click or Ctrl/Cmd-Space.
+	 * When `multiselect: false` (default) this is a no-op so single-select
+	 * consumers see the same behavior as before.
+	 *
+	 * Toggles `path` in `selectedKeys`, sets anchor for subsequent range select,
+	 * and fires `onselect` for leaf targets. Group targets update focus + anchor
+	 * but do not toggle into selectedKeys (groups aren't selectable values).
+	 *
+	 * @param {string|null} path
+	 */
+	extend(path) {
+		if (!this.#multiselect) return
+		const key = path ?? this.#focusedKey
+		if (!key) return
+		const proxy = this.#proxyTree.lookup.get(key)
+		if (!proxy) return
+
+		this.#focusedKey = key
+		this.#anchorKey = key
+		if (proxy.hasChildren) return
+
+		if (this.#selectedKeys.has(key)) {
+			this.#selectedKeys.delete(key)
+		} else {
+			this.#selectedKeys.add(key)
+		}
+		this.#onselect?.(proxy.value, proxy)
+	}
+
+	/**
+	 * Multi-select range — Shift-click or Shift-Space.
+	 * Selects every navigable item from the anchor (last single-click target,
+	 * or the focused item if no anchor) to `path`, inclusive. Replaces any
+	 * existing selection.
+	 *
+	 * When `multiselect: false` (default) this is a no-op.
+	 *
+	 * @param {string|null} path
+	 */
+	range(path) {
+		if (!this.#multiselect) return
+		const key = path ?? this.#focusedKey
+		if (!key) return
+
+		const anchorKey = this.#anchorKey ?? this.#focusedKey
+		if (!anchorKey) {
+			this.select(path)
+			return
+		}
+
+		const nav = this.#navigable
+		const anchorIdx = nav.findIndex((n) => n.key === anchorKey)
+		const targetIdx = nav.findIndex((n) => n.key === key)
+		if (anchorIdx < 0 || targetIdx < 0) return
+
+		const lo = Math.min(anchorIdx, targetIdx)
+		const hi = Math.max(anchorIdx, targetIdx)
+
+		this.#selectedKeys.clear()
+		for (let i = lo; i <= hi; i++) {
+			this.#selectedKeys.add(nav[i].key)
+		}
+		this.#focusedKey = key
 
-	/** Multiselect range — not yet implemented. */
-	range(_path) {}
+		const proxy = this.#proxyTree.lookup.get(key)
+		if (proxy && !proxy.hasChildren) this.#onselect?.(proxy.value, proxy)
+	}
 
 	// ─── IWrapper: typeahead ───────────────────────────────────────────────────
 
@@ -269,4 +354,31 @@ export class Wrapper {
 	get proxyTree() {
 		return this.#proxyTree
 	}
+
+	/**
+	 * Reactive set of selected keys. Tracks meaningfully only when
+	 * `multiselect: true` — in single-select mode it mirrors the most
+	 * recent `select()` target (one key at a time).
+	 *
+	 * @returns {SvelteSet<string>}
+	 */
+	get selectedKeys() {
+		return this.#selectedKeys
+	}
+
+	/**
+	 * In multi-select mode: array of selected leaf values (in selectedKeys order).
+	 * In single-select mode: the last selected value (back-compat with `select()`).
+	 *
+	 * @returns {unknown[] | unknown}
+	 */
+	get selected() {
+		if (!this.#multiselect) return this.#selectedValue
+		const out = []
+		for (const key of this.#selectedKeys) {
+			const proxy = this.#proxyTree.lookup.get(key)
+			if (proxy !== undefined) out.push(proxy.value)
+		}
+		return out
+	}
 }

package/src/derive.svelte.js

@@ -1,105 +0,0 @@
-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
- * @returns {Array}
- */
-function collectVisibleNodes(items, fields, path, expandedKeys) {
-	const 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
-}
-
- 
-export function flatVisibleNodes(items, fields = DEFAULT_FIELDS, path = [], expandedKeys = null) {
-	if (!items || !Array.isArray(items)) return []
-	return collectVisibleNodes(items, fields, path, expandedKeys)
-}
-
-/**
- * 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)
-	}
-}
-
-/**
- * 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]
-	}
-}
-
-/**
- * @param {SvelteMap} lookup  Accumulator map
- * @param {{ item: *, index: number, fields: *, path: Array<number> }} ctx
- */
- 
-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 SvelteMap()
-	if (!items || !Array.isArray(items)) return lookup
-	items.forEach((item, index) => visitLookupNode(lookup, { item, index, fields, path }))
-	return lookup
-}

package/src/list-controller.svelte.js

@@ -1,347 +0,0 @@
-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 = 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, [], this.expandedKeys))
-	lookup = $derived(deriveLookupWithProxy(this.items, this.fields))
-
-	constructor(items, value, fields, options) {
-		this.items = items
-		this.fields = { ...DEFAULT_FIELDS, ...fields }
-		this.mappers.push(new FieldMapper(fields))
-		this.#options = { multiselect: false, ...options }
-		this.#initExpandedKeys(items, this.fields)
-		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
-	 */
-	 
-	#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) => this.#initExpandedItem(item, index, fields, path))
-	}
-
-	/**
-	 * @private
-	 * @param {Array<*>} items
-	 * @param {*} value
-	 */
-	init(value) {
-		// items.forEach((item, index) => this.lookup.set(String(index), item))
-		this.moveToValue(value)
-	}
-
-	get isNested() {
-		return this.mappers.length > 1
-	}
-
-	get currentKey() {
-		return this.focusedKey
-	}
-
-	get currentIndex() {
-		return this.#currentIndex
-	}
-
-	/**
-	 * @private
-	 * @param {*} value
-	 * @returns
-	 */
-	findByValue(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] }
-	}
-
-	/**
-	 * @private
-	 * @param {*} value
-	 * @returns
-	 */
-	moveToValue(value = null) {
-		const { index, key } = this.findByValue(value)
-
-		this.selectedKeys.clear()
-		if (index >= 0) {
-			this.moveToIndex(index)
-			this.selectedKeys.add(key)
-		} else {
-			this.focusedKey = null
-			this.#currentIndex = -1
-		}
-		return true
-	}
-
-	/**
-	 *
-	 * @param {string|number} path - path key string (e.g. "0", "1-0", "2-1-3")
-	 * @returns
-	 */
-	moveTo(path) {
-		const key = String(path)
-		const index = this.data.findIndex((row) => row.key === key)
-		return index >= 0 ? this.moveToIndex(index) : false
-	}
-
-	/**
-	 * @private
-	 * @param {number} index
-	 */
-	moveToIndex(index) {
-		if (index >= 0 && index < this.data.length && this.#currentIndex !== index) {
-			this.#currentIndex = index
-			this.focusedKey = this.data[index].key
-			return true
-		}
-		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.moveLast()
-		for (let i = this.#currentIndex - 1; i >= 0; i--) {
-			if (!this.#isDisabled(i)) return this.moveToIndex(i)
-		}
-		return false
-	}
-
-	moveNext() {
-		for (let i = this.#currentIndex + 1; i < this.data.length; i++) {
-			if (!this.#isDisabled(i)) return this.moveToIndex(i)
-		}
-		return false
-	}
-
-	moveFirst() {
-		for (let i = 0; i < this.data.length; i++) {
-			if (!this.#isDisabled(i)) return this.moveToIndex(i)
-		}
-		return false
-	}
-
-	moveLast() {
-		for (let i = this.data.length - 1; i >= 0; i--) {
-			if (!this.#isDisabled(i)) return this.moveToIndex(i)
-		}
-		return false
-	}
-
-	/**
-	 * Toggles the selection.
-	 * @private
-	 * @param {string} key
-	 */
-	toggleSelection(key) {
-		if (this.selectedKeys.has(key)) {
-			this.selectedKeys.delete(key)
-		} else {
-			this.selectedKeys.add(key)
-		}
-
-		return true
-	}
-
-	/**
-	 *
-	 * @param {string} selectedKey
-	 * @returns
-	 */
-	select(selectedKey) {
-		const key = selectedKey ?? this.focusedKey
-
-		if (!this.lookup.has(key)) return false
-
-		if (this.focusedKey !== key) {
-			const { index } = this.findByValue(this.lookup.get(key).value)
-			this.moveToIndex(index)
-		}
-
-		if (!this.selectedKeys.has(key)) {
-			this.selectedKeys.clear()
-			this.selectedKeys.add(key)
-		}
-
-		this.#anchorKey = key
-		return true
-	}
-
-	/**
-	 *
-	 * @param {string} selectedKey
-	 * @returns
-	 */
-	extendSelection(selectedKey) {
-		const key = selectedKey ?? this.focusedKey
-
-		if (!this.lookup.has(key)) return false
-
-		if (this.#options.multiselect) {
-			this.#anchorKey = key
-			return this.toggleSelection(key)
-		} else {
-			return this.select(key)
-		}
-	}
-
-	/**
-	 * 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.
-	 * @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)
-		return this.#applyRangeSelection(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
-	}
-
-	/**
-	 * 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)
-	}
-
-	/**
-	 * 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()
-		const startIndex = this.#findStartIndex(startAfterKey)
-		for (let i = 0; i < this.data.length; i++) {
-			const idx = (startIndex + i) % this.data.length
-			if (this.#matchesText(idx, q)) return this.data[idx].key
-		}
-		return null
-	}
-
-	update(items) {
-		this.items = items
-	}
-}

package/src/table-controller.svelte.js

@@ -1,221 +0,0 @@
-import { ascending, descending } from 'd3-array'
-import { deriveColumns } from '@rokkit/data'
-import { ListController } from './list-controller.svelte.js'
-
-/**
- * TableController — manages table state via composition over ListController.
- *
- * Handles column metadata, sorting (single and multi-column), and delegates
- * row focus/selection/navigation to an internal ListController.
- */
-export class TableController {
-	columns = $state([])
-	sortState = $state([])
-
-	#list
-	#rawData
-	#fields
-
-	/**
-	 * @param {Array<Record<string, unknown>>} data - Row data
-	 * @param {Object} [options]
-	 * @param {Array} [options.columns] - Column definitions (auto-derived if empty)
-	 * @param {Object} [options.fields] - Row-level field mapping
-	 * @param {*} [options.value] - Initial selected value
-	 * @param {boolean} [options.multiselect] - Enable multi-row selection
-	 */
-	constructor(data = [], options = {}) {
-		const { columns, fields, value, multiselect } = options
-		this.#rawData = data
-		this.#fields = fields
-		this.columns = columns?.length
-			? columns.map((c) => ({ sortable: true, sorted: 'none', ...c }))
-			: deriveColumns(data)
-		this.#list = new ListController(data, value, fields, { multiselect })
-	}
-
-	// =========================================================================
-	// Sort
-	// =========================================================================
-
-	/**
-	 * Compute the next sort state for multi-column (extend) mode.
-	 * @param {string} columnName
-	 * @param {string} nextDirection
-	 * @returns {Array}
-	 */
-	#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 }]
-	}
-
-	/**
-	 * 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']
-	}
-
-	/**
-	 * 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()
-	}
-
-	/**
-	 * Clear all sort state and restore original data order.
-	 */
-	clearSort() {
-		this.sortState = []
-		this.columns = this.columns.map((c) => ({ ...c, sorted: 'none' }))
-		this.#list.update(this.#rawData)
-	}
-
-	/**
-	 * Apply current sortState to rawData and feed sorted data to list controller.
-	 * @private
-	 */
-	#applySortAndUpdate() {
-		if (this.sortState.length === 0) {
-			this.#list.update(this.#rawData)
-			return
-		}
-
-		const sorted = [...this.#rawData].sort((a, b) => {
-			for (const { column, direction } of this.sortState) {
-				const comparator = direction === 'ascending' ? ascending : descending
-				const result = comparator(a[column], b[column])
-				if (result !== 0) return result
-			}
-			return 0
-		})
-
-		this.#list.update(sorted)
-	}
-
-	// =========================================================================
-	// Data access (delegated to ListController)
-	// =========================================================================
-
-	get data() {
-		return this.#list.data
-	}
-
-	get lookup() {
-		return this.#list.lookup
-	}
-
-	get focusedKey() {
-		return this.#list.focusedKey
-	}
-
-	set focusedKey(v) {
-		this.#list.focusedKey = v
-	}
-
-	get focused() {
-		return this.#list.focused
-	}
-
-	get selected() {
-		return this.#list.selected
-	}
-
-	get selectedKeys() {
-		return this.#list.selectedKeys
-	}
-
-	// =========================================================================
-	// Navigation (delegated to ListController)
-	// =========================================================================
-
-	moveFirst() {
-		return this.#list.moveFirst()
-	}
-
-	moveLast() {
-		return this.#list.moveLast()
-	}
-
-	moveNext() {
-		return this.#list.moveNext()
-	}
-
-	movePrev() {
-		return this.#list.movePrev()
-	}
-
-	moveTo(path) {
-		return this.#list.moveTo(path)
-	}
-
-	moveToIndex(index) {
-		return this.#list.moveToIndex(index)
-	}
-
-	// =========================================================================
-	// Selection (delegated to ListController)
-	// =========================================================================
-
-	select(key) {
-		return this.#list.select(key)
-	}
-
-	extendSelection(key) {
-		return this.#list.extendSelection(key)
-	}
-
-	// =========================================================================
-	// Update
-	// =========================================================================
-
-	/**
-	 * Update the data source. Re-applies current sort if active.
-	 * @param {Array<Record<string, unknown>>} data
-	 */
-	update(data) {
-		this.#rawData = data
-		this.#applySortAndUpdate()
-	}
-}

package/src/traversal.svelte.js

@@ -1,137 +0,0 @@
-/**
- * Handles navigation through a flattened data structure
- */
-export class Traversal {
-	#dataProvider
-	#currentKey = $state(null)
-	#currentIndex = $derived(this.getCurrentIndex())
-
-	/**
-	 * @param {object} dataProvider - Data provider component
-	 */
-	constructor(dataProvider) {
-		this.#dataProvider = dataProvider
-	}
-
-	/**
-	 * Gets the current focused key
-	 * @returns {string|null} The current key or null if none selected
-	 */
-	get currentKey() {
-		return this.#currentKey
-	}
-
-	/**
-	 * Gets the current focused index
-	 * @returns {number} The current index or -1 if none selected
-	 */
-	get currentIndex() {
-		return this.#currentIndex
-	}
-
-	/**
-	 * Gets the currently focused item
-	 * @returns {object|null} The focused item or null
-	 */
-	get focused() {
-		return this.#currentKey ? this.#dataProvider.getItemByKey(this.#currentKey) : null
-	}
-
-	/**
-	 * Calculates the current index based on the current key
-	 * @private
-	 * @returns {number} The current index or -1 if not found
-	 */
-	getCurrentIndex() {
-		if (!this.#currentKey) return -1
-
-		const index = this.#dataProvider.getIndexForKey(this.#currentKey)
-		return index !== undefined ? index : -1
-	}
-
-	/**
-	 * Focuses on an item by its key
-	 * @param {string} key - Key of the item to focus
-	 * @returns {boolean} True if focus changed, false otherwise
-	 */
-	moveToKey(key) {
-		if (!key || !this.#dataProvider.lookup.has(key)) return false
-		if (this.#currentKey === key) return false
-
-		this.#currentKey = key
-		return true
-	}
-
-	/**
-	 * Focuses on an item by its index in the flattened list
-	 * @param {number} index - Index of the item to focus
-	 * @returns {boolean} True if focus changed, false otherwise
-	 */
-	moveToIndex(index) {
-		const nodes = this.#dataProvider.nodes
-
-		if (index < 0 || index >= nodes.length) return false
-		if (this.#currentIndex === index) return false
-
-		this.#currentKey = nodes[index].key
-		return true
-	}
-
-	/**
-	 * Focuses on an item by finding its value in the data
-	 * @param {*} value - Value to find and focus
-	 * @returns {boolean} True if found and focused, false otherwise
-	 */
-	moveToValue(value) {
-		if (!value) {
-			this.#currentKey = null
-			return true
-		}
-
-		const key = this.#dataProvider.getKeyForValue(value)
-		if (!key) return false
-
-		return this.moveToKey(key)
-	}
-
-	/**
-	 * Moves focus to the previous visible item
-	 * @returns {boolean} True if moved, false if at the beginning
-	 */
-	movePrev() {
-		if (this.#currentIndex > 0) {
-			return this.moveToIndex(this.#currentIndex - 1)
-		} else if (this.#currentIndex < 0 && this.#dataProvider.nodes.length > 0) {
-			return this.moveLast() // If not focused, go to last item
-		}
-		return false
-	}
-
-	/**
-	 * Moves focus to the next visible item
-	 * @returns {boolean} True if moved, false if at the end
-	 */
-	moveNext() {
-		if (this.#currentIndex < this.#dataProvider.nodes.length - 1) {
-			return this.moveToIndex(this.#currentIndex + 1)
-		}
-		return false
-	}
-
-	/**
-	 * Moves focus to the first item
-	 * @returns {boolean} True if moved, false otherwise
-	 */
-	moveFirst() {
-		return this.#dataProvider.nodes.length > 0 ? this.moveToIndex(0) : false
-	}
-
-	/**
-	 * Moves focus to the last item
-	 * @returns {boolean} True if moved, false otherwise
-	 */
-	moveLast() {
-		const lastIndex = this.#dataProvider.nodes.length - 1
-		return lastIndex >= 0 ? this.moveToIndex(lastIndex) : false
-	}
-}