@torpor/ui 0.3.7 → 1.0.0

package/dist/utils/focusGroup.ts

@@ -0,0 +1,204 @@
+import { $watch } from "@torpor/view";
+import { focusItem, type FocusTarget } from "./focusItem";
+
+/**
+ * A managed collection of focusable items with roving tabindex semantics,
+ * for group-style components where tabbing into the group lands on one item
+ * (the tab stop) and arrow keys move focus within it (ToolBar, MenuBar,
+ * button groups, Rating, SegmentedControl...).
+ *
+ * Owns the registration ledger (indexed states, ordered add/remove) that
+ * every list-like component duplicates today, plus the focus bookkeeping:
+ * `focusIndex` tracking via onItemFocus, first-item focus when the group
+ * itself takes focus, and keyboard movement over enabled items through
+ * utils/focusItem.
+ *
+ * Items are plain states carrying an index, a setFocused implementation and
+ * a disabled flag; each component renders its own elements and wires
+ * onfocus/onkeydown to the returned handlers.
+ */
+export interface FocusItemState {
+	/** Assigned by the group in registration order */
+	index?: number;
+	/** Focuses this item's element; implemented by the component's item */
+	setFocused: () => void;
+	/** Disabled items are skipped by movement */
+	disabled?: boolean;
+}
+
+export interface FocusGroup<T extends FocusItemState> {
+	/** The registered item states, in order */
+	itemStates: T[];
+
+	/** Adds an item state, assigning its index from position; returns it */
+	registerItem: (item: T) => { index: number };
+
+	/** Removes an item by index, reindexing the rest */
+	removeItem: (itemIndex: number) => void;
+
+	/**
+	 * Item onfocus handler: records the current tab stop
+	 */
+	handleItemFocus: (index: number) => void;
+
+	/**
+	 * Group-level key handler for a directional press at `index`. Handles
+	 * left/right (+up/down when vertical), Home and End; arrow keys depend
+	 * on orientation, matching ToolBar behavior.
+	 */
+	handleGroupKey: (index: number, e: KeyboardEvent, options?: { vertical?: boolean }) => boolean;
+
+	/** Moves focus from `index` to the target item (disabled items skipped) */
+	moveFocus: (index: number, target: FocusTarget) => void;
+
+	/** Focuses the first / last enabled item (popout open behavior) */
+	focusFirstItem: () => void;
+	focusLastItem: () => void;
+
+	/**
+	 * Whether any item is the current tab stop; components derive their
+	 * per-item tabindex from this plus the tracked focus index
+	 */
+	getFocusIndex: () => number;
+
+	/**
+	 * Whether item `index` should be the group's single tab stop: when focus
+	 * hasn't entered the group yet that is item 0, otherwise whichever item
+	 * focus last rested on.
+	 */
+	isTabStop: (index: number) => boolean;
+}
+
+export function createFocusGroup<T extends FocusItemState>(): FocusGroup<T> {
+	const itemStates: T[] = [];
+	// The tracked index is reactive, so components can derive each item's
+	// roving tabindex from it in their templates
+	const $state = $watch({ index: -1 });
+
+	function registerItem(item: T): { index: number } {
+		item.index = itemStates.length;
+		itemStates.push(item);
+		return { index: item.index };
+	}
+
+	function removeItem(itemIndex: number) {
+		const i = itemStates.findIndex((item) => item.index === itemIndex);
+		if (i !== -1) {
+			itemStates.splice(i, 1);
+			// Reindex the tail so indices stay dense
+			for (let j = i; j < itemStates.length; j++) {
+				itemStates[j].index = j;
+			}
+			if ($state.index > i) {
+				$state.index--;
+			} else if ($state.index === i) {
+				$state.index = -1;
+			}
+		}
+	}
+
+	function handleItemFocus(index: number) {
+		$state.index = index;
+	}
+
+	function getFocusIndex(): number {
+		return $state.index;
+	}
+
+	function isTabStop(index: number): boolean {
+		return ($state.index === -1 ? 0 : $state.index) === index;
+	}
+
+	function moveFocus(index: number, target: FocusTarget) {
+		if (itemStates.length === 0) return;
+		$state.index = focusItem(itemStates, index === -1 ? 0 : index, target);
+	}
+
+	function focusFirstItem() {
+		if (itemStates.length) {
+			$state.index = 0;
+			itemStates[0].setFocused();
+		}
+	}
+
+	function focusLastItem() {
+		if (itemStates.length > 0) {
+			$state.index = itemStates.length - 1;
+			itemStates.at(-1)!.setFocused();
+		}
+	}
+
+	function handleGroupKey(
+		index: number,
+		e: KeyboardEvent,
+		options?: { vertical?: boolean },
+	): boolean {
+		const vertical = options?.vertical ?? false;
+		let handled = true;
+		switch (e.key) {
+			case "ArrowRight": {
+				if (!vertical) {
+					e.preventDefault();
+					moveFocus(index, "next");
+				} else {
+					handled = false;
+				}
+				break;
+			}
+			case "ArrowLeft": {
+				if (!vertical) {
+					e.preventDefault();
+					moveFocus(index, "previous");
+				} else {
+					handled = false;
+				}
+				break;
+			}
+			case "ArrowDown": {
+				if (vertical) {
+					e.preventDefault();
+					moveFocus(index, "next");
+				} else {
+					handled = false;
+				}
+				break;
+			}
+			case "ArrowUp": {
+				if (vertical) {
+					e.preventDefault();
+					moveFocus(index, "previous");
+				} else {
+					handled = false;
+				}
+				break;
+			}
+			case "Home": {
+				e.preventDefault();
+				moveFocus(index, "start");
+				break;
+			}
+			case "End": {
+				e.preventDefault();
+				moveFocus(index, "end");
+				break;
+			}
+			default: {
+				handled = false;
+			}
+		}
+		return handled;
+	}
+
+	return {
+		itemStates,
+		registerItem,
+		removeItem,
+		handleItemFocus,
+		handleGroupKey,
+		moveFocus,
+		focusFirstItem,
+		focusLastItem,
+		getFocusIndex,
+		isTabStop,
+	};
+}

