feat(sidebar): warn when a resize handle has no usable bounds

Co-Authored-By: Claude <noreply@anthropic.com>

Author: frankieyan

src/sidebar/sidebar.mdx

@@ -89,6 +89,11 @@ the inner edge (right for `align="start"`, left for `align="end"`), drives a
 render-free pointer drag, and commits the width through `onWidthChange` on
 pointer up. Width is controlled by the consumer.
 
+A resizable sidebar needs `width`, `minWidth`, and `maxWidth` on `Sidebar` (with
+`minWidth` below `maxWidth`), plus `resizeStep` for keyboard steps and
+`defaultWidth` for the double-click reset. Without a usable range the handle
+renders and focuses but cannot move, and logs a development warning.
+
 <Canvas of={SidebarStories.Resizable} />
 
 Keyboard support, from the separator:

src/sidebar/sidebar.test.tsx

@@ -456,7 +456,7 @@ describe('errors', () => {
 describe('accessibility', () => {
     it('has no axe violations as a docked nav', async () => {
         const { container } = render(
-            <Sidebar align="start" isOpen id="nav">
+            <Sidebar align="start" isOpen id="nav" width={280} minWidth={210} maxWidth={420}>
                 <SidebarContent>
                     <nav aria-label="Main navigation">
                         <a href="#projects">Projects</a>

src/sidebar/sidebar.tsx

@@ -484,6 +484,19 @@ function SidebarResizeHandle({
     const minValuePx = minWidth ?? committedWidth
     const maxValuePx = maxWidth ?? committedWidth
 
+    const hasResizeRange = minWidth != null && maxWidth != null && minWidth < maxWidth
+    if (width == null) {
+        // eslint-disable-next-line no-console
+        console.warn(
+            '[Sidebar]: <SidebarResizeHandle> needs a controlled `width` on <Sidebar> to resize; the handle renders but cannot move.',
+        )
+    } else if (!hasResizeRange) {
+        // eslint-disable-next-line no-console
+        console.warn(
+            '[Sidebar]: <SidebarResizeHandle> needs `minWidth` and `maxWidth` (with minWidth < maxWidth) on <Sidebar>; without a range the handle renders but cannot move.',
+        )
+    }
+
     const { currentValuePx, onDoubleClick, onKeyDown, onPointerDown } = useResizablePanel({
         cssVariable: SIDEBAR_WIDTH_VAR,
         defaultValuePx: defaultWidth ?? committedWidth,