@torpor/ui 0.4.0 → 1.0.1

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>
+	}
+}

package/dist/Tree/TreeItemLabel.torp

@@ -0,0 +1,94 @@
+import {
+	type TreeContext,
+	TreeContextName,
+	type TreeItemContext,
+	TreeItemContextName,
+} from "./TreeTypes";
+import type { ClassValue, StyleValue } from "@torpor/view";
+
+interface TreeItemLabelProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+}
+
+/**
+ * The interactive label for a TreeItem, which can be clicked or keyboard-navigated to select the item.
+ * This component handles keyboard navigation and focus management for the tree.
+ *
+ * The structure is:
+ *
+ * ```
+ * <TreeItem>
+ * 	<TreeItemContent>
+ * 		<TreeItemTrigger />
+ * 		<TreeItemLabel>Item text</TreeItemLabel>
+ * 	</TreeItemContent>
+ * </TreeItem>
+ * ```
+ */
+export default function TreeItemLabel($props?: TreeItemLabelProps) {
+	const itemContext = $context[TreeItemContextName] as TreeItemContext;
+	const treeContext = $context[TreeContextName] as TreeContext;
+
+	if (!itemContext) {
+		throw new Error("TreeItemLabel must be contained within a TreeItem");
+	}
+
+	if (!treeContext) {
+		throw new Error("TreeItemLabel must be contained within a Tree");
+	}
+
+	const { state: $state } = itemContext;
+	let label: HTMLSpanElement;
+
+	$run(() => {
+		$state.setFocused = () => {
+			label.focus();
+		};
+	});
+
+	function handleSelectClick(e: MouseEvent) {
+		e.stopPropagation();
+		if (!$state.disabled && !$state.parentDisabled) {
+			treeContext.toggleSelect($state.value);
+		}
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		switch (e.key) {
+			case "Enter":
+			case " ": {
+				e.preventDefault();
+				e.stopPropagation();
+				if (!$state.disabled && !$state.parentDisabled) {
+					treeContext.toggleSelect($state.value);
+				}
+				break;
+			}
+			default: {
+				treeContext.handleKey($state.index, e);
+				break;
+			}
+		}
+	}
+
+	@render {
+		<span
+			{$props?.id}
+			class={["torp-tree-item-label", $props?.class]}
+			{$props?.style}
+			tabindex="0"
+			role="none"
+			data-selected={$state.selected ? "selected" : undefined}
+			onclick={handleSelectClick}
+			onkeydown={handleKey}
+			&ref={label}
+		>
+			<slot />
+		</span>
+	}
+}

package/dist/Tree/TreeItemTrigger.torp

@@ -0,0 +1,78 @@
+import ChevronDown from "../icons/ChevronDown.torp";
+import ChevronRight from "../icons/ChevronRight.torp";
+import {
+	type TreeContext,
+	TreeContextName,
+	type TreeItemContext,
+	TreeItemContextName,
+} from "./TreeTypes";
+import type { ClassValue, StyleValue } from "@torpor/view";
+
+interface TreeItemTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+}
+
+/**
+ * A button for expanding or collapsing a TreeItem that has nested children.
+ * When the item has no children, this renders as a spacer for consistent indentation.
+ *
+ * The structure is:
+ *
+ * ```
+ * <TreeItem>
+ * 	<TreeItemContent>
+ * 		<TreeItemTrigger />
+ * 		<TreeItemLabel />
+ * 	</TreeItemContent>
+ * </TreeItem>
+ * ```
+ */
+export default function TreeItemTrigger($props?: TreeItemTriggerProps) {
+	const itemContext = $context[TreeItemContextName] as TreeItemContext;
+	const treeContext = $context[TreeContextName] as TreeContext;
+
+	if (!itemContext) {
+		throw new Error("TreeItemTrigger must be contained within a TreeItem");
+	}
+
+	if (!treeContext) {
+		throw new Error("TreeItemTrigger must be contained within a Tree");
+	}
+
+	const { state: $state } = itemContext;
+
+	function handleClick(e: MouseEvent) {
+		e.stopPropagation();
+		treeContext.toggleExpand($state.value);
+	}
+
+	@render {
+		@if ($state.hasChildren) {
+			<button
+				{$props?.id}
+				class={["torp-tree-item-trigger", $props?.class]}
+				{$props?.style}
+				type="button"
+				disabled={$state.disabled || $state.parentDisabled}
+				aria-hidden="true"
+				tabindex="-1"
+				onclick={handleClick}
+			>
+				<slot {$state.expanded}>
+					@if ($state.expanded) {
+						<ChevronDown />
+					} else {
+						<ChevronRight />
+					}
+				</slot>
+			</button>
+		} else {
+			<span {$props?.id} class={["torp-tree-item-trigger", $props?.class, "spacer"]} {$props?.style} />
+		}
+	}
+}

package/dist/Tree/TreeLoadedChildren.torp

