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

package/src/CloseButton/v2/README.md

@@ -0,0 +1,70 @@
+---
+describes: CloseButton
+---
+
+Some design patterns require a `CloseButton` to be placed in the start or end position. This is a helper component that gives you the close icon out of the box and facilitates placement.
+
+The `placement` prop designates the `CloseButton` placement within the parent container. Note that in order to apply an `offset`, `placement` should be set to `start` or `end`. Also make sure that the container has a `position` css style applied other than `static`. In the following example we use [View](View) as the container and set the `position` to `relative`.
+
+```js
+---
+type: example
+---
+<View display="block" position="relative" height="5rem" background="primary" shadow="resting">
+  <CloseButton placement="end" offset="small" screenReaderLabel="Close" />
+</View>
+```
+
+If you need the `CloseButton` to work in a layout with other elements vs. absolutely positioning it, you can omit the `placement` prop or set it to `static`. You can then use another tool such as [Flex](Flex) to handle the layout.
+
+```js
+---
+type: example
+---
+<View display="block" position="relative" background="primary" shadow="resting">
+  <Flex height="6rem" justifyItems="space-between" alignItems="center" padding="medium">
+    <Flex.Item shouldShrink shouldGrow>
+      <Heading level="h2">Some Heading Text</Heading>
+    </Flex.Item>
+    <Flex.Item padding="none none none medium">
+      <CloseButton size="medium" screenReaderLabel="Close" />
+    </Flex.Item>
+  </Flex>
+</View>
+```
+
+If you need even more customization, note that you can always compose this component using the [IconButton](IconButton) directly. Supply the `renderIcon` prop with [XInstUIIcon](icons) and set the `withBorder` and `withBackground` props to `false`.
+
+```js
+---
+type: example
+---
+<View display="block" position="relative" height="5rem" background="primary" shadow="resting">
+  <Flex justifyItems="end">
+    <Flex.Item>
+      <IconButton
+        screenReaderLabel="Close"
+        renderIcon={XInstUIIcon}
+        size="small"
+        withBackground={false}
+        withBorder={false}
+        margin="small"
+      />
+    </Flex.Item>
+  </Flex>
+</View>
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="a11y" title="Accessibility">
+    <Figure.Item>Set the <code>color</code> prop to <code>primary</code> when a CloseButton appears on a dark background to ensure adequate contrast</Figure.Item>
+    <Figure.Item>Ensure the CloseButton is labeled correctly using the <code>screenReaderLabel</code> prop so screen readers announce what action will be taken when selected</Figure.Item>
+  </Figure>
+</Guidelines>
+```

package/src/CloseButton/v2/index.tsx

