From 4f04bed5718d093c8225c8423972e0157fa5e608 Mon Sep 17 00:00:00 2001
From: MinamiFunakoshiTR <minami.funakoshi@thomsonreuters.com>
Date: Wed, 19 Mar 2025 14:25:54 -0700
Subject: [PATCH] finished hero docs

---
 src/components/Byline/Byline.svelte           |   4 +-
 src/components/Headline/Headline.svelte       |   1 -
 src/components/HeroHeadline/HeroHeadline.mdx  | 316 ++++++++----------
 ...es..svelte => HeroHeadline.stories.svelte} | 240 ++++++-------
 .../HeroHeadline/HeroHeadline.svelte          | 299 +++++++++--------
 5 files changed, 398 insertions(+), 462 deletions(-)
 rename src/components/HeroHeadline/{HeroHeadline.stories..svelte => HeroHeadline.stories.svelte} (54%)

diff --git a/src/components/Byline/Byline.svelte b/src/components/Byline/Byline.svelte
index fa8e2558..8b67574a 100644
--- a/src/components/Byline/Byline.svelte
+++ b/src/components/Byline/Byline.svelte
@@ -19,7 +19,7 @@
      * Update time as a datetime string.
      * @type {string}
      */
-    updateTime: string;
+    updateTime?: string;
     /**
      * Alignment of the byline.
      * @type {string}
@@ -130,7 +130,7 @@
         <div class="whitespace-nowrap inline-block">
           Published
           <time datetime={publishTime}>
-            {#if isValidDate(updateTime)}
+            {#if updateTime && isValidDate(updateTime)}
               {apdate(new Date(publishTime))}
             {:else}
               {apdate(new Date(publishTime))}&nbsp;&nbsp;{formatTime(
diff --git a/src/components/Headline/Headline.svelte b/src/components/Headline/Headline.svelte
index 07e77005..1858db98 100644
--- a/src/components/Headline/Headline.svelte
+++ b/src/components/Headline/Headline.svelte
@@ -12,7 +12,6 @@
   interface Props {
     /** Headline, parsed as an _inline_ markdown string in an `h1` element OR as a custom snippet. */
     hed: string | Snippet;
-
     /** Add extra classes to the block tag to target it with custom CSS. */
     class?: string;
     /** Headline size: small, normal, big, bigger, biggest */
diff --git a/src/components/HeroHeadline/HeroHeadline.mdx b/src/components/HeroHeadline/HeroHeadline.mdx
index b5336d58..47051f80 100644
--- a/src/components/HeroHeadline/HeroHeadline.mdx
+++ b/src/components/HeroHeadline/HeroHeadline.mdx
@@ -6,44 +6,50 @@ import * as HeroHeadlineStories from './HeroHeadline.stories.svelte';
 
 # HeroHeadline
 
