@torpor/ui 0.3.7 → 1.0.0

package/dist/ListBox/ListBox.torp

@@ -0,0 +1,374 @@
+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 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
+
+interface ListBoxProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** Whether a single ListBoxItem or multiple ListBoxItems can be selected at the same time */
+	type?: "single" | "multiple";
+	/** The value of the selected ListBoxItem, or an array of values if the type is "multiple" */
+	value: Bindable<any | any[]>;
+	/** If set to true, the user cannot interact with any items in the ListBox */
+	disabled?: boolean;
+	/** An ARIA label for describing the ListBox to screen readers  */
+	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 */
+	/** 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;
+}
+
+/**
+ * A list of options that a user can select.
+ *
+ * See [the WAI ARIA guidelines for ListBoxes](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/).
+ *
+ * The structure of an ListBox is:
+ *
+ * ```
+ * <ListBox>
+ * 	<ListBoxItem />
+ * 	<ListBoxSeparator /> (optional)
+ * </ListBox>
+ * ```
+ */
+export default function ListBox($props: ListBoxProps | undefined) {
+	let defaultId = getId();
+	let root: HTMLElement;
+
+	// Wire up the enclosing Form and Field, if any
+	const form = createFormField(
+		$props?.name,
+		$context[FormContextName] as FormContext | undefined,
+		$context[FieldContextName] as FieldContext | undefined,
+	);
+
+	// Get the current selection type, re-reading $props so changes are picked up
+	function getType(): "single" | "multiple" {
+		return $props?.type ?? "single";
+	}
+
+	// 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,
+	});
+
+	$bind($state, $props, "value", "searchText");
+
+	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;
+	const popoutContext = $context[PopoutContextName] as PopoutContext;
+	if (popoutContext) {
+		handleButton = popoutContext.handleButton;
+
+		//popoutContext.handleClickOutside = handleClickOutside;
+		// Set the focusFirstElement method in the PopoutContext so that it can be
+		// 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 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 = {
+		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 (group.itemStates.length > 0) {
+			group.itemStates[0].setFocused();
+		}
+	}
+
+	function focusLastElement() {
+		if (group.itemStates.length > 0) {
+			group.itemStates.at(-1)!.setFocused();
+		}
+	}
+
+	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;
+		});
+	}
+
+	function selectMarkedElement() {
+		const marked = group.itemStates.find((i) => i.active === true);
+		if (marked && handleButton) {
+			handleButton("confirm", marked.value);
+		}
+	}
+
+	function searchItems(searchText: string) {
+		const normalizedSearchText = searchText.toLocaleLowerCase();
+		for (let item of group.itemStates) {
+			if (item.text.toLocaleLowerCase().includes(normalizedSearchText)) {
+				return item;
+			}
+		}
+	}
+
+	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 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;
+			}
+			return i;
+		};
+		const clearSearch = () => {
+			if (popoutContext) {
+				popoutContext.searchText = undefined;
+			} else {
+				searchText = undefined;
+			}
+		};
+		switch (e.key) {
+			case "ArrowUp": {
+				const target = findFocusable(index - 1, -1);
+				if (target >= 0) {
+					e.preventDefault();
+					itemStates[target].setFocused();
+					clearSearch();
+				}
+				break;
+			}
+			case "ArrowDown": {
+				const target = findFocusable(index + 1, 1);
+				if (target < itemStates.length) {
+					e.preventDefault();
+					itemStates[target].setFocused();
+					clearSearch();
+				}
+				break;
+			}
+			case "Home": {
+				if (index > 0) {
+					e.preventDefault();
+					itemStates[findFocusable(0, 1)].setFocused();
+					clearSearch();
+				}
+				break;
+			}
+			case "End": {
+				if (index < itemStates.length - 1) {
+					e.preventDefault();
+					itemStates[findFocusable(itemStates.length - 1, -1)].setFocused();
+					clearSearch();
+				}
+				break;
+			}
+			case "Escape": {
+				if (handleButton) {
+					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();
+					}
+				}
+			}
+		}
+	}
+
+	@render {
+		<div
+			id={$props?.id ?? defaultId}
+			class={["torp-list-box", $props?.class]}
+			{$props?.style}
+			role="listbox"
+			tabindex="0"
+			onfocus={focusSelectedElement}
+			aria-label={$props?.ariaLabel}
+			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>
+				@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

@@ -0,0 +1,131 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+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;
+	/** Styles for the root element */
+	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;
+	/** 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;
+	/** If set to true, the user cannot interact with this ListBoxItem */
+	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,
+		text: $props?.text ?? "",
+		value: $props?.value,
+		selected: false,
+		active: false,
+		disabled: $props?.disabled ?? false,
+		parentDisabled: false,
+		setFocused,
+	});
+
+	let button: HTMLButtonElement;
+
+	// Get stuff out of the ListBoxContext
+	const context = $context[ListBoxContextName] as ListBoxContext;
+	if (!context) {
+		throw new Error("ListBoxItem must be contained within a ListBox");
+	}
+
+	// Register this item with the parent ListBox, which will handle toggling selected for all items
+	context.registerItem($state);
+
+	// Remove the item from the parent ListBox when this item is destroyed
+	$run(() => {
+		return () => {
+			context.removeItem($state.index);
+		};
+	});
+
+	// Dispatch the change event when the value of selected changes
+	$handle((first) => {
+		const selected = $state.selected;
+		if (!first) $props?.onchange?.(selected);
+	});
+
+	// This function is called by the parent ListBox to focus this item's button
+	function setFocused() {
+		button.focus();
+	}
+
+	function handleClick() {
+		// Pass the value to the toggleItem method in the parent ListBox which will handle toggling
+		// 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) {
+		switch (e.key) {
+			case "Enter": {
+				e.preventDefault();
+				context.toggleItem($state.value);
+				break;
+			}
+			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
+			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 || $state.parentDisabled ? "true" : undefined}
+			data-state={$state.selected || $state.active ? "active" : undefined}
+			onclick={handleClick}
+			onkeydown={handleKey}
+			onfocus={handleFocus}
+			onmount={handleMount}
+			&ref={button}
+		>
+			<slot />
+		</button>
+	}
+}

