@intility/bifrost-react-select 4.0.0-alpha.3

package/src/Select.md

@@ -0,0 +1,410 @@
+<Message header='More props available'>
+This component is a wrapper for react-select. Visit [React Select](https://react-select.com/home) for full documentation.
+
+To see all available props, click [here](https://react-select.com/props).
+</Message>
+
+### Basic Select
+
+```jsx
+const options = [
+  { value: 'Norway', label: 'Norway' },
+  { value: 'Sweden', label: 'Sweden' },
+  { value: 'Denmark', label: 'Denmark' },
+  { value: 'Germany', label: 'Germany' }
+]
+
+;<Select
+  label='Country'
+  placeholder='- Select country -'
+  options={options}
+  description='Select your country of residence'
+/>
+```
+
+You can get and set the currently selected item using `value` and `onChange`.
+
+```jsx
+import { useState } from 'react'
+import { Select, Button } from '@intility/bifrost-react'
+
+const options = [
+  { value: 'Norway', label: 'Norway' },
+  { value: 'Sweden', label: 'Sweden' },
+  { value: 'Denmark', label: 'Denmark' },
+  { value: 'Germany', label: 'Germany' }
+]
+const [selected, setSelected] = useState(options[2])
+
+;<div>
+  <Select
+    label='Country'
+    placeholder='- Select country -'
+    description='Select your country of residence'
+    options={options}
+    value={selected}
+    onChange={item => setSelected(item)}
+  />
+  <p>Selected item: {selected.label}</p>
+  <Button onClick={() => setSelected(options[0])}>Select first option</Button>
+</div>
+```
+
+### Clearable
+
+Use `isClearable` prop for possibility to remove selected option with button.
+
+```jsx
+import { useState } from 'react'
+import { Select } from '@intility/bifrost-react'
+
+const options = [
+  { value: 'Norway', label: 'Norway' },
+  { value: 'Sweden', label: 'Sweden' },
+  { value: 'Denmark', label: 'Denmark' },
+  { value: 'Germany', label: 'Germany' }
+]
+const [selected, setSelected] = useState()
+
+;<Select
+  label='Country'
+  placeholder='- Select country -'
+  options={options}
+  onChange={item => setSelected(item)}
+  isClearable
+/>
+```
+
+### Validation
+
+`Select` can indicate an alert state based on input. Set `state` prop to `alert` to style it accordingly. Meanwhile, use `feedback` to provide additional information.
+
+Use the `required` prop to render `Select` as required. This will add `(required)` text after the label. You can hide this label with `requiredNoLabel`.
+
+<Message header='Read more'>
+  See usage demo at [Forms example](#/Welcome%20to%20Bifrost/Examples/Forms)
+</Message>
+
+```jsx
+import { useState } from 'react'
+import { Select } from '@intility/bifrost-react'
+
+const options = [
+  { value: 'Norway', label: 'Norway' },
+  { value: 'Sweden', label: 'Sweden' },
+  { value: 'Denmark', label: 'Denmark' },
+  { value: 'Germany', label: 'Germany' }
+]
+
+const [selected, setSelected] = useState()
+
+;<Select
+  label='Country'
+  placeholder='- Select country -'
+  description='Select your country of residence'
+  options={options}
+  onChange={item => setSelected(item)}
+  state={selected ? 'default' : 'alert'}
+  feedback={selected ? '' : 'Missing value'}
+  isClearable
+  required
+/>
+```
+
+### Multi Select
+
+Using the `isMulti` prop makes it possible to select multiple options.
+
+```jsx
+import { useState } from 'react'
+import { Select } from '@intility/bifrost-react'
+
+const options = [
+  { value: 'Norway', label: 'Norway' },
+  { value: 'Sweden', label: 'Sweden' },
+  { value: 'Denmark', label: 'Denmark' },
+  { value: 'Finland', label: 'Finland' },
+  { value: 'France', label: 'France' },
+  { value: 'Spain', label: 'Spain' },
+  { value: 'Italy', label: 'Italy' },
+  { value: 'Germany', label: 'Germany' }
+]
+
+const [selected, setSelected] = useState([])
+
+;<Select
+  label='Countries'
+  placeholder='- Select countries -'
+  description='Select countries you have visited'
+  options={options}
+  value={selected}
+  onChange={items => setSelected(items)}
+  isMulti
+/>
+```
+
+### Grouped options
+
+To make grouped options with labels you simply need to structure the `options` value a bit different.
+
+```jsx
+const options = [
+  {
+    label: 'Marvel',
+    options: [
+      { value: 'Iron Man', label: 'Iron Man' },
+      { value: 'Spider-man', label: 'Spider-man' },
+      { value: 'Star Lord', label: 'Star Lord' }
+    ]
+  },
+  {
+    label: 'DC',
+    options: [
+      { value: 'Superman', label: 'Superman' },
+      { value: 'Batman', label: 'Batman' },
+      { value: 'The Flash', label: 'The Flash' }
+    ]
+  }
+]
+
+;<div className='bfl-autocol'>
+  <Select
+    label='Superhero'
+    placeholder='- Select your hero -'
+    options={options}
+  />
+  <Select
+    label='Superheroes'
+    placeholder='- Select multiple heroes -'
+    options={options}
+    isMulti
+  />
+</div>
+```
+
+### Disabled
+
+Disable a `<Select>` with `isDisabled` prop.
+
+You can also disable an option with `isDisabled` property on the option object.
+
+```jsx
+const options = [
+  { value: 'Norway', label: 'Norway' },
+  { value: 'Sweden', label: 'Sweden' },
+  { value: 'Denmark', label: 'Denmark', isDisabled: true },
+  { value: 'Germany', label: 'Germany' }
+]
+
+;<div className='bfl-autocol'>
+  <Select
+    label='Disabled select'
+    placeholder='- Select country -'
+    description='This is a disabled component'
+    isDisabled
+  />
+  <Select
+    label='Disabled option'
+    placeholder='- Select country -'
+    description='Denmark option is disabled'
+    options={options}
+  />
+</div>
+```
+
+### Loading spinner
+
+The `loading` prop displays a loading spinner on the right hand side of the input.
+
+```jsx
+const options = [
+  { value: 'Norway', label: 'Norway' },
+  { value: 'Sweden', label: 'Sweden' },
+  { value: 'Denmark', label: 'Denmark' },
+  { value: 'Germany', label: 'Germany' }
+]
+
+;<Select
+  label='Country'
+  placeholder='- Select country -'
+  options={options}
+  loading
+/>
+```
+
+### Hide label
+
+The `label` prop is required, but you can hide it with `hideLabel`.
+
+```jsx
+const options = [
+  { value: 'Norway', label: 'Norway' },
+  { value: 'Sweden', label: 'Sweden' },
+  { value: 'Denmark', label: 'Denmark' },
+  { value: 'Germany', label: 'Germany' }
+]
+
+;<Select
+  label='Country'
+  hideLabel
+  placeholder='- Select country -'
+  options={options}
+/>
+```
+
+### Async
+
+AsyncSelect can be used to load options from a source as the user types.
+
+Try type 'No' in the demo below
+
+```jsx
+import { useState } from 'react'
+import { AsyncSelect } from '@intility/bifrost-react'
+
+const countries = [
+  { value: 'Norway', label: 'Norway' },
+  { value: 'Sweden', label: 'Sweden' },
+  { value: 'Denmark', label: 'Denmark' },
+  { value: 'Germany', label: 'Germany' }
+]
+
+const [selected, setSelected] = useState()
+
+function getAsyncOptions(inputValue) {
+  return new Promise((resolve, reject) => {
+    const filtered = countries.filter(c =>
+      String(c.label.toLowerCase()).startsWith(inputValue.toLowerCase())
+    )
+
+    resolve(filtered.slice(0, 3))
+  })
+}
+
+;<AsyncSelect
+  label='Country'
+  placeholder='- Select country -'
+  loadOptions={inputValue => getAsyncOptions(inputValue)}
+  onChange={item => setSelected(item)}
+  isClearable
+/>
+```
+
+### Creatable
+
+CreatableSelect can be used to create new options.
+
+Try to type 'England' and add the new option to the component
+
+```jsx
+import { useState } from 'react'
+import { CreatableSelect } from '@intility/bifrost-react'
+
+const countries = [
+  { value: 'Norway', label: 'Norway' },
+  { value: 'Sweden', label: 'Sweden' },
+  { value: 'Denmark', label: 'Denmark' },
+  { value: 'Germany', label: 'Germany' }
+]
+
+const [selected, setSelected] = useState()
+const [options, setOptions] = useState(countries)
+
+const handleCreate = option => {
+  const newOption = {
+    value: option,
+    label: option
+  }
+
+  setOptions(options => [...options, newOption])
+  setSelected(newOption)
+}
+
+;<CreatableSelect
+  label='Country'
+  placeholder='- Select country -'
+  options={options}
+  value={selected}
+  onChange={item => setSelected(item)}
+  onCreateOption={option => handleCreate(option)}
+  isClearable
+/>
+```
+
+### Replace components
+
+`react-select` allows you to [replace internal components](https://react-select.com/components) which allows for more advanced use cases.
+
+Let's say you have a multi-select, but don't want to display a badge for each selected item, but something like "Selected (4)" instead, you can replace the `ValueContainer` component:
+
+```jsx
+import { useState } from 'react'
+import { components } from 'react-select'
+import { Select } from '@intility/bifrost-react'
+
+const ValueContainer = ({ children, ...props }) => {
+  let [values, input] = children
+
+  if (Array.isArray(values)) {
+    // convert array of values to a string that will get displayed
+    values = `Selected (${values.length})`
+  }
+
+  return (
+    <components.ValueContainer {...props}>
+      {values}
+      {input}
+    </components.ValueContainer>
+  )
+}
+
+const options = [
+  { value: 'Norway', label: 'Norway' },
+  { value: 'Sweden', label: 'Sweden' },
+  { value: 'Denmark', label: 'Denmark' },
+  { value: 'Finland', label: 'Finland' },
+  { value: 'France', label: 'France' },
+  { value: 'Spain', label: 'Spain' },
+  { value: 'Italy', label: 'Italy' },
+  { value: 'Germany', label: 'Germany' }
+]
+
+const SelectDemo = () => {
+  const [selected, setSelected] = useState([])
+
+  return (
+    <Select
+      label='Countries'
+      placeholder='- Select countries -'
+      description='Select countries you have visited'
+      options={options}
+      value={selected}
+      onChange={items => setSelected(items)}
+      isMulti
+      // pass in the custom override
+      components={{
+        ValueContainer
+      }}
+    />
+  )
+}
+
+;<SelectDemo />
+```
+
+Bifrost replaces the following components internally:
+
+- ClearIndicator
+- DropdownIndicator
+- Input
+- LoadingIndicator
+- MenuList
+- Option
+
+To use or wrap our components in your own overrides, you can import them from `selectComponents` <Copy text="import { selectComponents } from '@intility/bifrost-react'" />
+
+```jsx static
+import { selectComponents } from '@intility/bifrost-react'
+// ...
+;<selectComponents.Option>...</selectComponents.Option>
+```

package/src/Select.test.tsx

@@ -0,0 +1,118 @@
+import Select from './Select'
+import { render } from '@testing-library/react'
+
+let getByTestId, getByText, queryByText, element, customInput, rerender
+
+beforeEach(() => {
+  const options = [
+    { value: 'Norway', label: 'Norway' },
+    { value: 'Sweden', label: 'Sweden' },
+    { value: 'Denmark', label: 'Denmark' },
+    { value: 'Germany', label: 'Germany' }
+  ]
+
+  const select = render(
+    <Select
+      label='Select country'
+      placeholder='Select country here'
+      options={options}
+    />
+  )
+
+  getByTestId = select.getByTestId
+  getByText = select.getByText
+  queryByText = select.queryByText
+  element = getByTestId('bf-select-container')
+  customInput = getByTestId('bf-select-input')
+  rerender = select.rerender
+  // debug = select.debug
+})
+
+describe('select component', () => {
+  it('renders select component', () => {
+    expect(element)
+  })
+})
+
+describe('select with required label prop', () => {
+  it('renders label text', () => {
+    expect(getByText('Select country'))
+  })
+})
+
+describe('select with className and style', () => {
+  it('renders with custom classname and custom styles', () => {
+    rerender(
+      <Select
+        label='Custom classname'
+        className='custom-classname'
+        style={{ width: '100%' }}
+      />
+    )
+
+    expect(element).toHaveClass('custom-classname')
+    expect(element).toHaveStyle('width: 100%')
+  })
+})
+
+describe('select with description prop', () => {
+  it('renders with text as description', () => {
+    rerender(
+      <Select label='Select country' description='Please select one country' />
+    )
+
+    expect(getByText('Please select one country'))
+  })
+})
+
+describe('select with state and feedback props', () => {
+  it('renders with alert state ', () => {
+    rerender(
+      <Select label='Select country' state='alert' feedback='Missing value ' />
+    )
+
+    expect(element).toHaveClass('bf-select-alert')
+  })
+
+  it('renders with feedback text', () => {
+    rerender(
+      <Select label='Select country' state='alert' feedback='Missing value ' />
+    )
+    const feedback = getByText('Missing value')
+
+    expect(feedback)
+    expect(feedback).toHaveClass('bf-label-feedback')
+    expect(feedback.tagName.toLowerCase()).toBe('div')
+  })
+})
+
+describe('select disabled', () => {
+  it('renders as disabled', () => {
+    rerender(<Select label='Disabled' isDisabled />)
+    // can only test classname, hence isDisabled is a prop for react-select
+    expect(element).toHaveClass('bf-select-disabled')
+  })
+})
+
+describe('select with required/optional props', () => {
+  it('renders as required', () => {
+    rerender(<Select label='This is required' required />)
+
+    expect(customInput).toBeRequired()
+    expect(getByText('(required)'))
+  })
+
+  it('renders as required, but hiding the (required) text', () => {
+    rerender(<Select label='This is required' requiredNoLabel />)
+
+    expect(customInput).toBeRequired()
+    expect(queryByText('(required)')).toBeNull()
+  })
+
+  it('renders as optional with (optional) text', () => {
+    rerender(<Select label='This is optional' optional />)
+
+    expect(customInput).not.toBeRequired()
+    expect(getByText('(optional)'))
+  })
+})