@galaxy-io/dls 1.6.0 → 2.0.0

package/dist/tree/Tree.js

@@ -0,0 +1,387 @@
+import Text, { TextVariant } from "../text/Text.js";
+import { useControlledState } from "../hooks/useControlledState.js";
+import Icon, { IconVariant } from "../icons/Icon.js";
+import Rotate from "../transform/Rotate.js";
+import Spinner from "../feedback/Spinner.js";
+import CollapseMotion from "../transform/internal/CollapseMotion.js";
+import { TREE_ROW_CSS, TREE_ROW_LABEL_CSS, TREE_ROW_LEVEL_VARIABLE, TREE_ROW_SIZE_TO_CARET_PX_MAP, TREE_ROW_SIZE_TO_CSS_MAP, TREE_ROW_SIZE_TO_ICON_PX_MAP, TREE_ROW_SIZE_TO_SPINNER_SIZE_MAP, TREE_ROW_SIZE_TO_TEXT_SIZE_MAP, TreeRowCaretSlot, TreeRowSize } from "./treeRow.js";
+/* empty css               */
+import { styled } from "@linaria/react";
+import { Fragment, forwardRef, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cx } from "@linaria/core";
+import { CaretRightIcon } from "@phosphor-icons/react";
+//#region src/tree/Tree.tsx
+/**
+* Hierarchical rows that expand and collapse: a schema browser, a file or folder list, a
+* pipeline's nested steps. The hierarchy is data (`items`); each row has a turning caret, an
+* optional icon, a one-line label and an optional non-interactive `trailing` mark. Groups open and
+* close with an animated height (reduced motion: instant), one row can be selected, a parent whose children are not loaded yet
+* shows a loading row, and the WAI-ARIA tree keyboard pattern is built in.
+*
+* The accessibility tree is flat: every row is a `role="treeitem"` with `aria-level`,
+* `aria-setsize` and `aria-posinset`, and the animated wrappers between rows are generic `div`s,
+* so the focus ring outlines one row, never a whole subtree. One row is the tab stop (roving
+* `tabIndex`); arrows move focus, and selection does not follow focus.
+*
+* It does not fetch, filter, sort, drag or edit. Lazy children are the app's: it learns about an
+* expansion from `onExpandedIdsChange` and passes the children in. JSON is `JsonViewer`.
+*/
+/** Row rung. Tree rows are dense: 24 and 28px, the same geometry as `JsonViewerSize`. */
+var TreeSize = /* @__PURE__ */ function(TreeSize) {
+	/** 24px rows, `body_sm` labels, 12px icons, 10px carets, 14px indent per level. */
+	TreeSize["SMALL"] = "SMALL";
+	/** 28px rows, `body_md` labels, 14px icons, 12px carets, 16px indent per level. The default. */
+	TreeSize["MEDIUM"] = "MEDIUM";
+	return TreeSize;
+}({});
+/** Printable keys typed within this window build one type-ahead query (logic, not motion). */
+var TYPEAHEAD_TIMEOUT_MS = 500;
+/** The loading row's text (fixed English, spec Decision 13). */
+var LOADING_LABEL = "Loading";
+/** The tree: a column of rows on its container's surface (no fill, border or padding). */
+var Root = /*#__PURE__*/ styled("div")({
+	name: "Root",
+	class: "gx-Tree-r1js5qnv",
+	propsAsIs: false
+});
+/** Hover and press fills; applied only to rows that are neither selected nor disabled. */
+var ROW_INTERACTIVE_CSS = "gx-Tree-ROW_INTERACTIVE_CSS-r7rdijp";
+/** Selection is `background.selected`: `text.primary` at 12% over the canvas, quiet and neutral. */
+var SELECTED_CSS = "gx-Tree-SELECTED_CSS-s1b0wl0p";
+/** Disabled and loading rows: no pointer affordance. */
+var DISABLED_CSS = "gx-Tree-DISABLED_CSS-d1ir0aar";
+/** The trailing mark, right-aligned by the label's growth. */
+var Trailing = /*#__PURE__*/ styled("span")({
+	name: "Trailing",
+	class: "gx-Tree-Trailing-t14n6wjb",
+	propsAsIs: false
+});
+/** Identity: the Tree rungs are the shared row rungs (`treeRow.ts`, shared with JsonViewer). */
+var TREE_SIZE_TO_ROW_SIZE_MAP = {
+	["SMALL"]: TreeRowSize.SMALL,
+	["MEDIUM"]: TreeRowSize.MEDIUM
+};
+/** A parent has children, or says it will (lazy). */
+var isParentItem = (item) => item.hasChildren ?? (item.children !== void 0 && item.children.length > 0);
+/** The loading row's key; never an item `id` (a NUL character cannot come from data by accident). */
+var loadingKey = (parentId) => `\u0000loading:${parentId}`;
+/** Depth-first walk of the rows that are showing (descends into expanded parents only). */
+function getVisibleRows(items, expanded) {
+	const rows = [];
+	const walk = (list, level, parentKey) => {
+		for (const item of list) {
+			const isParent = isParentItem(item);
+			const isExpanded = isParent && expanded.has(item.id);
+			rows.push({
+				kind: "item",
+				key: item.id,
+				item,
+				level,
+				parentKey,
+				isParent,
+				isExpanded
+			});
+			if (!isExpanded) continue;
+			if (item.children === void 0) rows.push({
+				kind: "loading",
+				key: loadingKey(item.id),
+				level: level + 1,
+				parentKey: item.id
+			});
+			else walk(item.children, level + 1, item.id);
+		}
+	};
+	walk(items, 1, null);
+	return rows;
+}
+/** Every item's parent id, for finding the nearest visible ancestor of a hidden row. */
+function getParentMap(items) {
+	const parents = /* @__PURE__ */ new Map();
+	const walk = (list, parentId) => {
+		for (const item of list) {
+			parents.set(item.id, parentId);
+			if (item.children !== void 0) walk(item.children, item.id);
+		}
+	};
+	walk(items, null);
+	return parents;
+}
+/** A row's depth as the `--gx-tree-level` custom property (0 at the top level). */
+var levelStyle = (level) => ({ [TREE_ROW_LEVEL_VARIABLE]: String(level - 1) });
+/** Turns a tree `id` into a DOM-id-safe suffix. */
+var toDomId = (value) => encodeURIComponent(value).replace(/[%.']/g, "_");
+/** Hierarchical rows with expand / collapse, single selection, lazy children and tree keyboard. */
+var Tree = forwardRef(function Tree(props, ref) {
+	const { items, value, defaultValue = null, onChange, expandedIds, defaultExpandedIds = [], onExpandedIdsChange, size = "MEDIUM", ariaLabel, id, className, style, ...rest } = props;
+	const baseId = useId();
+	const rowSize = TREE_SIZE_TO_ROW_SIZE_MAP[size];
+	const textSize = TREE_ROW_SIZE_TO_TEXT_SIZE_MAP[rowSize];
+	const iconPx = TREE_ROW_SIZE_TO_ICON_PX_MAP[rowSize];
+	const [selectedId, setSelectedId] = useControlledState({
+		value,
+		defaultValue
+	});
+	const [expandedList, setExpandedList] = useControlledState({
+		value: expandedIds,
+		defaultValue: defaultExpandedIds,
+		onChange: onExpandedIdsChange
+	});
+	const expanded = useMemo(() => new Set(expandedList), [expandedList]);
+	const visible = useMemo(() => getVisibleRows(items, expanded), [items, expanded]);
+	const parents = useMemo(() => getParentMap(items), [items]);
+	const visibleIndex = useMemo(() => new Map(visible.map((row, index) => [row.key, index])), [visible]);
+	const [focusedKey, setFocusedKey] = useState(null);
+	const rowElements = useRef(/* @__PURE__ */ new Map());
+	const typeahead = useRef({
+		query: "",
+		timer: void 0
+	});
+	useEffect(() => {
+		const state = typeahead.current;
+		return () => clearTimeout(state.timer);
+	}, []);
+	/** The roving tab stop: the last focused row, its nearest visible ancestor, else selected / first. */
+	const tabStopKey = useMemo(() => {
+		const first = visible[0]?.key ?? null;
+		if (focusedKey === null) return selectedId !== null && visibleIndex.has(selectedId) ? selectedId : first;
+		if (visibleIndex.has(focusedKey)) return focusedKey;
+		let ancestor = focusedKey.startsWith("\0") ? focusedKey.slice(9) : parents.get(focusedKey) ?? null;
+		while (ancestor !== null) {
+			if (visibleIndex.has(ancestor)) return ancestor;
+			ancestor = parents.get(ancestor) ?? null;
+		}
+		return first;
+	}, [
+		focusedKey,
+		selectedId,
+		visible,
+		visibleIndex,
+		parents
+	]);
+	const focusRow = useCallback((key) => {
+		if (key === void 0) return;
+		rowElements.current.get(key)?.focus();
+	}, []);
+	const toggle = useCallback((itemId) => {
+		setExpandedList(expanded.has(itemId) ? expandedList.filter((entry) => entry !== itemId) : [...expandedList, itemId]);
+	}, [
+		expanded,
+		expandedList,
+		setExpandedList
+	]);
+	const select = useCallback((item) => {
+		if (item.isDisabled || item.id === selectedId) return;
+		setSelectedId(item.id);
+		onChange?.(item.id);
+	}, [
+		onChange,
+		selectedId,
+		setSelectedId
+	]);
+	/** Moves focus to the next visible item row whose label starts with the typed query. */
+	const handleTypeahead = (fromIndex, character) => {
+		const state = typeahead.current;
+		clearTimeout(state.timer);
+		state.query += character.toLowerCase();
+		state.timer = setTimeout(() => {
+			state.query = "";
+		}, TYPEAHEAD_TIMEOUT_MS);
+		const isRepeat = [...state.query].every((entry) => entry === state.query[0]);
+		const query = isRepeat ? state.query.charAt(0) : state.query;
+		const start = isRepeat ? fromIndex + 1 : fromIndex;
+		for (let offset = 0; offset < visible.length; offset += 1) {
+			const row = visible[(start + offset) % visible.length];
+			if (row?.kind === "item" && row.item.label.toLowerCase().startsWith(query)) {
+				focusRow(row.key);
+				return;
+			}
+		}
+	};
+	const handleKeyDown = (event, row) => {
+		if (event.target !== event.currentTarget) return;
+		const index = visibleIndex.get(row.key) ?? 0;
+		const isItem = row.kind === "item";
+		let isHandled = true;
+		switch (event.key) {
+			case "ArrowDown":
+				focusRow(visible[index + 1]?.key);
+				break;
+			case "ArrowUp":
+				focusRow(visible[index - 1]?.key);
+				break;
+			case "Home":
+				focusRow(visible[0]?.key);
+				break;
+			case "End":
+				focusRow(visible[visible.length - 1]?.key);
+				break;
+			case "ArrowRight":
+				if (isItem && row.isParent) if (!row.isExpanded) toggle(row.item.id);
+				else {
+					const next = visible[index + 1];
+					if (next?.parentKey === row.key) focusRow(next.key);
+				}
+				break;
+			case "ArrowLeft":
+				if (isItem && row.isExpanded) toggle(row.item.id);
+				else if (row.parentKey !== null) focusRow(row.parentKey);
+				break;
+			case "Enter":
+				if (isItem) {
+					select(row.item);
+					if (row.isParent) toggle(row.item.id);
+				}
+				break;
+			case " ":
+				if (isItem) select(row.item);
+				break;
+			default: if (event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) handleTypeahead(index, event.key);
+			else isHandled = false;
+		}
+		if (isHandled) event.preventDefault();
+	};
+	const rowRefCallbacks = useRef(/* @__PURE__ */ new Map());
+	const shouldRestoreFocus = useRef(false);
+	const setRowElement = (key) => {
+		let callback = rowRefCallbacks.current.get(key);
+		if (callback === void 0) {
+			callback = (element) => {
+				if (element) {
+					rowElements.current.set(key, element);
+					return;
+				}
+				const previous = rowElements.current.get(key);
+				if (previous !== void 0 && previous === previous.ownerDocument.activeElement) shouldRestoreFocus.current = true;
+				rowElements.current.delete(key);
+				rowRefCallbacks.current.delete(key);
+			};
+			rowRefCallbacks.current.set(key, callback);
+		}
+		return callback;
+	};
+	useEffect(() => {
+		if (!shouldRestoreFocus.current) return;
+		shouldRestoreFocus.current = false;
+		if (tabStopKey !== null) rowElements.current.get(tabStopKey)?.focus();
+	});
+	/** The loading row of an expanded parent whose children are not loaded yet. */
+	const renderLoadingRow = (parentId, level) => {
+		const key = loadingKey(parentId);
+		return /* @__PURE__ */ jsxs("div", {
+			ref: setRowElement(key),
+			role: "treeitem",
+			id: `${baseId}-loading-${toDomId(parentId)}`,
+			"aria-level": level,
+			"aria-setsize": 1,
+			"aria-posinset": 1,
+			"aria-disabled": "true",
+			"aria-busy": "true",
+			tabIndex: tabStopKey === key ? 0 : -1,
+			className: cx(TREE_ROW_CSS, TREE_ROW_SIZE_TO_CSS_MAP[rowSize], DISABLED_CSS),
+			style: levelStyle(level),
+			onFocus: () => setFocusedKey(key),
+			onKeyDown: (event) => handleKeyDown(event, {
+				kind: "loading",
+				key,
+				level,
+				parentKey: parentId
+			}),
+			children: [/* @__PURE__ */ jsx(TreeRowCaretSlot, { "aria-hidden": true }), /* @__PURE__ */ jsx(Spinner, {
+				size: TREE_ROW_SIZE_TO_SPINNER_SIZE_MAP[rowSize],
+				label: LOADING_LABEL
+			})]
+		}, key);
+	};
+	/** One level of rows, each parent followed by its animated group. */
+	const renderItems = (list, level, parentKey) => list.map((item, position) => {
+		const isParent = isParentItem(item);
+		const isExpanded = isParent && expanded.has(item.id);
+		const isSelected = item.id === selectedId;
+		const isDisabled = item.isDisabled === true;
+		const row = {
+			kind: "item",
+			key: item.id,
+			item,
+			level,
+			parentKey,
+			isParent,
+			isExpanded
+		};
+		const handleClick = () => {
+			select(item);
+			if (isParent) toggle(item.id);
+		};
+		const handleCaretClick = (event) => {
+			event.stopPropagation();
+			rowElements.current.get(item.id)?.focus();
+			toggle(item.id);
+		};
+		return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("div", {
+			ref: setRowElement(item.id),
+			role: "treeitem",
+			id: `${baseId}-${toDomId(item.id)}`,
+			"aria-level": level,
+			"aria-setsize": list.length,
+			"aria-posinset": position + 1,
+			"aria-expanded": isParent ? isExpanded : void 0,
+			"aria-selected": isDisabled ? void 0 : isSelected,
+			"aria-disabled": isDisabled || void 0,
+			tabIndex: tabStopKey === item.id ? 0 : -1,
+			className: cx(TREE_ROW_CSS, TREE_ROW_SIZE_TO_CSS_MAP[rowSize], !isSelected && !isDisabled && ROW_INTERACTIVE_CSS, isSelected && SELECTED_CSS, isDisabled && DISABLED_CSS),
+			style: levelStyle(level),
+			onFocus: () => setFocusedKey(item.id),
+			onClick: handleClick,
+			onKeyDown: (event) => handleKeyDown(event, row),
+			children: [
+				/* @__PURE__ */ jsx(TreeRowCaretSlot, {
+					"aria-hidden": true,
+					onClick: isParent ? handleCaretClick : void 0,
+					children: isParent && /* @__PURE__ */ jsx(Rotate, {
+						isRotated: isExpanded,
+						deg: 90,
+						children: /* @__PURE__ */ jsx(Icon, {
+							component: CaretRightIcon,
+							size: TREE_ROW_SIZE_TO_CARET_PX_MAP[rowSize],
+							variant: IconVariant.TERTIARY
+						})
+					})
+				}),
+				item.icon && /* @__PURE__ */ jsx(Icon, {
+					component: item.icon,
+					size: iconPx,
+					variant: isDisabled ? IconVariant.DISABLED : IconVariant.SECONDARY
+				}),
+				/* @__PURE__ */ jsx(Text, {
+					as: "span",
+					size: textSize,
+					variant: isDisabled ? TextVariant.DISABLED : TextVariant.PRIMARY,
+					lineClamp: 1,
+					shouldTooltipOnOverflow: true,
+					className: TREE_ROW_LABEL_CSS,
+					children: item.label
+				}),
+				item.trailing !== void 0 && /* @__PURE__ */ jsx(Trailing, {
+					className: "gx-treeRow-TREE_ROW_TRAILING_CSS-tl2nei7",
+					children: item.trailing
+				})
+			]
+		}), isParent && /* @__PURE__ */ jsx(CollapseMotion, {
+			isOpen: isExpanded,
+			children: isExpanded && (item.children === void 0 ? renderLoadingRow(item.id, level + 1) : renderItems(item.children, level + 1, item.id))
+		})] }, item.id);
+	});
+	return /* @__PURE__ */ jsx(Root, {
+		...rest,
+		ref,
+		role: "tree",
+		"aria-label": ariaLabel ?? rest["aria-label"],
+		id,
+		className,
+		style,
+		children: renderItems(items, 1, null)
+	});
+});
+Tree.displayName = "Tree";
+//#endregion
+export { TreeSize, Tree as default };

