@torpor/ui 0.3.7 → 1.0.0

package/dist/ColorPicker/ColorPicker.torp

@@ -0,0 +1,157 @@
+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 { defaultPalette, parseHex } from "../utils/colorUtils";
+import createFormField from "../utils/formField";
+import ColorPalette from "./ColorPalette.torp";
+
+interface ColorPickerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The selected color as "#rrggbb"; undefined if nothing is selected */
+	value?: Bindable<string | undefined>;
+	/** The colors offered in the palette */
+	colors?: string[];
+	/**
+	 * If set to true, a text field for arbitrary hex values ("#ff8800") is
+	 * shown below the palette
+	 */
+	showInput?: boolean;
+	/** If set to true, the user cannot interact with this picker */
+	disabled?: boolean;
+	/** An accessible name for the picker */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when the color has changed or been cleared */
+	onchange?: (value: string | undefined) => void;
+}
+
+/**
+ * A color input: a ColorPalette with an optional hex text field, sharing a
+ * single bound value.
+ *
+ * ```
+ * <ColorPicker name="accent" showInput &value={$state.accent} />
+ * ```
+ */
+export default function ColorPicker($props: ColorPickerProps | undefined) {
+	let hexInput: HTMLInputElement;
+
+	// 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;
+	}
+
+	let $state = $watch({
+		value: undefined as string | undefined,
+
+		// Text while the hex input is being typed into; committed on blur or
+		// Enter, invalid text reverting like NumberInput
+		text: "",
+		editing: false,
+	});
+
+	$bind($state, $props, "value");
+
+	function handleSelect(value: string | undefined) {
+		$state.text = value ?? "";
+		form.handleInput();
+		$props?.onchange?.(value);
+	}
+
+	function commit() {
+		$state.editing = false;
+		const next = parseHex($state.text);
+		if ($state.text.trim() !== "" && !next) {
+			// Not a color: revert to the last committed value
+			$state.text = $state.value ?? "";
+			return;
+		}
+		if (next !== $state.value) {
+			$state.value = next;
+			form.handleInput();
+			$props?.onchange?.(next);
+		}
+		$state.text = $state.value ?? "";
+	}
+
+	function handleInput(e: Event) {
+		const el = e.currentTarget as HTMLInputElement;
+		$state.editing = true;
+		$state.text = el.value;
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		if (e.key === "Enter") {
+			e.preventDefault();
+			commit();
+		}
+	}
+
+	function handleChange() {
+		commit();
+	}
+
+	// Keep the input's value in sync with the text; typing sets the
+	// property directly, so an attribute alone would not update it
+	function syncInput() {
+		if (hexInput && !$state.editing && hexInput.value !== $state.text) {
+			hexInput.value = $state.text;
+		}
+	}
+	$run(() => {
+		const text = $state.text;
+		const editing = $state.editing;
+		if (hexInput && !editing && hexInput.value !== text) {
+			hexInput.value = text;
+		}
+	});
+	$onmount(() => syncInput());
+
+	@render {
+		<div class={["torp-color-picker", $props?.class]} {$props?.style}>
+			<ColorPalette
+				class="torp-color-picker-palette"
+				colors={$props?.colors ?? defaultPalette}
+				value={$state.value}
+				disabled={getDisabled()}
+				ariaLabel={$props?.ariaLabel}
+				onchange={handleSelect}
+			/>
+			@if ($props?.showInput) {
+				<input
+					&ref={hexInput}
+					type="text"
+					class="torp-color-picker-input"
+					spellcheck="false"
+					placeholder="#rrggbb"
+					aria-label={$props?.ariaLabel ? `${$props.ariaLabel} hex value` : "Hex value"}
+					value={$state.editing ? $state.text : $state.value ?? ""}
+					disabled={getDisabled()}
+					oninput={handleInput}
+					onchange={handleChange}
+					onblur={handleChange}
+					onkeydown={handleKey}
+				/>
+			}
+		</div>
+
+		<FormValues name={form.name} value={$state.value} />
+	}
+}

