@torpor/ui 1.0.1 → 1.1.0

package/dist/Progress/ProgressIndicator.torp

@@ -0,0 +1,52 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { type ProgressContext, ProgressContextName } from "./ProgressTypes";
+
+interface ProgressIndicatorProps {
+	/** An ID for the indicator element */
+	id?: string;
+	/** Classes for the indicator element */
+	class?: ClassValue;
+	/** Styles for the indicator element */
+	style?: StyleValue;
+}
+
+/**
+ * The bar of a Progress that fills the track in proportion to the current
+ * value, or animates while the progress is indeterminate.
+ */
+export default function ProgressIndicator($props: ProgressIndicatorProps | undefined) {
+	// Get stuff out of the Progress context
+	const context = $context[ProgressContextName] as ProgressContext;
+	if (!context) {
+		throw new Error("ProgressIndicator must be contained within a Progress");
+	}
+
+	function state(): "indeterminate" | "determinate" {
+		return context.isIndeterminate() ? "indeterminate" : "determinate";
+	}
+
+	function widthStyle(): string | undefined {
+		return context.isIndeterminate() ? undefined : `width: ${context.getPct()}%;`;
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-progress-bar", $props?.class]}
+			style={[widthStyle(), $props?.style]}
+			data-state={state()}
+		/>
+	}
+
+	@style {
+		/* Headless: layout only, so the bar fills the track proportionally.
+		   All appearance is up to the consuming theme */
+		.torp-progress-bar {
+			position: absolute;
+			inset: 0 auto 0 0;
+		}
+		.torp-progress-bar[data-state="indeterminate"] {
+			width: 100%;
+		}
+	}
+}

package/dist/Progress/ProgressTypes.ts

@@ -0,0 +1,8 @@
+export const ProgressContextName: unique symbol = Symbol.for("torp.Progress");
+
+export interface ProgressContext {
+	/** Whether the extent is unknown (no value was passed) */
+	isIndeterminate: () => boolean;
+	/** The percentage of the range that the value represents (0..100) */
+	getPct: () => number;
+}

package/dist/Progress/index.d.ts

