Skip to content

Commit

Permalink
docs: improve JSDoc, remove Polymer-specific parts (#3049)
Browse files Browse the repository at this point in the history
  • Loading branch information
@web-padawan
web-padawan authored Nov 16, 2021
1 parent 3d5fde4 commit 38caba7
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 82 deletions.
65 changes: 24 additions & 41 deletions packages/combo-box/src/vaadin-combo-box.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,77 +62,60 @@ export interface ComboBoxEventMap<TItem> extends HTMLElementEventMap {
}

/**
* `<vaadin-combo-box>` is a combo box element combining a dropdown list with an
* input field for filtering the list of items. If you want to replace the default
* input field with a custom implementation, you should use the
* [`<vaadin-combo-box-light>`](#/elements/vaadin-combo-box-light) element.
*
* Items in the dropdown list must be provided as a list of `String` values.
* Defining the items is done using the `items` property, which can be assigned
* with data-binding, using an attribute or directly with the JavaScript property.
* `<vaadin-combo-box>` is a web component for choosing a value from a filterable list of options
* presented in a dropdown overlay. The options can be provided as a list of strings or objects
* by setting [`items`](#/elements/vaadin-combo-box#property-items) property on the element.
*
* ```html
* <vaadin-combo-box
* label="Fruit"
* items="[[data]]">
* </vaadin-combo-box>
* <vaadin-combo-box id="combo-box"></vaadin-combo-box>
* ```
*
* ```js
* combobox.items = ['apple', 'orange', 'banana'];
* document.querySelector('#combo-box').items = ['apple', 'orange', 'banana'];
* ```
*
* When the selected `value` is changed, a `value-changed` event is triggered.
*
* ### Item rendering
*
* `<vaadin-combo-box>` supports using custom renderer callback function for defining the
* content of `<vaadin-combo-box-item>`.
* To customize the content of the `<vaadin-combo-box-item>` elements placed in the dropdown, use
* [`renderer`](#/elements/vaadin-combo-box#property-renderer) property which accepts a function.
* The renderer function is called with `root`, `comboBox`, and `model` as arguments.
*
* The renderer function provides `root`, `comboBox`, `model` arguments when applicable.
* Generate DOM content by using `model` object properties if needed, append it to the `root`
* element and control the state of the host element by accessing `comboBox`. Before generating new
* content, users are able to check if there is already content in `root` for reusing it.
* Generate DOM content by using `model` object properties if needed, and append it to the `root`
* element. The `comboBox` reference is provided to access the combo-box element state. Do not
* set combo-box properties in a `renderer` function.
*
* ```html
* <vaadin-combo-box id="combo-box"></vaadin-combo-box>
* ```
* ```js
* const comboBox = document.querySelector('#combo-box');
* comboBox.items = [{'label': 'Hydrogen', 'value': 'H'}];
* comboBox.renderer = function(root, comboBox, model) {
* root.innerHTML = model.index + ': ' +
* model.item.label + ' ' +
* '<b>' + model.item.value + '</b>';
* comboBox.renderer = (root, comboBox, model) => {
* const item = model.item;
* root.innerHTML = `${model.index}: ${item.label} <b>${item.value}</b>`;
* };
* ```
*
* Renderer is called on the opening of the combo-box and each time the related model is updated.
* DOM generated during the renderer call can be reused
* in the next renderer call and will be provided with the `root` argument.
* On first call it will be empty.
* Before creating new content, it is recommended to check if there is already an existing DOM
* element in `root` from a previous renderer call for reusing it. Even though combo-box uses
* infinite scrolling, reducing DOM operations might improve performance.
*
* The following properties are available in the `model` argument:
*
* Property name | Type | Description
* --------------|------|------------
* `index`| Number | Index of the item in the `items` array
* `item` | String or Object | The item reference
* `selected` | Boolean | True when item is selected
* `focused` | Boolean | True when item is focused
* Property | Type | Description
* -----------|------------------|-------------
* `index` | Number | Index of the item in the `items` array
* `item` | String or Object | The item reference
* `selected` | Boolean | True when item is selected
* `focused` | Boolean | True when item is focused
*
* ### Lazy Loading with Function Data Provider
*
* In addition to assigning an array to the items property, you can alternatively
* provide the `<vaadin-combo-box>` data through the
* In addition to assigning an array to the items property, you can alternatively use the
* [`dataProvider`](#/elements/vaadin-combo-box#property-dataProvider) function property.
* The `<vaadin-combo-box>` calls this function lazily, only when it needs more data
* to be displayed.
*
* See the [`dataProvider`](#/elements/vaadin-combo-box#property-dataProvider) in
* the API reference below for the detailed data provider arguments description,
* and the “Lazy Loading“ example on “Basics” page in the demos.
*
* __Note that when using function data providers, the total number of items
* needs to be set manually. The total number of items can be returned
* in the second argument of the data provider callback:__
Expand Down
65 changes: 24 additions & 41 deletions packages/combo-box/src/vaadin-combo-box.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,77 +19,60 @@ import { ComboBoxMixin } from './vaadin-combo-box-mixin.js';
registerStyles('vaadin-combo-box', inputFieldShared, { moduleId: 'vaadin-combo-box-styles' });

/**
* `<vaadin-combo-box>` is a combo box element combining a dropdown list with an
* input field for filtering the list of items. If you want to replace the default
* input field with a custom implementation, you should use the
* [`<vaadin-combo-box-light>`](#/elements/vaadin-combo-box-light) element.
*
* Items in the dropdown list must be provided as a list of `String` values.
* Defining the items is done using the `items` property, which can be assigned
* with data-binding, using an attribute or directly with the JavaScript property.
* `<vaadin-combo-box>` is a web component for choosing a value from a filterable list of options
* presented in a dropdown overlay. The options can be provided as a list of strings or objects
* by setting [`items`](#/elements/vaadin-combo-box#property-items) property on the element.
*
* ```html
* <vaadin-combo-box
* label="Fruit"
* items="[[data]]">
* </vaadin-combo-box>
* <vaadin-combo-box id="combo-box"></vaadin-combo-box>
* ```
*
* ```js
* combobox.items = ['apple', 'orange', 'banana'];
* document.querySelector('#combo-box').items = ['apple', 'orange', 'banana'];
* ```
*
* When the selected `value` is changed, a `value-changed` event is triggered.
*
* ### Item rendering
*
* `<vaadin-combo-box>` supports using custom renderer callback function for defining the
* content of `<vaadin-combo-box-item>`.
* To customize the content of the `<vaadin-combo-box-item>` elements placed in the dropdown, use
* [`renderer`](#/elements/vaadin-combo-box#property-renderer) property which accepts a function.
* The renderer function is called with `root`, `comboBox`, and `model` as arguments.
*
* The renderer function provides `root`, `comboBox`, `model` arguments when applicable.
* Generate DOM content by using `model` object properties if needed, append it to the `root`
* element and control the state of the host element by accessing `comboBox`. Before generating new
* content, users are able to check if there is already content in `root` for reusing it.
* Generate DOM content by using `model` object properties if needed, and append it to the `root`
* element. The `comboBox` reference is provided to access the combo-box element state. Do not
* set combo-box properties in a `renderer` function.
*
* ```html
* <vaadin-combo-box id="combo-box"></vaadin-combo-box>
* ```
* ```js
* const comboBox = document.querySelector('#combo-box');
* comboBox.items = [{'label': 'Hydrogen', 'value': 'H'}];
* comboBox.renderer = function(root, comboBox, model) {
* root.innerHTML = model.index + ': ' +
* model.item.label + ' ' +
* '<b>' + model.item.value + '</b>';
* comboBox.renderer = (root, comboBox, model) => {
* const item = model.item;
* root.innerHTML = `${model.index}: ${item.label} <b>${item.value}</b>`;
* };
* ```
*
* Renderer is called on the opening of the combo-box and each time the related model is updated.
* DOM generated during the renderer call can be reused
* in the next renderer call and will be provided with the `root` argument.
* On first call it will be empty.
* Before creating new content, it is recommended to check if there is already an existing DOM
* element in `root` from a previous renderer call for reusing it. Even though combo-box uses
* infinite scrolling, reducing DOM operations might improve performance.
*
* The following properties are available in the `model` argument:
*
* Property name | Type | Description
* --------------|------|------------
* `index`| Number | Index of the item in the `items` array
* `item` | String or Object | The item reference
* `selected` | Boolean | True when item is selected
* `focused` | Boolean | True when item is focused
* Property | Type | Description
* -----------|------------------|-------------
* `index` | Number | Index of the item in the `items` array
* `item` | String or Object | The item reference
* `selected` | Boolean | True when item is selected
* `focused` | Boolean | True when item is focused
*
* ### Lazy Loading with Function Data Provider
*
* In addition to assigning an array to the items property, you can alternatively
* provide the `<vaadin-combo-box>` data through the
* In addition to assigning an array to the items property, you can alternatively use the
* [`dataProvider`](#/elements/vaadin-combo-box#property-dataProvider) function property.
* The `<vaadin-combo-box>` calls this function lazily, only when it needs more data
* to be displayed.
*
* See the [`dataProvider`](#/elements/vaadin-combo-box#property-dataProvider) in
* the API reference below for the detailed data provider arguments description,
* and the “Lazy Loading“ example on “Basics” page in the demos.
*
* __Note that when using function data providers, the total number of items
* needs to be set manually. The total number of items can be returned
* in the second argument of the data provider callback:__
Expand Down

0 comments on commit 38caba7

Please sign in to comment.