@torpor/ui 0.4.0 → 1.0.0

package/dist/ListBox/ListBoxTypes.ts

@@ -2,20 +2,38 @@ export const ListBoxContextName: unique symbol = Symbol.for("torp.ListBox");
 export const ListBoxItemContextName: unique symbol = Symbol.for("torp.ListBoxItem");
 
 export interface ListBoxContext {
-	/** Called from an ListBoxItem when it is added */
-	registerItem: (state: ItemState, setFocused: () => void) => void;
-	/** Called from an ListBoxItem when it is removed */
+	type: "single" | "multiple";
+	state: ListBoxState;
+	/** Called from a ListBoxItem when it is added */
+	registerItem: (state: ItemState) => void;
+	/** Called from a ListBoxItem when it is removed */
 	removeItem: (index: number) => void;
-	/** Called from an ListBoxItem when it is toggled */
+	/** Called from a ListBoxItem when it is toggled */
 	toggleItem: (value: string) => void;
-	/** Called from an ListBoxItem when it receives a keyboard event */
+	/** Called from a ListBoxItem when it receives a keyboard event */
 	handleKey: (index: number, e: KeyboardEvent) => void;
+	/** Called from a ListBoxItem when it receives focus */
+	setActiveDescendant?: (id: string) => void;
+	/** Reads the items loaded from the network loader, when one is set */
+	getLoadedItems?: () => any[];
+	/** Extracts the display text for a loaded item */
+	getItemLabel?: (item: any) => any;
+	/** Extracts the value for a loaded item */
+	getItemValue?: (item: any) => any;
+}
+
+export interface ListBoxState {
+	value: any;
 }
 
 export interface ItemState {
+	id: string;
 	index: number;
+	text: string;
 	value: any;
 	selected: boolean;
+	/** Used for styling when item has keyboard focus */
+	active: boolean;
 	disabled: boolean;
 	parentDisabled: boolean;
 	/** Called in the ListBox when an item needs to be focused */

package/dist/ListBox/LoadedListBoxItems.torp

@@ -0,0 +1,41 @@
+import ListBoxItem from "./ListBoxItem.torp";
+
+interface LoadedListBoxItemsProps {
+	/** The loaded items */
+	items: any[];
+	/** Extracts the display text for an item (defaults to `label ?? text ?? item`) */
+	getItemLabel?: (item: any) => any;
+	/** Extracts the value for an item (defaults to `value ?? id`) */
+	getItemValue?: (item: any) => any;
+}
+
+function defaultLabel(item: any): string {
+	const label = item?.label ?? item?.text ?? item;
+	return typeof label === "string" ? label : String(label);
+}
+
+function defaultValue(item: any): any {
+	return item?.value ?? item?.id;
+}
+
+/**
+ * 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.
+ */
+export default function LoadedListBoxItems($props?: LoadedListBoxItemsProps) {
+	const getLabel = $props?.getItemLabel ?? defaultLabel;
+	const getValue = $props?.getItemValue ?? defaultValue;
+
+	@render {
+		@for (let item of $props!.items) {
+			@key = getValue(item)
+			<ListBoxItem value={getValue(item)}>
+				{getLabel(item)}
+			</ListBoxItem>
+		}
+		@if ($props!.items.length === 0) {
+			<span class="torp-list-box-empty">No results.</span>
+		}
+	}
+}

package/dist/ListBox/index.d.ts

@@ -5,19 +5,39 @@ interface ListBoxProps {
 	/** 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;
 	/** Whether a single ListBoxItem or multiple ListBoxItems can be selected at the same time */
-	type?: "single" | "multiple",
+	type?: "single" | "multiple";
 	/** The value of the selected ListBoxItem, or an array of values if the type is "multiple" */
-	value?: any | any[],
+	value: Bindable<any | any[]>;
 	/** If set to true, the user cannot interact with any items in the ListBox */
-	disabled?: boolean,
+	disabled?: boolean;
 	/** An ARIA label for describing the ListBox to screen readers  */
-	ariaLabel?: string | undefined,
+	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 */
-	onchange?: (value: any | any[]) => void,
+	/** 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;
 }
 
 /**
@@ -48,17 +68,19 @@ interface ListBoxItemProps {
 	/** 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 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,
+	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,
+	value?: string;
 	/** If set to true, the user cannot interact with this ListBoxItem */
-	disabled?: boolean,
-	/** Raised when this item is opened or closed */
-	ontoggle?: (open: boolean) => void,
+	disabled?: boolean;
+	/** Raised when this item's selected state has changed */
+	onchange?: (selected: boolean) => void;
 }
 
 /**
@@ -78,9 +100,11 @@ interface ListBoxSeparatorProps {
 	/** 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 orientation of the separator */
+	orientation?: "vertical" | "horizontal";
 }
 
 /**
@@ -94,4 +118,19 @@ declare function ListBoxSeparator(
 	$slots?: Record<string, SlotRender>,
 ): void;
 
-export { ListBox, ListBoxItem, ListBoxSeparator };
+
+
+/**
+ * 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

@@ -1,14 +1,4 @@
-// src/ListBox/ListBox.torp
-import ListBox_default from "./ListBox.torp";
-
-// src/ListBox/ListBoxItem.torp
-import ListBoxItem_default from "./ListBoxItem.torp";
-
-// src/ListBox/ListBoxSeparator.torp
-import ListBoxSeparator_default from "./ListBoxSeparator.torp";
-export {
-  ListBox_default as ListBox,
-  ListBoxItem_default as ListBoxItem,
-  ListBoxSeparator_default as ListBoxSeparator
-};
-//# sourceMappingURL=index.js.map
+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,22 +1,17 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { PopoutContextName, type PopoutContext } from "../utils/PopoutTypes";
-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;
 }
 
 /**
@@ -39,92 +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
+	// 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, state } = popoutContext;
+	const { handleButton, state } = popoutContext;
 
-	// Check whether this is a menu in a popout
-	const menuPopoutContext = $context[MenuPopoutContextName] as MenuPopoutContext;
-	const inPopout = !!menuPopoutContext;
-	const setPopoutVisible = menuPopoutContext?.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
-	popoutContext.focusFirstElement = focusFirstElement;
-	if (menuPopoutContext) {
-		menuPopoutContext.focusFirstElement = focusFirstElement;
-		menuPopoutContext.focusLastElement = focusLastElement;
-	}
+	popoutContext.focusFirstElement = group.focusFirstItem;
+	popoutContext.focusLastElement = group.focusLastItem;
 
 	// Set the context to pass down to items
 	let context: MenuContext = {
-		setVisible,
 		handleButton,
 		handleItemFocus,
 		handleItemKey,
+		handlePopout,
 		state,
-		registerItem
+		registerItem,
 	};
 	$context[MenuContextName] = context;
 
-	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 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();
-					setPopoutVisible(false);
+					popoutContext.navigateMenuBar("previous");
+				} else if (inPopout) {
+					// TODO: This should be based on what side the menu shows on
+					e.preventDefault();
+					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;
 			}
@@ -138,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 {
@@ -170,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"
 		>