@planningcenter/tapestry-react 2.10.0-rc.2 → 2.10.0-rc.4

package/src/Select/Select.js

@@ -0,0 +1,621 @@
+// @flow
+import React, { Component } from 'react'
+
+import FocusGroup from '../FocusGroup'
+import Icon from '../Icon'
+import Input from '../Input'
+import { ItemList, ItemListController } from '../ItemList'
+import Menu from '../Menu'
+import Popover from '../Popover'
+import Tooltip from '../Tooltip'
+import {
+  generateId,
+  isArray,
+  isFunction,
+  isValueInArray,
+  joinChildren,
+  shallowEqual,
+} from '../utils'
+
+import { SELECT_DISPLAY_NAME } from './constants'
+import SelectContext from './Context'
+import Value from './Value'
+import { getSelectedOptions, optionsToElements, renderOptions } from './utils'
+
+type Props = {
+  /**
+   * The value to show when nothing is selected
+   */
+  emptyValue?: any,
+  /**
+   * Disables the select.
+   */
+  disabled?: boolean,
+  /**
+   * Gain access to the internal ref
+   */
+  innerRef?: any,
+  /**
+   * Controls the initial Popover state: open or closed (default).
+   */
+  defaultOpen?: boolean,
+  /**
+   * Allows multiple selection of values. Note that value must be an array if
+   * using a controlled component and multiple is true.
+   */
+  multiple?: boolean,
+  /**
+   * Sets internal hidden input[s] to the current selected value[s]. Useful for components
+   * that collect data outside of React and need to be posted to a form.
+   */
+  name?: string,
+  /**
+   * Callback when an option has been selected/deselected.
+   * returns { value, selectedValue }
+   */
+  onChange?: Function,
+  /**
+   * Maps to the select's `onFocus` prop.
+   */
+  onFocus?: () => null,
+
+  /**
+   * Maps to the select's `onBlur` prop.
+   */
+  onBlur?: () => null,
+  onClick?: Function,
+  onMouseUp?: Funtion,
+  onMouseDown?: Funtion,
+  onKeyUp?: Funtion,
+  onKeyDown?: Funtion,
+  /**
+   * Usually accepts `Select.OptionGroup` and `Select.Option`.
+   */
+  children?: any,
+  /**
+   * Pass an object instead of `children` for use when rendering in a non React environment.
+   */
+  options?: Array<{
+    label?: string,
+    optgroup?: Array<{
+      label?: string,
+      value?: any,
+    }>,
+    value?: any,
+  }>,
+  /**
+   * Control how the selected value is displayed.
+   */
+  renderValue?: number | string | React.Element | Array<any> | Function,
+  /**
+   * Wraps `Select` in a `Tooltip` component. Accepts any valid `Tooltip` props.
+   */
+  tooltip?: Object,
+  /**
+   * Selected value[s]. Accepts any value besides `undefined`, also accepts a function that returns
+   * each `Option`'s `value` to determine what should be currently selected.
+   */
+  value?: boolean | string | number | Array<any> | Function,
+  /**
+   * Initial `value` when component is uncontrolled.
+   */
+  defaultValue?: boolean | string | number | Array<any> | Function,
+  /**
+   * Locks external scrollbars when open.
+   */
+  lockScrollWhileOpen?: boolean,
+  /**
+   * Matches anchor and popover widths.
+   */
+  matchWidths?: boolean | 'minimum',
+  /**
+   * Attempts to keep popover in view clipping edges if too large.
+   */
+  keepInView?: boolean,
+  /** 
+   * `'top-start'
+    | 'top'
+    | 'top-end'
+    | 'right-start'
+    | 'right'
+    | 'right-end'
+    | 'bottom-start'
+    | 'bottom'
+    | 'bottom-end'
+    | 'left-start'
+    | 'left'
+    | 'left-end'`
+
+   * Where to place the popover. 
+  */
+  placement?: string,
+  /**
+   * Where to render the popover into. Accepts an HTML element or selector.
+   * Uses the closest fixed parent or `document.body` by default. This will only
+   * be computed once on initial render.
+   */
+  renderTo?: HTMLElement | string,
+  /**
+   * Accepts any valid [Popover](/popover) props.
+   */
+  popoverProps?: object,
+}
+
+function MenuList(props) {
+  return <Menu {...props} as="ul" />
+}
+
+class Select extends Component<Props> {
+  static displayName = SELECT_DISPLAY_NAME
+
+  static defaultProps = {
+    emptyValue: <Value>Select an item</Value>,
+    defaultOpen: false,
+    lockScrollWhileOpen: true,
+    matchWidths: 'minimum',
+    renderValue: (selectedOptions) => (
+      <Value>
+        {joinChildren(selectedOptions.map((option) => option.children))}
+      </Value>
+    ),
+  }
+
+  id = generateId('select')
+
+  canCallFocus = true
+
+  contextValue = {
+    multiple: this.props.multiple,
+    canSelectOption: {
+      current: false,
+    },
+  }
+
+  state = {
+    isPopoverOpen: this.props.defaultOpen,
+    isPopoverVisible: false,
+    selectedOptions: [],
+    uncontrolledValue:
+      this.props.defaultValue === undefined
+        ? this.props.multiple
+          ? []
+          : null
+        : this.props.defaultValue,
+  }
+
+  componentDidMount() {
+    if (typeof document !== 'undefined') {
+      document.addEventListener('mouseup', this.clearUserSelectStyle)
+    }
+    this.setSelectedOptions()
+  }
+
+  componentDidUpdate() {
+    if (this.isControlled()) {
+      this.setSelectedOptions()
+    }
+  }
+
+  componentWillUnmount() {
+    if (typeof document !== 'undefined') {
+      document.removeEventListener('mouseup', this.clearUserSelectStyle)
+      this.clearUserSelectStyle()
+    }
+  }
+
+  addUserSelectStyle = () => {
+    document.body.style.webkitUserSelect = 'none'
+  }
+
+  clearUserSelectStyle = () => {
+    document.body.style.webkitUserSelect = ''
+  }
+
+  isControlled() {
+    return this.props.value !== undefined
+  }
+
+  openPopover = (isPopoverVisible) => {
+    if (isPopoverVisible) {
+      // prevent options from being selected immediately
+      setTimeout(() => {
+        this.contextValue.canSelectOption.current = true
+      }, 300)
+
+      // TODO: use better method for moving scrollbar to selected option
+      // ideally we would open menu exactly on top of selected item's location
+      setTimeout(() => {
+        const { selectedOptions } = this.state
+        if (selectedOptions.length > 0) {
+          this.itemList.scrollItemIntoViewByIndex(selectedOptions[0].index)
+        }
+      })
+    }
+    this.setState({ isPopoverOpen: true, isPopoverVisible })
+  }
+
+  closePopover = () => {
+    this.contextValue.canSelectOption.current = false
+    this.setState({ isPopoverOpen: false, isPopoverVisible: false })
+    if (this.itemList) {
+      this.itemList.clearHighlightedIndex()
+    }
+  }
+
+  togglePopover = () => {
+    if (this.state.isPopoverVisible) {
+      if (this.state.isPopoverOpen) {
+        this.closePopover()
+      } else {
+        this.openPopover(true)
+      }
+    } else {
+      this.openPopover(true)
+    }
+  }
+
+  setSelectedOptions() {
+    const options = this.props.options
+      ? optionsToElements(this.props.options)
+      : this.props.children
+    const nextSelectedOptions = getSelectedOptions(options, this.getSelected)
+    if (
+      !shallowEqual(
+        this.state.selectedOptions.map((option) => option.value),
+        nextSelectedOptions.map((option) => option.value)
+      )
+    ) {
+      this.setState({ selectedOptions: nextSelectedOptions })
+    }
+  }
+
+  getSortedSelectedOptions(value) {
+    return [...this.state.selectedOptions].sort(
+      (a, b) => isValueInArray(value, a.value) - isValueInArray(value, b.value)
+    )
+  }
+
+  getValue = () => {
+    if (this.state.selectedOptions.length > 0) {
+      const value = this.isControlled()
+        ? this.props.value
+        : this.state.uncontrolledValue
+      return this.props.renderValue(
+        isArray(value)
+          ? this.getSortedSelectedOptions(value)
+          : this.state.selectedOptions
+      )
+    } else {
+      return this.props.emptyValue
+    }
+  }
+
+  getHiddenInputValues = () => {
+    const { name } = this.props
+    const { selectedOptions } = this.state
+    return name && selectedOptions.length > 0
+      ? selectedOptions.map((option, index) => (
+          <input key={index} name={name} type="hidden" value={option.value} />
+        ))
+      : null
+  }
+
+  getSelected = (item) => {
+    const { value } = this.props
+    const { uncontrolledValue } = this.state
+    return this.isControlled()
+      ? isFunction(value)
+        ? value(item)
+        : isArray(value)
+        ? isValueInArray(value, item) > -1
+        : value === item
+      : isArray(uncontrolledValue)
+      ? isValueInArray(uncontrolledValue, item) > -1
+      : uncontrolledValue === item
+  }
+
+  handleSelect = (item) => {
+    const { multiple, value } = this.props
+    let newValue = item
+
+    if (!this.isControlled()) {
+      if (multiple) {
+        newValue = Select.toggleValue(this.state.uncontrolledValue, item)
+      }
+      this.setState({ uncontrolledValue: newValue }, this.setSelectedOptions)
+    } else if (isArray(value)) {
+      newValue = Select.toggleValue(this.props.value, item)
+    }
+
+    if (this.props.onChange) {
+      this.props.onChange({
+        selectedValue: item,
+        value: newValue,
+      })
+    }
+
+    if (!multiple && this.state.isPopoverVisible) {
+      this.focusInput()
+    }
+  }
+
+  highlightFirstSelectedOption = () => {
+    const { selectedOptions } = this.state
+    if (selectedOptions.length > 0) {
+      this.itemList.setHighlightedIndex(selectedOptions[0].index)
+    } else {
+      this.itemList.moveHighlightedIndex(1, { contain: true })
+    }
+  }
+
+  highlightLastSelectedOption = () => {
+    const { selectedOptions } = this.state
+    if (selectedOptions.length > 0) {
+      this.itemList.setHighlightedIndex(
+        selectedOptions[Math.max(0, selectedOptions.length - 1)].index
+      )
+    } else {
+      this.itemList.moveHighlightedIndex(-1, { contain: true })
+    }
+  }
+
+  focusInput = () => {
+    if (this.input) {
+      this.contextValue.canSelectOption.current = false
+      this.setState({ isPopoverVisible: false })
+      this.canCallFocus = false
+      this.input.focus()
+      this.canCallFocus = true
+    }
+  }
+
+  render() {
+    const {
+      children,
+      defaultValue,
+      disabled,
+      emptyValue,
+      innerRef,
+      defaultOpen,
+      keepInView,
+      lockScrollWhileOpen,
+      matchWidths,
+      multiple,
+      name,
+      onBlur,
+      onChange,
+      onClick,
+      onFocus,
+      onKeyDown,
+      onMouseDown,
+      onMouseUp,
+      options,
+      placement,
+      popoverProps,
+      renderTo,
+      renderValue,
+      tooltip,
+      value,
+      ...restProps
+    } = this.props
+    const { isPopoverOpen, isPopoverVisible } = this.state
+    return (
+      <SelectContext.Provider value={this.contextValue}>
+        <FocusGroup onBlur={this.closePopover}>
+          {({ requestBlur, setRef }) => (
+            <ItemList
+              ref={(c) => (this.itemList = c)}
+              selected={this.getSelected}
+              onSelect={this.handleSelect}
+            >
+              {({
+                getItemByText,
+                getHighlightedIndex,
+                moveHighlightedIndex,
+                selectHighlightedItem,
+                setHighlightedIndex,
+                selectItemByIndex,
+                stringSearch,
+              }) => {
+                const handleKeyboardControls = (event) => {
+                  switch (event.key) {
+                    case 'ArrowUp':
+                      event.preventDefault()
+                      if (isPopoverVisible) {
+                        moveHighlightedIndex(-1, { contain: true })
+                      } else {
+                        this.openPopover(true)
+                        setTimeout(() => {
+                          this.highlightLastSelectedOption()
+                        })
+                      }
+                      break
+                    case 'ArrowDown':
+                      event.preventDefault()
+                      if (isPopoverVisible) {
+                        moveHighlightedIndex(1, { contain: true })
+                      } else {
+                        this.openPopover(true)
+                        setTimeout(() => {
+                          this.highlightFirstSelectedOption()
+                        })
+                      }
+                      break
+                    case 'Enter':
+                      if (isPopoverVisible) {
+                        event.preventDefault()
+                        selectHighlightedItem()
+                      }
+                      break
+                    case 'Escape':
+                      if (isPopoverOpen && !isPopoverVisible) {
+                        event.preventDefault()
+                        this.closePopover()
+                      }
+                      break
+                    case ' ':
+                      event.preventDefault()
+                      if (getHighlightedIndex() === null) {
+                        this.togglePopover()
+                        setTimeout(() => {
+                          this.highlightFirstSelectedOption()
+                        })
+                      } else if (isPopoverVisible) {
+                        selectHighlightedItem()
+                      } else {
+                        this.openPopover(true)
+                      }
+                      break
+                    default:
+                      stringSearch(event).then((text) => {
+                        const item = getItemByText(text)
+                        if (item) {
+                          if (isPopoverVisible) {
+                            setHighlightedIndex(item.props.index)
+                          } else {
+                            selectItemByIndex(item.props.index)
+                          }
+                        }
+                      })
+                  }
+                }
+                return (
+                  <Popover
+                    {...popoverProps}
+                    ref={(component) => {
+                      this.popover = component
+                    }}
+                    innerRef={(node) => {
+                      setRef(`${this.id}-popover`)(node)
+                    }}
+                    as={MenuList}
+                    tabIndex={-1}
+                    aria-labelledby={this.id}
+                    aria-multiselectable={multiple}
+                    role="listbox"
+                    display={isPopoverVisible ? undefined : 'none'}
+                    minWidth={16}
+                    padding={0}
+                    elevation={2}
+                    matchWidths={matchWidths}
+                    lockScrollWhileOpen={
+                      isPopoverVisible ? lockScrollWhileOpen : false
+                    }
+                    keepInView={keepInView}
+                    placement={placement}
+                    renderTo={renderTo}
+                    open={isPopoverOpen}
+                    onRequestClose={() =>
+                      this.setState({ isPopoverVisible: false })
+                    }
+                    onBlur={requestBlur}
+                    onKeyDown={handleKeyboardControls}
+                    anchorElement={(anchorProps) => {
+                      if (!disabled) {
+                        restProps.onFocus = (event) => {
+                          if (this.canCallFocus) {
+                            this.openPopover(false)
+                          }
+                          if (onFocus) {
+                            onFocus(event)
+                          }
+                        }
+                        restProps.onBlur = (event) => {
+                          requestBlur(event)
+                          if (onBlur) {
+                            onBlur(event)
+                          }
+                        }
+                        restProps.onMouseDown = (event) => {
+                          if (event.button === 0) {
+                            this.addUserSelectStyle()
+                            this.canCallFocus = false
+                            this.togglePopover()
+                          }
+                          if (onMouseDown) {
+                            onMouseDown(event)
+                          }
+                        }
+                        restProps.onMouseUp = (event) => {
+                          this.canCallFocus = true
+                          if (onMouseUp) {
+                            onMouseUp(event)
+                          }
+                        }
+                        restProps.onKeyDown = (event) => {
+                          anchorProps.onKeyDown(event)
+                          if (onKeyDown) {
+                            onKeyDown(event)
+                          }
+                        }
+                      }
+                      return (
+                        <ItemListController>
+                          {({ getHighlightedItemId }) => (
+                            <Tooltip
+                              triggerOnHover={!isPopoverVisible}
+                              triggerOnFocus={!isPopoverVisible}
+                              {...tooltip}
+                            >
+                              <Input.InputBox
+                                innerRef={(node) => {
+                                  if (
+                                    typeof anchorProps.innerRef === 'function'
+                                  ) {
+                                    anchorProps.innerRef(node)
+                                  } else if (anchorProps.innerRef?.current) {
+                                    anchorProps.innerRef.current = node
+                                  }
+                                  this.input = node
+                                  setRef(`${this.id}-button`)(node)
+                                  if (innerRef) {
+                                    innerRef(node)
+                                  }
+                                }}
+                                id={this.id}
+                                tabIndex={0}
+                                role="button"
+                                disabled={disabled}
+                                aria-disabled={disabled}
+                                aria-haspopup={isPopoverVisible}
+                                aria-expanded={isPopoverVisible}
+                                aria-activedescendant={getHighlightedItemId()}
+                                cursor="pointer"
+                                userSelect="none"
+                                touchAction="manipulation"
+                                focusChildrenOnFocus={false}
+                                renderRight={
+                                  <Icon
+                                    name={
+                                      isPopoverVisible
+                                        ? 'general.upCaret'
+                                        : 'general.downCaret'
+                                    }
+                                  />
+                                }
+                                {...restProps}
+                              >
+                                {this.getValue()}
+                                {this.getHiddenInputValues()}
+                              </Input.InputBox>
+                            </Tooltip>
+                          )}
+                        </ItemListController>
+                      )
+                    }}
+                  >
+                    {renderOptions(
+                      options ? optionsToElements(options) : children
+                    )}
+                  </Popover>
+                )
+              }}
+            </ItemList>
+          )}
+        </FocusGroup>
+      </SelectContext.Provider>
+    )
+  }
+}
+
+export default Select

