@torpor/ui 0.4.0 → 1.0.0

package/dist/SegmentedControl/SegmentedItem.torp

@@ -0,0 +1,78 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { type SegmentedControlContext, SegmentedControlContextName } from "./SegmentedControlTypes";
+
+interface SegmentedItemProps {
+	/** 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 */
+	index?: number;
+	/** The value for this item */
+	value?: string;
+	/** If set to true, the user cannot interact with this item */
+	disabled?: boolean;
+}
+
+/**
+ * A segment in a SegmentedControl, one of which is always active.
+ */
+export default function SegmentedItem($props: SegmentedItemProps | undefined) {
+	let button: HTMLButtonElement;
+
+	// Get stuff out of the SegmentedControl context
+	const context = $context[SegmentedControlContextName] as SegmentedControlContext;
+	if (!context) {
+		throw new Error("SegmentedItem must be contained within a SegmentedControl");
+	}
+
+	// Register this item with the parent SegmentedControl
+	let $state = context.registerItem($props?.index, $props?.value, $props?.disabled);
+
+	$run(() => {
+		return () => {
+			context.removeItem($state.index);
+		};
+	});
+
+	// This function is called by the parent SegmentedControl to focus this item
+	function setFocused() {
+		button.focus();
+	}
+	$state.setFocused = setFocused;
+
+	function getDisabled(): boolean {
+		return $state.disabled || $state.parentDisabled;
+	}
+
+	function handleClick() {
+		if (getDisabled()) return;
+		context.triggerItem($state.value);
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		if (getDisabled()) return;
+		context.handleItemKey($state.index, e);
+	}
+
+	@render {
+		<button
+			type="button"
+			{$props?.id}
+			class={["torp-segmented-item", $props?.class]}
+			{$props?.style}
+			role="radio"
+			tabindex={$state.active ? 0 : -1}
+			aria-checked={$state.active ? "true" : "false"}
+			aria-disabled={getDisabled() ? "true" : undefined}
+			data-state={$state.active ? "active" : "inactive"}
+			onclick={handleClick}
+			onkeydown={handleKey}
+			&ref={button}
+		>
+			<slot />
+		</button>
+	}
+}

package/dist/SegmentedControl/index.d.ts

