@torpor/ui 0.4.0 → 1.0.0

package/dist/TagInput/TagInput.torp

@@ -0,0 +1,378 @@
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import $handle from "../utils/$handle";
+import {
+	type FieldContext,
+	FieldContextName,
+	type FormContext,
+	FormContextName,
+} from "../Form/FormTypes";
+import FormValues from "../Form/FormValues.torp";
+import { type Loader, createItemLoader } from "../utils/loader";
+import getId from "../utils/getId";
+import createFormField from "../utils/formField";
+
+interface TagInputProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The current tags */
+	value?: Bindable<string[]>;
+	/** Placeholder text for the empty input */
+	placeholder?: string;
+	/** If set to true, the user cannot interact with this input */
+	disabled?: boolean;
+	/** An accessible name for the input */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when the tags have changed */
+	onchange?: (value: string[]) => void;
+	/**
+	 * Reads suggestions from the network (or anywhere async) as the user
+	 * types, receiving `{ searchText }`. Suggestions are offered in a
+	 * dropdown; selecting one adds it as a tag
+	 */
+	load?: Loader;
+	/** Extracts the display text for a suggestion (defaults to `label ?? text ?? item`) */
+	getItemLabel?: (item: any) => any;
+	/** Raised when the suggestion list opens or closes */
+	onopen?: (open: boolean) => void;
+}
+
+/**
+ * An input where the user enters multiple free-text values, each shown as a
+ * tag that can be removed. Typing a value and pressing Enter or comma adds
+ * it as a tag, and pressing Backspace in an empty field removes the last one.
+ */
+export default function TagInput($props: TagInputProps | undefined) {
+	let input: HTMLInputElement;
+	let root: HTMLElement;
+
+	// Wire up the enclosing Form and Field, if any
+	const form = createFormField(
+		$props?.name,
+		$context[FormContextName] as FormContext | undefined,
+		$context[FieldContextName] as FieldContext | undefined,
+	);
+
+	function getDisabled(): boolean {
+		return $props?.disabled === true;
+	}
+
+	let defaultId = getId();
+
+	let $state = $watch({
+		// Seed from the props so the initial tags render; $bind handles later
+		// pushes both ways
+		value: ($props?.value ?? []) as string[],
+		text: "",
+		suggestionsOpen: false,
+		activeSuggestion: -1,
+	});
+
+	$bind($state, $props, "value");
+
+	if ($props?.load !== undefined && typeof $props.load !== "function") {
+		throw new Error("TagInput: `load` must be a function");
+	}
+	const hasLoader = typeof $props?.load === "function";
+
+	function getLabel(item: any): string {
+		const getItemLabel = $props?.getItemLabel;
+		if (getItemLabel) return String(getItemLabel(item));
+		const label = (item as any)?.label ?? (item as any)?.text ?? item;
+		return typeof label === "string" ? label : String(label);
+	}
+
+	// Fetches suggestions as the text changes; nothing is fetched while the
+	// field is empty (the loader only mounts with the suggestion list)
+	const $load = hasLoader
+		? createItemLoader({
+				load: $props!.load!,
+				getRequest: () => ({ searchText: $state.text }),
+			})
+		: undefined;
+
+	function openSuggestions() {
+		if (!hasLoader || $state.text.trim() === "") return;
+		if (!$state.suggestionsOpen) {
+			$state.suggestionsOpen = true;
+			$props?.onopen?.(true);
+		}
+	}
+
+	function closeSuggestions() {
+		if ($state.suggestionsOpen) {
+			$state.suggestionsOpen = false;
+			$state.activeSuggestion = -1;
+			$props?.onopen?.(false);
+		}
+	}
+
+	function suggestionId(index: number): string {
+		return `${defaultId}-suggestion-${index}`;
+	}
+
+	function suggestions(): any[] {
+		return $load ? $load.items : [];
+	}
+
+	// Dispatch the change event when the tags change
+	$handle((first) => {
+		const values = $state.value;
+		if (!first) $props?.onchange?.([...values]);
+	});
+
+	// Keep the input's value in sync with the text; typing sets the property
+	// directly, so an attribute alone would not update it
+	function syncInput() {
+		if (input && input.value !== $state.text) {
+			input.value = $state.text;
+		}
+	}
+	$run(() => {
+		const text = $state.text;
+		if (input && input.value !== text) {
+			input.value = text;
+		}
+	});
+	$onmount(() => syncInput());
+
+	function addTagFromText(text: string) {
+		const trimmed = text.trim();
+		if (trimmed === "") return;
+		$state.value = [...$state.value, trimmed];
+		$state.text = "";
+		syncInput();
+		closeSuggestions();
+		input?.focus();
+		form.handleInput();
+	}
+
+	function addTag() {
+		if (getDisabled()) return;
+
+		// A highlighted suggestion is selected over the raw text
+		if ($state.suggestionsOpen && $state.activeSuggestion >= 0) {
+			const item = suggestions()[$state.activeSuggestion];
+			if (item !== undefined) {
+				addTagFromText(getLabel(item));
+				return;
+			}
+		}
+		addTagFromText($state.text);
+	}
+
+	function removeTag(index: number) {
+		if (getDisabled()) return;
+		$state.value = $state.value.filter((_, i) => i !== index);
+		form.handleInput();
+	}
+
+	function removeLastTag() {
+		if (getDisabled()) return;
+		if ($state.text === "" && $state.value.length > 0) {
+			$state.value = $state.value.slice(0, -1);
+			form.handleInput();
+		}
+	}
+
+	function handleInput(e: Event) {
+		const el = e.currentTarget as HTMLInputElement;
+		$state.text = el.value;
+		$state.activeSuggestion = -1;
+		if ($state.text.trim() === "") {
+			closeSuggestions();
+		} else {
+			openSuggestions();
+		}
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		if (getDisabled()) return;
+
+		switch (e.key) {
+			case "ArrowDown": {
+				if ($state.suggestionsOpen) {
+					e.preventDefault();
+					const count = suggestions().length;
+					if (count > 0) {
+						$state.activeSuggestion = Math.min(count - 1, $state.activeSuggestion + 1);
+					}
+				}
+				break;
+			}
+			case "ArrowUp": {
+				if ($state.suggestionsOpen) {
+					e.preventDefault();
+					$state.activeSuggestion = Math.max(-1, $state.activeSuggestion - 1);
+				}
+				break;
+			}
+			case "Escape": {
+				if ($state.suggestionsOpen) {
+					e.preventDefault();
+					closeSuggestions();
+				}
+				break;
+			}
+			case "Enter": {
+				e.preventDefault();
+				addTag();
+				break;
+			}
+			case ",": {
+				e.preventDefault();
+				addTag();
+				break;
+			}
+			case "Backspace": {
+				if ($state.text === "") {
+					e.preventDefault();
+					removeLastTag();
+				}
+				break;
+			}
+		}
+	}
+
+	function pickSuggestion(item: any) {
+		addTagFromText(getLabel(item));
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={[
+				"torp-tag-input",
+				getDisabled() ? "torp-tag-input-disabled" : undefined,
+				$props?.class,
+			]}
+			{$props?.style}
+			data-valid={form.valid ? "valid" : "invalid"}
+			aria-describedby={form.messageId}
+			aria-invalid={form.inField && !form.valid ? "true" : undefined}
+			&ref={root}
+			onfocusout={(e: FocusEvent) => {
+				// Only blur when focus leaves the whole input
+				if (!root.contains(e.relatedTarget as Node | null)) {
+					form.handleBlur();
+				}
+			}}
+			onmousedown={(e: MouseEvent) => {
+				// Focus the field wherever the user clicks, without stealing
+				// focus from the remove button they may have clicked
+				if (!getDisabled() && e.target === e.currentTarget) {
+					e.preventDefault();
+					input?.focus();
+				}
+			}}
+		>
+			<ul class="torp-tag-input-tags">
+				@for (let [index, tag] of $state.value.entries()) {
+					@key = index
+					<li class="torp-tag-input-tag">
+						<span class="torp-tag-input-tag-text">{tag}</span>
+						<button
+							type="button"
+							class="torp-tag-input-remove"
+							aria-label={`Remove ${tag}`}
+							disabled={getDisabled()}
+							onclick={() => removeTag(index)}
+						>
+							<slot>×</slot>
+						</button>
+					</li>
+				}
+			</ul>
+			<input
+				class="torp-tag-input-field"
+				type="text"
+				&ref={input}
+				value={$state.text}
+				placeholder={$props?.placeholder}
+				disabled={getDisabled()}
+				aria-label={$props?.ariaLabel}
+				role={hasLoader ? "combobox" : undefined}
+				aria-expanded={hasLoader ? ($state.suggestionsOpen ? "true" : "false") : undefined}
+				aria-controls={$state.suggestionsOpen ? `${defaultId}-suggestions` : undefined}
+				aria-autocomplete="list"
+				aria-activedescendant={$state.activeSuggestion >= 0 ? suggestionId($state.activeSuggestion) : undefined}
+				oninput={handleInput}
+				onkeydown={handleKey}
+			/>
+			@if ($state.suggestionsOpen) {
+				@try {
+					@await {
+						<ul
+							id={`${defaultId}-suggestions`}
+							class="torp-tag-input-suggestions"
+							role="listbox"
+							aria-label={$props?.ariaLabel}
+						>
+							@for (let [index, item] of suggestions().entries()) {
+								@key = getLabel(item)
+								<li
+									class="torp-tag-input-suggestion"
+									role="option"
+									id={suggestionId(index)}
+									aria-selected={$state.activeSuggestion === index ? "true" : "false"}
+									data-active={$state.activeSuggestion === index ? "active" : undefined}
+									onmouseenter={() => ($state.activeSuggestion = index)}
+									onmousedown={(e: MouseEvent) => {
+										// mousedown so the field doesn't blur first
+										e.preventDefault();
+										pickSuggestion(item);
+									}}
+								>
+									{getLabel(item)}
+								</li>
+							}
+							@if (suggestions().length === 0) {
+								<li class="torp-tag-input-empty" role="presentation">No matches.</li>
+							}
+						</ul>
+					} with {
+						<div class="torp-tag-input-loading" role="status">Loading…</div>
+					}
+				} catch (err) {
+					<div class="torp-tag-input-error" role="alert">
+						{err instanceof Error ? err.message : String(err)}
+					</div>
+				}
+			}
+		</div>
+
+		<FormValues name={form.name} value={$state.value} />
+	}
+
+	@style {
+		/* Headless: layout only, so the tags sit in a row with the field. All
+		   appearance is up to the consuming theme */
+		.torp-tag-input {
+			display: flex;
+			flex-wrap: wrap;
+		}
+		.torp-tag-input-tags {
+			display: flex;
+			flex-wrap: wrap;
+			list-style: none;
+			margin: 0;
+			padding: 0;
+		}
+		.torp-tag-input-field {
+			flex: 1 1 auto;
+			min-width: 4em;
+		}
+		.torp-tag-input-suggestions {
+			position: absolute;
+			list-style: none;
+			margin: 0;
+			padding: 0;
+			z-index: 10;
+		}
+	}
+}

