@rio-cloud/uikit-mcp 1.0.0 → 1.1.0

package/dist/docs/components/virtualList.md

@@ -0,0 +1,483 @@
+# VirtualList
+
+*Category:* Components
+*Section:* Content
+*Source:* https://uikit.developers.rio.cloud/#components/virtualList
+*Captured:* 2025-12-12T12:38:48.209Z
+
+The VirtualList component is designed for efficiently rendering large lists of items by only displaying the visible portion of the list, also known as windowing.
+
+## VirtualList
+
+It allows a specified number of items outside the viewport for smoother scrolling. It optimizes performance by minimizing DOM updates and provides a customizable rendering function for each item, making it ideal for applications that require dynamic and responsive list displays.
+
+### Example: Example 1
+
+Virtual list with 100 itemsItem 1
+Et viverra Sed et quis, adipiscing
+
+Item 2
+Ac efficitur dolor molestie In finibus ipsum in in, nec felis. eget
+
+Item 3
+Rutrum Mauris molestie finibus faucibus. pretium
+
+Item 4
+Libero massa, Mauris ante efficitur
+
+Item 5
+In sem. in,
+Lorem et
+
+Item 6
+Vivamus sem. molestie in, vitae orci, ante ac in consectetur ut
+
+Item 7
+Finibus et faucibus. elit. et tortor
+
+Item 8
+Adipiscing tortor sem. in Mauris metus ligula felis.
+
+Item 9
+Vitae in lorem dolor ante elit. efficitur finibus fames felis. et eget fringilla vel volutpat
+
+Item 10
+Duis tortor libero orci aliquam ac semper. elit. elit. finibus primis massa consectetur condimentum Vivamus
+
+#### Summary
+
+Virtual list with 100 itemsItem 1
+Et viverra Sed et quis, adipiscing
+
+Item 2
+Ac efficitur dolor molestie In finibus ipsum in in, nec felis. eget
+
+Item 3
+Rutrum Mauris molestie finibus faucibus. pretium
+
+Item 4
+Libero massa, Mauris ante efficitur
+
+Item 5
+In sem. in,
+Lorem et
+
+Item 6
+Vivamus sem. molestie in, vitae orci, ante ac in consectetur ut
+
+Item 7
+Finibus et faucibus. elit. et tortor
+
+Item 8
+Adipiscing tortor sem. in Mauris metus ligula felis.
+
+Item 9
+Vitae in lorem dolor ante elit. efficitur finibus fames felis. et eget fringilla vel volutpat
+
+Item 10
+Duis tortor libero orci aliquam ac semper. elit. elit. finibus primis massa consectetur condimentum Vivamus
+
+#### React (tsx)
+
+```tsx
+import VirtualList from '@rio-cloud/rio-uikit/VirtualList';
+
+import { generateDummyText } from '../../../utils/data';
+
+const ITEM_COUNT = 100;
+
+export default () => {
+    const items = Array.from({ length: ITEM_COUNT }, (_, index) => ({
+        title: `Item ${index + 1}`,
+        description: generateDummyText(),
+    }));
+
+    return (
+        <div className='max-width-600 padding-y-20'>
+            <label className='padding-left-10'>Virtual list with {ITEM_COUNT} items</label>
+            <VirtualList
+                items={items}
+                renderItem={(item, index) => (
+                    <div
+                        key={index}
+                        className='margin-bottom-10 padding-y-10 padding-x-15 bg-white rounded shadow-accent text-color-darker'
+                    >
+                        <div className='text-medium' data-test-ignore='text'>
+                            {item.title}
+                        </div>
+                        <div className='word-break' data-test-ignore='text'>
+                            {item.description}
+                        </div>
+                    </div>
+                )}
+                className='max-height-400 padding-x-10'
+            />
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="max-width-600 padding-y-20">
+    <label class="padding-left-10">Virtual list with 100 items</label>
+    <div class="VirtualList overflow-y-auto max-height-400 padding-x-10" style="height: 100%; position: relative; overflow: auto;">
+        <div class="position-relative" style="height: 7200px;">
+            <div class="VirtualListItemContainer ">
+                <div class="VirtualListItemWrapper " data-index="0" style="position: absolute; transform: translateY(0px); width: 100%; will-change: transform;">
+                    <div class="margin-bottom-10 padding-y-10 padding-x-15 bg-white rounded shadow-accent text-color-darker">
+                        <div class="text-medium" data-test-ignore="text">Item 1</div>
+                        <div class="word-break" data-test-ignore="text">Et viverra Sed et quis, adipiscing</div>
+                    </div>
+                </div>
+                <div class="VirtualListItemWrapper " data-index="1" style="position: absolute; transform: translateY(70px); width: 100%; will-change: transform;">
+                    <div class="margin-bottom-10 padding-y-10 padding-x-15 bg-white rounded shadow-accent text-color-darker">
+                        <div class="text-medium" data-test-ignore="text">Item 2</div>
+                        <div class="word-break" data-test-ignore="text">Ac efficitur dolor molestie In finibus ipsum in in, nec felis. eget</div>
+                    </div>
+                </div>
+                <div class="VirtualListItemWrapper " data-index="2" style="position: absolute; transform: translateY(140px); width: 100%; will-change: transform;">
+                    <div class="margin-bottom-10 padding-y-10 padding-x-15 bg-white rounded shadow-accent text-color-darker">
+                        <div class="text-medium" data-test-ignore="text">Item 3</div>
+                        <div class="word-break" data-test-ignore="text">Rutrum Mauris molestie finibus faucibus. pretium</div>
+                    </div>
+                </div>
+                <div class="VirtualListItemWrapper " data-index="3" style="position: absolute; transform: translateY(210px); width: 100%; will-change: transform;">
+                    <div class="margin-bottom-10 padding-y-10 padding-x-15 bg-white rounded shadow-accent text-color-darker">
+                        <div class="text-medium" data-test-ignore="text">Item 4</div>
+                        <div class="word-break" data-test-ignore="text">Libero massa, Mauris ante efficitur</div>
+                    </div>
+                </div>
+                <div class="VirtualListItemWrapper " data-index="4" style="position: absolute; transform: translateY(280px); width: 100%; will-change: transform;">
+                    <div class="margin-bottom-10 padding-y-10 padding-x-15 bg-white rounded shadow-accent text-color-darker">
+                        <div class="text-medium" data-test-ignore="text">Item 5</div>
+                        <div class="word-break" data-test-ignore="text">In sem. in,
+                            Lorem et</div>
+                    </div>
+                </div>
+                <div class="VirtualListItemWrapper " data-index="5" style="position: absolute; transform: translateY(350px); width: 100%; will-change: transform;">
+                    <div class="margin-bottom-10 padding-y-10 padding-x-15 bg-white rounded shadow-accent text-color-darker">
+                        <div class="text-medium" data-test-ignore="text">Item 6</div>
+                        <div class="word-break" data-test-ignore="text">Vivamus sem. molestie in, vitae orci, ante ac in consectetur ut</div>
+                    </div>
+                </div>
+                <div class="VirtualListItemWrapper " data-index="6" style="position: absolute; transform: translateY(420px); width: 100%; will-change: transform;">
+                    <div class="margin-bottom-10 padding-y-10 padding-x-15 bg-white rounded shadow-accent text-color-darker">
+                        <div class="text-medium" data-test-ignore="text">Item 7</div>
+                        <div class="word-break" data-test-ignore="text">Finibus et faucibus. elit. et tortor</div>
+                    </div>
+                </div>
+                <div class="VirtualListItemWrapper " data-index="7" style="position: absolute; transform: translateY(490px); width: 100%; will-change: transform;">
+                    <div class="margin-bottom-10 padding-y-10 padding-x-15 bg-white rounded shadow-accent text-color-darker">
+                        <div class="text-medium" data-test-ignore="text">Item 8</div>
+                        <div class="word-break" data-test-ignore="text">Adipiscing tortor sem. in Mauris metus ligula felis.</div>
+                    </div>
+                </div>
+                <div class="VirtualListItemWrapper " data-index="8" style="position: absolute; transform: translateY(560px); width: 100%; will-change: transform;">
+                    <div class="margin-bottom-10 padding-y-10 padding-x-15 bg-white rounded shadow-accent text-color-darker">
+                        <div class="text-medium" data-test-ignore="text">Item 9</div>
+                        <div class="word-break" data-test-ignore="text">Vitae in lorem dolor ante elit. efficitur finibus fames felis. et eget fringilla vel volutpat</div>
+                    </div>
+                </div>
+                <div class="VirtualListItemWrapper " data-index="9" style="position: absolute; transform: translateY(630px); width: 100%; will-change: transform;">
+                    <div class="margin-bottom-10 padding-y-10 padding-x-15 bg-white rounded shadow-accent text-color-darker">
+                        <div class="text-medium" data-test-ignore="text">Item 10</div>
+                        <div class="word-break" data-test-ignore="text">Duis tortor libero orci aliquam ac semper. elit. elit. finibus primis massa consectetur condimentum Vivamus</div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| items | T[] | — | The array of items to be rendered in the list. |
+| renderItem | (item: T, index: number) => React.ReactElement | — | A function that renders an item given its data and index. |
+| overscanCount | number | 3 | The number of items to render outside the visible area for smoother scrolling. |
+| defaultHeight | number | 50 | The default height for items if their height cannot be determined. |
+| scrollContainerRef | React.RefObject<HTMLElement> | — | Optional ref to an external scroll container. Use this when VirtualList is inside a scrollable container. |
+| containerClassName | string | — | Additional classNames for the container of the list items. |
+| listItemWrapperClassName | string | — | Additional classNames for each individual list item wrapper. This wrapper is required for proper positioning each item in the list using an absolute top value. |
+| className | string | — | Additional classNames for the outer list container. |
+
+### Example: Example 2
+
+Virtual list with 5000 items
+Vehicle 1
+Ligula nec felis. in ante volutpat felis. fringilla finibus scelerisque
+
+Vehicle 2
+Libero molestie molestie pretium efficitur ac felis. dui elit. Integer fames iaculis. Duis sit
+
+Vehicle 3
+Viverra Integer dolor molestie orci, primis
+
+Vehicle 4
+Faucibus. orci, ante ut et libero primis
+
+Vehicle 5
+In orci In Vivamus libero adipiscing Sed ligula fringilla bibendum, elit. molestie ipsum ante finibus
+
+Vehicle 6
+Bibendum, adipiscing neque. ac semper in sem. Integer vel
+
+Vehicle 7
+Efficitur rutrum lorem velit. ut
+
+Vehicle 8
+Quis, eget viverra faucibus. aliquam elit. ante finibus ac fames libero finibus pretium
+
+Vehicle 9
+Orci fames Interdum felis. Integer semper. purus efficitur fames sem. ac
+
+Vehicle 10
+Dolor semper. vitae sit libero sit quis,
+
+#### Summary
+
+Virtual list with 5000 items
+Vehicle 1
+Ligula nec felis. in ante volutpat felis. fringilla finibus scelerisque
+
+Vehicle 2
+Libero molestie molestie pretium efficitur ac felis. dui elit. Integer fames iaculis. Duis sit
+
+Vehicle 3
+Viverra Integer dolor molestie orci, primis
+
+Vehicle 4
+Faucibus. orci, ante ut et libero primis
+
+Vehicle 5
+In orci In Vivamus libero adipiscing Sed ligula fringilla bibendum, elit. molestie ipsum ante finibus
+
+Vehicle 6
+Bibendum, adipiscing neque. ac semper in sem. Integer vel
+
+Vehicle 7
+Efficitur rutrum lorem velit. ut
+
+Vehicle 8
+Quis, eget viverra faucibus. aliquam elit. ante finibus ac fames libero finibus pretium
+
+Vehicle 9
+Orci fames Interdum felis. Integer semper. purus efficitur fames sem. ac
+
+Vehicle 10
+Dolor semper. vitae sit libero sit quis,
+
+#### React (tsx)
+
+```tsx
+import { useRef } from 'react';
+
+import Avatar from '@rio-cloud/rio-uikit/Avatar';
+import VirtualList from '@rio-cloud/rio-uikit/VirtualList';
+
+import { generateDummyText } from '../../../utils/data';
+
+const DemoItem = ({ title, description }: { title: string; description: string }) => (
+    <div className='display-flex gap-15 align-items-center'>
+        <Avatar iconName='truck' backgroundColor='bg-lightest' />
+        <div>
+            <div className='text-medium' data-test-ignore='text'>
+                {title}
+            </div>
+            <div className='word-break' data-test-ignore='text'>
+                {description}
+            </div>
+        </div>
+    </div>
+);
+
+const ITEM_COUNT = 5_000;
+
+// This demo includes:
+// - A custom item component
+// - List group styling for the inner container and the items wrapper
+// - The max height is defined outside on the parent of the VirtualList using a scrollContainerRef
+// - A custom overscan count, means more items are loaded outside the visible window
+
+export default () => {
+    const items = Array.from({ length: ITEM_COUNT }, (_, index) => ({
+        title: `Vehicle ${index + 1}`,
+        description: generateDummyText(),
+    }));
+
+    const scrollContainerRef = useRef<HTMLDivElement>(null);
+
+    return (
+        <div className='padding-20'>
+            <label>Virtual list with {ITEM_COUNT} items</label>
+            <div ref={scrollContainerRef} className='max-width-600 max-height-400 overflow-y-auto'>
+                <VirtualList
+                    items={items}
+                    renderItem={(item, index) => (
+                        <DemoItem key={index} title={item.title} description={item.description} />
+                    )}
+                    className='border rounded'
+                    containerClassName='list-group'
+                    listItemWrapperClassName='list-group-item padding-y-15'
+                    defaultHeight={71}
+                    overscanCount={5}
+                    scrollContainerRef={scrollContainerRef}
+                />
+            </div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="padding-20">
+    <label>Virtual list with 5000 items</label>
+    <div class="max-width-600 max-height-400 overflow-y-auto">
+        <div class="VirtualList overflow-y-auto border rounded" style="height: 360000px; position: relative; overflow: visible;">
+            <div class="position-relative" style="height: auto;">
+                <div class="VirtualListItemContainer list-group">
+                    <div class="VirtualListItemWrapper list-group-item padding-y-15" data-index="0" style="position: absolute; transform: translateY(0px); width: 100%; will-change: transform;">
+                        <div class="display-flex gap-15 align-items-center">
+                            <div class="Avatar bg-lightest" style="height: 40px;">
+                                <span class="Avatar-icon rioglyph rioglyph-truck ">
+                                </span>
+                            </div>
+                            <div>
+                                <div class="text-medium" data-test-ignore="text">Vehicle 1</div>
+                                <div class="word-break" data-test-ignore="text">Ligula nec felis. in ante volutpat felis. fringilla finibus scelerisque</div>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="VirtualListItemWrapper list-group-item padding-y-15" data-index="1" style="position: absolute; transform: translateY(69px); width: 100%; will-change: transform;">
+                        <div class="display-flex gap-15 align-items-center">
+                            <div class="Avatar bg-lightest" style="height: 40px;">
+                                <span class="Avatar-icon rioglyph rioglyph-truck ">
+                                </span>
+                            </div>
+                            <div>
+                                <div class="text-medium" data-test-ignore="text">Vehicle 2</div>
+                                <div class="word-break" data-test-ignore="text">Libero molestie molestie pretium efficitur ac felis. dui elit. Integer fames iaculis. Duis sit</div>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="VirtualListItemWrapper list-group-item padding-y-15" data-index="2" style="position: absolute; transform: translateY(139px); width: 100%; will-change: transform;">
+                        <div class="display-flex gap-15 align-items-center">
+                            <div class="Avatar bg-lightest" style="height: 40px;">
+                                <span class="Avatar-icon rioglyph rioglyph-truck ">
+                                </span>
+                            </div>
+                            <div>
+                                <div class="text-medium" data-test-ignore="text">Vehicle 3</div>
+                                <div class="word-break" data-test-ignore="text">Viverra Integer dolor molestie orci, primis</div>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="VirtualListItemWrapper list-group-item padding-y-15" data-index="3" style="position: absolute; transform: translateY(209px); width: 100%; will-change: transform;">
+                        <div class="display-flex gap-15 align-items-center">
+                            <div class="Avatar bg-lightest" style="height: 40px;">
+                                <span class="Avatar-icon rioglyph rioglyph-truck ">
+                                </span>
+                            </div>
+                            <div>
+                                <div class="text-medium" data-test-ignore="text">Vehicle 4</div>
+                                <div class="word-break" data-test-ignore="text">Faucibus. orci, ante ut et libero primis</div>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="VirtualListItemWrapper list-group-item padding-y-15" data-index="4" style="position: absolute; transform: translateY(279px); width: 100%; will-change: transform;">
+                        <div class="display-flex gap-15 align-items-center">
+                            <div class="Avatar bg-lightest" style="height: 40px;">
+                                <span class="Avatar-icon rioglyph rioglyph-truck ">
+                                </span>
+                            </div>
+                            <div>
+                                <div class="text-medium" data-test-ignore="text">Vehicle 5</div>
+                                <div class="word-break" data-test-ignore="text">In orci In Vivamus libero adipiscing Sed ligula fringilla bibendum, elit. molestie ipsum ante finibus</div>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="VirtualListItemWrapper list-group-item padding-y-15" data-index="5" style="position: absolute; transform: translateY(369px); width: 100%; will-change: transform;">
+                        <div class="display-flex gap-15 align-items-center">
+                            <div class="Avatar bg-lightest" style="height: 40px;">
+                                <span class="Avatar-icon rioglyph rioglyph-truck ">
+                                </span>
+                            </div>
+                            <div>
+                                <div class="text-medium" data-test-ignore="text">Vehicle 6</div>
+                                <div class="word-break" data-test-ignore="text">Bibendum, adipiscing neque. ac semper in sem. Integer vel</div>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="VirtualListItemWrapper list-group-item padding-y-15" data-index="6" style="position: absolute; transform: translateY(439px); width: 100%; will-change: transform;">
+                        <div class="display-flex gap-15 align-items-center">
+                            <div class="Avatar bg-lightest" style="height: 40px;">
+                                <span class="Avatar-icon rioglyph rioglyph-truck ">
+                                </span>
+                            </div>
+                            <div>
+                                <div class="text-medium" data-test-ignore="text">Vehicle 7</div>
+                                <div class="word-break" data-test-ignore="text">Efficitur rutrum lorem velit. ut</div>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="VirtualListItemWrapper list-group-item padding-y-15" data-index="7" style="position: absolute; transform: translateY(509px); width: 100%; will-change: transform;">
+                        <div class="display-flex gap-15 align-items-center">
+                            <div class="Avatar bg-lightest" style="height: 40px;">
+                                <span class="Avatar-icon rioglyph rioglyph-truck ">
+                                </span>
+                            </div>
+                            <div>
+                                <div class="text-medium" data-test-ignore="text">Vehicle 8</div>
+                                <div class="word-break" data-test-ignore="text">Quis, eget viverra faucibus. aliquam elit. ante finibus ac fames libero finibus pretium</div>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="VirtualListItemWrapper list-group-item padding-y-15" data-index="8" style="position: absolute; transform: translateY(579px); width: 100%; will-change: transform;">
+                        <div class="display-flex gap-15 align-items-center">
+                            <div class="Avatar bg-lightest" style="height: 40px;">
+                                <span class="Avatar-icon rioglyph rioglyph-truck ">
+                                </span>
+                            </div>
+                            <div>
+                                <div class="text-medium" data-test-ignore="text">Vehicle 9</div>
+                                <div class="word-break" data-test-ignore="text">Orci fames Interdum felis. Integer semper. purus efficitur fames sem. ac</div>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="VirtualListItemWrapper list-group-item padding-y-15" data-index="9" style="position: absolute; transform: translateY(649px); width: 100%; will-change: transform;">
+                        <div class="display-flex gap-15 align-items-center">
+                            <div class="Avatar bg-lightest" style="height: 40px;">
+                                <span class="Avatar-icon rioglyph rioglyph-truck ">
+                                </span>
+                            </div>
+                            <div>
+                                <div class="text-medium" data-test-ignore="text">Vehicle 10</div>
+                                <div class="word-break" data-test-ignore="text">Dolor semper. vitae sit libero sit quis,</div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| items | T[] | — | The array of items to be rendered in the list. |
+| renderItem | (item: T, index: number) => React.ReactElement | — | A function that renders an item given its data and index. |
+| overscanCount | number | 3 | The number of items to render outside the visible area for smoother scrolling. |
+| defaultHeight | number | 50 | The default height for items if their height cannot be determined. |
+| scrollContainerRef | React.RefObject<HTMLElement> | — | Optional ref to an external scroll container. Use this when VirtualList is inside a scrollable container. |
+| containerClassName | string | — | Additional classNames for the container of the list items. |
+| listItemWrapperClassName | string | — | Additional classNames for each individual list item wrapper. This wrapper is required for proper positioning each item in the list using an absolute top value. |
+| className | string | — | Additional classNames for the outer list container. |