@@ -0,0 +1,74 @@
+import { type SlotRender } from "@torpor/view";
+
+
+interface SegmentedControlProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The value of the active segment */
+	value?: Bindable<string | undefined>;
+	/** If set to true, the user cannot interact with any segments */
+	disabled?: boolean;
+	/** An accessible name for the control */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when the active segment has changed */
+	onchange?: (value: string) => void;
+}
+
+/**
+ * A compact group of segments, of which exactly one is active. The user moves
+ * between segments with the arrow keys, or selects one directly.
+ *
+ * See [the WAI ARIA guidelines for Radio Groups](https://www.w3.org/WAI/ARIA/apg/patterns/radiogroup/).
+ *
+ * The structure of a SegmentedControl is:
+ *
+ * ```
+ * <SegmentedControl ariaLabel="View">
+ * 	<SegmentedItem value="day">Day</SegmentedItem>
+ * 	<SegmentedItem value="week">Week</SegmentedItem>
+ * </SegmentedControl>
+ * ```
+ */
+declare function SegmentedControl(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: SegmentedControlProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface SegmentedItemProps {
+	/** 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 */
+	index?: number;
+	/** The value for this item */
+	value?: string;
+	/** If set to true, the user cannot interact with this item */
+	disabled?: boolean;
+}
+
+/**
+ * A segment in a SegmentedControl, one of which is always active.
+ */
+declare function SegmentedItem(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: SegmentedItemProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { SegmentedControl, SegmentedItem };

package/dist/SegmentedControl/index.js

@@ -0,0 +1,3 @@
+import SegmentedControl from "./SegmentedControl.torp";
+import SegmentedItem from "./SegmentedItem.torp";
+export { SegmentedControl, SegmentedItem };

package/dist/SelectBox/SelectBox.torp

@@ -1,26 +1,54 @@
-import type { ClassValue, StyleValue } from "@torpor/view";
-import { SelectBoxContextName, type SelectBoxContext, type SelectBoxState } from "./SelectBoxTypes";
-import { PopoutContextName, type PopoutContext } from "../utils/PopoutTypes";
+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,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
-	/** The data value selected by the user */
-	value?: any,
-	/** Whether the popout is visible  */
-	visible?: boolean,
-	/** A function to be called when the user selects a response */
-	callback?: ((value: any) => void),
-	/** Raised when the popout is opened or closed */
-	ontoggle?: (open: boolean) => void,
+	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,
+	onopen?: () => void;
 	/** Raised when the popout has closed */
-	onclose?: (result: any) => void,
+	onclose?: (result: any) => void;
 }
 
 /**
@@ -32,28 +60,42 @@ interface SelectBoxProps {
  *
  * ```
  * <SelectBox>
- * 	<SelectBoxInput />
- * 	<SelectBoxTrigger /> (optional)
+ * 	<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,
 	});
 
-	// Sync props and state
-	$run(() => {
-		$state.visible = $props?.visible ?? false;
-	});
-	$run(() => {
-		if ($props !== undefined) {
-			$props.visible = $state.visible;
-			$props.value = $state.value;
-		}
-	});
+	$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;
 
@@ -61,7 +103,20 @@ export default function SelectBox($props: SelectBoxProps | undefined) {
 	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;
 
@@ -69,22 +124,23 @@ export default function SelectBox($props: SelectBoxProps | undefined) {
 	let popoutContext: PopoutContext = context;
 	$context[PopoutContextName] = popoutContext;
 
-	// Dispatch the toggle event when the popout is opened or closed
-	let firstToggle = true;
-	$run(() => {
-		const ontoggle = $props?.ontoggle;
-		const onopen = $props?.onopen;
-		const onclose = $props?.onclose;
+	// 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 (firstToggle) {
-			firstToggle = false;
+		if (first) return;
+		if (visible) {
+			$props?.onopen?.();
 		} else {
-			if (ontoggle) ontoggle(visible);
-			if (visible) {
-				if (onopen) onopen()
-			} else {
-				if (onclose) onclose(result);
-			}
+			$props?.onclose?.(result);
 		}
 	});
 
@@ -110,27 +166,25 @@ export default function SelectBox($props: SelectBoxProps | undefined) {
 			$state.value = result;
 		}
 
-		// Hide the popout
-		$state.visible = false;
-
-		// Call the callback
-		if ($props?.callback) {
-			$props?.callback(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) {
+	function handleClickOutside(e: MouseEvent | KeyboardEvent) {
 		e.preventDefault();
 		$state.visible = false;
 	}
 
 	@render {
-		<div
-			{$props?.id}
-			class={["torp-select-box", $props?.class]}
-			{$props?.style}
-		>
+		<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

@@ -1,14 +1,15 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
 import { addDocumentEvent, removeDocumentEvent } from "../utils/documentEvents";
-import { SelectBoxContextName, type SelectBoxContext } from "./SelectBoxTypes";
+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,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
+	style?: StyleValue;
 }
 
 /**
@@ -33,7 +34,7 @@ export default function SelectBoxContent($props: SelectBoxContentProps | undefin
 		}
 	});
 
-	function show() {
+	function show(_: HTMLElement) {
 		shown = true;
 
 		// HACK: Because this SelectBox could be shown with a click, we need to wait for another mousedown
@@ -55,27 +56,52 @@ export default function SelectBoxContent($props: SelectBoxContentProps | undefin
 	}
 
 	function handleDocumentClick(e: MouseEvent) {
-		if (
-			closeOnClick &&
-			div &&
-			!div.contains(e.target as HTMLElement)
-		) {
+		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]}
-				{$props?.style}
-				&ref={div}
-				onmount={show}
-			>
-				<slot />
-			</div>
+		@//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

@@ -1,41 +1,141 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { SelectBoxContextName, type SelectBoxContext } from "./SelectBoxTypes";
+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,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
+	style?: StyleValue;
+	/** An ARIA label for describing the trigger to screen readers when there is no associated label element */
+	ariaLabel?: string;
 }
 
 /**
- * The button that causes a SelectBox to appear or disappear.
+ * 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"
-			{$props?.id}
+			role="combobox"
+			id={$props?.id ?? defaultId}
 			class={["torp-select-box-trigger", $props?.class]}
 			{$props?.style}
-			tabindex="-1"
+			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}
-			&ref={context.anchorElement}
+			onkeydown={handleKey}
+			&ref={button}
 		>
-			<slot />
+			<slot>
+				@if (displayValue()) {
+					<span>{displayValue()}</span>
+				} @else {
+					<span>{context.placeholder || "-"}</span>
+				}
+			</slot>
 		</button>
 	}
 }

package/dist/SelectBox/SelectBoxTypes.ts

@@ -1,18 +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 modal components (Contextual, Prompt and SelectBox) */
-export interface SelectBoxContext {
-	handleButton: (type: "confirm" | "cancel" | undefined, value?: any) => void;
-	// HACK: We need to be able to let children (i.e. Dialogs) override the click outside functionality
-	// There may be a more elegant way to accomplish this too
-	handleClickOutside?: (e: MouseEvent) => void;
+/** The shared context for SelectBox components */
+export interface SelectBoxContext extends PopoutContext {
+	placeholder?: string;
+	multiple?: boolean;
 	state: SelectBoxState;
-	focusFirstElement?: () => void;
-	focusLastElement?: () => void;
+	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 {
-	visible: boolean;
+export interface SelectBoxState extends PopoutState {
 	value: any;
-	contentId?: string;
+	name?: string;
 }
+
+export type { LoadResult, Loader };