@torpor/ui 0.2.0 → 0.3.0

package/src/Dialog/Dialog.torp

@@ -1,11 +1,24 @@
 import getId from "../utils/getId";
-import { addDocumentEvent, removeDocumentEvent } from "../utils/documentEvents";
 import { trapFocus, type TrapFocusOptions } from "../mount/trapFocus";
-import { PopoverContextName, type PopoverContext } from "../Popover/PopoverTypes";
-import { DialogContextName, type DialogContext, type DialogState } from "./DialogTypes";
+import { ModalContextName, type ModalContext } from "../Modal/ModalTypes";
+import { PopoverContextName } from "../Popover/PopoverTypes";
+import { DialogContextName, type DialogContext, type DialogState, type HandleButtonPress } from "./DialogTypes";
+
+interface DialogProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** An ARIA label for describing the popover to screen readers  */
+	ariaLabel?: string,
+	/** Whether the dialog should alert the user via the screen reader */
+	alert?: boolean,
+}
 
 /**
- * Content for a window displayed in a Popover.
+ * A dialog that can be used to show a message to the user, or get information from the user.
+ * 
+ * Dialogs are typically shown within a Modal or Popover.
  * 
  * See [the WAI ARIA guidelines for Dialogs](https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal/).
  * 
@@ -13,43 +26,44 @@ import { DialogContextName, type DialogContext, type DialogState } from "./Dialo
  * 
  * ```
  * <Dialog>
- *     <DialogHeader /> (optional)
- *     <DialogBody /> (optional)
- *     <DialogFooter> (optional)
- *         <DialogButton /> (optional)
- *     </DialogFooter>
+ * 	<ModalOverlay /> (optional -- will set `modal` to true)
+ * 	<DialogHeader /> (optional)
+ * 	<DialogBody /> (optional)
+ * 	<DialogFooter> (optional)
+ * 		<DialogButton /> (optional)
+ * 	</DialogFooter>
  * </Dialog>
  * ```
  * 
- * @prop {string | undefined} ariaLabel -- An ARIA label for describing the popover to screen readers 
- * @prop {boolean} alert -- Whether the dialog should alert the user via the screen reader
  */