package/dist/tree/treeRow.d.ts

@@ -0,0 +1,39 @@
+import { SpinnerSize } from "../feedback/Spinner.js";
+import { TextSize } from "../text/Text.js";
+/** @internal The two dense row rungs; `TreeSize` and `JsonViewerSize` map onto it. */
+export declare enum TreeRowSize {
+    /** 24px rows, 8px inline padding, `body_sm`, 12px icon and slot, 10px caret, 14px per level. */
+    SMALL = "SMALL",
+    /** 28px rows, 8px inline padding, `body_md`, 14px icon and slot, 12px caret, 16px per level. */
+    MEDIUM = "MEDIUM"
+}
+/** @internal The custom property carrying a row's depth (0 at the top level); a continuous value. */
+export declare const TREE_ROW_LEVEL_VARIABLE = "--gx-tree-level";
+/**
+ * @internal A row: caret slot, icon, label, trailing. Each level indents by the caret slot plus
+ * the caret gap.
+ */
+export declare const TREE_ROW_CSS: import("@linaria/core").LinariaClassName;
+/** @internal Height, inline padding and the caret slot width (the rung's icon px) per rung. */
+export declare const TREE_ROW_SIZE_TO_CSS_MAP: Record<TreeRowSize, string>;
+/**
+ * @internal The caret's slot, as wide as the rung's icon; leaf rows keep it empty so labels align.
+ * The press target stays a 16px square (centered on the slot through `::before`), larger than the
+ * glyph.
+ */
+export declare const TreeRowCaretSlot: import("@linaria/react").StyledComponent<import("react").ClassAttributes<HTMLSpanElement> & import("react").HTMLAttributes<HTMLSpanElement> & Record<never, unknown>>;
+/**
+ * @internal The label (or key / value text): takes the rest of the row and truncates; its 2px
+ * start padding makes the gap before it 4px.
+ */
+export declare const TREE_ROW_LABEL_CSS: import("@linaria/core").LinariaClassName;
+/** @internal A trailing mark after the label: 2px start padding makes the gap before it 4px. */
+export declare const TREE_ROW_TRAILING_CSS: import("@linaria/core").LinariaClassName;
+/** @internal The row's type step. */
+export declare const TREE_ROW_SIZE_TO_TEXT_SIZE_MAP: Record<TreeRowSize, TextSize>;
+/** @internal Row icon px per rung, which is also the caret slot's width. */
+export declare const TREE_ROW_SIZE_TO_ICON_PX_MAP: Record<TreeRowSize, number>;
+/** @internal The caret: 12px, 10px on the 24px rows (the collapsible Widget's caret). */
+export declare const TREE_ROW_SIZE_TO_CARET_PX_MAP: Record<TreeRowSize, number>;
+/** @internal The loading row's spinner. */
+export declare const TREE_ROW_SIZE_TO_SPINNER_SIZE_MAP: Record<TreeRowSize, SpinnerSize>;

