From 36482a43131f467683fe7d1c5605cd38b60083f2 Mon Sep 17 00:00:00 2001
From: MinamiFunakoshiTR <minami.funakoshi@thomsonreuters.com>
Date: Thu, 13 Mar 2025 12:12:06 -0700
Subject: [PATCH] cleaned up docs

---
 src/components/BeforeAfter/BeforeAfter.mdx    | 112 ++++++++++--------
 .../BeforeAfter/BeforeAfter.stories.svelte    |  43 +------
 src/components/BeforeAfter/BeforeAfter.svelte |  16 ++-
 3 files changed, 72 insertions(+), 99 deletions(-)

diff --git a/src/components/BeforeAfter/BeforeAfter.mdx b/src/components/BeforeAfter/BeforeAfter.mdx
index dfb459f8..41529395 100644
--- a/src/components/BeforeAfter/BeforeAfter.mdx
+++ b/src/components/BeforeAfter/BeforeAfter.mdx
@@ -24,9 +24,46 @@ The `BeforeAfter` component shows a before-and-after comparison of an image.
 
 <Canvas of={BeforeAfterStories.Demo} />
 
-## Using with overlays
+## Using with ArchieML docs
 
-Add overlays with the `beforeOverlay` and `afterOverlay` slots and a caption to the `caption` slot, then style these elements to match your page design as below.
+With the Graphics Kit, you'll likely get your text value from an ArchieML doc...
+
+```yaml
+# ArchieML doc
+[blocks]
+
+type: before-after
+beforeSrc: images/before-after/myrne-before.jpg
+beforeAlt: Satellite image of Russian base at Myrne taken on July 7, 2020.
+afterSrc: images/before-after/myrne-after.jpg
+afterAlt: Satellite image of Russian base at Myrne taken on Oct. 20, 2020.
+
+[]
+```
+
+... which you'll parse out of a ArchieML block object before passing to the `BeforeAfter` component.
+
+```svelte
+<!-- App.svelte -->
+{#each content.blocks as block}
+  {#if block.type === 'before-after'}
+    <BeforeAfter
+      beforeSrc={`${assets}/${block.beforeSrc}`}
+      beforeAlt={block.beforeAlt}
+      afterSrc={`${assets}/${block.afterSrc}`}
+      afterAlt={block.afterAlt}
+    />
+  {/if}
+{/each}
+```
+
+<Canvas of={BeforeAfterStories.Demo} />
+
+## Adding text
+
+To add text overlays and captions, use [snippets](https://svelte.dev/docs/svelte/snippet) for `beforeOverlay`, `afterOverlay` and `caption`. You can style these snippets to match your page design, like in [this demo](./?path=/story/components-multimedia-beforeafter--with-overlays).
+
+> 💡**NOTE:** The text in the overlays are used as [ARIA descriptions](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) for your before and after images. You must always use the `beforeAlt` / `afterAlt` props to label your image for visually impaired readers, but these ARIA descriptions provide additional information or context that the reader might need.
 
 ```svelte
 <BeforeAfter
@@ -35,15 +72,26 @@ Add overlays with the `beforeOverlay` and `afterOverlay` slots and a caption to
   afterSrc={afterImg}
   afterAlt="Satellite image of Russian base at Myrne taken on Oct. 20, 2020."
 >
-  <div slot="beforeOverlay" class="overlay p-3 before">
-    <p class="h4 font-bold">July 7, 2020</p>
-    <p class="body-note">Initially, this site was far smaller.</p>
-  </div>
-  <div slot="afterOverlay" class="overlay p-3 after">
-    <p class="h4 font-bold">Oct. 20, 2020</p>
-    <p class="body-note">But then forces built up.</p>
-  </div>
-  <p slot="caption">Photos by MAXAR Technologies, 2021.</p>
+  <!-- Optional custom text overlay for the before image -->
+  {#snippet beforeOverlay()}
+    <div class="overlay p-3 before text-left">
+      <p class="h4 font-bold">July 7, 2020</p>
+      <p class="body-note">Initially, this site was far smaller.</p>
+    </div>
+  {/snippet}
+
+  <!-- Optional custom text overlay for the after image -->
+  {#snippet afterOverlay()}
+    <div class="overlay p-3 after text-right">
+      <p class="h4 font-bold">Oct. 20, 2020</p>
+      <p class="body-note">But then forces built up.</p>
+    </div>
+  {/snippet}
+
+  <!-- Optional custom caption for both images -->
+  {#snippet caption()}
+    <p class="body-note">Photos by MAXAR Technologies, 2021.</p>
+  {/snippet}
 </BeforeAfter>
 
 <style lang="scss">
@@ -60,44 +108,4 @@ Add overlays with the `beforeOverlay` and `afterOverlay` slots and a caption to
 </style>
 ```
 
-<Canvas of={BeforeAfterStories.WithOverlays} />
-
-## Adding ARIA descriptions
-
-Use text elements in your overlays as [ARIA descriptions](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) for your images by setting an ID on text elements within each overlay with the `description` [slot prop](https://svelte.dev/tutorial/slot-props).
-
-> **💡 TIP:** You must always use the `beforeAlt` / `afterAlt` props to label your image for visually impaired readers, but you can use these descriptions to provide more information or context that the reader might also need.
-
-```svelte
-<BeforeAfter
-  beforeSrc={beforeImg}
-  beforeAlt="Satellite image of Russian base at Myrne taken on July 7, 2020."
-  afterSrc={afterImg}
-  afterAlt="Satellite image of Russian base at Myrne taken on Oct. 20, 2020."
->
-  <div slot="beforeOverlay" class="overlay p-3 before">
-    <p class="h4 font-bold">July 7, 2020</p>
-    <p class="body-note">Initially, this site was far smaller.</p>
-  </div>
-  <div slot="afterOverlay" class="overlay p-3 after">
-    <p class="h4 font-bold">Oct. 20, 2020</p>
-    <p class="body-note">But then forces built up.</p>
-  </div>
-  <p slot="caption">Photos by MAXAR Technologies, 2021.</p>
-</BeforeAfter>
-
-<style lang="scss">
-  .overlay {
-    background: rgba(0, 0, 0, 0.45);
-    max-width: 350px;
-    &.after {
-      text-align: right;
-    }
-    p {
-      color: #ffffff;
-    }
-  }
-</style>
-```
-
-<Canvas of={BeforeAfterStories.AriaDescriptions} />
+<Canvas of={BeforeAfterStories.WithText} />
diff --git a/src/components/BeforeAfter/BeforeAfter.stories.svelte b/src/components/BeforeAfter/BeforeAfter.stories.svelte
index 02a54187..74ef3be3 100644
--- a/src/components/BeforeAfter/BeforeAfter.stories.svelte
+++ b/src/components/BeforeAfter/BeforeAfter.stories.svelte
@@ -32,7 +32,7 @@
   }}
 />
 
