@torpor/ui 0.4.0 → 1.0.1

package/dist/Contextual/Contextual.torp

@@ -1,30 +1,32 @@
-import type { ClassValue, StyleValue } from "@torpor/view";
-import { ContextualContextName, type Point, type ContextualContext, type ContextualState } from "./ContextualTypes";
-import { PopoutContextName, type PopoutContext } from "../utils/PopoutTypes";
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import $handle from "../utils/$handle";
+import { type PopoutContext, PopoutContextName } from "../utils/PopoutTypes";
+import {
+	type ContextualContext,
+	ContextualContextName,
+	type ContextualState,
+	type Point,
+} from "./ContextualTypes";
 
 interface ContextualProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
+	style?: StyleValue;
 	/** Whether the contextual is modal. If true, an overlay should be supplied to obscure outside content, and only the context content will be visible to screen readers  */
-	modal?: boolean,
+	modal?: boolean;
 	/** Whether the contextual is visible  */
-	visible?: boolean,
+	visible: Bindable<boolean | undefined>;
 	/** The element to anchor this contextual to, as an alternative to supplying a ContextualTrigger  */
-	anchor?: HTMLElement,
+	anchor?: HTMLElement;
 	/** The position to display this contextual at  */
-	position?: Point,
-	/** A function to be called when the user selects a response */
-	callback?: ((value: any) => void),
-	/** Raised when this contextual is opened or closed */
-	ontoggle?: (open: boolean) => void,
+	position?: Point;
 	/** Raised when the contextual has opened */
-	onopen?: () => void,
+	onopen?: () => void;
 	/** Raised when the contextual has closed */
-	onclose?: (result: any) => void,
+	onclose?: (result: any) => void;
 }
 
 /**
@@ -42,19 +44,16 @@ interface ContextualProps {
 export default function Contextual($props: ContextualProps | undefined) {
 	let $state: ContextualState = $watch({
 		visible: false,
-		position: { x: 0, y: 0 }
-	})
+		position: { x: 0, y: 0 },
+		contentId: undefined,
+		triggerId: undefined,
+		contentRole: undefined,
+	});
 
-	// Sync props and state
+	$bind($state, $props, "visible");
 	$run(() => {
-		$state.visible = $props?.visible ?? false;
 		$state.position = $props?.position ?? { x: 0, y: 0 };
 	});
-	$run(() => {
-		if ($props !== undefined) {
-			$props.visible = $state.visible;
-		}
-	});
 
 	let result: any;
 
@@ -72,22 +71,14 @@ export default function Contextual($props: ContextualProps | undefined) {
 	let popoutContext: PopoutContext = context;
 	$context[PopoutContextName] = popoutContext;
 
-	// Dispatch the toggle event when the contextual is opened or closed
-	let firstToggle = true;
-	$run(() => {
-		const ontoggle = $props?.ontoggle;
-		const onopen = $props?.onopen;
-		const onclose = $props?.onclose;
+	// Dispatch the open/close events when the contextual is opened or closed
+	$handle((first) => {
 		const visible = $state.visible;
-		if (firstToggle) {
-			firstToggle = false;
+		if (first) return;
+		if (visible) {
+			$props?.onopen?.();
 		} else {
-			if (ontoggle) ontoggle(visible);
-			if (visible) {
-				if (onopen) onopen()
-			} else {
-				if (onclose) onclose(result);
-			}
+			$props?.onclose?.(result);
 		}
 	});
 
@@ -110,25 +101,16 @@ export default function Contextual($props: ContextualProps | undefined) {
 
 		// Hide the contextual
 		$state.visible = false;
-
-		// Call the callback
-		if ($props?.callback) {
-			$props.callback(result);
-		}
 	}
 
-	function handleClickOutside(e: MouseEvent) {
+	function handleClickOutside(e: MouseEvent | KeyboardEvent) {
 		e.preventDefault();
 		$state.visible = false;
 	}
 
 	@render {
-		<div
-			{$props?.id}
-			class={["torp-context", $props?.class]}
-			{$props?.style}
-		>
+		<div {$props?.id} class={["torp-context", $props?.class]} {$props?.style}>
 			<slot />
 		</div>
 	}
-}
+}

package/dist/Contextual/ContextualContent.torp

@@ -1,26 +1,24 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { addDocumentEvent, removeDocumentEvent } from "../utils/documentEvents";
-import getScrollParent from "../utils/getScrollParent";
+import getId from "../utils/getId";
+import { createPopoutContent } from "../utils/popoutContent";
 import setContextPosition from "../utils/setContextPosition";
-import { ContextualContextName, type ContextualContext } from "./ContextualTypes";
+import { type ContextualContext, ContextualContextName } from "./ContextualTypes";
 
 interface ContextualContentProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
+	style?: StyleValue;
 }
 
 /**
  * The content that is displayed for a Contextual when it is open, displayed at the
  * position that the user right-clicked.
  */
