morphing-scroll 2.6.0 → 2.7.0

package/README.md

@@ -13,7 +13,7 @@
 
 ### 〈 About 〉
 
-`morphing-scroll` is a `React` is a React library originally created to address common limitations of the native browser scrollbar, including:
+`morphing-scroll` is a `React` library originally created to address common limitations of the native browser scrollbar, including:
 
 - Design customization constraints
 - Cross-browser compatibility
@@ -49,6 +49,8 @@ Start using the `MorphScroll` component by defining the required `size` prop. Fo
 
 > **✦ Note:**  
 > `MorphScroll` supports both **ESM** (`import`) and **CommonJS** (`require`) builds.
+>
+> This library is currently under development. APIs and behavior may change in future releases.
 
 <h2></h2>
 
@@ -65,9 +67,6 @@ Start using the `MorphScroll` component by defining the required `size` prop. Fo
 ###### **— GENERAL SETTINGS —**
 
 <details><summary><b><code>className</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-string<br />
-<br />
 <b>Description:</b><em><br />
 allows you to add additional classes to the component.</em><br />
 <br />
@@ -84,14 +83,11 @@ allows you to add additional classes to the component.</em><br />
 <h2></h2>
 
 <details><summary><b><code>children</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-React.ReactNode<br />
-<br />
 <b>Description:</b><em><br />
-allows you to add custom content to the component.<br />
+allows to add custom content to the component.<br />
 Make sure to provide unique keys for each list item, as per React's rules. The <code>MorphScroll</code> component ensures that the cells it generates will use the same keys as your list items, allowing it to render the correct cells for the current list.<br />
-Additionally, <code>MorphScroll</code> handles a passed <b>null</b> value the same way as <b>undefined</b>, rendering nothing in both cases.</em><br />
-<br />
+Additionally, <code>MorphScroll</code> handles a passed <b>null</b> value the same way as <b>undefined</b>, rendering nothing in both cases.<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -105,21 +101,27 @@ Additionally, <code>MorphScroll</code> handles a passed <b>null</b> value the sa
 ###### **— SCROLL SETTINGS —**
 
 <details><summary><b><code>type</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-"scroll" | "slider" | "sliderMenu"<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+type: "slider"; // or "scroll" | "sliderMenu"
+```
+
 <b>Default:</b><br />
 "scroll"<br />
 <br />
 <b>Description:</b><em><br />
 defines how the provided <code>progressElement</code> behaves within <code>progressTrigger</code> and how you interact with it.<br />
 <br />
-<b>scroll</b> - This is the default value and represents a standard scrollbar.<br />
+<code><b>scroll</b></code>:<br />
+the default value and represents a standard scrollbar.<br />
 <br />
-<b>slider</b> - It displays distinct elements indicating the number of full scroll steps within the list.<br />
-<br />
-<b>sliderMenu</b> - It behaves like a <code>slider</code>, but now the <code>progressElement</code> is a menu, an you can provide custom buttons as an array in the <code>progressElement</code>.</em><br />
+<code><b>slider</b></code>:<br />
+displays distinct elements indicating the number of full scroll steps within the list.<br />
 <br />
+<code><b>sliderMenu</b></code>:<br />
+like <code>slider</code>, but the <code>progressElement</code> is a menu, an you can provide custom buttons as an array in the <code>progressElement</code>.<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -135,9 +137,12 @@ defines how the provided <code>progressElement</code> behaves within <code>progr
 <h2></h2>
 
 <details><summary><b><code>direction</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-"x" | "y" | "hybrid"<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+size: "x"; // or "y" | "hybrid"
+```
+
 <b>Default:</b><br />
 "y"<br />
 <br />
@@ -160,33 +165,47 @@ You can set the value to horizontal, vertical or hybrid positions to customize t
 <h2></h2>
 
 <details><summary><b><code>scrollPosition</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-number | "end" | (number | "end")[]<br />
-| {<br />
+<b>Usage:</b><br />
+
 <ul>
-  value: number | "end" | (number | "end")[];<br />
-  duration?: number;<br />
-  updater?: boolean;<br />
+  <li><b>Simple</b>:<br />
+  
+```tsx
+scrollPosition: 10; // or "end" | null | array if direction="hybrid"
+```
+
+  </li>
+  <li><b>Advanced</b>:<br />
+  
+```tsx
+scrollPosition: {
+  value: 10; // or "end" | null | array if direction="hybrid"
+  duration: 400;
+  updater: true;
+}
+```
+
+  </li>
 </ul>
-}<br />
-<br />
+
 <b>Default:</b><br />
 { duration: 200; updater: false }<br />
 <br />
 <b>Description:</b><em><br />
 allows you to set custom scroll values.<br />
 <br />
