@atlaskit/top-layer 0.1.5 → 0.2.0

package/dist/esm/placement-map/index.js

@@ -1,3 +1,7 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 /**
  * Legacy Popper.js placement values (used by `@atlaskit/popper`, `@atlaskit/popup`,
  * `@atlaskit/tooltip`, etc.).
@@ -128,11 +132,34 @@ var placementMapping = {
 };
 
 /**
- * Convert a legacy Popper.js placement to the new CSS `position-area`-based Placement.
+ * Convert a legacy Popper.js placement to the new `position-area`-based Placement.
+ * Optional `offset` is the legacy Popper `[along, away]` tuple (also known as
+ * `[skidding, distance]`); negative `along` becomes `direction: 'backwards'`.
+ *
+ * The tuple keeps the historical popper names so call sites that already pass
+ * `[along, away]` migrate without thinking; the new internal field names
+ * (`gap` / `crossAxisShift`) are produced inside this adapter.
  */
 export function fromLegacyPlacement(_ref) {
-  var legacy = _ref.legacy;
-  return placementMapping[legacy];
+  var legacy = _ref.legacy,
+    offset = _ref.offset;
+  var basePlacement = placementMapping[legacy];
+  if (!offset) {
+    return basePlacement;
+  }
+  var _offset = _slicedToArray(offset, 2),
+    along = _offset[0],
+    away = _offset[1];
+  return _objectSpread(_objectSpread({}, basePlacement), {}, {
+    offset: {
+      gap: away,
+      crossAxisShift: {
+        // Sign is captured in `direction`; `value` is the magnitude.
+        value: Math.abs(along),
+        direction: along >= 0 ? 'forwards' : 'backwards'
+      }
+    }
+  });
 }
 
 /**

package/dist/esm/popup/popup-content.js

@@ -32,7 +32,6 @@ export var PopupContent = /*#__PURE__*/forwardRef(function PopupContent(_ref, re
     placementProp = _ref.placement,
     onCloseProp = _ref.onClose,
     testIdProp = _ref.testId,
-    offsetProp = _ref.offset,
     forceFallbackPositioningProp = _ref.forceFallbackPositioning;
   // When inside <Popup>, context provides defaults. Props always win.
   var ctx = useMaybePopupContext();
@@ -129,7 +128,6 @@ export var PopupContent = /*#__PURE__*/forwardRef(function PopupContent(_ref, re
     },
     popoverRef: popoverRef,
     placement: placement,
-    offset: offsetProp,
     forceFallbackPositioning: forceFallbackPositioning,
     arrow: arrowPreset !== null && arrowPreset !== void 0 ? arrowPreset : undefined
   });

package/dist/types/internal/anchor-positioning-fallback.d.ts

@@ -1,15 +1,13 @@
 import { type TPlacement } from './resolve-placement';
 /**
- * JS fallback: compute popover position from trigger rect and viewport.
+ * Computes popover position from trigger rect and viewport, flipping to
+ * the side with more space when needed. Re-runs on scroll/resize.
  *
- * Placement algorithm (from the document):
- * - "block" placement: show above/below, picking the side with more space if flipping needed
- * - "inline" placement: show left/right, picking the side with more space if flipping needed
- * - "auto" placement: show on the edge with the most available space
- *
- * Re-runs on scroll (capture on window) and resize events.
+ * `gap` and `crossAxisShift` are pre-resolved to pixels by the
+ * caller (see `resolveCssLengthToPixels`), so this function stays purely
+ * numeric.
  */
-export declare function computeFallbackPosition({ triggerRect, popoverEl, placement, viewport, offset, }: {
+export declare function computeFallbackPosition({ triggerRect, popoverEl, placement, viewport, gap, crossAxisShift, }: {
     triggerRect: DOMRect;
     popoverEl: HTMLElement;
     placement: TPlacement;
@@ -17,7 +15,11 @@ export declare function computeFallbackPosition({ triggerRect, popoverEl, placem
         width: number;
         height: number;
     };
-    offset: number;
+    gap: number;
+    crossAxisShift: {
+        value: number;
+        direction: 'forwards' | 'backwards';
+    };
 }): {
     top: number;
     left: number;

package/dist/types/internal/resolve-css-length-to-pixels.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Resolves a CSS length value to a pixel number using a hidden DOM probe.
+ *
+ * Used by the JS positioning fallback: consumer offsets can be numbers,
+ * `${n}px` strings, tokenised `var(--ds-space-100, 8px)` strings, `calc()`
+ * expressions, viewport units, etc. Parsing arbitrary CSS in JS is fragile
+ * (and impossible for `calc(var(...))` without a layout context), so we let
+ * the browser do the math.
+ *
+ * The probe is appended to `container` so it inherits the same containing
+ * block, font size, and custom-property scope as the popover. We use `width`
+ * because it accepts any CSS length, including negative `calc()` results
+ * (negative widths are clamped to 0 — see note below).
+ *
+ * Cost: one synchronous reflow per call. The fallback only resolves on
+ * placement/offset changes, not on every scroll/resize update, so this is
+ * not a hot path.
+ */
+export declare function resolveCssLengthToPixels({ value, container, }: {
+    value: number | string;
+    container: HTMLElement;
+}): number;

package/dist/types/internal/resolve-css-length.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Normalizes an offset to a CSS length string. Numbers become `${n}px`;
+ * strings pass through. Apply at the API boundary so internal code only
+ * deals with strings.
+ */
+export declare function toCssLengthString({ value }: {
+    value: number | string;
+}): string;

package/dist/types/internal/resolve-placement.d.ts

@@ -1,16 +1,58 @@
 /**
- * Fully-resolved placement (internal). All fields are required.
- * Use getPlacement({ placement: partial }) to obtain from partial input.
+ * Cross-axis shift. `value` is a CSS length string (consumer numbers are
+ * normalized to `${n}px`). `direction` is `'forwards'` (toward end) or
+ * `'backwards'` (toward start).
+ */
+export type TCrossAxisShiftOffset = {
+    value: string;
+    direction: 'forwards' | 'backwards';
+};
+/**
+ * Fully-resolved placement (internal). Use `getPlacement` for partial input.
+ * `offset.gap` and `offset.crossAxisShift.value` are always CSS
+ * length strings.
  */
 export type TPlacement = {
     axis: 'block' | 'inline';
     edge: 'start' | 'end';
     align: 'start' | 'center' | 'end';
+    offset: {
+        gap: string;
+        crossAxisShift: {
+            value: string;
+            direction: 'forwards' | 'backwards';
+        };
+    };
+};
+/**
+ * Partial placement options. `offset.gap` and
+ * `offset.crossAxisShift.value` accept either a number (pixels) or a
+ * CSS length string (e.g. `token('space.100')`).
+ *
+ * The two offset axes are named for clarity at the call site:
+ *   - `gap`     — distance away from the trigger along the placement axis
+ *   - `crossAxisShift`  — nudge along the trigger edge (perpendicular to the placement axis)
+ */
+export type TPlacementOptions = {
+    axis?: 'block' | 'inline';
+    edge?: 'start' | 'end';
+    align?: 'start' | 'center' | 'end';
+    offset?: {
+        gap?: number | string;
+        crossAxisShift?: {
+            value?: number | string;
+            direction?: 'forwards' | 'backwards';
+        };
+    };
 };
 /**
- * Resolves a partial placement to its fully-specified form.
- * Defaults: `axis: 'block'`, `edge: 'end'`, `align: 'center'`.
+ * Resolves a partial placement to its fully-specified form. Number offsets
+ * are normalized to `${n}px` strings.
+ *
+ * Defaults: `axis: 'block'`, `edge: 'end'`, `align: 'center'`,
+ * `offset.gap: token('space.100', '8px')`,
+ * `offset.crossAxisShift: { value: '0px', direction: 'forwards' }`.
  */
 export declare function getPlacement({ placement }: {
-    placement: Partial<TPlacement>;
+    placement: TPlacementOptions;
 }): TPlacement;

package/dist/types/internal/use-anchor-positioning.d.ts

@@ -1,6 +1,20 @@
+/**
+ * Anchor positioning for top-layer popovers. See
+ * `notes/architecture/positioning.md` for the full model.
+ *
+ * Two runtime paths: CSS Anchor Positioning (modern browsers) and a JS
+ * fallback that measures the trigger and writes `top`/`left`.
+ *
+ * Both paths honour `offset.gap` and `offset.crossAxisShift`. The
+ * CSS path passes the values through as strings; the JS fallback resolves
+ * them to pixels via a hidden DOM probe (see `resolveCssLengthToPixels`)
+ * so tokens, `calc()`, `var()`, etc all work. The JS fallback hides the
+ * popover with `opacity: 0` until the first measurement completes, so it
+ * is never painted at the wrong location.
+ */
 import { type RefObject } from 'react';
 import { type TArrowPreset } from '../arrow/types';
-import { type TPlacementOptions } from '../popup/types';
+import { type TPlacementOptions } from '../internal/resolve-placement';
 export { getPlacement } from './resolve-placement';
 /**
  * Resolves placement options to CSS `position-area` syntax.
@@ -59,7 +73,7 @@ export declare function placementToTryFallbacks({ placement }: {
  * `position: fixed` with measured coordinates, re-running on scroll (capture)
  * and resize events.
  */
-export declare function useAnchorPosition({ anchorRef, popoverRef, placement, offset, forceFallbackPositioning, arrow, }: {
+export declare function useAnchorPosition({ anchorRef, popoverRef, placement, forceFallbackPositioning, arrow, }: {
     /**
      * Element to position relative to.
      */
@@ -70,13 +84,10 @@ export declare function useAnchorPosition({ anchorRef, popoverRef, placement, of
     popoverRef: RefObject<HTMLElement | null>;
     /**
      * Where to place the element relative to the anchor.
+     * `offset.gap` and `offset.crossAxisShift` are part of the
+     * placement object.
      */
     placement: TPlacementOptions;
-    /**
-     * Gap between the positioned element and the anchor, in pixels.
-     * Defaults to 8 (`space.100`). Tooltip uses 4.
-     */
-    offset?: number;
     /**
      * Forces the JavaScript positioning fallback even when the browser
      * supports CSS Anchor Positioning. Useful for testing fallback

package/dist/types/placement-map/index.d.ts

@@ -1,5 +1,4 @@
-import { type TPlacement } from '../internal/resolve-placement';
-import { type TPlacementOptions } from '../popup/types';
+import { type TPlacementOptions } from '../internal/resolve-placement';
 /**
  * Legacy Popper.js placement values (used by `@atlaskit/popper`, `@atlaskit/popup`,
  * `@atlaskit/tooltip`, etc.).
@@ -41,12 +40,19 @@ export type TLegacyPlacement = 'auto' | 'auto-start' | 'auto-end' | 'top' | 'top
  * // newPlacement === { axis: 'block', edge: 'end', align: 'start' }
  * ```
  */
-declare const placementMapping: Record<TLegacyPlacement, TPlacement>;
+declare const placementMapping: Record<TLegacyPlacement, TPlacementOptions>;
 /**
- * Convert a legacy Popper.js placement to the new CSS `position-area`-based Placement.
+ * Convert a legacy Popper.js placement to the new `position-area`-based Placement.
+ * Optional `offset` is the legacy Popper `[along, away]` tuple (also known as
+ * `[skidding, distance]`); negative `along` becomes `direction: 'backwards'`.
+ *
+ * The tuple keeps the historical popper names so call sites that already pass
+ * `[along, away]` migrate without thinking; the new internal field names
+ * (`gap` / `crossAxisShift`) are produced inside this adapter.
  */
-export declare function fromLegacyPlacement({ legacy }: {
+export declare function fromLegacyPlacement({ legacy, offset, }: {
     legacy: TLegacyPlacement;
+    offset?: [along: number, away: number];
 }): TPlacementOptions;
 /**
  * The full mapping record, exposed for consumers that need to iterate or introspect.

package/dist/types/popup/types.d.ts

@@ -2,39 +2,30 @@ import { type ReactElement, type ReactNode, type Ref, type RefObject } from 'rea
 import { type StrictXCSSProp } from '@atlaskit/css';
 import { type TAnimationPreset } from '../animations/types';
 import { type TArrowPreset } from '../arrow/types';
-import { type TPlacement } from '../internal/resolve-placement';
+import { type TPlacementOptions } from '../internal/resolve-placement';
 import { type TRoleRequiringAccessibleName, type TRoleWithImplicitName } from '../internal/role-types';
 import { type TPopoverCloseReason } from '../popover/types';
 /**
- * Describes where to position a popover relative to its trigger.
+ * Describes where to position a popover relative to its trigger. All fields
+ * are optional. The default `{}` means "below the trigger, centered, with a
+ * `space.100` token gap" (equivalent to Popper.js `'bottom'`).
  *
- * - `axis` — which axis the popover appears along (`'block'` = above/below, `'inline'` = left/right).
- *   Defaults to `'block'`.
- * - `edge` — which end of the axis (`'start'` = above/left in LTR, `'end'` = below/right in LTR).
- *   Defaults to `'end'`.
- * - `align` — where to align on the cross-axis (`'start'`, `'center'`, `'end'`).
- *   Defaults to `'center'`. Can be written explicitly for clarity.
- *
- * All fields are optional. The default `{}` means "below the trigger, centered"
- * (equivalent to Popper.js `'bottom'`).
+ * - `axis`: `'block'` (above/below, default) or `'inline'` (left/right)
+ * - `edge`: `'start'` or `'end'` (default)
+ * - `align`: `'start'`, `'center'` (default), or `'end'`
+ * - `offset.gap`: distance from the trigger toward the popover (default `token('space.100', '8px')`, accepts number or CSS string)
+ * - `offset.crossAxisShift.value`: cross-axis shift (default `0`)
+ * - `offset.crossAxisShift.direction`: `'forwards'` (default) or `'backwards'`
  *
  * @example
  * ```ts
- * // Below trigger, centered (all defaults)
- * placement={{}}
- * placement={{ axis: 'block', edge: 'end', align: 'center' }}
- *
- * // Below trigger, aligned to the start (left in LTR)
- * placement={{ align: 'start' }}
- *
- * // Above trigger, aligned to the end (right in LTR)
- * placement={{ edge: 'start', align: 'end' }}
- *
- * // Right of trigger, centered
- * placement={{ axis: 'inline' }}
+ * placement={{ align: 'start' }} // Below trigger, aligned to start
+ * placement={{ axis: 'inline' }} // Right of trigger, centered
+ * placement={{ offset: { gap: 4 } }} // Tooltip-like gap
+ * placement={{ offset: { crossAxisShift: { value: 4, direction: 'backwards' } } }}
  * ```
  */
-export type TPlacementOptions = Partial<TPlacement>;
+export { type TPlacementOptions } from '../internal/resolve-placement';
 export type TPopupProps = {
     /**
      * Position of the popup relative to the trigger. Only the Popup compound uses
@@ -176,11 +167,6 @@ type TPopupContentBaseProps = {
      * Test ID applied to the popover content element.
      */
     testId?: string;
-    /**
-     * Gap between the popover and its trigger, in pixels.
-     * Defaults to 8 (design token `space.100`). Tooltip uses 4.
-     */
-    offset?: number;
     /**
      * Forces the JavaScript positioning fallback even when the browser
      * supports CSS Anchor Positioning. Useful for testing fallback
@@ -302,4 +288,3 @@ export type TPopupContentProps = TPopupContentBaseProps & (({
 export type TPopupSurfaceProps = {
     children: ReactNode;
 };
-export {};

package/dist/types-ts4.5/internal/anchor-positioning-fallback.d.ts

@@ -1,15 +1,13 @@
 import { type TPlacement } from './resolve-placement';
 /**
- * JS fallback: compute popover position from trigger rect and viewport.
+ * Computes popover position from trigger rect and viewport, flipping to
+ * the side with more space when needed. Re-runs on scroll/resize.
  *
- * Placement algorithm (from the document):
- * - "block" placement: show above/below, picking the side with more space if flipping needed
- * - "inline" placement: show left/right, picking the side with more space if flipping needed
- * - "auto" placement: show on the edge with the most available space
- *
- * Re-runs on scroll (capture on window) and resize events.
+ * `gap` and `crossAxisShift` are pre-resolved to pixels by the
+ * caller (see `resolveCssLengthToPixels`), so this function stays purely
+ * numeric.
  */
-export declare function computeFallbackPosition({ triggerRect, popoverEl, placement, viewport, offset, }: {
+export declare function computeFallbackPosition({ triggerRect, popoverEl, placement, viewport, gap, crossAxisShift, }: {
     triggerRect: DOMRect;
     popoverEl: HTMLElement;
     placement: TPlacement;
@@ -17,7 +15,11 @@ export declare function computeFallbackPosition({ triggerRect, popoverEl, placem
         width: number;
         height: number;
     };
-    offset: number;
+    gap: number;
+    crossAxisShift: {
+        value: number;
+        direction: 'forwards' | 'backwards';
+    };
 }): {
     top: number;
     left: number;

package/dist/types-ts4.5/internal/resolve-css-length-to-pixels.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Resolves a CSS length value to a pixel number using a hidden DOM probe.
+ *
+ * Used by the JS positioning fallback: consumer offsets can be numbers,
+ * `${n}px` strings, tokenised `var(--ds-space-100, 8px)` strings, `calc()`
+ * expressions, viewport units, etc. Parsing arbitrary CSS in JS is fragile
+ * (and impossible for `calc(var(...))` without a layout context), so we let
+ * the browser do the math.
+ *
+ * The probe is appended to `container` so it inherits the same containing
+ * block, font size, and custom-property scope as the popover. We use `width`
+ * because it accepts any CSS length, including negative `calc()` results
+ * (negative widths are clamped to 0 — see note below).
+ *
+ * Cost: one synchronous reflow per call. The fallback only resolves on
+ * placement/offset changes, not on every scroll/resize update, so this is
+ * not a hot path.
+ */
+export declare function resolveCssLengthToPixels({ value, container, }: {
+    value: number | string;
+    container: HTMLElement;
+}): number;

package/dist/types-ts4.5/internal/resolve-css-length.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Normalizes an offset to a CSS length string. Numbers become `${n}px`;
+ * strings pass through. Apply at the API boundary so internal code only
+ * deals with strings.
+ */
+export declare function toCssLengthString({ value }: {
+    value: number | string;
+}): string;

package/dist/types-ts4.5/internal/resolve-placement.d.ts

@@ -1,16 +1,58 @@
 /**
- * Fully-resolved placement (internal). All fields are required.
- * Use getPlacement({ placement: partial }) to obtain from partial input.
+ * Cross-axis shift. `value` is a CSS length string (consumer numbers are
+ * normalized to `${n}px`). `direction` is `'forwards'` (toward end) or
+ * `'backwards'` (toward start).
+ */
+export type TCrossAxisShiftOffset = {
+    value: string;
+    direction: 'forwards' | 'backwards';
+};
+/**
+ * Fully-resolved placement (internal). Use `getPlacement` for partial input.
+ * `offset.gap` and `offset.crossAxisShift.value` are always CSS
+ * length strings.
  */
 export type TPlacement = {
     axis: 'block' | 'inline';
     edge: 'start' | 'end';
     align: 'start' | 'center' | 'end';
+    offset: {
+        gap: string;
+        crossAxisShift: {
+            value: string;
+            direction: 'forwards' | 'backwards';
+        };
+    };
+};
+/**
+ * Partial placement options. `offset.gap` and
+ * `offset.crossAxisShift.value` accept either a number (pixels) or a
+ * CSS length string (e.g. `token('space.100')`).
+ *
+ * The two offset axes are named for clarity at the call site:
+ *   - `gap`     — distance away from the trigger along the placement axis
+ *   - `crossAxisShift`  — nudge along the trigger edge (perpendicular to the placement axis)
+ */
+export type TPlacementOptions = {
+    axis?: 'block' | 'inline';
+    edge?: 'start' | 'end';
+    align?: 'start' | 'center' | 'end';
+    offset?: {
+        gap?: number | string;
+        crossAxisShift?: {
+            value?: number | string;
+            direction?: 'forwards' | 'backwards';
+        };
+    };
 };
 /**
- * Resolves a partial placement to its fully-specified form.
- * Defaults: `axis: 'block'`, `edge: 'end'`, `align: 'center'`.
+ * Resolves a partial placement to its fully-specified form. Number offsets
+ * are normalized to `${n}px` strings.
+ *
+ * Defaults: `axis: 'block'`, `edge: 'end'`, `align: 'center'`,
+ * `offset.gap: token('space.100', '8px')`,
+ * `offset.crossAxisShift: { value: '0px', direction: 'forwards' }`.
  */
 export declare function getPlacement({ placement }: {
-    placement: Partial<TPlacement>;
+    placement: TPlacementOptions;
 }): TPlacement;

package/dist/types-ts4.5/internal/use-anchor-positioning.d.ts

@@ -1,6 +1,20 @@
+/**
+ * Anchor positioning for top-layer popovers. See
+ * `notes/architecture/positioning.md` for the full model.
+ *
+ * Two runtime paths: CSS Anchor Positioning (modern browsers) and a JS
+ * fallback that measures the trigger and writes `top`/`left`.
+ *
+ * Both paths honour `offset.gap` and `offset.crossAxisShift`. The
+ * CSS path passes the values through as strings; the JS fallback resolves
+ * them to pixels via a hidden DOM probe (see `resolveCssLengthToPixels`)
+ * so tokens, `calc()`, `var()`, etc all work. The JS fallback hides the
+ * popover with `opacity: 0` until the first measurement completes, so it
+ * is never painted at the wrong location.
+ */
 import { type RefObject } from 'react';
 import { type TArrowPreset } from '../arrow/types';
-import { type TPlacementOptions } from '../popup/types';
+import { type TPlacementOptions } from '../internal/resolve-placement';
 export { getPlacement } from './resolve-placement';
 /**
  * Resolves placement options to CSS `position-area` syntax.
@@ -59,7 +73,7 @@ export declare function placementToTryFallbacks({ placement }: {
  * `position: fixed` with measured coordinates, re-running on scroll (capture)
  * and resize events.
  */
-export declare function useAnchorPosition({ anchorRef, popoverRef, placement, offset, forceFallbackPositioning, arrow, }: {
+export declare function useAnchorPosition({ anchorRef, popoverRef, placement, forceFallbackPositioning, arrow, }: {
     /**
      * Element to position relative to.
      */
@@ -70,13 +84,10 @@ export declare function useAnchorPosition({ anchorRef, popoverRef, placement, of
     popoverRef: RefObject<HTMLElement | null>;
     /**
      * Where to place the element relative to the anchor.
+     * `offset.gap` and `offset.crossAxisShift` are part of the
+     * placement object.
      */
     placement: TPlacementOptions;
-    /**
-     * Gap between the positioned element and the anchor, in pixels.
-     * Defaults to 8 (`space.100`). Tooltip uses 4.
-     */
-    offset?: number;
     /**
      * Forces the JavaScript positioning fallback even when the browser
      * supports CSS Anchor Positioning. Useful for testing fallback

package/dist/types-ts4.5/placement-map/index.d.ts

@@ -1,5 +1,4 @@
-import { type TPlacement } from '../internal/resolve-placement';
-import { type TPlacementOptions } from '../popup/types';
+import { type TPlacementOptions } from '../internal/resolve-placement';
 /**
  * Legacy Popper.js placement values (used by `@atlaskit/popper`, `@atlaskit/popup`,
  * `@atlaskit/tooltip`, etc.).
@@ -41,12 +40,22 @@ export type TLegacyPlacement = 'auto' | 'auto-start' | 'auto-end' | 'top' | 'top
  * // newPlacement === { axis: 'block', edge: 'end', align: 'start' }
  * ```
  */
-declare const placementMapping: Record<TLegacyPlacement, TPlacement>;
+declare const placementMapping: Record<TLegacyPlacement, TPlacementOptions>;
 /**
- * Convert a legacy Popper.js placement to the new CSS `position-area`-based Placement.
+ * Convert a legacy Popper.js placement to the new `position-area`-based Placement.
+ * Optional `offset` is the legacy Popper `[along, away]` tuple (also known as
+ * `[skidding, distance]`); negative `along` becomes `direction: 'backwards'`.
+ *
+ * The tuple keeps the historical popper names so call sites that already pass
+ * `[along, away]` migrate without thinking; the new internal field names
+ * (`gap` / `crossAxisShift`) are produced inside this adapter.
  */
-export declare function fromLegacyPlacement({ legacy }: {
+export declare function fromLegacyPlacement({ legacy, offset, }: {
     legacy: TLegacyPlacement;
+    offset?: [
+        along: number,
+        away: number
+    ];
 }): TPlacementOptions;
 /**
  * The full mapping record, exposed for consumers that need to iterate or introspect.

package/dist/types-ts4.5/popup/types.d.ts

@@ -2,39 +2,30 @@ import { type ReactElement, type ReactNode, type Ref, type RefObject } from 'rea
 import { type StrictXCSSProp } from '@atlaskit/css';
 import { type TAnimationPreset } from '../animations/types';
 import { type TArrowPreset } from '../arrow/types';
-import { type TPlacement } from '../internal/resolve-placement';
+import { type TPlacementOptions } from '../internal/resolve-placement';
 import { type TRoleRequiringAccessibleName, type TRoleWithImplicitName } from '../internal/role-types';
 import { type TPopoverCloseReason } from '../popover/types';
 /**
- * Describes where to position a popover relative to its trigger.
+ * Describes where to position a popover relative to its trigger. All fields
+ * are optional. The default `{}` means "below the trigger, centered, with a
+ * `space.100` token gap" (equivalent to Popper.js `'bottom'`).
  *
- * - `axis` — which axis the popover appears along (`'block'` = above/below, `'inline'` = left/right).
- *   Defaults to `'block'`.
- * - `edge` — which end of the axis (`'start'` = above/left in LTR, `'end'` = below/right in LTR).
- *   Defaults to `'end'`.
- * - `align` — where to align on the cross-axis (`'start'`, `'center'`, `'end'`).
- *   Defaults to `'center'`. Can be written explicitly for clarity.
- *
- * All fields are optional. The default `{}` means "below the trigger, centered"
- * (equivalent to Popper.js `'bottom'`).
+ * - `axis`: `'block'` (above/below, default) or `'inline'` (left/right)
+ * - `edge`: `'start'` or `'end'` (default)
+ * - `align`: `'start'`, `'center'` (default), or `'end'`
+ * - `offset.gap`: distance from the trigger toward the popover (default `token('space.100', '8px')`, accepts number or CSS string)
+ * - `offset.crossAxisShift.value`: cross-axis shift (default `0`)
+ * - `offset.crossAxisShift.direction`: `'forwards'` (default) or `'backwards'`
  *
  * @example
  * ```ts
- * // Below trigger, centered (all defaults)
- * placement={{}}
- * placement={{ axis: 'block', edge: 'end', align: 'center' }}
- *
- * // Below trigger, aligned to the start (left in LTR)
- * placement={{ align: 'start' }}
- *
- * // Above trigger, aligned to the end (right in LTR)
- * placement={{ edge: 'start', align: 'end' }}
- *
- * // Right of trigger, centered
- * placement={{ axis: 'inline' }}
+ * placement={{ align: 'start' }} // Below trigger, aligned to start
+ * placement={{ axis: 'inline' }} // Right of trigger, centered
+ * placement={{ offset: { gap: 4 } }} // Tooltip-like gap
+ * placement={{ offset: { crossAxisShift: { value: 4, direction: 'backwards' } } }}
  * ```
  */
-export type TPlacementOptions = Partial<TPlacement>;
+export { type TPlacementOptions } from '../internal/resolve-placement';
 export type TPopupProps = {
     /**
      * Position of the popup relative to the trigger. Only the Popup compound uses
@@ -176,11 +167,6 @@ type TPopupContentBaseProps = {
      * Test ID applied to the popover content element.
      */
     testId?: string;
-    /**
-     * Gap between the popover and its trigger, in pixels.
-     * Defaults to 8 (design token `space.100`). Tooltip uses 4.
-     */
-    offset?: number;
     /**
      * Forces the JavaScript positioning fallback even when the browser
      * supports CSS Anchor Positioning. Useful for testing fallback
@@ -302,4 +288,3 @@ export type TPopupContentProps = TPopupContentBaseProps & (({
 export type TPopupSurfaceProps = {
     children: ReactNode;
 };
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/top-layer",
-	"version": "0.1.5",
+	"version": "0.2.0",
 	"description": "Low-level layering primitives based on popover and dialog",
 	"homepage": "https://atlassian.design/components/top-layer",
 	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-mirror",
@@ -52,7 +52,7 @@
 		"@af/visual-regression": "workspace:^",
 		"@atlaskit/button": "^23.11.0",
 		"@atlaskit/heading": "^5.4.0",
-		"@atlaskit/lozenge": "^13.6.0",
+		"@atlaskit/lozenge": "^13.7.0",
 		"@atlaskit/primitives": "^19.0.0",
 		"@atlaskit/ssr": "workspace:^",
 		"@atlaskit/textfield": "^8.3.0",