package/dist/tree/treeRow.js

@@ -0,0 +1,75 @@
+import { TextSize } from "../text/Text.js";
+import { SpinnerSize } from "../feedback/Spinner.js";
+/* empty css                  */
+import { styled } from "@linaria/react";
+//#region src/tree/treeRow.ts
+/**
+* @internal The row geometry `Tree` and `JsonViewer` share, so the two can never drift: row
+* height, inline padding, per-level indent, caret slot and caret gap, caret / icon px and the type
+* step, per rung.
+*
+* A row is `[caret slot] 2px [icon] 4px [label] 4px [trailing]`. The caret slot is as wide as the
+* rung's icon and each level indents by the slot plus the 2px caret gap (14px at `SMALL`, 16px at
+* `MEDIUM`), so a child's caret is centered under its parent's icon. The rest of the row keeps a
+* 4px gap: the label and the trailing mark carry 2px of their own start padding on top of the row's
+* 2px gap.
+*/
+/** @internal The two dense row rungs; `TreeSize` and `JsonViewerSize` map onto it. */
+var TreeRowSize = /* @__PURE__ */ function(TreeRowSize) {
+	/** 24px rows, 8px inline padding, `body_sm`, 12px icon and slot, 10px caret, 14px per level. */
+	TreeRowSize["SMALL"] = "SMALL";
+	/** 28px rows, 8px inline padding, `body_md`, 14px icon and slot, 12px caret, 16px per level. */
+	TreeRowSize["MEDIUM"] = "MEDIUM";
+	return TreeRowSize;
+}({});
+/** @internal The custom property carrying a row's depth (0 at the top level); a continuous value. */
+var TREE_ROW_LEVEL_VARIABLE = "--gx-tree-level";
+/**
+* @internal A row: caret slot, icon, label, trailing. Each level indents by the caret slot plus
+* the caret gap.
+*/
+var TREE_ROW_CSS = "gx-treeRow-TREE_ROW_CSS-t1nodxwm";
+/** @internal Height, inline padding and the caret slot width (the rung's icon px) per rung. */
+var TREE_ROW_SIZE_TO_CSS_MAP = {
+	["SMALL"]: "gx-treeRow-SMALL-sgp5lqg",
+	["MEDIUM"]: "gx-treeRow-MEDIUM-mje6tqy"
+};
+/**
+* @internal The caret's slot, as wide as the rung's icon; leaf rows keep it empty so labels align.
+* The press target stays a 16px square (centered on the slot through `::before`), larger than the
+* glyph.
+*/
+var TreeRowCaretSlot = /*#__PURE__*/ styled("span")({
+	name: "TreeRowCaretSlot",
+	class: "gx-treeRow-TreeRowCaretSlot-t1kak285",
+	propsAsIs: false
+});
+/**
+* @internal The label (or key / value text): takes the rest of the row and truncates; its 2px
+* start padding makes the gap before it 4px.
+*/
+var TREE_ROW_LABEL_CSS = "gx-treeRow-TREE_ROW_LABEL_CSS-t1xuussb";
+/** @internal A trailing mark after the label: 2px start padding makes the gap before it 4px. */
+var TREE_ROW_TRAILING_CSS = "gx-treeRow-TREE_ROW_TRAILING_CSS-tl2nei7";
+/** @internal The row's type step. */
+var TREE_ROW_SIZE_TO_TEXT_SIZE_MAP = {
+	["SMALL"]: TextSize.BODY_SM,
+	["MEDIUM"]: TextSize.BODY_MD
+};
+/** @internal Row icon px per rung, which is also the caret slot's width. */
+var TREE_ROW_SIZE_TO_ICON_PX_MAP = {
+	["SMALL"]: 12,
+	["MEDIUM"]: 14
+};
+/** @internal The caret: 12px, 10px on the 24px rows (the collapsible Widget's caret). */
+var TREE_ROW_SIZE_TO_CARET_PX_MAP = {
+	["SMALL"]: 10,
+	["MEDIUM"]: 12
+};
+/** @internal The loading row's spinner. */
+var TREE_ROW_SIZE_TO_SPINNER_SIZE_MAP = {
+	["SMALL"]: SpinnerSize.SMALL,
+	["MEDIUM"]: SpinnerSize.MEDIUM
+};
+//#endregion
+export { TREE_ROW_CSS, TREE_ROW_LABEL_CSS, TREE_ROW_LEVEL_VARIABLE, TREE_ROW_SIZE_TO_CARET_PX_MAP, TREE_ROW_SIZE_TO_CSS_MAP, TREE_ROW_SIZE_TO_ICON_PX_MAP, TREE_ROW_SIZE_TO_SPINNER_SIZE_MAP, TREE_ROW_SIZE_TO_TEXT_SIZE_MAP, TREE_ROW_TRAILING_CSS, TreeRowCaretSlot, TreeRowSize };