@@ -0,0 +1,122 @@
+import type { Loader } from "../utils/loader";
+import { createItemLoader } from "../utils/loader";
+import {
+	type ItemState,
+	type TreeContext,
+	TreeContextName,
+	type TreeLoadRequest,
+} from "./TreeTypes";
+import TreeItemChildren from "./TreeItemChildren.torp";
+import TreeItem from "./TreeItem.torp";
+import TreeItemContent from "./TreeItemContent.torp";
+import TreeItemLabel from "./TreeItemLabel.torp";
+import TreeItemTrigger from "./TreeItemTrigger.torp";
+
+interface TreeLoadedChildrenProps {
+	/** The state of the item whose children are loaded */
+	itemState: ItemState;
+	/** The load function that reads this item's children */
+	load: Loader<any, TreeLoadRequest>;
+}
+
+/** A loaded item, normalized for rendering */
+interface ChildEntry {
+	/** The item's value as a string, for the @key directive */
+	key: string;
+	value: any;
+	label: any;
+	hasChildren: boolean;
+}
+
+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;
+}
+
+/**
+ * Loads the children of a TreeItem that declares `hasChildren` but has no
+ * slotted TreeItemChildren, rendering them as nested TreeItems. The load
+ * starts when the item is first expanded and is not repeated afterwards;
+ * the results stay mounted (hidden while collapsed) so the tree can search
+ * through them.
+ *
+ * This is rendered automatically by TreeItem when there is a `load`
+ * function available; it is not part of the public API.
+ */
+export default function TreeLoadedChildren($props: TreeLoadedChildrenProps | undefined) {
+	const context = $context[TreeContextName] as TreeContext;
+	if (!context) {
+		throw new Error("TreeLoadedChildren must be contained within a Tree");
+	}
+
+	const $itemState = $props!.itemState;
+
+	const getLabel = context.getItemLabel ?? defaultLabel;
+	const getValue = context.getItemValue ?? defaultValue;
+
+	let $state = $watch({
+		started: false,
+		get childEntries(): ChildEntry[] {
+			return this.items.map(toEntry);
+		},
+		get items(): any[] {
+			return $load.items;
+		},
+	});
+
+	function toEntry(item: any): ChildEntry {
+		return {
+			key: String(getValue(item)),
+			value: getValue(item),
+			label: getLabel(item),
+			hasChildren: item?.hasChildren === true,
+		};
+	}
+
+	// Nothing is fetched until the item's first expansion; afterwards the
+	// loader keeps its result while the item is collapsed again
+	const $load = createItemLoader({
+		load: $props!.load,
+		getRequest: () => ({ item: $itemState.value }),
+		onload: (r) => context.onload?.(r, $itemState.value),
+	});
+
+	$run(() => {
+		if ($itemState.expanded) {
+			$state.started = true;
+		}
+	});
+
+	@render {
+		@if ($state.started) {
+			<TreeItemChildren>
+				@try {
+					@await {
+						@for (let entry of $state.childEntries) {
+							@key = entry.key
+							<TreeItem value={entry.value} hasChildren={entry.hasChildren}>
+								<TreeItemContent>
+									<TreeItemTrigger />
+									<TreeItemLabel>{entry.label}</TreeItemLabel>
+								</TreeItemContent>
+							</TreeItem>
+						}
+						@if ($state.childEntries.length === 0) {
+							<span class="torp-tree-item-empty">No items.</span>
+						}
+					} with {
+						<span class="torp-tree-item-loading">Loading…</span>
+					}
+				} catch (err) {
+					<span class="torp-tree-item-error" role="alert">
+						{err instanceof Error ? err.message : String(err)}
+					</span>
+				}
+			</TreeItemChildren>
+		}
+	}
+}

package/dist/Tree/TreeTypes.ts

@@ -0,0 +1,63 @@
+import type { LoadRequest, Loader } from "../utils/loader";
+import type { LoadResult } from "../utils/loader";
+
+/** The shape of a request sent to a Tree's `load` function */
+export interface TreeLoadRequest extends LoadRequest {
+	/** The value of the item whose children to load */
+	item?: string;
+}
+
+export const TreeContextName: unique symbol = Symbol.for("torp.Tree");
+
+export interface TreeContext {
+	type: "single" | "multiple";
+	state: TreeState;
+	registerItem: (state: ItemState, level: number) => void;
+	removeItem: (index: number) => void;
+	toggleExpand: (value: string) => void;
+	toggleSelect: (value: string) => void;
+	handleKey: (index: number, e: KeyboardEvent) => void;
+	focusFirstItem: () => void;
+	focusLastItem: () => void;
+	findItem: (index: number) => ItemState | undefined;
+	getNextVisibleItem: (index: number) => ItemState | undefined;
+	getPreviousVisibleItem: (index: number) => ItemState | undefined;
+	getParentItem: (index: number) => ItemState | undefined;
+	getFirstChildItem: (index: number) => ItemState | undefined;
+	/**
+	 * Reads the children of an item that declares `hasChildren`, called when
+	 * the item is first expanded
+	 */
+	load: Loader<any, TreeLoadRequest> | undefined;
+	/** Called after each successful child load with the normalized result */
+	onload: ((result: LoadResult, item: string | undefined) => void) | undefined;
+	/** Extracts the display text for a loaded item (defaults to `label ?? text ?? item`) */
+	getItemLabel: ((item: any) => any) | undefined;
+	/** Extracts the value for a loaded item (defaults to `value ?? id`) */
+	getItemValue: ((item: any) => any) | undefined;
+}
+
+export const TreeItemContextName: unique symbol = Symbol.for("torp.TreeItem");
+
+export interface TreeItemContext {
+	state: ItemState;
+	setHasChildren: (hasChildren: boolean) => void;
+}
+
+export interface TreeState {
+	expanded?: string | string[];
+	value?: string | string[];
+}
+
+export interface ItemState {
+	id: string;
+	index: number;
+	value: string;
+	expanded: boolean;
+	selected: boolean;
+	disabled: boolean;
+	parentDisabled: boolean;
+	level: number;
+	hasChildren: boolean;
+	setFocused: () => void;
+}