@torpor/ui 0.3.7 → 0.4.0

package/dist/ToolBar/ToolBar.torp

@@ -0,0 +1,198 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import {
+	ToolBarContextName,
+	type ToolBarContext,
+	type ItemState,
+	ToolBarPopoutContextName,
+	type ToolBarPopoutContext
+} from "./ToolBarTypes";
+
+interface ToolBarProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue,
+	/** Styles for the root element */
+	style?: StyleValue,
+	/** An ARIA label for describing the menu to screen readers  */
+	ariaLabel?: string | undefined,
+	/** The orientation of the menu, which affects keyboard navigation */
+	orientation?: "horizontal" | "vertical",
+}
+
+/**
+ * A toolbar is a container for grouping a set of controls, such as buttons, menubuttons, or checkboxes.
+ *
+ * See [the WAI ARIA guidelines for ToolBars](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/).
+ *
+ * The structure of a ToolBar is:
+ *
+ * ```
+ * <ToolBar>
+ *	 <ToolBarButton />
+ *	 <ToolBarSeparator /> (optional)
+ *	 <ToolBarPopout /> (optional)
+ *	 ...
+ * </ToolBar>
+ * ```
+ */
+export default function ToolBar($props: ToolBarProps | undefined) {
+	let orientation = $props?.orientation ?? "horizontal";
+
+	// A collection containing the state and some functions for each item
+	let itemStates: ItemState[] = [];
+	let focusIndex = -1;
+
+	// Check whether this is a menu in a popout
+	const popoutContext = $context[ToolBarPopoutContextName] as ToolBarPopoutContext;
+	const inPopout = !!popoutContext;
+	let popoutState = popoutContext?.state;
+
+	// Set the focusFirstElement method in the PopoverContext(s) so that it can be called after everything has been shown
+	if (popoutContext) {
+		popoutContext.focusFirstElement = focusFirstElement;
+		popoutContext.focusLastElement = focusLastElement;
+	}
+
+	// Set the context to pass down to items
+	let context: ToolBarContext = {
+		handleItemFocus,
+		handleItemKey,
+		registerItem,
+		orientation
+	};
+	$context[ToolBarContextName] = context;
+
+	// If the ToolBar is not in a popout, focus its first item. Otherwise the popout will call focusFirstElement, below
+	function handleFocus() {
+		if (!popoutContext && itemStates.length) {
+			itemStates[0].setFocused();
+		}
+	}
+
+	function focusFirstElement() {
+		if (itemStates.length) {
+			itemStates[0].setFocused();
+		}
+	}
+
+	function focusLastElement() {
+		if (itemStates.length > 0) {
+			itemStates.at(-1)!.setFocused();
+		}
+	}
+
+	function registerItem(setFocused: () => void) {
+		// Add the item's state to the array and return its index
+		const newItemState: ItemState = {
+			setFocused
+		};
+		itemStates.push(newItemState);
+		itemStates = itemStates;
+		return { index: itemStates.length - 1 };
+	}
+
+	function handleItemFocus(index: number) {
+		focusIndex = index;
+	}
+
+	function handleItemKey(e: KeyboardEvent) {
+		switch (e.key) {
+			case "Esc":
+			case "Escape": {
+				if (inPopout) {
+					e.preventDefault();
+					//setPopoutVisible(false);
+					popoutState.visible = false;
+				}
+				break;
+			}
+			case "Right":
+			case "ArrowRight": {
+				if (orientation === "horizontal") {
+					e.preventDefault();
+					focusItem("next");
+				}
+				break;
+			}
+			case "Left":
+			case "ArrowLeft": {
+				if (orientation === "horizontal") {
+					e.preventDefault();
+					focusItem("previous");
+				}
+				break;
+			}
+			case "Down":
+			case "ArrowDown": {
+				if (orientation === "vertical") {
+					e.preventDefault();
+					focusItem("next");
+				}
+				break;
+			}
+			case "Up":
+			case "ArrowUp": {
+				if (orientation === "vertical") {
+					e.preventDefault();
+					focusItem("previous");
+				} else {
+					// TODO: This should be based on what side the menu shows on
+					// And on the orientation
+					if (inPopout) {
+						e.preventDefault();
+						popoutState.visible = false;
+					}
+				}
+				break;
+			}
+			case "Home": {
+				e.preventDefault();
+				focusItem("start");
+				break;
+			}
+			case "End": {
+				e.preventDefault();
+				focusItem("end");
+				break;
+			}
+		}
+	}
+
+	function focusItem(target: "start" | "previous" | "next" | "end") {
+		switch (target) {
+			case "start": {
+				focusIndex = 0;
+				break;
+			}
+			case "previous": {
+				focusIndex = Math.max(0, focusIndex - 1);
+				break;
+			}
+			case "next": {
+				focusIndex = Math.min(itemStates.length - 1, focusIndex + 1);
+				break;
+			}
+			case "end": {
+				focusIndex = itemStates.length - 1;
+				break;
+			}
+		}
+		itemStates[focusIndex]?.setFocused();
+	}
+
+	@render {
+		<nav
+			{$props?.id}
+			class={["torp-tool-bar", $props?.class]}
+			{$props?.style}
+			tabindex="0"
+			role="toolbar"
+			aria-label={$props?.ariaLabel}
+			aria-orientation={orientation}
+			onfocus={handleFocus}
+		>
+			<slot />
+		</nav>
+	}
+}

