@torpor/ui 0.0.17 → 0.1.0

package/src/Accordion/Accordion.torp

@@ -1,4 +1,4 @@
-import { AccordionContextName, type AccordionContext, type ItemState } from './AccordionTypes';
+import { AccordionContextName, type AccordionContext, type ItemState } from "./AccordionTypes";
 
 /**
  * A vertically stacked set of interactive headings that enable users to reveal
@@ -19,24 +19,16 @@ import { AccordionContextName, type AccordionContext, type ItemState } from './A
  * </Accordion>
  * ```
  *
- * @prop {'single' | 'multiple'} type -- Whether a single AccordionItem or multiple AccordionItems can be expanded at the same time
- * @prop {string | string[]} value -- The value of the expanded AccordionItem, or an array of values if the type is 'multiple'
+ * @prop {"single" | "multiple"} type -- Whether a single AccordionItem or multiple AccordionItems can be expanded at the same time
+ * @prop {string | string[]} value -- The value of the expanded AccordionItem, or an array of values if the type is "multiple"
  * @prop {boolean} disabled -- If set to true, the user cannot interact with any items in the Accordion
  * @prop {(value: string | string[]) => void} [onchange] -- Raised when the expanded item(s) have changed
  */
 export default function Accordion($props: any) {
-	$props.type ||= 'single';
-	$props.value ||= $props.type === 'single' ? '' : [];
+	$props.type ||= "single";
+	$props.value ||= $props.type === "single" ? "" : [];
 
-	interface State {
-		value: string | string[];
-		itemStates: ItemState[];
-	}
-
-	let $state: State = $watch({
-		value: $props.value,
-		itemStates: []
-	})
+	let itemStates: ItemState[] = [];
 
 	// This is used to assign automatic indexes to items where needed
 	let nextIndex = 0;
@@ -52,24 +44,24 @@ export default function Accordion($props: any) {
 
 	$run(() => {
 		// HACK: This should probably be done with setters?
-		let newValue = $state.value;
+		let newValue = $props.value;
 
 		// Get the value
 		switch ($props.type) {
-			case 'single': {
+			case "single": {
 				// 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 $state.itemStates) {
+				for (let item of itemStates) {
 					item.expanded = item.value === newValue;
 				}
 				break;
 			}
-			case 'multiple': {
+			case "multiple": {
 				// Ensure the value passed in is an array
 				if (!Array.isArray(newValue)) {
 					newValue = [newValue];
 				}
-				for (let item of $state.itemStates) {
+				for (let item of itemStates) {
 					item.expanded = newValue.indexOf(item.value) !== -1;
 				}
 				break;
@@ -77,20 +69,24 @@ export default function Accordion($props: any) {
 		}
 
 		// Set the value
-		$state.value = newValue;
+		$props.value = newValue;
 	})
 
 	$run(() => {
-		$state.itemStates.forEach((s) => s.parentDisabled = $props.disabled);
+		itemStates.forEach((s) => s.parentDisabled = $props.disabled);
 	});
 
 	// Dispatch the change event when the value changes
-	// TODO: Should this be a setter instead?
+	let firstChange = true;
 	$run(() => {
-		if ($props.onchange) {
-			$props.onchange($state.value);
+		const ev = $props.onchange;
+		const value = $props.value;
+		if (firstChange) {
+			firstChange = false;
+		} else if (ev) {
+			ev(value);
 		}
-	})
+	});
 
 	function registerItem(itemState: ItemState) {
 		// If an index wasn't set for the item, set it automatically
@@ -104,52 +100,52 @@ export default function Accordion($props: any) {
 		}
 
 		// If we have a value, set whether the item should be expanded
-		if ($state.value) {
+		if ($props.value) {
 			switch ($props.type) {
-				case 'single': {
-					itemState.expanded = $state.value === itemState.value;
+				case "single": {
+					itemState.expanded = $props.value === itemState.value;
 					break;
 				}
-				case 'multiple': {
-					itemState.expanded = $state.value.includes(itemState.value);
+				case "multiple": {
+					itemState.expanded = $props.value.includes(itemState.value);
 					break;
 				}
 			}
 		}
 
 		// Set whether the Accordion itself is disabled
-		$state.parentDisabled = $props.disabled
+		itemState.parentDisabled = $props.disabled
 
 		// Add the item's state to the array
-		$state.itemStates.splice(itemState.index, 0, itemState);
+		itemStates.splice(itemState.index, 0, itemState);
 	}
 
 	// TODO: I think this should be done by value
 	function removeItem(itemIndex: number) {
 		// Remove the item and re-index
-		let index = $state.itemStates.findIndex((item) => item.index === itemIndex);
+		let index = itemStates.findIndex((item) => item.index === itemIndex);
 		if (index !== -1) {
-			$state.itemStates.splice(itemIndex, 1);
+			itemStates.splice(itemIndex, 1);
 		}
-		$state.itemStates.forEach((item, i) => (item.index = i));
+		itemStates.forEach((item, i) => (item.index = i));
 	}
 
 	function toggleItem(toggleValue: string) {
 		switch ($props.type) {
-			case 'single': {
-				for (let item of $state.itemStates) {
+			case "single": {
+				for (let item of itemStates) {
 					// The item is expanded if it has the supplied value (i.e. if it was clicked) and if it
 					// wasn't already expanded (i.e. we collapse it if it was expanded and clicked)
 					if (item.value === toggleValue) {
-						$state.value = item.expanded ? '' : item.value;
+						$props.value = item.expanded ? "" : item.value;
 						break;
 					}
 				}
 				break;
 			}
-			case 'multiple': {
+			case "multiple": {
 				let newValue = [];
-				for (let item of $state.itemStates) {
+				for (let item of itemStates) {
 					// The item is expanded if it has the supplied value (i.e. if it was clicked) or if it
 					// was already expanded
 					if (
@@ -159,7 +155,7 @@ export default function Accordion($props: any) {
 						newValue.push(item.value);
 					}
 				}
-				$state.value = newValue.sort();
+				$props.value = newValue.sort();
 				break;
 			}
 		}
@@ -167,33 +163,33 @@ export default function Accordion($props: any) {
 
 	function handleHeaderKey(headerIndex: number, e: KeyboardEvent) {
 		switch (e.key) {
-			case 'Up':
-			case 'ArrowUp': {
+			case "Up":
+			case "ArrowUp": {
 				if (headerIndex > 0) {
 					e.preventDefault();
-					$state.itemStates[headerIndex - 1].setFocused();
+					itemStates[headerIndex - 1].setFocused();
 				}
 				break;
 			}
-			case 'Down':
-			case 'ArrowDown': {
-				if (headerIndex < $state.itemStates.length - 1) {
+			case "Down":
+			case "ArrowDown": {
+				if (headerIndex < itemStates.length - 1) {
 					e.preventDefault();
-					$state.itemStates[headerIndex + 1].setFocused();
+					itemStates[headerIndex + 1].setFocused();
 				}
 				break;
 			}
-			case 'Home': {
+			case "Home": {
 				if (headerIndex > 0) {
 					e.preventDefault();
-					$state.itemStates[0].setFocused();
+					itemStates[0].setFocused();
 				}
 				break;
 			}
-			case 'End': {
-				if (headerIndex < $state.itemStates.length - 1) {
+			case "End": {
+				if (headerIndex < itemStates.length - 1) {
 					e.preventDefault();
-					$state.itemStates[$state.itemStates.length - 1].setFocused();
+					itemStates[itemStates.length - 1].setFocused();
 				}
 				break;
 			}
@@ -201,7 +197,10 @@ export default function Accordion($props: any) {
 	}
 
 	@render {
-		<div class="torp-accordion">
+		<div
+			id={$props.id}
+			class={`torp-accordion ${$props.class ?? ""}`.trim()}
+		>
 			<:slot />
 		</div>
 	}

package/src/Accordion/AccordionContent.torp

@@ -1,5 +1,5 @@
-import getId from '../utils/getId';
-import { AccordionItemContextName, type AccordionItemContext } from './AccordionTypes';
+import getId from "../utils/getId";
+import { AccordionItemContextName, type AccordionItemContext } from "./AccordionTypes";
 
 /**
  * Content for an AccordionItem, which can be revealed or hidden by an associated AccordionTrigger.
@@ -12,7 +12,7 @@ export default function AccordionContent($props: any) {
 
 	const context = $context[AccordionItemContextName] as AccordionItemContext;
 	if (!context) {
-		throw new Error('AccordionContent must be contained within an AccordionItem');
+		throw new Error("AccordionContent must be contained within an AccordionItem");
 	}
 	let $state = $context[AccordionItemContextName].state
 
@@ -22,8 +22,8 @@ export default function AccordionContent($props: any) {
 	@render {
 		<div
 			id={$props.id}
-			class='torp-accordion-content'
-			role={$props.ariaRegion ? 'region' : undefined}
+			class={`torp-accordion-content ${$props.class ?? ""}`.trim()}
+			role={$props.ariaRegion ? "region" : undefined}
 			aria-labelledby={$state.headerId}
 			data-state={$state.dataState}
 			data-disabled={$state.dataDisabled}

package/src/Accordion/AccordionHeader.torp

@@ -1,4 +1,4 @@
-import { AccordionItemContextName, type AccordionItemContext } from './AccordionTypes';
+import { AccordionItemContextName, type AccordionItemContext } from "./AccordionTypes";
 
 /**
  * The header for an AccordionItem, which contains the AccordionTrigger.
@@ -11,19 +11,20 @@ import { AccordionItemContextName, type AccordionItemContext } from './Accordion
  * </AccordionHeader>
  * ```
  *
- * @prop {'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'} as -- The type of HTML header to use
+ * @prop {"h1" | "h2" | "h3" | "h4" | "h5" | "h6"} as -- The type of HTML header to use
  */
 export default function AccordionHeader($props: any) {
 	const context = $context[AccordionItemContextName] as AccordionItemContext;
 	if (!context) {
-		throw new Error('AccordionHeader must be contained within an AccordionItem');
+		throw new Error("AccordionHeader must be contained within an AccordionItem");
 	}
 	let $state = $context[AccordionItemContextName].state
 
 	@render {
 		@// TODO: $props.as
 		<h4
-			class='torp-accordion-header'
+			id={$props.id}
+			class={`torp-accordion-header ${$props.class ?? ""}`.trim()}
 			data-state={$state.dataState}
 			data-disabled={$state.dataDisabled}
 		>

package/src/Accordion/AccordionItem.torp

@@ -1,4 +1,4 @@
-import { AccordionContextName, AccordionItemContextName, type AccordionContext, type AccordionItemContext } from './AccordionTypes';
+import { AccordionContextName, AccordionItemContextName, type AccordionContext, type AccordionItemContext } from "./AccordionTypes";
 
 /**
  * An item in an Accordion, which must consist of an AccordionTrigger and an AccordionContent.
@@ -27,14 +27,14 @@ export default function AccordionItem($props: any) {
 		disabled: $props.disabled,
 		parentDisabled: false,
 		get dataState() {
-			return this.expanded ? 'open' : 'closed';
+			return this.expanded ? "open" : "closed";
 		},
 	})
 
 	// Get stuff out of the AccordionContext
 	const context = $context[AccordionContextName] as AccordionContext;
 	if (!context) {
-		throw new Error('AccordionItem must be contained within an Accordion');
+		throw new Error("AccordionItem must be contained within an Accordion");
 	}
 
 	// Put stuff into an AccordionItemContext
@@ -56,16 +56,21 @@ export default function AccordionItem($props: any) {
 	});
 
 	// Dispatch the toggle event when the value of expanded changes
-	// TODO: Should this be a setter instead?
+	let firstToggle = true;
 	$run(() => {
-		if ($props.ontoggle) {
-			$props.ontoggle($state.expanded);
+		const ev = $props.ontoggle;
+		const expanded = $state.expanded;
+		if (firstToggle) {
+			firstToggle = false;
+		} else if (ev) {
+			ev(expanded);
 		}
-	})
+	});
 
 	@render {
 		<div
-			class='torp-accordion-item'
+			id={$props.id}
+			class={`torp-accordion-item ${$props.class ?? ""}`.trim()}
 			data-state={$state.dataState}
 			data-disabled={$state.dataDisabled}
 		>

package/src/Accordion/AccordionTrigger.torp

@@ -1,5 +1,5 @@
-import getId from '../utils/getId';
-import { AccordionItemContextName, type AccordionItemContext } from './AccordionTypes';
+import getId from "../utils/getId";
+import { AccordionItemContextName, type AccordionItemContext } from "./AccordionTypes";
 
 /**
  * A header button for an AccordionItem, which can be used to reveal or hide an associated AccordionContent.
@@ -12,7 +12,7 @@ export default function AccordionTrigger() {
 	// Get stuff out of the AccordionItemContext
 	const context = $context[AccordionItemContextName] as AccordionItemContext;
 	if (!context) {
-		throw new Error('AccordionTrigger must be contained within an AccordionItem');
+		throw new Error("AccordionTrigger must be contained within an AccordionItem");
 	}
 	let $state = $context[AccordionItemContextName].state;
 
@@ -42,14 +42,14 @@ export default function AccordionTrigger() {
 		<button
 			type="button"
 			id={$props.id}
-			class='torp-accordion-button'
+			class={`torp-accordion-trigger ${$props.class ?? ""}`.trim()}
 			disabled={$state.disabled || $state.parentDisabled}
 			aria-expanded={$state.expanded.toString()}
 			aria-disabled={$state.disabled}
 			aria-controls={$state.contentId}
 			data-state={$state.dataState}
 			data-disabled={$state.disabled}
-			:self={button}
+			&ref={button}
 			onclick={handleClick}
 			onkeydown={handleKey}
 		>

package/src/Accordion/AccordionTypes.ts

@@ -27,6 +27,7 @@ export interface ItemState {
 	expanded: boolean;
 	disabled: boolean;
 	parentDisabled: boolean;
+	dataState: "open" | "closed";
 	/** Called in the Accordion when a header needs to be focused */
 	setFocused: () => void;
 }

package/src/Dialog/Dialog.torp

@@ -0,0 +1,156 @@
+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";
+
+/**
+ * Content for a window displayed in a Popover.
+ * 
+ * See [the WAI ARIA guidelines for Dialogs](https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal/).
+ * 
+ * The structure of a Dialog is:
+ * 
+ * ```
+ * <Dialog>
+ *     <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;
+
+	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 Contextual, Prompt or Popover");
+	}
+	const { handleButton, modal } = popoverContext;
+	const visible = popoverContext.state.visible;
+
+	popoverContext.handleClickOutside = handleClickOutside;
+	// Set the focusFirstElement method in the PopoverContext so that it can be
+	// called after everything has been shown
+	popoverContext.focusFirstElement = focusFirstElement;
+
+	// Set the IDs for using in the Dialog's ARIA attributes
+	let $state: DialogState = $watch({
+		dialogId: $props.id,
+		headerId: "",
+		bodyId: "",
+		visible
+	})
+
+	// Set the context to pass down to items
+	let context: DialogContext = {
+		handleButton,
+		state: $state,
+		anchorElement: popoverContext.anchorElement
+	};
+	$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;
+		}
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		switch (e.key) {
+			case "Esc":
+			case "Escape": {
+				if (context.cancelButton) {
+					context.cancelButton.click();
+					e.preventDefault();
+				}
+				break;
+			}
+			case "Enter": {
+				if (context.confirmButton) {
+					context.confirmButton.click();
+					e.preventDefault();
+				}
+				break;
+			}
+		}
+	}
+
+	@render {
+		<div
+			id={$props.id}
+			class={`torp-dialog ${$props.class ?? ""}`.trim()}
+			tabindex="0"
+			role={$props.alert ? "alertdialog" : "dialog"}
+			aria-modal={modal}
+			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}
+		>
+			<:slot />
+		</div>
+	}
+}

package/src/Dialog/DialogBody.torp

@@ -0,0 +1,34 @@
+import getId from "../utils/getId";
+import { DialogContextName, type DialogContext } from "./DialogTypes";
+
+/**
+ * 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;
+
+	// Get stuff out of the DialogContext
+	const context = $context[DialogContextName] as DialogContext;
+	if (!context) {
+		throw new Error("DialogBody must be contained within a Dialog");
+	}
+	let $state = context.state;
+
+	// Set the body id for using in the Dialog's ARIA attributes
+	if ($props.ariaAnnounce) {
+		$state.bodyId = $props.id;
+	}
+
+	@render {
+		<div
+			id={$props.id} 
+			class={`torp-dialog-body ${$props.class ?? ""}`.trim()}
+		>
+			<:slot />
+		</div>
+	}
+}

package/src/Dialog/DialogButton.torp

@@ -0,0 +1,48 @@
+import { DialogContextName, type DialogContext } from "./DialogTypes";
+
+/**
+ * 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) {
+	let button: HTMLButtonElement;
+
+	// Get stuff out of the DialogContext
+	const context = $context[DialogContextName] as DialogContext;
+	if (!context) {
+		throw new Error("DialogButton must be contained within a Dialog");
+	}
+	const handleButton = context.handleButton;
+
+	$mount(() => {
+		// Store the confirm or cancel button in the DialogContext
+		if ($props.type === "confirm") {
+			context.confirmButton = button;
+		} else if ($props.type === "cancel") {
+			context.cancelButton = button;
+		}
+	});
+
+	function handleClick(e) {
+		if ($props.onclick) {
+			$props.onclick(e)
+		}
+		handleButton($props.type, $props.value);
+	}
+
+	@render {
+		<button
+			type="button"
+			id={$props.id}
+			class={`torp-dialog-button ${$props.class ?? ""}`.trim()}
+			disabled={$props.disabled}
+			onclick={handleClick}
+			&ref={button}
+		>
+			<:slot />
+		</button>
+	}
+}

package/src/Dialog/DialogFooter.torp

@@ -0,0 +1,13 @@
+/**
+ * The footer for a Dialog, which may contain one or more DialogButtons.
+ */
+export default function DialogFooter($props: any) {
+	@render {
+		<div
+			id={$props.id}
+			class={`torp-dialog-footer ${$props.class ?? ""}`.trim()}
+		>
+			<:slot />
+		</div>
+	}
+}

package/src/Dialog/DialogHeader.torp

@@ -0,0 +1,34 @@
+import getId from "../utils/getId";
+import { DialogContextName, type DialogContext } from "./DialogTypes";
+
+/**
+ * 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;
+
+	// Get stuff out of the DialogContext
+	const context = $context[DialogContextName] as DialogContext;
+	if (!context) {
+		throw new Error("DialogHeader must be contained within a Dialog");
+	}
+	let $state = context.state;
+
+	// Set the header id for using in the Dialog's ARIA attributes
+	if ($props.ariaAnnounce) {
+		$state.headerId = $props.id;
+	}
+
+	@render {
+		<div
+			id={$props.id}
+			class={`torp-dialog-footer ${$props.class ?? ""}`.trim()}
+		>
+			<:slot />
+		</div>
+	}
+}