-<code>value</code>:<br />
+<code><b>value</b></code>:<br />
+
 <ul>
   <li><b>number</b> - Sets position to a specific value.</li>
   <li><b>"end"</b> - Sets position to the end of the list.</li>
 </ul>
 You can also provide an array of two values to specific positions ( e.g., [ x, y ] axes ) for hybrid directions.</code><br />
 <br />
-<code>duration</code>:<br />
+<code><b>duration</b></code>:<br />
 property determines the animation speed for scrolling in <b>ms</b>.<br />
 <br />
-<code>updater</code>:<br />
+<code><b>updater</b></code>:<br />
 property is a helper for the <code>value</code>. When setting the same scroll value repeatedly, React does not register the update and you can use it to force an update</em><br />
 <br />
 <b>Example:</b>
@@ -204,11 +223,8 @@ property is a helper for the <code>value</code>. When setting the same scroll va
 <h2></h2>
 
 <details><summary><b><code>onScrollValue</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-( left: number, top: number ) => void<br />
-<br />
 <b>Description:</b><em><br />
-accepts a callback function that is triggered on every scroll event. The callback receives the current scroll top and left position as a number. The return value of the callback can be used to determine custom behavior based on the scroll value.</em><br />
+accepts a callback function that is triggered on every scroll event. The callback receives the current scroll top and left position as a <b>number</b>. The return value of the callback can be used to determine custom behavior based on the scroll value.</em><br />
 <br />
 <b>Example:</b>
 
@@ -227,9 +243,6 @@ accepts a callback function that is triggered on every scroll event. The callbac
 <h2></h2>
 
 <details><summary><b><code>isScrolling</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-( motion: boolean ) => void<br />
-<br />
 <b>Description:</b><em><br />
 accepts a callback function that is triggered whenever the scroll status changes. The callback receives a boolean value, where <code>true</code> indicates that scrolling is in progress, and <code>false</code> indicates that scrolling has stopped. This can be useful for triggering additional actions, such as pausing animations or loading indicators based on the scroll state.</em><br />
 <br />
@@ -253,16 +266,19 @@ accepts a callback function that is triggered whenever the scroll status changes
 ###### **— VISUAL SETTINGS —**
 
 <details><summary><b><code>size</code></b> REQUIRED</summary><br /><ul><div>
-<b>Type:</b><br />
-number | number[] | "auto"<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+size: 100; // or [100, 70] | "auto"
+```
+
 <b>Description:</b><em><br />
 sets the width and height of the <code>MorphScroll</code>.<br />
 <br />
-<code>number</code>:<br />
+<code><b>number</b></code>:<br />
 sets a fixed size in pixels. It can be 1 number if you want to set the same width and height, or an array of 2 numbers.<br />
 <br />
-<code>"auto"</code>:<br />
+<code><b>"auto"</b></code>:<br />
 adds the <code>ResizeTracker</code> component to measure the width and height of the area where <code>MorphScroll</code> is added. The dimensions will automatically adjust when the container changes.</em><br />
 <br />
 <b>Example:</b>
@@ -280,41 +296,31 @@ adds the <code>ResizeTracker</code> component to measure the width and height of
 <h2></h2>
 
 <details><summary><b><code>objectsSize</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-number | "size" | "firstChild" | "none"<br />
-| ( number | "size" | "firstChild" | "none" )[]<br />
-<br />
-<b>Default:</b><br />
-If you don't provide any value, the default value will be taken from <code>size</code>.<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+objectsSize: 100; // or [100, 70] | "size" | "firstChild" | "none"
+```
+
 <b>Description:</b><em><br />
 defines the <b>[width, height]</b> of cells for each of your objects.<br />
 <br />
 <code>number</code>:<br />
 sets a fixed size for your custom objects.<br />
 <br />
-<code>"size"</code>:<br />
+<code><b>"size"</b></code>:<br />
 the dimensions will be taken from <code>size</code>.<br />
 <br />
-<code>"firstChild"</code>:<br />
+<code><b>"firstChild"</b></code>:<br />
 creates a <code>ResizeTracker</code> wrapper for the first child of your list. This wrapper will calculate the size of the first child, and these dimensions will be applied to all cells in the list.<br />
 This can be useful if you want to change the size of objects in your list dynamically, e.g., when reducing the size of the user's screen.<br />
 <br />
-<code>"none"</code>:<br />
+<code><b>"none"</b></code>:<br />
 cells will still be created, but <code>MorphScroll</code> will not calculate their sizes-they will simply wrap your objects.<br />
 <br />
-If no value is provided, the default behavior is partially inferred from the <code>size</code> prop:
-<ul>
-  <li>When <code>direction="x"</code>, the height from <code>size</code> will be used, behaving as if you had passed <code>objectsSize=["size", "none"]</code>.</li>
-  <li>When <code>direction="y"</code>, the width from <code>size</code> will be used, behaving as if you had passed <code>objectsSize=["none", "size"]</code>.</li>
-</ul>
-<br />
 ✦ Note:<br />
