@instructure/ui-buttons 11.6.0 → 11.6.1-snapshot-129

package/src/BaseButton/v2/index.tsx

@@ -0,0 +1,343 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Component } from 'react'
+import keycode from 'keycode'
+
+import {
+  getElementType,
+  getInteraction,
+  passthroughProps
+} from '@instructure/ui-react-utils'
+import { isActiveElement } from '@instructure/ui-dom-utils'
+import { hasVisibleChildren } from '@instructure/ui-a11y-utils'
+import { renderIconWithProps } from '@instructure/ui-icons'
+import { View } from '@instructure/ui-view/latest'
+import type { ViewProps } from '@instructure/ui-view/latest'
+
+// TODO these have to be imported in separate lines because otherwise `isSafari` will be missing from the babel build
+// this bug is very likely caused by `babel-plugin-transform-imports` and can be reverted once it is removed from the codebase
+import { isSafari } from '@instructure/ui-utils'
+import { combineDataCid } from '@instructure/ui-utils'
+
+import { withStyle } from '@instructure/emotion'
+
+import generateStyles from './styles'
+
+import { allowedProps } from './props'
+import type { BaseButtonProps, BaseButtonStyleProps } from './props'
+
+const buttonSizeToIconSize = {
+  small: 'sm',
+  medium: 'md',
+  large: 'lg',
+  condensedSmall: 'xs',
+  condensedMedium: 'xs'
+} as const
+
+const buttonColorToIconColor = {
+  'primary': 'inherit',
+  'primary-inverse': 'inherit',
+  'secondary': 'inherit',
+  'success': 'inherit',
+  'danger': 'inherit',
+  'ai-primary': 'inherit',
+  'ai-secondary': 'ai'
+} as const
+
+/**
+---
+category: components/utilities
+---
+**/
+@withStyle(generateStyles)
+class BaseButton extends Component<BaseButtonProps> {
+  static readonly componentId = 'BaseButton'
+
+  static allowedProps = allowedProps
+  static defaultProps = {
+    type: 'button',
+    size: 'medium',
+    as: 'button',
+    // Leave interaction default undefined so that `disabled` and `readOnly` can also be supplied
+    interaction: undefined,
+    color: 'secondary',
+    shape: 'rectangle',
+    display: 'inline-block',
+    textAlign: 'start',
+    withBackground: true,
+    withBorder: true,
+    isCondensed: false,
+    margin: '0',
+    cursor: 'pointer'
+  } as const
+
+  ref: HTMLElement | null = null
+
+  componentDidMount() {
+    this.props.makeStyles?.(this.makeStylesVariables)
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.(this.makeStylesVariables)
+  }
+
+  get makeStylesVariables(): BaseButtonStyleProps {
+    return {
+      isDisabled: this.isDisabled,
+      hasOnlyIconVisible: this.hasOnlyIconVisible,
+      isEnabled: this.isEnabled
+    }
+  }
+
+  get hasOnlyIconVisible() {
+    const { children, renderIcon } = this.props
+    return !!(renderIcon && !hasVisibleChildren(children))
+  }
+
+  get elementType() {
+    return getElementType(BaseButton, this.props)
+  }
+
+  get interaction() {
+    return getInteraction({ props: this.props })
+  }
+
+  get isDisabled() {
+    return this.interaction === 'disabled'
+  }
+
+  get isReadOnly() {
+    return this.interaction === 'readonly'
+  }
+
+  get isEnabled() {
+    return this.interaction === 'enabled'
+  }
+
+  get focusColor() {
+    const { color, focusColor, withBackground } = this.props
+
+    // Give user specified focusColor preference
+    if (focusColor) {
+      return focusColor
+    }
+
+    // The `primary-inverse` background has an info focus outline
+    // by default since it is replacing the `light` button variant.
+    // Override the focus color with info even though it is
+    // an inverse color
+    if (color === 'primary-inverse' && withBackground) {
+      return 'info'
+    }
+
+    return color!.includes('inverse') ? 'inverse' : 'info'
+  }
+
+  get focused() {
+    return isActiveElement(this.ref)
+  }
+
+  focus() {
+    this.ref && this.ref.focus()
+  }
+
+  handleElementRef = (el: HTMLElement | null) => {
+    const { elementRef } = this.props
+
+    this.ref = el
+
+    if (typeof elementRef === 'function') {
+      elementRef(el)
+    }
+  }
+
+  handleClick = (event: React.MouseEvent<ViewProps & Element>) => {
+    const { onClick } = this.props
+    const { interaction } = this
+
+    if (interaction !== 'enabled') {
+      event.preventDefault()
+      event.stopPropagation()
+      return
+    }
+
+    if (typeof onClick === 'function') {
+      onClick(event)
+    }
+  }
+
+  handleKeyDown = (event: React.KeyboardEvent<ViewProps & Element>) => {
+    const { onClick, onKeyDown, href } = this.props
+    const { interaction } = this
+
+    if (typeof onKeyDown === 'function') {
+      onKeyDown(event)
+    }
+
+    // behave like a button when space key is pressed
+    const { space, enter } = keycode.codes
+
+    if (
+      this.elementType !== 'button' &&
+      [space, enter].includes(event.keyCode)
+    ) {
+      event.preventDefault()
+      event.stopPropagation()
+
+      if (typeof onClick === 'function' && interaction === 'enabled') {
+        onClick(event)
+      }
+
+      if (href) {
+        this.ref && (this.ref as HTMLElement).click()
+      }
+    }
+  }
+
+  renderChildren() {
+    const { renderIcon, children, styles, size, color } = this.props
+
+    const wrappedChildren = <span css={styles?.children}>{children}</span>
+
+    if (!renderIcon) {
+      return wrappedChildren
+    }
+
+    const { hasOnlyIconVisible } = this
+    const iconSize = buttonSizeToIconSize[size!]
+    const iconColor = buttonColorToIconColor[color!]
+    const wrappedIcon = (
+      <span css={styles?.iconSVG}>
+        {renderIconWithProps(renderIcon, iconSize, iconColor)}
+      </span>
+    )
+
+    const flexChildren = hasOnlyIconVisible ? (
+      <span css={styles?.iconOnly}>
+        {wrappedIcon}
+        {children}
+      </span>
+    ) : (
+      [
+        <span key="icon" css={styles?.iconWrapper}>
+          {wrappedIcon}
+        </span>,
+        <span key="children" css={styles?.childrenWrapper}>
+          {wrappedChildren}
+        </span>
+      ]
+    )
+    return <span css={styles?.childrenLayout}>{flexChildren}</span>
+  }
+
+  render() {
+    const {
+      type,
+      size,
+      elementRef,
+      as,
+      href,
+      color,
+      focusColor,
+      textAlign,
+      shape,
+      display,
+      withBackground,
+      withBorder,
+      isCondensed,
+      margin,
+      cursor,
+      onClick,
+      renderIcon,
+      tabIndex,
+      styles,
+      makeStyles,
+      withFocusOutline,
+      ...props
+    } = this.props
+
+    const { isDisabled, isReadOnly, elementType } = this
+    // only add 0 tabIndex value if it doesn't have it by default, see
+    // https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex
+    let needsZeroTabIndex = true
+    if (typeof elementType == 'string') {
+      if (
+        [
+          'button',
+          'frame',
+          'iframe',
+          'input',
+          'object',
+          'select',
+          'textarea',
+          'summary'
+        ].includes(elementType)
+      ) {
+        needsZeroTabIndex = false
+      }
+      if (href && (elementType === 'a' || elementType === 'area')) {
+        needsZeroTabIndex = false
+      }
+    }
+    let tabIndexValue = tabIndex
+    // In Safari, a button cannot get focus unless it has an explicit 0 tabindex
+    if ((onClick && as && needsZeroTabIndex) || (isSafari() && as)) {
+      tabIndexValue = tabIndex || 0
+    }
+
+    return (
+      <View
+        {...passthroughProps(props)}
+        as={elementType}
+        focusColor={this.focusColor}
+        position="relative"
+        display={display}
+        width={display === 'block' ? '100%' : 'auto'}
+        borderRadius={shape === 'circle' ? 'circle' : 'medium'}
+        background="transparent"
+        padding="none"
+        borderWidth="none"
+        margin={margin}
+        cursor={isDisabled ? 'not-allowed' : cursor}
+        href={href}
+        type={href ? undefined : type}
+        elementRef={this.handleElementRef}
+        onClick={this.handleClick}
+        onKeyDown={this.handleKeyDown}
+        role={onClick && as !== 'button' ? 'button' : undefined}
+        tabIndex={tabIndexValue}
+        disabled={isDisabled || isReadOnly}
+        css={styles?.baseButton}
+        withFocusOutline={withFocusOutline}
+        data-cid={combineDataCid('BaseButton', this.props)}
+      >
+        <span css={styles?.content}>{this.renderChildren()}</span>
+      </View>
+    )
+  }
+}
+
+export { BaseButton }
+export default BaseButton

