@torpor/ui 0.4.0 → 1.0.0

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,152 @@
+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;
+	/** 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,220 @@
+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 = "";
+			}
+		}
+	});
+
+	// 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 };

package/dist/Contextual/Contextual.torp

@@ -1,30 +1,32 @@
-import type { ClassValue, StyleValue } from "@torpor/view";
-import { ContextualContextName, type Point, type ContextualContext, type ContextualState } from "./ContextualTypes";
-import { PopoutContextName, type PopoutContext } from "../utils/PopoutTypes";
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import $handle from "../utils/$handle";
+import { type PopoutContext, PopoutContextName } from "../utils/PopoutTypes";
+import {
+	type ContextualContext,
+	ContextualContextName,
+	type ContextualState,
+	type Point,
+} from "./ContextualTypes";
 
 interface ContextualProps {
 	/** 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;
 	/** Whether the contextual is modal. If true, an overlay should be supplied to obscure outside content, and only the context content will be visible to screen readers  */
-	modal?: boolean,
+	modal?: boolean;
 	/** Whether the contextual is visible  */
-	visible?: boolean,
+	visible: Bindable<boolean | undefined>;
 	/** The element to anchor this contextual to, as an alternative to supplying a ContextualTrigger  */
-	anchor?: HTMLElement,
+	anchor?: HTMLElement;
 	/** The position to display this contextual at  */
-	position?: Point,
-	/** A function to be called when the user selects a response */
-	callback?: ((value: any) => void),
-	/** Raised when this contextual is opened or closed */
-	ontoggle?: (open: boolean) => void,
+	position?: Point;
 	/** Raised when the contextual has opened */
-	onopen?: () => void,
+	onopen?: () => void;
 	/** Raised when the contextual has closed */
-	onclose?: (result: any) => void,
+	onclose?: (result: any) => void;
 }
 
 /**
@@ -42,19 +44,16 @@ interface ContextualProps {
 export default function Contextual($props: ContextualProps | undefined) {
 	let $state: ContextualState = $watch({
 		visible: false,
-		position: { x: 0, y: 0 }
-	})
+		position: { x: 0, y: 0 },
+		contentId: undefined,
+		triggerId: undefined,
+		contentRole: undefined,
+	});
 
-	// Sync props and state
+	$bind($state, $props, "visible");
 	$run(() => {
-		$state.visible = $props?.visible ?? false;
 		$state.position = $props?.position ?? { x: 0, y: 0 };
 	});
-	$run(() => {
-		if ($props !== undefined) {
-			$props.visible = $state.visible;
-		}
-	});
 
 	let result: any;
 
@@ -72,22 +71,14 @@ export default function Contextual($props: ContextualProps | undefined) {
 	let popoutContext: PopoutContext = context;
 	$context[PopoutContextName] = popoutContext;
 
-	// Dispatch the toggle event when the contextual is opened or closed
-	let firstToggle = true;
-	$run(() => {
-		const ontoggle = $props?.ontoggle;
-		const onopen = $props?.onopen;
-		const onclose = $props?.onclose;
+	// Dispatch the open/close events when the contextual is opened or closed
+	$handle((first) => {
 		const visible = $state.visible;
-		if (firstToggle) {
-			firstToggle = false;
+		if (first) return;
+		if (visible) {
+			$props?.onopen?.();
 		} else {
-			if (ontoggle) ontoggle(visible);
-			if (visible) {
-				if (onopen) onopen()
-			} else {
-				if (onclose) onclose(result);
-			}
+			$props?.onclose?.(result);
 		}
 	});
 
@@ -110,25 +101,16 @@ export default function Contextual($props: ContextualProps | undefined) {
 
 		// Hide the contextual
 		$state.visible = false;
-
-		// Call the callback
-		if ($props?.callback) {
-			$props.callback(result);
-		}
 	}
 
-	function handleClickOutside(e: MouseEvent) {
+	function handleClickOutside(e: MouseEvent | KeyboardEvent) {
 		e.preventDefault();
 		$state.visible = false;
 	}
 
 	@render {
-		<div
-			{$props?.id}
-			class={["torp-context", $props?.class]}
-			{$props?.style}
-		>
+		<div {$props?.id} class={["torp-context", $props?.class]} {$props?.style}>
 			<slot />
 		</div>
 	}
-}
+}