@torpor/ui 0.4.0 → 1.0.1

package/dist/NumberInput/NumberInput.torp

@@ -0,0 +1,255 @@
+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 NumberInputProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The current value of the input; null if the field is empty */
+	value?: Bindable<number | null>;
+	/** The minimum allowed value */
+	min?: number;
+	/** The maximum allowed value */
+	max?: number;
+	/** The amount by which the value is increased or decreased (default 1) */
+	step?: number;
+	/** If set to true, the user cannot interact with this input */
+	disabled?: boolean;
+	/** An accessible name for the input */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when the value has changed */
+	onchange?: (value: number | null) => void;
+}
+
+/**
+ * An input where the user enters or steps a number between minimum and
+ * maximum values, by typing, by pressing the arrow keys, or by pressing the
+ * Home, End, PageUp or PageDown keys.
+ *
+ * See [the WAI ARIA guidelines for Spin Buttons](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/).
+ */
+export default function NumberInput($props: NumberInputProps | undefined) {
+	let input: HTMLInputElement;
+
+	// 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 | undefined {
+		return $props?.min;
+	}
+	function getMax(): number | undefined {
+		return $props?.max;
+	}
+	function getStep(): number {
+		const step = $props?.step ?? 1;
+		return step > 0 ? step : 1;
+	}
+	function getDisabled(): boolean {
+		return $props?.disabled === true;
+	}
+
+	// The number of decimal places implied by the step, e.g. 0.25 -> 2
+	function getPrecision(): number {
+		const text = String(getStep());
+		const dot = text.indexOf(".");
+		return dot === -1 ? 0 : text.length - dot - 1;
+	}
+
+	let $state = $watch({
+		value: null as number | null,
+		text: "",
+		editing: false,
+	});
+
+	$bind($state, $props, "value");
+
+	// Keep the stored value clamped, so that out-of-range initial values
+	// don't later surface as user changes
+	$run(() => {
+		const clamped = clamp($state.value);
+		if (clamped !== $state.value) {
+			$state.value = clamped;
+		}
+	});
+
+	// The text tracks the value, unless the user is typing
+	$run(() => {
+		if (!$state.editing) {
+			$state.text = $state.value == null ? "" : String($state.value);
+		}
+	});
+
+	// Keep the input's value in sync with the text; typing sets the property
+	// directly, so an attribute alone would not update it
+	function syncInput() {
+		if (input && !$state.editing && input.value !== $state.text) {
+			input.value = $state.text;
+		}
+	}
+	$run(() => {
+		const text = $state.text;
+		const editing = $state.editing;
+		if (input && !editing && input.value !== text) {
+			input.value = text;
+		}
+	});
+	$onmount(() => syncInput());
+
+	// Dispatch the change event when a committed value changes
+	$handle((first) => {
+		const value = $state.value;
+		if (!first && !$state.editing) $props?.onchange?.(value);
+	});
+
+	function clamp(value: number | null): number | null {
+		if (value == null) return null;
+		let result = value;
+		if (getMin() != null) result = Math.max(getMin()!, result);
+		if (getMax() != null) result = Math.min(getMax()!, result);
+		return round(result);
+	}
+
+	function round(value: number): number {
+		const precision = getPrecision();
+		return precision ? Number(value.toFixed(precision)) : value;
+	}
+
+	function parse(text: string): number | null {
+		const trimmed = text.trim();
+		if (trimmed === "") return null;
+		const parsed = Number(trimmed);
+		return Number.isFinite(parsed) ? parsed : null;
+	}
+
+	function setValue(value: number | null) {
+		const next = clamp(value);
+		$state.editing = false;
+		if (next !== $state.value) {
+			$state.value = next;
+			form.handleInput();
+		}
+		// The text always matches what was committed
+		$state.text = next == null ? "" : String(next);
+	}
+
+	function stepValue(delta: number) {
+		if (getDisabled()) return;
+		const base = $state.value ?? 0;
+		setValue(base + delta);
+	}
+
+	function handleInput(e: Event) {
+		const el = e.currentTarget as HTMLInputElement;
+		$state.editing = true;
+		$state.text = el.value;
+	}
+
+	// Typing commits on blur or Enter; invalid text reverts
+	function commit() {
+		const text = $state.text;
+		$state.editing = false;
+		const parsed = parse(text);
+		if (parsed == null && text.trim() !== "") {
+			// Not a number: revert to the last committed value
+			$state.text = $state.value == null ? "" : String($state.value);
+			return;
+		}
+		setValue(parsed);
+	}
+
+	function handleBlur() {
+		commit();
+		form.handleBlur();
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		if (getDisabled()) return;
+
+		switch (e.key) {
+			case "ArrowUp": {
+				e.preventDefault();
+				stepValue(getStep());
+				break;
+			}
+			case "ArrowDown": {
+				e.preventDefault();
+				stepValue(-getStep());
+				break;
+			}
+			case "PageUp": {
+				e.preventDefault();
+				stepValue(getStep() * 10);
+				break;
+			}
+			case "PageDown": {
+				e.preventDefault();
+				stepValue(-getStep() * 10);
+				break;
+			}
+			case "Home": {
+				if (getMin() != null) {
+					e.preventDefault();
+					setValue(getMin()!);
+				}
+				break;
+			}
+			case "End": {
+				if (getMax() != null) {
+					e.preventDefault();
+					setValue(getMax()!);
+				}
+				break;
+			}
+			case "Enter": {
+				e.preventDefault();
+				commit();
+				break;
+			}
+		}
+	}
+
+	@render {
+		<input
+			id={$props?.id}
+			class={["torp-number-input", $props?.class]}
+			{$props?.style}
+			type="text"
+			inputmode="decimal"
+			role="spinbutton"
+			value={$state.text}
+			&ref={input}
+			tabindex={getDisabled() ? -1 : 0}
+			aria-label={$props?.ariaLabel}
+			aria-valuemin={getMin()}
+			aria-valuemax={getMax()}
+			aria-valuenow={$state.value == null ? undefined : $state.value}
+			aria-disabled={getDisabled() ? "true" : undefined}
+			data-valid={form.valid ? "valid" : "invalid"}
+			aria-describedby={form.messageId}
+			aria-invalid={form.inField && !form.valid ? "true" : undefined}
+			disabled={getDisabled()}
+			oninput={handleInput}
+			onblur={handleBlur}
+			onkeydown={handleKey}
+		/>
+
+		<FormValues name={form.name} value={$state.value} />
+	}
+}

