@rio-cloud/uikit-mcp 1.0.1 → 1.1.1

package/dist/docs/components/virtualList.md

@@ -0,0 +1,486 @@
+# VirtualList
+
+*Category:* Components
+*Section:* Content
+*Source:* https://uikit.developers.rio.cloud/#components/virtualList
+*Captured:* 2025-12-12T14:20:50.395Z
+
+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
+In ante Sed nunc finibus ante massa, tortor ac In Mauris amet, Vivamus
+
+Item 2
+Efficitur Integer in Mauris Ut ac pretium tincidunt. ipsum elementum enim
+
+Item 3
+Ligula ut bibendum, Fusce nunc
+
+Item 4
+Nec ac iaculis. In iaculis. massa ante fames Fusce massa, sem. elit. primis ipsum
+
+Item 5
+Elit. volutpat sit eget et hendrerit adipiscing nec vel et ut amet, nec
+
+Item 6
+Pretium elit. elit. sagittis dui semper amet, hendrerit ipsum
+
+Item 7
+Est eget efficitur sem. ante semper Integer neque. enim condimentum in sit ligula elit.
+
+Item 8
+Scelerisque Ut ante et aliquam Mauris pharetra finibus semper. vitae libero efficitur In
+
+Item 9
+Est in ante enim metus Mauris elit. Ut
+Lorem elit. vitae hendrerit scelerisque amet,
+
+Item 10
+Posuere dui orci libero et massa, finibus
+
+#### Summary
+
+Virtual list with 100 itemsItem 1
+In ante Sed nunc finibus ante massa, tortor ac In Mauris amet, Vivamus
+
+Item 2
+Efficitur Integer in Mauris Ut ac pretium tincidunt. ipsum elementum enim
+
+Item 3
+Ligula ut bibendum, Fusce nunc
+
+Item 4
+Nec ac iaculis. In iaculis. massa ante fames Fusce massa, sem. elit. primis ipsum
+
+Item 5
+Elit. volutpat sit eget et hendrerit adipiscing nec vel et ut amet, nec
+
+Item 6
+Pretium elit. elit. sagittis dui semper amet, hendrerit ipsum
+
+Item 7
+Est eget efficitur sem. ante semper Integer neque. enim condimentum in sit ligula elit.
+
+Item 8
+Scelerisque Ut ante et aliquam Mauris pharetra finibus semper. vitae libero efficitur In
+
+Item 9
+Est in ante enim metus Mauris elit. Ut
+Lorem elit. vitae hendrerit scelerisque amet,
+
+Item 10
+Posuere dui orci libero et massa, finibus
+
+#### 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: 7000px;">
+            <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">In ante Sed nunc finibus ante massa, tortor ac In Mauris amet, Vivamus</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">Efficitur Integer in Mauris Ut ac pretium tincidunt. ipsum elementum enim</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">Ligula ut bibendum, Fusce nunc</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">Nec ac iaculis. In iaculis. massa ante fames Fusce massa, sem. elit. primis ipsum</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">Elit. volutpat sit eget et hendrerit adipiscing nec vel et ut amet, nec</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">Pretium elit. elit. sagittis dui semper amet, hendrerit ipsum</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">Est eget efficitur sem. ante semper Integer neque. enim condimentum in sit ligula elit.</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">Scelerisque Ut ante et aliquam Mauris pharetra finibus semper. vitae libero efficitur In</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">Est in ante enim metus Mauris elit. Ut
+                            Lorem elit. vitae hendrerit scelerisque amet,</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">Posuere dui orci libero et massa, finibus</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
+Rutrum quis, ipsum sit tincidunt. semper. libero ac ut tincidunt.
+
+Vehicle 2
+Ligula Ut tortor in aliquam
+
+Vehicle 3
+Mauris ut vitae Fusce et et Fusce orci, primis lorem neque. sem. orci In ut
+
+Vehicle 4
+Pretium est orci ante aliquam
+
+Vehicle 5
+Nec condimentum enim sagittis quis, quis, fames dolor
+
+Vehicle 6
+Interdum eget orci velit. elit. sagittis bibendum, elit. massa ac pretium iaculis.
+
+Vehicle 7
+Ante Duis Interdum ut dolor aliquam
+Lorem dolor tincidunt. volutpat primis iaculis. iaculis.
+
+Vehicle 8
+Nec iaculis. et lorem condimentum ac semper. neque. Interdum
+
+Vehicle 9
+Metus adipiscing fames orci, consectetur Duis efficitur Integer eget ipsum elit.
+
+Vehicle 10
+Interdum vitae Fusce adipiscing tincidunt. hendrerit ac condimentum In in semper
+
+#### Summary
+
+Virtual list with 5000 items
+Vehicle 1
+Rutrum quis, ipsum sit tincidunt. semper. libero ac ut tincidunt.
+
+Vehicle 2
+Ligula Ut tortor in aliquam
+
+Vehicle 3
+Mauris ut vitae Fusce et et Fusce orci, primis lorem neque. sem. orci In ut
+
+Vehicle 4
+Pretium est orci ante aliquam
+
+Vehicle 5
+Nec condimentum enim sagittis quis, quis, fames dolor
+
+Vehicle 6
+Interdum eget orci velit. elit. sagittis bibendum, elit. massa ac pretium iaculis.
+
+Vehicle 7
+Ante Duis Interdum ut dolor aliquam
+Lorem dolor tincidunt. volutpat primis iaculis. iaculis.
+
+Vehicle 8
+Nec iaculis. et lorem condimentum ac semper. neque. Interdum
+
+Vehicle 9
+Metus adipiscing fames orci, consectetur Duis efficitur Integer eget ipsum elit.
+
+Vehicle 10
+Interdum vitae Fusce adipiscing tincidunt. hendrerit ac condimentum In in semper
+
+#### 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">Rutrum quis, ipsum sit tincidunt. semper. libero ac ut tincidunt.</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">Ligula Ut tortor in aliquam</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">Mauris ut vitae Fusce et et Fusce orci, primis lorem neque. sem. orci In ut</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">Pretium est orci ante aliquam</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">Nec condimentum enim sagittis quis, quis, fames dolor</div>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="VirtualListItemWrapper list-group-item padding-y-15" data-index="5" style="position: absolute; transform: translateY(349px); 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">Interdum eget orci velit. elit. sagittis bibendum, elit. massa ac pretium iaculis.</div>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="VirtualListItemWrapper list-group-item padding-y-15" data-index="6" style="position: absolute; transform: translateY(419px); 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">Ante Duis Interdum ut dolor aliquam
+                                    Lorem dolor tincidunt. volutpat primis iaculis. iaculis.</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">Nec iaculis. et lorem condimentum ac semper. neque. Interdum</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">Metus adipiscing fames orci, consectetur Duis efficitur Integer eget ipsum elit.</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">Interdum vitae Fusce adipiscing tincidunt. hendrerit ac condimentum In in semper</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. |