svelte-multiselect 6.0.3 → 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,17 +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 = ``;
+// 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
@@ -63,35 +77,32 @@ 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]) {
     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) {
-    if (maxSelect && maxSelect > 1 && selected.length >= maxSelect)
+function add(label, event) {
+    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
@@ -123,23 +134,23 @@ function add(label) {
         }
         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)
-            close_dropdown();
+        if (_selected.length === maxSelect)
+            close_dropdown(event);
         else if (focusInputOnSelect === true ||
             (focusInputOnSelect === `desktop` && window_width > breakpoint)) {
             input?.focus();
@@ -150,10 +161,10 @@ function add(label) {
 }
 // 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
@@ -165,24 +176,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,17 +204,17 @@ 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)) {
@@ -238,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();
@@ -257,7 +271,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>
@@ -292,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}
@@ -320,14 +334,30 @@ 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}
         {name}
         {disabled}
-        placeholder={selectedLabels.length ? `` : placeholder}
+        {inputmode}
+        {pattern}
+        placeholder={_selected.length == 0 ? placeholder : null}
         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}
@@ -339,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"
@@ -375,8 +405,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
@@ -407,7 +437,7 @@ 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={add_option_msg_is_active}
             on:mouseover={() => (add_option_msg_is_active = true)}

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,14 +33,15 @@ 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;

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.3",
+  "version": "7.0.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,8 @@
 - **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).
+- **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
 
@@ -97,7 +99,8 @@ import type { Option } from 'svelte-multiselect'
    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`
@@ -162,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
    ```
@@ -218,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
@@ -232,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
    ```
@@ -263,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
@@ -286,13 +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
-   userInputAs: 'string' | 'number' | 'object' =
-    options.length > 0 ? (typeof options[0] as 'object' | 'string' | 'number') : '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'`.
-
 ## Slots
 
 `MultiSelect.svelte` has 3 named slots:
@@ -353,10 +364,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 +389,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:
@@ -461,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:
 
@@ -486,9 +512,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) {