[EuiComboBox] Added sortMatchesBy prop

CHANGELOG.md

@@ -1,5 +1,6 @@
 ## [`master`](https://github.com/elastic/eui/tree/master)
 
+- Added `startingWith` prop for `EuiComboBox` ([#3089](https://github.com/elastic/eui/pull/3089))
 - Added props descriptions for `EuiComboBox` ([#3007](https://github.com/elastic/eui/pull/3007))
 - Exported `dateFormatAliases` as a part of the public API ([#3043](https://github.com/elastic/eui/pull/3043))
 - Exported `EuiTextProps` type definition ([#3039](https://github.com/elastic/eui/pull/3039))

src-docs/src/views/combo_box/combo_box_example.js

@@ -59,6 +59,10 @@ import Disabled from './disabled';
 const disabledSource = require('!!raw-loader!./disabled');
 const disabledHtml = renderToHtml(Disabled);
 
+import StartingWith from './startingWith';
+const startingWithSource = require('!!raw-loader!./startingWith');
+const startingWithHtml = renderToHtml(StartingWith);
+
 export const ComboBoxExample = {
   title: 'Combo Box',
   intro: (
@@ -347,5 +351,27 @@ export const ComboBoxExample = {
       props: { EuiComboBox },
       demo: <Async />,
     },
+    {
+      title: 'Starting With',
+      source: [
+        {
+          type: GuideSectionTypes.JS,
+          code: startingWithSource,
+        },
+        {
+          type: GuideSectionTypes.HTML,
+          code: startingWithHtml,
+        },
+      ],
+      text: (
+        <p>
+          Use the
+          <EuiCode>startingWith</EuiCode> prop to let the options that start
+          with the query be displayed on the top of the list.
+        </p>
+      ),
+      props: { EuiComboBox },
+      demo: <StartingWith />,
+    },
   ],
 };

src-docs/src/views/combo_box/startingWith.js

@@ -0,0 +1,97 @@
+import React, { Component } from 'react';
+
+import { EuiComboBox } from '../../../../src/components';
+
+export default class extends Component {
+  constructor(props) {
+    super(props);
+
+    this.options = [
+      {
+        label: 'Titan',
+        'data-test-subj': 'titanOption',
+      },
+      {
+        label: 'Enceladus is disabled',
+        disabled: true,
+      },
+      {
+        label: 'Mimas',
+      },
+      {
+        label: 'Dione',
+      },
+      {
+        label: 'Iapetus',
+      },
+      {
+        label: 'Phoebe',
+      },
+      {
+        label: 'Rhea',
+      },
+      {
+        label:
+          "Pandora is one of Saturn's moons, named for a Titaness of Greek mythology",
+      },
+      {
+        label: 'Tethys',
+      },
+      {
+        label: 'Hyperion',
+      },
+    ];
+
+    this.state = {
+      selectedOptions: [this.options[2], this.options[4]],
+    };
+  }
+
+  onChange = selectedOptions => {
+    this.setState({
+      selectedOptions,
+    });
+  };
+
+  onCreateOption = (searchValue, flattenedOptions) => {
+    const normalizedSearchValue = searchValue.trim().toLowerCase();
+
+    if (!normalizedSearchValue) {
+      return;
+    }
+
+    const newOption = {
+      label: searchValue,
+    };
+
+    // Create the option if it doesn't exist.
+    if (
+      flattenedOptions.findIndex(
+        option => option.label.trim().toLowerCase() === normalizedSearchValue
+      ) === -1
+    ) {
+      this.options.push(newOption);
+    }
+
+    // Select the option.
+    this.setState(prevState => ({
+      selectedOptions: prevState.selectedOptions.concat(newOption),
+    }));
+  };
+
+  render() {
+    const { selectedOptions } = this.state;
+    return (
+      <EuiComboBox
+        startingWith={true}
+        placeholder="Select or create options"
+        options={this.options}
+        selectedOptions={selectedOptions}
+        onChange={this.onChange}
+        onCreateOption={this.onCreateOption}
+        isClearable={true}
+        data-test-subj="demoComboBox"
+      />
+    );
+  }
+}

src/components/combo_box/combo_box.tsx

@@ -110,6 +110,10 @@ interface _EuiComboBoxProps<T>
    * When `true` only allows the user to select a single option. Set to `{ asPlainText: true }` to not render input selection as pills
    */
   singleSelection: boolean | EuiComboBoxSingleSelectionShape;
+  /**
+   * Display matching options that start with search value on top of the list
+   */
+  startingWith?: boolean;
   /**
    * Creates an input group with element(s) coming before input. It won't show if `singleSelection` is set to `false`.
    * `string` | `ReactElement` or an array of these
@@ -170,6 +174,7 @@ export class EuiComboBox<T> extends Component<
     singleSelection: false,
     prepend: null,
     append: null,
+    startingWith: false,
   };
 
   state: EuiComboBoxState<T> = {
@@ -779,6 +784,7 @@ export class EuiComboBox<T> extends Component<
           );
         }
       }
+
       this.setState({
         matchingOptions: newMatchingOptions,
         activeOptionIndex: nextActiveOptionIndex,
@@ -841,6 +847,7 @@ export class EuiComboBox<T> extends Component<
       singleSelection,
       prepend,
       append,
+      startingWith,
       ...rest
     } = this.props;
     const {
@@ -850,8 +857,30 @@ export class EuiComboBox<T> extends Component<
       listPosition,
       searchValue,
       width,
+      matchingOptions,
     } = this.state;
 
+    let newMatchingOptions = matchingOptions;
+
+    if (startingWith) {
+      const refObj: {
+        startWith: Array<EuiComboBoxOptionOption<T>>;
+        others: Array<EuiComboBoxOptionOption<T>>;
+      } = { startWith: [], others: [] };
+
+      newMatchingOptions.forEach(object => {
+        if (
+          object.label
+            .toLowerCase()
+            .startsWith(searchValue.trim().toLowerCase())
+        ) {
+          refObj.startWith.push(object);
+        } else {
+          refObj.others.push(object);
+        }
+      });
+      newMatchingOptions = [...refObj.startWith, ...refObj.others];
+    }
     // Visually indicate the combobox is in an invalid state if it has lost focus but there is text entered in the input.
     // When custom options are disabled and the user leaves the combo box after entering text that does not match any
     // options, this tells the user that they've entered invalid input.
@@ -887,7 +916,7 @@ export class EuiComboBox<T> extends Component<
             fullWidth={fullWidth}
             isLoading={isLoading}
             listRef={this.listRefCallback}
-            matchingOptions={this.state.matchingOptions}
+            matchingOptions={newMatchingOptions}
             onCloseList={this.closeList}
             onCreateOption={onCreateOption}
             onOptionClick={this.onOptionClick}