@atlaskit/navigation-system 9.3.1 → 9.4.1

package/dist/esm/components/skip-links/skip-links-popup.js

@@ -9,6 +9,7 @@ import { flushSync } from 'react-dom';
 import Button from '@atlaskit/button/new';
 import mergeRefs from '@atlaskit/ds-lib/merge-refs';
 import Popup from '@atlaskit/popup';
+import { focusElement } from './focus-element';
 import { SkipLink } from './skip-link';
 var contentStyles = {
   root: "_1rjcu2gc _18zrpxbi _1e0c1txw _2lx21bp4 _1pbyjh3g",
@@ -89,13 +90,34 @@ export function SkipLinksPopup(_ref) {
       }, links.map(function (_ref2) {
         var id = _ref2.id,
           label = _ref2.label,
-          _onBeforeNavigate = _ref2.onBeforeNavigate;
+          _navigate = _ref2.navigate;
         return /*#__PURE__*/React.createElement(SkipLink, {
           key: id,
-          id: id,
-          onBeforeNavigate: function onBeforeNavigate() {
+          id: id
+          /**
+           * The popup always owns the navigation effect under the
+           * `platform_dst_nav4_skip_link_a11y_1` gate (the only path
+           * that renders `SkipLinksPopup`). It first closes itself
+           * synchronously so its focus lock is released, then either:
+           *
+           *  - delegates to the consumer's `navigate` (e.g. SideNav
+           *    expanding and focusing its first nav item), or
+           *  - falls back to focusing the slot element with `id`.
+           *
+           * This means `SkipLink`'s `onBeforeNavigate` hook is never
+           * needed under the gate and can be removed on cleanup.
+           */,
+          navigate: function navigate() {
             closePopup();
-            _onBeforeNavigate === null || _onBeforeNavigate === void 0 || _onBeforeNavigate();
+            if (_navigate) {
+              _navigate();
+              return;
+            }
+            // Intentionally not using `document.querySelector` because many valid IDs are not valid selectors.
+            var target = document.getElementById(id);
+            if (target) {
+              focusElement(target);
+            }
           }
         }, label);
       })));

package/dist/esm/context/skip-links/use-skip-link-internal.js

@@ -5,14 +5,15 @@ import { SkipLinksContext } from './skip-links-context';
  *
  * `useSkipLink` is the public API wrapper of this.
  *
- * This private version exists for us to support `onBeforeNavigate` for the side nav use case,
- * where we might need to expand it before moving focus, without having to support `onBeforeNavigate` publicly.
+ * This private version exists for us to support `onBeforeNavigate` / `navigate` for the side nav use case,
+ * where we might need to expand it before moving focus, without having to support those publicly.
  */
 export var useSkipLinkInternal = function useSkipLinkInternal(_ref) {
   var id = _ref.id,
     label = _ref.label,
     listIndex = _ref.listIndex,
     onBeforeNavigate = _ref.onBeforeNavigate,
+    navigate = _ref.navigate,
     isHidden = _ref.isHidden;
   var _useContext = useContext(SkipLinksContext),
     registerSkipLink = _useContext.registerSkipLink,
@@ -30,10 +31,11 @@ export var useSkipLinkInternal = function useSkipLinkInternal(_ref) {
       label: label,
       listIndex: listIndex,
       onBeforeNavigate: onBeforeNavigate,
+      navigate: navigate,
       isHidden: isHidden
     });
     return function () {
       unregisterSkipLink(id);
     };
-  }, [id, isHidden, label, listIndex, onBeforeNavigate, registerSkipLink, unregisterSkipLink]);
+  }, [id, isHidden, label, listIndex, onBeforeNavigate, navigate, registerSkipLink, unregisterSkipLink]);
 };

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

@@ -13,6 +13,7 @@ import { useAnalyticsEvents } from '@atlaskit/analytics-next';
 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';
 import { media } from '@atlaskit/primitives/responsive';
 import { useSkipLinkInternal } from '../../../context/skip-links/use-skip-link-internal';
