@torpor/ui 0.3.7 → 1.0.0

package/dist/Slider/Slider.torp

@@ -0,0 +1,248 @@
+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 createFormField from "../utils/formField";
+
+interface SliderProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The minimum allowed value */
+	min?: number;
+	/** The maximum allowed value */
+	max?: number;
+	/** The amount by which the value is increased or decreased */
+	step?: number;
+	/** The current value of the slider */
+	value?: Bindable<number>;
+	/** The orientation of the slider */
+	orientation?: "horizontal" | "vertical";
+	/** If set to true, the user cannot interact with this slider */
+	disabled?: boolean;
+	/** An accessible name for the slider */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when the value has changed */
+	onchange?: (value: number) => void;
+}
+
+/**
+ * An input where the user selects a value from within a given range, by
+ * 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/).
+ */
+export default function Slider($props: SliderProps | undefined) {
+	let track: HTMLElement;
+	let thumb: 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 getMin(): number {
+		return $props?.min ?? 0;
+	}
+	function getMax(): number {
+		return $props?.max ?? 100;
+	}
+	function getStep(): number {
+		const step = $props?.step ?? 1;
+		return step > 0 ? step : 1;
+	}
+	function getOrientation(): "horizontal" | "vertical" {
+		return $props?.orientation === "vertical" ? "vertical" : "horizontal";
+	}
+	function getDisabled(): boolean {
+		return $props?.disabled === true;
+	}
+
+	let $state = $watch({
+		value: 0,
+	});
+
+	$bind($state, $props, "value");
+
+	// Dispatch the change event when the value changes
+	$handle((first) => {
+		const value = $state.value;
+		if (!first) $props?.onchange?.(value);
+	});
+
+	function clamp(value: number): number {
+		return Math.min(getMax(), Math.max(getMin(), value));
+	}
+
+	// Snap a raw position-derived value to the nearest step multiple
+	function snap(value: number): number {
+		const min = getMin();
+		const snapped = min + Math.round((value - min) / getStep()) * getStep();
+		return snapped === -0 ? 0 : snapped;
+	}
+
+	// The clamped value that is displayed and reported to assistive tech
+	function getValue(): number {
+		return clamp($state.value);
+	}
+
+	// The percentage of the range that the value represents (0..100)
+	function getPct(): number {
+		const min = getMin();
+		const max = getMax();
+		if (max <= min) return 0;
+		return ((getValue() - min) / (max - min)) * 100;
+	}
+
+	function setValue(value: number) {
+		const next = clamp(snap(value));
+		if (next !== $state.value) {
+			$state.value = next;
+			form.handleInput();
+			return true;
+		}
+		return false;
+	}
+
+	// Convert a pointer position into a value along the track
+	function valueFromPointer(e: { clientX: number; clientY: number }): number {
+		const rect = track.getBoundingClientRect();
+		const horizontal = getOrientation() === "horizontal";
+		const pos = horizontal ? e.clientX - rect.left : e.clientY - rect.top;
+		const size = horizontal ? rect.width : rect.height;
+		if (!(size > 0)) {
+			return getValue();
+		}
+		const ratio = Math.min(1, Math.max(0, pos / size));
+		return getMin() + ratio * (getMax() - getMin());
+	}
+
+	let dragging = false;
+
+	function removeDragListeners() {
+		removeEventListener("mousemove", handleMouseMove);
+		removeEventListener("mouseup", handleMouseUp);
+	}
+
+	function handleMouseDown(e: MouseEvent) {
+		if (getDisabled()) return;
+		e.preventDefault();
+		dragging = true;
+		setValue(valueFromPointer(e));
+		thumb.focus();
+		addEventListener("mousemove", handleMouseMove);
+		addEventListener("mouseup", handleMouseUp);
+	}
+
+	function handleMouseMove(e: MouseEvent) {
+		if (!dragging || getDisabled()) return;
+		setValue(valueFromPointer(e));
+	}
+
+	function handleMouseUp() {
+		if (!dragging) return;
+		dragging = false;
+		removeDragListeners();
+	}
+
+	// Stop listening if the slider is unmounted mid-drag
+	$onmount(() => {
+		return () => removeDragListeners();
+	});
+
+	function handleKey(e: KeyboardEvent) {
+		if (getDisabled()) return;
+
+		switch (e.key) {
+			case "ArrowRight":
+			case "ArrowUp": {
+				e.preventDefault();
+				setValue($state.value + getStep());
+				break;
+			}
+			case "ArrowLeft":
+			case "ArrowDown": {
+				e.preventDefault();
+				setValue($state.value - getStep());
+				break;
+			}
+			case "PageUp": {
+				e.preventDefault();
+				setValue($state.value + getStep() * 10);
+				break;
+			}
+			case "PageDown": {
+				e.preventDefault();
+				setValue($state.value - getStep() * 10);
+				break;
+			}
+			case "Home": {
+				e.preventDefault();
+				setValue(getMin());
+				break;
+			}
+			case "End": {
+				e.preventDefault();
+				setValue(getMax());
+				break;
+			}
+		}
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-slider", getDisabled() ? "torp-slider-disabled" : undefined, $props?.class]}
+			{$props?.style}
+			onmousedown={handleMouseDown}
+			&ref={track}
+		>
+			<div class="torp-slider-fill" style={`${getOrientation() === "vertical" ? "height" : "width"}: ${getPct()}%;`} />
+			<div
+				class="torp-slider-thumb"
+				style={`${getOrientation() === "vertical" ? "top" : "left"}: ${getPct()}%;`}
+				role="slider"
+				tabindex={getDisabled() ? -1 : 0}
+				aria-orientation={getOrientation()}
+				aria-valuemin={getMin()}
+				aria-valuemax={getMax()}
+				aria-valuenow={getValue()}
+				aria-label={$props?.ariaLabel}
+				aria-disabled={getDisabled() ? "true" : undefined}
+				data-valid={form.valid ? "valid" : "invalid"}
+				aria-describedby={form.messageId}
+				aria-invalid={form.inField && !form.valid ? "true" : undefined}
+				onblur={form.handleBlur}
+				onkeydown={handleKey}
+				&ref={thumb}
+			/>
+		</div>
+
+		<FormValues name={form.name} value={getValue()} />
+	}
+
+	@style {
+		/* Headless: positioning only, so the thumb sits at the value along
+		   the track. All appearance is up to the consuming theme */
+		.torp-slider {
+			position: relative;
+			touch-action: none;
+		}
+		.torp-slider-thumb {
+			position: absolute;
+			transform: translateX(-50%);
+		}
+	}
+}

