svelte-multiselect 1.2.2 → 3.0.1

package/MultiSelect.svelte

@@ -1,67 +1,113 @@
-<script >import { createEventDispatcher } from 'svelte';
+<script >import { createEventDispatcher, onMount } from 'svelte';
 import { fly } from 'svelte/transition';
-import CrossIcon from './icons/Cross.svelte';
-import ExpandIcon from './icons/ChevronExpand.svelte';
-import ReadOnlyIcon from './icons/ReadOnly.svelte';
-export let selected;
+import { onClickOutside } from './actions';
+import { CrossIcon, ExpandIcon, ReadOnlyIcon } from './icons';
+export let selected = [];
+export let selectedLabels = [];
+export let selectedValues = [];
 export let maxSelect = null; // null means any number of options are selectable
+export let maxSelectMsg = (current, max) => `${current}/${max}`;
 export let readonly = false;
-export let placeholder = ``;
 export let options;
-export let disabledOptions = [];
 export let input = null;
-export let name = ``;
+export let placeholder = undefined;
+export let name = undefined;
+export let id = undefined;
 export let noOptionsMsg = `No matching options`;
+export let activeOption = null;
 export let outerDivClass = ``;
-export let ulTokensClass = ``;
-export let liTokenClass = ``;
+export let ulSelectedClass = ``;
+export let liSelectedClass = ``;
 export let ulOptionsClass = ``;
 export let liOptionClass = ``;
 export let removeBtnTitle = `Remove`;
 export let removeAllTitle = `Remove all`;
+// https://github.com/sveltejs/svelte/issues/6964
+export let defaultDisabledTitle = `This option is disabled`;
 if (maxSelect !== null && maxSelect < 0) {
-    throw new TypeError(`maxSelect must be null or positive integer, got ${maxSelect}`);
+    console.error(`maxSelect must be null or positive integer, got ${maxSelect}`);
 }
-$: single = maxSelect === 1;
-if (!selected)
-    selected = single ? `` : [];
 if (!(options?.length > 0))
     console.error(`MultiSelect missing options`);
