@torpor/ui 0.0.16 → 0.1.0

package/src/TabGroup/TabGroup.torp

@@ -0,0 +1,225 @@
+import { TabGroupContextName, type TabGroupContext, type ItemState } from "./TabGroupTypes";
+
+/**
+ * A list of interactive headings coupled with layered sections of content that
+ * enable users to reveal a single section of content at a time.
+ *
+ * See [the WAI ARIA guidelines for Tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
+ *
+ * The structure of a TabGroup is:
+ *
+ * ```
+ * <TabGroup>
+ * 	<TabList>
+ * 		<TabHeader>
+ * 			<TabTrigger />
+ * 		</TabHeader>
+ * 	</TabList>
+ * 	<TabContent />
+ * </TabGroup>
+ * ```
+ *
+ * @prop {"horizontal" | "vertical"} orientation -- The orientation of the tab buttons, which affects keyboard navigation
+ * @prop {"automatic" | "manual"} activation -- How tabs are activated; if automatic they are shown on focus, if manual they must be clicked
+ * @prop {string | string[]} value -- The value of the active TabContent
+ * @prop {boolean} disabled -- If set to true, the user cannot interact with any items in the TabGroup
+ * @prop {(value: string | string[]) => void} [onchange] -- Raised when the active item has changed
+ */
+export default function TabGroup($props: any) {
+	$props.orientation ||= "horizontal";
+	$props.activation ||= "automatic";
+	$props.value ||= "";
+
+	let itemStates: ItemState[] = [];
+
+	// This is used to assign automatic indexes to items where needed
+	let nextHeaderIndex = 0;
+	let nextItemIndex = 0;
+
+	// Set the context to pass down to headers and content, with functions for each item to call
+	let context: TabGroupContext = {
+		registerHeader,
+		registerItem,
+		removeItem,
+		triggerItem,
+		handleHeaderKey,
+		orientation: $props.orientation,
+		activation: $props.activation,
+	};
+	$context[TabGroupContextName] = context;
+	$run(() => {
+		// HACK: This should probably be done with setters?
+		let newValue = $props.value;
+
+		// Ensure the value passed in was a string (in case e.g. the user has set values to ints)
+		newValue = newValue?.toString();
+		for (let item of itemStates) {
+			item.active = item.value === newValue;
+		}
+
+		// Set the value
+		$props.value = newValue;
+	});
+
+	$run(() => {
+		itemStates.forEach((s) => s.parentDisabled = $props.disabled);
+	});
+
+	// Dispatch the change event when the value changes
+	let firstChange = true;
+	$run(() => {
+		const ev = $props.onchange;
+		const value = $props.value;
+		if (firstChange) {
+			firstChange = false;
+		} else if (ev) {
+			ev(value);
+		}
+	});
+
+	// TODO:
+	//$mount(() => {
+	//	if ($props.value === "" && itemStates.length) {
+	//		$props.value = itemStates[0].value;
+	//	}
+	//})
+
+	function registerHeader(index: number | undefined, value: string | undefined, setFocused: () => void): ItemState {
+		// If an index wasn't set for the header, set it automatically
+		if (!index) {
+			index = nextHeaderIndex++;
+		}
+
+		// Get or add the ItemState at this index
+		const itemState = getItemState(index, value);
+
+		itemState.setFocused = setFocused;
+
+		return itemState;
+	}
+
+	function registerItem(index: number | undefined, value: string | undefined): ItemState {
+		// If an index wasn't set for the item, set it automatically
+		if (!index) {
+			index = nextItemIndex++;
+		}
+
+		// Get or add the ItemState at this index
+		const itemState = getItemState(index, value);
+
+		return itemState;
+	}
+
+	function getItemState(index: number, value: string | undefined): ItemState {
+		// If we already have an item at this index, just return it
+		if (itemStates.length > index) {
+			return itemStates[index];
+		}
+
+		// If a value wasn't set for the item, set it to the index
+		if (!value) {
+			value = index.toString();
+		}
+
+		// Add the item's state to the array
+		const newItemState: ItemState = $watch({
+			index,
+			value,
+			active: value === $props.value,
+			headerId: "",
+			contentId: "",
+			disabled: false,
+			parentDisabled: false,
+			get dataState() {
+				return this.active ? "active" : "inactive";
+			},
+			setFocused: () => {},
+			orientation: $props.orientation,
+			activation: $props.activation
+		});
+		itemStates.splice(index, 0, newItemState);
+
+		return newItemState;
+	}
+
+	// TODO: I think this should be done by value
+	function removeItem(itemIndex: number) {
+		// Remove the item and re-index
+		let index = itemStates.findIndex((item) => item.index === itemIndex);
+		if (index !== -1) {
+			itemStates.splice(itemIndex, 1);
+		}
+		itemStates.forEach((item, i) => (item.index = i));
+	}
+
+	function triggerItem(toggleValue: string) {
+		for (let item of itemStates) {
+			// The item is active if it has the supplied value
+			if (item.value === toggleValue) {
+				$props.value = item.value;
+				break;
+			}
+		}
+	}
+
+	function handleHeaderKey(headerIndex: number, e: KeyboardEvent) {
+		switch (e.key) {
+			case "Left":
+			case "ArrowLeft": {
+				if ($props.orientation === "horizontal" && headerIndex > 0) {
+					e.preventDefault();
+					itemStates[headerIndex - 1].setFocused();
+				}
+				break;
+			}
+			case "Up":
+			case "ArrowUp": {
+				if ($props.orientation === "vertical" && headerIndex > 0) {
+					e.preventDefault();
+					itemStates[headerIndex - 1].setFocused();
+				}
+				break;
+			}
+			case "Right":
+			case "ArrowRight": {
+				if ($props.orientation === "horizontal" && headerIndex < itemStates.length - 1) {
+					e.preventDefault();
+					itemStates[headerIndex + 1].setFocused();
+				}
+				break;
+			}
+			case "Down":
+			case "ArrowDown": {
+				if ($props.orientation === "vertical" && headerIndex < itemStates.length - 1) {
+					e.preventDefault();
+					itemStates[headerIndex + 1].setFocused();
+				}
+				break;
+			}
+			case "Home": {
+				if (headerIndex > 0) {
+					e.preventDefault();
+					itemStates[0].setFocused();
+				}
+				break;
+			}
+			case "End": {
+				if (headerIndex < itemStates.length - 1) {
+					e.preventDefault();
+					itemStates[itemStates.length - 1].setFocused();
+				}
+				break;
+			}
+		}
+	}
+
+	@render {
+		<div
+			id={$props.id}
+			class={`torp-tab-group ${$props.class ?? ""}`.trim()}
+			data-orientation={$props.orientation}
+		>
+			<:slot />
+		</div>
+	}
+}

