@torpor/ui 0.2.0 → 0.3.0

package/dist/Form/StandardSchemaV1.ts

@@ -0,0 +1,70 @@
+// From https://github.com/standard-schema/standard-schema
+
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+	/** The Standard Schema properties. */
+	readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+
+export declare namespace StandardSchemaV1 {
+	/** The Standard Schema properties interface. */
+	export interface Props<Input = unknown, Output = Input> {
+		/** The version number of the standard. */
+		readonly version: 1;
+		/** The vendor name of the schema library. */
+		readonly vendor: string;
+		/** Validates unknown input values. */
+		readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+		/** Inferred types associated with the schema. */
+		readonly types?: Types<Input, Output> | undefined;
+	}
+
+	/** The result interface of the validate function. */
+	export type Result<Output> = SuccessResult<Output> | FailureResult;
+
+	/** The result interface if validation succeeds. */
+	export interface SuccessResult<Output> {
+		/** The typed output value. */
+		readonly value: Output;
+		/** The non-existent issues. */
+		readonly issues?: undefined;
+	}
+
+	/** The result interface if validation fails. */
+	export interface FailureResult {
+		/** The issues of failed validation. */
+		readonly issues: ReadonlyArray<Issue>;
+	}
+
+	/** The issue interface of the failure output. */
+	export interface Issue {
+		/** The error message of the issue. */
+		readonly message: string;
+		/** The path of the issue, if any. */
+		readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+	}
+
+	/** The path segment interface of the issue. */
+	export interface PathSegment {
+		/** The key representing a path segment. */
+		readonly key: PropertyKey;
+	}
+
+	/** The Standard Schema types interface. */
+	export interface Types<Input = unknown, Output = Input> {
+		/** The input type of the schema. */
+		readonly input: Input;
+		/** The output type of the schema. */
+		readonly output: Output;
+	}
+
+	/** Infers the input type of a Standard Schema. */
+	export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+		Schema["~standard"]["types"]
+	>["input"];
+
+	/** Infers the output type of a Standard Schema. */
+	export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+		Schema["~standard"]["types"]
+	>["output"];
+}

package/dist/Form/index.d.ts

