@torpor/ui 0.3.7 → 1.0.0

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/chartUtils.ts

@@ -1,4 +1,4 @@
-import type DataSeries from "../Chart/DataSeries";
+import type DataSeries from "../Charts/DataSeries";
 
 export function calculateMaxValue(series: DataSeries[]): number {
 	// HACK: Yeah, nested reduces

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",
+];

package/dist/utils/createItemGroup.ts

@@ -0,0 +1,152 @@
+import { $cache, $run } from "@torpor/view";
+
+export interface ItemGroupItem {
+	index: number;
+	value: any;
+	parentDisabled?: boolean;
+}
+
+export interface ItemGroup<T extends ItemGroupItem> {
+	itemStates: T[];
+	registerItem: (item: T) => void;
+	removeItem: (itemIndex: number) => void;
+	toggleItem: (value: any) => void;
+}
+
+/**
+ * Creates a managed collection of selectable items for group-style components
+ * (Accordion, ListBox, TabGroup, Tree, etc.).
+ *
+ * Handles item registration, removal, and toggle logic. Each item's selection
+ * state is derived: registration installs a `$cache` getter over
+ * `selectedProperty` that computes from the group value, so selection can
+ * never drift out of sync with it — eliminating the boilerplate that was
+ * duplicated across ~5 components.
+ *
+ * The returned `itemStates` array is the source of truth; components should
+ * store it in their context for child items to access.
+ *
+ * NOTE: Items must be registered before their selection property is first
+ * read, so the derived getter can take the property over.
+ */
+export function createItemGroup<T extends ItemGroupItem>(options: {
+	/** The reactive state containing the group value */
+	state: { value: any };
+	/** Selection type, or a getter for it if it can change */
+	type: "single" | "multiple" | (() => "single" | "multiple");
+	/** The boolean property on items that reflects selection state */
+	selectedProperty: keyof T;
+	/** Getter for parent disabled state */
+	disabled?: () => boolean | undefined;
+	/** Allow deselecting in single-select mode (default: true) */
+	allowDeselect?: boolean;
+	/** Called for each item after index assignment but before selection check */
+	onRegister?: (item: T) => void;
+	/** Callback after a toggle, for side effects like closing a popout */
+	onToggle?: (value: any) => void;
+}): ItemGroup<T> {
+	const { state, selectedProperty } = options;
+	const getType = typeof options.type === "function" ? options.type : () => options.type;
+	const allowDeselect = options.allowDeselect ?? true;
+	const itemStates: T[] = [];
+	let nextIndex = 0;
+
+	// Propagate disabled state from parent
+	if (options.disabled) {
+		const disabledGetter = options.disabled;
+		$run(() => {
+			const disabled = disabledGetter() === true;
+			for (let item of itemStates) {
+				item.parentDisabled = disabled;
+			}
+		});
+	}
+
+	function isItemSelected(item: T, value: any): boolean {
+		if (value === undefined || value === null) return false;
+		if (getType() === "multiple") {
+			const values = Array.isArray(value) ? value : [value];
+			return values.some((v) => sameValue(v, item.value));
+		}
+		return sameValue(item.value, value);
+	}
+
+	function registerItem(item: T) {
+		if (item.index === -1 || item.index === undefined) {
+			item.index = nextIndex++;
+		}
+		if (options.onRegister) {
+			options.onRegister(item);
+		}
+		// Make the selection property derived: a cached getter computed from the
+		// group value, so it always reflects (and only reflects) that value
+		Object.defineProperty(item, selectedProperty, {
+			get() {
+				return $cache(() => isItemSelected(item, state.value));
+			},
+			enumerable: true,
+			configurable: true,
+		});
+		if (options.disabled) {
+			item.parentDisabled = options.disabled() === true;
+		}
+		itemStates.splice(item.index, 0, item);
+	}
+
+	function removeItem(itemIndex: number) {
+		const index = itemStates.findIndex((item) => item.index === itemIndex);
+		if (index !== -1) {
+			itemStates.splice(index, 1);
+		}
+		itemStates.forEach((item, i) => (item.index = i));
+	}
+
+	function toggleItem(value: any) {
+		switch (getType()) {
+			case "single": {
+				const item = itemStates.find((i) => sameValue(i.value, value));
+				if (allowDeselect) {
+					if (item) {
+						state.value = (item as any)[selectedProperty] ? undefined : item.value;
+					}
+				} else {
+					// Store the item's own value, so the group value keeps its
+					// canonical type
+					state.value = item ? item.value : value;
+				}
+				break;
+			}
+			case "multiple": {
+				const newValue: any[] = [];
+				for (let item of itemStates) {
+					const toggled = sameValue(item.value, value);
+					if (
+						(toggled && !(item as any)[selectedProperty]) ||
+						(!toggled && (item as any)[selectedProperty])
+					) {
+						newValue.push(item.value);
+					}
+				}
+				state.value = newValue.sort((a, b) => a - b);
+				break;
+			}
+		}
+		if (options.onToggle) {
+			options.onToggle(value);
+		}
+	}
+
+	return { itemStates, registerItem, removeItem, toggleItem };
+}
+
+/**
+ * Compares an item value with a group/toggle value. Primitives are compared
+ * as strings — DOM values are always strings, while callers may pass e.g.
+ * numbers — and everything else by strict equality.
+ */
+function sameValue(a: any, b: any): boolean {
+	if (a === b) return true;
+	if (a === null || b === null || a === undefined || b === undefined) return false;
+	if (typeof a === "object" || typeof b === "object") return false;
+	return String(a) === String(b);
+}

