@atlaskit/top-layer 0.1.0

package/dist/es2019/internal/anchor-positioning-fallback.js

@@ -0,0 +1,153 @@
+/**
+ * Computes the base {top, left} position based on the primary edge,
+ * flipping to the opposite side when there is not enough space.
+ */
+function computeEdgePosition({
+  axis,
+  edge,
+  triggerRect,
+  popoverWidth,
+  popoverHeight,
+  viewport,
+  offset
+}) {
+  if (axis === 'block' && edge === 'end') {
+    // Below trigger
+    const spaceBelow = viewport.height - triggerRect.bottom;
+    const spaceAbove = triggerRect.top;
+    return {
+      top: spaceBelow >= popoverHeight + offset || spaceBelow >= spaceAbove ? triggerRect.bottom + offset : triggerRect.top - popoverHeight - offset,
+      left: triggerRect.left + triggerRect.width / 2 - popoverWidth / 2
+    };
+  }
+  if (axis === 'block' && edge === 'start') {
+    // Above trigger
+    const spaceAbove = triggerRect.top;
+    const spaceBelow = viewport.height - triggerRect.bottom;
+    return {
+      top: spaceAbove >= popoverHeight + offset || spaceAbove >= spaceBelow ? triggerRect.top - popoverHeight - offset : triggerRect.bottom + offset,
+      left: triggerRect.left + triggerRect.width / 2 - popoverWidth / 2
+    };
+  }
+  if (axis === 'inline' && edge === 'end') {
+    // Right of trigger
+    const spaceRight = viewport.width - triggerRect.right;
+    const spaceLeft = triggerRect.left;
+    return {
+      top: triggerRect.top + triggerRect.height / 2 - popoverHeight / 2,
+      left: spaceRight >= popoverWidth + offset || spaceRight >= spaceLeft ? triggerRect.right + offset : triggerRect.left - popoverWidth - offset
+    };
+  }
+  if (axis === 'inline' && edge === 'start') {
+    // Left of trigger
+    const spaceLeft = triggerRect.left;
+    const spaceRight = viewport.width - triggerRect.right;
+    return {
+      top: triggerRect.top + triggerRect.height / 2 - popoverHeight / 2,
+      left: spaceLeft >= popoverWidth + offset || spaceLeft >= spaceRight ? triggerRect.left - popoverWidth - offset : triggerRect.right + offset
+    };
+  }
+
+  // Unreachable for valid placements; defaults to below trigger
+  return {
+    top: triggerRect.bottom + offset,
+    left: triggerRect.left + triggerRect.width / 2 - popoverWidth / 2
+  };
+}
+
+/**
+ * Adjusts the base (centered) position for non-center alignments.
+ *
+ * `align: 'start'` → popover start edge at trigger start edge
+ * `align: 'end'`   → popover end edge at trigger end edge
+ */
+function applyAlignment({
+  position,
+  axis,
+  align,
+  triggerRect,
+  popoverWidth,
+  popoverHeight
+}) {
+  if (align === 'center') {
+    return position;
+  }
+  if (axis === 'block') {
+    // Block-axis placement → cross-axis is inline (left/right)
+    if (align === 'start') {
+      return {
+        ...position,
+        left: triggerRect.left
+      };
+    }
+    // align === 'end'
+    return {
+      ...position,
+      left: triggerRect.right - popoverWidth
+    };
+  }
+
+  // Inline-axis placement → cross-axis is block (top/bottom)
+  if (align === 'start') {
+    return {
+      ...position,
+      top: triggerRect.top
+    };
+  }
+  // align === 'end'
+  return {
+    ...position,
+    top: triggerRect.bottom - popoverHeight
+  };
+}
+
+/**
+ * JS fallback: compute popover position from trigger rect and viewport.
+ *
+ * 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.
+ */
+export function computeFallbackPosition({
+  triggerRect,
+  popoverEl,
+  placement,
+  viewport,
+  offset
+}) {
+  const {
+    axis,
+    edge,
+    align
+  } = placement;
+
+  // Measure popover dimensions (it might not have layout yet if just shown)
+  const popoverWidth = popoverEl.offsetWidth;
+  const popoverHeight = popoverEl.offsetHeight;
+  const basePosition = computeEdgePosition({
+    axis,
+    edge,
+    triggerRect,
+    popoverWidth,
+    popoverHeight,
+    viewport,
+    offset
+  });
+  const alignedPosition = applyAlignment({
+    position: basePosition,
+    axis,
+    align,
+    triggerRect,
+    popoverWidth,
+    popoverHeight
+  });
+
+  // Clamp to viewport so the popover is never offscreen
+  return {
+    top: Math.max(0, Math.min(alignedPosition.top, viewport.height - popoverHeight)),
+    left: Math.max(0, Math.min(alignedPosition.left, viewport.width - popoverWidth))
+  };
+}