package/dist/Slider/index.d.ts

@@ -0,0 +1,45 @@
+import { type SlotRender } from "@torpor/view";
+
+
+interface SliderProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The minimum allowed value */
+	min?: number;
+	/** The maximum allowed value */
+	max?: number;
+	/** The amount by which the value is increased or decreased */
+	step?: number;
+	/** The current value of the slider */
+	value?: Bindable<number>;
+	/** The orientation of the slider */
+	orientation?: "horizontal" | "vertical";
+	/** If set to true, the user cannot interact with this slider */
+	disabled?: boolean;
+	/** An accessible name for the slider */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when the value has changed */
+	onchange?: (value: number) => void;
+}
+
+/**
+ * An input where the user selects a value from within a given range, by
+ * 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/).
+ */
+declare function Slider(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: SliderProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { Slider };

package/dist/Slider/index.js

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

package/dist/Splitter/Splitter.torp

@@ -0,0 +1,156 @@
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import $handle from "../utils/$handle";
+import { type SplitterContext, SplitterContextName } from "./SplitterTypes";
+
+interface SplitterProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The orientation of the splitter (default horizontal) */
+	orientation?: "horizontal" | "vertical";
+	/** The percentage of the container taken up by the primary (first) pane */
+	value?: Bindable<number>;
+	/** The minimum percentage for the primary pane (default 0) */
+	min?: number;
+	/** The maximum percentage for the primary pane (default 100) */
+	max?: number;
+	/** The percentage by which keyboard interaction changes the value (default 1) */
+	step?: number;
+	/** If set to true, the user cannot interact with this splitter */
+	disabled?: boolean;
+	/** Raised when the value has changed */
+	onchange?: (value: number) => void;
+}
+
+/**
+ * Two resizable panes with a separator between them, which the user can drag
+ * or move with the keyboard to resize the panes.
+ *
+ * See [the WAI ARIA guidelines for Window Splitters](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/).
+ *
+ * The structure of a Splitter is:
+ *
+ * ```
+ * <Splitter>
+ * 	<SplitterPane>...</SplitterPane>
+ * 	<SplitterHandle ariaLabel="Resize" />
+ * 	<SplitterPane>...</SplitterPane>
+ * </Splitter>
+ * ```
+ */
+export default function Splitter($props: SplitterProps | undefined) {
+	let container: HTMLElement;
+
+	let $state = $watch({
+		value: 50,
+		panes: [] as SplitterPaneStateLite[],
+	});
+
+	interface SplitterPaneStateLite {
+		index: number;
+	}
+
+	$bind($state, $props, "value");
+
+	// Keep the stored value clamped, so that out-of-range initial values or
+	// min/max changes don't later surface as user changes
+	$run(() => {
+		const clamped = getValue();
+		if (clamped !== $state.value) {
+			$state.value = clamped;
+		}
+	});
+
+	// Set the context to pass down to panes and handles
+	const context: SplitterContext = {
+		registerPane,
+		removePane,
+		getOrientation,
+		getValue,
+		getMin,
+		getMax,
+		getStep,
+		getDisabled,
+		setValue,
+		count: () => $state.panes.length,
+		getContainer: () => container,
+	};
+	$context[SplitterContextName] = context;
+
+	// Dispatch the change event when the value changes
+	$handle((first) => {
+		const value = getValue();
+		if (!first) $props?.onchange?.(value);
+	});
+
+	function getOrientation(): "horizontal" | "vertical" {
+		return $props?.orientation === "vertical" ? "vertical" : "horizontal";
+	}
+
+	function getMin(): number {
+		return clampPercent($props?.min ?? 0);
+	}
+
+	function getMax(): number {
+		return clampPercent($props?.max ?? 100);
+	}
+
+	function clampPercent(value: number): number {
+		return Math.min(100, Math.max(0, value));
+	}
+
+	function getStep(): number {
+		const step = $props?.step ?? 1;
+		return step > 0 ? step : 1;
+	}
+
+	function getDisabled(): boolean {
+		return $props?.disabled === true;
+	}
+
+	// The clamped value that is applied to the primary pane
+	function getValue(): number {
+		return Math.min(getMax(), Math.max(getMin(), $state.value));
+	}
+
+	function setValue(value: number) {
+		$state.value = Math.min(getMax(), Math.max(getMin(), value));
+	}
+
+	function registerPane(): SplitterPaneStateLite {
+		const state: SplitterPaneStateLite = $watch({ index: $state.panes.length });
+		$state.panes.push(state);
+		return state;
+	}
+
+	function removePane(index: number) {
+		if (index >= 0 && index < $state.panes.length) {
+			$state.panes.splice(index, 1);
+		}
+		$state.panes.forEach((pane, i) => (pane.index = i));
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-splitter", $props?.class]}
+			{$props?.style}
+			data-orientation={getOrientation()}
+			style={`flex-direction: ${getOrientation()};`}
+			&ref={container}
+		>
+			<slot />
+		</div>
+	}
+
+	@style {
+		/* Headless: layout only, so the panes split the container. All other
+		   appearance is up to the consuming theme */
+		.torp-splitter {
+			display: flex;
+		}
+	}
+}

