@torpor/ui 0.4.0 → 1.0.1

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;

package/dist/utils/chartLayout.ts

@@ -0,0 +1,143 @@
+import { $watch } from "@torpor/view";
+import type DataSeries from "../Charts/DataSeries";
+import {
+	calculateChartBottom,
+	calculateChartLeft,
+	calculateItemWidth,
+	calculateMaxValue,
+	calculateStepLabels,
+	calculateStepValue,
+	calculateValueHeight,
+} from "./chartUtils";
+
+export interface ChartLayoutOptions {
+	/** The named series to lay out */
+	series: () => DataSeries[];
+	/** Fixed height, if any (default 200 or the container's client height) */
+	height?: () => number | undefined;
+	/** Fixed width, if any (default 400 or the container's client width) */
+	width?: () => number | undefined;
+	/** Label under the x axis */
+	xLabel?: () => string | undefined;
+	/** Label beside the y axis */
+	yLabel?: () => string | undefined;
+	/** The value at the top of the chart, instead of the series' maximum */
+	maxValue?: () => number | undefined;
+	/** The number of steps between 0 and the maximum value (default 2) */
+	stepCount?: () => number | undefined;
+	/** The size of each step, instead of being calculated */
+	stepValue?: () => number | undefined;
+	/** The container element, used to measure responsive widths */
+	getContainer?: () => HTMLElement | undefined;
+}
+
+/**
+ * The shared layout scaffold behind the cartesian charts (Bar, Column,
+ * Line): measures the chart's text so labels can be sized, and calculates
+ * the plot geometry -- maximum value, step sizes, slot widths and the
+ * left/bottom margins -- reactively from the series and axis props.
+ *
+ * Charts render only their own marks; call `measure` from `$onmount` with the
+ * hidden `<text>` element they render for that purpose.
+ *
+ * ```
+ * let $layout = createChartLayout({
+ * 	series: () => $props.series,
+ * 	getContainer: () => container,
+ * });
+ * $onmount(() => setTimeout(() => measure($layout, measurer), 1));
+ * ```
+ */
+export interface ChartLayout {
+	/** The width of the chart's text, measured from the measurer element */
+	textWidth: number;
+	/** The height of the chart's text (1.5x the measurer's box) */
+	textHeight: number;
+	/** The series names, rendered along the x axis */
+	readonly labels: string[];
+	readonly calculatedHeight: number;
+	readonly calculatedWidth: number;
+	/** The largest value across all series, unless overridden */
+	readonly maxValue: number;
+	/** The size of one y axis step */
+	readonly stepValue: number;
+	/** The labels for each step, 0 through max */
+	readonly stepLabels: number[];
+	/** The width of one category slot */
+	readonly itemWidth: number;
+	/** The pixel height of one unit of value */
+	readonly valueHeight: number;
+	/** The bottom edge of the plot area */
+	readonly chartBottom: number;
+	/** The left edge of the plot area */
+	readonly chartLeft: number;
+	setTextSize(width: number, height: number): void;
+}
+
+export function createChartLayout(options: ChartLayoutOptions): ChartLayout {
+	const defaultHeight = 200;
+	const defaultWidth = 400;
+	const getStepCount = () => options.stepCount?.() ?? 2;
+
+	return $watch({
+		textWidth: 0,
+		textHeight: 0,
+
+		get labels() {
+			return options.series().map((s) => s.name);
+		},
+		get calculatedHeight() {
+			return options.height?.() || defaultHeight;
+		},
+		get calculatedWidth() {
+			return options.width?.() || options.getContainer?.()?.clientWidth || defaultWidth;
+		},
+		get maxValue() {
+			return options.maxValue?.() || calculateMaxValue(options.series());
+		},
+		get stepValue() {
+			return options.stepValue?.() || calculateStepValue(this.maxValue, options.stepCount?.());
+		},
+		get stepLabels() {
+			return calculateStepLabels(getStepCount(), this.stepValue);
+		},
+		get itemWidth() {
+			return calculateItemWidth(this.calculatedWidth, this.chartLeft, this.labels);
+		},
+		get valueHeight() {
+			return calculateValueHeight(
+				this.chartBottom,
+				this.textHeight,
+				this.stepValue,
+				getStepCount(),
+			);
+		},
+		get chartBottom() {
+			return calculateChartBottom(options.xLabel?.() ?? "", this.calculatedHeight, this.textHeight);
+		},
+		get chartLeft() {
+			return calculateChartLeft(
+				this.stepLabels,
+				options.yLabel?.() ?? "",
+				this.textHeight,
+				this.textWidth,
+			);
+		},
+
+		setTextSize(width: number, height: number) {
+			this.textWidth = width;
+			this.textHeight = height * 1.5;
+		},
+	});
+}
+
+/**
+ * Reads the size of a hidden measurer `<text>` element into the layout
+ * state and removes it. Call once the element is in the document (from
+ * `$onmount`, deferred a tick).
+ */
+export function measureChartText(layout: ChartLayout, measurer: SVGTextElement): void {
+	const bbox = measurer.getBBox();
+	layout.setTextSize(bbox.width, bbox.height);
+	measurer.remove();
+}

