From 18f7e1cd18e0a4ace0096cf226fbbe3acc98cde5 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 22 Oct 2024 14:47:37 +0800
Subject: [PATCH 01/20] Move useContext call from hooks to components

---
 packages/react/src/Tabs/Tab/Tab.tsx         | 24 ++++++++++++++-------
 packages/react/src/Tabs/Tab/useTab.test.tsx | 12 +++++++++--
 packages/react/src/Tabs/Tab/useTab.ts       | 22 ++++++++++---------
 3 files changed, 38 insertions(+), 20 deletions(-)

diff --git a/packages/react/src/Tabs/Tab/Tab.tsx b/packages/react/src/Tabs/Tab/Tab.tsx
index d6c007657b..8b217b7807 100644
--- a/packages/react/src/Tabs/Tab/Tab.tsx
+++ b/packages/react/src/Tabs/Tab/Tab.tsx
@@ -4,7 +4,8 @@ import PropTypes from 'prop-types';
 import { useTab } from './useTab';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import type { BaseUIComponentProps } from '../../utils/types';
-import { TabsOrientation } from '../Root/TabsRoot';
+import type { TabsOrientation } from '../Root/TabsRoot';
+import { useTabsRootContext } from '../Root/TabsRootContext';
 
 /**
  *
@@ -20,18 +21,25 @@ const Tab = React.forwardRef(function Tab(
   props: Tab.Props,
   forwardedRef: React.ForwardedRef<Element>,
 ) {
-  const { className, disabled = false, render, value, ...other } = props;
+  const { className, disabled = false, render, value: valueProp, ...other } = props;
 
-  const { selected, getRootProps, orientation } = useTab({
+  const { value: selectedValue, getTabPanelId, orientation } = useTabsRootContext();
+
+  const { selected, getRootProps } = useTab({
     ...props,
+    getTabPanelId,
+    isSelected: valueProp === selectedValue,
     rootRef: forwardedRef,
   });
 
-  const ownerState: Tab.OwnerState = {
-    disabled,
-    selected,
-    orientation,
-  };
+  const ownerState: Tab.OwnerState = React.useMemo(
+    () => ({
+      disabled,
+      selected,
+      orientation,
+    }),
+    [disabled, selected, orientation],
+  );
 
   const { renderElement } = useComponentRenderer({
     propGetter: getRootProps,
diff --git a/packages/react/src/Tabs/Tab/useTab.test.tsx b/packages/react/src/Tabs/Tab/useTab.test.tsx
index 13feef62a9..9f817177a1 100644
--- a/packages/react/src/Tabs/Tab/useTab.test.tsx
+++ b/packages/react/src/Tabs/Tab/useTab.test.tsx
@@ -12,7 +12,11 @@ describe('useTab', () => {
     it('returns props for root slot', () => {
       function TestTab() {
         const rootRef = React.createRef<HTMLDivElement>();
-        const { getRootProps } = useTab({ rootRef });
+        const { getRootProps } = useTab({
+          rootRef,
+          isSelected: true,
+          getTabPanelId: () => undefined,
+        });
         return <button {...getRootProps()} />;
       }
 
@@ -37,7 +41,11 @@ describe('useTab', () => {
 
       function TestTab() {
         const rootRef = React.createRef<HTMLDivElement>();
-        const { getRootProps } = useTab({ rootRef });
+        const { getRootProps } = useTab({
+          rootRef,
+          isSelected: true,
+          getTabPanelId: () => undefined,
+        });
         return (
           <button
             {...getRootProps({
diff --git a/packages/react/src/Tabs/Tab/useTab.ts b/packages/react/src/Tabs/Tab/useTab.ts
index 204ba177c2..3fec1f4570 100644
--- a/packages/react/src/Tabs/Tab/useTab.ts
+++ b/packages/react/src/Tabs/Tab/useTab.ts
@@ -1,6 +1,6 @@
 'use client';
 import * as React from 'react';
-import { useTabsRootContext } from '../Root/TabsRootContext';
+import type { TabsRootContext } from '../Root/TabsRootContext';
 import { TabMetadata } from '../Root/useTabsRoot';
 import { useCompoundItem } from '../../useCompound';
 import { useListItem } from '../../useList';
@@ -8,20 +8,24 @@ import { useButton } from '../../useButton';
 import { useId } from '../../utils/useId';
 import { useForkRef } from '../../utils/useForkRef';
 import { mergeReactProps } from '../../utils/mergeReactProps';
-import { TabsOrientation } from '../Root/TabsRoot';
 
 function tabValueGenerator(otherTabValues: Set<any>) {
   return otherTabValues.size;
 }
 
 function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
-  const { value: valueParam, rootRef: externalRef, disabled = false, id: idParam } = parameters;
+  const {
+    value: valueParam,
+    rootRef: externalRef,
+    disabled = false,
+    getTabPanelId,
+    id: idParam,
+    isSelected,
+  } = parameters;
 
   const tabRef = React.useRef<HTMLElement>(null);
   const id = useId(idParam);
 
-  const { value: selectedValue, getTabPanelId, orientation } = useTabsRootContext();
-
   const tabMetadata = React.useMemo(() => ({ disabled, ref: tabRef, id }), [disabled, tabRef, id]);
 
   const {
@@ -46,7 +50,6 @@ function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
 
   const getRootProps = React.useCallback(
     (externalProps = {}) => {
-      //
       return mergeReactProps<'button'>(
         externalProps,
         mergeReactProps<'button'>(
@@ -70,14 +73,13 @@ function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
     rootRef: handleRef,
     // the `selected` state isn't set on the server (it relies on effects to be calculated),
     // so we fall back to checking the `value` prop with the selectedValue from the TabsContext
-    selected: selected || value === selectedValue,
+    selected: selected || isSelected,
     totalTabsCount,
-    orientation,
   };
 }
 
 namespace useTab {
-  export interface Parameters {
+  export interface Parameters extends Pick<TabsRootContext, 'getTabPanelId'> {
     /**
      * The value of the tab.
      * It's used to associate the tab with a tab panel(s) with the same value.
@@ -97,6 +99,7 @@ namespace useTab {
      * If not provided, it will be automatically generated.
      */
     id?: string;
+    isSelected: boolean;
     /**
      * Ref to the root slot's DOM element.
      */
@@ -116,7 +119,6 @@ namespace useTab {
      * 0-based index of the tab in the list of tabs.
      */
     index: number;
-    orientation: TabsOrientation;
     /**
      * Ref to the root slot's DOM element.
      */

From f7941fe17c0789a98b4d1322c794a06ef28066a1 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 22 Oct 2024 15:58:27 +0800
Subject: [PATCH 02/20] TabsList

---
 packages/react/src/Tabs/TabsList/TabsList.tsx | 26 ++++++++++----
 .../src/Tabs/TabsList/useTabsList.test.tsx    | 23 ++++++++++--
 .../react/src/Tabs/TabsList/useTabsList.ts    | 35 +++++++------------
 3 files changed, 54 insertions(+), 30 deletions(-)

diff --git a/packages/react/src/Tabs/TabsList/TabsList.tsx b/packages/react/src/Tabs/TabsList/TabsList.tsx
index 87943fab52..3decca92a8 100644
--- a/packages/react/src/Tabs/TabsList/TabsList.tsx
+++ b/packages/react/src/Tabs/TabsList/TabsList.tsx
@@ -4,6 +4,7 @@ import PropTypes from 'prop-types';
 import { useTabsList } from './useTabsList';
 import { TabsListProvider } from './TabsListProvider';
 import { tabsStyleHookMapping } from '../Root/styleHooks';
+import { useTabsRootContext } from '../Root/TabsRootContext';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import { TabsRoot } from '../Root/TabsRoot';
 import { BaseUIComponentProps } from '../../utils/types';
@@ -24,12 +25,25 @@ const TabsList = React.forwardRef(function TabsList(
 ) {
   const { activateOnFocus = true, className, loop = true, render, ...other } = props;
 
-  const { direction, orientation, getRootProps, contextValue, tabActivationDirection } =
-    useTabsList({
-      rootRef: forwardedRef,
-      loop,
-      activateOnFocus,
-    });
+  const {
+    direction = 'ltr',
+    onSelected,
+    orientation = 'horizontal',
+    value,
+    registerTabIdLookup,
+    tabActivationDirection,
+  } = useTabsRootContext();
+
+  const { getRootProps, contextValue } = useTabsList({
+    activateOnFocus,
+    direction,
+    loop,
+    onSelected,
+    orientation,
+    registerTabIdLookup,
+    rootRef: forwardedRef,
+    value,
+  });
 
   const ownerState: TabsList.OwnerState = React.useMemo(
     () => ({
diff --git a/packages/react/src/Tabs/TabsList/useTabsList.test.tsx b/packages/react/src/Tabs/TabsList/useTabsList.test.tsx
index 5f808d8fbc..46e3e469d7 100644
--- a/packages/react/src/Tabs/TabsList/useTabsList.test.tsx
+++ b/packages/react/src/Tabs/TabsList/useTabsList.test.tsx
@@ -3,6 +3,7 @@ import { expect } from 'chai';
 import { spy } from 'sinon';
 import { createRenderer, screen, fireEvent } from '@mui/internal-test-utils';
 import { Tabs } from '@base-ui-components/react/Tabs';
+import { NOOP } from '../../utils/noop';
 import { useTabsList } from './useTabsList';
 
 describe('useTabsList', () => {
@@ -12,7 +13,16 @@ describe('useTabsList', () => {
     it('returns props for root slot', () => {
       function TestTabsList() {
         const rootRef = React.createRef<HTMLDivElement>();
-        const { getRootProps } = useTabsList({ rootRef, activateOnFocus: true, loop: true });
+        const { getRootProps } = useTabsList({
+          activateOnFocus: true,
+          direction: 'ltr',
+          loop: true,
+          onSelected: NOOP,
+          orientation: 'horizontal',
+          registerTabIdLookup: NOOP,
+          rootRef,
+          value: 0,
+        });
         return <div {...getRootProps()} />;
       }
 
@@ -35,7 +45,16 @@ describe('useTabsList', () => {
 
       function TestTabsList() {
         const rootRef = React.createRef<HTMLDivElement>();
-        const { getRootProps } = useTabsList({ rootRef, activateOnFocus: true, loop: true });
+        const { getRootProps } = useTabsList({
+          activateOnFocus: true,
+          direction: 'ltr',
+          loop: true,
+          onSelected: NOOP,
+          orientation: 'horizontal',
+          registerTabIdLookup: NOOP,
+          rootRef,
+          value: 0,
+        });
         return (
           <div
             {...getRootProps({
diff --git a/packages/react/src/Tabs/TabsList/useTabsList.ts b/packages/react/src/Tabs/TabsList/useTabsList.ts
index 846b111d5a..3845e5883c 100644
--- a/packages/react/src/Tabs/TabsList/useTabsList.ts
+++ b/packages/react/src/Tabs/TabsList/useTabsList.ts
@@ -1,7 +1,7 @@
 'use client';
 import * as React from 'react';
 import { TabsListActionTypes, tabsListReducer, ValueChangeAction } from './tabsListReducer';
-import { useTabsRootContext } from '../Root/TabsRootContext';
+import type { TabsRootContext } from '../Root/TabsRootContext';
 import { type TabMetadata } from '../Root/useTabsRoot';
 import { type TabsOrientation, type TabActivationDirection } from '../Root/TabsRoot';
 import { useCompoundParent } from '../../useCompound';
@@ -9,20 +9,19 @@ import { useList, ListState, UseListParameters, ListAction } from '../../useList
 import { useForkRef } from '../../utils/useForkRef';
 import { mergeReactProps } from '../../utils/mergeReactProps';
 import { useEnhancedEffect } from '../../utils/useEnhancedEffect';
-import { TabsDirection } from '../Root/TabsRoot';
 import { TabsListProviderValue } from './TabsListProvider';
 
 function useTabsList(parameters: useTabsList.Parameters): useTabsList.ReturnValue {
-  const { rootRef: externalRef, loop, activateOnFocus } = parameters;
-
   const {
-    direction = 'ltr',
+    activateOnFocus,
+    direction,
+    loop,
     onSelected,
-    orientation = 'horizontal',
-    value,
+    orientation,
     registerTabIdLookup,
-    tabActivationDirection,
-  } = useTabsRootContext();
+    rootRef: externalRef,
+    value,
+  } = parameters;
 
   const { subitems, contextValue: compoundComponentContextValue } = useCompoundParent<
     any,
@@ -169,11 +168,8 @@ function useTabsList(parameters: useTabsList.Parameters): useTabsList.ReturnValu
     dispatch,
     getRootProps,
     highlightedValue,
-    direction,
-    orientation,
     rootRef: handleRef,
     selectedValue: selectedValues[0] ?? null,
-    tabActivationDirection,
   };
 }
 
@@ -260,7 +256,11 @@ function useActivationDirectionDetector(
 }
 
 namespace useTabsList {
-  export interface Parameters {
+  export interface Parameters
+    extends Pick<
+      TabsRootContext,
+      'direction' | 'onSelected' | 'orientation' | 'registerTabIdLookup' | 'value'
+    > {
     /**
      * If `true`, the tab will be activated whenever it is focused.
      * Otherwise, it has to be activated by clicking or pressing the Enter or Space key.
@@ -298,20 +298,11 @@ namespace useTabsList {
      * The value of the currently highlighted tab.
      */
     highlightedValue: any | null;
-    /**
-     * If `true`, it will indicate that the text's direction in right-to-left.
-     */
-    direction: TabsDirection;
-    /**
-     * The component orientation (layout flow direction).
-     */
-    orientation: TabsOrientation;
     rootRef: React.RefCallback<Element> | null;
     /**
      * The value of the currently selected tab.
      */
     selectedValue: any | null;
-    tabActivationDirection: TabActivationDirection;
   }
 }
 

From 546ee35e6645e19fa8d53e1d36d526a70320d8a3 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 22 Oct 2024 16:21:58 +0800
Subject: [PATCH 03/20] TabPanel

---
 packages/react/src/Tabs/TabPanel/TabPanel.tsx | 32 +++++++++++++------
 .../src/Tabs/TabPanel/useTabPanel.test.tsx    | 16 ++++++++--
 .../react/src/Tabs/TabPanel/useTabPanel.ts    | 28 +++++++---------
 3 files changed, 49 insertions(+), 27 deletions(-)

diff --git a/packages/react/src/Tabs/TabPanel/TabPanel.tsx b/packages/react/src/Tabs/TabPanel/TabPanel.tsx
index 89d5e56889..87e14938e6 100644
--- a/packages/react/src/Tabs/TabPanel/TabPanel.tsx
+++ b/packages/react/src/Tabs/TabPanel/TabPanel.tsx
@@ -3,6 +3,7 @@ import * as React from 'react';
 import PropTypes from 'prop-types';
 import { useTabPanel } from './useTabPanel';
 import { tabsStyleHookMapping } from '../Root/styleHooks';
+import { useTabsRootContext } from '../Root/TabsRootContext';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import { TabsRoot } from '../Root/TabsRoot';
 import type { BaseUIComponentProps } from '../../utils/types';
@@ -21,19 +22,32 @@ const TabPanel = React.forwardRef(function TabPanel(
   props: TabPanel.Props,
   forwardedRef: React.ForwardedRef<HTMLDivElement>,
 ) {
-  const { children, className, value, render, keepMounted = false, ...other } = props;
+  const { children, className, value: valueProp, render, keepMounted = false, ...other } = props;
 
-  const { hidden, getRootProps, orientation, direction, tabActivationDirection } = useTabPanel({
-    ...props,
-    rootRef: forwardedRef,
-  });
-
-  const ownerState: TabPanel.OwnerState = {
-    hidden,
+  const {
+    value: selectedValue,
+    getTabId,
     orientation,
     direction,
     tabActivationDirection,
-  };
+  } = useTabsRootContext();
+
+  const { hidden, getRootProps } = useTabPanel({
+    getTabId,
+    rootRef: forwardedRef,
+    selectedValue,
+    value: valueProp,
+  });
+
+  const ownerState: TabPanel.OwnerState = React.useMemo(
+    () => ({
+      direction,
+      hidden,
+      orientation,
+      tabActivationDirection,
+    }),
+    [direction, hidden, orientation, tabActivationDirection],
+  );
 
   const { renderElement } = useComponentRenderer({
     propGetter: getRootProps,
diff --git a/packages/react/src/Tabs/TabPanel/useTabPanel.test.tsx b/packages/react/src/Tabs/TabPanel/useTabPanel.test.tsx
index 5927463ad6..9973048be4 100644
--- a/packages/react/src/Tabs/TabPanel/useTabPanel.test.tsx
+++ b/packages/react/src/Tabs/TabPanel/useTabPanel.test.tsx
@@ -12,7 +12,13 @@ describe('useTabPanel', () => {
     it('returns props for root slot', () => {
       const rootRef = React.createRef<HTMLDivElement>();
       function TestTabPanel() {
-        const { getRootProps } = useTabPanel({ rootRef, id: 'test-tabpanel', value: 0 });
+        const { getRootProps } = useTabPanel({
+          getTabId: () => undefined,
+          id: 'test-tabpanel',
+          rootRef,
+          selectedValue: 0,
+          value: 0,
+        });
         return <div {...getRootProps()} />;
       }
 
@@ -35,7 +41,13 @@ describe('useTabPanel', () => {
       const rootRef = React.createRef<HTMLElement>();
 
       function TestTabPanel() {
-        const { getRootProps } = useTabPanel({ rootRef, value: 0 });
+        const { getRootProps } = useTabPanel({
+          getTabId: () => undefined,
+          id: 'test-tabpanel',
+          rootRef,
+          selectedValue: 0,
+          value: 0,
+        });
         return (
           <div
             {...getRootProps({
diff --git a/packages/react/src/Tabs/TabPanel/useTabPanel.ts b/packages/react/src/Tabs/TabPanel/useTabPanel.ts
index 7ffb05ac4e..fb772d1d5d 100644
--- a/packages/react/src/Tabs/TabPanel/useTabPanel.ts
+++ b/packages/react/src/Tabs/TabPanel/useTabPanel.ts
@@ -1,25 +1,23 @@
 'use client';
 import * as React from 'react';
-import { useTabsRootContext } from '../Root/TabsRootContext';
+import type { TabsRootContext } from '../Root/TabsRootContext';
 import { useCompoundItem } from '../../useCompound';
 import { useId } from '../../utils/useId';
 import { useForkRef } from '../../utils/useForkRef';
 import { mergeReactProps } from '../../utils/mergeReactProps';
-import { TabActivationDirection, TabsDirection, TabsOrientation } from '../Root/TabsRoot';
 
 function tabPanelValueGenerator(otherTabPanelValues: Set<any>) {
   return otherTabPanelValues.size;
 }
 
 function useTabPanel(parameters: useTabPanel.Parameters): useTabPanel.ReturnValue {
-  const { value: valueParam, id: idParam, rootRef: externalRef } = parameters;
   const {
-    value: selectedTabValue,
     getTabId,
-    orientation,
-    direction,
-    tabActivationDirection,
-  } = useTabsRootContext();
+    id: idParam,
+    rootRef: externalRef,
+    selectedValue,
+    value: valueParam,
+  } = parameters;
 
   const id = useId(idParam);
   const ref = React.useRef<HTMLElement>(null);
@@ -28,7 +26,7 @@ function useTabPanel(parameters: useTabPanel.Parameters): useTabPanel.ReturnValu
 
   const { id: value } = useCompoundItem(valueParam ?? tabPanelValueGenerator, metadata);
 
-  const hidden = value !== selectedTabValue;
+  const hidden = value !== selectedValue;
 
   const correspondingTabId = value !== undefined ? getTabId(value) : undefined;
 
@@ -52,14 +50,11 @@ function useTabPanel(parameters: useTabPanel.Parameters): useTabPanel.ReturnValu
     hidden,
     getRootProps,
     rootRef: handleRef,
-    orientation,
-    direction,
-    tabActivationDirection,
   };
 }
 
 namespace useTabPanel {
-  export interface Parameters {
+  export interface Parameters extends Pick<TabsRootContext, 'getTabId'> {
     /**
      * The id of the TabPanel.
      */
@@ -68,6 +63,10 @@ namespace useTabPanel {
      * The ref of the TabPanel.
      */
     rootRef?: React.Ref<HTMLElement>;
+    /**
+     * The (context) value of the currently active/selected Tab.
+     */
+    selectedValue: TabsRootContext['value'];
     /**
      * The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected.
      */
@@ -88,9 +87,6 @@ namespace useTabPanel {
       externalProps?: React.ComponentPropsWithRef<'div'>,
     ) => React.ComponentPropsWithRef<'div'>;
     rootRef: React.RefCallback<HTMLElement> | null;
-    orientation: TabsOrientation;
-    direction: TabsDirection;
-    tabActivationDirection: TabActivationDirection;
   }
 }
 

From 47dc125d3eb6e728bcc07296937f4143ef396a6d Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 22 Oct 2024 17:08:43 +0800
Subject: [PATCH 04/20] TabIndicator

---
 .../src/Tabs/TabIndicator/TabIndicator.tsx    | 36 ++++++++++---------
 .../src/Tabs/TabIndicator/useTabIndicator.ts  | 22 ++++++------
 packages/react/src/utils/useOnMount.ts        |  4 +++
 3 files changed, 34 insertions(+), 28 deletions(-)
 create mode 100644 packages/react/src/utils/useOnMount.ts

diff --git a/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx b/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx
index c484947a00..7f1a0f5ace 100644
--- a/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx
+++ b/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx
@@ -6,7 +6,9 @@ import { script as prehydrationScript } from './prehydrationScript.min';
 import type { TabsDirection, TabsOrientation, TabsRoot } from '../Root/TabsRoot';
 import { useTabsRootContext } from '../Root/TabsRootContext';
 import { tabsStyleHookMapping } from '../Root/styleHooks';
+import { useTabsListContext } from '../TabsList/TabsListContext';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
+import { useOnMount } from '../../utils/useOnMount';
 import type { BaseUIComponentProps } from '../../utils/types';
 
 const noop = () => null;
@@ -25,28 +27,30 @@ const TabIndicator = React.forwardRef<HTMLSpanElement, TabIndicator.Props>(
   function TabIndicator(props, forwardedRef) {
     const { className, render, renderBeforeHydration = false, ...other } = props;
 
+    const { orientation, direction, value, tabActivationDirection } = useTabsRootContext();
+    const { tabsListRef, getTabElement } = useTabsListContext();
+
     const [instanceId] = React.useState(() => Math.random().toString(36).slice(2));
     const [isMounted, setIsMounted] = React.useState(false);
     const { value: activeTabValue } = useTabsRootContext();
 
-    React.useEffect(() => {
-      setIsMounted(true);
-    }, []);
+    useOnMount(() => setIsMounted(true));
 
-    const {
-      direction,
-      getRootProps,
-      orientation,
-      activeTabPosition: selectedTabPosition,
-      tabActivationDirection,
-    } = useTabIndicator();
+    const { getRootProps, activeTabPosition: selectedTabPosition } = useTabIndicator({
+      getTabElement,
+      tabsListRef,
+      value,
+    });
 
-    const ownerState: TabIndicator.OwnerState = {
-      selectedTabPosition,
-      orientation,
-      direction,
-      tabActivationDirection,
-    };
+    const ownerState: TabIndicator.OwnerState = React.useMemo(
+      () => ({
+        direction,
+        orientation,
+        selectedTabPosition,
+        tabActivationDirection,
+      }),
+      [direction, orientation, selectedTabPosition, tabActivationDirection],
+    );
 
     const { renderElement } = useComponentRenderer({
       propGetter: getRootProps,
diff --git a/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts b/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts
index 8571028952..b5da1e42fa 100644
--- a/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts
+++ b/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts
@@ -1,18 +1,18 @@
 'use client';
 import * as React from 'react';
-import { useTabsListContext } from '../TabsList/TabsListContext';
-import { useTabsRootContext } from '../Root/TabsRootContext';
+import type { TabsListContext } from '../TabsList/TabsListContext';
+import type { TabsRootContext } from '../Root/TabsRootContext';
 import { mergeReactProps } from '../../utils/mergeReactProps';
 import { useForcedRerendering } from '../../utils/useForcedRerendering';
-import type { TabsDirection, TabsOrientation, TabActivationDirection } from '../Root/TabsRoot';
 
 function round(value: number) {
   return Math.round(value * 100) * 0.01;
 }
 
-export function useTabIndicator(): useTabIndicator.ReturnValue {
-  const { tabsListRef, getTabElement } = useTabsListContext();
-  const { orientation, direction, value, tabActivationDirection } = useTabsRootContext();
+export function useTabIndicator(
+  parameters: useTabIndicator.Parameters,
+): useTabIndicator.ReturnValue {
+  const { value, tabsListRef, getTabElement } = parameters;
 
   const rerender = useForcedRerendering();
   React.useEffect(() => {
@@ -109,9 +109,6 @@ export function useTabIndicator(): useTabIndicator.ReturnValue {
   return {
     getRootProps,
     activeTabPosition,
-    orientation,
-    direction,
-    tabActivationDirection,
   };
 }
 
@@ -123,13 +120,14 @@ export interface ActiveTabPosition {
 }
 
 export namespace useTabIndicator {
+  export interface Parameters extends Pick<TabsListContext, 'getTabElement' | 'tabsListRef'> {
+    value: TabsRootContext['value'];
+  }
+
   export interface ReturnValue {
     getRootProps: (
       otherProps?: React.ComponentPropsWithRef<'span'>,
     ) => React.ComponentPropsWithRef<'span'>;
     activeTabPosition: ActiveTabPosition | null;
-    direction: TabsDirection;
-    orientation: TabsOrientation;
-    tabActivationDirection: TabActivationDirection;
   }
 }
diff --git a/packages/react/src/utils/useOnMount.ts b/packages/react/src/utils/useOnMount.ts
new file mode 100644
index 0000000000..429fe1db6c
--- /dev/null
+++ b/packages/react/src/utils/useOnMount.ts
@@ -0,0 +1,4 @@
+/**
+ * @ignore - internal hook.
+ */
+export { default as useOnMount } from '@mui/utils/useOnMount';

From d59589a5ac02f55ae91c8d078497c9f432b93f9f Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Thu, 14 Nov 2024 00:29:52 +0800
Subject: [PATCH 05/20] Add composite list item metadata support

---
 .../src/Composite/List/CompositeList.tsx      | 42 +++++++++++++------
 .../Composite/List/CompositeListContext.ts    | 12 +++---
 .../Composite/List/useCompositeListItem.ts    | 16 +++----
 .../src/utils/fastObjectShallowCompare.ts     | 32 ++++++++++++++
 4 files changed, 77 insertions(+), 25 deletions(-)
 create mode 100644 packages/react/src/utils/fastObjectShallowCompare.ts

diff --git a/packages/react/src/Composite/List/CompositeList.tsx b/packages/react/src/Composite/List/CompositeList.tsx
index 09815eb7e6..5caa95f889 100644
--- a/packages/react/src/Composite/List/CompositeList.tsx
+++ b/packages/react/src/Composite/List/CompositeList.tsx
@@ -2,6 +2,7 @@
 'use client';
 import * as React from 'react';
 import PropTypes from 'prop-types';
+import { fastObjectShallowCompare } from '../../utils/fastObjectShallowCompare';
 import { useEnhancedEffect } from '../../utils/useEnhancedEffect';
 import { CompositeListContext } from './CompositeListContext';
 
@@ -22,12 +23,22 @@ function sortByDocumentPosition(a: Node, b: Node) {
   return 0;
 }
 
-function areMapsEqual(map1: Map<Node, number | null>, map2: Map<Node, number | null>) {
+type BaseMetadata = { index?: number | null };
+
+function areMapsEqual<CustomMetadata>(
+  map1: Map<Node, (CustomMetadata & BaseMetadata) | null>,
+  map2: Map<Node, (CustomMetadata & BaseMetadata) | null>,
+) {
   if (map1.size !== map2.size) {
     return false;
   }
   for (const [key, value] of map1.entries()) {
-    if (value !== map2.get(key)) {
+    const value2 = map2.get(key);
+    // compare the index before comparing everything else
+    if (value?.index !== value2?.index) {
+      return false;
+    }
+    if (value2 !== undefined && !fastObjectShallowCompare(value, value2)) {
       return false;
     }
   }
@@ -38,13 +49,15 @@ function areMapsEqual(map1: Map<Node, number | null>, map2: Map<Node, number | n
  * Provides context for a list of items in a composite component.
  * @ignore - internal component.
  */
-function CompositeList(props: CompositeList.Props) {
-  const { children, elementsRef, labelsRef } = props;
+function CompositeList<CustomMetadata>(props: CompositeList.Props<CustomMetadata>) {
+  const { children, elementsRef, labelsRef, onMapChange } = props;
 
-  const [map, setMap] = React.useState(() => new Map<Node, number | null>());
+  const [map, setMap] = React.useState(
+    () => new Map<Node, (CustomMetadata & BaseMetadata) | null>(),
+  );
 
-  const register = React.useCallback((node: Node) => {
-    setMap((prevMap) => new Map(prevMap).set(node, null));
+  const register = React.useCallback((node: Node, metadata: CustomMetadata) => {
+    setMap((prevMap) => new Map(prevMap).set(node, metadata ?? null));
   }, []);
 
   const unregister = React.useCallback((node: Node) => {
@@ -57,16 +70,20 @@ function CompositeList(props: CompositeList.Props) {
 
   useEnhancedEffect(() => {
     const newMap = new Map(map);
+
     const nodes = Array.from(newMap.keys()).sort(sortByDocumentPosition);
 
     nodes.forEach((node, index) => {
-      newMap.set(node, index);
+      const metadata = map.get(node) ?? ({} as CustomMetadata & BaseMetadata);
+
+      newMap.set(node, { ...metadata, index });
     });
 
     if (!areMapsEqual(map, newMap)) {
       setMap(newMap);
+      onMapChange?.(newMap);
     }
-  }, [map]);
+  }, [map, onMapChange]);
 
   const contextValue = React.useMemo(
     () => ({ register, unregister, map, elementsRef, labelsRef }),
@@ -79,18 +96,19 @@ function CompositeList(props: CompositeList.Props) {
 }
 
 namespace CompositeList {
-  export interface Props {
+  export interface Props<CustomMetadata> {
     children: React.ReactNode;
     /**
      * A ref to the list of HTML elements, ordered by their index.
      * `useListNavigation`'s `listRef` prop.
      */
-    elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+    elementsRef: React.RefObject<Array<HTMLElement | null>>;
     /**
      * A ref to the list of element labels, ordered by their index.
      * `useTypeahead`'s `listRef` prop.
      */
-    labelsRef?: React.MutableRefObject<Array<string | null>>;
+    labelsRef?: React.RefObject<Array<string | null>>;
+    onMapChange?: (newMap: Map<Node, (CustomMetadata & BaseMetadata) | null>) => void;
   }
 }
 
diff --git a/packages/react/src/Composite/List/CompositeListContext.ts b/packages/react/src/Composite/List/CompositeListContext.ts
index 4f1358525f..4bd95392c0 100644
--- a/packages/react/src/Composite/List/CompositeListContext.ts
+++ b/packages/react/src/Composite/List/CompositeListContext.ts
@@ -1,15 +1,15 @@
 'use client';
 import * as React from 'react';
 
-export interface CompositeListContextValue {
-  register: (node: Node) => void;
+export interface CompositeListContextValue<Metadata> {
+  register: (node: Node, metadata: Metadata) => void;
   unregister: (node: Node) => void;
-  map: Map<Node, number | null>;
-  elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
-  labelsRef?: React.MutableRefObject<Array<string | null>>;
+  map: Map<Node, Metadata | null>;
+  elementsRef: React.RefObject<Array<HTMLElement | null>>;
+  labelsRef?: React.RefObject<Array<string | null>>;
 }
 
-export const CompositeListContext = React.createContext<CompositeListContextValue>({
+export const CompositeListContext = React.createContext<CompositeListContextValue<any>>({
   register: () => {},
   unregister: () => {},
   map: new Map(),
diff --git a/packages/react/src/Composite/List/useCompositeListItem.ts b/packages/react/src/Composite/List/useCompositeListItem.ts
index c4cd337da9..ef21fb47e2 100644
--- a/packages/react/src/Composite/List/useCompositeListItem.ts
+++ b/packages/react/src/Composite/List/useCompositeListItem.ts
@@ -3,8 +3,9 @@ import * as React from 'react';
 import { useEnhancedEffect } from '../../utils/useEnhancedEffect';
 import { useCompositeListContext } from './CompositeListContext';
 
-export interface UseCompositeListItemParameters {
+export interface UseCompositeListItemParameters<Metadata> {
   label?: string | null;
+  metadata?: Metadata;
 }
 
 interface UseCompositeListItemReturnValue {
@@ -20,10 +21,10 @@ interface UseCompositeListItemReturnValue {
  *
  * - [useCompositeListItem API](https://mui.com/base-ui/api/use-composite-list-item/)
  */
-export function useCompositeListItem(
-  params: UseCompositeListItemParameters = {},
+export function useCompositeListItem<Metadata>(
+  params: UseCompositeListItemParameters<Metadata> = {},
 ): UseCompositeListItemReturnValue {
-  const { label } = params;
+  const { label, metadata } = params;
 
   const { register, unregister, map, elementsRef, labelsRef } = useCompositeListContext();
 
@@ -49,16 +50,17 @@ export function useCompositeListItem(
   useEnhancedEffect(() => {
     const node = componentRef.current;
     if (node) {
-      register(node);
+      register(node, metadata);
       return () => {
         unregister(node);
       };
     }
     return undefined;
-  }, [register, unregister]);
+  }, [register, unregister, metadata]);
 
   useEnhancedEffect(() => {
-    const i = componentRef.current ? map.get(componentRef.current) : null;
+    const i = componentRef.current ? map.get(componentRef.current)?.index : null;
+
     if (i != null) {
       setIndex(i);
     }
diff --git a/packages/react/src/utils/fastObjectShallowCompare.ts b/packages/react/src/utils/fastObjectShallowCompare.ts
new file mode 100644
index 0000000000..18046b3ca5
--- /dev/null
+++ b/packages/react/src/utils/fastObjectShallowCompare.ts
@@ -0,0 +1,32 @@
+// https://github.com/mui/mui-x/blob/master/packages/x-internals/src/fastObjectShallowCompare/fastObjectShallowCompare.ts
+const is = Object.is;
+
+export function fastObjectShallowCompare<T extends Record<string, any> | null>(a: T, b: T) {
+  if (a === b) {
+    return true;
+  }
+  if (!(a instanceof Object) || !(b instanceof Object)) {
+    return false;
+  }
+
+  let aLength = 0;
+  let bLength = 0;
+
+  /* eslint-disable guard-for-in */
+  for (const key in a) {
+    aLength += 1;
+
+    if (!is(a[key], b[key])) {
+      return false;
+    }
+    if (!(key in b)) {
+      return false;
+    }
+  }
+
+  /* eslint-disable-next-line @typescript-eslint/naming-convention, @typescript-eslint/no-unused-vars */
+  for (const _ in b) {
+    bLength += 1;
+  }
+  return aLength === bLength;
+}

From 8b34473ad0c7f4966a904095bec9aa1375abcba6 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 22 Oct 2024 20:19:42 +0800
Subject: [PATCH 06/20] Use Composite for TabsRoot and TabPanel

---
 packages/react/src/Tabs/Root/TabsProvider.tsx | 108 ---------------
 packages/react/src/Tabs/Root/TabsRoot.tsx     |  59 ++++++--
 .../react/src/Tabs/Root/TabsRootContext.ts    |   4 +-
 packages/react/src/Tabs/Root/useTabsRoot.ts   | 128 ++++++++++++------
 packages/react/src/Tabs/Tab/Tab.test.tsx      |   2 +-
 packages/react/src/Tabs/Tab/Tab.tsx           |   8 +-
 packages/react/src/Tabs/Tab/useTab.test.tsx   |   4 +-
 packages/react/src/Tabs/Tab/useTab.ts         |   6 +-
 .../react/src/Tabs/TabPanel/TabPanel.test.tsx |  24 +++-
 .../react/src/Tabs/TabPanel/useTabPanel.ts    |  65 ++++++---
 .../react/src/Tabs/TabsList/TabsList.test.tsx |   2 +-
 .../react/src/Tabs/TabsList/useTabsList.ts    |   4 +
 12 files changed, 216 insertions(+), 198 deletions(-)
 delete mode 100644 packages/react/src/Tabs/Root/TabsProvider.tsx

diff --git a/packages/react/src/Tabs/Root/TabsProvider.tsx b/packages/react/src/Tabs/Root/TabsProvider.tsx
deleted file mode 100644
index d8d2e55157..0000000000
--- a/packages/react/src/Tabs/Root/TabsProvider.tsx
+++ /dev/null
@@ -1,108 +0,0 @@
-'use client';
-import * as React from 'react';
-import PropTypes from 'prop-types';
-import { TabsRootContext } from './TabsRootContext';
-import { CompoundComponentContext, CompoundComponentContextValue } from '../../useCompound';
-
-export type TabPanelMetadata = {
-  id: string | undefined;
-  ref: React.RefObject<HTMLElement>;
-};
-
-export type TabsProviderValue = CompoundComponentContextValue<any, TabPanelMetadata> &
-  TabsRootContext;
-
-export interface TabsProviderProps {
-  value: TabsProviderValue;
-  children: React.ReactNode;
-}
-
-/**
- * Sets up the contexts for the underlying Tab and TabPanel components.
- *
- * @ignore - do not document.
- */
-const TabsProvider: React.FC<TabsProviderProps> = function TabsProvider(props) {
-  const { value: valueProp, children } = props;
-  const {
-    direction,
-    getItemIndex,
-    onSelected,
-    orientation,
-    registerItem,
-    registerTabIdLookup,
-    totalSubitemCount,
-    value,
-    getTabId,
-    getTabPanelId,
-    tabActivationDirection,
-  } = valueProp;
-
-  const compoundComponentContextValue: CompoundComponentContextValue<any, TabPanelMetadata> =
-    React.useMemo(
-      () => ({
-        getItemIndex,
-        registerItem,
-        totalSubitemCount,
-      }),
-      [registerItem, getItemIndex, totalSubitemCount],
-    );
-
-  const tabsContextValue: TabsRootContext = React.useMemo(
-    () => ({
-      direction,
-      getTabId,
-      getTabPanelId,
-      onSelected,
-      orientation,
-      registerTabIdLookup,
-      value,
-      tabActivationDirection,
-    }),
-    [
-      direction,
-      getTabId,
-      getTabPanelId,
-      onSelected,
-      orientation,
-      registerTabIdLookup,
-      value,
-      tabActivationDirection,
-    ],
-  );
-
-  return (
-    <CompoundComponentContext.Provider value={compoundComponentContextValue}>
-      <TabsRootContext.Provider value={tabsContextValue}>{children}</TabsRootContext.Provider>
-    </CompoundComponentContext.Provider>
-  );
-};
-
-TabsProvider.propTypes /* remove-proptypes */ = {
-  // ┌────────────────────────────── Warning ──────────────────────────────┐
-  // │ These PropTypes are generated from the TypeScript type definitions. │
-  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
-  // └─────────────────────────────────────────────────────────────────────┘
-  /**
-   * @ignore
-   */
-  children: PropTypes.node,
-  /**
-   * @ignore
-   */
-  value: PropTypes.shape({
-    direction: PropTypes.oneOf(['ltr', 'rtl']).isRequired,
-    getItemIndex: PropTypes.func.isRequired,
-    getTabId: PropTypes.func.isRequired,
-    getTabPanelId: PropTypes.func.isRequired,
-    onSelected: PropTypes.func.isRequired,
-    orientation: PropTypes.oneOf(['horizontal', 'vertical']).isRequired,
-    registerItem: PropTypes.func.isRequired,
-    registerTabIdLookup: PropTypes.func.isRequired,
-    tabActivationDirection: PropTypes.oneOf(['down', 'left', 'none', 'right', 'up']).isRequired,
-    totalSubitemCount: PropTypes.number.isRequired,
-    value: PropTypes.any,
-  }).isRequired,
-} as any;
-
-export { TabsProvider };
diff --git a/packages/react/src/Tabs/Root/TabsRoot.tsx b/packages/react/src/Tabs/Root/TabsRoot.tsx
index 7f36969908..86581f54ae 100644
--- a/packages/react/src/Tabs/Root/TabsRoot.tsx
+++ b/packages/react/src/Tabs/Root/TabsRoot.tsx
@@ -1,11 +1,13 @@
 'use client';
 import * as React from 'react';
 import PropTypes from 'prop-types';
-import { useTabsRoot } from './useTabsRoot';
-import { tabsStyleHookMapping } from './styleHooks';
-import { TabsProvider } from './TabsProvider';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import type { BaseUIComponentProps } from '../../utils/types';
+import { CompositeList } from '../../Composite/List/CompositeList';
+import { useTabsRoot } from './useTabsRoot';
+import { TabsRootContext } from './TabsRootContext';
+import { tabsStyleHookMapping } from './styleHooks';
+import { TabPanelMetadata } from '../TabPanel/useTabPanel';
 
 /**
  *
@@ -24,22 +26,55 @@ const TabsRoot = React.forwardRef(function TabsRoot(
   const {
     className,
     defaultValue,
-    direction = 'ltr',
+    direction: directionProp = 'ltr',
     onValueChange,
     orientation = 'horizontal',
     render,
-    value,
+    value: valueProp,
     ...other
   } = props;
 
-  const { contextValue, getRootProps, tabActivationDirection } = useTabsRoot({
+  const {
+    getRootProps,
+    direction,
+    getTabId,
+    getTabPanelIdByTabValueOrIndex,
+    onSelected,
+    registerTabIdLookup,
+    setTabPanelMap,
+    tabActivationDirection,
+    tabPanelRefs,
     value,
+  } = useTabsRoot({
+    value: valueProp,
     defaultValue,
     onValueChange,
-    orientation,
-    direction,
+    direction: directionProp,
   });
 
+  const tabsContextValue = React.useMemo(
+    () => ({
+      direction,
+      getTabId,
+      getTabPanelIdByTabValueOrIndex,
+      onSelected,
+      orientation,
+      registerTabIdLookup,
+      tabActivationDirection,
+      value,
+    }),
+    [
+      direction,
+      getTabId,
+      getTabPanelIdByTabValueOrIndex,
+      onSelected,
+      orientation,
+      registerTabIdLookup,
+      tabActivationDirection,
+      value,
+    ],
+  );
+
   const ownerState: TabsRoot.OwnerState = {
     orientation,
     direction,
@@ -56,7 +91,13 @@ const TabsRoot = React.forwardRef(function TabsRoot(
     customStyleHookMapping: tabsStyleHookMapping,
   });
 
-  return <TabsProvider value={contextValue}>{renderElement()}</TabsProvider>;
+  return (
+    <TabsRootContext.Provider value={tabsContextValue}>
+      <CompositeList<TabPanelMetadata> elementsRef={tabPanelRefs} onMapChange={setTabPanelMap}>
+        {renderElement()}
+      </CompositeList>
+    </TabsRootContext.Provider>
+  );
 });
 
 export type TabsOrientation = 'horizontal' | 'vertical';
diff --git a/packages/react/src/Tabs/Root/TabsRootContext.ts b/packages/react/src/Tabs/Root/TabsRootContext.ts
index 5e1e5e30da..6224a0beb9 100644
--- a/packages/react/src/Tabs/Root/TabsRootContext.ts
+++ b/packages/react/src/Tabs/Root/TabsRootContext.ts
@@ -6,7 +6,7 @@ export interface TabsRootContext {
   /**
    * The currently selected tab's value.
    */
-  value?: any | null;
+  value: any | null;
   /**
    * Callback for setting new value.
    */
@@ -36,7 +36,7 @@ export interface TabsRootContext {
    * Gets the id of the tab panel with the given value.
    * @param value Value to find the tab panel for.
    */
-  getTabPanelId: (value: any) => string | undefined;
+  getTabPanelIdByTabValueOrIndex: (tabValue: any, index: number) => string | undefined;
   /**
    * The position of the active tab relative to the previously active tab.
    */
diff --git a/packages/react/src/Tabs/Root/useTabsRoot.ts b/packages/react/src/Tabs/Root/useTabsRoot.ts
index 1a38f6e8f9..72ccf83463 100644
--- a/packages/react/src/Tabs/Root/useTabsRoot.ts
+++ b/packages/react/src/Tabs/Root/useTabsRoot.ts
@@ -1,10 +1,9 @@
 'use client';
 import * as React from 'react';
-import type { TabActivationDirection } from './TabsRoot';
-import type { TabsProviderValue, TabPanelMetadata } from './TabsProvider';
-import { useCompoundParent } from '../../useCompound';
 import { mergeReactProps } from '../../utils/mergeReactProps';
 import { useControlled } from '../../utils/useControlled';
+import type { TabPanelMetadata } from '../TabPanel/useTabPanel';
+import type { TabActivationDirection } from './TabsRoot';
 
 export interface TabMetadata {
   disabled: boolean;
@@ -15,13 +14,10 @@ export interface TabMetadata {
 type IdLookupFunction = (id: any) => string | undefined;
 
 function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValue {
-  const {
-    value: valueProp,
-    defaultValue,
-    onValueChange,
-    orientation = 'horizontal',
-    direction = 'ltr',
-  } = parameters;
+  const { value: valueProp, defaultValue, onValueChange, direction = 'ltr' } = parameters;
+
+  const tabPanelRefs = React.useRef<(HTMLElement | null)[]>([]);
+  const getTabIdByPanelValueRef = React.useRef<IdLookupFunction>(() => undefined);
 
   const [value, setValue] = useControlled({
     controlled: valueProp,
@@ -30,6 +26,10 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
     state: 'value',
   });
 
+  const [tabPanelMap, setTabPanelMap] = React.useState(
+    () => new Map<Node, (TabPanelMetadata & { index?: number | null }) | null>(),
+  );
+
   const [tabActivationDirection, setTabActivationDirection] =
     React.useState<TabActivationDirection>('none');
 
@@ -46,26 +46,39 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
     [onValueChange, setValue],
   );
 
-  const { subitems: tabPanels, contextValue: compoundComponentContextValue } = useCompoundParent<
-    any,
-    TabPanelMetadata
-  >();
-
-  const tabIdLookup = React.useRef<IdLookupFunction>(() => undefined);
-
-  const getTabPanelId = React.useCallback(
-    (tabValue: any) => {
-      return tabPanels.get(tabValue)?.id;
+  const getTabPanelIdByTabValueOrIndex = React.useCallback(
+    (tabValue: any | undefined, index: number) => {
+      if (tabValue === undefined && index < 0) {
+        return undefined;
+      }
+
+      for (const tabPanelMetadata of tabPanelMap.values()) {
+        // find by tabValue
+        if (tabValue !== undefined && tabPanelMetadata && tabValue === tabPanelMetadata?.value) {
+          return tabPanelMetadata.id;
+        }
+
+        // find by index
+        if (
+          tabValue === undefined &&
+          tabPanelMetadata?.index &&
+          tabPanelMetadata?.index === index
+        ) {
+          return tabPanelMetadata.id;
+        }
+      }
+
+      return undefined;
     },
-    [tabPanels],
+    [tabPanelMap],
   );
 
-  const getTabId = React.useCallback((tabPanelId: any) => {
-    return tabIdLookup.current(tabPanelId);
+  const getTabIdByPanelValue = React.useCallback((tabPanelValue: any) => {
+    return getTabIdByPanelValueRef.current(tabPanelValue);
   }, []);
 
   const registerTabIdLookup = React.useCallback((lookupFunction: IdLookupFunction) => {
-    tabIdLookup.current = lookupFunction;
+    getTabIdByPanelValueRef.current = lookupFunction;
   }, []);
 
   const getRootProps: useTabsRoot.ReturnValue['getRootProps'] = React.useCallback(
@@ -77,19 +90,16 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
   );
 
   return {
-    contextValue: {
-      direction,
-      getTabId,
-      getTabPanelId,
-      onSelected,
-      orientation,
-      registerTabIdLookup,
-      value,
-      tabActivationDirection,
-      ...compoundComponentContextValue,
-    },
     getRootProps,
+    direction,
+    getTabId: getTabIdByPanelValue,
+    getTabPanelIdByTabValueOrIndex,
+    onSelected,
+    registerTabIdLookup,
+    setTabPanelMap,
     tabActivationDirection,
+    tabPanelRefs,
+    value,
   };
 }
 
@@ -104,11 +114,6 @@ namespace useTabsRoot {
      * The default value. Use when the component is not controlled.
      */
     defaultValue?: any | null;
-    /**
-     * The component orientation (layout flow direction).
-     * @default 'horizontal'
-     */
-    orientation?: 'horizontal' | 'vertical';
     /**
      * The direction of the text.
      * @default 'ltr'
@@ -121,14 +126,49 @@ namespace useTabsRoot {
   }
 
   export interface ReturnValue {
-    /**
-     * Returns the values to be passed to the tabs provider.
-     */
-    contextValue: TabsProviderValue;
     getRootProps: (
       externalProps?: React.ComponentPropsWithRef<'div'>,
     ) => React.ComponentPropsWithRef<'div'>;
+    /**
+     * The direction of the text.
+     */
+    direction: 'ltr' | 'rtl';
+    /**
+     * Gets the id of the tab with the given value.
+     * @param value Value to find the tab for.
+     */
+    getTabId: (value: any) => string | undefined;
+    /**
+     * Gets the id of the tab panel with the given value.
+     * @param value Value to find the tab panel for.
+     */
+    getTabPanelIdByTabValueOrIndex: (
+      tabValue: any | undefined,
+      tabIndex: number,
+    ) => string | undefined;
+
+    /**
+     * Callback for setting new value.
+     */
+    onSelected: (
+      event: React.SyntheticEvent | null,
+      value: any | null,
+      activationDirection: TabActivationDirection,
+    ) => void;
+    /**
+     * Registers a function that returns the id of the tab with the given value.
+     */
+    registerTabIdLookup: (lookupFunction: (id: any) => string | undefined) => void;
+    setTabPanelMap: (map: Map<Node, (TabPanelMetadata & { index?: number | null }) | null>) => void;
+    /**
+     * The position of the active tab relative to the previously active tab.
+     */
     tabActivationDirection: TabActivationDirection;
+    tabPanelRefs: React.RefObject<(HTMLElement | null)[]>;
+    /**
+     * The currently selected tab's value.
+     */
+    value: any | null;
   }
 }
 
diff --git a/packages/react/src/Tabs/Tab/Tab.test.tsx b/packages/react/src/Tabs/Tab/Tab.test.tsx
index 257e289b41..e6100173dc 100644
--- a/packages/react/src/Tabs/Tab/Tab.test.tsx
+++ b/packages/react/src/Tabs/Tab/Tab.test.tsx
@@ -27,7 +27,7 @@ describe('<Tabs.Tab />', () => {
     onSelected() {},
     registerTabIdLookup() {},
     getTabId: () => '',
-    getTabPanelId: () => '',
+    getTabPanelIdByTabValueOrIndex: () => '',
     orientation: 'horizontal',
     direction: 'ltr',
     tabActivationDirection: 'none',
diff --git a/packages/react/src/Tabs/Tab/Tab.tsx b/packages/react/src/Tabs/Tab/Tab.tsx
index 8b217b7807..eda994f345 100644
--- a/packages/react/src/Tabs/Tab/Tab.tsx
+++ b/packages/react/src/Tabs/Tab/Tab.tsx
@@ -23,11 +23,15 @@ const Tab = React.forwardRef(function Tab(
 ) {
   const { className, disabled = false, render, value: valueProp, ...other } = props;
 
-  const { value: selectedValue, getTabPanelId, orientation } = useTabsRootContext();
+  const {
+    value: selectedValue,
+    getTabPanelIdByTabValueOrIndex,
+    orientation,
+  } = useTabsRootContext();
 
   const { selected, getRootProps } = useTab({
     ...props,
-    getTabPanelId,
+    getTabPanelIdByTabValueOrIndex,
     isSelected: valueProp === selectedValue,
     rootRef: forwardedRef,
   });
diff --git a/packages/react/src/Tabs/Tab/useTab.test.tsx b/packages/react/src/Tabs/Tab/useTab.test.tsx
index 9f817177a1..fd4fe50130 100644
--- a/packages/react/src/Tabs/Tab/useTab.test.tsx
+++ b/packages/react/src/Tabs/Tab/useTab.test.tsx
@@ -15,7 +15,7 @@ describe('useTab', () => {
         const { getRootProps } = useTab({
           rootRef,
           isSelected: true,
-          getTabPanelId: () => undefined,
+          getTabPanelIdByTabValueOrIndex: () => undefined,
         });
         return <button {...getRootProps()} />;
       }
@@ -44,7 +44,7 @@ describe('useTab', () => {
         const { getRootProps } = useTab({
           rootRef,
           isSelected: true,
-          getTabPanelId: () => undefined,
+          getTabPanelIdByTabValueOrIndex: () => undefined,
         });
         return (
           <button
diff --git a/packages/react/src/Tabs/Tab/useTab.ts b/packages/react/src/Tabs/Tab/useTab.ts
index 3fec1f4570..c54b4a1946 100644
--- a/packages/react/src/Tabs/Tab/useTab.ts
+++ b/packages/react/src/Tabs/Tab/useTab.ts
@@ -18,7 +18,7 @@ function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
     value: valueParam,
     rootRef: externalRef,
     disabled = false,
-    getTabPanelId,
+    getTabPanelIdByTabValueOrIndex,
     id: idParam,
     isSelected,
   } = parameters;
@@ -46,7 +46,7 @@ function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
 
   const handleRef = useForkRef(tabRef, externalRef, buttonRefHandler);
 
-  const tabPanelId = value !== undefined ? getTabPanelId(value) : undefined;
+  const tabPanelId = index > -1 ? getTabPanelIdByTabValueOrIndex(valueParam, index) : undefined;
 
   const getRootProps = React.useCallback(
     (externalProps = {}) => {
@@ -79,7 +79,7 @@ function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
 }
 
 namespace useTab {
-  export interface Parameters extends Pick<TabsRootContext, 'getTabPanelId'> {
+  export interface Parameters extends Pick<TabsRootContext, 'getTabPanelIdByTabValueOrIndex'> {
     /**
      * The value of the tab.
      * It's used to associate the tab with a tab panel(s) with the same value.
diff --git a/packages/react/src/Tabs/TabPanel/TabPanel.test.tsx b/packages/react/src/Tabs/TabPanel/TabPanel.test.tsx
index 376fafdabd..161aee47e4 100644
--- a/packages/react/src/Tabs/TabPanel/TabPanel.test.tsx
+++ b/packages/react/src/Tabs/TabPanel/TabPanel.test.tsx
@@ -1,20 +1,24 @@
 import * as React from 'react';
 import { Tabs } from '@base-ui-components/react/Tabs';
 import { createRenderer, describeConformance } from '#test-utils';
-import { TabsProvider, TabsProviderValue } from '../Root/TabsProvider';
+import { CompoundComponentContext } from '../../useCompound';
+import { TabsRootContext } from '../Root/TabsRootContext';
 
 describe('<Tabs.Panel />', () => {
   const { render } = createRenderer();
 
-  const tabsProviderDefaultValue: TabsProviderValue = {
+  const compoundContextValue = {
+    getItemIndex: () => 0,
+    registerItem: () => ({ id: 0, deregister: () => {} }),
+    totalSubitemCount: 1,
+  };
+
+  const tabsContextDefaultValue: TabsRootContext = {
     value: '1',
     onSelected: () => {},
     registerTabIdLookup() {},
     getTabId: () => '',
-    getTabPanelId: () => '',
-    getItemIndex: () => 0,
-    registerItem: () => ({ id: 0, deregister: () => {} }),
-    totalSubitemCount: 1,
+    getTabPanelIdByTabValueOrIndex: () => '',
     direction: 'ltr',
     orientation: 'horizontal',
     tabActivationDirection: 'none',
@@ -22,7 +26,13 @@ describe('<Tabs.Panel />', () => {
 
   describeConformance(<Tabs.Panel value="1" />, () => ({
     render: (node) => {
-      return render(<TabsProvider value={tabsProviderDefaultValue}>{node}</TabsProvider>);
+      return render(
+        <CompoundComponentContext.Provider value={compoundContextValue}>
+          <TabsRootContext.Provider value={tabsContextDefaultValue}>
+            {node}
+          </TabsRootContext.Provider>
+        </CompoundComponentContext.Provider>,
+      );
     },
     refInstanceof: window.HTMLDivElement,
   }));
diff --git a/packages/react/src/Tabs/TabPanel/useTabPanel.ts b/packages/react/src/Tabs/TabPanel/useTabPanel.ts
index fb772d1d5d..65d288dfa8 100644
--- a/packages/react/src/Tabs/TabPanel/useTabPanel.ts
+++ b/packages/react/src/Tabs/TabPanel/useTabPanel.ts
@@ -1,49 +1,76 @@
 'use client';
 import * as React from 'react';
 import type { TabsRootContext } from '../Root/TabsRootContext';
-import { useCompoundItem } from '../../useCompound';
 import { useId } from '../../utils/useId';
 import { useForkRef } from '../../utils/useForkRef';
 import { mergeReactProps } from '../../utils/mergeReactProps';
+import { useCompositeListContext } from '../../Composite/List/CompositeListContext';
+import { useCompositeListItem } from '../../Composite/List/useCompositeListItem';
 
-function tabPanelValueGenerator(otherTabPanelValues: Set<any>) {
-  return otherTabPanelValues.size;
+export interface TabPanelMetadata {
+  id?: string;
+  value: useTabPanel.Parameters['value'];
 }
 
 function useTabPanel(parameters: useTabPanel.Parameters): useTabPanel.ReturnValue {
-  const {
-    getTabId,
-    id: idParam,
-    rootRef: externalRef,
-    selectedValue,
-    value: valueParam,
-  } = parameters;
+  const { rootRef: externalRef, selectedValue, value: valueParam } = parameters;
 
-  const id = useId(idParam);
-  const ref = React.useRef<HTMLElement>(null);
-  const handleRef = useForkRef(ref, externalRef);
-  const metadata = React.useMemo(() => ({ id, ref }), [id]);
+  const id = useId();
 
-  const { id: value } = useCompoundItem(valueParam ?? tabPanelValueGenerator, metadata);
+  const metadata = React.useMemo(
+    () => ({
+      id,
+      value: valueParam,
+    }),
+    [id, valueParam],
+  );
+
+  // tabPanelCompositeMap
+  const { map: tabPanelCompositeMap } = useCompositeListContext();
+
+  const { ref: listItemRef, index } = useCompositeListItem<TabPanelMetadata>({
+    metadata,
+  });
+
+  const tabPanelValue = valueParam ?? index;
+
+  const panelRef = React.useRef<HTMLElement>(null);
+  const handleRef = useForkRef(panelRef, listItemRef, externalRef);
+
+  const hidden = tabPanelValue !== selectedValue;
+
+  // const correspondingTabId = tabPanelValue !== undefined ? getTabId(tabPanelValue) : undefined;
+
+  const tabId = React.useMemo(() => {
+    if (index < 0) {
+      return undefined;
+    }
 
-  const hidden = value !== selectedValue;
+    // TODO: this is incorrect, should be tabButtonMap
+    for (const value of tabPanelCompositeMap.values()) {
+      if (value.index > -1 && value.index === index) {
+        return value.id;
+      }
+    }
 
-  const correspondingTabId = value !== undefined ? getTabId(value) : undefined;
+    return undefined;
+  }, [index, tabPanelCompositeMap]);
 
   const getRootProps = React.useCallback(
     (
       externalProps: React.ComponentPropsWithoutRef<'div'> = {},
     ): React.ComponentPropsWithRef<'div'> => {
       return mergeReactProps(externalProps, {
-        'aria-labelledby': correspondingTabId ?? undefined,
+        'aria-labelledby': undefined,
         hidden,
         id: id ?? undefined,
         role: 'tabpanel',
         tabIndex: hidden ? -1 : 0,
         ref: handleRef,
+        'data-index': index,
       });
     },
-    [correspondingTabId, handleRef, hidden, id],
+    [handleRef, hidden, id, index],
   );
 
   return {
diff --git a/packages/react/src/Tabs/TabsList/TabsList.test.tsx b/packages/react/src/Tabs/TabsList/TabsList.test.tsx
index 397f4db803..d4d5c6ba6f 100644
--- a/packages/react/src/Tabs/TabsList/TabsList.test.tsx
+++ b/packages/react/src/Tabs/TabsList/TabsList.test.tsx
@@ -17,7 +17,7 @@ describe('<Tabs.List />', () => {
             onSelected: () => {},
             registerTabIdLookup() {},
             getTabId: () => '',
-            getTabPanelId: () => '',
+            getTabPanelIdByTabValueOrIndex: () => '',
             orientation: 'horizontal',
             direction: 'ltr',
             tabActivationDirection: 'none',
diff --git a/packages/react/src/Tabs/TabsList/useTabsList.ts b/packages/react/src/Tabs/TabsList/useTabsList.ts
index 3845e5883c..52b41230f9 100644
--- a/packages/react/src/Tabs/TabsList/useTabsList.ts
+++ b/packages/react/src/Tabs/TabsList/useTabsList.ts
@@ -28,6 +28,9 @@ function useTabsList(parameters: useTabsList.Parameters): useTabsList.ReturnValu
     TabMetadata
   >();
 
+  // get id attribute of a Tab by tab value
+  // for binding aria attributes
+  // this function needs to be registered to the context
   const tabIdLookup = React.useCallback(
     (tabValue: any) => {
       return subitems.get(tabValue)?.id;
@@ -39,6 +42,7 @@ function useTabsList(parameters: useTabsList.Parameters): useTabsList.ReturnValu
 
   const subitemKeys = React.useMemo(() => Array.from(subitems.keys()), [subitems]);
 
+  // get the element/node of a tab by tab value
   const getTabElement = React.useCallback(
     (tabValue: any) => {
       if (tabValue == null) {

From 22e35b8b141d2c84a3de5b479a25bdf624ffc594 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Fri, 15 Nov 2024 01:01:43 +0800
Subject: [PATCH 07/20] Use Composite for TabsList and Tabs

---
 .../src/Composite/Item/useCompositeItem.ts    |   8 +-
 .../src/Composite/List/CompositeList.tsx      |  12 +-
 .../src/Composite/Root/CompositeRoot.tsx      |   7 +-
 packages/react/src/Tabs/Root/TabsRoot.tsx     |  72 ++----
 .../react/src/Tabs/Root/TabsRootContext.ts    |  14 +-
 packages/react/src/Tabs/Root/useTabsRoot.ts   |  88 ++++---
 packages/react/src/Tabs/Tab/Tab.test.tsx      |  21 +-
 packages/react/src/Tabs/Tab/Tab.tsx           |  54 ++---
 packages/react/src/Tabs/Tab/useTab.test.tsx   |   3 +
 packages/react/src/Tabs/Tab/useTab.ts         |  61 ++---
 .../src/Tabs/TabIndicator/TabIndicator.tsx    |  31 +--
 .../src/Tabs/TabIndicator/useTabIndicator.ts  |   2 +-
 .../react/src/Tabs/TabPanel/TabPanel.test.tsx |   6 +-
 packages/react/src/Tabs/TabPanel/TabPanel.tsx |  39 +--
 .../src/Tabs/TabPanel/useTabPanel.test.tsx    |   4 +-
 .../react/src/Tabs/TabPanel/useTabPanel.ts    |   2 +-
 .../react/src/Tabs/TabsList/TabsList.test.tsx |   6 +-
 packages/react/src/Tabs/TabsList/TabsList.tsx |  89 ++++---
 .../src/Tabs/TabsList/TabsListContext.ts      |   1 +
 .../src/Tabs/TabsList/TabsListProvider.tsx    |  94 --------
 .../src/Tabs/TabsList/tabsListReducer.ts      |  60 -----
 .../src/Tabs/TabsList/useTabsList.test.tsx    |  18 +-
 .../react/src/Tabs/TabsList/useTabsList.ts    | 223 ++++++------------
 23 files changed, 306 insertions(+), 609 deletions(-)
 delete mode 100644 packages/react/src/Tabs/TabsList/TabsListProvider.tsx
 delete mode 100644 packages/react/src/Tabs/TabsList/tabsListReducer.ts

diff --git a/packages/react/src/Composite/Item/useCompositeItem.ts b/packages/react/src/Composite/Item/useCompositeItem.ts
index 70ab405323..acc082a6db 100644
--- a/packages/react/src/Composite/Item/useCompositeItem.ts
+++ b/packages/react/src/Composite/Item/useCompositeItem.ts
@@ -4,15 +4,19 @@ import { useCompositeRootContext } from '../Root/CompositeRootContext';
 import { useCompositeListItem } from '../List/useCompositeListItem';
 import { mergeReactProps } from '../../utils/mergeReactProps';
 
+export interface UseCompositeItemParameters<Metadata> {
+  metadata?: Metadata;
+}
+
 /**
  *
  * API:
  *
  * - [useCompositeItem API](https://mui.com/base-ui/api/use-composite-item/)
  */
-export function useCompositeItem() {
+export function useCompositeItem<Metadata>(params: UseCompositeItemParameters<Metadata> = {}) {
   const { activeIndex, onActiveIndexChange } = useCompositeRootContext();
-  const { ref, index } = useCompositeListItem();
+  const { ref, index } = useCompositeListItem(params);
   const isActive = activeIndex === index;
 
   const getItemProps = React.useCallback(
diff --git a/packages/react/src/Composite/List/CompositeList.tsx b/packages/react/src/Composite/List/CompositeList.tsx
index 5caa95f889..9fc547cd47 100644
--- a/packages/react/src/Composite/List/CompositeList.tsx
+++ b/packages/react/src/Composite/List/CompositeList.tsx
@@ -23,11 +23,11 @@ function sortByDocumentPosition(a: Node, b: Node) {
   return 0;
 }
 
-type BaseMetadata = { index?: number | null };
+export type BaseMetadata = { index?: number | null };
 
 function areMapsEqual<CustomMetadata>(
-  map1: Map<Node, (CustomMetadata & BaseMetadata) | null>,
-  map2: Map<Node, (CustomMetadata & BaseMetadata) | null>,
+  map1: Map<Node, (BaseMetadata & CustomMetadata) | null>,
+  map2: Map<Node, (BaseMetadata & CustomMetadata) | null>,
 ) {
   if (map1.size !== map2.size) {
     return false;
@@ -53,7 +53,7 @@ function CompositeList<CustomMetadata>(props: CompositeList.Props<CustomMetadata
   const { children, elementsRef, labelsRef, onMapChange } = props;
 
   const [map, setMap] = React.useState(
-    () => new Map<Node, (CustomMetadata & BaseMetadata) | null>(),
+    () => new Map<Node, (BaseMetadata & CustomMetadata) | null>(),
   );
 
   const register = React.useCallback((node: Node, metadata: CustomMetadata) => {
@@ -74,7 +74,7 @@ function CompositeList<CustomMetadata>(props: CompositeList.Props<CustomMetadata
     const nodes = Array.from(newMap.keys()).sort(sortByDocumentPosition);
 
     nodes.forEach((node, index) => {
-      const metadata = map.get(node) ?? ({} as CustomMetadata & BaseMetadata);
+      const metadata = map.get(node) ?? ({} as BaseMetadata & CustomMetadata);
 
       newMap.set(node, { ...metadata, index });
     });
@@ -108,7 +108,7 @@ namespace CompositeList {
      * `useTypeahead`'s `listRef` prop.
      */
     labelsRef?: React.RefObject<Array<string | null>>;
-    onMapChange?: (newMap: Map<Node, (CustomMetadata & BaseMetadata) | null>) => void;
+    onMapChange?: (newMap: Map<Node, (BaseMetadata & CustomMetadata) | null>) => void;
   }
 }
 
diff --git a/packages/react/src/Composite/Root/CompositeRoot.tsx b/packages/react/src/Composite/Root/CompositeRoot.tsx
index 5cdeff18e1..af8e23e1ea 100644
--- a/packages/react/src/Composite/Root/CompositeRoot.tsx
+++ b/packages/react/src/Composite/Root/CompositeRoot.tsx
@@ -26,6 +26,7 @@ const CompositeRoot = React.forwardRef(function CompositeRoot(
     loop,
     cols,
     enableHomeAndEndKeys,
+    onMapChange,
     ...otherProps
   } = props;
 
@@ -57,7 +58,9 @@ const CompositeRoot = React.forwardRef(function CompositeRoot(
 
   return (
     <CompositeRootContext.Provider value={contextValue}>
-      <CompositeList elementsRef={elementsRef}>{renderElement()}</CompositeList>
+      <CompositeList elementsRef={elementsRef} onMapChange={onMapChange}>
+        {renderElement()}
+      </CompositeList>
     </CompositeRootContext.Provider>
   );
 });
@@ -74,6 +77,8 @@ namespace CompositeRoot {
     itemSizes?: Dimensions[];
     dense?: boolean;
     enableHomeAndEndKeys?: boolean;
+    // TODO: can't pass a generic <CustomMetadata> into forwardRef?
+    onMapChange?: (newMap: Map<Node, any>) => void;
   }
 }
 
diff --git a/packages/react/src/Tabs/Root/TabsRoot.tsx b/packages/react/src/Tabs/Root/TabsRoot.tsx
index 86581f54ae..6649875ac0 100644
--- a/packages/react/src/Tabs/Root/TabsRoot.tsx
+++ b/packages/react/src/Tabs/Root/TabsRoot.tsx
@@ -1,6 +1,5 @@
 'use client';
 import * as React from 'react';
-import PropTypes from 'prop-types';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import type { BaseUIComponentProps } from '../../utils/types';
 import { CompositeList } from '../../Composite/List/CompositeList';
@@ -27,7 +26,7 @@ const TabsRoot = React.forwardRef(function TabsRoot(
     className,
     defaultValue,
     direction: directionProp = 'ltr',
-    onValueChange,
+    onValueChange: onValueChangeProp,
     orientation = 'horizontal',
     render,
     value: valueProp,
@@ -37,10 +36,11 @@ const TabsRoot = React.forwardRef(function TabsRoot(
   const {
     getRootProps,
     direction,
-    getTabId,
+    getTabIdByPanelValueOrIndex,
     getTabPanelIdByTabValueOrIndex,
-    onSelected,
-    registerTabIdLookup,
+    onValueChange,
+    registerGetTabIdByPanelValueOrIndexFn,
+    setTabMap,
     setTabPanelMap,
     tabActivationDirection,
     tabPanelRefs,
@@ -48,28 +48,30 @@ const TabsRoot = React.forwardRef(function TabsRoot(
   } = useTabsRoot({
     value: valueProp,
     defaultValue,
-    onValueChange,
+    onValueChange: onValueChangeProp,
     direction: directionProp,
   });
 
   const tabsContextValue = React.useMemo(
     () => ({
       direction,
-      getTabId,
+      getTabIdByPanelValueOrIndex,
       getTabPanelIdByTabValueOrIndex,
-      onSelected,
+      onValueChange,
       orientation,
-      registerTabIdLookup,
+      registerGetTabIdByPanelValueOrIndexFn,
+      setTabMap,
       tabActivationDirection,
       value,
     }),
     [
       direction,
-      getTabId,
+      getTabIdByPanelValueOrIndex,
       getTabPanelIdByTabValueOrIndex,
-      onSelected,
+      onValueChange,
       orientation,
-      registerTabIdLookup,
+      registerGetTabIdByPanelValueOrIndexFn,
+      setTabMap,
       tabActivationDirection,
       value,
     ],
@@ -100,6 +102,8 @@ const TabsRoot = React.forwardRef(function TabsRoot(
   );
 });
 
+export { TabsRoot };
+
 export type TabsOrientation = 'horizontal' | 'vertical';
 export type TabsDirection = 'ltr' | 'rtl';
 export type TabActivationDirection = 'left' | 'right' | 'up' | 'down' | 'none';
@@ -137,47 +141,3 @@ namespace TabsRoot {
     onValueChange?: (value: any | null, event?: Event) => void;
   }
 }
-
-TabsRoot.propTypes /* remove-proptypes */ = {
-  // ┌────────────────────────────── Warning ──────────────────────────────┐
-  // │ These PropTypes are generated from the TypeScript type definitions. │
-  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
-  // └─────────────────────────────────────────────────────────────────────┘
-  /**
-   * @ignore
-   */
-  children: PropTypes.node,
-  /**
-   * Class names applied to the element or a function that returns them based on the component's state.
-   */
-  className: PropTypes.oneOfType([PropTypes.func, PropTypes.string]),
-  /**
-   * The default value. Use when the component is not controlled.
-   */
-  defaultValue: PropTypes.any,
-  /**
-   * The direction of the text.
-   * @default 'ltr'
-   */
-  direction: PropTypes.oneOf(['ltr', 'rtl']),
-  /**
-   * Callback invoked when new value is being set.
-   */
-  onValueChange: PropTypes.func,
-  /**
-   * The component orientation (layout flow direction).
-   * @default 'horizontal'
-   */
-  orientation: PropTypes.oneOf(['horizontal', 'vertical']),
-  /**
-   * A function to customize rendering of the component.
-   */
-  render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
-  /**
-   * The value of the currently selected `Tab`.
-   * If you don't want any selected `Tab`, you can set this prop to `null`.
-   */
-  value: PropTypes.any,
-} as any;
-
-export { TabsRoot };
diff --git a/packages/react/src/Tabs/Root/TabsRootContext.ts b/packages/react/src/Tabs/Root/TabsRootContext.ts
index 6224a0beb9..464746ca7f 100644
--- a/packages/react/src/Tabs/Root/TabsRootContext.ts
+++ b/packages/react/src/Tabs/Root/TabsRootContext.ts
@@ -1,5 +1,6 @@
 'use client';
 import * as React from 'react';
+import { type TabMetadata } from '../Tab/useTab';
 import { type TabActivationDirection } from './TabsRoot';
 
 export interface TabsRootContext {
@@ -10,10 +11,10 @@ export interface TabsRootContext {
   /**
    * Callback for setting new value.
    */
-  onSelected: (
-    event: Event | undefined,
+  onValueChange: (
     value: any | null,
     activationDirection: TabActivationDirection,
+    event: Event,
   ) => void;
   /**
    * The component orientation (layout flow direction).
@@ -26,17 +27,18 @@ export interface TabsRootContext {
   /**
    * Registers a function that returns the id of the tab with the given value.
    */
-  registerTabIdLookup: (lookupFunction: (id: any) => string | undefined) => void;
+  // registerGetTabIdByPanelValueOrIndexFn?: (lookupFunction: (id: any) => string | undefined) => void;
   /**
    * Gets the id of the tab with the given value.
-   * @param value Value to find the tab for.
+   * @param {any | undefined} value Value to find the tab for.
    */
-  getTabId: (value: any) => string | undefined;
+  getTabIdByPanelValueOrIndex: (panelValue: any | undefined, index: number) => string | undefined;
   /**
    * Gets the id of the tab panel with the given value.
-   * @param value Value to find the tab panel for.
+   * @param {any | undefined} value Value to find the tab panel for.
    */
   getTabPanelIdByTabValueOrIndex: (tabValue: any, index: number) => string | undefined;
+  setTabMap: (map: Map<Node, (TabMetadata & { index?: number | null }) | null>) => void;
   /**
    * The position of the active tab relative to the previously active tab.
    */
diff --git a/packages/react/src/Tabs/Root/useTabsRoot.ts b/packages/react/src/Tabs/Root/useTabsRoot.ts
index 72ccf83463..49ef80c611 100644
--- a/packages/react/src/Tabs/Root/useTabsRoot.ts
+++ b/packages/react/src/Tabs/Root/useTabsRoot.ts
@@ -3,21 +3,21 @@ import * as React from 'react';
 import { mergeReactProps } from '../../utils/mergeReactProps';
 import { useControlled } from '../../utils/useControlled';
 import type { TabPanelMetadata } from '../TabPanel/useTabPanel';
+import type { TabMetadata } from '../Tab/useTab';
 import type { TabActivationDirection } from './TabsRoot';
 
-export interface TabMetadata {
-  disabled: boolean;
-  id: string | undefined;
-  ref: React.RefObject<HTMLElement | null>;
-}
-
 type IdLookupFunction = (id: any) => string | undefined;
 
 function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValue {
-  const { value: valueProp, defaultValue, onValueChange, direction = 'ltr' } = parameters;
+  const {
+    value: valueProp,
+    defaultValue,
+    onValueChange: onValueChangeProp,
+    direction = 'ltr',
+  } = parameters;
 
   const tabPanelRefs = React.useRef<(HTMLElement | null)[]>([]);
-  const getTabIdByPanelValueRef = React.useRef<IdLookupFunction>(() => undefined);
+  const getTabIdByPanelValueOrIndexRef = React.useRef<IdLookupFunction>(() => undefined);
 
   const [value, setValue] = useControlled({
     controlled: valueProp,
@@ -29,23 +29,27 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
   const [tabPanelMap, setTabPanelMap] = React.useState(
     () => new Map<Node, (TabPanelMetadata & { index?: number | null }) | null>(),
   );
+  const [tabMap, setTabMap] = React.useState(
+    () => new Map<Node, (TabMetadata & { index?: number | null }) | null>(),
+  );
 
   const [tabActivationDirection, setTabActivationDirection] =
     React.useState<TabActivationDirection>('none');
 
-  const onSelected = React.useCallback(
+  const onValueChange = React.useCallback(
     (
-      event: Event | undefined,
       newValue: any | null,
       activationDirection: TabActivationDirection,
+      event: Event | undefined,
     ) => {
       setValue(newValue);
       setTabActivationDirection(activationDirection);
-      onValueChange?.(newValue, event ?? undefined);
+      onValueChangeProp?.(newValue, event);
     },
-    [onValueChange, setValue],
+    [onValueChangeProp, setValue],
   );
 
+  // get the `id` attribute of <Tabs.Panel> to set as the value of `aria-controls` on <Tabs.Tab>
   const getTabPanelIdByTabValueOrIndex = React.useCallback(
     (tabValue: any | undefined, index: number) => {
       if (tabValue === undefined && index < 0) {
@@ -73,13 +77,33 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
     [tabPanelMap],
   );
 
-  const getTabIdByPanelValue = React.useCallback((tabPanelValue: any) => {
-    return getTabIdByPanelValueRef.current(tabPanelValue);
-  }, []);
+  // get the `id` attribute of <Tabs.Tab> to set as the value of `aria-labelledby` on <Tabs.Panel>
+  const getTabIdByPanelValueOrIndex = React.useCallback(
+    (tabPanelValue: any | undefined, index: number) => {
+      // return getTabIdByPanelValueOrIndexRef.current(tabPanelValue);
+      for (const tabMetadata of tabMap.values()) {
+        console.log(tabPanelValue, index, tabMetadata);
+      }
+      return undefined;
+    },
+    [tabMap],
+  );
+
+  // used as a param for `useActivationDirectionDetector`
+  const getTabElementByPanelValueOrIndex = React.useCallback(
+    (tabPanelValue: any | undefined, index: number) => {
+      // return getTabIdByPanelValueOrIndexRef.current(tabPanelValue);
+      return null;
+    },
+    [],
+  );
 
-  const registerTabIdLookup = React.useCallback((lookupFunction: IdLookupFunction) => {
-    getTabIdByPanelValueRef.current = lookupFunction;
-  }, []);
+  const registerGetTabIdByPanelValueOrIndexFn = React.useCallback(
+    (lookupFunction: IdLookupFunction) => {
+      getTabIdByPanelValueOrIndexRef.current = lookupFunction;
+    },
+    [],
+  );
 
   const getRootProps: useTabsRoot.ReturnValue['getRootProps'] = React.useCallback(
     (otherProps = {}) =>
@@ -92,10 +116,12 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
   return {
     getRootProps,
     direction,
-    getTabId: getTabIdByPanelValue,
+    getTabElementByPanelValueOrIndex,
+    getTabIdByPanelValueOrIndex,
     getTabPanelIdByTabValueOrIndex,
-    onSelected,
-    registerTabIdLookup,
+    onValueChange,
+    registerGetTabIdByPanelValueOrIndexFn,
+    setTabMap,
     setTabPanelMap,
     tabActivationDirection,
     tabPanelRefs,
@@ -133,32 +159,38 @@ namespace useTabsRoot {
      * The direction of the text.
      */
     direction: 'ltr' | 'rtl';
+    getTabElementByPanelValueOrIndex: (
+      panelValue: any | undefined,
+      index: number,
+    ) => HTMLElement | null;
     /**
      * Gets the id of the tab with the given value.
      * @param value Value to find the tab for.
      */
-    getTabId: (value: any) => string | undefined;
+    getTabIdByPanelValueOrIndex: (panelValue: any | undefined, index: number) => string | undefined;
     /**
      * Gets the id of the tab panel with the given value.
      * @param value Value to find the tab panel for.
      */
     getTabPanelIdByTabValueOrIndex: (
       tabValue: any | undefined,
-      tabIndex: number,
+      index: number,
     ) => string | undefined;
-
     /**
      * Callback for setting new value.
      */
-    onSelected: (
-      event: React.SyntheticEvent | null,
+    onValueChange: (
       value: any | null,
       activationDirection: TabActivationDirection,
+      event: Event,
     ) => void;
     /**
      * Registers a function that returns the id of the tab with the given value.
      */
-    registerTabIdLookup: (lookupFunction: (id: any) => string | undefined) => void;
+    registerGetTabIdByPanelValueOrIndexFn: (
+      lookupFunction: (id: any) => string | undefined,
+    ) => void;
+    setTabMap: (map: Map<Node, (TabMetadata & { index?: number | null }) | null>) => void;
     setTabPanelMap: (map: Map<Node, (TabPanelMetadata & { index?: number | null }) | null>) => void;
     /**
      * The position of the active tab relative to the previously active tab.
@@ -172,4 +204,4 @@ namespace useTabsRoot {
   }
 }
 
-export { useTabsRoot };
+export { useTabsRoot, TabMetadata };
diff --git a/packages/react/src/Tabs/Tab/Tab.test.tsx b/packages/react/src/Tabs/Tab/Tab.test.tsx
index e6100173dc..8f76696e64 100644
--- a/packages/react/src/Tabs/Tab/Tab.test.tsx
+++ b/packages/react/src/Tabs/Tab/Tab.test.tsx
@@ -1,22 +1,17 @@
 import * as React from 'react';
 import { Tabs } from '@base-ui-components/react/Tabs';
 import { createRenderer, describeConformance } from '#test-utils';
-import { TabsListProviderValue, TabsListProvider } from '../TabsList/TabsListProvider';
+import { NOOP } from '../../utils/noop';
 import { TabsRootContext } from '../Root/TabsRootContext';
+import { TabsListContext } from '../TabsList/TabsListContext';
 
 describe('<Tabs.Tab />', () => {
   const { render } = createRenderer();
 
-  const testTabsListContext: TabsListProviderValue = {
-    dispatch: () => {},
-    registerItem: () => ({ id: 0, deregister: () => {} }),
-    getItemIndex: () => 0,
-    totalSubitemCount: 1,
-    getItemState() {
-      return { disabled: false, highlighted: false, selected: false, focusable: true, index: 0 };
-    },
+  const testTabsListContext: TabsListContext = {
     activateOnFocus: true,
     getTabElement: () => null,
+    onTabActivation: NOOP,
     tabsListRef: {
       current: null,
     },
@@ -24,9 +19,9 @@ describe('<Tabs.Tab />', () => {
 
   const testTabsContext: TabsRootContext = {
     value: 0,
-    onSelected() {},
-    registerTabIdLookup() {},
-    getTabId: () => '',
+    onValueChange() {},
+    setTabMap() {},
+    getTabIdByPanelValueOrIndex: () => '',
     getTabPanelIdByTabValueOrIndex: () => '',
     orientation: 'horizontal',
     direction: 'ltr',
@@ -37,7 +32,7 @@ describe('<Tabs.Tab />', () => {
     render: (node) => {
       return render(
         <TabsRootContext.Provider value={testTabsContext}>
-          <TabsListProvider value={testTabsListContext}>{node}</TabsListProvider>
+          <TabsListContext.Provider value={testTabsListContext}>{node}</TabsListContext.Provider>
         </TabsRootContext.Provider>,
       );
     },
diff --git a/packages/react/src/Tabs/Tab/Tab.tsx b/packages/react/src/Tabs/Tab/Tab.tsx
index eda994f345..7bbedfc59b 100644
--- a/packages/react/src/Tabs/Tab/Tab.tsx
+++ b/packages/react/src/Tabs/Tab/Tab.tsx
@@ -1,11 +1,12 @@
 'use client';
 import * as React from 'react';
-import PropTypes from 'prop-types';
 import { useTab } from './useTab';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import type { BaseUIComponentProps } from '../../utils/types';
+import { useCompositeRootContext } from '../../Composite/Root/CompositeRootContext';
 import type { TabsOrientation } from '../Root/TabsRoot';
 import { useTabsRootContext } from '../Root/TabsRootContext';
+import { useTabsListContext } from '../TabsList/TabsListContext';
 
 /**
  *
@@ -21,7 +22,7 @@ const Tab = React.forwardRef(function Tab(
   props: Tab.Props,
   forwardedRef: React.ForwardedRef<Element>,
 ) {
-  const { className, disabled = false, render, value: valueProp, ...other } = props;
+  const { className, disabled = false, render, value: valueProp, id: idProp, ...other } = props;
 
   const {
     value: selectedValue,
@@ -29,20 +30,32 @@ const Tab = React.forwardRef(function Tab(
     orientation,
   } = useTabsRootContext();
 
-  const { selected, getRootProps } = useTab({
-    ...props,
+  const { activateOnFocus, onTabActivation } = useTabsListContext();
+
+  // this is the context of TabsList
+  const { activeIndex } = useCompositeRootContext();
+  // console.log('activeIndex', activeIndex);
+
+  const { getRootProps, index, selected } = useTab({
+    disabled,
     getTabPanelIdByTabValueOrIndex,
+    id: idProp,
     isSelected: valueProp === selectedValue,
+    onTabActivation,
     rootRef: forwardedRef,
+    value: valueProp,
   });
 
+  const highlighted = index > -1 && index === activeIndex;
+
   const ownerState: Tab.OwnerState = React.useMemo(
     () => ({
       disabled,
+      highlighted,
       selected,
       orientation,
     }),
-    [disabled, selected, orientation],
+    [disabled, highlighted, selected, orientation],
   );
 
   const { renderElement } = useComponentRenderer({
@@ -56,6 +69,8 @@ const Tab = React.forwardRef(function Tab(
   return renderElement();
 });
 
+export { Tab };
+
 namespace Tab {
   export interface Props extends BaseUIComponentProps<'button', Tab.OwnerState> {
     /**
@@ -70,32 +85,3 @@ namespace Tab {
     orientation: TabsOrientation;
   }
 }
-
-Tab.propTypes /* remove-proptypes */ = {
-  // ┌────────────────────────────── Warning ──────────────────────────────┐
-  // │ These PropTypes are generated from the TypeScript type definitions. │
-  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
-  // └─────────────────────────────────────────────────────────────────────┘
-  /**
-   * @ignore
-   */
-  children: PropTypes.node,
-  /**
-   * Class names applied to the element or a function that returns them based on the component's state.
-   */
-  className: PropTypes.oneOfType([PropTypes.func, PropTypes.string]),
-  /**
-   * @ignore
-   */
-  disabled: PropTypes.bool,
-  /**
-   * A function to customize rendering of the component.
-   */
-  render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
-  /**
-   * You can provide your own value. Otherwise, it falls back to the child position index.
-   */
-  value: PropTypes.any,
-} as any;
-
-export { Tab };
diff --git a/packages/react/src/Tabs/Tab/useTab.test.tsx b/packages/react/src/Tabs/Tab/useTab.test.tsx
index fd4fe50130..fb8ae31b21 100644
--- a/packages/react/src/Tabs/Tab/useTab.test.tsx
+++ b/packages/react/src/Tabs/Tab/useTab.test.tsx
@@ -3,6 +3,7 @@ import { expect } from 'chai';
 import { spy } from 'sinon';
 import { createRenderer, screen, fireEvent } from '@mui/internal-test-utils';
 import { Tabs } from '@base-ui-components/react/Tabs';
+import { NOOP } from '../../utils/noop';
 import { useTab } from './useTab';
 
 describe('useTab', () => {
@@ -15,6 +16,7 @@ describe('useTab', () => {
         const { getRootProps } = useTab({
           rootRef,
           isSelected: true,
+          onTabActivation: NOOP,
           getTabPanelIdByTabValueOrIndex: () => undefined,
         });
         return <button {...getRootProps()} />;
@@ -44,6 +46,7 @@ describe('useTab', () => {
         const { getRootProps } = useTab({
           rootRef,
           isSelected: true,
+          onTabActivation: NOOP,
           getTabPanelIdByTabValueOrIndex: () => undefined,
         });
         return (
diff --git a/packages/react/src/Tabs/Tab/useTab.ts b/packages/react/src/Tabs/Tab/useTab.ts
index c54b4a1946..00b7e0aa1b 100644
--- a/packages/react/src/Tabs/Tab/useTab.ts
+++ b/packages/react/src/Tabs/Tab/useTab.ts
@@ -1,50 +1,51 @@
 'use client';
 import * as React from 'react';
-import type { TabsRootContext } from '../Root/TabsRootContext';
-import { TabMetadata } from '../Root/useTabsRoot';
-import { useCompoundItem } from '../../useCompound';
-import { useListItem } from '../../useList';
-import { useButton } from '../../useButton';
-import { useId } from '../../utils/useId';
-import { useForkRef } from '../../utils/useForkRef';
 import { mergeReactProps } from '../../utils/mergeReactProps';
+import { useForkRef } from '../../utils/useForkRef';
+import { useId } from '../../utils/useId';
+import { useButton } from '../../useButton';
+import { useCompositeItem } from '../../Composite/Item/useCompositeItem';
+import type { TabsRootContext } from '../Root/TabsRootContext';
+import type { useTabsList } from '../TabsList/useTabsList';
 
-function tabValueGenerator(otherTabValues: Set<any>) {
-  return otherTabValues.size;
+export interface TabMetadata {
+  disabled: boolean;
+  id: string | undefined;
 }
 
 function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
   const {
-    value: valueParam,
-    rootRef: externalRef,
     disabled = false,
     getTabPanelIdByTabValueOrIndex,
     id: idParam,
     isSelected,
+    onTabActivation,
+    rootRef: externalRef,
+    value: valueParam,
   } = parameters;
 
-  const tabRef = React.useRef<HTMLElement>(null);
   const id = useId(idParam);
 
-  const tabMetadata = React.useMemo(() => ({ disabled, ref: tabRef, id }), [disabled, tabRef, id]);
+  const tabMetadata = React.useMemo(
+    () => ({ disabled, id, value: valueParam }),
+    [disabled, id, valueParam],
+  );
 
   const {
-    id: value,
+    getItemProps,
+    ref: compositeItemRef,
     index,
-    totalItemCount: totalTabsCount,
-  } = useCompoundItem<any, TabMetadata>(valueParam ?? tabValueGenerator, tabMetadata);
+  } = useCompositeItem<TabMetadata>({ metadata: tabMetadata });
 
-  const { getRootProps: getListItemProps, selected } = useListItem({
-    item: value,
-  });
+  const tabValue = valueParam ?? index;
 
-  const { getButtonProps, buttonRef: buttonRefHandler } = useButton({
+  const { getButtonProps, buttonRef } = useButton({
     disabled,
     focusableWhenDisabled: true,
     type: 'button',
   });
 
-  const handleRef = useForkRef(tabRef, externalRef, buttonRefHandler);
+  const handleRef = useForkRef(compositeItemRef, buttonRef, externalRef);
 
   const tabPanelId = index > -1 ? getTabPanelIdByTabValueOrIndex(valueParam, index) : undefined;
 
@@ -56,15 +57,18 @@ function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
           {
             role: 'tab',
             'aria-controls': tabPanelId,
-            'aria-selected': selected,
+            'aria-selected': false,
             id,
             ref: handleRef,
+            onClick(event) {
+              onTabActivation(tabValue, event.nativeEvent);
+            },
           },
-          mergeReactProps(getListItemProps(), getButtonProps()),
+          mergeReactProps(getItemProps(), getButtonProps()),
         ),
       );
     },
-    [getButtonProps, getListItemProps, handleRef, id, selected, tabPanelId],
+    [getButtonProps, getItemProps, handleRef, id, onTabActivation, tabPanelId, tabValue],
   );
 
   return {
@@ -73,13 +77,16 @@ function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
     rootRef: handleRef,
     // the `selected` state isn't set on the server (it relies on effects to be calculated),
     // so we fall back to checking the `value` prop with the selectedValue from the TabsContext
-    selected: selected || isSelected,
-    totalTabsCount,
+    selected: /* selected || */ isSelected,
+    // TODO: recalculate this using Composite stuff, but is it really needed?
+    totalTabsCount: -1,
   };
 }
 
 namespace useTab {
-  export interface Parameters extends Pick<TabsRootContext, 'getTabPanelIdByTabValueOrIndex'> {
+  export interface Parameters
+    extends Pick<TabsRootContext, 'getTabPanelIdByTabValueOrIndex'>,
+      Pick<useTabsList.ReturnValue, 'onTabActivation'> {
     /**
      * The value of the tab.
      * It's used to associate the tab with a tab panel(s) with the same value.
diff --git a/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx b/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx
index 7f1a0f5ace..c3bd2a5c6b 100644
--- a/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx
+++ b/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx
@@ -1,6 +1,5 @@
 'use client';
 import * as React from 'react';
-import PropTypes from 'prop-types';
 import { ActiveTabPosition, useTabIndicator } from './useTabIndicator';
 import { script as prehydrationScript } from './prehydrationScript.min';
 import type { TabsDirection, TabsOrientation, TabsRoot } from '../Root/TabsRoot';
@@ -88,6 +87,8 @@ const TabIndicator = React.forwardRef<HTMLSpanElement, TabIndicator.Props>(
   },
 );
 
+export { TabIndicator };
+
 namespace TabIndicator {
   export interface OwnerState extends TabsRoot.OwnerState {
     selectedTabPosition: ActiveTabPosition | null;
@@ -105,31 +106,3 @@ namespace TabIndicator {
     renderBeforeHydration?: boolean;
   }
 }
-
-TabIndicator.propTypes /* remove-proptypes */ = {
-  // ┌────────────────────────────── Warning ──────────────────────────────┐
-  // │ These PropTypes are generated from the TypeScript type definitions. │
-  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
-  // └─────────────────────────────────────────────────────────────────────┘
-  /**
-   * @ignore
-   */
-  children: PropTypes.node,
-  /**
-   * Class names applied to the element or a function that returns them based on the component's state.
-   */
-  className: PropTypes.oneOfType([PropTypes.func, PropTypes.string]),
-  /**
-   * A function to customize rendering of the component.
-   */
-  render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
-  /**
-   * If `true`, the indicator will include code to render itself before React hydrates.
-   * This will minimize the time the indicator is not visible after the SSR-generated content is downloaded.
-   *
-   * @default false
-   */
-  renderBeforeHydration: PropTypes.bool,
-} as any;
-
-export { TabIndicator };
diff --git a/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts b/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts
index b5da1e42fa..3d49a93d36 100644
--- a/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts
+++ b/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts
@@ -41,7 +41,7 @@ export function useTabIndicator(
   let isTabSelected = false;
 
   if (value != null && tabsListRef.current != null) {
-    const selectedTabElement = getTabElement(value);
+    const selectedTabElement = null; /*getTabElement(value)*/
     isTabSelected = true;
 
     if (selectedTabElement != null) {
diff --git a/packages/react/src/Tabs/TabPanel/TabPanel.test.tsx b/packages/react/src/Tabs/TabPanel/TabPanel.test.tsx
index 161aee47e4..026145ceb6 100644
--- a/packages/react/src/Tabs/TabPanel/TabPanel.test.tsx
+++ b/packages/react/src/Tabs/TabPanel/TabPanel.test.tsx
@@ -15,9 +15,9 @@ describe('<Tabs.Panel />', () => {
 
   const tabsContextDefaultValue: TabsRootContext = {
     value: '1',
-    onSelected: () => {},
-    registerTabIdLookup() {},
-    getTabId: () => '',
+    onValueChange: () => {},
+    setTabMap() {},
+    getTabIdByPanelValueOrIndex: () => '',
     getTabPanelIdByTabValueOrIndex: () => '',
     direction: 'ltr',
     orientation: 'horizontal',
diff --git a/packages/react/src/Tabs/TabPanel/TabPanel.tsx b/packages/react/src/Tabs/TabPanel/TabPanel.tsx
index 87e14938e6..61663cdef6 100644
--- a/packages/react/src/Tabs/TabPanel/TabPanel.tsx
+++ b/packages/react/src/Tabs/TabPanel/TabPanel.tsx
@@ -1,6 +1,5 @@
 'use client';
 import * as React from 'react';
-import PropTypes from 'prop-types';
 import { useTabPanel } from './useTabPanel';
 import { tabsStyleHookMapping } from '../Root/styleHooks';
 import { useTabsRootContext } from '../Root/TabsRootContext';
@@ -26,14 +25,14 @@ const TabPanel = React.forwardRef(function TabPanel(
 
   const {
     value: selectedValue,
-    getTabId,
+    getTabIdByPanelValueOrIndex,
     orientation,
     direction,
     tabActivationDirection,
   } = useTabsRootContext();
 
   const { hidden, getRootProps } = useTabPanel({
-    getTabId,
+    getTabIdByPanelValueOrIndex,
     rootRef: forwardedRef,
     selectedValue,
     value: valueProp,
@@ -61,6 +60,8 @@ const TabPanel = React.forwardRef(function TabPanel(
   return renderElement();
 });
 
+export { TabPanel };
+
 namespace TabPanel {
   export interface OwnerState extends TabsRoot.OwnerState {
     hidden: boolean;
@@ -80,35 +81,3 @@ namespace TabPanel {
     keepMounted?: boolean;
   }
 }
-
-TabPanel.propTypes /* remove-proptypes */ = {
-  // ┌────────────────────────────── Warning ──────────────────────────────┐
-  // │ These PropTypes are generated from the TypeScript type definitions. │
-  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
-  // └─────────────────────────────────────────────────────────────────────┘
-  /**
-   * @ignore
-   */
-  children: PropTypes.node,
-  /**
-   * Class names applied to the element or a function that returns them based on the component's state.
-   */
-  className: PropTypes.oneOfType([PropTypes.func, PropTypes.string]),
-  /**
-   * If `true`, keeps the contents of the hidden TabPanel in the DOM.
-   * @default false
-   */
-  keepMounted: PropTypes.bool,
-  /**
-   * A function to customize rendering of the component.
-   */
-  render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
-  /**
-   * The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected.
-   * If not provided, it will fall back to the index of the panel.
-   * It is recommended to explicitly provide it, as it's required for the tab panel to be rendered on the server.
-   */
-  value: PropTypes.any,
-} as any;
-
-export { TabPanel };
diff --git a/packages/react/src/Tabs/TabPanel/useTabPanel.test.tsx b/packages/react/src/Tabs/TabPanel/useTabPanel.test.tsx
index 9973048be4..f5d5df7ed2 100644
--- a/packages/react/src/Tabs/TabPanel/useTabPanel.test.tsx
+++ b/packages/react/src/Tabs/TabPanel/useTabPanel.test.tsx
@@ -13,7 +13,7 @@ describe('useTabPanel', () => {
       const rootRef = React.createRef<HTMLDivElement>();
       function TestTabPanel() {
         const { getRootProps } = useTabPanel({
-          getTabId: () => undefined,
+          getTabIdByPanelValueOrIndex: () => undefined,
           id: 'test-tabpanel',
           rootRef,
           selectedValue: 0,
@@ -42,7 +42,7 @@ describe('useTabPanel', () => {
 
       function TestTabPanel() {
         const { getRootProps } = useTabPanel({
-          getTabId: () => undefined,
+          getTabIdByPanelValueOrIndex: () => undefined,
           id: 'test-tabpanel',
           rootRef,
           selectedValue: 0,
diff --git a/packages/react/src/Tabs/TabPanel/useTabPanel.ts b/packages/react/src/Tabs/TabPanel/useTabPanel.ts
index 65d288dfa8..c199e284e7 100644
--- a/packages/react/src/Tabs/TabPanel/useTabPanel.ts
+++ b/packages/react/src/Tabs/TabPanel/useTabPanel.ts
@@ -81,7 +81,7 @@ function useTabPanel(parameters: useTabPanel.Parameters): useTabPanel.ReturnValu
 }
 
 namespace useTabPanel {
-  export interface Parameters extends Pick<TabsRootContext, 'getTabId'> {
+  export interface Parameters extends Pick<TabsRootContext, 'getTabIdByPanelValueOrIndex'> {
     /**
      * The id of the TabPanel.
      */
diff --git a/packages/react/src/Tabs/TabsList/TabsList.test.tsx b/packages/react/src/Tabs/TabsList/TabsList.test.tsx
index d4d5c6ba6f..1d9c30afa5 100644
--- a/packages/react/src/Tabs/TabsList/TabsList.test.tsx
+++ b/packages/react/src/Tabs/TabsList/TabsList.test.tsx
@@ -14,9 +14,9 @@ describe('<Tabs.List />', () => {
         <TabsRootContext.Provider
           value={{
             value: '1',
-            onSelected: () => {},
-            registerTabIdLookup() {},
-            getTabId: () => '',
+            onValueChange: () => {},
+            setTabMap() {},
+            getTabIdByPanelValueOrIndex: () => '',
             getTabPanelIdByTabValueOrIndex: () => '',
             orientation: 'horizontal',
             direction: 'ltr',
diff --git a/packages/react/src/Tabs/TabsList/TabsList.tsx b/packages/react/src/Tabs/TabsList/TabsList.tsx
index 3decca92a8..a8c35df243 100644
--- a/packages/react/src/Tabs/TabsList/TabsList.tsx
+++ b/packages/react/src/Tabs/TabsList/TabsList.tsx
@@ -1,13 +1,13 @@
 'use client';
 import * as React from 'react';
-import PropTypes from 'prop-types';
-import { useTabsList } from './useTabsList';
-import { TabsListProvider } from './TabsListProvider';
+import { BaseUIComponentProps } from '../../utils/types';
+import { useComponentRenderer } from '../../utils/useComponentRenderer';
+import { CompositeRoot } from '../../Composite/Root/CompositeRoot';
 import { tabsStyleHookMapping } from '../Root/styleHooks';
 import { useTabsRootContext } from '../Root/TabsRootContext';
-import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import { TabsRoot } from '../Root/TabsRoot';
-import { BaseUIComponentProps } from '../../utils/types';
+import { useTabsList } from './useTabsList';
+import { TabsListContext } from './TabsListContext';
 
 /**
  *
@@ -27,21 +27,21 @@ const TabsList = React.forwardRef(function TabsList(
 
   const {
     direction = 'ltr',
-    onSelected,
+    onValueChange,
     orientation = 'horizontal',
     value,
-    registerTabIdLookup,
+    setTabMap,
     tabActivationDirection,
   } = useTabsRootContext();
 
-  const { getRootProps, contextValue } = useTabsList({
-    activateOnFocus,
-    direction,
-    loop,
-    onSelected,
+  const tabsListRef = React.useRef<HTMLElement>(null);
+
+  const { getRootProps, onTabActivation } = useTabsList({
+    onValueChange,
     orientation,
-    registerTabIdLookup,
     rootRef: forwardedRef,
+    setTabMap,
+    tabsListRef,
     value,
   });
 
@@ -63,9 +63,36 @@ const TabsList = React.forwardRef(function TabsList(
     customStyleHookMapping: tabsStyleHookMapping,
   });
 
-  return <TabsListProvider value={contextValue}>{renderElement()}</TabsListProvider>;
+  const tabsListContextValue = React.useMemo(
+    () => ({
+      activateOnFocus,
+      onTabActivation,
+      // getTabElement,
+      value,
+      tabsListRef,
+    }),
+    [
+      activateOnFocus,
+      onTabActivation,
+      // getTabElement,
+      value,
+      tabsListRef,
+    ],
+  );
+
+  return (
+    <TabsListContext.Provider value={tabsListContextValue}>
+      {/*
+        TODO: pass `direction` prop to `rtl` prop of CompositeRoot when
+        https://github.com/mui/base-ui/pull/763 is merged
+       */}
+      <CompositeRoot loop={loop} onMapChange={setTabMap} render={renderElement()} />
+    </TabsListContext.Provider>
+  );
 });
 
+export { TabsList };
+
 namespace TabsList {
   export type OwnerState = TabsRoot.OwnerState;
 
@@ -85,37 +112,3 @@ namespace TabsList {
     loop?: boolean;
   }
 }
-
-TabsList.propTypes /* remove-proptypes */ = {
-  // ┌────────────────────────────── Warning ──────────────────────────────┐
-  // │ These PropTypes are generated from the TypeScript type definitions. │
-  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
-  // └─────────────────────────────────────────────────────────────────────┘
-  /**
-   * If `true`, the tab will be activated whenever it is focused.
-   * Otherwise, it has to be activated by clicking or pressing the Enter or Space key.
-   *
-   * @default true
-   */
-  activateOnFocus: PropTypes.bool,
-  /**
-   * @ignore
-   */
-  children: PropTypes.node,
-  /**
-   * Class names applied to the element or a function that returns them based on the component's state.
-   */
-  className: PropTypes.oneOfType([PropTypes.func, PropTypes.string]),
-  /**
-   * If `true`, using keyboard navigation will wrap focus to the other end of the list once the end is reached.
-   *
-   * @default true
-   */
-  loop: PropTypes.bool,
-  /**
-   * A function to customize rendering of the component.
-   */
-  render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
-} as any;
-
-export { TabsList };
diff --git a/packages/react/src/Tabs/TabsList/TabsListContext.ts b/packages/react/src/Tabs/TabsList/TabsListContext.ts
index fa31ac8a92..740d66a51f 100644
--- a/packages/react/src/Tabs/TabsList/TabsListContext.ts
+++ b/packages/react/src/Tabs/TabsList/TabsListContext.ts
@@ -4,6 +4,7 @@ import * as React from 'react';
 export interface TabsListContext {
   activateOnFocus: boolean;
   getTabElement: (value: any) => HTMLElement | null;
+  onTabActivation: (newValue: any, event: Event) => void;
   tabsListRef: React.RefObject<HTMLElement | null>;
 }
 
diff --git a/packages/react/src/Tabs/TabsList/TabsListProvider.tsx b/packages/react/src/Tabs/TabsList/TabsListProvider.tsx
deleted file mode 100644
index 3567bc5205..0000000000
--- a/packages/react/src/Tabs/TabsList/TabsListProvider.tsx
+++ /dev/null
@@ -1,94 +0,0 @@
-'use client';
-import * as React from 'react';
-import PropTypes from 'prop-types';
-import { TabsListContext } from './TabsListContext';
-import { TabMetadata } from '../Root/useTabsRoot';
-import { ListContext, ListContextValue } from '../../useList/ListContext';
-import { CompoundComponentContext, CompoundComponentContextValue } from '../../useCompound';
-import { refType } from '../../utils/proptypes';
-
-export type TabsListProviderValue = CompoundComponentContextValue<any, TabMetadata> &
-  ListContextValue<any> &
-  TabsListContext;
-
-export interface TabsListProviderProps {
-  value: TabsListProviderValue;
-  children: React.ReactNode;
-}
-
-/**
- * Sets up the contexts for the underlying Tab components.
- *
- * @ignore - do not document.
- */
-const TabsListProvider: React.FC<TabsListProviderProps> = function TabsListProvider(props) {
-  const { value, children } = props;
-  const {
-    dispatch,
-    getItemIndex,
-    getItemState,
-    registerItem,
-    totalSubitemCount,
-    activateOnFocus,
-    getTabElement,
-    tabsListRef,
-  } = value;
-
-  const listContextValue: ListContextValue<any> = React.useMemo(
-    () => ({
-      dispatch,
-      getItemState,
-      getItemIndex,
-    }),
-    [dispatch, getItemIndex, getItemState],
-  );
-
-  const compoundComponentContextValue: CompoundComponentContextValue<any, TabMetadata> =
-    React.useMemo(
-      () => ({
-        getItemIndex,
-        registerItem,
-        totalSubitemCount,
-      }),
-      [registerItem, getItemIndex, totalSubitemCount],
-    );
-
-  const tabsListContextValue: TabsListContext = React.useMemo(
-    () => ({ activateOnFocus, getTabElement, tabsListRef }),
-    [activateOnFocus, getTabElement, tabsListRef],
-  );
-
-  return (
-    <CompoundComponentContext.Provider value={compoundComponentContextValue}>
-      <ListContext.Provider value={listContextValue}>
-        <TabsListContext.Provider value={tabsListContextValue}>{children}</TabsListContext.Provider>
-      </ListContext.Provider>
-    </CompoundComponentContext.Provider>
-  );
-};
-
-TabsListProvider.propTypes /* remove-proptypes */ = {
-  // ┌────────────────────────────── Warning ──────────────────────────────┐
-  // │ These PropTypes are generated from the TypeScript type definitions. │
-  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
-  // └─────────────────────────────────────────────────────────────────────┘
-  /**
-   * @ignore
-   */
-  children: PropTypes.node,
-  /**
-   * @ignore
-   */
-  value: PropTypes /* @typescript-to-proptypes-ignore */.shape({
-    activateOnFocus: PropTypes.bool.isRequired,
-    dispatch: PropTypes.func.isRequired,
-    getItemIndex: PropTypes.func.isRequired,
-    getItemState: PropTypes.func.isRequired,
-    getTabElement: PropTypes.func.isRequired,
-    registerItem: PropTypes.func.isRequired,
-    tabsListRef: refType.isRequired,
-    totalSubitemCount: PropTypes.number.isRequired,
-  }).isRequired,
-} as any;
-
-export { TabsListProvider };
diff --git a/packages/react/src/Tabs/TabsList/tabsListReducer.ts b/packages/react/src/Tabs/TabsList/tabsListReducer.ts
deleted file mode 100644
index 903bed29a6..0000000000
--- a/packages/react/src/Tabs/TabsList/tabsListReducer.ts
+++ /dev/null
@@ -1,60 +0,0 @@
-import {
-  ListState,
-  ListAction,
-  ListActionContext,
-  listReducer,
-  ListActionTypes,
-  moveHighlight,
-} from '../../useList';
-import { ActionWithContext } from '../../utils/useControllableReducer.types';
-
-export type TabsListActionContext = ListActionContext<any> & {
-  activateOnFocus: boolean;
-};
-
-export const TabsListActionTypes = {
-  valueChange: 'valueChange',
-} as const;
-
-export interface ValueChangeAction {
-  type: typeof TabsListActionTypes.valueChange;
-  value: any | null;
-}
-
-export function tabsListReducer(
-  state: ListState<any>,
-  action: ActionWithContext<ListAction<any> | ValueChangeAction, TabsListActionContext>,
-) {
-  if (action.type === TabsListActionTypes.valueChange) {
-    return {
-      ...state,
-      highlightedValue: action.value,
-    };
-  }
-
-  const newState = listReducer(state, action);
-
-  const {
-    context: { activateOnFocus },
-  } = action;
-
-  if (action.type === ListActionTypes.itemsChange) {
-    if (newState.selectedValues.length > 0) {
-      return {
-        ...newState,
-        highlightedValue: newState.selectedValues[0],
-      };
-    }
-
-    moveHighlight(null, 'reset', action.context);
-  }
-
-  if (activateOnFocus && newState.highlightedValue != null) {
-    return {
-      ...newState,
-      selectedValues: [newState.highlightedValue],
-    };
-  }
-
-  return newState;
-}
diff --git a/packages/react/src/Tabs/TabsList/useTabsList.test.tsx b/packages/react/src/Tabs/TabsList/useTabsList.test.tsx
index 46e3e469d7..e13dd04b0c 100644
--- a/packages/react/src/Tabs/TabsList/useTabsList.test.tsx
+++ b/packages/react/src/Tabs/TabsList/useTabsList.test.tsx
@@ -13,14 +13,13 @@ describe('useTabsList', () => {
     it('returns props for root slot', () => {
       function TestTabsList() {
         const rootRef = React.createRef<HTMLDivElement>();
+        const tabsListRef = React.createRef<HTMLDivElement>();
         const { getRootProps } = useTabsList({
-          activateOnFocus: true,
-          direction: 'ltr',
-          loop: true,
-          onSelected: NOOP,
+          onValueChange: NOOP,
           orientation: 'horizontal',
-          registerTabIdLookup: NOOP,
           rootRef,
+          tabsListRef,
+          setTabMap: NOOP,
           value: 0,
         });
         return <div {...getRootProps()} />;
@@ -45,14 +44,13 @@ describe('useTabsList', () => {
 
       function TestTabsList() {
         const rootRef = React.createRef<HTMLDivElement>();
+        const tabsListRef = React.createRef<HTMLDivElement>();
         const { getRootProps } = useTabsList({
-          activateOnFocus: true,
-          direction: 'ltr',
-          loop: true,
-          onSelected: NOOP,
+          onValueChange: NOOP,
           orientation: 'horizontal',
-          registerTabIdLookup: NOOP,
           rootRef,
+          tabsListRef,
+          setTabMap: NOOP,
           value: 0,
         });
         return (
diff --git a/packages/react/src/Tabs/TabsList/useTabsList.ts b/packages/react/src/Tabs/TabsList/useTabsList.ts
index 52b41230f9..75f3b83760 100644
--- a/packages/react/src/Tabs/TabsList/useTabsList.ts
+++ b/packages/react/src/Tabs/TabsList/useTabsList.ts
@@ -1,67 +1,70 @@
 'use client';
 import * as React from 'react';
-import { TabsListActionTypes, tabsListReducer, ValueChangeAction } from './tabsListReducer';
 import type { TabsRootContext } from '../Root/TabsRootContext';
-import { type TabMetadata } from '../Root/useTabsRoot';
 import { type TabsOrientation, type TabActivationDirection } from '../Root/TabsRoot';
-import { useCompoundParent } from '../../useCompound';
-import { useList, ListState, UseListParameters, ListAction } from '../../useList';
 import { useForkRef } from '../../utils/useForkRef';
 import { mergeReactProps } from '../../utils/mergeReactProps';
 import { useEnhancedEffect } from '../../utils/useEnhancedEffect';
-import { TabsListProviderValue } from './TabsListProvider';
+import { useEventCallback } from '../../utils/useEventCallback';
+// import { TabsListContext } from './TabsListContext';
 
 function useTabsList(parameters: useTabsList.Parameters): useTabsList.ReturnValue {
   const {
-    activateOnFocus,
-    direction,
-    loop,
-    onSelected,
+    onValueChange,
     orientation,
-    registerTabIdLookup,
+    // registerGetTabIdByPanelValueOrIndexFn,
     rootRef: externalRef,
+    tabsListRef,
     value,
   } = parameters;
 
-  const { subitems, contextValue: compoundComponentContextValue } = useCompoundParent<
-    any,
-    TabMetadata
-  >();
+  // subitems are <Tab>s, their Composite parent is <Tabs.List>
+  // const { subitems } = useCompoundParent<any, TabMetadata>();
 
+  // DON"T NEED THIS ANYMORE
+  //
   // get id attribute of a Tab by tab value
   // for binding aria attributes
   // this function needs to be registered to the context
-  const tabIdLookup = React.useCallback(
-    (tabValue: any) => {
-      return subitems.get(tabValue)?.id;
-    },
-    [subitems],
-  );
+  //
+  // const tabIdLookup = React.useCallback(
+  //   (tabValue: any) => {
+  //     return subitems.get(tabValue)?.id;
+  //   },
+  //   [subitems],
+  // );
 
-  registerTabIdLookup(tabIdLookup);
+  // registerGetTabIdByPanelValueOrIndexFn(tabIdLookup);
 
-  const subitemKeys = React.useMemo(() => Array.from(subitems.keys()), [subitems]);
+  // this is a param for useList
+  // const subitemKeys = React.useMemo(() => Array.from(subitems.keys()), [subitems]);
 
   // get the element/node of a tab by tab value
+  // used as a param for `useActivationDirectionDetector`
+  // TODO: move this to useTabsRoot since tabMap is there
   const getTabElement = React.useCallback(
     (tabValue: any) => {
       if (tabValue == null) {
         return null;
       }
 
-      return subitems.get(tabValue)?.ref.current ?? null;
+      // subitems are <Tab>s, their Composite parent is <Tabs.List>
+      // return subitems.get(tabValue)?.ref.current ?? null;
+      return null;
     },
-    [subitems],
+    [
+      /* subitems */
+    ],
   );
 
-  let listOrientation: UseListParameters<any, any>['orientation'];
-  if (orientation === 'vertical') {
-    listOrientation = 'vertical';
-  } else {
-    listOrientation = direction === 'rtl' ? 'horizontal-rtl' : 'horizontal-ltr';
-  }
+  // let listOrientation: UseListParameters<any, any>['orientation'];
+  // if (orientation === 'vertical') {
+  //   listOrientation = 'vertical';
+  // } else {
+  //   listOrientation = direction === 'rtl' ? 'horizontal-rtl' : 'horizontal-ltr';
+  // }
 
-  const tabsListRef = React.useRef<HTMLElement>(null);
+  // const tabsListRef = React.useRef<HTMLElement>(null);
   const detectActivationDirection = useActivationDirectionDetector(
     value,
     orientation,
@@ -69,111 +72,52 @@ function useTabsList(parameters: useTabsList.Parameters): useTabsList.ReturnValu
     getTabElement,
   );
 
-  const handleChange = React.useCallback(
-    (
-      event:
-        | React.FocusEvent<Element, Element>
-        | React.KeyboardEvent<Element>
-        | React.MouseEvent<Element, MouseEvent>
-        | null,
-      newValue: any[],
-    ) => {
-      const newSelectedValue = newValue[0] ?? null;
-      const activationDirection = detectActivationDirection(newSelectedValue);
-      onSelected(event?.nativeEvent, newValue[0] ?? null, activationDirection);
-    },
-    [onSelected, detectActivationDirection],
-  );
+  const onTabActivation = useEventCallback((newValue: any, event: Event) => {
+    // console.log('onTabActivation()', newValue, event.target);
+    const activationDirection = detectActivationDirection(newValue);
+    onValueChange(newValue, activationDirection, event);
+  });
 
-  const controlledProps = React.useMemo(() => {
-    return value != null ? { selectedValues: [value] } : { selectedValues: [] };
-  }, [value]);
+  // const controlledProps = React.useMemo(() => {
+  //   return value != null ? { selectedValues: [value] } : { selectedValues: [] };
+  // }, [value]);
 
-  const isItemDisabled = React.useCallback(
-    (item: any) => subitems.get(item)?.disabled ?? false,
-    [subitems],
-  );
+  // const isItemDisabled = React.useCallback(
+  //   (item: any) => subitems.get(item)?.disabled ?? false,
+  //   [subitems],
+  // );
 
-  const {
-    contextValue: listContextValue,
-    dispatch,
-    getRootProps: getListboxRootProps,
-    state: { highlightedValue, selectedValues },
-    rootRef: mergedRootRef,
-  } = useList<any, ListState<any>, ValueChangeAction, { activateOnFocus: boolean }>({
-    controlledProps,
-    disabledItemsFocusable: !activateOnFocus,
-    focusManagement: 'DOM',
-    getItemDomElement: getTabElement,
-    isItemDisabled,
-    items: subitemKeys,
-    rootRef: externalRef,
-    onChange: handleChange,
-    orientation: listOrientation,
-    reducerActionContext: React.useMemo(() => ({ activateOnFocus }), [activateOnFocus]),
-    selectionMode: 'single',
-    stateReducer: tabsListReducer,
-    disableListWrap: !loop,
-  });
+  // React.useEffect(() => {
+  //   if (value === undefined) {
+  //     return;
+  //   }
 
-  React.useEffect(() => {
-    if (value === undefined) {
-      return;
-    }
+  //   // when a value changes externally, the highlighted value should be synced to it
+  //   if (value != null) {
+  //     dispatch({
+  //       type: TabsListActionTypes.valueChange,
+  //       value,
+  //     });
+  //   }
+  // }, [dispatch, value]);
 
-    // when a value changes externally, the highlighted value should be synced to it
-    if (value != null) {
-      dispatch({
-        type: TabsListActionTypes.valueChange,
-        value,
-      });
-    }
-  }, [dispatch, value]);
-
-  const handleRef = useForkRef(mergedRootRef, tabsListRef);
+  const handleRef = useForkRef(tabsListRef, externalRef);
 
   const getRootProps = (
     externalProps: React.ComponentPropsWithoutRef<'div'> = {},
   ): React.ComponentPropsWithRef<'div'> => {
-    return mergeReactProps(
-      externalProps,
-      mergeReactProps(
-        {
-          'aria-orientation': orientation === 'vertical' ? 'vertical' : undefined,
-          role: 'tablist',
-          ref: handleRef,
-        },
-        getListboxRootProps(),
-      ),
-    );
+    return mergeReactProps(externalProps, {
+      'aria-orientation': orientation === 'vertical' ? 'vertical' : undefined,
+      ref: handleRef,
+      role: 'tablist',
+    });
   };
 
-  const contextValue = React.useMemo(
-    () => ({
-      ...compoundComponentContextValue,
-      ...listContextValue,
-      activateOnFocus,
-      getTabElement,
-      value,
-      tabsListRef,
-    }),
-    [
-      compoundComponentContextValue,
-      listContextValue,
-      activateOnFocus,
-      getTabElement,
-      value,
-      tabsListRef,
-    ],
-  );
-
   return {
-    contextValue,
-    dispatch,
     getRootProps,
-    highlightedValue,
+    onTabActivation,
     rootRef: handleRef,
-    selectedValue: selectedValues[0] ?? null,
+    tabsListRef,
   };
 }
 
@@ -261,35 +205,15 @@ function useActivationDirectionDetector(
 
 namespace useTabsList {
   export interface Parameters
-    extends Pick<
-      TabsRootContext,
-      'direction' | 'onSelected' | 'orientation' | 'registerTabIdLookup' | 'value'
-    > {
-    /**
-     * If `true`, the tab will be activated whenever it is focused.
-     * Otherwise, it has to be activated by clicking or pressing the Enter or Space key.
-     */
-    activateOnFocus: boolean;
-    /**
-     * If `true`, using keyboard navigation will wrap focus to the other end of the list once the end is reached.
-     */
-    loop: boolean;
+    extends Pick<TabsRootContext, 'onValueChange' | 'orientation' | 'setTabMap' | 'value'> {
     /**
      * Ref to the root element.
      */
     rootRef: React.Ref<Element>;
+    tabsListRef: React.RefObject<HTMLElement | null>;
   }
 
   export interface ReturnValue {
-    /**
-     * The value to be passed to the TabListProvider above all the tabs.
-     */
-    contextValue: TabsListProviderValue;
-    /**
-     * Action dispatcher for the tabs list component.
-     * Allows to programmatically control the tabs list.
-     */
-    dispatch: (action: ListAction<any>) => void;
     /**
      * Resolver for the root slot's props.
      * @param externalProps props for the root slot
@@ -299,14 +223,13 @@ namespace useTabsList {
       externalProps?: React.ComponentPropsWithRef<'div'>,
     ) => React.ComponentPropsWithRef<'div'>;
     /**
-     * The value of the currently highlighted tab.
+     * Callback when a Tab is activated
+     * @param {any | null} newValue The value of the newly activated tab.
+     * @param {Event} event The event that activated the Tab.
      */
-    highlightedValue: any | null;
+    onTabActivation: (newValue: any, event: Event) => void;
     rootRef: React.RefCallback<Element> | null;
-    /**
-     * The value of the currently selected tab.
-     */
-    selectedValue: any | null;
+    tabsListRef: React.RefObject<HTMLElement | null>;
   }
 }
 

From 3d6266d32ccaee75a71da4cc4cef898d0b7cc490 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Fri, 15 Nov 2024 03:30:07 +0800
Subject: [PATCH 08/20] Fix activateOnFocus

---
 .../react/src/Tabs/Root/TabsRoot.test.tsx     | 13 ++-
 packages/react/src/Tabs/Tab/Tab.test.tsx      | 14 +++-
 packages/react/src/Tabs/Tab/Tab.tsx           | 17 ++--
 packages/react/src/Tabs/Tab/useTab.test.tsx   | 81 ------------------
 packages/react/src/Tabs/Tab/useTab.ts         | 59 +++++++++++--
 .../src/Tabs/TabPanel/useTabPanel.test.tsx    | 78 -----------------
 packages/react/src/Tabs/TabsList/TabsList.tsx | 18 +++-
 .../src/Tabs/TabsList/TabsListContext.ts      |  2 +
 .../src/Tabs/TabsList/useTabsList.test.tsx    | 83 -------------------
 .../react/src/Tabs/TabsList/useTabsList.ts    | 10 ++-
 10 files changed, 108 insertions(+), 267 deletions(-)
 delete mode 100644 packages/react/src/Tabs/Tab/useTab.test.tsx
 delete mode 100644 packages/react/src/Tabs/TabPanel/useTabPanel.test.tsx
 delete mode 100644 packages/react/src/Tabs/TabsList/useTabsList.test.tsx

diff --git a/packages/react/src/Tabs/Root/TabsRoot.test.tsx b/packages/react/src/Tabs/Root/TabsRoot.test.tsx
index 09fc8e808a..16033eb2f8 100644
--- a/packages/react/src/Tabs/Root/TabsRoot.test.tsx
+++ b/packages/react/src/Tabs/Root/TabsRoot.test.tsx
@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { expect } from 'chai';
 import { spy } from 'sinon';
-import { act, describeSkipIf, fireEvent, screen } from '@mui/internal-test-utils';
+import { act, describeSkipIf, flushMicrotasks, fireEvent, screen } from '@mui/internal-test-utils';
 import { Tabs } from '@base-ui-components/react/Tabs';
 import { createRenderer, describeConformance } from '#test-utils';
 
@@ -214,6 +214,7 @@ describe('<Tabs.Root />', () => {
       });
 
       fireEvent.keyDown(firstTab, { key: 'ArrowRight' });
+      await flushMicrotasks();
 
       expect(handleChange.callCount).to.equal(1);
       expect(handleChange.firstCall.args[0]).to.equal(1);
@@ -301,6 +302,7 @@ describe('<Tabs.Root />', () => {
               });
 
               fireEvent.keyDown(firstTab, { key: previousItemKey });
+              await flushMicrotasks();
 
               expect(lastTab).toHaveFocus();
               expect(handleChange.callCount).to.equal(0);
@@ -332,6 +334,7 @@ describe('<Tabs.Root />', () => {
               });
 
               fireEvent.keyDown(secondTab, { key: previousItemKey });
+              await flushMicrotasks();
 
               expect(firstTab).toHaveFocus();
               expect(handleChange.callCount).to.equal(0);
@@ -365,6 +368,7 @@ describe('<Tabs.Root />', () => {
               });
 
               fireEvent.keyDown(firstTab, { key: previousItemKey });
+              await flushMicrotasks();
 
               expect(lastTab).toHaveFocus();
               expect(handleChange.callCount).to.equal(1);
@@ -397,6 +401,7 @@ describe('<Tabs.Root />', () => {
               });
 
               fireEvent.keyDown(secondTab, { key: previousItemKey });
+              await flushMicrotasks();
 
               expect(firstTab).toHaveFocus();
               expect(handleChange.callCount).to.equal(1);
@@ -428,6 +433,7 @@ describe('<Tabs.Root />', () => {
             });
 
             fireEvent.keyDown(lastTab, { key: previousItemKey });
+            await flushMicrotasks();
 
             expect(firstTab).toHaveFocus();
             expect(handleKeyDown.callCount).to.equal(1);
@@ -461,6 +467,7 @@ describe('<Tabs.Root />', () => {
               });
 
               fireEvent.keyDown(lastTab, { key: nextItemKey });
+              await flushMicrotasks();
 
               expect(firstTab).toHaveFocus();
               expect(handleChange.callCount).to.equal(0);
@@ -492,6 +499,7 @@ describe('<Tabs.Root />', () => {
               });
 
               fireEvent.keyDown(secondTab, { key: nextItemKey });
+              await flushMicrotasks();
 
               expect(lastTab).toHaveFocus();
               expect(handleChange.callCount).to.equal(0);
@@ -525,6 +533,7 @@ describe('<Tabs.Root />', () => {
               });
 
               fireEvent.keyDown(lastTab, { key: nextItemKey });
+              await flushMicrotasks();
 
               expect(firstTab).toHaveFocus();
               expect(handleChange.callCount).to.equal(1);
@@ -557,6 +566,7 @@ describe('<Tabs.Root />', () => {
               });
 
               fireEvent.keyDown(secondTab, { key: nextItemKey });
+              await flushMicrotasks();
 
               expect(lastTab).toHaveFocus();
               expect(handleChange.callCount).to.equal(1);
@@ -588,6 +598,7 @@ describe('<Tabs.Root />', () => {
             });
 
             fireEvent.keyDown(firstTab, { key: nextItemKey });
+            await flushMicrotasks();
 
             expect(lastTab).toHaveFocus();
             expect(handleKeyDown.callCount).to.equal(1);
diff --git a/packages/react/src/Tabs/Tab/Tab.test.tsx b/packages/react/src/Tabs/Tab/Tab.test.tsx
index 8f76696e64..cf5d643760 100644
--- a/packages/react/src/Tabs/Tab/Tab.test.tsx
+++ b/packages/react/src/Tabs/Tab/Tab.test.tsx
@@ -2,16 +2,24 @@ import * as React from 'react';
 import { Tabs } from '@base-ui-components/react/Tabs';
 import { createRenderer, describeConformance } from '#test-utils';
 import { NOOP } from '../../utils/noop';
+import { CompositeRootContext } from '../../Composite/Root/CompositeRootContext';
 import { TabsRootContext } from '../Root/TabsRootContext';
 import { TabsListContext } from '../TabsList/TabsListContext';
 
 describe('<Tabs.Tab />', () => {
   const { render } = createRenderer();
 
+  const testCompositeContext = {
+    activeIndex: 0,
+    onActiveIndexChange: NOOP,
+  };
+
   const testTabsListContext: TabsListContext = {
     activateOnFocus: true,
     getTabElement: () => null,
+    highlightedTabIndex: 0,
     onTabActivation: NOOP,
+    setHighlightedTabIndex: NOOP,
     tabsListRef: {
       current: null,
     },
@@ -32,7 +40,11 @@ describe('<Tabs.Tab />', () => {
     render: (node) => {
       return render(
         <TabsRootContext.Provider value={testTabsContext}>
-          <TabsListContext.Provider value={testTabsListContext}>{node}</TabsListContext.Provider>
+          <TabsListContext.Provider value={testTabsListContext}>
+            <CompositeRootContext.Provider value={testCompositeContext}>
+              {node}
+            </CompositeRootContext.Provider>
+          </TabsListContext.Provider>
         </TabsRootContext.Provider>,
       );
     },
diff --git a/packages/react/src/Tabs/Tab/Tab.tsx b/packages/react/src/Tabs/Tab/Tab.tsx
index 7bbedfc59b..1a750f54ef 100644
--- a/packages/react/src/Tabs/Tab/Tab.tsx
+++ b/packages/react/src/Tabs/Tab/Tab.tsx
@@ -3,7 +3,6 @@ import * as React from 'react';
 import { useTab } from './useTab';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import type { BaseUIComponentProps } from '../../utils/types';
-import { useCompositeRootContext } from '../../Composite/Root/CompositeRootContext';
 import type { TabsOrientation } from '../Root/TabsRoot';
 import { useTabsRootContext } from '../Root/TabsRootContext';
 import { useTabsListContext } from '../TabsList/TabsListContext';
@@ -25,28 +24,28 @@ const Tab = React.forwardRef(function Tab(
   const { className, disabled = false, render, value: valueProp, id: idProp, ...other } = props;
 
   const {
-    value: selectedValue,
+    value: selectedTabValue,
     getTabPanelIdByTabValueOrIndex,
     orientation,
   } = useTabsRootContext();
 
-  const { activateOnFocus, onTabActivation } = useTabsListContext();
-
-  // this is the context of TabsList
-  const { activeIndex } = useCompositeRootContext();
-  // console.log('activeIndex', activeIndex);
+  const { activateOnFocus, highlightedTabIndex, onTabActivation, setHighlightedTabIndex } =
+    useTabsListContext();
 
   const { getRootProps, index, selected } = useTab({
+    activateOnFocus,
     disabled,
     getTabPanelIdByTabValueOrIndex,
+    highlightedTabIndex,
     id: idProp,
-    isSelected: valueProp === selectedValue,
     onTabActivation,
     rootRef: forwardedRef,
+    setHighlightedTabIndex,
+    selectedTabValue,
     value: valueProp,
   });
 
-  const highlighted = index > -1 && index === activeIndex;
+  const highlighted = index > -1 && index === highlightedTabIndex;
 
   const ownerState: Tab.OwnerState = React.useMemo(
     () => ({
diff --git a/packages/react/src/Tabs/Tab/useTab.test.tsx b/packages/react/src/Tabs/Tab/useTab.test.tsx
deleted file mode 100644
index fb8ae31b21..0000000000
--- a/packages/react/src/Tabs/Tab/useTab.test.tsx
+++ /dev/null
@@ -1,81 +0,0 @@
-import * as React from 'react';
-import { expect } from 'chai';
-import { spy } from 'sinon';
-import { createRenderer, screen, fireEvent } from '@mui/internal-test-utils';
-import { Tabs } from '@base-ui-components/react/Tabs';
-import { NOOP } from '../../utils/noop';
-import { useTab } from './useTab';
-
-describe('useTab', () => {
-  const { render } = createRenderer();
-
-  describe('getRootProps', () => {
-    it('returns props for root slot', () => {
-      function TestTab() {
-        const rootRef = React.createRef<HTMLDivElement>();
-        const { getRootProps } = useTab({
-          rootRef,
-          isSelected: true,
-          onTabActivation: NOOP,
-          getTabPanelIdByTabValueOrIndex: () => undefined,
-        });
-        return <button {...getRootProps()} />;
-      }
-
-      function Test() {
-        return (
-          <Tabs.Root defaultValue={1}>
-            <Tabs.List>
-              <TestTab />
-            </Tabs.List>
-          </Tabs.Root>
-        );
-      }
-
-      const { getByRole } = render(<Test />);
-
-      const tab = getByRole('tab');
-      expect(tab).not.to.equal(null);
-    });
-
-    it('forwards external props including event handlers', () => {
-      const handleClick = spy();
-
-      function TestTab() {
-        const rootRef = React.createRef<HTMLDivElement>();
-        const { getRootProps } = useTab({
-          rootRef,
-          isSelected: true,
-          onTabActivation: NOOP,
-          getTabPanelIdByTabValueOrIndex: () => undefined,
-        });
-        return (
-          <button
-            {...getRootProps({
-              'data-testid': 'test-tab',
-              onClick: handleClick,
-            } as React.ComponentPropsWithoutRef<'button'>)}
-          />
-        );
-      }
-
-      function Test() {
-        return (
-          <Tabs.Root defaultValue={1}>
-            <Tabs.List>
-              <TestTab />
-            </Tabs.List>
-          </Tabs.Root>
-        );
-      }
-
-      render(<Test />);
-
-      const tab = screen.getByTestId('test-tab');
-      expect(tab).not.to.equal(null);
-
-      fireEvent.click(tab);
-      expect(handleClick.callCount).to.equal(1);
-    });
-  });
-});
diff --git a/packages/react/src/Tabs/Tab/useTab.ts b/packages/react/src/Tabs/Tab/useTab.ts
index 00b7e0aa1b..7dac5ad155 100644
--- a/packages/react/src/Tabs/Tab/useTab.ts
+++ b/packages/react/src/Tabs/Tab/useTab.ts
@@ -1,12 +1,14 @@
 'use client';
 import * as React from 'react';
 import { mergeReactProps } from '../../utils/mergeReactProps';
+import { useEnhancedEffect } from '../../utils/useEnhancedEffect';
 import { useForkRef } from '../../utils/useForkRef';
 import { useId } from '../../utils/useId';
 import { useButton } from '../../useButton';
 import { useCompositeItem } from '../../Composite/Item/useCompositeItem';
 import type { TabsRootContext } from '../Root/TabsRootContext';
 import type { useTabsList } from '../TabsList/useTabsList';
+import type { TabsList } from '../TabsList/TabsList';
 
 export interface TabMetadata {
   disabled: boolean;
@@ -15,12 +17,15 @@ export interface TabMetadata {
 
 function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
   const {
+    activateOnFocus,
     disabled = false,
     getTabPanelIdByTabValueOrIndex,
+    highlightedTabIndex,
     id: idParam,
-    isSelected,
     onTabActivation,
     rootRef: externalRef,
+    selectedTabValue,
+    setHighlightedTabIndex,
     value: valueParam,
   } = parameters;
 
@@ -39,6 +44,25 @@ function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
 
   const tabValue = valueParam ?? index;
 
+  // the `selected` state isn't set on the server (it relies on effects to be calculated),
+  // so we fall back to checking the `value` param with the selectedValue from the TabsContext
+  const selected = React.useMemo(() => {
+    if (valueParam === undefined) {
+      return index < 0 ? false : index === selectedTabValue;
+    }
+
+    return valueParam === selectedTabValue;
+  }, [index, selectedTabValue, valueParam]);
+
+  // ensure the active item in Composite's roving focus group matches the selected Tab
+  // FIXME: something is wrong with this
+  useEnhancedEffect(() => {
+    if (activateOnFocus && selected && index > -1 && highlightedTabIndex !== index) {
+      console.log('useEnhancedEffect update index', index);
+      setHighlightedTabIndex(index);
+    }
+  }, [activateOnFocus, highlightedTabIndex, index, selected, setHighlightedTabIndex]);
+
   const { getButtonProps, buttonRef } = useButton({
     disabled,
     focusableWhenDisabled: true,
@@ -57,27 +81,45 @@ function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
           {
             role: 'tab',
             'aria-controls': tabPanelId,
-            'aria-selected': false,
+            'aria-selected': selected,
             id,
             ref: handleRef,
             onClick(event) {
               onTabActivation(tabValue, event.nativeEvent);
             },
+            onFocus(event) {
+              if (!activateOnFocus) {
+                return;
+              }
+
+              if (selectedTabValue !== tabValue) {
+                onTabActivation(tabValue, event.nativeEvent);
+              }
+            },
           },
           mergeReactProps(getItemProps(), getButtonProps()),
         ),
       );
     },
-    [getButtonProps, getItemProps, handleRef, id, onTabActivation, tabPanelId, tabValue],
+    [
+      activateOnFocus,
+      getButtonProps,
+      getItemProps,
+      handleRef,
+      id,
+      onTabActivation,
+      selected,
+      selectedTabValue,
+      tabPanelId,
+      tabValue,
+    ],
   );
 
   return {
     getRootProps,
     index,
     rootRef: handleRef,
-    // the `selected` state isn't set on the server (it relies on effects to be calculated),
-    // so we fall back to checking the `value` prop with the selectedValue from the TabsContext
-    selected: /* selected || */ isSelected,
+    selected,
     // TODO: recalculate this using Composite stuff, but is it really needed?
     totalTabsCount: -1,
   };
@@ -86,6 +128,7 @@ function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
 namespace useTab {
   export interface Parameters
     extends Pick<TabsRootContext, 'getTabPanelIdByTabValueOrIndex'>,
+      Pick<TabsList.Props, 'activateOnFocus'>,
       Pick<useTabsList.ReturnValue, 'onTabActivation'> {
     /**
      * The value of the tab.
@@ -101,12 +144,14 @@ namespace useTab {
      * If `true`, the tab will be disabled.
      */
     disabled?: boolean;
+    highlightedTabIndex: number;
     /**
      * The id of the tab.
      * If not provided, it will be automatically generated.
      */
     id?: string;
-    isSelected: boolean;
+    selectedTabValue: TabsRootContext['value'];
+    setHighlightedTabIndex: (index: number) => void;
     /**
      * Ref to the root slot's DOM element.
      */
diff --git a/packages/react/src/Tabs/TabPanel/useTabPanel.test.tsx b/packages/react/src/Tabs/TabPanel/useTabPanel.test.tsx
deleted file mode 100644
index f5d5df7ed2..0000000000
--- a/packages/react/src/Tabs/TabPanel/useTabPanel.test.tsx
+++ /dev/null
@@ -1,78 +0,0 @@
-import * as React from 'react';
-import { expect } from 'chai';
-import { spy } from 'sinon';
-import { createRenderer, screen, fireEvent } from '@mui/internal-test-utils';
-import { Tabs } from '@base-ui-components/react/Tabs';
-import { useTabPanel } from './useTabPanel';
-
-describe('useTabPanel', () => {
-  const { render } = createRenderer();
-
-  describe('getRootProps', () => {
-    it('returns props for root slot', () => {
-      const rootRef = React.createRef<HTMLDivElement>();
-      function TestTabPanel() {
-        const { getRootProps } = useTabPanel({
-          getTabIdByPanelValueOrIndex: () => undefined,
-          id: 'test-tabpanel',
-          rootRef,
-          selectedValue: 0,
-          value: 0,
-        });
-        return <div {...getRootProps()} />;
-      }
-
-      function Test() {
-        return (
-          <Tabs.Root>
-            <TestTabPanel />
-          </Tabs.Root>
-        );
-      }
-
-      render(<Test />);
-
-      const tabpanel = document.querySelector('#test-tabpanel');
-      expect(tabpanel).to.equal(rootRef.current);
-    });
-
-    it('forwards external props including event handlers', () => {
-      const handleClick = spy();
-      const rootRef = React.createRef<HTMLElement>();
-
-      function TestTabPanel() {
-        const { getRootProps } = useTabPanel({
-          getTabIdByPanelValueOrIndex: () => undefined,
-          id: 'test-tabpanel',
-          rootRef,
-          selectedValue: 0,
-          value: 0,
-        });
-        return (
-          <div
-            {...getRootProps({
-              'data-testid': 'test-tabpanel',
-              onClick: handleClick,
-            } as React.ComponentPropsWithoutRef<'div'>)}
-          />
-        );
-      }
-
-      function Test() {
-        return (
-          <Tabs.Root>
-            <TestTabPanel />
-          </Tabs.Root>
-        );
-      }
-
-      render(<Test />);
-
-      const tabPanel = screen.getByTestId('test-tabpanel');
-      expect(tabPanel).not.to.equal(null);
-
-      fireEvent.click(tabPanel);
-      expect(handleClick.callCount).to.equal(1);
-    });
-  });
-});
diff --git a/packages/react/src/Tabs/TabsList/TabsList.tsx b/packages/react/src/Tabs/TabsList/TabsList.tsx
index a8c35df243..7a8ff02e6f 100644
--- a/packages/react/src/Tabs/TabsList/TabsList.tsx
+++ b/packages/react/src/Tabs/TabsList/TabsList.tsx
@@ -34,6 +34,8 @@ const TabsList = React.forwardRef(function TabsList(
     tabActivationDirection,
   } = useTabsRootContext();
 
+  const [highlightedTabIndex, setHighlightedTabIndex] = React.useState(0);
+
   const tabsListRef = React.useRef<HTMLElement>(null);
 
   const { getRootProps, onTabActivation } = useTabsList({
@@ -66,17 +68,21 @@ const TabsList = React.forwardRef(function TabsList(
   const tabsListContextValue = React.useMemo(
     () => ({
       activateOnFocus,
+      highlightedTabIndex,
       onTabActivation,
       // getTabElement,
-      value,
+      setHighlightedTabIndex,
       tabsListRef,
+      value,
     }),
     [
       activateOnFocus,
+      highlightedTabIndex,
       onTabActivation,
       // getTabElement,
-      value,
+      setHighlightedTabIndex,
       tabsListRef,
+      value,
     ],
   );
 
@@ -86,7 +92,13 @@ const TabsList = React.forwardRef(function TabsList(
         TODO: pass `direction` prop to `rtl` prop of CompositeRoot when
         https://github.com/mui/base-ui/pull/763 is merged
        */}
-      <CompositeRoot loop={loop} onMapChange={setTabMap} render={renderElement()} />
+      <CompositeRoot
+        activeIndex={highlightedTabIndex}
+        loop={loop}
+        onActiveIndexChange={setHighlightedTabIndex}
+        onMapChange={setTabMap}
+        render={renderElement()}
+      />
     </TabsListContext.Provider>
   );
 });
diff --git a/packages/react/src/Tabs/TabsList/TabsListContext.ts b/packages/react/src/Tabs/TabsList/TabsListContext.ts
index 740d66a51f..fc32651eb7 100644
--- a/packages/react/src/Tabs/TabsList/TabsListContext.ts
+++ b/packages/react/src/Tabs/TabsList/TabsListContext.ts
@@ -4,7 +4,9 @@ import * as React from 'react';
 export interface TabsListContext {
   activateOnFocus: boolean;
   getTabElement: (value: any) => HTMLElement | null;
+  highlightedTabIndex: number;
   onTabActivation: (newValue: any, event: Event) => void;
+  setHighlightedTabIndex: (index: number) => void;
   tabsListRef: React.RefObject<HTMLElement | null>;
 }
 
diff --git a/packages/react/src/Tabs/TabsList/useTabsList.test.tsx b/packages/react/src/Tabs/TabsList/useTabsList.test.tsx
deleted file mode 100644
index e13dd04b0c..0000000000
--- a/packages/react/src/Tabs/TabsList/useTabsList.test.tsx
+++ /dev/null
@@ -1,83 +0,0 @@
-import * as React from 'react';
-import { expect } from 'chai';
-import { spy } from 'sinon';
-import { createRenderer, screen, fireEvent } from '@mui/internal-test-utils';
-import { Tabs } from '@base-ui-components/react/Tabs';
-import { NOOP } from '../../utils/noop';
-import { useTabsList } from './useTabsList';
-
-describe('useTabsList', () => {
-  const { render } = createRenderer();
-
-  describe('getRootProps', () => {
-    it('returns props for root slot', () => {
-      function TestTabsList() {
-        const rootRef = React.createRef<HTMLDivElement>();
-        const tabsListRef = React.createRef<HTMLDivElement>();
-        const { getRootProps } = useTabsList({
-          onValueChange: NOOP,
-          orientation: 'horizontal',
-          rootRef,
-          tabsListRef,
-          setTabMap: NOOP,
-          value: 0,
-        });
-        return <div {...getRootProps()} />;
-      }
-
-      function Test() {
-        return (
-          <Tabs.Root>
-            <TestTabsList />
-          </Tabs.Root>
-        );
-      }
-
-      const { getByRole } = render(<Test />);
-
-      const tablist = getByRole('tablist');
-      expect(tablist).not.to.equal(null);
-    });
-
-    it('forwards external props including event handlers', () => {
-      const handleClick = spy();
-
-      function TestTabsList() {
-        const rootRef = React.createRef<HTMLDivElement>();
-        const tabsListRef = React.createRef<HTMLDivElement>();
-        const { getRootProps } = useTabsList({
-          onValueChange: NOOP,
-          orientation: 'horizontal',
-          rootRef,
-          tabsListRef,
-          setTabMap: NOOP,
-          value: 0,
-        });
-        return (
-          <div
-            {...getRootProps({
-              'data-testid': 'test-tabslist',
-              onClick: handleClick,
-            } as React.ComponentPropsWithoutRef<'div'>)}
-          />
-        );
-      }
-
-      function Test() {
-        return (
-          <Tabs.Root>
-            <TestTabsList />
-          </Tabs.Root>
-        );
-      }
-
-      render(<Test />);
-
-      const tabsList = screen.getByTestId('test-tabslist');
-      expect(tabsList).not.to.equal(null);
-
-      fireEvent.click(tabsList);
-      expect(handleClick.callCount).to.equal(1);
-    });
-  });
-});
diff --git a/packages/react/src/Tabs/TabsList/useTabsList.ts b/packages/react/src/Tabs/TabsList/useTabsList.ts
index 75f3b83760..40bc3ffbdc 100644
--- a/packages/react/src/Tabs/TabsList/useTabsList.ts
+++ b/packages/react/src/Tabs/TabsList/useTabsList.ts
@@ -15,7 +15,7 @@ function useTabsList(parameters: useTabsList.Parameters): useTabsList.ReturnValu
     // registerGetTabIdByPanelValueOrIndexFn,
     rootRef: externalRef,
     tabsListRef,
-    value,
+    value: selectedTabValue,
   } = parameters;
 
   // subitems are <Tab>s, their Composite parent is <Tabs.List>
@@ -66,7 +66,7 @@ function useTabsList(parameters: useTabsList.Parameters): useTabsList.ReturnValu
 
   // const tabsListRef = React.useRef<HTMLElement>(null);
   const detectActivationDirection = useActivationDirectionDetector(
-    value,
+    selectedTabValue,
     orientation,
     tabsListRef,
     getTabElement,
@@ -74,8 +74,10 @@ function useTabsList(parameters: useTabsList.Parameters): useTabsList.ReturnValu
 
   const onTabActivation = useEventCallback((newValue: any, event: Event) => {
     // console.log('onTabActivation()', newValue, event.target);
-    const activationDirection = detectActivationDirection(newValue);
-    onValueChange(newValue, activationDirection, event);
+    if (newValue !== selectedTabValue) {
+      const activationDirection = detectActivationDirection(newValue);
+      onValueChange(newValue, activationDirection, event);
+    }
   });
 
   // const controlledProps = React.useMemo(() => {

From 86e309239f07c7b8dca93d0d0371365dd649fd4f Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Fri, 15 Nov 2024 17:05:41 +0800
Subject: [PATCH 09/20] Fix binding aria-labelledby

---
 .../react/src/Tabs/Root/TabsRoot.test.tsx     |  2 +-
 packages/react/src/Tabs/Root/TabsRoot.tsx     |  3 +
 .../react/src/Tabs/Root/TabsRootContext.ts    |  1 +
 packages/react/src/Tabs/Root/useTabsRoot.ts   | 61 ++++++++++----
 packages/react/src/Tabs/Tab/Tab.test.tsx      |  2 +-
 packages/react/src/Tabs/Tab/useTab.ts         |  3 +-
 .../src/Tabs/TabIndicator/TabIndicator.tsx    | 18 ++--
 .../src/Tabs/TabIndicator/useTabIndicator.ts  | 10 +--
 .../react/src/Tabs/TabPanel/TabPanel.test.tsx | 14 +---
 .../react/src/Tabs/TabPanel/useTabPanel.ts    | 34 +++-----
 .../react/src/Tabs/TabsList/TabsList.test.tsx |  1 +
 packages/react/src/Tabs/TabsList/TabsList.tsx |  2 +
 .../src/Tabs/TabsList/TabsListContext.ts      |  1 -
 .../react/src/Tabs/TabsList/useTabsList.ts    | 82 ++++---------------
 14 files changed, 99 insertions(+), 135 deletions(-)

diff --git a/packages/react/src/Tabs/Root/TabsRoot.test.tsx b/packages/react/src/Tabs/Root/TabsRoot.test.tsx
index 16033eb2f8..3a1d74c68a 100644
--- a/packages/react/src/Tabs/Root/TabsRoot.test.tsx
+++ b/packages/react/src/Tabs/Root/TabsRoot.test.tsx
@@ -275,7 +275,7 @@ describe('<Tabs.Root />', () => {
     ].forEach((entry) => {
       const [orientation, direction, previousItemKey, nextItemKey] = entry;
 
-      describe(`when focus is on a tab element in a ${orientation} ${direction} tablist`, () => {
+      describe(`when focus is on a tab element in a ${orientation} ${direction ?? ''} tablist`, () => {
         describe(previousItemKey ?? '', () => {
           describe('with `activateOnFocus = false`', () => {
             it('moves focus to the last tab without activating it if focus is on the first tab', async () => {
diff --git a/packages/react/src/Tabs/Root/TabsRoot.tsx b/packages/react/src/Tabs/Root/TabsRoot.tsx
index 6649875ac0..a72ec5df52 100644
--- a/packages/react/src/Tabs/Root/TabsRoot.tsx
+++ b/packages/react/src/Tabs/Root/TabsRoot.tsx
@@ -36,6 +36,7 @@ const TabsRoot = React.forwardRef(function TabsRoot(
   const {
     getRootProps,
     direction,
+    getTabElementBySelectedValue,
     getTabIdByPanelValueOrIndex,
     getTabPanelIdByTabValueOrIndex,
     onValueChange,
@@ -55,6 +56,7 @@ const TabsRoot = React.forwardRef(function TabsRoot(
   const tabsContextValue = React.useMemo(
     () => ({
       direction,
+      getTabElementBySelectedValue,
       getTabIdByPanelValueOrIndex,
       getTabPanelIdByTabValueOrIndex,
       onValueChange,
@@ -66,6 +68,7 @@ const TabsRoot = React.forwardRef(function TabsRoot(
     }),
     [
       direction,
+      getTabElementBySelectedValue,
       getTabIdByPanelValueOrIndex,
       getTabPanelIdByTabValueOrIndex,
       onValueChange,
diff --git a/packages/react/src/Tabs/Root/TabsRootContext.ts b/packages/react/src/Tabs/Root/TabsRootContext.ts
index 464746ca7f..b68d5f128e 100644
--- a/packages/react/src/Tabs/Root/TabsRootContext.ts
+++ b/packages/react/src/Tabs/Root/TabsRootContext.ts
@@ -28,6 +28,7 @@ export interface TabsRootContext {
    * Registers a function that returns the id of the tab with the given value.
    */
   // registerGetTabIdByPanelValueOrIndexFn?: (lookupFunction: (id: any) => string | undefined) => void;
+  getTabElementBySelectedValue: (selectedValue: any | undefined) => HTMLElement | null;
   /**
    * Gets the id of the tab with the given value.
    * @param {any | undefined} value Value to find the tab for.
diff --git a/packages/react/src/Tabs/Root/useTabsRoot.ts b/packages/react/src/Tabs/Root/useTabsRoot.ts
index 49ef80c611..caf53c9350 100644
--- a/packages/react/src/Tabs/Root/useTabsRoot.ts
+++ b/packages/react/src/Tabs/Root/useTabsRoot.ts
@@ -80,24 +80,49 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
   // get the `id` attribute of <Tabs.Tab> to set as the value of `aria-labelledby` on <Tabs.Panel>
   const getTabIdByPanelValueOrIndex = React.useCallback(
     (tabPanelValue: any | undefined, index: number) => {
-      // return getTabIdByPanelValueOrIndexRef.current(tabPanelValue);
+      if (tabPanelValue === undefined && index < 0) {
+        return undefined;
+      }
+
       for (const tabMetadata of tabMap.values()) {
-        console.log(tabPanelValue, index, tabMetadata);
+        // console.log(tabPanelValue, index, tabMetadata);
+
+        // find by tabPanelValue
+        if (
+          tabPanelValue !== undefined &&
+          index > -1 &&
+          tabPanelValue === (tabMetadata?.value ?? tabMetadata?.index ?? undefined)
+        ) {
+          // console.log('found by tabPanelValue', tabMetadata?.id);
+          return tabMetadata?.id;
+        }
+
+        // find by index
+        if (
+          tabPanelValue === undefined &&
+          index > -1 &&
+          index === (tabMetadata?.value ?? tabMetadata?.index ?? undefined)
+        ) {
+          // console.log('found by tabPanel index', tabMetadata?.id);
+          return tabMetadata?.id;
+        }
       }
+
       return undefined;
     },
     [tabMap],
   );
 
+  // FIXME
   // used as a param for `useActivationDirectionDetector`
-  const getTabElementByPanelValueOrIndex = React.useCallback(
-    (tabPanelValue: any | undefined, index: number) => {
-      // return getTabIdByPanelValueOrIndexRef.current(tabPanelValue);
-      return null;
-    },
-    [],
-  );
-
+  // put this into TabsRootContext
+  // use it in useTabsList
+  const getTabElementBySelectedValue = React.useCallback((selectedValue: any | undefined) => {
+    console.log('getTabElementBySelectedValue', selectedValue);
+    return null;
+  }, []);
+
+  // TODO: no need to put this in a ref anymore?
   const registerGetTabIdByPanelValueOrIndexFn = React.useCallback(
     (lookupFunction: IdLookupFunction) => {
       getTabIdByPanelValueOrIndexRef.current = lookupFunction;
@@ -116,7 +141,7 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
   return {
     getRootProps,
     direction,
-    getTabElementByPanelValueOrIndex,
+    getTabElementBySelectedValue,
     getTabIdByPanelValueOrIndex,
     getTabPanelIdByTabValueOrIndex,
     onValueChange,
@@ -124,6 +149,7 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
     setTabMap,
     setTabPanelMap,
     tabActivationDirection,
+    tabMap,
     tabPanelRefs,
     value,
   };
@@ -159,14 +185,16 @@ namespace useTabsRoot {
      * The direction of the text.
      */
     direction: 'ltr' | 'rtl';
-    getTabElementByPanelValueOrIndex: (
-      panelValue: any | undefined,
-      index: number,
-    ) => HTMLElement | null;
     /**
-     * Gets the id of the tab with the given value.
+     * Gets the underlying element of the Tab with the given value.
      * @param value Value to find the tab for.
      */
+    getTabElementBySelectedValue: (panelValue: any | undefined) => HTMLElement | null;
+    /**
+     * Gets the `id` attribute of the Tab with the given value.
+     * @param (any | undefined) panelValue Value to find the Tab for.
+     * @param (number) index The index of the Tab to look for.
+     */
     getTabIdByPanelValueOrIndex: (panelValue: any | undefined, index: number) => string | undefined;
     /**
      * Gets the id of the tab panel with the given value.
@@ -196,6 +224,7 @@ namespace useTabsRoot {
      * The position of the active tab relative to the previously active tab.
      */
     tabActivationDirection: TabActivationDirection;
+    tabMap: Map<Node, (TabMetadata & { index?: number | null }) | null>;
     tabPanelRefs: React.RefObject<(HTMLElement | null)[]>;
     /**
      * The currently selected tab's value.
diff --git a/packages/react/src/Tabs/Tab/Tab.test.tsx b/packages/react/src/Tabs/Tab/Tab.test.tsx
index cf5d643760..c10e982097 100644
--- a/packages/react/src/Tabs/Tab/Tab.test.tsx
+++ b/packages/react/src/Tabs/Tab/Tab.test.tsx
@@ -16,7 +16,6 @@ describe('<Tabs.Tab />', () => {
 
   const testTabsListContext: TabsListContext = {
     activateOnFocus: true,
-    getTabElement: () => null,
     highlightedTabIndex: 0,
     onTabActivation: NOOP,
     setHighlightedTabIndex: NOOP,
@@ -29,6 +28,7 @@ describe('<Tabs.Tab />', () => {
     value: 0,
     onValueChange() {},
     setTabMap() {},
+    getTabElementBySelectedValue: () => null,
     getTabIdByPanelValueOrIndex: () => '',
     getTabPanelIdByTabValueOrIndex: () => '',
     orientation: 'horizontal',
diff --git a/packages/react/src/Tabs/Tab/useTab.ts b/packages/react/src/Tabs/Tab/useTab.ts
index 7dac5ad155..f4699009cf 100644
--- a/packages/react/src/Tabs/Tab/useTab.ts
+++ b/packages/react/src/Tabs/Tab/useTab.ts
@@ -13,6 +13,7 @@ import type { TabsList } from '../TabsList/TabsList';
 export interface TabMetadata {
   disabled: boolean;
   id: string | undefined;
+  value: any | undefined;
 }
 
 function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
@@ -45,7 +46,7 @@ function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
   const tabValue = valueParam ?? index;
 
   // the `selected` state isn't set on the server (it relies on effects to be calculated),
-  // so we fall back to checking the `value` param with the selectedValue from the TabsContext
+  // so we fall back to checking the `value` param with the selectedTabValue from the TabsContext
   const selected = React.useMemo(() => {
     if (valueParam === undefined) {
       return index < 0 ? false : index === selectedTabValue;
diff --git a/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx b/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx
index c3bd2a5c6b..85f9a057f5 100644
--- a/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx
+++ b/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx
@@ -1,14 +1,14 @@
 'use client';
 import * as React from 'react';
-import { ActiveTabPosition, useTabIndicator } from './useTabIndicator';
-import { script as prehydrationScript } from './prehydrationScript.min';
+import { useComponentRenderer } from '../../utils/useComponentRenderer';
+import { useOnMount } from '../../utils/useOnMount';
+import type { BaseUIComponentProps } from '../../utils/types';
 import type { TabsDirection, TabsOrientation, TabsRoot } from '../Root/TabsRoot';
 import { useTabsRootContext } from '../Root/TabsRootContext';
 import { tabsStyleHookMapping } from '../Root/styleHooks';
 import { useTabsListContext } from '../TabsList/TabsListContext';
-import { useComponentRenderer } from '../../utils/useComponentRenderer';
-import { useOnMount } from '../../utils/useOnMount';
-import type { BaseUIComponentProps } from '../../utils/types';
+import { ActiveTabPosition, useTabIndicator } from './useTabIndicator';
+import { script as prehydrationScript } from './prehydrationScript.min';
 
 const noop = () => null;
 
@@ -26,8 +26,10 @@ const TabIndicator = React.forwardRef<HTMLSpanElement, TabIndicator.Props>(
   function TabIndicator(props, forwardedRef) {
     const { className, render, renderBeforeHydration = false, ...other } = props;
 
-    const { orientation, direction, value, tabActivationDirection } = useTabsRootContext();
-    const { tabsListRef, getTabElement } = useTabsListContext();
+    const { direction, getTabElementBySelectedValue, orientation, tabActivationDirection, value } =
+      useTabsRootContext();
+
+    const { tabsListRef } = useTabsListContext();
 
     const [instanceId] = React.useState(() => Math.random().toString(36).slice(2));
     const [isMounted, setIsMounted] = React.useState(false);
@@ -36,7 +38,7 @@ const TabIndicator = React.forwardRef<HTMLSpanElement, TabIndicator.Props>(
     useOnMount(() => setIsMounted(true));
 
     const { getRootProps, activeTabPosition: selectedTabPosition } = useTabIndicator({
-      getTabElement,
+      getTabElementBySelectedValue,
       tabsListRef,
       value,
     });
diff --git a/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts b/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts
index 3d49a93d36..8e0b45f981 100644
--- a/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts
+++ b/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts
@@ -12,7 +12,7 @@ function round(value: number) {
 export function useTabIndicator(
   parameters: useTabIndicator.Parameters,
 ): useTabIndicator.ReturnValue {
-  const { value, tabsListRef, getTabElement } = parameters;
+  const { value, tabsListRef, getTabElementBySelectedValue } = parameters;
 
   const rerender = useForcedRerendering();
   React.useEffect(() => {
@@ -41,7 +41,7 @@ export function useTabIndicator(
   let isTabSelected = false;
 
   if (value != null && tabsListRef.current != null) {
-    const selectedTabElement = null; /*getTabElement(value)*/
+    const selectedTabElement = getTabElementBySelectedValue(value);
     isTabSelected = true;
 
     if (selectedTabElement != null) {
@@ -120,9 +120,9 @@ export interface ActiveTabPosition {
 }
 
 export namespace useTabIndicator {
-  export interface Parameters extends Pick<TabsListContext, 'getTabElement' | 'tabsListRef'> {
-    value: TabsRootContext['value'];
-  }
+  export interface Parameters
+    extends Pick<TabsRootContext, 'getTabElementBySelectedValue' | 'value'>,
+      Pick<TabsListContext, 'tabsListRef'> {}
 
   export interface ReturnValue {
     getRootProps: (
diff --git a/packages/react/src/Tabs/TabPanel/TabPanel.test.tsx b/packages/react/src/Tabs/TabPanel/TabPanel.test.tsx
index 026145ceb6..c12e13fe4f 100644
--- a/packages/react/src/Tabs/TabPanel/TabPanel.test.tsx
+++ b/packages/react/src/Tabs/TabPanel/TabPanel.test.tsx
@@ -1,22 +1,16 @@
 import * as React from 'react';
 import { Tabs } from '@base-ui-components/react/Tabs';
 import { createRenderer, describeConformance } from '#test-utils';
-import { CompoundComponentContext } from '../../useCompound';
 import { TabsRootContext } from '../Root/TabsRootContext';
 
 describe('<Tabs.Panel />', () => {
   const { render } = createRenderer();
 
-  const compoundContextValue = {
-    getItemIndex: () => 0,
-    registerItem: () => ({ id: 0, deregister: () => {} }),
-    totalSubitemCount: 1,
-  };
-
   const tabsContextDefaultValue: TabsRootContext = {
     value: '1',
     onValueChange: () => {},
     setTabMap() {},
+    getTabElementBySelectedValue: () => null,
     getTabIdByPanelValueOrIndex: () => '',
     getTabPanelIdByTabValueOrIndex: () => '',
     direction: 'ltr',
@@ -27,11 +21,7 @@ describe('<Tabs.Panel />', () => {
   describeConformance(<Tabs.Panel value="1" />, () => ({
     render: (node) => {
       return render(
-        <CompoundComponentContext.Provider value={compoundContextValue}>
-          <TabsRootContext.Provider value={tabsContextDefaultValue}>
-            {node}
-          </TabsRootContext.Provider>
-        </CompoundComponentContext.Provider>,
+        <TabsRootContext.Provider value={tabsContextDefaultValue}>{node}</TabsRootContext.Provider>,
       );
     },
     refInstanceof: window.HTMLDivElement,
diff --git a/packages/react/src/Tabs/TabPanel/useTabPanel.ts b/packages/react/src/Tabs/TabPanel/useTabPanel.ts
index c199e284e7..f35be421a6 100644
--- a/packages/react/src/Tabs/TabPanel/useTabPanel.ts
+++ b/packages/react/src/Tabs/TabPanel/useTabPanel.ts
@@ -4,7 +4,6 @@ import type { TabsRootContext } from '../Root/TabsRootContext';
 import { useId } from '../../utils/useId';
 import { useForkRef } from '../../utils/useForkRef';
 import { mergeReactProps } from '../../utils/mergeReactProps';
-import { useCompositeListContext } from '../../Composite/List/CompositeListContext';
 import { useCompositeListItem } from '../../Composite/List/useCompositeListItem';
 
 export interface TabPanelMetadata {
@@ -13,7 +12,12 @@ export interface TabPanelMetadata {
 }
 
 function useTabPanel(parameters: useTabPanel.Parameters): useTabPanel.ReturnValue {
-  const { rootRef: externalRef, selectedValue, value: valueParam } = parameters;
+  const {
+    getTabIdByPanelValueOrIndex,
+    rootRef: externalRef,
+    selectedValue,
+    value: valueParam,
+  } = parameters;
 
   const id = useId();
 
@@ -25,9 +29,6 @@ function useTabPanel(parameters: useTabPanel.Parameters): useTabPanel.ReturnValu
     [id, valueParam],
   );
 
-  // tabPanelCompositeMap
-  const { map: tabPanelCompositeMap } = useCompositeListContext();
-
   const { ref: listItemRef, index } = useCompositeListItem<TabPanelMetadata>({
     metadata,
   });
@@ -39,29 +40,16 @@ function useTabPanel(parameters: useTabPanel.Parameters): useTabPanel.ReturnValu
 
   const hidden = tabPanelValue !== selectedValue;
 
-  // const correspondingTabId = tabPanelValue !== undefined ? getTabId(tabPanelValue) : undefined;
-
-  const tabId = React.useMemo(() => {
-    if (index < 0) {
-      return undefined;
-    }
-
-    // TODO: this is incorrect, should be tabButtonMap
-    for (const value of tabPanelCompositeMap.values()) {
-      if (value.index > -1 && value.index === index) {
-        return value.id;
-      }
-    }
-
-    return undefined;
-  }, [index, tabPanelCompositeMap]);
+  const correspondingTabId = React.useMemo(() => {
+    return getTabIdByPanelValueOrIndex(valueParam, index);
+  }, [getTabIdByPanelValueOrIndex, index, valueParam]);
 
   const getRootProps = React.useCallback(
     (
       externalProps: React.ComponentPropsWithoutRef<'div'> = {},
     ): React.ComponentPropsWithRef<'div'> => {
       return mergeReactProps(externalProps, {
-        'aria-labelledby': undefined,
+        'aria-labelledby': correspondingTabId,
         hidden,
         id: id ?? undefined,
         role: 'tabpanel',
@@ -70,7 +58,7 @@ function useTabPanel(parameters: useTabPanel.Parameters): useTabPanel.ReturnValu
         'data-index': index,
       });
     },
-    [handleRef, hidden, id, index],
+    [correspondingTabId, handleRef, hidden, id, index],
   );
 
   return {
diff --git a/packages/react/src/Tabs/TabsList/TabsList.test.tsx b/packages/react/src/Tabs/TabsList/TabsList.test.tsx
index 1d9c30afa5..115b08dd41 100644
--- a/packages/react/src/Tabs/TabsList/TabsList.test.tsx
+++ b/packages/react/src/Tabs/TabsList/TabsList.test.tsx
@@ -16,6 +16,7 @@ describe('<Tabs.List />', () => {
             value: '1',
             onValueChange: () => {},
             setTabMap() {},
+            getTabElementBySelectedValue: () => null,
             getTabIdByPanelValueOrIndex: () => '',
             getTabPanelIdByTabValueOrIndex: () => '',
             orientation: 'horizontal',
diff --git a/packages/react/src/Tabs/TabsList/TabsList.tsx b/packages/react/src/Tabs/TabsList/TabsList.tsx
index 7a8ff02e6f..6677943654 100644
--- a/packages/react/src/Tabs/TabsList/TabsList.tsx
+++ b/packages/react/src/Tabs/TabsList/TabsList.tsx
@@ -27,6 +27,7 @@ const TabsList = React.forwardRef(function TabsList(
 
   const {
     direction = 'ltr',
+    getTabElementBySelectedValue,
     onValueChange,
     orientation = 'horizontal',
     value,
@@ -39,6 +40,7 @@ const TabsList = React.forwardRef(function TabsList(
   const tabsListRef = React.useRef<HTMLElement>(null);
 
   const { getRootProps, onTabActivation } = useTabsList({
+    getTabElementBySelectedValue,
     onValueChange,
     orientation,
     rootRef: forwardedRef,
diff --git a/packages/react/src/Tabs/TabsList/TabsListContext.ts b/packages/react/src/Tabs/TabsList/TabsListContext.ts
index fc32651eb7..c633fbf979 100644
--- a/packages/react/src/Tabs/TabsList/TabsListContext.ts
+++ b/packages/react/src/Tabs/TabsList/TabsListContext.ts
@@ -3,7 +3,6 @@ import * as React from 'react';
 
 export interface TabsListContext {
   activateOnFocus: boolean;
-  getTabElement: (value: any) => HTMLElement | null;
   highlightedTabIndex: number;
   onTabActivation: (newValue: any, event: Event) => void;
   setHighlightedTabIndex: (index: number) => void;
diff --git a/packages/react/src/Tabs/TabsList/useTabsList.ts b/packages/react/src/Tabs/TabsList/useTabsList.ts
index 40bc3ffbdc..3caaa9bc69 100644
--- a/packages/react/src/Tabs/TabsList/useTabsList.ts
+++ b/packages/react/src/Tabs/TabsList/useTabsList.ts
@@ -6,70 +6,23 @@ import { useForkRef } from '../../utils/useForkRef';
 import { mergeReactProps } from '../../utils/mergeReactProps';
 import { useEnhancedEffect } from '../../utils/useEnhancedEffect';
 import { useEventCallback } from '../../utils/useEventCallback';
-// import { TabsListContext } from './TabsListContext';
 
 function useTabsList(parameters: useTabsList.Parameters): useTabsList.ReturnValue {
   const {
+    getTabElementBySelectedValue,
     onValueChange,
     orientation,
-    // registerGetTabIdByPanelValueOrIndexFn,
     rootRef: externalRef,
     tabsListRef,
     value: selectedTabValue,
   } = parameters;
 
-  // subitems are <Tab>s, their Composite parent is <Tabs.List>
-  // const { subitems } = useCompoundParent<any, TabMetadata>();
-
-  // DON"T NEED THIS ANYMORE
-  //
-  // get id attribute of a Tab by tab value
-  // for binding aria attributes
-  // this function needs to be registered to the context
-  //
-  // const tabIdLookup = React.useCallback(
-  //   (tabValue: any) => {
-  //     return subitems.get(tabValue)?.id;
-  //   },
-  //   [subitems],
-  // );
-
-  // registerGetTabIdByPanelValueOrIndexFn(tabIdLookup);
-
-  // this is a param for useList
-  // const subitemKeys = React.useMemo(() => Array.from(subitems.keys()), [subitems]);
-
-  // get the element/node of a tab by tab value
-  // used as a param for `useActivationDirectionDetector`
-  // TODO: move this to useTabsRoot since tabMap is there
-  const getTabElement = React.useCallback(
-    (tabValue: any) => {
-      if (tabValue == null) {
-        return null;
-      }
-
-      // subitems are <Tab>s, their Composite parent is <Tabs.List>
-      // return subitems.get(tabValue)?.ref.current ?? null;
-      return null;
-    },
-    [
-      /* subitems */
-    ],
-  );
-
-  // let listOrientation: UseListParameters<any, any>['orientation'];
-  // if (orientation === 'vertical') {
-  //   listOrientation = 'vertical';
-  // } else {
-  //   listOrientation = direction === 'rtl' ? 'horizontal-rtl' : 'horizontal-ltr';
-  // }
-
-  // const tabsListRef = React.useRef<HTMLElement>(null);
   const detectActivationDirection = useActivationDirectionDetector(
+    // the old value
     selectedTabValue,
     orientation,
     tabsListRef,
-    getTabElement,
+    getTabElementBySelectedValue,
   );
 
   const onTabActivation = useEventCallback((newValue: any, event: Event) => {
@@ -80,15 +33,6 @@ function useTabsList(parameters: useTabsList.Parameters): useTabsList.ReturnValu
     }
   });
 
-  // const controlledProps = React.useMemo(() => {
-  //   return value != null ? { selectedValues: [value] } : { selectedValues: [] };
-  // }, [value]);
-
-  // const isItemDisabled = React.useCallback(
-  //   (item: any) => subitems.get(item)?.disabled ?? false,
-  //   [subitems],
-  // );
-
   // React.useEffect(() => {
   //   if (value === undefined) {
   //     return;
@@ -134,21 +78,22 @@ function getInset(tab: HTMLElement, tabsList: HTMLElement) {
 }
 
 function useActivationDirectionDetector(
-  value: any,
+  // the old value
+  selectedTabValue: any,
   orientation: TabsOrientation,
   tabsListRef: React.RefObject<HTMLElement | null>,
-  getTabElement: (tabValue: any) => HTMLElement | null,
+  getTabElement: (selectedValue: any) => HTMLElement | null,
 ): (newValue: any) => TabActivationDirection {
   const previousTabEdge = React.useRef<number | null>(null);
 
   useEnhancedEffect(() => {
     // Whenever orientation changes, reset the state.
-    if (value == null || tabsListRef.current == null) {
+    if (selectedTabValue == null || tabsListRef.current == null) {
       previousTabEdge.current = null;
       return;
     }
 
-    const activeTab = getTabElement(value);
+    const activeTab = getTabElement(selectedTabValue);
     if (activeTab == null) {
       previousTabEdge.current = null;
       return;
@@ -156,11 +101,11 @@ function useActivationDirectionDetector(
 
     const { left, top } = getInset(activeTab, tabsListRef.current);
     previousTabEdge.current = orientation === 'horizontal' ? left : top;
-  }, [orientation, getTabElement, tabsListRef, value]);
+  }, [orientation, getTabElement, tabsListRef, selectedTabValue]);
 
   return React.useCallback(
     (newValue: any) => {
-      if (newValue === value) {
+      if (newValue === selectedTabValue) {
         return 'none';
       }
 
@@ -201,13 +146,16 @@ function useActivationDirectionDetector(
 
       return 'none';
     },
-    [getTabElement, orientation, previousTabEdge, tabsListRef, value],
+    [getTabElement, orientation, previousTabEdge, tabsListRef, selectedTabValue],
   );
 }
 
 namespace useTabsList {
   export interface Parameters
-    extends Pick<TabsRootContext, 'onValueChange' | 'orientation' | 'setTabMap' | 'value'> {
+    extends Pick<
+      TabsRootContext,
+      'getTabElementBySelectedValue' | 'onValueChange' | 'orientation' | 'setTabMap' | 'value'
+    > {
     /**
      * Ref to the root element.
      */

From b448258b8c446acdc94fda2cb9032cc691f083cb Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Fri, 15 Nov 2024 20:27:32 +0800
Subject: [PATCH 10/20] Force CompositeRoot to propagate events

---
 packages/react/src/Composite/Root/CompositeRoot.tsx   |  3 +++
 packages/react/src/Composite/Root/useCompositeRoot.ts |  7 ++++++-
 packages/react/src/Tabs/Root/useTabsRoot.ts           | 11 +++++++----
 packages/react/src/Tabs/Tab/useTab.ts                 |  2 +-
 packages/react/src/Tabs/TabsList/TabsList.tsx         |  1 +
 5 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/packages/react/src/Composite/Root/CompositeRoot.tsx b/packages/react/src/Composite/Root/CompositeRoot.tsx
index af8e23e1ea..2c7f396e67 100644
--- a/packages/react/src/Composite/Root/CompositeRoot.tsx
+++ b/packages/react/src/Composite/Root/CompositeRoot.tsx
@@ -27,6 +27,7 @@ const CompositeRoot = React.forwardRef(function CompositeRoot(
     cols,
     enableHomeAndEndKeys,
     onMapChange,
+    alwaysPropagateEvents,
     ...otherProps
   } = props;
 
@@ -39,6 +40,7 @@ const CompositeRoot = React.forwardRef(function CompositeRoot(
     activeIndex: activeIndexProp,
     onActiveIndexChange: onActiveIndexChangeProp,
     rootRef: forwardedRef,
+    alwaysPropagateEvents,
     enableHomeAndEndKeys,
   });
 
@@ -79,6 +81,7 @@ namespace CompositeRoot {
     enableHomeAndEndKeys?: boolean;
     // TODO: can't pass a generic <CustomMetadata> into forwardRef?
     onMapChange?: (newMap: Map<Node, any>) => void;
+    alwaysPropagateEvents?: boolean;
   }
 }
 
diff --git a/packages/react/src/Composite/Root/useCompositeRoot.ts b/packages/react/src/Composite/Root/useCompositeRoot.ts
index ca5a49748f..248cfa0de4 100644
--- a/packages/react/src/Composite/Root/useCompositeRoot.ts
+++ b/packages/react/src/Composite/Root/useCompositeRoot.ts
@@ -45,6 +45,7 @@ export interface UseCompositeRootParameters {
    * @default false
    */
   enableHomeAndEndKeys?: boolean;
+  alwaysPropagateEvents?: boolean;
 }
 
 // Advanced options of Composite, to be implemented later if needed.
@@ -64,6 +65,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
     onActiveIndexChange: externalSetActiveIndex,
     rootRef: externalRef,
     enableHomeAndEndKeys = false,
+    alwaysPropagateEvents = false,
   } = params;
 
   const [internalActiveIndex, internalSetActiveIndex] = React.useState(0);
@@ -219,7 +221,9 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
           }
 
           if (nextIndex !== activeIndex && !isIndexOutOfBounds(elementsRef, nextIndex)) {
-            event.stopPropagation();
+            if (!alwaysPropagateEvents) {
+              event.stopPropagation();
+            }
 
             if (preventedKeys.includes(event.key)) {
               event.preventDefault();
@@ -236,6 +240,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
       }),
     [
       activeIndex,
+      alwaysPropagateEvents,
       cols,
       dense,
       elementsRef,
diff --git a/packages/react/src/Tabs/Root/useTabsRoot.ts b/packages/react/src/Tabs/Root/useTabsRoot.ts
index caf53c9350..ec96c6f5af 100644
--- a/packages/react/src/Tabs/Root/useTabsRoot.ts
+++ b/packages/react/src/Tabs/Root/useTabsRoot.ts
@@ -117,10 +117,13 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
   // used as a param for `useActivationDirectionDetector`
   // put this into TabsRootContext
   // use it in useTabsList
-  const getTabElementBySelectedValue = React.useCallback((selectedValue: any | undefined) => {
-    console.log('getTabElementBySelectedValue', selectedValue);
-    return null;
-  }, []);
+  const getTabElementBySelectedValue = React.useCallback(
+    (/* selectedValue: any | undefined */) => {
+      // console.log('getTabElementBySelectedValue', selectedValue);
+      return null;
+    },
+    [],
+  );
 
   // TODO: no need to put this in a ref anymore?
   const registerGetTabIdByPanelValueOrIndexFn = React.useCallback(
diff --git a/packages/react/src/Tabs/Tab/useTab.ts b/packages/react/src/Tabs/Tab/useTab.ts
index f4699009cf..cc6df77bf4 100644
--- a/packages/react/src/Tabs/Tab/useTab.ts
+++ b/packages/react/src/Tabs/Tab/useTab.ts
@@ -59,7 +59,7 @@ function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
   // FIXME: something is wrong with this
   useEnhancedEffect(() => {
     if (activateOnFocus && selected && index > -1 && highlightedTabIndex !== index) {
-      console.log('useEnhancedEffect update index', index);
+      // console.log('useEnhancedEffect update index', index);
       setHighlightedTabIndex(index);
     }
   }, [activateOnFocus, highlightedTabIndex, index, selected, setHighlightedTabIndex]);
diff --git a/packages/react/src/Tabs/TabsList/TabsList.tsx b/packages/react/src/Tabs/TabsList/TabsList.tsx
index 6677943654..e56277d247 100644
--- a/packages/react/src/Tabs/TabsList/TabsList.tsx
+++ b/packages/react/src/Tabs/TabsList/TabsList.tsx
@@ -96,6 +96,7 @@ const TabsList = React.forwardRef(function TabsList(
        */}
       <CompositeRoot
         activeIndex={highlightedTabIndex}
+        alwaysPropagateEvents
         loop={loop}
         onActiveIndexChange={setHighlightedTabIndex}
         onMapChange={setTabMap}

From 59dc6d9bc5fabda6c6d1cb68c35eabbc9fdde656 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 19 Nov 2024 17:16:15 +0800
Subject: [PATCH 11/20] Fix RTL tests

---
 .../react/src/Tabs/Root/TabsRoot.test.tsx     | 543 +++++++++---------
 packages/react/src/Tabs/TabsList/TabsList.tsx |   1 +
 2 files changed, 278 insertions(+), 266 deletions(-)

diff --git a/packages/react/src/Tabs/Root/TabsRoot.test.tsx b/packages/react/src/Tabs/Root/TabsRoot.test.tsx
index 3a1d74c68a..b29ef0578a 100644
--- a/packages/react/src/Tabs/Root/TabsRoot.test.tsx
+++ b/packages/react/src/Tabs/Root/TabsRoot.test.tsx
@@ -5,6 +5,8 @@ import { act, describeSkipIf, flushMicrotasks, fireEvent, screen } from '@mui/in
 import { Tabs } from '@base-ui-components/react/Tabs';
 import { createRenderer, describeConformance } from '#test-utils';
 
+const isJSDOM = /jsdom/.test(window.navigator.userAgent);
+
 describe('<Tabs.Root />', () => {
   const { render } = createRenderer();
 
@@ -275,188 +277,156 @@ describe('<Tabs.Root />', () => {
     ].forEach((entry) => {
       const [orientation, direction, previousItemKey, nextItemKey] = entry;
 
-      describe(`when focus is on a tab element in a ${orientation} ${direction ?? ''} tablist`, () => {
-        describe(previousItemKey ?? '', () => {
-          describe('with `activateOnFocus = false`', () => {
-            it('moves focus to the last tab without activating it if focus is on the first tab', async () => {
-              const handleChange = spy();
-              const handleKeyDown = spy();
-              const { getAllByRole } = await render(
-                <Tabs.Root
-                  direction={direction as Tabs.Root.Props['direction']}
-                  onValueChange={handleChange}
-                  onKeyDown={handleKeyDown}
-                  orientation={orientation as Tabs.Root.Props['orientation']}
-                  value={0}
-                >
-                  <Tabs.List activateOnFocus={false}>
-                    <Tabs.Tab value={0} />
-                    <Tabs.Tab value={1} />
-                    <Tabs.Tab value={2} />
-                  </Tabs.List>
-                </Tabs.Root>,
-              );
-              const [firstTab, , lastTab] = getAllByRole('tab');
-              await act(async () => {
-                firstTab.focus();
+      describeSkipIf(isJSDOM && direction === 'rtl')(
+        `when focus is on a tab element in a ${orientation} ${direction ?? ''} tablist`,
+        () => {
+          describe(previousItemKey ?? '', () => {
+            describe('with `activateOnFocus = false`', () => {
+              it('moves focus to the last tab without activating it if focus is on the first tab', async () => {
+                const handleChange = spy();
+                const handleKeyDown = spy();
+                const { getAllByRole } = await render(
+                  <Tabs.Root
+                    direction={direction as Tabs.Root.Props['direction']}
+                    onValueChange={handleChange}
+                    onKeyDown={handleKeyDown}
+                    orientation={orientation as Tabs.Root.Props['orientation']}
+                    value={0}
+                  >
+                    <Tabs.List activateOnFocus={false}>
+                      <Tabs.Tab value={0} />
+                      <Tabs.Tab value={1} />
+                      <Tabs.Tab value={2} />
+                    </Tabs.List>
+                  </Tabs.Root>,
+                );
+                const [firstTab, , lastTab] = getAllByRole('tab');
+                await act(async () => {
+                  firstTab.focus();
+                });
+
+                fireEvent.keyDown(firstTab, { key: previousItemKey });
+                await flushMicrotasks();
+
+                expect(lastTab).toHaveFocus();
+                expect(handleChange.callCount).to.equal(0);
+                expect(handleKeyDown.callCount).to.equal(1);
+                expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
               });
 
-              fireEvent.keyDown(firstTab, { key: previousItemKey });
-              await flushMicrotasks();
-
-              expect(lastTab).toHaveFocus();
-              expect(handleChange.callCount).to.equal(0);
-              expect(handleKeyDown.callCount).to.equal(1);
-              expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
-            });
-
-            it('moves focus to the previous tab without activating it', async () => {
-              const handleChange = spy();
-              const handleKeyDown = spy();
-              const { getAllByRole } = await render(
-                <Tabs.Root
-                  direction={direction as Tabs.Root.Props['direction']}
-                  onValueChange={handleChange}
-                  onKeyDown={handleKeyDown}
-                  orientation={orientation as Tabs.Root.Props['orientation']}
-                  value={1}
-                >
-                  <Tabs.List activateOnFocus={false}>
-                    <Tabs.Tab value={0} />
-                    <Tabs.Tab value={1} />
-                    <Tabs.Tab value={2} />
-                  </Tabs.List>
-                </Tabs.Root>,
-              );
-              const [firstTab, secondTab] = getAllByRole('tab');
-              await act(async () => {
-                secondTab.focus();
+              it('moves focus to the previous tab without activating it', async () => {
+                const handleChange = spy();
+                const handleKeyDown = spy();
+                const { getAllByRole } = await render(
+                  <Tabs.Root
+                    direction={direction as Tabs.Root.Props['direction']}
+                    onValueChange={handleChange}
+                    onKeyDown={handleKeyDown}
+                    orientation={orientation as Tabs.Root.Props['orientation']}
+                    value={1}
+                  >
+                    <Tabs.List activateOnFocus={false}>
+                      <Tabs.Tab value={0} />
+                      <Tabs.Tab value={1} />
+                      <Tabs.Tab value={2} />
+                    </Tabs.List>
+                  </Tabs.Root>,
+                );
+                const [firstTab, secondTab] = getAllByRole('tab');
+                await act(async () => {
+                  secondTab.focus();
+                });
+
+                fireEvent.keyDown(secondTab, { key: previousItemKey });
+                await flushMicrotasks();
+
+                expect(firstTab).toHaveFocus();
+                expect(handleChange.callCount).to.equal(0);
+                expect(handleKeyDown.callCount).to.equal(1);
+                expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
               });
-
-              fireEvent.keyDown(secondTab, { key: previousItemKey });
-              await flushMicrotasks();
-
-              expect(firstTab).toHaveFocus();
-              expect(handleChange.callCount).to.equal(0);
-              expect(handleKeyDown.callCount).to.equal(1);
-              expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
             });
-          });
 
-          describe('with `activateOnFocus = true`', () => {
-            it('moves focus to the last tab while activating it if focus is on the first tab', async () => {
-              const handleChange = spy();
-              const handleKeyDown = spy();
-              const { getAllByRole } = await render(
-                <Tabs.Root
-                  direction={direction as Tabs.Root.Props['direction']}
-                  onValueChange={handleChange}
-                  onKeyDown={handleKeyDown}
-                  orientation={orientation as Tabs.Root.Props['orientation']}
-                  value={0}
-                >
-                  <Tabs.List>
-                    <Tabs.Tab value={0} />
-                    <Tabs.Tab value={1} />
-                    <Tabs.Tab value={2} />
-                  </Tabs.List>
-                </Tabs.Root>,
-              );
-              const [firstTab, , lastTab] = getAllByRole('tab');
-              await act(async () => {
-                firstTab.focus();
+            describe('with `activateOnFocus = true`', () => {
+              it('moves focus to the last tab while activating it if focus is on the first tab', async () => {
+                const handleChange = spy();
+                const handleKeyDown = spy();
+                const { getAllByRole } = await render(
+                  <Tabs.Root
+                    direction={direction as Tabs.Root.Props['direction']}
+                    onValueChange={handleChange}
+                    onKeyDown={handleKeyDown}
+                    orientation={orientation as Tabs.Root.Props['orientation']}
+                    value={0}
+                  >
+                    <Tabs.List>
+                      <Tabs.Tab value={0} />
+                      <Tabs.Tab value={1} />
+                      <Tabs.Tab value={2} />
+                    </Tabs.List>
+                  </Tabs.Root>,
+                );
+                const [firstTab, , lastTab] = getAllByRole('tab');
+                await act(async () => {
+                  firstTab.focus();
+                });
+
+                fireEvent.keyDown(firstTab, { key: previousItemKey });
+                await flushMicrotasks();
+
+                expect(lastTab).toHaveFocus();
+                expect(handleChange.callCount).to.equal(1);
+                expect(handleChange.firstCall.args[0]).to.equal(2);
+                expect(handleKeyDown.callCount).to.equal(1);
+                expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
               });
 
-              fireEvent.keyDown(firstTab, { key: previousItemKey });
-              await flushMicrotasks();
-
-              expect(lastTab).toHaveFocus();
-              expect(handleChange.callCount).to.equal(1);
-              expect(handleChange.firstCall.args[0]).to.equal(2);
-              expect(handleKeyDown.callCount).to.equal(1);
-              expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
-            });
-
-            it('moves focus to the previous tab while activating it', async () => {
-              const handleChange = spy();
-              const handleKeyDown = spy();
-              const { getAllByRole } = await render(
-                <Tabs.Root
-                  direction={direction as Tabs.Root.Props['direction']}
-                  onValueChange={handleChange}
-                  onKeyDown={handleKeyDown}
-                  orientation={orientation as Tabs.Root.Props['orientation']}
-                  value={1}
-                >
-                  <Tabs.List>
-                    <Tabs.Tab value={0} />
-                    <Tabs.Tab value={1} />
-                    <Tabs.Tab value={2} />
-                  </Tabs.List>
-                </Tabs.Root>,
-              );
-              const [firstTab, secondTab] = getAllByRole('tab');
-              await act(async () => {
-                secondTab.focus();
+              it('moves focus to the previous tab while activating it', async () => {
+                const handleChange = spy();
+                const handleKeyDown = spy();
+                const { getAllByRole } = await render(
+                  <Tabs.Root
+                    direction={direction as Tabs.Root.Props['direction']}
+                    onValueChange={handleChange}
+                    onKeyDown={handleKeyDown}
+                    orientation={orientation as Tabs.Root.Props['orientation']}
+                    value={1}
+                  >
+                    <Tabs.List>
+                      <Tabs.Tab value={0} />
+                      <Tabs.Tab value={1} />
+                      <Tabs.Tab value={2} />
+                    </Tabs.List>
+                  </Tabs.Root>,
+                );
+                const [firstTab, secondTab] = getAllByRole('tab');
+                await act(async () => {
+                  secondTab.focus();
+                });
+
+                fireEvent.keyDown(secondTab, { key: previousItemKey });
+                await flushMicrotasks();
+
+                expect(firstTab).toHaveFocus();
+                expect(handleChange.callCount).to.equal(1);
+                expect(handleChange.firstCall.args[0]).to.equal(0);
+                expect(handleKeyDown.callCount).to.equal(1);
+                expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
               });
-
-              fireEvent.keyDown(secondTab, { key: previousItemKey });
-              await flushMicrotasks();
-
-              expect(firstTab).toHaveFocus();
-              expect(handleChange.callCount).to.equal(1);
-              expect(handleChange.firstCall.args[0]).to.equal(0);
-              expect(handleKeyDown.callCount).to.equal(1);
-              expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
-            });
-          });
-
-          it('skips over disabled tabs', async () => {
-            const handleKeyDown = spy();
-            const { getAllByRole } = await render(
-              <Tabs.Root
-                direction={direction as Tabs.Root.Props['direction']}
-                onKeyDown={handleKeyDown}
-                orientation={orientation as Tabs.Root.Props['orientation']}
-                value={2}
-              >
-                <Tabs.List>
-                  <Tabs.Tab value={0} />
-                  <Tabs.Tab value={1} disabled />
-                  <Tabs.Tab value={2} />
-                </Tabs.List>
-              </Tabs.Root>,
-            );
-            const [firstTab, , lastTab] = getAllByRole('tab');
-            await act(async () => {
-              lastTab.focus();
             });
 
-            fireEvent.keyDown(lastTab, { key: previousItemKey });
-            await flushMicrotasks();
-
-            expect(firstTab).toHaveFocus();
-            expect(handleKeyDown.callCount).to.equal(1);
-            expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
-          });
-        });
-
-        describe(nextItemKey ?? '', () => {
-          describe('with `activateOnFocus = false`', () => {
-            it('moves focus to the first tab without activating it if focus is on the last tab', async () => {
-              const handleChange = spy();
+            it('skips over disabled tabs', async () => {
               const handleKeyDown = spy();
               const { getAllByRole } = await render(
                 <Tabs.Root
                   direction={direction as Tabs.Root.Props['direction']}
-                  onValueChange={handleChange}
                   onKeyDown={handleKeyDown}
                   orientation={orientation as Tabs.Root.Props['orientation']}
                   value={2}
                 >
-                  <Tabs.List activateOnFocus={false}>
+                  <Tabs.List>
                     <Tabs.Tab value={0} />
-                    <Tabs.Tab value={1} />
+                    <Tabs.Tab value={1} disabled />
                     <Tabs.Tab value={2} />
                   </Tabs.List>
                 </Tabs.Root>,
@@ -466,146 +436,181 @@ describe('<Tabs.Root />', () => {
                 lastTab.focus();
               });
 
-              fireEvent.keyDown(lastTab, { key: nextItemKey });
+              fireEvent.keyDown(lastTab, { key: previousItemKey });
               await flushMicrotasks();
 
               expect(firstTab).toHaveFocus();
-              expect(handleChange.callCount).to.equal(0);
               expect(handleKeyDown.callCount).to.equal(1);
               expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
             });
+          });
 
-            it('moves focus to the next tab without activating it', async () => {
-              const handleChange = spy();
-              const handleKeyDown = spy();
-              const { getAllByRole } = await render(
-                <Tabs.Root
-                  direction={direction as Tabs.Root.Props['direction']}
-                  onValueChange={handleChange}
-                  onKeyDown={handleKeyDown}
-                  orientation={orientation as Tabs.Root.Props['orientation']}
-                  value={1}
-                >
-                  <Tabs.List activateOnFocus={false}>
-                    <Tabs.Tab value={0} />
-                    <Tabs.Tab value={1} />
-                    <Tabs.Tab value={2} />
-                  </Tabs.List>
-                </Tabs.Root>,
-              );
-              const [, secondTab, lastTab] = getAllByRole('tab');
-              await act(async () => {
-                secondTab.focus();
+          describe(nextItemKey ?? '', () => {
+            describe('with `activateOnFocus = false`', () => {
+              it('moves focus to the first tab without activating it if focus is on the last tab', async () => {
+                const handleChange = spy();
+                const handleKeyDown = spy();
+                const { getAllByRole } = await render(
+                  <Tabs.Root
+                    direction={direction as Tabs.Root.Props['direction']}
+                    onValueChange={handleChange}
+                    onKeyDown={handleKeyDown}
+                    orientation={orientation as Tabs.Root.Props['orientation']}
+                    value={2}
+                  >
+                    <Tabs.List activateOnFocus={false}>
+                      <Tabs.Tab value={0} />
+                      <Tabs.Tab value={1} />
+                      <Tabs.Tab value={2} />
+                    </Tabs.List>
+                  </Tabs.Root>,
+                );
+                const [firstTab, , lastTab] = getAllByRole('tab');
+                await act(async () => {
+                  lastTab.focus();
+                });
+
+                fireEvent.keyDown(lastTab, { key: nextItemKey });
+                await flushMicrotasks();
+
+                expect(firstTab).toHaveFocus();
+                expect(handleChange.callCount).to.equal(0);
+                expect(handleKeyDown.callCount).to.equal(1);
+                expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
               });
 
-              fireEvent.keyDown(secondTab, { key: nextItemKey });
-              await flushMicrotasks();
-
-              expect(lastTab).toHaveFocus();
-              expect(handleChange.callCount).to.equal(0);
-              expect(handleKeyDown.callCount).to.equal(1);
-              expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
+              it('moves focus to the next tab without activating it', async () => {
+                const handleChange = spy();
+                const handleKeyDown = spy();
+                const { getAllByRole } = await render(
+                  <Tabs.Root
+                    direction={direction as Tabs.Root.Props['direction']}
+                    onValueChange={handleChange}
+                    onKeyDown={handleKeyDown}
+                    orientation={orientation as Tabs.Root.Props['orientation']}
+                    value={1}
+                  >
+                    <Tabs.List activateOnFocus={false}>
+                      <Tabs.Tab value={0} />
+                      <Tabs.Tab value={1} />
+                      <Tabs.Tab value={2} />
+                    </Tabs.List>
+                  </Tabs.Root>,
+                );
+                const [, secondTab, lastTab] = getAllByRole('tab');
+                await act(async () => {
+                  secondTab.focus();
+                });
+
+                fireEvent.keyDown(secondTab, { key: nextItemKey });
+                await flushMicrotasks();
+
+                expect(lastTab).toHaveFocus();
+                expect(handleChange.callCount).to.equal(0);
+                expect(handleKeyDown.callCount).to.equal(1);
+                expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
+              });
             });
-          });
 
-          describe('with `activateOnFocus = true`', () => {
-            it('moves focus to the first tab while activating it if focus is on the last tab', async () => {
-              const handleChange = spy();
-              const handleKeyDown = spy();
-              const { getAllByRole } = await render(
-                <Tabs.Root
-                  direction={direction as Tabs.Root.Props['direction']}
-                  onValueChange={handleChange}
-                  onKeyDown={handleKeyDown}
-                  orientation={orientation as Tabs.Root.Props['orientation']}
-                  value={2}
-                >
-                  <Tabs.List>
-                    <Tabs.Tab value={0} />
-                    <Tabs.Tab value={1} />
-                    <Tabs.Tab value={2} />
-                  </Tabs.List>
-                </Tabs.Root>,
-              );
-              const [firstTab, , lastTab] = getAllByRole('tab');
-              await act(async () => {
-                lastTab.focus();
+            describe('with `activateOnFocus = true`', () => {
+              it('moves focus to the first tab while activating it if focus is on the last tab', async () => {
+                const handleChange = spy();
+                const handleKeyDown = spy();
+                const { getAllByRole } = await render(
+                  <Tabs.Root
+                    direction={direction as Tabs.Root.Props['direction']}
+                    onValueChange={handleChange}
+                    onKeyDown={handleKeyDown}
+                    orientation={orientation as Tabs.Root.Props['orientation']}
+                    value={2}
+                  >
+                    <Tabs.List>
+                      <Tabs.Tab value={0} />
+                      <Tabs.Tab value={1} />
+                      <Tabs.Tab value={2} />
+                    </Tabs.List>
+                  </Tabs.Root>,
+                );
+                const [firstTab, , lastTab] = getAllByRole('tab');
+                await act(async () => {
+                  lastTab.focus();
+                });
+
+                fireEvent.keyDown(lastTab, { key: nextItemKey });
+                await flushMicrotasks();
+
+                expect(firstTab).toHaveFocus();
+                expect(handleChange.callCount).to.equal(1);
+                expect(handleChange.firstCall.args[0]).to.equal(0);
+                expect(handleKeyDown.callCount).to.equal(1);
+                expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
               });
 
-              fireEvent.keyDown(lastTab, { key: nextItemKey });
-              await flushMicrotasks();
-
-              expect(firstTab).toHaveFocus();
-              expect(handleChange.callCount).to.equal(1);
-              expect(handleChange.firstCall.args[0]).to.equal(0);
-              expect(handleKeyDown.callCount).to.equal(1);
-              expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
+              it('moves focus to the next tab while activating it', async () => {
+                const handleChange = spy();
+                const handleKeyDown = spy();
+                const { getAllByRole } = await render(
+                  <Tabs.Root
+                    direction={direction as Tabs.Root.Props['direction']}
+                    onValueChange={handleChange}
+                    onKeyDown={handleKeyDown}
+                    orientation={orientation as Tabs.Root.Props['orientation']}
+                    value={1}
+                  >
+                    <Tabs.List>
+                      <Tabs.Tab value={0} />
+                      <Tabs.Tab value={1} />
+                      <Tabs.Tab value={2} />
+                    </Tabs.List>
+                  </Tabs.Root>,
+                );
+                const [, secondTab, lastTab] = getAllByRole('tab');
+                await act(async () => {
+                  secondTab.focus();
+                });
+
+                fireEvent.keyDown(secondTab, { key: nextItemKey });
+                await flushMicrotasks();
+
+                expect(lastTab).toHaveFocus();
+                expect(handleChange.callCount).to.equal(1);
+                expect(handleChange.firstCall.args[0]).to.equal(2);
+                expect(handleKeyDown.callCount).to.equal(1);
+                expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
+              });
             });
 
-            it('moves focus to the next tab while activating it', async () => {
-              const handleChange = spy();
+            it('skips over disabled tabs', async () => {
               const handleKeyDown = spy();
               const { getAllByRole } = await render(
                 <Tabs.Root
                   direction={direction as Tabs.Root.Props['direction']}
-                  onValueChange={handleChange}
                   onKeyDown={handleKeyDown}
                   orientation={orientation as Tabs.Root.Props['orientation']}
-                  value={1}
+                  value={0}
                 >
                   <Tabs.List>
                     <Tabs.Tab value={0} />
-                    <Tabs.Tab value={1} />
+                    <Tabs.Tab value={1} disabled />
                     <Tabs.Tab value={2} />
                   </Tabs.List>
                 </Tabs.Root>,
               );
-              const [, secondTab, lastTab] = getAllByRole('tab');
+              const [firstTab, , lastTab] = getAllByRole('tab');
               await act(async () => {
-                secondTab.focus();
+                firstTab.focus();
               });
 
-              fireEvent.keyDown(secondTab, { key: nextItemKey });
+              fireEvent.keyDown(firstTab, { key: nextItemKey });
               await flushMicrotasks();
 
               expect(lastTab).toHaveFocus();
-              expect(handleChange.callCount).to.equal(1);
-              expect(handleChange.firstCall.args[0]).to.equal(2);
               expect(handleKeyDown.callCount).to.equal(1);
               expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
             });
           });
-
-          it('skips over disabled tabs', async () => {
-            const handleKeyDown = spy();
-            const { getAllByRole } = await render(
-              <Tabs.Root
-                direction={direction as Tabs.Root.Props['direction']}
-                onKeyDown={handleKeyDown}
-                orientation={orientation as Tabs.Root.Props['orientation']}
-                value={0}
-              >
-                <Tabs.List>
-                  <Tabs.Tab value={0} />
-                  <Tabs.Tab value={1} disabled />
-                  <Tabs.Tab value={2} />
-                </Tabs.List>
-              </Tabs.Root>,
-            );
-            const [firstTab, , lastTab] = getAllByRole('tab');
-            await act(async () => {
-              firstTab.focus();
-            });
-
-            fireEvent.keyDown(firstTab, { key: nextItemKey });
-            await flushMicrotasks();
-
-            expect(lastTab).toHaveFocus();
-            expect(handleKeyDown.callCount).to.equal(1);
-            expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
-          });
-        });
-      });
+        },
+      );
     });
 
     describe('when focus is on a tab regardless of orientation', () => {
@@ -628,6 +633,7 @@ describe('<Tabs.Root />', () => {
           });
 
           fireEvent.keyDown(lastTab, { key: 'Home' });
+          await flushMicrotasks();
 
           expect(firstTab).toHaveFocus();
           expect(handleChange.callCount).to.equal(0);
@@ -653,6 +659,7 @@ describe('<Tabs.Root />', () => {
           });
 
           fireEvent.keyDown(lastTab, { key: 'Home' });
+          await flushMicrotasks();
 
           expect(firstTab).toHaveFocus();
           expect(handleChange.callCount).to.equal(1);
@@ -678,6 +685,7 @@ describe('<Tabs.Root />', () => {
           });
 
           fireEvent.keyDown(lastTab, { key: 'Home' });
+          await flushMicrotasks();
 
           expect(secondTab).toHaveFocus();
           expect(handleKeyDown.callCount).to.equal(1);
@@ -704,6 +712,7 @@ describe('<Tabs.Root />', () => {
           });
 
           fireEvent.keyDown(firstTab, { key: 'End' });
+          await flushMicrotasks();
 
           expect(lastTab).toHaveFocus();
           expect(handleChange.callCount).to.equal(0);
@@ -729,6 +738,7 @@ describe('<Tabs.Root />', () => {
           });
 
           fireEvent.keyDown(firstTab, { key: 'End' });
+          await flushMicrotasks();
 
           expect(lastTab).toHaveFocus();
           expect(handleChange.callCount).to.equal(1);
@@ -754,6 +764,7 @@ describe('<Tabs.Root />', () => {
           });
 
           fireEvent.keyDown(firstTab, { key: 'End' });
+          await flushMicrotasks();
 
           expect(secondTab).toHaveFocus();
           expect(handleKeyDown.callCount).to.equal(1);
@@ -779,7 +790,7 @@ describe('<Tabs.Root />', () => {
     });
   });
 
-  describeSkipIf(/jsdom/.test(window.navigator.userAgent))('activation direction', () => {
+  describeSkipIf(isJSDOM)('activation direction', () => {
     it('should set the `data-activation-direction` attribute on the tabs root with orientation=horizontal', async () => {
       const { getAllByRole, getByTestId } = await render(
         <Tabs.Root data-testid="root">
diff --git a/packages/react/src/Tabs/TabsList/TabsList.tsx b/packages/react/src/Tabs/TabsList/TabsList.tsx
index e56277d247..8212bc8897 100644
--- a/packages/react/src/Tabs/TabsList/TabsList.tsx
+++ b/packages/react/src/Tabs/TabsList/TabsList.tsx
@@ -97,6 +97,7 @@ const TabsList = React.forwardRef(function TabsList(
       <CompositeRoot
         activeIndex={highlightedTabIndex}
         alwaysPropagateEvents
+        enableHomeAndEndKeys
         loop={loop}
         onActiveIndexChange={setHighlightedTabIndex}
         onMapChange={setTabMap}

From e8bce2395c3695382d1a0fb7578de313be230126 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 19 Nov 2024 19:15:01 +0800
Subject: [PATCH 12/20] Fix tab activation direction

---
 .../react/src/Tabs/Root/TabsRoot.test.tsx     | 12 +++----
 packages/react/src/Tabs/Root/TabsRoot.tsx     |  2 +-
 packages/react/src/Tabs/Root/useTabsRoot.ts   | 22 +++++++-----
 .../react/src/Tabs/TabsList/useTabsList.ts    | 34 ++++++-------------
 4 files changed, 30 insertions(+), 40 deletions(-)

diff --git a/packages/react/src/Tabs/Root/TabsRoot.test.tsx b/packages/react/src/Tabs/Root/TabsRoot.test.tsx
index b29ef0578a..a686c32787 100644
--- a/packages/react/src/Tabs/Root/TabsRoot.test.tsx
+++ b/packages/react/src/Tabs/Root/TabsRoot.test.tsx
@@ -802,17 +802,17 @@ describe('<Tabs.Root />', () => {
       );
 
       const root = getByTestId('root');
-      const tabs = getAllByRole('tab');
+      const [tab1, tab2] = getAllByRole('tab');
 
       expect(root).to.have.attribute('data-activation-direction', 'none');
       await act(async () => {
-        tabs[1].click();
+        tab2.click();
       });
 
       expect(root).to.have.attribute('data-activation-direction', 'right');
 
       await act(async () => {
-        tabs[0].click();
+        tab1.click();
       });
 
       expect(root).to.have.attribute('data-activation-direction', 'left');
@@ -829,17 +829,17 @@ describe('<Tabs.Root />', () => {
       );
 
       const root = getByTestId('root');
-      const tabs = getAllByRole('tab');
+      const [tab1, tab2] = getAllByRole('tab');
 
       expect(root).to.have.attribute('data-activation-direction', 'none');
       await act(async () => {
-        tabs[1].click();
+        tab2.click();
       });
 
       expect(root).to.have.attribute('data-activation-direction', 'down');
 
       await act(async () => {
-        tabs[0].click();
+        tab1.click();
       });
 
       expect(root).to.have.attribute('data-activation-direction', 'up');
diff --git a/packages/react/src/Tabs/Root/TabsRoot.tsx b/packages/react/src/Tabs/Root/TabsRoot.tsx
index a72ec5df52..66aa184aed 100644
--- a/packages/react/src/Tabs/Root/TabsRoot.tsx
+++ b/packages/react/src/Tabs/Root/TabsRoot.tsx
@@ -24,7 +24,7 @@ const TabsRoot = React.forwardRef(function TabsRoot(
 ) {
   const {
     className,
-    defaultValue,
+    defaultValue = 0,
     direction: directionProp = 'ltr',
     onValueChange: onValueChangeProp,
     orientation = 'horizontal',
diff --git a/packages/react/src/Tabs/Root/useTabsRoot.ts b/packages/react/src/Tabs/Root/useTabsRoot.ts
index ec96c6f5af..ab4452e507 100644
--- a/packages/react/src/Tabs/Root/useTabsRoot.ts
+++ b/packages/react/src/Tabs/Root/useTabsRoot.ts
@@ -85,8 +85,6 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
       }
 
       for (const tabMetadata of tabMap.values()) {
-        // console.log(tabPanelValue, index, tabMetadata);
-
         // find by tabPanelValue
         if (
           tabPanelValue !== undefined &&
@@ -113,16 +111,22 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
     [tabMap],
   );
 
-  // FIXME
-  // used as a param for `useActivationDirectionDetector`
-  // put this into TabsRootContext
-  // use it in useTabsList
+  // used in `useActivationDirectionDetector` for setting data-activation-direction
   const getTabElementBySelectedValue = React.useCallback(
-    (/* selectedValue: any | undefined */) => {
-      // console.log('getTabElementBySelectedValue', selectedValue);
+    (selectedValue: any | undefined): HTMLElement | null => {
+      if (selectedValue === undefined) {
+        return null;
+      }
+
+      for (const [tabElement, tabMetadata] of tabMap.entries()) {
+        if (tabMetadata != null && selectedValue === (tabMetadata.value ?? tabMetadata.index)) {
+          return tabElement as HTMLElement;
+        }
+      }
+
       return null;
     },
-    [],
+    [tabMap],
   );
 
   // TODO: no need to put this in a ref anymore?
diff --git a/packages/react/src/Tabs/TabsList/useTabsList.ts b/packages/react/src/Tabs/TabsList/useTabsList.ts
index 3caaa9bc69..f574cec7ca 100644
--- a/packages/react/src/Tabs/TabsList/useTabsList.ts
+++ b/packages/react/src/Tabs/TabsList/useTabsList.ts
@@ -26,38 +26,24 @@ function useTabsList(parameters: useTabsList.Parameters): useTabsList.ReturnValu
   );
 
   const onTabActivation = useEventCallback((newValue: any, event: Event) => {
-    // console.log('onTabActivation()', newValue, event.target);
     if (newValue !== selectedTabValue) {
       const activationDirection = detectActivationDirection(newValue);
       onValueChange(newValue, activationDirection, event);
     }
   });
 
-  // React.useEffect(() => {
-  //   if (value === undefined) {
-  //     return;
-  //   }
-
-  //   // when a value changes externally, the highlighted value should be synced to it
-  //   if (value != null) {
-  //     dispatch({
-  //       type: TabsListActionTypes.valueChange,
-  //       value,
-  //     });
-  //   }
-  // }, [dispatch, value]);
-
   const handleRef = useForkRef(tabsListRef, externalRef);
 
-  const getRootProps = (
-    externalProps: React.ComponentPropsWithoutRef<'div'> = {},
-  ): React.ComponentPropsWithRef<'div'> => {
-    return mergeReactProps(externalProps, {
-      'aria-orientation': orientation === 'vertical' ? 'vertical' : undefined,
-      ref: handleRef,
-      role: 'tablist',
-    });
-  };
+  const getRootProps = React.useCallback(
+    (otherProps = {}): React.ComponentPropsWithRef<'div'> => {
+      return mergeReactProps(otherProps, {
+        'aria-orientation': orientation === 'vertical' ? 'vertical' : undefined,
+        ref: handleRef,
+        role: 'tablist',
+      });
+    },
+    [handleRef, orientation],
+  );
 
   return {
     getRootProps,

From 1e5db24668bfa6e3323207e9214dd8d52cb009c9 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 20 Nov 2024 13:34:54 +0800
Subject: [PATCH 13/20] Cleanup

---
 .../src/Composite/List/CompositeList.tsx      | 12 +++++-----
 .../src/Composite/Root/CompositeRoot.tsx      | 24 ++++++++++---------
 .../src/Composite/Root/useCompositeRoot.ts    | 13 ++++++----
 packages/react/src/Tabs/Root/TabsRoot.tsx     |  5 +---
 packages/react/src/Tabs/Root/useTabsRoot.ts   | 18 --------------
 packages/react/src/Tabs/Tab/useTab.ts         |  5 ++--
 packages/react/src/Tabs/TabsList/TabsList.tsx | 12 +++-------
 7 files changed, 34 insertions(+), 55 deletions(-)

diff --git a/packages/react/src/Composite/List/CompositeList.tsx b/packages/react/src/Composite/List/CompositeList.tsx
index 9fc547cd47..f4fae4da4a 100644
--- a/packages/react/src/Composite/List/CompositeList.tsx
+++ b/packages/react/src/Composite/List/CompositeList.tsx
@@ -23,11 +23,11 @@ function sortByDocumentPosition(a: Node, b: Node) {
   return 0;
 }
 
-export type BaseMetadata = { index?: number | null };
+export type CompositeMetadata<CustomMetadata> = { index?: number | null } & CustomMetadata;
 
 function areMapsEqual<CustomMetadata>(
-  map1: Map<Node, (BaseMetadata & CustomMetadata) | null>,
-  map2: Map<Node, (BaseMetadata & CustomMetadata) | null>,
+  map1: Map<Node, CompositeMetadata<CustomMetadata> | null>,
+  map2: Map<Node, CompositeMetadata<CustomMetadata> | null>,
 ) {
   if (map1.size !== map2.size) {
     return false;
@@ -53,7 +53,7 @@ function CompositeList<CustomMetadata>(props: CompositeList.Props<CustomMetadata
   const { children, elementsRef, labelsRef, onMapChange } = props;
 
   const [map, setMap] = React.useState(
-    () => new Map<Node, (BaseMetadata & CustomMetadata) | null>(),
+    () => new Map<Node, CompositeMetadata<CustomMetadata> | null>(),
   );
 
   const register = React.useCallback((node: Node, metadata: CustomMetadata) => {
@@ -74,7 +74,7 @@ function CompositeList<CustomMetadata>(props: CompositeList.Props<CustomMetadata
     const nodes = Array.from(newMap.keys()).sort(sortByDocumentPosition);
 
     nodes.forEach((node, index) => {
-      const metadata = map.get(node) ?? ({} as BaseMetadata & CustomMetadata);
+      const metadata = map.get(node) ?? ({} as CompositeMetadata<CustomMetadata>);
 
       newMap.set(node, { ...metadata, index });
     });
@@ -108,7 +108,7 @@ namespace CompositeList {
      * `useTypeahead`'s `listRef` prop.
      */
     labelsRef?: React.RefObject<Array<string | null>>;
-    onMapChange?: (newMap: Map<Node, (BaseMetadata & CustomMetadata) | null>) => void;
+    onMapChange?: (newMap: Map<Node, CompositeMetadata<CustomMetadata> | null>) => void;
   }
 }
 
diff --git a/packages/react/src/Composite/Root/CompositeRoot.tsx b/packages/react/src/Composite/Root/CompositeRoot.tsx
index 2c7f396e67..c493631d2f 100644
--- a/packages/react/src/Composite/Root/CompositeRoot.tsx
+++ b/packages/react/src/Composite/Root/CompositeRoot.tsx
@@ -2,7 +2,7 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
-import { CompositeList } from '../List/CompositeList';
+import { CompositeList, type CompositeMetadata } from '../List/CompositeList';
 import { useCompositeRoot } from './useCompositeRoot';
 import { CompositeRootContext } from './CompositeRootContext';
 import type { BaseUIComponentProps } from '../../utils/types';
@@ -11,8 +11,8 @@ import type { Dimensions } from '../composite';
 /**
  * @ignore - internal component.
  */
-const CompositeRoot = React.forwardRef(function CompositeRoot(
-  props: CompositeRoot.Props,
+const CompositeRoot = React.forwardRef(function CompositeRoot<CustomMetadata extends {}>(
+  props: CompositeRoot.Props<CustomMetadata>,
   forwardedRef: React.ForwardedRef<HTMLDivElement>,
 ) {
   const {
@@ -27,7 +27,7 @@ const CompositeRoot = React.forwardRef(function CompositeRoot(
     cols,
     enableHomeAndEndKeys,
     onMapChange,
-    alwaysPropagateEvents,
+    stopEventPropagation,
     ...otherProps
   } = props;
 
@@ -40,7 +40,7 @@ const CompositeRoot = React.forwardRef(function CompositeRoot(
     activeIndex: activeIndexProp,
     onActiveIndexChange: onActiveIndexChangeProp,
     rootRef: forwardedRef,
-    alwaysPropagateEvents,
+    stopEventPropagation,
     enableHomeAndEndKeys,
   });
 
@@ -60,17 +60,20 @@ const CompositeRoot = React.forwardRef(function CompositeRoot(
 
   return (
     <CompositeRootContext.Provider value={contextValue}>
-      <CompositeList elementsRef={elementsRef} onMapChange={onMapChange}>
+      <CompositeList<CustomMetadata> elementsRef={elementsRef} onMapChange={onMapChange}>
         {renderElement()}
       </CompositeList>
     </CompositeRootContext.Provider>
   );
-});
+}) as {
+  <CustomMetadata extends {}>(props: CompositeRoot.Props<CustomMetadata>): React.JSX.Element | null;
+  propTypes?: any;
+};
 
 namespace CompositeRoot {
   export interface OwnerState {}
 
-  export interface Props extends BaseUIComponentProps<'div', OwnerState> {
+  export interface Props<CustomMetadata> extends BaseUIComponentProps<'div', OwnerState> {
     orientation?: 'horizontal' | 'vertical' | 'both';
     cols?: number;
     loop?: boolean;
@@ -79,9 +82,8 @@ namespace CompositeRoot {
     itemSizes?: Dimensions[];
     dense?: boolean;
     enableHomeAndEndKeys?: boolean;
-    // TODO: can't pass a generic <CustomMetadata> into forwardRef?
-    onMapChange?: (newMap: Map<Node, any>) => void;
-    alwaysPropagateEvents?: boolean;
+    onMapChange?: (newMap: Map<Node, CompositeMetadata<CustomMetadata> | null>) => void;
+    stopEventPropagation?: boolean;
   }
 }
 
diff --git a/packages/react/src/Composite/Root/useCompositeRoot.ts b/packages/react/src/Composite/Root/useCompositeRoot.ts
index 248cfa0de4..73c1589246 100644
--- a/packages/react/src/Composite/Root/useCompositeRoot.ts
+++ b/packages/react/src/Composite/Root/useCompositeRoot.ts
@@ -45,7 +45,12 @@ export interface UseCompositeRootParameters {
    * @default false
    */
   enableHomeAndEndKeys?: boolean;
-  alwaysPropagateEvents?: boolean;
+  /**
+   * When `true`, keypress events on Composite's navigation keys
+   * be stopped with event.stopPropagation()
+   * @default false
+   */
+  stopEventPropagation?: boolean;
 }
 
 // Advanced options of Composite, to be implemented later if needed.
@@ -65,7 +70,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
     onActiveIndexChange: externalSetActiveIndex,
     rootRef: externalRef,
     enableHomeAndEndKeys = false,
-    alwaysPropagateEvents = false,
+    stopEventPropagation = false,
   } = params;
 
   const [internalActiveIndex, internalSetActiveIndex] = React.useState(0);
@@ -221,7 +226,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
           }
 
           if (nextIndex !== activeIndex && !isIndexOutOfBounds(elementsRef, nextIndex)) {
-            if (!alwaysPropagateEvents) {
+            if (stopEventPropagation) {
               event.stopPropagation();
             }
 
@@ -240,7 +245,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
       }),
     [
       activeIndex,
-      alwaysPropagateEvents,
+      stopEventPropagation,
       cols,
       dense,
       elementsRef,
diff --git a/packages/react/src/Tabs/Root/TabsRoot.tsx b/packages/react/src/Tabs/Root/TabsRoot.tsx
index 66aa184aed..8613548739 100644
--- a/packages/react/src/Tabs/Root/TabsRoot.tsx
+++ b/packages/react/src/Tabs/Root/TabsRoot.tsx
@@ -40,7 +40,6 @@ const TabsRoot = React.forwardRef(function TabsRoot(
     getTabIdByPanelValueOrIndex,
     getTabPanelIdByTabValueOrIndex,
     onValueChange,
-    registerGetTabIdByPanelValueOrIndexFn,
     setTabMap,
     setTabPanelMap,
     tabActivationDirection,
@@ -53,7 +52,7 @@ const TabsRoot = React.forwardRef(function TabsRoot(
     direction: directionProp,
   });
 
-  const tabsContextValue = React.useMemo(
+  const tabsContextValue: TabsRootContext = React.useMemo(
     () => ({
       direction,
       getTabElementBySelectedValue,
@@ -61,7 +60,6 @@ const TabsRoot = React.forwardRef(function TabsRoot(
       getTabPanelIdByTabValueOrIndex,
       onValueChange,
       orientation,
-      registerGetTabIdByPanelValueOrIndexFn,
       setTabMap,
       tabActivationDirection,
       value,
@@ -73,7 +71,6 @@ const TabsRoot = React.forwardRef(function TabsRoot(
       getTabPanelIdByTabValueOrIndex,
       onValueChange,
       orientation,
-      registerGetTabIdByPanelValueOrIndexFn,
       setTabMap,
       tabActivationDirection,
       value,
diff --git a/packages/react/src/Tabs/Root/useTabsRoot.ts b/packages/react/src/Tabs/Root/useTabsRoot.ts
index ab4452e507..91f2c22814 100644
--- a/packages/react/src/Tabs/Root/useTabsRoot.ts
+++ b/packages/react/src/Tabs/Root/useTabsRoot.ts
@@ -6,8 +6,6 @@ import type { TabPanelMetadata } from '../TabPanel/useTabPanel';
 import type { TabMetadata } from '../Tab/useTab';
 import type { TabActivationDirection } from './TabsRoot';
 
-type IdLookupFunction = (id: any) => string | undefined;
-
 function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValue {
   const {
     value: valueProp,
@@ -17,7 +15,6 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
   } = parameters;
 
   const tabPanelRefs = React.useRef<(HTMLElement | null)[]>([]);
-  const getTabIdByPanelValueOrIndexRef = React.useRef<IdLookupFunction>(() => undefined);
 
   const [value, setValue] = useControlled({
     controlled: valueProp,
@@ -129,14 +126,6 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
     [tabMap],
   );
 
-  // TODO: no need to put this in a ref anymore?
-  const registerGetTabIdByPanelValueOrIndexFn = React.useCallback(
-    (lookupFunction: IdLookupFunction) => {
-      getTabIdByPanelValueOrIndexRef.current = lookupFunction;
-    },
-    [],
-  );
-
   const getRootProps: useTabsRoot.ReturnValue['getRootProps'] = React.useCallback(
     (otherProps = {}) =>
       mergeReactProps<'div'>(otherProps, {
@@ -152,7 +141,6 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
     getTabIdByPanelValueOrIndex,
     getTabPanelIdByTabValueOrIndex,
     onValueChange,
-    registerGetTabIdByPanelValueOrIndexFn,
     setTabMap,
     setTabPanelMap,
     tabActivationDirection,
@@ -219,12 +207,6 @@ namespace useTabsRoot {
       activationDirection: TabActivationDirection,
       event: Event,
     ) => void;
-    /**
-     * Registers a function that returns the id of the tab with the given value.
-     */
-    registerGetTabIdByPanelValueOrIndexFn: (
-      lookupFunction: (id: any) => string | undefined,
-    ) => void;
     setTabMap: (map: Map<Node, (TabMetadata & { index?: number | null }) | null>) => void;
     setTabPanelMap: (map: Map<Node, (TabPanelMetadata & { index?: number | null }) | null>) => void;
     /**
diff --git a/packages/react/src/Tabs/Tab/useTab.ts b/packages/react/src/Tabs/Tab/useTab.ts
index cc6df77bf4..644d776074 100644
--- a/packages/react/src/Tabs/Tab/useTab.ts
+++ b/packages/react/src/Tabs/Tab/useTab.ts
@@ -55,11 +55,10 @@ function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
     return valueParam === selectedTabValue;
   }, [index, selectedTabValue, valueParam]);
 
-  // ensure the active item in Composite's roving focus group matches the selected Tab
-  // FIXME: something is wrong with this
+  // when activateOnFocus is `true`, ensure the active item in Composite's roving
+  // focus group matches the selected Tab
   useEnhancedEffect(() => {
     if (activateOnFocus && selected && index > -1 && highlightedTabIndex !== index) {
-      // console.log('useEnhancedEffect update index', index);
       setHighlightedTabIndex(index);
     }
   }, [activateOnFocus, highlightedTabIndex, index, selected, setHighlightedTabIndex]);
diff --git a/packages/react/src/Tabs/TabsList/TabsList.tsx b/packages/react/src/Tabs/TabsList/TabsList.tsx
index 8212bc8897..7520b0c3ac 100644
--- a/packages/react/src/Tabs/TabsList/TabsList.tsx
+++ b/packages/react/src/Tabs/TabsList/TabsList.tsx
@@ -6,6 +6,7 @@ import { CompositeRoot } from '../../Composite/Root/CompositeRoot';
 import { tabsStyleHookMapping } from '../Root/styleHooks';
 import { useTabsRootContext } from '../Root/TabsRootContext';
 import { TabsRoot } from '../Root/TabsRoot';
+import { type TabMetadata } from '../Tab/useTab';
 import { useTabsList } from './useTabsList';
 import { TabsListContext } from './TabsListContext';
 
@@ -67,12 +68,11 @@ const TabsList = React.forwardRef(function TabsList(
     customStyleHookMapping: tabsStyleHookMapping,
   });
 
-  const tabsListContextValue = React.useMemo(
+  const tabsListContextValue: TabsListContext = React.useMemo(
     () => ({
       activateOnFocus,
       highlightedTabIndex,
       onTabActivation,
-      // getTabElement,
       setHighlightedTabIndex,
       tabsListRef,
       value,
@@ -81,7 +81,6 @@ const TabsList = React.forwardRef(function TabsList(
       activateOnFocus,
       highlightedTabIndex,
       onTabActivation,
-      // getTabElement,
       setHighlightedTabIndex,
       tabsListRef,
       value,
@@ -90,13 +89,8 @@ const TabsList = React.forwardRef(function TabsList(
 
   return (
     <TabsListContext.Provider value={tabsListContextValue}>
-      {/*
-        TODO: pass `direction` prop to `rtl` prop of CompositeRoot when
-        https://github.com/mui/base-ui/pull/763 is merged
-       */}
-      <CompositeRoot
+      <CompositeRoot<TabMetadata>
         activeIndex={highlightedTabIndex}
-        alwaysPropagateEvents
         enableHomeAndEndKeys
         loop={loop}
         onActiveIndexChange={setHighlightedTabIndex}

From 76610be4c15e7b51d39da96492e2e89b8e566c7f Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 20 Nov 2024 18:47:10 +0800
Subject: [PATCH 14/20] Update proptypes and docs

---
 docs/data/api/tabs-root.json                  |  2 +-
 docs/data/translations/api-docs/tab/tab.json  |  2 +-
 .../api-docs/tabs-root/tabs-root.json         |  4 +-
 docs/reference/generated/tab.json             |  2 +-
 docs/reference/generated/tabs-root.json       |  5 +-
 .../src/Composite/List/CompositeList.tsx      |  4 ++
 .../src/Composite/Root/CompositeRoot.tsx      |  8 +++
 packages/react/src/Tabs/Root/TabsRoot.tsx     | 60 +++++++++++++++--
 .../react/src/Tabs/Root/TabsRootContext.ts    | 27 ++++----
 packages/react/src/Tabs/Root/useTabsRoot.ts   | 64 ++++++++++---------
 packages/react/src/Tabs/Tab/Tab.tsx           | 40 +++++++++++-
 packages/react/src/Tabs/Tab/useTab.ts         |  6 +-
 .../src/Tabs/TabIndicator/TabIndicator.tsx    | 27 ++++++++
 .../src/Tabs/TabIndicator/useTabIndicator.ts  | 10 ++-
 packages/react/src/Tabs/TabPanel/TabPanel.tsx | 35 +++++++++-
 .../react/src/Tabs/TabPanel/useTabPanel.ts    | 20 +++---
 packages/react/src/Tabs/TabsList/TabsList.tsx | 33 ++++++++++
 .../react/src/Tabs/TabsList/useTabsList.ts    | 13 ++--
 18 files changed, 279 insertions(+), 83 deletions(-)

diff --git a/docs/data/api/tabs-root.json b/docs/data/api/tabs-root.json
index 7e6b2588ee..3f5059c7f8 100644
--- a/docs/data/api/tabs-root.json
+++ b/docs/data/api/tabs-root.json
@@ -1,7 +1,7 @@
 {
   "props": {
     "className": { "type": { "name": "union", "description": "func<br>&#124;&nbsp;string" } },
-    "defaultValue": { "type": { "name": "any" } },
+    "defaultValue": { "type": { "name": "any" }, "default": "0" },
     "direction": {
       "type": { "name": "enum", "description": "'ltr'<br>&#124;&nbsp;'rtl'" },
       "default": "'ltr'"
diff --git a/docs/data/translations/api-docs/tab/tab.json b/docs/data/translations/api-docs/tab/tab.json
index d486100235..5eff531661 100644
--- a/docs/data/translations/api-docs/tab/tab.json
+++ b/docs/data/translations/api-docs/tab/tab.json
@@ -6,7 +6,7 @@
     },
     "render": { "description": "A function to customize rendering of the component." },
     "value": {
-      "description": "You can provide your own value. Otherwise, it falls back to the child position index."
+      "description": "The value of the Tab. When not specified, the value is the child position index."
     }
   },
   "classDescriptions": {}
diff --git a/docs/data/translations/api-docs/tabs-root/tabs-root.json b/docs/data/translations/api-docs/tabs-root/tabs-root.json
index 5800f4b6b4..27020d8d4f 100644
--- a/docs/data/translations/api-docs/tabs-root/tabs-root.json
+++ b/docs/data/translations/api-docs/tabs-root/tabs-root.json
@@ -5,14 +5,14 @@
       "description": "Class names applied to the element or a function that returns them based on the component&#39;s state."
     },
     "defaultValue": {
-      "description": "The default value. Use when the component is not controlled."
+      "description": "The default value. Use when the component is not controlled. When the value is <code>null</code>, no Tab will be selected."
     },
     "direction": { "description": "The direction of the text." },
     "onValueChange": { "description": "Callback invoked when new value is being set." },
     "orientation": { "description": "The component orientation (layout flow direction)." },
     "render": { "description": "A function to customize rendering of the component." },
     "value": {
-      "description": "The value of the currently selected <code>Tab</code>. If you don&#39;t want any selected <code>Tab</code>, you can set this prop to <code>null</code>."
+      "description": "The value of the currently selected <code>Tab</code>. Use when the component is controlled. When the value is <code>null</code>, no Tab will be selected."
     }
   },
   "classDescriptions": {}
diff --git a/docs/reference/generated/tab.json b/docs/reference/generated/tab.json
index 733e416638..bf941b933d 100644
--- a/docs/reference/generated/tab.json
+++ b/docs/reference/generated/tab.json
@@ -12,7 +12,7 @@
     },
     "value": {
       "type": "any",
-      "description": "You can provide your own value. Otherwise, it falls back to the child position index."
+      "description": "The value of the Tab.\nWhen not specified, the value is the child position index."
     }
   }
 }
diff --git a/docs/reference/generated/tabs-root.json b/docs/reference/generated/tabs-root.json
index fbef93c3f9..33998d6c74 100644
--- a/docs/reference/generated/tabs-root.json
+++ b/docs/reference/generated/tabs-root.json
@@ -8,7 +8,8 @@
     },
     "defaultValue": {
       "type": "any",
-      "description": "The default value. Use when the component is not controlled."
+      "default": "0",
+      "description": "The default value. Use when the component is not controlled.\nWhen the value is `null`, no Tab will be selected."
     },
     "direction": {
       "type": "'ltr' | 'rtl'",
@@ -30,7 +31,7 @@
     },
     "value": {
       "type": "any",
-      "description": "The value of the currently selected `Tab`.\nIf you don't want any selected `Tab`, you can set this prop to `null`."
+      "description": "The value of the currently selected `Tab`. Use when the component is controlled.\nWhen the value is `null`, no Tab will be selected."
     }
   }
 }
diff --git a/packages/react/src/Composite/List/CompositeList.tsx b/packages/react/src/Composite/List/CompositeList.tsx
index f4fae4da4a..f3eca29708 100644
--- a/packages/react/src/Composite/List/CompositeList.tsx
+++ b/packages/react/src/Composite/List/CompositeList.tsx
@@ -133,6 +133,10 @@ CompositeList.propTypes /* remove-proptypes */ = {
   labelsRef: PropTypes.shape({
     current: PropTypes.arrayOf(PropTypes.string).isRequired,
   }),
+  /**
+   * @ignore
+   */
+  onMapChange: PropTypes.func,
 } as any;
 
 export { CompositeList };
diff --git a/packages/react/src/Composite/Root/CompositeRoot.tsx b/packages/react/src/Composite/Root/CompositeRoot.tsx
index c493631d2f..c8d3f4ae8e 100644
--- a/packages/react/src/Composite/Root/CompositeRoot.tsx
+++ b/packages/react/src/Composite/Root/CompositeRoot.tsx
@@ -133,6 +133,10 @@ CompositeRoot.propTypes /* remove-proptypes */ = {
    * @ignore
    */
   onActiveIndexChange: PropTypes.func,
+  /**
+   * @ignore
+   */
+  onMapChange: PropTypes.func,
   /**
    * @ignore
    */
@@ -141,6 +145,10 @@ CompositeRoot.propTypes /* remove-proptypes */ = {
    * A function to customize rendering of the component.
    */
   render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  /**
+   * @ignore
+   */
+  stopEventPropagation: PropTypes.bool,
 } as any;
 
 export { CompositeRoot };
diff --git a/packages/react/src/Tabs/Root/TabsRoot.tsx b/packages/react/src/Tabs/Root/TabsRoot.tsx
index 8613548739..d116918f1a 100644
--- a/packages/react/src/Tabs/Root/TabsRoot.tsx
+++ b/packages/react/src/Tabs/Root/TabsRoot.tsx
@@ -1,5 +1,6 @@
 'use client';
 import * as React from 'react';
+import PropTypes from 'prop-types';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import type { BaseUIComponentProps } from '../../utils/types';
 import { CompositeList } from '../../Composite/List/CompositeList';
@@ -102,11 +103,56 @@ const TabsRoot = React.forwardRef(function TabsRoot(
   );
 });
 
+TabsRoot.propTypes /* remove-proptypes */ = {
+  // ┌────────────────────────────── Warning ──────────────────────────────┐
+  // │ These PropTypes are generated from the TypeScript type definitions. │
+  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
+  // └─────────────────────────────────────────────────────────────────────┘
+  /**
+   * @ignore
+   */
+  children: PropTypes.node,
+  /**
+   * Class names applied to the element or a function that returns them based on the component's state.
+   */
+  className: PropTypes.oneOfType([PropTypes.func, PropTypes.string]),
+  /**
+   * The default value. Use when the component is not controlled.
+   * When the value is `null`, no Tab will be selected.
+   * @default 0
+   */
+  defaultValue: PropTypes.any,
+  /**
+   * The direction of the text.
+   * @default 'ltr'
+   */
+  direction: PropTypes.oneOf(['ltr', 'rtl']),
+  /**
+   * Callback invoked when new value is being set.
+   */
+  onValueChange: PropTypes.func,
+  /**
+   * The component orientation (layout flow direction).
+   * @default 'horizontal'
+   */
+  orientation: PropTypes.oneOf(['horizontal', 'vertical']),
+  /**
+   * A function to customize rendering of the component.
+   */
+  render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  /**
+   * The value of the currently selected `Tab`. Use when the component is controlled.
+   * When the value is `null`, no Tab will be selected.
+   */
+  value: PropTypes.any,
+} as any;
+
 export { TabsRoot };
 
 export type TabsOrientation = 'horizontal' | 'vertical';
 export type TabsDirection = 'ltr' | 'rtl';
 export type TabActivationDirection = 'left' | 'right' | 'up' | 'down' | 'none';
+export type TabValue = any | null;
 
 namespace TabsRoot {
   export type OwnerState = {
@@ -115,16 +161,18 @@ namespace TabsRoot {
     tabActivationDirection: TabActivationDirection;
   };
 
-  export interface Props extends BaseUIComponentProps<'div', OwnerState> {
+  export interface Props extends Omit<BaseUIComponentProps<'div', OwnerState>, 'defaultValue'> {
     /**
-     * The value of the currently selected `Tab`.
-     * If you don't want any selected `Tab`, you can set this prop to `null`.
+     * The value of the currently selected `Tab`. Use when the component is controlled.
+     * When the value is `null`, no Tab will be selected.
      */
-    value?: any | null;
+    value?: TabValue;
     /**
      * The default value. Use when the component is not controlled.
+     * When the value is `null`, no Tab will be selected.
+     * @default 0
      */
-    defaultValue?: any | null;
+    defaultValue?: TabValue;
     /**
      * The component orientation (layout flow direction).
      * @default 'horizontal'
@@ -138,6 +186,6 @@ namespace TabsRoot {
     /**
      * Callback invoked when new value is being set.
      */
-    onValueChange?: (value: any | null, event?: Event) => void;
+    onValueChange?: (value: TabValue, event?: Event) => void;
   }
 }
diff --git a/packages/react/src/Tabs/Root/TabsRootContext.ts b/packages/react/src/Tabs/Root/TabsRootContext.ts
index b68d5f128e..5797e146d9 100644
--- a/packages/react/src/Tabs/Root/TabsRootContext.ts
+++ b/packages/react/src/Tabs/Root/TabsRootContext.ts
@@ -1,18 +1,18 @@
 'use client';
 import * as React from 'react';
 import { type TabMetadata } from '../Tab/useTab';
-import { type TabActivationDirection } from './TabsRoot';
+import type { TabActivationDirection, TabValue } from './TabsRoot';
 
 export interface TabsRootContext {
   /**
    * The currently selected tab's value.
    */
-  value: any | null;
+  value: TabValue;
   /**
    * Callback for setting new value.
    */
   onValueChange: (
-    value: any | null,
+    value: TabValue,
     activationDirection: TabActivationDirection,
     event: Event,
   ) => void;
@@ -25,18 +25,23 @@ export interface TabsRootContext {
    */
   direction: 'ltr' | 'rtl';
   /**
-   * Registers a function that returns the id of the tab with the given value.
+   * Gets the element of the Tab with the given value.
+   * @param {any | undefined} value Value to find the tab for.
    */
-  // registerGetTabIdByPanelValueOrIndexFn?: (lookupFunction: (id: any) => string | undefined) => void;
-  getTabElementBySelectedValue: (selectedValue: any | undefined) => HTMLElement | null;
+  getTabElementBySelectedValue: (selectedValue: TabValue | undefined) => HTMLElement | null;
   /**
-   * Gets the id of the tab with the given value.
-   * @param {any | undefined} value Value to find the tab for.
+   * Gets the `id` attribute of the Tab that corresponds to the given TabPanel value or index.
+   * @param (any | undefined) panelValue Value to find the Tab for.
+   * @param (number) index The index of the TabPanel to look for.
    */
-  getTabIdByPanelValueOrIndex: (panelValue: any | undefined, index: number) => string | undefined;
+  getTabIdByPanelValueOrIndex: (
+    panelValue: TabValue | undefined,
+    index: number,
+  ) => string | undefined;
   /**
-   * Gets the id of the tab panel with the given value.
-   * @param {any | undefined} value Value to find the tab panel for.
+   * Gets the `id` attribute of the TabPanel that corresponds to the given Tab value or index.
+   * @param (any | undefined) tabValue Value to find the Tab for.
+   * @param (number) index The index of the Tab to look for.
    */
   getTabPanelIdByTabValueOrIndex: (tabValue: any, index: number) => string | undefined;
   setTabMap: (map: Map<Node, (TabMetadata & { index?: number | null }) | null>) => void;
diff --git a/packages/react/src/Tabs/Root/useTabsRoot.ts b/packages/react/src/Tabs/Root/useTabsRoot.ts
index 91f2c22814..1594ffb5dc 100644
--- a/packages/react/src/Tabs/Root/useTabsRoot.ts
+++ b/packages/react/src/Tabs/Root/useTabsRoot.ts
@@ -1,10 +1,12 @@
 'use client';
 import * as React from 'react';
 import { mergeReactProps } from '../../utils/mergeReactProps';
+import { GenericHTMLProps } from '../../utils/types';
 import { useControlled } from '../../utils/useControlled';
+import type { CompositeMetadata } from '../../Composite/List/CompositeList';
 import type { TabPanelMetadata } from '../TabPanel/useTabPanel';
 import type { TabMetadata } from '../Tab/useTab';
-import type { TabActivationDirection } from './TabsRoot';
+import type { TabActivationDirection, TabValue } from './TabsRoot';
 
 function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValue {
   const {
@@ -24,21 +26,17 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
   });
 
   const [tabPanelMap, setTabPanelMap] = React.useState(
-    () => new Map<Node, (TabPanelMetadata & { index?: number | null }) | null>(),
+    () => new Map<Node, CompositeMetadata<TabPanelMetadata> | null>(),
   );
   const [tabMap, setTabMap] = React.useState(
-    () => new Map<Node, (TabMetadata & { index?: number | null }) | null>(),
+    () => new Map<Node, CompositeMetadata<TabMetadata> | null>(),
   );
 
   const [tabActivationDirection, setTabActivationDirection] =
     React.useState<TabActivationDirection>('none');
 
   const onValueChange = React.useCallback(
-    (
-      newValue: any | null,
-      activationDirection: TabActivationDirection,
-      event: Event | undefined,
-    ) => {
+    (newValue: TabValue, activationDirection: TabActivationDirection, event: Event | undefined) => {
       setValue(newValue);
       setTabActivationDirection(activationDirection);
       onValueChangeProp?.(newValue, event);
@@ -48,7 +46,7 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
 
   // get the `id` attribute of <Tabs.Panel> to set as the value of `aria-controls` on <Tabs.Tab>
   const getTabPanelIdByTabValueOrIndex = React.useCallback(
-    (tabValue: any | undefined, index: number) => {
+    (tabValue: TabValue | undefined, index: number) => {
       if (tabValue === undefined && index < 0) {
         return undefined;
       }
@@ -76,7 +74,7 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
 
   // get the `id` attribute of <Tabs.Tab> to set as the value of `aria-labelledby` on <Tabs.Panel>
   const getTabIdByPanelValueOrIndex = React.useCallback(
-    (tabPanelValue: any | undefined, index: number) => {
+    (tabPanelValue: TabValue | undefined, index: number) => {
       if (tabPanelValue === undefined && index < 0) {
         return undefined;
       }
@@ -88,7 +86,6 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
           index > -1 &&
           tabPanelValue === (tabMetadata?.value ?? tabMetadata?.index ?? undefined)
         ) {
-          // console.log('found by tabPanelValue', tabMetadata?.id);
           return tabMetadata?.id;
         }
 
@@ -98,7 +95,6 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
           index > -1 &&
           index === (tabMetadata?.value ?? tabMetadata?.index ?? undefined)
         ) {
-          // console.log('found by tabPanel index', tabMetadata?.id);
           return tabMetadata?.id;
         }
       }
@@ -110,7 +106,7 @@ function useTabsRoot(parameters: useTabsRoot.Parameters): useTabsRoot.ReturnValu
 
   // used in `useActivationDirectionDetector` for setting data-activation-direction
   const getTabElementBySelectedValue = React.useCallback(
-    (selectedValue: any | undefined): HTMLElement | null => {
+    (selectedValue: TabValue | undefined): HTMLElement | null => {
       if (selectedValue === undefined) {
         return null;
       }
@@ -156,11 +152,11 @@ namespace useTabsRoot {
      * The value of the currently selected `Tab`.
      * If you don't want any selected `Tab`, you can set this prop to `false`.
      */
-    value?: any | null;
+    value?: TabValue;
     /**
      * The default value. Use when the component is not controlled.
      */
-    defaultValue?: any | null;
+    defaultValue?: TabValue;
     /**
      * The direction of the text.
      * @default 'ltr'
@@ -169,56 +165,62 @@ namespace useTabsRoot {
     /**
      * Callback invoked when new value is being set.
      */
-    onValueChange?: (value: any | null, event?: Event) => void;
+    onValueChange?: (value: TabValue, event?: Event) => void;
   }
 
   export interface ReturnValue {
-    getRootProps: (
-      externalProps?: React.ComponentPropsWithRef<'div'>,
-    ) => React.ComponentPropsWithRef<'div'>;
+    /**
+     * Resolver for the Root component's props.
+     * @param externalProps additional props for Tabs.Root
+     * @returns props that should be spread on Tabs.Root
+     */
+    getRootProps: (externalProps?: GenericHTMLProps) => GenericHTMLProps;
     /**
      * The direction of the text.
      */
     direction: 'ltr' | 'rtl';
     /**
-     * Gets the underlying element of the Tab with the given value.
-     * @param value Value to find the tab for.
+     * Gets the element of the Tab with the given value.
+     * @param {any | undefined} value Value to find the tab for.
      */
-    getTabElementBySelectedValue: (panelValue: any | undefined) => HTMLElement | null;
+    getTabElementBySelectedValue: (panelValue: TabValue | undefined) => HTMLElement | null;
     /**
-     * Gets the `id` attribute of the Tab with the given value.
+     * Gets the `id` attribute of the Tab that corresponds to the given TabPanel value or index.
      * @param (any | undefined) panelValue Value to find the Tab for.
      * @param (number) index The index of the Tab to look for.
      */
-    getTabIdByPanelValueOrIndex: (panelValue: any | undefined, index: number) => string | undefined;
+    getTabIdByPanelValueOrIndex: (
+      panelValue: TabValue | undefined,
+      index: number,
+    ) => string | undefined;
     /**
-     * Gets the id of the tab panel with the given value.
+     * Gets the `id` attribute of the TabPanel that corresponds to the given Tab value or index.
      * @param value Value to find the tab panel for.
      */
     getTabPanelIdByTabValueOrIndex: (
-      tabValue: any | undefined,
+      tabValue: TabValue | undefined,
       index: number,
     ) => string | undefined;
     /**
      * Callback for setting new value.
      */
     onValueChange: (
-      value: any | null,
+      value: TabValue,
       activationDirection: TabActivationDirection,
       event: Event,
     ) => void;
-    setTabMap: (map: Map<Node, (TabMetadata & { index?: number | null }) | null>) => void;
-    setTabPanelMap: (map: Map<Node, (TabPanelMetadata & { index?: number | null }) | null>) => void;
+    setTabMap: (map: Map<Node, CompositeMetadata<TabMetadata> | null>) => void;
+    setTabPanelMap: (map: Map<Node, CompositeMetadata<TabPanelMetadata> | null>) => void;
     /**
      * The position of the active tab relative to the previously active tab.
      */
     tabActivationDirection: TabActivationDirection;
-    tabMap: Map<Node, (TabMetadata & { index?: number | null }) | null>;
+    tabMap: Map<Node, CompositeMetadata<TabMetadata> | null>;
     tabPanelRefs: React.RefObject<(HTMLElement | null)[]>;
     /**
      * The currently selected tab's value.
      */
-    value: any | null;
+    value: TabValue;
   }
 }
 
diff --git a/packages/react/src/Tabs/Tab/Tab.tsx b/packages/react/src/Tabs/Tab/Tab.tsx
index 1a750f54ef..3912465c6b 100644
--- a/packages/react/src/Tabs/Tab/Tab.tsx
+++ b/packages/react/src/Tabs/Tab/Tab.tsx
@@ -1,9 +1,10 @@
 'use client';
 import * as React from 'react';
+import PropTypes from 'prop-types';
 import { useTab } from './useTab';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import type { BaseUIComponentProps } from '../../utils/types';
-import type { TabsOrientation } from '../Root/TabsRoot';
+import type { TabsOrientation, TabValue } from '../Root/TabsRoot';
 import { useTabsRootContext } from '../Root/TabsRootContext';
 import { useTabsListContext } from '../TabsList/TabsListContext';
 
@@ -68,14 +69,47 @@ const Tab = React.forwardRef(function Tab(
   return renderElement();
 });
 
+Tab.propTypes /* remove-proptypes */ = {
+  // ┌────────────────────────────── Warning ──────────────────────────────┐
+  // │ These PropTypes are generated from the TypeScript type definitions. │
+  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
+  // └─────────────────────────────────────────────────────────────────────┘
+  /**
+   * @ignore
+   */
+  children: PropTypes.node,
+  /**
+   * Class names applied to the element or a function that returns them based on the component's state.
+   */
+  className: PropTypes.oneOfType([PropTypes.func, PropTypes.string]),
+  /**
+   * @ignore
+   */
+  disabled: PropTypes.bool,
+  /**
+   * @ignore
+   */
+  id: PropTypes.string,
+  /**
+   * A function to customize rendering of the component.
+   */
+  render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  /**
+   * The value of the Tab.
+   * When not specified, the value is the child position index.
+   */
+  value: PropTypes.any,
+} as any;
+
 export { Tab };
 
 namespace Tab {
   export interface Props extends BaseUIComponentProps<'button', Tab.OwnerState> {
     /**
-     * You can provide your own value. Otherwise, it falls back to the child position index.
+     * The value of the Tab.
+     * When not specified, the value is the child position index.
      */
-    value?: any;
+    value?: TabValue;
   }
 
   export interface OwnerState {
diff --git a/packages/react/src/Tabs/Tab/useTab.ts b/packages/react/src/Tabs/Tab/useTab.ts
index 644d776074..27350e5e99 100644
--- a/packages/react/src/Tabs/Tab/useTab.ts
+++ b/packages/react/src/Tabs/Tab/useTab.ts
@@ -160,9 +160,9 @@ namespace useTab {
 
   export interface ReturnValue {
     /**
-     * Resolver for the root slot's props.
-     * @param externalProps props for the root slot
-     * @returns props that should be spread on the root slot
+     * Resolver for the Tab component's props.
+     * @param externalProps additional props for Tabs.Tab
+     * @returns props that should be spread on Tabs.Tab
      */
     getRootProps: (
       externalProps?: React.ComponentPropsWithRef<'button'>,
diff --git a/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx b/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx
index 85f9a057f5..2492aa08e6 100644
--- a/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx
+++ b/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx
@@ -1,5 +1,6 @@
 'use client';
 import * as React from 'react';
+import PropTypes from 'prop-types';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import { useOnMount } from '../../utils/useOnMount';
 import type { BaseUIComponentProps } from '../../utils/types';
@@ -89,6 +90,32 @@ const TabIndicator = React.forwardRef<HTMLSpanElement, TabIndicator.Props>(
   },
 );
 
+TabIndicator.propTypes /* remove-proptypes */ = {
+  // ┌────────────────────────────── Warning ──────────────────────────────┐
+  // │ These PropTypes are generated from the TypeScript type definitions. │
+  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
+  // └─────────────────────────────────────────────────────────────────────┘
+  /**
+   * @ignore
+   */
+  children: PropTypes.node,
+  /**
+   * Class names applied to the element or a function that returns them based on the component's state.
+   */
+  className: PropTypes.oneOfType([PropTypes.func, PropTypes.string]),
+  /**
+   * A function to customize rendering of the component.
+   */
+  render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  /**
+   * If `true`, the indicator will include code to render itself before React hydrates.
+   * This will minimize the time the indicator is not visible after the SSR-generated content is downloaded.
+   *
+   * @default false
+   */
+  renderBeforeHydration: PropTypes.bool,
+} as any;
+
 export { TabIndicator };
 
 namespace TabIndicator {
diff --git a/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts b/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts
index 8e0b45f981..73d6e1c28d 100644
--- a/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts
+++ b/packages/react/src/Tabs/TabIndicator/useTabIndicator.ts
@@ -3,6 +3,7 @@ import * as React from 'react';
 import type { TabsListContext } from '../TabsList/TabsListContext';
 import type { TabsRootContext } from '../Root/TabsRootContext';
 import { mergeReactProps } from '../../utils/mergeReactProps';
+import { GenericHTMLProps } from '../../utils/types';
 import { useForcedRerendering } from '../../utils/useForcedRerendering';
 
 function round(value: number) {
@@ -125,9 +126,12 @@ export namespace useTabIndicator {
       Pick<TabsListContext, 'tabsListRef'> {}
 
   export interface ReturnValue {
-    getRootProps: (
-      otherProps?: React.ComponentPropsWithRef<'span'>,
-    ) => React.ComponentPropsWithRef<'span'>;
+    /**
+     * Resolver for the TabIndicator component's props.
+     * @param externalProps additional props for Tabs.TabIndicator
+     * @returns props that should be spread on Tabs.TabIndicator
+     */
+    getRootProps: (externalProps?: GenericHTMLProps) => GenericHTMLProps;
     activeTabPosition: ActiveTabPosition | null;
   }
 }
diff --git a/packages/react/src/Tabs/TabPanel/TabPanel.tsx b/packages/react/src/Tabs/TabPanel/TabPanel.tsx
index 61663cdef6..d2e99b3f74 100644
--- a/packages/react/src/Tabs/TabPanel/TabPanel.tsx
+++ b/packages/react/src/Tabs/TabPanel/TabPanel.tsx
@@ -1,10 +1,11 @@
 'use client';
 import * as React from 'react';
+import PropTypes from 'prop-types';
 import { useTabPanel } from './useTabPanel';
 import { tabsStyleHookMapping } from '../Root/styleHooks';
 import { useTabsRootContext } from '../Root/TabsRootContext';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
-import { TabsRoot } from '../Root/TabsRoot';
+import { TabsRoot, type TabValue } from '../Root/TabsRoot';
 import type { BaseUIComponentProps } from '../../utils/types';
 
 /**
@@ -60,6 +61,36 @@ const TabPanel = React.forwardRef(function TabPanel(
   return renderElement();
 });
 
+TabPanel.propTypes /* remove-proptypes */ = {
+  // ┌────────────────────────────── Warning ──────────────────────────────┐
+  // │ These PropTypes are generated from the TypeScript type definitions. │
+  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
+  // └─────────────────────────────────────────────────────────────────────┘
+  /**
+   * @ignore
+   */
+  children: PropTypes.node,
+  /**
+   * Class names applied to the element or a function that returns them based on the component's state.
+   */
+  className: PropTypes.oneOfType([PropTypes.func, PropTypes.string]),
+  /**
+   * If `true`, keeps the contents of the hidden TabPanel in the DOM.
+   * @default false
+   */
+  keepMounted: PropTypes.bool,
+  /**
+   * A function to customize rendering of the component.
+   */
+  render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  /**
+   * The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected.
+   * If not provided, it will fall back to the index of the panel.
+   * It is recommended to explicitly provide it, as it's required for the tab panel to be rendered on the server.
+   */
+  value: PropTypes.any,
+} as any;
+
 export { TabPanel };
 
 namespace TabPanel {
@@ -73,7 +104,7 @@ namespace TabPanel {
      * If not provided, it will fall back to the index of the panel.
      * It is recommended to explicitly provide it, as it's required for the tab panel to be rendered on the server.
      */
-    value?: any;
+    value?: TabValue;
     /**
      * If `true`, keeps the contents of the hidden TabPanel in the DOM.
      * @default false
diff --git a/packages/react/src/Tabs/TabPanel/useTabPanel.ts b/packages/react/src/Tabs/TabPanel/useTabPanel.ts
index f35be421a6..36212ca04e 100644
--- a/packages/react/src/Tabs/TabPanel/useTabPanel.ts
+++ b/packages/react/src/Tabs/TabPanel/useTabPanel.ts
@@ -1,10 +1,12 @@
 'use client';
 import * as React from 'react';
-import type { TabsRootContext } from '../Root/TabsRootContext';
+import { mergeReactProps } from '../../utils/mergeReactProps';
+import { GenericHTMLProps } from '../../utils/types';
 import { useId } from '../../utils/useId';
 import { useForkRef } from '../../utils/useForkRef';
-import { mergeReactProps } from '../../utils/mergeReactProps';
 import { useCompositeListItem } from '../../Composite/List/useCompositeListItem';
+import type { TabsRootContext } from '../Root/TabsRootContext';
+import type { TabValue } from '../Root/TabsRoot';
 
 export interface TabPanelMetadata {
   id?: string;
@@ -81,11 +83,11 @@ namespace useTabPanel {
     /**
      * The (context) value of the currently active/selected Tab.
      */
-    selectedValue: TabsRootContext['value'];
+    selectedValue: TabValue;
     /**
      * The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected.
      */
-    value?: any;
+    value?: TabValue;
   }
 
   export interface ReturnValue {
@@ -94,13 +96,11 @@ namespace useTabPanel {
      */
     hidden: boolean;
     /**
-     * Resolver for the root slot's props.
-     * @param externalProps additional props for the root slot
-     * @returns props that should be spread on the root slot
+     * Resolver for the TabPanel component's props.
+     * @param externalProps additional props for Tabs.TabPanel
+     * @returns props that should be spread on Tabs.TabPanel
      */
-    getRootProps: (
-      externalProps?: React.ComponentPropsWithRef<'div'>,
-    ) => React.ComponentPropsWithRef<'div'>;
+    getRootProps: (externalProps?: GenericHTMLProps) => GenericHTMLProps;
     rootRef: React.RefCallback<HTMLElement> | null;
   }
 }
diff --git a/packages/react/src/Tabs/TabsList/TabsList.tsx b/packages/react/src/Tabs/TabsList/TabsList.tsx
index 7520b0c3ac..fb5c890b94 100644
--- a/packages/react/src/Tabs/TabsList/TabsList.tsx
+++ b/packages/react/src/Tabs/TabsList/TabsList.tsx
@@ -1,5 +1,6 @@
 'use client';
 import * as React from 'react';
+import PropTypes from 'prop-types';
 import { BaseUIComponentProps } from '../../utils/types';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import { CompositeRoot } from '../../Composite/Root/CompositeRoot';
@@ -101,6 +102,38 @@ const TabsList = React.forwardRef(function TabsList(
   );
 });
 
+TabsList.propTypes /* remove-proptypes */ = {
+  // ┌────────────────────────────── Warning ──────────────────────────────┐
+  // │ These PropTypes are generated from the TypeScript type definitions. │
+  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
+  // └─────────────────────────────────────────────────────────────────────┘
+  /**
+   * If `true`, the tab will be activated whenever it is focused.
+   * Otherwise, it has to be activated by clicking or pressing the Enter or Space key.
+   *
+   * @default true
+   */
+  activateOnFocus: PropTypes.bool,
+  /**
+   * @ignore
+   */
+  children: PropTypes.node,
+  /**
+   * Class names applied to the element or a function that returns them based on the component's state.
+   */
+  className: PropTypes.oneOfType([PropTypes.func, PropTypes.string]),
+  /**
+   * If `true`, using keyboard navigation will wrap focus to the other end of the list once the end is reached.
+   *
+   * @default true
+   */
+  loop: PropTypes.bool,
+  /**
+   * A function to customize rendering of the component.
+   */
+  render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+} as any;
+
 export { TabsList };
 
 namespace TabsList {
diff --git a/packages/react/src/Tabs/TabsList/useTabsList.ts b/packages/react/src/Tabs/TabsList/useTabsList.ts
index f574cec7ca..87bd847ffa 100644
--- a/packages/react/src/Tabs/TabsList/useTabsList.ts
+++ b/packages/react/src/Tabs/TabsList/useTabsList.ts
@@ -2,9 +2,10 @@
 import * as React from 'react';
 import type { TabsRootContext } from '../Root/TabsRootContext';
 import { type TabsOrientation, type TabActivationDirection } from '../Root/TabsRoot';
-import { useForkRef } from '../../utils/useForkRef';
 import { mergeReactProps } from '../../utils/mergeReactProps';
+import { GenericHTMLProps } from '../../utils/types';
 import { useEnhancedEffect } from '../../utils/useEnhancedEffect';
+import { useForkRef } from '../../utils/useForkRef';
 import { useEventCallback } from '../../utils/useEventCallback';
 
 function useTabsList(parameters: useTabsList.Parameters): useTabsList.ReturnValue {
@@ -151,13 +152,11 @@ namespace useTabsList {
 
   export interface ReturnValue {
     /**
-     * Resolver for the root slot's props.
-     * @param externalProps props for the root slot
-     * @returns props that should be spread on the root slot
+     * Resolver for the TabsList component's props.
+     * @param externalProps additional props for Tabs.TabsList
+     * @returns props that should be spread on Tabs.TabsList
      */
-    getRootProps: (
-      externalProps?: React.ComponentPropsWithRef<'div'>,
-    ) => React.ComponentPropsWithRef<'div'>;
+    getRootProps: (externalProps?: GenericHTMLProps) => GenericHTMLProps;
     /**
      * Callback when a Tab is activated
      * @param {any | null} newValue The value of the newly activated tab.

From 1ca8ba374bd27de6e3adf16c47824f47cb9f0dfb Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Thu, 21 Nov 2024 21:00:24 +0800
Subject: [PATCH 15/20] Use a custom ref prop

---
 .../src/Composite/Item/CompositeItem.tsx      | 38 ++++++++++++++-----
 .../src/Composite/Root/CompositeRoot.tsx      | 35 ++++++++++-------
 packages/react/src/Tabs/Tab/useTab.ts         |  2 +
 3 files changed, 53 insertions(+), 22 deletions(-)

diff --git a/packages/react/src/Composite/Item/CompositeItem.tsx b/packages/react/src/Composite/Item/CompositeItem.tsx
index 8b87646048..ee4843d696 100644
--- a/packages/react/src/Composite/Item/CompositeItem.tsx
+++ b/packages/react/src/Composite/Item/CompositeItem.tsx
@@ -10,14 +10,11 @@ import type { BaseUIComponentProps } from '../../utils/types';
 /**
  * @ignore - internal component.
  */
-const CompositeItem = React.forwardRef(function CompositeItem(
-  props: CompositeItem.Props,
-  forwardedRef: React.ForwardedRef<HTMLDivElement>,
-) {
-  const { render, className, ...otherProps } = props;
+function CompositeItem<Metadata>(props: CompositeItem.Props<Metadata>) {
+  const { render, className, itemRef, metadata, ...otherProps } = props;
 
   const { activeIndex } = useCompositeRootContext();
-  const { getItemProps, ref, index } = useCompositeItem();
+  const { getItemProps, ref, index } = useCompositeItem({ metadata });
 
   const ownerState: CompositeItem.OwnerState = React.useMemo(
     () => ({
@@ -26,7 +23,7 @@ const CompositeItem = React.forwardRef(function CompositeItem(
     [index, activeIndex],
   );
 
-  const mergedRef = useForkRef(forwardedRef, ref);
+  const mergedRef = useForkRef(itemRef, ref);
 
   const { renderElement } = useComponentRenderer({
     propGetter: getItemProps,
@@ -38,14 +35,19 @@ const CompositeItem = React.forwardRef(function CompositeItem(
   });
 
   return renderElement();
-});
+}
 
 namespace CompositeItem {
   export interface OwnerState {
     active: boolean;
   }
 
-  export interface Props extends BaseUIComponentProps<'div', OwnerState> {}
+  export interface Props<Metadata>
+    extends Omit<BaseUIComponentProps<'div', OwnerState>, 'itemRef'> {
+    // the itemRef name collides with https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemref
+    itemRef?: React.RefObject<HTMLElement | null>;
+    metadata?: Metadata;
+  }
 }
 
 CompositeItem.propTypes /* remove-proptypes */ = {
@@ -61,6 +63,24 @@ CompositeItem.propTypes /* remove-proptypes */ = {
    * Class names applied to the element or a function that returns them based on the component's state.
    */
   className: PropTypes.oneOfType([PropTypes.func, PropTypes.string]),
+  /**
+   * @ignore
+   */
+  itemRef: PropTypes.shape({
+    current: (props, propName) => {
+      if (props[propName] == null) {
+        return null;
+      }
+      if (typeof props[propName] !== 'object' || props[propName].nodeType !== 1) {
+        return new Error(`Expected prop '${propName}' to be of type Element`);
+      }
+      return null;
+    },
+  }),
+  /**
+   * @ignore
+   */
+  metadata: PropTypes.any,
   /**
    * A function to customize rendering of the component.
    */
diff --git a/packages/react/src/Composite/Root/CompositeRoot.tsx b/packages/react/src/Composite/Root/CompositeRoot.tsx
index c8d3f4ae8e..f539d4ddb9 100644
--- a/packages/react/src/Composite/Root/CompositeRoot.tsx
+++ b/packages/react/src/Composite/Root/CompositeRoot.tsx
@@ -11,10 +11,7 @@ import type { Dimensions } from '../composite';
 /**
  * @ignore - internal component.
  */
-const CompositeRoot = React.forwardRef(function CompositeRoot<CustomMetadata extends {}>(
-  props: CompositeRoot.Props<CustomMetadata>,
-  forwardedRef: React.ForwardedRef<HTMLDivElement>,
-) {
+function CompositeRoot<Metadata extends {}>(props: CompositeRoot.Props<Metadata>) {
   const {
     render,
     className,
@@ -28,6 +25,7 @@ const CompositeRoot = React.forwardRef(function CompositeRoot<CustomMetadata ext
     enableHomeAndEndKeys,
     onMapChange,
     stopEventPropagation,
+    rootRef,
     ...otherProps
   } = props;
 
@@ -39,14 +37,13 @@ const CompositeRoot = React.forwardRef(function CompositeRoot<CustomMetadata ext
     orientation,
     activeIndex: activeIndexProp,
     onActiveIndexChange: onActiveIndexChangeProp,
-    rootRef: forwardedRef,
+    rootRef,
     stopEventPropagation,
     enableHomeAndEndKeys,
   });
 
   const { renderElement } = useComponentRenderer({
     propGetter: getRootProps,
-    ref: forwardedRef,
     render: render ?? 'div',
     ownerState: {},
     className,
@@ -60,20 +57,17 @@ const CompositeRoot = React.forwardRef(function CompositeRoot<CustomMetadata ext
 
   return (
     <CompositeRootContext.Provider value={contextValue}>
-      <CompositeList<CustomMetadata> elementsRef={elementsRef} onMapChange={onMapChange}>
+      <CompositeList<Metadata> elementsRef={elementsRef} onMapChange={onMapChange}>
         {renderElement()}
       </CompositeList>
     </CompositeRootContext.Provider>
   );
-}) as {
-  <CustomMetadata extends {}>(props: CompositeRoot.Props<CustomMetadata>): React.JSX.Element | null;
-  propTypes?: any;
-};
+}
 
 namespace CompositeRoot {
   export interface OwnerState {}
 
-  export interface Props<CustomMetadata> extends BaseUIComponentProps<'div', OwnerState> {
+  export interface Props<Metadata> extends BaseUIComponentProps<'div', OwnerState> {
     orientation?: 'horizontal' | 'vertical' | 'both';
     cols?: number;
     loop?: boolean;
@@ -82,8 +76,9 @@ namespace CompositeRoot {
     itemSizes?: Dimensions[];
     dense?: boolean;
     enableHomeAndEndKeys?: boolean;
-    onMapChange?: (newMap: Map<Node, CompositeMetadata<CustomMetadata> | null>) => void;
+    onMapChange?: (newMap: Map<Node, CompositeMetadata<Metadata> | null>) => void;
     stopEventPropagation?: boolean;
+    rootRef?: React.RefObject<HTMLElement | null>;
   }
 }
 
@@ -145,6 +140,20 @@ CompositeRoot.propTypes /* remove-proptypes */ = {
    * A function to customize rendering of the component.
    */
   render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  /**
+   * @ignore
+   */
+  rootRef: PropTypes.shape({
+    current: (props, propName) => {
+      if (props[propName] == null) {
+        return null;
+      }
+      if (typeof props[propName] !== 'object' || props[propName].nodeType !== 1) {
+        return new Error(`Expected prop '${propName}' to be of type Element`);
+      }
+      return null;
+    },
+  }),
   /**
    * @ignore
    */
diff --git a/packages/react/src/Tabs/Tab/useTab.ts b/packages/react/src/Tabs/Tab/useTab.ts
index 27350e5e99..fc7c9789d9 100644
--- a/packages/react/src/Tabs/Tab/useTab.ts
+++ b/packages/react/src/Tabs/Tab/useTab.ts
@@ -41,6 +41,8 @@ function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
     getItemProps,
     ref: compositeItemRef,
     index,
+    // hook is used instead of the CompositeItem component
+    // because the index is needed for Tab internals
   } = useCompositeItem<TabMetadata>({ metadata: tabMetadata });
 
   const tabValue = valueParam ?? index;

From 518925a61719cf1549654b4c3a5149dc12455606 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Fri, 22 Nov 2024 12:43:41 +0800
Subject: [PATCH 16/20] data-highlighted

---
 .../src/Composite/Item/CompositeItem.tsx      |   4 +-
 .../src/Composite/Root/CompositeRoot.test.tsx | 104 +++++++++---------
 2 files changed, 54 insertions(+), 54 deletions(-)

diff --git a/packages/react/src/Composite/Item/CompositeItem.tsx b/packages/react/src/Composite/Item/CompositeItem.tsx
index ee4843d696..3491b2dffa 100644
--- a/packages/react/src/Composite/Item/CompositeItem.tsx
+++ b/packages/react/src/Composite/Item/CompositeItem.tsx
@@ -18,7 +18,7 @@ function CompositeItem<Metadata>(props: CompositeItem.Props<Metadata>) {
 
   const ownerState: CompositeItem.OwnerState = React.useMemo(
     () => ({
-      active: index === activeIndex,
+      highlighted: index === activeIndex,
     }),
     [index, activeIndex],
   );
@@ -39,7 +39,7 @@ function CompositeItem<Metadata>(props: CompositeItem.Props<Metadata>) {
 
 namespace CompositeItem {
   export interface OwnerState {
-    active: boolean;
+    highlighted: boolean;
   }
 
   export interface Props<Metadata>
diff --git a/packages/react/src/Composite/Root/CompositeRoot.test.tsx b/packages/react/src/Composite/Root/CompositeRoot.test.tsx
index 401729c9ca..85a4da1ae9 100644
--- a/packages/react/src/Composite/Root/CompositeRoot.test.tsx
+++ b/packages/react/src/Composite/Root/CompositeRoot.test.tsx
@@ -36,29 +36,29 @@ describe('Composite', () => {
 
       act(() => item1.focus());
 
-      expect(item1).to.have.attribute('data-active');
+      expect(item1).to.have.attribute('data-highlighted');
 
       fireEvent.keyDown(item1, { key: 'ArrowDown' });
       await flushMicrotasks();
-      expect(item2).to.have.attribute('data-active');
+      expect(item2).to.have.attribute('data-highlighted');
       expect(item2).to.have.attribute('tabindex', '0');
       expect(item2).toHaveFocus();
 
       fireEvent.keyDown(item2, { key: 'ArrowDown' });
       await flushMicrotasks();
-      expect(item3).to.have.attribute('data-active');
+      expect(item3).to.have.attribute('data-highlighted');
       expect(item3).to.have.attribute('tabindex', '0');
       expect(item3).toHaveFocus();
 
       fireEvent.keyDown(item3, { key: 'ArrowUp' });
       await flushMicrotasks();
-      expect(item2).to.have.attribute('data-active');
+      expect(item2).to.have.attribute('data-highlighted');
       expect(item2).to.have.attribute('tabindex', '0');
       expect(item2).toHaveFocus();
 
       fireEvent.keyDown(item2, { key: 'ArrowUp' });
       await flushMicrotasks();
-      expect(item1).to.have.attribute('data-active');
+      expect(item1).to.have.attribute('data-highlighted');
       expect(item1).to.have.attribute('tabindex', '0');
       expect(item1).toHaveFocus();
     });
@@ -78,29 +78,29 @@ describe('Composite', () => {
 
       act(() => item1.focus());
 
-      expect(item1).to.have.attribute('data-active');
+      expect(item1).to.have.attribute('data-highlighted');
 
       fireEvent.keyDown(item1, { key: 'ArrowDown' });
       await flushMicrotasks();
-      expect(item2).to.have.attribute('data-active');
+      expect(item2).to.have.attribute('data-highlighted');
       expect(item2).to.have.attribute('tabindex', '0');
       expect(item2).toHaveFocus();
 
       fireEvent.keyDown(item2, { key: 'ArrowDown' });
       await flushMicrotasks();
-      expect(item3).to.have.attribute('data-active');
+      expect(item3).to.have.attribute('data-highlighted');
       expect(item3).to.have.attribute('tabindex', '0');
       expect(item3).toHaveFocus();
 
       fireEvent.keyDown(item3, { key: 'ArrowUp' });
       await flushMicrotasks();
-      expect(item2).to.have.attribute('data-active');
+      expect(item2).to.have.attribute('data-highlighted');
       expect(item2).to.have.attribute('tabindex', '0');
       expect(item2).toHaveFocus();
 
       fireEvent.keyDown(item2, { key: 'ArrowUp' });
       await flushMicrotasks();
-      expect(item1).to.have.attribute('data-active');
+      expect(item1).to.have.attribute('data-highlighted');
       expect(item1).to.have.attribute('tabindex', '0');
       expect(item1).toHaveFocus();
     });
@@ -119,11 +119,11 @@ describe('Composite', () => {
         const item3 = getByTestId('3');
 
         act(() => item3.focus());
-        expect(item3).to.have.attribute('data-active');
+        expect(item3).to.have.attribute('data-highlighted');
 
         fireEvent.keyDown(item3, { key: 'Home' });
         await flushMicrotasks();
-        expect(item1).to.have.attribute('data-active');
+        expect(item1).to.have.attribute('data-highlighted');
         expect(item1).to.have.attribute('tabindex', '0');
         expect(item1).toHaveFocus();
       });
@@ -141,11 +141,11 @@ describe('Composite', () => {
         const item3 = getByTestId('3');
 
         act(() => item1.focus());
-        expect(item1).to.have.attribute('data-active');
+        expect(item1).to.have.attribute('data-highlighted');
 
         fireEvent.keyDown(item1, { key: 'End' });
         await flushMicrotasks();
-        expect(item3).to.have.attribute('data-active');
+        expect(item3).to.have.attribute('data-highlighted');
         expect(item3).to.have.attribute('tabindex', '0');
         expect(item3).toHaveFocus();
       });
@@ -169,40 +169,40 @@ describe('Composite', () => {
 
         act(() => item1.focus());
 
-        expect(item1).to.have.attribute('data-active');
+        expect(item1).to.have.attribute('data-highlighted');
 
         fireEvent.keyDown(item1, { key: 'ArrowDown' });
         await flushMicrotasks();
-        expect(item1).to.have.attribute('data-active');
+        expect(item1).to.have.attribute('data-highlighted');
 
         fireEvent.keyDown(item1, { key: 'ArrowLeft' });
         await flushMicrotasks();
-        expect(item2).to.have.attribute('data-active');
+        expect(item2).to.have.attribute('data-highlighted');
         expect(item2).to.have.attribute('tabindex', '0');
         expect(item2).toHaveFocus();
 
         fireEvent.keyDown(item2, { key: 'ArrowLeft' });
         await flushMicrotasks();
-        expect(item3).to.have.attribute('data-active');
+        expect(item3).to.have.attribute('data-highlighted');
         expect(item3).to.have.attribute('tabindex', '0');
         expect(item3).toHaveFocus();
 
         fireEvent.keyDown(item3, { key: 'ArrowRight' });
         await flushMicrotasks();
-        expect(item2).to.have.attribute('data-active');
+        expect(item2).to.have.attribute('data-highlighted');
         expect(item2).to.have.attribute('tabindex', '0');
         expect(item2).toHaveFocus();
 
         fireEvent.keyDown(item2, { key: 'ArrowRight' });
         await flushMicrotasks();
-        expect(item1).to.have.attribute('data-active');
+        expect(item1).to.have.attribute('data-highlighted');
         expect(item1).to.have.attribute('tabindex', '0');
         expect(item1).toHaveFocus();
 
         // loop backward
         fireEvent.keyDown(item1, { key: 'ArrowRight' });
         await flushMicrotasks();
-        expect(item3).to.have.attribute('data-active');
+        expect(item3).to.have.attribute('data-highlighted');
         expect(item3).to.have.attribute('tabindex', '0');
         expect(item3).toHaveFocus();
       });
@@ -224,41 +224,41 @@ describe('Composite', () => {
 
         act(() => item1.focus());
 
-        expect(item1).to.have.attribute('data-active');
+        expect(item1).to.have.attribute('data-highlighted');
 
         fireEvent.keyDown(item1, { key: 'ArrowLeft' });
         await flushMicrotasks();
-        expect(item2).to.have.attribute('data-active');
+        expect(item2).to.have.attribute('data-highlighted');
         expect(item2).to.have.attribute('tabindex', '0');
         expect(item2).toHaveFocus();
 
         fireEvent.keyDown(item2, { key: 'ArrowLeft' });
         await flushMicrotasks();
-        expect(item3).to.have.attribute('data-active');
+        expect(item3).to.have.attribute('data-highlighted');
         expect(item3).to.have.attribute('tabindex', '0');
         expect(item3).toHaveFocus();
 
         fireEvent.keyDown(item3, { key: 'ArrowRight' });
         await flushMicrotasks();
-        expect(item2).to.have.attribute('data-active');
+        expect(item2).to.have.attribute('data-highlighted');
         expect(item2).to.have.attribute('tabindex', '0');
         expect(item2).toHaveFocus();
 
         fireEvent.keyDown(item2, { key: 'ArrowRight' });
         await flushMicrotasks();
-        expect(item1).to.have.attribute('data-active');
+        expect(item1).to.have.attribute('data-highlighted');
         expect(item1).to.have.attribute('tabindex', '0');
         expect(item1).toHaveFocus();
 
         fireEvent.keyDown(item1, { key: 'ArrowDown' });
         await flushMicrotasks();
-        expect(item2).to.have.attribute('data-active');
+        expect(item2).to.have.attribute('data-highlighted');
         expect(item2).to.have.attribute('tabindex', '0');
         expect(item2).toHaveFocus();
 
         fireEvent.keyDown(item2, { key: 'ArrowDown' });
         await flushMicrotasks();
-        expect(item3).to.have.attribute('data-active');
+        expect(item3).to.have.attribute('data-highlighted');
         expect(item3).to.have.attribute('tabindex', '0');
         expect(item3).toHaveFocus();
       });
@@ -283,51 +283,51 @@ describe('Composite', () => {
       const { getByTestId } = await render(<App />);
 
       act(() => getByTestId('1').focus());
-      expect(getByTestId('1')).to.have.attribute('data-active');
+      expect(getByTestId('1')).to.have.attribute('data-highlighted');
 
       fireEvent.keyDown(getByTestId('1'), { key: 'ArrowDown' });
       await flushMicrotasks();
-      expect(getByTestId('4')).to.have.attribute('data-active');
+      expect(getByTestId('4')).to.have.attribute('data-highlighted');
       expect(getByTestId('4')).to.have.attribute('tabindex', '0');
       expect(getByTestId('4')).toHaveFocus();
 
       fireEvent.keyDown(getByTestId('4'), { key: 'ArrowRight' });
       await flushMicrotasks();
-      expect(getByTestId('5')).to.have.attribute('data-active');
+      expect(getByTestId('5')).to.have.attribute('data-highlighted');
       expect(getByTestId('5')).to.have.attribute('tabindex', '0');
       expect(getByTestId('5')).toHaveFocus();
 
       fireEvent.keyDown(getByTestId('5'), { key: 'ArrowDown' });
       await flushMicrotasks();
-      expect(getByTestId('8')).to.have.attribute('data-active');
+      expect(getByTestId('8')).to.have.attribute('data-highlighted');
       expect(getByTestId('8')).to.have.attribute('tabindex', '0');
       expect(getByTestId('8')).toHaveFocus();
 
       fireEvent.keyDown(getByTestId('8'), { key: 'ArrowLeft' });
       await flushMicrotasks();
-      expect(getByTestId('7')).to.have.attribute('data-active');
+      expect(getByTestId('7')).to.have.attribute('data-highlighted');
       expect(getByTestId('7')).to.have.attribute('tabindex', '0');
       expect(getByTestId('7')).toHaveFocus();
 
       fireEvent.keyDown(getByTestId('7'), { key: 'ArrowUp' });
       await flushMicrotasks();
-      expect(getByTestId('4')).to.have.attribute('data-active');
+      expect(getByTestId('4')).to.have.attribute('data-highlighted');
       expect(getByTestId('4')).to.have.attribute('tabindex', '0');
       expect(getByTestId('4')).toHaveFocus();
 
       act(() => getByTestId('9').focus());
       await flushMicrotasks();
-      expect(getByTestId('9')).to.have.attribute('data-active');
+      expect(getByTestId('9')).to.have.attribute('data-highlighted');
       expect(getByTestId('9')).to.have.attribute('tabindex', '0');
 
       fireEvent.keyDown(getByTestId('9'), { key: 'Home' });
       await flushMicrotasks();
-      expect(getByTestId('1')).to.have.attribute('data-active');
+      expect(getByTestId('1')).to.have.attribute('data-highlighted');
       expect(getByTestId('1')).to.have.attribute('tabindex', '0');
 
       fireEvent.keyDown(getByTestId('1'), { key: 'End' });
       await flushMicrotasks();
-      expect(getByTestId('9')).to.have.attribute('data-active');
+      expect(getByTestId('9')).to.have.attribute('data-highlighted');
       expect(getByTestId('9')).to.have.attribute('tabindex', '0');
     });
 
@@ -346,40 +346,40 @@ describe('Composite', () => {
         );
 
         act(() => getByTestId('1').focus());
-        expect(getByTestId('1')).to.have.attribute('data-active');
+        expect(getByTestId('1')).to.have.attribute('data-highlighted');
 
         fireEvent.keyDown(getByTestId('1'), { key: 'ArrowLeft' });
         await flushMicrotasks();
-        expect(getByTestId('2')).to.have.attribute('data-active');
+        expect(getByTestId('2')).to.have.attribute('data-highlighted');
         expect(getByTestId('2')).to.have.attribute('tabindex', '0');
         expect(getByTestId('2')).toHaveFocus();
 
         fireEvent.keyDown(getByTestId('2'), { key: 'ArrowLeft' });
         await flushMicrotasks();
-        expect(getByTestId('3')).to.have.attribute('data-active');
+        expect(getByTestId('3')).to.have.attribute('data-highlighted');
         expect(getByTestId('3')).to.have.attribute('tabindex', '0');
         expect(getByTestId('3')).toHaveFocus();
 
         fireEvent.keyDown(getByTestId('3'), { key: 'ArrowLeft' });
         await flushMicrotasks();
-        expect(getByTestId('4')).to.have.attribute('data-active');
+        expect(getByTestId('4')).to.have.attribute('data-highlighted');
         expect(getByTestId('4')).to.have.attribute('tabindex', '0');
         expect(getByTestId('4')).toHaveFocus();
 
         fireEvent.keyDown(getByTestId('4'), { key: 'ArrowLeft' });
         await flushMicrotasks();
-        expect(getByTestId('5')).to.have.attribute('data-active');
+        expect(getByTestId('5')).to.have.attribute('data-highlighted');
         expect(getByTestId('5')).to.have.attribute('tabindex', '0');
         expect(getByTestId('5')).toHaveFocus();
 
         fireEvent.keyDown(getByTestId('5'), { key: 'Home' });
         await flushMicrotasks();
-        expect(getByTestId('1')).to.have.attribute('data-active');
+        expect(getByTestId('1')).to.have.attribute('data-highlighted');
         expect(getByTestId('1')).to.have.attribute('tabindex', '0');
 
         fireEvent.keyDown(getByTestId('1'), { key: 'End' });
         await flushMicrotasks();
-        expect(getByTestId('9')).to.have.attribute('data-active');
+        expect(getByTestId('9')).to.have.attribute('data-highlighted');
         expect(getByTestId('9')).to.have.attribute('tabindex', '0');
       });
 
@@ -397,46 +397,46 @@ describe('Composite', () => {
         );
 
         act(() => getByTestId('1').focus());
-        expect(getByTestId('1')).to.have.attribute('data-active');
+        expect(getByTestId('1')).to.have.attribute('data-highlighted');
 
         fireEvent.keyDown(getByTestId('1'), { key: 'ArrowDown' });
         await flushMicrotasks();
-        expect(getByTestId('4')).to.have.attribute('data-active');
+        expect(getByTestId('4')).to.have.attribute('data-highlighted');
         expect(getByTestId('4')).to.have.attribute('tabindex', '0');
         expect(getByTestId('4')).toHaveFocus();
 
         fireEvent.keyDown(getByTestId('4'), { key: 'ArrowLeft' });
         await flushMicrotasks();
-        expect(getByTestId('5')).to.have.attribute('data-active');
+        expect(getByTestId('5')).to.have.attribute('data-highlighted');
         expect(getByTestId('5')).to.have.attribute('tabindex', '0');
         expect(getByTestId('5')).toHaveFocus();
 
         fireEvent.keyDown(getByTestId('5'), { key: 'ArrowDown' });
         await flushMicrotasks();
-        expect(getByTestId('8')).to.have.attribute('data-active');
+        expect(getByTestId('8')).to.have.attribute('data-highlighted');
         expect(getByTestId('8')).to.have.attribute('tabindex', '0');
         expect(getByTestId('8')).toHaveFocus();
 
         fireEvent.keyDown(getByTestId('8'), { key: 'ArrowRight' });
         await flushMicrotasks();
-        expect(getByTestId('7')).to.have.attribute('data-active');
+        expect(getByTestId('7')).to.have.attribute('data-highlighted');
         expect(getByTestId('7')).to.have.attribute('tabindex', '0');
         expect(getByTestId('7')).toHaveFocus();
 
         fireEvent.keyDown(getByTestId('7'), { key: 'ArrowUp' });
         await flushMicrotasks();
-        expect(getByTestId('4')).to.have.attribute('data-active');
+        expect(getByTestId('4')).to.have.attribute('data-highlighted');
         expect(getByTestId('4')).to.have.attribute('tabindex', '0');
         expect(getByTestId('4')).toHaveFocus();
 
         fireEvent.keyDown(getByTestId('4'), { key: 'End' });
         await flushMicrotasks();
-        expect(getByTestId('9')).to.have.attribute('data-active');
+        expect(getByTestId('9')).to.have.attribute('data-highlighted');
         expect(getByTestId('9')).to.have.attribute('tabindex', '0');
 
         fireEvent.keyDown(getByTestId('9'), { key: 'Home' });
         await flushMicrotasks();
-        expect(getByTestId('1')).to.have.attribute('data-active');
+        expect(getByTestId('1')).to.have.attribute('data-highlighted');
         expect(getByTestId('1')).to.have.attribute('tabindex', '0');
       });
     });

From 630d26330bb19bfd3e1c926b164949e2e4f79a54 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Fri, 22 Nov 2024 13:06:41 +0800
Subject: [PATCH 17/20] Clean up

---
 .../src/Composite/Item/CompositeItem.tsx      |  4 +-
 .../src/Composite/List/CompositeList.tsx      | 24 +++---
 .../src/Composite/Root/CompositeRoot.tsx      |  4 +-
 packages/react/src/Tabs/Root/TabsRoot.tsx     | 86 +++++++++----------
 packages/react/src/Tabs/Tab/Tab.tsx           | 36 ++++----
 .../src/Tabs/TabIndicator/TabIndicator.tsx    | 40 ++++-----
 packages/react/src/Tabs/TabPanel/TabPanel.tsx | 44 +++++-----
 packages/react/src/Tabs/TabsList/TabsList.tsx | 44 +++++-----
 8 files changed, 140 insertions(+), 142 deletions(-)

diff --git a/packages/react/src/Composite/Item/CompositeItem.tsx b/packages/react/src/Composite/Item/CompositeItem.tsx
index 3491b2dffa..d050ae03ce 100644
--- a/packages/react/src/Composite/Item/CompositeItem.tsx
+++ b/packages/react/src/Composite/Item/CompositeItem.tsx
@@ -50,6 +50,8 @@ namespace CompositeItem {
   }
 }
 
+export { CompositeItem };
+
 CompositeItem.propTypes /* remove-proptypes */ = {
   // ┌────────────────────────────── Warning ──────────────────────────────┐
   // │ These PropTypes are generated from the TypeScript type definitions. │
@@ -86,5 +88,3 @@ CompositeItem.propTypes /* remove-proptypes */ = {
    */
   render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
 } as any;
-
-export { CompositeItem };
diff --git a/packages/react/src/Composite/List/CompositeList.tsx b/packages/react/src/Composite/List/CompositeList.tsx
index f3eca29708..be2ed3827c 100644
--- a/packages/react/src/Composite/List/CompositeList.tsx
+++ b/packages/react/src/Composite/List/CompositeList.tsx
@@ -25,9 +25,9 @@ function sortByDocumentPosition(a: Node, b: Node) {
 
 export type CompositeMetadata<CustomMetadata> = { index?: number | null } & CustomMetadata;
 
-function areMapsEqual<CustomMetadata>(
-  map1: Map<Node, CompositeMetadata<CustomMetadata> | null>,
-  map2: Map<Node, CompositeMetadata<CustomMetadata> | null>,
+function areMapsEqual<Metadata>(
+  map1: Map<Node, CompositeMetadata<Metadata> | null>,
+  map2: Map<Node, CompositeMetadata<Metadata> | null>,
 ) {
   if (map1.size !== map2.size) {
     return false;
@@ -49,14 +49,12 @@ function areMapsEqual<CustomMetadata>(
  * Provides context for a list of items in a composite component.
  * @ignore - internal component.
  */
-function CompositeList<CustomMetadata>(props: CompositeList.Props<CustomMetadata>) {
+function CompositeList<Metadata>(props: CompositeList.Props<Metadata>) {
   const { children, elementsRef, labelsRef, onMapChange } = props;
 
-  const [map, setMap] = React.useState(
-    () => new Map<Node, CompositeMetadata<CustomMetadata> | null>(),
-  );
+  const [map, setMap] = React.useState(() => new Map<Node, CompositeMetadata<Metadata> | null>());
 
-  const register = React.useCallback((node: Node, metadata: CustomMetadata) => {
+  const register = React.useCallback((node: Node, metadata: Metadata) => {
     setMap((prevMap) => new Map(prevMap).set(node, metadata ?? null));
   }, []);
 
@@ -74,7 +72,7 @@ function CompositeList<CustomMetadata>(props: CompositeList.Props<CustomMetadata
     const nodes = Array.from(newMap.keys()).sort(sortByDocumentPosition);
 
     nodes.forEach((node, index) => {
-      const metadata = map.get(node) ?? ({} as CompositeMetadata<CustomMetadata>);
+      const metadata = map.get(node) ?? ({} as CompositeMetadata<Metadata>);
 
       newMap.set(node, { ...metadata, index });
     });
@@ -96,7 +94,7 @@ function CompositeList<CustomMetadata>(props: CompositeList.Props<CustomMetadata
 }
 
 namespace CompositeList {
-  export interface Props<CustomMetadata> {
+  export interface Props<Metadata> {
     children: React.ReactNode;
     /**
      * A ref to the list of HTML elements, ordered by their index.
@@ -108,10 +106,12 @@ namespace CompositeList {
      * `useTypeahead`'s `listRef` prop.
      */
     labelsRef?: React.RefObject<Array<string | null>>;
-    onMapChange?: (newMap: Map<Node, CompositeMetadata<CustomMetadata> | null>) => void;
+    onMapChange?: (newMap: Map<Node, CompositeMetadata<Metadata> | null>) => void;
   }
 }
 
+export { CompositeList };
+
 CompositeList.propTypes /* remove-proptypes */ = {
   // ┌────────────────────────────── Warning ──────────────────────────────┐
   // │ These PropTypes are generated from the TypeScript type definitions. │
@@ -138,5 +138,3 @@ CompositeList.propTypes /* remove-proptypes */ = {
    */
   onMapChange: PropTypes.func,
 } as any;
-
-export { CompositeList };
diff --git a/packages/react/src/Composite/Root/CompositeRoot.tsx b/packages/react/src/Composite/Root/CompositeRoot.tsx
index f539d4ddb9..22e06ae7c2 100644
--- a/packages/react/src/Composite/Root/CompositeRoot.tsx
+++ b/packages/react/src/Composite/Root/CompositeRoot.tsx
@@ -82,6 +82,8 @@ namespace CompositeRoot {
   }
 }
 
+export { CompositeRoot };
+
 CompositeRoot.propTypes /* remove-proptypes */ = {
   // ┌────────────────────────────── Warning ──────────────────────────────┐
   // │ These PropTypes are generated from the TypeScript type definitions. │
@@ -159,5 +161,3 @@ CompositeRoot.propTypes /* remove-proptypes */ = {
    */
   stopEventPropagation: PropTypes.bool,
 } as any;
-
-export { CompositeRoot };
diff --git a/packages/react/src/Tabs/Root/TabsRoot.tsx b/packages/react/src/Tabs/Root/TabsRoot.tsx
index d116918f1a..9c0d233feb 100644
--- a/packages/react/src/Tabs/Root/TabsRoot.tsx
+++ b/packages/react/src/Tabs/Root/TabsRoot.tsx
@@ -103,6 +103,49 @@ const TabsRoot = React.forwardRef(function TabsRoot(
   );
 });
 
+export type TabsOrientation = 'horizontal' | 'vertical';
+export type TabsDirection = 'ltr' | 'rtl';
+export type TabActivationDirection = 'left' | 'right' | 'up' | 'down' | 'none';
+export type TabValue = any | null;
+
+namespace TabsRoot {
+  export type OwnerState = {
+    orientation: TabsOrientation;
+    direction: TabsDirection;
+    tabActivationDirection: TabActivationDirection;
+  };
+
+  export interface Props extends Omit<BaseUIComponentProps<'div', OwnerState>, 'defaultValue'> {
+    /**
+     * The value of the currently selected `Tab`. Use when the component is controlled.
+     * When the value is `null`, no Tab will be selected.
+     */
+    value?: TabValue;
+    /**
+     * The default value. Use when the component is not controlled.
+     * When the value is `null`, no Tab will be selected.
+     * @default 0
+     */
+    defaultValue?: TabValue;
+    /**
+     * The component orientation (layout flow direction).
+     * @default 'horizontal'
+     */
+    orientation?: TabsOrientation;
+    /**
+     * The direction of the text.
+     * @default 'ltr'
+     */
+    direction?: TabsDirection;
+    /**
+     * Callback invoked when new value is being set.
+     */
+    onValueChange?: (value: TabValue, event?: Event) => void;
+  }
+}
+
+export { TabsRoot };
+
 TabsRoot.propTypes /* remove-proptypes */ = {
   // ┌────────────────────────────── Warning ──────────────────────────────┐
   // │ These PropTypes are generated from the TypeScript type definitions. │
@@ -146,46 +189,3 @@ TabsRoot.propTypes /* remove-proptypes */ = {
    */
   value: PropTypes.any,
 } as any;
-
-export { TabsRoot };
-
-export type TabsOrientation = 'horizontal' | 'vertical';
-export type TabsDirection = 'ltr' | 'rtl';
-export type TabActivationDirection = 'left' | 'right' | 'up' | 'down' | 'none';
-export type TabValue = any | null;
-
-namespace TabsRoot {
-  export type OwnerState = {
-    orientation: TabsOrientation;
-    direction: TabsDirection;
-    tabActivationDirection: TabActivationDirection;
-  };
-
-  export interface Props extends Omit<BaseUIComponentProps<'div', OwnerState>, 'defaultValue'> {
-    /**
-     * The value of the currently selected `Tab`. Use when the component is controlled.
-     * When the value is `null`, no Tab will be selected.
-     */
-    value?: TabValue;
-    /**
-     * The default value. Use when the component is not controlled.
-     * When the value is `null`, no Tab will be selected.
-     * @default 0
-     */
-    defaultValue?: TabValue;
-    /**
-     * The component orientation (layout flow direction).
-     * @default 'horizontal'
-     */
-    orientation?: TabsOrientation;
-    /**
-     * The direction of the text.
-     * @default 'ltr'
-     */
-    direction?: TabsDirection;
-    /**
-     * Callback invoked when new value is being set.
-     */
-    onValueChange?: (value: TabValue, event?: Event) => void;
-  }
-}
diff --git a/packages/react/src/Tabs/Tab/Tab.tsx b/packages/react/src/Tabs/Tab/Tab.tsx
index 3912465c6b..3ea7a9d96c 100644
--- a/packages/react/src/Tabs/Tab/Tab.tsx
+++ b/packages/react/src/Tabs/Tab/Tab.tsx
@@ -69,6 +69,24 @@ const Tab = React.forwardRef(function Tab(
   return renderElement();
 });
 
+namespace Tab {
+  export interface Props extends BaseUIComponentProps<'button', Tab.OwnerState> {
+    /**
+     * The value of the Tab.
+     * When not specified, the value is the child position index.
+     */
+    value?: TabValue;
+  }
+
+  export interface OwnerState {
+    disabled: boolean;
+    selected: boolean;
+    orientation: TabsOrientation;
+  }
+}
+
+export { Tab };
+
 Tab.propTypes /* remove-proptypes */ = {
   // ┌────────────────────────────── Warning ──────────────────────────────┐
   // │ These PropTypes are generated from the TypeScript type definitions. │
@@ -100,21 +118,3 @@ Tab.propTypes /* remove-proptypes */ = {
    */
   value: PropTypes.any,
 } as any;
-
-export { Tab };
-
-namespace Tab {
-  export interface Props extends BaseUIComponentProps<'button', Tab.OwnerState> {
-    /**
-     * The value of the Tab.
-     * When not specified, the value is the child position index.
-     */
-    value?: TabValue;
-  }
-
-  export interface OwnerState {
-    disabled: boolean;
-    selected: boolean;
-    orientation: TabsOrientation;
-  }
-}
diff --git a/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx b/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx
index 2492aa08e6..80879bbaf0 100644
--- a/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx
+++ b/packages/react/src/Tabs/TabIndicator/TabIndicator.tsx
@@ -90,6 +90,26 @@ const TabIndicator = React.forwardRef<HTMLSpanElement, TabIndicator.Props>(
   },
 );
 
+namespace TabIndicator {
+  export interface OwnerState extends TabsRoot.OwnerState {
+    selectedTabPosition: ActiveTabPosition | null;
+    orientation: TabsOrientation;
+    direction: TabsDirection;
+  }
+
+  export interface Props extends BaseUIComponentProps<'span', TabIndicator.OwnerState> {
+    /**
+     * If `true`, the indicator will include code to render itself before React hydrates.
+     * This will minimize the time the indicator is not visible after the SSR-generated content is downloaded.
+     *
+     * @default false
+     */
+    renderBeforeHydration?: boolean;
+  }
+}
+
+export { TabIndicator };
+
 TabIndicator.propTypes /* remove-proptypes */ = {
   // ┌────────────────────────────── Warning ──────────────────────────────┐
   // │ These PropTypes are generated from the TypeScript type definitions. │
@@ -115,23 +135,3 @@ TabIndicator.propTypes /* remove-proptypes */ = {
    */
   renderBeforeHydration: PropTypes.bool,
 } as any;
-
-export { TabIndicator };
-
-namespace TabIndicator {
-  export interface OwnerState extends TabsRoot.OwnerState {
-    selectedTabPosition: ActiveTabPosition | null;
-    orientation: TabsOrientation;
-    direction: TabsDirection;
-  }
-
-  export interface Props extends BaseUIComponentProps<'span', TabIndicator.OwnerState> {
-    /**
-     * If `true`, the indicator will include code to render itself before React hydrates.
-     * This will minimize the time the indicator is not visible after the SSR-generated content is downloaded.
-     *
-     * @default false
-     */
-    renderBeforeHydration?: boolean;
-  }
-}
diff --git a/packages/react/src/Tabs/TabPanel/TabPanel.tsx b/packages/react/src/Tabs/TabPanel/TabPanel.tsx
index d2e99b3f74..38c6ebb30e 100644
--- a/packages/react/src/Tabs/TabPanel/TabPanel.tsx
+++ b/packages/react/src/Tabs/TabPanel/TabPanel.tsx
@@ -61,6 +61,28 @@ const TabPanel = React.forwardRef(function TabPanel(
   return renderElement();
 });
 
+namespace TabPanel {
+  export interface OwnerState extends TabsRoot.OwnerState {
+    hidden: boolean;
+  }
+
+  export interface Props extends BaseUIComponentProps<'div', OwnerState> {
+    /**
+     * The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected.
+     * If not provided, it will fall back to the index of the panel.
+     * It is recommended to explicitly provide it, as it's required for the tab panel to be rendered on the server.
+     */
+    value?: TabValue;
+    /**
+     * If `true`, keeps the contents of the hidden TabPanel in the DOM.
+     * @default false
+     */
+    keepMounted?: boolean;
+  }
+}
+
+export { TabPanel };
+
 TabPanel.propTypes /* remove-proptypes */ = {
   // ┌────────────────────────────── Warning ──────────────────────────────┐
   // │ These PropTypes are generated from the TypeScript type definitions. │
@@ -90,25 +112,3 @@ TabPanel.propTypes /* remove-proptypes */ = {
    */
   value: PropTypes.any,
 } as any;
-
-export { TabPanel };
-
-namespace TabPanel {
-  export interface OwnerState extends TabsRoot.OwnerState {
-    hidden: boolean;
-  }
-
-  export interface Props extends BaseUIComponentProps<'div', OwnerState> {
-    /**
-     * The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected.
-     * If not provided, it will fall back to the index of the panel.
-     * It is recommended to explicitly provide it, as it's required for the tab panel to be rendered on the server.
-     */
-    value?: TabValue;
-    /**
-     * If `true`, keeps the contents of the hidden TabPanel in the DOM.
-     * @default false
-     */
-    keepMounted?: boolean;
-  }
-}
diff --git a/packages/react/src/Tabs/TabsList/TabsList.tsx b/packages/react/src/Tabs/TabsList/TabsList.tsx
index fb5c890b94..b1b1b9f68e 100644
--- a/packages/react/src/Tabs/TabsList/TabsList.tsx
+++ b/packages/react/src/Tabs/TabsList/TabsList.tsx
@@ -102,6 +102,28 @@ const TabsList = React.forwardRef(function TabsList(
   );
 });
 
+namespace TabsList {
+  export type OwnerState = TabsRoot.OwnerState;
+
+  export interface Props extends BaseUIComponentProps<'div', TabsList.OwnerState> {
+    /**
+     * If `true`, the tab will be activated whenever it is focused.
+     * Otherwise, it has to be activated by clicking or pressing the Enter or Space key.
+     *
+     * @default true
+     */
+    activateOnFocus?: boolean;
+    /**
+     * If `true`, using keyboard navigation will wrap focus to the other end of the list once the end is reached.
+     *
+     * @default true
+     */
+    loop?: boolean;
+  }
+}
+
+export { TabsList };
+
 TabsList.propTypes /* remove-proptypes */ = {
   // ┌────────────────────────────── Warning ──────────────────────────────┐
   // │ These PropTypes are generated from the TypeScript type definitions. │
@@ -133,25 +155,3 @@ TabsList.propTypes /* remove-proptypes */ = {
    */
   render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
 } as any;
-
-export { TabsList };
-
-namespace TabsList {
-  export type OwnerState = TabsRoot.OwnerState;
-
-  export interface Props extends BaseUIComponentProps<'div', TabsList.OwnerState> {
-    /**
-     * If `true`, the tab will be activated whenever it is focused.
-     * Otherwise, it has to be activated by clicking or pressing the Enter or Space key.
-     *
-     * @default true
-     */
-    activateOnFocus?: boolean;
-    /**
-     * If `true`, using keyboard navigation will wrap focus to the other end of the list once the end is reached.
-     *
-     * @default true
-     */
-    loop?: boolean;
-  }
-}

From 7fc654c25e7a87afd09b9f41d7dc4dfc31f99680 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Fri, 22 Nov 2024 18:47:47 +0800
Subject: [PATCH 18/20] Small fixes

---
 packages/react/src/Composite/Item/CompositeItem.tsx | 13 ++-----------
 packages/react/src/Composite/Root/CompositeRoot.tsx | 13 ++-----------
 packages/react/src/Tabs/Tab/useTab.ts               |  7 -------
 packages/react/src/utils/useOnMount.ts              | 13 ++++++++++++-
 4 files changed, 16 insertions(+), 30 deletions(-)

diff --git a/packages/react/src/Composite/Item/CompositeItem.tsx b/packages/react/src/Composite/Item/CompositeItem.tsx
index d050ae03ce..2d298b1768 100644
--- a/packages/react/src/Composite/Item/CompositeItem.tsx
+++ b/packages/react/src/Composite/Item/CompositeItem.tsx
@@ -5,6 +5,7 @@ import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import { useForkRef } from '../../utils/useForkRef';
 import { useCompositeRootContext } from '../Root/CompositeRootContext';
 import { useCompositeItem } from './useCompositeItem';
+import { refType } from '../../utils/proptypes';
 import type { BaseUIComponentProps } from '../../utils/types';
 
 /**
@@ -68,17 +69,7 @@ CompositeItem.propTypes /* remove-proptypes */ = {
   /**
    * @ignore
    */
-  itemRef: PropTypes.shape({
-    current: (props, propName) => {
-      if (props[propName] == null) {
-        return null;
-      }
-      if (typeof props[propName] !== 'object' || props[propName].nodeType !== 1) {
-        return new Error(`Expected prop '${propName}' to be of type Element`);
-      }
-      return null;
-    },
-  }),
+  itemRef: refType,
   /**
    * @ignore
    */
diff --git a/packages/react/src/Composite/Root/CompositeRoot.tsx b/packages/react/src/Composite/Root/CompositeRoot.tsx
index 22e06ae7c2..c8a71a04a0 100644
--- a/packages/react/src/Composite/Root/CompositeRoot.tsx
+++ b/packages/react/src/Composite/Root/CompositeRoot.tsx
@@ -5,6 +5,7 @@ import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import { CompositeList, type CompositeMetadata } from '../List/CompositeList';
 import { useCompositeRoot } from './useCompositeRoot';
 import { CompositeRootContext } from './CompositeRootContext';
+import { refType } from '../../utils/proptypes';
 import type { BaseUIComponentProps } from '../../utils/types';
 import type { Dimensions } from '../composite';
 
@@ -145,17 +146,7 @@ CompositeRoot.propTypes /* remove-proptypes */ = {
   /**
    * @ignore
    */
-  rootRef: PropTypes.shape({
-    current: (props, propName) => {
-      if (props[propName] == null) {
-        return null;
-      }
-      if (typeof props[propName] !== 'object' || props[propName].nodeType !== 1) {
-        return new Error(`Expected prop '${propName}' to be of type Element`);
-      }
-      return null;
-    },
-  }),
+  rootRef: refType,
   /**
    * @ignore
    */
diff --git a/packages/react/src/Tabs/Tab/useTab.ts b/packages/react/src/Tabs/Tab/useTab.ts
index fc7c9789d9..1b0f39c725 100644
--- a/packages/react/src/Tabs/Tab/useTab.ts
+++ b/packages/react/src/Tabs/Tab/useTab.ts
@@ -122,8 +122,6 @@ function useTab(parameters: useTab.Parameters): useTab.ReturnValue {
     index,
     rootRef: handleRef,
     selected,
-    // TODO: recalculate this using Composite stuff, but is it really needed?
-    totalTabsCount: -1,
   };
 }
 
@@ -181,11 +179,6 @@ namespace useTab {
      * If `true`, the tab is selected.
      */
     selected: boolean;
-    /**
-     * Total number of tabs in the nearest parent TabsList.
-     * This can be used to determine if the tab is the last one to style it accordingly.
-     */
-    totalTabsCount: number;
   }
 }
 
diff --git a/packages/react/src/utils/useOnMount.ts b/packages/react/src/utils/useOnMount.ts
index 429fe1db6c..a4a6f20565 100644
--- a/packages/react/src/utils/useOnMount.ts
+++ b/packages/react/src/utils/useOnMount.ts
@@ -1,4 +1,15 @@
+'use client';
+import * as React from 'react';
+
+const EMPTY = [] as unknown[];
+
 /**
+ * A React.useEffect equivalent that runs once, when the component is mounted.
  * @ignore - internal hook.
  */
-export { default as useOnMount } from '@mui/utils/useOnMount';
+export function useOnMount(fn: React.EffectCallback) {
+  // TODO: uncomment once we enable eslint-plugin-react-compiler // eslint-disable-next-line react-compiler/react-compiler -- no need to put `fn` in the dependency array
+  /* eslint-disable react-hooks/exhaustive-deps */
+  React.useEffect(fn, EMPTY);
+  /* eslint-enable react-hooks/exhaustive-deps */
+}

From bf0f41fb293f6a3614230b05dff00981f5c89184 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Fri, 22 Nov 2024 19:01:59 +0800
Subject: [PATCH 19/20] Remove unused hooks

---
 packages/react/src/useCompound/index.ts       |    2 -
 .../src/useCompound/useCompound.test.tsx      |  281 ----
 .../react/src/useCompound/useCompoundItem.ts  |   66 -
 .../src/useCompound/useCompoundParent.ts      |  167 ---
 packages/react/src/useList/ListContext.ts     |   14 -
 packages/react/src/useList/index.ts           |    9 -
 .../react/src/useList/listActions.types.ts    |   82 --
 .../react/src/useList/listReducer.test.ts     | 1230 -----------------
 packages/react/src/useList/listReducer.ts     |  481 -------
 packages/react/src/useList/useList.test.tsx   |  116 --
 packages/react/src/useList/useList.ts         |  373 -----
 packages/react/src/useList/useList.types.ts   |  268 ----
 packages/react/src/useList/useListItem.ts     |  108 --
 .../react/src/useList/useListItem.types.ts    |   42 -
 14 files changed, 3239 deletions(-)
 delete mode 100644 packages/react/src/useCompound/index.ts
 delete mode 100644 packages/react/src/useCompound/useCompound.test.tsx
 delete mode 100644 packages/react/src/useCompound/useCompoundItem.ts
 delete mode 100644 packages/react/src/useCompound/useCompoundParent.ts
 delete mode 100644 packages/react/src/useList/ListContext.ts
 delete mode 100644 packages/react/src/useList/index.ts
 delete mode 100644 packages/react/src/useList/listActions.types.ts
 delete mode 100644 packages/react/src/useList/listReducer.test.ts
 delete mode 100644 packages/react/src/useList/listReducer.ts
 delete mode 100644 packages/react/src/useList/useList.test.tsx
 delete mode 100644 packages/react/src/useList/useList.ts
 delete mode 100644 packages/react/src/useList/useList.types.ts
 delete mode 100644 packages/react/src/useList/useListItem.ts
 delete mode 100644 packages/react/src/useList/useListItem.types.ts

diff --git a/packages/react/src/useCompound/index.ts b/packages/react/src/useCompound/index.ts
deleted file mode 100644
index 2fea72863a..0000000000
--- a/packages/react/src/useCompound/index.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export * from './useCompoundParent';
-export * from './useCompoundItem';
diff --git a/packages/react/src/useCompound/useCompound.test.tsx b/packages/react/src/useCompound/useCompound.test.tsx
deleted file mode 100644
index d508805cbf..0000000000
--- a/packages/react/src/useCompound/useCompound.test.tsx
+++ /dev/null
@@ -1,281 +0,0 @@
-import * as React from 'react';
-import { expect } from 'chai';
-import { render } from '@mui/internal-test-utils';
-import { CompoundComponentContext, useCompoundParent } from './useCompoundParent';
-import { useCompoundItem } from './useCompoundItem';
-
-type ItemValue = { value: string; ref: React.RefObject<HTMLSpanElement> };
-
-describe('compound components', () => {
-  describe('useCompoundParent', () => {
-    it('knows about children from the whole subtree', () => {
-      let parentSubitems: Map<string, ItemValue>;
-
-      function Parent(props: React.PropsWithChildren<{}>) {
-        const { children } = props;
-        const { subitems, contextValue } = useCompoundParent<string, ItemValue>();
-
-        parentSubitems = subitems;
-
-        return (
-          <CompoundComponentContext.Provider value={contextValue}>
-            {children}
-          </CompoundComponentContext.Provider>
-        );
-      }
-
-      function Child(props: React.PropsWithChildren<{ id: string; value: string }>) {
-        const { id, value, children } = props;
-        const ref = React.useRef<HTMLSpanElement>(null);
-        useCompoundItem(
-          id,
-          React.useMemo(() => ({ value, ref }), [value]),
-        );
-
-        return <span ref={ref}>{children}</span>;
-      }
-
-      render(
-        <Parent>
-          <Child id="1" value="one" />
-          <Child id="2" value="two">
-            <Child id="2.1" value="two.one" />
-            <Child id="2.2" value="two.two" />
-          </Child>
-          <Child id="3" value="three">
-            <Child id="3.1" value="three.one">
-              <Child id="3.1.1" value="three.one.one" />
-            </Child>
-          </Child>
-        </Parent>,
-      );
-
-      expect(Array.from(parentSubitems!.keys())).to.deep.equal([
-        '1',
-        '2',
-        '2.1',
-        '2.2',
-        '3',
-        '3.1',
-        '3.1.1',
-      ]);
-
-      expect(Array.from(parentSubitems!.values()).map((v) => v.value)).to.deep.equal([
-        'one',
-        'two',
-        'two.one',
-        'two.two',
-        'three',
-        'three.one',
-        'three.one.one',
-      ]);
-    });
-
-    it('knows about children rendered by other components', () => {
-      let parentSubitems: Map<string, ItemValue>;
-
-      function Parent(props: React.PropsWithChildren<{}>) {
-        const { children } = props;
-        const { subitems, contextValue } = useCompoundParent<string, ItemValue>();
-
-        parentSubitems = subitems;
-
-        return (
-          <CompoundComponentContext.Provider value={contextValue}>
-            {children}
-          </CompoundComponentContext.Provider>
-        );
-      }
-
-      function Child(props: { id: string; value: string }) {
-        const { id, value } = props;
-        const ref = React.useRef<HTMLSpanElement>(null);
-        useCompoundItem(
-          id,
-          React.useMemo(() => ({ value, ref }), [value]),
-        );
-
-        return <span ref={ref} />;
-      }
-
-      function Wrapper() {
-        return (
-          <React.Fragment>
-            <Child id="1" value="one" />
-            <Child id="2" value="two" />
-            <Child id="3" value="three" />
-          </React.Fragment>
-        );
-      }
-
-      render(
-        <Parent>
-          <Child id="0" value="zero" />
-          <Wrapper />
-          <Child id="4" value="four" />
-        </Parent>,
-      );
-
-      expect(Array.from(parentSubitems!.keys())).to.deep.equal(['0', '1', '2', '3', '4']);
-
-      expect(Array.from(parentSubitems!.values()).map((v) => v.value)).to.deep.equal([
-        'zero',
-        'one',
-        'two',
-        'three',
-        'four',
-      ]);
-    });
-
-    // https://github.com/mui/material-ui/issues/36800
-    it('maintains the correct order of children when they are inserted in the middle', () => {
-      let parentSubitems: Map<string, ItemValue>;
-      let subitemsToRender = ['1', '4', '5'];
-
-      function Parent(props: React.PropsWithChildren<{}>) {
-        const { children } = props;
-        const { subitems, contextValue } = useCompoundParent<string, ItemValue>();
-
-        parentSubitems = subitems;
-
-        return (
-          <CompoundComponentContext.Provider value={contextValue}>
-            {children}
-          </CompoundComponentContext.Provider>
-        );
-      }
-
-      function Child(props: React.PropsWithChildren<{ id: string; value: string }>) {
-        const { id, value, children } = props;
-        const ref = React.useRef<HTMLSpanElement>(null);
-        useCompoundItem(
-          id,
-          React.useMemo(() => ({ value, ref }), [value]),
-        );
-
-        return <span ref={ref}>{children}</span>;
-      }
-
-      const { rerender } = render(
-        <Parent>
-          {subitemsToRender.map((item) => (
-            <Child key={item} id={item} value={item} />
-          ))}
-        </Parent>,
-      );
-
-      subitemsToRender = ['1', '2', '3', '4', '5'];
-
-      rerender(
-        <Parent>
-          {subitemsToRender.map((item) => (
-            <Child key={item} id={item} value={item} />
-          ))}
-        </Parent>,
-      );
-
-      expect(Array.from(parentSubitems!.keys())).to.deep.equal(['1', '2', '3', '4', '5']);
-    });
-
-    // TODO: test if removed children are removed from the map
-
-    // TODO: test if parent is notified about updated metadata
-  });
-
-  describe('useCompoundItem', () => {
-    it('knows its position within the parent and total number of registered items', () => {
-      function Parent(props: React.PropsWithChildren<{}>) {
-        const { children } = props;
-        const { contextValue } = useCompoundParent<
-          string,
-          { ref: React.RefObject<HTMLSpanElement> }
-        >();
-
-        return (
-          <CompoundComponentContext.Provider value={contextValue}>
-            {children}
-          </CompoundComponentContext.Provider>
-        );
-      }
-
-      function Child() {
-        const id = React.useId();
-        const ref = React.useRef<HTMLSpanElement>(null);
-        const { index, totalItemCount } = useCompoundItem(
-          id,
-          React.useMemo(() => ({ ref }), []),
-        );
-
-        return (
-          <span data-testid="child" ref={ref}>
-            {index + 1} of {totalItemCount}
-          </span>
-        );
-      }
-
-      const { getAllByTestId } = render(
-        <Parent>
-          <Child />
-          <Child />
-          <React.Fragment>
-            <p>Unrelated element 1</p>
-            <Child />
-          </React.Fragment>
-          <p>Unrelated element 2</p>
-          <div>
-            <Child />
-          </div>
-        </Parent>,
-      );
-
-      const children = getAllByTestId('child');
-
-      children.forEach((child, index) => {
-        expect(child.innerHTML).to.equal(`${index + 1} of 4`);
-      });
-    });
-
-    it('gets assigned a generated id if none is provided', () => {
-      function Parent(props: React.PropsWithChildren<{}>) {
-        const { children } = props;
-        const { contextValue } = useCompoundParent<
-          number,
-          { ref: React.RefObject<HTMLLIElement> }
-        >();
-
-        return (
-          <CompoundComponentContext.Provider value={contextValue}>
-            <ul>{children}</ul>
-          </CompoundComponentContext.Provider>
-        );
-      }
-
-      function idGenerator(existingIds: Set<string>) {
-        return `item-${existingIds.size}`;
-      }
-
-      function Child() {
-        const ref = React.useRef<HTMLLIElement>(null);
-        const { id } = useCompoundItem<string, { ref: React.RefObject<HTMLLIElement | null> }>(
-          idGenerator,
-          React.useMemo(() => ({ ref }), []),
-        );
-
-        return <li ref={ref}>{id}</li>;
-      }
-
-      const { getAllByRole } = render(
-        <Parent>
-          <Child />
-          <Child />
-          <Child />
-        </Parent>,
-      );
-
-      const children = getAllByRole('listitem');
-      expect(children[0].innerHTML).to.equal('item-0');
-      expect(children[1].innerHTML).to.equal('item-1');
-      expect(children[2].innerHTML).to.equal('item-2');
-    });
-  });
-});
diff --git a/packages/react/src/useCompound/useCompoundItem.ts b/packages/react/src/useCompound/useCompoundItem.ts
deleted file mode 100644
index 1c65a8d8da..0000000000
--- a/packages/react/src/useCompound/useCompoundItem.ts
+++ /dev/null
@@ -1,66 +0,0 @@
-'use client';
-import * as React from 'react';
-import { unstable_useEnhancedEffect as useEnhancedEffect } from '@mui/utils';
-import {
-  CompoundComponentContext,
-  CompoundComponentContextValue,
-  KeyGenerator,
-} from './useCompoundParent';
-
-export interface UseCompoundItemReturnValue<Key> {
-  /**
-   * The unique key for the child component.
-   * If the id was provided to `useCompoundItem`, this will be the same value.
-   * Otherwise, this will be a value generated by the `id` function.
-   */
-  id: Key | undefined;
-  /**
-   * The 0-based index of the child component in the parent component's list of registered children.
-   */
-  index: number;
-  /**
-   * The total number of child components registered with the parent component.
-   * This value will be correct after the effect phase of the component (as children are registered with the parent during the effect phase).
-   */
-  totalItemCount: number;
-}
-
-/**
- * Registers a child component with the parent component.
- *
- * @param id A unique key for the child component. If the `id` is `undefined`, the registration logic will not run (this can sometimes be the case during SSR).
- *   This can be either a value, or a function that generates a value based on already registered siblings' ids.
- *   If a function, it's called with the set of the ids of all the items that have already been registered.
- *   Return `existingKeys.size` if you want to use the index of the new item as the id.
- * @param itemMetadata Arbitrary metadata to pass to the parent component. This should be a stable reference (for example a memoized object), to avoid unnecessary re-registrations.
- *
- * @ignore - internal hook.
- */
-export function useCompoundItem<Key, Subitem>(
-  id: Key | KeyGenerator<Key>,
-  itemMetadata: Subitem,
-): UseCompoundItemReturnValue<Key> {
-  const context = React.useContext(CompoundComponentContext) as CompoundComponentContextValue<
-    Key,
-    Subitem
-  >;
-
-  if (context === null) {
-    throw new Error('useCompoundItem must be used within a useCompoundParent');
-  }
-
-  const { registerItem } = context;
-  const [registeredId, setRegisteredId] = React.useState(typeof id === 'function' ? undefined : id);
-
-  useEnhancedEffect(() => {
-    const { id: returnedId, deregister } = registerItem(id, itemMetadata);
-    setRegisteredId(returnedId);
-    return deregister;
-  }, [registerItem, itemMetadata, id]);
-
-  return {
-    id: registeredId,
-    index: registeredId !== undefined ? context.getItemIndex(registeredId) : -1,
-    totalItemCount: context.totalSubitemCount,
-  };
-}
diff --git a/packages/react/src/useCompound/useCompoundParent.ts b/packages/react/src/useCompound/useCompoundParent.ts
deleted file mode 100644
index 99f0b20827..0000000000
--- a/packages/react/src/useCompound/useCompoundParent.ts
+++ /dev/null
@@ -1,167 +0,0 @@
-'use client';
-import * as React from 'react';
-
-interface RegisterItemReturnValue<Key> {
-  /**
-   * The id of the item.
-   */
-  id: Key;
-  /**
-   * A function that deregisters the item.
-   */
-  deregister: () => void;
-}
-
-export type KeyGenerator<Key> = (existingKeys: Set<Key>) => Key;
-
-export type CompoundComponentContextValue<Key, Subitem> = {
-  /**
-   * Registers an item with the parent.
-   * This should be called during the effect phase of the child component.
-   * The `itemMetadata` should be a stable reference (for example a memoized object), to avoid unnecessary re-registrations.
-   *
-   * @param id Id of the item or A function that generates a unique id for the item.
-   *   It is called with the set of the ids of all the items that have already been registered.
-   *   Return `existingKeys.size` if you want to use the index of the new item as the id..
-   * @param itemMetadata Arbitrary metadata to pass to the parent component.
-   */
-  registerItem: (id: Key | KeyGenerator<Key>, item: Subitem) => RegisterItemReturnValue<Key>;
-  /**
-   * Returns the 0-based index of the item in the parent component's list of registered items.
-   *
-   * @param id id of the item.
-   */
-  getItemIndex: (id: Key) => number;
-  /**
-   * The total number of items registered with the parent.
-   */
-  totalSubitemCount: number;
-};
-
-export const CompoundComponentContext = React.createContext<CompoundComponentContextValue<
-  any,
-  any
-> | null>(null);
-
-if (process.env.NODE_ENV !== 'production') {
-  CompoundComponentContext.displayName = 'CompoundComponentContext';
-}
-
-export interface UseCompoundParentReturnValue<
-  Key,
-  Subitem extends { ref: React.RefObject<Node | null> },
-> {
-  /**
-   * The value for the CompoundComponentContext provider.
-   */
-  contextValue: CompoundComponentContextValue<Key, Subitem>;
-  /**
-   * The subitems registered with the parent.
-   * The key is the id of the subitem, and the value is the metadata passed to the `useCompoundItem` hook.
-   * The order of the items is the same as the order in which they were registered.
-   */
-  subitems: Map<Key, Subitem>;
-}
-
-/**
- * Sorts the subitems by their position in the DOM.
- */
-function sortSubitems<Key, Subitem extends { ref: React.RefObject<Node | null> }>(
-  subitems: Map<Key, Subitem>,
-) {
-  const subitemsArray = Array.from(subitems.keys()).map((key) => {
-    const subitem = subitems.get(key)!;
-    return { key, subitem };
-  });
-
-  subitemsArray.sort((a, b) => {
-    const aNode = a.subitem.ref.current;
-    const bNode = b.subitem.ref.current;
-
-    if (aNode === null || bNode === null || aNode === bNode) {
-      return 0;
-    }
-
-    // eslint-disable-next-line no-bitwise
-    return aNode.compareDocumentPosition(bNode) & Node.DOCUMENT_POSITION_PRECEDING ? 1 : -1;
-  });
-
-  return new Map(subitemsArray.map((item) => [item.key, item.subitem]));
-}
-
-/**
- * Provides a way for a component to know about its children.
- *
- * Child components register themselves with the `useCompoundItem` hook, passing in arbitrary metadata to the parent.
- *
- * This is a more powerful altervantive to `children` traversal, as child components don't have to be placed
- * directly inside the parent component. They can be anywhere in the tree (and even rendered by other components).
- *
- * The downside is that this doesn't work with SSR as it relies on the useEffect hook.
- *
- * @ignore - internal hook.
- */
-export function useCompoundParent<
-  Key,
-  Subitem extends { ref: React.RefObject<Node | null> },
->(): UseCompoundParentReturnValue<Key, Subitem> {
-  const [subitems, setSubitems] = React.useState(new Map<Key, Subitem>());
-  const subitemKeys = React.useRef(new Set<Key>());
-
-  const deregisterItem = React.useCallback(function deregisterItem(id: Key) {
-    subitemKeys.current.delete(id);
-    setSubitems((previousState) => {
-      const newState = new Map(previousState);
-      newState.delete(id);
-      return newState;
-    });
-  }, []);
-
-  const registerItem = React.useCallback(
-    function registerItem(id: Key | KeyGenerator<Key>, item: Subitem) {
-      let providedOrGeneratedId: Key;
-
-      if (typeof id === 'function') {
-        providedOrGeneratedId = (id as KeyGenerator<Key>)(subitemKeys.current);
-      } else {
-        providedOrGeneratedId = id;
-      }
-
-      subitemKeys.current.add(providedOrGeneratedId);
-      setSubitems((previousState) => {
-        const newState = new Map(previousState);
-        newState.set(providedOrGeneratedId, item);
-        return newState;
-      });
-
-      return {
-        id: providedOrGeneratedId,
-        deregister: () => deregisterItem(providedOrGeneratedId),
-      };
-    },
-    [deregisterItem],
-  );
-
-  const sortedSubitems = React.useMemo(() => sortSubitems(subitems), [subitems]);
-
-  const getItemIndex = React.useCallback(
-    function getItemIndex(id: Key) {
-      return Array.from(sortedSubitems.keys()).indexOf(id);
-    },
-    [sortedSubitems],
-  );
-
-  const contextValue = React.useMemo(
-    () => ({
-      getItemIndex,
-      registerItem,
-      totalSubitemCount: subitems.size,
-    }),
-    [getItemIndex, registerItem, subitems.size],
-  );
-
-  return {
-    contextValue,
-    subitems: sortedSubitems,
-  };
-}
diff --git a/packages/react/src/useList/ListContext.ts b/packages/react/src/useList/ListContext.ts
deleted file mode 100644
index 323a10023a..0000000000
--- a/packages/react/src/useList/ListContext.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-'use client';
-import * as React from 'react';
-import { ListAction } from './listActions.types';
-import { ListItemState } from './useList.types';
-
-export interface ListContextValue<ItemValue> {
-  dispatch: (action: ListAction<ItemValue>) => void;
-  getItemState: (item: ItemValue) => ListItemState;
-}
-
-export const ListContext = React.createContext<ListContextValue<any> | null>(null);
-if (process.env.NODE_ENV !== 'production') {
-  ListContext.displayName = 'ListContext';
-}
diff --git a/packages/react/src/useList/index.ts b/packages/react/src/useList/index.ts
deleted file mode 100644
index 1d6568987e..0000000000
--- a/packages/react/src/useList/index.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-export { useList } from './useList';
-export * from './useList.types';
-
-export { useListItem } from './useListItem';
-export * from './useListItem.types';
-
-export * from './listReducer';
-export * from './listActions.types';
-export * from './ListContext';
diff --git a/packages/react/src/useList/listActions.types.ts b/packages/react/src/useList/listActions.types.ts
deleted file mode 100644
index 848858100c..0000000000
--- a/packages/react/src/useList/listActions.types.ts
+++ /dev/null
@@ -1,82 +0,0 @@
-export const ListActionTypes = {
-  blur: 'list:blur',
-  focus: 'list:focus',
-  itemClick: 'list:itemClick',
-  itemHover: 'list:itemHover',
-  itemsChange: 'list:itemsChange',
-  keyDown: 'list:keyDown',
-  resetHighlight: 'list:resetHighlight',
-  highlightLast: 'list:highlightLast',
-  textNavigation: 'list:textNavigation',
-  clearSelection: 'list:clearSelection',
-} as const;
-
-interface ItemClickAction<ItemValue> {
-  type: typeof ListActionTypes.itemClick;
-  item: ItemValue;
-  event: React.MouseEvent;
-}
-
-interface ItemHoverAction<ItemValue> {
-  type: typeof ListActionTypes.itemHover;
-  item: ItemValue;
-  event: React.MouseEvent;
-}
-
-interface FocusAction {
-  type: typeof ListActionTypes.focus;
-  event: React.FocusEvent;
-}
-
-interface BlurAction {
-  type: typeof ListActionTypes.blur;
-  event: React.FocusEvent;
-}
-
-interface KeyDownAction {
-  type: typeof ListActionTypes.keyDown;
-  key: string;
-  event: React.KeyboardEvent;
-}
-
-interface TextNavigationAction {
-  type: typeof ListActionTypes.textNavigation;
-  event: React.KeyboardEvent;
-  searchString: string;
-}
-
-interface ItemsChangeAction<ItemValue> {
-  type: typeof ListActionTypes.itemsChange;
-  event: null;
-  items: ItemValue[];
-  previousItems: ItemValue[];
-}
-
-interface ResetHighlightAction {
-  type: typeof ListActionTypes.resetHighlight;
-  event: React.SyntheticEvent | null;
-}
-
-interface HighlightLastAction {
-  type: typeof ListActionTypes.highlightLast;
-  event: React.SyntheticEvent | null;
-}
-
-interface ClearSelectionAction {
-  type: typeof ListActionTypes.clearSelection;
-}
-
-/**
- * A union of all standard actions that can be dispatched to the list reducer.
- */
-export type ListAction<ItemValue> =
-  | BlurAction
-  | FocusAction
-  | ItemClickAction<ItemValue>
-  | ItemHoverAction<ItemValue>
-  | ItemsChangeAction<ItemValue>
-  | KeyDownAction
-  | ResetHighlightAction
-  | HighlightLastAction
-  | TextNavigationAction
-  | ClearSelectionAction;
diff --git a/packages/react/src/useList/listReducer.test.ts b/packages/react/src/useList/listReducer.test.ts
deleted file mode 100644
index 1a60ac1f74..0000000000
--- a/packages/react/src/useList/listReducer.test.ts
+++ /dev/null
@@ -1,1230 +0,0 @@
-import * as React from 'react';
-import { expect } from 'chai';
-import { listReducer } from './listReducer';
-import { ListReducerAction, ListState } from './useList.types';
-import { ListActionTypes } from './listActions.types';
-
-describe('listReducer', () => {
-  describe('action: blur', () => {
-    it('resets the highlightedValue', () => {
-      const state: ListState<string> = {
-        highlightedValue: 'a',
-        selectedValues: [],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.blur,
-        event: {} as any, // not relevant
-        context: {
-          items: [],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'activeDescendant',
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'single',
-        },
-      };
-
-      const result = listReducer(state, action);
-      expect(result.highlightedValue).to.equal(null);
-    });
-  });
-
-  describe('action: itemClick', () => {
-    it('sets the selectedValues to the clicked value', () => {
-      const state: ListState<string> = {
-        highlightedValue: 'a',
-        selectedValues: [],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.itemClick,
-        event: {} as any, // not relevant
-        context: {
-          items: ['one', 'two', 'three'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'activeDescendant',
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'single',
-        },
-        item: 'two',
-      };
-
-      const result = listReducer(state, action);
-      expect(result.selectedValues).to.deep.equal(['two']);
-    });
-
-    it('does not select a disabled item', () => {
-      const state: ListState<string> = {
-        highlightedValue: null,
-        selectedValues: [],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.itemClick,
-        event: {} as any, // not relevant
-        context: {
-          items: ['one', 'two', 'three'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'activeDescendant',
-          isItemDisabled: (item) => item === 'two',
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'single',
-        },
-        item: 'two',
-      };
-
-      const result = listReducer(state, action);
-      expect(result.highlightedValue).to.equal(null);
-      expect(result.selectedValues).to.deep.equal([]);
-    });
-
-    it('replaces the selectedValues with the clicked value if selectionMode = "single"', () => {
-      const state: ListState<string> = {
-        highlightedValue: 'a',
-        selectedValues: ['one'],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.itemClick,
-        event: {} as any, // not relevant
-        context: {
-          items: ['one', 'two', 'three'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'activeDescendant',
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'single',
-        },
-        item: 'two',
-      };
-
-      const result = listReducer(state, action);
-      expect(result.selectedValues).to.deep.equal(['two']);
-    });
-
-    it('add the clicked value to the selection if selectionMode = "multiple"', () => {
-      const state: ListState<string> = {
-        highlightedValue: 'one',
-        selectedValues: ['one'],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.itemClick,
-        event: {} as any, // not relevant
-        context: {
-          items: ['one', 'two', 'three'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'activeDescendant',
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'multiple',
-        },
-        item: 'two',
-      };
-
-      const result = listReducer(state, action);
-      expect(result.selectedValues).to.deep.equal(['one', 'two']);
-    });
-
-    it('remove the clicked value from the selection if selectionMode = "multiple" and it was selected already', () => {
-      const state: ListState<string> = {
-        highlightedValue: 'three',
-        selectedValues: ['one', 'two'],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.itemClick,
-        event: {} as any, // not relevant
-        context: {
-          items: ['one', 'two', 'three'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'activeDescendant',
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'multiple',
-        },
-        item: 'two',
-      };
-
-      const result = listReducer(state, action);
-      expect(result.selectedValues).to.deep.equal(['one']);
-    });
-
-    it('does not select the clicked value to the selection if selectionMode = "none"', () => {
-      const state: ListState<string> = {
-        highlightedValue: 'one',
-        selectedValues: [],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.itemClick,
-        event: {} as any, // not relevant
-        context: {
-          items: ['one', 'two', 'three'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'activeDescendant',
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'none',
-        },
-        item: 'two',
-      };
-
-      const result = listReducer(state, action);
-      expect(result.selectedValues).to.deep.equal([]);
-    });
-  });
-
-  describe('action: keyDown', () => {
-    interface KeydownTestCase {
-      description: string;
-      key: string;
-      initialHighlightedItem: string | null;
-      disabledItemFocusable: boolean;
-      disabledItems: string[];
-      disableListWrap: boolean;
-      expected: string | null;
-    }
-
-    const testCases: KeydownTestCase[] = [
-      {
-        description: 'happy path',
-        key: 'Home',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: [],
-        disableListWrap: false,
-        expected: '1',
-      },
-      {
-        description: 'highlights the first enabled item',
-        key: 'Home',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: ['1'],
-        disableListWrap: false,
-        expected: '2',
-      },
-      {
-        description: 'highlights the first enabled item',
-        key: 'Home',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: ['1', '2'],
-        disableListWrap: false,
-        expected: '3',
-      },
-      {
-        description: 'highlights the first item even if it is disabled',
-        key: 'Home',
-        initialHighlightedItem: null,
-        disabledItemFocusable: true,
-        disabledItems: ['1'],
-        disableListWrap: false,
-        expected: '1',
-      },
-      {
-        description: 'all disabled',
-        key: 'Home',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: ['1', '2', '3', '4', '5'],
-        disableListWrap: false,
-        expected: null,
-      },
-      {
-        description: 'all disabled but focusable',
-        key: 'Home',
-        initialHighlightedItem: null,
-        disabledItemFocusable: true,
-        disabledItems: ['1', '2', '3', '4', '5'],
-        disableListWrap: false,
-        expected: '1',
-      },
-      {
-        description: 'happy path',
-        key: 'End',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: [],
-        disableListWrap: false,
-        expected: '5',
-      },
-      {
-        description: 'highlights the last enabled item',
-        key: 'End',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: ['5'],
-        disableListWrap: false,
-        expected: '4',
-      },
-      {
-        description: 'highlights the last enabled item',
-        key: 'End',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: ['4', '5'],
-        disableListWrap: false,
-        expected: '3',
-      },
-      {
-        description: 'highlights the last item even if it is disabled',
-        key: 'End',
-        initialHighlightedItem: null,
-        disabledItemFocusable: true,
-        disabledItems: ['5'],
-        disableListWrap: false,
-        expected: '5',
-      },
-      {
-        description: 'all disabled',
-        key: 'End',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: ['1', '2', '3', '4', '5'],
-        disableListWrap: false,
-        expected: null,
-      },
-      {
-        description: 'all disabled but focusable',
-        key: 'End',
-        initialHighlightedItem: null,
-        disabledItemFocusable: true,
-        disabledItems: ['1', '2', '3', '4', '5'],
-        disableListWrap: false,
-        expected: '5',
-      },
-      {
-        description: 'happy path',
-        key: 'ArrowDown',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: [],
-        disableListWrap: false,
-        expected: '1',
-      },
-      {
-        description: 'happy path',
-        key: 'ArrowDown',
-        initialHighlightedItem: '1',
-        disabledItemFocusable: false,
-        disabledItems: [],
-        disableListWrap: false,
-        expected: '2',
-      },
-      {
-        description: 'skips the disabled item',
-        key: 'ArrowDown',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: ['1'],
-        disableListWrap: false,
-        expected: '2',
-      },
-      {
-        description: 'skips multiple disabled items',
-        key: 'ArrowDown',
-        initialHighlightedItem: '1',
-        disabledItemFocusable: false,
-        disabledItems: ['2', '3'],
-        disableListWrap: false,
-        expected: '4',
-      },
-      {
-        description: 'skips the disabled items and wraps around',
-        key: 'ArrowDown',
-        initialHighlightedItem: '3',
-        disabledItemFocusable: false,
-        disabledItems: ['1', '4', '5'],
-        disableListWrap: false,
-        expected: '2',
-      },
-      {
-        description: 'focuses the disabled item',
-        key: 'ArrowDown',
-        initialHighlightedItem: null,
-        disabledItemFocusable: true,
-        disabledItems: ['1'],
-        disableListWrap: false,
-        expected: '1',
-      },
-      {
-        description: 'does not wrap around',
-        key: 'ArrowDown',
-        initialHighlightedItem: '5',
-        disabledItemFocusable: false,
-        disabledItems: [],
-        disableListWrap: true,
-        expected: '5',
-      },
-      {
-        description: 'remains on the same item when all the next are disabled',
-        key: 'ArrowDown',
-        initialHighlightedItem: '3',
-        disabledItemFocusable: false,
-        disabledItems: ['4', '5'],
-        disableListWrap: true,
-        expected: '3',
-      },
-      {
-        description: 'all disabled',
-        key: 'ArrowDown',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: ['1', '2', '3', '4', '5'],
-        disableListWrap: false,
-        expected: null,
-      },
-      {
-        description: 'all disabled but focusable',
-        key: 'ArrowDown',
-        initialHighlightedItem: null,
-        disabledItemFocusable: true,
-        disabledItems: ['1', '2', '3', '4', '5'],
-        disableListWrap: false,
-        expected: '1',
-      },
-      {
-        description: 'happy path',
-        key: 'ArrowUp',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: [],
-        disableListWrap: false,
-        expected: '5',
-      },
-      {
-        description: 'happy path',
-        key: 'ArrowUp',
-        initialHighlightedItem: '2',
-        disabledItemFocusable: false,
-        disabledItems: [],
-        disableListWrap: false,
-        expected: '1',
-      },
-      {
-        description: 'skips the disabled item',
-        key: 'ArrowUp',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: ['5'],
-        disableListWrap: false,
-        expected: '4',
-      },
-      {
-        description: 'skips multiple disabled items',
-        key: 'ArrowUp',
-        initialHighlightedItem: '1',
-        disabledItemFocusable: false,
-        disabledItems: ['4', '5'],
-        disableListWrap: false,
-        expected: '3',
-      },
-      {
-        description: 'skips the disabled items and wraps around',
-        key: 'ArrowUp',
-        initialHighlightedItem: '2',
-        disabledItemFocusable: false,
-        disabledItems: ['1', '4', '5'],
-        disableListWrap: false,
-        expected: '3',
-      },
-      {
-        description: 'focuses the disabled item',
-        key: 'ArrowUp',
-        initialHighlightedItem: null,
-        disabledItemFocusable: true,
-        disabledItems: ['5'],
-        disableListWrap: false,
-        expected: '5',
-      },
-      {
-        description: 'does not wrap around',
-        key: 'ArrowUp',
-        initialHighlightedItem: '1',
-        disabledItemFocusable: false,
-        disabledItems: [],
-        disableListWrap: true,
-        expected: '1',
-      },
-      {
-        description: 'remains on the same item when all the previous are disabled',
-        key: 'ArrowUp',
-        initialHighlightedItem: '3',
-        disabledItemFocusable: false,
-        disabledItems: ['1', '2'],
-        disableListWrap: true,
-        expected: '3',
-      },
-      {
-        description: 'all disabled',
-        key: 'ArrowUp',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: ['1', '2', '3', '4', '5'],
-        disableListWrap: false,
-        expected: null,
-      },
-      {
-        description: 'all disabled but focusable',
-        key: 'ArrowUp',
-        initialHighlightedItem: null,
-        disabledItemFocusable: true,
-        disabledItems: ['1', '2', '3', '4', '5'],
-        disableListWrap: false,
-        expected: '5',
-      },
-      {
-        description: 'happy path',
-        key: 'PageDown',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: [],
-        disableListWrap: false,
-        expected: '3',
-      },
-      {
-        description: 'skips the disabled item',
-        key: 'PageDown',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: ['3'],
-        disableListWrap: false,
-        expected: '4',
-      },
-      {
-        description: 'does not wrap around, no matter the setting',
-        key: 'PageDown',
-        initialHighlightedItem: '4',
-        disabledItemFocusable: false,
-        disabledItems: [],
-        disableListWrap: false,
-        expected: '5',
-      },
-      {
-        description: 'does not wrap around, no matter the setting, and skips the disabled item',
-        key: 'PageDown',
-        initialHighlightedItem: '3',
-        disabledItemFocusable: false,
-        disabledItems: ['5'],
-        disableListWrap: false,
-        expected: '4',
-      },
-      {
-        description: 'happy path',
-        key: 'PageUp',
-        initialHighlightedItem: null,
-        disabledItemFocusable: false,
-        disabledItems: [],
-        disableListWrap: false,
-        expected: '1',
-      },
-      {
-        description: 'skips the disabled item',
-        key: 'PageUp',
-        initialHighlightedItem: '5',
-        disabledItemFocusable: false,
-        disabledItems: ['2'],
-        disableListWrap: false,
-        expected: '1',
-      },
-      {
-        description: 'does not wrap around, no matter the setting',
-        key: 'PageUp',
-        initialHighlightedItem: '2',
-        disabledItemFocusable: false,
-        disabledItems: [],
-        disableListWrap: false,
-        expected: '1',
-      },
-      {
-        description: 'does not wrap around, no matter the setting, and skips the disabled item',
-        key: 'PageUp',
-        initialHighlightedItem: '3',
-        disabledItemFocusable: false,
-        disabledItems: ['1'],
-        disableListWrap: false,
-        expected: '2',
-      },
-    ];
-
-    testCases.forEach((spec: KeydownTestCase) => {
-      describe(`given initialHighlightedItem: '${
-        spec.initialHighlightedItem
-      }', disabledItemsFocusable: ${spec.disabledItemFocusable}, disableListWrap: ${
-        spec.disableListWrap
-      }, disabledItems: [${spec.disabledItems.join()}]`, () => {
-        it(`${spec.description}: should highlight the '${spec.expected}' item after the ${spec.key} is pressed`, () => {
-          const state: ListState<string> = {
-            highlightedValue: spec.initialHighlightedItem,
-            selectedValues: [],
-          };
-
-          const action: ListReducerAction<string> = {
-            type: ListActionTypes.keyDown,
-            key: spec.key,
-            event: null as any, // not relevant
-            context: {
-              items: ['1', '2', '3', '4', '5'],
-              disableListWrap: spec.disableListWrap,
-              disabledItemsFocusable: spec.disabledItemFocusable,
-              focusManagement: 'activeDescendant',
-              isItemDisabled: (item) => spec.disabledItems.includes(item),
-              itemComparer: (o, v) => o === v,
-              getItemAsString: (option) => option,
-              orientation: 'vertical',
-              pageSize: 3,
-              selectionMode: 'single',
-            },
-          };
-
-          const result = listReducer(state, action);
-          expect(result.highlightedValue).to.equal(spec.expected);
-        });
-      });
-    });
-
-    describe('Enter key is pressed', () => {
-      it('selects the highlighted option', () => {
-        const state: ListState<string> = {
-          highlightedValue: 'two',
-          selectedValues: [],
-        };
-
-        const action: ListReducerAction<string> = {
-          type: ListActionTypes.keyDown,
-          key: 'Enter',
-          event: {} as any,
-          context: {
-            items: ['one', 'two', 'three'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            getItemAsString: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionMode: 'single',
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.selectedValues).to.deep.equal(['two']);
-      });
-
-      it('replaces the selectedValues with the highlighted value if selectionMode = "single"', () => {
-        const state: ListState<string> = {
-          highlightedValue: 'two',
-          selectedValues: ['one'],
-        };
-
-        const action: ListReducerAction<string> = {
-          type: ListActionTypes.keyDown,
-          key: 'Enter',
-          event: {} as any,
-          context: {
-            items: ['one', 'two', 'three'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            getItemAsString: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionMode: 'single',
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.selectedValues).to.deep.equal(['two']);
-      });
-
-      it('add the highlighted value to the selection if selectionMode = "multiple"', () => {
-        const state: ListState<string> = {
-          highlightedValue: 'two',
-          selectedValues: ['one'],
-        };
-
-        const action: ListReducerAction<string> = {
-          type: ListActionTypes.keyDown,
-          key: 'Enter',
-          event: {} as any,
-          context: {
-            items: ['one', 'two', 'three'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            getItemAsString: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionMode: 'multiple',
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.selectedValues).to.deep.equal(['one', 'two']);
-      });
-    });
-  });
-
-  describe('action: textNavigation', () => {
-    it('should navigate to next match', () => {
-      const state: ListState<string> = {
-        highlightedValue: 'two',
-        selectedValues: [],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.textNavigation,
-        searchString: 'th',
-        event: {} as React.KeyboardEvent,
-        context: {
-          items: ['one', 'two', 'three', 'four', 'five'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'activeDescendant',
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'single',
-        },
-      };
-
-      const result = listReducer(state, action);
-      expect(result.highlightedValue).to.equal('three');
-    });
-
-    it('should not move the highlight when there are no matched items', () => {
-      const state: ListState<string> = {
-        highlightedValue: 'one',
-        selectedValues: [],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.textNavigation,
-        searchString: 'z',
-        event: {} as React.KeyboardEvent,
-        context: {
-          items: ['one', 'two', 'three', 'four', 'five'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'activeDescendant',
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'single',
-        },
-      };
-
-      const result = listReducer(state, action);
-      expect(result.highlightedValue).to.equal('one');
-    });
-
-    it('should highlight first match that is not disabled', () => {
-      const state: ListState<string> = {
-        highlightedValue: 'one',
-        selectedValues: [],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.textNavigation,
-        searchString: 't',
-        event: {} as React.KeyboardEvent,
-        context: {
-          items: ['one', 'two', 'three', 'four', 'five'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'activeDescendant',
-          isItemDisabled: (_, i) => i === 1,
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'single',
-        },
-      };
-
-      const result = listReducer(state, action);
-      expect(result.highlightedValue).to.equal('three');
-    });
-
-    it('should move highlight to disabled items if disabledItemsFocusable=true', () => {
-      const state: ListState<string> = {
-        highlightedValue: 'one',
-        selectedValues: [],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.textNavigation,
-        searchString: 't',
-        event: {} as React.KeyboardEvent,
-        context: {
-          items: ['one', 'two', 'three', 'four', 'five'],
-          disableListWrap: false,
-          disabledItemsFocusable: true,
-          focusManagement: 'activeDescendant',
-          isItemDisabled: (_, i) => i === 1,
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'single',
-        },
-      };
-
-      const result = listReducer(state, action);
-      expect(result.highlightedValue).to.equal('two');
-    });
-
-    it('should not move highlight when disabled wrap and match is before highlighted option', () => {
-      const state: ListState<string> = {
-        highlightedValue: 'three',
-        selectedValues: [],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.textNavigation,
-        searchString: 'one',
-        event: {} as React.KeyboardEvent,
-        context: {
-          items: ['one', 'two', 'three', 'four', 'five'],
-          disableListWrap: true,
-          disabledItemsFocusable: false,
-          focusManagement: 'activeDescendant',
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'single',
-        },
-      };
-
-      const result = listReducer(state, action);
-      expect(result.highlightedValue).to.equal('three');
-    });
-  });
-
-  describe('action: itemsChange', () => {
-    const irrelevantConfig = {
-      disableListWrap: false,
-      disabledItemsFocusable: false,
-      focusManagement: 'activeDescendant' as const,
-      isItemDisabled: () => false,
-      getItemAsString: (option: any) => option,
-      orientation: 'vertical' as const,
-      pageSize: 5,
-      selectionMode: 'single' as const,
-    };
-
-    describe('using default item comparer', () => {
-      it('keeps the highlighted value if it is present among the new items', () => {
-        const state: ListState<string> = {
-          highlightedValue: '1',
-          selectedValues: [],
-        };
-
-        const action: ListReducerAction<string> = {
-          type: ListActionTypes.itemsChange,
-          event: null,
-          items: ['1', '2'],
-          previousItems: ['0', '1', '2'],
-          context: {
-            items: ['1', '2'],
-            itemComparer: (o, v) => o === v,
-            ...irrelevantConfig,
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.highlightedValue).to.equal('1');
-      });
-
-      it('resets the highlighted value if it is not present among the new items', () => {
-        const state: ListState<string> = {
-          highlightedValue: '0',
-          selectedValues: [],
-        };
-
-        const action: ListReducerAction<string> = {
-          type: ListActionTypes.itemsChange,
-          event: null,
-          items: ['1', '2'],
-          previousItems: ['0', '1', '2'],
-          context: {
-            items: ['1', '2'],
-            itemComparer: (o, v) => o === v,
-            ...irrelevantConfig,
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.highlightedValue).to.equal(null);
-      });
-
-      it('keeps the selected values if they are present among the new items', () => {
-        const state: ListState<string> = {
-          highlightedValue: '1',
-          selectedValues: ['1', '2'],
-        };
-
-        const action: ListReducerAction<string> = {
-          type: ListActionTypes.itemsChange,
-          event: null,
-          items: ['1', '2'],
-          previousItems: ['0', '1', '2'],
-          context: {
-            items: ['1', '2'],
-            itemComparer: (o, v) => o === v,
-            ...irrelevantConfig,
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.selectedValues).to.deep.equal(['1', '2']);
-      });
-
-      it('removes the values from the selection if they are no longer present among the new items', () => {
-        const state: ListState<string> = {
-          highlightedValue: '1',
-          selectedValues: ['0', '2'],
-        };
-
-        const action: ListReducerAction<string> = {
-          type: ListActionTypes.itemsChange,
-          event: null,
-          items: ['1', '2'],
-          previousItems: ['0', '1', '2'],
-          context: {
-            items: ['1', '2'],
-            itemComparer: (o, v) => o === v,
-            ...irrelevantConfig,
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.selectedValues).to.deep.equal(['2']);
-      });
-    });
-
-    describe('using custom item comparer', () => {
-      type ItemType = { v: string };
-
-      it('keeps the highlighted value if it is present among the new items', () => {
-        const state: ListState<ItemType> = {
-          highlightedValue: { v: '1' },
-          selectedValues: [],
-        };
-
-        const action: ListReducerAction<ItemType> = {
-          type: ListActionTypes.itemsChange,
-          event: null,
-          items: [{ v: '1' }, { v: '2' }],
-          previousItems: [{ v: '0' }, { v: '1' }, { v: '2' }],
-          context: {
-            items: [{ v: '1' }, { v: '2' }],
-            itemComparer: (a, b) => a.v === b.v,
-            ...irrelevantConfig,
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.highlightedValue?.v).to.equal('1');
-      });
-
-      it('resets the highlighted value if it is not present among the new items', () => {
-        const state: ListState<ItemType> = {
-          highlightedValue: { v: '0' },
-          selectedValues: [],
-        };
-
-        const action: ListReducerAction<ItemType> = {
-          type: ListActionTypes.itemsChange,
-          event: null,
-          items: [{ v: '1' }, { v: '2' }],
-          previousItems: [{ v: '0' }, { v: '1' }, { v: '2' }],
-          context: {
-            items: [{ v: '1' }, { v: '2' }],
-            itemComparer: (a, b) => a.v === b.v,
-            ...irrelevantConfig,
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.highlightedValue).to.equal(null);
-      });
-
-      it('keeps the selected values if they are present among the new items', () => {
-        const state: ListState<ItemType> = {
-          highlightedValue: { v: '1' },
-          selectedValues: [{ v: '1' }, { v: '2' }],
-        };
-
-        const action: ListReducerAction<ItemType> = {
-          type: ListActionTypes.itemsChange,
-          event: null,
-          items: [{ v: '1' }, { v: '2' }],
-          previousItems: [{ v: '0' }, { v: '1' }, { v: '2' }],
-          context: {
-            items: [{ v: '1' }, { v: '2' }],
-            itemComparer: (a, b) => a.v === b.v,
-            ...irrelevantConfig,
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.selectedValues.map((sv) => sv.v)).to.deep.equal(['1', '2']);
-      });
-
-      it('removes the values from the selection if they are no longer present among the new items', () => {
-        const state: ListState<ItemType> = {
-          highlightedValue: { v: '1' },
-          selectedValues: [{ v: '0' }, { v: '2' }],
-        };
-
-        const action: ListReducerAction<ItemType> = {
-          type: ListActionTypes.itemsChange,
-          event: null,
-          items: [{ v: '1' }, { v: '2' }],
-          previousItems: [{ v: '0' }, { v: '1' }, { v: '2' }],
-          context: {
-            items: [{ v: '1' }, { v: '2' }],
-            itemComparer: (a, b) => a.v === b.v,
-            ...irrelevantConfig,
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.selectedValues.map((sv) => sv.v)).to.deep.equal(['2']);
-      });
-    });
-
-    describe('after the items are initialized', () => {
-      it('highlights the first item when using DOM focus management', () => {
-        const state: ListState<string> = {
-          highlightedValue: null,
-          selectedValues: [],
-        };
-
-        const action: ListReducerAction<string> = {
-          type: ListActionTypes.itemsChange,
-          event: null,
-          items: ['1', '2'],
-          previousItems: [],
-          context: {
-            ...irrelevantConfig,
-            items: ['1', '2'],
-            itemComparer: (o, v) => o === v,
-            focusManagement: 'DOM',
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.highlightedValue).to.equal('1');
-      });
-
-      it('highlights the first enabled item when using DOM focus management', () => {
-        const state: ListState<string> = {
-          highlightedValue: null,
-          selectedValues: [],
-        };
-
-        const action: ListReducerAction<string> = {
-          type: ListActionTypes.itemsChange,
-          event: null,
-          items: ['1', '2', '3'],
-          previousItems: [],
-          context: {
-            ...irrelevantConfig,
-            items: ['1', '2', '3'],
-            itemComparer: (o, v) => o === v,
-            focusManagement: 'DOM',
-            isItemDisabled: (item) => ['1', '2'].includes(item),
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.highlightedValue).to.equal('3');
-      });
-    });
-  });
-
-  describe('action: resetHighlight', () => {
-    it('highlights the first item', () => {
-      const state: ListState<string> = {
-        highlightedValue: 'three',
-        selectedValues: [],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.resetHighlight,
-        event: null,
-        context: {
-          items: ['one', 'two', 'three'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'DOM',
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'none',
-        },
-      };
-
-      const result = listReducer(state, action);
-      expect(result.highlightedValue).to.equal('one');
-    });
-
-    it('highlights the first non-disabled item', () => {
-      const state: ListState<string> = {
-        highlightedValue: 'three',
-        selectedValues: [],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.resetHighlight,
-        event: null,
-        context: {
-          items: ['one', 'two', 'three'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'DOM',
-          isItemDisabled: (item) => item === 'one',
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'none',
-        },
-      };
-
-      const result = listReducer(state, action);
-      expect(result.highlightedValue).to.equal('two');
-    });
-  });
-
-  describe('action: highlightLast', () => {
-    it('highlights the last item', () => {
-      const state: ListState<string> = {
-        highlightedValue: 'one',
-        selectedValues: [],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.highlightLast,
-        event: null,
-        context: {
-          items: ['one', 'two', 'three'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'DOM',
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'none',
-        },
-      };
-
-      const result = listReducer(state, action);
-      expect(result.highlightedValue).to.equal('three');
-    });
-
-    it('highlights the last non-disabled item', () => {
-      const state: ListState<string> = {
-        highlightedValue: 'one',
-        selectedValues: [],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.highlightLast,
-        event: null,
-        context: {
-          items: ['one', 'two', 'three'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'DOM',
-          isItemDisabled: (item) => item === 'three',
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'none',
-        },
-      };
-
-      const result = listReducer(state, action);
-      expect(result.highlightedValue).to.equal('two');
-    });
-  });
-
-  describe('action: clearSelection', () => {
-    it('clears the selection', () => {
-      const state: ListState<string> = {
-        highlightedValue: null,
-        selectedValues: ['one', 'two'],
-      };
-
-      const action: ListReducerAction<string> = {
-        type: ListActionTypes.clearSelection,
-        context: {
-          items: ['one', 'two', 'three'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'DOM',
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          getItemAsString: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionMode: 'none',
-        },
-      };
-
-      const result = listReducer(state, action);
-      expect(result.selectedValues).to.deep.equal([]);
-    });
-  });
-});
diff --git a/packages/react/src/useList/listReducer.ts b/packages/react/src/useList/listReducer.ts
deleted file mode 100644
index 975d692834..0000000000
--- a/packages/react/src/useList/listReducer.ts
+++ /dev/null
@@ -1,481 +0,0 @@
-import { ListActionTypes } from './listActions.types';
-import { ListState, ListReducerAction, ListActionContext, SelectionMode } from './useList.types';
-
-type ItemPredicate<ItemValue> = (item: ItemValue, index: number) => boolean;
-
-/**
- * Looks up the next valid item to highlight within the list.
- *
- * @param currentIndex The index of the start of the search.
- * @param lookupDirection Whether to look for the next or previous item.
- * @param items The array of items to search.
- * @param includeDisabledItems Whether to include disabled items in the search.
- * @param isItemDisabled A function that determines whether an item is disabled.
- * @param wrapAround Whether to wrap around the list when searching.
- * @returns The index of the next valid item to highlight or -1 if no valid item is found.
- */
-function findValidItemToHighlight<ItemValue>(
-  currentIndex: number,
-  lookupDirection: 'next' | 'previous',
-  items: ItemValue[],
-  includeDisabledItems: boolean,
-  isItemDisabled: ItemPredicate<ItemValue>,
-  wrapAround: boolean,
-): number {
-  if (
-    items.length === 0 ||
-    (!includeDisabledItems && items.every((item, itemIndex) => isItemDisabled(item, itemIndex)))
-  ) {
-    return -1;
-  }
-
-  let nextFocus = currentIndex;
-
-  for (;;) {
-    // No valid items found
-    if (
-      (!wrapAround && lookupDirection === 'next' && nextFocus === items.length) ||
-      (!wrapAround && lookupDirection === 'previous' && nextFocus === -1)
-    ) {
-      return -1;
-    }
-
-    const nextFocusDisabled = includeDisabledItems
-      ? false
-      : isItemDisabled(items[nextFocus], nextFocus);
-    if (nextFocusDisabled) {
-      nextFocus += lookupDirection === 'next' ? 1 : -1;
-      if (wrapAround) {
-        nextFocus = (nextFocus + items.length) % items.length;
-      }
-    } else {
-      return nextFocus;
-    }
-  }
-}
-
-/**
- * Gets the next item to highlight based on the current highlighted item and the search direction.
- *
- * @param previouslyHighlightedValue The item from which to start the search for the next candidate.
- * @param offset The offset from the previously highlighted item to search for the next candidate or a special named value ('reset', 'start', 'end').
- * @param context The list action context.
- *
- * @returns The next item to highlight or null if no item is valid.
- */
-export function moveHighlight<ItemValue>(
-  previouslyHighlightedValue: ItemValue | null,
-  offset: number | 'reset' | 'start' | 'end',
-  context: ListActionContext<ItemValue>,
-) {
-  const {
-    items,
-    isItemDisabled,
-    disableListWrap,
-    disabledItemsFocusable,
-    itemComparer,
-    focusManagement,
-  } = context;
-
-  // TODO: make this configurable
-  // The always should be an item highlighted when focus is managed by the DOM
-  // so that it's accessible by the `tab` key.
-  const defaultHighlightedIndex = focusManagement === 'DOM' ? 0 : -1;
-  const maxIndex = items.length - 1;
-
-  const previouslyHighlightedIndex =
-    previouslyHighlightedValue == null
-      ? -1
-      : items.findIndex((item) => itemComparer(item, previouslyHighlightedValue));
-
-  let nextIndexCandidate: number;
-  let lookupDirection: 'next' | 'previous';
-  let wrapAround = !disableListWrap;
-
-  switch (offset) {
-    case 'reset':
-      if (defaultHighlightedIndex === -1) {
-        return null;
-      }
-
-      nextIndexCandidate = 0;
-      lookupDirection = 'next';
-      wrapAround = false;
-      break;
-
-    case 'start':
-      nextIndexCandidate = 0;
-      lookupDirection = 'next';
-      wrapAround = false;
-      break;
-
-    case 'end':
-      nextIndexCandidate = maxIndex;
-      lookupDirection = 'previous';
-      wrapAround = false;
-      break;
-
-    default: {
-      const newIndex = previouslyHighlightedIndex + offset;
-
-      if (newIndex < 0) {
-        if ((!wrapAround && previouslyHighlightedIndex !== -1) || Math.abs(offset) > 1) {
-          nextIndexCandidate = 0;
-          lookupDirection = 'next';
-        } else {
-          nextIndexCandidate = maxIndex;
-          lookupDirection = 'previous';
-        }
-      } else if (newIndex > maxIndex) {
-        if (!wrapAround || Math.abs(offset) > 1) {
-          nextIndexCandidate = maxIndex;
-          lookupDirection = 'previous';
-        } else {
-          nextIndexCandidate = 0;
-          lookupDirection = 'next';
-        }
-      } else {
-        nextIndexCandidate = newIndex;
-        lookupDirection = offset >= 0 ? 'next' : 'previous';
-      }
-    }
-  }
-
-  const nextIndex = findValidItemToHighlight(
-    nextIndexCandidate,
-    lookupDirection,
-    items,
-    disabledItemsFocusable,
-    isItemDisabled,
-    wrapAround,
-  );
-
-  // If there are no valid items to highlight, return the previously highlighted item (if it's still valid).
-  if (
-    nextIndex === -1 &&
-    previouslyHighlightedValue !== null &&
-    !isItemDisabled(previouslyHighlightedValue, previouslyHighlightedIndex)
-  ) {
-    return previouslyHighlightedValue;
-  }
-
-  return items[nextIndex] ?? null;
-}
-
-/**
- * Toggles the selection of an item.
- *
- * @param item Item to toggle.
- * @param selectedValues Already selected items.
- * @param selectionMode The number of items that can be simultanously selected.
- * @param itemComparer A custom item comparer function.
- *
- * @returns The new array of selected items.
- */
-export function toggleSelection<ItemValue>(
-  item: ItemValue,
-  selectedValues: ItemValue[],
-  selectionMode: SelectionMode,
-  itemComparer: (item1: ItemValue, item2: ItemValue) => boolean,
-) {
-  if (selectionMode === 'none') {
-    return [];
-  }
-
-  if (selectionMode === 'single') {
-    // if the item to select has already been selected, return the original array
-    if (itemComparer(selectedValues[0], item)) {
-      return selectedValues;
-    }
-
-    return [item];
-  }
-
-  // The toggled item is selected; remove it from the selection.
-  if (selectedValues.some((sv) => itemComparer(sv, item))) {
-    return selectedValues.filter((sv) => !itemComparer(sv, item));
-  }
-
-  // The toggled item is not selected - add it to the selection.
-  return [...selectedValues, item];
-}
-
-/**
- * Handles item selection in a list.
- *
- * @param item - The item to be selected.
- * @param state - The current state of the list.
- * @param context - The context of the list action.
- * @returns The new state of the list after the item has been selected, or the original state if the item is disabled.
- */
-export function handleItemSelection<ItemValue, State extends ListState<ItemValue>>(
-  item: ItemValue,
-  state: State,
-  context: ListActionContext<ItemValue>,
-): State {
-  const { itemComparer, isItemDisabled, selectionMode, items } = context;
-  const { selectedValues } = state;
-
-  const itemIndex = items.findIndex((i) => itemComparer(item, i));
-
-  if (isItemDisabled(item, itemIndex)) {
-    return state;
-  }
-
-  // if the item is already selected, remove it from the selection, otherwise add it
-  const newSelectedValues = toggleSelection(item, selectedValues, selectionMode, itemComparer);
-
-  return {
-    ...state,
-    selectedValues: newSelectedValues,
-    highlightedValue: item,
-  };
-}
-
-function handleKeyDown<ItemValue, State extends ListState<ItemValue>>(
-  key: string,
-  state: State,
-  context: ListActionContext<ItemValue>,
-): State {
-  const previouslySelectedValue = state.highlightedValue;
-  const { orientation, pageSize } = context;
-
-  switch (key) {
-    case 'Home':
-      return {
-        ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, 'start', context),
-      };
-
-    case 'End':
-      return {
-        ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, 'end', context),
-      };
-
-    case 'PageUp':
-      return {
-        ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, -pageSize, context),
-      };
-
-    case 'PageDown':
-      return {
-        ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, pageSize, context),
-      };
-
-    case 'ArrowUp':
-      if (orientation !== 'vertical') {
-        break;
-      }
-
-      return {
-        ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, -1, context),
-      };
-
-    case 'ArrowDown':
-      if (orientation !== 'vertical') {
-        break;
-      }
-
-      return {
-        ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, 1, context),
-      };
-
-    case 'ArrowLeft': {
-      if (orientation === 'vertical') {
-        break;
-      }
-
-      const offset = orientation === 'horizontal-ltr' ? -1 : 1;
-
-      return {
-        ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, offset, context),
-      };
-    }
-
-    case 'ArrowRight': {
-      if (orientation === 'vertical') {
-        break;
-      }
-
-      const offset = orientation === 'horizontal-ltr' ? 1 : -1;
-
-      return {
-        ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, offset, context),
-      };
-    }
-
-    case 'Enter':
-    case ' ':
-      if (state.highlightedValue === null) {
-        return state;
-      }
-
-      return handleItemSelection(state.highlightedValue, state, context);
-
-    default:
-      break;
-  }
-
-  return state;
-}
-
-function handleBlur<ItemValue, State extends ListState<ItemValue>>(
-  state: State,
-  context: ListActionContext<ItemValue>,
-): State {
-  if (context.focusManagement === 'DOM') {
-    return state;
-  }
-
-  return {
-    ...state,
-    highlightedValue: null,
-  };
-}
-
-function textCriteriaMatches<ItemValue>(
-  nextFocus: ItemValue,
-  searchString: string,
-  stringifyItem: (item: ItemValue) => string | undefined,
-) {
-  const text = stringifyItem(nextFocus)?.trim().toLowerCase();
-
-  if (!text || text.length === 0) {
-    // Make item not navigable if stringification fails or results in empty string.
-    return false;
-  }
-
-  return text.indexOf(searchString) === 0;
-}
-
-function handleTextNavigation<ItemValue, State extends ListState<ItemValue>>(
-  state: State,
-  searchString: string,
-  context: ListActionContext<ItemValue>,
-): State {
-  const { items, isItemDisabled, disabledItemsFocusable, getItemAsString } = context;
-
-  const startWithCurrentItem = searchString.length > 1;
-
-  let nextItem = startWithCurrentItem
-    ? state.highlightedValue
-    : moveHighlight(state.highlightedValue, 1, context);
-
-  for (let index = 0; index < items.length; index += 1) {
-    // Return un-mutated state if looped back to the currently highlighted value
-    if (!nextItem || (!startWithCurrentItem && state.highlightedValue === nextItem)) {
-      return state;
-    }
-
-    if (
-      textCriteriaMatches(nextItem, searchString, getItemAsString) &&
-      (!isItemDisabled(nextItem, items.indexOf(nextItem)) || disabledItemsFocusable)
-    ) {
-      // The nextItem is the element to be highlighted
-      return {
-        ...state,
-        highlightedValue: nextItem,
-      };
-    }
-    // Move to the next element.
-    nextItem = moveHighlight(nextItem, 1, context);
-  }
-
-  // No item matches the text search criteria
-  return state;
-}
-
-function handleItemsChange<ItemValue, State extends ListState<ItemValue>>(
-  items: ItemValue[],
-  previousItems: ItemValue[],
-  state: State,
-  context: ListActionContext<ItemValue>,
-): State {
-  const { itemComparer, focusManagement } = context;
-
-  let newHighlightedValue: ItemValue | null = null;
-
-  if (state.highlightedValue != null) {
-    newHighlightedValue = items.find((item) => itemComparer(item, state.highlightedValue!)) ?? null;
-  } else if (focusManagement === 'DOM' && previousItems.length === 0) {
-    newHighlightedValue = moveHighlight(null, 'reset', context);
-  }
-
-  // exclude selected values that are no longer in the items list
-  const selectedValues = state.selectedValues ?? [];
-  const newSelectedValues = selectedValues.filter((selectedValue) =>
-    items.some((item) => itemComparer(item, selectedValue)),
-  );
-
-  return {
-    ...state,
-    highlightedValue: newHighlightedValue,
-    selectedValues: newSelectedValues,
-  };
-}
-
-function handleResetHighlight<ItemValue, State extends ListState<ItemValue>>(
-  state: State,
-  context: ListActionContext<ItemValue>,
-) {
-  return {
-    ...state,
-    highlightedValue: moveHighlight(null, 'reset', context),
-  };
-}
-
-function handleHighlightLast<ItemValue, State extends ListState<ItemValue>>(
-  state: State,
-  context: ListActionContext<ItemValue>,
-) {
-  return {
-    ...state,
-    highlightedValue: moveHighlight(null, 'end', context),
-  };
-}
-
-function handleClearSelection<ItemValue, State extends ListState<ItemValue>>(
-  state: State,
-  context: ListActionContext<ItemValue>,
-) {
-  return {
-    ...state,
-    selectedValues: [],
-    highlightedValue: moveHighlight(null, 'reset', context),
-  };
-}
-
-export function listReducer<ItemValue, State extends ListState<ItemValue>>(
-  state: State,
-  action: ListReducerAction<ItemValue> & { context: ListActionContext<ItemValue> },
-): State {
-  const { type, context } = action;
-
-  switch (type) {
-    case ListActionTypes.keyDown:
-      return handleKeyDown(action.key, state, context);
-    case ListActionTypes.itemClick:
-      return handleItemSelection(action.item, state, context);
-    case ListActionTypes.blur:
-      return handleBlur(state, context);
-    case ListActionTypes.textNavigation:
-      return handleTextNavigation(state, action.searchString, context);
-    case ListActionTypes.itemsChange:
-      return handleItemsChange(action.items, action.previousItems, state, context);
-    case ListActionTypes.resetHighlight:
-      return handleResetHighlight(state, context);
-    case ListActionTypes.highlightLast:
-      return handleHighlightLast(state, context);
-    case ListActionTypes.clearSelection:
-      return handleClearSelection(state, context);
-    default:
-      return state;
-  }
-}
diff --git a/packages/react/src/useList/useList.test.tsx b/packages/react/src/useList/useList.test.tsx
deleted file mode 100644
index ca25e9101b..0000000000
--- a/packages/react/src/useList/useList.test.tsx
+++ /dev/null
@@ -1,116 +0,0 @@
-import * as React from 'react';
-import { expect } from 'chai';
-import { SinonSpy, spy } from 'sinon';
-import { createRenderer, createEvent, fireEvent } from '@mui/internal-test-utils';
-import { useList } from './useList';
-
-describe('useList', () => {
-  const { render } = createRenderer();
-
-  describe('preventing default behavior on keyDown', () => {
-    ['ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown', 'Enter', ' '].forEach((key) =>
-      it(`prevents default behavior when ${key} is pressed in activeDescendant focus management mode`, () => {
-        function Listbox() {
-          const { getRootProps } = useList({
-            items: [],
-            focusManagement: 'activeDescendant',
-            getItemId: () => undefined,
-          });
-          return <div role="listbox" {...getRootProps()} />;
-        }
-
-        const { getByRole } = render(<Listbox />);
-        const listbox = getByRole('listbox');
-        listbox.focus();
-
-        const event = createEvent.keyDown(listbox, {
-          key,
-        });
-
-        event.preventDefault = spy();
-        fireEvent(listbox, event);
-
-        expect((event.preventDefault as SinonSpy).calledOnce).to.equal(true);
-      }),
-    );
-
-    ['ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown'].forEach((key) =>
-      it(`prevents default behavior when ${key} is pressed in DOM focus management mode`, () => {
-        function Listbox() {
-          const { getRootProps } = useList({
-            items: [],
-            focusManagement: 'DOM',
-            getItemDomElement: () => null,
-          });
-          return <div role="listbox" {...getRootProps()} />;
-        }
-
-        const { getByRole } = render(<Listbox />);
-        const listbox = getByRole('listbox');
-        listbox.focus();
-
-        const event = createEvent.keyDown(listbox, {
-          key,
-        });
-
-        event.preventDefault = spy();
-        fireEvent(listbox, event);
-
-        expect((event.preventDefault as SinonSpy).calledOnce).to.equal(true);
-      }),
-    );
-
-    ['Enter', ' '].forEach((key) =>
-      it(`does not prevent default behavior when ${key} is pressed in DOM focus management mode`, () => {
-        function Listbox() {
-          const { getRootProps } = useList({
-            items: [],
-            focusManagement: 'DOM',
-            getItemDomElement: () => null,
-          });
-          return <div role="listbox" {...getRootProps()} />;
-        }
-
-        const { getByRole } = render(<Listbox />);
-        const listbox = getByRole('listbox');
-        listbox.focus();
-
-        const event = createEvent.keyDown(listbox, {
-          key,
-        });
-
-        event.preventDefault = spy();
-        fireEvent(listbox, event);
-
-        expect((event.preventDefault as SinonSpy).notCalled).to.equal(true);
-      }),
-    );
-  });
-
-  describe('external props', () => {
-    it('should pass arbitrary props to the root slot', () => {
-      const handleClick = spy();
-
-      function Listbox() {
-        const { getRootProps } = useList({
-          items: [],
-          getItemId: () => undefined,
-        });
-        return (
-          <div
-            role="listbox"
-            {...getRootProps({ 'data-testid': 'test-listbox', onClick: handleClick })}
-          />
-        );
-      }
-
-      const { getByRole } = render(<Listbox />);
-
-      const listbox = getByRole('listbox');
-      expect(listbox).to.have.attribute('data-testid', 'test-listbox');
-
-      fireEvent.click(listbox);
-      expect(handleClick.callCount).to.equal(1);
-    });
-  });
-});
diff --git a/packages/react/src/useList/useList.ts b/packages/react/src/useList/useList.ts
deleted file mode 100644
index 92f922e3c0..0000000000
--- a/packages/react/src/useList/useList.ts
+++ /dev/null
@@ -1,373 +0,0 @@
-'use client';
-import * as React from 'react';
-import { unstable_useForkRef as useForkRef } from '@mui/utils';
-import {
-  UseListParameters,
-  ListItemState,
-  UseListRootSlotProps,
-  ListState,
-  ListActionContext,
-  UseListReturnValue,
-} from './useList.types';
-import { ListActionTypes, ListAction } from './listActions.types';
-import { ListContextValue } from './ListContext';
-import { listReducer as defaultReducer } from './listReducer';
-
-import { useControllableReducer } from '../utils/useControllableReducer';
-import {
-  ControllableReducerAction,
-  StateChangeCallback,
-  StateComparers,
-} from '../utils/useControllableReducer.types';
-import { areArraysEqual } from '../utils/areArraysEqual';
-import { useTextNavigation } from '../utils/useTextNavigation';
-import { MuiCancellableEvent } from '../utils/MuiCancellableEvent';
-import { extractEventHandlers } from '../utils/extractEventHandlers';
-import { EventHandlers } from '../utils/types';
-
-const EMPTY_OBJECT = {};
-const NOOP = () => {};
-
-const defaultItemComparer = <ItemValue>(optionA: ItemValue, optionB: ItemValue) =>
-  optionA === optionB;
-
-const defaultIsItemDisabled = () => false;
-
-const defaultItemStringifier = <ItemValue>(item: ItemValue) =>
-  typeof item === 'string' ? item : String(item);
-
-const defaultGetInitialState = () => ({
-  highlightedValue: null,
-  selectedValues: [],
-});
-
-/**
- * The useList is a lower-level utility that is used to build list-like components.
- * It's used to manage the state of the list and its items.
- *
- * Supports highlighting a single item and selecting an arbitrary number of items.
- *
- * The state of the list is managed by a controllable reducer - that is a reducer that can have its state
- * controlled from outside.
- *
- * By default, the state consists of `selectedValues` and `highlightedValue` but can be extended by the caller of the hook.
- * Also the actions that can be dispatched and the reducer function can be defined externally.
- *
- * @template ItemValue The type of the item values.
- * @template State The type of the list state. This should be a subtype of `ListState<ItemValue>`.
- * @template CustomAction The type of the actions that can be dispatched (besides the standard ListAction).
- * @template CustomActionContext The shape of additional properties that will be added to actions when dispatched.
- *
- * @ignore - internal hook.
- */
-function useList<
-  ItemValue,
-  State extends ListState<ItemValue> = ListState<ItemValue>,
-  CustomAction extends ControllableReducerAction = never,
-  CustomActionContext = {},
->(
-  params: UseListParameters<ItemValue, State, CustomAction, CustomActionContext>,
-): UseListReturnValue<ItemValue, State, CustomAction> {
-  const {
-    controlledProps = EMPTY_OBJECT,
-    disabledItemsFocusable = false,
-    disableListWrap = false,
-    focusManagement = 'activeDescendant',
-    getInitialState = defaultGetInitialState,
-    getItemDomElement,
-    getItemId,
-    isItemDisabled = defaultIsItemDisabled,
-    rootRef: externalListRef,
-    onStateChange = NOOP,
-    items,
-    itemComparer = defaultItemComparer,
-    getItemAsString = defaultItemStringifier,
-    onChange,
-    onHighlightChange,
-    onItemsChange,
-    orientation = 'vertical',
-    pageSize = 5,
-    reducerActionContext = EMPTY_OBJECT as CustomActionContext,
-    selectionMode = 'single',
-    stateReducer: externalReducer,
-    componentName = 'useList',
-  } = params;
-
-  if (process.env.NODE_ENV !== 'production') {
-    if (focusManagement === 'DOM' && getItemDomElement == null) {
-      throw new Error(
-        'useList: The `getItemDomElement` prop is required when using the `DOM` focus management.',
-      );
-    }
-
-    if (focusManagement === 'activeDescendant' && getItemId == null) {
-      throw new Error(
-        'useList: The `getItemId` prop is required when using the `activeDescendant` focus management.',
-      );
-    }
-  }
-
-  const listRef = React.useRef<HTMLUListElement>(null);
-  const handleRef = useForkRef(externalListRef, listRef);
-
-  const handleHighlightChange = React.useCallback(
-    (
-      event: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
-      value: ItemValue | null,
-      reason: string,
-    ) => {
-      onHighlightChange?.(event, value, reason);
-
-      if (
-        focusManagement === 'DOM' &&
-        value != null &&
-        (reason === ListActionTypes.itemClick ||
-          reason === ListActionTypes.keyDown ||
-          reason === ListActionTypes.textNavigation)
-      ) {
-        getItemDomElement?.(value)?.focus();
-      }
-    },
-    [getItemDomElement, onHighlightChange, focusManagement],
-  );
-
-  const stateComparers = React.useMemo(
-    () =>
-      ({
-        highlightedValue: itemComparer,
-        selectedValues: (valuesArray1, valuesArray2) =>
-          areArraysEqual(valuesArray1, valuesArray2, itemComparer),
-      }) as StateComparers<State>,
-    [itemComparer],
-  );
-
-  // This gets called whenever a reducer changes the state.
-  const handleStateChange: StateChangeCallback<State> = React.useCallback(
-    (event, field, value, reason, state) => {
-      onStateChange?.(event, field, value, reason, state);
-
-      switch (field) {
-        case 'highlightedValue':
-          handleHighlightChange(
-            event as React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
-            value as ItemValue | null,
-            reason,
-          );
-          break;
-        case 'selectedValues':
-          onChange?.(
-            event as React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
-            value as ItemValue[],
-            reason,
-          );
-          break;
-        default:
-          break;
-      }
-    },
-    [handleHighlightChange, onChange, onStateChange],
-  );
-
-  // The following object is added to each action when it's dispatched.
-  // It's accessible in the reducer via the `action.context` field.
-  const listActionContext: ListActionContext<ItemValue> = React.useMemo(() => {
-    return {
-      disabledItemsFocusable,
-      disableListWrap,
-      focusManagement,
-      isItemDisabled,
-      itemComparer,
-      items,
-      getItemAsString,
-      onHighlightChange: handleHighlightChange,
-      orientation,
-      pageSize,
-      selectionMode,
-      stateComparers,
-    };
-  }, [
-    disabledItemsFocusable,
-    disableListWrap,
-    focusManagement,
-    isItemDisabled,
-    itemComparer,
-    items,
-    getItemAsString,
-    handleHighlightChange,
-    orientation,
-    pageSize,
-    selectionMode,
-    stateComparers,
-  ]);
-
-  const initialState = getInitialState();
-  const reducer = (externalReducer ?? defaultReducer) as React.Reducer<
-    State,
-    ListAction<ItemValue> | CustomAction
-  >;
-
-  const actionContext: ListActionContext<ItemValue> & CustomActionContext = React.useMemo(
-    () => ({ ...reducerActionContext, ...listActionContext }),
-    [reducerActionContext, listActionContext],
-  );
-
-  const [state, dispatch] = useControllableReducer<
-    State,
-    ListAction<ItemValue> | CustomAction,
-    ListActionContext<ItemValue> & CustomActionContext
-  >({
-    reducer,
-    actionContext,
-    initialState: initialState as State,
-    controlledProps,
-    stateComparers,
-    onStateChange: handleStateChange,
-    componentName,
-  });
-
-  const { highlightedValue, selectedValues } = state;
-
-  const handleTextNavigation = useTextNavigation((searchString, event) =>
-    dispatch({
-      type: ListActionTypes.textNavigation,
-      event,
-      searchString,
-    }),
-  );
-
-  const previousItems = React.useRef<ItemValue[]>([]);
-
-  React.useEffect(() => {
-    // Whenever the `items` object changes, we need to determine if the actual items changed.
-    // If they did, we need to dispatch an `itemsChange` action, so the selected/highlighted state is updated.
-    if (areArraysEqual(previousItems.current, items, itemComparer)) {
-      return;
-    }
-
-    dispatch({
-      type: ListActionTypes.itemsChange,
-      event: null,
-      items,
-      previousItems: previousItems.current,
-    });
-
-    previousItems.current = items;
-    onItemsChange?.(items);
-  }, [items, itemComparer, dispatch, onItemsChange]);
-
-  const createHandleKeyDown =
-    (externalHandlers: EventHandlers) =>
-    (event: React.KeyboardEvent<HTMLElement> & MuiCancellableEvent) => {
-      externalHandlers.onKeyDown?.(event);
-
-      if (event.defaultMuiPrevented) {
-        return;
-      }
-
-      const keysToPreventDefault = ['Home', 'End', 'PageUp', 'PageDown'];
-
-      if (orientation === 'vertical') {
-        keysToPreventDefault.push('ArrowUp', 'ArrowDown');
-      } else {
-        keysToPreventDefault.push('ArrowLeft', 'ArrowRight');
-      }
-
-      if (focusManagement === 'activeDescendant') {
-        // When the child element is focused using the activeDescendant attribute,
-        // the list handles keyboard events on its behalf.
-        // We have to `preventDefault()` is this case to prevent the browser from
-        // scrolling the view when space is pressed or submitting forms when enter is pressed.
-        keysToPreventDefault.push(' ', 'Enter');
-      }
-
-      if (keysToPreventDefault.includes(event.key)) {
-        event.preventDefault();
-      }
-
-      dispatch({
-        type: ListActionTypes.keyDown,
-        key: event.key,
-        event,
-      });
-
-      handleTextNavigation(event);
-    };
-
-  const createHandleBlur =
-    (externalHandlers: EventHandlers) =>
-    (event: React.FocusEvent<HTMLElement> & MuiCancellableEvent) => {
-      externalHandlers.onBlur?.(event);
-
-      if (event.defaultMuiPrevented) {
-        return;
-      }
-
-      if (listRef.current?.contains(event.relatedTarget)) {
-        // focus remains within the list
-        return;
-      }
-
-      dispatch({
-        type: ListActionTypes.blur,
-        event,
-      });
-    };
-
-  const getRootProps = <ExternalProps extends Record<string, any> = {}>(
-    externalProps: ExternalProps = {} as ExternalProps,
-  ): UseListRootSlotProps<ExternalProps> => {
-    const externalEventHandlers = extractEventHandlers(externalProps);
-    return {
-      ...externalProps,
-      'aria-activedescendant':
-        focusManagement === 'activeDescendant' && highlightedValue != null
-          ? getItemId!(highlightedValue)
-          : undefined,
-      tabIndex: focusManagement === 'DOM' ? -1 : 0,
-      ref: handleRef,
-      ...externalEventHandlers,
-      onBlur: createHandleBlur(externalEventHandlers),
-      onKeyDown: createHandleKeyDown(externalEventHandlers),
-    };
-  };
-
-  const getItemState = React.useCallback(
-    (item: ItemValue): ListItemState => {
-      const selected = (selectedValues ?? []).some(
-        (value) => value != null && itemComparer(item, value),
-      );
-
-      const highlighted = highlightedValue != null && itemComparer(item, highlightedValue);
-      const focusable = focusManagement === 'DOM';
-
-      return {
-        focusable,
-        highlighted,
-        selected,
-      };
-    },
-    [itemComparer, selectedValues, highlightedValue, focusManagement],
-  );
-
-  const contextValue: ListContextValue<ItemValue> = React.useMemo(
-    () => ({
-      dispatch,
-      getItemState,
-    }),
-    [dispatch, getItemState],
-  );
-
-  React.useDebugValue({
-    state,
-  });
-
-  return {
-    contextValue,
-    dispatch,
-    getRootProps,
-    rootRef: handleRef,
-    state,
-  };
-}
-
-export { useList };
diff --git a/packages/react/src/useList/useList.types.ts b/packages/react/src/useList/useList.types.ts
deleted file mode 100644
index 33c12b4386..0000000000
--- a/packages/react/src/useList/useList.types.ts
+++ /dev/null
@@ -1,268 +0,0 @@
-import * as React from 'react';
-import { Simplify } from '@mui/types';
-import { ListAction } from './listActions.types';
-import {
-  ActionWithContext,
-  ControllableReducerAction,
-  StateChangeCallback,
-} from '../utils/useControllableReducer.types';
-import type { ListContextValue } from './ListContext';
-import { MuiCancellableEventHandler } from '../utils/MuiCancellableEvent';
-
-type ListActionContextRequiredKeys =
-  | 'disabledItemsFocusable'
-  | 'disableListWrap'
-  | 'focusManagement'
-  | 'getItemAsString'
-  | 'isItemDisabled'
-  | 'itemComparer'
-  | 'items'
-  | 'orientation'
-  | 'pageSize'
-  | 'selectionMode';
-
-/**
- * The subset of `UseListParameters` that is passed to the list reducer actions.
- */
-export type ListActionContext<ItemValue> = Simplify<
-  Required<Pick<UseListParameters<ItemValue, any, any>, ListActionContextRequiredKeys>>
->;
-
-/**
- * The action object augmented with the action context ({@linkcode ListActionContext} instance).
- * Instances of this type are passed to the reducer.
- *
- * @template ItemValue The type of the item values.
- * @template CustomActionContext The shape of additional properties that will be added to actions when dispatched.
- */
-export type ListReducerAction<ItemValue, CustomActionContext = {}> = ActionWithContext<
-  ListAction<ItemValue>,
-  ListActionContext<ItemValue> & CustomActionContext
->;
-
-/**
- * The state of the list.
- * Modifications to this state should be done via the reducer.
- */
-export interface ListState<ItemValue> {
-  /**
-   * The item that is currently highlighted.
-   */
-  highlightedValue: ItemValue | null;
-  /**
-   * The item(s) that are currently selected.
-   */
-  selectedValues: ItemValue[];
-}
-
-/**
- * Type of the reducer that operates on the list state.
- *
- * @template ItemValue The type of the item values.
- * @template State The type of the list state. This should be a subtype of ListState<ItemValue>.
- * @template CustomActionContext The shape of additional properties that will be added to actions when dispatched.
- */
-export type ListReducer<ItemValue, State extends ListState<ItemValue>, CustomActionContext> = (
-  state: State,
-  action: ListReducerAction<ItemValue, CustomActionContext>,
-) => State;
-
-export type FocusManagementType = 'DOM' | 'activeDescendant';
-
-export type SelectionMode = 'none' | 'single' | 'multiple';
-
-/**
- * Parameters of the useList hook.
- *
- * @template ItemValue The type of the item values.
- * @template State The type of the list state. This should be a subtype of `ListState<ItemValue>`.
- * @template CustomAction The type of the actions that can be dispatched (besides the standard ListAction).
- * @template CustomActionContext The shape of additional properties that will be added to actions when dispatched.
- */
-export interface UseListParameters<
-  ItemValue,
-  State extends ListState<ItemValue> = ListState<ItemValue>,
-  CustomAction extends ControllableReducerAction = never,
-  CustomActionContext = {},
-> {
-  /**
-   * The externally controlled values (highlighted and selected item(s)) of the list.
-   * If a custom state is used, this object can contain the added state fields as well.
-   *
-   * @default {}
-   */
-  controlledProps?: Partial<State>;
-  /**
-   * If `true`, it will be possible to highlight disabled items.
-   * @default false
-   */
-  disabledItemsFocusable?: boolean;
-  /**
-   * If `true`, the highlight will not wrap around the list if arrow keys are used.
-   * @default false
-   */
-  disableListWrap?: boolean;
-  /**
-   * The focus management strategy used by the list.
-   * Controls the attributes used to set focus on the list items.
-   * @default 'activeDescendant'
-   */
-  focusManagement?: FocusManagementType;
-  /**
-   * A function that returns the DOM element associated with an item.
-   * This is required when using the `DOM` focus management.
-   *
-   * @param item List item to get the DOM element for.
-   */
-  getItemDomElement?: (itemValue: ItemValue) => HTMLElement | null;
-  /**
-   * A function that returns the id of an item.
-   * This is required when using the `activeDescendant` focus management.
-   *
-   * @param itemValue List item to get the id for.
-   */
-  getItemId?: (itemValue: ItemValue) => string | undefined;
-  /**
-   * A function that intializes the state of the list.
-   * It is required when using a custom state with mandatory fields.
-   * If not provided, the state will be initialized with the default values (nothing highlighted or selected).
-   *
-   * @returns The initial state of the list.
-   */
-  getInitialState?: () => State;
-  /**
-   * A function that determines if a particular item is disabled.
-   * @default () => false
-   */
-  isItemDisabled?: (itemValue: ItemValue, index: number) => boolean;
-  /**
-   * Ref to the list root DOM element.
-   */
-  rootRef?: React.Ref<Element>;
-  /**
-   * Callback fired when the selected value changes.
-   * This is a strongly typed convenience event that can be used instead of `onStateChange`.
-   */
-  onChange?: (
-    event: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
-    value: ItemValue[],
-    reason: string,
-  ) => void;
-  /**
-   * Callback fired when the highlighted option changes.
-   * This is a strongly typed convenience event that can be used instead of `onStateChange`.
-   */
-  onHighlightChange?: (
-    event: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
-    option: ItemValue | null,
-    reason: string,
-  ) => void;
-  /**
-   * Callback fired when the items change.
-   *
-   * @param items The new items collection
-   */
-  onItemsChange?: (items: ItemValue[]) => void;
-  /**
-   * Callback fired when the any of the state items change.
-   * Note that in case of `selectedValues` and `highlightedValue` the strongly typed
-   * `onChange` and `onHighlightChange` callbacks are also fired.
-   */
-  onStateChange?: StateChangeCallback<State>;
-  /**
-   * The number of items skip when using the page up and page down keys.
-   *
-   * @default 5
-   */
-  pageSize?: number;
-  /**
-   * A function that tests equality between two items' values.
-   * @default (a, b) => a === b
-   */
-  itemComparer?: (itemValue1: ItemValue, itemValue2: ItemValue) => boolean;
-  /**
-   * A function that converts an object to its string representation
-   * @default (o) => o
-   */
-  getItemAsString?: (option: ItemValue) => string | undefined;
-  /**
-   * Array of list items.
-   */
-  items: ItemValue[];
-  /**
-   * Additional data to be passed to all the reducer actions.
-   * It will be available in the `context` property of the action when dispatched.
-   */
-  reducerActionContext?: CustomActionContext;
-  /**
-   * Orientation of the items in the list.
-   * Determines the actions that are performed when arrow keys are pressed.
-   */
-  orientation?: 'horizontal-ltr' | 'horizontal-rtl' | 'vertical';
-  /**
-   * Controls how many items can be selected at once: none (the selection functionality is disabled in this case), one, or indefinitely many.
-   * @default 'single'
-   */
-  selectionMode?: SelectionMode;
-  /**
-   * Custom state reducer function. It calculates the new state (highlighted and selected items + optional custom state)
-   * based on the previous one and the performed action.
-   */
-  stateReducer?: (
-    state: State,
-    action: ActionWithContext<
-      ListAction<ItemValue> | CustomAction,
-      ListActionContext<ItemValue> & CustomActionContext
-    >,
-  ) => State;
-  /**
-   * The name of the component using useList.
-   * For debugging purposes.
-   * @default 'useList'
-   */
-  componentName?: string;
-}
-
-export interface ListItemState {
-  /**
-   * Determines if the item is focusable (its focus is managed by the DOM).
-   */
-  focusable: boolean;
-  /**
-   * If `true` the item is highlighted.
-   */
-  highlighted: boolean;
-  /**
-   * If `true` the item is selected.
-   */
-  selected: boolean;
-}
-
-interface UseListRootSlotOwnProps {
-  'aria-activedescendant'?: React.AriaAttributes['aria-activedescendant'];
-  onBlur: MuiCancellableEventHandler<React.FocusEvent<HTMLElement>>;
-  onKeyDown: MuiCancellableEventHandler<React.KeyboardEvent<HTMLElement>>;
-  tabIndex: number;
-  ref: React.RefCallback<Element> | null;
-}
-
-export type UseListRootSlotProps<ExternalProps = {}> = ExternalProps & UseListRootSlotOwnProps;
-
-export interface UseListReturnValue<
-  ItemValue,
-  State extends ListState<ItemValue>,
-  CustomAction extends ControllableReducerAction,
-> {
-  contextValue: ListContextValue<ItemValue>;
-  dispatch: (action: CustomAction | ListAction<ItemValue>) => void;
-  /**
-   * Resolver for the root slot's props.
-   * @param externalProps additional props for the root slot
-   * @returns props that should be spread on the root slot
-   */
-  getRootProps: <ExternalProps extends Record<string, unknown> = {}>(
-    externalProps?: ExternalProps,
-  ) => UseListRootSlotProps<ExternalProps>;
-  rootRef: React.RefCallback<Element> | null;
-  state: State;
-}
diff --git a/packages/react/src/useList/useListItem.ts b/packages/react/src/useList/useListItem.ts
deleted file mode 100644
index 9999748450..0000000000
--- a/packages/react/src/useList/useListItem.ts
+++ /dev/null
@@ -1,108 +0,0 @@
-'use client';
-import * as React from 'react';
-import { extractEventHandlers } from '../utils/extractEventHandlers';
-import { EventHandlers } from '../utils/types';
-import { UseListItemParameters, UseListItemReturnValue } from './useListItem.types';
-import { ListActionTypes } from './listActions.types';
-import { ListContext } from './ListContext';
-
-/**
- * Contains the logic for an item of a list-like component (for example Select, Menu, etc.).
- * It handles the item's mouse events and tab index.
- *
- * @template ItemValue The type of the item's value. This should be consistent with the type of useList's `items` parameter.
- * @ignore - internal hook.
- */
-export function useListItem<ItemValue>(
-  parameters: UseListItemParameters<ItemValue>,
-): UseListItemReturnValue {
-  const { handlePointerOverEvents = false, item } = parameters;
-
-  const listContext = React.useContext(ListContext);
-  if (!listContext) {
-    throw new Error('useListItem must be used within a ListProvider');
-  }
-
-  const { dispatch, getItemState } = listContext;
-
-  const { highlighted, selected, focusable } = getItemState(item);
-
-  const createHandleClick = React.useCallback(
-    (externalHandlers: EventHandlers) => (event: React.MouseEvent) => {
-      externalHandlers.onClick?.(event);
-      if (event.defaultPrevented) {
-        return;
-      }
-
-      if (process.env.NODE_ENV !== 'production') {
-        if (item === undefined) {
-          throw new Error(
-            [
-              'MUI: The `item` provided to useListItem() is undefined.',
-              'This should happen only during server-side rendering under React 17.',
-            ].join('\n'),
-          );
-        }
-      }
-
-      dispatch({
-        type: ListActionTypes.itemClick,
-        item: item!,
-        event,
-      });
-    },
-    [dispatch, item],
-  );
-
-  const createHandlePointerOver = React.useCallback(
-    (externalHandlers: EventHandlers) => (event: React.PointerEvent) => {
-      externalHandlers.onMouseOver?.(event);
-      if (event.defaultPrevented) {
-        return;
-      }
-
-      if (process.env.NODE_ENV !== 'production') {
-        if (item === undefined) {
-          throw new Error(
-            [
-              'MUI: The `item` provided to useListItem() is undefined.',
-              'This should happen only during server-side rendering under React 17.',
-            ].join('\n'),
-          );
-        }
-      }
-
-      dispatch({
-        type: ListActionTypes.itemHover,
-        item: item!,
-        event,
-      });
-    },
-    [dispatch, item],
-  );
-
-  let tabIndex: number | undefined;
-  if (focusable) {
-    tabIndex = highlighted ? 0 : -1;
-  }
-
-  const getRootProps = <ExternalProps extends Record<string, any>>(
-    externalProps: ExternalProps = {} as ExternalProps,
-  ) => {
-    const externalEventHandlers = extractEventHandlers(externalProps);
-    return {
-      ...externalProps,
-      onClick: createHandleClick(externalEventHandlers),
-      onPointerOver: handlePointerOverEvents
-        ? createHandlePointerOver(externalEventHandlers)
-        : undefined,
-      tabIndex,
-    };
-  };
-
-  return {
-    getRootProps,
-    highlighted,
-    selected,
-  };
-}
diff --git a/packages/react/src/useList/useListItem.types.ts b/packages/react/src/useList/useListItem.types.ts
deleted file mode 100644
index 965df87f8d..0000000000
--- a/packages/react/src/useList/useListItem.types.ts
+++ /dev/null
@@ -1,42 +0,0 @@
-export interface UseListItemParameters<ItemValue> {
-  /**
-   * If `true`, the list item will dispatch the `itemHover` action on pointer over.
-   * Since the use cases for it are rare, it's disabled by default.
-   * It could be used to mimic the native `select` behavior, which highlights the hovered item.
-   *
-   * @default false
-   */
-  handlePointerOverEvents?: boolean;
-  /**
-   * The list item.
-   */
-  item: ItemValue;
-}
-
-interface UseListItemRootSlotOwnProps {
-  onClick: React.MouseEventHandler;
-  onPointerOver: React.PointerEventHandler | undefined;
-  tabIndex?: number;
-}
-
-export type UseListItemRootSlotProps<ExternalProps = {}> = ExternalProps &
-  UseListItemRootSlotOwnProps;
-
-export interface UseListItemReturnValue {
-  /**
-   * Resolver for the root slot's props.
-   * @param externalProps additional props to be forwarded to the root slot
-   * @returns props that should be spread on the root slot
-   */
-  getRootProps: <ExternalProps extends Record<string, unknown> = {}>(
-    externalProps?: ExternalProps,
-  ) => UseListItemRootSlotProps<ExternalProps>;
-  /**
-   * If `true`, the current item is highlighted.
-   */
-  highlighted: boolean;
-  /**
-   * If `true`, the current item is selected.
-   */
-  selected: boolean;
-}

From ab269fdb913041614013cb20f69d57635f801e31 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Fri, 22 Nov 2024 21:09:33 +0800
Subject: [PATCH 20/20] Rename active to highlighted internally in Composite

---
 .../src/Composite/Item/CompositeItem.tsx      |  6 +--
 .../src/Composite/Item/useCompositeItem.ts    | 10 ++--
 .../src/Composite/Root/CompositeRoot.test.tsx |  7 ++-
 .../src/Composite/Root/CompositeRoot.tsx      | 47 ++++++++++---------
 .../Composite/Root/CompositeRootContext.ts    |  4 +-
 .../src/Composite/Root/useCompositeRoot.ts    | 39 ++++++++-------
 packages/react/src/Tabs/Tab/Tab.test.tsx      |  4 +-
 packages/react/src/Tabs/TabsList/TabsList.tsx |  4 +-
 8 files changed, 65 insertions(+), 56 deletions(-)

diff --git a/packages/react/src/Composite/Item/CompositeItem.tsx b/packages/react/src/Composite/Item/CompositeItem.tsx
index 2d298b1768..e26c24b27e 100644
--- a/packages/react/src/Composite/Item/CompositeItem.tsx
+++ b/packages/react/src/Composite/Item/CompositeItem.tsx
@@ -14,14 +14,14 @@ import type { BaseUIComponentProps } from '../../utils/types';
 function CompositeItem<Metadata>(props: CompositeItem.Props<Metadata>) {
   const { render, className, itemRef, metadata, ...otherProps } = props;
 
-  const { activeIndex } = useCompositeRootContext();
+  const { highlightedIndex } = useCompositeRootContext();
   const { getItemProps, ref, index } = useCompositeItem({ metadata });
 
   const ownerState: CompositeItem.OwnerState = React.useMemo(
     () => ({
-      highlighted: index === activeIndex,
+      highlighted: index === highlightedIndex,
     }),
-    [index, activeIndex],
+    [index, highlightedIndex],
   );
 
   const mergedRef = useForkRef(itemRef, ref);
diff --git a/packages/react/src/Composite/Item/useCompositeItem.ts b/packages/react/src/Composite/Item/useCompositeItem.ts
index acc082a6db..f182eb157b 100644
--- a/packages/react/src/Composite/Item/useCompositeItem.ts
+++ b/packages/react/src/Composite/Item/useCompositeItem.ts
@@ -15,19 +15,19 @@ export interface UseCompositeItemParameters<Metadata> {
  * - [useCompositeItem API](https://mui.com/base-ui/api/use-composite-item/)
  */
 export function useCompositeItem<Metadata>(params: UseCompositeItemParameters<Metadata> = {}) {
-  const { activeIndex, onActiveIndexChange } = useCompositeRootContext();
+  const { highlightedIndex, onHighlightedIndexChange } = useCompositeRootContext();
   const { ref, index } = useCompositeListItem(params);
-  const isActive = activeIndex === index;
+  const isHighlighted = highlightedIndex === index;
 
   const getItemProps = React.useCallback(
     (externalProps = {}) =>
       mergeReactProps<'div'>(externalProps, {
-        tabIndex: isActive ? 0 : -1,
+        tabIndex: isHighlighted ? 0 : -1,
         onFocus() {
-          onActiveIndexChange(index);
+          onHighlightedIndexChange(index);
         },
       }),
-    [isActive, index, onActiveIndexChange],
+    [isHighlighted, index, onHighlightedIndexChange],
   );
 
   return React.useMemo(
diff --git a/packages/react/src/Composite/Root/CompositeRoot.test.tsx b/packages/react/src/Composite/Root/CompositeRoot.test.tsx
index 85a4da1ae9..98b7d4523e 100644
--- a/packages/react/src/Composite/Root/CompositeRoot.test.tsx
+++ b/packages/react/src/Composite/Root/CompositeRoot.test.tsx
@@ -18,9 +18,12 @@ describe('Composite', () => {
   describe('list', () => {
     it('controlled mode', async () => {
       function App() {
-        const [activeIndex, setActiveIndex] = React.useState(0);
+        const [highlightedIndex, setHighlightedIndex] = React.useState(0);
         return (
-          <CompositeRoot activeIndex={activeIndex} onActiveIndexChange={setActiveIndex}>
+          <CompositeRoot
+            highlightedIndex={highlightedIndex}
+            onHighlightedIndexChange={setHighlightedIndex}
+          >
             <CompositeItem data-testid="1">1</CompositeItem>
             <CompositeItem data-testid="2">2</CompositeItem>
             <CompositeItem data-testid="3">3</CompositeItem>
diff --git a/packages/react/src/Composite/Root/CompositeRoot.tsx b/packages/react/src/Composite/Root/CompositeRoot.tsx
index c8a71a04a0..ba93408eff 100644
--- a/packages/react/src/Composite/Root/CompositeRoot.tsx
+++ b/packages/react/src/Composite/Root/CompositeRoot.tsx
@@ -16,8 +16,8 @@ function CompositeRoot<Metadata extends {}>(props: CompositeRoot.Props<Metadata>
   const {
     render,
     className,
-    activeIndex: activeIndexProp,
-    onActiveIndexChange: onActiveIndexChangeProp,
+    highlightedIndex: highlightedIndexProp,
+    onHighlightedIndexChange: onHighlightedIndexChangeProp,
     orientation,
     dense,
     itemSizes,
@@ -30,18 +30,19 @@ function CompositeRoot<Metadata extends {}>(props: CompositeRoot.Props<Metadata>
     ...otherProps
   } = props;
 
-  const { getRootProps, activeIndex, onActiveIndexChange, elementsRef } = useCompositeRoot({
-    itemSizes,
-    cols,
-    loop,
-    dense,
-    orientation,
-    activeIndex: activeIndexProp,
-    onActiveIndexChange: onActiveIndexChangeProp,
-    rootRef,
-    stopEventPropagation,
-    enableHomeAndEndKeys,
-  });
+  const { getRootProps, highlightedIndex, onHighlightedIndexChange, elementsRef } =
+    useCompositeRoot({
+      itemSizes,
+      cols,
+      loop,
+      dense,
+      orientation,
+      highlightedIndex: highlightedIndexProp,
+      onHighlightedIndexChange: onHighlightedIndexChangeProp,
+      rootRef,
+      stopEventPropagation,
+      enableHomeAndEndKeys,
+    });
 
   const { renderElement } = useComponentRenderer({
     propGetter: getRootProps,
@@ -52,8 +53,8 @@ function CompositeRoot<Metadata extends {}>(props: CompositeRoot.Props<Metadata>
   });
 
   const contextValue: CompositeRootContext = React.useMemo(
-    () => ({ activeIndex, onActiveIndexChange }),
-    [activeIndex, onActiveIndexChange],
+    () => ({ highlightedIndex, onHighlightedIndexChange }),
+    [highlightedIndex, onHighlightedIndexChange],
   );
 
   return (
@@ -72,8 +73,8 @@ namespace CompositeRoot {
     orientation?: 'horizontal' | 'vertical' | 'both';
     cols?: number;
     loop?: boolean;
-    activeIndex?: number;
-    onActiveIndexChange?: (index: number) => void;
+    highlightedIndex?: number;
+    onHighlightedIndexChange?: (index: number) => void;
     itemSizes?: Dimensions[];
     dense?: boolean;
     enableHomeAndEndKeys?: boolean;
@@ -90,10 +91,6 @@ CompositeRoot.propTypes /* remove-proptypes */ = {
   // │ These PropTypes are generated from the TypeScript type definitions. │
   // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
   // └─────────────────────────────────────────────────────────────────────┘
-  /**
-   * @ignore
-   */
-  activeIndex: PropTypes.number,
   /**
    * @ignore
    */
@@ -114,6 +111,10 @@ CompositeRoot.propTypes /* remove-proptypes */ = {
    * @ignore
    */
   enableHomeAndEndKeys: PropTypes.bool,
+  /**
+   * @ignore
+   */
+  highlightedIndex: PropTypes.number,
   /**
    * @ignore
    */
@@ -130,7 +131,7 @@ CompositeRoot.propTypes /* remove-proptypes */ = {
   /**
    * @ignore
    */
-  onActiveIndexChange: PropTypes.func,
+  onHighlightedIndexChange: PropTypes.func,
   /**
    * @ignore
    */
diff --git a/packages/react/src/Composite/Root/CompositeRootContext.ts b/packages/react/src/Composite/Root/CompositeRootContext.ts
index f92f119c95..347ec9d1a7 100644
--- a/packages/react/src/Composite/Root/CompositeRootContext.ts
+++ b/packages/react/src/Composite/Root/CompositeRootContext.ts
@@ -2,8 +2,8 @@
 import * as React from 'react';
 
 export interface CompositeRootContext {
-  activeIndex: number;
-  onActiveIndexChange: (index: number) => void;
+  highlightedIndex: number;
+  onHighlightedIndexChange: (index: number) => void;
 }
 
 export const CompositeRootContext = React.createContext<CompositeRootContext | undefined>(
diff --git a/packages/react/src/Composite/Root/useCompositeRoot.ts b/packages/react/src/Composite/Root/useCompositeRoot.ts
index 73c1589246..4311f78755 100644
--- a/packages/react/src/Composite/Root/useCompositeRoot.ts
+++ b/packages/react/src/Composite/Root/useCompositeRoot.ts
@@ -34,8 +34,8 @@ export interface UseCompositeRootParameters {
   orientation?: 'horizontal' | 'vertical' | 'both';
   cols?: number;
   loop?: boolean;
-  activeIndex?: number;
-  onActiveIndexChange?: (index: number) => void;
+  highlightedIndex?: number;
+  onHighlightedIndexChange?: (index: number) => void;
   dense?: boolean;
   itemSizes?: Array<Dimensions>;
   rootRef?: React.Ref<Element>;
@@ -66,19 +66,21 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
     loop = true,
     dense = false,
     orientation = 'both',
-    activeIndex: externalActiveIndex,
-    onActiveIndexChange: externalSetActiveIndex,
+    highlightedIndex: externalHighlightedIndex,
+    onHighlightedIndexChange: externalSetHighlightedIndex,
     rootRef: externalRef,
     enableHomeAndEndKeys = false,
     stopEventPropagation = false,
   } = params;
 
-  const [internalActiveIndex, internalSetActiveIndex] = React.useState(0);
+  const [internalHighlightedIndex, internalSetHighlightedIndex] = React.useState(0);
 
   const isGrid = cols > 1;
 
-  const activeIndex = externalActiveIndex ?? internalActiveIndex;
-  const onActiveIndexChange = useEventCallback(externalSetActiveIndex ?? internalSetActiveIndex);
+  const highlightedIndex = externalHighlightedIndex ?? internalHighlightedIndex;
+  const onHighlightedIndexChange = useEventCallback(
+    externalSetHighlightedIndex ?? internalSetHighlightedIndex,
+  );
 
   const textDirectionRef = React.useRef<TextDirection | null>(null);
 
@@ -110,7 +112,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
 
           const isRtl = textDirectionRef?.current === 'rtl';
 
-          let nextIndex = activeIndex;
+          let nextIndex = highlightedIndex;
           const minIndex = getMinIndex(elementsRef, disabledIndices);
           const maxIndex = getMaxIndex(elementsRef, disabledIndices);
 
@@ -163,7 +165,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
                   minIndex: minGridIndex,
                   maxIndex: maxGridIndex,
                   prevIndex: getCellIndexOfCorner(
-                    activeIndex > maxIndex ? minIndex : activeIndex,
+                    highlightedIndex > maxIndex ? minIndex : highlightedIndex,
                     sizes,
                     cellMap,
                     cols,
@@ -211,7 +213,10 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
             }
           }
 
-          if (nextIndex === activeIndex && [...toEndKeys, ...toStartKeys].includes(event.key)) {
+          if (
+            nextIndex === highlightedIndex &&
+            [...toEndKeys, ...toStartKeys].includes(event.key)
+          ) {
             if (loop && nextIndex === maxIndex && toEndKeys.includes(event.key)) {
               nextIndex = minIndex;
             } else if (loop && nextIndex === minIndex && toStartKeys.includes(event.key)) {
@@ -225,7 +230,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
             }
           }
 
-          if (nextIndex !== activeIndex && !isIndexOutOfBounds(elementsRef, nextIndex)) {
+          if (nextIndex !== highlightedIndex && !isIndexOutOfBounds(elementsRef, nextIndex)) {
             if (stopEventPropagation) {
               event.stopPropagation();
             }
@@ -234,7 +239,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
               event.preventDefault();
             }
 
-            onActiveIndexChange(nextIndex);
+            onHighlightedIndexChange(nextIndex);
 
             // Wait for FocusManager `returnFocus` to execute.
             queueMicrotask(() => {
@@ -244,7 +249,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
         },
       }),
     [
-      activeIndex,
+      highlightedIndex,
       stopEventPropagation,
       cols,
       dense,
@@ -253,7 +258,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
       itemSizes,
       loop,
       mergedRef,
-      onActiveIndexChange,
+      onHighlightedIndexChange,
       orientation,
       enableHomeAndEndKeys,
     ],
@@ -262,10 +267,10 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
   return React.useMemo(
     () => ({
       getRootProps,
-      activeIndex,
-      onActiveIndexChange,
+      highlightedIndex,
+      onHighlightedIndexChange,
       elementsRef,
     }),
-    [getRootProps, activeIndex, onActiveIndexChange, elementsRef],
+    [getRootProps, highlightedIndex, onHighlightedIndexChange, elementsRef],
   );
 }
diff --git a/packages/react/src/Tabs/Tab/Tab.test.tsx b/packages/react/src/Tabs/Tab/Tab.test.tsx
index c10e982097..010ae35c4c 100644
--- a/packages/react/src/Tabs/Tab/Tab.test.tsx
+++ b/packages/react/src/Tabs/Tab/Tab.test.tsx
@@ -10,8 +10,8 @@ describe('<Tabs.Tab />', () => {
   const { render } = createRenderer();
 
   const testCompositeContext = {
-    activeIndex: 0,
-    onActiveIndexChange: NOOP,
+    highlightedIndex: 0,
+    onHighlightedIndexChange: NOOP,
   };
 
   const testTabsListContext: TabsListContext = {
diff --git a/packages/react/src/Tabs/TabsList/TabsList.tsx b/packages/react/src/Tabs/TabsList/TabsList.tsx
index b1b1b9f68e..25cb0f21d4 100644
--- a/packages/react/src/Tabs/TabsList/TabsList.tsx
+++ b/packages/react/src/Tabs/TabsList/TabsList.tsx
@@ -91,10 +91,10 @@ const TabsList = React.forwardRef(function TabsList(
   return (
     <TabsListContext.Provider value={tabsListContextValue}>
       <CompositeRoot<TabMetadata>
-        activeIndex={highlightedTabIndex}
+        highlightedIndex={highlightedTabIndex}
         enableHomeAndEndKeys
         loop={loop}
-        onActiveIndexChange={setHighlightedTabIndex}
+        onHighlightedIndexChange={setHighlightedTabIndex}
         onMapChange={setTabMap}
         render={renderElement()}
       />