@bentoo/react-lazy 0.2.2 → 1.0.0

package/README.md

@@ -1,71 +1,154 @@
-
 # @bentoo/react-lazy
 
-A library designed to make it easier to implement `Lazy Loading` in `React` applications. It allows components to load only when they become visible on the screen, providing a way to monitor the entry of elements into the viewport.
-
-With this tool, you can improve the performance of your application by reducing the initial loading time and ensuring that `only the necessary elements are loaded`. This approach contributes to a more agile and responsive user experience.
+A lightweight and flexible **React lazy loading library**.  
+Load components or images **only when they enter the viewport**, improving performance, reducing initial bundle size, and providing optional callbacks when elements become visible.
 
-## Installation
+[![Version](https://img.shields.io/npm/v/@bentoo/react-lazy?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/@bentoo/react-lazy)  
+[![Downloads](https://img.shields.io/npm/dt/@bentoo/react-lazy.svg?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/@bentoo/react-lazy)  
+[![License](https://img.shields.io/npm/l/@bentoo/react-lazy.svg?style=flat&colorA=000000&colorB=000000)](LICENSE)
 
-You can install the package via NPM:
+---
 
-```bash
-npm install @bentoo/react-lazy
-```
+## Features
 
-or via Yarn:
+- Lazy load **any component or element** in React.  
+- Optional **fallback content** while loading.  
+- Callback support when an element becomes visible.  
+- Works with **Next.js**, **React 18**, and **TypeScript**.  
+- Lightweight, fully typed, and tree-shakable.  
 
-```bash
-yarn add @bentoo/react-lazy
-```
+---
 
-or via pnpm:
+## Installation
 
 ```bash
+npm install @bentoo/react-lazy
+# or
+yarn add @bentoo/react-lazy
+# or
 pnpm add @bentoo/react-lazy
-```
+````
+
+---
 
 ## Usage
 
-Here’s a basic example of how to use `@bentoo/react-lazy` in your project:
+### 1. LazyComponent
+
+Lazy load any React component with a fallback:
 
 ```tsx
 import React from 'react';
 import { LazyComponent } from '@bentoo/react-lazy';
 
-const App = () => {
+export default function App() {
   return (
     <div>
-      <h1>My image</h1>
-        <LazyComponent fallback={<h1>Loading...</h1>}>
-          <img src='/myPicture.png' alt='MyPicture'/>
-        </LazyComponent>
+      <h1>My content</h1>
+      <LazyComponent fallback={<h2>Loading...</h2>}>
+        <img src="/myPicture.png" alt="MyPicture" />
+      </LazyComponent>
     </div>
   );
-};
+}
+```
+
+**Props**:
+
+| Prop       | Type        | Description                         |
+| ---------- | ----------- | ----------------------------------- |
+| `children` | `ReactNode` | Content to display after lazy load. |
+| `fallback` | `ReactNode` | Content displayed while loading.    |
+
+---
+
+### 2. LazyImage
 
-export default App;
+Lazy load images with optional **placeholder, blur, fade-in, and Next.js support**:
+
+```tsx
+import { LazyImage } from '@bentoo/react-lazy';
+// For Next.js, pass ImageComponent={NextImage}
+
+<LazyImage
+  src="/photo.jpg"
+  alt="My Photo"
+  width={600}
+  height={400}
+  placeholder="/photo-low.jpg"
+  blur
+/>
+```
+
+**Props**:
+
+| Prop             | Type              | Description                             |
+| ---------------- | ----------------- | --------------------------------------- |
+| `src`            | `string`          | Image source                            |
+| `alt`            | `string`          | Image alt text                          |
+| `width`/`height` | `number`          | Optional width/height                   |
+| `placeholder`    | `string`          | Low-res placeholder for blur effect     |
+| `blur`           | `boolean`         | Apply blur to placeholder               |
+| `ImageComponent` | `React Component` | Optional (pass `next/image` in Next.js) |
+
+---
+
+### 3. Lazy with Callback
+
+Trigger a function when an element enters the viewport:
+
+```tsx
+import { useLazyCallback } from '@bentoo/react-lazy';
+
+export default function Section() {
+  const { ref } = useLazyCallback({
+    onVisible: () => console.log('Element is now visible!'),
+    triggerOnce: true
+  });
+
+  return <div ref={ref}>Watch me appear!</div>;
+}
 ```
 
-### Props
+---
+
+## Next.js Example
+
+```tsx
+import Image from 'next/image';
+import { LazyImage } from '@bentoo/react-lazy';
+
+export default function NextApp() {
+  return (
+    <LazyImage
+      ImageComponent={Image}
+      src="/photo.jpg"
+      alt="Next.js Image"
+      width={600}
+      height={400}
+      placeholder="/photo-low.jpg"
+      blur
+    />
+  );
+}
+```
 
-`LazyComponent` accepts the following props:
+> Note: `next/image` already supports lazy loading, but `LazyImage` adds viewport-triggered effects and callbacks.
 
-| Prop        | Type        | Description                                                       |
-|-------------|-------------|-------------------------------------------------------------------|
-| `fallback`  | `ReactNode` | The content to display while the component is being loaded.       |
-| `children`  | `ReactNode` | The content that will be displayed after loading.                 |
+---
 
 ## Contribution
 
-If you would like to contribute, feel free to open a pull request or report an issue.
+We welcome contributions!
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b my-feature`)
+3. Commit your changes (`git commit -m 'Add feature'`)
+4. Push to the branch (`git push origin my-feature`)
+5. Open a Pull Request
 
-1. Fork the project.
-2. Create your feature branch (`git checkout -b my-new-feature`).
-3. Commit your changes (`git commit -m 'Adding new feature'`).
-4. Push to the branch (`git push origin my-new-feature`).
-5. Open a Pull Request.
+---
 
 ## License
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
+MIT License – see the [LICENSE](LICENSE) file for details.

package/dist/components/container.d.ts

@@ -1,7 +1,10 @@
 import { default as React } from 'react';
-interface LazyComponentProps {
+import { LazyProps } from '../hooks';
+type LazyComponentProps = LazyProps & {
     children: React.ReactNode;
-    fallback: React.ReactNode;
-}
-export default function LazyComponent({ fallback, children }: LazyComponentProps): import("react/jsx-runtime").JSX.Element;
+    fallback?: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+};
+export declare function LazyComponent({ children, fallback, className, style, root, rootMargin, threshold, triggerOnce }: LazyComponentProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/image.d.ts

@@ -0,0 +1,13 @@
+import { default as React, ElementType } from 'react';
+type LazyImageProps = {
+    src: string;
+    alt: string;
+    placeholder?: string;
+    blur?: boolean;
+    width?: number;
+    height?: number;
+    ImageComponent?: ElementType;
+    fadeInDuration?: number;
+} & Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "alt">;
+export declare function LazyImage({ src, alt, placeholder, blur, fadeInDuration, width, height, style, ImageComponent, ...rest }: LazyImageProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/index.d.ts

@@ -1 +1,3 @@
-export { default as LazyComponent } from './container';
+export { LazyComponent } from './container';
+export { LazySuspense } from './suspense';
+export { LazyImage } from './image';

package/dist/components/suspense.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+type LazySuspenseProps = {
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+};
+export declare function LazySuspense({ children, fallback }: LazySuspenseProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export * from './useLazy';
+export * from './useLazyCallback';

package/dist/hooks/useImage.d.ts

@@ -0,0 +1,10 @@
+type Props = {
+    src: string;
+    visible: boolean;
+};
+export declare const useImage: ({ src, visible }: Props) => {
+    handleLoad: () => void;
+    loaded: boolean;
+    shouldLoad: boolean;
+};
+export {};

package/dist/hooks/useLazy.d.ts

@@ -0,0 +1,10 @@
+export type LazyProps = {
+    root?: Element | null;
+    rootMargin?: string;
+    threshold?: number | number[];
+    triggerOnce?: boolean;
+};
+export declare const useLazy: <T extends HTMLElement>({ root, rootMargin, threshold, triggerOnce }: LazyProps) => {
+    ref: import('react').RefObject<T | null>;
+    visible: boolean;
+};

package/dist/hooks/useLazyCallback.d.ts

@@ -0,0 +1,7 @@
+import { LazyProps } from './useLazy';
+export type LazyCallbackProps = LazyProps & {
+    onVisible: () => void;
+};
+export declare const useLazyCallback: <T extends HTMLElement>({ onVisible, root, rootMargin, threshold, triggerOnce }: LazyCallbackProps) => {
+    ref: import('react').RefObject<T | null>;
+};

package/dist/index.cjs.js

@@ -0,0 +1,6 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const b=require("react");var g={exports:{}},y={};var W;function te(){if(W)return y;W=1;var t=Symbol.for("react.transitional.element"),s=Symbol.for("react.fragment");function c(u,n,a){var i=null;if(a!==void 0&&(i=""+a),n.key!==void 0&&(i=""+n.key),"key"in n){a={};for(var l in n)l!=="key"&&(a[l]=n[l])}else a=n;return n=a.ref,{$$typeof:t,type:u,key:i,ref:n!==void 0?n:null,props:a}}return y.Fragment=s,y.jsx=c,y.jsxs=c,y}var k={};var M;function ne(){return M||(M=1,process.env.NODE_ENV!=="production"&&(function(){function t(e){if(e==null)return null;if(typeof e=="function")return e.$$typeof===K?null:e.displayName||e.name||null;if(typeof e=="string")return e;switch(e){case A:return"Fragment";case J:return"Profiler";case q:return"StrictMode";case B:return"Suspense";case H:return"SuspenseList";case Q:return"Activity"}if(typeof e=="object")switch(typeof e.tag=="number"&&console.error("Received an unexpected object in getComponentNameFromType(). This is likely a bug in React. Please file an issue."),e.$$typeof){case w:return"Portal";case G:return e.displayName||"Context";case V:return(e._context.displayName||"Context")+".Consumer";case X:var r=e.render;return e=e.displayName,e||(e=r.displayName||r.name||"",e=e!==""?"ForwardRef("+e+")":"ForwardRef"),e;case Z:return r=e.displayName||null,r!==null?r:t(e.type)||"Memo";case P:r=e._payload,e=e._init;try{return t(e(r))}catch{}}return null}function s(e){return""+e}function c(e){try{s(e);var r=!1}catch{r=!0}if(r){r=console;var o=r.error,f=typeof Symbol=="function"&&Symbol.toStringTag&&e[Symbol.toStringTag]||e.constructor.name||"Object";return o.call(r,"The provided key is an unsupported type %s. This value must be coerced to a string before using it here.",f),s(e)}}function u(e){if(e===A)return"<>";if(typeof e=="object"&&e!==null&&e.$$typeof===P)return"<...>";try{var r=t(e);return r?"<"+r+">":"<...>"}catch{return"<...>"}}function n(){var e=h.A;return e===null?null:e.getOwner()}function a(){return Error("react-stack-top-frame")}function i(e){if(I.call(e,"key")){var r=Object.getOwnPropertyDescriptor(e,"key").get;if(r&&r.isReactWarning)return!1}return e.key!==void 0}function l(e,r){function o(){Y||(Y=!0,console.error("%s: `key` is not a prop. Trying to access it will result in `undefined` being returned. If you need to access the same value within the child component, you should pass it as a different prop. (https://react.dev/link/special-props)",r))}o.isReactWarning=!0,Object.defineProperty(e,"key",{get:o,configurable:!0})}function m(){var e=t(this.type);return $[e]||($[e]=!0,console.error("Accessing element.ref was removed in React 19. ref is now a regular prop. It will be removed from the JSX Element type in a future release.")),e=this.props.ref,e!==void 0?e:null}function v(e,r,o,f,j,L){var d=o.ref;return e={$$typeof:T,type:e,key:r,props:o,_owner:f},(d!==void 0?d:null)!==null?Object.defineProperty(e,"ref",{enumerable:!1,get:m}):Object.defineProperty(e,"ref",{enumerable:!1,value:null}),e._store={},Object.defineProperty(e._store,"validated",{configurable:!1,enumerable:!1,writable:!0,value:0}),Object.defineProperty(e,"_debugInfo",{configurable:!1,enumerable:!1,writable:!0,value:null}),Object.defineProperty(e,"_debugStack",{configurable:!1,enumerable:!1,writable:!0,value:j}),Object.defineProperty(e,"_debugTask",{configurable:!1,enumerable:!1,writable:!0,value:L}),Object.freeze&&(Object.freeze(e.props),Object.freeze(e)),e}function S(e,r,o,f,j,L){var d=r.children;if(d!==void 0)if(f)if(ee(d)){for(f=0;f<d.length;f++)x(d[f]);Object.freeze&&Object.freeze(d)}else console.error("React.jsx: Static children should always be an array. You are likely explicitly calling React.jsxs or React.jsxDEV. Use the Babel transform instead.");else x(d);if(I.call(r,"key")){d=t(e);var R=Object.keys(r).filter(function(re){return re!=="key"});f=0<R.length?"{key: someKey, "+R.join(": ..., ")+": ...}":"{key: someKey}",D[d+f]||(R=0<R.length?"{"+R.join(": ..., ")+": ...}":"{}",console.error(`A props object containing a "key" prop is being spread into JSX:
+  let props = %s;
+  <%s {...props} />
+React keys must be passed directly to JSX without using spread:
+  let props = %s;
+  <%s key={someKey} {...props} />`,f,d,R,d),D[d+f]=!0)}if(d=null,o!==void 0&&(c(o),d=""+o),i(r)&&(c(r.key),d=""+r.key),"key"in r){o={};for(var C in r)C!=="key"&&(o[C]=r[C])}else o=r;return d&&l(o,typeof e=="function"?e.displayName||e.name||"Unknown":e),v(e,d,o,n(),j,L)}function x(e){p(e)?e._store&&(e._store.validated=1):typeof e=="object"&&e!==null&&e.$$typeof===P&&(e._payload.status==="fulfilled"?p(e._payload.value)&&e._payload.value._store&&(e._payload.value._store.validated=1):e._store&&(e._store.validated=1))}function p(e){return typeof e=="object"&&e!==null&&e.$$typeof===T}var E=b,T=Symbol.for("react.transitional.element"),w=Symbol.for("react.portal"),A=Symbol.for("react.fragment"),q=Symbol.for("react.strict_mode"),J=Symbol.for("react.profiler"),V=Symbol.for("react.consumer"),G=Symbol.for("react.context"),X=Symbol.for("react.forward_ref"),B=Symbol.for("react.suspense"),H=Symbol.for("react.suspense_list"),Z=Symbol.for("react.memo"),P=Symbol.for("react.lazy"),Q=Symbol.for("react.activity"),K=Symbol.for("react.client.reference"),h=E.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,I=Object.prototype.hasOwnProperty,ee=Array.isArray,N=console.createTask?console.createTask:function(){return null};E={react_stack_bottom_frame:function(e){return e()}};var Y,$={},z=E.react_stack_bottom_frame.bind(E,a)(),F=N(u(a)),D={};k.Fragment=A,k.jsx=function(e,r,o){var f=1e4>h.recentlyCreatedOwnerStacks++;return S(e,r,o,!1,f?Error("react-stack-top-frame"):z,f?N(u(e)):F)},k.jsxs=function(e,r,o){var f=1e4>h.recentlyCreatedOwnerStacks++;return S(e,r,o,!0,f?Error("react-stack-top-frame"):z,f?N(u(e)):F)}})()),k}var U;function ae(){return U||(U=1,process.env.NODE_ENV==="production"?g.exports=te():g.exports=ne()),g.exports}var _=ae();const O=({root:t=null,rootMargin:s="0px",threshold:c=.1,triggerOnce:u=!0})=>{const n=b.useRef(null),[a,i]=b.useState(!1);return b.useEffect(()=>{const l=n.current;if(!l)return;const m=new IntersectionObserver(([v])=>{v.isIntersecting?(i(!0),u&&m.unobserve(v.target)):u||i(!1)},{root:t,rootMargin:s,threshold:c});return m.observe(l),()=>{m.unobserve(l),m.disconnect()}},[t,s,c,u]),{ref:n,visible:a}},oe=({onVisible:t,root:s=null,rootMargin:c="0px",threshold:u=.1,triggerOnce:n=!0})=>{const a=b.useRef(null),i=b.useRef(!1);return b.useEffect(()=>{const l=a.current;if(!l)return;const m=new IntersectionObserver(([v])=>{v.isIntersecting&&((!i.current||!n)&&(t(),i.current=!0),n&&m.unobserve(v.target))},{root:s,rootMargin:c,threshold:u});return m.observe(l),()=>{m.unobserve(l),m.disconnect()}},[t,s,c,u,n]),{ref:a}};function se({children:t,fallback:s=null,className:c,style:u,root:n,rootMargin:a,threshold:i,triggerOnce:l}){const{ref:m,visible:v}=O({root:n,rootMargin:a,threshold:i,triggerOnce:l});return _.jsx("div",{ref:m,className:c,style:u,children:v?t:s})}function ue({children:t,fallback:s=null}){const{ref:c,visible:u}=O({});return _.jsx("div",{ref:c,children:u&&_.jsx(b.Suspense,{fallback:s,children:t})})}const le=({src:t,visible:s})=>{const[c,u]=b.useState(!1),[n,a]=b.useState(!1);function i(){a(!0)}return b.useEffect(()=>{if(!s||!t)return;const l=new Image;l.src=t,l.onload=()=>{u(!0)}},[s,t]),{handleLoad:i,loaded:n,shouldLoad:c}};function ce({src:t,alt:s,placeholder:c,blur:u=!1,fadeInDuration:n=300,width:a,height:i,style:l,ImageComponent:m="img",...v}){const{ref:S,visible:x}=O({}),{loaded:p,handleLoad:E,shouldLoad:T}=le({src:t,visible:x}),w=m!=="img";return _.jsxs("div",{style:{position:"relative",overflow:"hidden",width:a,height:i},children:[c&&!p&&_.jsx("img",{src:c,alt:s,"aria-hidden":!0,style:{position:"absolute",inset:0,width:"100%",height:"100%",objectFit:"cover",filter:u?"blur(20px)":"none",transform:u?"scale(1.1)":void 0}}),w?_.jsx(m,{src:T?t:"",alt:s,width:a,height:i,onLoad:E,style:{opacity:p?1:0,transition:`opacity ${n}ms ease`,...l},...v}):_.jsx("img",{ref:S,src:T?t:void 0,alt:s,loading:"lazy",width:a,height:i,onLoad:E,style:{opacity:p?1:0,transition:`opacity ${n}ms ease`,width:"100%",height:"100%",objectFit:"cover",display:"block",...l},...v})]})}exports.LazyComponent=se;exports.LazyImage=ce;exports.LazySuspense=ue;exports.useLazy=O;exports.useLazyCallback=oe;

package/dist/index.d.ts

@@ -1 +1,2 @@
 export * from './components';
+export * from './hooks';