@torpor/ui 0.4.0 → 1.0.1

package/dist/Form/FileDrop.torp

@@ -0,0 +1,187 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import getId from "../utils/getId";
+import {
+	type FieldContext,
+	FieldContextName,
+	type FormContext,
+	FormContextName,
+} from "./FormTypes";
+
+interface FileDropProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The name of the input's form data field */
+	name?: string;
+	/** The type of files that this input accepts e.g. `image/*` */
+	accept?: string;
+	/** Whether the user can drop or select multiple files at once */
+	multiple?: boolean;
+	/** If set to true, the user cannot interact with this dropzone */
+	disabled?: boolean;
+	/** An accessible name for the dropzone */
+	ariaLabel?: string;
+	/** Raised when files have been dropped or selected */
+	onfiles?: (files: File[]) => void;
+}
+
+/**
+ * A file input in a form, where the user can drop one or more files onto it,
+ * or activate it to select files with a file dialog.
+ *
+ * See [the MDN docs for the Drag and Drop API](https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API).
+ */
+export default function FileDrop($props: FileDropProps | undefined) {
+	let defaultId = getId();
+	let inputId = `${$props?.id ?? defaultId}-input`;
+	let input: HTMLInputElement;
+
+	let name = $props?.name;
+
+	let blurred = false;
+
+	function getDisabled(): boolean {
+		return $props?.disabled === true;
+	}
+
+	// Get stuff out of the FormContext and FieldContext
+	const formContext = $context[FormContextName] as FormContext;
+	const fieldContext = $context[FieldContextName] as FieldContext;
+	if (fieldContext) {
+		name ??= fieldContext.name;
+	}
+
+	// This will change the form's enctype to `multipart/form-data`
+	if (formContext) {
+		formContext.state.hasFile = true;
+	}
+
+	// Use the FieldContext's state, or create a new one
+	let $state =
+		fieldContext?.state ??
+		$watch({
+			inputId,
+			value: null,
+			errors: {} as Record<string, string>,
+			valid: false,
+			message: "",
+		});
+
+	// Set the input ID now that we know it and it will get linked with the associated label
+	$state.inputId = inputId;
+
+	function handleFiles(files: FileList | File[] | undefined | null) {
+		if (getDisabled() || !files) return;
+		const all = Array.from(files);
+		if (all.length === 0) return;
+		const selected = $props?.multiple ? all : all.slice(0, 1);
+
+		if (formContext) {
+			formContext.validate();
+		}
+		if (fieldContext && blurred) {
+			fieldContext.validate();
+		}
+
+		$props?.onfiles?.(selected);
+	}
+
+	function openDialog() {
+		if (getDisabled()) return;
+		input?.click();
+	}
+
+	function handleClick(e: MouseEvent) {
+		e.preventDefault();
+		openDialog();
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		if (e.key === "Enter" || e.key === " ") {
+			e.preventDefault();
+			openDialog();
+		}
+	}
+
+	function handleDrop(e: DragEvent) {
+		e.preventDefault();
+		if (getDisabled()) return;
+		(e.currentTarget as HTMLElement)?.removeAttribute("data-state");
+		handleFiles(e.dataTransfer?.files);
+	}
+
+	function handleDragOver(e: DragEvent) {
+		e.preventDefault();
+		if (getDisabled()) return;
+		(e.currentTarget as HTMLElement)?.setAttribute("data-state", "over");
+	}
+
+	function handleDragLeave(e: DragEvent) {
+		(e.currentTarget as HTMLElement)?.removeAttribute("data-state");
+	}
+
+	function handleChange(e: Event) {
+		handleFiles((e.currentTarget as HTMLInputElement).files);
+	}
+
+	function handleBlur() {
+		if (fieldContext) {
+			fieldContext.validate();
+		}
+		blurred = true;
+	}
+
+	@render {
+		<div
+			id={$props?.id ?? defaultId}
+			class={[
+				"torp-file-drop",
+				getDisabled() ? "torp-file-drop-disabled" : undefined,
+				$props?.class,
+			]}
+			{$props?.style}
+			role="button"
+			tabindex={getDisabled() ? -1 : 0}
+			aria-label={$props?.ariaLabel}
+			aria-disabled={getDisabled() ? "true" : undefined}
+			data-valid={$state.valid ? "valid" : "invalid"}
+			aria-describedby={$state.messageId}
+			aria-invalid={fieldContext && !$state.valid ? "true" : undefined}
+			onclick={handleClick}
+			onkeydown={handleKey}
+			onblur={handleBlur}
+			ondrop={handleDrop}
+			ondragover={handleDragOver}
+			ondragleave={handleDragLeave}
+		>
+			<slot>
+				<span class="torp-file-drop-text">Drag and drop files here, or press Enter to browse</span>
+			</slot>
+		</div>
+
+		<input
+			id={inputId}
+			class="torp-file-drop-input"
+			type="file"
+			{name}
+			aria-hidden="true"
+			tabindex={-1}
+			multiple={$props?.multiple}
+			{$props?.accept}
+			disabled={getDisabled()}
+			&ref={input}
+			onchange={handleChange}
+		/>
+	}
+
+	@style {
+		/* Headless: hide the input, since the dropzone is the interactive
+		   element. All appearance is up to the consuming theme */
+		.torp-file-drop-input {
+			display: none;
+		}
+	}
+}

