[Bug]: Dropdown does not function as expected and docs need to illustrate basic actual usage.

[dzearing]

Component

Dropdown

Package version

latest v9

React version

17

Environment

Edge, @fluentui/react-components latest, react 17.

Current Behavior

Given this:

<Dropdown value={0} onChange={ (value) => console.log(value); }>
   <Option value={0}>Text for 0</Option>
   <Option value={1}>Text for 1</Option>
   <Option value={2}>Text for 2</Option>
</Dropdown>

Expectations/Results:

• We should be displaying "Text for 0" but instead, the value 0 is displayed as the selected item.
• There should be a single way to specify the selected item - not 2. Either value or selectedOptions but not both. Pick one. Provide examples in documentation.
• There should be a single event fired when selection changes, but not 2. Pick one. Provide examples in documentation.
• Went to the controlled component usage example in docs - the first thing you see is uncontrolled usage example. What?

Expected Behavior

See all of the behaviors above.

Reproduction

https://stackblitz.com/edit/osrzayhe-mnd1lovb?file=src%2Fexample.tsx

Steps to reproduce

1. Use the actual component in a product as a controlled component. Don't know how to listen for change events or select a default value? Read the docs.
2. Try not to get frustrated.

Please fix! It's a beautiful component, just has some significant ergonomics and docs issues right now.

Are you reporting an Accessibility issue?

None

Suggested severity

Urgent - No workaround and Products/sites are affected

Products/sites affected

No response

Are you willing to submit a PR to fix?

yes

Validations

• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• The provided reproduction is a minimal reproducible example of the bug.

[ValentinaKozlova]

From your expectations description it looks like change request, not a bug. I'm afraid API won't be changed.
But I agree that documentation can be improved.
Also, not sure if severity is urgent in this case :)

[dmytrokirpa]

Thanks @dzearing for creating an issue and bringing up this topic, let me try addressing you questions/comments:

Given this:

<Dropdown value={0} onChange={ (value) => console.log(value); }>
   <Option value={0}>Text for 0</Option>
   <Option value={1}>Text for 1</Option>
   <Option value={2}>Text for 2</Option>
</Dropdown>

It's not a correct usage of the component according to the docs, the correct one would be:

// The `value` is used to display as the Dropdown trigger value
const [value, setValue] = useState("Text for 0");

// The `selectedOptions` is used to display options selected state in the Dropdown listbox/popup.   
const [selectedOptions, setSelectedOptions] = useState(['0']);

<Dropdown 
  value={value}
  selectedOptions={selectedOptions}
  onOptionSelect={(event, data) => { 
    setSelectedOptions(data.selectedOptions);
    setValue(data.optionText);
  }}
>
   <Option value="0">Text for 0</Option>
   <Option value="1">Text for 1</Option>
   <Option value="2">Text for 2</Option>
</Dropdown>

Expectations/Results:

• We should be displaying "Text for 0" but instead, the value 0 is displayed as the selected item.

As described above in the example, the value is used to display as the exact Dropdown trigger value, that's not Option value.

• There should be a single way to specify the selected item - not 2. Either value or selectedOptions but not both. Pick one. Provide examples in documentation.

I agree that it's not ideal, but there are two separate props that should be synched manually value and the selectedOptions, but they serve different purposes.

• There should be a single event fired when selection changes, but not 2. Pick one. Provide examples in documentation.

There is only one event and it's onOptionSelect, onChange is not fired.

• Went to the controlled component usage example in docs - the first thing you see is uncontrolled usage example. What?

The example showcases both uncontrolled (1st) and controlled (2nd) Dropdown components to highlight the difference. Do you think we should leave only the controlled component example to make things clearer?

Thank you @dzearing for the valuable feedback, it's greatly appreciated!