package/dist/utils/colors.d.ts

@@ -1,40 +1,60 @@
+/**
+ * Color math for JS logic (charts, canvas, seeded colors, contrast checks). Kept from 1.x
+ * `utils/colors.ts`; 2.0 types every returned hex as `Hex` and adds `contrastRatio`, `meetsAA`
+ * and `mix`. Styling never uses this module: components read `t.color.*`.
+ */
+import type { Hex } from "../theme/tokens/types.js";
+/** A `#`-prefixed hex color string (`#rrggbb` or `#rgb`). */
+export type { Hex };
+/** An sRGB color with 0–255 channels. */
 export type RGB = {
     r: number;
     g: number;
     b: number;
 };
+/** An sRGB color with 0–255 channels and a 0–1 alpha. */
 export type RGBA = RGB & {
     a: number;
 };
+/** Hue (0–360), saturation (0–1), lightness (0–1). */
 export type HSL = {
     h: number;
     s: number;
     l: number;
 };
+/** Hue (0–360), saturation (0–100), value (0–100), alpha (0–1), as `@uiw/react-color` expects. */
 export type HSVA = {
     h: number;
     s: number;
     v: number;
     a: number;
 };
+/** Parses `#rrggbb` / `#rgb` (with or without `#`) into 0–255 channels. Throws on invalid input. */
 export declare const hexToRgb: (hex: string) => RGB;
