@reuters-graphics/graphics-components 2.0.2 → 3.0.0

package/dist/components/Scroller/Embedded/Background.svelte

@@ -1,14 +1,18 @@
-<script>export let step;
-export let backgroundWidth;
-export let index;
-import Block from "../../Block/Block.svelte";
+<script lang="ts">
+  import type { ContainerWidth, ScrollerStep } from '../../@types/global';
+
+  import Block from '../../Block/Block.svelte';
+  interface Props {
+    step: ScrollerStep;
+    backgroundWidth: ContainerWidth;
+    index: number;
+  }
+
+  let { step, backgroundWidth, index }: Props = $props();
 </script>
 
-<Block width="{backgroundWidth}" class="background-container step-{index + 1}">
+<Block width={backgroundWidth} class="background-container step-{index + 1}">
   <div class="embedded-background step-{index + 1}" aria-hidden="true">
-    <svelte:component
-      this="{step.background}"
-      {...step.backgroundProps || {}}
-    />
+    <step.background {...step.backgroundProps || {}}></step.background>
   </div>
 </Block>

package/dist/components/Scroller/Embedded/Background.svelte.d.ts

@@ -1,21 +1,9 @@
-import { SvelteComponent } from "svelte";
 import type { ContainerWidth, ScrollerStep } from '../../@types/global';
