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

package/src/ProgressBar/v2/README.md

@@ -0,0 +1,384 @@
+---
+describes: ProgressBar
+---
+
+`<ProgressBar />` is a styled HTML `<progress />` element, complete
+with the aria attributes required to support screen readers.
+
+### `size`
+
+```js
+---
+type: example
+---
+<div>
+  <ProgressBar
+    size="x-small"
+    screenReaderLabel="Loading completion"
+    valueNow={40}
+    valueMax={60}
+    margin="0 0 small"
+    renderValue={({ valueNow, valueMax }) => {
+    return (
+      <span>
+        {Math.round(valueNow / valueMax * 100)}%
+      </span>
+    )
+  }}
+  formatScreenReaderValue={({ valueNow, valueMax }) => {
+    return Math.round((valueNow / valueMax * 100)) + ' percent'
+  }}
+  />
+  <ProgressBar
+    size="small"
+    screenReaderLabel="Loading completion"
+    valueNow={40}
+    valueMax={60}
+    margin="0 0 small"
+    renderValue={({ valueNow, valueMax }) => {
+    return (
+      <span>
+        {Math.round(valueNow / valueMax * 100)}%
+      </span>
+    )
+  }}
+  formatScreenReaderValue={({ valueNow, valueMax }) => {
+    return Math.round((valueNow / valueMax * 100)) + ' percent'
+  }}
+  />
+  <ProgressBar
+    screenReaderLabel="Loading completion"
+    valueNow={40}
+    valueMax={60}
+    margin="0 0 small"
+    renderValue={({ valueNow, valueMax }) => {
+    return (
+      <span>
+        {Math.round(valueNow / valueMax * 100)}%
+      </span>
+    )
+  }}
+  formatScreenReaderValue={({ valueNow, valueMax }) => {
+    return Math.round((valueNow / valueMax * 100)) + ' percent'
+  }}
+  />
+  <ProgressBar
+    size="large"
+    screenReaderLabel="Loading completion"
+    valueNow={40}
+    valueMax={60}
+    renderValue={({ valueNow, valueMax }) => {
+    return (
+      <span>
+        {Math.round(valueNow / valueMax * 100)}%
+      </span>
+    )
+  }}
+  formatScreenReaderValue={({ valueNow, valueMax }) => {
+    return Math.round((valueNow / valueMax * 100)) + ' percent'
+  }}
+  />
+</div>
+```
+
+### `color`
+
+`<ProgressBar />`'s `color` property controls the overall color scheme of the
+component. Set it to `primary-inverse` when the component is used on dark backgrounds.
+
+```js
+---
+type: example
+---
+<View background="primary-inverse" padding="medium" as="div">
+  <ProgressBar
+    screenReaderLabel="Loading completion"
+    color="primary-inverse"
+    valueNow={30}
+    valueMax={60}
+    renderValue={({ valueNow, valueMax }) => {
+    return (
+      <span>
+        {Math.round(valueNow / valueMax * 100)}%
+      </span>
+    )
+  }}
+  formatScreenReaderValue={({ valueNow, valueMax }) => {
+    return Math.round((valueNow / valueMax * 100)) + ' percent'
+  }}
+  />
+</View>
+```
+
+### `meterColor`
+
+The color of the progress meter is set separately through the `meterColor` property.
+
+```js
+---
+type: example
+---
+<div>
+  <ProgressBar
+    screenReaderLabel="Loading completion"
+    meterColor="info"
+    valueNow={40}
+    valueMax={60}
+    margin="0 0 small"
+    renderValue={({ valueNow, valueMax }) => {
+    return (
+      <span>
+        {Math.round(valueNow / valueMax * 100)}%
+      </span>
+    )
+  }}
+  formatScreenReaderValue={({ valueNow, valueMax }) => {
+    return Math.round((valueNow / valueMax * 100)) + ' percent'
+  }}
+  />
+  <ProgressBar
+    screenReaderLabel="Loading completion"
+    meterColor="success"
+    valueNow={40}
+    valueMax={60}
+    margin="0 0 small"
+    renderValue={({ valueNow, valueMax }) => {
+    return (
+      <span>
+        {Math.round(valueNow / valueMax * 100)}%
+      </span>
+    )
+  }}
+  formatScreenReaderValue={({ valueNow, valueMax }) => {
+    return Math.round((valueNow / valueMax * 100)) + ' percent'
+  }}
+  />
+  <ProgressBar
+    screenReaderLabel="Loading completion"
+    meterColor="alert"
+    valueNow={40}
+    valueMax={60}
+    margin="0 0 small"
+    renderValue={({ valueNow, valueMax }) => {
+    return (
+      <span>
+        {Math.round(valueNow / valueMax * 100)}%
+      </span>
+    )
+  }}
+  formatScreenReaderValue={({ valueNow, valueMax }) => {
+    return Math.round((valueNow / valueMax * 100)) + ' percent'
+  }}
+  />
+  <ProgressBar
+    screenReaderLabel="Loading completion"
+    meterColor="warning"
+    valueNow={40}
+    valueMax={60}
+    margin="0 0 small"
+    renderValue={({ valueNow, valueMax }) => {
+    return (
+      <span>
+        {Math.round(valueNow / valueMax * 100)}%
+      </span>
+    )
+  }}
+  formatScreenReaderValue={({ valueNow, valueMax }) => {
+    return Math.round((valueNow / valueMax * 100)) + ' percent'
+  }}
+  />
+  <ProgressBar
+    screenReaderLabel="Loading completion"
+    meterColor="danger"
+    valueNow={40}
+    valueMax={60}
+    margin="0 0 small"
+    renderValue={({ valueNow, valueMax }) => {
+    return (
+      <span>
+        {Math.round(valueNow / valueMax * 100)}%
+      </span>
+    )
+  }}
+  formatScreenReaderValue={({ valueNow, valueMax }) => {
+    return Math.round((valueNow / valueMax * 100)) + ' percent'
+  }}
+  />
+</div>
+```
+
+`meterColor` can also be passed in as a function that takes `valueNow / valueMax`
+as parameters. This allows you to adjust the color of the meter based on the
+current value.
+
+```js
+---
+type: example
+---
+<ProgressBar
+  screenReaderLabel="Loading completion"
+  meterColor={({ valueNow, valueMax }) => {
+    if (valueNow < 20) {
+      return 'danger'
+    } else if (valueNow / valueMax >= 1) {
+      return 'success'
+    } else {
+      return 'info'
+    }
+  }}
+  valueNow={10}
+  valueMax={60}
+  renderValue={({ valueNow, valueMax }) => {
+    return (
+      <span>
+        {Math.round(valueNow / valueMax * 100)}%
+      </span>
+    )
+  }}
+  formatScreenReaderValue={({ valueNow, valueMax }) => {
+    return Math.round((valueNow / valueMax * 100)) + ' percent'
+  }}
+/>
+```
+
+> `<ProgressBar />` defaults to setting the meter color to `success` when
+> complete.
+
+### `renderValue` / `formatScreenReaderValue`
+
+Via the `renderValue` prop, developers can use `valueMax` and `valueNow` props to format the
+value that `<ProgressBar />` displays.
+
+> `renderValue` will not be spoken by screen readers. Any essential information
+> in `renderValue` must also be conveyed via `formatScreenReaderValue` for screen reader users.
+
+```js
+---
+type: example
+---
+<ProgressBar
+  screenReaderLabel="Percent complete"
+  formatScreenReaderValue={({ valueNow, valueMax }) => {
+    return Math.round((valueNow / valueMax * 100)) + ' percent'
+  }}
+  renderValue={({ valueNow, valueMax }) => {
+    return (
+      <span>
+        {Math.round(valueNow / valueMax * 100)}%
+      </span>
+    )
+  }}
+  valueMax={88}
+  valueNow={33}
+/>
+```
+
+### `shouldAnimate`
+
+The `shouldAnimate` prop makes the progress bar animate the transition between value changes, giving it a smoother look.
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const MIN = 0
+  const MAX = 100
+
+  const [value, setValue] = useState(25)
+  const [shouldAnimate, setShouldAnimate] = useState(true)
+
+  const bound = (n) => {
+    if (n < MIN) return MIN
+    if (n > MAX) return MAX
+    return n
+  }
+
+  const handleChange = (event, value) => {
+    const newValue = Number(value)
+    if (isNaN(newValue)) {
+      return
+    }
+    setValue(newValue)
+  }
+
+  const handleDecrement = () => {
+    if (Number.isInteger(value)) {
+      setValue((value) => bound(value - 1))
+    }
+    setValue((value) => bound(Math.floor(value)))
+  }
+
+  const handleIncrement = () => {
+    if (Number.isInteger(value)) {
+      setValue((value) => bound(value + 1))
+    }
+    setValue((value) => bound(Math.ceil(value)))
+  }
+
+  const handleBlur = () => {
+    setValue((value) => bound(Math.round(value)))
+  }
+
+  return (
+    <div>
+      <View
+        as="div"
+        background="primary"
+        padding="medium"
+        margin="0 0 large 0"
+      >
+        <FormFieldGroup
+          description={<ScreenReaderContent>Settings</ScreenReaderContent>}
+        >
+          <Checkbox
+            label="Should animate"
+            checked={shouldAnimate}
+            onChange={() => {
+              setShouldAnimate((shouldAnimate) => !shouldAnimate)
+            }}
+            variant="toggle"
+          />
+
+          <NumberInput
+            renderLabel={`ProgressBar value (${MIN}-${MAX})`}
+            display="inline-block"
+            onBlur={handleBlur}
+            onChange={handleChange}
+            onDecrement={handleDecrement}
+            onIncrement={handleIncrement}
+            showArrows
+            value={value}
+          />
+        </FormFieldGroup>
+      </View>
+
+      <ProgressBar
+        screenReaderLabel="Loading completion"
+        valueNow={value}
+        valueMax={MAX}
+        shouldAnimate={shouldAnimate}
+        renderValue={({ valueNow, valueMax }) => {
+          return <span>{Math.round((valueNow / valueMax) * 100)}%</span>
+        }}
+        formatScreenReaderValue={({ valueNow, valueMax }) => {
+          return Math.round((valueNow / valueMax) * 100) + ' percent'
+        }}
+      />
+    </div>
+  )
+}
+
+render(<Example />)
+```
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="a11y" title="Accessibility">
+    <Figure.Item>If the progress bar conveys more information than just an approximate progress of a task (for example "5 or 23 items downloaded") then show this information as text too.</Figure.Item>
+  </Figure>
+</Guidelines>
+```

