@xlabs-store/core 0.0.1

package/dist/collection/components/x-slider/x-slider.js

@@ -0,0 +1,785 @@
+import { Host, h, } from "@stencil/core";
+/**
+ * Slider component supporting single and range values with keyboard and mouse input.
+ */
+export class XSlider {
+    /**
+     * Host element reference for layout.
+     */
+    el;
+    /* ---------------- PROPS ---------------- */
+    /**
+     * Minimum slider value.
+     * @example
+     * <x-slider min={0}></x-slider>
+     */
+    min = 0;
+    /**
+     * Maximum slider value.
+     * @example
+     * <x-slider max={100}></x-slider>
+     */
+    max = 100;
+    /**
+     * Step size between values, or null to use marks.
+     * @example
+     * <x-slider step={5}></x-slider>
+     */
+    step = 1;
+    /**
+     * Enable range mode with two thumbs.
+     * @example
+     * <x-slider range></x-slider>
+     */
+    range = false;
+    /**
+     * Render slider vertically.
+     * @example
+     * <x-slider vertical></x-slider>
+     */
+    vertical = false;
+    /**
+     * Disable interaction.
+     * @example
+     * <x-slider disabled></x-slider>
+     */
+    disabled = false;
+    /**
+     * Allow thumbs to cross in range mode.
+     * @example
+     * <x-slider range allowCross={false}></x-slider>
+     */
+    allowCross = true;
+    /**
+     * Push behavior or minimum distance between thumbs.
+     * @example
+     * <x-slider range pushable={10}></x-slider>
+     */
+    pushable = false;
+    /**
+     * Allow dragging the selected track in range mode.
+     * @example
+     * <x-slider range draggableTrack></x-slider>
+     */
+    draggableTrack = false;
+    /**
+     * Show tooltip values on handles.
+     * @example
+     * <x-slider tooltip={false}></x-slider>
+     */
+    tooltip = true;
+    /**
+     * Marks displayed on the rail.
+     * @example
+     * <x-slider marks={{ 0: '0', 100: '100' }}></x-slider>
+     */
+    marks = {};
+    /**
+     * Controlled value for slider.
+     * @example
+     * <x-slider value={50}></x-slider>
+     */
+    value;
+    /**
+     * Default value when uncontrolled.
+     * @example
+     * <x-slider defaultValue={20}></x-slider>
+     */
+    defaultValue = 0;
+    /* ---------------- STATE ---------------- */
+    /**
+     * Active thumb index while dragging.
+     */
+    activeThumb = null;
+    /**
+     * Whether a drag interaction is active.
+     */
+    isDragging = false;
+    /* ---------------- EVENTS ---------------- */
+    /**
+     * Emits on value change.
+     * @example
+     * <x-slider onXChange={(ev) => console.log(ev.detail)}></x-slider>
+     */
+    xChange;
+    /**
+     * Emits after drag interaction ends.
+     * @example
+     * <x-slider onXAfterChange={(ev) => console.log(ev.detail)}></x-slider>
+     */
+    xAfterChange;
+    /**
+     * Rail element reference for position calculations.
+     */
+    rail;
+    /* ---------------- LIFECYCLE ---------------- */
+    componentWillLoad() {
+        if (this.value === undefined) {
+            this.value = this.range
+                ? [this.min, this.max]
+                : this.defaultValue;
+        }
+    }
+    onValueChange() {
+        this.xChange.emit(this.value);
+    }
+    /* ---------------- UTIL ---------------- */
+    /**
+     * Clamp value within min and max.
+     * @param v - Input value.
+     * @returns number
+     * @example
+     * this.clamp(120)
+     */
+    clamp(v) {
+        return Math.min(this.max, Math.max(this.min, v));
+    }
+    /**
+     * Build list of steps based on step or marks.
+     * @returns number[]
+     * @example
+     * this.getSteps()
+     */
+    getSteps() {
+        if (this.step === null) {
+            return Object.keys(this.marks).map(Number);
+        }
+        const arr = [];
+        for (let v = this.min; v <= this.max; v += this.step) {
+            arr.push(v);
+        }
+        return arr;
+    }
+    /**
+     * Snap value to nearest step or mark.
+     * @param v - Raw value.
+     * @returns number
+     * @example
+     * this.snap(42)
+     */
+    snap(v) {
+        if (this.step === null) {
+            const steps = this.getSteps();
+            return steps.reduce((prev, curr) => Math.abs(curr - v) < Math.abs(prev - v) ? curr : prev);
+        }
+        return Math.round(v / this.step) * this.step;
+    }
+    /**
+     * Convert value to percentage along the rail.
+     * @param v - Value to convert.
+     * @returns number
+     * @example
+     * this.percent(50)
+     */
+    percent(v) {
+        return ((v - this.min) / (this.max - this.min)) * 100;
+    }
+    /**
+     * Calculates the slider value based on a mouse event.
+     *
+     * Flow:
+     * 1. Gets the bounding rectangle of the rail.
+     * 2. Calculates the ratio of the mouse position relative to the rail's width (or height if vertical).
+     * 3. Maps the ratio to the [min, max] range.
+     * 4. Clamps the value to ensure it stays within bounds.
+     * 5. Snaps the value to the nearest step.
+     *
+     * @param e - The mouse event.
+     * @returns number - The calculated value.
+     */
+    getValueFromEvent(e) {
+        const rect = this.rail.getBoundingClientRect();
+        const ratio = this.vertical
+            ? (rect.bottom - e.clientY) / rect.height
+            : (e.clientX - rect.left) / rect.width;
+        const v = this.min + this.clamp(ratio) * (this.max - this.min);
+        return this.snap(this.clamp(v));
+    }
+    /* ---------------- PUSH LOGIC ---------------- */
+    /**
+     * Enforces the `pushable` constraint between range thumbs.
+     * Ensures thumbs maintain a minimum distance from each other.
+     *
+     * @param values - Current range values [v1, v2].
+     * @param index - The index of the thumb actively being moved.
+     * @returns [number, number] - The adjusted values.
+     */
+    pushRange(values, index) {
+        if (!this.pushable)
+            return values;
+        const distance = typeof this.pushable === 'number' ? this.pushable : 1;
+        if (index === 0 && values[1] - values[0] < distance) {
+            values[1] = values[0] + distance;
+        }
+        if (index === 1 && values[1] - values[0] < distance) {
+            values[0] = values[1] - distance;
+        }
+        return values;
+    }
+    /* ---------------- MOUSE ---------------- */
+    /**
+     * Handles the mouse down event to initiate dragging.
+     *
+     * Flow:
+     * 1. Checks if disabled.
+     * 2. Sets `isDragging` flag.
+     * 3. Determines which thumb is active (closest to click if not specified).
+     * 4. Updates the value immediately.
+     * 5. Attaches global mouse listeners for drag and release.
+     *
+     * @param e - The mouse event.
+     * @param index - Optional index of the handle being clicked.
+     */
+    onMouseDown = (e, index) => {
+        if (this.disabled)
+            return;
+        this.isDragging = true;
+        if (this.range) {
+            this.activeThumb =
+                index ??
+                    this.getClosestThumb(this.getValueFromEvent(e));
+        }
+        this.updateValue(e);
+        document.addEventListener('mousemove', this.onMouseMove);
+        document.addEventListener('mouseup', this.onMouseUp);
+    };
+    /**
+     * Handles mouse move during drag.
+     * Updates the value if dragging is active.
+     */
+    onMouseMove = (e) => {
+        if (!this.isDragging)
+            return;
+        this.updateValue(e);
+    };
+    /**
+     * Handles mouse up to end drag.
+     * Clears state, emits final change event, and removes listeners.
+     */
+    onMouseUp = () => {
+        this.isDragging = false;
+        this.activeThumb = null;
+        this.xAfterChange.emit(this.value);
+        document.removeEventListener('mousemove', this.onMouseMove);
+        document.removeEventListener('mouseup', this.onMouseUp);
+    };
+    /**
+     * Updates the slider value logic during interaction.
+     *
+     * Flow:
+     * 1. Calculates new value from event.
+     * 2. If single mode, updates value directly.
+     * 3. If range mode:
+     *    - Handles track dragging (moving both thumbs).
+     *    - Handles individual thumb dragging.
+     *    - Enforces `allowCross` constraint (swapping thumbs if needed).
+     *    - Enforces `pushRange` constraint.
+     *
+     * @param e - The mouse event.
+     */
+    updateValue(e) {
+        const v = this.getValueFromEvent(e);
+        if (!this.range) {
+            this.value = v;
+            return;
+        }
+        let values = [...this.value];
+        if (this.draggableTrack && this.activeThumb === null) {
+            const diff = v - values[0];
+            values = [values[0] + diff, values[1] + diff];
+        }
+        else {
+            values[this.activeThumb] = v;
+            if (!this.allowCross) {
+                if (this.activeThumb === 0)
+                    values[0] = Math.min(values[0], values[1]);
+                else
+                    values[1] = Math.max(values[1], values[0]);
+            }
+            values = this.pushRange(values, this.activeThumb);
+        }
+        this.value = values;
+    }
+    /**
+     * Finds the index of the thumb closest to the given value.
+     * Used to determine which thumb to move when clicking on the rail.
+     *
+     * @param v - The target value.
+     * @returns number - 0 or 1.
+     */
+    getClosestThumb(v) {
+        const [v1, v2] = this.value;
+        return Math.abs(v - v1) < Math.abs(v - v2) ? 0 : 1;
+    }
+    /* ---------------- KEYBOARD ---------------- */
+    /**
+     * Handles keyboard navigation for fine-tuning values.
+     * Supports Arrow keys for stepping up/down.
+     *
+     * @param e - Keyboard event.
+     * @param index - Index of the handle focused.
+     */
+    onKeyDown = (e, index) => {
+        if (this.disabled)
+            return;
+        const delta = e.key === 'ArrowRight' || e.key === 'ArrowUp'
+            ? this.step ?? 1
+            : e.key === 'ArrowLeft' || e.key === 'ArrowDown'
+                ? -(this.step ?? 1)
+                : 0;
+        if (!delta)
+            return;
+        e.preventDefault();
+        if (!this.range) {
+            this.value = this.clamp(this.value + delta);
+        }
+        else {
+            const values = [...this.value];
+            values[index] = this.clamp(values[index] + delta);
+            this.value = values;
+        }
+    };
+    /* ---------------- RENDER ---------------- */
+    /**
+     * Renders the marks (ticks) along the slider rail.
+     *
+     * @returns JSX.Element[] - List of mark elements positioned by percentage.
+     */
+    renderMarks() {
+        return Object.entries(this.marks).map(([k, label]) => {
+            const percent = this.percent(Number(k));
+            return (h("div", { class: "x-slider-mark", style: {
+                    [this.vertical ? 'bottom' : 'left']: `${percent}%`,
+                } }, label));
+        });
+    }
+    /**
+     * Main render method for the Slider component.
+     *
+     * Structure:
+     * - Host element with classes for vertical/disabled state.
+     * - Rail: The background line.
+     * - Track: The active/colored segment indicating selected range.
+     * - Handles: Draggable knobs for interacting with values.
+     * - Marks: Optional labeled ticks.
+     *
+     * @returns JSX.Element
+     */
+    render() {
+        const values = this.range
+            ? this.value
+            : [this.value];
+        const p1 = this.percent(values[0]);
+        const p2 = this.range ? this.percent(values[1]) : p1;
+        return (h(Host, { key: '90fc23fbdcc78816be8c8d32d3e46e4687d3fad6', class: {
+                'x-slider': true,
+                'x-slider-vertical': this.vertical,
+                'x-slider-disabled': this.disabled,
+            } }, h("div", { key: '9ff4c3df41adfcd7cc3f7c65784fc569b6693ff3', class: "x-slider-rail", ref: el => (this.rail = el), onClick: e => this.onMouseDown(e) }), h("div", { key: '0c5f77c19a65e251e46d0393e626bfe96abd18c9', class: "x-slider-track", style: {
+                [this.vertical ? 'height' : 'width']: `${this.range ? p2 - p1 : p1}%`,
+                [this.vertical ? 'bottom' : 'left']: `${this.range ? p1 : 0}%`,
+            } }), values.map((v, i) => {
+            const percent = this.percent(v);
+            return (h("div", { class: "x-slider-handle", style: {
+                    [this.vertical ? 'bottom' : 'left']: `${percent}%`,
+                }, tabindex: 0, role: "slider", "aria-valuemin": this.min, "aria-valuemax": this.max, "aria-valuenow": v, onMouseDown: e => this.onMouseDown(e, i), onKeyDown: e => this.onKeyDown(e, i) }, this.tooltip && (h("div", { class: "x-slider-tooltip" }, v))));
+        }), h("div", { key: 'f3dd9f0c39947e115fd6160c1003cf48f93e97af', class: "x-slider-marks" }, this.renderMarks())));
+    }
+    static get is() { return "x-slider"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["x-slider.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["x-slider.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "min": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-slider min={0}></x-slider>"
+                        }],
+                    "text": "Minimum slider value."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "min",
+                "defaultValue": "0"
+            },
+            "max": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-slider max={100}></x-slider>"
+                        }],
+                    "text": "Maximum slider value."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "max",
+                "defaultValue": "100"
+            },
+            "step": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number | null",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-slider step={5}></x-slider>"
+                        }],
+                    "text": "Step size between values, or null to use marks."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "step",
+                "defaultValue": "1"
+            },
+            "range": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-slider range></x-slider>"
+                        }],
+                    "text": "Enable range mode with two thumbs."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "range",
+                "defaultValue": "false"
+            },
+            "vertical": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-slider vertical></x-slider>"
+                        }],
+                    "text": "Render slider vertically."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "vertical",
+                "defaultValue": "false"
+            },
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-slider disabled></x-slider>"
+                        }],
+                    "text": "Disable interaction."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "disabled",
+                "defaultValue": "false"
+            },
+            "allowCross": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-slider range allowCross={false}></x-slider>"
+                        }],
+                    "text": "Allow thumbs to cross in range mode."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "allow-cross",
+                "defaultValue": "true"
+            },
+            "pushable": {
+                "type": "any",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean | number",
+                    "resolved": "boolean | number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-slider range pushable={10}></x-slider>"
+                        }],
+                    "text": "Push behavior or minimum distance between thumbs."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "pushable",
+                "defaultValue": "false"
+            },
+            "draggableTrack": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-slider range draggableTrack></x-slider>"
+                        }],
+                    "text": "Allow dragging the selected track in range mode."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "draggable-track",
+                "defaultValue": "false"
+            },
+            "tooltip": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-slider tooltip={false}></x-slider>"
+                        }],
+                    "text": "Show tooltip values on handles."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "tooltip",
+                "defaultValue": "true"
+            },
+            "marks": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "Record<number, string>",
+                    "resolved": "number | string",
+                    "references": {
+                        "Record": {
+                            "location": "global",
+                            "id": "global::Record"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-slider marks={{ 0: '0', 100: '100' }}></x-slider>"
+                        }],
+                    "text": "Marks displayed on the rail."
+                },
+                "getter": false,
+                "setter": false,
+                "defaultValue": "{}"
+            },
+            "value": {
+                "type": "number",
+                "mutable": true,
+                "complexType": {
+                    "original": "SliderValue",
+                    "resolved": "[number, number] | number",
+                    "references": {
+                        "SliderValue": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/x-slider/types.ts::SliderValue",
+                            "referenceLocation": "SliderValue"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-slider value={50}></x-slider>"
+                        }],
+                    "text": "Controlled value for slider."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "value"
+            },
+            "defaultValue": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "SliderValue",
+                    "resolved": "[number, number] | number",
+                    "references": {
+                        "SliderValue": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/x-slider/types.ts::SliderValue",
+                            "referenceLocation": "SliderValue"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-slider defaultValue={20}></x-slider>"
+                        }],
+                    "text": "Default value when uncontrolled."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "default-value",
+                "defaultValue": "0"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "activeThumb": {},
+            "isDragging": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "xChange",
+                "name": "xChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-slider onXChange={(ev) => console.log(ev.detail)}></x-slider>"
+                        }],
+                    "text": "Emits on value change."
+                },
+                "complexType": {
+                    "original": "SliderValue",
+                    "resolved": "[number, number] | number",
+                    "references": {
+                        "SliderValue": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/x-slider/types.ts::SliderValue",
+                            "referenceLocation": "SliderValue"
+                        }
+                    }
+                }
+            }, {
+                "method": "xAfterChange",
+                "name": "xAfterChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "<x-slider onXAfterChange={(ev) => console.log(ev.detail)}></x-slider>"
+                        }],
+                    "text": "Emits after drag interaction ends."
+                },
+                "complexType": {
+                    "original": "SliderValue",
+                    "resolved": "[number, number] | number",
+                    "references": {
+                        "SliderValue": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/x-slider/types.ts::SliderValue",
+                            "referenceLocation": "SliderValue"
+                        }
+                    }
+                }
+            }];
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "value",
+                "methodName": "onValueChange"
+            }];
+    }
+}