@torpor/ui 0.4.0 → 1.0.0

package/dist/ListBox/ListBox.torp

@@ -1,7 +1,19 @@
-import type { ClassValue, StyleValue } from "@torpor/view";
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import $handle from "../utils/$handle";
+import {
+	type FieldContext,
+	FieldContextName,
+	type FormContext,
+	FormContextName,
+} from "../Form/FormTypes";
+import FormValues from "../Form/FormValues.torp";
+import { type LoadResult, type Loader, createItemLoader } from "../utils/loader";
+import { createItemGroup } from "../utils/createItemGroup";
 import getId from "../utils/getId";
-import { PopoutContextName, type PopoutContext, type HandleButtonPress } from "../utils/PopoutTypes";
-import { ListBoxContextName, type ListBoxContext, type ItemState } from "./ListBoxTypes";
+import createFormField from "../utils/formField";
+import { type HandleButtonPress, type PopoutContext, PopoutContextName } from "../utils/PopoutTypes";
+import LoadedListBoxItems from "./LoadedListBoxItems.torp";
+import { type ItemState, type ListBoxContext, ListBoxContextName } from "./ListBoxTypes";
 
 // TODO: orientation
 
@@ -9,19 +21,39 @@ interface ListBoxProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
+	style?: StyleValue;
 	/** Whether a single ListBoxItem or multiple ListBoxItems can be selected at the same time */
-	type?: "single" | "multiple",
+	type?: "single" | "multiple";
 	/** The value of the selected ListBoxItem, or an array of values if the type is "multiple" */
-	value?: any | any[],
+	value: Bindable<any | any[]>;
 	/** If set to true, the user cannot interact with any items in the ListBox */
-	disabled?: boolean,
+	disabled?: boolean;
 	/** An ARIA label for describing the ListBox to screen readers  */
-	ariaLabel?: string | undefined,
+	ariaLabel?: string | undefined;
+	/** An ID of an element that labels the ListBox */
+	ariaLabelledBy?: string | undefined;
+	/** The orientation of the ListBox */
+	orientation?: "vertical" | "horizontal";
 	/** Raised when the selected item(s) have changed */
