@torpor/ui 0.1.7 → 0.2.1

package/src/Menu/MenuPopoutContent.torp

@@ -0,0 +1,83 @@
+
+import setPopoverPosition from "../utils/setPopoverPosition";
+import { MenuPopoutContextName, type MenuPopoutContext } from "./MenuTypes";
+
+interface MenuPopoutContentProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** 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 MenuPopout when it is open.
+ */
+export default function MenuPopoutContent($props: MenuPopoutContentProps) {
+	$props ??= $watch({});
+	$props.side ??= "right";
+	$props.alignment ??= "start";
+
+	let div: HTMLDivElement;
+	let shown = false;
+
+	// Get stuff out of the MenuPopoutContext
+	const popoutContext = $context[MenuPopoutContextName] as MenuPopoutContext;
+	if (!popoutContext) {
+		throw new Error("MenuPopoutContent must be contained within a MenuPopout");
+	}
+	let $state = popoutContext.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();
+		addEventListener("resize", setPosition);
+		addEventListener("scroll", setPosition);
+		if (popoutContext.focusFirstElement) {
+			popoutContext.focusFirstElement();
+		}
+	}
+
+	function hide() {
+		if (!shown) return;
+
+		// Stop listening for window resize and focus the anchor element per WAI guidelines
+		removeEventListener("resize", setPosition);
+		removeEventListener("scroll", setPosition);
+		if (popoutContext.anchorElement?.focus) {
+			popoutContext.anchorElement.focus();
+		}
+	}
+
+	function setPosition() {
+		if (!popoutContext.anchorElement) {
+			throw new Error("MenuPopoutContent must have an anchor element");
+		}
+
+		setPopoverPosition(popoutContext.anchorElement, div, $props.side, $props.alignment);
+	}
+
+	@render {
+		@if ($state.visible) {
+			<div
+				{$props.id}
+				class={`torp-menu-popout-content ${$props.class ?? ""}`.trim()}
+				&ref={div}
+				onmount={show}
+			>
+				<slot />
+			</div>
+		}
+	}
+}

package/src/Menu/MenuPopoutTrigger.torp

