Merge pull request #50 from reuters-graphics/scroller

Accessibility updates to Scroller

src/components/@types/global.ts

@@ -5,11 +5,11 @@ import type { ComponentType } from 'svelte';
  */
 export type ContainerWidth = 'narrower' | 'narrow' | 'normal' | 'wide' | 'wider' | 'widest' | 'fluid';
 
-
 /**
  * A step in the Scroller component.
  */
 export interface ScrollerStep {
+  altText?: string;
   /**
    * A background component
    * @required
@@ -19,7 +19,7 @@ export interface ScrollerStep {
    * Optional props for background component
    */
   backgroundProps?: Object;
-  /** 
+  /**
    * Foreground can either be a component or markdown-formatted string.
    * @required
    */

src/components/Scroller/Embedded/Background.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
   import type { ContainerWidth, ScrollerStep } from '../../@types/global';
-  
+
   export let step: ScrollerStep;
   export let backgroundWidth: ContainerWidth;
   export let index: number;
@@ -8,8 +8,8 @@
   import Block from '../../Block/Block.svelte';
 </script>
 
-<Block width={backgroundWidth} cls="background-container step-{index + 1}">
-  <div class="embedded-background step-{index + 1}">
+<Block width="{backgroundWidth}" cls="background-container step-{index + 1}">
+  <div class="embedded-background step-{index + 1}" aria-hidden="true">
     <svelte:component
       this="{step.background}"
       {...step.backgroundProps || {}}

src/components/Scroller/Embedded/Foreground.svelte

@@ -11,11 +11,23 @@
 {#if step.foreground === '' || !step.foreground}
   <!-- Empty foreground -->
   <div class="empty-step-foreground step-{index + 1}"></div>
+
+  {#if typeof step.altText === 'string'}
+    <div class="background-alt-text visually-hidden">
+      {@html marked.parse(step.altText)}
+    </div>
+  {/if}
 {:else if typeof step.foreground === 'string'}
   <Block cls="body-text step-{index + 1}">
     <div class="embedded-foreground step-{index + 1}">
       {@html marked.parse(step.foreground)}
     </div>
+
+    {#if typeof step.altText === 'string'}
+      <div class="background-alt-text visually-hidden">
+        {@html marked.parse(step.altText)}
+      </div>
+    {/if}
   </Block>
 {:else}
   <div class="embedded-foreground step-{index + 1}">
@@ -27,7 +39,7 @@
 {/if}
 
 <style lang="scss">
-  @import "./../../../scss/mixins";
+  @import './../../../scss/mixins';
   div.embedded-foreground {
     :global {
       @include body-text;
@@ -36,4 +48,8 @@
       margin-bottom: 0;
     }
   }
+
+  .visually-hidden {
+    @include visually-hidden;
+  }
 </style>

src/components/Scroller/Foreground.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import type { ScrollerStep } from  '../@types/global';
+  import type { ScrollerStep } from '../@types/global';
 
   export let steps: ScrollerStep[] = [];
 
@@ -11,6 +11,11 @@
     {#if step.foreground === '' || !step.foreground}
       <!-- Empty foreground -->
       <div class="empty-step-foreground"></div>
+      {#if typeof step.altText === 'string'}
+        <div class="background-alt-text visually-hidden">
+          {@html marked.parse(step.altText)}
+        </div>
+      {/if}
     {:else}
       <div class="step-foreground">
         {#if typeof step.foreground === 'string'}
@@ -22,11 +27,18 @@
           />
         {/if}
       </div>
+      {#if typeof step.altText === 'string'}
+        <div class="background-alt-text visually-hidden">
+          {@html marked.parse(step.altText)}
+        </div>
+      {/if}
     {/if}
   </div>
 {/each}
 
 <style lang="scss">
+  @import './../../scss/mixins';
+
   div.step-foreground-container {
     height: 100vh;
     width: initial;
@@ -45,4 +57,8 @@
       }
     }
   }
+
+  .visually-hidden {
+    @include visually-hidden;
+  }
 </style>

src/components/Scroller/Scroller.stories.svelte

@@ -38,9 +38,22 @@
     ID: 'my-scroller',
     StackBackground: 'true',
     Steps: [
-      { Background: 'AiMap1', Text: '#### Step 1\n\nLorem ipsum' },
-      { Background: 'AiMap2', Text: '#### Step 2\n\nLorem ipsum' },
-      { Background: 'AiMap3', Text: '#### Step 3\n\nLorem ipsum' },
+      {
+        Background: 'AiMap1',
+        Text: '#### Step 1\n\nLorem ipsum',
+        AltText: 'A map showing the Upper West side in New York City.',
+      },
+      {
+        Background: 'AiMap2',
+        Text: '#### Step 2\n\nLorem ipsum',
+        AltText: 'The same map now highlights 98th Street.',
+      },
+      {
+        Background: 'AiMap3',
+        Text: '#### Step 3\n\nLorem ipsum',
+        AltText:
+          'The same map now highlights three locations near 98th Street where something particulary important happened.',
+      },
     ],
   };
 
@@ -80,16 +93,19 @@
         background: BasicStep,
         backgroundProps: { colour: 'red' },
         foreground: '#### Step 1\n\nLorem ipsum red',
+        altText: 'Red background',
       },
       {
         background: BasicStep,
         backgroundProps: { colour: 'blue' },
         foreground: '#### Step 2\n\nLorem ipsum blue',
+        altText: 'Blue background',
       },
       {
         background: BasicStep,
         backgroundProps: { colour: 'green' },
         foreground: '#### Step 3\n\nLorem ipsum green',
+        altText: 'Green background',
       },
     ],
     foregroundPosition: 'middle',
@@ -142,16 +158,21 @@
         background: AiMap1,
         backgroundProps: { colour: 'red' },
         foreground: '#### Step 1\n\nLorem ipsum',
+        altText: 'A map showing the Upper West side in New York City.',
       },
       {
         background: AiMap2,
         backgroundProps: { colour: 'blue' },
         foreground: '#### Step 2\n\nLorem ipsum',
+        altText:
+          'The same map now highlights 98th Street where something interesting happened.',
       },
       {
         background: AiMap3,
         backgroundProps: { colour: 'green' },
         foreground: '#### Step 3\n\nLorem ipsum',
+        altText:
+          'The same map now highlights three locations near 98th Street where something particulary important happened.',
       },
     ],
     foregroundPosition: 'middle',

src/components/Scroller/Scroller.svelte

@@ -12,9 +12,10 @@
    *
    * Each step object in the array can have:
    *
-   * - `background` A background component **REQUIRED**
+   * - `background` A background component. **REQUIRED**
    * - `backgroundProps` An object of props given to the background component
    * - `foreground` Either a markdown-formatted string or a foreground component **REQUIRED**
+   * - `altText` A string describing the background graphic, which is read aloud after the foreground blurb. You can add it to each step or, if you want to add just one alt text to describe all graphics in the scroll section, add it to just the first step. **RECOMMENDED**
    * - `foregroundProps` An object of props given to the foreground component
    *
    * @required
@@ -116,6 +117,7 @@
         class="background"
         class:right="{foregroundPosition === 'left opposite'}"
         class:left="{foregroundPosition === 'right opposite'}"
+        aria-hidden="true"
       >
         <div class="scroller-graphic-well">
           <Block

src/components/Scroller/docProps.ts

@@ -1,6 +1,7 @@
 import type { ComponentType } from 'svelte';
 
 interface BlockStep {
+  AltText?: string;
   Background: string;
   Text: string;
 }
@@ -30,6 +31,7 @@ export const getScrollerPropsFromDoc = (docBlock: Block, aiCharts: AiCharts, ass
       background: aiCharts[step.Background],
       backgroundProps: { assetsPath },
       foreground: step.Text,
+      altText: step.AltText,
     })),
   };
 };

