@alessiofrittoli/react-hooks 1.1.0 → 2.0.0

package/README.md

@@ -25,8 +25,21 @@
 - [ESLint Configuration](#eslint-configuration)
 - [API Reference](#api-reference)
   - [Browser API](#browser-api)
+    - [`useStorage`](#usestorage)
+    - [`useLocalStorage`](#uselocalstorage)
+    - [`useSessionStorage`](#usesessionstorage)
+    - [`useMediaQuery`](#usemediaquery)
+    - [`useDarkMode`](#usedarkmode)
+    - [`useIsPortrait`](#useisportrait)
   - [DOM API](#dom-api)
+    - [`useScrollBlock`](#usescrollblock)
+    - [`useFocusTrap`](#usefocustrap)
+    - [`useInView`](#useinview)
   - [Miscellaneous](#miscellaneous)
+    - [`useIsClient`](#useisclient)
+    - [`useIsFirstRender`](#useisfirstrender)
+    - [`useUpdateEffect`](#useupdateeffect)
+    - [`usePagination`](#usepagination)
 - [Development](#development)
   - [Install depenendencies](#install-depenendencies)
   - [Build the source code](#build-the-source-code)
@@ -105,9 +118,9 @@ Easly handle Local or Session Storage State.
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `key`          | `string`           | - | The storage item key. |
-| `initialValue` | `T`                | - | The storage item initial value. |
-| `type`         | `local\|session`   | local | (Optional) The storage API to use. |
+| `key`     | `string`           | - | The storage item key. |
+| `initial` | `T`                | - | The storage item initial value. |
+| `type`    | `local\|session`   | local | (Optional) The storage API to use. |
 
 </details>
 
@@ -135,14 +148,6 @@ A tuple with the stored item value or initial value and the setter function.
 import {
   useStorage, useLocalStorage, useSessionStorage
 } from '@alessiofrittoli/react-hooks'
-// or
-import {
-  useStorage, useLocalStorage, useSessionStorage
-} from '@alessiofrittoli/react-hooks/browser-api'
-// or
-import {
-  useStorage, useLocalStorage, useSessionStorage
-} from '@alessiofrittoli/react-hooks/browser-api/storage'
 ```
 
 ---
@@ -152,7 +157,7 @@ import {
 ```tsx
 'use client'
 
-import { useStorage } from '@alessiofrittoli/react-hooks/browser-api/storage'
+import { useStorage } from '@alessiofrittoli/react-hooks'
 
 type Locale = 'it' | 'en'
 
@@ -178,7 +183,7 @@ export const SomeComponent: React.FC = () => {
 'use client'
 
 import { useCallback } from 'react'
-import { useStorage } from '@alessiofrittoli/react-hooks/browser-api/storage'
+import { useStorage } from '@alessiofrittoli/react-hooks'
 
 type Locale = 'it' | 'en'
 
@@ -208,7 +213,7 @@ export const LanguageSwitcher: React.FC = () => {
 'use client'
 
 import { useCallback } from 'react'
-import { useStorage } from '@alessiofrittoli/react-hooks/browser-api/storage'
+import { useStorage } from '@alessiofrittoli/react-hooks'
 
 type Locale = 'it' | 'en'
 
@@ -287,20 +292,165 @@ Type: `boolean`
 
 <summary style="cursor:pointer">Usage</summary>
 
-###### Importing the hook
+###### Check if user device prefers dark color scheme
 
 ```tsx
 import { useMediaQuery } from '@alessiofrittoli/react-hooks'
-// or
-import { useMediaQuery } from '@alessiofrittoli/react-hooks/browser-api'
+
+const isDarkOS = useMediaQuery( '(prefers-color-scheme: dark)' )
 ```
 
+</details>
+
 ---
 
-###### Check if user device prefers dark color scheme
+##### `useDarkMode`
+
+Easily manage dark mode with full respect for user device preferences.
+
+This hook is user-oriented and built to honor system-level color scheme settings:
+
+- If the device prefers a dark color scheme, dark mode is automatically enabled on first load.
+- If the user enables/disables dark mode via a web widget, the preference is stored in `localStorage` under the key `dark-mode`.
+- If the device color scheme preference changes (e.g. via OS settings), that change takes precedence and is stored for future visits.
+
+<details>
+
+<summary style="cursor:pointer">Parameters</summary>
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `options` | `UseDarkModeOptions` | (Optional) Configuration object for the hook. |
+| `options.initial` | `boolean` | (Optional) The fallback value to use if no preference is saved in `localStorage`. Defaults to `true` if the device prefers dark mode. |
+| `options.docClassNames` | `[dark: string, light: string]` | (Optional) Array of class names to toggle on the `<html>` element, e.g. `['dark', 'light']`. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Returns</summary>
+
+Type: `UseDarkModeOutput`
+
+An object containing utilities for managing dark mode:
+
+- `isDarkMode`: `boolean` — Whether dark mode is currently enabled.
+- `isDarkOS`: `boolean` — Whether the user's system prefers dark mode.
+- `toggleDarkMode`: `() => void` — Toggles dark mode and saves the preference.
+- `enableDarkMode`: `() => void` — Enables dark mode and saves the preference.
+- `disableDarkMode`: `() => void` — Disables dark mode and saves the preference.
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Usage</summary>
+
+###### Basic usage
 
 ```tsx
-const isDarkOS = useMediaQuery( '(prefers-color-scheme: dark)' )
+'use client'
+
+import { useDarkMode } from '@alessiofrittoli/react-hooks'
+
+export const Component: React.FC = () => {
+  const { isDarkMode } = useDarkMode()
+
+  return (
+    <div>{ isDarkMode ? 'Dark mode enabled' : 'Dark mode disabled' }</div>
+  )
+}
+```
+
+---
+
+###### Update Document class names for CSS styling
+
+```tsx
+// Component.tsx
+'use client'
+
+import { useDarkMode } from '@alessiofrittoli/react-hooks'
+
+export const Component: React.FC = () => {
+  const { isDarkMode } = useDarkMode( {
+    docClassNames: [ 'dark', 'light' ],
+  } )
+
+  return (
+    <div>{ isDarkMode ? 'Dark mode enabled' : 'Dark mode disabled' }</div>
+  )
+}
+```
+
+```css
+/* style.css */
+.light {
+  color-scheme: light;
+}
+
+.dark {
+  color-scheme: dark;
+}
+
+.light body
+{
+  color     : black;
+  background: white;
+}
+
+.dark body
+{
+  color     : white;
+  background: black;
+}
+```
+
+---
+
+###### Custom theme switcher
+
+```tsx
+'use client'
+
+import { useDarkMode } from '@alessiofrittoli/react-hooks'
+
+export const ThemeSwitcher: React.FC = () => {
+  const { isDarkMode, toggleDarkMode } = useDarkMode()
+
+  return (
+    <button onClick={ toggleDarkMode }>
+      { isDarkMode ? '🌙' : '☀️' }
+    </button>
+  )
+}
+```
+
+---
+
+###### Sync Document theme-color for consistent browser styling
+
+Browsers automatically apply colorization using:
+
+```html
+<meta name='theme-color' media='(prefers-color-scheme: dark)' />
+```
+
+This works based on the OS preference — *not your site theme*. That can cause mismatches if, for example, the system is in dark mode but the user disabled dark mode via a web toggle.
+
+To ensure consistency, `useDarkMode` updates these meta tags dynamically based on the actual mode.
+
+Just make sure to define both `light` and `dark` theme-color tags in your document:
+
+```html
+<head>
+  <meta name='theme-color' media='(prefers-color-scheme: light)' content='lime'>
+  <meta name='theme-color' media='(prefers-color-scheme: dark)' content='aqua'>
+</head>
 ```
 
 </details>
@@ -330,19 +480,11 @@ Type: `boolean`
 
 <summary style="cursor:pointer">Usage</summary>
 
-###### Importing the hook
+###### Check if user device is in landscape
 
 ```tsx
 import { useIsPortrait } from '@alessiofrittoli/react-hooks'
-// or
-import { useIsPortrait } from '@alessiofrittoli/react-hooks/browser-api'
-```
 
----
-
-###### Check if user device is in landscape
-
-```tsx
 const isLandscape = ! useIsPortrait()
 ```
 
@@ -384,19 +526,11 @@ A tuple with block and restore scroll callbacks.
 
 <summary style="cursor:pointer">Usage</summary>
 
-###### Importing the hook
+###### Block Document Overflow
 
 ```tsx
 import { useScrollBlock } from '@alessiofrittoli/react-hooks'
-// or
-import { useScrollBlock } from '@alessiofrittoli/react-hooks/dom-api'
-```
 
----
-
-###### Block Document Overflow
-
-```tsx
 const [ blockScroll, restoreScroll ] = useScrollBlock()
 
 const openPopUpHandler = useCallback( () => {
@@ -476,19 +610,11 @@ A tuple containing:
 
 <summary style="cursor:pointer">Usage</summary>
 
-###### Importing the hook
+###### Defining the target on hook initialization
 
 ```tsx
 import { useFocusTrap } from '@alessiofrittoli/react-hooks'
-// or
-import { useFocusTrap } from '@alessiofrittoli/react-hooks/dom-api'
-```
 
----
-
-###### Defining the target on hook initialization
-
-```tsx
 const modalRef = useRef<HTMLDivElement>( null )
 const [ setFocusTrap, restoreFocusTrap ] = useFocusTrap( modalRef )
 
@@ -510,6 +636,8 @@ const modalCloseHandler = useCallback( () => {
 ###### Defining the target ondemand
 
 ```tsx
+import { useFocusTrap } from '@alessiofrittoli/react-hooks'
+
 const modalRef = useRef<HTMLDivElement>( null )
 const modal2Ref = useRef<HTMLDivElement>( null )
 const [ setFocusTrap, restoreFocusTrap ] = useFocusTrap()
@@ -533,6 +661,216 @@ const modal2OpenHandler = useCallback( () => {
 
 ---
 
+##### `useInView`
+
+Check if the given target Element is intersecting with an ancestor Element or with a top-level document's viewport.
+
+<details>
+
+<summary style="cursor:pointer">Parameters</summary>
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `target`  | `React.RefObject<Element\|null>` | The React.RefObject of the target Element to observe. |
+| `options` | `UseInViewOptions` | (Optional) An object defining custom `IntersectionObserver` options. |
+| `options.root` | `Element\|Document\|false\|null` | (Optional) Identifies the `Element` or `Document` whose bounds are treated as the bounding box of the viewport for the Element which is the observer's target. |
+| `options.margin` | `MarginType` | (Optional) A string, formatted similarly to the CSS margin property's value, which contains offsets for one or more sides of the root's bounding box. |
+| `options.amount` | `'all'\|'some'\|number\|number[]` | (Optional) The intersecting target thresholds. |
+| | | Threshold can be set to: |
+| | | - `all` - `1` will be used. |
+| | | - `some` - `0.5` will be used. |
+| | | - `number` |
+| | | - `number[]` |
+| `options.once` | `boolean` | (Optional) By setting this to `true` the observer will be disconnected after the target Element enters the viewport. |
+| `options.initial` | `boolean` | (Optional) Initial value. Default: `false`. |
+| `options.enable` | `boolean` | (Optional) Defines the initial observation activity. Use the returned `setEnabled` to update this state. Default: `true`. |
+| `options.onStart` | `OnStartHandler` | (Optional) A custom callback executed when target element's visibility has crossed one or more thresholds. |
+| | | This callback is awaited before any state update. |
+| | | If an error is thrown the React State update won't be fired. |
+| | | ⚠️ Wrap your callback with `useCallback` to avoid unnecessary `IntersectionObserver` recreation. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Returns</summary>
+
+Type: `UseInViewReturnType`
+
+An object containing:
+
+- `inView`: `boolean` - Indicates whether the target Element is in viewport or not.
+- `setInView`: `React.Dispatch<React.SetStateAction<boolean>>` - A React Dispatch SetState action that allows custom state updates.
+- `enabled`: `boolean` - Indicates whether the target Element is being observed or not.
+- `setEnabled`: `React.Dispatch<React.SetStateAction<boolean>>` - A React Dispatch SetState action that allows to enable/disable observation when needed.
+- `observer`: `IntersectionObserver | undefined` - The `IntersectionObserver` instance. It could be `undefined` if `IntersectionObserver` is not available or observation is not enabled.
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Usage</summary>
+
+###### Basic usage
+
+```tsx
+'use client'
+
+import { useRef } from 'react'
+import { useInView } from '@alessiofrittoli/react-hooks'
+
+const UseInViewExample: React.FC = () => {
+
+  const targetRef   = useRef<HTMLDivElement>( null )
+  const { inView }  = useInView( ref )
+
+  return (
+    Array.from( Array( 6 ) ).map( ( value, index ) => (
+      <div
+        key={ index }
+        style={ {
+          height          : '50vh',
+          border          : '1px solid red',
+          display         : 'flex',
+          alignItems      : 'center',
+          justifyContent  : 'center',
+        } }
+      >
+        <div
+          ref={ index === 2 ? targetRef : undefined }
+          style={ {
+            width           : 150,
+            height          : 150,
+            borderRadius    : 12,
+            display         : 'flex',
+            alignItems      : 'center',
+            justifyContent  : 'center',
+            background      : inView ? '#51AF83' : '#201A1B',
+            color           : inView ? '#201A1B' : '#FFFFFF',
+          } }
+        >{ index + 1 }</div>
+      </div>
+    ) )
+  )
+
+}
+```
+
+---
+
+###### Disconnect observer after target enters the viewport
+
+```tsx
+'use client'
+
+import { useRef } from 'react'
+import { useInView } from '@alessiofrittoli/react-hooks'
+
+const OnceExample: React.FC = () => {
+
+  const targetRef   = useRef<HTMLDivElement>( null )
+  const { inView }  = useInView( targetRef, { once: true } )
+
+  useEffect( () => {
+
+    if ( ! inView ) return
+    console.count( 'Fired only once: element entered viewport.' )
+
+  }, [ inView ] )
+
+  return (
+    <div
+      ref={ targetRef }
+      style={ {
+        height      : 200,
+        background  : inView ? 'lime' : 'gray',
+      } }
+    />
+  )
+
+}
+```
+
+---
+
+###### Observe target only when needed
+
+```tsx
+'use client'
+
+import { useRef } from 'react'
+import { useInView } from '@alessiofrittoli/react-hooks'
+
+const OnDemandObservation: React.FC = () => {
+
+  const targetRef = useRef<HTMLDivElement>( null )
+  const {
+    inView, enabled, setEnabled
+  } = useInView( targetRef, { enable: false } )
+
+  return (
+    <div>
+      <button onClick={ () => setEnabled( prev => ! prev ) }>
+        { enabled ? 'Disconnect observer' : 'Observe' }
+      </button>
+      <div
+        ref={ targetRef }
+        style={ {
+          height      : 200,
+          marginTop   : 50,
+          background  : inView ? 'lime' : 'gray',
+        } }
+      />
+    </div>
+  )
+
+}
+```
+
+---
+
+###### Execute custom callback when intersection occurs
+
+```tsx
+'use client'
+
+import { useRef } from 'react'
+import { useInView, type OnStartHandler } from '@alessiofrittoli/react-hooks'
+
+
+const AsyncStartExample: React.FC = () => {
+
+  const targetRef = useRef<HTMLDivElement>( null )
+  const onStart   = useCallback<OnStartHandler>( async entry => {
+
+    console.log( 'Delaying state update...' )
+    await new Promise( resolve => setTimeout( resolve, 1000 ) ) // Simulate delay
+    console.log( 'Async task completed. `inView` will now be updated.' )
+  
+  }, [] )
+
+  const { inView } = useInView( targetRef, { onStart } )
+
+  return (
+    <div
+      ref={ targetRef }
+      style={ {
+        height      : 200,
+        background  : inView ? 'lime' : 'gray',
+      } }
+    />
+  )
+}
+```
+
+</details>
+
+---
+
 #### Miscellaneous
 
 ##### `useIsClient`
@@ -558,20 +896,12 @@ Type: `boolean`
 
 <summary style="cursor:pointer">Usage</summary>
 
-###### Importing the hook
-
-```tsx
-import { useIsClient } from '@alessiofrittoli/react-hooks'
-// or
-import { useIsClient } from '@alessiofrittoli/react-hooks/misc'
-```
-
 ###### Basic usage
 
 ```tsx
 'use client'
 
-import { useIsClient } from '@alessiofrittoli/react-hooks/misc'
+import { useIsClient } from '@alessiofrittoli/react-hooks'
 
 export const ClientComponent: React.FC = () => {
 
@@ -611,20 +941,12 @@ Note that if the React Hook/Component has no state updates, `useIsFirstRender` w
 
 <summary style="cursor:pointer">Usage</summary>
 
-###### Importing the hook
-
-```tsx
-import { useIsFirstRender } from '@alessiofrittoli/react-hooks'
-// or
-import { useIsFirstRender } from '@alessiofrittoli/react-hooks/misc'
-```
-
 ###### Basic usage
 
 ```tsx
 'use client'
 
-import { useIsFirstRender } from '@alessiofrittoli/react-hooks/misc'
+import { useIsFirstRender } from '@alessiofrittoli/react-hooks'
 
 export const ClientComponent: React.FC = () => {
 
@@ -674,21 +996,13 @@ Modified version of `useEffect` that skips the first render.
 
 <summary style="cursor:pointer">Usage</summary>
 
-###### Importing the hook
-
-```tsx
-import { useUpdateEffect } from '@alessiofrittoli/react-hooks'
-// or
-import { useUpdateEffect } from '@alessiofrittoli/react-hooks/misc'
-```
-
 ###### Basic usage
 
 ```tsx
 'use client'
 
 import { useEffect, useState } from 'react'
-import { useUpdateEffect } from '@alessiofrittoli/react-hooks/misc'
+import { useUpdateEffect } from '@alessiofrittoli/react-hooks'
 
 export const ClientComponent: React.FC = () => {
 

package/dist/eslint.js

@@ -1,2 +1 @@
-'use strict';var n={recommended:[{rules:{"react-hooks/exhaustive-deps":["warn",{additionalHooks:"(useUpdateEffect)"}]}}]};exports.config=n;//# sourceMappingURL=eslint.js.map
-//# sourceMappingURL=eslint.js.map
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var o=["useUpdateEffect"],n= exports.config ={recommended:[{rules:{"react-hooks/exhaustive-deps":["warn",{additionalHooks:o.join("|")}]}}]};exports.config = n;

package/dist/eslint.mjs

@@ -1,2 +1 @@
-var o={recommended:[{rules:{"react-hooks/exhaustive-deps":["warn",{additionalHooks:"(useUpdateEffect)"}]}}]};export{o as config};//# sourceMappingURL=eslint.mjs.map
-//# sourceMappingURL=eslint.mjs.map
+var o=["useUpdateEffect"],i={recommended:[{rules:{"react-hooks/exhaustive-deps":["warn",{additionalHooks:o.join("|")}]}}]};export{i as config};