package/dist/TagInput/index.d.ts

@@ -0,0 +1,48 @@
+import { type SlotRender } from "@torpor/view";
+
+
+interface TagInputProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The current tags */
+	value?: Bindable<string[]>;
+	/** Placeholder text for the empty input */
+	placeholder?: string;
+	/** If set to true, the user cannot interact with this input */
+	disabled?: boolean;
+	/** An accessible name for the input */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when the tags have changed */
+	onchange?: (value: string[]) => void;
+	/**
+	 * Reads suggestions from the network (or anywhere async) as the user
+	 * types, receiving `{ searchText }`. Suggestions are offered in a
+	 * dropdown; selecting one adds it as a tag
+	 */
+	load?: Loader;
+	/** Extracts the display text for a suggestion (defaults to `label ?? text ?? item`) */
+	getItemLabel?: (item: any) => any;
+	/** Raised when the suggestion list opens or closes */
+	onopen?: (open: boolean) => void;
+}
+
+/**
+ * An input where the user enters multiple free-text values, each shown as a
+ * tag that can be removed. Typing a value and pressing Enter or comma adds
+ * it as a tag, and pressing Backspace in an empty field removes the last one.
+ */
+declare function TagInput(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: TagInputProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { TagInput };

package/dist/TagInput/index.js

@@ -0,0 +1,2 @@
+import TagInput from "./TagInput.torp";
+export { TagInput };