@torpor/ui 0.4.0 → 1.0.1

package/dist/ToolBar/ToolBarSeparator.torp

@@ -4,9 +4,9 @@ interface ToolBarSeparatorProps {
 	/** 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;
 }
 
 /**
@@ -14,11 +14,7 @@ interface ToolBarSeparatorProps {
  */
 export default function ToolBarSeparator($props: ToolBarSeparatorProps | undefined) {
 	@render {
-		<div
-			{$props?.id}
-			class={["torp-tool-bar-separator", $props?.class]}
-			role="separator"
-		>
+		<div {$props?.id} class={["torp-tool-bar-separator", $props?.class]} role="separator">
 			<slot />
 		</div>
 	}

package/dist/ToolBar/ToolBarTypes.ts

@@ -1,5 +1,6 @@
+import type { SubmenuItemState } from "../utils/PopoutTypes";
+
 export const ToolBarContextName: unique symbol = Symbol.for("torp.ToolBar");
-export const ToolBarPopoutContextName: unique symbol = Symbol.for("torp.ToolBarPopout");
 export const ToolBarGroupContextName: unique symbol = Symbol.for("torp.ToolBarGroup");
 
 export interface ToolBarContext {
@@ -9,27 +10,19 @@ export interface ToolBarContext {
 	/** Called from a ToolBarLink or ToolBarButton when a key is pressed */
 	handleItemKey: (e: KeyboardEvent) => void;
 
+	/** Called from a MenuButton when a submenu is shown */
+	handlePopout: (index: number) => void;
+
 	/** Called from each ToolBarLink or ToolBarButton to register itself with this ToolBar */
-	registerItem: (setFocused: () => void) => { index: number };
+	registerItem: (item: ItemState) => { index: number };
 
 	orientation: "horizontal" | "vertical";
 }
 
-export interface ToolBarPopoutContext {
-	state: {
-		visible: boolean;
-	};
-	anchorElement?: HTMLElement;
-	focusFirstElement?: () => void;
-	focusLastElement?: () => void;
-}
-
 export interface ToolBarGroupContext {
 	state: {
 		headerId: string;
 	};
 }
 
-export interface ItemState {
-	setFocused: () => void;
-}
+export type ItemState = SubmenuItemState;

package/dist/ToolBar/index.d.ts

@@ -5,13 +5,13 @@ interface ToolBarProps {
 	/** 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;
 	/** An ARIA label for describing the menu to screen readers  */
-	ariaLabel?: string | undefined,
+	ariaLabel?: string | undefined;
 	/** The orientation of the menu, which affects keyboard navigation */
-	orientation?: "horizontal" | "vertical",
+	orientation?: "horizontal" | "vertical";
 }
 
 /**
@@ -44,15 +44,15 @@ interface ToolBarButtonProps {
 	/** 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 this button is disabled  */
-	disabled?: boolean,
+	disabled?: boolean;
 	/** Raised when the button is clicked */
-	onclick?: (e: MouseEvent) => void,
+	onclick?: (e: MouseEvent) => void;
 	/** Raised when a key is pressed down */
-	onkeydown?: (e: KeyboardEvent) => void,
+	onkeydown?: (e: KeyboardEvent) => void;
 }
 
 /**
@@ -73,13 +73,13 @@ interface ToolBarElementProps {
 	/** 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 this button is disabled  */
-	disabled?: boolean,
+	disabled?: boolean;
 	/** An element that can be focused via keyboard navigation */
-	element?: HTMLElement,
+	element?: HTMLElement;
 }
 
 /**
@@ -100,21 +100,19 @@ interface ToolBarPopoutProps {
 	/** 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 the popout is visible */
-	visible?: boolean,
-	/** Raised when the popout is opened or closed */
-	ontoggle?: (open: boolean) => void,
+	visible: Bindable<boolean | undefined>;
 	/** Raised when the popout has opened */
-	onopen?: () => void,
+	onopen?: () => void;
 	/** Raised when the popout has closed */
-	onclose?: (result: any) => void,
+	onclose?: (result: any) => void;
 }
 
 /**
- * A popout that is attached to a menu button and can be used to show a submenu.
+ * A popout that is attached to a toolbar button and can be used to show a submenu.
  *
  * The structure of a ToolBarPopout is:
  *
@@ -139,13 +137,13 @@ interface ToolBarPopoutContentProps {
 	/** 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;
 	/** Where the popout will be shown, relative to the popout button */
