@reuters-graphics/graphics-components 2.0.2 → 3.0.0

package/dist/components/Analytics/Analytics.mdx

@@ -0,0 +1,73 @@
+import { Meta } from '@storybook/blocks';
+
+import * as AnalyticsStories from './Analytics.stories.svelte';
+
+<Meta of={AnalyticsStories} />
+
+# Analytics
+
+The `Analytics` component adds Google and Chartbeat analytics to your page.
+
+```svelte
+<script>
+  import { Analytics } from '@reuters-graphics/graphics-components';
+
+  const authors = [{ name: 'Jane Doe' }, { name: 'John Doe' }];
+</script>
+
+<Analytics {authors} />
+```
+
+## Environments
+
+Generally, you only want to send page analytics in production environments.
+
+In a SvelteKit context, you can use `$app` stores to restrict when you send analytics.
+
+For example, the following excludes analytics from pages in development or hosted on our preview server:
+
+```svelte
+<script>
+  import { Analytics } from '@reuters-graphics/graphics-components';
+  import { dev } from '$app/environment';
+  import { page } from '$app/stores';
+</script>
+
+{#if !dev && $page.url?.hostname !== 'graphics.thomsonreuters.com'}
+  <Analytics />
+{/if}
+```
+
+## Multipage apps
+
+If you're using analytics to measure a multipage newsapp that uses [client-side routing](https://kit.svelte.dev/docs/glossary#routing), then you may need to trigger analytics after virtual page navigation.
+
+This component exports a function you can call to register pageviews.
+
+For example, here's how you can use SvelteKit's [`afterNavigate`](https://kit.svelte.dev/docs/modules#$app-navigation-afternavigate) lifecycle to capture additional pageviews:
+
+```svelte
+<script>
+  import {
+    Analytics,
+    registerPageview,
+  } from '@reuters-graphics/graphics-components';
+  import { afterNavigate } from '$app/navigation';
+
+  let isFirstPageview = true;
+
+  afterNavigate(() => {
+    // We shouldn't fire on initial page load because the Analytics component
+    // already registers a reader's first pageview. After this component
+    // has initially mounted, we can be sure that further navigation is virtual
+    // and register pageviews using this function.
+    if (!isFirstPageview) {
+      registerPageview();
+    } else {
+      isFirstPageview = false;
+    }
+  });
+</script>
+
+<Analytics />
+```

package/dist/components/Analytics/Analytics.stories.svelte

@@ -1,37 +1,17 @@
-<script context="module">import Analytics from "./Analytics.svelte";
-import componentDocs from "./stories/docs/component.md?raw";
-import environmentsDocs from "./stories/docs/environments.md?raw";
-import multipageDocs from "./stories/docs/multipage.md?raw";
-import { withComponentDocs, withStoryDocs } from "$docs/utils/withParams.js";
-export const meta = {
-  title: "Components/Ads & analytics/Analytics",
-  component: Analytics,
-  ...withComponentDocs(componentDocs)
-};
-</script>
+<script module lang="ts">
+  import { defineMeta } from '@storybook/addon-svelte-csf';
+  import Analytics from './Analytics.svelte';
 
-<script>
-  import { Template, Story } from '@storybook/addon-svelte-csf';
+  const { Story } = defineMeta({
+    title: 'Components/Ads & analytics/Analytics',
+    component: Analytics,
+  });
 </script>
 
-<Template let:args>
-  <Analytics {...args} />
-  <div>Nothing to see here</div>
-</Template>
-
 <Story
-  name="Default"
-  args="{{
+  name="Demo"
+  tags={['!autodocs', '!dev']}
+  args={{
     authors: [{ name: 'Jane Doe' }, { name: 'John Doe' }],
-  }}"
+  }}
 />
-
-<Story name="Environments" {...withStoryDocs(environmentsDocs)}>
-  <Analytics />
-  <div>Nothing to see here</div>
-</Story>
-
-<Story name="Multipage apps" {...withStoryDocs(multipageDocs)}>
-  <Analytics />
-  <div>Nothing to see here</div>
-</Story>

package/dist/components/Analytics/Analytics.stories.svelte.d.ts