@@ -0,0 +1,126 @@
+import {
+	MenuContextName,
+	MenuPopoutContextName,
+	type MenuContext,
+	type MenuPopoutContext
+} from "./MenuTypes";
+
+interface MenuPopoutTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** The delay before showing the popout, in milliseconds */
+	hoverDelay?: number,
+	/** Whether this button is disabled */
+	disabled?: boolean,
+}
+
+/**
+ * A button that is placed in a Menu or MenuGroup and signals a response by a user.
+ */
+export default function MenuPopoutTrigger($props: MenuPopoutTriggerProps) {
+	$props ??= $watch({});
+	$props.hoverDelay ??= 500;
+	$props.disabled ??= false;
+
+	let button: HTMLButtonElement;
+	let interval: NodeJS.Timeout | undefined;
+
+	// Get stuff out of the MenuContext
+	const menuContext = $context[MenuContextName] as MenuContext;
+	if (!menuContext) {
+		throw new Error("MenuPopoutTrigger must be contained within a Menu");
+	}
+	const { registerItem, handleItemKey, handleItemFocus } = menuContext;
+
+	// Get stuff out of the MenuPopoutContext
+	const popoutContext = $context[MenuPopoutContextName] as MenuPopoutContext;
+	if (!popoutContext) {
+		throw new Error("MenuPopoutTrigger must be contained within a MenuPopout");
+	}
+	const { state: $state, setVisible } = popoutContext;
+
+	// Register this item with the parent Menu and store the index
+	const { index } = registerItem(setFocused);
+
+	// TODO: This is getting called before @render
+	//$mount(() => {
+	//	// Set the anchor element to the button when it exists
+	//	popoutContext.anchorElement = button;
+	//});
+
+	function setFocused() {
+		button.focus();
+	}
+
+	function handleClick() {
+		setVisible(true);
+	}
+
+	function handlePopoutKey(e: KeyboardEvent) {
+		switch (e.key) {
+			case "Right":
+			case "ArrowRight":
+				// TODO: This should be based on what side the menu shows on
+				e.preventDefault();
+				setVisible(true);
+				break;
+			default:
+				handleItemKey(e);
+		}
+	}
+
+	function handleMouseEnter() {
+		if ($props.disabled) return;
+
+		// Handle the hover after a delay
+		if (!interval) {
+			interval = setTimeout(() => setVisible(true), $props.hoverDelay);
+		}
+	}
+
+	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(() => setVisible(true), $props.hoverDelay);
+		}
+	}
+
+	@render {
+		<button
+			{$props.id}
+			class={`torp-menu-popout-trigger ${$props.class ?? ""}`.trim()}
+			type="button"
+			{$props.disabled}
+			role="menuitem"
+			aria-haspopup="true"
+			aria-expanded={($state.visible ?? false).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/src/Menu/MenuRadio.torp

@@ -0,0 +1,99 @@
+import {
+	MenuButtonContextName,
+	MenuContextName,
+	MenuRadioGroupContextName,
+	type MenuButtonContext,
+	type MenuContext,
+	type MenuRadioGroupContext
+} from "./MenuTypes";
+
+interface MenuRadioProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** The value of the item */
+	value?: string,
+	/** Whether this item is checked */
+	checked?: boolean,
+	/** Whether this item is disabled */
+	disabled?: boolean,
+}
+
+/**
+ * A button that is placed in a Menu or MenuGroup to allow the user to select
+ * from a number of options.
+ */
+export default function MenuRadio($props: MenuRadioProps) {
+	$props ??= $watch({});
+
+	let $state = $watch({
+		checked: $props.checked,
+	});
+
+	$run(() => {
+		$props.checked = $state.checked;
+	});
+
+	let button: HTMLButtonElement;
+
+	// Get stuff out of the MenuContext
+	const menuContext = $context[MenuContextName] as MenuContext;
+	if (!menuContext) {
+		throw new Error("MenuRadio must be contained within a Menu");
+	}
+	const { registerItem, handleItemKey, handleItemFocus } = menuContext;
+
+	// Get stuff out of the MenuRadioGroupContext
+	const groupContext = $context[MenuRadioGroupContextName] as MenuRadioGroupContext;
+	if (!groupContext) {
+		throw new Error("MenuRadio must be contained within a MenuRadioGroup");
+	}
+	const { registerItemInGroup, toggleItem } = groupContext;
+
+	// Register this item with the parent Menu
+	const { index } = registerItem(setFocused);
+
+	// Register this item with the parent MenuRadioGroup
+	registerItemInGroup($props.value, setChecked);
+
+	// Set the context to pass down to items
+	let context: MenuButtonContext = {
+		state: $state
+	};
+	$context[MenuButtonContextName] = context;
+
+	function setFocused() {
+		button.focus();
+	}
+
+	function setChecked(value: boolean) {
+		$state.checked = value;
+	}
+
+	function handleClick() {
+		if (!$state.checked) {
+			toggleItem($props.value);
+		}
+	}
+
+	@render {
+		<button
+			{$props.id}
+			class={`torp-menu-radio ${$props.class ?? ""}`.trim()}
+			type="button"
+			{$props.disabled}
+			role="menuitemradio"
+			aria-checked={$props.checked}
+			aria-disabled={$props.disabled ? "true" : undefined}
+			data-state={$props.checked ? "checked" : "unchecked"}
+			data-disabled={$props.disabled ? "true" : undefined}
+			onkeydown={handleItemKey}
+			onclick={handleClick}
+			onfocus={() => handleItemFocus(index)}
+			&ref={button}
+		>
+			<slot />
+		</button>
+	}
+}

package/src/Menu/MenuRadioGroup.torp

@@ -0,0 +1,97 @@
+import {
+	type MenuRadioGroupContext,
+	MenuRadioGroupContextName,
+	type RadioGroupItemState
+} from "./MenuTypes";
+
+interface MenuRadioGroupProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** An ARIA label for describing the menu to screen readers */
+	ariaLabel?: string,
+	/** The value of the checked MenuRadio */
+	value?: string | undefined,
+	/** Called when the checked item has changed */
+	onchange?: (value: any) => void,
+}
+
+/**
+ * A container for a logical group of menu RadioGroup items.
+ */
+export default function MenuRadioGroup($props: MenuRadioGroupProps) {
+	$props ??= $watch({});
+
+	// A collection containing the state and some functions for each item
+	let itemStates: RadioGroupItemState[] = [];
+
+	// Set the context to pass down to items
+	let context: MenuRadioGroupContext = {
+		registerItemInGroup,
+		toggleItem
+	};
+	$context[MenuRadioGroupContextName] = context;
+
+	$mount(() => {
+		// Set the initial checked item
+		setValue($props.value);
+	});
+
+	function registerItemInGroup(itemValue: string, setChecked: (value: boolean) => void) {
+		// Add the item"s state to the array
+		const newItemState: RadioGroupItemState = {
+			value: itemValue,
+			checked: false,
+			setChecked
+		};
+		itemStates.push(newItemState);
+		itemStates = itemStates;
+	}
+
+	function setValue(newValue?: string) {
+		// No point doing this if there aren't any items yet (e.g. from the initial setValue() call)
+		if (!itemStates.length) {
+			return;
+		}
+
+		// Ensure the value passed in was a string (in case e.g. the user has set values to ints)
+		newValue = newValue?.toString();
+		for (let item of itemStates) {
+			item.checked = item.value === newValue;
+			item.setChecked(item.checked);
+		}
+
+		// Set the value
+		if ($props.value !== newValue) {
+			$props.value = newValue;
+
+			if ($props.onchange) {
+				$props.onchange($props.value);
+			}
+		}
+	}
+
+	function toggleItem(toggleValue: string) {
+		let newValue = "";
+		for (let item of itemStates) {
+			const checked = item.value === toggleValue;
+			item.setChecked(checked);
+			if (checked) {
+				newValue = item.value;
+			}
+		}
+		$props.value = newValue;
+	}
+
+	@render {
+		<div
+			{$props.id}
+			class={`torp-menu-radio-group ${$props.class ?? ""}`.trim()}
+			role="group"
+			aria-label={$props.ariaLabel}
+		>
+			<slot />
+		</div>
+	}
+}

