feat: sections/groups

[timc1]

Alternative solution to #49.
Closes #36.

Background

While working on the initial version of groups, I noticed the current API required too much leg work for the consumer; i.e., currently a developer can import the standard KBarResults component, which handles everything from keyboard navigation to rendering results.

However, if you wanted to segment results by groups, you'd have to write a component from scratch handling all pointer and keyboard events that KBarResults had built in. This requires the developer to write a lot of code – index management, event listeners, coordinating values from useKBar, etc.

For example, #49 introduced another component, KBarGroupedResults, but what happens when more feature requests roll in? How do we build an API that can easily enable developers to create any type of result view that they want, with all the complexity abstracted away?

Solution

From a high level, we want to:

• Expose a very simple API
• Implicitly handle index management, keyboard events so the developer does not have to

If a developer wanted to build sectioned/grouped results, they would do this:

return (
  <Results>
    <div>
      <p>Group 1</p>
      <ResultItem /> 
      <ResultItem /> 
    </div>
    <div>
      <p>Group 2</p>
      <ResultItem />
    </div>
  </Results>
)

wherein ResultItem can be rendered anywhere within Results, and events and index management will be implicitly handled.

We will introduce a few components/hooks:

useMatches: () => ActionGroup[]

This hook uses match-sorter under the hood to take the current list of actions and search query, and returns a filtered list of actions grouped by their action.section value. Additionally, as match-sorter returns a new object on every call, we slightly throttle the call to improve the overall search performance.

Results: ({ children }: { children: React.ReactNode }) => JSX.Element

All results must be wrapped with this components, which leverages a simple context implementation which implicitly handles all keyboard/pointer events alongside an index management solution inspired by @reach/descendants and use-descendants.

useResultItem: (action: Action) => { index: number; active: boolean; handlers: any; }

Every result rendered will need to use this hook, which works alongside Results to get the current index, whether it is active, and and event handlers that need to be spread onto the result.

function ResultItem(action: Action) {
  const { active, handlers } = useResultItem({ action });
  return (
    <div 
      style={{
        background: active ? "#eee" : "none"
      }}
      {...handlers}
    >
      {action.name}
    </div> 
  );
}

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/timc/kbar/HkiZDG9FGSGNo7e5smKjSMQXaeZ3
✅ Preview: https://kbar-git-feat-improved-results-timc.vercel.app

[timc1]

Updates index for all nested useResultItems whenever children rerenders.

[timc1]

TODO: Make sure results are visible to screen readers.

[tommoor]

My main bit of feedback on the interface is it seems like there is an implicit dependency between Results component and useMatches hook introduced here.

Would there be a downside of making Results expect a functional child that gets passed the results? This would prevent a couple of easy to make mistakes and self-document a little better:

return (
  <Results>
    {(groupedResults) => 
      groupedResults.map(...)
    }
  </Results>
)

[timc1]

My main bit of feedback on the interface is it seems like there is an implicit dependency between Results component and useMatches hook introduced here.

Would there be a downside of making Results expect a functional child that gets passed the results? This would prevent a couple of easy to make mistakes and self-document a little better:

We should keep the matches and Results/useResultItem separate – useMatches is a helper hook that will return a set of grouped results, but the user could just calculate their own results if they wanted to