@rokkit/ui 1.7.0 → 1.8.1

package/dist/components/CodeGroup.svelte

@@ -168,7 +168,7 @@
 		<aside
 			id="codegroup-drawer"
 			class="rail"
-			data-open={drawerOpen ? '' : undefined}
+			data-open={drawerOpen || undefined}
 			aria-label="Files"
 		>
 			<div class="rail-header">Files</div>

package/dist/components/List.svelte

@@ -25,6 +25,8 @@
 	 *   data-list-group        — theme hook for group headers
 	 *   data-list-group-icon   — icon span inside group headers
 	 *   data-active            — highlights current value match
+	 *   data-selected          — "true" on every row in the selection, multiselect only
+	 *   data-multiselect       — "true" on the root when multiselect (base CSS: no text selection)
 	 *   data-disabled          — disabled state
 	 */
 	import type { ProxyItem } from '@rokkit/states'
@@ -38,12 +40,15 @@
 		items = [],
 		fields = {},
 		value = $bindable(),
+		multiselect = false,
+		values = $bindable([]),
 		size = 'md',
 		disabled = false,
 		collapsible = false,
 		label = messages.list.label,
 		icons: userIcons = {} as ListStateIcons,
 		onselect,
+		onchange,
 		class: className = '',
 		itemContent,
 		groupContent,
@@ -92,11 +97,29 @@
 		onselect?.(next, proxy)
 	}
 
+	/**
+	 * The outbound half of `values` (multiselect). The wrapper reports the set only when it
+	 * actually changed, so this writes and notifies once per real change. As with `value`,
+	 * the write lands before the callback, so a consumer reading the bound set inside
+	 * `onchange` sees the new one.
+	 */
+	function handleSelectionChange(next: unknown[]) {
+		values = next
+		onchange?.(next)
+	}
+
 	// Single source of truth.
 	// Navigator calls wrapper[action](path) → focusedKey / proxy.expanded updates →
 	// flatView $derived re-computes → Svelte re-renders the changed nodes.
 	const proxyTree = $derived(new ProxyTree(items, fields))
-	const wrapper = $derived(new Wrapper(proxyTree, { onselect: handleSelect, collapsible }))
+	const wrapper = $derived(
+		new Wrapper(proxyTree, {
+			onselect: handleSelect,
+			onselectionchange: handleSelectionChange,
+			collapsible,
+			multiselect
+		})
+	)
 
 	let listRef = $state<HTMLElement | null>(null)
 
@@ -150,6 +173,12 @@
 	$effect(() => {
 		wrapper.moveToValue(value)
 	})