-	side?: "top" | "right" | "bottom" | "left",
+	side?: "top" | "right" | "bottom" | "left";
 	/** How the popout will be aligned, relative to the popout button */
-	alignment?: "start" | "center" | "end",
+	alignment?: "start" | "center" | "end";
 }
 
 /**
@@ -166,13 +164,13 @@ interface ToolBarPopoutTriggerProps {
 	/** 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 delay before showing the popout, in milliseconds */
-	hoverDelay?: number,
+	hoverDelay?: number;
 	/** Whether this button is disabled */
-	disabled?: boolean,
+	disabled?: boolean;
 }
 
 /**
@@ -193,9 +191,9 @@ interface ToolBarSeparatorProps {
 	/** 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;
 }
 
 /**
@@ -209,4 +207,4 @@ declare function ToolBarSeparator(
 	$slots?: Record<string, SlotRender>,
 ): void;
 
-export { ToolBar, ToolBarButton, ToolBarElement, ToolBarPopout, ToolBarPopoutContent, ToolBarPopoutTrigger, ToolBarSeparator };
+export { ToolBar, ToolBarButton, ToolBarElement, ToolBarPopout, ToolBarPopoutContent, ToolBarPopoutTrigger, ToolBarSeparator };

package/dist/ToolBar/index.js

@@ -1,30 +1,8 @@
-// src/ToolBar/ToolBar.torp
-import ToolBar_default from "./ToolBar.torp";
-
-// src/ToolBar/ToolBarButton.torp
-import ToolBarButton_default from "./ToolBarButton.torp";
-
-// src/ToolBar/ToolBarElement.torp
-import ToolBarElement_default from "./ToolBarElement.torp";
-
-// src/ToolBar/ToolBarPopout.torp
-import ToolBarPopout_default from "./ToolBarPopout.torp";
-
-// src/ToolBar/ToolBarPopoutContent.torp
-import ToolBarPopoutContent_default from "./ToolBarPopoutContent.torp";
-
-// src/ToolBar/ToolBarPopoutTrigger.torp
-import ToolBarPopoutTrigger_default from "./ToolBarPopoutTrigger.torp";
-
-// src/ToolBar/ToolBarSeparator.torp
-import ToolBarSeparator_default from "./ToolBarSeparator.torp";
-export {
-  ToolBar_default as ToolBar,
-  ToolBarButton_default as ToolBarButton,
-  ToolBarElement_default as ToolBarElement,
-  ToolBarPopout_default as ToolBarPopout,
-  ToolBarPopoutContent_default as ToolBarPopoutContent,
-  ToolBarPopoutTrigger_default as ToolBarPopoutTrigger,
-  ToolBarSeparator_default as ToolBarSeparator
-};
-//# sourceMappingURL=index.js.map
+import ToolBar from "./ToolBar.torp";
+import ToolBarButton from "./ToolBarButton.torp";
+import ToolBarElement from "./ToolBarElement.torp";
+import ToolBarPopout from "./ToolBarPopout.torp";
+import ToolBarPopoutContent from "./ToolBarPopoutContent.torp";
+import ToolBarPopoutTrigger from "./ToolBarPopoutTrigger.torp";
+import ToolBarSeparator from "./ToolBarSeparator.torp";
+export { ToolBar, ToolBarButton, ToolBarElement, ToolBarPopout, ToolBarPopoutContent, ToolBarPopoutTrigger, ToolBarSeparator };

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