@torpor/ui 0.3.7 → 1.0.0

package/dist/SelectBox/SelectBox.torp

@@ -0,0 +1,190 @@
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import $handle from "../utils/$handle";
+import {
+	type FieldContext,
+	FieldContextName,
+	type FormContext,
+	FormContextName,
+} from "../Form/FormTypes";
+import FormValues from "../Form/FormValues.torp";
+import { type LoadResult, type Loader, createItemLoader } from "../utils/loader";
+import { type PopoutContext, PopoutContextName } from "../utils/PopoutTypes";
+import createFormField from "../utils/formField";
+import { type SelectBoxContext, SelectBoxContextName, type SelectBoxState } from "./SelectBoxTypes";
+
+interface SelectBoxProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The name of the input's form data field */
+	name?: string;
+	/** The data value selected by the user, or an array of values if multiple is set */
+	value: Bindable<any>;
+	/** Whether multiple values can be selected at the same time */
+	multiple?: boolean;
+	/**
+	 * Reads options from the network (or anywhere async) when the box is
+	 * shown. When set and no content is 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;
+	/** Text to display when the input value is empty */
+	placeholder?: string;
+	///** Whether the input's value is required */
+	//required?: boolean,
+	/** Whether the popout is visible; only bind this to control it from outside */
+	visible?: Bindable<boolean | undefined>;
+	/** Raised when the value has changed */
+	onchange?: (value: any) => void;
+	/** Raised when the popout has opened */
+	onopen?: () => void;
+	/** Raised when the popout has closed */
+	onclose?: (result: any) => void;
+}
+
+/**
+ * An input box for selecting a value from a popout ListBox or Dialog.
+ *
+ * See [the WAI ARIA guidelines for ComboBoxes](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
+ *
+ * The structure of a SelectBox is:
+ *
+ * ```
+ * <SelectBox>
+ * 	<SelectBoxTrigger />
+ * 	<SelectBoxContent />
+ * </SelectBox>
+ * ```
+ */
+export default function SelectBox($props: SelectBoxProps | undefined) {
+	// Wire up the enclosing Form and Field, if any
+	const form = createFormField(
+		$props?.name,
+		$context[FormContextName] as FormContext | undefined,
+		$context[FieldContextName] as FieldContext | undefined,
+	);
+
+	let $state: SelectBoxState = $watch({
+		visible: false,
+		value: $props?.value,
+		contentId: undefined,
+		triggerId: undefined,
+		contentRole: undefined,
+	});
+
+	$bind($state, $props, "visible", "value");
+
+	if ($props?.load !== undefined && typeof $props.load !== "function") {
+		throw new Error("SelectBox: `load` must be a function");
+	}
+	const hasLoader = typeof $props?.load === "function";
+
+	// Load options from the network (lazily, on first read)
+	const $load = hasLoader
+		? createItemLoader({
+				load: $props!.load!,
+				getRequest: () => ({}),
+				onload: (r) => $props?.onload?.(r),
+			})
+		: undefined;
+
+	let result: any;
+
+	// Set the context to pass down to items
+	let context: SelectBoxContext = {
+		handleButton,
+		handleClickOutside,
+		get placeholder() {
+			return $props?.placeholder;
+		},
+		get multiple() {
+			return $props?.multiple === true;
+		},
+		inField: () => form.inField,
+		valid: () => form.valid,
+		messageId: () => form.messageId,
+		handleBlur: () => form.handleBlur(),
+		state: $state,
+		getLoadedItems: $load ? () => $load.items : undefined,
+		getItemLabel: $props?.getItemLabel,
+		getItemValue: $props?.getItemValue,
+	};
+	$context[SelectBoxContextName] = context;
+
+	// Set the context to pass down to items
+	let popoutContext: PopoutContext = context;
+	$context[PopoutContextName] = popoutContext;
+
+	// Dispatch the change event when the value changes
+	$handle((first) => {
+		const value = $state.value;
+		if (!first) {
+			form.handleInput();
+			$props?.onchange?.(value);
+		}
+	});
+
+	// Dispatch the open/close events when the popout is opened or closed
+	$handle((first) => {
+		const visible = $state.visible;
+		if (first) return;
+		if (visible) {
+			$props?.onopen?.();
+		} else {
+			$props?.onclose?.(result);
+		}
+	});
+
+	function handleButton(type: "confirm" | "cancel" | undefined, value?: any) {
+		// Get the button's result
+		switch (type) {
+			case "confirm": {
+				result = value ?? true;
+				break;
+			}
+			case "cancel": {
+				result = value ?? false;
+				break;
+			}
+			default: {
+				result = value;
+				break;
+			}
+		}
+
+		// Update the value
+		if (type !== "cancel") {
+			$state.value = result;
+		}
+
+		// Hide the popout and focus the button
+		if (type === "confirm" || type === "cancel") {
+			$state.visible = false;
+			if (context.focusTrigger) {
+				context.focusTrigger();
+			}
+		}
+	}
+
+	function handleClickOutside(e: MouseEvent | KeyboardEvent) {
+		e.preventDefault();
+		$state.visible = false;
+	}
+
+	@render {
+		<div {$props?.id} class={["torp-select-box", $props?.class]} {$props?.style}>
+			<slot />
+		</div>
+
+		<FormValues name={form.name} value={$state.value} />
+	}
+}

