SelectNext docs

website/sidebars-components.js

@@ -88,6 +88,16 @@ module.exports = {
 								'es-ui-components/select-customization',
 							],
 						},
+						{
+							type: 'category',
+							label: 'Select Next',
+							items: [
+								'es-ui-components/select-next',
+								'es-ui-components/multi-select-next',
+								'es-ui-components/async-select-next',
+								'es-ui-components/async-multi-select-next',
+							],
+						},
 					],
 				},
 

website/ui-components/es-ui-components/async-multi-select-next.mdx

@@ -0,0 +1,71 @@
+# Async multi-select V2
+
+import { ComponentShowcase } from '../components/component-showcase';
+import { __AsyncMultiSelectNext } from '@eightshift/ui-components';
+import { icons } from '@eightshift/ui-components/icons';
+import { demoGetData, slugify } from './select-helpers';
+
+:::info
+This component is currently experimental. List of props is mostly stable, with no major changes expected.
+However, there might be bugs, inconsistencies, or occasional layout issues.
+<br />
+Once fully stable, the component will be renamed to `AsyncMultiSelectNext`.
+<br />
+There are slight differences in behavior, compare to the previous `AsyncMultiSelect`:
+- there are no remove buttons on each item, instead the items are removed by unselecting them in the dropdown
+- `clearable` adds the *Clear* button below the list of options, instead of inline with the options
+:::
+
+<ComponentShowcase defaultValue={[]}>
+	{(data, setData) => (
+		<__AsyncMultiSelectNext
+			value={data}
+			onChange={setData}
+			fetchUrl={(searchText) =>
+				searchText?.length >= 3
+					? `http://universities.hipolabs.com/search?limit=5&name=${searchText}`
+					: 'http://universities.hipolabs.com/search?limit=5&country=croatia'
+			}
+			getLabel={(item) => item?.name}
+			getValue={(item) => item?.value}
+			getSubtitle={(item) => item?.country}
+			getIcon={() => icons.emptyCircle}
+			processLoadedOptions={(items) => items.map((item) => ({ ...item, value: slugify(item?.name) }))}
+		/>
+	)}
+</ComponentShowcase>
+
+```jsx
+<__AsyncMultiSelectNext
+	value={value}
+	onChange={(value) => setValue(value)}
+	fetchUrl={(searchText) =>
+		searchText?.length >= 3 ? `http://example-api.com?limit=5&search=${searchText}` : 'http://example-api.com?limit=5'
+	}
+	getLabel={(item) => item?.name}
+	getValue={(item) => item?.id}
+/>
+```
+
+:::note
+Props are mostly the same as for the [Single select](/components/es-ui-components/select-next),
+with the exceptions of `options` and `simpleValue`.
+:::
+
+For the complete list of props, use your IDE's autocomplete functionality.
+
+## Migration from `AsyncMultiSelect`
+
+1. **Replace `loadOptions`**
+
+	Custom loading functions are currently not supported.
+
+	You can provide the URL to fetch the data from using the `fetchUrl` prop.
+	It provides the search text as an argument.
+
+	If you need to process data after fetching, use the `processLoadedOptions` prop.
+
+2. **Define data points**
+
+	To define how label, value, subtitle (optional), and icon (optional) are defined in the options,
+	use `getLabel`, `getValue`, `getSubtitle`, `getIcon`.

website/ui-components/es-ui-components/async-select-next.mdx

@@ -0,0 +1,60 @@
+# Async single select V2
+
+import { ComponentShowcase } from '../components/component-showcase';
+import { AsyncSelect, AsyncSelectNext } from '@eightshift/ui-components';
+import { icons } from '@eightshift/ui-components/icons';
+import { demoGetData, slugify } from './select-helpers';
+
+<ComponentShowcase defaultValue={[]}>
+	{(data, setData) => (
+		<AsyncSelectNext
+			value={data}
+			onChange={setData}
+			fetchUrl={(searchText) =>
+				searchText?.length >= 3
+					? `http://universities.hipolabs.com/search?limit=5&name=${searchText}`
+					: 'http://universities.hipolabs.com/search?limit=5&country=croatia'
+			}
+			getLabel={(item) => item?.name}
+			getValue={(item) => item?.value}
+			getSubtitle={(item) => item?.country}
+			getIcon={() => icons.emptyCircle}
+			processLoadedOptions={(items) => items.map((item) => ({ ...item, value: slugify(item?.name) }))}
+		/>
+	)}
+</ComponentShowcase>
+
+```jsx
+<AsyncSelectNext
+	value={value}
+	onChange={(value) => setValue(value)}
+	fetchUrl={(searchText) =>
+		searchText?.length >= 3 ? `http://example-api.com?limit=5&search=${searchText}` : 'http://example-api.com?limit=5'
+	}
+	getLabel={(item) => item?.name}
+	getValue={(item) => item?.id}
+/>
+```
+
+:::note
+Props are mostly the same as for the [Single select](/components/es-ui-components/select-next),
+with the exceptions of `options` and `simpleValue`.
+:::
+
+For the complete list of props, use your IDE's autocomplete functionality.
+
+## Migration from `AsyncSelect`
+
+1. **Replace `loadOptions`**
+
+	Custom loading functions are currently not supported.
+
+	You can provide the URL to fetch the data from using the `fetchUrl` prop.
+	It provides the search text as an argument.
+
+	If you need to process data after fetching, use the `processLoadedOptions` prop.
+
+2. **Define data points**
+
+	To define how label, value, subtitle (optional), and icon (optional) are defined in the options,
+	use `getLabel`, `getValue`, `getSubtitle`, `getIcon`.

website/ui-components/es-ui-components/multi-select-next.mdx

@@ -0,0 +1,45 @@
+# Multi-select V2
+
+import { ComponentShowcase } from '../components/component-showcase';
+import { __MultiSelectNext } from '@eightshift/ui-components';
+import { icons } from '@eightshift/ui-components/icons';
+import { demoOptions } from './select-helpers';
+
+:::info
+This component is currently experimental. List of props is mostly stable, with no major changes expected.
+However, there might be bugs, inconsistencies, or occasional layout issues.
+<br />
+Once fully stable, the component will be renamed to `MultiSelectNext`.
+<br />
+There are slight differences in behavior, compare to the previous `MultiSelect`:
+- there are no remove buttons on each item, instead the items are removed by unselecting them in the dropdown
+- `clearable` adds the *Clear* button below the list of options, instead of inline with the options
+:::
+
+<ComponentShowcase defaultValue={[]}>
+	{(data, setData) => (
+		<__MultiSelectNext
+			value={data}
+			onChange={setData}
+			options={demoOptions}
+		/>
+	)}
+</ComponentShowcase>
+
+```jsx
+<__MultiSelectNext
+	value={value}
+	onChange={(value) => setValue(value)}
+	options={[
+		{ value: 'option-1', label: 'Option 1' },
+		{ value: 'option-2', label: 'Option 2' },
+		{ value: 'option-3', label: 'Option 3' },
+	]}
+/>
+```
+
+:::note
+Props are the same as for the [Single select](/components/es-ui-components/select-next).
+:::
+
+For the complete list of props, use your IDE's autocomplete functionality.

website/ui-components/es-ui-components/select-helpers.js

@@ -97,3 +97,15 @@ export const CustomMultiValueDisplay = (props) => {
 		</RSMultiValue>
 	);
 };
+
+export const slugify = (input) => {
+	return input
+		.toString()
+		.toLowerCase()
+		.trim()
+		.replace(/\s+/g, '-')
+		.replace(/[^\w\-]+/g, '')
+		.replace(/\-\-+/g, '-')
+		.replace(/^-+/, '')
+		.replace(/-+$/, '');
+};

website/ui-components/es-ui-components/select-next.mdx

@@ -0,0 +1,138 @@
+# Single select V2
+
+import { ComponentShowcase } from '../components/component-showcase';
+import { SelectNext } from '@eightshift/ui-components';
+import { icons } from '@eightshift/ui-components/icons';
+import { demoOptions } from './select-helpers';
+
+<ComponentShowcase>
+	{(data, setData) => (
+		<SelectNext
+			value={data}
+			onChange={setData}
+			options={demoOptions}
+		/>
+	)}
+</ComponentShowcase>
+
+```jsx
+<SelectNext
+	value={value}
+	onChange={(value) => setValue(value)}
+	options={[
+		{ value: 'option-1', label: 'Option 1' },
+		{ value: 'option-2', label: 'Option 2' },
+		{ value: 'option-3', label: 'Option 3' },
+	]}
+/>
+```
+
+## Highlighted props
+
+For the complete list of props, use your IDE's autocomplete functionality.
+
+### Allow clearing the selected option
+
+<ComponentShowcase defaultValue={null}>
+	{(data, setData) => (
+		<SelectNext
+			value={data}
+			onChange={setData}
+			options={demoOptions}
+			clearable
+		/>
+	)}
+</ComponentShowcase>
+
+```jsx
+<SelectNext
+	value={value}
+	onChange={(value) => setValue(value)}
+	options={[
+		{ value: 'option-1', label: 'Option 1' },
+		{ value: 'option-2', label: 'Option 2' },
+		{ value: 'option-3', label: 'Option 3' },
+	]}
+	// highlight-next-line
+	clearable
+/>
+```
+
+### Search through options
+
+<ComponentShowcase defaultValue={null}>
+	{(data, setData) => (
+		<SelectNext
+			value={data}
+			onChange={setData}
+			options={demoOptions}
+			searchable
+		/>
+	)}
+</ComponentShowcase>
+
+```jsx
+<SelectNext
+	value={value}
+	onChange={(value) => setValue(value)}
+	options={[
+		{ value: 'option-1', label: 'Option 1' },
+		{ value: 'option-2', label: 'Option 2' },
+		{ value: 'option-3', label: 'Option 3' },
+	]}
+	// highlight-next-line
+	searchable
+/>
+```
+
+### Simple value
+
+By default, values are objects with `value` and `label` properties (and optionally `metadata`).
+If you want to use a simple string value, use the `simpleValue` prop.
+
+<ComponentShowcase
+	defaultValue={null}
+	preContent={(data) => (
+		<span className='es:font-mono es:text-xs esd-white-space-pre'>{JSON.stringify(data, null, 2)}</span>
+	)}
+>
+	{(data, setData) => (
+		<SelectNext
+			label='Default'
+			value={data}
+			onChange={setData}
+			options={demoOptions}
+		/>
+	)}
+</ComponentShowcase>
+
+<ComponentShowcase
+	defaultValue={null}
+	preContent={(data) => (
+		<span className='es:font-mono es:text-xs esd-white-space-pre'>{JSON.stringify(data, null, 2)}</span>
+	)}
+>
+	{(data, setData) => (
+		<SelectNext
+			label='Simple value'
+			value={data}
+			onChange={setData}
+			options={demoOptions}
+			simpleValue
+		/>
+	)}
+</ComponentShowcase>
+
+```jsx
+<SelectNext
+	value={value}
+	onChange={(value) => setValue(value)}
+	options={[
+		{ value: 'option-1', label: 'Option 1' },
+		{ value: 'option-2', label: 'Option 2' },
+		{ value: 'option-3', label: 'Option 3' },
+	]}
+	// highlight-next-line
+	simpleValue
+/>
+```