@torpor/ui 1.0.2 → 1.1.1

package/dist/Slider/SliderTypes.ts

@@ -0,0 +1,34 @@
+export const SliderContextName: unique symbol = Symbol.for("torp.Slider");
+
+export interface SliderContext {
+	/** The minimum allowed value */
+	getMin: () => number;
+	/** The maximum allowed value */
+	getMax: () => number;
+	/** The amount by which the value is increased or decreased */
+	getStep: () => number;
+	/** The orientation of the slider */
+	getOrientation: () => "horizontal" | "vertical";
+	/** Whether the user cannot interact with the slider */
+	getDisabled: () => boolean;
+	/** The current value, clamped to the min and max */
+	getValue: () => number;
+	/** The percentage of the range that the value represents (0..100) */
+	getPct: () => number;
+	/** Sets the value, snapped to the step and clamped to the min and max */
+	setValue: (value: number) => void;
+	/** The accessible name for the slider, from the Slider's ariaLabel */
+	getAriaLabel: () => string | undefined;
+	/** Called from the handle when it is added */
+	registerHandle: (el: HTMLElement) => void;
+	/** Called from the handle when it is removed */
+	unregisterHandle: (el: HTMLElement) => void;
+	/** Whether the slider is contained within a Form Field */
+	inField: () => boolean;
+	/** Whether the slider's value is currently valid */
+	valid: () => boolean;
+	/** The ID of the Field's Message component, for aria-describedby */
+	messageId: () => string | undefined;
+	/** Called when the handle loses focus */
+	handleBlur: () => void;
+}

package/dist/Slider/index.d.ts