+/** `hexToRgb` plus an alpha channel. */
 export declare const hexToRgba: (hex: string, a?: number) => RGBA;
-export declare const rgbToHex: ({ r, g, b }: RGB) => string;
-export declare const rgbToHsl: ({ r, g, b }: RGB) => HSL;
-export declare const hslToRgb: ({ h, s, l }: HSL) => RGB;
-export declare const hslToHex: ({ h, s, l }: HSL) => string;
+/** Formats 0–255 channels (rounded, clamped) as lowercase `#rrggbb`. */
+export declare const rgbToHex: ({ r, g, b }: RGB) => Hex;
+/** Converts 0–255 channels to HSL (`h` 0–360, `s` and `l` 0–1). */
+export declare const rgbToHsl: (rgb: RGB) => HSL;
+/** Converts HSL to unrounded 0–255 channels. Wraps `h`, clamps `s` and `l` to 0–1. */
+export declare const hslToRgb: (hsl: HSL) => RGB;
+/** Converts HSL to `#rrggbb`. */
+export declare const hslToHex: ({ h, s, l }: HSL) => Hex;
+/** Converts a hex color to HSVA (`s`, `v` 0–100; `a` always 1), as `@uiw/react-color` expects. */
 export declare const hexToHsva: (hex: string) => HSVA;
