@torpor/ui 0.2.0 → 0.3.0

package/src/Modal/ModalContent.torp

@@ -0,0 +1,77 @@
+import { addDocumentEvent, removeDocumentEvent } from "../utils/documentEvents";
+import { ModalContextName, type ModalContext } from "./ModalTypes";
+
+interface ModalContentProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
+/**
+ * The content that is displayed for a Modal when it is open, displayed
+ * alongside an element.
+ */
+export default function ModalContent($props: ModalContentProps | undefined) {
+	let div: HTMLDivElement;
+	let shown = false;
+	let closeOnClick = false;
+
+	// Get stuff out of the ModalContext
+	const context = $context[ModalContextName] as ModalContext;
+	if (!context) {
+		throw new Error("ModalContent must be contained within a Modal");
+	}
+	let $state = context.state;
+
+	$run(() => {
+		if (!$state.visible) {
+			hide();
+		}
+	});
+
+	function show() {
+		shown = true;
+
+		// HACK: Because this Modal 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);
+	}
+
+	function hide() {
+		if (!shown) return;
+
+		removeDocumentEvent("mousedown", handleDocumentMouseDown);
+		removeDocumentEvent("click", handleDocumentClick);
+	}
+
+	function handleDocumentMouseDown() {
+		closeOnClick = true;
+	}
+
+	function handleDocumentClick(e: MouseEvent) {
+		if (
+			closeOnClick &&
+			div &&
+			!div.contains(e.target as HTMLElement)
+		) {
+			e.preventDefault();
+			context.handleClickOutside!(e);
+		}
+	}
+
+	@render {
+		@if ($state.visible) {
+			<div
+				{$props?.id}
+				class={`torp-modal-content ${$props?.class ?? ""}`.trim()}
+				&ref={div}
+				onmount={show}
+			>
+				<slot />
+			</div>
+		}
+	}
+}

package/src/Modal/ModalOverlay.torp

@@ -0,0 +1,38 @@
+import { disableScroll } from "../mount/disableScroll";
+import { ModalContextName, type ModalContext } from "./ModalTypes";
+
+interface ModalOverlayProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
+/**
+ * The background overlay for a modal popup component (e.g. Context, Dialog or Popover).
+ * Adding an overlay automatically sets the component's `modal` value to true.
+ */
+export default function ModalOverlay($props: ModalOverlayProps | undefined) {
+	// Get stuff out of the ModalContext
+	const context = $context[ModalContextName] as ModalContext;
+	if (!context) {
+		throw new Error("ModalOverlay must be contained within a Modal");
+	}
+	let $state = context.state;
+
+	// Any popup with an overlay is modal
+	$state.modal = true;
+
+	@render {
+		@if ($state.visible) {
+			<div
+				{$props?.id}
+				class={`torp-modal-overlay ${$props?.class ?? ""}`.trim()}
+				tabindex="-1"
+				onmount={(el) => disableScroll(el)}
+			>
+				<slot />
+			</div>
+		}
+	}
+}

package/src/Modal/ModalTrigger.torp

@@ -0,0 +1,50 @@
+import { ModalContextName, type ModalContext } from "./ModalTypes";
+import hoverTrigger from "../mount/hoverTrigger";
+
+interface ModalTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether the modal is activated by click/press or by hover **/
+	activation?: "press" | "hover"
+}
+
+/**
+ * The button that causes a Modal to appear or disappear.
+ */
+export default function ModalTrigger($props: ModalTriggerProps | undefined) {
+	let activation = $props?.activation ?? "press";
+
+	// Get stuff out of the ModalContext
+	const context = $context[ModalContextName] as ModalContext;
+	if (!context) {
+		throw new Error("ModalTrigger must be contained within a Modal");
+	}
+	let $state = context.state;
+
+	function handleClick() {
+		if (activation !== "press") return;
+
+		$state.visible = !$state.visible;
+	}
+
+	function handleHover() {
+		if (activation !== "hover") return;
+
+		$state.visible = !$state.visible
+	}
+
+	@render {
+		<button
+			type="button"
+			{$props?.id}
+			class={`torp-modal-trigger ${$props?.class ?? ""}`.trim()}
+			onclick={handleClick}
+			onmount={(el) => hoverTrigger(el, { onHover: handleHover, onExit: handleHover })}
+			&ref={context.anchorElement}
+		>
+			<slot />
+		</button>
+	}
+}

package/src/Modal/ModalTypes.ts

@@ -0,0 +1,22 @@
+export const ModalContextName = "Modal";
+
+/** The shared context for modal components (Contextual, Prompt and Modal) */
+export interface ModalContext {
+	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;
+	state: ModalState;
+	// 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 ModalState {
+	visible: boolean;
+}

package/src/Modal/index.ts