package/dist/utils/dateUtils.ts

@@ -25,7 +25,7 @@ const dayNames: string[] = [
 	"Saturday",
 	"Sunday",
 ];
-const shortDayNames: string[] = dayNames.map((n) => n.substring(0, 3).toLowerCase());
+const shortDayNames: string[] = dayNames.map((n) => n.substring(0, 2));
 
 export { monthNames, shortMonthNames, dayNames, shortDayNames };
 
@@ -229,16 +229,17 @@ function formatMonth(date: Date, m: string): string {
 	} else if (m.length === 3) {
 		return monthNames[date.getMonth()].substring(0, 3);
 	} else if (m.length == 2) {
-		let text = date.getMonth().toString();
-		return text.length < 2 ? "0" + text : text;
+		// getMonth is zero-based
+		return String(date.getMonth() + 1).padStart(2, "0");
 	} else {
 		return date.getMonth().toString();
 	}
 }
 
 function formatYear(date: Date, y: string): string {
-	return date
-		.getFullYear()
-		.toString()
-		.substring(4 - y.length, y.length);
+	const year = date.getFullYear().toString();
+	if (y.length >= 4) {
+		return year;
+	}
+	return year.substring(4 - y.length);
 }

package/dist/utils/documentEvents.ts

@@ -1,17 +1,17 @@
 export function addDocumentEvent<K extends keyof DocumentEventMap>(
 	type: K,
-	listener: (this: Document, ev: DocumentEventMap[K]) => any
+	listener: (this: Document, ev: DocumentEventMap[K]) => any,
 ): void {
-	if (typeof document !== 'undefined') {
+	if (typeof document !== "undefined") {
 		document.addEventListener(type, listener);
 	}
 }
 
 export function removeDocumentEvent<K extends keyof DocumentEventMap>(
 	type: K,
-	listener: (this: Document, ev: DocumentEventMap[K]) => any
+	listener: (this: Document, ev: DocumentEventMap[K]) => any,
 ): void {
-	if (typeof document !== 'undefined') {
+	if (typeof document !== "undefined") {
 		document.removeEventListener(type, listener);
 	}
 }

package/dist/utils/dragState.ts

@@ -0,0 +1,86 @@
+import { $watch } from "@torpor/view";
+
+/**
+ * Shared state for HTML5 drag & drop. A source element starts a drag with
+ * `beginDrag`; drop targets consult `dragState.current` during dragover and
+ * drop. Because the dataTransfer API restricts what can be read outside
+ * drop, the store is the reliable channel -- the dataTransfer only carries
+ * the drag's id, which doubles as an integrity check and makes drags
+ * interoperable across windows when the type is allowed through.
+ *
+ * Drags don't nest, so a single module-level state is enough.
+ */
+
+export interface DragInfo {
+	/** Generated identifier for this drag, mirrored into the dataTransfer */
+	id: string;
+	/** High-level kind ("list-item", "tree-item", "file"...), for filtering */
+	kind: string;
+	/** Arbitrary payload attached by the drag source */
+	data: any;
+}
+
+export interface DragState {
+	/** The active drag, if any */
+	current: DragInfo | undefined;
+}
+
+export const dragState: DragState = $watch({
+	current: undefined as DragInfo | undefined,
+});
+
+let nextId = 0;
+
+/** Starts tracking a drag and returns its id */
+export function beginDrag(kind: string, data: any): DragInfo {
+	const info: DragInfo = {
+		id: String(nextId++),
+		kind,
+		data,
+	};
+	dragState.current = info;
+	return info;
+}
+
+/** Clears the tracked drag */
+export function endDrag(): void {
+	dragState.current = undefined;
+}
+
+const TYPE_PREFIX = "application/x-torpor-drag/";
+
+/** Encodes a drag id into a dataTransfer-compatible mime type */
+export function encodeDragType(id: string): string {
+	return TYPE_PREFIX + id;
+}
+
+/**
+ * Writes the drag's id into the event's dataTransfer. No-op when the event
+ * carries no transfer (some synthetic tests construct bare events).
+ */
+export function writeDragType(e: DragEvent, id: string): void {
+	e.dataTransfer?.setData(encodeDragType(id), id);
+}
+
+/**
+ * Resolves which drag an incoming event refers to. Prefers the id encoded
+ * in the dataTransfer (verified against the live drag); falls back to the
+ * tracked drag itself for dragover events, whose transfers are locked.
+ */
+export function resolveDrag(e: DragEvent): DragInfo | undefined {
+	const current = dragState.current;
+	if (!current) return undefined;
+
+	try {
+		const types: readonly string[] = e.dataTransfer?.types ?? [];
+		for (let type of types) {
+			if (type.startsWith(TYPE_PREFIX)) {
+				return type === encodeDragType(current.id) ? current : undefined;
+			}
+		}
+	} catch {
+		// Reading types can throw for foreign-origin drags; treat those as
+		// unmatched and fall back to the tracked drag below
+	}
+	return current;
+}