-The `HeroHeadline` component creates a Reuters Graphics headline with a Hero media.
+The `HeroHeadline` component creates a Reuters Graphics headline with a hero media, which can be a graphic, photo, video, or any other media.
+
+By default, the hero is in the background, i.e. the headline and dek are stacked on top of the hero. You can unstack and make the headline and dek come before or after the hero media by setting `stacked: true`. [Read more.](?path=/docs/components-text-elements-heroheadline--docs&globals=#transparent-site-header)
+
+## Photo hero
+
+To use a photo as the hero, simply pass the image source to the `img` prop.
 
 ```svelte
+<!-- App.svelte -->
 <script>
   import { HeroHeadline } from '@reuters-graphics/graphics-components';
   import { assets } from '$app/paths'; // 👈 If using in the Graphics Kit...
 
-  export let embedded = false;
+  let { embedded = false } = $props(); // 👈 If using in the Graphics Kit...
 </script>
 
 <HeroHeadline
   {embedded}
-  img={`${assets}/images/myImage.jpg`}
+  img={`${assets}/images/polar-bear.jpg`}
+  ariaDescription="A photo of a polar bear"
+  notes="Photo by REUTERS"
+  section={'World News'}
   hed={'Reuters Graphics Interactive'}
   dek={'The beginning of a beautiful page'}
-  section={'World News'}
-  authors={['Simon Scarr', 'Vijdan Mohammad Kawoosa']}
-  publishTime={new Date('2022-03-04').toISOString()}
+  authors={['Jane Doe', 'John Doe']}
 />
 ```
 
-<Canvas of={HeroHeadlineStories.Demo} />
+<Canvas of={HeroHeadlineStories.PhotoHero} />
 
 ## Transparent site header
 
-Make the hero full bleed and under the header.
+In the Graphics Kit, set styles in `global.scss` to make the Reuters site header transparent and make the hero go all the way to the top of the page:
 
 ```scss
 // global.scss
-
 .nav-container {
   background-color: transparent !important;
 }
 .nav-container .inner {
   background-color: transparent !important;
-  border: none;
+  border: none !important;
 }
-
 .hero-wrapper {
   margin-top: -64px;
 }
@@ -51,29 +57,35 @@ Make the hero full bleed and under the header.
 
 <Canvas of={HeroHeadlineStories.TransparentHeader} />
 
-## With background graphic
+## Ai2svelte hero
 
-Reuters Graphics headline with ai2svelte graphic as background.
+To use an ai2svelte graphic as the hero, wrap your ai2svelte component in a `GraphicBlock` component and insert it inside the `HeroHeadline` component.
+
+To customise styles, use CSS to target the class passed to `HeroHeadline`.
+
+> **Note:** Pass `notes` and `ariaDescription` to the `GraphicBlock` component to provide additional information about the ai2svelte graphic.
 
 ```svelte
+<!-- App.svelte -->
 <script>
   import {
     HeroHeadline,
     GraphicBlock,
   } from '@reuters-graphics/graphics-components';
-  import QuakeMap from './ai2svelte/graphic.svelte';
-  import { assets } from '$app/paths';
 
-  export let embedded = false;
+  import QuakeMap from './ai2svelte/graphic.svelte'; // Your ai2svelte component
+
+  import { assets } from '$app/paths'; // 👈 If using in the Graphics Kit...
+
+  export let embedded = false; // 👈 If using in the Graphics Kit...
 </script>
 
 <HeroHeadline
   {embedded}
-  hed={'Earthquake devastates Afghanistan'}
-  hedSize={'big'}
+  hed="Earthquake devastates Afghanistan"
+  hedSize="big"
   hedWidth="wide"
   class="custom-hero mb-0"
-  dek=""
   authors={[
     'Anand Katakam',
     'Vijdan Mohammad Kawoosa',
@@ -87,20 +99,18 @@ Reuters Graphics headline with ai2svelte graphic as background.
   ]}
   publishTime={new Date('2022-06-24').toISOString()}
 >
-  <div slot="background">
-    <GraphicBlock
-      width="widest"
-      role="figure"
-      class="my-0"
-      textWidth="normal"
-      notes=""
-      ariaDescription="Earthquake impact map"
-    >
-      <svelte:component this={QuakeMap} />
-    </GraphicBlock>
-  </div>
+  <GraphicBlock
+    width="widest"
+    role="figure"
+    class="my-0"
+    ariaDescription="Earthquake impact map"
+  >
+    <!-- Pass `assetsPath` if in Graphics Kit -->
+    <QuakeMap assetsPath={assets || '/'} />
+  </GraphicBlock>
 </HeroHeadline>
 
+<!-- Customise styles using the class (e.g. `custom-hero` here) passed to `HeroHeadline` -->
 <style lang="scss">
   .hero-wrapper {
     .custom-hero.headline {
@@ -113,7 +123,7 @@ Reuters Graphics headline with ai2svelte graphic as background.
       }
     }
 
-    // Make hero smaller than 100vh
+    // Make hero shorter than 100vh
     --heroHeight: 85svh;
 
     @media (max-width: 960px) {
@@ -138,48 +148,49 @@ Reuters Graphics headline with ai2svelte graphic as background.
 </style>
 ```
 
-<Canvas of={HeroHeadlineStories.BackgroundGraphic} />
+<Canvas of={HeroHeadlineStories.Ai2svelteHero} />
 
-## With background video
+## Video hero
 
-Add a cover video and position the title with ease.
+To add a video as the hero, use the [Video](?path=/docs/components-multimedia-video--docs) component. To customise styles, use CSS to target the class passed to `HeroHeadline`.
+
+> **Note:** Pass `notes` and `ariaDescription` to the `GraphicBlock` component to provide additional information about the video.
 
 ```svelte
 <script>
   import { HeroHeadline, Video } from '@reuters-graphics/graphics-components';
-  import { assets } from '$app/paths';
+  import { assets } from '$app/paths'; // 👈 If using in the Graphics Kit...
 
-  export let embedded = false;
+  export let embedded = false; // 👈 If using in the Graphics Kit...
 </script>
 
 <HeroHeadline
   {embedded}
-  class="custom-hero"
+  class="video-hero"
   hed="The conflict in Ethiopia"
   hedSize="bigger"
   hedWidth="wide"
   authors={['Aditi Bhandari ', 'David Lewis']}
   publishTime={new Date('2020-12-18').toISOString()}
 >
-  <div slot="background">
-    <Video
-      width="widest"
-      class="my-0"
-      showControls={false}
-      preloadVideo="auto"
-      playVideoWhenInView={false}
-      src="{assets}/videos/intro.mp4"
-      poster="{assets}/images/video-poster-intro.jpg"
-      notes="Drone footage from the Village 8 refugee camp in Sudan."
-      ariaDescription="Aerial footage of people houses in refugee camp"
-    />
-  </div>
+  <Video
+    width="widest"
+    class="my-0"
+    showControls={false}
+    preloadVideo="auto"
+    playVideoWhenInView={false}
+    src={`${assets}/videos/intro.mp4`}
+    poster={`${assets}/images/video-poster-intro.jpg`}
+    notes="Drone footage from the Village 8 refugee camp in Sudan."
+    ariaDescription="Aerial footage of people houses in refugee camp"
+  />
 </HeroHeadline>
 
+<!-- Customise styles using the class (e.g. `video-hero` here) passed to `HeroHeadline` -->
 <style lang="scss">
   .hero-wrapper {
     --heroHeight: calc(100svh - 60px);
-    .custom-hero.headline {
+    .video-hero.headline {
       header {
         // Adjust vertical position as offset from default center
         top: calc(50svh - 250px);
@@ -194,143 +205,61 @@ Add a cover video and position the title with ease.
 </style>
 ```
 
-<Canvas of={HeroHeadlineStories.BackgroundVideo} />
+<Canvas of={HeroHeadlineStories.VideoHero} />
 
-## With inline photo
+## Inline hero
 
-Reuters Graphics headline followed by a graphic or any media block.
-
-```svelte
-<script>
-  import {
-    HeroHeadline,
-    FeaturePhoto,
-  } from '@reuters-graphics/graphics-components';
-  import { assets } from '$app/paths';
-
-  export let embedded = false;
-</script>
-
-<HeroHeadline
-  {embedded}
-  hed={'Buried under the bricks'}
-  hedWidth="wide"
-  class="mb-0"
-  dek={'How mud-brick housing made the Morocco earthquake so deadly'}
-  section={'Global news'}
-  authors={['Mariano Zafra']}
-  publishTime={new Date('2020-01-01').toISOString()}
->
-  <div slot="inline">
-    <FeaturePhoto
-      width="widest"
-      class="my-0"
-      src={`${assets}/images/myImage.jpg`}
-      caption="Photo by REUTERS/Nacho Doce."
-      altText="A photo of the town of Adassil, Morocco, showing severe damage to many houses, which have collapsed after the earthquake. The houses are all made of mud brick."
-    />
-  </div>
-</HeroHeadline>
-```
-
-<Canvas of={HeroHeadlineStories.InlinePhoto} />
-
-## With inline graphic
-
-Reuters Graphics headline followed by a graphic or any media block.
+To use a photo, graphic, video, etc. as an inline hero -- i.e. to make the hero appear below or above the headline and dek, not on top -- set `stacked` to `false`. Otherwise add your hero media as documented above.
+
+> **Note:** Pass `notes` and `ariaDescription` to the component you're inserting into `HeroHeadline` to provide additional information.
 
 ```svelte
+<!-- App.svelte -->
 <script>
   import {
     HeroHeadline,
     GraphicBlock,
   } from '@reuters-graphics/graphics-components';
-  import Map from './ai2svelte/graphic.svelte';
-  import { assets } from '$app/paths';
+  import { assets } from '$app/paths'; // 👈 If using in the Graphics Kit...
 
-  export let embedded = false;
+  export let embedded = false; // 👈 If using in the Graphics Kit...
 </script>
 
+<!-- Set `stacked` to `false` -->
 <HeroHeadline
   {embedded}
-  hed={'The plunge from 29,000 feet'}
-  hedWidth="wide"
+  stacked={false}
+  section="Global news"
+  hed="The plunge from 29,000 feet"
+  dek="How China Eastern Airlines flight MU5735 went from an uneventful flight at cruising altitude to disaster in just minutes."
   class="mb-0"
-  dek={'How China Eastern Airlines flight MU5735 went from an uneventful flight at cruising altitude to disaster in just minutes.'}
-  section={'Global news'}
   authors={['Simon Scarr', 'Vijdan Mohammad Kawoosa']}
   publishTime={new Date('2020-01-01').toISOString()}
 >
-  <div slot="inline">
-    <GraphicBlock
-      width="widest"
-      role="img"
-      class="my-0"
-      textWidth="normal"
-      notes="Source: Satellite image from Google, Maxar Technologies, CNES/Airbus, Landsat/Copernicus"
-      ariaDescription="Aerial map showing trajectory of crash"
-    >
-      <svelte:component this={Map} assetsPath={assets || '/'} />
-    </GraphicBlock>
-  </div>
+  <GraphicBlock
+    width="widest"
+    role="figure"
+    class="my-0"
+    ariaDescription="Earthquake impact map"
+    notes="Source: Satellite image from Google, Maxar Technologies, CNES/Airbus, Landsat/Copernicus"
+  >
+    <!-- Pass `assetsPath` if in Graphics Kit -->
+    <CrashMap assetsPath={assets || '/'} />
+  </GraphicBlock>
 </HeroHeadline>
 ```
 
-<Canvas of={HeroHeadlineStories.InlineGraphic} />
+<Canvas of={HeroHeadlineStories.InlineHero} />
 
-## With inline video
+## Custom hed and dek
 
-Add a cover video and position the title with ease.
+The `HeroHeadline` component internally uses the [Headline](?path=/docs/components-text-elements-headline--docs) component to render the headline and dek.
+
+If `hed` and `dek` values are strings, they are rendered according to the default Reuters style. To customise the headline and dek, pass custom `hed` and `dek` elements as [snippets](https://svelte.dev/docs/svelte/snippet) to `HeroHeadline` -- the same way as you would with `Headline`.
 
 ```svelte
-<script>
-  import { HeroHeadline, Video } from '@reuters-graphics/graphics-components';
-  import { assets } from '$app/paths';
-
-  export let embedded = false;
-</script>
-
+<!-- App.svelte -->
 <HeroHeadline
-  {embedded}
-  hed={'Devastation in Derna'}
-  hedWidth="wide"
-  class="mb-0"
-  dek={'How raging floods burst dams, destroyed neighbourhoods and killed thousands in Libya'}
-  section={'Global news'}
-  authors={['Simon Scarr']}
-  publishTime={new Date('2020-01-01').toISOString()}
->
-  <div slot="inline">
-    <Video
-      width="widest"
-      class="my-0"
-      showControls={false}
-      preloadVideo="auto"
-      playVideoWhenInView={false}
-      src="{assets}/videos/intro.mp4"
-      notes="Drone shots of Derna, Libya. September 14, 2023. REUTERS"
-      ariaDescription="alttext fot video"
-    />
-  </div>
-</HeroHeadline>
-```
-
-<Canvas of={HeroHeadlineStories.InlineVideo} />
-
-## Custom hed
-
-Add a custom styled headline.
-
-```svelte
-<script>
-  import { HeroHeadline } from '@reuters-graphics/graphics-components';
-  import { assets } from '$app/paths'; // 👈 If using in the Graphics Kit...
-
-  export let embedded = false;
-</script>
-
-<HeroHeadline
-  {embedded}
   class="custom-hed"
   authors={[
     'Prasanta Kumar Dutta',
@@ -339,28 +268,53 @@ Add a custom styled headline.
     'Anurag Rao',
   ]}
   publishTime={new Date('2023-05-11').toISOString()}
-  img={`${assets}/images/myImage.jpg`}
+  img={eurovisImgSrc}
 >
-  <h1 slot="hed">
-    <div class="body-note">A visual guide to</div>
-    <div class="title text-6xl font-light tracking-widest">EUROVISION</div>
-  </h1>
-</HeroHeadline>
+  <!-- Custom hed snippet -->
+  {#snippet hed()}
+    <h1>
+      <div class="body-note">A visual guide to</div>
+      <div class="title text-6xl font-light tracking-widest">EUROVISION</div>
+    </h1>
+  {/snippet}
 
-<style lang="scss">
-  .custom-hed {
-    h1 {
-      .body-note {
-        color: #ffffff;
+  <!-- Custom dek snippet -->
+  {#snippet dek()}
+    <div class="dek">
+      <p>
+        Performers from 37 countries are coming together May 9-13 in Liverpool,
+        England, for the 67th annual Eurovision Song Contest. The winner gets
+        the trophy and their country gets the right to host next year’s event,
+        produced by the European Broadcasting Union (EBU).
+      </p>
+    </div>
+  {/snippet}
+
+  <!-- Style your custom hed and dek -->
+  <style lang="scss">
+    .custom-hed {
+      h1 {
+        .body-note {
+          color: #ffffff;
+        }
+        .title {
+          color: #ffffff;
+          text-shadow: 1px 1px 8px #ff7c88;
+          filter: drop-shadow(0px 0px 12px #ff7c88);
+        }
       }
-      .title {
-        color: #ffffff;
-        text-shadow: 1px 1px 8px #ff7c88;
-        filter: drop-shadow(0px 0px 12px #ff7c88);
+
+      .dek {
+        margin-top: 1rem;
+        p {
+          color: #ffffff;
+          text-shadow: 1px 1px 8px #ff7c88;
+          filter: drop-shadow(0px 0px 12px #ff7c88);
+        }
       }
     }
-  }
-</style>
+  </style>
+</HeroHeadline>
 ```
 
-    <Canvas of={HeroHeadlineStories.CustomHed} />
+<Canvas of={HeroHeadlineStories.CustomHed} />
diff --git a/src/components/HeroHeadline/HeroHeadline.stories..svelte b/src/components/HeroHeadline/HeroHeadline.stories.svelte
similarity index 54%
rename from src/components/HeroHeadline/HeroHeadline.stories..svelte
rename to src/components/HeroHeadline/HeroHeadline.stories.svelte
index ca03867f..c2f3baf9 100644
--- a/src/components/HeroHeadline/HeroHeadline.stories..svelte
+++ b/src/components/HeroHeadline/HeroHeadline.stories.svelte
@@ -26,7 +26,7 @@
   });
 </script>
 
-<script>
+<script lang="ts">
   import polarImgSrc from './demo/polar.jpg';
   import eurovisImgSrc from './demo/eurovis.jpeg';
 
@@ -40,54 +40,61 @@
   import QuakeMap from './demo/graphics/quakemap.svelte';
 </script>
 
-{#snippet template(args)}
+<Story name="Photo hero" exportName="PhotoHero">
   <Block width="fluid" class="chromatic-ignore">
     <SiteHeader />
   </Block>
-
-  <HeroHeadline {...args} />
-{/snippet}
-
-<Story
-  name="Demo"
-  args={{
-    section: 'World News',
-    hed: 'Reuters Graphics Interactive',
-    dek: 'The beginning of a beautiful page',
-    authors: ['Simon Scarr', 'Vijdan Mohammad Kawoosa'],
-    publishTime: new Date('2022-03-04').toISOString(),
-    img: polarImgSrc,
-  }}
->
-  {@render template({
-    section: 'World News',
-    hed: 'Reuters Graphics Interactive',
-    dek: 'The beginning of a beautiful page',
-    authors: ['Simon Scarr', 'Vijdan Mohammad Kawoosa'],
-    publishTime: new Date('2022-03-04').toISOString(),
-    img: polarImgSrc,
-  })}
+  <HeroHeadline
+    section="World News"
+    hed="Reuters Graphics Interactive"
+    dek="The beginning of a beautiful page"
+    authors={['Jane Doe', 'John Doe']}
+    publishTime={new Date('2022-03-04').toISOString()}
+    img={polarImgSrc}
+    notes="Photo by REUTERS"
+    ariaDescription="A photo of a polar bear"
+  />
 </Story>
 
-<!-- 
-<Story name="With transparent header">
+<Story name="Feature photo hero" exportName="FeaturePhotoHero">
+  <Block width="fluid" class="chromatic-ignore">
+    <SiteHeader />
+  </Block>
+  <HeroHeadline
+    section="World News"
+    hed="Reuters Graphics Interactive"
+    dek="The beginning of a beautiful page"
+    authors={['Jane Doe', 'John Doe']}
+    publishTime={new Date('2022-03-04').toISOString()}
+  >
+    <FeaturePhoto
+      width="widest"
+      class="my-0"
+      src={polarImgSrc}
+      caption="Photo by REUTERS."
+      altText="A photo of a polar bear."
+    />
+  </HeroHeadline>
+</Story>
+
+<Story name="Transparent header" exportName="TransparentHeader">
   <div class="transparent-header">
     <Block width="fluid" class="chromatic-ignore">
       <SiteHeader />
     </Block>
-
     <HeroHeadline
       section="World News"
       hed="Reuters Graphics Interactive"
       dek="The beginning of a beautiful page"
-      authors={['Simon Scarr', 'Vijdan Mohammad Kawoosa']}
+      authors={['Jane Doe', 'John Doe']}
       publishTime={new Date('2022-03-04').toISOString()}
       img={polarImgSrc}
+      ariaDescription="A photo of a polar bear"
     />
   </div>
 </Story>
 
-<Story name="With backdrop graphic">
+<Story name="Ai2svelte hero" exportName="Ai2svelteHero">
   <Block width="fluid" class="chromatic-ignore">
     <SiteHeader />
   </Block>
@@ -97,7 +104,6 @@
     hedSize={'big'}
     hedWidth="wide"
     class="custom-hero mb-0"
-    dek=""
     authors={[
       'Anand Katakam',
       'Vijdan Mohammad Kawoosa',
@@ -111,18 +117,14 @@
     ]}
     publishTime={new Date('2022-06-24').toISOString()}
   >
-    <div slot="background">
-      <GraphicBlock
-        width="widest"
-        role="figure"
-        class="my-0"
-        textWidth="normal"
-        notes=""
-        ariaDescription="Earthquake impact map"
-      >
-        <svelte:component this={QuakeMap} />
-      </GraphicBlock>
-    </div>
+    <GraphicBlock
+      width="widest"
+      role="figure"
+      class="my-0"
+      ariaDescription="Earthquake impact map"
+    >
+      <QuakeMap />
+    </GraphicBlock>
   </HeroHeadline>
   <style lang="scss">
     .hero-wrapper {
@@ -136,7 +138,7 @@
         }
       }
 
-      // Make hero smaller than 100vh
+      // Make hero shorter than 100vh
       --heroHeight: 85svh;
 
       @media (max-width: 960px) {
@@ -161,12 +163,13 @@
   </style>
 </Story>
 
-<Story name="With backdrop video">
+<Story name="Video hero" exportName="VideoHero">
   <Block width="fluid" class="chromatic-ignore">
     <SiteHeader />
   </Block>
 
   <HeroHeadline
+    stacked={false}
     class="video-hero"
     hed="The conflict in Ethiopia"
     hedSize="bigger"
@@ -174,19 +177,17 @@
     authors={['Aditi Bhandari ', 'David Lewis']}
     publishTime={new Date('2020-12-18').toISOString()}
   >
-    <div slot="background">
-      <Video
-        width="widest"
-        class="my-0"
-        showControls={false}
-        preloadVideo="auto"
-        playVideoWhenInView={false}
-        src="https://vm.reuters.tv/9c72e/titlef2ac(425954_R21MP41500).mp4"
-        poster="https://www.reuters.com/resizer/vexYmtEuXKmfnsCbfS6jSMVbHms=/1080x0/filters:quality(80)/cloudfront-us-east-2.images.arcpublishing.com/reuters/VKJHKJEENVO4DASDND3VLHPV5Y.jpg"
-        notes="Drone footage from the Village 8 refugee camp in Sudan."
-        ariaDescription="Aerial footage of people houses in refugee camp"
-      />
-    </div>
+    <Video
+      width="widest"
+      class="my-0"
+      showControls={false}
+      preloadVideo="auto"
+      playVideoWhenInView={false}
+      src="https://vm.reuters.tv/9c72e/titlef2ac(425954_R21MP41500).mp4"
+      poster="https://www.reuters.com/resizer/vexYmtEuXKmfnsCbfS6jSMVbHms=/1080x0/filters:quality(80)/cloudfront-us-east-2.images.arcpublishing.com/reuters/VKJHKJEENVO4DASDND3VLHPV5Y.jpg"
+      notes="Drone footage from the Village 8 refugee camp in Sudan."
+      ariaDescription="Aerial footage of people houses in refugee camp"
+    />
   </HeroHeadline>
   <style lang="scss">
     .hero-wrapper {
@@ -206,91 +207,34 @@
   </style>
 </Story>
 
-<Story name="With inline photo">
+<Story name="Inline hero" exportName="InlineHero">
   <Block width="fluid" class="chromatic-ignore">
     <SiteHeader />
   </Block>
 
+  <!-- Set `stacked` to `false` -->
   <HeroHeadline
-    hed={'Buried under the bricks'}
-    hedWidth="wide"
+    stacked={false}
+    section="Global news"
+    hed="The plunge from 29,000 feet"
+    dek="How China Eastern Airlines flight MU5735 went from an uneventful flight at cruising altitude to disaster in just minutes."
     class="mb-0"
-    dek={'How mud-brick housing made the Morocco earthquake so deadly'}
-    section={'Global news'}
-    authors={['Mariano Zafra']}
-    publishTime={new Date('2020-01-01').toISOString()}
-  >
-    <div slot="inline">
-      <FeaturePhoto
-        width="widest"
-        class="my-0"
-        src="https://www.reuters.com/graphics/MOROCCO-QUAKE/CONSTRUCTION/xmpjlblojpr/cdn/images/opening.jpg"
-        caption="Photo by REUTERS/Nacho Doce."
-        altText="A photo of the town of Adassil, Morocco, showing severe damage to many houses, which have collapsed after the earthquake. The houses are all made of mud brick."
-      />
-    </div>
-  </HeroHeadline>
-</Story>
-
-<Story name="With inline graphic">
-  <Block width="fluid" class="chromatic-ignore">
-    <SiteHeader />
-  </Block>
-
-  <HeroHeadline
-    hed={'The plunge from 29,000 feet'}
-    hedWidth="wide"
-    class="mb-0"
-    dek={'How China Eastern Airlines flight MU5735 went from an uneventful flight at cruising altitude to disaster in just minutes.'}
-    section={'Global news'}
     authors={['Simon Scarr', 'Vijdan Mohammad Kawoosa']}
     publishTime={new Date('2020-01-01').toISOString()}
   >
-    <div slot="inline">
-      <GraphicBlock
-        width="widest"
-        role="img"
-        class="my-0"
-        textWidth="normal"
-        notes="Source: Satellite image from Google, Maxar Technologies, CNES/Airbus, Landsat/Copernicus"
-        ariaDescription="Aerial map showing trajectory of crash"
-      >
-        <svelte:component this={CrashMap} />
-      </GraphicBlock>
-    </div>
+    <GraphicBlock
+      width="widest"
+      role="figure"
+      class="my-0"
+      ariaDescription="Earthquake impact map"
+      notes="Source: Satellite image from Google, Maxar Technologies, CNES/Airbus, Landsat/Copernicus"
+    >
+      <CrashMap />
+    </GraphicBlock>
   </HeroHeadline>
 </Story>
 
-<Story name="With inline video">
-  <Block width="fluid" class="chromatic-ignore">
-    <SiteHeader />
-  </Block>
-
-  <HeroHeadline
-    hed={'Devastation in Derna'}
-    hedWidth="wide"
-    class="mb-0"
-    dek={'How raging floods burst dams, destroyed neighbourhoods and killed thousands in Libya'}
-    section={'Global news'}
-    authors={['Simon Scarr']}
-    publishTime={new Date('2020-01-01').toISOString()}
-  >
-    <div slot="inline">
-      <Video
-        width="widest"
-        class="my-0"
-        showControls={false}
-        preloadVideo="auto"
-        playVideoWhenInView={false}
-        src="https://www.reuters.com/graphics/LIBYA-STORM/EXPLAINER/klvyzqebzpg/cdn/video/drone.mp4"
-        notes="Drone shots of Derna, Libya. September 14, 2023. REUTERS"
-        ariaDescription="alttext fot video"
-      />
-    </div>
-  </HeroHeadline>
-</Story>
-
-<Story name="With custom hed">
+<Story name="Custom hed" exportName="CustomHed">
   <HeroHeadline
     class="custom-hed"
     authors={[
@@ -302,10 +246,23 @@
     publishTime={new Date('2023-05-11').toISOString()}
     img={eurovisImgSrc}
   >
-    <h1 slot="hed">
-      <div class="body-note">A visual guide to</div>
-      <div class="title text-6xl font-light tracking-widest">EUROVISION</div>
-    </h1>
+    {#snippet hed()}
+      <h1>
+        <div class="body-note">A visual guide to</div>
+        <div class="title text-6xl font-light tracking-widest">EUROVISION</div>
+      </h1>
+    {/snippet}
+
+    {#snippet dek()}
+      <div class="dek">
+        <p>
+          Performers from 37 countries are coming together May 9-13 in
+          Liverpool, England, for the 67th annual Eurovision Song Contest. The
+          winner gets the trophy and their country gets the right to host next
+          year’s event, produced by the European Broadcasting Union (EBU).
+        </p>
+      </div>
+    {/snippet}
   </HeroHeadline>
 
   <style lang="scss">
@@ -320,9 +277,18 @@
           filter: drop-shadow(0px 0px 12px #ff7c88);
         }
       }
+
+      .dek {
+        margin-top: 1rem;
+        p {
+          color: #ffffff;
+          text-shadow: 1px 1px 8px #ff7c88;
+          filter: drop-shadow(0px 0px 12px #ff7c88);
+        }
+      }
     }
   </style>
-</Story> -->
+</Story>
 
 <style lang="scss">
   .transparent-header {
@@ -331,7 +297,7 @@
     }
     :global(.nav-container .inner) {
       background-color: transparent !important;
-      border: none;
+      border: none !important;
     }
 
     :global(.hero-wrapper) {
diff --git a/src/components/HeroHeadline/HeroHeadline.svelte b/src/components/HeroHeadline/HeroHeadline.svelte
index cceaee8f..06de711c 100644
--- a/src/components/HeroHeadline/HeroHeadline.svelte
+++ b/src/components/HeroHeadline/HeroHeadline.svelte
@@ -1,127 +1,142 @@
 <!-- @component `HeroHeadline` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-text-elements-heroheadline--docs) -->
 <script lang="ts">
+  import type { Snippet } from 'svelte';
   import type { HeadlineSize } from '../@types/global';
 
-  /** Set to true for embeddables. */
-  export let embedded: boolean = false;
-
-  /**
-   * Path to background image
-   * @type {string}
-   */
-  export let img: string | null = null;
-
-  /**
-   * ARIA description, passed in as a markdown string.
-   * @type {string}
-   */
-  export let ariaDescription: string | null = null;
-
-  /**
-   * Notes to the graphic, passed in as a markdown string.
-   * @type {string}
-   */
-  export let notes: string | null = null;
-
-  /**
-   * Headline, parsed as an _inline_ markdown string in an `h1` element.
-   * @type {string}
-   */
-  export let hed: string = 'Reuters Graphics Interactive';
-
-  /** Add extra classes to the block tag to target it with custom CSS. */
-  let cls: string = '';
-  export { cls as class };
-
-  /**
-   * Headline size
-   * @type {string}
-   */
-  export let hedSize: HeadlineSize = 'normal';
-
-  /**
-   * Headline horizontal alignment
-   * @type {string}
-   */
-  export let hedAlign: 'left' | 'center' | 'right' = 'center';
-
-  /**
-   * Width of the headline.
-   */
-  export let hedWidth: 'normal' | 'wide' | 'wider' | 'widest' = 'normal';
-
-  /**
-   * Dek, parsed as a markdown string.
-   * @type {string}
-   */
-  export let dek: string | null = null;
-  /**
-   * Section title
-   * @type {string}
-   */
-  export let section: string | null = null;
-  /**
-   * Array of author names, which will be slugified to create links to Reuters author pages
-   */
-  export let authors: string[] = [];
-  /**
-   * Publish time as a datetime string.
-   * @type {string}
-   */
-  export let publishTime: string = '';
-  /**
-   * Update time as a datetime string.
-   * @type {string}
-   */
-  export let updateTime: string = '';
-
-  /**
-   * Width of the Hero graphic.
-   */
-  export let width: 'normal' | 'wide' | 'wider' | 'widest' = 'widest';
-
-  import Headline from '../Headline/Headline.svelte';
-  import GraphicBlock from '../GraphicBlock/GraphicBlock.svelte';
+  // Components
   import Block from '../Block/Block.svelte';
-  import Byline from '../Byline/Byline.svelte';
+  import GraphicBlock from '../GraphicBlock/GraphicBlock.svelte';
   import PaddingReset from '../PaddingReset/PaddingReset.svelte';
+  import Headline from '../Headline/Headline.svelte';
+  import Byline from '../Byline/Byline.svelte';
+
+  export interface Props {
+    /** Headline, parsed as an _inline_ markdown string in an `h1` element OR as a custom snippet. */
+    hed: string | Snippet;
+    /**
+     * Optional snippet for a custom hero graphic, photo, etc.
+     */
+    children?: Snippet;
+    /** Set to `false` for non-stacked hero headline */
+    stacked?: boolean;
+    /**
+     * Path to background image
+     */
+    img?: string;
+    /**
+     * ARIA description, passed in as a markdown string.
+     */
+    ariaDescription?: string;
+    /**
+     * Notes to the graphic, passed in as a markdown string.
+     */
+    notes?: string;
+
+    /** Add classes to the block tag to target it with custom CSS. */
+    class?: string;
+    /**
+     * Headline size
+     */
+    hedSize?: HeadlineSize;
+    /**
+     * Headline horizontal alignment: left, center, right
+     */
+    hedAlign?: 'left' | 'center' | 'right';
+    /**
+     * Width of the headline: normal, wide, wider, widest
+     */
+    hedWidth?: 'normal' | 'wide' | 'wider' | 'widest';
+    /**
+     * Dek, parsed as a markdown string OR as a custom snippet.
+     */
+    dek?: string | Snippet;
+    /**
+     * Section title
+     */
+    section?: string;
+    /**
+     * Array of author names, which will be slugified to create links to Reuters author pages
+     */
+    authors?: string[];
+    /**
+     * Publish time as a datetime string.
+     */
+    publishTime: string;
+    /**
+     * Update time as a datetime string.
+     */
+    updateTime?: string;
+    /**
+     * Width of the hero graphic: normal, wide, wider, widest
+     */
+    width?: 'normal' | 'wide' | 'wider' | 'widest';
+    /** Set to true for embeddables. */
+    embedded?: boolean;
+    /**
+     * Custom function that returns an author page URL.
+     */
+    getAuthorPage?: (author: string) => string;
+    /**
+     * Optional snippet for a custom byline.
+     */
+    byline?: Snippet;
+    /**
+     * Optional snippet for a custom published dateline.
+     */
+    published?: Snippet;
+    /**
+     * Optional snippet for a custom updated dateline.
+     */
+    updated?: Snippet;
+  }
+
+  let {
+    hed,
+    stacked = true,
+    img,
+    ariaDescription,
+    notes,
+    class: cls = '',
+    hedSize = 'normal',
+    hedAlign = 'center',
+    hedWidth = 'normal',
+    dek,
+    section,
+    authors = [],
+    publishTime,
+    updateTime,
+    width = 'widest',
+    embedded = false,
+    children,
+    getAuthorPage,
+    byline,
+    published,
+    updated,
+  }: Props = $props();
 </script>
 
 <div style="--heroHeight: {embedded ? '850px' : '100svh'}; display:contents;">
   <div class="hero-wrapper fmb-6" class:embedded>
-    <!-- Background media hero-->
-    {#if $$slots.background || img}
+    <!-- stacked media hero-->
+    {#if stacked}
       <Block width="fluid" class="hero-headline background-hero fmt-0">
-        {#if $$slots.hed}
-          <Headline
-            class="{cls} !text-{hedAlign}"
-            width={hedWidth}
-            {section}
-            {hedSize}
-            {hed}
-            {dek}
-          >
-            <!-- Headline named slot -->
-            <div slot="hed">
-              <slot name="hed" />
-            </div>
-          </Headline>
-        {:else}
-          <Headline
-            class="{cls} !text-{hedAlign}"
-            width={hedWidth}
-            {section}
-            {hedSize}
-            {hed}
-            {dek}
-          />
-        {/if}
+        <!-- Handles string or snippet `hed` -->
+        <Headline
+          class="{cls} !text-{hedAlign}"
+          width={hedWidth}
+          {section}
+          {hedSize}
+          {hed}
+          {dek}
+        />
 
         <div class="graphic-container">
-          {#if $$slots.background}
-            <!-- Hero graphic named slot -->
-            <slot name="background" />
-          {:else}
+          <!-- Custom hero snippet -->
+          {#if children}
+            {@render children()}
+
+            <!-- Otherwise render the image if it exists -->
+          {:else if img}
             <GraphicBlock
               {width}
               role="img"
@@ -140,47 +155,49 @@
       </Block>
     {/if}
 
-    <!-- Inline hero -->
-    {#if $$slots.inline}
+    <!-- Non-stacked hero -->
+    {#if stacked === false}
       <Block width="fluid" class="hero-headline inline-hero">
         <PaddingReset containerIsFluid={true}>
-          {#if $$slots.hed}
-            <Headline
-              class="{cls} !text-{hedAlign}"
-              width={hedWidth}
-              {section}
-              {hedSize}
-              {hed}
-              {dek}
-            >
-              <!-- Headline named slot -->
-              <div slot="hed">
-                <slot name="hed" />
-              </div>
-            </Headline>
-          {:else}
-            <Headline
-              class="{cls} !text-{hedAlign}"
-              width={hedWidth}
-              {section}
-              {hedSize}
-              {hed}
-              {dek}
-            />
-          {/if}
+          <Headline
+            class="{cls} !text-{hedAlign}"
+            width={hedWidth}
+            {section}
+            {hedSize}
+            {hed}
+            {dek}
+          />
         </PaddingReset>
         <div class="graphic-container">
-          <!-- Hero named slot -->
-          <slot name="inline" />
+          <!-- Custom hero snippet -->
+          {#if children}
+            {@render children()}
+
+            <!-- Otherwise render the image if it exists -->
+          {:else if img}
+            <GraphicBlock
+              {width}
+              role="img"
+              class="my-0"
+              textWidth="normal"
+              {notes}
+              {ariaDescription}
+            >
+              <div
+                class="background-image"
+                style="background-image: url({img})"
+              ></div>
+            </GraphicBlock>
+          {/if}
         </div>
       </Block>
     {/if}
   </div>
 
   <div class="hero-byline fmb-6">
-    {#if $$slots.byline}
+    {#if byline}
       <!-- Custom byline/dateline -->
-      <slot name="byline" />
+      {@render byline()}
     {:else if authors.length > 0 || publishTime}
       <Byline {authors} {publishTime} {updateTime} align="left" />
     {/if}