@@ -0,0 +1,142 @@
+/*
+ * 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 { XInstUIIcon } from '@instructure/ui-icons'
+import { ScreenReaderContent } from '@instructure/ui-a11y-content'
+import { getInteraction, passthroughProps } from '@instructure/ui-react-utils'
+
+import { withStyle } from '@instructure/emotion'
+
+import generateStyle from './styles'
+import { BaseButton } from '../../BaseButton/v2'
+
+import { allowedProps } from './props'
+import type { CloseButtonProps } from './props'
+
+/**
+---
+category: components
+---
+**/
+@withStyle(generateStyle, 'BaseButton')
+class CloseButton extends Component<CloseButtonProps> {
+  static readonly componentId = 'CloseButton'
+
+  static allowedProps = allowedProps
+  static defaultProps = {
+    // Leave interaction default undefined so that `disabled` and `readOnly` can also be supplied
+    interaction: undefined,
+    type: 'button',
+    placement: 'static',
+    offset: 'x-small',
+    size: 'small',
+    margin: '0',
+    as: 'button',
+    cursor: 'pointer'
+  }
+
+  ref: Element | null = null
+
+  handleRef = (el: Element | null) => {
+    const { elementRef } = this.props
+    if (typeof elementRef === 'function') {
+      elementRef(el)
+    }
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+  }
+
+  get interaction() {
+    return getInteraction({ props: this.props })
+  }
+
+  get color() {
+    const { color } = this.props
+
+    return color === 'primary' ? 'secondary' : color
+  }
+
+  render() {
+    const {
+      screenReaderLabel,
+      elementRef,
+      size,
+      onClick,
+      margin,
+      placement,
+      offset,
+      type,
+      as,
+      href,
+      cursor,
+      tabIndex,
+      styles,
+      ...props
+    } = this.props
+
+    const themeOverride = this.props.themeOverride
+
+    return (
+      <span
+        {...passthroughProps(props)}
+        css={styles?.closeButton}
+        ref={(el) => {
+          this.ref = el
+        }}
+      >
+        <BaseButton
+          renderIcon={XInstUIIcon}
+          elementRef={this.handleRef}
+          interaction={this.interaction}
+          type={type}
+          {...(this.color ? { color: this.color } : {})}
+          size={size}
+          onClick={onClick}
+          margin={margin}
+          withBorder={false}
+          withBackground={false}
+          as={as}
+          href={href}
+          cursor={cursor}
+          tabIndex={tabIndex}
+          themeOverride={themeOverride}
+          data-cid="CloseButton"
+        >
+          <ScreenReaderContent>{screenReaderLabel}</ScreenReaderContent>
+        </BaseButton>
+      </span>
+    )
+  }
+}
+
+export default CloseButton
+export { CloseButton }

package/src/CloseButton/v2/props.ts

@@ -0,0 +1,148 @@
+/*
+ * 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 {
+  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'
+
+type CloseButtonOwnProps = {
+  /**
+   * An accessible label for the `CloseButton` (required)
+   */
+  screenReaderLabel: React.ReactNode
+
+  /**
+   * Specifies the color for the `CloseButton`.
+   */
+  color?: 'primary' | 'primary-inverse'
+
+  /**
+   * Specifies if interaction with the `CloseButton` is enabled, disabled, or readonly.
+   */
+  interaction?: 'enabled' | 'disabled' | 'readonly'
+
+  /**
+   * Provides a reference to the `CloseButton`'s underlying html element.
+   */
+  elementRef?: (element: Element | null) => void
+
+  /**
+   * The size of the `CloseButton`
+   */
+  size?: 'small' | 'medium' | 'large'
+
+  /**
+   * Callback fired when the `CloseButton` is clicked.
+   */
+  onClick?: (
+    event: React.KeyboardEvent<ViewProps> | React.MouseEvent<ViewProps>
+  ) => void
+
+  /**
+   * 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
+
+  /**
+   * Specifies the placement of the `CloseButton`
+   */
+  placement?: 'start' | 'end' | 'static'
+
+  /**
+   * Specifies the offset distance for the `CloseButton` with respect to both the top and start/end of the container.
+   * Note that for this property to have an effect, the `placement` prop must be set to either `start` or `end`. The
+   * offset will also be created with respect to a positioned parent. If it does not appear to be working, try setting
+   * the `position` of the parent container to `relative`.
+   */
+  offset?: 'none' | 'x-small' | 'small' | 'medium'
+
+  /**
+   * Specifies the type of the `Button`'s underlying html element.
+   */
+  type?: 'button' | 'submit' | 'reset'
+
+  /**
+   * The element to render as the component root, `CloseButton` by default.
+   */
+  as?: AsElementType
+
+  /**
+   * Specifies an href attribute for the `CloseButton`'s underlying html element.
+   */
+  href?: string
+
+  /**
+   * Specify a mouse cursor to use when hovering over the `CloseButton`.
+   */
+  cursor?: Cursor
+
+  /**
+   * Specifies the tabindex of the `CloseButton`.
+   *
+   */
+  tabIndex?: number
+}
+
+type PropKeys = keyof CloseButtonOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type CloseButtonProps = CloseButtonOwnProps &
+  WithStyleProps<BaseButtonTheme, CloseButtonStyle> &
+  OtherHTMLAttributes<CloseButtonOwnProps> &
+  ToProp
+
+type CloseButtonStyle = ComponentStyle<'closeButton'>
+const allowedProps: AllowedPropKeys = [
+  'as',
+  'color',
+  'cursor',
+  'elementRef',
+  'href',
+  'interaction',
+  'margin',
+  'offset',
+  'onClick',
+  'placement',
+  'screenReaderLabel',
+  'size',
+  'tabIndex',
+  'type'
+]
+
+export type { CloseButtonProps, CloseButtonStyle }
+export { allowedProps }

