Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 3 commits into from
Nov 27, 2023
Merged

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9fa1cf5
fix(ui5-slider, ui5-range-slider): enhance documentation
niyap Nov 23, 2023
1fa7234
Merge remote-tracking branch 'refs/remotes/origin/new-cem' into slide…
niyap Nov 27, 2023
a6d6b0b
docs(ui5-slider, ui5-range-slider): reflect review comments
niyap Nov 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
39 changes: 12 additions & 27 deletions packages/main/src/RangeSlider.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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",
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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) {
Expand All @@ -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) {
Expand Down Expand Up @@ -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
*/
Expand Down Expand Up @@ -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
*/
Expand Down
23 changes: 5 additions & 18 deletions packages/main/src/Slider.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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",
Expand All @@ -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
Expand Down
39 changes: 9 additions & 30 deletions packages/main/src/SliderBase.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,8 @@ type DirectionStart = "left" | "right";
*
* <h3 class="comment-api-title">Overview</h3>
*
*
* @constructor
* @author SAP SE
* @alias sap.ui.webc.main.SliderBase
* @extends sap.ui.webc.base.UI5Element
* @extends UI5Element
* @public
*/
@customElement({
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

move this JSDoc to the class declaration and create 2 static getters in the class respectively for styles and renderer. SliderBase is class, not a custom element so the decorator should not be used here

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

Expand All @@ -42,25 +39,21 @@ type DirectionStart = "left" | "right";
/**
* 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")
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 })
Expand All @@ -69,9 +62,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 })
Expand All @@ -82,9 +73,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 })
Expand All @@ -97,9 +86,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 })
Expand All @@ -110,9 +97,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 })
Expand All @@ -121,9 +106,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 })
Expand All @@ -132,9 +115,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 })
Expand All @@ -143,9 +124,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
*/
Expand Down