-<ul>
-  <li>All types can be used as 1 value, or an array of 2 values.</li>
-  <li><b>"none"</b> is not compatible with <code>render</code>.</li>
-</ul></em><br />
-<br />
+<b>"none"</b> is not compatible with <code>render</code>.<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -330,9 +336,6 @@ If no value is provided, the default behavior is partially inferred from the <co
 <h2></h2>
 
 <details><summary><b><code>crossCount</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-number<br />
-<br />
 <b>Description:</b><em><br />
 defines the number of <b>columns</b> or <b>rows</b>.<br />
 <br />
@@ -357,15 +360,15 @@ defines the number of <b>columns</b> or <b>rows</b>.<br />
 <h2></h2>
 
 <details><summary><b><code>gap</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-number | number[]<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+gap: 10; // or [20, 10]
+```
+
 <b>Description:</b><em><br />
 allows you to set spacing in pixels between list items for rows and columns.<br />
-<br />
-✦ Note:<br />
-it can be 1 number or an array of 2 numbers.</em><br />
-<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -381,15 +384,15 @@ it can be 1 number or an array of 2 numbers.</em><br />
 <h2></h2>
 
 <details><summary><b><code>wrapperMargin</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-number | number[]<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+wrapperMargin: 10; // or [v, h] | [t, r, b, l]
+```
+
 <b>Description:</b><em><br />
 defines the spacing between the list items and their wrapper, effectively increasing the width or height of the scrollable area.<br />
-<br />
-✦ Note:<br />
-can be 1 number or an array of 2 or 4 numbers in pixels.</em><br />
-<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -405,15 +408,32 @@ can be 1 number or an array of 2 or 4 numbers in pixels.</em><br />
 <h2></h2>
 
 <details><summary><b><code>wrapperMinSize</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-number | "full" | (number | "full")[]<br />
-<br />
+<b>Usage:</b><br />
+
+<ul>
+  <li><b>Simple</b>:<br />
+  
+```tsx
+wrapperMinSize: 10; // or "full"
+```
+
+  </li>
+  <li><b>Advanced</b>:<br />
+  
+```tsx
+// if direction="hybrid"
+wrapperMinSize: [
+  "full",
+  10,
+] // or one value for both sides
+```
+
+  </li>
+</ul>
+
 <b>Description:</b><em><br />
 defines the minimum height or width of the <b>.ms-objects-wrapper</b>, to which CSS properties like <code>min-height</code> or <code>min-width</code> will be applied.<br />
-<br />
-✦ Note:<br />
-can be used as 1 value, or an array of 2 values.</em><br />
-<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -429,19 +449,34 @@ can be used as 1 value, or an array of 2 values.</em><br />
 <h2></h2>
 
 <details><summary><b><code>wrapperAlign</code></b></summary><br /><ul><div> 
-<b>Type:</b><br />
-"start" | "center" | "end"<br />
-| ("start" | "center" | "end")[]<br />
-<br />
+<b>Usage:</b><br />
+
+<ul>
+  <li><b>Simple</b>:<br />
+  
+```tsx
+wrapperAlign: "center"; // or "start" | "end"
+```
+
+  </li>
+  <li><b>Advanced</b>:<br />
+  
+```tsx
+wrapperAlign: [
+  "center",
+  "start",
+] // or one value for both axes
+```
+
+  </li>
+</ul>
+
 <b>Default:</b><br />
 "start"<br />
 <br />
 <b>Description:</b><em><br />
 aligns the <b>.ms-objects-wrapper</b>, which contains all the provided elements, relative to the scroll or the <code>size</code>.<br />
-<br />
-✦ Note:<br />
-use 1 value to align one or both axes, or an array of 2 values to align both axes.</em><br />
-<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -457,9 +492,12 @@ use 1 value to align one or both axes, or an array of 2 values to align both axe
 <h2></h2>
 
 <details><summary><b><code>elementsAlign</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-"start" | "center" | "end"<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+elementsAlign: "center"; // or "start" | "end"
+```
+
 <b>Default:</b><br />
 "start"<br />
 <br />
@@ -478,9 +516,12 @@ use 1 value to align one or both axes, or an array of 2 values to align both axe
 <h2></h2>
 
 <details><summary><b><code>elementsDirection</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-"row" | "column"<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+elementsDirection: "row"; // or "column"
+```
+
 <b>Default:</b><br />
 "row"<br />
 <br />
@@ -502,22 +543,42 @@ changes the order of the provided elements based on the provided value.</em><br
 <h2></h2>
 
 <details><summary><b><code>edgeGradient</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-boolean | string | { color?: string; size?: number }<br />
