@torpor/ui 0.4.0 → 1.0.1

package/dist/utils/createItemGroup.ts

@@ -0,0 +1,152 @@
+import { $cache, $run } from "@torpor/view";
+
+export interface ItemGroupItem {
+	index: number;
+	value: any;
+	parentDisabled?: boolean;
+}
+
+export interface ItemGroup<T extends ItemGroupItem> {
+	itemStates: T[];
+	registerItem: (item: T) => void;
+	removeItem: (itemIndex: number) => void;
+	toggleItem: (value: any) => void;
+}
+
+/**
+ * Creates a managed collection of selectable items for group-style components
+ * (Accordion, ListBox, TabGroup, Tree, etc.).
+ *
+ * Handles item registration, removal, and toggle logic. Each item's selection
+ * state is derived: registration installs a `$cache` getter over
+ * `selectedProperty` that computes from the group value, so selection can
+ * never drift out of sync with it — eliminating the boilerplate that was
+ * duplicated across ~5 components.
+ *
+ * The returned `itemStates` array is the source of truth; components should
+ * store it in their context for child items to access.
+ *
+ * NOTE: Items must be registered before their selection property is first
+ * read, so the derived getter can take the property over.
+ */
+export function createItemGroup<T extends ItemGroupItem>(options: {
+	/** The reactive state containing the group value */
+	state: { value: any };
+	/** Selection type, or a getter for it if it can change */
+	type: "single" | "multiple" | (() => "single" | "multiple");
+	/** The boolean property on items that reflects selection state */
+	selectedProperty: keyof T;
+	/** Getter for parent disabled state */
+	disabled?: () => boolean | undefined;
+	/** Allow deselecting in single-select mode (default: true) */
+	allowDeselect?: boolean;
+	/** Called for each item after index assignment but before selection check */
+	onRegister?: (item: T) => void;
+	/** Callback after a toggle, for side effects like closing a popout */
+	onToggle?: (value: any) => void;
+}): ItemGroup<T> {
+	const { state, selectedProperty } = options;
+	const getType = typeof options.type === "function" ? options.type : () => options.type;
+	const allowDeselect = options.allowDeselect ?? true;
+	const itemStates: T[] = [];
+	let nextIndex = 0;
+
+	// Propagate disabled state from parent
+	if (options.disabled) {
+		const disabledGetter = options.disabled;
+		$run(() => {
+			const disabled = disabledGetter() === true;
+			for (let item of itemStates) {
+				item.parentDisabled = disabled;
+			}
+		});
+	}
+
+	function isItemSelected(item: T, value: any): boolean {
+		if (value === undefined || value === null) return false;
+		if (getType() === "multiple") {
+			const values = Array.isArray(value) ? value : [value];
+			return values.some((v) => sameValue(v, item.value));
+		}
+		return sameValue(item.value, value);
+	}
+
+	function registerItem(item: T) {
+		if (item.index === -1 || item.index === undefined) {
+			item.index = nextIndex++;
+		}
+		if (options.onRegister) {
+			options.onRegister(item);
+		}
+		// Make the selection property derived: a cached getter computed from the
+		// group value, so it always reflects (and only reflects) that value
+		Object.defineProperty(item, selectedProperty, {
+			get() {
+				return $cache(() => isItemSelected(item, state.value));
+			},
+			enumerable: true,
+			configurable: true,
+		});
+		if (options.disabled) {
+			item.parentDisabled = options.disabled() === true;
+		}
+		itemStates.splice(item.index, 0, item);
+	}
+
+	function removeItem(itemIndex: number) {
+		const index = itemStates.findIndex((item) => item.index === itemIndex);
+		if (index !== -1) {
+			itemStates.splice(index, 1);
+		}
+		itemStates.forEach((item, i) => (item.index = i));
+	}
+
+	function toggleItem(value: any) {
+		switch (getType()) {
+			case "single": {
+				const item = itemStates.find((i) => sameValue(i.value, value));
+				if (allowDeselect) {
+					if (item) {
+						state.value = (item as any)[selectedProperty] ? undefined : item.value;
+					}
+				} else {
+					// Store the item's own value, so the group value keeps its
+					// canonical type
+					state.value = item ? item.value : value;
+				}
+				break;
+			}
+			case "multiple": {
+				const newValue: any[] = [];
+				for (let item of itemStates) {
+					const toggled = sameValue(item.value, value);
+					if (
+						(toggled && !(item as any)[selectedProperty]) ||
+						(!toggled && (item as any)[selectedProperty])
+					) {
+						newValue.push(item.value);
+					}
+				}
+				state.value = newValue.sort((a, b) => a - b);
+				break;
+			}
+		}
+		if (options.onToggle) {
+			options.onToggle(value);
+		}
+	}
+
+	return { itemStates, registerItem, removeItem, toggleItem };
+}
+
+/**
+ * Compares an item value with a group/toggle value. Primitives are compared
+ * as strings — DOM values are always strings, while callers may pass e.g.
+ * numbers — and everything else by strict equality.
+ */
+function sameValue(a: any, b: any): boolean {
+	if (a === b) return true;
+	if (a === null || b === null || a === undefined || b === undefined) return false;
+	if (typeof a === "object" || typeof b === "object") return false;
+	return String(a) === String(b);
+}

