@ctrl-ui/react 0.8.0

package/dist/hooks/use-dynamic-notification.d.ts

@@ -0,0 +1,37 @@
+import { FormSubmitEvent, OpenChangeEventDetails, OpenChangeReason } from "../control-props.js";
+import { DynamicNotificationKnobStyle } from "../knob-contracts/dynamic-notification-knobs.js";
+import { CSSProperties, ComponentProps } from "react";
+//#region src/hooks/use-dynamic-notification.d.ts
+type DynamicNotificationVariant = "surface" | "glass" | "liquid";
+type DynamicNotificationReplyPayload = {
+  value: string;
+  clear: () => void;
+};
+type DynamicNotificationProps = Omit<ComponentProps<"div">, "onChange" | "style"> & {
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean, eventDetails: OpenChangeEventDetails) => void;
+  loading?: boolean;
+  replyValue?: string;
+  defaultReplyValue?: string;
+  onReplyValueChange?: (value: string) => void;
+  onReply?: (payload: DynamicNotificationReplyPayload) => void | Promise<void>;
+  variant?: DynamicNotificationVariant;
+  disabled?: boolean;
+  style?: CSSProperties & DynamicNotificationKnobStyle;
+};
+type DynamicNotificationController = {
+  open: boolean;
+  disabled: boolean;
+  setOpen: (nextOpen: boolean, reason: OpenChangeReason, event: Event, trigger?: Element) => void;
+  reply: string;
+  setReply: (nextValue: string) => void;
+  normalizedReply: string;
+  canSubmit: boolean;
+  clear: () => void;
+  submitReply: () => void;
+  handleReplySubmit: (event: FormSubmitEvent) => void;
+};
+declare function useDynamicNotification({ open, defaultOpen, onOpenChange, replyValue, defaultReplyValue, onReplyValueChange, onReply, disabled }: Pick<DynamicNotificationProps, "open" | "defaultOpen" | "onOpenChange" | "replyValue" | "defaultReplyValue" | "onReplyValueChange" | "onReply" | "disabled">): DynamicNotificationController;
+//#endregion
+export { DynamicNotificationController, DynamicNotificationProps, DynamicNotificationReplyPayload, DynamicNotificationVariant, useDynamicNotification };

package/dist/hooks/use-dynamic-notification.js

@@ -0,0 +1,87 @@
+import { useMemo, useState } from "react";
+//#region src/hooks/use-dynamic-notification.ts
+function createOpenChangeEventDetails(reason, event, trigger) {
+	let canceled = false;
+	let propagationAllowed = false;
+	return {
+		reason,
+		event,
+		cancel() {
+			canceled = true;
+		},
+		allowPropagation() {
+			propagationAllowed = true;
+		},
+		get isCanceled() {
+			return canceled;
+		},
+		get isPropagationAllowed() {
+			return propagationAllowed;
+		},
+		trigger
+	};
+}
+function useControllableText({ value, defaultValue = "", onValueChange }) {
+	const [internalValue, setInternalValue] = useState(defaultValue);
+	const isControlled = value !== void 0;
+	return [isControlled ? value : internalValue, useMemo(() => (nextValue) => {
+		if (!isControlled) setInternalValue(nextValue);
+		onValueChange?.(nextValue);
+	}, [isControlled, onValueChange])];
+}
+function useDynamicNotification({ open, defaultOpen = false, onOpenChange, replyValue, defaultReplyValue, onReplyValueChange, onReply, disabled = false }) {
+	const [internalOpen, setInternalOpen] = useState(defaultOpen);
+	const isControlled = open !== void 0;
+	const isOpen = isControlled ? open : internalOpen;
+	const [reply, setReply] = useControllableText({
+		value: replyValue,
+		defaultValue: defaultReplyValue,
+		onValueChange: onReplyValueChange
+	});
+	const normalizedReply = reply.trim();
+	const canSubmit = normalizedReply.length > 0 && !disabled;
+	const setOpen = useMemo(() => (nextOpen, reason, event, trigger) => {
+		if (disabled || nextOpen === isOpen) return;
+		const details = createOpenChangeEventDetails(reason, event, trigger);
+		onOpenChange?.(nextOpen, details);
+		if (details.isCanceled) return;
+		if (!isControlled) setInternalOpen(nextOpen);
+	}, [
+		disabled,
+		isControlled,
+		isOpen,
+		onOpenChange
+	]);
+	const clear = useMemo(() => () => {
+		setReply("");
+	}, [setReply]);
+	const submitReply = useMemo(() => () => {
+		if (!canSubmit) return;
+		onReply?.({
+			value: normalizedReply,
+			clear
+		});
+	}, [
+		canSubmit,
+		clear,
+		normalizedReply,
+		onReply
+	]);
+	return {
+		open: isOpen,
+		disabled,
+		setOpen,
+		reply,
+		setReply,
+		normalizedReply,
+		canSubmit,
+		clear,
+		submitReply,
+		handleReplySubmit: useMemo(() => (event) => {
+			event.preventDefault();
+			submitReply();
+		}, [submitReply])
+	};
+}
+//#endregion
+export { useDynamicNotification };