package/dist/utils/colorUtils.ts

@@ -0,0 +1,103 @@
+/** Converts between color representations used by the picker components */
+
+export interface Rgb {
+	r: number;
+	g: number;
+	b: number;
+}
+
+/** Parses "#rgb", "#rrggbb" or "rrggbb"; returns undefined when invalid */
+export function parseHex(text: string | undefined | null): string | undefined {
+	if (!text) return undefined;
+	let value = text.trim().replace(/^#/, "");
+	if (value.length === 3) {
+		value = value
+			.split("")
+			.map((c) => c + c)
+			.join("");
+	}
+	if (!/^[0-9a-fA-F]{6}$/.test(value)) return undefined;
+	return "#" + value.toLowerCase();
+}
+
+export function hexToRgb(hex: string): Rgb {
+	const value = parseHex(hex) ?? "#000000";
+	return {
+		r: parseInt(value.slice(1, 3), 16),
+		g: parseInt(value.slice(3, 5), 16),
+		b: parseInt(value.slice(5, 7), 16),
+	};
+}
+
+function toHexPart(n: number): string {
+	const clamped = Math.min(255, Math.max(0, Math.round(n)));
+	return clamped.toString(16).padStart(2, "0");
+}
+
+export function rgbToHex({ r, g, b }: Rgb): string {
+	return `#${toHexPart(r)}${toHexPart(g)}${toHexPart(b)}`;
+}
+
+/** Blends two colors; amount 0 returns a, 1 returns b */
+export function mix(a: string, b: string, amount: number): string {
+	const ca = hexToRgb(a);
+	const cb = hexToRgb(b);
+	const t = Math.min(1, Math.max(0, amount));
+	return rgbToHex({
+		r: ca.r + (cb.r - ca.r) * t,
+		g: ca.g + (cb.g - ca.g) * t,
+		b: ca.b + (cb.b - ca.b) * t,
+	});
+}
+
+/** Perceptual lightness in [0..1], for choosing readable text on swatches */
+export function luminance(hex: string): number {
+	const { r, g, b } = hexToRgb(hex);
+	return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+}
+
+/** A default palette, roughly ordered light to dark */
+export const defaultPalette: string[] = [
+	"#FFFFFF",
+	"#F5F5F5",
+	"#D9D9D9",
+	"#BFBFBF",
+	"#8C8C8C",
+	"#595959",
+	"#404040",
+	"#262626",
+	"#0F0F0F",
+	"#000000",
+	"#FFE4E1",
+	"#FFC0CB",
+	"#FF7F7F",
+	"#FF4040",
+	"#E60000",
+	"#A61C00",
+	"#FFEDCC",
+	"#FFD59E",
+	"#FFAA33",
+	"#E67E00",
+	"#B35900",
+	"#FFF9C4",
+	"#FFF176",
+	"#FFEB3B",
+	"#FBC02D",
+	"#F9A825",
+	"#827717",
+	"#E8F5E9",
+	"#A5D6A7",
+	"#66BB6A",
+	"#2E7D32",
+	"#1B5E20",
+	"#0D47A1",
+	"#1565C0",
+	"#1E88E5",
+	"#42A5F5",
+	"#90CAF9",
+	"#E1BEE7",
+	"#CE93D8",
+	"#AB47BC",
+	"#8E24AA",
+	"#4A148C",
+];