-<br />
-<b>Default:</b><br />
-{ size: 40 }<br />
-<br />
+<b>Usage:</b><br />
+
+<ul>
+  <li><b>Simple</b>:<br />
+  
+```tsx
+edgeGradient: true; // or "#fff"
+```
+
+  </li>
+  <li><b>Advanced</b>:<br />
+  
+```tsx
+edgeGradient: {
+  color: "#fff",
+  size: 60, // default 40px
+}
+```
+
+  </li>
+</ul>
+
 <b>Description:</b><em><br />
-parameter creates two edge elements responsible for darkening the edges of the scroll when it overflows.<br />
+parameter creates several edge elements responsible for darkening the edges of the scroll when it overflows.<br />
 <br />
-<code>color</code>:<br />
+<code><b>color</b></code>:<br />
 property accepts any valid color format.
 If you provide it, the library will generate a gradient transitioning from the custom color to transparent.
 If you provide just <b>true</b>, the edge elements will have no color, allowing for custom styling via CSS class <code>.ms-edge</code>.<br />
 <br />
-<code>size</code>:<br />
-property changes the height of the edges for the horizontal and the width of the edges for the vertical.</em><br />
+<code><b>size</b></code>:<br />
+property changes the height of the edges for the horizontal and the width of the edges for the vertical.<br />
+<br />
+If the edge element is inactive, it gets the <code>"ms-disabled"</code> class.<br />
+Also, each edge element gets the <code>--edge-visibility</code> variable in the styles with value 0 or 1.
+</em><br />
 <br />
 <b>Example:</b>
 
@@ -537,24 +598,43 @@ property changes the height of the edges for the horizontal and the width of the
 <h2></h2>
 
 <details><summary><b><code>progressTrigger</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-{<br />
-  <ul> 
-    wheel?: boolean | { changeDirection?: boolean; changeDirectionKey?: string };<br />
-    content?: boolean;<br />
-    progressElement?: boolean | React.ReactNode | React.ReactNode[];<br />
-    arrows?: boolean | React.ReactNode<br />
-    | {<br />
-      <ul>
-        element?: React.ReactNode;<br />
-        size?: number;<br />
-        contentReduce?: boolean;<br />
-        loop?: boolean;<br />
-      </ul>
-    };<br />
-  </ul>
-}<br />
-<br />
+<b>Usage:</b><br />
+
+<ul>
+  <li><b>Simple</b>:<br />
+  
+```tsx
+progressTrigger: {
+  wheel: true,
+  content: true,
+  progressElement: true, // or <ScrollThumbComponent />
+  arrows: true, // or <ArrowComponent />
+}
+```
+
+  </li>
+  <li><b>Advanced</b>:<br />
+  
+```tsx
+progressTrigger: {
+  wheel: {
+    // if direction="hybrid"
+    changeDirection: true,
+    changeDirectionKey: "someKay" // default "KeyX"
+  },
+  progressElement: [<Elem1 />, <Elem2 />, <Elem3 />],
+  arrows: {
+    element: <ArrowComponent />,
+    size: 60, // default 40px
+    contentReduce: true;
+    loop: true,
+  }
+}
+```
+
+  </li>
+</ul>
+
 <b>Default:</b><br />
 { wheel: true }<br />
 <br />
@@ -563,17 +643,22 @@ this is one of the most important properties, allowing you to define how users i
 <br />
 <code><b>wheel</b></code>:<br />
 determines whether the progress bar responds to mouse wheel scrolling<br />
-<br />
 If you use <code>direction="hybrid"</code>, you can use:<br />
+
 <ul>
   <li><code>changeDirection</code>: allows switching the scroll direction with the mouse wheel.</li><br />
-  <li><code>changeDirectionKey</code>: enables switching the scroll direction by pressing a specific key (default: <b>"KeyX"</b>).<br />
+  <li><code>changeDirectionKey</code>: enables switching the scroll direction by pressing a specific key.<br />
   To disable this behavior, pass an empty string.<br />
   <a href="https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values">more about keys</a></li>
 </ul>
 <br />
 <code><b>content</b></code>:<br />
 enables interaction by clicking and dragging anywhere within the scrollable content to move it.<br />
+By using <code>content</code> drag scrolling will not work in these cases:<br />
+interactive elements:<br />
+<code>input</code>, <code>textarea</code>, <code>select</code>, <code>button</code>, <code>a</code><br />
+elements with attribute:<br />
+<code>[draggable="true"]</code>, <code>[contenteditable]</code> and custom attribute - <code>[data-ms-no-drag]</code><br />
 <br />
 <code><b>progressElement</b></code>:<br />
 determines how the scroll progress is managed<br />
