@blocdigital/usetoplayerelement 0.0.3 → 0.0.4
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.
|
@@ -31,6 +31,55 @@ if (typeof document !== 'undefined') {
|
|
|
31
31
|
});
|
|
32
32
|
observer.observe(document.body, { childList: true, subtree: true });
|
|
33
33
|
}
|
|
34
|
+
/**
|
|
35
|
+
* React hook to track and interact with elements in the "top layer" (such as dialogs and popovers).
|
|
36
|
+
*
|
|
37
|
+
* This hook provides a ref to attach to your element, and returns information about its position
|
|
38
|
+
* and presence in the top layer, as well as the current list of top layer elements.
|
|
39
|
+
*
|
|
40
|
+
* The top layer is determined by listening for the `toggle` event on dialogs and popovers,
|
|
41
|
+
* and by observing DOM mutations for automatic cleanup.
|
|
42
|
+
*
|
|
43
|
+
* @template T - The type of HTMLElement to track.
|
|
44
|
+
* @returns {useTopLayerElementsReturn<T>} An object containing:
|
|
45
|
+
* - `ref`: React ref to attach to your element.
|
|
46
|
+
* - `topElement`: The topmost element in the top layer.
|
|
47
|
+
* - `topDialog`: The topmost dialog element in the top layer.
|
|
48
|
+
* - `isInTopLayer`: Whether your element is currently in the top layer.
|
|
49
|
+
* - `isTopElement`: Whether your element is the topmost element in the top layer.
|
|
50
|
+
* - `topLayerList`: Array of all elements currently in the top layer.
|
|
51
|
+
*
|
|
52
|
+
* @example
|
|
53
|
+
* ```tsx
|
|
54
|
+
* import useTopLayerElements from './useTopLayerElement';
|
|
55
|
+
*
|
|
56
|
+
* function MyDialog() {
|
|
57
|
+
* const { ref, isInTopLayer, isTopElement } = useTopLayerElements<HTMLDialogElement>();
|
|
58
|
+
*
|
|
59
|
+
* return (
|
|
60
|
+
* <dialog ref={ref} open>
|
|
61
|
+
* {isInTopLayer && <span>I'm in the top layer!</span>}
|
|
62
|
+
* {isTopElement && <span>I'm the topmost dialog!</span>}
|
|
63
|
+
* </dialog>
|
|
64
|
+
* );
|
|
65
|
+
* }
|
|
66
|
+
* ```
|
|
67
|
+
*
|
|
68
|
+
* @example
|
|
69
|
+
* ```tsx
|
|
70
|
+
* import useTopLayerElements from './useTopLayerElement';
|
|
71
|
+
*
|
|
72
|
+
* function MyPopover() {
|
|
73
|
+
* const { ref, topLayerList } = useTopLayerElements<HTMLDivElement>();
|
|
74
|
+
*
|
|
75
|
+
* return (
|
|
76
|
+
* <div ref={ref} popover="auto">
|
|
77
|
+
* <span>Current top layer count: {topLayerList.length}</span>
|
|
78
|
+
* </div>
|
|
79
|
+
* );
|
|
80
|
+
* }
|
|
81
|
+
* ```
|
|
82
|
+
*/
|
|
34
83
|
function useTopLayerElements() {
|
|
35
84
|
const ref = (0, react_1.useRef)(null);
|
|
36
85
|
const [topLayerList, setTopLayerList] = (0, react_1.useState)([...topLayerElements]);
|
|
@@ -28,6 +28,55 @@ if (typeof document !== 'undefined') {
|
|
|
28
28
|
});
|
|
29
29
|
observer.observe(document.body, { childList: true, subtree: true });
|
|
30
30
|
}
|
|
31
|
+
/**
|
|
32
|
+
* React hook to track and interact with elements in the "top layer" (such as dialogs and popovers).
|
|
33
|
+
*
|
|
34
|
+
* This hook provides a ref to attach to your element, and returns information about its position
|
|
35
|
+
* and presence in the top layer, as well as the current list of top layer elements.
|
|
36
|
+
*
|
|
37
|
+
* The top layer is determined by listening for the `toggle` event on dialogs and popovers,
|
|
38
|
+
* and by observing DOM mutations for automatic cleanup.
|
|
39
|
+
*
|
|
40
|
+
* @template T - The type of HTMLElement to track.
|
|
41
|
+
* @returns {useTopLayerElementsReturn<T>} An object containing:
|
|
42
|
+
* - `ref`: React ref to attach to your element.
|
|
43
|
+
* - `topElement`: The topmost element in the top layer.
|
|
44
|
+
* - `topDialog`: The topmost dialog element in the top layer.
|
|
45
|
+
* - `isInTopLayer`: Whether your element is currently in the top layer.
|
|
46
|
+
* - `isTopElement`: Whether your element is the topmost element in the top layer.
|
|
47
|
+
* - `topLayerList`: Array of all elements currently in the top layer.
|
|
48
|
+
*
|
|
49
|
+
* @example
|
|
50
|
+
* ```tsx
|
|
51
|
+
* import useTopLayerElements from './useTopLayerElement';
|
|
52
|
+
*
|
|
53
|
+
* function MyDialog() {
|
|
54
|
+
* const { ref, isInTopLayer, isTopElement } = useTopLayerElements<HTMLDialogElement>();
|
|
55
|
+
*
|
|
56
|
+
* return (
|
|
57
|
+
* <dialog ref={ref} open>
|
|
58
|
+
* {isInTopLayer && <span>I'm in the top layer!</span>}
|
|
59
|
+
* {isTopElement && <span>I'm the topmost dialog!</span>}
|
|
60
|
+
* </dialog>
|
|
61
|
+
* );
|
|
62
|
+
* }
|
|
63
|
+
* ```
|
|
64
|
+
*
|
|
65
|
+
* @example
|
|
66
|
+
* ```tsx
|
|
67
|
+
* import useTopLayerElements from './useTopLayerElement';
|
|
68
|
+
*
|
|
69
|
+
* function MyPopover() {
|
|
70
|
+
* const { ref, topLayerList } = useTopLayerElements<HTMLDivElement>();
|
|
71
|
+
*
|
|
72
|
+
* return (
|
|
73
|
+
* <div ref={ref} popover="auto">
|
|
74
|
+
* <span>Current top layer count: {topLayerList.length}</span>
|
|
75
|
+
* </div>
|
|
76
|
+
* );
|
|
77
|
+
* }
|
|
78
|
+
* ```
|
|
79
|
+
*/
|
|
31
80
|
export default function useTopLayerElements() {
|
|
32
81
|
const ref = useRef(null);
|
|
33
82
|
const [topLayerList, setTopLayerList] = useState([...topLayerElements]);
|
|
@@ -1,9 +1,58 @@
|
|
|
1
|
-
export interface useTopLayerElementsReturn {
|
|
2
|
-
ref: React.RefObject<
|
|
1
|
+
export interface useTopLayerElementsReturn<T extends HTMLElement> {
|
|
2
|
+
ref: React.RefObject<T | null>;
|
|
3
3
|
topElement: HTMLElement | null;
|
|
4
4
|
topDialog: HTMLElement | null;
|
|
5
5
|
isInTopLayer: boolean;
|
|
6
6
|
isTopElement: boolean;
|
|
7
7
|
topLayerList: HTMLElement[];
|
|
8
8
|
}
|
|
9
|
-
|
|
9
|
+
/**
|
|
10
|
+
* React hook to track and interact with elements in the "top layer" (such as dialogs and popovers).
|
|
11
|
+
*
|
|
12
|
+
* This hook provides a ref to attach to your element, and returns information about its position
|
|
13
|
+
* and presence in the top layer, as well as the current list of top layer elements.
|
|
14
|
+
*
|
|
15
|
+
* The top layer is determined by listening for the `toggle` event on dialogs and popovers,
|
|
16
|
+
* and by observing DOM mutations for automatic cleanup.
|
|
17
|
+
*
|
|
18
|
+
* @template T - The type of HTMLElement to track.
|
|
19
|
+
* @returns {useTopLayerElementsReturn<T>} An object containing:
|
|
20
|
+
* - `ref`: React ref to attach to your element.
|
|
21
|
+
* - `topElement`: The topmost element in the top layer.
|
|
22
|
+
* - `topDialog`: The topmost dialog element in the top layer.
|
|
23
|
+
* - `isInTopLayer`: Whether your element is currently in the top layer.
|
|
24
|
+
* - `isTopElement`: Whether your element is the topmost element in the top layer.
|
|
25
|
+
* - `topLayerList`: Array of all elements currently in the top layer.
|
|
26
|
+
*
|
|
27
|
+
* @example
|
|
28
|
+
* ```tsx
|
|
29
|
+
* import useTopLayerElements from './useTopLayerElement';
|
|
30
|
+
*
|
|
31
|
+
* function MyDialog() {
|
|
32
|
+
* const { ref, isInTopLayer, isTopElement } = useTopLayerElements<HTMLDialogElement>();
|
|
33
|
+
*
|
|
34
|
+
* return (
|
|
35
|
+
* <dialog ref={ref} open>
|
|
36
|
+
* {isInTopLayer && <span>I'm in the top layer!</span>}
|
|
37
|
+
* {isTopElement && <span>I'm the topmost dialog!</span>}
|
|
38
|
+
* </dialog>
|
|
39
|
+
* );
|
|
40
|
+
* }
|
|
41
|
+
* ```
|
|
42
|
+
*
|
|
43
|
+
* @example
|
|
44
|
+
* ```tsx
|
|
45
|
+
* import useTopLayerElements from './useTopLayerElement';
|
|
46
|
+
*
|
|
47
|
+
* function MyPopover() {
|
|
48
|
+
* const { ref, topLayerList } = useTopLayerElements<HTMLDivElement>();
|
|
49
|
+
*
|
|
50
|
+
* return (
|
|
51
|
+
* <div ref={ref} popover="auto">
|
|
52
|
+
* <span>Current top layer count: {topLayerList.length}</span>
|
|
53
|
+
* </div>
|
|
54
|
+
* );
|
|
55
|
+
* }
|
|
56
|
+
* ```
|
|
57
|
+
*/
|
|
58
|
+
export default function useTopLayerElements<T extends HTMLElement>(): useTopLayerElementsReturn<T>;
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@blocdigital/usetoplayerelement",
|
|
3
3
|
"type": "module",
|
|
4
|
-
"version": "0.0.
|
|
4
|
+
"version": "0.0.4",
|
|
5
5
|
"description": "React hook for monitoring the top layer",
|
|
6
6
|
"author": "Bloc Digital <web@bloc.digital>",
|
|
7
7
|
"license": "MIT",
|
|
@@ -50,28 +50,28 @@
|
|
|
50
50
|
"test": "jest"
|
|
51
51
|
},
|
|
52
52
|
"devDependencies": {
|
|
53
|
-
"@babel/core": "^7.28.
|
|
54
|
-
"@babel/preset-env": "^7.28.
|
|
53
|
+
"@babel/core": "^7.28.3",
|
|
54
|
+
"@babel/preset-env": "^7.28.3",
|
|
55
55
|
"@babel/preset-typescript": "^7.27.1",
|
|
56
56
|
"@testing-library/react": "^16.3.0",
|
|
57
57
|
"@types/jest": "^30.0.0",
|
|
58
|
-
"@types/react": "^19.1.
|
|
59
|
-
"@types/react-dom": "^19.1.
|
|
60
|
-
"@typescript-eslint/eslint-plugin": "^8.
|
|
61
|
-
"@typescript-eslint/parser": "^8.
|
|
62
|
-
"@vitejs/plugin-react-swc": "^
|
|
63
|
-
"babel-jest": "^30.0.
|
|
64
|
-
"eslint": "^9.
|
|
65
|
-
"eslint-config-prettier": "^10.1.
|
|
66
|
-
"eslint-plugin-prettier": "^5.5.
|
|
58
|
+
"@types/react": "^19.1.11",
|
|
59
|
+
"@types/react-dom": "^19.1.8",
|
|
60
|
+
"@typescript-eslint/eslint-plugin": "^8.41.0",
|
|
61
|
+
"@typescript-eslint/parser": "^8.41.0",
|
|
62
|
+
"@vitejs/plugin-react-swc": "^4.0.1",
|
|
63
|
+
"babel-jest": "^30.0.5",
|
|
64
|
+
"eslint": "^9.34.0",
|
|
65
|
+
"eslint-config-prettier": "^10.1.8",
|
|
66
|
+
"eslint-plugin-prettier": "^5.5.4",
|
|
67
67
|
"eslint-plugin-react-hooks": "^5.2.0",
|
|
68
68
|
"eslint-plugin-react-refresh": "^0.4.20",
|
|
69
69
|
"globals": "^16.3.0",
|
|
70
|
-
"jest": "^30.0.
|
|
71
|
-
"jest-environment-jsdom": "^30.0.
|
|
70
|
+
"jest": "^30.0.5",
|
|
71
|
+
"jest-environment-jsdom": "^30.0.5",
|
|
72
72
|
"prettier": "^3.6.2",
|
|
73
|
-
"typescript": "^5.
|
|
74
|
-
"vite": "^7.
|
|
73
|
+
"typescript": "^5.9.2",
|
|
74
|
+
"vite": "^7.1.3"
|
|
75
75
|
},
|
|
76
76
|
"bugs": {
|
|
77
77
|
"url": "https://github.com/bloc-digital/usetoplayerelement/issues"
|