package/dist/NumberInput/index.d.ts

@@ -0,0 +1,44 @@
+import { type SlotRender } from "@torpor/view";
+
+
+interface NumberInputProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The current value of the input; null if the field is empty */
+	value?: Bindable<number | null>;
+	/** The minimum allowed value */
+	min?: number;
+	/** The maximum allowed value */
+	max?: number;
+	/** The amount by which the value is increased or decreased (default 1) */
+	step?: number;
+	/** If set to true, the user cannot interact with this input */
+	disabled?: boolean;
+	/** An accessible name for the input */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when the value has changed */
+	onchange?: (value: number | null) => void;
+}
+
+/**
+ * An input where the user enters or steps a number between minimum and
+ * maximum values, by typing, by pressing the arrow keys, or by pressing the
+ * Home, End, PageUp or PageDown keys.
+ *
+ * See [the WAI ARIA guidelines for Spin Buttons](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/).
+ */
+declare function NumberInput(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: NumberInputProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { NumberInput };

package/dist/NumberInput/index.js

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

package/dist/Pagination/Pagination.torp

@@ -1,27 +1,43 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { PaginationContextName, type PaginationContext, type ItemState, type PageNumber } from "./PaginationTypes";
+import {
+	type ItemState,
+	type PageNumber,
+	type PaginationContext,
+	PaginationContextName,
+} from "./PaginationTypes";
+import buildPages from "./buildPages";
 
 interface PaginationProps {
 	/** 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 total number of pages (or items if the page size is greater than 1) */
-	count: number,
-	/** The active page number */
-	number: number,
+	count: number;
+	/** The active page */
+	page: number;
+	/** The number of items on each page **/
+	pageSize?: number;
+	/** The maximum number of pages to display (gaps will be indicated with ellipses) **/
+	maxPages?: number;
+	/** Accessible label for the pagination navigation */
+	"aria-label"?: string;
+	/** Called when a user wants to jump to a specific page (e.g., via ellipsis) */
+	onjump?: (targetPage: number, jumpTo: (page: number) => void) => void;
 }
 
 /**
  * Buttons with page numbers that can be used to move between pages.
  */
 export default function Pagination($props: PaginationProps) {
-	// TODO: Should we (by default) create PaginationItems?
+	let $state = $watch({
+		get pages() {
+			return buildPages($props.count, $props.page, $props.pageSize, $props.maxPages);
+		},
+	});
 
-	// TODO: Do we actually need ItemStates when we're creating the item collection ourselves??
-	// A collection containing the active state and some functions for each item
 	let itemStates: ItemState[] = [];
 
 	// Put stuff into a PaginationContext
@@ -29,23 +45,16 @@ export default function Pagination($props: PaginationProps) {
 		registerItem,
 		removeItem,
 		toggleItem,
-		handleItemKey
+		handleItemKey,
+		jumpToPage: (page: number) => {
+			$props.page = Math.max(1, Math.min($props.count, page));
+		},
 	};
 	$context[PaginationContextName] = context;
 
-	function registerItem(
-		target: PageNumber,
-		setActive: (value: boolean) => void,
-		setFocused: () => void
-	) {
+	function registerItem(item: ItemState) {
 		// Add the item's state to the array
-		const newItemState: ItemState = {
-			target,
-			active: false,
-			setActive,
-			setFocused
-		};
-		itemStates.push(newItemState);
+		itemStates.push(item);
 	}
 
 	function removeItem(target: PageNumber) {
@@ -59,31 +68,30 @@ export default function Pagination($props: PaginationProps) {
 	function toggleItem(target: PageNumber) {
 		switch (target) {
 			case "start": {
-				$props.number = 1;
+				$props.page = 1;
 				break;
 			}
 			case "previous": {
-				$props.number = Math.max(1, $props.number - 1);
+				$props.page = Math.max(1, $props.page - 1);
 				break;
 			}
 			case "next": {
-				$props.number = Math.min($props.count, $props.number + 1);
+				$props.page = Math.min($props.count, $props.page + 1);
 				break;
 			}
 			case "end": {
-				$props.number = $props.count;
+				$props.page = $props.count;
 				break;
 			}
 			case "startgap":
 			case "endgap": {
-				let input = prompt("Go to page:");
-				if (input) {
-					$props.number = parseInt(input);
+				if ($props.onjump) {
+					$props.onjump($props.page, context.jumpToPage);
 				}
 				break;
 			}
 			default: {
-				$props.number = target;
+				$props.page = target;
 			}
 		}
 
@@ -102,15 +110,12 @@ export default function Pagination($props: PaginationProps) {
 	}
 
 	function handleItemKey(e: KeyboardEvent) {
-		// TODO: Actually just change focus??
 		switch (e.key) {
-			case "Left":
 			case "ArrowLeft": {
 				toggleItem("previous");
 				e.preventDefault();
 				break;
 			}
-			case "Right":
 			case "ArrowRight": {
 				toggleItem("next");
 				e.preventDefault();
@@ -135,10 +140,12 @@ export default function Pagination($props: PaginationProps) {
 				{$props?.id}
 				class={["torp-pagination", $props?.class]}
 				{$props?.style}
+				role="navigation"
+				aria-label={$props["aria-label"] ?? "Pagination"}
 				tabindex="0"
 				onfocus={handleFocus}
 			>
-				<slot />
+				<slot {$state.pages} />
 			</div>
 		}
 	}

package/dist/Pagination/PaginationItem.torp

@@ -1,20 +1,26 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { PaginationContextName, type PaginationContext, type PageNumber } from "./PaginationTypes";
+import ChevronDoubleLeft from "../icons/ChevronDoubleLeft.torp";
+import ChevronDoubleRight from "../icons/ChevronDoubleRight.torp";
+import ChevronLeft from "../icons/ChevronLeft.torp";
+import ChevronRight from "../icons/ChevronRight.torp";
+import { type PageNumber, type PaginationContext, PaginationContextName } from "./PaginationTypes";
 
 interface PaginationItemProps {
 	/** 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 page for the button */
 	page: PageNumber;
 	/** Whether this is the active item */
 	active?: boolean;
+	/** Whether this item is disabled */
+	disabled?: boolean;
 	/** Raised when this item is made active */
-	ontoggle?: (active: boolean) => void,
-};
+	onchange?: (active: boolean) => void;
+}
 
 export default function PaginationItem($props: PaginationItemProps) {
 	let button: HTMLButtonElement;
@@ -24,10 +30,28 @@ export default function PaginationItem($props: PaginationItemProps) {
 	if (!context) {
 		throw new Error("PaginationItem must be contained within a Pagination");
 	}
-	const { registerItem, /*removeItem,*/ toggleItem, handleItemKey } = context;
+	const { registerItem, removeItem, toggleItem, handleItemKey } = context;
 
 	// Register this item with the parent Pagination, which will handle setting this item's focus on keyboard events
-	registerItem($props.page, setActive, setFocused);
+	registerItem({ target: $props.page, active: false, setActive, setFocused });
+
+	$run(() => {
+		return () => {
+			removeItem($props.page);
+		};
+	});
+
+	// Call onchange when the active state changes
+	let prevActive = $props.active ?? false;
+	$run(() => {
+		const active = $props.active ?? false;
+		if (active !== prevActive) {
+			prevActive = active;
+			if ($props?.onchange) {
+				$props.onchange(active);
+			}
+		}
+	});
 
 	// This function is called by the parent Pagination to set this item's active value
 	function setActive(value: boolean) {
@@ -36,8 +60,8 @@ export default function PaginationItem($props: PaginationItemProps) {
 
 			/** Raised when this item is made active */
 			//dispatch("toggle", value);
-		 	if ($props?.ontoggle) {
-				$props.ontoggle(value);
+			if ($props?.onchange) {
+				$props.onchange(value);
 			}
 		}
 	}
@@ -64,6 +88,9 @@ export default function PaginationItem($props: PaginationItemProps) {
 				{$props?.id}
 				class={["torp-pagination-item", $props?.class]}
 				{$props?.style}
+				role="button"
+				aria-current="page"
+				aria-label={`Page ${$props.page}`}
 				data-state={$props.active ? "active" : "inactive"}
 			>
 				{$props.page}
@@ -73,6 +100,16 @@ export default function PaginationItem($props: PaginationItemProps) {
 				type="button"
 				{$props?.id}
 				class={["torp-pagination-item", $props?.class]}
+				{$props?.disabled}
+				aria-label={
+					$props.page === "start" ? "First page" :
+					$props.page === "previous" ? "Previous page" :
+					$props.page === "next" ? "Next page" :
+					$props.page === "end" ? "Last page" :
+					$props.page === "startgap" || $props.page === "endgap" ? "More pages" :
+					`Page ${$props.page}`
+				}
+				aria-disabled={$props.disabled ? "true" : undefined}
 				data-type={$props.page}
 				data-state={$props.active ? "active" : "inactive"}
 				&ref={button}
@@ -81,13 +118,13 @@ export default function PaginationItem($props: PaginationItemProps) {
 			>
 				<slot>
 					@if ($props.page === "start") {
-						<span>&lt;&lt;</span>
+						<ChevronDoubleLeft />
 					} else if ($props.page === "previous") {
-						<span>&lt;</span>
+						<ChevronLeft />
 					} else if ($props.page === "next") {
-						<span>&gt;</span>
+						<ChevronRight />
 					} else if ($props.page === "end") {
-						<span>&gt;&gt;</span>
+						<ChevronDoubleRight />
 					} else if ($props.page === "startgap" || $props.page === "endgap") {
 						<span>…</span>
 					} else {

package/dist/Pagination/PaginationTypes.ts

@@ -2,17 +2,14 @@ export const PaginationContextName: unique symbol = Symbol.for("torp.Pagination"
 
 export interface PaginationContext {
 	// The registerItem function is called from each SeriesItem to register itself and its
-	// methods with this component
-	registerItem: (
-		target: PageNumber,
-		setActive: (value: boolean) => void,
-		setFocused: () => void,
-	) => void;
+	// state with this component
+	registerItem: (item: ItemState) => void;
 	// The removeItem function is called from a SeriesItem when it has been unloaded so that we
 	// can remove it from the itemStates array
 	removeItem: (target: PageNumber) => void;
 	toggleItem: (target: PageNumber) => void;
 	handleItemKey: (e: KeyboardEvent) => void;
+	jumpToPage: (page: number) => void;
 }
 
 export interface ItemState {

package/dist/Pagination/buildPages.ts

@@ -4,13 +4,13 @@ import { type PageNumber } from "./PaginationTypes";
  * Builds the pages that should be displayed for pagination.
  *
  * @param count The total number of pages (or items if the page size is greater than 1)
- * @param number The active page number
+ * @param page The active page
  * @param pageSize The number of items on each page
  * @param maxPages The maximum number of pages to display (gaps will be indicated with ellipses)
  */
 export default function buildPages(
 	count: number,
-	number: number,
+	page: number,
 	pageSize: number = 1,
 	maxPages: number = 9,
 ): PageNumber[] {
@@ -18,7 +18,7 @@ export default function buildPages(
 	const pageCount = Math.ceil(count / pageSize);
 
 	if (pageCount <= maxPages) {
-		// There"s no need for ellipses, just return the numbers
+		// There's no need for ellipses, just return the numbers
 		return Array.from({ length: pageCount })
 			.fill(0)
 			.map((_, i) => i + 1);
@@ -26,8 +26,8 @@ export default function buildPages(
 		// Get the start and end around the current page number
 		// Use floor and ceil in case there is an even number of pages (e.g. if
 		// maxPages is 8, there will be 3 numbers at the start and 4 at the end)
-		let start = number - Math.floor((maxPages - 1) / 2);
-		let end = number + Math.ceil((maxPages - 1) / 2);
+		let start = page - Math.floor((maxPages - 1) / 2);
+		let end = page + Math.ceil((maxPages - 1) / 2);
 		if (start < 1) {
 			end += Math.abs(start) + 1;
 			start = 1;
@@ -44,12 +44,16 @@ export default function buildPages(
 		// Replace numbers at the start and end with ellipses if necessary
 		if (numbers[0] !== 1) {
 			numbers[0] = 1;
+			//if (numbers.length > 1) {
 			numbers[1] = "startgap";
+			//}
 		}
 		const l = numbers.length;
 		if (numbers[l - 1] !== pageCount) {
 			numbers[l - 1] = pageCount;
+			//if (l > 2) {
 			numbers[l - 2] = "endgap";
+			//}
 		}
 
 		return numbers;

package/dist/Pagination/index.d.ts

@@ -5,13 +5,21 @@ interface PaginationProps {
 	/** 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 total number of pages (or items if the page size is greater than 1) */
-	count: number,
-	/** The active page number */
-	number: number,
+	count: number;
+	/** The active page */
+	page: number;
+	/** The number of items on each page **/
+	pageSize?: number;
+	/** The maximum number of pages to display (gaps will be indicated with ellipses) **/
+	maxPages?: number;
+	/** Accessible label for the pagination navigation */
+	"aria-label"?: string;
+	/** Called when a user wants to jump to a specific page (e.g., via ellipsis) */
+	onjump?: (targetPage: number, jumpTo: (page: number) => void) => void;
 }
 
 /**
@@ -31,15 +39,17 @@ interface PaginationItemProps {
 	/** 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 page for the button */
 	page: PageNumber;
 	/** Whether this is the active item */
 	active?: boolean;
+	/** Whether this item is disabled */
+	disabled?: boolean;
 	/** Raised when this item is made active */
-	ontoggle?: (active: boolean) => void,
+	onchange?: (active: boolean) => void;
 }
 
 declare function PaginationItem(
@@ -50,4 +60,4 @@ declare function PaginationItem(
 	$slots?: Record<string, SlotRender>,
 ): void;
 
-export { Pagination, PaginationItem };
+export { Pagination, PaginationItem };