resolves theopenconversationkit#87 Improve web accessibility for screen reader

Author: correi-f

README.md

@@ -255,6 +255,38 @@ A `TockTheme` can be used as a value of a `ThemeProvider` of [`emotion-theming`]
 | `timeoutBetweenMessage`                  | `number?`                             | Timeout between message                                          |
 | `widgets`                                | `any?`                                | Custom display component                                         |
 | `disableSse`                             | `boolean?`                            | Disable SSE (not even trying)                                    |
+| `accessibility`                          | `TockAccessibility`                   | Object for overriding role and label accessibility attributes    |
+
+#### `TockAccessibility`
+
+| Property name                     | Type                   | Description                                                                                       |
+|-----------------------------------|------------------------|---------------------------------------------------------------------------------------------------|
+| `carouselRoleDescription`         | `string?`              | Message of the carousel aria-roledescription attribute (overrides 'Carousel')                     |
+| `slideRoleDescription`            | `string?`              | Message of the slide carousel aria-roledescription attribute (overrides 'Slide')                  |
+| `previousCarouselButtonLabel`     | `string?`              | Message of the carousel previous button image aria-label attribute (overrides 'Previous slides')  |
+| `nextCarouselButtonLabel`         | `string?`              | Message of the carousel next button image aria-label attribute (overrides 'Next slides')          |
+| `sendButtonLabel`                 | `string?`              | Message of the send message button image aria-label attribute (overrides 'Send a message')        |
+| `clearButtonLabel`                | `string?`              | Message of the clear messages button image aria-label attribute (overrides 'Clear messages')      |
+
+#### Accessibility
+
+The optional `accessibility` makes it possible to override default messages for some aria attributes.
+
+Example :
+
+```js
+renderChat(
+    document.getElementById('chat'),
+    '<TOCK_BOT_API_URL>',
+    undefined,
+    {},
+    { accessibility: {
+        carouselRoleDescription: 'Carousel',
+        slideRoleDescription: 'Resultat',
+      },
+    },
+);
+```
 
 #### Opening message
 

src/TockAccessibility.ts

@@ -0,0 +1,10 @@
+export interface TockAccessibility {
+    carouselRoleDescription?: string;
+    slideRoleDescription?: string;
+    previousCarouselButtonLabel?: string;
+    nextCarouselButtonLabel?: string;
+    sendButtonLabel?: string;
+    clearButtonLabel?: string;
+}
+
+export default TockAccessibility;

src/TockOptions.ts

