@torpor/ui 0.0.17 → 0.1.1

package/src/Accordion/AccordionItem.torp

@@ -1,4 +1,4 @@
-import { AccordionContextName, AccordionItemContextName, type AccordionContext, type AccordionItemContext } from './AccordionTypes';
+import { AccordionContextName, AccordionItemContextName, type AccordionContext, type AccordionItemContext } from "./AccordionTypes";
 
 /**
  * An item in an Accordion, which must consist of an AccordionTrigger and an AccordionContent.
@@ -27,14 +27,14 @@ export default function AccordionItem($props: any) {
 		disabled: $props.disabled,
 		parentDisabled: false,
 		get dataState() {
-			return this.expanded ? 'open' : 'closed';
+			return this.expanded ? "open" : "closed";
 		},
 	})
 
 	// Get stuff out of the AccordionContext
 	const context = $context[AccordionContextName] as AccordionContext;
 	if (!context) {
-		throw new Error('AccordionItem must be contained within an Accordion');
+		throw new Error("AccordionItem must be contained within an Accordion");
 	}
 
 	// Put stuff into an AccordionItemContext
@@ -56,16 +56,21 @@ export default function AccordionItem($props: any) {
 	});
 
 	// Dispatch the toggle event when the value of expanded changes
-	// TODO: Should this be a setter instead?
+	let firstToggle = true;
 	$run(() => {
-		if ($props.ontoggle) {
-			$props.ontoggle($state.expanded);
+		const ev = $props.ontoggle;
+		const expanded = $state.expanded;
+		if (firstToggle) {
+			firstToggle = false;
+		} else if (ev) {
+			ev(expanded);
 		}
-	})
+	});
 
 	@render {
 		<div
-			class='torp-accordion-item'
+			id={$props.id}
+			class={`torp-accordion-item ${$props.class ?? ""}`.trim()}
 			data-state={$state.dataState}
 			data-disabled={$state.dataDisabled}
 		>

package/src/Accordion/AccordionTrigger.torp

@@ -1,5 +1,5 @@
-import getId from '../utils/getId';
-import { AccordionItemContextName, type AccordionItemContext } from './AccordionTypes';
+import getId from "../utils/getId";
+import { AccordionItemContextName, type AccordionItemContext } from "./AccordionTypes";
 
 /**
  * A header button for an AccordionItem, which can be used to reveal or hide an associated AccordionContent.
@@ -12,7 +12,7 @@ export default function AccordionTrigger() {
 	// Get stuff out of the AccordionItemContext
 	const context = $context[AccordionItemContextName] as AccordionItemContext;
 	if (!context) {
-		throw new Error('AccordionTrigger must be contained within an AccordionItem');
+		throw new Error("AccordionTrigger must be contained within an AccordionItem");
 	}
 	let $state = $context[AccordionItemContextName].state;
 
@@ -42,14 +42,14 @@ export default function AccordionTrigger() {
 		<button
 			type="button"
 			id={$props.id}
-			class='torp-accordion-button'
+			class={`torp-accordion-trigger ${$props.class ?? ""}`.trim()}
 			disabled={$state.disabled || $state.parentDisabled}
 			aria-expanded={$state.expanded.toString()}
 			aria-disabled={$state.disabled}
 			aria-controls={$state.contentId}
 			data-state={$state.dataState}
 			data-disabled={$state.disabled}
-			:self={button}
+			&ref={button}
 			onclick={handleClick}
 			onkeydown={handleKey}
 		>

package/src/Accordion/AccordionTypes.ts

@@ -27,6 +27,7 @@ export interface ItemState {
 	expanded: boolean;
 	disabled: boolean;
 	parentDisabled: boolean;
+	dataState: "open" | "closed";
 	/** Called in the Accordion when a header needs to be focused */
 	setFocused: () => void;
 }

package/src/Dialog/Dialog.torp

