@reuters-graphics/graphics-components 1.0.29 → 1.1.0

package/dist/docs/guides/graphics-kit.mdx

@@ -0,0 +1,56 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../utils/docsPage.js';
+
+<Meta
+  title="Guides/Using with the Graphics Kit"
+  parameters={{ ...parameters }}
+/>
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Using with the Graphics Kit
+
+If you haven't, check out ["Using Reuters Graphics Components" in the Graphics Kit docs](https://reuters-graphics.github.io/docs_graphics-kit/for_developers/graphics-components/) to get a general idea of how to use components.
+
+## Quickit
+
+Look <span className="highlight">for <strong>🚀 QUICKIT</strong> stories</span> (Quick Kit 🤣🙄) for some of our most commonly used components. These stories
+include easy copy/paste snippets as well as Google Doc block examples that should
+shortcut getting a component working in the Graphics Kit.
+
+(Want a QUICKIT story for another component? [Just ask us!](https://github.com/reuters-graphics/graphics-components/issues/new?labels=%F0%9F%93%9A%20documentation&assignees=hobbes7878))
+
+## FAQs
+
+### How do I write my Google Doc?
+
+Many component stories show passing data directly into component props. In the Kit, though, you likely won't be hard-coding things like text strings in your code and instead will get them from a Google Doc.
+
+Check out the guide devoted to [using components with Google Docs](?path=/docs/guides-using-with-google-docs--page) for a quick explanation of how to work with Google Docs.
+
+And, of course, look for a QUICKIT story for your component, which will have a Docs example specific to it.
+
+### How do I use this image/video/etc.?
+
+Remember, all references to images, videos and other media must be _absolute paths_:
+
+✅ `https://.../myImage.jpg`
+
+❌ `./myImage.jpg`
+
+In most cases, that means you'll need to prefix relative paths with the special `assets` Svelte module. Many examples in these docs show how to do it. But it's also easy enough to demo again here!
+
+```svelte
+<script>
+  import { FeaturePhoto } from '@reuters-graphics/graphics-components';
+
+  // This is already imported for you in App.svelte
+  import { assets } from '$app/paths';
+</script>
+
+<FeautrePhoto src="{`${assets}/imgs/myImage.jpg`}" />
+```
+
+### How do I change this component's styles?
+
+Check out our guide on [customising components with SCSS](?path=/docs/guides-customising-components-with-scss--page)

package/dist/docs/guides/using-docs.mdx

@@ -0,0 +1,58 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../utils/docsPage.js';
+
+import storiesImg from './imgs/stories.png';
+import introImg from './imgs/intro.png';
+import argsImg from './imgs/argstable.png';
+import frameImg from './imgs/frame.png';
+import copyImg from './imgs/copy-code.png';
+import moreStoriesImg from './imgs/more-stories.png';
+
+<Meta title="Guides/Using these docs" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Using these docs
+
+The docs in this site include interactive examples of how to use our components, explanations of how our basic design system works and helpful docs on SCSS tools you can use to customise your page.
+
+## How component docs are organised
+
+Component docs are written using a framework called [Storybook](https://storybook.js.org/docs/svelte/get-started/introduction), which creates a page for each component. You can find those pages in left-hand nav on the site.
+
+Each component has a Docs page and one or more "stories" or demos that show how the component works:
+
+<img
+  src={storiesImg}
+  style={{ maxWidth: '300px', width: '100%', margin: '0 0 2rem' }}
+/>
+
+### Parts of a component page
+
+Each component page starts with an intro that includes a little documentation and a code snippet. The intro always shows the simplest way to import and use a component.
+
+<img src={introImg} width="650" style={{ margin: '0 0 2rem' }} />
+
+Next is a **frame** that shows how the component looks. Each story will have its own frame.
+
+<img src={frameImg} width="650" style={{ margin: '0 0 2rem' }} />
+
+Below the story frame is an **args table**. <span className="highlight bold">This is the most important part of every component&rsquo;s page.</span> The args table documents all the [props](https://learn.svelte.dev/tutorial/declaring-props) and [slots](https://learn.svelte.dev/tutorial/slots) a component has, i.e., all the ways you can customise it.
+
+<img src={argsImg} width="100%" style={{ margin: '0 0 2rem', maxWidth: 800 }} />
+
+Each prop includes its name and a description with the data type that prop expects as well as the default value, if there is one.
+
+The `Control` column in the table gives you a way to play with the value of that prop in the live demo. Make changes here, and for most components, they'll update the demo frame to reflect your changes.
+
+Click the "Show code" button in the frame to see how your component looks with the props you set.
+
+<img src={copyImg} width="100%" style={{ margin: '2rem 0', maxWidth: 800 }} />
+
+From there, more stories show other ways you might use a component, also with a snippet you can copy into your own page.
+
+<img
+  src={moreStoriesImg}
+  width="100%"
+  style={{ margin: '2rem 0', maxWidth: 800 }}
+/>

package/dist/docs/intro.mdx

@@ -0,0 +1,38 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from './utils/docsPage.js';
+
+<Meta title="Intro" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# @reuters-graphics/graphics-components
+
+<p>
+  <a href="https://www.npmjs.com/package/@reuters-graphics/graphics-components">
+    <img src="https://badge.fury.io/js/@reuters-graphics%2Fgraphics-components.svg" alt="npm version" style={{ display: 'inline-block', margin: '0 5px 0 0' }} />
+  </a>
+
+  <a href="https://github.com/reuters-graphics/graphics-components">
+    <img src="https://badgen.net/badge/icon/GitHub?icon=github&label" alt="GitHub" style={{ display: 'inline-block', margin: '0 5px 0 0' }} />
+  </a>
+</p>
+
+Svelte components, SCSS and more you can use in graphics projects.
+
+## Getting started
+
+1. Install
+
+```bash
+yarn add @reuters-graphics/graphics-components
+```
+
+2. Checkout the [guides](?path=/docs/guides-using-these-docs--page), if you haven't, or dive straight into the docs to start using components.
+
+```svelte
+<script>
+  import { BodyText } from '@reuters-graphics/graphics-components';
+</script>
+
+<BodyText text="{'Hello world!'}" />
+```

package/dist/docs/layout/intro.mdx

@@ -0,0 +1,29 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../utils/docsPage.js';
+
+import WellImg from './article-well.jpg';
+
+<Meta title="Layout/Intro" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Layout
+
+Layout components setup our default page structure.
+
+Generally, our page layout includes a central text well and a few preset block breakpoints, wider and narrower than the well.
+
+Here's how it works:
+
+<img
+  className="feature"
+  src={WellImg}
+  width="100%"
+  style={{ margin: '3rem 0' }}
+/>
+
+The [`Article`](?path=/docs/layout-article--default) component sets up the set dimensions of the well and the block breakpoints.
+
+The [`Block`](?path=/docs/layout-block--default) component is a wrapper for individual parts of a page that can be as wide as any of those breakpoints.
+
+The docs in this section explain how to use our layout components to build the basic structure of your page and also how to break out of our default layout if you need to do something different.

package/dist/docs/styles/colours/intro.mdx

@@ -0,0 +1,24 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../../utils/docsPage.js';
+
+<Meta title="Styles/Colours/Intro" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Working with colours
+
+Colour palettes are provided as [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) you can use in your own styles. Some are included by default, others can be imported in your global stylesheet and then used.
+
+```scss
+/* global.scss */
+@import '@reuters-graphics/graphics-components/scss/colours/primary/blue';
+
+p {
+  color: var(--grey-400); // Included by default
+}
+
+p.blue-bg {
+  color: white;
+  background-colour: var(--blue-600); // Imported palette
+}
+```

package/dist/docs/styles/colours/primary.mdx

@@ -0,0 +1,165 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../../utils/docsPage.js';
+import CopyColourTable from '../../docs-components/CopyColourTable/Table.jsx';
+import { extractCssColourVariables } from '../../utils/parseCss';
+import greyScheme from '../../../scss/colours/primary/_grey.scss?raw';
+import slateScheme from '../../../scss/colours/primary/_slate.scss?raw';
+import zincScheme from '../../../scss/colours/primary/_zinc.scss?raw';
+import neutralScheme from '../../../scss/colours/primary/_neutral.scss?raw';
+import stoneScheme from '../../../scss/colours/primary/_stone.scss?raw';
+import redScheme from '../../../scss/colours/primary/_red.scss?raw';
+import orangeScheme from '../../../scss/colours/primary/_orange.scss?raw';
+import amberScheme from '../../../scss/colours/primary/_amber.scss?raw';
+import yellowScheme from '../../../scss/colours/primary/_yellow.scss?raw';
+import limeScheme from '../../../scss/colours/primary/_lime.scss?raw';
+import greenScheme from '../../../scss/colours/primary/_green.scss?raw';
+import emeraldScheme from '../../../scss/colours/primary/_emerald.scss?raw';
+import tealScheme from '../../../scss/colours/primary/_teal.scss?raw';
+import cyanScheme from '../../../scss/colours/primary/_cyan.scss?raw';
+import skyScheme from '../../../scss/colours/primary/_sky.scss?raw';
+import blueScheme from '../../../scss/colours/primary/_blue.scss?raw';
+import indigoScheme from '../../../scss/colours/primary/_indigo.scss?raw';
+import violetScheme from '../../../scss/colours/primary/_violet.scss?raw';
+import purpleScheme from '../../../scss/colours/primary/_purple.scss?raw';
+import fuchsiaScheme from '../../../scss/colours/primary/_fuchsia.scss?raw';
+import pinkScheme from '../../../scss/colours/primary/_pink.scss?raw';
+import roseScheme from '../../../scss/colours/primary/_rose.scss?raw';
+
+<Meta title="Styles/Colours/Primary" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Primary colours
+
+<CopyColourTable
+  title="Grey"
+  body={extractCssColourVariables(greyScheme)}
+  included
+  partial="primary/_grey.scss"
+/>
+
+<CopyColourTable
+  title="Slate"
+  body={extractCssColourVariables(slateScheme)}
+  partial="primary/_slate.scss"
+/>
+
+<CopyColourTable
+  title="Zinc"
+  body={extractCssColourVariables(zincScheme)}
+  partial="primary/_zinc.scss"
+/>
+
+<CopyColourTable
+  title="Neutral"
+  body={extractCssColourVariables(neutralScheme)}
+  partial="primary/_neutral.scss"
+/>
+
+<CopyColourTable
+  title="Stone"
+  body={extractCssColourVariables(stoneScheme)}
+  partial="primary/_stone.scss"
+/>
+
+<CopyColourTable
+  title="Red"
+  body={extractCssColourVariables(redScheme)}
+  partial="primary/_red.scss"
+/>
+
+<CopyColourTable
+  title="Orange"
+  body={extractCssColourVariables(orangeScheme)}
+  partial="primary/_orange.scss"
+/>
+
+<CopyColourTable
+  title="Amber"
+  body={extractCssColourVariables(amberScheme)}
+  partial="primary/_amber.scss"
+/>
+
+<CopyColourTable
+  title="Yellow"
+  body={extractCssColourVariables(yellowScheme)}
+  partial="primary/_yellow.scss"
+/>
+
+<CopyColourTable
+  title="Lime"
+  body={extractCssColourVariables(limeScheme)}
+  partial="primary/_lime.scss"
+/>
+
+<CopyColourTable
+  title="Green"
+  body={extractCssColourVariables(greenScheme)}
+  partial="primary/_green.scss"
+/>
+
+<CopyColourTable
+  title="Emerald"
+  body={extractCssColourVariables(emeraldScheme)}
+  partial="primary/_emerald.scss"
+/>
+
+<CopyColourTable
+  title="Teal"
+  body={extractCssColourVariables(tealScheme)}
+  partial="primary/_teal.scss"
+/>
+
+<CopyColourTable
+  title="Cyan"
+  body={extractCssColourVariables(cyanScheme)}
+  partial="primary/_cyan.scss"
+/>
+
+<CopyColourTable
+  title="Sky"
+  body={extractCssColourVariables(skyScheme)}
+  partial="primary/_sky.scss"
+/>
+
+<CopyColourTable
+  title="Blue"
+  body={extractCssColourVariables(blueScheme)}
+  partial="primary/_blue.scss"
+/>
+
+<CopyColourTable
+  title="Indigo"
+  body={extractCssColourVariables(indigoScheme)}
+  partial="primary/_indigo.scss"
+/>
+
+<CopyColourTable
+  title="Violet"
+  body={extractCssColourVariables(violetScheme)}
+  partial="primary/_violet.scss"
+/>
+
+<CopyColourTable
+  title="Purple"
+  body={extractCssColourVariables(purpleScheme)}
+  partial="primary/_purple.scss"
+/>
+
+<CopyColourTable
+  title="Fuchsia"
+  body={extractCssColourVariables(fuchsiaScheme)}
+  partial="primary/_fuchsia.scss"
+/>
+
+<CopyColourTable
+  title="Pink"
+  body={extractCssColourVariables(pinkScheme)}
+  partial="primary/_pink.scss"
+/>
+
+<CopyColourTable
+  title="Rose"
+  body={extractCssColourVariables(roseScheme)}
+  partial="primary/_rose.scss"
+/>

package/dist/docs/styles/colours/thematic.mdx

@@ -0,0 +1,26 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../../utils/docsPage.js';
+import CopyColourTable from '../../docs-components/CopyColourTable/Table.jsx';
+import { extractCssColourVariables } from '../../utils/parseCss';
+
+import trScheme from '../../../scss/colours/thematic/_tr.scss?raw';
+import nordScheme from '../../../scss/colours/thematic/_nord.scss?raw';
+
+<Meta title="Styles/Colours/Thematic" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Thematic colours
+
+<CopyColourTable
+  title="Thomson Reuters"
+  body={extractCssColourVariables(trScheme)}
+  included
+  partial="thematic/_tr.scss"
+/>
+
+<CopyColourTable
+  title="Nord"
+  body={extractCssColourVariables(nordScheme)}
+  partial="thematic/_nord.scss"
+/>

package/dist/docs/styles/intro.mdx

@@ -0,0 +1,23 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from './../utils/docsPage.js';
+
+<Meta title="Styles/Intro" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Styles
+
+This library also includes our main SCSS stylesheets with pre-defined classes you can use to style your page.
+
+### Importing our main stylesheet
+
+Import the SCSS directly in your top-level component. (This is done for you in the Graphics Kit.)
+
+```svelte
+<!-- pages/index.svelte -->
+<script>
+  // other imports and stuffs ...
+
+  import '@reuters-graphics/graphics-components/scss/main';
+</script>
+```

package/dist/docs/styles/tokens/accessibility/main.mdx

@@ -0,0 +1,19 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../../../utils/docsPage.js';
+import CopyTable from '../../../docs-components/CopyTable/Table.jsx';
+import { cssStringToTableArray } from '../../../utils/parseCss';
+
+import visibilityStyles from '../../../../scss/tokens/accessibility/_visibility.scss?inline';
+
+<Meta title="Styles/Tokens/Accessibility" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Accessibility tokens
+
+<CopyTable
+  title="Visibility"
+  header={['Class', 'Include', 'Properties']}
+  body={cssStringToTableArray(visibilityStyles, true)}
+  copyable={[true, (t) => `@include ${t};`, false]}
+/>

package/dist/docs/styles/tokens/backgrounds/main.mdx

@@ -0,0 +1,20 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../../../utils/docsPage.js';
+import CopyTable from '../../../docs-components/CopyTable/Table.jsx';
+import { cssStringToTableArray } from '../../../utils/parseCss';
+
+import backgroundColor from '../../../../scss/tokens/backgrounds/_background-color.scss?inline';
+
+<Meta title="Styles/Tokens/Backgrounds" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Background tokens
+
+<CopyTable
+  title="Background colour"
+  mdnLink="background-color"
+  header={['Class', 'Include', 'Properties']}
+  body={cssStringToTableArray(backgroundColor, true)}
+  copyable={[true, (t) => `@include ${t};`, false]}
+/>

package/dist/docs/styles/tokens/borders/main.mdx

@@ -0,0 +1,46 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../../../utils/docsPage.js';
+import CopyTable from '../../../docs-components/CopyTable/Table.jsx';
+import { cssStringToTableArray } from '../../../utils/parseCss';
+import borderColor from '../../../../scss/tokens/borders/_border-color.scss?raw';
+import borderRadius from '../../../../scss/tokens/borders/_border-radius.scss?raw';
+import borderStyle from '../../../../scss/tokens/borders/_border-style.scss?raw';
+import borderWidth from '../../../../scss/tokens/borders/_border-width.scss?raw';
+
+<Meta title="Styles/Tokens/Borders" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Border tokens
+
+<CopyTable
+  title="Border color"
+  mdnLink="border-color"
+  header={['Class', 'Properties']}
+  body={cssStringToTableArray(borderColor)}
+  copyable={[true, false]}
+/>
+
+<CopyTable
+  title="Border radius"
+  mdnLink="border-radius"
+  header={['Class', 'Properties']}
+  body={cssStringToTableArray(borderRadius)}
+  copyable={[true, false]}
+/>
+
+<CopyTable
+  title="Border style"
+  mdnLink="border-style"
+  header={['Class', 'Properties']}
+  body={cssStringToTableArray(borderStyle)}
+  copyable={[true, false]}
+/>
+
+<CopyTable
+  title="Border width"
+  mdnLink="border-width"
+  header={['Class', 'Properties']}
+  body={cssStringToTableArray(borderWidth)}
+  copyable={[true, false]}
+/>

package/dist/docs/styles/tokens/flexbox/main.mdx

@@ -0,0 +1,113 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../../../utils/docsPage.js';
+import CopyTable from '../../../docs-components/CopyTable/Table.jsx';
+import { cssStringToTableArray } from '../../../utils/parseCss';
+import alignContent from '../../../../scss/tokens/layout/flex/_align-content.scss?raw';
+import alignItems from '../../../../scss/tokens/layout/flex/_align-items.scss?raw';
+import alignSelf from '../../../../scss/tokens/layout/flex/_align-self.scss?raw';
+import flexDirection from '../../../../scss/tokens/layout/flex/_flex-direction.scss?raw';
+import flexGrow from '../../../../scss/tokens/layout/flex/_flex-grow.scss?raw';
+import flexShrink from '../../../../scss/tokens/layout/flex/_flex-shrink.scss?raw';
+import flexWrap from '../../../../scss/tokens/layout/flex/_flex-wrap.scss?raw';
+import flex from '../../../../scss/tokens/layout/flex/_flex.scss?raw';
+import justifyContent from '../../../../scss/tokens/layout/flex/_justify-content.scss?raw';
+import justifyItems from '../../../../scss/tokens/layout/flex/_justify-items.scss?raw';
+import justifySelf from '../../../../scss/tokens/layout/flex/_justify-self.scss?raw';
+
+<Meta title="Styles/Tokens/Flexbox" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Flexbox tokens
+
+Flexbox is a modern way to lay out elements on your page while controling their alignment, distribution, space between and more. If flexbox is new, checkout the excellent [CSS tricks guide](https://css-tricks.com/snippets/css/a-guide-to-flexbox/).
+
+Our style library provides these flexbox utility classes:
+
+<CopyTable
+  title="Align content"
+  mdnLink="align-content"
+  header={['Class', 'Properties']}
+  body={cssStringToTableArray(alignContent)}
+  copyable={[true, false]}
+/>
+
+<CopyTable
+  title="Align items"
+  mdnLink="align-items"
+  header={['Class', 'Properties']}
+  body={cssStringToTableArray(alignItems)}
+  copyable={[true, false]}
+/>
+
+<CopyTable
+  title="Align self"
+  mdnLink="align-self"
+  header={['Class', 'Properties']}
+  body={cssStringToTableArray(alignSelf)}
+  copyable={[true, false]}
+/>
+
+<CopyTable
+  title="Flex direction"
+  mdnLink="flex-direction"
+  header={['Class', 'Properties']}
+  body={cssStringToTableArray(flexDirection)}
+  copyable={[true, false]}
+/>
+
+<CopyTable
+  title="Flex grow"
+  mdnLink="flex-grow"
+  header={['Class', 'Properties']}
+  body={cssStringToTableArray(flexGrow)}
+  copyable={[true, false]}
+/>
+
+<CopyTable
+  title="Flex shrink"
+  mdnLink="flex-shrink"
+  header={['Class', 'Properties']}
+  body={cssStringToTableArray(flexShrink)}
+  copyable={[true, false]}
+/>
+
+<CopyTable
+  title="Flex wrap"
+  mdnLink="flex-wrap"
+  header={['Class', 'Properties']}
+  body={cssStringToTableArray(flexWrap)}
+  copyable={[true, false]}
+/>
+
+<CopyTable
+  title="Flex"
+  mdnLink="flex"
+  header={['Class', 'Properties']}
+  body={cssStringToTableArray(flex)}
+  copyable={[true, false]}
+/>
+
+<CopyTable
+  title="Justify content"
+  mdnLink="justify-content"
+  header={['Class', 'Properties']}
+  body={cssStringToTableArray(justifyContent)}
+  copyable={[true, false]}
+/>
+
+<CopyTable
+  title="Justify items"
+  mdnLink="justify-items"
+  header={['Class', 'Properties']}
+  body={cssStringToTableArray(justifyItems)}
+  copyable={[true, false]}
+/>
+
+<CopyTable
+  title="Justify self"
+  mdnLink="justify-self"
+  header={['Class', 'Properties']}
+  body={cssStringToTableArray(justifySelf)}
+  copyable={[true, false]}
+/>