src/components/Scroller/stories/docs/ai2svelte.md

@@ -15,16 +15,19 @@ A more detailed example of using `Scroller` with graphics created by [ai2svelte]
       background: MyAiMap1,
       backgroundProps: { assetsPath: assets },
       foreground: '#### Step 1\n\nLorem ipsum',
+      altText: 'A map showing TKTK',
     },
     {
       background: MyAiMap2,
       backgroundProps: { assetsPath: assets },
       foreground: '#### Step 2\n\nLorem ipsum',
+      altText: 'The same map now highlights something interesting.',
     },
     {
       background: MyAiMap3,
       backgroundProps: { assetsPath: assets },
       foreground: '#### Step 3\n\nLorem ipsum',
+      altText: 'The same map now shows something else that is interesting.',
     },
   ];
 </script>
@@ -48,14 +51,22 @@ Step1Text: #### Step 1
 
 Lorem Ipsum
 :end
+AltText1: A map showing the Upper West side in New York City.
+:end
+
 Step2Text: #### Step 2
 
 Lorem Ipsum
 :end
+AltText2: The same map now highlights 98th Street.
+:end
+
 Step3Text: #### Step 3
 
 Lorem Ipsum
 :end
+AltText3: The same map now highlights three locations near 98th Street where something particulary important happened.
+:end
 ```
 
 ```svelte