@@ -589,17 +674,11 @@ allows you to add custom arrows to the progress bar<br />
 <br />
 <ul>
   <li><code>element</code>: the custom arrow element.</li><br />
-  <li><code>size</code>: adds a custom size to the arrow.</li><br />
+  <li><code>size</code>: adds a custom size to the <b>.ms-arrow-box</b>.</li><br />
   <li><code>contentReduce</code>: this parameter reduces the size of the scroll content by the arrow size.</li><br />
   <li><code>loop</code>: enables infinite scrolling.</li>
-</ul>
-You can either specify a <code>size</code> for the arrows and provide a custom element.
-<br />
-✦ Note:<br />
-<ul>
-  <li><code>progressTrigger</code> can only create or provide elements, but you must make the design for them yourself.</li>
-  <li>The Library scroll element in browser automatically receives <code>:focus</code> when you start scrolling with the mouse wheel.</li>
-</ul></em><br />
+</ul><br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -619,18 +698,15 @@ You can either specify a <code>size</code> for the arrows and provide a custom e
 <h2></h2>
 
 <details><summary><b><code>progressReverse</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-boolean | boolean[]<br />
-<br />
-<b>Default:</b><br />
-false<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+progressReverse: true; // or [true, false] if direction="hybrid"
+```
+
 <b>Description:</b><em><br />
 this parameter changes the position of the progress bar in the opposite direction and depends on the <code>direction</code> property.<br />
-<br />
-✦ Note:<br />
-use it like an array to set different values for each direction when using <code>direction="hybrid"</code>.</em><br />
-<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -646,16 +722,16 @@ use it like an array to set different values for each direction when using <code
 <h2></h2>
 
 <details><summary><b><code>scrollBarOnHover</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-boolean<br />
-<br />
-<b>Default:</b><br />
-false<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+scrollBarOnHover: true;
+```
+
 <b>Description:</b><em><br />
 this parameter controls the visibility of the progress bar regardless of the <code>type</code> value.<br />
-When you use it, the <b>"hover"</b> class is applied to the <b>.ms-bar</b> when the cursor is over it (or the finger touches it on touchscreens), and <b>"leave"</b> is applied when it is no longer hovered. This allows you to easily customize its appearance on interaction.</em><br />
-<br />
+When you use it, the <b>"hover"</b> class is applied to the <b>.ms-bar</b> when the cursor is over it (or the finger touches it on touchscreens), and <b>"leave"</b> is applied when it is no longer hovered. This allows you to easily customize its appearance on interaction.<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -671,16 +747,18 @@ When you use it, the <b>"hover"</b> class is applied to the <b>.ms-bar</b> when
 <h2></h2>
 
 <details><summary><b><code>scrollBarEdge</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-number | number[]<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+scrollBarEdge: 10; // or [10, 20] for control each bar if direction="hybrid"