@@ -1,23 +1,19 @@
-import { SvelteComponent } from "svelte";
-export declare const meta: {
-    parameters: {
-        docs: any;
+import Analytics from './Analytics.svelte';
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
     };
-    title: string;
-    component: typeof Analytics;
-};
-declare const __propDef: {
-    props: Record<string, never>;
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {};
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type AnalyticsProps = typeof __propDef.props;
-export type AnalyticsEvents = typeof __propDef.events;
-export type AnalyticsSlots = typeof __propDef.slots;
-export default class Analytics extends SvelteComponent<AnalyticsProps, AnalyticsEvents, AnalyticsSlots> {
+    z_$$bindings?: Bindings;
 }
-export {};
+declare const Analytics: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type Analytics = InstanceType<typeof Analytics>;
+export default Analytics;

package/dist/components/Analytics/Analytics.svelte

@@ -1,23 +1,39 @@
-<script context="module">
+<!-- @component `Analytics` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-ads-analytics-analytics--docs) -->
+
+<script module>
   import { registerPageview as registerChartbeatPageview } from './providers/chartbeat';
   import { registerPageview as registerGAPageview } from './providers/ga';
   import { registerPageview as registerParselyPageview } from './providers/parsely';
 
   /** Register virtual pageviews when using client-side routing in multipage applications. */
-  export function registerPageview() {
+  function registerPageview() {
     registerChartbeatPageview();
     registerGAPageview();
     registerParselyPageview();
   }
+
+  export { registerPageview };
 </script>
 
-<!-- @component `Analytics` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-ads-analytics-analytics--docs) -->
-<script>export let authors = [];
-import { onMount } from "svelte";
-import { ga, chartbeat, parsely } from "./providers";
-onMount(() => {
-  ga();
-  chartbeat(authors);
-  parsely();
-});
+<script lang="ts">
+  interface Author {
+    name: string;
+  }
+
+  import { onMount } from 'svelte';
+  import { ga, chartbeat, parsely } from './providers';
+  interface Props {
+    /**
+     * Used to associate a page with its author(s) in Chartbeat.
+     */
+    authors?: Author[];
+  }
+
+  let { authors = [] }: Props = $props();
+
+  onMount(() => {
+    ga();
+    chartbeat(authors);
+    parsely();
+  });
 </script>

package/dist/components/Analytics/Analytics.svelte.d.ts

@@ -1,25 +1,16 @@
-import { SvelteComponent } from "svelte";
 /** Register virtual pageviews when using client-side routing in multipage applications. */