package/dist/hooks/use-environment-variables.d.ts

@@ -0,0 +1,51 @@
+import { EnvironmentVariableEntry } from "../lib/env-file.js";
+//#region src/hooks/use-environment-variables.d.ts
+type EnvironmentVariableRow = EnvironmentVariableEntry;
+type EnvironmentVariablesImportMode = "auto" | "bulk";
+interface UseEnvironmentVariablesOptions<TRow extends EnvironmentVariableRow = EnvironmentVariableRow> {
+  initialRows?: readonly TRow[];
+  rows?: readonly TRow[];
+  onRowsChange?: (rows: TRow[]) => void;
+  createDefaultRow?: () => TRow;
+  createRow?: (entry: EnvironmentVariableEntry) => TRow;
+  getEditableRows?: (rows: readonly TRow[]) => readonly TRow[];
+  getPreservedRows?: (rows: readonly TRow[]) => readonly TRow[];
+  maxUploadSize?: number;
+}
+interface EnvironmentVariablesFileUploadEvent {
+  target: {
+    files?: FileList | readonly File[] | null;
+    value: string;
+  };
+}
+interface EnvironmentVariablesImportOptions {
+  targetIndex?: number;
+  mode?: EnvironmentVariablesImportMode;
+}
+interface EnvironmentVariablesController<TRow extends EnvironmentVariableRow = EnvironmentVariableRow> {
+  rows: readonly TRow[];
+  uploadError: string | null;
+  duplicateKeys: Set<string>;
+  hasDuplicateKeys: boolean;
+  isDirty: boolean;
+  setRows: (rows: readonly TRow[]) => TRow[];
+  resetRows: (rows?: readonly TRow[]) => TRow[];
+  appendRow: (row?: TRow) => TRow[];
+  updateRow: (index: number, patch: Partial<EnvironmentVariableEntry>) => TRow[];
+  removeRow: (index: number) => TRow[];
+  getRowsForSubmit: () => TRow[];
+  getEnvironmentVariablesForSubmit: () => Record<string, string>;
+  getEnvFileTextForSubmit: () => string;
+  importText: (text: string, options?: EnvironmentVariablesImportOptions) => boolean;
+  handleFileUpload: (event: EnvironmentVariablesFileUploadEvent) => Promise<void>;
+  handlePaste: (index: number, text: string) => boolean;
+  clearUploadError: () => void;
+  getRowId: (index: number) => string;
+  isValueRevealed: (index: number) => boolean;
+  toggleValueVisibility: (index: number) => void;
+  rowHasDuplicateKey: (index: number) => boolean;
+}
+declare function useEnvironmentVariables<TRow extends EnvironmentVariableRow = EnvironmentVariableRow>(options?: UseEnvironmentVariablesOptions<TRow>): EnvironmentVariablesController<TRow>;
+declare function parseEnvironmentVariablesImportText(text: string, mode?: EnvironmentVariablesImportMode): EnvironmentVariableEntry[];
+//#endregion
+export { EnvironmentVariableRow, EnvironmentVariablesController, EnvironmentVariablesFileUploadEvent, EnvironmentVariablesImportMode, EnvironmentVariablesImportOptions, UseEnvironmentVariablesOptions, parseEnvironmentVariablesImportText, useEnvironmentVariables };

package/dist/hooks/use-environment-variables.js

