From 3ae074ab038f53e00f3263982ef6e9a59d14ebbc Mon Sep 17 00:00:00 2001 From: MinamiFunakoshiTR Date: Mon, 12 Jan 2026 10:08:09 -0500 Subject: [PATCH 1/2] adds toggle scrub demo button --- .../HorizontalScroller/HorizontalScroller.mdx | 53 +++++++++++-------- .../HorizontalScroller.stories.svelte | 47 ++++++---------- .../HorizontalScroller.svelte | 2 +- .../HorizontalScroller/demo/Demo.svelte | 29 +++++++++- 4 files changed, 76 insertions(+), 55 deletions(-) diff --git a/src/components/HorizontalScroller/HorizontalScroller.mdx b/src/components/HorizontalScroller/HorizontalScroller.mdx index c29bbd3fb..dbca16475 100644 --- a/src/components/HorizontalScroller/HorizontalScroller.mdx +++ b/src/components/HorizontalScroller/HorizontalScroller.mdx @@ -8,16 +8,17 @@ import IllustratorScreenshot from './assets/illustrator.png'; # HorizontalScroller -The `HorizontalScroller` component is helpful in making horizontal scrolling sections that respond to vertical scroll input. It is flexible in a way that it can horizontally scroll any children content wider than 100vw from one end to the other. +The `HorizontalScroller` component creates a horizontal scrolling section that scrolls through any child content wider than `100vw`. -To scroll any DOM layout wider than the viewport, wrap the content inside the `HorizontalScroller` component. The component will take care of the rest. +To use `HorizontalScroller`, wrap it around the content that you want to horizontally scroll through. The scroll length is controlled by the height of the `HorizontalScroller` container, which is set by the prop `height`. `height` defaults to `200lvh`, but you can adjust this to any valid CSS height value such as `1200px` or `400lvh`. -## Basic demo - -To use the `HorizontalScroller` component, import it and provide the children content to scroll. The scroll height defaults to `200lvh`, but you can adjust this to any valid CSS height value such as `1200px` or `200lvh` with the `height` prop. +The child content inside the `HorizontalScroller` must be wider than `100vw` so that there is overflow to horizontal scroll through. By default, only the top `100lvh` of the child content is visible. You can use CSS `transform: translate()` on the child content to adjust its vertical positioning within the visible area. > đź’ˇTIP: Use `lvh` or `svh` units instead of `vh` unit for the height, as [these units](https://www.w3.org/TR/css-values-4/#large-viewport-size) are more reliable on mobile or other devices where elements such as the address bar toggle between being shown and hidden. +Set the `showDebugInfo` prop to `true` to visualise the scroll progress and other useful information. + + [Demo](?path=/story/components-graphics-horizontalscroller--demo) ```svelte @@ -25,36 +26,46 @@ To use the `HorizontalScroller` component, import it and provide the children co import { HorizontalScroller } from '@reuters-graphics/graphics-components'; - - -
- - - alt text + + + +
+ alt text
``` -## With stops +## Controlling scroll with stops and easing + +The `HorizontalScroller` allows you to control the horizontal scroll experience using various props. + +**`stops`:** -The `HorizontalScroller` also allows you to define a set of points to stop or slow down the scrolling at specific intervals using the `stops` prop. This is useful for creating step-based horizontal scrolling experiences. +`stops` is an optional prop that accepts an array of numbers between `0` and `1` — which corresponds to the scroll `progress` — at which to stop or slow down the scrolling. This is useful for creating progress-based horizontal scrolling experiences. -The `scrubbed` prop can be used to define whether the scrolling experience should be smooth or tied directly to the scroll position. Setting `scrubbed` to `true` will make the horizontal scroll position directly correspond to the vertical scroll position, while setting it to `false` will create a smooth scrolling effect. +For example, as shown in the demo below, if you define `stops` as `[0.2, 0.5, 0.6, 0.7]`, the scrolling will pause or slow down at these `progress` values as the user scrolls through the `HorizontalScroller` section. -If `scrubbed` is set to `false` and `stops` are defined, the scroller will transition smoothly to the next stop when the `Mapped Progress` reaches the midpoint between the two stops. The transition speed is controlled by the `duration` prop (in milliseconds) and the `easing` prop (which accepts any easing function from `svelte/easing` or a custom function based on signature `(t: number) => number`). +**`scrubbed`, `duration`, and `easing`:** +The `scrubbed` prop controls whether the scrolling tied exactly to the scroll position (`scrubbed: true`) or is smoothed out (`scrubbed: false`). The prop defaults to `true`. + +If `scrubbed` is set to `false` and `stops` are defined, `HorizontalScroller` transitions smoothly between the stop values. + +when the `Mapped Progress` reaches the midpoint between the two stops. The transition speed is controlled by the `duration` prop (in milliseconds) and the `easing` prop (which accepts any easing function from `svelte/easing` or a custom function based on signature `(t: number) => number`). If `scrubbed` is set to `true` and `stops` are defined, all the stops are traversed at equal distance but based on the easing function provided. -Use `showDebugInfo` prop to visualize the scroll progress and other useful debug information. The `Progress` indicates the vertical progress with values in the range 0...1 indicating the content being locked or a user-fed value to control the horizontal scroll position. The `Mapped Progress` value indicates the vertical progress mapped to mappedStart and mappedEnd values. By default these are 0 and 1 respectively. Finally, the `Eased Progress` value indicates the horizontal scroll progress after applying stops and easing (if any). `Eased Progress` accurately reflects the transition of horizontal scroll position. -Feel free to toggle `scrubbed` prop here to see the difference. + + `Progress` indicates the scroll progress value between `0` and `1`. The `Mapped Progress` indicates the vertical progress mapped to `mappedStart` and `mappedEnd` values. By default these are 0 and 1 respectively. Finally, the `Eased Progress` value indicates the horizontal scroll progress after applying stops and easing (if any). `Eased Progress` accurately reflects the transition of horizontal scroll position. [Demo](?path=/story/components-graphics-horizontalscroller--demo) +[Demo](?path=/story/components-graphics-horizontalscroller--with-stops) + ```svelte - - {#snippet DemoSnippet()} @@ -32,36 +29,24 @@ {/snippet} - - {#snippet children(args)} - - {/snippet} + + + + - - {#snippet children(args)} - - - - {/snippet} + + + + + + import { onMount, type Snippet } from 'svelte'; import { Tween } from 'svelte/motion'; - import type { Action } from 'svelte/action'; import { clamp, map } from './utils/index'; + import type { Action } from 'svelte/action'; import Debug from './Debug.svelte'; interface Props { diff --git a/src/components/HorizontalScroller/demo/Demo.svelte b/src/components/HorizontalScroller/demo/Demo.svelte index 5f0fd9d58..157c5d108 100644 --- a/src/components/HorizontalScroller/demo/Demo.svelte +++ b/src/components/HorizontalScroller/demo/Demo.svelte @@ -1,15 +1,40 @@ - +{#if args.toggleScrub} + + + +{/if} + + + + From 0ab89de32aae8720a6b9dfa5b1a810c8afb56258 Mon Sep 17 00:00:00 2001 From: MinamiFunakoshiTR Date: Mon, 12 Jan 2026 12:42:17 -0500 Subject: [PATCH 2/2] edits demos, documentation --- .../HorizontalScroller/HorizontalScroller.mdx | 422 +++++++++--------- .../HorizontalScroller.stories.svelte | 76 +--- .../HorizontalScroller.svelte | 3 +- .../HorizontalScroller/assets/illustrator.jpg | Bin 0 -> 255597 bytes .../HorizontalScroller/assets/illustrator.png | Bin 1307269 -> 0 bytes .../demo/AdvancedScrollableGraphic.svelte | 53 +-- .../HorizontalScroller/demo/Demo.svelte | 4 +- .../demo/ScrollableGraphic.svelte | 15 +- .../demo/withScrollerBase.svelte | 42 +- 9 files changed, 291 insertions(+), 324 deletions(-) create mode 100644 src/components/HorizontalScroller/assets/illustrator.jpg delete mode 100644 src/components/HorizontalScroller/assets/illustrator.png diff --git a/src/components/HorizontalScroller/HorizontalScroller.mdx b/src/components/HorizontalScroller/HorizontalScroller.mdx index dbca16475..d6efad902 100644 --- a/src/components/HorizontalScroller/HorizontalScroller.mdx +++ b/src/components/HorizontalScroller/HorizontalScroller.mdx @@ -2,7 +2,7 @@ import { Meta } from '@storybook/blocks'; import * as HorizontalScrollerStories from './HorizontalScroller.stories.svelte'; -import IllustratorScreenshot from './assets/illustrator.png'; +import IllustratorScreenshot from './assets/illustrator.jpg'; @@ -16,192 +16,128 @@ The child content inside the `HorizontalScroller` must be wider than `100vw` so > 💡TIP: Use `lvh` or `svh` units instead of `vh` unit for the height, as [these units](https://www.w3.org/TR/css-values-4/#large-viewport-size) are more reliable on mobile or other devices where elements such as the address bar toggle between being shown and hidden. -Set the `showDebugInfo` prop to `true` to visualise the scroll progress and other useful information. +> 💡TIP: Set the `showDebugInfo` prop to `true` to visualise the scroll progress and other useful information. - -[Demo](?path=/story/components-graphics-horizontalscroller--demo) +See the full list of available props under the `Controls` tab in the [demo](?path=/story/components-graphics-horizontalscroller--demo). ```svelte - - - -
- alt text -
- + + + + + +
+ alt text +
+ + ``` -## Controlling scroll with stops and easing +## Controlling scroll behaviour with stops and easing -The `HorizontalScroller` allows you to control the horizontal scroll experience using various props. +The `HorizontalScroller` allows you to control the horizontal scroll behaviour and pacing with various props. **`stops`:** -`stops` is an optional prop that accepts an array of numbers between `0` and `1` — which corresponds to the scroll `progress` — at which to stop or slow down the scrolling. This is useful for creating progress-based horizontal scrolling experiences. - -For example, as shown in the demo below, if you define `stops` as `[0.2, 0.5, 0.6, 0.7]`, the scrolling will pause or slow down at these `progress` values as the user scrolls through the `HorizontalScroller` section. +`stops` is an optional prop that accepts an array of numbers between `0` and `1`. At these points, which corresponds to the scroll `progress` values, the scrolling stops or slows down. This is useful for adding custom pauses based on progress. -**`scrubbed`, `duration`, and `easing`:** -The `scrubbed` prop controls whether the scrolling tied exactly to the scroll position (`scrubbed: true`) or is smoothed out (`scrubbed: false`). The prop defaults to `true`. +For example, as shown in the demo below, if you define `stops` as `[0.2, 0.5, 0.9]`, the scrolling will pause or slow down at these `progress` values as the user scrolls through the `HorizontalScroller` section. -If `scrubbed` is set to `false` and `stops` are defined, `HorizontalScroller` transitions smoothly between the stop values. +**`scrubbed`:** -when the `Mapped Progress` reaches the midpoint between the two stops. The transition speed is controlled by the `duration` prop (in milliseconds) and the `easing` prop (which accepts any easing function from `svelte/easing` or a custom function based on signature `(t: number) => number`). +The `scrubbed` prop controls whether the scrolling is tied exactly to the scroll position (`scrubbed: true`) or is smoothed out (`scrubbed: false`). This prop defaults to `true`. -If `scrubbed` is set to `true` and `stops` are defined, all the stops are traversed at equal distance but based on the easing function provided. +If `scrubbed` is set to `false` and `stops` are defined, the scrolling transitions smoothly between the stop values. +**`easing`** and **`duration`**: +`easing` accepts any easing function from `svelte/easing` or a custom easing function, while `duration` sets the time, in milliseconds, for each transition between stops. +So, if the stops are at irregular intervals — for example, `[0.2, 0.9]` — the scroll to the first stop will be much quicker than the scroll to the second stop since the distance to travel is different but the duration of the transition is the same. - `Progress` indicates the scroll progress value between `0` and `1`. The `Mapped Progress` indicates the vertical progress mapped to `mappedStart` and `mappedEnd` values. By default these are 0 and 1 respectively. Finally, the `Eased Progress` value indicates the horizontal scroll progress after applying stops and easing (if any). `Eased Progress` accurately reflects the transition of horizontal scroll position. -[Demo](?path=/story/components-graphics-horizontalscroller--demo) +By default, `duration` is set to `400` milliseconds. [Demo](?path=/story/components-graphics-horizontalscroller--with-stops) ```svelte - -
- - - alt text -
- + + + + +
+ alt text +
+ + ``` -## Extended boundary +## Extended boundaries -`HorizontalScroller` also provides `mappedStart` and `mappedEnd` props to extend the horizontal scroll boundaries beyond the default 0 to 1 range. This is useful when you want to create an overscroll effect or have more control over the horizontal scroll range. By default these values are set to 0 and 1 respectively. +`HorizontalScroller` has `mappedStart` and `mappedEnd` props, which extend the horizontal scroll boundaries beyond the default 0 to 1 range. This is useful when you want to create an overscroll effect or have more control over the horizontal scroll range. By default, these values are set to 0 and 1 respectively. -[Demo](?path=/story/components-graphics-horizontalscroller--extended-boundary) +If using custom `mappedStart` and `mappedEnd` values, you must also set `stops` values that are within the mapped range. -```svelte - - - -
- - - alt text -
- -``` +> đź’ˇTIP: In the debugging info box, `Progress` indicates the raw scroll progress value between `0` and `1`. `Mapped Progress` indicates the vertical progress mapped to `mappedStart` and `mappedEnd`. If they are not set, `Mapped Progress` is bound between 0 and 1 and matches `Progress`. `Eased Progress` indicates the scroll progress with any stops and easing applied. `Eased Progress` is what reflects the actual transition of the horizontal scroll position. -## With custom child components - -You can create a horizontal stack of any components and pass it as children to the `HorizontalScroller`. Here's an example of using `DatawrapperChart`, `Headline` and ai2svelte components inside the scroller. - -[Demo](?path=/story/components-graphics-horizontalscroller--custom-children) +[Demo](?path=/story/components-graphics-horizontalscroller--extended-boundaries) ```svelte - - -
-
- -
-
- + + + +
+ alt text
-
- - - -
-
- - - + + ``` ## With ai2svelte components -With ai2svelte v1.0.3 onwards, you can export your ai2svelte graphic with a wider-than-viewport layout and use it directly inside the `HorizontalScroller` component to create horizontal scrolling graphics. +With [ai2svelte](https://reuters-graphics.github.io/ai2svelte/) v1.0.3 onwards, you can export your ai2svelte graphic with a wider-than-viewport layout and use it directly inside `HorizontalScroller` to create horizontally scrolling graphics. To do that, follow these steps: -1. In Illustrator, rename your artboard with a tag indicating breakpoint width for that artboard to be visible on page. For example, to make the XL artboard visible on viewports wider than 1200px, rename the artboard to `xl:1200`. You can have more than one artboard with different breakpoint widths. -2. In ai2svelte settings, set these properties and run ai2svelte to export the component. +1. In Illustrator, rename your artboard with the breakpoint at which you want that artboard to be visible on the page. For example, to make the XL artboard visible on viewports wider than 1200px, rename it to `xl:1200`. You can have multiple artboards with different breakpoints. +2. Add these properties to the ai2svelte settings and run the script to export the component. ```yaml include_resizer_css: false @@ -218,35 +154,50 @@ allow_overflow: true ```svelte - - - + + + + + + ``` -## With ai2svelte components (advanced) +## With ai2svelte components: advanced + +You can use the bound prop `progress` to create advanced interactivity with an ai2svelte graphic. + +The demo below has 2 advanced interactions: fade in/out of caption boxes based on scroll position and parallax movement of a `png` layer. -Binding the `progress` can be useful to even transition tagged content inside the ai2svelte graphic as part of the horizontal scrolling experience. For example, caption boxes exported as `htext` tagged layers can be animated to fade in/out or move in/out of view based on the scroll progress. Or one could even use tagged `png` layers to create parallax effects. +### Captions fading in/out + +Caption boxes are exported as `htext` [tagged layers](https://reuters-graphics.github.io/ai2svelte/users/tagged-layers/) in ai2svelte. In this example, we use the `handleScroll()` function to check the position of each caption box relative to the viewport width and set its opacity to `1` (visible) or `0` (hidden) based on whether the caption box is within the `threshold` of the viewport. + +### Parallax effect with png layer + +This demo has a tagged `png` [layer](https://reuters-graphics.github.io/ai2svelte/users/tagged-layers/), which contains the foreground overlay image. The `handleScroll()` function uses the bound `progress` value to calculate a horizontal translation for the `png` layer, creating a parallax effect as the user scrolls through the `HorizontalScroller`. [Demo](?path=/story/components-graphics-horizontalscroller--scrollable-ai-2-svelte-advanced) ```svelte - - - + + + + Caption 1!
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
', + caption2: + '
Caption 2!
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
', + caption3: + '
Caption 3!
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
', + caption4: + '
Caption 4!
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
', + }, + }, + }} /> + + ``` + +## With custom child components + +You can create a custom horizontal layout with any component and pass it as a child to the `HorizontalScroller`. Here's an example with `DatawrapperChart`, `Headline` and ai2svelte components laid out in a horizontal scroll. + +[Demo](?path=/story/components-graphics-horizontalscroller--custom-children) + +```svelte + + + + + +
+
+ +
+
+ +
+
+ + + +
+
+ + + + +``` + ## With ScrollerBase -You can also integrate HorizontalScroller with `ScrollerBase` for a horizontal scroll with vertical captions experience. +You can also integrate HorizontalScroller with `ScrollerBase` for a horizontal scroll with vertical captions. -[Demo](?path=/story/components-graphics-horizontalscroller--scrollable-ai-2-svelte) +When using `HorizontalScroller` with `ScrollerBase` or other scrollers, you must: +- Create a `progress` state variable and bind it to both `ScrollerBase` and `HorizontalScroller` +- Set `HorizontalScroller`'s `height` to `100lvh` +- Set `handleScroll` to `false` + +[Demo](?path=/story/components-graphics-horizontalscroller--with-scroller-base) ```svelte - + {#snippet backgroundSnippet()} - - - - - + + + + + + {/snippet} {#snippet foregroundSnippet()} diff --git a/src/components/HorizontalScroller/HorizontalScroller.stories.svelte b/src/components/HorizontalScroller/HorizontalScroller.stories.svelte index f1bcb17f5..5e9f104a3 100644 --- a/src/components/HorizontalScroller/HorizontalScroller.stories.svelte +++ b/src/components/HorizontalScroller/HorizontalScroller.stories.svelte @@ -1,14 +1,14 @@ - + {#snippet backgroundSnippet()} - - - - + + + + + {/snippet} {#snippet foregroundSnippet()}