@ctrl-ui/react 0.8.0

package/dist/environment-variables.js

@@ -0,0 +1,492 @@
+"use client";
+import { cn } from "./lib/cn.js";
+import { Button } from "./ui/button.js";
+import { DUPLICATE_ENVIRONMENT_VARIABLE_MESSAGE, collectEnvironmentVariables, rowsToEnvFileText } from "./lib/env-file.js";
+import { useEnvironmentVariables } from "./hooks/use-environment-variables.js";
+import { Input } from "./ui/input.js";
+import { InputGroup, InputGroupAddon, InputGroupInput } from "./ui/input-group.js";
+import { createContext, use, useId } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { AlertTriangleIcon, EyeIcon, EyeOffIcon, FileUpIcon, PlusIcon, RotateCcwIcon, SaveIcon, Trash2Icon } from "lucide-react";
+//#region src/environment-variables.tsx
+const EnvironmentVariablesContext = createContext(null);
+function useEnvironmentVariablesContext(componentName) {
+	const context = use(EnvironmentVariablesContext);
+	if (!context) throw new Error(`${componentName} must be used inside <EnvironmentVariables.Root>.`);
+	return context;
+}
+function EnvironmentVariablesRoot({ editor, disabled = false, readOnly = false, rowErrors, keyLabel = "Key", valueLabel = "Value", keyPlaceholder = "OPENAI_API_KEY", valuePlaceholder = "sk-...", duplicateKeyMessage = DUPLICATE_ENVIRONMENT_VARIABLE_MESSAGE, onSubmit, className, children, ...props }) {
+	function handleSubmit(event) {
+		if (event.defaultPrevented || !onSubmit) return;
+		event.preventDefault();
+		if (editor.hasDuplicateKeys) return;
+		const rows = editor.getRowsForSubmit();
+		onSubmit({
+			rows,
+			variables: collectEnvironmentVariables(rows),
+			envFileText: rowsToEnvFileText(rows),
+			reset: () => editor.resetRows(rows)
+		});
+	}
+	return /* @__PURE__ */ jsx(EnvironmentVariablesContext.Provider, {
+		value: {
+			editor,
+			disabled,
+			readOnly,
+			rowErrors,
+			keyLabel,
+			valueLabel,
+			keyPlaceholder,
+			valuePlaceholder,
+			duplicateKeyMessage
+		},
+		children: /* @__PURE__ */ jsx("form", {
+			"data-control-ui": "environment-variables",
+			"data-control-family": "environment-variables",
+			"data-slot": "root",
+			"data-surface": "panel",
+			"data-disabled": disabled ? "true" : void 0,
+			"data-readonly": readOnly ? "true" : void 0,
+			className: cn("flex min-w-0 flex-col", className),
+			onSubmit: handleSubmit,
+			...props,
+			children
+		})
+	});
+}
+function EnvironmentVariablesComponent({ editor: providedEditor, initialRows, rows, onRowsChange, createDefaultRow, createRow, getEditableRows, getPreservedRows, maxUploadSize, title = "Environment variables", description, error, submitLabel = "Save", resetLabel = "Reset", addLabel = "Add variable", hideDefaultActions = false, children, onSubmit, ...props }) {
+	const internalEditor = useEnvironmentVariables({
+		initialRows,
+		rows,
+		onRowsChange,
+		createDefaultRow,
+		createRow,
+		getEditableRows,
+		getPreservedRows,
+		maxUploadSize
+	});
+	return /* @__PURE__ */ jsx(EnvironmentVariablesRoot, {
+		editor: providedEditor ?? internalEditor,
+		onSubmit,
+		...props,
+		children: children ?? /* @__PURE__ */ jsxs(Fragment$1, { children: [
+			/* @__PURE__ */ jsx(EnvironmentVariablesHeader, {
+				title,
+				description
+			}),
+			/* @__PURE__ */ jsx(EnvironmentVariablesToolbar, {}),
+			/* @__PURE__ */ jsx(EnvironmentVariablesUploadError, {}),
+			/* @__PURE__ */ jsx(EnvironmentVariablesRows, {}),
+			/* @__PURE__ */ jsx(EnvironmentVariablesDuplicateKeysError, {}),
+			/* @__PURE__ */ jsx(EnvironmentVariablesMessage, { error }),
+			!hideDefaultActions && /* @__PURE__ */ jsxs(EnvironmentVariablesActions, { children: [/* @__PURE__ */ jsx(EnvironmentVariablesAddButton, { children: addLabel }), /* @__PURE__ */ jsxs("div", {
+				className: "flex min-w-0 items-center",
+				children: [/* @__PURE__ */ jsx(EnvironmentVariablesResetButton, { children: resetLabel }), onSubmit ? /* @__PURE__ */ jsx(EnvironmentVariablesSubmitButton, { children: submitLabel }) : null]
+			})] })
+		] })
+	});
+}
+function EnvironmentVariablesHeader({ title, description, className, children, ...props }) {
+	if (children) return /* @__PURE__ */ jsx("div", {
+		"data-control-ui": "environment-variables",
+		"data-control-family": "environment-variables",
+		"data-slot": "header",
+		className: cn("flex flex-col", className),
+		...props,
+		children
+	});
+	if (!title && !description) return null;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-control-ui": "environment-variables",
+		"data-control-family": "environment-variables",
+		"data-slot": "header",
+		className: cn("flex flex-col", className),
+		...props,
+		children: [title ? /* @__PURE__ */ jsx("div", {
+			"data-control-ui": "environment-variables",
+			"data-control-family": "environment-variables",
+			"data-slot": "title",
+			children: title
+		}) : null, description ? /* @__PURE__ */ jsx("div", {
+			"data-control-ui": "environment-variables",
+			"data-control-family": "environment-variables",
+			"data-slot": "description",
+			className: "max-w-2xl",
+			children: description
+		}) : null]
+	});
+}
+function EnvironmentVariablesToolbar({ className, children, ...props }) {
+	const { readOnly } = useEnvironmentVariablesContext("EnvironmentVariables.Toolbar");
+	if (readOnly) return null;
+	return /* @__PURE__ */ jsx("div", {
+		"data-control-ui": "environment-variables",
+		"data-control-family": "environment-variables",
+		"data-slot": "toolbar",
+		className: cn("flex min-w-0 flex-col sm:flex-row sm:items-center", className),
+		...props,
+		children: children ?? /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsxs("p", {
+			"data-control-ui": "environment-variables",
+			"data-control-family": "environment-variables",
+			"data-slot": "hint",
+			className: "min-w-0 flex-1",
+			children: [
+				"Paste one or more",
+				" ",
+				/* @__PURE__ */ jsx("code", {
+					"data-control-ui": "environment-variables",
+					"data-control-family": "environment-variables",
+					"data-slot": "hint-code",
+					children: "KEY=value"
+				}),
+				" ",
+				"lines directly into any field."
+			]
+		}), /* @__PURE__ */ jsx(EnvironmentVariablesUploadButton, {})] })
+	});
+}
+function EnvironmentVariablesUploadButton({ inputLabel = "Import .env file", children = "Upload .env", variant = "surface", size = "sm", disabled, onClick, ...props }) {
+	const { editor, disabled: contextDisabled, readOnly } = useEnvironmentVariablesContext("EnvironmentVariables.UploadButton");
+	const inputId = useId();
+	const isDisabled = disabled ?? (contextDisabled || readOnly);
+	function handleChange(event) {
+		editor.handleFileUpload(event);
+	}
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("input", {
+		id: inputId,
+		type: "file",
+		accept: ".env,text/plain",
+		className: "sr-only",
+		disabled: isDisabled,
+		"aria-label": inputLabel,
+		onChange: handleChange
+	}), /* @__PURE__ */ jsxs(Button, {
+		type: "button",
+		variant,
+		size,
+		disabled: isDisabled,
+		onClick: (event) => {
+			onClick?.(event);
+			if (!event.defaultPrevented) event.currentTarget.ownerDocument.getElementById(inputId)?.click();
+		},
+		...props,
+		children: [/* @__PURE__ */ jsx(FileUpIcon, {
+			"aria-hidden": "true",
+			className: "size-3.5"
+		}), children]
+	})] });
+}
+function EnvironmentVariablesRows({ rowErrors, className, children, ...props }) {
+	const { editor, keyLabel, valueLabel, readOnly } = useEnvironmentVariablesContext("EnvironmentVariables.Rows");
+	return /* @__PURE__ */ jsx("div", {
+		"data-control-ui": "environment-variables",
+		"data-control-family": "environment-variables",
+		"data-slot": "rows",
+		className: cn("min-w-0", className),
+		...props,
+		children: children ?? /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsxs("div", {
+			"aria-hidden": "true",
+			"data-control-ui": "environment-variables",
+			"data-control-family": "environment-variables",
+			"data-slot": "column-labels",
+			className: cn("hidden min-w-0 grid-cols-[minmax(0,1fr)_minmax(0,1.2fr)_auto] sm:grid", readOnly && "grid-cols-[minmax(0,1fr)_minmax(0,1.2fr)]"),
+			children: [
+				/* @__PURE__ */ jsx("span", { children: keyLabel }),
+				/* @__PURE__ */ jsx("span", { children: valueLabel }),
+				!readOnly ? /* @__PURE__ */ jsx("span", { className: "size-[var(--control-h-sm)]" }) : null
+			]
+		}), editor.rows.map((row, index) => /* @__PURE__ */ jsx(EnvironmentVariablesRow, {
+			row,
+			index,
+			rowErrors
+		}, editor.getRowId(index)))] })
+	});
+}
+function EnvironmentVariablesRow({ row, index, rowErrors, className, ...props }) {
+	const { editor, disabled, readOnly, rowErrors: contextRowErrors, keyLabel, valueLabel, keyPlaceholder, valuePlaceholder, duplicateKeyMessage } = useEnvironmentVariablesContext("EnvironmentVariables.Row");
+	const resolvedRowErrors = rowErrors ?? contextRowErrors;
+	const keyError = resolvedRowErrors?.[index]?.key ?? (editor.rowHasDuplicateKey(index) ? duplicateKeyMessage : null);
+	const valueError = resolvedRowErrors?.[index]?.value;
+	const isDisabled = disabled || readOnly;
+	const rowId = editor.getRowId(index);
+	const keyInputId = `${rowId}-key`;
+	const valueInputId = `${rowId}-value`;
+	const revealValueLabel = editor.isValueRevealed(index) ? "Hide value" : "Show value";
+	const removeRowLabel = `Remove environment variable ${row.key.trim() || index + 1}`;
+	function handlePaste(event) {
+		if (editor.handlePaste(index, event.clipboardData.getData("text"))) event.preventDefault();
+	}
+	return /* @__PURE__ */ jsxs("div", {
+		"data-control-ui": "environment-variables",
+		"data-control-family": "environment-variables",
+		"data-slot": "row",
+		className: cn("relative grid min-w-0 sm:grid-cols-[minmax(0,1fr)_minmax(0,1.2fr)_auto]", className),
+		...props,
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex min-w-0 flex-col",
+				children: [
+					/* @__PURE__ */ jsx("label", {
+						"data-control-ui": "environment-variables",
+						"data-control-family": "environment-variables",
+						"data-slot": "field-label",
+						htmlFor: keyInputId,
+						className: "sm:sr-only",
+						children: keyLabel
+					}),
+					/* @__PURE__ */ jsx(Input, {
+						"data-control-ui": "environment-variables",
+						"data-control-family": "environment-variables",
+						"data-slot": "key-input",
+						id: keyInputId,
+						size: "sm",
+						value: row.key,
+						placeholder: keyPlaceholder,
+						disabled: isDisabled,
+						"aria-invalid": Boolean(keyError),
+						onChange: (event) => editor.updateRow(index, { key: event.target.value }),
+						onPaste: handlePaste
+					}),
+					keyError ? /* @__PURE__ */ jsx("p", {
+						"data-control-ui": "environment-variables",
+						"data-control-family": "environment-variables",
+						"data-slot": "field-error",
+						children: keyError
+					}) : null
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex min-w-0 flex-col",
+				children: [
+					/* @__PURE__ */ jsx("label", {
+						"data-control-ui": "environment-variables",
+						"data-control-family": "environment-variables",
+						"data-slot": "field-label",
+						htmlFor: valueInputId,
+						className: "sm:sr-only",
+						children: valueLabel
+					}),
+					/* @__PURE__ */ jsxs(InputGroup, {
+						"data-control-ui": "environment-variables",
+						"data-control-family": "environment-variables",
+						"data-slot": "value-group",
+						"data-invalid": valueError ? "true" : void 0,
+						size: "sm",
+						children: [/* @__PURE__ */ jsx(InputGroupInput, {
+							"data-control-ui": "environment-variables",
+							"data-control-family": "environment-variables",
+							"data-slot": "value-input",
+							id: valueInputId,
+							value: row.value,
+							placeholder: valuePlaceholder,
+							disabled: isDisabled,
+							"aria-invalid": Boolean(valueError),
+							type: editor.isValueRevealed(index) ? "text" : "password",
+							onChange: (event) => editor.updateRow(index, { value: event.target.value }),
+							onPaste: handlePaste
+						}), /* @__PURE__ */ jsx(InputGroupAddon, {
+							className: "pr-1",
+							children: /* @__PURE__ */ jsx(Button, {
+								type: "button",
+								variant: "quiet",
+								size: "sm",
+								iconOnly: true,
+								disabled: isDisabled,
+								"aria-label": revealValueLabel,
+								title: revealValueLabel,
+								onClick: () => editor.toggleValueVisibility(index),
+								children: editor.isValueRevealed(index) ? /* @__PURE__ */ jsx(EyeOffIcon, {
+									"aria-hidden": "true",
+									className: "size-3.5"
+								}) : /* @__PURE__ */ jsx(EyeIcon, {
+									"aria-hidden": "true",
+									className: "size-3.5"
+								})
+							})
+						})]
+					}),
+					valueError ? /* @__PURE__ */ jsx("p", {
+						"data-control-ui": "environment-variables",
+						"data-control-family": "environment-variables",
+						"data-slot": "field-error",
+						children: valueError
+					}) : null
+				]
+			}),
+			!readOnly ? /* @__PURE__ */ jsx(Button, {
+				type: "button",
+				variant: "quiet",
+				tone: "danger",
+				size: "sm",
+				iconOnly: true,
+				disabled,
+				"aria-label": removeRowLabel,
+				title: "Remove variable",
+				className: "absolute top-2 right-1 sm:static sm:justify-self-end sm:self-start",
+				onClick: () => editor.removeRow(index),
+				children: /* @__PURE__ */ jsx(Trash2Icon, {
+					"aria-hidden": "true",
+					className: "size-3.5"
+				})
+			}) : null
+		]
+	});
+}
+function EnvironmentVariablesAddButton({ children = "Add variable", variant = "surface", size = "sm", disabled, onClick, ...props }) {
+	const { editor, disabled: contextDisabled, readOnly } = useEnvironmentVariablesContext("EnvironmentVariables.AddButton");
+	if (readOnly) return null;
+	return /* @__PURE__ */ jsxs(Button, {
+		type: "button",
+		variant,
+		size,
+		disabled: disabled ?? contextDisabled,
+		onClick: (event) => {
+			onClick?.(event);
+			if (!event.defaultPrevented) editor.appendRow();
+		},
+		...props,
+		children: [/* @__PURE__ */ jsx(PlusIcon, {
+			"aria-hidden": "true",
+			className: "size-3.5"
+		}), children]
+	});
+}
+function EnvironmentVariablesResetButton({ children = "Reset", variant = "quiet", size = "sm", disabled, onClick, ...props }) {
+	const { editor, disabled: contextDisabled, readOnly } = useEnvironmentVariablesContext("EnvironmentVariables.ResetButton");
+	if (readOnly) return null;
+	return /* @__PURE__ */ jsxs(Button, {
+		type: "button",
+		variant,
+		size,
+		disabled: disabled ?? (contextDisabled || !editor.isDirty),
+		onClick: (event) => {
+			onClick?.(event);
+			if (!event.defaultPrevented) editor.resetRows();
+		},
+		...props,
+		children: [/* @__PURE__ */ jsx(RotateCcwIcon, {
+			"aria-hidden": "true",
+			className: "size-3.5"
+		}), children]
+	});
+}
+function EnvironmentVariablesSubmitButton({ children = "Save", variant = "solid", tone = "primary", size = "sm", disabled, ...props }) {
+	const { editor, disabled: contextDisabled, readOnly } = useEnvironmentVariablesContext("EnvironmentVariables.SubmitButton");
+	if (readOnly) return null;
+	return /* @__PURE__ */ jsxs(Button, {
+		type: "submit",
+		variant,
+		tone,
+		size,
+		disabled: disabled ?? (contextDisabled || editor.hasDuplicateKeys),
+		...props,
+		children: [/* @__PURE__ */ jsx(SaveIcon, {
+			"aria-hidden": "true",
+			className: "size-3.5"
+		}), children]
+	});
+}
+function EnvironmentVariablesActions({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-control-ui": "environment-variables",
+		"data-control-family": "environment-variables",
+		"data-slot": "actions",
+		className: cn("flex min-w-0 items-center justify-between", className),
+		...props
+	});
+}
+function EnvironmentVariablesMessage({ error, className, children, ...props }) {
+	const content = children ?? error;
+	if (!content) return null;
+	return /* @__PURE__ */ jsxs("div", {
+		role: "alert",
+		"data-control-ui": "environment-variables",
+		"data-control-family": "environment-variables",
+		"data-slot": "message",
+		className: cn("flex items-start", className),
+		...props,
+		children: [/* @__PURE__ */ jsx(AlertTriangleIcon, {
+			"aria-hidden": "true",
+			className: "mt-0.5 size-3.5 shrink-0"
+		}), /* @__PURE__ */ jsx("span", {
+			className: "min-w-0",
+			children: content
+		})]
+	});
+}
+function EnvironmentVariablesDuplicateKeysError({ message, ...props }) {
+	const { editor, duplicateKeyMessage } = useEnvironmentVariablesContext("EnvironmentVariables.DuplicateKeysError");
+	if (!editor.hasDuplicateKeys) return null;
+	return /* @__PURE__ */ jsx(EnvironmentVariablesMessage, {
+		error: message ?? duplicateKeyMessage,
+		...props
+	});
+}
+function EnvironmentVariablesUploadError(props) {
+	const { editor } = useEnvironmentVariablesContext("EnvironmentVariables.UploadError");
+	return /* @__PURE__ */ jsx(EnvironmentVariablesMessage, {
+		error: editor.uploadError,
+		...props
+	});
+}
+function EnvironmentVariablesReadOnlyList({ rows, emptyMessage = "No environment variables", className, children, ...props }) {
+	const context = use(EnvironmentVariablesContext);
+	const filledRows = (rows ?? context?.editor.rows ?? []).filter((row) => row.key.trim());
+	return /* @__PURE__ */ jsx("div", {
+		"data-control-ui": "environment-variables",
+		"data-control-family": "environment-variables",
+		"data-slot": "readonly-list",
+		className: cn("flex flex-col", className),
+		...props,
+		children: children ?? (filledRows.length > 0 ? filledRows.map((row) => /* @__PURE__ */ jsx(EnvironmentVariablesReadOnlyItem, {
+			name: row.key,
+			value: row.value
+		}, row.key)) : /* @__PURE__ */ jsx("div", {
+			"data-control-ui": "environment-variables",
+			"data-control-family": "environment-variables",
+			"data-slot": "empty",
+			children: emptyMessage
+		}))
+	});
+}
+function EnvironmentVariablesReadOnlyItem({ name, value = "********", revealed = false, className, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-control-ui": "environment-variables",
+		"data-control-family": "environment-variables",
+		"data-slot": "readonly-item",
+		className: cn("grid min-w-0 grid-cols-[minmax(0,0.9fr)_minmax(0,1.1fr)]", className),
+		...props,
+		children: [/* @__PURE__ */ jsx("span", {
+			"data-control-ui": "environment-variables",
+			"data-control-family": "environment-variables",
+			"data-slot": "readonly-key",
+			className: "min-w-0 truncate",
+			children: name
+		}), /* @__PURE__ */ jsx("span", {
+			"data-control-ui": "environment-variables",
+			"data-control-family": "environment-variables",
+			"data-slot": "readonly-value",
+			className: "min-w-0 truncate",
+			children: revealed ? value : "********"
+		})]
+	});
+}
+const EnvironmentVariables = Object.assign(EnvironmentVariablesComponent, {
+	Root: EnvironmentVariablesRoot,
+	Header: EnvironmentVariablesHeader,
+	Toolbar: EnvironmentVariablesToolbar,
+	UploadButton: EnvironmentVariablesUploadButton,
+	UploadError: EnvironmentVariablesUploadError,
+	Rows: EnvironmentVariablesRows,
+	Row: EnvironmentVariablesRow,
+	AddButton: EnvironmentVariablesAddButton,
+	ResetButton: EnvironmentVariablesResetButton,
+	SubmitButton: EnvironmentVariablesSubmitButton,
+	Actions: EnvironmentVariablesActions,
+	Message: EnvironmentVariablesMessage,
+	DuplicateKeysError: EnvironmentVariablesDuplicateKeysError,
+	ReadOnlyList: EnvironmentVariablesReadOnlyList,
+	ReadOnlyItem: EnvironmentVariablesReadOnlyItem
+});
+//#endregion
+export { EnvironmentVariables, EnvironmentVariablesActions, EnvironmentVariablesAddButton, EnvironmentVariablesDuplicateKeysError, EnvironmentVariablesHeader, EnvironmentVariablesMessage, EnvironmentVariablesReadOnlyItem, EnvironmentVariablesReadOnlyList, EnvironmentVariablesResetButton, EnvironmentVariablesRoot, EnvironmentVariablesRow, EnvironmentVariablesRows, EnvironmentVariablesSubmitButton, EnvironmentVariablesToolbar, EnvironmentVariablesUploadButton, EnvironmentVariablesUploadError };

