From 710c2942fa8bd589192d3b6f8d855e408824ac7a Mon Sep 17 00:00:00 2001
From: MinamiFunakoshiTR <minami.funakoshi@thomsonreuters.com>
Date: Wed, 18 Jan 2023 11:46:10 -0600
Subject: [PATCH] hides bg from SR, adds alt text, updates docs

---
 src/components/@types/global.ts               |  4 +--
 .../Scroller/Embedded/Background.svelte       |  6 ++---
 .../Scroller/Embedded/Foreground.svelte       | 14 +++++++++-
 src/components/Scroller/Foreground.svelte     | 14 +++++++++-
 .../Scroller/Scroller.stories.svelte          | 27 ++++++++++++++++---
 src/components/Scroller/Scroller.svelte       |  4 ++-
 src/components/Scroller/docProps.ts           |  2 ++
 .../Scroller/stories/docs/ai2svelte.md        | 12 +++++++++
 .../Scroller/stories/docs/component.md        | 26 +++++++++++++-----
 .../Scroller/stories/docs/interactive.md      | 26 +++++++++++++-----
 .../Scroller/stories/docs/quickit.md          |  4 +++
 11 files changed, 116 insertions(+), 23 deletions(-)

diff --git a/src/components/@types/global.ts b/src/components/@types/global.ts
index 918a739f..e76ba307 100644
--- a/src/components/@types/global.ts
+++ b/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
    */
diff --git a/src/components/Scroller/Embedded/Background.svelte b/src/components/Scroller/Embedded/Background.svelte
index f776f259..8081ba70 100644
--- a/src/components/Scroller/Embedded/Background.svelte
+++ b/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 || {}}
diff --git a/src/components/Scroller/Embedded/Foreground.svelte b/src/components/Scroller/Embedded/Foreground.svelte
index 23936cd3..ae3b6c37 100644
--- a/src/components/Scroller/Embedded/Foreground.svelte
+++ b/src/components/Scroller/Embedded/Foreground.svelte
@@ -11,11 +11,19 @@
 {#if step.foreground === '' || !step.foreground}
   <!-- Empty foreground -->
   <div class="empty-step-foreground step-{index + 1}"></div>
+
+  {#if typeof step.altText === 'string'}
+    <p class="background-alt-text visually-hidden">{step.altText}</p>
+  {/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'}
+      <p class="background-alt-text visually-hidden">{step.altText}</p>
+    {/if}
   </Block>
 {:else}
   <div class="embedded-foreground step-{index + 1}">
@@ -27,7 +35,7 @@
 {/if}
 
 <style lang="scss">
-  @import "./../../../scss/mixins";
+  @import './../../../scss/mixins';
   div.embedded-foreground {
     :global {
       @include body-text;
@@ -36,4 +44,8 @@
       margin-bottom: 0;
     }
   }
+
+  .visually-hidden {
+    @include visually-hidden;
+  }
 </style>
diff --git a/src/components/Scroller/Foreground.svelte b/src/components/Scroller/Foreground.svelte
index 604b7934..a74e990b 100644
--- a/src/components/Scroller/Foreground.svelte
+++ b/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,9 @@
     {#if step.foreground === '' || !step.foreground}
       <!-- Empty foreground -->
       <div class="empty-step-foreground"></div>
+      {#if typeof step.altText === 'string'}
+        <p class="background-alt-text visually-hidden">{step.altText}</p>
+      {/if}
     {:else}
       <div class="step-foreground">
         {#if typeof step.foreground === 'string'}
@@ -22,11 +25,16 @@
           />
         {/if}
       </div>
+      {#if typeof step.altText === 'string'}
+        <p class="background-alt-text visually-hidden">{step.altText}</p>
+      {/if}
     {/if}
   </div>
 {/each}
 
 <style lang="scss">
+  @import './../../scss/mixins';
+
   div.step-foreground-container {
     height: 100vh;
     width: initial;
@@ -45,4 +53,8 @@
       }
     }
   }
+
+  .visually-hidden {
+    @include visually-hidden;
+  }
 </style>
diff --git a/src/components/Scroller/Scroller.stories.svelte b/src/components/Scroller/Scroller.stories.svelte
index 89c96317..73429e5e 100644
--- a/src/components/Scroller/Scroller.stories.svelte
+++ b/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',
diff --git a/src/components/Scroller/Scroller.svelte b/src/components/Scroller/Scroller.svelte
index cd9b0392..e4dc9dfb 100644
--- a/src/components/Scroller/Scroller.svelte
+++ b/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
diff --git a/src/components/Scroller/docProps.ts b/src/components/Scroller/docProps.ts
index 3c21394f..e16fec25 100644
--- a/src/components/Scroller/docProps.ts
+++ b/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,
     })),
   };
 };
diff --git a/src/components/Scroller/stories/docs/ai2svelte.md b/src/components/Scroller/stories/docs/ai2svelte.md
index 4ffba630..5bead0e3 100644
--- a/src/components/Scroller/stories/docs/ai2svelte.md
+++ b/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,20 @@ Step1Text: #### Step 1
 
 Lorem Ipsum
 :end
+AltText1: A map showing the Upper West side in New York City.
+
 Step2Text: #### Step 2
 
 Lorem Ipsum
 :end
+AltText2: The same map now highlights 98th Street.
+
 Step3Text: #### Step 3
 
 Lorem Ipsum
 :end
+AltText3: The same map now highlights three locations near 98th Street where something particulary important happened.
+
 ```
 
 ```svelte
@@ -77,16 +86,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>
diff --git a/src/components/Scroller/stories/docs/component.md b/src/components/Scroller/stories/docs/component.md
index e61a3dda..42cada93 100644
--- a/src/components/Scroller/stories/docs/component.md
+++ b/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}"
 />
 ```
diff --git a/src/components/Scroller/stories/docs/interactive.md b/src/components/Scroller/stories/docs/interactive.md
index c7d4a003..1586b2d1 100644
--- a/src/components/Scroller/stories/docs/interactive.md
+++ b/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}"
 />
 ```
diff --git a/src/components/Scroller/stories/docs/quickit.md b/src/components/Scroller/stories/docs/quickit.md
index b3438765..b6b02189 100644
--- a/src/components/Scroller/stories/docs/quickit.md
+++ b/src/components/Scroller/stories/docs/quickit.md
@@ -35,18 +35,22 @@ StackBackground: true
 
   Lorem ipsum
   :end
+  AltText: A map showing the Upper West side in New York City.
 
   Background: AiMap2
   Text: #### Step 2
 
   Lorem ipsum
   :end
+  AltText: The same map now highlights 98th Street.
 
   Background: AiMap3
   Text: #### Step 3
 
   Lorem ipsum
   :end
+  AltText: The same map now highlights three locations near 98th Street where something particulary important happened.
+
 []
 
 ```