Make hiddenUntilFound override keepMounted

docs/data/components/accordion/accordion.mdx

@@ -205,12 +205,10 @@ Alternatively `keepMounted` can be passed to `Accordion.Panel`s directly to enab
 Content hidden by `Accordion.Panel` components can be made accessible only to a browser's find-in-page functionality with the `hiddenUntilFound` prop to improve searchability:
 
 ```jsx
-<Accordion.Root hiddenUntilFound keepMounted>
-  {/* accordion items */}
-</Accordion.Root>
+<Accordion.Root hiddenUntilFound>{/* accordion items */}</Accordion.Root>
 ```
 
-Be aware that this must be used together with `keepMounted`.
+When `hiddenUntilFound` is used, `Accordion.Panel`s will remain mounted even when closed, overriding the `keepMounted` prop on the root or the panel.
 
 Alternatively `hiddenUntilFound` can be passed to `Accordion.Panel`s directly to enable this for only one `Item` instead of the whole accordion.
 

docs/data/components/collapsible/collapsible.mdx

@@ -57,14 +57,14 @@ Content hidden in the `Collapsible.Panel` component can be made accessible only
 ```jsx
 <Collapsible.Root>
   <Collapsible.Trigger>Toggle</Collapsible.Trigger>
-  <Collapsible.Panel hiddenUntilFound keepMounted>
+  <Collapsible.Panel hiddenUntilFound>
     When this component is closed, this sentence will only be accessible to the browser's native
     find-in-page functionality
   </Collapsible.Panel>
 </Collapsible.Root>
 ```
 
-Be aware that this must be used together with `keepMounted`.
+When `hiddenUntilFound` is used, the `Panel` remains mounted even when closed, overriding the `keepMounted` prop.
 
 We recommend using [CSS animations](#css-animations) for animated collapsibles that use this feature. Currently there is browser bug that does not highlight the found text inside elements that have a [CSS transition](#css-transitions) applied.
 

docs/data/translations/api-docs/collapsible-panel/collapsible-panel.json

@@ -5,10 +5,10 @@
       "description": "Class names applied to the element or a function that returns them based on the component's state."
     },
     "hiddenUntilFound": {
-      "description": "If <code>true</code>, sets <code>hidden=&quot;until-found&quot;</code> when closed. Requires setting <code>keepMounted</code> to <code>true</code>. If <code>false</code>, sets <code>hidden</code> when closed."
+      "description": "If <code>true</code>, sets the hidden state using <code>hidden=&quot;until-found&quot;</code>. The panel remains mounted in the DOM when closed and overrides <code>keepMounted</code>. If <code>false</code>, sets the hidden state using <code>hidden</code>."
     },
     "keepMounted": {
-      "description": "If <code>true</code>, the panel remains mounted when closed and is instead hidden using the <code>hidden</code> attribute If <code>false</code>, the panel is unmounted when closed."
+      "description": "If <code>true</code>, the panel remains mounted when closed and is instead hidden using the <code>hidden</code> attribute If <code>false</code>, the panel is unmounted when closed. If the <code>hiddenUntilFound</code> prop is used, the panel overrides this prop and is remains mounted when closed."
     },
     "render": { "description": "A function to customize rendering of the component." }
   },

docs/src/app/experiments/collapsible-hidden-until-found.tsx

