svelte-multiselect 6.1.0 → 7.0.0

package/MultiSelect.svelte

@@ -22,6 +22,7 @@ export let focusInputOnSelect = `desktop`;
 export let id = null;
 export let input = null;
 export let inputClass = ``;
+export let inputmode = null;
 export let invalid = false;
 export let liActiveOptionClass = ``;
 export let liOptionClass = ``;
@@ -37,19 +38,30 @@ export let options;
 export let outerDiv = null;
 export let outerDivClass = ``;
 export let parseLabelsAsHtml = false; // should not be combined with allowUserOptions!
+export let pattern = null;
 export let placeholder = null;
 export let removeAllTitle = `Remove all`;
 export let removeBtnTitle = `Remove`;
 export let required = false;
 export let searchText = ``;
-export let selected = options?.filter((op) => op?.preselected) ?? [];
+export let selected = options
+    ?.filter((op) => op?.preselected)
+    .slice(0, maxSelect ?? undefined) ?? [];
 export let selectedLabels = [];
 export let selectedValues = [];
 export let sortSelected = false;
 export let ulOptionsClass = ``;
 export let ulSelectedClass = ``;
-export let inputmode = ``;
-export let pattern = ``;
+// selected and _selected are identical except if maxSelect=1, selected will be the single item (or null)
+// in _selected which will always be an array for easier component internals. selected then solves
+// https://github.com/janosh/svelte-multiselect/issues/86
+let _selected = (selected ?? []);
+$: selected = maxSelect === 1 ? _selected[0] ?? null : _selected;
+let wiggle = false; // controls wiggle animation when user tries to exceed maxSelect
+$: _selectedLabels = _selected?.map(get_label) ?? [];
+$: selectedLabels = maxSelect === 1 ? _selectedLabels[0] ?? null : _selectedLabels;
+$: _selectedValues = _selected?.map(get_value) ?? [];
+$: selectedValues = maxSelect === 1 ? _selectedValues[0] ?? null : _selectedValues;
 if (!(options?.length > 0)) {
     if (allowUserOptions) {
         options = []; // initializing as array avoids errors when component mounts
@@ -65,22 +77,19 @@ if (parseLabelsAsHtml && allowUserOptions) {
 if (maxSelect !== null && maxSelect < 1) {
     console.error(`maxSelect must be null or positive integer, got ${maxSelect}`);
 }
-if (!Array.isArray(selected)) {
-    console.error(`selected prop must be an array, got ${selected}`);
+if (!Array.isArray(_selected)) {
+    console.error(`internal variable _selected prop should always be an array, got ${_selected}`);
 }
 const dispatch = createEventDispatcher();
 let add_option_msg_is_active = false; // controls active state of <li>{addOptionMsg}</li>
 let window_width;
-let wiggle = false; // controls wiggle animation when user tries to exceed maxSelect
-$: selectedLabels = selected.map(get_label);
-$: selectedValues = selected.map(get_value);
 // formValue binds to input.form-control to prevent form submission if required
 // prop is true and no options are selected
-$: formValue = selectedValues.join(`,`);
+$: formValue = _selectedValues.join(`,`);
 $: if (formValue)
     invalid = false; // reset error status whenever component state changes
 // options matching the current search text
-$: matchingOptions = options.filter((op) => filterFunc(op, searchText) && !selectedLabels.includes(get_label(op)) // remove already selected options from dropdown list
+$: matchingOptions = options.filter((op) => filterFunc(op, searchText) && !_selectedLabels.includes(get_label(op)) // remove already selected options from dropdown list
 );
 // raise if matchingOptions[activeIndex] does not yield a value
 if (activeIndex !== null && !matchingOptions[activeIndex]) {
@@ -90,10 +99,10 @@ if (activeIndex !== null && !matchingOptions[activeIndex]) {
 $: activeOption = activeIndex !== null ? matchingOptions[activeIndex] : null;
 // add an option to selected list
 function add(label, event) {
-    if (maxSelect && maxSelect > 1 && selected.length >= maxSelect)
+    if (maxSelect && maxSelect > 1 && _selected.length >= maxSelect)
         wiggle = true;
     // to prevent duplicate selection, we could add `&& !selectedLabels.includes(label)`
-    if (maxSelect === null || maxSelect === 1 || selected.length < maxSelect) {
+    if (maxSelect === null || maxSelect === 1 || _selected.length < maxSelect) {
         // first check if we find option in the options list
         let option = options.find((op) => get_label(op) === label);
         if (!option && // this has the side-effect of not allowing to user to add the same
@@ -125,22 +134,22 @@ function add(label, event) {
         }
         if (maxSelect === 1) {
             // for maxselect = 1 we always replace current option with new one
-            selected = [option];
+            _selected = [option];
         }
         else {
-            selected = [...selected, option];
+            _selected = [..._selected, option];
             if (sortSelected === true) {
-                selected = selected.sort((op1, op2) => {
+                _selected = _selected.sort((op1, op2) => {
                     const [label1, label2] = [get_label(op1), get_label(op2)];
                     // coerce to string if labels are numbers
                     return `${label1}`.localeCompare(`${label2}`);
                 });
             }
             else if (typeof sortSelected === `function`) {
-                selected = selected.sort(sortSelected);
+                _selected = _selected.sort(sortSelected);
             }
         }
-        if (selected.length === maxSelect)
+        if (_selected.length === maxSelect)
             close_dropdown(event);
         else if (focusInputOnSelect === true ||
             (focusInputOnSelect === `desktop` && window_width > breakpoint)) {
@@ -152,10 +161,10 @@ function add(label, event) {
 }
 // remove an option from selected list
 function remove(label) {
-    if (selected.length === 0)
+    if (_selected.length === 0)
         return;
-    selected.splice(selectedLabels.lastIndexOf(label), 1);
-    selected = selected; // Svelte rerender after in-place splice
+    _selected.splice(_selectedLabels.lastIndexOf(label), 1);
+    _selected = _selected; // Svelte rerender after in-place splice
     const option = options.find((option) => get_label(option) === label) ??
         // if option with label could not be found but allowUserOptions is truthy,
         // assume it was created by user and create correspondidng option object
@@ -243,17 +252,17 @@ async function handle_keydown(event) {
         }
     }
     // on backspace key: remove last selected option
-    else if (event.key === `Backspace` && selectedLabels.length > 0 && !searchText) {
-        remove(selectedLabels.at(-1));
+    else if (event.key === `Backspace` && _selectedLabels.length > 0 && !searchText) {
+        remove(_selectedLabels.at(-1));
     }
 }
 function remove_all() {
-    dispatch(`removeAll`, { options: selected });
-    dispatch(`change`, { options: selected, type: `removeAll` });
-    selected = [];
+    dispatch(`removeAll`, { options: _selected });
+    dispatch(`change`, { options: _selected, type: `removeAll` });
+    _selected = [];
     searchText = ``;
 }
-$: is_selected = (label) => selectedLabels.includes(label);
+$: is_selected = (label) => _selectedLabels.includes(label);
 const if_enter_or_space = (handler) => (event) => {
     if ([`Enter`, `Space`].includes(event.code)) {
         event.preventDefault();
@@ -297,7 +306,7 @@ function on_click_outside(event) {
   />
   <ExpandIcon width="15px" style="min-width: 1em; padding: 0 1pt;" />
   <ul class="selected {ulSelectedClass}">
-    {#each selected as option, idx}
+    {#each _selected as option, idx}
       <li class={liSelectedClass} aria-selected="true">
         <slot name="selected" {option} {idx}>
           {#if parseLabelsAsHtml}
@@ -325,7 +334,7 @@ function on_click_outside(event) {
         {autocomplete}
         bind:value={searchText}
         on:mouseup|self|stopPropagation={open_dropdown}
-        on:keydown={handle_keydown}
+        on:keydown|stopPropagation={handle_keydown}
         on:focus
         on:focus={open_dropdown}
         {id}
@@ -333,7 +342,7 @@ function on_click_outside(event) {
         {disabled}
         {inputmode}
         {pattern}
-        placeholder={selectedLabels.length ? `` : placeholder}
+        placeholder={_selected.length == 0 ? placeholder : null}
         aria-invalid={invalid ? `true` : null}
         on:blur
         on:change
@@ -360,16 +369,16 @@ function on_click_outside(event) {
     <slot name="disabled-icon">
       <DisabledIcon width="15px" />
     </slot>
-  {:else if selected.length > 0}
+  {:else if _selected.length > 0}
     {#if maxSelect && (maxSelect > 1 || maxSelectMsg)}
       <Wiggle bind:wiggle angle={20}>
         <span style="padding: 0 3pt;">
-          {maxSelectMsg?.(selected.length, maxSelect) ??
-            (maxSelect > 1 ? `${selected.length}/${maxSelect}` : ``)}
+          {maxSelectMsg?.(_selected.length, maxSelect) ??
+            (maxSelect > 1 ? `${_selected.length}/${maxSelect}` : ``)}
         </span>
       </Wiggle>
     {/if}
-    {#if maxSelect !== 1 && selected.length > 1}
+    {#if maxSelect !== 1 && _selected.length > 1}
       <button
         type="button"
         class="remove-all"

package/MultiSelect.svelte.d.ts

@@ -17,6 +17,7 @@ declare const __propDef: {
         id?: string | null | undefined;
         input?: HTMLInputElement | null | undefined;
         inputClass?: string | undefined;
+        inputmode?: string | null | undefined;
         invalid?: boolean | undefined;
         liActiveOptionClass?: string | undefined;
         liOptionClass?: string | undefined;
@@ -32,19 +33,18 @@ declare const __propDef: {
         outerDiv?: HTMLDivElement | null | undefined;
         outerDivClass?: string | undefined;
         parseLabelsAsHtml?: boolean | undefined;
+        pattern?: string | null | undefined;
         placeholder?: string | null | undefined;
         removeAllTitle?: string | undefined;
         removeBtnTitle?: string | undefined;
         required?: boolean | undefined;
         searchText?: string | undefined;
-        selected?: Option[] | undefined;
-        selectedLabels?: (string | number)[] | undefined;
-        selectedValues?: unknown[] | undefined;
+        selected?: Option | Option[] | null | undefined;
+        selectedLabels?: string | number | (string | number)[] | null | undefined;
+        selectedValues?: unknown[] | unknown | null;
         sortSelected?: boolean | ((op1: Option, op2: Option) => number) | undefined;
         ulOptionsClass?: string | undefined;
         ulSelectedClass?: string | undefined;
-        inputmode?: string | undefined;
-        pattern?: string | undefined;
     };
     slots: {
         selected: {

package/package.json

@@ -5,7 +5,7 @@
   "homepage": "https://svelte-multiselect.netlify.app",
   "repository": "https://github.com/janosh/svelte-multiselect",
   "license": "MIT",
-  "version": "6.1.0",
+  "version": "7.0.0",
   "type": "module",
   "svelte": "index.js",
   "main": "index.js",

package/readme.md

@@ -41,6 +41,7 @@
 - **v6.0.1** The prop `disabledTitle` which sets the title of the `<MultiSelect>` `<input>` node if in `disabled` mode was renamed to `disabledInputTitle`. See [PR 105](https://github.com/janosh/svelte-multiselect/pull/105).
 - **v6.0.1** The default margin of `1em 0` on the wrapper `div.multiselect` was removed. Instead, there is now a new CSS variable `--sms-margin`. Set it to `--sms-margin: 1em 0;` to restore the old appearance. See [PR 105](https://github.com/janosh/svelte-multiselect/pull/105).
 - **6.1.0** The `dispatch` events `focus` and `blur` were renamed to `open` and `close`, respectively. These actions refer to the dropdown list, i.e. `<MultiSelect on:open={(event) => console.log(event)}>` will trigger when the dropdown list opens. The focus and blur events are now regular DOM (not Svelte `dispatch`) events emitted by the `<input>` node. See [PR 120](https://github.com/janosh/svelte-multiselect/pull/120).
+- **v7.0.0** `selected` (as well `selectedLabels` and `selectedValues`) used to be arrays always. Now, if `maxSelect=1`, they will no longer be a length-1 array but simply a single a option (label/value respectively) or `null` if no option is selected. See [PR 123](https://github.com/janosh/svelte-multiselect/pull/123).
 
 ## Installation
 
@@ -164,6 +165,12 @@ import type { Option } from 'svelte-multiselect'
 
    Handle to the `<input>` DOM node. Only available after component mounts (`null` before then).
 
+1. ```ts
+   inputmode: string | null = null
+   ```
+
+   The `inputmode` attribute hints at the type of data the user may enter. Values like `'numeric' | 'tel' | 'email'` allow browsers to display an appropriate virtual keyboard. See [MDN](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/inputmode) for details.
+
 1. ```ts
    invalid: boolean = false
    ```
@@ -220,7 +227,7 @@ import type { Option } from 'svelte-multiselect'
    options: Option[]
    ```
 
-   **The only required prop** (no default). Array of strings/numbers or `Option` objects to be listed in the dropdown. The only required key on objects is `label` which must also be unique. An object's `value` defaults to `label` if `undefined`. You can add arbitrary additional keys to your option objects. A few keys like `preselected` and `title` have special meaning though. See `src/lib/index.ts` for all special keys and their purpose.
+   **The only required prop** (no default). Array of strings/numbers or `Option` objects to be listed in the dropdown. The only required key on objects is `label` which must also be unique. An object's `value` defaults to `label` if `undefined`. You can add arbitrary additional keys to your option objects. A few keys like `preselected` and `title` have special meaning though. See type `ObjectOption` in [`src/lib/index.ts`](https://github.com/janosh/svelte-multiselect/blob/main/src/lib/index.ts) for all special keys and their purpose.
 
 1. ```ts
    outerDiv: HTMLDivElement | null = null
@@ -234,6 +241,12 @@ import type { Option } from 'svelte-multiselect'
 
    Whether option labels should be passed to [Svelte's `@html` directive](https://svelte.dev/tutorial/html-tags) or inserted into the DOM as plain text. `true` will raise an error if `allowUserOptions` is also truthy as it makes your site susceptible to [cross-site scripting (XSS) attacks](https://wikipedia.org/wiki/Cross-site_scripting).
 
+1. ```ts
+   pattern: string | null = null
+   ```
+
+   The pattern attribute specifies a regular expression which the input's value must match. If a non-null value doesn't match the `pattern` regex, the read-only `patternMismatch` property will be `true`. See [MDN](https://developer.mozilla.org/docs/Web/HTML/Attributes/pattern) for details.
+
 1. ```ts
    placeholder: string | null = null
    ```
@@ -265,22 +278,25 @@ import type { Option } from 'svelte-multiselect'
    Text the user-entered to filter down on the list of options. Binds both ways, i.e. can also be used to set the input text.
 
 1. ```ts
-   selected: Option[] = options?.filter((op) => op?.preselected) ?? []
+   selected: Option[] | Option | null =
+    options
+      ?.filter((op) => (op as ObjectOption)?.preselected)
+      .slice(0, maxSelect ?? undefined) ?? []
    ```
 
-   Array of currently selected options. Can be bound to `bind:selected={[1, 2, 3]}` to control component state externally or passed as prop to set pre-selected options that will already be populated when component mounts before any user interaction.
+   Array of currently selected options. Supports 2-way binding `bind:selected={[1, 2, 3]}` to control component state externally or passed as prop to set pre-selected options that will already be populated when component mounts before any user interaction. If `maxSelect={1}`, selected will not be an array but a single `Option` or `null` if no options are selected.
 
 1. ```ts
-   selectedLabels: (string | number)[] = []
+   selectedLabels: (string | number)[] | string | number | null = []
    ```
 
-   Labels of currently selected options. Exposed just for convenience, equivalent to `selected.map(op => op.label)` when options are objects. If options are simple strings, `selected === selectedLabels`. Supports binding but is read-only, i.e. since this value is reactive to `selected`, you cannot control `selected` by changing `bind:selectedLabels`.
+   Labels of currently selected options. Exposed just for convenience, equivalent to `selected.map(op => op.label)` when options are objects. If options are simple strings, `selected === selectedLabels`. Supports binding but is read-only, i.e. since this value is reactive to `selected`, you cannot control `selected` by changing `bind:selectedLabels`. If `maxSelect={1}`, selectedLabels will not be an array but a single `string | number` or `null` if no options are selected.
 
 1. ```ts
-   selectedValues: unknown[] = []
+   selectedValues: unknown[] | unknown | null = []
    ```
 
-   Values of currently selected options. Exposed just for convenience, equivalent to `selected.map(op => op.value)` when options are objects. If options are simple strings, `selected === selectedValues`. Supports binding but is read-only, i.e. since this value is reactive to `selected`, you cannot control `selected` by changing `bind:selectedValues`.
+   Values of currently selected options. Exposed just for convenience, equivalent to `selected.map(op => op.value)` when options are objects. If options are simple strings, `selected === selectedValues`. Supports binding but is read-only, i.e. since this value is reactive to `selected`, you cannot control `selected` by changing `bind:selectedValues`. If `maxSelect={1}`, selectedLabels will not be an array but a single value or `null` if no options are selected.
 
 1. ```ts
    sortSelected: boolean | ((op1: Option, op2: Option) => number) = false
@@ -288,18 +304,6 @@ import type { Option } from 'svelte-multiselect'
 
    Default behavior is to render selected items in the order they were chosen. `sortSelected={true}` uses default JS array sorting. A compare function enables custom logic for sorting selected options. See the [`/sort-selected`](https://svelte-multiselect.netlify.app/sort-selected) example.
 
-1. ```ts
-   inputmode: string = ``
-   ```
-
-   The `inputmode` attribute hints at the type of data the user may enter. Values like `'numeric' | 'tel' | 'email'` allow browsers to display an appropriate virtual keyboard. See [MDN](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/inputmode) for details.
-
-1. ```ts
-   pattern: string = ``
-   ```
-
-   The pattern attribute specifies a regular expression which the input's value must match. If a non-null value doesn't match the `pattern` regex, the read-only `patternMismatch` property will be `true`. See [MDN](https://developer.mozilla.org/docs/Web/HTML/Attributes/pattern) for details.
-
 ## Slots
 
 `MultiSelect.svelte` has 3 named slots:
@@ -483,12 +487,12 @@ 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`
-- `ulSelectedClass`
-- `liSelectedClass`
-- `ulOptionsClass`
-- `liOptionClass`
-- `liActiveOptionClass`
+- `outerDivClass`: wrapper `div` enclosing the whole component
+- `ulSelectedClass`: list of selected options
+- `liSelectedClass`: selected list items
+- `ulOptionsClass`: available options listed in the dropdown when component is in `open` state
+- `liOptionClass`: list items selectable from dropdown list
+- `liActiveOptionClass`: the currently active dropdown list item (i.e. hovered or navigated to with arrow keys)
 
 This simplified version of the DOM structure of the component shows where these classes are inserted: