@blocdigital/usetoplayerelement 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Bloc Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @blocdigital/usetoplayerelement
+
+> React hook for monitoring the top layer.
+
+## Install
+
+```bash
+npm install --save @blocdigital/usetoplayerelement
+```
+
+## Usage
+
+### Hook usage
+
+```tsx
+import { useEffect, createPortal } from 'react';
+
+// Hooks
+import useTopLayerElement from '@blocdigital/usetoplayerelement';
+
+export default function GreatContent({ show = false, className, children }) {
+  // Get the full list of elements in the top layer
+  const { topLayerList } = useTopLayerElement();
+
+  // If there is anything in the top layer prevent scrolling
+  return <SomeComponent preventScroll={Boolean(topLayerList.length)} />;
+}
+```
+
+Example for moving popover element so it is always interactable and on top  
+_**Warning:** It's possible to get caught in an infinite loop if multiple elements are fighting for the top spot._
+
+```tsx
+import { useEffect } from 'react';
+import { createPortal } from 'react-dom';
+
+// Hooks
+import useTopLayerElement from '@blocdigital/usetoplayerelement';
+
+export default function GreatContent({ show = false, children }) {
+  // We get a ref from useTopLayerElement to do specific checks
+  const { ref, isTopElement, topDialog } = useTopLayerElement();
+
+  // Handle show/hide popover
+  useEffect(() => {
+    const { current: el } = ref;
+
+    if (!el) return;
+
+    show ? el.showPopover() : el.hidePopover();
+  }, [show]);
+
+  // Keep element on top
+  useEffect(() => {
+    const { current: el } = ref;
+
+    if (!el || !show || isTopElement) return;
+
+    // Move the popover back on top
+    el.hidePopover();
+    el.showPopover();
+  }, [show, isTopElement]);
+
+  return createPortal(
+    <div ref={ref} popover="manual">
+      {children}
+    </div>,
+    topDialog || document.body,
+  );
+}
+```
+
+#### Event
+
+As an added bonus a `topLayer` event is now fired, you can listen for it on the document and it will tell you which element has entered or left the top layer provided the element is still in the dom. If the element is no longer in the dom the target will be document.

package/dist/cjs/index.js

@@ -0,0 +1,8 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = void 0;
+var useTopLayerElement_1 = require("./useTopLayerElement");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(useTopLayerElement_1).default; } });

