@torpor/ui 0.4.0 → 1.0.0

package/dist/Carousel/Carousel.torp

@@ -0,0 +1,180 @@
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import $handle from "../utils/$handle";
+import { type CarouselContext, CarouselContextName } from "./CarouselTypes";
+
+interface CarouselProps {
+	/** 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 active slide */
+	value?: Bindable<number>;
+	/** Whether the next and previous controls wrap around at the ends (default true) */
+	wrap?: boolean;
+	/** An accessible label for the carousel region */
+	ariaLabel?: string;
+	/** Raised when the active slide has changed */
+	onchange?: (index: number) => void;
+}
+
+/**
+ * A carousel that displays a sequence of slides, which the user can move
+ * between with previous and next controls, slide indicators, or the keyboard.
+ *
+ * See [the WAI ARIA guidelines for Carousels](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/).
+ *
+ * The structure of a Carousel is:
+ *
+ * ```
+ * <Carousel ariaLabel="Featured">
+ * 	<CarouselPrevious />
+ * 	<CarouselSlide>...</CarouselSlide>
+ * 	<CarouselSlide>...</CarouselSlide>
+ * 	<CarouselNext />
+ * 	<CarouselIndicators />
+ * </Carousel>
+ * ```
+ */
+export default function Carousel($props: CarouselProps | undefined) {
+	let $state = $watch({
+		value: 0,
+		slides: [] as SlideStateLite[],
+	});
+
+	interface SlideStateLite {
+		index: number;
+	}
+
+	$bind($state, $props, "value");
+
+	// Set the context to pass down to slides and controls
+	const context: CarouselContext = {
+		registerSlide,
+		removeSlide,
+		goToSlide,
+		nextSlide,
+		previousSlide,
+		isActive,
+		canNext,
+		canPrevious,
+		slides: () => $state.slides,
+		count: () => $state.slides.length,
+	};
+	$context[CarouselContextName] = context;
+
+	// Dispatch the change event when the active slide changes
+	$handle((first) => {
+		const value = getValue();
+		if (!first) $props?.onchange?.(value);
+	});
+
+	function getWrap(): boolean {
+		return $props?.wrap !== false;
+	}
+
+	// The clamped index that is displayed and reported to assistive tech
+	function getValue(): number {
+		const last = Math.max(0, $state.slides.length - 1);
+		return Math.min(last, Math.max(0, $state.value));
+	}
+
+	function isActive(index: number): boolean {
+		return getValue() === index;
+	}
+
+	function canNext(): boolean {
+		if ($state.slides.length < 2) return false;
+		return getWrap() || getValue() < $state.slides.length - 1;
+	}
+
+	function canPrevious(): boolean {
+		if ($state.slides.length < 2) return false;
+		return getWrap() || getValue() > 0;
+	}
+
+	function goToSlide(index: number) {
+		const last = Math.max(0, $state.slides.length - 1);
+		$state.value = Math.min(last, Math.max(0, index));
+	}
+
+	function nextSlide() {
+		const count = $state.slides.length;
+		if (count < 2) return;
+		if (getWrap()) {
+			goToSlide((getValue() + 1) % count);
+		} else {
+			goToSlide(getValue() + 1);
+		}
+	}
+
+	function previousSlide() {
+		const count = $state.slides.length;
+		if (count < 2) return;
+		if (getWrap()) {
+			goToSlide((getValue() - 1 + count) % count);
+		} else {
+			goToSlide(getValue() - 1);
+		}
+	}
+
+	function registerSlide(): SlideStateLite {
+		const state: SlideStateLite = $watch({ index: $state.slides.length });
+		$state.slides.push(state);
+		return state;
+	}
+
+	function removeSlide(index: number) {
+		if (index >= 0 && index < $state.slides.length) {
+			$state.slides.splice(index, 1);
+		}
+		$state.slides.forEach((slide, i) => (slide.index = i));
+	}
+
+	// The keyboard interface is the previous / next controls; arrow keys also
+	// work when focus is on the region or a slide, but never when it is on an
+	// interactive element inside the carousel
+	function handleKey(e: KeyboardEvent) {
+		const target = e.target as HTMLElement;
+		if (target.closest("button, a, input, select, textarea, [contenteditable]")) {
+			return;
+		}
+		switch (e.key) {
+			case "ArrowRight": {
+				e.preventDefault();
+				nextSlide();
+				break;
+			}
+			case "ArrowLeft": {
+				e.preventDefault();
+				previousSlide();
+				break;
+			}
+			case "Home": {
+				e.preventDefault();
+				goToSlide(0);
+				break;
+			}
+			case "End": {
+				e.preventDefault();
+				goToSlide($state.slides.length - 1);
+				break;
+			}
+		}
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-carousel", $props?.class]}
+			{$props?.style}
+			role="region"
+			aria-roledescription="carousel"
+			aria-label={$props?.ariaLabel ?? "Carousel"}
+			onkeydown={handleKey}
+		>
+			<slot />
+		</div>
+	}
+}