package/dist/ToolBar/ToolBarButton.torp

@@ -0,0 +1,57 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { ToolBarContextName, type ToolBarContext } from "./ToolBarTypes";
+
+interface ToolBarButtonProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue,
+	/** Styles for the root element */
+	style?: StyleValue,
+	/** Whether this button is disabled  */
+	disabled?: boolean,
+	/** Raised when the button is clicked */
+	onclick?: (e: MouseEvent) => void,
+	/** Raised when a key is pressed down */
+	onkeydown?: (e: KeyboardEvent) => void,
+}
+
+/**
+ * A button that is placed in a ToolBar.
+ *
+ */
+export default function ToolBarButton($props: ToolBarButtonProps | undefined) {
+	let button: HTMLButtonElement;
+
+	// Get stuff out of the ToolBarContext
+	const menuContext = $context[ToolBarContextName] as ToolBarContext;
+	if (!menuContext) {
+		throw new Error("ToolBarButton must be contained within a ToolBar");
+	}
+	const { registerItem, handleItemKey, handleItemFocus } = menuContext;
+
+	// Register this item with the parent ToolBar and store the index
+	const { index } = registerItem(setFocused);
+
+	function setFocused() {
+		button.focus();
+	}
+
+	@render {
+		<button
+			{$props?.id}
+			class={["torp-tool-bar-button", $props?.class]}
+			{$props?.style}
+			type="button"
+			{$props?.disabled}
+			aria-disabled={$props?.disabled ? "true" : undefined}
+			data-disabled={$props?.disabled ? "true" : undefined}
+			{$props?.onclick}
+			onkeydown={handleItemKey}
+			onfocus={() => handleItemFocus(index)}
+			&ref={button}
+		>
+			<slot />
+		</button>
+	}
+}

package/dist/ToolBar/ToolBarElement.torp