package/dist/es2019/internal/combine.js

@@ -0,0 +1,18 @@
+/**
+ * Combine multiple cleanup functions into a single cleanup function.
+ *
+ * @example
+ * ```ts
+ * useEffect(() => {
+ *   return combine(
+ *     bind(window, { type: 'resize', listener: onResize }),
+ *     bind(window, { type: 'scroll', listener: onScroll, options: { capture: true } }),
+ *   );
+ * }, []);
+ * ```
+ */
+export function combine(...cleanupFns) {
+  return function cleanup() {
+    cleanupFns.forEach(fn => fn === null || fn === void 0 ? void 0 : fn());
+  };
+}

package/dist/es2019/internal/ensure-preset-styles.js

@@ -0,0 +1,29 @@
+/**
+ * Per-preset CSS injection.
+ *
+ * Each preset's CSS is injected at most once into `<head>`.
+ * Shared by both PopoverContent and DialogContent.
+ *
+ * Note: injected `<style>` elements and the tracking Set are append-only —
+ * they are never removed. This is intentional: the number of distinct
+ * presets is bounded (handful of animation + arrow presets), so the
+ * memory footprint is negligible. Removing styles would risk breaking
+ * other instances of the same preset that are still mounted.
+ *
+ * Decision (2026-03-17 audit): Accepted as a non-issue. The bounded
+ * preset count (~5 presets) makes cleanup unnecessary. We plan to move
+ * to a Compiled-based solution which will handle style injection and
+ * deduplication natively.
+ */
+const injectedPresets = new Set();
+export function ensurePresetStyles({
+  preset
+}) {
+  if (injectedPresets.has(preset.name) || typeof document === 'undefined') {
+    return;
+  }
+  injectedPresets.add(preset.name);
+  const style = document.createElement('style');
+  style.textContent = preset.css;
+  document.head.appendChild(style);
+}

package/dist/es2019/internal/reduced-motion.js

@@ -0,0 +1,21 @@
+import once from '@atlaskit/ds-lib/once';
+
+/**
+ * Returns `true` when the user prefers reduced motion.
+ *
+ * Safe for SSR (returns `false` when `window` is unavailable).
+ *
+ * The result is cached after the first call via `once`. This avoids
+ * calling `matchMedia` on every render. The trade-off is that if a user
+ * toggles the OS reduced-motion setting mid-session, the change won't
+ * take effect until the next page load. This is acceptable because
+ * toggling this system-level preference mid-session is extremely rare,
+ * and a page refresh is a reasonable expectation for system accessibility
+ * settings to take effect.
+ */
+export const prefersReducedMotion = once(() => {
+  if (typeof window === 'undefined' || !('matchMedia' in window)) {
+    return false;
+  }
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+});

package/dist/es2019/internal/resolve-placement.js

@@ -0,0 +1,19 @@
+/**
+ * Fully-resolved placement (internal). All fields are required.
+ * Use getPlacement({ placement: partial }) to obtain from partial input.
+ */
+
+/**
+ * Resolves a partial placement to its fully-specified form.
+ * Defaults: `axis: 'block'`, `edge: 'end'`, `align: 'center'`.
+ */
+export function getPlacement({
+  placement
+}) {
+  var _placement$axis, _placement$edge, _placement$align;
+  return {
+    axis: (_placement$axis = placement.axis) !== null && _placement$axis !== void 0 ? _placement$axis : 'block',
+    edge: (_placement$edge = placement.edge) !== null && _placement$edge !== void 0 ? _placement$edge : 'end',
+    align: (_placement$align = placement.align) !== null && _placement$align !== void 0 ? _placement$align : 'center'
+  };
+}

package/dist/es2019/internal/role-types.js

