From 26276395e33c6a04aaf079d63722c4f187a741dd Mon Sep 17 00:00:00 2001
From: Eric Liu <ericyl.us@gmail.com>
Date: Thu, 29 Oct 2020 17:42:27 -0700
Subject: [PATCH 1/4] docs(dropdown): add example "Format item display text"

---
 docs/src/pages/components/Dropdown.svx | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/docs/src/pages/components/Dropdown.svx b/docs/src/pages/components/Dropdown.svx
index a027819b..31c7d45f 100644
--- a/docs/src/pages/components/Dropdown.svx
+++ b/docs/src/pages/components/Dropdown.svx
@@ -13,6 +13,16 @@ components: ["Dropdown", "DropdownSkeleton"]
   {id: "1", text: "Email"},
   {id: "2", text: "Fax"}]}" />
 
+### Format item display text
+
+Use the `itemToString` prop to format the display of individual items.
+
+<Dropdown itemToString={item => {
+  return item.text + ' (' + item.id +')'
+}} titleText="Contact" selectedIndex={0} items="{[{id: "0", text: "Slack"},
+  {id: "1", text: "Email"},
+  {id: "2", text: "Fax"}]}" />
+
 ### Light variant
 
 <Dropdown light titleText="Contact" selectedIndex={0} items="{[{id: "0", text: "Slack"},

From 956b316009cbcc6b102f7c0eeccecce0a7bc57ab Mon Sep 17 00:00:00 2001
From: Eric Liu <ericyl.us@gmail.com>
Date: Thu, 29 Oct 2020 17:43:08 -0700
Subject: [PATCH 2/4] docs(multi-select): add examples for initial selected
 items, format display text

---
 docs/src/pages/components/MultiSelect.svx | 29 +++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/docs/src/pages/components/MultiSelect.svx b/docs/src/pages/components/MultiSelect.svx
index e7274294..85a429c7 100644
--- a/docs/src/pages/components/MultiSelect.svx
+++ b/docs/src/pages/components/MultiSelect.svx
@@ -10,7 +10,7 @@ By default, items will be ordered alphabetically based on the `item.text` value.
 <MultiSelect titleText="Contact" label="Select contact methods..."
     items="{[{id: "0", text: "Slack"},
     {id: "1", text: "Email"},
-    {id: "2", text: "Fax"}]}" selectedIds="{["0", "1"]}"
+    {id: "2", text: "Fax"}]}"
   />
 
 ### No alphabetical ordering
@@ -20,7 +20,32 @@ To prevent alphabetical item ordering, pass an empty function to the `sortItem`
 <MultiSelect titleText="Contact" label="Select contact methods..."
     items="{[{id: "0", text: "Slack"},
     {id: "1", text: "Email"},
-    {id: "2", text: "Fax"}]}" selectedIds="{["0", "1"]}"
+    {id: "2", text: "Fax"}]}" 
+    sortItem="{() => {}}"
+  />
+
+### Initial selected items
+
+To select (or bind) items, pass an array of item ids to `selectedIds`.
+
+<MultiSelect selectedIds="{["0", "1"]}" titleText="Contact" label="Select contact methods..."
+    items="{[{id: "0", text: "Slack"},
+    {id: "1", text: "Email"},
+    {id: "2", text: "Fax"}]}" 
+  />
+
+
+
+### 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="{() => {}}"
   />
 

From a016bf897ca2004f1f288c103a8ebdd89b12a8b9 Mon Sep 17 00:00:00 2001
From: Eric Liu <ericyl.us@gmail.com>
Date: Thu, 29 Oct 2020 18:23:19 -0700
Subject: [PATCH 3/4] feat(multi-select): forward "on:clear" event

---
 COMPONENT_INDEX.md                 |  1 +
 docs/src/PUBLIC_API.json           | 23 +++++++++++++++++------
 src/MultiSelect/MultiSelect.svelte | 10 +++++-----
 3 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/COMPONENT_INDEX.md b/COMPONENT_INDEX.md
index 37c737db..c740e4b9 100644
--- a/COMPONENT_INDEX.md
+++ b/COMPONENT_INDEX.md
@@ -2749,6 +2749,7 @@ No slots.
 
 ### Forwarded events
 
+- `on:clear`
 - `on:keydown`
 - `on:focus`
 - `on:blur`
