@torpor/ui 0.2.0 → 0.2.1

package/dist/Menu/Menu.torp

@@ -7,6 +7,15 @@ import {
 	type MenuPopoutContext
 } from "./MenuTypes";
 
+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,
+}
+
 /**
  * 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.
@@ -24,10 +33,10 @@ import {
  *     </MenuGroup>
  * </Menu>
  * ```
- *
- * @prop {string} ariaLabel -- An ARIA label for describing the menu to screen readers
  */
-export default function Menu() {
+export default function Menu($props: MenuProps) {
+	$props ??= $watch({});
+
 	// A collection containing the state and some functions for each item
 	let itemStates: ItemState[] = [];
 	let focusIndex = -1;

package/dist/Menu/MenuButton.torp

@@ -1,12 +1,23 @@
 import { MenuContextName, type MenuContext } from "./MenuTypes";
 
+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,
+}
+
 /**
  * A button that is placed in a Menu or MenuGroup and signals a response by a user.
  *
- * @prop {any} value -- The value that should be returned when this button is pressed and the Dialog was invoked by calling showContextual, showPrompt or showPopover
- * @prop {boolean} disabled -- Whether this button is disabled
  */
-export default function MenuButton() {
+export default function MenuButton($props: MenuButtonProps) {
+	$props ??= $watch({});
+
 	let button: HTMLButtonElement;
 
 	// Get stuff out of the MenuContext

package/dist/Menu/MenuCheck.torp

@@ -5,14 +5,25 @@ import {
 	type MenuContext
 } from "./MenuTypes";
 
+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,
+}
+
 /**
  * A button that is placed in a Menu or MenuGroup to allow the user to turn an
  * option on or off.
  *
- * @prop {boolean} checked -- Whether this item is checked
- * @prop {boolean} disabled -- Whether this item is disabled
  */
-export default function MenuCheck() {
+export default function MenuCheck($props: MenuCheckProps) {
+	$props ??= $watch({});
+
 	let $state = $watch({
 		checked: $props.checked
 	});

package/dist/Menu/MenuGroup.torp

@@ -1,9 +1,19 @@
+
+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,
+}
+
 /**
  * A container for a logical group of menu items.
- *
- * @prop {string} ariaLabel -- An ARIA label for describing the group to screen readers
  */
-export default function MenuGroup() {
+export default function MenuGroup($props: MenuGroupProps) {
+	$props ??= $watch({});
+
 	// TODO: Intercept the context to steal toggleItem??
 
 	@render {

package/dist/Menu/MenuIndicator.torp

@@ -1,12 +1,21 @@
 import { MenuButtonContextName, type MenuButtonContext } from "./MenuTypes";
 
+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,
+}
+
 /**
  * An indicator for a MenuCheck or MenuRadio component, which is displayed
  * when the value of checked is true.
- *
- * @prop {boolean} disabled -- Whether this item is disabled
  */ 
-export default function MenuIndicator() {
+export default function MenuIndicator($props: MenuIndicatorProps) {
+	$props ??= $watch({});
+
 	// Get stuff out of the MenuButtonContext
 	const context = $context[MenuButtonContextName] as MenuButtonContext;
 	if (!context) {

package/dist/Menu/MenuPopout.torp

@@ -1,5 +1,20 @@
 import { MenuPopoutContextName, type MenuPopoutContext } from "./MenuTypes";
 
+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,
+	/** Called when the popout is opened or closed */
+	ontoggle?: (open: boolean) => void,
+	/** Called when the popout has opened */
+	onopen?: () => void,
+	/** Called when the popout has closed */
+	onclose?: () => void,
+}
+
 /**
  * A popout that is attached to a menu button and can be used to show a submenu.
  *
@@ -11,13 +26,9 @@ import { MenuPopoutContextName, type MenuPopoutContext } from "./MenuTypes";
  * 	<MenuPopoutContent />
  * </MenuPopout>
  * ```
- *
- * @prop {boolean} visible -- Whether the popout is visible
- * @prop {(boolean) => void} ontoggle -- Called when the popout is opened or closed
- * @prop {() => void} onopen -- Called when the popout has opened
- * @prop {() => void} onclose -- Called when the popout has closed
  */
-export default function MenuPopout($props) {
+export default function MenuPopout($props: MenuPopoutProps) {
+	$props ??= $watch({});
 	$props.visible ??= false;
 
 	let $state = $watch({

package/dist/Menu/MenuPopoutContent.torp

@@ -2,13 +2,22 @@
 import setPopoverPosition from "../utils/setPopoverPosition";
 import { MenuPopoutContextName, type MenuPopoutContext } from "./MenuTypes";
 
+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",
+}
+
 /**
  * The content that is displayed for a MenuPopout 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 MenuPopoutContent() {
+export default function MenuPopoutContent($props: MenuPopoutContentProps) {
+	$props ??= $watch({});
 	$props.side ??= "right";
 	$props.alignment ??= "start";
 

package/dist/Menu/MenuPopoutTrigger.torp

@@ -5,13 +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() {
+export default function MenuPopoutTrigger($props: MenuPopoutTriggerProps) {
+	$props ??= $watch({});
 	$props.hoverDelay ??= 500;
 	$props.disabled ??= false;
 

package/dist/Menu/MenuRadio.torp

@@ -7,15 +7,26 @@ 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) {
+	$props ??= $watch({});
+
 	let $state = $watch({
 		checked: $props.checked,
 	});

package/dist/Menu/MenuRadioGroup.torp

@@ -4,14 +4,25 @@ 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,
+	/** Called 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) {
+	$props ??= $watch({});
+
 	// A collection containing the state and some functions for each item
 	let itemStates: RadioGroupItemState[] = [];
 

package/dist/Menu/MenuSeparator.torp

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

package/dist/Menu/index.d.ts

@@ -1,198 +1,291 @@
 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,
 	$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,
+}
+
 /**
- * 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,
 	$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,
+}
+
 /**
- * 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,
 	$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,
 	$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,
 	$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,
+	/** Called when the popout is opened or closed */
+	ontoggle?: (open: boolean) => void,
+	/** Called when the popout has opened */
+	onopen?: () => void,
+	/** Called when the popout has closed */
+	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.
+ * 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,
 	$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,
 	$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,
 	$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,
 	$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,
+	/** Called 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,
 	$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,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;