foundation.d.ts 8.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244
  1. /**
  2. * @license
  3. * Copyright 2020 Google Inc.
  4. *
  5. * Permission is hereby granted, free of charge, to any person obtaining a copy
  6. * of this software and associated documentation files (the "Software"), to deal
  7. * in the Software without restriction, including without limitation the rights
  8. * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  9. * copies of the Software, and to permit persons to whom the Software is
  10. * furnished to do so, subject to the following conditions:
  11. *
  12. * The above copyright notice and this permission notice shall be included in
  13. * all copies or substantial portions of the Software.
  14. *
  15. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16. * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17. * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  18. * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19. * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  20. * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  21. * THE SOFTWARE.
  22. */
  23. import { MDCFoundation } from '@material/base/foundation';
  24. import { MDCSliderAdapter } from './adapter';
  25. import { Thumb } from './types';
  26. /**
  27. * Foundation class for slider. Responsibilities include:
  28. * - Updating slider values (internal state and DOM updates) based on client
  29. * 'x' position.
  30. * - Updating DOM after slider property updates (e.g. min, max).
  31. */
  32. export declare class MDCSliderFoundation extends MDCFoundation<MDCSliderAdapter> {
  33. static SUPPORTS_POINTER_EVENTS: boolean;
  34. private initialStylesRemoved;
  35. private min;
  36. private max;
  37. private valueStart;
  38. private value;
  39. private rect;
  40. private isDisabled;
  41. private isDiscrete;
  42. private step;
  43. private minRange;
  44. private numDecimalPlaces;
  45. private hasTickMarks;
  46. private isRange;
  47. private thumb;
  48. private downEventClientX;
  49. private valueStartBeforeDownEvent;
  50. private valueBeforeDownEvent;
  51. private startThumbKnobWidth;
  52. private endThumbKnobWidth;
  53. private readonly animFrame;
  54. private mousedownOrTouchstartListener;
  55. private moveListener;
  56. private pointerdownListener;
  57. private pointerupListener;
  58. private thumbMouseenterListener;
  59. private thumbMouseleaveListener;
  60. private inputStartChangeListener;
  61. private inputEndChangeListener;
  62. private inputStartFocusListener;
  63. private inputEndFocusListener;
  64. private inputStartBlurListener;
  65. private inputEndBlurListener;
  66. private resizeListener;
  67. constructor(adapter?: Partial<MDCSliderAdapter>);
  68. static get defaultAdapter(): MDCSliderAdapter;
  69. init(): void;
  70. destroy(): void;
  71. setMin(value: number): void;
  72. setMax(value: number): void;
  73. getMin(): number;
  74. getMax(): number;
  75. /**
  76. * - For single point sliders, returns the thumb value.
  77. * - For range (two-thumb) sliders, returns the end thumb's value.
  78. */
  79. getValue(): number;
  80. /**
  81. * - For single point sliders, sets the thumb value.
  82. * - For range (two-thumb) sliders, sets the end thumb's value.
  83. */
  84. setValue(value: number): void;
  85. /**
  86. * Only applicable for range sliders.
  87. * @return The start thumb's value.
  88. */
  89. getValueStart(): number;
  90. /**
  91. * Only applicable for range sliders. Sets the start thumb's value.
  92. */
  93. setValueStart(valueStart: number): void;
  94. setStep(value: number): void;
  95. /**
  96. * Only applicable for range sliders. Sets the minimum difference between the
  97. * start and end values.
  98. */
  99. setMinRange(value: number): void;
  100. setIsDiscrete(value: boolean): void;
  101. getStep(): number;
  102. getMinRange(): number;
  103. setHasTickMarks(value: boolean): void;
  104. getDisabled(): boolean;
  105. /**
  106. * Sets disabled state, including updating styles and thumb tabindex.
  107. */
  108. setDisabled(disabled: boolean): void;
  109. /** @return Whether the slider is a range slider. */
  110. getIsRange(): boolean;
  111. /**
  112. * - Syncs slider boundingClientRect with the current DOM.
  113. * - Updates UI based on internal state.
  114. */
  115. layout({ skipUpdateUI }?: {
  116. skipUpdateUI?: boolean;
  117. }): void;
  118. /** Handles resize events on the window. */
  119. handleResize(): void;
  120. /**
  121. * Handles pointer down events on the slider root element.
  122. */
  123. handleDown(event: PointerEvent | MouseEvent | TouchEvent): void;
  124. /**
  125. * Handles pointer move events on the slider root element.
  126. */
  127. handleMove(event: PointerEvent | MouseEvent | TouchEvent): void;
  128. /**
  129. * Handles pointer up events on the slider root element.
  130. */
  131. handleUp(): void;
  132. /**
  133. * For range, discrete slider, shows the value indicator on both thumbs.
  134. */
  135. handleThumbMouseenter(): void;
  136. /**
  137. * For range, discrete slider, hides the value indicator on both thumbs.
  138. */
  139. handleThumbMouseleave(): void;
  140. handleMousedownOrTouchstart(event: MouseEvent | TouchEvent): void;
  141. handlePointerdown(event: PointerEvent): void;
  142. /**
  143. * Handles input `change` event by setting internal slider value to match
  144. * input's new value.
  145. */
  146. handleInputChange(thumb: Thumb): void;
  147. /** Shows activated state and value indicator on thumb(s). */
  148. handleInputFocus(thumb: Thumb): void;
  149. /** Removes activated state and value indicator from thumb(s). */
  150. handleInputBlur(thumb: Thumb): void;
  151. /**
  152. * Emits custom dragStart event, along with focusing the underlying input.
  153. */
  154. private handleDragStart;
  155. /**
  156. * @return The thumb to be moved based on initial down event.
  157. */
  158. private getThumbFromDownEvent;
  159. /**
  160. * @return The thumb to be moved based on move event (based on drag
  161. * direction from original down event). Only applicable if thumbs
  162. * were overlapping in the down event.
  163. */
  164. private getThumbFromMoveEvent;
  165. /**
  166. * Updates UI based on internal state.
  167. * @param thumb Thumb whose value is being updated. If undefined, UI is
  168. * updated for both thumbs based on current internal state.
  169. */
  170. private updateUI;
  171. /**
  172. * Updates thumb and input attributes based on current value.
  173. * @param thumb Thumb whose aria attributes to update.
  174. */
  175. private updateThumbAndInputAttributes;
  176. /**
  177. * Updates value indicator UI based on current value.
  178. * @param thumb Thumb whose value indicator to update. If undefined, all
  179. * thumbs' value indicators are updated.
  180. */
  181. private updateValueIndicatorUI;
  182. /**
  183. * Updates tick marks UI within slider, based on current min, max, and step.
  184. */
  185. private updateTickMarksUI;
  186. /** Maps clientX to a value on the slider scale. */
  187. private mapClientXOnSliderScale;
  188. /** Calculates the quantized value based on step value. */
  189. private quantize;
  190. /**
  191. * Updates slider value (internal state and UI) based on the given value.
  192. */
  193. private updateValue;
  194. /**
  195. * Clamps the given value for the given thumb based on slider properties:
  196. * - Restricts value within [min, max].
  197. * - If range slider, clamp start value <= end value - min range, and
  198. * end value >= start value + min range.
  199. */
  200. private clampValue;
  201. /**
  202. * Updates the active track and thumb style properties to reflect current
  203. * value.
  204. */
  205. private updateThumbAndTrackUI;
  206. /**
  207. * Shifts the value indicator to either side if it would otherwise stick
  208. * beyond the slider's length while keeping the caret above the knob.
  209. */
  210. private alignValueIndicator;
  211. /**
  212. * Removes initial inline styles if not already removed. `left:<...>%`
  213. * inline styles can be added to position the thumb correctly before JS
  214. * initialization. However, they need to be removed before the JS starts
  215. * positioning the thumb. This is because the JS uses
  216. * `transform:translateX(<...>)px` (for performance reasons) to position
  217. * the thumb (which is not possible for initial styles since we need the
  218. * bounding rect measurements).
  219. */
  220. private removeInitialStyles;
  221. /**
  222. * Resets track/thumb animation to prevent animation when adding
  223. * `transform` styles to thumb initially.
  224. */
  225. private resetTrackAndThumbAnimation;
  226. /**
  227. * Adds THUMB_TOP class to active thumb if thumb knobs overlap; otherwise
  228. * removes THUMB_TOP class from both thumbs.
  229. * @param thumb Thumb that is active (being moved).
  230. */
  231. private updateOverlappingThumbsUI;
  232. /**
  233. * Converts attribute value to a number, e.g. '100' => 100. Throws errors
  234. * for invalid values.
  235. * @param attributeValue Attribute value, e.g. 100.
  236. * @param attributeName Attribute name, e.g. `aria-valuemax`.
  237. */
  238. private convertAttributeValueToNumber;
  239. /** Checks that the given properties are valid slider values. */
  240. private validateProperties;
  241. private registerEventHandlers;
  242. private deregisterEventHandlers;
  243. private handlePointerup;
  244. }