@@ -0,0 +1,55 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { ToolBarContextName, type ToolBarContext } from "./ToolBarTypes";
+
+interface ToolBarElementProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue,
+	/** Styles for the root element */
+	style?: StyleValue,
+	/** Whether this button is disabled  */
+	disabled?: boolean,
+	/** An element that can be focused via keyboard navigation */
+	element?: HTMLElement,
+}
+
+/**
+ * An element of any type that can be placed in a ToolBar.
+ *
+ */
+export default function ToolBarElement($props: ToolBarElementProps | undefined) {
+	// Get stuff out of the ToolBarContext
+	const menuContext = $context[ToolBarContextName] as ToolBarContext;
+	if (!menuContext) {
+		throw new Error("ToolBarElement must be contained within a ToolBar");
+	}
+	const { registerItem, handleItemKey, handleItemFocus } = menuContext;
+
+	// Register this item with the parent ToolBar and store the index
+	const { index } = registerItem(setFocused);
+
+	function setFocused() {
+		if ($props?.element) {
+			$props.element.focus();
+		}
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-tool-bar-div", $props?.class]}
+			{$props?.style}
+			type="div"
+			role="menuitem"
+			aria-disabled={$props?.disabled ? "true" : undefined}
+			data-disabled={$props?.disabled ? "true" : undefined}
+			onkeydown
+			onkeydown={handleItemKey}
+			onclick
+			onfocus={() => handleItemFocus(index)}
+		>
+			<slot />
+		</div>
+	}
+}

package/dist/ToolBar/ToolBarPopout.torp

@@ -0,0 +1,97 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { ToolBarPopoutContextName, type ToolBarPopoutContext } from "./ToolBarTypes";
+import { PopoutContextName, type PopoutContext } from "../utils/PopoutTypes";
+
+interface ToolBarPopoutProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue,
+	/** Styles for the root element */
+	style?: StyleValue,
+	/** Whether the popout is visible */
+	visible?: boolean,
+	/** Raised when the popout is opened or closed */
+	ontoggle?: (open: boolean) => void,
+	/** Raised when the popout has opened */
+	onopen?: () => void,
+	/** Raised when the popout has closed */
+	onclose?: (result: any) => void,
+}
+
+/**
+ * A popout that is attached to a menu button and can be used to show a submenu.
+ *
+ * The structure of a ToolBarPopout is:
+ *
+ * ```
+ * <ToolBarPopout>
+ * 	<ToolBarPopoutTrigger />
+ * 	<ToolBarPopoutContent />
+ * </ToolBarPopout>
+ * ```
+ */
+export default function ToolBarPopout($props: ToolBarPopoutProps | undefined) {
+	let $state = $watch({
+		visible: false
+	});
+
+	// Sync props and state
+	$run(() => {
+		$state.visible = $props?.visible ?? false;
+	});
+	$run(() => {
+		if ($props !== undefined) {
+			$props.visible = $state.visible;
+		}
+	});
+
+	let result: any;
+
+	// Set the context to pass down to items
+	let context: ToolBarPopoutContext = {
+		state: $state,
+	};
+	$context[ToolBarPopoutContextName] = context;
+
+	// Set the context to pass down to items
+	let popoutContext: PopoutContext = {
+		handleButton: () => {},
+		state: $state,
+	};
+	$context[PopoutContextName] = popoutContext;
+
+	// Dispatch the toggle event when the popout is opened or closed
+	let firstToggle = true;
+	$run(() => {
+		const ontoggle = $props?.ontoggle;
+		const onopen = $props?.onopen;
+		const onclose = $props?.onclose;
+		const visible = $state.visible;
+		if (firstToggle) {
+			firstToggle = false;
+		} else {
+			if (ontoggle) ontoggle(visible);
+			if (visible) {
+				if (onopen) onopen()
+			} else {
+				if (onclose) onclose(result);
+			}
+		}
+	});
+
+	function handleMouseLeave() {
+		$state.visible = false;
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-tool-bar-popout", $props?.class]}
+			{$props?.style}
+			onmouseleave={handleMouseLeave}
+		>
+			<slot />
+		</div>
+	}
+}

package/dist/ToolBar/ToolBarPopoutContent.torp

