@rokkit/states 1.0.0-next.133 → 1.0.0-next.134

package/README.md

@@ -0,0 +1,161 @@
+# @rokkit/states
+
+Reactive state management for Rokkit UI components — ProxyItem, ProxyTree, Wrapper, ListController.
+
+## Installation
+
+```bash
+npm install @rokkit/states
+# or
+bun add @rokkit/states
+```
+
+## Overview
+
+`@rokkit/states` provides the reactive data layer that drives `@rokkit/ui` components. It includes:
+
+- **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
+- **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.
+
+## Usage
+
+### ProxyItem — normalize any data object
+
+```js
+import { ProxyItem } from '@rokkit/states'
+
+const item = { name: 'Dashboard', path: '/dashboard', icon: 'i-solar:home' }
+const fields = { label: 'name', value: 'path' }
+
+const proxy = new ProxyItem(item, fields)
+
+proxy.label // 'Dashboard'
+proxy.value // '/dashboard'
+proxy.get('icon') // 'i-solar:home'
+proxy.selected // reactive boolean ($state)
+proxy.disabled // boolean
+proxy.children // child ProxyItems (if item has children)
+```
+
+### ProxyTree — build a navigable tree from nested data
+
+```js
+import { ProxyTree } from '@rokkit/states'
+
+const items = [
+  {
+    label: 'Section A',
+    children: [
+      { label: 'Item 1', value: '1' },
+      { label: 'Item 2', value: '2' }
+    ]
+  },
+  { label: 'Item 3', value: '3' }
+]
+
+const tree = new ProxyTree(items)
+tree.flatView // flat array of visible nodes for rendering
+tree.lookup // Map<pathKey, ProxyItem>
+```
+
+### Wrapper — navigation controller for persistent components
+
+```js
+import { ProxyTree, Wrapper } from '@rokkit/states'
+
+const tree = new ProxyTree(items)
+const wrapper = new Wrapper(tree, {
+  onselect: (value, item) => console.log('selected', value),
+  onchange: (value) => console.log('changed', value)
+})
+
+wrapper.flatView // flat array of visible nodes
+wrapper.focusedKey // currently focused path key (reactive)
+
+wrapper.next() // move focus down
+wrapper.prev() // move focus up
+wrapper.first() // jump to first item
+wrapper.last() // jump to last item
+wrapper.select(pathKey) // select item by path key
+wrapper.expand(pathKey) // expand a group node
+wrapper.collapse(pathKey)
+wrapper.moveToValue(value) // sync focus to match an external value
+```
+
+### ListController — base reactive state
+
+```js
+import { ListController } from '@rokkit/states'
+
+const ctrl = new ListController()
+
+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
+```
+
+### vibe — reactive theme mode
+
+```js
+import { vibe } from '@rokkit/states'
+
+vibe.mode // 'light' | 'dark'
+vibe.toggle() // switch between light and dark
+```
+
+### messages — i18n message store
+
+```js
+import { messages } from '@rokkit/states'
+
+messages.setLocale('fr')
+messages.get('no_results') // localized string
+```
+
+### watchMedia — responsive breakpoints
+
+```js
+import { watchMedia, defaultBreakpoints } from '@rokkit/states'
+
+const media = watchMedia(defaultBreakpoints)
+media.sm // reactive boolean — true when viewport matches 'sm'
+media.lg // reactive boolean
+```
+
+## API Reference
+
+### ProxyItem
+
+| Member       | Type          | Description                         |
+| ------------ | ------------- | ----------------------------------- |
+| `label`      | `string`      | Display text (field-mapped)         |
+| `value`      | `any`         | Selection value (field-mapped)      |
+| `get(field)` | `any`         | Read any field-mapped attribute     |
+| `expanded`   | `boolean`     | Reactive expansion state            |
+| `selected`   | `boolean`     | Reactive selection state            |
+| `disabled`   | `boolean`     | Whether the item is non-interactive |
+| `children`   | `ProxyItem[]` | Child items                         |
+
+### Wrapper
+
+| Member               | Type             | Description                                               |
+| -------------------- | ---------------- | --------------------------------------------------------- |
+| `flatView`           | `Node[]`         | Flat array of visible nodes for rendering                 |
+| `focusedKey`         | `string \| null` | Currently focused path key                                |
+| `next()`             | `void`           | Move focus to next navigable item                         |
+| `prev()`             | `void`           | Move focus to previous navigable item                     |
+| `first()`            | `void`           | Move focus to first item                                  |
+| `last()`             | `void`           | Move focus to last item                                   |
+| `select(key)`        | `void`           | Select item by path key                                   |
+| `expand(key)`        | `boolean`        | Expand a group; returns false if already expanded or leaf |
+| `collapse(key)`      | `void`           | Collapse a group or move focus to parent                  |
+| `moveToValue(value)` | `void`           | Sync focus to match an external bound value               |
+
+---
+
+Part of [Rokkit](https://github.com/jerrythomas/rokkit) — a Svelte 5 component library and design system.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/states",
-  "version": "1.0.0-next.133",
+  "version": "1.0.0-next.134",
   "description": "Contains generic data manipulation functions that can be used in various components.",
   "author": "Jerry Thomas <me@jerrythomas.name>",
   "license": "MIT",
@@ -13,12 +13,14 @@
   },
   "scripts": {
     "prepublishOnly": "cp ../../LICENSE . && tsc --project tsconfig.build.json",
+    "postpublish": "rm -f LICENSE",
     "clean": "rm -rf dist",
     "build": "bun clean && bun prepublishOnly"
   },
   "files": [
     "src/**/*.js",
     "src/**/*.svelte",
+    "README.md",
     "LICENSE"
   ],
   "exports": {
@@ -31,8 +33,8 @@
     }
   },
   "dependencies": {
-    "@rokkit/core": "1.0.0-next.133",
-    "@rokkit/data": "1.0.0-next.133",
+    "@rokkit/core": "1.0.0-next.134",
+    "@rokkit/data": "1.0.0-next.134",
     "d3-array": "^3.2.4",
     "ramda": "^0.32.0",
     "svelte": "^5.53.5"

package/src/derive.svelte.js

@@ -16,8 +16,7 @@ export function flatVisibleNodes(items, fields = DEFAULT_FIELDS, path = [], expa
 	items.forEach((item, index) => {
 		const itemPath = [...path, index]
 		const key = getKeyFromPath(itemPath)
-		const hasChildren =
-			Array.isArray(item[fields.children]) && item[fields.children].length > 0
+		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, level, hasChildren })

package/src/lazy-wrapper.svelte.js

@@ -86,7 +86,9 @@ export class LazyWrapper extends Wrapper {
 
 		// Lazy sentinel: fetch children, then expand
 		if (proxy.loaded === false) {
-			proxy.fetch().then(() => { proxy.expanded = true })
+			proxy.fetch().then(() => {
+				proxy.expanded = true
+			})
 			return
 		}
 
@@ -112,7 +114,9 @@ export class LazyWrapper extends Wrapper {
 
 		// Lazy sentinel: fetch children, then expand
 		if (proxy.loaded === false) {
-			proxy.fetch().then(() => { proxy.expanded = true })
+			proxy.fetch().then(() => {
+				proxy.expanded = true
+			})
 			return
 		}
 	}

package/src/list-controller.svelte.js

@@ -83,7 +83,10 @@ export class ListController {
 		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)
+				(row) =>
+					typeof row.value === 'object' &&
+					row.value !== null &&
+					equals(row.value[valueField], value)
 			)
 		}
 

package/src/messages.svelte.js

@@ -10,21 +10,38 @@ const defaultMessages = {
 	select: 'Select an option',
 	search: 'Search...',
 	list: { label: 'List' },
-	tree: { label: 'Tree', expand: 'Expand', collapse: 'Collapse', loading: 'Loading', loadMore: 'Load More' },
+	tree: {
+		label: 'Tree',
+		expand: 'Expand',
+		collapse: 'Collapse',
+		loading: 'Loading',
+		loadMore: 'Load More'
+	},
 	toolbar: { label: 'Toolbar' },
 	menu: { label: 'Menu' },
 	toggle: { label: 'Selection' },
 	rating: { label: 'Rating' },
 	stepper: { label: 'Progress' },
 	breadcrumbs: { label: 'Breadcrumb' },
-	carousel: { label: 'Carousel', prev: 'Previous slide', next: 'Next slide', slides: 'Slide navigation' },
+	carousel: {
+		label: 'Carousel',
+		prev: 'Previous slide',
+		next: 'Next slide',
+		slides: 'Slide navigation'
+	},
 	tabs: { add: 'Add tab', remove: 'Remove tab' },
 	code: { copy: 'Copy code', copied: 'Copied!' },
 	range: { lower: 'Lower bound', upper: 'Upper bound', value: 'Value' },
 	search_: { clear: 'Clear search' },
 	filter: { remove: 'Remove filter' },
 	grid: { label: 'Grid' },
-	uploadProgress: { label: 'Upload progress', clear: 'Clear all', cancel: 'Cancel', retry: 'Retry', remove: 'Remove' },
+	uploadProgress: {
+		label: 'Upload progress',
+		clear: 'Clear all',
+		cancel: 'Cancel',
+		retry: 'Retry',
+		remove: 'Remove'
+	},
 	floatingNav: { label: 'Page navigation', pin: 'Pin navigation', unpin: 'Unpin navigation' },
 	mode: { system: 'System', light: 'Light', dark: 'Dark' }
 }
@@ -51,7 +68,12 @@ class MessagesStore {
 	set(custom) {
 		const merged = { ...defaultMessages }
 		for (const key of Object.keys(custom)) {
-			if (typeof custom[key] === 'object' && custom[key] !== null && typeof merged[key] === 'object' && merged[key] !== null) {
+			if (
+				typeof custom[key] === 'object' &&
+				custom[key] !== null &&
+				typeof merged[key] === 'object' &&
+				merged[key] !== null
+			) {
 				merged[key] = { ...merged[key], ...custom[key] }
 			} else {
 				merged[key] = custom[key]

package/src/proxy-item.svelte.js

@@ -100,14 +100,13 @@ export class ProxyItem {
 		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
-				)
+		return raw.map((child, i) =>
+			this._createChild(
+				child,
+				this.#fields,
+				this.#key ? `${this.#key}-${i}` : String(i),
+				this.#level + 1
+			)
 		)
 	}
 
@@ -292,8 +291,12 @@ export class LazyProxyItem extends ProxyItem {
 		this.#loaded = lazyLoad === null || this.get('children') !== true
 	}
 
-	get loaded() { return this.#loaded }
-	get loading() { return this.#loading }
+	get loaded() {
+		return this.#loaded
+	}
+	get loading() {
+		return this.#loading
+	}
 
 	/**
 	 * Fetch children via the lazyLoad function.
@@ -317,4 +320,3 @@ export class LazyProxyItem extends ProxyItem {
 		return new LazyProxyItem(raw, fields, key, level, this.#lazyLoad)
 	}
 }
-

package/src/proxy-tree.svelte.js

@@ -21,7 +21,13 @@ import { ProxyItem } from './proxy-item.svelte.js'
 
 // 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' }
+const NEXT_LINE = {
+	child: 'sibling',
+	last: 'empty',
+	sibling: 'sibling',
+	empty: 'empty',
+	icon: 'empty'
+}
 
 // ─── Reactive tree traversal utilities ─────────────────────────────────────────
 
@@ -115,17 +121,24 @@ export class ProxyTree {
 	 */
 	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))
+		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 }
+	get roots() {
+		return this.#rootProxies
+	}
 
 	/** @returns {Map<string, ProxyItem>} Lookup map of all proxies by key */
-	get lookup() { return this.#lookup }
+	get lookup() {
+		return this.#lookup
+	}
 
 	// ─── Mutation methods ────────────────────────────────────────────────────
 
@@ -137,9 +150,7 @@ export class ProxyTree {
 	 */
 	append(items) {
 		const start = this.#rootProxies.length
-		const newProxies = items.map((raw, i) =>
-			this.#factory(raw, this.#fields, String(start + i), 1)
-		)
+		const newProxies = items.map((raw, i) => this.#factory(raw, this.#fields, String(start + i), 1))
 		this.#rootProxies = [...this.#rootProxies, ...newProxies]
 	}
 

package/src/table-controller.svelte.js

@@ -68,7 +68,8 @@ export class TableController {
 			}
 		} else {
 			// Single column sort: replace entire sort state
-			this.sortState = nextDirection === 'none' ? [] : [{ column: columnName, direction: nextDirection }]
+			this.sortState =
+				nextDirection === 'none' ? [] : [{ column: columnName, direction: nextDirection }]
 		}
 
 		// Update column sorted flags

package/src/wrapper.svelte.js

@@ -29,9 +29,7 @@ export class Wrapper {
 	// 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
-		)
+		this.flatView.filter((n) => n.type !== 'separator' && n.type !== 'spacer' && !n.proxy.disabled)
 	)
 
 	// ─── State ──────────────────────────────────────────────────────────────────
@@ -56,7 +54,9 @@ export class Wrapper {
 
 	// ─── IWrapper: state read by Navigator ─────────────────────────────────────
 
-	get focusedKey() { return this.#focusedKey }
+	get focusedKey() {
+		return this.#focusedKey
+	}
 
 	// ─── IWrapper: movement (path passed through but ignored) ──────────────────
 
@@ -211,9 +211,7 @@ export class Wrapper {
 		const nav = this.#navigable
 		if (!nav.length) return null
 		const q = query.toLowerCase()
-		const startIdx = startAfterKey
-			? nav.findIndex((n) => n.key === startAfterKey) + 1
-			: 0
+		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
@@ -224,8 +222,12 @@ export class Wrapper {
 	// ─── Helpers for the component ─────────────────────────────────────────────
 
 	/** @returns {Map<string, import('./proxy-item.svelte.js').ProxyItem>} */
-	get lookup() { return this.#proxyTree.lookup }
+	get lookup() {
+		return this.#proxyTree.lookup
+	}
 
 	/** @returns {import('./proxy-tree.svelte.js').ProxyTree} */
-	get proxyTree() { return this.#proxyTree }
+	get proxyTree() {
+		return this.#proxyTree
+	}
 }