package/src/BaseButton/v2/props.ts

@@ -0,0 +1,226 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import React from 'react'
+import type { InteractionType } from '@instructure/ui-react-utils'
+import type {
+  Spacing,
+  WithStyleProps,
+  ComponentStyle
+} from '@instructure/emotion'
+import type {
+  ToProp,
+  AsElementType,
+  BaseButtonTheme,
+  OtherHTMLAttributes
+} from '@instructure/shared-types'
+import type { Cursor } from '@instructure/shared-types'
+import type { ViewProps } from '@instructure/ui-view/latest'
+import { Renderable } from '@instructure/shared-types'
+
+type BaseButtonOwnProps = {
+  /**
+   * Specifies the `Button` children.
+   */
+  children?: React.ReactNode
+
+  /**
+   * Specifies the type of the `Button`'s underlying html element.
+   */
+  type?: 'button' | 'submit' | 'reset'
+
+  /**
+   * The size of the `Button`
+   */
+  size?: 'small' | 'medium' | 'large' | 'condensedSmall' | 'condensedMedium'
+
+  /**
+   * Provides a reference to the `Button`'s underlying html element.
+   */
+  elementRef?: (element: HTMLElement | null) => void
+
+  /**
+   * The element to render as the component root, `Button` by default.
+   */
+  as?: AsElementType
+
+  /**
+   * Specifies if interaction with the `Button` is enabled, disabled, or readonly.
+   */
+  interaction?: InteractionType
+
+  /**
+   * Specifies the color for the `Button`.
+   */
+  color?:
+    | 'primary'
+    | 'primary-inverse'
+    | 'secondary'
+    | 'success'
+    | 'danger'
+    | 'ai-primary'
+    | 'ai-secondary'
+
+  /**
+   * Override the `Button`'s default focus outline color.
+   */
+  focusColor?: 'info' | 'inverse'
+
+  /**
+   * The `Button` display property. When set to `inline-block`, the `Button` displays inline with other elements.
+   * When set to block, the `Button` expands to fill the width of the container.
+   */
+  display?: 'inline-block' | 'block'
+
+  /**
+   * Sets the alignment of the `Button` children and/or icon.
+   */
+  textAlign?: 'start' | 'center'
+
+  /**
+   * Specifies if the `Button` shape should be a circle or rectangle.
+   */
+  shape?: 'rectangle' | 'circle'
+
+  /**
+   * Specifies if the `Button` should render with a solid background. When false, the background is transparent.
+   */
+  withBackground?: boolean
+
+  /**
+   * Specifies if the `Button` should render with a border.
+   */
+  withBorder?: boolean
+
+  /**
+   * Designates if the `Button` should render without padding. This option should only be set when `withBorder` and
+   * `withBackground` are also set to false.
+   */
+  isCondensed?: boolean
+
+  /**
+   * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`,
+   * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via
+   * familiar CSS-like shorthand. For example: `margin="small auto large"`.
+   */
+  margin?: Spacing
+
+  /**
+   * Specify a mouse cursor to use when hovering over the button.
+   * The `pointer` cursor is used by default.
+   */
+  cursor?: Cursor
+
+  /**
+   * Specifies an href attribute for the `Button`'s underlying html element.
+   */
+  href?: string
+
+  /**
+   * Callback fired when the `Button` is clicked.
+   */
+  onClick?: (
+    event: React.KeyboardEvent<ViewProps> | React.MouseEvent<ViewProps>
+  ) => void
+
+  /**
+   * Callback fired when the `Button` receives a keydown event.
+   */
+  onKeyDown?: (event: React.KeyboardEvent<ViewProps>) => void
+
+  /**
+   * An icon, or function that returns an icon.
+   */
+  renderIcon?: Renderable
+
+  /**
+   * Specifies the tabindex of the `Button`.
+   */
+  tabIndex?: number
+
+  /**
+   * Manually control if the `Button` should display a focus outline.
+   *
+   * When left `undefined` (which is the default) the focus outline will display
+   * if this component is focusable and receives focus.
+   */
+  withFocusOutline?: boolean
+}
+
+type BaseButtonStyleProps = {
+  isDisabled: boolean
+  hasOnlyIconVisible: boolean
+  isEnabled: boolean
+}
+
+type PropKeys = keyof BaseButtonOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type BaseButtonProps = BaseButtonOwnProps &
+  WithStyleProps<BaseButtonTheme, BaseButtonStyle> &
+  OtherHTMLAttributes<BaseButtonOwnProps> &
+  ToProp
+
+type BaseButtonStyle = ComponentStyle<
+  | 'baseButton'
+  | 'content'
+  | 'children'
+  | 'iconSVG'
+  | 'childrenLayout'
+  | 'iconOnly'
+  | 'iconWrapper'
+  | 'childrenWrapper'
+>
+const allowedProps: AllowedPropKeys = [
+  'as',
+  'children',
+  'color',
+  'cursor',
+  'display',
+  'elementRef',
+  'focusColor',
+  'href',
+  'interaction',
+  'isCondensed',
+  'margin',
+  'onClick',
+  'onKeyDown',
+  'renderIcon',
+  'shape',
+  'size',
+  'tabIndex',
+  'textAlign',
+  'type',
+  'withBackground',
+  'withBorder'
+]
+
+export type {
+  BaseButtonProps,
+  BaseButtonOwnProps,
+  BaseButtonStyleProps,
+  BaseButtonStyle
+}
+export { allowedProps }