-<Story name="With overlays" exportName="WithOverlays">
+<Story name="With text" exportName="WithText">
   <BeforeAfter
     beforeSrc={beforeImg}
     beforeAlt="Satellite image of Russian base at Myrne taken on July 7, 2020."
@@ -66,44 +66,3 @@
     }
   </style>
 </Story>
-
-<Story name="ARIA descriptions" exportName="AriaDescriptions">
-  <BeforeAfter
-    beforeSrc={beforeImg}
-    beforeAlt="Satellite image of Russian base at Myrne taken on July 7, 2020."
-    afterSrc={afterImg}
-    afterAlt="Satellite image of Russian base at Myrne taken on Oct. 20, 2020."
-  >
-    {#snippet beforeOverlay()}
-      <div class="overlay p-3 text-left">
-        <p class="body-caption" id="aria-description-before">
-          On July 7, 2020, the base contained only a few transport vehicles.
-        </p>
-      </div>
-    {/snippet}
-    {#snippet afterOverlay()}
-      <div class="overlay p-3 text-right">
-        <p class="body-caption" id="aria-description-after">
-          But by October, tanks and artillery could be seen.
-        </p>
-        <p class="body-caption">
-          In total, over 50 pieces of heavy machinery and 200 personnel are now
-          based here.
-        </p>
-      </div>
-    {/snippet}
-    {#snippet caption()}
-      <p class="body-note">Photos by MAXAR Technologies, 2021.</p>
-    {/snippet}
-  </BeforeAfter>
-
-  <style lang="scss">
-    div.overlay {
-      max-width: 250px;
-      background: rgba(0, 0, 0, 0.45);
-      p {
-        color: #ffffff;
-      }
-    }
-  </style>
-</Story>
diff --git a/src/components/BeforeAfter/BeforeAfter.svelte b/src/components/BeforeAfter/BeforeAfter.svelte
index 23621bfc..f7f8b976 100644
--- a/src/components/BeforeAfter/BeforeAfter.svelte
+++ b/src/components/BeforeAfter/BeforeAfter.svelte
@@ -197,7 +197,7 @@
         ontouchstart={start}
         onmousedown={start}
         bind:this={figure}
-        aria-labelledby={(caption && `${id}-caption`) || ''}
+        aria-labelledby={(caption && `${id}-caption-description`) || undefined}
       >
         <img
           bind:this={img}
@@ -206,18 +206,21 @@
           onload={measureLoadedImage}
           style={imgStyle}
           class="after absolute block m-0 max-w-full object-cover"
-          aria-describedby={(beforeOverlay && `${id}-before`) || ''}
+          aria-describedby={(beforeOverlay && `${id}-before-description`) ||
+            undefined}
         />
+
         <img
           src={beforeSrc}
           alt={beforeAlt}
           style="clip: rect(0 {x}px {containerHeight}px 0);{imgStyle}"
           class="before absolute block m-0 max-w-full object-cover"
-          aria-describedby={(afterOverlay && `${id}-after`) || ''}
+          aria-describedby={(afterOverlay && `${id}-after-description`) ||
+            undefined}
         />
         {#if beforeOverlay}
           <div
-            id="image-before-label"
+            id="{id}-before-description"
             class="overlay-container before absolute"
             bind:clientWidth={beforeOverlayWidth}
             style="clip-path: inset(0 {beforeOverlayClip}px 0 0);"
@@ -227,7 +230,10 @@
           </div>
         {/if}
         {#if afterOverlay}
-          <div id="image-after-label" class="overlay-container after absolute">
+          <div
+            id="{id}-after-description"
+            class="overlay-container after absolute"
+          >
             <!-- Overlay for after image -->
             {@render afterOverlay()}
           </div>