@torpor/ui 0.2.0 → 0.3.0

package/dist/Breadcrumb/Breadcrumb.torp

@@ -1,4 +1,13 @@
 
+interface BreadcrumbProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** An ARIA label for describing the popover to screen readers  */
+	ariaLabel?: string | undefined,
+}
+
 /**
  *
  * A list of links to the parent pages of the current page in hierarchical order.
@@ -9,23 +18,22 @@
  *
  * ```
  * <Breadcrumb>
- *     <BreadcrumbItem />
- *     <BreadcrumbSeparator /> (optional)
- *     <BreadcrumbItem />
- * 	...
+ * 	<BreadcrumbItem />
+ * 	<BreadcrumbSeparator /> (optional)
+ * 	<BreadcrumbItem>
+ * 		...
+ * 	</BreadcrumbItem>
  * </Breadcrumb>
  * ```
  *
  * You can separate BreadcrumbItems using BreadcrumbSeparators or by using CSS.
- *
- * @prop {string | undefined} ariaLabel -- An ARIA label for describing the popover to screen readers 
  */
-export default function Breadcrumb($props: any) {
+export default function Breadcrumb($props: BreadcrumbProps | undefined) {
 	@render {
 		<nav
-			{$props.id}
-			class={`torp-breadcrumb ${$props.class ?? ""}`.trim()}
-			aria-label={$props.ariaLabel}
+			{$props?.id}
+			class={`torp-breadcrumb ${$props?.class ?? ""}`.trim()}
+			aria-label={$props?.ariaLabel}
 		>
 			<slot />
 		</nav>

package/dist/Breadcrumb/BreadcrumbItem.torp

@@ -1,17 +1,24 @@
 
+interface BreadcrumbItemProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether this is the current page */
+	current?: boolean,
+}
+
 /**
  * An item in a breadcrumb, containing a link to one of the parent pages of the
  * current page (or the current page).
- *
- * @prop {boolean | undefined} current -- Whether this is the current page
  */
-export default function BreadcrumbItem($props: any) {
+export default function BreadcrumbItem($props: BreadcrumbItemProps | undefined) {
 	@render {
 		<div
-			{$props.id}
-			class={`torp-breadcrumb ${$props.class ?? ""}`.trim()}
-			aria-current={$props.current ? "page" : undefined}
-			data-current={$props.current ? "current" : undefined}
+			{$props?.id}
+			class={`torp-breadcrumb ${$props?.class ?? ""}`.trim()}
+			aria-current={$props?.current ? "page" : undefined}
+			data-current={$props?.current ? "current" : undefined}
 		>
 			<slot />
 		</div>

package/dist/Breadcrumb/BreadcrumbSeparator.torp

@@ -1,13 +1,20 @@
 
+interface BreadcrumbSeparatorProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
 /**
  * A separator between links in a Breadcrumb component. It is hidden from
  * screen readers.
  */
-export default function BreadcrumbSeparator($props: any) {
+export default function BreadcrumbSeparator($props: BreadcrumbSeparatorProps | undefined) {
 	@render {
 		<div
-			{$props.id}
-			class={`torp-breadcrumb-separator ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-breadcrumb-separator ${$props?.class ?? ""}`.trim()}
 			aria-hidden="true"
 		>
 			<slot />

package/dist/Breadcrumb/index.d.ts

@@ -1,54 +1,83 @@
 import { type SlotRender } from "@torpor/view";
 
 
+interface BreadcrumbProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** An ARIA label for describing the popover to screen readers  */
+	ariaLabel?: string | undefined,
+}
+
 /**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
+ *
+ * A list of links to the parent pages of the current page in hierarchical order.
+ *
+ * See [the WAI ARIA guidelines for Breadcrumbs](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/).
+ *
+ * The structure of a Breadcrumb is:
+ *
+ * ```
+ * <Breadcrumb>
+ * 	<BreadcrumbItem />
+ * 	<BreadcrumbSeparator /> (optional)
+ * 	<BreadcrumbItem>
+ * 		...
+ * 	</BreadcrumbItem>
+ * </Breadcrumb>
+ * ```
+ *
+ * You can separate BreadcrumbItems using BreadcrumbSeparators or by using CSS.
  */
 declare function Breadcrumb(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props: any,
+	$props: BreadcrumbProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface BreadcrumbItemProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether this is the current page */
+	current?: boolean,
+}
+
 /**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
+ * An item in a breadcrumb, containing a link to one of the parent pages of the
+ * current page (or the current page).
  */
 declare function BreadcrumbItem(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props: any,
+	$props: BreadcrumbItemProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
+interface BreadcrumbSeparatorProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
 /**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
+ * A separator between links in a Breadcrumb component. It is hidden from
+ * screen readers.
  */
 declare function BreadcrumbSeparator(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props: any,
+	$props: BreadcrumbSeparatorProps | undefined,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;

package/dist/Calendar/Calendar.torp

@@ -7,7 +7,15 @@ import ChevronRight from "../icons/ChevronRight.torp";
 
 // TODO: Split this out into Calendar, CalendarHeader, CalendarPreviousTrigger, CalendarGrid etc
 
-export default function Calendar() {
+interface CalendarProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
+export default function Calendar($props: CalendarProps) {
+	$props ??= $watch({});
 	$props.startOfWeek ??= 1;
 	$props.selectable ??= false;
 	$props.value ??= new Date();
@@ -24,10 +32,11 @@ export default function Calendar() {
 	let $state = $watch({
 		activeDate: $props.value,
 		visibleDate: $props.value,
-		//get days() {
-		//	// TODO: $cache
-		//	return buildDays($state.visibleDate, $props.startOfWeek)
-		//},
+		get days() {
+			return $cache(() => {
+				return buildDays($state.visibleDate, $props.startOfWeek)
+			});
+		},
 	});
 
 	let visibleStartDate = $props.value;
@@ -41,8 +50,6 @@ export default function Calendar() {
 	$context[CalendarContextName] = context;
 
 	$run(() => {
-		$state.days = buildDays($state.visibleDate, $props.startOfWeek)
-
 		// HACK: Shouldn't need this
 		if (refocus) {
 			refocus = false;
@@ -211,27 +218,27 @@ export default function Calendar() {
 
 	@render {
 		<div
-			{$props.id}
-			class={`torp-calendar ${$props.class ?? ""}`.trim()}
+			{$props?.id}
+			class={`torp-calendar ${$props?.class ?? ""}`.trim()}
 			&ref={container}
 		>
-			<div class={`torp-calendar-header ${$props.class ?? ""}`.trim()}>
-				<button class={`torp-calendar-previous-trigger ${$props.class ?? ""}`.trim()} onclick={handlePrevMonth}>
+			<div class={`torp-calendar-header ${$props?.class ?? ""}`.trim()}>
+				<button class={`torp-calendar-previous-trigger ${$props?.class ?? ""}`.trim()} onclick={handlePrevMonth}>
 					<slot name="prev-button">
 						<ChevronLeft />
 					</slot>
 				</button>
-				<span class={`torp-calendar-month-name ${$props.class ?? ""}`.trim()}>
+				<span class={`torp-calendar-month-name ${$props?.class ?? ""}`.trim()}>
 					{monthNames[$state.visibleDate.getMonth()] + " " + $state.visibleDate.getFullYear()}
 				</span>
-				<button class={`torp-calendar-next-trigger ${$props.class ?? ""}`.trim()} onclick={handleNextMonth}>
+				<button class={`torp-calendar-next-trigger ${$props?.class ?? ""}`.trim()} onclick={handleNextMonth}>
 					<slot name="next-button">
 						<ChevronRight />
 					</slot>
 				</button>
 			</div>
 			<div
-				class={`torp-calendar-grid ${$props.class ?? ""}`.trim()}
+				class={`torp-calendar-grid ${$props?.class ?? ""}`.trim()}
 				tabindex={$props.selectable ? 0 : -1}
 				onfocus={handleFocus}
 				onkeydown={handleKey}

package/dist/Calendar/CalendarDay.torp

@@ -1,7 +1,15 @@
 import { areDatesEqual } from "../utils/dateUtils";
 import { type CalendarContext, type CalendarEvent, CalendarContextName } from "./CalendarTypes";
 
-export default function CalendarDay() {
+interface CalendarDayProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
+export default function CalendarDay($props: CalendarDayProps) {
+	$props ??= $watch({});
 	$props.date ??= new Date();
 	$props.selectable ??= false;
 	$props.muted ??= false;
@@ -40,9 +48,9 @@ export default function CalendarDay() {
 
 	@render {
 		<div 
-			{$props.id}
+			{$props?.id}
 			class={[
-				`torp-calendar-day ${$props.class ?? ""}`.trim(),
+				`torp-calendar-day ${$props?.class ?? ""}`.trim(),
 				{
 					muted: $props.muted,
 					today: isToday(),
@@ -57,7 +65,7 @@ export default function CalendarDay() {
 			} else {
 				<span>{date.getDate()}</span>
 			}
-			<ul class={`torp-calendar-day-events ${$props.class ?? ""}`.trim()}>
+			<ul class={`torp-calendar-day-events ${$props?.class ?? ""}`.trim()}>
 				@for (ev of $props.events) {
 					<li title={ev.content} />
 				}

package/dist/Calendar/index.d.ts

@@ -1,36 +1,34 @@
 import { type SlotRender } from "@torpor/view";
 
 
-/**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
- */
+interface CalendarProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
 declare function Calendar(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props?: Record<PropertyKey, any>,
+	$props: CalendarProps,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;
 
 
 
-/**
- * Mounts or hydrates the component into the supplied parent node.
- * @param $parent -- The parent node.
- * @param $anchor -- The node to mount the component before.
- * @param $props -- The values that have been passed into the component as properties.
- * @param $context -- Values that have been passed into the component from its ancestors.
- * @param $slots -- Functions for rendering children into slot nodes within the component.
- */
+interface CalendarDayProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
+
 declare function CalendarDay(
 	$parent: ParentNode,
 	$anchor: Node | null,
-	$props?: Record<PropertyKey, any>,
+	$props: CalendarDayProps,
 	$context?: Record<PropertyKey, any>,
 	$slots?: Record<string, SlotRender>,
 ): void;

package/dist/Contextual/Contextual.torp

@@ -0,0 +1,125 @@
+import { ContextualContextName, type Point, type ContextualContext, type ContextualState } from "./ContextualTypes";
+
+interface ContextualProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether the contextual is modal. If true, an overlay should be supplied to obscure outside content, and only the context content will be visible to screen readers  */
+	modal?: boolean,
+	/** Whether the contextual is visible  */
+	visible?: boolean,
+	/** The element to anchor this contextual to, as an alternative to supplying a ContextualTrigger  */
+	anchor?: HTMLElement,
+	/** The position to display this contextual at  */
+	position?: Point,
+	/** A function to be called when the user selects a response */
+	callback?: ((value: any) => void),
+	/** Raised when this contextual is opened or closed */
+	ontoggle?: (open: boolean) => void,
+	/** Raised when the contextual has opened */
+	onopen?: () => void,
+	/** Raised when the contextual has closed */
+	onclose?: (result: any) => void,
+}
+
+/**
+ * A contextual window that is shown to the user at the cursor's location.
+ *
+ * The structure of a Contextual is:
+ *
+ * ```
+ * <Contextual>
+ * 	<ContextualTrigger /> (optional)
+ * 	<ContextualContent />
+ * </Contextual>
+ * ```
+ */
+export default function Contextual($props: ContextualProps | undefined) {
+	let $state: ContextualState = $watch({
+		visible: false,
+		position: { x: 0, y: 0 }
+	})
+
+	// Sync props and state
+	$run(() => {
+		$state.visible = $props?.visible ?? false;
+		$state.position = $props?.position ?? { x: 0, y: 0 };
+	});
+	$run(() => {
+		if ($props !== undefined) {
+			$props.visible = $state.visible;
+		}
+	});
+
+	let result: any;
+
+	// Set the context to pass down to items
+	let context: ContextualContext = {
+		handleButton,
+		handleClickOutside,
+		state: $state,
+		modal: $props?.modal,
+		anchorElement: $props?.anchor ? $unwrap($props.anchor) : undefined,
+	};
+	$context[ContextualContextName] = context;
+
+	// Dispatch the toggle event when the contextual is opened or closed
+	let firstToggle = true;
+	$run(() => {
+		const ontoggle = $props?.ontoggle;
+		const onopen = $props?.onopen;
+		const onclose = $props?.onclose;
+		const visible = $state.visible;
+		if (firstToggle) {
+			firstToggle = false;
+		} else {
+			if (ontoggle) ontoggle(visible);
+			if (visible) {
+				if (onopen) onopen()
+			} else {
+				if (onclose) onclose(result);
+			}
+		}
+	});
+
+	function handleButton(type: "confirm" | "cancel" | undefined, value?: any) {
+		// Get the button's result
+		switch (type) {
+			case "confirm": {
+				result = value || true;
+				break;
+			}
+			case "cancel": {
+				result = value || false;
+				break;
+			}
+			default: {
+				result = value;
+				break;
+			}
+		}
+
+		// Hide the contextual
+		$state.visible = false;
+
+		// Call the callback
+		if ($props?.callback) {
+			$props.callback(result);
+		}
+	}
+
+	function handleClickOutside(e: MouseEvent) {
+		e.preventDefault();
+		$state.visible = false;
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={`torp-context ${$props?.class ?? ""}`.trim()}
+		>
+			<slot />
+		</div>
+	}
+}

package/dist/{Popover/PopoverContentContextual.torp → Contextual/ContextualContent.torp}

@@ -2,21 +2,28 @@
 import { addDocumentEvent, removeDocumentEvent } from "../utils/documentEvents";
 import getScrollParent from "../utils/getScrollParent";
 import setContextPosition from "../utils/setContextPosition";
-import { PopoverContextName, type PopoverContext } from "./PopoverTypes";
+import { ContextualContextName, type ContextualContext } from "./ContextualTypes";
+
+interface ContextualContentProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+}
 
 /**
- * The content that is displayed for a Popover when it is open, displayed at the
+ * The content that is displayed for a Contextual when it is open, displayed at the
  * position that the user right-clicked.
  */
-export default function PopoverContentContextual($props: any) {	
+export default function ContextualContent($props: ContextualContentProps | undefined) {	
 	let div: HTMLDivElement;
 	let shown = false;
 	let closeOnClick = false;
 
-	// Get stuff out of the PopoverContext
-	const context = $context[PopoverContextName] as PopoverContext;
+	// Get stuff out of the ContextualContext
+	const context = $context[ContextualContextName] as ContextualContext;
 	if (!context) {
-		throw new Error("PopoverContentContextual must be contained within a Popover");
+		throw new Error("ContextualContent must be contained within a Contextual");
 	}
 	let $state = context.state;
 
@@ -37,7 +44,8 @@ export default function PopoverContentContextual($props: any) {
 
 		// Set the position and listen for window resize and scroll to reset the position
 		setPosition();
-		const scrollParent = getScrollParent(context.anchorElement)
+		const anchorElement = context.anchorElement!;
+		const scrollParent = getScrollParent(anchorElement)
 		scrollParent.addEventListener("resize", setPosition);
 		scrollParent.addEventListener("scroll", setPosition);
 		if (context.focusFirstElement) {
@@ -52,11 +60,12 @@ export default function PopoverContentContextual($props: any) {
 		removeDocumentEvent("click", handleDocumentClick);
 
 		// Stop listening for window resize and focus the anchor element per WAI guidelines
-		const scrollParent = getScrollParent(context.anchorElement)
+		const anchorElement = context.anchorElement!;
+		const scrollParent = getScrollParent(anchorElement)
 		scrollParent.removeEventListener("resize", setPosition);
 		scrollParent.removeEventListener("scroll", setPosition);
-		if (context.anchorElement?.focus) {
-			context.anchorElement.focus();
+		if (anchorElement.focus) {
+			anchorElement.focus();
 		}
 	}
 
@@ -88,8 +97,8 @@ export default function PopoverContentContextual($props: any) {
 	@render {
 		@if ($state.visible) {
 			<div
-				{$props.id}
-				class={`torp-popover-content-contextual ${$props.class ?? ""}`.trim()}
+				{$props?.id}
+				class={`torp-popover-content-contextual ${$props?.class ?? ""}`.trim()}
 				&ref={div}
 				onmount={show}
 			>

package/dist/Contextual/ContextualTrigger.torp

@@ -0,0 +1,66 @@
+import { ContextualContextName, type ContextualContext } from "./ContextualTypes";
+import hoverTrigger from "../mount/hoverTrigger";
+
+interface ContextualTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Class name(s) for the root element */
+	class?: string,
+	/** Whether the popover is activated by click/press or by hover **/
+	activation?: "press" | "hover"
+}
+
+/**
+ * The element that causes a Contextual to appear or disappear when right-clicked.
+ */
+export default function ContextualTrigger($props: ContextualTriggerProps | undefined) {
+	let activation = $props?.activation ?? "press";
+
+	// Get stuff out of the ContextualContext
+	const context = $context[ContextualContextName] as ContextualContext;
+	if (!context) {
+		throw new Error("ContextualTrigger must be contained within a Contextual");
+	}
+	let $state = context.state;
+
+	function handleContextualMenu(e: MouseEvent & { currentTarget: EventTarget & HTMLDivElement }) {
+		if (activation !== "press") return;
+
+		e.preventDefault();
+		if ($state.position) {
+			// Get the position relative to the element, so we can reposition on scroll
+			const rect = e.currentTarget.getBoundingClientRect();
+			const x = e.clientX - rect.left;
+			const y = e.clientY - rect.top;
+			$state.position = { x, y };
+			//$state.position = { x: window.scrollX + e.clientX, y: window.scrollY + e.clientY };
+		}
+		$state.visible = !$state.visible;
+	}
+
+	function handleHover(node: HTMLElement, e: MouseEvent) {
+		if (activation !== "hover") return;
+
+		if ($state.position) {
+			// Get the position relative to the element, so we can reposition on scroll
+			const rect = node.getBoundingClientRect();
+			const x = e.clientX - rect.left;
+			const y = e.clientY - rect.top;
+			$state.position = { x, y };
+			//$state.position = { x: window.scrollX + e.clientX, y: window.scrollY + e.clientY };
+		}
+		$state.visible = !$state.visible
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={`torp-popover-trigger-contextual ${$props?.class ?? ""}`.trim()}
+			oncontextmenu={handleContextualMenu}
+			onmount={(el) => hoverTrigger(el, { onHover: handleHover, onExit: handleHover })}
+			&ref={context.anchorElement}
+		>
+			<slot />
+		</div>
+	}
+}

package/dist/Contextual/ContextualTypes.ts

@@ -0,0 +1,30 @@
+export const ContextualContextName = "Contextual";
+
+/** The shared context for popover components (Contextual, Prompt and Contextual) */
+export interface ContextualContext {
+	handleButton: (type: "confirm" | "cancel" | undefined, value?: any) => void;
+	// HACK: We need to be able to let children (i.e. Dialogs) override the click outside functionality
+	// There may be a more elegant way to accomplish this too
+	handleClickOutside?: (e: MouseEvent) => void;
+	state: ContextualState;
+	//modal: boolean;
+	anchorElement?: HTMLElement;
+	// HACK: focusFirstElement is necessary because if we focus the first element e.g. in a Dialog's
+	// onMount, it will scroll the page to the focused element and mess up our careful positioning
+	// We need to be able to manually set the order to
+	// 1. set visible (so we have an element with content)
+	// 2. set position (so the element is in the right place)
+	// 3. set focus (for accessibility)
+	// There may be a more elegant way to accomplish this!
+	focusFirstElement?: () => void;
+}
+
+export interface ContextualState {
+	visible: boolean;
+	position: Point;
+}
+
+export interface Point {
+	x: number;
+	y: number;
+}