@hyphen/hyphen-components 9.0.0 → 9.1.0

package/src/components/Sidebar/Sidebar.tsx

@@ -5,6 +5,7 @@ import React, {
   useEffect,
   forwardRef,
 } from 'react';
+import { useId } from '@radix-ui/react-id';
 import { Slot } from '@radix-ui/react-slot';
 import classNames from 'classnames';
 import { Button } from '../Button/Button';
@@ -14,6 +15,11 @@ import { Box } from '../Box/Box';
 import { IconName } from 'src/types';
 import { Icon } from '../Icon/Icon';
 import styles from './Sidebar.module.scss';
+import {
+  SidebarResizeContext,
+  SidebarResizeProps,
+  useSidebarResize,
+} from './useSidebarResize';
 import {
   Tooltip,
   TooltipContent,
@@ -326,6 +332,14 @@ const SidebarProvider = forwardRef<
         ) {
           return;
         }
+        // Leave Cmd/Ctrl combinations (e.g. Cmd+[ for back) to the browser.
+        // AltGraph also sets ctrlKey on Windows and types [ or ] on some layouts.
+        if (
+          event.metaKey ||
+          (event.ctrlKey && !event.getModifierState('AltGraph'))
+        ) {
+          return;
+        }
         const shortcutSide =
           event.key === SIDEBAR_KEYBOARD_SHORTCUT_LEFT
             ? 'left'
@@ -369,6 +383,7 @@ const SidebarProvider = forwardRef<
                   className
                 )}
                 ref={ref}
+                data-sidebar-provider=""
                 {...props}
               >
                 {children}
@@ -384,38 +399,76 @@ SidebarProvider.displayName = 'SidebarProvider';
 
 const Sidebar = React.forwardRef<
   HTMLDivElement,