-export declare const hsvaToHex: (hsva: HSVA) => string;
+/** Converts HSVA (`s`, `v` 0–100) to `#rrggbb`; alpha is ignored. */
+export declare const hsvaToHex: (hsva: HSVA) => Hex;
 /**
  * Generates a random hex color
  * @returns A random hex color in the format #RRGGBB
  */
-export declare const generateRandomHexColor: () => string;
+export declare const generateRandomHexColor: () => Hex;
 /**
  * Gets an opaque hex color
  * @param hex - The hex color to add opacity to
  * @param opacity - The opacity to add (0-1)
- * @returns A hex color with the added opacity
+ * @returns An `rgba(r, g, b, opacity)` string (not a hex)
  */
 export declare const getOpaqueHexColor: (hex: string, opacity?: number) => string;
 /**
@@ -42,13 +62,13 @@ export declare const getOpaqueHexColor: (hex: string, opacity?: number) => strin
  * @param hex - The hex color to darken
  * @param amount - Amount to subtract from each channel (0..255-ish)
  */
-export declare const getDarkerHexColor: (hex: string, amount?: number) => string;
+export declare const getDarkerHexColor: (hex: string, amount?: number) => Hex;
 /**
  * Generates a lighter hex color by adding to each RGB channel (clamped)
  * @param hex - The hex color to lighten
  * @param amount - Amount to add to each channel (0..255-ish)
  */