-declare const __propDef: {
-    props: {
-        step: ScrollerStep;
-        backgroundWidth: ContainerWidth;
-        index: number;
-    };
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {};
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type BackgroundProps = typeof __propDef.props;
-export type BackgroundEvents = typeof __propDef.events;
-export type BackgroundSlots = typeof __propDef.slots;
-export default class Background extends SvelteComponent<BackgroundProps, BackgroundEvents, BackgroundSlots> {
+interface Props {
+    step: ScrollerStep;
+    backgroundWidth: ContainerWidth;
+    index: number;
 }
-export {};
+declare const Background: import("svelte").Component<Props, {}, "">;
+type Background = ReturnType<typeof Background>;
+export default Background;

package/dist/components/Scroller/Embedded/Foreground.svelte

@@ -1,7 +1,15 @@
-<script>export let step;
-export let index;
-import Block from "../../Block/Block.svelte";
-import Markdown from "../../Markdown/Markdown.svelte";
+<script lang="ts">
+  import type { ScrollerStep } from '../../@types/global';
+
+  import Block from '../../Block/Block.svelte';
+  import { Markdown } from '@reuters-graphics/svelte-markdown';
+
+  interface Props {
+    step: ScrollerStep;
+    index: number;
+  }
+
+  let { step, index }: Props = $props();
 </script>
 
 {#if step.foreground === '' || !step.foreground}
@@ -10,27 +18,24 @@ import Markdown from "../../Markdown/Markdown.svelte";
 
   {#if typeof step.altText === 'string'}
     <div class="background-alt-text visually-hidden">
-      <Markdown source="{step.altText}" />
+      <Markdown source={step.altText} />
     </div>
   {/if}
 {:else if typeof step.foreground === 'string'}
   <Block class="body-text step-{index + 1}">
     <div class="embedded-foreground step-{index + 1}">
-      <Markdown source="{step.foreground}" />
+      <Markdown source={step.foreground} />
     </div>
 
     {#if typeof step.altText === 'string'}
       <div class="background-alt-text visually-hidden">
-        <Markdown source="{step.altText}" />
+        <Markdown source={step.altText} />
       </div>
     {/if}
   </Block>
 {:else}
   <div class="embedded-foreground step-{index + 1}">
-    <svelte:component
-      this="{step.foreground}"
-      {...step.foregroundProps || {}}
-    />
+    <step.foreground {...step.foregroundProps || {}}></step.foreground>
   </div>
 {/if}
 

package/dist/components/Scroller/Embedded/Foreground.svelte.d.ts

@@ -1,20 +1,8 @@
-import { SvelteComponent } from "svelte";
 import type { ScrollerStep } from '../../@types/global';
-declare const __propDef: {
-    props: {
-        step: ScrollerStep;
-        index: number;
-    };
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {};
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type ForegroundProps = typeof __propDef.props;
-export type ForegroundEvents = typeof __propDef.events;
-export type ForegroundSlots = typeof __propDef.slots;
-export default class Foreground extends SvelteComponent<ForegroundProps, ForegroundEvents, ForegroundSlots> {
+interface Props {
+    step: ScrollerStep;
+    index: number;
 }
-export {};
+declare const Foreground: import("svelte").Component<Props, {}, "">;
+type Foreground = ReturnType<typeof Foreground>;
+export default Foreground;

package/dist/components/Scroller/Embedded/index.svelte

@@ -1,8 +1,21 @@
-<script>export let steps = [];
-export let embeddedLayout = "fb";
-export let backgroundWidth = "fluid";
-import Background from "./Background.svelte";
-import Foreground from "./Foreground.svelte";
+<script lang="ts">
+  import type { ContainerWidth, ScrollerStep } from '../../@types/global';
+
+  type EmbeddedLayout = 'fb' | 'bf';
+
+  import Background from './Background.svelte';
+  import Foreground from './Foreground.svelte';
+  interface Props {
+    steps: ScrollerStep[];
+    embeddedLayout?: EmbeddedLayout;
+    backgroundWidth?: ContainerWidth;
+  }
+
+  let {
+    steps,
+    embeddedLayout = 'fb',
+    backgroundWidth = 'fluid',
+  }: Props = $props();
 </script>
 
 {#each steps as step, index}

package/dist/components/Scroller/Embedded/index.svelte.d.ts

@@ -1,21 +1,10 @@
-import { SvelteComponent } from "svelte";
 import type { ContainerWidth, ScrollerStep } from '../../@types/global';
-declare const __propDef: {
-    props: {
-        steps?: ScrollerStep[];
-        embeddedLayout?: "fb" | "bf";
-        backgroundWidth?: ContainerWidth;
-    };
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {};
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type IndexProps = typeof __propDef.props;
-export type IndexEvents = typeof __propDef.events;
-export type IndexSlots = typeof __propDef.slots;
-export default class Index extends SvelteComponent<IndexProps, IndexEvents, IndexSlots> {
+type EmbeddedLayout = 'fb' | 'bf';
+interface Props {
+    steps: ScrollerStep[];
+    embeddedLayout?: EmbeddedLayout;
+    backgroundWidth?: ContainerWidth;
 }
-export {};
+declare const Index: import("svelte").Component<Props, {}, "">;
+type Index = ReturnType<typeof Index>;
+export default Index;

package/dist/components/Scroller/Foreground.svelte

@@ -1,5 +1,13 @@
-<script>export let steps = [];
-import Markdown from "../Markdown/Markdown.svelte";
+<script lang="ts">
+  import type { ScrollerStep } from '../@types/global';
+
+  import { Markdown } from '@reuters-graphics/svelte-markdown';
+
+  interface Props {
+    steps: ScrollerStep[];
+  }
+
+  let { steps }: Props = $props();
 </script>
 
 {#each steps as step, i}
@@ -12,23 +20,20 @@ import Markdown from "../Markdown/Markdown.svelte";
       <div class="empty-step-foreground"></div>
       {#if typeof step.altText === 'string'}
         <div class="background-alt-text visually-hidden">
-          <Markdown source="{step.altText}" />
+          <Markdown source={step.altText} />
         </div>
       {/if}
     {:else}
       <div class="step-foreground w-full">
         {#if typeof step.foreground === 'string'}
-          <Markdown source="{step.foreground}" />
+          <Markdown source={step.foreground} />
         {:else}
-          <svelte:component
-            this="{step.foreground}"
-            {...step.foregroundProps || {}}
-          />
+          <step.foreground {...step.foregroundProps || {}}></step.foreground>
         {/if}
       </div>
       {#if typeof step.altText === 'string'}
         <div class="background-alt-text visually-hidden">
-          <Markdown source="{step.altText}" />
+          <Markdown source={step.altText} />
         </div>
       {/if}
     {/if}

package/dist/components/Scroller/Foreground.svelte.d.ts

@@ -1,19 +1,7 @@
-import { SvelteComponent } from "svelte";
 import type { ScrollerStep } from '../@types/global';
-declare const __propDef: {
-    props: {
-        steps?: ScrollerStep[];
-    };
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {};
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type ForegroundProps = typeof __propDef.props;
-export type ForegroundEvents = typeof __propDef.events;
-export type ForegroundSlots = typeof __propDef.slots;
-export default class Foreground extends SvelteComponent<ForegroundProps, ForegroundEvents, ForegroundSlots> {
+interface Props {
+    steps: ScrollerStep[];
 }
-export {};
+declare const Foreground: import("svelte").Component<Props, {}, "">;
+type Foreground = ReturnType<typeof Foreground>;
+export default Foreground;

package/dist/components/Scroller/Scroller.mdx

@@ -0,0 +1,279 @@
+import { Meta } from '@storybook/blocks';
+
+import * as ScrollerStories from './Scroller.stories.svelte';
+
+<Meta of={ScrollerStories} />
+
+# Scroller
+
+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
+<script>
+  import { Scroller } from '@reuters-graphics/graphics-components';
+
+  import MyBackground from './MyBackground.svelte'; // Your own background component
+
+  // Array of step objects that define the steps in your scroller.
+  const steps = [
+    {
+      background: MyBackground,
+      backgroundProps: { colour: 'red' }, // Optional props for your background component
+      foreground: '#### Step 1\n\nLorem ipsum red',
+      altText: 'Red background',
+    },
+    {
+      background: MyBackground,
+      backgroundProps: { colour: 'blue' },
+      foreground: '#### Step 2\n\nLorem ipsum blue',
+      altText: 'Blue background',
+    },
+    {
+      background: MyBackground,
+      backgroundProps: { colour: 'green' },
+      foreground: '#### Step 3\n\nLorem ipsum green',
+      altText: 'Green background',
+    },
+  ];
+</script>
+
+<Scroller {steps} foregroundPosition="middle" backgroundWidth="fluid" />
+```
+
+## 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
+<!-- App.svelte -->
+<script>
+  import AiMap1 from './ai2svelte/my-map-1.svelte';
+  import AiMap2 from './ai2svelte/my-map-2.svelte';
+  import AiMap3 from './ai2svelte/my-map-3.svelte';
+
+  import content from '$locales/en/content.json';
+
+  // Graphics kit only
+  import { assets } from '$app/paths'; // 👈 If using in the graphics kit...
+  import { truthy } from '$utils/propValidators'; // 👈 If using in the graphics kit...
+
+  const aiCharts = {
+    AiMap1,
+    AiMap2,
+    AiMap3,
+    // Other charts...
+  };
+</script>
+```
+
+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
+<!-- App.svelte -->
+{#each content.blocks as block}
+  {#if block.type === 'ai-scroller'}
+    <Scroller
+      id={block.id}
+      backgroundWidth={block.width}
+      foregroundPosition={block.foregroundPosition}
+      stackBackground={truthy(block.stackBackground)}
+      steps={block.steps.map((step) => ({
+        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
+<script>
+  import MyBackground from './MyBackground.svelte'; // Your own background component
+  import MyInteractiveForeground from './MyInteractiveForeground.svelte'; // Your custom foreground component
+
+  const steps = [
+    {
+      background: MyBackground,
+      backgroundProps: { colour: 'red' }, // Props for your background component, if needed
+      foreground: MyInteractiveForeground, // Custom foreground component
+    },
+    {
+      background: MyBackground,
+      backgroundProps: { colour: 'blue' },
+      foreground: '#### Step 2\n\nLorem ipsum blue', // You can still add a markdown string as foreground; you can mix and match
+    },
+    {
+      background: MyBackground,
+      backgroundProps: { colour: 'green' },
+      foreground: MyInteractiveForeground,
+      foregroundProps: { count: 100 }, // Props for your custom foreground component, if needed
+    },
+  ];
+</script>
+
+<Scroller {steps} />
+```
+
+## 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
+<!-- App.svelte -->
+<script>
+  import content from '$locales/en/content.json';
+
+  // Background ai2svelte graphics
+  import AiMap1 from './ai2svelte/my-map-1.svelte';
+  import AiMap2 from './ai2svelte/my-map-2.svelte';
+  import AiMap3 from './ai2svelte/my-map-3.svelte';
+
+  // Foreground components, which can be ai2svelte or not.
+  import Foreground1 from './ai2svelte/my-foreground-1.svelte';
+
+  // Graphics kit only
+  import { assets } from '$app/paths'; // 👈 If using in the graphics kit...
+  import { truthy } from '$utils/propValidators'; // 👈 If using in the graphics kit...
+
+  // Background ai2svelte graphics components
+  const aiCharts = {
+    AiMap1,
+    AiMap2,
+    AiMap3,
+    // Other charts...
+  };
+
+  // Foreground components
+  const foregroundComponents = {
+    Foreground1,
+    // Other components...
+  };
+</script>
+```
+
+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
+<!-- App.svelte -->
+{#each content.blocks as block}
+  {#if block.type === 'ai-scroller'}
+    <Scroller
+      id={block.id}
+      backgroundWidth={block.width}
+      foregroundPosition={block.foregroundPosition}
+      stackBackground={truthy(block.stackBackground)}
+      steps={block.steps.map((step) => ({
+        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.