@deftui/react 0.2.5 → 0.3.1

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

@@ -0,0 +1,159 @@
+"use client";
+import { useCascaderActions, useCascaderHighlight, useCascaderState } from "./cascader-context.mjs";
+import { CascaderItem, CascaderItems, getCascaderMoreProps } from "./cascader-item.mjs";
+import * as React$1 from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { defaultRangeExtractor, useVirtualizer } from "@tanstack/react-virtual";
+// src/vendor/reui.io/cascader/cascader-virtual.tsx
+/**
+* The cascader's virtualizer: TanStack plus the highlight pinning and
+* scroll-into-view a combobox list needs. `activeIndex` is clamped here, not by
+* the caller: emitted from a layout effect, it can be one commit ahead of a
+* level that just shrank and would otherwise scroll to a row that is gone.
+*/
+function useCascaderVirtualizer({ count, getScrollElement, estimateSize = 32, overscan = 8, getItemKey, activeIndex = -1 }) {
+	const active = activeIndex >= 0 && activeIndex < count ? activeIndex : -1;
+	const rangeExtractor = React$1.useCallback((range) => {
+		const indices = new Set(defaultRangeExtractor(range));
+		if (active !== -1) indices.add(active);
+		return Array.from(indices).sort((a, b) => a - b);
+	}, [active]);
+	const measureEstimate = React$1.useCallback(() => estimateSize, [estimateSize]);
+	const virtualizer = useVirtualizer({
+		count,
+		getScrollElement,
+		estimateSize: measureEstimate,
+		overscan,
+		getItemKey,
+		rangeExtractor
+	});
+	React$1.useEffect(() => {
+		if (active === -1) return;
+		virtualizer.scrollToIndex(active, { align: "auto" });
+	}, [
+		active,
+		count,
+		virtualizer
+	]);
+	return virtualizer;
+}
+const NO_GUTTER = {
+	block: 0,
+	inline: 0
+};
+/**
+* The ROWS' BOX's own padding, never the scrollport's (separate element, reads
+* a flat zero). Measured because every style sets its own: a windowed row is
+* positioned against this box's PADDING box while the scroll-height spacer is
+* an in-flow child of its CONTENT box, so without it rows sit flush.
+*/
+function useCascaderVirtualGutter(contentElement) {
+	const [gutter, setGutter] = React$1.useState(NO_GUTTER);
+	React$1.useLayoutEffect(() => {
+		if (!contentElement) return;
+		const styles = getComputedStyle(contentElement);
+		const block = Number.parseFloat(styles.paddingTop) || 0;
+		const inline = Number.parseFloat(styles.paddingInlineStart || styles.paddingLeft) || 0;
+		setGutter((previous) => previous.block === block && previous.inline === inline ? previous : {
+			block,
+			inline
+		});
+	}, [contentElement]);
+	return gutter;
+}
+/** Logical insets, not `left` / `width`, so RTL needs no second code path. */
+function cascaderVirtualRowStyle(start, gutter) {
+	return {
+		position: "absolute",
+		top: 0,
+		insetInlineStart: gutter.inline,
+		insetInlineEnd: gutter.inline,
+		transform: `translateY(${start + gutter.block}px)`
+	};
+}
+/**
+* The element that actually SCROLLS: the `ScrollArea` viewport above the rows'
+* box, not the rows' box itself, which never overflows, so a virtualizer aimed
+* at it would read a full `clientHeight` and render every row. `closest` rather
+* than `parentElement`, plus a fallback to the content element, keeps a
+* hand-written `overflow-y-auto` container working.
+*/
+function cascaderScrollElement(content) {
+	if (!content) return null;
+	return content.closest("[data-slot=\"scroll-area-viewport\"]") ?? content;
+}
+/**
+* `role="presentation"` keeps the listbox owning nothing but options, and this
+* node's parent IS the rows' box, saving a ref threaded through `CascaderList`.
+*/
+function CascaderVirtualSpacer({ height, onContentElement }) {
+	return /* @__PURE__ */ jsx("div", {
+		ref: (node) => onContentElement(node?.parentElement ?? null),
+		role: "presentation",
+		"data-slot": "cascader-virtual-spacer",
+		style: { height }
+	});
+}
+/**
+* Windowed replacement for `CascaderItems`, dropped inside `CascaderList`. The
+* registration is a LAYOUT effect because the root derives `virtualized` from
+* it and the flip has to land before the browser paints. Until the root has
+* seen it, this renders exactly what `CascaderItems` does, so no frame carries
+* indexed rows while Base UI still owns the composite list.
+*/
+function CascaderVirtualItems(props) {
+	const { virtualized, registerVirtualRenderer } = useCascaderActions();
+	React$1.useLayoutEffect(() => registerVirtualRenderer(), [registerVirtualRenderer]);
+	if (!virtualized) return /* @__PURE__ */ jsx(CascaderItems, {});
+	return /* @__PURE__ */ jsx(CascaderVirtualRows, { ...props });
+}
+function CascaderVirtualRows({ estimateSize, overscan }) {
+	"use no memo";
+	const { estimateRowSize, overscan: rootOverscan, mode, isBranch, isSelectable, isSelected, isIndeterminate } = useCascaderActions();
+	const { renderedItems, treeRows, deepResults, loadStates } = useCascaderState();
+	const highlight = useCascaderHighlight();
+	const [contentElement, setContentElement] = React$1.useState(null);
+	const gutter = useCascaderVirtualGutter(contentElement);
+	const tree = mode === "tree";
+	const count = tree ? treeRows.length : renderedItems.length;
+	const showPath = !tree && deepResults !== null;
+	const getItemKey = React$1.useCallback((index) => (tree ? treeRows[index]?.node.value : renderedItems[index]?.value) ?? index, [
+		tree,
+		treeRows,
+		renderedItems
+	]);
+	const virtualizer = useCascaderVirtualizer({
+		count,
+		getScrollElement: () => cascaderScrollElement(contentElement),
+		estimateSize: estimateSize ?? estimateRowSize,
+		overscan: overscan ?? rootOverscan,
+		getItemKey,
+		activeIndex: highlight.index
+	});
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(CascaderVirtualSpacer, {
+		height: virtualizer.getTotalSize(),
+		onContentElement: setContentElement
+	}), virtualizer.getVirtualItems().map((row) => {
+		const flat = tree ? treeRows[row.index] : void 0;
+		const node = tree ? flat?.node : renderedItems[row.index];
+		if (!node) return null;
+		return /* @__PURE__ */ jsx(CascaderItem, {
+			ref: virtualizer.measureElement,
+			"data-index": row.index,
+			style: cascaderVirtualRowStyle(row.start, gutter),
+			node,
+			index: row.index,
+			depth: flat?.depth,
+			expanded: flat?.expanded,
+			branch: flat ? flat.branch : isBranch(node),
+			selectable: isSelectable(node),
+			selected: isSelected(node),
+			indeterminate: isIndeterminate(node),
+			...getCascaderMoreProps(node, loadStates),
+			showPath,
+			"aria-setsize": flat ? flat.setSize : count,
+			"aria-posinset": flat ? flat.posInSet : row.index + 1
+		}, row.key);
+	})] });
+}
+export { CascaderVirtualItems, useCascaderVirtualizer };

