@torpor/ui 0.4.0 → 1.0.0

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;
+}

package/dist/Splitter/index.d.ts

@@ -0,0 +1,103 @@
+import { type SlotRender } from "@torpor/view";
+
+
+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>
+ * ```
+ */
+declare function Splitter(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: SplitterProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+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/).
+ */
+declare function SplitterHandle(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: SplitterHandleProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+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.
+ */
+declare function SplitterPane(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: SplitterPaneProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { Splitter, SplitterHandle, SplitterPane };

package/dist/Splitter/index.js

@@ -0,0 +1,4 @@
+import Splitter from "./Splitter.torp";
+import SplitterHandle from "./SplitterHandle.torp";
+import SplitterPane from "./SplitterPane.torp";
+export { Splitter, SplitterHandle, SplitterPane };

package/dist/Stepper/Stepper.torp

@@ -0,0 +1,146 @@
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import $handle from "../utils/$handle";
+import { type StepperContext, StepperContextName } from "./StepperTypes";
+
+interface StepperProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The index of the current step */
+	value?: Bindable<number>;
+	/** Whether steps can only be visited in order, with completed ones revisitable (default true) */
+	linear?: boolean;
+	/** An accessible label for the steps */
+	ariaLabel?: string;
+	/** Raised when the current step has changed */
+	onchange?: (index: number) => void;
+	/** Raised when the user moves next from the last step */
+	oncomplete?: () => void;
+}
+
+/**
+ * A sequence of steps in a task, showing progress through them. Steps before
+ * the current one are complete, and can be revisited; the user moves between
+ * steps with the navigation controls.
+ *
+ * The structure of a Stepper is:
+ *
+ * ```
+ * <Stepper ariaLabel="Sign up">
+ * 	<StepperStep label="Account" />
+ * 	<StepperStep label="Profile" />
+ * 	<fill name="nav">
+ * 		<StepperPrevious />
+ * 		<StepperNext />
+ * 	</fill>
+ * </Stepper>
+ * ```
+ */
+export default function Stepper($props: StepperProps | undefined) {
+	let $state = $watch({
+		value: 0,
+		steps: [] as StepperStepStateLite[],
+	});
+
+	interface StepperStepStateLite {
+		index: number;
+	}
+
+	$bind($state, $props, "value");
+
+	// Set the context to pass down to steps and navigation controls
+	const context: StepperContext = {
+		registerStep,
+		removeStep,
+		getValue,
+		setValue,
+		next,
+		previous,
+		canNext,
+		canPrevious,
+		steps: () => $state.steps,
+		count: () => $state.steps.length,
+		linear: $props?.linear !== false,
+	};
+	$context[StepperContextName] = context;
+
+	// Dispatch the change event when the current step changes
+	$handle((first) => {
+		const value = getValue();
+		if (!first) $props?.onchange?.(value);
+	});
+
+	// The clamped index of the current step
+	function getValue(): number {
+		const last = Math.max(0, $state.steps.length - 1);
+		return Math.min(last, Math.max(0, $state.value));
+	}
+
+	function canNext(): boolean {
+		return getValue() < $state.steps.length - 1;
+	}
+
+	function canPrevious(): boolean {
+		return getValue() > 0;
+	}
+
+	function setValue(index: number) {
+		const last = Math.max(0, $state.steps.length - 1);
+		$state.value = Math.min(last, Math.max(0, index));
+	}
+
+	function next() {
+		if (canNext()) {
+			setValue(getValue() + 1);
+		} else {
+			$props?.oncomplete?.();
+		}
+	}
+
+	function previous() {
+		if (canPrevious()) {
+			setValue(getValue() - 1);
+		}
+	}
+
+	function registerStep(): StepperStepStateLite {
+		const state: StepperStepStateLite = $watch({ index: $state.steps.length });
+		$state.steps.push(state);
+		return state;
+	}
+
+	function removeStep(index: number) {
+		if (index >= 0 && index < $state.steps.length) {
+			$state.steps.splice(index, 1);
+		}
+		$state.steps.forEach((step, i) => (step.index = i));
+	}
+
+	@render {
+		<div {$props?.id} class={["torp-stepper", $props?.class]} {$props?.style}>
+			<ol class="torp-stepper-steps" aria-label={$props?.ariaLabel}>
+				<slot />
+			</ol>
+			<div class="torp-stepper-nav">
+				<slot name="nav" />
+			</div>
+		</div>
+	}
+
+	@style {
+		/* Headless: layout only, so the steps and navigation sit in rows. All
+		   appearance is up to the consuming theme */
+		.torp-stepper-steps {
+			display: flex;
+			list-style: none;
+			margin: 0;
+			padding: 0;
+		}
+		.torp-stepper-nav {
+			display: flex;
+		}
+	}
+}

package/dist/Stepper/StepperMarker.torp

@@ -0,0 +1,24 @@
+import Check from "../icons/Check.torp";
+
+interface StepperMarkerProps {
+	/** Whether the step this marker belongs to is complete */
+	complete: boolean;
+	/** The index of the step this marker belongs to */
+	index: number;
+}
+
+/**
+ * The marker for a Stepper step, which shows a check when the step is
+ * complete or its number otherwise.
+ */
+export default function StepperMarker($props: StepperMarkerProps) {
+	@render {
+		<span class="torp-stepper-marker" data-state={$props.complete ? "complete" : "incomplete"}>
+			@if ($props.complete) {
+				<Check />
+			} @else {
+				<span aria-hidden="true">{$props.index + 1}</span>
+			}
+		</span>
+	}
+}

package/dist/Stepper/StepperNext.torp

@@ -0,0 +1,44 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import ChevronRight from "../icons/ChevronRight.torp";
+import { type StepperContext, StepperContextName } from "./StepperTypes";
+
+interface StepperNextProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** An ARIA label for the button, for screen readers when the button contains no text */
+	ariaLabel?: string;
+	/** If set to true, the user cannot interact with this button */
+	disabled?: boolean;
+}
+
+/**
+ * The button in a Stepper that a user can press to move to the next step,
+ * which raises the stepper's oncomplete event on the last step.
+ */
+export default function StepperNext($props: StepperNextProps | undefined) {
+	// Get stuff out of the Stepper context
+	const context = $context[StepperContextName] as StepperContext;
+	if (!context) {
+		throw new Error("StepperNext must be contained within a Stepper");
+	}
+
+	@render {
+		<button
+			{$props?.id}
+			class={["torp-stepper-next", $props?.class]}
+			{$props?.style}
+			type="button"
+			aria-label={$props?.ariaLabel ?? "Next step"}
+			disabled={$props?.disabled}
+			onclick={() => context.next()}
+		>
+			<slot>
+				<ChevronRight />
+			</slot>
+		</button>
+	}
+}

package/dist/Stepper/StepperPrevious.torp

@@ -0,0 +1,44 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import ChevronLeft from "../icons/ChevronLeft.torp";
+import { type StepperContext, StepperContextName } from "./StepperTypes";
+
+interface StepperPreviousProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** An ARIA label for the button, for screen readers when the button contains no text */
+	ariaLabel?: string;
+	/** If set to true, the user cannot interact with this button */
+	disabled?: boolean;
+}
+
+/**
+ * The button in a Stepper that a user can press to move to the previous
+ * step.
+ */
+export default function StepperPrevious($props: StepperPreviousProps | undefined) {
+	// Get stuff out of the Stepper context
+	const context = $context[StepperContextName] as StepperContext;
+	if (!context) {
+		throw new Error("StepperPrevious must be contained within a Stepper");
+	}
+
+	@render {
+		<button
+			{$props?.id}
+			class={["torp-stepper-previous", $props?.class]}
+			{$props?.style}
+			type="button"
+			aria-label={$props?.ariaLabel ?? "Previous step"}
+			disabled={$props?.disabled || !context.canPrevious()}
+			onclick={() => context.previous()}
+		>
+			<slot>
+				<ChevronLeft />
+			</slot>
+		</button>
+	}
+}