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

package/src/CondensedButton/v2/props.ts

@@ -0,0 +1,134 @@
+/*
+ * 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 } 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 CondensedButtonOwnProps = {
+  /**
+   * Specifies the `CondensedButton` children.
+   */
+  children?: React.ReactNode
+
+  /**
+   * Specifies the type of the `CondensedButton`'s underlying html element.
+   */
+  type?: 'button' | 'submit' | 'reset'
+
+  /**
+   * The size of the `CondensedButton`
+   */
+  size?: 'small' | 'medium' | 'large' | 'condensedSmall' | 'condensedMedium'
+
+  /**
+   * Provides a reference to the `CondensedButton`'s underlying html element.
+   */
+  elementRef?: (element: Element | null) => void
+
+  /**
+   * The element to render as the component root, `button` by default.
+   */
+  as?: AsElementType
+
+  /**
+   * Specifies if interaction with the `CondensedButton` is enabled, disabled, or readonly.
+   */
+  interaction?: 'enabled' | 'disabled' | 'readonly'
+
+  /**
+   * Specifies the color for the `CondensedButton`.
+   */
+  color?: 'primary' | 'primary-inverse' | 'secondary'
+
+  /**
+   * 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 `CondensedButton`'s underlying html element.
+   */
+  href?: string
+
+  /**
+   * An icon, or function that returns an icon.
+   */
+  renderIcon?: React.ReactNode | (() => React.ReactNode)
+
+  /**
+   * Callback fired when the `CondensedButton` is clicked.
+   */
+  onClick?: (
+    event: React.KeyboardEvent<ViewProps> | React.MouseEvent<ViewProps>
+  ) => void
+
+  /**
+   * The CSS display property of the button, `inline-block` or `block`
+   */
+  display?: 'inline-block' | 'block'
+}
+
+type PropKeys = keyof CondensedButtonOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type CondensedButtonProps = CondensedButtonOwnProps &
+  WithStyleProps<BaseButtonTheme, null> &
+  OtherHTMLAttributes<CondensedButtonOwnProps> &
+  ToProp
+
+const allowedProps: AllowedPropKeys = [
+  'as',
+  'children',
+  'color',
+  'cursor',
+  'elementRef',
+  'href',
+  'interaction',
+  'margin',
+  'renderIcon',
+  'size',
+  'type',
+  'onClick',
+  'display'
+]
+
+export type { CondensedButtonProps }
+export { allowedProps }

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

@@ -28,10 +28,10 @@ import { passthroughProps } from '@instructure/ui-react-utils'
 import { ScreenReaderContent } from '@instructure/ui-a11y-content'
 import { combineDataCid } from '@instructure/ui-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 { IconButtonProps } from './props'

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