-export default function ContextualContent($props: ContextualContentProps | undefined) {	
-	let div: HTMLDivElement;
-	let shown = false;
-	let closeOnClick = false;
+export default function ContextualContent($props: ContextualContentProps | undefined) {
+	let defaultId = getId();
 
 	// Get stuff out of the ContextualContext
 	const context = $context[ContextualContextName] as ContextualContext;
@@ -29,81 +27,39 @@ export default function ContextualContent($props: ContextualContentProps | undef
 	}
 	let $state = context.state;
 
-	$run(() => {
-		if (!$state.visible) {
-			hide();
-		}
-	});
-
-	function show() {
-		shown = true;
-
-		// HACK: Because this Contextual 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);
-
-		// Set the position and listen for window resize and scroll to reset the position
-		setPosition();
-		const anchorElement = context.anchorElement!;
-		const scrollParent = getScrollParent(anchorElement)
-		scrollParent.addEventListener("resize", setPosition);
-		scrollParent.addEventListener("scroll", setPosition);
-		if (context.focusFirstElement) {
-			context.focusFirstElement();
-		}
-	}
-
-	function hide() {
-		if (!shown) return;
-
-		removeDocumentEvent("mousedown", handleDocumentMouseDown);
-		removeDocumentEvent("click", handleDocumentClick);
-
-		// Stop listening for window resize and focus the anchor element per WAI guidelines
-		const anchorElement = context.anchorElement!;
-		const scrollParent = getScrollParent(anchorElement)
-		scrollParent.removeEventListener("resize", setPosition);
-		scrollParent.removeEventListener("scroll", setPosition);
-		if (anchorElement.focus) {
-			anchorElement.focus();
-		}
-	}
-
-	function handleDocumentMouseDown() {
-		closeOnClick = true;
-	}
+	// Set the content ID so that the trigger can use it with aria-controls
+	$state.contentId = $props?.id ?? defaultId;
 
-	function handleDocumentClick(e: MouseEvent) {
-		if (
-			closeOnClick &&
-			div &&
-			!div.contains(e.target as HTMLElement) &&
-			(!context.anchorElement || !context.anchorElement.contains(e.target as HTMLElement))
-		) {
-			context.handleClickOutside!(e);
-		}
-	}
+	const popout = createPopoutContent({
+		getAnchor: () => context.anchorElement,
+		getContent: () => div,
+		close: (e) => context.handleClickOutside?.(e),
+		position: () => {
+			if (context.anchorElement && div && $state.position) {
+				setContextPosition(context.anchorElement, div, $state.position);
+			}
+		},
+		ignoreAnchorClicks: true,
+		focusFirstElement: () => context.focusFirstElement?.(),
+		refocusAnchorOnHide: true,
+	});
 
-	function setPosition() {
-		if (!context.anchorElement) {
-			throw new Error("ContextualContent must have an anchor element");
-		}
+	let div: HTMLDivElement;
 
-		if ($state.position) {
-			setContextPosition(context.anchorElement, div, $state.position);
+	$run(() => {
+		if (!$state.visible) {
+			popout.hide();
 		}
-	}
+	});
 
 	@render {
 		@if ($state.visible) {
 			<div
-				{$props?.id}
+				id={$props?.id ?? defaultId}
 				class={["torp-popover-content-contextual", $props?.class]}
 				{$props?.style}
 				&ref={div}
-				onmount={show}
+				onmount={(_el) => popout.show()}
 			>
 				<slot />
 			</div>

package/dist/Contextual/ContextualHover.torp

@@ -0,0 +1,112 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { createHoverReveal } from "../utils/hoverReveal";
+import getId from "../utils/getId";
+import {
+	type ContextualContext,
+	ContextualContextName,
+} from "./ContextualTypes";
+
+interface ContextualHoverProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** Milliseconds to wait before opening (default 500; 0 opens immediately) */
+	hoverDelay?: number;
+	/** Milliseconds to wait after the pointer or focus leaves before closing (default 300) */
+	exitGrace?: number;
+	/** Whether hovering and focusing are ignored */
+	disabled?: boolean;
+}
+
+/**
+ * An element that shows a Contextual while hovered at the pointer's
+ * location, with proper hover semantics: an intent delay before opening
+ * (so passing over the element doesn't flash a window), and an exit grace
+ * period after leaving (so moving into the contextual content doesn't close
+ * it).
+ *
+ * Focusing the element opens it immediately; blurring closes it. Use this
+ * in place of ContextualTrigger:
+ *
+ * ```
+ * <Contextual>
+ * 	<ContextualHover>Anything can go here</ContextualHover>
+ * 	<ContextualContent />
+ * </Contextual>
+ * ```
+ */
+export default function ContextualHover($props?: ContextualHoverProps) {
+	let defaultId = getId();
+
+	// Get stuff out of the ContextualContext
+	const context = $context[ContextualContextName] as ContextualContext;
+	if (!context) {
+		throw new Error("ContextualHover must be contained within a Contextual");
+	}
+	const $state = context.state;
+
+	// Set the trigger ID so that it can be used with aria-labelledby
+	$state.triggerId = $props?.id ?? defaultId;
+
+	let node: HTMLElement;
+
+	function activate(e: MouseEvent | TouchEvent) {
+		if ($state.position) {
+			// Get the position relative to the element, so we can reposition on scroll
+			const rect = node.getBoundingClientRect();
+			const point = e instanceof TouchEvent ? e.touches[0] : e;
+			$state.position = {
+				x: (point?.clientX ?? 0) - rect.left,
+				y: (point?.clientY ?? 0) - rect.top,
+			};
+		}
+	}
+
+	function setVisible(visible: boolean) {
+		$state.visible = visible;
+	}
+
+	const hover = createHoverReveal({
+		show: () => setVisible(true),
+		hide: () => setVisible(false),
+		isVisible: () => $state.visible,
+		disabled: () => $props?.disabled === true,
+		getContent: () => ($state.contentId ? document.getElementById($state.contentId) : undefined),
+		hoverDelay: $props?.hoverDelay,
+		exitGrace: $props?.exitGrace,
+	});
+
+	$run(() => {
+		return () => hover.dispose();
+	});
+
+	function handleEnter() {
+		activate({ clientX: node.offsetWidth / 2, clientY: node.offsetHeight / 2 } as MouseEvent);
+		hover.handleEnter();
+	}
+
+	@render {
+		<div
+			id={$props?.id ?? defaultId}
+			class={["torp-contextual-hover", $props?.class]}
+			{$props?.style}
+			tabindex="0"
+			aria-haspopup={$state.contentRole ?? "true"}
+			aria-expanded={$state.visible ? "true" : "false"}
+			aria-controls={$state.contentId}
+			onmouseenter={handleEnter}
+			onmouseleave={(e: MouseEvent) => hover.handleLeave(e)}
+			onfocus={() => hover.handleFocus()}
+			onblur={(e: FocusEvent) => hover.handleBlur(e)}
+			onmount={(el) => {
+				node = el;
+				context.anchorElement = el;
+			}}
+		>
+			<slot />
+		</div>
+	}
+}

package/dist/Contextual/ContextualTrigger.torp

@@ -1,70 +1,59 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { ContextualContextName, type ContextualContext } from "./ContextualTypes";
-import hoverTrigger from "../mount/hoverTrigger";
+import PopoutClickTrigger from "../utils/PopoutClickTrigger.torp";
+import {
+	type ContextualContext,
+	ContextualContextName,
+	type Point,
+} from "./ContextualTypes";
 
 interface ContextualTriggerProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
-	/** Whether the popover is activated by click/press or by hover **/
-	activation?: "press" | "hover"
+	style?: StyleValue;
 }
 
 /**
- * The element that causes a Contextual to appear or disappear when right-clicked.
+ * The element that causes a Contextual to appear or disappear when
+ * right-clicked.
+ *
+ * For hover activation, use ContextualHover instead -- hover surfaces need
+ * an intent delay and an exit grace period that a right-click region
+ * doesn't.
  */
-export default function ContextualTrigger($props: ContextualTriggerProps | undefined) {
-	let activation = $props?.activation ?? "press";
-
+export default function ContextualTrigger($props?: ContextualTriggerProps) {
 	// Get stuff out of the ContextualContext
 	const context = $context[ContextualContextName] as ContextualContext;
 	if (!context) {
 		throw new Error("ContextualTrigger must be contained within a Contextual");
 	}
-	let $state = context.state;
-
-	function handleContextualMenu(e: MouseEvent & { currentTarget: EventTarget & HTMLDivElement }) {
-		if (activation !== "press") return;
-
-		e.preventDefault();
-		if ($state.position) {
-			// Get the position relative to the element, so we can reposition on scroll
-			const rect = e.currentTarget.getBoundingClientRect();
-			const x = e.clientX - rect.left;
-			const y = e.clientY - rect.top;
-			$state.position = { x, y };
-			//$state.position = { x: window.scrollX + e.clientX, y: window.scrollY + e.clientY };
-		}
-		$state.visible = !$state.visible;
-	}
-
-	function handleHover(node: HTMLElement, e: MouseEvent) {
-		if (activation !== "hover") return;
+	const $state = context.state;
 
+	function activate(node: HTMLElement, e: MouseEvent) {
 		if ($state.position) {
 			// Get the position relative to the element, so we can reposition on scroll
 			const rect = node.getBoundingClientRect();
-			const x = e.clientX - rect.left;
-			const y = e.clientY - rect.top;
-			$state.position = { x, y };
-			//$state.position = { x: window.scrollX + e.clientX, y: window.scrollY + e.clientY };
+			const point: Point = {
+				x: e.clientX - rect.left,
+				y: e.clientY - rect.top,
+			};
+			$state.position = point;
 		}
-		$state.visible = !$state.visible
 	}
 
 	@render {
-		<div
-			{$props?.id}
-			class={["torp-popover-trigger-contextual", $props?.class]}
-			{$props?.style}
-			oncontextmenu={handleContextualMenu}
-			onmount={(el) => hoverTrigger(el, { onHover: handleHover, onExit: handleHover })}
-			&ref={context.anchorElement}
+		<PopoutClickTrigger
+			id={$props?.id}
+			class={$props?.class ?? "torp-popover-trigger-contextual"}
+			style={$props?.style}
+			context={context}
+			tag="div"
+			event="contextmenu"
+			onactivate={activate}
 		>
 			<slot />
-		</div>
+		</PopoutClickTrigger>
 	}
 }

package/dist/Contextual/ContextualTypes.ts

@@ -1,26 +1,13 @@
+import { type PopoutContext, type PopoutState } from "../utils/PopoutTypes";
+
 export const ContextualContextName: unique symbol = Symbol.for("torp.Contextual");
 
 /** The shared context for popover components (Contextual, Prompt and Contextual) */
-export interface ContextualContext {
-	handleButton: (type: "confirm" | "cancel" | undefined, value?: any) => void;
-	// HACK: We need to be able to let children (i.e. Dialogs) override the click outside functionality
-	// There may be a more elegant way to accomplish this too
-	handleClickOutside?: (e: MouseEvent) => void;
+export interface ContextualContext extends PopoutContext {
 	state: ContextualState;
-	//modal: boolean;
-	anchorElement?: HTMLElement;
-	// HACK: focusFirstElement is necessary because if we focus the first element e.g. in a Dialog's
-	// onMount, it will scroll the page to the focused element and mess up our careful positioning
-	// We need to be able to manually set the order to
-	// 1. set visible (so we have an element with content)
-	// 2. set position (so the element is in the right place)
-	// 3. set focus (for accessibility)
-	// There may be a more elegant way to accomplish this!
-	focusFirstElement?: () => void;
 }
 
-export interface ContextualState {
-	visible: boolean;
+export interface ContextualState extends PopoutState {
 	position: Point;
 }
 

package/dist/Contextual/index.d.ts

@@ -5,25 +5,21 @@ interface ContextualProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
+	style?: StyleValue;
 	/** Whether the contextual is modal. If true, an overlay should be supplied to obscure outside content, and only the context content will be visible to screen readers  */
-	modal?: boolean,
+	modal?: boolean;
 	/** Whether the contextual is visible  */
-	visible?: boolean,
+	visible: Bindable<boolean | undefined>;
 	/** The element to anchor this contextual to, as an alternative to supplying a ContextualTrigger  */
-	anchor?: HTMLElement,
+	anchor?: HTMLElement;
 	/** The position to display this contextual at  */
-	position?: Point,
-	/** A function to be called when the user selects a response */
-	callback?: ((value: any) => void),
-	/** Raised when this contextual is opened or closed */
-	ontoggle?: (open: boolean) => void,
+	position?: Point;
 	/** Raised when the contextual has opened */
-	onopen?: () => void,
+	onopen?: () => void;
 	/** Raised when the contextual has closed */
-	onclose?: (result: any) => void,
+	onclose?: (result: any) => void;
 }
 
 /**
@@ -52,9 +48,9 @@ interface ContextualContentProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
+	style?: StyleValue;
 }
 
 /**
@@ -71,26 +67,47 @@ declare function ContextualContent(
 
 
 
-interface ContextualTriggerProps {
-	/** An ID for the root element */
-	id?: string;
-	/** Classes for the root element */
-	class?: ClassValue,
-	/** Styles for the root element */
-	style?: StyleValue,
-	/** Whether the popover is activated by click/press or by hover **/
-	activation?: "press" | "hover"
-}
+/**
+ * An element that shows a Contextual while hovered at the pointer's
+ * location, with proper hover semantics: an intent delay before opening
+ * (so passing over the element doesn't flash a window), and an exit grace
+ * period after leaving (so moving into the contextual content doesn't close
+ * it).
+ *
+ * Focusing the element opens it immediately; blurring closes it. Use this
+ * in place of ContextualTrigger:
+ *
+ * ```
+ * <Contextual>
+ * 	<ContextualHover>Anything can go here</ContextualHover>
+ * 	<ContextualContent />
+ * </Contextual>
+ * ```
+ */
+declare function ContextualHover(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props?: ContextualHoverProps,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
 
 /**
- * The element that causes a Contextual to appear or disappear when right-clicked.
+ * The element that causes a Contextual to appear or disappear when
+ * right-clicked.
+ *
+ * For hover activation, use ContextualHover instead -- hover surfaces need
+ * an intent delay and an exit grace period that a right-click region
+ * doesn't.
  */
 declare function ContextualTrigger(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props: ContextualTriggerProps | undefined,
+	$props?: ContextualTriggerProps,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
-export { Contextual, ContextualContent, ContextualTrigger };
+export { Contextual, ContextualContent, ContextualHover, ContextualTrigger };

package/dist/Contextual/index.js

@@ -1,14 +1,5 @@
-// src/Contextual/Contextual.torp
-import Contextual_default from "./Contextual.torp";
-
-// src/Contextual/ContextualContent.torp
-import ContextualContent_default from "./ContextualContent.torp";
-
-// src/Contextual/ContextualTrigger.torp
-import ContextualTrigger_default from "./ContextualTrigger.torp";
-export {
-  Contextual_default as Contextual,
-  ContextualContent_default as ContextualContent,
-  ContextualTrigger_default as ContextualTrigger
-};
-//# sourceMappingURL=index.js.map
+import Contextual from "./Contextual.torp";
+import ContextualContent from "./ContextualContent.torp";
+import ContextualHover from "./ContextualHover.torp";
+import ContextualTrigger from "./ContextualTrigger.torp";
+export { Contextual, ContextualContent, ContextualHover, ContextualTrigger };