@reuters-graphics/graphics-components 3.10.0 → 4.0.0

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

@@ -0,0 +1,143 @@
+# BodyText
+
+**Category:** Components/Text elements/BodyText
+
+**Import:** `import { BodyText } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `text` | `string` | — | ✓ | A markdown text string. |
+| `class` | `string` | `''` |  | Add a class to target with SCSS. |
+| `id` | `string` | `''` |  | Add an id to the block tag to target it with custom CSS. |
+
+## Examples
+
+### Demo
+
+```svelte
+<BodyText text={/* value — see Props/Types for full type */} />
+```
+
+### Typography sample
+
+```svelte
+<BodyText
+  class="body-text-typography-example-story"
+  text={/* value — see Props/Types for full type */}
+/>
+```
+
+### Custom styles
+
+```svelte
+<BodyText
+  class="body-text-custom-styles-story"
+  text="Venison shoulder <span class="highlight">ham hock</span> ham leberkas."
+/>
+```
+
+## Documentation
+
+# BodyText
+
+The `BodyText` component creates the main text of your page. You can pass the `text` prop a [markdown-formatted](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) string, which will be parsed into paragraphs, headers, lists, links, blockquotes and other markdown-supported elements.
+
+```svelte
+<script>
+  import { BodyText } from '@reuters-graphics/graphics-components';
+
+  const markdownText = `Bacon ipsum **dolor amet** cow tongue tri-tip.
+  
+Biltong turducken ground round kevin [hamburger turkey](https://reuters.com) pig.
+
+- Steak
+- [Pork chop](https://www.google.com)
+- Fillet
+  
+Venison shoulder *ham hock ham leberkas*. Flank beef ribs fatback, jerky meatball ham hock.`;
+</script>
+
+<BodyText text={markdownText} />
+```
+
+## Using with ArchieML docs
+
+With the graphics kit, you'll likely get your text value from an ArchieML doc...
+
+```yaml
+# ArchieML doc
+[blocks]
+
+type: text
+text: Bacon ipsum ...
+
+... etc.
+:end
+
+[]
+```
+
+... which you'll parse out of a ArchieML block object before passing to the `BodyText` component.
+
+```svelte
+<!-- App.svelte -->
+<script>
+  import { BodyText } from '@reuters-graphics/graphics-components';
+  import content from '$locales/en/content.json';
+</script>
+
+{#each content.blocks as block}
+  {#if block.type === 'text'}
+    <BodyText text={block.text} />
+  {/if}
+{/each}
+```
+
+## Styling text
+
+Styles are built in for many text elements created by `BodyText`, including headings, ordered and unordered lists, links, blockquotes and even drop caps (using a `"drop-cap"` classed span).
+
+```svelte
+<BodyText
+  text="<span class='drop-cap'>R</span>eprehenderit hamburger pork bresaola ..."
+/>
+```
+
+### Custom styles
+
+To add your own styling, you can write styles in a global SCSS stylesheet:
+
+```svelte
+<BodyText
+  text="Venison shoulder <span class='highlight'>ham hock</span> ham leberkas."
+/>
+```
+
+```scss
+// global.scss
+span.highlight {
+  background: palegoldenrod;
+  padding: 2px 4px;
+}
+```
+
+If you want to make sure styles for one portion of text don't apply other parts of the page, add a `class` to BodyText to use as an additional selector.
+
+```svelte highlight=2
+<BodyText
+  class="my-special-text-block"
+  text="Venison shoulder <span class='highlight'>ham hock</span> ham leberkas."
+/>
+```
+
+```scss
+// global.scss
+.my-special-text-block {
+  span.highlight {
+    background: palegoldenrod;
+    padding: 2px 4px;
+  }
+}
+```

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/environment';
+</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} />
+```