package/dist/extensions/create-track-highlight.d.ts

@@ -0,0 +1,12 @@
+//#region src/extensions/create-track-highlight.d.ts
+type TrackHighlightOptions = {
+  /** Selector for highlightable rows, resolved within track. */
+  itemSelector: string;
+  /** Selector for resting row (active/selected) used when nothing is hovered. */
+  activeSelector: string;
+  range?: boolean;
+  followHover?: boolean;
+};
+declare function createTrackHighlight(track: HTMLElement, highlight: HTMLElement, options: TrackHighlightOptions, hoverHighlight?: HTMLElement): () => void;
+//#endregion
+export { TrackHighlightOptions, createTrackHighlight };

package/dist/extensions/create-track-highlight.js

@@ -0,0 +1,147 @@
+//#region src/extensions/create-track-highlight.ts
+const STABLE_EPSILON = .5;
+const MAX_FOLLOW_FRAMES = 90;
+function isHighlightable(node) {
+	return node instanceof HTMLElement && node.getAttribute("aria-disabled") !== "true" && node.getAttribute("data-disabled") !== "true" && node.checkVisibility();
+}
+function createTrackHighlight(track, highlight, options, hoverHighlight) {
+	const { itemSelector, activeSelector, range = false, followHover = true } = options;
+	let hovered = null;
+	let rafId = 0;
+	let followFrames = 0;
+	const activeLayer = {
+		ready: false,
+		last: {
+			x: 0,
+			y: 0,
+			w: 0,
+			h: 0
+		}
+	};
+	const hoverLayer = {
+		ready: false,
+		last: {
+			x: 0,
+			y: 0,
+			w: 0,
+			h: 0
+		}
+	};
+	function measureBox(target, trackRect) {
+		const rect = target.getBoundingClientRect();
+		return {
+			x: rect.left - trackRect.left + track.scrollLeft - track.clientLeft,
+			y: rect.top - trackRect.top + track.scrollTop - track.clientTop,
+			w: rect.width,
+			h: rect.height
+		};
+	}
+	function resolveActiveBox(trackRect) {
+		const actives = Array.from(track.querySelectorAll(activeSelector)).filter(isHighlightable);
+		const firstActive = actives[0];
+		if (!firstActive) return null;
+		if (!range) return measureBox(firstActive, trackRect);
+		let box = measureBox(firstActive, trackRect);
+		for (const active of actives.slice(1)) {
+			const b = measureBox(active, trackRect);
+			const left = Math.min(box.x, b.x);
+			const top = Math.min(box.y, b.y);
+			const right = Math.max(box.x + box.w, b.x + b.w);
+			const bottom = Math.max(box.y + box.h, b.y + b.h);
+			box = {
+				x: left,
+				y: top,
+				w: right - left,
+				h: bottom - top
+			};
+		}
+		return box;
+	}
+	function resolveHoveredBox(trackRect) {
+		if (!followHover || !hovered || !track.contains(hovered) || !isHighlightable(hovered)) return null;
+		return measureBox(hovered, trackRect);
+	}
+	function place(element, state, next, visible) {
+		if (!next) {
+			element.removeAttribute("data-visible");
+			return false;
+		}
+		const moved = Math.abs(next.x - state.last.x) > STABLE_EPSILON || Math.abs(next.y - state.last.y) > STABLE_EPSILON || Math.abs(next.w - state.last.w) > STABLE_EPSILON || Math.abs(next.h - state.last.h) > STABLE_EPSILON;
+		state.last = next;
+		if (!state.ready) element.style.transition = "none";
+		element.style.left = `${next.x}px`;
+		element.style.top = `${next.y}px`;
+		element.style.right = `${track.clientWidth - (next.x + next.w)}px`;
+		element.style.bottom = `${track.clientHeight - (next.y + next.h)}px`;
+		element.toggleAttribute("data-visible", visible);
+		if (!state.ready) {
+			element.offsetWidth;
+			element.style.transition = "";
+			state.ready = true;
+		}
+		return moved;
+	}
+	function placeHighlightLayers() {
+		const trackRect = track.getBoundingClientRect();
+		const activeBox = resolveActiveBox(trackRect);
+		const hoveredBox = resolveHoveredBox(trackRect);
+		const isAway = hoveredBox !== null && hovered !== null && !hovered.matches(activeSelector);
+		track.toggleAttribute("data-track-hover", isAway);
+		const activeMoved = place(highlight, activeLayer, hoverHighlight ? activeBox : hoveredBox ?? activeBox, Boolean(activeBox || hoveredBox));
+		if (!hoverHighlight) highlight.toggleAttribute("data-hover", isAway);
+		const hoverMoved = hoverHighlight ? place(hoverHighlight, hoverLayer, hoveredBox ?? activeBox, Boolean(hoveredBox)) : false;
+		return activeMoved || hoverMoved;
+	}
+	function scheduleFollow() {
+		followFrames = 0;
+		if (rafId) return;
+		const step = () => {
+			rafId = 0;
+			if (!placeHighlightLayers() || followFrames >= MAX_FOLLOW_FRAMES) return;
+			followFrames += 1;
+			rafId = requestAnimationFrame(step);
+		};
+		rafId = requestAnimationFrame(step);
+	}
+	const onPointerOver = (event) => {
+		if (event.pointerType === "touch" || !(event.target instanceof Element)) return;
+		const item = event.target.closest(itemSelector);
+		if (!isHighlightable(item) || !track.contains(item) || item === hovered) return;
+		hovered = item;
+		scheduleFollow();
+	};
+	const onPointerLeave = () => {
+		if (!hovered) return;
+		hovered = null;
+		scheduleFollow();
+	};
+	if (followHover) {
+		track.addEventListener("pointerover", onPointerOver);
+		track.addEventListener("pointerleave", onPointerLeave);
+	}
+	const resizeObserver = new ResizeObserver(() => scheduleFollow());
+	resizeObserver.observe(track);
+	const mutationObserver = new MutationObserver(() => scheduleFollow());
+	mutationObserver.observe(track, {
+		subtree: true,
+		childList: true,
+		attributes: true,
+		attributeFilter: [
+			"data-selected",
+			"aria-selected",
+			"data-active",
+			"data-state"
+		]
+	});
+	scheduleFollow();
+	return () => {
+		if (rafId) cancelAnimationFrame(rafId);
+		track.removeEventListener("pointerover", onPointerOver);
+		track.removeEventListener("pointerleave", onPointerLeave);
+		track.removeAttribute("data-track-hover");
+		resizeObserver.disconnect();
+		mutationObserver.disconnect();
+	};
+}
+//#endregion
+export { createTrackHighlight };