package/src/CloseButton/v2/styles.ts

@@ -0,0 +1,81 @@
+/*
+ * 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 type { NewComponentTypes, SharedTokens } from '@instructure/ui-themes'
+import type { CloseButtonProps, CloseButtonStyle } from './props'
+
+/**
+ * ---
+ * private: true
+ * ---
+ * Generates the style object from the theme and provided additional information
+ * @param  {Object} _componentTheme The theme variable object.
+ * @param  {Object} props the props of the component, the style is applied to
+ * @param  {Object} sharedTokens the shared design tokens
+ * @return {Object} The final style object, which will be used in the component
+ */
+const generateStyle = (
+  _componentTheme: NewComponentTypes['BaseButton'],
+  props: CloseButtonProps,
+  sharedTokens: SharedTokens
+): CloseButtonStyle => {
+  const { placement, offset } = props
+
+  const offsetValueMap = {
+    none: 0,
+    'x-small': sharedTokens.spacing.general.spaceXs,
+    small: sharedTokens.spacing.general.spaceSm,
+    medium: sharedTokens.spacing.general.spaceMd,
+  }
+
+  const getOffsetStyle = () => {
+    const offsetValue = offsetValueMap[offset!]
+
+    return {
+      ...(offsetValue !== 0 && {
+        top: offsetValue
+      }),
+      insetInlineStart: placement === 'start' ? offsetValue : 'auto',
+      insetInlineEnd: placement === 'end' ? offsetValue : 'auto'
+    }
+  }
+
+  return {
+    closeButton: {
+      label: 'closeButton',
+      zIndex: 1,
+      display: 'inline-block',
+      ...(placement === 'static'
+        ? {
+            position: 'static'
+          }
+        : {
+            position: 'absolute',
+            ...getOffsetStyle()
+          })
+    }
+  }
+}
+
+export default generateStyle

package/src/CondensedButton/{index.tsx → v1/index.tsx}

@@ -26,10 +26,10 @@ import { Component } from 'react'
 
 import { passthroughProps } from '@instructure/ui-react-utils'
 
-import { withStyle } from '@instructure/emotion'
+import { withStyleLegacy as withStyle } from '@instructure/emotion'
 
 import generateComponentTheme from './theme'
-import { BaseButton } from '../BaseButton'
+import { BaseButton } from '../../BaseButton/v1'
 
 import { allowedProps } from './props'
 import type { CondensedButtonProps } from './props'

package/src/CondensedButton/{props.ts → v1/props.ts}

@@ -31,7 +31,7 @@ import type {
   OtherHTMLAttributes
 } from '@instructure/shared-types'
 import type { Cursor } from '@instructure/shared-types'