package/dist/utils/focusItem.ts

@@ -0,0 +1,44 @@
+export type FocusTarget = "start" | "previous" | "next" | "end";
+
+/**
+ * Standard keyboard navigation for a list of registered items: moves through
+ * the items in the given direction and focuses the first one that isn't
+ * disabled. Returns the new focus index, or the original when no focusable
+ * item was found.
+ */
+export function focusItem<T extends { setFocused: () => void; disabled?: boolean }>(
+	items: T[],
+	current: number,
+	target: FocusTarget,
+): number {
+	if (items.length === 0) return current;
+	let index = current;
+	switch (target) {
+		case "start": {
+			index = 0;
+			break;
+		}
+		case "previous": {
+			index = Math.max(0, current - 1);
+			break;
+		}
+		case "next": {
+			index = Math.min(items.length - 1, current + 1);
+			break;
+		}
+		case "end": {
+			index = items.length - 1;
+			break;
+		}
+	}
+	// Skip disabled items, searching in the direction of travel
+	const step = target === "previous" ? -1 : 1;
+	while (index >= 0 && index < items.length && items[index].disabled) {
+		index += step;
+	}
+	if (index < 0 || index >= items.length) {
+		return current;
+	}
+	items[index].setFocused();
+	return index;
+}

package/dist/utils/formField.ts