@@ -33,7 +33,7 @@ import type {
   Renderable
 } 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 IconButtonOwnProps = {
   /**

package/src/IconButton/{theme.ts → v1/theme.ts}

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

package/src/IconButton/v2/README.md

@@ -0,0 +1,86 @@
+---
+describes: IconButton
+---
+
+An IconButton can be used when the Button only renders an Icon and does not have other visual elements or text content.
+It is not recommended to set the size of an icon inside an IconButton. Only use the `size` property of the IconButton.
+
+```js
+---
+type: example
+---
+<IconButton screenReaderLabel="Add User"><PlusInstUIIcon /></IconButton>
+```
+
+### Accessibility
+
+Because the IconButton visually only renders an icon, a description is necessary for assistive technologies. The `screenReaderLabel` prop is required for this purpose, and should consist of a complete description of the action.
+
+```js
+---
+type: example
+---
+<IconButton color="primary" screenReaderLabel="Add blog post"><PlusInstUIIcon /></IconButton>
+```
+
+Using [Tooltip](Tooltip) in conjunction with IconButton can also provide necessary context when the IconButton alone would be insufficient.
+
+```js
+---
+type: example
+---
+<Tooltip
+  renderTip="View user profile"
+  on={['hover', 'focus']}
+  placement="bottom"
+>
+  <IconButton screenReaderLabel="View user profile"><UserInstUIIcon /></IconButton>
+</Tooltip>
+```
+
+### AI Icon buttons
+
+```js
+---
+type: example
+---
+<View display="block">
+  <IconButton color="ai-primary" screenReaderLabel="AI button" margin="small"><IgniteaiLogoInstUIIcon/></IconButton>
+  <IconButton color="ai-secondary" screenReaderLabel="AI button"  margin="small"><IgniteaiLogoInstUIIcon/></IconButton>
+</View>
+```
+
+### Shaping
+
+The `shape` prop specifies if the IconButton will render as a `rectangle` or `circle`.
+
+```js
+---
+type: example
+---
+<View display="block">
+  <IconButton shape="rectangle" screenReaderLabel="Delete tag" margin="small"><XInstUIIcon /></IconButton>
+  <IconButton shape="circle" screenReaderLabel="Delete tag" margin="small"><XInstUIIcon /></IconButton>
+</View>
+```
+
+### Rendering only the icon
+
+The background and border can be optionally removed as needed by setting the `withBorder` and `withBackground` props to `false`
+
+```js
+---
+type: example
+---
+<View display="block">
+  <View display="inline-block" background="primary">
+    <IconButton withBackground={false} withBorder={false} screenReaderLabel="Delete tag" margin="large">
+      <XInstUIIcon />
+    </IconButton>
+  </View>
+</View>
+```
+
+### Styling
+
+For an example see [Button](Button/#Styling%20buttons)

package/src/IconButton/v2/index.tsx

@@ -0,0 +1,138 @@
+/*
+ * 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 { ScreenReaderContent } from '@instructure/ui-a11y-content'
+import { combineDataCid } from '@instructure/ui-utils'
+
+import { withStyle } from '@instructure/emotion'
+import { BaseButton } from '../../BaseButton/v2'
+
+import { allowedProps } from './props'
+import type { IconButtonProps } from './props'
+
+/**
+---
+category: components
+---
+**/
+
+// needed for listing the available theme variables on docs page
+@withStyle(null, 'BaseButton')
+class IconButton extends Component<IconButtonProps> {
+  static readonly componentId = 'IconButton'
+
+  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',
+    withBackground: true,
+    withBorder: true,
+    margin: '0',
+    cursor: 'pointer'
+  }
+
+  _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,
+      renderIcon,
+      screenReaderLabel,
+      type,
+      size,
+      elementRef,
+      as,
+      interaction,
+      color,
+      focusColor,
+      shape,
+      withBackground,
+      withBorder,
+      margin,
+      cursor,
+      href,
+      ...props
+    } = this.props
+
+    const themeOverride = this.props.themeOverride
+
+    return (
+      <BaseButton
+        {...passthroughProps(props)}
+        type={type}
+        size={size}
+        elementRef={this.handleRef}
+        as={as}
+        interaction={interaction}
+        color={color}
+        focusColor={focusColor}
+        shape={shape}
+        withBackground={withBackground}
+        withBorder={withBorder}
+        margin={margin}
+        cursor={cursor}
+        href={href}
+        renderIcon={children || renderIcon}
+        themeOverride={themeOverride}
+        ref={(component) => {
+          this._baseButton = component
+        }}
+        data-cid={combineDataCid('IconButton', this.props)}
+      >
+        <ScreenReaderContent>{screenReaderLabel}</ScreenReaderContent>
+      </BaseButton>
+    )
+  }
+}
+
+export default IconButton
+export { IconButton }

package/src/IconButton/v2/props.ts

@@ -0,0 +1,166 @@
+/*
+ * 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 { ReactNode } from 'react'
+
+import type { Spacing, WithStyleProps } from '@instructure/emotion'
+import type {
+  ToProp,
+  AsElementType,
+  BaseButtonTheme,
+  OtherHTMLAttributes,
+  Renderable
+} from '@instructure/shared-types'
+import type { Cursor } from '@instructure/shared-types'
+import type { ViewProps } from '@instructure/ui-view/latest'
+
+type IconButtonOwnProps = {
+  /**
+   * An icon, or function returning an icon (identical to the `renderIcon` prop).
+   */
+  children?: Renderable
+
+  /**
+   * An icon, or function that returns an icon (identical to the `children` prop).
+   */
+  renderIcon?: Renderable
+
+  /**
+   * An accessible label for the `IconButton`.
+   */
+  screenReaderLabel: ReactNode
+
+  /**
+   * Specifies the type of the `IconButton`'s underlying html element.
+   */
+  type?: 'button' | 'submit' | 'reset'
+
+  /**
+   * The size of the `IconButton`
+   */
+  size?: 'small' | 'medium' | 'large'
+
+  /**
+   * Provides a reference to the `IconButton`'s underlying html element.
+   */
+  elementRef?: (element: Element | null) => void
+
+  /**
+   * The element to render as the component root, `button` by default.
+   */
+  as?: AsElementType
+
+  /**
+   * Specifies if interaction with the `IconButton` is enabled, disabled, or readonly.
+   */
+  interaction?: 'enabled' | 'disabled' | 'readonly'
+
+  /**
+   * Specifies the color for the `IconButton`.
+   */
+  color?:
+    | 'primary'
+    | 'primary-inverse'
+    | 'secondary'
+    | 'success'
+    | 'danger'
+    | 'ai-primary'
+    | 'ai-secondary'
+
+  /**
+   * Override the `Button`'s default focus outline color.
+   */
+  focusColor?: 'info' | 'inverse'
+
+  /**
+   * Specifies if the `IconButton` shape should be a circle or rectangle.
+   */
+  shape?: 'rectangle' | 'circle'
+
+  /**
+   * Specifies if the `IconButton` should render with a solid background. When false, the background is transparent.
+   */
+  withBackground?: boolean
+
+  /**
+   * Specifies if the `IconButton` should render with a border.
+   */
+  withBorder?: 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 `IconButton`'s underlying html element.
+   */
+  href?: string
+
+  /**
+   * Callback fired when the `Button` is clicked.
+   */
+  onClick?: (
+    event: React.KeyboardEvent<ViewProps> | React.MouseEvent<ViewProps>
+  ) => void
+}
+
+type PropKeys = keyof IconButtonOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type IconButtonProps = IconButtonOwnProps &
+  WithStyleProps<BaseButtonTheme, null> &
+  OtherHTMLAttributes<IconButtonOwnProps> &
+  ToProp
+const allowedProps: AllowedPropKeys = [
+  'as',
+  'children',
+  'color',
+  'cursor',
+  'elementRef',
+  'focusColor',
+  'href',
+  'interaction',
+  'margin',
+  'renderIcon',
+  'screenReaderLabel',
+  'shape',
+  'size',
+  'type',
+  'withBackground',
+  'withBorder',
+  'onClick'
+]
+
+export type { IconButtonProps }
+export { allowedProps }

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

