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

docs(ui5-multi-combobox): improve documentation #7944

Merged
merged 1 commit into from
Dec 4, 2023
Merged

docs(ui5-multi-combobox): improve documentation #7944

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 26 additions & 67 deletions packages/main/src/MultiComboBox.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ import Tokenizer, { ClipboardDataOperation } from "./Tokenizer.js";
import type { TokenizerTokenDeleteEventDetail } from "./Tokenizer.js";
import Token from "./Token.js";
import Icon from "./Icon.js";
import type { IIcon } from "./Interfaces.js";
import Popover from "./Popover.js";
import ResponsivePopover from "./ResponsivePopover.js";
import List from "./List.js";
Expand Down Expand Up @@ -100,6 +101,9 @@ import ComboBoxFilter from "./types/ComboBoxFilter.js";
import type FormSupportT from "./features/InputElementsFormSupport.js";
import type ListItemBase from "./ListItemBase.js";

/**
* @public
*/
interface IMultiComboBoxItem extends UI5Element {
text: string,
selected: boolean,
Expand Down Expand Up @@ -154,28 +158,16 @@ type MultiComboboxItemWithSelection = {
* <li> Backspace - deletes the token and focus the next token. </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-multi-combobox</code> exposes the following CSS Shadow Parts:
* <ul>
* <li>token-{index} - Used to style each token(where <code>token-0</code> corresponds to the first item)</li>
* </ul>
*
* <h3>ES6 Module Import</h3>
*
* <code>import "@ui5/webcomponents/dist/MultiComboBox";</code>
*
*
* @constructor
* @author SAP SE
* @alias sap.ui.webc.main.MultiComboBox
* @extends sap.ui.webc.base.UI5Element
* @tagname ui5-multi-combobox
* @extends UI5Element
* @public
* @appenddocs sap.ui.webc.main.MultiComboBoxItem sap.ui.webc.main.MultiComboBoxGroupItem
* @since 0.11.0
* @csspart token-{index} - Used to style each token(where <code>token-0</code> corresponds to the first item)
*/
@customElement({
tag: "ui5-multi-combobox",
Expand Down Expand Up @@ -203,23 +195,20 @@ type MultiComboboxItemWithSelection = {
/**
* Fired when the input operation has finished by pressing Enter or on focusout.
*
* @event sap.ui.webc.main.MultiComboBox#change
* @public
*/
@event("change")

/**
* Fired when the value of the component changes at each keystroke.
*
* @event sap.ui.webc.main.MultiComboBox#input
* @public
*/
@event("input")

/**
* Fired when the dropdown is opened or closed.
*
* @event sap.ui.webc.main.MultiComboBox#open-change
* @since 1.0.0-rc.5
* @public
*/
Expand All @@ -229,13 +218,15 @@ type MultiComboboxItemWithSelection = {
* Fired when selection is changed by user interaction
* in <code>SingleSelect</code> and <code>MultiSelect</code> modes.
*
* @event sap.ui.webc.main.MultiComboBox#selection-change
* @param {Array} items an array of the selected items.
* @param {IMultiComboBoxItem[]} items an array of the selected items.
* @public
*/
@event("selection-change", {
detail: {
items: { type: Array },
/**
* @public
*/
items: { type: Array<IMultiComboBoxItem> },
},
})

Expand All @@ -245,9 +236,7 @@ class MultiComboBox extends UI5Element {
* <br><br>
* <b>Note:</b> The property is updated upon typing.
*
* @type {string}
* @name sap.ui.webc.main.MultiComboBox.prototype.value
* @defaultvalue ""
* @default ""
* @formEvents change input
* @formProperty
* @public
Expand All @@ -258,9 +247,7 @@ class MultiComboBox extends UI5Element {
/**
* Defines whether the value will be autcompleted to match an item
*
* @type {boolean}
* @name sap.ui.webc.main.MultiComboBox.prototype.noTypeahead
* @defaultvalue false
* @default false
* @public
* @since 1.4.0
*/
Expand All @@ -270,9 +257,8 @@ class MultiComboBox extends UI5Element {
/**
* Defines a short hint intended to aid the user with data entry when the
* component has no value.
* @type {string}
* @name sap.ui.webc.main.MultiComboBox.prototype.placeholder
* @defaultvalue ""
*
* @default ""
* @public
*/
@property()
Expand All @@ -281,9 +267,7 @@ class MultiComboBox extends UI5Element {
/**
* Defines if the user input will be prevented, if no matching item has been found
*
* @type {boolean}
* @name sap.ui.webc.main.MultiComboBox.prototype.allowCustomValues
* @defaultvalue false
* @default false
* @public
*/
@property({ type: Boolean })
Expand All @@ -294,9 +278,7 @@ class MultiComboBox extends UI5Element {
* <br><br>
* <b>Note:</b> A disabled component is completely noninteractive.
*
* @type {boolean}
* @name sap.ui.webc.main.MultiComboBox.prototype.disabled
* @defaultvalue false
* @default false
* @public
*/
@property({ type: Boolean })
Expand All @@ -307,9 +289,7 @@ class MultiComboBox extends UI5Element {
* <br><br>
* Available options are:
*
* @type {sap.ui.webc.base.types.ValueState}
* @name sap.ui.webc.main.MultiComboBox.prototype.valueState
* @defaultvalue "None"
* @default "None"
* @public
*/
@property({ type: ValueState, defaultValue: ValueState.None })
Expand All @@ -321,9 +301,7 @@ class MultiComboBox extends UI5Element {
* <b>Note:</b> A read-only component is not editable,
* but still provides visual feedback upon user interaction.
*
* @type {boolean}
* @name sap.ui.webc.main.MultiComboBox.prototype.readonly
* @defaultvalue false
* @default false
* @public
*/
@property({ type: Boolean })
Expand All @@ -332,9 +310,7 @@ class MultiComboBox extends UI5Element {
/**
* Defines whether the component is required.
*
* @type {boolean}
* @name sap.ui.webc.main.MultiComboBox.prototype.required
* @defaultvalue false
* @default false
* @public
* @since 1.0.0-rc.5
*/
Expand All @@ -345,9 +321,7 @@ class MultiComboBox extends UI5Element {
* Defines the filter type of the component.
* Available options are: <code>StartsWithPerTerm</code>, <code>StartsWith</code>, <code>Contains</code> and <code>None</code>.
*
* @type {sap.ui.webc.main.types.ComboBoxFilter}
* @name sap.ui.webc.main.MultiComboBox.prototype.filter
* @defaultvalue "StartsWithPerTerm"
* @default "StartsWithPerTerm"
* @public
*/
@property({ type: ComboBoxFilter, defaultValue: ComboBoxFilter.StartsWithPerTerm })
Expand All @@ -356,10 +330,7 @@ class MultiComboBox extends UI5Element {
/**
* Indicates whether the dropdown is open. True if the dropdown is open, false otherwise.
*
* @type {boolean}
* @name sap.ui.webc.main.MultiComboBox.prototype.open
* @defaultvalue false
* @readonly
* @default false
* @since 1.0.0-rc.5
* @public
*/
Expand All @@ -369,9 +340,7 @@ class MultiComboBox extends UI5Element {
/**
* Defines the accessible ARIA name of the component.
*
* @type {string}
* @name sap.ui.webc.main.MultiComboBox.prototype.accessibleName
* @defaultvalue ""
* @default ""
* @public
* @since 1.4.0
*/
Expand All @@ -381,9 +350,7 @@ class MultiComboBox extends UI5Element {
/**
* Receives id(or many ids) of the elements that label the component.
*
* @type {string}
* @name sap.ui.webc.main.MultiComboBox.prototype.accessibleNameRef
* @defaultvalue ""
* @default ""
* @public
* @since 1.4.0
*/
Expand Down Expand Up @@ -427,9 +394,6 @@ class MultiComboBox extends UI5Element {
/**
* Defines the component items.
*
* @type {sap.ui.webc.main.IMultiComboBoxItem[]}
* @name sap.ui.webc.main.MultiComboBox.prototype.default
* @slot items
* @public
*/
@slot({ type: HTMLElement, "default": true, invalidateOnChildChange: true })
Expand All @@ -438,14 +402,11 @@ class MultiComboBox extends UI5Element {
/**
* Defines the icon to be displayed in the component.
*
* @type {sap.ui.webc.main.IIcon[]}
* @name sap.ui.webc.main.MultiComboBox.prototype.icon
* @slot
* @public
* @since 1.0.0-rc.9
*/
@slot()
icon!: Array<Icon>;
icon!: Array<IIcon>;

/**
* Defines the value state message that will be displayed as pop up under the component.
Expand All @@ -455,10 +416,8 @@ class MultiComboBox extends UI5Element {
* <br>
* <b>Note:</b> The <code>valueStateMessage</code> would be displayed,
* when the component is in <code>Information</code>, <code>Warning</code> or <code>Error</code> value state.
* @type {HTMLElement[]}
* @name sap.ui.webc.main.MultiComboBox.prototype.valueStateMessage
*
* @since 1.0.0-rc.9
* @slot
* @public
*/
@slot()
Expand Down
10 changes: 2 additions & 8 deletions packages/main/src/MultiComboBoxGroupItem.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,23 +9,17 @@ import type { IMultiComboBoxItem } from "./MultiComboBox.js";
* that can be used to split the <code>ui5-multi-combobox</code> suggestions into groups.
*
* @constructor
* @author SAP SE
* @alias sap.ui.webc.main.MultiComboBoxGroupItem
* @extends sap.ui.webc.base.UI5Element
* @abstract
* @tagname ui5-mcb-group-item
* @public
* @implements sap.ui.webc.main.IMultiComboBoxItem
* @implements {IMultiComboBoxItem}
* @since 1.4.0
*/
@customElement("ui5-mcb-group-item")
class MultiComboBoxGroupItem extends UI5Element implements IMultiComboBoxItem {
/**
* Defines the text of the component.
*
* @type {string}
* @name sap.ui.webc.main.MultiComboBoxGroupItem.prototype.text
* @defaultvalue ""
* @default ""
* @public
*/
@property()
Expand Down
12 changes: 4 additions & 8 deletions packages/main/src/MultiComboBoxItem.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,17 @@ import type { IMultiComboBoxItem } from "./MultiComboBox.js";
* The <code>ui5-mcb-item</code> represents the item for a <code>ui5-multi-combobox</code>.
*
* @constructor
* @author SAP SE
* @alias sap.ui.webc.main.MultiComboBoxItem
* @extends sap.ui.webc.main.ComboBoxItem
* @extends ComboBoxItem
* @abstract
* @tagname ui5-mcb-item
* @implements sap.ui.webc.main.IMultiComboBoxItem
* @implements {IMultiComboBoxItem}
* @public
*/
@customElement("ui5-mcb-item")
class MultiComboBoxItem extends ComboBoxItem implements IMultiComboBoxItem {
/**
* Defines the selected state of the component.
* @type {boolean}
* @name sap.ui.webc.main.MultiComboBoxItem.prototype.selected
* @defaultvalue false
*
* @default false
* @public
*/
@property({ type: Boolean })
Expand Down
Loading