package/dist/extensions/track-highlight.d.ts

@@ -0,0 +1,22 @@
+import { TrackHighlightKnobStyle } from "../knob-contracts/track-highlight-knobs.js";
+import { CSSProperties, ComponentProps, ReactNode, RefObject } from "react";
+//#region src/extensions/track-highlight.d.ts
+type TrackHighlightProps = Omit<ComponentProps<"div">, "children" | "ref" | "style"> & {
+  /** Track container (`relative isolate`) highlight is measured against. Defaults to highlight's parent element. */
+  trackRef?: RefObject<HTMLElement | null>;
+  /** Selector for highlightable rows, resolved within track. */
+  itemSelector?: string;
+  /** Selector for resting row (active/selected) used when nothing is hovered. */
+  activeSelector?: string;
+  /** Span box across union of every active row (first..last) instead of single row. */
+  range?: boolean;
+  /** Follow pointer to hovered row; turn off for purely selection/scroll-driven box. */
+  followHover?: boolean;
+  /** Non-empty = second layer that follows hover while primary layer stays pinned on selection. */
+  hoverClassName?: string;
+  children?: ReactNode;
+  style?: CSSProperties & TrackHighlightKnobStyle;
+};
+declare function TrackHighlight({ trackRef, itemSelector, activeSelector, range, followHover, hoverClassName, className, style, children, ...props }: TrackHighlightProps): import("react").JSX.Element;
+//#endregion
+export { TrackHighlight, TrackHighlightProps };