[Select]: new API

[fabien-ml]

• Status: Published
• Start Date: 2023-02-03
• Target release: v0.7.0
• Authors: @fabien-ml

Summary

Currently Select.Root is responsible for managing the selection state of the component, in order to do that Select.Root needs to be aware of all it's child Select.Item.

Motivation

Wille the current implementation has a good Developer eXperience in terms of "writing" the component, there are some drawbacks related to the way it's designed :

• Every Select.Item needs to be mounted and register themselves to Select.Root which lead to poor performance when using large dataset (ex: 2000 items).
• The Select.Content is always mounted even if the user never open the Select.
• The component slow down page load when having multiple Select or Select with large collection of items in a page.
• The component is not compatible with virtual list solution out there since Select.Root needs to know every Select.Item but virtual list solution only render a part of the collection.

Goal

• Being able to use virtual scroll solution to improve performance on large dataset.
• The Select.Content keep unmounted when not opened.
• The component don't affect page load.

Detailed Design

The proposed solution is to provide an external "data source" as the single source of truth and not relying on the DOM and Select.Item registration to make Select.Root aware of all items.

API

• Select.Root will have the following props:

Name	Description
options	T[] | () => T[] An array of options to display as the available options.
optionValue	string | (option: T) => string Property name or getter function to use as the value of an option, defaults to the option itself when not defined.
optionTextValue	string | (option: T) => string Property name or getter function to use as the text value of an option for typeahead purpose, defaults to the option itself when not defined.
optionDisabled	string | (option: T) => boolean Property name or getter function to use as the disabled flag of an option, defaults to false when not defined.
optionGroupChildren	string | (optGroup: T) => T[] Property name or getter function that refers to the children options of option group.

Internally Kobalte will use the options prop to build a flatten array of CollectionItem which is an abstraction over user's provided option/group data.

• The CollectionItem<T> interface has the following properties:

Name	Description
type	'item' | 'section' The type of the item.
key	string The unique key for the item.
textValue	string The string value for the item, used for feature like typeahead.
isDisabled	boolean Whether the item is disabled.
level	number The level of depth the item is at (ex: when the item is built from an option part of an option group).
rawValue	T The option/group this item was created from.

Note

For "section" type, key, textValue and isDisabled values will be empty string and false as they are not relevant for this item type.

• Select.Listbox will accept a children render prop which will give access to each CollectionItem.

Usage

The following use case show how to deal with a data source containing a mix of plain and grouped options.

An option is described as an object structure, the final API will have equivalent for dealing with string based options.

import { Select } from "@kobalte/core";

const options = [
  // Plain
  {
    id: "dog",
    textValue: "Dog",
    label: "🐶 Dog",
    disabled: false
  },
  {
    id: "cat",
    textValue: "Cat",
    label: "🐱 Cat",
    disabled: false
  },
  // Grouped
  {
    label: "Fruits",
    options: [
      {
        id: "apple",
        textValue: "Apple",
        label: "🍎 Apple",
        disabled: false
      },
      {
        id: "banana",
        textValue: "Banana",
        label: "🍌 Banana",
        disabled: false
      },
      {
        id: "grapes",
        textValue: "Grapes",
        label: "🍇 Grapes",
        disabled: true
      }
    ]
  }
];

function App() {
  return (
    <Select.Root
      options={options}
      optionValue="id" /* or `optionValue={option => option.id}` */
      optionTextValue="textValue" /* or `optionTextValue={option => option.textValue}` */
      optionDisabled="disabled" /* or `optionDisabled={option => option.disabled}` */
      optionGroupChildren="options" /* or `optionGroupChildren={optGroup => optGroup.options}` */
    >
      <Select.Trigger>
        <Select.Value>
          {selectedItem => selectedItem.rawValue.label}
        </Select.Value>
      </Select.Trigger>
      <Select.Portal>
        <Select.Content>
          <Select.Listbox>
            {item => (
              <Switch>
                <Match when={item.type === "section"}>
                  <Select.Section>{item.rawValue.label}</Select.Section>
                </Match>
                <Match when={item.type === "item"}>
                  <Select.Item item={item}>{item.rawValue.label}</Select.Item>
                </Match>
              </Switch>
            )}
          </Select.Listbox>
        </Select.Content>
      </Select.Portal>
    </Select.Root>
  );
}

