@torpor/ui 0.3.7 → 1.0.0

package/dist/Rating/Rating.torp

@@ -0,0 +1,225 @@
+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 RatingProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The maximum rating, i.e. the number of stars (default 5) */
+	max?: number;
+	/** The current rating */
+	value?: Bindable<number>;
+	/** If set to true, the user cannot interact with this rating */
+	disabled?: boolean;
+	/** If set to false, clicking or re-selecting the current rating does not clear it (default true) */
+	allowClear?: boolean;
+	/** An accessible name for the rating */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when the rating has changed */
+	onchange?: (value: number) => void;
+}
+
+/**
+ * A star rating input, where the user selects a value from 1 to a maximum
+ * number of stars by clicking or by using the keyboard.
+ *
+ * Implements the radio group pattern: each star is a radio button, the star
+ * matching the current rating is checked, and arrow keys move the rating.
+ *
+ * See [the WAI ARIA guidelines for Rating](https://www.w3.org/WAI/ARIA/apg/patterns/rating/).
+ */
+export default function Rating($props: RatingProps | undefined) {
+	let stars: (HTMLButtonElement | undefined)[] = [];
+	let root: 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 getMax(): number {
+		const max = $props?.max ?? 5;
+		return max > 0 ? Math.floor(max) : 5;
+	}
+	function getDisabled(): boolean {
+		return $props?.disabled === true;
+	}
+
+	let $state = $watch({
+		value: 0,
+		hover: 0,
+		get stars(): number[] {
+			return Array.from({ length: getMax() }, (_, i) => i + 1);
+		},
+	});
+
+	$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;
+		}
+	});
+
+	// 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(0, value));
+	}
+
+	function getValue(): number {
+		return clamp($state.value);
+	}
+
+	function setValue(value: number, focus = false) {
+		const next = clamp(value);
+		if (next !== $state.value) {
+			$state.value = next;
+		}
+		if (focus) {
+			stars[next - 1]?.focus();
+		}
+	}
+
+	// The number of filled stars to display, taking the hovered star into
+	// account for the mouse preview
+	function getDisplayValue(): number {
+		return getDisabled() ? getValue() : Math.max(getValue(), $state.hover);
+	}
+
+	function handleClick(value: number) {
+		if (getDisabled()) return;
+		if (value === $state.value && ($props?.allowClear ?? true)) {
+			setValue(0);
+		} else {
+			setValue(value);
+		}
+		form.handleInput();
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		if (getDisabled()) return;
+
+		switch (e.key) {
+			case "ArrowRight":
+			case "ArrowUp": {
+				e.preventDefault();
+				setValue(Math.max(1, $state.value + 1), true);
+				form.handleInput();
+				break;
+			}
+			case "ArrowLeft":
+			case "ArrowDown": {
+				e.preventDefault();
+				setValue($state.value <= 1 ? 1 : $state.value - 1, true);
+				form.handleInput();
+				break;
+			}
+			case "Home": {
+				e.preventDefault();
+				setValue(1, true);
+				form.handleInput();
+				break;
+			}
+			case "End": {
+				e.preventDefault();
+				setValue(getMax(), true);
+				form.handleInput();
+				break;
+			}
+		}
+	}
+
+	// Only blur when focus leaves the whole rating
+	function handleFocusOut(e: FocusEvent) {
+		if (!root.contains(e.relatedTarget as Node | null)) {
+			form.handleBlur();
+		}
+	}
+
+	// Roving tabindex: the star matching the current rating (or the first
+	// star when there is no rating) is the single tab stop
+	function tabStop(value: number): boolean {
+		return value === ($state.value > 0 ? $state.value : 1);
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-rating", getDisabled() ? "torp-rating-disabled" : undefined, $props?.class]}
+			{$props?.style}
+			role="radiogroup"
+			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}
+			onmouseleave={() => ($state.hover = 0)}
+			onfocusout={handleFocusOut}
+			&ref={root}
+		>
+			@for (let value of $state.stars) {
+				@key = value
+				<button
+					type="button"
+					class="torp-rating-star"
+					role="radio"
+					tabindex={tabStop(value) ? 0 : -1}
+					aria-checked={value === getValue() ? "true" : "false"}
+					aria-label={`${value} ${value === 1 ? "star" : "stars"}`}
+					aria-disabled={getDisabled() ? "true" : undefined}
+					data-state={value <= getDisplayValue() ? "filled" : "empty"}
+					onmount={(el) => {
+						stars[value - 1] = el;
+						return () => {
+							if (stars[value - 1] === el) {
+								stars[value - 1] = undefined;
+							}
+						};
+					}}
+					onclick={() => handleClick(value)}
+					onkeydown={handleKey}
+					onmouseenter={() => {
+						if (!getDisabled()) $state.hover = value;
+					}}
+				>
+					<slot item={{ value: value, filled: value <= getDisplayValue() }}>
+						<span aria-hidden="true">{value <= getDisplayValue() ? "★" : "☆"}</span>
+					</slot>
+				</button>
+			}
+		</div>
+
+		<FormValues name={form.name} value={getValue() > 0 ? getValue() : undefined} />
+	}
+
+	@style {
+		/* Headless: layout only, so the stars sit in a row. All appearance is
+		   up to the consuming theme */
+		.torp-rating {
+			display: inline-flex;
+		}
+	}
+}

