@torpor/ui 0.3.7 → 1.0.0

package/README.md

@@ -2,15 +2,91 @@
 
 Accessible, unstyled components for use in your Torpor front-end.
 
-🚧 WARNING: WORK IN PROGRESS 🚧
+Each component is exported as a separate subpath (e.g.
+`@torpor/ui/Accordion`) and is bundled with sensible behavior and ARIA
+attributes, while styling is left up to you.
 
-## Features
+## Installation
+
+```bash
+npm install @torpor/ui
+```
+
+## Usage
+
+```torp
+import {
+	Accordion,
+	AccordionContent,
+	AccordionHeader,
+	AccordionItem,
+	AccordionTrigger,
+} from "@torpor/ui/Accordion";
+
+@render {
+	<Accordion>
+		<AccordionItem>
+			<AccordionHeader>
+				<AccordionTrigger>Header 1</AccordionTrigger>
+			</AccordionHeader>
+			<AccordionContent>Content 1</AccordionContent>
+		</AccordionItem>
+	</Accordion>
+}
+```
+
+## Components
 
 - Accordion
-- motion
-  - fade
+- Breadcrumb
+- Calendar
+- Carousel
+- Charts
+- ColorPicker
+- ComboBox
+- CommandPalette
+- Contextual
+- DataGrid
+- DatePicker
+- DateRangePicker
+- Dialog
+- Disclosure
+- Drawer
+- FocusGroup
+- Form
+- icons
+- ListBox
+- MaskedInput
+- Menu
+- MenuBar
+- Modal
+- NavMenu
+- Notification
+- NumberInput
+- Pagination
+- Popover
+- Progress
+- Rating
+- SegmentedControl
+- SelectBox
+- Slider
+- Splitter
+- Stepper
+- TabGroup
+- TagInput
+- TimePicker
+- ToolBar
+- Tree
+
+## Motion
+
+Transition helpers for use with the `transition` / `transition-in` /
+`transition-out` directives (see [torpor/view](../view)), exported from
+`@torpor/ui/motion`:
 
-## Not yet
+- `fade`
+- `grow`
+- `slide`
 
-- Forms, validation etc
-- Utility functions e.g. intersection observer
+Plus `measure`, a utility for measuring an element before it is added to the
+DOM (used by `grow` and `slide`).

package/dist/Accordion/Accordion.torp

