[combobox] Add getValueFromItem prop

[atomiks]

• I have followed (at least) the PR section of the contributing guide.

Fixes #3865
Fixes #3951
Closes #3853

Smaller and more flexible alternative to #3954. This explicitly supports object items with primitive value.

<Combobox.Root> needs to know what is passed to <Combobox.Item item={...}> ahead of time regarding the shape of items. e.g. value could be a primitive string or number, or the whole item object. This new prop getValueFromItem lets it know explicitly.

This can't be inferred automatically except in two cases:

• { value, label } is the shape of the items objects
• defaultValue/value aren't null

getValueFromItem supports arbitrary object shapes and the initial null value.

<Combobox.Root> will error if getValueFromItem is missing an value/defaultValue don't match the shape of items:

// @ts-expect-error - primitive selected values with object items require `getValueFromItem`
<Combobox.Root items={objectItems} defaultValue="a" />;
// @ts-expect-error - primitive selected values with object items require `getValueFromItem`
<Combobox.Root items={objectItems} value="a" />;
// @ts-expect-error - primitive selected values with object items require `getValueFromItem`
<Combobox.Root items={numberObjectItems} defaultValue={1} />;
// @ts-expect-error - primitive selected values with object items require `getValueFromItem`
<Combobox.Root items={numberObjectItems} value={1} />;

This does require synchronizing <Combobox.Item value={...} and getValueFromItem together. I added a wrapper example in the spec file.

The getValueFromItem name is differentiated from the other mappers (itemToStringValue, itemToStringLabel) as those ones operate on item values, not item objects.

[pkg-pr-new]

• base-ui-tanstack-start

• vite-css-base-ui-example

  pnpm add https://pkg.pr.new/@base-ui/react@4097
  

  pnpm add https://pkg.pr.new/@base-ui/utils@4097
  

commit: 5dd5f3f

[mui-bot]

Bundle size report

Bundle	Parsed size	Gzip size
@base-ui/react	🔺+682B(+0.15%)	🔺+341B(+0.23%)

Details of bundle changes

---

Check out the code infra dashboard for more information about this PR.

[netlify]

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	5dd5f3f
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/6992c2fc2741a60008e9e5bb
😎 Deploy Preview	https://deploy-preview-4097--base-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.