@@ -77,16 +88,19 @@ Lorem Ipsum
       background: MyAiMap1,
       backgroundProps: { basePath: assets },
       foreground: scrollerBlock.Step1Text,
+      altText: scrollerBlock.AltText1,
     },
     {
       background: MyAiMap2,
       backgroundProps: { basePath: assets },
       foreground: scrollerBlock.Step2Text,
+      altText: scrollerBlock.AltText2,
     },
     {
       background: MyAiMap3,
       backgroundProps: { basePath: assets },
       foreground: scrollerBlock.Step3Text,
+      altText: scrollerBlock.AltText3,
     },
   ];
 </script>

src/components/Scroller/stories/docs/component.md

@@ -11,17 +11,31 @@ Check out the "Canvas" tab to play with the layout options available on this com
   import MyColourBackground from './MyColourBackground.svelte';
 
   const steps = [
-    { background: MyColourBackground, backgroundProps: { colour: 'red' }, foreground: '#### Step 1\n\nLorem ipsum red' },
-    { background: MyColourBackground, backgroundProps: { colour: 'blue' }, foreground: '#### Step 2\n\nLorem ipsum blue' },
-    { background: MyColourBackground, backgroundProps: { colour: 'green' }, foreground: '#### Step 3\n\nLorem ipsum green' },
-  ]
+    {
+      background: MyColourBackground,
+      backgroundProps: { colour: 'red' },
+      foreground: '#### Step 1\n\nLorem ipsum red',
+      altText: 'Red background',
+    },
+    {
+      background: MyColourBackground,
+      backgroundProps: { colour: 'blue' },
+      foreground: '#### Step 2\n\nLorem ipsum blue',
+      altText: 'Blue background',
+    },
+    {
+      background: MyColourBackground,
+      backgroundProps: { colour: 'green' },
+      foreground: '#### Step 3\n\nLorem ipsum green',
+      altText: 'Green background',
+    },
+  ];
 </script>
 
-
 <Scroller
   steps="{steps}"
   backgroundWidth="fluid"
   foregroundPosition="middle"
-  embedded={false}
+  embedded="{false}"
 />
 ```

src/components/Scroller/stories/docs/interactive.md

@@ -1,22 +1,36 @@
 Instead of just text, you can use any component in the foreground, too, and pass whatever props you need to it.
 
+If you're making your own custom foreground component, remember to add alt text describing the background graphic.
+
 ```svelte
 <script>
   // ...
   import MyCounter from './MyCounter.svelte';
 
   const steps = [
-    { background: MyColourBackground, backgroundProps: { colour: 'red' }, foreground: MyCounter },
-    { background: MyColourBackground, backgroundProps: { colour: 'blue' }, foreground: '#### Step 2\n\nLorem ipsum blue' },
-    { background: MyColourBackground, backgroundProps: { colour: 'green' }, foreground: MyCounter, foregroundProps: { count: 100 } },
-  ]
+    {
+      background: MyColourBackground,
+      backgroundProps: { colour: 'red' },
+      foreground: MyCounter,
+    },
+    {
+      background: MyColourBackground,
+      backgroundProps: { colour: 'blue' },
+      foreground: '#### Step 2\n\nLorem ipsum blue',
+    },
+    {
+      background: MyColourBackground,
+      backgroundProps: { colour: 'green' },
+      foreground: MyCounter,
+      foregroundProps: { count: 100 },
+    },
+  ];
 </script>
 
-
 <Scroller
   steps="{steps}"
   backgroundWidth="fluid"
   foregroundPosition="middle"
-  embedded={false}
+  embedded="{false}"
 />
 ```

src/components/Scroller/stories/docs/quickit.md

@@ -35,18 +35,26 @@ StackBackground: true
 
   Lorem ipsum
   :end
+  AltText: A map showing the Upper West side in New York City.
+
+  Can add paragraphs of alt text if you want to break up sentences.
+  :end
 
   Background: AiMap2
   Text: #### Step 2
 
   Lorem ipsum
   :end
+  AltText: The same map now highlights 98th Street.
+  :end
 
   Background: AiMap3
   Text: #### Step 3
 
   Lorem ipsum
   :end
+  AltText: The same map now highlights three locations near 98th Street where something particulary important happened.
+  :end
 []
 
 ```