package/dist/Carousel/CarouselIndicators.torp

@@ -0,0 +1,65 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { type CarouselContext, CarouselContextName } from "./CarouselTypes";
+
+interface CarouselIndicatorsProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+}
+
+/**
+ * A series of buttons in a Carousel, one per slide, that a user can press to
+ * move directly to that slide.
+ */
+export default function CarouselIndicators($props: CarouselIndicatorsProps | undefined) {
+	// Get stuff out of the Carousel context
+	const context = $context[CarouselContextName] as CarouselContext;
+	if (!context) {
+		throw new Error("CarouselIndicators must be contained within a Carousel");
+	}
+
+	let $state = $watch({
+		get slides() {
+			return context.slides();
+		},
+	});
+
+	function indicatorLabel(index: number): string {
+		return `Go to slide ${index + 1}`;
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-carousel-indicators", $props?.class]}
+			{$props?.style}
+		>
+			@for (let slide of $state.slides) {
+				@key = slide.index
+				<button
+					type="button"
+					class="torp-carousel-indicator"
+					aria-label={indicatorLabel(slide.index)}
+					aria-current={context.isActive(slide.index) ? "true" : undefined}
+					data-state={context.isActive(slide.index) ? "active" : "inactive"}
+					onclick={() => context.goToSlide(slide.index)}
+				>
+					<slot item={{ index: slide.index, active: context.isActive(slide.index) }}>
+						<span aria-hidden="true" />
+					</slot>
+				</button>
+			}
+		</div>
+	}
+
+	@style {
+		/* Headless: layout only, so the indicators sit in a row. All appearance
+		   is up to the consuming theme */
+		.torp-carousel-indicators {
+			display: flex;
+		}
+	}
+}

package/dist/Carousel/CarouselNext.torp

@@ -0,0 +1,43 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import ChevronRight from "../icons/ChevronRight.torp";
+import { type CarouselContext, CarouselContextName } from "./CarouselTypes";
+
+interface CarouselNextProps {
+	/** 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 Carousel that a user can press to move to the next slide.
+ */
+export default function CarouselNext($props: CarouselNextProps | undefined) {
+	// Get stuff out of the Carousel context
+	const context = $context[CarouselContextName] as CarouselContext;
+	if (!context) {
+		throw new Error("CarouselNext must be contained within a Carousel");
+	}
+
+	@render {
+		<button
+			{$props?.id}
+			class={["torp-carousel-next", $props?.class]}
+			{$props?.style}
+			type="button"
+			aria-label={$props?.ariaLabel ?? "Next slide"}
+			disabled={$props?.disabled || !context.canNext()}
+			onclick={() => context.nextSlide()}
+		>
+			<slot>
+				<ChevronRight />
+			</slot>
+		</button>
+	}
+}

package/dist/Carousel/CarouselPrevious.torp

@@ -0,0 +1,44 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import ChevronLeft from "../icons/ChevronLeft.torp";
+import { type CarouselContext, CarouselContextName } from "./CarouselTypes";
+
+interface CarouselPreviousProps {
+	/** 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 Carousel that a user can press to move to the previous
+ * slide.
+ */
+export default function CarouselPrevious($props: CarouselPreviousProps | undefined) {
+	// Get stuff out of the Carousel context
+	const context = $context[CarouselContextName] as CarouselContext;
+	if (!context) {
+		throw new Error("CarouselPrevious must be contained within a Carousel");
+	}
+
+	@render {
+		<button
+			{$props?.id}
+			class={["torp-carousel-previous", $props?.class]}
+			{$props?.style}
+			type="button"
+			aria-label={$props?.ariaLabel ?? "Previous slide"}
+			disabled={$props?.disabled || !context.canPrevious()}
+			onclick={() => context.previousSlide()}
+		>
+			<slot>
+				<ChevronLeft />
+			</slot>
+		</button>
+	}
+}

package/dist/Carousel/CarouselSlide.torp

@@ -0,0 +1,57 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { type CarouselContext, CarouselContextName } from "./CarouselTypes";
+
+interface CarouselSlideProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** An accessible label for the slide; defaults to "n of m" */
+	ariaLabel?: string;
+}
+
+/**
+ * A slide in a Carousel, only one of which is visible at a time.
+ */
+export default function CarouselSlide($props: CarouselSlideProps | undefined) {
+	// Get stuff out of the Carousel context
+	const context = $context[CarouselContextName] as CarouselContext;
+	if (!context) {
+		throw new Error("CarouselSlide must be contained within a Carousel");
+	}
+
+	// Register this slide with the parent Carousel
+	let $state = context.registerSlide();
+
+	$run(() => {
+		return () => {
+			context.removeSlide($state.index);
+		};
+	});
+
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-carousel-slide", $props?.class]}
+			{$props?.style}
+			role="group"
+			aria-roledescription="slide"
+			aria-label={$props?.ariaLabel ?? `${$state.index + 1} of ${context.count()}`}
+			data-state={context.isActive($state.index) ? "active" : "inactive"}
+		>
+			@if (context.isActive($state.index)) {
+				<slot />
+			}
+		</div>
+	}
+
+	@style {
+		/* Headless: inactive slides are hidden from display and the accessibility
+		   tree. All other appearance is up to the consuming theme */
+		.torp-carousel-slide[data-state="inactive"] {
+			display: none;
+		}
+	}
+}