@@ -0,0 +1,92 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import getScrollParent from "../utils/getScrollParent";
+import setPopoverPosition from "../utils/setPopoverPosition";
+import { ToolBarPopoutContextName, type ToolBarPopoutContext } from "./ToolBarTypes";
+
+interface ToolBarPopoutContentProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue,
+	/** Styles for the root element */
+	style?: StyleValue,
+	/** Where the popout will be shown, relative to the popout button */
+	side?: "top" | "right" | "bottom" | "left",
+	/** How the popout will be aligned, relative to the popout button */
+	alignment?: "start" | "center" | "end",
+}
+
+/**
+ * The content that is displayed for a ToolBarPopout when it is open.
+ *
+ */
+export default function ToolBarPopoutContent($props: ToolBarPopoutContentProps | undefined) {
+	let div: HTMLDivElement;
+	let shown = false;
+
+	// Get stuff out of the ToolBarPopoutContext
+	const context = $context[ToolBarPopoutContextName] as ToolBarPopoutContext;
+	if (!context) {
+		throw new Error("ToolBarPopoutContent must be contained within a ToolBarPopout");
+	}
+	let $state = context.state;
+
+	$run(() => {
+		if (!$state.visible) {
+			hide();
+		}
+	});
+
+	function show() {
+		shown = true;
+
+		// Set the position and listen for window resize and scroll to reset the position
+		setPosition();
+		const anchorElement = context.anchorElement!
+		const scrollParent = getScrollParent(anchorElement)
+		scrollParent.addEventListener("resize", setPosition);
+		scrollParent.addEventListener("scroll", setPosition);
+		if (context.focusFirstElement) {
+			context.focusFirstElement();
+		}
+	}
+
+	function hide() {
+		if (!shown) return;
+
+		// Stop listening for window resize and focus the anchor element per WAI guidelines
+		const anchorElement = context.anchorElement!
+		const scrollParent = getScrollParent(anchorElement)
+		scrollParent.removeEventListener("resize", setPosition);
+		scrollParent.removeEventListener("scroll", setPosition);
+		if (anchorElement.focus) {
+			anchorElement.focus();
+		}
+	}
+
+	function setPosition() {
+		if (!context.anchorElement) {
+			throw new Error("ToolBarPopoutContent must have an anchor element");
+		}
+
+		if (div) {
+			let side = $props?.side ?? "bottom";
+			let alignment = $props?.alignment ?? "start";
+			setPopoverPosition(context.anchorElement, div, side, alignment);
+		}
+	}
+
+	@render {
+		@if ($state.visible) {
+			<div
+				{$props?.id}
+				class={["torp-tool-bar-popout-content", $props?.class]}
+				{$props?.style}
+				&ref={div}
+				onmount={show}
+			>
+				<slot />
+			</div>
+		}
+	}
+}

package/dist/ToolBar/ToolBarPopoutTrigger.torp