-import type { ViewProps } from '@instructure/ui-view'
+import type { ViewProps } from '@instructure/ui-view/v11_6'
 
 type CondensedButtonOwnProps = {
   /**

package/src/{Button → CondensedButton/v1}/theme.ts

@@ -22,4 +22,4 @@
  * SOFTWARE.
  */
 
-export { default } from '../BaseButton/theme'
+export { default } from '../../BaseButton/v1/theme'

package/src/CondensedButton/v2/README.md

@@ -0,0 +1,75 @@
+---
+describes: CondensedButton
+---
+
+CondensedButton is a button component that renders without padding. It is meant specifically for tight spaces, or areas where the button padding would prevent the button content from aligning correctly with other elements.
+
+```js
+---
+type: example
+---
+<View display="block" background="primary" padding="small">
+  <CondensedButton>Click Me</CondensedButton>
+</View>
+```
+
+In the following example, CondensedButton is used so that the button content can align with the rest of the table cell content.
+
+```js
+---
+type: example
+---
+<Table caption='Tallest Roller Coasters'>
+  <Table.Head>
+    <Table.Row>
+      <Table.ColHeader id="Roller Coaster">
+        Roller Coaster
+      </Table.ColHeader>
+      <Table.ColHeader id="Height">
+        Height
+      </Table.ColHeader>
+      <Table.ColHeader id="Amusement Park">
+        Amusement Park
+      </Table.ColHeader>
+    </Table.Row>
+  </Table.Head>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>
+        Kingda Ka<br />
+        <CondensedButton>View Advanced Stats</CondensedButton>
+      </Table.Cell>
+      <Table.Cell>
+        456.0ft
+      </Table.Cell>
+      <Table.Cell>
+        Six Flags Great America
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        Top Thrill Dragster<br />
+        <CondensedButton>View Advanced Stats</CondensedButton>
+      </Table.Cell>
+      <Table.Cell>
+        420.0ft
+      </Table.Cell>
+      <Table.Cell>
+        Cedar Point
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        Superman: Escape from Krypton<br />
+        <CondensedButton>View Advanced Stats</CondensedButton>
+      </Table.Cell>
+      <Table.Cell>
+        415.0ft
+      </Table.Cell>
+      <Table.Cell>
+        Six Flags Magic Mountain
+      </Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>
+```

package/src/CondensedButton/v2/index.tsx

@@ -0,0 +1,129 @@
+/*
+ * 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 { passthroughProps } from '@instructure/ui-react-utils'
+
+import { withStyle } from '@instructure/emotion'
+import { BaseButton } from '../../BaseButton/v2'
+
+import { allowedProps } from './props'
+import type { CondensedButtonProps } from './props'
+
+/**
+---
+category: components
+---
+**/
+// needed for listing the available theme variables on docs page
+@withStyle(null, 'BaseButton')
+class CondensedButton extends Component<CondensedButtonProps> {
+  static readonly componentId = 'CondensedButton'
+
+  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: 'primary',
+    margin: '0',
+    cursor: 'pointer',
+    display: 'inline-block'
+  }
+
+  _baseButton: BaseButton | null = null
+
+  ref: Element | null = null
+
+  handleRef = (el: Element | null) => {
+    const { elementRef } = this.props
+
+    this.ref = el
+
+    if (typeof elementRef === 'function') {
+      elementRef(el)
+    }
+  }
+
+  get focused() {
+    return this._baseButton && this._baseButton.focused
+  }
+
+  focus() {
+    this._baseButton && this._baseButton.focus()
+  }
+
+  render() {
+    const {
+      children,
+      type,
+      size,
+      elementRef,
+      as,
+      interaction,
+      color,
+      margin,
+      cursor,
+      href,
+      renderIcon,
+      display,
+      ...props
+    } = this.props
+
+    const themeOverride = this.props.themeOverride
+
+    return (
+      <BaseButton
+        {...passthroughProps(props)}
+        isCondensed
+        display={display}
+        withBackground={false}
+        withBorder={false}
+        type={type}
+        size={size}
+        elementRef={this.handleRef}
+        as={as}
+        interaction={interaction}
+        color={color}
+        margin={margin}
+        cursor={cursor}
+        href={href}
+        renderIcon={renderIcon}
+        themeOverride={themeOverride}
+        ref={(component) => {
+          this._baseButton = component
+        }}
+        data-cid="CondensedButton"
+      >
+        {children}
+      </BaseButton>
+    )
+  }
+}
+
+export default CondensedButton
+export { CondensedButton }