@@ -26,8 +26,8 @@ import { Component } from 'react'
 
 import { callRenderProp, passthroughProps } from '@instructure/ui-react-utils'
 
-import { Tooltip } from '@instructure/ui-tooltip'
-import { IconButton } from '../IconButton'
+import { Tooltip } from '@instructure/ui-tooltip/v11_6'
+import { IconButton } from '../../IconButton/v1'
 
 import { allowedProps } from './props'
 import type { ToggleButtonProps, ToggleButtonState } from './props'

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

@@ -33,7 +33,7 @@ import type {
   PositionConstraint,
   PositionMountNode
 } from '@instructure/ui-position'
-import type { ViewProps } from '@instructure/ui-view'
+import type { ViewProps } from '@instructure/ui-view/v11_6'
 import { Renderable } from '@instructure/shared-types'
 
 type ToggleButtonOwnProps = {

package/src/ToggleButton/v2/README.md

@@ -0,0 +1,85 @@
+---
+describes: ToggleButton
+---
+
+`ToggleButton` is a controlled button component used for toggling a status or setting
+between one of two states (locked/unlocked, published/unpublished, etc.).
+
+```js
+---
+type: example
+---
+  const Example = () => {
+    const [locked, setLocked] = useState(false)
+
+    const handleLocked = () => {
+      setLocked(!locked)
+    }
+
+    return (
+      <View as="div" padding="x-large" id="toggleContainer">
+        <ToggleButton
+          status={locked ? 'pressed' : 'unpressed'}
+          color={locked ? 'danger' : 'secondary'}
+          renderIcon={locked ? LockInstUIIcon : UnlockInstUIIcon}
+          screenReaderLabel={locked ? 'Unlock assignment' : 'Lock assignment'}
+          renderTooltipContent={locked ? 'Unlock' : 'Lock'}
+          onClick={handleLocked}
+        />
+      </View>
+    )
+  }
+
+  render(<Example />)
+```
+
+### Inverse ToggleButton
+
+```js
+---
+type: example
+---
+  const InverseExample = () => {
+    const [locked, setLocked] = useState(false)
+
+    const handleLocked = () => {
+      setLocked(!locked)
+    }
+
+    return (
+      <View
+        as="div"
+        padding="xx-large"
+        background="primary-inverse"
+        id="inverseToggleContainer"
+      >
+        <ToggleButton
+          status={locked ? 'pressed' : 'unpressed'}
+          color="primary-inverse"
+          renderIcon={locked ? LockInstUIIcon : UnlockInstUIIcon}
+          screenReaderLabel={locked ? 'Unlock assignment' : 'Lock assignment'}
+          renderTooltipContent={locked ? 'Unlock' : 'Lock'}
+          onClick={handleLocked}
+        />
+      </View>
+    )
+  }
+  render(<InverseExample />)
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="yes" title="Do">
+    <Figure.Item>Use for toggling a setting or status between one of two states</Figure.Item>
+    <Figure.Item>Use <code>color="primary-inverse"</code> on dark backgrounds so your icon and tooltip are visible</Figure.Item>
+  </Figure>
+  <Figure recommendation="no" title="Don't">
+    <Figure.Item>Use text inside a <code>ToggleButton</code></Figure.Item>
+  </Figure>
+</Guidelines>
+```