-	onchange?: (value: any | any[]) => void,
+	/** The name of the component's form data field */
+	name?: string;
+	/**
+	 * Reads options from the network (or anywhere async), receiving
+	 * `{ searchText }` whenever the bound `searchText` changes. When set and
+	 * no ListBoxItems are slotted in, the options are rendered automatically
+	 */
+	load?: Loader;
+	/** Called after each successful load with the normalized result */
+	onload?: (result: LoadResult) => void;
+	/** Extracts the display text for a loaded item (defaults to `label ?? text ?? item`) */
+	getItemLabel?: (item: any) => any;
+	/** Extracts the value for a loaded item (defaults to `value ?? id`) */
+	getItemValue?: (item: any) => any;
+	/** Filter text for a `load` function; two-way bindable */
+	searchText?: Bindable<string | undefined>;
+	onchange?: (value: any | any[]) => void;
 }
 
 /**
@@ -40,28 +72,44 @@ interface ListBoxProps {
  */
 export default function ListBox($props: ListBoxProps | undefined) {
 	let defaultId = getId();
-	let type = $props?.type ?? "single";
+	let root: HTMLElement;
 
-	let $state = $watch({
-		value: $props?.value ?? (type === "single" ? undefined : [])
-	});
+	// Wire up the enclosing Form and Field, if any
+	const form = createFormField(
+		$props?.name,
+		$context[FormContextName] as FormContext | undefined,
+		$context[FieldContextName] as FieldContext | undefined,
+	);
 
-	// Update $state on $props change
-	$run(() => {
-		$state.value = $props?.value ?? (type === "single" ? undefined : [])
-	});
+	// Get the current selection type, re-reading $props so changes are picked up
+	function getType(): "single" | "multiple" {
+		return $props?.type ?? "single";
+	}
 
-	// Update $props on $state change
-	$run(() => {
-		if ($props !== undefined) {
-			$props.value = $state.value;
-		}
+	// This may come from a PopoutContext, or we may need to handle it ourselves
+	let searchText: string | undefined;
+
+	let $state = $watch({
+		value: $props?.value ?? (getType() === "single" ? undefined : []),
+		searchText: undefined as string | undefined,
 	});
 
-	let itemStates: ItemState[] = [];
+	$bind($state, $props, "value", "searchText");
 
-	// This is used to assign automatic indexes to items where needed
-	let nextIndex = 0;
+	if ($props?.load !== undefined && typeof $props.load !== "function") {
+		throw new Error("ListBox: `load` must be a function");
+	}
+	const hasLoader = typeof $props?.load === "function";
+
+	// Load options whenever the search text changes; pass the loaded items
+	// and getters through the context for the slot fallback to render
+	const $load = hasLoader
+		? createItemLoader({
+				load: $props!.load!,
+				getRequest: () => ({ searchText: $state.searchText }),
+				onload: (r) => $props?.onload?.(r),
+			})
+		: undefined;
 
 	// Maybe get stuff out of a popout context
 	let handleButton: HandleButtonPress | undefined = undefined;
@@ -74,185 +122,204 @@ export default function ListBox($props: ListBoxProps | undefined) {
 		// called after everything has been shown
 		popoutContext.focusFirstElement = focusFirstElement;
 		popoutContext.focusLastElement = focusLastElement;
+		popoutContext.markElement = markElement;
+		popoutContext.selectMarkedElement = selectMarkedElement;
+		popoutContext.searchItems = searchItems;
 
-		// Set the content ID so that it can be used with aria-controls in AccordionTrigger
+		// Set the content ID and role so that triggers can use them with
+		// aria-controls / aria-haspopup
 		popoutContext.state.contentId = $props?.id ?? defaultId;
+		popoutContext.state.contentRole = "listbox";
 	}
 
+	const group = createItemGroup<ItemState>({
+		state: $state,
+		type: getType,
+		selectedProperty: "selected",
+		disabled: () => $props?.disabled,
+		onToggle: () => {
+			// Clear the keyboard focus marker
+			for (let item of group.itemStates) {
+				item.active = false;
+			}
+			form.handleInput();
+			// Pass this along to the containing popout if applicable
+			if (handleButton) {
+				if (getType() === "single") {
+					handleButton("confirm", $state.value);
+				} else {
+					handleButton(undefined, $state.value);
+				}
+			}
+		},
+	});
+
 	// Set the context to pass down to items, with functions for each item to call
 	let context: ListBoxContext = {
-		registerItem,
-		removeItem,
-		toggleItem,
+		get type() {
+			return getType();
+		},
+		state: $state,
+		registerItem: group.registerItem,
+		removeItem: group.removeItem,
+		toggleItem: group.toggleItem,
 		handleKey,
+		setActiveDescendant: popoutContext ? (id) => { popoutContext.state.activeDescendant = id; } : undefined,
+		getLoadedItems: $load ? () => $load.items : undefined,
+		getItemLabel: $props?.getItemLabel,
+		getItemValue: $props?.getItemValue,
 	};
 	$context[ListBoxContextName] = context;
 
+	// Dispatch the change event when the value changes
+	$handle((first) => {
+		const value = $state.value;
+		if (!first) $props?.onchange?.(value);
+	});
+
 	function focusFirstElement() {
-		if (itemStates.length > 0) {
-			itemStates[0].setFocused();
+		if (group.itemStates.length > 0) {
+			group.itemStates[0].setFocused();
 		}
 	}
 
 	function focusLastElement() {
-		if (itemStates.length > 0) {
-			itemStates.at(-1)!.setFocused();
+		if (group.itemStates.length > 0) {
+			group.itemStates.at(-1)!.setFocused();
 		}
 	}
 
-	$run(() => {
-		// Get the value to ensure that this effect will be subscribed
-		let value = $state.value;
-
-		// And set the expanded item(s)
-		switch (type) {
-			case "single": {
-				for (let item of itemStates) {
-					item.selected = item.value === value;
-				}
-				break;
-			}
-			case "multiple": {
-				if (!Array.isArray(value)) {
-					value = [value];
-				}
-				for (let item of itemStates) {
-					item.selected = value.indexOf(item.value) !== -1;
-				}
-				break;
-			}
-		}
-	})
-
-	$run(() => {
-		let disabled = $props?.disabled;
-		itemStates.forEach((s) => s.parentDisabled = disabled === true);
-	});
-
-	// Dispatch the change event when the value changes
-	let firstChange = true;
-	$run(() => {
-		const onchange = $props?.onchange;
-		const value = $state.value;
-		if (firstChange) {
-			firstChange = false;
-		} else if (onchange) {
-			onchange(value);
-		}
-	});
-
-	function registerItem(itemState: ItemState) {
-		// If an index wasn't set for the item, set it automatically
-		if (itemState.index === -1) {
-			itemState.index = nextIndex++;
-		}
+	function markElement(id: string) {
+		// selected stays derived from the group value; active marks the
+		// keyboard-focus preview
+		group.itemStates.forEach((i) => {
+			i.active = i.id === id;
+		});
+	}
 
-		// If a value wasn't set for the item, set it to the index
-		if (!itemState.value) {
-			itemState.value = itemState.index;
+	function selectMarkedElement() {
+		const marked = group.itemStates.find((i) => i.active === true);
+		if (marked && handleButton) {
+			handleButton("confirm", marked.value);
 		}
+	}
 
-		// If we have a value, set whether the item should be selected
-		if ($state.value !== undefined && $state.value !== null) {
-			switch (type) {
-				case "single": {
-					itemState.selected = $state.value === itemState.value;
-					break;
-				}
-				case "multiple": {
-					itemState.selected = $state.value.includes(itemState.value);
-					break;
-				}
+	function searchItems(searchText: string) {
+		const normalizedSearchText = searchText.toLocaleLowerCase();
+		for (let item of group.itemStates) {
+			if (item.text.toLocaleLowerCase().includes(normalizedSearchText)) {
+				return item;
 			}
 		}
-
-		// Set whether the ListBox itself is disabled
-		itemState.parentDisabled = $props?.disabled === true
-
-		// Add the item's state to the array
-		itemStates.splice(itemState.index, 0, itemState);
 	}
 
-	// TODO: I think this should be done by value
-	function removeItem(itemIndex: number) {
-		// Remove the item and re-index
-		let index = itemStates.findIndex((item) => item.index === itemIndex);
-		if (index !== -1) {
-			itemStates.splice(itemIndex, 1);
-		}
-		itemStates.forEach((item, i) => (item.index = i));
+	function focusSelectedElement() {
+		// Called when the list box receives focus: focus the selected option,
+		// or the first option if none is selected
+		const itemStates = group.itemStates;
+		const target = itemStates.find((i) => i.selected) ?? itemStates[0];
+		target?.setFocused();
 	}
 
-	function toggleItem(value: string) {
-		switch (type) {
-			case "single": {
-				for (let item of itemStates) {
-					if (item.value === value) {
-						$state.value = item.selected ? "" : item.value;
-						break;
-					}
-				}
-				// Pass this along to the containing popout if applicable, so
-				// that the popout can be closed
-				if (handleButton) {
-					handleButton("confirm", value)
-				}
-				break;
+	function handleKey(index: number, e: KeyboardEvent) {
+		const itemStates = group.itemStates;
+		// Finds the nearest focusable item, skipping disabled ones
+		const findFocusable = (from: number, step: number): number => {
+			let i = from;
+			while (i >= 0 && i < itemStates.length && itemStates[i].disabled) {
+				i += step;
 			}
-			case "multiple": {
-				let newValue = [];
-				for (let item of itemStates) {
-					if (
-						(item.value === value && !item.selected) ||
-						(item.value !== value && item.selected)
-					) {
-						newValue.push(item.value);
-					}
-				}
-				$state.value = newValue.sort();
-				break;
+			return i;
+		};
+		const clearSearch = () => {
+			if (popoutContext) {
+				popoutContext.searchText = undefined;
+			} else {
+				searchText = undefined;
 			}
-		}
-	}
-
-	function handleKey(index: number, e: KeyboardEvent) {
+		};
 		switch (e.key) {
-			case "Up":
 			case "ArrowUp": {
-				if (index > 0) {
+				const target = findFocusable(index - 1, -1);
+				if (target >= 0) {
 					e.preventDefault();
-					itemStates[index - 1].setFocused();
+					itemStates[target].setFocused();
+					clearSearch();
 				}
 				break;
 			}
-			case "Down":
 			case "ArrowDown": {
-				if (index < itemStates.length - 1) {
+				const target = findFocusable(index + 1, 1);
+				if (target < itemStates.length) {
 					e.preventDefault();
-					itemStates[index + 1].setFocused();
+					itemStates[target].setFocused();
+					clearSearch();
 				}
 				break;
 			}
 			case "Home": {
 				if (index > 0) {
 					e.preventDefault();
-					itemStates[0].setFocused();
+					itemStates[findFocusable(0, 1)].setFocused();
+					clearSearch();
 				}
 				break;
 			}
 			case "End": {
 				if (index < itemStates.length - 1) {
 					e.preventDefault();
-					itemStates[itemStates.length - 1].setFocused();
+					itemStates[findFocusable(itemStates.length - 1, -1)].setFocused();
+					clearSearch();
 				}
 				break;
 			}
 			case "Escape": {
 				if (handleButton) {
-					handleButton("cancel")
+					handleButton("cancel");
+					if (popoutContext) {
+						popoutContext.searchText = undefined;
+					} else {
+						searchText = undefined;
+					}
+				}
+				break;
+			}
+			case "Backspace": {
+				if (popoutContext?.searchText || searchText) {
+					e.preventDefault();
+					const shorten = (str: string) => str.substring(0, str.length - 1);
+					if (popoutContext) {
+						popoutContext.searchText = shorten(popoutContext.searchText!);
+						searchText = popoutContext.searchText;
+					} else {
+						searchText = shorten(searchText!);
+					}
+					if (searchText.length > 0) {
+						const found = searchItems(searchText);
+						if (found) {
+							found.setFocused();
+						}
+					}
 				}
 				break;
 			}
+			default: {
+				// TODO: Handle unicode
+				if (e.key.length === 1) {
+					e.preventDefault();
+					const lengthen = (str: string) => (str ??= "") + e.key;
+					if (popoutContext) {
+						popoutContext.searchText = lengthen(popoutContext.searchText!);
+						searchText = popoutContext.searchText;
+					} else {
+						searchText = lengthen(searchText!);
+					}
+					const found = searchItems(searchText);
+					if (found) {
+						found.setFocused();
+					}
+				}
+			}
 		}
 	}
 
@@ -262,10 +329,46 @@ export default function ListBox($props: ListBoxProps | undefined) {
 			class={["torp-list-box", $props?.class]}
 			{$props?.style}
 			role="listbox"
+			tabindex="0"
+			onfocus={focusSelectedElement}
 			aria-label={$props?.ariaLabel}
-			aria-multiselectable={type === "multiple" ? "true" : undefined}
+			aria-labelledby={$props?.ariaLabelledBy}
+			aria-multiselectable={getType() === "multiple" ? "true" : undefined}
+			aria-disabled={$props?.disabled ? "true" : undefined}
+			aria-orientation={$props?.orientation}
+			data-valid={form.valid ? "valid" : "invalid"}
+			aria-describedby={form.messageId}
+			aria-invalid={form.inField && !form.valid ? "true" : undefined}
+			onfocusout={(e: FocusEvent) => {
+				// Only validate when focus leaves the whole list box
+				if (!root.contains(e.relatedTarget as Node | null)) {
+					form.handleBlur();
+				}
+			}}
+			&ref={root}
 		>
-			<slot />
+			<slot>
+				@if (context.getLoadedItems) {
+					@// Options loaded from a network loader, rendered automatically
+					@try {
+						@await {
+							<LoadedListBoxItems
+								items={context.getLoadedItems!()}
+								getItemLabel={context.getItemLabel}
+								getItemValue={context.getItemValue}
+							/>
+						} with {
+							<div class="torp-list-box-loading" role="status">Loading…</div>
+						}
+					} catch (err) {
+						<div class="torp-list-box-error" role="alert">
+							{err instanceof Error ? err.message : String(err)}
+						</div>
+					}
+				}
+			</slot>
 		</div>
+
+		<FormValues name={form.name} value={$state.value} />
 	}
 }

package/dist/ListBox/ListBoxItem.torp

@@ -1,35 +1,44 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { ListBoxContextName, type ItemState, type ListBoxContext } from "./ListBoxTypes";
+import $handle from "../utils/$handle";
+import getId from "../utils/getId";
+import { type ItemState, type ListBoxContext, ListBoxContextName } from "./ListBoxTypes";
 
 interface ListBoxItemProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
+	style?: StyleValue;
 	/** The index of this item in the ListBox. Set this if you will be inserting, removing or sorting items. If you don't set this, it will be set automatically */
-	index?: number,
+	index?: number;
+	/** The text for the item. If not set, this will come from it's text content */
+	text?: string;
 	/** A value for the item. Set this if you need more control over which item(s) are selected. If you don't set this, the value will be set to the item's initial index */
-	value?: string,
+	value?: string;
 	/** If set to true, the user cannot interact with this ListBoxItem */
-	disabled?: boolean,
-	/** Raised when this item is opened or closed */
-	ontoggle?: (open: boolean) => void,
+	disabled?: boolean;
+	/** Raised when this item's selected state has changed */
+	onchange?: (selected: boolean) => void;
 }
 
 /**
  * An item in an ListBox.
  */
 export default function ListBoxItem($props: ListBoxItemProps | undefined) {
+	let defaultId = getId();
+
 	let $state: ItemState = $watch({
+		id: $props?.id ?? defaultId,
 		index: -1,
-		value: "",
+		text: $props?.text ?? "",
+		value: $props?.value,
 		selected: false,
+		active: false,
 		disabled: $props?.disabled ?? false,
 		parentDisabled: false,
-		setFocused
-	})
+		setFocused,
+	});
 
 	let button: HTMLButtonElement;
 
@@ -40,25 +49,19 @@ export default function ListBoxItem($props: ListBoxItemProps | undefined) {
 	}
 
 	// Register this item with the parent ListBox, which will handle toggling selected for all items
-	context.registerItem($state, setFocused);
+	context.registerItem($state);
 
 	// Remove the item from the parent ListBox when this item is destroyed
 	$run(() => {
 		return () => {
 			context.removeItem($state.index);
-		}
+		};
 	});
 
-	// Dispatch the toggle event when the value of selected changes
-	let firstToggle = true;
-	$run(() => {
-		const ontoggle = $props?.ontoggle;
+	// Dispatch the change event when the value of selected changes
+	$handle((first) => {
 		const selected = $state.selected;
-		if (firstToggle) {
-			firstToggle = false;
-		} else if (ontoggle) {
-			ontoggle(selected);
-		}
+		if (!first) $props?.onchange?.(selected);
 	});
 
 	// This function is called by the parent ListBox to focus this item's button
@@ -68,37 +71,58 @@ export default function ListBoxItem($props: ListBoxItemProps | undefined) {
 
 	function handleClick() {
 		// Pass the value to the toggleItem method in the parent ListBox which will handle toggling
-		// the value of expanded for all items (e.g. to unselect other items if necessary)
+		// the value of selected for all items (e.g. to unselect other items if necessary)
 		context.toggleItem($state.value);
 	}
 
+	function handleFocus() {
+		if (context.setActiveDescendant) {
+			context.setActiveDescendant($state.id);
+		}
+	}
+
 	function handleKey(e: KeyboardEvent) {
-		// For testing
 		switch (e.key) {
-			case "Enter":
+			case "Enter": {
 				e.preventDefault();
 				context.toggleItem($state.value);
 				break;
-			default:
+			}
+			default: {
 				// Pass the key press up to the parent ListBox which will handle
 				// setting the focused button
 				context.handleKey($state.index, e);
 				break;
+			}
+		}
+	}
+
+	function handleMount(el: HTMLButtonElement) {
+		// If the item has no value, set it to the text content; selected is
+		// derived from the group value, so it picks this up automatically
+		if (!$state.text) {
+			$state.text = el.textContent.trim();
+		}
+		if ($state.value === undefined || $state.value === null) {
+			$state.value = $state.text;
 		}
 	}
 
 	@render {
 		<button
-			{$props?.id}
+			type="button"
+			{$state.id}
 			class={["torp-list-box-item", $props?.class]}
 			{$props?.style}
 			role="option"
+			tabindex="-1"
 			aria-selected={$state.selected ? "true" : "false"}
-			aria-disabled={$state.disabled ? "true" : undefined}
-			data-state={$state.selected ? "active" : undefined}
-			data-disabled={$state.disabled ? "true" : undefined}
+			aria-disabled={$state.disabled || $state.parentDisabled ? "true" : undefined}
+			data-state={$state.selected || $state.active ? "active" : undefined}
 			onclick={handleClick}
 			onkeydown={handleKey}
+			onfocus={handleFocus}
+			onmount={handleMount}
 			&ref={button}
 		>
 			<slot />

package/dist/ListBox/ListBoxSeparator.torp

@@ -4,9 +4,11 @@ interface ListBoxSeparatorProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
+	style?: StyleValue;
+	/** The orientation of the separator */
+	orientation?: "vertical" | "horizontal";
 }
 
 /**
@@ -19,6 +21,7 @@ export default function ListBoxSeparator($props: ListBoxSeparatorProps | undefin
 			class={["torp-list-box-separator", $props?.class]}
 			{$props?.style}
 			role="separator"
+			aria-orientation={$props?.orientation ?? "horizontal"}
 		>
 			<slot />
 		</div>