@torpor/ui 0.3.7 → 1.0.0

package/dist/Tree/Tree.torp

@@ -0,0 +1,395 @@
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import $handle from "../utils/$handle";
+import {
+	type FieldContext,
+	FieldContextName,
+	type FormContext,
+	FormContextName,
+} from "../Form/FormTypes";
+import type { LoadResult, Loader } from "../utils/loader";
+import { type PopoutContext, PopoutContextName } from "../utils/PopoutTypes";
+import { createItemGroup } from "../utils/createItemGroup";
+import getId from "../utils/getId";
+import createFormField from "../utils/formField";
+import {
+	type ItemState,
+	type TreeContext,
+	type TreeLoadRequest,
+	TreeContextName,
+} from "./TreeTypes";
+import FormValues from "../Form/FormValues.torp";
+
+interface TreeProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The value(s) of the expanded TreeItem(s) */
+	expanded: Bindable<string | string[] | undefined>;
+	/** Whether a single TreeItem or multiple TreeItems can be selected at the same time */
+	type?: "single" | "multiple";
+	/** The value of the selected TreeItem, or an array of values if the type is "multiple" */
+	value: Bindable<string | string[] | undefined>;
+	/** If set to true, the user cannot interact with any items in the Tree */
+	disabled?: boolean;
+	/** The aria-label for the root element */
+	ariaLabel?: string | undefined;
+	/**
+	 * Reads the children of an item from the network (or anywhere async) when
+	 * the item is first expanded. Receives a request with `item` (the parent
+	 * item's value). Items load automatically when they set the TreeItem
+	 * `hasChildren` prop; a TreeItem `load` prop overrides this per item.
+	 */
+	load?: Loader<any, TreeLoadRequest>;
+	/** Called after each successful child load with the normalized result */
+	onload?: (result: LoadResult, item: string | undefined) => 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;
+	/** Raised when the expanded item(s) have changed */
+	onexpand?: (value: string | string[]) => void;
+	/** Raised when the selected item(s) have changed */
+	/** The name of the component's form data field */
+	name?: string;
+	onchange?: (value: string | string[] | undefined) => void;
+}
+
+/**
+ * A hierarchical list of items that can be expanded and collapsed to reveal nested content,
+ * with support for selecting items.
+ *
+ * See [the WAI ARIA guidelines for Tree Views](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/).
+ *
+ * The structure of a Tree is:
+ *
+ * ```
+ * <Tree>
+ * 	<TreeItem>
+ * 		<TreeItemContent>
+ * 			<TreeItemTrigger />
+ * 			<TreeItemLabel />
+ * 		</TreeItemContent>
+ * 		<TreeItemChildren>
+ * 			<TreeItem />
+ * 		</TreeItemChildren>
+ * 	</TreeItem>
+ * </Tree>
+ * ```
+ */
+export default function Tree($props: TreeProps | 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";
+	}
+
+	if ($props?.load !== undefined && typeof $props.load !== "function") {
+		throw new Error("Tree: `load` must be a function");
+	}
+
+	let $state = $watch({
+		expanded: $props?.expanded ?? [],
+		value: $props?.value ?? (getType() === "single" ? undefined : []),
+	});
+
+	$bind($state, $props, "expanded", "value");
+
+	// Maybe get stuff out of a popout context
+	const popoutContext = $context[PopoutContextName] as PopoutContext | undefined;
+	if (popoutContext) {
+		// 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 = "tree";
+	}
+
+	// Expansion behaves like a multiple-select group over the "expanded" flag;
+	// selection behaves like a single- or multiple-select group over "selected".
+	// Both groups share the same item states.
+	const expandedGroup = createItemGroup<ItemState>({
+		state: {
+			get value() {
+				return $state.expanded;
+			},
+			set value(value) {
+				$state.expanded = value;
+			},
+		},
+		type: "multiple",
+		selectedProperty: "expanded",
+	});
+	const selectGroup = createItemGroup<ItemState>({
+		state: $state,
+		type: getType,
+		selectedProperty: "selected",
+		disabled: () => $props?.disabled,
+	});
+
+	// Both groups hold the same item states in the same order
+	const itemStates = selectGroup.itemStates;
+
+	let context: TreeContext = {
+		get type() {
+			return getType();
+		},
+		state: $state,
+		registerItem,
+		removeItem,
+		toggleExpand: expandedGroup.toggleItem,
+		toggleSelect: (value) => {
+			selectGroup.toggleItem(value);
+			form.handleInput();
+		},
+		handleKey,
+		focusFirstItem,
+		focusLastItem,
+		findItem,
+		getNextVisibleItem,
+		getPreviousVisibleItem,
+		getParentItem,
+		getFirstChildItem,
+		load: typeof $props?.load === "function" ? $props.load : undefined,
+		onload: $props?.onload,
+		getItemLabel: $props?.getItemLabel,
+		getItemValue: $props?.getItemValue,
+	};
+	$context[TreeContextName] = context;
+
+	// Dispatch the expand event when the expanded value changes
+	$handle((first) => {
+		const value = $state.expanded;
+		if (!first) $props?.onexpand?.(value);
+	});
+
+	// Dispatch the change event when the selected value changes
+	$handle((first) => {
+		const value = $state.value;
+		if (!first) $props?.onchange?.(value);
+	});
+
+	function registerItem(itemState: ItemState, level: number) {
+		itemState.level = level;
+		expandedGroup.registerItem(itemState);
+		selectGroup.registerItem(itemState);
+	}
+
+	function removeItem(itemIndex: number) {
+		expandedGroup.removeItem(itemIndex);
+		selectGroup.removeItem(itemIndex);
+	}
+
+	function handleKey(index: number, e: KeyboardEvent) {
+		switch (e.key) {
+			case "ArrowUp": {
+				e.preventDefault();
+				let previousItem = getPreviousVisibleItem(index);
+				if (previousItem) {
+					previousItem.setFocused();
+				}
+				break;
+			}
+			case "ArrowDown": {
+				e.preventDefault();
+				let nextItem = getNextVisibleItem(index);
+				if (nextItem) {
+					nextItem.setFocused();
+				}
+				break;
+			}
+			case "ArrowLeft": {
+				e.preventDefault();
+				let currentItem = findItem(index);
+				if (currentItem && currentItem.expanded) {
+					expandedGroup.toggleItem(currentItem.value);
+				} else {
+					let parentItem = getParentItem(index);
+					if (parentItem) {
+						parentItem.setFocused();
+					}
+				}
+				break;
+			}
+			case "ArrowRight": {
+				e.preventDefault();
+				let currentItem = findItem(index);
+				if (currentItem) {
+					if (currentItem.expanded) {
+						let firstChild = getFirstChildItem(index);
+						if (firstChild) {
+							firstChild.setFocused();
+						}
+					} else if (currentItem.hasChildren) {
+						expandedGroup.toggleItem(currentItem.value);
+					}
+				}
+				break;
+			}
+			case "Home": {
+				e.preventDefault();
+				focusFirstItem();
+				break;
+			}
+			case "End": {
+				e.preventDefault();
+				focusLastItem();
+				break;
+			}
+			case "Enter":
+			case " ": {
+				e.preventDefault();
+				let currentItem = findItem(index);
+				if (currentItem) {
+					selectGroup.toggleItem(currentItem.value);
+				}
+				break;
+			}
+		}
+	}
+
+	function focusFirstItem() {
+		for (let item of itemStates) {
+			if (!isItemVisible(item, itemStates)) {
+				continue;
+			}
+			item.setFocused();
+			break;
+		}
+	}
+
+	function focusLastItem() {
+		for (let i = itemStates.length - 1; i >= 0; i--) {
+			let item = itemStates[i];
+			if (!isItemVisible(item, itemStates)) {
+				continue;
+			}
+			item.setFocused();
+			break;
+		}
+	}
+
+	function findItem(index: number): ItemState | undefined {
+		return itemStates.find((item) => item.index === index);
+	}
+
+	function getNextVisibleItem(index: number): ItemState | undefined {
+		let currentItem = findItem(index);
+		if (!currentItem) {
+			return undefined;
+		}
+
+		if (currentItem.expanded && currentItem.hasChildren) {
+			let nextIndex = index + 1;
+			if (nextIndex < itemStates.length) {
+				return itemStates[nextIndex];
+			}
+		}
+
+		for (let i = index + 1; i < itemStates.length; i++) {
+			let item = itemStates[i];
+			if (isItemVisible(item, itemStates) && !item.disabled) {
+				return item;
+			}
+		}
+
+		return undefined;
+	}
+
+	function getPreviousVisibleItem(index: number): ItemState | undefined {
+		for (let i = index - 1; i >= 0; i--) {
+			let item = itemStates[i];
+			if (isItemVisible(item, itemStates) && !item.disabled) {
+				return item;
+			}
+		}
+		return undefined;
+	}
+
+	function getParentItem(index: number): ItemState | undefined {
+		let currentItem = findItem(index);
+		if (!currentItem) {
+			return undefined;
+		}
+
+		for (let i = index - 1; i >= 0; i--) {
+			let item = itemStates[i];
+			if (item.expanded && item.hasChildren && i < index) {
+				let nextIndex = i + 1;
+				while (nextIndex < itemStates.length) {
+					let sibling = itemStates[nextIndex];
+					if (sibling.level <= item.level) {
+						break;
+					}
+					if (nextIndex === index) {
+						return item;
+					}
+					nextIndex++;
+				}
+			}
+		}
+
+		return undefined;
+	}
+
+	function getFirstChildItem(index: number): ItemState | undefined {
+		let nextIndex = index + 1;
+		if (nextIndex < itemStates.length) {
+			let child = itemStates[nextIndex];
+			if (child.level > itemStates[index].level) {
+				return child;
+			}
+		}
+		return undefined;
+	}
+
+	function isItemVisible(item: ItemState, allItems: ItemState[]): boolean {
+		if (item.level === 0) {
+			return true;
+		}
+
+		for (let i = item.index - 1; i >= 0; i--) {
+			let parentItem = allItems[i];
+			if (parentItem.level < item.level) {
+				return parentItem.expanded;
+			}
+		}
+
+		return true;
+	}
+
+	@render {
+		<div
+			id={$props?.id ?? defaultId}
+			class={["torp-tree", $props?.class]}
+			{$props?.style}
+			role="tree"
+			aria-label={$props?.ariaLabel}
+			aria-multiselectable={getType() === "multiple" ? "true" : undefined}
+			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 tree
+				if (!root.contains(e.relatedTarget as Node | null)) {
+					form.handleBlur();
+				}
+			}}
+			&ref={root}
+		>
+			<slot />
+		</div>
+
+		<FormValues name={form.name} value={$state.value} />
+	}
+}

