From 221bb70a000be94b4daeddd9f1ba132141d68b6d Mon Sep 17 00:00:00 2001
From: MinamiFunakoshiTR <minami.funakoshi@thomsonreuters.com>
Date: Wed, 12 Mar 2025 15:53:46 -0700
Subject: [PATCH 01/12] svelte 5 set up but before/after not quite working

---
 src/components/BeforeAfter/BeforeAfter.mdx    | 103 +++++++
 .../BeforeAfter/BeforeAfter.stories.svelte    |  51 ++--
 src/components/BeforeAfter/BeforeAfter.svelte | 256 +++++++++---------
 .../{stories => images}/myrne-after.jpg       | Bin
 .../{stories => images}/myrne-before.jpg      | Bin
 .../stories/docs/ariaDescriptions.md          |  35 ---
 .../BeforeAfter/stories/docs/component.md     |  15 -
 .../BeforeAfter/stories/docs/withOverlays.md  |  33 ---
 src/components/Byline/Byline.svelte           |  14 +-
 9 files changed, 258 insertions(+), 249 deletions(-)
 create mode 100644 src/components/BeforeAfter/BeforeAfter.mdx
 rename src/components/BeforeAfter/{stories => images}/myrne-after.jpg (100%)
 rename src/components/BeforeAfter/{stories => images}/myrne-before.jpg (100%)
 delete mode 100644 src/components/BeforeAfter/stories/docs/ariaDescriptions.md
 delete mode 100644 src/components/BeforeAfter/stories/docs/component.md
 delete mode 100644 src/components/BeforeAfter/stories/docs/withOverlays.md