@@ -25,6 +25,16 @@ interface ProgressProps {
  * specific value or as indeterminate when the extent is unknown.
  *
  * See [the WAI ARIA guidelines for Progress Bars](https://www.w3.org/WAI/ARIA/apg/patterns/progressbar/).
+ *
+ * The structure of a Progress is:
+ *
+ * ```
+ * <Progress>
+ * 	<ProgressIndicator />
+ * </Progress>
+ * ```
+ *
+ * With no children, the indicator is rendered automatically.
  */
 declare function Progress(
 	$parent: ParentNode,
@@ -34,4 +44,27 @@ declare function Progress(
 	$slots?: Record<string, SlotRender>,
 ): void;
 
-export { Progress };
+
+
+interface ProgressIndicatorProps {
+	/** An ID for the indicator element */
+	id?: string;
+	/** Classes for the indicator element */
+	class?: ClassValue;
+	/** Styles for the indicator element */
+	style?: StyleValue;
+}
+
+/**
+ * The bar of a Progress that fills the track in proportion to the current
+ * value, or animates while the progress is indeterminate.
+ */
+declare function ProgressIndicator(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: ProgressIndicatorProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { Progress, ProgressIndicator };

package/dist/Progress/index.js

@@ -1,2 +1,3 @@
 import Progress from "./Progress.torp";
-export { Progress };
+import ProgressIndicator from "./ProgressIndicator.torp";
+export { Progress, ProgressIndicator };

package/dist/Rating/Rating.torp

@@ -8,6 +8,8 @@ import {
 } from "../Form/FormTypes";
 import FormValues from "../Form/FormValues.torp";
 import createFormField from "../utils/formField";
+import RatingStar from "./RatingStar.torp";
+import { type RatingContext, RatingContextName } from "./RatingTypes";
 
 interface RatingProps {
 	/** An ID for the root element */
@@ -40,6 +42,16 @@ interface RatingProps {
  * 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/).
+ *
+ * The structure of a Rating is:
+ *
+ * ```
+ * <Rating>
+ * 	<RatingStar />
+ * </Rating>
+ * ```
+ *
+ * With no children, the stars are rendered automatically.
  */
 export default function Rating($props: RatingProps | undefined) {
 	let stars: (HTMLButtonElement | undefined)[] = [];
@@ -109,7 +121,29 @@ export default function Rating($props: RatingProps | undefined) {
 		return getDisabled() ? getValue() : Math.max(getValue(), $state.hover);
 	}
 
-	function handleClick(value: number) {
+	// Set the context to pass down to the stars
+	let context: RatingContext = {
+		getDisplayValue,
+		getDisabled,
+		isTabStop: (value) => value === ($state.value > 0 ? $state.value : 1),
+		isChecked: (value) => value === getValue(),
+		selectValue,
+		handleKey,
+		setHover: (value) => {
+			$state.hover = value;
+		},
+		registerStar: (value, el) => {
+			stars[value - 1] = el;
+		},
+		unregisterStar: (value, el) => {
+			if (stars[value - 1] === el) {
+				stars[value - 1] = undefined;
+			}
+		},
+	};
+	$context[RatingContextName] = context;
+
+	function selectValue(value: number) {
 		if (getDisabled()) return;
 		if (value === $state.value && ($props?.allowClear ?? true)) {
 			setValue(0);
@@ -159,12 +193,6 @@ export default function Rating($props: RatingProps | undefined) {
 		}
 	}
 
-	// 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}
@@ -180,36 +208,12 @@ export default function Rating($props: RatingProps | undefined) {
 			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">★</span>
-					</slot>
-				</button>
-			}
+			<slot>
+				@for (let value of $state.stars) {
+					@key = value
+					<RatingStar {value} />
+				}
+			</slot>
 		</div>
 
 		<FormValues name={form.name} value={getValue() > 0 ? getValue() : undefined} />

package/dist/Rating/RatingStar.torp

@@ -0,0 +1,71 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { type RatingContext, RatingContextName } from "./RatingTypes";
+
+interface RatingStarProps {
+	/** An ID for the star element */
+	id?: string;
+	/** Classes for the star element */
+	class?: ClassValue;
+	/** Styles for the star element */
+	style?: StyleValue;
+	/** The star's value (1-based position in the rating) */
+	value: number;
+}
+
+/**
+ * One star of a Rating, acting as a radio button. The star matching the
+ * current rating is checked, and the stars up to the rating (or the hovered
+ * star) are marked as filled.
+ *
+ * See [the WAI ARIA guidelines for Rating](https://www.w3.org/WAI/ARIA/apg/patterns/rating/).
+ */
+export default function RatingStar($props: RatingStarProps | undefined) {
+	// Get stuff out of the Rating context
+	const context = $context[RatingContextName] as RatingContext;
+	if (!context) {
+		throw new Error("RatingStar must be contained within a Rating");
+	}
+
+	function getValue(): number {
+		return $props?.value ?? 0;
+	}
+
+	function getDisabled(): boolean {
+		return context.getDisabled();
+	}
+
+	function label(): string {
+		const value = getValue();
+		return `${value} ${value === 1 ? "star" : "stars"}`;
+	}
+
+	@render {
+		<button
+			type="button"
+			{$props?.id}
+			class={["torp-rating-star", $props?.class]}
+			{$props?.style}
+			role="radio"
+			tabindex={context.isTabStop(getValue()) ? 0 : -1}
+			aria-checked={context.isChecked(getValue()) ? "true" : "false"}
+			aria-label={label()}
+			aria-disabled={getDisabled() ? "true" : undefined}
+			data-state={getValue() <= context.getDisplayValue() ? "filled" : "empty"}
+			onmount={(el) => {
+				context.registerStar(getValue(), el);
+				return () => {
+					context.unregisterStar(getValue(), el);
+				};
+			}}
+			onclick={() => context.selectValue(getValue())}
+			onkeydown={context.handleKey}
+			onmouseenter={() => {
+				if (!getDisabled()) context.setHover(getValue());
+			}}
+		>
+			<slot item={{ value: getValue(), filled: getValue() <= context.getDisplayValue() }}>
+				<span aria-hidden="true">★</span>
+			</slot>
+		</button>
+	}
+}

package/dist/Rating/RatingTypes.ts

@@ -0,0 +1,22 @@
+export const RatingContextName: unique symbol = Symbol.for("torp.Rating");
+
+export interface RatingContext {
+	/** The number of filled stars to display, taking the hovered star into account */
+	getDisplayValue: () => number;
+	/** Whether the user cannot interact with the rating */
+	getDisabled: () => boolean;
+	/** Whether the star is the single tab stop (roving tabindex) */
+	isTabStop: (value: number) => boolean;
+	/** Whether the star matches the current rating */
+	isChecked: (value: number) => boolean;
+	/** Selects a star, clearing the rating if it is already selected */
+	selectValue: (value: number) => void;
+	/** Handles arrow/Home/End keys on a star */
+	handleKey: (e: KeyboardEvent) => void;
+	/** Previews a rating while the pointer hovers a star */
+	setHover: (value: number) => void;
+	/** Called from a star when it is added */
+	registerStar: (value: number, el: HTMLButtonElement | undefined) => void;
+	/** Called from a star when it is removed */
+	unregisterStar: (value: number, el: HTMLButtonElement | undefined) => void;
+}

package/dist/Rating/index.d.ts

@@ -32,6 +32,16 @@ interface RatingProps {
  * 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/).
+ *
+ * The structure of a Rating is:
+ *
+ * ```
+ * <Rating>
+ * 	<RatingStar />
+ * </Rating>
+ * ```
+ *
+ * With no children, the stars are rendered automatically.
  */
 declare function Rating(
 	$parent: ParentNode,
@@ -41,4 +51,32 @@ declare function Rating(
 	$slots?: Record<string, SlotRender>,
 ): void;
 
-export { Rating };
+
+
+interface RatingStarProps {
+	/** An ID for the star element */
+	id?: string;
+	/** Classes for the star element */
+	class?: ClassValue;
+	/** Styles for the star element */
+	style?: StyleValue;
+	/** The star's value (1-based position in the rating) */
+	value: number;
+}
+
+/**
+ * One star of a Rating, acting as a radio button. The star matching the
+ * current rating is checked, and the stars up to the rating (or the hovered
+ * star) are marked as filled.
+ *
+ * See [the WAI ARIA guidelines for Rating](https://www.w3.org/WAI/ARIA/apg/patterns/rating/).
+ */
+declare function RatingStar(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: RatingStarProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { Rating, RatingStar };

package/dist/Rating/index.js

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

package/dist/Slider/Slider.torp

@@ -8,6 +8,9 @@ import {
 } from "../Form/FormTypes";
 import FormValues from "../Form/FormValues.torp";
 import createFormField from "../utils/formField";
+import SliderHandle from "./SliderHandle.torp";
+import SliderRange from "./SliderRange.torp";
+import { type SliderContext, SliderContextName } from "./SliderTypes";
 
 interface SliderProps {
 	/** An ID for the root element */
@@ -41,10 +44,21 @@ interface SliderProps {
  * 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/).
+ *
+ * The structure of a Slider is:
+ *
+ * ```
+ * <Slider>
+ * 	<SliderRange />
+ * 	<SliderHandle />
+ * </Slider>
+ * ```
+ *
+ * With no children, the range and handle are rendered automatically.
  */
 export default function Slider($props: SliderProps | undefined) {
 	let track: HTMLElement;
-	let thumb: HTMLElement;
+	let handle: HTMLElement | undefined;
 
 	// Wire up the enclosing Form and Field, if any
 	const form = createFormField(
@@ -116,6 +130,32 @@ export default function Slider($props: SliderProps | undefined) {
 		return false;
 	}
 
+	// Set the context to pass down to the range and handle
+	let context: SliderContext = {
+		getMin,
+		getMax,
+		getStep,
+		getOrientation,
+		getDisabled,
+		getValue,
+		getPct,
+		setValue,
+		getAriaLabel: () => $props?.ariaLabel,
+		registerHandle: (el) => {
+			handle = el;
+		},
+		unregisterHandle: (el) => {
+			if (handle === el) {
+				handle = undefined;
+			}
+		},
+		inField: () => form.inField,
+		valid: () => form.valid,
+		messageId: () => form.messageId,
+		handleBlur: () => form.handleBlur(),
+	};
+	$context[SliderContextName] = context;
+
 	// Convert a pointer position into a value along the track
 	function valueFromPointer(e: { clientX: number; clientY: number }): number {
 		const rect = track.getBoundingClientRect();
@@ -141,7 +181,7 @@ export default function Slider($props: SliderProps | undefined) {
 		e.preventDefault();
 		dragging = true;
 		setValue(valueFromPointer(e));
-		thumb.focus();
+		handle?.focus();
 		addEventListener("mousemove", handleMouseMove);
 		addEventListener("mouseup", handleMouseUp);
 	}
@@ -162,45 +202,6 @@ export default function Slider($props: SliderProps | undefined) {
 		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}
@@ -209,34 +210,18 @@ export default function Slider($props: SliderProps | undefined) {
 			onmousedown={handleMouseDown}
 			&ref={track}
 		>
-			<div class="torp-slider-fill" style={`${getOrientation() === "vertical" ? "height" : "width"}: ${getPct()}%;`} />
-			<div
-				class="torp-slider-thumb"
-				style={`position: absolute; transform: translate(-50%, -50%); ${getOrientation() === "vertical" ? `top: ${getPct()}%; left: 50%` : `left: ${getPct()}%; top: 50%`};`}
-				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}
-			/>
+			<slot>
+				<SliderRange />
+				<SliderHandle />
+			</slot>
 		</div>
 
 		<FormValues name={form.name} value={getValue()} />
 	}
 
 	@style {
-		/* Headless: all positioning is done with inline styles (so that theme
-		   CSS can't dislodge the thumb from the track). All appearance is up
-		   to the consuming theme */
+		/* Headless: layout only, so the range and handle position against the
+		   track. All appearance is up to the consuming theme */
 		.torp-slider {
 			position: relative;
 			touch-action: none;

package/dist/Slider/SliderHandle.torp

@@ -0,0 +1,107 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { type SliderContext, SliderContextName } from "./SliderTypes";
+
+interface SliderHandleProps {
+	/** An ID for the handle element */
+	id?: string;
+	/** Classes for the handle element */
+	class?: ClassValue;
+	/** Styles for the handle element */
+	style?: StyleValue;
+	/** An accessible name for the slider; falls back to the Slider's ariaLabel */
+	ariaLabel?: string;
+	/** If set to true, the user cannot interact with this handle */
+	disabled?: boolean;
+}
+
+/**
+ * The thumb of a Slider that the user drags along the track, or moves with
+ * the keyboard. It carries `role="slider"` and all of the slider's ARIA
+ * value attributes.
+ *
+ * See [the WAI ARIA guidelines for Sliders](https://www.w3.org/WAI/ARIA/apg/patterns/slider/).
+ */
+export default function SliderHandle($props: SliderHandleProps | undefined) {
+	// Get stuff out of the Slider context
+	const context = $context[SliderContextName] as SliderContext;
+	if (!context) {
+		throw new Error("SliderHandle must be contained within a Slider");
+	}
+
+	function getDisabled(): boolean {
+		return $props?.disabled === true || context.getDisabled();
+	}
+
+	function positionStyle(): string {
+		if (context.getOrientation() === "vertical") {
+			return `position: absolute; transform: translate(-50%, -50%); top: ${context.getPct()}%; left: 50%;`;
+		}
+		return `position: absolute; transform: translate(-50%, -50%); left: ${context.getPct()}%; top: 50%;`;
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		if (getDisabled()) return;
+
+		switch (e.key) {
+			case "ArrowRight":
+			case "ArrowUp": {
+				e.preventDefault();
+				context.setValue(context.getValue() + context.getStep());
+				break;
+			}
+			case "ArrowLeft":
+			case "ArrowDown": {
+				e.preventDefault();
+				context.setValue(context.getValue() - context.getStep());
+				break;
+			}
+			case "PageUp": {
+				e.preventDefault();
+				context.setValue(context.getValue() + context.getStep() * 10);
+				break;
+			}
+			case "PageDown": {
+				e.preventDefault();
+				context.setValue(context.getValue() - context.getStep() * 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-slider-thumb", $props?.class]}
+			style={[positionStyle(), $props?.style]}
+			role="slider"
+			tabindex={getDisabled() ? -1 : 0}
+			aria-orientation={context.getOrientation()}
+			aria-valuemin={context.getMin()}
+			aria-valuemax={context.getMax()}
+			aria-valuenow={context.getValue()}
+			aria-label={$props?.ariaLabel ?? context.getAriaLabel()}
+			aria-disabled={getDisabled() ? "true" : undefined}
+			data-valid={context.valid() ? "valid" : "invalid"}
+			aria-describedby={context.messageId()}
+			aria-invalid={context.inField() && !context.valid() ? "true" : undefined}
+			onblur={() => context.handleBlur()}
+			onkeydown={handleKey}
+			onmount={(el) => {
+				context.registerHandle(el);
+				return () => {
+					context.unregisterHandle(el);
+				};
+			}}
+		/>
+	}
+}

package/dist/Slider/SliderRange.torp

@@ -0,0 +1,36 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { type SliderContext, SliderContextName } from "./SliderTypes";
+
+interface SliderRangeProps {
+	/** An ID for the range element */
+	id?: string;
+	/** Classes for the range element */
+	class?: ClassValue;
+	/** Styles for the range element */
+	style?: StyleValue;
+}
+
+/**
+ * The filled portion of a Slider, from the start of the track to the
+ * current value.
+ */
+export default function SliderRange($props: SliderRangeProps | undefined) {
+	// Get stuff out of the Slider context
+	const context = $context[SliderContextName] as SliderContext;
+	if (!context) {
+		throw new Error("SliderRange must be contained within a Slider");
+	}
+
+	function fillStyle(): string {
+		const property = context.getOrientation() === "vertical" ? "height" : "width";
+		return `${property}: ${context.getPct()}%;`;
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-slider-fill", $props?.class]}
+			style={[fillStyle(), $props?.style]}
+		/>
+	}
+}