@atlaskit/navigation-system 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @atlassian/navigation-system
 
+## 4.4.0
+
+### Minor Changes
+
+- [`327d6a06eebb2`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/327d6a06eebb2) -
+  Adds `onPeekStart` and `onPeekEnd` callbacks to the `SideNav` to use for monitoring when users
+  peek at the side navigation when it is collapsed.
+
 ## 4.3.0
 
 ### Minor Changes

package/dist/cjs/ui/page-layout/side-nav/side-nav.js

@@ -7,6 +7,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.SideNav = SideNav;
+exports.onPeekStartDelayMs = void 0;
 require("./side-nav.compiled.css");
 var _react = _interopRequireWildcard(require("react"));
 var React = _react;
@@ -17,6 +18,7 @@ var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/sli
 var _bindEventListener = require("bind-event-listener");
 var _reactDom = require("react-dom");
 var _mergeRefs = _interopRequireDefault(require("@atlaskit/ds-lib/merge-refs"));
+var _useStableRef = _interopRequireDefault(require("@atlaskit/ds-lib/use-stable-ref"));
 var _openLayerObserver = require("@atlaskit/layering/experimental/open-layer-observer");
 var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
 var _adapter = require("@atlaskit/pragmatic-drag-and-drop/element/adapter");
@@ -77,6 +79,7 @@ var styles = {
   fullHeightSidebar: "_165t56xv _180k1wjm _26vxoned _1mt19dtb"
 };
 var fallbackDefaultWidth = 320;
+var onPeekStartDelayMs = exports.onPeekStartDelayMs = 500;
 
 /**
  * We need an additional component layer so we can wrap the side nav in a `OpenLayerObserver` and have access to the
@@ -95,6 +98,8 @@ function SideNavInternal(_ref) {
     skipLinkLabel = _ref$skipLinkLabel === void 0 ? label : _ref$skipLinkLabel,
     onExpand = _ref.onExpand,
     onCollapse = _ref.onCollapse,
+    onPeekStart = _ref.onPeekStart,
+    onPeekEnd = _ref.onPeekEnd,
     providedId = _ref.id;
   var id = (0, _idUtils.useLayoutId)({
     providedId: providedId
@@ -161,6 +166,16 @@ function SideNavInternal(_ref) {
     type: 'not-active'
   });
   var isFlyoutVisible = (sideNavState === null || sideNavState === void 0 ? void 0 : sideNavState.flyout) === 'open';
+  var isExpandedOnDesktopRef = (0, _useStableRef.default)(isExpandedOnDesktop);
+  var hasPeekStartedRef = (0, _react.useRef)(false);
+  var onPeekStartRef = (0, _useStableRef.default)(onPeekStart);
+  var onPeekEndRef = (0, _useStableRef.default)(onPeekEnd);
+  var onPeekStartTimeoutIdRef = (0, _react.useRef)(undefined);
+  (0, _react.useEffect)(function () {
+    return function () {
+      clearTimeout(onPeekStartTimeoutIdRef.current);
+    };
+  }, []);
   var updateFlyoutState = (0, _react.useMemo)(function () {
     function tryAbortPendingClose() {
       if (flyoutStateRef.current.type === 'waiting-for-close') {
@@ -168,6 +183,7 @@ function SideNavInternal(_ref) {
       }
     }
     function open() {
+      var prevFlyoutState = flyoutStateRef.current;
       tryAbortPendingClose();
       flyoutStateRef.current = {
         type: 'open'
@@ -180,8 +196,24 @@ function SideNavInternal(_ref) {
         }
         return currentState;
       });
+
+      // Avoid redundant calls to `onPeekStart()`
+      if (prevFlyoutState.type === 'not-active') {
+        clearTimeout(onPeekStartTimeoutIdRef.current);
+        onPeekStartTimeoutIdRef.current = setTimeout(function () {
+          var _onPeekStartRef$curre;
+          // If the flyout isn't still open after ~500ms then we won't count the peek
+          // As we want to track user intention rather than all hovers
+          if (isExpandedOnDesktopRef.current || flyoutStateRef.current.type !== 'open') {
+            return;
+          }
+          hasPeekStartedRef.current = true;
+          (_onPeekStartRef$curre = onPeekStartRef.current) === null || _onPeekStartRef$curre === void 0 || _onPeekStartRef$curre.call(onPeekStartRef);
+        }, onPeekStartDelayMs);
+      }
     }
     function close() {
+      var prevFlyoutState = flyoutStateRef.current;
       tryAbortPendingClose();
       flyoutStateRef.current = {
         type: 'not-active'
@@ -194,6 +226,15 @@ function SideNavInternal(_ref) {
         }
         return currentState;
       });
+
+      // Avoid redundant calls to `onPeekEnd()`
+      if (prevFlyoutState.type !== 'not-active' && hasPeekStartedRef.current) {
+        var _onPeekEndRef$current;
+        hasPeekStartedRef.current = false;
+        (_onPeekEndRef$current = onPeekEndRef.current) === null || _onPeekEndRef$current === void 0 || _onPeekEndRef$current.call(onPeekEndRef, {
+          trigger: isExpandedOnDesktopRef.current ? 'side-nav-expand' : 'mouse-leave'
+        });
+      }
     }
     return function onAction(action) {
       if (action === 'drag-from-flyout-started') {
@@ -252,7 +293,7 @@ function SideNavInternal(_ref) {
         return;
       }
     };
-  }, [openLayerObserver, setSideNavState]);
+  }, [isExpandedOnDesktopRef, onPeekEndRef, onPeekStartRef, openLayerObserver, setSideNavState]);
   var toggleVisibilityByScreenResize = (0, _useToggleSideNav.useToggleSideNav)({
     trigger: 'screen-resize'
   });
@@ -703,6 +744,8 @@ function SideNav(_ref8) {
     skipLinkLabel = _ref8$skipLinkLabel === void 0 ? label : _ref8$skipLinkLabel,
     onExpand = _ref8.onExpand,
     onCollapse = _ref8.onCollapse,
+    onPeekStart = _ref8.onPeekStart,
+    onPeekEnd = _ref8.onPeekEnd,
     id = _ref8.id;
   return /*#__PURE__*/React.createElement(_openLayerObserver.OpenLayerObserverNamespaceProvider, {
     namespace: openLayerObserverSideNavNamespace
@@ -714,6 +757,8 @@ function SideNav(_ref8) {
     skipLinkLabel: skipLinkLabel,
     onExpand: onExpand,
     onCollapse: onCollapse,
+    onPeekStart: onPeekStart,
+    onPeekEnd: onPeekEnd,
     id: id
   }, children));
 }

