@instructure/ui-alerts 10.18.0 → 10.18.1-snapshot-1

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [10.18.1-snapshot-1](https://github.com/instructure/instructure-ui/compare/v10.18.0...v10.18.1-snapshot-1) (2025-05-28)
+
+
+### Bug Fixes
+
+* **ui-alerts:** add variantScreenReaderLabel prop to Alert to improve screenreader usability ([814a0ea](https://github.com/instructure/instructure-ui/commit/814a0eaebc0cededff575a8ea0cd05f8ec27b6de))
+
+
+
+
+
 # [10.18.0](https://github.com/instructure/instructure-ui/compare/v10.17.0...v10.18.0) (2025-05-26)
 
 

package/es/Alert/index.js

@@ -1,5 +1,5 @@
 import _objectWithoutProperties from "@babel/runtime/helpers/esm/objectWithoutProperties";
-const _excluded = ["margin", "styles", "children", "onDismiss"];
+const _excluded = ["margin", "styles", "children", "onDismiss", "variantScreenReaderLabel"];
 var _dec, _dec2, _class, _Alert;
 /*
  * The MIT License (MIT)
@@ -39,7 +39,7 @@ import { withStyle } from '@instructure/emotion';
 import generateStyle from './styles';
 import generateComponentTheme from './theme';
 import { propTypes, allowedProps } from './props';
-import { jsx as _jsx, jsxs as _jsxs } from "@emotion/react/jsx-runtime";
+import { jsxs as _jsxs, jsx as _jsx } from "@emotion/react/jsx-runtime";
 /**
 ---
 category: components
@@ -120,8 +120,8 @@ let Alert = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle, gene
     }
   }
   createScreenreaderContentNode() {
-    return _jsx(ScreenReaderContent, {
-      children: this.props.children
+    return _jsxs(ScreenReaderContent, {
+      children: [this.props.variantScreenReaderLabel || '', " ", this.props.children]
     });
   }
   createScreenreaderAlert() {
@@ -197,6 +197,7 @@ let Alert = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle, gene
       styles = _this$props3.styles,
       children = _this$props3.children,
       onDismiss = _this$props3.onDismiss,
+      variantScreenReaderLabel = _this$props3.variantScreenReaderLabel,
       props = _objectWithoutProperties(_this$props3, _excluded);
     return _jsxs(View, {
       ...passthroughProps({
@@ -207,9 +208,12 @@ let Alert = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle, gene
       css: styles === null || styles === void 0 ? void 0 : styles.alert,
       onKeyUp: this.handleKeyUp,
       elementRef: this.handleRef,
-      children: [this.renderIcon(), _jsx("div", {
+      children: [this.renderIcon(), _jsxs("div", {
         css: styles === null || styles === void 0 ? void 0 : styles.content,
-        children: children
+        children: [variantScreenReaderLabel && _jsx("span", {
+          css: styles === null || styles === void 0 ? void 0 : styles.variantScreenReaderLabel,
+          children: variantScreenReaderLabel
+        }), children]
       }), this.renderCloseButton()]
     });
   }

package/es/Alert/props.js

@@ -36,7 +36,8 @@ const propTypes = {
   onDismiss: PropTypes.func,
   transition: PropTypes.oneOf(['none', 'fade']),
   open: PropTypes.bool,
-  hasShadow: PropTypes.bool
+  hasShadow: PropTypes.bool,
+  variantScreenReaderLabel: PropTypes.string
 };
 const allowedProps = ['children', 'variant', 'margin', 'liveRegion', 'liveRegionPoliteness', 'isLiveRegionAtomic', 'screenReaderOnly', 'timeout', 'renderCloseButtonLabel', 'onDismiss', 'transition', 'open', 'hasShadow'];
 export { propTypes, allowedProps };

package/es/Alert/styles.js

@@ -117,6 +117,13 @@ const generateStyle = (componentTheme, props) => {
       fontWeight: componentTheme.contentFontWeight,
       lineHeight: componentTheme.contentLineHeight,
       padding: componentTheme.contentPadding
+    },
+    variantScreenReaderLabel: {
+      position: 'absolute',
+      height: '1px',
+      width: '1px',
+      overflow: 'hidden',
+      margin: '-1px'
     }
   };
 };

package/lib/Alert/index.js

@@ -26,7 +26,7 @@ var _styles = _interopRequireDefault(require("./styles"));
 var _theme = _interopRequireDefault(require("./theme"));
 var _props = require("./props");
 var _jsxRuntime = require("@emotion/react/jsx-runtime");
-const _excluded = ["margin", "styles", "children", "onDismiss"];
+const _excluded = ["margin", "styles", "children", "onDismiss", "variantScreenReaderLabel"];
 var _dec, _dec2, _class, _Alert;
 /*
  * The MIT License (MIT)
@@ -131,8 +131,8 @@ let Alert = exports.Alert = (_dec = (0, _withDeterministicId.withDeterministicId
     }
   }
   createScreenreaderContentNode() {
-    return (0, _jsxRuntime.jsx)(_ScreenReaderContent.ScreenReaderContent, {
-      children: this.props.children
+    return (0, _jsxRuntime.jsxs)(_ScreenReaderContent.ScreenReaderContent, {
+      children: [this.props.variantScreenReaderLabel || '', " ", this.props.children]
     });
   }
   createScreenreaderAlert() {
@@ -208,6 +208,7 @@ let Alert = exports.Alert = (_dec = (0, _withDeterministicId.withDeterministicId
       styles = _this$props3.styles,
       children = _this$props3.children,
       onDismiss = _this$props3.onDismiss,
+      variantScreenReaderLabel = _this$props3.variantScreenReaderLabel,
       props = (0, _objectWithoutProperties2.default)(_this$props3, _excluded);
     return (0, _jsxRuntime.jsxs)(_View.View, {
       ...(0, _passthroughProps.passthroughProps)({
@@ -218,9 +219,12 @@ let Alert = exports.Alert = (_dec = (0, _withDeterministicId.withDeterministicId
       css: styles === null || styles === void 0 ? void 0 : styles.alert,
       onKeyUp: this.handleKeyUp,
       elementRef: this.handleRef,
-      children: [this.renderIcon(), (0, _jsxRuntime.jsx)("div", {
+      children: [this.renderIcon(), (0, _jsxRuntime.jsxs)("div", {
         css: styles === null || styles === void 0 ? void 0 : styles.content,
-        children: children
+        children: [variantScreenReaderLabel && (0, _jsxRuntime.jsx)("span", {
+          css: styles === null || styles === void 0 ? void 0 : styles.variantScreenReaderLabel,
+          children: variantScreenReaderLabel
+        }), children]
       }), this.renderCloseButton()]
     });
   }

package/lib/Alert/props.js

@@ -43,6 +43,7 @@ const propTypes = exports.propTypes = {
   onDismiss: _propTypes.default.func,
   transition: _propTypes.default.oneOf(['none', 'fade']),
   open: _propTypes.default.bool,
-  hasShadow: _propTypes.default.bool
+  hasShadow: _propTypes.default.bool,
+  variantScreenReaderLabel: _propTypes.default.string
 };
 const allowedProps = exports.allowedProps = ['children', 'variant', 'margin', 'liveRegion', 'liveRegionPoliteness', 'isLiveRegionAtomic', 'screenReaderOnly', 'timeout', 'renderCloseButtonLabel', 'onDismiss', 'transition', 'open', 'hasShadow'];

package/lib/Alert/styles.js

@@ -123,6 +123,13 @@ const generateStyle = (componentTheme, props) => {
       fontWeight: componentTheme.contentFontWeight,
       lineHeight: componentTheme.contentLineHeight,
       padding: componentTheme.contentPadding
+    },
+    variantScreenReaderLabel: {
+      position: 'absolute',
+      height: '1px',
+      width: '1px',
+      overflow: 'hidden',
+      margin: '-1px'
     }
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-alerts",
-  "version": "10.18.0",
+  "version": "10.18.1-snapshot-1",
   "description": "An alert component",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -23,11 +23,11 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@instructure/ui-axe-check": "10.18.0",
-    "@instructure/ui-babel-preset": "10.18.0",
-    "@instructure/ui-color-utils": "10.18.0",
-    "@instructure/ui-scripts": "10.18.0",
-    "@instructure/ui-test-utils": "10.18.0",
+    "@instructure/ui-axe-check": "10.18.1-snapshot-1",
+    "@instructure/ui-babel-preset": "10.18.1-snapshot-1",
+    "@instructure/ui-color-utils": "10.18.1-snapshot-1",
+    "@instructure/ui-scripts": "10.18.1-snapshot-1",
+    "@instructure/ui-test-utils": "10.18.1-snapshot-1",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.0.1",
     "@testing-library/user-event": "^14.5.2",
@@ -35,16 +35,16 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.26.0",
-    "@instructure/console": "10.18.0",
-    "@instructure/emotion": "10.18.0",
-    "@instructure/shared-types": "10.18.0",
-    "@instructure/ui-a11y-content": "10.18.0",
-    "@instructure/ui-buttons": "10.18.0",
-    "@instructure/ui-icons": "10.18.0",
-    "@instructure/ui-motion": "10.18.0",
-    "@instructure/ui-react-utils": "10.18.0",
-    "@instructure/ui-themes": "10.18.0",
-    "@instructure/ui-view": "10.18.0",
+    "@instructure/console": "10.18.1-snapshot-1",
+    "@instructure/emotion": "10.18.1-snapshot-1",
+    "@instructure/shared-types": "10.18.1-snapshot-1",
+    "@instructure/ui-a11y-content": "10.18.1-snapshot-1",
+    "@instructure/ui-buttons": "10.18.1-snapshot-1",
+    "@instructure/ui-icons": "10.18.1-snapshot-1",
+    "@instructure/ui-motion": "10.18.1-snapshot-1",
+    "@instructure/ui-react-utils": "10.18.1-snapshot-1",
+    "@instructure/ui-themes": "10.18.1-snapshot-1",
+    "@instructure/ui-view": "10.18.1-snapshot-1",
     "keycode": "^2",
     "prop-types": "^15.8.1"
   },

package/src/Alert/README.md

@@ -20,6 +20,7 @@ type: example
     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>
@@ -27,6 +28,7 @@ type: example
     variant="info"
     renderCloseButtonLabel="Close"
     margin="small"
+    variantScreenReaderLabel="Information, "
   >
     Sample info text. I will fade out if you close me.
   </Alert>
@@ -34,6 +36,7 @@ type: example
     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
@@ -43,6 +46,7 @@ type: example
   <Alert
     variant="warning"
     margin="small"
+    variantScreenReaderLabel="Warning, "
   >
     Sample warning text. This alert is not dismissible and cannot be closed.
   </Alert>
@@ -59,6 +63,7 @@ type: example
   variant="info"
   margin="small"
   timeout={5000}
+  variantScreenReaderLabel="Information, "
 >
   Sample info text. I will fade out after 5 seconds
 </Alert>
@@ -111,6 +116,16 @@ For more information about live regions, see
       this.setState({ alerts })
     }
 
+    getScreenReaderLabel(variant) {
+      const labels = {
+        info: 'Information, ',
+        success: 'Success, ',
+        warning: 'Warning, ',
+        error: 'Error, '
+      }
+      return labels[variant] || ''
+    }
+
     render() {
       return (
         <div>
@@ -125,6 +140,9 @@ For more information about live regions, see
                   liveRegion={() => document.getElementById('flash-messages')}
                   liveRegionPoliteness={alert.politeness}
                   margin="small 0"
+                  variantScreenReaderLabel={this.getScreenReaderLabel(
+                    alert.variant
+                  )}
                 >
                   This is {alert.politeness === 'polite' ? 'a' : 'an'}{' '}
                   {alert.politeness} {alert.variant} alert
@@ -325,6 +343,7 @@ type: embed
     <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>

package/src/Alert/index.tsx

@@ -169,7 +169,11 @@ class Alert extends Component<AlertProps, AlertState> {
   }
 
   createScreenreaderContentNode() {
-    return <ScreenReaderContent>{this.props.children}</ScreenReaderContent>
+    return (
+      <ScreenReaderContent>
+        {this.props.variantScreenReaderLabel || ''} {this.props.children}
+      </ScreenReaderContent>
+    )
   }
 
   createScreenreaderAlert() {
@@ -260,7 +264,14 @@ class Alert extends Component<AlertProps, AlertState> {
   renderAlert() {
     // prevent onDismiss from being passed to the View component
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const { margin, styles, children, onDismiss, ...props } = this.props
+    const {
+      margin,
+      styles,
+      children,
+      onDismiss,
+      variantScreenReaderLabel,
+      ...props
+    } = this.props
     return (
       <View
         {...passthroughProps({ ...props })}
@@ -271,7 +282,14 @@ class Alert extends Component<AlertProps, AlertState> {
         elementRef={this.handleRef}
       >
         {this.renderIcon()}
-        <div css={styles?.content}>{children}</div>
+        <div css={styles?.content}>
+          {variantScreenReaderLabel && (
+            <span css={styles?.variantScreenReaderLabel}>
+              {variantScreenReaderLabel}
+            </span>
+          )}
+          {children}
+        </div>
         {this.renderCloseButton()}
       </View>
     )

package/src/Alert/props.ts

@@ -46,6 +46,10 @@ type AlertOwnProps = {
    * Determines color and icon
    */
   variant?: 'info' | 'success' | 'warning' | 'error'
+  /**
+   * How the screen reader should announce the alert variant. While the `variant` prop sets the color and icon for the alert component, this label should be a textual representation of that information. So e.g. if the variant is `info`, this label could be "Information," or "Information alert,". Note the `,` at the end of the label which helps the screenreader to be more natural sounding.
+   */
+  variantScreenReaderLabel?: string
   /**
    * Function that returns the DIV where screenreader alerts will be placed.
    */
@@ -115,7 +119,9 @@ type AlertProps = AlertOwnProps &
   WithStyleProps<AlertTheme, AlertStyle> &
   WithDeterministicIdProps
 
-type AlertStyle = ComponentStyle<'alert' | 'icon' | 'closeButton' | 'content'>
+type AlertStyle = ComponentStyle<
+  'alert' | 'icon' | 'closeButton' | 'content' | 'variantScreenReaderLabel'
+>
 
 const propTypes: PropValidators<PropKeys> = {
   children: PropTypes.node,
@@ -130,7 +136,8 @@ const propTypes: PropValidators<PropKeys> = {
   onDismiss: PropTypes.func,
   transition: PropTypes.oneOf(['none', 'fade']),
   open: PropTypes.bool,
-  hasShadow: PropTypes.bool
+  hasShadow: PropTypes.bool,
+  variantScreenReaderLabel: PropTypes.string
 }
 
 const allowedProps: AllowedPropKeys = [

package/src/Alert/styles.ts

@@ -114,6 +114,13 @@ const generateStyle = (
       fontWeight: componentTheme.contentFontWeight,
       lineHeight: componentTheme.contentLineHeight,
       padding: componentTheme.contentPadding
+    },
+    variantScreenReaderLabel: {
+      position: 'absolute',
+      height: '1px',
+      width: '1px',
+      overflow: 'hidden',
+      margin: '-1px'
     }
   }
 }