@torpor/ui 0.4.0 → 1.0.0

package/dist/Stepper/StepperStep.torp

@@ -0,0 +1,90 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import StepperMarker from "./StepperMarker.torp";
+import { type StepperContext, StepperContextName } from "./StepperTypes";
+
+interface StepperStepProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** A label for the step, shown next to its marker */
+	label?: string;
+}
+
+/**
+ * A step in a Stepper, which is complete once the stepper has moved past it,
+ * and current when the stepper is on it.
+ */
+export default function StepperStep($props: StepperStepProps | undefined) {
+	// Get stuff out of the Stepper context
+	const context = $context[StepperContextName] as StepperContext;
+	if (!context) {
+		throw new Error("StepperStep must be contained within a Stepper");
+	}
+
+	// Register this step with the parent Stepper
+	let $state = context.registerStep();
+
+	$run(() => {
+		return () => {
+			context.removeStep($state.index);
+		};
+	});
+
+	function isComplete(): boolean {
+		return $state.index < context.getValue();
+	}
+
+	function isCurrent(): boolean {
+		return $state.index === context.getValue();
+	}
+
+	// Steps can always be revisited once complete; when the stepper is not
+	// linear, any step can be jumped to
+	function canVisit(): boolean {
+		return isComplete() || !context.linear;
+	}
+
+	function handleClick() {
+		if (canVisit()) {
+			context.setValue($state.index);
+		}
+	}
+
+	function stepLabel(): string {
+		return $props?.label ?? `Step ${$state.index + 1}`;
+	}
+
+	@render {
+		<li
+			{$props?.id}
+			class={["torp-stepper-step", $props?.class]}
+			{$props?.style}
+			aria-current={isCurrent() ? "step" : undefined}
+			data-state={isComplete() ? "complete" : isCurrent() ? "current" : "upcoming"}
+		>
+			@if (canVisit()) {
+				<button
+					type="button"
+					class="torp-stepper-step-button"
+					aria-label={`Go to ${stepLabel()}`}
+					onclick={handleClick}
+				>
+					<StepperMarker complete={isComplete()} index={$state.index} />
+					<slot>
+						<span>{stepLabel()}</span>
+					</slot>
+				</button>
+			} @else {
+				<span class="torp-stepper-step-label">
+					<StepperMarker complete={isComplete()} index={$state.index} />
+					<slot>
+						<span>{stepLabel()}</span>
+					</slot>
+				</span>
+			}
+		</li>
+	}
+}

package/dist/Stepper/StepperTypes.ts

@@ -0,0 +1,30 @@
+export const StepperContextName: unique symbol = Symbol.for("torp.Stepper");
+
+export interface StepperStepState {
+	/** The index of the step */
+	index: number;
+}
+
+export interface StepperContext {
+	/** Called from a step when it is added */
+	registerStep: () => StepperStepState;
+	/** Called from a step when it is removed */
+	removeStep: (index: number) => void;
+	/** The index of the current step */
+	getValue: () => number;
+	/** Moves to the step at the given index */
+	setValue: (index: number) => void;
+	/** Moves to the next step, or raises oncomplete on the last one */
+	next: () => void;
+	/** Moves to the previous step */
+	previous: () => void;
+	/** Whether the next / previous controls can move from the current step */
+	canNext: () => boolean;
+	canPrevious: () => boolean;
+	/** The reactive list of registered steps */
+	steps: () => StepperStepState[];
+	/** The number of registered steps */
+	count: () => number;
+	/** Whether steps can only be visited in order, with completed ones revisitable */
+	linear: boolean;
+}

package/dist/Stepper/index.d.ts

