@torpor/ui 0.1.7 → 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

@@ -0,0 +1,169 @@
+import { PopoverContextName, type PopoverContext } from "../Popover/PopoverTypes";
+import {
+	MenuContextName,
+	type MenuContext,
+	type ItemState,
+	MenuPopoutContextName,
+	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.
+ *
+ * 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>
+ * ```
+ */
+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;
+
+	// Get stuff out of the PopoverContext
+	const popoverContext = $context[PopoverContextName] as PopoverContext;
+	if (!popoverContext) {
+		throw new Error("Menu must be contained within a Contextual, Prompt or Popover");
+	}
+	const { setVisible, handleButton, modal, visible } = popoverContext;
+
+	// Check whether this is a menu in a popout
+	const popoutContext = $context[MenuPopoutContextName] as MenuPopoutContext;
+	const inPopout = !!popoutContext;
+	const setPopoutVisible = popoutContext?.setVisible;
+
+	// Set the focusFirstElement method in the PopoverContext(s) so that it can be called after everything has been shown
+	popoverContext.focusFirstElement = focusFirstElement;
+	if (popoutContext) {
+		popoutContext.focusFirstElement = focusFirstElement;
+	}
+
+	// Set the context to pass down to items
+	let context: MenuContext = {
+		setVisible,
+		handleButton,
+		handleItemFocus,
+		handleItemKey,
+		visible,
+		registerItem
+	};
+	$context[MenuContextName] = context;
+
+	function focusFirstElement() {
+		if (itemStates.length) {
+			itemStates[0].setFocused();
+		}
+	}
+
+	function registerItem(setFocused: () => void) {
+		// Add the item"s state to the array and return its index
+		const newItemState: ItemState = {
+			setFocused
+		};
+		itemStates.push(newItemState);
+		itemStates = itemStates;
+		return { index: itemStates.length - 1 };
+	}
+
+	function handleItemFocus(index: number) {
+		focusIndex = index;
+	}
+
+	function handleItemKey(e: KeyboardEvent) {
+		switch (e.key) {
+			case "Esc":
+			case "Escape": {
+				e.preventDefault();
+				setVisible(false);
+				break;
+			}
+			case "Down":
+			case "ArrowDown": {
+				e.preventDefault();
+				focusItem("next");
+				break;
+			}
+			case "Up":
+			case "ArrowUp": {
+				e.preventDefault();
+				focusItem("previous");
+				break;
+			}
+			case "Left":
+			case "ArrowLeft": {
+				// TODO: This should be based on what side the menu shows on
+				if (inPopout) {
+					e.preventDefault();
+					setPopoutVisible(false);
+				}
+				break;
+			}
+			case "Home": {
+				e.preventDefault();
+				focusItem("start");
+				break;
+			}
+			case "End": {
+				e.preventDefault();
+				focusItem("end");
+				break;
+			}
+		}
+	}
+
+	function focusItem(target: "start" | "previous" | "next" | "end") {
+		switch (target) {
+			case "start": {
+				focusIndex = 0;
+				break;
+			}
+			case "previous": {
+				focusIndex = Math.max(0, focusIndex - 1);
+				break;
+			}
+			case "next": {
+				focusIndex = Math.min(itemStates.length - 1, focusIndex + 1);
+				break;
+			}
+			case "end": {
+				focusIndex = itemStates.length - 1;
+				break;
+			}
+		}
+		itemStates[focusIndex]?.setFocused();
+	}
+
+	@render {
+		<div
+			{$props.id}
+			class={`torp-menu ${$props.class ?? ""}`.trim()}
+			tabindex="-1"
+			role="menu"
+			aria-label={$props.ariaLabel}
+			aria-orientation="vertical"
+		>
+			<slot />
+		</div>
+	}
+}

package/src/Menu/MenuButton.torp

@@ -0,0 +1,64 @@
+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.
+ *
+ */
+export default function MenuButton($props: MenuButtonProps) {
+	$props ??= $watch({});
+
+	let button: HTMLButtonElement;
+
+	// Get stuff out of the MenuContext
+	const menuContext = $context[MenuContextName] as MenuContext;
+	if (!menuContext) {
+		throw new Error("MenuButton must be contained within a Menu");
+	}
+	const { registerItem, handleButton, handleItemKey, handleItemFocus } = menuContext;
+
+	// Register this item with the parent Menu and store the index
+	const { index } = registerItem(setFocused);
+
+	function handleKeyDown(e) {
+		handleItemKey(e);
+		if ($props.onkeydown) $props.onkeydown(e);
+	}
+
+	function handleClick(e) {
+		handleButton($props.value);
+		if ($props.onclick) $props.onclick(e);
+	}
+
+	function setFocused() {
+		button.focus();
+	}
+
+	@render {
+		<button
+			{$props.id}
+			class={`torp-menu-button ${$props.class ?? ""}`.trim()}
+			type="button"
+			{$props.disabled}
+			role="menuitem"
+			aria-disabled={$props.disabled ? "true" : undefined}
+			data-disabled={$props.disabled ? "true" : undefined}
+			onkeydown={handleKeyDown}
+			onclick={handleClick}
+			onfocus={() => handleItemFocus(index)}
+			&ref={button}
+		>
+			<slot />
+		</button>
+	}
+}

package/src/Menu/MenuCheck.torp

@@ -0,0 +1,81 @@
+import {
+	MenuButtonContextName,
+	MenuContextName,
+	type MenuButtonContext,
+	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.
+ *
+ */
+export default function MenuCheck($props: MenuCheckProps) {
+	$props ??= $watch({});
+
+	let $state = $watch({
+		checked: $props.checked
+	});
+
+	$run(() => {
+		$props.checked = $state.checked;
+	});
+
+	let button: HTMLButtonElement;
+
+	// Get stuff out of the MenuContext
+	const menuContext = $context[MenuContextName] as MenuContext;
+	if (!menuContext) {
+		throw new Error("MenuCheck must be contained within a Menu");
+	}
+	const { registerItem, handleItemKey, handleItemFocus } = menuContext;
+
+	// Register this item with the parent Menu
+	const { index } = registerItem(setFocused);
+
+	// Set the context to pass down to items
+	let context: MenuButtonContext = {
+		state: $state
+	};
+	$context[MenuButtonContextName] = context;
+
+	function setFocused() {
+		button.focus();
+	}
+
+	function handleClick() {
+		$state.checked = !$state.checked;
+		if ($props.onclick) $props.onclick();
+	}
+
+	@render {
+		<button
+			{$props.id}
+			class={`torp-menu-check ${$props.class ?? ""}`.trim()}
+			type="button"
+			{$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}
+			onkeydown={handleItemKey}
+			onclick={handleClick}
+			onfocus={() => handleItemFocus(index)}
+			&ref={button}
+		>
+			<slot />
+		</button>
+	}
+}

package/src/Menu/MenuGroup.torp

@@ -0,0 +1,29 @@
+
+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.
+ */
+export default function MenuGroup($props: MenuGroupProps) {
+	$props ??= $watch({});
+
+	// TODO: Intercept the context to steal toggleItem??
+
+	@render {
+		<div
+			{$props.id}
+			class={`torp-menu-group ${$props.class ?? ""}`.trim()}
+			role="group"
+			aria-label={$props.ariaLabel}
+		>
+			<slot />
+		</div>
+	}
+}

package/src/Menu/MenuIndicator.torp

@@ -0,0 +1,38 @@
+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.
+ */ 
+export default function MenuIndicator($props: MenuIndicatorProps) {
+	$props ??= $watch({});
+
+	// Get stuff out of the MenuButtonContext
+	const context = $context[MenuButtonContextName] as MenuButtonContext;
+	if (!context) {
+		throw new Error("MenuIndicator must be contained within a MenuCheck or MenuRadio");
+	}
+	let $state = context.state;
+
+	@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}
+			>
+				<slot />
+			</div>
+		}
+	}
+}

package/src/Menu/MenuPopout.torp

@@ -0,0 +1,82 @@
+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.
+ *
+ * The structure of a MenuPopout is:
+ *
+ * ```
+ * <MenuPopout>
+ *     <MenuPopoutTrigger /> (optional)
+ * 	<MenuPopoutContent />
+ * </MenuPopout>
+ * ```
+ */
+export default function MenuPopout($props: MenuPopoutProps) {
+	$props ??= $watch({});
+	$props.visible ??= false;
+
+	let $state = $watch({
+		visible: $props.visible
+	});
+
+	let result: any;
+
+	// Set the context to pass down to items
+	let context: MenuPopoutContext = {
+		setVisible,
+		state: $state
+	};
+	$context[MenuPopoutContextName] = context;
+
+	function setVisible(value: boolean) {
+		$state.visible = value;
+	}
+
+	let firstToggle = true;
+	$run(() => {
+		const ontoggle = $props.ontoggle;
+		const onopen = $props.onopen;
+		const onclose = $props.onclose;
+		const visible = $state.visible;
+		if (firstToggle) {
+			firstToggle = false;
+		} else {
+			if (ontoggle) ontoggle(visible);
+			if (visible) {
+				if (onopen) onopen()
+			} else {
+				if (onclose) onclose(result);
+			}
+		}
+	});
+
+	function handleMouseLeave() {
+		setVisible(false);
+	}
+
+	@render {
+		<div
+			{$props.id}
+			class={`torp-menu-popout ${$props.class ?? ""}`.trim()}
+			onmouseleave={handleMouseLeave}
+		>
+			<slot />
+		</div>
+	}
+}