svelte-multiselect 6.0.2 → 6.1.0

package/MultiSelect.svelte

@@ -37,7 +37,7 @@ export let options;
 export let outerDiv = null;
 export let outerDivClass = ``;
 export let parseLabelsAsHtml = false; // should not be combined with allowUserOptions!
-export let placeholder = undefined;
+export let placeholder = null;
 export let removeAllTitle = `Remove all`;
 export let removeBtnTitle = `Remove`;
 export let required = false;
@@ -48,6 +48,8 @@ export let selectedValues = [];
 export let sortSelected = false;
 export let ulOptionsClass = ``;
 export let ulSelectedClass = ``;
+export let inputmode = ``;
+export let pattern = ``;
 if (!(options?.length > 0)) {
     if (allowUserOptions) {
         options = []; // initializing as array avoids errors when component mounts
@@ -67,7 +69,7 @@ if (!Array.isArray(selected)) {
     console.error(`selected prop must be an array, got ${selected}`);
 }
 const dispatch = createEventDispatcher();
-let activeMsg = false; // controls active state of <li>{addOptionMsg}</li>
+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);
@@ -85,9 +87,9 @@ if (activeIndex !== null && !matchingOptions[activeIndex]) {
     throw `Run time error, activeIndex=${activeIndex} is out of bounds, matchingOptions.length=${matchingOptions.length}`;
 }
 // update activeOption when activeIndex changes
-$: activeOption = activeIndex ? matchingOptions[activeIndex] : null;
+$: activeOption = activeIndex !== null ? matchingOptions[activeIndex] : null;
 // add an option to selected list
-function add(label) {
+function add(label, event) {
     if (maxSelect && maxSelect > 1 && selected.length >= maxSelect)
         wiggle = true;
     // to prevent duplicate selection, we could add `&& !selectedLabels.includes(label)`
@@ -139,7 +141,7 @@ function add(label) {
             }
         }
         if (selected.length === maxSelect)
-            close_dropdown();
+            close_dropdown(event);
         else if (focusInputOnSelect === true ||
             (focusInputOnSelect === `desktop` && window_width > breakpoint)) {
             input?.focus();
@@ -165,24 +167,27 @@ function remove(label) {
     dispatch(`remove`, { option });
     dispatch(`change`, { option, type: `remove` });
 }
-function open_dropdown() {
+function open_dropdown(event) {
     if (disabled)
         return;
     open = true;
-    input?.focus();
-    dispatch(`focus`);
+    if (!(event instanceof FocusEvent)) {
+        // avoid double-focussing input when event that opened dropdown was already input FocusEvent
+        input?.focus();
+    }
+    dispatch(`open`, { event });
 }
-function close_dropdown() {
+function close_dropdown(event) {
     open = false;
     input?.blur();
     activeOption = null;
-    dispatch(`blur`);
+    dispatch(`close`, { event });
 }
 // handle all keyboard events this component receives
 async function handle_keydown(event) {
     // on escape or tab out of input: dismiss options dropdown and reset search text
     if (event.key === `Escape` || event.key === `Tab`) {
-        close_dropdown();
+        close_dropdown(event);
         searchText = ``;
     }
     // on enter key: toggle active option and reset search text
@@ -190,49 +195,41 @@ async function handle_keydown(event) {
         event.preventDefault(); // prevent enter key from triggering form submission
         if (activeOption) {
             const label = get_label(activeOption);
-            selectedLabels.includes(label) ? remove(label) : add(label);
+            selectedLabels.includes(label) ? remove(label) : add(label, event);
             searchText = ``;
         }
         else if (allowUserOptions && searchText.length > 0) {
             // user entered text but no options match, so if allowUserOptions is truthy, we create new option
-            add(searchText);
+            add(searchText, event);
         }
         // no active option and no search text means the options dropdown is closed
         // in which case enter means open it
         else
-            open_dropdown();
+            open_dropdown(event);
     }
     // on up/down arrow keys: update active option
     else if ([`ArrowDown`, `ArrowUp`].includes(event.key)) {
         // if no option is active yet, but there are matching options, make first one active
-        if (activeOption === null && matchingOptions.length > 0) {
-            activeOption = matchingOptions[0];
+        if (activeIndex === null && matchingOptions.length > 0) {
+            activeIndex = 0;
             return;
         }
         else if (allowUserOptions && searchText.length > 0) {
             // if allowUserOptions is truthy and user entered text but no options match, we make
             // <li>{addUserMsg}</li> active on keydown (or toggle it if already active)
-            activeMsg = !activeMsg;
+            add_option_msg_is_active = !add_option_msg_is_active;
             return;
         }
-        else if (activeOption === null) {
+        else if (activeIndex === null) {
             // if no option is active and no options are matching, do nothing
             return;
         }
         const increment = event.key === `ArrowUp` ? -1 : 1;
-        const newActiveIdx = matchingOptions.indexOf(activeOption) + increment;
-        if (newActiveIdx < 0) {
-            // wrap around top
-            activeOption = matchingOptions[matchingOptions.length - 1];
-        }
-        else if (newActiveIdx === matchingOptions.length) {
-            // wrap around bottom
-            activeOption = matchingOptions[0];
-        }
-        else {
-            // default case: select next/previous in item list
-            activeOption = matchingOptions[newActiveIdx];
-        }
+        activeIndex = (activeIndex + increment) % matchingOptions.length;
+        // % in JS behaves like remainder operator, not real modulo, so negative numbers stay negative
+        // need to do manual wrap around at 0
+        if (activeIndex < 0)
+            activeIndex = matchingOptions.length - 1;
         if (autoScroll) {
             // TODO This ugly timeout hack is needed to properly scroll element into view when wrapping
             // around start/end of option list. Find a better solution than waiting 10 ms to.
@@ -265,7 +262,7 @@ const if_enter_or_space = (handler) => (event) => {
 };
 function on_click_outside(event) {
     if (outerDiv && !outerDiv.contains(event.target)) {
-        close_dropdown();
+        close_dropdown(event);
     }
 }
 </script>
@@ -329,13 +326,29 @@ function on_click_outside(event) {
         bind:value={searchText}
         on:mouseup|self|stopPropagation={open_dropdown}
         on:keydown={handle_keydown}
+        on:focus
         on:focus={open_dropdown}
         {id}
         {name}
         {disabled}
+        {inputmode}
+        {pattern}
         placeholder={selectedLabels.length ? `` : placeholder}
         aria-invalid={invalid ? `true` : null}
+        on:blur
+        on:change
+        on:click
+        on:keydown
+        on:keyup
+        on:mousedown
+        on:mouseenter
+        on:mouseleave
+        on:touchcancel
+        on:touchend
+        on:touchmove
+        on:touchstart
       />
+      <!-- the above on:* lines forward potentially useful DOM events -->
     </li>
   </ul>
   {#if loading}
@@ -383,8 +396,8 @@ function on_click_outside(event) {
         {@const active = activeIndex === idx}
         <li
           on:mousedown|stopPropagation
-          on:mouseup|stopPropagation={() => {
-            if (!disabled) is_selected(label) ? remove(label) : add(label)
+          on:mouseup|stopPropagation={(event) => {
+            if (!disabled) is_selected(label) ? remove(label) : add(label, event)
           }}
           title={disabled
             ? disabledTitle
@@ -415,13 +428,13 @@ function on_click_outside(event) {
         {#if allowUserOptions && searchText}
           <li
             on:mousedown|stopPropagation
-            on:mouseup|stopPropagation={() => add(searchText)}
+            on:mouseup|stopPropagation={(event) => add(searchText, event)}
             title={addOptionMsg}
-            class:active={activeMsg}
-            on:mouseover={() => (activeMsg = true)}
-            on:focus={() => (activeMsg = true)}
-            on:mouseout={() => (activeMsg = false)}
-            on:blur={() => (activeMsg = false)}
+            class:active={add_option_msg_is_active}
+            on:mouseover={() => (add_option_msg_is_active = true)}
+            on:focus={() => (add_option_msg_is_active = true)}
+            on:mouseout={() => (add_option_msg_is_active = false)}
+            on:blur={() => (add_option_msg_is_active = false)}
             aria-selected="false"
           >
             {addOptionMsg}

package/MultiSelect.svelte.d.ts

@@ -32,7 +32,7 @@ declare const __propDef: {
         outerDiv?: HTMLDivElement | null | undefined;
         outerDivClass?: string | undefined;
         parseLabelsAsHtml?: boolean | undefined;
-        placeholder?: string | undefined;
+        placeholder?: string | null | undefined;
         removeAllTitle?: string | undefined;
         removeBtnTitle?: string | undefined;
         required?: boolean | undefined;
@@ -43,6 +43,8 @@ declare const __propDef: {
         sortSelected?: boolean | ((op1: Option, op2: Option) => number) | undefined;
         ulOptionsClass?: string | undefined;
         ulSelectedClass?: string | undefined;
+        inputmode?: string | undefined;
+        pattern?: string | undefined;
     };
     slots: {
         selected: {

package/index.d.ts

@@ -25,11 +25,27 @@ export declare type DispatchEvents = {
         options?: Option[];
         type: 'add' | 'remove' | 'removeAll';
     };
-    focus: undefined;
-    blur: undefined;
+    open: {
+        event: Event;
+    };
+    close: {
+        event: Event;
+    };
 };
 export declare type MultiSelectEvents = {
     [key in keyof DispatchEvents]: CustomEvent<DispatchEvents[key]>;
+} & {
+    blur: FocusEvent;
+    click: MouseEvent;
+    focus: FocusEvent;
+    keydown: KeyboardEvent;
+    keyup: KeyboardEvent;
+    mouseenter: MouseEvent;
+    mouseleave: MouseEvent;
+    touchcancel: TouchEvent;
+    touchend: TouchEvent;
+    touchmove: TouchEvent;
+    touchstart: TouchEvent;
 };
 export declare const get_label: (op: Option) => string | number;
 export declare const get_value: (op: Option) => {};

package/package.json

@@ -5,20 +5,20 @@
   "homepage": "https://svelte-multiselect.netlify.app",
   "repository": "https://github.com/janosh/svelte-multiselect",
   "license": "MIT",
-  "version": "6.0.2",
+  "version": "6.1.0",
   "type": "module",
   "svelte": "index.js",
   "main": "index.js",
   "bugs": "https://github.com/janosh/svelte-multiselect/issues",
   "devDependencies": {
-    "@playwright/test": "^1.25.2",
+    "@playwright/test": "^1.26.0",
     "@sveltejs/adapter-static": "^1.0.0-next.43",
-    "@sveltejs/kit": "^1.0.0-next.481",
-    "@sveltejs/package": "^1.0.0-next.3",
-    "@sveltejs/vite-plugin-svelte": "^1.0.5",
-    "@typescript-eslint/eslint-plugin": "^5.37.0",
-    "@typescript-eslint/parser": "^5.37.0",
-    "eslint": "^8.23.1",
+    "@sveltejs/kit": "^1.0.0-next.502",
+    "@sveltejs/package": "^1.0.0-next.5",
+    "@sveltejs/vite-plugin-svelte": "^1.0.8",
+    "@typescript-eslint/eslint-plugin": "^5.38.0",
+    "@typescript-eslint/parser": "^5.38.0",
+    "eslint": "^8.24.0",
     "eslint-plugin-svelte3": "^4.0.0",
     "hastscript": "^7.0.2",
     "jsdom": "^20.0.0",
@@ -32,11 +32,11 @@
     "svelte-github-corner": "^0.1.0",
     "svelte-preprocess": "^4.10.6",
     "svelte-toc": "^0.4.0",
-    "svelte2tsx": "^0.5.17",
+    "svelte2tsx": "^0.5.18",
     "tslib": "^2.4.0",
     "typescript": "^4.8.3",
-    "vite": "^3.1.0",
-    "vitest": "^0.23.2"
+    "vite": "^3.1.3",
+    "vitest": "^0.23.4"
   },
   "keywords": [
     "svelte",

package/readme.md

@@ -9,7 +9,7 @@
 [![Netlify Status](https://api.netlify.com/api/v1/badges/a45b62c3-ea45-4cfd-9912-77ec4fc8d7e8/deploy-status)](https://app.netlify.com/sites/svelte-multiselect/deploys)
 [![NPM version](https://img.shields.io/npm/v/svelte-multiselect?logo=NPM&color=purple)](https://npmjs.com/package/svelte-multiselect)
 [![Needs Svelte version](https://img.shields.io/npm/dependency-version/svelte-multiselect/dev/svelte?color=teal)](https://github.com/sveltejs/svelte/blob/master/CHANGELOG.md)
-[![REPL](https://img.shields.io/badge/Svelte-REPL-blue)](https://svelte.dev/repl/a5a14b8f15d64cb083b567292480db05)
+[![REPL](https://img.shields.io/badge/Svelte-REPL-blue?logo=Svelte)](https://svelte.dev/repl/a5a14b8f15d64cb083b567292480db05)
 [![Open in StackBlitz](https://img.shields.io/badge/Open%20in-StackBlitz-darkblue?logo=stackblitz)](https://stackblitz.com/github/janosh/svelte-multiselect)
 
 </h4>
@@ -40,6 +40,7 @@
 - **v6.0.0** The prop `showOptions` which controls whether the list of dropdown options is currently open or closed was renamed to `open`. See [PR 103](https://github.com/janosh/svelte-multiselect/pull/103).
 - **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).
 
 ## Installation
 
@@ -76,7 +77,7 @@ import type { Option } from 'svelte-multiselect'
 ```
 
 1. ```ts
-   activeIndex: integer | null = null
+   activeIndex: number | null = null
    ```
 
    Zero-based index of currently active option in the array of currently matching options, i.e. if the user typed a search string into the input and only a subset of options match, this index refers to the array position of the matching subset of options
@@ -88,22 +89,23 @@ import type { Option } from 'svelte-multiselect'
    Currently active option, i.e. the one the user currently hovers or navigated to with arrow keys.
 
 1. ```ts
-   addOptionMsg: string = 'Create this option...'
+   addOptionMsg: string = `Create this option...`
    ```
 
    Message shown to users after entering text when no options match their query and `allowUserOptions` is truthy.
 
 1. ```ts
-   allowUserOptions: boolean = false
+   allowUserOptions: boolean | 'append' = false
    ```
 
-   Whether users are allowed to enter values not in the dropdown list. `true` means add user-defined options to the selected list only, `'append'` means add to both options and selected.
+   Whether users can enter values that are not in the dropdown list. `true` means add user-defined options to the selected list only, `'append'` means add to both options and selected.
+   If `allowUserOptions` is `true` or `'append'` then the type `object | number | string` of entered value is determined from the first option of the list to keep type homogeneity.
 
 1. ```ts
-   autocomplete: string = 'off'
+   autocomplete: string = `off`
    ```
 
-   Applied to the `<input>`. Specifies if browser is permitted to auto-fill this form field. See [MDN docs](https://developer.mozilla.org/docs/Web/HTML/Attributes/autocomplete) for other admissible values.
+   Applied to the `<input>`. Specifies if browser is permitted to auto-fill this form field. Should usually be one of `'on'` or `'off'` but see [MDN docs](https://developer.mozilla.org/docs/Web/HTML/Attributes/autocomplete) for other admissible values.
 
 1. ```ts
    autoScroll: boolean = true
@@ -112,13 +114,13 @@ import type { Option } from 'svelte-multiselect'
    `false` disables keeping the active dropdown items in view when going up/down the list of options with arrow keys.
 
 1. ```ts
-   breakpoint: integer = 800
+   breakpoint: number = 800
    ```
 
    Screens wider than `breakpoint` in pixels will be considered `'desktop'`, everything narrower as `'mobile'`.
 
 1. ```ts
-   defaultDisabledTitle: string = 'This option is disabled'
+   defaultDisabledTitle: string = `This option is disabled`
    ```
 
    Title text to display when user hovers over a disabled option. Each option can override this through its `disabledTitle` attribute.
@@ -130,13 +132,13 @@ import type { Option } from 'svelte-multiselect'
    Disable the component. It will still be rendered but users won't be able to interact with it.
 
 1. ```ts
-   disabledInputTitle: string = 'This input is disabled'
+   disabledInputTitle: string = `This input is disabled`
    ```
 
    Tooltip text to display on hover when the component is in `disabled` state.
 
 1. ```ts
-   filterFunc: = (op: Option, searchText: string): boolean => {
+   filterFunc = (op: Option, searchText: string): boolean => {
      if (!searchText) return true
      return `${get_label(op)}`.toLowerCase().includes(searchText.toLowerCase())
    }
@@ -187,7 +189,7 @@ import type { Option } from 'svelte-multiselect'
    Positive integer to limit the number of options users can pick. `null` means no limit.
 
 1. ```ts
-   maxSelectMsg: (current: number, max: number): string = null
+   maxSelectMsg: ((current: number, max: number) => string) | null = null
    ```
 
    Inform users how many of the maximum allowed options they have already selected. Set `maxSelectMsg={null}` to not show a message. Defaults to `null` when `maxSelect={1}` or `maxSelect={null}`. Else if `maxSelect > 1`, defaults to:
@@ -203,7 +205,7 @@ import type { Option } from 'svelte-multiselect'
    Applied to the `<input>` element. Sets the key of this field in a submitted form data object. Not useful at the moment since the value is stored in Svelte state, not on the `<input>` node.
 
 1. ```ts
-   noOptionsMsg: string = 'No matching options'
+   noOptionsMsg: string = `No matching options`
    ```
 
    What message to show if no options match the user-entered search string.
@@ -239,13 +241,13 @@ import type { Option } from 'svelte-multiselect'
    String shown in the text input when no option is selected.
 
 1. ```ts
-   removeAllTitle: string = 'Remove all'
+   removeAllTitle: string = `Remove all`
    ```
 
    Title text to display when user hovers over remove-all button.
 
 1. ```ts
-   removeBtnTitle: string = 'Remove'
+   removeBtnTitle: string = `Remove`
    ```
 
    Title text to display when user hovers over button to remove selected option (which defaults to a cross icon).
@@ -257,7 +259,7 @@ import type { Option } from 'svelte-multiselect'
    Whether forms can be submitted without selecting any options. Aborts submission, is scrolled into view and shows help "Please fill out" message when true and user tries to submit with no options selected.
 
 1. ```ts
-   searchText: string = ''
+   searchText: string = ``
    ```
 
    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.
@@ -287,11 +289,16 @@ 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
-   userInputAs: 'string' | 'number' | 'object' =
-    options.length > 0 ? (typeof options[0] as 'object' | 'string' | 'number') : 'string'
+   inputmode: string = ``
    ```
 
-   What type new options created from user text input should be. Only relevant if `allowUserOptions=true | 'append'`. If not explicitly set, we default `userInputAs` to the type of the 1st option (if available, else `string`) to keep type homogeneity. E.g. if MultiSelect already contains at least one option and it's an object, new options from user-entered text will take the shape `{label: userText, value: userText}`. Likewise if the 1st existing option is a number of string. If MultiSelect starts out empty but you still want user-created custom options to be objects, pass `userInputAs='object'`.
+   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
 
@@ -353,10 +360,16 @@ Example:
    Triggers when an option is either added or removed, or all options are removed at once. `type` is one of `'add' | 'remove' | 'removeAll'` and payload will be `option: Option` or `options: Option[]`, respectively.
 
 1. ```ts
-   on:blur={() => console.log('Multiselect input lost focus')}
+   on:open={(event) => console.log(`Multiselect dropdown was opened by ${event}`)}
+   ```
+
+   Triggers when the dropdown list of options appears. Event is the DOM's `FocusEvent`,`KeyboardEvent` or `ClickEvent` that initiated this Svelte `dispatch` event.
+
+1. ```ts
+   on:close={(event) => console.log(`Multiselect dropdown was closed by ${event}`)}
    ```
 
-   Triggers when the input field looses focus.
+   Triggers when the dropdown list of options disappears. Event is the DOM's `FocusEvent`, `KeyboardEvent` or `ClickEvent` that initiated this Svelte `dispatch` event.
 
 For example, here's how you might annoy your users with an alert every time one or more options are added or removed:
 
@@ -372,6 +385,15 @@ For example, here's how you might annoy your users with an alert every time one
 
 > Note: Depending on the data passed to the component the `options(s)` payload will either be objects or simple strings/numbers.
 
+This component also forwards many DOM events from the `<input>` node: `blur`, `change`, `click`, `keydown`, `keyup`, `mousedown`, `mouseenter`, `mouseleave`, `touchcancel`, `touchend`, `touchmove`, `touchstart`. You can register listeners for these just like for the above [Svelte `dispatch` events](https://svelte.dev/tutorial/component-events):
+
+```svelte
+<MultiSelect
+  options={[1, 2, 3]}
+  on:keyup={(event) => console.log('key', event.target.value)}
+/>
+```
+
 ## TypeScript
 
 TypeScript users can import the types used for internal type safety:
@@ -486,9 +508,9 @@ This simplified version of the DOM structure of the component shows where these
 </div>
 ```
 
-### Granular control through global CSS
+### With global CSS
 
-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.
+Odd as it may seem, you get the most fine-grained control over the styling of every part of this component 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 is in its `open` state. See also [simplified DOM structure](#styling).
 
 ```css
 :global(div.multiselect) {