@atlaskit/navigation-system 9.3.1 → 9.4.0

package/dist/cjs/components/skip-links/focus-element.js

@@ -0,0 +1,54 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.focusElement = focusElement;
+var _bindEventListener = require("bind-event-listener");
+/**
+ * Used for moving focus to the corresponding slot or custom target after clicking on a skip link.
+ */
+function focusElement(element) {
+  /**
+   * 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.
+   */
+  element.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
+   */
+  (0, _bindEventListener.bind)(element, {
+    type: 'blur',
+    listener: function listener() {
+      element.removeAttribute('tabindex');
+    },
+    options: {
+      // Using a one-time listener so it cleans itself up
+      once: true
+    }
+  });
+
+  /**
+   * Move focus to the slot or custom target.
+   *
+   * Calling `.focus()` will also scroll the element into view:
+   * https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus
+   */
+  element.focus({
+    // Forces the focus ring to appear after moving focus to the slot
+    // https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#focusvisible
+    // @ts-expect-error - new and not in types yet
+    focusVisible: true
+  });
+}

package/dist/cjs/components/skip-links/skip-link.js

@@ -9,63 +9,15 @@ exports.SkipLink = void 0;
 require("./skip-link.compiled.css");
 var _runtime = require("@compiled/react/runtime");
 var _react = _interopRequireWildcard(require("react"));
-var _bindEventListener = require("bind-event-listener");
 var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
 var _compiled = require("@atlaskit/primitives/compiled");
+var _focusElement = require("./focus-element");
 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); }
 // eslint-disable-next-line @atlaskit/design-system/no-emotion-primitives -- to be migrated to @atlaskit/primitives/compiled – go/akcss
 var styles = {
   skipLinkListItem: "_1pfhze3t",
   skipLinkListItemNew: "_1rjcu2gc"
 };
-
-/**
- * Used for moving focus to the corresponding slot or custom target after clicking on a skip link.
- */
-function focusElement(element) {
-  /**
-   * 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.
-   */
-  element.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
-   */
-  (0, _bindEventListener.bind)(element, {
-    type: 'blur',
-    listener: function listener() {
-      element.removeAttribute('tabindex');
-    },
-    options: {
-      // Using a one-time listener so it cleans itself up
-      once: true
-    }
-  });
-
-  /**
-   * Move focus to the slot or custom target.
-   *
-   * Calling `.focus()` will also scroll the element into view:
-   * https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus
-   */
-  element.focus({
-    // Forces the focus ring to appear after moving focus to the slot
-    // https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#focusvisible
-    // @ts-expect-error - new and not in types yet
-    focusVisible: true
-  });
-}
 /**
  * A link that moves current tab position to a different element
  *
@@ -74,25 +26,40 @@ function focusElement(element) {
 var SkipLink = exports.SkipLink = function SkipLink(_ref) {
   var id = _ref.id,
     children = _ref.children,
-    onBeforeNavigate = _ref.onBeforeNavigate;
+    onBeforeNavigate = _ref.onBeforeNavigate,
+    navigate = _ref.navigate;
   var href = "#".concat(id);
-  var onClick = (0, _react.useCallback)(function (event) {
+  var handleClick = (0, _react.useCallback)(function (event) {
     event.preventDefault();
+    if (navigate && (0, _platformFeatureFlags.fg)('platform_dst_nav4_skip_link_a11y_1')) {
+      /**
+       * The consumer takes over the navigation effect (e.g. expanding the
+       * side nav and focusing the first nav item). The universal pre/post
+       * work below (e.g. `window.scrollTo`) still runs around it.
+       */
+      navigate();
+    } else {
+      // Intentionally not using `document.querySelector` because many valid IDs are not valid selectors.
+      var target = document.getElementById(id);
+      if (!target) {
+        return;
+      }
 
-    // Intentionally not using `document.querySelector` because many valid IDs are not valid selectors.
-    var target = document.getElementById(id);
-    if (!target) {
-      return;
+      /**
+       * Legacy `onBeforeNavigate` hook. Intentionally NOT called when
+       * `platform_dst_nav4_skip_link_a11y_1` is enabled — under the gate the
+       * gate-on path delegates state mutation + focus management to `navigate`,
+       * and `SkipLinksPopup` injects its popup-close behavior into the
+       * `navigate` wrapper instead of relying on this hook.
+       *
+       * This callback can be removed entirely on gate cleanup.
+       */
+      if (!(0, _platformFeatureFlags.fg)('platform_dst_nav4_skip_link_a11y_1')) {
+        onBeforeNavigate === null || onBeforeNavigate === void 0 || onBeforeNavigate();
+      }
+      (0, _focusElement.focusElement)(target);
     }
 
-    /**
-     * Internal slots can attach an `onBeforeNavigate` callback.
-     *
-     * Side nav uses this to ensure it is expanded.
-     */
-    onBeforeNavigate === null || onBeforeNavigate === void 0 || onBeforeNavigate();
-    focusElement(target);
-
     /**
      * We should look into removing this, or only calling it in specific cases.
      *
@@ -106,7 +73,7 @@ var SkipLink = exports.SkipLink = function SkipLink(_ref) {
      * E.g. jumping to main / aside it makes sense to look at the start of the content.
      */
     window.scrollTo(0, 0);
-  }, [id, onBeforeNavigate]);
+  }, [id, onBeforeNavigate, navigate]);
   return /*#__PURE__*/_react.default.createElement("li", {
     className: (0, _runtime.ax)([styles.skipLinkListItem, (0, _platformFeatureFlags.fg)('platform_dst_nav4_skip_link_a11y_1') && styles.skipLinkListItemNew])
   }, /*#__PURE__*/_react.default.createElement(_compiled.Anchor
@@ -118,6 +85,6 @@ var SkipLink = exports.SkipLink = function SkipLink(_ref) {
    */, {
     tabIndex: 0,
     href: href,
-    onClick: onClick
+    onClick: handleClick
   }, children));
 };

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