package/src/Menu/MenuSeparator.torp

@@ -0,0 +1,24 @@
+
+interface MenuSeparatorProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
+/**
+ * An element in a menu that separates logical sets of menu items.
+ */
+export default function MenuSeparator($props: MenuSeparatorProps) {
+	$props ??= $watch({});
+
+	@render {
+		<div
+			{$props.id}
+			class={`torp-menu-separator ${$props.class ?? ""}`.trim()}
+			role="separator"
+		>
+			<slot />
+		</div>
+	}
+}

package/src/Menu/MenuTypes.ts

@@ -0,0 +1,58 @@
+export const MenuContextName = "Menu";
+export const MenuButtonContextName = "MenuButton";
+export const MenuRadioGroupContextName = "MenuRadioGroup";
+export const MenuPopoutContextName = "MenuPopout";
+
+export interface MenuContext {
+	setVisible: (value: boolean, result?: any) => void;
+
+	/** Called from a MenuButton to close the Menu and return a result */
+	handleTrigger: (type: "confirm" | "cancel" | undefined, value?: any) => void;
+
+	/** Called from a MenuButton when its button is focused */
+	handleItemFocus: (index: number) => void;
+
+	/** Called from a MenuButton when a key is pressed */
+	handleItemKey: (e: KeyboardEvent) => void;
+
+	state: {
+		/** Whether the Menu is visible. Writable so that it can be subscribed to by children */
+		visible: boolean;
+	};
+
+	/** The element that caused this Menu to be shown */
+	anchorElement?: HTMLElement;
+
+	/** Called from each MenuButton/Check/Radio to register itself with this Menu */
+	registerItem: (setFocused: () => void) => { index: number };
+}
+
+export interface MenuButtonContext {
+	state: {
+		checked: boolean;
+	};
+}
+
+export interface MenuRadioGroupContext {
+	registerItemInGroup: (value: string, setChecked: (value: boolean) => void) => void;
+	toggleItem: (value: string) => void;
+}
+
+export interface MenuPopoutContext {
+	setVisible: (value: boolean) => void;
+	state: {
+		visible: boolean;
+	};
+	anchorElement?: HTMLElement;
+	focusFirstElement?: () => void;
+}
+
+export interface ItemState {
+	setFocused: () => void;
+}
+
+export interface RadioGroupItemState {
+	value: string;
+	checked: boolean;
+	setChecked: (value: boolean) => void;
+}