-export declare const getLighterHexColor: (hex: string, amount?: number) => string;
+export declare const getLighterHexColor: (hex: string, amount?: number) => Hex;
 /**
  * Creates a brighter, more neon/vibrant version of a color.
  * Lightens the color while increasing saturation to create a neon effect.
@@ -60,7 +80,7 @@ export declare const getLighterHexColor: (hex: string, amount?: number) => strin
  * @param saturationTarget - Target saturation (0-1, default 0.75 = 75% saturation for vibrant look)
  * @returns A brighter, more saturated hex color
  */
-export declare const getBrighterPronouncedHexColor: (hex: string, lightnessTarget?: number, saturationTarget?: number) => string;
+export declare const getBrighterPronouncedHexColor: (hex: string, lightnessTarget?: number, saturationTarget?: number) => Hex;
 /**
  * Creates a darker but more pronounced/vibrant version of a color.
  * Darkens the color while increasing saturation to maintain vibrancy.
@@ -72,13 +92,26 @@ export declare const getBrighterPronouncedHexColor: (hex: string, lightnessTarge
  * @param saturationTarget - Target saturation (0-1, default 0.35 = 35% saturation for pronounced dark colors)
  * @returns A darker, more saturated hex color
  */
-export declare const getDarkerPronouncedHexColor: (hex: string, lightnessTarget?: number, saturationTarget?: number) => string;
+export declare const getDarkerPronouncedHexColor: (hex: string, lightnessTarget?: number, saturationTarget?: number) => Hex;
 /**
  * Random pastel color (soft, light, UI-friendly)
  */
