@atlaskit/top-layer 0.12.0 → 0.12.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (156) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/dist/cjs/animations/presets.js +5 -5
  3. package/dist/cjs/dialog/create-close-event.js +1 -1
  4. package/dist/cjs/dialog/dialog-content.js +5 -5
  5. package/dist/cjs/entry-points/use-arrow-navigation.js +3 -2
  6. package/dist/cjs/internal/ensure-preset-styles.js +1 -1
  7. package/dist/cjs/internal/placement-to-position-area.js +43 -0
  8. package/dist/cjs/internal/placement-to-try-fallbacks.js +82 -0
  9. package/dist/cjs/internal/reduced-motion.js +1 -1
  10. package/dist/cjs/internal/resolve-placement.js +2 -2
  11. package/dist/cjs/internal/role-types.js +1 -1
  12. package/dist/cjs/internal/slot.js +3 -3
  13. package/dist/cjs/internal/use-anchor-position.js +33 -161
  14. package/dist/cjs/internal/use-animated-visibility.js +10 -10
  15. package/dist/cjs/internal/use-animation-preset.js +1 -1
  16. package/dist/cjs/internal/use-preset-styles.js +1 -1
  17. package/dist/cjs/internal/use-width-from-anchor.js +4 -4
  18. package/dist/cjs/popover/create-close-event.js +1 -1
  19. package/dist/cjs/popover/popover.js +3 -3
  20. package/dist/cjs/popup/popup-content.js +6 -6
  21. package/dist/cjs/popup/popup-context.js +2 -38
  22. package/dist/cjs/popup/popup-provider.js +15 -0
  23. package/dist/cjs/popup/popup-trigger-function.js +2 -2
  24. package/dist/cjs/popup/popup-trigger.js +2 -2
  25. package/dist/cjs/popup/popup.js +2 -2
  26. package/dist/cjs/popup/use-maybe-popup-context.js +17 -0
  27. package/dist/cjs/popup/use-popup-context.js +20 -0
  28. package/dist/cjs/testing/polyfill.js +8 -8
  29. package/dist/cjs/testing/to-be-visible.js +5 -5
  30. package/dist/cjs/use-arrow-navigation/index.js +3 -2
  31. package/dist/cjs/use-arrow-navigation/is-at-current-menu-level.js +94 -0
  32. package/dist/cjs/use-arrow-navigation/use-arrow-navigation.js +0 -82
  33. package/dist/cjs/use-simple-light-dismiss/index.js +3 -3
  34. package/dist/es2019/animations/presets.js +5 -5
  35. package/dist/es2019/dialog/create-close-event.js +1 -1
  36. package/dist/es2019/dialog/dialog-content.js +5 -5
  37. package/dist/es2019/entry-points/use-arrow-navigation.js +2 -1
  38. package/dist/es2019/internal/ensure-preset-styles.js +1 -1
  39. package/dist/es2019/internal/placement-to-position-area.js +40 -0
  40. package/dist/es2019/internal/placement-to-try-fallbacks.js +77 -0
  41. package/dist/es2019/internal/reduced-motion.js +1 -1
  42. package/dist/es2019/internal/resolve-placement.js +2 -2
  43. package/dist/es2019/internal/role-types.js +1 -1
  44. package/dist/es2019/internal/slot.js +3 -3
  45. package/dist/es2019/internal/use-anchor-position.js +15 -132
  46. package/dist/es2019/internal/use-animated-visibility.js +10 -10
  47. package/dist/es2019/internal/use-animation-preset.js +1 -1
  48. package/dist/es2019/internal/use-preset-styles.js +1 -1
  49. package/dist/es2019/internal/use-width-from-anchor.js +4 -4
  50. package/dist/es2019/popover/create-close-event.js +1 -1
  51. package/dist/es2019/popover/popover.js +3 -3
  52. package/dist/es2019/popup/popup-content.js +6 -5
  53. package/dist/es2019/popup/popup-context.js +2 -36
  54. package/dist/es2019/popup/popup-provider.js +10 -0
  55. package/dist/es2019/popup/popup-trigger-function.js +1 -1
  56. package/dist/es2019/popup/popup-trigger.js +2 -1
  57. package/dist/es2019/popup/popup.js +1 -1
  58. package/dist/es2019/popup/use-maybe-popup-context.js +12 -0
  59. package/dist/es2019/popup/use-popup-context.js +15 -0
  60. package/dist/es2019/testing/polyfill.js +8 -8
  61. package/dist/es2019/testing/to-be-visible.js +5 -5
  62. package/dist/es2019/use-arrow-navigation/index.js +2 -1
  63. package/dist/es2019/use-arrow-navigation/is-at-current-menu-level.js +88 -0
  64. package/dist/es2019/use-arrow-navigation/use-arrow-navigation.js +0 -81
  65. package/dist/es2019/use-simple-light-dismiss/index.js +3 -3
  66. package/dist/esm/animations/presets.js +5 -5
  67. package/dist/esm/dialog/create-close-event.js +1 -1
  68. package/dist/esm/dialog/dialog-content.js +5 -5
  69. package/dist/esm/entry-points/use-arrow-navigation.js +2 -1
  70. package/dist/esm/internal/ensure-preset-styles.js +1 -1
  71. package/dist/esm/internal/placement-to-position-area.js +38 -0
  72. package/dist/esm/internal/placement-to-try-fallbacks.js +76 -0
  73. package/dist/esm/internal/reduced-motion.js +1 -1
  74. package/dist/esm/internal/resolve-placement.js +2 -2
  75. package/dist/esm/internal/role-types.js +1 -1
  76. package/dist/esm/internal/slot.js +3 -3
  77. package/dist/esm/internal/use-anchor-position.js +31 -157
  78. package/dist/esm/internal/use-animated-visibility.js +10 -10
  79. package/dist/esm/internal/use-animation-preset.js +1 -1
  80. package/dist/esm/internal/use-preset-styles.js +1 -1
  81. package/dist/esm/internal/use-width-from-anchor.js +4 -4
  82. package/dist/esm/popover/create-close-event.js +1 -1
  83. package/dist/esm/popover/popover.js +3 -3
  84. package/dist/esm/popup/popup-content.js +6 -5
  85. package/dist/esm/popup/popup-context.js +2 -36
  86. package/dist/esm/popup/popup-provider.js +10 -0
  87. package/dist/esm/popup/popup-trigger-function.js +1 -1
  88. package/dist/esm/popup/popup-trigger.js +2 -1
  89. package/dist/esm/popup/popup.js +1 -1
  90. package/dist/esm/popup/use-maybe-popup-context.js +12 -0
  91. package/dist/esm/popup/use-popup-context.js +15 -0
  92. package/dist/esm/testing/polyfill.js +8 -8
  93. package/dist/esm/testing/to-be-visible.js +5 -5
  94. package/dist/esm/use-arrow-navigation/index.js +2 -1
  95. package/dist/esm/use-arrow-navigation/is-at-current-menu-level.js +88 -0
  96. package/dist/esm/use-arrow-navigation/use-arrow-navigation.js +0 -81
  97. package/dist/esm/use-simple-light-dismiss/index.js +3 -3
  98. package/dist/types/dialog/create-close-event.d.ts +1 -1
  99. package/dist/types/dialog/types.d.ts +8 -0
  100. package/dist/types/entry-points/use-arrow-navigation.d.ts +2 -1
  101. package/dist/types/internal/placement-to-position-area.d.ts +21 -0
  102. package/dist/types/internal/placement-to-try-fallbacks.d.ts +36 -0
  103. package/dist/types/internal/reduced-motion.d.ts +1 -1
  104. package/dist/types/internal/resolve-placement.d.ts +2 -2
  105. package/dist/types/internal/slot.d.ts +4 -4
  106. package/dist/types/internal/use-anchor-position.d.ts +0 -55
  107. package/dist/types/internal/use-animated-visibility.d.ts +3 -3
  108. package/dist/types/internal/use-animation-preset.d.ts +1 -1
  109. package/dist/types/internal/use-preset-styles.d.ts +1 -1
  110. package/dist/types/internal/use-width-from-anchor.d.ts +2 -2
  111. package/dist/types/popover/create-close-event.d.ts +1 -1
  112. package/dist/types/popover/popover.d.ts +1 -1
  113. package/dist/types/popup/popup-context.d.ts +2 -22
  114. package/dist/types/popup/popup-provider.d.ts +10 -0
  115. package/dist/types/popup/use-maybe-popup-context.d.ts +8 -0
  116. package/dist/types/popup/use-popup-context.d.ts +7 -0
  117. package/dist/types/testing/to-be-visible.d.ts +3 -3
  118. package/dist/types/use-arrow-navigation/index.d.ts +2 -1
  119. package/dist/types/use-arrow-navigation/is-at-current-menu-level.d.ts +48 -0
  120. package/dist/types/use-arrow-navigation/use-arrow-navigation.d.ts +0 -48
  121. package/dist/types/use-simple-light-dismiss/index.d.ts +1 -1
  122. package/dist/types-ts4.5/dialog/create-close-event.d.ts +1 -1
  123. package/dist/types-ts4.5/dialog/types.d.ts +8 -0
  124. package/dist/types-ts4.5/entry-points/use-arrow-navigation.d.ts +2 -1
  125. package/dist/types-ts4.5/internal/placement-to-position-area.d.ts +21 -0
  126. package/dist/types-ts4.5/internal/placement-to-try-fallbacks.d.ts +36 -0
  127. package/dist/types-ts4.5/internal/reduced-motion.d.ts +1 -1
  128. package/dist/types-ts4.5/internal/resolve-placement.d.ts +2 -2
  129. package/dist/types-ts4.5/internal/slot.d.ts +4 -4
  130. package/dist/types-ts4.5/internal/use-anchor-position.d.ts +0 -55
  131. package/dist/types-ts4.5/internal/use-animated-visibility.d.ts +3 -3
  132. package/dist/types-ts4.5/internal/use-animation-preset.d.ts +1 -1
  133. package/dist/types-ts4.5/internal/use-preset-styles.d.ts +1 -1
  134. package/dist/types-ts4.5/internal/use-width-from-anchor.d.ts +2 -2
  135. package/dist/types-ts4.5/popover/create-close-event.d.ts +1 -1
  136. package/dist/types-ts4.5/popover/popover.d.ts +1 -1
  137. package/dist/types-ts4.5/popup/popup-context.d.ts +2 -22
  138. package/dist/types-ts4.5/popup/popup-provider.d.ts +10 -0
  139. package/dist/types-ts4.5/popup/use-maybe-popup-context.d.ts +8 -0
  140. package/dist/types-ts4.5/popup/use-popup-context.d.ts +7 -0
  141. package/dist/types-ts4.5/testing/to-be-visible.d.ts +3 -3
  142. package/dist/types-ts4.5/use-arrow-navigation/index.d.ts +2 -1
  143. package/dist/types-ts4.5/use-arrow-navigation/is-at-current-menu-level.d.ts +48 -0
  144. package/dist/types-ts4.5/use-arrow-navigation/use-arrow-navigation.d.ts +0 -48
  145. package/dist/types-ts4.5/use-simple-light-dismiss/index.d.ts +1 -1
  146. package/package.json +2 -2
  147. package/dist/cjs/arrow/index.js +0 -131
  148. package/dist/cjs/arrow/types.js +0 -5
  149. package/dist/es2019/arrow/index.js +0 -269
  150. package/dist/es2019/arrow/types.js +0 -1
  151. package/dist/esm/arrow/index.js +0 -124
  152. package/dist/esm/arrow/types.js +0 -1
  153. package/dist/types/arrow/index.d.ts +0 -24
  154. package/dist/types/arrow/types.d.ts +0 -29
  155. package/dist/types-ts4.5/arrow/index.d.ts +0 -24
  156. package/dist/types-ts4.5/arrow/types.d.ts +0 -29