package/src/TabGroup/TabGroupTypes.ts

@@ -0,0 +1,39 @@
+export const TabGroupContextName = "TabGroup";
+export const TabItemContextName = "TabItem";
+
+export interface TabGroupContext {
+	/** Called from a header when it is added */
+	registerHeader: (index: number, value: string, setFocused: () => void) => ItemState;
+	/** Called from an item when it is added */
+	registerItem: (index: number, value: string) => ItemState;
+	/** Called from an item when it is removed */
+	removeItem: (index: number) => void;
+	/** Called from an item when it is triggered */
+	triggerItem: (value: string) => void;
+	/** Called from a TabHeader when it receives a keyboard event */
+	handleHeaderKey: (index: number, e: KeyboardEvent) => void;
+	orientation: "horizontal" | "vertical";
+	activation: "automatic" | "manual";
+}
+
+export interface TabItemContext {
+	/** Called when an item is triggered */
+	triggerItem: (value: string) => void;
+	/** Called when a TabHeader receives a keyboard event */
+	handleHeaderKey: (index: number, e: KeyboardEvent) => void;
+	/** The reactive state for an item */
+	state: ItemState;
+}
+
+export interface ItemState {
+	index: number;
+	value: string;
+	active: boolean;
+	headerId: string;
+	contentId: string;
+	disabled: boolean;
+	parentDisabled: boolean;
+	dataState: "active" | "inactive";
+	/** Called in the TabGroup when a header needs to be focused */
+	setFocused: () => void;
+}

package/src/TabGroup/TabHeader.torp