@@ -0,0 +1,10 @@
+import Modal from "./Modal.torp";
+import ModalContent from "./ModalContent.torp";
+import ModalOverlay from "./ModalOverlay.torp";
+import ModalTrigger from "./ModalTrigger.torp";
+import showModal from "./showModal";
+import showPrompt from "./showPrompt";
+
+export { Modal, ModalContent, ModalOverlay, ModalTrigger };
+
+export { showModal, showPrompt };

package/src/Modal/showModal.ts

@@ -0,0 +1,19 @@
+// TODO: Allow passing in a variable -- so that you can show an inline modal
+import type { Component } from "@torpor/view";
+
+/**
+ * Shows a modal component in code.
+ * @param modal The modal component
+ * @param props The properties for the modal component
+ * @param target The target element to show the modal in
+ * @returns The value selected by the user
+ */
+export default function showModal(
+	modal: Component,
+	props?: Record<PropertyKey, any>,
+	target?: Element,
+): void {
+	// Create the modal
+	// TODO: This needs to clean up after itself, like the mount methods do
+	modal(target || document.body, null, props);
+}

package/src/Modal/showPrompt.ts

@@ -0,0 +1,23 @@
+import type { Component } from "@torpor/view";
+
+/**
+ * Shows a modal component in code, and asynchronously returns the value selected by the user.
+ * @param modal The modal component
+ * @param props The properties for the modal component
+ * @param target The target element to show the modal in
+ * @returns The value selected by the user
+ */
+export default function showPrompt(
+	modal: Component,
+	props?: Record<PropertyKey, any>,
+	target?: Element,
+): Promise<any> {
+	return new Promise((resolve) => {
+		// Add the promise as the callback
+		const allProps = Object.assign({}, props, { callback: resolve });
+
+		// Create the modal
+		// TODO: This needs to clean up after itself, like the use methods do
+		modal(target || document.body, null, allProps);
+	});
+}

package/src/NavMenu/NavMenu.torp

@@ -6,6 +6,17 @@ import {
 	type NavMenuPopoutContext
 } from "./NavMenuTypes";
 
+interface NavMenuProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** An ARIA label for describing the menu to screen readers  */
+	ariaLabel?: string | undefined,
+	/** The orientation of the menu, which affects keyboard navigation */
+	orientation?: "horizontal" | "vertical",
+}
+
 /**
  * A list of links for navigating a website.
  *
@@ -21,12 +32,9 @@ import {
  *	 ...
  * </NavMenu>
  * ```
- *
- * @prop {string | undefined} ariaLabel -- An ARIA label for describing the menu to screen readers 
- * @prop {"horizontal" | "vertical"} orientation -- The orientation of the menu, which affects keyboard navigation
  */
