@torpor/ui 0.3.7 → 1.0.0

package/dist/utils/LoadedItems.torp

@@ -0,0 +1,47 @@
+import { ListBox, ListBoxItem } from "../ListBox/index";
+
+interface LoadedItemsProps {
+	/** The items to render */
+	items: any[];
+	/** The selected value(s), bound through to the internal ListBox */
+	value: any;
+	/** Whether multiple items can be selected */
+	multiple?: boolean;
+	/** Extracts the display text for an item (defaults to label ?? text ?? item) */
+	getItemLabel?: (item: any) => any;
+	/** Extracts the value for an item (defaults to value ?? id) */
+	getItemValue?: (item: any) => any;
+}
+
+function defaultLabel(item: any): string {
+	const label = item?.label ?? item?.text ?? item;
+	return typeof label === "string" ? label : String(label);
+}
+
+function defaultValue(item: any): any {
+	return item?.value ?? item?.id;
+}
+
+/**
+ * The internally rendered list of options for components that load their
+ * items from a network loader (ComboBox auto-complete etc). Used as the
+ * fallback content when a consumer doesn't slot their own ListBox.
+ */
+export default function LoadedItems($props: LoadedItemsProps) {
+	const getLabel = $props.getItemLabel ?? defaultLabel;
+	const getValue = $props.getItemValue ?? defaultValue;
+
+	@render {
+		<ListBox type={$props.multiple ? "multiple" : "single"} value={$props.value}>
+			@for (let item of $props.items) {
+				@key = getValue(item)
+				<ListBoxItem value={getValue(item)}>
+					{getLabel(item)}
+				</ListBoxItem>
+			}
+		</ListBox>
+		@if ($props.items.length === 0) {
+			<span class="torp-loaded-items-empty">No results.</span>
+		}
+	}
+}

package/dist/utils/PopoutClickTrigger.torp

@@ -0,0 +1,99 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import getId from "./getId";
+import { type PopoutContext } from "./PopoutTypes";
+
+interface PopoutClickTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The element to render: a button, or a div for right-click regions */
+	tag?: "button" | "div";
+	/** The event that activates the popout */
+	event?: "click" | "contextmenu";
+	/** The containing popout's context (the family-specific one, not PopoutContext) */
+	context: PopoutContext;
+	/**
+	 * Called with the activating event before visibility is toggled, for
+	 * triggers that track a position (right-click coordinates etc)
+	 */
+	onactivate?: (node: HTMLElement, e: MouseEvent) => void;
+}
+
+/**
+ * The shared primitive behind PopoverTrigger, ContextualTrigger and
+ * ModalTrigger: it publishes the trigger id, renders the standard trigger
+ * attributes (aria-haspopup / aria-expanded / aria-controls), anchors the
+ * popout to itself and toggles visibility on the configured event.
+ *
+ * Hover activation deliberately lives in PopoverHover / ContextualHover,
+ * whose open/close semantics (intent delay, exit grace) differ enough from
+ * a press to warrant their own component.
+ */
+export default function PopoutClickTrigger($props?: PopoutClickTriggerProps) {
+	let defaultId = getId();
+
+	const context = $props!.context;
+	const $state = context.state;
+
+	// Set the trigger ID so that it can be used with aria-labelledby
+	$state.triggerId = $props?.id ?? defaultId;
+
+	const tag = $props?.tag ?? "button";
+	const event = $props?.event ?? "click";
+
+	function handleEvent(node: HTMLElement, e: MouseEvent) {
+		if (event === "contextmenu") {
+			e.preventDefault();
+		}
+		$props?.onactivate?.(node, e);
+		$state.visible = !$state.visible;
+	}
+
+	function handleClick(e: MouseEvent) {
+		if (event !== "click") return;
+		handleEvent(e.currentTarget as HTMLElement, e);
+	}
+
+	function handleContextMenu(e: MouseEvent) {
+		if (event !== "contextmenu") return;
+		handleEvent(e.currentTarget as HTMLElement, e);
+	}
+
+	function handleMount(el: HTMLElement) {
+		context.anchorElement = el;
+	}
+
+	@render {
+		@if (tag === "button") {
+			<button
+				type="button"
+				id={$props?.id ?? defaultId}
+				class={["torp-popout-trigger", $props?.class]}
+				{$props?.style}
+				aria-haspopup={$state.contentRole ?? "true"}
+				aria-expanded={$state.visible ? "true" : "false"}
+				aria-controls={$state.contentId}
+				onclick={handleClick}
+				onmount={handleMount}
+			>
+				<slot />
+			</button>
+		} else {
+			<div
+				id={$props?.id ?? defaultId}
+				class={["torp-popout-trigger", $props?.class]}
+				{$props?.style}
+				aria-haspopup={$state.contentRole ?? "true"}
+				aria-expanded={$state.visible ? "true" : "false"}
+				aria-controls={$state.contentId}
+				oncontextmenu={handleContextMenu}
+				onmount={handleMount}
+			>
+				<slot />
+			</div>
+		}
+	}
+}

