@hyphen/hyphen-components 9.0.0 → 9.1.1

package/dist/index.d.ts

@@ -2225,6 +2225,19 @@ interface ResponsiveProviderProps {
 }
 declare const ResponsiveProvider: React__default.FC<ResponsiveProviderProps>;
 
+interface SidebarResizeProps {
+    /** Enable desktop resizing with SidebarRail. Disabled by default. */
+    resizable?: boolean;
+    /** Initial expanded width in pixels. Defaults to 256 left / 384 right. */
+    defaultWidth?: number;
+    /** Minimum expanded width in pixels. Defaults to 256. */
+    minWidth?: number;
+    /** Maximum expanded width in pixels, also capped at 2/3 of the provider. */
+    maxWidth?: number;
+    /** Optional localStorage key for the preferred expanded width. */
+    widthStorageKey?: string;
+}
+
 declare const TooltipProvider: React.FC<TooltipPrimitive.TooltipProviderProps>;
 declare const Tooltip: React.FC<TooltipPrimitive.TooltipProps>;
 declare const TooltipTrigger: React.ForwardRefExoticComponent<TooltipPrimitive.TooltipTriggerProps & React.RefAttributes<HTMLButtonElement>>;
@@ -2268,7 +2281,7 @@ declare const SidebarProvider: React__default.ForwardRefExoticComponent<Omit<Rea
      */
     onOpenChange?: (open: boolean, side?: SidebarSide) => void;
 }, "ref"> & React__default.RefAttributes<HTMLDivElement>>;