package/dist/ColorPicker/index.d.ts

@@ -0,0 +1,85 @@
+import { type SlotRender } from "@torpor/view";
+
+
+interface ColorPaletteProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The selected color as "#rrggbb"; undefined if nothing is selected */
+	value?: Bindable<string | undefined>;
+	/** The colors to offer (default: a built-in gray + hue palette) */
+	colors?: string[];
+	/** If set to true, the user cannot interact with this palette */
+	disabled?: boolean;
+	/** An accessible name for the palette */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when a color has been selected or deselected */
+	onchange?: (value: string | undefined) => void;
+}
+
+/**
+ * A grid of color swatches that behaves like a radio group: one swatch can
+ * be selected, clicking it again deselects, and the arrow keys move through
+ * the swatches selecting as they go.
+ *
+ * Use ColorPicker instead when arbitrary hex values should be enterable
+ * alongside the palette.
+ */
+declare function ColorPalette(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: ColorPaletteProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface ColorPickerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The selected color as "#rrggbb"; undefined if nothing is selected */
+	value?: Bindable<string | undefined>;
+	/** The colors offered in the palette */
+	colors?: string[];
+	/**
+	 * If set to true, a text field for arbitrary hex values ("#ff8800") is
+	 * shown below the palette
+	 */
+	showInput?: boolean;
+	/** If set to true, the user cannot interact with this picker */
+	disabled?: boolean;
+	/** An accessible name for the picker */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when the color has changed or been cleared */
+	onchange?: (value: string | undefined) => void;
+}
+
+/**
+ * A color input: a ColorPalette with an optional hex text field, sharing a
+ * single bound value.
+ *
+ * ```
+ * <ColorPicker name="accent" showInput &value={$state.accent} />
+ * ```
+ */
+declare function ColorPicker(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: ColorPickerProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { ColorPalette, ColorPicker };

package/dist/ColorPicker/index.js

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

package/dist/ComboBox/ComboBox.torp

@@ -0,0 +1,205 @@
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import $handle from "../utils/$handle";
+import {
+	type FieldContext,
+	FieldContextName,
+	type FormContext,
+	FormContextName,
+} from "../Form/FormTypes";
+import { type LoadResult, type Loader, createItemLoader } from "../utils/loader";
+import { type PopoutContext, PopoutContextName } from "../utils/PopoutTypes";
+import createFormField from "../utils/formField";
+import { type ComboBoxContext, ComboBoxContextName, type ComboBoxState } from "./ComboBoxTypes";
+import FormValues from "../Form/FormValues.torp";
+
+interface ComboBoxProps {
+	/** 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) as the user types,
+	 * receiving `{ searchText }`. 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;
+	/** An ARIA label for describing the input to screen readers when there is no associated label element */
+	ariaLabel?: string;
+	/** 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 ComboBox is:
+ *
+ * ```
+ * <ComboBox>
+ * 	<ComboBoxInput />
+ * 	<ComboBoxTrigger /> (optional)
+ * 	<ComboBoxContent />
+ * </ComboBox>
+ * ```
+ */
+export default function ComboBox($props: ComboBoxProps | 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: ComboBoxState = $watch({
+		visible: false,
+		value: $props?.value,
+		contentId: undefined,
+		triggerId: undefined,
+		contentRole: undefined,
+		activeDescendant: undefined,
+		searchText: undefined,
+	});
+
+	$bind($state, $props, "visible", "value");
+
+	if ($props?.load !== undefined && typeof $props.load !== "function") {
+		throw new Error("ComboBox: `load` must be a function");
+	}
+	const hasLoader = typeof $props?.load === "function";
+
+	// Load options from the network as the search text changes
+	const $load = hasLoader
+		? createItemLoader({
+				load: $props!.load!,
+				getRequest: () => ({ searchText: $state.searchText }),
+				onload: (r) => $props?.onload?.(r),
+			})
+		: undefined;
+
+	let result: any;
+
+	// Set the context to pass down to items
+	let context: ComboBoxContext = {
+		handleButton,
+		handleClickOutside,
+		get placeholder() {
+			return $props?.placeholder;
+		},
+		get required() {
+			return $props?.required;
+		},
+		get ariaLabel() {
+			return $props?.ariaLabel;
+		},
+		get name() {
+			return $props?.name;
+		},
+		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[ComboBoxContextName] = 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 input
+		if (type === "confirm") {
+			$state.visible = false;
+			if (context.focusInput) {
+				context.focusInput();
+			}
+		} else if (type === "cancel") {
+			$state.visible = false;
+		}
+	}
+
+	function handleClickOutside(e: MouseEvent | KeyboardEvent) {
+		e.preventDefault();
+		$state.visible = false;
+	}
+
+	@render {
+		<div {$props?.id} class={["torp-combo-box", $props?.class]} {$props?.style}>
+			<slot />
+		</div>
+
+		<FormValues name={form.name} value={$props?.value} />
+	}
+}

package/dist/ComboBox/ComboBoxContent.torp

@@ -0,0 +1,112 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { addDocumentEvent, removeDocumentEvent } from "../utils/documentEvents";
+import LoadedItems from "../utils/LoadedItems.torp";
+import { type ComboBoxContext, ComboBoxContextName } from "./ComboBoxTypes";
+
+interface ComboBoxContentProps {
+	/** 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 ComboBox when it is open, displayed
+ * alongside an element.
+ */
+export default function ComboBoxContent($props: ComboBoxContentProps | undefined) {
+	let div: HTMLDivElement;
+	let shown = false;
+	let closeOnClick = false;
+
+	// Get stuff out of the ComboBoxContext
+	const context = $context[ComboBoxContextName] as ComboBoxContext;
+	if (!context) {
+		throw new Error("ComboBoxContent must be contained within a ComboBox");
+	}
+	let $state = context.state;
+
+	$run(() => {
+		if ($state.visible) {
+			show();
+		} else {
+			hide();
+		}
+	});
+
+	function show() {
+		shown = true;
+
+		// HACK: Because this ComboBox 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);
+		addDocumentEvent("keydown", handleDocumentKeyDown);
+	}
+
+	function hide() {
+		if (!shown) return;
+
+		removeDocumentEvent("mousedown", handleDocumentMouseDown);
+		removeDocumentEvent("click", handleDocumentClick);
+		removeDocumentEvent("keydown", handleDocumentKeyDown);
+	}
+
+	function handleDocumentMouseDown() {
+		closeOnClick = true;
+	}
+
+	function handleDocumentClick(e: MouseEvent) {
+		// Don't close if the click is inside the content div OR inside the
+		// ComboBox root (which contains the input/trigger)
+		if (closeOnClick && div && !div.contains(e.target as HTMLElement) && !div.parentElement?.contains(e.target as HTMLElement)) {
+			e.preventDefault();
+			context.handleClickOutside!(e);
+		}
+	}
+
+	function handleDocumentKeyDown(e: KeyboardEvent) {
+		if (e.key === "Escape") {
+			e.preventDefault();
+			$state.visible = false;
+		}
+	}
+
+	// HACK: We need to keep the items in the document so that we can search through them
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-combo-box-content", $props?.class]}
+			{$props?.style}
+			hidden={!$state.visible}
+			aria-hidden={$state.visible ? undefined : "true"}
+			&ref={div}
+		>
+			<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-combo-box-loading">Loading…</span>
+						}
+					} catch (err) {
+						<span class="torp-combo-box-error" role="alert">
+							{err instanceof Error ? err.message : String(err)}
+						</span>
+					}
+				}
+			</slot>
+		</div>
+	}
+}

