@reuters-graphics/graphics-components 3.10.0 → 4.0.0

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 { asset } from '$app/paths'; // 👈 If using in the graphics kit...
+</script>
+
+<FeaturePhoto
+  src={asset('/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 { asset } from '$app/paths';
+</script>
+
+{#each content.blocks as block}
+  {#if block.Type === 'text'}
+    <!-- ... -->
+  {:else if block.type === 'photo'}
+    <FeaturePhoto
+      width={block.width}
+      src={asset(`/${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} />
+```

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

@@ -0,0 +1,49 @@
+# Geocoder
+
+**Category:** Components/Controls/Geocoder
+
+**Import:** `import { Geocoder } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `accessToken` | `string` | — | ✓ | Mapbox public access token. |
+| `searchPlaceholder` | `string` | `'Search for a location'` |  | Placeholder text shown in the search input. |
+| `onselect` | `(location: { lng: number; lat: number; name: string }) => void` | — |  | Callback fired when a location is selected from the results. |
+| `minLength` | `number` | `2` |  | Minimum number of characters before a request is made. Raising this cuts the number of paid geocoding requests per search. Defaults to 2. |
+| `debounceMs` | `number` | `300` |  | Debounce window in milliseconds between the last keystroke and the request. Raising this fires fewer requests while the user is still typing (each request is billed). Defaults to 300. |
+
+## Examples
+
+### Demo
+
+```svelte
+<div style="min-height: 330px; padding-top: 1rem;">
+  <Geocoder {accessToken} onselect={handleSelect} />
+</div>
+```
+
+## Documentation
+
+# Geocoder
+
+The `Geocoder` component provides an autocomplete location search powered by the [Mapbox Geocoding v6 API](https://docs.mapbox.com/api/search/geocoding-v6/). It returns coordinates and a place name via the `onselect` callback.
+
+```svelte
+<script>
+  import { Geocoder } from '@reuters-graphics/graphics-components';
+
+  const MAPBOX_TOKEN = 'your_mapbox_token';
+
+  function handleSelect(location) {
+    console.log(location.name, location.lng, location.lat);
+  }
+</script>
+
+<Geocoder accessToken={MAPBOX_TOKEN} onselect={handleSelect} />
+```
+
+The `accessToken` prop is required. Look up the Reuters Mapbox token in the team's 1Password vault. All [Mapbox forward geocoding options](https://docs.mapbox.com/api/search/geocoding-v6/#forward-geocoding) are available as props, including `country`, `language`, `types`, `bbox`, `proximity`, `limit`, and `worldview`.
+
+To reduce the number of paid geocoding requests, use `minLength` (minimum characters before searching, default `2`) and `debounceMs` (delay after the last keystroke before requesting, default `300`). Raising them fires fewer requests while the user is still typing.

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

@@ -0,0 +1,319 @@
+# GraphicBlock
+
+**Category:** Components/Graphics/GraphicBlock
+
+**Import:** `import { GraphicBlock } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `children` | `Snippet` | — | ✓ | Content to place inside `GraphicBlock` |
+| `id` | `string` | `''` |  | Add an id to the block tag to target it with custom CSS. |
+| `class` | `string` | `''` |  | Add 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 |
+| `notes` | `string \| Snippet` | — |  | Notes to the graphic, passed in as a markdown string OR as a custom snippet. |
+| `width` | `ContainerWidth` | `'normal'` |  | Width of the component 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`. Options: `normal`, `wide`, `wider`, `widest`, `fluid` |
+| `title` | `string \| Snippet` | — |  | Title of the graphic as a string or a custom snippet. |
+| `description` | `string` | — |  | Description of the graphic, passed in as a markdown string. |
+| `ariaLabel` | `string` | `'chart'` |  | ARIA [label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) for the block |
+| `ariaDescription` | `string \| Snippet` | — |  | ARIA description, passed in as a markdown string OR as a custom snippet. |
+
+## Examples
+
+### Demo
+
+```svelte
+<GraphicBlock
+  title="Title for my chart"
+  description="Some description for your chart."
+  notes={`Note: Data current as of Aug. 2, 2022.\n\nSource: [Google research](https://google.com)`}
+>
+  <div id="my-chart">
+    <img src={PlaceholderImg} alt="placeholder" />
+  </div>
+</GraphicBlock>
+```
+
+### Ai2svelte and ArchieML
+
+```svelte
+<GraphicBlock
+  title="Earthquake in Haiti"
+  description="The 7.2-magnitude earthquake struck at 8:29 a.m. EST, Aug. 14, 2021."
+  notes="Note: A shakemap represents the ground shaking produced by an earthquake."
+>
+  <AiMap />
+</GraphicBlock>
+```
+
+### Custom text
+
+```svelte
+<GraphicBlock>
+  <div class="demo-graphic">
+    <img src={PlaceholderImg} alt="placeholder" />
+  </div>
+
+  {#snippet title()}
+    <h5>My smaller title</h5>
+  {/snippet}
+
+  {#snippet notes()}
+    <aside>
+      <p><strong>Note:</strong> Data current as of Aug. 2, 2022.</p>
+    </aside>
+  {/snippet}
+</GraphicBlock>
+```
+
+### AREA description
+
+```svelte
+<GraphicBlock
+  title="Earthquake in Haiti"
+  description="The 7.2-magnitude earthquake struck at 8:29 a.m. EST, Aug. 14, 2021."
+  notes="Note: A shakemap represents the ground shaking produced by an earthquake."
+  ariaDescription="A map showing the shake intensity produced by the earthquake."
+>
+  <AiMap />
+</GraphicBlock>
+```
+
+### Custom AREA description
+
+```svelte
+<GraphicBlock
+  title="Earthquake in Haiti"
+  description="The 7.2-magnitude earthquake struck at 8:29 a.m. EST, Aug. 14, 2021."
+  notes="Note: A shakemap represents the ground shaking produced by an earthquake."
+>
+  <AiMap />
+  {#snippet ariaDescription()}
+    <p>
+      A shakemap shows the intensity of the 7.2-magnitude earthquake that
+      struck Haiti at 8:29 a.m. EST, Aug. 14, 2021.
+    </p>
+    <table>
+      <tbody>
+        <tr>
+          <th>City</th>
+          <th>Felt shake strength</th>
+        </tr>
+        <tr>
+          <td>Les Cayes</td>
+          <td>Very strong</td>
+        </tr>
+        <tr>
+          <td>Jeremie</td>
+          <td>Strong</td>
+        </tr>
+      </tbody>
+    </table>
+  {/snippet}
+</GraphicBlock>
+```
+
+## Documentation
+
+# GraphicBlock
+
+The `GraphicBlock` component is a special derivative of the [Block](?path=/docs/components-page-layout-block--docs) component that wraps around your graphic. It also adds a title, description, notes and other text elements.
+
+Many other Reuters Graphics components use `GraphicBlock` to wrap graphics with styled text.
+
+```svelte
+<script>
+  import { GraphicBlock } from '@reuters-graphics/graphics-components';
+</script>
+
+<GraphicBlock
+  title="Title for my chart"
+  description="Some description for your chart."
+  notes={`Note: Data current as of Aug. 2, 2022.\n\nSource: [Google research](https://google.com)`}
+>
+  <!-- Your chart goes here -->
+  <div id="my-chart" />
+</GraphicBlock>
+```
+
+## Using with ai2svelte and ArchieML docs
+
+The `GraphicBlock` component is built to handle [ai2svelte](https://github.com/reuters-graphics/ai2svelte) graphics in graphics kit.
+
+You'll likely get your text value from an ArchieML doc...
+
+```yaml
+# ArchieML doc
+[blocks]
+type: ai-graphic
+width: normal
+chart: AiMap # IMPORTANT: This must match the name of the ai2svelte chart you import in App.svelte
+title: Earthquake in Haiti
+description: The 7.2-magnitude earthquake struck at 8:29 a.m. EST, Aug. 14, 2021.
+notes: \Note: A shakemap represents the ground shaking produced by an earthquake.
+
+\Source: USGIS
+:end
+altText: A map that shows the shake intensity of the earthquake, which was worst in central Haiti.
+:end
+[]
+```
+
+... which you'll parse out of a ArchieML block object before passing to the `GraphicBlock` component.
+
+To pass your ai2svelte graphic into `GraphicBlock` component, import your ai2svelte graphic at the top of `App.svelte` and add it to the `aiCharts` object.
+
+> **Important❗:** Make sure that the value for `chart` in the ArchieML doc matches the name of the ai2svelte file imported in `App.svelte`.
+
+```svelte
+<!-- App.svelte -->
+<script>
+  // IMPORTANT: The name of your ai2svelte chart must match `chart` in your ArchieML doc
+  import AiMap from './ai2svelte/my-map.svelte';
+  // Error handler for missing ai2svelte charts
+  import LogBlock from './components/dev/LogBlock.svelte';
+
+  // If using with the graphics kit
+  import { asset } from '$app/paths';
+
+  // A built-in helper function in Graphis Kit for validating container width
+  import { containerWidth } from '$utils/propValidators';
+
+  // Add your imported ai2svelte charts to this object
+  const aiCharts = {
+    AiMap,
+    // Other ai2svelte graphics...
+  };
+</script>
+
+<!-- Loop through ArchieML blocks -->
+{#each content.blocks as block}
+  {#if block.type === 'ai-graphic'}
+    {#if !aiCharts[block.chart]}
+      <!-- Error message for when the ai2svelte chart is missing -->
+      <LogBlock message={`Unable to find "${block.chart}" in aiCharts`} />
+    {:else}
+      <!-- Get the ai2svelte graphic specified by `chart` in ArchieML -->
+      {@const AiChart = aiCharts[block.chart]}
+      <GraphicBlock
+        id={block.chart}
+        width={containerWidth(block.width)}
+        title={block.title}
+        description={block.description}
+        notes={block.notes}
+        ariaDescription={block.altText}
+      >
+        <!-- In graphics kit, pass the `assetsPath` prop -->
+        <AiChart assetsPath={asset('/').replace(/\/$/, '')} />
+      </GraphicBlock>
+    {/if}
+  {/if}
+{/each}
+```
+
+## Custom text
+
+You can override the default styles for title and notes by making your own custom elements and passing them as `title` and `notes` [snippets](https://svelte.dev/docs/svelte/snippet) instead of as strings:
+
+```svelte
+<GraphicBlock>
+  <!-- Custom title snippet -->
+  {#snippet title()}
+    <h5>My smaller title</h5>
+  {/snippet}
+
+  <!-- Your graphic -->
+  <div id="my-chart"></div>
+
+  <!-- Custom notes snippet -->
+  {#snippet notes()}
+    <aside>
+      <p><strong>Note:</strong> Data current as of Aug. 2, 2022.</p>
+    </aside>
+  {/snippet}
+</GraphicBlock>
+```
+
+## ARIA descriptions
+
+If the text in your chart isn't easily read by screen readers — for example, a map with annotations that wouldn't make sense without the visual — add an `ariaDescription` that describes the chart.
+
+The `ariaDescription` string will be processed as markdown, so you can add multiple paragraphs, links, headers, etc. in markdown.
+
+> **Note:** When you set an `ariaDescription`, your graphic will be automatically wrapped in a div with [aria-hidden="true"](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden), which tells screen readers to read the hidden ARIA description and skip the text in the graphic.
+
+```svelte
+<GraphicBlock
+  title="Earthquake in Haiti"
+  description="The 7.2-magnitude earthquake struck at 8:29 a.m. EST, Aug. 14, 2021."
+  notes="Note: A shakemap represents the ground shaking produced by an earthquake."
+  ariaDescription="A map showing the shake intensity produced by the earthquake."
+>
+  <!-- In graphics kit, pass the `assetsPath` prop -->
+  <AiChart assetsPath={asset('/').replace(/\/$/, '')} />
+</GraphicBlock>
+```
+
+## Custom ARIA descriptions
+
+Sometimes, instead of a simple sentence, we want to provide a data table or something more complex as an ARIA description. To do this, pass the custom elements as an `ariaDescription` [snippet](https://svelte.dev/docs/svelte/snippet) instead of as a string, as in the [example above](?path=/docs/components-graphics-graphicblock--docs#aria-descriptions).
+
+[Read this](https://accessibility.psu.edu/images/charts/) for more information on using screen reader data tables for charts.
+
+> **Note:** The `customAria` snippet will override the `ariaDescription` and will also hide the text in your graphic from screen readers.
+
+```svelte
+<GraphicBlock
+  title="Earthquake in Haiti"
+  description="The 7.2-magnitude earthquake struck at 8:29 a.m. EST, Aug. 14, 2021."
+  notes="Note: A shakemap represents the ground shaking produced by an earthquake."
+>
+  <!-- In graphics kit, pass the `assetsPath` prop -->
+  <AiChart assetsPath={asset('/').replace(/\/$/, '')} />
+
+  <!-- Custom ARIA description snippet -->
+  {#snippet ariaDescription()}
+    <p>
+      A shakemap shows the intensity of the 7.2-magnitude earthquake that struck
+      Haiti at 8:29 a.m. EST, Aug. 14, 2021.
+    </p>
+    <table>
+      <tbody>
+        <tr>
+          <th>City</th>
+          <th>Felt shake strength</th>
+        </tr>
+        <tr>
+          <td>Les Cayes</td>
+          <td>Very strong</td>
+        </tr>
+        <tr>
+          <td>Jeremie</td>
+          <td>Strong</td>
+        </tr>
+      </tbody>
+    </table>
+  {/snippet}
+</GraphicBlock>
+
+<!-- Optionally, style the visually hidden table nicely for sighted readers who use screen readers -->
+<style lang="scss">
+  table {
+    width: 100%;
+    border-collapse: collapse;
+
+    th,
+    td {
+      border: 1px solid #ddd;
+      padding: 8px;
+    }
+
+    th {
+      background-color: #f2f2f2;
+    }
+  }
+</style>
+```