From 19e65d2c872207a6a2e089270cd994819bcba0ac Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 29 Oct 2024 00:49:12 +0800
Subject: [PATCH 01/19] Add ToggleButton component and hooks

---
 docs/data/api/toggle-button.json              |  29 ++++
 .../toggle-button/ToggleButtonIntroduction.js |  26 ++++
 .../ToggleButtonIntroduction.tsx              |  26 ++++
 .../ToggleButtonIntroduction.tsx.preview      |  16 ++
 .../toggle-button/styles.module.css           |  38 +++++
 .../toggle-button/toggle-button.mdx           |  76 ++++++++++
 docs/data/pages.ts                            |   1 +
 .../api-docs/toggle-button/toggle-button.json |  26 ++++
 docs/src/app/experiments/toggle.tsx           |  30 ++++
 .../src/ToggleButton/ToggleButton.test.tsx    | 101 +++++++++++++
 .../src/ToggleButton/ToggleButton.tsx         | 142 ++++++++++++++++++
 packages/mui-base/src/ToggleButton/index.ts   |   1 +
 .../src/ToggleButton/useToggleButton.ts       | 112 ++++++++++++++
 packages/mui-base/src/index.ts                |   1 +
 14 files changed, 625 insertions(+)
 create mode 100644 docs/data/api/toggle-button.json
 create mode 100644 docs/data/components/toggle-button/ToggleButtonIntroduction.js
 create mode 100644 docs/data/components/toggle-button/ToggleButtonIntroduction.tsx
 create mode 100644 docs/data/components/toggle-button/ToggleButtonIntroduction.tsx.preview
 create mode 100644 docs/data/components/toggle-button/styles.module.css
 create mode 100644 docs/data/components/toggle-button/toggle-button.mdx
 create mode 100644 docs/data/translations/api-docs/toggle-button/toggle-button.json
 create mode 100644 docs/src/app/experiments/toggle.tsx
 create mode 100644 packages/mui-base/src/ToggleButton/ToggleButton.test.tsx
 create mode 100644 packages/mui-base/src/ToggleButton/ToggleButton.tsx
 create mode 100644 packages/mui-base/src/ToggleButton/index.ts
 create mode 100644 packages/mui-base/src/ToggleButton/useToggleButton.ts

diff --git a/docs/data/api/toggle-button.json b/docs/data/api/toggle-button.json
new file mode 100644
index 0000000000..bd65e37c6b
--- /dev/null
+++ b/docs/data/api/toggle-button.json
@@ -0,0 +1,29 @@
+{
+  "props": {
+    "aria-label": { "type": { "name": "string" } },
+    "aria-labelledby": { "type": { "name": "string" } },
+    "className": { "type": { "name": "union", "description": "func<br>&#124;&nbsp;string" } },
+    "defaultPressed": { "type": { "name": "bool" }, "default": "false" },
+    "disabled": { "type": { "name": "bool" }, "default": "false" },
+    "onPressedChange": {
+      "type": { "name": "func" },
+      "signature": {
+        "type": "function(pressed: boolean, event: Event) => void",
+        "describedArgs": ["pressed", "event"]
+      }
+    },
+    "pressed": { "type": { "name": "bool" }, "default": "undefined" },
+    "render": { "type": { "name": "union", "description": "element<br>&#124;&nbsp;func" } }
+  },
+  "name": "ToggleButton",
+  "imports": ["import { ToggleButton } from '@base_ui/react/ToggleButton';"],
+  "classes": [],
+  "spread": true,
+  "themeDefaultProps": true,
+  "muiName": "ToggleButton",
+  "forwardsRefTo": "HTMLButtonElement",
+  "filename": "/packages/mui-base/src/ToggleButton/ToggleButton.tsx",
+  "inheritance": null,
+  "demos": "<ul><li><a href=\"/components/react-toggle-button/\">ToggleButton</a></li></ul>",
+  "cssComponent": false
+}
diff --git a/docs/data/components/toggle-button/ToggleButtonIntroduction.js b/docs/data/components/toggle-button/ToggleButtonIntroduction.js
new file mode 100644
index 0000000000..446269b0ca
--- /dev/null
+++ b/docs/data/components/toggle-button/ToggleButtonIntroduction.js
@@ -0,0 +1,26 @@
+'use client';
+import * as React from 'react';
+import { ToggleButton } from '@base_ui/react/ToggleButton';
+import classes from './styles.module.css';
+
+export default function ToggleButtonIntroduction() {
+  const [pressed, setPressed] = React.useState(false);
+  return (
+    <ToggleButton
+      pressed={pressed}
+      onPressedChange={setPressed}
+      className={classes.button}
+      aria-label="Bookmark this article"
+    >
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        className={classes.icon}
+      >
+        <path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z" />
+      </svg>
+    </ToggleButton>
+  );
+}
diff --git a/docs/data/components/toggle-button/ToggleButtonIntroduction.tsx b/docs/data/components/toggle-button/ToggleButtonIntroduction.tsx
new file mode 100644
index 0000000000..446269b0ca
--- /dev/null
+++ b/docs/data/components/toggle-button/ToggleButtonIntroduction.tsx
@@ -0,0 +1,26 @@
+'use client';
+import * as React from 'react';
+import { ToggleButton } from '@base_ui/react/ToggleButton';
+import classes from './styles.module.css';
+
+export default function ToggleButtonIntroduction() {
+  const [pressed, setPressed] = React.useState(false);
+  return (
+    <ToggleButton
+      pressed={pressed}
+      onPressedChange={setPressed}
+      className={classes.button}
+      aria-label="Bookmark this article"
+    >
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        className={classes.icon}
+      >
+        <path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z" />
+      </svg>
+    </ToggleButton>
+  );
+}
diff --git a/docs/data/components/toggle-button/ToggleButtonIntroduction.tsx.preview b/docs/data/components/toggle-button/ToggleButtonIntroduction.tsx.preview
new file mode 100644
index 0000000000..3109ca040b
--- /dev/null
+++ b/docs/data/components/toggle-button/ToggleButtonIntroduction.tsx.preview
@@ -0,0 +1,16 @@
+<ToggleButton
+  pressed={pressed}
+  onPressedChange={setPressed}
+  className={classes.button}
+  aria-label="Bookmark this article"
+>
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="24"
+    height="24"
+    viewBox="0 0 24 24"
+    className={classes.icon}
+  >
+    <path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z" />
+  </svg>
+</ToggleButton>
\ No newline at end of file
diff --git a/docs/data/components/toggle-button/styles.module.css b/docs/data/components/toggle-button/styles.module.css
new file mode 100644
index 0000000000..13cf86e1d1
--- /dev/null
+++ b/docs/data/components/toggle-button/styles.module.css
@@ -0,0 +1,38 @@
+.button {
+  --size: 2.5rem;
+  --corner: 0.4rem;
+
+  display: flex;
+  flex-flow: row nowrap;
+  justify-content: center;
+  align-items: center;
+  height: var(--size);
+  width: var(--size);
+  border: 1px solid var(--gray-outline-2);
+  border-radius: var(--corner);
+  background-color: var(--gray-container-1);
+  color: var(--gray-text-1);
+}
+
+.button:hover {
+  background-color: var(--gray-surface-1);
+  color: var(--gray-text-2);
+}
+
+.button:focus-visible {
+  outline: 2px solid var(--gray-900);
+}
+
+.icon {
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.button[data-pressed] .icon {
+  color: var(--gray-text-2);
+  fill: currentColor;
+  stroke-width: 0;
+}
diff --git a/docs/data/components/toggle-button/toggle-button.mdx b/docs/data/components/toggle-button/toggle-button.mdx
new file mode 100644
index 0000000000..23fcf639ea
--- /dev/null
+++ b/docs/data/components/toggle-button/toggle-button.mdx
@@ -0,0 +1,76 @@
+---
+productId: base-ui
+title: React ToggleButton component
+description: Toggle Buttons are a two-state button that can either be off (not pressed) or on (pressed).
+components: ToggleButton
+hooks: useToggleButton
+githubLabel: 'component: toggle button'
+waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/button/
+packageName: '@base_ui/react'
+---
+
+# ToggleButton
+
+<Description />
+
+<ComponentLinkHeader design={false} />
+
+<Demo demo="ToggleButtonIntroduction" defaultCodeOpen="false" bg="gradient" />
+
+## Installation
+
+<InstallationInstructions componentName="ToggleButton" />
+
+## Anatomy
+
+ToggleButton is a single component that renders a `<button>`:
+
+```tsx
+<ToggleButton>Toggle bookmark</ToggleButton>
+```
+
+## Controlled
+
+Use the `pressed` and `onPressedChange` props to control the pressed state:
+
+```jsx
+const [pressed, setPressed] = React.useState(false);
+
+<ToggleButton pressed={pressed} onPressedChange={setPressed}>
+  {/* children */}
+</ToggleButton>;
+```
+
+## Uncontrolled
+
+Use the `defaultPressed` prop to set the initial pressed state of the component when uncontrolled:
+
+```jsx
+<ToggleButton defaultPressed={false}>{/* children */}</ToggleButton>
+```
+
+## Accessibility
+
+ToggleButtons must be given an accessible name with `aria-label` or `aria-labelledby`. It is important that the label does not change based on the pressed state to ensure a smooth screen-reader experience, since announcing the pressed state is already handled by `aria-pressed`.
+
+## Styling
+
+Use the `[data-pressed]` attribute to apply styles based on the pressed state:
+
+```jsx
+<ToggleButton className="MyToggle">{/* children */}</ToggleButton>
+```
+
+```css
+/* base state, not pressed */
+.MyToggle {
+  background: white;
+  color: black;
+}
+
+/* pressed state */
+.MyToggle[data-pressed] {
+  background: black;
+  color: white;
+}
+```
diff --git a/docs/data/pages.ts b/docs/data/pages.ts
index b0efde5018..e31aada27f 100644
--- a/docs/data/pages.ts
+++ b/docs/data/pages.ts
@@ -44,6 +44,7 @@ const pages: readonly RouteMetadata[] = [
       { pathname: '/components/react-switch', title: 'Switch' },
       { pathname: '/components/react-tabs', title: 'Tabs' },
       { pathname: '/components/react-text-input', title: 'Text Input' },
+      { pathname: '/components/react-toggle-button', title: 'Toggle Button' },
       { pathname: '/components/react-tooltip', title: 'Tooltip' },
     ],
   },
diff --git a/docs/data/translations/api-docs/toggle-button/toggle-button.json b/docs/data/translations/api-docs/toggle-button/toggle-button.json
new file mode 100644
index 0000000000..61c1df289b
--- /dev/null
+++ b/docs/data/translations/api-docs/toggle-button/toggle-button.json
@@ -0,0 +1,26 @@
+{
+  "componentDescription": "",
+  "propDescriptions": {
+    "aria-label": { "description": "The label for the ToggleButton." },
+    "aria-labelledby": {
+      "description": "An id or space-separated list of ids of elements that label the ToggleButton."
+    },
+    "className": {
+      "description": "Class names applied to the element or a function that returns them based on the component&#39;s state."
+    },
+    "defaultPressed": {
+      "description": "The default pressed state. Use when the component is not controlled."
+    },
+    "disabled": { "description": "If <code>true</code>, the component is disabled." },
+    "onPressedChange": {
+      "description": "Callback fired when the pressed state is changed.",
+      "typeDescriptions": {
+        "pressed": "The new pressed state.",
+        "event": "The event source of the callback."
+      }
+    },
+    "pressed": { "description": "If <code>true</code>, the component is pressed." },
+    "render": { "description": "A function to customize rendering of the component." }
+  },
+  "classDescriptions": {}
+}
diff --git a/docs/src/app/experiments/toggle.tsx b/docs/src/app/experiments/toggle.tsx
new file mode 100644
index 0000000000..08ff006ac4
--- /dev/null
+++ b/docs/src/app/experiments/toggle.tsx
@@ -0,0 +1,30 @@
+'use client';
+import * as React from 'react';
+import { ToggleButton } from '@base_ui/react/ToggleButton';
+
+export default function ToggleButtonDemo() {
+  const [pressed, setPressed] = React.useState(true);
+  return (
+    <div>
+      <ToggleButton
+        pressed={pressed}
+        onPressedChange={setPressed}
+        // className={classes.button}
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={2}
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z" />
+        </svg>
+      </ToggleButton>
+    </div>
+  );
+}
diff --git a/packages/mui-base/src/ToggleButton/ToggleButton.test.tsx b/packages/mui-base/src/ToggleButton/ToggleButton.test.tsx
new file mode 100644
index 0000000000..cb0f17d100
--- /dev/null
+++ b/packages/mui-base/src/ToggleButton/ToggleButton.test.tsx
@@ -0,0 +1,101 @@
+import * as React from 'react';
+import { expect } from 'chai';
+import { spy } from 'sinon';
+import { act } from '@mui/internal-test-utils';
+import { ToggleButton } from '@base_ui/react/ToggleButton';
+import { createRenderer, describeConformance } from '#test-utils';
+
+describe('<ToggleButton />', () => {
+  const { render } = createRenderer();
+
+  describeConformance(<ToggleButton />, () => ({
+    refInstanceof: window.HTMLButtonElement,
+    render,
+  }));
+
+  describe('pressed state', () => {
+    it('controlled', async () => {
+      function App() {
+        const [pressed, setPressed] = React.useState(false);
+        return (
+          <div>
+            <input type="checkbox" checked={pressed} onChange={() => setPressed(!pressed)} />
+            <ToggleButton pressed={pressed} />;
+          </div>
+        );
+      }
+
+      const { getByRole } = await render(<App />);
+      const checkbox = getByRole('checkbox');
+      const button = getByRole('button');
+
+      expect(button).to.have.attribute('aria-pressed', 'false');
+      await act(async () => {
+        checkbox.click();
+      });
+
+      expect(button).to.have.attribute('aria-pressed', 'true');
+
+      await act(async () => {
+        checkbox.click();
+      });
+
+      expect(button).to.have.attribute('aria-pressed', 'false');
+    });
+
+    it('uncontrolled', async () => {
+      const { getByRole } = await render(<ToggleButton defaultPressed={false} />);
+
+      const button = getByRole('button');
+
+      expect(button).to.have.attribute('aria-pressed', 'false');
+      await act(async () => {
+        button.click();
+      });
+
+      expect(button).to.have.attribute('aria-pressed', 'true');
+
+      await act(async () => {
+        button.click();
+      });
+
+      expect(button).to.have.attribute('aria-pressed', 'false');
+    });
+  });
+
+  describe('prop: onPressedChange', () => {
+    it('is called when the pressed state changes', async () => {
+      const handlePressed = spy();
+      const { getByRole } = await render(
+        <ToggleButton defaultPressed={false} onPressedChange={handlePressed} />,
+      );
+
+      const button = getByRole('button');
+
+      await act(async () => {
+        button.click();
+      });
+
+      expect(handlePressed.callCount).to.equal(1);
+      expect(handlePressed.firstCall.args[0]).to.equal(true);
+    });
+  });
+
+  describe('prop: disabled', () => {
+    it('disables the component', async () => {
+      const handlePressed = spy();
+      const { getByRole } = await render(<ToggleButton disabled onPressedChange={handlePressed} />);
+
+      const button = getByRole('button');
+      expect(button).to.have.attribute('disabled');
+      expect(button).to.have.attribute('aria-pressed', 'false');
+
+      await act(async () => {
+        button.click();
+      });
+
+      expect(handlePressed.callCount).to.equal(0);
+      expect(button).to.have.attribute('aria-pressed', 'false');
+    });
+  });
+});
diff --git a/packages/mui-base/src/ToggleButton/ToggleButton.tsx b/packages/mui-base/src/ToggleButton/ToggleButton.tsx
new file mode 100644
index 0000000000..549c6bf1e3
--- /dev/null
+++ b/packages/mui-base/src/ToggleButton/ToggleButton.tsx
@@ -0,0 +1,142 @@
+'use client';
+import * as React from 'react';
+import PropTypes from 'prop-types';
+import { useComponentRenderer } from '../utils/useComponentRenderer';
+import type { BaseUIComponentProps } from '../utils/types';
+import { useToggleButton } from './useToggleButton';
+
+const customStyleHookMapping = {
+  disabled: () => null,
+};
+
+/**
+ *
+ * Demos:
+ *
+ * - [ToggleButton](https://base-ui.netlify.app/components/react-toggle-button/)
+ *
+ * API:
+ *
+ * - [ToggleButton API](https://base-ui.netlify.app/components/react-toggle-button/#api-reference-ToggleButton)
+ */
+const ToggleButton = React.forwardRef(function ToggleButton(
+  props: ToggleButton.Props,
+  forwardedRef: React.ForwardedRef<HTMLButtonElement>,
+) {
+  const {
+    pressed: pressedProp,
+    defaultPressed: defaultPressedProp,
+    disabled: disabledProp,
+    onPressedChange,
+    className,
+    render,
+    ...otherProps
+  } = props;
+
+  const { disabled, pressed, getRootProps } = useToggleButton({
+    pressed: pressedProp,
+    defaultPressed: defaultPressedProp,
+    disabled: disabledProp,
+    onPressedChange,
+    buttonRef: forwardedRef,
+  });
+
+  const ownerState: ToggleButton.OwnerState = React.useMemo(
+    () => ({
+      disabled,
+      pressed,
+    }),
+    [disabled, pressed],
+  );
+
+  const { renderElement } = useComponentRenderer({
+    propGetter: getRootProps,
+    render: render ?? 'button',
+    ref: forwardedRef,
+    ownerState,
+    className,
+    customStyleHookMapping,
+    extraProps: {
+      ...otherProps,
+    },
+  });
+
+  return renderElement();
+});
+
+ToggleButton.propTypes /* remove-proptypes */ = {
+  // ┌────────────────────────────── Warning ──────────────────────────────┐
+  // │ These PropTypes are generated from the TypeScript type definitions. │
+  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
+  // └─────────────────────────────────────────────────────────────────────┘
+  /**
+   * The label for the ToggleButton.
+   */
+  'aria-label': PropTypes.string,
+  /**
+   * An id or space-separated list of ids of elements that label the ToggleButton.
+   */
+  'aria-labelledby': PropTypes.string,
+  /**
+   * @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 pressed state. Use when the component is not controlled.
+   *
+   * @default false
+   */
+  defaultPressed: PropTypes.bool,
+  /**
+   * If `true`, the component is disabled.
+   *
+   * @default false
+   */
+  disabled: PropTypes.bool,
+  /**
+   * Callback fired when the pressed state is changed.
+   *
+   * @param {boolean} pressed The new pressed state.
+   * @param {Event} event The event source of the callback.
+   */
+  onPressedChange: PropTypes.func,
+  /**
+   * If `true`, the component is pressed.
+   *
+   * @default undefined
+   */
+  pressed: PropTypes.bool,
+  /**
+   * A function to customize rendering of the component.
+   */
+  render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+} as any;
+
+export { ToggleButton };
+
+export namespace ToggleButton {
+  export interface OwnerState {
+    pressed: boolean;
+    disabled: boolean;
+  }
+
+  export interface Props
+    extends Pick<
+        useToggleButton.Parameters,
+        'pressed' | 'defaultPressed' | 'disabled' | 'onPressedChange'
+      >,
+      BaseUIComponentProps<'button', OwnerState> {
+    /**
+     * The label for the ToggleButton.
+     */
+    'aria-label'?: React.AriaAttributes['aria-label'];
+    /**
+     * An id or space-separated list of ids of elements that label the ToggleButton.
+     */
+    'aria-labelledby'?: React.AriaAttributes['aria-labelledby'];
+  }
+}
diff --git a/packages/mui-base/src/ToggleButton/index.ts b/packages/mui-base/src/ToggleButton/index.ts
new file mode 100644
index 0000000000..0eb96b68e4
--- /dev/null
+++ b/packages/mui-base/src/ToggleButton/index.ts
@@ -0,0 +1 @@
+export { ToggleButton } from './ToggleButton';
diff --git a/packages/mui-base/src/ToggleButton/useToggleButton.ts b/packages/mui-base/src/ToggleButton/useToggleButton.ts
new file mode 100644
index 0000000000..d7eb351605
--- /dev/null
+++ b/packages/mui-base/src/ToggleButton/useToggleButton.ts
@@ -0,0 +1,112 @@
+'use client';
+import * as React from 'react';
+import { mergeReactProps } from '../utils/mergeReactProps';
+import { NOOP } from '../utils/noop';
+import { GenericHTMLProps } from '../utils/types';
+import { useControlled } from '../utils/useControlled';
+import { useEventCallback } from '../utils/useEventCallback';
+import { useButton } from '../useButton/useButton';
+
+export function useToggleButton(
+  parameters: useToggleButton.Parameters,
+): useToggleButton.ReturnValue {
+  const {
+    pressed: pressedProp,
+    onPressedChange: onPressedChangeProp = NOOP,
+    defaultPressed = false,
+    disabled = false,
+    buttonRef: externalRef,
+  } = parameters;
+
+  const [pressed, setPressedState] = useControlled({
+    controlled: pressedProp,
+    default: defaultPressed,
+    name: 'ToggleButton',
+    state: 'pressed',
+  });
+
+  const onPressedChange = useEventCallback(onPressedChangeProp);
+
+  const { getButtonProps, buttonRef } = useButton({
+    disabled,
+    buttonRef: externalRef,
+    type: 'button',
+  });
+
+  const getRootProps = React.useCallback(
+    (externalProps?: GenericHTMLProps): GenericHTMLProps => {
+      return mergeReactProps(
+        externalProps,
+        {
+          'aria-pressed': pressed,
+          onClick(event: React.MouseEvent) {
+            const nextPressed = !pressed;
+            setPressedState(nextPressed);
+            onPressedChange?.(nextPressed, event.nativeEvent);
+          },
+          ref: buttonRef,
+        },
+        getButtonProps(),
+      );
+    },
+    [getButtonProps, buttonRef, onPressedChange, pressed, setPressedState],
+  );
+
+  return React.useMemo(
+    () => ({
+      getRootProps,
+      disabled,
+      pressed,
+    }),
+    [getRootProps, disabled, pressed],
+  );
+}
+
+export namespace useToggleButton {
+  export interface Parameters {
+    buttonRef?: React.Ref<HTMLElement>;
+    /**
+     * If `true`, the component is pressed.
+     *
+     * @default undefined
+     */
+    pressed?: boolean;
+    /**
+     * The default pressed state. Use when the component is not controlled.
+     *
+     * @default false
+     */
+    defaultPressed?: boolean;
+    /**
+     * If `true`, the component is disabled.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Callback fired when the pressed state is changed.
+     *
+     * @param {boolean} pressed The new pressed state.
+     * @param {Event} event The event source of the callback.
+     */
+    onPressedChange?: (pressed: boolean, event: Event) => void;
+    // TODO: a prop to indicate `aria-pressed='mixed'` is supported
+  }
+
+  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
+     */
+    getRootProps: (externalProps?: GenericHTMLProps) => GenericHTMLProps;
+    /**
+     * If `true`, the ToggleButton is disabled.
+     */
+    disabled: boolean;
+    /**
+     * If `true`, the ToggleButton is pressed.
+     */
+    pressed: boolean;
+  }
+}
diff --git a/packages/mui-base/src/index.ts b/packages/mui-base/src/index.ts
index add2838b36..ef93f5beb2 100644
--- a/packages/mui-base/src/index.ts
+++ b/packages/mui-base/src/index.ts
@@ -20,4 +20,5 @@ export * from './Slider';
 export * from './Switch';
 export * from './Tabs';
 export * from './TextInput';
+export * from './ToggleButton';
 export * from './Tooltip';

From b8fe44c5f709b4820f2c36369169399516093afd Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 29 Oct 2024 14:15:00 +0800
Subject: [PATCH 02/19] Update dir structure

---
 docs/data/api/toggle-button-root.json         | 31 ++++++++
 .../toggle-button/toggle-button.mdx           |  3 +-
 .../toggle-button-root.json}                  |  0
 .../ToggleButtonRoot.test.tsx}                |  0
 .../ToggleButtonRoot.tsx}                     | 72 +++++++++----------
 .../useToggleButtonRoot.ts}                   | 20 +++---
 .../mui-base/src/ToggleButton/index.parts.ts  |  1 +
 packages/mui-base/src/ToggleButton/index.ts   |  2 +-
 8 files changed, 79 insertions(+), 50 deletions(-)
 create mode 100644 docs/data/api/toggle-button-root.json
 rename docs/data/translations/api-docs/{toggle-button/toggle-button.json => toggle-button-root/toggle-button-root.json} (100%)
 rename packages/mui-base/src/ToggleButton/{ToggleButton.test.tsx => Root/ToggleButtonRoot.test.tsx} (100%)
 rename packages/mui-base/src/ToggleButton/{ToggleButton.tsx => Root/ToggleButtonRoot.tsx} (81%)
 rename packages/mui-base/src/ToggleButton/{useToggleButton.ts => Root/useToggleButtonRoot.ts} (83%)
 create mode 100644 packages/mui-base/src/ToggleButton/index.parts.ts

diff --git a/docs/data/api/toggle-button-root.json b/docs/data/api/toggle-button-root.json
new file mode 100644
index 0000000000..cb3929415b
--- /dev/null
+++ b/docs/data/api/toggle-button-root.json
@@ -0,0 +1,31 @@
+{
+  "props": {
+    "aria-label": { "type": { "name": "string" } },
+    "aria-labelledby": { "type": { "name": "string" } },
+    "className": { "type": { "name": "union", "description": "func<br>&#124;&nbsp;string" } },
+    "defaultPressed": { "type": { "name": "bool" }, "default": "false" },
+    "disabled": { "type": { "name": "bool" }, "default": "false" },
+    "onPressedChange": {
+      "type": { "name": "func" },
+      "signature": {
+        "type": "function(pressed: boolean, event: Event) => void",
+        "describedArgs": ["pressed", "event"]
+      }
+    },
+    "pressed": { "type": { "name": "bool" }, "default": "undefined" },
+    "render": { "type": { "name": "union", "description": "element<br>&#124;&nbsp;func" } }
+  },
+  "name": "ToggleButtonRoot",
+  "imports": [
+    "import { ToggleButton } from '@base_ui/react/ToggleButton';\nconst ToggleButtonRoot = ToggleButton.Root;"
+  ],
+  "classes": [],
+  "spread": true,
+  "themeDefaultProps": true,
+  "muiName": "ToggleButtonRoot",
+  "forwardsRefTo": "HTMLButtonElement",
+  "filename": "/packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.tsx",
+  "inheritance": null,
+  "demos": "<ul><li><a href=\"/components/react-toggle-button/\">ToggleButton</a></li></ul>",
+  "cssComponent": false
+}
diff --git a/docs/data/components/toggle-button/toggle-button.mdx b/docs/data/components/toggle-button/toggle-button.mdx
index 23fcf639ea..00dffe7967 100644
--- a/docs/data/components/toggle-button/toggle-button.mdx
+++ b/docs/data/components/toggle-button/toggle-button.mdx
@@ -2,8 +2,7 @@
 productId: base-ui
 title: React ToggleButton component
 description: Toggle Buttons are a two-state button that can either be off (not pressed) or on (pressed).
-components: ToggleButton
-hooks: useToggleButton
+components: ToggleButtonRoot
 githubLabel: 'component: toggle button'
 waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/button/
 packageName: '@base_ui/react'
