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

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, DEFAULT_THEME_MAPPING, themeRules, detectDirection } from '@rokkit/core'
+import { DEFAULT_STYLES, VALID_DENSITIES, VALID_MODES, VALID_DIRECTIONS } from './constants'
 import { has } from 'ramda'
 
 /**
@@ -25,7 +26,8 @@ class Vibe {
 	#style = $state('rokkit')
 	#colors = $state(defaultColors)
 	#density = $state('comfortable')
-	#colorMap = $state(defaultThemeMapping)
+	#direction = $state(detectDirection())
+	#colorMap = $state(DEFAULT_THEME_MAPPING)
 	#palette = $derived.by(() => themeRules(this.#colorMap, this.#colors))
 
 	/**
@@ -61,7 +63,7 @@ class Vibe {
 			if (missing.length > 0) {
 				throw new Error(`Did you forget to define "${missing.join(', ')}"?`)
 			}
-			this.#colorMap = { ...defaultThemeMapping, ...value }
+			this.#colorMap = { ...DEFAULT_THEME_MAPPING, ...value }
 		}
 	}
 
@@ -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()
 	}
 }
 

package/src/wrapper.svelte.js

@@ -0,0 +1,231 @@
+/**
+ * Wrapper
+ *
+ * Navigation controller for persistent list/tree/sidebar components.
+ * Accepts a ProxyTree instance for reactive data (flatView, lookup),
+ * and provides full navigation, expansion, selection, and typeahead logic.
+ *
+ * ProxyTree owns the data layer: items -> proxies -> flatView + lookup.
+ * Wrapper owns the navigation layer: focusedKey, movement, selection callbacks.
+ *
+ * Designed for any persistent (always-visible) component:
+ *   - Sidebar navigation (links, collapsible groups)
+ *   - List / Tree components
+ *   - Any option list rendered inline
+ *
+ * Dropdown variants (Select, Menu) extend this class and override cancel() / blur()
+ * to close the dropdown and return focus to the trigger.
+ */
+
+export class Wrapper {
+	// ─── Data ──────────────────────────────────────────────────────────────────
+
+	#proxyTree
+
+	// flatView: re-derives from proxyTree's flatView, which itself re-derives
+	// when any proxy.expanded or proxy.children changes.
+	flatView = $derived(this.#proxyTree.flatView)
+
+	// Navigable items: exclude separators, spacers, and disabled items.
+	// This is the subset that keyboard navigation moves through.
+	#navigable = $derived(
+		this.flatView.filter(
+			(n) => n.type !== 'separator' && n.type !== 'spacer' && !n.proxy.disabled
+		)
+	)
+
+	// ─── State ──────────────────────────────────────────────────────────────────
+
+	#focusedKey = $state(null)
+
+	// ─── Callbacks ──────────────────────────────────────────────────────────────
+
+	#onselect
+	#onchange
+	#selectedValue = $state(undefined)
+
+	/**
+	 * @param {import('./proxy-tree.svelte.js').ProxyTree} proxyTree
+	 * @param {{ onselect?: Function, onchange?: Function }} [options]
+	 */
+	constructor(proxyTree, options = {}) {
+		this.#proxyTree = proxyTree
+		this.#onselect = options.onselect
+		this.#onchange = options.onchange
+	}
+
+	// ─── IWrapper: state read by Navigator ─────────────────────────────────────
+
+	get focusedKey() { return this.#focusedKey }
+
+	// ─── IWrapper: movement (path passed through but ignored) ──────────────────
+
+	/** Move focus to the next navigable item; clamp at end. */
+	next(_path) {
+		const nav = this.#navigable
+		if (!nav.length) return
+		const idx = nav.findIndex((n) => n.key === this.#focusedKey)
+		if (idx < nav.length - 1) this.#focusedKey = nav[idx + 1].key
+	}
+
+	/** Move focus to the previous navigable item; clamp at start. */
+	prev(_path) {
+		const nav = this.#navigable
+		if (!nav.length) return
+		const idx = nav.findIndex((n) => n.key === this.#focusedKey)
+		if (idx > 0) this.#focusedKey = nav[idx - 1].key
+	}
+
+	/** Move focus to the first navigable item. */
+	first(_path) {
+		const nav = this.#navigable
+		if (nav.length) this.#focusedKey = nav[0].key
+	}
+
+	/** Move focus to the last navigable item. */
+	last(_path) {
+		const nav = this.#navigable
+		if (nav.length) this.#focusedKey = nav[nav.length - 1].key
+	}
+
+	/**
+	 * Expand focused group, or move focus into it if already open.
+	 * No-op on leaf items.
+	 */
+	expand(_path) {
+		if (!this.#focusedKey) return
+		const node = this.flatView.find((n) => n.key === this.#focusedKey)
+		if (!node || !node.hasChildren) return
+		if (!node.proxy.expanded) {
+			node.proxy.expanded = true
+		} else {
+			// Already open — advance focus to first visible child
+			this.next(null)
+		}
+	}
+
+	/**
+	 * Collapse focused group, or move focus to parent if already collapsed / leaf.
+	 * At root level with no parent: no-op.
+	 */
+	collapse(_path) {
+		if (!this.#focusedKey) return
+		const node = this.flatView.find((n) => n.key === this.#focusedKey)
+		if (!node) return
+		if (node.hasChildren && node.proxy.expanded) {
+			node.proxy.expanded = false
+		} else {
+			// Move to parent: strip the last segment from the key
+			const parts = this.#focusedKey.split('-')
+			if (parts.length > 1) {
+				parts.pop()
+				this.#focusedKey = parts.join('-')
+			}
+			// At root level (no '-'): no-op — already at root
+		}
+	}
+
+	// ─── IWrapper: selection actions ───────────────────────────────────────────
+
+	/**
+	 * Select item at path (or focusedKey when path is null).
+	 * Groups toggle expanded. Leaves fire onchange (value differs) and onselect callbacks.
+	 */
+	select(path) {
+		const key = path ?? this.#focusedKey
+		if (!key) return
+		this.#focusedKey = key
+		const proxy = this.#proxyTree.lookup.get(key)
+		if (!proxy) return
+		if (proxy.hasChildren) {
+			proxy.expanded = !proxy.expanded
+		} else {
+			if (proxy.value !== this.#selectedValue) {
+				this.#selectedValue = proxy.value
+				this.#onchange?.(proxy.value, proxy)
+			}
+			this.#onselect?.(proxy.value, proxy)
+		}
+	}
+
+	/**
+	 * Toggle expansion of group at path — called by Navigator for accordion-trigger clicks.
+	 * Unlike select(), this only applies to groups and never fires onselect.
+	 */
+	toggle(path) {
+		const key = path ?? this.#focusedKey
+		if (!key) return
+		const proxy = this.#proxyTree.lookup.get(key)
+		if (proxy?.hasChildren) proxy.expanded = !proxy.expanded
+	}
+
+	/**
+	 * Sync focused state to path — called by Navigator on focusin and typeahead match.
+	 */
+	moveTo(path) {
+		if (path !== null) this.#focusedKey = path
+	}
+
+	/**
+	 * Sync focused key to the item matching this semantic value.
+	 * Used by controlled components (Toggle, Select) to keep navigation
+	 * in sync when the bound value changes externally.
+	 *
+	 * @param {unknown} v
+	 */
+	moveToValue(v) {
+		if (v === undefined || v === null) return
+		for (const [key, proxy] of this.#proxyTree.lookup) {
+			if (proxy.value === v) {
+				this.#focusedKey = key
+				this.#selectedValue = v
+				return
+			}
+		}
+	}
+
+	/** Persistent list: no dropdown to close. Override in dropdown wrappers. */
+	cancel(_path) {}
+
+	/** Persistent list: no-op. Override in dropdown wrappers to close + restore trigger focus. */
+	blur() {}
+
+	/** Multiselect toggle — not yet implemented. */
+	extend(_path) {}
+
+	/** Multiselect range — not yet implemented. */
+	range(_path) {}
+
+	// ─── IWrapper: typeahead ───────────────────────────────────────────────────
+
+	/**
+	 * Return the key of the first navigable item whose text starts with query
+	 * (case-insensitive). Wraps around. startAfterKey enables cycling.
+	 * Returns null if no match.
+	 *
+	 * @param {string} query
+	 * @param {string|null} [startAfterKey]
+	 * @returns {string|null}
+	 */
+	findByText(query, startAfterKey = null) {
+		const nav = this.#navigable
+		if (!nav.length) return null
+		const q = query.toLowerCase()
+		const startIdx = startAfterKey
+			? nav.findIndex((n) => n.key === startAfterKey) + 1
+			: 0
+		for (let i = 0; i < nav.length; i++) {
+			const node = nav[(startIdx + i) % nav.length]
+			if (node.proxy.label.toLowerCase().startsWith(q)) return node.key
+		}
+		return null
+	}
+
+	// ─── Helpers for the component ─────────────────────────────────────────────
+
+	/** @returns {Map<string, import('./proxy-item.svelte.js').ProxyItem>} */
+	get lookup() { return this.#proxyTree.lookup }
+
+	/** @returns {import('./proxy-tree.svelte.js').ProxyTree} */
+	get proxyTree() { return this.#proxyTree }
+}

package/src/nested-controller.svelte.js

@@ -1,71 +0,0 @@
-import { getKeyFromPath, getPathFromKey } from '@rokkit/core'
-import { equals } from 'ramda'
-import { ListController } from './list-controller.svelte'
-
-export class NestedController extends ListController {
-	/**
-	 * @protected
-	 * @param {Object} [value]
-	 */
-	init(value) {
-		if (value) {
-			this.ensureVisible(value)
-			this.moveToValue(value)
-		}
-	}
-
-	/**
-	 * Mark parents as expanded so that item is visible
-	 * @param {*} value
-	 * @returns
-	 */
-	ensureVisible(value) {
-		const result = this.lookup.entries().find((entry) => equals(entry[1].value, value))
-		const path = getPathFromKey(result[0])
-
-		for (let i = 1; i < path.length; i++) {
-			const nodeKey = getKeyFromPath(path.slice(0, i))
-			this.expand(nodeKey)
-		}
-		return true
-	}
-
-	/**
-	 * Toggle expansion of item
-	 * @param {*} value
-	 * @returns
-	 */
-	toggleExpansion(key) {
-		if (!this.lookup.has(key)) return false
-		const proxy = this.lookup.get(key)
-		proxy.expanded = !proxy.expanded
-		return true
-	}
-
-	/**
-	 * Expand item
-	 * @param {*} value
-	 * @returns
-	 */
-	expand(key) {
-		const actualKey = key ?? this.focusedKey
-		if (!this.lookup.has(actualKey)) return false
-		const proxy = this.lookup.get(actualKey)
-		proxy.expanded = true
-
-		return true
-	}
-
-	/**
-	 * Collapse item
-	 * @param {*} value
-	 * @returns
-	 */
-	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
-	}
-}

package/src/proxy.svelte.js

@@ -1,126 +0,0 @@
-import { defaultFields, id, toString, getNestedFields } from '@rokkit/core'
-import { isNil, has } from 'ramda'
-
-export class Proxy {
-	#original = null
-	#value = $state(null)
-	#fields = defaultFields
-	#id = null
-
-	#children = $derived(this.#processChildren())
-
-	constructor(value, fields) {
-		this.fields = fields
-		this.#original = value
-		this.#value = typeof value === 'object' ? value : { [this.fields.text]: value }
-		this.id = typeof value === 'object' ? (this.get('id') ?? id()) : value
-	}
-
-	#processChildren() {
-		if (isNil(this.#value)) return []
-
-		const children = this.#value[this.fields.children] ?? []
-		if (Array.isArray(children)) {
-			const fields = getNestedFields(this.fields)
-			return children.map((child) => new Proxy(child, fields))
-		}
-		return []
-	}
-
-	get id() {
-		return this.#id
-	}
-	set id(new_id) {
-		this.#id = typeof new_id === 'string' ? new_id : toString(new_id)
-	}
-	get children() {
-		return this.#children
-	}
-	get fields() {
-		return this.#fields
-	}
-	set fields(value) {
-		this.#fields = { ...defaultFields, ...value }
-	}
-
-	get value() {
-		return typeof this.#original === 'object' ? this.#value : this.#original
-	}
-
-	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 = { [this.fields.text]: value }
-			this.#original = value
-		}
-	}
-
-	/**
-	 * Gets a mapped attribute from the original item
-	 *
-	 * @param {string} fieldName - Name of the field to get
-	 * @param {any}   [defaultValue] - Default value to return if not found
-	 * @returns {any|undefined} - The attribute value or null if not found
-	 */
-	get(fieldName, defaultValue) {
-		return this.has(fieldName) ? this.#value[this.fields[fieldName]] : defaultValue
-	}
-
-	/**
-	 * 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)
-	}
-
-	/**
-	 * Gets the appropriate snippet for rendering this item:
-	 * - Uses the 'snippet' field from the current item to find the snippet key
-	 * - Finds a matching snippet in the provided collection using this key
-	 * - Falls back to the defaultSnippet if:
-	 *   - No snippet key is configured for this item
-	 *   - The configured snippet key doesn't exist in the snippets collection
-	 * @param {Object} snippets
-	 * @param {import('svelte').Snippet|undefined} [defaultSnippet]
-	 * @returns {import('svelte').Snippet|undefined}
-	 */
-	getSnippet(snippets, defaultSnippet) {
-		const snippetKey = this.get('snippet')
-		const snippet = has(snippetKey, snippets) ? snippets[snippetKey] : undefined
-		return snippet ?? defaultSnippet
-	}
-
-	/**
-	 * Identifies if the item has children
-	 */
-	get hasChildren() {
-		return (
-			typeof this.#original === 'object' &&
-			has(this.fields.children, this.#value) &&
-			Array.isArray(this.#value[this.fields.children]) &&
-			this.#value[this.fields.children].length > 0
-		)
-	}
-
-	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)
-		}
-	}
-}