feat: add enterDelayMs-type prop to delay displaying SideNav component

packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap

@@ -6536,6 +6536,9 @@ Map {
       "defaultExpanded": Object {
         "type": "bool",
       },
+      "enterDelayMs": Object {
+        "type": "number",
+      },
       "expanded": Object {
         "type": "bool",
       },

packages/react/src/components/UIShell/SideNav.tsx

@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React, {
-  useState,
   useRef,
   type ForwardedRef,
   type ComponentProps,
@@ -22,6 +21,7 @@ import { usePrefix } from '../../internal/usePrefix';
 import { keys, match } from '../../internal/keyboard';
 import { useMergedRefs } from '../../internal/useMergedRefs';
 import { useWindowEvent } from '../../internal/useEvent';
+import { useDelayedState } from '../../internal/useDelayedState';
 // TO-DO: comment back in when footer is added for rails
 // import SideNavFooter from './SideNavFooter';
 
@@ -43,6 +43,7 @@ interface SideNavProps extends ComponentProps<'nav'> {
   addMouseListeners?: boolean | undefined;
   onOverlayClick?: MouseEventHandler<HTMLDivElement> | undefined;
   onSideNavBlur?: () => void | undefined;
+  enterDelayMs?: number;
 }
 
 function SideNavRenderFunction(
@@ -65,28 +66,29 @@ function SideNavRenderFunction(
     addMouseListeners = true,
     onOverlayClick,
     onSideNavBlur,
+    enterDelayMs = 100,
     ...other
   }: SideNavProps,
   ref: ForwardedRef<HTMLElement>
 ) {
   const prefix = usePrefix();
   const { current: controlled } = useRef(expandedProp !== undefined);
-  const [expandedState, setExpandedState] = useState(defaultExpanded);
+  const [expandedState, setExpandedState] = useDelayedState(defaultExpanded);
   const [expandedViaHoverState, setExpandedViaHoverState] =
-    useState(defaultExpanded);
+    useDelayedState(defaultExpanded);
   const expanded = controlled ? expandedProp : expandedState;
   const sideNavRef = useRef<HTMLDivElement>(null);
   const navRef = useMergedRefs([sideNavRef, ref]);
 
   const handleToggle: typeof onToggle = (event, value = !expanded) => {
     if (!controlled) {
-      setExpandedState(value);
+      setExpandedState(value, enterDelayMs);
     }
     if (onToggle) {
       onToggle(event, value);
     }
     if (controlled || isRail) {
-      setExpandedViaHoverState(value);
+      setExpandedViaHoverState(value, enterDelayMs);
     }
   };
 
@@ -143,7 +145,12 @@ function SideNavRenderFunction(
   const eventHandlers: Partial<
     Pick<
       ComponentProps<'nav'>,
-      'onFocus' | 'onBlur' | 'onKeyDown' | 'onMouseEnter' | 'onMouseLeave'
+      | 'onFocus'
+      | 'onBlur'
+      | 'onKeyDown'
+      | 'onMouseEnter'
+      | 'onMouseLeave'
+      | 'onClick'
     >
   > = {};
 
@@ -174,8 +181,20 @@ function SideNavRenderFunction(
   }
 
   if (addMouseListeners && isRail) {
-    eventHandlers.onMouseEnter = () => handleToggle(true, true);
-    eventHandlers.onMouseLeave = () => handleToggle(false, false);
+    eventHandlers.onMouseEnter = () => {
+      handleToggle(true, true);
+    };
+    eventHandlers.onMouseLeave = () => {
+      setExpandedState(false);
+      setExpandedViaHoverState(false);
+      handleToggle(false, false);
+    };
+    eventHandlers.onClick = () => {
+      //if delay is enabled, and user intentionally clicks it to see it expanded immediately
+      setExpandedState(true);
+      setExpandedViaHoverState(true);
+      handleToggle(true, true);
+    };
   }
 
   useWindowEvent('keydown', (event: Event) => {
@@ -242,6 +261,11 @@ SideNav.propTypes = {
    */
   defaultExpanded: PropTypes.bool,
 
+  /**
+   * Specify the duration in milliseconds to delay before displaying the sidenavigation
+   */
+  enterDelayMs: PropTypes.number,
+
   /**
    * If `true`, the SideNav will be expanded, otherwise it will be collapsed.
    * Using this prop causes SideNav to become a controled component.

packages/react/src/components/UIShell/UIShell.stories.js

@@ -160,6 +160,9 @@ export default {
     docs: {
       page: mdx,
     },
+    controls: {
+      hideNoControlsWarning: true,
+    },
   },
   argTypes: {
     className: {
@@ -1019,4 +1022,76 @@ export const SideNavWLargeSideNavItems = () => (
   </>
 );
 
+const UIShellPlayground = (props) => {
+  const { isRail, enterDelayMs } = props;
+  return (
+    <SideNav
+      aria-label="Side navigation"
+      href="#main-content"
+      isRail={isRail}
+      enterDelayMs={enterDelayMs}>
+      <SideNavItems>
+        <SideNavMenu renderIcon={Fade} title="Category title">
+          <SideNavMenuItem href="https://www.carbondesignsystem.com/">
+            Link
+          </SideNavMenuItem>
+          <SideNavMenuItem
+            aria-current="page"
+            href="https://www.carbondesignsystem.com/">
+            Link
+          </SideNavMenuItem>
+          <SideNavMenuItem href="https://www.carbondesignsystem.com/">
+            Link
+          </SideNavMenuItem>
+        </SideNavMenu>
+        <SideNavMenu renderIcon={Fade} title="Category title">
+          <SideNavMenuItem href="https://www.carbondesignsystem.com/">
+            Link
+          </SideNavMenuItem>
+          <SideNavMenuItem href="https://www.carbondesignsystem.com/">
+            Link
+          </SideNavMenuItem>
+          <SideNavMenuItem href="https://www.carbondesignsystem.com/">
+            Link
+          </SideNavMenuItem>
+        </SideNavMenu>
+        <SideNavMenu renderIcon={Fade} title="Category title">
+          <SideNavMenuItem href="https://www.carbondesignsystem.com/">
+            Link
+          </SideNavMenuItem>
+          <SideNavMenuItem href="https://www.carbondesignsystem.com/">
+            Link
+          </SideNavMenuItem>
+          <SideNavMenuItem href="https://www.carbondesignsystem.com/">
+            Link
+          </SideNavMenuItem>
+        </SideNavMenu>
+        <SideNavLink
+          renderIcon={Fade}
+          href="https://www.carbondesignsystem.com/">
+          Link
+        </SideNavLink>
+        <SideNavLink
+          renderIcon={Fade}
+          href="https://www.carbondesignsystem.com/">
+          Link
+        </SideNavLink>
+      </SideNavItems>
+    </SideNav>
+  );
+};
+export const Playground = UIShellPlayground.bind({});
+Playground.argTypes = {
+  isRail: {
+    defaultValue: true,
+    control: {
+      type: 'boolean',
+    },
+  },
+  enterDelayMs: {
+    control: {
+      type: 'number',
+    },
+  },
+};
 SideNavWLargeSideNavItems.storyName = 'SideNav w/ large side nav items';

packages/styles/scss/components/ui-shell/side-nav/_side-nav.scss

@@ -68,9 +68,6 @@
     width: 0;
   }
 
-  .#{$prefix}--side-nav.#{$prefix}--side-nav--rail:not(
-      .#{$prefix}--side-nav--fixed
-    ):hover,
   .#{$prefix}--side-nav--expanded {
     width: mini-units(32);
   }