package/dist/utils/PopoutTypes.ts

@@ -0,0 +1,82 @@
+export const PopoutContextName: unique symbol = Symbol.for("torp.Popout");
+
+// TODO: Use this type in more places
+export type HandleButtonPress = (type: "confirm" | "cancel" | undefined, value?: any) => void;
+
+/**
+ * The shared focus API for popout-style contexts: content can focus its
+ * first/last item after being shown.
+ *
+ * HACK: Deferring the focus call 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!
+ */
+export interface FocusApi {
+	focusFirstElement?: () => void;
+	focusLastElement?: () => void;
+}
+
+/** The shared context for popout components */
+export interface PopoutContext extends FocusApi {
+	handleButton: HandleButtonPress;
+	// 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 | KeyboardEvent) => void;
+	state: PopoutState;
+	//modal: boolean;
+	anchorElement?: HTMLElement;
+
+	/**
+	 * Called from menu content when an arrow key should move to an adjacent item
+	 * in a containing MenuBar, opening its menu. Only set by MenuBarItem.
+	 */
+	navigateMenuBar?: (target: "previous" | "next") => void;
+
+	markElement?: (id: string) => void;
+	selectMarkedElement?: () => void;
+	searchText?: string;
+	searchItems?: (searchText: string) => { id: string; setFocused: () => void } | undefined;
+}
+
+export interface PopoutState {
+	visible: boolean;
+	contentId?: string;
+	triggerId?: string;
+	/**
+	 * The role of this popout's content ("menu", "listbox", "tree", "grid" or
+	 * "dialog"), set by the content component so that triggers can use it for
+	 * their aria-haspopup attribute.
+	 */
+	contentRole?: string;
+	/** Whether the popout is modal (e.g. it has an overlay) */
+	modal?: boolean;
+	/** The ID of the active descendant element, for aria-activedescendant */
+	activeDescendant?: string;
+}
+
+/**
+ * The state that a submenu trigger registers with its containing group
+ * (Menu, MenuBar, ToolBar or NavMenu). Passed to `registerItem`; the group
+ * assigns `index`, and the trigger assigns `text` from its label on mount.
+ */
+export interface SubmenuItemState {
+	/** Assigned by the group on registration */
+	index?: number;
+	/** The item's label, set from its text content on mount; used for type-ahead */
+	text?: string;
+	setFocused: () => void;
+	/** Shows or hides the item's submenu */
+	setVisible?: (visible: boolean) => void;
+	/** Whether the item is disabled; disabled items are skipped by keyboard navigation */
+	disabled?: boolean;
+}
+
+export interface Point {
+	x: number;
+	y: number;
+}

package/dist/utils/SubmenuPopout.torp

@@ -0,0 +1,89 @@
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import $handle from "./$handle";
+import { type PopoutContext, type PopoutState, PopoutContextName } from "./PopoutTypes";
+
+interface SubmenuPopoutProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** Whether the popout is visible */
+	visible: Bindable<boolean | undefined>;
+	/** Raised when the popout has opened */
+	onopen?: () => void;
+	/** Raised when the popout has closed */
+	onclose?: (result: any) => void;
+	/** The popout's state, supplied when the containing component needs access to it */
+	state?: PopoutState;
+	/** Extra values published through the popout context, e.g. handleButton */
+	context?: Partial<PopoutContext>;
+	/** Whether the popout closes when the pointer leaves it (default true) */
+	closeOnMouseLeave?: boolean;
+	/** The role of the popout's content, published so that triggers can use it for aria-haspopup */
+	contentRole?: string;
+}
+
+/**
+ * The shared primitive behind MenuPopout, MenuBarItem, ToolBarPopout and
+ * NavMenuPopout: it owns the popout's state, publishes the popout context for
+ * its trigger and content, and raises open/close events. The component
+ * wrappers supply their group's behaviour through props.
+ *
+ * The structure of a submenu popout is:
+ *
+ * ```
+ * <XPopout>
+ * 	<XPopoutTrigger /> (optional)
+ * 	<XPopoutContent />
+ * </XPopout>
+ * ```
+ */
+export default function SubmenuPopout($props: SubmenuPopoutProps | undefined) {
+	let $state: PopoutState = $props?.state ?? $watch({
+		visible: false,
+		contentId: undefined,
+		triggerId: undefined,
+		contentRole: $props?.contentRole,
+	});
+
+	$bind($state, $props, "visible");
+
+	let result: any;
+
+	// Set the context to pass down to the trigger and content
+	let context: PopoutContext = {
+		handleButton: () => {},
+		...$props?.context,
+		state: $state,
+	};
+	$context[PopoutContextName] = context;
+
+	$handle((first) => {
+		const visible = $state.visible;
+		if (first) return;
+		if (visible) {
+			$props?.onopen?.();
+		} else {
+			$props?.onclose?.(result);
+		}
+	});
+
+	function handleMouseLeave() {
+		if ($props?.closeOnMouseLeave !== false) {
+			$state.visible = false;
+		}
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={$props?.class}
+			{$props?.style}
+			onmouseleave={handleMouseLeave}
+		>
+			<slot />
+		</div>
+	}
+}