package/dist/Rating/index.d.ts

@@ -0,0 +1,44 @@
+import { type SlotRender } from "@torpor/view";
+
+
+interface RatingProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The maximum rating, i.e. the number of stars (default 5) */
+	max?: number;
+	/** The current rating */
+	value?: Bindable<number>;
+	/** If set to true, the user cannot interact with this rating */
+	disabled?: boolean;
+	/** If set to false, clicking or re-selecting the current rating does not clear it (default true) */
+	allowClear?: boolean;
+	/** An accessible name for the rating */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when the rating has changed */
+	onchange?: (value: number) => void;
+}
+
+/**
+ * A star rating input, where the user selects a value from 1 to a maximum
+ * number of stars by clicking or by using the keyboard.
+ *
+ * Implements the radio group pattern: each star is a radio button, the star
+ * matching the current rating is checked, and arrow keys move the rating.
+ *
+ * See [the WAI ARIA guidelines for Rating](https://www.w3.org/WAI/ARIA/apg/patterns/rating/).
+ */
+declare function Rating(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: RatingProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { Rating };

package/dist/Rating/index.js

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

package/dist/SegmentedControl/SegmentedControl.torp

@@ -0,0 +1,233 @@
+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 { createFocusGroup } from "../utils/focusGroup";
+import { createItemGroup } from "../utils/createItemGroup";
+import createFormField from "../utils/formField";
+import type { FocusTarget } from "../utils/focusItem";
+import {
+	type ItemState,
+	type SegmentedControlContext,
+	SegmentedControlContextName,
+} from "./SegmentedControlTypes";
+
+interface SegmentedControlProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The value of the active segment */
+	value?: Bindable<string | undefined>;
+	/** If set to true, the user cannot interact with any segments */
+	disabled?: boolean;
+	/** An accessible name for the control */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when the active segment has changed */
+	onchange?: (value: string) => void;
+}
+
+/**
+ * A compact group of segments, of which exactly one is active. The user moves
+ * between segments with the arrow keys, or selects one directly.
+ *
+ * See [the WAI ARIA guidelines for Radio Groups](https://www.w3.org/WAI/ARIA/apg/patterns/radiogroup/).
+ *
+ * The structure of a SegmentedControl is:
+ *
+ * ```
+ * <SegmentedControl ariaLabel="View">
+ * 	<SegmentedItem value="day">Day</SegmentedItem>
+ * 	<SegmentedItem value="week">Week</SegmentedItem>
+ * </SegmentedControl>
+ * ```
+ */
+export default function SegmentedControl($props: SegmentedControlProps | undefined) {
+	let nextItemIndex = 0;
+	let root: 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,
+	);
+
+	let $state = $watch({
+		value: $props?.value ?? "",
+	});
+
+	$bind($state, $props, "value");
+
+	const group = createItemGroup<ItemState>({
+		state: $state,
+		type: "single",
+		selectedProperty: "active",
+		allowDeselect: false,
+		disabled: () => $props?.disabled,
+		// Select the first enabled item as items register, when nothing is
+		// selected yet; this is a default, not a user change, so it doesn't
+		// raise onchange
+		onRegister: (item) => {
+			if ($state.value === "" && !item.disabled) {
+				skipNextChange = true;
+				$state.value = item.value;
+			}
+		},
+	});
+
+	// The focus group owns the roving-tabindex bookkeeping; the selection
+	// group above stays the source of truth for the active segment
+	const focusGroup = createFocusGroup<ItemState>();
+
+	// Set the context to pass down to items
+	const context: SegmentedControlContext = {
+		registerItem,
+		removeItem: (itemIndex) => {
+			group.removeItem(itemIndex);
+			focusGroup.removeItem(itemIndex);
+		},
+		triggerItem: (value) => {
+			group.toggleItem(value);
+			form.handleInput();
+		},
+		handleItemKey,
+	};
+	$context[SegmentedControlContextName] = context;
+
+	// Dispatch the change event when the value changes
+	let skipNextChange = false;
+	$handle((first) => {
+		const value = $state.value;
+		if (skipNextChange) {
+			skipNextChange = false;
+			return;
+		}
+		if (!first && value !== "") $props?.onchange?.(value);
+	});
+
+	function registerItem(
+		index: number | undefined,
+		value: string | undefined,
+		disabled: boolean | undefined,
+	): ItemState {
+		// If an index wasn't set for the item, set it automatically
+		if (index === undefined) {
+			index = nextItemIndex++;
+		}
+
+		// 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
+		if (value === undefined) {
+			value = index.toString();
+		}
+
+		const itemState: ItemState = $watch({
+			index,
+			value,
+			active: false,
+			disabled: disabled ?? false,
+			parentDisabled: $props?.disabled ?? false,
+			setFocused: () => {},
+		});
+		group.registerItem(itemState);
+		focusGroup.registerItem(itemState);
+
+		return itemState;
+	}
+
+	function handleItemKey(index: number, e: KeyboardEvent) {
+		switch (e.key) {
+			case "ArrowRight":
+			case "ArrowDown": {
+				e.preventDefault();
+				move(index, "next");
+				break;
+			}
+			case "ArrowLeft":
+			case "ArrowUp": {
+				e.preventDefault();
+				move(index, "previous");
+				break;
+			}
+			case "Home": {
+				e.preventDefault();
+				move(index, "start");
+				break;
+			}
+			case "End": {
+				e.preventDefault();
+				move(index, "end");
+				break;
+			}
+		}
+	}
+
+	// Moving with the keyboard both selects and focuses the target segment,
+	// like a radio group
+	function move(index: number, target: FocusTarget) {
+		const before = focusGroup.getFocusIndex();
+		focusGroup.moveFocus(index, target);
+		const next = focusGroup.getFocusIndex();
+		if (next !== before) {
+			const item = focusGroup.itemStates[next];
+			if (item) {
+				group.toggleItem(item.value);
+				form.handleInput();
+			}
+		}
+	}
+
+	// Only blur when focus leaves the whole control
+	function handleFocusOut(e: FocusEvent) {
+		if (!root.contains(e.relatedTarget as Node | null)) {
+			form.handleBlur();
+		}
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={[
+				"torp-segmented-control",
+				$props?.disabled ? "torp-segmented-control-disabled" : undefined,
+				$props?.class,
+			]}
+			{$props?.style}
+			role="radiogroup"
+			aria-label={$props?.ariaLabel}
+			aria-disabled={$props?.disabled ? "true" : undefined}
+			data-valid={form.valid ? "valid" : "invalid"}
+			aria-describedby={form.messageId}
+			aria-invalid={form.inField && !form.valid ? "true" : undefined}
+			onfocusout={handleFocusOut}
+			&ref={root}
+		>
+			<slot />
+		</div>
+
+		<FormValues name={form.name} value={$state.value} />
+	}
+
+	@style {
+		/* Headless: layout only, so the segments sit in a row. All appearance
+		   is up to the consuming theme */
+		.torp-segmented-control {
+			display: inline-flex;
+		}
+	}
+}

