@reuters-graphics/graphics-components 1.0.29 → 1.1.0

package/dist/docs/contributing/component-guidelines.mdx

@@ -0,0 +1,170 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../utils/docsPage.js';
+
+<Meta
+  title="Contributing/Component guidelines"
+  parameters={{ ...parameters }}
+/>
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Component guidelines
+
+## Dependencies
+
+Components should be written for any Svelte context. If your component needs, for example, values from SvelteKit stores, these should be passed in as props.
+
+## Typescript
+
+By default, component's are written in TypeScript, which adds robust type-checking and helpful hints for people using your component in editors like Visual Studio Code.
+
+> If you've never used TypeScript, you can check out the [5-minute intro](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html). If you're still uneasy writing TypeScript, don't sweat it! Just write your component in plain JavaScript/Svelte. We'll convert at least your component's props to TypeScript as part of the PR review.
+
+### Typing and documenting component props
+
+Document props using [JSDoc comments](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html) (be sure to mark required props) and type props with TypeScript.
+
+Here are a few examples:
+
+#### Typing simple props
+
+```svelte
+<script lang="ts">
+  /** Height of the component */
+  export let height: number = 250;
+  /** Text colour */
+  export let colour: string = 'blue';
+</script>
+```
+
+#### Documenting required props
+
+```svelte
+<script lang="ts">
+  /**
+   * Image source
+   * @required
+   */
+  export let src: string;
+  /**
+   * AltText for the image
+   * @required
+   */
+  export let altText: string;
+</script>
+```
+
+#### Custom types for props
+
+```svelte
+<script lang="ts">
+  type ContainerWidth = 'normal' | 'wide' | 'wider' | 'widest' | 'fluid';
+
+  /** Width of the component within the text well. */
+  export let width: ContainerWidth = 'normal';
+
+  interface Person {
+    name: string;
+    age: number;
+  }
+
+  /**
+   * Array of people
+   * @required
+   */
+  export let people: Person[];
+</script>
+```
+
+#### Future syntax
+
+Using some future syntax like [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) in your components currently breaks the automatic discovery of JSDoc comments in your component, which are used to fill in the [ArgsTable](https://storybook.js.org/docs/react/writing-docs/doc-block-argstable).
+
+So instead of...
+
+```javascript
+const prop = myObject?.myOptionalProp;
+```
+
+...unfortunately, use something old-fashioned like...
+
+```javascript
+const prop = myObject.myOptionalProp ? myObject.myOptionalProp : null;
+```
+
+If your component docs still aren't working, check if you're using other future-JS sytax, for now.
+
+## Styles
+
+### Theming
+
+Always respect styles set by the [`Theme`](/?path=/docs/theming-theme--default) component by using [CSS variables](?path=/docs/scss-css-variables--page) where they apply to your component.
+
+Always set [fallback values](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties#custom_property_fallback_values) for the default light theme.
+
+### SCSS
+
+Use SCSS with the `lang` attribute to write your styles.
+
+```svelte
+<button>My component</button>
+
+<style lang="scss">
+  button {
+    color: blue;
+  }
+</style>
+```
+
+### Scope
+
+Styles should **always** be scoped to your components.
+
+```svelte
+<button>My component</button>
+
+<style lang="scss">
+  button {
+    color: blue;
+  }
+</style>
+```
+
+In rare cases, you can use the SCSS `:global` operator to style child elements in your component, but those rules should still be scoped below a parent element.
+
+```svelte
+<svg></svg>
+
+<style lang="scss">
+  svg {
+    :global(path) {
+      stroke: black;
+    }
+  }
+</style>
+```
+
+### CSS variables
+
+Use [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) and props to allow better theming of your components.
+
+```svelte
+<script>
+  export let textColour = '#333';
+</script>
+
+<div style="--textColour: {textColour};">
+  <h3>My title</h3>
+  <p>My text.</p>
+  <p></p>
+</div>
+
+<style lang="scss">
+  div {
+    h3,
+    p {
+      color: var(--textColour, #333);
+    }
+  }
+</style>
+```

package/dist/docs/contributing/quickstart.mdx

@@ -0,0 +1,48 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../utils/docsPage.js';
+
+<Meta title="Contributing/Quickstart" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Contributing
+
+Reuters Graphics team members can contribute new components, and we welcome pull requests for any of our existing components from the community.
+
+Components are documented (and tested) using [Storybook](https://storybook.js.org).
+
+## Adding a new chart component
+
+### Prereqs
+
+Before you start, it's probably a good idea to read up a bit on [Storybook](https://storybook.js.org/docs/svelte/get-started/introduction), the framework used to document components.
+
+### Quickstart
+
+Make a new git branch for your new component, like...
+
+```
+git checkout -b my-component
+```
+
+This library includes a basic template for creating and documenting your component with Storybook you can use to get started.
+
+Just run...
+
+```
+yarn new
+```
+
+... which will create a new directory for your component and copy over an example Svelte component and story page.
+
+To start developing your component, start the dev server with...
+
+```
+yarn start
+```
+
+When you're ready to share your chart, commit your branch to GitHub, make a PR and we'll get it published!
+
+```
+git push origin my-chart
+```

package/dist/docs/contributing/story-recipes/basic-story.mdx

@@ -0,0 +1,79 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../../utils/docsPage.js';
+
+<Meta
+  title="Contributing/Recipes: Basic story"
+  parameters={{ ...parameters }}
+/>
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Recipes: Basic story
+
+To make a basic story, you'll need to setup a few things from storybook's Svelte [Component Story Framework (CSF)](https://storybook.js.org/docs/svelte/api/csf) library.
+
+Once you've setup the `Meta` and `Template` components as below, you can write a `Story` component with an `args` prop. In that `args` prop you can pass values that will be used to fill in your component's props.
+
+```svelte
+<!-- YourComponent.stories.svelte -->
+<script>
+  import { Meta, Template, Story } from '@storybook/addon-svelte-csf';
+
+  import YourComponent from './YourComponent.svelte';
+</script>
+
+<Meta title="Components/YourComponent" component="{YourComponent}" />
+
+<Template let:args>
+  <YourComponent {...args} />
+</Template>
+
+<Story
+  name="Default"
+  args="{{
+    width: 'normal',
+  }}"
+/>
+```
+
+For example, the `width` property in the `Story` args above would be passed to your component as though you'd written it like this:
+
+```svelte
+<YourComponent width="normal" />
+```
+
+You can define additional stories with _different_ args to show how your component will render with different props like:
+
+```svelte
+<!-- ... -->
+
+<Story
+  name="Default"
+  args="{{
+    width: 'normal',
+  }}"
+/>
+
+<Story
+  name="Extra wide"
+  args="{{
+    width: 'wider',
+  }}"
+/>
+```
+
+If you want even more control, you can skip the `args` and pass your component directly into the `Story` with whatever props you need:
+
+```svelte
+<Story name="Super custom">
+  <YourComponent
+    width="fluid"
+    data="{[
+      { id: 'UK', value: 65 },
+      { id: 'USA', value: 265 },
+    ]}"
+  />
+</Story>
+```
+
+> **Pro tip:** If you pass your component in directly, your users won't be able to control its props using Storybook's built-in [controls panel](https://storybook.js.org/docs/svelte/essentials/controls), so it's always best to start with a default example using `args`.

package/dist/docs/contributing/story-recipes/story-with-custom-controls.mdx

@@ -0,0 +1,48 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../../utils/docsPage.js';
+
+<Meta
+  title="Contributing/Recipes: Story with custom controls"
+  parameters={{ ...parameters }}
+/>
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Recipes: Story with custom controls
+
+You can customise the controls in Storybook's built-in [controls panel](https://storybook.js.org/docs/svelte/essentials/controls) by passing [argTypes](https://storybook.js.org/docs/svelte/api/argtypes) to `Meta` like this:
+
+```svelte
+<!-- YourComponent.stories.svelte -->
+<script>
+  import { Meta, Template, Story } from '@storybook/addon-svelte-csf';
+
+  import YourComponent from './YourComponent.svelte';
+
+  const meta = {
+    argTypes: {
+      // A colour picker for the component's "colour" prop
+      colour: { control: 'color' },
+      // A range picker for the "height" prop
+      height: { control: { type: 'range', min: 5, max: 100, step: 5 } },
+      // A custom dropdown for the "width" prop
+      width: {
+        control: 'select',
+        options: ['normal', 'wide', 'wider', 'widest', 'fluid'],
+      },
+      // Turn off control for the "data" prop
+      data: { control: false },
+    },
+  };
+</script>
+
+<Meta title="Components/YourComponent" component="{YourComponent}" {...meta} />
+
+<template let:args>
+  <YourComponent {...args} />
+</template>
+
+<Story name="Default" />
+```
+
+Read more about Storybook's custom controls options [here](https://storybook.js.org/docs/svelte/essentials/controls).

package/dist/docs/contributing/story-recipes/story-with-custom-docs.mdx

@@ -0,0 +1,132 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../../utils/docsPage.js';
+
+import SourceCodeImg from './source-code.png';
+
+import '../../docStyles.scss';
+
+<Meta
+  title="Contributing/Recipes: Story with custom docs"
+  parameters={{ ...parameters }}
+/>
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Recipes: Story with custom docs
+
+You can add custom markdown to your story page by importing and using markdown files.
+
+First, create a markdown file in a `stories` directory in your component folder like this:
+
+```
+YourComponent/
+  YourComponent.svelte
+  YourComponent.stories.svelte
+  stories/
+    docs/
+      component.md
+      someStory.md
+```
+
+Now, import your markdown file in your story page component and attach it to either the `Meta` (for the top docs that introduce your component) or any individual `Story` using one of our handy docs utils.
+
+```svelte
+<!-- YourComponent.stories.svelte -->
+<script>
+  import { Meta, Template, Story } from '@storybook/addon-svelte-csf';
+
+  import YourComponent from './YourComponent.svelte';
+
+  // Import markdown files.
+  // Note: the "?raw" in the imports below is important!!
+  import componentDocs from './stories/docs/component.md?raw';
+  import someStoryDocs from './stories/docs/someStory.md?raw';
+
+  import { withComponentDocs, withStoryDocs } from '$docs/utils/withParams';
+
+  const meta = {
+    ...withComponentDocs(componentDocs),
+  };
+</script>
+
+<Meta title="Components/YourComponent" component="{YourComponent}" {...meta} />
+
+<template let:args>
+  <YourComponent {...args} />
+</template>
+
+<!-- The first story will use the component docs in Meta... -->
+<Story name="Basic" args="{{ width: 'normal' }}" />
+
+<!-- Additional stories can use other docs now. -->
+<Story
+  name="Another story"
+  args="{{ width: 'normal' }}"
+  {...withStoryDocs(someStoryDocs)}
+/>
+```
+
+## Customising copyable source code
+
+If you need to, you can customise the "Copy" source code available below a component story's iframe window.
+
+<img className="feature" src={SourceCodeImg} width="80%" />
+
+First, add a snippet file in a `stories` directory in your component folder like this:
+
+```
+YourComponent/
+  YourComponent.svelte
+  YourComponent.stories.svelte
+  stories/
+    snippets/
+      default.svelte
+```
+
+Now, import your snippet file in your story page component and attach it to any individual `Story` using our docs utils.
+
+```svelte
+<script>
+  import { Meta, Template, Story } from '@storybook/addon-svelte-csf';
+
+  import YourComponent from './YourComponent.svelte';
+
+  // Import snippet file.
+  // Note: the "?raw" in the import below is important!!
+  import defaultSource from './stories/snippets/default.svelte?raw';
+
+  import { withSource } from '$docs/utils/withParams';
+
+  const meta = {
+    title: 'Components/YourComponent',
+    component: YourComponent,
+  };
+</script>
+
+<meta {...meta} />
+
+<template let:args>
+  <YourComponent {...args} />
+</template>
+
+<!-- Pass source in inside an object keyed by your snippet's language, e.g., svelte, scss, etc. -->
+<Story
+  name="Basic"
+  args="{{ width: 'normal' }}"
+  {...withSource({ svelte: defaultSnippet })}
+/>
+```
+
+> **Pro tip:** If you pass your source code in directly, the code won't change prop values when users play with Storybook's built-in [controls panel](https://storybook.js.org/docs/svelte/essentials/controls), so it's best to start with a default example using the generated source code.
+
+If you're adding source code AND custom docs to a story, you can chain `withSource` and `withComponentDocs` like this:
+
+```svelte
+<!-- ... -->
+
+<Story
+  name="Extra wide"
+  args="{{ width: 'wider' }}"
+  {...withComponentDocs(componentDocs, withSource({ svelte: defaultSnippet }))}
+/>
+```

package/dist/docs/contributing/story-recipes/story-with-media.mdx

@@ -0,0 +1,52 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../../utils/docsPage.js';
+
+<Meta
+  title="Contributing/Recipes: Story with media"
+  parameters={{ ...parameters }}
+/>
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Recipes: Story with media
+
+To use media files in your stories, import them directly.
+
+First, add a media file in a `stories` directory in your component folder like this:
+
+```
+YourComponent/
+  YourComponent.svelte
+  YourComponent.stories.svelte
+  stories/
+    imgs/
+      myImage.jpg
+```
+
+Now, import your media file directly in your code, which will resolve to the URL of the file.
+
+```svelte
+<!-- YourComponent.stories.svelte -->
+<script>
+  import { Meta, Template, Story } from '@storybook/addon-svelte-csf';
+
+  import YourComponent from './YourComponent.svelte';
+
+  // 🖼️ Import media you need in stories directly in code!
+  import myImageSrc from './stories/imgs/myImage.jpg';
+</script>
+
+<Meta title="Components/YourComponent" component="{YourComponent}" />
+
+<template let:args>
+  <YourComponent {...args} />
+</template>
+
+<Story
+  name="Basic"
+  args="{{
+    src: myImageSrc,
+    altText: 'My image in the component',
+  }}"
+/>
+```

package/dist/docs/contributing/writing-component-stories.mdx

@@ -0,0 +1,34 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../utils/docsPage.js';
+
+<Meta title="Contributing/Writing stories" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Writing component stories
+
+As well as writing your component, you should also document how to use it using Storybook "stories."
+
+## What's a story?
+
+Paraphrasing [Storybook's definition](https://storybook.js.org/docs/svelte/writing-stories/introduction): A story captures the rendered state of a Svelte component, given certain props. Translation: It's a demo of what your component can do.
+
+In Storybook, you create a story page for your component, which can itself contain several "stories" or demos of how your component works.
+
+To make a story page, you'll create a `*.stories.svelte` file next to your component like this:
+
+```
+src/
+  components/
+    YourComponent/
+      YourComponent.svelte
+      YourComponent.stories.svelte
+```
+
+Your component's story page will then have at least one story that shows how it can be used.
+
+## How do I write stories?
+
+Read through the recipes docs for some common examples of how you may want to write and customise your stories.
+
+If you're comparing the recipes to Storybook's own docs, note that all the examples use "Svelte Native" story format. (Storybook is technically a React-first tool that's been retrofit to also support a number of other frameworks, including Svelte.)

package/dist/docs/contributing/writing-docs-stories.mdx

@@ -0,0 +1,39 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../utils/docsPage.js';
+
+<Meta title="Contributing/Writing docs pages" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Writing docs-only pages
+
+You can write docs-only pages in simple markdown using MDX format.
+
+> MDX is _technically_ a mixture of markdown and React. Unforuntately, there isn't a native Svelte option for markdown pages in Storybook yet. Good news, though, you won't _really_ need to know React to use it. Just write in markdown and follow the template below for the React bits you'll need.
+
+### Quickstart
+
+Make a new `.stories.mdx` file for your docs page in the `src/docs/` directory.
+
+```
+src/
+  docs/
+    my-docs.stories.mdx
+```
+
+Add the following at the top of the file and customise the `title` property in the `Meta` component for where you want the page to live in the Storybook nav.
+
+```markdown
+import { Meta } from '@storybook/addon-docs';
+import { parameters } from '$docs/utils/docsPage.js';
+
+<Meta title="SCSS/Special rules" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# My docs page
+
+Your docs TK...
+```
+
+From there, write whatever you need in markdown.

package/dist/docs/docStyles.scss

@@ -0,0 +1,11 @@
+img.feature {
+  max-width: 100%;
+  margin: 0 auto;
+  display: block;
+}
+
+#custom-table {
+  [data-field='Net worth (in billions)'] {
+    text-align: right;
+  }
+}

package/dist/docs/docs-components/CopyColourTable/ImportSnippet.d.ts

@@ -0,0 +1,6 @@
+export default ImportSnippet;
+declare function ImportSnippet({ included, partial }: {
+    included?: boolean | undefined;
+    partial?: string | undefined;
+}): React.JSX.Element;
+import React from 'react';

package/dist/docs/docs-components/CopyColourTable/ImportSnippet.jsx

@@ -0,0 +1,54 @@
+import React, { useEffect, useState } from 'react';
+
+import SyntaxHighlighter from 'react-syntax-highlighter/dist/esm/prism-light';
+// @ts-ignore scss
+import classes from './styles.module.scss';
+import prism from 'react-syntax-highlighter/dist/esm/styles/prism/prism';
+import scss from 'react-syntax-highlighter/dist/esm/languages/prism/scss';
+
+SyntaxHighlighter.registerLanguage('scss', scss);
+
+const formatPartial = (partial) => {
+  return partial.replace(/\/_/, '/').replace(/\.scss$/, '');
+};
+
+const Copyable = (props) => {
+  const [copied, setCopied] = useState(false);
+
+  let timeout;
+
+  useEffect(() => {
+    if (timeout) clearTimeout(timeout);
+    timeout = setTimeout(() => {
+      setCopied(false);
+    }, 1500);
+  }, [copied]);
+
+  const handleClick = async ({ partial }) => {
+    const copyText = `@import "@reuters-graphics/graphics-components/scss/colours/${formatPartial(partial)}";`;
+    await navigator.clipboard.writeText(copyText);
+    setCopied(true);
+  };
+
+  return (
+    <button className="copy-btn" onClick={() => handleClick(props)}>
+      <span className="material-symbols-outlined">content_copy</span>
+      {copied && <span className="copy-tag">Copied</span>}
+    </button>
+  );
+};
+
+const ImportSnippet = ({ included = false, partial = 'thematic/_tr.scss' }) => {
+  return included ?
+      <div className={classes.importsnippet}>
+        <p>Included</p>
+      </div>
+    : <div className={classes.importsnippet}>
+        <SyntaxHighlighter language="scss" style={prism}>
+          {`// global.scss \n@import "@reuters-graphics/graphics-components/scss/colours/${formatPartial(partial)}";`}
+        </SyntaxHighlighter>
+        <Copyable partial={partial} />
+      </div>;
+};
+
+export default ImportSnippet;