svelte-multiselect 8.0.3 → 8.1.0

package/MultiSelect.svelte

@@ -22,6 +22,7 @@ export let filterFunc = (op, searchText) => {
     return `${get_label(op)}`.toLowerCase().includes(searchText.toLowerCase());
 };
 export let focusInputOnSelect = `desktop`;
+export let form_input;
 export let id = null;
 export let input = null;
 export let inputClass = ``;
@@ -32,8 +33,9 @@ export let liOptionClass = ``;
 export let liSelectedClass = ``;
 export let loading = false;
 export let matchingOptions = [];
-export let maxSelect = null; // null means any number of options are selectable
+export let maxSelect = null; // null means there is no upper limit for selected.length
 export let maxSelectMsg = (current, max) => (max > 1 ? `${current}/${max}` : ``);
+export let maxSelectMsgClass = ``;
 export let name = null;
 export let noMatchingOptionsMsg = `No matching options`;
 export let open = false;
@@ -45,6 +47,7 @@ export let pattern = null;
 export let placeholder = null;
 export let removeAllTitle = `Remove all`;
 export let removeBtnTitle = `Remove`;
+export let minSelect = null; // null means there is no lower limit for selected.length
 export let required = false;
 export let resetFilterOnAdd = true;
 export let searchText = ``;