package/dist/Splitter/SplitterHandle.torp

@@ -0,0 +1,161 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { type SplitterContext, SplitterContextName } from "./SplitterTypes";
+
+interface SplitterHandleProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** An accessible name for the separator */
+	ariaLabel?: string;
+	/** If set to true, the user cannot interact with this handle */
+	disabled?: boolean;
+}
+
+/**
+ * The separator in a Splitter that a user can drag, or move with the
+ * keyboard, to resize the panes on either side of it.
+ *
+ * See [the WAI ARIA guidelines for Window Splitters](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/).
+ */
+export default function SplitterHandle($props: SplitterHandleProps | undefined) {
+	// Get stuff out of the Splitter context
+	const context = $context[SplitterContextName] as SplitterContext;
+	if (!context) {
+		throw new Error("SplitterHandle must be contained within a Splitter");
+	}
+
+	function getDisabled(): boolean {
+		return $props?.disabled === true || context.getDisabled();
+	}
+
+	let dragging = false;
+
+	function removeDragListeners() {
+		removeEventListener("mousemove", handleMouseMove);
+		removeEventListener("mouseup", handleMouseUp);
+	}
+
+	// Convert a pointer position into a percentage of the container
+	function valueFromPointer(e: { clientX: number; clientY: number }): number {
+		const container = context.getContainer();
+		if (!container) return context.getValue();
+		const rect = container.getBoundingClientRect();
+		const horizontal = context.getOrientation() === "horizontal";
+		const pos = horizontal ? e.clientX - rect.left : e.clientY - rect.top;
+		const size = horizontal ? rect.width : rect.height;
+		if (!(size > 0)) return context.getValue();
+		const ratio = Math.min(1, Math.max(0, pos / size));
+		return ratio * 100;
+	}
+
+	function handleMouseDown(e: MouseEvent) {
+		if (getDisabled()) return;
+		e.preventDefault();
+		dragging = true;
+		context.setValue(valueFromPointer(e));
+		addEventListener("mousemove", handleMouseMove);
+		addEventListener("mouseup", handleMouseUp);
+	}
+
+	function handleMouseMove(e: MouseEvent) {
+		if (!dragging || getDisabled()) return;
+		context.setValue(valueFromPointer(e));
+	}
+
+	function handleMouseUp() {
+		if (!dragging) return;
+		dragging = false;
+		removeDragListeners();
+	}
+
+	// Stop listening if the handle is unmounted mid-drag
+	$onmount(() => {
+		return () => removeDragListeners();
+	});
+
+	function handleKey(e: KeyboardEvent) {
+		if (getDisabled()) return;
+		const step = context.getStep();
+		const vertical = context.getOrientation() === "vertical";
+
+		switch (e.key) {
+			case "ArrowRight": {
+				if (!vertical) {
+					e.preventDefault();
+					context.setValue(context.getValue() + step);
+				}
+				break;
+			}
+			case "ArrowLeft": {
+				if (!vertical) {
+					e.preventDefault();
+					context.setValue(context.getValue() - step);
+				}
+				break;
+			}
+			case "ArrowUp": {
+				if (vertical) {
+					e.preventDefault();
+					context.setValue(context.getValue() + step);
+				}
+				break;
+			}
+			case "ArrowDown": {
+				if (vertical) {
+					e.preventDefault();
+					context.setValue(context.getValue() - step);
+				}
+				break;
+			}
+			case "PageUp": {
+				e.preventDefault();
+				context.setValue(context.getValue() + step * 10);
+				break;
+			}
+			case "PageDown": {
+				e.preventDefault();
+				context.setValue(context.getValue() - step * 10);
+				break;
+			}
+			case "Home": {
+				e.preventDefault();
+				context.setValue(context.getMin());
+				break;
+			}
+			case "End": {
+				e.preventDefault();
+				context.setValue(context.getMax());
+				break;
+			}
+		}
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-splitter-handle", $props?.class]}
+			{$props?.style}
+			role="separator"
+			tabindex={getDisabled() ? -1 : 0}
+			aria-label={$props?.ariaLabel ?? "Resize"}
+			aria-orientation={context.getOrientation()}
+			aria-valuemin={Math.round(context.getMin())}
+			aria-valuemax={Math.round(context.getMax())}
+			aria-valuenow={Math.round(context.getValue())}
+			aria-disabled={getDisabled() ? "true" : undefined}
+			onmousedown={handleMouseDown}
+			onkeydown={handleKey}
+		/>
+	}
+
+	@style {
+		/* Headless: behavior only, so the handle can be dragged on touch
+		   devices. All appearance is up to the consuming theme */
+		.torp-splitter-handle {
+			touch-action: none;
+		}
+	}
+}