+
+	// The inbound half of `values`. moveToValues does not report back, so an outbound change
+	// re-syncs to the set it already holds and settles.
+	$effect(() => {
+		if (multiselect) wrapper.moveToValues(values)
+	})
 </script>
 
 {#snippet collapsibleIcon(proxy: ProxyItem)}
@@ -168,12 +197,14 @@
 	data-size={size}
 	data-disabled={disabled || undefined}
 	data-collapsible={collapsible || undefined}
+	data-multiselect={multiselect || undefined}
 	class={className || undefined}
 	aria-label={label}
 >
 	{#each wrapper.flatView as node (node.key)}
 		{@const proxy = node.proxy}
 		{@const isActive = proxy.value === value}
+		{@const isSelected = multiselect && wrapper.selectedKeys.has(node.key)}
 		{@const content = resolveSnippet(
 			snippetBag,
 			proxy,
@@ -245,6 +276,8 @@
 				data-path={node.key}
 				data-level={node.level}
 				data-active={isActive || undefined}
+				data-selected={isSelected || undefined}
+				aria-pressed={multiselect ? isSelected : undefined}
 				data-disabled={proxy.disabled || undefined}
 				disabled={proxy.disabled || disabled}
 			>

package/dist/components/List.svelte.d.ts

@@ -1,4 +1,4 @@
 import type { ListProps } from '../types/list.js';
-declare const List: import("svelte").Component<ListProps, {}, "value">;
+declare const List: import("svelte").Component<ListProps, {}, "values" | "value">;
 type List = ReturnType<typeof List>;
 export default List;

package/dist/components/MultiSelect.svelte

@@ -26,10 +26,10 @@
 	 */
 	import type { ProxyItem } from '@rokkit/states'
 	import { Wrapper, ProxyTree, messages } from '@rokkit/states'
-	import { SvelteSet } from 'svelte/reactivity'
-	import { Navigator, Trigger } from '@rokkit/actions'
+	import { Navigator, Trigger, focusItem } from '@rokkit/actions'
 	import { DEFAULT_STATE_ICONS, resolveSnippet, ITEM_SNIPPET, GROUP_SNIPPET } from '@rokkit/core'
 	import ItemContent from './ItemContent.svelte'
+	import { groupsAsLabels, groupDividerKeys } from '../utils/dropdown.js'
 	import type { MultiSelectProps, SelectStateIcons } from '../types/select.js'
 
 	let {
@@ -74,17 +74,8 @@
 
 	const childrenField = $derived(fields?.children || 'children')
 
-	// Force groups expanded + disabled (non-navigable labels)
-	const processedItems = $derived(
-		items.map((item) => {
-			const asRecord = item as Record<string, unknown>
-			const children = asRecord[childrenField]
-			if (Array.isArray(children) && children.length > 0) {
-				return { ...asRecord, expanded: true, disabled: true }
-			}
-			return item
-		})
-	)
+	// Groups render as non-navigable labels
+	const processedItems = $derived(groupsAsLabels(items, childrenField))
 
 	// ─── Wrapper ──────────────────────────────────────────────────────────────
 
@@ -194,32 +185,19 @@
 		return () => nav.destroy()
 	})
 
-	// DOM focus sync
+	// DOM focus sync. focusItem, not focus() + scrollIntoView(): those scroll every scrollable
+	// ancestor, so arrowing through a MultiSelect inside a scrolling panel moved the page.
 	$effect(() => {
 		const key = wrapper.focusedKey
 		if (!isOpen || !dropdownRef || !key) return
 		requestAnimationFrame(() => {
-			const target = dropdownRef?.querySelector(`[data-path="${key}"]`) as HTMLElement | null
-			if (target && target !== document.activeElement) {
-				target.focus()
-				target.scrollIntoView?.({ block: 'nearest' })
-			}
+			if (dropdownRef) focusItem(dropdownRef, key)
 		})
 	})
 
 	// ─── Helpers ──────────────────────────────────────────────────────────────
 
-	const groupDividers = $derived.by(() => {
-		const set = new SvelteSet<string>()
-		let foundFirst = false
-		for (const node of wrapper.flatView) {
-			if (node.hasChildren) {
-				if (foundFirst) set.add(node.key)
-				foundFirst = true
-			}
-		}
-		return set
-	})
+	const groupDividers = $derived(groupDividerKeys(wrapper.flatView))
 </script>
 
 {#snippet defaultOptionContent(proxy: ProxyItem)}

package/dist/components/Select.svelte

@@ -39,10 +39,16 @@
 	 */
 	import type { ProxyItem } from '@rokkit/states'
 	import { Wrapper, ProxyTree, messages } from '@rokkit/states'
-	import { SvelteSet } from 'svelte/reactivity'
-	import { Navigator, Trigger } from '@rokkit/actions'
+	import { Navigator, Trigger, focusItem } from '@rokkit/actions'
 	import { DEFAULT_STATE_ICONS, resolveSnippet, ITEM_SNIPPET, GROUP_SNIPPET } from '@rokkit/core'
 	import ItemContent from './ItemContent.svelte'
+	import {
+		filterItems,
+		groupsAsLabels,
+		groupDividerKeys,
+		valueKey,
+		dropdownPlacement
+	} from '../utils/dropdown.js'
 	import type { SelectProps, SelectStateIcons } from '../types/select.js'
 
 	let {
@@ -92,46 +98,13 @@
 	const textField = $derived(fields?.label || 'label')
 	const childrenField = $derived(fields?.children || 'children')
 
-	function childMatchesQuery(child: unknown, query: string): boolean {
-		return String((child as Record<string, unknown>)[textField] ?? '')
-			.toLowerCase()
-			.includes(query)
-	}
-
-	function filterGroupChildren(asRecord: Record<string, unknown>, query: string): unknown | null {
-		const children = asRecord[childrenField] as unknown[]
-		const matching = children.filter((child: unknown) => childMatchesQuery(child, query))
-		return matching.length > 0 ? { ...asRecord, [childrenField]: matching } : null
-	}
-
-	function filterItem(item: unknown, query: string): unknown | null {
-		const asRecord = item as Record<string, unknown>
-		const children = asRecord[childrenField]
-		if (Array.isArray(children) && children.length > 0) {
-			return filterGroupChildren(asRecord, query)
-		}
-		const text = String(asRecord[textField] ?? '').toLowerCase()
-		return text.includes(query) ? item : null
-	}
-
-	const filteredItems = $derived.by(() => {
-		if (!filterable || !filterQuery) return items
-		const query = filterQuery.toLowerCase()
-		return items.map((item) => filterItem(item, query)).filter(Boolean)
-	})
-
-	// Pre-process: force groups expanded + disabled (non-navigable labels)
-	const processedItems = $derived(
-		filteredItems.map((item) => {
-			const asRecord = item as Record<string, unknown>
-			const children = asRecord[childrenField]
-			if (Array.isArray(children) && children.length > 0) {
-				return { ...asRecord, expanded: true, disabled: true }
-			}
-			return item
-		})
+	const filteredItems = $derived(
+		filterable && filterQuery ? filterItems(items, filterQuery, { textField, childrenField }) : items
 	)
 
+	// Groups render as non-navigable labels
+	const processedItems = $derived(groupsAsLabels(filteredItems, childrenField))
+
 	// ─── Wrapper ──────────────────────────────────────────────────────────────
 
 	function handleSelect(extractedValue: unknown, proxy: ProxyItem) {
@@ -194,31 +167,12 @@
 
 	// ─── Trigger action ───────────────────────────────────────────────────────
 
-	/** Bring `el` into view inside the dropdown only — never scroll an ancestor. */
-	function scrollIntoDropdown(el: HTMLElement) {
-		if (!dropdownRef) return
-		const top = el.offsetTop
-		const bottom = top + el.offsetHeight
-		if (top < dropdownRef.scrollTop) {
-			dropdownRef.scrollTop = top
-		} else if (bottom > dropdownRef.scrollTop + dropdownRef.clientHeight) {
-			dropdownRef.scrollTop = bottom - dropdownRef.clientHeight
-		}
-	}
-
 	/**
-	 * Move DOM focus to the wrapper's focused item so subsequent keydown events
-	 * fire inside the dropdown, where Navigator is listening. preventScroll plus
-	 * the dropdown-only scroll above keeps ancestor containers still.
+	 * Move DOM focus to the wrapper's focused item so subsequent keydown events fire inside the
+	 * dropdown, where Navigator is listening — without scrolling any ancestor (focusItem).
 	 */
 	function focusFocusedItem() {
-		if (!dropdownRef) return
-		const key = wrapper.focusedKey
-		if (!key) return
-		const el = dropdownRef.querySelector(`[data-path="${key}"]`) as HTMLElement | null
-		if (!el) return
-		el.focus({ preventScroll: true })
-		scrollIntoDropdown(el)
+		if (dropdownRef) focusItem(dropdownRef, wrapper.focusedKey)
 	}
 
 	/** Where focus lands once the dropdown is open: the filter box, or the current item. */
@@ -248,19 +202,10 @@
 		return () => t.destroy()
 	})
 
-	function moveToSelectedValue(): boolean {
-		for (const node of wrapper.flatView) {
-			if (!node.proxy.disabled && node.proxy.value === value) {
-				wrapper.moveTo(node.key)
-				return true
-			}
-		}
-		return false
-	}
-
 	function focusSelectedOrFirst() {
-		if (value !== undefined && value !== null && moveToSelectedValue()) return
-		wrapper.first(null)
+		const key = valueKey(wrapper.flatView, value)
+		if (key) wrapper.moveTo(key)
+		else wrapper.first(null)
 	}
 
 	// ─── Navigator on dropdown ────────────────────────────────────────────────
@@ -298,24 +243,12 @@
 	// away from the trigger.
 	function positionDropdown() {
 		if (!dropdownRef || !triggerRef) return
-		const r = triggerRef.getBoundingClientRect()
-		const gap = 4
-		dropdownRef.style.position = 'fixed'
-		dropdownRef.style.minWidth = `${r.width}px`
-		if (direction === 'up') {
-			dropdownRef.style.top = 'auto'
-			dropdownRef.style.bottom = `${window.innerHeight - r.top + gap}px`
-		} else {
-			dropdownRef.style.top = `${r.bottom + gap}px`
-			dropdownRef.style.bottom = 'auto'
-		}
-		if (align === 'end') {
-			dropdownRef.style.left = 'auto'
-			dropdownRef.style.right = `${window.innerWidth - r.right}px`
-		} else {
-			dropdownRef.style.left = `${r.left}px`
-			dropdownRef.style.right = 'auto'
-		}
+		const placement = dropdownPlacement(
+			triggerRef.getBoundingClientRect(),
+			{ width: window.innerWidth, height: window.innerHeight },
+			{ direction, align }
+		)
+		Object.assign(dropdownRef.style, placement)
 	}
 
 	$effect(() => {
@@ -339,7 +272,7 @@
 		}
 	})
 
-	// Focus sync is owned by Navigator (#syncFocus). The previous duplicate
+	// Focus sync after a key is owned by Navigator (focusItem). The previous duplicate
 	// $effect here competed with Navigator's own focus + scroll logic and
 	// caused race conditions (page-scroll on arrow nav, layout shift on
 	// reopen). Single source of truth lives in the Navigator class.
@@ -376,17 +309,7 @@
 	// ─── Helpers ──────────────────────────────────────────────────────────────
 
 	/** Set of group keys that need a divider before them (not the first group) */
-	const groupDividers = $derived.by(() => {
-		const set = new SvelteSet<string>()
-		let foundFirst = false
-		for (const node of wrapper.flatView) {
-			if (node.hasChildren) {
-				if (foundFirst) set.add(node.key)
-				foundFirst = true
-			}
-		}
-		return set
-	})
+	const groupDividers = $derived(groupDividerKeys(wrapper.flatView))
 </script>
 
 {#snippet defaultOptionContent(proxy: ProxyItem)}

package/dist/types/list.d.ts

@@ -62,6 +62,13 @@ export interface ListProps extends ItemSnippets {
     fields?: Record<string, string>;
     /** Selected value (bindable) — matched against each item's value field */
     value?: unknown;
+    /**
+     * Let the reader select several rows: a click selects one, ctrl/⌘-click toggles,
+     * shift-click extends a range. Off by default.
+     */
+    multiselect?: boolean;
+    /** The selected values when `multiselect` (bindable) — matched by identity */
+    values?: unknown[];
     /** Size variant */
     size?: string;
     /** Whether the entire list is disabled */
@@ -74,6 +81,8 @@ export interface ListProps extends ItemSnippets {
     icons?: ListStateIcons;
     /** Called when an item is selected, with the item's `ProxyItem` */
     onselect?: (value: unknown, proxy: ProxyItem) => void;
+    /** Called with the new set whenever a multiselect selection changes */
+    onchange?: (values: unknown[]) => void;
     /** Additional CSS classes */
     class?: string;
 }

package/dist/utils/dropdown.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The pure parts of a list dropdown (Select, MultiSelect): filtering, groups as labels, the
+ * dividers between groups, finding a value's node, and fixed-position placement.
+ */
+export type ItemFields = {
+    textField: string;
+    childrenField: string;
+};
+/** A node of a Wrapper's flat view — only the members these helpers read. */
+export type FlatNode = {
+    key: string;
+    hasChildren?: boolean;
+    proxy?: {
+        value: unknown;
+        disabled?: boolean;
+    };
+};
+/**
+ * The items a filter query keeps. A leaf stays when its text contains the query
+ * (case-insensitive); a group stays with only its matching children, and goes when none match.
+ * A group is an item with a non-empty children array.
+ */
+export declare function filterItems(items: unknown[], query: string, { textField, childrenField }: ItemFields): unknown[];
+/**
+ * Groups rendered as labels: always expanded (children always shown) and disabled, so the
+ * Navigator skips them. Leaves pass through untouched.
+ */
+export declare function groupsAsLabels(items: unknown[], childrenField: string): unknown[];
+/** The group keys that get a divider before them — every group after the first. */
+export declare function groupDividerKeys(flatView: FlatNode[]): Set<string>;
+/** The key of the first enabled node holding `value`, or null (also for a null/undefined value). */
+export declare function valueKey(flatView: FlatNode[], value: unknown): string | null;
+export type Placement = {
+    position: 'fixed';
+    minWidth: string;
+    top: string;
+    bottom: string;
+    left: string;
+    right: string;
+};
+/**
+ * Where a `position: fixed` dropdown sits against its trigger: `gap` px below it (or above for
+ * `direction: 'up'`), its start edge on the trigger's (or its end edge for `align: 'end'`), and
+ * at least as wide as the trigger. Fixed, so it escapes an ancestor's `overflow` clipping.
+ */
+export declare function dropdownPlacement(trigger: {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+    width: number;
+}, viewport: {
+    width: number;
+    height: number;
+}, { direction, align, gap }: {
+    direction: string;
+    align: string;
+    gap?: number;
+}): Placement;

package/dist/utils/dropdown.js

@@ -0,0 +1,64 @@
+/**
+ * The pure parts of a list dropdown (Select, MultiSelect): filtering, groups as labels, the
+ * dividers between groups, finding a value's node, and fixed-position placement.
+ */
+const childrenOf = (item, childrenField) => {
+    const children = item[childrenField];
+    return Array.isArray(children) && children.length > 0 ? children : null;
+};
+const textMatches = (item, textField, query) => String(item[textField] ?? '')
+    .toLowerCase()
+    .includes(query);
+/**
+ * The items a filter query keeps. A leaf stays when its text contains the query
+ * (case-insensitive); a group stays with only its matching children, and goes when none match.
+ * A group is an item with a non-empty children array.
+ */
+export function filterItems(items, query, { textField, childrenField }) {
+    const q = query.toLowerCase();
+    return items
+        .map((item) => {
+        const children = childrenOf(item, childrenField);
+        if (!children)
+            return textMatches(item, textField, q) ? item : null;
+        const matching = children.filter((child) => textMatches(child, textField, q));
+        return matching.length > 0 ? { ...item, [childrenField]: matching } : null;
+    })
+        .filter(Boolean);
+}
+/**
+ * Groups rendered as labels: always expanded (children always shown) and disabled, so the
+ * Navigator skips them. Leaves pass through untouched.
+ */
+export function groupsAsLabels(items, childrenField) {
+    return items.map((item) => childrenOf(item, childrenField) ? { ...item, expanded: true, disabled: true } : item);
+}
+/** The group keys that get a divider before them — every group after the first. */
+export function groupDividerKeys(flatView) {
+    const groups = flatView.filter((node) => node.hasChildren).map((node) => node.key);
+    return new Set(groups.slice(1));
+}
+/** The key of the first enabled node holding `value`, or null (also for a null/undefined value). */
+export function valueKey(flatView, value) {
+    if (value === undefined || value === null)
+        return null;
+    const node = flatView.find((n) => !n.proxy?.disabled && n.proxy?.value === value);
+    return node ? node.key : null;
+}
+/**
+ * Where a `position: fixed` dropdown sits against its trigger: `gap` px below it (or above for
+ * `direction: 'up'`), its start edge on the trigger's (or its end edge for `align: 'end'`), and
+ * at least as wide as the trigger. Fixed, so it escapes an ancestor's `overflow` clipping.
+ */
+export function dropdownPlacement(trigger, viewport, { direction, align, gap = 4 }) {
+    const up = direction === 'up';
+    const end = align === 'end';
+    return {
+        position: 'fixed',
+        minWidth: `${trigger.width}px`,
+        top: up ? 'auto' : `${trigger.bottom + gap}px`,
+        bottom: up ? `${viewport.height - trigger.top + gap}px` : 'auto',
+        left: end ? 'auto' : `${trigger.left}px`,
+        right: end ? `${viewport.width - trigger.right}px` : 'auto'
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/ui",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "Data driven UI components for Rokkit applications",
   "repository": {
     "type": "git",
@@ -45,15 +45,15 @@
     "dropdown"
   ],
   "dependencies": {
-    "@rokkit/core": "1.7.0",
-    "@rokkit/data": "1.7.0",
-    "@rokkit/states": "1.7.0",
-    "@rokkit/actions": "1.7.0",
+    "@rokkit/core": "1.8.0",
+    "@rokkit/data": "1.8.0",
+    "@rokkit/states": "1.8.0",
+    "@rokkit/actions": "1.8.0",
     "marked": "^15.0.0",
-    "dompurify": "^3.4.13"
+    "dompurify": "^3.4.16"
   },
   "peerDependencies": {
-    "shiki": "^3.23.0",
+    "shiki": "^3.23.0 || ^4",
     "svelte": "^5.0.0"
   },
   "devDependencies": {