docs(ui5-slider, ui5-range-slider): enhance documentation (#7910)

* fix(ui5-slider, ui5-range-slider): enhance documentation * docs(ui5-slider, ui5-range-slider): reflect review comments
SAP · Nov 27, 2023 · 0032fa6 · 0032fa6
1 parent 92ab975
commit 0032fa6
Show file tree

Hide file tree

Showing 3 changed files with 43 additions and 87 deletions.
diff --git a/packages/main/src/RangeSlider.ts b/packages/main/src/RangeSlider.ts
@@ -58,17 +58,6 @@ type AffectedValue = "startValue" | "endValue";
  * <h3>Responsive Behavior</h3>
  * You can move the currently selected range by clicking on it and dragging it along the interval.
  *
- * <h3>CSS Shadow Parts</h3>
- *
- * <ui5-link target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/CSS/::part">CSS Shadow Parts</ui5-link> allow developers to style elements inside the Shadow DOM.
- * <br>
- * The <code>ui5-range-slider</code> exposes the following CSS Shadow Parts:
- * <ul>
- * <li>progress-container - Used to style the progress container(the horizontal bar which visually represents the range between the minimum and maximum value) of the <code>ui5-range-slider</code>.</li>
- * <li>progress-bar - Used to style the progress bar, which shows the progress of the <code>ui5-range-slider</code>.</li>
- * <li>handle - Used to style the handles of the <code>ui5-range-slider</code>.</li>
- * </ul>
- *
  * <h3>Keyboard Handling</h3>
  *
  * <ul>
@@ -91,12 +80,12 @@ type AffectedValue = "startValue" | "endValue";
  *
  *
  * @constructor
- * @author SAP SE
- * @alias sap.ui.webc.main.RangeSlider
- * @extends sap.ui.webc.main.SliderBase
- * @tagname ui5-range-slider
+ * @extends SliderBase
  * @since 1.0.0-rc.11
  * @public
+ * @csspart progress-container - Used to style the progress container, the horizontal bar that visually represents the range between the minimum and maximum values, of the <code>ui5-range-slider</code>.
+ * @csspart progress-bar - Used to style the progress bar, which shows the progress of the <code>ui5-range-slider</code>.
+ * @csspart handle - Used to style the handles of the <code>ui5-range-slider</code>.
  */
 @customElement({
 	tag: "ui5-range-slider",
@@ -110,9 +99,7 @@ class RangeSlider extends SliderBase {
 	 * Defines start point of a selection - position of a first handle on the slider.
 	 * <br><br>
 	 *
-	 * @type {sap.ui.webc.base.types.Float}
-	 * @name sap.ui.webc.main.RangeSlider.prototype.startValue
-	 * @defaultvalue 0
+	 * @default 0
 	 * @formEvents change input
 	 * @formProperty
 	 * @public
@@ -124,9 +111,7 @@ class RangeSlider extends SliderBase {
 	 * Defines end point of a selection - position of a second handle on the slider.
 	 * <br><br>
 	 *
-	 * @type {sap.ui.webc.base.types.Float}
-	 * @name sap.ui.webc.main.RangeSlider.prototype.endValue
-	 * @defaultvalue 100
+	 * @default 100
 	 * @formEvents change input
 	 * @formProperty
 	 * @public
@@ -609,7 +594,7 @@ class RangeSlider extends SliderBase {
 	 * - mouse press position - cursor coordinates relative to the start/end handles
 	 * - selected inner element via a keyboard navigation
 	 *
-	 * @param {string} affectedValue The value that will get modified by the interaction
+	 * @param affectedValue The value that will get modified by the interaction
 	 * @private
 	 */
 	_setAffectedValue(affectedValue: AffectedValue | undefined) {
@@ -624,7 +609,7 @@ class RangeSlider extends SliderBase {
 	/**
 	 * Flag if press action is made on the currently selected range of values
 	 *
-	 * @param {boolean} isPressInCurrentRange Did the current press action occur in the current range (between the two handles)
+	 * @param isPressInCurrentRange Did the current press action occur in the current range (between the two handles)
 	 * @private
 	 */
 	_setIsPressInCurrentRange(isPressInCurrentRange: boolean) {
@@ -679,8 +664,8 @@ class RangeSlider extends SliderBase {
 	 * Uses the change of the position of the start handle and adds the initially
 	 * selected range to it, to determine the whole range offset.
 	 *
-	 * @param {Integer} currentPageXPos The current horizontal position of the cursor/touch
-	 * @param {Integer} initialStartHandlePageXPos The initial horizontal position of the start handle
+	 * @param currentPageXPos The current horizontal position of the cursor/touch
+	 * @param initialStartHandlePageXPos The initial horizontal position of the start handle
 	 *
 	 * @private
 	 */
@@ -710,8 +695,8 @@ class RangeSlider extends SliderBase {
 	 * Computes the new value based on the difference of the current cursor location from the
 	 * start of the interaction.
 	 *
-	 * @param {Integer} currentPageXPos The current horizontal position of the cursor/touch
-	 * @param {Integer} initialStartHandlePageXPos The initial horizontal position of the start handle
+	 * @param currentPageXPos The current horizontal position of the cursor/touch
+	 * @param initialStartHandlePageXPos The initial horizontal position of the start handle
 	 *
 	 * @private
 	 */

diff --git a/packages/main/src/Slider.ts b/packages/main/src/Slider.ts
@@ -46,17 +46,6 @@ import {
  * <li>Click/tap on the range bar to move the handle to that location.</li>
  * </ul>
  *
- * <h3>CSS Shadow Parts</h3>
- *
- * <ui5-link target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/CSS/::part">CSS Shadow Parts</ui5-link> allow developers to style elements inside the Shadow DOM.
- * <br>
- * The <code>ui5-slider</code> exposes the following CSS Shadow Parts:
- * <ul>
- * <li>progress-container - Used to style the progress container(the horizontal bar which visually represents the range between the minimum and maximum value) of the <code>ui5-slider</code>.</li>
- * <li>progress-bar - Used to style the progress bar, which shows the progress of the <code>ui5-slider</code>.</li>
- * <li>handle - Used to style the handle of the <code>ui5-slider</code>.</li>
- * </ul>
- *
  * <h3>Keyboard Handling</h3>
  *
  * <ul>
@@ -78,12 +67,12 @@ import {
  * <code>import "@ui5/webcomponents/dist/Slider";</code>
  *
  * @constructor
- * @author SAP SE
- * @alias sap.ui.webc.main.Slider
- * @extends sap.ui.webc.main.SliderBase
- * @tagname ui5-slider
+ * @extends SliderBase
  * @since 1.0.0-rc.11
  * @public
+ * @csspart progress-container - Used to style the progress container, the horizontal bar that visually represents the range between the minimum and maximum values, of the <code>ui5-slider</code>.
+ * @csspart progress-bar - Used to style the progress bar, which shows the progress of the <code>ui5-slider</code>.
+ * @csspart handle - Used to style the handle of the <code>ui5-slider</code>.
  */
 @customElement({
 	tag: "ui5-slider",
@@ -95,9 +84,7 @@ class Slider extends SliderBase {
 	/**
 	 * Current value of the slider
 	 *
-	 * @type {sap.ui.webc.base.types.Float}
-	 * @name sap.ui.webc.main.Slider.prototype.value
-	 * @defaultvalue 0
+	 * @default 0
 	 * @formEvents change input
 	 * @formProperty
 	 * @public

diff --git a/packages/main/src/SliderBase.ts b/packages/main/src/SliderBase.ts
@@ -23,44 +23,34 @@ type StateStorage = {
 
 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
- * @public
- */
-@customElement({
-	renderer: litRender,
-	styles: sliderBaseStyles,
-})
 /**
  * Fired when the value changes and the user has finished interacting with the slider.
  *
- * @event sap.ui.webc.main.SliderBase#change
  * @public
  */
 @event("change")
 
 /**
  * Fired when the value changes due to user interaction that is not yet finished - during mouse/touch dragging.
  *
- * @event sap.ui.webc.main.SliderBase#input
  * @public
  */
 @event("input")
+
+/**
+ * @class
+ *
+ * <h3 class="comment-api-title">Overview</h3>
+ *
+ * @constructor
+ * @extends UI5Element
+ * @public
+ */
 abstract 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
+	 * @default 0
 	 * @public
 	 */
 	@property({ validator: Float, defaultValue: 0 })
@@ -69,9 +59,7 @@ abstract class SliderBase extends UI5Element {
 	/**
 	 * Defines the maximum value of the slider.
 	 *
-	 * @type {sap.ui.webc.base.types.Float}
-	 * @name sap.ui.webc.main.SliderBase.prototype.max
-	 * @defaultvalue 100
+	 * @default 100
 	 * @public
 	 */
 	@property({ validator: Float, defaultValue: 100 })
@@ -82,9 +70,7 @@ abstract class SliderBase extends UI5Element {
 	 * <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
+	 * @default 1
 	 * @public
 	 */
 	@property({ validator: Float, defaultValue: 1 })
@@ -97,9 +83,7 @@ abstract class SliderBase extends UI5Element {
 	 * 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
+	 * @default 0
 	 * @public
 	 */
 	@property({ validator: Integer, defaultValue: 0 })
@@ -110,9 +94,7 @@ abstract class SliderBase extends UI5Element {
 	 * <br><br>
 	 * <b>Note:</b> The step must be a positive number.
 	 *
-	 * @type {boolean}
-	 * @name sap.ui.webc.main.SliderBase.prototype.showTickmarks
-	 * @defaultvalue false
+	 * @default false
 	 * @public
 	 */
 	@property({ type: Boolean })
@@ -121,9 +103,7 @@ abstract class SliderBase extends UI5Element {
 	/**
 	 * Enables handle tooltip displaying the current value.
 	 *
-	 * @type {boolean}
-	 * @name sap.ui.webc.main.SliderBase.prototype.showTooltip
-	 * @defaultvalue false
+	 * @default false
 	 * @public
 	 */
 	@property({ type: Boolean })
@@ -132,9 +112,7 @@ abstract class SliderBase extends UI5Element {
 	/**
 	 * Defines whether the slider is in disabled state.
 	 *
-	 * @type {boolean}
-	 * @name sap.ui.webc.main.SliderBase.prototype.disabled
-	 * @defaultvalue false
+	 * @default false
 	 * @public
 	 */
 	@property({ type: Boolean })
@@ -143,9 +121,7 @@ abstract class SliderBase extends UI5Element {
 	/**
 	 * Defines the accessible ARIA name of the component.
 	 *
-	 * @type {string}
-	 * @name sap.ui.webc.main.SliderBase.prototype.accessibleName
-	 * @defaultvalue: ""
+	 * @default ""
 	 * @public
 	 * @since 1.4.0
 	 */
@@ -249,6 +225,14 @@ abstract class SliderBase extends UI5Element {
 		};
 	}
 
+	static get render() {
+		return litRender;
+	}
+
+	static get styles() {
+		return sliderBaseStyles;
+	}
+
 	get classes() {
 		return {
 			root: {