package/dist/Carousel/CarouselTypes.ts

@@ -0,0 +1,28 @@
+export const CarouselContextName: unique symbol = Symbol.for("torp.Carousel");
+
+export interface SlideState {
+	/** The index of the slide */
+	index: number;
+}
+
+export interface CarouselContext {
+	/** Called from a slide when it is added */
+	registerSlide: () => SlideState;
+	/** Called from a slide when it is removed */
+	removeSlide: (index: number) => void;
+	/** Moves to the slide at the given index */
+	goToSlide: (index: number) => void;
+	/** Moves to the next slide */
+	nextSlide: () => void;
+	/** Moves to the previous slide */
+	previousSlide: () => void;
+	/** Whether the slide at the given index is the active one */
+	isActive: (index: number) => boolean;
+	/** Whether the next / previous controls can move from the current slide */
+	canNext: () => boolean;
+	canPrevious: () => boolean;
+	/** The reactive list of registered slides */
+	slides: () => SlideState[];
+	/** The number of registered slides */
+	count: () => number;
+}

package/dist/Carousel/index.d.ts

@@ -0,0 +1,147 @@
+import { type SlotRender } from "@torpor/view";
+
+
+interface CarouselProps {
+	/** 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 active slide */
+	value?: Bindable<number>;
+	/** Whether the next and previous controls wrap around at the ends (default true) */
+	wrap?: boolean;
+	/** An accessible label for the carousel region */
+	ariaLabel?: string;
+	/** Raised when the active slide has changed */
+	onchange?: (index: number) => void;
+}
+
+/**
+ * A carousel that displays a sequence of slides, which the user can move
+ * between with previous and next controls, slide indicators, or the keyboard.
+ *
+ * See [the WAI ARIA guidelines for Carousels](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/).
+ *
+ * The structure of a Carousel is:
+ *
+ * ```
+ * <Carousel ariaLabel="Featured">
+ * 	<CarouselPrevious />
+ * 	<CarouselSlide>...</CarouselSlide>
+ * 	<CarouselSlide>...</CarouselSlide>
+ * 	<CarouselNext />
+ * 	<CarouselIndicators />
+ * </Carousel>
+ * ```
+ */
+declare function Carousel(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: CarouselProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface CarouselIndicatorsProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+}
+
+/**
+ * A series of buttons in a Carousel, one per slide, that a user can press to
+ * move directly to that slide.
+ */
+declare function CarouselIndicators(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: CarouselIndicatorsProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface CarouselNextProps {
+	/** 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 Carousel that a user can press to move to the next slide.
+ */
+declare function CarouselNext(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: CarouselNextProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface CarouselPreviousProps {
+	/** 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 Carousel that a user can press to move to the previous
+ * slide.
+ */
+declare function CarouselPrevious(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: CarouselPreviousProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface CarouselSlideProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** An accessible label for the slide; defaults to "n of m" */
+	ariaLabel?: string;
+}
+
+/**
+ * A slide in a Carousel, only one of which is visible at a time.
+ */
+declare function CarouselSlide(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: CarouselSlideProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+export { Carousel, CarouselIndicators, CarouselNext, CarouselPrevious, CarouselSlide };

package/dist/Carousel/index.js

@@ -0,0 +1,6 @@
+import Carousel from "./Carousel.torp";
+import CarouselIndicators from "./CarouselIndicators.torp";
+import CarouselNext from "./CarouselNext.torp";
+import CarouselPrevious from "./CarouselPrevious.torp";
+import CarouselSlide from "./CarouselSlide.torp";
+export { Carousel, CarouselIndicators, CarouselNext, CarouselPrevious, CarouselSlide };