package/dist/Tree/TreeItem.torp

@@ -0,0 +1,176 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import type { Loader } from "../utils/loader";
+import getId from "../utils/getId";
+import {
+	type ItemState,
+	type TreeContext,
+	TreeContextName,
+	type TreeItemContext,
+	TreeItemContextName,
+	type TreeLoadRequest,
+} from "./TreeTypes";
+import TreeLoadedChildren from "./TreeLoadedChildren.torp";
+
+interface TreeItemProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** A value for the item */
+	value?: string;
+	/**
+	 * Declares that the item has children that are not slotted in. When a
+	 * `load` function is available (this item's, or the tree's) they are
+	 * loaded from the network when the item is first expanded.
+	 */
+	hasChildren?: boolean;
+	/** If set to true, the user cannot interact with this TreeItem */
+	disabled?: boolean;
+	/**
+	 * Reads this item's children from the network (or anywhere async),
+	 * receiving `{ item }` (the item's value). Set alongside `hasChildren`;
+	 * overrides the tree's `load` function for this item.
+	 */
+	load?: Loader<any, TreeLoadRequest>;
+	/** Raised when this item is expanded or collapsed */
+	onexpand?: (expanded: boolean) => void;
+	/** Raised when this item is selected or deselected */
+	onselect?: (selected: boolean) => void;
+}
+
+/**
+ * An item in a Tree, which can contain nested TreeItems via TreeItemChildren.
+ *
+ * The structure of a TreeItem is:
+ *
+ * ```
+ * <TreeItem>
+ * 	<TreeItemContent>
+ * 		<TreeItemTrigger />
+ * 		<TreeItemLabel />
+ * 	</TreeItemContent>
+ * 	<TreeItemChildren>
+ * 		<TreeItem />
+ * 	</TreeItemChildren>
+ * </TreeItem>
+ * ```
+ */
+export default function TreeItem($props: TreeItemProps | undefined) {
+	let defaultId = getId();
+
+	const parentContext = $context[TreeItemContextName] as TreeItemContext;
+	const level = parentContext ? parentContext.state.level + 1 : 0;
+
+	let $state: ItemState = $watch({
+		id: $props?.id ?? defaultId,
+		index: -1,
+		value: $props?.value ?? "",
+		expanded: false,
+		selected: false,
+		disabled: $props?.disabled ?? false,
+		parentDisabled: false,
+		level,
+		hasChildren: false,
+		setFocused,
+	});
+
+	const context = $context[TreeContextName] as TreeContext;
+	if (!context) {
+		throw new Error("TreeItem must be contained within a Tree");
+	}
+
+	// Whether the item declares children that aren't slotted in and can be
+	// loaded when expanded. TreeItemChildren sets `slottedChildren` itself.
+	const declaredChildren = $props?.hasChildren === true;
+	const slottedLoad = typeof $props?.load === "function" ? $props.load : undefined;
+	let slottedChildren = false;
+
+	function updateHasChildren() {
+		if (declaredChildren || slottedChildren) {
+			if (!$state.hasChildren) $state.hasChildren = true;
+		} else if ($state.hasChildren) {
+			$state.hasChildren = false;
+		}
+	}
+	updateHasChildren();
+
+	// The loader for this item's children: the item's own or the tree's
+	const itemLoader = slottedLoad ?? (declaredChildren ? context.load : undefined);
+	if (declaredChildren && !itemLoader) {
+		throw new Error(
+			"TreeItem: declaring `hasChildren` requires a `load` function on the item or on the tree",
+		);
+	}
+
+	context.registerItem($state, $state.level);
+
+	$run(() => {
+		return () => {
+			context.removeItem($state.index);
+		};
+	});
+
+	$run(() => {
+		const onexpand = $props?.onexpand;
+		const expanded = $state.expanded;
+		if (onexpand) {
+			onexpand(expanded);
+		}
+	});
+
+	$run(() => {
+		const onselect = $props?.onselect;
+		const selected = $state.selected;
+		if (onselect) {
+			onselect(selected);
+		}
+	});
+
+	let focusLabel: (() => void) | undefined;
+
+	function setFocused() {
+		focusLabel?.();
+	}
+
+	let itemContext: TreeItemContext = {
+		state: $state,
+		setHasChildren: (hasChildren) => {
+			slottedChildren = hasChildren;
+			updateHasChildren();
+		},
+	};
+	$context[TreeItemContextName] = itemContext;
+
+	@render {
+		<div
+			{$state.id}
+			class={["torp-tree-item", $props?.class]}
+			{$props?.style}
+			role="treeitem"
+			aria-level={$state.level + 1}
+			aria-expanded={$state.hasChildren ? ($state.expanded ? "true" : "false") : undefined}
+			aria-selected={$state.selected ? "true" : "false"}
+			aria-disabled={$state.disabled || $state.parentDisabled ? "true" : undefined}
+			data-selected={$state.selected ? "selected" : undefined}
+		>
+			@// HACK: May be better to do this with CSS?
+			@if ($state.level) {
+				<div style="display: flex">
+					<div class={["torp-tree-item", $props?.class, "spacer"]} />
+					<div>
+						<slot />
+					</div>
+				</div>
+			} else {
+				<div>
+					<slot />
+				</div>
+			}
+			@if (declaredChildren && itemLoader) {
+				<TreeLoadedChildren itemState={$state} load={itemLoader} />
+			}
+		</div>
+	}
+}