@@ -104,28 +105,38 @@ function SideNavInternal(_ref) {
   var id = useLayoutId({
     providedId: providedId
   });
-  var expandSideNav = useExpandSideNav({
+  var expandAndFocusSideNav = useExpandSideNav({
     trigger: 'skip-link'
   });
   /**
    * Called after clicking on the side nav skip link, and ensures the side nav is expanded so that it is focusable.
    *
    * We need to update the DOM synchronously because `.focus()` is called synchronously after this state update.
+   *
+   * Only used when `platform_dst_nav4_skip_link_a11y_1` is OFF; can be removed on gate cleanup.
    */
   var synchronouslyExpandSideNav = useCallback(function () {
     flushSync(function () {
       /**
        * Calling this unconditionally and relying on it to avoid no-op renders.
        *
-       * We _could_ call it conditionally, but we'd be duplicating the screen size checks `expandSideNav` makes.
+       * We _could_ call it conditionally, but we'd be duplicating the screen size checks `expandAndFocusSideNav` makes.
        */
-      expandSideNav();
+      expandAndFocusSideNav();
     });
-  }, [expandSideNav]);
+  }, [expandAndFocusSideNav]);
   useSkipLinkInternal({
     id: id,
     label: skipLinkLabel,
-    onBeforeNavigate: synchronouslyExpandSideNav
+    /**
+     * `navigate` is the gate-on contract: it owns expanding the side nav AND moving
+     * focus to the first nav item, atomically (via `useExpandSideNav`'s `flushSync`).
+     *
+     * `onBeforeNavigate` is the legacy contract used only when the gate is OFF.
+     * On gate cleanup, drop `onBeforeNavigate` and `synchronouslyExpandSideNav` here.
+     */
+    navigate: fg('platform_dst_nav4_skip_link_a11y_1') ? expandAndFocusSideNav : undefined,
+    onBeforeNavigate: fg('platform_dst_nav4_skip_link_a11y_1') ? undefined : synchronouslyExpandSideNav
   });
   var sideNavState = useContext(SideNavVisibilityState);
   var setSideNavState = useContext(SetSideNavVisibilityState);

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

@@ -1,5 +1,59 @@
 import { useCallback, useContext } from 'react';
+import { bind } from 'bind-event-listener';
+import { flushSync } from 'react-dom';
+import { fg } from '@atlaskit/platform-feature-flags';
 import { SetSideNavVisibilityState } from './set-side-nav-visibility-state';
+import { useSideNavRef } from './use-side-nav-ref';
+/**
+ * Moves focus to the first focusable item in the side nav, or the side nav element itself as a fallback.
+ */
+function focusFirstNavItem(sideNavElement) {
+  var _firstNavItem$checkVi, _firstNavItem$checkVi2;
+  /**
+   * Try to get the first focusable item in the side nav.
+   * The selector is not very broad, but should be appropriate for items from this package.
+   */
+  var firstNavItem = sideNavElement.querySelector('a, button');
+  var isFirstNavItemVisible = firstNavItem !== null && ((_firstNavItem$checkVi = (_firstNavItem$checkVi2 = firstNavItem.checkVisibility) === null || _firstNavItem$checkVi2 === void 0 ? void 0 : _firstNavItem$checkVi2.call(firstNavItem)) !== null && _firstNavItem$checkVi !== void 0 ? _firstNavItem$checkVi : false);
+  var itemToFocus = isFirstNavItemVisible ? firstNavItem : sideNavElement;
+  if (itemToFocus === sideNavElement) {
+    /**
+     * Elements without an explicit `tabindex` attribute are not guaranteed to be focusable:
+     * https://html.spec.whatwg.org/multipage/interaction.html#attr-tabindex
+     *
+     * Our slots are not interactive, so this is required.
+     *
+     * In the future we may want to check if there is an existing `tabindex` attribute,
+     * as custom skip linked elements might already have one.
+     */
+    sideNavElement.setAttribute('tabindex', '-1');
+
+    /**
+     * Cleanup the `tabindex` attribute we set when the slot or custom target loses focus.
+     *
+     * This is preferable to always having `tabindex="-1"` because always applying the tab index can:
+     *
+     * - mess with click events
+     * - potentially cause a focus ring to be always visible
+     */
+    bind(sideNavElement, {
+      type: 'blur',
+      listener: function listener() {
+        sideNavElement.removeAttribute('tabindex');
+      },
+      options: {
+        once: true
+      }
+    });
+  }
+
+  /**
+   * Not using `focusVisible` option because we don't want clicks on the toggle button to show a focus ring.
+   */
+  itemToFocus.focus();
+}
+var triggersWithFocusOnExpand = new Set(['toggle-button', 'skip-link']);
+
 /**
  * __useExpandSideNav__
  *
@@ -14,48 +68,60 @@ export function useExpandSideNav() {
     _ref$trigger = _ref.trigger,
     trigger = _ref$trigger === void 0 ? 'programmatic' : _ref$trigger;
   var setSideNavState = useContext(SetSideNavVisibilityState);
+  var sideNavRef = useSideNavRef();
   var expandSideNav = useCallback(function () {
     var _window$matchMedia = window.matchMedia('(min-width: 64rem)'),
-      matches = _window$matchMedia.matches;
-    if (matches) {
-      setSideNavState(function (currentState) {
-        // No-op if the side nav state has not been initialised yet
-        // e.g. if the SideNav has not been mounted yet
-        if (!currentState) {
-          return null;
-        }
+      isDesktop = _window$matchMedia.matches;
+    var runUpdate = function runUpdate() {
+      if (isDesktop) {
+        setSideNavState(function (currentState) {
+          // No-op if the side nav state has not been initialised yet
+          // e.g. if the SideNav has not been mounted yet
+          if (!currentState) {
+            return null;
+          }
 
-        // Skip the re-render if it's a no-op change
-        if (currentState.desktop === 'expanded' && currentState.flyout === 'closed') {
-          return currentState;
-        }
-        return {
-          mobile: currentState.mobile,
-          desktop: 'expanded',
-          flyout: 'closed',
-          lastTrigger: trigger
-        };
-      });
-    } else {
-      setSideNavState(function (currentState) {
-        // No-op if the side nav state has not been initialised yet
-        // e.g. if the SideNav has not been mounted yet
-        if (!currentState) {
-          return null;
-        }
+          // Skip the re-render if it's a no-op change
+          if (currentState.desktop === 'expanded' && currentState.flyout === 'closed') {
+            return currentState;
+          }
+          return {
+            mobile: currentState.mobile,
+            desktop: 'expanded',
+            flyout: 'closed',
+            lastTrigger: trigger
+          };
+        });
+      } else {
+        setSideNavState(function (currentState) {
+          // No-op if the side nav state has not been initialised yet
+          // e.g. if the SideNav has not been mounted yet
+          if (!currentState) {
+            return null;
+          }
 
-        // Skip the re-render if it's a no-op change
-        if (currentState.mobile === 'expanded' && currentState.flyout === 'closed') {
-          return currentState;
-        }
-        return {
-          desktop: currentState.desktop,
-          mobile: 'expanded',
-          flyout: 'closed',
-          lastTrigger: trigger
-        };
-      });
+          // Skip the re-render if it's a no-op change
+          if (currentState.mobile === 'expanded' && currentState.flyout === 'closed') {
+            return currentState;
+          }
+          return {
+            desktop: currentState.desktop,
+            mobile: 'expanded',
+            flyout: 'closed',
+            lastTrigger: trigger
+          };
+        });
+      }
+    };
+    if (triggersWithFocusOnExpand.has(trigger) && fg('platform_dst_nav4_skip_link_a11y_1')) {
+      flushSync(runUpdate);
+      var sideNavElement = sideNavRef.current;
+      if (sideNavElement) {
+        focusFirstNavItem(sideNavElement);
+      }
+    } else {
+      runUpdate();
     }
-  }, [setSideNavState, trigger]);
+  }, [setSideNavState, sideNavRef, trigger]);
   return expandSideNav;
 }

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

@@ -1,5 +1,8 @@
 import { useCallback, useContext } from 'react';
+import { fg } from '@atlaskit/platform-feature-flags';
 import { SetSideNavVisibilityState } from './set-side-nav-visibility-state';
+import { SideNavVisibilityState } from './side-nav-visibility-state';
+import { useExpandSideNav } from './use-expand-side-nav';
 /**
  * __useToggleSideNav__
  *
@@ -14,10 +17,37 @@ export function useToggleSideNav() {
     _ref$trigger = _ref.trigger,
     trigger = _ref$trigger === void 0 ? 'programmatic' : _ref$trigger;
   var setSideNavState = useContext(SetSideNavVisibilityState);
+  var sideNavState = useContext(SideNavVisibilityState);
+  var expandSideNav = useExpandSideNav({
+    trigger: trigger
+  });
+  var isCollapsedOnDesktop = (sideNavState === null || sideNavState === void 0 ? void 0 : sideNavState.desktop) === 'collapsed';
+  var isCollapsedOnMobile = (sideNavState === null || sideNavState === void 0 ? void 0 : sideNavState.mobile) === 'collapsed';
   var toggleSideNav = useCallback(function () {
     var _window$matchMedia = window.matchMedia('(min-width: 64rem)'),
-      matches = _window$matchMedia.matches;
-    if (matches) {
+      isDesktop = _window$matchMedia.matches;
+    if (fg('platform_dst_nav4_skip_link_a11y_1')) {
+      var isExpanding = isDesktop ? isCollapsedOnDesktop : isCollapsedOnMobile;
+      if (isExpanding) {
+        expandSideNav();
+      } else {
+        setSideNavState(function (currentState) {
+          // No-op if the side nav state has not been initialised yet
+          // e.g. if the SideNav has not been mounted yet
+          if (!currentState) {
+            return null;
+          }
+          return {
+            mobile: isDesktop ? currentState.mobile : 'collapsed',
+            desktop: isDesktop ? 'collapsed' : currentState.desktop,
+            flyout: 'closed',
+            lastTrigger: trigger
+          };
+        });
+      }
+      return;
+    }
+    if (isDesktop) {
       setSideNavState(function (currentState) {
         // No-op if the side nav state has not been initialised yet
         // e.g. if the SideNav has not been mounted yet
@@ -46,6 +76,6 @@ export function useToggleSideNav() {
         };
       });
     }
-  }, [setSideNavState, trigger]);
+  }, [expandSideNav, isCollapsedOnDesktop, isCollapsedOnMobile, setSideNavState, trigger]);
   return toggleSideNav;
 }

package/dist/types/components/skip-links/focus-element.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Used for moving focus to the corresponding slot or custom target after clicking on a skip link.
+ */
+export declare function focusElement(element: HTMLElement): void;

package/dist/types/components/skip-links/skip-link.d.ts

@@ -8,11 +8,12 @@ type SkipLinkProps = {
     id: string;
     children: ReactNode;
     onBeforeNavigate?: SkipLinkData['onBeforeNavigate'];
+    navigate?: SkipLinkData['navigate'];
 };
 /**
  * A link that moves current tab position to a different element
  *
  * This component is rendered internally and is not exported publicly.
  */
-export declare const SkipLink: ({ id, children, onBeforeNavigate }: SkipLinkProps) => JSX.Element;
+export declare const SkipLink: ({ id, children, onBeforeNavigate, navigate, }: SkipLinkProps) => JSX.Element;
 export {};

package/dist/types/context/skip-links/types.d.ts

@@ -16,10 +16,27 @@ export type SkipLinkData = {
      * immediately before focus is moved to the associated element.
      *
      * This can be used to update state, such as to show a hidden element.
+     *
+     * @deprecated Only used when `platform_dst_nav4_skip_link_a11y_1` is OFF.
+     * When the gate is on, prefer `navigate` for consumers that need to atomically
+     * commit state and move focus somewhere other than the slot element with id `id`.
+     * This callback can be removed once the gate is fully enabled and cleaned up.
      */
     onBeforeNavigate?: () => void;
     /**
-     * Used to hide skip links for slots with 0 height or width.s
+     * Replaces the default "focus the element with `id`" behavior when the skip link is activated.
+     *
+     * Use this when the consumer needs to atomically commit state and move focus to
+     * a different element (e.g. SideNav expanding and focusing the first nav item).
+     *
+     * The universal pre/post work owned by `SkipLink` (e.g. `event.preventDefault`,
+     * `window.scrollTo`) still runs around this callback. Only the focus step is replaced.
+     *
+     * Only consumed when `platform_dst_nav4_skip_link_a11y_1` is enabled.
+     */
+    navigate?: () => void;
+    /**
+     * Used to hide skip links for slots with 0 height or width.
      *
      * We can remove this once products conditionally render slots correctly.
      */

package/dist/types/context/skip-links/use-skip-link-internal.d.ts

@@ -4,7 +4,7 @@ import { type SkipLinkData } from './types';
  *
  * `useSkipLink` is the public API wrapper of this.
  *
- * This private version exists for us to support `onBeforeNavigate` for the side nav use case,
- * where we might need to expand it before moving focus, without having to support `onBeforeNavigate` publicly.
+ * This private version exists for us to support `onBeforeNavigate` / `navigate` for the side nav use case,
+ * where we might need to expand it before moving focus, without having to support those publicly.
  */
-export declare const useSkipLinkInternal: ({ id, label, listIndex, onBeforeNavigate, isHidden, }: SkipLinkData) => void;
+export declare const useSkipLinkInternal: ({ id, label, listIndex, onBeforeNavigate, navigate, isHidden, }: SkipLinkData) => void;

package/dist/types-ts4.5/components/skip-links/focus-element.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Used for moving focus to the corresponding slot or custom target after clicking on a skip link.
+ */
+export declare function focusElement(element: HTMLElement): void;

package/dist/types-ts4.5/components/skip-links/skip-link.d.ts

@@ -8,11 +8,12 @@ type SkipLinkProps = {
     id: string;
     children: ReactNode;
     onBeforeNavigate?: SkipLinkData['onBeforeNavigate'];
+    navigate?: SkipLinkData['navigate'];
 };
 /**
  * A link that moves current tab position to a different element
  *
  * This component is rendered internally and is not exported publicly.
  */
-export declare const SkipLink: ({ id, children, onBeforeNavigate }: SkipLinkProps) => JSX.Element;
+export declare const SkipLink: ({ id, children, onBeforeNavigate, navigate, }: SkipLinkProps) => JSX.Element;
 export {};

package/dist/types-ts4.5/context/skip-links/types.d.ts

@@ -16,10 +16,27 @@ export type SkipLinkData = {
      * immediately before focus is moved to the associated element.
      *
      * This can be used to update state, such as to show a hidden element.
+     *
+     * @deprecated Only used when `platform_dst_nav4_skip_link_a11y_1` is OFF.
+     * When the gate is on, prefer `navigate` for consumers that need to atomically
+     * commit state and move focus somewhere other than the slot element with id `id`.
+     * This callback can be removed once the gate is fully enabled and cleaned up.
      */
     onBeforeNavigate?: () => void;
     /**
-     * Used to hide skip links for slots with 0 height or width.s
+     * Replaces the default "focus the element with `id`" behavior when the skip link is activated.
+     *
+     * Use this when the consumer needs to atomically commit state and move focus to
+     * a different element (e.g. SideNav expanding and focusing the first nav item).
+     *
+     * The universal pre/post work owned by `SkipLink` (e.g. `event.preventDefault`,
+     * `window.scrollTo`) still runs around this callback. Only the focus step is replaced.
+     *
+     * Only consumed when `platform_dst_nav4_skip_link_a11y_1` is enabled.
+     */
+    navigate?: () => void;
+    /**
+     * Used to hide skip links for slots with 0 height or width.
      *
      * We can remove this once products conditionally render slots correctly.
      */

package/dist/types-ts4.5/context/skip-links/use-skip-link-internal.d.ts

@@ -4,7 +4,7 @@ import { type SkipLinkData } from './types';
  *
  * `useSkipLink` is the public API wrapper of this.
  *
- * This private version exists for us to support `onBeforeNavigate` for the side nav use case,
- * where we might need to expand it before moving focus, without having to support `onBeforeNavigate` publicly.
+ * This private version exists for us to support `onBeforeNavigate` / `navigate` for the side nav use case,
+ * where we might need to expand it before moving focus, without having to support those publicly.
  */
-export declare const useSkipLinkInternal: ({ id, label, listIndex, onBeforeNavigate, isHidden, }: SkipLinkData) => void;
+export declare const useSkipLinkInternal: ({ id, label, listIndex, onBeforeNavigate, navigate, isHidden, }: SkipLinkData) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/navigation-system",
-	"version": "9.3.1",
+	"version": "9.4.1",
 	"description": "The latest navigation system for Atlassian apps.",
 	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-mirror",
 	"author": "Atlassian Pty Ltd",
@@ -76,7 +76,7 @@
 		"@atlaskit/button": "^23.11.0",
 		"@atlaskit/css": "^0.19.0",
 		"@atlaskit/ds-lib": "^7.0.0",
-		"@atlaskit/icon": "^34.5.0",
+		"@atlaskit/icon": "^35.0.0",
 		"@atlaskit/layering": "^3.7.0",
 		"@atlaskit/logo": "^20.1.0",
 		"@atlaskit/platform-feature-flags": "^1.1.0",
@@ -125,12 +125,12 @@
 		"@atlaskit/textfield": "^8.3.0",
 		"@atlaskit/top-layer": "^0.6.0",
 		"@atlassian/feature-flags-test-utils": "^1.1.0",
-		"@atlassian/gemini": "^1.44.0",
+		"@atlassian/gemini": "^1.45.0",
 		"@atlassian/react-compiler-gating": "workspace:^",
 		"@atlassian/search-dialog": "^10.3.0",
 		"@atlassian/ssr-tests": "workspace:^",
 		"@atlassian/test-utils": "^1.0.0",
-		"@atlassian/testing-library": "^0.5.0",
+		"@atlassian/testing-library": "^0.6.0",
 		"@axe-core/playwright": "^4.11.1",
 		"@testing-library/react": "^16.3.0",
 		"@testing-library/user-event": "^14.4.3",