@torpor/ui 0.3.7 → 1.0.0

package/dist/Popover/PopoverContent.torp

@@ -1,20 +1,19 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { addDocumentEvent, removeDocumentEvent } from "../utils/documentEvents";
-import getScrollParent from "../utils/getScrollParent";
-import setPopoverPosition from "../utils/setPopoverPosition";
-import { PopoverContextName, type PopoverContext } from "./PopoverTypes";
+import getId from "../utils/getId";
+import { createPopoutContent } from "../utils/popoutContent";
+import { type PopoverContext, PopoverContextName } from "./PopoverTypes";
 
 interface PopoverContentProps {
 	/** 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;
 	/** Where the popover will be shown, relative to the popover trigger */
-	side?: "top" | "right" | "bottom" | "left",
+	side?: "top" | "right" | "bottom" | "left";
 	/** How the popover will be aligned, relative to the popover trigger */
-	alignment?: "start" | "center" | "end",
+	alignment?: "start" | "center" | "end";
 }
 
 /**
@@ -22,9 +21,7 @@ interface PopoverContentProps {
  * alongside an element.
  */
 export default function PopoverContent($props?: PopoverContentProps | undefined) {
-	let div: HTMLDivElement;
-	let shown = false;
-	let closeOnClick = false;
+	let defaultId = getId();
 
 	// Get stuff out of the PopoverContext
 	const context = $context[PopoverContextName] as PopoverContext;
@@ -33,82 +30,36 @@ export default function PopoverContent($props?: PopoverContentProps | undefined)
 	}
 	let $state = context.state;
 
-	$run(() => {
-		if (!$state.visible) {
-			hide();
-		}
-	});
-
-	function show() {
-		shown = true;
-
-		// HACK: Because this Popover 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 content ID so that the trigger can use it with aria-controls
+	$state.contentId = $props?.id ?? defaultId;
 
-		// 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;
-	}
+	const popout = createPopoutContent({
+		getAnchor: () => context.anchorElement,
+		getContent: () => div,
+		close: (e) => context.handleClickOutside?.(e),
+		side: $props?.side ?? "bottom",
+		alignment: $props?.alignment ?? "center",
+		ignoreAnchorClicks: true,
+		focusFirstElement: () => context.focusFirstElement?.(),
+		refocusAnchorOnHide: true,
+	});
 
-	function handleDocumentClick(e: MouseEvent) {
-		if (
-			closeOnClick &&
-			div &&
-			!div.contains(e.target as HTMLElement) &&
-			(!context.anchorElement || !context.anchorElement.contains(e.target as HTMLElement))
-		) {
-			e.preventDefault();
-			context.handleClickOutside!(e);
-		}
-	}
+	let div: HTMLDivElement;
 
