[combobox] Simplify keyed value mode bookkeeping

Author: atomiks

docs/src/app/(docs)/react/components/page.mdx

@@ -14,7 +14,7 @@
 
 ## Styling
 
-A guide to styling Base UI components with your preferred styling engine.
+Learn how to style Base UI components with your preferred styling engine.
 
 <details>
 

docs/src/app/(docs)/react/handbook/page.mdx

@@ -70,7 +70,7 @@ Changelogs for each Base UI release.
 
 ## About Base UI
 
-An open-source React component library for building accessible user interfaces.
+An overview of Base UI, providing information on its history, team, and goals.
 
 <details>
 

docs/src/app/(docs)/react/overview/page.mdx

@@ -12,7 +12,7 @@
 
 ## CSP Provider
 
-Configures CSP-related behavior for inline tags rendered by Base UI components.
+A CSP provider component that applies a nonce to inline  and  tags rendered by Base UI components, and can disable inline  elements.
 
 <details>
 
@@ -28,15 +28,14 @@ Configures CSP-related behavior for inline tags rendered by Base UI components.
 - Exports:
   - CSPProvider
     - Props: children, disableStyleElements, nonce
-- Types: CSPProvider.Props, CSPProvider.State
 
 </details>
 
 [Read more](./csp-provider/page.mdx)
 
 ## Direction Provider
 
-Enables RTL behavior for Base UI components.
+A direction provider component that enables RTL behavior for Base UI components.
 
 <details>
 
@@ -52,15 +51,14 @@ Enables RTL behavior for Base UI components.
   - DirectionProvider
     - Props: children, direction
   - useDirection
-- Types: DirectionProvider.Props, DirectionProvider.State, TextDirection
 
 </details>
 
 [Read more](./direction-provider/page.mdx)
 
 ## mergeProps
 
-A utility to merge multiple sets of React props.
+A utility to merge multiple sets of React props, handling event handlers, className, and style props intelligently.
 
 <details>
 
@@ -75,13 +73,9 @@ A utility to merge multiple sets of React props.
     - mergePropsN
 - Exports:
   - makeEventPreventable
-    - Parameters: event
   - mergeClassNames
-    - Parameters: ourClassName, theirClassName
   - mergeProps
-    - Parameters: a, b, c, d, e
   - mergePropsN
-    - Parameters: props
 
 </details>
 
@@ -107,16 +101,14 @@ Hook for enabling a render prop in custom components.
 - Exports:
   - ComponentRenderFn
   - useRender
-    - Parameters: params
-- Types: HTMLProps, UseRenderComponentProps, UseRenderElementProps, UseRenderParameters, UseRenderRenderProp, UseRenderReturnValue, UseRenderState, useRender.ComponentProps, useRender.ElementProps, useRender.Parameters, useRender.RenderProp, useRender.ReturnValue, useRender.State
 
 </details>
 
 [Read more](./use-render/page.mdx)
 
 ## Localization Provider
 
-Defines the locale to use in the temporal components.
+A localization provider component that defines the locale to use in the temporal components.
 
 <details>
 
@@ -133,7 +125,6 @@ Defines the locale to use in the temporal components.
   - LocalizationProvider
     - Props: children, temporalLocale
   - useTemporalLocale
-- Types: LocalizationProvider.Props
 
 </details>
 

docs/src/app/(docs)/react/utils/page.mdx

@@ -46,6 +46,8 @@ import { HTMLProps } from '../../utils/types';
 import { useValueChanged } from '../../utils/useValueChanged';
 import { NOOP } from '../../utils/noop';
 import {
+  hasEmptySelectionValue,
+  hasPrimitiveSelectionValue,
   inferItemValue,
   hasValueAndLabelItemsInput,
   mapItemValues,
@@ -64,24 +66,6 @@ import {
 } from '../../utils/itemEquality';
 import { INITIAL_LAST_HIGHLIGHT, NO_ACTIVE_VALUE } from './utils/constants';
 
-function hasPrimitiveSelectionValue(value: any, multiple: boolean): boolean {
-  if (multiple) {
-    return (
-      Array.isArray(value) && value.length > 0 && value.every((item) => typeof item !== 'object')
-    );
-  }
-
-  return value != null && typeof value !== 'object';
-}
-
-function hasEmptySelectionValue(value: any, multiple: boolean): boolean {
-  if (multiple) {
-    return Array.isArray(value) && value.length === 0;
-  }
-
-  return value == null;
-}
-
 /**
  * @internal
  */
@@ -205,19 +189,20 @@ export function AriaCombobox<Value = any, Mode extends SelectionMode = 'none'>(
     name: 'Combobox',
     state: 'selectedValue',
   });