package/dist/Form/Form.torp

@@ -1,41 +1,44 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { FormContextName, type ValidationIssue, type FormContext } from "./FormTypes";
-import { StandardSchemaV1 } from "./StandardSchemaV1"
+import { type FormContext, FormContextName, type ValidationIssue } from "./FormTypes";
+import { StandardSchemaV1 } from "./StandardSchemaV1";
 
-interface FormProps {
+interface FormProps<Data = Record<string, any>> {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
-	/** The data to display in the form */
-	data?: any,
+	style?: StyleValue;
+	/**
+	 * The data to display in the form. Type it with the page's form result
+	 * (e.g. `PageForm<typeof server>`) to get field name autocomplete
+	 */
+	data?: Data;
 	/** Where to post the form's data **/
-	action?: string,
+	action?: string;
 	/** The action to use when submitting the form, which defaults to POST */
-	method?: string,
+	method?: string;
 	/**
 	 * The form's encoding type e.g. `multipart/form-data` where there are file
 	 * inputs. This will be automatically set unless overridden
 	 */
-	enctype?: string,
+	enctype?: string;
 	/** The schema validator to use for this form */
-	schema?: StandardSchemaV1,
-	onsubmit?: (e: SubmitEvent) => boolean | void | Promise<boolean | void>,
-};
+	schema?: StandardSchemaV1;
+	onsubmit?: (e: SubmitEvent) => boolean | void | Promise<boolean | void>;
+}
 
 /**
  * A form for submitting values.
  */