@@ -0,0 +1,70 @@
+import type { FieldContext, FormContext } from "../Form/FormTypes";
+
+export interface FormField {
+	/** The resolved form data field name: the component's name, or the enclosing Field's */
+	name: string | undefined;
+	/** Whether this component is contained within a Form Field */
+	inField: boolean;
+	/** Whether the Field's value is valid; always true outside a Field */
+	valid: boolean;
+	/** The ID of the Field's Message component, for aria-describedby */
+	messageId: string | undefined;
+	/** Called after the value has been changed by user interaction */
+	handleInput: () => void;
+	/** Called when the component loses focus */
+	handleBlur: () => void;
+}
+
+/**
+ * Wires a standalone input component into an enclosing Form and Field, in
+ * the same way as the components in the Form family: the Field's name is
+ * used when the component doesn't set one, validation runs as the user
+ * interacts, and the standard validity attributes can be applied.
+ *
+ * Usage inside a component:
+ *
+ * ```ts
+ * const form = createFormField(
+ * 	$props?.name,
+ * 	$context[FormContextName] as FormContext | undefined,
+ * 	$context[FieldContextName] as FieldContext | undefined,
+ * );
+ * ```
+ */
+export default function createFormField(
+	name: string | undefined,
+	formContext: FormContext | undefined,
+	fieldContext: FieldContext | undefined,
+): FormField {
+	let blurred = false;
+
+	return {
+		get name() {
+			return name ?? fieldContext?.name;
+		},
+		get inField(): boolean {
+			return fieldContext !== undefined;
+		},
+		get valid(): boolean {
+			if (!fieldContext) return true;
+			return fieldContext.state.valid !== false;
+		},
+		get messageId(): string | undefined {
+			return fieldContext?.state.messageId;
+		},
+		handleInput() {
+			if (formContext) {
+				formContext.validate();
+			}
+			if (fieldContext && blurred) {
+				fieldContext.validate();
+			}
+		},
+		handleBlur() {
+			if (fieldContext) {
+				fieldContext.validate();
+			}
+			blurred = true;
+		},
+	};
+}

package/dist/utils/hoverOpen.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared hover-to-open behavior for popout triggers: opens after a delay,
+ * resetting the timer as the user moves within the element.
+ */
+export function createHoverOpen(
+	open: () => void,
+	disabled: () => boolean,
+	delay: number,
+): {
+	handleMouseEnter: () => void;
+	handleMouseLeave: () => void;
+	handleMouseMove: () => void;
+} {
+	let interval: ReturnType<typeof setTimeout> | undefined;
+
+	function schedule() {
+		interval = setTimeout(() => open(), delay);
+	}
+
+	function handleMouseEnter() {
+		if (disabled()) return;
+
+		// Handle the hover after a delay
+		if (!interval) {
+			schedule();
+		}
+	}
+
+	function handleMouseLeave() {
+		if (disabled()) return;
+
+		// Prevent short hovers or touches from firing the event
+		if (interval) {
+			clearTimeout(interval);
+			interval = undefined;
+		}
+	}
+
+	function handleMouseMove() {
+		if (disabled()) return;
+
+		// Reset the interval on mouse move
+		if (interval) {
+			clearTimeout(interval);
+			schedule();
+		}
+	}
+
+	return { handleMouseEnter, handleMouseLeave, handleMouseMove };
+}

package/dist/utils/hoverReveal.ts

