@torpor/ui 0.1.7 → 0.2.0

package/dist/Menu/Menu.torp

@@ -0,0 +1,160 @@
+import { PopoverContextName, type PopoverContext } from "../Popover/PopoverTypes";
+import {
+	MenuContextName,
+	type MenuContext,
+	type ItemState,
+	MenuPopoutContextName,
+	type MenuPopoutContext
+} from "./MenuTypes";
+
+/**
+ * A list of choices for the user, such as a set of actions or functions. A
+ * menu is usually hidden until made visible by the user.
+ *
+ * See [the WAI ARIA guidelines for Menus](https://www.w3.org/WAI/ARIA/apg/patterns/menu/).
+ *
+ * The structure of a Menu is:
+ *
+ * ```
+ * <Menu>
+ *     <MenuButton />
+ *     <MenuSeparator /> (optional)
+ *     <MenuGroup> (optional)
+ *         <MenuButton />
+ *     </MenuGroup>
+ * </Menu>
+ * ```
+ *
+ * @prop {string} ariaLabel -- An ARIA label for describing the menu to screen readers
+ */
+export default function Menu() {
+	// A collection containing the state and some functions for each item
+	let itemStates: ItemState[] = [];
+	let focusIndex = -1;
+
+	// Get stuff out of the PopoverContext
+	const popoverContext = $context[PopoverContextName] as PopoverContext;
+	if (!popoverContext) {
+		throw new Error("Menu must be contained within a Contextual, Prompt or Popover");
+	}
+	const { setVisible, handleButton, modal, visible } = popoverContext;
+
+	// Check whether this is a menu in a popout
+	const popoutContext = $context[MenuPopoutContextName] as MenuPopoutContext;
+	const inPopout = !!popoutContext;
+	const setPopoutVisible = popoutContext?.setVisible;
+
+	// Set the focusFirstElement method in the PopoverContext(s) so that it can be called after everything has been shown
+	popoverContext.focusFirstElement = focusFirstElement;
+	if (popoutContext) {
+		popoutContext.focusFirstElement = focusFirstElement;
+	}
+
+	// Set the context to pass down to items
+	let context: MenuContext = {
+		setVisible,
+		handleButton,
+		handleItemFocus,
+		handleItemKey,
+		visible,
+		registerItem
+	};
+	$context[MenuContextName] = context;
+
+	function focusFirstElement() {
+		if (itemStates.length) {
+			itemStates[0].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": {
+				e.preventDefault();
+				setVisible(false);
+				break;
+			}
+			case "Down":
+			case "ArrowDown": {
+				e.preventDefault();
+				focusItem("next");
+				break;
+			}
+			case "Up":
+			case "ArrowUp": {
+				e.preventDefault();
+				focusItem("previous");
+				break;
+			}
+			case "Left":
+			case "ArrowLeft": {
+				// TODO: This should be based on what side the menu shows on
+				if (inPopout) {
+					e.preventDefault();
+					setPopoutVisible(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 {
+		<div
+			{$props.id}
+			class={`torp-menu ${$props.class ?? ""}`.trim()}
+			tabindex="-1"
+			role="menu"
+			aria-label={$props.ariaLabel}
+			aria-orientation="vertical"
+		>
+			<slot />
+		</div>
+	}
+}

package/dist/Menu/MenuButton.torp

@@ -0,0 +1,53 @@
+import { MenuContextName, type MenuContext } from "./MenuTypes";
+
+/**
+ * A button that is placed in a Menu or MenuGroup and signals a response by a user.
+ *
+ * @prop {any} value -- The value that should be returned when this button is pressed and the Dialog was invoked by calling showContextual, showPrompt or showPopover
+ * @prop {boolean} disabled -- Whether this button is disabled
+ */
+export default function MenuButton() {
+	let button: HTMLButtonElement;
+
+	// Get stuff out of the MenuContext
+	const menuContext = $context[MenuContextName] as MenuContext;
+	if (!menuContext) {
+		throw new Error("MenuButton must be contained within a Menu");
+	}
+	const { registerItem, handleButton, handleItemKey, handleItemFocus } = menuContext;
+
+	// Register this item with the parent Menu and store the index
+	const { index } = registerItem(setFocused);
+
+	function handleKeyDown(e) {
+		handleItemKey(e);
+		if ($props.onkeydown) $props.onkeydown(e);
+	}
+
+	function handleClick(e) {
+		handleButton($props.value);
+		if ($props.onclick) $props.onclick(e);
+	}
+
+	function setFocused() {
+		button.focus();
+	}
+
+	@render {
+		<button
+			{$props.id}
+			class={`torp-menu-button ${$props.class ?? ""}`.trim()}
+			type="button"
+			{$props.disabled}
+			role="menuitem"
+			aria-disabled={$props.disabled ? "true" : undefined}
+			data-disabled={$props.disabled ? "true" : undefined}
+			onkeydown={handleKeyDown}
+			onclick={handleClick}
+			onfocus={() => handleItemFocus(index)}
+			&ref={button}
+		>
+			<slot />
+		</button>
+	}
+}

package/dist/Menu/MenuCheck.torp

@@ -0,0 +1,70 @@
+import {
+	MenuButtonContextName,
+	MenuContextName,
+	type MenuButtonContext,
+	type MenuContext
+} from "./MenuTypes";
+
+/**
+ * A button that is placed in a Menu or MenuGroup to allow the user to turn an
+ * option on or off.
+ *
+ * @prop {boolean} checked -- Whether this item is checked
+ * @prop {boolean} disabled -- Whether this item is disabled
+ */
+export default function MenuCheck() {
+	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("MenuCheck must be contained within a Menu");
+	}
+	const { registerItem, handleItemKey, handleItemFocus } = menuContext;
+
+	// Register this item with the parent Menu
+	const { index } = registerItem(setFocused);
+
+	// Set the context to pass down to items
+	let context: MenuButtonContext = {
+		state: $state
+	};
+	$context[MenuButtonContextName] = context;
+
+	function setFocused() {
+		button.focus();
+	}
+
+	function handleClick() {
+		$state.checked = !$state.checked;
+		if ($props.onclick) $props.onclick();
+	}
+
+	@render {
+		<button
+			{$props.id}
+			class={`torp-menu-check ${$props.class ?? ""}`.trim()}
+			type="button"
+			{$props.disabled}
+			role="menuitemcheckbox"
+			aria-checked={$props.checked ? "true" : "false"}
+			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/dist/Menu/MenuGroup.torp

@@ -0,0 +1,19 @@
+/**
+ * A container for a logical group of menu items.
+ *
+ * @prop {string} ariaLabel -- An ARIA label for describing the group to screen readers
+ */
+export default function MenuGroup() {
+	// TODO: Intercept the context to steal toggleItem??
+
+	@render {
+		<div
+			{$props.id}
+			class={`torp-menu-group ${$props.class ?? ""}`.trim()}
+			role="group"
+			aria-label={$props.ariaLabel}
+		>
+			<slot />
+		</div>
+	}
+}

package/dist/Menu/MenuIndicator.torp

@@ -0,0 +1,29 @@
+import { MenuButtonContextName, type MenuButtonContext } from "./MenuTypes";
+
+/**
+ * An indicator for a MenuCheck or MenuRadio component, which is displayed
+ * when the value of checked is true.
+ *
+ * @prop {boolean} disabled -- Whether this item is disabled
+ */ 
+export default function MenuIndicator() {
+	// Get stuff out of the MenuButtonContext
+	const context = $context[MenuButtonContextName] as MenuButtonContext;
+	if (!context) {
+		throw new Error("MenuIndicator must be contained within a MenuCheck or MenuRadio");
+	}
+	let $state = context.state;
+
+	@render {
+		@if ($state.checked) {
+			<div
+				{$props.id}
+				class={`torp-menu-indicator ${$props.class ?? ""}`.trim()}
+				aria-disabled={$props.disabled ? "true" : undefined}
+				data-disabled={$props.disabled ? "true" : undefined}
+			>
+				<slot />
+			</div>
+		}
+	}
+}

package/dist/Menu/MenuPopout.torp

@@ -0,0 +1,71 @@
+import { MenuPopoutContextName, type MenuPopoutContext } from "./MenuTypes";
+
+/**
+ * A popout that is attached to a menu button and can be used to show a submenu.
+ *
+ * The structure of a MenuPopout is:
+ *
+ * ```
+ * <MenuPopout>
+ *     <MenuPopoutTrigger /> (optional)
+ * 	<MenuPopoutContent />
+ * </MenuPopout>
+ * ```
+ *
+ * @prop {boolean} visible -- Whether the popout is visible
+ * @prop {(boolean) => void} ontoggle -- Called when the popout is opened or closed
+ * @prop {() => void} onopen -- Called when the popout has opened
+ * @prop {() => void} onclose -- Called when the popout has closed
+ */
+export default function MenuPopout($props) {
+	$props.visible ??= false;
+
+	let $state = $watch({
+		visible: $props.visible
+	});
+
+	let result: any;
+
+	// Set the context to pass down to items
+	let context: MenuPopoutContext = {
+		setVisible,
+		state: $state
+	};
+	$context[MenuPopoutContextName] = context;
+
+	function setVisible(value: boolean) {
+		$state.visible = value;
+	}
+
+	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() {
+		setVisible(false);
+	}
+
+	@render {
+		<div
+			{$props.id}
+			class={`torp-menu-popout ${$props.class ?? ""}`.trim()}
+			onmouseleave={handleMouseLeave}
+		>
+			<slot />
+		</div>
+	}
+}

package/dist/Menu/MenuPopoutContent.torp

@@ -0,0 +1,74 @@
+
+import setPopoverPosition from "../utils/setPopoverPosition";
+import { MenuPopoutContextName, type MenuPopoutContext } from "./MenuTypes";
+
+/**
+ * The content that is displayed for a MenuPopout when it is open.
+ *
+ * @prop {"top" | "right" | "bottom" | "left"} side -- Where the popout will be shown, relative to the popout button
+ * @prop {"start" | "center" | "end"} alignment -- How the popout will be aligned, relative to the popout button
+ */
+export default function MenuPopoutContent() {
+	$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/dist/Menu/MenuPopoutTrigger.torp

@@ -0,0 +1,117 @@
+import {
+	MenuContextName,
+	MenuPopoutContextName,
+	type MenuContext,
+	type MenuPopoutContext
+} from "./MenuTypes";
+
+/**
+ * A button that is placed in a Menu or MenuGroup and signals a response by a user.
+ *
+ * @prop {number} hoverDelay -- The delay before showing the popout, in milliseconds
+ * @prop {boolean} disabled -- Whether this button is disabled
+ */
+export default function MenuPopoutTrigger() {
+	$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/dist/Menu/MenuRadio.torp

@@ -0,0 +1,88 @@
+import {
+	MenuButtonContextName,
+	MenuContextName,
+	MenuRadioGroupContextName,
+	type MenuButtonContext,
+	type MenuContext,
+	type MenuRadioGroupContext
+} from "./MenuTypes";
+
+/**
+ * A button that is placed in a Menu or MenuGroup to allow the user to select
+ * from a number of options.
+ *
+ * @prop {string} value -- The value of the item
+ * @prop {boolean} checked -- Whether this item is checked
+ * @prop {boolean} disabled -- Whether this item is disabled
+ */
+export default function MenuRadio() {
+	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>
+	}
+}