package/dist/es2019/ui/page-layout/side-nav/side-nav.js

@@ -7,6 +7,7 @@ import { useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, u
 import { bind } from 'bind-event-listener';
 import { flushSync } from 'react-dom';
 import mergeRefs from '@atlaskit/ds-lib/merge-refs';
+import useStableRef from '@atlaskit/ds-lib/use-stable-ref';
 import { OpenLayerObserverNamespaceProvider, useOpenLayerObserver } from '@atlaskit/layering/experimental/open-layer-observer';
 import { fg } from '@atlaskit/platform-feature-flags';
 import { monitorForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
@@ -64,6 +65,7 @@ const styles = {
   fullHeightSidebar: "_165t56xv _180k1wjm _26vxoned _1mt19dtb"
 };
 const fallbackDefaultWidth = 320;
+export const onPeekStartDelayMs = 500;
 
 /**
  * We need an additional component layer so we can wrap the side nav in a `OpenLayerObserver` and have access to the
@@ -78,6 +80,8 @@ function SideNavInternal({
   skipLinkLabel = label,
   onExpand,
   onCollapse,
+  onPeekStart,
+  onPeekEnd,
   id: providedId
 }) {
   var _sideNavState$lastTri;
@@ -142,6 +146,16 @@ function SideNavInternal({
     type: 'not-active'
   });
   const isFlyoutVisible = (sideNavState === null || sideNavState === void 0 ? void 0 : sideNavState.flyout) === 'open';
+  const isExpandedOnDesktopRef = useStableRef(isExpandedOnDesktop);
+  const hasPeekStartedRef = useRef(false);
+  const onPeekStartRef = useStableRef(onPeekStart);
+  const onPeekEndRef = useStableRef(onPeekEnd);
+  const onPeekStartTimeoutIdRef = useRef(undefined);
+  useEffect(() => {
+    return () => {
+      clearTimeout(onPeekStartTimeoutIdRef.current);
+    };
+  }, []);
   const updateFlyoutState = useMemo(() => {
     function tryAbortPendingClose() {
       if (flyoutStateRef.current.type === 'waiting-for-close') {
@@ -149,6 +163,7 @@ function SideNavInternal({
       }
     }
     function open() {
+      const prevFlyoutState = flyoutStateRef.current;
       tryAbortPendingClose();
       flyoutStateRef.current = {
         type: 'open'
@@ -162,8 +177,24 @@ function SideNavInternal({
         }
         return currentState;
       });
+
+      // Avoid redundant calls to `onPeekStart()`
+      if (prevFlyoutState.type === 'not-active') {
+        clearTimeout(onPeekStartTimeoutIdRef.current);
+        onPeekStartTimeoutIdRef.current = setTimeout(() => {
+          var _onPeekStartRef$curre;
+          // If the flyout isn't still open after ~500ms then we won't count the peek
+          // As we want to track user intention rather than all hovers
+          if (isExpandedOnDesktopRef.current || flyoutStateRef.current.type !== 'open') {
+            return;
+          }
+          hasPeekStartedRef.current = true;
+          (_onPeekStartRef$curre = onPeekStartRef.current) === null || _onPeekStartRef$curre === void 0 ? void 0 : _onPeekStartRef$curre.call(onPeekStartRef);
+        }, onPeekStartDelayMs);
+      }
     }
     function close() {
+      const prevFlyoutState = flyoutStateRef.current;
       tryAbortPendingClose();
       flyoutStateRef.current = {
         type: 'not-active'
@@ -177,6 +208,15 @@ function SideNavInternal({
         }
         return currentState;
       });
+
+      // Avoid redundant calls to `onPeekEnd()`
+      if (prevFlyoutState.type !== 'not-active' && hasPeekStartedRef.current) {
+        var _onPeekEndRef$current;
+        hasPeekStartedRef.current = false;
+        (_onPeekEndRef$current = onPeekEndRef.current) === null || _onPeekEndRef$current === void 0 ? void 0 : _onPeekEndRef$current.call(onPeekEndRef, {
+          trigger: isExpandedOnDesktopRef.current ? 'side-nav-expand' : 'mouse-leave'
+        });
+      }
     }
     return function onAction(action) {
       if (action === 'drag-from-flyout-started') {
@@ -235,7 +275,7 @@ function SideNavInternal({
         return;
       }
     };
-  }, [openLayerObserver, setSideNavState]);
+  }, [isExpandedOnDesktopRef, onPeekEndRef, onPeekStartRef, openLayerObserver, setSideNavState]);
   const toggleVisibilityByScreenResize = useToggleSideNav({
     trigger: 'screen-resize'
   });
@@ -695,6 +735,8 @@ export function SideNav({
   // Default value is defined in `SideNavInternal`
   onExpand,
   onCollapse,
+  onPeekStart,
+  onPeekEnd,
   id
 }) {
   return /*#__PURE__*/React.createElement(OpenLayerObserverNamespaceProvider, {
@@ -707,6 +749,8 @@ export function SideNav({
     skipLinkLabel: skipLinkLabel,
     onExpand: onExpand,
     onCollapse: onCollapse,
+    onPeekStart: onPeekStart,
+    onPeekEnd: onPeekEnd,
     id: id
   }, children));
 }

package/dist/esm/ui/page-layout/side-nav/side-nav.js

@@ -11,6 +11,7 @@ import { useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, u
 import { bind } from 'bind-event-listener';
 import { flushSync } from 'react-dom';
 import mergeRefs from '@atlaskit/ds-lib/merge-refs';
+import useStableRef from '@atlaskit/ds-lib/use-stable-ref';
 import { OpenLayerObserverNamespaceProvider, useOpenLayerObserver } from '@atlaskit/layering/experimental/open-layer-observer';
 import { fg } from '@atlaskit/platform-feature-flags';
 import { monitorForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
@@ -68,6 +69,7 @@ var styles = {
   fullHeightSidebar: "_165t56xv _180k1wjm _26vxoned _1mt19dtb"
 };
 var fallbackDefaultWidth = 320;
+export var onPeekStartDelayMs = 500;
 
 /**
  * We need an additional component layer so we can wrap the side nav in a `OpenLayerObserver` and have access to the
@@ -86,6 +88,8 @@ function SideNavInternal(_ref) {
     skipLinkLabel = _ref$skipLinkLabel === void 0 ? label : _ref$skipLinkLabel,
     onExpand = _ref.onExpand,
     onCollapse = _ref.onCollapse,
+    onPeekStart = _ref.onPeekStart,
+    onPeekEnd = _ref.onPeekEnd,
     providedId = _ref.id;
   var id = useLayoutId({
     providedId: providedId
@@ -152,6 +156,16 @@ function SideNavInternal(_ref) {
     type: 'not-active'
   });
   var isFlyoutVisible = (sideNavState === null || sideNavState === void 0 ? void 0 : sideNavState.flyout) === 'open';
+  var isExpandedOnDesktopRef = useStableRef(isExpandedOnDesktop);
+  var hasPeekStartedRef = useRef(false);
+  var onPeekStartRef = useStableRef(onPeekStart);
+  var onPeekEndRef = useStableRef(onPeekEnd);
+  var onPeekStartTimeoutIdRef = useRef(undefined);
+  useEffect(function () {
+    return function () {
+      clearTimeout(onPeekStartTimeoutIdRef.current);
+    };
+  }, []);
   var updateFlyoutState = useMemo(function () {
     function tryAbortPendingClose() {
       if (flyoutStateRef.current.type === 'waiting-for-close') {
@@ -159,6 +173,7 @@ function SideNavInternal(_ref) {
       }
     }
     function open() {
+      var prevFlyoutState = flyoutStateRef.current;
       tryAbortPendingClose();
       flyoutStateRef.current = {
         type: 'open'
@@ -171,8 +186,24 @@ function SideNavInternal(_ref) {
         }
         return currentState;
       });
+
+      // Avoid redundant calls to `onPeekStart()`
+      if (prevFlyoutState.type === 'not-active') {
+        clearTimeout(onPeekStartTimeoutIdRef.current);
+        onPeekStartTimeoutIdRef.current = setTimeout(function () {
+          var _onPeekStartRef$curre;
+          // If the flyout isn't still open after ~500ms then we won't count the peek
+          // As we want to track user intention rather than all hovers
+          if (isExpandedOnDesktopRef.current || flyoutStateRef.current.type !== 'open') {
+            return;
+          }
+          hasPeekStartedRef.current = true;
+          (_onPeekStartRef$curre = onPeekStartRef.current) === null || _onPeekStartRef$curre === void 0 || _onPeekStartRef$curre.call(onPeekStartRef);
+        }, onPeekStartDelayMs);
+      }
     }
     function close() {
+      var prevFlyoutState = flyoutStateRef.current;
       tryAbortPendingClose();
       flyoutStateRef.current = {
         type: 'not-active'
@@ -185,6 +216,15 @@ function SideNavInternal(_ref) {
         }
         return currentState;
       });
+
+      // Avoid redundant calls to `onPeekEnd()`
+      if (prevFlyoutState.type !== 'not-active' && hasPeekStartedRef.current) {
+        var _onPeekEndRef$current;
+        hasPeekStartedRef.current = false;
+        (_onPeekEndRef$current = onPeekEndRef.current) === null || _onPeekEndRef$current === void 0 || _onPeekEndRef$current.call(onPeekEndRef, {
+          trigger: isExpandedOnDesktopRef.current ? 'side-nav-expand' : 'mouse-leave'
+        });
+      }
     }
     return function onAction(action) {
       if (action === 'drag-from-flyout-started') {
@@ -243,7 +283,7 @@ function SideNavInternal(_ref) {
         return;
       }
     };
-  }, [openLayerObserver, setSideNavState]);
+  }, [isExpandedOnDesktopRef, onPeekEndRef, onPeekStartRef, openLayerObserver, setSideNavState]);
   var toggleVisibilityByScreenResize = useToggleSideNav({
     trigger: 'screen-resize'
   });
@@ -694,6 +734,8 @@ export function SideNav(_ref8) {
     skipLinkLabel = _ref8$skipLinkLabel === void 0 ? label : _ref8$skipLinkLabel,
     onExpand = _ref8.onExpand,
     onCollapse = _ref8.onCollapse,
+    onPeekStart = _ref8.onPeekStart,
+    onPeekEnd = _ref8.onPeekEnd,
     id = _ref8.id;
   return /*#__PURE__*/React.createElement(OpenLayerObserverNamespaceProvider, {
     namespace: openLayerObserverSideNavNamespace
@@ -705,6 +747,8 @@ export function SideNav(_ref8) {
     skipLinkLabel: skipLinkLabel,
     onExpand: onExpand,
     onCollapse: onCollapse,
+    onPeekStart: onPeekStart,
+    onPeekEnd: onPeekEnd,
     id: id
   }, children));
 }

package/dist/types/ui/page-layout/side-nav/side-nav.d.ts

@@ -53,7 +53,18 @@ type SideNavProps = CommonSlotProps & {
      * Note: The trigger parameter is only provided when the `navx-full-height-sidebar` feature flag is enabled.
      */
     onCollapse?: VisibilityCallback;
+    /**
+     * Called when the side nav begins peeking / flyout.
+     */
+    onPeekStart?: () => void;
+    /**
+     * Called when the side nav stops peeking / flyout.
+     */
+    onPeekEnd?: (args: {
+        trigger: 'mouse-leave' | 'side-nav-expand';
+    }) => void;
 };
+export declare const onPeekStartDelayMs = 500;
 /**
  * The side navigation layout area. It will show on the left (inline start) of the screen.
  *
@@ -64,5 +75,5 @@ type SideNavProps = CommonSlotProps & {
  */
 export declare function SideNav({ children, defaultCollapsed, defaultWidth, testId, label, // Default value is defined in `SideNavInternal`
 skipLinkLabel, // Default value is defined in `SideNavInternal`
-onExpand, onCollapse, id, }: SideNavProps): JSX.Element;
+onExpand, onCollapse, onPeekStart, onPeekEnd, id, }: SideNavProps): JSX.Element;
 export {};

package/dist/types-ts4.5/ui/page-layout/side-nav/side-nav.d.ts

@@ -53,7 +53,18 @@ type SideNavProps = CommonSlotProps & {
      * Note: The trigger parameter is only provided when the `navx-full-height-sidebar` feature flag is enabled.
      */
     onCollapse?: VisibilityCallback;
+    /**
+     * Called when the side nav begins peeking / flyout.
+     */
+    onPeekStart?: () => void;
+    /**
+     * Called when the side nav stops peeking / flyout.
+     */
+    onPeekEnd?: (args: {
+        trigger: 'mouse-leave' | 'side-nav-expand';
+    }) => void;
 };
+export declare const onPeekStartDelayMs = 500;
 /**
  * The side navigation layout area. It will show on the left (inline start) of the screen.
  *
@@ -64,5 +75,5 @@ type SideNavProps = CommonSlotProps & {
  */
 export declare function SideNav({ children, defaultCollapsed, defaultWidth, testId, label, // Default value is defined in `SideNavInternal`
 skipLinkLabel, // Default value is defined in `SideNavInternal`
-onExpand, onCollapse, id, }: SideNavProps): JSX.Element;
+onExpand, onCollapse, onPeekStart, onPeekEnd, id, }: SideNavProps): JSX.Element;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/navigation-system",
-	"version": "4.3.0",
+	"version": "4.4.0",
 	"description": "The latest navigation system for Atlassian apps.",
 	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-mirror",
 	"author": "Atlassian Pty Ltd",