@torpor/ui 0.2.0 → 0.2.1

package/src/Form/Input.torp

@@ -0,0 +1,94 @@
+import getId from "../utils/getId";
+import { FormContextName, FieldContextName, type FormContext, type FieldContext } from "./FormTypes";
+
+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.
+ */
+export default function Input($props: InputProps) {
+	$props ??= $watch({});
+	$props.id ??= getId();
+	$props.type ??= "text";
+
+	let blurred = false;
+
+	// Get stuff out of the FormContext and FieldContext
+	const formContext = $context[FormContextName] as FormContext;
+	const fieldContext = $context[FieldContextName] as FieldContext;
+	if (fieldContext) {
+		$props.name ??= fieldContext.name;
+	}
+
+	// Use the FieldContext's state, or create a new one
+	let $state = fieldContext?.state ?? $watch({
+		inputId: $props.id,
+		value: $props.value,
+		errors: {} as Record<string, string>,
+		valid: false,
+		message: "",
+	});
+
+	// Binding
+	$run(() => {
+		$props.value = $state.value;
+	});
+
+	// Set the input ID now that we know it and it will get linked with the associated label
+	$state.inputId = $props.id;
+
+	// NOTE: Adapted this from https://stackoverflow.com/a/57393751,
+	// not sure if it's still a good way to do things
+	function handleInput(e: Event & { currentTarget: EventTarget & HTMLInputElement }) {
+		$state.value = $props!.type?.match(/^(number|range)$/) ? +e.currentTarget.value : e.currentTarget.value;
+		if (formContext) {
+			formContext.validate();
+		}
+		if (fieldContext && blurred) {
+			fieldContext.validate();
+		}
+	}
+
+	function handleBlur() {
+		if (fieldContext) {
+			fieldContext.validate();
+		}
+		blurred = true;
+	}
+
+	@render {
+		<input
+			{$props.id}
+			class={`torp-input ${$props.class ?? ""}`.trim()}
+			{$props.name}
+			&value={$state.value}
+			{$props.type}
+			{$props.placeholder}
+			{$props.readonly}
+			{$props.maxlength}
+			aria-label={$props.ariaLabel}
+			data-valid={$state.valid ? "valid" : "invalid"}
+			oninput={handleInput}
+			onblur={handleBlur}
+		/>
+	}
+}

package/src/Form/Label.torp

@@ -0,0 +1,31 @@
+import { FieldContextName, type FieldContext } from "./FormTypes";
+
+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.
+ */
+export default function Label($props?: LabelProps) {
+	// Get stuff out of the FieldContext
+	const context = $context[FieldContextName] as FieldContext;
+	if (!context) {
+		throw new Error("Label must be contained within a Field");
+	}
+	let { state: $state } = context;
+
+	@render {
+		<label
+			{$props?.id}
+			class={`torp-label ${$props?.class ?? ""}`.trim()}
+			for={$state.inputId}
+			data-valid={$state.valid ? "valid" : "invalid"}
+		>
+			<slot />
+		</label>
+	}
+}

package/src/Form/Message.torp

@@ -0,0 +1,35 @@
+import { FieldContextName, type FieldContext } from "./FormTypes";
+
+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.
+ */
+export default function Message($props?: MessageProps) {
+	// Get stuff out of the FieldContext
+	const context = $context[FieldContextName] as FieldContext;
+	if (!context) {
+		throw new Error("Message must be contained within a Field");
+	}
+	const { state: $state } = context;
+
+	@render {
+		@if ($state.message) {
+			<div 
+				{$props?.id}
+				class={`torp-message ${$props?.class ?? ""}`.trim()}
+				data-valid={$state.valid ? "valid" : "invalid"}
+			>
+				<slot name="message">
+					{$state.message}
+				</slot>
+			</div>
+		}
+	}
+}

package/src/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/src/Form/index.ts

@@ -0,0 +1,7 @@
+import Field from "./Field.torp";
+import Form from "./Form.torp";
+import Input from "./Input.torp";
+import Label from "./Label.torp";
+import Message from "./Message.torp";
+
+export { Form, Field, Label, Input, Message };

package/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/MenuBar/MenuBar.torp

@@ -1,5 +1,16 @@
 import { MenuBarContextName, type MenuBarContext, type ItemState } from "./MenuBarTypes";
 
+interface MenuBarProps {
+	/** 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 orientation of the menu, which affects keyboard navigation */
+	orientation?: "horizontal" | "vertical",
+}
+
 /**
  * A menu bar, similar to that shown at the top of Windows applications or at the top of the screen on Macs.
  *
@@ -17,11 +28,9 @@ import { MenuBarContextName, type MenuBarContext, type ItemState } from "./MenuB
  *     </MenuBarItem>
  * </MenuBar>
  * ```
- *
- * @prop {string} ariaLabel -- An ARIA label for describing the menu to screen readers
- * @prop {"horizontal" | "vertical"} orientation -- The orientation of the menu, which affects keyboard navigation
  */
-export default function MenuBar() {
+export default function MenuBar($props: MenuBarProps) {
+	$props ??= $watch({});
 	$props.orientation ??= "horizontal";
 
 	let $state = $watch({

package/src/MenuBar/MenuBarItem.torp

@@ -6,6 +6,21 @@ import {
 } from "./MenuBarTypes";
 import { PopoverContextName, type PopoverContext } from "../Popover/PopoverTypes";
 
+interface MenuBarItemProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether the item is visible */
+	visible?: boolean,
+	/** Called when the item is opened or closed */
+	ontoggle?: (visible: boolean) => void,
+	/** Called when the item has opened */
+	onopen?: () => void,
+	/** Called when the item has closed */
+	onclose?: () => void,
+}
+
 /**
  * A popout that is attached to a menubar button and can be used to show a submenu.
  *
@@ -17,13 +32,9 @@ import { PopoverContextName, type PopoverContext } from "../Popover/PopoverTypes
  *     <MenuBarItemContent />
  * </MenuBarItem>
  * ```
- *
- * @prop {boolean} visible -- Whether the item is visible
- * @prop {(boolean) => void} ontoggle -- Called when the item is opened or closed
- * @prop {() => void} onopen -- Called when the item has opened
- * @prop {() => void} onclose -- Called when the item has closed
  */
-export default function MenuBarItem() {
+export default function MenuBarItem($props: MenuBarItemProps) {
+	$props ??= $watch({});
 	$props.visible ??= false;
 
 	let $state = $watch({

package/src/MenuBar/MenuBarItemContent.torp

@@ -7,13 +7,22 @@ import {
 	type MenuBarItemContext
 } from "./MenuBarTypes";
 
+interface MenuBarItemContentProps {
+	/** 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 MenuBarItem 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 MenuBarItemContent() {
+export default function MenuBarItemContent($props: MenuBarItemContentProps) {
+	$props ??= $watch({});
 	$props.side ??= "bottom";
 	$props.alignment ??= "start";
 

package/src/MenuBar/MenuBarItemTrigger.torp

@@ -5,12 +5,21 @@ import {
 	type MenuBarItemContext
 } from "./MenuBarTypes";
 
+interface MenuBarItemTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether this button is disabled */
+	disabled?: boolean,
+}
+
 /**
  * A button that is placed in a MenuBar and opens a submenu.
  *
- * @prop {boolean} disabled -- Whether this button is disabled
  */
-export default function MenuBarItemTrigger() {
+export default function MenuBarItemTrigger($props: MenuBarItemTriggerProps) {
+	$props ??= $watch({});
 	$props.disabled ??= false;
 
 	let button: HTMLButtonElement;