@atlaskit/drawer 13.1.0 → 13.2.0

package/dist/cjs/use-drawer-stack.js

@@ -0,0 +1,88 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = useDrawerStack;
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var _react = require("react");
+var _useLazyCallback = _interopRequireDefault(require("@atlaskit/ds-lib/use-lazy-callback"));
+var _usePreviousValue = _interopRequireDefault(require("@atlaskit/ds-lib/use-previous-value"));
+var _useStateRef3 = _interopRequireDefault(require("@atlaskit/ds-lib/use-state-ref"));
+/**
+ * **Major versions will not know about each other**
+ *
+ * An array holding references to all currently open drawers. This only works
+ * for drawers of the same major version, because the reference differs between
+ * majors (for example V13 will not know about any from V14).
+ *
+ * Adapted from `useModalStack` in `@atlaskit/modal-dialog`. The top-layer drawer
+ * path uses this to know its position in the stack so that only the foreground
+ * drawer renders a visible `::backdrop` (this avoids cumulative darkening for
+ * nested or stacked drawers). Unlike the modal version, the register is timed
+ * off `isOpen` rather than `@atlaskit/motion`'s `useExitingPersistence`: the
+ * `Dialog` primitive owns its own exit lifecycle, so the top-layer drawer needs
+ * no `ExitingPersistence` wrapper.
+ */
+var drawerStackRegister = [];
+/**
+ * Returns the position of the calling drawer in the drawer stack. A stack index
+ * of `0` is the foreground (top of the stack); higher numbers are further back.
+ */
+function useDrawerStack(_ref) {
+  var isOpen = _ref.isOpen,
+    onStackChange = _ref.onStackChange;
+  var _useStateRef = (0, _useStateRef3.default)(0),
+    _useStateRef2 = (0, _slicedToArray2.default)(_useStateRef, 2),
+    stackIndexRef = _useStateRef2[0],
+    setStackIndex = _useStateRef2[1];
+  var currentStackIndex = stackIndexRef.current;
+  var previousStackIndex = (0, _usePreviousValue.default)(stackIndexRef.current);
+
+  // Kept stable for the lifetime of the component so it can be the identity in
+  // the shared register. This is why it is a lazy callback and not a
+  // useMemo/useCallback value.
+  var updateStack = (0, _useLazyCallback.default)(function () {
+    var newStackIndex = drawerStackRegister.indexOf(updateStack);
+    // Read from the ref rather than state: this closure only ever sees the
+    // initial state value.
+    if (stackIndexRef.current !== newStackIndex) {
+      setStackIndex(newStackIndex);
+      stackIndexRef.current = newStackIndex;
+    }
+  });
+  (0, _react.useEffect)(function () {
+    if (!isOpen) {
+      return;
+    }
+    // Opening: join the front of the register (the newest open drawer is the
+    // foreground at index 0), then notify every open drawer to recompute.
+    if (drawerStackRegister.indexOf(updateStack) === -1) {
+      drawerStackRegister.unshift(updateStack);
+    }
+    drawerStackRegister.forEach(function (callback) {
+      return callback();
+    });
+    return function () {
+      // Closing or unmounting: leave the register and notify the rest.
+      var index = drawerStackRegister.indexOf(updateStack);
+      if (index !== -1) {
+        drawerStackRegister.splice(index, 1);
+      }
+      drawerStackRegister.forEach(function (callback) {
+        return callback();
+      });
+    };
+  }, [isOpen, updateStack]);
+  (0, _react.useEffect)(function () {
+    if (previousStackIndex === undefined) {
+      // Initial render: nothing to notify about.
+      return;
+    }
+    if (previousStackIndex !== currentStackIndex) {
+      onStackChange === null || onStackChange === void 0 || onStackChange(currentStackIndex);
+    }
+  }, [onStackChange, previousStackIndex, currentStackIndex]);
+  return currentStackIndex;
+}

package/dist/es2019/drawer-panel/drawer-content.js

@@ -5,6 +5,7 @@ import { ax, ix } from "@compiled/react/runtime";
 import { forwardRef, useEffect, useRef, useState } from 'react';
 import ScrollLock from 'react-scrolllock';
 import { mergeRefs } from 'use-callback-ref';