@@ -0,0 +1,156 @@
+import getId from "../utils/getId";
+import { addDocumentEvent, removeDocumentEvent } from "../utils/documentEvents";
+import { trapFocus, type TrapFocusOptions } from "../mount/trapFocus";
+import { PopoverContextName, type PopoverContext } from "../Popover/PopoverTypes";
+import { DialogContextName, type DialogContext, type DialogState } from "./DialogTypes";
+
+/**
+ * Content for a window displayed in a Popover.
+ * 
+ * See [the WAI ARIA guidelines for Dialogs](https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal/).
+ * 
+ * The structure of a Dialog is:
+ * 
+ * ```
+ * <Dialog>
+ *     <DialogHeader /> (optional)
+ *     <DialogBody /> (optional)
+ *     <DialogFooter> (optional)
+ *         <DialogButton /> (optional)
+ *     </DialogFooter>
+ * </Dialog>
+ * ```
+ * 
+ * @prop {string | undefined} ariaLabel -- An ARIA label for describing the popover to screen readers 
+ * @prop {boolean} alert -- Whether the dialog should alert the user via the screen reader
+ */
+export default function Dialog($props: any) {
+	$props.id ??= getId();
+	$props.dialog ??= false;
+
+	let div: HTMLDivElement;
+
+	let trapFocusOptions: TrapFocusOptions = {
+		focusableElements: []
+	};
+
+	// Get stuff out of the PopoverContext
+	const popoverContext = $context[PopoverContextName] as PopoverContext;
+	if (!popoverContext) {
+		throw new Error("Dialog must be contained within a Popover");
+	}
+	const { handleButton, modal } = popoverContext;
+	const visible = popoverContext.state.visible;
+
+	popoverContext.handleClickOutside = handleClickOutside;
+	// Set the focusFirstElement method in the PopoverContext so that it can be
+	// called after everything has been shown
+	popoverContext.focusFirstElement = focusFirstElement;
+
+	// Set the IDs for using in the Dialog's ARIA attributes
+	let $state: DialogState = $watch({
+		dialogId: $props.id,
+		headerId: "",
+		bodyId: "",
+		visible
+	})
+
+	// Set the context to pass down to items
+	let context: DialogContext = {
+		handleButton,
+		state: $state,
+		anchorElement: popoverContext.anchorElement
+	};
+	$context[DialogContextName] = context;
+
+	let closeOnClick = false;
+
+	$mount(() => {
+		if ($state.visible) {
+			// HACK: Because this Dialog could be shown with a click, we need to
+			// wait for another mousedown before we close on click. Otherwise
+			// the click immediately bubbles to the document. I guess we could
+			// require the user to preventDefault after calling showPrompt etc,
+			// but that seems very error-prone?
+			closeOnClick = false;
+			addDocumentEvent("mousedown", handleDocumentMouseDown);
+			addDocumentEvent("click", handleDocumentClick);
+		} else {
+			removeDocumentEvent("mousedown", handleDocumentMouseDown);
+			removeDocumentEvent("click", handleDocumentClick);
+			// Focus the anchor element per WAI guidelines
+			if (context.anchorElement?.focus) {
+				context.anchorElement.focus();
+			}
+		}
+	});
+
+	function focusFirstElement() {
+		if (trapFocusOptions.focusableElements.length) {
+			trapFocusOptions.focusableElements[0].focus();
+		}
+	}
+
+	function handleDocumentMouseDown() {
+		closeOnClick = true;
+	}
+
+	function handleDocumentClick(e: MouseEvent) {
+		if (
+			closeOnClick &&
+			div &&
+			!div.contains(e.target as HTMLElement) &&
+			(!context.anchorElement || !context.anchorElement.contains(e.target as HTMLElement))
+		) {
+			handleClickOutside(e);
+		}
+	}
+
+	function handleClickOutside(e: MouseEvent) {
+		// Don't allow the user to click outside -- they must press a button or
+		// the Esc key
+		e.preventDefault();
+		if (!modal) {
+			popoverContext.state.visible = false;
+			context.state.visible = false;
+		}
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		switch (e.key) {
+			case "Esc":
+			case "Escape": {
+				if (context.cancelButton) {
+					context.cancelButton.click();
+					e.preventDefault();
+				}
+				break;
+			}
+			case "Enter": {
+				if (context.confirmButton) {
+					context.confirmButton.click();
+					e.preventDefault();
+				}
+				break;
+			}
+		}
+	}
+
+	@render {
+		<div
+			id={$props.id}
+			class={`torp-dialog ${$props.class ?? ""}`.trim()}
+			tabindex="0"
+			role={$props.alert ? "alertdialog" : "dialog"}
+			aria-modal={modal}
+			aria-label={$props.ariaLabel}
+			aria-labelledby={!$props.ariaLabel && $state.headerId ? $state.headerId : undefined}
+			aria-describedby={$state.bodyId ? $state.bodyId : undefined}
+			onkeydown={handleKey}
+			:onmount={(el) => trapFocus(el, trapFocusOptions)}
+			&ref={div}
+		>
+			<:slot />
+		</div>
+	}
+}