@@ -33,6 +33,17 @@ interface SliderProps {
  * dragging a thumb along a track or by using the keyboard.
  *
  * See [the WAI ARIA guidelines for Sliders](https://www.w3.org/WAI/ARIA/apg/patterns/slider/).
+ *
+ * The structure of a Slider is:
+ *
+ * ```
+ * <Slider>
+ * 	<SliderRange />
+ * 	<SliderHandle />
+ * </Slider>
+ * ```
+ *
+ * With no children, the range and handle are rendered automatically.
  */
 declare function Slider(
 	$parent: ParentNode,
@@ -42,4 +53,57 @@ declare function Slider(
 	$slots?: Record<string, SlotRender>,
 ): void;
 
-export { Slider };
+
+
+interface SliderHandleProps {
+	/** An ID for the handle element */
+	id?: string;
+	/** Classes for the handle element */
+	class?: ClassValue;
+	/** Styles for the handle element */
+	style?: StyleValue;
+	/** An accessible name for the slider; falls back to the Slider's ariaLabel */
+	ariaLabel?: string;
+	/** If set to true, the user cannot interact with this handle */
+	disabled?: boolean;
+}
+
+/**
+ * The thumb of a Slider that the user drags along the track, or moves with
+ * the keyboard. It carries `role="slider"` and all of the slider's ARIA
+ * value attributes.
+ *
+ * See [the WAI ARIA guidelines for Sliders](https://www.w3.org/WAI/ARIA/apg/patterns/slider/).
+ */
+declare function SliderHandle(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: SliderHandleProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface SliderRangeProps {
+	/** An ID for the range element */
+	id?: string;
+	/** Classes for the range element */
+	class?: ClassValue;
+	/** Styles for the range element */
+	style?: StyleValue;
+}
+
+/**
+ * The filled portion of a Slider, from the start of the track to the
+ * current value.
+ */
+declare function SliderRange(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: SliderRangeProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { Slider, SliderHandle, SliderRange };

package/dist/Slider/index.js

@@ -1,2 +1,4 @@
 import Slider from "./Slider.torp";
-export { Slider };
+import SliderHandle from "./SliderHandle.torp";
+import SliderRange from "./SliderRange.torp";
+export { Slider, SliderHandle, SliderRange };

package/dist/TagInput/TagInput.torp

@@ -10,6 +10,10 @@ import FormValues from "../Form/FormValues.torp";
 import { type Loader, createItemLoader } from "../utils/loader";
 import getId from "../utils/getId";
 import createFormField from "../utils/formField";
+import TagInputField from "./TagInputField.torp";
+import TagInputSuggestions from "./TagInputSuggestions.torp";
+import TagInputTag from "./TagInputTag.torp";
+import { type TagInputContext, TagInputContextName } from "./TagInputTypes";
 
 interface TagInputProps {
 	/** An ID for the root element */
@@ -46,9 +50,21 @@ interface TagInputProps {
  * 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.
+ *
+ * The structure of a TagInput is:
+ *
+ * ```
+ * <TagInput>
+ * 	<TagInputTag />
+ * 	<TagInputField />
+ * 	<TagInputSuggestions />
+ * </TagInput>
+ * ```
+ *
+ * With no children, the tags and suggestions are rendered automatically.
  */
 export default function TagInput($props: TagInputProps | undefined) {
-	let input: HTMLInputElement;
+	let input: HTMLInputElement | undefined;
 	let root: HTMLElement;
 
 	// Wire up the enclosing Form and Field, if any
@@ -116,10 +132,47 @@ export default function TagInput($props: TagInputProps | undefined) {
 		return `${defaultId}-suggestion-${index}`;
 	}
 
+	function listId(): string {
+		return `${defaultId}-suggestions`;
+	}
+
 	function suggestions(): any[] {
 		return $load ? $load.items : [];
 	}
 
+	// Set the context to pass down to the tags and suggestions
+	let context: TagInputContext = {
+		getDisabled,
+		removeTag,
+		getPlaceholder: () => $props?.placeholder,
+		getText: () => $state.text,
+		hasLoader: () => hasLoader,
+		isSuggestionsOpen: () => $state.suggestionsOpen,
+		getActiveSuggestionId: () =>
+			$state.activeSuggestion >= 0 ? suggestionId($state.activeSuggestion) : undefined,
+		handleFieldInput: handleInput,
+		handleFieldKey: handleKey,
+		registerField: (el) => {
+			input = el;
+		},
+		unregisterField: (el) => {
+			if (input === el) {
+				input = undefined;
+			}
+		},
+		getSuggestions: suggestions,
+		getSuggestionLabel: getLabel,
+		getSuggestionId: suggestionId,
+		isActiveSuggestion: (index) => $state.activeSuggestion === index,
+		setActiveSuggestion: (index) => {
+			$state.activeSuggestion = index;
+		},
+		pickSuggestion,
+		getListId: listId,
+		getAriaLabel: () => $props?.ariaLabel,
+	};
+	$context[TagInputContextName] = context;
+
 	// Dispatch the change event when the tags change
 	$handle((first) => {
 		const values = $state.value;
@@ -271,79 +324,16 @@ export default function TagInput($props: TagInputProps | undefined) {
 				}
 			}}
 		>
-			<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>
+			<slot>
+				<ul class="torp-tag-input-tags">
+					@for (let [index, tag] of $state.value.entries()) {
+						@key = index
+						<TagInputTag {index} {tag} />
 					}
-				} catch (err) {
-					<div class="torp-tag-input-error" role="alert">
-						{err instanceof Error ? err.message : String(err)}
-					</div>
-				}
-			}
+				</ul>
+				<TagInputField />
+				<TagInputSuggestions />
+			</slot>
 		</div>
 
 		<FormValues name={form.name} value={$state.value} />
@@ -363,16 +353,5 @@ export default function TagInput($props: TagInputProps | undefined) {
 			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/TagInputField.torp

@@ -0,0 +1,68 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { type TagInputContext, TagInputContextName } from "./TagInputTypes";
+
+interface TagInputFieldProps {
+	/** An ID for the field element */
+	id?: string;
+	/** Classes for the field element */
+	class?: ClassValue;
+	/** Styles for the field element */
+	style?: StyleValue;
+	/** Placeholder text for the empty field; falls back to the TagInput's placeholder */
+	placeholder?: string;
+	/** An accessible name for the field; falls back to the TagInput's ariaLabel */
+	ariaLabel?: string;
+	/** If set to true, the user cannot interact with this field */
+	disabled?: boolean;
+}
+
+/**
+ * The text field of a TagInput, where the user types values (and searches
+ * suggestions when a `load` function is set).
+ */
+export default function TagInputField($props: TagInputFieldProps | undefined) {
+	// Get stuff out of the TagInput context
+	const context = $context[TagInputContextName] as TagInputContext;
+	if (!context) {
+		throw new Error("TagInputField must be contained within a TagInput");
+	}
+
+	function getDisabled(): boolean {
+		return $props?.disabled === true || context.getDisabled();
+	}
+
+	@render {
+		<input
+			{$props?.id}
+			class={["torp-tag-input-field", $props?.class]}
+			{$props?.style}
+			type="text"
+			value={context.getText()}
+			placeholder={$props?.placeholder ?? context.getPlaceholder()}
+			disabled={getDisabled()}
+			aria-label={$props?.ariaLabel ?? context.getAriaLabel()}
+			role={context.hasLoader() ? "combobox" : undefined}
+			aria-expanded={context.hasLoader() ? (context.isSuggestionsOpen() ? "true" : "false") : undefined}
+			aria-controls={context.isSuggestionsOpen() ? context.getListId() : undefined}
+			aria-autocomplete="list"
+			aria-activedescendant={context.getActiveSuggestionId()}
+			oninput={context.handleFieldInput}
+			onkeydown={context.handleFieldKey}
+			onmount={(el) => {
+				context.registerField(el);
+				return () => {
+					context.unregisterField(el);
+				};
+			}}
+		/>
+	}
+
+	@style {
+		/* Headless: layout only, so the field shares the row with the tags.
+		   All appearance is up to the consuming theme */
+		.torp-tag-input-field {
+			flex: 1 1 auto;
+			min-width: 4em;
+		}
+	}
+}

package/dist/TagInput/TagInputSuggestions.torp

@@ -0,0 +1,79 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { type TagInputContext, TagInputContextName } from "./TagInputTypes";
+
+interface TagInputSuggestionsProps {
+	/** An ID for the suggestion list element */
+	id?: string;
+	/** Classes for the suggestion list element */
+	class?: ClassValue;
+	/** Styles for the suggestion list element */
+	style?: StyleValue;
+}
+
+/**
+ * The suggestion list of a TagInput, shown while the user types when a
+ * `load` function is set. Selecting a suggestion adds it as a tag.
+ */
+export default function TagInputSuggestions($props: TagInputSuggestionsProps | undefined) {
+	// Get stuff out of the TagInput context
+	const context = $context[TagInputContextName] as TagInputContext;
+	if (!context) {
+		throw new Error("TagInputSuggestions must be contained within a TagInput");
+	}
+
+	@render {
+		@if (context.isSuggestionsOpen()) {
+			@try {
+				@await {
+					<ul
+						id={$props?.id ?? context.getListId()}
+						class={["torp-tag-input-suggestions", $props?.class]}
+						{$props?.style}
+						role="listbox"
+						aria-label={context.getAriaLabel()}
+					>
+						@for (let [index, item] of context.getSuggestions().entries()) {
+							@key = context.getSuggestionLabel(item)
+							<li
+								class="torp-tag-input-suggestion"
+								role="option"
+								id={context.getSuggestionId(index)}
+								aria-selected={context.isActiveSuggestion(index) ? "true" : "false"}
+								data-active={context.isActiveSuggestion(index) ? "active" : undefined}
+								onmouseenter={() => context.setActiveSuggestion(index)}
+								onmousedown={(e: MouseEvent) => {
+									// mousedown so the field doesn't blur first
+									e.preventDefault();
+									context.pickSuggestion(item);
+								}}
+							>
+								{context.getSuggestionLabel(item)}
+							</li>
+						}
+						@if (context.getSuggestions().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>
+			}
+		}
+	}
+
+	@style {
+		/* Headless: layout only, so the list overlays the page. All appearance
+		   is up to the consuming theme */
+		.torp-tag-input-suggestions {
+			position: absolute;
+			list-style: none;
+			margin: 0;
+			padding: 0;
+			z-index: 10;
+		}
+	}
+}

package/dist/TagInput/TagInputTag.torp

@@ -0,0 +1,55 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { type TagInputContext, TagInputContextName } from "./TagInputTypes";
+
+interface TagInputTagProps {
+	/** An ID for the tag element */
+	id?: string;
+	/** Classes for the tag element */
+	class?: ClassValue;
+	/** Styles for the tag element */
+	style?: StyleValue;
+	/** The tag's position in the list */
+	index: number;
+	/** The tag's text */
+	tag: string;
+	/** If set to true, the tag cannot be removed */
+	disabled?: boolean;
+}
+
+/**
+ * One tag of a TagInput: its text with a button to remove it.
+ */
+export default function TagInputTag($props: TagInputTagProps | undefined) {
+	// Get stuff out of the TagInput context
+	const context = $context[TagInputContextName] as TagInputContext;
+	if (!context) {
+		throw new Error("TagInputTag must be contained within a TagInput");
+	}
+
+	function getIndex(): number {
+		return $props?.index ?? 0;
+	}
+
+	function getTag(): string {
+		return $props?.tag ?? "";
+	}
+
+	function getDisabled(): boolean {
+		return $props?.disabled === true || context.getDisabled();
+	}
+
+	@render {
+		<li {$props?.id} class={["torp-tag-input-tag", $props?.class]} {$props?.style}>
+			<span class="torp-tag-input-tag-text">{getTag()}</span>
+			<button
+				type="button"
+				class="torp-tag-input-remove"
+				aria-label={`Remove ${getTag()}`}
+				disabled={getDisabled()}
+				onclick={() => context.removeTag(getIndex())}
+			>
+				<slot>×</slot>
+			</button>
+		</li>
+	}
+}

package/dist/TagInput/TagInputTypes.ts

@@ -0,0 +1,42 @@
+export const TagInputContextName: unique symbol = Symbol.for("torp.TagInput");
+
+export interface TagInputContext {
+	/** Whether the user cannot interact with the input */
+	getDisabled: () => boolean;
+	/** Removes the tag at an index */
+	removeTag: (index: number) => void;
+	/** Placeholder text for the empty field */
+	getPlaceholder: () => string | undefined;
+	/** The text currently in the field */
+	getText: () => string;
+	/** Whether suggestions are loaded from a `load` function */
+	hasLoader: () => boolean;
+	/** Whether the suggestion list is open */
+	isSuggestionsOpen: () => boolean;
+	/** The ID of the active suggestion, for aria-activedescendant */
+	getActiveSuggestionId: () => string | undefined;
+	/** Handles typing in the field */
+	handleFieldInput: (e: Event) => void;
+	/** Handles keys in the field (arrows, Enter, comma, Backspace, Escape) */
+	handleFieldKey: (e: KeyboardEvent) => void;
+	/** Called from the field when it is added */
+	registerField: (el: HTMLInputElement) => void;
+	/** Called from the field when it is removed */
+	unregisterField: (el: HTMLInputElement) => void;
+	/** The current suggestions; suspends while loading */
+	getSuggestions: () => any[];
+	/** Extracts the display text for a suggestion */
+	getSuggestionLabel: (item: any) => string;
+	/** The ID of a suggestion option, for aria-activedescendant */
+	getSuggestionId: (index: number) => string;
+	/** Whether a suggestion is the active (highlighted) one */
+	isActiveSuggestion: (index: number) => boolean;
+	/** Highlights a suggestion */
+	setActiveSuggestion: (index: number) => void;
+	/** Adds a suggestion as a tag */
+	pickSuggestion: (item: any) => void;
+	/** The ID of the suggestion list, for aria-controls */
+	getListId: () => string;
+	/** An accessible name for the suggestion list */
+	getAriaLabel: () => string | undefined;
+}

package/dist/TagInput/index.d.ts

@@ -36,6 +36,18 @@ interface TagInputProps {
  * 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.
+ *
+ * The structure of a TagInput is:
+ *
+ * ```
+ * <TagInput>
+ * 	<TagInputTag />
+ * 	<TagInputField />
+ * 	<TagInputSuggestions />
+ * </TagInput>
+ * ```
+ *
+ * With no children, the tags and suggestions are rendered automatically.
  */
 declare function TagInput(
 	$parent: ParentNode,
@@ -45,4 +57,84 @@ declare function TagInput(
 	$slots?: Record<string, SlotRender>,
 ): void;
 
-export { TagInput };
+
+
+interface TagInputFieldProps {
+	/** An ID for the field element */
+	id?: string;
+	/** Classes for the field element */
+	class?: ClassValue;
+	/** Styles for the field element */
+	style?: StyleValue;
+	/** Placeholder text for the empty field; falls back to the TagInput's placeholder */
+	placeholder?: string;
+	/** An accessible name for the field; falls back to the TagInput's ariaLabel */
+	ariaLabel?: string;
+	/** If set to true, the user cannot interact with this field */
+	disabled?: boolean;
+}
+
+/**
+ * The text field of a TagInput, where the user types values (and searches
+ * suggestions when a `load` function is set).
+ */
+declare function TagInputField(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: TagInputFieldProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface TagInputSuggestionsProps {
+	/** An ID for the suggestion list element */
+	id?: string;
+	/** Classes for the suggestion list element */
+	class?: ClassValue;
+	/** Styles for the suggestion list element */
+	style?: StyleValue;
+}
+
+/**
+ * The suggestion list of a TagInput, shown while the user types when a
+ * `load` function is set. Selecting a suggestion adds it as a tag.
+ */
+declare function TagInputSuggestions(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: TagInputSuggestionsProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface TagInputTagProps {
+	/** An ID for the tag element */
+	id?: string;
+	/** Classes for the tag element */
+	class?: ClassValue;
+	/** Styles for the tag element */
+	style?: StyleValue;
+	/** The tag's position in the list */
+	index: number;
+	/** The tag's text */
+	tag: string;
+	/** If set to true, the tag cannot be removed */
+	disabled?: boolean;
+}
+
+/**
+ * One tag of a TagInput: its text with a button to remove it.
+ */
+declare function TagInputTag(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: TagInputTagProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { TagInput, TagInputField, TagInputSuggestions, TagInputTag };

package/dist/TagInput/index.js

@@ -1,2 +1,5 @@
 import TagInput from "./TagInput.torp";
-export { TagInput };
+import TagInputField from "./TagInputField.torp";
+import TagInputSuggestions from "./TagInputSuggestions.torp";
+import TagInputTag from "./TagInputTag.torp";
+export { TagInput, TagInputField, TagInputSuggestions, TagInputTag };