[New component] Autocomplete

[bsvensson]

Check existing issues

• [x] I have checked for existing issues to avoid duplicates

Description

We would like the combobox component to support async data, actions, a menu for switching sources and have the ability to show a suggestion/autocomplete list.

Blocked issues: #8877

Acceptance Criteria

• [ ] Create Input search component https://github.com/Esri/calcite-design-system/issues/10186
• [ ] Support Maps SDK for JS' Search widget updated to use Calcite Components.
• [ ] Create autocomplete component (this issue)
• [ ] Deprecate filter component https://github.com/Esri/calcite-design-system/issues/10187

Relevant Info

Ask @driskull for details ;)

Which Component

calcite-combobox

Example Use Case

We are trying to move the Search widget to Calcite Components.

• Currently that widget use a filter component, combobox and input and neither handles searching dynamic data or has the ability to show a suggestion/autocomplete list. We would like enhancements to calcite-combobox to support this.

Priority impact

impact - p1 - need for current milestone

Calcite package

• [X] @esri/calcite-components
• [ ] @esri/calcite-components-angular
• [ ] @esri/calcite-components-react
• [ ] @esri/calcite-design-tokens
• [ ] @esri/eslint-plugin-calcite-components

Esri team

ArcGIS Maps SDK for JavaScript

CalciteAutocomplete

• Internally uses calcite-input
• When autocomplete items are populated and the input is clicked or ArrowUp/ArrowDown the component is opened. (open=true)
• Users perform some async search when the calciteAutocompleteTextInput event fires, populate the autocomplete list and open it if needed.
• Users listen to keydown (Enter) on the component or listen for a form submission to do a regular search.
• Handle use case: https://developers.arcgis.com/javascript/latest/sample-code/sandbox/?sample=widgets-search-multiplesource
• When a user selects an autocomplete item, a dev can listen for the event and choose to populate or clear the inputText value or not.
• Autocomplete results area has a live region with count of results.

Proposed HTML

<calcite-autocomplete open scale="m" value="1" input-value="Redlands, CA">
  <calcite-autocomplete-item value="1" heading="Redlands, CA"></calcite-autocomplete-item>
  <calcite-autocomplete-item value="2" heading="Redlands, CO, USA"></calcite-autocomplete-item>
  <calcite-autocomplete-item value="2" heading="Redlands, Dorset, England, GBR"></calcite-autocomplete-item>
  <calcite-autocomplete-item value="2" heading="Redlands, Wiltshire, England, GBR"></calcite-autocomplete-item>
  <calcite-button scale="s" slot="actions-start" icon-start="banana"></calcite-button>
  <calcite-button scale="s" slot="actions-end" icon-start="banana"></calcite-button>
</calcite-autocomplete>

Properties

All of the properties from calcite-input plus these additional properties:

• value: string; // the value of the selected auto complete item. (used for form submissions)
• inputValue: string; // the input text value.
• open: boolean;
• overlayPositioning: OverlayPositioning = "absolute";
• placement: Placement;
• flipPlacements: FlipPlacement[];
• messageOverrides: { label: string; clear: string; };

Events

• calciteAutocompleteTextChange: EventEmitter; // Fires each time a new value is typed and committed.
• calciteAutocompleteTextInput: EventEmitter; // Fires each time a new value is typed.
• calciteAutocompleteChange: EventEmitter; // Fires each time an autocomplete item is clicked.
• calciteAutocompleteBeforeClose: EventEmitter;
• calciteAutocompleteClose: EventEmitter;
• calciteAutocompleteBeforeOpen: EventEmitter;
• calciteAutocompleteOpen: EventEmitter;

Methods

• selectText()
• setFocus()

Slots

• (default): -A slot for adding calcite-autocomplete-item elements.
• actions-end - A slot for adding content after the input.
• actions-start - A slot for adding content before the input.
• content-bottom - A slot for adding content below calcite-autocomplete-item elements.
• content-top - A slot for adding content above calcite-autocomplete-item elements.

• CalciteAutocompleteItem

<calcite-autocomplete-item value="1" heading="Redlands, CA"></calcite-autocomplete-item>

Properties

• description: string;
• disabled = false;
• icon-start: IconNameOrString;
• icon-end: IconNameOrString;
• iconFlipRtl: FlipContext;
• heading: string;
• value!: any; // string?
• label: any;

Events

None

Methods

• None

Slots

• content-start - A slot for adding non-actionable elements before content of the component.
• content-end - A slot for adding non-actionable elements after content of the component.

CalciteAutocompleteItemGroup

<calcite-autocomplete-item-group heading="Locations"></calcite-autocomplete-item-group>

Properties

• heading: string;
• label: string;
• scale: Scale;

Events

None

Methods

• None

Slots

• default: slot for adding autocomplete items.

Figma Spec

In progress design spec for Autocomplete, Autocomplete Item, and Autocomplete Item Group. Will update as needed during development.

[driskull]

https://www.syncfusion.com/blogs/post/which-control-should-i-use-autocomplete-or-combobox

This article shows the difference between combobox and autocomplete.

[geospatialem]

Related for discussion: https://github.com/Esri/calcite-design-system/issues/8877

[driskull]

The aria-autocomplete attribute can be associated with the following roles: combobox, textbox, or searchbox.

https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete#associated_roles

[geospatialem]

+1 for ArcGIS Knowledge

[driskull]

@geospatialem can we repurpose this issue to "Add autocomplete component"?

We'll also need issues for:

• Add input-search component (ideally autocomplete would use this component + add autocomplete functionality)
• Deprecate filter once we have input-search and autocomplete components

[github-actions[bot]]

cc @ashetland, @SkyeSeitz, @brittneytewks