Note

For multi-select, MultiSelect.Value will expose the selected items in it's children render prop as a CollectionItem[].

The Select.Section component

Select.Section is a syntactic sugar component used to render a presentational <li> which is ignored by screen readers and keyboard navigation. The common use case will be for rendering the label of your option group.

The Select.Item component

Select.Item is the component that represent a selectable option. It is visible by screen readers and support keyboard navigation.

FAQs

Will Kobalte provide a built-in virtual scroll solution ?

Not in the initial release, however a port of React Aria Virtualizer is planned.

Will Select support nested option group ?

No, Kobalte will follows the default html <select> behavior, meaning you can't nest <optgroup>.

Related Discussions

• #59
• #71

Appendix

• Edit (2023-02-07): based on [Select]: new API #109 (comment)
• Edit (2023-02-03): based on [Select]: new API #109 (comment)

[thetarnav]

Looks good 👍
Still don't get the importance of keys here when Solid prefers mutable updates and keeping references intact. If strings are important then a WeakMap<object, string> with id-generation should help.

---

Also what would happen if I had a store for the items:

const [options, setOptions] = createStore([
  {
    id: "apple",
    textValue: "Apple",
    label: "🍎 Apple",
    disabled: false,
  },
  // ...
])

// and updated the displayed value
setOptions(0, "label", "🍎 Apple 🍎")

would it mean diffing all the items to figure out what's changed?
I guess that's more on the implementation - the API would allow for it

---

What would virtualization API look like? is it something that user does on his own, or would this be a part of the <Select> that you toggle.
Because this seems limited to how <Select.Listbox> will handle it:

<Select.Content>
  <Select.Listbox>{node => <Select.Item node={node} />}</Select.Listbox>
</Select.Content>

Where I would expect:

<Select.Content>
  {(nodes, container) => (
    <MyVirtualFor each={nodes()} container={container}>
      {node => <Select.Item node={node} />}
    </MyVirtualFor>
  )}
</Select.Content>

But I guess this is for the library to handle. Just how this could be done so that it's tree-shakeable?

---

How do I listen for the value changes?
onValueChange seems taken by the createListData

---

I think that this

{
  getLabel: item => item.label
}

could be replaced with this:

<Select.Item node={node} label={node.label} />

Idk, it feels better to keep rendering/displaying parts in JSX rather than the data structure. Although keeping the label strings there is sound.

---

shouldn't the list or tree object return selectedNodes rather than selectedKeys?

---

Can't think of more things. Cheers :D

[fabien-ml]

Maybe the naming is wrong but key is the value of the option/item that get submitted with forms.

It's named key because the name convey that it has to be unique.

If I rely on object instead of a simple string I need to rewrite almost all components that use collection and need to ask the user how to check equality of two objects when providing a data source.

---

For the "store" question, I've planned to use solid-primitives <Key> internally instead of <For> since the collection uniqueness is key based. Not sure if it answer your question.

---

For virtualization I plan to port react-aria <Virtualizer> because it's the one that provide best a11y and keyboard navigation support with my API (which is also react-aria based).
I've tested @tanstack/virtual, it works but I had problems with a11y and keyboard navigation.

---

Good question, maybe createListData should only handle the creation of "nodes" and not manage selection.

---

If I remove getLabel you will have to do node.rawValue.<your-label-attr-name>

---

If createListData doesn't manage selection selectedKeys doesn't exist.

[fabien-ml]

@thetarnav i've updated the API proposal based on your feedback.

[martinpengellyphillips]

Looks good. +1 on separating out the source of truth for the data rather than building through registration.

Couple of thoughts:

1. "used for features like typeahead." I'm curious about the planned implementation here? Will it be more like solid-select where it is createListData that handles all the filtering logic and updates items() accordingly? Or will it be internal to the Select itself (an internal filtered data structure)?

2. getValue might be a clearer name for getKey (if the intention is that this is the value used in forms).

3. Is it intended that only one level of grouping be supported?