package/src/ProgressBar/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 { View } from '@instructure/ui-view/latest'
+import { callRenderProp, passthroughProps } from '@instructure/ui-react-utils'
+
+import { withStyle } from '@instructure/emotion'
+
+import generateStyle from './styles'
+
+import type { ProgressBarProps, Values } from './props'
+import { allowedProps } from './props'
+
+/**
+---
+category: components
+---
+**/
+@withStyle(generateStyle)
+class ProgressBar extends Component<ProgressBarProps> {
+  static readonly componentId = 'ProgressBar'
+
+  static allowedProps = allowedProps
+
+  static defaultProps = {
+    formatScreenReaderValue: ({ valueNow, valueMax }: Values) =>
+      `${valueNow} / ${valueMax}`,
+    size: 'medium',
+    valueMax: 100,
+    valueNow: 0,
+    as: 'div',
+    color: 'primary',
+    shouldAnimate: false,
+
+    // default to showing `success` color on completion
+    meterColor: ({ valueNow, valueMax }: Values) =>
+      valueNow / valueMax >= 1 ? 'success' : 'brand'
+  }
+
+  ref: Element | null = null
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+  }
+
+  handleRef = (el: Element | null) => {
+    const { elementRef } = this.props
+
+    this.ref = el
+
+    if (typeof elementRef === 'function') {
+      elementRef(el)
+    }
+  }
+
+  render() {
+    const {
+      renderValue,
+      formatScreenReaderValue,
+      valueNow,
+      valueMax,
+      screenReaderLabel,
+      size,
+      color,
+      meterColor,
+      renderValueInside,
+      styles,
+      ...props
+    } = this.props
+
+    const valueText =
+      typeof formatScreenReaderValue === 'function'
+        ? formatScreenReaderValue({ valueNow: valueNow!, valueMax: valueMax! })
+        : undefined
+
+    const value = callRenderProp(renderValue, {
+      valueNow: valueNow!,
+      valueMax: valueMax!
+    })
+
+    return (
+      <View
+        {...passthroughProps(props)}
+        as={this.props.as}
+        css={styles?.progressBar}
+        margin={this.props.margin}
+        elementRef={this.handleRef}
+        data-cid="ProgressBar"
+      >
+        <span css={styles?.trackLayout}>
+          <progress
+            css={styles?.htmlProgress}
+            max={valueMax}
+            value={valueNow}
+            aria-valuetext={valueText}
+            aria-label={screenReaderLabel}
+          />
+
+          <span css={styles?.track} role="presentation" aria-hidden="true">
+            <span css={styles?.trackValue}>{renderValueInside && value}</span>
+          </span>
+        </span>
+
+        {value && !renderValueInside && (
+          <span css={styles?.value} aria-hidden="true">
+            {value}
+          </span>
+        )}
+      </View>
+    )
+  }
+}
+
+export default ProgressBar
+export { ProgressBar }

