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

package/src/Dropdown/Dropdown.js

@@ -0,0 +1,322 @@
+// @flow
+import React, { Component, cloneElement, createElement } from 'react'
+
+import Button from '../Button'
+import FocusGroup from '../FocusGroup'
+import { ItemList, ItemListController } from '../ItemList'
+import Menu from '../Menu'
+import Popover from '../Popover'
+import { cloneChildren, generateId } from '../utils'
+
+import Item, { ITEM_DISPLAY_NAME } from './Item'
+import Link, { LINK_DISPLAY_NAME } from './Link'
+
+type Props = {
+  children?: React.ReactNode,
+
+  /** Allows specifying a type or custom element that will be cloned and provided `Dropdown` trigger props. (Defaults to a [Button](/button).) */
+  triggerElement?: React.ElementType | React.ReactNode,
+
+  /** Gain access to the internal ref. */
+  innerRef?: any,
+
+  /** Closes Popover upon selecting a `Dropdown.Item`. */
+  closeOnSelect?: boolean,
+
+  /** Forces Popover open for testing purposes. */
+  forceOpen?: boolean,
+
+  /** Externally control Popover open state on initial render. */
+  defaultOpen?: boolean,
+
+  /** Callback when Popover is opened. */
+  onOpen?: boolean,
+
+  /** Callback when Popover is closed. */
+  onClose?: boolean,
+
+  /** Overrides the default search function for selecting a dropdown item via keyboard. */
+  onSearch?: func,
+
+  /** Attempts to keep popover in view clipping edges if too large. */
+  keepInView?: boolean,
+
+  /** Locks external scrollbars when open. */
+  lockScrollWhileOpen?: boolean,
+
+  /** Matches anchor and popover widths. */
+  matchWidths?: boolean | 'minimum',
+
+  /** 
+   * `'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,
+}
+
+class Dropdown extends Component<Props> {
+  static Item = Item
+
+  static Link = Link
+
+  static defaultProps = {
+    triggerElement: Button,
+    closeOnSelect: true,
+    defaultOpen: false,
+  }
+
+  constructor(props: Props) {
+    super(props)
+    this.state = {
+      isPopoverOpen: props.defaultOpen || props.forceOpen,
+      preventBlur: false,
+    }
+    this.id = generateId('dropdown')
+  }
+
+  openPopover = (event) => {
+    if (this.props.onOpen) {
+      this.props.onOpen()
+    }
+    this.setState({ isPopoverOpen: true })
+  }
+
+  closePopover = (event) => {
+    if (this.props.onClose) {
+      this.props.onClose()
+    }
+    if (!this.props.forceOpen) {
+      this.setState({ isPopoverOpen: false })
+    }
+  }
+
+  togglePopover = (event) => {
+    this.setState({ preventBlur: false })
+    if (this.state.isPopoverOpen) {
+      this.closePopover(event)
+    } else {
+      this.openPopover(event)
+    }
+  }
+
+  handleSelect = (data, { node }) => {
+    if (this.props.closeOnSelect) {
+      this.itemList.clearHighlightedIndex()
+      this.closePopover()
+      this.popover.focusAnchor()
+    }
+    if (node.tagName === 'A' && event.type !== 'click') {
+      node.click()
+    } else if (this.props.onSelect) {
+      this.props.onSelect(data)
+    }
+  }
+
+  render() {
+    const {
+      forceOpen,
+      closeOnSelect,
+      children,
+      as,
+      defaultOpen,
+      innerRef,
+      keepInView,
+      lockScrollWhileOpen,
+      matchWidths,
+      onClick,
+      onClose,
+      onKeyDown,
+      onOpen,
+      onSearch,
+      placement,
+      popoverProps,
+      renderTo,
+      triggerElement,
+      ...restProps
+    } = this.props
+    const { isPopoverOpen } = this.state
+    const arrowIconOnly = !restProps.icon && !restProps.title
+    let index = -1
+    return (
+      <FocusGroup onBlur={this.closePopover}>
+        {({ requestBlur, setRef }) => (
+          <ItemList
+            ref={(c) => (this.itemList = c)}
+            onSelect={this.handleSelect}
+          >
+            {({
+              getItemByText,
+              moveHighlightedIndex,
+              selectHighlightedItem,
+              setHighlightedIndex,
+              stringSearch,
+            }) => (
+              <Popover
+                {...popoverProps}
+                as={Menu}
+                ref={(component) => {
+                  this.popover = component
+                }}
+                innerRef={(node) => {
+                  setRef(`${this.id}-popover`)(node)
+                }}
+                role="menu"
+                tabIndex={-1}
+                elevation={2}
+                display={Boolean(restProps.spinner) ? 'none' : undefined}
+                onBlur={requestBlur}
+                matchWidths={matchWidths}
+                keepInView={keepInView}
+                lockScrollWhileOpen={lockScrollWhileOpen}
+                placement={placement}
+                renderTo={renderTo}
+                open={isPopoverOpen}
+                onRequestClose={() => {
+                  this.closePopover()
+                  this.popover.focusAnchor()
+                }}
+                anchorElement={(anchorProps) => (
+                  <ItemListController>
+                    {({ getHighlightedItemId }) => {
+                      const triggerProps = {
+                        innerRef: (node) => {
+                          if (typeof anchorProps.innerRef === 'function') {
+                            anchorProps.innerRef(node)
+                          } else if (anchorProps.innerRef?.current) {
+                            anchorProps.innerRef.current = node
+                          }
+                          setRef(`${this.id}-button`)(node)
+                          if (innerRef) {
+                            innerRef(node)
+                          }
+                        },
+                        'aria-activedescendant': getHighlightedItemId(),
+                        'aria-owns': getHighlightedItemId(),
+                        'aria-haspopup': true,
+                        'aria-expanded': isPopoverOpen,
+                        [arrowIconOnly ? 'icon' : 'iconRight']: {
+                          name: isPopoverOpen
+                            ? 'general.upCaret'
+                            : 'general.downCaret',
+                          size: 'sm',
+                        },
+                        title: arrowIconOnly ? 'arrow down' : restProps.title,
+                        tabIndex: 0,
+                        cursor: 'pointer',
+                        onBlur: (event) => {
+                          if (this.state.preventBlur) {
+                            this.setState({ preventBlur: false })
+                          } else {
+                            requestBlur(event)
+                          }
+                        },
+                        onClick: (event) => {
+                          this.togglePopover()
+                          if (!isPopoverOpen) {
+                            this.popover.focusAnchor()
+                          }
+                          onClick && onClick(event)
+                        },
+                        onKeyDown: (event) => {
+                          anchorProps.onKeyDown(event)
+                          switch (event.key) {
+                            case 'ArrowUp':
+                              event.preventDefault()
+                              if (isPopoverOpen) {
+                                moveHighlightedIndex(-1)
+                              } else {
+                                this.openPopover()
+                                setTimeout(() => {
+                                  moveHighlightedIndex(-1)
+                                })
+                              }
+                              break
+                            case 'ArrowDown':
+                              event.preventDefault()
+                              if (isPopoverOpen) {
+                                moveHighlightedIndex(1)
+                              } else {
+                                this.openPopover()
+                                setTimeout(() => {
+                                  moveHighlightedIndex(1)
+                                })
+                              }
+                              break
+                            case 'Enter':
+                              if (isPopoverOpen) {
+                                event.preventDefault()
+                                selectHighlightedItem()
+                              }
+                              break
+                            case ' ':
+                              event.preventDefault()
+                              this.togglePopover()
+                              break
+                            default:
+                              onSearch
+                                ? onSearch(event)
+                                : stringSearch(event).then((text) => {
+                                    const item = getItemByText(text)
+                                    if (item) {
+                                      setHighlightedIndex(item.props.index)
+                                    }
+                                  })
+                          }
+                        },
+                        onMouseDown: () => {
+                          this.setState({ preventBlur: true })
+                        },
+                        ...restProps,
+                      }
+                      if (React.isValidElement(triggerElement)) {
+                        return cloneElement(triggerElement, triggerProps)
+                      } else {
+                        return createElement(triggerElement, triggerProps)
+                      }
+                    }}
+                  </ItemListController>
+                )}
+              >
+                {cloneChildren(children, (child) => {
+                  if (
+                    child.type.displayName === ITEM_DISPLAY_NAME ||
+                    child.type.displayName === LINK_DISPLAY_NAME
+                  ) {
+                    index++
+                    return { index }
+                  } else {
+                    return {}
+                  }
+                })}
+              </Popover>
+            )}
+          </ItemList>
+        )}
+      </FocusGroup>
+    )
+  }
+}
+
+export default Dropdown

package/src/Dropdown/Dropdown.mdx

@@ -0,0 +1,202 @@
+---
+title: Dropdown
+category: General
+summary: A compact way of displaying content or actionable items in a popover. Use [Select](/select) for selectable options if needed.
+propsSummary: Accepts [Button](/button) and [Popover](/popover) props.
+---
+
+### Items
+
+```jsx live
+render(
+  <Dropdown icon={{ name: 'general.cog' }} title="Folder settings" variant="outline">
+    <Dropdown.Item onSelect={() => console.log('edit folder')}>
+      Edit Folder
+    </Dropdown.Item>
+    <Dropdown.Item onSelect={() => console.log('add folder')}>
+      Add Folder
+    </Dropdown.Item>
+  </Dropdown>
+)
+```
+
+### Links
+
+```jsx live
+render(
+  <Dropdown title="Links" size="sm" variant="outline">
+    <Dropdown.Link to="http://planning.center" external>
+      Planning Center (external)
+    </Dropdown.Link>
+    <Dropdown.Link to="/button">
+      Tapestry React Button
+    </Dropdown.Link>
+  </Dropdown>
+)
+```
+
+### Custom children
+
+```jsx live
+render(() => {
+  const [previous, setPrevious] = React.useState(0)
+  const [future, setFuture] = React.useState(4)
+  return (
+    <Group>
+      <Button title="Matrix" size="xs" />
+      <Dropdown aria-label="Matrix options" size="xs">
+        <StackView width={28} padding={1} spacing={1}>
+          <StackView
+            as="label"
+            axis="horizontal"
+            alignment="center"
+            distribution="space-between"
+            spacing={1}
+          >
+            <Text>Past plans to load</Text>
+            <NumberField
+              size="xs"
+              minWidth="49px"
+              value={previous}
+              min={0}
+              onChange={(value) => setPrevious(value)}
+            />
+          </StackView>
+          <StackView
+            as="label"
+            axis="horizontal"
+            alignment="center"
+            distribution="space-between"
+            spacing={1}
+          >
+            <Text>Future plans to load</Text>
+            <NumberField
+              size="xs"
+              minWidth="49px"
+              value={future}
+              min={0}
+              onChange={(value) => setFuture(value)}
+            />
+          </StackView>
+        </StackView>
+      </Dropdown>
+    </Group>
+  )
+})
+```
+
+### Fetch data on open
+
+```jsx live
+render(() => {
+  const [loading, setLoading] = React.useState(false)
+  return (
+    <Dropdown
+      title="Lazy Items"
+      spinner={loading}
+      onOpen={() => {
+        setLoading(true)
+        setTimeout(() => {
+          setLoading(false)
+        }, 2000)
+      }}
+      onSelect={(value) => console.log(`Item "${value}" selected`)}
+    >
+      {loading
+        ? null
+        : [1, 2, 3].map((value) => (
+            <Dropdown.Item key={value} value={value}>
+              Item {value}
+            </Dropdown.Item>
+          ))}
+    </Dropdown>
+  )
+})
+```
+
+### No arrow and text truncation
+
+```jsx live
+render(
+  <StackView width={16}>
+    <Dropdown
+      iconRight={undefined}
+      title={<Text truncate>Supercalifragilisticexpialidocious</Text>}
+      variant="outline"
+    >
+      <Dropdown.Item value="item-1">Item 1</Dropdown.Item>
+      <Dropdown.Item value="item-2">Item 2</Dropdown.Item>
+      <Dropdown.Item value="item-3">Item 3</Dropdown.Item>
+    </Dropdown>
+  </StackView>
+)
+```
+
+### Custom Trigger
+
+```jsx live
+function GuitarIcon({ fill }) {
+  return (
+    <svg width="28" height="28" fill="none" viewBox="0 0 28 28">
+      <path
+        fill={fill}
+        fillRule="evenodd"
+        d="M27.349 2.657L24.887.237c-.32-.32-.88-.319-1.183.023l-3.38 3.46a1.607 1.607 0 00-.423.863l-.123.722c-.041.321-.182.622-.424.863l-5.072 5.37-.04.046c-2.081-1.322-4.576-1.324-6.055.155l-.127.127c-1.356 1.358-3.226 3.23-4.953 3.951-.68.285-1.312.7-1.858 1.246-2.443 2.443-.991 5.328 1.684 8.004 2.675 2.675 5.56 4.127 8.004 1.684a5.764 5.764 0 001.246-1.859c.721-1.726 2.592-3.596 3.95-4.952l.127-.127c1.479-1.479 1.478-3.972.157-6.052.037-.033.073-.067.108-.104l5.051-5.347c.241-.242.523-.403.844-.444l.722-.123c.32-.041.622-.222.843-.444l3.38-3.46a.83.83 0 00-.016-1.182zM8.584 19.415a2.284 2.284 0 103.23-3.23 2.284 2.284 0 00-3.23 3.23z"
+      />
+    </svg>
+  )
+}
+const colors = [
+  '#714dd8',
+  '#3c8bf7',
+  '#72bb52',
+  '#ff6767',
+  '#ffa833',
+  '#000000',
+]
+render(() => {
+  const [activeColor, setActiveColor] = React.useState('#000000')
+  return (
+    <Dropdown
+      triggerElement={
+        <StackView
+          width={10}
+          height={10}
+          alignment="center"
+          distribution="center"
+          stroke={activeColor === '#000000' ? 'separator' : activeColor}
+          strokeWeight={2}
+          spacing={1}
+          radius={5}
+        >
+          <GuitarIcon fill={activeColor} />
+          <Text size={4} weight={600} letterSpacing="0.05em">
+            Guitar
+          </Text>
+        </StackView>
+      }
+      title="Drums"
+      popoverProps={{
+        paddingHorizontal: 1,
+        paddingVertical: 1,
+      }}
+    >
+      <GridView columns="1fr 1fr 1fr" spacing={1}>
+        {colors.map((color, index) => (
+          <Dropdown.Item
+            key={color}
+            index={index}
+            width={4}
+            height={4}
+            backgroundColor={color}
+            highlightedColor={color + 'd1'}
+            stroke={color === activeColor ? color + '75' : undefined}
+            strokeWeight={2}
+            onSelect={() => setActiveColor(color)}
+          />
+        ))}
+      </GridView>
+    </Dropdown>
+  )
+})
+```

package/src/Dropdown/Dropdown.test.tsx

@@ -0,0 +1,133 @@
+import React, { useState } from 'react'
+import { fireEvent, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import '@testing-library/jest-dom/extend-expect'
+import noop from 'lodash/noop'
+import { Box, Button, Text, ThemeProvider } from '..'
+import Dropdown from './Dropdown'
+
+describe('Dropdown', () => {
+  describe('Text search', () => {
+    it(`should render title`, () => {
+      render(<Dropdown title="A menu"></Dropdown>)
+      screen.getByText('A menu')
+    })
+
+    it(`calls passed onSearch function when receiving keyboard input`, () => {
+      const customTextSearch = jest.fn()
+      render(
+        <ThemeProvider>
+          <Dropdown title="A menu" onSearch={customTextSearch}></Dropdown>
+        </ThemeProvider>
+      )
+      const dropdown = screen.getByText('A menu')
+
+      fireEvent.keyDown(dropdown, { key: 'A', code: 'KeyA' })
+      expect(customTextSearch).toHaveBeenCalled()
+    })
+  })
+
+  describe('Keyboard navigation', () => {
+    const StatefulDropdown = () => {
+      const [count, setCount] = useState(0)
+      return (
+        <ThemeProvider>
+          <Box>
+            <Dropdown>
+              <Dropdown.Item>
+                <Button title="One" onClick={() => noop()} />
+              </Dropdown.Item>
+              <Dropdown.Item>
+                <Button title="Two" onClick={() => setCount((c) => c + 1)} />
+                <Text data-testid="count-text">{count}</Text>
+              </Dropdown.Item>
+              <Dropdown.Item>
+                <Button title="Three" onClick={() => noop()} />
+              </Dropdown.Item>
+            </Dropdown>
+          </Box>
+        </ThemeProvider>
+      )
+    }
+
+    it('should trap focus, tab forward through all elements', () => {
+      render(<StatefulDropdown />)
+      userEvent.tab()
+      userEvent.keyboard('{enter}')
+      const [
+        openPopover,
+        buttonOne,
+        buttonTwo,
+        buttonThree,
+      ] = screen.getAllByRole('button')
+
+      expect(openPopover).toHaveFocus()
+      userEvent.tab()
+      expect(buttonOne).toHaveFocus()
+      userEvent.tab()
+      expect(buttonTwo).toHaveFocus()
+      userEvent.tab()
+      expect(buttonThree).toHaveFocus()
+      userEvent.tab()
+      expect(buttonOne).toHaveFocus()
+    })
+
+    it('should trap focus, tab backwards from first element to last', () => {
+      render(<StatefulDropdown />)
+      userEvent.tab()
+      userEvent.keyboard('{enter}')
+      const [
+        openPopover,
+        buttonOne,
+        _buttonTwo,
+        buttonThree,
+      ] = screen.getAllByRole('button')
+
+      expect(openPopover).toHaveFocus()
+      userEvent.tab()
+      expect(buttonOne).toHaveFocus()
+      userEvent.tab({ shift: true })
+      expect(buttonThree).toHaveFocus()
+    })
+
+    it('should retain tab order after rerender', () => {
+      render(<StatefulDropdown />)
+      userEvent.tab()
+      userEvent.keyboard('{enter}')
+      const [, buttonOne, buttonTwo, buttonThree] = screen.getAllByRole(
+        'button'
+      )
+
+      userEvent.tab()
+      userEvent.tab()
+      expect(screen.getByTestId('count-text')).toHaveTextContent('0')
+      userEvent.keyboard('{enter}')
+      expect(screen.getByTestId('count-text')).toHaveTextContent('1')
+      expect(buttonTwo).toHaveFocus()
+      userEvent.tab()
+      expect(buttonThree).toHaveFocus()
+      userEvent.tab({ shift: true })
+      userEvent.tab({ shift: true })
+      expect(buttonOne).toHaveFocus()
+      userEvent.tab()
+      userEvent.tab()
+      userEvent.tab()
+      expect(buttonOne).toHaveFocus()
+      userEvent.tab({ shift: true })
+      userEvent.tab({ shift: true })
+      userEvent.tab({ shift: true })
+      expect(buttonOne).toHaveFocus()
+    })
+
+    it('should focus dropdown toggle when a user presses escape key', () => {
+      render(<StatefulDropdown />)
+      userEvent.tab()
+      userEvent.keyboard('{enter}')
+      const [openPopover, buttonOne] = screen.getAllByRole('button')
+      userEvent.tab()
+      expect(buttonOne).toHaveFocus()
+      userEvent.keyboard(`{esc}`)
+      expect(openPopover).toHaveFocus()
+    })
+  })
+})

package/src/Dropdown/Item.js

@@ -0,0 +1,39 @@
+import React, { Component } from 'react'
+
+import { ItemListItem } from '../ItemList'
+import Menu from '../Menu'
+
+export const ITEM_DISPLAY_NAME = 'Dropdown.Item'
+
+class Item extends Component {
+  static displayName = ITEM_DISPLAY_NAME
+
+  render() {
+    const { disabled, index, onSelect, text, value, ...restProps } = this.props
+    return (
+      <ItemListItem
+        data={value}
+        text={text}
+        disabled={disabled}
+        index={index}
+        onSelect={onSelect}
+      >
+        {({ id, highlight, highlighted, clearHighlight, select }) => (
+          <Menu.Item
+            id={id}
+            role="menuitem"
+            aria-disabled={disabled}
+            disabled={disabled}
+            isHighlighted={highlighted}
+            onMouseOver={highlight}
+            onMouseOut={clearHighlight}
+            onClick={select}
+            {...restProps}
+          />
+        )}
+      </ItemListItem>
+    )
+  }
+}
+
+export default Item