-export declare function registerPageview(): void;
-declare const __propDef: {
-    props: {
-        /**
-           * Used to associate a page with its author(s) in Chartbeat.
-           */ authors?: {
-            name: string;
-        }[];
-    };
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {};
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type AnalyticsProps = typeof __propDef.props;
-export type AnalyticsEvents = typeof __propDef.events;
-export type AnalyticsSlots = typeof __propDef.slots;
-/** `Analytics` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-ads-analytics-analytics--docs) */
-export default class Analytics extends SvelteComponent<AnalyticsProps, AnalyticsEvents, AnalyticsSlots> {
+declare function registerPageview(): void;
+export { registerPageview };
+interface Author {
+    name: string;
+}
+interface Props {
+    /**
+     * Used to associate a page with its author(s) in Chartbeat.
+     */
+    authors?: Author[];
 }
-export {};
+/** `Analytics` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-ads-analytics-analytics--docs) */
+declare const Analytics: import("svelte").Component<Props, {}, "">;
+type Analytics = ReturnType<typeof Analytics>;
+export default Analytics;

package/dist/components/Article/Article.mdx

@@ -0,0 +1,117 @@
+import { Meta, Canvas } from '@storybook/blocks';
+
+import * as ArticleStories from './Article.stories.svelte';
+
+<Meta of={ArticleStories} />
+
+# Article
+
+The `Article` component contains all the contents of our story.
+
+> 📌 In most cases, **you don't need to mess with the `Article` component** because it's already set up in the graphics kit.
+
+```svelte
+<script>
+  import { Article } from '@reuters-graphics/graphics-components';
+</script>
+
+<Article>
+  <!-- The story content goes here! -->
+</Article>
+```
+
+<Canvas of={ArticleStories.Demo} />
+
+## Custom column widths
+
+The `Article` component also establishes the widths of columns that contain individual sections of the story, such as text, photos, and charts. The default column widths follow a basic class scheme:
+
+- `narrower` The narrowest...
+- `narrow` A bit narrower than the default body text column
+- `normal` **The default width of the body text column**
+- `wide` A bit wider
+- `wider` A bit wider than wide...
+- `widest` Edge-to-edge, but _excluding_ the left and right padding on `Article`
+- `fluid` Fully edge-to-edge
+
+You can set custom column widths by passing an object to the `columnWidths` prop with pixel values for the `narrower`, `narrow`, `normal`, `wide` and `wider` classes. These can then be used by the `Block` component or other elements housed inside `<Article>`.
+
+> **For most graphics kit pages, you shouldn't customise the column widths.** Other Reuters tools, like our AI templates, use our default column widths, so customising those widths here has downstream consequences for graphics made outside graphics kit. The main exception is SREP stories.
+
+```svelte
+<!-- Set custom column widths -->
+<Article
+  columnWidths={{
+    narrower: 310,
+    narrow: 450,
+    normal: 550,
+    wide: 675,
+    wider: 1400,
+  }}
+>
+  <!-- Custom column widths get passed down to the `Block` component -->
+  <Block width="narrower" />
+  <Block width="narrow" />
+  <Block width="normal" />
+  <Block width="wide" />
+  <Block width="wider" />
+  <Block width="widest" />
+  <Block width="fluid" />
+</Article>
+```
+
+If you're not using our `Block` component, you can still inherit the column widths from `Article` and create your own custom containers by using [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) like this:
+
+```svelte
+<div class="my-special-container">
+  <!-- Story content -->
+</div>
+
+<style lang="scss">
+  div.my-special-container {
+    max-width: var(--wide-column-width);
+  }
+</style>
+```
+
+... or you can make your column widths entirely configurable by adding classes and manually specifying widths:
+
+```svelte
+<script>
+  let { width = 'normal' } = $props();
+</script>
+
+<div class="my-special-container {width}">
+  <!-- Story content -->
+</div>
+
+<style lang="scss">
+  div.my-special-container {
+    max-width: var(--normal-column-width);
+    &.narrower {
+      max-width: var(--narrower-column-width);
+    }
+    &.narrow {
+      max-width: var(--narrow-column-width);
+    }
+    &.wide {
+      max-width: var(--wide-column-width);
+    }
+    &.wider {
+      max-width: var(--wider-column-width);
+    }
+    &.widest {
+      max-width: 100%;
+    }
+    &.fluid {
+      width: calc(100% + 30px);
+      margin-left: -15px;
+      max-width: none;
+    }
+  }
+</style>
+```
+
+Here's an example of how <span className='custom'>custom</span> `columnWidths` can be used to change column widths:
+
+<Canvas of={ArticleStories.CustomColumns} />

package/dist/components/Article/Article.stories.svelte

@@ -1,38 +1,26 @@
-<script context="module">import Article from "./Article.svelte";
-import componentDocs from "./stories/docs/component.md?raw";
-import customWellWidthsDocs from "./stories/docs/customWellWidths.md?raw";
-import { withComponentDocs, withStoryDocs } from "$docs/utils/withParams.js";
-export const meta = {
-  title: "Components/Page Layout/Article",
-  component: Article,
-  ...withComponentDocs(componentDocs)
-};
-</script>
+<script module lang="ts">
+  import { defineMeta } from '@storybook/addon-svelte-csf';
+  import Block from '../Block/Block.svelte';
+  import Article from './Article.svelte';
 
-<script>import { Template, Story } from "@storybook/addon-svelte-csf";
-import Block from "../Block/Block.svelte";
+  const { Story } = defineMeta({
+    title: 'Components/Page layout/Article',
+    component: Article,
+  });
 </script>
 
-<Template let:args>
-  <Article {...args} />
-</Template>
-
-<Story
-  name="Default"
-  args="{{
-    embedded: false,
-    id: '',
-  }}"
->
+<Story name="Demo">
   <Article id="article-story-basic">
     <div class="demo-container">
-      <div class="background-label">Article container</div>
+      <div class="background-label">Article well</div>
       <div class="padding-label"><span>⇤</span>15px padding</div>
     </div>
   </Article>
 </Story>
 
-<Story name="Custom columns" {...withStoryDocs(customWellWidthsDocs)}>
+<Story name="Custom columns" exportName="CustomColumns">
+  <h3>Default column widths</h3>
+
   <Article id="article-column-widths-demo">
     <div class="article-boundaries">
       <Block id="section-demo" width="narrower">narrower</Block>
@@ -44,29 +32,39 @@ import Block from "../Block/Block.svelte";
       <Block id="section-demo" width="fluid">fluid</Block>
     </div>
   </Article>
+  <h3>Custom column widths</h3>
   <Article
     id="article-column-widths-demo"
-    columnWidths="{{
-      narrower: 310,
-      narrow: 450,
-      normal: 550,
+    columnWidths={{
+      narrower: 250,
+      narrow: 400,
+      normal: 500,
       wide: 675,
       wider: 1400,
-    }}"
+    }}
   >
     <div class="article-boundaries custom">
-      <Block id="section-demo" width="narrower">narrower*</Block>
-      <Block id="section-demo" width="narrow">narrow*</Block>
-      <Block id="section-demo">normal*</Block>
-      <Block id="section-demo" width="wide">wide*</Block>
-      <Block id="section-demo" width="wider">wider*</Block>
+      <Block id="section-demo" width="narrower">narrower</Block>
+      <Block id="section-demo" width="narrow">narrow</Block>
+      <Block id="section-demo">normal</Block>
+      <Block id="section-demo" width="wide">wide</Block>
+      <Block id="section-demo" width="wider">wider</Block>
       <Block id="section-demo" width="widest">widest</Block>
       <Block id="section-demo" width="fluid">fluid</Block>
     </div>
   </Article>
 </Story>
 
