wabtec-internal-volt-basic-components 1.2.0 → 1.4.0

package/dist/types/components/slider-range-continuous/vds-basic-slider-range-continuous.d.ts

@@ -1,203 +1,461 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+import { Marks } from '../../utils/slider.utils';
+/**
+ * @component vds-basic-slider-range-continuous
+ * @description A continuous range slider component for selecting a numeric range with start and end values. Supports horizontal and vertical orientations, custom step increments, value labels, and custom theming. Ideal for filtering price ranges, time periods, and other numeric ranges.
+ *
+ * @example
+ * <!-- Basic range slider with default range 0-100 -->
+ * <vds-basic-slider-range-continuous
+ *   start-value="25"
+ *   end-value="75">
+ * </vds-basic-slider-range-continuous>
+ *
+ * @example
+ * <!-- Large range slider with custom range -->
+ * <vds-basic-slider-range-continuous
+ *   start-value="100"
+ *   end-value="400"
+ *   min-value="0"
+ *   max-value="500"
+ *   size="large">
+ * </vds-basic-slider-range-continuous>
+ *
+ * @example
+ * <!-- Range slider with step increment -->
+ * <vds-basic-slider-range-continuous
+ *   start-value="20"
+ *   end-value="80"
+ *   min-value="0"
+ *   max-value="100"
+ *   step="5">
+ * </vds-basic-slider-range-continuous>
+ *
+ * @example
+ * <!-- Vertical range slider -->
+ * <vds-basic-slider-range-continuous
+ *   start-value="30"
+ *   end-value="70"
+ *   orientation="vertical"
+ *   style="height: 300px;">
+ * </vds-basic-slider-range-continuous>
+ *
+ * @example
+ * <!-- Range slider without value labels -->
+ * <vds-basic-slider-range-continuous
+ *   start-value="40"
+ *   end-value="60"
+ *   display-label="off">
+ * </vds-basic-slider-range-continuous>
+ *
+ * @example
+ * <!-- Range slider with auto labels (shows on hover) -->
+ * <vds-basic-slider-range-continuous
+ *   start-value="30"
+ *   end-value="70"
+ *   display-label="auto">
+ * </vds-basic-slider-range-continuous>
+ *
+ * @example
+ * <!-- Range slider without limit labels -->
+ * <vds-basic-slider-range-continuous
+ *   start-value="20"
+ *   end-value="80"
+ *   display-limits="false">
+ * </vds-basic-slider-range-continuous>
+ *
+ * @example
+ * <!-- Disabled range slider -->
+ * <vds-basic-slider-range-continuous
+ *   start-value="25"
+ *   end-value="75"
+ *   disabled="true">
+ * </vds-basic-slider-range-continuous>
+ *
+ * @example
+ * <!-- Range slider with custom colors -->
+ * <vds-basic-slider-range-continuous
+ *   start-value="30"
+ *   end-value="70"
+ *   colors='{"Track": "grey-200", "TrackFill": "primary-500", "Thumb": "primary-700"}'>
+ * </vds-basic-slider-range-continuous>
+ *
+ * @example
+ * <!-- Price range filter -->
+ * <div>
+ *   <label>Price Range: <span id="price-min">$25</span> - <span id="price-max">$75</span></label>
+ *   <vds-basic-slider-range-continuous
+ *     id="price-range"
+ *     start-value="25"
+ *     end-value="75"
+ *     min-value="0"
+ *     max-value="100"
+ *     step="5"
+ *     set-aria-label="Price range filter">
+ *   </vds-basic-slider-range-continuous>
+ * </div>
+ *
+ * @example
+ * <!-- Time range selector (hours) -->
+ * <div style="margin: 2rem;">
+ *   <label>Select Time Range</label>
+ *   <vds-basic-slider-range-continuous
+ *     start-value="9"
+ *     end-value="17"
+ *     min-value="0"
+ *     max-value="24"
+ *     step="1"
+ *     set-aria-label="Time range selector">
+ *   </vds-basic-slider-range-continuous>
+ *   <div style="display: flex; justify-content: space-between; margin-top: 0.5rem;">
+ *     <span>00:00</span>
+ *     <span>24:00</span>
+ *   </div>
+ * </div>
+ *
+ * @example
+ * <!-- Range slider with event handling -->
+ * <div>
+ *   <label>Select Range: <span id="range-display">25 - 75</span></label>
+ *   <vds-basic-slider-range-continuous
+ *     id="event-range"
+ *     start-value="25"
+ *     end-value="75"
+ *     min-value="0"
+ *     max-value="100">
+ *   </vds-basic-slider-range-continuous>
+ * </div>
+ * <script>
+ *   const slider = document.getElementById('event-range');
+ *   const display = document.getElementById('range-display');
+ *   slider.addEventListener('changeRangeValue', (e) => {
+ *     display.textContent = `${e.detail.startValue} - ${e.detail.endValue}`;
+ *   });
+ * </script>
+ */
 export declare class VdsBasicSliderRangeContinuous {
-    /** Sets the start value of the slider.*/
+    /**
+     * Sets the start value of the slider
+     * @type {number}
+     */
     startValue: number;
-    /** Sets the start value of the slider.*/
+    /**
+     * Sets the end value of the slider
+     * @type {number}
+     */
     endValue: number;
-    /** Sets the size of the slider. */
+    /**
+     * Sets the size of the slider
+     * @type {"medium" | "large"}
+     * @default "medium"
+     */
     size: "medium" | "large";
-    /** Sets the slider’s orientation. */
+    /**
+     * Sets the slider's orientation
+     * @type {"horizontal" | "vertical"}
+     * @default "horizontal"
+     */
     orientation: "horizontal" | "vertical";
-    /** Sets the slider on disabled state. */
+    /**
+     * Sets the slider on disabled state
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
-    /** Sets the min value of the slider (Min value should always be lower than the max value). */
+    /**
+     * Sets the min value of the slider (Min value should always be lower than the max value)
+     * @type {number}
+     * @default 0
+     */
     minValue: number;
-    /** Sets the max value of the slider..*/
+    /**
+     * Sets the max value of the slider
+     * @type {number}
+     * @default 100
+     */
     maxValue: number;
-    /** Sets the amount of advance of the slider. */
+    /**
+     * Sets the amount of advance of the slider
+     * @type {number}
+     */
     step: number;
-    /** Sets the aria label in slider */
+    /**
+     * Sets the aria label in slider
+     * @type {string}
+     */
     setAriaLabel: string;
-    /** Toggles the value over the thumb in the slider
-    * on - Always shows value over the thumb.
-    * off - Do not show the value over the thumb.
-    * auto - Shows value over the thumb when mouse hover.
-    */
+    /**
+     * Toggles the value over the thumb in the slider
+     * - on: Always shows value over the thumb
+     * - off: Do not show the value over the thumb
+     * - auto: Shows value over the thumb when mouse hover
+     * @type {"on" | "off" | "auto"}
+     * @default "on"
+     */
     displayLabel: "on" | "off" | "auto";
-    /** Toggles the limit value (min and max) of the slider .*/
+    /**
+     * Toggles the limit value (min and max) of the slider
+     * @type {boolean}
+     * @default true
+     */
     displayLimits: boolean;
-    /** Sets colors of the slider.
-     * Track - ThemeColors
-     * TrackFill - ThemeColors
-     * Thumb - ThemeColors
-     * Background - ThemeColors - When specified, trackfill and track won't work. It will only be one background display.
+    /**
+     * Sets colors of the slider
+     * - Track: ThemeColors
+     * - TrackFill: ThemeColors
+     * - Thumb: ThemeColors
+     * - Background: ThemeColors - When specified, trackfill and track won't work. It will only be one background display
+     * @type {{ [key: string]: string } | string}
      */
     colors: {
         [key: string]: string;
     } | string;
-    /** Sets the thumb icon */
+    /**
+     * Sets the thumb icon
+     * @type {string}
+     * @default "thumb"
+     */
     icon: string;
-    /**  Emits updated input value */
+    /**
+     * Show / Hide marks in the slider track
+     * @type {boolean}
+     * @default false
+     */
+    showMarks: boolean;
+    /**
+     * Marks definition for discrete slider mode
+     * @type {Marks[]}
+     */
+    marks: Marks[];
+    /**
+     * Emits updated range values when start or end value changes
+     * @event changeRangeValue
+     * @type {EventEmitter<{ startValue: number; endValue: number }>}
+     */
     changeRangeValue: EventEmitter<{
         startValue: number;
         endValue: number;
     }>;
     host: HTMLElement;
     displayLabelShowValue: boolean;
+    /**
+     * Reference to the start range input element
+     * @private
+     */
     startInputRangeEl: HTMLInputElement;
+    /**
+     * Reference to the end range input element
+     * @private
+     */
     endInputRangeEl: HTMLInputElement;
+    /**
+     * String representation of the start value
+     * @private
+     */
     startShownValue: string;
+    /**
+     * String representation of the end value
+     * @private
+     */
     endShownValue: string;
+    /**
+     * CSS position of the start thumb
+     * @private
+     */
     startThumbPosition: string;
+    /**
+     * CSS position of the end thumb
+     * @private
+     */
     endThumbPosition: string;
+    /**
+     * Reference to the track range fill container element
+     * @private
+     */
     trackRangeFillContainerEl: HTMLDivElement;
+    /**
+     * Reference to the track content container element
+     * @private
+     */
     trackContentContainerEl: HTMLDivElement;
+    /**
+     * Tracks the event type that triggered display label for start slider
+     * @private
+     */
     displayLabelStartEventTriggerIn: "mouseover" | "focus";
+    /**
+     * Tracks the event type that triggered display label for end slider
+     * @private
+     */
     displayLabelEndEventTriggerIn: "mouseover" | "focus";
+    /**
+     * Flag indicating if slider has focus
+     * @private
+     */
     hasFocus: boolean;
+    /**
+     * Component lifecycle hook - logs warnings and sets default values
+     * @private
+     */
     componentWillRender(): void;
-    componentDidRender(): void;
+    /**
+     * Component lifecycle hook - sets input values and forces update
+     * @private
+     */
     componentDidLoad(): void;
     /**
-     * Sets the slider startValue and endValue to the specified value.
-     *
-     * @param { startValue: number; endValue: number } values - The new values for the slider.
-     * @returns {Promise<void>} A promise that resolves when the value is set.
+     * Sets the slider startValue and endValue to the specified values
+     * @method
+     * @public
+     * @param {{ startValue: number; endValue: number }} values - The new values for the slider
+     * @returns {Promise<void>} A promise that resolves when the values are set
      */
     setValues({ startValue, endValue }: {
         startValue: number;
         endValue: number;
     }): Promise<void>;
     /**
-     * Gets the slider startValue and endValue.
-     *
-     * @returns {Promise<{ startValue: number; endValue: number }>} A promise that resolves the values.
+     * Gets the slider startValue and endValue
+     * @method
+     * @public
+     * @returns {Promise<{ startValue: number; endValue: number }>} A promise that resolves with the current values
      */
     getValues(): Promise<{
         startValue: number;
         endValue: number;
     }>;
     /**
-     * Clears the slider range values by setting it to the minimum and maximun value respectively.
-     *
-     * @returns {Promise<void>} A promise that resolves when the value is cleared.
+     * Clears the slider range values by setting them to the minimum and maximum value respectively
+     * @method
+     * @public
+     * @returns {Promise<void>} A promise that resolves when the values are cleared
      */
     clear(): Promise<void>;
     /**
-     * Focus the slider range by focusing start slider.
-     *
-     * @returns {Promise<void>} A promise that resolves when the first slider is focused.
+     * Focus the slider range by focusing start slider
+     * @method
+     * @public
+     * @returns {Promise<void>} A promise that resolves when the first slider is focused
      */
     setFocus(): Promise<void>;
     /**
-     * Sets slider startThumbPosition, startShownValue.
+     * Sets slider startThumbPosition and startShownValue.
      * Calculates the start thumb position based on the value.
      * Emits changeRangeValue event
-     *
-     * @returns {void}
+     * @private
      */
     setInputStartValue(): void;
     /**
-     * Sets slider endThumbPosition, endShownValue.
+     * Sets slider endThumbPosition and endShownValue.
      * Calculates the end thumb position based on the value.
      * Emits changeRangeValue event
-     *
-     * @returns {void}
+     * @private
      */
     setInputEndValue(): void;
     /**
-     * Updates the thumb position and forces a component update on window resize.
-     *
-     * @ListensTo("resize", {target: "window"})
+     * Updates the thumb position and forces a component update on window resize
+     * @private
      */
     updateThumbAndTrackPosition(): void;
     /**
-     * Focus the first slider when displayLabel is set to auto.
-     *
-     * @ListensTo("focus")
+     * Focus the first slider when displayLabel is set to auto
+     * @private
      */
     setFocusOnDisplayLabelAuto(): void;
     /**
      * Sets the initial value of the slider to the minimum and maximum value when start and end value are not provided.
-     * When values are provided, shownValues get set.
-     *
+     * When values are provided, values get normalized and shownValues get set.
      * @private
      */
     private setDefaultValues;
     /**
-     * Sets the values of the slider to the minimum and maximum value when start and end value are out of bound.
-     *
-     * @private
-     */
-    private setOutboundValues;
-    /**
-     * Calculates the CSS left position of the slider thumb based on the current value.
-     *
+     * Calculates the CSS left position of the slider thumb based on the current value
      * @private
-     * @params value - number
-     * @params inputRangeEl - HTMLInputElement
-     * @returns {string} The calculated left position of the slider thumb as a CSS pixel value.
+     * @param {number} value - The value to calculate position for
+     * @returns {string} The calculated left position of the slider thumb as a CSS percentage value
      */
     private getValuePosition;
     /**
-     * Sets the start/end value of the slider range to the specified in the event.
-     *
+     * Sets the start/end value of the slider range to the specified in the event
      * @private
-     * @param {InputEvent} evt - The event emitted by the input.
-     * @param {SliderRangeValueType} rangeType - start | end slider.
-     * @returns {void}
+     * @param {InputEvent} evt - The event emitted by the input
+     * @param {SliderRangeValueType} rangeType - start | end slider
      */
     private handleInputRangeChange;
     /**
      * Handles mouseover or focus events on the slider.
-     * Sets the `displayLabelShowValue` flag to `true` to indicate that the display label should show the value.
-     *
+     * Sets the displayLabelShowValue flag to true to indicate that the display label should show the value.
      * @private
-     * @param {SliderRangeValueType} rangeType - The type of range (either "start" or "end").
-     * @param {"mouseover" | "focus"} eventTrigger - The type of event that triggered this function.
-     * @returns {void}
+     * @param {SliderRangeValueType} rangeType - The type of range (either "start" or "end")
+     * @param {"mouseover" | "focus"} eventTrigger - The type of event that triggered this function
      */
     private handleInputMouseoverOrFocus;
     /**
      * Handles mouseleave or blur events on the slider.
-     * Sets the `displayLabelShowValue` flag to `false` to hide the value in the display label.
-     *
+     * Sets the displayLabelShowValue flag to false to hide the value in the display label.
      * @private
-     * @param {SliderRangeValueType} rangeType - The type of range (either "start" or "end").
-     * @returns {void}
+     * @param {SliderRangeValueType} rangeType - The type of range (either "start" or "end")
      */
     private handleInputMouseleaveOrBlur;
     /**
      * Handles click events on the slider track.
      * Calculates the corresponding value based on the click position and updates the slider's start or end value accordingly.
-     *
      * @private
-     * @param {MouseEvent} evt - The mouse event object.
-     * @returns {void}
+     * @param {MouseEvent} evt - The mouse event object
      */
     private handleTrackClick;
     /**
-     * Determines whether the value should be displayed in the label based on the current displayLabel setting.
-     *
+     * Determines whether the value should be displayed in the label based on the current displayLabel setting
      * @private
-     * @returns {boolean} - True if the value should be displayed, false otherwise.
+     * @returns {boolean} True if the value should be displayed, false otherwise
      */
     private getShowValue;
+    /**
+     * Gets the marks to display on the slider track
+     * @private
+     * @returns {Marks[]} Array of mark definitions
+     */
+    private getMarks;
+    /**
+     * Renders the marks on the slider track
+     * @private
+     * @param {Marks[]} marks - Array of mark definitions
+     * @returns {HTMLStencilElement | null} Marks element or null if no marks
+     */
+    private renderMarks;
     /**
      * Sets the custom colors for the slider based on the colors property.
      * This colors have to be css variables by preferences that work in both dark and light mode.
-     *
-     * Track - ThemeColors
-     * TrackFill - ThemeColors
-     * Thumb - ThemeColors
-     * Background - ThemeColors - When specified, trackfill and track won't work. It will only be one background display.
-     *
+     * - Track: ThemeColors
+     * - TrackFill: ThemeColors
+     * - Thumb: ThemeColors
+     * - Background: ThemeColors - When specified, trackfill and track won't work. It will only be one background display
      * @private
-     * @returns { [key: string]: string }
+     * @returns {{ [key: string]: string }} Object with CSS custom properties
      */
     private setColors;
+    /**
+     * Renders the value tooltip for start or end thumb
+     * @private
+     * @param {SliderRangeValueType} rangeType - The type of range (either "start" or "end")
+     * @returns {HTMLStencilElement} Value display element
+     */
     private renderShownValue;
+    /**
+     * Renders the min and max value references
+     * @private
+     * @returns {HTMLStencilElement} Value references element
+     */
     private renderValueReferences;
+    /**
+     * Renders the main range slider inputs and track elements
+     * @private
+     * @returns {HTMLStencilElement} Range slider element
+     */
     private renderSliders;
+    /**
+     * Render the range slider component
+     * @returns {HTMLStencilElement} The rendered range slider element
+     */
     render(): any;
 }

package/dist/types/components/slider-range-continuous/vds-basic-slider-range-continuous.stories.d.ts

@@ -40,3 +40,4 @@ declare const _default: {
 };
 export default _default;
 export declare const BasicUsage: any;
+export declare const MarksUsage: any;