-declare const Sidebar: React__default.ForwardRefExoticComponent<Omit<React__default.ClassAttributes<HTMLDivElement> & React__default.HTMLAttributes<HTMLDivElement> & {
+declare const Sidebar: React__default.ForwardRefExoticComponent<Omit<React__default.ClassAttributes<HTMLDivElement> & React__default.HTMLAttributes<HTMLDivElement> & SidebarResizeProps & {
     /**
      * Which edge of the viewport the sidebar is attached to.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyphen/hyphen-components",
-  "version": "9.0.0",
+  "version": "9.1.1",
   "license": "MIT",
   "author": {
     "name": "@hyphen"
@@ -40,6 +40,7 @@
     "@radix-ui/react-aspect-ratio": "^1.1.9",
     "@radix-ui/react-collapsible": "^1.1.13",
     "@radix-ui/react-dropdown-menu": "^2.1.17",
+    "@radix-ui/react-id": "^1.1.4",
     "@radix-ui/react-popover": "^1.1.16",
     "@radix-ui/react-slot": "^1.2.5",
     "@radix-ui/react-toggle": "^1.1.11",
@@ -52,11 +53,11 @@
     "react-focus-lock": "^2.13.2",
     "react-modal": "^3.16.3",
     "react-remove-scroll": "^2.7.2",
-    "react-router-dom": "^6.30.4",
+    "react-router-dom": "^6.30.6",
     "react-select": "^5.10.0",
     "react-select-event": "^5.5.1",
     "uuid": "^11.1.1",
-    "@hyphen/hyphen-design-tokens": "^9.0.0"
+    "@hyphen/hyphen-design-tokens": "^9.1.1"
   },
   "devDependencies": {
     "@babel/core": "^7.27.4",

package/src/components/Sidebar/Sidebar.mdx

@@ -206,3 +206,21 @@ The sidebar exposes CSS custom properties you can override on `SidebarProvider`
 - `SidebarRail` is removed from the tab order (`tabIndex={-1}`) since `SidebarTrigger` and the keyboard shortcuts cover keyboard users; it exposes an `aria-label` and a `title` with the shortcut.
 - `SidebarMenu` and `SidebarMenuSub` render semantic lists, and `asChild` lets menu items render real links for correct link semantics.
 - On mobile the sidebar renders inside a [Drawer](/docs/components-drawer--docs), which traps focus and closes with <kbd>Esc</kbd>.
+
+## Resizable sidebars
+
+Opt in with `resizable` and include a `SidebarRail`. Either side can resize independently on desktop. Drag the rail to resize; click to toggle. Keyboard users can focus the rail, move it with Left/Right arrows (10px), use Home/End for limits, and Enter/Space to toggle. Mobile drawers keep their existing behavior.
+
+```tsx
+<Sidebar side="right" resizable defaultWidth={384} minWidth={320} maxWidth={960}
+  widthStorageKey="agent-panel-width">
+  <SidebarContent>{/* content */}</SidebarContent>
+  <SidebarRail />
+</Sidebar>
+```
+
+Widths are pixels. Defaults are 256px on the left, 384px on the right, a 256px minimum, and a 960px maximum. Rendered width is additionally capped at two-thirds of the `SidebarProvider` container; fitting the container takes precedence over the minimum. Temporary container constraints and collapse do not overwrite the preferred expanded width.
+
+`widthStorageKey` is optional. Supply a distinct key per panel to restore its preferred width across reloads. Without a key, width lasts until the sidebar unmounts. Existing sidebars remain unchanged unless `resizable` is enabled.
+
+<Canvas of={Stories.ResizableBothSides} />

package/src/components/Sidebar/Sidebar.module.scss

@@ -26,3 +26,21 @@
   ) {
   display: none;
 }
+
+.resizeDescription {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+// Widen the hit area without moving the existing visible rail.
+.rail[data-resizable]::before {
+  content: '';
+  position: absolute;
+  inset: 0 -7px;
+}

package/src/components/Sidebar/Sidebar.react17.test.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import { Sidebar, SidebarProvider, SidebarRail } from './Sidebar';
+
+// React 16.8 and 17 are in the peer range but have no React.useId.
+jest.mock('react', () => ({ ...jest.requireActual('react'), useId: undefined }));
+jest.mock('../../hooks/useIsMobile/useIsMobile', () => ({
+  useIsMobile: () => false,
+}));
+
+beforeEach(() => {
+  window.ResizeObserver = jest.fn().mockImplementation(() => ({
+    observe: jest.fn(),
+    disconnect: jest.fn(),
+  }));
+});
+
+test('SidebarRail renders without React.useId', () => {
+  render(
+    <SidebarProvider>
+      <Sidebar side="left">
+        <SidebarRail />
+      </Sidebar>
+      <Sidebar side="right" resizable>
+        <SidebarRail />
+      </Sidebar>
+    </SidebarProvider>
+  );
+  expect(
+    screen.getByRole('button', { name: 'Toggle Sidebar' })
+  ).toBeInTheDocument();
+  expect(
+    screen.getByRole('button', { name: 'Resize or toggle right sidebar' })
+  ).toHaveAccessibleDescription(/^Width \d+ pixels/);
+});

package/src/components/Sidebar/Sidebar.resize.test.tsx

@@ -0,0 +1,391 @@
+import React from 'react';
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import {
+  Sidebar,
+  SidebarProvider,
+  SidebarRail,
+  SidebarTrigger,
+} from './Sidebar';
+import { useIsMobile } from '../../hooks/useIsMobile/useIsMobile';
+
+jest.mock('../../hooks/useIsMobile/useIsMobile', () => ({
+  useIsMobile: jest.fn(() => false),
+}));
+
+let containerWidth = 1800;
+let notifyResize: () => void;
+const disconnect = jest.fn();
+
+function Example({
+  side = 'right',
+  resizable = true,
+  collapsible = 'offcanvas',
+}: {
+  side?: 'left' | 'right';
+  resizable?: boolean;
+  collapsible?: 'offcanvas' | 'icon' | 'none';
+}) {
+  return (
+    <SidebarProvider>
+      <Sidebar
+        side={side}
+        resizable={resizable}
+        defaultWidth={384}
+        minWidth={320}
+        maxWidth={960}
+        widthStorageKey={`width-${side}`}
+        collapsible={collapsible}
+      >
+        <SidebarRail />
+      </Sidebar>
+      <SidebarTrigger side={side} />
+    </SidebarProvider>
+  );
+}
+Example.displayName = 'Example';
+
+function width(side = 'right') {
+  return document
+    .querySelector<HTMLElement>(`[data-side="${side}"]`)!
+    .style.getPropertyValue('--sidebar-width');
+}
+function transitionDuration(side = 'right') {
+  return (
+    document.querySelector(`[data-side="${side}"]`)!
+      .firstElementChild as HTMLElement
+  ).style.transitionDuration;
+}
+function drag(rail: HTMLElement, from: number, to: number) {
+  fireEvent.pointerDown(rail, { pointerId: 1, button: 0, clientX: from });
+  fireEvent.pointerMove(rail, { pointerId: 1, clientX: to });
+  fireEvent.pointerUp(rail, { pointerId: 1, clientX: to });
+  fireEvent.click(rail, { detail: 1 });
+}
+
+beforeEach(() => {
+  localStorage.clear();
+  containerWidth = 1800;
+  jest.mocked(useIsMobile).mockReturnValue(false);
+  jest
+    .spyOn(HTMLElement.prototype, 'getBoundingClientRect')
+    .mockImplementation(() => ({
+      width: containerWidth,
+      height: 900,
+      x: 0,
+      y: 0,
+      top: 0,
+      left: 0,
+      right: containerWidth,
+      bottom: 900,
+      toJSON: () => ({}),
+    }));
+  // jsdom has no PointerEvent or pointer capture implementation.
+  window.PointerEvent = MouseEvent as typeof PointerEvent;
+  HTMLElement.prototype.setPointerCapture = jest.fn();
+  HTMLElement.prototype.releasePointerCapture = jest.fn();
+  window.ResizeObserver = jest.fn().mockImplementation((callback) => {
+    notifyResize = callback;
+    return { observe: jest.fn(), disconnect };
+  });
+});
+
+test.each(['left', 'right'] as const)(
+  'resizes %s without toggling and persists on release',
+  (side) => {
+    render(<Example side={side} />);
+    const rail = screen.getByRole('button', {
+      name: `Resize or toggle ${side} sidebar`,
+    });
+    drag(rail, 500, side === 'left' ? 700 : 300);
+    expect(width(side)).toBe('584px');
+    expect(document.querySelector(`[data-side="${side}"]`)).toHaveAttribute(
+      'data-state',
+      'expanded'
+    );
+    expect(localStorage.getItem(`width-${side}`)).toBe('584');
+    expect(document.body.style.userSelect).toBe('');
+  }
+);
+
+test('restores a saved width without animating to it', () => {
+  localStorage.setItem('width-right', '700');
+  const commits: { width: string; duration: string }[] = [];
+  render(
+    <React.Profiler
+      id="sidebar"
+      onRender={() =>
+        commits.push({ width: width(), duration: transitionDuration() })
+      }
+    >
+      <Example />
+    </React.Profiler>
+  );
+  const animatedWidthChanges = commits.filter(
+    (commit, i) =>
+      i > 0 &&
+      commit.width !== commits[i - 1].width &&
+      commit.duration !== '0ms'
+  );
+  expect(animatedWidthChanges).toEqual([]);
+  expect(width()).toBe('700px');
+  expect(transitionDuration()).toBe(
+    'var(--sidebar-transition-duration, 200ms)'
+  );
+});
+
+test('a click with movement under the threshold toggles and reopening preserves width', () => {
+  render(<Example />);
+  const rail = screen.getByRole('button', { name: /Resize or toggle/ });
+  drag(rail, 500, 400);
+  drag(rail, 500, 502);
+  expect(document.querySelector('[data-side="right"]')).toHaveAttribute(
+    'data-state',
+    'collapsed'
+  );
+  fireEvent.click(screen.getByRole('button', { name: 'Toggle right sidebar' }));
+  expect(width()).toBe('484px');
+});
+
+test('keyboard resizing respects bounds and container changes preserve preferred size', () => {
+  localStorage.setItem('width-right', '900');
+  render(<Example />);
+  const rail = screen.getByRole('button', { name: /Resize or toggle/ });
+  expect(rail).toHaveAttribute('tabindex', '0');
+  expect(width()).toBe('900px');
+  fireEvent.keyDown(rail, { key: 'End' });
+  expect(width()).toBe('960px');
+  act(() => {
+    containerWidth = 900;
+    notifyResize();
+  });
+  expect(width()).toBe('600px');
+  expect(localStorage.getItem('width-right')).toBe('960');
+  act(() => {
+    containerWidth = 1800;
+    notifyResize();
+  });
+  expect(width()).toBe('960px');
+  fireEvent.keyDown(rail, { key: 'Home' });
+  fireEvent.keyDown(rail, { key: 'ArrowRight' });
+  expect(width()).toBe('320px');
+  fireEvent.keyDown(rail, { key: 'ArrowLeft' });
+  expect(width()).toBe('330px');
+  act(() => {
+    containerWidth = 300;
+    notifyResize();
+  });
+  expect(width()).toBe('200px');
+});
+
+test.each(['altKey', 'ctrlKey', 'metaKey', 'shiftKey'])(
+  'leaves %s arrow and Home/End keys to the browser',
+  (modifier) => {
+    render(<Example />);
+    const rail = screen.getByRole('button', { name: /Resize or toggle/ });
+    for (const key of ['ArrowLeft', 'ArrowRight', 'Home', 'End']) {
+      expect(fireEvent.keyDown(rail, { key, [modifier]: true })).toBe(true);
+    }
+    expect(width()).toBe('384px');
+    expect(localStorage.getItem('width-right')).toBeNull();
+  }
+);
+
+test('left and right widths are independent', () => {
+  render(
+    <SidebarProvider>
+      <Sidebar side="left" resizable>
+        <SidebarRail />
+      </Sidebar>
+      <Sidebar side="right" resizable>
+        <SidebarRail />
+      </Sidebar>
+    </SidebarProvider>
+  );
+  fireEvent.keyDown(
+    screen.getByRole('button', { name: /Resize or toggle left/ }),
+    { key: 'ArrowRight' }
+  );
+  expect(width('left')).toBe('266px');
+  expect(width('right')).toBe('384px');
+});
+
+test.each(['nonsense', '-1', 'Infinity'])(
+  'ignores invalid stored width %s',
+  (saved) => {
+    localStorage.setItem('width-right', saved);
+    render(<Example />);
+    expect(width()).toBe('384px');
+  }
+);
+
+test('unavailable storage does not block resizing', () => {
+  jest.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+    throw new Error('blocked');
+  });
+  jest.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+    throw new Error('blocked');
+  });
+  render(<Example />);
+  fireEvent.keyDown(screen.getByRole('button', { name: /Resize or toggle/ }), {
+    key: 'ArrowLeft',
+  });
+  expect(width()).toBe('394px');
+});
+
+test('cancel restores the starting width and unmount cleans up an active drag', () => {
+  const { unmount } = render(<Example />);
+  const rail = screen.getByRole('button', { name: /Resize or toggle/ });
+  fireEvent.pointerDown(rail, { button: 0, clientX: 500 });
+  fireEvent.pointerMove(rail, { clientX: 300 });
+  expect(width()).toBe('584px');
+  expect(document.body.style.userSelect).toBe('none');
+  fireEvent.pointerCancel(rail);
+  expect(width()).toBe('384px');
+  expect(localStorage.getItem('width-right')).toBeNull();
+  fireEvent.pointerDown(rail, { button: 0, clientX: 500 });
+  fireEvent.pointerMove(rail, { clientX: 300 });
+  unmount();
+  expect(document.body.style.userSelect).toBe('');
+  expect(disconnect).toHaveBeenCalled();
+});
+
+test('non-resizable sidebars retain their original rail and width', () => {
+  render(<Example resizable={false} />);
+  expect(width()).toBe('24rem');
+  expect(
+    screen.getByRole('button', { name: 'Toggle Sidebar' })
+  ).toHaveAttribute('tabindex', '-1');
+});
+
+test('icon collapse retains width and disables resizing until reopened', () => {
+  render(<Example collapsible="icon" />);
+  drag(screen.getByRole('button', { name: /Resize or toggle/ }), 500, 400);
+  fireEvent.click(screen.getByRole('button', { name: /Resize or toggle/ }));
+  expect(
+    screen.queryByRole('button', { name: /Resize or toggle/ })
+  ).not.toBeInTheDocument();
+  fireEvent.click(screen.getByRole('button', { name: 'Toggle right sidebar' }));
+  expect(width()).toBe('484px');
+});
+
+test('non-collapsible sidebars can resize', () => {
+  render(<Example collapsible="none" />);
+  const rail = screen.getByRole('button', { name: /Resize or toggle/ });
+  fireEvent.keyDown(rail, { key: 'End' });
+  expect(
+    rail
+      .closest<HTMLElement>('[style*="--sidebar-width"]')!
+      .style.getPropertyValue('--sidebar-width')
+  ).toBe('960px');
+});
+
+test('mobile uses its drawer without resize controls', () => {
+  jest.mocked(useIsMobile).mockReturnValue(true);
+  render(<Example />);
+  fireEvent.click(screen.getByRole('button', { name: 'Toggle right sidebar' }));
+  expect(document.querySelector('[data-mobile="true"]')).toBeInTheDocument();
+  expect(
+    screen.queryByRole('button', { name: /Resize or toggle/ })
+  ).not.toBeInTheDocument();
+});
+
+test('pointer movement clamps at both bounds', () => {
+  render(<Example />);
+  const rail = screen.getByRole('button', { name: /Resize or toggle/ });
+  drag(rail, 500, -1000);
+  expect(width()).toBe('960px');
+  drag(rail, 500, 1500);
+  expect(width()).toBe('320px');
+});
+
+test.each(['left', 'right'] as const)(
+  'keeps the last dragged %s width when capture ends before pointerup',
+  (side) => {
+    render(<Example side={side} />);
+    const rail = screen.getByRole('button', {
+      name: `Resize or toggle ${side} sidebar`,
+    });
+    const endX = side === 'left' ? 700 : 300;
+    fireEvent.pointerDown(rail, { pointerId: 1, button: 0, clientX: 500 });
+    // Do not pause for a render between the last move and losing capture.
+    act(() => {
+      fireEvent.pointerMove(rail, { pointerId: 1, clientX: endX });
+      fireEvent.lostPointerCapture(rail, { pointerId: 1 });
+    });
+    expect(width(side)).toBe('584px');
+    expect(localStorage.getItem(`width-${side}`)).toBe('584');
+    expect(document.body.style.cursor).toBe('');
+    expect(document.body.style.userSelect).toBe('');
+    fireEvent.pointerUp(rail, { pointerId: 1, clientX: endX });
+    fireEvent.click(rail, { detail: 1 });
+    expect(width(side)).toBe('584px');
+    expect(document.querySelector(`[data-side="${side}"]`)).toHaveAttribute(
+      'data-state',
+      'expanded'
+    );
+  }
+);
+
+test('resizes without ResizeObserver and removes its window listener on unmount', () => {
+  Object.defineProperty(window, 'ResizeObserver', {
+    configurable: true,
+    writable: true,
+    value: undefined,
+  });
+  const removeListener = jest.spyOn(window, 'removeEventListener');
+  const { unmount } = render(<Example />);
+  const rail = screen.getByRole('button', { name: /Resize or toggle/ });
+  drag(rail, 500, 300);
+  expect(width()).toBe('584px');
+  act(() => {
+    containerWidth = 600;
+    window.dispatchEvent(new Event('resize'));
+  });
+  expect(width()).toBe('400px');
+  act(() => {
+    containerWidth = 1800;
+    window.dispatchEvent(new Event('resize'));
+  });
+  expect(width()).toBe('584px');
+  unmount();
+  expect(removeListener).toHaveBeenCalledWith('resize', expect.any(Function));
+});
+
+test.each(['left', 'right'] as const)(
+  'the %s caret inherits the resize cursor only when expanded',
+  (side) => {
+    render(<Example side={side} collapsible="icon" />);
+    const rail = screen.getByRole('button', {
+      name: `Resize or toggle ${side} sidebar`,
+    });
+    const caret = rail.firstElementChild;
+    expect(rail).toHaveStyle({ cursor: 'col-resize' });
+    expect(caret).not.toHaveClass('cursor-w-resize');
+    expect(caret).not.toHaveClass('cursor-e-resize');
+    fireEvent.click(rail);
+    expect(caret).toHaveClass(
+      side === 'left' ? 'cursor-e-resize' : 'cursor-w-resize'
+    );
+  }
+);
+
+test.each(['release', 'cancel'])(
+  'keyboard activation toggles after drag %s without a pointer click',
+  (ending) => {
+    render(<Example />);
+    const rail = screen.getByRole('button', { name: /Resize or toggle/ });
+    fireEvent.pointerDown(rail, { pointerId: 1, button: 0, clientX: 500 });
+    fireEvent.pointerMove(rail, { pointerId: 1, clientX: 300 });
+    if (ending === 'release') {
+      fireEvent.pointerUp(rail, { pointerId: 1, clientX: 300 });
+    } else {
+      fireEvent.pointerCancel(rail, { pointerId: 1 });
+    }
+    // Native button keyboard activation has detail 0 and no pointerdown.
+    fireEvent.click(rail, { detail: 0 });
+    expect(document.querySelector('[data-side="right"]')).toHaveAttribute(
+      'data-state',
+      'collapsed'
+    );
+  }
+);

package/src/components/Sidebar/Sidebar.stories.tsx

@@ -746,3 +746,39 @@ const OrgSwitcher = ({
     </DropdownMenu>
   );
 };
+
+export const ResizableBothSides = () => (
+  <SidebarProvider>
+    <Sidebar
+      side="left"
+      collapsible="icon"
+      resizable
+      widthStorageKey="storybook-sidebar-left-width"
+    >
+      <SidebarHeader>Resizable navigation</SidebarHeader>
+      <SidebarRail />
+    </Sidebar>
+    <SidebarInset>
+      <Card height="100" padding="2xl">
+        <SidebarTrigger />
+        <SidebarTrigger side="right" />
+        <p>
+          Drag either rail to resize, or click to collapse. Focus a rail and use
+          arrow keys to resize.
+        </p>
+      </Card>
+    </SidebarInset>
+    <Sidebar
+      side="right"
+      resizable
+      defaultWidth={384}
+      minWidth={320}
+      maxWidth={960}
+      widthStorageKey="storybook-sidebar-right-width"
+    >
+      <SidebarHeader>Resizable agent panel</SidebarHeader>
+      <SidebarRail />
+    </Sidebar>
+  </SidebarProvider>
+);
+ResizableBothSides.displayName = 'ResizableBothSides';

package/src/components/Sidebar/Sidebar.test.tsx

@@ -124,6 +124,52 @@ describe('Sidebar', () => {
     expect(rightSidebar).toHaveAttribute('data-state', 'collapsed');
   });
 
+  test.each([
+    ['Cmd', { metaKey: true }],
+    ['Ctrl', { ctrlKey: true }],
+  ])('leaves %s+[ and ] to the browser', (_label, modifier) => {
+    render(
+      <SidebarProvider>
+        <Sidebar side="left">
+          <div>Left</div>
+        </Sidebar>
+        <Sidebar side="right">
+          <div>Right</div>
+        </Sidebar>
+      </SidebarProvider>
+    );
+
+    expect(fireEvent.keyDown(window, { key: '[', ...modifier })).toBe(true);
+    expect(fireEvent.keyDown(window, { key: ']', ...modifier })).toBe(true);
+    expect(document.querySelector('[data-side="left"]')).toHaveAttribute(
+      'data-state',
+      'expanded'
+    );
+    expect(document.querySelector('[data-side="right"]')).toHaveAttribute(
+      'data-state',
+      'expanded'
+    );
+  });
+
+  test.each([
+    ['AltGraph', { ctrlKey: true, altKey: true, modifierAltGraph: true }],
+    ['Option', { altKey: true }],
+  ])('toggles when [ is typed with %s', (_label, modifier) => {
+    render(
+      <SidebarProvider>
+        <Sidebar side="left">
+          <div>Left</div>
+        </Sidebar>
+      </SidebarProvider>
+    );
+
+    fireEvent.keyDown(window, { key: '[', ...modifier });
+    expect(document.querySelector('[data-side="left"]')).toHaveAttribute(
+      'data-state',
+      'collapsed'
+    );
+  });
+
   test('calls onOpenChange callback when sidebar state changes', () => {
     const onOpenChange = jest.fn();
     render(