@planningcenter/tapestry-react 2.10.0-rc.8 → 2.10.0

package/src/Button/Button.tsx

@@ -0,0 +1,430 @@
+import * as React from 'react'
+
+import { useBoxSize, useThemeValue } from '../system'
+import Icon from '../Icon'
+import { BoxSizes, MediaQueries } from '../index'
+import Link from '../Link'
+import Spinner from '../Spinner'
+import { StackView, StackViewProps } from '../StackView'
+import Tooltip from '../Tooltip'
+import { mergeProps } from '../utils'
+import { useAccessibilityViolation } from '../hooks/use-accessibility-violation'
+import { designTokens } from '../designTokens'
+
+import Input from './Input'
+
+export type ButtonProps = {
+  children?: any
+
+  /**
+   * "Soft disables" button by adding an `aria-disabled` attribute and preventing `onClick` and `keyDown` events for "space" / "enter". This approach allows composing components (such as `Tooltip`) to still bubble up their events, while ensuring that clicking the button or submitting a form is prevented.
+   */
+  disabled?: boolean
+
+  /**
+   * Opens the linked destination in a new window or tab.
+   */
+  external?: boolean
+
+  /**
+   * Pass styles for when the button is active.
+   */
+  active?: object
+
+  /**
+   * Pass styles for when the button is focused.
+   */
+  focus?: object
+
+  /**
+   * Pass styles for when the button is keyboard-focused.
+   */
+  focusVisible?: object
+
+  /**
+   * Pass styles for when the button is hovered.
+   */
+  hover?: object
+
+  /**
+   * Renders an [Icon](/icon) in the center of the button. Pass a string or any valid `Icon` props.
+   * Must pass a [`title`](/button#title) or [`tooltip.title`](/tooltip#title) when using icon-only buttons.
+   */
+  icon?: string | Object
+
+  /**
+   * Same as above, but renders an icon in the left portion of the button.
+   */
+  iconLeft?: string | Object
+
+  /**
+   * Same as above, but renders an icon in the right portion of the button.
+   */
+  iconRight?: string | Object
+
+  /**
+   * Sizes the button using values defined in [boxSizes](/theming)
+   */
+  size?: keyof BoxSizes
+
+  /**
+   * Renders a [`<Spinner />`](/spinner) in the center of the button. Accepts any valid Spinner props.
+   */
+  spinner?: any
+
+  /**
+   * Uses a 1:1 ratio for sizing the button.
+   */
+  square?: boolean
+
+  /**
+   * Uses theme defined in [`buttons.theme`](/theming). Pass `false` to not use theme at all.
+   */
+  theme?: string | boolean
+
+  /**
+   * Renders a text string in the center of the button.
+   */
+  title?: string | number
+
+  /**
+   * Where the browser should navigate to when pressed. If you need any element here other than `<a>`, remember to use the `as` prop.
+   */
+  to?: string
+
+  /**
+   * Where the browser should navigate to when pressed. If you need any element here other than `<a>`, remember to use the `as` prop.
+   */
+  href?: string
+
+  /**
+   * Wraps button in a [`<Tooltip />`](./tooltip). Accepts any valid Tooltip props.
+   */
+  tooltip?: string | Object
+
+  /**
+   * Sets the button type to `button`, `submit`, or `reset`. Default is `button`. Type is only valid for `<button>`s.
+   */
+  type?: 'button' | 'submit' | 'reset'
+
+  /**
+   * Determines the modified style of the button.
+   */
+  variant?: 'fill' | 'outline' | 'naked'
+
+  onClick?: Function
+
+  onKeyDown?: Function
+
+  /** Describes props at different breakpoints. [Read about mediaQueries](/responsive). */
+  mediaQueries?: object
+} & StackViewProps
+
+type Props = React.RefAttributes<any> &
+  React.HTMLAttributes<any> &
+  ButtonProps &
+  MediaQueries<ButtonProps>
+
+export function Button({
+  children,
+  disabled,
+  external,
+  icon,
+  iconLeft,
+  iconRight,
+  onClick,
+  onKeyDown,
+  size,
+  spinner,
+  square,
+  theme = 'default',
+  title,
+  to,
+  tooltip,
+  type = 'button',
+  variant,
+  ...restProps
+}: Props) {
+  const buttonThemes = useThemeValue('button.themes')
+  let {
+    boxSize,
+    fontSize,
+    lineHeight,
+    paddingHorizontal,
+    paddingHorizontalDense,
+    paddingVertical,
+  } = useBoxSize(size)
+
+  let buttonProps: any = {
+    alignment: 'center',
+    as: (restProps as any).href || to ? 'a' : 'button',
+    axis: 'horizontal',
+    distribution: 'center',
+    fontSize,
+    fontWeight: 700,
+    inline: true,
+    lineHeight,
+    position: 'relative',
+    radius: designTokens.button.borderRadius,
+    strokeAlign: 'inside',
+    strokeWeight: 1,
+    userSelect: 'none',
+    zIndex: 1,
+    type,
+  }
+
+  let spinnerColor
+
+  if (theme) {
+    const buttonTheme = buttonThemes[theme]
+    if (buttonTheme) {
+      const buttonThemeVariant = buttonTheme[variant || 'fill']
+      if (buttonThemeVariant) {
+        buttonProps = {
+          ...buttonProps,
+          ...buttonThemeVariant,
+        }
+      } else {
+        console.warn(
+          `Could not find "${variant}" in "${theme}" theme. Check your ThemeProvider and make sure "${variant}" variant exists in "${theme}".`
+        )
+      }
+    } else if (theme === 'false') {
+      console.warn(
+        `The string "false" is not a valid theme. Please pass a boolean %cfalse%c instead.`,
+        'color:red',
+        'color:inherit'
+      )
+    } else {
+      console.warn(
+        `Could not find "${theme}" in button.themes. Check your ThemeProvider and make sure "${theme}" exists.`
+      )
+    }
+  }
+
+  // normalize strings that should end up as objects
+  if (typeof icon === 'string') {
+    icon = { name: icon }
+  }
+  if (typeof iconLeft === 'string') {
+    iconLeft = { name: iconLeft }
+  }
+  if (typeof iconRight === 'string') {
+    iconRight = { name: iconRight }
+  }
+  if (typeof tooltip === 'string') {
+    tooltip = { title: tooltip }
+  }
+
+  // if using an icon only button, apply dense padding and possibly an aria label
+  if (icon) {
+    paddingHorizontal = paddingHorizontalDense
+    buttonProps['aria-label'] = tooltip ? tooltip['title'] : title
+  }
+
+  // square width and height if applicable props present
+  if (square) {
+    buttonProps.width = boxSize
+    buttonProps.height = boxSize
+  } else if (icon) {
+    buttonProps.minWidth = boxSize
+    buttonProps.minHeight = boxSize
+  }
+
+  // handle padding based on the incoming radius or whether icons are present or not
+  if (restProps['radius'] === 'pill') {
+    buttonProps.paddingHorizontal = paddingHorizontal * 1.25
+  } else if (restProps['radius'] === 'pill-left') {
+    buttonProps.paddingLeft = paddingHorizontal * 1.25
+    buttonProps.paddingRight = paddingHorizontal
+  } else if (restProps['radius'] === 'pill-right') {
+    buttonProps.paddingLeft = paddingHorizontal
+    buttonProps.paddingRight = paddingHorizontal * 1.25
+  } else if (!(icon && !iconLeft && !iconRight)) {
+    buttonProps.paddingHorizontal = paddingHorizontal
+    buttonProps.paddingVertical = paddingVertical
+  }
+
+  // clear text and/or icons when spinner is present
+  if (spinner) {
+    spinnerColor = buttonProps.color
+    buttonProps.color = 'transparent'
+    if (icon) {
+      icon['color'] = 'transparent'
+    }
+    if (iconLeft) {
+      iconLeft['color'] = 'transparent'
+    }
+    if (iconRight) {
+      iconRight['color'] = 'transparent'
+    }
+  }
+
+  if (disabled) {
+    const themeData = buttonThemes[theme]
+    if (themeData) {
+      const variantData = themeData[variant]
+      if (variantData && variantData.disabled) {
+        buttonProps = { ...buttonProps, ...variantData.disabled }
+      } else {
+        buttonProps.opacity = 0.65
+      }
+    }
+
+    buttonProps['aria-disabled'] = true
+    buttonProps.cursor = 'not-allowed'
+    buttonProps.onClick = (event) => event.preventDefault()
+    buttonProps.onKeyDown = (event) => {
+      if (event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault()
+      }
+    }
+  }
+
+  // don't apply hover/active styles or events when disabled or spinner is present
+  if (disabled || spinner) {
+    buttonProps.hover = undefined
+    buttonProps.active = undefined
+  } else {
+    buttonProps.focus = { zIndex: 5, ...buttonProps.focus }
+    buttonProps.cursor = 'pointer'
+    buttonProps.touchAction = 'manipulation'
+    buttonProps.onClick = onClick
+    buttonProps.onKeyDown = (event) => {
+      if (onClick && (event.key === 'Enter' || event.key === ' ')) {
+        event.preventDefault()
+        onClick(event)
+      }
+      if (onKeyDown) {
+        onKeyDown(event)
+      }
+    }
+  }
+
+  // apply rel and target for external links
+  if (external) {
+    buttonProps.rel = 'noopener noreferrer'
+    buttonProps.target = '_blank'
+  }
+
+  // apply href value when specified
+  if (to) {
+    restProps['href'] = to
+  }
+
+  // remove `type` if either `to` or `href` is specified
+  if (to || (restProps as any).href) {
+    buttonProps = {
+      ...buttonProps,
+      type: null,
+    }
+  }
+
+  // apply stroke defaults and higher z-index when hovering to show outline in group properly
+  if (variant === 'outline') {
+    buttonProps = {
+      ...buttonProps,
+      hover: {
+        strokeAlign: 'inside',
+        strokeWeight: 1,
+        zIndex: 2,
+        ...buttonProps.hover,
+      },
+    }
+  }
+
+  // pass to if as is defined
+  if ((restProps as any).as) {
+    buttonProps.to = to
+
+    // remove type if it is not a button
+    if ((restProps as any).as !== 'button') {
+      buttonProps = {
+        ...buttonProps,
+        type: null,
+      }
+    }
+  }
+
+  if (process.env.NODE_ENV !== 'production') {
+    if (icon && !(title || (tooltip && (tooltip as any).title))) {
+      const { tooltipProps, wrapperProps } = useAccessibilityViolation(
+        <>
+          Icon only buttons must define either a{' '}
+          <Link
+            external
+            to="https://planningcenter.github.io/tapestry-react/button#tooltip"
+            weight={700}
+          >
+            tooltip
+          </Link>{' '}
+          or{' '}
+          <Link
+            external
+            to="https://planningcenter.github.io/tapestry-react/button#title"
+            weight={700}
+          >
+            title
+          </Link>{' '}
+          prop.
+        </>,
+        `Tapestry-React: <Button/> icon only buttons must define either a "tooltip" or "title" prop for proper accessibility.`
+      )
+      tooltip = tooltipProps
+      restProps = mergeProps(restProps, wrapperProps)
+    }
+
+    if (
+      buttonProps.type &&
+      (restProps as any).as &&
+      (restProps as any).as !== 'button'
+    ) {
+      console.log(
+        `Tapestry-React: <Button/> type prop is only supported by <button> and not <${
+          (restProps as any).as
+        }>.`
+      )
+    }
+  }
+
+  return (
+    <Tooltip {...tooltip}>
+      <StackView
+        {...buttonProps}
+        {...restProps}
+        css={{
+          '&:focus-visible': {
+            ...buttonProps.focusVisible,
+          },
+        }}
+      >
+        {iconLeft && (
+          <Icon
+            size={size}
+            color={buttonProps.color}
+            marginRight={paddingHorizontalDense}
+            {...iconLeft}
+          />
+        )}
+        {icon ? (
+          <Icon size={size} color={buttonProps.color} {...icon} />
+        ) : (
+          title || children
+        )}
+        {iconRight && (
+          <Icon
+            size={size}
+            color={buttonProps.color}
+            marginLeft={paddingHorizontalDense}
+            {...iconRight}
+          />
+        )}
+        {spinner && (
+          <Spinner size={size} color={spinnerColor} {...spinner} center />
+        )}
+      </StackView>
+    </Tooltip>
+  )
+}
+
+Button.Input = Input

