@xlabs-store/core 0.0.1

package/dist/collection/components/x-virtual-scroll/x-virtual-scroll.css

@@ -0,0 +1,79 @@
+/**
+* X-Virtual-Scroll Component Variables
+* 
+* Variables for virtual scroll component styling
+*/
+/**
+ * X-Virtual-Scroll Component Styles
+ * 
+ * Styles for virtual scrolling container
+ */
+:host {
+  display: block;
+  box-sizing: border-box;
+  font-family: var(--x-font-family);
+}
+
+.x-virtual-scroll-host {
+  display: block;
+  width: 100%;
+}
+
+.x-virtual-scroll-container {
+  background: var(--x-color-bg-base, #ffffff);
+  border: var(--x-border-width-base, 1px) var(--x-virtual-scroll-border-style, solid) var(--x-color-border, #d9d9d9);
+  border-radius: var(--x-border-radius-base, 8px);
+  box-sizing: border-box;
+  /* Custom scrollbar styles */
+}
+.x-virtual-scroll-container::-webkit-scrollbar {
+  width: 8px;
+}
+.x-virtual-scroll-container::-webkit-scrollbar-track {
+  background: transparent;
+}
+.x-virtual-scroll-container::-webkit-scrollbar-thumb {
+  background: rgba(0, 0, 0, 0.2);
+  border-radius: 4px;
+}
+.x-virtual-scroll-container::-webkit-scrollbar-thumb:hover {
+  background: rgba(0, 0, 0, 0.3);
+}
+.x-virtual-scroll-container {
+  /* Firefox scrollbar */
+  scrollbar-width: thin;
+  scrollbar-color: rgba(0, 0, 0, 0.2) transparent;
+}
+
+.x-virtual-scroll-spacer {
+  width: 100%;
+}
+
+.x-virtual-scroll-items {
+  will-change: transform;
+}
+
+.x-virtual-scroll-item {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  padding: var(--x-padding-xs, 8px) var(--x-padding-md, 12px);
+  transition: background-color 0.3s ease;
+  border-bottom: 1px solid var(--x-color-split, rgba(5, 5, 5, 0.06));
+}
+.x-virtual-scroll-item:last-child {
+  border-bottom: none;
+}
+.x-virtual-scroll-item.x-virtual-scroll-item-hoverable:hover {
+  background: var(--x-color-background-hover, #fafafa);
+}
+.x-virtual-scroll-item.selected {
+  background: var(--x-color-primary-contrast, #e6f4ff);
+}
+
+.x-virtual-scroll-item-default {
+  width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}

package/dist/collection/components/x-virtual-scroll/x-virtual-scroll.js

@@ -0,0 +1,478 @@
+import { h, Host } from "@stencil/core";
+/**
+ * Virtual scroll component for efficiently rendering large lists.
+ */
+export class XVirtualScroll {
+    /**
+     * Host element reference for measurements.
+     */
+    el;
+    /**
+     * Array of items to render.
+     * @example
+     * <x-virtual-scroll items={[{ name: 'A' }]}></x-virtual-scroll>
+     */
+    items = [];
+    /**
+     * Height of each item in pixels.
+     * @example
+     * <x-virtual-scroll itemHeight={48}></x-virtual-scroll>
+     */
+    itemHeight = 40;
+    /**
+     * Container height in pixels.
+     * @example
+     * <x-virtual-scroll height={300}></x-virtual-scroll>
+     */
+    height = 300;
+    /**
+     * Number of items to render outside viewport (buffer).
+     * @example
+     * <x-virtual-scroll overscan={8}></x-virtual-scroll>
+     */
+    overscan = 5;
+    /**
+     * Width of the container.
+     * @example
+     * <x-virtual-scroll width="100%"></x-virtual-scroll>
+     */
+    width = '100%';
+    /**
+     * Custom CSS class for items.
+     * @example
+     * <x-virtual-scroll itemClass="my-item"></x-virtual-scroll>
+     */
+    itemClass = '';
+    /**
+     * Enable hover effect on items.
+     * @example
+     * <x-virtual-scroll hoverable={false}></x-virtual-scroll>
+     */
+    hoverable = true;
+    /**
+     * Current scroll offset in pixels.
+     */
+    scrollTop = 0;
+    /**
+     * Visible item range derived from scroll position.
+     */
+    visibleRange = { start: 0, end: 0 };
+    /**
+     * Scroll container reference.
+     */
+    scrollContainerRef;
+    /**
+     * Initialize visible range before render.
+     * @returns void
+     * @example
+     * <x-virtual-scroll></x-virtual-scroll>
+     */
+    componentWillLoad() {
+        this.updateVisibleRange();
+    }
+    updateVisibleRange() {
+        const { scrollTop, itemHeight, height, overscan, items } = this;
+        const totalItems = items.length;
+        // Calculate which items should be visible
+        const startIndex = Math.max(0, Math.floor(scrollTop / itemHeight) - overscan);
+        const endIndex = Math.min(totalItems - 1, Math.ceil((scrollTop + height) / itemHeight) + overscan);
+        this.visibleRange = {
+            start: startIndex,
+            end: endIndex,
+        };
+    }
+    /**
+     * Handle scroll event and update scrollTop state.
+     * @param event - Scroll event from container.
+     * @returns void
+     * @example
+     * <x-virtual-scroll></x-virtual-scroll>
+     */
+    handleScroll = (event) => {
+        const target = event.target;
+        this.scrollTop = target.scrollTop;
+    };
+    /**
+     * Scroll to specific index.
+     * @param index - Item index to scroll to.
+     * @param behavior - Scroll behavior.
+     * @returns Promise<void>
+     * @example
+     * await el.scrollToIndex(10, 'smooth')
+     */
+    async scrollToIndex(index, behavior = 'smooth') {
+        if (this.scrollContainerRef && index >= 0 && index < this.items.length) {
+            const scrollTop = index * this.itemHeight;
+            this.scrollContainerRef.scrollTo({
+                top: scrollTop,
+                behavior,
+            });
+        }
+    }
+    /**
+     * Get current scroll position.
+     * @returns Promise<number>
+     * @example
+     * const top = await el.getScrollTop()
+     */
+    async getScrollTop() {
+        return this.scrollTop;
+    }
+    /**
+     * Get visible range.
+     * @returns Promise<{ start: number; end: number }>
+     * @example
+     * const range = await el.getVisibleRange()
+     */
+    async getVisibleRange() {
+        return this.visibleRange;
+    }
+    /**
+     * Render the virtualized list with a spacer and visible window.
+     *
+     * Flow:
+     * 1. Calculates `totalHeight` of the list (items * itemHeight) to set the scrollable area.
+     * 2. Calculates `offsetY` (start index * itemHeight) to position the visible slice correctly.
+     * 3. Slices the `items` array to get only the `visibleItems` based on `visibleRange`.
+     * 4. Renders:
+     *    - Host element with specified width.
+     *    - Container div with `overflow: auto` and explicit height.
+     *    - Spacer div with `totalHeight` to force the scrollbar.
+     *    - Items container div positioned absolutely with `translateY(offsetY)` to simulate position.
+     *    - Map of `visibleItems` to render content (using slot or default text).
+     *
+     * @returns JSX.Element
+     * @example
+     * <x-virtual-scroll items={[1,2,3]}></x-virtual-scroll>
+     */
+    render() {
+        const { items, itemHeight, height, width, visibleRange, itemClass, hoverable } = this;
+        const totalHeight = items.length * itemHeight;
+        const offsetY = visibleRange.start * itemHeight;
+        // Get visible items
+        const visibleItems = items.slice(visibleRange.start, visibleRange.end + 1);
+        return (h(Host, { key: 'd717a359fa4fa3037a75f1363aacbb4dcea2ccaa', class: "x-virtual-scroll-host", style: {
+                width: width,
+            } }, h("div", { key: 'ff88b01940db972a4685e7ac349a61ba338bc860', class: "x-virtual-scroll-container", style: {
+                height: `${height}px`,
+                overflow: 'auto',
+                position: 'relative',
+            }, onScroll: this.handleScroll, ref: (el) => (this.scrollContainerRef = el) }, h("div", { key: '7d32d8c277a41209eadf6ae8d260396972c84a6f', class: "x-virtual-scroll-spacer", style: {
+                height: `${totalHeight}px`,
+                position: 'relative',
+            } }, h("div", { key: 'a582f1e5d2b6da550ab4c4af630dfdff8b1c6a5d', class: "x-virtual-scroll-items", style: {
+                transform: `translateY(${offsetY}px)`,
+                position: 'absolute',
+                top: '0',
+                left: '0',
+                right: '0',
+            } }, visibleItems.map((item, index) => {
+            const actualIndex = visibleRange.start + index;
+            return (h("div", { class: {
+                    'x-virtual-scroll-item': true,
+                    'x-virtual-scroll-item-hoverable': hoverable,
+                    [itemClass]: !!itemClass,
+                }, style: {
+                    height: `${itemHeight}px`,
+                    overflow: 'hidden',
+                }, key: actualIndex, "data-index": actualIndex }, h("slot", { name: `item-${actualIndex}` }, h("div", { class: "x-virtual-scroll-item-default" }, typeof item === 'string' ? item : JSON.stringify(item)))));
+        }))))));
+    }
+    static get is() { return "x-virtual-scroll"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["x-virtual-scroll.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["x-virtual-scroll.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "items": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "VirtualScrollItem[]",
+                    "resolved": "VirtualScrollItem[]",
+                    "references": {
+                        "VirtualScrollItem": {
+                            "location": "local",
+                            "path": "E:/projects/fintvn/labs/packages/core/src/components/x-virtual-scroll/x-virtual-scroll.tsx",
+                            "id": "src/components/x-virtual-scroll/x-virtual-scroll.tsx::VirtualScrollItem"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-virtual-scroll items={[{ name: 'A' }]}></x-virtual-scroll>"
+                        }],
+                    "text": "Array of items to render."
+                },
+                "getter": false,
+                "setter": false,
+                "defaultValue": "[]"
+            },
+            "itemHeight": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-virtual-scroll itemHeight={48}></x-virtual-scroll>"
+                        }],
+                    "text": "Height of each item in pixels."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "item-height",
+                "defaultValue": "40"
+            },
+            "height": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-virtual-scroll height={300}></x-virtual-scroll>"
+                        }],
+                    "text": "Container height in pixels."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "height",
+                "defaultValue": "300"
+            },
+            "overscan": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-virtual-scroll overscan={8}></x-virtual-scroll>"
+                        }],
+                    "text": "Number of items to render outside viewport (buffer)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "overscan",
+                "defaultValue": "5"
+            },
+            "width": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-virtual-scroll width=\"100%\"></x-virtual-scroll>"
+                        }],
+                    "text": "Width of the container."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "width",
+                "defaultValue": "'100%'"
+            },
+            "itemClass": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-virtual-scroll itemClass=\"my-item\"></x-virtual-scroll>"
+                        }],
+                    "text": "Custom CSS class for items."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "item-class",
+                "defaultValue": "''"
+            },
+            "hoverable": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-virtual-scroll hoverable={false}></x-virtual-scroll>"
+                        }],
+                    "text": "Enable hover effect on items."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "hoverable",
+                "defaultValue": "true"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "scrollTop": {},
+            "visibleRange": {}
+        };
+    }
+    static get methods() {
+        return {
+            "scrollToIndex": {
+                "complexType": {
+                    "signature": "(index: number, behavior?: ScrollBehavior) => Promise<void>",
+                    "parameters": [{
+                            "name": "index",
+                            "type": "number",
+                            "docs": "- Item index to scroll to."
+                        }, {
+                            "name": "behavior",
+                            "type": "\"auto\" | \"instant\" | \"smooth\"",
+                            "docs": "- Scroll behavior."
+                        }],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        },
+                        "ScrollBehavior": {
+                            "location": "global",
+                            "id": "global::ScrollBehavior"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Scroll to specific index.",
+                    "tags": [{
+                            "name": "param",
+                            "text": "index - Item index to scroll to."
+                        }, {
+                            "name": "param",
+                            "text": "behavior - Scroll behavior."
+                        }, {
+                            "name": "returns",
+                            "text": "Promise<void>"
+                        }, {
+                            "name": "example",
+                            "text": "await el.scrollToIndex(10, 'smooth')"
+                        }]
+                }
+            },
+            "getScrollTop": {
+                "complexType": {
+                    "signature": "() => Promise<number>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<number>"
+                },
+                "docs": {
+                    "text": "Get current scroll position.",
+                    "tags": [{
+                            "name": "returns",
+                            "text": "Promise<number>"
+                        }, {
+                            "name": "example",
+                            "text": "const top = await el.getScrollTop()"
+                        }]
+                }
+            },
+            "getVisibleRange": {
+                "complexType": {
+                    "signature": "() => Promise<{ start: number; end: number; }>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<{ start: number; end: number; }>"
+                },
+                "docs": {
+                    "text": "Get visible range.",
+                    "tags": [{
+                            "name": "returns",
+                            "text": "Promise<{ start: number; end: number }>"
+                        }, {
+                            "name": "example",
+                            "text": "const range = await el.getVisibleRange()"
+                        }]
+                }
+            }
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "scrollTop",
+                "methodName": "updateVisibleRange"
+            }, {
+                "propName": "items",
+                "methodName": "updateVisibleRange"
+            }, {
+                "propName": "itemHeight",
+                "methodName": "updateVisibleRange"
+            }, {
+                "propName": "height",
+                "methodName": "updateVisibleRange"
+            }, {
+                "propName": "overscan",
+                "methodName": "updateVisibleRange"
+            }];
+    }
+}