@atlaskit/navigation-system 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @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
+
+- [`4bb7b31bfda3b`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/4bb7b31bfda3b) -
+  Refactors changes that were previously behind `platform_dst_nav4_full_height_sidebar_api_changes`
+  to now be behind `platform_dst_nav4_side_nav_default_collapsed_api`. After rollout, both the new
+  and legacy APIs for defining side nav initial state will be supported.
+
 ## 4.2.0
 
 ### Minor Changes

package/dist/cjs/ui/page-layout/root.js

@@ -36,8 +36,7 @@ function Root(_ref) {
     _ref$skipLinksLabel = _ref.skipLinksLabel,
     skipLinksLabel = _ref$skipLinksLabel === void 0 ? 'Skip to:' : _ref$skipLinksLabel,
     testId = _ref.testId,
-    _ref$defaultSideNavCo = _ref.defaultSideNavCollapsed,
-    defaultSideNavCollapsed = _ref$defaultSideNavCo === void 0 ? false : _ref$defaultSideNavCo;
+    defaultSideNavCollapsed = _ref.defaultSideNavCollapsed;
   var ref = (0, _react.useRef)(null);
   (0, _react.useEffect)(function () {
     if (process.env.NODE_ENV !== 'production') {

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'
   });
@@ -260,8 +301,8 @@ function SideNavInternal(_ref) {
     trigger: 'click-outside-on-mobile'
   });
   (0, _react.useEffect)(function () {
-    if ((0, _platformFeatureFlags.fg)('platform_dst_nav4_full_height_sidebar_api_changes')) {
-      // We are passing initial state to the Root now, so no initial sync is required
+    if ((0, _platformFeatureFlags.fg)('platform_dst_nav4_side_nav_default_collapsed_api')) {
+      // This is the old version of the hook, so we skip it when the flag is enabled
       return;
     }
 
@@ -274,6 +315,28 @@ function SideNavInternal(_ref) {
       lastTrigger: null
     });
   }, [initialDefaultCollapsed, setSideNavState]);
+
+  // Moving to `useLayoutEffect` so that there's no visual shift in non-SSR environments when using legacy API
+  // For SSR the new API is still necessary
+  (0, _react.useLayoutEffect)(function () {
+    if (!(0, _platformFeatureFlags.fg)('platform_dst_nav4_side_nav_default_collapsed_api')) {
+      // This is the new version of the hook, so we skip it when the flag is disabled
+      return;
+    }
+    if (sideNavState !== null) {
+      // Only need to do an initial sync if it hasn't been initialized from Root
+      return;
+    }
+
+    // Sync the visibility in context (provided in `<Root>`) with the local `defaultCollapsed` prop provided to `SideNav`
+    // after SSR hydration. This should only run once, after the initial render on the client.
+    setSideNavState({
+      desktop: initialDefaultCollapsed ? 'collapsed' : 'expanded',
+      mobile: 'collapsed',
+      flyout: 'closed',
+      lastTrigger: null
+    });
+  }, [initialDefaultCollapsed, setSideNavState, sideNavState]);
   var handleExpand = (0, _react.useCallback)(function (_ref2) {
     var screen = _ref2.screen,
       trigger = _ref2.trigger;
@@ -681,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
@@ -692,6 +757,8 @@ function SideNav(_ref8) {
     skipLinkLabel: skipLinkLabel,
     onExpand: onExpand,
     onCollapse: onCollapse,
+    onPeekStart: onPeekStart,
+    onPeekEnd: onPeekEnd,
     id: id
   }, children));
 }

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

@@ -20,6 +20,7 @@ var _migration = require("../../top-nav-items/themed/migration");
 var _toggleButtonContext = require("./toggle-button-context");
 var _useSideNavVisibility2 = require("./use-side-nav-visibility");
 var _useToggleSideNav = require("./use-toggle-side-nav");
+var _visibilityContext = require("./visibility-context");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != _typeof(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
@@ -51,10 +52,11 @@ var SideNavToggleButton = exports.SideNavToggleButton = function SideNavToggleBu
     }),
     isSideNavExpandedOnDesktop = _useSideNavVisibility.isExpandedOnDesktop,
     isSideNavExpandedOnMobile = _useSideNavVisibility.isExpandedOnMobile;
+  var sideNavState = (0, _react.useContext)(_visibilityContext.SideNavVisibilityState);
 