package/dist/SegmentedControl/SegmentedControlTypes.ts

@@ -0,0 +1,26 @@
+export const SegmentedControlContextName: unique symbol = Symbol.for("torp.SegmentedControl");
+
+export interface SegmentedControlContext {
+	/** Called from an item when it is added */
+	registerItem: (
+		index: number | undefined,
+		value: string | undefined,
+		disabled: boolean | undefined,
+	) => ItemState;
+	/** Called from an item when it is removed */
+	removeItem: (index: number) => void;
+	/** Called from an item when it is selected */
+	triggerItem: (value: string) => void;
+	/** Called from an item when it receives a keyboard event */
+	handleItemKey: (index: number, e: KeyboardEvent) => void;
+}
+
+export interface ItemState {
+	index: number;
+	value: string;
+	active: boolean;
+	disabled: boolean;
+	parentDisabled: boolean;
+	/** Called in the SegmentedControl when an item needs to be focused */
+	setFocused: () => void;
+}

package/dist/SegmentedControl/SegmentedItem.torp

@@ -0,0 +1,78 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { type SegmentedControlContext, SegmentedControlContextName } from "./SegmentedControlTypes";
+
+interface SegmentedItemProps {
+	/** 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 this item */
+	index?: number;
+	/** The value for this item */
+	value?: string;
+	/** If set to true, the user cannot interact with this item */
+	disabled?: boolean;
+}
+
+/**
+ * A segment in a SegmentedControl, one of which is always active.
+ */
+export default function SegmentedItem($props: SegmentedItemProps | undefined) {
+	let button: HTMLButtonElement;
+
+	// Get stuff out of the SegmentedControl context
+	const context = $context[SegmentedControlContextName] as SegmentedControlContext;
+	if (!context) {
+		throw new Error("SegmentedItem must be contained within a SegmentedControl");
+	}
+
+	// Register this item with the parent SegmentedControl
+	let $state = context.registerItem($props?.index, $props?.value, $props?.disabled);
+
+	$run(() => {
+		return () => {
+			context.removeItem($state.index);
+		};
+	});
+
+	// This function is called by the parent SegmentedControl to focus this item
+	function setFocused() {
+		button.focus();
+	}
+	$state.setFocused = setFocused;
+
+	function getDisabled(): boolean {
+		return $state.disabled || $state.parentDisabled;
+	}
+
+	function handleClick() {
+		if (getDisabled()) return;
+		context.triggerItem($state.value);
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		if (getDisabled()) return;
+		context.handleItemKey($state.index, e);
+	}
+
+	@render {
+		<button
+			type="button"
+			{$props?.id}
+			class={["torp-segmented-item", $props?.class]}
+			{$props?.style}
+			role="radio"
+			tabindex={$state.active ? 0 : -1}
+			aria-checked={$state.active ? "true" : "false"}
+			aria-disabled={getDisabled() ? "true" : undefined}
+			data-state={$state.active ? "active" : "inactive"}
+			onclick={handleClick}
+			onkeydown={handleKey}
+			&ref={button}
+		>
+			<slot />
+		</button>
+	}
+}