+```
+
 <b>Description:</b><em><br />
-defines the margin (in pixels) applied to the edges of the scroll bar, effectively reducing its size.<br />
-If you use <code>direction="hybrid"</code>, you can also pass an array of numbers to control each bar individually.<br />
+defines the margin (in <b>px</b>) applied to the edges of the scroll bar, effectively reducing its size.<br />
 <br />
 ✦ Note:<br />
-this parameter is only used when <code>type="scroll"</code> is set.</em><br />
-<br />
+this parameter is only used when <code>type="scroll"</code> is set.<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -696,18 +774,15 @@ this parameter is only used when <code>type="scroll"</code> is set.</em><br />
 <h2></h2>
 
 <details><summary><b><code>thumbMinSize</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-number<br />
-<br />
 <b>Default:</b><br />
-30<br />
+30px<br />
 <br />
 <b>Description:</b><em><br />
-if the scrollable content is long, this option sets the minimum size (in pixels) of the scroll bar thumb automatically.<br />
+if the scrollable content is long, this option sets the minimum size (in <b>px</b>) of the scroll bar thumb automatically.<br />
 <br />
 ✦ Note:<br />
-this parameter is only used when <code>type="scroll"</code> is set.</em><br />
-<br />
+this parameter is only used when <code>type="scroll"</code> is set.<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -725,35 +800,52 @@ this parameter is only used when <code>type="scroll"</code> is set.</em><br />
 ###### **— OPTIMIZATIONS —**
 
 <details><summary><b><code>render</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-"lazy" | "virtual"<br />
-| {<br />
+<b>Usage:</b><br />
 <ul>
-  type: "lazy" | "virtual";<br />
-  rootMargin?: number | number[];<br />
-  stopLoadOnScroll?: boolean;<br />
+  <li><b>Simple</b>:<br />
+  
+```tsx
+render: "lazy"; // or "virtual"
+```
+
+  </li>
+  <li><b>Advanced</b>:<br />
+  
+```tsx
+render: {
+  type: "lazy", // or "virtual" (required)
+  rootMargin: 100, // or [v, h] | [t, r, b, l]
+  stopLoadOnScroll: true,
+  trackVisibility: true
+}
+```
+
+  </li>
 </ul>
-}<br />
-<br />
+
 <b>Description:</b><em><br />
 this parameter adds a gradual rendering of the content as it enters the viewport.<br />
 When used, a container is created for each scrollable object, and its absolute positioning is calculated based on scroll position and area dimensions.<br />
 <br />
-<code>type</code>:<br />
+<code><b>type</b></code>:
+
 <ul>
-  <li><b>"lazy"</b> - content is not deleted when it leaves the viewport.</li>
-  <li><b>"virtual"</b> - content is deleted when it leaves the viewport.</li>
+  <li><b>"lazy"</b> - render once when visible.</li>
+  <li><b>"virtual"</b> - render only when visible.</li>
 </ul>
 <br />
-<code>rootMargin</code>:<br />
-controls the threshold for loading content. It can be a single number or an array of 2 or 4 numbers. It is the distance for loading from the root element ( <b>.ms-element</b> ) in pixels.<br />
+<code><b>rootMargin</b></code>:<br />
+controls the threshold for loading content. It is the distance for loading from the root element (<b>.ms-element</b>) in px.<br />
 <br />
-<code>stopLoadOnScroll</code>:<br />
+<code><b>stopLoadOnScroll</b></code>:<br />
 controls whether to stop loading content when scrolling.<br />
 <br />
-✦ Note:<br />
-<code>render</code> is not compatible with <code>objectsSize: "none"</code>.</em><br />
+<code><b>trackVisibility</b></code>:<br />
+sets the <code>--content-visibility</code> variable for list item wrapper styles, which is very useful for styling such as <code>opacity: var(--content-visibility);</code>.<br />
 <br />
+✦ Note:<br />
+<code>render</code> is not compatible with <code>objectsSize: "none"</code>.<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -769,26 +861,44 @@ controls whether to stop loading content when scrolling.<br />
 <h2></h2>
 
 <details><summary><b><code>emptyElements</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-{<br />
+<b>Usage:</b><br />
 <ul>
-  mode: "clear" | "fallback" | { fallback: React.ReactNode };<br />
-  clickTrigger?: string | { selector: string; delay?: number };<br />
+  <li><b>Simple</b>:<br />
+  
+```tsx
+emptyElements: "clear"; // or "fallback" | <FallbackComponent />
+```
+
+  </li>
+  <li><b>Advanced</b>:<br />
+  
+```tsx
+emptyElements: {
+  mode: "clear", // or "fallback" | <FallbackComponent /> (required)
+  clickTrigger: ".btn-class", // or { selector: ".btn-class"; delay: 100 };
+}
+```
+
+  </li>
 </ul>
-}<br />
-<br />
+
 <b>Description:</b><em><br />
-this option will allow you to delete or replace empty list items during the first rendering, or to start this process by clicking<br />
+this option allows you to remove or replace empty list items during the initial render, or trigger this process via a click action<br />
 <br />
-<code>mode</code>:<br />
+<code><b>mode</b></code>:<br />
+
 <ul>
   <li><b>"clear"</b> – automatically removes empty elements.</li>
   <li><b>"fallback"</b> – replaces empty elements with the value from the <code>fallback</code> props.</li>
-  <li><b>{ fallback: React.ReactNode }</b> – if you need a different element than in <code>fallback</code> to replace empty elements, you can use this option.</li>
+  <li><b>{ fallback: React.ReactNode }</b> – allows you to override the default <code>fallback</code> content for this instance.</li>
 </ul>
 <br />
-<code>clickTrigger</code>:<br />
-in case if elements are removed via a click action, use this option. It accepts an object with a <code>selector</code> ( such as a delete button’s class ) and <code>delay</code> ( in <b>ms</b> ) to wait before removing the elements.<br />
+<code><b>clickTrigger</b></code>:<br />
+use this option if removal should be triggered by a click action.<br />
+<ul>
+  <li><b>"selector"</b> – CSS selector that triggers the removal.</li>
+  <li><b>"delay"</b> – delay before removal ( in <b>ms</b> ).</li>
+</ul>
 <br />
 ✦ Note:<br />
 <ul>
@@ -796,18 +906,12 @@ in case if elements are removed via a click action, use this option. It accepts
   <li>If you use <code>clickTrigger</code>:<br />
   - consider increasing <code>delay</code>, since the cleanup may run before removal.<br />
   - the wrapper <code>.ms-object-box</code> also gets the <code>remove</code> class, which you can use e.g. for fade-out animations.</li>
-</ul></em>
-<br />
+</ul>
+</em><br />
 <b>Example:</b>
 
 ```tsx