diff --git a/docs/src/PUBLIC_API.json b/docs/src/PUBLIC_API.json
index 87b322e5..15f6f148 100644
--- a/docs/src/PUBLIC_API.json
+++ b/docs/src/PUBLIC_API.json
@@ -8051,11 +8051,22 @@
       ],
       "slots": [],
       "forwarded_events": [
+        [
+          "clear",
+          {
+            "start": 8393,
+            "end": 8401,
+            "type": "EventHandler",
+            "name": "clear",
+            "modifiers": [],
+            "expression": null
+          }
+        ],
         [
           "keydown",
           {
-            "start": 9267,
-            "end": 9277,
+            "start": 9289,
+            "end": 9299,
             "type": "EventHandler",
             "name": "keydown",
             "modifiers": [],
@@ -8065,8 +8076,8 @@
         [
           "focus",
           {
-            "start": 9769,
-            "end": 9777,
+            "start": 9791,
+            "end": 9799,
             "type": "EventHandler",
             "name": "focus",
             "modifiers": [],
@@ -8076,8 +8087,8 @@
         [
           "blur",
           {
-            "start": 9788,
-            "end": 9795,
+            "start": 9810,
+            "end": 9817,
             "type": "EventHandler",
             "name": "blur",
             "modifiers": [],
diff --git a/src/MultiSelect/MultiSelect.svelte b/src/MultiSelect/MultiSelect.svelte
index 447b0a72..1d99ff9e 100644
--- a/src/MultiSelect/MultiSelect.svelte
+++ b/src/MultiSelect/MultiSelect.svelte
@@ -169,11 +169,10 @@
   let fieldRef = null;
   let selectionRef = null;
   let inputRef = null;
-
-  $: inputValue = "";
-  $: initialSorted = false;
-  $: highlightedIndex = -1;
-  $: prevChecked = [];
+  let inputValue = "";
+  let initialSorted = false;
+  let highlightedIndex = -1;
+  let prevChecked = [];
 
   setContext("MultiSelect", {
     declareRef: ({ key, ref }) => {
@@ -335,6 +334,7 @@
       {#if checked.length > 0}
         <ListBoxSelection
           selectionCount="{checked.length}"
+          on:clear
           on:clear="{() => {
             sortedItems = sortedItems.map((item) => ({
               ...item,

From 2140eebb33dde3108d95e220ffc4ab17283db826 Mon Sep 17 00:00:00 2001
From: Eric Liu <ericyl.us@gmail.com>
Date: Thu, 29 Oct 2020 18:39:41 -0700
Subject: [PATCH 4/4] feat(multi-select): dispatch "select" event

---
 COMPONENT_INDEX.md                 |  2 +-
 docs/src/PUBLIC_API.json           | 25 ++++++++++++++++---------
 src/MultiSelect/MultiSelect.svelte |  9 ++++++++-
 3 files changed, 25 insertions(+), 11 deletions(-)

diff --git a/COMPONENT_INDEX.md b/COMPONENT_INDEX.md
index c740e4b9..f412665b 100644
--- a/COMPONENT_INDEX.md
+++ b/COMPONENT_INDEX.md
@@ -2756,7 +2756,7 @@ No slots.
 
 ### Dispatched events
 
-No dispatched events.
+- `on:select`
 
 ---
 
diff --git a/docs/src/PUBLIC_API.json b/docs/src/PUBLIC_API.json
index 15f6f148..279d5abc 100644
--- a/docs/src/PUBLIC_API.json
+++ b/docs/src/PUBLIC_API.json
@@ -8054,8 +8054,8 @@
         [
           "clear",
           {
-            "start": 8393,
-            "end": 8401,
+            "start": 8577,
+            "end": 8585,
             "type": "EventHandler",
             "name": "clear",
             "modifiers": [],
@@ -8065,8 +8065,8 @@
         [
           "keydown",
           {
-            "start": 9289,
-            "end": 9299,
+            "start": 9473,
+            "end": 9483,
             "type": "EventHandler",
             "name": "keydown",
             "modifiers": [],
@@ -8076,8 +8076,8 @@
         [
           "focus",
           {
-            "start": 9791,
-            "end": 9799,
+            "start": 9975,
+            "end": 9983,
             "type": "EventHandler",
             "name": "focus",
             "modifiers": [],
@@ -8087,8 +8087,8 @@
         [
           "blur",
           {
-            "start": 9810,
-            "end": 9817,
+            "start": 9994,
+            "end": 10001,
             "type": "EventHandler",
             "name": "blur",
             "modifiers": [],
@@ -8096,7 +8096,14 @@
           }
         ]
       ],
-      "dispatched_events": []
+      "dispatched_events": [
+        [
+          "select",
+          {
+            "detail": "{\n        selectedIds,\n        selected: checked,\n        unselected: unchecked,\n      }"
+          }
+        ]
+      ]
     },
     "NotificationActionButton": {
       "moduleName": "NotificationActionButton",
diff --git a/src/MultiSelect/MultiSelect.svelte b/src/MultiSelect/MultiSelect.svelte
index 1d99ff9e..95f02c9f 100644
--- a/src/MultiSelect/MultiSelect.svelte
+++ b/src/MultiSelect/MultiSelect.svelte
@@ -153,7 +153,7 @@
    * @typedef {{ id: MultiSelectItemId; text: MultiSelectItemText; }} MultiSelectItem
    */
 
-  import { afterUpdate, setContext } from "svelte";
+  import { afterUpdate, createEventDispatcher, setContext } from "svelte";
   import WarningFilled16 from "carbon-icons-svelte/lib/WarningFilled16";
   import { Checkbox } from "../Checkbox";
   import {
@@ -165,6 +165,8 @@
     ListBoxSelection,
   } from "../ListBox";
 
+  const dispatch = createEventDispatcher();
+
   let multiSelectRef = null;
   let fieldRef = null;
   let selectionRef = null;
@@ -213,6 +215,11 @@
       }
       prevChecked = checked;
       selectedIds = checked.map(({ id }) => id);
+      dispatch("select", {
+        selectedIds,
+        selected: checked,
+        unselected: unchecked,
+      });
     }
 
     if (!open) {