@@ -1,21 +1,24 @@
-import type { ClassValue, StyleValue } from "@torpor/view";
-import { AccordionContextName, type AccordionContext, type ItemState } from "./AccordionTypes";
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import $handle from "../utils/$handle";
+import { type AccordionContext, AccordionContextName, type ItemState } from "./AccordionTypes";
+import { createItemGroup } from "../utils/createItemGroup";
+import { focusItem } from "../utils/focusItem";
 
 interface AccordionProps {
 	/** 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;
 	/** Whether a single AccordionItem or multiple AccordionItems can be expanded at the same time */
-	type?: "single" | "multiple",
+	type?: "single" | "multiple";
 	/** The value of the expanded AccordionItem, or an array of values if the type is "multiple" */
-	value?: string | string[],
+	value?: Bindable<any | any[]>;
 	/** If set to true, the user cannot interact with any items in the Accordion */
-	disabled?: boolean,
+	disabled?: boolean;
 	/** Raised when the expanded item(s) have changed */
-	onchange?: (value: string | string[]) => void,
+	onchange?: (value: any | any[]) => void;
 }
 
 /**
@@ -38,192 +41,67 @@ interface AccordionProps {
  * ```
  */
 export default function Accordion($props: AccordionProps | undefined) {
-	let type = $props?.type ?? "single";
-
 	let $state = $watch({
-		value: $props?.value ?? (type === "single" ? "" : [] as string[])
-	});
-
-	$run(() => {
-		if ($props !== undefined) {
-			$props.value = $state.value;
-		}
+		value: $props?.value ?? (($props?.type ?? "single") === "single" ? undefined : []),
 	});
 
-	let itemStates: ItemState[] = [];
-
-	// This is used to assign automatic indexes to items where needed
-	let nextIndex = 0;
-
-	// Set the context to pass down to items, with functions for each item to call
-	let context: AccordionContext = {
-		registerItem,
-		removeItem,
-		toggleItem,
-		handleHeaderKey
-	};
-	$context[AccordionContextName] = context;
-
-	$run(() => {
-		// HACK: This should probably be done with setters?
-		let newValue = $state.value;
-
-		// Get the value
-		switch (type) {
-			case "single": {
-				// Ensure the value passed in was a string (in case e.g. the user has set values to ints)
-				newValue = newValue.toString();
-				for (let item of itemStates) {
-					item.expanded = item.value === newValue;
-				}
-				break;
-			}
-			case "multiple": {
-				// Ensure the value passed in is an array
-				if (!Array.isArray(newValue)) {
-					newValue = [newValue];
-				}
-				for (let item of itemStates) {
-					item.expanded = newValue.indexOf(item.value) !== -1;
-				}
-				break;
-			}
-		}
-
-		// Set the value
-		$state.value = newValue;
-	})
-
-	$run(() => {
-		itemStates.forEach((s) => s.parentDisabled = $props?.disabled === true);
-	});
+	$bind($state, $props, "value");
 
 	// Dispatch the change event when the value changes
-	let firstChange = true;
-	$run(() => {
-		const ev = $props?.onchange;
+	$handle((first) => {
 		const value = $state.value;
-		if (firstChange) {
-			firstChange = false;
-		} else if (ev) {
-			ev(value);
-		}
+		if (!first) $props?.onchange?.(value);
 	});
 
-	function registerItem(itemState: ItemState) {
-		// If an index wasn't set for the item, set it automatically
-		if (itemState.index === -1) {
-			itemState.index = nextIndex++;
-		}
-
-		// If a value wasn't set for the item, set it to the index
-		if (!itemState.value) {
-			itemState.value = itemState.index.toString();
-		}
-
-		// If we have a value, set whether the item should be expanded
-		if ($state.value) {
-			switch (type) {
-				case "single": {
-					itemState.expanded = $state.value === itemState.value;
-					break;
-				}
-				case "multiple": {
-					itemState.expanded = $state.value.includes(itemState.value);
-					break;
-				}
+	const group = createItemGroup<ItemState>({
+		state: $state,
+		type: () => $props?.type ?? "single",
+		selectedProperty: "expanded",
+		disabled: () => $props?.disabled,
+		onRegister: (item) => {
+			if (!item.value) {
+				item.value = item.index;
 			}
-		}
-
-		// Set whether the Accordion itself is disabled
-		itemState.parentDisabled = $props?.disabled === true
-
-		// Add the item's state to the array
-		itemStates.splice(itemState.index, 0, itemState);
-	}
-
-	// 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 toggleItem(toggleValue: string) {
-		switch (type) {
-			case "single": {
-				for (let item of itemStates) {
-					// The item is expanded if it has the supplied value (i.e. if it was clicked) and if it
-					// wasn't already expanded (i.e. we collapse it if it was expanded and clicked)
-					if (item.value === toggleValue) {
-						$state.value = item.expanded ? "" : item.value;
-						break;
-					}
-				}
-				break;
-			}
-			case "multiple": {
-				let newValue = [];
-				for (let item of itemStates) {
-					// The item is expanded if it has the supplied value (i.e. if it was clicked) or if it
-					// was already expanded
-					if (
-						(item.value === toggleValue && !item.expanded) ||
-						(item.value !== toggleValue && item.expanded)
-					) {
-						newValue.push(item.value);
-					}
-				}
-				$state.value = newValue.sort();
-				break;
-			}
-		}
-	}
+	// Set the context to pass down to items, with functions for each item to call
+	let context: AccordionContext = {
+		registerItem: (state: ItemState) => group.registerItem(state),
+		removeItem: group.removeItem,
+		toggleItem: group.toggleItem,
+		handleHeaderKey,
+	};
+	$context[AccordionContextName] = context;
 
 	function handleHeaderKey(headerIndex: number, e: KeyboardEvent) {
+		const itemStates = group.itemStates;
 		switch (e.key) {
-			case "Up":
 			case "ArrowUp": {
-				if (headerIndex > 0) {
-					e.preventDefault();
-					itemStates[headerIndex - 1].setFocused();
-				}
+				e.preventDefault();
+				focusItem(itemStates, headerIndex, "previous");
 				break;
 			}
-			case "Down":
 			case "ArrowDown": {
-				if (headerIndex < itemStates.length - 1) {
-					e.preventDefault();
-					itemStates[headerIndex + 1].setFocused();
-				}
+				e.preventDefault();
+				focusItem(itemStates, headerIndex, "next");
 				break;
 			}
 			case "Home": {
-				if (headerIndex > 0) {
-					e.preventDefault();
-					itemStates[0].setFocused();
-				}
+				e.preventDefault();
+				focusItem(itemStates, headerIndex, "start");
 				break;
 			}
 			case "End": {
-				if (headerIndex < itemStates.length - 1) {
-					e.preventDefault();
-					itemStates[itemStates.length - 1].setFocused();
-				}
+				e.preventDefault();
+				focusItem(itemStates, headerIndex, "end");
 				break;
 			}
 		}
 	}
 
 	@render {
-		<div
-			{$props?.id}
-			class={["torp-accordion", $props?.class]}
-			{$props?.style}
-		>
+		<div {$props?.id} class={["torp-accordion", $props?.class]} {$props?.style}>
 			<slot />
 		</div>
 	}

package/dist/Accordion/AccordionContent.torp

@@ -1,16 +1,16 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
 import getId from "../utils/getId";
-import { AccordionItemContextName, type AccordionItemContext } from "./AccordionTypes";
+import { type AccordionItemContext, AccordionItemContextName } from "./AccordionTypes";
 
 interface AccordionContentProps {
 	/** 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;
 	/** Whether this content should act as a region. Set this when the content contains heading elements or a nested Accordion */
-	ariaRegion?: boolean,
+	ariaRegion?: boolean;
 }
 
 /**
@@ -23,7 +23,7 @@ export default function AccordionContent($props: AccordionContentProps | undefin
 	if (!context) {
 		throw new Error("AccordionContent must be contained within an AccordionItem");
 	}
-	let $state = context.state
+	let $state = context.state;
 
 	// Set the content ID so that it can be used with aria-controls in AccordionTrigger
 	$state.contentId = $props?.id ?? defaultId;
@@ -35,8 +35,8 @@ export default function AccordionContent($props: AccordionContentProps | undefin
 			{$props?.style}
 			role={$props?.ariaRegion ? "region" : undefined}
 			aria-labelledby={$state.headerId}
+			aria-hidden={$state.expanded ? undefined : "true"}
 			data-state={$state.expanded ? "open" : "closed"}
-			data-disabled={$state.disabled ? "true" : undefined}
 		>
 			@if ($state.expanded) {
 				<slot />

package/dist/Accordion/AccordionHeader.torp

@@ -1,22 +1,20 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { AccordionItemContextName, type AccordionItemContext } from "./AccordionTypes";
+import { type AccordionItemContext, AccordionItemContextName } from "./AccordionTypes";
 
 interface AccordionHeaderProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
-	/** The type of HTML header to use */
-	as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6",
+	style?: StyleValue;
 }
 
 /**
  * The header for an AccordionItem, which contains the AccordionTrigger.
  *
  * The structure of an AccordionHeader is:
- * 
+ *
  * ```
  * <AccordionHeader>
  * 	<AccordionTrigger />
@@ -28,18 +26,16 @@ export default function AccordionHeader($props: AccordionHeaderProps | undefined
 	if (!context) {
 		throw new Error("AccordionHeader must be contained within an AccordionItem");
 	}
-	let $state = context.state
+	let $state = context.state;
 
 	@render {
-		@// TODO: $props.as
-		<h4
+		<div
 			{$props?.id}
 			class={["torp-accordion-header", $props?.class]}
 			{$props?.style}
 			data-state={$state.expanded ? "open" : "closed"}
-			data-disabled={$state.disabled ? "true" : undefined}
 		>
 			<slot />
-		</h4>
+		</div>
 	}
 }

package/dist/Accordion/AccordionItem.torp

@@ -1,28 +1,35 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import { AccordionContextName, AccordionItemContextName, type ItemState, type AccordionContext, type AccordionItemContext } from "./AccordionTypes";
+import $handle from "../utils/$handle";
+import {
+	type AccordionContext,
+	AccordionContextName,
+	type AccordionItemContext,
+	AccordionItemContextName,
+	type ItemState,
+} from "./AccordionTypes";
 
 interface AccordionItemProps {
 	/** 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 in the Accordion. Set this if you will be inserting, removing or sorting items. If you don't set this, it will be set automatically */
-	index?: number,
+	index?: number;
 	/** A value for the item. Set this if you need more control over which item(s) are expanded. If you don't set this, the value will be set to the item's initial index */
-	value?: string,
+	value?: any;
 	/** If set to true, the user cannot interact with this AccordionItem */
-	disabled?: boolean,
+	disabled?: boolean;
 	/** Raised when this item is opened or closed */
-	ontoggle?: (open: boolean) => void,
+	onchange?: (open: boolean) => void;
 }
 
 /**
  * An item in an Accordion, which must consist of an AccordionTrigger and an AccordionContent.
- * 
+ *
  * The structure of an AccordionItem is:
- * 
+ *
  * ```
  * <AccordionItem>
  * 	<AccordionHeader>
@@ -35,14 +42,14 @@ interface AccordionItemProps {
 export default function AccordionItem($props: AccordionItemProps | undefined) {
 	let $state: ItemState = $watch({
 		index: -1,
-		value: "",
+		value: $props?.value,
 		expanded: false,
 		headerId: "",
 		contentId: "",
 		disabled: $props?.disabled ?? false,
 		parentDisabled: false,
-		setFocused
-	})
+		setFocused,
+	});
 
 	// Get stuff out of the AccordionContext
 	const context = $context[AccordionContextName] as AccordionContext;
@@ -59,25 +66,19 @@ export default function AccordionItem($props: AccordionItemProps | undefined) {
 	$context[AccordionItemContextName] = itemContext;
 
 	// Register this item with the parent Accordion, which will handle toggling expanded for all items
-	context.registerItem($state, setFocused);
+	context.registerItem($state);
 
 	// Remove the item from the parent Accordion when this item is destroyed
 	$run(() => {
 		return () => {
 			context.removeItem($state.index);
-		}
+		};
 	});
 
-	// Dispatch the toggle event when the value of expanded changes
-	let firstToggle = true;
-	$run(() => {
-		const ev = $props?.ontoggle;
+	// Dispatch the change event when the value of expanded changes
+	$handle((first) => {
 		const expanded = $state.expanded;
-		if (firstToggle) {
-			firstToggle = false;
-		} else if (ev) {
-			ev(expanded);
-		}
+		if (!first) $props?.onchange?.(expanded);
 	});
 
 	// Called from the parent Accordion; pass the focus command along to the AccordionButton
@@ -93,7 +94,6 @@ export default function AccordionItem($props: AccordionItemProps | undefined) {
 			class={["torp-accordion-item", $props?.class]}
 			{$props?.style}
 			data-state={$state.expanded ? "open" : "closed"}
-			data-disabled={$state.disabled ? "true" : undefined}
 		>
 			<slot />
 		</div>

package/dist/Accordion/AccordionTrigger.torp

@@ -1,14 +1,14 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
 import getId from "../utils/getId";
-import { AccordionItemContextName, type AccordionItemContext } from "./AccordionTypes";
+import { type AccordionItemContext, AccordionItemContextName } from "./AccordionTypes";
 
 interface AccordionTriggerProps {
 	/** 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;
 }
 
 /**
@@ -44,8 +44,18 @@ export default function AccordionTrigger($props: AccordionTriggerProps | undefin
 	}
 
 	function handleKey(e: KeyboardEvent) {
-		// Pass the key press up to the parent Accordion which will handle setting the focused button
-		context.handleHeaderKey($state.index, e);
+		switch (e.key) {
+			case "Enter":
+			case " ": {
+				e.preventDefault();
+				handleClick();
+				break;
+			}
+			default: {
+				// Pass the key press up to the parent Accordion which will handle setting the focused button
+				context.handleHeaderKey($state.index, e);
+			}
+		}
 	}
 
 	@render {
@@ -55,11 +65,10 @@ export default function AccordionTrigger($props: AccordionTriggerProps | undefin
 			class={["torp-accordion-trigger", $props?.class]}
 			{$props?.style}
 			disabled={$state.disabled || $state.parentDisabled}
-			aria-expanded={$state.expanded.toString()}
-			aria-disabled={$state.disabled ? "true" : undefined}
+			aria-expanded={$state.expanded ? "true" : "false"}
+			aria-disabled={$state.disabled || $state.parentDisabled ? "true" : undefined}
 			aria-controls={$state.contentId}
 			data-state={$state.expanded ? "open" : "closed"}
-			data-disabled={$state.disabled ? "true" : undefined}
 			&ref={button}
 			onclick={handleClick}
 			onkeydown={handleKey}

package/dist/Accordion/AccordionTypes.ts

@@ -1,20 +1,20 @@
-export const AccordionContextName = "Accordion";
-export const AccordionItemContextName = "AccordionItem";
+export const AccordionContextName: unique symbol = Symbol.for("torp.Accordion");
+export const AccordionItemContextName: unique symbol = Symbol.for("torp.AccordionItem");
 
 export interface AccordionContext {
 	/** Called from an AccordionItem when it is added */
-	registerItem: (state: ItemState, setFocused: () => void) => void;
+	registerItem: (state: ItemState) => void;
 	/** Called from an AccordionItem when it is removed */
 	removeItem: (index: number) => void;
 	/** Called from an AccordionItem when it is toggled */
-	toggleItem: (value: string) => void;
+	toggleItem: (value: any) => void;
 	/** Called from an AccordionHeader when it receives a keyboard event */
 	handleHeaderKey: (index: number, e: KeyboardEvent) => void;
 }
 
 export interface AccordionItemContext {
 	/** Raised when an AccordionItem is toggled */
-	toggleItem: (value: string) => void;
+	toggleItem: (value: any) => void;
 	/** Raised when an AccordionHeader receives a keyboard event */
 	handleHeaderKey: (index: number, e: KeyboardEvent) => void;
 	/** The reactive state for an AccordionItem */
@@ -25,7 +25,7 @@ export interface AccordionItemContext {
 
 export interface ItemState {
 	index: number;
-	value: string;
+	value: any;
 	expanded: boolean;
 	headerId: string;
 	contentId: string;