From 27a89998a06335ccf30b3d47f327e03f61960d5a Mon Sep 17 00:00:00 2001 From: MinamiFunakoshiTR Date: Tue, 20 May 2025 12:26:03 -0700 Subject: [PATCH] makes SvelteScroller, updates docs --- .../Scroller/ScrollerBase/index.svelte | 2 +- .../SvelteScroller/SvelteScroller.mdx | 304 +++--------------- .../SvelteScroller.stories.svelte | 151 ++------- .../SvelteScroller/SvelteScroller.svelte | 8 +- 4 files changed, 80 insertions(+), 385 deletions(-) diff --git a/src/components/Scroller/ScrollerBase/index.svelte b/src/components/Scroller/ScrollerBase/index.svelte index 807f05ff..21c2d9f9 100644 --- a/src/components/Scroller/ScrollerBase/index.svelte +++ b/src/components/Scroller/ScrollerBase/index.svelte @@ -117,7 +117,7 @@ top = 0, bottom = 1, threshold = 0.5, - query = 'section', + query = 'div.step-foreground-container', parallax = false, backgroundSnippet, foregroundSnippet, diff --git a/src/components/SvelteScroller/SvelteScroller.mdx b/src/components/SvelteScroller/SvelteScroller.mdx index f8905f34..8dd2686c 100644 --- a/src/components/SvelteScroller/SvelteScroller.mdx +++ b/src/components/SvelteScroller/SvelteScroller.mdx @@ -6,274 +6,70 @@ import * as SvelteScrollerStories from './SvelteScroller.stories.svelte'; # SvelteScroller -The `SvelteScroller` component creates a basic scrollytelling graphic with layout options. +The `SvelteScroller` component is the base Scroller component that powers the [`Scroller` component](?path=/story/components-graphics-scroller--docs). It is a Svelte 5 version of the [svelte-scroller](https://github.com/sveltejs/svelte-scroller). -> This component is designed to handle most common layouts for scrollytelling. To make something more complex, customise [ScrollerBase](https://github.com/reuters-graphics/graphics-components/blob/main/src/components/Scroller/ScrollerBase/index.svelte), which is a Svelte 5 version of the [svelte-scroller](https://github.com/sveltejs/svelte-scroller). +This component allows for customisation that the [`Scroller` component](?path=/story/components-graphics-scroller--docs) can't handle. -[Demo](?path=/story/components-graphics-scroller--demo) +> **Importantโ—:** Make sure each foreground step's container is a div with the class `step-foreground-container`. If you're modifying the class, pass the appropriate selector to the `query` prop. -```svelte - - - -``` - -## Using with ArchieML and ai2svelte - -[Demo](?path=/story/components-graphics-scroller--archie-ml) - -In your graphics kit project, import your ai2svelte graphics in `App.svelte` and add them to the `aiCharts` object: +[Demo](?path=/story/components-graphics-sveltescroller--demo) ```svelte -``` - -Then add the following structure to your ArchieML Doc, making sure that the names of your charts in the `aiCharts` object match the names of each step's `background` in the ArchieML doc: - -```yaml -# ArchieML doc -[blocks] -type: ai-scroller -id: my-map-scroller -width: fluid -foregroundPosition: right -stackBackground: true - -# Array of step objects - [.steps] - background: AiMap1 - foreground: #### Step 1 - - Here's where something happend. - :end - altText: A map showing the Upper West side in New York City. - - Can add paragraphs of alt text if you want to break up sentences. - :end - - background: AiMap2 - foreground: #### Step 2 - - Something happened on some street... - :end - altText: The same map now highlights 98th Street. - :end - - background: AiMap3 - foreground: #### Step 3 - - ... and now there are multiple protests. - :end - altText: The same map now highlights three locations near 98th Street where something particulary important happened. - :end - [] -[] -``` - -Then parse the relevant ArchieML block object before passing to the `Scroller` component. - -```svelte - -{#each content.blocks as block} - {#if block.type === 'ai-scroller'} - ({ - background: aiCharts[step.background], - backgroundProps: { assetsPath: assets || '/' }, - foreground: step.foreground, - altText: step.altText, - }))} - /> - {/if} -{/each} -``` - -> **Note:** Some props, like `stackBackground`, expect boolean values. If you're using the graphics kit, use the `truthy()` util function to convert a string value to a boolean. - -> **Note:** In the graphics kit, the image source paths in ai2svelte components have to be fixed by passing `assets` to each step object, like in the example above. - -## Custom foreground - -[Demo](?path=/story/components-graphics-scroller--custom-foreground) - -Instead of just text, you can use components as foregrounds, and optionally pass props to it. - -If you're customising your own foreground component, remember to add alt text that describes the background graphic. - -```svelte - - + + {#snippet backgroundSnippet()} + +
+

