@reuters-graphics/graphics-components 3.10.0 → 4.0.0

package/dist/llm-docs/components/HeroHeadline.md

@@ -0,0 +1,515 @@
+# HeroHeadline
+
+**Category:** Components/Text elements/HeroHeadline
+
+**Import:** `import { HeroHeadline } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `hed` | `string \| Snippet` | — | ✓ | Headline, parsed as an _inline_ markdown string in an `h1` element OR as a custom snippet. |
+| `children` | `Snippet` | — |  | Optional snippet for a custom hero graphic, photo, etc. |
+| `stacked` | `boolean` | `true` |  | Set to `false` for inline hero media |
+| `img` | `string` | — |  | Path to the background hero image |
+| `ariaDescription` | `string` | — |  | ARIA description, passed in as a markdown string. |
+| `notes` | `string` | — |  | Notes to the graphic, passed in as a markdown string. |
+| `class` | `string` | `''` |  | Add classes to the block tag to target it with custom CSS. |
+| `hedSize` | `HeadlineSize` | `'normal'` |  | Headline size: small, normal, big, bigger, biggest Options: `small`, `normal`, `big`, `bigger`, `biggest` |
+| `hedAlign` | `'left' \| 'center' \| 'right'` | `'center'` |  | Headline horizontal alignment: left, center, right Options: `left`, `center`, `right` |
+| `hedWidth` | `'normal' \| 'wide' \| 'wider' \| 'widest'` | `'normal'` |  | Width of the headline: normal, wide, wider, widest Options: `normal`, `wide`, `wider`, `widest` |
+| `dek` | `string \| Snippet` | — |  | Dek, parsed as a markdown string OR as a custom snippet. |
+| `section` | `string` | — |  | Section title |
+| `authors` | `string[]` | `[]` |  | Array of author names, which will be slugified to create links to Reuters author pages |
+| `publishTime` | `string` | — | ✓ | Publish time as a datetime string. |
+| `updateTime` | `string` | — |  | Update time as a datetime string. |
+| `width` | `'normal' \| 'wide' \| 'wider' \| 'widest'` | `'widest'` |  | Width of the hero graphic: normal, wide, wider, widest Options: `normal`, `wide`, `wider`, `widest` |
+| `embedded` | `boolean` | `false` |  | Set to true for embeds. |
+| `getAuthorPage` | `(author: string) => string` | — |  | Custom function that returns an author page URL. |
+| `byline` | `Snippet` | — |  | Optional snippet for a custom byline. |
+| `published` | `Snippet` | — |  | Optional snippet for a custom published dateline. |
+| `updated` | `Snippet` | — |  | Optional snippet for a custom updated dateline. |
+
+## Examples
+
+### Photo hero
+
+```svelte
+<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()}
+  img={polarImgSrc}
+  notes="Photo by REUTERS"
+  ariaDescription="A photo of a polar bear"
+/>
+```
+
+### Transparent header
+
+```svelte
+<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={['Jane Doe', 'John Doe']}
+    publishTime={new Date('2022-03-04').toISOString()}
+    img={polarImgSrc}
+    ariaDescription="A photo of a polar bear"
+  />
+</div>
+```
+
+### Ai2svelte hero
+
+```svelte
+<Block width="fluid" class="chromatic-ignore">
+  <SiteHeader />
+</Block>
+
+<HeroHeadline
+  hed={'Earthquake devastates Afghanistan'}
+  hedSize={'big'}
+  hedWidth="wide"
+  class="custom-hero mb-0"
+  authors={[
+    'Anand Katakam',
+    'Vijdan Mohammad Kawoosa',
+    'Adolfo Arranz',
+    'Wen Foo',
+    'Simon Scarr',
+    'Aman Bhargava',
+    'Jitesh Chowdhury',
+    'Manas Sharma',
+    'Aditi Bhandari',
+  ]}
+  publishTime={new Date('2022-06-24').toISOString()}
+>
+  <GraphicBlock
+    width="widest"
+    role="figure"
+    class="my-0"
+    ariaDescription="Earthquake impact map"
+  >
+    <QuakeMap />
+  </GraphicBlock>
+</HeroHeadline>
+```
+
+### Video hero
+
+```svelte
+<Block width="fluid" class="chromatic-ignore">
+  <SiteHeader />
+</Block>
+
+<HeroHeadline
+  class="video-hero"
+  hed="The conflict in Ethiopia"
+  hedSize="bigger"
+  hedWidth="wide"
+  authors={['Aditi Bhandari ', 'David Lewis']}
+  publishTime={new Date('2020-12-18').toISOString()}
+>
+  <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>
+```
+
+### Inline hero
+
+```svelte
+<Block width="fluid" class="chromatic-ignore">
+  <SiteHeader />
+</Block>
+
+<!-- Set `stacked` to `false` -->
+<HeroHeadline
+  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"
+  authors={['Simon Scarr', 'Vijdan Mohammad Kawoosa']}
+  publishTime={new Date('2020-01-01').toISOString()}
+>
+  <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>
+```
+
+### Custom hed
+
+```svelte
+<HeroHeadline
+  class="custom-hed"
+  authors={[
+    'Prasanta Kumar Dutta',
+    'Dea Bankova',
+    'Aditi Bhandari',
+    'Anurag Rao',
+  ]}
+  publishTime={new Date('2023-05-11').toISOString()}
+  img={eurovisImgSrc}
+  getAuthorPage={(author: string) => {
+    return `mailto:${author.replace(' ', '')}@example.com`;
+  }}
+>
+  {#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>
+```
+
+## Documentation
+
+# HeroHeadline
+
+The `HeroHeadline` component creates a Reuters Graphics headline with a hero media, which can be a graphic, photo, video or 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 insert the hero media inline -- i.e., before or after the headline -- by setting `stacked: false`. [Read more.](?/iframe.html?viewMode=docs\&id=components-text-elements-heroheadline--docs\&globals=\&args=#inline-hero)
+
+## 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 { asset } from '$app/paths'; // 👈 If using in the graphics kit...
+
+  let { embedded = false } = $props(); // 👈 If using in the graphics kit...
+</script>
+
+<HeroHeadline
+  {embedded}
+  img={asset('/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'}
+  authors={['Jane Doe', 'John Doe']}
+/>
+```
+
+## Transparent site 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 !important;
+}
+.hero-wrapper {
+  margin-block-start: -64px;
+}
+```
+
+## Ai2svelte hero
+
+To use an ai2svelte graphic as the hero, wrap your ai2svelte component in a `GraphicBlock` component and insert it inside `HeroHeadline`.
+
+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'; // Your ai2svelte component
+
+  import { asset } from '$app/paths'; // 👈 If using in the graphics kit...
+
+  let { embedded = false } = $props(); // 👈 If using in the graphics kit...
+</script>
+
+<HeroHeadline
+  {embedded}
+  hed="Earthquake devastates Afghanistan"
+  hedSize="big"
+  hedWidth="wide"
+  class="custom-hero mb-0"
+  authors={[
+    'Anand Katakam',
+    'Vijdan Mohammad Kawoosa',
+    'Adolfo Arranz',
+    'Wen Foo',
+    'Simon Scarr',
+    'Aman Bhargava',
+    'Jitesh Chowdhury',
+    'Manas Sharma',
+    'Aditi Bhandari',
+  ]}
+  publishTime={new Date('2022-06-24').toISOString()}
+>
+  <GraphicBlock
+    width="widest"
+    role="figure"
+    class="my-0"
+    ariaDescription="Earthquake impact map"
+  >
+    <!-- Pass `assetsPath` if in graphics kit -->
+    <QuakeMap assetsPath={asset('/').replace(/\/$/, '')} />
+  </GraphicBlock>
+</HeroHeadline>
+```
+
+Add styles in `global.scss`:
+
+```scss
+// global.scss
+// Customise styles using the class (e.g. `custom-hero` here) passed to `HeroHeadline`
+.hero-wrapper {
+  .custom-hero.headline {
+    // Adjust vertical positioning
+    align-items: flex-end !important;
+
+    @media (max-width: 1100px) {
+      // Adjust line length of title
+      max-width: var(--normal-column-width) !important;
+    }
+  }
+
+  // Make hero shorter than 100vh
+  --heroHeight: 85svh;
+
+  @media (max-width: 960px) {
+    --heroHeight: 65svh;
+  }
+
+  // For small height
+  @media (max-height: 850px) {
+    --heroHeight: 100svh;
+  }
+
+  // Custom hero sizing for landscape mobile
+  @media (max-width: 960px) and (orientation: landscape) {
+    --heroHeight: 200svh;
+  }
+}
+
+// Override default fixed height for hero layout in embeds
+.hero-wrapper.embedded {
+  --heroHeight: 1000px;
+}
+```
+
+## Video hero
+
+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 { asset } from '$app/paths'; // 👈 If using in the graphics kit...
+
+  let { embedded = false } = $props(); // 👈 If using in the graphics kit...
+</script>
+
+<HeroHeadline
+  {embedded}
+  class="video-hero"
+  hed="The conflict in Ethiopia"
+  hedSize="bigger"
+  hedWidth="wide"
+  authors={['Aditi Bhandari ', 'David Lewis']}
+  publishTime={new Date('2020-12-18').toISOString()}
+>
+  <Video
+    width="widest"
+    class="my-0"
+    showControls={false}
+    preloadVideo="auto"
+    playVideoWhenInView={false}
+    src={asset('/videos/intro.mp4')}
+    poster={asset('/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>
+```
+
+Add styles in `global.scss`:
+
+```scss
+// global.scss
+// Customise styles using the class (e.g. `video-hero` here) passed to `HeroHeadline`
+.hero-wrapper {
+  --heroHeight: calc(100svh - 60px);
+  .video-hero.headline {
+    header {
+      // Adjust vertical position as offset from default center
+      top: calc(50svh - 250px);
+    }
+
+    h1 {
+      color: #ffd430;
+      text-shadow: 3px 4px 7px rgba(81, 67, 21, 0.8);
+    }
+  }
+}
+```
+
+## Inline hero
+
+To use a photo, graphic, video, etc. as an inline hero -- i.e., to make the hero appear _after_ the headline and dek, instead of stacked underneath -- set `stacked` to `false`. Otherwise, add your hero media in the same way as documented above.
+
+```svelte
+<!-- App.svelte -->
+<script>
+  import {
+    HeroHeadline,
+    GraphicBlock,
+  } from '@reuters-graphics/graphics-components';
+  import { asset } from '$app/paths'; // 👈 If using in the graphics kit...
+
+  let { embedded = false } = $props(); // 👈 If using in the graphics kit...
+</script>
+
+<!-- Set `stacked` to `false` -->
+<HeroHeadline
+  {embedded}
+  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"
+  authors={['Simon Scarr', 'Vijdan Mohammad Kawoosa']}
+  publishTime={new Date('2020-01-01').toISOString()}
+>
+  <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={asset('/').replace(/\/$/, '')} />
+  </GraphicBlock>
+</HeroHeadline>
+```
+
+## Custom hed, dek and byline
+
+The `HeroHeadline` component internally uses the [Headline](?path=/docs/components-text-elements-headline--docs) component to render the headline and dek, which lets you to customise the headline and dek by passing [snippets](https://svelte.dev/docs/svelte/snippet) into the `hed` and `dek` props.
+
+Since `Headline` internally uses the [Byline](?path=/docs/components-text-elements-headline--docs) component, you can also customise the author page hyperlink and bylines with the `getAuthorPage`, `byline`, `published` and `updated` props.
+
+```svelte
+<!-- App.svelte -->
+<HeroHeadline
+  class="custom-hed"
+  authors={[
+    'Prasanta Kumar Dutta',
+    'Dea Bankova',
+    'Aditi Bhandari',
+    'Anurag Rao',
+  ]}
+  publishTime={new Date('2023-05-11').toISOString()}
+  img={eurovisImgSrc}
+  getAuthorPage={(author) => {
+    return `mailto:${author.replace(' ', '')}@example.com`;
+  }}
+>
+  <!-- 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}
+
+  <!-- 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}
+</HeroHeadline>
+```
+
+Add styles in `global.scss`:
+
+```scss
+// global.scss
+.custom-hed {
+  h1 {
+    .body-note {
+      color: #ffffff;
+    }
+    .title {
+      color: #ffffff;
+      text-shadow: 1px 1px 8px #ff7c88;
+      filter: drop-shadow(0px 0px 12px #ff7c88);
+    }
+  }
+
+  .dek {
+    margin-block-start: 1rem;
+    p {
+      color: #ffffff;
+      text-shadow: 1px 1px 8px #ff7c88;
+      filter: drop-shadow(0px 0px 12px #ff7c88);
+    }
+  }
+}
+```