@reuters-graphics/graphics-components 3.10.0 → 3.10.1

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

@@ -0,0 +1,11 @@
+# AdSlot
+
+**Import:** `import { AdSlot } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `placementName` | `DesktopPlacementName \| MobilePlacementName` | — | ✓ | — |
+| `adType` | `DesktopAdType \| MobileAdType` | — | ✓ | — |
+| `dataFreestarAd` | `string` | `'__970x250'` |  | — |

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

@@ -0,0 +1,89 @@
+# Analytics
+
+**Category:** Components/Ads & analytics/Analytics
+
+**Import:** `import { Analytics } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `authors` | `Author[]` | `[]` |  | Used to associate a page with its author(s) in Chartbeat. |
+
+## Examples
+
+### Demo
+
+```svelte
+<Analytics authors={[{ name: 'Jane Doe' }, { name: 'John Doe' }]} />
+```
+
+## Documentation
+
+# Analytics
+
+The `Analytics` component adds Google and Chartbeat analytics to your page.
+
+```svelte
+<script>
+  import { Analytics } from '@reuters-graphics/graphics-components';
+
+  const authors = [{ name: 'Jane Doe' }, { name: 'John Doe' }];
+</script>
+
+<Analytics {authors} />
+```
+
+## Environments
+
+Generally, you only want to send page analytics in production environments.
+
+In a SvelteKit context, you can use `$app` stores to restrict when you send analytics.
+
+For example, the following excludes analytics from pages in development or hosted on our preview server:
+
+```svelte
+<script>
+  import { Analytics } from '@reuters-graphics/graphics-components';
+  import { dev } from '$app/environment';
+  import { page } from '$app/stores';
+</script>
+
+{#if !dev && $page.url?.hostname !== 'graphics.thomsonreuters.com'}
+  <Analytics />
+{/if}
+```
+
+## Multipage apps
+
+If you're using analytics to measure a multipage newsapp that uses [client-side routing](https://kit.svelte.dev/docs/glossary#routing), then you may need to trigger analytics after virtual page navigation.
+
+This component exports a function you can call to register pageviews.
+
+For example, here's how you can use SvelteKit's [`afterNavigate`](https://kit.svelte.dev/docs/modules#$app-navigation-afternavigate) lifecycle to capture additional pageviews:
+
+```svelte
+<script>
+  import {
+    Analytics,
+    registerPageview,
+  } from '@reuters-graphics/graphics-components';
+  import { afterNavigate } from '$app/navigation';
+
+  let isFirstPageview = true;
+
+  afterNavigate(() => {
+    // We shouldn't fire on initial page load because the Analytics component
+    // already registers a reader's first pageview. After this component
+    // has initially mounted, we can be sure that further navigation is virtual
+    // and register pageviews using this function.
+    if (!isFirstPageview) {
+      registerPageview();
+    } else {
+      isFirstPageview = false;
+    }
+  });
+</script>
+
+<Analytics />
+```

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

@@ -0,0 +1,183 @@
+# Article
+
+**Category:** Components/Page layout/Article
+
+**Import:** `import { Article } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `embedded` | `boolean` | `false` |  | Set to true for embeddables. |
+| `id` | `string` | `''` |  | Add an id to the article tag to target it with custom CSS. |
+| `role` | `string \| null` | `null` |  | ARIA role of the article |
+| `columnWidths` | `ColumnWidths` | `{
+      narrower: 330,
+      narrow: 510,
+      normal: 660,
+      wide: 930,
+      wider: 1200,
+    }` |  | Set custom widths for the normal, wide and wider column dimensions |
+| `children` | `import('svelte').Snippet` | — |  | — |
+
+## Examples
+
+### Demo
+
+```svelte
+<Article id="article-story-basic">
+  <div class="demo-container">
+    <div class="background-label">Article well</div>
+    <div class="padding-label"><span>⇤</span>15px padding</div>
+  </div>
+</Article>
+```
+
+### Custom columns
+
+```svelte
+<h3>Default column widths</h3>
+
+<Article id="article-column-widths-demo">
+  <div class="article-boundaries">
+    <Block id="section-demo" width="narrower">narrower</Block>
+    <Block id="section-demo" width="narrow">narrow</Block>
+    <Block id="section-demo">normal</Block>
+    <Block id="section-demo" width="wide">wide</Block>
+    <Block id="section-demo" width="wider">wider</Block>
+    <Block id="section-demo" width="widest">widest</Block>
+    <Block id="section-demo" width="fluid">fluid</Block>
+  </div>
+</Article>
+<h3>Custom column widths</h3>
+<Article
+  id="article-column-widths-demo"
+  columnWidths={{
+    narrower: 250,
+    narrow: 400,
+    normal: 500,
+    wide: 675,
+    wider: 1400,
+  }}
+>
+  <div class="article-boundaries custom">
+    <Block id="section-demo" width="narrower">narrower</Block>
+    <Block id="section-demo" width="narrow">narrow</Block>
+    <Block id="section-demo">normal</Block>
+    <Block id="section-demo" width="wide">wide</Block>
+    <Block id="section-demo" width="wider">wider</Block>
+    <Block id="section-demo" width="widest">widest</Block>
+    <Block id="section-demo" width="fluid">fluid</Block>
+  </div>
+</Article>
+```
+
+## Documentation
+
+# Article
+
+The `Article` component contains all the contents of our story.
+
+> 📌 In most cases, **you don't need to mess with the `Article` component** because it's already set up in the graphics kit.
+
+```svelte
+<script>
+  import { Article } from '@reuters-graphics/graphics-components';
+</script>
+
+<Article>
+  <!-- The story content goes here! -->
+</Article>
+```
+
+## Custom column widths
+
+The `Article` component also establishes the widths of columns that contain individual sections of the story, such as text, photos, and charts. The default column widths follow a basic class scheme:
+
+- `narrower` The narrowest...
+- `narrow` A bit narrower than the default body text column
+- `normal` **The default width of the body text column**
+- `wide` A bit wider
+- `wider` A bit wider than wide...
+- `widest` Edge-to-edge, but _excluding_ the left and right padding on `Article`
+- `fluid` Fully edge-to-edge
+
+You can set custom column widths by passing an object to the `columnWidths` prop with pixel values for the `narrower`, `narrow`, `normal`, `wide` and `wider` classes. These can then be used by the `Block` component or other elements housed inside `<Article>`.
+
+> **For most graphics kit pages, you shouldn't customise the column widths.** Other Reuters tools, like our AI templates, use our default column widths, so customising those widths here has downstream consequences for graphics made outside graphics kit. The main exception is SREP stories.
+
+```svelte
+<!-- Set custom column widths -->
+<Article
+  columnWidths={{
+    narrower: 310,
+    narrow: 450,
+    normal: 550,
+    wide: 675,
+    wider: 1400,
+  }}
+>
+  <!-- Custom column widths get passed down to the `Block` component -->
+  <Block width="narrower" />
+  <Block width="narrow" />
+  <Block width="normal" />
+  <Block width="wide" />
+  <Block width="wider" />
+  <Block width="widest" />
+  <Block width="fluid" />
+</Article>
+```
+
+If you're not using our `Block` component, you can still inherit the column widths from `Article` and create your own custom containers by using [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) like this:
+
+```svelte
+<div class="my-special-container">
+  <!-- Story content -->
+</div>
+
+<style lang="scss">
+  div.my-special-container {
+    max-width: var(--wide-column-width);
+  }
+</style>
+```
+
+... or you can make your column widths entirely configurable by adding classes and manually specifying widths:
+
+```svelte
+<script>
+  let { width = 'normal' } = $props();
+</script>
+
+<div class="my-special-container {width}">
+  <!-- Story content -->
+</div>
+
+<style lang="scss">
+  div.my-special-container {
+    max-width: var(--normal-column-width);
+    &.narrower {
+      max-width: var(--narrower-column-width);
+    }
+    &.narrow {
+      max-width: var(--narrow-column-width);
+    }
+    &.wide {
+      max-width: var(--wide-column-width);
+    }
+    &.wider {
+      max-width: var(--wider-column-width);
+    }
+    &.widest {
+      max-width: 100%;
+    }
+    &.fluid {
+      width: calc(100% + 30px);
+      margin-inline-start: -15px;
+      max-width: none;
+    }
+  }
+</style>
+```
+
+Here's an example of how  `columnWidths` can be used to change column widths:

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

@@ -0,0 +1,170 @@
+# BeforeAfter
+
+**Category:** Components/Multimedia/BeforeAfter
+
+**Import:** `import { BeforeAfter } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `width` | `ContainerWidth` | `'normal'` |  | Width of the chart within the text well. Options: wide, wider, widest, fluid Options: `normal`, `wide`, `wider`, `widest`, `fluid` |
+| `height` | `number` | `600` |  | Height of the component |
+| `heightRatio` | `number` | — |  | If set, makes the height a ratio of the component's width. |
+| `beforeSrc` | `string` | — | ✓ | Before image source |
+| `beforeAlt` | `string` | — | ✓ | Before image altText |
+| `afterSrc` | `string` | — | ✓ | After image source |
+| `afterAlt` | `string` | — | ✓ | After image altText |
+| `class` | `string` | `''` |  | Class to target with SCSS. |
+| `handleColour` | `string` | `'white'` |  | Drag handle colour |
+| `handleInactiveOpacity` | `number` | `0.9` |  | Drag handle opacity |
+| `handleMargin` | `number` | `20` |  | Margin at the edge of the image to stop dragging |
+| `keyPressStep` | `number` | `0.05` |  | Percentage of the component width the handle will travel ona key press |
+| `offset` | `number` | `0.5` |  | Initial offset of the handle, between 0 and 1. |
+| `id` | `string` | `'before-after-' + random4() + random4()` |  | ID to target with SCSS. |
+| `beforeOverlay` | `Snippet` | — |  | Optional snippet for a custom overlay for the before image. |
+| `afterOverlay` | `Snippet` | — |  | Optional snippet for a custom overlay for the after image. |
+| `caption` | `Snippet` | — |  | Optional snippet for a custom caption. |
+| `ariaLabel` | `string` | `'Stacked before and after images with an adjustable slider'` |  | Custom ARIA label language to label the component. |
+
+## Examples
+
+### Demo
+
+```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."
+/>
+```
+
+### With text
+
+```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."
+>
+  {#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>
+```
+
+## Documentation
+
+# 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."
+/>
+```
+
+## Using with ArchieML docs
+
+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}
+```
+
+## Adding text
+
+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.
+
+```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."
+>
+  <!-- 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">
+  .overlay {
+    background: rgba(0, 0, 0, 0.45);
+    max-width: 350px;
+    &.after {
+      text-align: right;
+    }
+    p {
+      color: #ffffff;
+    }
+  }
+</style>
+```

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

@@ -0,0 +1,74 @@
+# BioBox
+
+BioBox shows one or more author biographies in a bordered box, echoing the contributor box on Reuters.com stories.
+
+**Category:** Components/Page furniture/BioBox
+
+**Import:** `import { BioBox } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `authors` | `Author[]` | — | ✓ | Authors to display, in order. |
+| `id` | `string` | `''` |  | ID on the containing block. |
+| `class` | `string` | `'fmy-8'` |  | Extra classes on the containing block. |
+
+## Examples
+
+### Demo
+
+```svelte
+<BioBox authors={/* authors */} />
+```
+
+### Single author
+
+```svelte
+<BioBox authors={[authors[1]]} />
+```
+
+### Logo fallback
+
+```svelte
+<BioBox authors={/* array — see Props/Types for full type */} />
+```
+
+## Documentation
+
+# BioBox
+
+The `BioBox` component shows one or more author biographies in a bordered box, echoing the contributor box at the bottom of Reuters.com stories.
+
+Each author can include a name, job title, short bio, avatar image and a row of contact and social links (email, X, LinkedIn, Facebook, Instagram, Bluesky or a generic link). When no avatar is provided, the Reuters Kinesis logo is shown instead.
+
+On narrow screens the social links move below the bio text so names and titles stay readable.
+
+```svelte
+<script>
+  import { BioBox } from '@reuters-graphics/graphics-components';
+
+  const authors = [
+    {
+      name: 'Ben Welsh',
+      title: 'News Applications Editor',
+      bio: 'Ben Welsh leads the development of dashboards, databases and other automated systems.',
+      imageUrl: 'https://www.reuters.com/.../avatar.jpg',
+      links: [
+        { platform: 'email', url: 'ben.welsh@thomsonreuters.com' },
+        { platform: 'x', url: 'https://x.com/palewire' },
+        { platform: 'linkedin', url: 'https://www.linkedin.com/in/palewire' },
+        { platform: 'link', url: 'https://palewi.re/who-is-ben-welsh/' },
+      ],
+    },
+  ];
+</script>
+
+<BioBox {authors} />
+```
+
+## Single author
+
+## Logo fallback
+
+When an author has no `imageUrl`, the box falls back to the Reuters Kinesis logo.