@reuters-graphics/graphics-components 3.9.0 → 3.10.1

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

@@ -0,0 +1,237 @@
+# PhotoPack
+
+**Category:** Components/Multimedia/PhotoPack
+
+**Import:** `import { PhotoPack } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `images` | `Image[]` | — | ✓ | Array of image objects |
+| `layouts` | `Layout[]` | — |  | Array of layout objects |
+| `gap` | `number` | `15` |  | Gap between images. |
+| `id` | `string` | `'photopack-' + random4() + random4()` |  | Add an ID to target with SCSS. Should be unique from all other elements. |
+| `class` | `string` | `''` |  | Add a class to target with SCSS. |
+| `width` | `ContainerWidth` | `'normal'` |  | Width of the component within the text well: 'normal' \| 'wide' \| 'wider' \| 'widest' \| 'fluid' Options: `normal`, `wide`, `wider`, `widest`, `fluid` |
+| `textWidth` | `ContainerWidth` | `'normal'` |  | Set a different width for captions within the text well. For example, "normal" to keep captions inline with the rest of the text well.  Can't ever be wider than `width`: 'normal' \| 'wide' \| 'wider' \| 'widest' \| 'fluid' Options: `normal`, `wide`, `wider`, `widest`, `fluid` |
+
+## Types
+
+```typescript
+export interface Image {
+    src: string;
+    altText: string;
+    caption?: string;
+    maxHeight?: number;
+  }
+
+export interface Layout {
+    breakpoint: number;
+    rows: number[];
+  }
+```
+
+## Examples
+
+### Demo
+
+```svelte
+<PhotoPack
+  width="wide"
+  textWidth="normal"
+  images={/* array — see Props/Types for full type */}
+  layouts={[
+    { breakpoint: 450, rows: [1, 2, 1] },
+    { breakpoint: 750, rows: [1, 3] },
+  ]}
+/>
+```
+
+### ArchieML
+
+```svelte
+<PhotoPack archieMLBlock={/* object — see Props/Types for full type */} />
+```
+
+### Smart layouts
+
+```svelte
+{#snippet children(args)}
+  {@const { imageCount, ...photoPackProps } = args as SmartDefaultsArgs}
+  <PhotoPack
+    {...photoPackProps}
+    images={allImages.slice(0, imageCount || 4)}
+  />
+{/snippet}
+```
+
+## Documentation
+
+# PhotoPack
+
+The `PhotoPack` component makes simple photo grids with custom layouts at various breakpoints.
+
+`images` are defined with their src, alt text, captions and an optional `maxHeight`, which ensures that an image is no taller than that height in any layout.
+
+```javascript
+const images = [
+  {
+    src: 'https://...',
+    altText: 'Alt text',
+    caption: 'Lorem ipsum. REUTERS/Photog',
+    // Optional max-height of images across all layouts
+    maxHeight: 800,
+  },
+  // ...
+];
+```
+
+`layouts` optionally define how images are laid out at different breakpoints. You can customise the layouts and group images into `rows` above a certain `breakpoint` by specifying the number of images that should go in that row. For example:
+
+```javascript
+const layouts = [
+  {
+    breakpoint: 450,
+    rows: [1, 2, 1],
+  },
+];
+```
+
+... tells the component that when the `PhotoPack` container is 450 pixels or wider, it should group the 4 images in 3 rows: 1 in the first, 2 in the second and 1 in the last.
+
+If you don't specify any layouts, the component will use a default responsive layout based on the number of images in your pack.
+
+You can define as many layouts for as many images as you like.
+
+```svelte
+<script>
+  import { PhotoPack } from '@reuters-graphics/graphics-components';
+
+  /** Array of photo metadata */
+  const images = [
+    {
+      src: 'https://...',
+      altText: 'Alt text',
+      caption: 'Lorem ipsum. REUTERS/Photog',
+      // Optional max-height of images across all layouts
+      maxHeight: 800,
+    },
+    // ...
+  ];
+
+  /** Set the number of photos in each row at various breakpoints */
+  const layouts = [
+    {
+      breakpoint: 450, // Applies to containers wider than 450px
+      rows: [1, 2, 1], // Number of photos in each row
+    },
+    // Another layout for containers wider than 750px
+    { breakpoint: 750, rows: [1, 3] },
+  ];
+</script>
+
+<PhotoPack {images} {layouts} />
+```
+
+## 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-pack
+id: my-photo-pack # Optional
+class: mb-2 # Optional
+width: wide # Optional
+textWidth: normal # Optional
+gap: 10 # Optional; must be a number.
+
+# Array of image metadata
+  [.images]
+    src: images/my-img-1.jpg
+    altText: Alt text
+    caption: Lorem ipsum. REUTERS/Photog
+
+    src: images/my-img-2.jpg
+    altText: Alt text
+    caption: Lorem ipsum. REUTERS/Photog
+
+    ...
+  []
+
+[]
+```
+
+... which you'll parse out of a ArchieML block object before passing to the `PhotoPack` component.
+
+> **Important ❗**: The prop `gap` must be a number. ArchieML renders all values -- including numbers -- as strings, so convert the `prop` value to a number before passing it to `PhotoPack`.
+
+```svelte
+<!-- App.svelte -->
+<script>
+  import { PhotoPack } from '@reuters-graphics/graphics-components';
+  import { assets } from '$app/paths'; // 👈 If using in the graphics kit...
+
+  import content from '$locales/en/content.json';
+</script>
+
+{#each content.blocks as block}
+  {#if block.type === 'photo-pack'}
+    <!-- Pass `assets` into the image source in graphics kit -->
+    <PhotoPack
+      id={block.id}
+      class={block.class}
+      width={block.width}
+      textWidth={block.textWidth}
+      gap={Number(block.gap)}
+      images={block.images.map((img) => ({
+        ...img,
+        src: `${assets}/${img.src}`,
+      }))}
+      layouts={[
+        { breakpoint: 750, rows: [2, 3] },
+        { breakpoint: 450, rows: [1, 2, 2] },
+      ]}
+    />
+  {/if}
+{/each}
+```
+
+## Smart default layouts
+
+If you don't specify the `layouts` prop, `PhotoPack` will automatically generate responsive layouts based on the number of images and the container width.
+
+**How it works:**
+
+- **Desktop** (1024px+): Number of images per row depends on container width:
+  - `normal`: max 2 per row
+  - `wide` / `wider`: max 3 per row
+  - `widest` / `fluid`: max 4 per row
+- **Tablet** (768px+): Always max 2 per row
+- **Mobile** (below 768px): 1 per row
+
+The smart defaults use a **bottom-heavy distribution**, meaning earlier rows have fewer images (making them larger and more prominent), while later rows have more images.
+
+**Examples:**
+
+- 5 images, `wide` container, desktop: `[2, 3]` (2 in first row, 3 in second)
+- 7 images, `widest` container, desktop: `[3, 4]` (3 in first row, 4 in second)
+- 4 images, any container, desktop: `[2, 2]` (evenly distributed)
+
+```svelte
+<script>
+  import { PhotoPack } from '@reuters-graphics/graphics-components';
+
+  const images = [
+    { src: `${assets}/image1.jpg`, altText: 'Photo 1', caption: 'Caption 1' },
+    { src: `${assets}/image2.jpg`, altText: 'Photo 2', caption: 'Caption 2' },
+    { src: `${assets}/image3.jpg`, altText: 'Photo 3', caption: 'Caption 3' },
+    { src: `${assets}/image4.jpg`, altText: 'Photo 4', caption: 'Caption 4' },
+  ];
+</script>
+
+<!-- No layouts prop = smart defaults! -->
+<PhotoPack {images} width="wide" />
+```

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

@@ -0,0 +1,49 @@
+# PymChild
+
+**Category:** Components/Utilities/PymChild
+
+**Import:** `import { PymChild } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `polling` | `number` | `500` |  | Pym.js polling interval |
+
+## Examples
+
+### Demo
+
+```svelte
+<PymChild />
+```
+
+## Documentation
+
+# PymChild
+
+The `PymChild` component creates a [Pym.js](https://blog.apps.npr.org/pym.js/) child instance for embeddables.
+
+```svelte
+<script>
+  import { PymChild } from '@reuters-graphics/graphics-components';
+</script>
+
+<PymChild polling={500} />
+```
+
+You can access the Pym.js child via `pym` in other components to send custom height updates to parent frames:
+
+```svelte
+<script>
+  import { PymChild, pym } from '@reuters-graphics/graphics-components';
+
+  const updateHeight = () => {
+    if (pym.child) pym.child.sendHeight();
+  };
+</script>
+
+<PymChild />
+
+<button onclick={updateHeight}>Update height</button>
+```

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

@@ -0,0 +1,119 @@
+# ReferralBlock
+
+**Category:** Components/Page furniture/ReferralBlock
+
+**Import:** `import { ReferralBlock } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `section` | `string` | `'/world/'` |  | Section ID, which is often the URL path to the section page on reuters.com.  Note that not all section pages will be available in the recent stories by section API. Options: `/world/`, `/world/europe/`, `/lifestyle/`, `/lifestyle/sports/`, `/legal/`, `/business/`, `/business/energy/` |
+| `collection` | `string` | — |  | Collection alias, as defined in Arc Collections editor. |
+| `stories` | `ReferralItem[]` | `[]` |  | Provide your own referrals instead of fetching recent stories from Reuters.com. When set, the `section`/`collection` fetch is skipped and these stories are rendered as-is. |
+| `number` | `number` | `4` |  | Number of referrals to show. Options: `2`, `4`, `6`, `8` |
+| `linkTarget` | `LinkTarget` | `'_self'` |  | Link [target](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target), e.g., `_blank` or `_parent`. |
+| `heading` | `string` | `''` |  | Add a heading to the referral block. |
+| `width` | `ReferralBlockWidth` | `'wide'` |  | Width of the component within the text well: 'normal' \| 'wide' \| 'wider' \| 'widest' \| 'fluid' Options: `normal`, `wide`, `wider`, `widest`, `fluid` |
+| `id` | `string` | `''` |  | Add an ID to target with SCSS. |
+| `class` | `string` | `'fmy-8'` |  | Add a class to target with SCSS. |
+
+## Examples
+
+### Demo
+
+```svelte
+<ReferralBlock section="/lifestyle/sports/" class="fmy-0" heading="More World Cup coverage" />
+```
+
+### By collection
+
+```svelte
+<ReferralBlock collection="x-trump" number={6} class="fmy-8" heading="The latest Trump coverage" />
+```
+
+### Manual stories
+
+```svelte
+<ReferralBlock
+  class="fmy-0"
+  heading="Related coverage"
+  stories={/* array — see Props/Types for full type */}
+/>
+```
+
+## Documentation
+
+# ReferralBlock
+
+The `ReferralBlock` component creates a set of referral links from recent Reuters.com stories using the [recent stories by section API](https://www.reuters.com/pf/api/v3/content/fetch/recent-stories-by-sections-v1?query=%7B%22section_ids%22%3A%22%2Fworld%2F%22%2C%22size%22%3A20%2C%22website%22%3A%22reuters%22%7D).
+
+> Note: The `section` or `collection` prop determines which section or collection stories are from.
+>
+> You can get the section ID from the URL for the Reuters.com section pages. For example, the section ID for [World - Europe](https://www.reuters.com/world/europe/) stories at `www.reuters.com/world/europe/` would be `/world/europe/`. (The leading and trailing slashes are required!)
+>
+> You should get the collection alias from the dotcom team.
+
+```svelte
+<script>
+  import { ReferralBlock } from '@reuters-graphics/graphics-components';
+</script>
+
+<ReferralBlock
+  section="/lifestyle/sports/"
+  class="fmy-0"
+  heading="More World Cup coverage"
+/>
+```
+
+## Collections
+
+TK - Check if this is still relevant.
+
+```svelte
+<script>
+  import { ReferralBlock } from '@reuters-graphics/graphics-components';
+</script>
+
+<ReferralBlock collection="x-trump" number={6} class="fmy-8" />
+```
+
+## Manual stories
+
+Pass a `stories` array to populate the block with your own one-off referrals
+instead of fetching them over the wire. When `stories` is set, the
+`section`/`collection` fetch is skipped entirely and your stories render as-is —
+which also means they show up in any environment, not just production
+`www.reuters.com`.
+
+Each story matches the `ReferralItem` type. Only `url`, `kicker`, `title` and
+`imageUrl` are required; `imageAlt` and `time` are optional (omit `time` to hide
+the publish time).
+
+```svelte
+<script>
+  import { ReferralBlock } from '@reuters-graphics/graphics-components';
+
+  const stories = [
+    {
+      url: 'https://www.reuters.com/world/europe/',
+      kicker: 'Europe',
+      title: 'A hand-picked story you provide yourself',
+      imageUrl: 'https://www.reuters.com/your-thumbnail.jpg',
+      imageAlt: 'Describe the image',
+      time: new Date('2026-06-16T12:00:00Z'),
+    },
+    {
+      url: 'https://www.reuters.com/business/energy/',
+      kicker: 'Energy',
+      title: 'Another one-off referral with no publish time',
+      imageUrl: 'https://www.reuters.com/another-thumbnail.jpg',
+    },
+  ];
+</script>
+
+<ReferralBlock {stories} heading="Related coverage" class="fmy-0" />
+```
+
+```
+```

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

@@ -0,0 +1,37 @@
+# ReutersGraphicsLogo
+
+**Category:** Components/Logos/ReutersGraphicsLogo
+
+**Import:** `import { ReutersGraphicsLogo } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `logoColour` | `string` | `'#D64000'` |  | "Kinesis" colour |
+| `textColour` | `string` | `'#212223'` |  | Text colour |
+| `width` | `string` | `'100%'` |  | CSS width value |
+
+## Examples
+
+### Demo
+
+```svelte
+<ReutersGraphicsLogo />
+```
+
+## Documentation
+
+# ReutersGraphicsLogo
+
+The `ReutersGraphicsLogo` component contains the Reuters Graphics team logo.
+
+> Generally, used only for internal tools. For public pages, use the [ReutersLogo](./?path=/docs/components-logos-reuterslogo--docs) component.
+
+```svelte
+<script>
+  import { ReutersGraphicsLogo } from '@reuters-graphics/graphics-components';
+</script>
+
+<ReutersGraphicsLogo />
+```

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

@@ -0,0 +1,35 @@
+# ReutersLogo
+
+**Category:** Components/Logos/ReutersLogo
+
+**Import:** `import { ReutersLogo } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `logoColour` | `string` | `'#D64000'` |  | "Kinesis" colour |
+| `textColour` | `string` | `'#212223'` |  | Text colour |
+| `width` | `string` | `'100%'` |  | CSS width value |
+
+## Examples
+
+### Demo
+
+```svelte
+<ReutersLogo />
+```
+
+## Documentation
+
+# ReutersLogo
+
+The `ReutersLogo` component contains the official Reuters logo.
+
+```svelte
+<script>
+  import { ReutersLogo } from '@reuters-graphics/graphics-components';
+</script>
+
+<ReutersLogo />
+```

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

@@ -0,0 +1,113 @@
+# SEO
+
+**Category:** Components/Ads & analytics/SEO
+
+**Import:** `import { SEO } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `baseUrl` | `string` | — | ✓ | Base url for the page, which in [Vite-based projects](https://vitejs.dev/guide/build.html#public-base-path) is globally available as `import.meta.env.BASE_URL`. |
+| `pageUrl` | `URL` | — | ✓ | [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object for the page. |
+| `seoTitle` | `string` | — | ✓ | SEO title |
+| `seoDescription` | `string` | — | ✓ | SEO description |
+| `shareTitle` | `string` | — | ✓ | Share title |
+| `shareDescription` | `string` | — | ✓ | Share description |
+| `shareImgPath` | `string` | — | ✓ | Share image path. **Must be an absolute path.** |
+| `shareImgAlt` | `string` | `''` |  | Share image alt text, up to 420 characters. |
+| `publishTime` | `string` | `''` |  | Publish time as an [ISO string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) |
+| `updateTime` | `string` | `''` |  | Updated time as an [ISO string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) |
+| `authors` | `GraphicAuthor[]` | `[]` |  | Array of authors for the piece. Each author object must have `name` and `link` attributes. |
+
+## Examples
+
+### Demo
+
+```svelte
+<SEO
+  baseUrl="https://www.reuters.com"
+  seoTitle="A title for Google"
+  seoDescription="A description for Google"
+  shareTitle="A title for Twitter/Facebook"
+  shareDescription="A description for Twitter/Facebook"
+  shareImgPath="https://www.reuters.com/graphics/world-coronavirus-tracker-and-maps/assets/images/share.jpg"
+/>
+```
+
+## Documentation
+
+# SEO
+
+The `SEO` component adds essential metadata to pages.
+
+```svelte
+<script>
+  import { SEO } from '@reuters-graphics/graphics-components';
+</script>
+
+<SEO
+  baseUrl="https://www.reuters.com/graphics/world-coronavirus-tracker-and-maps"
+  pageUrl={new URL(
+    'https://www.reuters.com/graphics/world-coronavirus-tracker-and-maps/countries/united-kingdom/'
+  )}
+  seoTitle="A title for Google"
+  seoDescription="A description for Google"
+  shareTitle="A title for Twitter/Facebook"
+  shareDescription="A description for Twitter/Facebook"
+  shareImgPath="https://www.reuters.com/graphics/world-coronavirus-tracker-and-maps/assets/images/share.jpg"
+  shareImgAlt="An image showing global COVID infection rates"
+  publishTime="2020-09-15T00:00:00.000Z"
+  updateTime="2021-01-10T12:30:00.000Z"
+  authors={[
+    { name: 'Jane Doe', link: 'https://www.reuters.com/authors/jane-doe/' },
+    { name: 'John Doe', link: 'https://www.reuters.com/authors/john-doe/' },
+  ]}
+/>
+```
+
+## Using with ArchieML docs
+
+With the graphics kit, you'll likely get many of your text values from an ArchieML doc...
+
+```yaml
+# ArchieML doc
+slug: ROOT-SLUG/WILD
+seoTitle: Page title for search
+seoDescription: Page description for search
+shareTitle: Page title for social media
+shareDescription: Page description for social media
+shareImgPath: images/reuters-graphics.jpg
+shareImgAlt: Alt text for share image.
+```
+
+... which you'll pass to the `SEO` component.
+
+```svelte
+<script>
+  import { SEO } from '@reuters-graphics/graphics-components';
+  import pkg from '$pkg';
+  import content from '$locales/en/content.json';
+  import { assets } from '$app/paths';
+  import { page } from '$app/stores';
+</script>
+
+<SEO
+  baseUrl={VITE_BASE_URL}
+  pageUrl={$page.url}
+  seoTitle={content.seoTitle}
+  seoDescription={content.seoDescription}
+  shareTitle={content.shareTitle}
+  shareDescription={content.shareDescription}
+  shareImgPath={`${assets}/${content.shareImgPath}`}
+  shareImgAlt={content.shareImgAlt}
+  publishTime={pkg?.reuters?.graphic?.published}
+  updateTime={pkg?.reuters?.graphic?.updated}
+  authors={pkg?.reuters?.graphic?.authors}
+/>
+```
+
+> **Note:** For _reasons_, we can't document the value of `VITE_BASE_URL` below. It's `import` + `.meta.env.BASE_URL` (concatenate all that) in the graphics kit and other Vite-based rigs.
+
+```
+```