package/src/Dialog/DialogBody.torp

@@ -0,0 +1,34 @@
+import getId from "../utils/getId";
+import { DialogContextName, type DialogContext } from "./DialogTypes";
+
+/**
+ * The body information for a Dialog. Content in the body will be announced by
+ * screen readers when the Dialog is opened, unless ariaAnnounce is false.
+ * 
+ * @prop {boolean} ariaAnnounce -- Whether the body content will be announced by screen readers when the Dialog is opened
+ */
+export default function DialogBody($props: any) {
+	$props.id ??= getId();
+	$props.ariaAnnounce ??= true;
+
+	// Get stuff out of the DialogContext
+	const context = $context[DialogContextName] as DialogContext;
+	if (!context) {
+		throw new Error("DialogBody must be contained within a Dialog");
+	}
+	let $state = context.state;
+
+	// Set the body id for using in the Dialog's ARIA attributes
+	if ($props.ariaAnnounce) {
+		$state.bodyId = $props.id;
+	}
+
+	@render {
+		<div
+			id={$props.id} 
+			class={`torp-dialog-body ${$props.class ?? ""}`.trim()}
+		>
+			<:slot />
+		</div>
+	}
+}

package/src/Dialog/DialogButton.torp

@@ -0,0 +1,48 @@
+import { DialogContextName, type DialogContext } from "./DialogTypes";
+
+/**
+ * A button that is placed in a DialogFooter and signals a response by a user.
+ * 
+ * @prop {any | undefined} value -- The value that should be returned when this button is pressed and the Dialog was invoked by calling showContextual, showPrompt or showPopover
+ * @prop {"confirm" | "cancel" | undefined} type -- "confirm" if the button should respond to the Enter key or "cancel" if the button should respond to the Escape key
+ * @prop {boolean} disabled -- Whether this button is disabled
+ */
+export default function DialogButton($props: any) {
+	let button: HTMLButtonElement;
+
+	// Get stuff out of the DialogContext
+	const context = $context[DialogContextName] as DialogContext;
+	if (!context) {
+		throw new Error("DialogButton must be contained within a Dialog");
+	}
+	const handleButton = context.handleButton;
+
+	$mount(() => {
+		// Store the confirm or cancel button in the DialogContext
+		if ($props.type === "confirm") {
+			context.confirmButton = button;
+		} else if ($props.type === "cancel") {
+			context.cancelButton = button;
+		}
+	});
+
+	function handleClick(e) {
+		if ($props.onclick) {
+			$props.onclick(e)
+		}
+		handleButton($props.type, $props.value);
+	}
+
+	@render {
+		<button
+			type="button"
+			id={$props.id}
+			class={`torp-dialog-button ${$props.class ?? ""}`.trim()}
+			disabled={$props.disabled}
+			onclick={handleClick}
+			&ref={button}
+		>
+			<:slot />
+		</button>
+	}
+}

package/src/Dialog/DialogFooter.torp