-<MorphScroll
-  {...props}
-  emptyElements={{
-    mode: "clear",
-    clickTrigger: ".close-button",
-  }}
->
+<MorphScroll {...props} emptyElements="clear">
   {children}
 </MorphScroll>
 ```
@@ -819,9 +923,12 @@ in case if elements are removed via a click action, use this option. It accepts
 <h2></h2>
 
 <details><summary><b><code>suspending</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-boolean<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+suspending: true;
+```
+
 <b>Default:</b><br />
 false<br />
 <br />
@@ -841,19 +948,17 @@ adds React Suspense to the MorphScroll component for async rendering.</em><br />
 <h2></h2>
 
 <details><summary><b><code>fallback</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-React.ReactNode<br />
-<br />
 <b>Description:</b><em><br />
 sets the fallback element to display during loading or placeholder.<br />
 <br />
 It will be used when:
+
 <ul>
   <li><code>suspending</code> is set to <b>true</b>.</li>
   <li><code>render.stopLoadOnScroll</code> is set to <b>true</b>.</li>
   <li><code>emptyElements.mode</code> is set to <b>"fallback"</b>.</li> 
-</ul></em><br />
-<br />
+</ul>
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -876,12 +981,9 @@ It will be used when:
 <ul><div>
 
 <details><summary><b><code>className</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-string<br />
-<br />
 <b>Description:</b><em><br />
-allows you to add additional classes to the component.</em><br />
-<br />
+allows to add additional classes to the component.<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -893,12 +995,9 @@ allows you to add additional classes to the component.</em><br />
 <h2></h2>
 
 <details><summary><b><code>children</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-React.ReactNode<br />
-<br />
 <b>Description:</b><em><br />
-allows you to add custom content to the component.</em><br />
-<br />
+allows to add custom content to the component.<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -910,9 +1009,9 @@ allows you to add custom content to the component.</em><br />
 <h2></h2>
 
 <details><summary><b><code>style</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-React.CSSProperties<br />
-<br />
+<b>Description:</b><em><br />
+allows to add custom inline styles.<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -924,20 +1023,26 @@ React.CSSProperties<br />
 <h2></h2>
 
 <details><summary><b><code>measure</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-"inner" | "outer" | "all"<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+measure: "outer"; // or "inner" | "all"
+```
+
 <b>Default:</b><br />
 "inner"<br />
 <br />
 <b>Description:</b><em><br />
 determines what is being measured by automatically applying inline styles that affect width and height.<br />
 <br />
-<ul>
-  <li><b>"inner"</b> sets <code>width: "max-content"</code> and <code>height: "max-content"</code>, measuring the size of child elements.</li>
-  <li><b>"outer"</b> measures the parent element by setting <code>minWidth: "100%"</code> and <code>minHeight: "100%"</code>.</li>
-  <li><b>"all"</b> value combines the styles of both <code>"inner"</code> and <code>"outer"</code>, allowing measurement of both the parent and child elements.</li>
-</ul>
+<code><b>"inner"</b></code>:<br />
+sets <code>width: "max-content"</code> and <code>height: "max-content"</code>, measuring the size of child elements.<br />
+<br />
+<code><b>"outer"</b></code>:<br />
+measures the parent element by setting <code>minWidth: "100%"</code> and <code>minHeight: "100%"</code>.<br />
+<br />
+<code><b>"all"</b></code>:<br />
+value combines the styles of both <code>"inner"</code> and <code>"outer"</code>, allowing measurement of both the parent and child elements.<br />
 <br />
 ✦ Note: <br />
 Be cautious when overriding styles via the <code>style</code> prop, as it may interfere with the styles applied by <code>measure</code>, leading to unexpected behavior.</em><br />
@@ -953,13 +1058,10 @@ Be cautious when overriding styles via the <code>style</code> prop, as it may in
 <h2></h2>
 
 <details><summary><b><code>onResize</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-(rect: Partial<DOMRectReadOnly>) => void<br />
-<br />
 <b>Description:</b><em><br />
 callback function that is triggered whenever the observed element's dimensions change.<br />
-The function receives an object containing the updated size properties.</em><br />
-<br />
+The function receives an object of type <b>Partial<DOMRectReadOnly></b> that containing updated size properties.<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -993,12 +1095,9 @@ The function receives an object containing the updated size properties.</em><br
 <ul><div>
 
 <details><summary><b><code>className</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-string<br />
-<br />
 <b>Description:</b><em><br />
-allows you to add additional classes to the component.</em><br />
-<br />
+allows to add additional classes to the component.<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -1010,9 +1109,9 @@ allows you to add additional classes to the component.</em><br />
 <h2></h2>
 
 <details><summary><b><code>children</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-React.ReactNode<br />
-<br />
+<b>Description:</b><em><br />
+allows to add custom content to the component.<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -1024,9 +1123,9 @@ React.ReactNode<br />
 <h2></h2>
 
 <details><summary><b><code>style</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-React.CSSProperties<br />
-<br />
+<b>Description:</b><em><br />
+allows to add custom inline styles.<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -1040,16 +1139,13 @@ React.CSSProperties<br />
 <h2></h2>
 
 <details><summary><b><code>root</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-Element | null<br />
-<br />
 <b>Default:</b><br />
-null (window)<br />
+null (browser window)<br />
 <br />
 <b>Description:</b><em><br />
 specifies the element that serves as the bounding box for the intersection observation. 
-If provided, it must be an ancestor of the observed element.</em><br />
-<br />
+If provided, it must be an ancestor of the observed element.<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -1063,15 +1159,15 @@ If provided, it must be an ancestor of the observed element.</em><br />
 <h2></h2>
 
 <details><summary><b><code>rootMargin</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-number | number[]<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+rootMargin: 10; // or [v, h] | [t, r, b, l]
+```
+
 <b>Description:</b><em><br />
 defines an offset around the root element, expanding or shrinking the observed area.<br />