@@ -0,0 +1,61 @@
+/**
+ * Valid values for the `aria-haspopup` attribute.
+ * Derived from the HTML spec — maps popover roles to what the trigger announces.
+ */
+
+/**
+ * Roles that require an accessible name (`label` or `labelledBy`) per WCAG 4.1.2.
+ * Without a name, assistive technology cannot identify these landmarks.
+ */
+
+/**
+ * Roles where the accessible name is derived from content or provided externally
+ * (e.g. a combobox labels its listbox, tooltip content IS the accessible name).
+ */
+
+// ── Shared ARIA role discrimination types ──
+//
+// These encode the WCAG 4.1.2 constraint: roles like `dialog`, `alertdialog`,
+// and `menu` MUST have an accessible name (either `label` or `labelledBy`).
+// TypeScript enforces this at compile time via discriminated unions.
+
+/**
+ * ARIA role props where a role is always required.
+ *
+ * Used by `TPopupContentProps` — popup content must always declare
+ * its role so assistive technology can identify the layer.
+ */
+
+/**
+ * ARIA role props where a role is optional.
+ *
+ * Used by `TPopoverProps` — the low-level primitive allows omitting
+ * the role for cases where it is set externally or not needed.
+ */
+
+/**
+ * Maps a popover content role to the correct `aria-haspopup` value
+ * for its trigger element.
+ */
+export function roleToAriaHasPopup({
+  role
+}) {
+  if (role === 'menu') {
+    return 'menu';
+  }
+  if (role === 'listbox') {
+    return 'listbox';
+  }
+  if (role === 'tree') {
+    return 'tree';
+  }
+  if (role === 'grid') {
+    return 'grid';
+  }
+  // Default: return 'dialog' for all unmapped roles (tooltip, alertdialog,
+  // note, status, alert, log, etc). This is a kinder API — rather than
+  // throwing on unknown roles, we fall back to the most common popup type.
+  // New roles that need specific aria-haspopup values should be added
+  // as explicit cases above.
+  return 'dialog';
+}

package/dist/es2019/internal/set-style.js

@@ -0,0 +1,39 @@
+/**
+ * Sets inline styles on an element and returns a cleanup function
+ * that removes only the styles that were applied.
+ *
+ * Uses `style.setProperty()` / `style.removeProperty()` so that
+ * hyphenated CSS property names (e.g. `position-area`, `anchor-name`)
+ * work correctly. These newer properties do not have camelCase
+ * mappings in `CSSStyleDeclaration` yet.
+ *
+ * @example
+ * ```ts
+ * const cleanup = setStyle({ el: popover, styles: [
+ *   { property: 'position-anchor', value: '--my-anchor' },
+ *   { property: 'position-area', value: 'block-end' },
+ *   { property: 'margin', value: '0' },
+ * ] });
+ *
+ * // Later: removes all three properties
+ * cleanup();
+ * ```
+ */
+export function setStyle({
+  el,
+  styles
+}) {
+  styles.forEach(({
+    property,
+    value
+  }) => {
+    el.style.setProperty(property, value);
+  });
+  return function cleanup() {
+    styles.forEach(({
+      property
+    }) => {
+      el.style.removeProperty(property);
+    });
+  };
+}

package/dist/es2019/internal/slot.js

@@ -0,0 +1,57 @@
+import { cloneElement, forwardRef, isValidElement } from 'react';
+import mergeRefs from '@atlaskit/ds-lib/merge-refs';
+
+/**
+ * Extra DOM/event props are passed through to the cloned child.
+ */
+
+/**
+ * Single element child: merge the caller ref with `child.ref`.
+ *
+ * Do not read `child.props.ref`: React keeps a `ref` key on `props` for
+ * host elements but accessing it logs a warning and returns `undefined`
+ * (ref lives on the element as `child.ref`).
+ */
+
+function isSlotChild(child) {
+  return /*#__PURE__*/isValidElement(child);
+}
+
+/**
+ * Merges props (including ref) onto a single React element child.
+ *
+ * A safer alternative to raw `cloneElement` that:
+ * 1. Guards with `isValidElement` — non-element children (strings,
+ *    fragments, null) are returned as-is instead of crashing.
+ * 2. Merges refs via `mergeRefs` so both the caller's ref and the
+ *    child's existing ref are honoured.
+ * 3. Spreads any additional props (ARIA attributes, event handlers, etc.)
+ *    onto the child element.
+ *
+ * Event handlers (e.g. `onClick`) are **not** auto-merged — the caller's
+ * handler replaces the child's. Compose handlers before passing them in.
+ *
+ * @example
+ * ```tsx
+ * <Slot ref={triggerRef} onClick={handleClick} aria-expanded={isOpen}>
+ *   <button>Open</button>
+ * </Slot>
+ * ```
+ */
+export const Slot = /*#__PURE__*/forwardRef(function Slot(slotProps, ref) {
+  const {
+    children: rawChildren,
+    ...props
+  } = slotProps;
+  // `SlotProps` intersects `Record<string, unknown>`, so `children` is typed as `unknown`.
+  const children = rawChildren;
+  if (!isSlotChild(children)) {
+    return children;
+  }
+
+  // eslint-disable-next-line @repo/internal/react/no-clone-element -- Slot is a controlled wrapper around cloneElement with isValidElement guard
+  return /*#__PURE__*/cloneElement(children, {
+    ...props,
+    ref: mergeRefs([ref, children.ref])
+  });
+});