@@ -0,0 +1,149 @@
+import { type SlotRender } from "@torpor/view";
+
+
+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>
+ * ```
+ */
+declare function Stepper(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: StepperProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+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.
+ */
+declare function StepperMarker(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: StepperMarkerProps,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+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.
+ */
+declare function StepperNext(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: StepperNextProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+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.
+ */
+declare function StepperPrevious(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: StepperPreviousProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface StepperStepProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** A label for the step, shown next to its marker */
+	label?: string;
+}
+
+/**
+ * A step in a Stepper, which is complete once the stepper has moved past it,
+ * and current when the stepper is on it.
+ */
+declare function StepperStep(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: StepperStepProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { Stepper, StepperMarker, StepperNext, StepperPrevious, StepperStep };

package/dist/Stepper/index.js

@@ -0,0 +1,6 @@
+import Stepper from "./Stepper.torp";
+import StepperMarker from "./StepperMarker.torp";
+import StepperNext from "./StepperNext.torp";
+import StepperPrevious from "./StepperPrevious.torp";
+import StepperStep from "./StepperStep.torp";
+export { Stepper, StepperMarker, StepperNext, StepperPrevious, StepperStep };

package/dist/TabGroup/TabContent.torp

@@ -1,18 +1,18 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
 import getId from "../utils/getId";
-import { TabGroupContextName, type TabGroupContext } from "./TabGroupTypes";
+import { type TabGroupContext, TabGroupContextName } from "./TabGroupTypes";
 
 interface TabContentProps {
 	/** 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;
 	/** The index of this item */
-	index?: number,
+	index?: number;
 	/** The value for this item */
-	value?: string,
+	value?: string;
 }
 
 /**
@@ -36,10 +36,10 @@ export default function TabContent($props: TabContentProps | undefined) {
 			class={["torp-tab-content", $props?.class]}
 			{$props?.style}
 			role="tabpanel"
+			tabindex="0"
 			aria-labelledby={$state.headerId}
 			data-orientation={context.orientation}
 			data-state={$state.active ? "active" : "inactive"}
-			data-disabled={$state.disabled ? "true" : undefined}
 		>
 			@if ($state.active) {
 				<slot />

package/dist/TabGroup/TabGroup.torp

@@ -1,23 +1,25 @@
-import type { ClassValue, StyleValue } from "@torpor/view";
-import { TabGroupContextName, type TabGroupContext, type ItemState } from "./TabGroupTypes";
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import $handle from "../utils/$handle";
+import { createItemGroup } from "../utils/createItemGroup";
+import { type ItemState, type TabGroupContext, TabGroupContextName } from "./TabGroupTypes";
 
 interface TabGroupProps {
 	/** 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;
 	/** The orientation of the tab buttons, which affects keyboard navigation */
-	orientation?: "horizontal" | "vertical",
+	orientation?: "horizontal" | "vertical";
 	/** How tabs are activated; if automatic they are shown on focus, if manual they must be clicked */
-	activation?: "automatic" | "manual",
+	activation?: "automatic" | "manual";
 	/** The value of the active TabContent */
-	value?: string,
+	value?: Bindable<string | undefined>;
 	/** If set to true, the user cannot interact with any items in the TabGroup */
-	disabled?: boolean,
+	disabled?: boolean;
 	/** Raised when the active item has changed */
-	onchange?: (value: string | string[]) => void
+	onchange?: (value: string | string[]) => void;
 }
 
 /**
@@ -40,24 +42,19 @@ interface TabGroupProps {
  * ```
  */
 export default function TabGroup($props: TabGroupProps | undefined) {
-	let orientation = $props?.orientation ?? "horizontal";
-	let activation = $props?.activation ?? "automatic";
-
 	let $state = $watch({
-		value: ""
+		value: "",
 	});
 
-	// Sync props and state
-	$run(() => {
-		$state.value = $props?.value ?? "";
-	});
-	$run(() => {
-		if ($props !== undefined) {
-			$props.value = $state.value;
-		}
-	});
+	$bind($state, $props, "value");
 
-	let itemStates: ItemState[] = [];
+	const group = createItemGroup<ItemState>({
+		state: $state,
+		type: "single",
+		selectedProperty: "active",
+		allowDeselect: false,
+		disabled: () => $props?.disabled,
+	});
 
 	// This is used to assign automatic indexes to items where needed
 	let nextHeaderIndex = 0;
@@ -67,55 +64,43 @@ export default function TabGroup($props: TabGroupProps | undefined) {
 	let context: TabGroupContext = {
 		registerHeader,
 		registerItem,
-		removeItem,
-		triggerItem,
+		removeItem: group.removeItem,
+		triggerItem: group.toggleItem,
 		handleHeaderKey,
-		orientation,
-		activation,
+		get orientation() {
+			return $props?.orientation ?? "horizontal";
+		},
+		get activation() {
+			return $props?.activation ?? "automatic";
+		},
 	};
 	$context[TabGroupContextName] = context;
 
-	$run(() => {
-		// Ensure the value passed in was a string (in case e.g. the user has set values to ints)
-		$state.value = $state.value.toString();
-		for (let item of itemStates) {
-			item.active = item.value === $state.value;
-		}
-	});
-
-	$run(() => {
-		itemStates.forEach((s) => s.parentDisabled = $props?.disabled === true);
-	});
-
 	// Dispatch the change event when the value changes
-	let firstChange = true;
-	$run(() => {
-		const onchange = $props?.onchange;
+	$handle((first) => {
 		const value = $props?.value;
-		if (firstChange) {
-			firstChange = false;
-		} else if (onchange) {
-			onchange(value!);
-		}
+		if (!first) $props?.onchange?.(value!);
 	});
 
 	// On mount, if no value was set, show the first tab content
-	$mount(() => {
-		if ($state.value === "" && itemStates.length) {
-			$state.value = itemStates[0].value;
+	$onmount(() => {
+		if ($state.value === "" && group.itemStates.length) {
+			$state.value = group.itemStates[0].value;
 		}
 	});
 
-	function registerHeader(index: number | undefined, value: string | undefined, setFocused: () => void): ItemState {
+	function registerHeader(
+		index: number | undefined,
+		value: string | undefined,
+		disabled: boolean | undefined,
+	): ItemState {
 		// If an index wasn't set for the header, set it automatically
-		if (!index) {
+		if (index === undefined) {
 			index = nextHeaderIndex++;
 		}
 
 		// Get or add the ItemState at this index
-		const itemState = getItemState(index, value);
-
-		itemState.setFocused = setFocused;
+		const itemState = getItemState(index, value, disabled);
 
 		return itemState;
 	}
@@ -132,10 +117,11 @@ export default function TabGroup($props: TabGroupProps | undefined) {
 		return itemState;
 	}
 
-	function getItemState(index: number, value: string | undefined): ItemState {
-		// If we already have an item at this index, just return it
-		if (itemStates.length > index) {
-			return itemStates[index];
+	function getItemState(index: number, value: string | undefined, disabled?: boolean): ItemState {
+		// If we already have an item with this index, just return it
+		const existing = group.itemStates.find((item) => item.index === index);
+		if (existing) {
+			return existing;
 		}
 
 		// If a value wasn't set for the item, set it to the index
@@ -143,94 +129,92 @@ export default function TabGroup($props: TabGroupProps | undefined) {
 			value = index.toString();
 		}
 
-		// Add the item's state to the array
+		// Add the item's state to the array; the group assigns the active and
+		// parentDisabled states and places it at its index
 		const newItemState: ItemState = $watch({
 			index,
 			value,
-			// TODO: this would be better than using $mount, but it doesn't work with nested tabs
-			// active: value === $props?.value || ($props?.value === "" && index === 0),
-			active: value === $state.value,
+			active: false,
 			headerId: "",
 			contentId: "",
-			disabled: false,
-			parentDisabled: false,
-			get dataState() {
-				return this.active ? "active" : "inactive";
-			},
+			disabled: $props?.disabled ?? disabled ?? false,
+			parentDisabled: $props?.disabled ?? false,
 			setFocused: () => {},
-			orientation,
-			activation
 		});
-		itemStates.splice(index, 0, newItemState);
+		group.registerItem(newItemState);
 
 		return newItemState;
 	}
 
-	// TODO: I think this should be done by value
-	function removeItem(itemIndex: number) {
-		// Remove the item and re-index
-		let index = itemStates.findIndex((item) => item.index === itemIndex);
-		if (index !== -1) {
-			itemStates.splice(itemIndex, 1);
-		}
-		itemStates.forEach((item, i) => (item.index = i));
-	}
-
-	function triggerItem(toggleValue: string) {
-		for (let item of itemStates) {
-			// The item is active if it has the supplied value
-			if (item.value === toggleValue) {
-				$state.value = item.value;
-				break;
-			}
-		}
-	}
-
 	function handleHeaderKey(headerIndex: number, e: KeyboardEvent) {
+		const itemStates = group.itemStates;
+		const orientation = $props?.orientation ?? "horizontal";
 		switch (e.key) {
-			case "Left":
 			case "ArrowLeft": {
-				if (orientation === "horizontal" && headerIndex > 0) {
-					e.preventDefault();
-					itemStates[headerIndex - 1].setFocused();
+				if (orientation === "horizontal") {
+					for (let i = headerIndex - 1; i >= 0; i--) {
+						if (!itemStates[i].disabled) {
+							e.preventDefault();
+							itemStates[i].setFocused();
+							break;
+						}
+					}
 				}
 				break;
 			}
-			case "Up":
 			case "ArrowUp": {
-				if (orientation === "vertical" && headerIndex > 0) {
-					e.preventDefault();
-					itemStates[headerIndex - 1].setFocused();
+				if (orientation === "vertical") {
+					for (let i = headerIndex - 1; i >= 0; i--) {
+						if (!itemStates[i].disabled) {
+							e.preventDefault();
+							itemStates[i].setFocused();
+							break;
+						}
+					}
 				}
 				break;
 			}
-			case "Right":
 			case "ArrowRight": {
-				if (orientation === "horizontal" && headerIndex < itemStates.length - 1) {
-					e.preventDefault();
-					itemStates[headerIndex + 1].setFocused();
+				if (orientation === "horizontal") {
+					for (let i = headerIndex + 1; i < itemStates.length; i++) {
+						if (!itemStates[i].disabled) {
+							e.preventDefault();
+							itemStates[i].setFocused();
+							break;
+						}
+					}
 				}
 				break;
 			}
-			case "Down":
 			case "ArrowDown": {
-				if (orientation === "vertical" && headerIndex < itemStates.length - 1) {
-					e.preventDefault();
-					itemStates[headerIndex + 1].setFocused();
+				if (orientation === "vertical") {
+					for (let i = headerIndex + 1; i < itemStates.length; i++) {
+						if (!itemStates[i].disabled) {
+							e.preventDefault();
+							itemStates[i].setFocused();
+							break;
+						}
+					}
 				}
 				break;
 			}
 			case "Home": {
-				if (headerIndex > 0) {
-					e.preventDefault();
-					itemStates[0].setFocused();
+				for (let i = 0; i < itemStates.length; i++) {
+					if (!itemStates[i].disabled) {
+						e.preventDefault();
+						itemStates[i].setFocused();
+						break;
+					}
 				}
 				break;
 			}
 			case "End": {
-				if (headerIndex < itemStates.length - 1) {
-					e.preventDefault();
-					itemStates[itemStates.length - 1].setFocused();
+				for (let i = itemStates.length - 1; i >= 0; i--) {
+					if (!itemStates[i].disabled) {
+						e.preventDefault();
+						itemStates[i].setFocused();
+						break;
+					}
 				}
 				break;
 			}

package/dist/TabGroup/TabGroupTypes.ts

@@ -6,7 +6,7 @@ export interface TabGroupContext {
 	registerHeader: (
 		index: number | undefined,
 		value: string | undefined,
-		setFocused: () => void,
+		disabled: boolean | undefined,
 	) => ItemState;
 	/** Called from an item when it is added */
 	registerItem: (index: number | undefined, value: string | undefined) => ItemState;