-<br />
-✦ Note:<br />
-it can be a single number or an array of 2 <b>[ top-bottom, left-right ]</b> or 4 <b>[ top, right, bottom, left ]</b> numbers.</em><br />
-<br />
+</em><br />
 <b>Example:</b>
 
 ```tsx
@@ -1083,16 +1179,20 @@ it can be a single number or an array of 2 <b>[ top-bottom, left-right ]</b> or
 <h2></h2>
 
 <details><summary><b><code>threshold</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-number | number[]<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+threshold: 0.5; // or [0, 0.5, 1]
+```
+
 <b>Default:</b><br />
 0<br />
 <br />
 <b>Description:</b><em><br />
-specifies at what percentage of the observed element’s visibility the callback should be executed.<br />
+specifies at what percentage of the observed element’s visibility the callback <code>onIntersection</code> should be executed.<br />
 <br />
 ✦ Note:<br />
+
 <ul>
   <li>A value of <code>0</code> means the callback fires when any part of the element appears, while <code>1</code> means the element must be fully visible.</li>
   <li>An array (e.g., <code>[0, 0.5, 1]</code>) triggers the callback multiple times at different visibility levels.</li>
@@ -1109,9 +1209,12 @@ specifies at what percentage of the observed element’s visibility the callback
 <h2></h2>
 
 <details><summary><b><code>visibleContent</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-boolean<br />
-<br />
+<b>Usage:</b><br />
+
+```tsx
+visibleContent: true;
+```
+
 <b>Default:</b><br />
 false<br />
 <br />
@@ -1130,21 +1233,18 @@ This is useful for testing purposes or when using the <code>onIntersection</code
 <h2></h2>
 
 <details><summary><b><code>onIntersection</code></b></summary><br /><ul><div>
-<b>Type:</b><br />
-(entry: IntersectionObserverEntry) => void<br />
-<br />
 <b>Description:</b><em><br />
 callback function that is called when the observed element enters or leaves the viewport or the area defined by the <code>root</code> property. This can be used to load new list items for <code>MorphScroll</code>.<br />
 <br />
 ✦ Note:<br />
-the <code>IntersectionObserverEntry</code> object provides details about the intersection state, including:<br />
+<code>entry</code> is an object of type <b>IntersectionObserverEntry</b> that provides details about the intersection state, including:<br />
 <ul>
-  <li><code>boundingClientRect</code>: The bounding rectangle of the element relative to the viewport.</li>
-  <li><code>intersectionRatio</code>: The percentage of the element that is visible in the viewport.</li>
-  <li><code>intersectionRect</code>: The intersection rectangle between the element and the viewport.</li>
-  <li><code>rootBounds</code>: The bounding rectangle of the root element relative to the viewport.</li>
-  <li><code>target</code>: The observed element.</li>
-  <li><code>time</code>: The timestamp when the intersection state changed.</li>
+  <li><code>boundingClientRect</code>: bounding rectangle of the element relative to the viewport.</li>
+  <li><code>intersectionRatio</code>: percentage of the element that is visible in the viewport.</li>
+  <li><code>intersectionRect</code>: intersection rectangle between the element and the viewport.</li>
+  <li><code>rootBounds</code>: bounding rectangle of the root element relative to the viewport.</li>
+  <li><code>target</code>: observed element.</li>
+  <li><code>time</code>: timestamp when the intersection state changed.</li>
 </ul></em>
 <br />
 <b>Example:</b>