+ This is the background content. It will stay fixed in place while the + foreground scrolls over the top. +

+
+ {/snippet} + {#snippet foregroundSnippet()} + +
+

Index {myIndex}: This is the first section.

+
+
+

Index {myIndex}: This is the second section.

+
+
+

Index {myIndex}: This is the third section.

+
+ {/snippet} + ``` -## Custom foreground with ArchieML +To add your own styling, you can write styles in a global SCSS stylesheet: -[Demo](?path=/story/components-graphics-scroller--customforeground-archie-ml) +```scss +// global.scss + .custom-background { + padding: 20px; + border-radius: 5px; + height: 100vh; + } -You can use custom foreground components with ArchieML with a few additional steps. + .step-foreground-container { + height: 100vh; + p { + padding: 1em; + background-color: rgba(162, 220, 231, 0.5); + } + } -In your graphics kit project's `App.svelte`, import your custom foregroud components and add them to a `foregroundComponents` object, just as you import ai2svelte background graphics and add them to the `aiCharts` object: - -```svelte - - ``` - -Then add the following structure to your ArchieML Doc, making sure that the names of your charts in the `aiCharts` and `foregroundComponents` objects match the names of each step's `background` and `foreground` in the ArchieML doc: - -```yaml -# ArchieML doc -[blocks] -type: ai-scroller -id: my-map-scroller -foregroundPosition: left -stackBackground: true - -# Array of step objects - [.steps] - background: AiMap1 - # You can still use a markdown string even if other step/s use a custom foreground component - foreground: #### Step 1 - - Here's where something happend. - :end - altText: A map showing the Upper West side in New York City. - :end - - background: AiMap2 - foreground: Foreground1 # The name of your custom foreground component - altText: The same map now highlights 98th Street. - :end - background: AiMap3 - foreground: #### Step 3 - - ... and now there are multiple protests. - :end - altText: The same map now highlights three locations near 98th Street where something particulary important happened. - :end - [] -[] -``` - -Then parse the relevant ArchieML block object before passing to the `Scroller` component. - -```svelte - -{#each content.blocks as block} - {#if block.type === 'ai-scroller'} - ({ - background: aiCharts[step.background], - backgroundProps: { assetsPath: assets || '/' }, - foreground: foregroundComponents[step.foreground] || step.foreground, - foregroundProps: { assetsPath: assets || '/' }, - altText: step.altText, - }))} - /> - {/if} -{/each} -``` - -> **Note:** You only need to pass `foregroundProps: { assetsPath: assets || '/' }` in the graphics kit if your foreground components are ai2svelte graphicss. diff --git a/src/components/SvelteScroller/SvelteScroller.stories.svelte b/src/components/SvelteScroller/SvelteScroller.stories.svelte index 76f1f4a3..30660c3f 100644 --- a/src/components/SvelteScroller/SvelteScroller.stories.svelte +++ b/src/components/SvelteScroller/SvelteScroller.stories.svelte @@ -5,155 +5,54 @@ const { Story } = defineMeta({ title: 'Components/Graphics/SvelteScroller', component: SvelteScroller, - argTypes: { - steps: { control: false }, - backgroundWidth: { - control: 'select', - options: ['normal', 'wide', 'wider', 'widest', 'fluid'], - }, - foregroundPosition: { - control: 'select', - options: ['middle', 'left', 'right', 'left opposite', 'right opposite'], - }, - embeddedLayout: { - control: 'select', - options: ['fb', 'bf'], - }, - }, }); - - {#snippet backgroundSnippet(index)} + + {#snippet backgroundSnippet()}

This is the background content. It will stay fixed in place while the foreground scrolls over the top.

- -

Section {index + 1} is currently active.

{/snippet} - {#snippet foregroundSnippet(index)} -
Index {index}: This is the first section.
-
Index {index}: This is the second section.
-
Index {index}: This is the third section.
+ {#snippet foregroundSnippet()} +
+

Index {myIndex}: This is the first section.

+
+
+

Index {myIndex}: This is the second section.

+
+
+

Index {myIndex}: This is the third section.

+
{/snippet} - - - diff --git a/src/components/SvelteScroller/SvelteScroller.svelte b/src/components/SvelteScroller/SvelteScroller.svelte index f3eaec86..21c2d9f9 100644 --- a/src/components/SvelteScroller/SvelteScroller.svelte +++ b/src/components/SvelteScroller/SvelteScroller.svelte @@ -117,7 +117,7 @@ top = 0, bottom = 1, threshold = 0.5, - query = 'section', + query = 'div.step-foreground-container', parallax = false, backgroundSnippet, foregroundSnippet, @@ -211,7 +211,7 @@ } - + - {@render backgroundSnippet(index)} + {@render backgroundSnippet()} - {@render foregroundSnippet(index)} + {@render foregroundSnippet()}