From ad71ee07977b925516b3e99f027ceceaf4e2d9eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Goran=20Alkovi=C4=87?= <77000136+goranalkovic-infinum@users.noreply.github.com> Date: Fri, 25 Jul 2025 13:10:16 +0200 Subject: [PATCH] add select next docs --- website/sidebars-components.js | 10 ++ .../async-multi-select-next.mdx | 71 +++++++++ .../es-ui-components/async-select-next.mdx | 60 ++++++++ .../es-ui-components/multi-select-next.mdx | 45 ++++++ .../es-ui-components/select-helpers.js | 12 ++ .../es-ui-components/select-next.mdx | 138 ++++++++++++++++++ 6 files changed, 336 insertions(+) create mode 100644 website/ui-components/es-ui-components/async-multi-select-next.mdx create mode 100644 website/ui-components/es-ui-components/async-select-next.mdx create mode 100644 website/ui-components/es-ui-components/multi-select-next.mdx create mode 100644 website/ui-components/es-ui-components/select-next.mdx diff --git a/website/sidebars-components.js b/website/sidebars-components.js index 45511a59c..e1be67b19 100644 --- a/website/sidebars-components.js +++ b/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', + ], + }, ], }, diff --git a/website/ui-components/es-ui-components/async-multi-select-next.mdx b/website/ui-components/es-ui-components/async-multi-select-next.mdx new file mode 100644 index 000000000..c252bb6d4 --- /dev/null +++ b/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. +
+Once fully stable, the component will be renamed to `AsyncMultiSelectNext`. +
+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 +::: + + + {(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) }))} + /> + )} + + +```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`. diff --git a/website/ui-components/es-ui-components/async-select-next.mdx b/website/ui-components/es-ui-components/async-select-next.mdx new file mode 100644 index 000000000..712a48b81 --- /dev/null +++ b/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'; + + + {(data, setData) => ( + + 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) }))} + /> + )} + + +```jsx + 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`. diff --git a/website/ui-components/es-ui-components/multi-select-next.mdx b/website/ui-components/es-ui-components/multi-select-next.mdx new file mode 100644 index 000000000..0ac41ca3c --- /dev/null +++ b/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. +
+Once fully stable, the component will be renamed to `MultiSelectNext`. +
+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 +::: + + + {(data, setData) => ( + <__MultiSelectNext + value={data} + onChange={setData} + options={demoOptions} + /> + )} + + +```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. diff --git a/website/ui-components/es-ui-components/select-helpers.js b/website/ui-components/es-ui-components/select-helpers.js index 175d8fb52..92c53e8f0 100644 --- a/website/ui-components/es-ui-components/select-helpers.js +++ b/website/ui-components/es-ui-components/select-helpers.js @@ -97,3 +97,15 @@ export const CustomMultiValueDisplay = (props) => { ); }; + +export const slugify = (input) => { + return input + .toString() + .toLowerCase() + .trim() + .replace(/\s+/g, '-') + .replace(/[^\w\-]+/g, '') + .replace(/\-\-+/g, '-') + .replace(/^-+/, '') + .replace(/-+$/, ''); +}; diff --git a/website/ui-components/es-ui-components/select-next.mdx b/website/ui-components/es-ui-components/select-next.mdx new file mode 100644 index 000000000..1679fe75b --- /dev/null +++ b/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'; + + + {(data, setData) => ( + + )} + + +```jsx + 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 + + + {(data, setData) => ( + + )} + + +```jsx + 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 + + + {(data, setData) => ( + + )} + + +```jsx + 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. + + ( + {JSON.stringify(data, null, 2)} + )} +> + {(data, setData) => ( + + )} + + + ( + {JSON.stringify(data, null, 2)} + )} +> + {(data, setData) => ( + + )} + + +```jsx + 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 +/> +```