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

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/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()
+	}
+}