v6.0 Release (#253)

* Drop usage of `nanoid`

* Drop Less.js support

* Update style format dependencies

* Add `getOptionLabel` and `getOptionValue` props

Resolves #208.

* Update links to latest React docs

* Update options document

* Organize links

* Mention the loss of `id` on some children

* Split `simpleValue={false}` into its own wrapper component

Having both `simpleValue={true}` and simplevalue={false}` mixed into the core component logic made things messy and unwiedly. By separating concerns, the primary component becomes simpler and easier to maintain.

* Fix lint error

* Make default filter utilize `getOptionLabel`

* Minor rearrangement

* Merge missing keys in `icons` and `lang` with default

* Split `filterPlaceholder` by control key

* Add async search example

This takes a lot of inspiration from #155 by @saltovo.

Co-Authored-By: saltovo <46911969+saltovo@users.noreply.github.com>

* Remove unnecessary state derivation

* Remove extra lines

* Prevent race conditions in `LazyFilterExample`

* Add padding on no options text

* Convert main component into function

* Fix linting error

* Favor selected/available over right/left

Left/right are can be incorrect in certain arrangements. Consistent use of "available" and "selected" is unambiguous and precise, if wordy.

This is unfortunately a major backwards compatibility breakage, but is necesary to make the underyling code and markup more precise and semantic.

* Add migration guide

* Simplify button positioning

* Simplify filter component

* Simplify Action component

* Simplify `showHeaderLabels` logic

* Add additional breaking change to CHANGELOG

* Add more contrast and visibility of text

* Make CHANGELOG language cleaner

* Drop support for React before v16.8

Hooks did not exist before this version.

* Fix bug when double-clicking optgroups

* Make positive changes more prominent

* Remove no longer necessary Unicode escaping

* Default to `'fa6'` for `iconsClass`

Also update CDN links to latest version.

* Put breaking changes first

* Fix matrix resolution

* Drop usage of depreacted `defaultProps`

This necessitated some clever workarounds to share default property values between the main component and `ObjectValueWrapper`. In the end, we have added back in the `simpleValue` property, thus reducing BC breakage.

Resolves #248.

* Improve accessibility of required error

* Conform changelog to a more standardized format

* Fix `required` test

* Change filter input to `type="search"`

Resolves #247.

* Fix example buttons on smaller widths

* Update dependencies

* Slightly improve descriptions and names

* Prefer order over index

* Extract `mergeRefs` into its own function

* Make `userSelections` return label, value, and index

Resolves #230.

* Update dependencies

* Release v6.0

---------

Co-authored-by: saltovo <46911969+saltovo@users.noreply.github.com>

Author: jakezatecky

.github/workflows/main.yml

@@ -8,15 +8,15 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node: ['14', '16', '18']
+        node: [18, 20]
     steps:
       -
         uses: actions/checkout@v3
       -
-        name: Use Node.js ${{ matrix.node-version }}
+        name: Use Node.js ${{ matrix.node }}
         uses: actions/setup-node@v3
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: ${{ matrix.node }}
       -
         name: Install dependencies
         run: yarn install

.gitignore

@@ -1,4 +1,3 @@
-/.css-compare
 /examples/dist
 /lib
 /node_modules

CHANGELOG.md

@@ -1,6 +1,57 @@
-# CHANGELOG
+# Changelog
 
-## [v5.0.2]((https://github.com/jakezatecky/react-dual-listbox/compare/v5.0.1...v5.0.2)) (2023-02-08)
+## [6.0.0](https://github.com/jakezatecky/react-dual-listbox/compare/v5.0.2...v6.0.0) (2023-12-06)
+
+_This new version includes a variety of breaking changes. Please review them before upgrading._
+
+### Added
+
+* Add `getOptionLabel` and `getOptionValue` properties to allow for custom keys beyond `label` and `value` (#208)
+* Add `LazyFilterExample.jsx` to demonstrate lazy loading for the `options` property by user search
+
+### Changed
+
+* **Breaking:** `onChange` property: the second argument now returns objects with `label`, `index`, and `value`, instead of just values (#230)
+* **Breaking:** `icons` property:
+  * Will now merge any missing keys with the default icons
+  * Rename `moveLeft`, `moveAllLeft`, `moveRight`, and `moveAllRight` to `moveToAvailable`, `moveAllToAvailable`, `moveToSelected`, and `moveAllToSelected`
+* **Breaking:** `iconsClass` property: now defaults to `'fa6'`
+* **Breaking:** `id` property: no longer defaults to a random UUID when null and no longer used for some child components
+* **Breaking:** `lang` property:
+  * Will now merge any missing keys with the default language
+  * Rename `moveLeft`, `moveAllLeft`, `moveRight`, and `moveAllRight` to `moveToAvailable`, `moveAllToAvailable`, `moveToSelected`, and `moveAllToSelected`
+  * Split `filterPlaceholder` into `availableFilterPlaceholder` and `selectedFilterPlaceholder`
+* **Breaking:** `options` property: no longer has PropTypes validation for `label` and `value` (#208)
+* **Breaking:** Rename `*-right` and `*-left` classes to `*-to-selected` and `*-to-available`
+* Improve accessibility of required error
+* Change filter input to `type="search"` (#247)
+
+### Removed
+
+* **Breaking:** Drop support for Less.js styles
+* **Breaking:** Drop support for React before v16.8
+* **Breaking:** Remove `rdl-sr-only` class
+* Drop usage of deprecated `defaultProps` (#248)
+
+### Fixed
+
+* Fix positioning of action buttons relative to the list boxes
+* Prevent situation where double-clicking an `optgroup` moved any selected options under it
+
+### `icons` and `lang` Migration Guide
+
+The keys `moveLeft`, `moveAllLeft`, `moveRight`, and `moveAllRight` are now `moveToAvailable`, `moveAllToAvailable`, `moveToSelected`, and `moveAllToSelected` in all instances. Refer to the table below to rename any affected `icons` or `lang` keys:
+
+| Old Key Name   | New Key Name         |
+| -------------- | -------------------- |
+| `moveLeft`     | `moveToAvailable`    |
+| `moveAllLeft`  | `moveAllToAvailable` |
+| `moveRight`    | `moveToSelected`     |
+| `moveAllRight` | `moveAllToSelected`  |
+
+### Other
+
+## [v5.0.2](https://github.com/jakezatecky/react-dual-listbox/compare/v5.0.1...v5.0.2) (2023-02-08)
 
 ### Bug Fixes
 
@@ -95,7 +146,7 @@
 ### New Features
 
 * [#80]: Add `disabled` support for elements in the `options` property
-* [#87]: Add `title` support for elements in the `options` property 
+* [#87]: Add `title` support for elements in the `options` property
 * [#90]: Add `selection` argument to the `onChange` handler to track highlighted values
 * [#104]: Add `className` property to allow specification of a custom class on the root node
 * [#133]: Add `moveTop` and `moveBottom` buttons to `showOrderButtons` property

README.md

@@ -28,10 +28,9 @@ npm install react-dual-listbox --save
 
 ### Include CSS
 
-For your convenience, the library's styles can be consumed utilizing one of the following files:
+The library's styles are available through one of the following files:
 
 * `node_modules/react-dual-listbox/lib/react-dual-listbox.css`
-* `node_modules/react-dual-listbox/src/less/react-dual-listbox.less`
 * `node_modules/react-dual-listbox/src/scss/react-dual-listbox.scss`
 
 Either include one of these files in your stylesheets or utilize a CSS loader:
@@ -42,13 +41,14 @@ import 'react-dual-listbox/lib/react-dual-listbox.css';
 
 ### Render Component
 
-The `DualListBox` is a [controlled] component, so you have to update the `selected` property in conjunction with the `onChange` handler if you want the selected values to change.
+The `DualListBox` is a [controlled][react-controlled] component, so you have to update the `selected` property in conjunction with the `onChange` handler if you want the selected values to change.
 
 Here is a minimal rendering of the component:
 
 ``` jsx
 import React, { useState } from 'react';
 import DualListBox from 'react-dual-listbox';
+import 'react-dual-listbox/lib/react-dual-listbox.css';
 
 const options = [
     { value: 'one', label: 'Option One' },
@@ -142,12 +142,12 @@ Optionally, you can also override the default filter placeholder text and the fi
 ``` jsx
 <DualListBox
     canFilter
-    filterCallback={(option, filterInput) => {
+    filterCallback={(option, filterInput, { getOptionLabel }) => {
         if (filterInput === '') {
             return true;
         }
 
-        return (new RegExp(filterInput, 'i')).test(option.label);
+        return (new RegExp(filterInput, 'i')).test(getOptionLabel(option));
     }}
     options={options}
 />
@@ -244,19 +244,21 @@ const onChange = (selected, selection, controlKey) => {
 | Property              | Type     | Description                                                                                                             | Default          |
 | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------- |
 | `options`             | array    | **Required**. Specifies the list of options that may exist on either side of the dual list box.                         |                  |
-| `onChange`            | function | **Required**. The handler called when options are moved to either side: `function(selected, selection, controlKey) {}`. |                  |
+| `onChange`            | function | **Required**. The handler called when the selected options change: `function(selected, selection, controlKey) {}`.      |                  |
 | `alignActions`        | string   | A value specifying whether to align the action buttons to the `'top'` or `'middle'`.                                    | `middle`         |
 | `allowDuplicates`     | bool     | If true, duplicate options will be allowed in the selected list box.                                                    | `false`          |
 | `available`           | array    | A subset of the `options` array to optionally filter the available list box.                                            | `undefined`      |
-| `availableRef`        | function | A React function [ref] to the "available" list box.                                                                     | `null`           |
+| `availableRef`        | function | A React function [ref][react-ref] to the "available" list box.                                                          | `null`           |
 | `canFilter`           | bool     | If true, search boxes will appear above both list boxes, allowing the user to filter the results.                       | `false`          |
 | `className`           | string   | An optional `className` to apply to the root node.                                                                      | `null`           |
 | `disabled`            | bool     | If true, both "available" and "selected" list boxes will be disabled.                                                   | `false`          |
 | `filter`              | object   | A key-value map of `{ available: [value], selected: [value] }` to control the filter values (defaults to uncontrolled). | `null`           |
 | `filterCallback`      | function | The filter function to run on a given option and input string: `function(option, filterInput) {}`. See **Filtering**.   | `() => { ... }`  |
+| `getOptionLabel`      | function | The function to resolve the **label** from an option. Defaults to `option => option.label`.                             | `() => { ... }`  |
+| `getOptionValue`      | function | The function to resolve the **value** from an option. Defaults to `option => option.value`.                             | `() => { ... }`  |
 | `htmlDir`             | string   | The [directionality][mdn-directionality] of the component's elements. Set to `'rtl'` if using a right-to-left language. | `'ltr'`          |
 | `icons`               | object   | A key-value pairing of action icons and their React nodes. See **Changing the Default Icons** for further info.         | `{ ... }`        |
-| `iconsClass`          | string   | A value specifying which overarching icon class to use. Built-in support for `fa5`, `fa6`, and `native` icons.          | `'fa5'`          |
+| `iconsClass`          | string   | A value specifying which overarching icon class to use. Built-in support for `fa5`, `fa6`, and `native` icons.          | `'fa6'`          |
 | `id`                  | string   | An HTML ID prefix for the various sub elements.                                                                         | `null`           |
 | `lang`                | object   | A key-value pairing of localized text. See [`src/js/lang/default.js`][lang-file] for a list of keys.                    | `{ ... }`        |
 | `moveKeys`            | array    | A list of [keyboard keys][mdn-key] that will trigger a toggle of the highlighted options.                               | `[' ', 'Enter']` |
@@ -265,24 +267,24 @@ const onChange = (selected, selection, controlKey) => {
 | `preserveSelectOrder` | bool     | If true, the order in which the available options are selected are preserved when the items are moved to the right.     | `false`          |
 | `required`            | bool     | If true, this component will require `selected` to be non-empty to pass a form validation                               | `false`          |
 | `selected`            | array    | A list of the selected options appearing in the rightmost list box.                                                     | `[]`             |
-| `selectedRef`         | function | A React function [ref] to the "selected" list box.                                                                      | `null`           |
-| `simpleValue`         | bool     | If true, the `selected` value passed in `onChange` is an array of string values. Otherwise, it is an array of options.  | `true`           |
+| `selectedRef`         | function | A React function [ref][react-ref] to the "selected" list box.                                                           | `null`           |
 | `showHeaderLabels`    | bool     | If true, labels above both the available and selected list boxes will appear. These labels derive from `lang`.          | `false`          |
 | `showNoOptionsText`   | bool     | If true, text will appear in place of the available/selected list boxes when no options are present.                    | `false`          |
 | `showOrderButtons`    | bool     | If true, a set of up/down buttons will appear near the selected list box to allow the user to re-arrange the items.     | `false`          |
+| `simpleValue`         | bool     | If true, the `selected` value passed in `onChange` is an array of string values. Otherwise, it is an array of options.  | `true`           |
 
 #### Option Properties
 
-| Property   | Type   | Description                                                   |
-| ---------- | ------ | ------------------------------------------------------------- |
-| `label`    | string | **Required**. The text label for the given option.            |
-| `value`    | mixed  | **Required**. The text or numeric value for the given option. |
-| `disabled` | bool   | If true, disables the option from selection.                  |
-| `title`    | string | Adds the HTML `title` attribute to the option.                |
+| Property   | Type   | Description                                                                                                |
+| ---------- | ------ | ---------------------------------------------------------------------------------------------------------- |
+| `label`    | string | **Required**. The text label for the given option. Use `getOptionLabel` to set a different key.            |
+| `value`    | mixed  | **Required**. The text or numeric value for the given option. Use `getOptionValue` to set a different key. |
+| `disabled` | bool   | If true, disables the option from selection.                                                               |
+| `title`    | string | Adds the HTML `title` attribute to the option.                                                             |
 
-[controlled]: https://facebook.github.io/react/docs/forms.html#controlled-components
+[react-controlled]: https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components
+[react-ref]: https://react.dev/learn/manipulating-the-dom-with-refs
 [font-awesome]: https://fontawesome.com
 [lang-file]: https://github.com/jakezatecky/react-dual-listbox/blob/master/src/js/lang/default.js
 [mdn-directionality]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir
 [mdn-key]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key
-[ref]: https://reactjs.org/docs/refs-and-the-dom.html

examples/src/index.html

@@ -6,9 +6,12 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="theme-color" content="#3498db">
     <meta name="description" content="React Dual Listbox: A feature-rich dual listbox for React.">
-    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/normalize/8.0.1/normalize.min.css">
-    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/font-awesome/5.9.0/css/all.min.css">
-    <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Open+Sans:400,700">
+
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;700&display=swap">
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/normalize/8.0.1/normalize.min.css">
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
     <link rel="stylesheet" href="./scss/style.scss">
 
     <!-- Google tag (gtag.js) -->
@@ -33,8 +36,9 @@ <h2 class="project-tagline">A feature-rich dual listbox for React</h2>
     <section class="main-content">
       <p>
         <strong>React Dual Listbox</strong> is a lightweight React component for rendering dual listbox views.
-        Checkout the examples below and then view <a href="https://github.com/jakezatecky/react-dual-listbox/tree/master/examples/src/js">source code</a>
-        or main <a href="https://github.com/jakezatecky/react-dual-listbox">documentation page</a> when you are ready to try it out.
+        Checkout the examples and <a href="https://github.com/jakezatecky/react-dual-listbox/tree/master/examples/src/js">source code</a>
+        below. Head over to the main <a href="https://github.com/jakezatecky/react-dual-listbox">documentation page</a>
+        to see the full list of options.
       </p>
 
       <h1>Examples</h1>
@@ -59,6 +63,18 @@ <h3>Filter Example</h3>
       </p>
       <div id="filter-example"></div>
 
+      <h3>Lazy Filter Example</h3>
+      <p>
+        The component can support lazy filtering/searching, using the <code>onFilterCallback</code> property. Try
+        searching for “europa” or “io”.
+      </p>
+      <p>
+        See
+        <a href="https://github.com/jakezatecky/react-dual-listbox/blob/master/examples/src/js/LazyFilterExample.jsx"><code>LazyFilterExample.jsx</code></a>
+        for the sample code that includes a mock API request.
+      </p>
+      <div id="lazy-filter-example"></div>
+
       <h3>Align Actions to Top Example</h3>
       <p>
         In addition to having the movement action aligned to the middle of the component, you can arrange them to the

examples/src/index.jsx

@@ -6,6 +6,7 @@ import AllowDuplicatesExample from './js/AllowDuplicatesExample';
 import BasicExample from './js/BasicExample';
 import DisabledExample from './js/DisabledExample';
 import FilterExample from './js/FilterExample';
+import LazyFilterExample from './js/LazyFilterExample';
 import PreserveSelectOrderExample from './js/PreserveSelectOrderExample';
 import OptGroupExample from './js/OptGroupExample';
 import RequiredExample from './js/RequiredExample';
@@ -15,6 +16,7 @@ import RtlExample from './js/RtlExample';
 createRoot(document.getElementById('basic-example')).render(<BasicExample />);
 createRoot(document.getElementById('optgroup-example')).render(<OptGroupExample />);
 createRoot(document.getElementById('filter-example')).render(<FilterExample />);
+createRoot(document.getElementById('lazy-filter-example')).render(<LazyFilterExample />);
 createRoot(document.getElementById('align-top-example')).render(<AlignTopExample />);
 createRoot(document.getElementById('disabled-example')).render(<DisabledExample />);
 createRoot(document.getElementById('preserve-select-order-example')).render(<PreserveSelectOrderExample />);

examples/src/js/AlignTopExample.jsx

@@ -14,6 +14,7 @@ function AlignTopExample() {
         <DualListBox
             alignActions="top"
             canFilter
+            id="align-top"
             options={options}
             selected={selected}
             onChange={onChange}

examples/src/js/AllowDuplicatesExample.jsx

@@ -13,6 +13,7 @@ function AllowDuplicatesExample() {
     return (
         <DualListBox
             allowDuplicates
+            id="allow-duplicates"
             options={options}
             preserveSelectOrder
             selected={selected}

examples/src/js/BasicExample.jsx

@@ -12,6 +12,7 @@ function BasicExample() {
 
     return (
         <DualListBox
+            id="basic"
             options={options}
             selected={selected}
             onChange={onChange}

examples/src/js/DisabledExample.jsx

@@ -14,6 +14,7 @@ function DisabledExample() {
         <DualListBox
             canFilter
             disabled
+            id="disabled"
             options={options}
             selected={selected}
             onChange={onChange}