@reuters-graphics/graphics-components 3.10.0 → 4.0.0

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

@@ -0,0 +1,196 @@
+# InfoBox
+
+**Category:** Components/Text elements/InfoBox
+
+**Import:** `import { InfoBox } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `title` | `string \| null` | `null` |  | Title of the box |
+| `text` | `string` | — |  | Contents of the note as a markdown string |
+| `notes` | `string \| null` | `null` |  | Additional footnotes |
+| `width` | `ContainerWidth` | `'normal'` |  | Width of the component within the text well. Options: `normal`, `wide`, `wider`, `widest`, `fluid` |
+| `class` | `string` | `''` |  | Add extra classes to the block tag to target it with custom CSS. |
+| `id` | `string` | `''` |  | Add an id to the block tag to target it with custom CSS. |
+| `theme` | `Theme` | `'light'` |  | Page theme Options: `light`, `dark` |
+| `header` | `Snippet` | — |  | Optional custom header snippet |
+| `body` | `Snippet` | — |  | Optional custom body snippet |
+| `footer` | `Snippet` | — |  | Optional custom footer snippet |
+
+## Examples
+
+### Demo
+
+```svelte
+<BodyText
+  text="Bacon ipsum dolor amet turducken buffalo beef ribs bresaola pancetta ribeye pork belly doner hamburger biltong cupim porchetta chuck ham tenderloin. Turducken bresaola jerky chicken."
+/>
+<InfoBox
+  title="About this data"
+  text={'Reuters is collecting daily COVID-19 infections and deaths data for 240 countries and territories around the world, updated regularly throughout each day. \n\n Every country reports those figures a little differently and, inevitably, misses undiagnosed infections and deaths. With this project we are focusing on the trends within countries as they try to contain the virus’ spread, whether they are approaching or past peak infection rates, or if they are seeing a resurgence of infections or deaths.'}
+  notes={'[Read more about our methodology](https://www.reuters.com/world-coronavirus-tracker-and-maps/en/methodology/)'}
+/>
+<BodyText
+  text="Ham drumstick tail ribeye pancetta, leberkas hamburger chicken spare ribs buffalo jerky sausage ground round meatball. Leberkas kevin short loin, tri-tip shank spare ribs buffalo beef pork belly corned beef chislic tongue."
+/>
+```
+
+### Lists
+
+```svelte
+<InfoBox
+  title="What you need to know about the war"
+  text={/* value — see Props/Types for full type */}
+/>
+```
+
+### Customised
+
+```svelte
+<InfoBox>
+  {#snippet header()}
+    <h3>Global video game market</h3>
+  {/snippet}
+  {#snippet body()}
+    <table>
+      <thead>
+        <tr>
+          <th>Year</th>
+          <th>Market size ($bln)</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>2024</td>
+          <td>274.63</td>
+        </tr>
+        <tr>
+          <td>2023</td>
+          <td>281.77</td>
+        </tr>
+        <tr>
+          <td>2022</td>
+          <td>249.55</td>
+        </tr>
+      </tbody>
+    </table>
+  {/snippet}
+  {#snippet footer()}
+    <div class="text-xs font-note">Source: Precedence Research</div>
+  {/snippet}
+</InfoBox>
+```
+
+## Documentation
+
+# InfoBox
+
+The `InfoBox` component creates a stylised text box that provides additional information that needs to be visually separate from the main content flow, such as methodology, detailed notes about data and extra context.
+
+```svelte
+<script>
+  import { InfoBox } from '@reuters-graphics/graphics-components';
+</script>
+
+<InfoBox
+  title="About this data"
+  text={'Reuters is collecting daily COVID-19 infections and deaths data for 240 countries and territories around the world, updated regularly throughout each day. \n\n Every country reports those figures a little differently and, inevitably, misses undiagnosed infections and deaths. With this project we are focusing on the trends within countries as they try to contain the virus’ spread, whether they are approaching or past peak infection rates, or if they are seeing a resurgence of infections or deaths.'}
+  notes={'[Read more about our methodology](https://www.reuters.com/world-coronavirus-tracker-and-maps/en/methodology/)'}
+/>
+```
+
+## Using with ArchieML docs
+
+With the graphics kit, you'll likely get your text value from an ArchieML doc...
+
+```yaml
+# Archie ML doc
+[blocks]
+
+type: info-box
+title: What you need to know about the war
+text: Reuters is collecting daily COVID-19 infections and deaths data for 240 countries and territories around the world, updated regularly throughout each day.
+
+Every country reports those figures a little differently and, inevitably, misses undiagnosed infections and deaths. With this project we are focusing on the trends within countries as they try to contain the virus’ spread, whether they are approaching or past peak infection rates, or if they are seeing a resurgence of infections or deaths.
+:end
+notes: [Read more about our methodology](https://www.reuters.com/world-coronavirus-tracker-and-maps/en/methodology/)
+[]
+```
+
+... which you'll parse out of a ArchieML block object before passing to the `InfoBox` component.
+
+```svelte
+<!-- graphics kit -->
+<script>
+  import { InfoBox } from '@reuters-graphics/graphics-components';
+  import content from '$locales/en/content.json';
+</script>
+
+# Graphics kit
+{#each content.blocks as block}
+  {#if block.type === 'info-box'}
+    <InfoBox title={block.title} text={block.text} notes={block.notes} />
+    <!-- ... -->
+  {/if}
+{/each}
+```
+
+## Lists
+
+Use markdown to add lists to `InfoBox`.
+
+```svelte
+<script>
+  import { InfoBox } from '@reuters-graphics/graphics-components';
+</script>
+
+<InfoBox
+  title="What you need to know about the war"
+  text={"- **Food crisis**: [Russia's invasion of Ukraine](#) in late February dramatically worsened the outlook for already inflated global food prices.\n- **Under fire**: Civillian homes destroyed in the conflict and Russia accused of war crimes.\n- **Nordstream sabotage**: A series of clandestine bombings and subsequent underwater gas leaks occurred on the Nord Stream 1 and Nord Stream 2 natural gas pipelines."}
+  notes={'[Read more about our methodology](https://www.reuters.com/world-coronavirus-tracker-and-maps/en/methodology/)'}
+/>
+```
+
+## Customisation
+
+Use [snippets](https://svelte.dev/docs/svelte/snippet) to customise the `InfoBox`, such as adding tables, icons and thumbnail images.
+
+```svelte
+<InfoBox title="About this data">
+  <!-- Optional custom header -->
+  {#snippet header()}
+    <h3>Global video game market</h3>
+  {/snippet}
+  <!-- Optional custom body -->
+  {#snippet body()}
+    <table>
+      <thead>
+        <tr>
+          <th>Year</th>
+          <th>Market size ($bln)</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>2024</td>
+          <td>274.63</td>
+        </tr>
+        <tr>
+          <td>2023</td>
+          <td>281.77</td>
+        </tr>
+        <tr>
+          <td>2022</td>
+          <td>249.55</td>
+        </tr>
+      </tbody>
+    </table>
+  {/snippet}
+  <!-- Optional custom footer -->
+  {#snippet updated()}
+    <div class="text-xs font-note">Source: Precedence Research</div>
+  {/snippet}
+</InfoBox>
+```

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

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

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

@@ -0,0 +1,170 @@
+# LanguageButton
+
+**Category:** Components/Text elements/LanguageButton
+
+**Import:** `import { LanguageButton } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `locale` | `string \| undefined` | `'en'` |  | The current locale of the article |
+| `embedded` | `boolean` | `false` |  | Whether the article is embedded |
+| `buttonOptions` | `{       locale: string;       label: string;     }` | `{
+      locale: 'es',
+      label: 'Leer en español',
+    }` |  | Options for the language toggle button |
+| `setUrl` | `() => string` | — |  | Custom function for handling URL changes for locales and embed versions. |
+
+## Examples
+
+### Demo
+
+```svelte
+<div style="display: flex; flex-direction: column; gap: 2rem;">
+  {@render demoToggle(
+    spanishLocale,
+    'es',
+    'ES',
+    'Toggle between English and Spanish',
+    () => {
+      spanishLocale = spanishLocale === 'en' ? 'es' : 'en';
+    }
+  )}
+  <LanguageButton locale={spanishLocale}></LanguageButton>
+</div>
+```
+
+### CustomiseLanguage
+
+```svelte
+<div style="display: flex; flex-direction: column; gap: 2rem;">
+  {@render demoToggle(
+    frenchLocale,
+    'fr',
+    'FR',
+    'Toggle between English and French',
+    () => {
+      frenchLocale = frenchLocale === 'en' ? 'fr' : 'en';
+    }
+  )}
+  <LanguageButton
+    locale={frenchLocale}
+    buttonOptions={{
+      locale: 'fr',
+      label: 'Lire en français',
+    }}
+  ></LanguageButton>
+</div>
+```
+
+## Documentation
+
+# LanguageButton
+
+The `LanguageButton` component creates a button that switches between an article written in English and another language.
+
+> 💡**NOTE:** If a translated embed page does not exist, add `LanguageButton` conditionally so it only renders when `embedded` is `false`. This prevents a toggle button from appearing on the English embed page.
+
+```svelte
+<script>
+  import { LanguageButton } from '@reuters-graphics/graphics-components';
+
+  //  If using in the graphics kit, use `resolve` from `$app/paths` to ensure the toggle links to the correct URL
+  import { resolve } from '$app/paths';
+
+  // If using in the graphics kit, `embedded` prop will already be available in App.svelte.
+  // Additionally, pass `locale = 'en'` as a prop
+  let { embedded = false, locale = 'en' }: Props = $props();
+</script>
+
+<!-- Pass `embedded` to `LanguageButton` if the embed page is translated -->
+<LanguageButton {locale} {embedded} {resolve} />
+```
+
+## Customise language and button label
+
+By default, the toggle button will switch between English and Spanish, and the `buttonOptions` prop does not need to be passed. To customise the language and button label, pass the `locale` and the button `label` for the translation language as an object to the `buttonOptions` prop.
+
+```svelte
+<script>
+  import { LanguageButton } from '@reuters-graphics/graphics-components';
+
+  //  If using in the graphics kit, use `resolve` from `$app/paths` to ensure the toggle links to the correct URL
+  import { resolve } from '$app/paths';
+
+  // If using in the graphics kit, `embedded` prop will already be available in App.svelte.
+  // Additionally, pass `locale = 'en'` as a prop
+  let { embedded = false, locale = 'en' }: Props = $props();
+</script>
+
+<!-- Pass `buttonOptions` to customise the language and button label -->
+<LanguageButton
+  {locale}
+  {embedded}
+  {resolve}
+  buttonOptions={{
+    locale: 'fr',
+    label: 'Lire en français',
+  }}
+/>
+```
+
+## Styling
+
+Use global CSS to style the toggle button. The container div has the class `language-button` and the nested button has an id of `translate-button`.
+
+```scss
+:global(div.language-button) {
+  /* Custom styles for the container div */
+
+    button#translate-button {
+        /* Custom styles for the toggle button */
+    }
+}
+
+<Canvas of={LanguageButtonStories.CustomStyle} />
+
+```
+
+## Customising URLs
+
+By default, the `LanguageButton` component will switch from English to the translated version of the main article by appending `/{locale}/` to the base URL. For example, if the English version of the article is at `www.example.com/article/`, the translated version will be at `www.example.com/article/{locale}/`.
+
+If `embedded` is passed, it will switch between English and translated versions of the embed page by appending `/embeds/{locale}/page/` to the base URL. For example, if the English version of the embed page is at `www.example.com/article/embeds/en/page/`, the translated version will be at `www.example.com/article/embeds/{locale}/page/`.
+
+To customise this, pass a function to the `setUrl` prop that returns the URLs you want to link to.
+
+```svelte
+<script>
+  import { LanguageButton } from '@reuters-graphics/graphics-components';
+
+  //  If using in the graphics kit, use `resolve` from `$app/paths` to ensure the toggle links to the correct URL
+  import { resolve } from '$app/paths';
+
+  // If using in the graphics kit, `embedded` prop will already be available in App.svelte.
+  // Additionally, pass `locale = 'en'` as a prop
+  let { embedded = false, locale = 'en' }: Props = $props();
+
+  // Custom function to return the URLs for the toggle button
+  const setUrl = () => {
+    if (embedded) {
+      if (locale === 'es') {
+        // If we're in the non-English article, link to the English article
+        return resolve('/embeds/en/custom-embed-url/');
+      } else {
+        return resolve('/embeds/es/custom-embed-url/');
+      }
+    } else {
+      if (locale === 'es') {
+        // If we're in the non-English article, link to the English article
+        return resolve('/');
+      } else {
+        return resolve('/es/');
+      }
+    }
+  };
+</script>
+
+<LanguageButton {locale} {embedded} {setUrl} />
+```

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

@@ -0,0 +1,251 @@
+# Legend
+
+Quantitative and categorical legend for maps and data displays.
+
+Renders one of five legend types:
+- threshold: discrete bins with color swatches
+- continuous: a continuous gradient with ticks
+- diverging: threshold bins with a highlighted midpoint
+- categorical: square swatches with labels in a horizontal row
+- proportional-symbols: nested circles with leader lines and labels
+
+The component is presentational and can be placed anywhere in page layout. The
+optional noData prop renders a separate fallback swatch for missing, unknown,
+or unavailable values across all legend modes.
+
+**Category:** Components/Graphics/Legend
+
+**Import:** `import { Legend } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `title` | `string` | `''` |  | Optional legend heading displayed above the scale. |
+| `subtitle` | `string` | `''` |  | Optional subtitle displayed beneath the title. |
+| `mode` | `LegendMode` | `'threshold'` |  | Legend rendering mode. Options: `threshold`, `continuous`, `diverging`, `categorical`, `proportional-symbols` |
+| `items` | `LegendItem[] \| LegendSymbolItem[]` | `[]` |  | Legend entries. Threshold/diverging modes use numeric bounds and colors; categorical mode uses label and color pairs; proportional-symbols mode uses numeric values and optional labels. |
+| `stops` | `LegendStop[]` | `[]` |  | Ordered continuous color stops with numeric values. |
+| `ticks` | `LegendTick[]` | `[]` |  | Optional tick values and labels for continuous mode. |
+| `midpoint` | `LegendMidpoint \| null` | `null` |  | Diverging midpoint with a numeric value and optional label. |
+| `formatter` | `LegendFormatter \| null` | `null` |  | Optional formatter applied to numeric values. |
+| `noData` | `LegendNoData \| null` | `null` |  | Optional fallback swatch for missing values. |
+| `width` | `ContainerWidth` | `'normal'` |  | Width of the legend within the text well. Options: `narrower`, `narrow`, `normal`, `wide`, `wider`, `widest`, `fluid` |
+
+## Types
+
+```typescript
+export type LegendMode =
+    | 'threshold'
+    | 'continuous'
+    | 'diverging'
+    | 'categorical'
+    | 'proportional-symbols';
+
+export type LegendFormatter = (value: number) => string;
+
+export interface LegendItem {
+    /** CSS color for the bin or category swatch. */
+    color: string;
+    /** Lower bound of the bin (inclusive). Omit for an open-ended first bin. */
+    from?: number | null;
+    /** Upper bound of the bin (exclusive). Omit for an open-ended last bin. */
+    to?: number | null;
+    /** Optional explicit label. Generated from the bounds when omitted. */
+    label?: string;
+  }
+
+export interface LegendStop {
+    /** Numeric position of the stop along the domain. */
+    value: number;
+    /** CSS color at this stop. */
+    color: string;
+    /** Optional explicit label. */
+    label?: string;
+  }
+
+export interface LegendTick {
+    /** Numeric position of the tick along the domain. */
+    value: number;
+    /** Optional explicit label. Formatted from `value` when omitted. */
+    label?: string;
+  }
+
+export interface LegendMidpoint {
+    /** Numeric value of the midpoint within the legend domain. */
+    value: number;
+    /** Optional explicit label. Formatted from `value` when omitted. */
+    label?: string;
+  }
+
+export interface LegendSymbolItem {
+    /** Non-negative numeric value mapped to circle area. */
+    value: number;
+    /** Optional explicit label. Formatted from `value` when omitted. */
+    label?: string;
+  }
+
+export interface LegendNoData {
+    /** Label shown next to the fallback swatch. */
+    label: string;
+    /** Optional CSS color for the fallback swatch. */
+    color?: string;
+  }
+```
+
+## Examples
+
+### Threshold
+
+```svelte
+<Legend
+  title="Annual average PM2.5"
+  subtitle="Micrograms per cubic meter"
+  mode="threshold"
+  items={[
+    { to: 12, color: 'var(--tr-light-orange)' },
+    { from: 12, to: 35, color: 'var(--tr-orange)' },
+    { from: 35, to: 55, color: 'var(--tr-dark-orange)' },
+    { from: 55, color: 'var(--tr-dark-red)' },
+  ]}
+  noData={{ label: 'Data not available' }}
+/>
+```
+
+### Continuous Gradient
+
+```svelte
+<Legend
+  title="Graduation rate"
+  mode="continuous"
+  stops={[
+    { value: 0, color: 'var(--tr-superlight-blue)' },
+    { value: 50, color: 'var(--tr-light-blue)' },
+    { value: 100, color: 'var(--tr-dark-blue)' },
+  ]}
+  ticks={[
+    { value: 0, label: '0%' },
+    { value: 25, label: '25%' },
+    { value: 50, label: '50%' },
+    { value: 75, label: '75%' },
+    { value: 100, label: '100%' },
+  ]}
+/>
+```
+
+### Diverging Midpoint
+
+```svelte
+<Legend
+  title="Today's difference from the normal high of 1961-1990"
+  mode="diverging"
+  items={/* array — see Props/Types for full type */}
+  midpoint={{ value: 0, label: '±0°' }}
+  formatter={(value: number) => {
+    if (value === 0) {
+      return '0°';
+    }
+
+    return `${value > 0 ? '+' : '−'}${Math.abs(value)}°`;
+  }}
+/>
+```
+
+### Categorical
+
+```svelte
+<Legend
+  title="Hurricanes since 1980"
+  subtitle="By Saffir-Simpson category"
+  mode="categorical"
+  items={/* array — see Props/Types for full type */}
+/>
+```
+
+### Proportional Symbols
+
+```svelte
+<Legend
+  title="Population"
+  subtitle="in millions"
+  mode="proportional-symbols"
+  items={[
+    { value: 1400, label: '1,400' },
+    { value: 600, label: '600' },
+    { value: 150, label: '150' },
+    { value: 0, label: '0' },
+  ]}
+/>
+```
+
+### Map Layout
+
+```svelte
+<TileMap
+  id="legend-demo-map"
+  center={[0, 20]}
+  zoom={0}
+  height="460px"
+  onMapReady={addCycloneLayer}
+>
+  {#snippet legend()}
+    <Legend
+      title="Hurricanes since 1980"
+      subtitle="By Saffir-Simpson category"
+      mode="categorical"
+      items={cycloneCategories}
+    />
+  {/snippet}
+</TileMap>
+```
+
+## Documentation
+
+# Legend
+
+A legend or key for maps and data displays. Renders one of five
+modes.
+
+They are:
+
+- **`threshold`** — discrete bins with color swatches and break ticks
+- **`continuous`** — a continuous gradient with axis ticks
+- **`diverging`** — threshold bins with a highlighted midpoint
+- **`categorical`** — square swatches with labels in a horizontal row
+- **`proportional-symbols`** — nested circles with leader lines and labels
+
+The optional `noData` prop renders a separate fallback swatch for missing,
+unknown, or unavailable values across every mode.
+
+The legend sizes itself to the text well with the `width` prop, matching the
+other graphics components.
+
+## Threshold
+
+Discrete bins, each with its own color. Labels are generated from the numeric
+bounds unless you pass an explicit `label`.
+
+## Continuous gradient
+
+A smooth gradient built from ordered `stops`. Pass `ticks` to control the axis
+labels.
+
+## Diverging midpoint
+
+Threshold bins centered on a highlighted `midpoint`. Use `formatter` to control
+how numeric boundaries are displayed.
+
+## Categorical
+
+Square swatches with labels laid out in a wrapping row.
+
+## Proportional symbols
+
+Nested circles sized by area, with leader lines and labels.
+
+## With a map
+
+`Legend` is standalone and can be placed anywhere in the layout, including above
+or below a `TileMap`.
+
+## Props