@torpor/ui 0.4.0 → 1.0.1

package/dist/ComboBox/ComboBoxInput.torp

@@ -0,0 +1,161 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import getId from "../utils/getId";
+import { type ComboBoxContext, ComboBoxContextName } from "./ComboBoxTypes";
+
+interface ComboBoxInputProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+
+	// TODO: Get these from the parent
+	/** The name of the input's form data field */
+	name?: string;
+	/** The value displayed in the input */
+	value?: any;
+	/** The text to display in the input (e.g. the selected item's label), instead of the raw value */
+	text?: string;
+	/** Text to display when the input value is empty */
+	placeholder?: string;
+	/** Whether the input's value is required */
+	required?: boolean;
+
+	/** An ARIA label for describing the input to screen readers when there is no associated label element */
+	ariaLabel?: string;
+	/** Raised on change */
+	onchange?: (e: Event) => void;
+	/** Raised on input */
+	oninput?: (e: InputEvent) => void;
+}
+
+/**
+ * The input that causes a ComboBox to appear or disappear.
+ */
+export default function ComboBoxInput($props: ComboBoxInputProps | undefined) {
+	let defaultId = getId();
+	let input: HTMLInputElement;
+
+	// Get stuff out of the ComboBoxContext
+	const context = $context[ComboBoxContextName] as ComboBoxContext;
+	if (!context) {
+		throw new Error("ComboBoxInput must be contained within a ComboBox");
+	}
+	let $state = context.state;
+	context.focusInput = focusInput;
+
+	// Set the trigger ID so that it can be used with aria-labelledby
+	$state.triggerId = $props?.id ?? defaultId;
+
+	function focusInput() {
+		input.focus();
+	}
+
+	// The text shown in the input: the consumer-supplied label for the
+	// selected value if given, otherwise the raw value itself. One-way: what
+	// the user types is search text, not the value (that's updated on select)
+	function displayValue(): string {
+		if ($props?.text !== undefined) {
+			return $props.text;
+		}
+		const value = $state.value;
+		if (value === undefined || value === null || value === "") {
+			return "";
+		}
+		return Array.isArray(value) ? value.join(", ") : String(value);
+	}
+
+	function handleClick() {
+		$state.visible = true;
+	}
+
+	function handleInput(e: InputEvent) {
+		if (context.getLoadedItems) {
+			// Loaded from a network loader: refetch with the current text
+			$state.searchText = input.value;
+			$state.visible = true;
+		} else if (context.searchItems) {
+			context.searchText = input.value;
+			const found = context.searchItems(context.searchText);
+			if (found !== undefined) {
+				$state.visible = true;
+				$state.activeDescendant = found.id;
+				if (context.markElement) {
+					context.markElement(found.id);
+				}
+			}
+		}
+
+		if ($props?.oninput) {
+			$props.oninput(e);
+		}
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		switch (e.key) {
+			case "ArrowDown": {
+				e.preventDefault();
+				$state.visible = true;
+				if (context.focusFirstElement) {
+					context.focusFirstElement();
+				}
+				break;
+			}
+			case "ArrowUp": {
+				e.preventDefault();
+				$state.visible = true;
+				if (context.focusLastElement) {
+					context.focusLastElement();
+				}
+				break;
+			}
+			case "Enter": {
+				if ($state.visible) {
+					e.preventDefault();
+					if (context.selectMarkedElement) {
+						context.selectMarkedElement();
+					}
+					$state.visible = false;
+				}
+				break;
+			}
+			case "Escape": {
+				if ($state.visible) {
+					e.preventDefault();
+					$state.visible = false;
+				}
+				break;
+			}
+		}
+	}
+
+	@render {
+		<input
+			role="combobox"
+			aria-autocomplete="list"
+			id={$props?.id ?? defaultId}
+			class={["torp-combo-box-input", $props?.class]}
+			{$props?.style}
+			name={$props?.name !== undefined ? $props.name : context.name}
+			value={displayValue()}
+			placeholder={$props?.placeholder !== undefined ? $props.placeholder : context.placeholder}
+			required={$props?.required !== undefined ? $props.required : context.required}
+			aria-readonly
+			aria-controls={$state.contentId}
+			aria-haspopup={$state.contentRole}
+			aria-activedescendant={$state.activeDescendant}
+			aria-expanded={$state.visible ? "true" : "false"}
+			aria-label={$props?.ariaLabel !== undefined ? $props.ariaLabel : context.ariaLabel}
+			data-valid={context.valid?.() ? "valid" : "invalid"}
+			aria-describedby={context.messageId?.()}
+			aria-invalid={context.inField?.() && !context.valid?.() ? "true" : undefined}
+			onblur={() => context.handleBlur?.()}
+			{$props?.onchange}
+			onclick={handleClick}
+			oninput={handleInput}
+			onkeydown={handleKey}
+			&ref={input}
+		/>
+	}
+}

