@deftui/react 0.2.5 → 0.3.1

package/dist/vendor/reui.io/cascader/cascader.mjs

@@ -0,0 +1,1470 @@
+"use client";
+import { useCascaderLoadState, useCascaderLoader } from "./cascader-async.mjs";
+import { CascaderActionsContext, CascaderHighlightContext, CascaderRenderContext, CascaderStateContext, createCascaderHighlightStore, useCascaderActions, useCascaderState } from "./cascader-context.mjs";
+import { resolveCascaderLabels } from "./cascader-i18n.mjs";
+import { CASCADER_LIST_HEIGHT_CLASS, CASCADER_LIST_PAD_CLASS, CASCADER_ROOT_KEY, CASCADER_ROWS_CLASS, CASCADER_SCROLL_CLASS, applyCascadeSelection, buildCascaderIndex, collapseCascaderPath, createCascaderMoreNode, filterCascaderLevel, findAmbiguousCascaderLabels, findCascaderDataIssues, flattenCascaderTree, focusCascaderHome, getCascaderCheckedValues, getCascaderChildren, getCascaderCount, getCascaderIndeterminateFrom, getCascaderListedValues, getCascaderPath, getCascaderSelectedDescendants, getCascaderTabTarget, isCascaderBranch, isCascaderDisabled, isCascaderMoreNode, isCascaderSelectable, matchesCascaderQuery, mergeCascaderIndex, normalizeCascaderQuery, searchCascaderDeep, warnCascaderOnce, withCascaderMoreRow } from "./cascader-lib.mjs";
+import { ScrollArea } from "../../coss/scroll-area.mjs";
+import { cn } from "cn";
+import { mergeProps } from "@base-ui/react/merge-props";
+import * as React$1 from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useRender } from "@base-ui/react/use-render";
+import { ChevronDownIcon, XIcon } from "lucide-react";
+import { Combobox } from "@base-ui/react";
+// src/vendor/reui.io/cascader/cascader.tsx
+/** Stable `filteredItems` for a level swap; a fixed identity cannot loop. */
+const EMPTY = [];
+/** Stable empty array for the `actions` prop, so a cascader with no footer
+* does not republish the actions context on every render. */
+const EMPTY_ACTIONS = [];
+/** The `onSearch` scope of a global search: no path, so the whole tree. */
+const GLOBAL_SEARCH_PATH = [];
+const ANNOUNCE_MARKER = "⁠";
+const ANNOUNCE_DEBOUNCE = 150;
+function useControllable(controlled, defaultValue, onChange, devName) {
+	const [uncontrolled, setUncontrolled] = React$1.useState(defaultValue);
+	const isControlled = controlled !== void 0;
+	const value = isControlled ? controlled : uncontrolled;
+	const wasControlled = React$1.useRef(isControlled);
+	React$1.useEffect(() => {
+		if (process.env.NODE_ENV === "production") return;
+		if (wasControlled.current === isControlled || !devName) return;
+		const from = wasControlled.current ? "controlled" : "uncontrolled";
+		const to = isControlled ? "controlled" : "uncontrolled";
+		wasControlled.current = isControlled;
+		warnCascaderOnce(`controlled-switch:${devName}`, `\`${devName}\` switched from ${from} to ${to}. Decide once: pass \`${devName}\` for the whole life of the component, or pass only the default and let the cascader own it.`);
+	}, [isControlled, devName]);
+	const latest = React$1.useRef({
+		value,
+		isControlled,
+		onChange
+	});
+	React$1.useEffect(() => {
+		latest.current = {
+			value,
+			isControlled,
+			onChange
+		};
+	});
+	const lastProp = React$1.useRef(controlled);
+	React$1.useEffect(() => {
+		lastProp.current = controlled;
+	});
+	return [value, React$1.useCallback((next) => {
+		const current = latest.current.value;
+		const resolved = typeof next === "function" ? next(current) : next;
+		if (Object.is(resolved, current)) {
+			if (!latest.current.isControlled || Object.is(resolved, lastProp.current)) return;
+		}
+		latest.current = {
+			...latest.current,
+			value: resolved
+		};
+		if (!latest.current.isControlled) setUncontrolled(resolved);
+		latest.current.onChange?.(resolved);
+	}, [])];
+}
+function shallowEqualRecords(a, b) {
+	const left = a;
+	const right = b;
+	const keys = Object.keys(left);
+	if (keys.length !== Object.keys(right).length) return false;
+	for (const key of keys) if (!Object.is(left[key], right[key])) return false;
+	return true;
+}
+function shallowEqualItemLists(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i] && !shallowEqualRecords(a[i], b[i])) return false;
+	return true;
+}
+function useShallowStable(value, equal) {
+	const [stable, setStable] = React$1.useState(value);
+	if (Object.is(value, stable)) return stable;
+	if (typeof value === "object" && value !== null && typeof stable === "object" && stable !== null && equal(value, stable)) return stable;
+	setStable(value);
+	return value;
+}
+/** Normalizes to an array. `""` is "no selection", not a node: it is the
+* uncontrolled default, and resolving it would render a blank chip. */
+function toArray(value) {
+	if (value == null) return [];
+	if (Array.isArray(value)) return value.filter((entry) => entry !== "");
+	return value === "" ? [] : [value];
+}
+/** Misconfigurations that are SILENT by design. Once each, never in prod. */
+function useCascaderDevWarnings(options) {
+	const { items, getParent, mode, multiple, cascade, indicator, selectable, searchScope, max, value, defaultValue, hasExpanded, hasPath, hasOnSearch } = options;
+	const issues = React$1.useMemo(() => process.env.NODE_ENV === "production" ? null : findCascaderDataIssues(items, getParent), [items, getParent]);
+	React$1.useEffect(() => {
+		if (process.env.NODE_ENV === "production") return;
+		for (const duplicate of issues?.duplicates ?? []) warnCascaderOnce(`duplicate-value:${duplicate}`, `Duplicate node value ${JSON.stringify(duplicate)}. \`value\` is the selection key, so only the first occurrence is indexed and the rest never render.`);
+		for (const cycle of issues?.cycles ?? []) warnCascaderOnce(`cycle:${cycle}`, `\`getParent\` puts ${JSON.stringify(cycle)} on a cycle. The depth walk is cycle-guarded so nothing hangs, but every depth on that chain is clamped rather than derived.`);
+	}, [issues]);
+	React$1.useEffect(() => {
+		if (process.env.NODE_ENV === "production") return;
+		for (const [prop, current] of [["value", value], ["defaultValue", defaultValue]]) {
+			if (current == null) continue;
+			if (multiple && !Array.isArray(current)) warnCascaderOnce(`value-shape:multiple:${prop}`, `\`multiple\` is set but \`${prop}\` is a string. Multi-select reads and writes a \`string[]\`; a string is treated as no selection at all.`);
+			else if (!multiple && Array.isArray(current)) warnCascaderOnce(`value-shape:single:${prop}`, `\`${prop}\` is an array but \`multiple\` is not set. Single-select reads and writes a \`string\`; only the first entry would survive a commit.`);
+		}
+		if (cascade && !multiple) warnCascaderOnce("cascade-without-multiple", "`cascade` does nothing without `multiple`: a single selection has no subtree to propagate over.");
+		if (cascade && selectable === "leaf") warnCascaderOnce("cascade-with-leaf-selectable", "`cascade` does nothing while `selectable=\"leaf\"`: no branch can be committed, so no commit ever has a subtree under it. Pass `selectable=\"any\"` or a predicate that accepts branches.");
+		if (!indicator && multiple) warnCascaderOnce("indicator-false-with-multiple", "`indicator={false}` does nothing with `multiple`: the checkbox is the selection control rather than a decoration, so it and its gutter stay. Mark selection your own way from `data-selected` on the row, and drop the prop.");
+		if (max != null && !multiple) warnCascaderOnce("max-without-multiple", "`max` does nothing without `multiple`: there is only ever one selection to cap.");
+		if (hasExpanded && mode !== "tree") warnCascaderOnce(`expanded-outside-tree:${mode}`, `\`expanded\` only does something in \`mode="tree"\`, and this cascader is in \`mode="${mode}"\`. Drill and columns navigate with \`path\`.`);
+		if (hasPath && mode === "tree") warnCascaderOnce("path-in-tree", "`path` does nothing in `mode=\"tree\"`: branches expand in place rather than replacing the level. Use `expanded`.");
+		if (searchScope === "deep" && mode === "tree") warnCascaderOnce("deep-search-in-tree", "`searchScope=\"deep\"` does nothing in `mode=\"tree\"`: a tree query already matches at any depth and auto-expands the ancestors of every hit.");
+		if (searchScope === "global" && mode === "tree") warnCascaderOnce("global-search-in-tree", "`searchScope=\"global\"` does nothing in `mode=\"tree\"`: a tree query already searches the whole tree and auto-expands the ancestors of every hit.");
+		if (hasOnSearch && mode === "tree") warnCascaderOnce("onsearch-in-tree", "`onSearch` does nothing in `mode=\"tree\"`: a tree query filters the loaded tree in place, and a server hit belongs to no visible branch, so its results would never render. The request is not fired. Filter the tree locally, or use drill or columns for server search.");
+	}, [
+		mode,
+		multiple,
+		cascade,
+		indicator,
+		selectable,
+		searchScope,
+		max,
+		value,
+		defaultValue,
+		hasExpanded,
+		hasPath,
+		hasOnSearch
+	]);
+}
+/** No default on `T`: inferred from `items`, so `node.data` arrives typed. */
+function Cascader({ items, getParent, getChildren, onSearch, searchDebounce, resolveValue, loadKey, prefetch, onLoadError, value: valueProp, defaultValue, onValueChange: onValueChangeProp, multiple = false, selectable = "leaf", indicator = true, actions, cascade = false, max, mode = "drill", expandTrigger, path: pathProp, defaultPath, onPathChange, expanded: expandedProp, defaultExpanded, onExpandedChange, open: openProp, defaultOpen = false, onOpenChange, closeOnSelect = true, inputValue: inputValueProp, defaultInputValue = "", onInputValueChange, searchScope = "level", filter, revealSelected = true, maxHeight, virtualize, virtualizeThreshold = 100, estimateRowSize = 32, overscan = 8, labels: labelsProp, renderItem, renderLabel, disabled, name, form, id, required, readOnly, invalid, inputRef, inline, children }) {
+	const baseIndex = React$1.useMemo(() => buildCascaderIndex(items, getParent), [items]);
+	const baseId = React$1.useId();
+	const stableLabelsProp = useShallowStable(labelsProp, shallowEqualRecords);
+	const labels = React$1.useMemo(() => resolveCascaderLabels(stableLabelsProp), [stableLabelsProp]);
+	useCascaderDevWarnings({
+		items,
+		getParent,
+		mode,
+		multiple,
+		cascade,
+		indicator,
+		selectable,
+		searchScope,
+		max,
+		value: valueProp,
+		defaultValue,
+		hasExpanded: expandedProp !== void 0 || defaultExpanded !== void 0 || onExpandedChange !== void 0,
+		hasPath: pathProp !== void 0 || defaultPath !== void 0 || onPathChange !== void 0,
+		hasOnSearch: onSearch !== void 0
+	});
+	const onValueChange = onValueChangeProp;
+	const [value, setValue] = useControllable(valueProp, defaultValue ?? (multiple ? [] : ""), void 0, "value");
+	const pathReasonRef = React$1.useRef("external");
+	const openReasonRef = React$1.useRef("none");
+	const [path, setPath] = useControllable(pathProp, defaultPath ?? [], (next) => onPathChange?.(next, { reason: pathReasonRef.current }), "path");
+	const [expandedList, setExpandedList] = useControllable(expandedProp, defaultExpanded ?? [], onExpandedChange, "expanded");
+	const [open, setOpen] = useControllable(openProp, defaultOpen, (next) => onOpenChange?.(next, { reason: openReasonRef.current }), "open");
+	/** The internal `setPath`: names its reason, then hands back to "external". */
+	const setPathWithReason = React$1.useCallback((next, reason) => {
+		pathReasonRef.current = reason;
+		try {
+			setPath(next);
+		} finally {
+			pathReasonRef.current = "external";
+		}
+	}, [setPath]);
+	const [query, setQuery] = useControllable(inputValueProp, defaultInputValue, onInputValueChange, "inputValue");
+	const expanded = React$1.useMemo(() => new Set(expandedList), [expandedList]);
+	const selectedValues = React$1.useMemo(() => toArray(value), [value]);
+	const levels = React$1.useMemo(() => {
+		if (mode === "tree") return [CASCADER_ROOT_KEY, ...expandedList];
+		if (mode === "columns") return [CASCADER_ROOT_KEY, ...path];
+		return [path.length ? path[path.length - 1] : CASCADER_ROOT_KEY];
+	}, [
+		mode,
+		path,
+		expandedList
+	]);
+	const loader = useCascaderLoader({
+		base: baseIndex,
+		getChildren,
+		onSearch: mode === "tree" ? void 0 : onSearch,
+		resolveValue,
+		searchDebounce,
+		loadKey,
+		prefetch,
+		onLoadError,
+		enabled: open || !!inline,
+		query,
+		levels,
+		path: searchScope === "global" ? GLOBAL_SEARCH_PATH : path,
+		values: selectedValues
+	});
+	const loadStates = loader.states;
+	const { ensureLevel, retryLevel: retryLoaderLevel, invalidateLevel } = loader;
+	/**
+	* Whether pressing this branch has to FETCH first: in flight, failed, or
+	* never asked. `baseIndex`, as `ensureLevel` asks it: the two must agree or a
+	* press parks a navigation nothing will ever settle.
+	*/
+	const needsChildren = React$1.useCallback((node) => {
+		if (!loader.active) return false;
+		const state = loadStates.get(node.value);
+		if (state) return state.loading || state.error;
+		return !baseIndex.childrenOf.has(node.value);
+	}, [
+		loader.active,
+		loadStates,
+		baseIndex
+	]);
+	const pagingKey = JSON.stringify(Array.from(loadStates).filter(([, state]) => state.hasMore).map(([key]) => key));
+	const paging = React$1.useMemo(() => new Set(JSON.parse(pagingKey)), [pagingKey]);
+	const { pages, detached, links } = loader.store;
+	const index = React$1.useMemo(() => mergeCascaderIndex(baseIndex, pages, detached, links, paging), [
+		baseIndex,
+		pages,
+		detached,
+		links,
+		paging
+	]);
+	/** Whether a level needs the paging pseudo-row. A never-fetched level gets
+	* nothing; that is the empty state's job. Tree has no per-level empty state,
+	* so there the row is also the branch's loading and error surface. */
+	const needsMoreRow = React$1.useCallback((key, childCount) => {
+		const state = loadStates.get(key);
+		if (!state) return false;
+		if (childCount > 0) return state.hasMore || state.loading || state.error;
+		return mode === "tree" && (state.loading || state.error);
+	}, [loadStates, mode]);
+	const labelCacheRef = React$1.useRef(/* @__PURE__ */ new Map());
+	for (const selected of selectedValues) {
+		const node = index.byValue.get(selected);
+		if (node) labelCacheRef.current.set(selected, node);
+	}
+	const resolveNode = React$1.useCallback((nodeValue) => index.byValue.get(nodeValue) ?? labelCacheRef.current.get(nodeValue) ?? {
+		value: nodeValue,
+		label: nodeValue
+	}, [index]);
+	const currentParentValue = path.length ? path[path.length - 1] : null;
+	const currentParent = currentParentValue ? index.byValue.get(currentParentValue) ?? null : null;
+	const currentLevelKey = currentParentValue ?? "\0root";
+	const isDeepSearching = (searchScope === "deep" || searchScope === "global") && query.trim().length > 0 && mode !== "tree";
+	const deepSearchWithin = searchScope === "global" ? null : currentParentValue;
+	const localDeepResults = React$1.useMemo(() => {
+		if (!isDeepSearching) return null;
+		return searchCascaderDeep(index, query, {
+			within: deepSearchWithin,
+			matches: filter
+		});
+	}, [
+		isDeepSearching,
+		index,
+		query,
+		deepSearchWithin,
+		filter
+	]);
+	const deepResults = loader.searchResults ?? localDeepResults;
+	const levelItems = React$1.useMemo(() => {
+		const level = getCascaderChildren(index, currentParentValue);
+		return filterCascaderLevel(level, query, filter);
+	}, [
+		index,
+		currentParentValue,
+		query,
+		filter
+	]);
+	/** The active level's rows plus the paging pseudo-row, appended HERE because
+	* every index Base UI hands out indexes this array: a DOM row missing from
+	* it shifts the highlight and every windowed row by one. */
+	const levelRendered = React$1.useMemo(() => {
+		if (deepResults) return deepResults;
+		if (!needsMoreRow(currentLevelKey, levelItems.length)) return levelItems;
+		return withCascaderMoreRow(levelItems, createCascaderMoreNode(currentLevelKey, levelItems.length), index.pinned);
+	}, [
+		deepResults,
+		levelItems,
+		currentLevelKey,
+		needsMoreRow,
+		index.pinned
+	]);
+	const columns = React$1.useMemo(() => {
+		if (mode !== "columns") return [];
+		const trail = [];
+		for (let depth = 0; depth <= path.length; depth += 1) {
+			const parentValue = depth === 0 ? null : path[depth - 1];
+			const parent = parentValue ? index.byValue.get(parentValue) ?? null : null;
+			const isActive = depth === path.length;
+			let columnItems;
+			if (isActive) columnItems = levelRendered;
+			else {
+				const key = parentValue ?? "\0root";
+				const children = getCascaderChildren(index, parentValue);
+				columnItems = needsMoreRow(key, children.length) ? withCascaderMoreRow(children, createCascaderMoreNode(key, children.length), index.pinned) : children;
+			}
+			trail.push({
+				parent,
+				depth,
+				activeValue: path[depth] ?? null,
+				active: isActive,
+				items: columnItems
+			});
+		}
+		return trail;
+	}, [
+		mode,
+		path,
+		index,
+		levelRendered,
+		needsMoreRow
+	]);
+	const treeSentinels = React$1.useMemo(() => {
+		if (mode !== "tree") return void 0;
+		const keys = /* @__PURE__ */ new Set();
+		const consider = (key) => {
+			if (needsMoreRow(key, index.childrenOf.get(key)?.length ?? 0)) keys.add(key);
+		};
+		consider(CASCADER_ROOT_KEY);
+		for (const value of expanded) consider(value);
+		return keys.size ? keys : void 0;
+	}, [
+		mode,
+		index,
+		expanded,
+		needsMoreRow
+	]);
+	const treeRows = React$1.useMemo(() => {
+		if (mode !== "tree") return [];
+		const rows = flattenCascaderTree(index, expanded, treeSentinels);
+		const normalized = normalizeCascaderQuery(query);
+		if (!normalized) return rows;
+		const keep = /* @__PURE__ */ new Set();
+		const listed = getCascaderListedValues(index);
+		for (const node of index.all) {
+			if (!listed.has(node.value)) continue;
+			if (!(filter ? filter(node, normalized) : matchesCascaderQuery(node, normalized))) continue;
+			for (const ancestor of getCascaderPath(index, node.value)) keep.add(ancestor.value);
+		}
+		return flattenCascaderTree(index, /* @__PURE__ */ new Set([...expanded, ...keep])).filter((row) => keep.has(row.node.value));
+	}, [
+		mode,
+		index,
+		expanded,
+		treeSentinels,
+		query,
+		filter
+	]);
+	const renderedItems = React$1.useMemo(() => mode === "tree" ? treeRows.map((row) => row.node) : levelRendered, [
+		mode,
+		treeRows,
+		levelRendered
+	]);
+	/** Base UI never resets the highlighted index on an `items` change and has
+	* no imperative setter; its one automatic reset is an out-of-range clamp, so
+	* a single empty frame trips it. The frame rides `filteredItems`, so the
+	* `items` identity stays put. */
+	const levelKey = currentParentValue ?? "";
+	const [swap, setSwap] = React$1.useState({
+		key: levelKey,
+		active: false
+	});
+	if (swap.key !== levelKey) setSwap({
+		key: levelKey,
+		active: true
+	});
+	const swapping = swap.active && swap.key === levelKey;
+	React$1.useLayoutEffect(() => {
+		if (swap.active) setSwap((prev) => ({
+			...prev,
+			active: false
+		}));
+	}, [swap.active]);
+	const resetHighlight = React$1.useCallback(() => {
+		setSwap((prev) => prev.active ? prev : {
+			...prev,
+			active: true
+		});
+	}, []);
+	const [virtualRenderers, setVirtualRenderers] = React$1.useState(0);
+	const registerVirtualRenderer = React$1.useCallback(() => {
+		setVirtualRenderers((count) => count + 1);
+		return () => setVirtualRenderers((count) => Math.max(0, count - 1));
+	}, []);
+	const hasVirtualRenderer = virtualRenderers > 0;
+	const wantsVirtual = virtualize ?? renderedItems.length >= virtualizeThreshold;
+	const [virtualLatch, setVirtualLatch] = React$1.useState({
+		key: levelKey,
+		on: false
+	});
+	const virtualized = hasVirtualRenderer && (virtualLatch.key === levelKey ? virtualLatch.on || wantsVirtual : wantsVirtual);
+	if (!hasVirtualRenderer) {
+		if (virtualLatch.on || virtualLatch.key !== levelKey) setVirtualLatch({
+			key: levelKey,
+			on: false
+		});
+	} else if (virtualLatch.key !== levelKey) setVirtualLatch({
+		key: levelKey,
+		on: virtualized
+	});
+	else if (virtualized && !virtualLatch.on) setVirtualLatch({
+		key: levelKey,
+		on: true
+	});
+	/**
+	* One forced re-render, one commit AFTER windowing turns on. Base UI sizes
+	* `listRef` from `filteredItems` in a layout effect keyed on that array's
+	* identity, but `virtualized` reaches the list a commit later and the
+	* `CompositeList` teardown REPLACES `listRef` with an empty array nothing
+	* re-sizes, so ArrowDown stops at the last WINDOWED row. A passive effect is
+	* late enough: the teardown is scheduled from a layout effect.
+	*/
+	const [virtualSyncs, setVirtualSyncs] = React$1.useState(0);
+	React$1.useEffect(() => {
+		if (!virtualized) return;
+		setVirtualSyncs((count) => count + 1);
+	}, [virtualized]);
+	React$1.useEffect(() => {
+		if (process.env.NODE_ENV === "production") return void 0;
+		if (virtualize !== true || hasVirtualRenderer) return void 0;
+		const timeout = setTimeout(() => {
+			console.error("[Cascader] `virtualize` is true but no windowing renderer is mounted. Render <CascaderVirtualItems /> inside <CascaderList>, or <CascaderVirtualColumn /> through the <CascaderColumns> slot.");
+		}, 0);
+		return () => clearTimeout(timeout);
+	}, [virtualize, hasVirtualRenderer]);
+	/** One signal per navigation, feeding the live region, bumped EXACTLY once
+	* per action. `seq` alternates the invisible marker so two identical
+	* announcements are still two mutations; `toggled` names the tree branch. */
+	const [announceSignal, setAnnounceSignal] = React$1.useState({
+		seq: 0,
+		toggled: null,
+		notice: null
+	});
+	const bumpAnnouncement = React$1.useCallback((toggled) => {
+		setAnnounceSignal((prev) => ({
+			seq: prev.seq + 1,
+			toggled,
+			notice: null
+		}));
+	}, []);
+	/** Speaks for interactions that change nothing on screen: a refusal returns
+	* before any state moves, a cascade sweep is invisible from the row pressed.
+	* The seq bump keeps two identical refusals two mutations. */
+	const announceNotice = React$1.useCallback((notice) => {
+		setAnnounceSignal((prev) => ({
+			seq: prev.seq + 1,
+			toggled: null,
+			notice
+		}));
+	}, []);
+	/**
+	* The navigation a press asked for and a fetch has not answered yet. Load
+	* BEFORE you move: drilling in first threw away the list the user was
+	* reading and, on failure, stranded them on an error screen for a level they
+	* had never seen. Holding here keeps the old rows and puts the progress on
+	* the pressed row, whose chevron `CascaderItem` swaps for a spinner.
+	*/
+	const [pendingNavigation, setPendingNavigation] = React$1.useState(null);
+	/** Asks for a branch's children and parks the navigation until they land.
+	* BOTH entry points are called unconditionally: `retryLevel` no-ops unless
+	* the level errored, `ensureLevel` no-ops if it has state, so a repeat press
+	* is free and the readiness decision stays inside the loader. */
+	const requestChildren = React$1.useCallback((node, pending) => {
+		setPendingNavigation(pending);
+		retryLoaderLevel(node.value);
+		ensureLevel(node.value, "level");
+		bumpAnnouncement(null);
+	}, [
+		retryLoaderLevel,
+		ensureLevel,
+		bumpAnnouncement
+	]);
+	const pushLevel = React$1.useCallback((nodeValue) => {
+		setPathWithReason((prev) => [...prev, nodeValue], "drill");
+		setQuery("");
+		bumpAnnouncement(null);
+	}, [
+		setPathWithReason,
+		setQuery,
+		bumpAnnouncement
+	]);
+	const popLevel = React$1.useCallback(() => {
+		setPathWithReason((prev) => prev.length ? prev.slice(0, -1) : prev, "back");
+		setQuery("");
+		setPendingNavigation(null);
+		bumpAnnouncement(null);
+	}, [
+		setPathWithReason,
+		setQuery,
+		bumpAnnouncement
+	]);
+	const goToDepth = React$1.useCallback((depth) => {
+		setPathWithReason((prev) => prev.slice(0, Math.max(0, depth)), "breadcrumb");
+		setQuery("");
+		setPendingNavigation(null);
+		bumpAnnouncement(null);
+	}, [
+		setPathWithReason,
+		setQuery,
+		bumpAnnouncement
+	]);
+	const toggleExpanded = React$1.useCallback((nodeValue) => {
+		setExpandedList((prev) => prev.includes(nodeValue) ? prev.filter((v) => v !== nodeValue) : [...prev, nodeValue]);
+		bumpAnnouncement(nodeValue);
+	}, [setExpandedList, bumpAnnouncement]);
+	const isBranch = React$1.useCallback((node) => isCascaderBranch(index, node), [index]);
+	const isSelectable = React$1.useCallback((node) => isCascaderSelectable(index, node, selectable), [index, selectable]);
+	const isDisabled = React$1.useCallback((node) => isCascaderDisabled(index, node), [index]);
+	const branchesSelectable = selectable !== "leaf";
+	const openFlyoutsRef = React$1.useRef(/* @__PURE__ */ new Set());
+	const setFlyoutOpen = React$1.useCallback((key, open) => {
+		if (open) openFlyoutsRef.current.add(key);
+		else openFlyoutsRef.current.delete(key);
+	}, []);
+	const hasOpenFlyout = React$1.useCallback(() => openFlyoutsRef.current.size > 0, []);
+	const stableActions = useShallowStable(actions, shallowEqualItemLists);
+	const resolvedActions = React$1.useMemo(() => stableActions ?? EMPTY_ACTIONS, [stableActions]);
+	const selectedSet = React$1.useMemo(() => new Set(selectedValues), [selectedValues]);
+	const isSelected = React$1.useCallback((node) => selectedSet.has(node.value), [selectedSet]);
+	/** Selected-descendant counts, walked ONCE per selection change and never
+	* stored, so the flat value array stays the only source of truth. The walk
+	* is `selections x depth`, up from each selection rather than down from each
+	* row, which keeps the count and `isIndeterminate` O(1). */
+	const selectedDescendants = React$1.useMemo(() => getCascaderSelectedDescendants(index, selectedValues), [index, selectedValues]);
+	const selectedDescendantCount = React$1.useCallback((node) => selectedDescendants.get(node.value) ?? 0, [selectedDescendants]);
+	const indeterminateSet = React$1.useMemo(() => {
+		if (!cascade || !multiple) return null;
+		return getCascaderIndeterminateFrom(selectedDescendants, selectedValues);
+	}, [
+		cascade,
+		multiple,
+		selectedDescendants,
+		selectedValues
+	]);
+	const isIndeterminate = React$1.useCallback((node) => indeterminateSet?.has(node.value) ?? false, [indeterminateSet]);
+	const highlightedRef = React$1.useRef(null);
+	const getHighlighted = React$1.useCallback(() => highlightedRef.current, []);
+	const [highlightStore] = React$1.useState(createCascaderHighlightStore);
+	const currentLoadState = React$1.useMemo(() => loadStates.get(currentLevelKey) ?? null, [loadStates, currentLevelKey]);
+	const searchLoadState = loader.searchState;
+	/** What the query announcement COUNTS: matches, not rows, since the list
+	* also carries a tree query's ancestor context and the Load-more row. Server
+	* hits count as-is; re-judging them locally would drop what it matched on
+	* data the client cannot see. */
+	const announcedMatches = React$1.useMemo(() => {
+		if (deepResults) return deepResults.length;
+		const normalized = normalizeCascaderQuery(query);
+		if (!normalized) return 0;
+		const matches = filter ?? matchesCascaderQuery;
+		return renderedItems.filter((node) => !isCascaderMoreNode(node) && matches(node, normalized)).length;
+	}, [
+		deepResults,
+		renderedItems,
+		query,
+		filter
+	]);
+	const hasRows = renderedItems.some((node) => !isCascaderMoreNode(node));
+	const announcementTarget = React$1.useMemo(() => {
+		if (!open && !inline) return {
+			text: "",
+			defer: false
+		};
+		const total = renderedItems.length;
+		const marker = ANNOUNCE_MARKER.repeat(announceSignal.seq % 2);
+		if (announceSignal.notice) return {
+			text: `${announceSignal.notice}${marker}`,
+			defer: false
+		};
+		const toggled = mode === "tree" && announceSignal.toggled ? index.byValue.get(announceSignal.toggled) ?? null : null;
+		const pendingState = pendingNavigation ? loadStates.get(pendingNavigation.value) ?? null : null;
+		const levelState = query.trim() ? searchLoadState : currentLoadState;
+		let text;
+		let defer = false;
+		if (pendingState?.error) text = labels.error;
+		else if (pendingNavigation) text = labels.loading;
+		else if (levelState?.error) text = labels.error;
+		else if (levelState?.loading) text = query.trim() ? labels.searchingAnnouncement : hasRows ? labels.loadingMore : labels.loading;
+		else if (query.trim()) {
+			text = announcedMatches === 0 ? labels.empty : labels.resultsAnnouncement(announcedMatches);
+			defer = true;
+		} else if (toggled) text = expanded.has(toggled.value) ? labels.expandedAnnouncement(toggled.label, getCascaderCount(index, toggled)) : labels.collapsedAnnouncement(toggled.label);
+		else if (currentParent) text = labels.levelAnnouncement(currentParent.label, path.length + 1, total);
+		else text = labels.rootAnnouncement(total);
+		return {
+			text: `${text}${marker}`,
+			defer
+		};
+	}, [
+		open,
+		inline,
+		mode,
+		index,
+		expanded,
+		announceSignal,
+		query,
+		labels,
+		renderedItems.length,
+		hasRows,
+		announcedMatches,
+		currentParent,
+		path.length,
+		currentLoadState,
+		searchLoadState,
+		pendingNavigation,
+		loadStates
+	]);
+	/** The COMMITTED announcement. Immediate texts commit during render (the
+	* pattern `swap` uses), so an async settle announces in the very commit that
+	* shows the rows. Only the deferred query count uses the timer below. */
+	const [announced, setAnnounced] = React$1.useState(announcementTarget);
+	if (!announcementTarget.defer && announced.text !== announcementTarget.text) setAnnounced(announcementTarget);
+	React$1.useEffect(() => {
+		if (!announcementTarget.defer) return void 0;
+		const timer = setTimeout(() => setAnnounced(announcementTarget), ANNOUNCE_DEBOUNCE);
+		return () => clearTimeout(timer);
+	}, [announcementTarget]);
+	const announcement = announced.text;
+	const stateValue = React$1.useMemo(() => ({
+		index,
+		path,
+		expanded,
+		query,
+		currentParent,
+		levelItems,
+		deepResults,
+		renderedItems,
+		columns,
+		treeRows,
+		selectedValues,
+		selectedDescendants,
+		loadStates,
+		searchState: searchLoadState,
+		announcement
+	}), [
+		index,
+		path,
+		expanded,
+		query,
+		currentParent,
+		levelItems,
+		deepResults,
+		renderedItems,
+		columns,
+		treeRows,
+		selectedValues,
+		selectedDescendants,
+		loadStates,
+		searchLoadState,
+		announcement
+	]);
+	/**
+	* Latest committed props and derived state, WRITTEN IN AN EFFECT. That is
+	* what keeps the callbacks below `[]`-dep and stable for the life of the
+	* cascader; writing during render is unsafe under concurrent rendering. The
+	* cost: a read sees the PREVIOUS commit until the effect runs, so ONLY event
+	* handlers may read it. Anything used during render is memoised instead.
+	*/
+	const latest = React$1.useRef({
+		index,
+		state: stateValue,
+		mode,
+		multiple,
+		cascade,
+		max,
+		labels,
+		closeOnSelect,
+		selectedValues,
+		deepResults,
+		onValueChange,
+		resolveNode,
+		isSelectable,
+		needsChildren,
+		expanded
+	});
+	React$1.useEffect(() => {
+		latest.current = {
+			index,
+			state: stateValue,
+			mode,
+			multiple,
+			cascade,
+			max,
+			labels,
+			closeOnSelect,
+			selectedValues,
+			deepResults,
+			onValueChange,
+			resolveNode,
+			isSelectable,
+			needsChildren,
+			expanded
+		};
+	});
+	const getIndex = React$1.useCallback(() => latest.current.index, []);
+	const getState = React$1.useCallback(() => latest.current.state, []);
+	const goToLevelAt = React$1.useCallback((nodeValue, depth) => {
+		setPathWithReason((prev) => [...prev.slice(0, Math.max(0, depth)), nodeValue], "drill");
+		setQuery("");
+		bumpAnnouncement(null);
+	}, [
+		setPathWithReason,
+		setQuery,
+		bumpAnnouncement
+	]);
+	const goToTrail = React$1.useCallback((trail) => {
+		const { path: current } = latest.current.state;
+		if (trail.length === current.length && trail.every((entry, i) => entry === current[i])) resetHighlight();
+		else setPathWithReason(trail, "drill");
+		setQuery("");
+		bumpAnnouncement(null);
+	}, [
+		setPathWithReason,
+		resetHighlight,
+		setQuery,
+		bumpAnnouncement
+	]);
+	const navigateAt = React$1.useCallback((node, depth) => {
+		if (isCascaderDisabled(latest.current.index, node)) return;
+		if (latest.current.mode === "tree") {
+			toggleExpanded(node.value);
+			return;
+		}
+		if (latest.current.needsChildren(node)) {
+			requestChildren(node, {
+				value: node.value,
+				kind: "at",
+				depth
+			});
+			return;
+		}
+		goToLevelAt(node.value, depth);
+	}, [
+		toggleExpanded,
+		goToLevelAt,
+		requestChildren
+	]);
+	const navigate = React$1.useCallback((node) => {
+		const { mode: currentMode, deepResults: currentDeepResults, index: currentIndex, expanded: currentExpanded, needsChildren: pending } = latest.current;
+		if (isCascaderDisabled(currentIndex, node)) return;
+		if (currentMode === "tree") {
+			if (!currentExpanded.has(node.value) && pending(node)) {
+				requestChildren(node, {
+					value: node.value,
+					kind: "expand",
+					depth: 0
+				});
+				return;
+			}
+			toggleExpanded(node.value);
+			return;
+		}
+		if (currentDeepResults) {
+			const trail = getCascaderPath(currentIndex, node.value).map((entry) => entry.value);
+			if (pending(node)) {
+				requestChildren(node, {
+					value: node.value,
+					kind: "trail",
+					trail
+				});
+				return;
+			}
+			goToTrail(trail);
+			return;
+		}
+		if (pending(node)) {
+			requestChildren(node, {
+				value: node.value,
+				kind: "push",
+				depth: 0
+			});
+			return;
+		}
+		pushLevel(node.value);
+	}, [
+		toggleExpanded,
+		goToTrail,
+		pushLevel,
+		requestChildren
+	]);
+	/**
+	* The other half of `requestChildren`: the fetch settled, so the held
+	* navigation happens or is dropped. Reads the load STATE, not a promise:
+	* only the loader knows a request was superseded, aborted or retried, and no
+	* entry at all means it has not reached the store yet. On failure nothing
+	* moves and the intent is KEPT, which is what makes the row's retry
+	* affordance mean something; only `popLevel`, `goToDepth` and a close drop it.
+	*/
+	React$1.useEffect(() => {
+		if (!pendingNavigation) return;
+		const state = loadStates.get(pendingNavigation.value);
+		if (!state || state.loading || state.error) return;
+		setPendingNavigation(null);
+		const target = index.byValue.get(pendingNavigation.value);
+		if (target && isDisabled(target)) return;
+		if (pendingNavigation.kind === "expand") {
+			toggleExpanded(pendingNavigation.value);
+			return;
+		}
+		if (pendingNavigation.kind === "trail") {
+			goToTrail(pendingNavigation.trail);
+			return;
+		}
+		if (pendingNavigation.kind === "at") {
+			goToLevelAt(pendingNavigation.value, pendingNavigation.depth);
+			return;
+		}
+		pushLevel(pendingNavigation.value);
+	}, [
+		pendingNavigation,
+		loadStates,
+		index,
+		isDisabled,
+		toggleExpanded,
+		goToTrail,
+		goToLevelAt,
+		pushLevel
+	]);
+	React$1.useEffect(() => {
+		if (!open && !inline) setPendingNavigation(null);
+	}, [open, inline]);
+	const emitSelection = React$1.useCallback((nextValues, node, reason) => {
+		const { selectedValues: current, multiple: currentMultiple, onValueChange: emit, index: currentIndex, resolveNode: resolve } = latest.current;
+		if (nextValues.length === current.length && nextValues.every((entry, i) => entry === current[i])) return;
+		const next = currentMultiple ? nextValues : nextValues[0] ?? "";
+		setValue(next);
+		if (!emit) return;
+		const chain = node ? getCascaderPath(currentIndex, node.value) : [];
+		emit(next, {
+			node,
+			path: node ? chain.length ? chain : [node] : [],
+			nodes: nextValues.map(resolve),
+			reason
+		});
+	}, [setValue]);
+	const setSelection = React$1.useCallback((values, reason) => {
+		const { selectedValues: current, resolveNode: resolve } = latest.current;
+		const before = new Set(current);
+		const after = new Set(values);
+		const added = values.find((entry) => !before.has(entry));
+		const removed = current.find((entry) => !after.has(entry));
+		if (reason === "clear") {
+			emitSelection(values, null, "clear");
+			return;
+		}
+		if (added) {
+			emitSelection(values, resolve(added), reason ?? "select");
+			return;
+		}
+		if (removed) {
+			emitSelection(values, resolve(removed), reason ?? "deselect");
+			return;
+		}
+		emitSelection(values, null, reason ?? "select");
+	}, [emitSelection]);
+	const commit = React$1.useCallback((node) => {
+		const { multiple: currentMultiple, cascade: currentCascade, selectedValues: current, max: currentMax, index: currentIndex, isSelectable: currentIsSelectable, labels: currentLabels, closeOnSelect: currentCloseOnSelect } = latest.current;
+		const selecting = !currentMultiple || !current.includes(node.value);
+		if (selecting && isCascaderDisabled(currentIndex, node)) return;
+		if (!currentMultiple) {
+			emitSelection([node.value], node, "select");
+			if (currentCloseOnSelect) {
+				openReasonRef.current = "item-press";
+				setOpen(false);
+			} else setQuery("");
+			return;
+		}
+		if (currentCascade) {
+			const next = applyCascadeSelection(currentIndex, current, node.value, selecting, currentIsSelectable);
+			if (selecting && currentMax != null && next.length > currentMax && next.length > current.length) {
+				announceNotice(currentLabels.maxReachedAnnouncement(currentMax));
+				return;
+			}
+			emitSelection(next, node, selecting ? "select" : "deselect");
+			const before = new Set(current);
+			const after = new Set(next);
+			let swept = 0;
+			for (const entry of selecting ? next : current) {
+				if (entry === node.value) continue;
+				if (selecting ? !before.has(entry) : !after.has(entry)) swept += 1;
+			}
+			if (swept > 0) announceNotice(currentLabels.cascadeAnnouncement(node.label ?? node.value, swept, selecting));
+			setQuery("");
+			return;
+		}
+		if (current.includes(node.value)) emitSelection(current.filter((v) => v !== node.value), node, "deselect");
+		else if (currentMax == null || current.length < currentMax) emitSelection([...current, node.value], node, "select");
+		else announceNotice(currentLabels.maxReachedAnnouncement(currentMax));
+		setQuery("");
+	}, [
+		emitSelection,
+		setOpen,
+		setQuery,
+		announceNotice
+	]);
+	/** Safety net for paths that bypass the row-level veto (the drag-select
+	* mouseup). `details.cancel()` suppresses the commit and the close together:
+	* Base UI shares one event-details object between them. */
+	const handleComboboxValueChange = React$1.useCallback((next, details) => {
+		if (!multiple) {
+			const node = Array.isArray(next) ? next[0] ?? null : next;
+			if (node && isCascaderMoreNode(node)) {
+				details.cancel();
+				return;
+			}
+			if (node && isDisabled(node)) {
+				details.cancel();
+				return;
+			}
+			if (node && !isSelectable(node) && isBranch(node)) {
+				details.cancel();
+				navigate(node);
+				return;
+			}
+			if (node) {
+				if (!closeOnSelect) details.cancel();
+				commit(node);
+			}
+			return;
+		}
+		const nextNodes = Array.isArray(next) ? next : [];
+		const before = new Set(selectedValues);
+		const added = nextNodes.find((node) => !before.has(node.value));
+		if (added && (isCascaderMoreNode(added) || isDisabled(added))) {
+			details.cancel();
+			return;
+		}
+		if (added && !isSelectable(added) && isBranch(added)) {
+			details.cancel();
+			navigate(added);
+			return;
+		}
+		if (cascade) {
+			const nextValues = new Set(nextNodes.map((node) => node.value));
+			const removed = selectedValues.find((entry) => !nextValues.has(entry));
+			const toggled = added ?? (removed != null ? resolveNode(removed) : null);
+			if (toggled) commit(toggled);
+			return;
+		}
+		if (max != null && nextNodes.length > selectedValues.length && nextNodes.length > max) {
+			details.cancel();
+			announceNotice(labels.maxReachedAnnouncement(max));
+			return;
+		}
+		setSelection(nextNodes.map((node) => node.value));
+		setQuery("");
+	}, [
+		multiple,
+		selectedValues,
+		max,
+		cascade,
+		closeOnSelect,
+		labels,
+		announceNotice,
+		isSelectable,
+		isDisabled,
+		isBranch,
+		navigate,
+		commit,
+		resolveNode,
+		setSelection,
+		setQuery
+	]);
+	const handleOpenChange = React$1.useCallback((nextOpen, details) => {
+		if (details.isCanceled) return;
+		if (!nextOpen && details.reason === "escape-key" && hasOpenFlyout()) {
+			details.cancel();
+			return;
+		}
+		openReasonRef.current = details.reason ?? "none";
+		setOpen(nextOpen);
+		if (!nextOpen) {
+			setQuery("");
+			return;
+		}
+		if (revealSelected) {
+			setQuery("");
+			const first = toArray(value)[0];
+			if (mode !== "tree") setPathWithReason(first ? getCascaderPath(index, first).slice(0, -1).map((node) => node.value) : [], "reveal");
+		}
+	}, [
+		setOpen,
+		setQuery,
+		revealSelected,
+		value,
+		index,
+		mode,
+		setPathWithReason,
+		hasOpenFlyout
+	]);
+	const renderContext = React$1.useMemo(() => ({
+		renderItem,
+		renderLabel
+	}), [renderItem, renderLabel]);
+	/** The stable half: nothing in these deps moves on a keystroke, a level
+	* change or a highlight, which is what makes `React.memo` on `CascaderItem`
+	* hold while the user types. Destructured off `loader` so the memo depends
+	* on its `[]`-dep callbacks, not the object it republishes per load. */
+	const { active: hasLoader, loadMore, retryLevel, retrySearch, prefetchNode } = loader;
+	const actionsValue = React$1.useMemo(() => ({
+		index,
+		mode,
+		multiple,
+		cascade,
+		branchesSelectable,
+		indicator,
+		expandTrigger,
+		actions: resolvedActions,
+		searchScope,
+		maxHeight,
+		inline: !!inline,
+		invalid: !!invalid,
+		baseId,
+		labels,
+		virtualized,
+		registerVirtualRenderer,
+		virtualize,
+		virtualizeThreshold,
+		estimateRowSize,
+		overscan,
+		hasLoader,
+		loadMore,
+		retryLevel,
+		retrySearch,
+		invalidateLevel,
+		getIndex,
+		getState,
+		getHighlighted,
+		setPath,
+		pushLevel,
+		popLevel,
+		goToDepth,
+		toggleExpanded,
+		setFlyoutOpen,
+		hasOpenFlyout,
+		setQuery,
+		setSelection,
+		commit,
+		navigate,
+		navigateAt,
+		resolveNode,
+		isBranch,
+		isSelectable,
+		isDisabled,
+		isSelected,
+		isIndeterminate,
+		selectedDescendantCount
+	}), [
+		index,
+		mode,
+		multiple,
+		cascade,
+		branchesSelectable,
+		indicator,
+		expandTrigger,
+		resolvedActions,
+		searchScope,
+		maxHeight,
+		inline,
+		invalid,
+		baseId,
+		labels,
+		virtualized,
+		registerVirtualRenderer,
+		virtualize,
+		virtualizeThreshold,
+		estimateRowSize,
+		overscan,
+		hasLoader,
+		loadMore,
+		retryLevel,
+		retrySearch,
+		invalidateLevel,
+		getIndex,
+		getState,
+		getHighlighted,
+		setPath,
+		pushLevel,
+		popLevel,
+		goToDepth,
+		toggleExpanded,
+		setFlyoutOpen,
+		hasOpenFlyout,
+		setQuery,
+		setSelection,
+		commit,
+		navigate,
+		navigateAt,
+		resolveNode,
+		isBranch,
+		isSelectable,
+		isDisabled,
+		isSelected,
+		isIndeterminate,
+		selectedDescendantCount
+	]);
+	const comboboxItems = React$1.useMemo(() => virtualized ? renderedItems.slice() : renderedItems, [
+		renderedItems,
+		virtualized,
+		virtualSyncs
+	]);
+	const comboboxValue = React$1.useMemo(() => {
+		if (multiple) return selectedValues.map(resolveNode);
+		return selectedValues.length ? resolveNode(selectedValues[0]) : null;
+	}, [
+		multiple,
+		selectedValues,
+		resolveNode
+	]);
+	return /* @__PURE__ */ jsx(CascaderActionsContext.Provider, {
+		value: actionsValue,
+		children: /* @__PURE__ */ jsx(CascaderStateContext.Provider, {
+			value: stateValue,
+			children: /* @__PURE__ */ jsx(CascaderHighlightContext.Provider, {
+				value: highlightStore,
+				children: /* @__PURE__ */ jsx(CascaderRenderContext.Provider, {
+					value: renderContext,
+					children: /* @__PURE__ */ jsx(Combobox.Root, {
+						items: renderedItems,
+						filteredItems: swapping ? EMPTY : comboboxItems,
+						filter: null,
+						value: comboboxValue,
+						onValueChange: handleComboboxValueChange,
+						open,
+						onOpenChange: handleOpenChange,
+						inputValue: query,
+						onInputValueChange: (next) => setQuery(next),
+						multiple,
+						disabled,
+						name,
+						...form != null ? { form } : null,
+						...id != null ? { id } : null,
+						...required != null ? { required } : null,
+						...readOnly != null ? { readOnly } : null,
+						...inputRef ? { inputRef } : null,
+						inline,
+						virtualized,
+						itemToStringValue: (item) => item?.value ?? "",
+						itemToStringLabel: (item) => item?.label ?? "",
+						isItemEqualToValue: (a, b) => a?.value === b?.value,
+						onItemHighlighted: (item, details) => {
+							highlightedRef.current = item ?? null;
+							highlightStore.set({
+								index: details.index,
+								value: item?.value ?? null
+							});
+							prefetchNode(item);
+						},
+						children
+					})
+				})
+			})
+		})
+	});
+}
+function CascaderTrigger({ className, children, showIcon = true, ref, ...props }) {
+	const { invalid } = useCascaderActions();
+	const triggerRef = React$1.useRef(null);
+	const setTrigger = React$1.useCallback((node) => {
+		triggerRef.current = node;
+		if (typeof ref === "function") ref(node);
+		else if (ref) ref.current = node;
+	}, [ref]);
+	/** 18 of 19 audited examples shipped an unnamed combobox: the trigger's
+	* contents are the field's VALUE, so a screen reader never hears its NAME.
+	* Checked in the DOM, since the name may arrive as a `<label for>`. */
+	React$1.useEffect(() => {
+		if (process.env.NODE_ENV === "production") return;
+		const element = triggerRef.current;
+		if (!element) return;
+		if (element.hasAttribute("aria-label") || element.hasAttribute("aria-labelledby") || element.closest("label") !== null || element.id !== "" && element.ownerDocument.querySelector(`label[for="${CSS.escape(element.id)}"]`) !== null) return;
+		warnCascaderOnce("trigger-unnamed", "`CascaderTrigger` has no accessible name. Its contents are the field's VALUE - they change with the selection - so a screen reader hears what is picked but never what the field is for. Pass `aria-label` or `aria-labelledby`, or reference the trigger's `id` from a `<label>`.");
+	});
+	return /* @__PURE__ */ jsxs(Combobox.Trigger, {
+		ref: setTrigger,
+		"data-slot": "cascader-trigger",
+		...invalid ? {
+			"aria-invalid": true,
+			"data-invalid": ""
+		} : null,
+		className: cn(TRIGGER_ICON_FALLBACK_CLASS, className),
+		...props,
+		children: [children, showIcon ? /* @__PURE__ */ jsx(ChevronDownIcon, { className: `${TRIGGER_ICON_CLASS} pointer-events-none shrink-0` }) : null]
+	});
+}
+/** Icon size for a combobox surface: 14px in mira and sera, 16px elsewhere. */
+const TRIGGER_ICON_CLASS = "text-muted-foreground size-4";
+/** The same ladder, applied only to trigger children that carry no size. */
+const TRIGGER_ICON_FALLBACK_CLASS = "[&_svg:not([class*='size-'])]:size-4";
+/** The chips field: a form-control surface, so it carries the invalid states. */
+const CHIPS_CLASS = "flex flex-wrap items-center border bg-clip-padding dark:bg-input/30 border-input focus-within:border-ring focus-within:ring-ring/50 has-aria-invalid:ring-destructive/20 dark:has-aria-invalid:ring-destructive/40 has-aria-invalid:border-destructive dark:has-aria-invalid:border-destructive/50 min-h-9 gap-1.5 rounded-md bg-transparent px-2.5 py-1.5 text-sm shadow-xs transition-[color,box-shadow] focus-within:ring-3 has-aria-invalid:ring-3 has-data-[slot=combobox-chip]:px-1.5";
+const CHIP_CLASS = "text-foreground flex w-fit items-center justify-center gap-1 font-medium whitespace-nowrap bg-muted h-[calc(--spacing(5.5))] rounded-sm px-1.5 text-xs has-data-[slot=combobox-chip-remove]:pr-0";
+const CHIP_REMOVE_CLASS = "opacity-50 hover:opacity-100 -ml-1";
+/** The floating panel's surface. The shared popup's `InputGroup` sizing is
+* left out (mirrored in `cascader-nav.tsx`), as are its `max-h-72` and
+* `min-w-*`: `CascaderContent` sets both from the positioner's variables. */
+const CONTENT_SURFACE_CLASS = "bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 overflow-hidden ring-1 duration-100 ring-foreground/10 rounded-md shadow-md data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2";
+const EMPTY_CLASS = "text-muted-foreground hidden w-full justify-center py-2 text-center group-data-empty/combobox-content:flex text-sm";
+/**
+* The multi-select trigger surface: one removable chip per selection, where
+* `CascaderValue` would collapse to "3 selected". A component rather than a
+* recipe because of three easy misses: the popup anchored to the chips, an
+* accessible name on every remove button, and labels that disambiguate when
+* two branches use the same one.
+*
+* ```tsx
+* const anchor = useCascaderAnchor()
+* <Cascader multiple items={items}>
+*   <CascaderChips ref={anchor} placeholder="Select attributes" />
+*   <CascaderContent anchor={anchor}>...</CascaderContent>
+* </Cascader>
+* ```
+*/
+function CascaderChips({ className, children, placeholder, strategy = "all", ...props }) {
+	const { labels, multiple, invalid, resolveNode, index, isSelectable, setSelection } = useCascaderActions();
+	const { selectedValues } = useCascaderState();
+	React$1.useEffect(() => {
+		if (process.env.NODE_ENV === "production") return;
+		if (multiple) return;
+		warnCascaderOnce("chips-without-multiple", "`CascaderChips` renders one chip per selection and there is only ever one without `multiple`. Use `CascaderValue` for a single-select trigger.");
+	}, [multiple]);
+	const nodes = (strategy === "all" ? selectedValues : getCascaderCheckedValues(index, selectedValues, strategy)).map(resolveNode);
+	const ambiguous = findAmbiguousCascaderLabels(nodes);
+	const removeClosure = (node) => {
+		setSelection(applyCascadeSelection(index, selectedValues, node.value, false, isSelectable), "deselect");
+	};
+	const content = typeof children === "function" ? children(nodes) : children;
+	return /* @__PURE__ */ jsx(Combobox.Chips, {
+		"data-slot": "cascader-chips",
+		"aria-label": labels.chipsLabel,
+		...invalid ? {
+			"aria-invalid": true,
+			"data-invalid": ""
+		} : null,
+		className: cn(CHIPS_CLASS, className),
+		...props,
+		children: content ?? (nodes.length === 0 ? /* @__PURE__ */ jsx("span", {
+			"data-slot": "cascader-chips-placeholder",
+			className: "text-muted-foreground truncate",
+			children: placeholder
+		}) : nodes.map((node) => /* @__PURE__ */ jsx(CascaderChip, {
+			node,
+			showPath: ambiguous.has(node.value),
+			...strategy !== "all" ? { onRemove: () => removeClosure(node) } : null
+		}, node.value)))
+	});
+}
+/** One chip. Removal goes through Base UI's `ChipRemove`, which reports the
+* shortened selection to the root, so it lands in the same `setSelection` as
+* every other deselection and `cascade` applies to it. */
+function CascaderChip({ className, node, showPath = false, maxSegments = 2, showRemove = true, onRemove, children, ...props }) {
+	const { labels, index } = useCascaderActions();
+	const chain = showPath ? getCascaderPath(index, node.value) : [];
+	const segments = collapseCascaderPath(chain, {
+		maxSegments,
+		collapse: "start"
+	});
+	const label = segments.length ? segments.map((segment) => segment.type === "node" ? segment.node.label : "…").join(` ${labels.pathSeparator} `) : node.label;
+	return /* @__PURE__ */ jsxs(Combobox.Chip, {
+		"data-slot": "cascader-chip",
+		...onRemove ? { onKeyDown: (event) => {
+			if (event.key !== "Backspace" && event.key !== "Delete") return;
+			event.preventBaseUIHandler();
+			onRemove();
+		} } : null,
+		className: cn(CHIP_CLASS, "has-disabled:pointer-events-none has-disabled:cursor-not-allowed has-disabled:opacity-50", className),
+		...props,
+		children: [children ?? /* @__PURE__ */ jsx("span", {
+			className: "truncate",
+			children: label
+		}), showRemove ? /* @__PURE__ */ jsx(Combobox.ChipRemove, {
+			"data-slot": "cascader-chip-remove",
+			"aria-label": labels.removeChip(label),
+			...onRemove ? { onClick: (event) => {
+				event.preventBaseUIHandler();
+				onRemove();
+			} } : null,
+			className: CHIP_REMOVE_CLASS,
+			children: /* @__PURE__ */ jsx(XIcon, { className: "pointer-events-none" })
+		}) : null]
+	});
+}
+/** Portal + Positioner + floating panel. Unlike shadcn's `ComboboxContent` it
+* does NOT clamp the popup to the anchor width (a cascader panel is routinely
+* wider), but it keeps `group/combobox-content`, which `CascaderEmpty` needs. */
+function CascaderContent({ className, side = "bottom", sideOffset = 6, align = "start", alignOffset = 0, anchor, collisionBoundary, collisionPadding, sticky, positionMethod, container, ref, ...props }) {
+	const { labels } = useCascaderActions();
+	const popupRef = React$1.useRef(null);
+	const setPopup = React$1.useCallback((node) => {
+		popupRef.current = node;
+		if (typeof ref === "function") ref(node);
+		else if (ref) ref.current = node;
+	}, [ref]);
+	/**
+	* Focus goes to the search field, where the level keys and
+	* `aria-activedescendant` live. Base UI's own default agrees but is COMPUTED
+	* FROM THE FIRST RENDER, when the field has not mounted, and collapses to
+	* "do not move focus": measured, a KEYBOARD open left focus on the trigger
+	* and cost two Tabs to reach the footer where a pointer open cost one.
+	*
+	* `initialFocus` rather than an effect, because anything scheduled alongside
+	* Base UI's focus manager is a race; the field is resolved INSIDE the
+	* callback, which runs after the layout effects. Touch is handed back to
+	* Base UI on purpose - focusing the popup keeps the Android keyboard shut.
+	*/
+	const initialFocus = React$1.useCallback((openType) => {
+		const popup = popupRef.current;
+		if (!popup) return true;
+		if (openType === "touch") return popup;
+		return popup.querySelector("[data-slot=\"cascader-input\"]") ?? true;
+	}, []);
+	return /* @__PURE__ */ jsx(Combobox.Portal, {
+		...container !== void 0 ? { container } : null,
+		children: /* @__PURE__ */ jsx(Combobox.Positioner, {
+			side,
+			sideOffset,
+			align,
+			alignOffset,
+			anchor,
+			...collisionBoundary !== void 0 ? { collisionBoundary } : null,
+			...collisionPadding !== void 0 ? { collisionPadding } : null,
+			...sticky !== void 0 ? { sticky } : null,
+			...positionMethod !== void 0 ? { positionMethod } : null,
+			className: "isolate z-50",
+			children: /* @__PURE__ */ jsx(Combobox.Popup, {
+				ref: setPopup,
+				"data-slot": "cascader-content",
+				"data-menu-target": "",
+				"aria-label": labels.panelLabel,
+				initialFocus,
+				className: cn(CONTENT_SURFACE_CLASS, "group/combobox-content relative flex max-h-(--available-height) max-w-(--available-width) min-w-(--anchor-width) origin-(--transform-origin) flex-col", className),
+				...props
+			})
+		})
+	});
+}
+/**
+* The nav + list(s) + footer container, with no positioning of its own: inside
+* `CascaderContent` for the popup case, alone for the embedded one.
+*
+* `min-h-0` and `max-h-full` are load-bearing. A flex child without `min-h-0`
+* refuses to shrink below its content, which is the usual reason a scroll area
+* never scrolls - worst embedded, where no positioner publishes
+* `--available-height`. It also owns the panel's TAB ORDER: the scroll area
+* makes itself a tab stop whenever the level overflows, stranding the footer,
+* and the panel is the only ancestor of both ends of that move in BOTH shapes.
+*/
+function CascaderPanel({ className, ...props }) {
+	const { mode } = useCascaderActions();
+	const defaultProps = {
+		"data-slot": "cascader-panel",
+		"data-mode": mode,
+		onKeyDown: React$1.useCallback((event) => {
+			if (event.key !== "Tab" || event.defaultPrevented) return;
+			if (event.altKey || event.ctrlKey || event.metaKey) return;
+			const panel = event.currentTarget;
+			const target = event.target;
+			if (!target || !panel.contains(target)) return;
+			const next = getCascaderTabTarget(panel, target, event.shiftKey);
+			if (!next) return;
+			event.preventDefault();
+			next.focus();
+		}, []),
+		className: cn("flex max-h-full min-h-0 w-full flex-col", className)
+	};
+	return useRender({
+		defaultTagName: "div",
+		render: props.render,
+		props: mergeProps(defaultProps, props)
+	});
+}
+/**
+* Scroll container for one level: pattern 3 of the house scroll reference,
+* viewport-bounded popup scroll. The height is `min()` of `--available-height`
+* (the positioner's space between anchor and viewport edge) and `maxHeight`,
+* so neither can be ignored; a fixed pixel cap alone still reserved 288px for
+* a panel opened 200px above the fold and spilled off screen, and wasted room
+* in a tall window. The four classes are shared with `CascaderColumns` and
+* live in `cascader-lib.tsx`.
+*/
+function CascaderList({ className, style, maxHeight: maxHeightProp, ...props }) {
+	const { maxHeight, mode, labels, baseId, virtualized, searchScope } = useCascaderActions();
+	const { currentParent, deepResults } = useCascaderState();
+	const resolved = maxHeightProp ?? maxHeight;
+	const listName = searchScope === "global" && deepResults ? labels.rootLevel : currentParent?.label ?? labels.rootLevel;
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": "cascader-list-shell",
+		style: resolved != null ? {
+			...style,
+			"--cascader-max-height": typeof resolved === "number" ? `${resolved}px` : resolved
+		} : style,
+		className: cn("relative flex max-h-full min-h-0", CASCADER_LIST_PAD_CLASS),
+		children: /* @__PURE__ */ jsx("div", {
+			"data-slot": "cascader-list-bounds",
+			className: cn("flex w-full min-w-0 flex-col overscroll-contain", CASCADER_LIST_HEIGHT_CLASS),
+			children: /* @__PURE__ */ jsx(ScrollArea, {
+				className: CASCADER_SCROLL_CLASS,
+				children: /* @__PURE__ */ jsx(Combobox.List, {
+					"data-slot": "cascader-list",
+					"aria-label": listName,
+					id: `${baseId}-column-0`,
+					...mode === "tree" ? { role: "tree" } : null,
+					...virtualized ? { "data-virtualized": true } : null,
+					className: cn(CASCADER_ROWS_CLASS, virtualized && "relative", className),
+					...props
+				})
+			})
+		})
+	});
+}
+/** The empty, loading and error surface, in ONE element that never unmounts.
+* `Combobox.Empty` renders whenever `filteredItems.length === 0`, as true of a
+* fetching level as of an empty one, so swapping siblings would announce "No
+* results found." over every async level. Swap the CHILDREN. */
+function CascaderEmpty({ className, children, skeletonRows, ...props }) {
+	const { labels, retryLevel, retrySearch } = useCascaderActions();
+	const { query, path, searchState } = useCascaderState();
+	const levelKey = path.length ? path[path.length - 1] : CASCADER_ROOT_KEY;
+	const loadState = useCascaderLoadState(levelKey);
+	const state = query.trim() ? searchState ?? loadState : loadState;
+	let body = children ?? labels.empty;
+	if (state?.error) body = /* @__PURE__ */ jsxs("span", {
+		"data-slot": "cascader-error",
+		className: "flex flex-col items-center gap-1.5",
+		children: [/* @__PURE__ */ jsx("span", { children: labels.error }), /* @__PURE__ */ jsx("button", {
+			type: "button",
+			"data-slot": "cascader-retry",
+			onClick: (event) => {
+				focusCascaderHome(event.currentTarget);
+				if (query.trim() && searchState?.error) retrySearch();
+				else retryLevel(levelKey);
+			},
+			className: "text-foreground hover:bg-accent focus-visible:ring-ring/50 rounded-md px-2 py-0.5 font-medium outline-hidden transition-colors focus-visible:ring-2",
+			children: labels.retry
+		})]
+	});
+	else if (state?.loading) body = /* @__PURE__ */ jsx("span", {
+		"data-slot": "cascader-loading",
+		className: "flex w-full items-center justify-center",
+		children: labels.loading
+	});
+	return /* @__PURE__ */ jsx(Combobox.Empty, {
+		"data-slot": "cascader-empty",
+		"data-state": state?.error ? "error" : state?.loading ? "loading" : "empty",
+		className: cn(EMPTY_CLASS, className),
+		role: void 0,
+		"aria-live": void 0,
+		"aria-atomic": void 0,
+		...props,
+		children: body
+	});
+}
+/**
+* Polite live region for the current level and result count, which drill-down
+* otherwise hides in a visual breadcrumb. Built on `Combobox.Status` for its
+* initial-mutation marker: Safari and VoiceOver need a text change ~200ms
+* after mount before reading a polite region at all.
+*/
+function CascaderStatus({ className, children, ...props }) {
+	const { announcement } = useCascaderState();
+	return /* @__PURE__ */ jsx(Combobox.Status, {
+		"data-slot": "cascader-status",
+		className: cn("sr-only", className),
+		...props,
+		children: children ?? announcement
+	});
+}
+export { Cascader, CascaderChip, CascaderChips, CascaderContent, CascaderEmpty, CascaderList, CascaderPanel, CascaderStatus, CascaderTrigger, createCascaderHighlightStore, useCascaderActions, useCascaderState };