@@ -3,7 +3,6 @@
3
3
  Object.defineProperty(exports, "__esModule", {
4
4
  value: true
5
5
  });
6
- exports.isAtCurrentMenuLevel = isAtCurrentMenuLevel;
7
6
  exports.useArrowNavigation = useArrowNavigation;
8
7
  var _react = require("react");
9
8
  var _bindEventListener = require("bind-event-listener");
@@ -12,86 +11,6 @@ var _keycodes = require("@atlaskit/ds-lib/keycodes");
12
11
  var _focus = require("../focus");
13
12
  var menuScope = '[role="menu"]';
14
13
 
15
- /**
16
- * Returns true if the element belongs to the current menu level of the
17
- * container, i.e. it is NOT inside a nested `role="menu"` sub-container.
18
- *
19
- * Uses `element.closest('[role="menu"]')` to determine the nearest menu
20
- * scope. If the nearest scope is the container's own `role="menu"` element,
21
- * the element belongs to this level. If it is a different (nested) menu,
22
- * the element belongs to a child level and should be excluded.
23
- *
24
- * Supports two container patterns:
25
- *
26
- * **1. Container has `role="menu"` directly** (preferred, used by avatar-group):
27
- * ```
28
- * <div ref={containerRef} role="menu">
29
- * <button role="menuitem" /> ← isAtCurrentMenuLevel → true
30
- * <div role="menu"> ← nested sub-menu
31
- * <button role="menuitem" /> ← isAtCurrentMenuLevel → false
32
- * </div>
33
- * </div>
34
- * ```
35
- * Uses the simple check: `element.closest('[role="menu"]') === container`
36
- *
37
- * **2. Container is a wrapper without `role="menu"`** (used by dropdown-menu,
38
- * where `MenuGroup` owns `role="menu"` but does not accept a ref):
39
- * ```
40
- * <div ref={containerRef}> ← wrapper (no role="menu")
41
- * <MenuGroup role="menu">
42
- * <button role="menuitem" /> ← isAtCurrentMenuLevel → true
43
- * <div role="menu"> ← nested sub-menu
44
- * <button role="menuitem" /> ← isAtCurrentMenuLevel → false
45
- * </div>
46
- * </MenuGroup>
47
- * </div>
48
- * ```
49
- * Falls back to walking the DOM to check that the element's closest
50
- * `role="menu"` is the container's own menu (not doubly nested).
51
- *
52
- * Ideally all consumers should use pattern 1 (place the ref directly on the
53
- * `role="menu"` element). Pattern 2 exists because `@atlaskit/menu`'s
54
- * `MenuGroup` does not currently accept a ref. If `MenuGroup` gains ref
55
- * support in the future, dropdown-menu should switch to pattern 1 and the
56
- * fallback path can be removed.
57
- *
58
- * Used both as a `TFocusableFilter` (to scope getNextFocusable etc.) and as
59
- * a guard to prevent parent menu handlers from acting on events that
60
- * belong to a nested menu.
61
- */
62
- function isAtCurrentMenuLevel(element, container) {
63
- var closestMenu = element.closest(menuScope);
64
-
65
- // Container itself has role="menu". Element belongs to this level
66
- // if its closest menu is the container.
67
- if (container.getAttribute('role') === 'menu') {
68
- return closestMenu === container;
69
- }
70
-
71
- // Container is a wrapper without role="menu" (e.g. dropdown-menu
72
- // wraps a MenuGroup). The element belongs to the top level if its
73
- // closest role="menu" ancestor is a direct child of the container,
74
- // i.e. there is no nested role="menu" between them.
75
- if (closestMenu === null) {
76
- return true;
77
- }
78
-
79
- // Walk up from the closest menu to see if it is "owned" by this
80
- // container without passing through another role="menu" first.
81
- var parent = closestMenu.parentElement;
82
- while (parent && parent !== container) {
83
- if (parent.getAttribute('role') === 'menu') {
84
- // There is a parent menu between the closest menu and the
85
- // container, so the element is in a nested sub-menu.
86
- return false;
87
- }
88
- parent = parent.parentElement;
89
- }
90
-
91
- // The closest menu is directly inside the container (no nesting).
92
- return parent === container;
93
- }
94
-
95
14
  /**
96
15
  * Args for `useArrowNavigation`.
97
16
  *
@@ -142,7 +61,6 @@ function isAtCurrentMenuLevel(element, container) {
142
61
  * });
143
62
  * ```
144
63
  */
