Merge branch 'master' into feat/meter

.circleci/config.yml

@@ -288,7 +288,7 @@ jobs:
     <<: *default-job
     resource_class: 'medium+'
     docker:
-      - image: mcr.microsoft.com/playwright:v1.48.2-focal
+      - image: mcr.microsoft.com/playwright:v1.49.0-noble
     steps:
       - checkout
       - install_js:
@@ -317,7 +317,7 @@ jobs:
   test_profile:
     <<: *default-job
     docker:
-      - image: mcr.microsoft.com/playwright:v1.48.2-focal
+      - image: mcr.microsoft.com/playwright:v1.49.0-noble
     steps:
       - checkout
       - install_js:
@@ -343,7 +343,7 @@ jobs:
   test_regressions:
     <<: *default-job
     docker:
-      - image: mcr.microsoft.com/playwright:v1.48.2-focal
+      - image: mcr.microsoft.com/playwright:v1.49.0-noble
     steps:
       - checkout
       - install_js:
@@ -358,7 +358,7 @@ jobs:
   test_e2e:
     <<: *default-job
     docker:
-      - image: mcr.microsoft.com/playwright:v1.48.2-focal
+      - image: mcr.microsoft.com/playwright:v1.49.0-noble
     steps:
       - checkout
       - install_js:

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'"

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": {}

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'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": {}

docs/package.json

@@ -25,8 +25,8 @@
     "@mdx-js/loader": "^3.1.0",
     "@mdx-js/mdx": "^3.1.0",
     "@mdx-js/react": "^3.1.0",
-    "@mui/system": "6.1.6",
-    "@mui/utils": "6.1.6",
+    "@mui/system": "6.1.8",
+    "@mui/utils": "6.1.8",
     "@next/mdx": "^15.0.2",
     "@react-spring/web": "^9.7.5",
     "@stefanprobst/rehype-extract-toc": "^2.2.0",
@@ -74,7 +74,7 @@
     "@babel/plugin-transform-react-constant-elements": "^7.25.9",
     "@babel/preset-typescript": "^7.26.0",
     "@mui/internal-docs-utils": "^1.0.15",
-    "@mui/internal-scripts": "^1.0.26",
+    "@mui/internal-scripts": "^1.0.27",
     "@mui/internal-test-utils": "https://pkg.csb.dev/mui/material-ui/commit/92c23999/@mui/internal-test-utils",
     "@tailwindcss/postcss": "4.0.0-alpha.36",
     "@types/chai": "^4.3.20",

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."
     }
   }
 }

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."
     }
   }
 }

package.json

@@ -75,14 +75,14 @@
     "@babel/preset-typescript": "^7.26.0",
     "@babel/register": "^7.25.9",
     "@mui/internal-docs-utils": "^1.0.15",
-    "@mui/internal-markdown": "^1.0.19",
-    "@mui/internal-scripts": "^1.0.26",
+    "@mui/internal-markdown": "^1.0.20",
+    "@mui/internal-scripts": "^1.0.27",
     "@mui/internal-test-utils": "https://pkg.csb.dev/mui/material-ui/commit/92c23999/@mui/internal-test-utils",
     "@mui/monorepo": "github:mui/material-ui#v6.1.7",
-    "@mui/utils": "6.1.6",
+    "@mui/utils": "6.1.8",
     "@next/eslint-plugin-next": "^14.2.17",
     "@octokit/rest": "^20.1.1",
-    "@playwright/test": "1.48.2",
+    "@playwright/test": "1.49.0",
     "@tailwindcss/postcss": "4.0.0-alpha.36",
     "@types/fs-extra": "^11.0.4",
     "@types/lodash": "^4.17.13",

packages/eslint-plugin-material-ui/package.json

@@ -7,7 +7,7 @@
   "devDependencies": {
     "@types/eslint": "^8.56.12",
     "@typescript-eslint/experimental-utils": "^5.62.0",
-    "@typescript-eslint/parser": "^8.14.0"
+    "@typescript-eslint/parser": "^8.15.0"
   },
   "scripts": {
     "test": "cd ../../ && cross-env NODE_ENV=test mocha 'packages/eslint-plugin-material-ui/**/*.test.js' --timeout 3000"

packages/react/package.json

@@ -51,17 +51,17 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.26.0",
-    "@floating-ui/react": "^0.26.27",
+    "@floating-ui/react": "^0.26.28",
     "@floating-ui/react-dom": "^2.1.2",
     "@floating-ui/utils": "^0.2.8",
     "@mui/types": "^7.2.19",
-    "@mui/utils": "^6.1.7",
+    "@mui/utils": "^6.1.8",
     "clsx": "^2.1.1",
     "prop-types": "^15.8.1",
     "use-sync-external-store": "^1.2.2"
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.16.4",
+    "@arethetypeswrong/cli": "^0.17.0",
     "@mui/internal-test-utils": "https://pkg.csb.dev/mui/material-ui/commit/92c23999/@mui/internal-test-utils",
     "@testing-library/react": "^16.0.1",
     "@testing-library/user-event": "^14.5.2",

packages/react/src/Composite/Item/CompositeItem.tsx

@@ -5,28 +5,26 @@ 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';
 
 /**
  * @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 { highlightedIndex } = useCompositeRootContext();
+  const { getItemProps, ref, index } = useCompositeItem({ metadata });
 
   const ownerState: CompositeItem.OwnerState = React.useMemo(
     () => ({
-      active: index === activeIndex,
+      highlighted: index === highlightedIndex,
     }),
-    [index, activeIndex],
+    [index, highlightedIndex],
   );
 
-  const mergedRef = useForkRef(forwardedRef, ref);
+  const mergedRef = useForkRef(itemRef, ref);
 
   const { renderElement } = useComponentRenderer({
     propGetter: getItemProps,
@@ -38,16 +36,23 @@ const CompositeItem = React.forwardRef(function CompositeItem(
   });
 
   return renderElement();
-});
+}
 
 namespace CompositeItem {
   export interface OwnerState {
-    active: boolean;
+    highlighted: 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;
+  }
 }
 
+export { CompositeItem };
+
 CompositeItem.propTypes /* remove-proptypes */ = {
   // ┌────────────────────────────── Warning ──────────────────────────────┐
   // │ These PropTypes are generated from the TypeScript type definitions. │
@@ -61,10 +66,16 @@ 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: refType,
+  /**
+   * @ignore
+   */
+  metadata: PropTypes.any,
   /**
    * A function to customize rendering of the component.
    */
   render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
 } as any;
-
-export { CompositeItem };

packages/react/src/Composite/Item/useCompositeItem.ts

@@ -4,26 +4,30 @@ 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() {
-  const { activeIndex, onActiveIndexChange } = useCompositeRootContext();
-  const { ref, index } = useCompositeListItem();
-  const isActive = activeIndex === index;
+export function useCompositeItem<Metadata>(params: UseCompositeItemParameters<Metadata> = {}) {
+  const { highlightedIndex, onHighlightedIndexChange } = useCompositeRootContext();
+  const { ref, index } = useCompositeListItem(params);
+  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(