@torpor/ui 0.2.0 → 0.3.0

package/dist/NavMenu/NavMenuPopoutContent.torp

@@ -3,16 +3,22 @@ import getScrollParent from "../utils/getScrollParent";
 import setPopoverPosition from "../utils/setPopoverPosition";
 import { NavMenuPopoutContextName, type NavMenuPopoutContext } from "./NavMenuTypes";
 
+interface NavMenuPopoutContentProps {
+	/** 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",
+}
+
 /**
  * The content that is displayed for a NavMenuPopout when it is open.
  *
- * @prop {"top" | "right" | "bottom" | "left"} side -- Where the popout will be shown, relative to the popout button
- * @prop {"start" | "center" | "end"} alignment -- How the popout will be aligned, relative to the popout button
  */
-export default function NavMenuPopoutContent($props: any) {
-	$props.side ??= "bottom";
-	$props.alignment ??= "start";
-
+export default function NavMenuPopoutContent($props: NavMenuPopoutContentProps | undefined) {
 	let div: HTMLDivElement;
 	let shown = false;
 
@@ -34,7 +40,8 @@ export default function NavMenuPopoutContent($props: any) {
 
 		// Set the position and listen for window resize and scroll to reset the position
 		setPosition();
-		const scrollParent = getScrollParent(context.anchorElement)
+		const anchorElement = context.anchorElement!
+		const scrollParent = getScrollParent(anchorElement)
 		scrollParent.addEventListener("resize", setPosition);
 		scrollParent.addEventListener("scroll", setPosition);
 		if (context.focusFirstElement) {
@@ -46,11 +53,12 @@ export default function NavMenuPopoutContent($props: any) {
 		if (!shown) return;
 
 		// Stop listening for window resize and focus the anchor element per WAI guidelines
-		const scrollParent = getScrollParent(context.anchorElement)
+		const anchorElement = context.anchorElement!
+		const scrollParent = getScrollParent(anchorElement)
 		scrollParent.removeEventListener("resize", setPosition);
 		scrollParent.removeEventListener("scroll", setPosition);
-		if (context.anchorElement?.focus) {
-			context.anchorElement.focus();
+		if (anchorElement.focus) {
+			anchorElement.focus();
 		}
 	}
 
@@ -60,15 +68,17 @@ export default function NavMenuPopoutContent($props: any) {
 		}
 
 		if (div) {
-			setPopoverPosition(context.anchorElement, div, $props.side, $props.alignment);
+			let side = $props?.side ?? "bottom";
+			let alignment = $props?.alignment ?? "start";
+			setPopoverPosition(context.anchorElement, div, side, alignment);
 		}
 	}
 
 	@render {
 		@if ($state.visible) {
 			<div
-				{$props.id}
-				class={`torp-nav-menu-popout-content ${$props.class ?? ""}`.trim()}
+				{$props?.id}
+				class={`torp-nav-menu-popout-content ${$props?.class ?? ""}`.trim()}
 				&ref={div}
 				onmount={show}
 			>

package/dist/NavMenu/NavMenuSeparator.torp

@@ -1,12 +1,19 @@
 
+interface NavMenuSeparatorProps {
+	/** 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 NavMenuSeparator($props: any) {
+export default function NavMenuSeparator($props: NavMenuSeparatorProps | undefined) {
 	@render {
 		<div
-			{$props.id}
-			class={`torp-nav-menu-separator ${$props.class ?? ""}`.trim()} role="separator"
+			{$props?.id}
+			class={`torp-nav-menu-separator ${$props?.class ?? ""}`.trim()} role="separator"
 		>
 			<slot />
 		</div>

package/dist/NavMenu/index.d.ts

@@ -1,180 +1,263 @@
 import { type SlotRender } from "@torpor/view";
 
 
+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",
+}
+
 /**
- * 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 links for navigating a website.
+ *
+ * See [the WAI ARIA guidelines for Menus](https://www.w3.org/WAI/ARIA/apg/patterns/menu/).
+ *
+ * The structure of a NavMenu is:
+ *
+ * ```
+ * <NavMenu>
+ *	 <NavMenuLink />
+ *	 <NavMenuSeparator /> (optional)
+ *	 <NavMenuPopout /> (optional)
+ *	 ...
+ * </NavMenu>
+ * ```
  */
 declare function NavMenu(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props: any,
+	$props: NavMenuProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+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,
+}
+
 /**
- * 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 NavMenu to carry out a non-navigation action such as logging out.
+ *
  */
 declare function NavMenuButton(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props: any,
+	$props: NavMenuButtonProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+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,
+}
+
 /**
- * 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 of any type that can be placed in a NavMenu.
+ *
  */
 declare function NavMenuElement(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props: any,
+	$props: NavMenuElementProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+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,
+}
+
 /**
- * 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 navigation menu items.
  */
 declare function NavMenuGroup(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props: any,
+	$props: NavMenuGroupProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+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",
+}
+
 /**
- * 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 header for a NavMenuGroup.
  */
 declare function NavMenuGroupHeader(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props: any,
+	$props: NavMenuGroupHeaderProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+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,
+}
+
 /**
- * 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 link that is placed in a NavMenu and signals a response by a user.
+ *
  */
 declare function NavMenuLink(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props: any,
+	$props: NavMenuLinkProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+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,
+}
+
 /**
- * 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 NavMenuPopout is:
+ *
+ * ```
+ * <NavMenuPopout>
+ * 	<NavMenuPopoutButton />
+ * 	<NavMenuPopoutContent />
+ * </NavMenuPopout>
+ * ```
  */
 declare function NavMenuPopout(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props: any,
+	$props: NavMenuPopoutProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface NavMenuPopoutButtonProps {
+	/** 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 NavMenu and signals a response by a user.
+ *
  */
 declare function NavMenuPopoutButton(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props: any,
+	$props: NavMenuPopoutButtonProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface NavMenuPopoutContentProps {
+	/** 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 NavMenuPopout when it is open.
+ *
  */
 declare function NavMenuPopoutContent(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props: any,
+	$props: NavMenuPopoutContentProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface NavMenuSeparatorProps {
+	/** 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 NavMenuSeparator(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props: any,
+	$props: NavMenuSeparatorProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;

package/dist/Notification/Notification.torp

@@ -1,18 +1,39 @@
 import { NotificationContextName, type NotificationContext } from "./NotificationTypes";
 
+interface NotificationProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether the notification is visible */
+	visible?: boolean,
+	/** The duration, in milliseconds, to keep the notification visible */
+	duration?: number,
+	/** Raised when the notification has closed, either after the duration has elapsed, or when the user has pressed the close button */
+	onclose?: () => void,
+}
+
 /**
  * An element that displays a brief, important message in a way that attracts
  * the user's attention without interrupting the user's task.
  *
  * See [the WAI ARIA guidelines for Alerts](https://www.w3.org/WAI/ARIA/apg/patterns/alert/).
- *
- * @prop {boolean} visible -- Whether the notification is visible
- * @prop {number | undefined} duration -- The duration, in milliseconds, to keep the notification visible
- * @prop {() => void} onclose -- Raised when the notification has closed, either after the duration has elapsed, or when the user has pressed the close button
  */
-export default function Notification($props) {
-	$props.visible ??= true;
-	$props.duration ??= 5000;
+export default function Notification($props: NotificationProps | undefined) {
+	let defaultDuration = 5000;
+
+	let $state = $watch({
+		visible: false
+	});
+
+	$run(() => {
+		$state.visible = $props?.visible ?? true;
+	});
+	$run(() => {
+		if ($props !== undefined) {
+			$props.visible = $state.visible;
+		}
+	});
 
 	// Set the context to pass down to items
 	let context: NotificationContext = {
@@ -21,24 +42,22 @@ export default function Notification($props) {
 	$context[NotificationContextName] = context;
 
 	$mount(() => {
-		if ($props.duration) {
-			setTimeout(closeNotification, $props.duration);
-		}
+		setTimeout(closeNotification, $props?.duration ?? defaultDuration);
 	});
 
 	function closeNotification() {
-		$props.visible = false;
+		$state.visible = false;
 
-		if ($props.onclose) {
-			$props.onclose();
+		if ($props?.onclose) {
+			$props?.onclose();
 		}
 	}
 
 	@render {
-		@if ($props.visible) {
+		@if ($state.visible) {
 			<div 
-				{$props.id}
-				class={`torp-notification ${$props.class ?? ""}`.trim()}
+				{$props?.id}
+				class={`torp-notification ${$props?.class ?? ""}`.trim()}
 				role="alert"
 			>
 				<slot />

package/dist/Notification/NotificationClose.torp

@@ -1,9 +1,16 @@
 import { NotificationContextName, type NotificationContext } from "./NotificationTypes";
 
+interface NotificationCloseProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
 /**
  * The button that a user can press to close this Notification.
  */
-export default function NotificationClose() {
+export default function NotificationClose($props: NotificationCloseProps | undefined) {
 	// Get stuff out of the NotificationContext
 	const context = $context[NotificationContextName] as NotificationContext;
 	if (!context) {
@@ -17,8 +24,8 @@ export default function NotificationClose() {
 
 	@render {
 		<button
-			{$props.id}
-			class={`torp-notification-close ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-notification-close ${$props?.class ?? ""}`.trim()}
 			type="button"
 			onclick={handleClick}
 		>

package/dist/Notification/NotificationContainer.torp

@@ -1,12 +1,20 @@
+
+interface NotificationContainerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
 /**
  * The container for one or more Notifications, which can be used to position
  * the notifications inside the viewport.
  */
-export default function NotificationContainer() {
+export default function NotificationContainer($props: NotificationContainerProps | undefined) {
 	@render {
 		<div
-			{$props.id}
-			class={`torp-notification-container ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-notification-container ${$props?.class ?? ""}`.trim()}
 		>
 			<slot />
 		</div>

package/dist/Notification/NotificationContent.torp

@@ -1,11 +1,19 @@
+
+interface NotificationContentProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
 /**
  * The content to display within a Notification.
  */
-export default function NotificationContent() {
+export default function NotificationContent($props: NotificationContentProps | undefined) {
 	@render {
 		<div 
-			{$props.id}
-			class={`torp-notification-content ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-notification-content ${$props?.class ?? ""}`.trim()}
 		>
 			<slot />
 		</div>