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

package/src/ProgressBar/v2/styles.ts

@@ -0,0 +1,221 @@
+/*
+ * 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 { ProgressBarProps, ProgressBarStyle } 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 Shared token object that stores common values for the theme.
+ * @return {Object} The final style object, which will be used in the component
+ */
+const generateStyle = (
+  componentTheme: NewComponentTypes['ProgressBar'],
+  props: ProgressBarProps,
+  _sharedTokens: SharedTokens
+): ProgressBarStyle => {
+  const {
+    valueNow = 0,
+    valueMax = 100,
+    size,
+    color,
+    meterColor,
+    shouldAnimate
+  } = props
+
+  const meterColorClassName =
+    typeof meterColor === 'function'
+      ? meterColor({ valueNow, valueMax })
+      : meterColor
+
+  const currentValue =
+    valueNow > valueMax ? valueMax : valueNow < 0 ? 0 : valueNow
+
+  const currentValuePercent = `${(currentValue / valueMax) * 100}%`
+
+  const sizeVariants = {
+    'x-small': {
+      track: { height: componentTheme.xSmallHeight },
+      value: { fontSize: componentTheme.xSmallValueFontSize }
+    },
+    small: {
+      track: { height: componentTheme.smallHeight }, // product design wants = 18px
+      value: { fontSize: componentTheme.smallValueFontSize }
+    },
+    medium: {
+      track: { height: componentTheme.mediumHeight },
+      value: { fontSize: componentTheme.mediumValueFontSize }
+    },
+    large: {
+      track: { height: componentTheme.largeHeight },
+      value: { fontSize: componentTheme.largeValueFontSize }
+    }
+  }
+
+  const colorVariants = {
+    primary: {
+      trackLayout: {
+        background: componentTheme.trackColor,
+        borderWidth: componentTheme.trackBottomBorderWidth,
+        borderStyle: 'solid',
+        borderColor: componentTheme.borderColor
+      },
+      trackBorder: {
+        borderBottomColor: componentTheme.trackBottomBorderColor
+      },
+      value: {
+        color: componentTheme.textColor
+      },
+      htmlProgress: {
+        borderColor: componentTheme.borderColor
+      }
+    },
+    'primary-inverse': {
+      trackLayout: {
+        background: componentTheme.trackColorInverse,
+        borderWidth: componentTheme.trackBottomBorderWidth,
+        borderStyle: 'solid',
+        borderColor: componentTheme.borderColorInverse
+      },
+      trackBorder: {
+        borderBottomColor: componentTheme.trackBottomBorderColorInverse
+      },
+      value: {
+        color: componentTheme.textColorInverse
+      },
+      htmlProgress: {
+        borderColor: componentTheme.borderColorInverse
+      }
+    }
+  }
+
+  const trackBackgroundVariants = {
+    primary: {
+      brand: { background: componentTheme.meterColorBrand },
+      info: { background: componentTheme.meterColorInfo },
+      success: { background: componentTheme.meterColorSuccess },
+      danger: { background: componentTheme.meterColorDanger },
+      warning: { background: componentTheme.meterColorWarning },
+      alert: { background: componentTheme.meterColorAlert }
+    },
+    'primary-inverse': {
+      brand: { background: componentTheme.meterColorBrandInverse },
+      info: { background: componentTheme.meterColorInfoInverse },
+      success: { background: componentTheme.meterColorSuccessInverse },
+      danger: { background: componentTheme.meterColorDangerInverse },
+      warning: { background: componentTheme.meterColorWarningInverse },
+      alert: { background: componentTheme.meterColorAlertInverse }
+    }
+  }
+
+  return {
+    progressBar: {
+      label: 'progressBar',
+      display: 'flex',
+      alignItems: 'center',
+      fontFamily: componentTheme.fontFamily,
+      fontWeight: componentTheme.fontWeight,
+      lineHeight: componentTheme.lineHeight,
+      fontSize: componentTheme.fontSize,
+      borderRadius: componentTheme.borderRadius
+    },
+
+    trackLayout: {
+      label: 'progressBar__trackLayout',
+      position: 'relative',
+      flex: 1,
+      borderRadius: 'inherit',
+
+      ...colorVariants[color!].trackLayout
+    },
+
+    track: {
+      label: 'progressBar__track',
+      display: 'block',
+      boxSizing: 'border-box',
+      width: '100%',
+      borderBottomWidth: componentTheme.trackBottomBorderWidth,
+      borderBottomStyle: 'solid',
+      background: 'transparent',
+      // Inner border-radius must be smaller than outer to avoid geometric gaps with nested rounded borders
+      // Formula: inner radius = outer radius - border width
+      borderTopLeftRadius: `calc(${componentTheme.borderRadius} - ${componentTheme.trackBottomBorderWidth})`,
+      borderBottomLeftRadius: `calc(${componentTheme.borderRadius} - ${componentTheme.trackBottomBorderWidth})`,
+      // Negative margin pulls track down so trackLayout's full border overlaps and hides track's bottom border.
+      // When trackLayout border is visible (light/dark themes), it creates a clean full border appearance.
+      // When trackLayout border is transparent (legacy Canvas), track's bottom border remains visible.
+      marginBottom: `calc(-1 * ${componentTheme.trackBottomBorderWidth})`,
+
+      ...sizeVariants[size!].track,
+      ...colorVariants[color!].trackBorder
+    },
+
+    trackValue: {
+      label: 'progressBar__trackValue',
+      display: 'block',
+      boxSizing: 'border-box',
+      height: '100%',
+      width: currentValuePercent,
+      maxWidth: '100%',
+      borderRadius: 'inherit',
+
+      ...(shouldAnimate && { transition: 'all 0.5s' }),
+      ...(meterColorClassName &&
+        trackBackgroundVariants[color!][meterColorClassName])
+    },
+
+    value: {
+      label: 'progressBar__value',
+      lineHeight: 1,
+      boxSizing: 'border-box',
+      paddingInlineStart: componentTheme.valuePadding,
+      flex: '0 0 5.625rem',
+
+      ...sizeVariants[size!].value,
+      ...colorVariants[color!].value
+    },
+
+    htmlProgress: {
+      label: 'progressBar__htmlProgress',
+      display: 'block',
+      position: 'absolute',
+      top: '0',
+      left: '0',
+      width: '100%',
+      height: '100%',
+      boxSizing: 'border-box',
+      zIndex: -1,
+      opacity: 0,
+
+      ...colorVariants[color!].htmlProgress
+    }
+  }
+}
+
+export default generateStyle

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