@@ -0,0 +1,194 @@
+/**
+ * Shared hover-to-reveal behavior for hover-activated popout triggers
+ * (PopoverHover, ContextualHover).
+ *
+ * Unlike press activation, hover needs:
+ * - an intent delay before opening, so passing over an element doesn't flash
+ *   a popout (mirrors createHoverOpen for menu items)
+ * - an exit grace period after leaving, so moving the pointer from the
+ *   trigger into the popout content doesn't close it -- entering the content
+ *   cancels a pending close entirely
+ */
+
+export interface HoverRevealOptions {
+	/** Shows the popout */
+	show: () => void;
+	/** Hides the popout */
+	hide: () => void;
+	/** Whether the popout is currently visible */
+	isVisible: () => boolean;
+	/** Whether hover interaction is ignored entirely */
+	disabled?: () => boolean;
+	/** The popout content element, for keeping it open when hovered */
+	getContent?: () => HTMLElement | null | undefined;
+	/** Milliseconds to wait before opening (default 500; 0 opens immediately) */
+	hoverDelay?: number;
+	/** Milliseconds to wait after the pointer leaves before closing (default 300) */
+	exitGrace?: number;
+}
+
+export interface HoverRevealHandlers {
+	/** Handles the pointer entering the trigger */
+	handleEnter: () => void;
+	/** Handles the pointer leaving the trigger; closes unless it moved into the content element */
+	handleLeave: (e: MouseEvent | FocusEvent) => void;
+	/** Handles focus landing on the trigger (opens immediately) */
+	handleFocus: () => void;
+	/** Handles focus leaving the trigger (closes unless focus moved into the content element) */
+	handleBlur: (e: FocusEvent) => void;
+	/** Cancels pending open/close timers */
+	dispose: () => void;
+}
+
+export function createHoverReveal(options: HoverRevealOptions): HoverRevealHandlers {
+	const show = options.show;
+	const hide = options.hide;
+	const isVisible = options.isVisible;
+	const disabled = options.disabled ?? (() => false);
+	const getContent = options.getContent ?? (() => undefined);
+	const hoverDelay = options.hoverDelay ?? 500;
+	const exitGrace = options.exitGrace ?? 300;
+
+	let openTimer: ReturnType<typeof setTimeout> | undefined;
+	let closeTimer: ReturnType<typeof setTimeout> | undefined;
+	let suppressFocusOpen = false;
+
+	function clearTimers() {
+		if (openTimer !== undefined) {
+			clearTimeout(openTimer);
+			openTimer = undefined;
+		}
+		if (closeTimer !== undefined) {
+			clearTimeout(closeTimer);
+			closeTimer = undefined;
+		}
+	}
+
+	function cancelPendingOpen() {
+		if (openTimer !== undefined) {
+			clearTimeout(openTimer);
+			openTimer = undefined;
+		}
+	}
+
+	/** While armed, moving into the content cancels the close */
+	function scheduleClose() {
+		if (closeTimer !== undefined) return;
+
+		closeTimer = setTimeout(() => {
+			closeTimer = undefined;
+			stopListening();
+			// The content hides with `refocusAnchorOnHide`, which drops
+			// focus back onto this trigger -- that is not user intent,
+			// so swallow the one focus-driven open that follows
+			suppressFocusOpen = true;
+			hide();
+		}, exitGrace);
+
+		// Cancel as soon as the pointer or focus lands on the content
+		document.addEventListener("mouseover", handleDocumentOver);
+		document.addEventListener("focusin", handleDocumentFocusIn);
+	}
+
+	function stopListening() {
+		document.removeEventListener("mouseover", handleDocumentOver);
+		document.removeEventListener("focusin", handleDocumentFocusIn);
+	}
+
+	function handleDocumentFocusIn(e: FocusEvent) {
+		if (closeTimer === undefined) {
+			stopListening();
+			return;
+		}
+		if (insideContent(e.target)) {
+			clearTimeout(closeTimer);
+			closeTimer = undefined;
+			stopListening();
+		}
+	}
+
+	function handleDocumentOver(e: MouseEvent) {
+		if (closeTimer === undefined) {
+			document.removeEventListener("mouseover", handleDocumentOver);
+			return;
+		}
+		if (insideContent(e.target)) {
+			clearTimeout(closeTimer);
+			closeTimer = undefined;
+			document.removeEventListener("mouseover", handleDocumentOver);
+		}
+	}
+
+	function insideContent(target: EventTarget | null): boolean {
+		const content = getContent();
+		if (!content || !target) return false;
+		return content === target || content.contains(target as Node);
+	}
+
+	return {
+		handleEnter() {
+			if (disabled()) return;
+
+			if (closeTimer !== undefined) {
+				clearTimeout(closeTimer);
+				closeTimer = undefined;
+				stopListening();
+			}
+			if (isVisible()) return;
+
+			if (hoverDelay <= 0) {
+				show();
+				return;
+			}
+			if (openTimer === undefined) {
+				openTimer = setTimeout(() => {
+					openTimer = undefined;
+					show();
+				}, hoverDelay);
+			}
+		},
+
+		handleLeave(_e) {
+			if (disabled()) return;
+
+			// Just a pass-over: cancel the pending open and stay closed
+			if (openTimer !== undefined) {
+				cancelPendingOpen();
+				return;
+			}
+			if (!isVisible()) return;
+
+			scheduleClose();
+		},
+
+		handleFocus() {
+			if (disabled()) return;
+
+			if (suppressFocusOpen) {
+				suppressFocusOpen = false;
+				return;
+			}
+
+			if (closeTimer !== undefined) {
+				clearTimeout(closeTimer);
+				closeTimer = undefined;
+				stopListening();
+			}
+			if (!isVisible()) {
+				show();
+			}
+		},
+
+		handleBlur(_e) {
+			if (disabled()) return;
+			if (!isVisible()) return;
+
+			scheduleClose();
+		},
+
+		dispose() {
+			clearTimers();
+			stopListening();
+		},
+	};
+}