-export default function Dialog($props: any) {
-	$props.id ??= getId();
-	$props.dialog ??= false;
+export default function Dialog($props: DialogProps | undefined) {
+	let defaultId = getId();
 
-	let div: HTMLDivElement;
+	//let div: HTMLDivElement;
 
 	let trapFocusOptions: TrapFocusOptions = {
 		focusableElements: []
 	};
 
-	// Get stuff out of the PopoverContext
-	const popoverContext = $context[PopoverContextName] as PopoverContext;
-	if (!popoverContext) {
-		throw new Error("Dialog must be contained within a Popover");
-	}
-	const { handleButton, modal } = popoverContext;
-	const visible = popoverContext.state.visible;
+	// Maybe get stuff out of a Modal context
+	let modal = false;
+	let visible = true;
+	let handleButton: HandleButtonPress | undefined = undefined;
+	const modalContext = $context[ModalContextName] ?? $context[PopoverContextName] as ModalContext;
+	if (modalContext) {
+		modal = true;
+		visible = modalContext.state.visible;
+		handleButton = modalContext.handleButton;
 
-	popoverContext.handleClickOutside = handleClickOutside;
-	// Set the focusFirstElement method in the PopoverContext so that it can be
-	// called after everything has been shown
-	popoverContext.focusFirstElement = focusFirstElement;
+		modalContext.handleClickOutside = handleClickOutside;
+		// Set the focusFirstElement method in the ModalContext so that it can be
+		// called after everything has been shown
+		modalContext.focusFirstElement = focusFirstElement;
+	}
 
 	// Set the IDs for using in the Dialog's ARIA attributes
 	let $state: DialogState = $watch({
-		dialogId: $props.id,
+		dialogId: $props?.id ?? defaultId,
 		headerId: "",
 		bodyId: "",
 		visible
@@ -59,60 +73,22 @@ export default function Dialog($props: any) {
 	let context: DialogContext = {
 		handleButton,
 		state: $state,
-		anchorElement: popoverContext.anchorElement
+		anchorElement: modalContext ? modalContext.anchorElement : undefined
 	};
 	$context[DialogContextName] = context;
 
-	let closeOnClick = false;
-
-	$mount(() => {
-		if ($state.visible) {
-			// HACK: Because this Dialog 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. I guess we could
-			// require the user to preventDefault after calling showPrompt etc,
-			// but that seems very error-prone?
-			closeOnClick = false;
-			addDocumentEvent("mousedown", handleDocumentMouseDown);
-			addDocumentEvent("click", handleDocumentClick);
-		} else {
-			removeDocumentEvent("mousedown", handleDocumentMouseDown);
-			removeDocumentEvent("click", handleDocumentClick);
-			// Focus the anchor element per WAI guidelines
-			if (context.anchorElement?.focus) {
-				context.anchorElement.focus();
-			}
-		}
-	});
-
 	function focusFirstElement() {
 		if (trapFocusOptions.focusableElements.length) {
 			trapFocusOptions.focusableElements[0].focus();
 		}
 	}
 
-	function handleDocumentMouseDown() {
-		closeOnClick = true;
-	}
-
-	function handleDocumentClick(e: MouseEvent) {
-		if (
-			closeOnClick &&
-			div &&
-			!div.contains(e.target as HTMLElement) &&
-			(!context.anchorElement || !context.anchorElement.contains(e.target as HTMLElement))
-		) {
-			handleClickOutside(e);
-		}
-	}
-
 	function handleClickOutside(e: MouseEvent) {
 		// Don't allow the user to click outside -- they must press a button or
 		// the Esc key
 		e.preventDefault();
 		if (!modal) {
-			popoverContext.state.visible = false;
-			context.state.visible = false;
+			modalContext.state.visible = false;
 		}
 	}
 
@@ -138,17 +114,17 @@ export default function Dialog($props: any) {
 
 	@render {
 		<div
-			{$props.id}
-			class={`torp-dialog ${$props.class ?? ""}`.trim()}
+			id={$props?.id ?? defaultId}
+			class={`torp-dialog ${$props?.class ?? ""}`.trim()}
 			tabindex="0"
-			role={$props.alert ? "alertdialog" : "dialog"}
+			role={$props?.alert === true ? "alertdialog" : "dialog"}
 			aria-modal={modal}
-			aria-label={$props.ariaLabel}
-			aria-labelledby={!$props.ariaLabel && $state.headerId ? $state.headerId : undefined}
+			aria-label={$props?.ariaLabel}
+			aria-labelledby={!$props?.ariaLabel && $state.headerId ? $state.headerId : undefined}
 			aria-describedby={$state.bodyId ? $state.bodyId : undefined}
 			onkeydown={handleKey}
 			onmount={(el) => trapFocus(el, trapFocusOptions)}
-			&ref={div}
+			@//&ref={div}
 		>
 			<slot />
 		</div>

package/src/Dialog/DialogBody.torp

@@ -1,15 +1,21 @@
 import getId from "../utils/getId";
 import { DialogContextName, type DialogContext } from "./DialogTypes";
 
+interface DialogBodyProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether the body content will be announced by screen readers when the Dialog is opened */
+	ariaAnnounce?: boolean,
+}
+
 /**
  * The body information for a Dialog. Content in the body will be announced by
  * screen readers when the Dialog is opened, unless ariaAnnounce is false.
- * 
- * @prop {boolean} ariaAnnounce -- Whether the body content will be announced by screen readers when the Dialog is opened
  */
-export default function DialogBody($props: any) {
-	$props.id ??= getId();
-	$props.ariaAnnounce ??= true;
+export default function DialogBody($props: DialogBodyProps | undefined) {
+	let defaultId = getId();
 
 	// Get stuff out of the DialogContext
 	const context = $context[DialogContextName] as DialogContext;
@@ -19,14 +25,14 @@ export default function DialogBody($props: any) {
 	let $state = context.state;
 
 	// Set the body id for using in the Dialog's ARIA attributes
-	if ($props.ariaAnnounce) {
-		$state.bodyId = $props.id;
+	if ($props?.ariaAnnounce !== false) {
+		$state.bodyId = $props?.id || defaultId;
 	}
 
 	@render {
 		<div
-			{$props.id} 
-			class={`torp-dialog-body ${$props.class ?? ""}`.trim()}
+			id={$props?.id ?? defaultId} 
+			class={`torp-dialog-body ${$props?.class ?? ""}`.trim()}
 		>
 			<slot />
 		</div>

package/src/Dialog/DialogButton.torp

@@ -1,13 +1,25 @@
 import { DialogContextName, type DialogContext } from "./DialogTypes";
 
+interface DialogButtonProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** The value that should be returned when this button is pressed and the Dialog was invoked by calling showContextual, showPrompt or showPopover */
+	value?: any,
+	/** "confirm" if the button should respond to the Enter key or "cancel" if the button should respond to the Escape key */
+	type?: "confirm" | "cancel",
+	/** Whether this button is disabled */
+	disabled?: boolean,
+	/** Raised when the button is clicked */
+	onclick?: (e: MouseEvent) => void,
+}
+
 /**
  * A button that is placed in a DialogFooter and signals a response by a user.
  * 
- * @prop {any | undefined} value -- The value that should be returned when this button is pressed and the Dialog was invoked by calling showContextual, showPrompt or showPopover
- * @prop {"confirm" | "cancel" | undefined} type -- "confirm" if the button should respond to the Enter key or "cancel" if the button should respond to the Escape key
- * @prop {boolean} disabled -- Whether this button is disabled
  */
-export default function DialogButton($props: any) {
+export default function DialogButton($props: DialogButtonProps | undefined) {
 	let button: HTMLButtonElement;
 
 	// Get stuff out of the DialogContext
@@ -19,26 +31,28 @@ export default function DialogButton($props: any) {
 
 	$mount(() => {
 		// Store the confirm or cancel button in the DialogContext
-		if ($props.type === "confirm") {
+		if ($props?.type === "confirm") {
 			context.confirmButton = button;
-		} else if ($props.type === "cancel") {
+		} else if ($props?.type === "cancel") {
 			context.cancelButton = button;
 		}
 	});
 
-	function handleClick(e) {
-		if ($props.onclick) {
-			$props.onclick(e)
+	function handleClick(e: MouseEvent) {
+		if ($props?.onclick) {
+			$props?.onclick(e)
+		}
+		if (handleButton) {
+			handleButton($props?.type, $props?.value);
 		}
-		handleButton($props.type, $props.value);
 	}
 
 	@render {
 		<button
 			type="button"
-			{$props.id}
-			class={`torp-dialog-button ${$props.class ?? ""}`.trim()}
-			disabled={$props.disabled}
+			{$props?.id}
+			class={`torp-dialog-button ${$props?.class ?? ""}`.trim()}
+			disabled={$props?.disabled}
 			onclick={handleClick}
 			&ref={button}
 		>

package/src/Dialog/DialogFooter.torp

@@ -1,11 +1,19 @@
+
+interface DialogFooterProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
 /**
  * The footer for a Dialog, which may contain one or more DialogButtons.
  */
-export default function DialogFooter($props: any) {
+export default function DialogFooter($props: DialogFooterProps | undefined) {
 	@render {
 		<div
-			{$props.id}
-			class={`torp-dialog-footer ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-dialog-footer ${$props?.class ?? ""}`.trim()}
 		>
 			<slot />
 		</div>

package/src/Dialog/DialogHeader.torp

@@ -1,15 +1,22 @@
 import getId from "../utils/getId";
 import { DialogContextName, type DialogContext } from "./DialogTypes";
 
+interface DialogHeaderProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether the header will be announced by screen readers when the Dialog is opened */
+	ariaAnnounce?: boolean,
+}
+
 /**
  * The header for a Dialog. Content in the header will be announced by screen
  * readers when the Dialog is opened, unless ariaAnnounce is false.
  * 
- * @prop {boolean} ariaAnnounce -- Whether the header will be announced by screen readers when the Dialog is opened
  */
-export default function DialogHeader($props: any) {
-	$props.id ??= getId();
-	$props.ariaAnnounce ??= true;
+export default function DialogHeader($props: DialogHeaderProps | undefined) {
+	let defaultId = getId();
 
 	// Get stuff out of the DialogContext
 	const context = $context[DialogContextName] as DialogContext;
@@ -19,14 +26,14 @@ export default function DialogHeader($props: any) {
 	let $state = context.state;
 
 	// Set the header id for using in the Dialog's ARIA attributes
-	if ($props.ariaAnnounce) {
-		$state.headerId = $props.id;
+	if ($props?.ariaAnnounce !== false) {
+		$state.headerId = $props?.id ?? defaultId;
 	}
 
 	@render {
 		<div
-			{$props.id}
-			class={`torp-dialog-footer ${$props.class ?? ""}`.trim()}
+			id={$props?.id ?? defaultId}
+			class={`torp-dialog-footer ${$props?.class ?? ""}`.trim()}
 		>
 			<slot />
 		</div>

package/src/Dialog/DialogTypes.ts

@@ -1,7 +1,9 @@
 export const DialogContextName = "Dialog";
 
+export type HandleButtonPress = (type: "confirm" | "cancel" | undefined, value?: any) => void;
+
 export interface DialogContext {
-	handleButton: (type: "confirm" | "cancel" | undefined, value?: any) => void;
+	handleButton?: HandleButtonPress;
 	state: DialogState;
 	anchorElement?: HTMLElement;
 	confirmButton?: HTMLButtonElement;
@@ -12,5 +14,4 @@ export interface DialogState {
 	dialogId: string;
 	headerId: string;
 	bodyId: string;
-	visible: boolean;
 }

package/src/Disclosure/Disclosure.torp

@@ -1,4 +1,17 @@
-import { DisclosureContextName, type DisclosureContext } from "./DisclosureTypes";
+import { DisclosureContextName, type DisclosureContext, type DisclosureState } from "./DisclosureTypes";
+
+interface DisclosureProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether the disclosure is expanded and its content visible */
+	expanded?: boolean,
+	/** If set to true, the user cannot interact with this disclosure */
+	disabled?: boolean,
+	/** Raised when the disclosure is opened or closed */
+	ontoggle?: (open: boolean) => void,
+}
 
 /**
  * An interactive header that enables users to reveal or hide an associated section of content.
@@ -9,33 +22,29 @@ import { DisclosureContextName, type DisclosureContext } from "./DisclosureTypes
  *
  * ```
  * <Disclosure>
- *     <DisclosureHeader>
- *         <DisclosureTrigger />
- *     </DisclosureHeader>
- *     <DisclosureContent />
+ * 	<DisclosureHeader>
+ * 		<DisclosureTrigger />
+ * 	</DisclosureHeader>
+ * 	<DisclosureContent />
  * </Disclosure>
  * ```
- *
- * @prop {boolean} [expanded] -- Whether the Disclosure is expanded and its content visible
- * @prop {boolean} [disabled] -- If set to true, the user cannot interact with this Disclosure
- * @prop {(boolean) => void} [ontoggle] -- Raised when this item is opened or closed
  */
-export default function Disclosure($props: any) {
-	$props.expanded ??= false;
-	$props.disabled ??= false;
-
+export default function Disclosure($props: DisclosureProps | undefined) {
 	let $state: DisclosureState = $watch({
-		expanded: $props.expanded && $props.expanded !== "false",
-		disabled: $props.disabled,
-		get dataState() {
-			return this.expanded ? "open" : "closed";
-		},
+		expanded: false,
+		disabled: false,
+		headerId: "",
+		contentId: "",
 	});
 
 	// Update $state with $props
 	$run(() => {
-		$state.expanded = $props.expanded && $props.expanded !== "false";
-		$state.disabled = $props.disabled;
+		$state.expanded = $props?.expanded === true ||
+			// @ts-ignore
+			$props?.expanded === "true";
+		$state.disabled = $props?.disabled === true ||
+			// @ts-ignore
+			$props?.disabled === "true";
 	});
 
 	// Put stuff into a DisclosureContext
@@ -47,7 +56,7 @@ export default function Disclosure($props: any) {
 	// Dispatch the toggle event when the value of expanded changes
 	let firstToggle = true;
 	$run(() => {
-		const ev = $props.ontoggle;
+		const ev = $props?.ontoggle;
 		const expanded = $state.expanded;
 		if (firstToggle) {
 			firstToggle = false;
@@ -58,10 +67,10 @@ export default function Disclosure($props: any) {
 
 	@render {
 		<div
-			{$props.id}
-			class={`torp-disclosure-item ${$props.class ?? ""}`.trim()}
-			data-state={$state.dataState}
-			data-disabled={$state.dataDisabled}
+			{$props?.id}
+			class={`torp-disclosure-item ${$props?.class ?? ""}`.trim()}
+			data-state={$state.expanded ? "open" : "closed"}
+			data-disabled={$state.disabled ? "true" : undefined}
 		>
 			<slot />
 		</div>

package/src/Disclosure/DisclosureContent.torp

@@ -1,32 +1,38 @@
 import getId from "../utils/getId";
 import { DisclosureContextName, type DisclosureContext } from "./DisclosureTypes";
 
+interface DisclosureContentProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether this content should act as a region. Set this when the content contains heading elements or a nested Disclosure */
+	ariaRegion?: boolean,
+}
+
 /**
  * Content for a Disclosure, which can be revealed or hidden by an associated DisclosureTrigger.
- *
- * @prop {string} [id] -- An ID for the DisclosureContent's div container
- * @prop {boolean} [ariaRegion] -- Whether this content should act as a region. Set this when the content contains heading elements or a nested Disclosure
  */
-export default function DisclosureContent($props: any) {
-	$props.id ||= getId();
+export default function DisclosureContent($props: DisclosureContentProps | undefined) {
+	let defaultId = getId();
 
 	const context = $context[DisclosureContextName] as DisclosureContext;
 	if (!context) {
 		throw new Error("DisclosureContent must be contained within a Disclosure");
 	}
-	let $state = $context[DisclosureContextName].state
+	let $state = context.state
 
 	// Set the content ID so that it can be used with aria-controls in DisclosureTrigger
-	$state.contentId = $props.id;
+	$state.contentId = $props?.id ?? defaultId;
 
 	@render {
 		<div
-			{$props.id}
-			class={`torp-disclosure-content ${$props.class ?? ""}`.trim()}
-			role={$props.ariaRegion ? "region" : undefined}
+			id={$props?.id ?? defaultId}
+			class={`torp-disclosure-content ${$props?.class ?? ""}`.trim()}
+			role={$props?.ariaRegion ? "region" : undefined}
 			aria-labelledby={$state.headerId}
-			data-state={$state.dataState}
-			data-disabled={$state.dataDisabled}
+			data-state={$state.expanded ? "open" : "closed"}
+			data-disabled={$state.disabled ? "true" : undefined}
 		>
 			@if ($state.expanded) {
 				<slot />

package/src/Disclosure/DisclosureHeader.torp

@@ -1,5 +1,14 @@
 import { DisclosureContextName, type DisclosureContext } from "./DisclosureTypes";
 
+interface DisclosureHeaderProps {
+	/** 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 Disclosure, which contains the DisclosureTrigger.
  *
@@ -7,26 +16,24 @@ import { DisclosureContextName, type DisclosureContext } from "./DisclosureTypes
  * 
  * ```
  * <DisclosureHeader>
- *    <DisclosureTrigger />
+ * 	<DisclosureTrigger />
  * </DisclosureHeader>
  * ```
- *
- * @prop {"h1" | "h2" | "h3" | "h4" | "h5" | "h6"} as -- The type of HTML header to use
  */
-export default function DisclosureHeader($props: any) {
+export default function DisclosureHeader($props: DisclosureHeaderProps | undefined) {
 	const context = $context[DisclosureContextName] as DisclosureContext;
 	if (!context) {
 		throw new Error("DisclosureHeader must be contained within a Disclosure");
 	}
-	let $state = $context[DisclosureContextName].state
+	let $state = context.state
 
 	@render {
 		@// TODO: $props.as
 		<h4
-			{$props.id}
-			class={`torp-disclosure-header ${$props.class ?? ""}`.trim()}
-			data-state={$state.dataState}
-			data-disabled={$state.dataDisabled}
+			{$props?.id}
+			class={`torp-disclosure-header ${$props?.class ?? ""}`.trim()}
+			data-state={$state.expanded ? "open" : "closed"}
+			data-disabled={$state.disabled ? "true" : undefined}
 		>
 			<slot />
 		</h4>

package/src/Disclosure/DisclosureTrigger.torp

@@ -1,32 +1,39 @@
 import getId from "../utils/getId";
 import { DisclosureContextName, type DisclosureContext } from "./DisclosureTypes";
 
+interface DisclosureTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
 /**
  * A header button for a Disclosure, which can be used to reveal or hide an associated DisclosureContent.
  */
-export default function DisclosureTrigger() {
-	$props.id ||= getId();
+export default function DisclosureTrigger($props: DisclosureTriggerProps | undefined) {
+	let defaultId = getId();
 
 	// Get stuff out of the DisclosureContext
 	const context = $context[DisclosureContextName] as DisclosureContext;
 	if (!context) {
 		throw new Error("DisclosureTrigger must be contained within a Disclosure");
 	}
-	let $state = $context[DisclosureContextName].state;
+	let $state = context.state;
 
 	// Set the header ID so that it can be used with aria-labelledby in DisclosureContent
-	$state.headerId = $props.id;
+	$state.headerId = $props?.id ?? defaultId;
 
 	@render {
 		<button
 			type="button"
-			{$props.id}
-			class={`torp-disclosure-trigger ${$props.class ?? ""}`.trim()}
-			disabled={$state.disabled || $state.parentDisabled}
+			id={$props?.id ?? defaultId}
+			class={`torp-disclosure-trigger ${$props?.class ?? ""}`.trim()}
+			disabled={$state.disabled}
 			aria-expanded={$state.expanded.toString()}
 			aria-disabled={$state.disabled}
 			aria-controls={$state.contentId}
-			data-state={$state.dataState}
+			data-state={$state.expanded ? "open" : "closed"}
 			data-disabled={$state.disabled}
 			onclick={() => $state.expanded = !$state.expanded}
 		>

package/src/Disclosure/DisclosureTypes.ts

@@ -10,5 +10,4 @@ export interface DisclosureState {
 	contentId: string;
 	expanded: boolean;
 	disabled: boolean;
-	dataState: "open" | "closed";
 }