@atlaskit/top-layer 0.2.0 → 0.4.0

package/dist/esm/testing/to-be-visible.js

@@ -0,0 +1,89 @@
+/* eslint-disable compat/compat */
+/* global expect */
+/**
+ * Patches `toBeVisible()` to understand popover and dialog visibility.
+ *
+ * jest-dom's `toBeVisible()` does not know about the Popover API. In real
+ * browsers the UA stylesheet hides `[popover]` with `display: none`, but
+ * jsdom has no such stylesheet — so closed popovers incorrectly appear visible.
+ *
+ * Raw jest-dom results in jsdom:
+ *
+ *   closed popover / child  → true  (WRONG — should be false)
+ *   open popover / child    → true  (correct)
+ *   closed dialog / child   → false (correct — jsdom natively hides <dialog>)
+ *   open dialog / child     → true  (correct)
+ *
+ * We correct both false positives and false negatives:
+ *   1. Delegate to the original first.
+ *   2. If it says "visible" → check for closed top-layer hosts (false positive).
+ *   3. If it says "not visible" → check for open top-layer hosts (false negative).
+ *
+ * Must load via `setupFilesAfterEnv` (after jest-dom registers its matchers).
+ * Polyfills live in `./polyfill` (loaded via `setupFiles`).
+ */
+
+// Delegating to jest-dom's matcher; types come from @testing-library/jest-dom.
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { toBeVisible as originalToBeVisible } from '@testing-library/jest-dom/matchers';
+/**
+ * Finds the nearest popover or dialog ancestor (including the element itself)
+ * and returns its state: 'open', 'closed', or null if no top-layer ancestor exists.
+ *
+ * Checking the *nearest* ancestor handles nesting correctly:
+ * a closed popover inside an open popover → nearest is closed → not visible.
+ */
+function nearestTopLayerState(element) {
+  if (!element) {
+    return null;
+  }
+  if (element.hasAttribute('popover')) {
+    return element.hasAttribute('data-popover-open') ? 'open' : 'closed';
+  }
+  if (element.nodeName === 'DIALOG') {
+    return element.hasAttribute('open') ? 'open' : 'closed';
+  }
+  return nearestTopLayerState(element.parentElement);
+}
+function getNearestTopLayerType(element) {
+  if (!element.closest) {
+    return 'top-layer element';
+  }
+  if (element.closest('[popover]')) {
+    return 'popover';
+  }
+  return 'dialog';
+}
+
+// `expect` is registered globally by jest before this file runs.
+
+expect.extend({
+  toBeVisible: function toBeVisible(element) {
+    var originalResult = originalToBeVisible.call(this, element);
+    var topLayerState = nearestTopLayerState(element);
+    if (originalResult.pass) {
+      // Original says visible — override if nearest top-layer host is closed.
+      if (topLayerState === 'closed') {
+        return {
+          pass: false,
+          message: function message() {
+            return "expected element to be visible, but it is inside a closed ".concat(getNearestTopLayerType(element));
+          }
+        };
+      }
+      return originalResult;
+    }
+
+    // Original says not visible — override if nearest top-layer host is open.
+    // jsdom may hide [popover] elements even when they are logically open.
+    if (topLayerState === 'open') {
+      return {
+        pass: true,
+        message: function message() {
+          return "expected element not to be visible, but it is inside an open ".concat(getNearestTopLayerType(element));
+        }
+      };
+    }
+    return originalResult;
+  }
+});

package/dist/types/testing/polyfill.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Popover API & HTMLDialogElement polyfills for jsdom.
+ *
+ * jsdom does not implement the Popover API or the HTMLDialogElement methods
+ * (showModal, show, close). This polyfill provides faithful implementations,
+ * including timing semantics validated against Chromium via Playwright.
+ *
+ * Behaviour:
+ *  - beforetoggle: sync, cancelable on popover show only. toggle: async task, never cancelable.
+ *  - Rapid show/hide coalesces into one toggle event (originalOldState to finalNewState).
+ *  - Dialog: showModal/show fire beforetoggle+toggle. close fires toggle then close event.
+ *  - Popover open state tracked via `data-popover-open` (no `:popover-open` in jsdom).
+ *  - Auto popovers: maintain an open stack, perform light-dismiss on document mousedown
+ *    outside the open chain, and dismiss the topmost on Escape.
+ *  - On open, removes any inline `opacity: 0` from the popover element so callers that
+ *    rely on a `ResizeObserver` reveal callback (e.g. `use-anchor-positioning`) become
+ *    visible in jsdom, where layout-driven RO callbacks never fire.
+ *
+ * Companion `toBeVisible` patch lives at `./to-be-visible`.
+ *
+ * Importing this module has the side-effect of patching the relevant
+ * prototypes. It is safe to import multiple times; each branch is guarded
+ * to avoid overwriting native implementations or re-patching.
+ */
+export {};