package/src/Button/Input.mdx

@@ -0,0 +1,170 @@
+---
+title: Button.Input
+category: General
+summary: Transforms a button into an input. Composes and forwards props to [Button](/button).
+parent: Button
+---
+
+```jsx live
+render(
+  <Box padding={2} backgroundColor="primary">
+    <Button.Input
+      title="Add Person"
+      theme="light"
+      iconLeft={{
+        name: 'general.person',
+        color: 'light-6',
+      }}
+    >
+      <Input width={24} />
+    </Button.Input>
+  </Box>
+)
+```
+
+```jsx live
+const people = [
+  {
+    first: 'Charlie',
+    last: 'Brown',
+    twitter: 'dancounsell',
+  },
+  {
+    first: 'Charlotte',
+    last: 'White',
+    twitter: 'mtnmissy',
+  },
+  {
+    first: 'Chloe',
+    last: 'Jones',
+    twitter: 'ladylexy',
+  },
+  {
+    first: 'Cooper',
+    last: 'King',
+    twitter: 'steveodom',
+  },
+  {
+    first: 'James',
+    last: 'Miller',
+    twitter: 'bensie',
+  },
+  {
+    first: 'John',
+    last: 'James',
+    twitter: 'miller',
+  },
+  {
+    first: 'Travis',
+    last: 'Arnold',
+    twitter: 'souporserious',
+  },
+]
+function ButtonCombobox({ buttonProps, comboboxProps, children }) {
+  const comboboxRef = React.useRef(null)
+  return (
+    <Button.Input {...buttonProps}>
+      {({ inputProps, close }) => (
+        <Combobox.Popover
+          ref={comboboxRef}
+          openOnFocus
+          closeButton={{
+            onClick: () => {
+              close()
+              comboboxRef.current.closePopover()
+            },
+          }}
+          onClear={() => {
+            close()
+            comboboxRef.current.closePopover()
+          }}
+          {...inputProps}
+          {...comboboxProps}
+        >
+          {children}
+        </Combobox.Popover>
+      )}
+    </Button.Input>
+  )
+}
+render(() => {
+  const [value, setValue] = React.useState('')
+  const [open, setOpen] = React.useState(false)
+  const containerRef = React.useRef(null)
+  return (
+    <StackView
+      axis="horizontal"
+      alignment="center"
+      distribution="space-between"
+      minWidth="80%"
+      padding={2}
+      spacing={2}
+      backgroundColor="primary"
+    >
+      <StackView axis="horizontal" spacing={2}>
+        <Link color="white">Link 1</Link>
+        <Link color="white">Link 2</Link>
+        <Link color="white">Link 3</Link>
+      </StackView>
+      <ButtonCombobox
+        buttonProps={{
+          innerRef: containerRef,
+          title: 'search',
+          icon: { name: 'general.search', color: 'light-9' },
+          theme: 'light',
+          onClose: () => setValue(''),
+        }}
+        comboboxProps={{
+          value,
+          onChange: (event) => setValue(event.target.value),
+          onSelect: (person) => setValue(person.first + ' ' + person.last),
+          placeholder: 'Search by name, email, or phone number',
+          width: 40,
+          stroke: 'primary-light',
+          radius: 'pill',
+          placement: 'bottom-end',
+          popoverProps: {
+            width: 40,
+            matchWidths: false,
+            relativeTo: containerRef,
+          },
+        }}
+      >
+        <Combobox.Items
+          value={value}
+          filter={{ keys: [(person) => person.first + ' ' + person.last] }}
+          items={people}
+          renderItem={(person, index) => (
+            <Combobox.Item
+              key={person.first + ' ' + person.last}
+              value={person}
+              index={index}
+              spacing={1}
+            >
+              <Avatar
+                source={'https://api.adorable.io/avatars/' + index}
+                size="sm"
+              />
+              <Highlight
+                query={value}
+                text={person.first + ' ' + person.last}
+              />
+              <Text inline italic fontSize={5} marginLeft="auto" color="grey-6">
+                {person.twitter}
+              </Text>
+            </Combobox.Item>
+          )}
+          renderEmpty={[
+            <Menu.Item>
+              No results for
+              <Text as="span" inline color="grey-7">
+                "{value}"
+              </Text>
+            </Menu.Item>,
+          ]}
+        />
+      </ButtonCombobox>
+    </StackView>
+  )
+})
+```