4. In general, I'm not sure about the approach to 'groups'. The JSX structure seems tightly coupled to the data structure, meaning that if I change from a plain list to groups I have to update the JSX. Would be good to avoid that. Could groups be special items (can't be selected and are skipped in navigation) in a flat list structure instead? 🤔

5. Group items should likely match general items more closely. E.g. why have name for groups, but label for items. Can I disable a whole group with a disabled property etc.

[fabien-ml]

1. "typeahead" refers to the ability to move to an item when typing letters (ex: typing "Ap" focus "Apple"). In Select it's not a search/filtering feature which will be in the Combobox component.

2. agree

3. In theory it's possible to have more that one level of depth, i've also thought about using only one primitive and allow mixing group and plain items in the same data source. But internally I have to find a way to check if an item from the datasource is an "item" or a "group".

4. I think we can do something like this, which is correct from an a11y point of view and work with keyboard navigation.
   But it's not really a "group" in the DOM, just a sort of "text separator" :

import { createTreeData, Select } from "@kobalte/core";
import { Switch, Match } from "solid-js";

const items = createTreeData({
  dataSource: [
    {
      name: "Fruits",
      options: ["Apple", "Banana", "Grapes"],
    },
    {
      name: "Vegetables",
      options: ["Aubergine", "Broccoli", "Carrot"],
    },
    {
      name: "Meat",
      options: ["Beef", "Chicken", "Pork"],
    },
  ],
  getChildItems: item => item.options,
});

function App() {
  return (
    <Select.Root items={items()}>
      <Select.Trigger />
      <Select.Portal>
        <Select.Content>
          <Select.Listbox>
            {item => (
              <Switch>
                <Match when={item.type === "group"}>
                  <li role="presentation">
                    <span aria-hidden="true">{item.rawValue.name}</span>
                  </li>
                </Match>
                <Match when={item.type === "item"}>
                  <Select.Item item={item}>{item.rawValue}</Select.Item>
                </Match>
              </Switch>
            )}
          </Select.Listbox>
        </Select.Content>
      </Select.Portal>
    </Select.Root>
  );
}

Internally Kobalte will transform the dataSource :

[
  {
    name: "Fruits",
    options: ["Apple", "Banana", "Grapes"],
  },
  {
    name: "Vegetables",
    options: ["Aubergine", "Broccoli", "Carrot"],
  },
  {
    name: "Meat",
    options: ["Beef", "Chicken", "Pork"],
  },
]

Into a CollectionItem<T>[] which may look like this :

[
  {
    type: "group",
    rawValue: {
      name: "Fruits",
      options: ["Apple", "Banana", "Grapes"],
    },
  },
  {
    type: "item",
    rawValue: "Apple",
  },
  {
    type: "item",
    rawValue: "Banana",
  },
  {
    type: "item",
    rawValue: "Grapes",
  },
  // etc...
]

5. If you talk about the "name" attribute in dataSource or .rawValue.name, this is the data coming from the user not the data structure of a Kobalte CollectionItem.

Group items should likely match general items more closely.

I think i can go further that say that a "group" is just an item with a "childItems" attribute or something like that and internally handle the logic for disabling the whole group, etc.

[martinpengellyphillips]

Curious:

• Is label used to render selected value as well?
• Do options get passed their selected state in the list? E.g. If I wanted to render a checkbox there for multi select.

[fabien-ml]

• I don't know if I should add an optionLabel and optionGroupLabel props to Select.Root to get the label from the user data, or if Select.Value should expose all selected items in a render prop and the user do it's thing with item.rawValue.*
• You can use the Select.ItemIndicator which is rendered when the item is selected to visually indicate the "selected" state. I need to think about how to pass this state.

[martinpengellyphillips]

• I think consistency makes sense - so expose render prop. This will need consideration of mutli vs single value rendering though - essentially whether the component decides to always pass value as an array of Values or not. In solid-select I made value a single entry for non-multiple and relied upon testing 'props.multiple' to determine what to render. It might be good to write out that api example for clarity.
• 👍

[fabien-ml]

In Kobalte there are two distinct Select components so:

• Select.Value will expose the selected item in its children render prop
• MultiSelect.Value will expose an array of selected items in its children render prop

[fabien-ml]

Released in v0.7.0, however I had to change a bit the API for a better Typescript support.