package/src/Menu/index.ts

@@ -0,0 +1,25 @@
+import Menu from "./Menu.torp";
+import MenuButton from "./MenuButton.torp";
+import MenuCheck from "./MenuCheck.torp";
+import MenuGroup from "./MenuGroup.torp";
+import MenuIndicator from "./MenuIndicator.torp";
+import MenuPopout from "./MenuPopout.torp";
+import MenuPopoutContent from "./MenuPopoutContent.torp";
+import MenuPopoutTrigger from "./MenuPopoutTrigger.torp";
+import MenuRadio from "./MenuRadio.torp";
+import MenuRadioGroup from "./MenuRadioGroup.torp";
+import MenuSeparator from "./MenuSeparator.torp";
+
+export {
+	Menu,
+	MenuGroup,
+	MenuButton,
+	MenuCheck,
+	MenuRadio,
+	MenuRadioGroup,
+	MenuIndicator,
+	MenuPopout,
+	MenuPopoutTrigger,
+	MenuPopoutContent,
+	MenuSeparator,
+};

package/src/MenuBar/MenuBar.torp

@@ -0,0 +1,159 @@
+import { MenuBarContextName, type MenuBarContext, type ItemState } from "./MenuBarTypes";
+
+interface MenuBarProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** An ARIA label for describing the menu to screen readers */
+	ariaLabel?: string,
+	/** The orientation of the menu, which affects keyboard navigation */
+	orientation?: "horizontal" | "vertical",
+}
+
+/**
+ * A menu bar, similar to that shown at the top of Windows applications or at the top of the screen on Macs.
+ *
+ * See [the WAI ARIA guidelines for Menus](https://www.w3.org/WAI/ARIA/apg/patterns/menu/).
+ *
+ * The structure of a MenuBar is:
+ *
+ * ```
+ * <MenuBar>
+ *     <MenuBarItem>
+ *         <MenuBarItemTrigger />
+ *         <MenuBarItemContent>
+ *             <Menu />
+ *         </MenuBarItemContent>
+ *     </MenuBarItem>
+ * </MenuBar>
+ * ```
+ */
+export default function MenuBar($props: MenuBarProps) {
+	$props ??= $watch({});
+	$props.orientation ??= "horizontal";
+
+	let $state = $watch({
+		active: false,
+	});
+
+	// A collection containing the state and some functions for each item
+	let itemStates: ItemState[] = [];
+	let focusIndex = -1;
+
+	// Set the context to pass down to items
+	let context: MenuBarContext = {
+		handleItemShow,
+		handleButtonFocus,
+		handleButtonKey,
+		registerItem,
+		state: $state
+	};
+	$context[MenuBarContextName] = context;
+
+	function registerItem(setVisible: (value: boolean) => void, setFocused: () => void) {
+		// Add the item"s state to the array and return its index
+		const newItemState: ItemState = {
+			setVisible,
+			setFocused
+		};
+		itemStates.push(newItemState);
+		itemStates = itemStates;
+		return { index: itemStates.length - 1 };
+	}
+
+	function handleItemShow(index: number) {
+		// Make sure other items are hidden
+		itemStates.forEach((item, i) => {
+			if (i !== index) {
+				item.setVisible(false);
+			}
+		});
+	}
+
+	function handleButtonFocus(index: number) {
+		focusIndex = index;
+	}
+
+	function handleButtonKey(e: KeyboardEvent) {
+		switch (e.key) {
+			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");
+				}
+				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 {
+		<div
+			{$props.id}
+			class={`torp-menu-bar ${$props.class ?? ""}`.trim()}
+			tabindex="-1"
+			role="menubar"
+			aria-label={$props.ariaLabel}
+			aria-orientation={$props.orientation}
+		>
+			<slot />
+		</div>
+	}
+}