@torpor/ui 0.2.0 → 0.2.1

package/dist/NavMenu/index.d.ts

@@ -1,180 +1,257 @@
 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,
 	$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,
 	$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,
 	$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,
 	$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,
 	$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,
 	$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,
+}
+
 /**
- * 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,
 	$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,
 	$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,
 	$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,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;

package/dist/Notification/Notification.torp

@@ -1,16 +1,26 @@
 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) {
+export default function Notification($props: NotificationProps) {
+	$props ??= $watch({});
 	$props.visible ??= true;
 	$props.duration ??= 5000;
 

package/dist/Notification/NotificationClose.torp

@@ -1,9 +1,18 @@
 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) {
+	$props ??= $watch({});
+
 	// Get stuff out of the NotificationContext
 	const context = $context[NotificationContextName] as NotificationContext;
 	if (!context) {

package/dist/Notification/NotificationContainer.torp

@@ -1,8 +1,18 @@
+
+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) {
+	$props ??= $watch({});
+
 	@render {
 		<div
 			{$props.id}

package/dist/Notification/NotificationContent.torp

@@ -1,7 +1,17 @@
+
+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) {
+	$props ??= $watch({});
+
 	@render {
 		<div 
 			{$props.id}

package/dist/Notification/index.d.ts

@@ -1,72 +1,90 @@
 import { type SlotRender } from "@torpor/view";
 
 
+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,
+}
+
 /**
- * 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 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/).
  */
 declare function Notification(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props,
+	$props: NotificationProps,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface NotificationCloseProps {
+	/** 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.
+ * The button that a user can press to close this Notification.
  */
 declare function NotificationClose(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props?: Record<PropertyKey, any>,
+	$props: NotificationCloseProps,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface NotificationContainerProps {
+	/** 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.
+ * The container for one or more Notifications, which can be used to position
+ * the notifications inside the viewport.
  */
 declare function NotificationContainer(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props?: Record<PropertyKey, any>,
+	$props: NotificationContainerProps,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface NotificationContentProps {
+	/** 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.
+ * The content to display within a Notification.
  */
 declare function NotificationContent(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props?: Record<PropertyKey, any>,
+	$props: NotificationContentProps,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;

package/dist/Popover/Popover.torp

@@ -1,5 +1,22 @@
 import { PopoverContextName, type Point, type PopoverContext, type PopoverState } from "./PopoverTypes";
 
+interface PopoverProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether the popover is modal. If true, an overlay should be supplied to obscure outside content, and only the popover content will be visible to screen readers  */
+	modal?: boolean,
+	/** Whether the popover is visible  */
+	visible?: boolean,
+	/** The element to anchor this popover to, as an alternative to supplying a PopoverTrigger  */
+	anchor?: HTMLElement,
+	/** The position to display this popover at if it's contextual, as an alternative to supplying a PopoverTriggerContextual  */
+	position?: Point,
+	/** A function to be called when the user selects a response */
+	callback?: ((value: any) => void),
+}
+
 /**
  * A popover that can be used to show rich content or obtain information from a user.
  *
@@ -14,13 +31,10 @@ import { PopoverContextName, type Point, type PopoverContext, type PopoverState
  * 	<PopoverContent/PopoverContentAnchored/PopoverContentContextual />
  * </Popover>
  * ```
- * @prop {boolean} modal -- Whether the popover is modal. If true, an overlay should be supplied to obscure outside content, and only the popover content will be visible to screen readers 
- * @prop {boolean} visible -- Whether the popover is visible 
- * @prop {HTMLElement | undefined} anchor -- The element to anchor this popover to, as an alternative to supplying a PopoverTrigger 
- * @prop {Point | undefined} position -- The position to display this popover at if it's contextual, as an alternative to supplying a PopoverTriggerContextual 
- * @prop {((value: any) => void) | undefined} [callback] -- A function to be called when the user selects a response
  */
-export default function Popover($props: any) {
+export default function Popover($props: PopoverProps) {
+	$props ??= $watch({});
+
 	let $state: PopoverState = $watch({
 		visible: false,
 		position: { x: 0, y: 0 }

package/dist/Popover/PopoverContent.torp

@@ -1,11 +1,20 @@
 import { addDocumentEvent, removeDocumentEvent } from "../utils/documentEvents";
 import { PopoverContextName, type PopoverContext } from "./PopoverTypes";
 
+interface PopoverContentProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
 /**
  * The content that is displayed for a Popover when it is open, such as a Dialog
  * in the middle of the screen or a div that slides in from the side.
  */
-export default function PopoverContent($props: any) {
+export default function PopoverContent($props: PopoverContentProps) {
+	$props ??= $watch({});
+
 	let div: HTMLDivElement;
 	let shown = false;
 	let closeOnClick = false;

package/dist/Popover/PopoverContentAnchored.torp

@@ -3,16 +3,23 @@ import getScrollParent from "../utils/getScrollParent";
 import setPopoverPosition from "../utils/setPopoverPosition";
 import { PopoverContextName, type PopoverContext } from "./PopoverTypes";
 
+interface PopoverContentAnchoredProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Where the popover will be shown, relative to the popover button */
+	side?: "top" | "right" | "bottom" | "left",
+	/** How the popover will be aligned, relative to the popover button */
+	alignment?: "start" | "center" | "end",
+}
+
 /**
  * The content that is displayed for a Popover when it is open, displayed
  * alongside an element.
- *
- * @prop {"top" | "right" | "bottom" | "left"} site -- Where the popover will be
- * shown, relative to the popover button
- * @prop {"start" | "center" | "end"} alignment -- How the popover will be
- * aligned, relative to the popover button
  */
-export default function PopoverContentAnchored($props: any) {
+export default function PopoverContentAnchored($props: PopoverContentAnchoredProps) {
+	$props ??= $watch({});
 	$props.side ??= "bottom";
 	$props.alignment ??= "center";
 

package/dist/Popover/PopoverContentContextual.torp

@@ -4,11 +4,20 @@ import getScrollParent from "../utils/getScrollParent";
 import setContextPosition from "../utils/setContextPosition";
 import { PopoverContextName, type PopoverContext } from "./PopoverTypes";
 
+interface PopoverContentContextualProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
 /**
  * The content that is displayed for a Popover when it is open, displayed at the
  * position that the user right-clicked.
  */
-export default function PopoverContentContextual($props: any) {	
+export default function PopoverContentContextual($props: PopoverContentContextualProps) {	
+	$props ??= $watch({});
+
 	let div: HTMLDivElement;
 	let shown = false;
 	let closeOnClick = false;