@@ -0,0 +1,13 @@
+/**
+ * The footer for a Dialog, which may contain one or more DialogButtons.
+ */
+export default function DialogFooter($props: any) {
+	@render {
+		<div
+			id={$props.id}
+			class={`torp-dialog-footer ${$props.class ?? ""}`.trim()}
+		>
+			<:slot />
+		</div>
+	}
+}

package/src/Dialog/DialogHeader.torp

@@ -0,0 +1,34 @@
+import getId from "../utils/getId";
+import { DialogContextName, type DialogContext } from "./DialogTypes";
+
+/**
+ * The header for a Dialog. Content in the header will be announced by screen
+ * readers when the Dialog is opened, unless ariaAnnounce is false.
+ * 
+ * @prop {boolean} ariaAnnounce -- Whether the header will be announced by screen readers when the Dialog is opened
+ */
+export default function DialogHeader($props: any) {
+	$props.id ??= getId();
+	$props.ariaAnnounce ??= true;
+
+	// Get stuff out of the DialogContext
+	const context = $context[DialogContextName] as DialogContext;
+	if (!context) {
+		throw new Error("DialogHeader must be contained within a Dialog");
+	}
+	let $state = context.state;
+
+	// Set the header id for using in the Dialog's ARIA attributes
+	if ($props.ariaAnnounce) {
+		$state.headerId = $props.id;
+	}
+
+	@render {
+		<div
+			id={$props.id}
+			class={`torp-dialog-footer ${$props.class ?? ""}`.trim()}
+		>
+			<:slot />
+		</div>
+	}
+}

package/src/Dialog/DialogTypes.ts

@@ -0,0 +1,16 @@
+export const DialogContextName = "Dialog";
+
+export interface DialogContext {
+	handleButton: (type: "confirm" | "cancel" | undefined, value?: any) => void;
+	state: DialogState;
+	anchorElement?: HTMLElement;
+	confirmButton?: HTMLButtonElement;
+	cancelButton?: HTMLButtonElement;
+}
+
+export interface DialogState {
+	dialogId: string;
+	headerId: string;
+	bodyId: string;
+	visible: boolean;
+}

package/src/Dialog/index.ts

@@ -0,0 +1,7 @@
+import Dialog from "./Dialog.torp";
+import DialogBody from "./DialogBody.torp";
+import DialogButton from "./DialogButton.torp";
+import DialogFooter from "./DialogFooter.torp";
+import DialogHeader from "./DialogHeader.torp";
+
+export { Dialog, DialogHeader, DialogBody, DialogFooter, DialogButton };

package/src/Dialog.ts

@@ -0,0 +1,7 @@
+import Dialog from "./Dialog/Dialog.torp";
+import DialogBody from "./Dialog/DialogBody.torp";
+import DialogButton from "./Dialog/DialogButton.torp";
+import DialogFooter from "./Dialog/DialogFooter.torp";
+import DialogHeader from "./Dialog/DialogHeader.torp";
+
+export { Dialog, DialogHeader, DialogBody, DialogFooter, DialogButton };

package/src/NavMenu/NavMenu.torp

@@ -0,0 +1,178 @@
+import {
+	NavMenuContextName,
+	type NavMenuContext,
+	type ItemState,
+	NavMenuPopoutContextName,
+	type NavMenuPopoutContext
+} from "./NavMenuTypes";
+
+/**
+ * A list of links for navigating a website.
+ *
+ * See [the WAI ARIA guidelines for Menus](https://www.w3.org/WAI/ARIA/apg/patterns/menu/).
+ *
+ * The structure of a NavMenu is:
+ *
+ * ```
+ * <NavMenu>
+ *	 <NavMenuLink />
+ *	 <NavMenuSeparator /> (optional)
+ *	 <NavMenuPopout /> (optional)
+ *	 ...
+ * </NavMenu>
+ * ```
+ *
+ * @prop {string | undefined} ariaLabel -- An ARIA label for describing the menu to screen readers 
+ * @prop {"horizontal" | "vertical"} orientation -- The orientation of the menu, which affects keyboard navigation
+ */
+export default function NavMenu($props: any) {
+	$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[NavMenuPopoutContextName] as NavMenuPopoutContext;
+	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;
+	}
+
+	// Set the context to pass down to items
+	let context: NavMenuContext = {
+		handleItemFocus,
+		handleItemKey,
+		registerItem
+	};
+	$context[NavMenuContextName] = context;
+
+	// If the NavMenu is not in a popout, focus its first item. Otherwise the popout will call focusFirstElement, below
+	function handleFocus(e: FocusEvent & { currentTarget: EventTarget & HTMLElement }) {
+		if (!popoutContext && itemStates.length) {
+			itemStates[0].setFocused();
+		}
+	}
+
+	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": {
+				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
+			id={$props.id}
+			class={`torp-nav-menu ${$props.class ?? ""}`.trim()}
+			tabindex="0"
+			role="menubar"
+			aria-label={$props.ariaLabel}
+			aria-orientation={$props.orientation}
+			onfocus={handleFocus}
+		>
+			<:slot />
+		</nav>
+	}
+}