-  React.ComponentProps<'div'> & {
-    /**
-     * Which edge of the viewport the sidebar is attached to.
-     */
-    side?: 'left' | 'right';
-    /**
-     * Collapse behavior when the sidebar is toggled closed: slide fully out
-     * of view (`offcanvas`), collapse to a narrow icon strip (`icon`), or
-     * stay at full width (`none`).
-     */
-    collapsible?: 'offcanvas' | 'icon' | 'none';
-  }
+  React.ComponentProps<'div'> &
+    SidebarResizeProps & {
+      /**
+       * Which edge of the viewport the sidebar is attached to.
+       */
+      side?: 'left' | 'right';
+      /**
+       * Collapse behavior when the sidebar is toggled closed: slide fully out
+       * of view (`offcanvas`), collapse to a narrow icon strip (`icon`), or
+       * stay at full width (`none`).
+       */
+      collapsible?: 'offcanvas' | 'icon' | 'none';
+    }
 >(
   (
-    { side = 'left', collapsible = 'offcanvas', className, children, ...props },
+    {
+      side = 'left',
+      collapsible = 'offcanvas',
+      className,
+      children,
+      resizable,
+      defaultWidth,
+      minWidth,
+      maxWidth,
+      widthStorageKey,
+      ...props
+    },
     ref
   ) => {
     const { isMobile, state, openMobile, setOpenMobile } = useSidebar(side);
-    const sidebarWidth = side === 'right' ? SIDEBAR_RIGHT_WIDTH : SIDEBAR_WIDTH;
+    const rootRef = React.useRef<HTMLDivElement | null>(null);
+    const setRootRef = React.useCallback(
+      (node: HTMLDivElement | null) => {
+        rootRef.current = node;
+        if (typeof ref === 'function') ref(node);
+        else if (ref) ref.current = node;
+      },
+      [ref]
+    );
+    const resize = useSidebarResize({
+      resizable,
+      defaultWidth,
+      minWidth,
+      maxWidth,
+      widthStorageKey,
+      side,
+      isMobile,
+      expanded: state === 'expanded' || collapsible === 'none',
+      rootRef,
+    });
+    const sidebarWidth = resizable
+      ? `${resize.width}px`
+      : side === 'right'
+        ? SIDEBAR_RIGHT_WIDTH
+        : SIDEBAR_WIDTH;
 
     if (isMobile) {
       return (
         <SidebarSideContext.Provider value={side}>
-          <Drawer
-            isOpen={openMobile}
-            onDismiss={() => setOpenMobile(false)}
-            placement={side}
-          >
-            <Box data-sidebar="sidebar" data-mobile="true" height="100">
-              {children}
-            </Box>
-          </Drawer>
+          <SidebarResizeContext.Provider value={resize}>
+            <Drawer
+              isOpen={openMobile}
+              onDismiss={() => setOpenMobile(false)}
+              placement={side}
+            >
+              <Box data-sidebar="sidebar" data-mobile="true" height="100">
+                {children}
+              </Box>
+            </Drawer>
+          </SidebarResizeContext.Provider>
         </SidebarSideContext.Provider>
       );
     }
@@ -423,97 +476,106 @@ const Sidebar = React.forwardRef<
     if (collapsible === 'none') {
       return (
         <SidebarSideContext.Provider value={side}>
-          <div
-            className={classNames(
-              'group display-flex h-100 font-size-xs flex-direction-column background-color-secondary font-color-base',
-              className
-            )}
-            style={
-              {
-                '--sidebar-width': sidebarWidth,
-                width: 'var(--sidebar-width)',
-              } as React.CSSProperties
-            }
-            ref={ref}
-            {...props}
-          >
-            {children}
-          </div>
+          <SidebarResizeContext.Provider value={resize}>
+            <div
+              className={classNames(
+                'group display-flex h-100 font-size-xs flex-direction-column background-color-secondary font-color-base',
+                className
+              )}
+              style={
+                {
+                  '--sidebar-width': sidebarWidth,
+                  width: 'var(--sidebar-width)',
+                  ...(resizable ? { position: 'relative', flexShrink: 0 } : {}),
+                } as React.CSSProperties
+              }
+              ref={setRootRef}
+              {...props}
+            >
+              {children}
+            </div>
+          </SidebarResizeContext.Provider>
         </SidebarSideContext.Provider>
       );
     }
 
     return (
       <SidebarSideContext.Provider value={side}>
-        <Box
-          ref={ref}
-          background="primary"
-          display={{ base: 'none', desktop: 'block' }}
-          color="base"
-          fontSize="sm"
-          position="relative"
-          style={
-            {
-              '--sidebar-width': sidebarWidth,
-            } as React.CSSProperties
-          }
-          data-state={state}
-          data-collapsible={collapsible}
-          data-side={side}
-          className="group"
-        >
-          <div
-            style={{
-              animationTimingFunction:
-                'var(--sidebar-transition-timing, linear)',
-              transitionTimingFunction:
-                'var(--sidebar-transition-timing, linear)',
-              transitionDuration: 'var(--sidebar-transition-duration, 200ms)',
-              animationDuration: 'var(--sidebar-transition-duration, 200ms)',
-              transitionProperty: 'width',
-              width: getSidebarWidth(state, collapsible),
-              height: '100svh',
-            }}
-            className={classNames('position-relative', className)}
-          />
-          <div
-            className={classNames(
-              'position-absolute display-none display-flex-desktop ',
-              className
-            )}
-            style={{
-              ...getSidebarOffsetStyles(side, state, collapsible),
-              top: '0',
-              bottom: '0',
-              zIndex: 'var(--size-z-index-drawer)',
-              animationTimingFunction:
-                'var(--sidebar-transition-timing, linear)',
-              transitionTimingFunction:
-                'var(--sidebar-transition-timing, linear)',
-              transitionDuration: 'var(--sidebar-transition-duration, 200ms)',
-              animationDuration: 'var(--sidebar-transition-duration, 200ms)',
-              transitionProperty: 'left, right, width',
-              width:
-                state === 'collapsed' && collapsible === 'icon'
-                  ? 'var(--sidebar-width-icon)'
-                  : 'var(--sidebar-width)',
-              height: '100svh',
-            }}
-            {...props}
+        <SidebarResizeContext.Provider value={resize}>
+          <Box
+            ref={setRootRef}
+            background="primary"
+            display={{ base: 'none', desktop: 'block' }}
+            color="base"
+            fontSize="sm"
+            position="relative"
+            style={
+              {
+                '--sidebar-width': sidebarWidth,
+              } as React.CSSProperties
+            }
+            data-state={state}
+            data-collapsible={collapsible}
+            data-side={side}
+            className="group"
           >
             <div
-              data-sidebar="sidebar"
+              style={{
+                animationTimingFunction:
+                  'var(--sidebar-transition-timing, linear)',
+                transitionTimingFunction:
+                  'var(--sidebar-transition-timing, linear)',
+                transitionDuration: resize.animate
+                  ? 'var(--sidebar-transition-duration, 200ms)'
+                  : '0ms',
+                animationDuration: 'var(--sidebar-transition-duration, 200ms)',
+                transitionProperty: 'width',
+                width: getSidebarWidth(state, collapsible),
+                height: '100svh',
+              }}
+              className={classNames('position-relative', className)}
+            />
+            <div
               className={classNames(
-                'display-flex h-100 w-100 flex-direction-column background-color-secondary font-color-base',
-                {
-                  'p-right-lg-desktop': side === 'right',
-                }
+                'position-absolute display-none display-flex-desktop ',
+                className
               )}
+              style={{
+                ...getSidebarOffsetStyles(side, state, collapsible),
+                top: '0',
+                bottom: '0',
+                zIndex: 'var(--size-z-index-drawer)',
+                animationTimingFunction:
+                  'var(--sidebar-transition-timing, linear)',
+                transitionTimingFunction:
+                  'var(--sidebar-transition-timing, linear)',
+                transitionDuration: resize.animate
+                  ? 'var(--sidebar-transition-duration, 200ms)'
+                  : '0ms',
+                animationDuration: 'var(--sidebar-transition-duration, 200ms)',
+                transitionProperty: 'left, right, width',
+                width:
+                  state === 'collapsed' && collapsible === 'icon'
+                    ? 'var(--sidebar-width-icon)'
+                    : 'var(--sidebar-width)',
+                height: '100svh',
+              }}
+              {...props}
             >
-              {children}
+              <div
+                data-sidebar="sidebar"
+                className={classNames(
+                  'display-flex h-100 w-100 flex-direction-column background-color-secondary font-color-base',
+                  {
+                    'p-right-lg-desktop': side === 'right',
+                  }
+                )}
+              >
+                {children}
+              </div>
             </div>
-          </div>
-        </Box>
+          </Box>
+        </SidebarResizeContext.Provider>
       </SidebarSideContext.Provider>
     );
   }
@@ -860,6 +922,9 @@ const SidebarRail = React.forwardRef<
   React.ComponentProps<'button'>
 >(({ className, ...props }, ref) => {
   const { open, toggleSidebar, side } = useSidebar();
+  const resize = React.useContext(SidebarResizeContext);
+  // React.useId requires React 18; Radix's useId also supports 16.8 and 17.
+  const descriptionId = useId();
   const shortcutLabel =
     side === 'left'
       ? SIDEBAR_KEYBOARD_SHORTCUT_LEFT
@@ -870,64 +935,91 @@ const SidebarRail = React.forwardRef<
       ? 'caret-sm-right'
       : 'caret-sm-left'
     : side === 'right'
-    ? 'caret-sm-left'
-    : 'caret-sm-right';
+      ? 'caret-sm-left'
+      : 'caret-sm-right';
 
   return (
-    <button
-      ref={ref}
-      data-sidebar="rail"
-      aria-label="Toggle Sidebar"
-      tabIndex={-1}
-      onClick={toggleSidebar}
-      title={`Toggle Sidebar ${shortcutLabel}`}
-      className={classNames(
-        styles.rail,
-        'hover-show-child background-color-transparent display-flex p-top-5xl p-left-xl p-right-0 justify-content-center position-absolute',
-        {
-          'cursor-w-resize':
-            (open && side === 'left') || (!open && side === 'right'),
-          'cursor-e-resize':
-            (!open && side === 'left') || (open && side === 'right'),
-        },
-        className
-      )}
-      style={{
-        top: '20px',
-        bottom: '20px',
-        right: side === 'left' ? '-14px' : undefined,
-        left: side === 'right' ? '-18px' : undefined,
-        width: '10px',
-      }}
-      type="button"
-      {...props}
-    >
-      <Box
-        radius="xl"
-        background="primary"
-        color="secondary"
-        borderWidth="sm"
-        padding="xs"
-        margin="0"
-        shadow="xs"
-        width="3xl"
-        height="3xl"
-        alignItems="center"
-        justifyContent="center"
+    <>
+      <button
+        ref={ref}
+        data-sidebar="rail"
+        data-resizable={resize?.enabled || undefined}
+        aria-label={
+          resize?.enabled
+            ? `Resize or toggle ${side} sidebar`
+            : 'Toggle Sidebar'
+        }
+        aria-describedby={resize?.enabled ? descriptionId : undefined}
+        tabIndex={resize?.enabled ? 0 : -1}
+        {...(resize?.enabled ? resize.railProps : {})}
+        onClick={toggleSidebar}
+        title={
+          resize?.enabled
+            ? `Drag to resize; click to toggle (${shortcutLabel})`
+            : `Toggle Sidebar ${shortcutLabel}`
+        }
         className={classNames(
-          'hover-child',
+          styles.rail,
+          'hover-show-child background-color-transparent display-flex p-top-5xl p-left-xl p-right-0 justify-content-center position-absolute',
           {
             'cursor-w-resize':
-              (open && side === 'left') || (!open && side === 'right'),
+              !resize?.enabled &&
+              ((open && side === 'left') || (!open && side === 'right')),
             'cursor-e-resize':
-              (!open && side === 'left') || (open && side === 'right'),
+              !resize?.enabled &&
+              ((!open && side === 'left') || (open && side === 'right')),
           },
           className
         )}
+        style={{
+          top: '20px',
+          bottom: '20px',
+          right: side === 'left' ? '-14px' : undefined,
+          left: side === 'right' ? '-18px' : undefined,
+          width: '10px',
+          ...(resize?.enabled
+            ? { cursor: 'col-resize', touchAction: 'none' }
+            : {}),
+        }}
+        type="button"
+        {...props}
       >
-        <Icon name={caretIcon} />
-      </Box>
-    </button>
+        <Box
+          radius="xl"
+          background="primary"
+          color="secondary"
+          borderWidth="sm"
+          padding="xs"
+          margin="0"
+          shadow="xs"
+          width="3xl"
+          height="3xl"
+          alignItems="center"
+          justifyContent="center"
+          className={classNames(
+            'hover-child',
+            {
+              'cursor-w-resize':
+                !resize?.enabled &&
+              ((open && side === 'left') || (!open && side === 'right')),
+              'cursor-e-resize':
+                !resize?.enabled &&
+              ((!open && side === 'left') || (open && side === 'right')),
+            },
+            className
+          )}
+        >
+          <Icon name={caretIcon} />
+        </Box>
+      </button>
+      {resize?.enabled && (
+        <span id={descriptionId} className={styles.resizeDescription}>
+          Width {Math.round(resize.width)} pixels. Use left and right arrows to
+          resize, Home for minimum, End for maximum, and Enter or Space to
+          toggle.
+        </span>
+      )}
+    </>
   );
 });
 SidebarRail.displayName = 'SidebarRail';

package/src/components/Sidebar/useSidebarResize.ts

@@ -0,0 +1,214 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { useIsomorphicLayoutEffect } from '../../hooks/useIsomorphicLayoutEffect/useIsomorphicLayoutEffect';
+
+export 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;
+}
+
+export function useSidebarResize({
+  resizable = false,
+  defaultWidth,
+  minWidth = 256,
+  maxWidth = 960,
+  widthStorageKey,
+  side,
+  isMobile,
+  expanded,
+  rootRef,
+}: SidebarResizeProps & {
+  side: 'left' | 'right';
+  isMobile: boolean;
+  expanded: boolean;
+  rootRef: React.RefObject<HTMLDivElement>;
+}) {
+  const initialWidth = defaultWidth ?? (side === 'left' ? 256 : 384);
+  const [preferredWidth, setPreferredWidth] = useState(initialWidth);
+  const [containerWidth, setContainerWidth] = useState<number>(Infinity);
+  const [dragging, setDragging] = useState(false);
+  const gesture = useRef<{
+    id: number;
+    x: number;
+    width: number;
+    preferred: number;
+    moved: boolean;
+  } | null>(null);
+  const suppressClick = useRef(false);
+  const currentWidth = useRef(preferredWidth);
+  const enabled = resizable && !isMobile && expanded;
+  const maximum = Math.max(0, Math.min(maxWidth, containerWidth * (2 / 3)));
+  const minimum = Math.min(Math.max(0, minWidth), maximum);
+  const clamp = (value: number) => Math.max(minimum, Math.min(maximum, value));
+  const width = clamp(preferredWidth);
+  const [settledWidth, setSettledWidth] = useState(width);
+
+  // Restore and measure before paint so the first frame uses the saved width.
+  useIsomorphicLayoutEffect(() => {
+    if (!resizable) return;
+    let savedWidth = initialWidth;
+    try {
+      const saved = widthStorageKey && localStorage.getItem(widthStorageKey);
+      if (saved && Number.isFinite(Number(saved)) && Number(saved) > 0) {
+        savedWidth = Number(saved);
+      }
+    } catch {
+      // Resizing still works when browser storage is unavailable.
+    }
+    setPreferredWidth(savedWidth);
+  }, [resizable, initialWidth, widthStorageKey]);
+
+  useIsomorphicLayoutEffect(() => {
+    if (!resizable || isMobile) return;
+    const container = rootRef.current?.closest('[data-sidebar-provider]');
+    if (!container) return;
+    const measure = () =>
+      setContainerWidth(container.getBoundingClientRect().width);
+    measure();
+    if (typeof ResizeObserver === 'undefined') {
+      window.addEventListener('resize', measure);
+      return () => window.removeEventListener('resize', measure);
+    }
+    const observer = new ResizeObserver(measure);
+    observer.observe(container);
+    return () => observer.disconnect();
+  }, [resizable, isMobile, rootRef]);
+
+  // Only expanding and collapsing animate. A width change (restore, container
+  // cap, keyboard, drag release) is committed with transitions off; flushing
+  // styles at that width lets the next render turn them back on without the
+  // browser animating from the old width.
+  useIsomorphicLayoutEffect(() => {
+    if (dragging || width === settledWidth) return;
+    rootRef.current?.getBoundingClientRect();
+    setSettledWidth(width);
+  }, [dragging, width, settledWidth, rootRef]);
+
+  useEffect(() => {
+    if (!enabled) {
+      gesture.current = null;
+      setDragging(false);
+    }
+  }, [enabled]);
+
+  useEffect(() => {
+    if (!dragging) return;
+    const { cursor, userSelect } = document.body.style;
+    document.body.style.cursor = 'col-resize';
+    document.body.style.userSelect = 'none';
+    return () => {
+      document.body.style.cursor = cursor;
+      document.body.style.userSelect = userSelect;
+    };
+  }, [dragging]);
+
+  const update = (next: number) => {
+    currentWidth.current = clamp(next);
+    setPreferredWidth(currentWidth.current);
+  };
+  const persist = () => {
+    if (!widthStorageKey) return;
+    try {
+      localStorage.setItem(widthStorageKey, String(currentWidth.current));
+    } catch {
+      // A storage failure must not interrupt the interaction.
+    }
+  };
+  const cancel = () => {
+    if (!gesture.current) return;
+    setPreferredWidth(gesture.current.preferred);
+    gesture.current = null;
+    setDragging(false);
+  };
+
+  const railProps: React.ComponentProps<'button'> = {
+    onPointerDown: (event) => {
+      suppressClick.current = false;
+      if (!enabled || event.button !== 0 || gesture.current) return;
+      gesture.current = {
+        id: event.pointerId,
+        x: event.clientX,
+        width,
+        preferred: preferredWidth,
+        moved: false,
+      };
+      event.currentTarget.setPointerCapture(event.pointerId);
+    },
+    onPointerMove: (event) => {
+      const start = gesture.current;
+      if (!start || start.id !== event.pointerId) return;
+      const delta = event.clientX - start.x;
+      if (!start.moved && Math.abs(delta) < 4) return;
+      start.moved = true;
+      suppressClick.current = true;
+      setDragging(true);
+      update(start.width + (side === 'left' ? delta : -delta));
+    },
+    onPointerUp: (event) => {
+      const start = gesture.current;
+      if (!start || start.id !== event.pointerId) return;
+      if (start.moved) {
+        update(
+          start.width + (side === 'left' ? 1 : -1) * (event.clientX - start.x)
+        );
+        persist();
+      }
+      gesture.current = null;
+      setDragging(false);
+      event.currentTarget.releasePointerCapture(event.pointerId);
+    },
+    onPointerCancel: cancel,
+    onLostPointerCapture: cancel,
+    onClickCapture: (event) => {
+      if (suppressClick.current && event.detail !== 0) {
+        event.preventDefault();
+        event.stopPropagation();
+        suppressClick.current = false;
+      }
+    },
+    onKeyDown: (event) => {
+      // Leave modified keys to the browser, e.g. Cmd/Alt+Arrow for history.
+      const modified =
+        event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
+      if (!enabled || modified) return;
+      let next: number;
+      switch (event.key) {
+        case 'ArrowLeft':
+          next = width + (side === 'left' ? -10 : 10);
+          break;
+        case 'ArrowRight':
+          next = width + (side === 'left' ? 10 : -10);
+          break;
+        case 'Home':
+          next = minimum;
+          break;
+        case 'End':
+          next = maximum;
+          break;
+        default:
+          return;
+      }
+      event.preventDefault();
+      update(next);
+      persist();
+    },
+  };
+
+  return {
+    width,
+    animate: !dragging && width === settledWidth,
+    enabled,
+    railProps,
+  };
+}
+
+export const SidebarResizeContext = React.createContext<ReturnType<
+  typeof useSidebarResize
+> | null>(null);