feat(core-ui): Allow searchMatcher to return a score for result ordering (#108719)

Stacked on #108714.

Extends the `searchMatcher` prop introduced in the base PR so it can
optionally return a `SearchMatchResult` object in addition to a plain
`boolean`.

```ts
interface SearchMatchResult {
  score: number;
}
```

When a matcher returns `SearchMatchResult`, the option is shown and its
`score` is used to sort matching options — higher scores appear first.
Returning `false` still hides the option. Returning `true` (the existing
behaviour) shows it with no ordering influence, so the change is fully
additive.

---

**Update**: `searchMatcher` now always returns `SearchMatchResult` — the
`boolean` return path is removed. A score > 0 means the option matches;
score <= 0 hides it. The default implementation returns `{score: 1}` for
a substring match and `{score: 0}` otherwise. Sorting is only triggered
when a custom `searchMatcher` is provided, so the default path pays no
extra cost.

Sorting is scoped: within each section for sectioned lists, and globally
for flat lists. Options with equal scores maintain their original
relative order (stable sort).

The `SearchMatchResult` type and the new `getSortedItems` utility are
exported from the package for callers building custom composite selects.

---------

Co-authored-by: Claude <[email protected]>

Author: 2 people

static/app/components/core/compactSelect/compactSelect.spec.tsx

@@ -518,7 +518,9 @@ describe('CompactSelect', () => {
         <CompactSelect
           searchable
           searchPlaceholder="Search here…"
-          searchMatcher={(option, search) => String(option.value).endsWith(search)}
+          searchMatcher={(option, search) => ({
+            score: String(option.value).endsWith(search) ? 1 : 0,
+          })}
           options={[
             {value: 'opt_one', label: 'Option One'},
             {value: 'opt_two', label: 'Option Two'},
@@ -537,6 +539,33 @@ describe('CompactSelect', () => {
       expect(screen.queryByRole('option', {name: 'Option Two'})).not.toBeInTheDocument();
     });
 
+    it('does not call searchMatcher when search is empty, showing all options', async () => {
+      // A matcher that returns score 0 for any empty query would hide all options if
+      // called during the initial render (before the user types anything).
+      render(
+        <CompactSelect
+          searchable
+          searchPlaceholder="Search here…"
+          searchMatcher={(option, search) => ({
+            // Return 0 for empty search — real-world matchers may do this
+            score: search === '' ? 0 : String(option.value).includes(search) ? 1 : 0,
+          })}
+          options={[
+            {value: 'opt_one', label: 'Option One'},
+            {value: 'opt_two', label: 'Option Two'},
+          ]}
+          value={undefined}
+          onChange={jest.fn()}
+        />
+      );
+
+      await userEvent.click(screen.getByRole('button'));
+
+      // All options should be visible even though the matcher returns 0 for ''
+      expect(screen.getByRole('option', {name: 'Option One'})).toBeInTheDocument();
+      expect(screen.getByRole('option', {name: 'Option Two'})).toBeInTheDocument();
+    });
+
     it('uses string.includes for default search matching', async () => {
       render(
         <CompactSelect
@@ -560,6 +589,123 @@ describe('CompactSelect', () => {
       expect(screen.queryByRole('option', {name: 'Option Two'})).not.toBeInTheDocument();
     });
 
+    it('sorts options by score when searchMatcher returns SearchMatchResult', async () => {
+      // Assign scores so the natural order (One, Two, Three) is reversed: Three > Two > One
+      const scores: Record<string, number> = {opt_one: 1, opt_two: 2, opt_three: 3};
+
+      render(
+        <CompactSelect
+          searchable
+          searchPlaceholder="Search here…"
+          searchMatcher={option => ({score: scores[String(option.value)] ?? 0})}
+          options={[
+            {value: 'opt_one', label: 'Option One'},
+            {value: 'opt_two', label: 'Option Two'},
+            {value: 'opt_three', label: 'Option Three'},
+          ]}
+          value={undefined}
+          onChange={jest.fn()}
+        />
+      );
+
+      await userEvent.click(screen.getByRole('button'));
+      await userEvent.click(screen.getByPlaceholderText('Search here…'));
+      await userEvent.keyboard('opt');
+
+      const options = screen.getAllByRole('option');
+      expect(options[0]).toHaveTextContent('Option Three'); // score 3
+      expect(options[1]).toHaveTextContent('Option Two'); // score 2
+      expect(options[2]).toHaveTextContent('Option One'); // score 1
+    });
+
+    it('options with equal scores maintain their original relative order', async () => {
+      // opt_two gets a higher score; opt_one and opt_three share the same low score
+      // and should keep their original relative order (One before Three)
+      render(
+        <CompactSelect
+          searchable
+          searchPlaceholder="Search here…"
+          searchMatcher={option => ({score: option.value === 'opt_two' ? 10 : 1})}
+          options={[
+            {value: 'opt_one', label: 'Option One'},
+            {value: 'opt_two', label: 'Option Two'},
+            {value: 'opt_three', label: 'Option Three'},
+          ]}
+          value={undefined}
+          onChange={jest.fn()}
+        />
+      );
+
+      await userEvent.click(screen.getByRole('button'));
+      await userEvent.click(screen.getByPlaceholderText('Search here…'));
+      await userEvent.keyboard('opt');
+
+      const options = screen.getAllByRole('option');
+      expect(options[0]).toHaveTextContent('Option Two'); // score 10
+      expect(options[1]).toHaveTextContent('Option One'); // no score, original order
+      expect(options[2]).toHaveTextContent('Option Three'); // no score, original order
+    });
+
+    it('sizeLimit keeps highest-scored options visible, not first-in-order options', async () => {
+      // Natural order: One (score 1), Two (score 3), Three (score 2).
+      // sizeLimit=2 should keep the two highest-scored items: Two (3) and Three (2),
+      // not the first two in original order: One (1) and Two (3).
+      const scores: Record<string, number> = {opt_one: 1, opt_two: 3, opt_three: 2};
+
+      render(
+        <CompactSelect
+          searchable
+          searchPlaceholder="Search here…"
+          sizeLimit={2}
+          searchMatcher={option => ({score: scores[String(option.value)] ?? 0})}
+          options={[
+            {value: 'opt_one', label: 'Option One'},
+            {value: 'opt_two', label: 'Option Two'},
+            {value: 'opt_three', label: 'Option Three'},
+          ]}
+          value={undefined}
+          onChange={jest.fn()}
+        />
+      );
+
+      await userEvent.click(screen.getByRole('button'));
+      await userEvent.click(screen.getByPlaceholderText('Search here…'));
+      await userEvent.keyboard('opt');
+
+      const options = screen.getAllByRole('option');
+      expect(options).toHaveLength(2);
+      expect(options[0]).toHaveTextContent('Option Two'); // score 3, visible
+      expect(options[1]).toHaveTextContent('Option Three'); // score 2, visible
+      expect(screen.queryByRole('option', {name: 'Option One'})).not.toBeInTheDocument(); // score 1, hidden
+    });
+
+    it('passes option and search string to searchMatcher', async () => {
+      const searchMatcher = jest.fn().mockReturnValue({score: 1});
+
+      render(
+        <CompactSelect
+          searchable
+          searchPlaceholder="Search here…"
+          searchMatcher={searchMatcher}
+          options={[
+            {value: 'opt_one', label: 'Option One'},
+            {value: 'opt_two', label: 'Option Two'},
+          ]}
+          value={undefined}
+          onChange={jest.fn()}
+        />
+      );
+
+      await userEvent.click(screen.getByRole('button'));
+      await userEvent.click(screen.getByPlaceholderText('Search here…'));
+      await userEvent.keyboard('test');
+
+      expect(searchMatcher).toHaveBeenCalledWith(
+        expect.objectContaining({value: 'opt_one', label: 'Option One'}),
+        'test'
+      );
+    });
+
     it('can search with sections', async () => {
       render(
         <CompactSelect
@@ -1022,7 +1168,9 @@ describe('CompactSelect', () => {
           grid
           searchable
           searchPlaceholder="Search here…"
-          searchMatcher={(option, search) => String(option.value).endsWith(search)}
+          searchMatcher={(option, search) => ({
+            score: String(option.value).endsWith(search) ? 1 : 0,
+          })}
           options={[
             {value: 'opt_one', label: 'Option One'},
             {value: 'opt_two', label: 'Option Two'},

static/app/components/core/compactSelect/control.tsx

@@ -33,7 +33,12 @@ import useOverlay from 'sentry/utils/useOverlay';
 import usePrevious from 'sentry/utils/usePrevious';
 
 import type {SingleListProps} from './list';
-import type {SelectKey, SelectOptionOrSection, SelectOptionWithKey} from './types';
+import type {
+  SearchMatchResult,
+  SelectKey,
+  SelectOptionOrSection,
+  SelectOptionWithKey,
+} from './types';
 
 // autoFocus react attribute is sync called on render, this causes
 // layout thrashing and is bad for performance. This thin wrapper function
@@ -68,7 +73,10 @@ interface ControlContextValue {
   /**
    * Custom function to determine whether an option matches the search query.
    */
-  searchMatcher?: (option: SelectOptionWithKey<SelectKey>, search: string) => boolean;
+  searchMatcher?: (
+    option: SelectOptionWithKey<SelectKey>,
+    search: string
+  ) => SearchMatchResult;
   size?: FormSize;
 }
 
@@ -180,10 +188,13 @@ export interface ControlProps
   /**
    * Custom function to determine whether an option matches the search query (applicable
    * only when `searchable` is true). Receives the option and the current search string,
-   * and should return true if the option matches. If not provided, defaults to
-   * case-insensitive substring matching on `textValue` or `label`.
+   * and must return a `SearchMatchResult`. A score greater than 0 means the option
+   * matches; options with higher scores are sorted first.
    */
-  searchMatcher?: (option: SelectOptionWithKey<SelectKey>, search: string) => boolean;
+  searchMatcher?: (
+    option: SelectOptionWithKey<SelectKey>,
+    search: string
+  ) => SearchMatchResult;
   /**
    * The search input's placeholder text (applicable only when `searchable` is true).
    */

static/app/components/core/compactSelect/list.tsx

@@ -23,6 +23,7 @@ import {
   getEscapedKey,
   getHiddenOptions,
   getSelectedOptions,
+  getSortedItems,
   HiddenSectionToggle,
   shouldCloseOnSelect,
 } from './utils';
@@ -177,11 +178,16 @@ export function List<Value extends SelectKey>({
   const {overlayState, search, searchable, overlayIsOpen, searchMatcher} =
     useContext(ControlContext);
 
-  const hiddenOptions = useMemo(
+  const {hidden: hiddenOptions, scores} = useMemo(
     () => getHiddenOptions(items, search, sizeLimit, searchMatcher),
     [items, search, sizeLimit, searchMatcher]
   );
 
+  const sortedItems = useMemo(
+    () => (searchMatcher && scores.size > 0 ? getSortedItems(items, scores) : items),
+    [items, scores, searchMatcher]
+  );
+
   /**
    * Props to be passed into useListState()
    */
@@ -250,7 +256,7 @@ export function List<Value extends SelectKey>({
   const listState = useListState({
     ...props,
     ...listStateProps,
-    items,
+    items: sortedItems,
   });
 
   // In composite selects, focus should seamlessly move from one region (list) to

static/app/components/core/compactSelect/types.tsx

@@ -38,6 +38,20 @@ export type SelectOptionOrSection<Value extends SelectKey> =
   | SelectOption<Value>
   | SelectSection<Value>;
 
+/**
+ * The result of a custom `searchMatcher` function. Returning this (instead of a plain
+ * boolean) allows callers to influence how matching options are sorted: options with a
+ * higher `score` are shown first. To hide an option, return `{score: 0}.
+ */
+export interface SearchMatchResult {
+  /**
+   * Match quality score. Higher values cause the option to appear earlier in the list.
+   * Options that match but return no score maintain their original order relative to
+   * each other.
+   */
+  score: number;
+}
+
 export interface SelectOptionWithKey<
   Value extends SelectKey,
 > extends SelectOption<Value> {