@@ -0,0 +1,62 @@
+import { TabGroupContextName, TabItemContextName, type TabGroupContext, type TabItemContext } from "./TabGroupTypes";
+
+/**
+ * The header for a tab item, which contains the TabTrigger.
+ *
+ * The structure of a TabHeader is:
+ * 
+ * ```
+ * <TabHeader>
+ * 	<TabTrigger />
+ * </TabHeader>
+ * ```
+ *
+ * @prop {"h1" | "h2" | "h3" | "h4" | "h5" | "h6"} as -- The type of HTML header to use
+ */
+export default function TabHeader($props: any) {
+	const context = $context[TabGroupContextName] as TabGroupContext;
+	if (!context) {
+		throw new Error("TabHeader must be contained within a TabGroup");
+	}
+	let $state = $context[TabGroupContextName].registerHeader($props.index, $props.value);
+
+	const itemContext: TabItemContext = {
+		triggerItem: context.triggerItem,
+		handleHeaderKey: context.handleHeaderKey,
+		state: $state,
+	};
+	$context[TabItemContextName] = itemContext;
+
+	// Remove the item from the parent TabGroup when this item is destroyed
+	$run(() => {
+		return () => {
+			context.removeItem($state.index);
+		}
+	});
+
+	@render {
+		@// TODO: $props.as
+		<h4
+			id={$props.id}
+			:class={[
+				"torp-tab-header",
+				$props.class,
+				$state.orientation
+			]}
+			data-state={$state.dataState}
+			data-disabled={$state.dataDisabled}
+		>
+			<:slot />
+		</h4>
+	}
+
+	@style {
+		.torp-tab-header.horizontal {
+			display: inline-block;
+		}
+
+		.torp-tab-header.vertical {
+			display: block;
+		}
+	}
+}

package/src/TabGroup/TabList.torp

@@ -0,0 +1,50 @@
+import { TabGroupContextName, TabItemContextName, type TabGroupContext, type TabItemContext } from "./TabGroupTypes";
+
+/**
+ * A component that holds the TabHeaders of a TabGroup.
+ * 
+ * The structure of a TabList is:
+ * 
+ * ```
+ * <TabList>
+ * 	<TabHeader>
+ * 		<TabTrigger />
+ * 	</TabHeader>
+ * </TabList>
+ * ```
+ *
+ * @prop {string} ariaLabel -- An ARIA label for describing the tab list to screen readers
+ */
+export default function TabList($props: any) {
+	// Get stuff out of the TabGroupContext
+	const context = $context[TabGroupContextName] as TabGroupContext;
+	if (!context) {
+		throw new Error("TabList must be contained within a TabGroup");
+	}
+	// TODO: const { orientation } = context;
+	const orientation = context.orientation;
+
+	function handleFocus(e: FocusEvent & { currentTarget: EventTarget & HTMLElement }) {
+		// TODO: Should this be the first button?
+		const el = e.currentTarget.childNodes[0];
+		if (el instanceof HTMLElement) {
+			el.focus();
+			e.preventDefault();
+		}
+	}
+
+	@render {
+		<div
+			id={$props.id}
+			class={`torp-tab-list ${$props.class ?? ""}`.trim()}
+			role="tablist"
+			aria-label={$props.ariaLabel}
+			aria-orientation={orientation}
+			data-orientation={orientation}
+			tabindex="0"
+			onfocus={handleFocus}
+		>
+			<:slot />
+		</div>
+	}
+}

package/src/TabGroup/TabTrigger.torp

@@ -0,0 +1,65 @@
+import getId from "../utils/getId";
+import { TabItemContextName, type TabItemContext } from "./TabGroupTypes";
+
+/**
+ * A header button for a tab item, which can be used to reveal an associated TabContent.
+ */
+export default function TabTrigger() {
+	let button: HTMLButtonElement;
+
+	$props.id ||= getId();
+
+	// Get stuff out of the TabItemContext
+	const context = $context[TabItemContextName] as TabItemContext;
+	if (!context) {
+		throw new Error("TabTrigger must be contained within a TabHeader");
+	}
+	let $state = $context[TabItemContextName].state;
+
+	// Set the header ID so that it can be used with aria-labelledby in TabContent
+	$state.headerId = $props.id;
+
+	// Let the item know how to set the button's focus
+	$state.setFocused = setFocused;
+
+	// This function is called by the parent TabGroup to focus this item's button
+	function setFocused() {
+		button.focus();
+		if ($state.activation === "automatic") {
+			context.triggerItem($state.value);
+		}
+	}
+
+	function handleClick() {
+		// Pass the value to the triggerItem method in the parent TabGroup which will handle toggling
+		// the value of active for all items (e.g. to close other items if necessary)
+		context.triggerItem($state.value);
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		// Pass the key press up to the parent TabGroup which will handle setting the focused button
+		context.handleHeaderKey($state.index, e);
+	}
+
+	@render {
+		<button
+			type="button"
+			id={$props.id}
+			class={`torp-tab-trigger ${$props.class ?? ""}`.trim()}
+			role="tab"
+			tabindex="-1"
+			disabled={$state.disabled || $state.parentDisabled}
+			aria-selected={$state.active.toString()}
+			aria-disabled={$state.disabled}
+			aria-controls={$state.contentId}
+			data-state={$state.dataState}
+			data-disabled={$state.disabled}
+			data-orientation={$state.orientation}
+			&ref={button}
+			onclick={handleClick}
+			onkeydown={handleKey}
+		>
+			<:slot />
+		</button>
+	}
+}