-export declare const generateRandomPastelHexColor: () => string;
+export declare const generateRandomPastelHexColor: () => Hex;
 /**
  * Random vibrant color (saturated, bold, UI-friendly)
  * Generates colors similar to: #5D9CEC, #4FC1E9, #48CFAD, #A0D468, #FFCE54, #FC6E51, #ED5565, #AC92EC, #EC87C0
  */
-export declare const generateRandomVibrantHexColor: () => string;
+export declare const generateRandomVibrantHexColor: () => Hex;
+/** WCAG 2.x contrast ratio between two hex colors, from 1 (same) to 21 (black on white). Order-independent. */
+export declare const contrastRatio: (a: Hex, b: Hex) => number;
+/**
+ * Whether `fg` on `bg` meets WCAG AA: ≥ 4.5:1, or ≥ 3:1 when `isLargeText`.
+ * @param isLargeText - Text is ≥ 18pt, or ≥ 14pt bold. @default false
+ */
+export declare const meetsAA: (fg: Hex, bg: Hex, isLargeText?: boolean) => boolean;
+/**
+ * Per-channel sRGB interpolation `a·(1−t) + b·t`, rounded: `t = 0` is `a`, `t = 1` is `b`.
+ * The formula the token `subtle`/`strong` steps are derived with (Tokens Q3).
+ * @param t - Weight of `b`, clamped to 0–1.
+ */
+export declare const mix: (a: Hex, b: Hex, t: number) => Hex;