@reuters-graphics/graphics-components 1.0.30 → 1.1.1

package/dist/docs/docs-components/ThemeBuilder/Customiser/Key.d.ts

@@ -0,0 +1,10 @@
+export default Key;
+declare function Key({ value, name, map, themeName, setTheme, theme }: {
+    value: any;
+    name: any;
+    map: any;
+    themeName: any;
+    setTheme: any;
+    theme: any;
+}): React.JSX.Element;
+import React from 'react';

package/dist/docs/docs-components/ThemeBuilder/Customiser/Key.jsx

@@ -0,0 +1,40 @@
+import React, { useState } from 'react';
+
+import Value from './Value.jsx';
+
+const Key = ({ value, name, map, themeName, setTheme, theme }) => {
+  const [isOpen, setIsOpen] = useState(false);
+  return (
+    <div className="key">
+      <button
+        className={isOpen ? 'open' : ''}
+        onClick={() => setIsOpen((o) => !o)}
+      >
+        <div>
+          <span className="material-symbols-outlined">
+            {isOpen ? 'expand_less' : 'expand_more'}
+          </span>
+        </div>{' '}
+        {name}
+      </button>
+
+      {Object.entries(value).map(([key, value]) => {
+        const props = {
+          theme,
+          setTheme,
+          name: key,
+          themeName,
+          map: map + '.' + key,
+          value,
+          key: themeName + map + key,
+        };
+        if (!isOpen) return null;
+        if (typeof value === 'object')
+          return <Key {...props} key={props.key} />;
+        return <Value {...props} key={props.key} />;
+      })}
+    </div>
+  );
+};
+
+export default Key;

package/dist/docs/docs-components/ThemeBuilder/Customiser/Value.d.ts

@@ -0,0 +1,10 @@
+export default Value;
+declare function Value({ value, name, map, themeName, theme, setTheme }: {
+    value: any;
+    name: any;
+    map: any;
+    themeName: any;
+    theme: any;
+    setTheme: any;
+}): React.JSX.Element;
+import React from 'react';

package/dist/docs/docs-components/ThemeBuilder/Customiser/Value.jsx

