feat: accessible descriptions and labels for various components (#674)

* feat: added descriptions for content buttons, links, basic cards, caption
gravity-ui · Nov 7, 2023 · 44ef8fa · 44ef8fa
1 parent b5be2da
commit 44ef8fa
Show file tree

Hide file tree

Showing 13 changed files with 79 additions and 13 deletions.
diff --git a/src/blocks/Header/Header.tsx b/src/blocks/Header/Header.tsx
@@ -1,5 +1,7 @@
 import React, {useContext} from 'react';
 
+import {useUniqId} from '@gravity-ui/uikit';
+
 import {Button, HTML, Media, RouterLink} from '../../components';
 import HeaderBreadcrumbs from '../../components/HeaderBreadcrumbs/HeaderBreadcrumbs';
 import {getMediaImage} from '../../components/Media/Image/utils';
@@ -96,6 +98,7 @@ export const HeaderBlock = (props: WithChildren<HeaderBlockFullProps>) => {
     const imageThemed = image && getThemedValue(image, theme);
     const videoThemed = video && getThemedValue(video, theme);
     const fullWidth = backgroundThemed?.fullWidth || backgroundThemed?.fullWidthMedia;
+    const titleId = useUniqId();
 
     return (
         <header
@@ -134,7 +137,7 @@ export const HeaderBlock = (props: WithChildren<HeaderBlockFullProps>) => {
                                             <HTML>{overtitle}</HTML>
                                         </div>
                                     )}
-                                    <h1 className={b('title')}>
+                                    <h1 className={b('title')} id={titleId}>
                                         {status}
                                         {renderTitle ? renderTitle(title) : <HTML>{title}</HTML>}
                                     </h1>
@@ -157,6 +160,9 @@ export const HeaderBlock = (props: WithChildren<HeaderBlockFullProps>) => {
                                                         key={index}
                                                         className={b('button')}
                                                         size="xl"
+                                                        extraProps={{
+                                                            'aria-describedby': titleId,
+                                                        }}
                                                         {...button}
                                                     />
                                                 </RouterLink>

diff --git a/src/blocks/Tabs/Tabs.tsx b/src/blocks/Tabs/Tabs.tsx
@@ -1,5 +1,7 @@
 import React, {Fragment, useRef, useState} from 'react';
 
+import {useUniqId} from '@gravity-ui/uikit';
+
 import AnimateBlock from '../../components/AnimateBlock/AnimateBlock';
 import ButtonTabs, {ButtonTabsItemProps} from '../../components/ButtonTabs/ButtonTabs';
 import FullscreenImage from '../../components/FullscreenImage/FullscreenImage';
@@ -36,13 +38,19 @@ export const TabsBlock = ({
     const ref = useRef<HTMLDivElement>(null);
     const mediaWidth = ref?.current?.offsetWidth;
     const mediaHeight = mediaWidth && getHeight(mediaWidth);
+    const captionId = useUniqId();
 
     let imageProps;
 
     if (activeTabData) {
         const themedImage = getThemedValue(activeTabData.image, theme);
 
         imageProps = themedImage && getMediaImage(themedImage);
+        if (activeTabData.caption && imageProps) {
+            Object.assign(imageProps, {
+                'aria-describedby': captionId,
+            });
+        }
     }
 
     const showMedia = Boolean(activeTabData?.media || imageProps);
@@ -99,7 +107,11 @@ export const TabsBlock = ({
                     <FullscreenImage {...imageProps} imageClassName={b('image')} />
                 </Fragment>
             )}
-            {activeTabData?.caption && <p className={b('caption')}>{activeTabData.caption}</p>}
+            {activeTabData?.caption && (
+                <p className={b('caption')} id={captionId}>
+                    {activeTabData.caption}
+                </p>
+            )}
         </Col>
     );
 

diff --git a/src/components/BackLink/BackLink.tsx b/src/components/BackLink/BackLink.tsx
@@ -1,4 +1,4 @@
-import React, {ReactNode, useCallback, useContext} from 'react';
+import React, {HTMLProps, ReactNode, useCallback, useContext} from 'react';
 
 import {Button, ButtonSize, Icon} from '@gravity-ui/uikit';
 
@@ -9,14 +9,15 @@ import {DefaultEventNames, Tabbable} from '../../models';
 
 export type Theme = 'default' | 'special';
 
-export interface BackLinkProps extends Tabbable {
+export interface BackLinkProps<T = HTMLElement> extends Tabbable {
     url: string;
     title: ReactNode;
     theme?: Theme;
     size?: ButtonSize;
     className?: string;
     shouldHandleBackAction?: boolean;
     onClick?: () => void;
+    extraProps?: HTMLProps<T>;
 }
 
 export default function BackLink(props: BackLinkProps) {
@@ -30,6 +31,7 @@ export default function BackLink(props: BackLinkProps) {
         shouldHandleBackAction = false,
         onClick,
         tabIndex,
+        extraProps,
     } = props;
     const handleAnalytics = useAnalytics(DefaultEventNames.ShareButton, url);
 
@@ -59,6 +61,7 @@ export default function BackLink(props: BackLinkProps) {
             href={shouldHandleBackAction ? undefined : url}
             onClick={shouldHandleBackAction ? backActionHandler : undefined}
             tabIndex={tabIndex}
+            extraProps={extraProps}
         >
             <Icon data={ArrowSidebar} size={24} />
             <span>{title}</span>

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
@@ -18,7 +18,6 @@ import './Button.scss';
 export interface ButtonProps extends Omit<ButtonParams, 'url'>, QAProps {
     className?: string;
     url?: string;
-    urlTitle?: string;
     onClick?: React.MouseEventHandler<HTMLButtonElement | HTMLAnchorElement>;
 }
 

diff --git a/src/components/FileLink/FileLink.tsx b/src/components/FileLink/FileLink.tsx
@@ -57,6 +57,7 @@ const FileLink = (props: WithChildren<FileLinkProps>) => {
         onClick,
         tabIndex,
         urlTitle,
+        extraProps,
     } = props;
     const fileExt = getFileExt(href) as FileExtension;
     const labelTheme = (FileExtensionThemes[fileExt] || 'unknown') as LabelProps['theme'];
@@ -74,6 +75,7 @@ const FileLink = (props: WithChildren<FileLinkProps>) => {
                     tabIndex={tabIndex}
                     title={urlTitle}
                     {...getLinkProps(href, hostname)}
+                    {...extraProps}
                 >
                     {text}
                 </a>

diff --git a/src/components/FullscreenImage/FullscreenImage.tsx b/src/components/FullscreenImage/FullscreenImage.tsx
@@ -1,4 +1,4 @@
-import React, {CSSProperties, useState} from 'react';
+import React, {CSSProperties, HTMLProps, useState} from 'react';
 
 import {Icon, Modal} from '@gravity-ui/uikit';
 
@@ -14,21 +14,22 @@ export interface FullscreenImageProps extends ImageProps {
     imageClassName?: string;
     modalImageClass?: string;
     imageStyle?: CSSProperties;
+    extraProps?: HTMLProps<HTMLDivElement>;
 }
 
 const b = block('fullscreen-image');
 const FULL_SCREEN_ICON_SIZE = 18;
 const CLOSE_ICON_SIZE = 30;
 
 const FullscreenImage = (props: FullscreenImageProps) => {
-    const {imageClassName, modalImageClass, imageStyle, alt = i18n('img-alt')} = props;
+    const {imageClassName, modalImageClass, imageStyle, alt = i18n('img-alt'), extraProps} = props;
     const [isOpened, setIsOpened] = useState(false);
 
     const openModal = () => setIsOpened(true);
     const closeModal = () => setIsOpened(false);
 
     return (
-        <div className={b()}>
+        <div className={b()} {...extraProps}>
             <div className={b('image-wrapper')}>
                 <Image
                     {...props}

diff --git a/src/components/Image/Image.tsx b/src/components/Image/Image.tsx
@@ -57,6 +57,7 @@ const Image = (props: ImageProps) => {
         onClick,
         containerClassName,
         qa,
+        ...rest
     } = props;
     const [imgLoadingError, setImgLoadingError] = useState(false);
 
@@ -113,6 +114,7 @@ const Image = (props: ImageProps) => {
                 style={style}
                 onClick={onClick}
                 onError={() => setImgLoadingError(true)}
+                {...rest}
             />
         </picture>
     );

diff --git a/src/components/Link/Link.tsx b/src/components/Link/Link.tsx
@@ -58,6 +58,7 @@ const LinkBlock = (props: WithChildren<LinkFullProps>) => {
         tabIndex,
         qa,
         urlTitle,
+        extraProps,
     } = props;
     const qaAttributes = getQaAttrubutes(qa, ['normal']);
 
@@ -82,6 +83,7 @@ const LinkBlock = (props: WithChildren<LinkFullProps>) => {
                         url={href}
                         onClick={onClick}
                         tabIndex={tabIndex}
+                        extraProps={extraProps}
                     />
                 );
             case 'file-link':
@@ -94,6 +96,7 @@ const LinkBlock = (props: WithChildren<LinkFullProps>) => {
                         textSize={textSize}
                         onClick={onClick}
                         tabIndex={tabIndex}
+                        extraProps={extraProps}
                     />
                 );
             case 'normal': {
@@ -109,6 +112,7 @@ const LinkBlock = (props: WithChildren<LinkFullProps>) => {
                         title={urlTitle}
                         {...linkProps}
                         data-qa={qaAttributes.normal}
+                        {...extraProps}
                     >
                         {arrow ? (
                             <Fragment>

diff --git a/src/components/Title/Title.tsx b/src/components/Title/Title.tsx
@@ -13,13 +13,15 @@ const b = block('title');
 
 export interface TitleProps extends TitleParams {
     colSizes?: GridColumnSizesType;
+    id?: string;
 }
 
 const Title = ({
     title,
     subtitle,
     className,
     colSizes = {all: 12, sm: 8},
+    id,
 }: TitleProps & ClassNameProps) => {
     if (!title && !subtitle) {
         return null;
@@ -29,7 +31,7 @@ const Title = ({
         !title || typeof title === 'string' ? ({text: title} as TitleItemProps) : title;
 
     return (
-        <div className={b(null, className)}>
+        <div className={b(null, className)} id={id}>
             {text && (
                 <Col reset sizes={colSizes}>
                     <TitleItem text={text} {...titleProps} />

diff --git a/src/models/constructor-items/blocks.ts b/src/models/constructor-items/blocks.ts
@@ -352,7 +352,9 @@ export interface ContentItemProps {
 
 export interface ContentBlockProps {
     title?: TitleItemBaseProps | string;
+    titleId?: string;
     text?: string;
+    textId?: string;
     additionalInfo?: string;
     links?: LinkProps[];
     buttons?: ButtonProps[];

diff --git a/src/models/constructor-items/common.ts b/src/models/constructor-items/common.ts
@@ -1,4 +1,4 @@
-import React, {CSSProperties, ReactNode} from 'react';
+import React, {CSSProperties, HTMLProps, ReactNode} from 'react';
 
 import {ButtonView, ButtonProps as UikitButtonProps} from '@gravity-ui/uikit';
 
@@ -124,7 +124,7 @@ interface LoopProps {
 
 // images
 
-export interface ImageInfoProps {
+export interface ImageInfoProps extends Pick<HTMLProps<HTMLImageElement>, 'aria-describedby'> {
     alt?: string;
     disableCompress?: boolean;
 }
@@ -179,6 +179,7 @@ export interface LinkProps extends AnalyticsEventsBase, Stylable, Tabbable {
     target?: string;
     metrikaGoals?: MetrikaGoal;
     pixelEvents?: ButtonPixel;
+    extraProps?: HTMLProps<HTMLAnchorElement>;
 }
 
 export interface FileLinkProps extends ClassNameProps, Tabbable {
@@ -189,6 +190,7 @@ export interface FileLinkProps extends ClassNameProps, Tabbable {
     theme?: ContentTheme;
     urlTitle?: string;
     onClick?: () => void;
+    extraProps?: HTMLProps<HTMLAnchorElement>;
 }
 
 // buttons
@@ -205,6 +207,7 @@ export interface ButtonProps
         Pick<UikitButtonProps, 'size' | 'width' | 'extraProps'> {
     text: string;
     url: string;
+    urlTitle?: string;
     primary?: boolean;
     theme?: ButtonTheme;
     img?: ButtonImageProps | string;

diff --git a/src/sub-blocks/BasicCard/BasicCard.tsx b/src/sub-blocks/BasicCard/BasicCard.tsx
@@ -1,5 +1,7 @@
 import React from 'react';
 
+import {useUniqId} from '@gravity-ui/uikit';
+
 import {Content} from '../';
 import CardBase from '../../components/CardBase/CardBase';
 import Image from '../../components/Image/Image';
@@ -24,9 +26,15 @@ const BasicCard = (props: BasicCardProps) => {
         ...cardParams
     } = props;
     const iconProps = icon && getMediaImage(icon);
+    const titleId = useUniqId();
+    const descriptionId = useUniqId();
 
     return (
-        <CardBase className={b()} {...cardParams}>
+        <CardBase
+            className={b()}
+            {...cardParams}
+            extraProps={{'aria-describedby': descriptionId, 'aria-labelledby': titleId}}
+        >
             <CardBase.Content>
                 <div className={b('content', {['icon-position']: iconPosition})}>
                     {iconProps && (
@@ -37,7 +45,9 @@ const BasicCard = (props: BasicCardProps) => {
                     )}
                     <Content
                         title={title}
+                        titleId={titleId}
                         text={text}
+                        textId={descriptionId}
                         additionalInfo={additionalInfo}
                         links={links}
                         buttons={buttons}

diff --git a/src/sub-blocks/Content/Content.tsx b/src/sub-blocks/Content/Content.tsx
@@ -1,5 +1,7 @@
 import React from 'react';
 
+import {useUniqId} from '@gravity-ui/uikit';
+
 import {Button, Title, YFMWrapper} from '../../components';
 import LinkBlock from '../../components/Link/Link';
 import {Col} from '../../grid';
@@ -49,7 +51,9 @@ export type ContentProps = ContentBlockProps & ClassNameProps & QAProps;
 const Content = (props: ContentProps) => {
     const {
         title,
+        titleId: titleIdFromProps,
         text,
+        textId,
         additionalInfo,
         size = 'l',
         links,
@@ -69,6 +73,8 @@ const Content = (props: ContentProps) => {
             : title;
 
     const hasTitle = Boolean(title);
+    const defaultTitleId = useUniqId();
+    const titleId = titleIdFromProps || defaultTitleId;
 
     return (
         <Col
@@ -77,12 +83,20 @@ const Content = (props: ContentProps) => {
             sizes={colSizes}
             qa={qaAttributes.container}
         >
-            {title && <Title className={b('title')} title={titleProps} colSizes={{all: 12}} />}
+            {title && (
+                <Title
+                    className={b('title')}
+                    title={titleProps}
+                    colSizes={{all: 12}}
+                    id={titleId}
+                />
+            )}
             {text && (
                 <div className={b('text', {['without-title']: !hasTitle})}>
                     <YFMWrapper
                         content={text}
                         modifiers={{constructor: true, [`constructor-size-${size}`]: true}}
+                        id={textId}
                     />
                 </div>
             )}
@@ -108,6 +122,9 @@ const Content = (props: ContentProps) => {
                             textSize={getLinkSize(size)}
                             key={link.url}
                             qa={qaAttributes.link}
+                            extraProps={{
+                                'aria-describedby': link.urlTitle ? undefined : titleId,
+                            }}
                         />
                     ))}
                 </div>
@@ -121,6 +138,9 @@ const Content = (props: ContentProps) => {
                             key={item.url}
                             size={getButtonSize(size)}
                             qa={qaAttributes.button}
+                            extraProps={{
+                                'aria-describedby': item.urlTitle ? undefined : titleId,
+                            }}
                         />
                     ))}
                 </div>