@torpor/ui 0.3.7 → 1.0.0

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

package/dist/Tree/index.d.ts

@@ -0,0 +1,262 @@
+import { type SlotRender } from "@torpor/view";
+
+
+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>
+ * ```
+ */
+declare function Tree(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: TreeProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+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>
+ * ```
+ */
+declare function TreeItem(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: TreeItemProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+/**
+ * A container for nested TreeItems. This component must be a direct child of TreeItem.
+ *
+ * The structure is:
+ *
+ * ```
+ * <TreeItem>
+ * 	<TreeItemContent>...</TreeItemContent>
+ * 	<TreeItemChildren>
+ * 		<TreeItem />
+ * 	</TreeItemChildren>
+ * </TreeItem>
+ * ```
+ */
+declare function TreeItemChildren(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props?: TreeItemChildrenProps,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+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>
+ * ```
+ */
+declare function TreeItemContent(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: TreeItemContentProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+/**
+ * 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>
+ * ```
+ */
+declare function TreeItemLabel(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props?: TreeItemLabelProps,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+/**
+ * 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>
+ * ```
+ */
+declare function TreeItemTrigger(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props?: TreeItemTriggerProps,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+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>;
+}
+
+/**
+ * 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.
+ */
+declare function TreeLoadedChildren(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: TreeLoadedChildrenProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { Tree, TreeItem, TreeItemChildren, TreeItemContent, TreeItemLabel, TreeItemTrigger, TreeLoadedChildren };

package/dist/Tree/index.js

@@ -0,0 +1,7 @@
+import Tree from "./Tree.torp";
+import TreeItem from "./TreeItem.torp";
+import TreeItemChildren from "./TreeItemChildren.torp";
+import TreeItemContent from "./TreeItemContent.torp";
+import TreeItemLabel from "./TreeItemLabel.torp";
+import TreeItemTrigger from "./TreeItemTrigger.torp";
+export { Tree, TreeItem, TreeItemChildren, TreeItemContent, TreeItemLabel, TreeItemTrigger };

package/dist/icons/ChevronDoubleLeft.torp

@@ -0,0 +1,19 @@
+import { type IconProps } from "./IconTypes";
+
+export default function ChevronDoubleLeft($props: IconProps | undefined) {
+	@render {
+		<svg
+			{$props?.id}
+			class={["torp-icon", $props?.class]}
+			{$props?.style}
+			viewBox="0 0 100 100"
+			stroke-linejoin="round"
+			stroke-width="12"
+		>
+			<g>
+				<path fill="none" d="M90,10 L50,50 L90,90"></path>
+				<path fill="none" d="M50,10 L10,50 L50,90"></path>
+			</g>
+		</svg>
+	}
+}

package/dist/icons/ChevronDoubleRight.torp

@@ -0,0 +1,19 @@
+import { type IconProps } from "./IconTypes";
+
+export default function ChevronDoubleRight($props: IconProps | undefined) {
+	@render {
+		<svg
+			{$props?.id}
+			class={["torp-icon", $props?.class]}
+			{$props?.style}
+			viewBox="0 0 100 100"
+			stroke-linejoin="round"
+			stroke-width="12"
+		>
+			<g>
+				<path d="M10,10 L50,50 L10,90" fill="none" />
+				<path d="M50,10 L90,50 L50,90" fill="none" />
+			</g>
+		</svg>
+	}
+}