package/dist/utils/SubmenuPopoutContent.torp

@@ -0,0 +1,87 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import getId from "./getId";
+import { createPopoutContent } from "./popoutContent";
+import { type PopoutContext, PopoutContextName } from "./PopoutTypes";
+
+interface SubmenuPopoutContentProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** Where the popout will be shown, relative to the popout button */
+	side?: "top" | "right" | "bottom" | "left";
+	/** How the popout will be aligned, relative to the popout button */
+	alignment?: "start" | "center" | "end";
+	/** Whether pressing Escape closes the popout (default true) */
+	closeOnEscape?: boolean;
+	/** Only close on Escape when the focus is inside the content */
+	escapeOnlyWhenFocused?: boolean;
+	/** The ARIA role of the content element, e.g. "menu" */
+	role?: string;
+	/**
+	 * The role of the popout's content, published so that triggers can use it
+	 * for aria-haspopup
+	 */
+	contentRole?: string;
+}
+
+/**
+ * The shared primitive behind MenuPopoutContent, MenuBarItemContent,
+ * ToolBarPopoutContent and NavMenuPopoutContent: it positions the content
+ * against the trigger, handles outside clicks, Escape and focus, and renders
+ * the content when the popout is visible.
+ */
+export default function SubmenuPopoutContent($props: SubmenuPopoutContentProps | undefined) {
+	const defaultId = getId();
+
+	// Get stuff out of the PopoutContext
+	const popoutContext = $context[PopoutContextName] as PopoutContext;
+	if (!popoutContext) {
+		throw new Error("SubmenuPopoutContent must be contained within a SubmenuPopout");
+	}
+	let $state = popoutContext.state;
+
+	// Set the content ID so that triggers can use it with aria-controls
+	$state.contentId = $props?.id ?? defaultId;
+
+	// Set the content role so that triggers can use it with aria-haspopup
+	$state.contentRole = $props?.contentRole ?? $state.contentRole;
+
+	const popout = createPopoutContent({
+		getAnchor: () => popoutContext.anchorElement,
+		getContent: () => div,
+		close: () => ($state.visible = false),
+		side: $props?.side ?? "bottom",
+		alignment: $props?.alignment ?? "start",
+		closeOnEscape: $props?.closeOnEscape ?? true,
+		escapeOnlyWhenFocused: $props?.escapeOnlyWhenFocused,
+		focusFirstElement: () => popoutContext.focusFirstElement?.(),
+		refocusAnchorOnHide: true,
+	});
+
+	let div: HTMLDivElement;
+
+	$run(() => {
+		if (!$state.visible) {
+			popout.hide();
+		}
+	});
+
+	@render {
+		@if ($state.visible) {
+			<div
+				id={$props?.id ?? defaultId}
+				class={$props?.class}
+				{$props?.style}
+				role={$props?.role}
+				aria-labelledby={$props?.role ? $state.triggerId : undefined}
+				&ref={div}
+				onmount={(_el) => popout.show()}
+			>
+				<slot />
+			</div>
+		}
+	}
+}

package/dist/utils/SubmenuPopoutTrigger.torp

