@torpor/ui 0.3.7 → 1.0.0

package/dist/ListBox/index.d.ts

@@ -0,0 +1,136 @@
+import { type SlotRender } from "@torpor/view";
+
+
+interface ListBoxProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** Whether a single ListBoxItem or multiple ListBoxItems can be selected at the same time */
+	type?: "single" | "multiple";
+	/** The value of the selected ListBoxItem, or an array of values if the type is "multiple" */
+	value: Bindable<any | any[]>;
+	/** If set to true, the user cannot interact with any items in the ListBox */
+	disabled?: boolean;
+	/** An ARIA label for describing the ListBox to screen readers  */
+	ariaLabel?: string | undefined;
+	/** An ID of an element that labels the ListBox */
+	ariaLabelledBy?: string | undefined;
+	/** The orientation of the ListBox */
+	orientation?: "vertical" | "horizontal";
+	/** Raised when the selected item(s) have changed */
+	/** The name of the component's form data field */
+	name?: string;
+	/**
+	 * Reads options from the network (or anywhere async), receiving
+	 * `{ searchText }` whenever the bound `searchText` changes. When set and
+	 * no ListBoxItems are slotted in, the options are rendered automatically
+	 */
+	load?: Loader;
+	/** Called after each successful load with the normalized result */
+	onload?: (result: LoadResult) => 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;
+	/** Filter text for a `load` function; two-way bindable */
+	searchText?: Bindable<string | undefined>;
+	onchange?: (value: any | any[]) => void;
+}
+
+/**
+ * A list of options that a user can select.
+ *
+ * See [the WAI ARIA guidelines for ListBoxes](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/).
+ *
+ * The structure of an ListBox is:
+ *
+ * ```
+ * <ListBox>
+ * 	<ListBoxItem />
+ * 	<ListBoxSeparator /> (optional)
+ * </ListBox>
+ * ```
+ */
+declare function ListBox(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: ListBoxProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface ListBoxItemProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The index of this item in the ListBox. Set this if you will be inserting, removing or sorting items. If you don't set this, it will be set automatically */
+	index?: number;
+	/** The text for the item. If not set, this will come from it's text content */
+	text?: string;
+	/** A value for the item. Set this if you need more control over which item(s) are selected. If you don't set this, the value will be set to the item's initial index */
+	value?: string;
+	/** If set to true, the user cannot interact with this ListBoxItem */
+	disabled?: boolean;
+	/** Raised when this item's selected state has changed */
+	onchange?: (selected: boolean) => void;
+}
+
+/**
+ * An item in an ListBox.
+ */
+declare function ListBoxItem(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: ListBoxItemProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface ListBoxSeparatorProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The orientation of the separator */
+	orientation?: "vertical" | "horizontal";
+}
+
+/**
+ * An element in a list box that separates logical sets of items.
+ */
+declare function ListBoxSeparator(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: ListBoxSeparatorProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+/**
+ * The internally rendered options for a ListBox that loads them from a
+ * network loader. Used as the slot fallback when no ListBoxItems are slotted
+ * in; not part of the public API.
+ */
+declare function LoadedListBoxItems(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props?: LoadedListBoxItemsProps,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { ListBox, ListBoxItem, ListBoxSeparator, LoadedListBoxItems };

package/dist/ListBox/index.js

@@ -0,0 +1,4 @@
+import ListBox from "./ListBox.torp";
+import ListBoxItem from "./ListBoxItem.torp";
+import ListBoxSeparator from "./ListBoxSeparator.torp";
+export { ListBox, ListBoxItem, ListBoxSeparator };

package/dist/MaskedInput/MaskedInput.torp

@@ -0,0 +1,143 @@
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import {
+	type FieldContext,
+	FieldContextName,
+	type FormContext,
+	FormContextName,
+} from "../Form/FormTypes";
+import FormValues from "../Form/FormValues.torp";
+import { extractRaw, formatMask, parseMask } from "../utils/maskUtils";
+import createFormField from "../utils/formField";
+
+interface MaskedInputProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/**
+	 * The input mask: `9` accepts a digit, `L` a letter and `a` an
+	 * alphanumeric character; any other character is a literal shown as-is.
+	 * Use `\x` to escape a token character as a literal. e.g. "(999) 999-9999"
+	 */
+	mask: string;
+	/** The raw entered characters, without mask literals */
+	value?: Bindable<string>;
+	/** Text displayed when no value has been entered (defaults to the mask) */
+	placeholder?: string;
+	/** If set to true, the user cannot interact with this input */
+	disabled?: boolean;
+	/** An accessible name for the input */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when the value has changed */
+	onchange?: (value: string) => void;
+}
+
+/**
+ * An input that formats its contents as the user types -- phone numbers,
+ * credit cards, product codes -- displaying literals automatically while
+ * binding only the underlying characters.
+ *
+ * ```
+ * <MaskedInput mask="(999) 999-9999" &value={$state.phone} />
+ * <MaskedInput mask="LLL-9999" name="code" />
+ * ```
+ *
+ * Note that a complete value is not required: the bound value grows as the
+ * user types, so validate completeness with a schema when needed.
+ */
+export default function MaskedInput($props: MaskedInputProps | undefined) {
+	let input: HTMLInputElement;
+
+	const tokens = parseMask($props?.mask ?? "");
+
+	// Wire up the enclosing Form and Field, if any
+	const form = createFormField(
+		$props?.name,
+		$context[FormContextName] as FormContext | undefined,
+		$context[FieldContextName] as FieldContext | undefined,
+	);
+
+	function getDisabled(): boolean {
+		return $props?.disabled === true;
+	}
+
+	// The bound value is the raw entered characters, so the state key
+	// matches the prop name for $bind
+	let $state = $watch({
+		value: "",
+	});
+
+	$bind($state, $props, "value");
+
+	function display(): string {
+		return formatMask(tokens, $state.value ?? "");
+	}
+
+	function getPlaceholder(): string | undefined {
+		return $props?.placeholder ?? $props?.mask;
+	}
+
+	// Keep the element's text matching the formatted raw value; typing sets
+	// the property directly, so an attribute alone would not update it
+	function syncInput() {
+		if (input && !getDisabled() && input.value !== display()) {
+			input.value = display();
+		}
+	}
+	$run(() => {
+		if (!input) return;
+		const raw = $state.value ?? "";
+		const next = formatMask(tokens, raw);
+		if (input.value !== next) {
+			input.value = next;
+		}
+	});
+	$onmount(() => syncInput());
+
+	function handleInput(e: Event) {
+		if (getDisabled()) return;
+		const el = e.currentTarget as HTMLInputElement;
+
+		const raw = extractRaw(tokens, el.value);
+		if (raw !== $state.value) {
+			$state.value = raw;
+			form.handleInput();
+			$props?.onchange?.(raw);
+		}
+
+		// Rewrite the element so rejected characters disappear immediately
+		el.value = formatMask(tokens, raw);
+	}
+
+	function handleBlur() {
+		form.handleBlur();
+	}
+
+	@render {
+		<input
+			&ref={input}
+			id={$props?.id}
+			class={["torp-masked-input", $props?.class]}
+			{$props?.style}
+			type="text"
+			spellcheck="false"
+			autocomplete="off"
+			value={display()}
+			placeholder={getPlaceholder()}
+			disabled={getDisabled()}
+			tabindex={getDisabled() ? -1 : 0}
+			aria-label={$props?.ariaLabel}
+			data-valid={form.valid ? "valid" : "invalid"}
+			aria-describedby={form.messageId}
+			aria-invalid={form.inField && !form.valid ? "true" : undefined}
+			oninput={handleInput}
+			onblur={handleBlur}
+		/>
+
+		<FormValues name={form.name} value={$state.value || undefined} />
+	}
+}

package/dist/MaskedInput/index.d.ts

@@ -0,0 +1,52 @@
+import { type SlotRender } from "@torpor/view";
+
+
+interface MaskedInputProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/**
+	 * The input mask: `9` accepts a digit, `L` a letter and `a` an
+	 * alphanumeric character; any other character is a literal shown as-is.
+	 * Use `\x` to escape a token character as a literal. e.g. "(999) 999-9999"
+	 */
+	mask: string;
+	/** The raw entered characters, without mask literals */
+	value?: Bindable<string>;
+	/** Text displayed when no value has been entered (defaults to the mask) */
+	placeholder?: string;
+	/** If set to true, the user cannot interact with this input */
+	disabled?: boolean;
+	/** An accessible name for the input */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when the value has changed */
+	onchange?: (value: string) => void;
+}
+
+/**
+ * An input that formats its contents as the user types -- phone numbers,
+ * credit cards, product codes -- displaying literals automatically while
+ * binding only the underlying characters.
+ *
+ * ```
+ * <MaskedInput mask="(999) 999-9999" &value={$state.phone} />
+ * <MaskedInput mask="LLL-9999" name="code" />
+ * ```
+ *
+ * Note that a complete value is not required: the bound value grows as the
+ * user types, so validate completeness with a schema when needed.
+ */
+declare function MaskedInput(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: MaskedInputProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { MaskedInput };

package/dist/MaskedInput/index.js

@@ -0,0 +1,2 @@
+import MaskedInput from "./MaskedInput.torp";
+export { MaskedInput };

package/dist/Menu/Menu.torp

@@ -1,24 +1,17 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { ContextualContextName } from "../Contextual/ContextualTypes";
-import { ModalContextName } from "../Modal/ModalTypes";
-import { PopoverContextName, type PopoverContext } from "../Popover/PopoverTypes";
-import {
-	MenuContextName,
-	type MenuContext,
-	type ItemState,
-	MenuPopoutContextName,
-	type MenuPopoutContext
-} from "./MenuTypes";
+import { type PopoutContext, PopoutContextName } from "../utils/PopoutTypes";
+import { createFocusGroup } from "../utils/focusGroup";
+import { type ItemState, type MenuContext, MenuContextName } from "./MenuTypes";
 
 interface MenuProps {
 	/** 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,
+	ariaLabel?: string;
 }
 
 /**
@@ -41,85 +34,80 @@ interface MenuProps {
  */
 export default function Menu($props: MenuProps | undefined) {
 	// A collection containing the state and some functions for each item
-	let itemStates: ItemState[] = [];
-	let focusIndex = -1;
+	const group = createFocusGroup<ItemState>();
+	const { itemStates } = group;
 
-	// Get stuff out of the PopoverContext
-	// HACK: share state in PopupState and extend in context/modal/popover
-	const popoverContext = $context[ContextualContextName] ?? $context[ModalContextName] ?? $context[PopoverContextName] as PopoverContext;
-	if (!popoverContext) {
-		throw new Error("Menu must be contained within a Context, Modal or Popover");
+	// The text typed for type-ahead, which is reset after a short pause between key presses
+	let searchText = "";
+	let searchTimer: ReturnType<typeof setTimeout> | undefined;
+
+	// Get stuff out of the PopoutContext
+	const popoutContext = $context[PopoutContextName] as PopoutContext;
+	if (!popoutContext) {
+		throw new Error("Menu must be contained within a popout component");
 	}
-	const { setVisible, handleButton, visible } = popoverContext;
+	const { handleButton, state } = popoutContext;
 
-	// Check whether this is a menu in a popout
-	const popoutContext = $context[MenuPopoutContextName] as MenuPopoutContext;
-	const inPopout = !!popoutContext;
-	const setPopoutVisible = popoutContext?.setVisible;
+	const inPopout = state.contentRole === "menu";
+	state.contentRole = "menu";
 
 	// 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;
-	}
+	popoutContext.focusFirstElement = group.focusFirstItem;
+	popoutContext.focusLastElement = group.focusLastItem;
 
 	// Set the context to pass down to items
 	let context: MenuContext = {
-		setVisible,
 		handleButton,
 		handleItemFocus,
 		handleItemKey,
-		visible,
-		registerItem
+		handlePopout,
+		state,
+		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 registerItem(item: ItemState) {
+		return group.registerItem(item);
 	}
 
 	function handleItemFocus(index: number) {
-		focusIndex = index;
+		group.handleItemFocus(index);
 	}
 
 	function handleItemKey(e: KeyboardEvent) {
 		switch (e.key) {
-			case "Esc":
 			case "Escape": {
 				e.preventDefault();
-				setVisible(false);
+				state.visible = 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) {
+				if (popoutContext.navigateMenuBar) {
+					// In a menu under a menubar item: move to the previous item and open its menu
+					e.preventDefault();
+					popoutContext.navigateMenuBar("previous");
+				} else if (inPopout) {
+					// TODO: This should be based on what side the menu shows on
 					e.preventDefault();
-					setPopoutVisible(false);
+					state.visible = false;
+				}
+				break;
+			}
+			case "ArrowRight": {
+				if (popoutContext.navigateMenuBar) {
+					// In a menu under a menubar item: move to the next item and open its menu
+					e.preventDefault();
+					popoutContext.navigateMenuBar("next");
 				}
 				break;
 			}
@@ -133,29 +121,60 @@ export default function Menu($props: MenuProps | undefined) {
 				focusItem("end");
 				break;
 			}
-		}
-	}
-
-	function focusItem(target: "start" | "previous" | "next" | "end") {
-		switch (target) {
-			case "start": {
-				focusIndex = 0;
+			case "Tab": {
+				state.visible = false;
 				break;
 			}
-			case "previous": {
-				focusIndex = Math.max(0, focusIndex - 1);
+			default: {
+				// Type-ahead: typing a character focuses the next item whose label starts with it
+				if (e.key.length === 1 && e.key !== " ") {
+					e.preventDefault();
+					search(e.key);
+				}
 				break;
 			}
-			case "next": {
-				focusIndex = Math.min(itemStates.length - 1, focusIndex + 1);
-				break;
+		}
+	}
+
+	function search(key: string) {
+		const character = key.toLocaleLowerCase();
+		if (searchTimer) {
+			clearTimeout(searchTimer);
+			// Typing the same character repeatedly cycles through the items that
+			// start with it, instead of searching for a repeated-character string
+			if (searchText.length !== 1 || character !== searchText) {
+				searchText += character;
 			}
-			case "end": {
-				focusIndex = itemStates.length - 1;
+		} else {
+			searchText = character;
+		}
+		searchTimer = setTimeout(() => {
+			searchTimer = undefined;
+			searchText = "";
+		}, 1000);
+
+		// Focus the next item whose label starts with the search text, wrapping
+		// around to the start and skipping disabled items
+		for (let offset = 1; offset <= itemStates.length; offset++) {
+			const item = itemStates[(group.getFocusIndex() + offset) % itemStates.length];
+			if (!item.disabled && item.text?.toLocaleLowerCase().startsWith(searchText)) {
+				item.setFocused();
 				break;
 			}
 		}
-		itemStates[focusIndex]?.setFocused();
+	}
+
+	function focusItem(target: "start" | "previous" | "next" | "end") {
+		group.moveFocus(group.getFocusIndex(), target);
+	}
+
+	function handlePopout(index: number) {
+		// Hide all other submenus
+		for (let item of itemStates) {
+			if (item.index !== index) {
+				item.setVisible?.(false);
+			}
+		}
 	}
 
 	@render {
@@ -165,6 +184,7 @@ export default function Menu($props: MenuProps | undefined) {
 			{$props?.style}
 			tabindex="-1"
 			role="menu"
+			aria-labelledby={state.triggerId}
 			aria-label={$props?.ariaLabel}
 			aria-orientation="vertical"
 		>

package/dist/Menu/MenuButton.torp

@@ -1,21 +1,21 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { MenuContextName, type MenuContext } from "./MenuTypes";
+import { type ItemState, type MenuContext, MenuContextName } from "./MenuTypes";
 
 interface MenuButtonProps {
 	/** 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 value that should be returned when this button is pressed and the Dialog was invoked by calling showContextual, showPrompt or showPopover */
-	value?: any,
+	value?: any;
 	/** 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;
 }
 
 /**
@@ -33,7 +33,8 @@ export default function MenuButton($props: MenuButtonProps | undefined) {
 	const { registerItem, handleButton, handleItemKey, handleItemFocus } = menuContext;
 
 	// Register this item with the parent Menu and store the index
-	const { index } = registerItem(setFocused);
+	const item: ItemState = { setFocused, disabled: $props?.disabled };
+	const { index } = registerItem(item);
 
 	function handleKeyDown(e: KeyboardEvent) {
 		handleItemKey(e);
@@ -43,7 +44,7 @@ export default function MenuButton($props: MenuButtonProps | undefined) {
 	}
 
 	function handleClick(e: MouseEvent) {
-		handleButton($props?.value);
+		handleButton("confirm", $props?.value);
 		if ($props?.onclick) {
 			$props.onclick(e);
 		}
@@ -53,6 +54,11 @@ export default function MenuButton($props: MenuButtonProps | undefined) {
 		button.focus();
 	}
 
+	// Store the item's label for type-ahead
+	function handleMount(el: HTMLButtonElement) {
+		item.text = el.textContent.trim();
+	}
+
 	@render {
 		<button
 			{$props?.id}
@@ -61,11 +67,12 @@ export default function MenuButton($props: MenuButtonProps | undefined) {
 			type="button"
 			{$props?.disabled}
 			role="menuitem"
+			tabindex="-1"
 			aria-disabled={$props?.disabled ? "true" : undefined}
-			data-disabled={$props?.disabled ? "true" : undefined}
 			onkeydown={handleKeyDown}
 			onclick={handleClick}
 			onfocus={() => handleItemFocus(index)}
+			onmount={handleMount}
 			&ref={button}
 		>
 			<slot />