@@ -0,0 +1,60 @@
+import React, { useState } from 'react';
+import { cloneDeep, set } from 'lodash-es';
+
+import ColourPicker from './ColourPicker.jsx';
+
+const Input = ({ value, onChange }) => {
+  // Number type
+  // this is buggy...
+  // if ((value || value === 0) && !isNaN(value)) return <input type="number" value={value} onChange={(e) => onChange(Number(e.target.value))}/>;
+  // Colour type
+  if (!/var\(.*\)/i.test(value) && CSS.supports('color', value))
+    return <ColourPicker colour={value} onChange={onChange} />;
+  // Text for the rest...
+  return (
+    <input
+      type="text"
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+    />
+  );
+};
+
+const Value = ({ value, name, map, themeName, theme, setTheme }) => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  const onChange = (newValue) => {
+    const mutableTheme = cloneDeep(theme);
+    set(mutableTheme, map, newValue);
+    setTheme(mutableTheme);
+  };
+
+  const isColour = !/var\(.*\)/i.test(value) && CSS.supports('color', value);
+
+  return (
+    <div className="value">
+      <label>
+        <div>
+          <button
+            className={isOpen ? 'open' : ''}
+            onClick={() => setIsOpen((o) => !o)}
+          >
+            <div>
+              <span className="material-symbols-outlined">
+                {isOpen ? 'expand_less' : 'expand_more'}
+              </span>
+            </div>{' '}
+            {isColour && <div style={{ background: value }}></div>} {name}
+          </button>
+        </div>
+      </label>
+      {isOpen && (
+        <div className="input-container">
+          <Input value={value} key={themeName + map} onChange={onChange} />
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default Value;

package/dist/docs/docs-components/ThemeBuilder/Customiser/styles.module.scss

@@ -0,0 +1,93 @@
+.customiser :global {
+  p {
+    font-size: 14px;
+    color: #666;
+  }
+  div.key > button,
+  div.value > label > div > button {
+    background-color: transparent;
+    border: 0;
+    padding: 0;
+    cursor: pointer;
+    vertical-align: middle;
+    display: inline-flex;
+    div {
+      margin-right: 4px;
+      background-color: #fff;
+      border: 1px solid #bbb;
+      color: #777;
+      font-size: 1rem;
+      line-height: 1rem;
+      transition: all 0.2s;
+      width: 1.2rem;
+      height: 1.2rem;
+      display: inline-flex;
+      justify-content: center;
+      align-items: center;
+      border-radius: 4px;
+      span {
+        display: inline-block;
+        font-size: 1rem;
+      }
+    }
+    &.open {
+      div {
+        // background-color: #666;
+        // border: 1px solid #bbb;
+        color: #333;
+        font-weight: bold;
+      }
+    }
+  }
+  div.key {
+    div.key {
+      padding-left: 10px;
+    }
+  }
+  div.value {
+    padding-left: 10px;
+    div.input-container {
+      padding-left: 0px;
+    }
+    input {
+      width: 100%;
+      outline: 0 !important;
+      margin: 5px 0 5px;
+      padding: 2px 5px;
+      background-color: rgb(245, 242, 240);
+      padding: 5px 5px !important;
+      border: 1px solid #ccc !important;
+      border-radius: 4px;
+    }
+    input[type='color'] {
+      width: 40px;
+    }
+  }
+}
+
+.colourpicker :global {
+  width: 160px;
+  margin-bottom: 10px;
+  .react-colorful {
+    height: 120px;
+    width: 160px;
+    border: 1px solid #666;
+    border-radius: 4px;
+    overflow: hidden;
+  }
+  .react-colorful__saturation {
+    border-radius: 0;
+  }
+  .react-colorful__hue {
+    height: 20px;
+    border-radius: 0;
+  }
+  .react-colorful__pointer {
+    width: 20px;
+    height: 20px;
+  }
+  input {
+    width: 100%;
+    margin-bottom: 5px !important;
+  }
+}

package/dist/docs/docs-components/ThemeBuilder/NewTheme/NewTheme.d.ts

@@ -0,0 +1,6 @@
+export default NewTheme;
+declare function NewTheme({ theme, themeName }: {
+    theme: any;
+    themeName: any;
+}): React.JSX.Element;
+import React from 'react';

package/dist/docs/docs-components/ThemeBuilder/NewTheme/NewTheme.jsx

@@ -0,0 +1,55 @@
+import React from 'react';
+
+import { PrismLight as SyntaxHighlighter } from 'react-syntax-highlighter';
+import VariableTable from '../CSSVariables/VariableTable';
+// @ts-ignore scss
+import classes from './styles.module.scss';
+import darkTheme from '../../../../components/Theme/themes/dark';
+import lightTheme from '../../../../components/Theme/themes/light';
+import prism from 'react-syntax-highlighter/dist/esm/styles/prism/prism';
+import scss from 'react-syntax-highlighter/dist/esm/languages/prism/scss';
+import svelteSyntax from '../../../../../.storybook/svelte-highlighting';
+import { updatedDiff } from 'deep-object-diff';
+
+SyntaxHighlighter.registerLanguage('svelte', svelteSyntax);
+SyntaxHighlighter.registerLanguage('scss', scss);
+
+const NewTheme = ({ theme, themeName }) => {
+  const originalTheme = themeName === 'light' ? lightTheme : darkTheme;
+  const updates = updatedDiff(originalTheme, theme);
+
+  const bgChanged = theme.colour.background !== lightTheme.colour.background;
+
+  return (
+    <div className={classes.newtheme}>
+      <p>
+        Use the code below to adapt the <code>Theme</code> component for your
+        new design:
+      </p>
+      <SyntaxHighlighter language="svelte" style={prism}>
+        {`<Theme
+  base="${themeName}"
+  theme={${JSON.stringify(updates, null, 2).replaceAll('"', "'")}}
+>
+  <!-- ... -->
+</Theme>
+      `}
+      </SyntaxHighlighter>
+      {bgChanged && (
+        <SyntaxHighlighter
+          language="scss"
+          style={prism}
+          customStyle={{ maxHeight: '140px' }}
+        >
+          {`// global.scss
+body {
+  background-color: ${theme.colour.background};
+}`}
+        </SyntaxHighlighter>
+      )}
+      <VariableTable theme={theme} />
+    </div>
+  );
+};
+
+export default NewTheme;

package/dist/docs/docs-components/ThemeBuilder/NewTheme/styles.module.scss

@@ -0,0 +1,9 @@
+.newtheme {
+  position: sticky;
+  top: 10px;
+  p {
+    font-size: 14px;
+    line-height: 18px;
+    color: #666;
+  }
+}

package/dist/docs/docs-components/ThemeBuilder/ThemeBuilder.d.ts

@@ -0,0 +1,3 @@
+export default ThemeBuilder;
+declare function ThemeBuilder(_props: any): React.JSX.Element;
+import React from 'react';

package/dist/docs/docs-components/ThemeBuilder/ThemeBuilder.jsx

@@ -0,0 +1,42 @@
+import React, { useEffect, useState } from 'react';
+
+import Customiser from './Customiser/Customiser';
+import NewTheme from './NewTheme/NewTheme.jsx';
+import ThemeSwitch from './ThemeSwitch/Switch';
+import { Unstyled } from '@storybook/blocks';
+// @ts-ignore scss
+import classes from './styles.module.scss';
+import { cloneDeep } from 'lodash-es';
+import darkTheme from '../../../components/Theme/themes/dark';
+import lightTheme from '../../../components/Theme/themes/light';
+
+const ThemeBuilder = (_props) => {
+  const [themeName, setThemeName] = useState('light');
+  const [theme, setTheme] = useState(cloneDeep(lightTheme));
+
+  useEffect(() => {
+    const newTheme = themeName === 'light' ? lightTheme : darkTheme;
+    setTheme(cloneDeep(newTheme));
+  }, [themeName]);
+
+  return (
+    <Unstyled>
+      <div className={classes.themebuilder}>
+        <div className="column">
+          <ThemeSwitch setThemeName={setThemeName} themeName={themeName} />
+          <Customiser
+            theme={theme}
+            setTheme={setTheme}
+            themeName={themeName}
+            key={themeName}
+          />
+        </div>
+        <div className="column">
+          <NewTheme theme={theme} themeName={themeName} />
+        </div>
+      </div>
+    </Unstyled>
+  );
+};
+
+export default ThemeBuilder;

package/dist/docs/docs-components/ThemeBuilder/ThemeSwitch/Switch.d.ts

@@ -0,0 +1,6 @@
+export default ThemeSwitch;
+declare function ThemeSwitch({ themeName, setThemeName }: {
+    themeName: any;
+    setThemeName: any;
+}): React.JSX.Element;
+import React from 'react';

package/dist/docs/docs-components/ThemeBuilder/ThemeSwitch/Switch.jsx

@@ -0,0 +1,28 @@
+import React from 'react';
+
+// @ts-ignore scss
+import classes from './styles.module.scss';
+
+const ThemeSwitch = ({ themeName, setThemeName }) => {
+  return (
+    <div className={classes.switch}>
+      <p>Choose a base theme:</p>
+      <div className="container">
+        <button
+          className={themeName === 'light' ? 'active' : ''}
+          onClick={() => setThemeName('light')}
+        >
+          <span className="material-symbols-outlined">light_mode</span>
+        </button>
+        <button
+          className={themeName === 'dark' ? 'active' : ''}
+          onClick={() => setThemeName('dark')}
+        >
+          <span className="material-symbols-outlined">dark_mode</span>
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export default ThemeSwitch;

package/dist/docs/docs-components/ThemeBuilder/ThemeSwitch/styles.module.scss

@@ -0,0 +1,40 @@
+.switch :global {
+  margin-bottom: 12px;
+  p {
+    font-size: 14px;
+    color: #666;
+  }
+  div {
+    border: 1px solid #999;
+    display: inline-block;
+    border-radius: 50px;
+    overflow: hidden;
+    padding: 0;
+  }
+  button {
+    padding: 5px 22px;
+    background-color: #efefef;
+    color: #999;
+    cursor: pointer;
+    border: 0;
+    display: inline-flex;
+    justify-content: center;
+    align-items: center;
+    &:hover {
+      color: #333;
+    }
+    span {
+      font-size: 1.2rem;
+      line-height: 1.2rem;
+    }
+    &.active {
+      background-color: #fff;
+      color: rgb(0, 119, 170);
+      font-weight: bold;
+    }
+
+    &:first-child {
+      border-right: 1px solid #999;
+    }
+  }
+}

package/dist/docs/docs-components/ThemeBuilder/styles.module.scss

@@ -0,0 +1,20 @@
+.themebuilder :global {
+  margin: 2rem 0;
+  display: grid;
+  grid-auto-flow: column;
+  grid-auto-columns: 1fr;
+  gap: 80px;
+
+  div.column {
+    min-width: 200px;
+  }
+
+  pre {
+    background-color: #ddd;
+    width: 100%;
+    height: 400px;
+    margin: 0;
+    border-radius: 4px;
+    border: 1px solid #ccc;
+  }
+}

package/dist/docs/guides/customising-with-scss.mdx

@@ -0,0 +1,94 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../utils/docsPage.js';
+
+import startImg from './imgs/scss-start.png';
+import highlightImg from './imgs/scss-highlight.png';
+import inspectorImg from './imgs/scss-inspector.png';
+import changeImg from './imgs/scss-change.png';
+import testImg from './imgs/scss-test.png';
+import winningImg from './imgs/scss-winning.png';
+
+<Meta
+  title="Guides/Customising components with SCSS"
+  parameters={{ ...parameters }}
+/>
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Customising components with SCSS
+
+One of the most powerful ways to customise components isn't props or, even, Svelte.
+
+<p className="sbdocs-p">
+  <span className="highlight bold">
+    It&rsquo;s SCSS and your web inspector!
+  </span>
+</p>
+
+## How's that??
+
+Let's say you wanted to change our `BeforeAfter` component. You want the text overlays to be at the bottom of the image instead of the top like this:
+
+<img src={startImg} width="600" />
+
+The first thing you should do is <span className="highlight">check out the elements you want to change in your web inspector</span> and see if CSS can make the change you want.
+
+<img src={highlightImg} width="300" style={{ margin: '0 0 1rem' }} />
+
+<img src={inspectorImg} width="100%" />
+
+In our case, we want to change the absolute position of those elements. To test that'll actually work, we can <span className="highlight">try it directly in the inspector first!</span>
+
+<img src={changeImg} width="500" style={{ margin: '0 0 1rem' }} />
+
+<img src={testImg} width="600" style={{ margin: '0 0 1rem' }} />
+
+Now that we know we can change what we need through CSS it's time to write some SCSS, either in your `global.scss` file or directly in a component like `App.svelte`.
+
+First, let's look at the class of the style rule we changed in the inspector:
+
+`figure.before-after-container.s-khJY-w4TYkp5 .overlay-container.before.s-khJY-w4TYkp5`
+
+One thing we always need to do is <span className="highlight">strip out any Svelte class names</span>, i.e., those weird `.s-khJY-w4TYkp5` classes. Why? Those are random classes Svelte adds to CSS, and we can't guarantee they won't change.
+
+That leaves us with:
+
+`figure.before-after-container .overlay-container.before`
+
+But we need our style rule to _beat_ the original style in the CSS cascade, and right now, it's less specific without those class names we stripped.
+
+The easiest way to make sure your style rule wins out is to <span className="highlight">add an ID either directly to the element or to a parent</span>. In our case, let's add an ID through the `BeforeAfter` `id` prop. Now we can use it! (For extra credit, though, we'll drop the `.before` so our new style rule applies to _both_ overlays.)
+
+```scss
+figure#my-before-after .overlay-container {
+  bottom: 0;
+}
+```
+
+Now our selector is more specific. We win!
+
+If you don't see a way to add an ID through a component's props, then just wrap the component in a `div` in your code:
+
+```svelte
+<div id="my-before-after">
+  <BeforeAfter />
+</div>
+```
+
+... and use that, instead!
+
+```scss
+div#my-before-after figure .overlay-container {
+  bottom: 0;
+}
+```
+
+We can <span className="highlight">confirm the new style rule is winning by looking at its order back in our web inspector!</span>
+
+<img src={winningImg} width="500" style={{ margin: '0 0 1rem' }} />
+
+Done!
+
+#### Can I just... `important!` it?
+
+Yep, as a last result. Just be sure your style rule is **very specific** and not something generic that might apply to other elements like `div.container`.

package/dist/docs/guides/getting-help.mdx

@@ -0,0 +1,30 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../utils/docsPage.js';
+
+<Meta title="Guides/Getting help" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Getting help
+
+🚨 **If you're on deadline**, talk to your editor who can point you to the nearest developer.
+
+If you're _off_ deadline, we use GitHub issues to track things that need fixing up or could be improved. Use one of the links below to create a new issue.
+
+---
+
+### Is something wrong in the code?
+
+🏷️ [Click here](https://github.com/reuters-graphics/graphics-components/issues/new?labels=%F0%9F%90%9B%20bug&assignees=hobbes7878) to create an issue on GitHub and report any bugs you've found. It's **very** helpful if you also share a link to any repo you're working in where you've spotted the bug.
+
+---
+
+### Is something wrong in the docs?
+
+🏷️ [Click here](https://github.com/reuters-graphics/graphics-components/issues/new?labels=%F0%9F%93%9A%20documentation&assignees=hobbes7878) and tell us which docs are incorrect, unclear or could otherwise be improved.
+
+---
+
+### Have an idea for a new component or how to improve an existing one?
+
+🏷️ [Click here](https://github.com/reuters-graphics/graphics-components/issues/new?labels=%F0%9F%9A%80%20new%20feature&assignees=hobbes7878) and tell us more.

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

@@ -0,0 +1,74 @@
+import { Meta } from '@storybook/blocks';
+import { parameters } from '../utils/docsPage.js';
+
+<Meta title="Guides/Using with Google docs" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Using with Google docs
+
+Most of the default examples in these docs show how to use components by passing data into them directly through 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.
+
+It's usually easy to use a Google Doc to fill in the props for our components, but it may mean you need to write a tiny bit of code to translate strings from a doc into the data type our component's props expect.
+
+Let's look at a basic component, a `ProfileCard`, with a demo that looks like this in the docs:
+
+```svelte
+<script>
+  import { ProfileCard } from '@reuters-graphics/graphics-components';
+</script>
+
+<ProfileCard
+  name="Tom"
+  img="https://cats.com/cat1.jpg"
+  birthday="{new Date('2020-09-25')}"
+  bio="Some notes.\n\nWith multiple paragraphs."
+  isStaff="{true}"
+/>
+```
+
+The data for the component's props includes strings, a date and a boolean.
+
+In our Google doc, we might fill out a block for this component like this:
+
+```yaml
+Type: profile-card
+Name: Tom
+Image: images/tom-the-cat.jpg
+Birthday: 2020-09-25
+Bio: Some notes.
+
+With multiple paragraphs.
+:end
+Staff: true
+```
+
+Now we can tie that data into your blocks loop like this:
+
+```svelte
+<script>
+  // These are usually already imported for you
+  import { assets } from '$app/paths';
+  import content from '$locales/en/content.json';
+
+  import { ProfileCard } from '@reuters-graphics/graphics-components';
+</script>
+
+{#each content.blocks as block}
+  {#if block.Type}
+    <!-- ... -->
+  {:else if block.Type === 'profile-card'}
+    <ProfileCard
+      name="{block.Name}"
+      img="{`${assets}/${block.Image}`}"
+      birthday="{new Date(block.Birthday)}"
+      bio="{block.Bio}"
+      isStaff="{block.Staff === 'true'}"
+    />
+
+    <!-- ... -->
+  {/if}
+{/each}
+```
+
+Notice how we're coercing some of our data from strings into other data types: a boolean for `isStaff`, a date for `birthday` and an absolute path for `img`.