diff --git a/src/components/BeforeAfter/BeforeAfter.mdx b/src/components/BeforeAfter/BeforeAfter.mdx
new file mode 100644
index 00000000..dfb459f8
--- /dev/null
+++ b/src/components/BeforeAfter/BeforeAfter.mdx
@@ -0,0 +1,103 @@
+import { Meta, Canvas } from '@storybook/blocks';
+
+import * as BeforeAfterStories from './BeforeAfter.stories.svelte';
+
+<Meta of={BeforeAfterStories} />
+
+# BeforeAfter
+
+The `BeforeAfter` component shows a before-and-after comparison of an image.
+
+```svelte
+<script>
+  import { BeforeAfter } from '@reuters-graphics/graphics-components';
+  import { assets } from '$app/paths'; // If using in the Graphics Kit
+</script>
+
+<BeforeAfter
+  beforeSrc={`${assets}/images/before-after/myrne-before.jpg`}
+  beforeAlt="Satellite image of Russian base at Myrne taken on July 7, 2020."
+  afterSrc={`${assets}/images/before-after/myrne-after.jpg`}
+  afterAlt="Satellite image of Russian base at Myrne taken on Oct. 20, 2020."
+/>
+```
+
+<Canvas of={BeforeAfterStories.Demo} />
+
+## Using with overlays
+
+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.
+
+```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.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} />
diff --git a/src/components/BeforeAfter/BeforeAfter.stories.svelte b/src/components/BeforeAfter/BeforeAfter.stories.svelte
index d2f79821..4b4ed935 100644
--- a/src/components/BeforeAfter/BeforeAfter.stories.svelte
+++ b/src/components/BeforeAfter/BeforeAfter.stories.svelte
@@ -1,19 +1,10 @@
-<!-- @migration-task Error while migrating Svelte code: end is out of bounds -->
-<script context="module" lang="ts">
+<script module lang="ts">
+  import { defineMeta } from '@storybook/addon-svelte-csf';
   import BeforeAfter from './BeforeAfter.svelte';
-  // @ts-ignore raw
-  import componentDocs from './stories/docs/component.md?raw';
-  // @ts-ignore raw
-  import withOverlaysDocs from './stories/docs/withOverlays.md?raw';
-  // @ts-ignore raw
-  import ariaDescriptionsDocs from './stories/docs/ariaDescriptions.md?raw';
 
-  import { withComponentDocs, withStoryDocs } from '$docs/utils/withParams.js';
-
-  export const meta = {
+  const { Story } = defineMeta({
     title: 'Components/Graphics/BeforeAfter',
     component: BeforeAfter,
-    ...withComponentDocs(componentDocs),
     argTypes: {
       handleColour: { control: 'color' },
       width: {
@@ -21,39 +12,31 @@
         options: ['normal', 'wide', 'wider', 'widest', 'fluid'],
       },
     },
-  };
+  });
 </script>
 
 <script>
-  import { Template, Story } from '@storybook/addon-svelte-csf';
-
-  // @ts-ignore raw
-  import beforeImg from './stories/myrne-before.jpg';
-  // @ts-ignore raw
-  import afterImg from './stories/myrne-after.jpg';
+  import beforeImg from './images/myrne-before.jpg';
+  import afterImg from './images/myrne-after.jpg';
 </script>
 
-<Template let:args>
-  <BeforeAfter {...args} />
-</Template>
-
 <Story
-  name="Default"
-  args="{{
+  name="Demo"
+  args={{
     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.',
-  }}"
+  }}
 />
 
-<Story name="With overlays" {...withStoryDocs(withOverlaysDocs)}>
+<Story name="With overlays" exportName="WithOverlays">
   <BeforeAfter
-    beforeSrc="{beforeImg}"
+    beforeSrc={beforeImg}
     beforeAlt="Satellite image of Russian base at Myrne taken on July 7, 2020."
-    afterSrc="{afterImg}"
+    afterSrc={afterImg}
     afterAlt="Satellite image of Russian base at Myrne taken on Oct. 20, 2020."
   >
     <div slot="beforeOverlay" class="overlay p-3 before">
@@ -81,19 +64,19 @@
   </style>
 </Story>
 
-<Story name="ARIA descriptions" {...withStoryDocs(ariaDescriptionsDocs)}>
+<Story name="ARIA descriptions" exportName="AriaDescriptions">
   <BeforeAfter
-    beforeSrc="{beforeImg}"
+    beforeSrc={beforeImg}
     beforeAlt="Satellite image of Russian base at Myrne taken on July 7, 2020."
-    afterSrc="{afterImg}"
+    afterSrc={afterImg}
     afterAlt="Satellite image of Russian base at Myrne taken on Oct. 20, 2020."
   >
-    <div let:description="{id}" slot="beforeOverlay" class="overlay p-3">
+    <div let:description={id} slot="beforeOverlay" class="overlay p-3">
       <p class="body-caption" {id}>
         On July 7, 2020, the base contained only a few transport vehicles.
       </p>
     </div>
-    <div let:description="{id}" slot="afterOverlay" class="overlay p-3">
+    <div let:description={id} slot="afterOverlay" class="overlay p-3">
       <!-- 👇 id can also be used on an element containing multiple text elements -->
       <div {id}>
         <p class="body-caption">
diff --git a/src/components/BeforeAfter/BeforeAfter.svelte b/src/components/BeforeAfter/BeforeAfter.svelte
index e6229af5..293bb582 100644
--- a/src/components/BeforeAfter/BeforeAfter.svelte
+++ b/src/components/BeforeAfter/BeforeAfter.svelte
@@ -1,73 +1,92 @@
-<!-- @migration-task Error while migrating Svelte code: Cannot set properties of undefined (setting 'next') -->
 <!-- @component `BeforeAfter` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-graphics-beforeafter--docs) -->
 <script lang="ts">
+  import { onMount, type Snippet } from 'svelte';
   import { throttle } from 'lodash-es';
-  import { onMount } from 'svelte';
+
   import Block from '../Block/Block.svelte';
-  import type { ContainerWidth } from '../@types/global';
   import PaddingReset from '../PaddingReset/PaddingReset.svelte';
+  import type { ContainerWidth } from '../@types/global';
 
-  /** Width of the chart within the text well. */
-  export let width: ContainerWidth = 'normal'; // options: wide, wider, widest, fluid
-  /** Height of the component */
-  export let height = 600;
-
-  /**
-   * If set, makes the height a ratio of the component's width.
-   * @type {number}
-   */
-  export let heightRatio: number | null = null;
-
-  /**
-   * Before image src
-   * @required
-   */
-  export let beforeSrc: string | null = null;
-  /**
-   * Before image altText
-   * @required
-   */
-  export let beforeAlt: string | null = null;
-  /**
-   * After image src
-   * @required
-   */
-  export let afterSrc: string | null = null;
-  /**
-   * After image altText
-   * @required
-   */
-  export let afterAlt: string | null = null;
-
-  /**
-   * Set a class to target with SCSS.
-   * @type {string}
-   */
-  let cls: string = '';
-  export { cls as class };
-
-  /** Drag handle colour */
-  export let handleColour = 'white';
-  /** Drag handle opacity */
-  export let handleInactiveOpacity = 0.9;
-  /** Margin at the edge of the image to stop dragging */
-  export let handleMargin = 20;
-  /** Percentage of the component width the handle will travel ona key press */
-  export let keyPressStep = 0.05;
-
-  /** Initial offset of the handle, between 0 and 1. */
-  export let offset = 0.5;
-
+  /** Helper function to generate a random 4-character string */
   const random4 = () =>
     Math.floor((1 + Math.random()) * 0x10000)
       .toString(16)
       .substring(1);
 
-  /**
-   * Add an ID to target with SCSS.
-   * @type {string}
-   */
-  export let id: string = 'before-after-' + random4() + random4();
+  interface Props {
+    /** Width of the chart within the text well. Options: wide, wider, widest, fluid */
+    width?: ContainerWidth;
+    /** Height of the component */
+    height?: number;
+    /**
+     * If set, makes the height a ratio of the component's width.
+     */
+    heightRatio?: number;
+    /**
+     * Before image source
+     */
+    beforeSrc: string;
+    /**
+     * Before image altText
+     */
+    beforeAlt: string;
+    /**
+     * After image source
+     */
+    afterSrc: string;
+    /**
+     * After image altText
+     */
+    afterAlt: string;
+    /**
+     * Class to target with SCSS.
+     */
+    class?: string;
+    /** Drag handle colour */
+    handleColour?: string;
+    /** Drag handle opacity */
+    handleInactiveOpacity?: number;
+    /** Margin at the edge of the image to stop dragging */
+    handleMargin?: number;
+    /** Percentage of the component width the handle will travel ona key press */
+    keyPressStep?: number;
+    /** Initial offset of the handle, between 0 and 1. */
+    offset?: number;
+    /** ID to target with SCSS. */
+    id?: string;
+    /**
+     * Optional snippet for a custom overlay for the before image.
+     */
+    beforeOverlay?: Snippet;
+    /**
+     * Optional snippet for a custom overlay for the after image.
+     */
+    afterOverlay?: Snippet;
+    /**
+     * Optional snippet for a custom caption.
+     */
+    caption?: Snippet;
+  }
+
+  let {
+    width = 'normal',
+    height = 600,
+    heightRatio,
+    beforeSrc,
+    beforeAlt,
+    afterSrc,
+    afterAlt,
+    class: cls = '',
+    handleColour = 'white',
+    handleInactiveOpacity = 0.9,
+    handleMargin = 20,
+    keyPressStep = 0.05,
+    offset = 0.5,
+    id = 'before-after-' + random4() + random4(),
+    beforeOverlay,
+    afterOverlay,
+    caption,
+  }: Props = $props();
 
   let img: HTMLImageElement;
   let imgOffset: DOMRect | null = null;
@@ -77,21 +96,23 @@
   let isFocused = false;
   let containerWidth: number;
 
-  $: containerHeight =
-    containerWidth && heightRatio ? containerWidth * heightRatio : height;
+  let containerHeight = $derived(
+    containerWidth && heightRatio ? containerWidth * heightRatio : height
+  );
 
-  $: w = (imgOffset && imgOffset.width) || 0;
-  $: x = w * offset;
-  $: figStyle = `width:100%;height:${containerHeight}px;`;
-  $: imgStyle = 'width:100%;height:100%;';
-  $: beforeOverlayClip =
-    x < beforeOverlayWidth ? Math.abs(x - beforeOverlayWidth) : 0;
+  let w = $derived((imgOffset && imgOffset.width) || 0);
+  let x = $derived(w * offset);
+  let figStyle = $derived(`width:100%;height:${containerHeight}px;`);
+  const imgStyle = 'width:100%;height:100%;';
+  let beforeOverlayClip = $derived(
+    x < beforeOverlayWidth ? Math.abs(x - beforeOverlayWidth) : 0
+  );
 
-  const onFocus = () => (isFocused = true);
-  const onBlur = () => (isFocused = false);
+  const onfocus = () => (isFocused = true);
+  const onblur = () => (isFocused = false);
   const handleKeyDown = (e: KeyboardEvent) => {
     if (!isFocused) return;
-    const { keyCode } = e;
+    const { keyCode } = e; // DEPRECATED, change to key or code tk
     const margin = handleMargin / w;
     if (keyCode === 39) {
       offset = Math.min(1 - margin, offset + keyPressStep);
@@ -134,14 +155,11 @@
     sliding = true;
     move(e);
   };
+
   const end = () => {
     sliding = false;
   };
 
-  if (!(beforeSrc && beforeAlt && afterSrc && afterAlt)) {
-    console.warn('Missing required src or alt props for BeforeAfter component');
-  }
-
   onMount(() => {
     // This is necessary b/c on:load doesn't reliably fire on the image...
     const interval = setInterval(() => {
@@ -152,93 +170,83 @@
 </script>
 
 <svelte:window
-  on:touchmove="{move}"
-  on:touchend="{end}"
-  on:mousemove="{move}"
-  on:mouseup="{end}"
-  on:resize="{throttle(resize, 100)}"
-  on:keydown="{handleKeyDown}"
+  on:touchmove={move}
+  on:touchend={end}
+  on:mousemove={move}
+  on:mouseup={end}
+  on:resize={throttle(resize, 100)}
+  on:keydown={handleKeyDown}
 />
 
 {#if beforeSrc && beforeAlt && afterSrc && afterAlt}
   <Block {width} {id} class="photo before-after fmy-6 {cls}">
-    <div
-      style="height: {containerHeight}px;"
-      bind:clientWidth="{containerWidth}"
-    >
-      <!-- svelte-ignore a11y-no-noninteractive-element-interactions -->
+    <div style="height: {containerHeight}px;" bind:clientWidth={containerWidth}>
+      <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
       <figure
-        style="{figStyle}"
+        style={figStyle}
         class="before-after-container relative overflow-hidden my-0 mx-auto"
-        on:touchstart="{start}"
-        on:mousedown="{start}"
-        bind:this="{figure}"
-        aria-labelledby="{($$slots.caption && `${id}-caption`) || undefined}"
+        ontouchstart={start}
+        onmousedown={start}
+        bind:this={figure}
+        aria-labelledby={(caption && `${id}-caption`) || undefined}
       >
+        <!-- onmousedown={start || (e) => e.preventDefault()} -->
         <img
-          bind:this="{img}"
-          src="{afterSrc}"
-          alt="{afterAlt}"
-          on:load="{measureLoadedImage}"
-          on:mousedown|preventDefault
-          style="{imgStyle}"
+          bind:this={img}
+          src={afterSrc}
+          alt={afterAlt}
+          onload={measureLoadedImage}
+          onmousedown={start}
+          style={imgStyle}
           class="after absolute block m-0 max-w-full object-cover"
-          aria-describedby="{($$slots.beforeOverlay && `${id}-before`) ||
-            undefined}"
+          aria-describedby={(beforeOverlay && `${id}-before`) || undefined}
         />
-
+        <!-- onmousedown={start || (e) => e.preventDefault()} -->
         <img
-          src="{beforeSrc}"
-          alt="{beforeAlt}"
-          on:mousedown|preventDefault
+          src={beforeSrc}
+          alt={beforeAlt}
+          onmousedown={start}
           style="clip: rect(0 {x}px {containerHeight}px 0);{imgStyle}"
           class="before absolute block m-0 max-w-full object-cover"
-          aria-describedby="{($$slots.afterOverlay && `${id}-after`) ||
-            undefined}"
+          aria-describedby={(afterOverlay && `${id}-after`) || undefined}
         />
-        {#if $$slots.beforeOverlay}
+        {#if beforeOverlay}
           <div
             id="image-before-label"
             class="overlay-container before absolute"
-            bind:clientWidth="{beforeOverlayWidth}"
+            bind:clientWidth={beforeOverlayWidth}
             style="clip-path: inset(0 {beforeOverlayClip}px 0 0);"
           >
             <!-- Overlay for before image -->
-            <slot
-              name="beforeOverlay"
-              description="{`${id}-before-description`}"
-            />
+            {@render beforeOverlay()}
           </div>
         {/if}
-        {#if $$slots.afterOverlay}
+        {#if afterOverlay}
           <div id="image-after-label" class="overlay-container after absolute">
             <!-- Overlay for after image -->
-            <slot
-              name="afterOverlay"
-              description="{`${id}-after-description`}"
-            />
+            {@render afterOverlay()}
           </div>
         {/if}
         <div
           tabindex="0"
           role="slider"
-          aria-valuenow="{Math.round(offset * 100)}"
+          aria-valuenow={Math.round(offset * 100)}
           class="handle"
           style="left: calc({offset *
             100}% - 20px); --before-after-handle-colour: {handleColour}; --before-after-handle-inactive-opacity: {handleInactiveOpacity};"
-          on:focus="{onFocus}"
-          on:blur="{onBlur}"
+          {onfocus}
+          {onblur}
         >
           <div class="arrow-left"></div>
           <div class="arrow-right"></div>
         </div>
       </figure>
     </div>
-    {#if $$slots.caption}
-      <PaddingReset containerIsFluid="{width === 'fluid'}">
-        <aside class="before-after-caption mx-auto" id="{`${id}-caption`}">
+    {#if caption}
+      <PaddingReset containerIsFluid={width === 'fluid'}>
+        <aside class="before-after-caption mx-auto" id={`${id}-caption`}>
           <!-- Caption for image credits -->
-          <slot name="caption" />
+          {@render caption()}
         </aside>
       </PaddingReset>
     {/if}
@@ -246,7 +254,7 @@
 {/if}
 
 <style lang="scss">
-  @use '../../scss/mixins' as *;
+  @use '../../scss/mixins' as mixins;
 
   figure.before-after-container {
     box-sizing: content-box;
@@ -339,7 +347,7 @@
 
   aside.before-after-caption {
     :global(p) {
-      @include body-caption;
+      @include mixins.body-caption;
     }
   }
 </style>
diff --git a/src/components/BeforeAfter/stories/myrne-after.jpg b/src/components/BeforeAfter/images/myrne-after.jpg
similarity index 100%
rename from src/components/BeforeAfter/stories/myrne-after.jpg
rename to src/components/BeforeAfter/images/myrne-after.jpg
diff --git a/src/components/BeforeAfter/stories/myrne-before.jpg b/src/components/BeforeAfter/images/myrne-before.jpg
similarity index 100%
rename from src/components/BeforeAfter/stories/myrne-before.jpg
rename to src/components/BeforeAfter/images/myrne-before.jpg
diff --git a/src/components/BeforeAfter/stories/docs/ariaDescriptions.md b/src/components/BeforeAfter/stories/docs/ariaDescriptions.md
deleted file mode 100644
index 7e87edd3..00000000
--- a/src/components/BeforeAfter/stories/docs/ariaDescriptions.md
+++ /dev/null
@@ -1,35 +0,0 @@
-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>
-```
diff --git a/src/components/BeforeAfter/stories/docs/component.md b/src/components/BeforeAfter/stories/docs/component.md
deleted file mode 100644
index 6998143a..00000000
--- a/src/components/BeforeAfter/stories/docs/component.md
+++ /dev/null
@@ -1,15 +0,0 @@
-A before and after image comparison component.
-
-```svelte
-<script>
-  import { BeforeAfter } from '@reuters-graphics/graphics-components';
-  import { assets } from '$app/paths'; // If using in the Graphics Kit
-</script>
-
-<BeforeAfter
-  beforeSrc="{`${assets}/images/before-after/myrne-before.jpg`}"
-  beforeAlt="Satellite image of Russian base at Myrne taken on July 7, 2020."
-  afterSrc="{`${assets}/images/before-after/myrne-after.jpg`}"
-  afterAlt="Satellite image of Russian base at Myrne taken on Oct. 20, 2020."
-/>
-```
diff --git a/src/components/BeforeAfter/stories/docs/withOverlays.md b/src/components/BeforeAfter/stories/docs/withOverlays.md
deleted file mode 100644
index 4a6028d6..00000000
--- a/src/components/BeforeAfter/stories/docs/withOverlays.md
+++ /dev/null
@@ -1,33 +0,0 @@
-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.
-
-```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>
-```
diff --git a/src/components/Byline/Byline.svelte b/src/components/Byline/Byline.svelte
index 62b1ff5d..37050af2 100644
--- a/src/components/Byline/Byline.svelte
+++ b/src/components/Byline/Byline.svelte
@@ -17,12 +17,10 @@
     publishTime: string;
     /**
      * Update time as a datetime string.
-     * @type {string}
      */
     updateTime: string;
     /**
      * Alignment of the byline.
-     * @type {string}
      */
     align?: 'left' | 'center';
     /**
@@ -42,16 +40,16 @@
     /**
      * Optional snippet for a custom byline.
      */