@@ -0,0 +1,131 @@
+import { type SlotRender } from "@torpor/view";
+
+
+interface FieldProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** The name of the data that this field contains */
+	name: string,
+	/** The data value that this field is bound to */
+	value?: any,
+	/** The schema validator to use for this form */
+	schema?: StandardSchemaV1,
+}
+
+/**
+ * A field in a form which automatically links up a Label and/or an input
+ * component and/or a Message.
+ */
+declare function Field(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: FieldProps,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface FormProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** The data to display in the form */
+	data?: any,
+	/** Where to post the form's data **/
+	action?: string,
+	/** The schema validator to use for this form */
+	schema?: StandardSchemaV1,
+	onsubmit?: (e: SubmitEvent) => boolean | void | Promise<boolean | void>,
+}
+
+/**
+ * A form for submitting values.
+ */
+declare function Form(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: FormProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface InputProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** The input type */
+	type?: "text" | "number" | "password" | "email" | "url" | "tel",
+	/** The name of the input's form data field */
+	name?: string,
+	/** The data value that this field is bound to */
+	value?: any,
+	/** Text to display when the input value is empty */
+	placeholder?: string,
+	/** Whether the input should be readonly */
+	readonly?: boolean,
+	/** The maximum number of characters allowed for the input value */
+	maxlength?: number,
+	/** An ARIA label for describing the input to screen readers when there is no associated label element */
+	ariaLabel?: string,
+}
+
+/**
+ * A standard input in a form.
+ */
+declare function Input(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: InputProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface LabelProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
+/**
+ * A label to describe the contents of an input in a form.
+ */
+declare function Label(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: LabelProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface MessageProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
+/**
+ * A validation message to show when the contents of an input component have
+ * problems that need to be fixed.
+ */
+declare function Message(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: MessageProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { Field, Form, Input, Label, Message };

package/dist/Form/index.js

@@ -0,0 +1,22 @@
+// src/Form/Field.torp
+import Field_default from "./Field.torp";
+
+// src/Form/Form.torp
+import Form_default from "./Form.torp";
+
+// src/Form/Input.torp
+import Input_default from "./Input.torp";
+
+// src/Form/Label.torp
+import Label_default from "./Label.torp";
+
+// src/Form/Message.torp
+import Message_default from "./Message.torp";
+export {
+  Field_default as Field,
+  Form_default as Form,
+  Input_default as Input,
+  Label_default as Label,
+  Message_default as Message
+};
+//# sourceMappingURL=index.js.map

package/dist/Form/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/Menu/Menu.torp

@@ -1,3 +1,5 @@
+import { ContextualContextName } from "../Contextual/ContextualTypes";
+import { ModalContextName } from "../Modal/ModalTypes";
 import { PopoverContextName, type PopoverContext } from "../Popover/PopoverTypes";
 import {
 	MenuContextName,
@@ -7,6 +9,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.
@@ -17,27 +28,26 @@ import {
  *
  * ```
  * <Menu>
- *     <MenuButton />
- *     <MenuSeparator /> (optional)
- *     <MenuGroup> (optional)
- *         <MenuButton />
- *     </MenuGroup>
+ * 	<MenuButton />
+ * 	<MenuSeparator /> (optional)
+ * 	<MenuGroup> (optional)
+ * 		<MenuButton />
+ * 	</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 | undefined) {
 	// A collection containing the state and some functions for each item
 	let itemStates: ItemState[] = [];
 	let focusIndex = -1;
 
 	// Get stuff out of the PopoverContext
-	const popoverContext = $context[PopoverContextName] as PopoverContext;
+	// HACK: share state in PopupState and extend in context/modal/popover
+	const popoverContext = $context[ContextualContextName] ?? $context[ModalContextName] ?? $context[PopoverContextName] as PopoverContext;
 	if (!popoverContext) {
-		throw new Error("Menu must be contained within a Contextual, Prompt or Popover");
+		throw new Error("Menu must be contained within a Context, Modal or Popover");
 	}
-	const { setVisible, handleButton, modal, visible } = popoverContext;
+	const { setVisible, handleButton, visible } = popoverContext;
 
 	// Check whether this is a menu in a popout
 	const popoutContext = $context[MenuPopoutContextName] as MenuPopoutContext;
@@ -68,7 +78,7 @@ export default function Menu() {
 	}
 
 	function registerItem(setFocused: () => void) {
-		// Add the item"s state to the array and return its index
+		// Add the item's state to the array and return its index
 		const newItemState: ItemState = {
 			setFocused
 		};
@@ -147,11 +157,11 @@ export default function Menu() {
 
 	@render {
 		<div
-			{$props.id}
-			class={`torp-menu ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-menu ${$props?.class ?? ""}`.trim()}
 			tabindex="-1"
 			role="menu"
-			aria-label={$props.ariaLabel}
+			aria-label={$props?.ariaLabel}
 			aria-orientation="vertical"
 		>
 			<slot />

package/dist/Menu/MenuButton.torp

@@ -1,12 +1,25 @@
 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,
+	/** Raised when the button is clicked */
+	onclick?: (e: MouseEvent) => void,
+	/** Raised when a key is pressed down */
+	onkeydown?: (e: KeyboardEvent) => void,
+}
+
 /**
  * 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 | undefined) {
 	let button: HTMLButtonElement;
 
 	// Get stuff out of the MenuContext
@@ -19,14 +32,18 @@ export default function MenuButton() {
 	// Register this item with the parent Menu and store the index
 	const { index } = registerItem(setFocused);
 
-	function handleKeyDown(e) {
+	function handleKeyDown(e: KeyboardEvent) {
 		handleItemKey(e);
-		if ($props.onkeydown) $props.onkeydown(e);
+		if ($props?.onkeydown) {
+			$props.onkeydown(e);
+		}
 	}
 
-	function handleClick(e) {
-		handleButton($props.value);
-		if ($props.onclick) $props.onclick(e);
+	function handleClick(e: MouseEvent) {
+		handleButton($props?.value);
+		if ($props?.onclick) {
+			$props.onclick(e);
+		}
 	}
 
 	function setFocused() {
@@ -35,13 +52,13 @@ export default function MenuButton() {
 
 	@render {
 		<button
-			{$props.id}
-			class={`torp-menu-button ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-menu-button ${$props?.class ?? ""}`.trim()}
 			type="button"
-			{$props.disabled}
+			{$props?.disabled}
 			role="menuitem"
-			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={handleKeyDown}
 			onclick={handleClick}
 			onfocus={() => handleItemFocus(index)}

package/dist/Menu/MenuCheck.torp

@@ -5,20 +5,33 @@ 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,
+	/** Raised when the checkbox is clicked */
+	onclick?: (e: MouseEvent) => void,
+}
+
 /**
  * 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 | 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;
@@ -43,22 +56,24 @@ export default function MenuCheck() {
 		button.focus();
 	}
 
-	function handleClick() {
+	function handleClick(e: MouseEvent) {
 		$state.checked = !$state.checked;
-		if ($props.onclick) $props.onclick();
+		if ($props?.onclick) {
+			$props.onclick(e);
+		}
 	}
 
 	@render {
 		<button
-			{$props.id}
-			class={`torp-menu-check ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-menu-check ${$props?.class ?? ""}`.trim()}
 			type="button"
-			{$props.disabled}
+			{$props?.disabled}
 			role="menuitemcheckbox"
-			aria-checked={$props.checked ? "true" : "false"}
-			aria-disabled={$props.disabled ? "true" : undefined}
-			data-state={$props.checked ? "checked" : "unchecked"}
-			data-disabled={$props.disabled ? "true" : undefined}
+			aria-checked={$props?.checked ? "true" : "false"}
+			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/MenuGroup.torp

@@ -1,17 +1,25 @@
+
+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 | undefined) {
 	// TODO: Intercept the context to steal toggleItem??
 
 	@render {
 		<div
-			{$props.id}
-			class={`torp-menu-group ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-menu-group ${$props?.class ?? ""}`.trim()}
 			role="group"
-			aria-label={$props.ariaLabel}
+			aria-label={$props?.ariaLabel}
 		>
 			<slot />
 		</div>

package/dist/Menu/MenuIndicator.torp

@@ -1,12 +1,19 @@
 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 | undefined) {
 	// Get stuff out of the MenuButtonContext
 	const context = $context[MenuButtonContextName] as MenuButtonContext;
 	if (!context) {
@@ -17,10 +24,10 @@ export default function MenuIndicator() {
 	@render {
 		@if ($state.checked) {
 			<div
-				{$props.id}
-				class={`torp-menu-indicator ${$props.class ?? ""}`.trim()}
-				aria-disabled={$props.disabled ? "true" : undefined}
-				data-disabled={$props.disabled ? "true" : undefined}
+				{$props?.id}
+				class={`torp-menu-indicator ${$props?.class ?? ""}`.trim()}
+				aria-disabled={$props?.disabled ? "true" : undefined}
+				data-disabled={$props?.disabled ? "true" : undefined}
 			>
 				<slot />
 			</div>

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,
+	/** 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,
+}
+
 /**
  * A popout that is attached to a menu button and can be used to show a submenu.
  *
@@ -7,21 +22,14 @@ import { MenuPopoutContextName, type MenuPopoutContext } from "./MenuTypes";
  *
  * ```
  * <MenuPopout>
- *     <MenuPopoutTrigger /> (optional)
+ * 	<MenuPopoutTrigger /> (optional)
  * 	<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) {
-	$props.visible ??= false;
-
+export default function MenuPopout($props: MenuPopoutProps | undefined) {
 	let $state = $watch({
-		visible: $props.visible
+		visible: $props?.visible ?? false
 	});
 
 	let result: any;
@@ -39,9 +47,9 @@ export default function MenuPopout($props) {
 
 	let firstToggle = true;
 	$run(() => {
-		const ontoggle = $props.ontoggle;
-		const onopen = $props.onopen;
-		const onclose = $props.onclose;
+		const ontoggle = $props?.ontoggle;
+		const onopen = $props?.onopen;
+		const onclose = $props?.onclose;
 		const visible = $state.visible;
 		if (firstToggle) {
 			firstToggle = false;
@@ -61,8 +69,8 @@ export default function MenuPopout($props) {
 
 	@render {
 		<div
-			{$props.id}
-			class={`torp-menu-popout ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-menu-popout ${$props?.class ?? ""}`.trim()}
 			onmouseleave={handleMouseLeave}
 		>
 			<slot />

package/dist/Menu/MenuPopoutContent.torp

@@ -2,16 +2,21 @@
 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() {
-	$props.side ??= "right";
-	$props.alignment ??= "start";
-
+export default function MenuPopoutContent($props: MenuPopoutContentProps | undefined) {
 	let div: HTMLDivElement;
 	let shown = false;
 
@@ -56,14 +61,16 @@ export default function MenuPopoutContent() {
 			throw new Error("MenuPopoutContent must have an anchor element");
 		}
 
-		setPopoverPosition(popoutContext.anchorElement, div, $props.side, $props.alignment);
+		let side = $props?.side ?? "right";
+		let alignment = $props?.alignment ?? "start";
+		setPopoverPosition(popoutContext.anchorElement, div, side, alignment);
 	}
 
 	@render {
 		@if ($state.visible) {
 			<div
-				{$props.id}
-				class={`torp-menu-popout-content ${$props.class ?? ""}`.trim()}
+				{$props?.id}
+				class={`torp-menu-popout-content ${$props?.class ?? ""}`.trim()}
 				&ref={div}
 				onmount={show}
 			>