package/dist/Tree/TreeItemChildren.torp

@@ -0,0 +1,60 @@
+import { type TreeItemContext, TreeItemContextName } from "./TreeTypes";
+import type { ClassValue, StyleValue } from "@torpor/view";
+
+interface TreeItemChildrenProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+}
+
+/**
+ * A container for nested TreeItems. This component must be a direct child of TreeItem.
+ *
+ * The structure is:
+ *
+ * ```
+ * <TreeItem>
+ * 	<TreeItemContent>...</TreeItemContent>
+ * 	<TreeItemChildren>
+ * 		<TreeItem />
+ * 	</TreeItemChildren>
+ * </TreeItem>
+ * ```
+ */
+export default function TreeItemChildren($props?: TreeItemChildrenProps) {
+	const itemContext = $context[TreeItemContextName] as TreeItemContext;
+
+	if (!itemContext) {
+		throw new Error("TreeItemChildren must be contained within a TreeItem");
+	}
+
+	const { setHasChildren, state: $state } = itemContext;
+
+	$run(() => {
+		setHasChildren(true);
+		return () => {
+			setHasChildren(false);
+		};
+	});
+
+	// HACK: We need to keep the items in the document so that we can search through them
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-tree-item-children", $props?.class, $state.expanded ? undefined : "hidden"]}
+			{$props?.style}
+			role="group"
+		>
+			<slot />
+		</div>
+	}
+
+	@style {
+		.torp-tree-item-children.hidden {
+			display: none;
+		}
+	}
+}

package/dist/Tree/TreeItemContent.torp

@@ -0,0 +1,46 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { type TreeItemContext, TreeItemContextName } from "./TreeTypes";
+
+interface TreeItemContentProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+}
+
+/**
+ * A wrapper for the content of a TreeItem, which should contain TreeItemTrigger and TreeItemLabel.
+ *
+ * The structure is:
+ *
+ * ```
+ * <TreeItem>
+ * 	<TreeItemContent>
+ * 		<TreeItemTrigger />
+ * 		<TreeItemLabel />
+ * 	</TreeItemContent>
+ * </TreeItem>
+ * ```
+ */
+export default function TreeItemContent($props: TreeItemContentProps | undefined) {
+	const itemContext = $context[TreeItemContextName] as TreeItemContext;
+
+	if (!itemContext) {
+		throw new Error("TreeItemLabel must be contained within a TreeItem");
+	}
+
+	const { state: $state } = itemContext;
+
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-tree-item-content", $props?.class]}
+			{$props?.style}
+			data-selected={$state.selected ? "selected" : undefined}
+		>
+			<slot />
+		</div>
+	}
+}