@rokkit/states 1.0.0-next.106 → 1.0.0-next.107

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/states",
-  "version": "1.0.0-next.106",
+  "version": "1.0.0-next.107",
   "description": "Contains generic data manipulation functions that can be used in various components.",
   "author": "Jerry Thomas <me@jerrythomas.name>",
   "license": "MIT",
@@ -31,7 +31,7 @@
   },
   "dependencies": {
     "@lukeed/uuid": "^2.0.1",
-    "@rokkit/core": "1.0.0-next.105",
+    "@rokkit/core": "1.0.0-next.106",
     "d3-array": "^3.2.4",
     "d3-collection": "^1.0.7",
     "ramda": "^0.30.1",

package/src/base-proxy.svelte.js

@@ -0,0 +1,243 @@
+import { defaultFields } from '@rokkit/core'
+
+/**
+ * Base class for all proxy models that provides a common interface
+ * for navigation and selection operations.
+ *
+ * @abstract
+ */
+export class BaseProxy {
+	/** @type {any[]} Original data array */
+	data = $state(null)
+	/** @type {NodeProxy|null} Currently focused node */
+	nodes = $state([])
+	/** @type {NodeProxy[]} Flattened array of all visible nodes */
+	visibleNodes = $state([])
+
+	/** @type {NodeProxy|null} Currently focused node */
+	currentNode = $state(null)
+	/** @type {Object|null} Currently focused node */
+	value = $state(null)
+	/** @type {Map<string, NodeProxy>} Map of selected nodes by id */
+	selectedNodes = $state(new Map())
+
+	/** @type {Object} Field mappings */
+	fields
+
+	/** @type {Object} Configuration options */
+	options = {
+		multiSelect: false,
+		keyboardNavigation: true
+	}
+
+	/**
+	 * Creates a new proxy instance
+	 *
+	 * @param {any[]} data - Original data
+	 * @param {Object} fields - Field mappings
+	 * @param {Object} options - Configuration options
+	 */
+	constructor(data, value, fields = {}, options = {}) {
+		this.fields = { ...defaultFields, ...fields }
+		this.options = { ...this.options, ...options }
+		this.value = value
+
+		this.update(data)
+	}
+
+	/**
+	 * Updates the proxy with new data
+	 *
+	 * @param {any} data - New data to use
+	 * @returns {BaseProxy} - This proxy for method chaining
+	 */
+	update(data) {
+		this.data = data
+		this.reset()
+		return this
+	}
+
+	/**
+	 * Resets selection state
+	 *
+	 * @returns {BaseProxy} - This proxy for method chaining
+	 */
+	reset() {
+		this.selectedNodes.clear()
+		this.currentNode = null
+		return this
+	}
+
+	/**
+	 * Move to a specific target (index, path, or item)
+	 *
+	 * @abstract
+	 * @param {number|number[]} target - Target to move to
+	 * @returns {boolean} - True if moved, false otherwise
+	 */
+	moveTo() {
+		throw new Error('moveTo() must be implemented by subclass')
+	}
+
+	/**
+	 * Move to the next item
+	 *
+	 * @abstract
+	 * @returns {boolean} - True if moved, false otherwise
+	 */
+	moveNext() {
+		throw new Error('moveNext() must be implemented by subclass')
+	}
+
+	/**
+	 * Move to the previous item
+	 *
+	 * @abstract
+	 * @returns {boolean} - True if moved, false otherwise
+	 */
+	movePrev() {
+		throw new Error('movePrev() must be implemented by subclass')
+	}
+
+	/**
+	 * Expand the current node
+	 *
+	 * @returns {boolean} - True if expanded, false otherwise
+	 */
+	expand() {
+		// Default implementation for flat lists (no-op)
+		return false
+	}
+
+	/**
+	 * Collapse the current node
+	 *
+	 * @returns {boolean} - True if collapsed, false otherwise
+	 */
+	collapse() {
+		// Default implementation for flat lists (no-op)
+		return false
+	}
+
+	/**
+	 * Toggle expanded/collapsed state
+	 *
+	 * @returns {boolean} - True if state changed, false otherwise
+	 */
+	toggleExpansion() {
+		// Default implementation for flat lists (no-op)
+		return false
+	}
+
+	/**
+	 * Finds a node by a custom condition
+	 *
+	 * @param {Function} condition - Function that returns true for matching nodes
+	 * @returns {NodeProxy|null} - The found node or null
+	 */
+	find(condition) {
+		let result = null
+		for (let i = 0; i < this.nodes.length; i++) {
+			result = this.nodes[i].find(condition)
+			if (result) return result
+		}
+		return null
+	}
+
+	/**
+	 * Finds the path index by a custom condition
+	 *
+	 * @param {Function} condition - Function that returns true for matching nodes
+	 * @returns {number[]} - path index of found node or empty array
+	 */
+	findPathIndex(condition) {
+		const result = this.find(condition)
+		return result?.path ?? []
+	}
+
+	/**
+	 * Gets a node by its path
+	 *
+	 * @param {number|number[]} path - Path to the node
+	 * @returns {NodeProxy|null} - The node or null if not found
+	 */
+	getNodeByPath(path = []) {
+		path = Array.isArray(path) ? path : [path]
+
+		if (!path.length || !this.data) return null
+		return path.reduce((currentNodes, index, depth) => {
+			// If we've hit a dead end or invalid index, return null
+			if (currentNodes === null || index < 0 || index >= currentNodes.length) {
+				return null
+			}
+
+			// Get the node at the current index
+			const node = currentNodes[index]
+
+			// If we've reached the final depth, return the node
+			if (depth === path.length - 1) return node
+
+			// Otherwise, move to the next level (children)
+			return node.children
+		}, this.nodes)
+	}
+
+	/**
+	 * Selects the current node
+	 *
+	 * @param {number|number[]} [path] - The path to the node to toggle selection
+	 * @returns {boolean} - Whether the selection was successful
+	 */
+	select(path) {
+		const node = path ? this.getNodeByPath(path) : this.currentNode
+		if (!node) return false
+
+		if (!this.options.multiSelect) {
+			this.selectedNodes.forEach((node) => {
+				node.selected = false
+			})
+			this.selectedNodes.clear()
+		}
+
+		// Select the current node
+		node.selected = true
+		this.selectedNodes.set(node.id, node)
+		return true
+	}
+
+	/**
+	 * Toggles selection on the current node (for multi-select)
+	 *
+	 * @param {number|number[]} [path] - The path to the node to toggle selection
+	 * @returns {boolean} - Whether the operation was successful
+	 */
+	toggleSelection(path) {
+		const node = path ? this.getNodeByPath(path) : this.currentNode
+
+		if (!node) return false
+
+		node.selected = !node.selected
+		const nodeId = node.id
+
+		if (node.selected) {
+			this.selectedNodes.set(nodeId, node)
+		} else {
+			this.selectedNodes.delete(nodeId)
+		}
+		return true
+	}
+
+	/**
+	 * Extends selection on the current node (for multi-select)
+	 *
+	 * @param {number|number[]} [path] - The path to the node to extend selection
+	 * @returns {boolean} - Whether the operation was successful
+	 */
+	extendSelection(path) {
+		if (this.options.multiSelect) {
+			return this.toggleSelection(path)
+		} else {
+			return this.select(path)
+		}
+	}
+}

package/src/index.js

@@ -1,3 +1,7 @@
 export { DataWrapper } from './nested.svelte'
 export { TableWrapper } from './tabular.svelte'
+export { NodeProxy } from './node-proxy.svelte'
+export { ListProxy } from './list-proxy.svelte'
+export { NestedProxy } from './nested-proxy.svelte'
+export { Proxy } from './proxy.svelte'
 export { vibe } from './vibe.svelte'

package/src/list-proxy.svelte.js

@@ -0,0 +1,127 @@
+import { BaseProxy } from './base-proxy.svelte.js'
+import { NodeProxy } from './node-proxy.svelte.js'
+import { equals } from 'ramda'
+/**
+ * Manages a flat list of nodes with selection and focus capabilities
+ */
+export class ListProxy extends BaseProxy {
+	/**
+	 * Creates a new ListProxy
+	 *
+	 * @param {Object[]} data    - Original data array
+	 * @param {Object}   value   - Active value in the list
+	 * @param {Object}   fields  - Field mappings
+	 * @param {Object}   options - Configuration options
+	 */
+	constructor(data, value, fields = {}, options = {}) {
+		super(data, value, fields, options)
+		this.moveToValue(value)
+	}
+
+	/**
+	 * Updates the proxy with new data
+	 *
+	 * @param {any[]}    data    - New data to use
+	 * @returns {ListProxy}      - This proxy for method chaining
+	 */
+	update(data) {
+		this.data = data || null
+
+		// Create node proxies for all items
+		if (data && Array.isArray(data)) {
+			this.nodes = data.map((item, index) => new NodeProxy(item, [index], this.fields))
+		} else {
+			this.nodes = []
+		}
+
+		this.reset()
+		return this
+	}
+
+	/**
+	 * Moves focus to the specified target (index or item)
+	 *
+	 * @param {number|object} target - Index of the node or the node item to focus
+	 * @returns {boolean}            - Whether the move was successful
+	 */
+	moveTo(target) {
+		const index = Array.isArray(target) ? target[0] : target
+
+		// Validate index
+		if (index < 0 || index >= this.nodes.length) {
+			return false
+		}
+
+		// Update focus
+		if (this.currentNode) this.currentNode.focused = false
+
+		this.currentNode = this.nodes[index]
+		this.currentNode.focused = true
+
+		return true
+	}
+
+	/**
+	 * Moves focus to the next node
+	 *
+	 * @returns {boolean} - Whether the move was successful
+	 */
+	moveNext() {
+		if (!this.nodes.length) return false
+
+		let nextIndex = 0
+
+		if (this.currentNode) {
+			const currentIndex = this.nodes.indexOf(this.currentNode)
+			nextIndex = currentIndex + 1
+
+			// If at end of list, stay at current position
+			if (nextIndex >= this.nodes.length) {
+				return false
+			}
+		}
+
+		return this.moveTo(nextIndex)
+	}
+
+	/**
+	 * Moves focus to the previous node
+	 *
+	 * @returns {boolean} - Whether the move was successful
+	 */
+	movePrev() {
+		if (!this.nodes.length) return false
+
+		if (!this.currentNode) {
+			return this.moveTo(this.nodes.length - 1)
+		}
+
+		const currentIndex = this.nodes.indexOf(this.currentNode)
+		const prevIndex = currentIndex - 1
+
+		// If at start of list, stay at current position
+		if (prevIndex < 0) {
+			return false
+		}
+
+		return this.moveTo(prevIndex)
+	}
+
+	/**
+	 * Finds a node by value and makes it the current & active node
+	 *
+	 * @param {any} value
+	 * @returns
+	 */
+	moveToValue(value) {
+		if (!value || equals(this.currentNode?.value, value)) return false
+
+		const path = this.findPathIndex((node) => equals(node.value, value))
+		if (path.length > 0) {
+			this.moveTo(path)
+			this.select()
+			return true
+		}
+		return false
+	}
+}

package/src/nested-proxy.svelte.js

@@ -0,0 +1,286 @@
+import { BaseProxy } from './base-proxy.svelte.js'
+import { NodeProxy } from './node-proxy.svelte.js'
+import { equals } from 'ramda'
+
+/**
+ * Manages a hierarchical tree of nodes with selection, focus and expansion capabilities
+ */
+export class NestedProxy extends BaseProxy {
+	/**
+	 * Creates a new NestedProxy
+	 *
+	 * @param {any[]} data - Original hierarchical data array
+	 * @param {any} value - Initial value for the proxy
+	 * @param {Object} fields - Field mappings
+	 * @param {Object} options - Configuration options
+	 */
+	constructor(data, value, fields = {}, options = {}) {
+		// Default options for tree structures
+		const defaultTreeOptions = {
+			expandedByDefault: false
+		}
+
+		super(data, value, fields, { ...defaultTreeOptions, ...options })
+		this.moveToValue(value)
+		// this._refreshFlatNodes()
+	}
+
+	/**
+	 * Refreshes the flatNodes
+	 * @private
+	 */
+	_refreshFlatNodes(nodes = null) {
+		if (!nodes) {
+			this.visibleNodes = []
+			this._refreshFlatNodes(this.nodes)
+		} else {
+			nodes.forEach((node) => {
+				this.visibleNodes.push(node)
+				if (node.hasChildren() && node.expanded) {
+					this._refreshFlatNodes(node.children)
+				}
+			})
+		}
+	}
+
+	/**
+	 * Processes hierarchical data into node proxies
+	 *
+	 * @private
+	 * @param {any[]} items - Items to process
+	 */
+	processNodes(items) {
+		if (!items || !Array.isArray(items)) return
+
+		this.nodes = []
+		items.forEach((item, index) => {
+			const node = new NodeProxy(item, [index], this.fields)
+			this.nodes.push(node)
+		})
+		this._refreshFlatNodes()
+	}
+
+	/**
+	 * Updates the proxy with new data
+	 *
+	 * @param {any[]} data - New hierarchical data to use
+	 * @returns {NestedProxy} - This proxy for method chaining
+	 */
+	update(data) {
+		this.data = data || null
+		this.reset()
+
+		if (!data) {
+			this.visibleNodes = []
+			return this
+		}
+
+		// Create node tree and flatten visible nodes
+		this.processNodes(data)
+		return this
+	}
+
+	/**
+	 * Moves focus to the specified target (index, path)
+	 *
+	 * @param {number|number[]} target - index or path to move to
+	 * @returns {boolean} - Whether the move was successful
+	 */
+	moveTo(target) {
+		const targetNode = Array.isArray(target)
+			? this.find((node) => equals(node.path, target))
+			: this.visibleNodes[target]
+
+		if (!targetNode) return false
+
+		// Update focus
+		if (this.currentNode) {
+			this.currentNode.focused = false
+		}
+
+		this.currentNode = targetNode
+		this.currentNode.focused = true
+
+		return true
+	}
+
+	/**
+	 * Moves focus to the next visible node
+	 *
+	 * @returns {boolean} - Whether the move was successful
+	 */
+	moveNext() {
+		if (!this.visibleNodes.length) return false
+
+		let nextIndex = 0
+
+		if (this.currentNode) {
+			const currentIndex = this.visibleNodes.indexOf(this.currentNode)
+			nextIndex = currentIndex + 1
+
+			// If at end of list, stay at current position
+			if (nextIndex >= this.visibleNodes.length) {
+				return false
+			}
+		}
+
+		return this.moveTo(nextIndex)
+	}
+
+	/**
+	 * Moves focus to the previous visible node
+	 *
+	 * @returns {boolean} - Whether the move was successful
+	 */
+	movePrev() {
+		if (!this.visibleNodes.length) return false
+
+		if (!this.currentNode) {
+			return this.moveTo(this.visibleNodes.length - 1)
+		}
+
+		const currentIndex = this.visibleNodes.indexOf(this.currentNode)
+		const prevIndex = currentIndex - 1
+
+		// If at start of list, stay at current position
+		if (prevIndex < 0) {
+			return false
+		}
+
+		return this.moveTo(prevIndex)
+	}
+
+	/**
+	 * Expand the current node
+	 *
+	 * @param {number[]} [path] - The path to the node to expand
+	 * @returns {boolean} - Whether the node was expanded
+	 */
+	expand(path) {
+		const node = path ? this.getNodeByPath(path) : this.currentNode
+		if (!node || !node.hasChildren() || node.expanded) {
+			return false
+		}
+
+		node.expanded = true
+		this._refreshFlatNodes()
+		return true
+	}
+
+	/**
+	 * Collapse the current node
+	 *
+	 * @param {number[]} [path] - The path to the node to collapse
+	 * @returns {boolean} - Whether the node was collapsed
+	 */
+	collapse(path) {
+		const node = path ? this.getNodeByPath(path) : this.currentNode
+		if (!node || !node.hasChildren() || !node.expanded) return false
+
+		node.expanded = false
+		this._refreshFlatNodes()
+		return true
+	}
+
+	/**
+	 * Toggle expanded/collapsed state of current node
+	 *
+	 * @param {number[]} [path] - The path to the node to toggle expansion
+	 * @returns {boolean} - Whether the state changed
+	 */
+	toggleExpansion(path) {
+		const node = path ? this.getNodeByPath(path) : this.currentNode
+
+		if (!node || !node.hasChildren()) {
+			return false
+		}
+
+		node.expanded = !node.expanded
+		this._refreshFlatNodes()
+		return true
+	}
+
+	/**
+	 * Expands all nodes
+	 *
+	 * @returns {NestedProxy} - This proxy for method chaining
+	 */
+	expandAll() {
+		this.visibleNodes.forEach((node) => {
+			node.expandAll()
+		})
+
+		this._refreshFlatNodes()
+		return this
+	}
+
+	/**
+	 * Collapses all nodes
+	 *
+	 * @returns {NestedProxy} - This proxy for method chaining
+	 */
+	collapseAll() {
+		this.visibleNodes.forEach((node) => {
+			node.collapseAll()
+		})
+
+		this._refreshFlatNodes()
+		return this
+	}
+
+	/**
+	 * Resets selection and expansion state
+	 *
+	 * @returns {NestedProxy} - This proxy for method chaining
+	 */
+	reset() {
+		// Clear focus
+		if (this.currentNode) {
+			this.currentNode.focused = false
+			this.currentNode = null
+		}
+		if (this.options.expandedByDefault) this.expandAll()
+		this.nodes.forEach((node) => node.resetStates())
+		this.selectedNodes.clear()
+		this._refreshFlatNodes()
+
+		return this
+	}
+
+	/**
+	 * Ensures a node is visible by expanding its ancestors
+	 *
+	 * @param {NodeProxy} node - Node to make visible
+	 * @returns {boolean} - Whether the node is now visible
+	 */
+	ensureVisible(node) {
+		if (!node || !node.path || node.path.length <= 1) return true
+
+		for (let i = 1; i < node.path.length; i++) {
+			const parentNode = this.getNodeByPath(node.path.slice(0, i))
+			parentNode.expanded = true
+		}
+		this._refreshFlatNodes()
+		return true
+	}
+
+	/**
+	 * Finds a node by value and makes it the current & active node
+	 *
+	 * @param {any} value
+	 * @returns
+	 */
+	moveToValue(value) {
+		if (!value || equals(this.currentNode?.value, value)) return false
+
+		const targetNode = this.find((node) => equals(node.value, value))
+
+		if (targetNode) {
+			this.ensureVisible(targetNode)
+			this.moveTo(targetNode.path)
+			this.select()
+			return true
+		}
+		return false
+	}
+}

package/src/nested.svelte.js

@@ -1,4 +1,4 @@
-import { has, equals, pick, omit } from 'ramda'
+import { has, equals, pick } from 'ramda'
 import { SvelteMap } from 'svelte/reactivity'
 import { DEFAULT_EVENTS } from './constants'
 import { FieldMapper, getKeyFromPath } from '@rokkit/core'

package/src/node-proxy.svelte.js

@@ -0,0 +1,293 @@
+import { has, isNil } from 'ramda'
+import { defaultFields } from '@rokkit/core'
+/**
+ * Represents an individual node within a data structure
+ */
+export class NodeProxy {
+	/** @type {number[]} Path to this node */
+	path
+	/** @type {number} Depth in the hierarchy */
+	depth
+	/** @type {NodeProxy|null} Parent node */
+	parent = null
+
+	/** @type {any} Original data item */
+	original = $state({})
+	/** @type {string} Unique identifier */
+	id = $state()
+
+	/** @type {boolean} Whether this node is expanded */
+	expanded = $state(false)
+
+	/** @type {boolean} Whether this node is selected  */
+	selected = $state(false)
+
+	/** @type {boolean} Whether this node has focus */
+	focused = $state(false)
+
+	/** @type {NodeProxy[]} Child nodes */
+	children = []
+
+	#fields = {}
+	/**
+	 * Creates a new NodeProxy
+	 *
+	 * @param {any} item - Original data item
+	 * @param {number[]} path - Path to this node
+	 * @param {import('./field-mapper.js').FieldMapper} mapper - Field mapper
+	 * @param {NodeProxy|null} parent - Parent node
+	 */
+	constructor(item, path, fields, parent = null) {
+		this.original = typeof item === 'object' ? item : { text: item }
+		this.path = path
+		this.depth = path.length - 1
+		this.parent = parent
+		this.fields = { ...defaultFields, ...fields }
+
+		this._init()
+	}
+
+	_init() {
+		this.id = has(this.fields.id, this.original)
+			? String(this.original[this.fields.id])
+			: this.path.join('-')
+		this.expanded =
+			has(this.fields.isOpen, this.original) && Boolean(this.original[this.fields.isOpen])
+		this.selected =
+			has(this.fields.isSelected, this.original) && Boolean(this.original[this.fields.isSelected])
+		this._refreshAllChildren(this.path)
+	}
+
+	set fields(props) {
+		this.#fields = { ...defaultFields, ...props }
+	}
+
+	get fields() {
+		return this.#fields
+	}
+
+	/**
+	 * Gets a mapped attribute from the original item
+	 *
+	 * @param {string} fieldName - Name of the field to get
+	 * @returns {any|null} - The attribute value or null if not found
+	 */
+	get(fieldName) {
+		const mappedField = this.fields[fieldName]
+		if (!mappedField || !has(mappedField, this.original)) {
+			return null
+		}
+		return this.original[mappedField]
+	}
+
+	/**
+	 * Get the display text for this node
+	 * @returns {string}
+	 */
+	get text() {
+		return this.get('text')
+	}
+
+	/**
+	 * Get the icon for this node
+	 * @returns {string|null}
+	 */
+	get icon() {
+		return this.get('icon')
+	}
+
+	/**
+	 * Get formatted text using a formatter function
+	 * @param {Function} formatter - Function to format the text
+	 * @returns {string}
+	 */
+	formattedText(formatter) {
+		const text = this.get('text')
+		if (isNil(text)) return ''
+		if (typeof formatter !== 'function') return text.toString()
+		return formatter(text, this.get('currency'))
+	}
+
+	/**
+	 * Toggles the expanded state of this node
+	 */
+	toggle() {
+		this.expanded = !this.expanded
+
+		// Update original data if it has the isOpen field
+		if (has(this.fields.isOpen, this.original)) {
+			this.original[this.fields.isOpen] = this.expanded
+		}
+		return this
+	}
+
+	/**
+	 * Checks if this node has children
+	 * @returns {boolean}
+	 */
+	hasChildren() {
+		return this.children.length > 0
+	}
+
+	/**
+	 * Expand all children
+	 */
+	expandAll() {
+		if (this.hasChildren()) {
+			this.expanded = true
+			this.children.forEach((child) => child.expandAll())
+		}
+	}
+
+	/**
+	 * Collapse all children
+	 */
+	collapseAll() {
+		if (this.hasChildren()) {
+			this.children.forEach((child) => child.collapseAll())
+			this.expanded = false
+		}
+	}
+
+	/**
+	 * Checks if this node is a leaf node (no children)
+	 * @returns {boolean}
+	 */
+	isLeaf() {
+		return !this.hasChildren()
+	}
+
+	/**
+	 * Gets the path to this node
+	 * @returns {number[]}
+	 */
+	getPath() {
+		return [...this.path]
+	}
+
+	/**
+	 * Adds a child node proxy from an existing data item.
+	 * If index is provided, the child is inserted at that index, otherwise it is appended to the end
+	 * @param {any} childData - Child data to add (already exists in original data)
+	 * @returns {NodeProxy} - The newly created child node proxy
+	 */
+	addChild(childData, index = -1) {
+		if (this.children.length === 0) {
+			this.original[this.fields.children] = []
+		}
+		if (index < 0 || index > this.children.length) {
+			index = this.children.length
+		}
+
+		this.original[this.fields.children].splice(index, 0, childData)
+		this._refreshAllChildren(this.path)
+	}
+
+	/**
+	 * Removes a child node by index
+	 * @param {number} index - Index of the child to remove
+	 * @returns {boolean} - Whether the removal was successful
+	 */
+	removeChild(index) {
+		if (index < 0 || index >= this.children.length) {
+			return null
+		}
+		const child = this.original[this.fields.children][index]
+		this.original[this.fields.children].splice(index, 1)
+		this._refreshAllChildren(this.path)
+		return child
+	}
+
+	/**
+	 * Removes all children from this node
+	 * @private
+	 */
+	_removeAllChildren() {
+		this.children.forEach((child) => child.destroy())
+		this.children = []
+	}
+
+	/**
+	 * Checks if the original data has children
+	 * @private
+	 */
+	_hasChildren() {
+		const childAttr = this.fields.children
+		return has(childAttr, this.original) && Array.isArray(this.original[childAttr])
+	}
+
+	/**
+	 * Removes all children from this node
+	 * @private
+	 */
+	_refreshAllChildren(path) {
+		if (this.children.length > 0) this._removeAllChildren()
+		if (this._hasChildren()) {
+			const childFields = this.fields.fields ?? this.fields
+			this.original[this.fields.children].forEach((child, index) => {
+				const childNode = new NodeProxy(child, [...path, index], childFields, this)
+				this.children.push(childNode)
+			})
+		}
+	}
+
+	/**
+	 * Destroys this node, cleaning up references
+	 */
+	destroy() {
+		// Clean up all children first
+		this.children.forEach((child) => child.destroy())
+
+		// Clear references
+		this.children = []
+		this.parent = null
+	}
+
+	/**
+	 * Clear selected, focused states
+	 */
+	resetStates() {
+		this.selected = false
+		this.focused = false
+		if (this.children.length > 0) {
+			this.children.forEach((child) => child.resetStates())
+		}
+	}
+
+	/**
+	 * Get/Set the value for this node
+	 */
+	get value() {
+		return this.original
+	}
+
+	set value(newValue) {
+		if (typeof newValue === 'object') {
+			const removedKeys = Object.keys(this.original).filter(
+				(key) => !Object.keys(newValue).includes(key)
+			)
+			Object.entries(newValue).forEach(([k, v]) => {
+				this.original[k] = v
+			})
+			removedKeys.forEach((key) => {
+				delete this.original[key]
+			})
+			this._refreshAllChildren(this.path)
+		} else {
+			this.original.text = newValue
+		}
+	}
+
+	/**
+	 * Find nodes matching a criteria
+	 * @param {function} condition - The condition to match
+	 * @returns {NodeProxy|null} - First matching node or null if no matches found
+	 */
+	find(condition) {
+		if (condition(this)) return this
+		let result = null
+		for (let i = 0; i < this.children.length && !result; i++)
+			result = this.children[i].find(condition)
+		return result
+	}
+}

package/src/proxy.svelte.js

@@ -0,0 +1,59 @@
+import { defaultFields } from '@rokkit/core'
+import { isNil, has } from 'ramda'
+
+export class Proxy {
+	#value = $state({})
+	#fields = $state(defaultFields)
+
+	constructor(value, fields) {
+		this.#value = typeof value === 'object' ? value : { text: value }
+		this.fields = fields
+	}
+
+	get fields() {
+		return this.#fields
+	}
+	set fields(value) {
+		this.#fields = { ...defaultFields, ...value }
+	}
+
+	get value() {
+		return this.#value
+	}
+
+	set value(value) {
+		if (typeof value === 'object') {
+			const removedKeys = Object.keys(this.#value).filter(
+				(key) => !Object.keys(value).includes(key)
+			)
+			Object.entries(value).forEach(([k, v]) => {
+				this.#value[k] = v
+			})
+			removedKeys.forEach((key) => {
+				delete this.#value[key]
+			})
+		} else {
+			this.#value.text = value
+		}
+	}
+
+	/**
+	 * Gets a mapped attribute from the original item
+	 *
+	 * @param {string} fieldName - Name of the field to get
+	 * @returns {any|null} - The attribute value or null if not found
+	 */
+	get(fieldName) {
+		return this.has(fieldName) ? this.value[this.fields[fieldName]] : null
+	}
+
+	/**
+	 * Checks if a mapped attribute exists in the original item
+	 * @param {string} fieldName - Name of the field to check
+	 * @returns boolean
+	 */
+	has(fieldName) {
+		const mappedField = this.fields[fieldName]
+		return !isNil(mappedField) && has(mappedField, this.value)
+	}
+}