package/dist/utils/dateUtils.ts

@@ -25,7 +25,7 @@ const dayNames: string[] = [
 	"Saturday",
 	"Sunday",
 ];
-const shortDayNames: string[] = dayNames.map((n) => n.substring(0, 3).toLowerCase());
+const shortDayNames: string[] = dayNames.map((n) => n.substring(0, 2));
 
 export { monthNames, shortMonthNames, dayNames, shortDayNames };
 
@@ -229,16 +229,17 @@ function formatMonth(date: Date, m: string): string {
 	} else if (m.length === 3) {
 		return monthNames[date.getMonth()].substring(0, 3);
 	} else if (m.length == 2) {
-		let text = date.getMonth().toString();
-		return text.length < 2 ? "0" + text : text;
+		// getMonth is zero-based
+		return String(date.getMonth() + 1).padStart(2, "0");
 	} else {
 		return date.getMonth().toString();
 	}
 }
 
 function formatYear(date: Date, y: string): string {
-	return date
-		.getFullYear()
-		.toString()
-		.substring(4 - y.length, y.length);
+	const year = date.getFullYear().toString();
+	if (y.length >= 4) {
+		return year;
+	}
+	return year.substring(4 - y.length);
 }

package/dist/utils/documentEvents.ts

@@ -1,17 +1,17 @@
 export function addDocumentEvent<K extends keyof DocumentEventMap>(
 	type: K,
-	listener: (this: Document, ev: DocumentEventMap[K]) => any
+	listener: (this: Document, ev: DocumentEventMap[K]) => any,
 ): void {
-	if (typeof document !== 'undefined') {
+	if (typeof document !== "undefined") {
 		document.addEventListener(type, listener);
 	}
 }
 
 export function removeDocumentEvent<K extends keyof DocumentEventMap>(
 	type: K,
-	listener: (this: Document, ev: DocumentEventMap[K]) => any
+	listener: (this: Document, ev: DocumentEventMap[K]) => any,
 ): void {
-	if (typeof document !== 'undefined') {
+	if (typeof document !== "undefined") {
 		document.removeEventListener(type, listener);
 	}
 }

package/dist/utils/dragState.ts

@@ -0,0 +1,86 @@
+import { $watch } from "@torpor/view";
+
+/**
+ * Shared state for HTML5 drag & drop. A source element starts a drag with
+ * `beginDrag`; drop targets consult `dragState.current` during dragover and
+ * drop. Because the dataTransfer API restricts what can be read outside
+ * drop, the store is the reliable channel -- the dataTransfer only carries
+ * the drag's id, which doubles as an integrity check and makes drags
+ * interoperable across windows when the type is allowed through.
+ *
+ * Drags don't nest, so a single module-level state is enough.
+ */
+
+export interface DragInfo {
+	/** Generated identifier for this drag, mirrored into the dataTransfer */
+	id: string;
+	/** High-level kind ("list-item", "tree-item", "file"...), for filtering */
+	kind: string;
+	/** Arbitrary payload attached by the drag source */
+	data: any;
+}
+
+export interface DragState {
+	/** The active drag, if any */
+	current: DragInfo | undefined;
+}
+
+export const dragState: DragState = $watch({
+	current: undefined as DragInfo | undefined,
+});
+
+let nextId = 0;
+
+/** Starts tracking a drag and returns its id */
+export function beginDrag(kind: string, data: any): DragInfo {
+	const info: DragInfo = {
+		id: String(nextId++),
+		kind,
+		data,
+	};
+	dragState.current = info;
+	return info;
+}
+
+/** Clears the tracked drag */
+export function endDrag(): void {
+	dragState.current = undefined;
+}
+
+const TYPE_PREFIX = "application/x-torpor-drag/";
+
+/** Encodes a drag id into a dataTransfer-compatible mime type */
+export function encodeDragType(id: string): string {
+	return TYPE_PREFIX + id;
+}
+
+/**
+ * Writes the drag's id into the event's dataTransfer. No-op when the event
+ * carries no transfer (some synthetic tests construct bare events).
+ */
+export function writeDragType(e: DragEvent, id: string): void {
+	e.dataTransfer?.setData(encodeDragType(id), id);
+}
+
+/**
+ * Resolves which drag an incoming event refers to. Prefers the id encoded
+ * in the dataTransfer (verified against the live drag); falls back to the
+ * tracked drag itself for dragover events, whose transfers are locked.
+ */
+export function resolveDrag(e: DragEvent): DragInfo | undefined {
+	const current = dragState.current;
+	if (!current) return undefined;
+
+	try {
+		const types: readonly string[] = e.dataTransfer?.types ?? [];
+		for (let type of types) {
+			if (type.startsWith(TYPE_PREFIX)) {
+				return type === encodeDragType(current.id) ? current : undefined;
+			}
+		}
+	} catch {
+		// Reading types can throw for foreign-origin drags; treat those as
+		// unmatched and fall back to the tracked drag below
+	}
+	return current;
+}

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 };
+}