-  // When `platform_dst_nav4_full_height_sidebar_api_changes` is enabled,
-  // we default to the desktop state for SSR
-  var _useState = (0, _react.useState)((0, _platformFeatureFlags.fg)('platform_dst_nav4_full_height_sidebar_api_changes') ? isSideNavExpandedOnDesktop : !defaultCollapsed),
+  // When default state is provided to `Root` the state in context will already be
+  // initialized in SSR
+  var _useState = (0, _react.useState)(sideNavState === null || !(0, _platformFeatureFlags.fg)('platform_dst_nav4_side_nav_default_collapsed_api') ? !defaultCollapsed : isSideNavExpandedOnDesktop),
     _useState2 = (0, _slicedToArray2.default)(_useState, 2),
     isSideNavExpanded = _useState2[0],
     setIsSideNavExpanded = _useState2[1];

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

@@ -17,7 +17,7 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
 var SideNavVisibilityProvider = exports.SideNavVisibilityProvider = function SideNavVisibilityProvider(_ref) {
   var children = _ref.children,
     defaultCollapsed = _ref.defaultCollapsed;
-  var initialState = (0, _platformFeatureFlags.fg)('platform_dst_nav4_full_height_sidebar_api_changes') ? {
+  var initialState = typeof defaultCollapsed === 'boolean' && (0, _platformFeatureFlags.fg)('platform_dst_nav4_side_nav_default_collapsed_api') ? {
     desktop: defaultCollapsed ? 'collapsed' : 'expanded',
     mobile: 'collapsed',
     flyout: 'closed',

package/dist/cjs/ui/page-layout/top-nav/top-nav-start.js

@@ -16,6 +16,7 @@ var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
 var _compiled = require("@atlaskit/primitives/compiled");
 var _topNavStartContext = require("../../../context/top-nav-start/top-nav-start-context");
 var _useSideNavVisibility3 = require("../side-nav/use-side-nav-visibility");
+var _visibilityContext = require("../side-nav/visibility-context");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != _typeof(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
 /**
  * Firefox does support these reorder animations, but only partially enabling layout animations would look odd.
@@ -180,14 +181,22 @@ function TopNavStart(_ref3) {
 
   // Used to prevent the reorder animations from running on the initial render.
   var isFirstRenderRef = (0, _react.useRef)(true);
+  var sideNavState = (0, _react.useContext)(_visibilityContext.SideNavVisibilityState);
   (0, _react.useEffect)(function () {
     if (!(0, _platformFeatureFlags.fg)('navx-full-height-sidebar')) {
       return;
     }
+
+    // Ignore renders until the side nav state is initialized
+    // So that apps using the legacy API for setting side nav default state do not see
+    // animations when they shouldn't
+    if (sideNavState === null) {
+      return;
+    }
     if (isFirstRenderRef.current) {
       isFirstRenderRef.current = false;
     }
-  }, []);
+  }, [sideNavState]);
 
   // Using a stable ref to avoid re-running the animation layout effect when the toggle button prop value changes, which
   // can happen a lot (e.g. if the parent re-renders)

package/dist/es2019/ui/page-layout/root.js

@@ -26,7 +26,7 @@ export function Root({
   UNSAFE_dangerouslyHoistSlotSizes = false,
   skipLinksLabel = 'Skip to:',
   testId,
-  defaultSideNavCollapsed = false
+  defaultSideNavCollapsed
 }) {
   const ref = useRef(null);
   useEffect(() => {

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

@@ -3,10 +3,11 @@ import _extends from "@babel/runtime/helpers/extends";
 import "./side-nav.compiled.css";
 import * as React from 'react';
 import { ax, ix } from "@compiled/react/runtime";
-import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 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'
   });
@@ -243,8 +283,8 @@ function SideNavInternal({
     trigger: 'click-outside-on-mobile'
   });
   useEffect(() => {
-    if (fg('platform_dst_nav4_full_height_sidebar_api_changes')) {
-      // We are passing initial state to the Root now, so no initial sync is required
+    if (fg('platform_dst_nav4_side_nav_default_collapsed_api')) {
+      // This is the old version of the hook, so we skip it when the flag is enabled
       return;
     }
 
@@ -257,6 +297,28 @@ function SideNavInternal({
       lastTrigger: null
     });
   }, [initialDefaultCollapsed, setSideNavState]);
+
+  // Moving to `useLayoutEffect` so that there's no visual shift in non-SSR environments when using legacy API
+  // For SSR the new API is still necessary
+  useLayoutEffect(() => {
+    if (!fg('platform_dst_nav4_side_nav_default_collapsed_api')) {
+      // This is the new version of the hook, so we skip it when the flag is disabled
+      return;
+    }
+    if (sideNavState !== null) {
+      // Only need to do an initial sync if it hasn't been initialized from Root
+      return;
+    }
+
+    // Sync the visibility in context (provided in `<Root>`) with the local `defaultCollapsed` prop provided to `SideNav`
+    // after SSR hydration. This should only run once, after the initial render on the client.
+    setSideNavState({
+      desktop: initialDefaultCollapsed ? 'collapsed' : 'expanded',
+      mobile: 'collapsed',
+      flyout: 'closed',
+      lastTrigger: null
+    });
+  }, [initialDefaultCollapsed, setSideNavState, sideNavState]);
   const handleExpand = useCallback(({
     screen,
     trigger
@@ -673,6 +735,8 @@ export function SideNav({
   // Default value is defined in `SideNavInternal`
   onExpand,
   onCollapse,
+  onPeekStart,
+  onPeekEnd,
   id
 }) {
   return /*#__PURE__*/React.createElement(OpenLayerObserverNamespaceProvider, {
@@ -685,6 +749,8 @@ export function SideNav({
     skipLinkLabel: skipLinkLabel,
     onExpand: onExpand,
     onCollapse: onCollapse,
+    onPeekStart: onPeekStart,
+    onPeekEnd: onPeekEnd,
     id: id
   }, children));
 }

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

@@ -10,6 +10,7 @@ import { IconButton } from '../../top-nav-items/themed/migration';
 import { SideNavToggleButtonAttachRef } from './toggle-button-context';
 import { useSideNavVisibility } from './use-side-nav-visibility';
 import { useToggleSideNav } from './use-toggle-side-nav';
+import { SideNavVisibilityState } from './visibility-context';
 const toggleButtonTooltipOptions = {
   // We're disabling pointer events on the tooltip to prevent it from blocking mouse events, so that the side nav flyout stays open
   // when moving the mouse from the top bar to the side nav.
@@ -39,10 +40,11 @@ export const SideNavToggleButton = ({
   } = useSideNavVisibility({
     defaultCollapsed
   });
+  const sideNavState = useContext(SideNavVisibilityState);
 
-  // When `platform_dst_nav4_full_height_sidebar_api_changes` is enabled,
-  // we default to the desktop state for SSR
-  const [isSideNavExpanded, setIsSideNavExpanded] = useState(fg('platform_dst_nav4_full_height_sidebar_api_changes') ? isSideNavExpandedOnDesktop : !defaultCollapsed);
+  // When default state is provided to `Root` the state in context will already be
+  // initialized in SSR
+  const [isSideNavExpanded, setIsSideNavExpanded] = useState(sideNavState === null || !fg('platform_dst_nav4_side_nav_default_collapsed_api') ? !defaultCollapsed : isSideNavExpandedOnDesktop);
   const ref = useContext(SideNavToggleButtonAttachRef);
   const elementRef = useRef(null);
 

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

@@ -9,7 +9,7 @@ export const SideNavVisibilityProvider = ({
   children,
   defaultCollapsed
 }) => {
-  const initialState = fg('platform_dst_nav4_full_height_sidebar_api_changes') ? {
+  const initialState = typeof defaultCollapsed === 'boolean' && fg('platform_dst_nav4_side_nav_default_collapsed_api') ? {
     desktop: defaultCollapsed ? 'collapsed' : 'expanded',
     mobile: 'collapsed',
     flyout: 'closed',

package/dist/es2019/ui/page-layout/top-nav/top-nav-start.js

@@ -7,6 +7,7 @@ import { fg } from '@atlaskit/platform-feature-flags';
 import { UNSAFE_useMediaQuery } from '@atlaskit/primitives/compiled';
 import { TopNavStartAttachRef } from '../../../context/top-nav-start/top-nav-start-context';
 import { useSideNavVisibility } from '../side-nav/use-side-nav-visibility';
+import { SideNavVisibilityState } from '../side-nav/visibility-context';
 
 /**
  * Firefox does support these reorder animations, but only partially enabling layout animations would look odd.
@@ -170,14 +171,22 @@ export function TopNavStart({
 
   // Used to prevent the reorder animations from running on the initial render.
   const isFirstRenderRef = useRef(true);
+  const sideNavState = useContext(SideNavVisibilityState);
   useEffect(() => {
     if (!fg('navx-full-height-sidebar')) {
       return;
     }
+
+    // Ignore renders until the side nav state is initialized
+    // So that apps using the legacy API for setting side nav default state do not see
+    // animations when they shouldn't
+    if (sideNavState === null) {
+      return;
+    }
     if (isFirstRenderRef.current) {
       isFirstRenderRef.current = false;
     }
-  }, []);
+  }, [sideNavState]);
 
   // Using a stable ref to avoid re-running the animation layout effect when the toggle button prop value changes, which
   // can happen a lot (e.g. if the parent re-renders)

package/dist/esm/ui/page-layout/root.js

@@ -28,8 +28,7 @@ export function Root(_ref) {
     _ref$skipLinksLabel = _ref.skipLinksLabel,
     skipLinksLabel = _ref$skipLinksLabel === void 0 ? 'Skip to:' : _ref$skipLinksLabel,
     testId = _ref.testId,
-    _ref$defaultSideNavCo = _ref.defaultSideNavCollapsed,
-    defaultSideNavCollapsed = _ref$defaultSideNavCo === void 0 ? false : _ref$defaultSideNavCo;
+    defaultSideNavCollapsed = _ref.defaultSideNavCollapsed;
   var ref = useRef(null);
   useEffect(function () {
     if (process.env.NODE_ENV !== 'production') {

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

@@ -7,10 +7,11 @@ import * as React from 'react';
 import { ax, ix } from "@compiled/react/runtime";
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
-import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 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'
   });
@@ -251,8 +291,8 @@ function SideNavInternal(_ref) {
     trigger: 'click-outside-on-mobile'
   });
   useEffect(function () {
-    if (fg('platform_dst_nav4_full_height_sidebar_api_changes')) {
-      // We are passing initial state to the Root now, so no initial sync is required
+    if (fg('platform_dst_nav4_side_nav_default_collapsed_api')) {
+      // This is the old version of the hook, so we skip it when the flag is enabled
       return;
     }
 
@@ -265,6 +305,28 @@ function SideNavInternal(_ref) {
       lastTrigger: null
     });
   }, [initialDefaultCollapsed, setSideNavState]);
+
+  // Moving to `useLayoutEffect` so that there's no visual shift in non-SSR environments when using legacy API
+  // For SSR the new API is still necessary
+  useLayoutEffect(function () {
+    if (!fg('platform_dst_nav4_side_nav_default_collapsed_api')) {
+      // This is the new version of the hook, so we skip it when the flag is disabled
+      return;
+    }
+    if (sideNavState !== null) {
+      // Only need to do an initial sync if it hasn't been initialized from Root
+      return;
+    }
+
+    // Sync the visibility in context (provided in `<Root>`) with the local `defaultCollapsed` prop provided to `SideNav`
+    // after SSR hydration. This should only run once, after the initial render on the client.
+    setSideNavState({
+      desktop: initialDefaultCollapsed ? 'collapsed' : 'expanded',
+      mobile: 'collapsed',
+      flyout: 'closed',
+      lastTrigger: null
+    });
+  }, [initialDefaultCollapsed, setSideNavState, sideNavState]);
   var handleExpand = useCallback(function (_ref2) {
     var screen = _ref2.screen,
       trigger = _ref2.trigger;
@@ -672,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
@@ -683,6 +747,8 @@ export function SideNav(_ref8) {
     skipLinkLabel: skipLinkLabel,
     onExpand: onExpand,
     onCollapse: onCollapse,
+    onPeekStart: onPeekStart,
+    onPeekEnd: onPeekEnd,
     id: id
   }, children));
 }

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

@@ -14,6 +14,7 @@ import { IconButton } from '../../top-nav-items/themed/migration';
 import { SideNavToggleButtonAttachRef } from './toggle-button-context';
 import { useSideNavVisibility } from './use-side-nav-visibility';
 import { useToggleSideNav } from './use-toggle-side-nav';
+import { SideNavVisibilityState } from './visibility-context';
 var toggleButtonTooltipOptions = {
   // We're disabling pointer events on the tooltip to prevent it from blocking mouse events, so that the side nav flyout stays open
   // when moving the mouse from the top bar to the side nav.
@@ -42,10 +43,11 @@ export var SideNavToggleButton = function SideNavToggleButton(_ref) {
     }),
     isSideNavExpandedOnDesktop = _useSideNavVisibility.isExpandedOnDesktop,
     isSideNavExpandedOnMobile = _useSideNavVisibility.isExpandedOnMobile;
+  var sideNavState = useContext(SideNavVisibilityState);
 
-  // When `platform_dst_nav4_full_height_sidebar_api_changes` is enabled,
-  // we default to the desktop state for SSR
-  var _useState = useState(fg('platform_dst_nav4_full_height_sidebar_api_changes') ? isSideNavExpandedOnDesktop : !defaultCollapsed),
+  // When default state is provided to `Root` the state in context will already be
+  // initialized in SSR
+  var _useState = useState(sideNavState === null || !fg('platform_dst_nav4_side_nav_default_collapsed_api') ? !defaultCollapsed : isSideNavExpandedOnDesktop),
     _useState2 = _slicedToArray(_useState, 2),
     isSideNavExpanded = _useState2[0],
     setIsSideNavExpanded = _useState2[1];

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

@@ -9,7 +9,7 @@ import { SetSideNavVisibilityState, SideNavVisibilityState } from './visibility-
 export var SideNavVisibilityProvider = function SideNavVisibilityProvider(_ref) {
   var children = _ref.children,
     defaultCollapsed = _ref.defaultCollapsed;
-  var initialState = fg('platform_dst_nav4_full_height_sidebar_api_changes') ? {
+  var initialState = typeof defaultCollapsed === 'boolean' && fg('platform_dst_nav4_side_nav_default_collapsed_api') ? {
     desktop: defaultCollapsed ? 'collapsed' : 'expanded',
     mobile: 'collapsed',
     flyout: 'closed',

package/dist/esm/ui/page-layout/top-nav/top-nav-start.js

@@ -8,6 +8,7 @@ import { fg } from '@atlaskit/platform-feature-flags';
 import { UNSAFE_useMediaQuery } from '@atlaskit/primitives/compiled';
 import { TopNavStartAttachRef } from '../../../context/top-nav-start/top-nav-start-context';
 import { useSideNavVisibility } from '../side-nav/use-side-nav-visibility';
+import { SideNavVisibilityState } from '../side-nav/visibility-context';
 
 /**
  * Firefox does support these reorder animations, but only partially enabling layout animations would look odd.
@@ -172,14 +173,22 @@ export function TopNavStart(_ref3) {
 
   // Used to prevent the reorder animations from running on the initial render.
   var isFirstRenderRef = useRef(true);
+  var sideNavState = useContext(SideNavVisibilityState);
   useEffect(function () {
     if (!fg('navx-full-height-sidebar')) {
       return;
     }
+
+    // Ignore renders until the side nav state is initialized
+    // So that apps using the legacy API for setting side nav default state do not see
+    // animations when they shouldn't
+    if (sideNavState === null) {
+      return;
+    }
     if (isFirstRenderRef.current) {
       isFirstRenderRef.current = false;
     }
-  }, []);
+  }, [sideNavState]);
 
   // Using a stable ref to avoid re-running the animation layout effect when the toggle button prop value changes, which
   // can happen a lot (e.g. if the parent re-renders)

package/dist/types/ui/page-layout/root.d.ts

@@ -44,7 +44,7 @@ export declare function Root({ children, xcss, UNSAFE_dangerouslyHoistSlotSizes,
      * persisted state using the `onCollapse` and `onExpand` callbacks, to ensure it is up to date
      * when the app is reloaded.
      *
-     * __Note:__ This prop will only work when the `platform_dst_nav4_full_height_sidebar_api_changes` gate is enabled.
+     * __Note:__ When provided, the `defaultCollapsed` props on `SideNav` and `SideNavToggleButton` will be ignored.
      */
     defaultSideNavCollapsed?: boolean;
 }): JSX.Element;

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

@@ -15,7 +15,7 @@ type SideNavProps = CommonSlotProps & {
      * @deprecated
      *
      * This prop is being replaced by `defaultSideNavCollapsed` on the `Root` element,
-     * and will be removed after `platform_dst_nav4_full_height_sidebar_api_changes` is cleaned up.
+     * and will be removed in the future.
      *
      * ---
      *
@@ -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/ui/page-layout/side-nav/toggle-button.d.ts

@@ -17,7 +17,7 @@ export declare const SideNavToggleButton: ({ defaultCollapsed, expandLabel, coll
      * @deprecated
      *
      * This prop is being replaced by `defaultSideNavCollapsed` on the `Root` element,
-     * and will be removed after `platform_dst_nav4_full_height_sidebar_api_changes` is cleaned up.
+     * and will be removed in the future.
      *
      * ---
      *

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

@@ -4,5 +4,5 @@ import React from 'react';
  */
 export declare const SideNavVisibilityProvider: ({ children, defaultCollapsed, }: {
     children: React.ReactNode;
-    defaultCollapsed: boolean;
+    defaultCollapsed?: boolean;
 }) => React.JSX.Element;

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

@@ -19,7 +19,7 @@ type TopNavStartProps = {
      *
      * You should only render `<SideNavToggleButton>` inside this slot, not as a child.
      *
-     * After `platform_dst_nav4_full_height_sidebar_api_changes` rolls out,
+     * After `platform_dst_nav4_side_nav_toggle_button_slot` rolls out,
      * this prop will become required.
      *
      * Consumers that do not need a toggle button can explicitly pass `null`.

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

@@ -44,7 +44,7 @@ export declare function Root({ children, xcss, UNSAFE_dangerouslyHoistSlotSizes,
      * persisted state using the `onCollapse` and `onExpand` callbacks, to ensure it is up to date
      * when the app is reloaded.
      *
-     * __Note:__ This prop will only work when the `platform_dst_nav4_full_height_sidebar_api_changes` gate is enabled.
+     * __Note:__ When provided, the `defaultCollapsed` props on `SideNav` and `SideNavToggleButton` will be ignored.
      */
     defaultSideNavCollapsed?: boolean;
 }): JSX.Element;

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

@@ -15,7 +15,7 @@ type SideNavProps = CommonSlotProps & {
      * @deprecated
      *
      * This prop is being replaced by `defaultSideNavCollapsed` on the `Root` element,
-     * and will be removed after `platform_dst_nav4_full_height_sidebar_api_changes` is cleaned up.
+     * and will be removed in the future.
      *
      * ---
      *
@@ -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/toggle-button.d.ts

@@ -17,7 +17,7 @@ export declare const SideNavToggleButton: ({ defaultCollapsed, expandLabel, coll
      * @deprecated
      *
      * This prop is being replaced by `defaultSideNavCollapsed` on the `Root` element,
-     * and will be removed after `platform_dst_nav4_full_height_sidebar_api_changes` is cleaned up.
+     * and will be removed in the future.
      *
      * ---
      *

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

@@ -4,5 +4,5 @@ import React from 'react';
  */
 export declare const SideNavVisibilityProvider: ({ children, defaultCollapsed, }: {
     children: React.ReactNode;
-    defaultCollapsed: boolean;
+    defaultCollapsed?: boolean;
 }) => React.JSX.Element;

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

@@ -19,7 +19,7 @@ type TopNavStartProps = {
      *
      * You should only render `<SideNavToggleButton>` inside this slot, not as a child.
      *
-     * After `platform_dst_nav4_full_height_sidebar_api_changes` rolls out,
+     * After `platform_dst_nav4_side_nav_toggle_button_slot` rolls out,
      * this prop will become required.
      *
      * Consumers that do not need a toggle button can explicitly pass `null`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/navigation-system",
-	"version": "4.2.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",
@@ -145,6 +145,9 @@
 		}
 	},
 	"platform-feature-flags": {
+		"platform_dst_nav4_side_nav_default_collapsed_api": {
+			"type": "boolean"
+		},
 		"platform_dst_nav4_side_nav_toggle_ref_fix": {
 			"type": "boolean"
 		},
@@ -170,9 +173,6 @@
 		"team25-eu-jira-logo-updates-csm-jsm": {
 			"type": "boolean"
 		},
-		"platform_dst_nav4_full_height_sidebar_api_changes": {
-			"type": "boolean"
-		},
 		"platform-dst-tooltip-shortcuts": {
 			"type": "boolean"
 		},