From 8c6c5afa188e2f0b96cf2795a79553af16efc2ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Thu, 4 May 2023 18:40:11 -0700
Subject: [PATCH 1/5] [docs] Improve the Select docs

---
 docs/data/base/components/select/select.md | 74 +++++++++++++---------
 1 file changed, 45 insertions(+), 29 deletions(-)

diff --git a/docs/data/base/components/select/select.md b/docs/data/base/components/select/select.md
index 0c550540352b71..af0ff2532edf0b 100644
--- a/docs/data/base/components/select/select.md
+++ b/docs/data/base/components/select/select.md
@@ -43,8 +43,9 @@ import Option from '@mui/base/Option';
 export default function MyApp() {
   return (
     <Select>
-      <Option>{/* option one */}</Option>
-      <Option>{/* option two */}</Option>
+      <Option value="#F00">Red</Option>
+      <Option value="#0F0">Green</Option>
+      <Option value="#00F">Blue</Option>
     </Select>
   );
 }
@@ -70,7 +71,7 @@ See the [Object values](#object-values) section to learn how to do it.
 
 #### TypeScript caveat
 
-Select accepts generic props.
+Select's props are generic.
 Due to TypeScript limitations, this may cause unexpected behavior when wrapping the component in `forwardRef` (or other higher-order components).
 
 In such cases, the generic argument will be defaulted to `unknown` and type suggestions will be incomplete.
@@ -93,10 +94,51 @@ For the sake of brevity, the rest of the demos throughout this doc will not use
 ### Multi-select
 
 The Select component lets your users select multiple options from the list.
+In constrast to the single-selection mode, the options popup does not close after an item is selected, allowing users to continue choosing mor e options.
+
 Set the `multiple` prop to turn on the multi-selection mode.
 
 {{"demo": "UnstyledSelectMultiple.js", "defaultCodeOpen": false}}
 
+Note that in the multiple selection mode, the `value` prop (and `defaultValue`) is an array.
+
+### Controlled select
+
+Select can be used as an uncontrolled or controlled component:
+
+{{"demo": "UnstyledSelectControlled.js", "defaultCodeOpen": false}}
+
+To set the value of the controlled Select, use the `value` prop.
+In the other case the `defaultValue` can be used to set the initial value of the component.
+In any case, if you wish to deselect all values pass `null` to the respective prop.
+
+:::warning
+This is one of the differences with Material UI's Select API.
+There, an empty string was used to deselect all values.
+In Base UI, use `null` to achieve this.
+:::
+
+### Object values
+
+The Select component can be used with non-string values:
+
+{{"demo": "UnstyledSelectObjectValues.js", "defaultCodeOpen": false}}
+
+If you use a Select with object values in a form and post the form contents to a server, the selected value will be converted to JSON.
+You can change this behavior with the help of the `getSerializedValue` prop.
+
+{{"demo": "UnstyledSelectObjectValuesForm.js", "defaultCodeOpen": false}}
+
+### Grouping options
+
+Options can be grouped, similarly to how the native `<select>` element works.
+Unlike the native `<select>`, groups can be nested.
+
+The following demo shows how to group options with the Option Group component:
+
+{{"demo": "UnstyledSelectGrouping.js", "defaultCodeOpen": false}}
+
+
 ### Anatomy
 
 The Select component is composed of a root `<button>` along with a `<div>` that houses a `<ul>` within a Popper.
@@ -172,23 +214,6 @@ The resulting HTML is much smaller compared to the unstyled component version, a
 
 ## Customization
 
-### Controlled select
-
-Select can be used as an uncontrolled or controlled component:
-
-{{"demo": "UnstyledSelectControlled.js", "defaultCodeOpen": false}}
-
-### Object values
-
-The Select component can be used with non-string values:
-
-{{"demo": "UnstyledSelectObjectValues.js", "defaultCodeOpen": false}}
-
-If you use a Select with object values in a form and post the form contents to a server, the selected value will be converted to JSON.
-You can change this behavior with the help of the `getSerializedValue` prop.
-
-{{"demo": "UnstyledSelectObjectValuesForm.js", "defaultCodeOpen": false}}
-
 ### Selected value appearance
 
 You can customize the appearance of the selected value display by providing a function to the `renderValue` prop.
@@ -202,12 +227,3 @@ Options don't have to be plain strings.
 You can include custom elements to be rendered inside the listbox.
 
 {{"demo": "UnstyledSelectRichOptions.js", "defaultCodeOpen": false}}
-
-### Grouping options
-
-Options can be grouped, similarly to how the native `<select>` element works.
-Unlike the native `<select>`, groups can be nested.
-
-The following demo shows how to group options with the Option Group component:
-
-{{"demo": "UnstyledSelectGrouping.js", "defaultCodeOpen": false}}

From 82514b0c8fd1d7481a91fc30fbbafbf390379fe4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 16 May 2023 11:30:43 +0200
Subject: [PATCH 2/5] Prettier

---
 docs/data/base/components/select/select.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/data/base/components/select/select.md b/docs/data/base/components/select/select.md
index af0ff2532edf0b..7817745105bae2 100644
--- a/docs/data/base/components/select/select.md
+++ b/docs/data/base/components/select/select.md
@@ -138,7 +138,6 @@ The following demo shows how to group options with the Option Group component:
 
 {{"demo": "UnstyledSelectGrouping.js", "defaultCodeOpen": false}}
 
-
 ### Anatomy
 
 The Select component is composed of a root `<button>` along with a `<div>` that houses a `<ul>` within a Popper.

From 98c4006dec318aa0a48d4d9a817c38acf1d7b026 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal.dudak@gmail.com>
Date: Wed, 28 Jun 2023 18:49:07 +0200
Subject: [PATCH 3/5] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Signed-off-by: Michał Dudak <michal.dudak@gmail.com>
---
 docs/data/base/components/select/select.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/data/base/components/select/select.md b/docs/data/base/components/select/select.md
index 7817745105bae2..ff8f7cd5ada857 100644
--- a/docs/data/base/components/select/select.md
+++ b/docs/data/base/components/select/select.md
@@ -94,7 +94,7 @@ For the sake of brevity, the rest of the demos throughout this doc will not use
 ### Multi-select
 
 The Select component lets your users select multiple options from the list.
-In constrast to the single-selection mode, the options popup does not close after an item is selected, allowing users to continue choosing mor e options.
+In contrast to the single-selection mode, the options popup doesn't close after an item is selected, enabling users to continue choosing more options.
 
 Set the `multiple` prop to turn on the multi-selection mode.
 
@@ -113,8 +113,8 @@ In the other case the `defaultValue` can be used to set the initial value of the
 In any case, if you wish to deselect all values pass `null` to the respective prop.
 
 :::warning
-This is one of the differences with Material UI's Select API.
-There, an empty string was used to deselect all values.
+This pattern is where Base UI's Select differs from the equivalent [Material UI component](/material-ui/react-select/).
+The Material UI Select takes an empty string to deselect all values.
 In Base UI, use `null` to achieve this.
 :::
 

From 6bec6dc33cd3b34a18f13557eac409e76ebda284 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@mui.com>
Date: Wed, 28 Jun 2023 19:03:20 +0200
Subject: [PATCH 4/5] Clarify the difference between controlled and
 uncontrolled components

---
 docs/data/base/components/select/select.md | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/docs/data/base/components/select/select.md b/docs/data/base/components/select/select.md
index d050d5aad2a3b5..e4cbb2496850ed 100644
--- a/docs/data/base/components/select/select.md
+++ b/docs/data/base/components/select/select.md
@@ -104,12 +104,20 @@ Note that in the multiple selection mode, the `value` prop (and `defaultValue`)
 
 ### Controlled select
 
-Select can be used as an uncontrolled or controlled component:
+Select can be used as an uncontrolled or controlled component.
+
+:::info
+
+- The value is **controlled** when its parent manages it by providing a `value` prop.
+- The value is **uncontrolled** when it is managed by the component's own internal state. This state can be initialized using the `defaultValue` prop.
+
+Learn more about the _Controlled and uncontrolled_ pattern in the [React documentation](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components).
+:::
 
 {{"demo": "UnstyledSelectControlled.js", "defaultCodeOpen": false}}
 
 To set the value of the controlled Select, use the `value` prop.
-In the other case the `defaultValue` can be used to set the initial value of the component.
+The uncontrolled component accepts the `defaultValue` that can be used to set the initial value.
 In any case, if you wish to deselect all values pass `null` to the respective prop.
 
 :::warning

From 3ef5a9bf2407a676d3db3cf868b80b409e4c5abc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@mui.com>
Date: Wed, 12 Jul 2023 09:19:45 +0200
Subject: [PATCH 5/5] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Signed-off-by: Michał Dudak <michal.dudak@gmail.com>
---
 docs/data/base/components/select/select.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/data/base/components/select/select.md b/docs/data/base/components/select/select.md
index 56ce4f4c1a7d05..b41b460d199108 100644
--- a/docs/data/base/components/select/select.md
+++ b/docs/data/base/components/select/select.md
@@ -111,19 +111,19 @@ Select can be used as an uncontrolled or controlled component.
 - The value is **controlled** when its parent manages it by providing a `value` prop.
 - The value is **uncontrolled** when it is managed by the component's own internal state. This state can be initialized using the `defaultValue` prop.
 
-Learn more about the _Controlled and uncontrolled_ pattern in the [React documentation](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components).
+Learn more about controlled and uncontrolled components in the [React documentation](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components).
 :::
 
 {{"demo": "UnstyledSelectControlled.js", "defaultCodeOpen": false}}
 
 To set the value of the controlled Select, use the `value` prop.
 The uncontrolled component accepts the `defaultValue` that can be used to set the initial value.
-In any case, if you wish to deselect all values pass `null` to the respective prop.
+In any case, if you wish to deselect all values, pass `null` to the respective prop.
 
 :::warning
 This pattern is where Base UI's Select differs from the equivalent [Material UI component](/material-ui/react-select/).
 The Material UI Select takes an empty string to deselect all values.
-In Base UI, use `null` to achieve this.
+In Base UI, you must use `null` to achieve this.
 :::
 
 ### Object values