@atlaskit/drawer 13.1.0 → 13.2.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @atlaskit/drawer
 
+## 13.2.0
+
+### Minor Changes
+
+- [`e297058763bc0`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/e297058763bc0) -
+  Add a top-layer rendering path for `Drawer` behind the `platform-dst-top-layer` feature gate. Some
+  focus-management and labelling props behave slightly differently on the native dialog path.
+
+### Patch Changes
+
+- Updated dependencies
+
+## 13.1.1
+
+### Patch Changes
+
+- [`820f00bd7db09`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/820f00bd7db09) -
+  Enable platform-dst-motion-uplift-button by default in constellation examples so button motion is
+  previewed in component demos. Docs/examples-only; no change to shipped component behaviour.
+
 ## 13.1.0
 
 ### Minor Changes

package/__tests__/playwright/top-layer-focus.spec.tsx

@@ -0,0 +1,148 @@
+import { expect, test } from '@af/integration-testing';
+
+/**
+ * Drawer: focus contract on the top-layer code path.
+ *
+ * The top-layer `Drawer` renders as a native modal `<dialog>` (via the
+ * `@atlaskit/top-layer` `Dialog` primitive). Per WCAG 2.4.3 (Focus Order) and
+ * the top-layer focus rules:
+ *
+ * 1. Initial focus moves to the first focusable element on open (or to the
+ *    element marked with the native HTML `autofocus` attribute when present).
+ * 2. Closing the drawer (Escape) restores focus to the trigger.
+ * 3. Tab / Shift+Tab cycle focus within the drawer (focus does not escape to
+ *    elements behind the inert modal surface).
+ *
+ * `Drawer` has no `autoFocus` ref prop (unlike `ModalDialog`); its consumer
+ * focus override is `shouldReturnFocus`, exercised in the top-layer
+ * `drawer.spec.tsx`.
+ *
+ * See: `platform/packages/design-system/top-layer/notes/architecture/focus.md`.
+ */
+
+const featureFlag = 'platform-dst-top-layer';
+
+test.describe('Drawer: top-layer focus contract', () => {
+	test('initial focus: focus moves to the first focusable element on open', async ({ page }) => {
+		await page.visitExample<typeof import('../../examples/98-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'drawer',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		await page.getByTestId('default-drawer-trigger').click();
+
+		const dialog = page.getByTestId('default-drawer');
+		await expect(dialog).toBeVisible();
+
+		// The first focusable inside the drawer is the sidebar close button.
+		await expect(page.getByTestId('DrawerCloseButton')).toBeFocused();
+	});
+
+	test('focus restoration: Escape restores focus to the trigger', async ({ page }) => {
+		await page.visitExample<typeof import('../../examples/98-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'drawer',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		const trigger = page.getByTestId('default-drawer-trigger');
+		await trigger.click();
+		await expect(page.getByTestId('default-drawer')).toBeVisible();
+
+		await page.keyboard.press('Escape');
+		await expect(page.getByTestId('default-drawer')).toBeHidden();
+		await expect(trigger).toBeFocused();
+	});
+
+	// WCAG 2.4.3 Focus Order + HTML `<dialog>` focusing steps
+	// (https://html.spec.whatwg.org/multipage/interactive-elements.html#dialog-focusing-steps).
+	// When a descendant of the dialog carries the native HTML `autofocus`
+	// attribute, focus must land on that element instead of the first
+	// focusable. This matches both `<dialog>.showModal()` and the WAI-ARIA APG
+	// Dialog pattern.
+	test('initial focus: native [autofocus] element wins over the first focusable element', async ({
+		page,
+	}) => {
+		await page.visitExample<typeof import('../../examples/98-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'drawer',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		await page.getByTestId('native-autofocus-drawer-trigger').click();
+
+		const dialog = page.getByTestId('native-autofocus-drawer');
+		await expect(dialog).toBeVisible();
+
+		// The first focusable inside the drawer is the sidebar close button, but
+		// the body input carries `autofocus`, so focus must land on the input.
+		await expect(page.getByTestId('native-autofocus-input')).toBeFocused();
+	});
+
+	test('focus movement: Tab cycles focus forward within the drawer', async ({ page }) => {
+		await page.visitExample<typeof import('../../examples/98-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'drawer',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		await page.getByTestId('multi-focusable-drawer-trigger').click();
+		const dialog = page.getByTestId('multi-focusable-drawer');
+		await expect(dialog).toBeVisible();
+
+		// Walk forward through every focusable element in the drawer and verify
+		// focus never escapes the dialog surface.
+		const focusables = [
+			page.getByTestId('DrawerCloseButton'),
+			page.getByTestId('focusable-1'),
+			page.getByTestId('focusable-2'),
+			page.getByTestId('focusable-3'),
+		];
+
+		for (const target of focusables) {
+			await expect(target).toBeFocused();
+			await page.keyboard.press('Tab');
+		}
+
+		// After cycling past the last focusable, focus must remain inside the
+		// drawer (focus wrap), never on a node behind it.
+		const activeWithinDialog = await dialog.evaluate(
+			(dialogElement) =>
+				document.activeElement !== null && dialogElement.contains(document.activeElement),
+		);
+		expect(activeWithinDialog).toBe(true);
+	});
+
+	test('focus movement: Shift+Tab cycles focus backward within the drawer', async ({ page }) => {
+		await page.visitExample<typeof import('../../examples/98-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'drawer',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		await page.getByTestId('multi-focusable-drawer-trigger').click();
+		const dialog = page.getByTestId('multi-focusable-drawer');
+		await expect(dialog).toBeVisible();
+		await expect(page.getByTestId('DrawerCloseButton')).toBeFocused();
+
+		// From the first focusable, Shift+Tab wraps to the last, then walks back
+		// up. Focus stays trapped within the drawer throughout.
+		const backwardOrder = [
+			page.getByTestId('focusable-3'),
+			page.getByTestId('focusable-2'),
+			page.getByTestId('focusable-1'),
+			page.getByTestId('DrawerCloseButton'),
+		];
+
+		for (const target of backwardOrder) {
+			await page.keyboard.press('Shift+Tab');
+			await expect(target).toBeFocused();
+		}
+	});
+});

package/compass.yml

@@ -0,0 +1,38 @@
+configVersion: 1
+id: ari:cloud:compass:a436116f-02ce-4520-8fbb-7301462a1674:component/c5751cc6-3513-4070-9deb-af31e86aed34/77224ba7-72d9-4d2b-a3f6-a78dcc8067ee
+name: '@atlaskit/drawer'
+ownerId: ari:cloud:identity::team/be19136e-6275-419f-be0c-fcee844b8684 # Design System Engineers
+labels:
+  - platform-code
+  - platform-afm
+typeId: OTHER
+fields:
+  tier: 4
+  lifecycle: Active
+  isMonorepoProject: true
+links:
+  - name: Root Repository
+    type: REPOSITORY
+    url: https://bitbucket.org/atlassian/atlassian-frontend-monorepo/src/master
+  - name: Slack Channel
+    type: CHAT_CHANNEL
+    url: https://atlassian.enterprise.slack.com/archives/CFJ9DU39U # #help-design-system
+  - name: Drawer
+    type: REPOSITORY
+    url: https://bitbucket.org/atlassian/atlassian-frontend-monorepo/src/master/platform/packages/design-system/drawer
+customFields:
+  - name: Department
+    type: text
+    value: Eng - Design System Fundamentals
+  - name: Technical Owner
+    type: user
+    value: ari:cloud:identity::user/557058:86a9b692-7997-49cb-9984-080801b1de91 # Jared Crowe
+  - name: Required Reviewers Opt In
+    type: boolean
+    value: true
+  - name: Reviewer Selection Mechanism
+    type: text
+    value: random(3)
+  - name: Required Reviewer Approvals
+    type: number
+    value: 1

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

@@ -14,6 +14,7 @@ var _runtime = require("@compiled/react/runtime");
 var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
 var _reactScrolllock = _interopRequireDefault(require("react-scrolllock"));
 var _useCallbackRef = require("use-callback-ref");
+var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
 var _useEnsureIsInsideDrawer = require("../use-ensure-is-inside-drawer");
 var _usePreventProgrammaticScroll = _interopRequireDefault(require("./hooks/use-prevent-programmatic-scroll"));
 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); }
@@ -60,8 +61,16 @@ var DrawerContent = exports.DrawerContent = function DrawerContent(_ref2) {
     xcss = _ref2.xcss;
   (0, _useEnsureIsInsideDrawer.useEnsureIsInsideDrawer)();
   (0, _usePreventProgrammaticScroll.default)();
-  return /*#__PURE__*/React.createElement(_reactScrolllock.default, 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 ((0, _platformFeatureFlags.fg)('platform-dst-top-layer')) {
+    return content;
+  }
+  return /*#__PURE__*/React.createElement(_reactScrolllock.default, null, content);
 };

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

@@ -0,0 +1,67 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.drawerSlideIn = drawerSlideIn;
+/**
+ * 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.
+ */
+var 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.
+var ENTER_MS = 100;
+var EXIT_MS = 50;
+var 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) {
+  var sel = "[data-ds-dialog-".concat(name, "]");
+  return "\n".concat(sel, " {\n  transform: ").concat(hidden, ";\n  transition:\n    transform ").concat(EXIT_MS, "ms ").concat(EASE, ",\n    overlay ").concat(EXIT_MS, "ms allow-discrete,\n    display ").concat(EXIT_MS, "ms allow-discrete;\n}\n\n").concat(sel, "[open] {\n  transform: none;\n  transition-duration: ").concat(ENTER_MS, "ms;\n}\n\n@starting-style {\n  ").concat(sel, "[open] {\n    transform: ").concat(hidden, ";\n  }\n}\n\n").concat(sel, "::backdrop {\n  background-color: transparent;\n  transition:\n    background-color ").concat(EXIT_MS, "ms ").concat(EASE, ",\n    overlay ").concat(EXIT_MS, "ms allow-discrete,\n    display ").concat(EXIT_MS, "ms allow-discrete;\n}\n\n").concat(sel, "[open]::backdrop {\n  background-color: var(--ds-blanket, #050C1F75);\n  transition-duration: ").concat(ENTER_MS, "ms;\n}\n\n@starting-style {\n  ").concat(sel, "[open]::backdrop {\n    background-color: transparent;\n  }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  ").concat(sel, ",\n  ").concat(sel, "[open],\n  ").concat(sel, "::backdrop,\n  ").concat(sel, "[open]::backdrop {\n    transition-duration: 0s;\n  }\n}\n");
+}
+/**
+ * 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>
+ * ```
+ */
+function drawerSlideIn() {
+  var _ref = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {},
+    _ref$from = _ref.from,
+    from = _ref$from === void 0 ? 'left' : _ref$from;
+  var name = "drawer-slide-".concat(from);
+  return {
+    name: name,
+    css: buildCss(name, HIDDEN_TRANSFORM[from]),
+    enterDurationMs: ENTER_MS,
+    exitDurationMs: EXIT_MS
+  };
+}

package/dist/cjs/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/cjs/drawer-panel/drawer-top-layer.js

@@ -0,0 +1,256 @@
+/* drawer-top-layer.tsx generated by @compiled/babel-plugin v0.39.1 */
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+var _typeof3 = require("@babel/runtime/helpers/typeof");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.DrawerTopLayer = DrawerTopLayer;
+require("./drawer-top-layer.compiled.css");
+var _react = _interopRequireWildcard(require("react"));
+var React = _react;
+var _runtime = require("@compiled/react/runtime");
+var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
+var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
+var _bindEventListener = require("bind-event-listener");
+var _usePlatformLeafEventHandler = require("@atlaskit/analytics-next/usePlatformLeafEventHandler");
+var _dialog = require("@atlaskit/top-layer/dialog");
+var _dialogScrollLock = require("@atlaskit/top-layer/dialog-scroll-lock");
+var _ensureIsInsideDrawerContext = require("../ensure-is-inside-drawer-context");
+var _onCloseContext = require("../on-close-context");
+var _useDrawerStack = _interopRequireDefault(require("../use-drawer-stack"));
+var _drawerSlideIn = require("./drawer-slide-in");
+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" != _typeof3(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 LOCAL_CURRENT_SURFACE_CSS_VAR = '--ds-elevation-surface-current';
+var 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.
+var 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(_ref) {
+  var label = _ref.label,
+    titleId = _ref.titleId;
+  if (label) {
+    return {
+      label: 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.
+ */
+function DrawerTopLayer(_ref2) {
+  var _ref2$width = _ref2.width,
+    width = _ref2$width === void 0 ? 'narrow' : _ref2$width,
+    isOpen = _ref2.isOpen,
+    _ref2$shouldReturnFoc = _ref2.shouldReturnFocus,
+    shouldReturnFocus = _ref2$shouldReturnFoc === void 0 ? true : _ref2$shouldReturnFoc,
+    onKeyDown = _ref2.onKeyDown,
+    testId = _ref2.testId,
+    children = _ref2.children,
+    onClose = _ref2.onClose,
+    onCloseComplete = _ref2.onCloseComplete,
+    onOpenComplete = _ref2.onOpenComplete,
+    label = _ref2.label,
+    titleId = _ref2.titleId,
+    _ref2$enterFrom = _ref2.enterFrom,
+    enterFrom = _ref2$enterFrom === void 0 ? 'left' : _ref2$enterFrom;
+  var stackIndex = (0, _useDrawerStack.default)({
+    isOpen: isOpen
+  });
+
+  /**
+   * Points to the panel surface. Passed to `onOpenComplete` / `onCloseComplete`.
+   */
+  var contentRef = (0, _react.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).
+  var lastContentElRef = (0, _react.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.
+  var setContentEl = (0, _react.useCallback)(function (el) {
+    contentRef.current = el;
+    if (el) {
+      lastContentElRef.current = el;
+    }
+  }, []);
+
+  // Analytics-wrapped close handlers, one per legacy trigger.
+  var handleEscapeClose = (0, _usePlatformLeafEventHandler.usePlatformLeafEventHandler)({
+    fn: function fn(evt, analyticsEvent) {
+      return onClose === null || onClose === void 0 ? void 0 : onClose(evt, analyticsEvent);
+    },
+    action: 'dismissed',
+    componentName: 'drawer',
+    packageName: "@atlaskit/drawer",
+    packageVersion: "13.1.1",
+    analyticsData: {
+      trigger: 'escKey'
+    }
+  });
+  var handleBlanketClose = (0, _usePlatformLeafEventHandler.usePlatformLeafEventHandler)({
+    fn: function fn(evt, analyticsEvent) {
+      return onClose === null || onClose === void 0 ? void 0 : onClose(evt, analyticsEvent);
+    },
+    action: 'dismissed',
+    componentName: 'drawer',
+    packageName: "@atlaskit/drawer",
+    packageVersion: "13.1.1",
+    analyticsData: {
+      trigger: 'blanket'
+    }
+  });
+  var handleBackButtonClose = (0, _usePlatformLeafEventHandler.usePlatformLeafEventHandler)({
+    fn: function fn(evt, analyticsEvent) {
+      return 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.
+  var handleDialogClose = (0, _react.useCallback)(function (_ref3) {
+    var reason = _ref3.reason;
+    var event = (0, _dialog.createCloseEvent)({
+      reason: 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.
+  var handleKeyDown = (0, _react.useCallback)(function (evt) {
+    onKeyDown === null || onKeyDown === void 0 || onKeyDown(evt);
+  }, [onKeyDown]);
+  (0, _react.useEffect)(function () {
+    if (!isOpen) {
+      return;
+    }
+    return (0, _bindEventListener.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).
+  var handleEnterFinish = (0, _react.useCallback)(function () {
+    onOpenComplete === null || onOpenComplete === 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.
+  var handleExitFinish = (0, _react.useCallback)(function () {
+    var _contentRef$current;
+    onCloseComplete === null || onCloseComplete === void 0 || onCloseComplete((_contentRef$current = contentRef.current) !== null && _contentRef$current !== void 0 ? _contentRef$current : lastContentElRef.current);
+    lastContentElRef.current = null;
+    if ((0, _typeof2.default)(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`.
+  var dialogStyle = {
+    margin: 0,
+    insetBlockStart: 0,
+    insetInlineStart: 0,
+    insetInlineEnd: 'auto',
+    height: '100dvh',
+    maxHeight: '100dvh',
+    width: "min(".concat(WIDTH_MAP[width], ", 100vw)")
+  };
+
+  // Memoized so the preset object (and its CSS string) is rebuilt only when
+  // `enterFrom` changes, not on every render.
+  var animate = (0, _react.useMemo)(function () {
+    return (0, _drawerSlideIn.drawerSlideIn)({
+      from: enterFrom
+    });
+  }, [enterFrom]);
+  var accessibleName = getAccessibleName({
+    label: label,
+    titleId: titleId
+  });
+  return /*#__PURE__*/React.createElement(_dialog.Dialog, (0, _extends2.default)({
+    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.DialogScrollLock, {
+    isOpen: true
+  }), /*#__PURE__*/React.createElement("div", {
+    ref: setContentEl,
+    className: (0, _runtime.ax)([styles.surface])
+  }, /*#__PURE__*/React.createElement(_ensureIsInsideDrawerContext.EnsureIsInsideDrawerContext.Provider, {
+    value: true
+  }, /*#__PURE__*/React.createElement(_onCloseContext.OnCloseContext.Provider, {
+    value: handleBackButtonClose
+  }, children))));
+}

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

@@ -8,6 +8,7 @@ exports.default = usePreventProgrammaticScroll;
 var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
 var _react = require("react");
 var _bindEventListener = require("bind-event-listener");
+var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
 /**
  * Returns how far the body is scrolled from the top of the viewport.
  *
@@ -47,6 +48,11 @@ function usePreventProgrammaticScroll() {
     }
   }, [scrollTopOffset]);
   (0, _react.useEffect)(function () {
+    // The top-layer drawer relies on native modality + `DialogScrollLock`; the
+    // programmatic-scroll guard is intentionally dropped under the flag.
+    if ((0, _platformFeatureFlags.fg)('platform-dst-top-layer')) {
+      return;
+    }
     return (0, _bindEventListener.bind)(window, {
       type: 'scroll',
       listener: onWindowScroll

package/dist/cjs/drawer.js

@@ -10,9 +10,11 @@ var _react = _interopRequireWildcard(require("react"));
 var _exenv = require("exenv");
 var _analyticsNext = require("@atlaskit/analytics-next");
 var _layering = require("@atlaskit/layering");
+var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
 var _portal = _interopRequireDefault(require("@atlaskit/portal"));
 var _blanket = _interopRequireDefault(require("./blanket"));
 var _drawerPanel = require("./drawer-panel/drawer-panel");
+var _drawerTopLayer = require("./drawer-panel/drawer-top-layer");
 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); }
 /// <reference types="node" />
 /* eslint-disable @repo/internal/dom-events/no-unsafe-event-listeners */
@@ -29,17 +31,7 @@ var EscapeCloseManager = function EscapeCloseManager(_ref) {
   });
   return /*#__PURE__*/_react.default.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)
- */
-var Drawer = exports.Drawer = function Drawer(_ref2) {
+var DrawerBase = function DrawerBase(_ref2) {
   var _ref2$width = _ref2.width,
     width = _ref2$width === void 0 ? 'narrow' : _ref2$width,
     isOpen = _ref2.isOpen,
@@ -67,7 +59,7 @@ var Drawer = exports.Drawer = function Drawer(_ref2) {
     action: 'dismissed',
     componentName: 'drawer',
     packageName: "@atlaskit/drawer",
-    packageVersion: "13.0.1",
+    packageVersion: "13.1.1",
     analyticsData: {
       trigger: 'escKey'
     }
@@ -90,7 +82,7 @@ var Drawer = exports.Drawer = function Drawer(_ref2) {
     action: 'dismissed',
     componentName: 'drawer',
     packageName: "@atlaskit/drawer",
-    packageVersion: "13.0.1",
+    packageVersion: "13.1.1",
     analyticsData: {
       trigger: 'blanket'
     }
@@ -102,7 +94,7 @@ var Drawer = exports.Drawer = function Drawer(_ref2) {
     action: 'dismissed',
     componentName: 'drawer',
     packageName: "@atlaskit/drawer",
-    packageVersion: "13.0.1",
+    packageVersion: "13.1.1",
     analyticsData: {
       trigger: 'backButton'
     }
@@ -135,4 +127,23 @@ var Drawer = exports.Drawer = function Drawer(_ref2) {
   }, children, /*#__PURE__*/_react.default.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)
+ */
+var Drawer = exports.Drawer = function Drawer(props) {
+  if ((0, _platformFeatureFlags.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.default.createElement(_drawerTopLayer.DrawerTopLayer, props);
+  }
+
+  // eslint-disable-next-line @repo/internal/react/no-unsafe-spread-props -- internal implementation component takes the same DrawerProps
+  return /*#__PURE__*/_react.default.createElement(DrawerBase, props);
 };