@torpor/ui 0.4.0 → 1.0.1

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 ?? [];
+		},
+	});
+}

package/dist/utils/maskUtils.ts

@@ -0,0 +1,98 @@
+/**
+ * Masked input plumbing: masks are strings where token characters accept
+ * user input and everything else is a literal.
+ *
+ * - `9` -- digit (0-9)
+ * - `L` -- letter (a-z, case preserved)
+ * - `a` -- alphanumeric
+ * - `\x` -- the literal character x
+ */
+
+export interface MaskToken {
+	/** Literal characters render as-is; tokens accept input */
+	literal: boolean;
+	char: string;
+	pattern?: RegExp;
+}
+
+/** Splits a mask into literal/token parts */
+export function parseMask(mask: string): MaskToken[] {
+	const tokens: MaskToken[] = [];
+	for (let i = 0; i < mask.length; i++) {
+		const char = mask[i];
+		if (char === "\\" && i + 1 < mask.length) {
+			tokens.push({ literal: true, char: mask[i + 1] });
+			i++;
+			continue;
+		}
+		switch (char) {
+			case "9":
+				tokens.push({ literal: false, char, pattern: /[0-9]/ });
+				break;
+			case "L":
+				tokens.push({ literal: false, char, pattern: /[A-Za-z]/ });
+				break;
+			case "a":
+				tokens.push({ literal: false, char, pattern: /[A-Za-z0-9]/ });
+				break;
+			default:
+				tokens.push({ literal: true, char });
+		}
+	}
+	return tokens;
+}
+
+/** The characters a mask can hold, ignoring literals */
+export function tokenCount(tokens: MaskToken[]): number {
+	return tokens.filter((t) => !t.literal).length;
+}
+
+/**
+ * Walks user-entered text against the mask, keeping only characters that
+ * fit the remaining slots. Typing ahead of literals works because missing
+ * literals are skipped, so `5551234` formats like `(555) 123-4`.
+ */
+export function extractRaw(tokens: MaskToken[], text: string): string {
+	let result = "";
+	let ti = 0;
+
+	for (const ch of text) {
+		if (ti >= tokens.length) break;
+
+		// Skip forward to the first token this character satisfies
+		while (ti < tokens.length && tokens[ti].literal && tokens[ti].char !== ch) {
+			ti++;
+		}
+		const token = tokens[ti];
+		if (!token) break;
+
+		if (token.literal) {
+			// The user typed the literal itself
+			ti++;
+			continue;
+		}
+		if (!token.pattern!.test(ch)) continue;
+
+		result += ch;
+		ti++;
+	}
+	return result;
+}
+
+/** Builds the displayed text from raw input characters */
+export function formatMask(tokens: MaskToken[], raw: string): string {
+	let result = "";
+	let index = 0;
+	let lastFilledEnd = 0;
+
+	for (let i = 0; i < tokens.length && index < raw.length; i++) {
+		const token = tokens[i];
+		if (token.literal) {
+			result += token.char;
+			continue;
+		}
+		result += raw[index++];
+		lastFilledEnd = result.length;
+	}
+	return result.slice(0, lastFilledEnd);
+}

package/dist/utils/popoutContent.ts

