From 239c5277a3775470a87e1a610f722d7ab7611eee Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Mon, 10 Mar 2025 17:52:12 +0800
Subject: [PATCH 01/31] Add experiment

---
 .../experiments/collapsible/plain.module.css  | 71 +++++++++++++
 .../experiments/collapsible/plain.tsx         | 99 +++++++++++++++++++
 2 files changed, 170 insertions(+)
 create mode 100644 docs/src/app/(private)/experiments/collapsible/plain.module.css
 create mode 100644 docs/src/app/(private)/experiments/collapsible/plain.tsx

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.module.css b/docs/src/app/(private)/experiments/collapsible/plain.module.css
new file mode 100644
index 0000000000..9f65d55e86
--- /dev/null
+++ b/docs/src/app/(private)/experiments/collapsible/plain.module.css
@@ -0,0 +1,71 @@
+.wrapper {
+  --width: 320px;
+  --duration: 2000ms;
+
+  font-family: system-ui, sans-serif;
+  line-height: 1.4;
+  display: flex;
+  flex-flow: column nowrap;
+  align-items: stretch;
+  gap: 3rem;
+  align-self: flex-start;
+}
+
+.Root {
+  width: var(--width);
+}
+
+.Trigger {
+  display: flex;
+  width: 100%;
+  align-items: center;
+  padding: 0.25rem 0.5rem;
+  border-radius: 0.25rem;
+  background-color: var(--color-gray-200);
+  color: var(--color-gray-900);
+
+  & svg {
+    transform: rotate(-90deg);
+    transition: transform var(--duration) ease-in;
+  }
+
+  &[data-panel-open] svg {
+    transform: rotate(0);
+    transition: transform var(--duration) ease-out;
+  }
+}
+
+.Panel {
+  overflow: hidden;
+  box-sizing: border-box;
+  width: var(--width);
+
+  transition: all var(--duration) ease-out;
+
+  &[data-open] {
+    height: var(--collapsible-panel-height);
+    /*    height: auto;*/
+    opacity: 1;
+  }
+
+  &[data-closed] {
+    display: none;
+    height: 0;
+    opacity: 0;
+  }
+}
+
+.Content {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  margin-top: 0.25rem;
+  padding: 0.5rem;
+  border-radius: 0.25rem;
+  background-color: var(--color-gray-200);
+  cursor: text;
+
+  & p {
+    overflow-wrap: break-word;
+  }
+}
diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
new file mode 100644
index 0000000000..6907acce45
--- /dev/null
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -0,0 +1,99 @@
+'use client';
+import * as React from 'react';
+import classes from './plain.module.css';
+
+export default function DomCollapsible() {
+  const [open, setOpen] = React.useState(false);
+
+  const panelRef: React.RefObject<HTMLElement | null> = React.useRef(null);
+
+  const [height, setHeight] = React.useState(0);
+
+  const handleTrigger = () => {
+    const panel = panelRef.current;
+    if (!panel) {
+      return;
+    }
+
+    const nextOpen = !open;
+
+    panel.style.display = 'block';
+    // const targetHeight = panel.clientHeight;
+
+    if (nextOpen) {
+      /* opening */
+      panel.style.opacity = '0';
+      panel.style.height = '0px';
+
+      requestAnimationFrame(() => {
+        panel.style.opacity = '1';
+        panel.style.height = '';
+        setHeight(panel.scrollHeight);
+      });
+    } else {
+      /* closing */
+      requestAnimationFrame(() => {
+        console.log('closing, scrollHeight', panel.scrollHeight);
+        panel.style.opacity = '0';
+        setHeight(0);
+      });
+    }
+
+    setOpen(!open);
+  };
+
+  return (
+    <div className={classes.wrapper}>
+      <div
+        className={classes.Root}
+        style={{
+          // @ts-ignore
+          '--collapsible-panel-height': `${height}px`,
+        }}
+      >
+        <button
+          type="button"
+          className={classes.Trigger}
+          data-panel-open={open || undefined}
+          onClick={handleTrigger}
+        >
+          <ExpandMoreIcon className={classes.Icon} />
+          Trigger
+        </button>
+
+        <div
+          // @ts-ignore
+          ref={panelRef}
+          className={classes.Panel}
+          {...{ [open ? 'data-open' : 'data-closed']: '' }}
+          // hidden={!open}
+        >
+          <div className={classes.Content}>
+            <p>
+              He rubbed his eyes, and came close to the picture, and examined it
+              again. There were no signs of any change when he looked into the actual
+              painting, and yet there was no doubt that the whole expression had
+              altered. It was not a mere fancy of his own. The thing was horribly
+              apparent.
+            </p>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function ExpandMoreIcon(props: React.SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+    >
+      <path d="M16.59 8.59 12 13.17 7.41 8.59 6 10l6 6 6-6z" fill="currentColor" />
+    </svg>
+  );
+}

From d69830f62bcb2806fcae52e94f35d6fcbb793365 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Mon, 10 Mar 2025 19:57:10 +0800
Subject: [PATCH 02/31] Support keepMounted false

---
 .../experiments/collapsible/plain.module.css  |  15 +--
 .../experiments/collapsible/plain.tsx         | 110 ++++++++++++++----
 2 files changed, 94 insertions(+), 31 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.module.css b/docs/src/app/(private)/experiments/collapsible/plain.module.css
index 9f65d55e86..c523d4cb37 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.module.css
+++ b/docs/src/app/(private)/experiments/collapsible/plain.module.css
@@ -1,17 +1,17 @@
 .wrapper {
-  --width: 320px;
-  --duration: 2000ms;
-
   font-family: system-ui, sans-serif;
   line-height: 1.4;
   display: flex;
   flex-flow: column nowrap;
   align-items: stretch;
-  gap: 3rem;
+  gap: 1rem;
   align-self: flex-start;
 }
 
 .Root {
+  --width: 320px;
+  --duration: 1000ms;
+
   width: var(--width);
 }
 
@@ -38,13 +38,14 @@
 .Panel {
   overflow: hidden;
   box-sizing: border-box;
-  width: var(--width);
+  width: 100%;
 
-  transition: all var(--duration) ease-out;
+  transition:
+    height var(--duration) ease-out,
+    opacity var(--duration) ease-out;
 
   &[data-open] {
     height: var(--collapsible-panel-height);
-    /*    height: auto;*/
     opacity: 1;
   }
 
diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index 6907acce45..9dce2853b8 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -1,22 +1,38 @@
 'use client';
 import * as React from 'react';
+import { useEnhancedEffect } from '@base-ui-components/react/utils';
 import classes from './plain.module.css';
 
-export default function DomCollapsible() {
+import { useAnimationsFinished } from '../../../../../../packages/react/src/utils/useAnimationsFinished';
+import { useEventCallback } from '../../../../../../packages/react/src/utils/useEventCallback';
+
+function PlainCollapsible(props: { keepMounted?: boolean }) {
+  const { keepMounted = true } = props;
+
   const [open, setOpen] = React.useState(false);
 
+  const [mounted, setMounted] = React.useState(open);
+
   const panelRef: React.RefObject<HTMLElement | null> = React.useRef(null);
 
   const [height, setHeight] = React.useState(0);
 
-  const handleTrigger = () => {
+  const handleTrigger = useEventCallback(() => {
+    const nextOpen = !open;
+
+    if (!keepMounted) {
+      // mount only
+      if (!mounted) {
+        setMounted(true);
+      }
+    }
+    setOpen(nextOpen);
+
     const panel = panelRef.current;
     if (!panel) {
       return;
     }
 
-    const nextOpen = !open;
-
     panel.style.display = 'block';
     // const targetHeight = panel.clientHeight;
 
@@ -33,34 +49,70 @@ export default function DomCollapsible() {
     } else {
       /* closing */
       requestAnimationFrame(() => {
-        console.log('closing, scrollHeight', panel.scrollHeight);
+        // console.log('closing, scrollHeight', panel.scrollHeight);
         panel.style.opacity = '0';
         setHeight(0);
       });
     }
+  });
 
-    setOpen(!open);
-  };
+  const runOnceAnimationsFinish = useAnimationsFinished(panelRef);
+
+  useEnhancedEffect(() => {
+    // This only matters when `keepMounted={false}`
+    if (keepMounted) {
+      return;
+    }
+    // console.log('useEnhancedEffect open', open, 'mounted', mounted);
+
+    const panel = panelRef.current;
+    if (!panel) {
+      return;
+    }
+
+    if (open) {
+      /* opening */
+      panel.style.opacity = '0';
+      panel.style.height = '0px';
+
+      requestAnimationFrame(() => {
+        panel.style.opacity = '1';
+        panel.style.height = '';
+        setHeight(panel.scrollHeight);
+      });
+    } else {
+      /* closing */
+      requestAnimationFrame(() => {
+        console.log('closing, scrollHeight', panel.scrollHeight);
+        panel.style.opacity = '0';
+        setHeight(0);
+      });
+
+      runOnceAnimationsFinish(() => {
+        setMounted(false);
+      });
+    }
+  }, [keepMounted, open, mounted, setMounted, runOnceAnimationsFinish]);
 
   return (
-    <div className={classes.wrapper}>
-      <div
-        className={classes.Root}
-        style={{
-          // @ts-ignore
-          '--collapsible-panel-height': `${height}px`,
-        }}
+    <div
+      className={classes.Root}
+      style={{
+        // @ts-ignore
+        '--collapsible-panel-height': `${height}px`,
+      }}
+    >
+      <button
+        type="button"
+        className={classes.Trigger}
+        data-panel-open={open || undefined}
+        onClick={handleTrigger}
       >
-        <button
-          type="button"
-          className={classes.Trigger}
-          data-panel-open={open || undefined}
-          onClick={handleTrigger}
-        >
-          <ExpandMoreIcon className={classes.Icon} />
-          Trigger
-        </button>
+        <ExpandMoreIcon className={classes.Icon} />
+        Trigger (keepMounted {String(keepMounted)})
+      </button>
 
+      {(keepMounted || (!keepMounted && mounted)) && (
         <div
           // @ts-ignore
           ref={panelRef}
@@ -78,7 +130,17 @@ export default function DomCollapsible() {
             </p>
           </div>
         </div>
-      </div>
+      )}
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <div className={classes.wrapper}>
+      <PlainCollapsible />
+
+      <PlainCollapsible keepMounted={false} />
     </div>
   );
 }

From 96644b6bbbc27cac371aaf7ae8ae933c15efee2a Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Mon, 10 Mar 2025 20:10:18 +0800
Subject: [PATCH 03/31] Support hidden attribute

---
 .../experiments/collapsible/plain.module.css        |  1 -
 .../app/(private)/experiments/collapsible/plain.tsx | 13 +++++++++++--
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.module.css b/docs/src/app/(private)/experiments/collapsible/plain.module.css
index c523d4cb37..023ad40237 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.module.css
+++ b/docs/src/app/(private)/experiments/collapsible/plain.module.css
@@ -50,7 +50,6 @@
   }
 
   &[data-closed] {
-    display: none;
     height: 0;
     opacity: 0;
   }
diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index 9dce2853b8..d00916602d 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -33,7 +33,8 @@ function PlainCollapsible(props: { keepMounted?: boolean }) {
       return;
     }
 
-    panel.style.display = 'block';
+    // panel.style.display = 'block';
+
     // const targetHeight = panel.clientHeight;
 
     if (nextOpen) {
@@ -94,6 +95,14 @@ function PlainCollapsible(props: { keepMounted?: boolean }) {
     }
   }, [keepMounted, open, mounted, setMounted, runOnceAnimationsFinish]);
 
+  const isHidden = React.useMemo(() => {
+    if (keepMounted) {
+      return !open;
+    }
+
+    return !open && !mounted;
+  }, [keepMounted, open, mounted]);
+
   return (
     <div
       className={classes.Root}
@@ -118,7 +127,7 @@ function PlainCollapsible(props: { keepMounted?: boolean }) {
           ref={panelRef}
           className={classes.Panel}
           {...{ [open ? 'data-open' : 'data-closed']: '' }}
-          // hidden={!open}
+          hidden={isHidden}
         >
           <div className={classes.Content}>
             <p>

From 37f2cc5d6d0e2f52046acd73cbf729dd6194239d Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Mon, 10 Mar 2025 21:20:54 +0800
Subject: [PATCH 04/31] Fix Tailwind hidden attr default

---
 docs/src/styles.css | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/src/styles.css b/docs/src/styles.css
index f0142f6ee2..869c1428e7 100644
--- a/docs/src/styles.css
+++ b/docs/src/styles.css
@@ -222,6 +222,10 @@
   [data-demo]:not([data-demo='tailwind']) * {
     all: revert-layer;
   }
+
+  [hidden]:where(:not([hidden='until-found'])) {
+    display: revert-layer !important;
+  }
 }
 
 @layer all {

From 3c7c6a60974e695294a175977df9a0e1809a5c8b Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Mon, 10 Mar 2025 23:49:50 +0800
Subject: [PATCH 05/31] Cancel transition if initially open

---
 .../experiments/collapsible/plain.tsx         | 101 +++++++++++++-----
 .../react/src/utils/useAnimationsFinished.ts  |  80 ++++++++------
 2 files changed, 125 insertions(+), 56 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index d00916602d..b88b30ba97 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -5,17 +5,61 @@ import classes from './plain.module.css';
 
 import { useAnimationsFinished } from '../../../../../../packages/react/src/utils/useAnimationsFinished';
 import { useEventCallback } from '../../../../../../packages/react/src/utils/useEventCallback';
+import { useForkRef } from '../../../../../../packages/react/src/utils/useForkRef';
 
-function PlainCollapsible(props: { keepMounted?: boolean }) {
-  const { keepMounted = true } = props;
+const DEFAULT_OPEN = true;
 
-  const [open, setOpen] = React.useState(false);
+function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
+  const { keepMounted = true, defaultOpen = false } = props;
+
+  const [open, setOpen] = React.useState(defaultOpen);
 
   const [mounted, setMounted] = React.useState(open);
 
+  const [height, setHeight] = React.useState<number | undefined>(undefined);
+
+  const isInitiallyOpen = React.useRef(open);
+
+  const isHidden = React.useMemo(() => {
+    if (keepMounted) {
+      return !open;
+    }
+
+    return !open && !mounted;
+  }, [keepMounted, open, mounted]);
+
   const panelRef: React.RefObject<HTMLElement | null> = React.useRef(null);
 
-  const [height, setHeight] = React.useState(0);
+  const handlePanelRef = useEventCallback((element: HTMLElement) => {
+    if (!element) {
+      return;
+    }
+
+    element.style.setProperty('display', 'block', 'important');
+
+    if (height === undefined) {
+      setHeight(element.scrollHeight);
+
+      if (isInitiallyOpen.current) {
+        element.style.transitionDuration = '0s';
+
+        requestAnimationFrame(() => {
+          setTimeout(() => {
+            element.style.transitionDuration = '';
+            if (!keepMounted) {
+              isInitiallyOpen.current = false;
+            }
+          });
+        });
+      }
+    }
+  });
+
+  const mergedRef = useForkRef(panelRef, handlePanelRef);
+
+  const abortControllerRef = React.useRef<AbortController | null>(null);
+
+  const runOnceAnimationsFinish = useAnimationsFinished(panelRef, false);
 
   const handleTrigger = useEventCallback(() => {
     const nextOpen = !open;
@@ -33,11 +77,15 @@ function PlainCollapsible(props: { keepMounted?: boolean }) {
       return;
     }
 
-    // panel.style.display = 'block';
-
     // const targetHeight = panel.clientHeight;
+    panel.style.setProperty('display', 'block', 'important');
 
     if (nextOpen) {
+      if (abortControllerRef.current != null) {
+        abortControllerRef.current.abort();
+        abortControllerRef.current = null;
+      }
+
       /* opening */
       panel.style.opacity = '0';
       panel.style.height = '0px';
@@ -50,21 +98,23 @@ function PlainCollapsible(props: { keepMounted?: boolean }) {
     } else {
       /* closing */
       requestAnimationFrame(() => {
-        // console.log('closing, scrollHeight', panel.scrollHeight);
         panel.style.opacity = '0';
         setHeight(0);
       });
+
+      abortControllerRef.current = new AbortController();
+
+      runOnceAnimationsFinish(() => {
+        panel.style.setProperty('display', 'none');
+      }, abortControllerRef.current.signal);
     }
   });
 
-  const runOnceAnimationsFinish = useAnimationsFinished(panelRef);
-
   useEnhancedEffect(() => {
     // This only matters when `keepMounted={false}`
     if (keepMounted) {
       return;
     }
-    // console.log('useEnhancedEffect open', open, 'mounted', mounted);
 
     const panel = panelRef.current;
     if (!panel) {
@@ -72,6 +122,13 @@ function PlainCollapsible(props: { keepMounted?: boolean }) {
     }
 
     if (open) {
+      // console.log('mounted?', mounted);
+
+      if (abortControllerRef.current != null) {
+        abortControllerRef.current.abort();
+        abortControllerRef.current = null;
+      }
+
       /* opening */
       panel.style.opacity = '0';
       panel.style.height = '0px';
@@ -81,34 +138,30 @@ function PlainCollapsible(props: { keepMounted?: boolean }) {
         panel.style.height = '';
         setHeight(panel.scrollHeight);
       });
+
+      setMounted(true);
     } else {
       /* closing */
       requestAnimationFrame(() => {
-        console.log('closing, scrollHeight', panel.scrollHeight);
         panel.style.opacity = '0';
         setHeight(0);
       });
 
+      abortControllerRef.current = new AbortController();
+
       runOnceAnimationsFinish(() => {
         setMounted(false);
-      });
+      }, abortControllerRef.current.signal);
     }
   }, [keepMounted, open, mounted, setMounted, runOnceAnimationsFinish]);
 
-  const isHidden = React.useMemo(() => {
-    if (keepMounted) {
-      return !open;
-    }
-
-    return !open && !mounted;
-  }, [keepMounted, open, mounted]);
-
   return (
     <div
       className={classes.Root}
       style={{
         // @ts-ignore
-        '--collapsible-panel-height': `${height}px`,
+        '--collapsible-panel-height':
+          height !== undefined ? `${height}px` : undefined,
       }}
     >
       <button
@@ -124,7 +177,7 @@ function PlainCollapsible(props: { keepMounted?: boolean }) {
       {(keepMounted || (!keepMounted && mounted)) && (
         <div
           // @ts-ignore
-          ref={panelRef}
+          ref={mergedRef}
           className={classes.Panel}
           {...{ [open ? 'data-open' : 'data-closed']: '' }}
           hidden={isHidden}
@@ -147,9 +200,9 @@ function PlainCollapsible(props: { keepMounted?: boolean }) {
 export default function App() {
   return (
     <div className={classes.wrapper}>
-      <PlainCollapsible />
+      <PlainCollapsible defaultOpen={DEFAULT_OPEN} />
 
-      <PlainCollapsible keepMounted={false} />
+      <PlainCollapsible keepMounted={false} defaultOpen={DEFAULT_OPEN} />
     </div>
   );
 }
diff --git a/packages/react/src/utils/useAnimationsFinished.ts b/packages/react/src/utils/useAnimationsFinished.ts
index b76224a76c..81d74a9ab2 100644
--- a/packages/react/src/utils/useAnimationsFinished.ts
+++ b/packages/react/src/utils/useAnimationsFinished.ts
@@ -23,38 +23,54 @@ export function useAnimationsFinished(
 
   React.useEffect(() => cancelTasks, [cancelTasks]);
 
-  return useEventCallback((fnToExecute: () => void) => {
-    cancelTasks();
-
-    const element = ref.current;
-
-    if (!element) {
-      return;
-    }
-
-    if (typeof element.getAnimations !== 'function' || globalThis.BASE_UI_ANIMATIONS_DISABLED) {
-      fnToExecute();
-    } else {
-      frameRef.current = requestAnimationFrame(() => {
-        function exec() {
-          if (!element) {
-            return;
+  return useEventCallback(
+    (
+      /**
+       * A function to execute once all animations have finished.
+       */
+      fnToExecute: () => void,
+      /**
+       * An optional [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that
+       * can be used to abort `fnToExecute` before all the animations have finished.
+       * @default null
+       */
+      signal: AbortSignal | null = null,
+    ) => {
+      cancelTasks();
+
+      const element = ref.current;
+
+      if (!element) {
+        return;
+      }
+
+      if (typeof element.getAnimations !== 'function' || globalThis.BASE_UI_ANIMATIONS_DISABLED) {
+        fnToExecute();
+      } else {
+        frameRef.current = requestAnimationFrame(() => {
+          function exec() {
+            if (!element) {
+              return;
+            }
+
+            Promise.allSettled(element.getAnimations().map((anim) => anim.finished)).then(() => {
+              if (signal != null && signal.aborted) {
+                return;
+              }
+              // Synchronously flush the unmounting of the component so that the browser doesn't
+              // paint: https://github.com/mui/base-ui/issues/979
+              ReactDOM.flushSync(fnToExecute);
+            });
           }
 
-          Promise.allSettled(element.getAnimations().map((anim) => anim.finished)).then(() => {
-            // Synchronously flush the unmounting of the component so that the browser doesn't
-            // paint: https://github.com/mui/base-ui/issues/979
-            ReactDOM.flushSync(fnToExecute);
-          });
-        }
-
-        // `open: true` animations need to wait for the next tick to be detected
-        if (waitForNextTick) {
-          timeoutRef.current = window.setTimeout(exec);
-        } else {
-          exec();
-        }
-      });
-    }
-  });
+          // `open: true` animations need to wait for the next tick to be detected
+          if (waitForNextTick) {
+            timeoutRef.current = window.setTimeout(exec);
+          } else {
+            exec();
+          }
+        });
+      }
+    },
+  );
 }

From 3479f5a698c9c788331f4b56baef6bb3c03d17df Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 11 Mar 2025 13:42:42 +0800
Subject: [PATCH 06/31] Remove unnecessary opacity changes

---
 .../experiments/collapsible/plain.module.css  |  8 +++----
 .../experiments/collapsible/plain.tsx         | 23 ++++++++-----------
 2 files changed, 13 insertions(+), 18 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.module.css b/docs/src/app/(private)/experiments/collapsible/plain.module.css
index 023ad40237..539e596446 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.module.css
+++ b/docs/src/app/(private)/experiments/collapsible/plain.module.css
@@ -40,15 +40,13 @@
   box-sizing: border-box;
   width: 100%;
 
+  height: var(--collapsible-panel-height);
+  opacity: 1;
+
   transition:
     height var(--duration) ease-out,
     opacity var(--duration) ease-out;
 
-  &[data-open] {
-    height: var(--collapsible-panel-height);
-    opacity: 1;
-  }
-
   &[data-closed] {
     height: 0;
     opacity: 0;
diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index b88b30ba97..3ef2c0641e 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -7,14 +7,14 @@ import { useAnimationsFinished } from '../../../../../../packages/react/src/util
 import { useEventCallback } from '../../../../../../packages/react/src/utils/useEventCallback';
 import { useForkRef } from '../../../../../../packages/react/src/utils/useForkRef';
 
-const DEFAULT_OPEN = true;
+const DEFAULT_OPEN = false;
 
 function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
   const { keepMounted = true, defaultOpen = false } = props;
 
   const [open, setOpen] = React.useState(defaultOpen);
 
-  const [mounted, setMounted] = React.useState(open);
+  const [mounted, setMounted] = React.useState(keepMounted ? true : open);
 
   const [height, setHeight] = React.useState<number | undefined>(undefined);
 
@@ -39,7 +39,6 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 
     if (height === undefined) {
       setHeight(element.scrollHeight);
-
       if (isInitiallyOpen.current) {
         element.style.transitionDuration = '0s';
 
@@ -66,7 +65,7 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 
     if (!keepMounted) {
       // mount only
-      if (!mounted) {
+      if (!mounted && nextOpen) {
         setMounted(true);
       }
     }
@@ -91,14 +90,13 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
       panel.style.height = '0px';
 
       requestAnimationFrame(() => {
-        panel.style.opacity = '1';
+        panel.style.removeProperty('opacity');
         panel.style.height = '';
         setHeight(panel.scrollHeight);
       });
     } else {
       /* closing */
       requestAnimationFrame(() => {
-        panel.style.opacity = '0';
         setHeight(0);
       });
 
@@ -106,6 +104,7 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 
       runOnceAnimationsFinish(() => {
         panel.style.setProperty('display', 'none');
+        abortControllerRef.current = null;
       }, abortControllerRef.current.signal);
     }
   });
@@ -122,8 +121,6 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
     }
 
     if (open) {
-      // console.log('mounted?', mounted);
-
       if (abortControllerRef.current != null) {
         abortControllerRef.current.abort();
         abortControllerRef.current = null;
@@ -134,16 +131,13 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
       panel.style.height = '0px';
 
       requestAnimationFrame(() => {
-        panel.style.opacity = '1';
-        panel.style.height = '';
+        panel.style.removeProperty('opacity');
+        panel.style.removeProperty('height');
         setHeight(panel.scrollHeight);
       });
-
-      setMounted(true);
     } else {
       /* closing */
       requestAnimationFrame(() => {
-        panel.style.opacity = '0';
         setHeight(0);
       });
 
@@ -151,6 +145,7 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 
       runOnceAnimationsFinish(() => {
         setMounted(false);
+        abortControllerRef.current = null;
       }, abortControllerRef.current.signal);
     }
   }, [keepMounted, open, mounted, setMounted, runOnceAnimationsFinish]);
@@ -203,6 +198,8 @@ export default function App() {
       <PlainCollapsible defaultOpen={DEFAULT_OPEN} />
 
       <PlainCollapsible keepMounted={false} defaultOpen={DEFAULT_OPEN} />
+
+      <small>———</small>
     </div>
   );
 }

From d362b38ad904aa055236b43f46b6a543a8756735 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 11 Mar 2025 14:36:00 +0800
Subject: [PATCH 07/31] useTransitionStatus

---
 .../experiments/collapsible/plain.module.css  |  3 +-
 .../experiments/collapsible/plain.tsx         | 29 +++++++++++++++++--
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.module.css b/docs/src/app/(private)/experiments/collapsible/plain.module.css
index 539e596446..bb2477bb08 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.module.css
+++ b/docs/src/app/(private)/experiments/collapsible/plain.module.css
@@ -47,7 +47,8 @@
     height var(--duration) ease-out,
     opacity var(--duration) ease-out;
 
-  &[data-closed] {
+  &[data-starting-style],
+  &[data-ending-style] {
     height: 0;
     opacity: 0;
   }
diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index 3ef2c0641e..520e129cde 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -1,20 +1,36 @@
 'use client';
 import * as React from 'react';
-import { useEnhancedEffect } from '@base-ui-components/react/utils';
+import {
+  useEnhancedEffect,
+  useTransitionStatus,
+} from '@base-ui-components/react/utils';
 import classes from './plain.module.css';
 
 import { useAnimationsFinished } from '../../../../../../packages/react/src/utils/useAnimationsFinished';
 import { useEventCallback } from '../../../../../../packages/react/src/utils/useEventCallback';
 import { useForkRef } from '../../../../../../packages/react/src/utils/useForkRef';
 
-const DEFAULT_OPEN = false;
+const STARTING_HOOK = { 'data-starting-style': '' };
+const ENDING_HOOK = { 'data-ending-style': '' };
+
+const DEFAULT_OPEN = true;
 
 function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
   const { keepMounted = true, defaultOpen = false } = props;
 
   const [open, setOpen] = React.useState(defaultOpen);
 
-  const [mounted, setMounted] = React.useState(keepMounted ? true : open);
+  const { mounted, setMounted, transitionStatus } = useTransitionStatus(open, true);
+
+  const styleHooks = React.useMemo(() => {
+    if (transitionStatus === 'starting') {
+      return STARTING_HOOK;
+    }
+    if (transitionStatus === 'ending') {
+      return ENDING_HOOK;
+    }
+    return null;
+  }, [transitionStatus]);
 
   const [height, setHeight] = React.useState<number | undefined>(undefined);
 
@@ -35,10 +51,16 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
       return;
     }
 
+    // override potential `display: none` set on `[hidden]`
+    // to ensure the panel is actually rendered before measuring
     element.style.setProperty('display', 'block', 'important');
 
     if (height === undefined) {
+      element.style.opacity = '0';
+
       setHeight(element.scrollHeight);
+      element.style.removeProperty('display');
+      element.style.removeProperty('opacity');
       if (isInitiallyOpen.current) {
         element.style.transitionDuration = '0s';
 
@@ -175,6 +197,7 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
           ref={mergedRef}
           className={classes.Panel}
           {...{ [open ? 'data-open' : 'data-closed']: '' }}
+          {...styleHooks}
           hidden={isHidden}
         >
           <div className={classes.Content}>

From 7904aa33a5bc2052f2c372fdc487566a16040f4f Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 11 Mar 2025 15:03:25 +0800
Subject: [PATCH 08/31] No flag

---
 docs/src/app/(private)/experiments/collapsible/plain.tsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index 520e129cde..de3b4760ff 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -13,14 +13,14 @@ import { useForkRef } from '../../../../../../packages/react/src/utils/useForkRe
 const STARTING_HOOK = { 'data-starting-style': '' };
 const ENDING_HOOK = { 'data-ending-style': '' };
 
-const DEFAULT_OPEN = true;
+const DEFAULT_OPEN = false;
 
 function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
   const { keepMounted = true, defaultOpen = false } = props;
 
   const [open, setOpen] = React.useState(defaultOpen);
 
-  const { mounted, setMounted, transitionStatus } = useTransitionStatus(open, true);
+  const { mounted, setMounted, transitionStatus } = useTransitionStatus(open, false);
 
   const styleHooks = React.useMemo(() => {
     if (transitionStatus === 'starting') {
@@ -66,7 +66,7 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 
         requestAnimationFrame(() => {
           setTimeout(() => {
-            element.style.transitionDuration = '';
+            element.style.removeProperty('transition-duration');
             if (!keepMounted) {
               isInitiallyOpen.current = false;
             }

From 6c96edd3a1cdb8fa53289cbff827bc8ffcc84d15 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 11 Mar 2025 19:16:57 +0800
Subject: [PATCH 09/31] Remove more manual opacity changes.

---
 docs/src/app/(private)/experiments/collapsible/plain.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index de3b4760ff..38dd970b4c 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -56,7 +56,7 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
     element.style.setProperty('display', 'block', 'important');
 
     if (height === undefined) {
-      element.style.opacity = '0';
+      // element.style.opacity = '0';
 
       setHeight(element.scrollHeight);
       element.style.removeProperty('display');
@@ -108,7 +108,7 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
       }
 
       /* opening */
-      panel.style.opacity = '0';
+      // panel.style.opacity = '0';
       panel.style.height = '0px';
 
       requestAnimationFrame(() => {

From 149e15a3d5db989b327b4f8d2a745820fe01ddc8 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 11 Mar 2025 20:25:59 +0800
Subject: [PATCH 10/31] Tweak style tag cleanup

---
 .../experiments/collapsible/plain.tsx         | 24 ++++++++++++++-----
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index 38dd970b4c..bfe98d3611 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -56,10 +56,16 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
     element.style.setProperty('display', 'block', 'important');
 
     if (height === undefined) {
-      // element.style.opacity = '0';
+      // the closed transition styles must be set here to transition the first
+      // opening transition when both:
+      // 1 - the panel is initially closed
+      // 2 - `keepMounted={false}`
+      element.style.opacity = '0';
 
       setHeight(element.scrollHeight);
       element.style.removeProperty('display');
+
+      // after setHeight() all the transition properties need to be removed
       element.style.removeProperty('opacity');
       if (isInitiallyOpen.current) {
         element.style.transitionDuration = '0s';
@@ -107,13 +113,13 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
         abortControllerRef.current = null;
       }
 
+      panel.style.removeProperty('display');
+
       /* opening */
-      // panel.style.opacity = '0';
       panel.style.height = '0px';
 
       requestAnimationFrame(() => {
-        panel.style.removeProperty('opacity');
-        panel.style.height = '';
+        panel.style.removeProperty('height');
         setHeight(panel.scrollHeight);
       });
     } else {
@@ -125,6 +131,7 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
       abortControllerRef.current = new AbortController();
 
       runOnceAnimationsFinish(() => {
+        // TODO: !important may be needed
         panel.style.setProperty('display', 'none');
         abortControllerRef.current = null;
       }, abortControllerRef.current.signal);
@@ -149,12 +156,17 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
       }
 
       /* opening */
-      panel.style.opacity = '0';
       panel.style.height = '0px';
+      // the closed transition styles must be set here to transition all opening
+      // transitions except the first one when both:
+      // 1 - the panel is initially closed
+      // 2 - `keepMounted={false}`
+      panel.style.opacity = '0';
 
       requestAnimationFrame(() => {
-        panel.style.removeProperty('opacity');
         panel.style.removeProperty('height');
+        // remove all the transition properties that were just manually applied
+        panel.style.removeProperty('opacity');
         setHeight(panel.scrollHeight);
       });
     } else {

From 4888f865857a152218dbf83118a39bcbdf5c0346 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 12 Mar 2025 00:31:03 +0800
Subject: [PATCH 11/31] keepMounted true works well

---
 .../experiments/collapsible/plain.module.css  |  4 ++
 .../experiments/collapsible/plain.tsx         | 66 ++++++++++++++++---
 2 files changed, 61 insertions(+), 9 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.module.css b/docs/src/app/(private)/experiments/collapsible/plain.module.css
index bb2477bb08..85e3a33f20 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.module.css
+++ b/docs/src/app/(private)/experiments/collapsible/plain.module.css
@@ -52,6 +52,10 @@
     height: 0;
     opacity: 0;
   }
+
+  &[data-closed] {
+    opacity: 0;
+  }
 }
 
 .Content {
diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index bfe98d3611..60c03391eb 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -13,7 +13,8 @@ import { useForkRef } from '../../../../../../packages/react/src/utils/useForkRe
 const STARTING_HOOK = { 'data-starting-style': '' };
 const ENDING_HOOK = { 'data-ending-style': '' };
 
-const DEFAULT_OPEN = false;
+// const DEFAULT_OPEN = false;
+const KEEP_MOUNTED = true;
 
 function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
   const { keepMounted = true, defaultOpen = false } = props;
@@ -46,27 +47,63 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 
   const panelRef: React.RefObject<HTMLElement | null> = React.useRef(null);
 
+  /**
+   * When `keepMounted` is `true` this runs once as soon as it exists in the DOM
+   * regardless of initial open state.
+   *
+   * When `keepMounted` is `false` this runs on every mount, typically every
+   * time it opens. If the panel is in the middle of a close transition that is
+   * interrupted and re-opens, this won't run as the panel was not unmounted.
+   */
   const handlePanelRef = useEventCallback((element: HTMLElement) => {
     if (!element) {
       return;
     }
-
-    // override potential `display: none` set on `[hidden]`
-    // to ensure the panel is actually rendered before measuring
+    /**
+     * Explicitly set `display` to ensure the panel is actually rendered before
+     * measuring anything. `!important` is to needed to override a conflicting
+     * Tailwind v4 default that sets `display: none !important` on `[hidden]`:
+     * https://github.com/tailwindlabs/tailwindcss/blame/main/packages/tailwindcss/preflight.css#L382
+     */
     element.style.setProperty('display', 'block', 'important');
 
+    // const panelStyles = getComputedStyle(element);
+
     if (height === undefined) {
+      // console.log('here');
+      // it's possible to read the values of all transition properties in their closed state
+      // at the cost of a flash:
+      // if (keepMounted) {
+      //   if (isInitiallyOpen.current) {
+      //     // initially open
+      //     element.style.setProperty('transition', 'none', 'important');
+      //     setOpen(false);
+      //     requestAnimationFrame(() => {
+      //       requestAnimationFrame(() => {
+      //         requestAnimationFrame(() => {
+      //           console.log('here 2');
+      //           console.log(panelStyles.height, panelStyles.opacity);
+      //           setOpen(true);
+      //         });
+      //       });
+      //     });
+      //   } else {
+      //     // initially closed
+      //     console.log('here 3');
+      //     console.log(panelStyles.height, panelStyles.opacity);
+      //   }
+      // }
       // the closed transition styles must be set here to transition the first
       // opening transition when both:
       // 1 - the panel is initially closed
       // 2 - `keepMounted={false}`
-      element.style.opacity = '0';
+      // element.style.opacity = '0';
 
       setHeight(element.scrollHeight);
       element.style.removeProperty('display');
 
       // after setHeight() all the transition properties need to be removed
-      element.style.removeProperty('opacity');
+      // element.style.removeProperty('opacity');
       if (isInitiallyOpen.current) {
         element.style.transitionDuration = '0s';
 
@@ -104,6 +141,10 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
       return;
     }
 
+    // // this is the safest opportunity to unset `transition: none !important`
+    // // that was set in `handleRef` when initially open and `keepMounted={true}`
+    // panel.style.removeProperty('transition');
+
     // const targetHeight = panel.clientHeight;
     panel.style.setProperty('display', 'block', 'important');
 
@@ -138,8 +179,11 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
     }
   });
 
+  /**
+   * This only handles `keepMounted={false}` as the state changes can't be done
+   * in the event handler
+   */
   useEnhancedEffect(() => {
-    // This only matters when `keepMounted={false}`
     if (keepMounted) {
       return;
     }
@@ -164,6 +208,10 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
       panel.style.opacity = '0';
 
       requestAnimationFrame(() => {
+        // this is the earliest opportunity to unset the `display` property
+        // that was set in `handlePanelRef`
+        panel.style.removeProperty('display');
+
         panel.style.removeProperty('height');
         // remove all the transition properties that were just manually applied
         panel.style.removeProperty('opacity');
@@ -230,9 +278,9 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 export default function App() {
   return (
     <div className={classes.wrapper}>
-      <PlainCollapsible defaultOpen={DEFAULT_OPEN} />
+      <PlainCollapsible keepMounted={KEEP_MOUNTED} defaultOpen={true} />
 
-      <PlainCollapsible keepMounted={false} defaultOpen={DEFAULT_OPEN} />
+      <PlainCollapsible keepMounted={KEEP_MOUNTED} defaultOpen={false} />
 
       <small>———</small>
     </div>

From ce81c533f2a8d8ba7ac9a48f33d3dd0e8ed6a46d Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 12 Mar 2025 01:27:46 +0800
Subject: [PATCH 12/31] WIP other transitions wwhen keepMounted false

---
 .../experiments/collapsible/plain.tsx         | 63 ++++++-------------
 1 file changed, 19 insertions(+), 44 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index 60c03391eb..700a7af17e 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -14,7 +14,7 @@ const STARTING_HOOK = { 'data-starting-style': '' };
 const ENDING_HOOK = { 'data-ending-style': '' };
 
 // const DEFAULT_OPEN = false;
-const KEEP_MOUNTED = true;
+const KEEP_MOUNTED = false;
 
 function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
   const { keepMounted = true, defaultOpen = false } = props;
@@ -35,7 +35,7 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 
   const [height, setHeight] = React.useState<number | undefined>(undefined);
 
-  const isInitiallyOpen = React.useRef(open);
+  const isInitiallyOpenRef = React.useRef(open);
 
   const isHidden = React.useMemo(() => {
     if (keepMounted) {
@@ -70,49 +70,29 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
     // const panelStyles = getComputedStyle(element);
 
     if (height === undefined) {
-      // console.log('here');
-      // it's possible to read the values of all transition properties in their closed state
-      // at the cost of a flash:
-      // if (keepMounted) {
-      //   if (isInitiallyOpen.current) {
-      //     // initially open
-      //     element.style.setProperty('transition', 'none', 'important');
-      //     setOpen(false);
-      //     requestAnimationFrame(() => {
-      //       requestAnimationFrame(() => {
-      //         requestAnimationFrame(() => {
-      //           console.log('here 2');
-      //           console.log(panelStyles.height, panelStyles.opacity);
-      //           setOpen(true);
-      //         });
-      //       });
-      //     });
-      //   } else {
-      //     // initially closed
-      //     console.log('here 3');
-      //     console.log(panelStyles.height, panelStyles.opacity);
-      //   }
-      // }
-      // the closed transition styles must be set here to transition the first
-      // opening transition when both:
-      // 1 - the panel is initially closed
-      // 2 - `keepMounted={false}`
-      // element.style.opacity = '0';
-
-      setHeight(element.scrollHeight);
-      element.style.removeProperty('display');
+      if (
+        isInitiallyOpenRef.current ||
+        (!isInitiallyOpenRef.current && !keepMounted)
+      ) {
+        // the closed transition styles must be set here to transition the first
+        // opening transition when EITHER:
+        // 1 - the panel is initially closed AND `keepMounted={false}`
+        // 2 - the panel is initially open regardless of keepMounted
+        element.style.opacity = '0';
+
+        setHeight(element.scrollHeight);
+        element.style.removeProperty('display');
+
+        // after setHeight() all the transition properties need to be removed
+        element.style.removeProperty('opacity');
+      }
 
-      // after setHeight() all the transition properties need to be removed
-      // element.style.removeProperty('opacity');
-      if (isInitiallyOpen.current) {
+      if (isInitiallyOpenRef.current) {
         element.style.transitionDuration = '0s';
 
         requestAnimationFrame(() => {
           setTimeout(() => {
             element.style.removeProperty('transition-duration');
-            if (!keepMounted) {
-              isInitiallyOpen.current = false;
-            }
           });
         });
       }
@@ -141,11 +121,6 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
       return;
     }
 
-    // // this is the safest opportunity to unset `transition: none !important`
-    // // that was set in `handleRef` when initially open and `keepMounted={true}`
-    // panel.style.removeProperty('transition');
-
-    // const targetHeight = panel.clientHeight;
     panel.style.setProperty('display', 'block', 'important');
 
     if (nextOpen) {

From 72acf3eefd05354955dd28758fc3367498d43230 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 12 Mar 2025 01:51:40 +0800
Subject: [PATCH 13/31] WIP other transition properties

---
 .../experiments/collapsible/plain.tsx         | 22 ++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index 700a7af17e..7dac814211 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -93,6 +93,11 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
         requestAnimationFrame(() => {
           setTimeout(() => {
             element.style.removeProperty('transition-duration');
+            if (!keepMounted) {
+              // FIXME: this should actually be isInitialOpenTransitionRef
+              // or maybe both are needed?
+              isInitiallyOpenRef.current = false;
+            }
           });
         });
       }
@@ -174,13 +179,19 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
         abortControllerRef.current = null;
       }
 
+      console.log('mounted?', mounted);
+      console.log('isInitiallyOpenRef?', isInitiallyOpenRef.current);
+
       /* opening */
       panel.style.height = '0px';
       // the closed transition styles must be set here to transition all opening
       // transitions except the first one when both:
       // 1 - the panel is initially closed
       // 2 - `keepMounted={false}`
-      panel.style.opacity = '0';
+      if (!isInitiallyOpenRef.current) {
+        console.log('useEnhancedEffect setting opacity 0');
+        panel.style.opacity = '0';
+      }
 
       requestAnimationFrame(() => {
         // this is the earliest opportunity to unset the `display` property
@@ -188,8 +199,13 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
         panel.style.removeProperty('display');
 
         panel.style.removeProperty('height');
-        // remove all the transition properties that were just manually applied
-        panel.style.removeProperty('opacity');
+
+        if (!isInitiallyOpenRef.current) {
+          // remove all the transition properties that were just manually applied
+          console.log('useEnhancedEffect unsetting inline opacity');
+          panel.style.removeProperty('opacity');
+        }
+
         setHeight(panel.scrollHeight);
       });
     } else {

From 0ffb27af69db768300cda287844d4cbde6ef57b6 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 12 Mar 2025 13:57:32 +0800
Subject: [PATCH 14/31] WIP handle other transition props

---
 .../experiments/collapsible/plain.tsx         | 54 +++++++++----------
 1 file changed, 25 insertions(+), 29 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index 7dac814211..55651a1516 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react/jsx-boolean-value */
 'use client';
 import * as React from 'react';
 import {
@@ -36,6 +37,7 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
   const [height, setHeight] = React.useState<number | undefined>(undefined);
 
   const isInitiallyOpenRef = React.useRef(open);
+  const shouldCancelInitialOpenTransitionRef = React.useRef(open);
 
   const isHidden = React.useMemo(() => {
     if (keepMounted) {
@@ -45,6 +47,11 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
     return !open && !mounted;
   }, [keepMounted, open, mounted]);
 
+  function setHeightAndRemoveDisplayProperty(panelElement: HTMLElement) {
+    setHeight(panelElement.scrollHeight);
+    panelElement.style.removeProperty('display');
+  }
+
   const panelRef: React.RefObject<HTMLElement | null> = React.useRef(null);
 
   /**
@@ -65,43 +72,35 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
      * Tailwind v4 default that sets `display: none !important` on `[hidden]`:
      * https://github.com/tailwindlabs/tailwindcss/blame/main/packages/tailwindcss/preflight.css#L382
      */
-    element.style.setProperty('display', 'block', 'important');
-
-    // const panelStyles = getComputedStyle(element);
+    element.style.setProperty('display', 'block', 'important'); // TODO: maybe this can be set more conditionally
 
     if (height === undefined) {
-      if (
-        isInitiallyOpenRef.current ||
-        (!isInitiallyOpenRef.current && !keepMounted)
-      ) {
+      if (!isInitiallyOpenRef.current && !keepMounted) {
         // the closed transition styles must be set here to transition the first
-        // opening transition when EITHER:
-        // 1 - the panel is initially closed AND `keepMounted={false}`
-        // 2 - the panel is initially open regardless of keepMounted
+        // opening transition when the panel is BOTH initially closed AND `keepMounted={false}`
+        console.log('handlePanelRef setting opacity 0');
         element.style.opacity = '0';
 
-        setHeight(element.scrollHeight);
-        element.style.removeProperty('display');
+        setHeightAndRemoveDisplayProperty(element);
 
         // after setHeight() all the transition properties need to be removed
+        console.log('handlePanelRef unsetting inline opacity');
         element.style.removeProperty('opacity');
+      } else {
+        setHeightAndRemoveDisplayProperty(element);
       }
 
-      if (isInitiallyOpenRef.current) {
+      if (shouldCancelInitialOpenTransitionRef.current) {
         element.style.transitionDuration = '0s';
-
-        requestAnimationFrame(() => {
-          setTimeout(() => {
-            element.style.removeProperty('transition-duration');
-            if (!keepMounted) {
-              // FIXME: this should actually be isInitialOpenTransitionRef
-              // or maybe both are needed?
-              isInitiallyOpenRef.current = false;
-            }
-          });
-        });
       }
     }
+
+    requestAnimationFrame(() => {
+      setTimeout(() => {
+        element.style.removeProperty('transition-duration');
+        shouldCancelInitialOpenTransitionRef.current = false;
+      });
+    });
   });
 
   const mergedRef = useForkRef(panelRef, handlePanelRef);
@@ -179,16 +178,13 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
         abortControllerRef.current = null;
       }
 
-      console.log('mounted?', mounted);
-      console.log('isInitiallyOpenRef?', isInitiallyOpenRef.current);
-
       /* opening */
       panel.style.height = '0px';
       // the closed transition styles must be set here to transition all opening
       // transitions except the first one when both:
       // 1 - the panel is initially closed
       // 2 - `keepMounted={false}`
-      if (!isInitiallyOpenRef.current) {
+      if (!shouldCancelInitialOpenTransitionRef.current) {
         console.log('useEnhancedEffect setting opacity 0');
         panel.style.opacity = '0';
       }
@@ -200,7 +196,7 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 
         panel.style.removeProperty('height');
 
-        if (!isInitiallyOpenRef.current) {
+        if (!shouldCancelInitialOpenTransitionRef.current) {
           // remove all the transition properties that were just manually applied
           console.log('useEnhancedEffect unsetting inline opacity');
           panel.style.removeProperty('opacity');

From 57c2fe6d8e25787f4f776adafcc86393ff468cdc Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 12 Mar 2025 14:37:14 +0800
Subject: [PATCH 15/31] drop isInitiallyOpenRef

---
 docs/src/app/(private)/experiments/collapsible/plain.tsx | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index 55651a1516..a627fea3e3 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -36,7 +36,6 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 
   const [height, setHeight] = React.useState<number | undefined>(undefined);
 
-  const isInitiallyOpenRef = React.useRef(open);
   const shouldCancelInitialOpenTransitionRef = React.useRef(open);
 
   const isHidden = React.useMemo(() => {
@@ -75,7 +74,7 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
     element.style.setProperty('display', 'block', 'important'); // TODO: maybe this can be set more conditionally
 
     if (height === undefined) {
-      if (!isInitiallyOpenRef.current && !keepMounted) {
+      if (!shouldCancelInitialOpenTransitionRef.current && !keepMounted) {
         // the closed transition styles must be set here to transition the first
         // opening transition when the panel is BOTH initially closed AND `keepMounted={false}`
         console.log('handlePanelRef setting opacity 0');
@@ -181,9 +180,7 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
       /* opening */
       panel.style.height = '0px';
       // the closed transition styles must be set here to transition all opening
-      // transitions except the first one when both:
-      // 1 - the panel is initially closed
-      // 2 - `keepMounted={false}`
+      // transitions except the first one when `keepMounted={false}`
       if (!shouldCancelInitialOpenTransitionRef.current) {
         console.log('useEnhancedEffect setting opacity 0');
         panel.style.opacity = '0';

From 2edc4ebc0c7cf6f0133cbb0183fe4d0ba4b023d1 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 12 Mar 2025 15:03:19 +0800
Subject: [PATCH 16/31] data-closed is not needed in CSS anymore

---
 .../app/(private)/experiments/collapsible/plain.module.css    | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.module.css b/docs/src/app/(private)/experiments/collapsible/plain.module.css
index 85e3a33f20..e52b0c59b6 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.module.css
+++ b/docs/src/app/(private)/experiments/collapsible/plain.module.css
@@ -53,9 +53,9 @@
     opacity: 0;
   }
 
-  &[data-closed] {
+  /*&[data-closed] {
     opacity: 0;
-  }
+  }*/
 }
 
 .Content {

From 669d9cf3187efbc3d4b3d2e48179b4acb38e3802 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 12 Mar 2025 15:05:46 +0800
Subject: [PATCH 17/31] remove extra flag on useTransitionStatus

---
 .../(private)/experiments/collapsible/plain.tsx   |  2 +-
 .../src/collapsible/root/useCollapsibleRoot.ts    |  2 +-
 packages/react/src/utils/useTransitionStatus.ts   | 15 +++------------
 3 files changed, 5 insertions(+), 14 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index a627fea3e3..8b30b284c3 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -22,7 +22,7 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 
   const [open, setOpen] = React.useState(defaultOpen);
 
-  const { mounted, setMounted, transitionStatus } = useTransitionStatus(open, false);
+  const { mounted, setMounted, transitionStatus } = useTransitionStatus(open);
 
   const styleHooks = React.useMemo(() => {
     if (transitionStatus === 'starting') {
diff --git a/packages/react/src/collapsible/root/useCollapsibleRoot.ts b/packages/react/src/collapsible/root/useCollapsibleRoot.ts
index 6fe3a73ad7..91e55ef24c 100644
--- a/packages/react/src/collapsible/root/useCollapsibleRoot.ts
+++ b/packages/react/src/collapsible/root/useCollapsibleRoot.ts
@@ -17,7 +17,7 @@ export function useCollapsibleRoot(
     state: 'open',
   });
 
-  const { mounted, setMounted, transitionStatus } = useTransitionStatus(open, true);
+  const { mounted, setMounted, transitionStatus } = useTransitionStatus(open);
 
   const [panelId, setPanelId] = React.useState<string | undefined>(useBaseUiId());
 
diff --git a/packages/react/src/utils/useTransitionStatus.ts b/packages/react/src/utils/useTransitionStatus.ts
index d33ea23c5d..99904bf953 100644
--- a/packages/react/src/utils/useTransitionStatus.ts
+++ b/packages/react/src/utils/useTransitionStatus.ts
@@ -7,20 +7,15 @@ export type TransitionStatus = 'starting' | 'ending' | undefined;
 /**
  * Provides a status string for CSS animations.
  * @param open - a boolean that determines if the element is open.
- * @param delayStartingStatus - a boolean that set the `starting` status one
- *     tick later. Example use-case: collapsible needs an extra frame in order
- *     to measure the panel contents.
  * @ignore - internal hook.
  */
-export function useTransitionStatus(open: boolean, delayStartingStatus = false) {
+export function useTransitionStatus(open: boolean) {
   const [transitionStatus, setTransitionStatus] = React.useState<TransitionStatus>();
   const [mounted, setMounted] = React.useState(open);
 
   if (open && !mounted) {
     setMounted(true);
-    if (transitionStatus !== 'starting' && !delayStartingStatus) {
-      setTransitionStatus('starting');
-    }
+    setTransitionStatus('starting');
   }
 
   if (!open && mounted && transitionStatus !== 'ending') {
@@ -36,10 +31,6 @@ export function useTransitionStatus(open: boolean, delayStartingStatus = false)
       return undefined;
     }
 
-    if (delayStartingStatus) {
-      setTransitionStatus('starting');
-    }
-
     const frame = requestAnimationFrame(() => {
       setTransitionStatus(undefined);
     });
@@ -47,7 +38,7 @@ export function useTransitionStatus(open: boolean, delayStartingStatus = false)
     return () => {
       cancelAnimationFrame(frame);
     };
-  }, [open, delayStartingStatus]);
+  }, [open]);
 
   return React.useMemo(
     () => ({

From 2fadd654c53d7b026637a7a235108ad4038eaf0b Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 12 Mar 2025 15:22:32 +0800
Subject: [PATCH 18/31] extend starting status

---
 .../experiments/collapsible/plain.module.css  |  2 +-
 .../experiments/collapsible/plain.tsx         | 24 ++++++++++---------
 .../react/src/utils/useTransitionStatus.ts    |  9 ++++---
 3 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.module.css b/docs/src/app/(private)/experiments/collapsible/plain.module.css
index e52b0c59b6..f162102de2 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.module.css
+++ b/docs/src/app/(private)/experiments/collapsible/plain.module.css
@@ -41,7 +41,7 @@
   width: 100%;
 
   height: var(--collapsible-panel-height);
-  opacity: 1;
+  /*  opacity: 1;*/
 
   transition:
     height var(--duration) ease-out,
diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index 8b30b284c3..8b5f38745e 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -77,14 +77,14 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
       if (!shouldCancelInitialOpenTransitionRef.current && !keepMounted) {
         // the closed transition styles must be set here to transition the first
         // opening transition when the panel is BOTH initially closed AND `keepMounted={false}`
-        console.log('handlePanelRef setting opacity 0');
-        element.style.opacity = '0';
+        // console.log('handlePanelRef setting opacity 0');
+        // element.style.opacity = '0';
 
         setHeightAndRemoveDisplayProperty(element);
 
         // after setHeight() all the transition properties need to be removed
-        console.log('handlePanelRef unsetting inline opacity');
-        element.style.removeProperty('opacity');
+        // console.log('handlePanelRef unsetting inline opacity');
+        // element.style.removeProperty('opacity');
       } else {
         setHeightAndRemoveDisplayProperty(element);
       }
@@ -95,9 +95,11 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
     }
 
     requestAnimationFrame(() => {
-      setTimeout(() => {
-        element.style.removeProperty('transition-duration');
-        shouldCancelInitialOpenTransitionRef.current = false;
+      shouldCancelInitialOpenTransitionRef.current = false;
+      requestAnimationFrame(() => {
+        setTimeout(() => {
+          element.style.removeProperty('transition-duration');
+        });
       });
     });
   });
@@ -182,8 +184,8 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
       // the closed transition styles must be set here to transition all opening
       // transitions except the first one when `keepMounted={false}`
       if (!shouldCancelInitialOpenTransitionRef.current) {
-        console.log('useEnhancedEffect setting opacity 0');
-        panel.style.opacity = '0';
+        // console.log('useEnhancedEffect setting opacity 0');
+        // panel.style.opacity = '0';
       }
 
       requestAnimationFrame(() => {
@@ -195,8 +197,8 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 
         if (!shouldCancelInitialOpenTransitionRef.current) {
           // remove all the transition properties that were just manually applied
-          console.log('useEnhancedEffect unsetting inline opacity');
-          panel.style.removeProperty('opacity');
+          // console.log('useEnhancedEffect unsetting inline opacity');
+          // panel.style.removeProperty('opacity');
         }
 
         setHeight(panel.scrollHeight);
diff --git a/packages/react/src/utils/useTransitionStatus.ts b/packages/react/src/utils/useTransitionStatus.ts
index 99904bf953..539338fa73 100644
--- a/packages/react/src/utils/useTransitionStatus.ts
+++ b/packages/react/src/utils/useTransitionStatus.ts
@@ -2,7 +2,7 @@
 import * as React from 'react';
 import { useEnhancedEffect } from './useEnhancedEffect';
 
-export type TransitionStatus = 'starting' | 'ending' | undefined;
+export type TransitionStatus = 'starting' | 'ending' | 'idle' | undefined;
 
 /**
  * Provides a status string for CSS animations.
@@ -30,15 +30,18 @@ export function useTransitionStatus(open: boolean) {
     if (!open) {
       return undefined;
     }
+    if (open && mounted && transitionStatus !== 'idle') {
+      setTransitionStatus('starting');
+    }
 
     const frame = requestAnimationFrame(() => {
-      setTransitionStatus(undefined);
+      setTransitionStatus('idle');
     });
 
     return () => {
       cancelAnimationFrame(frame);
     };
-  }, [open]);
+  }, [open, mounted, setTransitionStatus, transitionStatus]);
 
   return React.useMemo(
     () => ({

From b2836cdfa8bae380da6f261ebdf387343e23ff63 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 12 Mar 2025 15:28:59 +0800
Subject: [PATCH 19/31] remove one more manual opacity change

---
 .../experiments/collapsible/plain.tsx         | 22 +++++--------------
 1 file changed, 5 insertions(+), 17 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index 8b5f38745e..9bf45ae2bf 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -74,17 +74,17 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
     element.style.setProperty('display', 'block', 'important'); // TODO: maybe this can be set more conditionally
 
     if (height === undefined) {
+      // the closed transition styles must be set here to transition the first
+      // opening transition when the panel is BOTH initially closed AND `keepMounted={false}`
       if (!shouldCancelInitialOpenTransitionRef.current && !keepMounted) {
-        // the closed transition styles must be set here to transition the first
-        // opening transition when the panel is BOTH initially closed AND `keepMounted={false}`
-        // console.log('handlePanelRef setting opacity 0');
-        // element.style.opacity = '0';
+        console.log('handlePanelRef setting opacity 0');
+        element.style.opacity = '0';
 
         setHeightAndRemoveDisplayProperty(element);
 
         // after setHeight() all the transition properties need to be removed
         // console.log('handlePanelRef unsetting inline opacity');
-        // element.style.removeProperty('opacity');
+        element.style.removeProperty('opacity');
       } else {
         setHeightAndRemoveDisplayProperty(element);
       }
@@ -181,12 +181,6 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 
       /* opening */
       panel.style.height = '0px';
-      // the closed transition styles must be set here to transition all opening
-      // transitions except the first one when `keepMounted={false}`
-      if (!shouldCancelInitialOpenTransitionRef.current) {
-        // console.log('useEnhancedEffect setting opacity 0');
-        // panel.style.opacity = '0';
-      }
 
       requestAnimationFrame(() => {
         // this is the earliest opportunity to unset the `display` property
@@ -195,12 +189,6 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 
         panel.style.removeProperty('height');
 
-        if (!shouldCancelInitialOpenTransitionRef.current) {
-          // remove all the transition properties that were just manually applied
-          // console.log('useEnhancedEffect unsetting inline opacity');
-          // panel.style.removeProperty('opacity');
-        }
-
         setHeight(panel.scrollHeight);
       });
     } else {

From c8cd8a46cdbf614f9dd4fe8772afe9c1ea9354bc Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 12 Mar 2025 21:15:45 +0800
Subject: [PATCH 20/31] a brilliant hack

---
 .../experiments/collapsible/plain.tsx         | 28 ++++++++-----------
 1 file changed, 11 insertions(+), 17 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index 9bf45ae2bf..5ce5145af6 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -46,11 +46,6 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
     return !open && !mounted;
   }, [keepMounted, open, mounted]);
 
-  function setHeightAndRemoveDisplayProperty(panelElement: HTMLElement) {
-    setHeight(panelElement.scrollHeight);
-    panelElement.style.removeProperty('display');
-  }
-
   const panelRef: React.RefObject<HTMLElement | null> = React.useRef(null);
 
   /**
@@ -74,21 +69,20 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
     element.style.setProperty('display', 'block', 'important'); // TODO: maybe this can be set more conditionally
 
     if (height === undefined) {
-      // the closed transition styles must be set here to transition the first
-      // opening transition when the panel is BOTH initially closed AND `keepMounted={false}`
+      /**
+       * When `keepMounted={false}` and the panel is initially closed, the very
+       * first time it opens (not any subsequent opens) `data-starting-style` is
+       * off or missing by a frame so we need to set it manually. Otherwise any
+       * CSS properties expected to transition using [data-starting-style] may
+       * be mis-timed and appear to be complete skipped.
+       */
       if (!shouldCancelInitialOpenTransitionRef.current && !keepMounted) {
-        console.log('handlePanelRef setting opacity 0');
-        element.style.opacity = '0';
-
-        setHeightAndRemoveDisplayProperty(element);
-
-        // after setHeight() all the transition properties need to be removed
-        // console.log('handlePanelRef unsetting inline opacity');
-        element.style.removeProperty('opacity');
-      } else {
-        setHeightAndRemoveDisplayProperty(element);
+        element.setAttribute('data-starting-style', '');
       }
 
+      setHeight(element.scrollHeight);
+      element.style.removeProperty('display');
+
       if (shouldCancelInitialOpenTransitionRef.current) {
         element.style.transitionDuration = '0s';
       }

From 48412810852af6a41e546e851032c6e913b56f3b Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 12 Mar 2025 21:49:56 +0800
Subject: [PATCH 21/31] slight polish

---
 .../experiments/collapsible/plain.module.css    |  9 +--------
 .../(private)/experiments/collapsible/plain.tsx | 17 +++++++++++------
 docs/src/styles.css                             |  4 ----
 3 files changed, 12 insertions(+), 18 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.module.css b/docs/src/app/(private)/experiments/collapsible/plain.module.css
index f162102de2..15a842d13c 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.module.css
+++ b/docs/src/app/(private)/experiments/collapsible/plain.module.css
@@ -41,21 +41,14 @@
   width: 100%;
 
   height: var(--collapsible-panel-height);
-  /*  opacity: 1;*/
 
-  transition:
-    height var(--duration) ease-out,
-    opacity var(--duration) ease-out;
+  transition: all var(--duration) ease-out;
 
   &[data-starting-style],
   &[data-ending-style] {
     height: 0;
     opacity: 0;
   }
-
-  /*&[data-closed] {
-    opacity: 0;
-  }*/
 }
 
 .Content {
diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/plain.tsx
index 5ce5145af6..15fcac1afc 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/plain.tsx
@@ -1,4 +1,3 @@
-/* eslint-disable react/jsx-boolean-value */
 'use client';
 import * as React from 'react';
 import {
@@ -14,7 +13,6 @@ import { useForkRef } from '../../../../../../packages/react/src/utils/useForkRe
 const STARTING_HOOK = { 'data-starting-style': '' };
 const ENDING_HOOK = { 'data-ending-style': '' };
 
-// const DEFAULT_OPEN = false;
 const KEEP_MOUNTED = false;
 
 function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
@@ -91,6 +89,12 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
     requestAnimationFrame(() => {
       shouldCancelInitialOpenTransitionRef.current = false;
       requestAnimationFrame(() => {
+        /**
+         * This is slightly faster than another RAF and is the earliest
+         * opportunity to remove the temporary `transition-duration: 0s` that
+         * was applied to cancel opening transitions of initially open panels.
+         * https://nolanlawson.com/2018/09/25/accurately-measuring-layout-on-the-web/
+         */
         setTimeout(() => {
           element.style.removeProperty('transition-duration');
         });
@@ -108,7 +112,6 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
     const nextOpen = !open;
 
     if (!keepMounted) {
-      // mount only
       if (!mounted && nextOpen) {
         setMounted(true);
       }
@@ -177,8 +180,10 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
       panel.style.height = '0px';
 
       requestAnimationFrame(() => {
-        // this is the earliest opportunity to unset the `display` property
-        // that was set in `handlePanelRef`
+        /**
+         * When `keepMounted={false}` this is the earliest opportunity to unset
+         * the temporary `display` property that was set in `handlePanelRef`
+         */
         panel.style.removeProperty('display');
 
         panel.style.removeProperty('height');
@@ -246,7 +251,7 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 export default function App() {
   return (
     <div className={classes.wrapper}>
-      <PlainCollapsible keepMounted={KEEP_MOUNTED} defaultOpen={true} />
+      <PlainCollapsible keepMounted={KEEP_MOUNTED} defaultOpen />
 
       <PlainCollapsible keepMounted={KEEP_MOUNTED} defaultOpen={false} />
 
diff --git a/docs/src/styles.css b/docs/src/styles.css
index 869c1428e7..f0142f6ee2 100644
--- a/docs/src/styles.css
+++ b/docs/src/styles.css
@@ -222,10 +222,6 @@
   [data-demo]:not([data-demo='tailwind']) * {
     all: revert-layer;
   }
-
-  [hidden]:where(:not([hidden='until-found'])) {
-    display: revert-layer !important;
-  }
 }
 
 @layer all {

From 4754b49fe8386ceb1207b39e08704015734c4f28 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 12 Mar 2025 21:58:35 +0800
Subject: [PATCH 22/31] rename

---
 .../{plain.module.css => transition.module.css}           | 0
 .../experiments/collapsible/{plain.tsx => transition.tsx} | 8 ++++----
 2 files changed, 4 insertions(+), 4 deletions(-)
 rename docs/src/app/(private)/experiments/collapsible/{plain.module.css => transition.module.css} (100%)
 rename docs/src/app/(private)/experiments/collapsible/{plain.tsx => transition.tsx} (96%)

diff --git a/docs/src/app/(private)/experiments/collapsible/plain.module.css b/docs/src/app/(private)/experiments/collapsible/transition.module.css
similarity index 100%
rename from docs/src/app/(private)/experiments/collapsible/plain.module.css
rename to docs/src/app/(private)/experiments/collapsible/transition.module.css
diff --git a/docs/src/app/(private)/experiments/collapsible/plain.tsx b/docs/src/app/(private)/experiments/collapsible/transition.tsx
similarity index 96%
rename from docs/src/app/(private)/experiments/collapsible/plain.tsx
rename to docs/src/app/(private)/experiments/collapsible/transition.tsx
index 15fcac1afc..a8608166f1 100644
--- a/docs/src/app/(private)/experiments/collapsible/plain.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/transition.tsx
@@ -4,7 +4,7 @@ import {
   useEnhancedEffect,
   useTransitionStatus,
 } from '@base-ui-components/react/utils';
-import classes from './plain.module.css';
+import classes from './transition.module.css';
 
 import { useAnimationsFinished } from '../../../../../../packages/react/src/utils/useAnimationsFinished';
 import { useEventCallback } from '../../../../../../packages/react/src/utils/useEventCallback';
@@ -15,7 +15,7 @@ const ENDING_HOOK = { 'data-ending-style': '' };
 
 const KEEP_MOUNTED = false;
 
-function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
+function Collapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
   const { keepMounted = true, defaultOpen = false } = props;
 
   const [open, setOpen] = React.useState(defaultOpen);
@@ -251,9 +251,9 @@ function PlainCollapsible(props: { defaultOpen?: boolean; keepMounted?: boolean
 export default function App() {
   return (
     <div className={classes.wrapper}>
-      <PlainCollapsible keepMounted={KEEP_MOUNTED} defaultOpen />
+      <Collapsible keepMounted={KEEP_MOUNTED} defaultOpen />
 
-      <PlainCollapsible keepMounted={KEEP_MOUNTED} defaultOpen={false} />
+      <Collapsible keepMounted={KEEP_MOUNTED} defaultOpen={false} />
 
       <small>———</small>
     </div>

From ae5d2c80492b93c05c36e185c154ff5cfbc23ae6 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 12 Mar 2025 22:55:09 +0800
Subject: [PATCH 23/31] Add demos

---
 .../collapsible/transition.module.css         | 12 ++++++++-
 .../experiments/collapsible/transition.tsx    | 26 +++++++++++++------
 2 files changed, 29 insertions(+), 9 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/transition.module.css b/docs/src/app/(private)/experiments/collapsible/transition.module.css
index 15a842d13c..3c8dcd370e 100644
--- a/docs/src/app/(private)/experiments/collapsible/transition.module.css
+++ b/docs/src/app/(private)/experiments/collapsible/transition.module.css
@@ -1,3 +1,9 @@
+.grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  grid-gap: 5rem;
+}
+
 .wrapper {
   font-family: system-ui, sans-serif;
   line-height: 1.4;
@@ -10,9 +16,13 @@
 
 .Root {
   --width: 320px;
-  --duration: 1000ms;
+  --duration: 800ms;
 
   width: var(--width);
+
+  & + .Root {
+    margin-top: 2rem;
+  }
 }
 
 .Trigger {
diff --git a/docs/src/app/(private)/experiments/collapsible/transition.tsx b/docs/src/app/(private)/experiments/collapsible/transition.tsx
index a8608166f1..a2bbb372f6 100644
--- a/docs/src/app/(private)/experiments/collapsible/transition.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/transition.tsx
@@ -13,7 +13,7 @@ import { useForkRef } from '../../../../../../packages/react/src/utils/useForkRe
 const STARTING_HOOK = { 'data-starting-style': '' };
 const ENDING_HOOK = { 'data-ending-style': '' };
 
-const KEEP_MOUNTED = false;
+// const KEEP_MOUNTED = false;
 
 function Collapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
   const { keepMounted = true, defaultOpen = false } = props;
@@ -221,7 +221,7 @@ function Collapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
         onClick={handleTrigger}
       >
         <ExpandMoreIcon className={classes.Icon} />
-        Trigger (keepMounted {String(keepMounted)})
+        Trigger {/* (keepMounted {String(keepMounted)}) */}
       </button>
 
       {(keepMounted || (!keepMounted && mounted)) && (
@@ -250,12 +250,22 @@ function Collapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
 
 export default function App() {
   return (
-    <div className={classes.wrapper}>
-      <Collapsible keepMounted={KEEP_MOUNTED} defaultOpen />
-
-      <Collapsible keepMounted={KEEP_MOUNTED} defaultOpen={false} />
-
-      <small>———</small>
+    <div className={classes.grid}>
+      <div className={classes.wrapper}>
+        <pre>keepMounted: true</pre>
+        <Collapsible keepMounted defaultOpen />
+
+        <Collapsible keepMounted defaultOpen={false} />
+
+        <small>———</small>
+      </div>
+      <div className={classes.wrapper}>
+        <pre>keepMounted: false</pre>
+        <Collapsible keepMounted={false} defaultOpen />
+
+        <Collapsible keepMounted={false} defaultOpen={false} />
+        <small>———</small>
+      </div>
     </div>
   );
 }

From e461391cd24cbd56ce3c405025a9542c0de1140e Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Thu, 13 Mar 2025 14:05:14 +0800
Subject: [PATCH 24/31] Isolate CSS animation logic

---
 .../experiments/collapsible/animation-old.tsx |  40 +++++
 .../collapsible/animation.module.css          |  97 ++++++++++
 .../experiments/collapsible/animation.tsx     | 169 ++++++++++++++++++
 .../experiments/collapsible/transition.tsx    |  47 ++++-
 docs/src/styles.css                           |   4 +
 .../collapsible/panel/useCollapsiblePanel.ts  |   2 +-
 6 files changed, 349 insertions(+), 10 deletions(-)
 create mode 100644 docs/src/app/(private)/experiments/collapsible/animation-old.tsx
 create mode 100644 docs/src/app/(private)/experiments/collapsible/animation.module.css
 create mode 100644 docs/src/app/(private)/experiments/collapsible/animation.tsx

diff --git a/docs/src/app/(private)/experiments/collapsible/animation-old.tsx b/docs/src/app/(private)/experiments/collapsible/animation-old.tsx
new file mode 100644
index 0000000000..e79c53a790
--- /dev/null
+++ b/docs/src/app/(private)/experiments/collapsible/animation-old.tsx
@@ -0,0 +1,40 @@
+'use client';
+import * as React from 'react';
+import { Collapsible } from '@base-ui-components/react/collapsible';
+import styles from './animation.module.css';
+
+export default function CollapsibleCssAnimation() {
+  return (
+    <div className={styles.wrapper}>
+      <Collapsible.Root defaultOpen className={styles.Root}>
+        <Collapsible.Trigger className={styles.Trigger}>Trigger</Collapsible.Trigger>
+        <Collapsible.Panel className={styles.Panel} keepMounted>
+          <div className={styles.Content}>
+            <p>
+              He rubbed his eyes, and came close to the picture, and examined it
+              again. There were no signs of any change when he looked into the actual
+              painting, and yet there was no doubt that the whole expression had
+              altered. It was not a mere fancy of his own. The thing was horribly
+              apparent.
+            </p>
+          </div>
+        </Collapsible.Panel>
+      </Collapsible.Root>
+
+      <Collapsible.Root defaultOpen={false} className={styles.Root}>
+        <Collapsible.Trigger className={styles.Trigger}>Trigger</Collapsible.Trigger>
+        <Collapsible.Panel className={styles.Panel} keepMounted>
+          <div className={styles.Content}>
+            <p>
+              He rubbed his eyes, and came close to the picture, and examined it
+              again. There were no signs of any change when he looked into the actual
+              painting, and yet there was no doubt that the whole expression had
+              altered. It was not a mere fancy of his own. The thing was horribly
+              apparent.
+            </p>
+          </div>
+        </Collapsible.Panel>
+      </Collapsible.Root>
+    </div>
+  );
+}
diff --git a/docs/src/app/(private)/experiments/collapsible/animation.module.css b/docs/src/app/(private)/experiments/collapsible/animation.module.css
new file mode 100644
index 0000000000..0522ca9721
--- /dev/null
+++ b/docs/src/app/(private)/experiments/collapsible/animation.module.css
@@ -0,0 +1,97 @@
+@keyframes slide-down {
+  from {
+    height: 0;
+  }
+
+  to {
+    height: var(--collapsible-panel-height);
+  }
+}
+
+@keyframes slide-up {
+  from {
+    height: var(--collapsible-panel-height);
+  }
+
+  to {
+    height: 0;
+  }
+}
+
+.Panel {
+  overflow: hidden;
+  box-sizing: border-box;
+  width: 100%;
+  animation-fill-mode: forwards !important;
+
+  &[data-open] {
+    animation: slide-down var(--duration) ease-out;
+  }
+
+  &[data-closed] {
+    animation: slide-up var(--duration) ease-in;
+  }
+}
+
+/* the styles below are irrelevant to the features */
+.grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  grid-gap: 5rem;
+}
+
+.wrapper {
+  font-family: system-ui, sans-serif;
+  line-height: 1.4;
+  display: flex;
+  flex-flow: column nowrap;
+  align-items: stretch;
+  gap: 1rem;
+  align-self: flex-start;
+}
+
+.Root {
+  --width: 320px;
+  --duration: 800ms;
+
+  width: var(--width);
+
+  & + .Root {
+    margin-top: 2rem;
+  }
+}
+
+.Trigger {
+  display: flex;
+  width: 100%;
+  align-items: center;
+  padding: 0.25rem 0.5rem;
+  border-radius: 0.25rem;
+  background-color: var(--color-gray-200);
+  color: var(--color-gray-900);
+
+  & svg {
+    transform: rotate(-90deg);
+    transition: transform var(--duration) ease-in;
+  }
+
+  &[data-panel-open] svg {
+    transform: rotate(0);
+    transition: transform var(--duration) ease-out;
+  }
+}
+
+.Content {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  margin-top: 0.25rem;
+  padding: 0.5rem;
+  border-radius: 0.25rem;
+  background-color: var(--color-gray-200);
+  cursor: text;
+
+  & p {
+    overflow-wrap: break-word;
+  }
+}
diff --git a/docs/src/app/(private)/experiments/collapsible/animation.tsx b/docs/src/app/(private)/experiments/collapsible/animation.tsx
new file mode 100644
index 0000000000..f8a6350d2a
--- /dev/null
+++ b/docs/src/app/(private)/experiments/collapsible/animation.tsx
@@ -0,0 +1,169 @@
+'use client';
+import * as React from 'react';
+import {
+  useEnhancedEffect,
+  // useTransitionStatus,
+} from '@base-ui-components/react/utils';
+import classes from './animation.module.css';
+
+import { useAnimationsFinished } from '../../../../../../packages/react/src/utils/useAnimationsFinished';
+import { useEventCallback } from '../../../../../../packages/react/src/utils/useEventCallback';
+// import { useForkRef } from '../../../../../../packages/react/src/utils/useForkRef';
+import { useOnMount } from '../../../../../../packages/react/src/utils/useOnMount';
+
+function Collapsible(props: {
+  defaultOpen?: boolean;
+  keepMounted?: boolean;
+  id?: string;
+}) {
+  const { keepMounted = true, defaultOpen = false, id } = props;
+
+  const [open, setOpen] = React.useState(defaultOpen);
+
+  const [visible, setVisible] = React.useState(open);
+
+  const [mounted, setMounted] = React.useState(open);
+
+  const [height, setHeight] = React.useState<number | undefined>(0);
+
+  const latestAnimationNameRef = React.useRef<string>(null);
+  const shouldCancelInitialOpenAnimationRef = React.useRef(open);
+
+  const isHidden = !visible;
+
+  const panelRef: React.RefObject<HTMLElement | null> = React.useRef(null);
+
+  const runOnceAnimationsFinish = useAnimationsFinished(panelRef, false);
+
+  const handleTrigger = useEventCallback(() => {
+    const nextOpen = !open;
+
+    const panel = panelRef.current;
+
+    if (panel) {
+      panel.style.removeProperty('animation-name');
+    }
+
+    if (!keepMounted) {
+      if (!visible && nextOpen) {
+        setVisible(true);
+      }
+      if (!mounted && nextOpen) {
+        setMounted(true);
+      }
+    }
+    setOpen(nextOpen);
+  });
+
+  useEnhancedEffect(() => {
+    const panel = panelRef.current;
+    if (!panel) {
+      return;
+    }
+
+    latestAnimationNameRef.current =
+      panel.style.animationName || latestAnimationNameRef.current;
+
+    panel.style.animationName = 'none';
+
+    setHeight(panel.scrollHeight);
+
+    if (!shouldCancelInitialOpenAnimationRef.current) {
+      panel.style.removeProperty('animation-name');
+    }
+
+    if (open) {
+      setMounted(true);
+    }
+
+    runOnceAnimationsFinish(() => {
+      setVisible(open);
+    });
+  }, [open, visible, runOnceAnimationsFinish]);
+
+  useOnMount(() => {
+    const frame = requestAnimationFrame(() => {
+      shouldCancelInitialOpenAnimationRef.current = false;
+    });
+    return () => cancelAnimationFrame(frame);
+  });
+
+  return (
+    <div
+      className={classes.Root}
+      style={{
+        // @ts-ignore
+        '--collapsible-panel-height': height ? `${height}px` : undefined,
+      }}
+    >
+      <button
+        type="button"
+        className={classes.Trigger}
+        data-panel-open={open || undefined}
+        onClick={handleTrigger}
+      >
+        <ExpandMoreIcon className={classes.Icon} />
+        Trigger {id}
+      </button>
+
+      {(keepMounted || (!keepMounted && mounted)) && (
+        <div
+          // @ts-ignore
+          ref={panelRef}
+          className={classes.Panel}
+          {...{ [open ? 'data-open' : 'data-closed']: '' }}
+          // {...styleHooks}
+          hidden={isHidden}
+          id={id}
+        >
+          <div className={classes.Content}>
+            <p>
+              He rubbed his eyes, and came close to the picture, and examined it
+              again. There were no signs of any change when he looked into the actual
+              painting, and yet there was no doubt that the whole expression had
+              altered. It was not a mere fancy of his own. The thing was horribly
+              apparent.
+            </p>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <div className={classes.grid}>
+      <div className={classes.wrapper}>
+        <pre>keepMounted: true</pre>
+        <Collapsible keepMounted defaultOpen id="1" />
+
+        <Collapsible keepMounted defaultOpen={false} id="2" />
+
+        <small>———</small>
+      </div>
+      <div className={classes.wrapper}>
+        <pre>keepMounted: false</pre>
+        <Collapsible keepMounted={false} defaultOpen id="3" />
+
+        <Collapsible keepMounted={false} defaultOpen={false} id="4" />
+        <small>———</small>
+      </div>
+    </div>
+  );
+}
+
+function ExpandMoreIcon(props: React.SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+    >
+      <path d="M16.59 8.59 12 13.17 7.41 8.59 6 10l6 6 6-6z" fill="currentColor" />
+    </svg>
+  );
+}
diff --git a/docs/src/app/(private)/experiments/collapsible/transition.tsx b/docs/src/app/(private)/experiments/collapsible/transition.tsx
index a2bbb372f6..ab64cf532d 100644
--- a/docs/src/app/(private)/experiments/collapsible/transition.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/transition.tsx
@@ -9,14 +9,19 @@ import classes from './transition.module.css';
 import { useAnimationsFinished } from '../../../../../../packages/react/src/utils/useAnimationsFinished';
 import { useEventCallback } from '../../../../../../packages/react/src/utils/useEventCallback';
 import { useForkRef } from '../../../../../../packages/react/src/utils/useForkRef';
+import { warn } from '../../../../../../packages/react/src/utils/warn';
 
 const STARTING_HOOK = { 'data-starting-style': '' };
 const ENDING_HOOK = { 'data-ending-style': '' };
 
-// const KEEP_MOUNTED = false;
+type AnimationType = 'css-transition' | 'css-animation' | 'none' | null;
 
-function Collapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
-  const { keepMounted = true, defaultOpen = false } = props;
+function Collapsible(props: {
+  defaultOpen?: boolean;
+  keepMounted?: boolean;
+  id?: string;
+}) {
+  const { keepMounted = true, defaultOpen = false, id } = props;
 
   const [open, setOpen] = React.useState(defaultOpen);
 
@@ -44,8 +49,8 @@ function Collapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
     return !open && !mounted;
   }, [keepMounted, open, mounted]);
 
+  const animationTypeRef = React.useRef<AnimationType>(null);
   const panelRef: React.RefObject<HTMLElement | null> = React.useRef(null);
-
   /**
    * When `keepMounted` is `true` this runs once as soon as it exists in the DOM
    * regardless of initial open state.
@@ -58,6 +63,29 @@ function Collapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
     if (!element) {
       return;
     }
+    if (animationTypeRef.current == null) {
+      const panelStyles = getComputedStyle(element);
+      if (
+        panelStyles.animationName !== 'none' &&
+        panelStyles.transitionDelay !== '0s'
+      ) {
+        warn('CSS transitions and CSS animations both detected');
+      } else if (
+        panelStyles.animationName === 'none' &&
+        panelStyles.transitionDuration !== '0s'
+      ) {
+        animationTypeRef.current = 'css-transition';
+      } else if (
+        panelStyles.animationName !== 'none' &&
+        panelStyles.transitionDuration === '0s'
+      ) {
+        animationTypeRef.current = 'css-animation';
+      } else {
+        animationTypeRef.current = 'none';
+      }
+    }
+    // console.log('animationType', animationTypeRef.current);
+
     /**
      * Explicitly set `display` to ensure the panel is actually rendered before
      * measuring anything. `!important` is to needed to override a conflicting
@@ -221,7 +249,7 @@ function Collapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
         onClick={handleTrigger}
       >
         <ExpandMoreIcon className={classes.Icon} />
-        Trigger {/* (keepMounted {String(keepMounted)}) */}
+        Trigger {id}
       </button>
 
       {(keepMounted || (!keepMounted && mounted)) && (
@@ -232,6 +260,7 @@ function Collapsible(props: { defaultOpen?: boolean; keepMounted?: boolean }) {
           {...{ [open ? 'data-open' : 'data-closed']: '' }}
           {...styleHooks}
           hidden={isHidden}
+          id={id}
         >
           <div className={classes.Content}>
             <p>
@@ -253,17 +282,17 @@ export default function App() {
     <div className={classes.grid}>
       <div className={classes.wrapper}>
         <pre>keepMounted: true</pre>
-        <Collapsible keepMounted defaultOpen />
+        <Collapsible keepMounted defaultOpen id="1" />
 
-        <Collapsible keepMounted defaultOpen={false} />
+        <Collapsible keepMounted defaultOpen={false} id="2" />
 
         <small>———</small>
       </div>
       <div className={classes.wrapper}>
         <pre>keepMounted: false</pre>
-        <Collapsible keepMounted={false} defaultOpen />
+        <Collapsible keepMounted={false} defaultOpen id="3" />
 
-        <Collapsible keepMounted={false} defaultOpen={false} />
+        <Collapsible keepMounted={false} defaultOpen={false} id="4" />
         <small>———</small>
       </div>
     </div>
diff --git a/docs/src/styles.css b/docs/src/styles.css
index f0142f6ee2..869c1428e7 100644
--- a/docs/src/styles.css
+++ b/docs/src/styles.css
@@ -222,6 +222,10 @@
   [data-demo]:not([data-demo='tailwind']) * {
     all: revert-layer;
   }
+
+  [hidden]:where(:not([hidden='until-found'])) {
+    display: revert-layer !important;
+  }
 }
 
 @layer all {
diff --git a/packages/react/src/collapsible/panel/useCollapsiblePanel.ts b/packages/react/src/collapsible/panel/useCollapsiblePanel.ts
index ee1072fa95..24954fc0c2 100644
--- a/packages/react/src/collapsible/panel/useCollapsiblePanel.ts
+++ b/packages/react/src/collapsible/panel/useCollapsiblePanel.ts
@@ -283,7 +283,7 @@ export function useCollapsiblePanel(
   }, [hiddenUntilFound, isOpen]);
 
   const hidden = hiddenUntilFound ? 'until-found' : 'hidden';
-
+  console.log('isOpen', isOpen);
   const getRootProps: useCollapsiblePanel.ReturnValue['getRootProps'] = React.useCallback(
     (externalProps = {}) =>
       mergeProps<'button'>(

From 4743ec8ebb9243c844a685a446da0c9e5cbf419c Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 18 Mar 2025 19:37:33 +0800
Subject: [PATCH 25/31] Merge reworked implementations

---
 .../experiments/collapsible/_icons.tsx        |  21 +
 .../collapsible/animation.module.css          |   1 -
 .../experiments/collapsible/animation.tsx     |  17 +-
 .../(private)/experiments/collapsible/new.tsx | 376 ++++++++++++++++++
 .../experiments/collapsible/transition.tsx    |  16 +-
 5 files changed, 399 insertions(+), 32 deletions(-)
 create mode 100644 docs/src/app/(private)/experiments/collapsible/_icons.tsx
 create mode 100644 docs/src/app/(private)/experiments/collapsible/new.tsx

diff --git a/docs/src/app/(private)/experiments/collapsible/_icons.tsx b/docs/src/app/(private)/experiments/collapsible/_icons.tsx
new file mode 100644
index 0000000000..e85233ea4b
--- /dev/null
+++ b/docs/src/app/(private)/experiments/collapsible/_icons.tsx
@@ -0,0 +1,21 @@
+'use client';
+import * as React from 'react';
+
+export default function Nothing() {
+  return <div>This is just a dummy file to hold icons</div>;
+}
+
+export function ExpandMoreIcon(props: React.SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+    >
+      <path d="M16.59 8.59 12 13.17 7.41 8.59 6 10l6 6 6-6z" fill="currentColor" />
+    </svg>
+  );
+}
diff --git a/docs/src/app/(private)/experiments/collapsible/animation.module.css b/docs/src/app/(private)/experiments/collapsible/animation.module.css
index 0522ca9721..6553387d34 100644
--- a/docs/src/app/(private)/experiments/collapsible/animation.module.css
+++ b/docs/src/app/(private)/experiments/collapsible/animation.module.css
@@ -22,7 +22,6 @@
   overflow: hidden;
   box-sizing: border-box;
   width: 100%;
-  animation-fill-mode: forwards !important;
 
   &[data-open] {
     animation: slide-down var(--duration) ease-out;
diff --git a/docs/src/app/(private)/experiments/collapsible/animation.tsx b/docs/src/app/(private)/experiments/collapsible/animation.tsx
index f8a6350d2a..8f7a4eab29 100644
--- a/docs/src/app/(private)/experiments/collapsible/animation.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/animation.tsx
@@ -8,8 +8,8 @@ import classes from './animation.module.css';
 
 import { useAnimationsFinished } from '../../../../../../packages/react/src/utils/useAnimationsFinished';
 import { useEventCallback } from '../../../../../../packages/react/src/utils/useEventCallback';
-// import { useForkRef } from '../../../../../../packages/react/src/utils/useForkRef';
 import { useOnMount } from '../../../../../../packages/react/src/utils/useOnMount';
+import { ExpandMoreIcon } from './_icons';
 
 function Collapsible(props: {
   defaultOpen?: boolean;
@@ -152,18 +152,3 @@ export default function App() {
     </div>
   );
 }
-
-function ExpandMoreIcon(props: React.SVGProps<SVGSVGElement>) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      {...props}
-      width="24"
-      height="24"
-      viewBox="0 0 24 24"
-      fill="none"
-    >
-      <path d="M16.59 8.59 12 13.17 7.41 8.59 6 10l6 6 6-6z" fill="currentColor" />
-    </svg>
-  );
-}
diff --git a/docs/src/app/(private)/experiments/collapsible/new.tsx b/docs/src/app/(private)/experiments/collapsible/new.tsx
new file mode 100644
index 0000000000..63c30808bb
--- /dev/null
+++ b/docs/src/app/(private)/experiments/collapsible/new.tsx
@@ -0,0 +1,376 @@
+'use client';
+import * as React from 'react';
+import {
+  useEnhancedEffect,
+  useTransitionStatus,
+} from '@base-ui-components/react/utils';
+import classes from './animation.module.css';
+import { ExpandMoreIcon } from './_icons';
+
+import { useAnimationsFinished } from '../../../../../../packages/react/src/utils/useAnimationsFinished';
+import { useEventCallback } from '../../../../../../packages/react/src/utils/useEventCallback';
+import { useForkRef } from '../../../../../../packages/react/src/utils/useForkRef';
+import { useOnMount } from '../../../../../../packages/react/src/utils/useOnMount';
+import { warn } from '../../../../../../packages/react/src/utils/warn';
+
+const STARTING_HOOK = { 'data-starting-style': '' };
+const ENDING_HOOK = { 'data-ending-style': '' };
+
+type AnimationType = 'css-transition' | 'css-animation' | 'none' | null;
+
+function Collapsible(props: {
+  defaultOpen?: boolean;
+  keepMounted?: boolean;
+  id?: string;
+}) {
+  const { keepMounted = true, defaultOpen = false, id } = props;
+
+  const [open, setOpen] = React.useState(defaultOpen);
+
+  const { mounted, setMounted, transitionStatus } = useTransitionStatus(open);
+
+  const [visible, setVisible] = React.useState(open);
+
+  const styleHooks = React.useMemo(() => {
+    if (transitionStatus === 'starting') {
+      return STARTING_HOOK;
+    }
+    if (transitionStatus === 'ending') {
+      return ENDING_HOOK;
+    }
+    return null;
+  }, [transitionStatus]);
+
+  const [height, setHeight] = React.useState<number | undefined>(undefined);
+
+  const shouldCancelInitialOpenTransitionRef = React.useRef(open);
+  const latestAnimationNameRef = React.useRef<string>(null);
+  const shouldCancelInitialOpenAnimationRef = React.useRef(open);
+
+  const animationTypeRef = React.useRef<AnimationType>(null);
+
+  const isHidden = React.useMemo(() => {
+    if (animationTypeRef.current === 'css-animation') {
+      return !visible;
+    }
+
+    if (keepMounted) {
+      return !open;
+    }
+
+    return !open && !mounted;
+  }, [keepMounted, open, mounted, visible]);
+
+  const panelRef: React.RefObject<HTMLElement | null> = React.useRef(null);
+  /**
+   * When `keepMounted` is `true` this runs once as soon as it exists in the DOM
+   * regardless of initial open state.
+   *
+   * When `keepMounted` is `false` this runs on every mount, typically every
+   * time it opens. If the panel is in the middle of a close transition that is
+   * interrupted and re-opens, this won't run as the panel was not unmounted.
+   */
+  const handlePanelRef = useEventCallback((element: HTMLElement) => {
+    if (!element) {
+      return;
+    }
+    /**
+     * This ref is safe to read in render because it's only ever set once here
+     * during the first render and never again.
+     * https://react.dev/learn/referencing-values-with-refs#best-practices-for-refs
+     */
+    if (animationTypeRef.current == null) {
+      const panelStyles = getComputedStyle(element);
+      if (
+        panelStyles.animationName !== 'none' &&
+        panelStyles.transitionDelay !== '0s'
+      ) {
+        warn('CSS transitions and CSS animations both detected');
+      } else if (
+        panelStyles.animationName === 'none' &&
+        panelStyles.transitionDuration !== '0s'
+      ) {
+        animationTypeRef.current = 'css-transition';
+      } else if (
+        panelStyles.animationName !== 'none' &&
+        panelStyles.transitionDuration === '0s'
+      ) {
+        animationTypeRef.current = 'css-animation';
+      } else {
+        animationTypeRef.current = 'none';
+      }
+    }
+    // console.log('animationType', animationTypeRef.current);
+
+    if (animationTypeRef.current !== 'css-transition') {
+      return;
+    }
+
+    /**
+     * Explicitly set `display` to ensure the panel is actually rendered before
+     * measuring anything. `!important` is to needed to override a conflicting
+     * Tailwind v4 default that sets `display: none !important` on `[hidden]`:
+     * https://github.com/tailwindlabs/tailwindcss/blame/main/packages/tailwindcss/preflight.css#L382
+     */
+    element.style.setProperty('display', 'block', 'important'); // TODO: maybe this can be set more conditionally
+
+    if (height === undefined) {
+      /**
+       * When `keepMounted={false}` and the panel is initially closed, the very
+       * first time it opens (not any subsequent opens) `data-starting-style` is
+       * off or missing by a frame so we need to set it manually. Otherwise any
+       * CSS properties expected to transition using [data-starting-style] may
+       * be mis-timed and appear to be complete skipped.
+       */
+      if (!shouldCancelInitialOpenTransitionRef.current && !keepMounted) {
+        element.setAttribute('data-starting-style', '');
+      }
+
+      setHeight(element.scrollHeight);
+      element.style.removeProperty('display');
+
+      if (shouldCancelInitialOpenTransitionRef.current) {
+        element.style.transitionDuration = '0s';
+      }
+    }
+
+    requestAnimationFrame(() => {
+      shouldCancelInitialOpenTransitionRef.current = false;
+      requestAnimationFrame(() => {
+        /**
+         * This is slightly faster than another RAF and is the earliest
+         * opportunity to remove the temporary `transition-duration: 0s` that
+         * was applied to cancel opening transitions of initially open panels.
+         * https://nolanlawson.com/2018/09/25/accurately-measuring-layout-on-the-web/
+         */
+        setTimeout(() => {
+          element.style.removeProperty('transition-duration');
+        });
+      });
+    });
+  });
+
+  const mergedRef = useForkRef(panelRef, handlePanelRef);
+
+  const abortControllerRef = React.useRef<AbortController | null>(null);
+
+  const runOnceAnimationsFinish = useAnimationsFinished(panelRef, false);
+
+  const handleTrigger = useEventCallback(() => {
+    const nextOpen = !open;
+
+    const panel = panelRef.current;
+    if (panel && animationTypeRef.current === 'css-animation') {
+      panel.style.removeProperty('animation-name');
+    }
+
+    if (!keepMounted) {
+      if (animationTypeRef.current === 'css-transition') {
+        if (!mounted && nextOpen) {
+          setMounted(true);
+        }
+      }
+
+      if (animationTypeRef.current === 'css-animation') {
+        if (!visible && nextOpen) {
+          setVisible(true);
+        }
+        if (!mounted && nextOpen) {
+          setMounted(true);
+        }
+      }
+    }
+    setOpen(nextOpen);
+
+    if (!panel || animationTypeRef.current !== 'css-transition') {
+      return;
+    }
+
+    panel.style.setProperty('display', 'block', 'important');
+
+    if (nextOpen) {
+      if (abortControllerRef.current != null) {
+        abortControllerRef.current.abort();
+        abortControllerRef.current = null;
+      }
+
+      panel.style.removeProperty('display');
+
+      /* opening */
+      panel.style.height = '0px';
+
+      requestAnimationFrame(() => {
+        panel.style.removeProperty('height');
+        setHeight(panel.scrollHeight);
+      });
+    } else {
+      /* closing */
+      requestAnimationFrame(() => {
+        setHeight(0);
+      });
+
+      abortControllerRef.current = new AbortController();
+
+      runOnceAnimationsFinish(() => {
+        // TODO: !important may be needed
+        panel.style.setProperty('display', 'none');
+        abortControllerRef.current = null;
+      }, abortControllerRef.current.signal);
+    }
+  });
+
+  /**
+   * This only handles `keepMounted={false}` as the state changes can't be done
+   * in the event handler
+   */
+  useEnhancedEffect(() => {
+    if (animationTypeRef.current !== 'css-transition') {
+      return;
+    }
+
+    if (keepMounted) {
+      return;
+    }
+
+    const panel = panelRef.current;
+    if (!panel) {
+      return;
+    }
+
+    if (open) {
+      if (abortControllerRef.current != null) {
+        abortControllerRef.current.abort();
+        abortControllerRef.current = null;
+      }
+
+      /* opening */
+      panel.style.height = '0px';
+
+      requestAnimationFrame(() => {
+        /**
+         * When `keepMounted={false}` this is the earliest opportunity to unset
+         * the temporary `display` property that was set in `handlePanelRef`
+         */
+        panel.style.removeProperty('display');
+
+        panel.style.removeProperty('height');
+
+        setHeight(panel.scrollHeight);
+      });
+    } else {
+      /* closing */
+      requestAnimationFrame(() => {
+        setHeight(0);
+      });
+
+      abortControllerRef.current = new AbortController();
+
+      runOnceAnimationsFinish(() => {
+        setMounted(false);
+        abortControllerRef.current = null;
+      }, abortControllerRef.current.signal);
+    }
+  }, [keepMounted, open, mounted, setMounted, runOnceAnimationsFinish]);
+
+  useEnhancedEffect(() => {
+    if (animationTypeRef.current !== 'css-animation') {
+      return;
+    }
+
+    const panel = panelRef.current;
+    if (!panel) {
+      return;
+    }
+
+    latestAnimationNameRef.current =
+      panel.style.animationName || latestAnimationNameRef.current;
+
+    panel.style.animationName = 'none';
+
+    setHeight(panel.scrollHeight);
+
+    if (!shouldCancelInitialOpenAnimationRef.current) {
+      panel.style.removeProperty('animation-name');
+    }
+
+    if (open) {
+      setMounted(true);
+    }
+
+    runOnceAnimationsFinish(() => {
+      setVisible(open);
+    });
+  }, [open, visible, runOnceAnimationsFinish, setMounted]);
+
+  useOnMount(() => {
+    const frame = requestAnimationFrame(() => {
+      shouldCancelInitialOpenAnimationRef.current = false;
+    });
+    return () => cancelAnimationFrame(frame);
+  });
+
+  return (
+    <div
+      className={classes.Root}
+      style={{
+        // @ts-ignore
+        '--collapsible-panel-height':
+          height !== undefined ? `${height}px` : undefined,
+      }}
+    >
+      <button
+        type="button"
+        className={classes.Trigger}
+        data-panel-open={open || undefined}
+        onClick={handleTrigger}
+      >
+        <ExpandMoreIcon className={classes.Icon} />
+        Trigger {id}
+      </button>
+
+      {(keepMounted || (!keepMounted && mounted)) && (
+        <div
+          // @ts-ignore
+          ref={mergedRef}
+          className={classes.Panel}
+          {...{ [open ? 'data-open' : 'data-closed']: '' }}
+          {...styleHooks}
+          hidden={isHidden}
+          id={id}
+        >
+          <div className={classes.Content}>
+            <p>
+              He rubbed his eyes, and came close to the picture, and examined it
+              again. There were no signs of any change when he looked into the actual
+              painting, and yet there was no doubt that the whole expression had
+              altered. It was not a mere fancy of his own. The thing was horribly
+              apparent.
+            </p>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <div className={classes.grid}>
+      <div className={classes.wrapper}>
+        <pre>keepMounted: true</pre>
+        <Collapsible keepMounted defaultOpen id="1" />
+
+        <Collapsible keepMounted defaultOpen={false} id="2" />
+
+        <small>———</small>
+      </div>
+      <div className={classes.wrapper}>
+        <pre>keepMounted: false</pre>
+        <Collapsible keepMounted={false} defaultOpen id="3" />
+
+        <Collapsible keepMounted={false} defaultOpen={false} id="4" />
+        <small>———</small>
+      </div>
+    </div>
+  );
+}
diff --git a/docs/src/app/(private)/experiments/collapsible/transition.tsx b/docs/src/app/(private)/experiments/collapsible/transition.tsx
index ab64cf532d..ca6f1f926a 100644
--- a/docs/src/app/(private)/experiments/collapsible/transition.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/transition.tsx
@@ -10,6 +10,7 @@ import { useAnimationsFinished } from '../../../../../../packages/react/src/util
 import { useEventCallback } from '../../../../../../packages/react/src/utils/useEventCallback';
 import { useForkRef } from '../../../../../../packages/react/src/utils/useForkRef';
 import { warn } from '../../../../../../packages/react/src/utils/warn';
+import { ExpandMoreIcon } from './_icons';
 
 const STARTING_HOOK = { 'data-starting-style': '' };
 const ENDING_HOOK = { 'data-ending-style': '' };
@@ -298,18 +299,3 @@ export default function App() {
     </div>
   );
 }
-
-function ExpandMoreIcon(props: React.SVGProps<SVGSVGElement>) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      {...props}
-      width="24"
-      height="24"
-      viewBox="0 0 24 24"
-      fill="none"
-    >
-      <path d="M16.59 8.59 12 13.17 7.41 8.59 6 10l6 6 6-6z" fill="currentColor" />
-    </svg>
-  );
-}

From cf7dddab065024eb164eb1f19f36197e978468f0 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 18 Mar 2025 22:17:44 +0800
Subject: [PATCH 26/31] WIP rework hidden-until-found

---
 .../(private)/experiments/collapsible/new.tsx | 38 +++++++++++++++++--
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/new.tsx b/docs/src/app/(private)/experiments/collapsible/new.tsx
index 63c30808bb..f0ec880109 100644
--- a/docs/src/app/(private)/experiments/collapsible/new.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/new.tsx
@@ -4,7 +4,7 @@ import {
   useEnhancedEffect,
   useTransitionStatus,
 } from '@base-ui-components/react/utils';
-import classes from './animation.module.css';
+import classes from './transition.module.css';
 import { ExpandMoreIcon } from './_icons';
 
 import { useAnimationsFinished } from '../../../../../../packages/react/src/utils/useAnimationsFinished';
@@ -22,8 +22,14 @@ function Collapsible(props: {
   defaultOpen?: boolean;
   keepMounted?: boolean;
   id?: string;
+  hiddenUntilFound?: boolean;
 }) {
-  const { keepMounted = true, defaultOpen = false, id } = props;
+  const {
+    keepMounted = true,
+    defaultOpen = false,
+    id,
+    hiddenUntilFound: hiddenUntilFoundProp = true,
+  } = props;
 
   const [open, setOpen] = React.useState(defaultOpen);
 
@@ -122,7 +128,12 @@ function Collapsible(props: {
        * CSS properties expected to transition using [data-starting-style] may
        * be mis-timed and appear to be complete skipped.
        */
-      if (!shouldCancelInitialOpenTransitionRef.current && !keepMounted) {
+      if (
+        (!shouldCancelInitialOpenTransitionRef.current && !keepMounted) ||
+        (hiddenUntilFoundProp &&
+          keepMounted &&
+          !shouldCancelInitialOpenTransitionRef.current)
+      ) {
         element.setAttribute('data-starting-style', '');
       }
 
@@ -188,6 +199,10 @@ function Collapsible(props: {
 
     panel.style.setProperty('display', 'block', 'important');
 
+    if (hiddenUntilFoundProp) {
+      panel.style.setProperty('content-visibility', 'visible');
+    }
+
     if (nextOpen) {
       if (abortControllerRef.current != null) {
         abortControllerRef.current.abort();
@@ -195,6 +210,7 @@ function Collapsible(props: {
       }
 
       panel.style.removeProperty('display');
+      panel.style.removeProperty('content-visibility');
 
       /* opening */
       panel.style.height = '0px';
@@ -214,6 +230,7 @@ function Collapsible(props: {
       runOnceAnimationsFinish(() => {
         // TODO: !important may be needed
         panel.style.setProperty('display', 'none');
+        panel.style.removeProperty('content-visibility');
         abortControllerRef.current = null;
       }, abortControllerRef.current.signal);
     }
@@ -309,6 +326,15 @@ function Collapsible(props: {
     return () => cancelAnimationFrame(frame);
   });
 
+  useEnhancedEffect(() => {
+    const panel = panelRef.current;
+
+    if (panel && hiddenUntilFoundProp && panel?.hidden && isHidden) {
+      // @ts-ignore
+      panel.hidden = 'until-found';
+    }
+  }, [hiddenUntilFoundProp, isHidden]);
+
   return (
     <div
       className={classes.Root}
@@ -328,7 +354,7 @@ function Collapsible(props: {
         Trigger {id}
       </button>
 
-      {(keepMounted || (!keepMounted && mounted)) && (
+      {(keepMounted || hiddenUntilFoundProp || (!keepMounted && mounted)) && (
         <div
           // @ts-ignore
           ref={mergedRef}
@@ -337,6 +363,10 @@ function Collapsible(props: {
           {...styleHooks}
           hidden={isHidden}
           id={id}
+          style={{
+            contentVisibility:
+              hiddenUntilFoundProp && mounted ? 'visible' : undefined,
+          }}
         >
           <div className={classes.Content}>
             <p>

From 2c1b53fa182841bdf6d574f33ac36379453c102b Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Tue, 18 Mar 2025 22:57:09 +0800
Subject: [PATCH 27/31] WIP 2

---
 .../collapsible/animation.module.css          |  2 +-
 .../(private)/experiments/collapsible/new.tsx | 45 ++++++++++++++++---
 .../collapsible/transition.module.css         |  2 +-
 docs/src/styles.css                           |  4 --
 4 files changed, 42 insertions(+), 11 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/animation.module.css b/docs/src/app/(private)/experiments/collapsible/animation.module.css
index 6553387d34..70060c6e76 100644
--- a/docs/src/app/(private)/experiments/collapsible/animation.module.css
+++ b/docs/src/app/(private)/experiments/collapsible/animation.module.css
@@ -51,7 +51,7 @@
 
 .Root {
   --width: 320px;
-  --duration: 800ms;
+  --duration: 5000ms;
 
   width: var(--width);
 
diff --git a/docs/src/app/(private)/experiments/collapsible/new.tsx b/docs/src/app/(private)/experiments/collapsible/new.tsx
index f0ec880109..d94352fc58 100644
--- a/docs/src/app/(private)/experiments/collapsible/new.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/new.tsx
@@ -53,6 +53,8 @@ function Collapsible(props: {
   const latestAnimationNameRef = React.useRef<string>(null);
   const shouldCancelInitialOpenAnimationRef = React.useRef(open);
 
+  const isBeforeMatchRef = React.useRef(false);
+
   const animationTypeRef = React.useRef<AnimationType>(null);
 
   const isHidden = React.useMemo(() => {
@@ -245,11 +247,15 @@ function Collapsible(props: {
       return;
     }
 
+    const panel = panelRef.current;
+
     if (keepMounted) {
+      if (panel != null && isBeforeMatchRef.current) {
+        panel.style.transitionDuration = '0s';
+      }
       return;
     }
 
-    const panel = panelRef.current;
     if (!panel) {
       return;
     }
@@ -263,6 +269,10 @@ function Collapsible(props: {
       /* opening */
       panel.style.height = '0px';
 
+      if (isBeforeMatchRef.current) {
+        panel.style.transitionDuration = '0s';
+      }
+
       requestAnimationFrame(() => {
         /**
          * When `keepMounted={false}` this is the earliest opportunity to unset
@@ -335,6 +345,31 @@ function Collapsible(props: {
     }
   }, [hiddenUntilFoundProp, isHidden]);
 
+  React.useEffect(
+    function registerBeforeMatchListener() {
+      const panel = panelRef.current;
+      if (!panel) {
+        return undefined;
+      }
+
+      function handleOnBeforeMatch(event: Event) {
+        event.preventDefault();
+
+        isBeforeMatchRef.current = true;
+
+        // beforematch only fires if the matching content is initially hidden
+        setOpen(true);
+      }
+
+      panel.addEventListener('beforematch', handleOnBeforeMatch);
+
+      return () => {
+        panel.removeEventListener('beforematch', handleOnBeforeMatch);
+      };
+    },
+    [setOpen],
+  );
+
   return (
     <div
       className={classes.Root}
@@ -388,19 +423,19 @@ export default function App() {
     <div className={classes.grid}>
       <div className={classes.wrapper}>
         <pre>keepMounted: true</pre>
-        <Collapsible keepMounted defaultOpen id="1" />
+        {/*<Collapsible keepMounted defaultOpen id="1" />*/}
 
-        <Collapsible keepMounted defaultOpen={false} id="2" />
+        <Collapsible keepMounted={false} defaultOpen={false} id="2" />
 
         <small>———</small>
       </div>
-      <div className={classes.wrapper}>
+      {/*<div className={classes.wrapper}>
         <pre>keepMounted: false</pre>
         <Collapsible keepMounted={false} defaultOpen id="3" />
 
         <Collapsible keepMounted={false} defaultOpen={false} id="4" />
         <small>———</small>
-      </div>
+      </div>*/}
     </div>
   );
 }
diff --git a/docs/src/app/(private)/experiments/collapsible/transition.module.css b/docs/src/app/(private)/experiments/collapsible/transition.module.css
index 3c8dcd370e..39bdcab47c 100644
--- a/docs/src/app/(private)/experiments/collapsible/transition.module.css
+++ b/docs/src/app/(private)/experiments/collapsible/transition.module.css
@@ -16,7 +16,7 @@
 
 .Root {
   --width: 320px;
-  --duration: 800ms;
+  --duration: 5000ms;
 
   width: var(--width);
 
diff --git a/docs/src/styles.css b/docs/src/styles.css
index 869c1428e7..f0142f6ee2 100644
--- a/docs/src/styles.css
+++ b/docs/src/styles.css
@@ -222,10 +222,6 @@
   [data-demo]:not([data-demo='tailwind']) * {
     all: revert-layer;
   }
-
-  [hidden]:where(:not([hidden='until-found'])) {
-    display: revert-layer !important;
-  }
 }
 
 @layer all {

From 4fb41b4681edee360c1e5e693f071bae19474d41 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 19 Mar 2025 03:04:08 +0800
Subject: [PATCH 28/31] WIP 3

---
 .../(private)/experiments/collapsible/new.tsx | 99 +++++++++++--------
 1 file changed, 60 insertions(+), 39 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/new.tsx b/docs/src/app/(private)/experiments/collapsible/new.tsx
index d94352fc58..d631f8f26e 100644
--- a/docs/src/app/(private)/experiments/collapsible/new.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/new.tsx
@@ -70,6 +70,7 @@ function Collapsible(props: {
   }, [keepMounted, open, mounted, visible]);
 
   const panelRef: React.RefObject<HTMLElement | null> = React.useRef(null);
+
   /**
    * When `keepMounted` is `true` this runs once as soon as it exists in the DOM
    * regardless of initial open state.
@@ -108,7 +109,6 @@ function Collapsible(props: {
         animationTypeRef.current = 'none';
       }
     }
-    // console.log('animationType', animationTypeRef.current);
 
     if (animationTypeRef.current !== 'css-transition') {
       return;
@@ -130,12 +130,11 @@ function Collapsible(props: {
        * CSS properties expected to transition using [data-starting-style] may
        * be mis-timed and appear to be complete skipped.
        */
-      if (
-        (!shouldCancelInitialOpenTransitionRef.current && !keepMounted) ||
-        (hiddenUntilFoundProp &&
-          keepMounted &&
-          !shouldCancelInitialOpenTransitionRef.current)
-      ) {
+      if (!shouldCancelInitialOpenTransitionRef.current && !keepMounted) {
+        element.setAttribute('data-starting-style', '');
+      }
+
+      if (!shouldCancelInitialOpenTransitionRef.current && hiddenUntilFoundProp) {
         element.setAttribute('data-starting-style', '');
       }
 
@@ -143,7 +142,8 @@ function Collapsible(props: {
       element.style.removeProperty('display');
 
       if (shouldCancelInitialOpenTransitionRef.current) {
-        element.style.transitionDuration = '0s';
+        element.style.setProperty('transition-duration', '0s');
+        // element.style.setProperty('display', 'none');
       }
     }
 
@@ -177,7 +177,7 @@ function Collapsible(props: {
       panel.style.removeProperty('animation-name');
     }
 
-    if (!keepMounted) {
+    if (!hiddenUntilFoundProp && !keepMounted) {
       if (animationTypeRef.current === 'css-transition') {
         if (!mounted && nextOpen) {
           setMounted(true);
@@ -201,10 +201,6 @@ function Collapsible(props: {
 
     panel.style.setProperty('display', 'block', 'important');
 
-    if (hiddenUntilFoundProp) {
-      panel.style.setProperty('content-visibility', 'visible');
-    }
-
     if (nextOpen) {
       if (abortControllerRef.current != null) {
         abortControllerRef.current.abort();
@@ -222,6 +218,9 @@ function Collapsible(props: {
         setHeight(panel.scrollHeight);
       });
     } else {
+      if (hiddenUntilFoundProp) {
+        panel.style.setProperty('content-visibility', 'visible');
+      }
       /* closing */
       requestAnimationFrame(() => {
         setHeight(0);
@@ -232,7 +231,7 @@ function Collapsible(props: {
       runOnceAnimationsFinish(() => {
         // TODO: !important may be needed
         panel.style.setProperty('display', 'none');
-        panel.style.removeProperty('content-visibility');
+        // panel.style.removeProperty('content-visibility');
         abortControllerRef.current = null;
       }, abortControllerRef.current.signal);
     }
@@ -249,18 +248,15 @@ function Collapsible(props: {
 
     const panel = panelRef.current;
 
-    if (keepMounted) {
-      if (panel != null && isBeforeMatchRef.current) {
-        panel.style.transitionDuration = '0s';
-      }
-      return;
-    }
-
     if (!panel) {
       return;
     }
 
     if (open) {
+      if (hiddenUntilFoundProp) {
+        return;
+      }
+      console.log('open here');
       if (abortControllerRef.current != null) {
         abortControllerRef.current.abort();
         abortControllerRef.current = null;
@@ -269,10 +265,6 @@ function Collapsible(props: {
       /* opening */
       panel.style.height = '0px';
 
-      if (isBeforeMatchRef.current) {
-        panel.style.transitionDuration = '0s';
-      }
-
       requestAnimationFrame(() => {
         /**
          * When `keepMounted={false}` this is the earliest opportunity to unset
@@ -293,11 +285,43 @@ function Collapsible(props: {
       abortControllerRef.current = new AbortController();
 
       runOnceAnimationsFinish(() => {
+        panel.style.removeProperty('content-visibility');
         setMounted(false);
         abortControllerRef.current = null;
       }, abortControllerRef.current.signal);
     }
-  }, [keepMounted, open, mounted, setMounted, runOnceAnimationsFinish]);
+  }, [
+    keepMounted,
+    open,
+    mounted,
+    setMounted,
+    runOnceAnimationsFinish,
+    hiddenUntilFoundProp,
+  ]);
+
+  useEnhancedEffect(() => {
+    if (!hiddenUntilFoundProp) {
+      return;
+    }
+
+    const panel = panelRef.current;
+    if (!panel) {
+      return;
+    }
+
+    if (open && isBeforeMatchRef.current) {
+      panel.style.transitionDuration = '0s';
+      setHeight(panel.scrollHeight);
+      requestAnimationFrame(() => {
+        isBeforeMatchRef.current = false;
+        requestAnimationFrame(() => {
+          setTimeout(() => {
+            panel.style.removeProperty('transition-duration');
+          });
+        });
+      });
+    }
+  }, [hiddenUntilFoundProp, open]);
 
   useEnhancedEffect(() => {
     if (animationTypeRef.current !== 'css-animation') {
@@ -339,9 +363,10 @@ function Collapsible(props: {
   useEnhancedEffect(() => {
     const panel = panelRef.current;
 
-    if (panel && hiddenUntilFoundProp && panel?.hidden && isHidden) {
+    if (panel && hiddenUntilFoundProp && isHidden) {
       // @ts-ignore
-      panel.hidden = 'until-found';
+      panel.setAttribute('hidden', 'until-found');
+      panel.setAttribute('data-starting-style', '');
     }
   }, [hiddenUntilFoundProp, isHidden]);
 
@@ -352,7 +377,7 @@ function Collapsible(props: {
         return undefined;
       }
 
-      function handleOnBeforeMatch(event: Event) {
+      function handleBeforeMatch(event: Event) {
         event.preventDefault();
 
         isBeforeMatchRef.current = true;
@@ -361,10 +386,10 @@ function Collapsible(props: {
         setOpen(true);
       }
 
-      panel.addEventListener('beforematch', handleOnBeforeMatch);
+      panel.addEventListener('beforematch', handleBeforeMatch);
 
       return () => {
-        panel.removeEventListener('beforematch', handleOnBeforeMatch);
+        panel.removeEventListener('beforematch', handleBeforeMatch);
       };
     },
     [setOpen],
@@ -398,10 +423,6 @@ function Collapsible(props: {
           {...styleHooks}
           hidden={isHidden}
           id={id}
-          style={{
-            contentVisibility:
-              hiddenUntilFoundProp && mounted ? 'visible' : undefined,
-          }}
         >
           <div className={classes.Content}>
             <p>
@@ -423,19 +444,19 @@ export default function App() {
     <div className={classes.grid}>
       <div className={classes.wrapper}>
         <pre>keepMounted: true</pre>
-        {/*<Collapsible keepMounted defaultOpen id="1" />*/}
+        <Collapsible keepMounted defaultOpen id="1" />
 
-        <Collapsible keepMounted={false} defaultOpen={false} id="2" />
+        <Collapsible keepMounted defaultOpen={false} id="2" />
 
         <small>———</small>
       </div>
-      {/*<div className={classes.wrapper}>
+      <div className={classes.wrapper}>
         <pre>keepMounted: false</pre>
         <Collapsible keepMounted={false} defaultOpen id="3" />
 
         <Collapsible keepMounted={false} defaultOpen={false} id="4" />
         <small>———</small>
-      </div>*/}
+      </div>
     </div>
   );
 }

From f8d0147e2abe54bd1a0c0b3ba2c696eb072cfdb7 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 19 Mar 2025 12:10:31 +0800
Subject: [PATCH 29/31] WIP 4

---
 .../(private)/experiments/collapsible/new.tsx | 57 +++++++++++--------
 .../collapsible/transition.module.css         |  2 +-
 .../experiments/collapsible/transition.tsx    |  2 +-
 3 files changed, 34 insertions(+), 27 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/new.tsx b/docs/src/app/(private)/experiments/collapsible/new.tsx
index d631f8f26e..05b8d9517c 100644
--- a/docs/src/app/(private)/experiments/collapsible/new.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/new.tsx
@@ -118,7 +118,7 @@ function Collapsible(props: {
      * Explicitly set `display` to ensure the panel is actually rendered before
      * measuring anything. `!important` is to needed to override a conflicting
      * Tailwind v4 default that sets `display: none !important` on `[hidden]`:
-     * https://github.com/tailwindlabs/tailwindcss/blame/main/packages/tailwindcss/preflight.css#L382
+     * https://github.com/tailwindlabs/tailwindcss/blob/cd154a4f471e7a63cc27cad15dada650de89d52b/packages/tailwindcss/preflight.css#L320-L326
      */
     element.style.setProperty('display', 'block', 'important'); // TODO: maybe this can be set more conditionally
 
@@ -134,16 +134,11 @@ function Collapsible(props: {
         element.setAttribute('data-starting-style', '');
       }
 
-      if (!shouldCancelInitialOpenTransitionRef.current && hiddenUntilFoundProp) {
-        element.setAttribute('data-starting-style', '');
-      }
-
       setHeight(element.scrollHeight);
       element.style.removeProperty('display');
 
       if (shouldCancelInitialOpenTransitionRef.current) {
         element.style.setProperty('transition-duration', '0s');
-        // element.style.setProperty('display', 'none');
       }
     }
 
@@ -173,7 +168,8 @@ function Collapsible(props: {
     const nextOpen = !open;
 
     const panel = panelRef.current;
-    if (panel && animationTypeRef.current === 'css-animation') {
+
+    if (animationTypeRef.current === 'css-animation' && panel != null) {
       panel.style.removeProperty('animation-name');
     }
 
@@ -195,6 +191,10 @@ function Collapsible(props: {
     }
     setOpen(nextOpen);
 
+    /**
+     * When `keepMounted={false}` and when opening, the element isn't inserted
+     * in the DOM at this point so bail out here and resume in an effect.
+     */
     if (!panel || animationTypeRef.current !== 'css-transition') {
       return;
     }
@@ -202,6 +202,7 @@ function Collapsible(props: {
     panel.style.setProperty('display', 'block', 'important');
 
     if (nextOpen) {
+      /* opening */
       if (abortControllerRef.current != null) {
         abortControllerRef.current.abort();
         abortControllerRef.current = null;
@@ -209,9 +210,7 @@ function Collapsible(props: {
 
       panel.style.removeProperty('display');
       panel.style.removeProperty('content-visibility');
-
-      /* opening */
-      panel.style.height = '0px';
+      panel.style.setProperty('height', '0px');
 
       requestAnimationFrame(() => {
         panel.style.removeProperty('height');
@@ -229,20 +228,19 @@ function Collapsible(props: {
       abortControllerRef.current = new AbortController();
 
       runOnceAnimationsFinish(() => {
-        // TODO: !important may be needed
-        panel.style.setProperty('display', 'none');
-        // panel.style.removeProperty('content-visibility');
+        panel.style.removeProperty('display');
+        panel.style.removeProperty('content-visibility');
         abortControllerRef.current = null;
       }, abortControllerRef.current.signal);
     }
   });
 
   /**
-   * This only handles `keepMounted={false}` as the state changes can't be done
-   * in the event handler
+   * This only handles CSS transitions when `keepMounted={false}` as we may not
+   * have access to the panel element in the DOM in the trigger event handler.
    */
   useEnhancedEffect(() => {
-    if (animationTypeRef.current !== 'css-transition') {
+    if (animationTypeRef.current !== 'css-transition' || keepMounted) {
       return;
     }
 
@@ -253,10 +251,6 @@ function Collapsible(props: {
     }
 
     if (open) {
-      if (hiddenUntilFoundProp) {
-        return;
-      }
-      console.log('open here');
       if (abortControllerRef.current != null) {
         abortControllerRef.current.abort();
         abortControllerRef.current = null;
@@ -273,7 +267,6 @@ function Collapsible(props: {
         panel.style.removeProperty('display');
 
         panel.style.removeProperty('height');
-
         setHeight(panel.scrollHeight);
       });
     } else {
@@ -363,9 +356,24 @@ function Collapsible(props: {
   useEnhancedEffect(() => {
     const panel = panelRef.current;
 
-    if (panel && hiddenUntilFoundProp && isHidden) {
-      // @ts-ignore
+    if (
+      panel &&
+      hiddenUntilFoundProp &&
+      animationTypeRef.current === 'css-transition' &&
+      isHidden
+    ) {
+      /**
+       * React only supports a boolean for the `hidden` attribute and forces
+       * legit string values to booleans so we have to force it back in the DOM
+       * when necessary: https://github.com/facebook/react/issues/24740
+       */
       panel.setAttribute('hidden', 'until-found');
+      /**
+       * Set data-starting-style here to persist the closed styles, this is to
+       * prevent transitions from starting when the `hidden` attribute changes
+       * to `'until-found'` as they could have different `display` properties:
+       * https://github.com/tailwindlabs/tailwindcss/pull/14625
+       */
       panel.setAttribute('data-starting-style', '');
     }
   }, [hiddenUntilFoundProp, isHidden]);
@@ -378,11 +386,10 @@ function Collapsible(props: {
       }
 
       function handleBeforeMatch(event: Event) {
+        // TODO: probably remove this because beforematch isn't cancellable anyway
         event.preventDefault();
 
         isBeforeMatchRef.current = true;
-
-        // beforematch only fires if the matching content is initially hidden
         setOpen(true);
       }
 
diff --git a/docs/src/app/(private)/experiments/collapsible/transition.module.css b/docs/src/app/(private)/experiments/collapsible/transition.module.css
index 39bdcab47c..1cc18c1f44 100644
--- a/docs/src/app/(private)/experiments/collapsible/transition.module.css
+++ b/docs/src/app/(private)/experiments/collapsible/transition.module.css
@@ -16,7 +16,7 @@
 
 .Root {
   --width: 320px;
-  --duration: 5000ms;
+  --duration: 1000ms;
 
   width: var(--width);
 
diff --git a/docs/src/app/(private)/experiments/collapsible/transition.tsx b/docs/src/app/(private)/experiments/collapsible/transition.tsx
index ca6f1f926a..cae940d135 100644
--- a/docs/src/app/(private)/experiments/collapsible/transition.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/transition.tsx
@@ -91,7 +91,7 @@ function Collapsible(props: {
      * Explicitly set `display` to ensure the panel is actually rendered before
      * measuring anything. `!important` is to needed to override a conflicting
      * Tailwind v4 default that sets `display: none !important` on `[hidden]`:
-     * https://github.com/tailwindlabs/tailwindcss/blame/main/packages/tailwindcss/preflight.css#L382
+     * https://github.com/tailwindlabs/tailwindcss/blob/cd154a4f471e7a63cc27cad15dada650de89d52b/packages/tailwindcss/preflight.css#L320-L326
      */
     element.style.setProperty('display', 'block', 'important'); // TODO: maybe this can be set more conditionally
 

From 00f99b80c41f45c337f0aedef59c89360b916910 Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 19 Mar 2025 12:26:11 +0800
Subject: [PATCH 30/31] CSS animation fixes

---
 .../experiments/collapsible/animation.module.css |  2 +-
 .../(private)/experiments/collapsible/new.tsx    | 16 +++++++++-------
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/animation.module.css b/docs/src/app/(private)/experiments/collapsible/animation.module.css
index 70060c6e76..e719704c6d 100644
--- a/docs/src/app/(private)/experiments/collapsible/animation.module.css
+++ b/docs/src/app/(private)/experiments/collapsible/animation.module.css
@@ -51,7 +51,7 @@
 
 .Root {
   --width: 320px;
-  --duration: 5000ms;
+  --duration: 900ms;
 
   width: var(--width);
 
diff --git a/docs/src/app/(private)/experiments/collapsible/new.tsx b/docs/src/app/(private)/experiments/collapsible/new.tsx
index 05b8d9517c..987945e9df 100644
--- a/docs/src/app/(private)/experiments/collapsible/new.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/new.tsx
@@ -4,7 +4,7 @@ import {
   useEnhancedEffect,
   useTransitionStatus,
 } from '@base-ui-components/react/utils';
-import classes from './transition.module.css';
+import classes from './animation.module.css';
 import { ExpandMoreIcon } from './_icons';
 
 import { useAnimationsFinished } from '../../../../../../packages/react/src/utils/useAnimationsFinished';
@@ -28,7 +28,7 @@ function Collapsible(props: {
     keepMounted = true,
     defaultOpen = false,
     id,
-    hiddenUntilFound: hiddenUntilFoundProp = true,
+    hiddenUntilFound: hiddenUntilFoundProp = false,
   } = props;
 
   const [open, setOpen] = React.useState(defaultOpen);
@@ -329,7 +329,7 @@ function Collapsible(props: {
     latestAnimationNameRef.current =
       panel.style.animationName || latestAnimationNameRef.current;
 
-    panel.style.animationName = 'none';
+    panel.style.setProperty('animation-name', 'none');
 
     setHeight(panel.scrollHeight);
 
@@ -339,11 +339,13 @@ function Collapsible(props: {
 
     if (open) {
       setMounted(true);
+      setVisible(true);
+    } else {
+      runOnceAnimationsFinish(() => {
+        setMounted(false);
+        setVisible(false);
+      });
     }
-
-    runOnceAnimationsFinish(() => {
-      setVisible(open);
-    });
   }, [open, visible, runOnceAnimationsFinish, setMounted]);
 
   useOnMount(() => {

From 5c9a15913cb69859b1d705eb8fefaeef1ec56a9f Mon Sep 17 00:00:00 2001
From: Albert Yu <albert@albertyu.co>
Date: Wed, 19 Mar 2025 12:34:32 +0800
Subject: [PATCH 31/31] Handle beforematch with CSS animations

---
 .../(private)/experiments/collapsible/new.tsx | 22 +++++++------------
 1 file changed, 8 insertions(+), 14 deletions(-)

diff --git a/docs/src/app/(private)/experiments/collapsible/new.tsx b/docs/src/app/(private)/experiments/collapsible/new.tsx
index 987945e9df..b1ff6e47e4 100644
--- a/docs/src/app/(private)/experiments/collapsible/new.tsx
+++ b/docs/src/app/(private)/experiments/collapsible/new.tsx
@@ -28,7 +28,7 @@ function Collapsible(props: {
     keepMounted = true,
     defaultOpen = false,
     id,
-    hiddenUntilFound: hiddenUntilFoundProp = false,
+    hiddenUntilFound: hiddenUntilFoundProp = true,
   } = props;
 
   const [open, setOpen] = React.useState(defaultOpen);
@@ -92,7 +92,7 @@ function Collapsible(props: {
       const panelStyles = getComputedStyle(element);
       if (
         panelStyles.animationName !== 'none' &&
-        panelStyles.transitionDelay !== '0s'
+        panelStyles.transitionDuration !== '0s'
       ) {
         warn('CSS transitions and CSS animations both detected');
       } else if (
@@ -333,7 +333,7 @@ function Collapsible(props: {
 
     setHeight(panel.scrollHeight);
 
-    if (!shouldCancelInitialOpenAnimationRef.current) {
+    if (!shouldCancelInitialOpenAnimationRef.current && !isBeforeMatchRef.current) {
       panel.style.removeProperty('animation-name');
     }
 
@@ -358,12 +358,7 @@ function Collapsible(props: {
   useEnhancedEffect(() => {
     const panel = panelRef.current;
 
-    if (
-      panel &&
-      hiddenUntilFoundProp &&
-      animationTypeRef.current === 'css-transition' &&
-      isHidden
-    ) {
+    if (panel && hiddenUntilFoundProp && isHidden) {
       /**
        * React only supports a boolean for the `hidden` attribute and forces
        * legit string values to booleans so we have to force it back in the DOM
@@ -376,7 +371,9 @@ function Collapsible(props: {
        * to `'until-found'` as they could have different `display` properties:
        * https://github.com/tailwindlabs/tailwindcss/pull/14625
        */
-      panel.setAttribute('data-starting-style', '');
+      if (animationTypeRef.current === 'css-transition') {
+        panel.setAttribute('data-starting-style', '');
+      }
     }
   }, [hiddenUntilFoundProp, isHidden]);
 
@@ -387,10 +384,7 @@ function Collapsible(props: {
         return undefined;
       }
 
-      function handleBeforeMatch(event: Event) {
-        // TODO: probably remove this because beforematch isn't cancellable anyway
-        event.preventDefault();
-
+      function handleBeforeMatch() {
         isBeforeMatchRef.current = true;
         setOpen(true);
       }