@@ -0,0 +1,138 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import {
+	ToolBarContextName,
+	ToolBarPopoutContextName,
+	type ToolBarContext,
+	type ToolBarPopoutContext,
+} from "./ToolBarTypes";
+
+interface ToolBarPopoutTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue,
+	/** Styles for the root element */
+	style?: StyleValue,
+	/** The delay before showing the popout, in milliseconds */
+	hoverDelay?: number,
+	/** Whether this button is disabled */
+	disabled?: boolean,
+}
+
+/**
+ * A button that is placed in a ToolBar and signals a response by a user.
+ *
+ */
+export default function ToolBarPopoutTrigger($props: ToolBarPopoutTriggerProps | undefined) {
+	let defaultHoverDelay = 500;
+
+	let button: HTMLButtonElement;
+	let interval: NodeJS.Timeout | undefined;
+
+	// Get stuff out of the ToolBarContext
+	const toolBarContext = $context[ToolBarContextName] as ToolBarContext;
+	if (!toolBarContext) {
+		throw new Error("ToolBarPopoutTrigger must be contained within a ToolBar");
+	}
+	const { registerItem, handleItemKey, handleItemFocus } = toolBarContext;
+
+	// Get stuff out of the ToolBarPopoutContext
+	const popoutContext = $context[ToolBarPopoutContextName] as ToolBarPopoutContext;
+	if (!popoutContext) {
+		throw new Error("ToolBarPopoutTrigger must be contained within a ToolBarPopout");
+	}
+	let $state = popoutContext.state;
+
+	// Register this item with the parent ToolBar and store the index
+	const { index } = registerItem(setFocused);
+
+	// TODO: $mount should be run AFTER the button has been set
+	//$mount(() => {
+	//	// Set the anchor element to the button when it exists
+	//	popoutContext.anchorElement = button;
+	//});
+
+	function setFocused() {
+		button.focus();
+	}
+
+	function handleClick() {
+		$state.visible = true;
+	}
+
+	function handlePopoutKey(e: KeyboardEvent) {
+		switch (e.key) {
+			case "Right":
+			case "ArrowRight":
+				if (toolBarContext.orientation === "vertical") {
+					// TODO: This should be based on what side the menu shows on
+					e.preventDefault();
+					$state.visible = true;
+				}
+				break;
+			case "Down":
+			case "ArrowDown":
+				if (toolBarContext.orientation === "horizontal") {
+					e.preventDefault();
+					$state.visible = true;
+				}
+				break;
+			default:
+				handleItemKey(e);
+		}
+	}
+
+	function handleMouseEnter() {
+		if ($props?.disabled) return;
+
+		// Handle the hover after a delay
+		if (!interval) {
+			interval = setTimeout(() => $state.visible = true, $props?.hoverDelay ?? defaultHoverDelay);
+		}
+	}
+
+	function handleMouseLeave() {
+		if ($props?.disabled) return;
+
+		// Prevent short hovers or touches from firing the event
+		if (interval) {
+			clearTimeout(interval);
+			interval = undefined;
+		}
+	}
+
+	function handleMouseMove() {
+		if ($props?.disabled) return;
+
+		// Reset the interval on mouse move
+		if (interval) {
+			clearTimeout(interval);
+			interval = setTimeout(() => $state.visible = true, $props?.hoverDelay ?? defaultHoverDelay);
+		}
+	}
+
+	@render {
+		<button
+			{$props?.id}
+			class={["torp-tool-bar-popout-trigger", $props?.class]}
+			{$props?.style}
+			type="button"
+			{$props?.disabled}
+			role="menuitem"
+			aria-haspopup="true"
+			aria-expanded={$state.visible.toString()}
+			aria-disabled={$props?.disabled ? "true" : undefined}
+			data-disabled={$props?.disabled ? "true" : undefined}
+			onkeydown={handlePopoutKey}
+			onclick={handleClick}
+			onfocus={() => handleItemFocus(index)}
+			onmouseenter={handleMouseEnter}
+			onmouseleave={handleMouseLeave}
+			onmousemove={handleMouseMove}
+			&ref={button}
+			onmount={(el) => popoutContext.anchorElement = el }
+		>
+			<slot />
+		</button>
+	}
+}

package/dist/ToolBar/ToolBarSeparator.torp

@@ -0,0 +1,25 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+
+interface ToolBarSeparatorProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue,
+	/** Styles for the root element */
+	style?: StyleValue,
+}
+
+/**
+ * An element in a menu that separates logical sets of menu items.
+ */
+export default function ToolBarSeparator($props: ToolBarSeparatorProps | undefined) {
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-tool-bar-separator", $props?.class]}
+			role="separator"
+		>
+			<slot />
+		</div>
+	}
+}

package/dist/ToolBar/ToolBarTypes.ts

@@ -0,0 +1,35 @@
+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 {
+	/** Called from a ToolBarLink or ToolBarButton when its button is focused */
+	handleItemFocus: (index: number) => void;
+
+	/** Called from a ToolBarLink or ToolBarButton when a key is pressed */
+	handleItemKey: (e: KeyboardEvent) => void;
+
+	/** Called from each ToolBarLink or ToolBarButton to register itself with this ToolBar */
+	registerItem: (setFocused: () => void) => { 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;
+}