diff --git a/docs/data/translations/api-docs/toggle-button/toggle-button.json b/docs/data/translations/api-docs/toggle-button-root/toggle-button-root.json
similarity index 100%
rename from docs/data/translations/api-docs/toggle-button/toggle-button.json
rename to docs/data/translations/api-docs/toggle-button-root/toggle-button-root.json
diff --git a/packages/mui-base/src/ToggleButton/ToggleButton.test.tsx b/packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.test.tsx
similarity index 100%
rename from packages/mui-base/src/ToggleButton/ToggleButton.test.tsx
rename to packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.test.tsx
diff --git a/packages/mui-base/src/ToggleButton/ToggleButton.tsx b/packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.tsx
similarity index 81%
rename from packages/mui-base/src/ToggleButton/ToggleButton.tsx
rename to packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.tsx
index 549c6bf1e3..5a8a37800e 100644
--- a/packages/mui-base/src/ToggleButton/ToggleButton.tsx
+++ b/packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.tsx
@@ -1,9 +1,9 @@
 'use client';
 import * as React from 'react';
 import PropTypes from 'prop-types';
-import { useComponentRenderer } from '../utils/useComponentRenderer';
-import type { BaseUIComponentProps } from '../utils/types';
-import { useToggleButton } from './useToggleButton';
+import { useComponentRenderer } from '../../utils/useComponentRenderer';
+import type { BaseUIComponentProps } from '../../utils/types';
+import { useToggleButtonRoot } from './useToggleButtonRoot';
 
 const customStyleHookMapping = {
   disabled: () => null,
@@ -17,10 +17,10 @@ const customStyleHookMapping = {
  *
  * API:
  *
- * - [ToggleButton API](https://base-ui.netlify.app/components/react-toggle-button/#api-reference-ToggleButton)
+ * - [ToggleButtonRoot API](https://base-ui.netlify.app/components/react-toggle-button/#api-reference-ToggleButtonRoot)
  */
-const ToggleButton = React.forwardRef(function ToggleButton(
-  props: ToggleButton.Props,
+const ToggleButtonRoot = React.forwardRef(function ToggleButtonRoot(
+  props: ToggleButtonRoot.Props,
   forwardedRef: React.ForwardedRef<HTMLButtonElement>,
 ) {
   const {
@@ -33,7 +33,7 @@ const ToggleButton = React.forwardRef(function ToggleButton(
     ...otherProps
   } = props;
 
-  const { disabled, pressed, getRootProps } = useToggleButton({
+  const { disabled, pressed, getRootProps } = useToggleButtonRoot({
     pressed: pressedProp,
     defaultPressed: defaultPressedProp,
     disabled: disabledProp,
@@ -41,7 +41,7 @@ const ToggleButton = React.forwardRef(function ToggleButton(
     buttonRef: forwardedRef,
   });
 
-  const ownerState: ToggleButton.OwnerState = React.useMemo(
+  const ownerState: ToggleButtonRoot.OwnerState = React.useMemo(
     () => ({
       disabled,
       pressed,
@@ -56,15 +56,38 @@ const ToggleButton = React.forwardRef(function ToggleButton(
     ownerState,
     className,
     customStyleHookMapping,
-    extraProps: {
-      ...otherProps,
-    },
+    extraProps: otherProps,
   });
 
   return renderElement();
 });
 
-ToggleButton.propTypes /* remove-proptypes */ = {
+export { ToggleButtonRoot };
+
+export namespace ToggleButtonRoot {
+  export interface OwnerState {
+    pressed: boolean;
+    disabled: boolean;
+  }
+
+  export interface Props
+    extends Pick<
+        useToggleButtonRoot.Parameters,
+        'pressed' | 'defaultPressed' | 'disabled' | 'onPressedChange'
+      >,
+      BaseUIComponentProps<'button', OwnerState> {
+    /**
+     * The label for the ToggleButton.
+     */
+    'aria-label'?: React.AriaAttributes['aria-label'];
+    /**
+     * An id or space-separated list of ids of elements that label the ToggleButton.
+     */
+    'aria-labelledby'?: React.AriaAttributes['aria-labelledby'];
+  }
+}
+
+ToggleButtonRoot.propTypes /* remove-proptypes */ = {
   // ┌────────────────────────────── Warning ──────────────────────────────┐
   // │ These PropTypes are generated from the TypeScript type definitions. │
   // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
@@ -115,28 +138,3 @@ ToggleButton.propTypes /* remove-proptypes */ = {
    */
   render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
 } as any;
-
-export { ToggleButton };
-
-export namespace ToggleButton {
-  export interface OwnerState {
-    pressed: boolean;
-    disabled: boolean;
-  }
-
-  export interface Props
-    extends Pick<
-        useToggleButton.Parameters,
-        'pressed' | 'defaultPressed' | 'disabled' | 'onPressedChange'
-      >,
-      BaseUIComponentProps<'button', OwnerState> {
-    /**
-     * The label for the ToggleButton.
-     */
-    'aria-label'?: React.AriaAttributes['aria-label'];
-    /**
-     * An id or space-separated list of ids of elements that label the ToggleButton.
-     */
-    'aria-labelledby'?: React.AriaAttributes['aria-labelledby'];
-  }
-}
diff --git a/packages/mui-base/src/ToggleButton/useToggleButton.ts b/packages/mui-base/src/ToggleButton/Root/useToggleButtonRoot.ts
similarity index 83%
rename from packages/mui-base/src/ToggleButton/useToggleButton.ts
rename to packages/mui-base/src/ToggleButton/Root/useToggleButtonRoot.ts
index d7eb351605..e944cd0902 100644
--- a/packages/mui-base/src/ToggleButton/useToggleButton.ts
+++ b/packages/mui-base/src/ToggleButton/Root/useToggleButtonRoot.ts
@@ -1,15 +1,15 @@
 'use client';
 import * as React from 'react';
-import { mergeReactProps } from '../utils/mergeReactProps';
-import { NOOP } from '../utils/noop';
-import { GenericHTMLProps } from '../utils/types';
-import { useControlled } from '../utils/useControlled';
-import { useEventCallback } from '../utils/useEventCallback';
-import { useButton } from '../useButton/useButton';
+import { mergeReactProps } from '../../utils/mergeReactProps';
+import { NOOP } from '../../utils/noop';
+import { GenericHTMLProps } from '../../utils/types';
+import { useControlled } from '../../utils/useControlled';
+import { useEventCallback } from '../../utils/useEventCallback';
+import { useButton } from '../../useButton/useButton';
 
-export function useToggleButton(
-  parameters: useToggleButton.Parameters,
-): useToggleButton.ReturnValue {
+export function useToggleButtonRoot(
+  parameters: useToggleButtonRoot.Parameters,
+): useToggleButtonRoot.ReturnValue {
   const {
     pressed: pressedProp,
     onPressedChange: onPressedChangeProp = NOOP,
@@ -62,7 +62,7 @@ export function useToggleButton(
   );
 }
 
-export namespace useToggleButton {
+export namespace useToggleButtonRoot {
   export interface Parameters {
     buttonRef?: React.Ref<HTMLElement>;
     /**
diff --git a/packages/mui-base/src/ToggleButton/index.parts.ts b/packages/mui-base/src/ToggleButton/index.parts.ts
new file mode 100644
index 0000000000..9ede29f130
--- /dev/null
+++ b/packages/mui-base/src/ToggleButton/index.parts.ts
@@ -0,0 +1 @@
+export { ToggleButtonRoot as Root } from './Root/ToggleButtonRoot';
diff --git a/packages/mui-base/src/ToggleButton/index.ts b/packages/mui-base/src/ToggleButton/index.ts
index 0eb96b68e4..af39dd65af 100644
--- a/packages/mui-base/src/ToggleButton/index.ts
+++ b/packages/mui-base/src/ToggleButton/index.ts
@@ -1 +1 @@
-export { ToggleButton } from './ToggleButton';
+export { Root as ToggleButton } from './index.parts';

From 23d35f286c4c93a364b44e88cad80c1e5e235961 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 29 Oct 2024 23:21:39 +0800
Subject: [PATCH 03/19] Add ToggleButtonGroup

---
 docs/data/api/toggle-button-group-item.json   |  29 ++
 docs/data/api/toggle-button-group-root.json   |  24 ++
 .../ToggleButtonGroupIntroduction.js          |  77 +++++
 .../ToggleButtonGroupIntroduction.tsx         |  77 +++++
 .../ToggleButtonGroupToggleMultiple.js        |  66 +++++
 .../ToggleButtonGroupToggleMultiple.tsx       |  66 +++++
 .../toggle-button-group/styles.module.css     |  56 ++++
 .../toggle-button-group.mdx                   | 120 ++++++++
 docs/data/pages.ts                            |   1 +
 .../toggle-button-group-item.json             |  24 ++
 .../toggle-button-group-root.json             |  14 +
 docs/src/app/experiments/toggle-group.tsx     | 142 +++++++++
 docs/src/app/experiments/toggle.module.css    |  75 +++++
 docs/src/app/experiments/toggle.tsx           |  30 --
 .../ToggleButton/Root/ToggleButtonRoot.tsx    |  10 +
 .../Item/ToggleButtonGroupItem.test.tsx       |  94 ++++++
 .../Item/ToggleButtonGroupItem.tsx            | 144 ++++++++++
 .../Item/useToggleButtonGroupItem.ts          |  76 +++++
 .../Root/ToggleButtonGroupRoot.test.tsx       | 269 ++++++++++++++++++
 .../Root/ToggleButtonGroupRoot.tsx            | 159 +++++++++++
 .../Root/ToggleButtonGroupRootContext.ts      |  27 ++
 .../Root/useToggleButtonGroupRoot.ts          | 109 +++++++
 .../src/ToggleButtonGroup/index.parts.ts      |   2 +
 .../mui-base/src/ToggleButtonGroup/index.ts   |   1 +
 packages/mui-base/src/index.ts                |   1 +
 25 files changed, 1663 insertions(+), 30 deletions(-)
 create mode 100644 docs/data/api/toggle-button-group-item.json
 create mode 100644 docs/data/api/toggle-button-group-root.json
 create mode 100644 docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.js
 create mode 100644 docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.tsx
 create mode 100644 docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.js
 create mode 100644 docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.tsx
 create mode 100644 docs/data/components/toggle-button-group/styles.module.css
 create mode 100644 docs/data/components/toggle-button-group/toggle-button-group.mdx
 create mode 100644 docs/data/translations/api-docs/toggle-button-group-item/toggle-button-group-item.json
 create mode 100644 docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json
 create mode 100644 docs/src/app/experiments/toggle-group.tsx
 create mode 100644 docs/src/app/experiments/toggle.module.css
 delete mode 100644 docs/src/app/experiments/toggle.tsx
 create mode 100644 packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx
 create mode 100644 packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx
 create mode 100644 packages/mui-base/src/ToggleButtonGroup/Item/useToggleButtonGroupItem.ts
 create mode 100644 packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
 create mode 100644 packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
 create mode 100644 packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRootContext.ts
 create mode 100644 packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
 create mode 100644 packages/mui-base/src/ToggleButtonGroup/index.parts.ts
 create mode 100644 packages/mui-base/src/ToggleButtonGroup/index.ts

diff --git a/docs/data/api/toggle-button-group-item.json b/docs/data/api/toggle-button-group-item.json
new file mode 100644
index 0000000000..a9f4f93982
--- /dev/null
+++ b/docs/data/api/toggle-button-group-item.json
@@ -0,0 +1,29 @@
+{
+  "props": {
+    "value": { "type": { "name": "any" }, "required": true },
+    "aria-label": { "type": { "name": "string" } },
+    "aria-labelledby": { "type": { "name": "string" } },
+    "className": { "type": { "name": "union", "description": "func<br>&#124;&nbsp;string" } },
+    "onPressedChange": {
+      "type": { "name": "func" },
+      "signature": {
+        "type": "function(pressed: boolean, event: Event) => void",
+        "describedArgs": ["pressed", "event"]
+      }
+    },
+    "render": { "type": { "name": "union", "description": "element<br>&#124;&nbsp;func" } }
+  },
+  "name": "ToggleButtonGroupItem",
+  "imports": [
+    "import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';\nconst ToggleButtonGroupItem = ToggleButtonGroup.Item;"
+  ],
+  "classes": [],
+  "spread": true,
+  "themeDefaultProps": true,
+  "muiName": "ToggleButtonGroupItem",
+  "forwardsRefTo": "HTMLButtonElement",
+  "filename": "/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx",
+  "inheritance": null,
+  "demos": "<ul><li><a href=\"/components/react-toggle-button-group/\">ToggleButtonGroup</a></li></ul>",
+  "cssComponent": false
+}
diff --git a/docs/data/api/toggle-button-group-root.json b/docs/data/api/toggle-button-group-root.json
new file mode 100644
index 0000000000..1ecf406957
--- /dev/null
+++ b/docs/data/api/toggle-button-group-root.json
@@ -0,0 +1,24 @@
+{
+  "props": {
+    "className": { "type": { "name": "union", "description": "func<br>&#124;&nbsp;string" } },
+    "direction": {
+      "type": { "name": "enum", "description": "'ltr'<br>&#124;&nbsp;'rtl'" },
+      "default": "'ltr'"
+    },
+    "render": { "type": { "name": "union", "description": "element<br>&#124;&nbsp;func" } },
+    "toggleMultiple": { "type": { "name": "bool" }, "default": "false" }
+  },
+  "name": "ToggleButtonGroupRoot",
+  "imports": [
+    "import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';\nconst ToggleButtonGroupRoot = ToggleButtonGroup.Root;"
+  ],
+  "classes": [],
+  "spread": true,
+  "themeDefaultProps": true,
+  "muiName": "ToggleButtonGroupRoot",
+  "forwardsRefTo": "HTMLDivElement",
+  "filename": "/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx",
+  "inheritance": null,
+  "demos": "<ul><li><a href=\"/components/react-toggle-button-group/\">ToggleButtonGroup</a></li></ul>",
+  "cssComponent": false
+}
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.js b/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.js
new file mode 100644
index 0000000000..dea1da5e11
--- /dev/null
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.js
@@ -0,0 +1,77 @@
+'use client';
+import * as React from 'react';
+import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import classes from './styles.module.css';
+
+export default function ToggleButtonGroupIntroduction() {
+  const [value, setValue] = React.useState(['align-center']);
+  return (
+    <ToggleButtonGroup.Root
+      className={classes.root}
+      value={value}
+      onValueChange={(newValue) => {
+        if (newValue.length > 0) {
+          setValue(newValue);
+        }
+      }}
+      aria-label="Text alignment"
+    >
+      <ToggleButtonGroup.Item
+        className={classes.button}
+        value="align-left"
+        aria-label="Align left"
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <line x1="17" y1="10" x2="3" y2="10" />
+          <line x1="21" y1="6" x2="3" y2="6" />
+          <line x1="21" y1="14" x2="3" y2="14" />
+          <line x1="17" y1="18" x2="3" y2="18" />
+        </svg>
+      </ToggleButtonGroup.Item>
+
+      <ToggleButtonGroup.Item
+        className={classes.button}
+        value="align-center"
+        aria-label="Align center"
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <line x1="18" y1="10" x2="6" y2="10" />
+          <line x1="21" y1="6" x2="3" y2="6" />
+          <line x1="21" y1="14" x2="3" y2="14" />
+          <line x1="18" y1="18" x2="6" y2="18" />
+        </svg>
+      </ToggleButtonGroup.Item>
+
+      <ToggleButtonGroup.Item
+        className={classes.button}
+        value="align-right"
+        aria-label="Align right"
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <line x1="21" y1="10" x2="7" y2="10" />
+          <line x1="21" y1="6" x2="3" y2="6" />
+          <line x1="21" y1="14" x2="3" y2="14" />
+          <line x1="21" y1="18" x2="7" y2="18" />
+        </svg>
+      </ToggleButtonGroup.Item>
+    </ToggleButtonGroup.Root>
+  );
+}
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.tsx b/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.tsx
new file mode 100644
index 0000000000..1488496011
--- /dev/null
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.tsx
@@ -0,0 +1,77 @@
+'use client';
+import * as React from 'react';
+import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import classes from './styles.module.css';
+
+export default function ToggleButtonGroupIntroduction() {
+  const [value, setValue] = React.useState(['align-center']);
+  return (
+    <ToggleButtonGroup.Root
+      className={classes.root}
+      value={value}
+      onValueChange={(newValue) => {
+        if (newValue.length > 0) {
+          setValue(newValue as string[]);
+        }
+      }}
+      aria-label="Text alignment"
+    >
+      <ToggleButtonGroup.Item
+        className={classes.button}
+        value="align-left"
+        aria-label="Align left"
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <line x1="17" y1="10" x2="3" y2="10" />
+          <line x1="21" y1="6" x2="3" y2="6" />
+          <line x1="21" y1="14" x2="3" y2="14" />
+          <line x1="17" y1="18" x2="3" y2="18" />
+        </svg>
+      </ToggleButtonGroup.Item>
+
+      <ToggleButtonGroup.Item
+        className={classes.button}
+        value="align-center"
+        aria-label="Align center"
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <line x1="18" y1="10" x2="6" y2="10" />
+          <line x1="21" y1="6" x2="3" y2="6" />
+          <line x1="21" y1="14" x2="3" y2="14" />
+          <line x1="18" y1="18" x2="6" y2="18" />
+        </svg>
+      </ToggleButtonGroup.Item>
+
+      <ToggleButtonGroup.Item
+        className={classes.button}
+        value="align-right"
+        aria-label="Align right"
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <line x1="21" y1="10" x2="7" y2="10" />
+          <line x1="21" y1="6" x2="3" y2="6" />
+          <line x1="21" y1="14" x2="3" y2="14" />
+          <line x1="21" y1="18" x2="7" y2="18" />
+        </svg>
+      </ToggleButtonGroup.Item>
+    </ToggleButtonGroup.Root>
+  );
+}
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.js b/docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.js
new file mode 100644
index 0000000000..f67f4d2567
--- /dev/null
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.js
@@ -0,0 +1,66 @@
+'use client';
+import * as React from 'react';
+import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import classes from './styles.module.css';
+
+export default function ToggleButtonGroupToggleMultiple() {
+  return (
+    <ToggleButtonGroup.Root
+      toggleMultiple
+      aria-label="Text formatting"
+      className={classes.root}
+    >
+      <ToggleButtonGroup.Item
+        value="bold"
+        aria-label="Toggle bold"
+        className={classes.button}
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+          <path d="M6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+        </svg>
+      </ToggleButtonGroup.Item>
+
+      <ToggleButtonGroup.Item
+        value="italics"
+        aria-label="Toggle italics"
+        className={classes.button}
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <line x1="19" y1="4" x2="10" y2="4" />
+          <line x1="14" y1="20" x2="5" y2="20" />
+          <line x1="15" y1="4" x2="9" y2="20" />
+        </svg>
+      </ToggleButtonGroup.Item>
+
+      <ToggleButtonGroup.Item
+        value="underline"
+        aria-label="Toggle underline"
+        className={classes.button}
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <path d="M6 3v7a6 6 0 0 0 6 6 6 6 0 0 0 6-6V3" />
+          <line x1="4" y1="21" x2="20" y2="21" />
+        </svg>
+      </ToggleButtonGroup.Item>
+    </ToggleButtonGroup.Root>
+  );
+}
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.tsx b/docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.tsx
new file mode 100644
index 0000000000..f67f4d2567
--- /dev/null
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.tsx
@@ -0,0 +1,66 @@
+'use client';
+import * as React from 'react';
+import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import classes from './styles.module.css';
+
+export default function ToggleButtonGroupToggleMultiple() {
+  return (
+    <ToggleButtonGroup.Root
+      toggleMultiple
+      aria-label="Text formatting"
+      className={classes.root}
+    >
+      <ToggleButtonGroup.Item
+        value="bold"
+        aria-label="Toggle bold"
+        className={classes.button}
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+          <path d="M6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+        </svg>
+      </ToggleButtonGroup.Item>
+
+      <ToggleButtonGroup.Item
+        value="italics"
+        aria-label="Toggle italics"
+        className={classes.button}
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <line x1="19" y1="4" x2="10" y2="4" />
+          <line x1="14" y1="20" x2="5" y2="20" />
+          <line x1="15" y1="4" x2="9" y2="20" />
+        </svg>
+      </ToggleButtonGroup.Item>
+
+      <ToggleButtonGroup.Item
+        value="underline"
+        aria-label="Toggle underline"
+        className={classes.button}
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <path d="M6 3v7a6 6 0 0 0 6 6 6 6 0 0 0 6-6V3" />
+          <line x1="4" y1="21" x2="20" y2="21" />
+        </svg>
+      </ToggleButtonGroup.Item>
+    </ToggleButtonGroup.Root>
+  );
+}
diff --git a/docs/data/components/toggle-button-group/styles.module.css b/docs/data/components/toggle-button-group/styles.module.css
new file mode 100644
index 0000000000..965b79590b
--- /dev/null
+++ b/docs/data/components/toggle-button-group/styles.module.css
@@ -0,0 +1,56 @@
+.root {
+  display: flex;
+}
+
+.button {
+  --size: 2.5rem;
+  --corner: 0.4rem;
+  --border-color: var(--gray-outline-2);
+
+  display: flex;
+  flex-flow: row nowrap;
+  justify-content: center;
+  align-items: center;
+  height: var(--size);
+  width: var(--size);
+  border: 1px solid var(--border-color);
+  background-color: var(--gray-container-2);
+  color: var(--gray-400);
+}
+
+.button:first-child {
+  border-radius: var(--corner) 0 0 var(--corner);
+  border-right-color: transparent;
+}
+
+.button:last-child {
+  border-radius: 0 var(--corner) var(--corner) 0;
+  border-left-color: transparent;
+}
+
+.button:hover {
+  background-color: var(--gray-surface-1);
+  outline: 1px solid var(--gray-500);
+  outline-offset: -1px;
+  color: var(--gray-text-2);
+  cursor: pointer;
+  z-index: 1;
+}
+
+.button:focus-visible {
+  outline: 2px solid var(--gray-900);
+  z-index: 1;
+}
+
+.icon {
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.button[data-pressed] {
+  background-color: #fefefe;
+  color: var(--gray-text-2);
+}
diff --git a/docs/data/components/toggle-button-group/toggle-button-group.mdx b/docs/data/components/toggle-button-group/toggle-button-group.mdx
new file mode 100644
index 0000000000..3b49138d4e
--- /dev/null
+++ b/docs/data/components/toggle-button-group/toggle-button-group.mdx
@@ -0,0 +1,120 @@
+---
+productId: base-ui
+title: React ToggleButtonGroup component
+description: ToggleButtonGroup provides a set of two-state buttons that can either be off (not pressed) or on (pressed).
+components: ToggleButtonGroupRoot, ToggleButtonGroupItem
+githubLabel: 'component: toggle button'
+waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/radio-group/
+packageName: '@base_ui/react'
+---
+
+# ToggleButtonGroup
+
+<Description />
+
+<ComponentLinkHeader design={false} />
+
+<Demo demo="ToggleButtonGroupIntroduction" defaultCodeOpen="false" bg="gradient" />
+
+## Installation
+
+<InstallationInstructions componentName="ToggleButtonGroup" />
+
+## Anatomy
+
+ToggleButtonGroups are composed with two components:
+
+- `<ToggleButtonGroup.Root />` is the outer component that wraps a set of [`toggle buttons`](/components/react-toggle-button)
+- `<ToggleButtonGroup.Item />`s renders the `<button>`
+
+```tsx
+<ToggleButtonGroup.Root>
+  <ToggleButtonGroup.Item value="bold">Bold</ToggleButtonGroup.Item>
+  <ToggleButtonGroup.Item value="italics">Italics</ToggleButtonGroup.Item>
+  <ToggleButtonGroup.Item value="underline">Underline</ToggleButtonGroup.Item>
+</ToggleButtonGroup.Root>
+```
+
+## Value
+
+Each `Item` in the group must be given a unique value, e.g. a string like `'bold'`, `'italics'` in the examples above.
+
+### Uncontrolled
+
+When uncontrolled, use the `defaultValue` prop to set the initial state of the group:
+
+```tsx
+// only the "Italics" button is initially pressed
+<ToggleButtonGroup.Root defaultValue={['italics']}>
+  <ToggleButtonGroup.Item value="bold">Bold</ToggleButtonGroup.Item>
+  <ToggleButtonGroup.Item value="italics">Italics</ToggleButtonGroup.Item>
+  <ToggleButtonGroup.Item value="underline">Underline</ToggleButtonGroup.Item>
+</ToggleButtonGroup.Root>
+```
+
+### Controlled
+
+When controlled, pass the `value` and `onValueChange` props to `ToggleButtonGroup.Root`:
+
+```tsx
+const [value, setValue] = React.useState(['italics']);
+
+return (
+  <ToggleButtonGroup.Root value={value} onValueChange={setValue}>
+    <ToggleButtonGroup.Item value="align-left" />
+    <ToggleButtonGroup.Item value="align-center" />
+    <ToggleButtonGroup.Item value="align-right" />
+  </ToggleButtonGroup.Root>
+);
+```
+
+## Customization
+
+### Allow multiple buttons to be pressed
+
+Use the `toggleMultiple` prop to allow multiple buttons to be pressed at the same time:
+
+```tsx
+<ToggleButtonGroup.Root toggleMultiple>
+  <ToggleButtonGroup.Item value="bold" />
+  <ToggleButtonGroup.Item value="italics" />
+  <ToggleButtonGroup.Item value="underline" />
+</ToggleButtonGroup.Root>
+```
+
+<Demo demo="ToggleButtonGroupToggleMultiple" />
+
+### One button must be pressed
+
+Use controlled mode to always keep one button in the pressed state:
+
+```tsx
+const [value, setValue] = React.useState(['align-left']);
+
+const handleValueChange = (newValue) => {
+  if (newValue.length > 0) {
+    setValue(newValue);
+  }
+};
+
+return (
+  <ToggleButtonGroup.Root value={value} onValueChange={handleValueChange}>
+    <ToggleButtonGroup.Item value="align-left" />
+    <ToggleButtonGroup.Item value="align-center" />
+    <ToggleButtonGroup.Item value="align-right" />
+  </ToggleButtonGroup.Root>
+);
+```
+
+## RTL
+
+Use the `direction` prop to configure a RTL toggle button group:
+
+```tsx
+<ToggleButtonGroup.Root direction="rtl">{/* toggle buttons */}</ToggleButtonGroup.Root>
+```
+
+## Accessibility
+
+- The `Root` component, and every `Item` must be given must be given an accessible name with `aria-label` or `aria-labelledby`.
+- The `Item`'s label or accessible name _must not_ change based on the pressed state to ensure a smooth screen-reader experience, otherwise it may duplicate the announcement of the pressed state based on `aria-pressed`.
diff --git a/docs/data/pages.ts b/docs/data/pages.ts
index e31aada27f..600397b593 100644
--- a/docs/data/pages.ts
+++ b/docs/data/pages.ts
@@ -45,6 +45,7 @@ const pages: readonly RouteMetadata[] = [
       { pathname: '/components/react-tabs', title: 'Tabs' },
       { pathname: '/components/react-text-input', title: 'Text Input' },
       { pathname: '/components/react-toggle-button', title: 'Toggle Button' },
+      { pathname: '/components/react-toggle-button-group', title: 'Toggle Button Group' },
       { pathname: '/components/react-tooltip', title: 'Tooltip' },
     ],
   },
diff --git a/docs/data/translations/api-docs/toggle-button-group-item/toggle-button-group-item.json b/docs/data/translations/api-docs/toggle-button-group-item/toggle-button-group-item.json
new file mode 100644
index 0000000000..0527007e3d
--- /dev/null
+++ b/docs/data/translations/api-docs/toggle-button-group-item/toggle-button-group-item.json
@@ -0,0 +1,24 @@
+{
+  "componentDescription": "",
+  "propDescriptions": {
+    "aria-label": { "description": "The label for the toggle button." },
+    "aria-labelledby": {
+      "description": "An id or space-separated list of ids of elements that label the toggle button."
+    },
+    "className": {
+      "description": "Class names applied to the element or a function that returns them based on the component&#39;s state."
+    },
+    "onPressedChange": {
+      "description": "Callback fired when the pressed state is changed.",
+      "typeDescriptions": {
+        "pressed": "The new pressed state.",
+        "event": "The event source of the callback."
+      }
+    },
+    "render": { "description": "A function to customize rendering of the component." },
+    "value": {
+      "description": "A unique value that identifies the component when used inside a ToggleButtonGroup"
+    }
+  },
+  "classDescriptions": {}
+}
diff --git a/docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json b/docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json
new file mode 100644
index 0000000000..1b218a08ca
--- /dev/null
+++ b/docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json
@@ -0,0 +1,14 @@
+{
+  "componentDescription": "",
+  "propDescriptions": {
+    "className": {
+      "description": "Class names applied to the element or a function that returns them based on the component&#39;s state."
+    },
+    "direction": { "description": "Text direction" },
+    "render": { "description": "A function to customize rendering of the component." },
+    "toggleMultiple": {
+      "description": "When <code>false</code> only one ToggleButton in the group can be pressed. When a ToggleButton is pressed, the others in the group will become unpressed"
+    }
+  },
+  "classDescriptions": {}
+}
diff --git a/docs/src/app/experiments/toggle-group.tsx b/docs/src/app/experiments/toggle-group.tsx
new file mode 100644
index 0000000000..2ab4cd513b
--- /dev/null
+++ b/docs/src/app/experiments/toggle-group.tsx
@@ -0,0 +1,142 @@
+'use client';
+import * as React from 'react';
+import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import classes from './toggle.module.css';
+
+export default function ToggleButtonGroupDemo() {
+  const [value, setValue] = React.useState(['align-center']);
+  return (
+    <div className={classes.grid}>
+      <h4 style={{ margin: 0 }}>LTR</h4>
+
+      <ToggleButtonGroup.Root
+        value={value}
+        onValueChange={(newValue) => {
+          if (newValue.length > 0) {
+            setValue(newValue as string[]);
+          }
+        }}
+        aria-label="Text alignment"
+        className={classes.group}
+      >
+        <ToggleButtonGroup.Item
+          value="align-left"
+          aria-label="Align left"
+          className={classes.button}
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            className={classes.icon}
+          >
+            <line x1="17" y1="10" x2="3" y2="10" />
+            <line x1="21" y1="6" x2="3" y2="6" />
+            <line x1="21" y1="14" x2="3" y2="14" />
+            <line x1="17" y1="18" x2="3" y2="18" />
+          </svg>
+        </ToggleButtonGroup.Item>
+
+        <ToggleButtonGroup.Item
+          value="align-center"
+          aria-label="Align center"
+          className={classes.button}
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            className={classes.icon}
+          >
+            <line x1="18" y1="10" x2="6" y2="10" />
+            <line x1="21" y1="6" x2="3" y2="6" />
+            <line x1="21" y1="14" x2="3" y2="14" />
+            <line x1="18" y1="18" x2="6" y2="18" />
+          </svg>
+        </ToggleButtonGroup.Item>
+
+        <ToggleButtonGroup.Item
+          value="align-right"
+          aria-label="Align right"
+          className={classes.button}
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            className={classes.icon}
+          >
+            <line x1="21" y1="10" x2="7" y2="10" />
+            <line x1="21" y1="6" x2="3" y2="6" />
+            <line x1="21" y1="14" x2="3" y2="14" />
+            <line x1="21" y1="18" x2="7" y2="18" />
+          </svg>
+        </ToggleButtonGroup.Item>
+      </ToggleButtonGroup.Root>
+
+      <h4 style={{ margin: 0 }}>RTL</h4>
+
+      <ToggleButtonGroup.Root
+        toggleMultiple
+        aria-label="Text formatting"
+        direction="rtl"
+        className={classes.group}
+      >
+        <ToggleButtonGroup.Item
+          value="bold"
+          aria-label="Toggle bold"
+          className={classes.button}
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            className={classes.icon}
+          >
+            <path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+            <path d="M6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+          </svg>
+        </ToggleButtonGroup.Item>
+
+        <ToggleButtonGroup.Item
+          value="italics"
+          aria-label="Toggle italics"
+          className={classes.button}
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            className={classes.icon}
+          >
+            <line x1="19" y1="4" x2="10" y2="4" />
+            <line x1="14" y1="20" x2="5" y2="20" />
+            <line x1="15" y1="4" x2="9" y2="20" />
+          </svg>
+        </ToggleButtonGroup.Item>
+
+        <ToggleButtonGroup.Item
+          value="underline"
+          aria-label="Toggle underline"
+          className={classes.button}
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            className={classes.icon}
+          >
+            <path d="M6 3v7a6 6 0 0 0 6 6 6 6 0 0 0 6-6V3" />
+            <line x1="4" y1="21" x2="20" y2="21" />
+          </svg>
+        </ToggleButtonGroup.Item>
+      </ToggleButtonGroup.Root>
+    </div>
+  );
+}
diff --git a/docs/src/app/experiments/toggle.module.css b/docs/src/app/experiments/toggle.module.css
new file mode 100644
index 0000000000..f98692a217
--- /dev/null
+++ b/docs/src/app/experiments/toggle.module.css
@@ -0,0 +1,75 @@
+.grid {
+  display: grid;
+  grid-gap: 2rem;
+}
+
+.group {
+  display: flex;
+}
+
+.button {
+  --size: 2.5rem;
+  --corner-radius: 0.4rem;
+  --border-color: var(--gray-outline-2);
+  --border-radius-visual-right: 0 var(--corner-radius) var(--corner-radius) 0;
+  --border-radius-visual-left: var(--corner-radius) 0 0 var(--corner-radius);
+
+  display: flex;
+  flex-flow: row nowrap;
+  justify-content: center;
+  align-items: center;
+  height: var(--size);
+  width: var(--size);
+  border: 1px solid var(--border-color);
+  background-color: var(--gray-container-2);
+  color: var(--gray-400);
+}
+
+.button:disabled {
+  cursor: not-allowed;
+}
+
+.button:first-child {
+  border-radius: var(--border-radius-visual-left);
+  border-right-color: transparent;
+}
+
+.button:last-child {
+  border-radius: var(--border-radius-visual-right);
+  border-left-color: transparent;
+}
+
+[dir='rtl'] .button:first-child {
+  border-radius: var(--border-radius-visual-right);
+}
+
+[dir='rtl'] .button:last-child {
+  border-radius: var(--border-radius-visual-left);
+}
+
+.button:not(:disabled):hover {
+  background-color: var(--gray-surface-1);
+  outline: 1px solid var(--gray-500);
+  outline-offset: -1px;
+  color: var(--gray-text-2);
+  cursor: pointer;
+  z-index: 1;
+}
+
+.button:focus-visible {
+  outline: 2px solid var(--gray-900);
+  z-index: 1;
+}
+
+.icon {
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.button[data-pressed] {
+  background-color: #fefefe;
+  color: var(--gray-text-2);
+}
diff --git a/docs/src/app/experiments/toggle.tsx b/docs/src/app/experiments/toggle.tsx
deleted file mode 100644
index 08ff006ac4..0000000000
--- a/docs/src/app/experiments/toggle.tsx
+++ /dev/null
@@ -1,30 +0,0 @@
-'use client';
-import * as React from 'react';
-import { ToggleButton } from '@base_ui/react/ToggleButton';
-
-export default function ToggleButtonDemo() {
-  const [pressed, setPressed] = React.useState(true);
-  return (
-    <div>
-      <ToggleButton
-        pressed={pressed}
-        onPressedChange={setPressed}
-        // className={classes.button}
-      >
-        <svg
-          xmlns="http://www.w3.org/2000/svg"
-          width="24"
-          height="24"
-          viewBox="0 0 24 24"
-          fill="none"
-          stroke="currentColor"
-          strokeWidth={2}
-          strokeLinecap="round"
-          strokeLinejoin="round"
-        >
-          <path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z" />
-        </svg>
-      </ToggleButton>
-    </div>
-  );
-}
diff --git a/packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.tsx b/packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.tsx
index 5a8a37800e..47ae64c2d4 100644
--- a/packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.tsx
+++ b/packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.tsx
@@ -30,6 +30,8 @@ const ToggleButtonRoot = React.forwardRef(function ToggleButtonRoot(
     onPressedChange,
     className,
     render,
+    type,
+    form,
     ...otherProps
   } = props;
 
@@ -120,6 +122,10 @@ ToggleButtonRoot.propTypes /* remove-proptypes */ = {
    * @default false
    */
   disabled: PropTypes.bool,
+  /**
+   * @ignore
+   */
+  form: PropTypes.string,
   /**
    * Callback fired when the pressed state is changed.
    *
@@ -137,4 +143,8 @@ ToggleButtonRoot.propTypes /* remove-proptypes */ = {
    * A function to customize rendering of the component.
    */
   render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  /**
+   * @ignore
+   */
+  type: PropTypes.oneOf(['button', 'reset', 'submit']),
 } as any;
diff --git a/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx b/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx
new file mode 100644
index 0000000000..843d71837e
--- /dev/null
+++ b/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx
@@ -0,0 +1,94 @@
+import * as React from 'react';
+import { expect } from 'chai';
+import { spy } from 'sinon';
+import { act } from '@mui/internal-test-utils';
+import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import { createRenderer, describeConformance } from '#test-utils';
+import { NOOP } from '../../utils/noop';
+import { ToggleButtonGroupRootContext } from '../Root/ToggleButtonGroupRootContext';
+
+const contextValue: ToggleButtonGroupRootContext = {
+  value: [],
+  setGroupValue: NOOP,
+  disabled: false,
+};
+
+describe('<ToggleButtonGroup.Item />', () => {
+  const { render } = createRenderer();
+
+  describeConformance(<ToggleButtonGroup.Item value="bookmark" />, () => ({
+    refInstanceof: window.HTMLButtonElement,
+    render: (node) =>
+      render(
+        <ToggleButtonGroupRootContext.Provider value={contextValue}>
+          {node}
+        </ToggleButtonGroupRootContext.Provider>,
+      ),
+  }));
+
+  describe('prop: onPressedChange', () => {
+    it('fires when an Item is clicked', async () => {
+      const onPressedChange = spy();
+
+      const { getAllByRole, user } = await render(
+        <ToggleButtonGroup.Root>
+          <ToggleButtonGroup.Item value="one" onPressedChange={onPressedChange} />
+          <ToggleButtonGroup.Item value="two" />
+        </ToggleButtonGroup.Root>,
+      );
+
+      const [button1] = getAllByRole('button');
+
+      expect(onPressedChange.callCount).to.equal(0);
+
+      await user.pointer({ keys: '[MouseLeft]', target: button1 });
+
+      expect(onPressedChange.callCount).to.equal(1);
+      expect(onPressedChange.args[0][0]).to.equal(true);
+
+      await user.pointer({ keys: '[MouseLeft]', target: button1 });
+
+      expect(onPressedChange.callCount).to.equal(2);
+      expect(onPressedChange.args[1][0]).to.equal(false);
+    });
+
+    describe('keypresses', () => {
+      ['Enter', 'Space'].forEach((key) => {
+        it(`fires when when the ${key} is pressed`, async function test(t = {}) {
+          if (/jsdom/.test(window.navigator.userAgent)) {
+            // @ts-expect-error to support mocha and vitest
+            // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+            this?.skip?.() || t?.skip();
+          }
+
+          const onPressedChange = spy();
+
+          const { getAllByRole, user } = await render(
+            <ToggleButtonGroup.Root>
+              <ToggleButtonGroup.Item value="one" onPressedChange={onPressedChange} />
+              <ToggleButtonGroup.Item value="two" />
+            </ToggleButtonGroup.Root>,
+          );
+
+          const [button1] = getAllByRole('button');
+
+          expect(onPressedChange.callCount).to.equal(0);
+
+          await act(async () => {
+            button1.focus();
+          });
+
+          await user.keyboard(`[${key}]`);
+
+          expect(onPressedChange.callCount).to.equal(1);
+          expect(onPressedChange.args[0][0]).to.equal(true);
+
+          await user.keyboard(`[${key}]`);
+
+          expect(onPressedChange.callCount).to.equal(2);
+          expect(onPressedChange.args[1][0]).to.equal(false);
+        });
+      });
+    });
+  });
+});
diff --git a/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx b/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx
new file mode 100644
index 0000000000..4a3efc58e6
--- /dev/null
+++ b/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx
@@ -0,0 +1,144 @@
+'use client';
+import * as React from 'react';
+import PropTypes from 'prop-types';
+import { useComponentRenderer } from '../../utils/useComponentRenderer';
+import type { BaseUIComponentProps } from '../../utils/types';
+import { useToggleButtonGroupRootContext } from '../Root/ToggleButtonGroupRootContext';
+import { useToggleButtonGroupItem } from './useToggleButtonGroupItem';
+
+const customStyleHookMapping = {
+  disabled: () => null,
+};
+/**
+ *
+ * Demos:
+ *
+ * - [ToggleButtonGroup](https://base-ui.netlify.app/components/react-toggle-button-group/)
+ *
+ * API:
+ *
+ * - [ToggleButtonGroupItem API](https://base-ui.netlify.app/components/react-toggle-button-group/#api-reference-ToggleButtonGroupItem)
+ */
+const ToggleButtonGroupItem = React.forwardRef(function ToggleButtonGroupItem(
+  props: ToggleButtonGroupItem.Props,
+  forwardedRef: React.ForwardedRef<HTMLButtonElement>,
+) {
+  const {
+    value,
+    disabled: disabledProp,
+    onPressedChange,
+    className,
+    render,
+    type, // cannot change button type
+    form, // never participates in form validation
+    ...otherProps
+  } = props;
+
+  const {
+    value: groupValue,
+    setGroupValue,
+    disabled: groupDisabled,
+  } = useToggleButtonGroupRootContext();
+
+  const { disabled, pressed, getRootProps } = useToggleButtonGroupItem({
+    value,
+    groupValue,
+    setGroupValue,
+    disabled: groupDisabled || disabledProp,
+    onPressedChange,
+    itemRef: forwardedRef,
+  });
+
+  const ownerState: ToggleButtonGroupItem.OwnerState = React.useMemo(
+    () => ({
+      disabled,
+      pressed,
+    }),
+    [disabled, pressed],
+  );
+
+  const { renderElement } = useComponentRenderer({
+    propGetter: getRootProps,
+    render: render ?? 'button',
+    ref: forwardedRef,
+    ownerState,
+    className,
+    customStyleHookMapping,
+    extraProps: otherProps,
+  });
+
+  return renderElement();
+});
+
+export { ToggleButtonGroupItem };
+
+export namespace ToggleButtonGroupItem {
+  export interface OwnerState {
+    pressed: boolean;
+    disabled: boolean;
+  }
+
+  export interface Props
+    extends Pick<useToggleButtonGroupItem.Parameters, 'value' | 'onPressedChange'>,
+      Omit<BaseUIComponentProps<'button', OwnerState>, 'value'> {
+    /**
+     * The label for the toggle button.
+     */
+    'aria-label'?: React.AriaAttributes['aria-label'];
+    /**
+     * An id or space-separated list of ids of elements that label the toggle button.
+     */
+    'aria-labelledby'?: React.AriaAttributes['aria-labelledby'];
+  }
+}
+
+ToggleButtonGroupItem.propTypes /* remove-proptypes */ = {
+  // ┌────────────────────────────── Warning ──────────────────────────────┐
+  // │ These PropTypes are generated from the TypeScript type definitions. │
+  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
+  // └─────────────────────────────────────────────────────────────────────┘
+  /**
+   * The label for the toggle button.
+   */
+  'aria-label': PropTypes.string,
+  /**
+   * An id or space-separated list of ids of elements that label the toggle button.
+   */
+  'aria-labelledby': PropTypes.string,
+  /**
+   * @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
+   */
+  form: PropTypes.string,
+  /**
+   * Callback fired when the pressed state is changed.
+   *
+   * @param {boolean} pressed The new pressed state.
+   * @param {Event} event The event source of the callback.
+   */
+  onPressedChange: PropTypes.func,
+  /**
+   * A function to customize rendering of the component.
+   */
+  render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  /**
+   * @ignore
+   */
+  type: PropTypes.oneOf(['button', 'reset', 'submit']),
+  /**
+   * A unique value that identifies the component when used
+   * inside a ToggleButtonGroup
+   */
+  value: PropTypes.any.isRequired,
+} as any;
diff --git a/packages/mui-base/src/ToggleButtonGroup/Item/useToggleButtonGroupItem.ts b/packages/mui-base/src/ToggleButtonGroup/Item/useToggleButtonGroupItem.ts
new file mode 100644
index 0000000000..9e4938f5b7
--- /dev/null
+++ b/packages/mui-base/src/ToggleButtonGroup/Item/useToggleButtonGroupItem.ts
@@ -0,0 +1,76 @@
+'use client';
+import * as React from 'react';
+import { mergeReactProps } from '../../utils/mergeReactProps';
+import { GenericHTMLProps } from '../../utils/types';
+import { useEventCallback } from '../../utils/useEventCallback';
+import { useToggleButtonRoot } from '../../ToggleButton/Root/useToggleButtonRoot';
+
+export function useToggleButtonGroupItem(
+  parameters: useToggleButtonGroupItem.Parameters,
+): useToggleButtonGroupItem.ReturnValue {
+  const {
+    value,
+    groupValue,
+    setGroupValue,
+    disabled: disabledParam,
+    onPressedChange,
+    itemRef: externalRef,
+  } = parameters;
+
+  const isPressed = groupValue?.indexOf(value) > -1;
+
+  const handlePressedChange = useEventCallback((nextPressed: boolean, event: Event) => {
+    setGroupValue(value, nextPressed, event);
+    onPressedChange?.(nextPressed, event);
+  });
+
+  const {
+    pressed,
+    disabled,
+    getRootProps: getToggleButtonProps,
+  } = useToggleButtonRoot({
+    pressed: isPressed,
+    disabled: disabledParam,
+    onPressedChange: handlePressedChange,
+    buttonRef: externalRef,
+  });
+
+  const getRootProps = React.useCallback(
+    (externalProps?: GenericHTMLProps): GenericHTMLProps => {
+      return mergeReactProps(externalProps, {}, getToggleButtonProps());
+    },
+    [getToggleButtonProps],
+  );
+
+  return React.useMemo(
+    () => ({
+      getRootProps,
+      disabled,
+      pressed,
+    }),
+    [getRootProps, disabled, pressed],
+  );
+}
+
+export namespace useToggleButtonGroupItem {
+  export interface Parameters
+    extends Pick<useToggleButtonRoot.Parameters, 'disabled' | 'onPressedChange'> {
+    itemRef?: React.Ref<HTMLElement>;
+    /**
+     * A unique value that identifies the component when used
+     * inside a ToggleButtonGroup
+     */
+    value: unknown;
+    /**
+     * The value of the ToggleButtonGroup represented by an array of values
+     * of the items that are pressed
+     */
+    groupValue: unknown[];
+    /**
+     *
+     */
+    setGroupValue: (newValue: unknown, nextPressed: boolean, event: Event) => void;
+  }
+
+  export interface ReturnValue extends useToggleButtonRoot.ReturnValue {}
+}
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
new file mode 100644
index 0000000000..f3b28e49ae
--- /dev/null
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
@@ -0,0 +1,269 @@
+import * as React from 'react';
+import { expect } from 'chai';
+import { spy } from 'sinon';
+import { act, flushMicrotasks } from '@mui/internal-test-utils';
+import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import { createRenderer, describeConformance } from '#test-utils';
+
+describe('<ToggleButtonGroup.Root />', () => {
+  const { render } = createRenderer();
+
+  describeConformance(<ToggleButtonGroup.Root />, () => ({
+    refInstanceof: window.HTMLDivElement,
+    render,
+  }));
+
+  it('renders a `group`', async () => {
+    const { queryByRole } = await render(<ToggleButtonGroup.Root aria-label="My Toggle Group" />);
+
+    expect(queryByRole('group', { name: 'My Toggle Group' })).not.to.equal(null);
+  });
+
+  describe('uncontrolled', () => {
+    it('pressed state', async function test(t = {}) {
+      if (/jsdom/.test(window.navigator.userAgent)) {
+        // @ts-expect-error to support mocha and vitest
+        // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+        this?.skip?.() || t?.skip();
+      }
+
+      const { getAllByRole, user } = await render(
+        <ToggleButtonGroup.Root>
+          <ToggleButtonGroup.Item value="one" />
+          <ToggleButtonGroup.Item value="two" />
+        </ToggleButtonGroup.Root>,
+      );
+
+      const [button1, button2] = getAllByRole('button');
+
+      expect(button1).to.have.attribute('aria-pressed', 'false');
+      expect(button2).to.have.attribute('aria-pressed', 'false');
+
+      await user.pointer({ keys: '[MouseLeft]', target: button1 });
+
+      expect(button1).to.have.attribute('aria-pressed', 'true');
+      expect(button1).to.have.attribute('data-pressed');
+      expect(button2).to.have.attribute('aria-pressed', 'false');
+
+      await user.pointer({ keys: '[MouseLeft]', target: button2 });
+
+      expect(button2).to.have.attribute('aria-pressed', 'true');
+      expect(button2).to.have.attribute('data-pressed');
+      expect(button1).to.have.attribute('aria-pressed', 'false');
+    });
+
+    it('prop: defaultValue', async () => {
+      const { getAllByRole, user } = await render(
+        <ToggleButtonGroup.Root defaultValue={['two']}>
+          <ToggleButtonGroup.Item value="one" />
+          <ToggleButtonGroup.Item value="two" />
+        </ToggleButtonGroup.Root>,
+      );
+
+      const [button1, button2] = getAllByRole('button');
+
+      expect(button2).to.have.attribute('aria-pressed', 'true');
+      expect(button2).to.have.attribute('data-pressed');
+      expect(button1).to.have.attribute('aria-pressed', 'false');
+
+      await user.pointer({ keys: '[MouseLeft]', target: button1 });
+
+      expect(button1).to.have.attribute('aria-pressed', 'true');
+      expect(button1).to.have.attribute('data-pressed');
+      expect(button2).to.have.attribute('aria-pressed', 'false');
+    });
+  });
+
+  describe('controlled', () => {
+    it('pressed state', async () => {
+      const { getAllByRole, setProps } = await render(
+        <ToggleButtonGroup.Root value={['two']}>
+          <ToggleButtonGroup.Item value="one" />
+          <ToggleButtonGroup.Item value="two" />
+        </ToggleButtonGroup.Root>,
+      );
+
+      const [button1, button2] = getAllByRole('button');
+
+      expect(button1).to.have.attribute('aria-pressed', 'false');
+      expect(button2).to.have.attribute('aria-pressed', 'true');
+      expect(button2).to.have.attribute('data-pressed');
+
+      setProps({ value: ['one'] });
+      await flushMicrotasks();
+
+      expect(button1).to.have.attribute('aria-pressed', 'true');
+      expect(button1).to.have.attribute('data-pressed');
+      expect(button2).to.have.attribute('aria-pressed', 'false');
+
+      setProps({ value: ['two'] });
+      await flushMicrotasks();
+
+      expect(button2).to.have.attribute('aria-pressed', 'true');
+      expect(button2).to.have.attribute('data-pressed');
+      expect(button1).to.have.attribute('aria-pressed', 'false');
+    });
+
+    it('prop: value', async () => {
+      const { getAllByRole, setProps } = await render(
+        <ToggleButtonGroup.Root value={['two']}>
+          <ToggleButtonGroup.Item value="one" />
+          <ToggleButtonGroup.Item value="two" />
+        </ToggleButtonGroup.Root>,
+      );
+
+      const [button1, button2] = getAllByRole('button');
+
+      expect(button2).to.have.attribute('aria-pressed', 'true');
+      expect(button2).to.have.attribute('data-pressed');
+      expect(button1).to.have.attribute('aria-pressed', 'false');
+
+      setProps({ value: ['one'] });
+      await flushMicrotasks();
+
+      expect(button1).to.have.attribute('aria-pressed', 'true');
+      expect(button1).to.have.attribute('data-pressed');
+      expect(button2).to.have.attribute('aria-pressed', 'false');
+    });
+  });
+
+  describe('prop: disabled', () => {
+    it('can disable the whole group', async () => {
+      const { getAllByRole } = await render(
+        <ToggleButtonGroup.Root disabled>
+          <ToggleButtonGroup.Item value="one" />
+          <ToggleButtonGroup.Item value="two" />
+        </ToggleButtonGroup.Root>,
+      );
+
+      const [button1, button2] = getAllByRole('button');
+
+      expect(button1).to.have.attribute('disabled');
+      expect(button2).to.have.attribute('disabled');
+    });
+
+    it('can disable individual items', async () => {
+      const { getAllByRole } = await render(
+        <ToggleButtonGroup.Root>
+          <ToggleButtonGroup.Item value="one" />
+          <ToggleButtonGroup.Item value="two" disabled />
+        </ToggleButtonGroup.Root>,
+      );
+
+      const [button1, button2] = getAllByRole('button');
+
+      expect(button1).to.not.have.attribute('disabled');
+      expect(button2).to.have.attribute('disabled');
+    });
+  });
+
+  describe('prop: toggleMultiple', () => {
+    it('multiple items can be pressed when true', async () => {
+      const { getAllByRole, user } = await render(
+        <ToggleButtonGroup.Root toggleMultiple defaultValue={['one']}>
+          <ToggleButtonGroup.Item value="one" />
+          <ToggleButtonGroup.Item value="two" />
+        </ToggleButtonGroup.Root>,
+      );
+
+      const [button1, button2] = getAllByRole('button');
+
+      expect(button1).to.have.attribute('aria-pressed', 'true');
+      expect(button2).to.have.attribute('aria-pressed', 'false');
+
+      await user.pointer({ keys: '[MouseLeft]', target: button2 });
+
+      expect(button1).to.have.attribute('aria-pressed', 'true');
+      expect(button2).to.have.attribute('aria-pressed', 'true');
+    });
+
+    it('only one item can be pressed when false', async () => {
+      const { getAllByRole, user } = await render(
+        <ToggleButtonGroup.Root toggleMultiple={false} defaultValue={['one']}>
+          <ToggleButtonGroup.Item value="one" />
+          <ToggleButtonGroup.Item value="two" />
+        </ToggleButtonGroup.Root>,
+      );
+
+      const [button1, button2] = getAllByRole('button');
+
+      expect(button1).to.have.attribute('aria-pressed', 'true');
+      expect(button2).to.have.attribute('aria-pressed', 'false');
+
+      await user.pointer({ keys: '[MouseLeft]', target: button2 });
+
+      expect(button1).to.have.attribute('aria-pressed', 'false');
+      expect(button2).to.have.attribute('aria-pressed', 'true');
+    });
+  });
+
+  describe('prop: onValueChange', () => {
+    it('fires when an Item is clicked', async () => {
+      const onValueChange = spy();
+
+      const { getAllByRole, user } = await render(
+        <ToggleButtonGroup.Root onValueChange={onValueChange}>
+          <ToggleButtonGroup.Item value="one" />
+          <ToggleButtonGroup.Item value="two" />
+        </ToggleButtonGroup.Root>,
+      );
+
+      const [button1, button2] = getAllByRole('button');
+
+      expect(onValueChange.callCount).to.equal(0);
+
+      await user.pointer({ keys: '[MouseLeft]', target: button1 });
+
+      expect(onValueChange.callCount).to.equal(1);
+      expect(onValueChange.args[0][0]).to.deep.equal(['one']);
+
+      await user.pointer({ keys: '[MouseLeft]', target: button2 });
+
+      expect(onValueChange.callCount).to.equal(2);
+      expect(onValueChange.args[1][0]).to.deep.equal(['two']);
+    });
+
+    describe('keypresses', () => {
+      ['Enter', 'Space'].forEach((key) => {
+        it(`fires when when the ${key} is pressed`, async function test(t = {}) {
+          if (/jsdom/.test(window.navigator.userAgent)) {
+            // @ts-expect-error to support mocha and vitest
+            // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+            this?.skip?.() || t?.skip();
+          }
+
+          const onValueChange = spy();
+
+          const { getAllByRole, user } = await render(
+            <ToggleButtonGroup.Root onValueChange={onValueChange}>
+              <ToggleButtonGroup.Item value="one" />
+              <ToggleButtonGroup.Item value="two" />
+            </ToggleButtonGroup.Root>,
+          );
+
+          const [button1, button2] = getAllByRole('button');
+
+          expect(onValueChange.callCount).to.equal(0);
+
+          await act(async () => {
+            button1.focus();
+          });
+
+          await user.keyboard(`[${key}]`);
+
+          expect(onValueChange.callCount).to.equal(1);
+          expect(onValueChange.args[0][0]).to.deep.equal(['one']);
+
+          await act(async () => {
+            button2.focus();
+          });
+
+          await user.keyboard(`[${key}]`);
+
+          expect(onValueChange.callCount).to.equal(2);
+          expect(onValueChange.args[1][0]).to.deep.equal(['two']);
+        });
+      });
+    });
+  });
+});
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
new file mode 100644
index 0000000000..21fa7b590f
--- /dev/null
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
@@ -0,0 +1,159 @@
+'use client';
+import * as React from 'react';
+import PropTypes from 'prop-types';
+import { useComponentRenderer } from '../../utils/useComponentRenderer';
+import type { BaseUIComponentProps } from '../../utils/types';
+import {
+  useToggleButtonGroupRoot,
+  type UseToggleButtonGroupRoot,
+} from './useToggleButtonGroupRoot';
+import { ToggleButtonGroupRootContext } from './ToggleButtonGroupRootContext';
+
+const customStyleHookMapping = {
+  multiple(value: boolean) {
+    if (value) {
+      return { 'data-multiple': '' } as Record<string, string>;
+    }
+    return null;
+  },
+};
+/**
+ *
+ * Demos:
+ *
+ * - [ToggleButtonGroup](https://base-ui.netlify.app/components/react-toggle-button-group/)
+ *
+ * API:
+ *
+ * - [ToggleButtonGroupRoot API](https://base-ui.netlify.app/components/react-toggle-button-group/#api-reference-ToggleButtonGroupRoot)
+ */
+const ToggleButtonGroupRoot = React.forwardRef(function ToggleButtonGroupRoot(
+  props: ToggleButtonGroupRoot.Props,
+  forwardedRef: React.ForwardedRef<HTMLDivElement>,
+) {
+  const {
+    value: valueProp,
+    defaultValue: defaultValueProp,
+    direction,
+    disabled: disabledProp,
+    toggleMultiple = false,
+    onValueChange,
+    className,
+    render,
+    ...otherProps
+  } = props;
+
+  const defaultValue = React.useMemo(() => {
+    if (valueProp === undefined) {
+      return defaultValueProp ?? [];
+    }
+
+    return undefined;
+  }, [valueProp, defaultValueProp]);
+
+  const { getRootProps, disabled, setGroupValue, value } = useToggleButtonGroupRoot({
+    value: valueProp,
+    defaultValue,
+    direction,
+    disabled: disabledProp,
+    toggleMultiple,
+    onValueChange,
+  });
+
+  const ownerState: ToggleButtonGroupRoot.OwnerState = React.useMemo(
+    () => ({ disabled, multiple: toggleMultiple }),
+    [disabled, toggleMultiple],
+  );
+
+  const contextValue: ToggleButtonGroupRootContext = React.useMemo(
+    () => ({
+      disabled,
+      setGroupValue,
+      value,
+    }),
+    [disabled, value, setGroupValue],
+  );
+
+  const { renderElement } = useComponentRenderer({
+    propGetter: getRootProps,
+    render: render ?? 'div',
+    ref: forwardedRef,
+    ownerState,
+    className,
+    customStyleHookMapping,
+    extraProps: otherProps,
+  });
+
+  return (
+    <ToggleButtonGroupRootContext.Provider value={contextValue}>
+      {renderElement()}
+    </ToggleButtonGroupRootContext.Provider>
+  );
+});
+
+export { ToggleButtonGroupRoot };
+
+export namespace ToggleButtonGroupRoot {
+  export interface OwnerState {
+    disabled: boolean;
+    multiple: boolean;
+  }
+
+  export interface Props
+    extends Pick<
+        UseToggleButtonGroupRoot.Parameters,
+        'value' | 'defaultValue' | 'onValueChange' | 'disabled' | 'toggleMultiple' | 'direction'
+      >,
+      Omit<BaseUIComponentProps<'div', OwnerState>, 'defaultValue'> {
+    /**
+     * @default false
+     */
+    disabled?: boolean;
+  }
+}
+
+ToggleButtonGroupRoot.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
+   */
+  defaultValue: PropTypes.array,
+  /**
+   * Text direction
+   * @default 'ltr'
+   */
+  direction: PropTypes.oneOf(['ltr', 'rtl']),
+  /**
+   * @default false
+   */
+  disabled: PropTypes.bool,
+  /**
+   * @ignore
+   */
+  onValueChange: PropTypes.func,
+  /**
+   * A function to customize rendering of the component.
+   */
+  render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  /**
+   * When `false` only one ToggleButton in the group can be pressed.
+   * When a ToggleButton is pressed, the others in the group will become unpressed
+   * @default false
+   */
+  toggleMultiple: PropTypes.bool,
+  /**
+   * @ignore
+   */
+  value: PropTypes.array,
+} as any;
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRootContext.ts b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRootContext.ts
new file mode 100644
index 0000000000..8b6bb43cab
--- /dev/null
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRootContext.ts
@@ -0,0 +1,27 @@
+'use client';
+import * as React from 'react';
+
+export interface ToggleButtonGroupRootContext {
+  value: unknown[];
+  setGroupValue: (newValue: unknown, nextPressed: boolean, event: Event) => void;
+  disabled: boolean;
+}
+
+export const ToggleButtonGroupRootContext = React.createContext<
+  ToggleButtonGroupRootContext | undefined
+>(undefined);
+
+if (process.env.NODE_ENV !== 'production') {
+  ToggleButtonGroupRootContext.displayName = 'ToggleButtonGroupRootContext';
+}
+
+export function useToggleButtonGroupRootContext() {
+  const context = React.useContext(ToggleButtonGroupRootContext);
+  if (context === undefined) {
+    throw new Error(
+      'Base UI: ToggleButtonGroupRootContext is missing. ToggleButtonGroup parts must be placed within <ToggleButtonGroup.Root>.',
+    );
+  }
+
+  return context;
+}
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts b/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
new file mode 100644
index 0000000000..a033a962ec
--- /dev/null
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
@@ -0,0 +1,109 @@
+'use client';
+import * as React from 'react';
+import { mergeReactProps } from '../../utils/mergeReactProps';
+import { useControlled } from '../../utils/useControlled';
+import { useEventCallback } from '../../utils/useEventCallback';
+import type { GenericHTMLProps } from '../../utils/types';
+
+export function useToggleButtonGroupRoot(
+  parameters: UseToggleButtonGroupRoot.Parameters,
+): UseToggleButtonGroupRoot.ReturnValue {
+  const {
+    value,
+    defaultValue,
+    direction = 'ltr',
+    disabled = false,
+    onValueChange,
+    toggleMultiple = false,
+  } = parameters;
+
+  const [groupValue, setValueState] = useControlled({
+    controlled: value,
+    default: defaultValue,
+    name: 'ToggleButtonGroup',
+    state: 'value',
+  });
+
+  const setGroupValue = useEventCallback(
+    (newValue: unknown, nextPressed: boolean, event: Event) => {
+      let newGroupValue: unknown[] | undefined;
+      if (toggleMultiple) {
+        newGroupValue = groupValue.slice();
+        if (nextPressed) {
+          newGroupValue.push(newValue);
+        } else {
+          newGroupValue.splice(groupValue.indexOf(newValue), 1);
+        }
+      } else {
+        newGroupValue = nextPressed ? [newValue] : [];
+      }
+      if (Array.isArray(newGroupValue)) {
+        setValueState(newGroupValue);
+        onValueChange?.(newGroupValue, event);
+      }
+    },
+  );
+
+  const getRootProps = React.useCallback(
+    (externalProps = {}) =>
+      mergeReactProps<'div'>(externalProps, {
+        role: 'group',
+        dir: direction,
+      }),
+    [direction],
+  );
+
+  return React.useMemo(
+    () => ({
+      getRootProps,
+      disabled,
+      setGroupValue,
+      value: groupValue,
+    }),
+    [getRootProps, disabled, groupValue, setGroupValue],
+  );
+}
+
+export namespace UseToggleButtonGroupRoot {
+  export type Direction = 'ltr' | 'rtl';
+
+  export interface Parameters {
+    value?: unknown[];
+    defaultValue?: unknown[];
+    onValueChange?: (groupValue: unknown[], event: Event) => void;
+    /**
+     * When `true` the component is disabled
+     * @false
+     */
+    disabled?: boolean;
+    /**
+     * When `false` only one ToggleButton in the group can be pressed.
+     * When a ToggleButton is pressed, the others in the group will become unpressed
+     * @default false
+     */
+    toggleMultiple?: boolean;
+    /**
+     * Text direction
+     * @default 'ltr'
+     */
+    direction?: Direction;
+  }
+
+  export interface ReturnValue {
+    getRootProps: (externalProps?: GenericHTMLProps) => GenericHTMLProps;
+    /**
+     * When `true` the component is disabled
+     * @false
+     */
+    disabled: boolean;
+    /**
+     *
+     */
+    setGroupValue: (newValue: unknown, nextPressed: boolean, event: Event) => void;
+    /**
+     * The value of the ToggleButtonGroup represented by an array of values
+     * of the items that are pressed
+     */
+    value: unknown[];
+  }
+}
diff --git a/packages/mui-base/src/ToggleButtonGroup/index.parts.ts b/packages/mui-base/src/ToggleButtonGroup/index.parts.ts
new file mode 100644
index 0000000000..5c0e559a33
--- /dev/null
+++ b/packages/mui-base/src/ToggleButtonGroup/index.parts.ts
@@ -0,0 +1,2 @@
+export { ToggleButtonGroupRoot as Root } from './Root/ToggleButtonGroupRoot';
+export { ToggleButtonGroupItem as Item } from './Item/ToggleButtonGroupItem';
diff --git a/packages/mui-base/src/ToggleButtonGroup/index.ts b/packages/mui-base/src/ToggleButtonGroup/index.ts
new file mode 100644
index 0000000000..6466ce449f
--- /dev/null
+++ b/packages/mui-base/src/ToggleButtonGroup/index.ts
@@ -0,0 +1 @@
+export * as ToggleButtonGroup from './index.parts';
diff --git a/packages/mui-base/src/index.ts b/packages/mui-base/src/index.ts
index ef93f5beb2..ac87904c84 100644
--- a/packages/mui-base/src/index.ts
+++ b/packages/mui-base/src/index.ts
@@ -21,4 +21,5 @@ export * from './Switch';
 export * from './Tabs';
 export * from './TextInput';
 export * from './ToggleButton';
+export * from './ToggleButtonGroup';
 export * from './Tooltip';

From 5d3ceab2d29f8155d7ea4a38ece3a9dd9fe1c464 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Fri, 25 Oct 2024 16:29:44 +0800
Subject: [PATCH 04/19] Add tests for composite

---
 .../src/Composite/Root/CompositeRoot.test.tsx | 100 ++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx

diff --git a/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx b/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx
new file mode 100644
index 0000000000..c583f48ebb
--- /dev/null
+++ b/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx
@@ -0,0 +1,100 @@
+import * as React from 'react';
+import { expect } from 'chai';
+import { act, createRenderer, fireEvent, flushMicrotasks } from '@mui/internal-test-utils';
+import { CompositeItem } from '../Item/CompositeItem';
+import { CompositeRoot } from './CompositeRoot';
+
+describe('Composite', () => {
+  const { render } = createRenderer();
+
+  describe('list', () => {
+    it('controlled mode', async () => {
+      function App() {
+        const [activeIndex, setActiveIndex] = React.useState(0);
+        return (
+          <CompositeRoot activeIndex={activeIndex} onActiveIndexChange={setActiveIndex}>
+            <CompositeItem data-testid="1">1</CompositeItem>
+            <CompositeItem data-testid="2">2</CompositeItem>
+            <CompositeItem data-testid="3">3</CompositeItem>
+          </CompositeRoot>
+        );
+      }
+
+      const { getByTestId } = render(<App />);
+
+      const item1 = getByTestId('1');
+      const item2 = getByTestId('2');
+      const item3 = getByTestId('3');
+
+      act(() => item1.focus());
+
+      expect(item1).to.have.attribute('data-active');
+
+      fireEvent.keyDown(item1, { key: 'ArrowDown' });
+      await flushMicrotasks();
+      expect(item2).to.have.attribute('data-active');
+      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('tabindex', '0');
+      expect(item3).toHaveFocus();
+
+      fireEvent.keyDown(item3, { key: 'ArrowUp' });
+      await flushMicrotasks();
+      expect(item2).to.have.attribute('data-active');
+      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('tabindex', '0');
+      expect(item1).toHaveFocus();
+    });
+
+    it('uncontrolled mode', async () => {
+      const { getByTestId } = render(
+        <CompositeRoot>
+          <CompositeItem data-testid="1">1</CompositeItem>
+          <CompositeItem data-testid="2">2</CompositeItem>
+          <CompositeItem data-testid="3">3</CompositeItem>
+        </CompositeRoot>,
+      );
+
+      const item1 = getByTestId('1');
+      const item2 = getByTestId('2');
+      const item3 = getByTestId('3');
+
+      act(() => item1.focus());
+
+      expect(item1).to.have.attribute('data-active');
+
+      fireEvent.keyDown(item1, { key: 'ArrowDown' });
+      await flushMicrotasks();
+      expect(item2).to.have.attribute('data-active');
+      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('tabindex', '0');
+      expect(item3).toHaveFocus();
+
+      fireEvent.keyDown(item3, { key: 'ArrowUp' });
+      await flushMicrotasks();
+      expect(item2).to.have.attribute('data-active');
+      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('tabindex', '0');
+      expect(item1).toHaveFocus();
+    });
+  });
+});

From 405c854ea3a6a086a83ecfcf8a82fed87a5e9f59 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 5 Nov 2024 15:40:15 +0800
Subject: [PATCH 05/19] Add isRtl prop to CompositeRoot for lists only

---
 .../src/Composite/Root/CompositeRoot.test.tsx | 166 ++++++++++++++++++
 .../src/Composite/Root/CompositeRoot.tsx      |   6 +
 .../src/Composite/Root/useCompositeRoot.ts    |  36 ++--
 3 files changed, 198 insertions(+), 10 deletions(-)

diff --git a/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx b/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx
index c583f48ebb..c257c91d1e 100644
--- a/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx
+++ b/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx
@@ -96,5 +96,171 @@ describe('Composite', () => {
       expect(item1).to.have.attribute('tabindex', '0');
       expect(item1).toHaveFocus();
     });
+
+    describe('prop: isRtl', () => {
+      it('horizontal orientation', async () => {
+        const { getByTestId } = render(
+          <CompositeRoot isRtl orientation="horizontal">
+            <CompositeItem data-testid="1">1</CompositeItem>
+            <CompositeItem data-testid="2">2</CompositeItem>
+            <CompositeItem data-testid="3">3</CompositeItem>
+          </CompositeRoot>,
+        );
+
+        const item1 = getByTestId('1');
+        const item2 = getByTestId('2');
+        const item3 = getByTestId('3');
+
+        act(() => item1.focus());
+
+        expect(item1).to.have.attribute('data-active');
+
+        fireEvent.keyDown(item1, { key: 'ArrowDown' });
+        await flushMicrotasks();
+        expect(item1).to.have.attribute('data-active');
+
+        fireEvent.keyDown(item1, { key: 'ArrowLeft' });
+        await flushMicrotasks();
+        expect(item2).to.have.attribute('data-active');
+        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('tabindex', '0');
+        expect(item3).toHaveFocus();
+
+        fireEvent.keyDown(item3, { key: 'ArrowRight' });
+        await flushMicrotasks();
+        expect(item2).to.have.attribute('data-active');
+        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('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('tabindex', '0');
+        expect(item3).toHaveFocus();
+      });
+
+      it('both horizontal and vertical orientation', async () => {
+        const { getByTestId } = render(
+          <CompositeRoot isRtl orientation="both">
+            <CompositeItem data-testid="1">1</CompositeItem>
+            <CompositeItem data-testid="2">2</CompositeItem>
+            <CompositeItem data-testid="3">3</CompositeItem>
+          </CompositeRoot>,
+        );
+
+        const item1 = getByTestId('1');
+        const item2 = getByTestId('2');
+        const item3 = getByTestId('3');
+
+        act(() => item1.focus());
+
+        expect(item1).to.have.attribute('data-active');
+
+        fireEvent.keyDown(item1, { key: 'ArrowLeft' });
+        await flushMicrotasks();
+        expect(item2).to.have.attribute('data-active');
+        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('tabindex', '0');
+        expect(item3).toHaveFocus();
+
+        fireEvent.keyDown(item3, { key: 'ArrowRight' });
+        await flushMicrotasks();
+        expect(item2).to.have.attribute('data-active');
+        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('tabindex', '0');
+        expect(item1).toHaveFocus();
+
+        fireEvent.keyDown(item1, { key: 'ArrowDown' });
+        await flushMicrotasks();
+        expect(item2).to.have.attribute('data-active');
+        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('tabindex', '0');
+        expect(item3).toHaveFocus();
+      });
+    });
+  });
+
+  describe('grid', () => {
+    it('uniform 1x1 items', async () => {
+      function App() {
+        return (
+          // 1 to 9 numpad
+          <CompositeRoot cols={3}>
+            {['1', '2', '3', '4', '5', '6', '7', '8', '9'].map((i) => (
+              <CompositeItem key={i} data-testid={i}>
+                {i}
+              </CompositeItem>
+            ))}
+          </CompositeRoot>
+        );
+      }
+
+      const { getByTestId } = await render(<App />);
+
+      act(() => getByTestId('1').focus());
+      expect(getByTestId('1')).to.have.attribute('data-active');
+
+      fireEvent.keyDown(getByTestId('1'), { key: 'ArrowDown' });
+      await flushMicrotasks();
+      expect(getByTestId('4')).to.have.attribute('data-active');
+      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('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('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('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('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('tabindex', '0');
+    });
   });
 });
diff --git a/packages/mui-base/src/Composite/Root/CompositeRoot.tsx b/packages/mui-base/src/Composite/Root/CompositeRoot.tsx
index 089addb887..f926356838 100644
--- a/packages/mui-base/src/Composite/Root/CompositeRoot.tsx
+++ b/packages/mui-base/src/Composite/Root/CompositeRoot.tsx
@@ -25,6 +25,7 @@ const CompositeRoot = React.forwardRef(function CompositeRoot(
     itemSizes,
     loop,
     cols,
+    isRtl,
     ...otherProps
   } = props;
 
@@ -58,6 +59,7 @@ namespace CompositeRoot {
     orientation?: 'horizontal' | 'vertical' | 'both';
     cols?: number;
     loop?: boolean;
+    isRtl?: boolean;
     activeIndex?: number;
     onActiveIndexChange?: (index: number) => void;
     itemSizes?: Dimensions[];
@@ -90,6 +92,10 @@ CompositeRoot.propTypes /* remove-proptypes */ = {
    * @ignore
    */
   dense: PropTypes.bool,
+  /**
+   * @ignore
+   */
+  isRtl: PropTypes.bool,
   /**
    * @ignore
    */
diff --git a/packages/mui-base/src/Composite/Root/useCompositeRoot.ts b/packages/mui-base/src/Composite/Root/useCompositeRoot.ts
index 3a42f6f8dd..c7e02e5ad0 100644
--- a/packages/mui-base/src/Composite/Root/useCompositeRoot.ts
+++ b/packages/mui-base/src/Composite/Root/useCompositeRoot.ts
@@ -25,6 +25,8 @@ import {
 export interface UseCompositeRootParameters {
   orientation?: 'horizontal' | 'vertical' | 'both';
   cols?: number;
+  // isRtl not yet supported for grids (cols > 1)
+  isRtl?: boolean;
   loop?: boolean;
   activeIndex?: number;
   onActiveIndexChange?: (index: number) => void;
@@ -42,6 +44,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
   const {
     itemSizes,
     cols = 1,
+    isRtl = false,
     loop = true,
     dense = false,
     orientation = 'both',
@@ -135,17 +138,29 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
             ] as number; // navigated cell will never be nullish
           }
 
-          const toEndKeys = {
-            horizontal: [ARROW_RIGHT],
-            vertical: [ARROW_DOWN],
-            both: [ARROW_RIGHT, ARROW_DOWN],
-          }[orientation];
+          const toEndKeys = isRtl
+            ? {
+                horizontal: [ARROW_LEFT],
+                vertical: [ARROW_DOWN],
+                both: [ARROW_LEFT, ARROW_DOWN],
+              }[orientation]
+            : {
+                horizontal: [ARROW_RIGHT],
+                vertical: [ARROW_DOWN],
+                both: [ARROW_RIGHT, ARROW_DOWN],
+              }[orientation];
 
-          const toStartKeys = {
-            horizontal: [ARROW_LEFT],
-            vertical: [ARROW_UP],
-            both: [ARROW_LEFT, ARROW_UP],
-          }[orientation];
+          const toStartKeys = isRtl
+            ? {
+                horizontal: [ARROW_RIGHT],
+                vertical: [ARROW_UP],
+                both: [ARROW_RIGHT, ARROW_UP],
+              }[orientation]
+            : {
+                horizontal: [ARROW_LEFT],
+                vertical: [ARROW_UP],
+                both: [ARROW_LEFT, ARROW_UP],
+              }[orientation];
 
           const preventedKeys = isGrid
             ? ALL_KEYS
@@ -191,6 +206,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
       dense,
       elementsRef,
       isGrid,
+      isRtl,
       itemSizes,
       loop,
       onActiveIndexChange,

From f50c212aae407ddb894e5c36159005d1f990d371 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 6 Nov 2024 13:44:13 +0800
Subject: [PATCH 06/19] Add RTL support

---
 .../ToggleButtonGroupRtl.js                   |  67 +++++++
 .../ToggleButtonGroupRtl.tsx                  |  67 +++++++
 .../toggle-button-group/styles.module.css     |  20 +-
 .../toggle-button-group.mdx                   |   4 +-
 .../toggle-button/styles.module.css           |   2 +-
 .../Item/ToggleButtonGroupItem.test.tsx       |   3 +-
 .../Item/ToggleButtonGroupItem.tsx            |   3 +-
 .../Root/ToggleButtonGroupRoot.test.tsx       | 175 ++++++++++++++----
 .../Root/ToggleButtonGroupRoot.tsx            |   3 +-
 9 files changed, 302 insertions(+), 42 deletions(-)
 create mode 100644 docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js
 create mode 100644 docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx

diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js
new file mode 100644
index 0000000000..1f96c61b31
--- /dev/null
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js
@@ -0,0 +1,67 @@
+'use client';
+import * as React from 'react';
+import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import classes from './styles.module.css';
+
+export default function ToggleButtonGroupRtl() {
+  return (
+    <ToggleButtonGroup.Root
+      direction="rtl"
+      toggleMultiple
+      aria-label="Text formatting"
+      className={classes.root}
+    >
+      <ToggleButtonGroup.Item
+        value="bold"
+        aria-label="Toggle bold"
+        className={classes.button}
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+          <path d="M6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+        </svg>
+      </ToggleButtonGroup.Item>
+
+      <ToggleButtonGroup.Item
+        value="italics"
+        aria-label="Toggle italics"
+        className={classes.button}
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <line x1="19" y1="4" x2="10" y2="4" />
+          <line x1="14" y1="20" x2="5" y2="20" />
+          <line x1="15" y1="4" x2="9" y2="20" />
+        </svg>
+      </ToggleButtonGroup.Item>
+
+      <ToggleButtonGroup.Item
+        value="underline"
+        aria-label="Toggle underline"
+        className={classes.button}
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <path d="M6 3v7a6 6 0 0 0 6 6 6 6 0 0 0 6-6V3" />
+          <line x1="4" y1="21" x2="20" y2="21" />
+        </svg>
+      </ToggleButtonGroup.Item>
+    </ToggleButtonGroup.Root>
+  );
+}
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx
new file mode 100644
index 0000000000..1f96c61b31
--- /dev/null
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx
@@ -0,0 +1,67 @@
+'use client';
+import * as React from 'react';
+import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import classes from './styles.module.css';
+
+export default function ToggleButtonGroupRtl() {
+  return (
+    <ToggleButtonGroup.Root
+      direction="rtl"
+      toggleMultiple
+      aria-label="Text formatting"
+      className={classes.root}
+    >
+      <ToggleButtonGroup.Item
+        value="bold"
+        aria-label="Toggle bold"
+        className={classes.button}
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+          <path d="M6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+        </svg>
+      </ToggleButtonGroup.Item>
+
+      <ToggleButtonGroup.Item
+        value="italics"
+        aria-label="Toggle italics"
+        className={classes.button}
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <line x1="19" y1="4" x2="10" y2="4" />
+          <line x1="14" y1="20" x2="5" y2="20" />
+          <line x1="15" y1="4" x2="9" y2="20" />
+        </svg>
+      </ToggleButtonGroup.Item>
+
+      <ToggleButtonGroup.Item
+        value="underline"
+        aria-label="Toggle underline"
+        className={classes.button}
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          className={classes.icon}
+        >
+          <path d="M6 3v7a6 6 0 0 0 6 6 6 6 0 0 0 6-6V3" />
+          <line x1="4" y1="21" x2="20" y2="21" />
+        </svg>
+      </ToggleButtonGroup.Item>
+    </ToggleButtonGroup.Root>
+  );
+}
diff --git a/docs/data/components/toggle-button-group/styles.module.css b/docs/data/components/toggle-button-group/styles.module.css
index 965b79590b..49d9ac5646 100644
--- a/docs/data/components/toggle-button-group/styles.module.css
+++ b/docs/data/components/toggle-button-group/styles.module.css
@@ -4,8 +4,10 @@
 
 .button {
   --size: 2.5rem;
-  --corner: 0.4rem;
+  --corner-radius: 0.4rem;
   --border-color: var(--gray-outline-2);
+  --border-radius-visual-right: 0 var(--corner-radius) var(--corner-radius) 0;
+  --border-radius-visual-left: var(--corner-radius) 0 0 var(--corner-radius);
 
   display: flex;
   flex-flow: row nowrap;
@@ -19,16 +21,24 @@
 }
 
 .button:first-child {
-  border-radius: var(--corner) 0 0 var(--corner);
+  border-radius: var(--border-radius-visual-left);
   border-right-color: transparent;
 }
 
 .button:last-child {
-  border-radius: 0 var(--corner) var(--corner) 0;
+  border-radius: var(--border-radius-visual-right);
   border-left-color: transparent;
 }
 
-.button:hover {
+[dir='rtl'] .button:first-child {
+  border-radius: var(--border-radius-visual-right);
+}
+
+[dir='rtl'] .button:last-child {
+  border-radius: var(--border-radius-visual-left);
+}
+
+.button:not(:disabled):hover {
   background-color: var(--gray-surface-1);
   outline: 1px solid var(--gray-500);
   outline-offset: -1px;
@@ -38,7 +48,7 @@
 }
 
 .button:focus-visible {
-  outline: 2px solid var(--gray-900);
+  outline: 2px solid var(--color-violet);
   z-index: 1;
 }
 
diff --git a/docs/data/components/toggle-button-group/toggle-button-group.mdx b/docs/data/components/toggle-button-group/toggle-button-group.mdx
index 3b49138d4e..226bd1c882 100644
--- a/docs/data/components/toggle-button-group/toggle-button-group.mdx
+++ b/docs/data/components/toggle-button-group/toggle-button-group.mdx
@@ -57,7 +57,7 @@ When uncontrolled, use the `defaultValue` prop to set the initial state of the g
 When controlled, pass the `value` and `onValueChange` props to `ToggleButtonGroup.Root`:
 
 ```tsx
-const [value, setValue] = React.useState(['italics']);
+const [value, setValue] = React.useState(['align-center']);
 
 return (
   <ToggleButtonGroup.Root value={value} onValueChange={setValue}>
@@ -114,6 +114,8 @@ Use the `direction` prop to configure a RTL toggle button group:
 <ToggleButtonGroup.Root direction="rtl">{/* toggle buttons */}</ToggleButtonGroup.Root>
 ```
 
+<Demo demo="ToggleButtonGroupRtl" />
+
 ## Accessibility
 
 - The `Root` component, and every `Item` must be given must be given an accessible name with `aria-label` or `aria-labelledby`.
diff --git a/docs/data/components/toggle-button/styles.module.css b/docs/data/components/toggle-button/styles.module.css
index 13cf86e1d1..1c18fed1ca 100644
--- a/docs/data/components/toggle-button/styles.module.css
+++ b/docs/data/components/toggle-button/styles.module.css
@@ -20,7 +20,7 @@
 }
 
 .button:focus-visible {
-  outline: 2px solid var(--gray-900);
+  outline: 2px solid var(--color-violet);
 }
 
 .icon {
diff --git a/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx b/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx
index 843d71837e..beb639a8ae 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx
@@ -5,6 +5,7 @@ import { act } from '@mui/internal-test-utils';
 import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
 import { createRenderer, describeConformance } from '#test-utils';
 import { NOOP } from '../../utils/noop';
+import { CompositeRoot } from '../../Composite/Root/CompositeRoot';
 import { ToggleButtonGroupRootContext } from '../Root/ToggleButtonGroupRootContext';
 
 const contextValue: ToggleButtonGroupRootContext = {
@@ -21,7 +22,7 @@ describe('<ToggleButtonGroup.Item />', () => {
     render: (node) =>
       render(
         <ToggleButtonGroupRootContext.Provider value={contextValue}>
-          {node}
+          <CompositeRoot>{node}</CompositeRoot>
         </ToggleButtonGroupRootContext.Provider>,
       ),
   }));
diff --git a/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx b/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx
index 4a3efc58e6..338ef851bb 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx
@@ -3,6 +3,7 @@ import * as React from 'react';
 import PropTypes from 'prop-types';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import type { BaseUIComponentProps } from '../../utils/types';
+import { CompositeItem } from '../../Composite/Item/CompositeItem';
 import { useToggleButtonGroupRootContext } from '../Root/ToggleButtonGroupRootContext';
 import { useToggleButtonGroupItem } from './useToggleButtonGroupItem';
 
@@ -67,7 +68,7 @@ const ToggleButtonGroupItem = React.forwardRef(function ToggleButtonGroupItem(
     extraProps: otherProps,
   });
 
-  return renderElement();
+  return <CompositeItem render={renderElement()} />;
 });
 
 export { ToggleButtonGroupItem };
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
index f3b28e49ae..1a99fadc2a 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
@@ -1,10 +1,12 @@
 import * as React from 'react';
 import { expect } from 'chai';
 import { spy } from 'sinon';
-import { act, flushMicrotasks } from '@mui/internal-test-utils';
+import { act, describeSkipIf, flushMicrotasks } from '@mui/internal-test-utils';
 import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
 import { createRenderer, describeConformance } from '#test-utils';
 
+const isJSDOM = /jsdom/.test(window.navigator.userAgent);
+
 describe('<ToggleButtonGroup.Root />', () => {
   const { render } = createRenderer();
 
@@ -21,7 +23,7 @@ describe('<ToggleButtonGroup.Root />', () => {
 
   describe('uncontrolled', () => {
     it('pressed state', async function test(t = {}) {
-      if (/jsdom/.test(window.navigator.userAgent)) {
+      if (isJSDOM) {
         // @ts-expect-error to support mocha and vitest
         // eslint-disable-next-line @typescript-eslint/no-unused-expressions
         this?.skip?.() || t?.skip();
@@ -197,6 +199,117 @@ describe('<ToggleButtonGroup.Root />', () => {
     });
   });
 
+  describeSkipIf(isJSDOM)('keyboard interactions', () => {
+    it('ltr', async () => {
+      const { getAllByRole, user } = await render(
+        <ToggleButtonGroup.Root>
+          <ToggleButtonGroup.Item value="one" />
+          <ToggleButtonGroup.Item value="two" />
+        </ToggleButtonGroup.Root>,
+      );
+
+      const [button1, button2] = getAllByRole('button');
+
+      await user.keyboard('[Tab]');
+
+      expect(button1).to.have.attribute('data-active');
+      expect(button1).to.have.attribute('tabindex', '0');
+      expect(button1).toHaveFocus();
+
+      await user.keyboard('[ArrowRight]');
+
+      expect(button2).to.have.attribute('data-active');
+      expect(button2).to.have.attribute('tabindex', '0');
+      expect(button2).toHaveFocus();
+
+      await user.keyboard('[ArrowRight]');
+
+      expect(button1).to.have.attribute('data-active');
+      expect(button1).to.have.attribute('tabindex', '0');
+      expect(button1).toHaveFocus();
+
+      await user.keyboard('[ArrowDown]');
+
+      expect(button2).to.have.attribute('data-active');
+      expect(button2).to.have.attribute('tabindex', '0');
+      expect(button2).toHaveFocus();
+
+      await user.keyboard('[ArrowDown]');
+
+      expect(button1).to.have.attribute('data-active');
+      expect(button1).to.have.attribute('tabindex', '0');
+      expect(button1).toHaveFocus();
+    });
+
+    it('rtl', async () => {
+      const { getAllByRole, user } = await render(
+        <ToggleButtonGroup.Root direction="rtl">
+          <ToggleButtonGroup.Item value="one" />
+          <ToggleButtonGroup.Item value="two" />
+        </ToggleButtonGroup.Root>,
+      );
+
+      const [button1, button2] = getAllByRole('button');
+
+      await user.keyboard('[Tab]');
+
+      expect(button1).to.have.attribute('data-active');
+      expect(button1).to.have.attribute('tabindex', '0');
+      expect(button1).toHaveFocus();
+
+      await user.keyboard('[ArrowLeft]');
+
+      expect(button2).to.have.attribute('data-active');
+      expect(button2).to.have.attribute('tabindex', '0');
+      expect(button2).toHaveFocus();
+
+      await user.keyboard('[ArrowLeft]');
+
+      expect(button1).to.have.attribute('data-active');
+      expect(button1).to.have.attribute('tabindex', '0');
+      expect(button1).toHaveFocus();
+
+      await user.keyboard('[ArrowDown]');
+
+      expect(button2).to.have.attribute('data-active');
+      expect(button2).to.have.attribute('tabindex', '0');
+      expect(button2).toHaveFocus();
+
+      await user.keyboard('[ArrowDown]');
+
+      expect(button1).to.have.attribute('data-active');
+      expect(button1).to.have.attribute('tabindex', '0');
+      expect(button1).toHaveFocus();
+    });
+
+    ['Enter', 'Space'].forEach((key) => {
+      it(`key: ${key} toggles the pressed state`, async () => {
+        const { getAllByRole, user } = await render(
+          <ToggleButtonGroup.Root>
+            <ToggleButtonGroup.Item value="one" />
+            <ToggleButtonGroup.Item value="two" />
+          </ToggleButtonGroup.Root>,
+        );
+
+        const [button1] = getAllByRole('button');
+
+        expect(button1).to.have.attribute('aria-pressed', 'false');
+
+        await act(async () => {
+          button1.focus();
+        });
+
+        await user.keyboard(`[${key}]`);
+
+        expect(button1).to.have.attribute('aria-pressed', 'true');
+
+        await user.keyboard(`[${key}]`);
+
+        expect(button1).to.have.attribute('aria-pressed', 'false');
+      });
+    });
+  });
+
   describe('prop: onValueChange', () => {
     it('fires when an Item is clicked', async () => {
       const onValueChange = spy();
@@ -223,46 +336,44 @@ describe('<ToggleButtonGroup.Root />', () => {
       expect(onValueChange.args[1][0]).to.deep.equal(['two']);
     });
 
-    describe('keypresses', () => {
-      ['Enter', 'Space'].forEach((key) => {
-        it(`fires when when the ${key} is pressed`, async function test(t = {}) {
-          if (/jsdom/.test(window.navigator.userAgent)) {
-            // @ts-expect-error to support mocha and vitest
-            // eslint-disable-next-line @typescript-eslint/no-unused-expressions
-            this?.skip?.() || t?.skip();
-          }
+    ['Enter', 'Space'].forEach((key) => {
+      it(`fires when when the ${key} is pressed`, async function test(t = {}) {
+        if (isJSDOM) {
+          // @ts-expect-error to support mocha and vitest
+          // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+          this?.skip?.() || t?.skip();
+        }
 
-          const onValueChange = spy();
+        const onValueChange = spy();
 
-          const { getAllByRole, user } = await render(
-            <ToggleButtonGroup.Root onValueChange={onValueChange}>
-              <ToggleButtonGroup.Item value="one" />
-              <ToggleButtonGroup.Item value="two" />
-            </ToggleButtonGroup.Root>,
-          );
+        const { getAllByRole, user } = await render(
+          <ToggleButtonGroup.Root onValueChange={onValueChange}>
+            <ToggleButtonGroup.Item value="one" />
+            <ToggleButtonGroup.Item value="two" />
+          </ToggleButtonGroup.Root>,
+        );
 
-          const [button1, button2] = getAllByRole('button');
+        const [button1, button2] = getAllByRole('button');
 
-          expect(onValueChange.callCount).to.equal(0);
+        expect(onValueChange.callCount).to.equal(0);
 
-          await act(async () => {
-            button1.focus();
-          });
+        await act(async () => {
+          button1.focus();
+        });
 
-          await user.keyboard(`[${key}]`);
+        await user.keyboard(`[${key}]`);
 
-          expect(onValueChange.callCount).to.equal(1);
-          expect(onValueChange.args[0][0]).to.deep.equal(['one']);
+        expect(onValueChange.callCount).to.equal(1);
+        expect(onValueChange.args[0][0]).to.deep.equal(['one']);
 
-          await act(async () => {
-            button2.focus();
-          });
+        await act(async () => {
+          button2.focus();
+        });
 
-          await user.keyboard(`[${key}]`);
+        await user.keyboard(`[${key}]`);
 
-          expect(onValueChange.callCount).to.equal(2);
-          expect(onValueChange.args[1][0]).to.deep.equal(['two']);
-        });
+        expect(onValueChange.callCount).to.equal(2);
+        expect(onValueChange.args[1][0]).to.deep.equal(['two']);
       });
     });
   });
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
index 21fa7b590f..cae2cba706 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
@@ -3,6 +3,7 @@ import * as React from 'react';
 import PropTypes from 'prop-types';
 import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import type { BaseUIComponentProps } from '../../utils/types';
+import { CompositeRoot } from '../../Composite/Root/CompositeRoot';
 import {
   useToggleButtonGroupRoot,
   type UseToggleButtonGroupRoot,
@@ -86,7 +87,7 @@ const ToggleButtonGroupRoot = React.forwardRef(function ToggleButtonGroupRoot(
 
   return (
     <ToggleButtonGroupRootContext.Provider value={contextValue}>
-      {renderElement()}
+      <CompositeRoot render={renderElement()} isRtl={direction === 'rtl'} />
     </ToggleButtonGroupRootContext.Provider>
   );
 });

From f62060a19c84abf200a22f814b384e5198a03fe6 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Fri, 8 Nov 2024 15:13:06 +0800
Subject: [PATCH 07/19] Simplify value type

---
 docs/data/api/toggle-button-group-item.json   |  2 +-
 .../ToggleButtonGroupIntroduction.tsx         |  2 +-
 .../toggle-button-group-item.json             |  2 +-
 docs/src/app/experiments/toggle-group.tsx     |  2 +-
 .../Item/ToggleButtonGroupItem.tsx            |  4 +-
 .../Item/useToggleButtonGroupItem.ts          |  8 ++--
 .../Root/ToggleButtonGroupRoot.tsx            |  4 +-
 .../Root/ToggleButtonGroupRootContext.ts      |  4 +-
 .../Root/useToggleButtonGroupRoot.ts          | 42 +++++++++----------
 9 files changed, 34 insertions(+), 36 deletions(-)

diff --git a/docs/data/api/toggle-button-group-item.json b/docs/data/api/toggle-button-group-item.json
index a9f4f93982..82bb97087e 100644
--- a/docs/data/api/toggle-button-group-item.json
+++ b/docs/data/api/toggle-button-group-item.json
@@ -1,6 +1,6 @@
 {
   "props": {
-    "value": { "type": { "name": "any" }, "required": true },
+    "value": { "type": { "name": "string" }, "required": true },
     "aria-label": { "type": { "name": "string" } },
     "aria-labelledby": { "type": { "name": "string" } },
     "className": { "type": { "name": "union", "description": "func<br>&#124;&nbsp;string" } },
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.tsx b/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.tsx
index 1488496011..dea1da5e11 100644
--- a/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.tsx
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.tsx
@@ -11,7 +11,7 @@ export default function ToggleButtonGroupIntroduction() {
       value={value}
       onValueChange={(newValue) => {
         if (newValue.length > 0) {
-          setValue(newValue as string[]);
+          setValue(newValue);
         }
       }}
       aria-label="Text alignment"
diff --git a/docs/data/translations/api-docs/toggle-button-group-item/toggle-button-group-item.json b/docs/data/translations/api-docs/toggle-button-group-item/toggle-button-group-item.json
index 0527007e3d..d8232c78d9 100644
--- a/docs/data/translations/api-docs/toggle-button-group-item/toggle-button-group-item.json
+++ b/docs/data/translations/api-docs/toggle-button-group-item/toggle-button-group-item.json
@@ -17,7 +17,7 @@
     },
     "render": { "description": "A function to customize rendering of the component." },
     "value": {
-      "description": "A unique value that identifies the component when used inside a ToggleButtonGroup"
+      "description": "A unique string that identifies the component when used inside a ToggleButtonGroup"
     }
   },
   "classDescriptions": {}
diff --git a/docs/src/app/experiments/toggle-group.tsx b/docs/src/app/experiments/toggle-group.tsx
index 2ab4cd513b..c7eb18de8b 100644
--- a/docs/src/app/experiments/toggle-group.tsx
+++ b/docs/src/app/experiments/toggle-group.tsx
@@ -13,7 +13,7 @@ export default function ToggleButtonGroupDemo() {
         value={value}
         onValueChange={(newValue) => {
           if (newValue.length > 0) {
-            setValue(newValue as string[]);
+            setValue(newValue);
           }
         }}
         aria-label="Text alignment"
diff --git a/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx b/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx
index 338ef851bb..752a680039 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx
@@ -138,8 +138,8 @@ ToggleButtonGroupItem.propTypes /* remove-proptypes */ = {
    */
   type: PropTypes.oneOf(['button', 'reset', 'submit']),
   /**
-   * A unique value that identifies the component when used
+   * A unique string that identifies the component when used
    * inside a ToggleButtonGroup
    */
-  value: PropTypes.any.isRequired,
+  value: PropTypes.string.isRequired,
 } as any;
diff --git a/packages/mui-base/src/ToggleButtonGroup/Item/useToggleButtonGroupItem.ts b/packages/mui-base/src/ToggleButtonGroup/Item/useToggleButtonGroupItem.ts
index 9e4938f5b7..8b15a9ef55 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Item/useToggleButtonGroupItem.ts
+++ b/packages/mui-base/src/ToggleButtonGroup/Item/useToggleButtonGroupItem.ts
@@ -57,19 +57,19 @@ export namespace useToggleButtonGroupItem {
     extends Pick<useToggleButtonRoot.Parameters, 'disabled' | 'onPressedChange'> {
     itemRef?: React.Ref<HTMLElement>;
     /**
-     * A unique value that identifies the component when used
+     * A unique string that identifies the component when used
      * inside a ToggleButtonGroup
      */
-    value: unknown;
+    value: string;
     /**
      * The value of the ToggleButtonGroup represented by an array of values
      * of the items that are pressed
      */
-    groupValue: unknown[];
+    groupValue: readonly string[];
     /**
      *
      */
-    setGroupValue: (newValue: unknown, nextPressed: boolean, event: Event) => void;
+    setGroupValue: (newValue: string, nextPressed: boolean, event: Event) => void;
   }
 
   export interface ReturnValue extends useToggleButtonRoot.ReturnValue {}
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
index cae2cba706..11860f5ee6 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
@@ -129,7 +129,7 @@ ToggleButtonGroupRoot.propTypes /* remove-proptypes */ = {
   /**
    * @ignore
    */
-  defaultValue: PropTypes.array,
+  defaultValue: PropTypes.arrayOf(PropTypes.string),
   /**
    * Text direction
    * @default 'ltr'
@@ -156,5 +156,5 @@ ToggleButtonGroupRoot.propTypes /* remove-proptypes */ = {
   /**
    * @ignore
    */
-  value: PropTypes.array,
+  value: PropTypes.arrayOf(PropTypes.string),
 } as any;
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRootContext.ts b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRootContext.ts
index 8b6bb43cab..be10d9f408 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRootContext.ts
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRootContext.ts
@@ -2,8 +2,8 @@
 import * as React from 'react';
 
 export interface ToggleButtonGroupRootContext {
-  value: unknown[];
-  setGroupValue: (newValue: unknown, nextPressed: boolean, event: Event) => void;
+  value: readonly string[];
+  setGroupValue: (newValue: string, nextPressed: boolean, event: Event) => void;
   disabled: boolean;
 }
 
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts b/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
index a033a962ec..cbb060c4de 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
@@ -24,25 +24,23 @@ export function useToggleButtonGroupRoot(
     state: 'value',
   });
 
-  const setGroupValue = useEventCallback(
-    (newValue: unknown, nextPressed: boolean, event: Event) => {
-      let newGroupValue: unknown[] | undefined;
-      if (toggleMultiple) {
-        newGroupValue = groupValue.slice();
-        if (nextPressed) {
-          newGroupValue.push(newValue);
-        } else {
-          newGroupValue.splice(groupValue.indexOf(newValue), 1);
-        }
+  const setGroupValue = useEventCallback((newValue: string, nextPressed: boolean, event: Event) => {
+    let newGroupValue: string[] | undefined;
+    if (toggleMultiple) {
+      newGroupValue = groupValue.slice();
+      if (nextPressed) {
+        newGroupValue.push(newValue);
       } else {
-        newGroupValue = nextPressed ? [newValue] : [];
+        newGroupValue.splice(groupValue.indexOf(newValue), 1);
       }
-      if (Array.isArray(newGroupValue)) {
-        setValueState(newGroupValue);
-        onValueChange?.(newGroupValue, event);
-      }
-    },
-  );
+    } else {
+      newGroupValue = nextPressed ? [newValue] : [];
+    }
+    if (Array.isArray(newGroupValue)) {
+      setValueState(newGroupValue);
+      onValueChange?.(newGroupValue, event);
+    }
+  });
 
   const getRootProps = React.useCallback(
     (externalProps = {}) =>
@@ -68,9 +66,9 @@ export namespace UseToggleButtonGroupRoot {
   export type Direction = 'ltr' | 'rtl';
 
   export interface Parameters {
-    value?: unknown[];
-    defaultValue?: unknown[];
-    onValueChange?: (groupValue: unknown[], event: Event) => void;
+    value?: readonly string[];
+    defaultValue?: readonly string[];
+    onValueChange?: (groupValue: string[], event: Event) => void;
     /**
      * When `true` the component is disabled
      * @false
@@ -99,11 +97,11 @@ export namespace UseToggleButtonGroupRoot {
     /**
      *
      */
-    setGroupValue: (newValue: unknown, nextPressed: boolean, event: Event) => void;
+    setGroupValue: (newValue: string, nextPressed: boolean, event: Event) => void;
     /**
      * The value of the ToggleButtonGroup represented by an array of values
      * of the items that are pressed
      */
-    value: unknown[];
+    value: readonly string[];
   }
 }

From b00d92ed82afd0b8dc076fa8a6d05875970acce9 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Fri, 8 Nov 2024 21:56:21 +0800
Subject: [PATCH 08/19] Update docs

---
 docs/data/api/toggle-button-group-root.json   | 11 +++++++++-
 .../toggle-button-group/styles.module.css     | 12 +++++------
 .../toggle-button-group-root.json             | 15 ++++++++++++-
 .../Root/ToggleButtonGroupRoot.tsx            | 18 +++++++++++-----
 .../Root/useToggleButtonGroupRoot.ts          | 21 +++++++++++++++++--
 5 files changed, 62 insertions(+), 15 deletions(-)

diff --git a/docs/data/api/toggle-button-group-root.json b/docs/data/api/toggle-button-group-root.json
index 1ecf406957..eb03524a5e 100644
--- a/docs/data/api/toggle-button-group-root.json
+++ b/docs/data/api/toggle-button-group-root.json
@@ -1,12 +1,21 @@
 {
   "props": {
     "className": { "type": { "name": "union", "description": "func<br>&#124;&nbsp;string" } },
+    "defaultValue": { "type": { "name": "arrayOf", "description": "Array&lt;string&gt;" } },
     "direction": {
       "type": { "name": "enum", "description": "'ltr'<br>&#124;&nbsp;'rtl'" },
       "default": "'ltr'"
     },
+    "onValueChange": {
+      "type": { "name": "func" },
+      "signature": {
+        "type": "function(groupValue: Array<string>, event: Event) => void",
+        "describedArgs": ["groupValue", "event"]
+      }
+    },
     "render": { "type": { "name": "union", "description": "element<br>&#124;&nbsp;func" } },
-    "toggleMultiple": { "type": { "name": "bool" }, "default": "false" }
+    "toggleMultiple": { "type": { "name": "bool" }, "default": "false" },
+    "value": { "type": { "name": "arrayOf", "description": "Array&lt;string&gt;" } }
   },
   "name": "ToggleButtonGroupRoot",
   "imports": [
diff --git a/docs/data/components/toggle-button-group/styles.module.css b/docs/data/components/toggle-button-group/styles.module.css
index 49d9ac5646..b0d9b09e68 100644
--- a/docs/data/components/toggle-button-group/styles.module.css
+++ b/docs/data/components/toggle-button-group/styles.module.css
@@ -6,8 +6,8 @@
   --size: 2.5rem;
   --corner-radius: 0.4rem;
   --border-color: var(--gray-outline-2);
-  --border-radius-visual-right: 0 var(--corner-radius) var(--corner-radius) 0;
-  --border-radius-visual-left: var(--corner-radius) 0 0 var(--corner-radius);
+  --border-radius-right: 0 var(--corner-radius) var(--corner-radius) 0;
+  --border-radius-left: var(--corner-radius) 0 0 var(--corner-radius);
 
   display: flex;
   flex-flow: row nowrap;
@@ -21,21 +21,21 @@
 }
 
 .button:first-child {
-  border-radius: var(--border-radius-visual-left);
+  border-radius: var(--border-radius-left);
   border-right-color: transparent;
 }
 
 .button:last-child {
-  border-radius: var(--border-radius-visual-right);
+  border-radius: var(--border-radius-right);
   border-left-color: transparent;
 }
 
 [dir='rtl'] .button:first-child {
-  border-radius: var(--border-radius-visual-right);
+  border-radius: var(--border-radius-right);
 }
 
 [dir='rtl'] .button:last-child {
-  border-radius: var(--border-radius-visual-left);
+  border-radius: var(--border-radius-left);
 }
 
 .button:not(:disabled):hover {
diff --git a/docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json b/docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json
index 1b218a08ca..40f2121541 100644
--- a/docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json
+++ b/docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json
@@ -4,10 +4,23 @@
     "className": {
       "description": "Class names applied to the element or a function that returns them based on the component&#39;s state."
     },
+    "defaultValue": {
+      "description": "The open state of the ToggleButtonGroup represented by an array of the values of all pressed <code>&lt;ToggleButtonGroup.Item/&gt;</code>s This is the uncontrolled counterpart of <code>value</code>."
+    },
     "direction": { "description": "Text direction" },
+    "onValueChange": {
+      "description": "Callback fired when the pressed states of the ToggleButtonGroup changes.",
+      "typeDescriptions": {
+        "groupValue": "An array of the <code>value</code>s of all the pressed items.",
+        "event": "The event source of the callback."
+      }
+    },
     "render": { "description": "A function to customize rendering of the component." },
     "toggleMultiple": {
-      "description": "When <code>false</code> only one ToggleButton in the group can be pressed. When a ToggleButton is pressed, the others in the group will become unpressed"
+      "description": "When <code>false</code> only one item in the group can be pressed. If any item in the group becomes pressed, the others will become unpressed. When <code>true</code> multiple items can be pressed."
+    },
+    "value": {
+      "description": "The open state of the ToggleButtonGroup represented by an array of the values of all pressed <code>&lt;ToggleButtonGroup.Item/&gt;</code>s This is the controlled counterpart of <code>defaultValue</code>."
     }
   },
   "classDescriptions": {}
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
index 11860f5ee6..d92d53577a 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
@@ -127,7 +127,9 @@ ToggleButtonGroupRoot.propTypes /* remove-proptypes */ = {
    */
   className: PropTypes.oneOfType([PropTypes.func, PropTypes.string]),
   /**
-   * @ignore
+   * The open state of the ToggleButtonGroup represented by an array of
+   * the values of all pressed `<ToggleButtonGroup.Item/>`s
+   * This is the uncontrolled counterpart of `value`.
    */
   defaultValue: PropTypes.arrayOf(PropTypes.string),
   /**
@@ -140,7 +142,10 @@ ToggleButtonGroupRoot.propTypes /* remove-proptypes */ = {
    */
   disabled: PropTypes.bool,
   /**
-   * @ignore
+   * Callback fired when the pressed states of the ToggleButtonGroup changes.
+   *
+   * @param {string[]} groupValue An array of the `value`s of all the pressed items.
+   * @param {Event} event The event source of the callback.
    */
   onValueChange: PropTypes.func,
   /**
@@ -148,13 +153,16 @@ ToggleButtonGroupRoot.propTypes /* remove-proptypes */ = {
    */
   render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
   /**
-   * When `false` only one ToggleButton in the group can be pressed.
-   * When a ToggleButton is pressed, the others in the group will become unpressed
+   * When `false` only one item in the group can be pressed. If any item in
+   * the group becomes pressed, the others will become unpressed.
+   * When `true` multiple items can be pressed.
    * @default false
    */
   toggleMultiple: PropTypes.bool,
   /**
-   * @ignore
+   * The open state of the ToggleButtonGroup represented by an array of
+   * the values of all pressed `<ToggleButtonGroup.Item/>`s
+   * This is the controlled counterpart of `defaultValue`.
    */
   value: PropTypes.arrayOf(PropTypes.string),
 } as any;
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts b/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
index cbb060c4de..98a67cd6e4 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
@@ -66,8 +66,24 @@ export namespace UseToggleButtonGroupRoot {
   export type Direction = 'ltr' | 'rtl';
 
   export interface Parameters {
+    /**
+     * The open state of the ToggleButtonGroup represented by an array of
+     * the values of all pressed `<ToggleButtonGroup.Item/>`s
+     * This is the controlled counterpart of `defaultValue`.
+     */
     value?: readonly string[];
+    /**
+     * The open state of the ToggleButtonGroup represented by an array of
+     * the values of all pressed `<ToggleButtonGroup.Item/>`s
+     * This is the uncontrolled counterpart of `value`.
+     */
     defaultValue?: readonly string[];
+    /**
+     * Callback fired when the pressed states of the ToggleButtonGroup changes.
+     *
+     * @param {string[]} groupValue An array of the `value`s of all the pressed items.
+     * @param {Event} event The event source of the callback.
+     */
     onValueChange?: (groupValue: string[], event: Event) => void;
     /**
      * When `true` the component is disabled
@@ -75,8 +91,9 @@ export namespace UseToggleButtonGroupRoot {
      */
     disabled?: boolean;
     /**
-     * When `false` only one ToggleButton in the group can be pressed.
-     * When a ToggleButton is pressed, the others in the group will become unpressed
+     * When `false` only one item in the group can be pressed. If any item in
+     * the group becomes pressed, the others will become unpressed.
+     * When `true` multiple items can be pressed.
      * @default false
      */
     toggleMultiple?: boolean;

From d431760e21d4276debdc5aeaed88155e28435759 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Mon, 11 Nov 2024 14:48:40 +0800
Subject: [PATCH 09/19] Rename isRtl to rtl

---
 .../src/Composite/Root/CompositeRoot.test.tsx        |  6 +++---
 .../mui-base/src/Composite/Root/CompositeRoot.tsx    | 12 ++++++------
 .../mui-base/src/Composite/Root/useCompositeRoot.ts  | 12 ++++++------
 .../ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx |  2 +-
 4 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx b/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx
index c257c91d1e..30f23881bf 100644
--- a/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx
+++ b/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx
@@ -97,10 +97,10 @@ describe('Composite', () => {
       expect(item1).toHaveFocus();
     });
 
-    describe('prop: isRtl', () => {
+    describe('prop: rtl', () => {
       it('horizontal orientation', async () => {
         const { getByTestId } = render(
-          <CompositeRoot isRtl orientation="horizontal">
+          <CompositeRoot rtl orientation="horizontal">
             <CompositeItem data-testid="1">1</CompositeItem>
             <CompositeItem data-testid="2">2</CompositeItem>
             <CompositeItem data-testid="3">3</CompositeItem>
@@ -153,7 +153,7 @@ describe('Composite', () => {
 
       it('both horizontal and vertical orientation', async () => {
         const { getByTestId } = render(
-          <CompositeRoot isRtl orientation="both">
+          <CompositeRoot rtl orientation="both">
             <CompositeItem data-testid="1">1</CompositeItem>
             <CompositeItem data-testid="2">2</CompositeItem>
             <CompositeItem data-testid="3">3</CompositeItem>
diff --git a/packages/mui-base/src/Composite/Root/CompositeRoot.tsx b/packages/mui-base/src/Composite/Root/CompositeRoot.tsx
index f926356838..0923d02108 100644
--- a/packages/mui-base/src/Composite/Root/CompositeRoot.tsx
+++ b/packages/mui-base/src/Composite/Root/CompositeRoot.tsx
@@ -25,7 +25,7 @@ const CompositeRoot = React.forwardRef(function CompositeRoot(
     itemSizes,
     loop,
     cols,
-    isRtl,
+    rtl,
     ...otherProps
   } = props;
 
@@ -59,7 +59,7 @@ namespace CompositeRoot {
     orientation?: 'horizontal' | 'vertical' | 'both';
     cols?: number;
     loop?: boolean;
-    isRtl?: boolean;
+    rtl?: boolean;
     activeIndex?: number;
     onActiveIndexChange?: (index: number) => void;
     itemSizes?: Dimensions[];
@@ -92,10 +92,6 @@ CompositeRoot.propTypes /* remove-proptypes */ = {
    * @ignore
    */
   dense: PropTypes.bool,
-  /**
-   * @ignore
-   */
-  isRtl: PropTypes.bool,
   /**
    * @ignore
    */
@@ -121,6 +117,10 @@ CompositeRoot.propTypes /* remove-proptypes */ = {
    * A function to customize rendering of the component.
    */
   render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  /**
+   * @ignore
+   */
+  rtl: PropTypes.bool,
 } as any;
 
 export { CompositeRoot };
diff --git a/packages/mui-base/src/Composite/Root/useCompositeRoot.ts b/packages/mui-base/src/Composite/Root/useCompositeRoot.ts
index c7e02e5ad0..6f4e468ed7 100644
--- a/packages/mui-base/src/Composite/Root/useCompositeRoot.ts
+++ b/packages/mui-base/src/Composite/Root/useCompositeRoot.ts
@@ -25,8 +25,8 @@ import {
 export interface UseCompositeRootParameters {
   orientation?: 'horizontal' | 'vertical' | 'both';
   cols?: number;
-  // isRtl not yet supported for grids (cols > 1)
-  isRtl?: boolean;
+  // rtl not yet supported for grids (cols > 1)
+  rtl?: boolean;
   loop?: boolean;
   activeIndex?: number;
   onActiveIndexChange?: (index: number) => void;
@@ -44,7 +44,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
   const {
     itemSizes,
     cols = 1,
-    isRtl = false,
+    rtl = false,
     loop = true,
     dense = false,
     orientation = 'both',
@@ -138,7 +138,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
             ] as number; // navigated cell will never be nullish
           }
 
-          const toEndKeys = isRtl
+          const toEndKeys = rtl
             ? {
                 horizontal: [ARROW_LEFT],
                 vertical: [ARROW_DOWN],
@@ -150,7 +150,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
                 both: [ARROW_RIGHT, ARROW_DOWN],
               }[orientation];
 
-          const toStartKeys = isRtl
+          const toStartKeys = rtl
             ? {
                 horizontal: [ARROW_RIGHT],
                 vertical: [ARROW_UP],
@@ -206,7 +206,7 @@ export function useCompositeRoot(params: UseCompositeRootParameters) {
       dense,
       elementsRef,
       isGrid,
-      isRtl,
+      rtl,
       itemSizes,
       loop,
       onActiveIndexChange,
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
index d92d53577a..a0f95d1633 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
@@ -87,7 +87,7 @@ const ToggleButtonGroupRoot = React.forwardRef(function ToggleButtonGroupRoot(
 
   return (
     <ToggleButtonGroupRootContext.Provider value={contextValue}>
-      <CompositeRoot render={renderElement()} isRtl={direction === 'rtl'} />
+      <CompositeRoot render={renderElement()} rtl={direction === 'rtl'} />
     </ToggleButtonGroupRootContext.Provider>
   );
 });

From 8d029707c834024344ea85a742c8d54ee6f2d2d3 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Mon, 11 Nov 2024 14:54:57 +0800
Subject: [PATCH 10/19] data-highlighted

---
 .../src/Composite/Item/CompositeItem.tsx      |  4 +-
 .../src/Composite/Root/CompositeRoot.test.tsx | 62 +++++++++----------
 .../Root/ToggleButtonGroupRoot.test.tsx       | 20 +++---
 3 files changed, 43 insertions(+), 43 deletions(-)

diff --git a/packages/mui-base/src/Composite/Item/CompositeItem.tsx b/packages/mui-base/src/Composite/Item/CompositeItem.tsx
index 8b87646048..fac4c94c76 100644
--- a/packages/mui-base/src/Composite/Item/CompositeItem.tsx
+++ b/packages/mui-base/src/Composite/Item/CompositeItem.tsx
@@ -21,7 +21,7 @@ const CompositeItem = React.forwardRef(function CompositeItem(
 
   const ownerState: CompositeItem.OwnerState = React.useMemo(
     () => ({
-      active: index === activeIndex,
+      highlighted: index === activeIndex,
     }),
     [index, activeIndex],
   );
@@ -42,7 +42,7 @@ const CompositeItem = React.forwardRef(function CompositeItem(
 
 namespace CompositeItem {
   export interface OwnerState {
-    active: boolean;
+    highlighted: boolean;
   }
 
   export interface Props extends BaseUIComponentProps<'div', OwnerState> {}
diff --git a/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx b/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx
index 30f23881bf..e7b9ff7b34 100644
--- a/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx
+++ b/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx
@@ -28,29 +28,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();
     });
@@ -70,29 +70,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();
     });
@@ -113,40 +113,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();
       });
@@ -166,41 +166,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();
       });
@@ -225,41 +225,41 @@ 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');
     });
   });
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
index 1a99fadc2a..1b8cd6c173 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
@@ -212,31 +212,31 @@ describe('<ToggleButtonGroup.Root />', () => {
 
       await user.keyboard('[Tab]');
 
-      expect(button1).to.have.attribute('data-active');
+      expect(button1).to.have.attribute('data-highlighted');
       expect(button1).to.have.attribute('tabindex', '0');
       expect(button1).toHaveFocus();
 
       await user.keyboard('[ArrowRight]');
 
-      expect(button2).to.have.attribute('data-active');
+      expect(button2).to.have.attribute('data-highlighted');
       expect(button2).to.have.attribute('tabindex', '0');
       expect(button2).toHaveFocus();
 
       await user.keyboard('[ArrowRight]');
 
-      expect(button1).to.have.attribute('data-active');
+      expect(button1).to.have.attribute('data-highlighted');
       expect(button1).to.have.attribute('tabindex', '0');
       expect(button1).toHaveFocus();
 
       await user.keyboard('[ArrowDown]');
 
-      expect(button2).to.have.attribute('data-active');
+      expect(button2).to.have.attribute('data-highlighted');
       expect(button2).to.have.attribute('tabindex', '0');
       expect(button2).toHaveFocus();
 
       await user.keyboard('[ArrowDown]');
 
-      expect(button1).to.have.attribute('data-active');
+      expect(button1).to.have.attribute('data-highlighted');
       expect(button1).to.have.attribute('tabindex', '0');
       expect(button1).toHaveFocus();
     });
@@ -253,31 +253,31 @@ describe('<ToggleButtonGroup.Root />', () => {
 
       await user.keyboard('[Tab]');
 
-      expect(button1).to.have.attribute('data-active');
+      expect(button1).to.have.attribute('data-highlighted');
       expect(button1).to.have.attribute('tabindex', '0');
       expect(button1).toHaveFocus();
 
       await user.keyboard('[ArrowLeft]');
 
-      expect(button2).to.have.attribute('data-active');
+      expect(button2).to.have.attribute('data-highlighted');
       expect(button2).to.have.attribute('tabindex', '0');
       expect(button2).toHaveFocus();
 
       await user.keyboard('[ArrowLeft]');
 
-      expect(button1).to.have.attribute('data-active');
+      expect(button1).to.have.attribute('data-highlighted');
       expect(button1).to.have.attribute('tabindex', '0');
       expect(button1).toHaveFocus();
 
       await user.keyboard('[ArrowDown]');
 
-      expect(button2).to.have.attribute('data-active');
+      expect(button2).to.have.attribute('data-highlighted');
       expect(button2).to.have.attribute('tabindex', '0');
       expect(button2).toHaveFocus();
 
       await user.keyboard('[ArrowDown]');
 
-      expect(button1).to.have.attribute('data-active');
+      expect(button1).to.have.attribute('data-highlighted');
       expect(button1).to.have.attribute('tabindex', '0');
       expect(button1).toHaveFocus();
     });

From f824a81047e43edbd1b7c787408efcccff7f7586 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Mon, 18 Nov 2024 21:05:47 +0800
Subject: [PATCH 11/19] Rename direction prop to dir

---
 docs/data/api/toggle-button-group-root.json   |  2 +-
 .../ToggleButtonGroupRtl.js                   |  2 +-
 .../ToggleButtonGroupRtl.tsx                  |  2 +-
 .../toggle-button-group.mdx                   |  4 +-
 .../toggle-button-group-root.json             |  2 +-
 .../generated/toggle-button-group-item.json   | 31 ++++++++++++++
 .../generated/toggle-button-group-root.json   | 36 ++++++++++++++++
 .../generated/toggle-button-root.json         | 41 +++++++++++++++++++
 docs/src/app/experiments/toggle-group.tsx     |  2 +-
 .../Root/ToggleButtonGroupRoot.test.tsx       |  2 +-
 .../Root/ToggleButtonGroupRoot.tsx            | 12 +++---
 .../Root/useToggleButtonGroupRoot.ts          |  8 ++--
 12 files changed, 126 insertions(+), 18 deletions(-)
 create mode 100644 docs/reference/generated/toggle-button-group-item.json
 create mode 100644 docs/reference/generated/toggle-button-group-root.json
 create mode 100644 docs/reference/generated/toggle-button-root.json

diff --git a/docs/data/api/toggle-button-group-root.json b/docs/data/api/toggle-button-group-root.json
index eb03524a5e..3114596595 100644
--- a/docs/data/api/toggle-button-group-root.json
+++ b/docs/data/api/toggle-button-group-root.json
@@ -2,7 +2,7 @@
   "props": {
     "className": { "type": { "name": "union", "description": "func<br>&#124;&nbsp;string" } },
     "defaultValue": { "type": { "name": "arrayOf", "description": "Array&lt;string&gt;" } },
-    "direction": {
+    "dir": {
       "type": { "name": "enum", "description": "'ltr'<br>&#124;&nbsp;'rtl'" },
       "default": "'ltr'"
     },
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js
index 1f96c61b31..429c0ae372 100644
--- a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js
@@ -6,7 +6,7 @@ import classes from './styles.module.css';
 export default function ToggleButtonGroupRtl() {
   return (
     <ToggleButtonGroup.Root
-      direction="rtl"
+      dir="rtl"
       toggleMultiple
       aria-label="Text formatting"
       className={classes.root}
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx
index 1f96c61b31..429c0ae372 100644
--- a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx
@@ -6,7 +6,7 @@ import classes from './styles.module.css';
 export default function ToggleButtonGroupRtl() {
   return (
     <ToggleButtonGroup.Root
-      direction="rtl"
+      dir="rtl"
       toggleMultiple
       aria-label="Text formatting"
       className={classes.root}
diff --git a/docs/data/components/toggle-button-group/toggle-button-group.mdx b/docs/data/components/toggle-button-group/toggle-button-group.mdx
index 226bd1c882..c37e16696a 100644
--- a/docs/data/components/toggle-button-group/toggle-button-group.mdx
+++ b/docs/data/components/toggle-button-group/toggle-button-group.mdx
@@ -108,10 +108,10 @@ return (
 
 ## RTL
 
-Use the `direction` prop to configure a RTL toggle button group:
+Use the `dir` prop to configure a RTL toggle button group:
 
 ```tsx
-<ToggleButtonGroup.Root direction="rtl">{/* toggle buttons */}</ToggleButtonGroup.Root>
+<ToggleButtonGroup.Root dir="rtl">{/* toggle buttons */}</ToggleButtonGroup.Root>
 ```
 
 <Demo demo="ToggleButtonGroupRtl" />
diff --git a/docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json b/docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json
index 40f2121541..243e6d2f94 100644
--- a/docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json
+++ b/docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json
@@ -7,7 +7,7 @@
     "defaultValue": {
       "description": "The open state of the ToggleButtonGroup represented by an array of the values of all pressed <code>&lt;ToggleButtonGroup.Item/&gt;</code>s This is the uncontrolled counterpart of <code>value</code>."
     },
-    "direction": { "description": "Text direction" },
+    "dir": { "description": "Text direction" },
     "onValueChange": {
       "description": "Callback fired when the pressed states of the ToggleButtonGroup changes.",
       "typeDescriptions": {
diff --git a/docs/reference/generated/toggle-button-group-item.json b/docs/reference/generated/toggle-button-group-item.json
new file mode 100644
index 0000000000..69a7f9b657
--- /dev/null
+++ b/docs/reference/generated/toggle-button-group-item.json
@@ -0,0 +1,31 @@
+{
+  "name": "ToggleButtonGroupItem",
+  "description": "",
+  "props": {
+    "value": {
+      "type": "string",
+      "required": true,
+      "description": "A unique string that identifies the component when used\ninside a ToggleButtonGroup"
+    },
+    "aria-label": {
+      "type": "string",
+      "description": "The label for the toggle button."
+    },
+    "aria-labelledby": {
+      "type": "string",
+      "description": "An id or space-separated list of ids of elements that label the toggle button."
+    },
+    "className": {
+      "type": "string | (state) => string",
+      "description": "Class names applied to the element or a function that returns them based on the component's state."
+    },
+    "onPressedChange": {
+      "type": "function(pressed: boolean, event: Event) => void",
+      "description": "Callback fired when the pressed state is changed."
+    },
+    "render": {
+      "type": "React.ReactElement | (props, state) => React.ReactElement",
+      "description": "A function to customize rendering of the component."
+    }
+  }
+}
diff --git a/docs/reference/generated/toggle-button-group-root.json b/docs/reference/generated/toggle-button-group-root.json
new file mode 100644
index 0000000000..8a9896ea18
--- /dev/null
+++ b/docs/reference/generated/toggle-button-group-root.json
@@ -0,0 +1,36 @@
+{
+  "name": "ToggleButtonGroupRoot",
+  "description": "",
+  "props": {
+    "className": {
+      "type": "string | (state) => string",
+      "description": "Class names applied to the element or a function that returns them based on the component's state."
+    },
+    "defaultValue": {
+      "type": "string[]",
+      "description": "The open state of the ToggleButtonGroup represented by an array of\nthe values of all pressed `<ToggleButtonGroup.Item/>`s\nThis is the uncontrolled counterpart of `value`."
+    },
+    "dir": {
+      "type": "'ltr' | 'rtl'",
+      "default": "'ltr'",
+      "description": "Text direction"
+    },
+    "onValueChange": {
+      "type": "function(groupValue: Array<string>, event: Event) => void",
+      "description": "Callback fired when the pressed states of the ToggleButtonGroup changes."
+    },
+    "render": {
+      "type": "React.ReactElement | (props, state) => React.ReactElement",
+      "description": "A function to customize rendering of the component."
+    },
+    "toggleMultiple": {
+      "type": "boolean",
+      "default": "false",
+      "description": "When `false` only one item in the group can be pressed. If any item in\nthe group becomes pressed, the others will become unpressed.\nWhen `true` multiple items can be pressed."
+    },
+    "value": {
+      "type": "string[]",
+      "description": "The open state of the ToggleButtonGroup represented by an array of\nthe values of all pressed `<ToggleButtonGroup.Item/>`s\nThis is the controlled counterpart of `defaultValue`."
+    }
+  }
+}
diff --git a/docs/reference/generated/toggle-button-root.json b/docs/reference/generated/toggle-button-root.json
new file mode 100644
index 0000000000..b481de2adc
--- /dev/null
+++ b/docs/reference/generated/toggle-button-root.json
@@ -0,0 +1,41 @@
+{
+  "name": "ToggleButtonRoot",
+  "description": "",
+  "props": {
+    "aria-label": {
+      "type": "string",
+      "description": "The label for the ToggleButton."
+    },
+    "aria-labelledby": {
+      "type": "string",
+      "description": "An id or space-separated list of ids of elements that label the ToggleButton."
+    },
+    "className": {
+      "type": "string | (state) => string",
+      "description": "Class names applied to the element or a function that returns them based on the component's state."
+    },
+    "defaultPressed": {
+      "type": "boolean",
+      "default": "false",
+      "description": "The default pressed state. Use when the component is not controlled."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": "false",
+      "description": "If `true`, the component is disabled."
+    },
+    "onPressedChange": {
+      "type": "function(pressed: boolean, event: Event) => void",
+      "description": "Callback fired when the pressed state is changed."
+    },
+    "pressed": {
+      "type": "boolean",
+      "default": "undefined",
+      "description": "If `true`, the component is pressed."
+    },
+    "render": {
+      "type": "React.ReactElement | (props, state) => React.ReactElement",
+      "description": "A function to customize rendering of the component."
+    }
+  }
+}
diff --git a/docs/src/app/experiments/toggle-group.tsx b/docs/src/app/experiments/toggle-group.tsx
index c7eb18de8b..11d02f67cf 100644
--- a/docs/src/app/experiments/toggle-group.tsx
+++ b/docs/src/app/experiments/toggle-group.tsx
@@ -82,7 +82,7 @@ export default function ToggleButtonGroupDemo() {
       <ToggleButtonGroup.Root
         toggleMultiple
         aria-label="Text formatting"
-        direction="rtl"
+        dir="rtl"
         className={classes.group}
       >
         <ToggleButtonGroup.Item
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
index 1b8cd6c173..06e40afaa8 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
@@ -243,7 +243,7 @@ describe('<ToggleButtonGroup.Root />', () => {
 
     it('rtl', async () => {
       const { getAllByRole, user } = await render(
-        <ToggleButtonGroup.Root direction="rtl">
+        <ToggleButtonGroup.Root dir="rtl">
           <ToggleButtonGroup.Item value="one" />
           <ToggleButtonGroup.Item value="two" />
         </ToggleButtonGroup.Root>,
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
index a0f95d1633..f7d9ca109d 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
@@ -35,7 +35,7 @@ const ToggleButtonGroupRoot = React.forwardRef(function ToggleButtonGroupRoot(
   const {
     value: valueProp,
     defaultValue: defaultValueProp,
-    direction,
+    dir,
     disabled: disabledProp,
     toggleMultiple = false,
     onValueChange,
@@ -55,7 +55,7 @@ const ToggleButtonGroupRoot = React.forwardRef(function ToggleButtonGroupRoot(
   const { getRootProps, disabled, setGroupValue, value } = useToggleButtonGroupRoot({
     value: valueProp,
     defaultValue,
-    direction,
+    dir,
     disabled: disabledProp,
     toggleMultiple,
     onValueChange,
@@ -87,7 +87,7 @@ const ToggleButtonGroupRoot = React.forwardRef(function ToggleButtonGroupRoot(
 
   return (
     <ToggleButtonGroupRootContext.Provider value={contextValue}>
-      <CompositeRoot render={renderElement()} rtl={direction === 'rtl'} />
+      <CompositeRoot render={renderElement()} rtl={dir === 'rtl'} />
     </ToggleButtonGroupRootContext.Provider>
   );
 });
@@ -103,9 +103,9 @@ export namespace ToggleButtonGroupRoot {
   export interface Props
     extends Pick<
         UseToggleButtonGroupRoot.Parameters,
-        'value' | 'defaultValue' | 'onValueChange' | 'disabled' | 'toggleMultiple' | 'direction'
+        'value' | 'defaultValue' | 'onValueChange' | 'disabled' | 'toggleMultiple' | 'dir'
       >,
-      Omit<BaseUIComponentProps<'div', OwnerState>, 'defaultValue'> {
+      Omit<BaseUIComponentProps<'div', OwnerState>, 'defaultValue' | 'dir'> {
     /**
      * @default false
      */
@@ -136,7 +136,7 @@ ToggleButtonGroupRoot.propTypes /* remove-proptypes */ = {
    * Text direction
    * @default 'ltr'
    */
-  direction: PropTypes.oneOf(['ltr', 'rtl']),
+  dir: PropTypes.oneOf(['ltr', 'rtl']),
   /**
    * @default false
    */
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts b/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
index 98a67cd6e4..5ce6329ca0 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
@@ -11,7 +11,7 @@ export function useToggleButtonGroupRoot(
   const {
     value,
     defaultValue,
-    direction = 'ltr',
+    dir = 'ltr',
     disabled = false,
     onValueChange,
     toggleMultiple = false,
@@ -46,9 +46,9 @@ export function useToggleButtonGroupRoot(
     (externalProps = {}) =>
       mergeReactProps<'div'>(externalProps, {
         role: 'group',
-        dir: direction,
+        dir,
       }),
-    [direction],
+    [dir],
   );
 
   return React.useMemo(
@@ -101,7 +101,7 @@ export namespace UseToggleButtonGroupRoot {
      * Text direction
      * @default 'ltr'
      */
-    direction?: Direction;
+    dir?: Direction;
   }
 
   export interface ReturnValue {

From adfa26c7178b1696fe524a45b8364c408b42e3b4 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 19 Nov 2024 16:27:26 +0800
Subject: [PATCH 12/19] No need to pass dir prop to Composite

---
 .../src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
index f7d9ca109d..b8dacb907a 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
@@ -87,7 +87,7 @@ const ToggleButtonGroupRoot = React.forwardRef(function ToggleButtonGroupRoot(
 
   return (
     <ToggleButtonGroupRootContext.Provider value={contextValue}>
-      <CompositeRoot render={renderElement()} rtl={dir === 'rtl'} />
+      <CompositeRoot render={renderElement()} />
     </ToggleButtonGroupRootContext.Provider>
   );
 });

From 5ac2910155f1d5a54be2e45689ada11f8fc7c9ad Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 19 Nov 2024 17:25:35 +0800
Subject: [PATCH 13/19] Fix data-highlighted

---
 .../src/Composite/Root/CompositeRoot.test.tsx | 104 +++++++++---------
 1 file changed, 52 insertions(+), 52 deletions(-)

diff --git a/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx b/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx
index 401729c9ca..85a4da1ae9 100644
--- a/packages/mui-base/src/Composite/Root/CompositeRoot.test.tsx
+++ b/packages/mui-base/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 fea48bd88ad3c7d3fefb19b9a5157f090c924ec8 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 20 Nov 2024 23:51:57 +0800
Subject: [PATCH 14/19] Fix conflicts

---
 docs/data/api/toggle-button-group-item.json                     | 2 +-
 docs/data/api/toggle-button-group-root.json                     | 2 +-
 docs/data/api/toggle-button-root.json                           | 2 +-
 docs/data/api/toggle-button.json                                | 2 +-
 .../toggle-button-group/ToggleButtonGroupIntroduction.js        | 2 +-
 .../toggle-button-group/ToggleButtonGroupIntroduction.tsx       | 2 +-
 .../data/components/toggle-button-group/ToggleButtonGroupRtl.js | 2 +-
 .../components/toggle-button-group/ToggleButtonGroupRtl.tsx     | 2 +-
 .../toggle-button-group/ToggleButtonGroupToggleMultiple.js      | 2 +-
 .../toggle-button-group/ToggleButtonGroupToggleMultiple.tsx     | 2 +-
 .../data/components/toggle-button-group/toggle-button-group.mdx | 2 +-
 docs/data/components/toggle-button/ToggleButtonIntroduction.js  | 2 +-
 docs/data/components/toggle-button/ToggleButtonIntroduction.tsx | 2 +-
 docs/data/components/toggle-button/toggle-button.mdx            | 2 +-
 docs/src/app/experiments/toggle-group.tsx                       | 2 +-
 .../mui-base/src/ToggleButton/Root/ToggleButtonRoot.test.tsx    | 2 +-
 .../src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx   | 2 +-
 .../src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx   | 2 +-
 18 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/docs/data/api/toggle-button-group-item.json b/docs/data/api/toggle-button-group-item.json
index 82bb97087e..de40528965 100644
--- a/docs/data/api/toggle-button-group-item.json
+++ b/docs/data/api/toggle-button-group-item.json
@@ -15,7 +15,7 @@
   },
   "name": "ToggleButtonGroupItem",
   "imports": [
-    "import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';\nconst ToggleButtonGroupItem = ToggleButtonGroup.Item;"
+    "import { ToggleButtonGroup } from '@base-ui-components/react/ToggleButtonGroup';\nconst ToggleButtonGroupItem = ToggleButtonGroup.Item;"
   ],
   "classes": [],
   "spread": true,
diff --git a/docs/data/api/toggle-button-group-root.json b/docs/data/api/toggle-button-group-root.json
index 3114596595..024cd3be86 100644
--- a/docs/data/api/toggle-button-group-root.json
+++ b/docs/data/api/toggle-button-group-root.json
@@ -19,7 +19,7 @@
   },
   "name": "ToggleButtonGroupRoot",
   "imports": [
-    "import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';\nconst ToggleButtonGroupRoot = ToggleButtonGroup.Root;"
+    "import { ToggleButtonGroup } from '@base-ui-components/react/ToggleButtonGroup';\nconst ToggleButtonGroupRoot = ToggleButtonGroup.Root;"
   ],
   "classes": [],
   "spread": true,
diff --git a/docs/data/api/toggle-button-root.json b/docs/data/api/toggle-button-root.json
index cb3929415b..45ba057814 100644
--- a/docs/data/api/toggle-button-root.json
+++ b/docs/data/api/toggle-button-root.json
@@ -17,7 +17,7 @@
   },
   "name": "ToggleButtonRoot",
   "imports": [
-    "import { ToggleButton } from '@base_ui/react/ToggleButton';\nconst ToggleButtonRoot = ToggleButton.Root;"
+    "import { ToggleButton } from '@base-ui-components/react/ToggleButton';\nconst ToggleButtonRoot = ToggleButton.Root;"
   ],
   "classes": [],
   "spread": true,
diff --git a/docs/data/api/toggle-button.json b/docs/data/api/toggle-button.json
index bd65e37c6b..57fdd49d01 100644
--- a/docs/data/api/toggle-button.json
+++ b/docs/data/api/toggle-button.json
@@ -16,7 +16,7 @@
     "render": { "type": { "name": "union", "description": "element<br>&#124;&nbsp;func" } }
   },
   "name": "ToggleButton",
-  "imports": ["import { ToggleButton } from '@base_ui/react/ToggleButton';"],
+  "imports": ["import { ToggleButton } from '@base-ui-components/react/ToggleButton';"],
   "classes": [],
   "spread": true,
   "themeDefaultProps": true,
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.js b/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.js
index dea1da5e11..6245721b16 100644
--- a/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.js
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.js
@@ -1,6 +1,6 @@
 'use client';
 import * as React from 'react';
-import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import { ToggleButtonGroup } from '@base-ui-components/react/ToggleButtonGroup';
 import classes from './styles.module.css';
 
 export default function ToggleButtonGroupIntroduction() {
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.tsx b/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.tsx
index dea1da5e11..6245721b16 100644
--- a/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.tsx
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupIntroduction.tsx
@@ -1,6 +1,6 @@
 'use client';
 import * as React from 'react';
-import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import { ToggleButtonGroup } from '@base-ui-components/react/ToggleButtonGroup';
 import classes from './styles.module.css';
 
 export default function ToggleButtonGroupIntroduction() {
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js
index 429c0ae372..ee041fbc7e 100644
--- a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js
@@ -1,6 +1,6 @@
 'use client';
 import * as React from 'react';
-import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import { ToggleButtonGroup } from '@base-ui-components/react/ToggleButtonGroup';
 import classes from './styles.module.css';
 
 export default function ToggleButtonGroupRtl() {
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx
index 429c0ae372..ee041fbc7e 100644
--- a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx
@@ -1,6 +1,6 @@
 'use client';
 import * as React from 'react';
-import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import { ToggleButtonGroup } from '@base-ui-components/react/ToggleButtonGroup';
 import classes from './styles.module.css';
 
 export default function ToggleButtonGroupRtl() {
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.js b/docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.js
index f67f4d2567..1cdc80bfab 100644
--- a/docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.js
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.js
@@ -1,6 +1,6 @@
 'use client';
 import * as React from 'react';
-import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import { ToggleButtonGroup } from '@base-ui-components/react/ToggleButtonGroup';
 import classes from './styles.module.css';
 
 export default function ToggleButtonGroupToggleMultiple() {
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.tsx b/docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.tsx
index f67f4d2567..1cdc80bfab 100644
--- a/docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.tsx
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupToggleMultiple.tsx
@@ -1,6 +1,6 @@
 'use client';
 import * as React from 'react';
-import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import { ToggleButtonGroup } from '@base-ui-components/react/ToggleButtonGroup';
 import classes from './styles.module.css';
 
 export default function ToggleButtonGroupToggleMultiple() {
diff --git a/docs/data/components/toggle-button-group/toggle-button-group.mdx b/docs/data/components/toggle-button-group/toggle-button-group.mdx
index c37e16696a..a1ac69c27e 100644
--- a/docs/data/components/toggle-button-group/toggle-button-group.mdx
+++ b/docs/data/components/toggle-button-group/toggle-button-group.mdx
@@ -5,7 +5,7 @@ description: ToggleButtonGroup provides a set of two-state buttons that can eith
 components: ToggleButtonGroupRoot, ToggleButtonGroupItem
 githubLabel: 'component: toggle button'
 waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/radio-group/
-packageName: '@base_ui/react'
+packageName: '@base-ui-components/react'
 ---
 
 # ToggleButtonGroup
diff --git a/docs/data/components/toggle-button/ToggleButtonIntroduction.js b/docs/data/components/toggle-button/ToggleButtonIntroduction.js
index 446269b0ca..f0a607b4f0 100644
--- a/docs/data/components/toggle-button/ToggleButtonIntroduction.js
+++ b/docs/data/components/toggle-button/ToggleButtonIntroduction.js
@@ -1,6 +1,6 @@
 'use client';
 import * as React from 'react';
-import { ToggleButton } from '@base_ui/react/ToggleButton';
+import { ToggleButton } from '@base-ui-components/react/ToggleButton';
 import classes from './styles.module.css';
 
 export default function ToggleButtonIntroduction() {
diff --git a/docs/data/components/toggle-button/ToggleButtonIntroduction.tsx b/docs/data/components/toggle-button/ToggleButtonIntroduction.tsx
index 446269b0ca..f0a607b4f0 100644
--- a/docs/data/components/toggle-button/ToggleButtonIntroduction.tsx
+++ b/docs/data/components/toggle-button/ToggleButtonIntroduction.tsx
@@ -1,6 +1,6 @@
 'use client';
 import * as React from 'react';
-import { ToggleButton } from '@base_ui/react/ToggleButton';
+import { ToggleButton } from '@base-ui-components/react/ToggleButton';
 import classes from './styles.module.css';
 
 export default function ToggleButtonIntroduction() {
diff --git a/docs/data/components/toggle-button/toggle-button.mdx b/docs/data/components/toggle-button/toggle-button.mdx
index 00dffe7967..54aa15635c 100644
--- a/docs/data/components/toggle-button/toggle-button.mdx
+++ b/docs/data/components/toggle-button/toggle-button.mdx
@@ -5,7 +5,7 @@ description: Toggle Buttons are a two-state button that can either be off (not p
 components: ToggleButtonRoot
 githubLabel: 'component: toggle button'
 waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/button/
-packageName: '@base_ui/react'
+packageName: '@base-ui-components/react'
 ---
 
 # ToggleButton
diff --git a/docs/src/app/experiments/toggle-group.tsx b/docs/src/app/experiments/toggle-group.tsx
index 11d02f67cf..82344bd507 100644
--- a/docs/src/app/experiments/toggle-group.tsx
+++ b/docs/src/app/experiments/toggle-group.tsx
@@ -1,6 +1,6 @@
 'use client';
 import * as React from 'react';
-import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import { ToggleButtonGroup } from '@base-ui-components/react/ToggleButtonGroup';
 import classes from './toggle.module.css';
 
 export default function ToggleButtonGroupDemo() {
diff --git a/packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.test.tsx b/packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.test.tsx
index cb0f17d100..4e0446bdd5 100644
--- a/packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.test.tsx
+++ b/packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.test.tsx
@@ -2,7 +2,7 @@ import * as React from 'react';
 import { expect } from 'chai';
 import { spy } from 'sinon';
 import { act } from '@mui/internal-test-utils';
-import { ToggleButton } from '@base_ui/react/ToggleButton';
+import { ToggleButton } from '@base-ui-components/react/ToggleButton';
 import { createRenderer, describeConformance } from '#test-utils';
 
 describe('<ToggleButton />', () => {
diff --git a/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx b/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx
index beb639a8ae..0ce61b5d67 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx
@@ -2,7 +2,7 @@ import * as React from 'react';
 import { expect } from 'chai';
 import { spy } from 'sinon';
 import { act } from '@mui/internal-test-utils';
-import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import { ToggleButtonGroup } from '@base-ui-components/react/ToggleButtonGroup';
 import { createRenderer, describeConformance } from '#test-utils';
 import { NOOP } from '../../utils/noop';
 import { CompositeRoot } from '../../Composite/Root/CompositeRoot';
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
index 06e40afaa8..0db30ef444 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
@@ -2,7 +2,7 @@ import * as React from 'react';
 import { expect } from 'chai';
 import { spy } from 'sinon';
 import { act, describeSkipIf, flushMicrotasks } from '@mui/internal-test-utils';
-import { ToggleButtonGroup } from '@base_ui/react/ToggleButtonGroup';
+import { ToggleButtonGroup } from '@base-ui-components/react/ToggleButtonGroup';
 import { createRenderer, describeConformance } from '#test-utils';
 
 const isJSDOM = /jsdom/.test(window.navigator.userAgent);

From 957eeb440f8ba8cd81870ab153e534e587ec425d Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Thu, 21 Nov 2024 14:58:49 +0800
Subject: [PATCH 15/19] Revert "Rename direction prop to dir"

This reverts commit f824a81047e43edbd1b7c787408efcccff7f7586.
---
 docs/data/api/toggle-button-group-root.json   |  2 +-
 .../ToggleButtonGroupRtl.js                   |  2 +-
 .../ToggleButtonGroupRtl.tsx                  |  2 +-
 .../toggle-button-group.mdx                   |  4 +-
 .../toggle-button-group-root.json             |  2 +-
 .../generated/toggle-button-group-item.json   | 31 --------------
 .../generated/toggle-button-group-root.json   | 36 ----------------
 .../generated/toggle-button-root.json         | 41 -------------------
 docs/src/app/experiments/toggle-group.tsx     |  2 +-
 .../Root/ToggleButtonGroupRoot.test.tsx       |  2 +-
 .../Root/ToggleButtonGroupRoot.tsx            | 10 ++---
 .../Root/useToggleButtonGroupRoot.ts          |  8 ++--
 12 files changed, 17 insertions(+), 125 deletions(-)
 delete mode 100644 docs/reference/generated/toggle-button-group-item.json
 delete mode 100644 docs/reference/generated/toggle-button-group-root.json
 delete mode 100644 docs/reference/generated/toggle-button-root.json

diff --git a/docs/data/api/toggle-button-group-root.json b/docs/data/api/toggle-button-group-root.json
index 024cd3be86..fdc1f645fc 100644
--- a/docs/data/api/toggle-button-group-root.json
+++ b/docs/data/api/toggle-button-group-root.json
@@ -2,7 +2,7 @@
   "props": {
     "className": { "type": { "name": "union", "description": "func<br>&#124;&nbsp;string" } },
     "defaultValue": { "type": { "name": "arrayOf", "description": "Array&lt;string&gt;" } },
-    "dir": {
+    "direction": {
       "type": { "name": "enum", "description": "'ltr'<br>&#124;&nbsp;'rtl'" },
       "default": "'ltr'"
     },
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js
index ee041fbc7e..757a320e83 100644
--- a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js
@@ -6,7 +6,7 @@ import classes from './styles.module.css';
 export default function ToggleButtonGroupRtl() {
   return (
     <ToggleButtonGroup.Root
-      dir="rtl"
+      direction="rtl"
       toggleMultiple
       aria-label="Text formatting"
       className={classes.root}
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx
index ee041fbc7e..757a320e83 100644
--- a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx
@@ -6,7 +6,7 @@ import classes from './styles.module.css';
 export default function ToggleButtonGroupRtl() {
   return (
     <ToggleButtonGroup.Root
-      dir="rtl"
+      direction="rtl"
       toggleMultiple
       aria-label="Text formatting"
       className={classes.root}
diff --git a/docs/data/components/toggle-button-group/toggle-button-group.mdx b/docs/data/components/toggle-button-group/toggle-button-group.mdx
index a1ac69c27e..b71ef6321c 100644
--- a/docs/data/components/toggle-button-group/toggle-button-group.mdx
+++ b/docs/data/components/toggle-button-group/toggle-button-group.mdx
@@ -108,10 +108,10 @@ return (
 
 ## RTL
 
-Use the `dir` prop to configure a RTL toggle button group:
+Use the `direction` prop to configure a RTL toggle button group:
 
 ```tsx
-<ToggleButtonGroup.Root dir="rtl">{/* toggle buttons */}</ToggleButtonGroup.Root>
+<ToggleButtonGroup.Root direction="rtl">{/* toggle buttons */}</ToggleButtonGroup.Root>
 ```
 
 <Demo demo="ToggleButtonGroupRtl" />
diff --git a/docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json b/docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json
index 243e6d2f94..40f2121541 100644
--- a/docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json
+++ b/docs/data/translations/api-docs/toggle-button-group-root/toggle-button-group-root.json
@@ -7,7 +7,7 @@
     "defaultValue": {
       "description": "The open state of the ToggleButtonGroup represented by an array of the values of all pressed <code>&lt;ToggleButtonGroup.Item/&gt;</code>s This is the uncontrolled counterpart of <code>value</code>."
     },
-    "dir": { "description": "Text direction" },
+    "direction": { "description": "Text direction" },
     "onValueChange": {
       "description": "Callback fired when the pressed states of the ToggleButtonGroup changes.",
       "typeDescriptions": {
diff --git a/docs/reference/generated/toggle-button-group-item.json b/docs/reference/generated/toggle-button-group-item.json
deleted file mode 100644
index 69a7f9b657..0000000000
--- a/docs/reference/generated/toggle-button-group-item.json
+++ /dev/null
@@ -1,31 +0,0 @@
-{
-  "name": "ToggleButtonGroupItem",
-  "description": "",
-  "props": {
-    "value": {
-      "type": "string",
-      "required": true,
-      "description": "A unique string that identifies the component when used\ninside a ToggleButtonGroup"
-    },
-    "aria-label": {
-      "type": "string",
-      "description": "The label for the toggle button."
-    },
-    "aria-labelledby": {
-      "type": "string",
-      "description": "An id or space-separated list of ids of elements that label the toggle button."
-    },
-    "className": {
-      "type": "string | (state) => string",
-      "description": "Class names applied to the element or a function that returns them based on the component's state."
-    },
-    "onPressedChange": {
-      "type": "function(pressed: boolean, event: Event) => void",
-      "description": "Callback fired when the pressed state is changed."
-    },
-    "render": {
-      "type": "React.ReactElement | (props, state) => React.ReactElement",
-      "description": "A function to customize rendering of the component."
-    }
-  }
-}
diff --git a/docs/reference/generated/toggle-button-group-root.json b/docs/reference/generated/toggle-button-group-root.json
deleted file mode 100644
index 8a9896ea18..0000000000
--- a/docs/reference/generated/toggle-button-group-root.json
+++ /dev/null
@@ -1,36 +0,0 @@
-{
-  "name": "ToggleButtonGroupRoot",
-  "description": "",
-  "props": {
-    "className": {
-      "type": "string | (state) => string",
-      "description": "Class names applied to the element or a function that returns them based on the component's state."
-    },
-    "defaultValue": {
-      "type": "string[]",
-      "description": "The open state of the ToggleButtonGroup represented by an array of\nthe values of all pressed `<ToggleButtonGroup.Item/>`s\nThis is the uncontrolled counterpart of `value`."
-    },
-    "dir": {
-      "type": "'ltr' | 'rtl'",
-      "default": "'ltr'",
-      "description": "Text direction"
-    },
-    "onValueChange": {
-      "type": "function(groupValue: Array<string>, event: Event) => void",
-      "description": "Callback fired when the pressed states of the ToggleButtonGroup changes."
-    },
-    "render": {
-      "type": "React.ReactElement | (props, state) => React.ReactElement",
-      "description": "A function to customize rendering of the component."
-    },
-    "toggleMultiple": {
-      "type": "boolean",
-      "default": "false",
-      "description": "When `false` only one item in the group can be pressed. If any item in\nthe group becomes pressed, the others will become unpressed.\nWhen `true` multiple items can be pressed."
-    },
-    "value": {
-      "type": "string[]",
-      "description": "The open state of the ToggleButtonGroup represented by an array of\nthe values of all pressed `<ToggleButtonGroup.Item/>`s\nThis is the controlled counterpart of `defaultValue`."
-    }
-  }
-}
diff --git a/docs/reference/generated/toggle-button-root.json b/docs/reference/generated/toggle-button-root.json
deleted file mode 100644
index b481de2adc..0000000000
--- a/docs/reference/generated/toggle-button-root.json
+++ /dev/null
@@ -1,41 +0,0 @@
-{
-  "name": "ToggleButtonRoot",
-  "description": "",
-  "props": {
-    "aria-label": {
-      "type": "string",
-      "description": "The label for the ToggleButton."
-    },
-    "aria-labelledby": {
-      "type": "string",
-      "description": "An id or space-separated list of ids of elements that label the ToggleButton."
-    },
-    "className": {
-      "type": "string | (state) => string",
-      "description": "Class names applied to the element or a function that returns them based on the component's state."
-    },
-    "defaultPressed": {
-      "type": "boolean",
-      "default": "false",
-      "description": "The default pressed state. Use when the component is not controlled."
-    },
-    "disabled": {
-      "type": "boolean",
-      "default": "false",
-      "description": "If `true`, the component is disabled."
-    },
-    "onPressedChange": {
-      "type": "function(pressed: boolean, event: Event) => void",
-      "description": "Callback fired when the pressed state is changed."
-    },
-    "pressed": {
-      "type": "boolean",
-      "default": "undefined",
-      "description": "If `true`, the component is pressed."
-    },
-    "render": {
-      "type": "React.ReactElement | (props, state) => React.ReactElement",
-      "description": "A function to customize rendering of the component."
-    }
-  }
-}
diff --git a/docs/src/app/experiments/toggle-group.tsx b/docs/src/app/experiments/toggle-group.tsx
index 82344bd507..c72eee032c 100644
--- a/docs/src/app/experiments/toggle-group.tsx
+++ b/docs/src/app/experiments/toggle-group.tsx
@@ -82,7 +82,7 @@ export default function ToggleButtonGroupDemo() {
       <ToggleButtonGroup.Root
         toggleMultiple
         aria-label="Text formatting"
-        dir="rtl"
+        direction="rtl"
         className={classes.group}
       >
         <ToggleButtonGroup.Item
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
index 0db30ef444..f9068bcf61 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
@@ -243,7 +243,7 @@ describe('<ToggleButtonGroup.Root />', () => {
 
     it('rtl', async () => {
       const { getAllByRole, user } = await render(
-        <ToggleButtonGroup.Root dir="rtl">
+        <ToggleButtonGroup.Root direction="rtl">
           <ToggleButtonGroup.Item value="one" />
           <ToggleButtonGroup.Item value="two" />
         </ToggleButtonGroup.Root>,
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
index b8dacb907a..d6c6b664bb 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
@@ -35,7 +35,7 @@ const ToggleButtonGroupRoot = React.forwardRef(function ToggleButtonGroupRoot(
   const {
     value: valueProp,
     defaultValue: defaultValueProp,
-    dir,
+    direction,
     disabled: disabledProp,
     toggleMultiple = false,
     onValueChange,
@@ -55,7 +55,7 @@ const ToggleButtonGroupRoot = React.forwardRef(function ToggleButtonGroupRoot(
   const { getRootProps, disabled, setGroupValue, value } = useToggleButtonGroupRoot({
     value: valueProp,
     defaultValue,
-    dir,
+    direction,
     disabled: disabledProp,
     toggleMultiple,
     onValueChange,
@@ -103,9 +103,9 @@ export namespace ToggleButtonGroupRoot {
   export interface Props
     extends Pick<
         UseToggleButtonGroupRoot.Parameters,
-        'value' | 'defaultValue' | 'onValueChange' | 'disabled' | 'toggleMultiple' | 'dir'
+        'value' | 'defaultValue' | 'onValueChange' | 'disabled' | 'toggleMultiple' | 'direction'
       >,
-      Omit<BaseUIComponentProps<'div', OwnerState>, 'defaultValue' | 'dir'> {
+      Omit<BaseUIComponentProps<'div', OwnerState>, 'defaultValue'> {
     /**
      * @default false
      */
@@ -136,7 +136,7 @@ ToggleButtonGroupRoot.propTypes /* remove-proptypes */ = {
    * Text direction
    * @default 'ltr'
    */
-  dir: PropTypes.oneOf(['ltr', 'rtl']),
+  direction: PropTypes.oneOf(['ltr', 'rtl']),
   /**
    * @default false
    */
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts b/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
index 5ce6329ca0..98a67cd6e4 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
@@ -11,7 +11,7 @@ export function useToggleButtonGroupRoot(
   const {
     value,
     defaultValue,
-    dir = 'ltr',
+    direction = 'ltr',
     disabled = false,
     onValueChange,
     toggleMultiple = false,
@@ -46,9 +46,9 @@ export function useToggleButtonGroupRoot(
     (externalProps = {}) =>
       mergeReactProps<'div'>(externalProps, {
         role: 'group',
-        dir,
+        dir: direction,
       }),
-    [dir],
+    [direction],
   );
 
   return React.useMemo(
@@ -101,7 +101,7 @@ export namespace UseToggleButtonGroupRoot {
      * Text direction
      * @default 'ltr'
      */
-    dir?: Direction;
+    direction?: Direction;
   }
 
   export interface ReturnValue {

From 5335ee4fecd6ef49743cadf818516a656f526862 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Thu, 21 Nov 2024 15:29:44 +0800
Subject: [PATCH 16/19] Use Composite for RTL detection

---
 .../ToggleButtonGroupRtl.js                   | 105 ++++-----
 .../ToggleButtonGroupRtl.tsx                  | 105 ++++-----
 .../toggle-button-group.mdx                   |  18 +-
 docs/src/app/experiments/toggle-group.tsx     | 220 ++++++++++--------
 docs/src/app/experiments/toggle.module.css    |  14 +-
 .../Root/useToggleButtonGroupRoot.ts          |   4 +-
 6 files changed, 258 insertions(+), 208 deletions(-)

diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js
index 757a320e83..56fe6c7c82 100644
--- a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.js
@@ -5,63 +5,64 @@ import classes from './styles.module.css';
 
 export default function ToggleButtonGroupRtl() {
   return (
-    <ToggleButtonGroup.Root
-      direction="rtl"
-      toggleMultiple
-      aria-label="Text formatting"
-      className={classes.root}
-    >
-      <ToggleButtonGroup.Item
-        value="bold"
-        aria-label="Toggle bold"
-        className={classes.button}
+    <div dir="rtl">
+      <ToggleButtonGroup.Root
+        toggleMultiple
+        aria-label="Text formatting"
+        className={classes.root}
       >
-        <svg
-          xmlns="http://www.w3.org/2000/svg"
-          width="24"
-          height="24"
-          viewBox="0 0 24 24"
-          className={classes.icon}
+        <ToggleButtonGroup.Item
+          value="bold"
+          aria-label="Toggle bold"
+          className={classes.button}
         >
-          <path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
-          <path d="M6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
-        </svg>
-      </ToggleButtonGroup.Item>
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            className={classes.icon}
+          >
+            <path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+            <path d="M6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+          </svg>
+        </ToggleButtonGroup.Item>
 
-      <ToggleButtonGroup.Item
-        value="italics"
-        aria-label="Toggle italics"
-        className={classes.button}
-      >
-        <svg
-          xmlns="http://www.w3.org/2000/svg"
-          width="24"
-          height="24"
-          viewBox="0 0 24 24"
-          className={classes.icon}
+        <ToggleButtonGroup.Item
+          value="italics"
+          aria-label="Toggle italics"
+          className={classes.button}
         >
-          <line x1="19" y1="4" x2="10" y2="4" />
-          <line x1="14" y1="20" x2="5" y2="20" />
-          <line x1="15" y1="4" x2="9" y2="20" />
-        </svg>
-      </ToggleButtonGroup.Item>
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            className={classes.icon}
+          >
+            <line x1="19" y1="4" x2="10" y2="4" />
+            <line x1="14" y1="20" x2="5" y2="20" />
+            <line x1="15" y1="4" x2="9" y2="20" />
+          </svg>
+        </ToggleButtonGroup.Item>
 
-      <ToggleButtonGroup.Item
-        value="underline"
-        aria-label="Toggle underline"
-        className={classes.button}
-      >
-        <svg
-          xmlns="http://www.w3.org/2000/svg"
-          width="24"
-          height="24"
-          viewBox="0 0 24 24"
-          className={classes.icon}
+        <ToggleButtonGroup.Item
+          value="underline"
+          aria-label="Toggle underline"
+          className={classes.button}
         >
-          <path d="M6 3v7a6 6 0 0 0 6 6 6 6 0 0 0 6-6V3" />
-          <line x1="4" y1="21" x2="20" y2="21" />
-        </svg>
-      </ToggleButtonGroup.Item>
-    </ToggleButtonGroup.Root>
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            className={classes.icon}
+          >
+            <path d="M6 3v7a6 6 0 0 0 6 6 6 6 0 0 0 6-6V3" />
+            <line x1="4" y1="21" x2="20" y2="21" />
+          </svg>
+        </ToggleButtonGroup.Item>
+      </ToggleButtonGroup.Root>
+    </div>
   );
 }
diff --git a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx
index 757a320e83..56fe6c7c82 100644
--- a/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx
+++ b/docs/data/components/toggle-button-group/ToggleButtonGroupRtl.tsx
@@ -5,63 +5,64 @@ import classes from './styles.module.css';
 
 export default function ToggleButtonGroupRtl() {
   return (
-    <ToggleButtonGroup.Root
-      direction="rtl"
-      toggleMultiple
-      aria-label="Text formatting"
-      className={classes.root}
-    >
-      <ToggleButtonGroup.Item
-        value="bold"
-        aria-label="Toggle bold"
-        className={classes.button}
+    <div dir="rtl">
+      <ToggleButtonGroup.Root
+        toggleMultiple
+        aria-label="Text formatting"
+        className={classes.root}
       >
-        <svg
-          xmlns="http://www.w3.org/2000/svg"
-          width="24"
-          height="24"
-          viewBox="0 0 24 24"
-          className={classes.icon}
+        <ToggleButtonGroup.Item
+          value="bold"
+          aria-label="Toggle bold"
+          className={classes.button}
         >
-          <path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
-          <path d="M6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
-        </svg>
-      </ToggleButtonGroup.Item>
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            className={classes.icon}
+          >
+            <path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+            <path d="M6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+          </svg>
+        </ToggleButtonGroup.Item>
 
-      <ToggleButtonGroup.Item
-        value="italics"
-        aria-label="Toggle italics"
-        className={classes.button}
-      >
-        <svg
-          xmlns="http://www.w3.org/2000/svg"
-          width="24"
-          height="24"
-          viewBox="0 0 24 24"
-          className={classes.icon}
+        <ToggleButtonGroup.Item
+          value="italics"
+          aria-label="Toggle italics"
+          className={classes.button}
         >
-          <line x1="19" y1="4" x2="10" y2="4" />
-          <line x1="14" y1="20" x2="5" y2="20" />
-          <line x1="15" y1="4" x2="9" y2="20" />
-        </svg>
-      </ToggleButtonGroup.Item>
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            className={classes.icon}
+          >
+            <line x1="19" y1="4" x2="10" y2="4" />
+            <line x1="14" y1="20" x2="5" y2="20" />
+            <line x1="15" y1="4" x2="9" y2="20" />
+          </svg>
+        </ToggleButtonGroup.Item>
 
-      <ToggleButtonGroup.Item
-        value="underline"
-        aria-label="Toggle underline"
-        className={classes.button}
-      >
-        <svg
-          xmlns="http://www.w3.org/2000/svg"
-          width="24"
-          height="24"
-          viewBox="0 0 24 24"
-          className={classes.icon}
+        <ToggleButtonGroup.Item
+          value="underline"
+          aria-label="Toggle underline"
+          className={classes.button}
         >
-          <path d="M6 3v7a6 6 0 0 0 6 6 6 6 0 0 0 6-6V3" />
-          <line x1="4" y1="21" x2="20" y2="21" />
-        </svg>
-      </ToggleButtonGroup.Item>
-    </ToggleButtonGroup.Root>
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            className={classes.icon}
+          >
+            <path d="M6 3v7a6 6 0 0 0 6 6 6 6 0 0 0 6-6V3" />
+            <line x1="4" y1="21" x2="20" y2="21" />
+          </svg>
+        </ToggleButtonGroup.Item>
+      </ToggleButtonGroup.Root>
+    </div>
   );
 }
diff --git a/docs/data/components/toggle-button-group/toggle-button-group.mdx b/docs/data/components/toggle-button-group/toggle-button-group.mdx
index b71ef6321c..adc563dd8e 100644
--- a/docs/data/components/toggle-button-group/toggle-button-group.mdx
+++ b/docs/data/components/toggle-button-group/toggle-button-group.mdx
@@ -108,10 +108,22 @@ return (
 
 ## RTL
 
-Use the `direction` prop to configure a RTL toggle button group:
+Place the toggle button group in a HTML element or component with the `dir="rtl"` attribute to reverse directional keys for RTL languages:
+
+```jsx
+<html dir="rtl">
+  <body>
+    <ToggleButtonGroup.Root /> {/* RTL */}
+  </body>
+<html>
+```
 
-```tsx
-<ToggleButtonGroup.Root direction="rtl">{/* toggle buttons */}</ToggleButtonGroup.Root>
+The `direction` prop can override this:
+
+```jsx
+<div dir="ltr">
+  <ToggleButtonGroup.Root direction="rtl" /> {/* RTL */}
+<div>
 ```
 
 <Demo demo="ToggleButtonGroupRtl" />
diff --git a/docs/src/app/experiments/toggle-group.tsx b/docs/src/app/experiments/toggle-group.tsx
index c72eee032c..552670f668 100644
--- a/docs/src/app/experiments/toggle-group.tsx
+++ b/docs/src/app/experiments/toggle-group.tsx
@@ -12,6 +12,7 @@ export default function ToggleButtonGroupDemo() {
       <ToggleButtonGroup.Root
         value={value}
         onValueChange={(newValue) => {
+          // one button must always remain pressed
           if (newValue.length > 0) {
             setValue(newValue);
           }
@@ -24,18 +25,7 @@ export default function ToggleButtonGroupDemo() {
           aria-label="Align left"
           className={classes.button}
         >
-          <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="24"
-            height="24"
-            viewBox="0 0 24 24"
-            className={classes.icon}
-          >
-            <line x1="17" y1="10" x2="3" y2="10" />
-            <line x1="21" y1="6" x2="3" y2="6" />
-            <line x1="21" y1="14" x2="3" y2="14" />
-            <line x1="17" y1="18" x2="3" y2="18" />
-          </svg>
+          <AlignLeftIcon />
         </ToggleButtonGroup.Item>
 
         <ToggleButtonGroup.Item
@@ -43,18 +33,7 @@ export default function ToggleButtonGroupDemo() {
           aria-label="Align center"
           className={classes.button}
         >
-          <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="24"
-            height="24"
-            viewBox="0 0 24 24"
-            className={classes.icon}
-          >
-            <line x1="18" y1="10" x2="6" y2="10" />
-            <line x1="21" y1="6" x2="3" y2="6" />
-            <line x1="21" y1="14" x2="3" y2="14" />
-            <line x1="18" y1="18" x2="6" y2="18" />
-          </svg>
+          <AlignCenterIcon />
         </ToggleButtonGroup.Item>
 
         <ToggleButtonGroup.Item
@@ -62,81 +41,138 @@ export default function ToggleButtonGroupDemo() {
           aria-label="Align right"
           className={classes.button}
         >
-          <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="24"
-            height="24"
-            viewBox="0 0 24 24"
-            className={classes.icon}
-          >
-            <line x1="21" y1="10" x2="7" y2="10" />
-            <line x1="21" y1="6" x2="3" y2="6" />
-            <line x1="21" y1="14" x2="3" y2="14" />
-            <line x1="21" y1="18" x2="7" y2="18" />
-          </svg>
+          <AlignRightIcon />
         </ToggleButtonGroup.Item>
       </ToggleButtonGroup.Root>
 
       <h4 style={{ margin: 0 }}>RTL</h4>
 
-      <ToggleButtonGroup.Root
-        toggleMultiple
-        aria-label="Text formatting"
-        direction="rtl"
-        className={classes.group}
-      >
-        <ToggleButtonGroup.Item
-          value="bold"
-          aria-label="Toggle bold"
-          className={classes.button}
-        >
-          <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="24"
-            height="24"
-            viewBox="0 0 24 24"
-            className={classes.icon}
-          >
-            <path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
-            <path d="M6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
-          </svg>
-        </ToggleButtonGroup.Item>
+      <div dir="rtl">
+        <div>
+          <div>
+            <ToggleButtonGroup.Root
+              toggleMultiple
+              aria-label="Text formatting"
+              className={classes.group}
+            >
+              <ToggleButtonGroup.Item
+                value="bold"
+                aria-label="Toggle bold"
+                className={classes.button}
+              >
+                <BoldIcon />
+              </ToggleButtonGroup.Item>
 
-        <ToggleButtonGroup.Item
-          value="italics"
-          aria-label="Toggle italics"
-          className={classes.button}
-        >
-          <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="24"
-            height="24"
-            viewBox="0 0 24 24"
-            className={classes.icon}
-          >
-            <line x1="19" y1="4" x2="10" y2="4" />
-            <line x1="14" y1="20" x2="5" y2="20" />
-            <line x1="15" y1="4" x2="9" y2="20" />
-          </svg>
-        </ToggleButtonGroup.Item>
+              <ToggleButtonGroup.Item
+                value="italics"
+                aria-label="Toggle italics"
+                className={classes.button}
+              >
+                <ItalicsIcon />
+              </ToggleButtonGroup.Item>
 
-        <ToggleButtonGroup.Item
-          value="underline"
-          aria-label="Toggle underline"
-          className={classes.button}
-        >
-          <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="24"
-            height="24"
-            viewBox="0 0 24 24"
-            className={classes.icon}
-          >
-            <path d="M6 3v7a6 6 0 0 0 6 6 6 6 0 0 0 6-6V3" />
-            <line x1="4" y1="21" x2="20" y2="21" />
-          </svg>
-        </ToggleButtonGroup.Item>
-      </ToggleButtonGroup.Root>
+              <ToggleButtonGroup.Item
+                value="underline"
+                aria-label="Toggle underline"
+                className={classes.button}
+              >
+                <UnderlineIcon />
+              </ToggleButtonGroup.Item>
+            </ToggleButtonGroup.Root>
+          </div>
+        </div>
+      </div>
     </div>
   );
 }
+
+function AlignLeftIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+    >
+      <line x1="17" y1="10" x2="3" y2="10" />
+      <line x1="21" y1="6" x2="3" y2="6" />
+      <line x1="21" y1="14" x2="3" y2="14" />
+      <line x1="17" y1="18" x2="3" y2="18" />
+    </svg>
+  );
+}
+
+function AlignCenterIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+    >
+      <line x1="18" y1="10" x2="6" y2="10" />
+      <line x1="21" y1="6" x2="3" y2="6" />
+      <line x1="21" y1="14" x2="3" y2="14" />
+      <line x1="18" y1="18" x2="6" y2="18" />
+    </svg>
+  );
+}
+
+function AlignRightIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+    >
+      <line x1="21" y1="10" x2="7" y2="10" />
+      <line x1="21" y1="6" x2="3" y2="6" />
+      <line x1="21" y1="14" x2="3" y2="14" />
+      <line x1="21" y1="18" x2="7" y2="18" />
+    </svg>
+  );
+}
+
+function BoldIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+    >
+      <path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+      <path d="M6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+    </svg>
+  );
+}
+
+function ItalicsIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+    >
+      <line x1="19" y1="4" x2="10" y2="4" />
+      <line x1="14" y1="20" x2="5" y2="20" />
+      <line x1="15" y1="4" x2="9" y2="20" />
+    </svg>
+  );
+}
+
+function UnderlineIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+    >
+      <path d="M6 3v7a6 6 0 0 0 6 6 6 6 0 0 0 6-6V3" />
+      <line x1="4" y1="21" x2="20" y2="21" />
+    </svg>
+  );
+}
diff --git a/docs/src/app/experiments/toggle.module.css b/docs/src/app/experiments/toggle.module.css
index f98692a217..3aad075232 100644
--- a/docs/src/app/experiments/toggle.module.css
+++ b/docs/src/app/experiments/toggle.module.css
@@ -11,8 +11,8 @@
   --size: 2.5rem;
   --corner-radius: 0.4rem;
   --border-color: var(--gray-outline-2);
-  --border-radius-visual-right: 0 var(--corner-radius) var(--corner-radius) 0;
-  --border-radius-visual-left: var(--corner-radius) 0 0 var(--corner-radius);
+  --border-radius-right: 0 var(--corner-radius) var(--corner-radius) 0;
+  --border-radius-left: var(--corner-radius) 0 0 var(--corner-radius);
 
   display: flex;
   flex-flow: row nowrap;
@@ -30,21 +30,21 @@
 }
 
 .button:first-child {
-  border-radius: var(--border-radius-visual-left);
+  border-radius: var(--border-radius-left);
   border-right-color: transparent;
 }
 
 .button:last-child {
-  border-radius: var(--border-radius-visual-right);
+  border-radius: var(--border-radius-right);
   border-left-color: transparent;
 }
 
 [dir='rtl'] .button:first-child {
-  border-radius: var(--border-radius-visual-right);
+  border-radius: var(--border-radius-right);
 }
 
 [dir='rtl'] .button:last-child {
-  border-radius: var(--border-radius-visual-left);
+  border-radius: var(--border-radius-left);
 }
 
 .button:not(:disabled):hover {
@@ -61,7 +61,7 @@
   z-index: 1;
 }
 
-.icon {
+.button svg {
   fill: none;
   stroke: currentColor;
   stroke-width: 2;
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts b/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
index 98a67cd6e4..2ff75a6804 100644
--- a/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
+++ b/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
@@ -46,9 +46,9 @@ export function useToggleButtonGroupRoot(
     (externalProps = {}) =>
       mergeReactProps<'div'>(externalProps, {
         role: 'group',
-        dir: direction,
+        // dir: direction,
       }),
-    [direction],
+    [],
   );
 
   return React.useMemo(

From 5ee7939ff51d6500e5d501d65046309c491a553d Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Thu, 21 Nov 2024 17:37:30 +0800
Subject: [PATCH 17/19] Move to new package dir

---
 .../src/ToggleButton/Root/ToggleButtonRoot.test.tsx               | 0
 .../src/ToggleButton/Root/ToggleButtonRoot.tsx                    | 0
 .../src/ToggleButton/Root/useToggleButtonRoot.ts                  | 0
 packages/{mui-base => react}/src/ToggleButton/index.parts.ts      | 0
 packages/{mui-base => react}/src/ToggleButton/index.ts            | 0
 .../src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx     | 0
 .../src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx          | 0
 .../src/ToggleButtonGroup/Item/useToggleButtonGroupItem.ts        | 0
 .../src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx     | 0
 .../src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx          | 0
 .../src/ToggleButtonGroup/Root/ToggleButtonGroupRootContext.ts    | 0
 .../src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts        | 0
 packages/{mui-base => react}/src/ToggleButtonGroup/index.parts.ts | 0
 packages/{mui-base => react}/src/ToggleButtonGroup/index.ts       | 0
 14 files changed, 0 insertions(+), 0 deletions(-)
 rename packages/{mui-base => react}/src/ToggleButton/Root/ToggleButtonRoot.test.tsx (100%)
 rename packages/{mui-base => react}/src/ToggleButton/Root/ToggleButtonRoot.tsx (100%)
 rename packages/{mui-base => react}/src/ToggleButton/Root/useToggleButtonRoot.ts (100%)
 rename packages/{mui-base => react}/src/ToggleButton/index.parts.ts (100%)
 rename packages/{mui-base => react}/src/ToggleButton/index.ts (100%)
 rename packages/{mui-base => react}/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx (100%)
 rename packages/{mui-base => react}/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx (100%)
 rename packages/{mui-base => react}/src/ToggleButtonGroup/Item/useToggleButtonGroupItem.ts (100%)
 rename packages/{mui-base => react}/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx (100%)
 rename packages/{mui-base => react}/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx (100%)
 rename packages/{mui-base => react}/src/ToggleButtonGroup/Root/ToggleButtonGroupRootContext.ts (100%)
 rename packages/{mui-base => react}/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts (100%)
 rename packages/{mui-base => react}/src/ToggleButtonGroup/index.parts.ts (100%)
 rename packages/{mui-base => react}/src/ToggleButtonGroup/index.ts (100%)

diff --git a/packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.test.tsx b/packages/react/src/ToggleButton/Root/ToggleButtonRoot.test.tsx
similarity index 100%
rename from packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.test.tsx
rename to packages/react/src/ToggleButton/Root/ToggleButtonRoot.test.tsx
diff --git a/packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.tsx b/packages/react/src/ToggleButton/Root/ToggleButtonRoot.tsx
similarity index 100%
rename from packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.tsx
rename to packages/react/src/ToggleButton/Root/ToggleButtonRoot.tsx
diff --git a/packages/mui-base/src/ToggleButton/Root/useToggleButtonRoot.ts b/packages/react/src/ToggleButton/Root/useToggleButtonRoot.ts
similarity index 100%
rename from packages/mui-base/src/ToggleButton/Root/useToggleButtonRoot.ts
rename to packages/react/src/ToggleButton/Root/useToggleButtonRoot.ts
diff --git a/packages/mui-base/src/ToggleButton/index.parts.ts b/packages/react/src/ToggleButton/index.parts.ts
similarity index 100%
rename from packages/mui-base/src/ToggleButton/index.parts.ts
rename to packages/react/src/ToggleButton/index.parts.ts
diff --git a/packages/mui-base/src/ToggleButton/index.ts b/packages/react/src/ToggleButton/index.ts
similarity index 100%
rename from packages/mui-base/src/ToggleButton/index.ts
rename to packages/react/src/ToggleButton/index.ts
diff --git a/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx b/packages/react/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx
similarity index 100%
rename from packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx
rename to packages/react/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.test.tsx
diff --git a/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx b/packages/react/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx
similarity index 100%
rename from packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx
rename to packages/react/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx
diff --git a/packages/mui-base/src/ToggleButtonGroup/Item/useToggleButtonGroupItem.ts b/packages/react/src/ToggleButtonGroup/Item/useToggleButtonGroupItem.ts
similarity index 100%
rename from packages/mui-base/src/ToggleButtonGroup/Item/useToggleButtonGroupItem.ts
rename to packages/react/src/ToggleButtonGroup/Item/useToggleButtonGroupItem.ts
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx b/packages/react/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
similarity index 100%
rename from packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
rename to packages/react/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.test.tsx
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx b/packages/react/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
similarity index 100%
rename from packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
rename to packages/react/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRootContext.ts b/packages/react/src/ToggleButtonGroup/Root/ToggleButtonGroupRootContext.ts
similarity index 100%
rename from packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRootContext.ts
rename to packages/react/src/ToggleButtonGroup/Root/ToggleButtonGroupRootContext.ts
diff --git a/packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts b/packages/react/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
similarity index 100%
rename from packages/mui-base/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
rename to packages/react/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
diff --git a/packages/mui-base/src/ToggleButtonGroup/index.parts.ts b/packages/react/src/ToggleButtonGroup/index.parts.ts
similarity index 100%
rename from packages/mui-base/src/ToggleButtonGroup/index.parts.ts
rename to packages/react/src/ToggleButtonGroup/index.parts.ts
diff --git a/packages/mui-base/src/ToggleButtonGroup/index.ts b/packages/react/src/ToggleButtonGroup/index.ts
similarity index 100%
rename from packages/mui-base/src/ToggleButtonGroup/index.ts
rename to packages/react/src/ToggleButtonGroup/index.ts

From 4ff9fc2ee99457b2fea94eae9bac8d8165780b18 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Thu, 21 Nov 2024 18:14:21 +0800
Subject: [PATCH 18/19] Fix proptypes and docs

---
 docs/data/api/toggle-button-group-item.json   |  2 +-
 docs/data/api/toggle-button-group-root.json   |  2 +-
 docs/data/api/toggle-button-root.json         |  2 +-
 .../generated/toggle-button-group-item.json   | 31 ++++++++++++++
 .../generated/toggle-button-group-root.json   | 36 ++++++++++++++++
 .../generated/toggle-button-root.json         | 41 +++++++++++++++++++
 .../ToggleButton/Root/ToggleButtonRoot.tsx    |  4 +-
 .../Item/ToggleButtonGroupItem.tsx            |  4 +-
 .../Root/ToggleButtonGroupRoot.tsx            |  4 +-
 9 files changed, 117 insertions(+), 9 deletions(-)
 create mode 100644 docs/reference/generated/toggle-button-group-item.json
 create mode 100644 docs/reference/generated/toggle-button-group-root.json
 create mode 100644 docs/reference/generated/toggle-button-root.json

diff --git a/docs/data/api/toggle-button-group-item.json b/docs/data/api/toggle-button-group-item.json
index de40528965..beedd1982d 100644
--- a/docs/data/api/toggle-button-group-item.json
+++ b/docs/data/api/toggle-button-group-item.json
@@ -22,7 +22,7 @@
   "themeDefaultProps": true,
   "muiName": "ToggleButtonGroupItem",
   "forwardsRefTo": "HTMLButtonElement",
-  "filename": "/packages/mui-base/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx",
+  "filename": "/packages/react/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx",
   "inheritance": null,
   "demos": "<ul><li><a href=\"/components/react-toggle-button-group/\">ToggleButtonGroup</a></li></ul>",
   "cssComponent": false
diff --git a/docs/data/api/toggle-button-group-root.json b/docs/data/api/toggle-button-group-root.json
index fdc1f645fc..ea5ac76f12 100644
--- a/docs/data/api/toggle-button-group-root.json
+++ b/docs/data/api/toggle-button-group-root.json
@@ -26,7 +26,7 @@
   "themeDefaultProps": true,
   "muiName": "ToggleButtonGroupRoot",
   "forwardsRefTo": "HTMLDivElement",
-  "filename": "/packages/mui-base/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx",
+  "filename": "/packages/react/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx",
   "inheritance": null,
   "demos": "<ul><li><a href=\"/components/react-toggle-button-group/\">ToggleButtonGroup</a></li></ul>",
   "cssComponent": false
diff --git a/docs/data/api/toggle-button-root.json b/docs/data/api/toggle-button-root.json
index 45ba057814..b06930d80e 100644
--- a/docs/data/api/toggle-button-root.json
+++ b/docs/data/api/toggle-button-root.json
@@ -24,7 +24,7 @@
   "themeDefaultProps": true,
   "muiName": "ToggleButtonRoot",
   "forwardsRefTo": "HTMLButtonElement",
-  "filename": "/packages/mui-base/src/ToggleButton/Root/ToggleButtonRoot.tsx",
+  "filename": "/packages/react/src/ToggleButton/Root/ToggleButtonRoot.tsx",
   "inheritance": null,
   "demos": "<ul><li><a href=\"/components/react-toggle-button/\">ToggleButton</a></li></ul>",
   "cssComponent": false
diff --git a/docs/reference/generated/toggle-button-group-item.json b/docs/reference/generated/toggle-button-group-item.json
new file mode 100644
index 0000000000..69a7f9b657
--- /dev/null
+++ b/docs/reference/generated/toggle-button-group-item.json
@@ -0,0 +1,31 @@
+{
+  "name": "ToggleButtonGroupItem",
+  "description": "",
+  "props": {
+    "value": {
+      "type": "string",
+      "required": true,
+      "description": "A unique string that identifies the component when used\ninside a ToggleButtonGroup"
+    },
+    "aria-label": {
+      "type": "string",
+      "description": "The label for the toggle button."
+    },
+    "aria-labelledby": {
+      "type": "string",
+      "description": "An id or space-separated list of ids of elements that label the toggle button."
+    },
+    "className": {
+      "type": "string | (state) => string",
+      "description": "Class names applied to the element or a function that returns them based on the component's state."
+    },
+    "onPressedChange": {
+      "type": "function(pressed: boolean, event: Event) => void",
+      "description": "Callback fired when the pressed state is changed."
+    },
+    "render": {
+      "type": "React.ReactElement | (props, state) => React.ReactElement",
+      "description": "A function to customize rendering of the component."
+    }
+  }
+}
diff --git a/docs/reference/generated/toggle-button-group-root.json b/docs/reference/generated/toggle-button-group-root.json
new file mode 100644
index 0000000000..52a942eb9a
--- /dev/null
+++ b/docs/reference/generated/toggle-button-group-root.json
@@ -0,0 +1,36 @@
+{
+  "name": "ToggleButtonGroupRoot",
+  "description": "",
+  "props": {
+    "className": {
+      "type": "string | (state) => string",
+      "description": "Class names applied to the element or a function that returns them based on the component's state."
+    },
+    "defaultValue": {
+      "type": "string[]",
+      "description": "The open state of the ToggleButtonGroup represented by an array of\nthe values of all pressed `<ToggleButtonGroup.Item/>`s\nThis is the uncontrolled counterpart of `value`."
+    },
+    "direction": {
+      "type": "'ltr' | 'rtl'",
+      "default": "'ltr'",
+      "description": "Text direction"
+    },
+    "onValueChange": {
+      "type": "function(groupValue: Array<string>, event: Event) => void",
+      "description": "Callback fired when the pressed states of the ToggleButtonGroup changes."
+    },
+    "render": {
+      "type": "React.ReactElement | (props, state) => React.ReactElement",
+      "description": "A function to customize rendering of the component."
+    },
+    "toggleMultiple": {
+      "type": "boolean",
+      "default": "false",
+      "description": "When `false` only one item in the group can be pressed. If any item in\nthe group becomes pressed, the others will become unpressed.\nWhen `true` multiple items can be pressed."
+    },
+    "value": {
+      "type": "string[]",
+      "description": "The open state of the ToggleButtonGroup represented by an array of\nthe values of all pressed `<ToggleButtonGroup.Item/>`s\nThis is the controlled counterpart of `defaultValue`."
+    }
+  }
+}
diff --git a/docs/reference/generated/toggle-button-root.json b/docs/reference/generated/toggle-button-root.json
new file mode 100644
index 0000000000..b481de2adc
--- /dev/null
+++ b/docs/reference/generated/toggle-button-root.json
@@ -0,0 +1,41 @@
+{
+  "name": "ToggleButtonRoot",
+  "description": "",
+  "props": {
+    "aria-label": {
+      "type": "string",
+      "description": "The label for the ToggleButton."
+    },
+    "aria-labelledby": {
+      "type": "string",
+      "description": "An id or space-separated list of ids of elements that label the ToggleButton."
+    },
+    "className": {
+      "type": "string | (state) => string",
+      "description": "Class names applied to the element or a function that returns them based on the component's state."
+    },
+    "defaultPressed": {
+      "type": "boolean",
+      "default": "false",
+      "description": "The default pressed state. Use when the component is not controlled."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": "false",
+      "description": "If `true`, the component is disabled."
+    },
+    "onPressedChange": {
+      "type": "function(pressed: boolean, event: Event) => void",
+      "description": "Callback fired when the pressed state is changed."
+    },
+    "pressed": {
+      "type": "boolean",
+      "default": "undefined",
+      "description": "If `true`, the component is pressed."
+    },
+    "render": {
+      "type": "React.ReactElement | (props, state) => React.ReactElement",
+      "description": "A function to customize rendering of the component."
+    }
+  }
+}
diff --git a/packages/react/src/ToggleButton/Root/ToggleButtonRoot.tsx b/packages/react/src/ToggleButton/Root/ToggleButtonRoot.tsx
index 47ae64c2d4..2af4a04ec9 100644
--- a/packages/react/src/ToggleButton/Root/ToggleButtonRoot.tsx
+++ b/packages/react/src/ToggleButton/Root/ToggleButtonRoot.tsx
@@ -13,11 +13,11 @@ const customStyleHookMapping = {
  *
  * Demos:
  *
- * - [ToggleButton](https://base-ui.netlify.app/components/react-toggle-button/)
+ * - [ToggleButton](https://base-ui.com/components/react-toggle-button/)
  *
  * API:
  *
- * - [ToggleButtonRoot API](https://base-ui.netlify.app/components/react-toggle-button/#api-reference-ToggleButtonRoot)
+ * - [ToggleButtonRoot API](https://base-ui.com/components/react-toggle-button/#api-reference-ToggleButtonRoot)
  */
 const ToggleButtonRoot = React.forwardRef(function ToggleButtonRoot(
   props: ToggleButtonRoot.Props,
diff --git a/packages/react/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx b/packages/react/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx
index 752a680039..0ee5f34db1 100644
--- a/packages/react/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx
+++ b/packages/react/src/ToggleButtonGroup/Item/ToggleButtonGroupItem.tsx
@@ -14,11 +14,11 @@ const customStyleHookMapping = {
  *
  * Demos:
  *
- * - [ToggleButtonGroup](https://base-ui.netlify.app/components/react-toggle-button-group/)
+ * - [ToggleButtonGroup](https://base-ui.com/components/react-toggle-button-group/)
  *
  * API:
  *
- * - [ToggleButtonGroupItem API](https://base-ui.netlify.app/components/react-toggle-button-group/#api-reference-ToggleButtonGroupItem)
+ * - [ToggleButtonGroupItem API](https://base-ui.com/components/react-toggle-button-group/#api-reference-ToggleButtonGroupItem)
  */
 const ToggleButtonGroupItem = React.forwardRef(function ToggleButtonGroupItem(
   props: ToggleButtonGroupItem.Props,
diff --git a/packages/react/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx b/packages/react/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
index d6c6b664bb..afe136ac11 100644
--- a/packages/react/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
+++ b/packages/react/src/ToggleButtonGroup/Root/ToggleButtonGroupRoot.tsx
@@ -22,11 +22,11 @@ const customStyleHookMapping = {
  *
  * Demos:
  *
- * - [ToggleButtonGroup](https://base-ui.netlify.app/components/react-toggle-button-group/)
+ * - [ToggleButtonGroup](https://base-ui.com/components/react-toggle-button-group/)
  *
  * API:
  *
- * - [ToggleButtonGroupRoot API](https://base-ui.netlify.app/components/react-toggle-button-group/#api-reference-ToggleButtonGroupRoot)
+ * - [ToggleButtonGroupRoot API](https://base-ui.com/components/react-toggle-button-group/#api-reference-ToggleButtonGroupRoot)
  */
 const ToggleButtonGroupRoot = React.forwardRef(function ToggleButtonGroupRoot(
   props: ToggleButtonGroupRoot.Props,

From e0296ad1d4edb6f16790c08fcc8d33cbc03516ba Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Thu, 21 Nov 2024 18:26:19 +0800
Subject: [PATCH 19/19] Fix eslint

---
 .../src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts b/packages/react/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
index 2ff75a6804..ef3918ec30 100644
--- a/packages/react/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
+++ b/packages/react/src/ToggleButtonGroup/Root/useToggleButtonGroupRoot.ts
@@ -11,7 +11,7 @@ export function useToggleButtonGroupRoot(
   const {
     value,
     defaultValue,
-    direction = 'ltr',
+    // direction = 'ltr',
     disabled = false,
     onValueChange,
     toggleMultiple = false,