@reuters-graphics/graphics-components 3.9.0 → 3.10.1

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

@@ -0,0 +1,242 @@
+# Byline
+
+**Category:** Components/Text elements/Byline
+
+**Import:** `import { Byline } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `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. |
+| `align` | `'auto' \| 'center'` | `'auto'` |  | Alignment of the byline. Options: `auto`, `center` |
+| `id` | `string` | `''` |  | Add an id to to target with custom CSS. |
+| `cls` | `string` | `''` |  | Add extra classes to target with custom CSS. |
+| `getAuthorPage` | `(author: string) => string` | `getAuthorPageUrl` |  | 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
+
+### Demo
+
+```svelte
+<Byline
+  authors={/* authors */}
+  publishTime={new Date('2021-09-12').toISOString()}
+  updateTime={new Date('2021-09-12T13:57:00').toISOString()}
+/>
+```
+
+### Customised
+
+```svelte
+<Byline publishTime="2021-09-12T00:00:00Z" updateTime="2021-09-12T13:57:00Z">
+  {#snippet byline()}
+    <strong>BY REUTERS GRAPHICS</strong>
+  {/snippet}
+  {#snippet published()}
+    PUBLISHED on some custom date and time
+  {/snippet}
+  {#snippet updated()}
+    <em>Updated every 5 minutes</em>
+  {/snippet}
+</Byline>
+```
+
+### Translation
+
+```svelte
+In locale = `es`:
+<Byline
+  publishTime="2021-09-12T00:00:00Z"
+  {authors}
+  byline={locale === 'es' ? esByline : undefined}
+  published={locale === 'es' ? esPublished : undefined}
+></Byline>
+
+In locale = `en`:
+<Byline
+  publishTime="2021-09-12T00:00:00Z"
+  {authors}
+  byline={undefined}
+  published={undefined}
+/>
+```
+
+### Custom author page
+
+```svelte
+<Byline
+  authors={/* authors */}
+  publishTime="2021-09-12T00:00:00Z"
+  updateTime="2021-09-12T13:57:00Z"
+  getAuthorPage={(author: string) => {
+      return `mailto:${author.replace(' ', '')}@example.com`;
+    }}
+/>
+```
+
+## Documentation
+
+# Byline
+
+The `Byline` component adds a byline, published and updated datelines to your page.
+
+```svelte
+<script>
+  import { Byline } from '@reuters-graphics/graphics-components';
+</script>
+
+<Byline
+  authors={[
+    'Dea Bankova',
+    'Prasanta Kumar Dutta',
+    'Anurag Rao',
+    'Mariano Zafra',
+  ]}
+  publishTime="2021-09-12T00:00:00.000Z"
+  updateTime="2021-09-12T12:57:00.000Z"
+/>
+```
+
+## Using with ArchieML docs
+
+With the graphics kit, you'll likely get your text value from an ArchieML doc...
+
+```yaml
+# ArchieML doc
+[authors]
+* Dea Bankova
+* Prasanta Kumar Dutta
+* Anurag Rao
+* Mariano Zafra
+[]
+publishTime: 2021-09-12T00:00:00.000Z
+updateTime: 2021-09-12T12:57:00.000Z
+```
+
+... which you'll pass to the `Byline` component.
+
+```svelte
+<script>
+  import { Byline } from '@reuters-graphics/graphics-components';
+  let { content }: Props = $props();
+</script>
+
+<Byline
+  authors={content.authors}
+  publishTime={content.publishTime}
+  updateTime={content.updateTime}
+/>
+```
+
+## Custom byline, published and updated datelines
+
+Use [snippets](https://svelte.dev/docs/svelte/snippet) to customise the byline, published and updated datelines.
+
+```svelte
+<Byline publishTime="2021-09-12T00:00:00Z" updateTime="2021-09-12T13:57:00Z">
+  <!-- Optional custom byline -->
+  {#snippet byline()}
+    <strong>BY REUTERS GRAPHICS</strong>
+  {/snippet}
+
+  <!-- Optional custom published dateline -->
+  {#snippet published()}
+    PUBLISHED on some custom date and time
+  {/snippet}
+
+  <!-- Optional custom updated dateline -->
+  {#snippet updated()}
+    <em>Updated every 5 minutes</em>
+  {/snippet}
+</Byline>
+```
+
+## Translated byline and datelines
+
+Use [snippets](https://svelte.dev/docs/svelte/snippet) to conditionally customise the byline, published and updated datelines for different languages.
+
+```svelte
+<!-- In App.svelte -->
+<script>
+  import {
+    Byline,
+    getAuthorPageUrl,
+    formatTime,
+  } from '@reuters-graphics/graphics-components';
+
+  let { content }: Props = $props();
+
+  // Note: In graphics kit, `locale` is already defined in `App.svelte`
+</script>
+```
+
+```svelte
+<!-- In App.svelte -->
+<!-- Define custom translation snippets for different languages above the <Byline/> component -->
+{#snippet esByline()}
+  Por
+  {#each content.authors as author, i}
+    <a
+      class="no-underline whitespace-nowrap text-primary font-bold"
+      href={getAuthorPageUrl(author)}
+      rel="author"
+    >
+      {author.trim()}</a
+    >{#if content.authors.length > 1 && i < content.authors.length - 2},{/if}
+    {#if content.authors.length > 1 && i === content.authors.length - 2}y&nbsp;{/if}
+  {/each}
+{/snippet}
+
+{#snippet esPublished()}
+  Publicado <time datetime="2026-04-08T10:00:00.000Z">
+    {new Date(content.publishTime).toLocaleDateString('es-ES', {
+      year: 'numeric',
+      month: 'long',
+      day: 'numeric',
+    })}&nbsp;&nbsp;{formatTime(content.publishTime)}</time
+  >
+{/snippet}
+```
+
+```svelte
+<!-- In App.svelte -->
+<!-- Conditionally render custom translation snippets depending on the locale -->
+<Byline
+  authors={content.authors}
+  publishTime={content.publishTime}
+  byline={locale === 'es' ? esByline : undefined}
+  published={locale === 'es' ? esPublished : undefined}
+/>
+```
+
+## Custom author page
+
+By default, the `Byline` component will hyperlink each author's byline to their Reuters.com page, formatted `https://www.reuters.com/authors/{author-slug}/`.
+
+To hyperlink to different pages or email addresses, pass a custom function to the `getAuthorPage` prop.
+
+```svelte
+<!-- Pass a custom function as `getAuthorPage` -->
+<Byline
+  authors={[
+    'Dea Bankova',
+    'Prasanta Kumar Dutta',
+    'Anurag Rao',
+    'Mariano Zafra',
+  ]}
+  publishTime="2021-09-12T00:00:00Z"
+  updateTime="2021-09-12T13:57:00Z"
+  getAuthorPage={(author) => {
+    return `mailto:${author.replace(' ', '')}@example.com`;
+  }}
+/>
+```
+
+```
+```

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

@@ -0,0 +1,48 @@
+# ClockWall
+
+**Category:** Components/Blog/ClockWall
+
+**Import:** `import { ClockWall } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `cities` | `City[]` | `[
+      { name: 'Tehran', tzIdentifier: 'Asia/Tehran' },
+      { name: 'Tel Aviv', tzIdentifier: 'Asia/Tel_Aviv' },
+      { name: 'Washington D.C.', tzIdentifier: 'America/New_York' },
+    ]` |  | — |
+| `width` | `ContainerWidth` | `'normal'` |  | — |
+| `clockSize` | `ClockProps['clockSize']` | `'XS'` |  | — Options: `XS`, `MD`, `LG`, `XL` |
+| `clockWeight` | `ClockProps['clockWeight']` | `'Bold'` |  | — Options: `Light`, `Normal`, `Bold` |
+
+## Examples
+
+### Demo
+
+```svelte
+<ClockWall />
+```
+
+## Documentation
+
+# ClockWall
+
+The `ClockWall` component displays a row of analog clocks for different cities and timezones. Use it paired with the overall headline of a graphics blog page to show the time of multiple cities involved in a breaking news event.
+
+Use the [IANA tz database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) to find valid `tzIdentifier` strings.
+
+```svelte
+<script>
+  import { ClockWall } from '@reuters-graphics/graphics-components';
+</script>
+
+<ClockWall
+  cities={[
+    { name: 'Tehran', tzIdentifier: 'Asia/Tehran' },
+    { name: 'Tel Aviv', tzIdentifier: 'Asia/Tel_Aviv' },
+    { name: 'Washington D.C.', tzIdentifier: 'America/New_York' },
+  ]}
+/>
+```

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

@@ -0,0 +1,87 @@
+# DatawrapperChart
+
+**Category:** Components/Graphics/DatawrapperChart
+
+**Import:** `import { DatawrapperChart } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `title` | `string` | — |  | Title of the graphic |
+| `description` | `string` | — |  | Description of the graphic, passed in as a markdown string. |
+| `frameTitle` | `string` | `''` |  | iframe title |
+| `notes` | `string` | — |  | Notes to the graphic, passed in as a markdown string. |
+| `ariaLabel` | `string` | `''` |  | iframe aria label |
+| `id` | `string` | `''` |  | — |
+| `src` | `string` | — | ✓ | Datawrapper embed URL |
+| `scrolling` | `ScrollingOption` | `'no'` |  | iframe scrolling option |
+| `width` | `ContainerWidth` | `'normal'` |  | Width of the chart within the text well. Options: `normal`, `wide`, `wider`, `widest`, `fluid` |
+| `textWidth` | `ContainerWidth` | `'normal'` |  | Set a different width for the text within the text well, for example, "normal" to keep the title, description and notes inline with the rest of the text well. Can't ever be wider than `width`. |
+| `titleSnippet` | `Snippet` | — |  | Custom headline and chatter snippet |
+| `notesSnippet` | `Snippet` | — |  | Custom notes and source snippet |
+
+## Examples
+
+### Demo
+
+```svelte
+<DatawrapperChart
+  src="https://reuters.com/graphics/USA-ABORTION/lgpdwggnwvo/media-embed.html"
+  id="abortion-rights-map"
+  ariaLabel="map"
+  frameTitle="Global abortion access"
+/>
+```
+
+### With chatter
+
+```svelte
+<DatawrapperChart
+  frameTitle="Global abortion access"
+  ariaLabel="map"
+  id="abortion-rights-map"
+  src="https://reuters.com/graphics/USA-ABORTION/lgvdwemlbpo/media-embed.html"
+  title="Global abortion access"
+  description="A map of worldwide access to abortion."
+  notes={/* value — see Props/Types for full type */}
+/>
+```
+
+## Documentation
+
+# DatawrapperChart
+
+Easily add a responsive Datawrapper embed on your page.
+
+```svelte
+<script>
+  import { DatawrapperChart } from '@reuters-graphics/graphics-components';
+</script>
+
+<DatawrapperChart
+  title="Global abortion access"
+  ariaLabel="map"
+  id="abortion-rights-map"
+  src="https://graphics.reuters.com/USA-ABORTION/lgpdwggnwvo/media-embed.html"
+/>
+```
+
+##### Getting the chart URL for `src`
+
+Copy the source url for the Datawrapper chart in the `src` prop.
+You can get this from the published url on Reuters Graphics.
+
+- Publish the chart on Datawrapper.
+- Go to the **Datawrapper charts** Teams channel, wait for the graphic to finish publishing.
+- Inside **Embed code (for developers only)**, find and copy the url inside the `src` prop. (It ends in `media-embed.html`.)
+
+**Note:** There is no need to update the url if you update the chart inside Datawrapper. Any changes will be automatically reflected.
+
+## With chatter
+
+By default, Datawrapper will export your chart with the chart chatter like title, description and notes.
+
+At the moment, these don't _exactly_ match our styles and can't be made to fit into the article well.
+
+Instead, it's often better to remove all the text from your Datawrapper chart before publishing it and add that text back via the component props.

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

@@ -0,0 +1,47 @@
+# DocumentCloud
+
+**Category:** Components/Multimedia/DocumentCloud
+
+**Import:** `import { DocumentCloud } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `slug` | `string` | — | ✓ | The unique identifier for the document. |
+| `altText` | `string` | — | ✓ | Alt text for the document. |
+| `width` | `ContainerWidth` | `'normal'` |  | Width of the container, one of: normal, wide, wider, widest or fluid Options: `normal`, `wide`, `wider`, `widest`, `fluid` |
+| `id` | `string` | `''` |  | Add an ID to target with SCSS. |
+| `class` | `string` | `''` |  | Add a class to target with SCSS. |
+
+## Examples
+
+### Demo
+
+```svelte
+<DocumentCloud
+  slug="3259984-Trump-Intelligence-Allegations"
+  altText="These Reports Allege Trump Has Deep Ties To Russia"
+/>
+```
+
+## Documentation
+
+# DocumentCloud
+
+The `DocumentCloud` component embeds a document hosted by [DocumentCloud](https://documentcloud.org).
+
+The document must have its access level set to **public** before it can be embedded. The `slug` can be found after the final slash in the document's URL.
+
+For instance, the document included in the example is found at [documentcloud.org/documents/3259984-Trump-Intelligence-Allegations](https://www.documentcloud.org/documents/3259984-Trump-Intelligence-Allegations). The `slug` is `3259984-Trump-Intelligence-Allegations`.
+
+```svelte
+<script>
+  import { DocumentCloud } from '@reuters-graphics/graphics-components';
+</script>
+
+<DocumentCloud
+  slug="3259984-Trump-Intelligence-Allegations"
+  altText="These Reports Allege Trump Has Deep Ties To Russia"
+/>
+```

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

@@ -0,0 +1,35 @@
+# EmbedPreviewerLink
+
+**Category:** Components/Utilities/EmbedPreviewerLink
+
+**Import:** `import { EmbedPreviewerLink } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `dev` | `boolean` | `false` |  | — |
+
+## Examples
+
+### Demo
+
+```svelte
+<EmbedPreviewerLink dev={true} />
+```
+
+## Documentation
+
+# EmbedPreviewerLink
+
+The `EmbedPreviewerLink` component is a tool for previewing the embeds in development. It adds an icon at the bottom of the page that, when clicked, opens a previewer with the embeds.
+
+```svelte
+<script>
+  import { EmbedPreviewerLink } from '@reuters-graphics/graphics-components';
+
+  import { dev } from '$app/env';
+</script>
+
+<EmbedPreviewerLink {dev} />
+```

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

@@ -0,0 +1,79 @@
+# EndNotes
+
+**Category:** Components/Text elements/EndNotes
+
+**Import:** `import { EndNotes } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `notes` | `EndNote[]` | — | ✓ | An array of endnote items. |
+
+## Examples
+
+### Demo
+
+```svelte
+<EndNotes notes={/* array — see Props/Types for full type */} />
+```
+
+## Documentation
+
+# EndNotes
+
+The `EndNotes` component adds notes such as sources, clarifiying notes and minor corrections that come at the end of a story.
+
+```svelte
+<script>
+  import { EndNotes } from '@reuters-graphics/graphics-components';
+
+  const notes = [
+    {
+      title: 'Note',
+      text: 'Data is current as of today.',
+    },
+    {
+      title: 'Sources',
+      text: 'Data, Inc.',
+    },
+    {
+      title: 'Edited by',
+      text: '<a href="https://www.reuters.com/graphics/">Editor</a>, Copyeditor',
+    },
+  ];
+</script>
+
+<EndNotes {notes} />
+```
+
+## Using with ArchieML docs
+
+With the graphics kit, you'll likely get your text value from an ArchieML doc...
+
+```yaml
+# ArchieML doc
+[endNotes]
+title: Note
+text: Data is current as of today
+
+title: Sources
+text: Data, Inc.
+
+title: Edited by
+text: Editor, Copyeditor
+[]
+```
+
+... which you'll pass to the `EndNotes` component.
+
+```svelte
+<!-- graphics kit -->
+<script>
+  import { EndNotes } from '@reuters-graphics/graphics-components';
+
+  import content from '$locales/en/content.json';
+</script>
+
+<EndNotes notes={content.endNotes} />
+```

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

@@ -0,0 +1,102 @@
+# FeaturePhoto
+
+**Category:** Components/Multimedia/FeaturePhoto
+
+**Import:** `import { FeaturePhoto } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `src` | `string` | — | ✓ | Photo source |
+| `altText` | `string` | — | ✓ | Photo altText |
+| `id` | `string` | `''` |  | Add an id to target with custom CSS. |
+| `class` | `string` | `''` |  | Add classes to target with custom CSS. |
+| `caption` | `string` | — |  | Photo caption |
+| `height` | `number` | `100` |  | Height of the photo placeholder when lazy-loading |
+| `width` | `ContainerWidth` | `'normal'` |  | Width of the container: normal, wide, wider, widest or fluid Options: `normal`, `wide`, `wider`, `widest`, `fluid` |
+| `textWidth` | `ContainerWidth` | `'normal'` |  | Set a different width for the text vs the photo. For example, "normal" to keep the title, description and notes inline with the rest of the text well. Can't ever be wider than `width`. Options: `normal`, `wide`, `wider`, `widest`, `fluid` |
+| `lazy` | `boolean` | `true` |  | Whether to lazy load the photo using the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) |
+| `top` | `number` | `0` |  | Set Intersection Observer [rootMargin](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#rootmargin) `top` when lazy loading. |
+| `bottom` | `number` | `0` |  | Set Intersection Observer [rootMargin](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#rootmargin) `bottom` when lazy loading. |
+| `left` | `number` | `0` |  | Set Intersection Observer [rootMargin](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#rootmargin) `left` when lazy loading. |
+| `right` | `number` | `0` |  | Set Intersection Observer [rootMargin](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#rootmargin) `right` when lazy loading. |
+
+## Examples
+
+### Demo
+
+```svelte
+<FeaturePhoto src={/* sharkSrc */} altText="A shark!" caption="Carcharodon carcharias - REUTERS" />
+```
+
+### Missing altText
+
+```svelte
+<FeaturePhoto src={/* sharkSrc */} caption="Carcharodon carcharias - REUTERS" />
+```
+
+## Documentation
+
+# FeaturePhoto
+
+The `FeaturePhoto` component adds a full-width photo.
+
+```svelte
+<script>
+  import { FeaturePhoto } from '@reuters-graphics/graphics-components';
+  import { assets } from '$app/paths'; // 👈 If using in the graphics kit...
+</script>
+
+<FeaturePhoto
+  src={`${assets}/images/myImage.jpg`}
+  altText="Some alt text"
+  caption="A caption"
+/>
+```
+
+## Using with ArchieML docs
+
+With the graphics kit, you'll likely get your text value from an ArchieML doc...
+
+```yaml
+# ArchieML doc
+[blocks]
+
+type: photo
+width: normal
+src: images/shark.jpg
+altText: The king of the sea
+caption: Carcharodon carcharias - REUTERS
+
+[]
+```
+
+... which you'll parse out of a ArchieML block object before passing to the `FeaturePhoto` component.
+
+```svelte
+<!-- App.svelte -->
+<script>
+  import { FeaturePhoto } from '@reuters-graphics/graphics-components';
+
+  import content from '$locales/en/content.json';
+  import { assets } from '$app/paths';
+</script>
+
+{#each content.blocks as block}
+  {#if block.Type === 'text'}
+    <!-- ... -->
+  {:else if block.type === 'photo'}
+    <FeaturePhoto
+      width={block.width}
+      src={`${assets}/${block.src}`}
+      altText={block.altText}
+      caption={block.caption}
+    />
+  {/if}
+{/each}
+```
+
+## Missing alt text
+
+`altText` is required in this component. If your photo is missing it, a small red text box will overlay the image.

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

@@ -0,0 +1,44 @@
+# Framer
+
+**Category:** Components/Utilities/Framer
+
+**Import:** `import { Framer } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `embeds` | `string[]` | `[]` |  | — |
+| `breakpoints` | `number[]` | `[330, 510, 660, 930, 1200]` |  | — |
+| `minFrameWidth` | `number` | `320` |  | — |
+| `maxFrameWidth` | `number` | `1200` |  | — |
+| `searchType` | `'dropdown' \| 'typeahead'` | `'dropdown'` |  | — |
+
+## Examples
+
+### Demo
+
+```svelte
+<Framer
+  embeds={[
+      'https://graphics.reuters.com/USA-CONGRESS/FUNDRAISING/zjvqkawjlvx/embeds/en/embed/?zzz',
+      'https://www.reuters.com/graphics/UKRAINE-CRISIS/MAP/klvymdzdrvg/embeds/en/map/',
+    ]}
+/>
+```
+
+## Documentation
+
+# FeaturePhoto
+
+An embed tool for development in the graphics kit.
+
+```svelte
+<script>
+  import { Framer } from '@reuters-graphics/graphics-components';
+
+  const embeds = ['/embeds/my-chart/index.html'];
+</script>
+
+<Framer {embeds} />
+```