Merge pull request #380 from IBM/docs-multiselect

MultiSelect: forward "clear" event, dispatch "select" event

COMPONENT_INDEX.md

@@ -2749,13 +2749,14 @@ No slots.
 
 ### Forwarded events
 
+- `on:clear`
 - `on:keydown`
 - `on:focus`
 - `on:blur`
 
 ### Dispatched events
 
-No dispatched events.
+- `on:select`
 
 ---
 

docs/src/PUBLIC_API.json

@@ -8051,11 +8051,22 @@
       ],
       "slots": [],
       "forwarded_events": [
+        [
+          "clear",
+          {
+            "start": 8577,
+            "end": 8585,
+            "type": "EventHandler",
+            "name": "clear",
+            "modifiers": [],
+            "expression": null
+          }
+        ],
         [
           "keydown",
           {
-            "start": 9267,
-            "end": 9277,
+            "start": 9473,
+            "end": 9483,
             "type": "EventHandler",
             "name": "keydown",
             "modifiers": [],
@@ -8065,8 +8076,8 @@
         [
           "focus",
           {
-            "start": 9769,
-            "end": 9777,
+            "start": 9975,
+            "end": 9983,
             "type": "EventHandler",
             "name": "focus",
             "modifiers": [],
@@ -8076,8 +8087,8 @@
         [
           "blur",
           {
-            "start": 9788,
-            "end": 9795,
+            "start": 9994,
+            "end": 10001,
             "type": "EventHandler",
             "name": "blur",
             "modifiers": [],
@@ -8085,7 +8096,14 @@
           }
         ]
       ],
-      "dispatched_events": []
+      "dispatched_events": [
+        [
+          "select",
+          {
+            "detail": "{\n        selectedIds,\n        selected: checked,\n        unselected: unchecked,\n      }"
+          }
+        ]
+      ]
     },
     "NotificationActionButton": {
       "moduleName": "NotificationActionButton",

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"},

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="{() => {}}"
   />
 

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,15 +165,16 @@
     ListBoxSelection,
   } from "../ListBox";
 
+  const dispatch = createEventDispatcher();
+
   let multiSelectRef = null;
   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 }) => {
@@ -214,6 +215,11 @@
       }
       prevChecked = checked;
       selectedIds = checked.map(({ id }) => id);
+      dispatch("select", {
+        selectedIds,
+        selected: checked,
+        unselected: unchecked,
+      });
     }
 
     if (!open) {
@@ -335,6 +341,7 @@
       {#if checked.length > 0}
         <ListBoxSelection
           selectionCount="{checked.length}"
+          on:clear
           on:clear="{() => {
             sortedItems = sortedItems.map((item) => ({
               ...item,