@@ -0,0 +1,188 @@
+"use client";
+import { collectEnvironmentVariables, createEmptyEnvironmentVariableEntry, getDuplicateEnvironmentVariableKeys, parseEnvFileText, readEnvFile, rowsToEnvFileText } from "../lib/env-file.js";
+import { useRef, useState } from "react";
+//#region src/hooks/use-environment-variables.ts
+function defaultCreateRow(entry) {
+	return {
+		key: entry.key,
+		value: entry.value
+	};
+}
+function defaultEditableRows(rows) {
+	return rows;
+}
+function defaultPreservedRows() {
+	return [];
+}
+function normalizeRows(rows, createDefaultRow) {
+	return rows && rows.length > 0 ? rows.map((row) => ({ ...row })) : [createDefaultRow()];
+}
+function hasOnlyEmptyRow(rows) {
+	if (rows.length !== 1) return false;
+	const [firstRow] = rows;
+	if (!firstRow) return false;
+	return !firstRow.key.trim() && !firstRow.value;
+}
+function areRowsEqual(a, b) {
+	if (a.length !== b.length) return false;
+	for (let index = 0; index < a.length; index++) {
+		const aRow = a[index];
+		const bRow = b[index];
+		if (!aRow || !bRow || aRow.key !== bRow.key || aRow.value !== bRow.value) return false;
+	}
+	return true;
+}
+function useEnvironmentVariables({ initialRows, rows: controlledRows, onRowsChange, createDefaultRow = createEmptyEnvironmentVariableEntry, createRow = defaultCreateRow, getEditableRows = defaultEditableRows, getPreservedRows = defaultPreservedRows, maxUploadSize } = {}) {
+	const initialSourceRows = controlledRows ?? initialRows;
+	const nextRowId = useRef(0);
+	const fallbackRowIds = useRef({});
+	const [uncontrolledRows, setUncontrolledRows] = useState(() => normalizeRows(initialSourceRows, createDefaultRow));
+	const [baselineRows, setBaselineRows] = useState(() => normalizeRows(initialSourceRows, createDefaultRow));
+	const [rowIds, setRowIds] = useState(() => normalizeRows(initialSourceRows, createDefaultRow).map(() => createRowId()));
+	const [uploadError, setUploadError] = useState(null);
+	const [revealedValues, setRevealedValues] = useState({});
+	const rows = controlledRows ? normalizeRows(controlledRows, createDefaultRow) : uncontrolledRows;
+	const editableRows = (sourceRows = rows) => getEditableRows(sourceRows);
+	const preservedRows = (sourceRows = rows) => getPreservedRows(sourceRows);
+	function createRowId() {
+		const rowId = nextRowId.current;
+		nextRowId.current += 1;
+		return `environment-variable-row-${rowId}`;
+	}
+	function commitRows(nextRows, nextRowIds) {
+		const normalizedRows = normalizeRows(nextRows, createDefaultRow);
+		const normalizedRowIds = normalizedRows.map((_, index) => nextRowIds?.[index] ?? rowIds[index] ?? createRowId());
+		if (!controlledRows) setUncontrolledRows(normalizedRows);
+		setRowIds(normalizedRowIds);
+		onRowsChange?.(normalizedRows);
+		return normalizedRows;
+	}
+	function setRows(nextRows) {
+		return commitRows(nextRows);
+	}
+	function resetRows(nextRows = baselineRows) {
+		const normalizedRows = normalizeRows(nextRows, createDefaultRow);
+		commitRows(normalizedRows, normalizedRows.map(() => createRowId()));
+		setBaselineRows(normalizedRows);
+		setRevealedValues({});
+		setUploadError(null);
+		return normalizedRows;
+	}
+	function getRowsForSubmit() {
+		return [...rows];
+	}
+	function appendRow(row = createDefaultRow()) {
+		return commitRows([...rows, row], [...rowIds, createRowId()]);
+	}
+	function updateRow(index, patch) {
+		return commitRows(rows.map((row, rowIndex) => rowIndex === index ? {
+			...row,
+			...patch
+		} : row), rowIds);
+	}
+	function removeRow(index) {
+		const nextRows = rows.filter((_, rowIndex) => rowIndex !== index);
+		const nextRowIds = rowIds.filter((_, rowIndex) => rowIndex !== index);
+		setRevealedValues({});
+		return commitRows(nextRows.length > 0 ? nextRows : [createDefaultRow()], nextRows.length > 0 ? nextRowIds : [createRowId()]);
+	}
+	function mergeParsedRows(parsedRows, targetIndex) {
+		const newRows = parsedRows.map(createRow);
+		const newRowIds = newRows.map(() => createRowId());
+		if (hasOnlyEmptyRow(editableRows(rows))) {
+			const preserved = preservedRows(rows);
+			return commitRows([...preserved, ...newRows], [...rowIds.slice(0, preserved.length), ...newRowIds]);
+		}
+		if (typeof targetIndex !== "number") return commitRows([...rows, ...newRows], [...rowIds, ...newRowIds]);
+		const targetRow = rows[targetIndex];
+		if (!targetRow) return commitRows([...rows, ...newRows], [...rowIds, ...newRowIds]);
+		const targetIsEmpty = !targetRow.key.trim() && !targetRow.value;
+		const before = rows.slice(0, targetIndex + (targetIsEmpty ? 0 : 1));
+		const after = rows.slice(targetIndex + 1);
+		const beforeIds = rowIds.slice(0, targetIndex + (targetIsEmpty ? 0 : 1));
+		const afterIds = rowIds.slice(targetIndex + 1);
+		return commitRows([
+			...before,
+			...newRows,
+			...after
+		], [
+			...beforeIds,
+			...newRowIds,
+			...afterIds
+		]);
+	}
+	function importText(text, options = {}) {
+		const entries = parseEnvironmentVariablesImportText(text, options.mode ?? "bulk");
+		if (entries.length === 0) return false;
+		mergeParsedRows(entries, options.targetIndex);
+		setRevealedValues({});
+		setUploadError(null);
+		return true;
+	}
+	function handlePaste(index, text) {
+		return importText(text, {
+			targetIndex: index,
+			mode: "auto"
+		});
+	}
+	async function handleFileUpload(event) {
+		setUploadError(null);
+		const file = event.target.files?.[0];
+		if (!file) return;
+		const result = await readEnvFile(file, { maxSize: maxUploadSize });
+		if (!result.ok) {
+			setUploadError(result.error);
+			event.target.value = "";
+			return;
+		}
+		mergeParsedRows(result.entries);
+		setRevealedValues({});
+		event.target.value = "";
+	}
+	function getRowId(index) {
+		const rowId = rowIds[index] ?? fallbackRowIds.current[index];
+		if (rowId) return rowId;
+		const fallbackRowId = createRowId();
+		fallbackRowIds.current[index] = fallbackRowId;
+		return fallbackRowId;
+	}
+	const duplicateKeys = getDuplicateEnvironmentVariableKeys(rows);
+	const rowsDirty = !areRowsEqual(rows, baselineRows);
+	return {
+		rows,
+		uploadError,
+		duplicateKeys,
+		hasDuplicateKeys: duplicateKeys.size > 0,
+		isDirty: rowsDirty,
+		setRows,
+		resetRows,
+		appendRow,
+		updateRow,
+		removeRow,
+		getRowsForSubmit,
+		getEnvironmentVariablesForSubmit: () => collectEnvironmentVariables(getRowsForSubmit()),
+		getEnvFileTextForSubmit: () => rowsToEnvFileText(getRowsForSubmit()),
+		importText,
+		handleFileUpload,
+		handlePaste,
+		clearUploadError: () => setUploadError(null),
+		getRowId,
+		isValueRevealed: (index) => Boolean(revealedValues[index]),
+		toggleValueVisibility: (index) => setRevealedValues((previous) => ({
+			...previous,
+			[index]: !previous[index]
+		})),
+		rowHasDuplicateKey: (index) => duplicateKeys.has(rows[index]?.key.trim() ?? "")
+	};
+}
+function parseEnvironmentVariablesImportText(text, mode = "bulk") {
+	const trimmedText = text.trim();
+	if (!trimmedText.includes("=")) return [];
+	const entries = parseEnvFileText(trimmedText);
+	if (entries.length === 0) return [];
+	if (mode === "bulk") return entries;
+	const firstAssignmentLooksLikeEnvVar = /^(?:export\s+)?[A-Z_][A-Z0-9_]*\s*=/.test(trimmedText);
+	return entries.length > 1 || trimmedText.includes("\n") || firstAssignmentLooksLikeEnvVar ? entries : [];
+}
+//#endregion
+export { parseEnvironmentVariablesImportText, useEnvironmentVariables };

