feat(ui): Add <Collapsible /> component (#7716)

Author: alexcarpenter

.changeset/soft-wings-flow.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': minor
+---
+
+Introduce `<Collapsible />` component and update `<CardAlert />` implementation to fix enter/exit animations.

packages/ui/src/customizables/elementDescriptors.ts

@@ -32,6 +32,9 @@ export const APPEARANCE_KEYS = containsAllElementsConfigKeys([
   'disclosureContentInner',
   'disclosureContent',
 
+  'collapsible',
+  'collapsibleInner',
+
   'lineItemsRoot',
   'lineItemsDivider',
   'lineItemsGroup',

packages/ui/src/elements/Card/CardAlert.tsx

@@ -1,16 +1,18 @@
 import React from 'react';
 
-import { animations, type PropsOfComponent } from '../../styledSystem';
+import type { PropsOfComponent } from '../../styledSystem';
 import { Alert } from '../Alert';
+import { Collapsible } from '../Collapsible';
 
 export const CardAlert = React.memo((props: PropsOfComponent<typeof Alert>) => {
+  const hasContent = Boolean(props.children);
+
   return (
-    <Alert
-      variant='danger'
-      sx={theme => ({
-        animation: `${animations.textInBig} ${theme.transitionDuration.$slow}`,
-      })}
-      {...props}
-    />
+    <Collapsible open={hasContent}>
+      <Alert
+        variant='danger'
+        {...props}
+      />
+    </Collapsible>
   );
 });

packages/ui/src/elements/Collapsible.tsx

@@ -0,0 +1,96 @@
+import { type PropsWithChildren, useEffect, useState } from 'react';
+
+import { Box, descriptors, useAppearance } from '../customizables';
+import { usePrefersReducedMotion } from '../hooks';
+import type { ThemableCssProp } from '../styledSystem';
+
+type CollapsibleProps = PropsWithChildren<{
+  open: boolean;
+  sx?: ThemableCssProp;
+}>;
+
+// Register custom property for animatable mask size
+if (typeof CSS !== 'undefined' && 'registerProperty' in CSS) {
+  try {
+    CSS.registerProperty({
+      name: '--cl-collapsible-mask-size',
+      syntax: '<length>',
+      initialValue: '0px',
+      inherits: false,
+    });
+  } catch {
+    // Property already registered or not supported
+  }
+}
+
+export function Collapsible({ open, children, sx }: CollapsibleProps): JSX.Element | null {
+  const prefersReducedMotion = usePrefersReducedMotion();
+  const { animations } = useAppearance().parsedOptions;
+  const isMotionSafe = !prefersReducedMotion && animations;
+
+  const [shouldRender, setShouldRender] = useState(open);
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  useEffect(() => {
+    if (open) {
+      setShouldRender(true);
+      const frame = requestAnimationFrame(() => setIsExpanded(true));
+      return () => cancelAnimationFrame(frame);
+    }
+
+    setIsExpanded(false);
+    if (!isMotionSafe) {
+      setShouldRender(false);
+    }
+  }, [open, isMotionSafe]);
+
+  function handleTransitionEnd(e: React.TransitionEvent): void {
+    if (e.target !== e.currentTarget) {
+      return;
+    }
+    if (!open) {
+      setShouldRender(false);
+    }
+  }
+
+  const isFullyOpen = open && isExpanded;
+  const isAnimating = shouldRender && !isFullyOpen;
+
+  if (!shouldRender) {
+    return null;
+  }
+
+  return (
+    <Box
+      elementDescriptor={descriptors.collapsible}
+      onTransitionEnd={handleTransitionEnd}
+      sx={[
+        t => ({
+          display: 'grid',
+          gridTemplateRows: isExpanded ? '1fr' : '0fr',
+          opacity: isExpanded ? 1 : 0,
+          transition: isMotionSafe
+            ? `grid-template-rows ${t.transitionDuration.$fast} ease-out, opacity ${t.transitionDuration.$fast} ease-out`
+            : 'none',
+        }),
+        sx,
+      ]}
+      // @ts-ignore - inert not yet in React types
+      inert={!open ? '' : undefined}
+    >
+      <Box
+        elementDescriptor={descriptors.collapsibleInner}
+        sx={t => ({
+          overflow: 'hidden',
+          minHeight: 0,
+          '--cl-collapsible-mask-size': isAnimating ? '0.5rem' : '0px',
+          maskImage:
+            'linear-gradient(to bottom, black, black calc(100% - var(--cl-collapsible-mask-size)), transparent)',
+          transition: isMotionSafe ? `--cl-collapsible-mask-size ${t.transitionDuration.$slow}` : 'none',
+        })}
+      >
+        {children}
+      </Box>
+    </Box>
+  );
+}