package/dist/ComboBox/ComboBoxTrigger.torp

@@ -0,0 +1,49 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import getId from "../utils/getId";
+import { type ComboBoxContext, ComboBoxContextName } from "./ComboBoxTypes";
+
+interface ComboBoxTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+}
+
+/**
+ * The button that causes a ComboBox to appear or disappear.
+ */
+export default function ComboBoxTrigger($props: ComboBoxTriggerProps | undefined) {
+	let defaultId = getId();
+
+	// Get stuff out of the ComboBoxContext
+	const context = $context[ComboBoxContextName] as ComboBoxContext;
+	if (!context) {
+		throw new Error("ComboBoxTrigger must be contained within a ComboBox");
+	}
+	let $state = context.state;
+
+	// Set the trigger ID so that it can be used with aria-labelledby
+	$state.triggerId = $props?.id ?? defaultId;
+
+	function handleClick() {
+		$state.visible = !$state.visible;
+	}
+
+	@render {
+		<button
+			type="button"
+			id={$props?.id ?? defaultId}
+			class={["torp-combo-box-trigger", $props?.class]}
+			{$props?.style}
+			aria-haspopup={$state.contentRole}
+			aria-expanded={$state.visible ? "true" : "false"}
+			aria-controls={$state.contentId}
+			onclick={handleClick}
+			&ref={context.anchorElement}
+		>
+			<slot />
+		</button>
+	}
+}

package/dist/ComboBox/ComboBoxTypes.ts

@@ -0,0 +1,39 @@
+import { type LoadResult, type Loader } from "../utils/loader";
+import { type PopoutContext, type PopoutState } from "../utils/PopoutTypes";
+
+export const ComboBoxContextName: unique symbol = Symbol.for("torp.ComboBox");
+
+/** The shared context for ComboBox components */
+export interface ComboBoxContext extends PopoutContext {
+	placeholder?: string;
+	required?: boolean;
+	ariaLabel?: string;
+	name?: string;
+	multiple?: boolean;
+	state: ComboBoxState;
+	focusInput?: () => void;
+	/** Whether the component is contained within a Form Field */
+	inField?: () => boolean;
+	/** Whether the Field's value is valid, for data-valid / aria-invalid */
+	valid?: () => boolean;
+	/** The ID of the Field's Message component, for aria-describedby */
+	messageId?: () => string | undefined;
+	/** Called by the input when it loses focus, to run Field validation */
+	handleBlur?: () => void;
+	/** Returns the items loaded from the network loader, when one is set */
+	getLoadedItems?: () => any[];
+	/** Extracts the display text for a loaded item */
+	getItemLabel?: (item: any) => any;
+	/** Extracts the value for a loaded item */
+	getItemValue?: (item: any) => any;
+}
+
+export interface ComboBoxState extends PopoutState {
+	value: any;
+	name?: string;
+	activeDescendant?: string;
+	/** The current search text, kept up to date by the input when loading */
+	searchText?: string;
+}
+
+export type { LoadResult, Loader };

package/dist/ComboBox/index.d.ts