-<style>:global(#article-story-basic, #article-column-widths-demo) {
+<style>h3 {
+  text-align: center;
+}
+
+:global(span.custom) {
+  color: rgb(211, 132, 123);
+  font-weight: 600;
+}
+
+:global(#article-story-basic, #article-column-widths-demo) {
   width: calc(100% + 30px);
   margin-left: -15px;
 }
@@ -95,22 +93,23 @@ import Block from "../Block/Block.svelte";
   height: 50px;
   padding-left: 3px;
   color: white;
-  font-size: 12px;
+  font-size: 1rem;
 }
 
 div.demo-container {
   height: 300px;
   background: #ccc;
   position: relative;
-  font-size: 12px;
 }
 div.demo-container .background-label {
+  font-size: 1.5rem;
   position: absolute;
-  bottom: 0;
-  left: 5px;
+  top: 40%;
+  left: 40%;
   color: #666;
 }
 div.demo-container .padding-label {
+  font-size: 1rem;
   position: absolute;
   top: 0;
   left: -17px;

package/dist/components/Article/Article.stories.svelte.d.ts

@@ -1,23 +1,19 @@
-import { SvelteComponent } from "svelte";
-export declare const meta: {
-    parameters: {
-        docs: any;
+import Article from './Article.svelte';
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
     };
-    title: string;
-    component: typeof Article;
-};
-declare const __propDef: {
-    props: Record<string, never>;
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {};
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type ArticleProps = typeof __propDef.props;
-export type ArticleEvents = typeof __propDef.events;
-export type ArticleSlots = typeof __propDef.slots;
-export default class Article extends SvelteComponent<ArticleProps, ArticleEvents, ArticleSlots> {
+    z_$$bindings?: Bindings;
 }
-export {};
+declare const Article: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type Article = InstanceType<typeof Article>;
+export default Article;

package/dist/components/Article/Article.svelte

@@ -1,28 +1,58 @@
 <!-- @component `Article` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-page-layout-article--docs) -->
-<script>export let embedded = false;
-export let id = null;
-export let role = null;
-export let columnWidths = {
-  narrower: 330,
-  narrow: 510,
-  normal: 660,
-  wide: 930,
-  wider: 1200
-};
-import cssVariables from "../../actions/cssVariables/index.js";
-$: columnWidthVars = {
-  "narrower-column-width": columnWidths.narrower + "px",
-  "narrow-column-width": columnWidths.narrow + "px",
-  "normal-column-width": columnWidths.normal + "px",
-  "wide-column-width": columnWidths.wide + "px",
-  "wider-column-width": columnWidths.wider + "px"
-};
+<script lang="ts">
+  interface ColumnWidths {
+    /** Narrower column width */
+    narrower: number;
+    /** Narrow column width */
+    narrow: number;
+    /** Normal column width */
+    normal: number;
+    /** Wide column width */
+    wide: number;
+    /** Wider column width */
+    wider: number;
+  }
+
+  import cssVariables from '../../actions/cssVariables/index';
+  interface Props {
+    /** Set to true for embeddables. */
+    embedded?: boolean;
+    /** Add an id to the article tag to target it with custom CSS. */
+    id?: string;
+    /** ARIA role of the article */
+    role?: string | null;
+    /** Set custom widths for the normal, wide and wider column dimensions */
+    columnWidths?: ColumnWidths;
+    children?: import('svelte').Snippet;
+  }
+
+  let {
+    embedded = false,
+    id = '',
+    role = null,
+    columnWidths = {
+      narrower: 330,
+      narrow: 510,
+      normal: 660,
+      wide: 930,
+      wider: 1200,
+    },
+    children,
+  }: Props = $props();
+
+  let columnWidthVars = $derived({
+    'narrower-column-width': columnWidths.narrower + 'px',
+    'narrow-column-width': columnWidths.narrow + 'px',
+    'normal-column-width': columnWidths.normal + 'px',
+    'wide-column-width': columnWidths.wide + 'px',
+    'wider-column-width': columnWidths.wider + 'px',
+  });
 </script>
 
 <main id="main-content">
-  <article {id} class:embedded {role} use:cssVariables="{columnWidthVars}">
+  <article {id} class:embedded {role} use:cssVariables={columnWidthVars}>
     <!-- Article content -->
-    <slot />
+    {@render children?.()}
   </article>
 </main>