package/dist/ListBox/ListBoxSeparator.torp

@@ -0,0 +1,29 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+
+interface ListBoxSeparatorProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The orientation of the separator */
+	orientation?: "vertical" | "horizontal";
+}
+
+/**
+ * An element in a list box that separates logical sets of items.
+ */
+export default function ListBoxSeparator($props: ListBoxSeparatorProps | undefined) {
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-list-box-separator", $props?.class]}
+			{$props?.style}
+			role="separator"
+			aria-orientation={$props?.orientation ?? "horizontal"}
+		>
+			<slot />
+		</div>
+	}
+}

package/dist/ListBox/ListBoxTypes.ts

@@ -0,0 +1,41 @@
+export const ListBoxContextName: unique symbol = Symbol.for("torp.ListBox");
+export const ListBoxItemContextName: unique symbol = Symbol.for("torp.ListBoxItem");
+
+export interface ListBoxContext {
+	type: "single" | "multiple";
+	state: ListBoxState;
+	/** Called from a ListBoxItem when it is added */
+	registerItem: (state: ItemState) => void;
+	/** Called from a ListBoxItem when it is removed */
+	removeItem: (index: number) => void;
+	/** Called from a ListBoxItem when it is toggled */
+	toggleItem: (value: string) => void;
+	/** Called from a ListBoxItem when it receives a keyboard event */
+	handleKey: (index: number, e: KeyboardEvent) => void;
+	/** Called from a ListBoxItem when it receives focus */
+	setActiveDescendant?: (id: string) => void;
+	/** Reads the items loaded from the network loader, when one is set */
+	getLoadedItems?: () => any[];
+	/** Extracts the display text for a loaded item */
+	getItemLabel?: (item: any) => any;
+	/** Extracts the value for a loaded item */
+	getItemValue?: (item: any) => any;
+}
+
+export interface ListBoxState {
+	value: any;
+}
+
+export interface ItemState {
+	id: string;
+	index: number;
+	text: string;
+	value: any;
+	selected: boolean;
+	/** Used for styling when item has keyboard focus */
+	active: boolean;
+	disabled: boolean;
+	parentDisabled: boolean;
+	/** Called in the ListBox when an item needs to be focused */
+	setFocused: () => void;
+}

package/dist/ListBox/LoadedListBoxItems.torp

@@ -0,0 +1,41 @@
+import ListBoxItem from "./ListBoxItem.torp";
+
+interface LoadedListBoxItemsProps {
+	/** The loaded items */
+	items: any[];
+	/** Extracts the display text for an item (defaults to `label ?? text ?? item`) */
+	getItemLabel?: (item: any) => any;
+	/** Extracts the value for an item (defaults to `value ?? id`) */
+	getItemValue?: (item: any) => any;
+}
+
+function defaultLabel(item: any): string {
+	const label = item?.label ?? item?.text ?? item;
+	return typeof label === "string" ? label : String(label);
+}
+
+function defaultValue(item: any): any {
+	return item?.value ?? item?.id;
+}
+
+/**
+ * The internally rendered options for a ListBox that loads them from a
+ * network loader. Used as the slot fallback when no ListBoxItems are slotted
+ * in; not part of the public API.
+ */
+export default function LoadedListBoxItems($props?: LoadedListBoxItemsProps) {
+	const getLabel = $props?.getItemLabel ?? defaultLabel;
+	const getValue = $props?.getItemValue ?? defaultValue;
+
+	@render {
+		@for (let item of $props!.items) {
+			@key = getValue(item)
+			<ListBoxItem value={getValue(item)}>
+				{getLabel(item)}
+			</ListBoxItem>
+		}
+		@if ($props!.items.length === 0) {
+			<span class="torp-list-box-empty">No results.</span>
+		}
+	}
+}