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

package/src/Alert/v2/README.md

@@ -0,0 +1,249 @@
+---
+describes: Alert
+---
+
+The Alert component can be used to notify the user. It supports several
+variants to provide context to the message.
+
+Alert can optionally render as a dismissible 'dialog' with a close button.
+
+The `margin` prop can be added to give
+space above or below the alert.
+
+```js
+---
+type: example
+---
+<div>
+  <Alert
+    variant="success"
+    renderCloseButtonLabel="Close"
+    margin="small"
+    transition="none"
+    variantScreenReaderLabel="Success, "
+  >
+    Sample success alert text. I will close w/o a transition out if you close me
+  </Alert>
+  <Alert
+    variant="info"
+    renderCloseButtonLabel="Close"
+    margin="small"
+    variantScreenReaderLabel="Information, "
+  >
+    Sample info text. I will fade out if you close me.
+  </Alert>
+  <Alert
+    variant="error"
+    renderCloseButtonLabel="Close"
+    margin="small"
+    variantScreenReaderLabel="Error, "
+  >
+    Sample error text that continues for a while
+    to demonstrate what happens when the content stretches over
+    several lines. It really does take a lot of prose to get the
+    text to wrap when you are on a high resolution screen.
+  </Alert>
+  <Alert
+    variant="warning"
+    margin="small"
+    variantScreenReaderLabel="Warning, "
+  >
+    Sample warning text. This alert is not dismissible and cannot be closed.
+  </Alert>
+</div>
+```
+
+The `timeout` prop can be used to automatically dismiss an alert after a time.
+
+```js
+---
+type: example
+---
+<Alert
+  variant="info"
+  margin="small"
+  timeout={5000}
+  variantScreenReaderLabel="Information, "
+>
+  Sample info text. I will fade out after 5 seconds
+</Alert>
+```
+
+Given a `liveRegion` property, Alerts will guarantee a screenreader will announce their text.
+Use `liveRegionPoliteness` to choose an `aria-live` politeness setting of either `polite`
+or `assertive` (default). Use `isLiveRegionAtomic` to choose an `aria-atomic` setting
+of either `true` or `false` (default).
+
+Due to a bug in some screen readers, the live region element should be static, either through
+server rendering or included in the static HTML file for the app. The Alert component will
+ensure that element has the correct ARIA attributes.
+
+For more information about live regions, see
+[this MDN article](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions).
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const [alerts, setAlerts] = useState([])
+  const [count, setcount] = useState(0)
+
+  const variants = ['info', 'success', 'warning', 'error']
+
+  const addAlert = () => {
+    const variant = variants[count % variants.length]
+    const politeness = Math.random() < 0.5 ? 'polite' : 'assertive'
+    setAlerts([
+      ...alerts,
+      {
+        key: count,
+        variant,
+        politeness
+      }
+    ])
+    setcount(count + 1)
+  }
+
+  const closeAlert = (key) =>
+    setAlerts(alerts.filter((alert) => alert.key !== key))
+
+  return (
+    <div>
+      <Button onClick={addAlert}>Add Alert</Button>
+      {alerts.map((alert) => {
+        return (
+          <View key={alert.key} display="block" margin="small 0">
+            <Alert
+              variant={alert.variant}
+              renderCloseButtonLabel="Close"
+              onDismiss={() => closeAlert(alert.key)}
+              liveRegion={() => document.getElementById('flash-messages')}
+              liveRegionPoliteness={alert.politeness}
+              margin="small 0"
+            >
+              This is {alert.politeness === 'polite' ? 'a' : 'an'}{' '}
+              {alert.politeness} {alert.variant} alert
+            </Alert>
+          </View>
+        )
+      })}
+    </div>
+  )
+}
+
+render(<Example />)
+```
+
+Alerts can be used to emit screenreader only messages too
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const [message, setMessage] = useState(null)
+  const [count, setCount] = useState(1)
+
+  const changeMessage = () => {
+    setMessage(`this is message ${count}`)
+    setCount(count + 1)
+  }
+
+  const clearMessage = () => {
+    setMessage(null)
+    setCount(count + 1)
+  }
+
+  return (
+    <div>
+      <Button onClick={changeMessage}>Change Message</Button>
+      <Button onClick={clearMessage} margin="0 0 0 small">
+        Clear Message
+      </Button>
+      <Alert
+        liveRegion={() => document.getElementById('flash-messages')}
+        isLiveRegionAtomic
+        screenReaderOnly
+      >
+        {message}
+      </Alert>
+    </div>
+  )
+}
+
+render(<Example />)
+```
+
+When Alerts are used inline, the shadow can be removed with the `hasShadow` property.
+
+```js
+---
+type: example
+---
+<View as="div" background="primary" padding="large">
+  <View
+    as="div"
+    background="primary"
+    padding="small medium"
+    borderWidth="small"
+    borderRadius="small"
+    margin="x-small 0"
+  >
+    {lorem.paragraph()}
+  </View>
+  <Alert
+    variant="info"
+    margin="x-small 0"
+    renderCloseButtonLabel="Close"
+    hasShadow={false}
+  >
+    This is an inline Alert, so it shouldn't have a shadow.
+  </Alert>
+  <View
+    as="div"
+    background="primary"
+    padding="small medium"
+    borderWidth="small"
+    borderRadius="small"
+    margin="x-small 0"
+  >
+    {lorem.paragraph()}
+  </View>
+</View>
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="yes" title="Do">
+    <Figure.Item>Use the Info alert to notify the user of more information</Figure.Item>
+    <Figure.Item>Use the Error alert to notify user of an error</Figure.Item>
+    <Figure.Item>Use the Warning alert to notify user of a warning</Figure.Item>
+    <Figure.Item>Use the Success alert to notify user of a success event or action</Figure.Item>
+    <Figure.Item>Use the `variantScreenReaderLabel` prop to indicate the alert variant to screen reader users</Figure.Item>
+  </Figure>
+  <Figure recommendation="no" title="Don't">
+    <Figure.Item>Have alert messaging that is more than two lines long</Figure.Item>
+    <Figure.Item>Overuse alerts on the same page</Figure.Item>
+  </Figure>
+</Guidelines>
+```
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="a11y" title="Accessibility">
+    <Figure.Item>If the alert requires user interaction to be dismissed, the alert should behave as a modal dialog. Focus should be set to the alert when it appears, remain in the alert until it is dismissed, and return to a logical place on the page when the alert is dismissed</Figure.Item>
+    <Figure.Item>aria-live="polite" alerts will only be announced if the user is not currently doing anything. Polite should be used in most situations involving live regions that present new info to users</Figure.Item>
+    <Figure.Item>aria-live="assertive" alerts will be announced to the user as soon as possible, but not necessarily immediately. Assertive should be used if there is information that a user must know about right away, for example, a warning message in a form that does validation on the fly</Figure.Item>
+    <Figure.Item>The aria-atomic=BOOLEAN is used to set whether or not the screen reader should always present the live region as a whole, even if only part of the region changes. The possible settings are: false or true. The default setting is false.</Figure.Item>
+  </Figure>
+</Guidelines>
+```

package/src/Alert/v2/index.tsx

@@ -0,0 +1,349 @@
+/*
+ * 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 { Fragment, Component } from 'react'
+import ReactDOM from 'react-dom'
+import keycode from 'keycode'
+
+import {
+  callRenderProp,
+  withDeterministicId,
+  passthroughProps
+} from '@instructure/ui-react-utils'
+import { CloseButton } from '@instructure/ui-buttons/latest'
+import { View } from '@instructure/ui-view/latest'
+import type { ViewOwnProps } from '@instructure/ui-view/latest'
+import { ScreenReaderContent } from '@instructure/ui-a11y-content'
+import {
+  InfoInstUIIcon,
+  XCircleInstUIIcon,
+  CircleCheckInstUIIcon,
+  TriangleAlertInstUIIcon
+} from '@instructure/ui-icons'
+import { Transition } from '@instructure/ui-motion'
+import { logError as error } from '@instructure/console'
+import { withStyle } from '@instructure/emotion'
+
+import generateStyle from './styles'
+
+import { allowedProps } from './props'
+import type { AlertProps, AlertState } from './props'
+
+/**
+---
+category: components
+---
+**/
+@withDeterministicId()
+@withStyle(generateStyle)
+class Alert extends Component<AlertProps, AlertState> {
+  static readonly componentId = 'Alert'
+
+  static allowedProps = allowedProps
+  static defaultProps = {
+    variant: 'info',
+    margin: 'x-small 0',
+    timeout: 0,
+    transition: 'fade',
+    open: true,
+    screenReaderOnly: false,
+    liveRegionPoliteness: 'assertive',
+    isLiveRegionAtomic: false,
+    children: null,
+    hasShadow: true
+  }
+
+  constructor(props: AlertProps) {
+    super(props)
+
+    this.srid = this.props.deterministicId!()
+    this.state = {
+      open: true
+    }
+  }
+
+  _timeouts: ReturnType<typeof setTimeout>[] = []
+  srid: string
+
+  variantUI = {
+    error: XCircleInstUIIcon,
+    info: InfoInstUIIcon,
+    success: CircleCheckInstUIIcon,
+    warning: TriangleAlertInstUIIcon
+  }
+
+  ref: Element | null = null
+
+  handleRef = (el: Element | null) => {
+    this.ref = el
+  }
+
+  handleTimeout = () => {
+    if (this.props.timeout! > 0) {
+      this._timeouts.push(
+        setTimeout(() => {
+          this.close()
+        }, this.props.timeout)
+      )
+    }
+  }
+
+  clearTimeouts() {
+    this._timeouts.forEach((timeout) => clearTimeout(timeout))
+    this._timeouts = []
+  }
+
+  onExitTransition = () => {
+    if (this.props.onDismiss) {
+      this.props.onDismiss()
+    }
+  }
+
+  close = () => {
+    this.clearTimeouts()
+    this.removeScreenreaderAlert()
+    this.setState({ open: false }, () => {
+      if (
+        this.props.onDismiss &&
+        (this.props.transition === 'none' || this.props.screenReaderOnly)
+      ) {
+        this.props.onDismiss()
+      }
+    })
+  }
+
+  // duck type for a dom node
+  isDOMNode(n: Element | null | undefined) {
+    return n && typeof n === 'object' && n.nodeType === 1
+  }
+
+  getLiveRegion() {
+    const lr =
+      typeof this.props.liveRegion === 'function'
+        ? this.props.liveRegion()
+        : this.props.liveRegion
+
+    return this.isDOMNode(lr) ? lr : null
+  }
+
+  initLiveRegion(liveRegion: Element) {
+    error(
+      liveRegion.getAttribute('role') === 'alert',
+      `[Alert] live region must have role='alert' set on page load in order to announce content`
+    )
+
+    if (liveRegion) {
+      liveRegion.setAttribute('aria-live', this.props.liveRegionPoliteness!)
+      // indicates what notifications the user agent will trigger when the
+      // accessibility tree within a live region is modified.
+      // additions: elements are added, text: Text content is added
+      liveRegion.setAttribute('aria-relevant', 'additions text')
+      liveRegion.setAttribute(
+        'aria-atomic',
+        `${this.props.isLiveRegionAtomic!}`
+      )
+    }
+  }
+
+  createScreenreaderContentNode() {
+    return (
+      <ScreenReaderContent>
+        {this.props.variantScreenReaderLabel || ''} {this.props.children}
+      </ScreenReaderContent>
+    )
+  }
+
+  createScreenreaderAlert() {
+    const liveRegion = this.getLiveRegion()
+    if (liveRegion) {
+      const div = document.createElement('div')
+      div.setAttribute('id', this.srid)
+
+      liveRegion.appendChild(div)
+    }
+  }
+
+  removeScreenreaderAlert() {
+    const liveRegion = this.getLiveRegion()
+    if (liveRegion) {
+      const div = document.getElementById(this.srid!)
+      if (div) {
+        // Accessibility attributes must be removed for the deletion of the node
+        // and then reapplied because JAWS/IE will not respect the
+        // "aria-relevant" attribute and read when the node is deleted if
+        // the attributes are in place
+        liveRegion.removeAttribute('aria-live')
+        liveRegion.removeAttribute('aria-relevant')
+        liveRegion.removeAttribute('aria-atomic')
+
+        this.initLiveRegion(liveRegion)
+      }
+    }
+  }
+
+  handleKeyUp = (event: React.KeyboardEvent<ViewOwnProps>) => {
+    if (
+      this.props.renderCloseButtonLabel &&
+      event.keyCode === keycode.codes.esc
+    ) {
+      this.close()
+    }
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+    const liveRegion = this.getLiveRegion()
+    if (liveRegion) {
+      this.initLiveRegion(liveRegion)
+    }
+
+    this.handleTimeout()
+  }
+
+  componentWillUnmount() {
+    this.clearTimeouts()
+  }
+
+  componentDidUpdate(prevProps: AlertProps) {
+    this.props.makeStyles?.()
+    if (!!this.props.open === false && !!this.props.open !== !!prevProps.open) {
+      // this outside world is asking us to close the alert, which needs to
+      // take place internally so the transition runs
+      this.close()
+    }
+  }
+
+  renderIcon() {
+    const { renderCustomIcon, variant, styles } = this.props
+    const Icon = this.variantUI[variant!]
+    return (
+      <div css={styles?.icon}>
+        {renderCustomIcon ? callRenderProp(renderCustomIcon) : <Icon />}
+      </div>
+    )
+  }
+
+  renderCloseButton() {
+    const closeButtonLabel =
+      this.props.renderCloseButtonLabel &&
+      callRenderProp(this.props.renderCloseButtonLabel)
+
+    return closeButtonLabel ? (
+      <div css={this.props.styles?.closeButton} key="closeButton">
+        <CloseButton
+          onClick={this.close}
+          size="small"
+          screenReaderLabel={closeButtonLabel}
+        />
+      </div>
+    ) : null
+  }
+
+  renderAlert() {
+    // prevent onDismiss from being passed to the View component
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const {
+      margin,
+      styles,
+      children,
+      onDismiss,
+      variantScreenReaderLabel,
+      ...props
+    } = this.props
+    return (
+      <View
+        {...passthroughProps({ ...props })}
+        as="div"
+        margin={margin}
+        css={styles?.alert}
+        onKeyUp={this.handleKeyUp}
+        elementRef={this.handleRef}
+      >
+        {this.renderIcon()}
+        <div css={styles?.content}>
+          {variantScreenReaderLabel && (
+            <span css={styles?.variantScreenReaderLabel}>
+              {variantScreenReaderLabel}
+            </span>
+          )}
+          {children}
+        </div>
+        {this.renderCloseButton()}
+      </View>
+    )
+  }
+
+  createScreenReaderPortal(liveRegion: Element) {
+    const { open } = this.state
+
+    return open
+      ? ReactDOM.createPortal(
+          <div id={this.srid}>{this.createScreenreaderContentNode()}</div>,
+          liveRegion
+        )
+      : null
+  }
+
+  render() {
+    const liveRegion = this.getLiveRegion()
+    const screenReaderContent = liveRegion
+      ? this.createScreenReaderPortal(liveRegion)
+      : null
+    // Don't render anything if screen reader only
+    if (this.props.screenReaderOnly) {
+      error(
+        !!this.getLiveRegion(),
+        `[Alert] The 'screenReaderOnly' prop must be used in conjunction with 'liveRegion'.`
+      )
+
+      return screenReaderContent
+    }
+
+    if (this.props.transition === 'none') {
+      return this.state.open ? (
+        <Fragment>
+          {screenReaderContent}
+          {this.renderAlert()}
+        </Fragment>
+      ) : null
+    }
+    return (
+      <Fragment>
+        {screenReaderContent}
+        <Transition
+          type={this.props.transition}
+          transitionOnMount
+          in={this.state.open}
+          unmountOnExit
+          onExited={this.onExitTransition}
+        >
+          {this.renderAlert()}
+        </Transition>
+      </Fragment>
+    )
+  }
+}
+
+export default Alert
+export { Alert }