svelte-multiselect 11.4.0 → 11.5.1

package/readme.md

@@ -34,9 +34,9 @@
 
 ## 🧪   Coverage
 
-| Statements                                                                                 | Branches                                                                          | Lines                                                                            |
-| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| ![Statements](https://img.shields.io/badge/statements-92.81%25-brightgreen.svg?style=flat) | ![Branches](https://img.shields.io/badge/branches-81.57%25-yellow.svg?style=flat) | ![Lines](https://img.shields.io/badge/lines-92.81%25-brightgreen.svg?style=flat) |
+| Statements                                                                            | Branches                                                                          | Lines                                                                       |
+| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| ![Statements](https://img.shields.io/badge/statements-85.65%25-yellow.svg?style=flat) | ![Branches](https://img.shields.io/badge/branches-82.47%25-yellow.svg?style=flat) | ![Lines](https://img.shields.io/badge/lines-85.51%25-yellow.svg?style=flat) |
 
 ## 🔨   Installation
 
@@ -334,6 +334,85 @@ These are the core props you'll use in most cases:
 
    Configuration for portal rendering. When `active: true`, the dropdown is rendered at document.body level with fixed positioning. Useful for avoiding z-index and overflow issues.
 
+### Grouping Props
+
+Group related options together with visual headers. Add a `group` key to your option objects:
+
+```svelte
+<script>
+  const options = [
+    { label: `JavaScript`, group: `Frontend` },
+    { label: `TypeScript`, group: `Frontend` },
+    { label: `Python`, group: `Backend` },
+    { label: `Go`, group: `Backend` },
+  ]
+</script>
+
+<MultiSelect {options} collapsibleGroups groupSelectAll />
+```
+
+See the [grouping demo](https://janosh.github.io/svelte-multiselect/grouping) for live examples.
+
+1. ```ts
+   collapsibleGroups: boolean = false
+   ```
+
+   Enable click-to-collapse groups. When `true`, users can click group headers to hide/show options in that group.
+
+1. ```ts
+   collapsedGroups: Set<string> = new Set()
+   ```
+
+   Bindable set of collapsed group names. Use `bind:collapsedGroups` to control which groups are collapsed externally or to persist collapse state.
+
+1. ```ts
+   groupSelectAll: boolean = false
+   ```
+
+   Add a "Select all" button to each group header, allowing users to select all options in a specific group at once.
+
+1. ```ts
+   ungroupedPosition: 'first' | 'last' = 'first'
+   ```
+
+   Where to render options that don't have a `group` key. `'first'` places them at the top, `'last'` at the bottom.
+
+1. ```ts
+   groupSortOrder: 'none' | 'asc' | 'desc' | ((a: string, b: string) => number) = 'none'
+   ```
+
+   Sort groups alphabetically (`'asc'` or `'desc'`) or with a custom comparator function. Default `'none'` preserves order of first occurrence.
+
+1. ```ts
+   searchExpandsCollapsedGroups: boolean = false
+   ```
+
+   When `true`, collapsed groups automatically expand when the search query matches options within them.
+
+1. ```ts
+   liGroupHeaderClass: string = ''
+   ```
+
+   CSS class applied to group header `<li>` elements.
+
+1. ```ts
+   liGroupHeaderStyle: string | null = null
+   ```
+
+   Inline style for group header elements.
+
+1. ```ts
+   groupHeader: Snippet<[{ group: string; options: T[]; collapsed: boolean }]>
+   ```
+
+   Custom snippet for rendering group headers. Receives the group name, array of options in that group, and whether the group is collapsed.
+
+1. ```ts
+   ongroupToggle: (data: { group: string; collapsed: boolean }) => void
+   ```
+
+   Callback fired when a group is collapsed or expanded. Receives the group name and its new collapsed state.
+
 ### Form & Accessibility Props
 
 1. ```ts
@@ -631,15 +710,16 @@ These reflect internal component state:
 
 1. `#snippet option({ option, idx })`: Customize rendering of dropdown options. Receives as props an `option` and the zero-indexed position (`idx`) it has in the dropdown.
 1. `#snippet selectedItem({ option, idx })`: Customize rendering of selected items. Receives as props an `option` and the zero-indexed position (`idx`) it has in the list of selected items.
+1. `#snippet children({ option, idx })`: Convenience snippet that applies to both dropdown options AND selected items. Use this when you want the same custom rendering for both. Takes precedence if `option` or `selectedItem` are not provided.
 1. `#snippet spinner()`: Custom spinner component to display when in `loading` state. Receives no props.
 1. `#snippet disabledIcon()`: Custom icon to display inside the input when in `disabled` state. Receives no props. Use an empty `{#snippet disabledIcon()}{/snippet}` to remove the default disabled icon.
-1. `#snippet expandIcon()`: Allows setting a custom icon to indicate to users that the Multiselect text input field is expandable into a dropdown list. Receives prop `open: boolean` which is true if the Multiselect dropdown is visible and false if it's hidden.
+1. `#snippet expandIcon({ open })`: Allows setting a custom icon to indicate to users that the Multiselect text input field is expandable into a dropdown list. `open` is `true` if the dropdown is visible and `false` if hidden.
 1. `#snippet removeIcon()`: Custom icon to display as remove button. Will be used both by buttons to remove individual selected options and the 'remove all' button that clears all options at once. Receives no props.
 1. `#snippet userMsg({ searchText, msgType, msg })`: Displayed like a dropdown item when the list is empty and user is allowed to create custom options based on text input (or if the user's text input clashes with an existing option). Receives props:
    - `searchText`: The text user typed into search input.
    - `msgType: false | 'create' | 'dupe' | 'no-match'`: `'dupe'` means user input is a duplicate of an existing option. `'create'` means user is allowed to convert their input into a new option not previously in the dropdown. `'no-match'` means user input doesn't match any dropdown items and users are not allowed to create new options. `false` means none of the above.
    - `msg`: Will be `duplicateOptionMsg` or `createOptionMsg` (see [props](#🔣-props)) based on whether user input is a duplicate or can be created as new option. Note this snippet replaces the default UI for displaying these messages so the snippet needs to render them instead (unless purposely not showing a message).
-1. `snippet='after-input'`: Placed after the search input. For arbitrary content like icons or temporary messages. Receives props `selected: Option[]`, `disabled: boolean`, `invalid: boolean`, `id: string | null`, `placeholder: string`, `open: boolean`, `required: boolean`. Can serve as a more dynamic, more customizable alternative to the `placeholder` prop.
+1. `#snippet afterInput({ selected, disabled, invalid, id, placeholder, open, required })`: Placed after the search input. For arbitrary content like icons or temporary messages. Can serve as a more dynamic, more customizable alternative to the `placeholder` prop.
 
 Example using several snippets:
 
@@ -666,65 +746,79 @@ Example using several snippets:
 
 ## 🎬 &thinsp; Events
 
-`MultiSelect.svelte` dispatches the following events:
+`MultiSelect.svelte` provides the following event callback props:
+
+1. ```ts
+   onadd={({ option }) => console.log(option)}
+   ```
+
+   Triggers when a new option is selected. The newly selected option is provided as `option`.
 
 1. ```ts
-   onadd={(event) => console.log(event.detail.option)}
+   oncreate={({ option }) => console.log(option)}
    ```
 
-   Triggers when a new option is selected. The newly selected option is provided as `event.detail.option`.
+   Triggers when a user creates a new option (when `allowUserOptions` is enabled). The created option is provided as `option`.
 
 1. ```ts
-   oncreate={(event) => console.log(event.detail.option)}
+   onremove={({ option }) => console.log(option)}
    ```
 
-   Triggers when a user creates a new option (when `allowUserOptions` is enabled). The created option is provided as `event.detail.option`.
+   Triggers when a single selected option is removed. The removed option is provided as `option`.
 
 1. ```ts
-   onremove={(event) => console.log(event.detail.option)}`
+   onremoveAll={({ options }) => console.log(options)}
    ```
 
-   Triggers when a single selected option is removed. The removed option is provided as `event.detail.option`.
+   Triggers when all selected options are removed. The `options` payload gives the options that were removed (might not be all if `minSelect` is set).
 
 1. ```ts
-   onremoveAll={(event) => console.log(event.detail.options)}`
+   onselectAll={({ options }) => console.log(options)}
    ```
 
-   Triggers when all selected options are removed. The payload `event.detail.options` gives the options that were removed (might not be all if `minSelect` is set).
+   Triggers when the "Select All" option is clicked (requires `selectAllOption` to be enabled). The `options` payload contains the options that were added.
 
 1. ```ts
-   onchange={(event) => console.log(`${event.detail.type}: '${event.detail.option}'`)}
+   onreorder={({ options }) => console.log(options)}
    ```
 
-   Triggers when an option is either added (selected) or removed from selected, or all selected options are removed at once. `type` is one of `'add' | 'remove' | 'removeAll'` and payload will be `option: Option` or `options: Option[]`, respectively.
+   Triggers when selected options are reordered via drag-and-drop (enabled by default when `sortSelected` is false). The `options` payload is the newly ordered array of selected options.
 
 1. ```ts
-   onopen={(event) => console.log(`Multiselect dropdown was opened by ${event}`)}
+   onchange={({ type, option, options }) => console.log(type, option ?? options)}
    ```
 
-   Triggers when the dropdown list of options appears. Event is the DOM's `FocusEvent`,`KeyboardEvent` or `ClickEvent` that initiated this Svelte `dispatch` event.
+   Triggers when an option is either added (selected) or removed from selected, all selected options are removed at once, or selected options are reordered via drag-and-drop. `type` is one of `'add' | 'remove' | 'removeAll' | 'selectAll' | 'reorder'` and payload will be `option: Option` or `options: Option[]`, respectively.
 
 1. ```ts
-   onclose={(event) => console.log(`Multiselect dropdown was closed by ${event}`)}
+   onopen={({ event }) => console.log(`Dropdown opened by`, event)}
    ```
 
-   Triggers when the dropdown list of options disappears. Event is the DOM's `FocusEvent`, `KeyboardEvent` or `ClickEvent` that initiated this Svelte `dispatch` event.
+   Triggers when the dropdown list of options appears. `event` is the DOM's `FocusEvent`, `KeyboardEvent` or `ClickEvent` that triggered the open.
+
+1. ```ts
+   onclose={({ event }) => console.log(`Dropdown closed by`, event)}
+   ```
+
+   Triggers when the dropdown list of options disappears. `event` is the DOM's `FocusEvent`, `KeyboardEvent` or `ClickEvent` that triggered the close.
 
 For example, here's how you might annoy your users with an alert every time one or more options are added or removed:
 
 ```svelte
 <MultiSelect
-  onchange={(event) => {
-    if (event.detail.type === 'add') alert(`You added ${event.detail.option}`)
-    if (event.detail.type === 'remove') alert(`You removed ${event.detail.option}`)
-    if (event.detail.type === 'removeAll') alert(`You removed ${event.detail.options}`)
+  onchange={({ type, option, options }) => {
+    if (type === 'add') alert(`You added ${option}`)
+    if (type === 'remove') alert(`You removed ${option}`)
+    if (type === 'removeAll') alert(`You removed ${options}`)
+    if (type === 'selectAll') alert(`You selected all: ${options}`)
+    if (type === 'reorder') alert(`New order: ${options}`)
   }}
 />
 ```
 
-> Note: Depending on the data passed to the component the `options(s)` payload will either be objects or simple strings/numbers.
+> Note: Depending on the data passed to the component the `option(s)` payload will either be objects or simple strings/numbers.
 
-The above list of events are [Svelte `dispatch` events](https://svelte.dev/tutorial/svelte/component-events). This component also forwards many DOM events from the `<input>` node: `blur`, `change`, `click`, `keydown`, `keyup`, `mousedown`, `mouseenter`, `mouseleave`, `touchcancel`, `touchend`, `touchmove`, `touchstart`. Registering listeners for these events works the same:
+This component also forwards many DOM events from the `<input>` node: `blur`, `change`, `click`, `keydown`, `keyup`, `mousedown`, `mouseenter`, `mouseleave`, `touchcancel`, `touchend`, `touchmove`, `touchstart`. Registering listeners for these events works the same:
 
 ```svelte
 <MultiSelect
@@ -795,10 +889,10 @@ Minimal example that changes the background color of the options dropdown:
 ```
 
 - `div.multiselect`
-  - `border: var(--sms-border, 1pt solid lightgray)`: Change this to e.g. to `1px solid red` to indicate this form field is in an invalid state.
+  - `border: var(--sms-border, 1pt solid light-dark(lightgray, #555))`: 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, 3pt)`
   - `padding: var(--sms-padding, 0 3pt)`
-  - `background: var(--sms-bg)`
+  - `background: var(--sms-bg, light-dark(white, #1a1a1a))`
   - `color: var(--sms-text-color)`
   - `min-height: var(--sms-min-height, 22pt)`
   - `width: var(--sms-width)`
@@ -810,23 +904,23 @@ Minimal example that changes the background color of the options dropdown:
 - `div.multiselect:focus-within`
   - `border: var(--sms-focus-border, 1pt solid var(--sms-active-color, cornflowerblue))`: Border when component has focus. Defaults to `--sms-active-color` which in turn defaults to `cornflowerblue`.
 - `div.multiselect.disabled`
-  - `background: var(--sms-disabled-bg, lightgray)`: Background when in disabled state.
+  - `background: var(--sms-disabled-bg, light-dark(lightgray, #444))`: Background when in disabled state.
 - `div.multiselect input::placeholder`
   - `color: var(--sms-placeholder-color)`
   - `opacity: var(--sms-placeholder-opacity)`
 - `div.multiselect > ul.selected > li`
-  - `background: var(--sms-selected-bg, rgba(0, 0, 0, 0.15))`: Background of selected options.
+  - `background: var(--sms-selected-bg, light-dark(rgba(0, 0, 0, 0.15), rgba(255, 255, 255, 0.15)))`: Background of selected options.
   - `padding: var(--sms-selected-li-padding, 1pt 5pt)`: Height of selected options.
   - `color: var(--sms-selected-text-color, var(--sms-text-color))`: Text color for selected options.
 - `ul.selected > li button:hover, button.remove-all:hover, button:focus`
-  - `color: var(--sms-remove-btn-hover-color, lightskyblue)`: Color of the remove-icon buttons for removing all or individual selected options when in `:focus` or `:hover` state.
-  - `background: var(--sms-remove-btn-hover-bg, rgba(0, 0, 0, 0.2))`: Background for hovered remove buttons.
+  - `color: var(--sms-remove-btn-hover-color, light-dark(#0088cc, lightskyblue))`: Color of the remove-icon buttons for removing all or individual selected options when in `:focus` or `:hover` state.
+  - `background: var(--sms-remove-btn-hover-bg, light-dark(rgba(0, 0, 0, 0.2), rgba(255, 255, 255, 0.2)))`: Background for hovered remove buttons.
 - `div.multiselect > ul.options`
-  - `background: var(--sms-options-bg, white)`: Background of dropdown list.
+  - `background: var(--sms-options-bg, light-dark(#fafafa, #1a1a1a))`: Background of dropdown list.
   - `max-height: var(--sms-options-max-height, 50vh)`: Maximum height of options dropdown.
   - `overscroll-behavior: var(--sms-options-overscroll, none)`: Whether scroll events bubble to parent elements when reaching the top/bottom of the options dropdown. See [MDN](https://developer.mozilla.org/docs/Web/CSS/overscroll-behavior).
   - `z-index: var(--sms-options-z-index, 3)`: Z-index for the dropdown options list.
-  - `box-shadow: var(--sms-options-shadow, 0 0 14pt -8pt black)`: Box shadow of dropdown list.
+  - `box-shadow: var(--sms-options-shadow, light-dark(0 0 14pt -8pt black, 0 0 14pt -4pt rgba(0, 0, 0, 0.8)))`: Box shadow of dropdown list.
   - `border: var(--sms-options-border)`
   - `border-width: var(--sms-options-border-width)`
   - `border-radius: var(--sms-options-border-radius, 1ex)`
@@ -835,13 +929,13 @@ Minimal example that changes the background color of the options dropdown:
 - `div.multiselect > ul.options > li`
   - `scroll-margin: var(--sms-options-scroll-margin, 100px)`: Top/bottom margin to keep between dropdown list items and top/bottom screen edge when auto-scrolling list to keep items in view.
 - `div.multiselect > ul.options > li.selected`
-  - `background: var(--sms-li-selected-bg)`: Background of selected list items in options pane.
-  - `color: var(--sms-li-selected-color)`: Text color of selected list items in options pane.
+  - `background: var(--sms-li-selected-plain-bg, light-dark(rgba(0, 123, 255, 0.1), rgba(100, 180, 255, 0.2)))`: Background of selected list items in options pane.
+  - `border-left: var(--sms-li-selected-plain-border, 3px solid var(--sms-active-color, cornflowerblue))`: Left border of selected list items in options pane.
 - `div.multiselect > ul.options > li.active`
-  - `background: var(--sms-li-active-bg, var(--sms-active-color, rgba(0, 0, 0, 0.15)))`: Background of active options. Options in the dropdown list become active either by mouseover or by navigating to them with arrow keys. Selected options become active when `selectedOptionsDraggable=true` and an option is being dragged to a new position. Note the active option in that case is not the dragged option but the option under it whose place it will take on drag end.
+  - `background: var(--sms-li-active-bg, var(--sms-active-color, light-dark(rgba(0, 0, 0, 0.15), rgba(255, 255, 255, 0.15))))`: Background of active options. Options in the dropdown list become active either by mouseover or by navigating to them with arrow keys. Selected options become active when `selectedOptionsDraggable=true` and an option is being dragged to a new position. Note the active option in that case is not the dragged option but the option under it whose place it will take on drag end.
 - `div.multiselect > ul.options > li.disabled`
-  - `background: var(--sms-li-disabled-bg, #f5f5f6)`: Background of disabled options in the dropdown list.
-  - `color: var(--sms-li-disabled-text, #b8b8b8)`: Text color of disabled option in the dropdown list.
+  - `background: var(--sms-li-disabled-bg, light-dark(#f5f5f6, #2a2a2a))`: Background of disabled options in the dropdown list.
+  - `color: var(--sms-li-disabled-text, light-dark(#b8b8b8, #666))`: Text color of disabled option in the dropdown list.
 - `::highlight(sms-search-matches)`: applies to search results in dropdown list that match the current search query if `highlightMatches=true`. These styles [cannot be set via CSS variables](https://stackoverflow.com/a/56799215). Instead, use a new rule set. For example:
 
   ```css
@@ -862,6 +956,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)
+- `liSelectAllClass`: the "Select All" option at the top of the dropdown (when `selectAllOption` is enabled)
 - `liUserMsgClass`: user message (last child of dropdown list when no options match user input)
 - `liActiveUserMsgClass`: user message when active (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
@@ -877,6 +972,7 @@ This simplified version of the DOM structure of the component shows where these
   </ul>
   <span class="maxSelectMsgClass">2/5 selected</span>
   <ul class="options {ulOptionsClass}">
+    <li class="select-all {liSelectAllClass}">Select all</li>
     <li class={liOptionClass}>Option 1</li>
     <li class="{liOptionClass} {liActiveOptionClass}">
       Option 2 (currently active)
@@ -937,6 +1033,9 @@ Odd as it may seem, you get the most fine-grained control over the styling of ev
 :global(div.multiselect > ul.options > li.disabled) {
   /* options with disabled key set to true (see props above) */
 }
+:global(div.multiselect > ul.options > li.select-all) {
+  /* the "Select All" option at the top of the dropdown */
+}
 ```
 
 ## 🆕 &thinsp; Changelog