@@ -0,0 +1,154 @@
+import { type SlotRender } from "@torpor/view";
+
+
+interface ComboBoxProps {
+	/** 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 data value selected by the user, or an array of values if multiple is set */
+	value: Bindable<any>;
+	/** Whether multiple values can be selected at the same time */
+	multiple?: boolean;
+	/**
+	 * Reads options from the network (or anywhere async) as the user types,
+	 * receiving `{ searchText }`. When set and no content is slotted in, the
+	 * options are rendered automatically.
+	 */
+	load?: Loader;
+	/** Called after each successful load with the normalized result */
+	onload?: (result: LoadResult) => void;
+	/** Extracts the display text for a loaded item (defaults to `label ?? text ?? item`) */
+	getItemLabel?: (item: any) => any;
+	/** Extracts the value for a loaded item (defaults to `value ?? id`) */
+	getItemValue?: (item: any) => any;
+	/** Text to display when the input value is empty */
+	placeholder?: string;
+	/** Whether the input's value is required */
+	required?: boolean;
+	/** An ARIA label for describing the input to screen readers when there is no associated label element */
+	ariaLabel?: string;
+	/** Whether the popout is visible; only bind this to control it from outside */
+	visible?: Bindable<boolean | undefined>;
+	/** Raised when the value has changed */
+	onchange?: (value: any) => void;
+	/** Raised when the popout has opened */
+	onopen?: () => void;
+	/** Raised when the popout has closed */
+	onclose?: (result: any) => void;
+}
+
+/**
+ * An input box for selecting a value from a popout ListBox or Dialog.
+ *
+ * See [the WAI ARIA guidelines for ComboBoxes](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
+ *
+ * The structure of a ComboBox is:
+ *
+ * ```
+ * <ComboBox>
+ * 	<ComboBoxInput />
+ * 	<ComboBoxTrigger /> (optional)
+ * 	<ComboBoxContent />
+ * </ComboBox>
+ * ```
+ */
+declare function ComboBox(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: ComboBoxProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface ComboBoxContentProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+}
+
+/**
+ * The content that is displayed for a ComboBox when it is open, displayed
+ * alongside an element.
+ */
+declare function ComboBoxContent(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: ComboBoxContentProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface ComboBoxInputProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+
+	// TODO: Get these from the parent
+	/** The name of the input's form data field */
+	name?: string;
+	/** The value displayed in the input */
+	value?: any;
+	/** The text to display in the input (e.g. the selected item's label), instead of the raw value */
+	text?: string;
+	/** Text to display when the input value is empty */
+	placeholder?: string;
+	/** Whether the input's value is required */
+	required?: boolean;
+
+	/** An ARIA label for describing the input to screen readers when there is no associated label element */
+	ariaLabel?: string;
+	/** Raised on change */
+	onchange?: (e: Event) => void;
+	/** Raised on input */
+	oninput?: (e: InputEvent) => void;
+}
+
+/**
+ * The input that causes a ComboBox to appear or disappear.
+ */
+declare function ComboBoxInput(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: ComboBoxInputProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface ComboBoxTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+}
+
+/**
+ * The button that causes a ComboBox to appear or disappear.
+ */
+declare function ComboBoxTrigger(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: ComboBoxTriggerProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { ComboBox, ComboBoxContent, ComboBoxInput, ComboBoxTrigger };

package/dist/ComboBox/index.js

@@ -0,0 +1,6 @@
+import { n as normalizeLoadResult, t as createItemLoader } from "../loader-DEeG5vFY.js";
+import ComboBox from "./ComboBox.torp";
+import ComboBoxContent from "./ComboBoxContent.torp";
+import ComboBoxInput from "./ComboBoxInput.torp";
+import ComboBoxTrigger from "./ComboBoxTrigger.torp";
+export { ComboBox, ComboBoxContent, ComboBoxInput, ComboBoxTrigger, createItemLoader, normalizeLoadResult };

package/dist/CommandPalette/CommandPalette.torp

@@ -0,0 +1,223 @@
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import Modal from "../Modal/Modal.torp";
+import ModalContent from "../Modal/ModalContent.torp";
+import ModalOverlay from "../Modal/ModalOverlay.torp";
+import getId from "../utils/getId";
+import type { Command } from "./CommandTypes";
+
+interface CommandPaletteProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** Whether the palette is visible */
+	visible: Bindable<boolean | undefined>;
+	/** The commands that the user can choose from */
+	commands: Command[];
+	/** Text to display in the input when it is empty */
+	placeholder?: string;
+	/**
+	 * A keyboard shortcut that toggles the palette, e.g. "mod+k", where "mod"
+	 * means the Cmd key on Mac and the Ctrl key elsewhere
+	 */
+	hotkey?: string;
+	/** An accessible name for the input */
+	ariaLabel?: string;
+	/** Text to display when no commands match the search */
+	emptyText?: string;
+	/** Raised when a command has been run */
+	onrun?: (command: Command) => void;
+}
+
+/**
+ * A modal input for searching and running commands, opened with a keyboard
+ * shortcut or programmatically.
+ *
+ * The structure of a CommandPalette is a Modal containing a search input and
+ * a filtered list of commands.
+ */
+export default function CommandPalette($props: CommandPaletteProps | undefined) {
+	let defaultId = getId();
+	let input: HTMLInputElement;
+
+	function getDisabled(command: Command): boolean {
+		return command.disabled === true;
+	}
+
+	let $state = $watch({
+		visible: false,
+		search: "",
+		activeIndex: 0,
+	});
+
+	$bind($state, $props, "visible");
+
+	// Reset the active item whenever the search changes or the palette opens
+	let lastSearch = "";
+	let lastVisible = false;
+	$run(() => {
+		const search = $state.search;
+		const visible = $state.visible;
+		if (search !== lastSearch || (visible && !lastVisible)) {
+			$state.activeIndex = 0;
+		}
+		lastSearch = search;
+		lastVisible = visible;
+		if (!visible) {
+			$state.search = "";
+			if (input) {
+				input.value = "";
+			}
+		} else {
+			// Focus the input once the modal content has rendered
+			setTimeout(() => input?.focus());
+		}
+	});
+
+	// The commands that match the current search text
+	function filteredCommands(): Command[] {
+		const search = $state.search.trim().toLowerCase();
+		if (search === "") return $props?.commands ?? [];
+		return ($props?.commands ?? []).filter(
+			(command) =>
+				command.label.toLowerCase().includes(search) ||
+				(command.keywords ?? "").toLowerCase().includes(search),
+		);
+	}
+
+	function activeCommand(): Command | undefined {
+		return filteredCommands()[$state.activeIndex];
+	}
+
+	function optionId(index: number): string {
+		return `${$props?.id ?? defaultId}-option-${index}`;
+	}
+
+	function runCommand(command: Command | undefined) {
+		if (!command || getDisabled(command)) return;
+		$state.visible = false;
+		command.run?.();
+		$props?.onrun?.(command);
+	}
+
+	function handleInput(e: Event) {
+		$state.search = (e.currentTarget as HTMLInputElement).value;
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		switch (e.key) {
+			case "ArrowDown": {
+				e.preventDefault();
+				const count = filteredCommands().length;
+				$state.activeIndex = Math.min(count - 1, $state.activeIndex + 1);
+				break;
+			}
+			case "ArrowUp": {
+				e.preventDefault();
+				$state.activeIndex = Math.max(0, $state.activeIndex - 1);
+				break;
+			}
+			case "Enter": {
+				e.preventDefault();
+				runCommand(activeCommand());
+				break;
+			}
+			case "Escape": {
+				e.preventDefault();
+				$state.visible = false;
+				break;
+			}
+		}
+	}
+
+	// Toggle the palette with a keyboard shortcut, e.g. mod+k
+	$onmount(() => {
+		if (!$props?.hotkey) return;
+		const [modifier, key] = parseHotkey($props.hotkey);
+		if (!key) return;
+		const handler = (e: KeyboardEvent) => {
+			const modOk =
+				modifier === "mod" ? e.metaKey || e.ctrlKey : modifier === "shift" ? e.shiftKey : true;
+			if (modOk && e.key.toLowerCase() === key.toLowerCase()) {
+				e.preventDefault();
+				$state.visible = !$state.visible;
+			}
+		};
+		document.addEventListener("keydown", handler);
+		return () => document.removeEventListener("keydown", handler);
+	});
+
+	function parseHotkey(hotkey: string): [string | undefined, string | undefined] {
+		const parts = hotkey.split("+");
+		if (parts.length === 2) {
+			return [parts[0].toLowerCase(), parts[1]];
+		}
+		return [undefined, hotkey];
+	}
+
+	@render {
+		<div {$props?.id} class={["torp-command-palette", $props?.class]} {$props?.style}>
+			<Modal {$state.visible}>
+				<ModalOverlay />
+				<ModalContent class="torp-command-palette-content">
+					<input
+						class="torp-command-palette-input"
+						type="text"
+						role="combobox"
+						aria-expanded="true"
+						aria-controls={`${$props?.id ?? defaultId}-list`}
+						aria-activedescendant={optionId($state.activeIndex)}
+						aria-autocomplete="list"
+						aria-label={$props?.ariaLabel}
+						placeholder={$props?.placeholder}
+						&ref={input}
+						oninput={handleInput}
+						onkeydown={handleKey}
+					/>
+					<ul class="torp-command-palette-list" role="listbox" id={`${$props?.id ?? defaultId}-list`}>
+						@for (let [index, command] of filteredCommands().entries()) {
+							@key = command.value
+							<li
+								class="torp-command-palette-item"
+								role="option"
+								id={optionId(index)}
+								aria-selected={$state.activeIndex === index ? "true" : "false"}
+								aria-disabled={getDisabled(command) ? "true" : undefined}
+								data-state={$state.activeIndex === index ? "active" : "inactive"}
+								onclick={() => runCommand(command)}
+							>
+								<span class="torp-command-palette-label">{command.label}</span>
+								@if (command.shortcut) {
+									<span class="torp-command-palette-shortcut" aria-hidden="true">
+										{command.shortcut}
+									</span>
+								}
+							</li>
+						}
+						@if (filteredCommands().length === 0) {
+							<li class="torp-command-palette-empty">
+								{$props?.emptyText ?? "No results"}
+							</li>
+						}
+					</ul>
+				</ModalContent>
+			</Modal>
+		</div>
+	}
+
+	@style {
+		/* Headless: layout only, so the input sits above the list. All
+		   appearance is up to the consuming theme */
+		.torp-command-palette-content {
+			display: flex;
+			flex-direction: column;
+		}
+		.torp-command-palette-list {
+			list-style: none;
+			margin: 0;
+			padding: 0;
+		}
+	}
+}

