@torpor/ui 0.2.0 → 0.3.0

package/dist/Menu/MenuPopoutTrigger.torp

@@ -5,15 +5,22 @@ import {
 	type MenuPopoutContext
 } from "./MenuTypes";
 
+interface MenuPopoutTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** The delay before showing the popout, in milliseconds */
+	hoverDelay?: number,
+	/** Whether this button is disabled */
+	disabled?: boolean,
+}
+
 /**
  * A button that is placed in a Menu or MenuGroup and signals a response by a user.
- *
- * @prop {number} hoverDelay -- The delay before showing the popout, in milliseconds
- * @prop {boolean} disabled -- Whether this button is disabled
  */
-export default function MenuPopoutTrigger() {
-	$props.hoverDelay ??= 500;
-	$props.disabled ??= false;
+export default function MenuPopoutTrigger($props: MenuPopoutTriggerProps | undefined) {
+	let defaultHoverDelay = 500;
 
 	let button: HTMLButtonElement;
 	let interval: NodeJS.Timeout | undefined;
@@ -63,16 +70,16 @@ export default function MenuPopoutTrigger() {
 	}
 
 	function handleMouseEnter() {
-		if ($props.disabled) return;
+		if ($props?.disabled) return;
 
 		// Handle the hover after a delay
 		if (!interval) {
-			interval = setTimeout(() => setVisible(true), $props.hoverDelay);
+			interval = setTimeout(() => setVisible(true), $props?.hoverDelay ?? defaultHoverDelay);
 		}
 	}
 
 	function handleMouseLeave() {
-		if ($props.disabled) return;
+		if ($props?.disabled) return;
 
 		// Prevent short hovers or touches from firing the event
 		if (interval) {
@@ -82,26 +89,26 @@ export default function MenuPopoutTrigger() {
 	}
 
 	function handleMouseMove() {
-		if ($props.disabled) return;
+		if ($props?.disabled) return;
 
 		// Reset the interval on mouse move
 		if (interval) {
 			clearTimeout(interval);
-			interval = setTimeout(() => setVisible(true), $props.hoverDelay);
+			interval = setTimeout(() => setVisible(true), $props?.hoverDelay ?? defaultHoverDelay);
 		}
 	}
 
 	@render {
 		<button
-			{$props.id}
-			class={`torp-menu-popout-trigger ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-menu-popout-trigger ${$props?.class ?? ""}`.trim()}
 			type="button"
-			{$props.disabled}
+			{$props?.disabled}
 			role="menuitem"
 			aria-haspopup="true"
 			aria-expanded={($state.visible ?? false).toString()}
-			aria-disabled={$props.disabled ? "true" : undefined}
-			data-disabled={$props.disabled ? "true" : undefined}
+			aria-disabled={$props?.disabled ? "true" : undefined}
+			data-disabled={$props?.disabled ? "true" : undefined}
 			onkeydown={handlePopoutKey}
 			onclick={handleClick}
 			onfocus={() => handleItemFocus(index)}

package/dist/Menu/MenuRadio.torp

@@ -7,21 +7,32 @@ import {
 	type MenuRadioGroupContext
 } from "./MenuTypes";
 
+interface MenuRadioProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** The value of the item */
+	value?: string,
+	/** Whether this item is checked */
+	checked?: boolean,
+	/** Whether this item is disabled */
+	disabled?: boolean,
+}
+
 /**
  * A button that is placed in a Menu or MenuGroup to allow the user to select
  * from a number of options.
- *
- * @prop {string} value -- The value of the item
- * @prop {boolean} checked -- Whether this item is checked
- * @prop {boolean} disabled -- Whether this item is disabled
  */
-export default function MenuRadio() {
+export default function MenuRadio($props: MenuRadioProps | undefined) {
 	let $state = $watch({
-		checked: $props.checked,
+		checked: $props?.checked ?? false,
 	});
 
 	$run(() => {
-		$props.checked = $state.checked;
+		if ($props !== undefined) {
+			$props.checked = $state.checked;
+		}
 	});
 
 	let button: HTMLButtonElement;
@@ -44,7 +55,7 @@ export default function MenuRadio() {
 	const { index } = registerItem(setFocused);
 
 	// Register this item with the parent MenuRadioGroup
-	registerItemInGroup($props.value, setChecked);
+	registerItemInGroup($props?.value ?? "", setChecked);
 
 	// Set the context to pass down to items
 	let context: MenuButtonContext = {
@@ -62,21 +73,21 @@ export default function MenuRadio() {
 
 	function handleClick() {
 		if (!$state.checked) {
-			toggleItem($props.value);
+			toggleItem($props?.value ?? "");
 		}
 	}
 
 	@render {
 		<button
-			{$props.id}
-			class={`torp-menu-radio ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-menu-radio ${$props?.class ?? ""}`.trim()}
 			type="button"
-			{$props.disabled}
+			{$props?.disabled}
 			role="menuitemradio"
-			aria-checked={$props.checked}
-			aria-disabled={$props.disabled ? "true" : undefined}
-			data-state={$props.checked ? "checked" : "unchecked"}
-			data-disabled={$props.disabled ? "true" : undefined}
+			aria-checked={$props?.checked}
+			aria-disabled={$props?.disabled ? "true" : undefined}
+			data-state={$props?.checked ? "checked" : "unchecked"}
+			data-disabled={$props?.disabled ? "true" : undefined}
 			onkeydown={handleItemKey}
 			onclick={handleClick}
 			onfocus={() => handleItemFocus(index)}

package/dist/Menu/MenuRadioGroup.torp

@@ -4,17 +4,36 @@ import {
 	type RadioGroupItemState
 } from "./MenuTypes";
 
+interface MenuRadioGroupProps {
+	/** 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,
+	/** The value of the checked MenuRadio */
+	value?: string | undefined,
+	/** Raised when the checked item has changed */
+	onchange?: (value: any) => void,
+}
+
 /**
  * A container for a logical group of menu RadioGroup items.
- *
- * @prop {string} ariaLabel -- An ARIA label for describing the menu to screen readers
- * @prop {string | undefined} value -- The value of the checked MenuRadio
- * @prop {(any) => void} onchange - Called when the checked item has changed
  */
-export default function MenuRadioGroup() {
+export default function MenuRadioGroup($props: MenuRadioGroupProps | undefined) {
 	// A collection containing the state and some functions for each item
 	let itemStates: RadioGroupItemState[] = [];
 
+	let $state = $watch({
+		value: $props?.value
+	});
+
+	$run(() => {
+		if ($props !== undefined) {
+			$props.value = $state.value;
+		}
+	});
+
 	// Set the context to pass down to items
 	let context: MenuRadioGroupContext = {
 		registerItemInGroup,
@@ -24,11 +43,11 @@ export default function MenuRadioGroup() {
 
 	$mount(() => {
 		// Set the initial checked item
-		setValue($props.value);
+		setValue($props?.value);
 	});
 
 	function registerItemInGroup(itemValue: string, setChecked: (value: boolean) => void) {
-		// Add the item"s state to the array
+		// Add the item's state to the array
 		const newItemState: RadioGroupItemState = {
 			value: itemValue,
 			checked: false,
@@ -52,11 +71,11 @@ export default function MenuRadioGroup() {
 		}
 
 		// Set the value
-		if ($props.value !== newValue) {
-			$props.value = newValue;
+		if ($state.value !== newValue) {
+			$state.value = newValue;
 
-			if ($props.onchange) {
-				$props.onchange($props.value);
+			if ($props?.onchange) {
+				$props?.onchange($props?.value);
 			}
 		}
 	}
@@ -70,15 +89,15 @@ export default function MenuRadioGroup() {
 				newValue = item.value;
 			}
 		}
-		$props.value = newValue;
+		$state.value = newValue;
 	}
 
 	@render {
 		<div
-			{$props.id}
-			class={`torp-menu-radio-group ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-menu-radio-group ${$props?.class ?? ""}`.trim()}
 			role="group"
-			aria-label={$props.ariaLabel}
+			aria-label={$props?.ariaLabel}
 		>
 			<slot />
 		</div>

package/dist/Menu/MenuSeparator.torp

@@ -1,11 +1,19 @@
+
+interface MenuSeparatorProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
 /**
  * An element in a menu that separates logical sets of menu items.
  */
-export default function MenuSeparator() {
+export default function MenuSeparator($props: MenuSeparatorProps | undefined) {
 	@render {
 		<div
-			{$props.id}
-			class={`torp-menu-separator ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-menu-separator ${$props?.class ?? ""}`.trim()}
 			role="separator"
 		>
 			<slot />

package/dist/Menu/MenuTypes.ts

@@ -7,7 +7,7 @@ export interface MenuContext {
 	setVisible: (value: boolean, result?: any) => void;
 
 	/** Called from a MenuButton to close the Menu and return a result */
-	handleTrigger: (type: "confirm" | "cancel" | undefined, value?: any) => void;
+	handleButton: (type: "confirm" | "cancel" | undefined, value?: any) => void;
 
 	/** Called from a MenuButton when its button is focused */
 	handleItemFocus: (index: number) => void;
@@ -15,10 +15,7 @@ export interface MenuContext {
 	/** Called from a MenuButton when a key is pressed */
 	handleItemKey: (e: KeyboardEvent) => void;
 
-	state: {
-		/** Whether the Menu is visible. Writable so that it can be subscribed to by children */
-		visible: boolean;
-	};
+	state: MenuState;
 
 	/** The element that caused this Menu to be shown */
 	anchorElement?: HTMLElement;
@@ -27,6 +24,11 @@ export interface MenuContext {
 	registerItem: (setFocused: () => void) => { index: number };
 }
 
+export interface MenuState {
+	/** Whether the Menu is visible */
+	visible: boolean;
+}
+
 export interface MenuButtonContext {
 	state: {
 		checked: boolean;

package/dist/Menu/index.d.ts

@@ -1,198 +1,297 @@
 import { type SlotRender } from "@torpor/view";
 
 
+interface MenuProps {
+	/** 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,
+}
+
 /**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
+ * A list of choices for the user, such as a set of actions or functions. A
+ * menu is usually hidden until made visible by the user.
+ *
+ * See [the WAI ARIA guidelines for Menus](https://www.w3.org/WAI/ARIA/apg/patterns/menu/).
+ *
+ * The structure of a Menu is:
+ *
+ * ```
+ * <Menu>
+ * 	<MenuButton />
+ * 	<MenuSeparator /> (optional)
+ * 	<MenuGroup> (optional)
+ * 		<MenuButton />
+ * 	</MenuGroup>
+ * </Menu>
+ * ```
  */
 declare function Menu(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props?: Record<PropertyKey, any>,
+	$props: MenuProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface MenuButtonProps {
+	/** 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,
+	/** Whether this button is disabled */
+	disabled?: boolean,
+	/** Raised when the button is clicked */
+	onclick?: (e: MouseEvent) => void,
+	/** Raised when a key is pressed down */
+	onkeydown?: (e: KeyboardEvent) => void,
+}
+
 /**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
+ * A button that is placed in a Menu or MenuGroup and signals a response by a user.
+ *
  */
 declare function MenuButton(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props?: Record<PropertyKey, any>,
+	$props: MenuButtonProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface MenuCheckProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether this item is checked */
+	checked?: boolean,
+	/** Whether this item is disabled */
+	disabled?: boolean,
+	/** Raised when the checkbox is clicked */
+	onclick?: (e: MouseEvent) => void,
+}
+
 /**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
+ * A button that is placed in a Menu or MenuGroup to allow the user to turn an
+ * option on or off.
+ *
  */
 declare function MenuCheck(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props?: Record<PropertyKey, any>,
+	$props: MenuCheckProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface MenuGroupProps {
+	/** 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,
+}
+
 /**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
+ * A container for a logical group of menu items.
  */
 declare function MenuGroup(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props?: Record<PropertyKey, any>,
+	$props: MenuGroupProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface MenuIndicatorProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether this item is disabled */
+	disabled?: boolean,
+}
+
 /**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
+ * An indicator for a MenuCheck or MenuRadio component, which is displayed
+ * when the value of checked is true.
  */
 declare function MenuIndicator(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props?: Record<PropertyKey, any>,
+	$props: MenuIndicatorProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface MenuPopoutProps {
+	/** 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,
+}
+
 /**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
+ * A popout that is attached to a menu button and can be used to show a submenu.
+ *
+ * The structure of a MenuPopout is:
+ *
+ * ```
+ * <MenuPopout>
+ * 	<MenuPopoutTrigger /> (optional)
+ * 	<MenuPopoutContent />
+ * </MenuPopout>
+ * ```
  */
 declare function MenuPopout(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props,
+	$props: MenuPopoutProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface MenuPopoutContentProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Where the popout will be shown, relative to the popout button */
+	side?: "top" | "right" | "bottom" | "left",
+	/** How the popout will be aligned, relative to the popout button */
+	alignment?: "start" | "center" | "end",
+}
+
 /**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
+ * The content that is displayed for a MenuPopout when it is open.
  */
 declare function MenuPopoutContent(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props?: Record<PropertyKey, any>,
+	$props: MenuPopoutContentProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface MenuPopoutTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** The delay before showing the popout, in milliseconds */
+	hoverDelay?: number,
+	/** Whether this button is disabled */
+	disabled?: boolean,
+}
+
 /**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
+ * A button that is placed in a Menu or MenuGroup and signals a response by a user.
  */
 declare function MenuPopoutTrigger(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props?: Record<PropertyKey, any>,
+	$props: MenuPopoutTriggerProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface MenuRadioProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** The value of the item */
+	value?: string,
+	/** Whether this item is checked */
+	checked?: boolean,
+	/** Whether this item is disabled */
+	disabled?: boolean,
+}
+
 /**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
+ * A button that is placed in a Menu or MenuGroup to allow the user to select
+ * from a number of options.
  */
 declare function MenuRadio(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props?: Record<PropertyKey, any>,
+	$props: MenuRadioProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface MenuRadioGroupProps {
+	/** 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,
+	/** The value of the checked MenuRadio */
+	value?: string | undefined,
+	/** Raised when the checked item has changed */
+	onchange?: (value: any) => void,
+}
+
 /**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
+ * A container for a logical group of menu RadioGroup items.
  */
 declare function MenuRadioGroup(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props?: Record<PropertyKey, any>,
+	$props: MenuRadioGroupProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface MenuSeparatorProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
 /**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
+ * An element in a menu that separates logical sets of menu items.
  */
 declare function MenuSeparator(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props?: Record<PropertyKey, any>,
+	$props: MenuSeparatorProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;