diff --git a/src/components/@types/global.ts b/src/components/@types/global.ts index 97075269..0d9323ba 100644 --- a/src/components/@types/global.ts +++ b/src/components/@types/global.ts @@ -45,7 +45,7 @@ export interface ScrollerStep { */ foregroundProps?: object; /** - * Optional alt text for the background, read aloud after the foregroud text. You can add it to each step or just to the first step to describe the entire scroller graphic. + * Optional alt text for the background, read aloud after the foreground text. You can add it to each step or just to the first step to describe the entire scroller graphic. */ altText?: string; } diff --git a/src/components/Scroller/Background.svelte b/src/components/Scroller/Background.svelte index 0f568478..337a3c15 100644 --- a/src/components/Scroller/Background.svelte +++ b/src/components/Scroller/Background.svelte @@ -3,17 +3,12 @@ interface Props { index: number; - steps?: ScrollerStep[]; + steps: ScrollerStep[]; preload?: number; stackBackground?: boolean; } - let { - index, - steps = [], - preload = 1, - stackBackground = true, - }: Props = $props(); + let { index, steps, preload = 1, stackBackground = true }: Props = $props(); {#each steps as step, i} @@ -22,8 +17,8 @@ {#if preload === 0 || (i >= (stackBackground ? 0 : index - preload) && i <= index + preload)}
index : i !== index} >
diff --git a/src/components/Scroller/Embedded/Foreground.svelte b/src/components/Scroller/Embedded/Foreground.svelte index c959a658..d3fe2d81 100644 --- a/src/components/Scroller/Embedded/Foreground.svelte +++ b/src/components/Scroller/Embedded/Foreground.svelte @@ -17,18 +17,18 @@ {#if typeof step.altText === 'string'}
- +
{/if} {:else if typeof step.foreground === 'string'}
- +
{#if typeof step.altText === 'string'}
- +
{/if}
diff --git a/src/components/Scroller/Embedded/index.svelte b/src/components/Scroller/Embedded/index.svelte index 6c1d0380..11484017 100644 --- a/src/components/Scroller/Embedded/index.svelte +++ b/src/components/Scroller/Embedded/index.svelte @@ -6,13 +6,13 @@ import Background from './Background.svelte'; import Foreground from './Foreground.svelte'; interface Props { - steps?: ScrollerStep[]; + steps: ScrollerStep[]; embeddedLayout?: EmbeddedLayout; backgroundWidth?: ContainerWidth; } let { - steps = [], + steps, embeddedLayout = 'fb', backgroundWidth = 'fluid', }: Props = $props(); diff --git a/src/components/Scroller/Foreground.svelte b/src/components/Scroller/Foreground.svelte index 58068a49..196144c1 100644 --- a/src/components/Scroller/Foreground.svelte +++ b/src/components/Scroller/Foreground.svelte @@ -3,10 +3,10 @@ import Markdown from '../Markdown/Markdown.svelte'; interface Props { - steps?: ScrollerStep[]; + steps: ScrollerStep[]; } - let { steps = [] }: Props = $props(); + let { steps }: Props = $props(); {#each steps as step, i} @@ -19,20 +19,20 @@
{#if typeof step.altText === 'string'}
- +
{/if} {:else}
{#if typeof step.foreground === 'string'} - + {:else} {/if}
{#if typeof step.altText === 'string'}
- +
{/if} {/if} diff --git a/src/components/Scroller/Scroller.mdx b/src/components/Scroller/Scroller.mdx index f804bd15..c6b8e498 100644 --- a/src/components/Scroller/Scroller.mdx +++ b/src/components/Scroller/Scroller.mdx @@ -6,14 +6,274 @@ import * as ScrollerStories from './Scroller.stories.svelte'; # Scroller -The `Scroller` component TK. +The `Scroller` component creates a basic scrollytelling graphic with layout options. + +> 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). [Demo](?path=/story/components-graphics-scroller--demo) ```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: + +```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 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 + + + +``` + +## Custom foreground with ArchieML + +[Demo](?path=/story/components-graphics-scroller--customforeground-archie-ml) + +You can use custom foreground components with ArchieML with a few additional steps. + +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 Graphics Kit if your foreground components are ai2svelte graphicss. diff --git a/src/components/Scroller/Scroller.stories.svelte b/src/components/Scroller/Scroller.stories.svelte index 63986f0b..02cd1dcc 100644 --- a/src/components/Scroller/Scroller.stories.svelte +++ b/src/components/Scroller/Scroller.stories.svelte @@ -24,38 +24,69 @@ + +
+ + {#if width && width >= 0} +
+
+
+
+

Likelihood of something happening

+
+ +
+

0-25%

+
+
+

50-75%

+
+
+

75-100%

+
+
+

25-50%

+
+
+ {/if} +
+ + + + + + diff --git a/src/components/Scroller/demo/components/ai2svelte/ai-scroller-1.svelte b/src/components/Scroller/demo/components/ai2svelte/ai-scroller-1.svelte index 37392f3c..6293b3d0 100644 --- a/src/components/Scroller/demo/components/ai2svelte/ai-scroller-1.svelte +++ b/src/components/Scroller/demo/components/ai2svelte/ai-scroller-1.svelte @@ -1,21 +1,16 @@ -
+
{#if width && width >= 1200}
diff --git a/src/components/Scroller/demo/components/ai2svelte/images/Body-issues-key-xs.png b/src/components/Scroller/demo/components/ai2svelte/images/Body-issues-key-xs.png new file mode 100644 index 00000000..e03e5e19 Binary files /dev/null and b/src/components/Scroller/demo/components/ai2svelte/images/Body-issues-key-xs.png differ diff --git a/src/components/Scroller/demo/components/ai2svelte/images/ai-chart-md.png b/src/components/Scroller/demo/components/ai2svelte/images/ai-chart-md.png new file mode 100644 index 00000000..8421cf9f Binary files /dev/null and b/src/components/Scroller/demo/components/ai2svelte/images/ai-chart-md.png differ diff --git a/src/components/Scroller/demo/components/ai2svelte/images/ai-chart-sm.png b/src/components/Scroller/demo/components/ai2svelte/images/ai-chart-sm.png new file mode 100644 index 00000000..7dd8b9e9 Binary files /dev/null and b/src/components/Scroller/demo/components/ai2svelte/images/ai-chart-sm.png differ diff --git a/src/components/Scroller/demo/components/ai2svelte/images/ai-chart-xs.png b/src/components/Scroller/demo/components/ai2svelte/images/ai-chart-xs.png new file mode 100644 index 00000000..15ea47a1 Binary files /dev/null and b/src/components/Scroller/demo/components/ai2svelte/images/ai-chart-xs.png differ diff --git a/src/components/Scroller/demo/components/basic/InteractiveForeground.svelte b/src/components/Scroller/demo/components/basic/InteractiveForeground.svelte index 63c91bee..769ec63b 100644 --- a/src/components/Scroller/demo/components/basic/InteractiveForeground.svelte +++ b/src/components/Scroller/demo/components/basic/InteractiveForeground.svelte @@ -8,10 +8,10 @@

Interactive step

-

The count is {count}

+

The count is {count}

Click Me diff --git a/src/components/Scroller/demo/components/basic/Step.svelte b/src/components/Scroller/demo/components/basic/Step.svelte index 05b95243..d914ec8a 100644 --- a/src/components/Scroller/demo/components/basic/Step.svelte +++ b/src/components/Scroller/demo/components/basic/Step.svelte @@ -6,7 +6,7 @@ let { colour = 'lightblue' }: Props = $props(); -
+