package/src/Select/Select.mdx

@@ -0,0 +1,81 @@
+---
+title: Select
+category: Forms
+summary: Provide a list of options that can be selected. Replaces native select menus by using aria roles to enhance accessibility while allowing full customization of the options and what is used in the select popover. Composes [InputBox](/input.inputbox) and [Popover](/popover).
+propsSummary: Accepts [InputBox](/input.inputbox) props.
+isParent: true
+---
+
+```jsx live
+render(
+  <Select
+    emptyValue="Select a fruit"
+    tooltip={{ title: 'Select a fruit' }}
+    onChange={(e) => console.log(e)}
+  >
+    <Select.Option value="apple">Apple</Select.Option>
+    <Select.Option value="orange">Orange</Select.Option>
+    <Select.Option value="banana">Banana</Select.Option>
+    <Select.Option value="mango">Mango</Select.Option>
+    <Select.Option value="kiwi" disabled>
+      Kiwi (Out of stock)
+    </Select.Option>
+    <Select.Option value="strawberry">Strawberry</Select.Option>
+    <Divider margin={0.5} />
+    <Menu.Item distribution="fill" spacing={1}>
+      <Button title="Action 1" size="sm" />
+      <Button title="Action 2" size="sm" />
+    </Menu.Item>
+  </Select>
+)
+```
+
+```jsx live
+const options = [
+  {
+    label: 'Dogs',
+    optgroup: [
+      { value: 'frenchy', label: 'French Bulldog' },
+      { value: 'pit-bull', label: 'Pit Bull' },
+    ],
+  },
+  {
+    label: 'Cats',
+    optgroup: [
+      { value: 'munchkin', label: 'Munchkin' },
+      { value: 'persian', label: 'Persian' },
+    ],
+  },
+]
+render(() => {
+  const ref = React.useRef(null)
+  const [selectedValues, setSelectedValues] = React.useState([])
+  return (
+    <StackView
+      innerRef={ref}
+      as="form"
+      id="container"
+      position="relative"
+      alignment="center"
+      spacing={1}
+    >
+      <Select
+        name="pets"
+        multiple
+        options={options}
+        value={selectedValues}
+        matchWidths={false}
+        emptyValue="Choose your favorite pets"
+        renderTo="#container"
+        onChange={(event) => setSelectedValues(event.value)}
+      />
+      <Button
+        title="Submit"
+        size="xs"
+        theme="primary"
+        onClick={() => ref.current.submit()}
+      />
+    </StackView>
+  )
+})
+```