Support secondary text on Combobox options

[rossnelson]

Adds an optional secondary line to combobox options, so an option can carry disambiguating context beneath its label.

What changed

• ComboboxOption takes an optional description, passed straight through to MenuItem.
• Combobox takes an optional optionDescriptionKey for custom (object) options, mirroring the existing optionValueKey / optionLabelKey pair. String options don't accept it — there's nothing to derive it from.
• New Custom Options With Descriptions story.

MenuItem already renders a styled description line (.menu-item-description), so this threads the existing primitive through rather than introducing new rendering. Styling, spacing and truncation come along for free.

Decisions worth a look

• Filtering still matches the label only, never the description. That keeps getDisplayValue as the single source of what a user is typing against. The new story asserts it, so if we ever want description-aware filtering it'll be a deliberate change with a failing test to update.
• Naming follows MenuItem (description) rather than something like secondaryText, so the prop means the same thing at both layers.
• Secondary text stays in the accessible name. It's meaningful content, and the axe run over the story reports no violations.

Verification

• pnpm check — 0 errors
• pnpm test -- --run — 3026 passed
• test-storybook scoped to Combobox — 15/15 play tests pass, no accessibility violations
• eslint, stylelint, prettier clean on the changed files

Context

Needed by FE-224 (namespace description in the cloud-ui namespace selector), but useful on its own. Tracked as FE-435.

Draft until reviewed — cloud-ui can't consume it until it's packed.

Note: fix/combobox-hint-text also touches combobox.svelte and combobox.stories.svelte. Different concern (hint text under the input), but worth landing in a deliberate order.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
holocene	Ready	Preview	Aug 26, 2026 5:51pm