377 lines
12 KiB
Markdown
377 lines
12 KiB
Markdown
# Combobox >> Use Cases ||20
|
|
|
|
A combobox is a widget made up of the combination of two distinct elements:
|
|
|
|
- a single-line textbox
|
|
- an associated listbox overlay
|
|
|
|
Based on the combobox configuration and entered textbox value, options in the listbox will be
|
|
filtered, checked, focused and the textbox value may be autocompleted.
|
|
Optionally the combobox contains a graphical button adjacent to the textbox, indicating the
|
|
availability of the popup.
|
|
|
|
> Fore more information, consult [Combobox wai-aria design pattern](https://www.w3.org/TR/wai-aria-practices/#combobox)
|
|
|
|
```js script
|
|
import { LitElement, html, repeat } from '@mdjs/mdjs-preview';
|
|
import { listboxData } from '../listbox/src/listboxData.js';
|
|
import { LionCombobox } from '@lion/combobox';
|
|
import '@lion/listbox/define';
|
|
import '@lion/combobox/define';
|
|
import './src/demo-selection-display.js';
|
|
import { lazyRender } from './src/lazyRender.js';
|
|
import levenshtein from './src/levenshtein.js';
|
|
```
|
|
|
|
## Autocomplete
|
|
|
|
Below you will find an overview of all possible `autocomplete` behaviors and how they correspond
|
|
to the configurable values `none`, `list`, `inline` and `both`.
|
|
|
|
| | list | filter | focus | check | complete |
|
|
| -----: | :--: | :----: | :---: | :---: | :------: |
|
|
| none | ✓ | | | | |
|
|
| list | ✓ | ✓ | ✓ | ✓ | |
|
|
| inline | ✓ | | ✓ | ✓ | ✓ |
|
|
| both | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
|
|
- **list** shows a list on keydown character press
|
|
- **filter** filters list of potential matches according to `matchmode` or provided `matchCondition`
|
|
- **focus** automatically focuses closest match (makes it the activedescendant)
|
|
- **check** automatically checks/selects closest match when `selection-follows-focus` is enabled (this is the default configuration)
|
|
- **complete** completes the textbox value inline (the 'missing characters' will be added as selected text)
|
|
|
|
When `autocomplete="none"` is configured, the suggested options in the overlay are not filtered
|
|
based on the characters typed in the textbox.
|
|
Selection will happen manually by the user.
|
|
|
|
```js preview-story
|
|
export const autocompleteNone = () => html`
|
|
<lion-combobox name="combo" label="Autocomplete 'none'" autocomplete="none">
|
|
${lazyRender(
|
|
listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
|
|
)}
|
|
</lion-combobox>
|
|
`;
|
|
```
|
|
|
|
When `autocomplete="list"` is configured, it will filter listbox suggestions based on textbox value.
|
|
|
|
```js preview-story
|
|
export const autocompleteList = () => html`
|
|
<lion-combobox name="combo" label="Autocomplete 'list'" autocomplete="list">
|
|
${lazyRender(
|
|
listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
|
|
)}
|
|
</lion-combobox>
|
|
`;
|
|
```
|
|
|
|
When `autocomplete="inline"` is configured, it will present a value completion prediction inside the text input itself.
|
|
It does NOT filter list of potential matches.
|
|
|
|
```js preview-story
|
|
export const autocompleteInline = () => html`
|
|
<lion-combobox name="combo" label="Autocomplete 'inline'" autocomplete="inline">
|
|
${lazyRender(
|
|
listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
|
|
)}
|
|
</lion-combobox>
|
|
`;
|
|
```
|
|
|
|
When `autocomplete="both"` is configured, it combines the filtered list from `'list'` with the text input value completion prediction from `'inline'`.
|
|
This is the default value for `autocomplete`.
|
|
|
|
```js preview-story
|
|
export const autocompleteBoth = () => html`
|
|
<lion-combobox name="combo" label="Autocomplete 'both'" autocomplete="both">
|
|
${lazyRender(
|
|
listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
|
|
)}
|
|
</lion-combobox>
|
|
`;
|
|
```
|
|
|
|
## Match Mode
|
|
|
|
When `match-mode="begin"` is applied, the entered text in the textbox only filters
|
|
options whose values begin with the entered text. For instance, the entered text 'ch' will match
|
|
with value 'Chard', but not with 'Artichoke'.
|
|
By default `match-mode="all"` is applied. This will also match parts of a word.
|
|
So 'ch' will both match 'Chard' and 'Artichoke'.
|
|
|
|
```js preview-story
|
|
export const matchModeBegin = () => html`
|
|
<lion-combobox name="combo" label="Match Mode 'begin'" match-mode="begin">
|
|
${lazyRender(
|
|
listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
|
|
)}
|
|
</lion-combobox>
|
|
`;
|
|
```
|
|
|
|
```js preview-story
|
|
export const matchModeAll = () => html`
|
|
<lion-combobox name="combo" label="Match Mode 'all'" match-mode="all">
|
|
${lazyRender(
|
|
listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
|
|
)}
|
|
</lion-combobox>
|
|
`;
|
|
```
|
|
|
|
When the preconfigurable `match-mode` conditions are not sufficient,
|
|
one can define a custom matching function.
|
|
The example below matches when the Levenshtein distance is below 3 (including some other conditions).
|
|
|
|
```js preview-story
|
|
export const customMatchCondition = () => html`
|
|
<lion-combobox
|
|
name="combo"
|
|
label="Custom Match Mode 'levenshtein'"
|
|
help-text="Spelling mistakes will be forgiven. Try typing 'Aple' instead of 'Apple'"
|
|
.matchCondition="${({ choiceValue }, textboxValue) => {
|
|
const oVal = choiceValue.toLowerCase();
|
|
const tVal = textboxValue.toLowerCase();
|
|
const t = 1; // treshold
|
|
return oVal.slice(0, t) === tVal.slice(0, t) && levenshtein(oVal, tVal) < 3;
|
|
}}"
|
|
>
|
|
${lazyRender(
|
|
listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
|
|
)}
|
|
</lion-combobox>
|
|
`;
|
|
```
|
|
|
|
## Options
|
|
|
|
```js preview-story
|
|
export const showAllOnEmpty = () => html`
|
|
<lion-combobox
|
|
name="combo"
|
|
label="Show all on empty"
|
|
help-text="Shows all (options) on empty (textbox has no value)"
|
|
show-all-on-empty
|
|
>
|
|
${lazyRender(
|
|
listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
|
|
)}
|
|
</lion-combobox>
|
|
`;
|
|
```
|
|
|
|
### Changing defaults
|
|
|
|
By default `selection-follows-focus` will be true (aligned with the
|
|
wai-aria examples and the native `<datalist>`).
|
|
It is possible to disable this behavior, so the active/focused and checked/selected values
|
|
will be kept track of independently.
|
|
|
|
> Note that, (just like in a listbox), selection-follows-focus will never be applicable for
|
|
> multiselect comboboxes.
|
|
|
|
```js preview-story
|
|
export const noSelectionFollowsFocus = () => html`
|
|
<lion-combobox name="combo" label="No Selection Follows focus" .selectionFollowsFocus="${false}">
|
|
${lazyRender(
|
|
listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
|
|
)}
|
|
</lion-combobox>
|
|
`;
|
|
```
|
|
|
|
By default `rotate-keyboard-navigation` will be true (aligned with the
|
|
wai-aria examples and the natve `<datalist>`).
|
|
It is possible to disable this behavior, see example below
|
|
|
|
```js preview-story
|
|
export const noRotateKeyboardNavigation = () => html`
|
|
<lion-combobox
|
|
name="combo"
|
|
label="No Rotate Keyboard Navigation"
|
|
.rotateKeyboardNavigation="${false}"
|
|
>
|
|
${lazyRender(
|
|
listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
|
|
)}
|
|
</lion-combobox>
|
|
`;
|
|
```
|
|
|
|
## Multiple choice
|
|
|
|
Add `multiple-choice` flag to allow multiple values to be selected.
|
|
This will:
|
|
|
|
- keep the listbox overlay open on click of an option
|
|
- display a list of selected option representations next to the text box
|
|
- make the value of type `Array` instead of `String`
|
|
|
|
> Please note that the lion-combobox-selection-display below is not exposed and only serves
|
|
> as an example. The selection part of a multiselect combobox is not yet accessible. Please keep
|
|
> in mind that for now, as a Subclasser, you would have to take care of this part yourself.
|
|
|
|
```js preview-story
|
|
export const multipleChoice = () => html`
|
|
<lion-combobox name="combo" label="Multiple" multiple-choice>
|
|
<demo-selection-display
|
|
slot="selection-display"
|
|
style="display: contents;"
|
|
></demo-selection-display>
|
|
${lazyRender(
|
|
listboxData.map(
|
|
(entry, i) =>
|
|
html` <lion-option .choiceValue="${entry}" ?checked=${i === 0}>${entry}</lion-option> `,
|
|
),
|
|
)}
|
|
</lion-combobox>
|
|
`;
|
|
```
|
|
|
|
## Invoker button
|
|
|
|
```js preview-story
|
|
export const invokerButton = () => html`
|
|
<lion-combobox
|
|
.modelValue="${listboxData[1]}"
|
|
autocomplete="none"
|
|
name="combo"
|
|
label="Invoker Button"
|
|
@click="${({ currentTarget: el }) => {
|
|
el.opened = !el.opened;
|
|
}}"
|
|
>
|
|
<button slot="suffix" type="button" tabindex="-1">▼</button>
|
|
${lazyRender(
|
|
listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
|
|
)}
|
|
</lion-combobox>
|
|
`;
|
|
```
|
|
|
|
## Server interaction
|
|
|
|
It's possible to fetch data from server side. When options are rerendered into the combobox,
|
|
the autocompletion (highlighting/selecting etc.) functionality of the combobox is triggered.
|
|
|
|
```js preview-story
|
|
const comboboxData = ['lorem', 'ipsum', 'dolor', 'sit', 'amet'];
|
|
let rejectPrev;
|
|
/**
|
|
* @param {string} val
|
|
*/
|
|
function fetchMyData(val) {
|
|
if (rejectPrev) {
|
|
rejectPrev();
|
|
}
|
|
const results = listboxData.filter(item => item.toLowerCase().includes(val.toLowerCase()));
|
|
return new Promise((resolve, reject) => {
|
|
rejectPrev = reject;
|
|
setTimeout(() => {
|
|
resolve(results);
|
|
}, 1000);
|
|
});
|
|
}
|
|
class DemoServerSide extends LitElement {
|
|
static get properties() {
|
|
return { options: { type: Array } };
|
|
}
|
|
|
|
constructor() {
|
|
super();
|
|
/** @type {string[]} */
|
|
this.options = [];
|
|
}
|
|
|
|
get combobox() {
|
|
return /** @type {LionCombobox} */ (this.shadowRoot?.querySelector('#combobox'));
|
|
}
|
|
|
|
/**
|
|
* @param {InputEvent & {target: HTMLInputElement}} e
|
|
*/
|
|
async fetchMyDataAndRender(e) {
|
|
this.loading = true;
|
|
this.requestUpdate();
|
|
try {
|
|
this.options = await fetchMyData(e.target.value);
|
|
this.loading = false;
|
|
this.requestUpdate();
|
|
} catch (_) {}
|
|
}
|
|
|
|
render() {
|
|
return html`
|
|
<lion-combobox
|
|
.showAllOnEmpty="${true}"
|
|
id="combobox"
|
|
@input="${this.fetchMyDataAndRender}"
|
|
.helpText="Returned from server: [${this.options.join(', ')}]"
|
|
>
|
|
<label slot="label" aria-live="polite"
|
|
>Server side completion ${this.loading
|
|
? html`<span style="font-style: italic;">(loading...)</span>`
|
|
: ''}</label
|
|
>
|
|
${repeat(
|
|
this.options,
|
|
entry => entry,
|
|
entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `,
|
|
)}
|
|
</lion-combobox>
|
|
`;
|
|
}
|
|
}
|
|
customElements.define('demo-server-side', DemoServerSide);
|
|
export const serverSideCompletion = () => html`<demo-server-side></demo-server-side>`;
|
|
```
|
|
|
|
## Set complex object in choiceValue
|
|
|
|
A common use case is to set a complex object in the `choiceValue` property. By default, `LionCombobox` will display in the text input the `modelValue`. By overriding the `_getTextboxValueFromOption` method, you can choose which value will be used for the input value.
|
|
|
|
```js preview-story
|
|
class ComplexObjectCombobox extends LionCombobox {
|
|
/**
|
|
* Override how the input text is filled
|
|
* @param {LionOption} option
|
|
* @returns {string}
|
|
*/
|
|
// eslint-disable-next-line class-methods-use-this
|
|
_getTextboxValueFromOption(option) {
|
|
return option.label;
|
|
}
|
|
}
|
|
|
|
customElements.define('complex-object-combobox', ComplexObjectCombobox);
|
|
|
|
const onModelValueChanged = event => {
|
|
console.log(`event.target.modelValue: ${JSON.stringify(event.target.modelValue)}`);
|
|
};
|
|
|
|
const listboxDataObject = listboxData.map(e => {
|
|
return { label: e, name: e };
|
|
});
|
|
|
|
export const complexObjectChoiceValue = () => html` <complex-object-combobox
|
|
name="combo"
|
|
label="Display only the label once selected"
|
|
@model-value-changed="${onModelValueChanged}"
|
|
>
|
|
${lazyRender(
|
|
listboxDataObject.map(
|
|
entry =>
|
|
html`
|
|
<lion-option .choiceValue="${entry}" .label="${entry.label}">${entry.label}</lion-option>
|
|
`,
|
|
),
|
|
)}
|
|
</complex-object-combobox>`;
|
|
```
|
|
|
|
## Listbox compatibility
|
|
|
|
All configurations that can be applied to `lion-listbox`, can be applied to `lion-combobox` as well.
|
|
See the [listbox documentation](../listbox/overview.md) for more information.
|