@refinitiv-ui/elements 7.9.0 → 7.10.0

package/lib/slider/elements/slider.d.ts

@@ -0,0 +1,508 @@
+import { JSXInterface } from '../../jsx';
+import { CSSResultGroup, FormFieldElement, PropertyValues, TemplateResult } from '@refinitiv-ui/core';
+import '@refinitiv-ui/phrasebook/locale/en/slider.js';
+import { TranslatePromise } from '@refinitiv-ui/translate';
+import '../../number-field/index.js';
+/**
+ * Allows users to make selections from a range of values
+ *
+ * @attr {string} value - Value of slider. Not applicable in range mode.
+ * @prop {string} [value="0"] - Value of slider. Not applicable in range mode.
+ *
+ * @attr {boolean} readonly - Set readonly state
+ * @prop {boolean} [readonly=false] - Set readonly state
+ *
+ * @attr {boolean} disabled - Set disabled state
+ * @prop {boolean} [disabled=false] - Set disabled state
+ *
+ * @fires value-changed - Fired when the user commits a value change. The event is not triggered if `value` property is changed programmatically.
+ * @fires from-changed - Fired when the user changes from's value. The event is not triggered if `from` property is changed programmatically.
+ * @fires to-changed - Fired when the user changes to's value. The event is not triggered if `to` property is changed programmatically.
+ * @fires input - Fired with the value of the input in `e.detail.value` like another custom events when the user inputs a value by interacting with the slider or updating its input field.
+ * @fires from-input - Fired when the user inputs from's value by interacting with the slider or updating its input field.
+ * @fires to-input - Fired when the user inputs to's value by interacting with the slider or updating its input field.
+ */
+export declare class Slider extends FormFieldElement {
+    /**
+     * Element version number
+     * @returns version number
+     */
+    static get version(): string;
+    /**
+     * Define styles in a tagged template literal, using the css tag function.
+     * @returns CSS template
+     */
+    static get styles(): CSSResultGroup;
+    /**
+     * Whether if the thumb is being drag
+     */
+    private dragging;
+    private valuePrevious;
+    private fromPrevious;
+    private toPrevious;
+    private valuePreviousInput;
+    private fromPreviousInput;
+    private toPreviousInput;
+    /** Aria label for 'to' and 'from' value thumb, resolved based on locale. */
+    private toAriaLabel;
+    private fromAriaLabel;
+    /**
+     * Specified size of increment or decrement jump between value.
+     */
+    step: string;
+    /**
+     * Set minimum value of slider.
+     */
+    min: string;
+    /**
+     * Set maximum value of slider.
+     */
+    max: string;
+    /**
+     * Uses with `range`. Low value of slider in range mode.
+     */
+    from: string;
+    /**
+     * Uses with `range`. High value of slider in range mode
+     */
+    to: string;
+    /**
+     * Set slider appearances to show pin mode.
+     * @ignore
+     * NOTE: Pin isn't applicable in Halo. Hide this from document
+     */
+    pin: boolean;
+    /**
+     * Set slider to range mode. Instead of a single value, slider will provide `from` and `to`.
+     */
+    range: boolean;
+    /**
+     * Show steps marker on slider.
+     */
+    showSteps: boolean;
+    /**
+     * Show input number field.
+     */
+    showInputField: 'readonly' | '' | null;
+    /**
+     * Uses with `range`. Set minimum allowance value (distance) between `from` and `to`.
+     */
+    minRange: string;
+    /**
+     * Slider internal translation strings
+     */
+    protected labelTPromise: TranslatePromise;
+    /**
+     * Converts value from string to number for calculations
+     * @returns value of input as a number
+     */
+    private get valueNumber();
+    /**
+     * Converts min value from string to number for calculations
+     * @returns minimum value of slider as a number
+     */
+    private get minNumber();
+    /**
+     * Converts max value from string to number for calculations
+     * @returns maximum value of slider as a number
+     */
+    private get maxNumber();
+    /**
+     * Converts step value from string to number for calculations
+     * @returns step value of slider as a number
+     */
+    private get stepNumber();
+    /**
+     * Compute and normalise step value for calculations
+     * @returns step value that should be inside the min / max boundary
+     */
+    private get stepRange();
+    /**
+     * Converts from value from string to number for calculations
+     * @returns from value of slider as a number
+     */
+    private get fromNumber();
+    /**
+     * Converts to value from string to number for calculations
+     * @returns to value of slider as a number
+     */
+    private get toNumber();
+    /**
+     * Converts min-range from string to number for calculations
+     * @returns min-range of input as a number
+     */
+    private get minRangeNumber();
+    /**
+     * Number of decimal places used for displaying value
+     * Based on step or min decimal places
+     */
+    private get decimalPlace();
+    /**
+     * Return hide/show input field state
+     * @returns true if showInputField value is exist
+     */
+    private get isShowInputField();
+    /**
+     * Slider element reference
+     */
+    private sliderRef;
+    /**
+     * Slider's track reference
+     */
+    private trackRef;
+    /**
+     * From value thumb reference, rendered only in range mode
+     */
+    private fromThumbRef;
+    /**
+     * To value thumb reference, rendered only in range mode
+     */
+    private toThumbRef;
+    /**
+     * Value thumb reference
+     */
+    private valueThumbRef;
+    /**
+     * Number field for slider value
+     */
+    private valueInput;
+    /**
+     * Number field for from value in range mode
+     */
+    private fromInput;
+    /**
+     * Number field for to value in range mode
+     */
+    private toInput;
+    /**
+     * Current focused thumb
+     */
+    private activeThumb;
+    /**
+     * Thumb that may involves data changes
+     */
+    private changedThumb;
+    constructor();
+    /**
+     * On first updated lifecycle
+     * @param changedProperties changed properties
+     * @returns {void}
+     */
+    protected firstUpdated(changedProperties: PropertyValues): void;
+    /**
+     * Perform asynchronous update
+     * @returns promise
+     */
+    protected performUpdate(): Promise<void>;
+    /**
+     * Gets Slider Marker elements from the slot.
+     * @returns Array of Slider Marker elements.
+     */
+    private getMarkerElements;
+    /**
+     * Gets the active marker based on the provided marker value.
+     * @param value - The marker value.
+     * @returns The active marker element.
+     */
+    private getActiveMarker;
+    /**
+     * Finds the closest ancestor ef-slider-marker in the DOM tree.
+     * @param startingElement The HTML element to start searching from.
+     * @returns The found marker, or null if not found.
+     */
+    private findClosestMarker;
+    /**
+     * Handles the slot change event by updating the position of markers.
+     * @returns {void}
+     */
+    private onSlotChange;
+    /**
+     * @ignore
+     * On willUpdate lifecycle
+     * @param changedProperties changed properties
+     * @returns {void}
+     */
+    willUpdate(changedProperties: PropertyValues): void;
+    /**
+     * On updated lifecycle
+     * @param changedProperties changed properties
+     * @returns {void}
+     */
+    protected updated(changedProperties: PropertyValues): void;
+    /**
+     * Update the ARIA value text for a given thumb.
+     *
+     * @param thumbRef - The reference to the thumb element.
+     * @param markerValue - The value associated with the marker.
+     * @returns {void}
+     */
+    private updateAriaValueText;
+    /**
+     * Show Warning a warning message invalid property
+     * @param propName value for checking
+     * @returns {void}
+     */
+    private showWarningInvalidProperty;
+    /**
+     * Initialises slider value properties
+     * @returns {void}
+     */
+    private prepareValues;
+    /**
+     * Add event listeners to thumbs depending on mode
+     * @returns {void}
+     */
+    private prepareThumbs;
+    /**
+     * Add or remove event listener on slider track depending on slider disabled and readonly state
+     * @returns {void}
+     */
+    private prepareSliderTrack;
+    /**
+     * Get slider data name from keyboard event target
+     * @param target target element
+     * @returns Slider data name
+     */
+    private getThumbName;
+    /**
+     * Handles key down event on thumbs
+     * @param event Keyboard event
+     * @returns {void}
+     */
+    private onKeyDown;
+    /**
+     * Set thumb to minimum value possible
+     * @param data type of data to change
+     * @returns {void}
+     */
+    private onApplyMin;
+    /**
+     * Set thumb to maximum value possible
+     * @param data type of data to change
+     * @returns {void}
+     */
+    private onApplyMax;
+    /**
+     * Increase or decrease value depending on direction
+     * Then fires value change event
+     * @param direction Up or Down
+     * @param data type of data to change
+     * @returns {void}
+     */
+    private onApplyStep;
+    /**
+     * Calculate thumb position based on value and multiplier
+     * @param value decimal fraction value
+     * @param multiplier defaults to 100
+     * @returns thumb position as a fraction of 100
+     */
+    private calculatePosition;
+    /**
+     * Adds active attribute used in styling
+     * @param event focus event
+     * @returns {void}
+     */
+    private onThumbFocus;
+    /**
+     * Removes active attribute used in styling
+     * @param event focus event
+     * @returns {void}
+     */
+    private onThumbBlur;
+    /**
+     * On number-field blur
+     * @param event focus event
+     * @returns {void}
+     */
+    private onNumberFieldBlur;
+    /**
+     * On number-field input
+     * @param event input event
+     * @returns {void}
+     */
+    private onNumberFieldInput;
+    /**
+     * On number-field keydown
+     * @param event keyboard event
+     * @returns {void}
+     */
+    private onNumberFieldKeyDown;
+    /**
+     * Update notify property by input name attribute
+     * @param name name input attribute
+     * @param value input value
+     * @returns {void}
+     */
+    private updateNotifyProperty;
+    /**
+     * Dispatch data {value, from, to} changed event
+     * @returns {void}
+     */
+    private dispatchDataChangedEvent;
+    /**
+     * Dispatch data {input, from-input, to-input} changing event
+     * @returns {void}
+     */
+    private dispatchDataInputEvent;
+    /**
+     * Start dragging event on slider
+     * @param event event dragstart
+     * @returns {void}
+     */
+    private onDragStart;
+    /**
+     * Get mouse position in percentage value
+     * @param event event mousemove and touchmove
+     * @returns mouse position by percentage
+     */
+    private getMousePosition;
+    /**
+     * Dragging after on dragging start event
+     * @param event event mousemove and touchmove
+     * @returns {void}
+     */
+    private onDrag;
+    /**
+     * Saves changed data into correct field
+     * @param value value of changed data
+     * @returns {void}
+     */
+    private persistChangedData;
+    /**
+     * Validate and return FROM value within available range
+     * @param value from value
+     * @returns validated from value
+     */
+    private validateFrom;
+    /**
+     * Validate and return TO value within available range
+     * @param value to value
+     * @returns validated to value.
+     */
+    private validateTo;
+    /**
+     * Validate number field from changed thumb
+     * @returns {void}
+     */
+    private validateNumberField;
+    /**
+     * Calculate the nearest possible step value depending on step interval
+     * @param thumbPosition current thumb position in fraction
+     * @returns nearest available slider step in fraction
+     */
+    private getNearestPossibleValue;
+    /**
+     * Get slider value from thumb position
+     * @param position thumb position
+     * @returns calculated value
+     */
+    private getValueFromPosition;
+    /**
+     * Format value to display in both integer and fraction cases
+     * @param value value before use display
+     * @returns formatted value
+     */
+    private format;
+    /**
+     * End dragging event and remove dragging event
+     * @param event event mouseup and touchmove
+     * @returns {void}
+     */
+    private onDragEnd;
+    /**
+     * Value observer
+     * @returns {void}
+     */
+    private onValueChange;
+    /**
+     * From value observer
+     * @returns {void}
+     */
+    private onFromValueChange;
+    /**
+     * Check if value is inside min / max boundary
+     * @param value value is checking
+     * @param valueFor notation variable binding if range === true
+     * @returns true if value and step inside a boundary
+     */
+    private isValueInBoundary;
+    /**
+     * To value observer
+     * @returns {void}
+     */
+    private onToValueChange;
+    /**
+     * Step observer
+     * @returns {void}
+     */
+    private onStepChange;
+    /**
+     * Min range observer
+     * @returns {void}
+     */
+    private onMinRangeChange;
+    /**
+     * Min observer
+     * @param oldValue old value of min property
+     * @returns {void}
+     */
+    private onMinChange;
+    /**
+     * Max observer
+     * @param oldValue old value of max property
+     * @returns {void}
+     */
+    private onMaxChange;
+    /**
+     * Implement `render` Track template.
+     * @param range show range slider
+     * @returns Track template
+     */
+    private renderTrack;
+    /**
+     * Implement `render` Thumb template.
+     * @param value thumb value in track
+     * @param thumbPosition thumb position in track
+     * @param name name of thumb to render
+     * @returns Thumb template
+     */
+    private thumbTemplate;
+    /**
+     * Renders thumb template depending on parameter
+     * @param from thumb value start in track
+     * @param to thumb value end in track (optional)
+     * @returns Thumbs template
+     */
+    private renderThumb;
+    /**
+     * Implement `render` number field has template.
+     * @param value value in the slider for binding in the input value
+     * @param name name input value
+     * @returns {TemplateResult} number field template
+     */
+    private renderNumberField;
+    /**
+     * Implement `render` slider template.
+     * @returns Slider template
+     */
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'ef-slider': Slider;
+    }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ef-slider': Slider;
+  }
+
+  namespace JSX {
+    interface IntrinsicElements {
+      'ef-slider': Partial<Slider> | JSXInterface.HTMLAttributes<Slider>;
+    }
+  }
+}
+
+export {};