package/dist/utils/loader.ts

@@ -0,0 +1,113 @@
+import { $async, $watch } from "@torpor/view";
+
+/**
+ * Shared contract for loading data from the network, used by components that
+ * can take either static data or a loader function (DataGrid now, ComboBox
+ * auto-complete and others later).
+ *
+ * A loader receives a request object describing what to fetch -- paging,
+ * search text and sorting are standard; components extend it with their own
+ * fields -- plus an AbortSignal so stale requests can be cancelled.
+ */
+
+/** The base shape of a load request. Components extend this with their own fields. */
+export interface LoadRequest {
+	/** 1-based page number to load */
+	page?: number;
+	/** Number of items per page */
+	pageSize?: number;
+	/** Search or filter text entered by the user */
+	searchText?: string;
+	/** The field to sort by */
+	sortBy?: string;
+	/** The direction to sort in */
+	sortDirection?: "asc" | "desc";
+}
+
+/**
+ * The result of a load: the items for the current request, and optionally
+ * the total count (needed for paged components to show a pager).
+ */
+export interface LoadResult<T = any> {
+	items: T[];
+	/** The total number of items across all pages, if known */
+	total?: number;
+}
+
+/**
+ * Reads data for a request. May return a promise or a plain result, and may
+ * return just an array of items when no total is available.
+ */
+export type Loader<T = any, TRequest extends LoadRequest = LoadRequest> = (
+	request: TRequest,
+	signal?: AbortSignal,
+) => Promise<LoadResult<T> | T[]> | LoadResult<T> | T[];
+
+/** Wraps a bare array in a LoadResult so consumers always get the same shape */
+export function normalizeLoadResult<T>(result: LoadResult<T> | T[]): LoadResult<T> {
+	return Array.isArray(result) ? { items: result } : result;
+}
+
+export interface ItemLoaderOptions<T = any, TRequest extends LoadRequest = LoadRequest> {
+	/** The loader function to fetch items */
+	load: Loader<T, TRequest>;
+	/**
+	 * Builds the request for the current fetch. Called inside the async
+	 * getter, so reads of reactive state here re-fetch when they change.
+	 */
+	getRequest: () => TRequest;
+	/** Called after each successful load with the normalized result */
+	onload?: (result: LoadResult<T>) => void;
+}
+
+/** Reactive loading state returned by createItemLoader */
+export interface ItemLoaderState<T = any> {
+	/** The full result of the current load; suspends while a fetch is pending */
+	readonly result: LoadResult<T> | undefined;
+	/** The loaded items; suspends while a fetch is pending */
+	readonly items: T[];
+}
+
+/**
+ * Shared loading state for components that read items from a network loader
+ * (DataGrid, ComboBox auto-complete etc). Read the returned state's `items`
+ * or `result` inside an `@await` boundary: while a fetch is pending the read
+ * suspends, and when dependencies read inside `getRequest` change the fetch
+ * re-runs.
+ *
+ * For lazy loading (fetch only once some condition is met), gate the whole
+ * rendering of the region that reads this loader behind that condition
+ * (`@if`), so the `@await` boundary -- and with it the first fetch --
+ * comes into existence when the condition flips.
+ *
+ * ```
+ * let $load = createItemLoader({
+ * 	load: $props.load,
+ * 	getRequest: () => ({ searchText: $state.searchText }),
+ * });
+ * @await { ...$load.items... } with { <span>Loading…</span> }
+ * ```
+ */
+export function createItemLoader<T = any, TRequest extends LoadRequest = LoadRequest>(
+	options: ItemLoaderOptions<T, TRequest>,
+): ItemLoaderState<T> {
+	return $watch({
+		get result(): LoadResult<T> | undefined {
+			return $async(() => {
+				const promise = Promise.resolve(options.load(options.getRequest())).then(
+					normalizeLoadResult,
+				);
+				// Report successful loads to the consumer; failures surface
+				// through the component's error boundary, not this chain
+				promise.then(
+					(r) => options.onload?.(r),
+					() => {},
+				);
+				return promise as Promise<LoadResult<T>>;
+			});
+		},
+		get items(): T[] {
+			return this.result?.items ?? [];
+		},
+	});
+}