[system] Introduce visuallyHidden style utility (mui#21413)

Author: mnajdova

docs/pages/api-docs/rating.md

@@ -59,7 +59,7 @@ Any other props supplied will be provided to the root element (native element).
 | <span class="prop-name">readOnly</span> | <span class="prop-name">.MuiRating-readOnly</span> | Styles applied to the root element if `readOnly={true}`.
 | <span class="prop-name">disabled</span> | <span class="prop-name">.Mui-disabled</span> | Pseudo-class applied to the root element if `disabled={true}`.
 | <span class="prop-name">focusVisible</span> | <span class="prop-name">.Mui-focusVisible</span> | Pseudo-class applied to the root element if keyboard focused.
-| <span class="prop-name">visuallyhidden</span> | <span class="prop-name">.MuiRating-visuallyhidden</span> | Visually hide an element.
+| <span class="prop-name">visuallyHidden</span> | <span class="prop-name">.MuiRating-visuallyHidden</span> | Visually hide an element.
 | <span class="prop-name">pristine</span> | <span class="prop-name">.MuiRating-pristine</span> | Styles applied to the pristine label.
 | <span class="prop-name">label</span> | <span class="prop-name">.MuiRating-label</span> | Styles applied to the label elements.
 | <span class="prop-name">icon</span> | <span class="prop-name">.MuiRating-icon</span> | Styles applied to the icon wrapping elements.

docs/pages/api-docs/typography.md

@@ -37,7 +37,7 @@ The `MuiTypography` name can be used for providing [default props](/customizatio
 | <span class="prop-name">gutterBottom</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | If `true`, the text will have a bottom margin. |
 | <span class="prop-name">noWrap</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | If `true`, the text will not wrap, but instead will truncate with a text overflow ellipsis.<br>Note that text overflow can only happen with block or inline-block level elements (the element needs to have a width in order to overflow). |
 | <span class="prop-name">paragraph</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | If `true`, the text will have a bottom margin. |
-| <span class="prop-name">variant</span> | <span class="prop-type">'h1'<br>&#124;&nbsp;'h2'<br>&#124;&nbsp;'h3'<br>&#124;&nbsp;'h4'<br>&#124;&nbsp;'h5'<br>&#124;&nbsp;'h6'<br>&#124;&nbsp;'subtitle1'<br>&#124;&nbsp;'subtitle2'<br>&#124;&nbsp;'body1'<br>&#124;&nbsp;'body2'<br>&#124;&nbsp;'caption'<br>&#124;&nbsp;'button'<br>&#124;&nbsp;'overline'<br>&#124;&nbsp;'srOnly'<br>&#124;&nbsp;'inherit'</span> | <span class="prop-default">'body1'</span> | Applies the theme typography styles. |
+| <span class="prop-name">variant</span> | <span class="prop-type">'h1'<br>&#124;&nbsp;'h2'<br>&#124;&nbsp;'h3'<br>&#124;&nbsp;'h4'<br>&#124;&nbsp;'h5'<br>&#124;&nbsp;'h6'<br>&#124;&nbsp;'subtitle1'<br>&#124;&nbsp;'subtitle2'<br>&#124;&nbsp;'body1'<br>&#124;&nbsp;'body2'<br>&#124;&nbsp;'caption'<br>&#124;&nbsp;'button'<br>&#124;&nbsp;'overline'<br>&#124;&nbsp;'inherit'</span> | <span class="prop-default">'body1'</span> | Applies the theme typography styles. |
 | <span class="prop-name">variantMapping</span> | <span class="prop-type">object</span> | <span class="prop-default">{  h1: 'h1',  h2: 'h2',  h3: 'h3',  h4: 'h4',  h5: 'h5',  h6: 'h6',  subtitle1: 'h6',  subtitle2: 'h6',  body1: 'p',  body2: 'p',}</span> | The component maps the variant prop to a range of different HTML element types. For instance, subtitle1 to `<h6>`. If you wish to change that mapping, you can provide your own. Alternatively, you can use the `component` prop. |
 
 The `ref` is forwarded to the root element.
@@ -62,7 +62,6 @@ Any other props supplied will be provided to the root element (native element).
 | <span class="prop-name">subtitle1</span> | <span class="prop-name">.MuiTypography-subtitle1</span> | Styles applied to the root element if `variant="subtitle1"`.
 | <span class="prop-name">subtitle2</span> | <span class="prop-name">.MuiTypography-subtitle2</span> | Styles applied to the root element if `variant="subtitle2"`.
 | <span class="prop-name">overline</span> | <span class="prop-name">.MuiTypography-overline</span> | Styles applied to the root element if `variant="overline"`.
-| <span class="prop-name">srOnly</span> | <span class="prop-name">.MuiTypography-srOnly</span> | Styles applied to the root element if `variant="srOnly"`. Only accessible to screen readers.
 | <span class="prop-name">alignLeft</span> | <span class="prop-name">.MuiTypography-alignLeft</span> | Styles applied to the root element if `align="left"`.
 | <span class="prop-name">alignCenter</span> | <span class="prop-name">.MuiTypography-alignCenter</span> | Styles applied to the root element if `align="center"`.
 | <span class="prop-name">alignRight</span> | <span class="prop-name">.MuiTypography-alignRight</span> | Styles applied to the root element if `align="right"`.

docs/pages/system/screen-readers.js

@@ -0,0 +1,20 @@
+import React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import { prepareMarkdown } from 'docs/src/modules/utils/parseMarkdown';
+
+const pageFilename = 'system/screen-readers';
+const requireDemo = require.context('docs/src/pages/system/screen-readers', false, /\.(js|tsx)$/);
+const requireRaw = require.context(
+  '!raw-loader!../../src/pages/system/screen-readers',
+  false,
+  /\.(js|md|tsx)$/,
+);
+
+export default function Page({ demos, docs }) {
+  return <MarkdownDocs demos={demos} docs={docs} requireDemo={requireDemo} />;
+}
+
+Page.getInitialProps = () => {
+  const { demos, docs } = prepareMarkdown({ pageFilename, requireRaw });
+  return { demos, docs };
+};

docs/src/pages.js

@@ -150,6 +150,7 @@ const pages = [
       { pathname: '/system/shadows' },
       { pathname: '/system/sizing' },
       { pathname: '/system/spacing' },
+      { pathname: '/system/screen-readers' },
       { pathname: '/system/typography' },
       { pathname: '/system/api', title: 'API' },
     ],

docs/src/pages/components/icons/icons.md

@@ -236,12 +236,15 @@ If your icons have semantic meaning, you need to provide a text alternative only
 
 ```jsx
 import Icon from '@material-ui/core/Icon';
-import Typography from '@material-ui/core/Typography';
+import { visuallyHidden } from '@material-ui/system';
+import { makeStyles } from '@material-ui/core/styles';
+
+const classes = makeStyles({ visuallyHidden })();
 
 // ...
 
 <Icon>add_circle</Icon>
-<Typography variant="srOnly">Create a user</Typography>
+<span className={classes.visuallyHidden}>Create a user</span>
 ```
 
 ### Reference

docs/src/pages/components/tables/EnhancedTable.js

@@ -20,6 +20,7 @@ import FormControlLabel from '@material-ui/core/FormControlLabel';
 import Switch from '@material-ui/core/Switch';
 import DeleteIcon from '@material-ui/icons/Delete';
 import FilterListIcon from '@material-ui/icons/FilterList';
+import { visuallyHidden } from '@material-ui/system';
 
 function createData(name, calories, fat, carbs, protein) {
   return { name, calories, fat, carbs, protein };
@@ -106,7 +107,7 @@ function EnhancedTableHead(props) {
             >
               {headCell.label}
               {orderBy === headCell.id ? (
-                <span className={classes.visuallyHidden}>
+                <span className={classes.sortSpan}>
                   {order === 'desc' ? 'sorted descending' : 'sorted ascending'}
                 </span>
               ) : null}
@@ -200,17 +201,8 @@ const useStyles = makeStyles((theme) => ({
   table: {
     minWidth: 750,
   },
-  visuallyHidden: {
-    border: 0,
-    clip: 'rect(0 0 0 0)',
-    height: 1,
-    margin: -1,
-    overflow: 'hidden',
-    padding: 0,
-    position: 'absolute',
-    top: 20,
-    width: 1,
-  },
+  // TODO fix #20379.
+  sortSpan: visuallyHidden,
 }));
 
 export default function EnhancedTable() {

docs/src/pages/components/tables/EnhancedTable.tsx

@@ -19,6 +19,8 @@ import FormControlLabel from '@material-ui/core/FormControlLabel';
 import Switch from '@material-ui/core/Switch';
 import DeleteIcon from '@material-ui/icons/Delete';
 import FilterListIcon from '@material-ui/icons/FilterList';
+import { visuallyHidden } from '@material-ui/system';
+import { CSSProperties } from '@material-ui/styles';
 
 interface Data {
   calories: number;
@@ -141,7 +143,7 @@ function EnhancedTableHead(props: EnhancedTableProps) {
             >
               {headCell.label}
               {orderBy === headCell.id ? (
-                <span className={classes.visuallyHidden}>
+                <span className={classes.sortSpan}>
                   {order === 'desc' ? 'sorted descending' : 'sorted ascending'}
                 </span>
               ) : null}
@@ -227,17 +229,8 @@ const useStyles = makeStyles((theme: Theme) =>
     table: {
       minWidth: 750,
     },
-    visuallyHidden: {
-      border: 0,
-      clip: 'rect(0 0 0 0)',
-      height: 1,
-      margin: -1,
-      overflow: 'hidden',
-      padding: 0,
-      position: 'absolute',
-      top: 20,
-      width: 1,
-    },
+    // TODO fix #20379.
+    sortSpan: visuallyHidden as CSSProperties,
   }),
 );
 

docs/src/pages/guides/migration-v4/migration-v4.md

@@ -1,6 +1,6 @@
-# Migration from v3 to v4
+# Migration from v4 to v5
 
-<p class="description">Yeah, v4 has been released!</p>
+<p class="description">Yeah, v5 has been released!</p>
 
 Looking for the v4 docs? [Find them here](https://material-ui.com/versions/).
 
@@ -54,4 +54,19 @@ yarn add @material-ui/core
   - background-color: #f00;
   + border-color: #f00;
   }
-  ```
+  ```
+
+### Typography
+
+- [Typography] Replace `srOnly` prop support with a style util:
+
+  ```diff
+  -import Typography from '@material-ui/core/Typography';
+  +import { visuallyHidden } from '@material-ui/system';
+  +import styled from 'styled-component';
+
+  +const Span = styled('span')(visuallyHidden);
+
+  -<Typography variant="srOnly">Create a user</Typography>
+  +<Span>Create a user</Span>
+  ```

docs/src/pages/system/screen-readers/VisuallyHiddenUsage.js

@@ -0,0 +1,21 @@
+import React from 'react';
+import Link from '@material-ui/core/Link';
+import { visuallyHidden } from '@material-ui/system';
+import { makeStyles } from '@material-ui/core/styles';
+
+const useStyles = makeStyles({
+  // TODO fix #20379.
+  span: visuallyHidden,
+});
+
+export default function VisuallyHiddenUsage() {
+  const classes = useStyles();
+
+  return (
+    <Link href="#foo">
+      Read more
+      {/* always visually hidden because the parent is focusable element */}
+      <span className={classes.span}>about how to visually hide elements</span>
+    </Link>
+  );
+}

docs/src/pages/system/screen-readers/VisuallyHiddenUsage.tsx

@@ -0,0 +1,22 @@
+import React from 'react';
+import Link from '@material-ui/core/Link';
+import { visuallyHidden } from '@material-ui/system';
+import { makeStyles } from '@material-ui/core/styles';
+import { CSSProperties } from '@material-ui/styles';
+
+const useStyles = makeStyles({
+  // TODO fix #20379.
+  span: visuallyHidden as CSSProperties,
+});
+
+export default function VisuallyHiddenUsage() {
+  const classes = useStyles();
+
+  return (
+    <Link href="#foo">
+      Read more
+      {/* always visually hidden because the parent is focusable element */}
+      <span className={classes.span}>about how to visually hide elements</span>
+    </Link>
+  );
+}

docs/src/pages/system/screen-readers/screen-readers.md

@@ -0,0 +1,13 @@
+# Screen readers
+
+<p class="description">Collection of utilities for improving accessibility with screen readers.</p>
+
+## Visually hidden elements
+
+The visually hidden style utility provides a common mechanism for hidings elements visually, but making them available for the assistive technology.
+
+### Usage
+
+The visually hidden style utility can help provide context to read more links.
+
+{{"demo": "pages/system/screen-readers/VisuallyHiddenUsage.js"}}

framer/Material-UI.framerfx/code/Typography.tsx

@@ -29,7 +29,6 @@ interface Props {
     | 'caption'
     | 'button'
     | 'overline'
-    | 'srOnly'
     | 'inherit';
   label?: string;
   width?: number;
@@ -93,7 +92,6 @@ addPropertyControls(Typography, {
       'caption',
       'button',
       'overline',
-      'srOnly',
       'inherit',
     ],
   },

packages/material-ui-lab/src/Rating/Rating.d.ts

@@ -93,7 +93,7 @@ export type RatingClassKey =
   | 'readOnly'
   | 'disabled'
   | 'focusVisible'
-  | 'visuallyhidden'
+  | 'visuallyHidden'
   | 'pristine'
   | 'label'
   | 'icon'

packages/material-ui-lab/src/Rating/Rating.js

@@ -10,6 +10,7 @@ import {
   useControlled,
   unstable_useId as useId,
 } from '@material-ui/core/utils';
+import { visuallyHidden } from '@material-ui/system';
 import Star from '../internal/svg-icons/Star';
 
 function clamp(value, min, max) {
@@ -71,18 +72,7 @@ export const styles = (theme) => ({
   /* Pseudo-class applied to the root element if keyboard focused. */
   focusVisible: {},
   /* Visually hide an element. */
-  visuallyhidden: {
-    border: 0,
-    clip: 'rect(0 0 0 0)',
-    height: 1,
-    margin: -1,
-    color: '#000',
-    overflow: 'hidden',
-    padding: 0,
-    position: 'absolute',
-    top: 20,
-    width: 1,
-  },
+  visuallyHidden,
   /* Styles applied to the pristine label. */
   pristine: {
     'input:focus + &': {
@@ -342,7 +332,7 @@ const Rating = React.forwardRef(function Rating(props, ref) {
       <React.Fragment key={state.value}>
         <label className={classes.label} htmlFor={id} {...labelProps}>
           {container}
-          <span className={classes.visuallyhidden}>{getLabelText(state.value)}</span>
+          <span className={classes.visuallyHidden}>{getLabelText(state.value)}</span>
         </label>
         <input
           onFocus={handleFocus}
@@ -355,7 +345,7 @@ const Rating = React.forwardRef(function Rating(props, ref) {
           type="radio"
           name={name}
           checked={state.checked}
-          className={classes.visuallyhidden}
+          className={classes.visuallyHidden}
         />
       </React.Fragment>
     );
@@ -444,10 +434,10 @@ const Rating = React.forwardRef(function Rating(props, ref) {
             type="radio"
             name={name}
             defaultChecked
-            className={classes.visuallyhidden}
+            className={classes.visuallyHidden}
           />
           <label className={classes.pristine} htmlFor={`${name}-empty`}>
-            <span className={classes.visuallyhidden}>{emptyLabelText}</span>
+            <span className={classes.visuallyHidden}>{emptyLabelText}</span>
           </label>
         </React.Fragment>
       )}

packages/material-ui-system/src/index.d.ts

@@ -1,5 +1,4 @@
 import * as CSS from 'csstype';
-
 // disable automatic export
 export {};
 
@@ -202,5 +201,7 @@ export const typography: SimpleStyleFunction<
 >;
 export type TypographyProps = PropsFor<typeof typography>;
 
+export const visuallyHidden: CSS.Properties;
+
 // utils
 type Omit<T, K> = Pick<T, Exclude<keyof T, K>>;

packages/material-ui-system/src/index.js

@@ -20,3 +20,4 @@ export * from './spacing';
 export { default as style } from './style';
 export { default as typography } from './typography';
 export * from './typography';
+export { default as visuallyHidden } from './visuallyHidden';

packages/material-ui-system/src/visuallyHidden.js

@@ -0,0 +1,13 @@
+const visuallyHidden = {
+  border: 0,
+  clip: 'rect(0 0 0 0)',
+  height: 1,
+  margin: -1,
+  overflow: 'hidden',
+  padding: 0,
+  position: 'absolute',
+  whiteSpace: 'nowrap',
+  width: 1,
+};
+
+export default visuallyHidden;

packages/material-ui/src/Typography/Typography.d.ts

@@ -1,9 +1,7 @@
 import * as React from 'react';
 import { StandardProps, PropTypes } from '..';
 import { OverrideProps, OverridableTypeMap, OverridableComponent } from '../OverridableComponent';
-import { Variant as ThemeVariant } from '../styles/createTypography';
-
-type Variant = ThemeVariant | 'srOnly';
+import { Variant } from '../styles/createTypography';
 
 export interface TypographyTypeMap<P = {}, D extends React.ElementType = 'span'> {
   props: P & {
@@ -64,7 +62,6 @@ export type TypographyClassKey =
   | 'caption'
   | 'button'
   | 'overline'
-  | 'srOnly'
   | 'alignLeft'
   | 'alignCenter'
   | 'alignRight'

packages/material-ui/src/Typography/Typography.js

@@ -35,13 +35,6 @@ export const styles = (theme) => ({
   subtitle2: theme.typography.subtitle2,
   /* Styles applied to the root element if `variant="overline"`. */
   overline: theme.typography.overline,
-  /* Styles applied to the root element if `variant="srOnly"`. Only accessible to screen readers. */
-  srOnly: {
-    position: 'absolute',
-    height: 1,
-    width: 1,
-    overflow: 'hidden',
-  },
   /* Styles applied to the root element if `align="left"`. */
   alignLeft: {
     textAlign: 'left',
@@ -233,7 +226,6 @@ Typography.propTypes = {
     'caption',
     'button',
     'overline',
-    'srOnly',
     'inherit',
   ]),
   /**