+
   const hasPrimitiveSelectableItems =
     hasItems && selectionMode !== 'none' && hasValueAndLabelItemsInput(items);
   const hasEmptySelection = hasEmptySelectionValue(selectedValue, multiple);
-  const shouldUsePrimitiveValuesForItems =
+  const usePrimitiveValuesForItems =
     hasPrimitiveSelectableItems && hasPrimitiveSelectionValue(selectedValue, multiple);
-  const shouldBypassItemToStringLabelForItems =
-    hasPrimitiveSelectableItems && (shouldUsePrimitiveValuesForItems || hasEmptySelection);
-  const shouldSkipPreMountItemRegistry =
-    hasPrimitiveSelectableItems && !shouldUsePrimitiveValuesForItems && hasEmptySelection;
-  const itemToStringLabelForItems = shouldBypassItemToStringLabelForItems
+  const disableItemToStringLabelForItems =
+    hasPrimitiveSelectableItems && (usePrimitiveValuesForItems || hasEmptySelection);
+  const skipPreMountItemRegistry =
+    hasPrimitiveSelectableItems && !usePrimitiveValuesForItems && hasEmptySelection;
+  const itemToStringLabelForItems = disableItemToStringLabelForItems
     ? undefined
     : itemToStringLabel;
-  const getVisibleItemValue = shouldUsePrimitiveValuesForItems ? inferItemValue : undefined;
+  const getVisibleItemValue = usePrimitiveValuesForItems ? inferItemValue : undefined;
 
   const filter = React.useMemo(() => {
     if (filterProp === null) {
@@ -500,7 +485,7 @@ export function AriaCombobox<Value = any, Mode extends SelectionMode = 'none'>(
 
   const forceMount = useStableCallback(() => {
     if (items) {
-      if (shouldSkipPreMountItemRegistry) {
+      if (skipPreMountItemRegistry) {
         labelsRef.current = [];
         valuesRef.current = [];
         return;
@@ -868,22 +853,15 @@ export function AriaCombobox<Value = any, Mode extends SelectionMode = 'none'>(
   useIsoLayoutEffect(() => {
     if (items) {
       if (!open && !inlineProp) {
-        if (shouldSkipPreMountItemRegistry) {
+        if (skipPreMountItemRegistry) {
           valuesRef.current = [];
         } else {
           valuesRef.current = mapItemValues(flatFilteredItems, getVisibleItemValue);
         }
       }
       listRef.current.length = flatFilteredItems.length;
     }
-  }, [
-    items,
-    flatFilteredItems,
-    inlineProp,
-    open,
-    getVisibleItemValue,
-    shouldSkipPreMountItemRegistry,
-  ]);
+  }, [items, flatFilteredItems, inlineProp, open, getVisibleItemValue, skipPreMountItemRegistry]);
 
   useIsoLayoutEffect(() => {
     const pendingHighlight = pendingQueryHighlightRef.current;

packages/react/src/combobox/root/AriaCombobox.tsx

@@ -112,6 +112,24 @@ export function inferItemValue(item: any) {
   return item;
 }
 
+export function hasPrimitiveSelectionValue(value: any, multiple: boolean): boolean {
+  if (multiple) {
+    return (
+      Array.isArray(value) && value.length > 0 && value.every((item) => typeof item !== 'object')
+    );
+  }
+
+  return value != null && typeof value !== 'object';
+}
+
+export function hasEmptySelectionValue(value: any, multiple: boolean): boolean {
+  if (multiple) {
+    return Array.isArray(value) && value.length === 0;
+  }
+
+  return value == null;
+}
+
 export function mapItemValues(
   items: readonly any[],
   getItemValue?: ((item: any) => any) | undefined,