-$: invalidDisabledOptions = disabledOptions.filter((opt) => !options.includes(opt));
-$: if (invalidDisabledOptions.length > 0) {
-    console.error(`Some disabledOptions are invalid as they do not appear in the options list: ${invalidDisabledOptions}`);
+if (!Array.isArray(selected))
+    console.error(`selected prop must be an array`);
+onMount(() => {
+    selected = _options.filter((op) => op?.preselected);
+});
+function isObject(item) {
+    return typeof item === `object` && !Array.isArray(item) && item !== null;
 }
+// process proto options to full ones with mandatory labels
+$: _options = options.map((rawOp) => {
+    // convert to objects internally if user passed list of strings or numbers as options
+    if (isObject(rawOp)) {
+        const op = { ...rawOp };
+        if (!op.value)
+            op.value = op.label;
+        return op;
+    }
+    else {
+        if (![`string`, `number`].includes(typeof rawOp)) {
+            console.error(`MultiSelect options must be objects, strings or numbers, got ${typeof rawOp}`);
+        }
+        // even if we logged error above, try to proceed hoping user knows what they're doing
+        return { label: rawOp, value: rawOp };
+    }
+});
+$: labels = _options.map((op) => op.label);
+$: if (new Set(labels).size !== options.length) {
+    console.error(`Option labels must be unique. Duplicates found: ${labels.filter((label, idx) => labels.indexOf(label) !== idx)}`);
+}
+$: selectedLabels = selected.map((op) => op.label);
+$: selectedValues = selected.map((op) => op.value);
 const dispatch = createEventDispatcher();
-let activeOption, searchText;
+let searchText = ``;
 let showOptions = false;
-$: filteredOptions = searchText
-    ? options.filter((option) => option.toLowerCase().includes(searchText.toLowerCase()))
-    : options;
-$: if ((activeOption && !filteredOptions.includes(activeOption)) ||
+// options matching the current search text
+$: matchingOptions = _options.filter((op) => {
+    if (!searchText)
+        return true;
+    return `${op.label}`.toLowerCase().includes(searchText.toLowerCase());
+});
+$: matchingEnabledOptions = matchingOptions.filter((op) => !op.disabled);
+$: if (
+// if there was an active option but it's not in the filtered list of options
+(activeOption &&
+    !matchingEnabledOptions.map((op) => op.label).includes(activeOption.label)) ||
+    // or there's no active option but the user entered search text
     (!activeOption && searchText))
-    activeOption = filteredOptions[0];
-function add(token) {
+    // make the first filtered option active
+    activeOption = matchingEnabledOptions[0];
+function add(label) {
     if (!readonly &&
-        !selected.includes(token) &&
-        // (... || single) because in single mode, we always replace current token with new selection
-        (maxSelect === null || selected.length < maxSelect || single)) {
+        !selectedLabels.includes(label) &&
+        // for maxselect = 1 we always replace current option with new selection
+        (maxSelect == null || maxSelect == 1 || selected.length < maxSelect)) {
         searchText = ``; // reset search string on selection
-        selected = single ? token : [token, ...selected];
-        if ((Array.isArray(selected) && selected.length === maxSelect) ||
-            typeof selected === `string`) {
-            setOptionsVisible(false);
-            input?.blur();
+        const option = _options.find((op) => op.label === label);
+        if (!option) {
+            console.error(`MultiSelect: option with label ${label} not found`);
+            return;
         }
-        dispatch(`add`, { token });
-        dispatch(`change`, { token, type: `add` });
+        if (maxSelect === 1) {
+            selected = [option];
+        }
+        else {
+            selected = [option, ...selected];
+        }
+        if (selected.length === maxSelect)
+            setOptionsVisible(false);
+        dispatch(`add`, { option });
+        dispatch(`change`, { option, type: `add` });
     }
 }
-function remove(token) {
-    if (readonly || typeof selected === `string`)
+function remove(label) {
+    if (selected.length === 0 || readonly)
         return;
-    selected = selected.filter((item) => item !== token);
-    dispatch(`remove`, { token });
-    dispatch(`change`, { token, type: `remove` });
+    selected = selected.filter((option) => label !== option.label);
+    const option = _options.find((option) => option.label === label);
+    dispatch(`remove`, { option });
+    dispatch(`change`, { option, type: `remove` });
 }
 function setOptionsVisible(show) {
     // nothing to do if visibility is already as intended
@@ -70,83 +116,115 @@ function setOptionsVisible(show) {
     showOptions = show;
     if (show)
         input?.focus();
+    else {
+        input?.blur();
+        activeOption = null;
+    }
 }
+// handle all keyboard events this component receives
 function handleKeydown(event) {
+    // on escape: dismiss options dropdown and reset search text
     if (event.key === `Escape`) {
         setOptionsVisible(false);
         searchText = ``;
     }
+    // on enter key: toggle active option and reset search text
     else if (event.key === `Enter`) {
         if (activeOption) {
-            if (isDisabled(activeOption))
-                return;
-            selected.includes(activeOption) ? remove(activeOption) : add(activeOption);
+            const { label } = activeOption;
+            selectedLabels.includes(label) ? remove(label) : add(label);
             searchText = ``;
-        } // no active option means the options are closed in which case enter means open
+        } // no active option means the options dropdown is closed in which case enter means open it
         else
             setOptionsVisible(true);
     }
+    // on up/down arrow keys: update active option
     else if ([`ArrowDown`, `ArrowUp`].includes(event.key)) {
+        if (activeOption === null) {
+            // if no option is active yet, make first one active
+            activeOption = matchingEnabledOptions[0];
+            return;
+        }
         const increment = event.key === `ArrowUp` ? -1 : 1;
-        const newActiveIdx = filteredOptions.indexOf(activeOption) + increment;
+        const newActiveIdx = matchingEnabledOptions.indexOf(activeOption) + increment;
+        const ulOps = document.querySelector(`ul.options`);
         if (newActiveIdx < 0) {
-            activeOption = filteredOptions[filteredOptions.length - 1];
+            // wrap around top
+            activeOption = matchingEnabledOptions[matchingEnabledOptions.length - 1];
+            if (ulOps)
+                ulOps.scrollTop = ulOps.scrollHeight;
+        }
+        else if (newActiveIdx === matchingEnabledOptions.length) {
+            // wrap around bottom
+            activeOption = matchingEnabledOptions[0];
+            if (ulOps)
+                ulOps.scrollTop = 0;
         }
         else {
-            if (newActiveIdx === filteredOptions.length)
-                activeOption = filteredOptions[0];
+            // default case
+            activeOption = matchingEnabledOptions[newActiveIdx];
+            const li = document.querySelector(`ul.options > li.active`);
+            // scrollIntoViewIfNeeded() scrolls top edge of element into view so when moving
+            // downwards, we scroll to next sibling to make element fully visible
+            if (increment === 1)
+                li?.nextSibling?.scrollIntoViewIfNeeded();
             else
-                activeOption = filteredOptions[newActiveIdx];
+                li?.scrollIntoViewIfNeeded();
         }
     }
     else if (event.key === `Backspace`) {
-        // only remove selected tags on backspace if if there are any and no searchText characters remain
-        if (selected.length > 0 && searchText.length === 0) {
-            selected = selected.slice(0, selected.length - 1);
-        }
+        const label = selectedLabels.pop();
+        if (label && !searchText)
+            remove(label);
     }
 }
 const removeAll = () => {
-    dispatch(`remove`, { token: selected });
-    dispatch(`change`, { token: selected, type: `remove` });
-    selected = single ? `` : [];
+    dispatch(`removeAll`, { options: selected });
+    dispatch(`change`, { options: selected, type: `removeAll` });
+    selected = [];
     searchText = ``;
 };
-const isDisabled = (option) => disabledOptions.includes(option);
-$: isSelected = (option) => {
-    if (!(selected?.length > 0))
-        return false; // nothing is selected if `selected` is the empty array or string
-    if (single)
-        return selected === option;
-    else
-        return selected.includes(option);
+$: isSelected = (label) => selectedLabels.includes(label);
+const handleEnterAndSpaceKeys = (handler) => (event) => {
+    if ([`Enter`, `Space`].includes(event.code)) {
+        event.preventDefault();
+        handler();
+    }
 };
 </script>
 
-<!-- z-index: 2 when showOptions is true ensures the ul.tokens of one <MultiSelect /> display above those of another following shortly after it -->
+<!-- z-index: 2 when showOptions is true ensures the ul.selected of one <MultiSelect />
+display above those of another following shortly after it -->
 <div
+  {id}
   class="multiselect {outerDivClass}"
   class:readonly
-  class:single
-  style={showOptions ? `z-index: 2;` : ``}
-  on:mouseup|stopPropagation={() => setOptionsVisible(true)}>
-  <ExpandIcon height="14pt" style="padding-left: 1pt;" />
-  <ul class="tokens {ulTokensClass}">
-    {#if single}
+  class:single={maxSelect == 1}
+  style={showOptions ? `z-index: 2;` : undefined}
+  on:mouseup|stopPropagation={() => setOptionsVisible(true)}
+  use:onClickOutside={() => setOptionsVisible(false)}
+  use:onClickOutside={() => dispatch(`blur`)}
+>
+  <ExpandIcon height="14pt" style="padding: 0 3pt 0 1pt;" />
+  <ul class="selected {ulSelectedClass}">
+    {#if maxSelect == 1 && selected[0]?.label}
       <span on:mouseup|self|stopPropagation={() => setOptionsVisible(true)}>
-        {selected}
+        {selected[0].label}
       </span>
-    {:else if selected?.length > 0}
-      {#each selected as tag}
+    {:else}
+      {#each selected as { label }}
         <li
-          class={liTokenClass}
-          on:mouseup|self|stopPropagation={() => setOptionsVisible(true)}>
-          {tag}
+          class={liSelectedClass}
+          on:mouseup|self|stopPropagation={() => setOptionsVisible(true)}
+        >
+          {label}
           {#if !readonly}
             <button
-              on:mouseup|stopPropagation={() => remove(tag)}
+              on:mouseup|stopPropagation={() => remove(label)}
+              on:keydown={handleEnterAndSpaceKeys(() => remove(label))}
               type="button"
-              title="{removeBtnTitle} {tag}">
+              title="{removeBtnTitle} {label}"
+            >
               <CrossIcon height="12pt" />
             </button>
           {/if}
@@ -160,20 +238,23 @@ $: isSelected = (option) => {
       on:mouseup|self|stopPropagation={() => setOptionsVisible(true)}
       on:keydown={handleKeydown}
       on:focus={() => setOptionsVisible(true)}
-      on:blur={() => dispatch(`blur`)}
-      on:blur={() => setOptionsVisible(false)}
       {name}
-      placeholder={selected.length ? `` : placeholder} />
+      placeholder={selectedLabels.length ? `` : placeholder}
+    />
   </ul>
   {#if readonly}
     <ReadOnlyIcon height="14pt" />
-  {:else}
+  {:else if selected.length > 0}
+    {#if maxSelect !== null && maxSelect > 1}
+      <span style="padding: 0 3pt;">{maxSelectMsg(selected.length, maxSelect)}</span>
+    {/if}
     <button
       type="button"
       class="remove-all"
       title={removeAllTitle}
       on:mouseup|stopPropagation={removeAll}
-      style={selected.length === 0 ? `display: none;` : ``}>
+      on:keydown={handleEnterAndSpaceKeys(removeAll)}
+    >
       <CrossIcon height="14pt" />
     </button>
   {/if}
@@ -182,20 +263,22 @@ $: isSelected = (option) => {
     <ul
       class="options {ulOptionsClass}"
       class:hidden={!showOptions}
-      transition:fly={{ duration: 300, y: 40 }}>
-      {#each filteredOptions as option}
+      transition:fly|local={{ duration: 300, y: 40 }}
+    >
+      {#each matchingOptions as { label, disabled, title = null, selectedTitle, disabledTitle = defaultDisabledTitle }}
         <li
           on:mouseup|preventDefault|stopPropagation
           on:mousedown|preventDefault|stopPropagation={() => {
-            if (isDisabled(option)) return
-
-            isSelected(option) ? remove(option) : add(option)
+            if (disabled) return
+            isSelected(label) ? remove(label) : add(label)
           }}
-          class:selected={isSelected(option)}
-          class:active={activeOption === option}
-          class:disabled={isDisabled(option)}
-          class={liOptionClass}>
-          {option}
+          class:selected={isSelected(label)}
+          class:active={activeOption?.label === label}
+          class:disabled
+          title={disabled ? disabledTitle : (isSelected(label) && selectedTitle) || title}
+          class={liOptionClass}
+        >
+          {label}
         </li>
       {:else}
         {noOptionsMsg}
@@ -214,6 +297,7 @@ $: isSelected = (option) => {
     min-height: 18pt;
     display: flex;
     cursor: text;
+    padding: 0 3pt;
   }
   :where(.multiselect:focus-within) {
     border: var(--sms-focus-border, 1pt solid var(--sms-active-color, cornflowerblue));
@@ -222,8 +306,8 @@ $: isSelected = (option) => {
     background: var(--sms-readonly-bg, lightgray);
   }
 
-  :where(ul.tokens > li) {
-    background: var(--sms-token-bg, var(--sms-active-color, cornflowerblue));
+  :where(ul.selected > li) {
+    background: var(--sms-selected-bg, var(--sms-active-color, cornflowerblue));
     align-items: center;
     border-radius: 4pt;
     display: flex;
@@ -233,16 +317,13 @@ $: isSelected = (option) => {
     white-space: nowrap;
     height: 16pt;
   }
-  :where(ul.tokens > li button, button.remove-all) {
+  :where(ul.selected > li button, button.remove-all) {
     align-items: center;
     border-radius: 50%;
     display: flex;
     cursor: pointer;
     transition: 0.2s;
   }
-  :where(ul.tokens > li button:hover, button.remove-all:hover) {
-    color: var(--sms-remove-x-hover-color, lightgray);
-  }
   :where(button) {
     color: inherit;
     background: transparent;
@@ -251,21 +332,33 @@ $: isSelected = (option) => {
     outline: none;
     padding: 0 2pt;
   }
+  :where(ul.selected > li button:hover, button.remove-all:hover) {
+    color: var(--sms-remove-x-hover-focus-color, lightskyblue);
+  }
+  :where(button:focus) {
+    color: var(--sms-remove-x-hover-focus-color, lightskyblue);
+    transform: scale(1.04);
+  }
 
   :where(.multiselect input) {
     border: none;
     outline: none;
     background: none;
     color: var(--sms-text-color, inherit);
-    width: 1pt; /* fixes issue #12  */
+    flex: 1; /* this + next line fix issue #12 https://git.io/JiDe3 */
+    min-width: 2em;
+    /* minimum font-size > 16px ensures iOS doesn't zoom in when focusing input */
+    /* https://stackoverflow.com/a/6394497 */
+    font-size: calc(16px + 0.1vw);
   }
 
-  :where(ul.tokens) {
+  :where(ul.selected) {
     display: flex;
     padding: 0;
     margin: 0;
     flex-wrap: wrap;
     flex: 1;
+    overscroll-behavior: none;
   }
 
   :where(ul.options) {

package/MultiSelect.svelte.d.ts

@@ -1,22 +1,28 @@
 import { SvelteComponentTyped } from "svelte";
+import type { Option, Primitive, ProtoOption } from './';
 declare const __propDef: {
     props: {
-        selected: string[] | string;
+        selected?: Option[] | undefined;
+        selectedLabels?: Primitive[] | undefined;
+        selectedValues?: Primitive[] | undefined;
         maxSelect?: number | null | undefined;
+        maxSelectMsg?: ((current: number, max: number) => string) | undefined;
         readonly?: boolean | undefined;
-        placeholder?: string | undefined;
-        options: string[];
-        disabledOptions?: string[] | undefined;
+        options: ProtoOption[];
         input?: HTMLInputElement | null | undefined;
+        placeholder?: string | undefined;
         name?: string | undefined;
+        id?: string | undefined;
         noOptionsMsg?: string | undefined;
+        activeOption?: Option | null | undefined;
         outerDivClass?: string | undefined;
-        ulTokensClass?: string | undefined;
-        liTokenClass?: string | undefined;
+        ulSelectedClass?: string | undefined;
+        liSelectedClass?: string | undefined;
         ulOptionsClass?: string | undefined;
         liOptionClass?: string | undefined;
         removeBtnTitle?: string | undefined;
         removeAllTitle?: string | undefined;
+        defaultDisabledTitle?: string | undefined;
     };
     events: {
         mouseup: MouseEvent;

package/actions.d.ts

@@ -0,0 +1,3 @@
+export declare function onClickOutside(node: HTMLElement, cb?: () => void): {
+    destroy(): void;
+};

package/actions.js

@@ -0,0 +1,39 @@
+export function onClickOutside(node, cb) {
+    const dispatchOnClickOutside = (event) => {
+        const clickWasOutside = node && !node.contains(event.target);
+        if (clickWasOutside && !event.defaultPrevented) {
+            node.dispatchEvent(new CustomEvent(`clickOutside`));
+            if (cb)
+                cb();
+        }
+    };
+    document.addEventListener(`click`, dispatchOnClickOutside);
+    return {
+        destroy() {
+            document.removeEventListener(`click`, dispatchOnClickOutside);
+        },
+    };
+}
+// import { spring } from 'svelte/motion'
+// export default function boop(node: HTMLElement, params = {}) {
+//   const { setter } = params
+//   const springyRotation = spring(
+//     { x: 0, y: 0, rotation: 0, scale: 1 },
+//     { stiffness: 0.1, damping: 0.15 }
+//   )
+//   node.style.display = `inline-block`
+//   const unsubscribe = springyRotation.subscribe(({ x, y, rotation, scale }) => {
+//     node.style.transform = `translate(${x}px, ${y}px) rotate(${rotation}deg) scale(${scale})`
+//   })
+//   return {
+//     update({ isBooped: x = 0, y = 0, rotation = 0, scale = 1, timing }) {
+//       springyRotation.set(
+//         isBooped
+//           ? { x, y, rotation, scale }
+//           : { x: 0, y: 0, rotation: 0, scale: 1 }
+//       )
+//       if (isBooped) window.setTimeout(() => setter(false), timing)
+//     },
+//     destroy: unsubscribe,
+//   }
+// }

package/icons/ChevronExpand.svelte

@@ -5,5 +5,6 @@ export let style = ``;
 
 <svg {width} {height} {style} fill="currentColor" viewBox="0 0 16 16">
   <path
-    d="M3.646 9.146a.5.5 0 0 1 .708 0L8 12.793l3.646-3.647a.5.5 0 0 1 .708.708l-4 4a.5.5 0 0 1-.708 0l-4-4a.5.5 0 0 1 0-.708zm0-2.292a.5.5 0 0 0 .708 0L8 3.207l3.646 3.647a.5.5 0 0 0 .708-.708l-4-4a.5.5 0 0 0-.708 0l-4 4a.5.5 0 0 0 0 .708z" />
+    d="M3.646 9.146a.5.5 0 0 1 .708 0L8 12.793l3.646-3.647a.5.5 0 0 1 .708.708l-4 4a.5.5 0 0 1-.708 0l-4-4a.5.5 0 0 1 0-.708zm0-2.292a.5.5 0 0 0 .708 0L8 3.207l3.646 3.647a.5.5 0 0 0 .708-.708l-4-4a.5.5 0 0 0-.708 0l-4 4a.5.5 0 0 0 0 .708z"
+  />
 </svg>

package/icons/Cross.svelte

@@ -5,5 +5,6 @@ export let style = ``;
 
 <svg {width} {height} {style} viewBox="0 0 20 20" fill="currentColor">
   <path
-    d="M10 1.6a8.4 8.4 0 100 16.8 8.4 8.4 0 000-16.8zm4.789 11.461L13.06 14.79 10 11.729l-3.061 3.06L5.21 13.06 8.272 10 5.211 6.939 6.94 5.211 10 8.271l3.061-3.061 1.729 1.729L11.728 10l3.061 3.061z" />
+    d="M10 1.6a8.4 8.4 0 100 16.8 8.4 8.4 0 000-16.8zm4.789 11.461L13.06 14.79 10 11.729l-3.061 3.06L5.21 13.06 8.272 10 5.211 6.939 6.94 5.211 10 8.271l3.061-3.061 1.729 1.729L11.728 10l3.061 3.061z"
+  />
 </svg>

package/icons/ReadOnly.svelte

@@ -6,5 +6,6 @@ export let style = ``;
 <svg {width} {height} {style} viewBox="0 0 24 24" fill="currentColor">
   <path fill="none" d="M0 0h24v24H0V0z" />
   <path
-    d="M14.48 11.95c.17.02.34.05.52.05 2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4c0 .18.03.35.05.52l3.43 3.43zm2.21 2.21L22.53 20H23v-2c0-2.14-3.56-3.5-6.31-3.84zM0 3.12l4 4V10H1v2h3v3h2v-3h2.88l2.51 2.51C9.19 15.11 7 16.3 7 18v2h9.88l4 4 1.41-1.41L1.41 1.71 0 3.12zM6.88 10H6v-.88l.88.88z" />
+    d="M14.48 11.95c.17.02.34.05.52.05 2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4c0 .18.03.35.05.52l3.43 3.43zm2.21 2.21L22.53 20H23v-2c0-2.14-3.56-3.5-6.31-3.84zM0 3.12l4 4V10H1v2h3v3h2v-3h2.88l2.51 2.51C9.19 15.11 7 16.3 7 18v2h9.88l4 4 1.41-1.41L1.41 1.71 0 3.12zM6.88 10H6v-.88l.88.88z"
+  />
 </svg>

package/icons/index.d.ts

@@ -0,0 +1,3 @@
+export { default as CrossIcon } from './Cross.svelte';
+export { default as ExpandIcon } from './ChevronExpand.svelte';
+export { default as ReadOnlyIcon } from './ReadOnly.svelte';

package/icons/index.js

@@ -0,0 +1,3 @@
+export { default as CrossIcon } from './Cross.svelte';
+export { default as ExpandIcon } from './ChevronExpand.svelte';
+export { default as ReadOnlyIcon } from './ReadOnly.svelte';

package/index.d.ts

@@ -1 +1,15 @@
 export { default } from './MultiSelect.svelte';
+export declare type Primitive = string | number;
+export declare type Option = {
+    label: Primitive;
+    value: Primitive;
+    title?: string;
+    disabled?: boolean;
+    preselected?: boolean;
+    disabledTitle?: string;
+    selectedTitle?: string;
+    [key: string]: unknown;
+};
+export declare type ProtoOption = Primitive | (Omit<Option, `value`> & {
+    value?: Primitive;
+});

package/package.json

@@ -5,33 +5,33 @@
   "homepage": "https://svelte-multiselect.netlify.app",
   "repository": "https://github.com/janosh/svelte-multiselect",
   "license": "MIT",
-  "version": "1.2.2",
+  "version": "3.0.1",
   "type": "module",
   "svelte": "MultiSelect.svelte",
   "bugs": {
     "url": "https://github.com/janosh/svelte-multiselect/issues"
   },
   "devDependencies": {
-    "@sveltejs/adapter-static": "^1.0.0-next.21",
-    "@sveltejs/kit": "^1.0.0-next.187",
-    "@typescript-eslint/eslint-plugin": "^5.1.0",
-    "@typescript-eslint/parser": "^5.1.0",
-    "eslint": "^8.0.1",
-    "eslint-plugin-svelte3": "^3.2.1",
+    "@sveltejs/adapter-static": "^1.0.0-next.24",
+    "@sveltejs/kit": "^1.0.0-next.216",
+    "@typescript-eslint/eslint-plugin": "^5.9.0",
+    "@typescript-eslint/parser": "^5.9.0",
+    "eslint": "^8.6.0",
+    "eslint-plugin-svelte3": "^3.3.0",
     "hastscript": "^7.0.2",
     "mdsvex": "^0.9.8",
-    "prettier": "^2.4.1",
-    "prettier-plugin-svelte": "^2.4.0",
-    "rehype-autolink-headings": "^6.1.0",
-    "rehype-slug": "^5.0.0",
-    "svelte": "^3.44.0",
-    "svelte-check": "^2.2.7",
-    "svelte-preprocess": "^4.9.8",
-    "svelte-toc": "^0.1.9",
-    "svelte2tsx": "^0.4.7",
+    "prettier": "^2.5.1",
+    "prettier-plugin-svelte": "^2.5.1",
+    "rehype-autolink-headings": "^6.1.1",
+    "rehype-slug": "^5.0.1",
+    "svelte": "^3.45.0",
+    "svelte-check": "^2.2.11",
+    "svelte-preprocess": "^4.10.1",
+    "svelte-toc": "^0.2.0",
+    "svelte2tsx": "^0.4.12",
     "tslib": "^2.3.1",
-    "typescript": "^4.4.4",
-    "vite": "^2.6.10"
+    "typescript": "^4.5.4",
+    "vite": "^2.7.10"
   },
   "keywords": [
     "svelte",

package/readme.md

@@ -20,7 +20,7 @@
 
 <!-- remove above in docs -->
 
-Keyboard-friendly, zero-dependency multi-select Svelte component.
+**Keyboard-friendly, zero-dependency multi-select Svelte component.**
 
 ## Key Features
 
@@ -29,10 +29,22 @@ Keyboard-friendly, zero-dependency multi-select Svelte component.
 - **Searchable:** start typing to filter options
 - **Tagging:** selected options are recorded as tags within the text input
 - **Server-side rendering:** no reliance on browser objects like `window` or `document`
-- **Configurable:** see section [props](#props)
+- **Configurable:** see [props](#props)
 - **No dependencies:** needs only Svelte as dev dependency
 - **Keyboard friendly** for mouse-less form completion
 
+## Recent breaking changes
+
+- v2.0.0 added the ability to pass options as objects. As a result, `bind:selected` no longer returns simple strings but objects as well, even if you still pass in `options` as strings.
+- v3.0.0 changed the `event.detail` payload for `'add'`, `'remove'` and `'change'` events from `token` to `option`, e.g.
+
+  ```js
+  on:add={(e) => console.log(e.detail.token.label)} // v2.0.0
+  on:add={(e) => console.log(e.detail.option.label)} // v3.0.0
+  ```
+
+  It also added a separate event type `removeAll` for when the user removes all currently selected options at once which previously fired a normal `remove`. The props `ulTokensClass` and `liTokenClass` were renamed to `ulSelectedClass` and `liSelectedClass`. Similarly, the CSS variable `--sms-token-bg` changed to `--sms-selected-bg`.
+
 ## Installation
 
 ```sh
@@ -75,16 +87,21 @@ Full list of props/bindable variables for this component:
 
 <div class="table">
 
-| name              | default                             | description                                                                                                                                                                |
-| :---------------- | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `options`         | N/A (required prop)                 | Array of strings that will be listed in the dropdown selection.                                                                                                            |
-| `maxSelect`       | `null`                              | `null` or positive integer to allow users to select as many as they like or a maximum number of options, respectively.                                                     |
-| `selected`        | `[]` (or `''` if `maxSelect === 1`) | Array of currently/pre-selected options when binding/passing as props respectively.                                                                                        |
-| `readonly`        | `false`                             | Disables the component. It will still be rendered but users won't be able to interact with it.                                                                             |
-| `placeholder`     | `''`                                | String shown in the text input when no option is selected.                                                                                                                 |
-| `disabledOptions` | `[]`                                | Array of strings to be disabled in the dropdown selection. Corresponding `<li>` elements in the dropdown list can be styled through the `ul.options li.disabled` selector. |
-| `input`           | `undefined`                         | Handle to the `<input>` DOM node.                                                                                                                                          |
-| `name`            | `''`                                | Passed to the `<input>` for associating HTML form `<label>`s with this component. E.g. clicking a `<label>` with same name will focus this component.                      |
+<!-- prettier-ignore -->
+| name             | default                                                    | description                                                                                                                                                                                    |
+| :--------------- | :--------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`        | required prop                                              | Array of strings/numbers or `Option` objects that will be listed in the dropdown. See `src/lib/index.ts` for admissible fields. The `label` is the only mandatory one. It must also be unique. |
+| `activeOption`   | `null`                                                     | Currently active option, i.e. the one the user currently hovers or navigated to with arrow keys.                                                                                               |
+| `maxSelect`      | `null`                                                     | Positive integer to limit the number of options users can pick. `null` means no limit.                                                                                                         |
+| `maxSelectMsg`   | ``(current: number, max: number) => `${current}/${max}` `` | Function that returns a string informing the user how many of the maximum allowed options they have currently selected. Return empty string to disable, i.e. `() => ''`.                       |
+| `selected`       | `[]`                                                       | Array of currently/pre-selected options when binding/passing as props respectively.                                                                                                            |
+| `selectedLabels` | `[]`                                                       | Labels of currently selected options.                                                                                                                                                          |
+| `selectedValues` | `[]`                                                       | Values of currently selected options.                                                                                                                                                          |
+| `readonly`       | `false`                                                    | Disable the component. It will still be rendered but users won't be able to interact with it.                                                                                                  |
+| `placeholder`    | `undefined`                                                | String shown in the text input when no option is selected.                                                                                                                                     |
+| `input`          | `undefined`                                                | Handle to the `<input>` DOM node.                                                                                                                                                              |
+| `name`           | `undefined`                                                | Passed to the `<input>` for associating HTML form `<label>`s with this component. E.g. clicking a `<label>` with same name will focus this component.                                          |
+| `id`             | `undefined`                                                | Applied to the top-level `<div>` e.g. for `document.getElementById()`.                                                                                                                         |
 
 </div>
 
@@ -92,35 +109,26 @@ Full list of props/bindable variables for this component:
 
 `MultiSelect.svelte` dispatches the following events:
 
-| name     | details                         | description                                                                                                                                    |
-| -------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `add`    | `token: string`                 | Triggers when a new token is selected.                                                                                                         |
-| `remove` | `token: string`                 | Triggers when one or all selected tokens are removed. `event.detail.token` will be a single or multiple tokens, respectively.                  |
-| `change` | `token: string`, `type: string` | Triggers when a token is either added or removed, or all tokens are removed at once. `event.detail.type` will be either `'add'` or `'remove'`. |
-| `blur`   | none                            | Triggers when the input field looses focus.                                                                                                    |
+| name        | detail                                                                              | description                                                                                                                         |
+| ----------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `add`       | `{ option: Option }`                                                                | Triggers when a new option is selected.                                                                                             |
+| `remove`    | `{ option: Option }`                                                                | Triggers when one selected option provided as `event.detail.option` is removed.                                                     |
+| `removeAll` | `options: Option[]`                                                                 | Triggers when all selected options are removed. The payload `event.detail.options` gives the options that were previously selected. |
+| `change`    | `{ option?: Option, options?: Option[] }`, `type: 'add' \| 'remove' \| 'removeAll'` | Triggers when a option is either added or removed, or all options are removed at once.                                              |
+| `blur`      | none                                                                                | Triggers when the input field looses focus.                                                                                         |
 
 ### Examples
 
 <!-- prettier-ignore -->
-- `on:add={(event) => console.log(event.detail.token)}`
-- `on:remove={(event) => console.log(event.detail.token)}`.
-- ``on:change={(event) => console.log(`${event.detail.type}: '${event.detail.token}'`)}``
+- `on:add={(event) => console.log(event.detail.option.label)}`
+- `on:remove={(event) => console.log(event.detail.option.label)}`.
+- ``on:change={(event) => console.log(`${event.detail.type}: '${event.detail.option.label}'`)}``
 - `on:blur={yourFunctionHere}`
 
 ```svelte
 <MultiSelect
-  on:change={(e) => alert(`You ${e.detail.type}ed '${e.detail.token}'`)} />
-```
-
-## Want to contribute?
-
-To submit a PR, clone the repo, install dependencies and start the dev server to try out your changes first.
-
-```sh
-git clone https://github.com/janosh/svelte-multiselect
-cd svelte-multiselect
-yarn
-yarn dev
+  on:change={(e) => alert(`You ${e.detail.type}ed '${e.detail.option.label}'`)}
+/>
 ```
 
 ## Styling
@@ -134,10 +142,11 @@ The first, if you only want to make small adjustments, allows you to pass the fo
 - `border: var(--sms-border, 1pt solid lightgray)`: Border around top-level `div.multiselect`. Change this to e.g. to `1px solid red` to indicate this form field is in an invalid state.
 - `border-radius: var(--sms-border-radius, 5pt)`: `div.multiselect` border radius.
 - `color: var(--sms-text-color, inherit)`: Input text color.
-- `border: var(--sms-focus-border, 1pt solid var(--sms-active-color, cornflowerblue))`: `div.multiselect` border when focused.
+- `border: var(--sms-focus-border, 1pt solid var(--sms-active-color, cornflowerblue))`: `div.multiselect` border when focused. Falls back to `--sms-active-color` if not set which in turn falls back on `cornflowerblue`.
 - `background: var(--sms-readonly-bg, lightgray)`: Background when in readonly state.
-- `background: var(--sms-token-bg, var(--sms-active-color, cornflowerblue))`: Background of selected tokens.
-- `color: var(--sms-remove-x-hover-color, lightgray)`: Hover color of cross icon to remove selected tokens.
+- `background: var(--sms-selected-bg, var(--sms-active-color, cornflowerblue))`: Background of selected options.
+- `color: var(--sms-remove-x-hover+focus-color, lightgray)`: Hover color of cross icon to remove selected options.
+- `color: var(--sms-remove-x-hover-focus-color, lightskyblue)`: Color of the cross-icon buttons for removing all or individual selected options when in `:focus` or `:hover` state.
 - `background: var(--sms-options-bg, white)`: Background of options list.
 - `background: var(--sms-li-selected-bg, inherit)`: Background of selected list items in options pane.
 - `color: var(--sms-li-selected-color, inherit)`: Text color of selected list items in options pane.
@@ -156,8 +165,8 @@ For example, to change the background color of the options dropdown:
 The second method allows you to pass in custom classes to the important DOM elements of this component to target them with frameworks like [Tailwind CSS](https://tailwindcss.com).
 
 - `outerDivClass`
-- `ulTokensClass`
-- `liTokenClass`
+- `ulSelectedClass`
+- `liSelectedClass`
 - `ulOptionsClass`
 - `liOptionClass`
 
@@ -165,9 +174,9 @@ This simplified version of the DOM structure of this component shows where these
 
 ```svelte
 <div class={outerDivClass}>
-  <ul class={ulTokensClass}>
-    <li class={liTokenClass}>First selected tag</li>
-    <li class={liTokenClass}>Second selected tag</li>
+  <ul class={ulSelectedClass}>
+    <li class={liSelectedClass}>First selected tag</li>
+    <li class={liSelectedClass}>Second selected tag</li>
   </ul>
   <ul class={ulOptionsClass}>
     <li class={liOptionClass}>First available option</li>
@@ -178,16 +187,16 @@ This simplified version of the DOM structure of this component shows where these
 
 ### Granular control through global CSS
 
-You can alternatively style every part of this component with more fine-grained control by using the following `:global()` CSS selectors.
+You can alternatively style every part of this component with more fine-grained control by using the following `:global()` CSS selectors. `ul.selected` is the list of currently selected options rendered inside the component's input whereas `ul.options` is the list of available options that slides out when the component has focus.
 
 ```css
 :global(.multiselect) {
   /* top-level wrapper div */
 }
-:global(.multiselect ul.tokens > li) {
-  /* the blue tags representing selected options with remove buttons inside the input */
+:global(.multiselect ul.selected > li) {
+  /* selected options */
 }
-:global(.multiselect ul.tokens > li button),
+:global(.multiselect ul.selected > li button),
 :global(.multiselect button.remove-all) {
   /* buttons to remove a single or all selected options at once */
 }
@@ -195,7 +204,7 @@ You can alternatively style every part of this component with more fine-grained
   /* dropdown options */
 }
 :global(.multiselect ul.options li) {
-  /* dropdown options */
+  /* dropdown list of available options */
 }
 :global(.multiselect ul.options li.selected) {
   /* selected options in the dropdown list */
@@ -208,11 +217,24 @@ You can alternatively style every part of this component with more fine-grained
   /* probably not necessary to style this state in most cases */
 }
 :global(.multiselect ul.options li.active) {
-  /* active means element was navigated to with up/down arrow keys */
+  /* active means item was navigated to with up/down arrow keys */
   /* ready to be selected by pressing enter */
 }
 :global(.multiselect ul.options li.selected.active) {
+  /* both active and already selected, pressing enter now will deselect the item */
 }
 :global(.multiselect ul.options li.disabled) {
+  /* options with disabled key set to true (see props above) */
 }
 ```
+
+## Want to contribute?
+
+To submit a PR, clone the repo, install dependencies and start the dev server to try out your changes.
+
+```sh
+git clone https://github.com/janosh/svelte-multiselect
+cd svelte-multiselect
+yarn
+yarn dev
+```