package/dist/hooks/use-mobile.d.ts

@@ -0,0 +1,5 @@
+//#region src/hooks/use-mobile.d.ts
+/** True below `breakpoint` px (Tailwind `md` by default); pass another breakpoint to match layout that switches elsewhere. */
+declare function useIsMobile(breakpoint?: number): boolean;
+//#endregion
+export { useIsMobile };

package/dist/hooks/use-mobile.js

@@ -0,0 +1,29 @@
+import { useSyncExternalStore } from "react";
+//#region src/hooks/use-mobile.ts
+const MOBILE_BREAKPOINT = 768;
+const viewportStores = /* @__PURE__ */ new Map();
+function viewportStore(breakpoint) {
+	const cached = viewportStores.get(breakpoint);
+	if (cached) return cached;
+	const mobileQuery = `(max-width: ${breakpoint - 1}px)`;
+	const store = {
+		subscribe(onChange) {
+			const query = window.matchMedia(mobileQuery);
+			query.addEventListener("change", onChange);
+			return () => query.removeEventListener("change", onChange);
+		},
+		getSnapshot: () => window.matchMedia(mobileQuery).matches
+	};
+	viewportStores.set(breakpoint, store);
+	return store;
+}
+function getServerViewportSnapshot() {
+	return false;
+}
+/** True below `breakpoint` px (Tailwind `md` by default); pass another breakpoint to match layout that switches elsewhere. */
+function useIsMobile(breakpoint = MOBILE_BREAKPOINT) {
+	const store = viewportStore(breakpoint);
+	return useSyncExternalStore(store.subscribe, store.getSnapshot, getServerViewportSnapshot);
+}
+//#endregion
+export { useIsMobile };