package/src/ProgressBar/v2/props.ts

@@ -0,0 +1,155 @@
+/*
+ * 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 {
+  Spacing,
+  WithStyleProps,
+  ComponentStyle
+} from '@instructure/emotion'
+import type {
+  AsElementType,
+  ProgressBarTheme,
+  OtherHTMLAttributes
+} from '@instructure/shared-types'
+import { Renderable } from '@instructure/shared-types'
+
+export type ProgressBarMeterColor =
+  | 'info'
+  | 'warning'
+  | 'danger'
+  | 'alert'
+  | 'success'
+  | 'brand'
+
+export type Values = { valueNow: number; valueMax: number }
+
+type ProgressBarOwnProps = {
+  /**
+   * A label is required for accessibility
+   */
+  screenReaderLabel: string
+
+  /**
+   * Control the height of the progress bar
+   */
+  size?: 'x-small' | 'small' | 'medium' | 'large'
+
+  /**
+   * Maximum value (defaults to 100)
+   */
+  valueMax?: Values['valueMax']
+
+  /**
+   * Receives the progress of the event
+   */
+  valueNow?: Values['valueNow']
+
+  /**
+   * A function for formatting the text provided to screen readers via `aria-valuenow`
+   */
+  formatScreenReaderValue?: (values: Values) => string
+
+  /**
+   * A function to format the displayed value. If null the value will not display.
+   * Takes `valueNow` and `valueMax` as parameters.
+   */
+  renderValue?: Renderable<Values>
+
+  /**
+   * Controls the overall color scheme of the component
+   */
+  color?: 'primary' | 'primary-inverse'
+
+  /**
+   * Control the color of the progress meter. Defaults to showing theme success
+   * color on completion, based on `valueNow` and `valueMax`.
+   */
+  meterColor?:
+    | ((values: Values) => ProgressBarMeterColor)
+    | ProgressBarMeterColor
+
+  /**
+   * Whether the change of value should have a transition
+   */
+  shouldAnimate?: 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
+
+  /**
+   * Provides a reference to the component's root HTML element
+   */
+  elementRef?: (element: Element | null) => void
+
+  /**
+   * Set the element type of the component's root
+   */
+  as?: AsElementType
+
+  /**
+   * If true, displays the `renderValue` inside the progress meter for customization.
+   *
+   * Note: This should not be used in most cases. When enabled, ensure `renderValue` is styled for proper
+   * legibility and alignment across themes and sizes.
+   */
+  renderValueInside?: boolean
+}
+
+type PropKeys = keyof ProgressBarOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type ProgressBarProps = ProgressBarOwnProps &
+  WithStyleProps<ProgressBarTheme, ProgressBarStyle> &
+  OtherHTMLAttributes<ProgressBarOwnProps>
+
+type ProgressBarStyle = ComponentStyle<
+  | 'progressBar'
+  | 'trackLayout'
+  | 'track'
+  | 'trackValue'
+  | 'value'
+  | 'htmlProgress'
+>
+const allowedProps: AllowedPropKeys = [
+  'screenReaderLabel',
+  'size',
+  'valueMax',
+  'valueNow',
+  'formatScreenReaderValue',
+  'renderValue',
+  'color',
+  'meterColor',
+  'shouldAnimate',
+  'margin',
+  'elementRef',
+  'as'
+]
+
+export type { ProgressBarProps, ProgressBarStyle }
+export { allowedProps }