@@ -0,0 +1,160 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import getId from "./getId";
+import { createHoverOpen } from "./hoverOpen";
+import {
+	type PopoutContext,
+	PopoutContextName,
+	type SubmenuItemState,
+} from "./PopoutTypes";
+
+interface SubmenuPopoutTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The delay before showing the popout on hover, in milliseconds (default 500; 0 opens immediately) */
+	hoverDelay?: number;
+	/** Whether this button is disabled */
+	disabled?: boolean;
+	/** The ARIA role of the trigger */
+	role?: string;
+	/** The element's tabindex, if it should not take focus via tabbing */
+	tabindex?: string;
+	/** The key that opens the popout */
+	openKey?: string;
+	/** The containing group's registration function */
+	registerItem: (item: SubmenuItemState) => { index: number };
+	/** Called with the registration index, for wrappers that need it elsewhere */
+	onRegister?: (index: number) => void;
+	/** The containing group's key handler, called for keys other than openKey */
+	handleItemKey: (e: KeyboardEvent) => void;
+	/** The containing group's focus handler */
+	handleItemFocus: (index: number) => void;
+	/**
+	 * Replaces how the popout is shown/hidden, which by default writes the
+	 * popout's visible state; also registered with the group
+	 */
+	setVisible?: (visible: boolean) => void;
+	/**
+	 * Called with the registration index when the trigger is activated by
+	 * clicking or with openKey, before the popout is shown
+	 */
+	onActivate?: (index: number) => void;
+	/** Replaces the default toggle behaviour when the trigger is clicked */
+	onclick?: () => void;
+}
+
+/**
+ * The shared primitive behind MenuPopoutTrigger, MenuBarItemTrigger,
+ * ToolBarPopoutTrigger and NavMenuPopoutTrigger: it registers itself with the
+ * containing group, opens the popout on hover, on click or with the group's
+ * open key, and renders the standard trigger attributes.
+ */
+export default function SubmenuPopoutTrigger($props: SubmenuPopoutTriggerProps | undefined) {
+	let defaultId = getId();
+
+	let button: HTMLButtonElement;
+
+	// Get stuff out of the PopoutContext
+	const popoutContext = $context[PopoutContextName] as PopoutContext;
+	if (!popoutContext) {
+		throw new Error("SubmenuPopoutTrigger must be contained within a SubmenuPopout");
+	}
+	const { state: $state } = popoutContext;
+
+	// Set the trigger ID so that it can be used with aria-labelledby
+	$state.triggerId = $props?.id ?? defaultId;
+
+	function setVisible(visible: boolean) {
+		if ($props?.setVisible) {
+			$props.setVisible(visible);
+		} else {
+			$state.visible = visible;
+		}
+	}
+
+	// Register this item with the containing group and store the index
+	const item: SubmenuItemState = { setFocused, setVisible, disabled: $props?.disabled };
+	const { index } = $props!.registerItem(item);
+	$props?.onRegister?.(index);
+
+	function setFocused() {
+		button.focus();
+	}
+
+	// Store the anchor element, and the item's label for type-ahead
+	function handleMount(el: HTMLButtonElement) {
+		popoutContext.anchorElement = el;
+		item.text = el.textContent.trim();
+	}
+
+	function activate() {
+		$props?.onActivate?.(index);
+	}
+
+	function handleClick() {
+		if ($props?.onclick) {
+			$props.onclick();
+			return;
+		}
+		activate();
+		setVisible(!$state.visible);
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		if (e.key === $props?.openKey) {
+			// TODO: This should be based on what side the menu shows on
+			e.preventDefault();
+			activate();
+			setVisible(true);
+		} else {
+			$props!.handleItemKey(e);
+		}
+	}
+
+	const hoverDelay = $props?.hoverDelay ?? 500;
+	const hoverOpen = createHoverOpen(
+		() => setVisible(true),
+		() => $props?.disabled ?? false,
+		hoverDelay,
+	);
+
+	function handleMouseEnter() {
+		// Open immediately when there is no hover delay, as menubar items do
+		if (hoverDelay <= 0) {
+			if (!$props?.disabled) {
+				setVisible(true);
+			}
+		} else {
+			hoverOpen.handleMouseEnter();
+		}
+	}
+
+	@render {
+		<button
+			id={$props?.id ?? defaultId}
+			class={$props?.class}
+			{$props?.style}
+			type="button"
+			{$props?.disabled}
+			role={$props?.role}
+			tabindex={$props?.tabindex}
+			aria-haspopup={$state.contentRole ?? "true"}
+			aria-expanded={$state.visible ? "true" : "false"}
+			aria-controls={$state.contentId}
+			aria-disabled={$props?.disabled ? "true" : undefined}
+			onkeydown={handleKey}
+			onclick={handleClick}
+			onfocus={() => $props!.handleItemFocus(index)}
+			onmouseenter={handleMouseEnter}
+			onmouseleave={hoverOpen.handleMouseLeave}
+			onmousemove={hoverOpen.handleMouseMove}
+			&ref={button}
+			onmount={handleMount}
+		>
+			<slot />
+		</button>
+	}
+}

package/dist/utils/chartColors.ts

@@ -2,16 +2,16 @@
  * Colors that can be used in charts, from http://colorbrewer2.org/
  */
 export const chartColors = [
-    "#A6CEE3",
-    "#B2DF8A",
-    "#FB9A99",
-    "#FDBF6F",
-    "#CAB2D6",
-    "#FFFF99",
-    "#1F78B4",
-    "#33A02C",
-    "#E31A1C",
-    "#FF7F00",
-    "#6A3D9A",
-    "#B15928"
-];
+	"#A6CEE3",
+	"#B2DF8A",
+	"#FB9A99",
+	"#FDBF6F",
+	"#CAB2D6",
+	"#FFFF99",
+	"#1F78B4",
+	"#33A02C",
+	"#E31A1C",
+	"#FF7F00",
+	"#6A3D9A",
+	"#B15928",
+] as const;