package/dist/hooks/use-textarea-trigger-menu.d.ts

@@ -0,0 +1,8 @@
+import { TriggerConfig, TriggerMenuController, TriggerMenuItemData } from "./use-trigger-menu.js";
+import { RefObject } from "react";
+//#region src/hooks/use-textarea-trigger-menu.d.ts
+declare function useTextareaTriggerMenu<Item extends TriggerMenuItemData>(ref: RefObject<HTMLTextAreaElement | null>, options: {
+  triggers: readonly TriggerConfig<Item>[];
+}): TriggerMenuController<Item>;
+//#endregion
+export { useTextareaTriggerMenu };

package/dist/hooks/use-textarea-trigger-menu.js

@@ -0,0 +1,69 @@
+"use client";
+import { caretRectInTextarea, detectTrigger } from "../lib/trigger-detect.js";
+import { useTriggerMenu } from "./use-trigger-menu.js";
+import { useEffect, useEffectEvent } from "react";
+//#region src/hooks/use-textarea-trigger-menu.ts
+function replaceRange(element, start, end, text) {
+	element.focus();
+	element.setSelectionRange(start, end);
+	if (document.execCommand("insertText", false, text)) return;
+	const next = element.value.slice(0, start) + text + element.value.slice(end);
+	(Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, "value")?.set)?.call(element, next);
+	element.dispatchEvent(new Event("input", { bubbles: true }));
+	const caret = start + text.length;
+	element.setSelectionRange(caret, caret);
+}
+function useTextareaTriggerMenu(ref, options) {
+	const controller = useTriggerMenu({
+		triggers: options.triggers,
+		onCommit: (item, trigger, match) => {
+			const element = ref.current;
+			if (!element) return;
+			const text = (trigger.insert ?? "replace") === "none" ? "" : trigger.insertText?.(item) ?? `${trigger.char}${item.label} `;
+			replaceRange(element, match.start, match.end, text);
+			trigger.onSelect?.(item, {
+				char: trigger.char,
+				query: match.query
+			});
+		}
+	});
+	const syncTrigger = useEffectEvent(() => {
+		const element = ref.current;
+		if (!element) return;
+		const caret = element.selectionStart ?? element.value.length;
+		const chars = options.triggers.map((trigger) => trigger.char);
+		const match = detectTrigger(element.value.slice(0, caret), chars);
+		controller.report(match, match === null ? null : caretRectInTextarea(element, match.start));
+	});
+	const handleKeyDown = useEffectEvent((event) => {
+		if (controller.open && controller.handleKeyDown(event.key)) event.preventDefault();
+	});
+	const closeAfterBlur = useEffectEvent(() => {
+		controller.close();
+	});
+	useEffect(() => {
+		const element = ref.current;
+		if (!element) return;
+		function onKeyDown(event) {
+			handleKeyDown(event);
+		}
+		function onBlur() {
+			window.setTimeout(closeAfterBlur, 120);
+		}
+		element.addEventListener("input", syncTrigger);
+		element.addEventListener("keydown", onKeyDown);
+		element.addEventListener("keyup", syncTrigger);
+		element.addEventListener("click", syncTrigger);
+		element.addEventListener("blur", onBlur);
+		return () => {
+			element.removeEventListener("input", syncTrigger);
+			element.removeEventListener("keydown", onKeyDown);
+			element.removeEventListener("keyup", syncTrigger);
+			element.removeEventListener("click", syncTrigger);
+			element.removeEventListener("blur", onBlur);
+		};
+	}, [ref]);
+	return controller;
+}
+//#endregion
+export { useTextareaTriggerMenu };