package/src/TabGroup/index.ts

@@ -0,0 +1,7 @@
+import TabContent from "./TabContent.torp";
+import TabGroup from "./TabGroup.torp";
+import TabHeader from "./TabHeader.torp";
+import TabList from "./TabList.torp";
+import TabTrigger from "./TabTrigger.torp";
+
+export { TabGroup, TabList, TabHeader, TabTrigger, TabContent };

package/src/TabGroup.ts

@@ -0,0 +1,7 @@
+import TabContent from "./TabGroup/TabContent.torp";
+import TabGroup from "./TabGroup/TabGroup.torp";
+import TabHeader from "./TabGroup/TabHeader.torp";
+import TabList from "./TabGroup/TabList.torp";
+import TabTrigger from "./TabGroup/TabTrigger.torp";
+
+export { TabGroup, TabList, TabHeader, TabTrigger, TabContent };

package/src/mount/disableScroll.ts

@@ -0,0 +1,28 @@
+export function disableScroll(): () => void {
+	// Remember body styles
+	const overflowX = document.body.style.overflowY;
+	const overflowY = document.body.style.overflowY;
+	const overscrollBehaviourX = document.body.style.overscrollBehaviorX;
+	const overscrollBehaviourY = document.body.style.overscrollBehaviorY;
+	const marginRight = document.body.style.marginRight;
+
+	// Get scrollbar width (if visible) so that we can set a margin to avoid things jumping around
+	// HACK: Does this work in all browsers/systems?
+	const scrollBarWidth = window.innerWidth - document.body.clientWidth;
+
+	// Set body styles to disallow scrolling
+	document.body.style.overflowY = "hidden";
+	document.body.style.overflowY = "hidden";
+	document.body.style.overscrollBehaviorX = "contain";
+	document.body.style.overscrollBehaviorY = "contain";
+	document.body.style.marginRight = scrollBarWidth + "px";
+
+	return () => {
+		// Reset body styles
+		document.body.style.overflowY = overflowX;
+		document.body.style.overflowY = overflowY;
+		document.body.style.overscrollBehaviorX = overscrollBehaviourX;
+		document.body.style.overscrollBehaviorY = overscrollBehaviourY;
+		document.body.style.marginRight = marginRight;
+	};
+}

package/src/mount/hoverTrigger.ts

@@ -0,0 +1,59 @@
+interface HoverTriggerOptions {
+	onHover: (node: HTMLElement, e: TouchEvent | MouseEvent) => void;
+	onExit?: (node: HTMLElement, e: TouchEvent | MouseEvent) => void;
+	hoverDelay?: number;
+	touchDelay?: number;
+}
+
+export default function hoverTrigger(node: HTMLElement, options: HoverTriggerOptions): () => void {
+	const { onHover, onExit } = options;
+	const hoverDelay = options.hoverDelay || 1000;
+	const touchDelay = options.touchDelay || 1000;
+
+	let interval: NodeJS.Timeout | undefined;
+
+	// Add click event handlers to the node
+	node.addEventListener("mouseenter", handleMouseEnter);
+	node.addEventListener("mouseleave", handleMouseLeave);
+	node.addEventListener("mousemove", handleMouseMove);
+	node.addEventListener("touchstart", handleMouseEnter);
+	node.addEventListener("touchend", handleMouseLeave);
+
+	function handleMouseEnter(e: MouseEvent | TouchEvent) {
+		// Handle the hover after a delay
+		e.preventDefault();
+		if (!interval) {
+			const delay = e.type.startsWith("mouse") ? hoverDelay : touchDelay;
+			interval = setTimeout(() => onHover(node, e), delay);
+		}
+	}
+
+	function handleMouseLeave(e: MouseEvent | TouchEvent) {
+		// Prevent short hovers or touches from firing the event
+		if (interval) {
+			clearTimeout(interval);
+			interval = undefined;
+		}
+
+		if (onExit) {
+			onExit(node, e);
+		}
+	}
+
+	function handleMouseMove(e: MouseEvent) {
+		// Reset the interval on mouse move
+		if (interval) {
+			clearTimeout(interval);
+			interval = setTimeout(() => onHover(node, e), hoverDelay);
+		}
+	}
+
+	// Remove the event listeners from the node on destroy
+	return () => {
+		node.removeEventListener("mouseenter", handleMouseEnter);
+		node.removeEventListener("mouseleave", handleMouseLeave);
+		node.removeEventListener("mousemove", handleMouseMove);
+		node.removeEventListener("touchstart", handleMouseEnter);
+		node.removeEventListener("touchend", handleMouseLeave);
+	};
+}