@@ -51,7 +51,6 @@ export default function CollapsibleHiddenUntilFound() {
           </Collapsible.Trigger>
           <Collapsible.Panel
             hiddenUntilFound
-            keepMounted
             className={classNames(classes.panel, classes.animation)}
           >
             <p>This is the collapsed content</p>
@@ -66,7 +65,6 @@ export default function CollapsibleHiddenUntilFound() {
           </Collapsible.Trigger>
           <Collapsible.Panel
             hiddenUntilFound
-            keepMounted
             className={classNames(classes.panel, classes.transition)}
           >
             <p>This is the collapsed content</p>

packages/mui-base/src/Accordion/Panel/AccordionPanel.tsx

@@ -40,6 +40,17 @@ const AccordionPanel = React.forwardRef(function AccordionPanel(
 
   const { hiddenUntilFound, keepMounted } = useAccordionRootContext();
 
+  if (process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    React.useEffect(() => {
+      if (keepMountedProp === false && (hiddenUntilFoundProp ?? hiddenUntilFound)) {
+        console.warn(
+          'Base UI: The `keepMounted={false}` prop on a Accordion.Panel will be ignored when using `hiddenUntilFound` on the Panel or the Root since it requires the panel to remain mounted when closed.',
+        );
+      }
+    }, [hiddenUntilFoundProp, hiddenUntilFound, keepMountedProp]);
+  }
+
   const { getRootProps, height, width, isOpen } = useCollapsiblePanel({
     animated,
     hiddenUntilFound: hiddenUntilFoundProp || hiddenUntilFound,
@@ -72,7 +83,7 @@ const AccordionPanel = React.forwardRef(function AccordionPanel(
     customStyleHookMapping: accordionStyleHookMapping,
   });
 
-  if (!(keepMountedProp || keepMounted) && !isOpen) {
+  if (!(keepMountedProp ?? keepMounted) && !isOpen) {
     return null;
   }
 

packages/mui-base/src/Accordion/Root/AccordionRoot.tsx

@@ -30,8 +30,8 @@ const AccordionRoot = React.forwardRef(function AccordionRoot(
     className,
     direction,
     disabled = false,
-    hiddenUntilFound = false,
-    keepMounted = false,
+    hiddenUntilFound: hiddenUntilFoundProp,
+    keepMounted: keepMountedProp,
     loop,
     onValueChange,
     openMultiple = true,
@@ -42,6 +42,17 @@ const AccordionRoot = React.forwardRef(function AccordionRoot(
     ...otherProps
   } = props;
 
+  if (process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    React.useEffect(() => {
+      if (hiddenUntilFoundProp && keepMountedProp === false) {
+        console.warn(
+          'Base UI: The `keepMounted={false}` prop on a Accordion.Root will be ignored when using `hiddenUntilFound` since it requires Panels to remain mounted when closed.',
+        );
+      }
+    }, [hiddenUntilFoundProp, keepMountedProp]);
+  }
+
   // memoized to allow omitting both defaultValue and value
   // which would otherwise trigger a warning in useControlled
   const defaultValue = React.useMemo(() => {
@@ -76,11 +87,11 @@ const AccordionRoot = React.forwardRef(function AccordionRoot(
   const contextValue: AccordionRootContext = React.useMemo(
     () => ({
       ...accordion,
-      hiddenUntilFound,
-      keepMounted,
+      hiddenUntilFound: hiddenUntilFoundProp ?? false,
+      keepMounted: keepMountedProp ?? false,
       ownerState,
     }),
-    [accordion, hiddenUntilFound, keepMounted, ownerState],
+    [accordion, hiddenUntilFoundProp, keepMountedProp, ownerState],
   );
 
   const { renderElement } = useComponentRenderer({

packages/mui-base/src/Collapsible/Panel/CollapsiblePanel.test.tsx

@@ -95,9 +95,7 @@ describe('<Collapsible.Panel />', () => {
       const { queryByText } = await render(
         <Collapsible.Root defaultOpen={false} animated={false} onOpenChange={handleOpenChange}>
           <Collapsible.Trigger />
-          <Collapsible.Panel hiddenUntilFound keepMounted>
-            This is panel content
-          </Collapsible.Panel>
+          <Collapsible.Panel hiddenUntilFound>This is panel content</Collapsible.Panel>
         </Collapsible.Root>,
       );
 
@@ -114,5 +112,23 @@ describe('<Collapsible.Panel />', () => {
       expect(handleOpenChange.callCount).to.equal(1);
       expect(panel).to.have.attribute('data-open');
     });
+
+    // toWarnDev doesn't work reliably with async rendering. To re-enable after it's fixed in the test-utils.
+    // eslint-disable-next-line mocha/no-skipped-tests
+    it.skip('warns when setting both `hiddenUntilFound` and `keepMounted={false}`', async function test() {
+      await expect(() =>
+        render(
+          <Collapsible.Root animated={false}>
+            <Collapsible.Trigger />
+            <Collapsible.Panel hiddenUntilFound keepMounted={false}>
+              This is panel content
+            </Collapsible.Panel>
+          </Collapsible.Root>,
+        ),
+      ).toWarnDev([
+        'Base UI: The `keepMounted={false}` prop on a Collapsible will be ignored when using `hiddenUntilFound` since it requires the Panel to remain mounted even when closed.',
+        'Base UI: The `keepMounted={false}` prop on a Collapsible will be ignored when using `hiddenUntilFound` since it requires the Panel to remain mounted even when closed.',
+      ]);
+    });
   });
 });

packages/mui-base/src/Collapsible/Panel/CollapsiblePanel.tsx

@@ -22,7 +22,26 @@ const CollapsiblePanel = React.forwardRef(function CollapsiblePanel(
   props: CollapsiblePanel.Props,
   forwardedRef: React.ForwardedRef<HTMLButtonElement>,
 ) {
-  const { className, hiddenUntilFound, keepMounted = false, render, ...otherProps } = props;
+  const {
+    className,
+    hiddenUntilFound,
+    keepMounted: keepMountedProp,
+    render,
+    ...otherProps
+  } = props;
+
+  if (process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    React.useEffect(() => {
+      if (hiddenUntilFound && keepMountedProp === false) {
+        console.warn(
+          'Base UI: The `keepMounted={false}` prop on a Collapsible will be ignored when using `hiddenUntilFound` since it requires the Panel to remain mounted even when closed.',
+        );
+      }
+    }, [hiddenUntilFound, keepMountedProp]);
+  }
+
+  const keepMounted = keepMountedProp ?? false;
 
   const { animated, mounted, open, panelId, setPanelId, setMounted, setOpen, ownerState } =
     useCollapsibleRootContext();
@@ -55,7 +74,7 @@ const CollapsiblePanel = React.forwardRef(function CollapsiblePanel(
     customStyleHookMapping: collapsibleStyleHookMapping,
   });
 
-  if (!keepMounted && !isOpen) {
+  if (!keepMounted && !isOpen && !hiddenUntilFound) {
     return null;
   }
 
@@ -72,6 +91,8 @@ namespace CollapsiblePanel {
      * If `true`, the panel remains mounted when closed and is instead
      * hidden using the `hidden` attribute
      * If `false`, the panel is unmounted when closed.
+     * If the `hiddenUntilFound` prop is used, the panel overrides this prop and
+     * is remains mounted when closed.
      * @default false
      */
     keepMounted?: boolean;
@@ -92,16 +113,18 @@ CollapsiblePanel.propTypes /* remove-proptypes */ = {
    */
   className: PropTypes.oneOfType([PropTypes.func, PropTypes.string]),
   /**
-   * If `true`, sets `hidden="until-found"` when closed.
-   * Requires setting `keepMounted` to `true`.
-   * If `false`, sets `hidden` when closed.
+   * If `true`, sets the hidden state using `hidden="until-found"`. The panel
+   * remains mounted in the DOM when closed and overrides `keepMounted`.
+   * If `false`, sets the hidden state using `hidden`.
    * @default false
    */
   hiddenUntilFound: PropTypes.bool,
   /**
    * If `true`, the panel remains mounted when closed and is instead
    * hidden using the `hidden` attribute
    * If `false`, the panel is unmounted when closed.
+   * If the `hiddenUntilFound` prop is used, the panel overrides this prop and
+   * is remains mounted when closed.
    * @default false
    */
   keepMounted: PropTypes.bool,

packages/mui-base/src/Collapsible/Panel/useCollapsiblePanel.ts

@@ -300,9 +300,9 @@ export namespace useCollapsiblePanel {
      */
     animated?: boolean;
     /**
-     * If `true`, sets `hidden="until-found"` when closed.
-     * Requires setting `keepMounted` to `true`.
-     * If `false`, sets `hidden` when closed.
+     * If `true`, sets the hidden state using `hidden="until-found"`. The panel
+     * remains mounted in the DOM when closed and overrides `keepMounted`.
+     * If `false`, sets the hidden state using `hidden`.
      * @default false
      */
     hiddenUntilFound?: boolean;

packages/mui-base/src/Dialog/Root/DialogRoot.test.tsx

@@ -46,7 +46,7 @@ describe('<Dialog.Root />', () => {
     });
   });
 
-  // toWarnDev doesn't work reliably with async rendering. To re-eanble after it's fixed in the test-utils.
+  // toWarnDev doesn't work reliably with async rendering. To re-enable after it's fixed in the test-utils.
   // eslint-disable-next-line mocha/no-skipped-tests
   describe.skip('prop: modal', () => {
     it('warns when the dialog is modal but no backdrop is present', async () => {