145
- // eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
146
64
  function useArrowNavigation(_ref) {
147
65
  var containerRef = _ref.containerRef,
148
66
  onClose = _ref.onClose,
@@ -15,7 +15,7 @@ var _bindEventListener = require("bind-event-listener");
15
15
  * **No stacking awareness:** This hook does not track a popover stack.
16
16
  * If multiple manual popovers are open and all use this hook, a single
17
17
  * Escape press or outside click will dismiss **all of them simultaneously**.
18
- * This is by design — the hook is intentionally simple for cases where
18
+ * This is by design - the hook is intentionally simple for cases where
19
19
  * only one manual popover is open at a time.
20
20
  *
21
21
  * For stacked/nested popovers that should dismiss one-at-a-time, use
@@ -52,7 +52,7 @@ function useSimpleLightDismiss(_ref) {
52
52
  // (trigger onClick → setIsOpen(true) → React render → useEffect).
53
53
  // By the time this effect runs, the opening click has finished
54
54
  // bubbling. A capture-phase listener added now cannot retroactively
55
- // fire for that event — it only fires for *future* clicks.
55
+ // fire for that event - it only fires for *future* clicks.
56
56
  //
57
57
  // This avoids the need for timestamp guards or deferred binding.
58
58
  // eslint-disable-next-line @atlaskit/platform/no-direct-document-usage -- binding to document for light dismiss
@@ -64,7 +64,7 @@ function useSimpleLightDismiss(_ref) {
64
64
  return;
65
65
  }
66
66
 
67
- // If the click target is inside the popover, don't dismiss.
67
+ // If the click target is inside the popover, do not dismiss.
68
68
  if (event.target instanceof Node && el.contains(event.target)) {
69
69
  return;
70
70
  }
@@ -1,6 +1,6 @@
1
1
  import { getPlacement } from '../internal/resolve-placement';
2
2
 
3
- // ── slideAndFade ──
3
+ // slideAndFade
4
4
 
5
5
  function getSlideAndFadeProperties({
6
6
  placement,
@@ -123,7 +123,7 @@ export function slideAndFade(options) {
123
123
  };
124
124
  }
125
125
 
126
- // ── fade ──
126
+ // fade
127
127
 
128
128
  const FADE_CSS = `
129
129
  [data-ds-popover-fade] {
@@ -175,7 +175,7 @@ export function fade() {
175
175
  };
176
176
  }
177
177
 
178
- // ── scaleAndFade ──
178
+ // scaleAndFade
179
179
 
180
180
  const SCALE_AND_FADE_CSS = `
181
181
  [data-ds-popover-scale-and-fade] {
@@ -235,7 +235,7 @@ export function scaleAndFade() {
235
235
  // Dialog presets
236
236
  // ══════════════════════════════════════════════════════════════════════════════
237
237
 
238
- // ── dialogSlideUpAndFade ──
238
+ // dialogSlideUpAndFade
239
239
 
240
240
  const DIALOG_SLIDE_UP_AND_FADE_CSS = `
241
241
  [data-ds-dialog-slide-up-and-fade] {
@@ -322,7 +322,7 @@ export function dialogSlideUpAndFade(options) {
322
322
  };
323
323
  }
324
324
 
325
- // ── dialogFade ──
325
+ // dialogFade
326
326
 
327
327
  const DIALOG_FADE_CSS = `
328
328
  [data-ds-dialog-fade] {
@@ -2,7 +2,7 @@
2
2
  * Creates a synthetic DOM event from a `TDialogCloseReason`.
3
3
  *
4
4
  * Useful when bridging the Dialog primitive's `onClose({ reason })` callback
5
- * to a legacy API that expects a `KeyboardEvent` or `MouseEvent` — for example,
5
+ * to a legacy API that expects a `KeyboardEvent` or `MouseEvent` - for example,
6
6
  * `@atlaskit/modal-dialog`'s `onClose(event, analyticsEvent)` contract.
7
7
  *
8
8
  * - `'escape'` → `KeyboardEvent('keydown', { key: 'Escape' })`
@@ -49,7 +49,7 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
49
49
  const ownRef = useRef(null);
50
50
  const combinedRef = mergeRefs([ownRef, ref]);
51
51
 
52
- // ── Animation lifecycle ──
52
+ // Animation lifecycle
53
53
  const {
54
54
  showChildren,
55
55
  preset
@@ -60,7 +60,7 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
60
60
  onExitFinish
61
61
  });
62
62
 
63
- // ── Focus wrap ──
63
+ // Focus wrap
64
64
  // Native <dialog>.showModal() traps focus but wraps through <body> at
65
65
  // the boundary (A → B → C → body → A). This hook intercepts Tab to
66
66
  // wrap directly (A → B → C → A), matching the WAI-ARIA APG pattern.
@@ -69,7 +69,7 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
69
69
  role: 'dialog'
70
70
  });
71
71
 
72
- // ── Open layer observer registration ──
72
+ // Open layer observer registration
73
73
  // Notifies the open layer observer so app-coordination features
74
74
  // (open-count subscriptions) work with top-layer dialogs.
75
75
  useNotifyOpenLayerObserver({
@@ -100,7 +100,7 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
100
100
  }
101
101
  }, [isOpen]);
102
102
 
103
- // ── Handle native Escape (cancel event) ──
103
+ // Handle native Escape (cancel event)
104
104
  const handleCancel = useCallback(event => {
105
105
  event.preventDefault();
106
106
  onClose({
@@ -108,7 +108,7 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
108
108
  });
109
109
  }, [onClose]);
110
110
 
111
- // ── Handle backdrop click ──
111
+ // Handle backdrop click
112
112
  // Attached via bind-event-listener rather than a React prop so we avoid
113
113
  // a11y lint suppressions on the <dialog> element.
114
114
  // Keyboard dismiss is already handled natively (Escape → onCancel above).
@@ -1 +1,2 @@
1
- export { useArrowNavigation, isAtCurrentMenuLevel } from '../use-arrow-navigation';
1
+ export { useArrowNavigation } from '../use-arrow-navigation';
2
+ export { isAtCurrentMenuLevel } from '../use-arrow-navigation/is-at-current-menu-level';
@@ -4,7 +4,7 @@
4
4
  * Each preset's CSS is injected at most once into `<head>`.
5
5
  * Shared by both PopoverContent and DialogContent.
6
6
  *
7
- * Note: injected `<style>` elements and the tracking Set are append-only —
7
+ * Note: injected `<style>` elements and the tracking Set are append-only -
8
8
  * they are never removed. This is intentional: the number of distinct
9
9
  * presets is bounded (handful of animation presets), so the
10
10
  * memory footprint is negligible. Removing styles would risk breaking
@@ -0,0 +1,40 @@
1
+ import { getPlacement } from './resolve-placement';
2
+
3
+ /**
4
+ * Resolves placement options to CSS `position-area` syntax.
5
+ *
6
+ * The `align` field represents the *visual* alignment:
7
+ * - `align: 'start'` means "aligned to the trigger's start edge" (left in LTR for block axis)
8
+ * - `align: 'end'` means "aligned to the trigger's end edge"
9
+ * - `align: 'center'` means centered (single-axis position-area)
10
+ *
11
+ * CSS `position-area` uses `span-*` keywords which indicate the *expansion direction*.
12
+ * Visual start-alignment requires `span-{cross-axis}-end` (expand toward end = start-aligned).
13
+ * This function handles the inversion internally.
14
+ *
15
+ * @example
16
+ * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'center' } }) // → 'block-end'
17
+ * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'start' } }) // → 'block-end span-inline-end'
18
+ * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'end' } }) // → 'block-end span-inline-start'
19
+ */
20
+ export function placementToPositionArea({
21
+ placement
22
+ }) {
23
+ const {
24
+ axis,
25
+ edge,
26
+ align
27
+ } = getPlacement({
28
+ placement
29
+ });
30
+ const edgeValue = `${axis}-${edge}`;
31
+ if (align === 'center') {
32
+ return edgeValue;
33
+ }
34
+
35
+ // Cross-axis name: block ↔ inline
36
+ const crossAxis = axis === 'block' ? 'inline' : 'block';
37
+ // Invert align → CSS span direction: visual 'start' → span toward 'end'
38
+ const spanDir = align === 'start' ? 'end' : 'start';
39
+ return `${edgeValue} span-${crossAxis}-${spanDir}`;
40
+ }
@@ -0,0 +1,77 @@
1
+ import { getPlacement } from './resolve-placement';
2
+
3
+ /**
4
+ * Returns `position-try-fallbacks` value based on placement.
5
+ *
6
+ * For centered placements, includes cross-axis aligned position-area
7
+ * values so the browser can shift the popover along the cross-axis
8
+ * when the centered position would overflow the viewport edge.
9
+ *
10
+ * Fallback order for centered placements (e.g. `block-end`):
11
+ * 1. Same edge, start-aligned (shift for near-edge overflow)
12
+ * 2. Same edge, end-aligned (shift for far-edge overflow)
13
+ * 3. Flipped edge, centered
14
+ * 4. Flipped edge, start-aligned
15
+ * 5. Flipped edge, end-aligned
16
+ *
17
+ * For aligned placements (start/end), includes the same-edge centered
18
+ * position as fallbacks so the browser can try centering when the aligned
19
+ * position would overflow, before flipping to the opposite edge.
20
+ *
21
+ * **Why `flip-inline flip-block` (or `flip-block flip-inline`) is included:**
22
+ *
23
+ * When a popup is in a viewport corner (e.g. inline-end align-end at the
24
+ * top-right), flipping only the primary axis (`flip-inline`) moves the popup
25
+ * to the left but keeps the same cross-axis span direction (e.g. upward),
26
+ * which is still off-screen. The combined keyword `flip-inline flip-block`
27
+ * mirrors the popup diagonally. It flips BOTH the position-area AND both
28
+ * inline and block margins simultaneously, placing the popup at the
29
+ * diagonally opposite corner where there is always space.
30
+ *
31
+ * Named `position-area` entries (e.g. `inline-start span-block-end`) in
32
+ * `position-try-fallbacks` do NOT update margins, so only the `flip-*`
33
+ * tactic keywords correctly flip the gap margin along with the position.
34
+ */
35
+ export function placementToTryFallbacks({
36
+ placement
37
+ }) {
38
+ const {
39
+ axis,
40
+ edge,
41
+ align
42
+ } = getPlacement({
43
+ placement
44
+ });
45
+ const crossAxis = axis === 'block' ? 'inline' : 'block';
46
+ const flippedEdge = edge === 'start' ? 'end' : 'start';
47
+ const sameEdge = `${axis}-${edge}`;
48
+ const oppositeEdge = `${axis}-${flippedEdge}`;
49
+ const flipKeyword = axis === 'block' ? 'flip-block' : 'flip-inline';
50
+ const flipCrossKeyword = axis === 'block' ? 'flip-inline' : 'flip-block';
51
+
52
+ // Single algorithm: produce the shift list against any base alignment.
53
+ // For `align: 'start'` the "near" shift expands toward `end`; for
54
+ // `align: 'end'` it expands toward `start`; for `align: 'center'`
55
+ // either order is symmetric (we use end-then-start to match the
56
+ // historical fallback list).
57
+ function shifts(baseAlign, edgeKey) {
58
+ if (baseAlign === 'center') {
59
+ return [`${edgeKey} span-${crossAxis}-end`, `${edgeKey} span-${crossAxis}-start`];
60
+ }
61
+ const near = baseAlign === 'start' ? 'end' : 'start';
62
+ const far = baseAlign === 'start' ? 'start' : 'end';
63
+ return [`${edgeKey} span-${crossAxis}-${near}`, edgeKey, `${edgeKey} span-${crossAxis}-${far}`];
64
+ }
65
+ if (align !== 'center') {
66
+ // Aligned (start/end): try same-edge shifts, then single-axis flip,
67
+ // then diagonal flip for corner overflow, then opposite-edge shifts.
68
+ // Legacy Popper fallback ordering for e.g. bottom-start:
69
+ // [bottom, bottom-end, top-start, top, top-end, auto].
70
+ return [...shifts(align, sameEdge), flipKeyword, `${flipKeyword} ${flipCrossKeyword}`, ...shifts(align, oppositeEdge)].join(', ');
71
+ }
72
+
73
+ // Centered: same-edge shifts, single-axis flip, opposite-edge shifts.
74
+ // Diagonal flip is unnecessary because centered placements expand
75
+ // equally in both cross-axis directions.
76
+ return [...shifts('center', sameEdge), flipKeyword, ...shifts('center', oppositeEdge)].join(', ');
77
+ }
@@ -7,7 +7,7 @@ import once from '@atlaskit/ds-lib/once';
7
7
  *
8
8
  * The result is cached after the first call via `once`. This avoids
9
9
  * calling `matchMedia` on every render. The trade-off is that if a user
10
- * toggles the OS reduced-motion setting mid-session, the change won't
10
+ * toggles the OS reduced-motion setting mid-session, the change will not
11
11
  * take effect until the next page load. This is acceptable because
12
12
  * toggling this system-level preference mid-session is extremely rare,
13
13
  * and a page refresh is a reasonable expectation for system accessibility
@@ -25,8 +25,8 @@ const DEFAULT_GAP = "var(--ds-space-100, 8px)";
25
25
  * CSS length string (e.g. `token('space.100')`).
26
26
  *
27
27
  * The two offset axes are named for clarity at the call site:
28
- * - `gap` — distance away from the trigger along the placement axis
29
- * - `crossAxisShift` — nudge along the trigger edge (perpendicular to the placement axis)
28
+ * - `gap` - distance away from the trigger along the placement axis
29
+ * - `crossAxisShift` - nudge along the trigger edge (perpendicular to the placement axis)
30
30
  */
31
31
 
32
32
  /**
@@ -22,7 +22,7 @@
22
22
  * (e.g. a combobox labels its listbox, tooltip content IS the accessible name).
23
23
  */
24
24
 
25
- // ── Shared ARIA role discrimination types ──
25
+ // Shared ARIA role discrimination types
26
26
  //
27
27
  // These encode the WCAG 4.1.2 constraint: roles like `dialog`, `alertdialog`,
28
28
  // and `menu` MUST have an accessible name (either `label` or `labelledBy`).
@@ -21,14 +21,14 @@ function isSlotChild(child) {
21
21
  * Merges props (including ref) onto a single React element child.
22
22
  *
23
23
  * A safer alternative to raw `cloneElement` that:
24
- * 1. Guards with `isValidElement` — non-element children (strings,
24
+ * 1. Guards with `isValidElement` - non-element children (strings,
25
25
  * fragments, null) are returned as-is instead of crashing.
26
26
  * 2. Merges refs via `mergeRefs` so both the caller's ref and the
27
27
  * child's existing ref are honoured.
28
28
  * 3. Spreads any additional props (ARIA attributes, event handlers, etc.)
29
29
  * onto the child element.
30
30
  *
31
- * Event handlers (e.g. `onClick`) are **not** auto-merged — the caller's
31
+ * Event handlers (e.g. `onClick`) are **not** auto-merged - the caller's
32
32
  * handler replaces the child's. Compose handlers before passing them in.
33
33
  *
34
34
  * @example
@@ -43,7 +43,7 @@ export const Slot = /*#__PURE__*/forwardRef(function Slot(slotProps, ref) {
43
43
  children: rawChildren,
44
44
  ...props
45
45
  } = slotProps;
46
- // `SlotProps` intersects `Record<string, unknown>`, so `children` is typed as `unknown`.
46
+ // `TSlotProps` intersects `Record<string, unknown>`, so `children` is typed as `unknown`.
47
47
  const children = rawChildren;
48
48
  if (!isSlotChild(children)) {
49
49
  return children;
@@ -18,6 +18,8 @@ import rafSchedule from 'raf-schd';
18
18
  import once from '@atlaskit/ds-lib/once';
19
19
  import { computeFallbackPosition } from './anchor-positioning-fallback';
20
20
  import { combine } from './combine';
21
+ import { placementToPositionArea } from './placement-to-position-area';
22
+ import { placementToTryFallbacks } from './placement-to-try-fallbacks';
21
23
  import { resolveCssLengthToPixels } from './resolve-css-length-to-pixels';
22
24
  import { getPlacement } from './resolve-placement';
23
25
  import { setStyle } from './set-style';
@@ -26,132 +28,16 @@ import { setStyle } from './set-style';
26
28
  // from `./resolve-placement` so search-and-jump lands at the source of truth.
27
29
 
28
30
  /**
29
- * Module-scope no-op `ResizeObserver` used in non-DOM jest environments where
31
+ * Module-scope no-op `ResizeObserver` stub used in non-DOM jest environments where
30
32
  * `ResizeObserver` is `undefined`. Hoisted out of the effect to avoid
31
- * allocating a new class declaration on every run.
33
+ * re-allocating on every run.
32
34
  */
33
- const NoopResizeObserver = class {
34
- observe() {}
35
- unobserve() {}
35
+ const noopResizeObserver = {
36
+ observe() {},
37
+ unobserve() {},
36
38
  disconnect() {}
37
39
  };
38
40
 
39
- /**
40
- * Resolves placement options to CSS `position-area` syntax.
41
- *
42
- * The `align` field represents the *visual* alignment:
43
- * - `align: 'start'` means "aligned to the trigger's start edge" (left in LTR for block axis)
44
- * - `align: 'end'` means "aligned to the trigger's end edge"
45
- * - `align: 'center'` means centered (single-axis position-area)
46
- *
47
- * CSS `position-area` uses `span-*` keywords which indicate the *expansion direction*.
48
- * Visual start-alignment requires `span-{cross-axis}-end` (expand toward end = start-aligned).
49
- * This function handles the inversion internally.
50
- *
51
- * @example
52
- * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'center' } }) // → 'block-end'
53
- * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'start' } }) // → 'block-end span-inline-end'
54
- * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'end' } }) // → 'block-end span-inline-start'
55
- */
56
- export function placementToPositionArea({
57
- placement
58
- }) {
59
- const {
60
- axis,
61
- edge,
62
- align
63
- } = getPlacement({
64
- placement
65
- });
66
- const edgeValue = `${axis}-${edge}`;
67
- if (align === 'center') {
68
- return edgeValue;
69
- }
70
-
71
- // Cross-axis name: block ↔ inline
72
- const crossAxis = axis === 'block' ? 'inline' : 'block';
73
- // Invert align → CSS span direction: visual 'start' → span toward 'end'
74
- const spanDir = align === 'start' ? 'end' : 'start';
75
- return `${edgeValue} span-${crossAxis}-${spanDir}`;
76
- }
77
-
78
- /**
79
- * Returns `position-try-fallbacks` value based on placement.
80
- *
81
- * For centered placements, includes cross-axis aligned position-area
82
- * values so the browser can shift the popover along the cross-axis
83
- * when the centered position would overflow the viewport edge.
84
- *
85
- * Fallback order for centered placements (e.g. `block-end`):
86
- * 1. Same edge, start-aligned (shift for near-edge overflow)
87
- * 2. Same edge, end-aligned (shift for far-edge overflow)
88
- * 3. Flipped edge, centered
89
- * 4. Flipped edge, start-aligned
90
- * 5. Flipped edge, end-aligned
91
- *
92
- * For aligned placements (start/end), includes the same-edge centered
93
- * position as fallbacks so the browser can try centering when the aligned
94
- * position would overflow, before flipping to the opposite edge.
95
- *
96
- * **Why `flip-inline flip-block` (or `flip-block flip-inline`) is included:**
97
- *
98
- * When a popup is in a viewport corner (e.g. inline-end align-end at the
99
- * top-right), flipping only the primary axis (`flip-inline`) moves the popup
100
- * to the left but keeps the same cross-axis span direction (e.g. upward),
101
- * which is still off-screen. The combined keyword `flip-inline flip-block`
102
- * mirrors the popup diagonally. It flips BOTH the position-area AND both
103
- * inline and block margins simultaneously, placing the popup at the
104
- * diagonally opposite corner where there is always space.
105
- *
106
- * Named `position-area` entries (e.g. `inline-start span-block-end`) in
107
- * `position-try-fallbacks` do NOT update margins, so only the `flip-*`
108
- * tactic keywords correctly flip the gap margin along with the position.
109
- */
110
- // eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
111
- export function placementToTryFallbacks({
112
- placement
113
- }) {
114
- const {
115
- axis,
116
- edge,
117
- align
118
- } = getPlacement({
119
- placement
120
- });
121
- const crossAxis = axis === 'block' ? 'inline' : 'block';
122
- const flippedEdge = edge === 'start' ? 'end' : 'start';
123
- const sameEdge = `${axis}-${edge}`;
124
- const oppositeEdge = `${axis}-${flippedEdge}`;
125
- const flipKeyword = axis === 'block' ? 'flip-block' : 'flip-inline';
126
- const flipCrossKeyword = axis === 'block' ? 'flip-inline' : 'flip-block';
127
-
128
- // Single algorithm: produce the shift list against any base alignment.
129
- // For `align: 'start'` the "near" shift expands toward `end`; for
130
- // `align: 'end'` it expands toward `start`; for `align: 'center'`
131
- // either order is symmetric (we use end-then-start to match the
132
- // historical fallback list).
133
- function shifts(baseAlign, edgeKey) {
134
- if (baseAlign === 'center') {
135
- return [`${edgeKey} span-${crossAxis}-end`, `${edgeKey} span-${crossAxis}-start`];
136
- }
137
- const near = baseAlign === 'start' ? 'end' : 'start';
138
- const far = baseAlign === 'start' ? 'start' : 'end';
139
- return [`${edgeKey} span-${crossAxis}-${near}`, edgeKey, `${edgeKey} span-${crossAxis}-${far}`];
140
- }
141
- if (align !== 'center') {
142
- // Aligned (start/end): try same-edge shifts, then single-axis flip,
143
- // then diagonal flip for corner overflow, then opposite-edge shifts.
144
- // Legacy Popper fallback ordering for e.g. bottom-start:
145
- // [bottom, bottom-end, top-start, top, top-end, auto].
146
- return [...shifts(align, sameEdge), flipKeyword, `${flipKeyword} ${flipCrossKeyword}`, ...shifts(align, oppositeEdge)].join(', ');
147
- }
148
-
149
- // Centered: same-edge shifts, single-axis flip, opposite-edge shifts.
150
- // Diagonal flip is unnecessary because centered placements expand
151
- // equally in both cross-axis directions.
152
- return [...shifts('center', sameEdge), flipKeyword, ...shifts('center', oppositeEdge)].join(', ');
153
- }
154
-
155
41
  /**
156
42
  * Returns true when the popover is currently open. Wrapped because the
157
43
  * `:popover-open` pseudo-class is not implemented in some test environments
@@ -443,7 +329,7 @@ export function useAnchorPosition({
443
329
  return undoPositioning;
444
330
  }
445
331
 
446
- // ── JS fallback ──
332
+ // JS fallback
447
333
  // The popover is already in the browser's top layer via popover="auto",
448
334
  // so it does not need position:fixed. We only reset the UA defaults
449
335
  // (inset: 0; margin: auto) and set top/left based on measurements.
@@ -513,20 +399,17 @@ export function useAnchorPosition({
513
399
  // Self-disconnects after one valid measurement; ongoing
514
400
  // scroll/resize is handled by the window listeners below.
515
401
  // `ResizeObserver` is missing in some non-DOM jest environments
516
- // (e.g. post-office's `node` environment). Fall back to a no-op
517
- // observer there. The scroll/resize listeners below still keep
518
- // the popover positioned in the rare case the consumer also
519
- // polyfilled `showPopover` but not `ResizeObserver`. Real
520
- // browsers always have it. The `NoopResizeObserver` class is
521
- // hoisted to module scope (see top of file) so we do not allocate
522
- // a new constructor on every effect run.
523
- const ResizeObserverImpl = typeof ResizeObserver !== 'undefined' ? ResizeObserver : NoopResizeObserver;
524
- const resizeObserver = new ResizeObserverImpl(() => {
402
+ // (e.g. post-office's `node` environment). Fall back to the
403
+ // module-scope `noopResizeObserver` stub there. The scroll/resize
404
+ // listeners below still keep the popover positioned in the rare
405
+ // case the consumer also polyfilled `showPopover` but not
406
+ // `ResizeObserver`. Real browsers always have it.
407
+ const resizeObserver = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(() => {
525
408
  if (popover.offsetWidth > 0 && popover.offsetHeight > 0) {
526
409
  update();
527
410
  resizeObserver.disconnect();
528
411
  }
529
- });
412
+ }) : noopResizeObserver;
530
413
 
531
414
  // If the popover is already open by the time this effect runs (for
532
415
  // example, the parent `useAnchorPosition` effect runs after the child