package/dist/vendor/reui.io/cascader/cascader.d.mts

@@ -0,0 +1,299 @@
+import { CascaderGetChildren, CascaderOnSearch, CascaderResolveValue } from "./cascader-async.mjs";
+import { CascaderItemState } from "./cascader-context.mjs";
+import { CascaderCheckedStrategy } from "./cascader-lib.mjs";
+import { CascaderActionItem, CascaderChangeDetails, CascaderLabels, CascaderMode, CascaderNode, CascaderSearchScope, CascaderSelectable } from "./cascader-types.mjs";
+import * as React$1 from "react";
+import { useRender } from "@base-ui/react/use-render";
+import { Combobox } from "@base-ui/react";
+/**
+ * Why the navigation path changed.
+ * - `"drill"`: a branch was entered (row press, level arrow, search hit).
+ * - `"back"`: one level up (back control, Backspace on an empty query).
+ * - `"breadcrumb"`: a jump to an exact depth in the trail.
+ * - `"reveal"`: the reopen navigated to the level holding the selection.
+ * - `"external"`: `setPath` called from outside the primitive's own flows.
+ */
+export type CascaderPathChangeReason = "drill" | "back" | "breadcrumb" | "reveal" | "external";
+/** Everything independent of the selection mode; the rest is on the two arms. */
+export interface CascaderBaseProps<T = unknown> {
+  /** Nested tree, or a flat list when `getParent` is supplied. */
+  items: CascaderNode<T>[];
+  /** Opt in to flat adjacency input by returning each node's parent value. */
+  getParent?: (node: CascaderNode<T>) => string | null | undefined;
+  /**
+   * Fetches one level on demand; `node` is `null` for the root, and only
+   * `{ value, label: value }` for a level on screen whose node has not loaded
+   * (a deep link, or a page-loaded level after a `loadKey` change). Return an
+   * array, or a `CascaderLoadResult` when the level pages. Pages cache apart
+   * from `items`; mark unfetched branches `hasChildren` or they read as leaves.
+   */
+  getChildren?: CascaderGetChildren<T>;
+  /**
+   * Server-side search, debounced by `searchDebounce`; replaces the local scan
+   * while the query is set. Results are detached: resolvable by value, in no
+   * level. Ignored in `mode="tree"`, where a hit belongs to no visible branch.
+   */
+  onSearch?: CascaderOnSearch<T>;
+  /** Milliseconds of quiet before `onSearch` fires. */
+  searchDebounce?: number;
+  /**
+   * Resolves a value the loader has never seen into its ancestor chain, root
+   * first, so the trigger can path a server-supplied selection. Runs with the
+   * popup closed too. Does NOT mark those levels loaded: opening one still
+   * fetches, and lists the node after its rows while it has pages left.
+   */
+  resolveValue?: CascaderResolveValue<T>;
+  /** Cache key. Changing it drops every page and aborts anything in flight. */
+  loadKey?: unknown;
+  /** Prefetch a highlighted branch's children after a pause. Off by default. */
+  prefetch?: boolean;
+  /**
+   * Called when a load fails. `context.parent` is the level (`null` for root);
+   * `context.reason` is `"level"`, `"more"`, `"retry"`, `"prefetch"`,
+   * `"search"` or `"resolve"`. Never for an aborted or superseded request.
+   */
+  onLoadError?: (error: unknown, context: {
+    parent: string | null;
+    reason: string;
+  }) => void;
+  /** Which nodes may be committed. Defaults to leaves only. */
+  selectable?: CascaderSelectable<T>;
+  /**
+   * Whether the built-in SINGLE-SELECT check is drawn. Defaults to true.
+   * `false` also gives back the inline-end gutter every style reserves for it;
+   * `data-selected` and `aria-selected` stay. A no-op under `multiple`, where
+   * the checkbox is the selection CONTROL rather than a decoration.
+   */
+  indicator?: boolean;
+  /**
+   * Footer ACTIONS: commands pinned below the list, never rows in it, and never
+   * touching the data tree. A childless `<CascaderFooter />` draws these; an
+   * action with `items` opens a side-anchored flyout rather than firing.
+   */
+  actions?: CascaderActionItem[];
+  /**
+   * Parent/child cascading. Multi-select only, off by default, and it needs
+   * committable branches (`selectable="any"` or a predicate). A commit selects
+   * or deselects every SELECTABLE node in the KNOWN subtree (loaded, or on a
+   * resolved chain) and reconciles ancestors. KNOWN is the semantic, not a
+   * hedge: a commit must not fan out into a request per level, so children
+   * arriving later arrive unchecked.
+   */
+  cascade?: boolean;
+  mode?: CascaderMode;
+  /** How a branch opens from the pointer in columns mode's ACTIVE column.
+   * `"click"` is the default, and neither value ever commits a selection. */
+  expandTrigger?: "click" | "hover";
+  path?: string[];
+  defaultPath?: string[];
+  /** The second argument says WHY. An existing `(path) => void` still works. */
+  onPathChange?: (path: string[], details: {
+    reason: CascaderPathChangeReason;
+  }) => void;
+  expanded?: string[];
+  defaultExpanded?: string[];
+  onExpandedChange?: (expanded: string[]) => void;
+  open?: boolean;
+  defaultOpen?: boolean;
+  /** Forwards Base UI's reason; a leaf commit's close says `"item-press"`. */
+  onOpenChange?: (open: boolean, details: {
+    reason: string;
+  }) => void;
+  /**
+   * Whether a SINGLE-SELECT leaf commit closes the popup. Defaults to true.
+   * `false` is for a compare-and-repick flow; Escape, outside press and the
+   * trigger still close. Ignored under `multiple`, which never closes.
+   */
+  closeOnSelect?: boolean;
+  inputValue?: string;
+  defaultInputValue?: string;
+  onInputValueChange?: (value: string) => void;
+  /**
+   * `"level"` (default) filters the level on screen, `"deep"` also searches
+   * below it, `"global"` searches the whole tree from any level.
+   */
+  searchScope?: CascaderSearchScope;
+  /** Custom matcher, replacing label + keywords substring matching. */
+  filter?: (node: CascaderNode<T>, normalizedQuery: string) => boolean;
+  /** On open, navigate to the level holding the selection. Default true.
+   * Not in `mode="tree"`, which has no levels to navigate. */
+  revealSelected?: boolean;
+  maxHeight?: number | string;
+  /**
+   * Window the rendered rows. `undefined` decides per level from
+   * `virtualizeThreshold`; `true`/`false` force it. Also opt-in at the markup
+   * level, so the base install pulls in no virtualization library.
+   */
+  virtualize?: boolean;
+  /** Row count at which windowing turns itself on. */
+  virtualizeThreshold?: number;
+  /** Row height handed to the virtualizer before a row has been measured. */
+  estimateRowSize?: number;
+  /** Rows rendered beyond each edge of the viewport. */
+  overscan?: number;
+  labels?: Partial<CascaderLabels>;
+  /** Replaces the entire row, affordances included. */
+  renderItem?: (node: CascaderNode<T>, state: CascaderItemState<T>) => React$1.ReactNode;
+  /** Replaces only the label block; icon, count, chevron and check stay. */
+  renderLabel?: (node: CascaderNode<T>, state: CascaderItemState<T>) => React$1.ReactNode;
+  disabled?: boolean;
+  /** Native form field name. Submits the selected value(s). */
+  name?: string;
+  /** Id of the owning form, for a cascader rendered outside it. */
+  form?: string;
+  /** Id of the control. Pairs the field with a `<label htmlFor>`. */
+  id?: string;
+  /** Marks the field required for native form validation. */
+  required?: boolean;
+  /** The value can be read and submitted, but not changed. */
+  readOnly?: boolean;
+  /** Marks the field invalid: `aria-invalid` and `data-invalid` on the trigger,
+   * the chips and the input, which every style's error treatment reads. */
+  invalid?: boolean;
+  /** Ref to the hidden input Base UI submits with, for form-library focus. */
+  inputRef?: React$1.Ref<HTMLInputElement>;
+  /** Renders without a floating popup, for an embedded `CascaderPanel`. */
+  inline?: boolean;
+  children?: React$1.ReactNode;
+}
+export interface CascaderSingleProps<T = unknown> extends CascaderBaseProps<T> {
+  multiple?: false;
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string, details: CascaderChangeDetails<T>) => void;
+  /** `never` so passing it is a compile error, not a silent no-op. */
+  max?: never;
+}
+/** Multi-select props. Enables checkbox rows and chip display. */
+export interface CascaderMultipleProps<T = unknown> extends CascaderBaseProps<T> {
+  multiple: true;
+  value?: string[];
+  defaultValue?: string[];
+  onValueChange?: (value: string[], details: CascaderChangeDetails<T>) => void;
+  /** Cap on selections. Further picks are refused, the existing ones survive. */
+  max?: number;
+}
+/** `multiple` discriminates: `value`, `onValueChange` and `max` narrow with it. */
+export type CascaderProps<T = unknown> = CascaderSingleProps<T> | CascaderMultipleProps<T>;
+/** No default on `T`: inferred from `items`, so `node.data` arrives typed. */
+declare function Cascader<T>({ items, getParent, getChildren, onSearch, searchDebounce, resolveValue, loadKey, prefetch, onLoadError, value: valueProp, defaultValue, onValueChange: onValueChangeProp, multiple, selectable, indicator, actions, cascade, max, mode, expandTrigger, path: pathProp, defaultPath, onPathChange, expanded: expandedProp, defaultExpanded, onExpandedChange, open: openProp, defaultOpen, onOpenChange, closeOnSelect, inputValue: inputValueProp, defaultInputValue, onInputValueChange, searchScope, filter, revealSelected, maxHeight, virtualize, virtualizeThreshold, estimateRowSize, overscan, labels: labelsProp, renderItem, renderLabel, disabled, name, form, id, required, readOnly, invalid, inputRef, inline, children }: CascaderProps<T>): React$1.JSX.Element;
+/** `Trigger.Props` stops short of `ref`, so it is intersected in, as the
+ * shadcn combobox wrapper also does: a form library needs a ref here, and
+ * `onBlur`, the "touched" signal, lands here too. */
+export interface CascaderTriggerProps extends Combobox.Trigger.Props, Pick<React$1.ComponentPropsWithRef<"button">, "ref"> {
+  /** Hides the trailing chevron, for a trigger that supplies its own. */
+  showIcon?: boolean;
+}
+declare function CascaderTrigger({ className, children, showIcon, ref, ...props }: CascaderTriggerProps): React$1.JSX.Element;
+export interface CascaderChipsProps extends Omit<Combobox.Chips.Props, "children">, Pick<React$1.ComponentPropsWithRef<"div">, "ref"> {
+  /** Shown in place of the chips when nothing is selected. */
+  placeholder?: React$1.ReactNode;
+  /**
+   * How a `cascade` selection is condensed into chips. DISPLAY ONLY: the
+   * stored value stays the full closure, which keeps a row's checked state an
+   * O(1) lookup. `"all"` (default) is one chip per value, `"parent"` collapses
+   * a fully selected branch, `"child"` chips only the deepest frontier.
+   * Removing a condensed chip removes its whole closure and reconciles.
+   */
+  strategy?: CascaderCheckedStrategy;
+  /** Replaces the chip list, receiving the resolved selection IN SELECTION
+   * ORDER. Keep that order: Base UI removes a chip by sibling position. */
+  children?: React$1.ReactNode | ((nodes: CascaderNode[]) => React$1.ReactNode);
+}
+/**
+ * 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>
+ * ```
+ */
+declare function CascaderChips({ className, children, placeholder, strategy, ...props }: CascaderChipsProps): React$1.JSX.Element;
+export interface CascaderChipProps extends Omit<Combobox.Chip.Props, "children"> {
+  node: CascaderNode;
+  /** Prefix the label with its ancestor trail. */
+  showPath?: boolean;
+  /** Trail segments to show, the node itself included. */
+  maxSegments?: number;
+  /** Hides the remove button, for a read-only chip. */
+  showRemove?: boolean;
+  /** Replaces Base UI's positional removal for this chip (remove button and
+   * Backspace/Delete). Supplied for a `strategy`-condensed chip, whose
+   * position no longer maps onto the stored array. */
+  onRemove?: () => void;
+  /** Replaces the chip's label. The remove button is still rendered. */
+  children?: React$1.ReactNode;
+}
+/** 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. */
+declare function CascaderChip({ className, node, showPath, maxSegments, showRemove, onRemove, children, ...props }: CascaderChipProps): React$1.JSX.Element;
+export interface CascaderContentProps extends Combobox.Popup.Props,
+/** Positioner surface forwarded as-is, so an unusual anchor does not force
+ * a rebuild of the content stack. No `trackAnchor`: Base UI 1.5.0 has
+ * none. */
+Pick<Combobox.Positioner.Props, "side" | "align" | "sideOffset" | "alignOffset" | "anchor" | "collisionBoundary" | "collisionPadding" | "sticky" | "positionMethod">,
+/** Where the portal mounts, for a shadow root or a scoped stacking context. */
+Pick<Combobox.Portal.Props, "container"> {}
+/** 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. */
+declare function CascaderContent({ className, side, sideOffset, align, alignOffset, anchor, collisionBoundary, collisionPadding, sticky, positionMethod, container, ref, ...props }: CascaderContentProps): React$1.JSX.Element;
+export type CascaderPanelProps = useRender.ComponentProps<"div">;
+/**
+ * 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.
+ */
+declare function CascaderPanel({ className, ...props }: CascaderPanelProps): React$1.ReactElement<unknown, string | React$1.JSXElementConstructor<any>>;
+export interface CascaderListProps extends Omit<Combobox.List.Props, "style"> {
+  /** Applied to the OUTER shell, which owns the height, so an inline
+   * `--cascader-max-height` lands where the bound can read it. Narrowed from
+   * Base UI's `style`: the shell is a plain `<div>` with no list state. */
+  style?: React$1.CSSProperties;
+  /** Caps this level's height; the panel still shrinks to fit. Default 24rem. */
+  maxHeight?: number | string;
+}
+/**
+ * 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`.
+ */
+declare function CascaderList({ className, style, maxHeight: maxHeightProp, ...props }: CascaderListProps): React$1.JSX.Element;
+export interface CascaderEmptyProps extends Combobox.Empty.Props {
+  /** @deprecated Ignored: the loading surface no longer draws skeletons. They
+   * promised a shape the level might not have and cost a second layout; the
+   * progress lives on the branch row instead. Kept so call sites compile. */
+  skeletonRows?: number;
+}
+/** 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. */
+declare function CascaderEmpty({ className, children, skeletonRows, ...props }: CascaderEmptyProps): React$1.JSX.Element;
+export type CascaderStatusProps = Combobox.Status.Props;
+/**
+ * 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.
+ */
+declare function CascaderStatus({ className, children, ...props }: CascaderStatusProps): React$1.JSX.Element;
+export { Cascader, CascaderChip, CascaderChips, CascaderContent, CascaderEmpty, type CascaderItemState, CascaderList, CascaderPanel, CascaderStatus, CascaderTrigger };