package/dist/Splitter/SplitterPane.torp

@@ -0,0 +1,63 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { type SplitterContext, SplitterContextName } from "./SplitterTypes";
+
+interface SplitterPaneProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+}
+
+/**
+ * A pane in a Splitter. When there is more than one pane, the first pane is
+ * sized to the splitter's value and the others share what's left.
+ */
+export default function SplitterPane($props: SplitterPaneProps | undefined) {
+	// Get stuff out of the Splitter context
+	const context = $context[SplitterContextName] as SplitterContext;
+	if (!context) {
+		throw new Error("SplitterPane must be contained within a Splitter");
+	}
+
+	// Register this pane with the parent Splitter
+	let $state = context.registerPane();
+
+	$run(() => {
+		return () => {
+			context.removePane($state.index);
+		};
+	});
+
+	// The primary (first) pane is sized to the value when there are other
+	// panes to share the rest of the space with
+	function getFlex(): string {
+		if ($state.index === 0 && context.count() > 1) {
+			return `0 0 ${context.getValue()}%;`;
+		}
+		return "1 1 0;";
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-splitter-pane", $props?.class]}
+			{$props?.style}
+			data-orientation={context.getOrientation()}
+			style={`flex: ${getFlex()}`}
+		>
+			<slot />
+		</div>
+	}
+
+	@style {
+		/* Headless: min sizes only, so the panes can shrink below their
+		   content. All other appearance is up to the consuming theme */
+		.torp-splitter-pane {
+			min-height: 0;
+			min-width: 0;
+			overflow: hidden;
+		}
+	}
+}

package/dist/Splitter/SplitterTypes.ts

@@ -0,0 +1,31 @@
+export const SplitterContextName: unique symbol = Symbol.for("torp.Splitter");
+
+export interface SplitterPaneState {
+	/** The index of the pane */
+	index: number;
+}
+
+export interface SplitterContext {
+	/** Called from a pane when it is added */
+	registerPane: () => SplitterPaneState;
+	/** Called from a pane when it is removed */
+	removePane: (index: number) => void;
+	/** The orientation of the splitter */
+	getOrientation: () => "horizontal" | "vertical";
+	/** The clamped percentage of the container taken up by the primary pane */
+	getValue: () => number;
+	/** The minimum percentage for the primary pane */
+	getMin: () => number;
+	/** The maximum percentage for the primary pane */
+	getMax: () => number;
+	/** The amount by which keyboard interaction changes the value */
+	getStep: () => number;
+	/** Whether the user cannot interact with the splitter */
+	getDisabled: () => boolean;
+	/** Sets the value, clamped to the min and max */
+	setValue: (value: number) => void;
+	/** The number of registered panes */
+	count: () => number;
+	/** The splitter's root element, used to convert pointer positions into values */
+	getContainer: () => HTMLElement | undefined;
+}