package/dist/SelectBox/SelectBoxContent.torp

@@ -0,0 +1,107 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { addDocumentEvent, removeDocumentEvent } from "../utils/documentEvents";
+import LoadedItems from "../utils/LoadedItems.torp";
+import { type SelectBoxContext, SelectBoxContextName } from "./SelectBoxTypes";
+
+interface SelectBoxContentProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+}
+
+/**
+ * The content that is displayed for a SelectBox when it is open, displayed
+ * alongside an element.
+ */
+export default function SelectBoxContent($props: SelectBoxContentProps | undefined) {
+	let div: HTMLDivElement;
+	let shown = false;
+	let closeOnClick = false;
+
+	// Get stuff out of the SelectBoxContext
+	const context = $context[SelectBoxContextName] as SelectBoxContext;
+	if (!context) {
+		throw new Error("SelectBoxContent must be contained within a SelectBox");
+	}
+	let $state = context.state;
+
+	$run(() => {
+		if (!$state.visible) {
+			hide();
+		}
+	});
+
+	function show(_: HTMLElement) {
+		shown = true;
+
+		// HACK: Because this SelectBox 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
+		closeOnClick = false;
+		addDocumentEvent("mousedown", handleDocumentMouseDown);
+		addDocumentEvent("click", handleDocumentClick);
+	}
+
+	function hide() {
+		if (!shown) return;
+
+		removeDocumentEvent("mousedown", handleDocumentMouseDown);
+		removeDocumentEvent("click", handleDocumentClick);
+	}
+
+	function handleDocumentMouseDown() {
+		closeOnClick = true;
+	}
+
+	function handleDocumentClick(e: MouseEvent) {
+		if (closeOnClick && div && !div.contains(e.target as HTMLElement)) {
+			e.preventDefault();
+			context.handleClickOutside!(e);
+		}
+	}
+
+	// HACK: We need to keep the items in the document so that we can search through them
+	@render {
+		@//if ($state.visible) {
+		<div
+			{$props?.id}
+			class={["torp-select-box-content", $props?.class, $state.visible ? undefined : "hidden"]}
+			{$props?.style}
+			aria-hidden={$state.visible ? undefined : "true"}
+			&ref={div}
+			onmount={show}
+		>
+			<slot>
+				@if (context.getLoadedItems) {
+					@// Options loaded from a network loader, rendered automatically
+					@try {
+						@await {
+							<LoadedItems
+								items={context.getLoadedItems!()}
+								value={$state.value}
+								multiple={context.multiple}
+								getItemLabel={context.getItemLabel}
+								getItemValue={context.getItemValue}
+							/>
+						} with {
+							<span class="torp-select-box-loading">Loading…</span>
+						}
+					} catch (err) {
+						<span class="torp-select-box-error" role="alert">
+							{err instanceof Error ? err.message : String(err)}
+						</span>
+					}
+				}
+			</slot>
+		</div>
+		@//}
+	}
+
+	@style {
+		.torp-select-box-content.hidden {
+			display: none;
+		}
+	}
+}