+import { fg } from '@atlaskit/platform-feature-flags';
 import { useEnsureIsInsideDrawer } from '../use-ensure-is-inside-drawer';
 import usePreventProgrammaticScroll from './hooks/use-prevent-programmatic-scroll';
 const styles = {
@@ -48,8 +49,16 @@ export const DrawerContent = ({
 }) => {
   useEnsureIsInsideDrawer();
   usePreventProgrammaticScroll();
-  return /*#__PURE__*/React.createElement(ScrollLock, null, /*#__PURE__*/React.createElement(DrawerContentBase, {
+  const content = /*#__PURE__*/React.createElement(DrawerContentBase, {
     scrollContentLabel: scrollContentLabel,
     xcss: xcss
-  }, children));
+  }, children);
+
+  // Under the top-layer flag, background scroll is handled by `DialogScrollLock`
+  // (rendered by `DrawerTopLayer`), so we skip `react-scrolllock` here to avoid
+  // double-locking the body. See the top-layer migration scroll decision.
+  if (fg('platform-dst-top-layer')) {
+    return content;
+  }
+  return /*#__PURE__*/React.createElement(ScrollLock, null, content);
 };

package/dist/es2019/drawer-panel/drawer-slide-in.js

@@ -0,0 +1,107 @@
+/**
+ * Off-screen transform per entry edge. A drawer slides in from the edge it is
+ * pinned to and exits back to the same edge (legacy `SlideIn` used
+ * `exitTo={enterFrom}`), so enter and exit are symmetric.
+ */
+const HIDDEN_TRANSFORM = {
+  left: 'translateX(-100%)',
+  right: 'translateX(100%)',
+  top: 'translateY(-100%)',
+  bottom: 'translateY(100%)'
+};
+
+// Match the legacy `CustomSlideIn`: `duration="small"` (100ms) on enter,
+// `small * 0.5` (50ms) on exit, `ease-out` timing. Drawer slides with no panel
+// fade (`fade="none"`); only the backdrop fades.
+const ENTER_MS = 100;
+const EXIT_MS = 50;
+const EASE = 'cubic-bezier(0.2,0,0,1)'; // @atlaskit/motion `easeOut`
+
+/**
+ * Builds the slide CSS for a single entry edge, scoped to
+ * `[data-ds-dialog-drawer-slide-{from}]` (the `Dialog` primitive stamps
+ * `data-ds-dialog-{name}` on the `<dialog>` element).
+ *
+ * - base selector  → hidden/exit state + exit duration
+ * - `[open]`        → visible state + enter duration
+ * - `@starting-style` → initial (pre-paint) state so the entry transition runs
+ *
+ * The `::backdrop` fades its blanket colour in step with the panel. Stacked
+ * drawers hide their backdrop via the `Dialog` `shouldHideBackdrop` prop (an
+ * ID-scoped `<style>` whose specificity beats this rule).
+ */
+function buildCss(name, hidden) {
+  const sel = `[data-ds-dialog-${name}]`;
+  return `
+${sel} {
+  transform: ${hidden};
+  transition:
+    transform ${EXIT_MS}ms ${EASE},
+    overlay ${EXIT_MS}ms allow-discrete,
+    display ${EXIT_MS}ms allow-discrete;
+}
+
+${sel}[open] {
+  transform: none;
+  transition-duration: ${ENTER_MS}ms;
+}
+
+@starting-style {
+  ${sel}[open] {
+    transform: ${hidden};
+  }
+}
+
+${sel}::backdrop {
+  background-color: transparent;
+  transition:
+    background-color ${EXIT_MS}ms ${EASE},
+    overlay ${EXIT_MS}ms allow-discrete,
+    display ${EXIT_MS}ms allow-discrete;
+}
+
+${sel}[open]::backdrop {
+  background-color: var(--ds-blanket, #050C1F75);
+  transition-duration: ${ENTER_MS}ms;
+}
+
+@starting-style {
+  ${sel}[open]::backdrop {
+    background-color: transparent;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  ${sel},
+  ${sel}[open],
+  ${sel}::backdrop,
+  ${sel}[open]::backdrop {
+    transition-duration: 0s;
+  }
+}
+`;
+}
+/**
+ * Directional slide animation for the top-layer `Drawer`, passed to the
+ * `Dialog` primitive's `animate` prop. Local to `@atlaskit/drawer` (not a
+ * shared top-layer preset). The panel slides in from its pinned viewport edge
+ * while the `::backdrop` fades.
+ *
+ * @example
+ * ```tsx
+ * <Dialog animate={drawerSlideIn({ from: 'left' })} isOpen={isOpen} onClose={onClose} label="...">
+ *   ...
+ * </Dialog>
+ * ```
+ */
+export function drawerSlideIn({
+  from = 'left'
+} = {}) {
+  const name = `drawer-slide-${from}`;
+  return {
+    name,
+    css: buildCss(name, HIDDEN_TRANSFORM[from]),
+    enterDurationMs: ENTER_MS,
+    exitDurationMs: EXIT_MS
+  };
+}

package/dist/es2019/drawer-panel/drawer-top-layer.compiled.css

@@ -0,0 +1,8 @@
+._18m915vq{overflow-y:hidden}
+._1bsb1osq{width:100%}
+._1e0c1txw{display:flex}
+._1q1l1bhr{--ds-elevation-surface-current:var(--ds-surface-overlay,#fff)}
+._1reo15vq{overflow-x:hidden}
+._4t3i1osq{height:100%}
+._bfhk1bhr{background-color:var(--ds-surface-overlay,#fff)}
+._ect4ttxp{font-family:var(--ds-font-family-body,"Atlassian Sans",ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI",Ubuntu,"Helvetica Neue",sans-serif)}

package/dist/es2019/drawer-panel/drawer-top-layer.js

@@ -0,0 +1,238 @@
+/* drawer-top-layer.tsx generated by @compiled/babel-plugin v0.39.1 */
+import _extends from "@babel/runtime/helpers/extends";
+import "./drawer-top-layer.compiled.css";
+import * as React from 'react';
+import { ax, ix } from "@compiled/react/runtime";
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { bind } from 'bind-event-listener';
+import { usePlatformLeafEventHandler } from '@atlaskit/analytics-next/usePlatformLeafEventHandler';
+import { createCloseEvent, Dialog } from '@atlaskit/top-layer/dialog';
+import { DialogScrollLock } from '@atlaskit/top-layer/dialog-scroll-lock';
+import { EnsureIsInsideDrawerContext } from '../ensure-is-inside-drawer-context';
+import { OnCloseContext } from '../on-close-context';
+import useDrawerStack from '../use-drawer-stack';
+import { drawerSlideIn } from './drawer-slide-in';
+const LOCAL_CURRENT_SURFACE_CSS_VAR = '--ds-elevation-surface-current';
+const styles = {
+  surface: "_1reo15vq _18m915vq _1e0c1txw _1bsb1osq _4t3i1osq _bfhk1bhr _1q1l1bhr _ect4ttxp"
+};
+
+// Width presets mirror the legacy `DrawerPanel`. Applied to the `<dialog>` (the
+// sized, edge-pinned element) and clamped to the viewport for mobile safety.
+const WIDTH_MAP = {
+  narrow: '360px',
+  medium: '480px',
+  wide: '600px',
+  extended: '95vw',
+  full: '100vw'
+};
+
+/**
+ * Resolve the native `<dialog>` accessible name props. Prefer the consumer's
+ * `label`, then their `titleId`. If neither is supplied (legacy allowed this),
+ * fall back to a generic name so the dialog is never unlabelled. Note:
+ * `@atlaskit/drawer` has no i18n setup, so this fallback is English only;
+ * consumers should pass a localised `label` or `titleId`.
+ */
+function getAccessibleName({
+  label,
+  titleId
+}) {
+  if (label) {
+    return {
+      label
+    };
+  }
+  if (titleId) {
+    return {
+      labelledBy: titleId
+    };
+  }
+  return {
+    label: 'Drawer'
+  };
+}
+
+/**
+ * **DrawerTopLayer**
+ *
+ * Top-layer (`platform-dst-top-layer`) implementation of `Drawer`. Renders a
+ * native `<dialog>` via `@atlaskit/top-layer`, replacing Portal, Blanket,
+ * react-focus-lock, react-scrolllock and `@atlaskit/layering` with native
+ * modality, `::backdrop`, focus trap and return, and `DialogScrollLock`.
+ *
+ * The `Dialog` primitive owns the entry and exit animation lifecycle (it keeps
+ * the host element mounted through the exit transition, then fires
+ * `onExitFinish`), so no `ExitingPersistence` wrapper is needed: the drawer
+ * renders `<Dialog isOpen={isOpen}>` directly. `useDrawerStack` tracks stack
+ * depth so only the foreground drawer shows a `::backdrop`.
+ *
+ * `isFocusLockEnabled` is intentionally unsupported: a native modal `<dialog>`
+ * always traps focus, so `isFocusLockEnabled={false}` is a no-op under this gate.
+ */
+export function DrawerTopLayer({
+  width = 'narrow',
+  isOpen,
+  shouldReturnFocus = true,
+  onKeyDown,
+  testId,
+  children,
+  onClose,
+  onCloseComplete,
+  onOpenComplete,
+  label,
+  titleId,
+  enterFrom = 'left'
+}) {
+  const stackIndex = useDrawerStack({
+    isOpen
+  });
+
+  /**
+   * Points to the panel surface. Passed to `onOpenComplete` / `onCloseComplete`.
+   */
+  const contentRef = useRef(null);
+  // Cache the last content element so `onCloseComplete` still receives a node
+  // after children unmount (with reduced motion `contentRef` can clear before
+  // `onExitFinish` fires).
+  const lastContentElRef = useRef(null);
+  // Callback ref runs at commit (not during render), so both refs stay
+  // populated without a render-time side effect. `lastContentElRef` only
+  // overwrites with a non-null node, preserving it across the unmount.
+  const setContentEl = useCallback(el => {
+    contentRef.current = el;
+    if (el) {
+      lastContentElRef.current = el;
+    }
+  }, []);
+
+  // Analytics-wrapped close handlers, one per legacy trigger.
+  const handleEscapeClose = usePlatformLeafEventHandler({
+    fn: (evt, analyticsEvent) => onClose === null || onClose === void 0 ? void 0 : onClose(evt, analyticsEvent),
+    action: 'dismissed',
+    componentName: 'drawer',
+    packageName: "@atlaskit/drawer",
+    packageVersion: "13.1.1",
+    analyticsData: {
+      trigger: 'escKey'
+    }
+  });
+  const handleBlanketClose = usePlatformLeafEventHandler({
+    fn: (evt, analyticsEvent) => onClose === null || onClose === void 0 ? void 0 : onClose(evt, analyticsEvent),
+    action: 'dismissed',
+    componentName: 'drawer',
+    packageName: "@atlaskit/drawer",
+    packageVersion: "13.1.1",
+    analyticsData: {
+      trigger: 'blanket'
+    }
+  });
+  const handleBackButtonClose = usePlatformLeafEventHandler({
+    fn: (evt, analyticsEvent) => onClose === null || onClose === void 0 ? void 0 : onClose(evt, analyticsEvent),
+    action: 'dismissed',
+    componentName: 'drawer',
+    packageName: "@atlaskit/drawer",
+    packageVersion: "13.1.1",
+    analyticsData: {
+      trigger: 'backButton'
+    }
+  });
+
+  // Bridge the Dialog primitive's `onClose({ reason })` to the legacy
+  // `onClose(event, analyticsEvent)` contract via a synthetic event. Drawer
+  // has no `shouldCloseOn*` props, so both reasons always forward.
+  const handleDialogClose = useCallback(({
+    reason
+  }) => {
+    const event = createCloseEvent({
+      reason
+    });
+    if (reason === 'escape') {
+      handleEscapeClose(event);
+    } else {
+      handleBlanketClose(event);
+    }
+  }, [handleEscapeClose, handleBlanketClose]);
+
+  // Mirror the legacy window `keydown` listener so `onKeyDown` still fires
+  // while the drawer is open.
+  const handleKeyDown = useCallback(evt => {
+    onKeyDown === null || onKeyDown === void 0 ? void 0 : onKeyDown(evt);
+  }, [onKeyDown]);
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+    return bind(window, {
+      type: 'keydown',
+      listener: handleKeyDown
+    });
+  }, [isOpen, handleKeyDown]);
+
+  // `onOpenComplete` once the entry animation settles (via `Dialog`'s
+  // `onEnterFinish`, which the underlying hook fires for animated,
+  // non-animated and reduced-motion paths).
+  const handleEnterFinish = useCallback(() => {
+    onOpenComplete === null || onOpenComplete === void 0 ? void 0 : onOpenComplete(contentRef.current);
+  }, [onOpenComplete]);
+
+  // `onCloseComplete` once the exit animation settles (via `Dialog`'s
+  // `onExitFinish`). This is also where a custom `shouldReturnFocus={ref}` is
+  // honoured: native `<dialog>` restores focus to the trigger at the start of
+  // close, so the consumer's ref is focused now that the exit is done.
+  // `shouldReturnFocus={false}` is a documented best-effort limitation; native
+  // always restores focus to the trigger.
+  const handleExitFinish = useCallback(() => {
+    var _contentRef$current;
+    onCloseComplete === null || onCloseComplete === void 0 ? void 0 : onCloseComplete((_contentRef$current = contentRef.current) !== null && _contentRef$current !== void 0 ? _contentRef$current : lastContentElRef.current);
+    lastContentElRef.current = null;
+    if (typeof shouldReturnFocus === 'object' && shouldReturnFocus !== null && shouldReturnFocus !== void 0 && shouldReturnFocus.current) {
+      shouldReturnFocus.current.focus();
+    }
+  }, [onCloseComplete, shouldReturnFocus]);
+
+  // Pin the `<dialog>` full-height to the inline-start edge (overriding the
+  // primitive's centred `margin: auto`); width from the preset, clamped to the
+  // viewport. `enterFrom` only drives the slide animation, not the pin edge;
+  // it matches the legacy panel, which always pins `inset-inline-start`.
+  const dialogStyle = {
+    margin: 0,
+    insetBlockStart: 0,
+    insetInlineStart: 0,
+    insetInlineEnd: 'auto',
+    height: '100dvh',
+    maxHeight: '100dvh',
+    width: `min(${WIDTH_MAP[width]}, 100vw)`
+  };
+
+  // Memoized so the preset object (and its CSS string) is rebuilt only when
+  // `enterFrom` changes, not on every render.
+  const animate = useMemo(() => drawerSlideIn({
+    from: enterFrom
+  }), [enterFrom]);
+  const accessibleName = getAccessibleName({
+    label,
+    titleId
+  });
+  return /*#__PURE__*/React.createElement(Dialog, _extends({
+    isOpen: isOpen,
+    onClose: handleDialogClose,
+    onEnterFinish: handleEnterFinish,
+    onExitFinish: handleExitFinish,
+    animate: animate,
+    shouldHideBackdrop: stackIndex > 0,
+    testId: testId
+  }, accessibleName, {
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/enforce-style-prop
+    style: dialogStyle
+  }), /*#__PURE__*/React.createElement(DialogScrollLock, {
+    isOpen: true
+  }), /*#__PURE__*/React.createElement("div", {
+    ref: setContentEl,
+    className: ax([styles.surface])
+  }, /*#__PURE__*/React.createElement(EnsureIsInsideDrawerContext.Provider, {
+    value: true
+  }, /*#__PURE__*/React.createElement(OnCloseContext.Provider, {
+    value: handleBackButtonClose
+  }, children))));
+}

package/dist/es2019/drawer-panel/hooks/use-prevent-programmatic-scroll.js

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useLayoutEffect, useState } from 'react';
 import { bind } from 'bind-event-listener';
+import { fg } from '@atlaskit/platform-feature-flags';
 
 /**
  * Returns how far the body is scrolled from the top of the viewport.
@@ -37,6 +38,11 @@ export default function usePreventProgrammaticScroll() {
     }
   }, [scrollTopOffset]);
   useEffect(() => {
+    // The top-layer drawer relies on native modality + `DialogScrollLock`; the
+    // programmatic-scroll guard is intentionally dropped under the flag.
+    if (fg('platform-dst-top-layer')) {
+      return;
+    }
     return bind(window, {
       type: 'scroll',
       listener: onWindowScroll

package/dist/es2019/drawer.js

@@ -4,9 +4,11 @@ import React, { useCallback, useEffect } from 'react';
 import { canUseDOM } from 'exenv';
 import { usePlatformLeafEventHandler } from '@atlaskit/analytics-next';
 import { Layering, useCloseOnEscapePress } from '@atlaskit/layering';
+import { fg } from '@atlaskit/platform-feature-flags';
 import Portal from '@atlaskit/portal';
 import Blanket from './blanket';
 import { DrawerPanel } from './drawer-panel/drawer-panel';
+import { DrawerTopLayer } from './drawer-panel/drawer-top-layer';
 // escape close manager for layering
 const EscapeCloseManager = ({
   onClose
@@ -20,17 +22,7 @@ const EscapeCloseManager = ({
   });
   return /*#__PURE__*/React.createElement("span", null);
 };
-
-/**
- * __Drawer__
- *
- * A drawer is a panel that slides in from the left side of the screen.
- *
- * - [Examples](https://atlassian.design/components/drawer/examples)
- * - [Code](https://atlassian.design/components/drawer/code)
- * - [Usage](https://atlassian.design/components/drawer/usage)
- */
-export const Drawer = ({
+const DrawerBase = ({
   width = 'narrow',
   isOpen,
   isFocusLockEnabled = true,
@@ -52,7 +44,7 @@ export const Drawer = ({
     action: 'dismissed',
     componentName: 'drawer',
     packageName: "@atlaskit/drawer",
-    packageVersion: "13.0.1",
+    packageVersion: "13.1.1",
     analyticsData: {
       trigger: 'escKey'
     }
@@ -73,7 +65,7 @@ export const Drawer = ({
     action: 'dismissed',
     componentName: 'drawer',
     packageName: "@atlaskit/drawer",
-    packageVersion: "13.0.1",
+    packageVersion: "13.1.1",
     analyticsData: {
       trigger: 'blanket'
     }
@@ -83,7 +75,7 @@ export const Drawer = ({
     action: 'dismissed',
     componentName: 'drawer',
     packageName: "@atlaskit/drawer",
-    packageVersion: "13.0.1",
+    packageVersion: "13.1.1",
     analyticsData: {
       trigger: 'backButton'
     }
@@ -116,4 +108,23 @@ export const Drawer = ({
   }, children, /*#__PURE__*/React.createElement(EscapeCloseManager, {
     onClose: handleClose
   })) : children));
+};
+
+/**
+ * __Drawer__
+ *
+ * A drawer is a panel that slides in from the left side of the screen.
+ *
+ * - [Examples](https://atlassian.design/components/drawer/examples)
+ * - [Code](https://atlassian.design/components/drawer/code)
+ * - [Usage](https://atlassian.design/components/drawer/usage)
+ */
+export const Drawer = props => {
+  if (fg('platform-dst-top-layer')) {
+    // eslint-disable-next-line @repo/internal/react/no-unsafe-spread-props -- internal implementation component takes the same DrawerProps
+    return /*#__PURE__*/React.createElement(DrawerTopLayer, props);
+  }
+
+  // eslint-disable-next-line @repo/internal/react/no-unsafe-spread-props -- internal implementation component takes the same DrawerProps
+  return /*#__PURE__*/React.createElement(DrawerBase, props);
 };

package/dist/es2019/use-drawer-stack.js

@@ -0,0 +1,75 @@
+import { useEffect } from 'react';
+import useLazyCallback from '@atlaskit/ds-lib/use-lazy-callback';
+import usePreviousValue from '@atlaskit/ds-lib/use-previous-value';
+import useStateRef from '@atlaskit/ds-lib/use-state-ref';
+
+/**
+ * **Major versions will not know about each other**
+ *
+ * An array holding references to all currently open drawers. This only works
+ * for drawers of the same major version, because the reference differs between
+ * majors (for example V13 will not know about any from V14).
+ *
+ * Adapted from `useModalStack` in `@atlaskit/modal-dialog`. The top-layer drawer
+ * path uses this to know its position in the stack so that only the foreground
+ * drawer renders a visible `::backdrop` (this avoids cumulative darkening for
+ * nested or stacked drawers). Unlike the modal version, the register is timed
+ * off `isOpen` rather than `@atlaskit/motion`'s `useExitingPersistence`: the
+ * `Dialog` primitive owns its own exit lifecycle, so the top-layer drawer needs
+ * no `ExitingPersistence` wrapper.
+ */
+const drawerStackRegister = [];
+/**
+ * Returns the position of the calling drawer in the drawer stack. A stack index
+ * of `0` is the foreground (top of the stack); higher numbers are further back.
+ */
+export default function useDrawerStack({
+  isOpen,
+  onStackChange
+}) {
+  const [stackIndexRef, setStackIndex] = useStateRef(0);
+  const currentStackIndex = stackIndexRef.current;
+  const previousStackIndex = usePreviousValue(stackIndexRef.current);
+
+  // Kept stable for the lifetime of the component so it can be the identity in
+  // the shared register. This is why it is a lazy callback and not a
+  // useMemo/useCallback value.
+  const updateStack = useLazyCallback(() => {
+    const newStackIndex = drawerStackRegister.indexOf(updateStack);
+    // Read from the ref rather than state: this closure only ever sees the
+    // initial state value.
+    if (stackIndexRef.current !== newStackIndex) {
+      setStackIndex(newStackIndex);
+      stackIndexRef.current = newStackIndex;
+    }
+  });
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+    // Opening: join the front of the register (the newest open drawer is the
+    // foreground at index 0), then notify every open drawer to recompute.
+    if (drawerStackRegister.indexOf(updateStack) === -1) {
+      drawerStackRegister.unshift(updateStack);
+    }
+    drawerStackRegister.forEach(callback => callback());
+    return () => {
+      // Closing or unmounting: leave the register and notify the rest.
+      const index = drawerStackRegister.indexOf(updateStack);
+      if (index !== -1) {
+        drawerStackRegister.splice(index, 1);
+      }
+      drawerStackRegister.forEach(callback => callback());
+    };
+  }, [isOpen, updateStack]);
+  useEffect(() => {
+    if (previousStackIndex === undefined) {
+      // Initial render: nothing to notify about.
+      return;
+    }
+    if (previousStackIndex !== currentStackIndex) {
+      onStackChange === null || onStackChange === void 0 ? void 0 : onStackChange(currentStackIndex);
+    }
+  }, [onStackChange, previousStackIndex, currentStackIndex]);
+  return currentStackIndex;
+}

package/dist/esm/drawer-panel/drawer-content.js

@@ -6,6 +6,7 @@ import { ax, ix } from "@compiled/react/runtime";
 import { forwardRef, useEffect, useRef, useState } from 'react';
 import ScrollLock from 'react-scrolllock';
 import { mergeRefs } from 'use-callback-ref';
+import { fg } from '@atlaskit/platform-feature-flags';
 import { useEnsureIsInsideDrawer } from '../use-ensure-is-inside-drawer';
 import usePreventProgrammaticScroll from './hooks/use-prevent-programmatic-scroll';
 var styles = {
@@ -51,8 +52,16 @@ export var DrawerContent = function DrawerContent(_ref2) {
     xcss = _ref2.xcss;
   useEnsureIsInsideDrawer();
   usePreventProgrammaticScroll();
-  return /*#__PURE__*/React.createElement(ScrollLock, null, /*#__PURE__*/React.createElement(DrawerContentBase, {
+  var content = /*#__PURE__*/React.createElement(DrawerContentBase, {
     scrollContentLabel: scrollContentLabel,
     xcss: xcss
-  }, children));
+  }, children);
+
+  // Under the top-layer flag, background scroll is handled by `DialogScrollLock`
+  // (rendered by `DrawerTopLayer`), so we skip `react-scrolllock` here to avoid
+  // double-locking the body. See the top-layer migration scroll decision.
+  if (fg('platform-dst-top-layer')) {
+    return content;
+  }
+  return /*#__PURE__*/React.createElement(ScrollLock, null, content);
 };