package/dist/ComboBox/ComboBoxInput.torp

@@ -0,0 +1,145 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import getId from "../utils/getId";
+import { type ComboBoxContext, ComboBoxContextName } from "./ComboBoxTypes";
+
+interface ComboBoxInputProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+
+	// TODO: Get these from the parent
+	/** The name of the input's form data field */
+	name?: string;
+	/** The value displayed in the input */
+	value?: any;
+	/** Text to display when the input value is empty */
+	placeholder?: string;
+	/** Whether the input's value is required */
+	required?: boolean;
+
+	/** An ARIA label for describing the input to screen readers when there is no associated label element */
+	ariaLabel?: string;
+	/** Raised on change */
+	onchange?: (e: Event) => void;
+	/** Raised on input */
+	oninput?: (e: InputEvent) => void;
+}
+
+/**
+ * The input that causes a ComboBox to appear or disappear.
+ */
+export default function ComboBoxInput($props: ComboBoxInputProps | undefined) {
+	let defaultId = getId();
+	let input: HTMLInputElement;
+
+	// Get stuff out of the ComboBoxContext
+	const context = $context[ComboBoxContextName] as ComboBoxContext;
+	if (!context) {
+		throw new Error("ComboBoxInput must be contained within a ComboBox");
+	}
+	let $state = context.state;
+	context.focusInput = focusInput;
+
+	// Set the trigger ID so that it can be used with aria-labelledby
+	$state.triggerId = $props?.id ?? defaultId;
+
+	function focusInput() {
+		input.focus();
+	}
+
+	function handleClick() {
+		$state.visible = true;
+	}
+
+	function handleInput(e: InputEvent) {
+		if (context.getLoadedItems) {
+			// Loaded from a network loader: refetch with the current text
+			$state.searchText = input.value;
+			$state.visible = true;
+		} else if (context.searchItems) {
+			context.searchText = input.value;
+			const found = context.searchItems(context.searchText);
+			if (found !== undefined) {
+				$state.visible = true;
+				$state.activeDescendant = found.id;
+				if (context.markElement) {
+					context.markElement(found.id);
+				}
+			}
+		}
+
+		if ($props?.oninput) {
+			$props.oninput(e);
+		}
+	}
+
+	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 "Enter": {
+				if ($state.visible) {
+					e.preventDefault();
+					if (context.selectMarkedElement) {
+						context.selectMarkedElement();
+					}
+					$state.visible = false;
+				}
+				break;
+			}
+			case "Escape": {
+				if ($state.visible) {
+					e.preventDefault();
+					$state.visible = false;
+				}
+				break;
+			}
+		}
+	}
+
+	@render {
+		<input
+			role="combobox"
+			aria-autocomplete="list"
+			id={$props?.id ?? defaultId}
+			class={["torp-combo-box-input", $props?.class]}
+			{$props?.style}
+			name={$props?.name !== undefined ? $props.name : context.name}
+			&value={Array.isArray($state.value) ? $state.value.join(", ") : $state.value}
+			placeholder={$props?.placeholder !== undefined ? $props.placeholder : context.placeholder}
+			required={$props?.required !== undefined ? $props.required : context.required}
+			aria-readonly
+			aria-controls={$state.contentId}
+			aria-haspopup={$state.contentRole}
+			aria-activedescendant={$state.activeDescendant}
+			aria-expanded={$state.visible ? "true" : "false"}
+			aria-label={$props?.ariaLabel !== undefined ? $props.ariaLabel : context.ariaLabel}
+			data-valid={context.valid?.() ? "valid" : "invalid"}
+			aria-describedby={context.messageId?.()}
+			aria-invalid={context.inField?.() && !context.valid?.() ? "true" : undefined}
+			onblur={() => context.handleBlur?.()}
+			{$props?.onchange}
+			onclick={handleClick}
+			oninput={handleInput}
+			onkeydown={handleKey}
+			&ref={input}
+		/>
+	}
+}