@@ -17,6 +17,7 @@ var _reactDom = require("react-dom");
 var _new = _interopRequireDefault(require("@atlaskit/button/new"));
 var _mergeRefs = _interopRequireDefault(require("@atlaskit/ds-lib/merge-refs"));
 var _popup = _interopRequireDefault(require("@atlaskit/popup"));
+var _focusElement = require("./focus-element");
 var _skipLink = require("./skip-link");
 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); }
 var contentStyles = {
@@ -98,13 +99,34 @@ 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.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) {
+              (0, _focusElement.focusElement)(target);
+            }
           }
         }, label);
       })));

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

@@ -11,14 +11,15 @@ var _skipLinksContext = require("./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.
  */
 var useSkipLinkInternal = exports.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 = (0, _react.useContext)(_skipLinksContext.SkipLinksContext),
     registerSkipLink = _useContext.registerSkipLink,
@@ -36,10 +37,11 @@ var useSkipLinkInternal = exports.useSkipLinkInternal = function useSkipLinkInte
       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/cjs/ui/page-layout/side-nav/side-nav.js

@@ -20,6 +20,7 @@ var _analyticsNext = require("@atlaskit/analytics-next");
 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");
 var _responsive = require("@atlaskit/primitives/responsive");
 var _useSkipLinkInternal = require("../../../context/skip-links/use-skip-link-internal");
@@ -114,28 +115,38 @@ function SideNavInternal(_ref) {
   var id = (0, _useLayoutId.useLayoutId)({
     providedId: providedId
   });
-  var expandSideNav = (0, _useExpandSideNav.useExpandSideNav)({
+  var expandAndFocusSideNav = (0, _useExpandSideNav.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 = (0, _react.useCallback)(function () {
     (0, _reactDom.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]);
   (0, _useSkipLinkInternal.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: (0, _platformFeatureFlags.fg)('platform_dst_nav4_skip_link_a11y_1') ? expandAndFocusSideNav : undefined,
+    onBeforeNavigate: (0, _platformFeatureFlags.fg)('platform_dst_nav4_skip_link_a11y_1') ? undefined : synchronouslyExpandSideNav
   });
   var sideNavState = (0, _react.useContext)(_sideNavVisibilityState.SideNavVisibilityState);
   var setSideNavState = (0, _react.useContext)(_setSideNavVisibilityState.SetSideNavVisibilityState);

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

@@ -5,7 +5,61 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.useExpandSideNav = useExpandSideNav;
 var _react = require("react");
+var _bindEventListener = require("bind-event-listener");
+var _reactDom = require("react-dom");
+var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
 var _setSideNavVisibilityState = require("./set-side-nav-visibility-state");
+var _useSideNavRef = require("./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
+     */
+    (0, _bindEventListener.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__
  *
@@ -20,48 +74,60 @@ function useExpandSideNav() {
     _ref$trigger = _ref.trigger,
     trigger = _ref$trigger === void 0 ? 'programmatic' : _ref$trigger;
   var setSideNavState = (0, _react.useContext)(_setSideNavVisibilityState.SetSideNavVisibilityState);
+  var sideNavRef = (0, _useSideNavRef.useSideNavRef)();
   var expandSideNav = (0, _react.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) && (0, _platformFeatureFlags.fg)('platform_dst_nav4_skip_link_a11y_1')) {
+      (0, _reactDom.flushSync)(runUpdate);
+      var sideNavElement = sideNavRef.current;
+      if (sideNavElement) {
+        focusFirstNavItem(sideNavElement);
+      }
+    } else {
+      runUpdate();
     }
-  }, [setSideNavState, trigger]);
+  }, [setSideNavState, sideNavRef, trigger]);
   return expandSideNav;
 }

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

@@ -5,7 +5,10 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.useToggleSideNav = useToggleSideNav;
 var _react = require("react");
+var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
 var _setSideNavVisibilityState = require("./set-side-nav-visibility-state");
+var _sideNavVisibilityState = require("./side-nav-visibility-state");
+var _useExpandSideNav = require("./use-expand-side-nav");
 /**
  * __useToggleSideNav__
  *
@@ -20,10 +23,37 @@ function useToggleSideNav() {
     _ref$trigger = _ref.trigger,
     trigger = _ref$trigger === void 0 ? 'programmatic' : _ref$trigger;
   var setSideNavState = (0, _react.useContext)(_setSideNavVisibilityState.SetSideNavVisibilityState);
+  var sideNavState = (0, _react.useContext)(_sideNavVisibilityState.SideNavVisibilityState);
+  var expandSideNav = (0, _useExpandSideNav.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 = (0, _react.useCallback)(function () {
     var _window$matchMedia = window.matchMedia('(min-width: 64rem)'),
-      matches = _window$matchMedia.matches;
-    if (matches) {
+      isDesktop = _window$matchMedia.matches;
+    if ((0, _platformFeatureFlags.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
@@ -52,6 +82,6 @@ function useToggleSideNav() {
         };
       });
     }
-  }, [setSideNavState, trigger]);
+  }, [expandSideNav, isCollapsedOnDesktop, isCollapsedOnMobile, setSideNavState, trigger]);
   return toggleSideNav;
 }

package/dist/es2019/components/skip-links/focus-element.js

@@ -0,0 +1,49 @@
+import { bind } from 'bind-event-listener';
+
+/**
+ * Used for moving focus to the corresponding slot or custom target after clicking on a skip link.
+ */
+export function focusElement(element) {
+  /**
+   * 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.
+   */
+  element.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(element, {
+    type: 'blur',
+    listener() {
+      element.removeAttribute('tabindex');
+    },
+    options: {
+      // Using a one-time listener so it cleans itself up
+      once: true
+    }
+  });
+
+  /**
+   * Move focus to the slot or custom target.
+   *
+   * Calling `.focus()` will also scroll the element into view:
+   * https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus
+   */
+  element.focus({
+    // Forces the focus ring to appear after moving focus to the slot
+    // https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#focusvisible
+    // @ts-expect-error - new and not in types yet
+    focusVisible: true
+  });
+}