@ui5/webcomponents 1.9.3 → 1.10.0

package/dist/SliderBase.d.ts

@@ -0,0 +1,357 @@
+import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
+import type { ComponentStylesData, PassiveEventListenerObject } from "@ui5/webcomponents-base/dist/types.js";
+import "@ui5/webcomponents-icons/dist/direction-arrows.js";
+type StateStorage = {
+    [key: string]: number | undefined;
+};
+type DirectionStart = "left" | "right";
+/**
+ * @class
+ *
+ * <h3 class="comment-api-title">Overview</h3>
+ *
+ *
+ * @constructor
+ * @author SAP SE
+ * @alias sap.ui.webc.main.SliderBase
+ * @extends sap.ui.webc.base.UI5Element
+ * @tagname ui5-slider
+ * @public
+ */
+/**
+ * Fired when the value changes and the user has finished interacting with the slider.
+ *
+ * @event sap.ui.webc.main.SliderBase#change
+ * @public
+ */
+declare class SliderBase extends UI5Element {
+    /**
+     * Defines the minimum value of the slider.
+     *
+     * @type {sap.ui.webc.base.types.Float}
+     * @name sap.ui.webc.main.SliderBase.prototype.min
+     * @defaultvalue 0
+     * @public
+     */
+    min: number;
+    /**
+     * Defines the maximum value of the slider.
+     *
+     * @type {sap.ui.webc.base.types.Float}
+     * @name sap.ui.webc.main.SliderBase.prototype.max
+     * @defaultvalue 100
+     * @public
+     */
+    max: number;
+    /**
+     * Defines the size of the slider's selection intervals (e.g. min = 0, max = 10, step = 5 would result in possible selection of the values 0, 5, 10).
+     * <br><br>
+     * <b>Note:</b> If set to 0 the slider handle movement is disabled. When negative number or value other than a number, the component fallbacks to its default value.
+     *
+     * @type {sap.ui.webc.base.types.Integer}
+     * @name sap.ui.webc.main.SliderBase.prototype.step
+     * @defaultvalue 1
+     * @public
+     */
+    step: number;
+    /**
+     * Displays a label with a value on every N-th step.
+     * <br><br>
+     * <b>Note:</b> The step and tickmarks properties must be enabled.
+     * Example - if the step value is set to 2 and the label interval is also specified to 2 - then every second
+     * tickmark will be labelled, which means every 4th value number.
+     *
+     * @type {sap.ui.webc.base.types.Integer}
+     * @name sap.ui.webc.main.SliderBase.prototype.labelInterval
+     * @defaultvalue 0
+     * @public
+     */
+    labelInterval: number;
+    /**
+     * Enables tickmarks visualization for each step.
+     * <br><br>
+     * <b>Note:</b> The step must be a positive number.
+     *
+     * @type {boolean}
+     * @name sap.ui.webc.main.SliderBase.prototype.showTickmarks
+     * @defaultvalue false
+     * @public
+     */
+    showTickmarks: boolean;
+    /**
+     * Enables handle tooltip displaying the current value.
+     *
+     * @type {boolean}
+     * @name sap.ui.webc.main.SliderBase.prototype.showTooltip
+     * @defaultvalue false
+     * @public
+     */
+    showTooltip: boolean;
+    /**
+     * Defines whether the slider is in disabled state.
+     *
+     * @type {boolean}
+     * @name sap.ui.webc.main.SliderBase.prototype.disabled
+     * @defaultvalue false
+     * @public
+     */
+    disabled: boolean;
+    /**
+     * Defines the accessible ARIA name of the component.
+     *
+     * @type {string}
+     * @name sap.ui.webc.main.SliderBase.prototype.accessibleName
+     * @defaultvalue: ""
+     * @public
+     * @since 1.4.0
+     */
+    accessibleName: string;
+    /**
+     * @private
+     */
+    _tooltipVisibility: string;
+    _labelsOverlapping: boolean;
+    _hiddenTickmarks: boolean;
+    _resizeHandler: () => void;
+    _moveHandler: (e: TouchEvent | MouseEvent) => void;
+    _upHandler: () => void;
+    _stateStorage: StateStorage;
+    _ontouchstart: PassiveEventListenerObject;
+    notResized: boolean;
+    _isUserInteraction: boolean;
+    _isInnerElementFocusing: boolean;
+    _oldNumberOfLabels?: number;
+    _labelWidth: number;
+    _labelValues?: Array<string>;
+    constructor();
+    _handleMove(e: TouchEvent | MouseEvent): void;
+    _handleUp(): void;
+    _onmousedown(e: TouchEvent | MouseEvent): void;
+    _handleActionKeyPress(e: Event): void;
+    static get render(): (templateResult: object, container: HTMLElement | DocumentFragment, styleStrOrHrefsArr: string | string[] | undefined, forStaticArea: boolean, options: import("lit-html").RenderOptions) => void;
+    static get styles(): ComponentStylesData;
+    static get ACTION_KEYS(): ((event: KeyboardEvent) => boolean)[];
+    static get MIN_SPACE_BETWEEN_TICKMARKS(): number;
+    static get TOOLTIP_VISIBILITY(): {
+        VISIBLE: string;
+        HIDDEN: string;
+    };
+    get classes(): {
+        root: {
+            "ui5-slider-root-phone": boolean;
+        };
+        labelContainer: {
+            "ui5-slider-hidden-labels": boolean;
+        };
+    };
+    onEnterDOM(): void;
+    onExitDOM(): void;
+    onAfterRendering(): void;
+    /** Shows the tooltip(s) if the <code>showTooltip</code> property is set to true
+     *
+     * @private
+     */
+    _onmouseover(): void;
+    /**
+     * Hides the tooltip(s) if the <code>showTooltip</code> property is set to true
+     *
+     * @private
+     */
+    _onmouseout(): void;
+    _onkeydown(e: KeyboardEvent): void;
+    _onkeyup(): void;
+    /**
+     * Flags if an inner element is currently being focused
+     *
+     * @private
+     */
+    _preserveFocus(isFocusing: boolean): void;
+    /**
+     * Return if an inside element within the component is currently being focused
+     *
+     * @private
+     */
+    _isFocusing(): boolean;
+    /**
+     * Prevent focus out when inner element within the component is currently being in process of focusing in.
+     * In theory this can be achieved either if the shadow root is focusable and 'delegatesFocus' attribute of
+     * the .attachShadow() customElement method is set to true, or if we forward it manually.
+
+     * As we use lit-element as base of our core UI5 element class that 'delegatesFocus' property is not set to 'true' and
+     * we have to manage the focus here. If at some point in the future this changes, the focus delegating logic could be
+     * removed as it will become redundant.
+     *
+     * When we manually set the focus on mouseDown to the first focusable element inside the shadowDom,
+     * that inner focus (shadowRoot.activeElement) is set a moment before the global document.activeElement
+     * is set to the customElement (ui5-slider) causing a 'race condition'.
+     *
+     * In order for a element within the shadowRoot to be focused, the global document.activeElement MUST be the parent
+     * customElement of the shadow root, in our case the ui5-slider component. Because of that after our focusin of the handle,
+     * a focusout event fired by the browser immidiatly after, resetting the focus. Focus out must be manually prevented
+     * in both initial focusing and switching the focus between inner elements of the component cases.
+
+     * Note: If we set the focus to the handle with a timeout or a bit later in time, on a mouseup or click event it will
+     * work fine and we will avoid the described race condition as our host customElement will be already finished focusing.
+     * However, that does not work for us as we need the focus to be set to the handle exactly on mousedown,
+     * because of the nature of the component and its available drag interactions.
+     *
+     * @private
+     */
+    _preventFocusOut(): void;
+    /**
+     * Manages the focus between the component's inner elements
+     * @protected
+     */
+    focusInnerElement(): void;
+    /**
+     * Handle the responsiveness of the Slider's UI elements when resizing
+     *
+     * @private
+     */
+    _handleResize(): void;
+    /**
+     * Called when the user starts interacting with the slider.
+     * After a down event on the slider root, listen for move events on window, so the slider value
+     * is updated even if the user drags the pointer outside the slider root.
+     *
+     * @protected
+     */
+    handleDownBase(e: TouchEvent | MouseEvent): number;
+    /**
+     * Forward the focus to an inner inner part within the component on press
+     *
+     * @private
+     */
+    _handleFocusOnMouseDown(e: TouchEvent | MouseEvent): void;
+    /**
+     * Called when the user finish interacting with the slider
+     * Fires an <code>change</code> event indicating a final value change, after user interaction is finished.
+     *
+     * @protected
+     */
+    handleUpBase(): void;
+    /**
+     * Updates state storage for the value-related property
+     * Fires an <code>input</code> event indicating a value change via interaction that is not yet finished.
+     *
+     * @protected
+     */
+    updateStateStorageAndFireInputEvent(valueType: string): void;
+    /**
+     * Goes through the key shortcuts available for the component and returns 'true' if the event is triggered by one.
+     *
+     * @private
+     */
+    static _isActionKey(e: KeyboardEvent): boolean;
+    /**
+     * Locks the given value between min and max boundaries based on slider properties
+     *
+     * @protected
+     */
+    static clipValue(value: number, min: number, max: number): number;
+    /**
+     * Sets the slider value from an event
+     *
+     * @protected
+     */
+    static getValueFromInteraction(e: TouchEvent | MouseEvent, stepSize: number, min: number, max: number, boundingClientRect: DOMRect, directionStart: DirectionStart): number;
+    /**
+     * "Stepify" the raw value - calculate the new value depending on the specified step property
+     *
+     * @protected
+     */
+    static getSteppedValue(value: number, stepSize: number, min: number): number;
+    /**
+     * Gets pageX value from event on user interaction with the Slider
+     *
+     * @protected
+     */
+    static getPageXValueFromEvent(e: TouchEvent | MouseEvent): number;
+    /**
+     * Computes the new value (in %) from the pageX position of the cursor.
+     * Returns the value rounded to a precision of at most 2 digits after decimal point.
+     *
+     * @protected
+     */
+    static computedValueFromPageX(pageX: number, min: number, max: number, boundingClientRect: DOMRect, directionStart: DirectionStart): number;
+    /**
+     * Calculates the precision (decimal places) of a number, returns 0 if integer
+     * Handles scientific notation cases.
+     * @private
+     */
+    static _getDecimalPrecisionOfNumber(value: number): number;
+    /**
+     * In order to always keep the visual UI representation and the internal
+     * state in sync, the component has a 'state storage' that is updated when the
+     * current state is changed due to a user action.
+     *
+     * Check if the previously saved state is outdated. That would mean
+     * a property has been changed programmatically because the previous state
+     * is always updated in the interaction handlers.
+     *
+     * Will return true if any of the properties is not equal to its previously
+     * stored value.
+     *
+     * @protected
+     */
+    isCurrentStateOutdated(): boolean;
+    /**
+     * Returns the last stored value of a property
+     *
+     * @protected
+     */
+    getStoredPropertyState(prop: string): number | undefined;
+    /**
+     * Check if one or more properties have been updated compared to their last
+     * saved values in the state storage.
+     *
+     * @protected
+     */
+    isPropertyUpdated(...props: Array<string>): boolean;
+    /**
+     * Updates the previously saved in the _stateStorage values of one or more properties.
+     *
+     * @protected
+     */
+    storePropertyState(...props: Array<string>): void;
+    /**
+     * Returns the start side of a direction - left for LTR, right for RTL
+     */
+    get directionStart(): "left" | "right";
+    /**
+     * Calculates the labels amount, width and text and creates them
+     *
+     * @private
+     */
+    _createLabels(): void;
+    _handleActionKeyPressBase(e: KeyboardEvent, affectedPropName: string): number;
+    static _isDecreaseValueAction(e: KeyboardEvent): boolean;
+    static _isIncreaseValueAction(e: KeyboardEvent): boolean;
+    static _isBigStepAction(e: KeyboardEvent): boolean;
+    get _tickmarksCount(): number;
+    /**
+     * Calculates space between tickmarks
+     *
+     * @private
+     */
+    _spaceBetweenTickmarks(): number;
+    /**
+     * Notify in case of a invalid step value type
+     *
+     * @private
+     */
+    _validateStep(step: number): void;
+    get _labels(): string[];
+    /**
+     * Normalizes a new <code>step</code> property value.
+     * If tickmarks are enabled recreates them according to it.
+     *
+     * @private
+     */
+    get _effectiveStep(): number;
+    get _effectiveMin(): number;
+    get _effectiveMax(): number;
+    get _tabIndex(): "0" | "-1";
+    get _ariaLabelledByHandleRefs(): string;
+}
+export default SliderBase;