@reuters-graphics/graphics-components 3.10.0 → 4.0.0

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 { asset } from '$app/paths'; // 👈 If using in the graphics kit...
+</script>
+
+<BeforeAfter
+  beforeSrc={asset('/images/before-after/myrne-before.jpg')}
+  beforeAlt="Satellite image of Russian base at Myrne taken on July 7, 2020."
+  afterSrc={asset('/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={asset(`/${block.beforeSrc}`)}
+      beforeAlt={block.beforeAlt}
+      afterSrc={asset(`/${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.

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

@@ -0,0 +1,211 @@
+# Block
+
+**Category:** Components/Page layout/Block
+
+**Import:** `import { Block } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `children` | `Snippet` | — | ✓ | Content that goes inside `<Block>` |
+| `width` | `ContainerWidth` | `'normal'` |  | Width of the block within the article well. Options: `narrower`, `narrow`, `normal`, `wide`, `wider`, `widest`, `fluid` |
+| `id` | `string` | `''` |  | Add an id to the block tag to target it with custom CSS. |
+| `class` | `string` | `''` |  | Add custom classes to the block tag to target it with custom CSS. |
+| `snap` | `boolean` | `false` |  | Snap block to column widths, rather than fluidly resizing them. |
+| `role` | `string` | — |  | ARIA [role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) for the block |
+| `ariaLabel` | `string` | — |  | ARIA [label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) for the block |
+
+## Examples
+
+### Demo
+
+```svelte
+<Article id="block-demo-article">
+  <div class="article-boundaries">
+    <div class="label">Article</div>
+    <Block>
+      <div class="label">Block</div>
+    </Block>
+  </div>
+</Article>
+```
+
+### Custom layout
+
+```svelte
+<Block width="fluid">
+  <!-- Enter bootstrap grid! -->
+  <div id="block-flex-example">
+    <div class="row">
+      <div class="col">Column</div>
+      <div class="col-6">Column</div>
+      <div class="col">Column</div>
+    </div>
+    <div class="row">
+      <div class="col">Column</div>
+      <div class="col">Column</div>
+    </div>
+  </div>
+</Block>
+```
+
+### Snap widths
+
+```svelte
+<Article id="block-demo-article">
+  <div class="article-boundaries">
+    <div class="label">Article</div>
+    <h4>snap widths</h4>
+    <Block snap={true}>
+      <div class="label">Block</div>
+    </Block>
+  </div>
+</Article>
+```
+
+### Snap and skip widths
+
+```svelte
+<Article id="block-demo-article">
+  <div class="article-boundaries">
+    <div class="label">Article</div>
+    <h4>Regular layout</h4>
+
+    <Block width="narrower" snap={true} class="block-snap-widths-demo">
+      narrower
+    </Block>
+    <Block width="narrow" snap={true} class="block-snap-widths-demo">
+      narrow
+    </Block>
+    <Block width="normal" snap={true} class="block-snap-widths-demo">
+      normal
+    </Block>
+    <Block width="wide" snap={true} class="block-snap-widths-demo">
+      wide
+    </Block>
+    <Block width="wider" snap={true} class="block-snap-widths-demo">
+      wider
+    </Block>
+
+    <h4>with snap and skip</h4>
+    <Block width="narrower" snap={true} class="block-snap-widths-demo even">
+      narrower
+    </Block>
+    <Block width="narrow" snap={true} class="block-snap-widths-demo even">
+      narrow
+    </Block>
+    <Block
+      width="normal"
+      snap={true}
+      class="block-snap-widths-demo even skip-narrow"
+    >
+      normal.skip-narrow
+    </Block>
+    <Block
+      width="wide"
+      snap={true}
+      class="block-snap-widths-demo even skip-normal skip-narrow"
+    >
+      wide.skip-normal.skip-narrow
+    </Block>
+    <Block
+      width="wider"
+      snap={true}
+      class="block-snap-widths-demo even skip-wide"
+    >
+      wider.skip-wide
+    </Block>
+  </div>
+</Article>
+```
+
+## Documentation
+
+# Block
+
+The `Block` component is the basic building block of pages, a responsive container that wraps around each section of your piece.
+
+Blocks are stacked vertically within the well created by the [Article](./?path=/docs/components-page-layout-article--docs) component. They can have different widths on larger screens depending on the `width` prop.
+
+> 📌 Many of our other components already use the `Block` component internally. You'll usually only need to use it yourself if you're making something custom.
+
+```svelte
+<script>
+  import { Block } from '@reuters-graphics/graphics-components';
+</script>
+
+<Block>
+  <!-- Contents for this block goes here -->
+</Block>
+```
+
+## Custom layouts
+
+Our article well is designed to provide a basic responsive layout for you, but it also lets you customise.
+
+The radical but easiest way to do this is to create a `Block` with a `fluid` width -- which basically cancels out the article well dimensions -- and then code whatever you need from scratch or with another framework.
+
+The demo below does exactly that to create an edge-to-edge grid with [flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/).
+
+```svelte
+<Block width="fluid">
+  <div class="my-radical-container">
+    <!-- Now, you have full control over layout! -->
+  </div>
+</Block>
+```
+
+## Snap widths
+
+Normally, `Block` containers resize fluidly below the original `width`. Sometimes, though, you may want the container to snap to the next breakpoint -- for example, if you have a static graphic that looks fine at the set block breakpoints, but isn't so great at widths inbetween.
+
+You can use the `snap` prop to force the container to snap to each block width successively as the window sizes down.
+
+```svelte
+<Block width="wider" snap={true}>
+  <!-- Contents for this block -->
+</Block>
+```
+
+If you want to skip certain block widths entirely, you can add one or more class of `skip-{block width class}` to the `Block`.
+
+> **NOTE:** The snap width breakpoints only work on `Block` components with widths `wider` and below. `widest` and `fluid` are both **always** fluid, since they go edge-to-edge.
+
+```svelte
+<!-- Will skip wide and go straight to normal column width on resize. -->
+<Block width="wider" snap={true} class="skip-wide">
+  <!-- Contents for this block -->
+</Block>
+```
+
+This is probably easier to see in action than explain in words, so [resize the demo](./?path=/docs/components-page-layout-block--snap-skip-widths) to get a better picture of how it all works.
+
+## Using with custom column widths
+
+Snap width breakpoints are hard-coded to the default article well column widths, so if you set custom `columnWidths` on the [Article](./?path=/docs/components-page-layout-article--docs) component (**rare!**), you need to do a littie work to use this functionality.
+
+Luckily, it's still pretty easy. Just add a `cls` or `id` to your `Block` so you can target it with some custom SCSS. Then define a few SCSS variables corresponding to your custom column widths, and use the `block-snap-widths` SCSS mixin to get the same functionality at your custom breakpoints.
+
+```svelte
+<Block width="wider" snap={true} class="custom-blocks">
+  <!-- Contents for this block -->
+</Block>
+
+<style lang="scss">
+  // Define custom column widths
+  $column-width-narrower: 310px;
+  $column-width-narrow: 450px;
+  $column-width-normal: 600px;
+  $column-width-wide: 860px;
+  $column-width-wider: 1400px;
+
+  @use '@reuters-graphics/graphics-components/scss/mixins' as mixins;
+
+  :global {
+    div.custom-blocks {
+      @include mixins.block-snap-widths; // Use the `block-snap-widths` mixin
+    }
+  }
+</style>
+```

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

@@ -0,0 +1,66 @@
+# BlogPost
+
+**Category:** Components/Blog/BlogPost
+
+**Import:** `import { BlogPost } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `title` | `string` | `'Reuters Graphics blog post'` |  | Title of the blog post |
+| `slugTitle` | `string` | `'Reuters Graphics blog post'` |  | A sluggable title of the blog post.  **Important:** Do not change this title after publishing the post. Changes will break published links to the post. |
+| `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. |
+| `id` | `string` | `''` |  | Add an id to target post headline with custom CSS. |
+| `cls` | `string` | `''` |  | Add extra classes to target post headline with custom CSS. |
+| `isLastPost` | `boolean` | `false` |  | If the post is the last on the page, remove the dividing rule used to separate posts. |
+| `children` | `import('svelte').Snippet` | — |  | — |
+
+## Examples
+
+### Demo
+
+```svelte
+<BlogPost
+  title="Iran fires ballistic missiles at Israel in major escalation"
+  slugTitle="Iran fires ballistic missiles at Israel in major escalation"
+  authors={['John Smith', 'Jane Doe']}
+  publishTime="2024-10-01T18:30:00Z"
+  updateTime="2024-10-01T21:45:00Z"
+>
+  <BodyText
+    text="Iran launched a barrage of ballistic missiles at Israel on Tuesday in its first direct attack on Israeli territory, marking a significant escalation in the conflict gripping the Middle East."
+  />
+  <BodyText
+    text="The attack, which Iran said was in retaliation for Israeli strikes that killed senior Hezbollah and Hamas leaders, prompted Israel and the United States to vow a response."
+  />
+</BlogPost>
+```
+
+## Documentation
+
+# BlogPost
+
+The `BlogPost` component renders a single entry in a graphics blog page, including a headline, dateline, authors and a divider. Body content is passed as children.
+
+```svelte
+<script>
+  import { BlogPost } from '@reuters-graphics/graphics-components';
+  import { resolve } from '$app/paths';
+</script>
+
+<BlogPost
+  title="Iran fires ballistic missiles at Israel in major escalation"
+  slugTitle="Iran fires ballistic missiles at Israel in major escalation"
+  authors={['John Smith', 'Jane Doe']}
+  publishTime="2024-10-01T18:30:00Z"
+  updateTime="2024-10-01T21:45:00Z"
+  {resolve}
+>
+  <!-- Post body content goes here -->
+</BlogPost>
+```
+
+> **Important:** Do not change `slugTitle` after publishing. It is used to generate the post's anchor link — changing it will break any published links to the post.

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

@@ -0,0 +1,89 @@
+# BlogTOC
+
+**Category:** Components/Blog/BlogTOC
+
+**Import:** `import { BlogTOC } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `posts` | `Post[]` | — | ✓ | — |
+| `label` | `string` | `'Show all articles'` |  | The label for the table of contents toggle button. |
+| `maxHeight` | `number` | `300` |  | The maximum height of the table of contents list in pixels. |
+
+## Examples
+
+### Demo
+
+```svelte
+<Headline
+  section="Graphics"
+  hed="Maps of the Iran crisis"
+  hedSize="big"
+  width="normal"
+  class="mb-2"
+/>
+
+<ClockWall
+  cities={[
+    { name: 'Tehran', tzIdentifier: 'Asia/Tehran' },
+    { name: 'Tel Aviv', tzIdentifier: 'Asia/Tel_Aviv' },
+    { name: 'Washington D.C.', tzIdentifier: 'America/New_York' },
+  ]}
+/>
+
+<BlogTOC {posts} />
+
+<BlogPost
+  title="Iran fires ballistic missiles at Israel in major escalation"
+  slugTitle="Iran fires ballistic missiles at Israel in major escalation"
+  authors={['John Smith', 'Jane Doe']}
+  publishTime="2024-10-01T18:30:00Z"
+  updateTime="2024-10-01T21:45:00Z"
+>
+  <BodyText
+    text="Iran launched a barrage of ballistic missiles at Israel on Tuesday in its first direct attack on Israeli territory, marking a significant escalation in the conflict gripping the Middle East."
+  />
+  <BodyText
+    text="The attack, which Iran said was in retaliation for Israeli strikes that killed senior Hezbollah and Hamas leaders, prompted Israel and the United States to vow a response."
+  />
+</BlogPost>
+```
+
+## Documentation
+
+# BlogTOC
+
+The `BlogTOC` component renders a collapsible table of contents for a graphics blog page, listing all posts sorted chronologically. It only renders when there are two or more posts.
+
+```svelte
+<script>
+  import { BlogTOC } from '@reuters-graphics/graphics-components';
+  import { resolve } from '$app/paths';
+</script>
+
+<BlogTOC
+  posts={[
+    {
+      title: 'Iran fires ballistic missiles at Israel',
+      slugTitle: 'Iran fires ballistic missiles at Israel',
+      publishTime: '2024-10-01T18:30:00Z',
+    },
+    {
+      title: 'Israel vows response',
+      slugTitle: 'Israel vows response',
+      publishTime: '2024-10-02T09:15:00Z',
+    },
+  ]}
+  {resolve}
+/>
+```
+
+Pass SvelteKit's `resolve` function (from `$app/paths`) so that post links resolve correctly against your project's base path.
+
+Each post in the `posts` array must have:
+
+- `title` — the display title
+- `slugTitle` — used to generate the anchor link; **do not change after publishing**
+- `publishTime` — an ISO datetime string used for sorting and the dateline