@@ -63,7 +66,7 @@ const get_label = (op) => (op instanceof Object ? op.label : op);
 $: value = maxSelect === 1 ? selected[0] ?? null : selected;
 let wiggle = false; // controls wiggle animation when user tries to exceed maxSelect
 if (!(options?.length > 0)) {
-    if (allowUserOptions || loading) {
+    if (allowUserOptions || loading || disabled) {
         options = []; // initializing as array avoids errors when component mounts
     }
     else {
@@ -76,10 +79,13 @@ if (parseLabelsAsHtml && allowUserOptions) {
     console.warn(`Don't combine parseLabelsAsHtml and allowUserOptions. It's susceptible to XSS attacks!`);
 }
 if (maxSelect !== null && maxSelect < 1) {
-    console.error(`maxSelect must be null or positive integer, got ${maxSelect}`);
+    console.error(`MultiSelect's maxSelect must be null or positive integer, got ${maxSelect}`);
 }
 if (!Array.isArray(selected)) {
-    console.error(`internal variable selected prop should always be an array, got ${selected}`);
+    console.error(`MultiSelect's selected prop should always be an array, got ${selected}`);
+}
+if (maxSelect && typeof required === `number` && required > maxSelect) {
+    console.error(`MultiSelect maxSelect=${maxSelect} < required=${required}, makes it impossible for users to submit a valid form`);
 }
 const dispatch = createEventDispatcher();
 let add_option_msg_is_active = false; // controls active state of <li>{addOptionMsg}</li>
@@ -161,6 +167,7 @@ function add(label, event) {
         dispatch(`add`, { option });
         dispatch(`change`, { option, type: `add` });
         invalid = false; // reset error status whenever new items are selected
+        form_input?.setCustomValidity(``);
     }
 }
 // remove an option from selected list
@@ -180,6 +187,7 @@ function remove(label) {
     dispatch(`remove`, { option });
     dispatch(`change`, { option, type: `remove` });
     invalid = false; // reset error status whenever items are removed
+    form_input?.setCustomValidity(``);
 }
 function open_dropdown(event) {
     if (disabled)
@@ -296,17 +304,30 @@ function on_click_outside(event) {
   on:mouseup|stopPropagation={open_dropdown}
   title={disabled ? disabledInputTitle : null}
   aria-disabled={disabled ? `true` : null}
+  data-id={id}
 >
   <!-- bind:value={selected} prevents form submission if required prop is true and no options are selected -->
   <input
-    {required}
     {name}
-    value={selected.length > 0 ? JSON.stringify(selected) : null}
+    required={Boolean(required)}
+    value={selected.length >= required ? JSON.stringify(selected) : null}
     tabindex="-1"
     aria-hidden="true"
     aria-label="ignore this, used only to prevent form submission if select is required but empty"
     class="form-control"
-    on:invalid={() => (invalid = true)}
+    bind:this={form_input}
+    on:invalid={() => {
+      invalid = true
+      let msg
+      if (maxSelect && maxSelect > 1 && required > 1) {
+        msg = `Please select between ${required} and ${maxSelect} options`
+      } else if (required > 1) {
+        msg = `Please select at least ${required} options`
+      } else {
+        msg = `Please select an option`
+      }
+      form_input.setCustomValidity(msg)
+    }}
   />
   <ExpandIcon width="15px" style="min-width: 1em; padding: 0 1pt;" />
   <ul class="selected {ulSelectedClass}">
@@ -319,7 +340,7 @@ function on_click_outside(event) {
             {get_label(option)}
           {/if}
         </slot>
-        {#if !disabled}
+        {#if !disabled && (minSelect === null || selected.length > minSelect)}
           <button
             on:mouseup|stopPropagation={() => remove(get_label(option))}
             on:keydown={if_enter_or_space(() => remove(get_label(option)))}
@@ -377,7 +398,7 @@ function on_click_outside(event) {
   {:else if selected.length > 0}
     {#if maxSelect && (maxSelect > 1 || maxSelectMsg)}
       <Wiggle bind:wiggle angle={20}>
-        <span style="padding: 0 3pt;">
+        <span class="max-select-msg {maxSelectMsgClass}">
           {maxSelectMsg?.(selected.length, maxSelect)}
         </span>
       </Wiggle>
@@ -607,4 +628,8 @@ function on_click_outside(event) {
     background: var(--sms-li-disabled-bg, #f5f5f6);
     color: var(--sms-li-disabled-text, #b8b8b8);
   }
+
+  :where(span.max-select-msg) {
+    padding: 0 3pt;
+  }
 </style>

package/MultiSelect.svelte.d.ts

@@ -17,6 +17,7 @@ declare const __propDef: {
         duplicates?: boolean | undefined;
         filterFunc?: ((op: Option, searchText: string) => boolean) | undefined;
         focusInputOnSelect?: boolean | "desktop" | undefined;
+        form_input: HTMLInputElement;
         id?: string | null | undefined;
         input?: HTMLInputElement | null | undefined;
         inputClass?: string | undefined;
@@ -29,6 +30,7 @@ declare const __propDef: {
         matchingOptions?: Option[] | undefined;
         maxSelect?: number | null | undefined;
         maxSelectMsg?: ((current: number, max: number) => string) | null | undefined;
+        maxSelectMsgClass?: string | undefined;
         name?: string | null | undefined;
         noMatchingOptionsMsg?: string | undefined;
         open?: boolean | undefined;
@@ -40,7 +42,8 @@ declare const __propDef: {
         placeholder?: string | null | undefined;
         removeAllTitle?: string | undefined;
         removeBtnTitle?: string | undefined;
-        required?: boolean | undefined;
+        minSelect?: number | null | undefined;
+        required?: number | boolean | undefined;
         resetFilterOnAdd?: boolean | undefined;
         searchText?: string | undefined;
         selected?: Option[] | undefined;

package/package.json

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

package/readme.md

@@ -21,7 +21,7 @@
 
 <slot name="examples" />
 
-## Key features
+## Features
 
 - **Bindable:** `bind:selected` gives you an array of the currently selected options. Thanks to Svelte's 2-way binding, it can also control the component state externally through assignment `selected = ['foo', 42]`.
 - **Keyboard friendly** for mouse-less form completion
@@ -36,9 +36,6 @@
 
 ## Recent breaking changes
 
-- **v6.0.0**&nbsp; The prop `showOptions` which controls whether the list of dropdown options is currently open or closed was renamed to `open`. [PR 103](https://github.com/janosh/svelte-multiselect/pull/103).
-- **v6.0.1**&nbsp; The prop `disabledTitle` which sets the title of the `<MultiSelect>` `<input>` node if in `disabled` mode was renamed to `disabledInputTitle`. [PR 105](https://github.com/janosh/svelte-multiselect/pull/105).
-- **v6.0.1**&nbsp; 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. [PR 105](https://github.com/janosh/svelte-multiselect/pull/105).
 - **6.1.0**&nbsp; 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. [PR 120](https://github.com/janosh/svelte-multiselect/pull/120).
 - **v7.0.0**&nbsp; `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. [PR 123](https://github.com/janosh/svelte-multiselect/pull/123).
 - **8.0.0**&nbsp;
@@ -171,6 +168,12 @@ Full list of props/bindable variables for this component. The `Option` type you
 
    One of `true`, `false` or `'desktop'`. Whether to set the cursor back to the input element after selecting an element. 'desktop' means only do so if current window width is larger than the current value of `breakpoint` prop (default 800).
 
+1. ```ts
+   form_input: HTMLInputElement
+   ```
+
+   Handle to the `<input>` DOM node that's responsible for form validity checks and passing selected options to form submission handlers. Only available after component mounts (`null` before then).
+
 1. ```ts
    id: string | null = null
    ```
@@ -193,7 +196,7 @@ Full list of props/bindable variables for this component. The `Option` type you
    invalid: boolean = false
    ```
 
-   If `required=true` and user tries to submit but `selected = []` is empty, `invalid` is automatically set to `true` and CSS class `invalid` applied to the top-level `div.multiselect`. `invalid` class is removed again as soon as the user selects an option. `invalid` can also be controlled externally by binding to it `<MultiSelect bind:invalid />` and setting it to `true` based on outside events or custom validation.
+   If `required = true, 1, 2, ...` and user tries to submit form but `selected = []` is empty/`selected.length < required`, `invalid` is automatically set to `true` and CSS class `invalid` applied to the top-level `div.multiselect`. `invalid` class is removed as soon as any change to `selected` is registered. `invalid` can also be controlled externally by binding to it `<MultiSelect bind:invalid />` and setting it to `true` based on outside events or custom validation.
 
 1. ```ts
    loading: boolean = false
@@ -226,6 +229,16 @@ Full list of props/bindable variables for this component. The `Option` type you
    maxSelectMsg = (current: number, max: number) => `${current}/${max}`
    ```
 
+   Use CSS selector `span.max-select-msg` (or prop `maxSelectMsgClass` if you're using a CSS framework like Tailwind) to customize appearance of the message container.
+
+1. ```ts
+   minSelect: number | null = null
+   ```
+
+   Conditionally render the `x` button which removes a selected option depending on the number of selected options. Meaning all remove buttons disappear if `selected.length <= minSelect`. E.g. if 2 options are selected and `minSelect={3}`, users will not be able to remove any selections until they selected more than 3 options.
+
+   Note: Prop `required={3}` should be used instead if you only care about the component state at form submission time. `minSelect={3}` should be used if you want to place constraints on component state at all times.
+
 1. ```ts
    name: string | null = null
    ```
@@ -287,10 +300,10 @@ Full list of props/bindable variables for this component. The `Option` type you
    Title text to display when user hovers over button to remove selected option (which defaults to a cross icon).
 
 1. ```ts
-   required: boolean = false
+   required: boolean | number = false
    ```
 
-   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.
+   If `required = true, 1, 2, ...` forms can't be submitted without selecting given number of options. `true` means 1. `false` means even empty MultiSelect will pass form validity check. If user tries to submit a form containing MultiSelect with less than the required number of options, submission is aborted, MultiSelect scrolls into view and shows message "Please select at least `required` options".
 
 1. ```ts
    resetFilterOnAdd: boolean = true
@@ -517,6 +530,7 @@ The second method allows you to pass in custom classes to the important DOM elem
 - `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)
+- `maxSelectMsgClass`: small span towards the right end of the input field displaying to the user how many of the allowed number of options they've already selected
 
 This simplified version of the DOM structure of the component shows where these classes are inserted:
 
@@ -527,6 +541,7 @@ This simplified version of the DOM structure of the component shows where these
     <li class={liSelectedClass}>Selected 1</li>
     <li class={liSelectedClass}>Selected 2</li>
   </ul>
+  <span class="maxSelectMsgClass">2/5 selected</span>
   <ul class="options {ulOptionsClass}">
     <li class={liOptionClass}>Option 1</li>
     <li class="{liOptionClass} {liActiveOptionClass}">
@@ -588,7 +603,7 @@ Odd as it may seem, you get the most fine-grained control over the styling of ev
 
 ## Want to contribute?
 
-To submit a PR, clone the repo, install dependencies and start the dev server to try out your changes.
+To submit a PR, clone the repo, install dependencies and start the dev server to see changes as you make them.
 
 ```sh
 git clone https://github.com/janosh/svelte-multiselect
@@ -596,3 +611,9 @@ cd svelte-multiselect
 pnpm install
 pnpm dev
 ```
+
+To make sure your changes didn't break anything, you can run the full test suite (which also runs in CI) using:
+
+```sh
+pnpm test
+```