package/dist/CommandPalette/CommandTypes.ts

@@ -0,0 +1,14 @@
+export interface Command {
+	/** A value identifying the command */
+	value: any;
+	/** The display label for the command */
+	label: string;
+	/** Extra text that is matched when searching, but isn't displayed */
+	keywords?: string;
+	/** A keyboard shortcut hint to display, e.g. "⌘N" */
+	shortcut?: string;
+	/** If set to true, the command can't be run */
+	disabled?: boolean;
+	/** The function to call when the command is run */
+	run?: () => void;
+}

package/dist/CommandPalette/index.d.ts

@@ -0,0 +1,45 @@
+import { type SlotRender } from "@torpor/view";
+
+
+interface CommandPaletteProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** Whether the palette is visible */
+	visible: Bindable<boolean | undefined>;
+	/** The commands that the user can choose from */
+	commands: Command[];
+	/** Text to display in the input when it is empty */
+	placeholder?: string;
+	/**
+	 * A keyboard shortcut that toggles the palette, e.g. "mod+k", where "mod"
+	 * means the Cmd key on Mac and the Ctrl key elsewhere
+	 */
+	hotkey?: string;
+	/** An accessible name for the input */
+	ariaLabel?: string;
+	/** Text to display when no commands match the search */
+	emptyText?: string;
+	/** Raised when a command has been run */
+	onrun?: (command: Command) => void;
+}
+
+/**
+ * A modal input for searching and running commands, opened with a keyboard
+ * shortcut or programmatically.
+ *
+ * The structure of a CommandPalette is a Modal containing a search input and
+ * a filtered list of commands.
+ */
+declare function CommandPalette(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: CommandPaletteProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { CommandPalette };

package/dist/CommandPalette/index.js

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