@@ -1,3 +1,5 @@
+import TockAccessibility from "TockAccessibility";
+
 export interface TockOptions {
   // An initial message to send to the backend to trigger a welcome sequence
   openingMessage?: string;
@@ -7,6 +9,7 @@ export interface TockOptions {
   timeoutBetweenMessage?: number;
   widgets?: any;
   disableSse?: boolean;
+  accessibility?: TockAccessibility;
 }
 
 export default TockOptions;

src/components/Card/Card.tsx

@@ -10,12 +10,13 @@ import { prop } from 'styled-tools';
 import { Button } from '../../TockContext';
 
 export const CardOuter: StyledComponent<
-  DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>,
+  DetailedHTMLProps<HTMLAttributes<HTMLLIElement>, HTMLLIElement>,
   unknown,
   TockTheme
-> = styled.div`
+> = styled.li`
   max-width: ${prop<any>('theme.sizing.conversation.width')};
   margin: 0.5em auto;
+  list-style: none;
 `;
 
 export const CardContainer: StyledComponent<
@@ -34,23 +35,27 @@ export const CardContainer: StyledComponent<
 `;
 
 const CardTitle: StyledComponent<
-  DetailedHTMLProps<HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>,
+  DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>,
   unknown,
   TockTheme
-> = styled.h3`
+> = styled.span`
   margin: 0.5em 0;
   font-size: 1.5em;
+  font-weight: bold;
+  display: block;
 
   ${prop<any>('theme.overrides.card.cardTitle', '')};
 `;
 
 const CardSubTitle: StyledComponent<
-  DetailedHTMLProps<HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>,
+  DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>,
   unknown,
   TockTheme
-> = styled.h4`
+> = styled.span`
   margin: 0.5em 0;
   font-size: 1em;
+  font-weight: bold;
+  display: block;
 
   ${prop<any>('theme.overrides.card.cardSubTitle', '')};
 `;
@@ -117,15 +122,16 @@ export interface CardProps {
   subTitle?: string;
   imageUrl?: string;
   buttons?: Button[];
+  roleDescription?: string;
   onAction: (button: Button) => void;
 }
 
-const Card = React.forwardRef<HTMLDivElement, CardProps>(function cardRender(
-  { title, subTitle, imageUrl, buttons, onAction }: CardProps,
+const Card = React.forwardRef<HTMLLIElement, CardProps>(function cardRender(
+  { title, subTitle, imageUrl, buttons, roleDescription, onAction }: CardProps,
   ref,
 ) {
   return (
-    <CardOuter ref={ref}>
+    <CardOuter ref={ref} role={(ref == undefined) ? undefined : 'group'} aria-roledescription={(ref == undefined) ? undefined : ((roleDescription) ? roleDescription : 'Slide')}>
       <CardContainer>
         {imageUrl && <CardImage src={imageUrl} alt={title} />}
         <CardTitle>{title}</CardTitle>

src/components/Carousel/Carousel.tsx

@@ -7,35 +7,38 @@ import { useTheme } from 'emotion-theming';
 import useCarousel from './hooks/useCarousel';
 import useArrowVisibility from './hooks/useArrowVisibility';
 import TockTheme from 'styles/theme';
+import TockAccessibility from 'TockAccessibility';
 
 const ButtonContainer: StyledComponent<
-  DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>,
+  DetailedHTMLProps<HTMLAttributes<HTMLLIElement>, HTMLLIElement>,
   unknown,
   TockTheme
-> = styled.div`
+> = styled.li`
   margin: 0.4em 0;
   position: relative;
+  list-style: none;
 `;
 
 const ItemContainer: StyledComponent<
-  DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>,
+  DetailedHTMLProps<HTMLAttributes<HTMLUListElement>, HTMLUListElement>,
   unknown,
   TockTheme
-> = styled.div`
+> = styled.ul`
   display: flex;
   overflow: auto;
   -webkit-overflow-scrolling: touch;
   justify-content: start;
   scroll-behavior: smooth;
   touch-action: pan-x pan-y;
   position: relative;
+  padding: 0;
   &::-webkit-scrollbar {
     display: none;
   }
   scrollbar-width: none;
   ${prop<any>('theme.overrides.carouselContainer', '')}
 
-  & > div, & > * {
+  & > li, & > * {
     margin-left: 1em;
     margin-right: 1em;
 
@@ -111,13 +114,15 @@ const Next: StyledComponent<
   ${prop<any>('theme.overrides.carouselArrow', '')};
 `;
 
-const Carousel: (props: { children?: ReactElement[] }) => JSX.Element = ({
+const Carousel: (props: { children?: ReactElement[] , accessibility?: TockAccessibility}) => JSX.Element = ({
   children,
+  accessibility,
 }: {
   children?: ReactElement[];
+  accessibility?: TockAccessibility;
 }) => {
   const theme: TockTheme = useTheme<TockTheme>();
-  const [ref, previous, next] = useCarousel<HTMLDivElement>(children?.length);
+  const [ref, previous, next] = useCarousel<HTMLUListElement>(children?.length);
   const [leftVisible, rightVisible] = useArrowVisibility(
     ref.container,
     ref.items,
@@ -127,17 +132,17 @@ const Carousel: (props: { children?: ReactElement[] }) => JSX.Element = ({
     <ButtonContainer>
       {leftVisible && (
         <Previous onClick={previous}>
-          <ArrowLeftCircle size={`calc(${theme.typography.fontSize} * 2)`} />
+          <ArrowLeftCircle size={`calc(${theme.typography.fontSize} * 2)`} role='img' aria-label={accessibility?.previousCarouselButtonLabel || 'Previous slides'} focusable='false'/>
         </Previous>
       )}
-      <ItemContainer ref={ref.container}>
+      <ItemContainer ref={ref.container} role='group' aria-roledescription={accessibility?.carouselRoleDescription || 'Carousel'}>
         {children?.map((child, i) =>
-          React.cloneElement(child, { ref: ref.items[i] }, undefined),
+          React.cloneElement(child, { ref: ref.items[i], roleDescription: accessibility?.slideRoleDescription }, undefined),
         )}
       </ItemContainer>
       {rightVisible && (
         <Next onClick={next}>
-          <ArrowRightCircle size={`calc(${theme.typography.fontSize} * 2)`} />
+          <ArrowRightCircle size={`calc(${theme.typography.fontSize} * 2)`} role='img' aria-label={accessibility?.nextCarouselButtonLabel || 'Next slides'} focusable='false'/>
         </Next>
       )}
     </ButtonContainer>

src/components/Carousel/hooks/useCarousel.ts

@@ -1,4 +1,4 @@
-import { RefObject, useRef, useCallback } from 'react';
+import { RefObject, useRef, useCallback, useEffect } from 'react';
 import useRefs from './useRefs';
 import useMeasures, { Measure } from './useMeasures';
 
@@ -19,10 +19,32 @@ function getMeanX(
   return Math.round((previous.x + previous.width + target.x) / 2);
 }
 
+function setAriaAttributes(
+  measures: Measure[],
+  itemRefs: RefObject<HTMLElement>[],
+  targetIndex: number,
+  width: number,
+) {
+  if (width !== 0) {
+    itemRefs.forEach(item => {
+      const offsetLeftItem = item.current?.offsetLeft || 0;
+
+      if (offsetLeftItem < measures[targetIndex].x || (offsetLeftItem + (item.current?.offsetWidth || 0) > measures[targetIndex].x + width)) {
+        item.current?.setAttribute('aria-hidden', 'true');
+        item.current?.setAttribute('tabIndex', '-1');
+      } else {
+        item.current?.removeAttribute('aria-hidden');
+        item.current?.removeAttribute('tabIndex');
+      }
+    });
+  }
+}
+
 function scrollStep(
   direction: 'NEXT' | 'PREVIOUS',
   container: HTMLElement | null,
   measures: Measure[],
+  itemRefs: RefObject<HTMLElement>[],
 ) {
   if (!container) return;
   const x = container.scrollLeft;
@@ -36,6 +58,7 @@ function scrollStep(
       measures[targetIndex],
       measures[targetIndex - 1],
     );
+    setAriaAttributes(measures, itemRefs, targetIndex, width);
   } else {
     const firstLeftHidden = measures
       .slice()
@@ -51,6 +74,7 @@ function scrollStep(
       measures[targetIndex - 1],
       measures[targetIndex],
     );
+    setAriaAttributes(measures, itemRefs, targetIndex, width);
   }
 }
 
@@ -60,15 +84,21 @@ export default function useCarousel<T>(itemCount = 0): CarouselReturn<T> {
   const measures = useMeasures(itemRefs);
 
   const previous = useCallback(
-    () => scrollStep('PREVIOUS', containerRef.current, measures),
+    () => scrollStep('PREVIOUS', containerRef.current, measures, itemRefs),
     [containerRef, measures],
   );
 
   const next = useCallback(
-    () => scrollStep('NEXT', containerRef.current, measures),
+    () => scrollStep('NEXT', containerRef.current, measures, itemRefs),
     [containerRef, measures],
   );
 
+  useEffect(() => {
+    if (measures !== undefined && measures.length !== 0) {
+      setAriaAttributes(measures, itemRefs, 0, (containerRef.current as HTMLElement | null)?.clientWidth || 0);
+    }
+  }, [measures]);
+
   return [
     {
       container: containerRef,

src/components/Chat/Chat.tsx

@@ -3,6 +3,7 @@ import useTock, { UseTock } from '../../useTock';
 import ChatInput from '../ChatInput';
 import Container from '../Container';
 import Conversation from '../Conversation';
+import TockAccessibility from "../../TockAccessibility";
 
 export interface ChatProps {
   endPoint: string;
@@ -12,6 +13,7 @@ export interface ChatProps {
   widgets?: any;
   extraHeadersProvider?: () => Promise<Record<string, string>>;
   disableSse?: boolean;
+  accessibility?: TockAccessibility;
 }
 
 const Chat: (props: ChatProps) => JSX.Element = ({
@@ -22,6 +24,7 @@ const Chat: (props: ChatProps) => JSX.Element = ({
   widgets = {},
   extraHeadersProvider = undefined,
   disableSse = false,
+  accessibility = {},
 }: ChatProps) => {
   const {
     messages,
@@ -58,8 +61,9 @@ const Chat: (props: ChatProps) => JSX.Element = ({
         quickReplies={quickReplies}
         onAction={sendAction}
         onQuickReplyClick={sendQuickReply}
+        accessibility={accessibility}
       />
-      <ChatInput disabled={sseInitializing} onSubmit={sendMessage} />
+      <ChatInput disabled={sseInitializing} onSubmit={sendMessage} accessibility={accessibility}/>
     </Container>
   );
 };

src/components/ChatInput/ChatInput.tsx

@@ -11,6 +11,7 @@ import { Send, Trash2 } from 'react-feather';
 import TockTheme from 'styles/theme';
 import { prop } from 'styled-tools';
 import useLocalTools, { UseLocalTools } from '../../useLocalTools';
+import TockAccessibility from 'TockAccessibility';
 
 const InputOuterContainer: StyledComponent<
   DetailedHTMLProps<FormHTMLAttributes<HTMLFormElement>, HTMLFormElement>,
@@ -123,11 +124,13 @@ const ClearIcon: StyledComponent<
 export interface ChatInputProps {
   disabled?: boolean;
   onSubmit: (message: string) => void;
+  accessibility?: TockAccessibility;
 }
 
 const ChatInput: (props: ChatInputProps) => JSX.Element = ({
   disabled,
   onSubmit,
+  accessibility,
 }: ChatInputProps): JSX.Element => {
   const { clearMessages }: UseLocalTools = useLocalTools();
   const [value, setValue] = useState('');
@@ -148,10 +151,10 @@ const ChatInput: (props: ChatInputProps) => JSX.Element = ({
         onChange={({ target: { value } }) => setValue(value)}
       />
       <SubmitIcon>
-        <Send size="100%" />
+        <Send size="100%" role='img' aria-label={accessibility?.sendButtonLabel || 'Send a message'} focusable='false' />
       </SubmitIcon>
       <ClearIcon>
-        <Trash2 size="25px" color={'white'} onClick={clearMessages} />
+        <Trash2 size="25px" color={'white'} onClick={clearMessages} role='img' aria-label={accessibility?.clearButtonLabel || 'Clear messages'} focusable='false' />
       </ClearIcon>
     </InputOuterContainer>
   );