-export default function Form($props: FormProps | undefined) {
+export default function Form<Data = Record<string, any>>($props: FormProps<Data> | undefined) {
 	let $state = $watch({
 		data: $props?.data ?? {},
 		hasFile: false,
 		issues: [] as ValidationIssue[],
 		get valid() {
 			return this.issues.length === 0;
-		}
+		},
 	});
 
 	let submitted = false;
@@ -46,9 +49,9 @@ export default function Form($props: FormProps | undefined) {
 	let context: FormContext = {
 		schema: $props?.schema,
 		state: $state,
-		validate: handleValidate
+		validate: handleValidate,
 	};
-	
+
 	$context[FormContextName] = context;
 
 	async function validate() {
@@ -63,10 +66,10 @@ export default function Form($props: FormProps | undefined) {
 				for (let issue of result.issues) {
 					if (issue.path) {
 						// TODO: arrays with `[0]` etc
-						issues.push({ 
+						issues.push({
 							// @ts-ignore
 							path: issue.path.map((p) => p.key ?? p).join("."),
-							message: issue.message
+							message: issue.message,
 						});
 					}
 				}
@@ -97,7 +100,7 @@ export default function Form($props: FormProps | undefined) {
 			}
 			proceed = userSubmit !== false && !e.defaultPrevented;
 		}
-		
+
 		// If the user handled the submit, don't continue
 		if (!proceed) {
 			e.preventDefault();
@@ -105,7 +108,7 @@ export default function Form($props: FormProps | undefined) {
 		}
 
 		// If there's a @torpor/build context, call its submit event
-		let buildContext = $context["TorporBuildContext"];
+		let buildContext = $context?.["TorporBuildContext"];
 		if (buildContext?.onformsubmit) {
 			let buildSubmit = buildContext.onformsubmit(e);
 			if (buildSubmit instanceof Promise) {
@@ -138,7 +141,6 @@ export default function Form($props: FormProps | undefined) {
 			method={$props?.method ?? "POST"}
 			enctype={$props?.enctype ?? ($state.hasFile ? "multipart/form-data" : undefined)}
 			onsubmit={handleSubmit}
-			@// Set novalidate only if JS is enabled (to override HTML validation)
 			onmount={(e) => e.novalidate = true }
 		>
 			<slot />

package/dist/Form/FormTypes.ts

@@ -26,6 +26,8 @@ export interface FieldContext {
 	schema?: StandardSchemaV1;
 	state: {
 		inputId: string;
+		/** The ID of the Message component in this field, if any, for use with aria-describedby */
+		messageId?: string;
 		value?: any;
 		issues: ValidationIssue[];
 		valid: boolean;

package/dist/Form/FormValues.torp

@@ -0,0 +1,37 @@
+interface FormValuesProps {
+	/** The name of the form data field(s) */
+	name?: string;
+	/** The value, or an array of values, to submit with the form */
+	value?: any;
+}
+
+/**
+ * Converts a form value to its text representation, without relying on
+ * implicit primitive conversion (which fails for reactive proxies).
+ */
+function toText(value: any): string {
+	if (value == null) return "";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	return JSON.stringify(value);
+}
+
+/**
+ * Renders hidden inputs for a component's value, so that it can take part
+ * in native form submission. One input per entry when the value is an array.
+ * Nothing is rendered when the value is null or undefined, so that the
+ * field is omitted from the submitted form data.
+ */
+export default function FormValues($props: FormValuesProps | undefined) {
+	@render {
+		@if ($props?.name && $props.value != null) {
+			@if (Array.isArray($props.value)) {
+				@for (let item of $props.value) {
+					<input type="hidden" name={$props.name} value={toText(item)} />
+				}
+			} @else {
+				<input type="hidden" name={$props.name} value={toText($props.value)} />
+			}
+		}
+	}
+}

package/dist/Form/Hidden.torp

@@ -1,25 +1,17 @@
-import getId from "../utils/getId";
-import { FormContextName, FieldContextName, type FormContext, type FieldContext } from "./FormTypes";
-
 interface HiddenProps {
 	/** An ID for the root element */
 	id?: string;
 	/** The name of the input's form data field */
-	name?: string,
+	name?: string;
 	/** The data value that this field is bound to */
-	value?: any,
-};
+	value?: any;
+}
 
 /**
  * A standard input in a form.
  */
 export default function Hidden($props: HiddenProps | undefined) {
 	@render {
-		<input
-			{$props?.id}
-			type="hidden"
-			{$props?.name}
-			{$props?.value}
-		/>
+		<input {$props?.id} type="hidden" {$props?.name} {$props?.value} />
 	}
 }

package/dist/Form/Input.torp

@@ -1,35 +1,40 @@
-import type { ClassValue, StyleValue } from "@torpor/view";
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
 import getId from "../utils/getId";
-import { FormContextName, FieldContextName, type FormContext, type FieldContext } from "./FormTypes";
+import {
+	type FieldContext,
+	FieldContextName,
+	type FormContext,
+	FormContextName,
+} from "./FormTypes";
 
 interface InputProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
+	style?: StyleValue;
 	/** The input type */
-	type?: string, // TODO: "text" | "number" | "password" | "email" | "url" | "tel",
+	type?: string; // TODO: "text" | "number" | "password" | "email" | "url" | "tel",
 	/** The name of the input's form data field */
-	name?: string,
+	name?: string;
 	/** The data value that this field is bound to */
-	value?: any,
+	value: Bindable<any>;
 	/** Text to display when the input value is empty */
-	placeholder?: string,
+	placeholder?: string;
 	/** Whether the input should be readonly */
-	readonly?: boolean,
+	readonly?: boolean;
 	/** Whether the input's value is required */
-	required?: boolean,
+	required?: boolean;
 	/** The maximum number of characters allowed for the input value */
-	maxlength?: number,
+	maxlength?: number;
 	/** An ARIA label for describing the input to screen readers when there is no associated label element */
-	ariaLabel?: string,
+	ariaLabel?: string;
 	/** Raised on change */
-	onchange?: (e: Event) => void,
+	onchange?: (e: Event) => void;
 	/** Raised on input */
-	oninput?: (e: Event) => void,
-};
+	oninput?: (e: Event) => void;
+}
 
 /**
  * A standard input in a form.
@@ -38,7 +43,7 @@ export default function Input($props: InputProps | undefined) {
 	let defaultId = getId();
 
 	let type = $props?.type ?? "text";
-	let name = $props?.name
+	let name = $props?.name;
 
 	let blurred = false;
 
@@ -50,28 +55,27 @@ export default function Input($props: InputProps | undefined) {
 	}
 
 	// Use the FieldContext's state, or create a new one
-	let $state = fieldContext?.state ?? $watch({
-		inputId: $props?.id ?? defaultId,
-		value: $props?.value,
-		errors: {} as Record<string, string>,
-		valid: false,
-		message: "",
-	});
-
-	// Binding
-	$run(() => {
-		if ($props !== undefined) {
-			$props.value = $state.value;
-		}
-	});
+	let $state =
+		fieldContext?.state ??
+		$watch({
+			inputId: $props?.id ?? defaultId,
+			value: $props?.value,
+			errors: {} as Record<string, string>,
+			valid: false,
+			message: "",
+		});
 
 	// Set the input ID now that we know it and it will get linked with the associated label
 	$state.inputId = $props?.id ?? defaultId;
 
+	$bind($state, $props, "value");
+
 	// 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;
+		$state.value = $props?.type?.match(/^(number|range)$/)
+			? +e.currentTarget.value
+			: e.currentTarget.value;
 		if (formContext) {
 			formContext.validate();
 		}
@@ -104,7 +108,9 @@ export default function Input($props: InputProps | undefined) {
 			{$props?.maxlength}
 			aria-label={$props?.ariaLabel}
 			data-valid={$state.valid ? "valid" : "invalid"}
-			onchange={$props?.onchange}
+			aria-describedby={$state.messageId}
+			aria-invalid={fieldContext && !$state.valid ? "true" : undefined}
+			{$props?.onchange}
 			oninput={handleInput}
 			onblur={handleBlur}
 		/>

package/dist/Form/Label.torp

@@ -1,13 +1,13 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { FieldContextName, type FieldContext } from "./FormTypes";
+import { type FieldContext, FieldContextName } from "./FormTypes";
 
 interface LabelProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
+	style?: StyleValue;
 }
 
 /**

package/dist/Form/Message.torp

@@ -1,13 +1,14 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { FieldContextName, type FieldContext } from "./FormTypes";
+import getId from "../utils/getId";
+import { type FieldContext, FieldContextName } from "./FormTypes";
 
 interface MessageProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
+	style?: StyleValue;
 }
 
 /**
@@ -15,6 +16,8 @@ interface MessageProps {
  * problems that need to be fixed.
  */
 export default function Message($props: MessageProps | undefined) {
+	let defaultId = getId();
+
 	// Get stuff out of the FieldContext
 	const context = $context[FieldContextName] as FieldContext;
 	if (!context) {
@@ -22,12 +25,17 @@ export default function Message($props: MessageProps | undefined) {
 	}
 	const { state: $state } = context;
 
+	// Set the message ID so that it can be used with aria-describedby in
+	// input components
+	$state.messageId = $props?.id ?? defaultId;
+
 	@render {
 		@if ($state.message) {
-			<div 
-				{$props?.id}
+			<div
+				id={$props?.id ?? defaultId}
 				class={["torp-message", $props?.class]}
 				{$props?.style}
+				role="alert"
 				data-valid={$state.valid ? "valid" : "invalid"}
 			>
 				<slot name="message">

package/dist/Form/MessageSummary.torp

@@ -1,13 +1,13 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { FormContextName, type FormContext } from "./FormTypes";
+import { type FormContext, FormContextName } from "./FormTypes";
 
 interface MessageSummaryProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
+	style?: StyleValue;
 }
 
 /**
@@ -23,10 +23,11 @@ export default function MessageSummary($props: MessageSummaryProps | undefined)
 
 	@render {
 		@if ($state.issues.length > 0) {
-			<ul 
+			<ul
 				{$props?.id}
 				class={["torp-message-summary", $props?.class]}
 				{$props?.style}
+				role="alert"
 			>
 				<slot />
 				@for (let issue of $state.issues) {

package/dist/Form/Option.torp

@@ -1,28 +1,32 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import getId from "../utils/getId";
-import { FormContextName, FieldContextName, type FormContext, type FieldContext } from "./FormTypes";
 
 interface OptionProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
+	style?: StyleValue;
 	/** The data value that this option has */
-	value?: any,
-};
+	value?: any;
+}
 
 /**
  * An option in a select.
  */
 export default function Option($props: OptionProps | undefined) {
+	let $state = $watch({
+		value: $props?.value,
+	});
+
+	$bind($state, $props, "value");
+
 	@render {
 		<option
 			{$props?.id}
 			class={["torp-option", $props?.class]}
 			{$props?.style}
-			&value={$props.value}
+			&value={$state.value}
 		/>
 	}
 }