@stackline/react-multiselect-dropdown 19.1.0 → 19.1.2

package/README.md

@@ -3,16 +3,19 @@
 > A maintained React multiselect dropdown for React 19 applications, with controlled React state, custom slots, headless/state hooks, searchable/grouped options, lazy loading hooks, custom render functions, skins, body-overlay positioning, and accessibility-focused and keyboard/ARIA tested behavior.
 
 [![npm version](https://img.shields.io/npm/v/@stackline/react-multiselect-dropdown.svg?style=flat-square)](https://www.npmjs.com/package/@stackline/react-multiselect-dropdown)
-[![npm downloads](https://img.shields.io/npm/dt/@stackline/react-multiselect-dropdown.svg?style=flat-square)](https://www.npmjs.com/package/@stackline/react-multiselect-dropdown)
 [![npm monthly](https://img.shields.io/npm/dm/@stackline/react-multiselect-dropdown.svg?style=flat-square)](https://www.npmjs.com/package/@stackline/react-multiselect-dropdown)
 [![license](https://img.shields.io/npm/l/@stackline/react-multiselect-dropdown.svg?style=flat-square)](https://github.com/alexandroit/react-multiselect-dropdown/blob/main/LICENSE)
 [![React 19](https://img.shields.io/badge/React-19.x-61dafb?style=flat-square&logo=react)](https://alexandro.net/docs/react/multiselect/react-19/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org)
-[![GitHub stars](https://img.shields.io/github/stars/alexandroit/react-multiselect-dropdown.svg?style=flat-square)](https://github.com/alexandroit/react-multiselect-dropdown/stargazers)
+[![Reddit community](https://img.shields.io/badge/community-r%2FStackline-ff4500?style=flat-square&logo=reddit&logoColor=white)](https://www.reddit.com/r/Stackline/)
 
-**[Documentation & Live Demos](https://alexandro.net/docs/react/multiselect/)** | **[React 19 Demo](https://alexandro.net/docs/react/multiselect/react-19/)** | **[React 19 StackBlitz](https://stackblitz.com/github/alexandroit/stackline-react-multiselect-react-19?file=src%2Fexamples%2Fbasic%2Fbasic.component.tsx&startScript=start&initialpath=%2Fbasic)** | **[npm](https://www.npmjs.com/package/@stackline/react-multiselect-dropdown)** | **[Issues](https://github.com/alexandroit/react-multiselect-dropdown/issues)** | **[Repository](https://github.com/alexandroit/react-multiselect-dropdown)**
+**[Documentation & Live Demos](https://alexandro.net/docs/react/multiselect/)** | **[React 19 Demo](https://alexandro.net/docs/react/multiselect/react-19/)** | **[React 19 StackBlitz](https://stackblitz.com/github/alexandroit/stackline-react-multiselect-react-19?file=src%2Fexamples%2Fbasic%2Fbasic.component.tsx&startScript=start&initialpath=%2Fbasic)** | **[npm](https://www.npmjs.com/package/@stackline/react-multiselect-dropdown)** | **[Issues](https://github.com/alexandroit/react-multiselect-dropdown/issues)** | **[Repository](https://github.com/alexandroit/react-multiselect-dropdown)** | **[Community Discussions](https://www.reddit.com/r/Stackline/)**
 
-**Latest React 19 release:** `19.1.0` for React `19.x`
+<p align="center">
+  <img src="https://alexandro.net/images/public/2026/06/dropdownlist.gif" alt="@stackline/react-multiselect-dropdown live dropdown preview" width="420">
+</p>
+
+**Latest React 19 release:** `19.1.2` for React `19.x`
 
 ---
 
@@ -26,7 +29,7 @@
 
 The package is built around a controlled React API: pass `data`, bind `selectedItems`, receive updates through `onChange`, and customize behavior through a `settings` object. It also supports a Slots API for replacing component structure without losing ARIA/focus behavior, a headless `useMultiSelectDropdown` hook, a lower-level `useMultiSelectState` hook, custom React render functions for option rows and selected badges, lazy loading callbacks, imperative `ref` methods, and body-overlay positioning for dialogs or clipped containers.
 
-The current stable React 19 release is `19.1.0`. It adds guided structural slots, a headless hook, a state hook, a type-safe factory helper, and a strengthened combobox contract while keeping the styled `<MultiSelectDropdown />` component compatible with the existing visual contract.
+The current stable React 19 release is `19.1.2`. It adds guided structural slots, a headless hook, a state hook, a type-safe factory helper, and a strengthened combobox contract while keeping the styled `<MultiSelectDropdown />` component compatible with the existing visual contract.
 
 ## Features
 
@@ -83,17 +86,17 @@ Each package family installs on its matching React family. Keep the package fami
 
 | Package family | React family | Peer range | Tested release window | Demo link |
 | :---: | :---: | :---: | :---: | :--- |
-| **17.x** | **React 17 only** | **`>=17.0.0 <18.0.0`** | **17.0.0 -> 17.0.2** | [React 17 family docs](https://alexandro.net/docs/react/multiselect/react-17/) |
-| **18.x** | **React 18 only** | **`>=18.0.0 <19.0.0`** | **18.0.0 -> 18.3.1** | [React 18 family docs](https://alexandro.net/docs/react/multiselect/react-18/) |
-| **19.x** | **React 19 only** | **`>=19.0.0 <20.0.0`** | **19.1.0 -> 19.2.4** | [React 19 family docs](https://alexandro.net/docs/react/multiselect/react-19/) |
+| **17.x** | **React 17 only** | **`>=17.0.0 <18.0.0`** | **17.0.1 -> 17.0.2** | [React 17 family docs](https://alexandro.net/docs/react/multiselect/react-17/) |
+| **18.x** | **React 18 only** | **`>=18.0.0 <19.0.0`** | **18.0.1 -> 18.3.1** | [React 18 family docs](https://alexandro.net/docs/react/multiselect/react-18/) |
+| **19.x** | **React 19 only** | **`>=19.0.0 <20.0.0`** | **19.1.2 -> 19.2.4** | [React 19 family docs](https://alexandro.net/docs/react/multiselect/react-19/) |
 
 ## Installation
 
 ```bash
-npm install @stackline/react-multiselect-dropdown@19.1.0 --save-exact
+npm install @stackline/react-multiselect-dropdown@19.1.1 --save-exact
 ```
 
-Install `19.1.0` for React 19.x applications. The styled component includes its component styles and injects them at runtime. The headless hook does not inject CSS and lets your application own the markup and styling.
+Install `19.1.2` for React 19.x applications. The styled component includes its component styles and injects them at runtime. The headless hook does not inject CSS and lets your application own the markup and styling.
 
 ## Setup
 
@@ -478,7 +481,7 @@ The styled component remains available for drop-in usage. The headless hooks are
 
 ## Combobox Contract
 
-Version `19.1.0` tightens the interaction details that usually matter most in production forms:
+Version `19.1.2` tightens the interaction details that usually matter most in production forms:
 
 | Behavior | Contract |
 | :--- | :--- |
@@ -522,6 +525,13 @@ Use the dedicated React 19 StackBlitz project when you want a fast editable exam
 | Example | StackBlitz |
 | :--- | :--- |
 | Basic usage | [Open](https://stackblitz.com/github/alexandroit/stackline-react-multiselect-react-19?file=src%2Fexamples%2Fbasic%2Fbasic.component.tsx&startScript=start&initialpath=%2Fbasic) |
+| Keyboard contract | [Open](https://stackblitz.com/github/alexandroit/stackline-react-multiselect-react-19?file=src%2Fexamples%2Fkeyboard-contract%2Fkeyboard-contract.component.tsx&startScript=start&initialpath=%2Fkeyboard-contract) |
+| ARIA state audit | [Open](https://stackblitz.com/github/alexandroit/stackline-react-multiselect-react-19?file=src%2Fexamples%2Faria-state%2Faria-state.component.tsx&startScript=start&initialpath=%2Faria-state) |
+| Headless + ARIA | [Open](https://stackblitz.com/github/alexandroit/stackline-react-multiselect-react-19?file=src%2Fexamples%2Fheadless-aria%2Fheadless-aria.component.tsx&startScript=start&initialpath=%2Fheadless-aria) |
+| State hook | [Open](https://stackblitz.com/github/alexandroit/stackline-react-multiselect-react-19?file=src%2Fexamples%2Fstate-hook%2Fstate-hook.component.tsx&startScript=start&initialpath=%2Fstate-hook) |
+| Slots API | [Open](https://stackblitz.com/github/alexandroit/stackline-react-multiselect-react-19?file=src%2Fexamples%2Fslots-api%2Fslots-api.component.tsx&startScript=start&initialpath=%2Fslots-api) |
+| Type-safe factory | [Open](https://stackblitz.com/github/alexandroit/stackline-react-multiselect-react-19?file=src%2Fexamples%2Ftype-safe-factory%2Ftype-safe-factory.component.tsx&startScript=start&initialpath=%2Ftype-safe-factory) |
+| Async object preservation | [Open](https://stackblitz.com/github/alexandroit/stackline-react-multiselect-react-19?file=src%2Fexamples%2Fasync-object-preservation%2Fasync-object-preservation.component.tsx&startScript=start&initialpath=%2Fasync-object-preservation) |
 | Single selection | [Open](https://stackblitz.com/github/alexandroit/stackline-react-multiselect-react-19?file=src%2Fexamples%2Fsingle-selection%2Fsingle-selection.component.tsx&startScript=start&initialpath=%2Fsingle-selection) |
 | Search filter | [Open](https://stackblitz.com/github/alexandroit/stackline-react-multiselect-react-19?file=src%2Fexamples%2Fsearch-filter%2Fsearch-filter.component.tsx&startScript=start&initialpath=%2Fsearch-filter) |
 | Custom search from API | [Open](https://stackblitz.com/github/alexandroit/stackline-react-multiselect-react-19?file=src%2Fexamples%2Fcustom-search-api%2Fcustom-search-api.component.tsx&startScript=start&initialpath=%2Fcustom-search-api) |
@@ -549,7 +559,7 @@ Use the dedicated React 19 StackBlitz project when you want a fast editable exam
 
 ## Official React 19 Test Matrix
 
-The React 19 release was tested in a clean React `19.2.4` application with `@stackline/react-multiselect-dropdown@19.1.0`. The docs use the same examples from that test app, including keyboard navigation, focus, ARIA behavior, badge counters, responsive action buttons, scrollable lists, dialog-safe body overlays, the corrected left-aligned placeholder with vertical centering, guided Slots API customization, headless/custom HTML, and the combobox contract checks for Backspace, Escape, focused badge removal, focus, and option ARIA.
+The React 19 release was tested in a clean React `19.2.4` application with `@stackline/react-multiselect-dropdown@19.1.1`. The docs use the same examples from that test app, including keyboard navigation, focus, ARIA behavior, badge counters, responsive action buttons, scrollable lists, dialog-safe body overlays, the corrected left-aligned placeholder with vertical centering, guided Slots API customization, headless/custom HTML, and the combobox contract checks for Backspace, Escape, focused badge removal, focus, and option ARIA.
 
 The same core scenarios are validated for the visual skins:
 

package/dist/index.cjs

@@ -1518,6 +1518,11 @@ function InnerMultiSelectDropdown({
       return;
     }
     if (isSelected(item)) {
+      if (settings.singleSelection) {
+        closeDropdown(true);
+        focusAfterSelectionChange("trigger");
+        return;
+      }
       removeItem(item, focusTarget);
       return;
     }
@@ -1928,7 +1933,7 @@ function InnerMultiSelectDropdown({
     }
     if (event.key === "Enter" || isSpaceKey(event.key)) {
       event.preventDefault();
-      const willClose = !isSelected(item) && (settings.singleSelection || settings.closeDropDownOnSelection);
+      const willClose = settings.singleSelection || !isSelected(item) && settings.closeDropDownOnSelection;
       const currentOptionId = event.currentTarget.id;
       const moveToNextOption = isSpaceKey(event.key) && settings.keyboard.spaceOptionAction === "toggle-and-next";
       selectItem(item, willClose ? "trigger" : "none");
@@ -2120,7 +2125,7 @@ function InnerMultiSelectDropdown({
         if (disabled) {
           return;
         }
-        const willClose = !isSelected(item) && (settings.singleSelection || settings.closeDropDownOnSelection);
+        const willClose = settings.singleSelection || !isSelected(item) && settings.closeDropDownOnSelection;
         selectItem(item, willClose ? "trigger" : "none");
         if (!willClose) {
           focusOptionAfterPointerSelection(optionId, optionIndex);
@@ -2610,6 +2615,10 @@ function useMultiSelectState({
       return;
     }
     if (isSelected(item)) {
+      if (settings.singleSelection) {
+        onSelectionShouldClose?.();
+        return;
+      }
       removeItem(item);
       return;
     }
@@ -2934,7 +2943,7 @@ function useMultiSelectDropdown({
   };
   const selectItem = (item, focusTarget = "search") => {
     const wasSelected = state.isSelected(item);
-    const willClose = !wasSelected && (settings.singleSelection || settings.closeDropDownOnSelection);
+    const willClose = settings.singleSelection || !wasSelected && settings.closeDropDownOnSelection;
     state.selectItem(item);
     focusAfterSelectionChange(willClose ? "trigger" : focusTarget);
   };
@@ -3049,7 +3058,7 @@ function useMultiSelectDropdown({
       event.preventDefault();
       const enabledOptions2 = options.filter((currentOption) => !currentOption.disabled);
       const currentEnabledIndex2 = enabledOptions2.findIndex((currentOption) => currentOption.id === option.id);
-      const willClose = !state.isSelected(option.item) && (settings.singleSelection || settings.closeDropDownOnSelection);
+      const willClose = settings.singleSelection || !state.isSelected(option.item) && settings.closeDropDownOnSelection;
       const moveToNextOption = isSpaceKey2(event.key) && settings.keyboard.spaceOptionAction === "toggle-and-next";
       selectItem(option.item, willClose ? "trigger" : "none");
       if (!willClose) {
@@ -3286,7 +3295,7 @@ function useMultiSelectDropdown({
           if (option.disabled) {
             return;
           }
-          const willClose = !state.isSelected(option.item) && (settings.singleSelection || settings.closeDropDownOnSelection);
+          const willClose = settings.singleSelection || !state.isSelected(option.item) && settings.closeDropDownOnSelection;
           selectItem(option.item, willClose ? "trigger" : "none");
           if (!willClose) {
             setActiveOptionIndex(option.index);

package/dist/index.js

@@ -1497,6 +1497,11 @@ function InnerMultiSelectDropdown({
       return;
     }
     if (isSelected(item)) {
+      if (settings.singleSelection) {
+        closeDropdown(true);
+        focusAfterSelectionChange("trigger");
+        return;
+      }
       removeItem(item, focusTarget);
       return;
     }
@@ -1907,7 +1912,7 @@ function InnerMultiSelectDropdown({
     }
     if (event.key === "Enter" || isSpaceKey(event.key)) {
       event.preventDefault();
-      const willClose = !isSelected(item) && (settings.singleSelection || settings.closeDropDownOnSelection);
+      const willClose = settings.singleSelection || !isSelected(item) && settings.closeDropDownOnSelection;
       const currentOptionId = event.currentTarget.id;
       const moveToNextOption = isSpaceKey(event.key) && settings.keyboard.spaceOptionAction === "toggle-and-next";
       selectItem(item, willClose ? "trigger" : "none");
@@ -2099,7 +2104,7 @@ function InnerMultiSelectDropdown({
         if (disabled) {
           return;
         }
-        const willClose = !isSelected(item) && (settings.singleSelection || settings.closeDropDownOnSelection);
+        const willClose = settings.singleSelection || !isSelected(item) && settings.closeDropDownOnSelection;
         selectItem(item, willClose ? "trigger" : "none");
         if (!willClose) {
           focusOptionAfterPointerSelection(optionId, optionIndex);
@@ -2595,6 +2600,10 @@ function useMultiSelectState({
       return;
     }
     if (isSelected(item)) {
+      if (settings.singleSelection) {
+        onSelectionShouldClose?.();
+        return;
+      }
       removeItem(item);
       return;
     }
@@ -2919,7 +2928,7 @@ function useMultiSelectDropdown({
   };
   const selectItem = (item, focusTarget = "search") => {
     const wasSelected = state.isSelected(item);
-    const willClose = !wasSelected && (settings.singleSelection || settings.closeDropDownOnSelection);
+    const willClose = settings.singleSelection || !wasSelected && settings.closeDropDownOnSelection;
     state.selectItem(item);
     focusAfterSelectionChange(willClose ? "trigger" : focusTarget);
   };
@@ -3034,7 +3043,7 @@ function useMultiSelectDropdown({
       event.preventDefault();
       const enabledOptions2 = options.filter((currentOption) => !currentOption.disabled);
       const currentEnabledIndex2 = enabledOptions2.findIndex((currentOption) => currentOption.id === option.id);
-      const willClose = !state.isSelected(option.item) && (settings.singleSelection || settings.closeDropDownOnSelection);
+      const willClose = settings.singleSelection || !state.isSelected(option.item) && settings.closeDropDownOnSelection;
       const moveToNextOption = isSpaceKey2(event.key) && settings.keyboard.spaceOptionAction === "toggle-and-next";
       selectItem(option.item, willClose ? "trigger" : "none");
       if (!willClose) {
@@ -3271,7 +3280,7 @@ function useMultiSelectDropdown({
           if (option.disabled) {
             return;
           }
-          const willClose = !state.isSelected(option.item) && (settings.singleSelection || settings.closeDropDownOnSelection);
+          const willClose = settings.singleSelection || !state.isSelected(option.item) && settings.closeDropDownOnSelection;
           selectItem(option.item, willClose ? "trigger" : "none");
           if (!willClose) {
             setActiveOptionIndex(option.index);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackline/react-multiselect-dropdown",
-  "version": "19.1.0",
+  "version": "19.1.2",
   "description": "Maintained React 19 multiselect dropdown with accessibility-focused and keyboard/ARIA tested support, controlled state, slots, headless/state hooks, Stackline skins, body overlays, live docs, search, grouping, lazy loading, and custom renderers.",
   "keywords": [
     "react",