-    byline?: Snippet | null;
+    byline?: Snippet;
     /**
      * Optional snippet for a custom published dateline.
      */
     // Specify that this prop should have the type of a Svelte snippet, i.e. basic html
-    published?: Snippet | null;
+    published?: Snippet;
     /**
      * Optional snippet for a custom updated dateline.
      */
-    updated?: Snippet | null;
+    updated?: Snippet;
   }
 
   let {
@@ -65,9 +63,9 @@
       const authorSlug = slugify(author.trim(), { lower: true });
       return `https://www.reuters.com/authors/${authorSlug}/`;
     },
-    byline = null,
-    published = null,
-    updated = null,
+    byline,
+    published,
+    updated,
   }: Props = $props();
 
   let alignmentClass = $derived(align === 'left' ? 'text-left' : 'text-center');

From 5834fd30082bbdd749359448d7719731e4aedfd8 Mon Sep 17 00:00:00 2001
From: MinamiFunakoshiTR <minami.funakoshi@thomsonreuters.com>
Date: Wed, 12 Mar 2025 16:22:31 -0700
Subject: [PATCH 02/12] component working now, need sanity check for other
 svelte 5 updates

---
 .../BeforeAfter/BeforeAfter.stories.svelte    | 50 +++++++++++--------
 src/components/BeforeAfter/BeforeAfter.svelte | 26 ++++++----
 2 files changed, 47 insertions(+), 29 deletions(-)