package/dist/hooks/use-trigger-menu.d.ts

@@ -0,0 +1,49 @@
+import { TriggerMatch } from "../lib/trigger-detect.js";
+import { ReactNode } from "react";
+//#region src/hooks/use-trigger-menu.d.ts
+type TriggerMenuItemData = {
+  id: string;
+  label: string;
+  description?: string;
+  icon?: ReactNode;
+  keywords?: readonly string[];
+  disabled?: boolean;
+  kind?: string;
+  image?: string;
+};
+type TriggerSelectContext = {
+  char: string;
+  query: string;
+};
+type TriggerConfig<Item extends TriggerMenuItemData = TriggerMenuItemData> = {
+  char: string;
+  items: readonly Item[] | ((query: string) => readonly Item[]);
+  filter?: (item: Item, query: string) => boolean;
+  insert?: "replace" | "none";
+  insertText?: (item: Item) => string;
+  onSelect?: (item: Item, ctx: TriggerSelectContext) => void;
+};
+type UseTriggerMenuOptions<Item extends TriggerMenuItemData> = {
+  triggers: readonly TriggerConfig<Item>[];
+  onCommit: (item: Item, trigger: TriggerConfig<Item>, match: TriggerMatch) => void;
+};
+type TriggerMenuController<Item extends TriggerMenuItemData> = {
+  open: boolean;
+  items: readonly Item[];
+  activeIndex: number;
+  anchorRect: DOMRect | null;
+  activeChar: string | null;
+  query: string;
+  /** Binding → engine: publish current trigger match (or null) and caret rect to anchor to. */
+  report: (match: TriggerMatch | null, anchorRect: DOMRect | null) => void;
+  /** Binding → engine: route keydown while open. Returns true when engine consumed key. */
+  handleKeyDown: (key: string) => boolean;
+  /** View → engine. */
+  setActiveIndex: (index: number) => void;
+  select: (item: Item) => void;
+  close: () => void;
+  setOpen: (open: boolean) => void;
+};
+declare function useTriggerMenu<Item extends TriggerMenuItemData>({ triggers, onCommit }: UseTriggerMenuOptions<Item>): TriggerMenuController<Item>;
+//#endregion
+export { TriggerConfig, TriggerMenuController, TriggerMenuItemData, TriggerSelectContext, UseTriggerMenuOptions, useTriggerMenu };

package/dist/hooks/use-trigger-menu.js

