@pelatform/ui.hook 0.1.3 → 0.2.1

package/README.md

@@ -3,7 +3,7 @@
 [![Version](https://img.shields.io/npm/v/@pelatform/ui.hook.svg)](https://www.npmjs.com/package/@pelatform/ui.hook)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A collection of production-ready React hooks for the Pelatform UI Library. This package provides 15 reusable hooks for analytics, responsive design, form handling, navigation, DOM management, and more.
+A collection of production-ready React hooks for the Pelatform UI Library. This package provides 18 reusable hooks for analytics, responsive design, form handling, navigation, DOM management, and more.
 
 ## Installation
 
@@ -67,6 +67,37 @@ import { useViewport } from "@pelatform/ui.hook";
 const [height, width] = useViewport();
 ```
 
+#### `useIntersectionObserver`
+
+Observe element intersection with viewport using Intersection Observer API.
+
+```typescript
+import { useIntersectionObserver } from "@pelatform/ui.hook";
+
+const ref = useRef<HTMLDivElement>(null);
+const { isIntersecting, entry } = useIntersectionObserver(ref, {
+  threshold: 0.5,
+  triggerOnce: true,
+});
+
+<div ref={ref}>
+  {isIntersecting ? "Visible!" : "Not visible"}
+</div>
+```
+
+#### `useIsMac`
+
+Detect if the user's operating system is macOS.
+
+```typescript
+import { useIsMac } from "@pelatform/ui.hook";
+
+const isMac = useIsMac();
+
+// Useful for keyboard shortcut hints (⌘ vs Ctrl)
+<div>Press {isMac ? "⌘" : "Ctrl"} + K to open command menu</div>
+```
+
 ### Form & Input Management
 
 #### `useFileUpload`
@@ -151,14 +182,14 @@ const elementScroll = useScrollPosition({ targetRef: myRef });
 
 ### DOM Management
 
-#### `useBodyClasses`
+#### `useBodyClass`
 
 Dynamically add/remove CSS classes from the document body element.
 
 ```typescript
-import { useBodyClasses } from "@pelatform/ui.hook";
+import { useBodyClass } from "@pelatform/ui.hook";
 
-useBodyClasses("dark-theme overflow-hidden");
+useBodyClass("dark-theme overflow-hidden");
 ```
 
 #### `useMutationObserver`
@@ -245,7 +276,8 @@ useRemoveGAParams(); // Cleans URL after GA processes linker attribution
 - **Responsive Design**: `useMediaQuery`, `useIsMobile`, `useViewport`
 - **Form Management**: `useFileUpload`, `useSliderInput`, `useCopyToClipboard`
 - **Navigation**: `useMenu`, `useScrollPosition`
-- **DOM Interaction**: `useMutationObserver`, `useBodyClasses`
+- **DOM Interaction**: `useMutationObserver`, `useBodyClass`, `useIntersectionObserver`
+- **Platform Detection**: `useIsMac`
 - **Security**: `useRecaptchaV2`
 - **SSR Safety**: `useMounted`, `useHydrated`, `useRemoveGAParams`
 
@@ -255,12 +287,14 @@ useRemoveGAParams(); // Cleans URL after GA processes linker attribution
 
 - `useMounted`
 - `useHydrated`
-- `useBodyClasses`
+- `useBodyClass`
 - `useRemoveGAParams`
 - `useMediaQuery`
 - `useIsMobile`
+- `useIsMac`
 - `useViewport`
 - `useScrollPosition`
+- `useIntersectionObserver`
 
 **Moderate** (State Management):
 

package/dist/index.d.ts

@@ -421,6 +421,91 @@ declare const formatBytes: (bytes: number, decimals?: number) => string;
  */
 declare function useHydrated(): boolean;
 
+/**
+ * Intersection observer hook for React components
+ * Efficiently observes visibility of DOM elements using a shared IntersectionObserver instance.
+ * Ideal for lazy loading, infinite scrolling, and animating elements when they enter the viewport.
+ */
+
+/**
+ * Configuration options for the `useIntersectionObserver` hook.
+ *
+ * Extends the native `IntersectionObserverInit` options with an additional
+ * convenience flag for freezing the observer state.
+ */
+interface IntersectionObserverOptions extends IntersectionObserverInit {
+    /**
+     * When `true`, the hook stops observing once the element becomes visible
+     * and keeps returning `true` for subsequent renders.
+     *
+     * This is useful for one-time animations or lazy loading where you only
+     * care about the first time an element enters the viewport.
+     */
+    freezeOnceVisible?: boolean;
+}
+/**
+ * React hook that tracks whether a DOM element is currently intersecting the viewport.
+ *
+ * Features:
+ * - Uses a shared `IntersectionObserver` instance for better performance.
+ * - Supports custom `threshold`, `root`, and `rootMargin` options.
+ * - Optional `freezeOnceVisible` flag to stop observing after first intersection.
+ *
+ * @param elementRef - React ref pointing to the DOM element to observe.
+ * @param options - Optional observer configuration and behavior flags.
+ * @param options.threshold - Intersection threshold(s) for triggering visibility changes.
+ * @param options.root - Scrollable ancestor element to use as the viewport (defaults to browser viewport).
+ * @param options.rootMargin - Margin around the root, expressed in CSS units (e.g. `"0px 0px -20% 0px"`).
+ * @param options.freezeOnceVisible - When `true`, stops observing after the element first becomes visible.
+ *
+ * @returns `true` when the element is intersecting based on the given options, otherwise `false`.
+ *
+ * @example
+ * ```tsx
+ * const ref = React.useRef<HTMLDivElement | null>(null);
+ * const isVisible = useIntersectionObserver(ref, {
+ *   threshold: 0.2,
+ *   rootMargin: "0px 0px -10% 0px",
+ *   freezeOnceVisible: true,
+ * });
+ *
+ * return (
+ *   <div ref={ref} className={isVisible ? "animate-in" : "opacity-0"}>
+ *     I will animate when I enter the viewport.
+ *   </div>
+ * );
+ * ```
+ */
+declare function useIntersectionObserver(elementRef: React.RefObject<Element | null>, { threshold, root, rootMargin, freezeOnceVisible, }?: IntersectionObserverOptions): boolean;
+
+/**
+ * Platform detection hook for React components
+ * Determines whether the current user agent is running on a macOS device.
+ * Useful for rendering platform-specific keyboard shortcuts or UI variations.
+ */
+/**
+ * React hook that returns whether the current platform is macOS.
+ *
+ * This hook:
+ * - Runs only on the client (browser) side.
+ * - Checks `navigator.platform` and normalizes the value to uppercase.
+ * - Returns a boolean indicating if the platform contains `"MAC"`.
+ *
+ * @returns `true` if the current platform is macOS, otherwise `false`.
+ *
+ * @example
+ * ```tsx
+ * const isMac = useIsMac();
+ *
+ * return (
+ *   <kbd>
+ *     {isMac ? "⌘" : "Ctrl"} + K
+ *   </kbd>
+ * );
+ * ```
+ */
+declare function useIsMac(): boolean;
+
 /**
  * Media query hook for responsive React components
  * Provides real-time tracking of CSS media query matches
@@ -1108,4 +1193,4 @@ type ViewportDimensions = [number, number];
  */
 declare const useViewport: () => ViewportDimensions;
 
-export { type FileMetadata, type FileUploadActions, type FileUploadOptions, type FileUploadState, type FileWithPreview, type GtagWindow, formatBytes, useAnalytics, useBodyClasses, useCopyToClipboard, useFileUpload, useHydrated, useIsMobile, useMediaQuery, useMenu, useMounted, useMutationObserver, useRecaptchaV2, useRemoveGAParams, useScrollPosition, useSliderInput, useViewport };
+export { type FileMetadata, type FileUploadActions, type FileUploadOptions, type FileUploadState, type FileWithPreview, type GtagWindow, formatBytes, useAnalytics, useBodyClasses, useCopyToClipboard, useFileUpload, useHydrated, useIntersectionObserver, useIsMac, useIsMobile, useMediaQuery, useMenu, useMounted, useMutationObserver, useRecaptchaV2, useRemoveGAParams, useScrollPosition, useSliderInput, useViewport };

package/dist/index.js

@@ -413,7 +413,7 @@ var formatBytes = (bytes, decimals = 2) => {
   return Number.parseFloat((bytes / k ** i).toFixed(dm)) + sizes[i];
 };
 
-// src/use-hydrated.tsx
+// src/use-hydrated.ts
 import { useSyncExternalStore } from "react";
 function useHydrated() {
   return useSyncExternalStore(
@@ -427,8 +427,88 @@ function subscribe() {
   };
 }
 
+// src/use-intersection-observer.ts
+import * as React2 from "react";
+var SharedObserver = class {
+  observer = null;
+  callbacks = /* @__PURE__ */ new Map();
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  getObserver() {
+    if (!this.observer) {
+      this.observer = new IntersectionObserver((entries) => {
+        entries.forEach((entry) => {
+          const callback = this.callbacks.get(entry.target);
+          if (callback) {
+            callback(entry.isIntersecting);
+          }
+        });
+      }, this.options);
+    }
+    return this.observer;
+  }
+  observe(element, callback) {
+    this.callbacks.set(element, callback);
+    this.getObserver().observe(element);
+  }
+  unobserve(element) {
+    this.callbacks.delete(element);
+    this.observer?.unobserve(element);
+  }
+  disconnect() {
+    this.observer?.disconnect();
+    this.callbacks.clear();
+    this.observer = null;
+  }
+};
+var observers = /* @__PURE__ */ new Map();
+function getSharedObserver(options) {
+  const key = JSON.stringify(options);
+  if (!observers.has(key)) {
+    observers.set(key, new SharedObserver(options));
+  }
+  return observers.get(key);
+}
+function useIntersectionObserver(elementRef, {
+  threshold = 0,
+  root = null,
+  rootMargin = "0%",
+  freezeOnceVisible = false
+} = {}) {
+  const [isIntersecting, setIntersecting] = React2.useState(false);
+  const frozen = React2.useRef(false);
+  React2.useEffect(() => {
+    const element = elementRef?.current;
+    if (!element || freezeOnceVisible && frozen.current) return;
+    const observer = getSharedObserver({ threshold, root, rootMargin });
+    observer.observe(element, (intersecting) => {
+      setIntersecting(intersecting);
+      if (intersecting && freezeOnceVisible) {
+        frozen.current = true;
+        observer.unobserve(element);
+      }
+    });
+    return () => {
+      observer.unobserve(element);
+    };
+  }, [elementRef, threshold, root, rootMargin, freezeOnceVisible]);
+  return isIntersecting;
+}
+
+// src/use-is-mac.ts
+import { useEffect as useEffect3, useState as useState4 } from "react";
+function useIsMac() {
+  const [isMac, setIsMac] = useState4(true);
+  useEffect3(() => {
+    setIsMac(navigator.platform.toUpperCase().includes("MAC"));
+  }, []);
+  return isMac;
+}
+
 // src/use-media-query.ts
-import { useEffect as useEffect2, useState as useState3 } from "react";
+import { useEffect as useEffect4, useState as useState5 } from "react";
 var getMatches = (query) => {
   if (typeof window !== "undefined") {
     return window.matchMedia(query).matches;
@@ -436,8 +516,8 @@ var getMatches = (query) => {
   return false;
 };
 var useMediaQuery = (query) => {
-  const [matches, setMatches] = useState3(getMatches(query));
-  useEffect2(() => {
+  const [matches, setMatches] = useState5(getMatches(query));
+  useEffect4(() => {
     function handleChange() {
       setMatches(getMatches(query));
     }
@@ -543,12 +623,12 @@ var useMenu = (pathname) => {
   };
 };
 
-// src/use-mobile.ts
-import * as React2 from "react";
+// src/use-is-mobile.ts
+import * as React3 from "react";
 var DEFAULT_MOBILE_BREAKPOINT = 1024;
 function useIsMobile(breakpoint = DEFAULT_MOBILE_BREAKPOINT) {
-  const [isMobile, setIsMobile] = React2.useState(void 0);
-  React2.useEffect(() => {
+  const [isMobile, setIsMobile] = React3.useState(void 0);
+  React3.useEffect(() => {
     const mql = window.matchMedia(`(max-width: ${breakpoint - 1}px)`);
     const onChange = () => {
       setIsMobile(window.innerWidth < breakpoint);
@@ -561,17 +641,17 @@ function useIsMobile(breakpoint = DEFAULT_MOBILE_BREAKPOINT) {
 }
 
 // src/use-mounted.ts
-import * as React3 from "react";
+import * as React4 from "react";
 function useMounted() {
-  const [mounted, setMounted] = React3.useState(false);
-  React3.useEffect(() => {
+  const [mounted, setMounted] = React4.useState(false);
+  React4.useEffect(() => {
     setMounted(true);
   }, []);
   return mounted;
 }
 
 // src/use-mutation-observer.ts
-import * as React4 from "react";
+import * as React5 from "react";
 var DEFAULT_OPTIONS = {
   /** Watch for attribute changes */
   attributes: true,
@@ -583,7 +663,7 @@ var DEFAULT_OPTIONS = {
   subtree: true
 };
 var useMutationObserver = (ref, callback, options = DEFAULT_OPTIONS) => {
-  React4.useEffect(() => {
+  React5.useEffect(() => {
     if (ref.current) {
       const observer = new MutationObserver(callback);
       observer.observe(ref.current, options);
@@ -595,7 +675,7 @@ var useMutationObserver = (ref, callback, options = DEFAULT_OPTIONS) => {
 };
 
 // src/use-recaptcha-v2.ts
-import { useCallback as useCallback4, useEffect as useEffect6, useRef as useRef2 } from "react";
+import { useCallback as useCallback4, useEffect as useEffect8, useRef as useRef3 } from "react";
 var RECAPTCHA_SCRIPT_ID = "recaptcha-v2-script";
 var scriptLoadPromise = null;
 function loadRecaptchaScript() {
@@ -622,10 +702,10 @@ function loadRecaptchaScript() {
   return scriptLoadPromise;
 }
 function useRecaptchaV2(siteKey) {
-  const widgetId = useRef2(null);
-  const containerRef = useRef2(null);
-  const isRendered = useRef2(false);
-  const isInitializing = useRef2(false);
+  const widgetId = useRef3(null);
+  const containerRef = useRef3(null);
+  const isRendered = useRef3(false);
+  const isInitializing = useRef3(false);
   const initializeRecaptcha = useCallback4(async () => {
     if (isInitializing.current) return;
     if (!containerRef.current || !siteKey) return;
@@ -667,7 +747,7 @@ function useRecaptchaV2(siteKey) {
       isInitializing.current = false;
     }
   }, [siteKey]);
-  useEffect6(() => {
+  useEffect8(() => {
     if (containerRef.current) {
       initializeRecaptcha();
     }
@@ -719,9 +799,9 @@ function useRecaptchaV2(siteKey) {
 }
 
 // src/use-remove-ga-params.ts
-import { useEffect as useEffect7 } from "react";
+import { useEffect as useEffect9 } from "react";
 function useRemoveGAParams() {
-  useEffect7(() => {
+  useEffect9(() => {
     const url = new URL(window.location.href);
     if (url.searchParams.has("_gl")) {
       const timer = setTimeout(() => {
@@ -734,10 +814,10 @@ function useRemoveGAParams() {
 }
 
 // src/use-scroll-position.ts
-import { useEffect as useEffect8, useState as useState6 } from "react";
+import { useEffect as useEffect10, useState as useState8 } from "react";
 var useScrollPosition = ({ targetRef } = {}) => {
-  const [scrollPosition, setScrollPosition] = useState6(0);
-  useEffect8(() => {
+  const [scrollPosition, setScrollPosition] = useState8(0);
+  useEffect10(() => {
     const target = targetRef?.current || document;
     const scrollable = target === document ? window : target;
     const updatePosition = () => {
@@ -754,10 +834,10 @@ var useScrollPosition = ({ targetRef } = {}) => {
 };
 
 // src/use-slider-input.ts
-import { useCallback as useCallback5, useState as useState7 } from "react";
+import { useCallback as useCallback5, useState as useState9 } from "react";
 function useSliderInput({ minValue, maxValue, initialValue }) {
-  const [sliderValues, setSliderValues] = useState7(initialValue);
-  const [inputValues, setInputValues] = useState7(initialValue);
+  const [sliderValues, setSliderValues] = useState9(initialValue);
+  const [inputValues, setInputValues] = useState9(initialValue);
   const handleSliderChange = useCallback5((values) => {
     setSliderValues(values);
     setInputValues(values);
@@ -805,15 +885,15 @@ function useSliderInput({ minValue, maxValue, initialValue }) {
 }
 
 // src/use-viewport.ts
-import { useEffect as useEffect9, useState as useState8 } from "react";
+import { useEffect as useEffect11, useState as useState10 } from "react";
 var useViewport = () => {
-  const [dimensions, setDimensions] = useState8(() => {
+  const [dimensions, setDimensions] = useState10(() => {
     if (typeof window !== "undefined") {
       return [window.innerHeight, window.innerWidth];
     }
     return [0, 0];
   });
-  useEffect9(() => {
+  useEffect11(() => {
     const handleResize = () => {
       setDimensions([window.innerHeight, window.innerWidth]);
     };
@@ -832,6 +912,8 @@ export {
   useCopyToClipboard,
   useFileUpload,
   useHydrated,
+  useIntersectionObserver,
+  useIsMac,
   useIsMobile,
   useMediaQuery,
   useMenu,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pelatform/ui.hook",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Hook components of the Pelatform UI Library.",
   "author": "Pelatform",
   "license": "MIT",
@@ -39,9 +39,9 @@
   ],
   "devDependencies": {
     "@pelatform/tsconfig": "^0.1.4",
-    "@types/node": "^25.0.9",
-    "@types/react": "^19.2.8",
-    "react": "^19.2.3",
+    "@types/node": "^25.3.3",
+    "@types/react": "^19.2.14",
+    "react": "^19.2.4",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },