@alessiofrittoli/react-hooks 4.0.0 → 4.1.0
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.
- package/README.md +55 -19
- package/dist/index.d.mts +8 -3
- package/dist/index.d.ts +8 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -58,6 +58,7 @@
|
|
|
58
58
|
- [`useIsPortrait`](#useisportrait)
|
|
59
59
|
- [`useIsTouchDevice`](#useistouchdevice)
|
|
60
60
|
- [`useMediaQuery`](#usemediaquery)
|
|
61
|
+
- [`usePreventContextMenu`](#usepreventcontextmenu)
|
|
61
62
|
- [`useDocumentVisibility`](#usedocumentvisibility)
|
|
62
63
|
- [`useWakeLock`](#usewakelock)
|
|
63
64
|
- [DOM API](#dom-api)
|
|
@@ -131,19 +132,20 @@ export default config;
|
|
|
131
132
|
|
|
132
133
|
#### Updates in the latest release 🎉
|
|
133
134
|
|
|
134
|
-
-
|
|
135
|
-
[`NetworkInformation`](https://github.com/alessiofrittoli/web-utils?tab=readme-ov-file#network-information) when available.
|
|
136
|
-
See [API Reference](#useconnection) for more info.
|
|
137
|
-
- Improved `useEventListener` hook types. It now supports `EventTarget` as listener targets.
|
|
138
|
-
See [API Reference](#useeventlistener) for more info.
|
|
135
|
+
- Added `usePreventContextMenu` hook. See [API Reference](#usepreventcontextmenu) for more info.
|
|
139
136
|
|
|
140
137
|
---
|
|
141
138
|
|
|
142
139
|
Old updates
|
|
143
140
|
|
|
144
|
-
-
|
|
145
|
-
|
|
146
|
-
|
|
141
|
+
- Improved `useConnection` hook. It now returns
|
|
142
|
+
[`NetworkInformation`](https://github.com/alessiofrittoli/web-utils?tab=readme-ov-file#network-information) when available.
|
|
143
|
+
See [API Reference](#useconnection) for more info.
|
|
144
|
+
- Improved `useEventListener` hook types. It now supports `EventTarget` as listener targets.
|
|
145
|
+
See [API Reference](#useeventlistener) for more info.
|
|
146
|
+
- Added `useDocumentVisibility` hook. See [API Reference](#usedocumentvisibility) for more info.
|
|
147
|
+
- Added `useWakeLock` hook. See [API Reference](#usewakelock) for more info.
|
|
148
|
+
- Added `useDeferCallback` hook. See [API Reference](#usedefercallback) for more info.
|
|
147
149
|
|
|
148
150
|
---
|
|
149
151
|
|
|
@@ -578,17 +580,17 @@ Attach a new Event listener to the `Window`, `Document`, `MediaQueryList` or an
|
|
|
578
580
|
|
|
579
581
|
<summary style="cursor:pointer">Custom events</summary>
|
|
580
582
|
|
|
581
|
-
| Parameter | Type
|
|
582
|
-
| ------------------- |
|
|
583
|
-
| `type` | `K\|K[]`
|
|
584
|
-
| |
|
|
585
|
-
| |
|
|
586
|
-
| `options` | `CustomEventListenerOptions<T, K>`
|
|
587
|
-
| `options.target` | `Document\|HTMLElement\|null\|React.RefObject<Document\|HTMLElement\|null>` | (Optional) The target where the listener get attached to. If not set, the listener will get attached to the `Window` object. |
|
|
588
|
-
| `options.listener` | `( event: T[ K ] ) => void`
|
|
589
|
-
| `options.onLoad` | `() => void`
|
|
590
|
-
| `options.onCleanUp` | `() => void`
|
|
591
|
-
| `options.options` | `ListenerOptions`
|
|
583
|
+
| Parameter | Type | Description |
|
|
584
|
+
| ------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
585
|
+
| `type` | `K\|K[]` | The custom event name or an array of event names. |
|
|
586
|
+
| | | ⚠️ Please, make sure to memoize the event names array with `useMemo` |
|
|
587
|
+
| | | or declare that array outside your Component/hook in order to avoid infinite loops when a React state changes. |
|
|
588
|
+
| `options` | `CustomEventListenerOptions<T, K>` | An object defining init options. |
|
|
589
|
+
| `options.target` | `Document\|EventTarget\|HTMLElement\|null\|React.RefObject<Document\|HTMLElement\|null>` | (Optional) The target where the listener get attached to. If not set, the listener will get attached to the `Window` object. |
|
|
590
|
+
| `options.listener` | `( event: T[ K ] ) => void` | The Event listener. |
|
|
591
|
+
| `options.onLoad` | `() => void` | A custom callback executed before event listener get attached. |
|
|
592
|
+
| `options.onCleanUp` | `() => void` | A custom callback executed after event listener get removed. |
|
|
593
|
+
| `options.options` | `ListenerOptions` | Specifies characteristics about the event listener. See [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options). |
|
|
592
594
|
|
|
593
595
|
</details>
|
|
594
596
|
|
|
@@ -899,6 +901,40 @@ useMediaQuery("(prefers-color-scheme: dark)", {
|
|
|
899
901
|
|
|
900
902
|
---
|
|
901
903
|
|
|
904
|
+
##### `usePreventContextMenu`
|
|
905
|
+
|
|
906
|
+
Prevents the context menu from appearing on a specified target element.
|
|
907
|
+
|
|
908
|
+
<details>
|
|
909
|
+
|
|
910
|
+
<summary style="cursor:pointer">Parameters</summary>
|
|
911
|
+
|
|
912
|
+
| Parameter | Type | Default | Description |
|
|
913
|
+
| --------- | ----------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- |
|
|
914
|
+
| `target` | `EventListenerTarget\|React.RefObject<EventListenerTarget>` | `window` | The target element or a `React.RefObject` where the context menu should be prevented. |
|
|
915
|
+
| | | | If not provided, the listener will be attached to the top `window`. |
|
|
916
|
+
|
|
917
|
+
</details>
|
|
918
|
+
|
|
919
|
+
---
|
|
920
|
+
|
|
921
|
+
<details>
|
|
922
|
+
|
|
923
|
+
<summary style="cursor:pointer">Examples</summary>
|
|
924
|
+
|
|
925
|
+
```tsx
|
|
926
|
+
// Prevent context menu on the entire top window.
|
|
927
|
+
usePreventContextMenu();
|
|
928
|
+
|
|
929
|
+
// Prevent context menu on a specific target.
|
|
930
|
+
const ref = useRef<HTMLDivElement>(null);
|
|
931
|
+
usePreventContextMenu(ref);
|
|
932
|
+
```
|
|
933
|
+
|
|
934
|
+
</details>
|
|
935
|
+
|
|
936
|
+
---
|
|
937
|
+
|
|
902
938
|
##### `useDocumentVisibility`
|
|
903
939
|
|
|
904
940
|
Track the visibility state of the document (i.e., whether the page is visible or hidden).
|
package/dist/index.d.mts
CHANGED
|
@@ -149,7 +149,7 @@ declare function useDocumentVisibility(otpions: StateDisabledUseDocumentVisibili
|
|
|
149
149
|
*/
|
|
150
150
|
declare function useDocumentVisibility(otpions?: UseDocumentVisibilityOptions): boolean;
|
|
151
151
|
|
|
152
|
-
type EventListenerTarget = (Document | HTMLElement | EventTarget | null | undefined);
|
|
152
|
+
type EventListenerTarget = (Window | Document | HTMLElement | EventTarget | null | undefined);
|
|
153
153
|
/**
|
|
154
154
|
* Specifies characteristics about the event listener.
|
|
155
155
|
*
|
|
@@ -258,6 +258,11 @@ interface CommonListenerOptions {
|
|
|
258
258
|
options?: ListenerOptions;
|
|
259
259
|
}
|
|
260
260
|
interface WindowListenerOptions<K extends keyof WindowEventMap> extends CommonListenerOptions {
|
|
261
|
+
/**
|
|
262
|
+
* Optionally defines a `Window` context.
|
|
263
|
+
*
|
|
264
|
+
*/
|
|
265
|
+
target?: Window;
|
|
261
266
|
/**
|
|
262
267
|
* The Window Event listener.
|
|
263
268
|
*
|
|
@@ -312,7 +317,7 @@ interface MediaQueryListenerOptions extends CommonListenerOptions {
|
|
|
312
317
|
*/
|
|
313
318
|
listener: MediaQueryChangeListener;
|
|
314
319
|
}
|
|
315
|
-
interface CustomEventListenerOptions<T extends Record<string,
|
|
320
|
+
interface CustomEventListenerOptions<T extends Record<string, U>, K extends keyof T = keyof T, U extends Event = Event> extends CommonListenerOptions {
|
|
316
321
|
/**
|
|
317
322
|
* The target where the listener get attached to.
|
|
318
323
|
*
|
|
@@ -564,7 +569,7 @@ declare function useEventListener(type: 'change', options: MediaQueryListenerOpt
|
|
|
564
569
|
* }, [] )
|
|
565
570
|
*```
|
|
566
571
|
*/
|
|
567
|
-
declare function useEventListener<T extends Record<string,
|
|
572
|
+
declare function useEventListener<T extends Record<string, U>, K extends keyof T = keyof T, U extends Event = Event>(type: K | K[], options: CustomEventListenerOptions<T, K>): void;
|
|
568
573
|
|
|
569
574
|
/**
|
|
570
575
|
* Check if device is portrait oriented.
|
package/dist/index.d.ts
CHANGED
|
@@ -149,7 +149,7 @@ declare function useDocumentVisibility(otpions: StateDisabledUseDocumentVisibili
|
|
|
149
149
|
*/
|
|
150
150
|
declare function useDocumentVisibility(otpions?: UseDocumentVisibilityOptions): boolean;
|
|
151
151
|
|
|
152
|
-
type EventListenerTarget = (Document | HTMLElement | EventTarget | null | undefined);
|
|
152
|
+
type EventListenerTarget = (Window | Document | HTMLElement | EventTarget | null | undefined);
|
|
153
153
|
/**
|
|
154
154
|
* Specifies characteristics about the event listener.
|
|
155
155
|
*
|
|
@@ -258,6 +258,11 @@ interface CommonListenerOptions {
|
|
|
258
258
|
options?: ListenerOptions;
|
|
259
259
|
}
|
|
260
260
|
interface WindowListenerOptions<K extends keyof WindowEventMap> extends CommonListenerOptions {
|
|
261
|
+
/**
|
|
262
|
+
* Optionally defines a `Window` context.
|
|
263
|
+
*
|
|
264
|
+
*/
|
|
265
|
+
target?: Window;
|
|
261
266
|
/**
|
|
262
267
|
* The Window Event listener.
|
|
263
268
|
*
|
|
@@ -312,7 +317,7 @@ interface MediaQueryListenerOptions extends CommonListenerOptions {
|
|
|
312
317
|
*/
|
|
313
318
|
listener: MediaQueryChangeListener;
|
|
314
319
|
}
|
|
315
|
-
interface CustomEventListenerOptions<T extends Record<string,
|
|
320
|
+
interface CustomEventListenerOptions<T extends Record<string, U>, K extends keyof T = keyof T, U extends Event = Event> extends CommonListenerOptions {
|
|
316
321
|
/**
|
|
317
322
|
* The target where the listener get attached to.
|
|
318
323
|
*
|
|
@@ -564,7 +569,7 @@ declare function useEventListener(type: 'change', options: MediaQueryListenerOpt
|
|
|
564
569
|
* }, [] )
|
|
565
570
|
*```
|
|
566
571
|
*/
|
|
567
|
-
declare function useEventListener<T extends Record<string,
|
|
572
|
+
declare function useEventListener<T extends Record<string, U>, K extends keyof T = keyof T, U extends Event = Event>(type: K | K[], options: CustomEventListenerOptions<T, K>): void;
|
|
568
573
|
|
|
569
574
|
/**
|
|
570
575
|
* Check if device is portrait oriented.
|