@neynar/ui 1.1.0 → 1.2.0

package/dist/components/ui/resizable.d.ts

@@ -6,12 +6,23 @@ type ResizablePanelGroupProps = React.ComponentProps<typeof PanelGroup>;
  * Supports both horizontal and vertical layouts with optional persistence via `id` prop.
  */
 declare function ResizablePanelGroup({ className, ...props }: ResizablePanelGroupProps): import("react/jsx-runtime").JSX.Element;
-type ResizablePanelProps = React.ComponentProps<typeof Panel>;
+type ResizablePanelProps = Omit<React.ComponentProps<typeof Panel>, "panelRef"> & {
+    /** Enable smooth CSS transition for collapse/expand. Drag resizing stays instant. @default false */
+    animated?: boolean;
+    /** Controlled collapsed state. When provided, the panel syncs to this value. */
+    collapsed?: boolean;
+};
 /**
  * Individual resizable panel within a ResizablePanelGroup.
  * Supports size constraints (minSize, maxSize), default sizing, and collapse behavior.
+ *
+ * Control collapse state declaratively via the `collapsed` prop.
+ * When `animated` is true, collapse/expand transitions are smooth.
+ *
+ * @example
+ * <ResizablePanel collapsed={isCollapsed} animated collapsible>
  */
-declare function ResizablePanel({ ...props }: ResizablePanelProps): import("react/jsx-runtime").JSX.Element;
+declare function ResizablePanel({ className, animated, collapsed, ...props }: ResizablePanelProps): import("react/jsx-runtime").JSX.Element;
 type ResizableHandleProps = React.ComponentProps<typeof PanelResizeHandle> & {
     /** Display a visible grip indicator on the resize handle. @default false */
     withHandle?: boolean;

package/dist/components/ui/resizable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resizable.d.ts","sourceRoot":"","sources":["../../../src/components/ui/resizable.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EACL,KAAK,IAAI,UAAU,EACnB,KAAK,EACL,SAAS,IAAI,iBAAiB,EAC/B,MAAM,wBAAwB,CAAC;AAIhC,KAAK,wBAAwB,GAAG,KAAK,CAAC,cAAc,CAAC,OAAO,UAAU,CAAC,CAAC;AAExE;;;GAGG;AACH,iBAAS,mBAAmB,CAAC,EAC3B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,wBAAwB,2CAW1B;AAED,KAAK,mBAAmB,GAAG,KAAK,CAAC,cAAc,CAAC,OAAO,KAAK,CAAC,CAAC;AAE9D;;;GAGG;AACH,iBAAS,cAAc,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,mBAAmB,2CAExD;AAED,KAAK,oBAAoB,GAAG,KAAK,CAAC,cAAc,CAAC,OAAO,iBAAiB,CAAC,GAAG;IAC3E,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;GAGG;AACH,iBAAS,eAAe,CAAC,EACvB,UAAU,EACV,SAAS,EACT,GAAG,KAAK,EACT,EAAE,oBAAoB,2CAetB;AAED,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,CAAC"}
+{"version":3,"file":"resizable.d.ts","sourceRoot":"","sources":["../../../src/components/ui/resizable.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EACL,KAAK,IAAI,UAAU,EACnB,KAAK,EACL,SAAS,IAAI,iBAAiB,EAE/B,MAAM,wBAAwB,CAAC;AAYhC,KAAK,wBAAwB,GAAG,KAAK,CAAC,cAAc,CAAC,OAAO,UAAU,CAAC,CAAC;AAExE;;;GAGG;AACH,iBAAS,mBAAmB,CAAC,EAC3B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,wBAAwB,2CAW1B;AAED,KAAK,mBAAmB,GAAG,IAAI,CAC7B,KAAK,CAAC,cAAc,CAAC,OAAO,KAAK,CAAC,EAClC,UAAU,CACX,GAAG;IACF,oGAAoG;IACpG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF;;;;;;;;;GASG;AACH,iBAAS,cAAc,CAAC,EACtB,SAAS,EACT,QAAQ,EACR,SAAS,EACT,GAAG,KAAK,EACT,EAAE,mBAAmB,2CAmErB;AAED,KAAK,oBAAoB,GAAG,KAAK,CAAC,cAAc,CAAC,OAAO,iBAAiB,CAAC,GAAG;IAC3E,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;GAGG;AACH,iBAAS,eAAe,CAAC,EACvB,UAAU,EACV,SAAS,EACT,GAAG,KAAK,EACT,EAAE,oBAAoB,2CAetB;AAED,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,CAAC"}

package/dist/components/ui/resizable.js

@@ -1,8 +1,10 @@
 "use client";
 import { jsx } from "react/jsx-runtime";
-import "react";
+import * as React from "react";
 import { Group as Tt, Panel as $t, Separator as Ht } from "../../node_modules/react-resizable-panels/dist/react-resizable-panels.js";
 import { cn } from "../../lib/utils.js";
+const TRANSITION_DURATION = 300;
+const TRANSITION_STYLE = "flex-grow 0.3s cubic-bezier(0.16, 1, 0.3, 1), flex-basis 0.3s cubic-bezier(0.16, 1, 0.3, 1)";
 function ResizablePanelGroup({
   className,
   ...props
@@ -19,8 +21,65 @@ function ResizablePanelGroup({
     }
   );
 }
-function ResizablePanel({ ...props }) {
-  return /* @__PURE__ */ jsx($t, { "data-slot": "resizable-panel", ...props });
+function ResizablePanel({
+  className,
+  animated,
+  collapsed,
+  ...props
+}) {
+  const panelRef = React.useRef(null);
+  const elementRef = React.useRef(null);
+  const animatedRef = React.useRef(animated);
+  const isFirstRender = React.useRef(true);
+  React.useEffect(() => {
+    animatedRef.current = animated;
+  }, [animated]);
+  const withTransition = React.useCallback(
+    (action, skipAnimation = false) => {
+      const panelEl = elementRef.current?.closest(
+        '[data-panel][data-slot="resizable-panel"]'
+      );
+      if (animatedRef.current && panelEl && !skipAnimation) {
+        panelEl.style.transition = TRANSITION_STYLE;
+        action();
+        setTimeout(() => {
+          panelEl.style.transition = "";
+        }, TRANSITION_DURATION);
+      } else {
+        action();
+      }
+    },
+    []
+  );
+  React.useEffect(() => {
+    if (collapsed === void 0) return;
+    if (isFirstRender.current) {
+      isFirstRender.current = false;
+      requestAnimationFrame(() => {
+        if (collapsed) {
+          panelRef.current?.collapse();
+        }
+      });
+      return;
+    }
+    const isCurrentlyCollapsed = panelRef.current?.isCollapsed() ?? false;
+    if (collapsed === isCurrentlyCollapsed) return;
+    if (collapsed) {
+      withTransition(() => panelRef.current?.collapse());
+    } else {
+      withTransition(() => panelRef.current?.expand());
+    }
+  }, [collapsed, withTransition]);
+  return /* @__PURE__ */ jsx(
+    $t,
+    {
+      "data-slot": "resizable-panel",
+      panelRef,
+      elementRef,
+      className: cn(className),
+      ...props
+    }
+  );
 }
 function ResizableHandle({
   withHandle,

package/dist/components/ui/resizable.js.map

@@ -1 +1 @@
-{"version":3,"file":"resizable.js","sources":["../../../src/components/ui/resizable.tsx"],"sourcesContent":["\"use client\";\n\nimport * as React from \"react\";\nimport {\n  Group as PanelGroup,\n  Panel,\n  Separator as PanelResizeHandle,\n} from \"react-resizable-panels\";\n\nimport { cn } from \"@/lib/utils\";\n\ntype ResizablePanelGroupProps = React.ComponentProps<typeof PanelGroup>;\n\n/**\n * Container for resizable panels. Manages layout orientation and panel resizing behavior.\n * Supports both horizontal and vertical layouts with optional persistence via `id` prop.\n */\nfunction ResizablePanelGroup({\n  className,\n  ...props\n}: ResizablePanelGroupProps) {\n  return (\n    <PanelGroup\n      data-slot=\"resizable-panel-group\"\n      className={cn(\n        \"flex h-full w-full aria-[orientation=vertical]:flex-col\",\n        className,\n      )}\n      {...props}\n    />\n  );\n}\n\ntype ResizablePanelProps = React.ComponentProps<typeof Panel>;\n\n/**\n * Individual resizable panel within a ResizablePanelGroup.\n * Supports size constraints (minSize, maxSize), default sizing, and collapse behavior.\n */\nfunction ResizablePanel({ ...props }: ResizablePanelProps) {\n  return <Panel data-slot=\"resizable-panel\" {...props} />;\n}\n\ntype ResizableHandleProps = React.ComponentProps<typeof PanelResizeHandle> & {\n  /** Display a visible grip indicator on the resize handle. @default false */\n  withHandle?: boolean;\n};\n\n/**\n * Resize handle between panels. Appears as a thin line with optional visible grip indicator.\n * Supports keyboard navigation and focus states.\n */\nfunction ResizableHandle({\n  withHandle,\n  className,\n  ...props\n}: ResizableHandleProps) {\n  return (\n    <PanelResizeHandle\n      data-slot=\"resizable-handle\"\n      className={cn(\n        \"group bg-border focus-visible:ring-primary/50 focus-visible:bg-primary/50 relative flex w-px items-center justify-center after:absolute after:inset-y-0 after:left-1/2 after:w-1 after:-translate-x-1/2 focus-visible:ring-1 focus-visible:ring-offset-1 focus-visible:ring-offset-background focus-visible:outline-hidden data-[resize-handle-state=hover]:bg-primary/50 data-[resize-handle-state=drag]:bg-primary/50 data-[resize-handle-state=active]:bg-primary/50 aria-[orientation=horizontal]:h-px aria-[orientation=horizontal]:w-full aria-[orientation=horizontal]:after:left-0 aria-[orientation=horizontal]:after:h-1 aria-[orientation=horizontal]:after:w-full aria-[orientation=horizontal]:after:translate-x-0 aria-[orientation=horizontal]:after:-translate-y-1/2 [&[aria-orientation=horizontal]>div]:rotate-90\",\n        className,\n      )}\n      {...props}\n    >\n      {withHandle && (\n        <div className=\"bg-border group-focus-visible:bg-primary/50 group-data-[resize-handle-state=hover]:bg-primary/50 group-data-[resize-handle-state=drag]:bg-primary/50 group-data-[resize-handle-state=active]:bg-primary/50 h-6 w-1 rounded-lg z-10 flex shrink-0\" />\n      )}\n    </PanelResizeHandle>\n  );\n}\n\nexport {\n  ResizablePanelGroup,\n  ResizablePanel,\n  ResizableHandle,\n  type ResizablePanelGroupProps,\n  type ResizablePanelProps,\n  type ResizableHandleProps,\n};\n"],"names":["PanelGroup","PanelResizeHandle"],"mappings":";;;;;AAiBA;AAA6B;AAC3B;AAEF;AACE;AACE;AAACA;AAAA;AACW;AACC;AACT;AACA;AAAA;AAEE;AAAA;AAGV;AAQA;AACE;AACF;AAWA;AAAyB;AACvB;AACA;AAEF;AACE;AACE;AAACC;AAAA;AACW;AACC;AACT;AACA;AAAA;AAEE;AAGgQ;AAAA;AAI1Q;;;;;;"}
+{"version":3,"file":"resizable.js","sources":["../../../src/components/ui/resizable.tsx"],"sourcesContent":["\"use client\";\n\nimport * as React from \"react\";\nimport {\n  Group as PanelGroup,\n  Panel,\n  Separator as PanelResizeHandle,\n  type PanelImperativeHandle,\n} from \"react-resizable-panels\";\n\nimport { cn } from \"@/lib/utils\";\n\n/** Duration of the collapse/expand animation in milliseconds. */\nconst TRANSITION_DURATION = 300;\n\n/** CSS transition value for animated collapse/expand. */\nconst TRANSITION_STYLE =\n  \"flex-grow 0.3s cubic-bezier(0.16, 1, 0.3, 1), flex-basis 0.3s cubic-bezier(0.16, 1, 0.3, 1)\";\n\n\ntype ResizablePanelGroupProps = React.ComponentProps<typeof PanelGroup>;\n\n/**\n * Container for resizable panels. Manages layout orientation and panel resizing behavior.\n * Supports both horizontal and vertical layouts with optional persistence via `id` prop.\n */\nfunction ResizablePanelGroup({\n  className,\n  ...props\n}: ResizablePanelGroupProps) {\n  return (\n    <PanelGroup\n      data-slot=\"resizable-panel-group\"\n      className={cn(\n        \"flex h-full w-full aria-[orientation=vertical]:flex-col\",\n        className,\n      )}\n      {...props}\n    />\n  );\n}\n\ntype ResizablePanelProps = Omit<\n  React.ComponentProps<typeof Panel>,\n  \"panelRef\"\n> & {\n  /** Enable smooth CSS transition for collapse/expand. Drag resizing stays instant. @default false */\n  animated?: boolean;\n  /** Controlled collapsed state. When provided, the panel syncs to this value. */\n  collapsed?: boolean;\n};\n\n/**\n * Individual resizable panel within a ResizablePanelGroup.\n * Supports size constraints (minSize, maxSize), default sizing, and collapse behavior.\n *\n * Control collapse state declaratively via the `collapsed` prop.\n * When `animated` is true, collapse/expand transitions are smooth.\n *\n * @example\n * <ResizablePanel collapsed={isCollapsed} animated collapsible>\n */\nfunction ResizablePanel({\n  className,\n  animated,\n  collapsed,\n  ...props\n}: ResizablePanelProps) {\n  const panelRef = React.useRef<PanelImperativeHandle>(null);\n  const elementRef = React.useRef<HTMLDivElement>(null);\n  const animatedRef = React.useRef(animated);\n  const isFirstRender = React.useRef(true);\n\n  // Keep the ref in sync with prop changes\n  React.useEffect(() => {\n    animatedRef.current = animated;\n  }, [animated]);\n\n  /** Apply transition, call action, then remove transition after duration */\n  const withTransition = React.useCallback(\n    (action: () => void, skipAnimation = false) => {\n      const panelEl = elementRef.current?.closest(\n        '[data-panel][data-slot=\"resizable-panel\"]',\n      ) as HTMLElement | null;\n\n      if (animatedRef.current && panelEl && !skipAnimation) {\n        panelEl.style.transition = TRANSITION_STYLE;\n        action();\n        setTimeout(() => {\n          panelEl.style.transition = \"\";\n        }, TRANSITION_DURATION);\n      } else {\n        action();\n      }\n    },\n    [],\n  );\n\n  // Sync collapsed prop to panel state\n  React.useEffect(() => {\n    if (collapsed === undefined) return;\n\n    // On first render, defer to allow panel registration\n    if (isFirstRender.current) {\n      isFirstRender.current = false;\n      // Use requestAnimationFrame to ensure panel is registered\n      requestAnimationFrame(() => {\n        if (collapsed) {\n          panelRef.current?.collapse();\n        }\n      });\n      return;\n    }\n\n    // After first render, check current state before acting\n    const isCurrentlyCollapsed = panelRef.current?.isCollapsed() ?? false;\n    if (collapsed === isCurrentlyCollapsed) return;\n\n    if (collapsed) {\n      withTransition(() => panelRef.current?.collapse());\n    } else {\n      withTransition(() => panelRef.current?.expand());\n    }\n  }, [collapsed, withTransition]);\n\n  return (\n    <Panel\n      data-slot=\"resizable-panel\"\n      panelRef={panelRef}\n      elementRef={elementRef}\n      className={cn(className)}\n      {...props}\n    />\n  );\n}\n\ntype ResizableHandleProps = React.ComponentProps<typeof PanelResizeHandle> & {\n  /** Display a visible grip indicator on the resize handle. @default false */\n  withHandle?: boolean;\n};\n\n/**\n * Resize handle between panels. Appears as a thin line with optional visible grip indicator.\n * Supports keyboard navigation and focus states.\n */\nfunction ResizableHandle({\n  withHandle,\n  className,\n  ...props\n}: ResizableHandleProps) {\n  return (\n    <PanelResizeHandle\n      data-slot=\"resizable-handle\"\n      className={cn(\n        \"group bg-border focus-visible:ring-primary/50 focus-visible:bg-primary/50 relative flex w-px items-center justify-center after:absolute after:inset-y-0 after:left-1/2 after:w-1 after:-translate-x-1/2 focus-visible:ring-1 focus-visible:ring-offset-1 focus-visible:ring-offset-background focus-visible:outline-hidden data-[resize-handle-state=hover]:bg-primary/50 data-[resize-handle-state=drag]:bg-primary/50 data-[resize-handle-state=active]:bg-primary/50 aria-[orientation=horizontal]:h-px aria-[orientation=horizontal]:w-full aria-[orientation=horizontal]:after:left-0 aria-[orientation=horizontal]:after:h-1 aria-[orientation=horizontal]:after:w-full aria-[orientation=horizontal]:after:translate-x-0 aria-[orientation=horizontal]:after:-translate-y-1/2 [&[aria-orientation=horizontal]>div]:rotate-90\",\n        className,\n      )}\n      {...props}\n    >\n      {withHandle && (\n        <div className=\"bg-border group-focus-visible:bg-primary/50 group-data-[resize-handle-state=hover]:bg-primary/50 group-data-[resize-handle-state=drag]:bg-primary/50 group-data-[resize-handle-state=active]:bg-primary/50 h-6 w-1 rounded-lg z-10 flex shrink-0\" />\n      )}\n    </PanelResizeHandle>\n  );\n}\n\nexport {\n  ResizablePanelGroup,\n  ResizablePanel,\n  ResizableHandle,\n  type ResizablePanelGroupProps,\n  type ResizablePanelProps,\n  type ResizableHandleProps,\n};\n"],"names":["PanelGroup","Panel","PanelResizeHandle"],"mappings":";;;;;AAaA;AAGA;AAUA;AAA6B;AAC3B;AAEF;AACE;AACE;AAACA;AAAA;AACW;AACC;AACT;AACA;AAAA;AAEE;AAAA;AAGV;AAsBA;AAAwB;AACtB;AACA;AACA;AAEF;AACE;AACA;AACA;AACA;AAGA;AACE;AAAsB;AAIxB;AAA6B;AAEzB;AAAoC;AAClC;AAGF;AACE;AACA;AACA;AACE;AAA2B;AACP;AAEtB;AAAA;AACF;AACF;AACA;AAIF;AACE;AAGA;AACE;AAEA;AACE;AACE;AAAkB;AACpB;AAEF;AAAA;AAIF;AACA;AAEA;AACE;AAAiD;AAEjD;AAA+C;AACjD;AAGF;AACE;AAACC;AAAA;AACW;AACV;AACA;AACuB;AACnB;AAAA;AAGV;AAWA;AAAyB;AACvB;AACA;AAEF;AACE;AACE;AAACC;AAAA;AACW;AACC;AACT;AACA;AAAA;AAEE;AAGgQ;AAAA;AAI1Q;;;;;;"}

package/llm/components/resizable.llm.md

@@ -70,7 +70,11 @@ All panels inherit props from react-resizable-panels Panel component.
 | maxSize | number \| string | 100 | Maximum size (number=pixels, string=percentage or CSS unit) |
 | collapsible | boolean | false | Allow panel to collapse below minSize |
 | collapsedSize | number \| string | 0 | Size when collapsed |
+| collapsed | boolean | - | Controlled collapsed state. Panel syncs to this value. |
+| animated | boolean | false | Enable smooth CSS transition for collapse/expand. Drag resizing stays instant. |
 | onResize | (size: { asPercentage: number; inPixels: number }) => void | - | Called when panel is resized |
+| onCollapse | () => void | - | Called when panel collapses |
+| onExpand | () => void | - | Called when panel expands |
 | className | string | - | Additional CSS classes |
 
 ### ResizableHandle
@@ -222,6 +226,48 @@ function MonitoredPanels() {
 }
 ```
 
+### Animated Collapse/Expand
+
+Use `collapsed` prop for declarative control and `animated` for smooth transitions. Drag resizing remains instant (no animation lag).
+
+```tsx
+import { useState } from "react"
+import {
+  ResizablePanelGroup,
+  ResizablePanel,
+  ResizableHandle,
+} from "@neynar/ui/resizable"
+import { Button } from "@neynar/ui/button"
+
+function CollapsibleSidebar() {
+  const [isCollapsed, setIsCollapsed] = useState(false)
+
+  return (
+    <div className="h-[400px]">
+      <Button onClick={() => setIsCollapsed(!isCollapsed)}>
+        {isCollapsed ? "Expand" : "Collapse"} Sidebar
+      </Button>
+      <ResizablePanelGroup orientation="horizontal">
+        <ResizablePanel
+          collapsed={isCollapsed}
+          animated
+          defaultSize="25%"
+          minSize="15%"
+          collapsible
+          collapsedSize="0%"
+        >
+          <div className="p-4">Sidebar content</div>
+        </ResizablePanel>
+        <ResizableHandle withHandle />
+        <ResizablePanel>
+          <div className="p-4">Main content</div>
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </div>
+  )
+}
+```
+
 ## Keyboard
 
 | Key | Action |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neynar/ui",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "license": "MIT",
   "author": "Neynar Inc.",
   "description": "AI-first React component library for coding agents. LLM-optimized docs, sensible defaults, zero config. Built on shadcn patterns, Base UI, and Tailwind CSS v4.",

package/src/components/neynar/typography/stories/title.stories.tsx

@@ -343,7 +343,9 @@ export const LargeMultiLine: Story = {
     <div className="w-full max-w-2xl space-y-8">
       <section className="space-y-4">
         <div>
-          <h3 className="text-lg font-semibold">Large Sizes with Multi-line Text</h3>
+          <h3 className="text-lg font-semibold">
+            Large Sizes with Multi-line Text
+          </h3>
           <p className="text-muted-foreground text-sm">
             5xl and 6xl sizes with proper line-height to prevent text overlap.
           </p>

package/src/components/ui/resizable.tsx

@@ -5,10 +5,19 @@ import {
   Group as PanelGroup,
   Panel,
   Separator as PanelResizeHandle,
+  type PanelImperativeHandle,
 } from "react-resizable-panels";
 
 import { cn } from "@/lib/utils";
 
+/** Duration of the collapse/expand animation in milliseconds. */
+const TRANSITION_DURATION = 300;
+
+/** CSS transition value for animated collapse/expand. */
+const TRANSITION_STYLE =
+  "flex-grow 0.3s cubic-bezier(0.16, 1, 0.3, 1), flex-basis 0.3s cubic-bezier(0.16, 1, 0.3, 1)";
+
+
 type ResizablePanelGroupProps = React.ComponentProps<typeof PanelGroup>;
 
 /**
@@ -31,14 +40,98 @@ function ResizablePanelGroup({
   );
 }
 
-type ResizablePanelProps = React.ComponentProps<typeof Panel>;
+type ResizablePanelProps = Omit<
+  React.ComponentProps<typeof Panel>,
+  "panelRef"
+> & {
+  /** Enable smooth CSS transition for collapse/expand. Drag resizing stays instant. @default false */
+  animated?: boolean;
+  /** Controlled collapsed state. When provided, the panel syncs to this value. */
+  collapsed?: boolean;
+};
 
 /**
  * Individual resizable panel within a ResizablePanelGroup.
  * Supports size constraints (minSize, maxSize), default sizing, and collapse behavior.
+ *
+ * Control collapse state declaratively via the `collapsed` prop.
+ * When `animated` is true, collapse/expand transitions are smooth.
+ *
+ * @example
+ * <ResizablePanel collapsed={isCollapsed} animated collapsible>
  */
-function ResizablePanel({ ...props }: ResizablePanelProps) {
-  return <Panel data-slot="resizable-panel" {...props} />;
+function ResizablePanel({
+  className,
+  animated,
+  collapsed,
+  ...props
+}: ResizablePanelProps) {
+  const panelRef = React.useRef<PanelImperativeHandle>(null);
+  const elementRef = React.useRef<HTMLDivElement>(null);
+  const animatedRef = React.useRef(animated);
+  const isFirstRender = React.useRef(true);
+
+  // Keep the ref in sync with prop changes
+  React.useEffect(() => {
+    animatedRef.current = animated;
+  }, [animated]);
+
+  /** Apply transition, call action, then remove transition after duration */
+  const withTransition = React.useCallback(
+    (action: () => void, skipAnimation = false) => {
+      const panelEl = elementRef.current?.closest(
+        '[data-panel][data-slot="resizable-panel"]',
+      ) as HTMLElement | null;
+
+      if (animatedRef.current && panelEl && !skipAnimation) {
+        panelEl.style.transition = TRANSITION_STYLE;
+        action();
+        setTimeout(() => {
+          panelEl.style.transition = "";
+        }, TRANSITION_DURATION);
+      } else {
+        action();
+      }
+    },
+    [],
+  );
+
+  // Sync collapsed prop to panel state
+  React.useEffect(() => {
+    if (collapsed === undefined) return;
+
+    // On first render, defer to allow panel registration
+    if (isFirstRender.current) {
+      isFirstRender.current = false;
+      // Use requestAnimationFrame to ensure panel is registered
+      requestAnimationFrame(() => {
+        if (collapsed) {
+          panelRef.current?.collapse();
+        }
+      });
+      return;
+    }
+
+    // After first render, check current state before acting
+    const isCurrentlyCollapsed = panelRef.current?.isCollapsed() ?? false;
+    if (collapsed === isCurrentlyCollapsed) return;
+
+    if (collapsed) {
+      withTransition(() => panelRef.current?.collapse());
+    } else {
+      withTransition(() => panelRef.current?.expand());
+    }
+  }, [collapsed, withTransition]);
+
+  return (
+    <Panel
+      data-slot="resizable-panel"
+      panelRef={panelRef}
+      elementRef={elementRef}
+      className={cn(className)}
+      {...props}
+    />
+  );
 }
 
 type ResizableHandleProps = React.ComponentProps<typeof PanelResizeHandle> & {

package/src/components/ui/stories/resizable.stories.tsx

@@ -3,6 +3,8 @@ import {
   CodeIcon,
   FileIcon,
   FolderIcon,
+  PanelLeftCloseIcon,
+  PanelLeftOpenIcon,
   PlayIcon,
   TerminalIcon,
 } from "lucide-react";
@@ -167,6 +169,103 @@ export function Counter() {
   },
 };
 
+/**
+ * Animated collapse/expand using the `collapsed` and `animated` props.
+ * Control collapse state declaratively - no ref needed.
+ * Toggle the animated prop to compare instant vs smooth transitions.
+ */
+export const AnimatedCollapse: Story = {
+  parameters: {
+    layout: "padded",
+  },
+  render: () => {
+    function AnimatedCollapseDemo() {
+      const [isCollapsed, setIsCollapsed] = useState(false);
+      const [animated, setAnimated] = useState(true);
+
+      return (
+        <div className="space-y-4">
+          <div className="flex gap-2">
+            <Button
+              onClick={() => setIsCollapsed(!isCollapsed)}
+              variant="default"
+            >
+              {isCollapsed ? (
+                <PanelLeftOpenIcon data-icon="inline-start" />
+              ) : (
+                <PanelLeftCloseIcon data-icon="inline-start" />
+              )}
+              {isCollapsed ? "Expand" : "Collapse"}
+            </Button>
+            <Button
+              onClick={() => setAnimated(!animated)}
+              variant={animated ? "secondary" : "outline"}
+            >
+              Animated: {animated ? "On" : "Off"}
+            </Button>
+          </div>
+          <div className="border-border h-[400px] w-full rounded-lg border">
+            <ResizablePanelGroup orientation="horizontal">
+              <ResizablePanel
+                collapsed={isCollapsed}
+                animated={animated}
+                defaultSize="25%"
+                minSize="15%"
+                maxSize="40%"
+                collapsible
+                collapsedSize="0%"
+              >
+                <div className="flex h-full flex-col">
+                  <div className="border-b p-3">
+                    <h3 className="flex items-center gap-2 text-sm font-semibold">
+                      <FolderIcon className="size-4" />
+                      Sidebar
+                    </h3>
+                  </div>
+                  <div className="flex-1 overflow-auto p-4">
+                    <div className="space-y-2">
+                      {["Dashboard", "Analytics", "Reports", "Settings"].map(
+                        (item) => (
+                          <div
+                            key={item}
+                            className="hover:bg-accent rounded px-2 py-1.5 text-sm transition-colors"
+                          >
+                            {item}
+                          </div>
+                        ),
+                      )}
+                    </div>
+                  </div>
+                </div>
+              </ResizablePanel>
+              <ResizableHandle withHandle />
+              <ResizablePanel defaultSize="75%">
+                <div className="flex h-full flex-col">
+                  <div className="border-b p-3">
+                    <h3 className="text-sm font-semibold">Main Content</h3>
+                  </div>
+                  <div className="flex-1 p-4">
+                    <p className="text-muted-foreground text-sm">
+                      The sidebar uses{" "}
+                      <code className="bg-muted rounded px-1 text-xs">
+                        collapsed={"{isCollapsed}"}
+                      </code>{" "}
+                      for declarative control. Toggle the button above to
+                      compare instant vs animated transitions.
+                    </p>
+                  </div>
+                </div>
+              </ResizablePanel>
+            </ResizablePanelGroup>
+          </div>
+        </div>
+      );
+    }
+
+    return <AnimatedCollapseDemo />;
+  },
+};
+
 /**
  * Complete design system reference showing all resizable panel configurations,
  * directions, handle styles, and complex layouts.