package/dist/types/testing/to-be-visible.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Patches `toBeVisible()` to understand popover and dialog visibility.
+ *
+ * jest-dom's `toBeVisible()` does not know about the Popover API. In real
+ * browsers the UA stylesheet hides `[popover]` with `display: none`, but
+ * jsdom has no such stylesheet — so closed popovers incorrectly appear visible.
+ *
+ * Raw jest-dom results in jsdom:
+ *
+ *   closed popover / child  → true  (WRONG — should be false)
+ *   open popover / child    → true  (correct)
+ *   closed dialog / child   → false (correct — jsdom natively hides <dialog>)
+ *   open dialog / child     → true  (correct)
+ *
+ * We correct both false positives and false negatives:
+ *   1. Delegate to the original first.
+ *   2. If it says "visible" → check for closed top-layer hosts (false positive).
+ *   3. If it says "not visible" → check for open top-layer hosts (false negative).
+ *
+ * Must load via `setupFilesAfterEnv` (after jest-dom registers its matchers).
+ * Polyfills live in `./polyfill` (loaded via `setupFiles`).
+ */
+export {};

package/dist/types-ts4.5/testing/polyfill.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Popover API & HTMLDialogElement polyfills for jsdom.
+ *
+ * jsdom does not implement the Popover API or the HTMLDialogElement methods
+ * (showModal, show, close). This polyfill provides faithful implementations,
+ * including timing semantics validated against Chromium via Playwright.
+ *
+ * Behaviour:
+ *  - beforetoggle: sync, cancelable on popover show only. toggle: async task, never cancelable.
+ *  - Rapid show/hide coalesces into one toggle event (originalOldState to finalNewState).
+ *  - Dialog: showModal/show fire beforetoggle+toggle. close fires toggle then close event.
+ *  - Popover open state tracked via `data-popover-open` (no `:popover-open` in jsdom).
+ *  - Auto popovers: maintain an open stack, perform light-dismiss on document mousedown
+ *    outside the open chain, and dismiss the topmost on Escape.
+ *  - On open, removes any inline `opacity: 0` from the popover element so callers that
+ *    rely on a `ResizeObserver` reveal callback (e.g. `use-anchor-positioning`) become
+ *    visible in jsdom, where layout-driven RO callbacks never fire.
+ *
+ * Companion `toBeVisible` patch lives at `./to-be-visible`.
+ *
+ * Importing this module has the side-effect of patching the relevant
+ * prototypes. It is safe to import multiple times; each branch is guarded
+ * to avoid overwriting native implementations or re-patching.
+ */
+export {};

package/dist/types-ts4.5/testing/to-be-visible.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Patches `toBeVisible()` to understand popover and dialog visibility.
+ *
+ * jest-dom's `toBeVisible()` does not know about the Popover API. In real
+ * browsers the UA stylesheet hides `[popover]` with `display: none`, but
+ * jsdom has no such stylesheet — so closed popovers incorrectly appear visible.
+ *
+ * Raw jest-dom results in jsdom:
+ *
+ *   closed popover / child  → true  (WRONG — should be false)
+ *   open popover / child    → true  (correct)
+ *   closed dialog / child   → false (correct — jsdom natively hides <dialog>)
+ *   open dialog / child     → true  (correct)
+ *
+ * We correct both false positives and false negatives:
+ *   1. Delegate to the original first.
+ *   2. If it says "visible" → check for closed top-layer hosts (false positive).
+ *   3. If it says "not visible" → check for open top-layer hosts (false negative).
+ *
+ * Must load via `setupFilesAfterEnv` (after jest-dom registers its matchers).
+ * Polyfills live in `./polyfill` (loaded via `setupFiles`).
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/top-layer",
-	"version": "0.2.0",
+	"version": "0.4.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,13 +52,14 @@
 		"@af/visual-regression": "workspace:^",
 		"@atlaskit/button": "^23.11.0",
 		"@atlaskit/heading": "^5.4.0",
-		"@atlaskit/lozenge": "^13.7.0",
+		"@atlaskit/lozenge": "^13.8.0",
 		"@atlaskit/primitives": "^19.0.0",
 		"@atlaskit/ssr": "workspace:^",
 		"@atlaskit/textfield": "^8.3.0",
 		"@atlassian/react-compiler-gating": "workspace:^",
 		"@atlassian/ssr-tests": "workspace:^",
 		"@atlassian/testing-library": "^0.5.0",
+		"@testing-library/jest-dom": "^6.4.5",
 		"@testing-library/react": "^16.3.0",
 		"@types/raf-schd": "^4.0.1",
 		"tiny-invariant": "^1.2.0"

package/testing/polyfill/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@atlaskit/top-layer/testing/polyfill",
+  "main": "../../dist/cjs/testing/polyfill.js",
+  "module": "../../dist/esm/testing/polyfill.js",
+  "module:es2019": "../../dist/es2019/testing/polyfill.js",
+  "sideEffects": [
+    "*.compiled.css"
+  ],
+  "types": "../../dist/types/testing/polyfill.d.ts",
+  "typesVersions": {
+    ">=4.5 <5.9": {
+      "*": [
+        "../../dist/types-ts4.5/testing/polyfill.d.ts"
+      ]
+    }
+  }
+}

package/testing/to-be-visible/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@atlaskit/top-layer/testing/to-be-visible",
+  "main": "../../dist/cjs/testing/to-be-visible.js",
+  "module": "../../dist/esm/testing/to-be-visible.js",
+  "module:es2019": "../../dist/es2019/testing/to-be-visible.js",
+  "sideEffects": [
+    "*.compiled.css"
+  ],
+  "types": "../../dist/types/testing/to-be-visible.d.ts",
+  "typesVersions": {
+    ">=4.5 <5.9": {
+      "*": [
+        "../../dist/types-ts4.5/testing/to-be-visible.d.ts"
+      ]
+    }
+  }
+}