@@ -0,0 +1,137 @@
+import { addDocumentEvent, removeDocumentEvent } from "./documentEvents";
+import getScrollParent from "./getScrollParent";
+import setPopoverPosition from "./setPopoverPosition";
+
+export interface PopoutContentOptions {
+	/** Resolves the element to position the content against */
+	getAnchor: () => HTMLElement | undefined;
+	/** Resolves the content element */
+	getContent: () => HTMLElement | undefined;
+	/** Closes the popout (e.g. by setting visible to false) */
+	close: (e: MouseEvent | KeyboardEvent) => void;
+	/** Where to show the content, relative to the anchor */
+	side?: "top" | "right" | "bottom" | "left";
+	/** How to align the content, relative to the anchor */
+	alignment?: "start" | "center" | "end";
+	/** Custom positioning, as an alternative to side/alignment */
+	position?: () => void;
+	/** Whether pressing Escape closes the popout */
+	closeOnEscape?: boolean;
+	/** Only close on Escape when the focus is inside the content */
+	escapeOnlyWhenFocused?: boolean;
+	/** Ignore clicks on the anchor element when closing on outside clicks */
+	ignoreAnchorClicks?: boolean;
+	/** Called after the content is shown, to set focus for accessibility */
+	focusFirstElement?: () => void;
+	/** Focus the anchor element after hiding */
+	refocusAnchorOnHide?: boolean;
+}
+
+/**
+ * Shared show/hide machinery for popout content components: outside click
+ * handling, Escape handling, repositioning on scroll/resize and focus
+ * management.
+ *
+ * HACK: Because the popout could be shown with a click, we need to wait for
+ * another mousedown before we close on click. Otherwise the click that opened
+ * the popout immediately bubbles to the document and closes it again.
+ */
+export function createPopoutContent(options: PopoutContentOptions): {
+	show: () => void;
+	hide: () => void;
+} {
+	let shown = false;
+	let closeOnClick = false;
+
+	function setPosition() {
+		const anchor = options.getAnchor();
+		const content = options.getContent();
+		if (!anchor || !content) return;
+
+		if (options.position) {
+			options.position();
+		} else {
+			setPopoverPosition(anchor, content, options.side ?? "bottom", options.alignment ?? "start");
+		}
+	}
+
+	function handleDocumentMouseDown() {
+		closeOnClick = true;
+	}
+
+	function handleDocumentClick(e: MouseEvent) {
+		const content = options.getContent();
+		const anchor = options.getAnchor();
+		if (!closeOnClick || !content || content.contains(e.target as HTMLElement)) {
+			return;
+		}
+		if (options.ignoreAnchorClicks && anchor?.contains(e.target as HTMLElement)) {
+			return;
+		}
+		e.preventDefault();
+		options.close(e);
+	}
+
+	function handleDocumentKeyDown(e: KeyboardEvent) {
+		if (e.key !== "Escape") return;
+		const content = options.getContent();
+		if (options.escapeOnlyWhenFocused && content && !content.contains(e.target as Node)) {
+			return;
+		}
+		e.preventDefault();
+		options.close(e);
+	}
+
+	function show() {
+		shown = true;
+
+		closeOnClick = false;
+		addDocumentEvent("mousedown", handleDocumentMouseDown);
+		addDocumentEvent("click", handleDocumentClick);
+		if (options.closeOnEscape) {
+			addDocumentEvent("keydown", handleDocumentKeyDown);
+		}
+
+		// Set the position and listen for window resize and scroll to reset the position
+		setPosition();
+		addEventListener("resize", setPosition);
+		const anchor = options.getAnchor();
+		if (anchor) {
+			getScrollParent(anchor).addEventListener("scroll", setPosition);
+		}
+
+		options.focusFirstElement?.();
+	}
+
+	function hide() {
+		if (!shown) return;
+		shown = false;
+
+		removeDocumentEvent("mousedown", handleDocumentMouseDown);
+		removeDocumentEvent("click", handleDocumentClick);
+		removeDocumentEvent("keydown", handleDocumentKeyDown);
+		removeEventListener("resize", setPosition);
+		const anchor = options.getAnchor();
+		if (anchor) {
+			getScrollParent(anchor).removeEventListener("scroll", setPosition);
+		}
+
+		// Focus the anchor element again, per the WAI guidelines, unless focus
+		// has already moved elsewhere (e.g. to an adjacent menubar item's menu).
+		// If the focused element was removed with the content, focus has fallen
+		// back to the body, and the anchor is focused again
+		if (options.refocusAnchorOnHide) {
+			const content = options.getContent();
+			if (
+				!content ||
+				content.contains(document.activeElement) ||
+				document.activeElement === document.body
+			) {
+				const el = options.getAnchor();
+				el?.focus?.();
+			}
+		}
+	}
+
+	return { show, hide };
+}

package/dist/utils/reorderList.ts

@@ -0,0 +1,52 @@
+/**
+ * Pure helpers for reorderable collections, used by list and tree drag &
+ * drop. Geometry-free on purpose: components measure their own slots with
+ * slotIndex and combine the result with these.
+ */
+
+/** Moves an item to a final index; out-of-range targets are clamped */
+export function moveItem<T>(items: T[], from: number, to: number): T[] {
+	const next = items.slice();
+	if (from < 0 || from >= next.length) return next;
+	const clamped = Math.min(next.length - 1, Math.max(0, to));
+	const [item] = next.splice(from, 1);
+	next.splice(clamped, 0, item);
+	return next;
+}
+
+/**
+ * Moves an item to sit at the slot `insertAt` occupied *before* the move --
+ * i.e. `insertAt` indexes into the original order, which is what pointer
+ * math produces (dropped before item N). Handles the index shift caused by
+ * removing the dragged element.
+ */
+export function moveToSlot<T>(items: T[], from: number, insertAt: number): T[] {
+	let to = insertAt;
+	if (from < insertAt) {
+		to = insertAt - 1;
+	}
+	return moveItem(items, from, to);
+}
+
+/**
+ * Finds which slot a pointer sits in along an axis: the index of the first
+ * element whose midpoint the point has passed (or elements.length when past
+ * all of them). `elements` must already be in display order.
+ *
+ * ```
+ * const insert = slotIndex([...list.children], "y", e.clientY);
+ * list.set(items => moveToSlot(items, dragFrom, insert));
+ * ```
+ */
+export function slotIndex(
+	elements: { getBoundingClientRect(): DOMRect }[],
+	axis: "x" | "y",
+	point: number,
+): number {
+	for (let i = 0; i < elements.length; i++) {
+		const rect = elements[i].getBoundingClientRect();
+		const mid = axis === "x" ? rect.left + rect.width / 2 : rect.top + rect.height / 2;
+		if (point < mid) return i;
+	}
+	return elements.length;
+}