@databricks/design-system 2.0.1 → 2.0.3

package/dist-types/design-system/TypeaheadCombobox/TypeaheadComboboxMenuItem.d.ts

@@ -1,6 +1,10 @@
 import { css } from "@emotion/react";
 import type { UseComboboxReturnValue } from "downshift";
 import type { Theme } from "../../theme";
+/**
+* Deprecated in favor of `TypeaheadComboboxV2`.
+* @deprecated
+*/
 export interface TypeaheadComboboxMenuItemProps<T> extends React.HTMLAttributes<HTMLElement> {
 	item: T;
 	/**
@@ -22,6 +26,10 @@ export interface TypeaheadComboboxMenuItemProps<T> extends React.HTMLAttributes<
 	_type?: string;
 }
 export declare const getMenuItemStyles: (theme: Theme, isHighlighted: boolean, disabled?: boolean) => ReturnType<typeof css>;
+/**
+* Deprecated in favor of `TypeaheadComboboxV2`.
+* @deprecated
+*/
 export declare const TypeaheadComboboxMenuItem: <T>(props: TypeaheadComboboxMenuItemProps<T> & {
 	ref?: React.Ref<HTMLLIElement>;
 }) => JSX.Element;

package/dist-types/design-system/TypeaheadCombobox/TypeaheadComboboxMultiSelectInput.d.ts

@@ -2,6 +2,10 @@ import type { UseMultipleSelectionReturnValue } from "downshift";
 import type { ForwardRefExoticComponent, PropsWithoutRef, RefAttributes } from "react";
 import type { TypeaheadComboboxInputProps } from "./TypeaheadComboboxInput";
 import type { ComboboxStateAnalyticsReturnValue } from "./hooks";
+/**
+* Deprecated in favor of `TypeaheadComboboxV2`.
+* @deprecated
+*/
 export interface TypeaheadComboboxMultiSelectInputProps<T> extends TypeaheadComboboxInputProps<T> {
 	comboboxState: ComboboxStateAnalyticsReturnValue<T>;
 	multipleSelectionState: UseMultipleSelectionReturnValue<T>;
@@ -18,5 +22,18 @@ export interface TypeaheadComboboxMultiSelectInputProps<T> extends TypeaheadComb
 	width?: string | number;
 	maxHeight?: string | number;
 	disableTooltip?: boolean;
+	/**
+	* Height of the control while its tags fit on one row; extra rows grow it either way.
+	* Omitted is 36px, `'middle'` is 32px — the height of `Input`, `Button` and a middle
+	* `DialogComboboxTrigger`.
+	*
+	* Narrows the inherited `ButtonSize`: `'small'` (24px) is unreachable because a tag row
+	* is itself 24px tall.
+	*/
+	size?: "middle";
 }
+/**
+* Deprecated in favor of `TypeaheadComboboxV2`.
+* @deprecated
+*/
 export declare const TypeaheadComboboxMultiSelectInput: ForwardRefExoticComponent<PropsWithoutRef<TypeaheadComboboxMultiSelectInputProps<any>> & RefAttributes<HTMLInputElement>>;

package/dist-types/design-system/TypeaheadCombobox/TypeaheadComboboxRoot.d.ts

@@ -1,10 +1,18 @@
 import React from "react";
 import type { ComboboxStateAnalyticsReturnValue } from "./hooks";
+/**
+* Deprecated in favor of `TypeaheadComboboxV2`.
+* @deprecated
+*/
 export interface TypeaheadComboboxRootProps<T> extends React.HTMLAttributes<HTMLDivElement> {
 	comboboxState: ComboboxStateAnalyticsReturnValue<T>;
 	multiSelect?: boolean;
 	floatingStrategy?: "absolute" | "fixed";
 	children: React.ReactNode;
 }
+/**
+* Deprecated in favor of `TypeaheadComboboxV2`.
+* @deprecated
+*/
 export declare const TypeaheadComboboxRoot: React.FC<React.PropsWithChildren<TypeaheadComboboxRootProps<any>>>;
 export default TypeaheadComboboxRoot;

package/dist-types/design-system/TypeaheadCombobox/TypeaheadComboboxSectionHeader.d.ts

@@ -1 +1,5 @@
+/**
+* Deprecated in favor of `TypeaheadComboboxV2`.
+* @deprecated
+*/
 export declare const TypeaheadComboboxSectionHeader: ({ children, ...props }: React.HTMLAttributes<HTMLDivElement>) => JSX.Element;

package/dist-types/design-system/TypeaheadCombobox/TypeaheadComboboxSelectedItem.d.ts

@@ -1,6 +1,10 @@
 import { type SerializedStyles } from "@emotion/react";
 import type { UseMultipleSelectionGetSelectedItemPropsOptions } from "downshift";
 import type { Theme } from "../../theme";
+/**
+* Deprecated in favor of `TypeaheadComboboxV2`.
+* @deprecated
+*/
 export interface TypeaheadComboboxSelectedItemProps<T> {
 	label: React.ReactNode;
 	item: any;
@@ -9,4 +13,8 @@ export interface TypeaheadComboboxSelectedItemProps<T> {
 	disabled?: boolean;
 }
 export declare const getSelectedItemStyles: (theme: Theme, disabled?: boolean) => SerializedStyles;
+/**
+* Deprecated in favor of `TypeaheadComboboxV2`.
+* @deprecated
+*/
 export declare const TypeaheadComboboxSelectedItem: React.FC<React.PropsWithChildren<any>>;

package/dist-types/design-system/TypeaheadCombobox/TypeaheadComboboxSeparator.d.ts

@@ -1 +1,5 @@
+/**
+* Deprecated in favor of `TypeaheadComboboxV2`.
+* @deprecated
+*/
 export declare const TypeaheadComboboxSeparator: (props: React.HTMLAttributes<HTMLDivElement>) => JSX.Element;

package/dist-types/design-system/TypeaheadCombobox/TypeaheadComboboxToggleButton.d.ts

@@ -1,5 +1,9 @@
 import type { ForwardRefExoticComponent, PropsWithoutRef, RefAttributes } from "react";
 import React from "react";
+/**
+* Deprecated in favor of `TypeaheadComboboxV2`.
+* @deprecated
+*/
 export interface DownshiftToggleButtonProps {
 	id: string;
 	onClick: (e: React.SyntheticEvent) => void;
@@ -8,5 +12,9 @@ export interface DownshiftToggleButtonProps {
 interface TypeaheadComboboxToggleButtonProps extends DownshiftToggleButtonProps {
 	disabled?: boolean;
 }
+/**
+* Deprecated in favor of `TypeaheadComboboxV2`.
+* @deprecated
+*/
 export declare const TypeaheadComboboxToggleButton: ForwardRefExoticComponent<PropsWithoutRef<TypeaheadComboboxToggleButtonProps> & RefAttributes<HTMLButtonElement>>;
 export {};

package/dist-types/design-system/TypeaheadCombobox/hooks/downshiftHookWrappers.d.ts

@@ -43,9 +43,17 @@ export type ComboboxStateAnalyticsReturnValue<T> = UseComboboxReturnValue<T> & A
 	onView: (value: any) => void;
 	firstOnViewValue?: string;
 };
+/**
+* Deprecated in favor of `TypeaheadComboboxV2`.
+* @deprecated
+*/
 export declare function useComboboxState<T>({ allItems, items, itemToString, onIsOpenChange, allowNewValue, formValue, formOnChange, formOnBlur, componentId, valueHasNoPii, analyticsEvents, matcher, preventUnsetOnBlur, selectedMatcher, ...props }: UseComboboxStateProps<T>): ComboboxStateAnalyticsReturnValue<T>;
 interface AnalyticsConfig extends AnalyticsEventValueChangeNoPiiFlagProps<DesignSystemEventProviderAnalyticsEventTypes.OnValueChange | DesignSystemEventProviderAnalyticsEventTypes.OnView> {
 	itemToString?: (item: any) => string;
 }
+/**
+* Deprecated in favor of `TypeaheadComboboxV2`.
+* @deprecated
+*/
 export declare function useMultipleSelectionState<T>(selectedItems: T[], setSelectedItems: React.Dispatch<React.SetStateAction<T[]>>, { componentId, analyticsEvents, valueHasNoPii, itemToString }: AnalyticsConfig): UseMultipleSelectionReturnValue<T>;
 export {};

package/dist-types/design-system/TypeaheadComboboxV2/CountBadge.d.ts

@@ -0,0 +1,6 @@
+export interface CountBadgeProps extends React.HTMLAttributes<HTMLDivElement> {
+	countStartAt?: number;
+	totalCount: number;
+	disabled?: boolean;
+}
+export declare const CountBadge: ({ countStartAt, totalCount, disabled, ...restProps }: CountBadgeProps) => JSX.Element;

package/dist-types/design-system/TypeaheadComboboxV2/TypeaheadComboboxAddButton.d.ts

@@ -0,0 +1,3 @@
+import type { ForwardRefExoticComponent, RefAttributes } from "react";
+import type { ButtonProps } from "../Button";
+export declare const TypeaheadComboboxAddButton: ForwardRefExoticComponent<ButtonProps & RefAttributes<HTMLButtonElement>>;

package/dist-types/design-system/TypeaheadComboboxV2/TypeaheadComboboxCheckboxItem.d.ts

@@ -0,0 +1,10 @@
+import { type TypeaheadComboboxMenuItemProps } from "./TypeaheadComboboxMenuItem";
+export interface TypeaheadComboboxCheckboxItemProps<T> extends TypeaheadComboboxMenuItemProps<T> {
+	/** Custom equality check for "is this item in selectedItems"; falls back to context key lookup. */
+	selectedMatcher?: (a: T, b: T) => boolean;
+	/** Required for `selectedMatcher` to function — kept for API parity with the original. */
+	selectedItems?: T[];
+}
+export declare const TypeaheadComboboxCheckboxItem: <T>(props: TypeaheadComboboxCheckboxItemProps<T> & {
+	ref?: React.Ref<HTMLLIElement>;
+}) => JSX.Element;

package/dist-types/design-system/TypeaheadComboboxV2/TypeaheadComboboxControls.d.ts

@@ -0,0 +1,11 @@
+export interface TypeaheadComboboxControlsProps {
+	showClearSelectionButton?: boolean;
+	showComboboxToggleButton?: boolean;
+	handleClear?: () => void;
+	disabled?: boolean;
+	loading?: boolean;
+	/** When true, renders as an inline flex container for use inside AntD's suffix slot. */
+	inline?: boolean;
+	className?: string;
+}
+export declare const TypeaheadComboboxControls: ({ showClearSelectionButton, showComboboxToggleButton, handleClear, disabled, loading, inline, className }: TypeaheadComboboxControlsProps) => JSX.Element;

package/dist-types/design-system/TypeaheadComboboxV2/TypeaheadComboboxFooter.d.ts

@@ -0,0 +1,2 @@
+export type TypeaheadComboboxFooterProps = React.HTMLAttributes<HTMLDivElement>;
+export declare const TypeaheadComboboxFooter: ({ children, onKeyDown, ...restProps }: TypeaheadComboboxFooterProps) => JSX.Element;

package/dist-types/design-system/TypeaheadComboboxV2/TypeaheadComboboxInput.d.ts

@@ -0,0 +1,9 @@
+import type { ForwardRefExoticComponent, RefAttributes } from "react";
+import type { InputProps } from "../Input";
+export interface TypeaheadComboboxInputProps extends Omit<InputProps, "componentId" | "analyticsEvents"> {
+	allowClear?: boolean;
+	showComboboxToggleButton?: boolean;
+	/** When true, replaces the dropdown toggle button with a spinner. */
+	loading?: boolean;
+}
+export declare const TypeaheadComboboxInput: ForwardRefExoticComponent<TypeaheadComboboxInputProps & RefAttributes<HTMLInputElement | null>>;

package/dist-types/design-system/TypeaheadComboboxV2/TypeaheadComboboxMenu.d.ts

@@ -0,0 +1,17 @@
+import type { ForwardRefExoticComponent, HTMLAttributes, ReactNode, Ref, RefAttributes } from "react";
+export interface TypeaheadComboboxMenuProps extends HTMLAttributes<HTMLUListElement> {
+	loading?: boolean;
+	emptyText?: string | ReactNode;
+	width?: number | string;
+	minWidth?: number | string;
+	maxWidth?: number | string;
+	minHeight?: number | string;
+	maxHeight?: number | string;
+	/** For react-virtual integration: pass `virtualizer.getTotalSize()` (or `totalSize`). */
+	listWrapperHeight?: number;
+	/** For react-virtual integration: ref to the scrollable parent (the listbox `<ul>`). Merged with the listbox ref. */
+	virtualizerRef?: Ref<HTMLUListElement>;
+	children?: ReactNode;
+	matchTriggerWidth?: boolean;
+}
+export declare const TypeaheadComboboxMenu: ForwardRefExoticComponent<TypeaheadComboboxMenuProps & RefAttributes<HTMLElement | null>>;

package/dist-types/design-system/TypeaheadComboboxV2/TypeaheadComboboxMenuItem.d.ts

@@ -0,0 +1,16 @@
+import type { SerializedStyles } from "@emotion/react";
+import type { Theme } from "../../theme";
+export interface TypeaheadComboboxMenuItemProps<T> extends React.HTMLAttributes<HTMLLIElement> {
+	item: T;
+	/** Kept for API parity with the original; not consumed by react-aria's useOption. */
+	index?: number;
+	textOverflowMode?: "ellipsis" | "multiline";
+	isDisabled?: boolean;
+	disabledReason?: React.ReactNode;
+	hintContent?: React.ReactNode;
+	children?: React.ReactNode;
+}
+export declare const getMenuItemStyles: (theme: Theme, isHighlighted: boolean, disabled?: boolean) => SerializedStyles;
+export declare const TypeaheadComboboxMenuItem: <T>(props: TypeaheadComboboxMenuItemProps<T> & {
+	ref?: React.Ref<HTMLLIElement>;
+}) => JSX.Element;

package/dist-types/design-system/TypeaheadComboboxV2/TypeaheadComboboxMultiSelectInput.d.ts

@@ -0,0 +1,18 @@
+import type { ValidationState } from "../types";
+export interface TypeaheadComboboxMultiSelectInputProps<T> extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size"> {
+	selectedItems: T[];
+	setSelectedItems: React.Dispatch<React.SetStateAction<T[]>>;
+	getSelectedItemLabel: (item: T) => React.ReactNode;
+	allowClear?: boolean;
+	showComboboxToggleButton?: boolean;
+	loading?: boolean;
+	/** Tag overflow threshold: number (default 20) or 'responsive' to fit naturally on one line. */
+	showTagAfterValueCount?: number | "responsive";
+	width?: string | number;
+	maxHeight?: string | number;
+	disableTooltip?: boolean;
+	validationState?: ValidationState;
+}
+export declare const TypeaheadComboboxMultiSelectInput: <T>(props: TypeaheadComboboxMultiSelectInputProps<T> & {
+	ref?: React.Ref<HTMLInputElement>;
+}) => JSX.Element;

package/dist-types/design-system/TypeaheadComboboxV2/TypeaheadComboboxRoot.d.ts

@@ -0,0 +1,17 @@
+import type { ForwardRefExoticComponent, RefAttributes } from "react";
+import type { ComboboxStateValue } from "./hooks/useComboboxState";
+export interface TypeaheadComboboxRootProps<T> extends React.HTMLAttributes<HTMLDivElement> {
+	/** Result of `useComboboxState({...})`. */
+	comboboxState: ComboboxStateValue<T>;
+	"aria-label"?: string;
+	/**
+	* When true (the default), Tab from the input moves DOM focus into the footer's first focusable
+	* control (menu stays open), and Shift+Tab / Escape from the footer returns focus to the input.
+	* Makes a real footer <button> keyboard/SR-reachable. A footer with no focusable control (e.g. a
+	* text-only footer) is unaffected — Tab falls through to the normal commit-and-close. Set to false
+	* only to opt a combobox out and keep the input as the sole tab stop.
+	*/
+	footerFocusable?: boolean;
+	children: React.ReactNode;
+}
+export declare const TypeaheadComboboxRoot: ForwardRefExoticComponent<TypeaheadComboboxRootProps<any> & RefAttributes<HTMLDivElement>>;

package/dist-types/design-system/TypeaheadComboboxV2/TypeaheadComboboxSectionHeader.d.ts

@@ -0,0 +1 @@
+export declare const TypeaheadComboboxSectionHeader: ({ children, ...props }: React.HTMLAttributes<HTMLDivElement>) => JSX.Element;

package/dist-types/design-system/TypeaheadComboboxV2/TypeaheadComboboxSelectedItem.d.ts

@@ -0,0 +1,11 @@
+import { type SerializedStyles } from "@emotion/react";
+import type { ForwardRefExoticComponent, RefAttributes } from "react";
+import type { Theme } from "../../theme";
+export interface TypeaheadComboboxSelectedItemProps {
+	label: React.ReactNode;
+	/** The raw selected item — used to look up its key in the context's `itemsByKey`. */
+	item: unknown;
+	disabled?: boolean;
+}
+export declare const getSelectedItemStyles: (theme: Theme, disabled?: boolean) => SerializedStyles;
+export declare const TypeaheadComboboxSelectedItem: ForwardRefExoticComponent<TypeaheadComboboxSelectedItemProps & RefAttributes<HTMLSpanElement>>;

package/dist-types/design-system/TypeaheadComboboxV2/TypeaheadComboboxSeparator.d.ts

@@ -0,0 +1 @@
+export declare const TypeaheadComboboxSeparator: (props: React.HTMLAttributes<HTMLDivElement>) => JSX.Element;

package/dist-types/design-system/TypeaheadComboboxV2/TypeaheadComboboxToggleButton.d.ts

@@ -0,0 +1,4 @@
+export interface TypeaheadComboboxToggleButtonProps {
+	disabled?: boolean;
+}
+export declare const TypeaheadComboboxToggleButton: ({ disabled }: TypeaheadComboboxToggleButtonProps) => JSX.Element;

package/dist-types/design-system/TypeaheadComboboxV2/hooks/footerFocus.d.ts

@@ -0,0 +1,13 @@
+/**
+* Focus the first tabbable control in `container`. Returns true only if focus actually moved onto a
+* control inside `container` — react-aria skips non-visible/inert nodes and `.focus()` on them is a
+* no-op, so we confirm against the resulting element rather than assuming a query match succeeded.
+*/
+export declare function focusFirstFocusable(container: HTMLElement | null): boolean;
+/**
+* Step focus to the adjacent tabbable control within `container`, starting from the currently focused
+* element. Returns true if focus moved to another control in `container`; false when there is none in
+* that direction (Shift+Tab from the first control, or forward Tab from the last) — the caller's cue
+* to return focus to the input instead of letting it escape the popover.
+*/
+export declare function focusAdjacentFocusable(container: HTMLElement | null, direction: "next" | "previous"): boolean;

package/dist-types/design-system/TypeaheadComboboxV2/hooks/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./useComboboxState";
+export * from "./useMultipleSelectionState";
+export * from "./useTypeaheadComboboxContext";
+export * from "./useVirtualizedComboboxScroll";

package/dist-types/design-system/TypeaheadComboboxV2/hooks/useComboboxItems.d.ts

@@ -0,0 +1,32 @@
+import type { Key } from "@react-types/shared";
+export type WrappedItem<T> = {
+	id: Key;
+	value: T;
+};
+/** JSON-encode a list of items by their display strings (the multi-select analytics value shape). */
+export declare const mapItemsToString: <T>(items: T[], itemToString: (item: T | null) => string) => string;
+interface UseComboboxItemsParams<T> {
+	allItems: T[];
+	itemToString?: (item: T) => string;
+	getKey?: (item: T) => Key;
+}
+export interface ComboboxItems<T> {
+	itemToString: (item: T | null | undefined) => string;
+	getKey: (item: T) => Key;
+	wrappedItems: WrappedItem<T>[];
+	itemsByKey: Map<Key, T>;
+	/**
+	* textValue → every item sharing that display string. react-aria's `defaultFilter` receives only
+	* the display string (not the key), so items that map to the same `itemToString` are
+	* indistinguishable to the filter; the custom-matcher path matches the label if any backing item
+	* matches.
+	*/
+	itemsByTextValue: Map<string, T[]>;
+}
+/**
+* Item ↔ key/string mapping for the TypeaheadCombobox: resolves each item's display string and
+* key, wraps items for react-aria's collection, and builds the key/text lookup maps. Warns in dev
+* when two items collapse to the same key.
+*/
+export declare function useComboboxItems<T>({ allItems, itemToString: itemToStringProp, getKey: getKeyProp }: UseComboboxItemsParams<T>): ComboboxItems<T>;
+export {};

package/dist-types/design-system/TypeaheadComboboxV2/hooks/useComboboxState.d.ts

@@ -0,0 +1,81 @@
+import type { ComboBoxState, SelectionMode } from "@react-stately/combobox";
+import type { Key } from "@react-types/shared";
+import { type WrappedItem } from "./useComboboxItems";
+import { DesignSystemEventProviderAnalyticsEventTypes } from "../../DesignSystemEventProvider";
+import type { AnalyticsEventValueChangeNoPiiFlagProps } from "../../types";
+interface BaseComboboxStateProps<T> extends AnalyticsEventValueChangeNoPiiFlagProps<DesignSystemEventProviderAnalyticsEventTypes.OnValueChange | DesignSystemEventProviderAnalyticsEventTypes.OnView> {
+	allItems: T[];
+	itemToString?: (item: T) => string;
+	getKey?: (item: T) => Key;
+	matcher?: (item: T, lowerCasedInputValue: string) => boolean;
+	/**
+	* Predicate marking items the user cannot select. react-aria enforces non-selection via the
+	* state's `disabledKeys`, so disabled must be declared here (a `<MenuItem isDisabled>` only
+	* styles the row — it can't block selection on its own).
+	*/
+	isItemDisabled?: (item: T) => boolean;
+	allowNewValue?: boolean;
+	/**
+	* Single-select only: open the menu showing the full option list (even with a value selected), and
+	* filter only once the user types. Multi-select clears the input on select, so it is unaffected.
+	*/
+	showAllOptionsOnOpen?: boolean;
+	initialInputValue?: string;
+	initialSelectedItem?: T;
+	formValue?: T;
+	formOnChange?: (value: T | null) => void;
+	formOnBlur?: (value: T | null) => void;
+	onStateChange?: (change: {
+		type: "select" | "input" | "open" | "close";
+		selectedItem: T | null;
+		inputValue: string;
+	}) => void;
+	onIsOpenChange?: (isOpen: boolean) => void;
+	/**
+	* @deprecated No-op under react-aria. Blur never clears the selection (it only re-syncs the
+	* input text), and closing on blur is required for non-modal popover dismissal, so this flag
+	* is ignored. Kept only for source compatibility with the original API.
+	*/
+	preventUnsetOnBlur?: boolean;
+}
+export interface SingleSelectComboboxStateProps<T> extends BaseComboboxStateProps<T> {
+	multiSelect?: false;
+}
+export interface MultiSelectComboboxStateProps<T> extends BaseComboboxStateProps<T> {
+	multiSelect: true;
+	selectedItems: T[];
+	setSelectedItems: React.Dispatch<React.SetStateAction<T[]>>;
+}
+export type UseComboboxStateProps<T> = SingleSelectComboboxStateProps<T> | MultiSelectComboboxStateProps<T>;
+export interface ComboboxStateValue<T> {
+	state: ComboBoxState<WrappedItem<T>, SelectionMode>;
+	itemsByKey: Map<Key, T>;
+	getKeyForItem: (item: T) => Key;
+	itemToString: (item: T | null | undefined) => string;
+	selectedItems: T[];
+	selectedKeys: Set<Key>;
+	/** Items remaining after react-aria's `defaultFilter` runs against the current `state.inputValue`. */
+	filteredItems: T[];
+	removeItem: (item: T) => void;
+	removeByKey: (key: Key) => void;
+	clearSelection: () => void;
+	isSelected: (item: T) => boolean;
+	/** Fire the consumer's `formOnBlur` on a genuine input blur (wired onto the input by `Root`). */
+	onInputBlur: () => void;
+	componentId: string;
+	analyticsEvents?: DesignSystemEventProviderAnalyticsEventTypes[];
+	valueHasNoPii?: boolean;
+	onView: (value: any) => void;
+	firstOnViewValue?: string;
+	multiSelect: boolean;
+	showAllOptionsOnOpen: boolean;
+}
+/**
+* Backs the Du Bois TypeaheadCombobox (react-aria variant) by wrapping react-aria's
+* `useComboBoxState`. Handles single- and multi-select modes, item↔key mapping, filtering
+* (default substring match or a custom `matcher`), selection helpers (`removeItem`,
+* `clearSelection`, `isSelected`), form `onChange`/`onBlur` bridging, and analytics wiring.
+* The returned object is what the `Root`/`Input`/`Menu` subtree consumes via context.
+*/
+export declare function useComboboxState<T>(props: UseComboboxStateProps<T>): ComboboxStateValue<T>;
+export {};

package/dist-types/design-system/TypeaheadComboboxV2/hooks/useComboboxStateProps.d.ts

@@ -0,0 +1,36 @@
+import type { ComboBoxState, ComboBoxStateOptions, SelectionMode } from "@react-stately/combobox";
+import type { MutableRefObject } from "react";
+import { type ComboboxItems, type WrappedItem } from "./useComboboxItems";
+interface UseComboboxStatePropsParams<T> {
+	items: ComboboxItems<T>;
+	multiSelect: boolean;
+	matcher?: (item: T, lowerCasedInputValue: string) => boolean;
+	isItemDisabled?: (item: T) => boolean;
+	allowNewValue: boolean;
+	initialInputValue?: string;
+	initialSelectedItem?: T;
+	formValue?: T;
+	formOnChange?: (value: T | null) => void;
+	onStateChange?: (change: {
+		type: "select" | "input" | "open" | "close";
+		selectedItem: T | null;
+		inputValue: string;
+	}) => void;
+	onIsOpenChange?: (isOpen: boolean) => void;
+	/** Controlled selected items for multi-select; null for single-select. */
+	externalSelectedItems: T[] | null;
+	/** Setter for controlled multi-select; null for single-select. */
+	externalSetSelectedItems: React.Dispatch<React.SetStateAction<T[]>> | null;
+	/** Live ref to the created state, so the selection handler can imperatively clear the input. */
+	stateRef: MutableRefObject<ComboBoxState<WrappedItem<T>, SelectionMode> | null>;
+	onValueChange?: (value: string) => void;
+}
+/**
+* Assembles the `ComboBoxStateOptions` passed to react-aria's `useComboBoxState`: the filter, the
+* disabled-keys set, the controlled/uncontrolled selection value, the initial (uncontrolled) input
+* text, and the selection/input/open change handlers (including analytics + multi-select
+* input-reset). Kept separate from `useComboboxState` so the wiring into react-aria is isolated
+* from the selection helpers the hook derives afterward.
+*/
+export declare function useComboboxStateProps<T>({ items, multiSelect, matcher, isItemDisabled, allowNewValue, initialInputValue, initialSelectedItem, formValue, formOnChange, onStateChange, onIsOpenChange, externalSelectedItems, externalSetSelectedItems, stateRef, onValueChange }: UseComboboxStatePropsParams<T>): ComboBoxStateOptions<WrappedItem<T>, SelectionMode>;
+export {};

package/dist-types/design-system/TypeaheadComboboxV2/hooks/useMultipleSelectionState.d.ts

@@ -0,0 +1,25 @@
+import type { Key } from "@react-types/shared";
+import { DesignSystemEventProviderAnalyticsEventTypes } from "../../DesignSystemEventProvider";
+import type { AnalyticsEventValueChangeNoPiiFlagProps } from "../../types";
+export interface UseMultipleSelectionStateConfig<T> extends AnalyticsEventValueChangeNoPiiFlagProps<DesignSystemEventProviderAnalyticsEventTypes.OnValueChange | DesignSystemEventProviderAnalyticsEventTypes.OnView> {
+	itemToString?: (item: T) => string;
+	getKey?: (item: T) => Key;
+}
+export interface MultipleSelectionStateReturn<T> {
+	selectedItems: T[];
+	/** Stable Set of keys for currently-selected items — used by CheckboxItem to render the checked state quickly. */
+	selectedKeys: Set<Key>;
+	addItem: (item: T) => void;
+	removeItem: (item: T) => void;
+	removeByKey: (key: Key) => void;
+	clear: () => void;
+	/** Lookup helper. */
+	isSelected: (item: T) => boolean;
+}
+/**
+* Companion hook to `useComboboxState` in multi-select mode. Returns chip-management helpers
+* keyed off the consumer-owned `selectedItems` array, plus analytics wiring. Mostly redundant —
+* the state hook already exposes `removeItem`/`removeByKey`/`clearSelection` — but kept for API
+* parity with the original.
+*/
+export declare function useMultipleSelectionState<T>(selectedItems: T[], setSelectedItems: React.Dispatch<React.SetStateAction<T[]>>, { componentId, analyticsEvents, valueHasNoPii, itemToString, getKey }: UseMultipleSelectionStateConfig<T>): MultipleSelectionStateReturn<T>;

package/dist-types/design-system/TypeaheadComboboxV2/hooks/useRestoreHighlightedOption.d.ts

@@ -0,0 +1,18 @@
+import type { ComboBoxState, SelectionMode } from "@react-stately/combobox";
+import type { WrappedItem } from "./useComboboxItems";
+/**
+* Keeps an option highlighted while the menu is open so Enter commits it, matching the original
+* downshift variant's `defaultHighlightedIndex: 0`. react-aria clears the focused key on every input
+* change (useComboBoxState: "Clear focused key when input value changes"), and its `commit()` only
+* selects when `focusedKey != null` — so without this, typing leaves nothing highlighted and Enter
+* falls through to commitValue(), selecting nothing.
+*
+* Only re-focuses when nothing is focused, so arrowing or hovering to another option sticks and we
+* merely restore the default after react-aria drops it. Keyed on the collection so it re-runs as
+* filtering narrows the list. Skipped when `allowNewValue`: there Enter commits the typed text, so
+* pre-highlighting an option would hijack it and select the option instead.
+*/
+export declare function useRestoreHighlightedOption<T>(state: ComboBoxState<WrappedItem<T>, SelectionMode>, { allowNewValue, showAllOptionsOnOpen }: {
+	allowNewValue: boolean;
+	showAllOptionsOnOpen: boolean;
+}): void;

package/dist-types/design-system/TypeaheadComboboxV2/hooks/useScrollOptionIntoView.d.ts

@@ -0,0 +1,11 @@
+import type { RefObject } from "react";
+/**
+* Scrolls the focused option into view while the combobox is open. react-aria keeps DOM focus on
+* the input (options are highlighted via `aria-activedescendant`), so the listbox does not get
+* native focus scrolling for the active option. Shared by the menu item and checkbox item.
+*
+* This handles the non-virtualized path in full, and final-pixel alignment for a virtualized row
+* once it is mounted. It cannot reach an option that isn't rendered — under virtualization the
+* consumer additionally wires `useVirtualizedComboboxScroll`, which mounts the off-screen row first.
+*/
+export declare function useScrollOptionIntoView(itemRef: RefObject<HTMLElement | null>, isFocused: boolean, isOpen: boolean): void;

package/dist-types/design-system/TypeaheadComboboxV2/hooks/useTypeaheadComboboxContext.d.ts

@@ -0,0 +1,2 @@
+import type { TypeaheadComboboxV2ContextType } from "../providers/TypeaheadComboboxContext";
+export declare const useTypeaheadComboboxV2Context: () => TypeaheadComboboxV2ContextType;

package/dist-types/design-system/TypeaheadComboboxV2/hooks/useVirtualizedComboboxScroll.d.ts

@@ -0,0 +1,36 @@
+import type { ComboBoxState, SelectionMode } from "@react-stately/combobox";
+import type { Key } from "@react-types/shared";
+import type { WrappedItem } from "./useComboboxItems";
+interface UseVirtualizedComboboxScrollParams<T> {
+	/** The react-aria combobox state (`comboboxState.state`). */
+	state: ComboBoxState<WrappedItem<T>, SelectionMode>;
+	/** Post-filter items, index-aligned with the react-virtual `size`. */
+	filteredItems: T[];
+	/** Same key resolver the combobox uses (`comboboxState.getKeyForItem`). */
+	getKey: (item: T) => Key;
+	/**
+	* The react-virtual (v2) / TanStack Virtual (v3) instance. Only `scrollToIndex` is used, typed
+	* structurally so the design-system does not couple to a specific virtualization library version.
+	*/
+	virtualizer: {
+		scrollToIndex: (index: number) => void;
+	};
+}
+/**
+* Scrolls the virtually-focused option into view when it is NOT currently rendered. Under
+* virtualization only a window of options is in the DOM, so react-aria's own scroll-into-view (and
+* our per-item `useScrollOptionIntoView`) can't reach an option that hasn't mounted — arrowing past
+* the rendered window would otherwise appear to do nothing. This bridges react-aria's
+* `selectionManager.focusedKey` to the consumer's virtualizer so the row mounts and scrolls in.
+*
+* Consumer-invoked (the consumer owns the virtualizer instance).
+*
+* The effect keys ONLY on `focusedKey`/`isOpen` — i.e. it runs when the *active option* changes,
+* not on every render. This is essential: `useVirtual` returns a new `virtualizer` object on every
+* render and re-renders on every scroll frame, so depending on it would re-fire `scrollToIndex` on
+* each scroll tick and fight the user's scrollbar drag. The mutable inputs are read through a ref
+* instead. Hovering an option also moves `focusedKey`, but a hovered option is by definition already
+* rendered/visible, so `scrollToIndex` (align "auto") is a no-op for it.
+*/
+export declare function useVirtualizedComboboxScroll<T>({ state, filteredItems, getKey, virtualizer }: UseVirtualizedComboboxScrollParams<T>): void;
+export {};

package/dist-types/design-system/TypeaheadComboboxV2/index.d.ts

@@ -0,0 +1,13 @@
+export { TypeaheadComboboxRoot } from "./TypeaheadComboboxRoot";
+export { TypeaheadComboboxMenu } from "./TypeaheadComboboxMenu";
+export { TypeaheadComboboxMenuItem } from "./TypeaheadComboboxMenuItem";
+export { TypeaheadComboboxCheckboxItem } from "./TypeaheadComboboxCheckboxItem";
+export { TypeaheadComboboxInput } from "./TypeaheadComboboxInput";
+export { TypeaheadComboboxMultiSelectInput } from "./TypeaheadComboboxMultiSelectInput";
+export { TypeaheadComboboxSectionHeader } from "./TypeaheadComboboxSectionHeader";
+export { TypeaheadComboboxSelectedItem } from "./TypeaheadComboboxSelectedItem";
+export { TypeaheadComboboxSeparator } from "./TypeaheadComboboxSeparator";
+export { TypeaheadComboboxToggleButton } from "./TypeaheadComboboxToggleButton";
+export { TypeaheadComboboxFooter } from "./TypeaheadComboboxFooter";
+export { TypeaheadComboboxAddButton } from "./TypeaheadComboboxAddButton";
+export * from "./hooks";

package/dist-types/design-system/TypeaheadComboboxV2/providers/TypeaheadComboboxContext.d.ts

@@ -0,0 +1,47 @@
+import type { AriaButtonProps } from "@react-aria/button";
+import type { AriaListBoxOptions } from "@react-aria/listbox";
+import type { ComboBoxState, SelectionMode } from "@react-stately/combobox";
+import type { Key } from "@react-types/shared";
+import { type InputHTMLAttributes, type MutableRefObject, type RefObject } from "react";
+import type { DesignSystemEventProviderAnalyticsEventTypes } from "../../DesignSystemEventProvider/DesignSystemEventProvider";
+import type { AnalyticsEventProps } from "../../types";
+import type { WrappedItem } from "../hooks/useComboboxItems";
+export interface TypeaheadComboboxV2ContextType extends AnalyticsEventProps<DesignSystemEventProviderAnalyticsEventTypes.OnValueChange | DesignSystemEventProviderAnalyticsEventTypes.OnView> {
+	isInsideTypeaheadCombobox: boolean;
+	multiSelect: boolean;
+	/** Single-select only: whether the menu opens showing all options (filtering begins on type). */
+	showAllOptionsOnOpen: boolean;
+	/** Null outside of a Root. */
+	comboBoxState: ComboBoxState<WrappedItem<unknown>, SelectionMode> | null;
+	inputProps: InputHTMLAttributes<HTMLInputElement>;
+	/** `AriaListBoxOptions` (input to `useListBox`), not DOM-spreadable. */
+	listBoxProps: AriaListBoxOptions<WrappedItem<unknown>>;
+	buttonProps: AriaButtonProps;
+	inputRef: MutableRefObject<HTMLInputElement | null>;
+	listBoxRef: RefObject<HTMLUListElement>;
+	popoverRef: MutableRefObject<HTMLDivElement | null>;
+	buttonRef: MutableRefObject<HTMLButtonElement | null>;
+	triggerRef: MutableRefObject<HTMLDivElement | null>;
+	/**
+	* PROTOTYPE (DUBOIS-455, "Option A"): opt-in that lets DOM focus genuinely move from the input to
+	* the footer and back, so a real footer <button> is keyboard/SR-reachable. Off by default; the
+	* default combobox keeps the input as the sole tab stop. See the FooterFocusMove debug story.
+	*/
+	footerFocusable: boolean;
+	/** Set by the footer when `footerFocusable` — the popover node holding the footer's controls. */
+	footerRef: MutableRefObject<HTMLDivElement | null>;
+	triggerWidth: number | undefined;
+	setTriggerWidth: (width: number) => void;
+	itemsByKey: Map<Key, unknown>;
+	getKeyForItem: (item: unknown) => Key;
+	itemToString: (item: unknown) => string;
+	removeByKey: (key: Key) => void;
+	clearSelection: () => void;
+}
+export declare const TypeaheadComboboxV2Context: React.Context<TypeaheadComboboxV2ContextType>;
+interface ProviderProps {
+	children: React.ReactNode;
+	value: Omit<TypeaheadComboboxV2ContextType, "triggerWidth" | "setTriggerWidth">;
+}
+export declare const TypeaheadComboboxV2ContextProvider: ({ children, value }: ProviderProps) => JSX.Element;
+export {};