@reuters-graphics/graphics-components 3.10.0 → 4.0.0

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

@@ -0,0 +1,254 @@
+# Video
+
+**Category:** Components/Multimedia/Video
+
+**Import:** `import { Video } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `src` | `string` | — | ✓ | Video source |
+| `poster` | `string` | `''` |  | Image to be shown while the video is downloading |
+| `ariaDescription` | `string` | — | ✓ | ARIA description, passed in as a markdown string. |
+| `class` | `string` | `''` |  | Add extra classes to the block tag to target it with custom CSS. |
+| `title` | `string` | — |  | Title of the graphic |
+| `notes` | `string \| Snippet` | — |  | Notes to the graphic, passed in as a markdown string OR a custom snippet. |
+| `description` | `string` | — |  | Description of the graphic, passed in as a markdown string. |
+| `width` | `ContainerWidth` | `'normal'` |  | Width of the block within the article well. |
+| `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`. |
+| `preloadVideo` | `'auto' \| 'none' \| 'metadata'` | `'auto'` |  | Preload options. `auto` is ignored if `autoplay` is true. Can also be `none` or `metadata`. |
+| `loopVideo` | `boolean` | `false` |  | Whether the video should loop. |
+| `muteVideo` | `boolean` | `true` |  | Whether video should have sound or not. |
+| `soundAutoplay` | `boolean` | `false` |  | If `true`, this allow videos with sound to autoplay if the user has previously interacted with DOM |
+| `playVideoWhenInView` | `boolean` | `true` |  | Whether the video should play when it comes into view or just on page load |
+| `playVideoThreshold` | `number` | `0.5` |  | Controls how much of the video should be visible when it starts playing. This is a number between 0 and 1, where 0 means the video will start playing as soon as its top enters the viewport, and 1 means it will start when the whole video is in the viewport. |
+| `possibleToPlayPause` | `boolean` | `true` |  | Whether to have the option to pause and play video |
+| `showControls` | `boolean` | `true` |  | Whether to show the play / pause buttons |
+| `separateReplayIcon` | `boolean` | `false` |  | Whether to use a separate replay icon or use the play icon for replay as well |
+| `controlsColour` | `string` | `'#333'` |  | Change the colour of the play/pause button |
+| `controlsOpacityMin` | `number` | `0` |  | Change the minimum opacity of the play/pause button, which you see on mouseover. Must be between 0 and 1. |
+| `controlsOpacityMax` | `number` | `0.7` |  | Change the maximum opacity of the play/pause button, which you see on mouseout. Must be between 0 and 1. |
+| `controlsPosition` | `ControlsPosition` | `'top left'` |  | Have four options for controls position - top right, top left, bottom right, bottom left |
+| `controlsBorderOffset` | `number` | `10` |  | Offset for the controls from the border |
+
+## Examples
+
+### Demo
+
+```svelte
+<Video
+  ariaDescription="Required description of your video for screen readers."
+  src={/* SilentVideo */}
+  width="wide"
+  notes="Optional caption for your video."
+/>
+```
+
+### Autoplay controls
+
+```svelte
+<Video
+  ariaDescription="Required description of your video for screen readers."
+  src={/* SilentVideo */}
+  loopVideo={true}
+  notes="World's longest glass bridge opens to public in Vietnam. (c) 2022 Thomson Reuters"
+  playVideoThreshold={0.9}
+/>
+```
+
+### Audio controls
+
+```svelte
+<Video
+  ariaDescription="Required description of your video for screen readers."
+  src={/* SoundVideo */}
+  notes="World's longest glass bridge opens to public in Vietnam. (c) 2022 Thomson Reuters"
+  controlsColour="#152a1c"
+  controlsOpacityMax={1}
+  controlsOpacityMin={0.5}
+  playVideoThreshold={0.9}
+  muteVideo={false}
+  soundAutoplay={true}
+/>
+```
+
+### Controls
+
+```svelte
+<Video
+  ariaDescription="Required description of your video for screen readers."
+  src={/* SilentVideo */}
+  width="normal"
+  notes="World's longest glass bridge opens to public in Vietnam. (c) 2022 Thomson Reuters"
+  playVideoThreshold={0.9}
+  controlsColour="white"
+  controlsOpacityMax={1}
+  controlsOpacityMin={0.5}
+  controlsPosition="bottom right"
+  separateReplayIcon={true}
+  loopVideo={false}
+  soundAutoplay={true}
+/>
+```
+
+### Text elements
+
+```svelte
+<Video
+  src={SilentVideo}
+  ariaDescription="Required description of your video for screen readers."
+  title="Title for your video"
+  description="Description for your video"
+>
+  {#snippet notes()}
+    <aside>
+      <p class="notes">Custom-styled notes for the video.</p>
+    </aside>
+  {/snippet}
+</Video>
+```
+
+## Documentation
+
+# Video
+
+The `Video` component adds a video with various controls to your page such as:
+
+- Play/pause button
+- Autoplay controls, i.e. whether the video plays when it comes into view or on page load
+- Looping
+- Audio controls
+- Text elements such as notes and titles
+
+```svelte
+<script>
+  import { Video } from '@reuters-graphics/graphics-components';
+</script>
+
+<Video
+  ariaDescription="Required description of your video for screen readers."
+  src="my-video.mp4"
+  width="wide"
+  notes="Optional caption for your video."
+/>
+```
+
+## Using with ArchieML docs
+
+With the graphics kit, you'll likely get your text value from an ArchieML doc...
+
+```yaml
+# ArchieML doc
+[blocks]
+type: video
+src: videos/my-video.mp4
+width: wide
+ariaDescription: Required description of your video for screen readers.
+notes: Optional caption for your video.
+loopVideo: true
+[]
+```
+
+... which you'll parse out of a ArchieML block object before passing to the `Video` component.
+
+```svelte
+<!-- App.svelte -->
+<script>
+  import { Video } from '@reuters-graphics/graphics-components';
+  import { asset } from '$app/paths'; // 👈 If using in the graphics kit...
+  import { truthy } from '$utils/propValidators'; // 👈 If using in the graphics kit...
+</script>
+
+{#each content.blocks as block}
+  {#if block.type === 'video'}
+    <Video
+      ariaDescription={block.ariaDescription}
+      src={asset(`/${block.src}`)}
+      width={block.width}
+      loopVideo={truthy(block.loopVideo)}
+      notes={block.notes}
+    />
+  {/if}
+{/each}
+```
+
+> **Note:** Some props, like `loopVideo`, expect boolean values. If you're using the graphics kit, you can use the `truthy()` util function to convert a string value to a boolean.
+
+## Autoplay controls
+
+By default, the video starts playing when 50% (0.5) of the video element's height comes into view. Adjust this with `playVideoThreshold`, which is a value between 0 and 1, where 0 means the video will start playing as soon as its top enters the viewport, and 1 means it will start when the whole video is in the viewport.
+
+To make the video play on page load regardless of whether it is in view, set the prop `playVideoWhenInView` to `false`.
+
+```svelte
+<script>
+  import { Video } from '@reuters-graphics/graphics-components';
+</script>
+
+<Video
+  ariaDescription="Required description of your video for screen readers."
+  src="https://..."
+  loopVideo={true}
+  playVideoThreshold={0.9}
+  notes="World's longest glass bridge opens to public in Vietnam. (c) 2022 Thomson Reuters"
+/>
+```
+
+## Audio controls
+
+On most browsers, [autoplaying videos with sound](https://developer.chrome.com/blog/autoplay#:~:text=Muted%20autoplay%20is%20always%20allowed,to%20allow%20autoplay%20with%20sound.) is allowed only if the user has interacted with the page. (Autoplay is allowed with muted videos.)
+
+By default, this component will not autoplay videos with sound. To change this, set `soundAutoplay` to `true`. This will allow the video to autoplay with sound when it comes into view, but only if the user has already interacted with the page by clicking or tapping on it.
+
+Test this with the example below: the video will autoplay when it comes into view _only if_ you have clicked or tapped on the page before scrolling down to it.
+
+```svelte
+<script>
+  import { Video } from '@reuters-graphics/graphics-components';
+</script>
+
+<Video
+  ariaDescription="Required description of your video for screen readers."
+  src="https://..."
+  controlsColour="#152a1c"
+  controlsOpacityMax={1}
+  controlsOpacityMin={0.5}
+  muteVideo={false}
+  soundAutoplay={true}
+/>
+```
+
+## Adding text
+
+The `Video` component allows you to add a title, description and notes to your video, which are rendered by the `GraphicBlock` component.
+
+Customise the `notes` section by passing a [snippet](https://svelte.dev/docs/svelte/snippet) instead of a string.
+
+```svelte
+<script>
+  import { Video } from '@reuters-graphics/graphics-components';
+</script>
+
+<Video
+  src="https://..."
+  ariaDescription="Required description of your video for screen readers."
+  title="Title for your video"
+  description="Description for your video"
+>
+  <!-- Custom notes snippet -->
+  {#snippet notes()}
+    <aside>
+      <p class="notes">Custom-styled notes for the video.</p>
+    </aside>
+  {/snippet}
+</Video>
+
+<style lang="scss">
+  @use '@reuters-graphics/graphics-components/dist/scss/mixins' as mixins;
+
+  p.notes {
+    @include mixins.body-note;
+  }
+</style>
+```

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

@@ -0,0 +1,54 @@
+# Visible
+
+**Category:** Components/Utilities/Visible
+
+**Import:** `import { Visible } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `once` | `boolean` | `false` |  | Whether to change visibility just once.  Useful for loading expensive images or other media and then keeping them around once they're first loaded. |
+| `top` | `string` | `'0px'` |  | Set Intersection Observer [rootMargin](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#rootmargin) `top` with units. Units must be  `px` or other [absolute lengths units](https://arc.net/l/quote/jkukcxqq), or `%`. |
+| `bottom` | `string` | `'0px'` |  | Set Intersection Observer [rootMargin](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#rootmargin) `bottom` with units. Units must be  `px` or other [absolute lengths units](https://arc.net/l/quote/jkukcxqq), or `%`. |
+| `left` | `string` | `'0px'` |  | Set Intersection Observer [rootMargin](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#rootmargin) `left` with units. Units must be  `px` or other [absolute lengths units](https://arc.net/l/quote/jkukcxqq), or `%`. |
+| `right` | `string` | `'0px'` |  | Set Intersection Observer [rootMargin](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#rootmargin) `right` with units. Units must be  `px` or other [absolute lengths units](https://arc.net/l/quote/jkukcxqq), or `%`. |
+| `threshold` | `number` | `0` |  | Set the Intersection Observer [threshold](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#threshold). |
+| `children` | `Snippet<[boolean]>` | — |  | — |
+
+## Examples
+
+### Demo
+
+```svelte
+<VisibleDemo />
+```
+
+## Documentation
+
+# Visible
+
+The `Visible` component wraps around other components or HTML elements and uses the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) to determine if they are visible on the page.
+
+This is useful for lazy loading elements, especially expensive media files or components that fetch lots of data. You can also use it trigger animations or play media once a reader scrolls a component into view.
+
+By default, `visible` will switch between `false` and `true` whenever the element is in our out of view. To trigger this just once, set the prop `once` to `true`. This is useful for loading expensive media when they first come into view and then keeping them around once they're loaded.
+
+> **Note:** Don't use this for content that's "above the fold" at the top of the page. That'll just slow down the first load of important visible content.
+
+```svelte
+<script>
+  import { Visible } from '@reuters-graphics/graphics-components';
+</script>
+
+<!-- Optionally set your own `top`, `bottom`, `right` and `left` values with `px` or `%` units -->
+<Visible top="10px">
+  {#snippet children(visible)}
+    {#if visible}
+      <p>Visible!</p>
+    {:else}
+      <p>Not yet visible.</p>
+    {/if}
+  {/snippet}
+</Visible>
+```

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

@@ -0,0 +1,40 @@
+# cssVariables
+
+**Import:** `import { cssVariables } from '@reuters-graphics/graphics-components'`
+
+## Documentation
+
+# `cssVariables`
+
+An action you can use to easily set [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) on HTML elements. Useful for passing JavaScript values to your component SCSS like this:
+
+```svelte
+<script>
+  import { cssVariables } from '@reuters-graphics/graphics-components';
+
+  let { height = 300, textColour = 'red' } = $props();
+
+  // Create an object of variable names and CSS values...
+  let variables = $derived({
+    height: height + 'px',
+    textColour: textColour,
+  });
+</script>
+
+<!-- Attach it to a parent element with the action -->
+<div use:cssVariables={variables}>
+  <p>My text...</p>
+</div>
+
+<style lang="scss">
+  /**
+   * Now use your variables in your SCSS!
+   */
+  div {
+    height: var(--height);
+    p {
+      color: var(--textColour);
+    }
+  }
+</style>
+```

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

@@ -0,0 +1,59 @@
+# Components
+
+Per-component reference with props tables, type definitions, and usage examples.
+
+| Component | Category | Description |
+|-----------|----------|-------------|
+| [AdSlot](./AdSlot.md) |  | — |
+| [Analytics](./Analytics.md) | Components/Ads & analytics/Analytics | — |
+| [Article](./Article.md) | Components/Page layout/Article | — |
+| [BeforeAfter](./BeforeAfter.md) | Components/Multimedia/BeforeAfter | — |
+| [BioBox](./BioBox.md) | Components/Page furniture/BioBox | BioBox shows one or more author biographies in a bordered box, echoing the contributor box on Reuters.com stories. |
+| [Block](./Block.md) | Components/Page layout/Block | — |
+| [BlogPost](./BlogPost.md) | Components/Blog/BlogPost | — |
+| [BlogTOC](./BlogTOC.md) | Components/Blog/BlogTOC | — |
+| [BodyText](./BodyText.md) | Components/Text elements/BodyText | — |
+| [Byline](./Byline.md) | Components/Text elements/Byline | — |
+| [ClockWall](./ClockWall.md) | Components/Blog/ClockWall | — |
+| [cssVariables](./cssVariables.md) |  | — |
+| [DatawrapperChart](./DatawrapperChart.md) | Components/Graphics/DatawrapperChart | — |
+| [DocumentCloud](./DocumentCloud.md) | Components/Multimedia/DocumentCloud | — |
+| [EmbedPreviewerLink](./EmbedPreviewerLink.md) | Components/Utilities/EmbedPreviewerLink | — |
+| [EndNotes](./EndNotes.md) | Components/Text elements/EndNotes | — |
+| [FeaturePhoto](./FeaturePhoto.md) | Components/Multimedia/FeaturePhoto | — |
+| [Framer](./Framer.md) | Components/Utilities/Framer | — |
+| [Geocoder](./Geocoder.md) | Components/Controls/Geocoder | — |
+| [GraphicBlock](./GraphicBlock.md) | Components/Graphics/GraphicBlock | — |
+| [Headline](./Headline.md) | Components/Text elements/Headline | — |
+| [Headpile](./Headpile.md) | Components/Text elements/Headpile | — |
+| [HeroHeadline](./HeroHeadline.md) | Components/Text elements/HeroHeadline | — |
+| [HorizontalScroller](./HorizontalScroller.md) | Components/Graphics/HorizontalScroller | — |
+| [InfoBox](./InfoBox.md) | Components/Text elements/InfoBox | — |
+| [KinesisLogo](./KinesisLogo.md) | Components/Logos/KinesisLogo | — |
+| [LanguageButton](./LanguageButton.md) | Components/Text elements/LanguageButton | — |
+| [Legend](./Legend.md) | Components/Graphics/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. |
+| [Lottie](./Lottie.md) | Components/Multimedia/Lottie | — |
+| [PaddingReset](./PaddingReset.md) | Components/Page layout/PaddingReset | — |
+| [PhotoPack](./PhotoPack.md) | Components/Multimedia/PhotoPack | — |
+| [PymChild](./PymChild.md) | Components/Utilities/PymChild | — |
+| [ReferralBlock](./ReferralBlock.md) | Components/Page furniture/ReferralBlock | — |
+| [resizeObserver](./resizeObserver.md) |  | — |
+| [ReutersGraphicsLogo](./ReutersGraphicsLogo.md) | Components/Logos/ReutersGraphicsLogo | — |
+| [ReutersLogo](./ReutersLogo.md) | Components/Logos/ReutersLogo | — |
+| [Scroller](./Scroller.md) | Components/Graphics/Scroller | — |
+| [ScrollerBase](./ScrollerBase.md) | Components/Graphics/ScrollerBase | — |
+| [ScrollerVideo](./ScrollerVideo.md) | Components/Graphics/ScrollerVideo | — |
+| [SearchInput](./SearchInput.md) | Components/Controls/SearchInput | — |
+| [SEO](./SEO.md) | Components/Ads & analytics/SEO | — |
+| [ShareBar](./ShareBar.md) | Components/Page furniture/ShareBar | ShareBar shows a row of share buttons (X, Facebook, LinkedIn, Email, Copy link) and an optional "Purchase Licensing Rights" button, echoing the share toolbar on Reuters.com stories. |
+| [SimpleTimeline](./SimpleTimeline.md) | Components/Text elements/SimpleTimeline | — |
+| [SiteFooter](./SiteFooter.md) | Components/Page furniture/SiteFooter | — |
+| [SiteHeader](./SiteHeader.md) | Components/Page furniture/SiteHeader | — |
+| [SiteHeadline](./SiteHeadline.md) | Components/Text elements/SiteHeadline | — |
+| [Spinner](./Spinner.md) | Components/Utilities/Spinner | — |
+| [Table](./Table.md) | Components/Graphics/Table | — |
+| [Theme](./Theme.md) | Components/Theming/Theme | — |
+| [TileMap](./TileMap.md) | Components/Graphics/TileMap | — |
+| [ToolsHeader](./ToolsHeader.md) | Components/Page furniture/ToolsHeader | — |
+| [Video](./Video.md) | Components/Multimedia/Video | — |
+| [Visible](./Visible.md) | Components/Utilities/Visible | — |

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

@@ -0,0 +1,21 @@
+# resizeObserver
+
+**Import:** `import { resizeObserver } from '@reuters-graphics/graphics-components'`
+
+## Documentation
+
+# `resizeObserver`
+
+An action you can use to easily to check when a DOM element's dimensions change using the [Resize Observer API](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver). Use it like this:
+
+```svelte
+<script>
+  import { resizeObserver } from '@reuters-graphics/graphics-components';
+
+  let elementWidth = 0;
+</script>
+
+<div use:resizeObserver={(element) => (elementWidth = element.clientWidth)}>
+  My width is: {elementWidth}
+</div>
+```