@@ -0,0 +1,102 @@
+import { useRef, useState } from "react";
+//#region src/hooks/use-trigger-menu.ts
+const CLOSED = {
+	open: false,
+	char: null,
+	query: "",
+	anchorRect: null,
+	activeIndex: 0
+};
+function matchesQuery(item, query) {
+	if (query === "") return true;
+	const needle = query.toLowerCase();
+	if (item.label.toLowerCase().includes(needle)) return true;
+	return (item.keywords ?? []).some((keyword) => keyword.toLowerCase().includes(needle));
+}
+function resolveItems(trigger, query) {
+	if (typeof trigger.items === "function") return trigger.items(query);
+	const filter = trigger.filter ?? matchesQuery;
+	return trigger.items.filter((item) => filter(item, query));
+}
+function useTriggerMenu({ triggers, onCommit }) {
+	const [state, setState] = useState(CLOSED);
+	const lastMatch = useRef(null);
+	const activeTrigger = state.char === null ? null : triggers.find((trigger) => trigger.char === state.char) ?? null;
+	const items = activeTrigger === null ? [] : resolveItems(activeTrigger, state.query);
+	function close() {
+		lastMatch.current = null;
+		setState(CLOSED);
+	}
+	function select(item) {
+		const match = lastMatch.current;
+		if (activeTrigger !== null && match !== null) onCommit(item, activeTrigger, match);
+		close();
+	}
+	function report(match, anchorRect) {
+		lastMatch.current = match;
+		const open = match !== null && triggers.some((trigger) => trigger.char === match.char);
+		setState((current) => {
+			if (!open || match === null) return CLOSED;
+			const activeIndex = current.char === match.char && current.query === match.query ? current.activeIndex : 0;
+			return {
+				open: true,
+				char: match.char,
+				query: match.query,
+				anchorRect,
+				activeIndex
+			};
+		});
+	}
+	function handleKeyDown(key) {
+		if (!state.open) return false;
+		if (key === "ArrowDown") {
+			setState((current) => ({
+				...current,
+				activeIndex: items.length === 0 ? 0 : (current.activeIndex + 1) % items.length
+			}));
+			return true;
+		}
+		if (key === "ArrowUp") {
+			setState((current) => ({
+				...current,
+				activeIndex: items.length === 0 ? 0 : (current.activeIndex - 1 + items.length) % items.length
+			}));
+			return true;
+		}
+		if (key === "Enter" || key === "Tab") {
+			const item = items[state.activeIndex];
+			if (item && !item.disabled) select(item);
+			return true;
+		}
+		if (key === "Escape") {
+			close();
+			return true;
+		}
+		return false;
+	}
+	function setOpen(open) {
+		if (!open) close();
+	}
+	function setActiveIndex(activeIndex) {
+		setState((current) => ({
+			...current,
+			activeIndex
+		}));
+	}
+	return {
+		open: state.open,
+		items,
+		activeIndex: state.activeIndex,
+		anchorRect: state.anchorRect,
+		activeChar: state.char,
+		query: state.query,
+		report,
+		handleKeyDown,
+		setActiveIndex,
+		select,
+		close,
+		setOpen
+	};
+}
+//#endregion
+export { useTriggerMenu };

package/dist/hooks/use-user-ask.d.ts

@@ -0,0 +1,48 @@
+import { UserAskKnobStyle } from "../knob-contracts/user-ask-knobs.js";
+import { CSSProperties, ComponentProps, KeyboardEvent, ReactNode } from "react";
+//#region src/hooks/use-user-ask.d.ts
+type UserAskAnswers = Record<string, string>;
+type UserAskProps = Omit<ComponentProps<"section">, "style"> & {
+  children?: ReactNode;
+  onComplete?: (answers: UserAskAnswers) => void;
+  onDismiss?: () => void;
+  style?: CSSProperties & UserAskKnobStyle;
+};
+type UserAskQuestionEntry = {
+  key: string;
+  id: string;
+  title: string;
+  defaultValue?: string;
+};
+type UserAskOptionEntry = {
+  key: string;
+  value: string;
+  disabled?: boolean;
+  /** Freeform options resolve to user's typed text instead of `value`. */
+  freeform?: boolean;
+};
+declare function useUserAsk({ onComplete, onDismiss }: Pick<UserAskProps, "onComplete" | "onDismiss">): {
+  questions: UserAskQuestionEntry[];
+  activeIndex: number;
+  activeQuestion: UserAskQuestionEntry;
+  canContinue: boolean;
+  isLastQuestion: boolean;
+  registerQuestion: (entry: UserAskQuestionEntry) => void;
+  unregisterQuestion: (key: string) => void;
+  registerOption: (questionId: string, entry: UserAskOptionEntry) => void;
+  unregisterOption: (questionId: string, key: string) => void;
+  optionsFor: (questionId: string) => UserAskOptionEntry[];
+  selectionFor: (questionId: string) => string | undefined;
+  isSelected: (questionId: string, optionKey: string) => boolean;
+  select: (questionId: string, optionKey: string) => void;
+  freeformTextFor: (questionId: string) => string;
+  setFreeformText: (questionId: string, text: string) => void;
+  answerFor: (questionId: string) => string | undefined;
+  resolveAnswers: () => UserAskAnswers;
+  goTo: (index: number) => void;
+  advance: () => void;
+  dismiss: () => void;
+  handleKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+};
+//#endregion
+export { UserAskAnswers, UserAskOptionEntry, UserAskProps, UserAskQuestionEntry, useUserAsk };