package/dist/SegmentedControl/index.d.ts

@@ -0,0 +1,74 @@
+import { type SlotRender } from "@torpor/view";
+
+
+interface SegmentedControlProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The value of the active segment */
+	value?: Bindable<string | undefined>;
+	/** If set to true, the user cannot interact with any segments */
+	disabled?: boolean;
+	/** An accessible name for the control */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when the active segment has changed */
+	onchange?: (value: string) => void;
+}
+
+/**
+ * A compact group of segments, of which exactly one is active. The user moves
+ * between segments with the arrow keys, or selects one directly.
+ *
+ * See [the WAI ARIA guidelines for Radio Groups](https://www.w3.org/WAI/ARIA/apg/patterns/radiogroup/).
+ *
+ * The structure of a SegmentedControl is:
+ *
+ * ```
+ * <SegmentedControl ariaLabel="View">
+ * 	<SegmentedItem value="day">Day</SegmentedItem>
+ * 	<SegmentedItem value="week">Week</SegmentedItem>
+ * </SegmentedControl>
+ * ```
+ */
+declare function SegmentedControl(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: SegmentedControlProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface SegmentedItemProps {
+	/** 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 this item */
+	index?: number;
+	/** The value for this item */
+	value?: string;
+	/** If set to true, the user cannot interact with this item */
+	disabled?: boolean;
+}
+
+/**
+ * A segment in a SegmentedControl, one of which is always active.
+ */
+declare function SegmentedItem(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: SegmentedItemProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { SegmentedControl, SegmentedItem };

package/dist/SegmentedControl/index.js

@@ -0,0 +1,3 @@
+import SegmentedControl from "./SegmentedControl.torp";
+import SegmentedItem from "./SegmentedItem.torp";
+export { SegmentedControl, SegmentedItem };