package/dist/SelectBox/SelectBoxTrigger.torp

@@ -0,0 +1,141 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import getId from "../utils/getId";
+import { type SelectBoxContext, SelectBoxContextName } from "./SelectBoxTypes";
+
+interface SelectBoxTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** An ARIA label for describing the trigger to screen readers when there is no associated label element */
+	ariaLabel?: string;
+}
+
+/**
+ * The input that causes a SelectBox to appear or disappear.
+ */
+export default function SelectBoxTrigger($props: SelectBoxTriggerProps | undefined) {
+	let defaultId = getId();
+	let button: HTMLButtonElement;
+
+	// Get stuff out of the SelectBoxContext
+	const context = $context[SelectBoxContextName] as SelectBoxContext;
+	if (!context) {
+		throw new Error("SelectBoxTrigger must be contained within a SelectBox");
+	}
+	let $state = context.state;
+	context.focusTrigger = focusTrigger;
+
+	// Set the trigger ID so that it can be used with aria-labelledby
+	$state.triggerId = $props?.id ?? defaultId;
+
+	function focusTrigger() {
+		button.focus();
+	}
+
+	function displayValue(): string | undefined {
+		const value = $state.value;
+		if (value === undefined || value === null || value === "") {
+			return undefined;
+		}
+		return Array.isArray(value) ? (value as any[]).join(", ") : String(value);
+	}
+
+	function handleClick() {
+		$state.visible = !$state.visible;
+		if (!$state.visible) {
+			context.searchText = "";
+		}
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		switch (e.key) {
+			case "ArrowDown": {
+				e.preventDefault();
+				$state.visible = true;
+				if (context.focusFirstElement) {
+					context.focusFirstElement();
+				}
+				break;
+			}
+			case "ArrowUp": {
+				e.preventDefault();
+				$state.visible = true;
+				if (context.focusLastElement) {
+					context.focusLastElement();
+				}
+				break;
+			}
+			case "Escape": {
+				if ($state.visible) {
+					e.preventDefault();
+					// NOTE: This may be too much of a departure from standards
+					if (context.searchText !== undefined && context.searchText !== "") {
+						context.searchText = "";
+					} else {
+						$state.visible = false;
+					}
+				}
+				break;
+			}
+			case "Backspace": {
+				if (context.searchText && context.searchItems) {
+					e.preventDefault();
+					const shorten = (str: string) => str.substring(0, str.length - 1);
+					context.searchText = shorten(context.searchText!);
+					if (context.searchText.length > 0) {
+						const found = context.searchItems(context.searchText);
+						if (found) {
+							found.setFocused();
+						}
+					}
+				}
+				break;
+			}
+			default: {
+				// TODO: Handle unicode
+				if (e.key.length === 1 && context.searchItems) {
+					e.preventDefault();
+					context.searchText ??= "";
+					context.searchText += e.key;
+					const found = context.searchItems(context.searchText);
+					if (found !== undefined) {
+						$state.visible = true;
+						found.setFocused();
+					}
+				}
+			}
+		}
+	}
+
+	@render {
+		<button
+			type="button"
+			role="combobox"
+			id={$props?.id ?? defaultId}
+			class={["torp-select-box-trigger", $props?.class]}
+			{$props?.style}
+			aria-controls={$state.contentId}
+			aria-haspopup={$state.contentRole}
+			aria-expanded={$state.visible ? "true" : "false"}
+			aria-label={$props?.ariaLabel}
+			data-valid={context.valid?.() ? "valid" : "invalid"}
+			aria-describedby={context.messageId?.()}
+			aria-invalid={context.inField?.() && !context.valid?.() ? "true" : undefined}
+			onblur={() => context.handleBlur?.()}
+			onclick={handleClick}
+			onkeydown={handleKey}
+			&ref={button}
+		>
+			<slot>
+				@if (displayValue()) {
+					<span>{displayValue()}</span>
+				} @else {
+					<span>{context.placeholder || "-"}</span>
+				}
+			</slot>
+		</button>
+	}
+}