@@ -25,10 +25,10 @@
 import { Component } from 'react'
 
 import { ScreenReaderContent } from '@instructure/ui-a11y-content'
-import { View } from '@instructure/ui-view'
+import { View } from '@instructure/ui-view/v11_6'
 import { callRenderProp, passthroughProps } from '@instructure/ui-react-utils'
 
-import { withStyle } from '@instructure/emotion'
+import { withStyleLegacy as withStyle } from '@instructure/emotion'
 
 import generateStyle from './styles'
 import generateComponentTheme from './theme'

package/src/ProgressCircle/v2/README.md

@@ -0,0 +1,219 @@
+---
+describes: ProgressCircle
+---
+
+`<ProgressCircle />` is a 🍩 styled HTML `<progress />` element, complete
+with the aria attributes required to support screen readers.
+
+### `size`, `shouldAnimateOnMount`, `animationDelay`
+
+```js
+---
+type: example
+---
+<div>
+  <ProgressCircle
+    size="x-small"
+    screenReaderLabel="Loading completion"
+    valueNow={40}
+    valueMax={60}
+    margin="0 small 0 0"
+    shouldAnimateOnMount
+  />
+  <ProgressCircle
+    size="small"
+    screenReaderLabel="Loading completion"
+    valueNow={40}
+    valueMax={60}
+    margin="0 small 0 0"
+    shouldAnimateOnMount
+    animationDelay={2000}
+  />
+  <ProgressCircle
+    screenReaderLabel="Loading completion"
+    valueNow={40}
+    valueMax={60}
+    margin="0 small 0 0"
+    shouldAnimateOnMount
+    animationDelay={4000}
+    formatScreenReaderValue={function ({ valueNow, valueMax }) {
+      return valueNow + ' out of ' + valueMax
+    }}
+    renderValue={function ({ valueNow, valueMax }) {
+      return (
+        <span>
+          <Text size="large" weight="bold">{valueNow}</Text>
+          <br />
+          <Text size="small">/&nbsp;</Text>
+          <Text size="small">{valueMax}</Text>
+        </span>
+      )
+    }}
+  />
+  <ProgressCircle
+    size="large"
+    screenReaderLabel="Loading completion"
+    valueNow={40}
+    valueMax={60}
+    shouldAnimateOnMount
+    animationDelay={6000}
+    formatScreenReaderValue={function ({ valueNow, valueMax }) {
+      const passing = valueNow > (valueMax / 2) ? 'pass' : 'fail'
+      return `${valueNow} of ${valueMax}: ${passing}`
+    }}
+    renderValue={function ({ valueNow, valueMax }) {
+      if (valueNow > (valueMax / 2)) {
+        return (
+          <Text weight="bold" size="large">
+            PASS
+          </Text>
+        )
+      } else {
+        return (
+        <Text weight="bold" size="large">
+          FAIL
+        </Text>
+        )
+      }
+    }}
+  />
+</div>
+```
+
+### `color`
+
+`<ProgressCircle />`'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" as="div">
+  <ProgressCircle
+    screenReaderLabel="Loading completion"
+    color="primary-inverse"
+    valueNow={50}
+    valueMax={60}
+  />
+</View>
+```
+
+### `meterColor`
+
+The color of the progress meter is set separately through the `meterColor` property.
+
+```js
+---
+type: example
+---
+<div>
+  <ProgressCircle
+    screenReaderLabel="Loading completion"
+    meterColor="info"
+    valueNow={40}
+    valueMax={60}
+    margin="0 0 small"
+  />
+  <ProgressCircle
+    screenReaderLabel="Loading completion"
+    meterColor="success"
+    valueNow={40}
+    valueMax={60}
+    margin="0 0 small"
+  />
+  <ProgressCircle
+    screenReaderLabel="Loading completion"
+    meterColor="alert"
+    valueNow={40}
+    valueMax={60}
+    margin="0 0 small"
+  />
+  <ProgressCircle
+    screenReaderLabel="Loading completion"
+    meterColor="warning"
+    valueNow={40}
+    valueMax={60}
+    margin="0 0 small"
+  />
+  <ProgressCircle
+    screenReaderLabel="Loading completion"
+    meterColor="danger"
+    valueNow={40}
+    valueMax={60}
+    margin="0 0 small"
+  />
+</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
+---
+<ProgressCircle
+  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}
+/>
+```
+
+> `<ProgressCircle />` 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 `<ProgressCircle />` 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
+---
+<ProgressCircle
+  screenReaderLabel="Percent complete"
+  formatScreenReaderValue={({ valueNow, valueMax }) => {
+    return Math.round((valueNow / valueMax * 100)) + ' percent'
+  }}
+  renderValue={({ valueNow, valueMax }) => {
+    const percent = Math.round(valueNow / valueMax * 100)
+    return (
+      <span>
+        <Text size="large" weight="bold" color="primary">
+          {percent > 100 ? 100 : percent}
+        </Text>
+        <Text size="small" weight="bold" color="secondary">%</Text>
+      </span>
+    )
+  }}
+  valueMax={88}
+  valueNow={33}
+/>
+```
+
+```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/ProgressCircle/v2/index.tsx

@@ -0,0 +1,196 @@
+/*
+ * 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 { ScreenReaderContent } from '@instructure/ui-a11y-content'
+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 { ProgressCircleProps, ProgressCircleState, Values } from './props'
+import { allowedProps } from './props'
+
+/**
+---
+category: components
+---
+**/
+@withStyle(generateStyle)
+class ProgressCircle extends Component<
+  ProgressCircleProps,
+  ProgressCircleState
+> {
+  static readonly componentId = 'ProgressCircle'
+
+  static allowedProps = allowedProps
+
+  static defaultProps = {
+    formatScreenReaderValue: ({ valueNow, valueMax }: Values) =>
+      `${valueNow} / ${valueMax}`,
+    size: 'medium',
+    valueMax: 100,
+    valueNow: 0,
+    as: 'div',
+    color: 'primary',
+    shouldAnimateOnMount: false,
+
+    // default to showing `success` color on completion
+    meterColor: ({ valueNow, valueMax }: Values) =>
+      valueNow / valueMax >= 1 ? 'success' : 'brand'
+  }
+
+  _timeouts: Array<ReturnType<typeof setTimeout>> = []
+  ref: Element | null = null
+
+  constructor(props: ProgressCircleProps) {
+    super(props)
+
+    this.state = {
+      shouldAnimateOnMount: props.shouldAnimateOnMount!
+    }
+  }
+
+  handleRef = (el: Element | null) => {
+    const { elementRef } = this.props
+
+    this.ref = el
+
+    if (typeof elementRef === 'function') {
+      elementRef(el)
+    }
+  }
+
+  get makeStylesVariables() {
+    return { shouldAnimateOnMount: this.state.shouldAnimateOnMount }
+  }
+
+  componentDidMount() {
+    if (this.state.shouldAnimateOnMount) {
+      this._timeouts.push(
+        setTimeout(() => {
+          this.setState({
+            shouldAnimateOnMount: false
+          })
+        }, this.props.animationDelay || 500)
+      )
+    }
+
+    this.props.makeStyles?.(this.makeStylesVariables)
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.(this.makeStylesVariables)
+  }
+
+  componentWillUnmount() {
+    this._timeouts.forEach((timeout) => clearTimeout(timeout))
+  }
+
+  render() {
+    const {
+      color,
+      renderValue,
+      formatScreenReaderValue,
+      meterColor,
+      valueNow,
+      valueMax,
+      screenReaderLabel,
+      size,
+      styles,
+      ...props
+    } = this.props
+
+    const valueText =
+      typeof formatScreenReaderValue === 'function'
+        ? formatScreenReaderValue({ valueNow: valueNow!, valueMax: valueMax! })
+        : undefined
+    // consolidating the label and aria-valuetext to put in aria-label because
+    // NVDA does not read aria-valuetext: https://github.com/nvaccess/nvda/issues/913
+    // But leaving aria-valuetext because JAWS ignores aria-label
+    const labelAndValueText = `${screenReaderLabel} ${valueText}`
+
+    const value = callRenderProp(renderValue, {
+      valueNow: valueNow!,
+      valueMax: valueMax!
+    })
+
+    const style = {
+      strokeDashoffset: `${styles?.dashOffset}em`
+    }
+
+    return (
+      <View
+        {...passthroughProps(props)}
+        as={this.props.as}
+        elementRef={this.handleRef}
+        css={styles?.progressCircle}
+        margin={this.props.margin}
+        data-cid="ProgressCircle"
+      >
+        <ScreenReaderContent>
+          <progress
+            max={valueMax}
+            value={valueNow}
+            aria-valuetext={labelAndValueText}
+          />
+        </ScreenReaderContent>
+        {value && (
+          <span css={styles?.center} aria-hidden="true">
+            <span css={styles?.value}>{value}</span>
+          </span>
+        )}
+        <svg css={styles?.circle} role="presentation" focusable="false">
+          <circle
+            css={styles?.track}
+            role="presentation"
+            cx="50%"
+            cy="50%"
+            r={styles?.radii?.radius}
+          />
+          <circle
+            css={styles?.border}
+            role="presentation"
+            cx="50%"
+            cy="50%"
+            r={styles?.radii?.borderOffsetRadius}
+          />
+          <circle
+            css={styles?.meter}
+            role="presentation"
+            style={style}
+            cx="50%"
+            cy="50%"
+            r={styles?.radii?.radius}
+          />
+        </svg>
+      </View>
+    )
+  }
+}
+
+export default ProgressCircle
+export { ProgressCircle }