diff --git a/src/components/BeforeAfter/BeforeAfter.stories.svelte b/src/components/BeforeAfter/BeforeAfter.stories.svelte
index 4b4ed935..5ba7b736 100644
--- a/src/components/BeforeAfter/BeforeAfter.stories.svelte
+++ b/src/components/BeforeAfter/BeforeAfter.stories.svelte
@@ -39,15 +39,21 @@
     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>
+    {#snippet beforeOverlay()}
+      <div 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>
+    {/snippet}
+    {#snippet afterOverlay()}
+      <div 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>
+    {/snippet}
+    {#snippet caption()}
+      <p class="body-note">Photos by MAXAR Technologies, 2021.</p>
+    {/snippet}
   </BeforeAfter>
 
   <style lang="scss">
@@ -71,15 +77,16 @@
     afterSrc={afterImg}
     afterAlt="Satellite image of Russian base at Myrne taken on Oct. 20, 2020."
   >
-    <div let:description={id} slot="beforeOverlay" class="overlay p-3">
-      <p class="body-caption" {id}>
-        On July 7, 2020, the base contained only a few transport vehicles.
-      </p>
-    </div>
-    <div let:description={id} slot="afterOverlay" class="overlay p-3">
-      <!-- 👇 id can also be used on an element containing multiple text elements -->
-      <div {id}>
-        <p class="body-caption">
+    {#snippet beforeOverlay()}
+      <div let:description={id} class="overlay p-3">
+        <p class="body-caption" {id}>
+          On July 7, 2020, the base contained only a few transport vehicles.
+        </p>
+      </div>
+    {/snippet}
+    {#snippet afterOverlay()}
+      <div let:description={id} class="overlay p-3">
+        <p class="body-caption" {id}>
           But by October, tanks and artillery could be seen.
         </p>
         <p class="body-caption">
@@ -87,9 +94,12 @@
           based here.
         </p>
       </div>
-    </div>
-    <p slot="caption">Photos by MAXAR Technologies, 2021.</p>
+    {/snippet}
+    {#snippet caption()}
+      <p class="body-note">Photos by MAXAR Technologies, 2021.</p>
+    {/snippet}
   </BeforeAfter>
+
   <style lang="scss">
     div.overlay {
       max-width: 250px;
diff --git a/src/components/BeforeAfter/BeforeAfter.svelte b/src/components/BeforeAfter/BeforeAfter.svelte
index 293bb582..a97a33a4 100644
--- a/src/components/BeforeAfter/BeforeAfter.svelte
+++ b/src/components/BeforeAfter/BeforeAfter.svelte
@@ -88,19 +88,23 @@
     caption,
   }: Props = $props();
 
-  let img: HTMLImageElement;
-  let imgOffset: DOMRect | null = null;
+  /** DOM nodes are undefined until the component is mounted — in other words, you should read it inside an effect or an event handler, but not during component initialisation.
+   */
+  let img: HTMLImageElement | undefined = $state(undefined);
+
+  /** Defaults with an empty DOMRect with all values set to 0 */
+  let imgOffset: DOMRect = $state(new DOMRect());
   let sliding = false;
-  let figure: HTMLElement;
-  let beforeOverlayWidth = 0;
+  let figure: HTMLElement | undefined = $state(undefined);
+  let beforeOverlayWidth = $state(0);
   let isFocused = false;
-  let containerWidth: number;
+  let containerWidth: number = $state(0); // check if this should be undefined
 
   let containerHeight = $derived(
     containerWidth && heightRatio ? containerWidth * heightRatio : height
   );
 
-  let w = $derived((imgOffset && imgOffset.width) || 0);
+  let w = $derived(imgOffset.width);
   let x = $derived(w * offset);
   let figStyle = $derived(`width:100%;height:${containerHeight}px;`);
   const imgStyle = 'width:100%;height:100%;';
@@ -110,13 +114,15 @@
 
   const onfocus = () => (isFocused = true);
   const onblur = () => (isFocused = false);
+
+  /** Handle left or right arrows being pressed */
   const handleKeyDown = (e: KeyboardEvent) => {
     if (!isFocused) return;
-    const { keyCode } = e; // DEPRECATED, change to key or code tk
+    const { code, key } = e;
     const margin = handleMargin / w;
-    if (keyCode === 39) {
+    if (code === 'ArrowRight' || key === 'ArrowRight') {
       offset = Math.min(1 - margin, offset + keyPressStep);
-    } else if (keyCode === 37) {
+    } else if (code === 'ArrowLeft' || key === 'ArrowLeft') {
       offset = Math.max(0 + margin, offset - keyPressStep);
     }
   };
@@ -129,6 +135,7 @@
     measureImage();
   };
 
+  /** This can probably get fixed?? */
   const measureLoadedImage = (e: Event) => {
     if (e.type === 'load') {
       imgOffset = (e.target as HTMLImageElement).getBoundingClientRect();
@@ -182,6 +189,7 @@
   <Block {width} {id} class="photo before-after fmy-6 {cls}">
     <div style="height: {containerHeight}px;" bind:clientWidth={containerWidth}>
       <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+
       <figure
         style={figStyle}
         class="before-after-container relative overflow-hidden my-0 mx-auto"

From bf1415ea3cae4fa4c69a327ea5ac59522b0b27a6 Mon Sep 17 00:00:00 2001
From: MinamiFunakoshiTR <minami.funakoshi@thomsonreuters.com>
Date: Wed, 12 Mar 2025 16:25:27 -0700
Subject: [PATCH 03/12] tweaks

---
 src/components/BeforeAfter/BeforeAfter.stories.svelte | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/components/BeforeAfter/BeforeAfter.stories.svelte b/src/components/BeforeAfter/BeforeAfter.stories.svelte
index 5ba7b736..9994ba48 100644
--- a/src/components/BeforeAfter/BeforeAfter.stories.svelte
+++ b/src/components/BeforeAfter/BeforeAfter.stories.svelte
@@ -78,15 +78,15 @@
     afterAlt="Satellite image of Russian base at Myrne taken on Oct. 20, 2020."
   >
     {#snippet beforeOverlay()}
-      <div let:description={id} class="overlay p-3">
-        <p class="body-caption" {id}>
+      <div class="overlay p-3">
+        <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 let:description={id} class="overlay p-3">
-        <p class="body-caption" {id}>
+      <div class="overlay p-3">
+        <p class="body-caption" id="aria-description-after">
           But by October, tanks and artillery could be seen.
         </p>
         <p class="body-caption">

From 607f0af7fe49827c23017ba8b80a1f3bc176e525 Mon Sep 17 00:00:00 2001
From: MinamiFunakoshiTR <minami.funakoshi@thomsonreuters.com>
Date: Thu, 13 Mar 2025 10:50:46 -0700
Subject: [PATCH 04/12] a11y fixes

---
 .../BeforeAfter/BeforeAfter.stories.svelte    | 13 ++---
 src/components/BeforeAfter/BeforeAfter.svelte | 49 +++++++++----------
 src/utils/index.ts                            |  5 ++
 3 files changed, 33 insertions(+), 34 deletions(-)
 create mode 100644 src/utils/index.ts

diff --git a/src/components/BeforeAfter/BeforeAfter.stories.svelte b/src/components/BeforeAfter/BeforeAfter.stories.svelte
index 9994ba48..02a54187 100644
--- a/src/components/BeforeAfter/BeforeAfter.stories.svelte
+++ b/src/components/BeforeAfter/BeforeAfter.stories.svelte
@@ -3,7 +3,7 @@
   import BeforeAfter from './BeforeAfter.svelte';
 
   const { Story } = defineMeta({
-    title: 'Components/Graphics/BeforeAfter',
+    title: 'Components/Multimedia/BeforeAfter',
     component: BeforeAfter,
     argTypes: {
       handleColour: { control: 'color' },
@@ -40,13 +40,13 @@
     afterAlt="Satellite image of Russian base at Myrne taken on Oct. 20, 2020."
   >
     {#snippet beforeOverlay()}
-      <div class="overlay p-3 before">
+      <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}
     {#snippet afterOverlay()}
-      <div class="overlay p-3 after">
+      <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>
@@ -60,9 +60,6 @@
     .overlay {
       background: rgba(0, 0, 0, 0.45);
       max-width: 350px;
-      &.after {
-        text-align: right;
-      }
       p {
         color: #ffffff;
       }
@@ -78,14 +75,14 @@
     afterAlt="Satellite image of Russian base at Myrne taken on Oct. 20, 2020."
   >
     {#snippet beforeOverlay()}
-      <div class="overlay p-3">
+      <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">
+      <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>
diff --git a/src/components/BeforeAfter/BeforeAfter.svelte b/src/components/BeforeAfter/BeforeAfter.svelte
index a97a33a4..23621bfc 100644
--- a/src/components/BeforeAfter/BeforeAfter.svelte
+++ b/src/components/BeforeAfter/BeforeAfter.svelte
@@ -6,12 +6,7 @@
   import Block from '../Block/Block.svelte';
   import PaddingReset from '../PaddingReset/PaddingReset.svelte';
   import type { ContainerWidth } from '../@types/global';
-
-  /** Helper function to generate a random 4-character string */
-  const random4 = () =>
-    Math.floor((1 + Math.random()) * 0x10000)
-      .toString(16)
-      .substring(1);
+  import { random4 } from '../../utils/';
 
   interface Props {
     /** Width of the chart within the text well. Options: wide, wider, widest, fluid */
@@ -98,7 +93,7 @@
   let figure: HTMLElement | undefined = $state(undefined);
   let beforeOverlayWidth = $state(0);
   let isFocused = false;
-  let containerWidth: number = $state(0); // check if this should be undefined
+  let containerWidth: number = $state(0); // Defaults to 0
 
   let containerHeight = $derived(
     containerWidth && heightRatio ? containerWidth * heightRatio : height
@@ -112,6 +107,7 @@
     x < beforeOverlayWidth ? Math.abs(x - beforeOverlayWidth) : 0
   );
 
+  /** Toggle `isFocused` */
   const onfocus = () => (isFocused = true);
   const onblur = () => (isFocused = false);
 
@@ -127,10 +123,12 @@
     }
   };
 
+  /** Measure image and set image offset */
   const measureImage = () => {
     if (img && img.complete) imgOffset = img.getBoundingClientRect();
   };
 
+  /** Reset image offset on resize */
   const resize = () => {
     measureImage();
   };
@@ -142,6 +140,7 @@
     }
   };
 
+  /** Move the slider */
   const move = (e: MouseEvent | TouchEvent) => {
     if (sliding && imgOffset) {
       const el =
@@ -158,11 +157,14 @@
       offset = x / w;
     }
   };
+
+  /** Starts the slider */
   const start = (e: MouseEvent | TouchEvent) => {
     sliding = true;
     move(e);
   };
 
+  /** Sets `sliding` to `false`*/
   const end = () => {
     sliding = false;
   };
@@ -177,46 +179,41 @@
 </script>
 
 <svelte:window
-  on:touchmove={move}
-  on:touchend={end}
-  on:mousemove={move}
-  on:mouseup={end}
-  on:resize={throttle(resize, 100)}
-  on:keydown={handleKeyDown}
+  ontouchmove={move}
+  ontouchend={end}
+  onmousemove={move}
+  onmouseup={end}
+  onresize={throttle(resize, 100)}
+  onkeydown={handleKeyDown}
 />
 
+<!-- Since we usually read these values from ArchieML, check that they exist -->
 {#if beforeSrc && beforeAlt && afterSrc && afterAlt}
   <Block {width} {id} class="photo before-after fmy-6 {cls}">
     <div style="height: {containerHeight}px;" bind:clientWidth={containerWidth}>
-      <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
-
-      <figure
+      <button
         style={figStyle}
         class="before-after-container relative overflow-hidden my-0 mx-auto"
         ontouchstart={start}
         onmousedown={start}
         bind:this={figure}
-        aria-labelledby={(caption && `${id}-caption`) || undefined}
+        aria-labelledby={(caption && `${id}-caption`) || ''}
       >
-        <!-- onmousedown={start || (e) => e.preventDefault()} -->
         <img
           bind:this={img}
           src={afterSrc}
           alt={afterAlt}
           onload={measureLoadedImage}
-          onmousedown={start}
           style={imgStyle}
           class="after absolute block m-0 max-w-full object-cover"
-          aria-describedby={(beforeOverlay && `${id}-before`) || undefined}
+          aria-describedby={(beforeOverlay && `${id}-before`) || ''}
         />
-        <!-- onmousedown={start || (e) => e.preventDefault()} -->
         <img
           src={beforeSrc}
           alt={beforeAlt}
-          onmousedown={start}
           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`) || undefined}
+          aria-describedby={(afterOverlay && `${id}-after`) || ''}
         />
         {#if beforeOverlay}
           <div
@@ -248,7 +245,7 @@
           <div class="arrow-left"></div>
           <div class="arrow-right"></div>
         </div>
-      </figure>
+      </button>
     </div>
     {#if caption}
       <PaddingReset containerIsFluid={width === 'fluid'}>
@@ -264,7 +261,7 @@
 <style lang="scss">
   @use '../../scss/mixins' as mixins;
 
-  figure.before-after-container {
+  button.before-after-container {
     box-sizing: content-box;
 
     img {
@@ -280,7 +277,7 @@
       user-select: none;
     }
     .overlay-container {
-      position: absolute;
+      top: 0;
       :global(:first-child) {
         margin-top: 0;
       }
diff --git a/src/utils/index.ts b/src/utils/index.ts
new file mode 100644
index 00000000..c3e132f5
--- /dev/null
+++ b/src/utils/index.ts
@@ -0,0 +1,5 @@
+/** Helper function to generate a random 4-character string */
+export const random4 = () =>
+  Math.floor((1 + Math.random()) * 0x10000)
+    .toString(16)
+    .substring(1);

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 05/12] 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>

From 3ddd21bced3912fb3d857e1582ec537e4d41a1d0 Mon Sep 17 00:00:00 2001
From: MinamiFunakoshiTR <minami.funakoshi@thomsonreuters.com>
Date: Thu, 13 Mar 2025 12:23:37 -0700
Subject: [PATCH 06/12] tweak

---
 src/components/BeforeAfter/BeforeAfter.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/components/BeforeAfter/BeforeAfter.mdx b/src/components/BeforeAfter/BeforeAfter.mdx
index 41529395..3ce6f1e3 100644
--- a/src/components/BeforeAfter/BeforeAfter.mdx
+++ b/src/components/BeforeAfter/BeforeAfter.mdx
@@ -61,7 +61,7 @@ afterAlt: Satellite image of Russian base at Myrne taken on Oct. 20, 2020.
 
 ## 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).
+To add text overlays and captions, use [snippets](https://svelte.dev/docs/svelte/snippet) for `beforeOverlay`, `afterOverlay` and `caption`. You can style the 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.
 

From 29c18fc64f4608586105bc366ed8ded17623e506 Mon Sep 17 00:00:00 2001
From: MinamiFunakoshiTR <minami.funakoshi@thomsonreuters.com>
Date: Thu, 13 Mar 2025 12:31:47 -0700
Subject: [PATCH 07/12] fixes typo on aria-labelledby

---
 src/components/BeforeAfter/BeforeAfter.svelte | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/components/BeforeAfter/BeforeAfter.svelte b/src/components/BeforeAfter/BeforeAfter.svelte
index f7f8b976..d212da7a 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-description`) || undefined}
+        aria-labelledby={(caption && `${id}-caption`) || undefined}
       >
         <img
           bind:this={img}

From 6d2a4af1c602b0d42941d915fc8fb3c3e165c091 Mon Sep 17 00:00:00 2001
From: MinamiFunakoshiTR <minami.funakoshi@thomsonreuters.com>
Date: Thu, 13 Mar 2025 12:37:50 -0700
Subject: [PATCH 08/12] cleanup

---
 src/components/BeforeAfter/BeforeAfter.svelte | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/src/components/BeforeAfter/BeforeAfter.svelte b/src/components/BeforeAfter/BeforeAfter.svelte
index d212da7a..61dfce6e 100644
--- a/src/components/BeforeAfter/BeforeAfter.svelte
+++ b/src/components/BeforeAfter/BeforeAfter.svelte
@@ -1,6 +1,6 @@
 <!-- @component `BeforeAfter` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-graphics-beforeafter--docs) -->
 <script lang="ts">
-  import { onMount, type Snippet } from 'svelte';
+  import { type Snippet } from 'svelte';
   import { throttle } from 'lodash-es';
 
   import Block from '../Block/Block.svelte';
@@ -133,7 +133,7 @@
     measureImage();
   };
 
-  /** This can probably get fixed?? */
+  /** Measure image and set image offset on load */
   const measureLoadedImage = (e: Event) => {
     if (e.type === 'load') {
       imgOffset = (e.target as HTMLImageElement).getBoundingClientRect();
@@ -169,13 +169,14 @@
     sliding = false;
   };
 
-  onMount(() => {
-    // This is necessary b/c on:load doesn't reliably fire on the image...
-    const interval = setInterval(() => {
-      if (imgOffset) clearInterval(interval);
-      if (img && img.complete && !imgOffset) measureImage();
-    }, 50);
-  });
+  /** @TODO - Double check if this onMount is still necessary */
+  // onMount(() => {
+  //   // This is necessary b/c on:load doesn't reliably fire on the image...
+  //   const interval = setInterval(() => {
+  //     if (imgOffset) clearInterval(interval);
+  //     if (img && img.complete && !imgOffset) measureImage();
+  //   }, 50);
+  // });
 </script>
 
 <svelte:window

From 6789b4b92f69e093fcf5238e9113a9c6b5ae9453 Mon Sep 17 00:00:00 2001
From: MinamiFunakoshiTR <minami.funakoshi@thomsonreuters.com>
Date: Thu, 13 Mar 2025 12:41:58 -0700
Subject: [PATCH 09/12] adds warning and notes

---
 src/components/BeforeAfter/BeforeAfter.svelte | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/components/BeforeAfter/BeforeAfter.svelte b/src/components/BeforeAfter/BeforeAfter.svelte
index 61dfce6e..5f59e714 100644
--- a/src/components/BeforeAfter/BeforeAfter.svelte
+++ b/src/components/BeforeAfter/BeforeAfter.svelte
@@ -169,6 +169,11 @@
     sliding = false;
   };
 
+  /** Keep this warning since these values are often read from an ArchieML doc, which will not trigger typescript errors even if required values don't exist */
+  if (!(beforeSrc && beforeAlt && afterSrc && afterAlt)) {
+    console.warn('Missing required src or alt props for BeforeAfter component');
+  }
+
   /** @TODO - Double check if this onMount is still necessary */
   // onMount(() => {
   //   // This is necessary b/c on:load doesn't reliably fire on the image...

From 8de33b64619055f2efa96df2204828346c164761 Mon Sep 17 00:00:00 2001
From: MinamiFunakoshiTR <minami.funakoshi@thomsonreuters.com>
Date: Thu, 13 Mar 2025 12:46:59 -0700
Subject: [PATCH 10/12] fixes aria desc/label handling

---
 src/components/BeforeAfter/BeforeAfter.svelte | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/src/components/BeforeAfter/BeforeAfter.svelte b/src/components/BeforeAfter/BeforeAfter.svelte
index 5f59e714..a4543746 100644
--- a/src/components/BeforeAfter/BeforeAfter.svelte
+++ b/src/components/BeforeAfter/BeforeAfter.svelte
@@ -203,7 +203,7 @@
         ontouchstart={start}
         onmousedown={start}
         bind:this={figure}
-        aria-labelledby={(caption && `${id}-caption`) || undefined}
+        aria-labelledby={caption ? `${id}-caption` : undefined}
       >
         <img
           bind:this={img}
@@ -212,8 +212,9 @@
           onload={measureLoadedImage}
           style={imgStyle}
           class="after absolute block m-0 max-w-full object-cover"
-          aria-describedby={(beforeOverlay && `${id}-before-description`) ||
-            undefined}
+          aria-describedby={beforeOverlay ?
+            `${id}-before-description`
+          : undefined}
         />
 
         <img
@@ -221,8 +222,9 @@
           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-description`) ||
-            undefined}
+          aria-describedby={afterOverlay ?
+            `${id}-after-description`
+          : undefined}
         />
         {#if beforeOverlay}
           <div

From b56fc64b968f33927ea1cbd523b633ab87a555ae Mon Sep 17 00:00:00 2001
From: MinamiFunakoshiTR <minami.funakoshi@thomsonreuters.com>
Date: Thu, 13 Mar 2025 13:15:58 -0700
Subject: [PATCH 11/12] adds label for button

---
 src/components/BeforeAfter/BeforeAfter.svelte | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/components/BeforeAfter/BeforeAfter.svelte b/src/components/BeforeAfter/BeforeAfter.svelte
index a4543746..b71930b6 100644
--- a/src/components/BeforeAfter/BeforeAfter.svelte
+++ b/src/components/BeforeAfter/BeforeAfter.svelte
@@ -61,6 +61,8 @@
      * Optional snippet for a custom caption.
      */
     caption?: Snippet;
+    /** Custom ARIA label language to label the slider. */
+    sliderAriaLabel?: string;
   }
 
   let {
@@ -81,6 +83,7 @@
     beforeOverlay,
     afterOverlay,
     caption,
+    sliderAriaLabel = 'Stacked before and after images with an adjustable slider',
   }: Props = $props();
 
   /** DOM nodes are undefined until the component is mounted — in other words, you should read it inside an effect or an event handler, but not during component initialisation.
@@ -203,7 +206,7 @@
         ontouchstart={start}
         onmousedown={start}
         bind:this={figure}
-        aria-labelledby={caption ? `${id}-caption` : undefined}
+        aria-label={sliderAriaLabel}
       >
         <img
           bind:this={img}
@@ -364,7 +367,7 @@
     }
   }
 
-  aside.before-after-caption {
+  .before-after-caption {
     :global(p) {
       @include mixins.body-caption;
     }

From 442b00989e01042cfbfa720076b6d8b8504562fd Mon Sep 17 00:00:00 2001
From: MinamiFunakoshiTR <minami.funakoshi@thomsonreuters.com>
Date: Thu, 13 Mar 2025 13:17:45 -0700
Subject: [PATCH 12/12] renames to ariaLabel

---
 src/components/BeforeAfter/BeforeAfter.svelte | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/components/BeforeAfter/BeforeAfter.svelte b/src/components/BeforeAfter/BeforeAfter.svelte
index b71930b6..c3a8dc62 100644
--- a/src/components/BeforeAfter/BeforeAfter.svelte
+++ b/src/components/BeforeAfter/BeforeAfter.svelte
@@ -61,8 +61,8 @@
      * Optional snippet for a custom caption.
      */
     caption?: Snippet;
-    /** Custom ARIA label language to label the slider. */
-    sliderAriaLabel?: string;
+    /** Custom ARIA label language to label the component. */
+    ariaLabel?: string;
   }
 
   let {
@@ -83,7 +83,7 @@
     beforeOverlay,
     afterOverlay,
     caption,
-    sliderAriaLabel = 'Stacked before and after images with an adjustable slider',
+    ariaLabel = 'Stacked before and after images with an adjustable slider',
   }: Props = $props();
 
   /** DOM nodes are undefined until the component is mounted — in other words, you should read it inside an effect or an event handler, but not during component initialisation.
@@ -206,7 +206,7 @@
         ontouchstart={start}
         onmousedown={start}
         bind:this={figure}
-        aria-label={sliderAriaLabel}
+        aria-label={ariaLabel}
       >
         <img
           bind:this={img}