-export default function NavMenu($props: any) {
-	$props.orientation ||= "horizontal";
+export default function NavMenu($props: NavMenuProps | undefined) {
+	let orientation = $props?.orientation ?? "horizontal";
 
 	// A collection containing the state and some functions for each item
 	let itemStates: ItemState[] = [];
@@ -51,7 +59,7 @@ export default function NavMenu($props: any) {
 	$context[NavMenuContextName] = context;
 
 	// If the NavMenu is not in a popout, focus its first item. Otherwise the popout will call focusFirstElement, below
-	function handleFocus(e: FocusEvent & { currentTarget: EventTarget & HTMLElement }) {
+	function handleFocus() {
 		if (!popoutContext && itemStates.length) {
 			itemStates[0].setFocused();
 		}
@@ -164,12 +172,12 @@ export default function NavMenu($props: any) {
 
 	@render {
 		<nav
-			{$props.id}
-			class={`torp-nav-menu ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-nav-menu ${$props?.class ?? ""}`.trim()}
 			tabindex="0"
 			role="menubar"
-			aria-label={$props.ariaLabel}
-			aria-orientation={$props.orientation}
+			aria-label={$props?.ariaLabel}
+			aria-orientation={orientation}
 			onfocus={handleFocus}
 		>
 			<slot />

package/src/NavMenu/NavMenuButton.torp

@@ -1,14 +1,19 @@
 import { NavMenuContextName, type NavMenuContext } from "./NavMenuTypes";
 
+interface NavMenuButtonProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether this button is disabled  */
+	disabled?: boolean,
+}
+
 /**
  * A button that is placed in a NavMenu to carry out a non-navigation action such as logging out.
  *
- * @prop {boolean} disabled -- Whether this button is disabled 
  */
-export default function NavMenuButton($props: any) {
-	/** Set when the item is disabled */
-	let dataDisabled = $props.disabled || undefined;
-
+export default function NavMenuButton($props: NavMenuButtonProps | undefined) {
 	let button: HTMLButtonElement;
 
 	// Get stuff out of the NavMenuContext
@@ -27,13 +32,13 @@ export default function NavMenuButton($props: any) {
 
 	@render {
 		<button
-			{$props.id}
-			class={`torp-nav-menu-button ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-nav-menu-button ${$props?.class ?? ""}`.trim()}
 			type="button"
-			{$props.disabled}
+			{$props?.disabled}
 			role="menuitem"
-			aria-disabled={$props.disabled ? "true" : undefined}
-			data-disabled={dataDisabled}
+			aria-disabled={$props?.disabled ? "true" : undefined}
+			data-disabled={$props?.disabled ? "true" : undefined}
 			onkeydown
 			onkeydown={handleItemKey}
 			onclick

package/src/NavMenu/NavMenuElement.torp

@@ -1,15 +1,21 @@
 import { NavMenuContextName, type NavMenuContext } from "./NavMenuTypes";
 
+interface NavMenuElementProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether this button is disabled  */
+	disabled?: boolean,
+	/** An element that can be focused via keyboard navigation */
+	element?: HTMLElement,
+}
+
 /**
  * An element of any type that can be placed in a NavMenu.
  *
- * @prop {boolean} disabled -- Whether this button is disabled 
- * @prop {HTMLElement} element -- An element that can be focused via keyboard navigation
  */
-export default function NavMenuElement($props: any) {
-	/** Set when the item is disabled */
-	let dataDisabled = $props.disabled || undefined;
-
+export default function NavMenuElement($props: NavMenuElementProps | undefined) {
 	// Get stuff out of the NavMenuContext
 	const menuContext = $context[NavMenuContextName] as NavMenuContext;
 	if (!menuContext) {
@@ -21,17 +27,19 @@ export default function NavMenuElement($props: any) {
 	const { index } = registerItem(setFocused);
 
 	function setFocused() {
-		element.focus();
+		if ($props?.element) {
+			$props.element.focus();
+		}
 	}
 
 	@render {
 		<div
-			{$props.id}
-			class={`torp-nav-menu-div ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-nav-menu-div ${$props?.class ?? ""}`.trim()}
 			type="div"
 			role="menuitem"
-			aria-disabled={$props.disabled ? "true" : undefined}
-			data-disabled={dataDisabled}
+			aria-disabled={$props?.disabled ? "true" : undefined}
+			data-disabled={$props?.disabled ? "true" : undefined}
 			onkeydown
 			onkeydown={handleItemKey}
 			onclick

package/src/NavMenu/NavMenuGroup.torp

@@ -1,11 +1,18 @@
 import { NavMenuGroupContextName, type NavMenuGroupContext } from "./NavMenuTypes";
 
+interface NavMenuGroupProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** An ARIA label for describing the group to screen readers  */
+	ariaLabel?: string,
+}
+
 /**
  * A container for a logical group of navigation menu items.
- *
- * @prop {string | undefined} ariaLabel -- An ARIA label for describing the group to screen readers 
  */
-export default function NavMenuGroup($props: any) {
+export default function NavMenuGroup($props: NavMenuGroupProps | undefined) {
 	let $state = $watch({
 		headerId: ""
 	});
@@ -18,10 +25,10 @@ export default function NavMenuGroup($props: any) {
 
 	@render {
 		<div
-			{$props.id}
-			class={`torp-nav-menu-group ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-nav-menu-group ${$props?.class ?? ""}`.trim()}
 			role="group"
-			aria-label={$props.ariaLabel}
+			aria-label={$props?.ariaLabel}
 			aria-labelledby={$state.headerId}
 		>
 			<slot />

package/src/NavMenu/NavMenuGroupHeader.torp

@@ -1,13 +1,20 @@
 import getId from "../utils/getId";
 import { NavMenuGroupContextName, type NavMenuGroupContext } from "./NavMenuTypes";
 
+interface NavMenuGroupHeaderProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** The type of HTML header to use */
+	as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6",
+}
+
 /**
  * The header for a NavMenuGroup.
- *
- * @prop {"h1" | "h2" | "h3" | "h4" | "h5" | "h6"} as -- The type of HTML header to use
  */
-export default function NavMenuGroupHeader($props: any) {
-	$props.id ??= getId();
+export default function NavMenuGroupHeader($props: NavMenuGroupHeaderProps | undefined) {
+	let defaultId = getId();
 
 	const context = $context[NavMenuGroupContextName] as NavMenuGroupContext;
 	if (!context) {
@@ -16,13 +23,13 @@ export default function NavMenuGroupHeader($props: any) {
 	let $state = context.state;
 
 	// Set the header ID now that we know what it is
-	$state.headerId = $props.id;
+	$state.headerId = $props?.id ?? defaultId;
 
 	@render {
+		@// TODO: self={$props.as}
 		<h4
-			@// TODO: self={$props.as}
-			{$props.id}
-			class={`torp-nav-menu-group-header ${$props.class ?? ""}`.trim()}
+			id={$props?.id ?? defaultId}
+			class={`torp-nav-menu-group-header ${$props?.class ?? ""}`.trim()}
 		>
 			<slot />
 		</h4>

package/src/NavMenu/NavMenuLink.torp

@@ -1,19 +1,24 @@
 
 import { NavMenuContextName, type NavMenuContext } from "./NavMenuTypes";
 
+interface NavMenuLinkProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** The URL for the menu link */
+	href: string,
+	/** Whether the menu link should open in a new tab/window */
+	newWindow?: boolean,
+	/** Whether this link is disabled */
+	disabled?: boolean,
+}
+
 /**
  * A link that is placed in a NavMenu and signals a response by a user.
  *
- * @prop {string} href -- The URL for the menu link
- * @prop {newWindow} boolean -- Whether the menu link should open in a new tab/window
- * @prop {boolean} disabled -- Whether this link is disabled
  */
-export default function NavMenuLink($props: any) {
-	$props.newWindow ??= false;
-
-	/** Set when the item is disabled */
-	let dataDisabled = $props.disabled || undefined;
-
+export default function NavMenuLink($props: NavMenuLinkProps | undefined) {
 	let link: HTMLAnchorElement;
 
 	// Get stuff out of the NavMenuContext
@@ -32,14 +37,14 @@ export default function NavMenuLink($props: any) {
 
 	@render {
 		<a
-			{$props.id}
-			class={`torp-nav-menu-link ${$props.class ?? ""}`.trim()}
-			href={$props.href}
-			{$props.disabled}
-			target={$props.newWindow ? "_blank" : undefined}
+			{$props?.id}
+			class={`torp-nav-menu-link ${$props?.class ?? ""}`.trim()}
+			{$props?.href}
+			{$props?.disabled}
+			target={$props?.newWindow ? "_blank" : undefined}
 			role="menuitem"
-			aria-disabled={$props.disabled ? "true" : undefined}
-			data-disabled={dataDisabled}
+			aria-disabled={$props?.disabled ? "true" : undefined}
+			data-disabled={$props?.disabled ? "true" : undefined}
 			onkeydown
 			onkeydown={handleItemKey}
 			onclick

package/src/NavMenu/NavMenuPopout.torp

@@ -1,5 +1,20 @@
 import { NavMenuPopoutContextName, type NavMenuPopoutContext } from "./NavMenuTypes";
 
+interface NavMenuPopoutProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether the popout is visible */
+	visible?: boolean,
+	/** Raised when the popout is opened or closed */
+	ontoggle?: (open: boolean) => void,
+	/** Raised when the popout has opened */
+	onopen?: () => void,
+	/** Raised when the popout has closed */
+	onclose?: (result: any) => void,
+}
+
 /**
  * A popout that is attached to a menu button and can be used to show a submenu.
  *
@@ -7,18 +22,24 @@ import { NavMenuPopoutContextName, type NavMenuPopoutContext } from "./NavMenuTy
  *
  * ```
  * <NavMenuPopout>
- *     <NavMenuPopoutButton />
+ * 	<NavMenuPopoutButton />
  * 	<NavMenuPopoutContent />
  * </NavMenuPopout>
  * ```
- *
- * @prop {boolean} visible -- Whether the popout is visible
  */
-export default function NavMenuPopout($props: any) {
-	$props.visible ??= false;
-
+export default function NavMenuPopout($props: NavMenuPopoutProps | undefined) {
 	let $state = $watch({
-		visible: $props.visible
+		visible: false
+	});
+
+	// Sync props and state
+	$run(() => {
+		$state.visible = $props?.visible ?? false;
+	});
+	$run(() => {
+		if ($props !== undefined) {
+			$props.visible = $state.visible;
+		}
 	});
 
 	let result: any;
@@ -29,18 +50,13 @@ export default function NavMenuPopout($props: any) {
 	};
 	$context[NavMenuPopoutContextName] = context;
 
-	// Copy props into state whenever they change
-	$run(() => {
-		$state.visible = $props.visible ?? false;
-	});
-
 	// Dispatch the toggle event when the popout is opened or closed
 	let firstToggle = true;
 	$run(() => {
-		const ontoggle = $props.ontoggle;
-		const onopen = $props.onopen;
-		const onclose = $props.onclose;
-		const visible = $props.visible;
+		const ontoggle = $props?.ontoggle;
+		const onopen = $props?.onopen;
+		const onclose = $props?.onclose;
+		const visible = $state.visible;
 		if (firstToggle) {
 			firstToggle = false;
 		} else {
@@ -59,8 +75,8 @@ export default function NavMenuPopout($props: any) {
 
 	@render {
 		<div
-			{$props.id}
-			class={`torp-nav-menu-popout ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-nav-menu-popout ${$props?.class ?? ""}`.trim()}
 			onmouseleave={handleMouseLeave}
 		>
 			<slot />