-	function setPosition() {
-		if (!context.anchorElement) {
-			throw new Error("Popover must have an anchor element");
+	$run(() => {
+		if (!$state.visible) {
+			popout.hide();
 		}
-
-		let side = $props?.side ?? "bottom";
-		let alignment = $props?.alignment ?? "center";
-		setPopoverPosition(context.anchorElement, div, side, alignment);
-	}
+	});
 
 	@render {
 		@if ($state.visible) {
 			<div
-				{$props?.id}
+				id={$props?.id ?? defaultId}
 				class={["torp-popover-content", $props?.class]}
 				{$props?.style}
 				&ref={div}
-				onmount={show}
+				onmount={(_el) => popout.show()}
 			>
 				<slot />
 			</div>

package/dist/Popover/PopoverHover.torp

@@ -0,0 +1,90 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { createHoverReveal } from "../utils/hoverReveal";
+import getId from "../utils/getId";
+import { type PopoverContext, PopoverContextName } from "./PopoverTypes";
+
+interface PopoverHoverProps {
+	/** 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 Popover while hovered, with proper hover
+ * semantics: an intent delay before opening (so passing over the element
+ * doesn't flash a popover), and an exit grace period after leaving (so
+ * moving into the popover content doesn't close it).
+ *
+ * Focusing the element opens it immediately; blurring closes it. Use this
+ * in place of PopoverTrigger:
+ *
+ * ```
+ * <Popover>
+ * 	<PopoverHover>Anything can go here</PopoverHover>
+ * 	<PopoverContent />
+ * </Popover>
+ * ```
+ */
+export default function PopoverHover($props?: PopoverHoverProps) {
+	let defaultId = getId();
+
+	// Get stuff out of the PopoverContext
+	const context = $context[PopoverContextName] as PopoverContext;
+	if (!context) {
+		throw new Error("PopoverHover must be contained within a Popover");
+	}
+	const $state = context.state;
+
+	// Set the trigger ID so that it can be used with aria-labelledby
+	$state.triggerId = $props?.id ?? defaultId;
+
+	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 anchor(node: HTMLElement) {
+		context.anchorElement = node;
+	}
+
+	@render {
+		<div
+			id={$props?.id ?? defaultId}
+			class={["torp-popover-hover", $props?.class]}
+			{$props?.style}
+			tabindex="0"
+			aria-haspopup={$state.contentRole ?? "true"}
+			aria-expanded={$state.visible ? "true" : "false"}
+			aria-controls={$state.contentId}
+			onmouseenter={() => hover.handleEnter()}
+			onmouseleave={(e: MouseEvent) => hover.handleLeave(e)}
+			onfocus={() => hover.handleFocus()}
+			onblur={(e: FocusEvent) => hover.handleBlur(e)}
+			onmount={anchor}
+		>
+			<slot />
+		</div>
+	}
+}

package/dist/Popover/PopoverTrigger.torp

@@ -1,62 +1,39 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { PopoverContextName, type PopoverContext } from "./PopoverTypes";
-import hoverTrigger from "../mount/hoverTrigger";
+import PopoutClickTrigger from "../utils/PopoutClickTrigger.torp";
+import { type PopoverContext, PopoverContextName } from "./PopoverTypes";
 
 interface PopoverTriggerProps {
 	/** 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 button that causes a Popover to appear or disappear.
+ * The button that causes a Popover to appear or disappear when pressed.
+ *
+ * For hover activation, use PopoverHover instead -- hover surfaces need an
+ * intent delay and an exit grace period that a press button doesn't.
  */
-export default function PopoverTrigger($props: PopoverTriggerProps | undefined) {
-	let activation = $props?.activation ?? "press";
-
+export default function PopoverTrigger($props?: PopoverTriggerProps) {
 	// Get stuff out of the PopoverContext
 	const context = $context[PopoverContextName] as PopoverContext;
 	if (!context) {
 		throw new Error("PopoverTrigger must be contained within a Popover");
 	}
-	let $state = context.state;
-
-	function handleClick() {
-		if (activation !== "press") return;
-
-		$state.visible = !$state.visible;
-	}
-
-	function handleHover(node: HTMLElement, e: MouseEvent) {
-		if (activation !== "hover") return;
-
-		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 };
-		}
-		$state.visible = !$state.visible
-	}
 
 	@render {
-		<button
-			type="button"
-			{$props?.id}
-			class={["torp-popover-trigger", $props?.class]}
-			{$props?.style}
-			onclick={handleClick}
-			onmount={(el) => hoverTrigger(el, { onHover: handleHover, onExit: handleHover })}
-			&ref={context.anchorElement}
+		<PopoutClickTrigger
+			id={$props?.id}
+			class={$props?.class ?? "torp-popover-trigger"}
+			style={$props?.style}
+			context={context}
+			tag="button"
+			event="click"
 		>
 			<slot />
-		</button>
+		</PopoutClickTrigger>
 	}
 }

package/dist/Popover/PopoverTypes.ts

@@ -1,26 +1,13 @@
-export const PopoverContextName = "Popover";
+import { type PopoutContext, type PopoutState } from "../utils/PopoutTypes";
+
+export const PopoverContextName: unique symbol = Symbol.for("torp.Popover");
 
 /** The shared context for popover components (Contextual, Prompt and Popover) */
-export interface PopoverContext {
-	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 PopoverContext extends PopoutContext {
 	state: PopoverState;
-	//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 PopoverState {
-	visible: boolean;
+export interface PopoverState extends PopoutState {
 	position: Point;
 }
 

package/dist/Popover/index.d.ts

@@ -5,25 +5,21 @@ interface PopoverProps {
 	/** 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 popover is modal. If true, an overlay should be supplied to obscure outside content, and only the popover content will be visible to screen readers  */
-	modal?: boolean,
+	modal?: boolean;
 	/** Whether the popover is visible  */
-	visible?: boolean,
+	visible: Bindable<boolean | undefined>;
 	/** The element to anchor this popover to, as an alternative to supplying a PopoverTrigger  */
-	anchor?: HTMLElement,
+	anchor?: HTMLElement;
 	/** The position to display this popover at if it's contextual, as an alternative to supplying a PopoverTriggerContextual  */
-	position?: Point,
-	/** A function to be called when the user selects a response */
-	callback?: ((value: any) => void),
-	/** Raised when the popover is opened or closed */
-	ontoggle?: (open: boolean) => void,
+	position?: Point;
 	/** Raised when the popover has opened */
-	onopen?: () => void,
+	onopen?: () => void;
 	/** Raised when the popover has closed */
-	onclose?: (result: any) => void,
+	onclose?: (result: any) => void;
 }
 
 /**
@@ -62,26 +58,45 @@ declare function PopoverContent(
 
 
 
-interface PopoverTriggerProps {
-	/** 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 Popover while hovered, with proper hover
+ * semantics: an intent delay before opening (so passing over the element
+ * doesn't flash a popover), and an exit grace period after leaving (so
+ * moving into the popover content doesn't close it).
+ *
+ * Focusing the element opens it immediately; blurring closes it. Use this
+ * in place of PopoverTrigger:
+ *
+ * ```
+ * <Popover>
+ * 	<PopoverHover>Anything can go here</PopoverHover>
+ * 	<PopoverContent />
+ * </Popover>
+ * ```
+ */
+declare function PopoverHover(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props?: PopoverHoverProps,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
 
 /**
- * The button that causes a Popover to appear or disappear.
+ * The button that causes a Popover to appear or disappear when pressed.
+ *
+ * For hover activation, use PopoverHover instead -- hover surfaces need an
+ * intent delay and an exit grace period that a press button doesn't.
  */
 declare function PopoverTrigger(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props: PopoverTriggerProps | undefined,
+	$props?: PopoverTriggerProps,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
-export { Popover, PopoverContent, PopoverTrigger };
+export { Popover, PopoverContent, PopoverHover, PopoverTrigger };
+export { default as showPopover } from "./showPopover";

package/dist/Popover/index.js

@@ -1,21 +1,21 @@
-// src/Popover/Popover.torp
-import Popover_default from "./Popover.torp";
-
-// src/Popover/PopoverContent.torp
-import PopoverContent_default from "./PopoverContent.torp";
-
-// src/Popover/PopoverTrigger.torp
-import PopoverTrigger_default from "./PopoverTrigger.torp";
-
-// src/Popover/showPopover.ts
+import Popover from "./Popover.torp";
+import PopoverContent from "./PopoverContent.torp";
+import PopoverHover from "./PopoverHover.torp";
+import PopoverTrigger from "./PopoverTrigger.torp";
+//#region src/Popover/showPopover.ts
+/**
+* Shows a popover component in code.
+* @param popover The popover component
+* @param anchor The element to use as an anchor for the popover component
+* @param props The properties for the popover component
+* @param target The target element to show the popover in
+* @returns The value selected by the user
+*/
 function showPopover(popover, anchor, props, target) {
-  const allProps = Object.assign({}, props, { anchor });
-  popover(target || anchor.parentElement || document.body, null, allProps);
+	const allProps = Object.assign({}, props, { anchor });
+	popover(target || anchor.parentElement || document.body, null, allProps);
 }
-export {
-  Popover_default as Popover,
-  PopoverContent_default as PopoverContent,
-  PopoverTrigger_default as PopoverTrigger,
-  showPopover
-};
+//#endregion
+export { Popover, PopoverContent, PopoverHover, PopoverTrigger, showPopover };
+
 //# sourceMappingURL=index.js.map

package/dist/Popover/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/Popover/showPopover.ts"],"sourcesContent":["// TODO: Allow passing in a variable -- so that you can show an inline popover\nimport type { Component } from \"@torpor/view\";\n\n/**\n * Shows a popover component in code.\n * @param popover The popover component\n * @param anchor The element to use as an anchor for the popover component\n * @param props The properties for the popover component\n * @param target The target element to show the popover in\n * @returns The value selected by the user\n */\nexport default function showPopover(\n\tpopover: Component,\n\tanchor: HTMLElement,\n\tprops?: Record<PropertyKey, any>,\n\ttarget?: Element,\n): void {\n\t// Add the anchor element to the properties\n\tconst allProps = Object.assign({}, props, { anchor });\n\n\t// Create the popover\n\t// TODO: This needs to clean up after itself, like the mount methods do\n\tpopover(target || anchor.parentElement || document.body, null, allProps);\n}\n"],"mappings":";;;;;;;;;;AAWe,SAAR,YACN,SACA,QACA,OACA,QACO;AAEP,QAAM,WAAW,OAAO,OAAO,CAAC,GAAG,OAAO,EAAE,OAAO,CAAC;AAIpD,UAAQ,UAAU,OAAO,iBAAiB,SAAS,MAAM,MAAM,QAAQ;AACxE;","names":[]}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/Popover/showPopover.ts"],"sourcesContent":["// TODO: Allow passing in a variable -- so that you can show an inline popover\nimport type { Component } from \"@torpor/view\";\n\n/**\n * Shows a popover component in code.\n * @param popover The popover component\n * @param anchor The element to use as an anchor for the popover component\n * @param props The properties for the popover component\n * @param target The target element to show the popover in\n * @returns The value selected by the user\n */\nexport default function showPopover(\n\tpopover: Component,\n\tanchor: HTMLElement,\n\tprops?: Record<PropertyKey, any>,\n\ttarget?: Element,\n): void {\n\t// Add the anchor element to the properties\n\tconst allProps = Object.assign({}, props, { anchor });\n\n\t// Create the popover\n\t// TODO: This needs to clean up after itself, like the mount methods do\n\tpopover(target || anchor.parentElement || document.body, null, allProps);\n}\n"],"mappings":";;;;;;;;;;;;;AAWA,SAAwB,YACvB,SACA,QACA,OACA,QACO;CAEP,MAAM,WAAW,OAAO,OAAO,CAAC,GAAG,OAAO,EAAE,OAAO,CAAC;CAIpD,QAAQ,UAAU,OAAO,iBAAiB,SAAS,MAAM,MAAM,QAAQ;AACxE"}

package/dist/Progress/Progress.torp

@@ -0,0 +1,88 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+
+interface ProgressProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The minimum value (default 0) */
+	min?: number;
+	/** The maximum value (default 100) */
+	max?: number;
+	/** The current value; omit it for an indeterminate progress bar */
+	value?: number;
+	/** A human-readable version of the current value, e.g. "3 of 10 files" */
+	valuetext?: string;
+	/** An accessible name for the progress bar */
+	ariaLabel?: string;
+}
+
+/**
+ * A progress bar that shows how far along an operation is, either with a
+ * specific value or as indeterminate when the extent is unknown.
+ *
+ * See [the WAI ARIA guidelines for Progress Bars](https://www.w3.org/WAI/ARIA/apg/patterns/progressbar/).
+ */
+export default function Progress($props: ProgressProps | undefined) {
+	function getMin(): number {
+		return $props?.min ?? 0;
+	}
+	function getMax(): number {
+		return $props?.max ?? 100;
+	}
+	function isIndeterminate(): boolean {
+		return $props?.value == null;
+	}
+
+	// The clamped value that is reported to assistive tech
+	function getValue(): number {
+		return Math.min(getMax(), Math.max(getMin(), $props?.value ?? getMin()));
+	}
+
+	// The percentage of the range that the value represents (0..100)
+	function getPct(): number {
+		const min = getMin();
+		const max = getMax();
+		if (max <= min) return 0;
+		return ((getValue() - min) / (max - min)) * 100;
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-progress", $props?.class]}
+			{$props?.style}
+			role="progressbar"
+			aria-label={$props?.ariaLabel}
+			aria-valuemin={isIndeterminate() ? undefined : getMin()}
+			aria-valuemax={isIndeterminate() ? undefined : getMax()}
+			aria-valuenow={isIndeterminate() ? undefined : getValue()}
+			aria-valuetext={$props?.valuetext}
+			data-state={isIndeterminate() ? "indeterminate" : "determinate"}
+		>
+			<div
+				class="torp-progress-bar"
+				data-state={isIndeterminate() ? "indeterminate" : "determinate"}
+				style={isIndeterminate() ? undefined : `width: ${getPct()}%;`}
+			/>
+		</div>
+	}
+
+	@style {
+		/* Headless: layout only, so the bar fills the track proportionally.
+		   All appearance is up to the consuming theme */
+		.torp-progress {
+			position: relative;
+			overflow: hidden;
+		}
+		.torp-progress-bar {
+			position: absolute;
+			inset: 0 auto 0 0;
+		}
+		.torp-progress-bar[data-state="indeterminate"] {
+			width: 100%;
+		}
+	}
+}

package/dist/Progress/index.d.ts

@@ -0,0 +1,37 @@
+import { type SlotRender } from "@torpor/view";
+
+
+interface ProgressProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The minimum value (default 0) */
+	min?: number;
+	/** The maximum value (default 100) */
+	max?: number;
+	/** The current value; omit it for an indeterminate progress bar */
+	value?: number;
+	/** A human-readable version of the current value, e.g. "3 of 10 files" */
+	valuetext?: string;
+	/** An accessible name for the progress bar */
+	ariaLabel?: string;
+}
+
+/**
+ * A progress bar that shows how far along an operation is, either with a
+ * specific value or as indeterminate when the extent is unknown.
+ *
+ * See [the WAI ARIA guidelines for Progress Bars](https://www.w3.org/WAI/ARIA/apg/patterns/progressbar/).
+ */
+declare function Progress(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: ProgressProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { Progress };

package/dist/Progress/index.js

@@ -0,0 +1,2 @@
+import Progress from "./Progress.torp";
+export { Progress };