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

package/package.json

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

package/src/constants.js

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

package/src/derive.svelte.js

@@ -5,23 +5,25 @@ import { Proxy } from './proxy.svelte'
  * @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 }>}
  */
-export function flatVisibleNodes(items, fields = defaultFields, path = []) {
+export function flatVisibleNodes(items, fields = defaultFields, path = [], expandedKeys = null) {
 	const data = []
+	if (!items || !Array.isArray(items)) return data
+
 	items.forEach((item, index) => {
 		const itemPath = [...path, index]
 		const key = getKeyFromPath(itemPath)
-		const expanded =
-			Array.isArray(item[fields.children]) &&
-			item[fields.children].length > 0 &&
-			item[fields.expanded]
+		const hasChildren =
+			Array.isArray(item[fields.children]) && item[fields.children].length > 0
+		const expanded = hasChildren && (expandedKeys ? expandedKeys.has(key) : item[fields.expanded])
 
 		data.push({ key, value: item })
 
 		if (expanded) {
 			const childFields = getNestedFields(fields)
-			data.push(...flatVisibleNodes(item[fields.children], childFields, itemPath))
+			data.push(...flatVisibleNodes(item[fields.children], childFields, itemPath, expandedKeys))
 		}
 	})
 	return data
@@ -38,6 +40,7 @@ export function flatVisibleNodes(items, fields = defaultFields, path = []) {
  */
 export function deriveLookupWithProxy(items, fields = defaultFields, path = []) {
 	const lookup = new Map()
+	if (!items || !Array.isArray(items)) return lookup
 
 	items.forEach((item, index) => {
 		const itemPath = [...path, index]

package/src/index.js

@@ -1,5 +1,6 @@
-export { TableWrapper } from './tabular.svelte.js'
+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'

package/src/list-controller.svelte.js

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

package/src/messages.svelte.js

@@ -0,0 +1,45 @@
+/**
+ * Default messages for UI components
+ * @type {import('./types').Messages}
+ */
+const defaultMessages = {
+	emptyList: 'No items found',
+	emptyTree: 'No data available',
+	loading: 'Loading...',
+	noResults: 'No results found',
+	select: 'Select an option',
+	search: 'Search...'
+}
+
+/**
+ * Messages store for localized UI strings
+ */
+class MessagesStore {
+	/** @type {import('./types').Messages} */
+	#messages = $state({ ...defaultMessages })
+
+	/**
+	 * Get the current messages
+	 * @returns {import('./types').Messages}
+	 */
+	get current() {
+		return this.#messages
+	}
+
+	/**
+	 * Set custom messages (merges with defaults)
+	 * @param {Partial<import('./types').Messages>} custom
+	 */
+	set(custom) {
+		this.#messages = { ...defaultMessages, ...custom }
+	}
+
+	/**
+	 * Reset to default messages
+	 */
+	reset() {
+		this.#messages = { ...defaultMessages }
+	}
+}
+
+export const messages = new MessagesStore()

package/src/nested-controller.svelte.js

@@ -21,51 +21,74 @@ export class NestedController extends ListController {
 	 */
 	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.expand(nodeKey)
+			this.expandedKeys.add(nodeKey)
 		}
 		return true
 	}
 
 	/**
 	 * Toggle expansion of item
-	 * @param {*} value
-	 * @returns
+	 * @param {string} key
+	 * @returns {boolean}
 	 */
 	toggleExpansion(key) {
 		if (!this.lookup.has(key)) return false
-		const proxy = this.lookup.get(key)
-		proxy.expanded = !proxy.expanded
+		if (this.expandedKeys.has(key)) {
+			this.expandedKeys.delete(key)
+		} else {
+			this.expandedKeys.add(key)
+		}
 		return true
 	}
 
 	/**
-	 * Expand item
-	 * @param {*} value
-	 * @returns
+	 * 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 proxy = this.lookup.get(actualKey)
-		proxy.expanded = true
 
+		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
-	 * @param {*} value
-	 * @returns
+	 * 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
-		const proxy = this.lookup.get(actualKey)
-		proxy.expanded = false
-		return true
+
+		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

@@ -117,10 +117,4 @@ export class Proxy {
 	get expanded() {
 		return this.has('expanded') ? this.#value[this.fields.expanded] : false
 	}
-
-	set expanded(value) {
-		if (typeof this.#original === 'object') {
-			this.#value[this.fields.expanded] = Boolean(value)
-		}
-	}
 }

package/src/table-controller.svelte.js

@@ -0,0 +1,199 @@
+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
+	// =========================================================================
+
+	/**
+	 * 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
+
+		// 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 }]
+		}
+
+		// Update column sorted flags
+		this.columns = this.columns.map((c) => {
+			const sort = this.sortState.find((s) => s.column === c.name)
+			return { ...c, sorted: sort ? sort.direction : 'none' }
+		})
+
+		// Apply sort and update list
+		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/vibe.svelte.js

@@ -1,8 +1,9 @@
 /** @typedef {'light' | 'dark'} ThemeMode */
 /** @typedef {'cozy' | 'compact' | 'comfortable'} Density */
+/** @typedef {'ltr' | 'rtl'} Direction */
 
-import { defaultColors, defaultThemeMapping, themeRules } from '@rokkit/core'
-import { DEFAULT_STYLES, VALID_DENSITIES, VALID_MODES } from './constants'
+import { defaultColors, defaultThemeMapping, themeRules, detectDirection } from '@rokkit/core'
+import { DEFAULT_STYLES, VALID_DENSITIES, VALID_MODES, VALID_DIRECTIONS } from './constants'
 import { has } from 'ramda'
 
 /**
@@ -25,6 +26,7 @@ class Vibe {
 	#style = $state('rokkit')
 	#colors = $state(defaultColors)
 	#density = $state('comfortable')
+	#direction = $state(detectDirection())
 	#colorMap = $state(defaultThemeMapping)
 	#palette = $derived.by(() => themeRules(this.#colorMap, this.#colors))
 
@@ -105,6 +107,21 @@ class Vibe {
 		}
 	}
 
+	get direction() {
+		return this.#direction
+	}
+
+	set direction(value) {
+		if (isAllowedValue(value, VALID_DIRECTIONS, this.#direction)) {
+			this.#direction = value
+		}
+	}
+
+	/** @returns {boolean} */
+	get isRTL() {
+		return this.#direction === 'rtl'
+	}
+
 	get palette() {
 		return this.#palette
 	}
@@ -133,7 +150,12 @@ class Vibe {
 		if (!key) throw new Error('Key is required')
 
 		try {
-			const config = { style: this.#style, mode: this.#mode, density: this.#density }
+			const config = {
+				style: this.#style,
+				mode: this.#mode,
+				density: this.#density,
+				direction: this.#direction
+			}
 			localStorage.setItem(key, JSON.stringify(config))
 		} catch (e) {
 			// eslint-disable-next-line no-console
@@ -149,6 +171,15 @@ class Vibe {
 		this.style = value.style
 		this.mode = value.mode
 		this.density = value.density
+		this.direction = value.direction
+	}
+
+	/**
+	 * Re-detect direction from document
+	 * Useful when lang attribute changes dynamically
+	 */
+	detectDirection() {
+		this.#direction = detectDirection()
 	}
 }