package/src/mount/trapFocus.ts

@@ -0,0 +1,58 @@
+export interface TrapFocusOptions {
+	focusableElements: HTMLElement[];
+}
+
+export function trapFocus(node: HTMLElement, options?: TrapFocusOptions): () => void {
+	options = options || { focusableElements: [] };
+
+	// Selectors for all things that are focusable:
+	const focusableSelectors = [
+		"a[href]",
+		"area[href]",
+		'input:not([disabled]):not([type="hidden"]):not([aria-hidden])',
+		"select:not([disabled]):not([aria-hidden])",
+		"textarea:not([disabled]):not([aria-hidden])",
+		"button:not([disabled]):not([aria-hidden])",
+		"iframe",
+		"object",
+		"embed",
+		"[contenteditable]",
+		'[tabindex]:not([tabindex^="-"])',
+	];
+
+	// Set the focusable elements array in the options, which can be used in the caller e.g. to focus the first element
+	options.focusableElements = Array.from(node.querySelectorAll(focusableSelectors.join()));
+
+	// Store first and last focusable elements
+	const firstFocusableElement = options.focusableElements[0] as HTMLElement;
+	const lastFocusableElement = options.focusableElements[
+		options.focusableElements.length - 1
+	] as HTMLElement;
+
+	// Add the keydown event listener to the node
+	node.addEventListener("keydown", handleKey);
+
+	// On Tab or Shift+Tab, move through the focusable elements, wrapping at either end
+	function handleKey(e: KeyboardEvent) {
+		if (e.key === "Tab") {
+			if (e.shiftKey) {
+				if (document.activeElement === firstFocusableElement) {
+					// Shift + Tab on the first element, so move to the last one
+					lastFocusableElement.focus();
+					e.preventDefault();
+				}
+			} else {
+				if (document.activeElement === lastFocusableElement) {
+					// Tab on the last element, so move to the first one
+					firstFocusableElement.focus();
+					e.preventDefault();
+				}
+			}
+		}
+	}
+
+	// Remove the keydown event listener from the node on destroy
+	return () => {
+		node.removeEventListener("keydown", handleKey);
+	};
+}

package/src/utils/documentEvents.ts

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

package/src/utils/getScrollParent.ts

@@ -0,0 +1,22 @@
+// From https://stackoverflow.com/a/76535387
+export default function getScrollParent(node: Element): Element {
+	let currentParent = node.parentElement;
+	while (currentParent) {
+		if (isScrollable(currentParent)) {
+			return currentParent;
+		}
+		currentParent = currentParent.parentElement;
+	}
+	return document.scrollingElement || document.documentElement;
+}
+
+function isScrollable(node: Element): boolean {
+	if (!(node instanceof HTMLElement || node instanceof SVGElement)) {
+		return false;
+	}
+	const style = getComputedStyle(node);
+	return ["overflow", "overflow-x", "overflow-y"].some((propertyName) => {
+		const value = style.getPropertyValue(propertyName);
+		return value === "auto" || value === "scroll";
+	});
+}

package/src/utils/setContextPosition.ts

@@ -0,0 +1,31 @@
+interface Point {
+	x: number;
+	y: number;
+}
+
+export default function setContextPosition(
+	anchor: HTMLElement,
+	content: HTMLElement,
+	position: Point,
+): void {
+	var anchorRect = anchor.getBoundingClientRect();
+	var contentRect = content.getBoundingClientRect();
+
+	content.style.position = "fixed";
+
+	// Try to make sure the content is entirely on the screen horizontally
+	// Just move it left or right -- the pointer is outside the content vertically so moving it left
+	// or right won't make the content appear over the cursor
+	let left = anchorRect.left + position.x;
+	left = Math.min(left, window.innerWidth - contentRect.width);
+	left = Math.max(left, 0);
+	content.style.left = left + "px";
+
+	// Try to make sure the content is entirely on the screen vertically
+	// Show it above the position if it wouldn't fit
+	let top = anchorRect.top + position.y;
+	if (top + contentRect.height > window.innerHeight) {
+		top -= contentRect.height;
+	}
+	content.style.top = top + "px";
+}