package/dist/SelectBox/SelectBoxTypes.ts

@@ -0,0 +1,33 @@
+import { type PopoutContext, type PopoutState } from "../utils/PopoutTypes";
+import { type LoadResult, type Loader } from "../utils/loader";
+
+export const SelectBoxContextName: unique symbol = Symbol.for("torp.SelectBox");
+
+/** The shared context for SelectBox components */
+export interface SelectBoxContext extends PopoutContext {
+	placeholder?: string;
+	multiple?: boolean;
+	state: SelectBoxState;
+	focusTrigger?: () => void;
+	/** Whether the component is contained within a Form Field */
+	inField?: () => boolean;
+	/** Whether the Field's value is valid, for data-valid / aria-invalid */
+	valid?: () => boolean;
+	/** The ID of the Field's Message component, for aria-describedby */
+	messageId?: () => string | undefined;
+	/** Called by the trigger when it loses focus, to run Field validation */
+	handleBlur?: () => void;
+	/** Returns 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 SelectBoxState extends PopoutState {
+	value: any;
+	name?: string;
+}
+
+export type { LoadResult, Loader };

package/dist/SelectBox/index.d.ts

@@ -0,0 +1,112 @@
+import { type SlotRender } from "@torpor/view";
+
+
+interface SelectBoxProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The name of the input's form data field */
+	name?: string;
+	/** The data value selected by the user, or an array of values if multiple is set */
+	value: Bindable<any>;
+	/** Whether multiple values can be selected at the same time */
+	multiple?: boolean;
+	/**
+	 * Reads options from the network (or anywhere async) when the box is
+	 * shown. When set and no content is 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;
+	/** Text to display when the input value is empty */
+	placeholder?: string;
+	///** Whether the input's value is required */
+	//required?: boolean,
+	/** Whether the popout is visible; only bind this to control it from outside */
+	visible?: Bindable<boolean | undefined>;
+	/** Raised when the value has changed */
+	onchange?: (value: any) => void;
+	/** Raised when the popout has opened */
+	onopen?: () => void;
+	/** Raised when the popout has closed */
+	onclose?: (result: any) => void;
+}
+
+/**
+ * An input box for selecting a value from a popout ListBox or Dialog.
+ *
+ * See [the WAI ARIA guidelines for ComboBoxes](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
+ *
+ * The structure of a SelectBox is:
+ *
+ * ```
+ * <SelectBox>
+ * 	<SelectBoxTrigger />
+ * 	<SelectBoxContent />
+ * </SelectBox>
+ * ```
+ */
+declare function SelectBox(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: SelectBoxProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface SelectBoxContentProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+}
+
+/**
+ * The content that is displayed for a SelectBox when it is open, displayed
+ * alongside an element.
+ */
+declare function SelectBoxContent(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: SelectBoxContentProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface SelectBoxTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** An ARIA label for describing the trigger to screen readers when there is no associated label element */
+	ariaLabel?: string;
+}
+
+/**
+ * The input that causes a SelectBox to appear or disappear.
+ */
+declare function SelectBoxTrigger(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: SelectBoxTriggerProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { SelectBox, SelectBoxContent, SelectBoxTrigger };

package/dist/SelectBox/index.js

@@ -0,0 +1,5 @@
+import { n as normalizeLoadResult, t as createItemLoader } from "../loader-DEeG5vFY.js";
+import SelectBox from "./SelectBox.torp";
+import SelectBoxContent from "./SelectBoxContent.torp";
+import SelectBoxTrigger from "./SelectBoxTrigger.torp";
+export { SelectBox, SelectBoxContent, SelectBoxTrigger, createItemLoader, normalizeLoadResult };