From 9ebf6963e06951db9469d1dd899dd7d8fb3362fc Mon Sep 17 00:00:00 2001
From: Eric Liu <ericyl.us@gmail.com>
Date: Sat, 9 Nov 2024 14:02:40 -0800
Subject: [PATCH] docs(multi-select): improvements [ci skip]

---
 docs/src/pages/components/MultiSelect.svx | 38 ++++++++++++++---------
 1 file changed, 23 insertions(+), 15 deletions(-)

diff --git a/docs/src/pages/components/MultiSelect.svx b/docs/src/pages/components/MultiSelect.svx
index 563fee26..9d38c548 100644
--- a/docs/src/pages/components/MultiSelect.svx
+++ b/docs/src/pages/components/MultiSelect.svx
@@ -24,15 +24,30 @@ Checkbox attributes can be adjusted via the `itemToInput` prop.
     {id: "2", text: "Fax"}]}"
   />
 
+## Format item display text
+
+Use the `itemToString` prop to format the display of individual items without modifying the underlying value.
+
+<MultiSelect itemToString={item => {
+  return item.text + ' (' + item.id +')'
+}} titleText="Contact" label="Select contact methods..."
+    items="{[{id: "0", text: "Slack"},
+    {id: "1", text: "Email"},
+    {id: "2", text: "Fax"}]}"
+    sortItem="{() => {}}"
+  />
+
 ## Custom slot
 
-Override the default slot to customize the display of each item. Access the item and index through the `let:` directive.
+For even more customization, use the default slot.
+
+Access the `item` and `index` values through the `let:` directive.
 
 <FileSource src="/framed/MultiSelect/MultiSelectSlot" />
 
 ## No alphabetical ordering
 
-To prevent alphabetical item ordering, pass an empty function to the `sortItem` prop.
+To prevent alphabetical item ordering, pass a noop function to the `sortItem` prop.
 
 <MultiSelect titleText="Contact" label="Select contact methods..."
     items="{[{id: "0", text: "Slack"},
@@ -43,6 +58,8 @@ To prevent alphabetical item ordering, pass an empty function to the `sortItem`
 
 ## Filterable
 
+Set `filterable` to `true` to enable filtering.
+
 `$$restProps` are spread to the underlying input element.
 
 <MultiSelect spellcheck="false" filterable titleText="Contact" placeholder="Filter contact methods..."
@@ -65,19 +82,6 @@ To select (or bind) items, pass an array of item ids to `selectedIds`.
 
 <FileSource src="/framed/MultiSelect/MultipleMultiSelect" />
 
-## Format item display text
-
-Use the `itemToString` prop to format the display of individual items.
-
-<MultiSelect itemToString={item => {
-  return item.text + ' (' + item.id +')'
-}} titleText="Contact" label="Select contact methods..."
-    items="{[{id: "0", text: "Slack"},
-    {id: "1", text: "Email"},
-    {id: "2", text: "Fax"}]}"
-    sortItem="{() => {}}"
-  />
-
 ## Format checkbox values
 
 Use the `itemToInput` prop to customize the user-selectable checkbox values.
@@ -118,6 +122,10 @@ Set `direction` to `"top"` for the dropdown menu to appear above the input.
 
 ## Hidden label
 
+Set `hideLabel` to `true` to visually hide the label.
+
+Note that you should still specify a `label` for accessibility.
+
 <MultiSelect titleText="Contact" label="Select contact methods..." hideLabel
     items="{[{id: "0", text: "Slack"},
     {id: "1", text: "Email"},