package/src/NavMenu/NavMenuButton.torp

@@ -0,0 +1,46 @@
+import { NavMenuContextName, type NavMenuContext } from "./NavMenuTypes";
+
+/**
+ * A button that is placed in a NavMenu to carry out a non-navigation action such as logging out.
+ *
+ * @prop {boolean} disabled -- Whether this button is disabled 
+ */
+export default function NavMenuButton($props: any) {
+	/** Set when the item is disabled */
+	let dataDisabled = $props.disabled || undefined;
+
+	let button: HTMLButtonElement;
+
+	// Get stuff out of the NavMenuContext
+	const menuContext = $context[NavMenuContextName] as NavMenuContext;
+	if (!menuContext) {
+		throw new Error("NavMenuButton must be contained within a NavMenu");
+	}
+	const { registerItem, handleItemKey, handleItemFocus } = menuContext;
+
+	// Register this item with the parent NavMenu and store the index
+	const { index } = registerItem(setFocused);
+
+	function setFocused() {
+		button.focus();
+	}
+
+	@render {
+		<button
+			id={$props.id}
+			class={`torp-nav-menu-button ${$props.class ?? ""}`.trim()}
+			type="button"
+			{disabled}
+			role="menuitem"
+			aria-disabled={disabled ? "true" : undefined}
+			data-disabled={dataDisabled}
+			onkeydown
+			onkeydown={handleItemKey}
+			onclick
+			onfocus={() => handleItemFocus(index)}
+			&ref={button}
+		>
+			<:slot />
+		</button>
+	}
+}

package/src/NavMenu/NavMenuElement.torp

@@ -0,0 +1,43 @@
+import { NavMenuContextName, type NavMenuContext } from "./NavMenuTypes";
+
+/**
+ * An element of any type that can be placed in a NavMenu.
+ *
+ * @prop {boolean} disabled -- Whether this button is disabled 
+ * @prop {HTMLElement} element -- An element that can be focused via keyboard navigation
+ */
+export default function NavMenuElement($props: any) {
+	/** Set when the item is disabled */
+	let dataDisabled = $props.disabled || undefined;
+
+	// Get stuff out of the NavMenuContext
+	const menuContext = $context[NavMenuContextName] as NavMenuContext;
+	if (!menuContext) {
+		throw new Error("NavMenuElement must be contained within a NavMenu");
+	}
+	const { registerItem, handleItemKey, handleItemFocus } = menuContext;
+
+	// Register this item with the parent NavMenu and store the index
+	const { index } = registerItem(setFocused);
+
+	function setFocused() {
+		element.focus();
+	}
+
+	@render {
+		<div
+			id={$props.id}
+			class={`torp-nav-menu-div ${$props.class ?? ""}`.trim()}
+			type="div"
+			role="menuitem"
+			aria-disabled={$props.disabled ? "true" : undefined}
+			data-disabled={dataDisabled}
+			onkeydown
+			onkeydown={handleItemKey}
+			onclick
+			onfocus={() => handleItemFocus(index)}
+		>
+			<:slot />
+		</div>
+	}
+}