@base-ui/react 1.2.0 → 1.4.0

package/esm/combobox/store.d.ts

@@ -6,6 +6,7 @@ import type { Side } from "../utils/useAnchorPositioning.js";
 import type { AriaCombobox } from "./root/AriaCombobox.js";
 export type State = {
   id: string | undefined;
+  labelId: string | undefined;
   query: string;
   filter: (item: any, query: string) => boolean;
   items: readonly any[] | undefined;
@@ -24,6 +25,7 @@ export type State = {
   listElement: HTMLElement | null;
   triggerElement: HTMLElement | null;
   inputElement: HTMLInputElement | null;
+  inputGroupElement: HTMLDivElement | null;
   popupSide: Side | null;
   openMethod: InteractionType | null;
   inputInsidePopup: boolean;
@@ -33,6 +35,8 @@ export type State = {
   popupRef: React.RefObject<HTMLDivElement | null>;
   emptyRef: React.RefObject<HTMLDivElement | null>;
   inputRef: React.RefObject<HTMLInputElement | null>;
+  startDismissRef: React.RefObject<HTMLSpanElement | null>;
+  endDismissRef: React.RefObject<HTMLSpanElement | null>;
   keyboardActiveRef: React.RefObject<boolean>;
   chipsContainerRef: React.RefObject<HTMLDivElement | null>;
   clearRef: React.RefObject<HTMLButtonElement | null>;
@@ -43,9 +47,9 @@ export type State = {
   setInputValue: (value: string, eventDetails: AriaCombobox.ChangeEventDetails) => void;
   setSelectedValue: (value: any, eventDetails: AriaCombobox.ChangeEventDetails) => void;
   setIndices: (indices: {
-    activeIndex?: (number | null) | undefined;
-    selectedIndex?: (number | null) | undefined;
-    type?: ('keyboard' | 'pointer' | 'none') | undefined;
+    activeIndex?: number | null | undefined;
+    selectedIndex?: number | null | undefined;
+    type?: 'keyboard' | 'pointer' | 'none' | undefined;
   }) => void;
   onItemHighlighted: (item: any, eventDetails: AriaCombobox.HighlightEventDetails) => void;
   forceMount: () => void;
@@ -56,6 +60,7 @@ export type State = {
   }) => Record<string, unknown>;
   requestSubmit: () => void;
   name: string | undefined;
+  form: string | undefined;
   disabled: boolean;
   readOnly: boolean;
   required: boolean;
@@ -74,7 +79,7 @@ export type State = {
 export type ComboboxStore = Store<State>;
 export declare const selectors: {
   id: (state: State) => string | undefined;
-  query: (state: State) => string;
+  labelId: (state: State) => string | undefined;
   items: (state: State) => readonly any[] | undefined;
   selectedValue: (state: State) => any;
   hasSelectionChips: (state: State) => boolean;
@@ -100,32 +105,21 @@ export declare const selectors: {
   listElement: (state: State) => HTMLElement | null;
   triggerElement: (state: State) => HTMLElement | null;
   inputElement: (state: State) => HTMLInputElement | null;
+  inputGroupElement: (state: State) => HTMLDivElement | null;
   popupSide: (state: State) => Side | null;
   openMethod: (state: State) => InteractionType | null;
   inputInsidePopup: (state: State) => boolean;
   selectionMode: (state: State) => "none" | "multiple" | "single";
-  listRef: (state: State) => import("react").RefObject<(HTMLElement | null)[]>;
-  labelsRef: (state: State) => import("react").RefObject<(string | null)[]>;
-  popupRef: (state: State) => import("react").RefObject<HTMLDivElement | null>;
-  emptyRef: (state: State) => import("react").RefObject<HTMLDivElement | null>;
-  inputRef: (state: State) => import("react").RefObject<HTMLInputElement | null>;
-  keyboardActiveRef: (state: State) => import("react").RefObject<boolean>;
-  chipsContainerRef: (state: State) => import("react").RefObject<HTMLDivElement | null>;
-  clearRef: (state: State) => import("react").RefObject<HTMLButtonElement | null>;
-  valuesRef: (state: State) => import("react").RefObject<any[]>;
-  allValuesRef: (state: State) => import("react").RefObject<any[]>;
   name: (state: State) => string | undefined;
+  form: (state: State) => string | undefined;
   disabled: (state: State) => boolean;
   readOnly: (state: State) => boolean;
   required: (state: State) => boolean;
   grid: (state: State) => boolean;
-  isGrouped: (state: State) => boolean;
   virtualized: (state: State) => boolean;
-  onOpenChangeComplete: (state: State) => (open: boolean) => void;
-  openOnInputClick: (state: State) => boolean;
   itemToStringLabel: (state: State) => ((item: any) => string) | undefined;
   isItemEqualToValue: (state: State) => (itemValue: any, selectedValue: any) => boolean;
   modal: (state: State) => boolean;
-  autoHighlight: (state: State) => false | "always" | "input-change";
+  autoHighlight: (state: State) => false | "input-change" | "always";
   submitOnItemClick: (state: State) => boolean;
 };

package/esm/combobox/store.js

@@ -3,7 +3,7 @@ import { compareItemEquality } from "../utils/itemEquality.js";
 import { hasNullItemLabel } from "../utils/resolveValueLabel.js";
 export const selectors = {
   id: createSelector(state => state.id),
-  query: createSelector(state => state.query),
+  labelId: createSelector(state => state.labelId),
   items: createSelector(state => state.items),
   selectedValue: createSelector(state => state.selectedValue),
   hasSelectionChips: createSelector(state => {
@@ -50,29 +50,18 @@ export const selectors = {
   listElement: createSelector(state => state.listElement),
   triggerElement: createSelector(state => state.triggerElement),
   inputElement: createSelector(state => state.inputElement),
+  inputGroupElement: createSelector(state => state.inputGroupElement),
   popupSide: createSelector(state => state.popupSide),
   openMethod: createSelector(state => state.openMethod),
   inputInsidePopup: createSelector(state => state.inputInsidePopup),
   selectionMode: createSelector(state => state.selectionMode),
-  listRef: createSelector(state => state.listRef),
-  labelsRef: createSelector(state => state.labelsRef),
-  popupRef: createSelector(state => state.popupRef),
-  emptyRef: createSelector(state => state.emptyRef),
-  inputRef: createSelector(state => state.inputRef),
-  keyboardActiveRef: createSelector(state => state.keyboardActiveRef),
-  chipsContainerRef: createSelector(state => state.chipsContainerRef),
-  clearRef: createSelector(state => state.clearRef),
-  valuesRef: createSelector(state => state.valuesRef),
-  allValuesRef: createSelector(state => state.allValuesRef),
   name: createSelector(state => state.name),
+  form: createSelector(state => state.form),
   disabled: createSelector(state => state.disabled),
   readOnly: createSelector(state => state.readOnly),
   required: createSelector(state => state.required),
   grid: createSelector(state => state.grid),
-  isGrouped: createSelector(state => state.isGrouped),
   virtualized: createSelector(state => state.virtualized),
-  onOpenChangeComplete: createSelector(state => state.onOpenChangeComplete),
-  openOnInputClick: createSelector(state => state.openOnInputClick),
   itemToStringLabel: createSelector(state => state.itemToStringLabel),
   isItemEqualToValue: createSelector(state => state.isItemEqualToValue),
   modal: createSelector(state => state.modal),

package/esm/combobox/trigger/ComboboxTrigger.d.ts

@@ -1,13 +1,15 @@
 import * as React from 'react';
 import { BaseUIComponentProps, NativeButtonProps } from "../../utils/types.js";
-import type { FieldRoot } from "../../field/root/FieldRoot.js";
+import type { FieldRootState } from "../../field/root/FieldRoot.js";
 import type { Side } from "../../utils/useAnchorPositioning.js";
 /**
  * A button that opens the popup.
  * Renders a `<button>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export declare const ComboboxTrigger: React.ForwardRefExoticComponent<Omit<ComboboxTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
-export interface ComboboxTriggerState extends FieldRoot.State {
+export interface ComboboxTriggerState extends FieldRootState {
   /**
    * Whether the popup is open.
    */
@@ -29,7 +31,7 @@ export interface ComboboxTriggerState extends FieldRoot.State {
    */
   placeholder: boolean;
 }
-export interface ComboboxTriggerProps extends NativeButtonProps, BaseUIComponentProps<'button', ComboboxTrigger.State> {
+export interface ComboboxTriggerProps extends NativeButtonProps, BaseUIComponentProps<'button', ComboboxTriggerState> {
   /**
    * Whether the component should ignore user interaction.
    * @default false

package/esm/combobox/trigger/ComboboxTrigger.js

@@ -18,11 +18,14 @@ import { createChangeEventDetails } from "../../utils/createBaseUIEventDetails.j
 import { REASONS } from "../../utils/reasons.js";
 import { useClick, useTypeahead } from "../../floating-ui-react/index.js";
 import { useLabelableId } from "../../labelable-provider/useLabelableId.js";
+import { resolveAriaLabelledBy } from "../../utils/resolveAriaLabelledBy.js";
 const BOUNDARY_OFFSET = 2;
 
 /**
  * A button that opens the popup.
  * Renders a `<button>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export const ComboboxTrigger = /*#__PURE__*/React.forwardRef(function ComboboxTrigger(componentProps, forwardedRef) {
   const {
@@ -31,6 +34,7 @@ export const ComboboxTrigger = /*#__PURE__*/React.forwardRef(function ComboboxTr
     nativeButton = true,
     disabled: disabledProp = false,
     id: idProp,
+    style,
     ...elementProps
   } = componentProps;
   const {
@@ -42,7 +46,7 @@ export const ComboboxTrigger = /*#__PURE__*/React.forwardRef(function ComboboxTr
     validation
   } = useFieldRootContext();
   const {
-    labelId
+    labelId: fieldLabelId
   } = useLabelableContext();
   const store = useComboboxRootContext();
   const {
@@ -60,6 +64,7 @@ export const ComboboxTrigger = /*#__PURE__*/React.forwardRef(function ComboboxTr
   const triggerElement = useStore(store, selectors.triggerElement);
   const inputInsidePopup = useStore(store, selectors.inputInsidePopup);
   const rootId = useStore(store, selectors.id);
+  const comboboxLabelId = useStore(store, selectors.labelId);
   const open = useStore(store, selectors.open);
   const selectedValue = useStore(store, selectors.selectedValue);
   const activeIndex = useStore(store, selectors.activeIndex);
@@ -75,6 +80,7 @@ export const ComboboxTrigger = /*#__PURE__*/React.forwardRef(function ComboboxTr
     id: inputInsidePopup ? idProp : undefined
   });
   const id = inputInsidePopup ? idProp ?? rootId : idProp;
+  const ariaLabelledBy = resolveAriaLabelledBy(fieldLabelId, comboboxLabelId);
   const currentPointerTypeRef = React.useRef('');
   function trackPointerType(event) {
     currentPointerTypeRef.current = event.pointerType;
@@ -124,7 +130,7 @@ export const ComboboxTrigger = /*#__PURE__*/React.forwardRef(function ComboboxTr
     disabled,
     popupSide,
     listEmpty,
-    placeholder: !hasSelectedValue
+    placeholder: selectionMode === 'none' ? false : !hasSelectedValue
   };
   const setTriggerElement = useStableCallback(element => {
     store.set('triggerElement', element);
@@ -140,7 +146,7 @@ export const ComboboxTrigger = /*#__PURE__*/React.forwardRef(function ComboboxTr
       'aria-haspopup': inputInsidePopup ? 'dialog' : 'listbox',
       'aria-controls': open ? listElement?.id : undefined,
       'aria-required': inputInsidePopup ? required || undefined : undefined,
-      'aria-labelledby': labelId,
+      'aria-labelledby': ariaLabelledBy,
       onPointerDown: trackPointerType,
       onPointerEnter: trackPointerType,
       onFocus() {

package/esm/combobox/utils/ComboboxInternalDismissButton.d.ts

@@ -0,0 +1,5 @@
+import * as React from 'react';
+/**
+ * @internal
+ */
+export declare const ComboboxInternalDismissButton: React.ForwardRefExoticComponent<React.RefAttributes<HTMLSpanElement>>;

package/esm/combobox/utils/ComboboxInternalDismissButton.js

@@ -0,0 +1,38 @@
+'use client';
+
+import * as React from 'react';
+import { useMergedRefs } from '@base-ui/utils/useMergedRefs';
+import { useStableCallback } from '@base-ui/utils/useStableCallback';
+import { visuallyHiddenInput } from '@base-ui/utils/visuallyHidden';
+import { useButton } from "../../use-button/index.js";
+import { createChangeEventDetails } from "../../utils/createBaseUIEventDetails.js";
+import { REASONS } from "../../utils/reasons.js";
+import { useComboboxRootContext } from "../root/ComboboxRootContext.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @internal
+ */
+export const ComboboxInternalDismissButton = /*#__PURE__*/React.forwardRef(function ComboboxInternalDismissButton(_, forwardedRef) {
+  const store = useComboboxRootContext();
+  const {
+    buttonRef,
+    getButtonProps
+  } = useButton({
+    native: false
+  });
+  const mergedRef = useMergedRefs(forwardedRef, buttonRef);
+  const handleDismiss = useStableCallback(event => {
+    store.state.setOpen(false, createChangeEventDetails(REASONS.closePress, event.nativeEvent, event.currentTarget));
+  });
+  const dismissProps = getButtonProps({
+    onClick: handleDismiss
+  });
+  return /*#__PURE__*/_jsx("span", {
+    ref: mergedRef,
+    ...dismissProps,
+    "aria-label": "Dismiss",
+    tabIndex: undefined,
+    style: visuallyHiddenInput
+  });
+});
+if (process.env.NODE_ENV !== "production") ComboboxInternalDismissButton.displayName = "ComboboxInternalDismissButton";

package/esm/combobox/utils/handleInputPress.d.ts

@@ -0,0 +1,5 @@
+import type * as React from 'react';
+import type { ComboboxStore } from "../store.js";
+export declare function handleInputPress(event: React.MouseEvent<HTMLElement> & {
+  baseUIHandlerPrevented?: boolean | undefined;
+}, store: ComboboxStore, disabled: boolean, readOnly: boolean, shouldIgnoreTarget?: ((target: Element | null) => boolean) | undefined): void;

package/esm/combobox/utils/handleInputPress.js

@@ -0,0 +1,22 @@
+import { isElement } from '@floating-ui/utils/dom';
+import { createChangeEventDetails } from "../../utils/createBaseUIEventDetails.js";
+import { REASONS } from "../../utils/reasons.js";
+import { getTarget, isInteractiveElement } from "../../floating-ui-react/utils/element.js";
+export function handleInputPress(event, store, disabled, readOnly, shouldIgnoreTarget) {
+  if (event.baseUIHandlerPrevented || readOnly) {
+    return;
+  }
+  const target = getTarget(event.nativeEvent);
+  const targetElement = isElement(target) ? target : null;
+  if (targetElement !== event.currentTarget && (shouldIgnoreTarget?.(targetElement) || isInteractiveElement(targetElement))) {
+    return;
+  }
+  event.preventDefault();
+  if (disabled) {
+    return;
+  }
+  store.state.inputRef.current?.focus();
+  if (store.state.openOnInputClick) {
+    store.state.setOpen(true, createChangeEventDetails(REASONS.inputPress, event.nativeEvent));
+  }
+}

package/esm/combobox/utils/useInitialLiveRegionTextMutation.d.ts

@@ -0,0 +1,3 @@
+import * as React from 'react';
+export declare const INITIAL_LIVE_REGION_TEXT_MUTATION_RESET_DELAY = 200;
+export declare function useInitialLiveRegionTextMutation<T extends HTMLElement>(): React.RefObject<T | null>;

package/esm/combobox/utils/useInitialLiveRegionTextMutation.js

@@ -0,0 +1,55 @@
+'use client';
+
+import * as React from 'react';
+import { isIOS } from '@base-ui/utils/detectBrowser';
+import { useTimeout } from '@base-ui/utils/useTimeout';
+
+// Word Joiner is invisible and zero-width, so it forces a text mutation without shifting layout.
+const LIVE_REGION_MARKER = '\u2060';
+// Safari VoiceOver needed roughly 200ms to reliably notice the initial polite live-region change.
+export const INITIAL_LIVE_REGION_TEXT_MUTATION_RESET_DELAY = 200;
+function findLastTextNode(root) {
+  const walker = root.ownerDocument.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  let lastTextNode = null;
+  while (walker.nextNode()) {
+    const textNode = walker.currentNode;
+    if (textNode.nodeValue !== '') {
+      lastTextNode = textNode;
+    }
+  }
+  return lastTextNode;
+}
+export function useInitialLiveRegionTextMutation() {
+  const timeout = useTimeout();
+  const rootRef = React.useRef(null);
+
+  // Only the initial mounted announcement needs the marker; later text updates announce naturally.
+  React.useEffect(() => {
+    if (isIOS) {
+      return undefined;
+    }
+    const root = rootRef.current;
+    if (root == null) {
+      return undefined;
+    }
+    const textNode = findLastTextNode(root);
+    if (textNode == null) {
+      return undefined;
+    }
+    const originalValue = textNode.nodeValue ?? '';
+    const markedValue = `${originalValue}${LIVE_REGION_MARKER}`;
+    textNode.nodeValue = markedValue;
+    timeout.start(INITIAL_LIVE_REGION_TEXT_MUTATION_RESET_DELAY, () => {
+      if (textNode.nodeValue === markedValue) {
+        textNode.nodeValue = originalValue;
+      }
+    });
+    return () => {
+      timeout.clear();
+      if (textNode.nodeValue === markedValue) {
+        textNode.nodeValue = originalValue;
+      }
+    };
+  }, [rootRef, timeout]);
+  return rootRef;
+}

package/esm/composite/composite.d.ts

@@ -10,6 +10,8 @@ export declare const ARROW_LEFT = "ArrowLeft";
 export declare const ARROW_RIGHT = "ArrowRight";
 export declare const HOME = "Home";
 export declare const END = "End";
+export declare const PAGE_UP = "PageUp";
+export declare const PAGE_DOWN = "PageDown";
 export declare const HORIZONTAL_KEYS: Set<string>;
 export declare const HORIZONTAL_KEYS_WITH_EXTRA_KEYS: Set<string>;
 export declare const VERTICAL_KEYS: Set<string>;

package/esm/composite/composite.js

@@ -6,6 +6,8 @@ export const ARROW_LEFT = 'ArrowLeft';
 export const ARROW_RIGHT = 'ArrowRight';
 export const HOME = 'Home';
 export const END = 'End';
+export const PAGE_UP = 'PageUp';
+export const PAGE_DOWN = 'PageDown';
 export const HORIZONTAL_KEYS = new Set([ARROW_LEFT, ARROW_RIGHT]);
 export const HORIZONTAL_KEYS_WITH_EXTRA_KEYS = new Set([ARROW_LEFT, ARROW_RIGHT, HOME, END]);
 export const VERTICAL_KEYS = new Set([ARROW_UP, ARROW_DOWN]);

package/esm/composite/item/CompositeItem.d.ts

@@ -5,7 +5,8 @@ import { StateAttributesMapping } from "../../utils/getStateAttributesProps.js";
  * @internal
  */
 export declare function CompositeItem<Metadata, State extends Record<string, any>>(componentProps: CompositeItem.Props<Metadata, State>): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
-export interface CompositeItemProps<Metadata, State extends Record<string, any>> extends Pick<BaseUIComponentProps<any, State>, 'render' | 'className'> {
+export interface CompositeItemState {}
+export interface CompositeItemProps<Metadata, State extends Record<string, any>> extends Pick<BaseUIComponentProps<any, State>, 'render' | 'className' | 'style'> {
   children?: React.ReactNode;
   metadata?: Metadata | undefined;
   refs?: React.Ref<HTMLElement | null>[] | undefined;
@@ -15,5 +16,6 @@ export interface CompositeItemProps<Metadata, State extends Record<string, any>>
   tag?: keyof React.JSX.IntrinsicElements | undefined;
 }
 export declare namespace CompositeItem {
-  type Props<Metadata, State extends Record<string, any>> = CompositeItemProps<Metadata, State>;
+  type State = CompositeItemState;
+  type Props<Metadata, TState extends Record<string, any>> = CompositeItemProps<Metadata, TState>;
 }

package/esm/composite/item/CompositeItem.js

@@ -10,6 +10,7 @@ export function CompositeItem(componentProps) {
   const {
     render,
     className,
+    style,
     state = EMPTY_OBJECT,
     props = EMPTY_ARRAY,
     refs = EMPTY_ARRAY,

package/esm/composite/list/CompositeList.d.ts

@@ -1,12 +1,13 @@
 import * as React from 'react';
 export type CompositeMetadata<CustomMetadata> = {
-  index?: (number | null) | undefined;
+  index?: number | null | undefined;
 } & CustomMetadata;
 /**
  * Provides context for a list of items in a composite component.
  * @internal
  */
 export declare function CompositeList<Metadata>(props: CompositeList.Props<Metadata>): import("react/jsx-runtime").JSX.Element;
+export interface CompositeListState {}
 export interface CompositeListProps<Metadata> {
   children: React.ReactNode;
   /**
@@ -22,5 +23,6 @@ export interface CompositeListProps<Metadata> {
   onMapChange?: ((newMap: Map<Element, CompositeMetadata<Metadata> | null>) => void) | undefined;
 }
 export declare namespace CompositeList {
+  type State = CompositeListState;
   type Props<Metadata> = CompositeListProps<Metadata>;
 }

package/esm/composite/list/useCompositeListItem.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 export interface UseCompositeListItemParameters<Metadata> {
   index?: number | undefined;
-  label?: (string | null) | undefined;
+  label?: string | null | undefined;
   metadata?: Metadata | undefined;
   textRef?: React.RefObject<HTMLElement | null> | undefined;
   /** Enables guessing the indexes. This avoids a re-render after mount, which is useful for

package/esm/composite/root/CompositeRoot.d.ts

@@ -1,27 +1,30 @@
 import * as React from 'react';
 import { type CompositeMetadata } from "../list/CompositeList.js";
-import type { BaseUIComponentProps } from "../../utils/types.js";
+import type { BaseUIComponentProps, BaseUIEvent } from "../../utils/types.js";
 import type { Dimensions, ModifierKey } from "../composite.js";
 import { StateAttributesMapping } from "../../utils/getStateAttributesProps.js";
 /**
  * @internal
  */
 export declare function CompositeRoot<Metadata extends {}, State extends Record<string, any>>(componentProps: CompositeRoot.Props<Metadata, State>): import("react/jsx-runtime").JSX.Element;
-export interface CompositeRootProps<Metadata, State extends Record<string, any>> extends Pick<BaseUIComponentProps<'div', State>, 'render' | 'className' | 'children'> {
+export interface CompositeRootState {}
+export interface CompositeRootProps<Metadata, State extends Record<string, any>> extends Pick<BaseUIComponentProps<'div', State>, 'render' | 'className' | 'children' | 'style'> {
   props?: Array<Record<string, any> | (() => Record<string, any>)> | undefined;
   state?: State | undefined;
   stateAttributesMapping?: StateAttributesMapping<State> | undefined;
   refs?: React.Ref<HTMLElement | null>[] | undefined;
   tag?: keyof React.JSX.IntrinsicElements | undefined;
-  orientation?: ('horizontal' | 'vertical' | 'both') | undefined;
+  orientation?: 'horizontal' | 'vertical' | 'both' | undefined;
   cols?: number | undefined;
   loopFocus?: boolean | undefined;
+  onLoop?: ((event: React.KeyboardEvent, prevIndex: number, nextIndex: number, elementsRef: React.RefObject<(HTMLDivElement | null)[]>) => number) | undefined;
   highlightedIndex?: number | undefined;
   onHighlightedIndexChange?: ((index: number) => void) | undefined;
   itemSizes?: Dimensions[] | undefined;
   dense?: boolean | undefined;
   enableHomeAndEndKeys?: boolean | undefined;
   onMapChange?: ((newMap: Map<Node, CompositeMetadata<Metadata> | null>) => void) | undefined;
+  onKeyDown?: ((event: BaseUIEvent<React.KeyboardEvent>) => void) | undefined;
   stopEventPropagation?: boolean | undefined;
   rootRef?: React.RefObject<HTMLElement | null> | undefined;
   disabledIndices?: number[] | undefined;
@@ -29,5 +32,6 @@ export interface CompositeRootProps<Metadata, State extends Record<string, any>>
   highlightItemOnHover?: boolean | undefined;
 }
 export declare namespace CompositeRoot {
-  type Props<Metadata, State extends Record<string, any>> = CompositeRootProps<Metadata, State>;
+  type State = CompositeRootState;
+  type Props<Metadata, TState extends Record<string, any>> = CompositeRootProps<Metadata, TState>;
 }

package/esm/composite/root/CompositeRoot.js

@@ -15,6 +15,7 @@ export function CompositeRoot(componentProps) {
   const {
     render,
     className,
+    style,
     refs = EMPTY_ARRAY,
     props = EMPTY_ARRAY,
     state = EMPTY_OBJECT,
@@ -25,6 +26,7 @@ export function CompositeRoot(componentProps) {
     dense,
     itemSizes,
     loopFocus,
+    onLoop,
     cols,
     enableHomeAndEndKeys,
     onMapChange: onMapChangeProp,
@@ -48,6 +50,7 @@ export function CompositeRoot(componentProps) {
     itemSizes,
     cols,
     loopFocus,
+    onLoop,
     dense,
     orientation,
     highlightedIndex: highlightedIndexProp,

package/esm/composite/root/useCompositeRoot.d.ts

@@ -4,9 +4,10 @@ import { type Dimensions, type ModifierKey } from "../composite.js";
 import { CompositeMetadata } from "../list/CompositeList.js";
 import { HTMLProps } from "../../utils/types.js";
 export interface UseCompositeRootParameters {
-  orientation?: ('horizontal' | 'vertical' | 'both') | undefined;
+  orientation?: 'horizontal' | 'vertical' | 'both' | undefined;
   cols?: number | undefined;
   loopFocus?: boolean | undefined;
+  onLoop?: ((event: React.KeyboardEvent, prevIndex: number, nextIndex: number, elementsRef: React.RefObject<(HTMLDivElement | null)[]>) => number) | undefined;
   highlightedIndex?: number | undefined;
   onHighlightedIndexChange?: ((index: number) => void) | undefined;
   dense?: boolean | undefined;

package/esm/composite/root/useCompositeRoot.js

@@ -6,12 +6,14 @@ import { useStableCallback } from '@base-ui/utils/useStableCallback';
 import { useMergedRefs } from '@base-ui/utils/useMergedRefs';
 import { ALL_KEYS, ARROW_DOWN, ARROW_KEYS, ARROW_LEFT, ARROW_RIGHT, ARROW_UP, END, HOME, HORIZONTAL_KEYS, HORIZONTAL_KEYS_WITH_EXTRA_KEYS, MODIFIER_KEYS, VERTICAL_KEYS, VERTICAL_KEYS_WITH_EXTRA_KEYS, createGridCellMap, findNonDisabledListIndex, getGridCellIndexOfCorner, getGridCellIndices, getGridNavigatedIndex, getMaxListIndex, getMinListIndex, isListIndexDisabled, isIndexOutOfListBounds, isNativeInput, scrollIntoViewIfNeeded } from "../composite.js";
 import { ACTIVE_COMPOSITE_ITEM } from "../constants.js";
+import { getTarget } from "../../floating-ui-react/utils.js";
 const EMPTY_ARRAY = [];
 export function useCompositeRoot(params) {
   const {
     itemSizes,
     cols = 1,
     loopFocus = true,
+    onLoop,
     dense = false,
     orientation = 'both',
     direction,
@@ -51,15 +53,22 @@ export function useCompositeRoot(params) {
     }
     scrollIntoViewIfNeeded(rootRef.current, activeItem, direction, orientation);
   });
+  const wrappedOnLoop = useStableCallback((event, prevIndex, nextIndex) => {
+    if (!onLoop) {
+      return nextIndex;
+    }
+    return onLoop?.(event, prevIndex, nextIndex, elementsRef);
+  });
   const props = React.useMemo(() => ({
     'aria-orientation': orientation === 'both' ? undefined : orientation,
     ref: mergedRef,
     onFocus(event) {
       const element = rootRef.current;
-      if (!element || !isNativeInput(event.target)) {
+      const target = getTarget(event.nativeEvent);
+      if (!element || target == null || !isNativeInput(target)) {
         return;
       }
-      event.target.setSelectionRange(0, event.target.value.length ?? 0);
+      target.setSelectionRange(0, target.value.length ?? 0);
     },
     onKeyDown(event) {
       const RELEVANT_KEYS = enableHomeAndEndKeys ? ALL_KEYS : ARROW_KEYS;
@@ -86,10 +95,11 @@ export function useCompositeRoot(params) {
         vertical: ARROW_UP,
         both: horizontalBackwardKey
       }[orientation];
-      if (isNativeInput(event.target) && !isElementDisabled(event.target)) {
-        const selectionStart = event.target.selectionStart;
-        const selectionEnd = event.target.selectionEnd;
-        const textContent = event.target.value ?? '';
+      const target = getTarget(event.nativeEvent);
+      if (target != null && isNativeInput(target) && !isElementDisabled(target)) {
+        const selectionStart = target.selectionStart;
+        const selectionEnd = target.selectionEnd;
+        const textContent = target.value ?? '';
         // return to native textbox behavior when
         // 1 - Shift is held to make a text selection, or if there already is a text selection
         if (selectionStart == null || event.shiftKey || selectionStart !== selectionEnd) {
@@ -117,19 +127,18 @@ export function useCompositeRoot(params) {
         // To calculate movements on the grid, we use hypothetical cell indices
         // as if every item was 1x1, then convert back to real indices.
         const cellMap = createGridCellMap(sizes, cols, dense);
-        const minGridIndex = cellMap.findIndex(index => index != null && !isListIndexDisabled(elementsRef, index, disabledIndices));
+        const minGridIndex = cellMap.findIndex(index => index != null && !isListIndexDisabled(elementsRef.current, index, disabledIndices));
         // last enabled index
-        const maxGridIndex = cellMap.reduce((foundIndex, index, cellIndex) => index != null && !isListIndexDisabled(elementsRef, index, disabledIndices) ? cellIndex : foundIndex, -1);
-        nextIndex = cellMap[getGridNavigatedIndex({
-          current: cellMap.map(itemIndex => itemIndex ? elementsRef.current[itemIndex] : null)
-        }, {
+        const maxGridIndex = cellMap.reduce((foundIndex, index, cellIndex) => index != null && !isListIndexDisabled(elementsRef.current, index, disabledIndices) ? cellIndex : foundIndex, -1);
+        nextIndex = cellMap[getGridNavigatedIndex(cellMap.map(itemIndex => itemIndex != null ? elementsRef.current[itemIndex] : null), {
           event,
           orientation,
           loopFocus,
+          onLoop: wrappedOnLoop,
           cols,
           // treat undefined (empty grid spaces) as disabled indices so we
           // don't end up in them
-          disabledIndices: getGridCellIndices([...(disabledIndices || elementsRef.current.map((_, index) => isListIndexDisabled(elementsRef, index) ? index : undefined)), undefined], cellMap),
+          disabledIndices: getGridCellIndices([...(disabledIndices || elementsRef.current.map((_, index) => isListIndexDisabled(elementsRef.current, index) ? index : undefined)), undefined], cellMap),
           minIndex: minGridIndex,
           maxIndex: maxGridIndex,
           prevIndex: getGridCellIndexOfCorner(highlightedIndex > maxIndex ? minIndex : highlightedIndex, sizes, cellMap, cols,
@@ -166,17 +175,23 @@ export function useCompositeRoot(params) {
       if (nextIndex === highlightedIndex && (forwardKeys.includes(event.key) || backwardKeys.includes(event.key))) {
         if (loopFocus && nextIndex === maxIndex && forwardKeys.includes(event.key)) {
           nextIndex = minIndex;
+          if (onLoop) {
+            nextIndex = onLoop(event, highlightedIndex, nextIndex, elementsRef);
+          }
         } else if (loopFocus && nextIndex === minIndex && backwardKeys.includes(event.key)) {
           nextIndex = maxIndex;
+          if (onLoop) {
+            nextIndex = onLoop(event, highlightedIndex, nextIndex, elementsRef);
+          }
         } else {
-          nextIndex = findNonDisabledListIndex(elementsRef, {
+          nextIndex = findNonDisabledListIndex(elementsRef.current, {
             startingIndex: nextIndex,
             decrement: backwardKeys.includes(event.key),
             disabledIndices
           });
         }
       }
-      if (nextIndex !== highlightedIndex && !isIndexOutOfListBounds(elementsRef, nextIndex)) {
+      if (nextIndex !== highlightedIndex && !isIndexOutOfListBounds(elementsRef.current, nextIndex)) {
         if (stopEventPropagation) {
           event.stopPropagation();
         }
@@ -191,7 +206,7 @@ export function useCompositeRoot(params) {
         });
       }
     }
-  }), [cols, dense, direction, disabledIndices, elementsRef, enableHomeAndEndKeys, highlightedIndex, isGrid, itemSizes, loopFocus, mergedRef, modifierKeys, onHighlightedIndexChange, orientation, stopEventPropagation]);
+  }), [cols, dense, direction, disabledIndices, elementsRef, enableHomeAndEndKeys, highlightedIndex, isGrid, itemSizes, loopFocus, onLoop, wrappedOnLoop, mergedRef, modifierKeys, onHighlightedIndexChange, orientation, stopEventPropagation]);
   return React.useMemo(() => ({
     props,
     highlightedIndex,

package/esm/context-menu/index.d.ts

@@ -2,7 +2,7 @@ export * as ContextMenu from "./index.parts.js";
 export type * from "./root/ContextMenuRoot.js";
 export type * from "./trigger/ContextMenuTrigger.js";
 export type { MenuBackdropProps as ContextMenuBackdropProps, MenuBackdropState as ContextMenuBackdropState } from "../menu/backdrop/MenuBackdrop.js";
-export type { MenuPortalProps as ContextMenuPortalProps } from "../menu/portal/MenuPortal.js";
+export type { MenuPortalProps as ContextMenuPortalProps, MenuPortalState as ContextMenuPortalState } from "../menu/portal/MenuPortal.js";
 export type { MenuPositionerProps as ContextMenuPositionerProps, MenuPositionerState as ContextMenuPositionerState } from "../menu/positioner/MenuPositioner.js";
 export type { MenuPopupProps as ContextMenuPopupProps, MenuPopupState as ContextMenuPopupState } from "../menu/popup/MenuPopup.js";
 export type { MenuArrowProps as ContextMenuArrowProps, MenuArrowState as ContextMenuArrowState } from "../menu/arrow/MenuArrow.js";