package/dist/cjs/useTopLayerElement.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = useTopLayerElements;
+const react_1 = require("react");
+const topLayerElements = new Set();
+// Custom event to notify elements when they are added/removed from the top layer
+const topLayerEvent = (inTopLayer) => new CustomEvent("topLayer", { bubbles: true, detail: { inTopLayer } });
+if (typeof document !== "undefined") {
+    // Listen for elements being added/removed from the top layer
+    document.addEventListener("toggle", ({ target }) => {
+        if (!target)
+            return;
+        const el = target;
+        if (!(el instanceof HTMLDialogElement || el.hasAttribute("popover")))
+            return;
+        if (el.matches(":modal, :popover-open") && document.contains(el)) {
+            topLayerElements.add(el);
+            el.dispatchEvent(topLayerEvent(true));
+        }
+        else {
+            if (topLayerElements.delete(el))
+                el.dispatchEvent(topLayerEvent(false));
+        }
+    }, { capture: true });
+    // MutationObserver for automatic cleanup
+    const observer = new MutationObserver((mutations) => {
+        const nodes = mutations.flatMap(({ removedNodes }) => [...removedNodes]);
+        for (const node of nodes)
+            if (topLayerElements.delete(node))
+                document.dispatchEvent(topLayerEvent(false));
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+}
+function useTopLayerElements() {
+    const ref = (0, react_1.useRef)(null);
+    const [topLayerList, setTopLayerList] = (0, react_1.useState)([
+        ...topLayerElements,
+    ]);
+    const derivedState = (0, react_1.useMemo)(() => {
+        const topElement = topLayerList.length ? topLayerList.at(-1) || null : null;
+        const topDialog = topLayerList.findLast((el) => el.tagName === "DIALOG") || null;
+        const isTopElement = ref.current ? topElement === ref.current : false;
+        const isInTopLayer = ref.current
+            ? topLayerList.includes(ref.current)
+            : false;
+        return { topElement, topDialog, isTopElement, isInTopLayer };
+    }, [topLayerList]);
+    // Listen for top layer changes
+    (0, react_1.useEffect)(() => {
+        const ac = new AbortController();
+        document.addEventListener("topLayer", () => setTopLayerList([...topLayerElements]), { signal: ac.signal });
+        return () => ac.abort();
+    }, []);
+    return (0, react_1.useMemo)(() => ({ ref, ...derivedState, topLayerList }), [derivedState, topLayerList]);
+}

package/dist/esm/index.js

@@ -0,0 +1 @@
+export { default } from './useTopLayerElement';

package/dist/esm/useTopLayerElement.js

@@ -0,0 +1,52 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+const topLayerElements = new Set();
+// Custom event to notify elements when they are added/removed from the top layer
+const topLayerEvent = (inTopLayer) => new CustomEvent("topLayer", { bubbles: true, detail: { inTopLayer } });
+if (typeof document !== "undefined") {
+    // Listen for elements being added/removed from the top layer
+    document.addEventListener("toggle", ({ target }) => {
+        if (!target)
+            return;
+        const el = target;
+        if (!(el instanceof HTMLDialogElement || el.hasAttribute("popover")))
+            return;
+        if (el.matches(":modal, :popover-open") && document.contains(el)) {
+            topLayerElements.add(el);
+            el.dispatchEvent(topLayerEvent(true));
+        }
+        else {
+            if (topLayerElements.delete(el))
+                el.dispatchEvent(topLayerEvent(false));
+        }
+    }, { capture: true });
+    // MutationObserver for automatic cleanup
+    const observer = new MutationObserver((mutations) => {
+        const nodes = mutations.flatMap(({ removedNodes }) => [...removedNodes]);
+        for (const node of nodes)
+            if (topLayerElements.delete(node))
+                document.dispatchEvent(topLayerEvent(false));
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+}
+export default function useTopLayerElements() {
+    const ref = useRef(null);
+    const [topLayerList, setTopLayerList] = useState([
+        ...topLayerElements,
+    ]);
+    const derivedState = useMemo(() => {
+        const topElement = topLayerList.length ? topLayerList.at(-1) || null : null;
+        const topDialog = topLayerList.findLast((el) => el.tagName === "DIALOG") || null;
+        const isTopElement = ref.current ? topElement === ref.current : false;
+        const isInTopLayer = ref.current
+            ? topLayerList.includes(ref.current)
+            : false;
+        return { topElement, topDialog, isTopElement, isInTopLayer };
+    }, [topLayerList]);
+    // Listen for top layer changes
+    useEffect(() => {
+        const ac = new AbortController();
+        document.addEventListener("topLayer", () => setTopLayerList([...topLayerElements]), { signal: ac.signal });
+        return () => ac.abort();
+    }, []);
+    return useMemo(() => ({ ref, ...derivedState, topLayerList }), [derivedState, topLayerList]);
+}

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './useTopLayerElement';
+export type { useTopLayerElementsReturn } from './useTopLayerElement';

package/dist/types/useTopLayerElement.d.ts

@@ -0,0 +1,9 @@
+export interface useTopLayerElementsReturn {
+    ref: React.RefObject<HTMLElement | null>;
+    topElement: HTMLElement | null;
+    topDialog: HTMLElement | null;
+    isInTopLayer: boolean;
+    isTopElement: boolean;
+    topLayerList: HTMLElement[];
+}
+export default function useTopLayerElements(): useTopLayerElementsReturn;

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@blocdigital/usetoplayerelement",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "React hook for monitoring the top layer",
+  "author": "Bloc Digital <web@bloc.digital>",
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "react",
+    "hooks",
+    "top",
+    "layer",
+    "modal",
+    "dialog",
+    "popover"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bloc-digital/usetoplayerelement.git"
+  },
+  "homepage": "https://github.com/bloc-digital/usetoplayerelement#readme",
+  "jest": {
+    "testEnvironment": "jsdom"
+  },
+  "types": "dist/types/index.d.ts",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig-cjs.json && tsc -p tsconfig-types.json",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "preview": "vite preview",
+    "test": "jest"
+  },
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.26.9",
+    "@babel/preset-env": "^7.26.9",
+    "@babel/preset-typescript": "^7.26.0",
+    "@testing-library/react": "^16.2.0",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "@typescript-eslint/eslint-plugin": "^8.24.1",
+    "@typescript-eslint/parser": "^8.24.1",
+    "@vitejs/plugin-react-swc": "^3.8.0",
+    "babel-jest": "^29.7.0",
+    "eslint": "^9.20.1",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.2.3",
+    "eslint-plugin-react": "^7.37.4",
+    "eslint-plugin-react-hooks": "^5.1.0",
+    "eslint-plugin-react-refresh": "^0.4.19",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "prettier": "^3.5.1",
+    "typescript": "^5.7.3",
+    "vite": "^6.1.0"
+  },
+  "bugs": {
+    "url": "https://github.com/bloc-digital/usetoplayerelement/issues"
+  }
+}