guides rewrite. rewrites quickit docs. removes Google Doc based utils

This commit is contained in:
hobbes7878 2024-11-21 14:37:38 +00:00
parent 850e907b85
commit 94a869223b
31 changed files with 121 additions and 590 deletions

View file

@ -34,7 +34,7 @@ div.sbdocs-content {
}
.docblock-source {
margin: 1rem 0;
margin: 1rem 0 2.5rem;
}
& > div > :where(p, ul, ol),
@ -130,10 +130,6 @@ div.sbdocs-content {
}
}
.sbdocs.sbdocs-wrapper {
padding-top: 1rem;
}
div.reset-article {
width: calc(100% + 30px);
margin-left: -15px;

View file

@ -17,7 +17,7 @@ const preview: Preview = {
// @ts-ignore Is OK
decorators: [() => Wrapper],
tags: ['autodocs'],
parameters: {
parameters: {
viewMode: 'docs',
previewTabs: { 'storybook/docs/panel': { index: -1 } },
controls: {
@ -40,7 +40,7 @@ const preview: Preview = {
[
'Using these docs',
'Using with the Graphics Kit',
'Using with Google docs',
'Using with ArchieML docs',
'Customising components with SCSS',
'*',
'Getting help',

View file

@ -16,7 +16,19 @@ Use it like this:
<BodyText text="{markdownText}" />
```
... or more commonly, you'll use it with a Google doc in the Graphics Kit like this:
... or more commonly, you'll use it with a ArchieML doc in the Graphics Kit like this:
```yaml
[blocks]
type: text
text: Lorem ipsum ...
... etc.
:end
[]
```
```svelte
<script>
@ -26,8 +38,9 @@ Use it like this:
</script>
{#each content.blocks as block}
{#if block.Type === 'text'}
<BodyText text="{block.Text}" />
{#if block.type === 'text'}
<BodyText text="{block.text}" />
<!-- ... -->
{/if}
{/each}
```

View file

@ -14,20 +14,19 @@
<script>
import { Template, Story } from '@storybook/addon-svelte-csf';
import { getEndNotesPropsFromDoc } from './docProps';
const notes = [
{
Title: 'Note',
Text: 'Data is current as of today.',
title: 'Note',
text: 'Data is current as of today.',
},
{
Title: 'Sources',
Text: 'Data, Inc.',
title: 'Sources',
text: 'Data, Inc.',
},
{
Title: 'Edited by',
Text: '<a href="https://www.reuters.com/graphics/">Editor</a>, Copyeditor',
title: 'Edited by',
text: '<a href="https://www.reuters.com/graphics/">Editor</a>, Copyeditor',
},
];
</script>
@ -36,4 +35,4 @@
<EndNotes {...args} />
</Template>
<Story name="Default" args="{{ notes: getEndNotesPropsFromDoc(notes) }}" />
<Story name="Default" args="{{ notes }}" />

View file

@ -1,15 +0,0 @@
interface EndNote {
Title: string;
Text: string;
}
type EndNotes = EndNote[];
export const getEndNotesPropsFromDoc = (endNotes: EndNotes) => {
return endNotes.map((d) => {
return {
title: d.Title,
text: d.Text,
};
});
};

View file

@ -2,7 +2,7 @@
// @ts-ignore raw
import componentDocs from './stories/docs/component.md?raw';
// @ts-ignore raw
import quickitDocs from './stories/docs/quickit.md?raw';
import archieMLDocs from './stories/docs/archieML.md?raw';
// @ts-ignore raw
import missingAltTextDocs from './stories/docs/missingAltText.md?raw';
@ -52,14 +52,14 @@
/>
<Story
name="🚀 QUICKIT"
name="ArchieML"
args="{{
src: sharkSrc,
altText: 'A shark!',
width: 'normal',
caption: 'Carcharodon carcharias - REUTERS',
}}"
{...withStoryDocs(quickitDocs)}
{...withStoryDocs(archieMLDocs)}
/>
<Story

View file

@ -1,38 +0,0 @@
An example of using `FeaturePhoto` in the Graphics Kit with a Google Doc.
```yaml
# Google doc block
Type: photo
Width: normal
Src: images/shark.jpg
AltText: The king of the sea
Caption: Carcharodon carcharias - REUTERS
```
```svelte
<!-- App.svelte -->
<script>
// Add FeaturePhoto to imports from graphics-components
import { FeaturePhoto } from '@reuters-graphics/graphics-components';
// These should be already imported for you.
import content from '$locales/en/content.json';
import { assets } from '$app/paths';
</script>
{#each content.blocks as block}
{#if block.Type === 'text'}
<!-- ... other blocks -->
<!-- Copy/paste into your blocks loop! -->
{:else if block.Type === 'photo'}
<FeaturePhoto
width="{block.Width}"
src="{`${assets}/${block.Src}`}"
altText="{block.AltText}"
caption="{block.Caption}"
/>
<!-- END copy/paste -->
{/if}
{/each}
```

View file

@ -2,7 +2,7 @@
// @ts-ignore raw
import componentDocs from './stories/docs/component.md?raw';
// @ts-ignore raw
import quickitDocs from './stories/docs/quickit.md?raw';
import archieMLDocs from './stories/docs/archieML.md?raw';
// @ts-ignore raw
import customTextDocs from './stories/docs/customText.md?raw';
// @ts-ignore raw
@ -60,7 +60,7 @@
}}"
/>
<Story name="🚀 QUICKIT" {...withStoryDocs(quickitDocs)}>
<Story name="ArchieML" {...withStoryDocs(archieMLDocs)}>
<GraphicBlock
width="normal"
title="Earthquake in Haiti"

View file

@ -1,35 +0,0 @@
For Graphics Kit users, the `GraphicBlock` component is built-in to handle [ai2svelte](https://github.com/reuters-graphics/ai2svelte) graphics.
First, import your ai2svelte graphic in `App.svelte` and add it to the `aiCharts` object;
```svelte
<!-- App.svelte -->
<script>
// Other stuff...
import AiMap from './ai2svelte/my-map.svelte';
const aiCharts = {
// Other charts...
AiMap,
};
</script>
```
Then add the following structure to your Google Doc, taking care that the name of your chart in the `aiCharts` object matches the name of your `Chart`:
```yaml
# Google doc block
Type: ai-graphic
Chart: AiMap
Width: normal
TextWidth: normal
Title: Earthquake in Haiti
Description: The 7.2-magnitude earthquake struck at 8:29 a.m. EST, Aug. 14, 2021.
Notes: \Note: A shakemap represents the ground shaking produced by an earthquake.
\Source: USGIS
:end
Aria: A map that shows the shake intensity of the earthquake, which was worst in central Haiti.
:end
```

View file

@ -251,7 +251,7 @@
}
:global(.splide__arrows button:hover) {
opacity: 1;
border-color: $theme-colour-text-secondary;
border-color: mixins.$theme-colour-text-secondary;
@include mixins.text-secondary;
}
:global(.splide__arrows button:disabled) {
@ -277,8 +277,8 @@
height: 7px;
border-radius: 0;
padding: 0;
border: 1px solid $theme-colour-background;
background: $theme-colour-text-secondary;
border: 1px solid mixins.$theme-colour-background;
background: mixins.$theme-colour-text-secondary;
opacity: 0.4;
}
:global(ul.splide__pagination li button.is-active) {

View file

@ -2,7 +2,7 @@
// @ts-ignore raw
import componentDocs from './stories/docs/component.md?raw';
// @ts-ignore raw
import quickitDocs from './stories/docs/quickit.md?raw';
import archieMLDocs from './stories/docs/archieML.md?raw';
// @ts-ignore raw
import missingAltTextDocs from './stories/docs/missingAltText.md?raw';
@ -30,8 +30,6 @@
<script>
import { Template, Story } from '@storybook/addon-svelte-csf';
import { getPhotoPackPropsFromDoc } from './docProps';
const defaultImages = [
{
src: 'https://via.placeholder.com/1024x768.jpg',
@ -65,44 +63,44 @@
{ breakpoint: 750, rows: [1, 3] },
];
const quickItBlock = {
Type: 'photo-pack',
ID: 'my-photo-pack',
Class: 'mb-2',
Width: 'wide',
const archieMLBlock = {
type: 'photo-pack',
id: 'my-photo-pack',
class: 'mb-2',
width: 'wide',
textWidth: 'normal',
Gap: '15',
Images: [
gap: '15',
images: [
{
Src: 'https://via.placeholder.com/1024x768.jpg',
AltText: 'alt text',
Caption: 'Lorem ipsum. Reuters/Photog',
MaxHeight: '600',
src: 'https://via.placeholder.com/1024x768.jpg',
altText: 'alt text',
caption: 'Lorem ipsum. Reuters/Photog',
maxHeight: 600,
},
{
Src: 'https://via.placeholder.com/1024x768.jpg',
AltText: 'alt text',
Caption: 'Lorem ipsum. Reuters/Photog',
src: 'https://via.placeholder.com/1024x768.jpg',
altText: 'alt text',
caption: 'Lorem ipsum. Reuters/Photog',
},
{
Src: 'https://via.placeholder.com/1024x768.jpg',
AltText: 'alt text',
Caption: 'Lorem ipsum. Reuters/Photog',
src: 'https://via.placeholder.com/1024x768.jpg',
altText: 'alt text',
caption: 'Lorem ipsum. Reuters/Photog',
},
{
Src: 'https://via.placeholder.com/1024x768.jpg',
AltText: 'alt text',
Caption: 'Lorem ipsum. Reuters/Photog',
src: 'https://via.placeholder.com/1024x768.jpg',
altText: 'alt text',
caption: 'Lorem ipsum. Reuters/Photog',
},
{
Src: 'https://via.placeholder.com/1024x768.jpg',
AltText: 'alt text',
Caption: 'Lorem ipsum. Reuters/Photog',
src: 'https://via.placeholder.com/1024x768.jpg',
altText: 'alt text',
caption: 'Lorem ipsum. Reuters/Photog',
},
],
Layouts: [
{ Breakpoint: '750', Rows: '2,3' },
{ Breakpoint: '450', Rows: '1, 2, 2' },
layouts: [
{ breakpoint: 750, rows: [2, 3] },
{ breakpoint: 450, rows: [1, 2, 2] },
],
};
@ -139,9 +137,9 @@
/>
<Story
name="🚀 QUICKIT"
{...withStoryDocs(quickitDocs)}
args="{getPhotoPackPropsFromDoc(quickItBlock)}"
name="ArchieML"
{...withStoryDocs(archieMLDocs)}
args="{archieMLBlock}"
/>
<Story

View file

@ -1,59 +0,0 @@
import urlJoin from 'proper-url-join';
interface BlockImage {
Src: string;
AltText: string;
Caption?: string;
MaxHeight?: string;
}
interface BlockLayout {
Breakpoint: string;
Rows: string;
}
interface Block {
Type: string;
ID?: string;
Class?: string;
Width: string;
textWidth?: string;
Gap?: string;
Images: BlockImage[];
Layouts: BlockLayout[];
}
export const getPhotoPackPropsFromDoc = (
docBlock: Block,
assetsPath: string = ''
) => {
return {
id: docBlock.ID,
cls: docBlock.Class,
width: docBlock.Width,
textWidth: docBlock.textWidth,
gap:
docBlock.Gap && isNaN(docBlock.Gap as unknown as number) ?
null
: parseInt(docBlock.Gap),
images: docBlock.Images.map((img) => ({
src:
/^https?:\/\/|^\/\//i.test(img.Src) ?
img.Src
: urlJoin(assetsPath, img.Src),
altText: img.AltText,
caption: img.Caption,
maxHeight:
img.MaxHeight && isNaN(img.MaxHeight as unknown as number) ?
null
: parseFloat(img.MaxHeight),
})),
layouts: docBlock.Layouts.map((layout) => ({
breakpoint:
isNaN(layout.Breakpoint as unknown as number) ? null : (
parseFloat(layout.Breakpoint)
),
rows: layout.Rows.split(',').map((r) => parseInt(r.trim())),
})),
};
};

View file

@ -1,67 +0,0 @@
Setup your Google Doc with the images, layouts and other props you want:
```yaml
# Google doc block
Type: photo-pack
ID: my-photo-pack
Class: mb-2 # adjust margin class as needed
Width: wide
TextWidth: normal
Gap: 10
[.Images]
Src: images/my-img-1.jpg
AltText: Alt text
Caption: Lorem ipsum. REUTERS/Photog
MaxHeight: 600 # Optional max-height
Src: images/my-img-2.jpg
AltText: Alt text
Caption: Lorem ipsum. REUTERS/Photog
Src: images/my-img-3.jpg
AltText: Alt text
Caption: Lorem ipsum. REUTERS/Photog
Src: images/my-img-4.jpg
AltText: Alt text
Caption: Lorem ipsum. REUTERS/Photog
Src: images/my-img-5.jpg
AltText: Alt text
Caption: Lorem ipsum. REUTERS/Photog
[]
[.Layouts]
Breakpoint: 750
Rows: 2,3 # Must add to total number of images!
Breakpoint: 450
Rows: 1,2,2
[]
```
In your project, you can use the `getPhotoPackPropsFromDoc` utilty to easily convert the GoogleDoc format above into the props the `PhotoPack` component expects.
```svelte
<!-- App.svelte -->
<script>
import {
getPhotoPackPropsFromDoc,
PhotoPack,
} from '@reuters-graphics/graphics-components';
// These should be already imported for you.
import content from '$locales/en/content.json';
import { assets } from '$app/paths';
</script>
{#each content.blocks as block}
{#if block.Type === 'text'}
<!-- ... other blocks -->
<!-- Copy/paste into your blocks loop! -->
{:else if block.Type === 'photo-pack'}
<PhotoPack {...getPhotoPackPropsFromDoc(block, assets)} />
<!-- END copy/paste -->
{/if}
{/each}
```

View file

@ -2,7 +2,7 @@
// @ts-ignore raw
import componentDocs from './stories/docs/component.md?raw';
// @ts-ignore raw
import quickitDocs from './stories/docs/quickit.md?raw';
import archieMLDocs from './stories/docs/archieML.md?raw';
import SEO from './SEO.svelte';
@ -37,11 +37,11 @@
/>
<Story
name="🚀 QUICKIT"
name="ArchieML"
args="{{
baseUrl: 'https://graphics.reuters.com',
pageUrl: new URL('https://graphics.reuters.com/hello-world/'),
publishTime: new Date('2020-09-15').toISOString(),
}}"
{...withStoryDocs(quickitDocs)}
{...withStoryDocs(archieMLDocs)}
/>

View file

@ -1,29 +0,0 @@
Add the `SEO` component to any page specified in the `pages/` directory of the Graphics Kit.
Most of the fields are filled in by other sources, like your Google Doc and package.json. (Usually, the fastest way is to copy the `SEO` component from one of the pages already in your project.)
> **IMPORTANT:** For _reasons_, we can't document the value of `VITE_BASE_URL` below. It's `import` + `.meta.env.BASE_URL` (concatenate all that) in the Graphics Kit and other Vite-based rigs.
```svelte
<script>
import { SEO } from '@reuters-graphics/graphics-components';
import pkg from '$pkg';
import content from '$locales/en/content.json';
import { assets } from '$app/paths';
import { page } from '$app/stores';
</script>
<SEO
baseUrl="{VITE_BASE_URL}"
pageUrl="{$page.url}"
seoTitle="{content.SEOTitle}"
seoDescription="{content.SEODescription}"
shareTitle="{content.ShareTitle}"
shareDescription="{content.ShareDescription}"
shareImgPath="{`${assets}/${content.ShareImgPath}`}"
shareImgAlt="{content.ShareImgAlt}"
publishTime="{pkg?.reuters?.graphic?.published}"
updateTime="{pkg?.reuters?.graphic?.updated}"
authors="{pkg?.reuters?.graphic?.authors}"
/>
```

View file

@ -6,7 +6,7 @@
// @ts-ignore raw
import ai2svelteDocs from './stories/docs/ai2svelte.md?raw';
// @ts-ignore raw
import quickitDocs from './stories/docs/quickit.md?raw';
import archieMLDocs from './stories/docs/archieML.md?raw';
import Scroller from './Scroller.svelte';
@ -46,8 +46,6 @@
import AiMap2 from './stories/components/ai2svelte/ai-scroller-2.svelte';
import AiMap3 from './stories/components/ai2svelte/ai-scroller-3.svelte';
import { getScrollerPropsFromDoc } from './docProps';
const aiCharts = {
AiMap1,
AiMap2,
@ -55,26 +53,26 @@
};
const docBlock = {
Type: 'scroller',
Width: 'fluid',
ForegroundPosition: 'middle',
ID: 'my-scroller',
StackBackground: 'true',
Steps: [
type: 'scroller',
width: 'fluid',
foregroundPosition: 'middle',
id: 'my-scroller',
stackBackground: true,
steps: [
{
Background: 'AiMap1',
Text: '#### Step 1\n\nLorem ipsum',
AltText: 'A map showing the Upper West side in New York City.',
background: aiCharts.AiMap1,
text: '#### Step 1\n\nLorem ipsum',
altText: 'A map showing the Upper West side in New York City.',
},
{
Background: 'AiMap2',
Text: '#### Step 2\n\nLorem ipsum',
AltText: 'The same map now highlights 98th Street.',
background: aiCharts.AiMap2,
text: '#### Step 2\n\nLorem ipsum',
altText: 'The same map now highlights 98th Street.',
},
{
Background: 'AiMap3',
Text: '#### Step 3\n\nLorem ipsum',
AltText:
background: aiCharts.AiMap3,
text: '#### Step 3\n\nLorem ipsum',
altText:
'The same map now highlights three locations near 98th Street where something particulary important happened.',
},
],
@ -115,11 +113,7 @@
}}"
/>
<Story
name="🚀 QUICKIT"
args="{getScrollerPropsFromDoc(docBlock, aiCharts)}"
{...withStoryDocs(quickitDocs)}
/>
<Story name="ArchieML" args="{docBlock}" {...withStoryDocs(archieMLDocs)} />
<Story
name="Foreground components"

View file

@ -1,44 +0,0 @@
import type { ComponentType } from 'svelte';
interface BlockStep {
AltText?: string;
Background: string;
Text: string;
}
interface Block {
Type: string;
Width: string;
Preload?: string;
ForegroundPosition: string;
StackBackground?: string;
EmbeddedLayout?: string;
ID?: string;
Steps: BlockStep[];
}
interface AiCharts {
[key: string]: ComponentType;
}
export const getScrollerPropsFromDoc = (
docBlock: Block,
aiCharts: AiCharts,
assetsPath: string = ''
) => {
return {
id: docBlock.ID,
backgroundWidth: docBlock.Width,
foregroundPosition: docBlock.ForegroundPosition,
stackBackground:
docBlock.StackBackground === 'true' || !docBlock.StackBackground,
embeddedLayout: docBlock.EmbeddedLayout,
preload: docBlock.Preload ? parseInt(docBlock.Preload) || 1 : 1,
steps: docBlock.Steps.map((step) => ({
background: aiCharts[step.Background],
backgroundProps: { assetsPath },
foreground: step.Text,
altText: step.AltText,
})),
};
};

View file

@ -41,7 +41,7 @@ A more detailed example of using `Scroller` with graphics created by [ai2svelte]
/>
```
When working with a Google doc, here's an example of how you can tie your text into your steps.
When working with a ArchieML doc, here's an example of how you can tie your text into your steps.
```yaml
# Google doc block

View file

@ -1,60 +0,0 @@
For Graphics Kit users, the `Scroller` component is built-in for scrollytelling with [ai2svelte](https://github.com/reuters-graphics/ai2svelte) graphics and text.
First, import your ai2svelte graphics in `App.svelte` and add them to the `aiCharts` object;
```svelte
<!-- App.svelte -->
<script>
// Other stuff...
import AiMap1 from './ai2svelte/my-map-1.svelte';
import AiMap2 from './ai2svelte/my-map-2.svelte';
import AiMap3 from './ai2svelte/my-map-3.svelte';
const aiCharts = {
// Other charts...
AiMap1,
AiMap2,
AiMap3,
};
</script>
```
Then add the following structure to your Google Doc, taking care that the names of your charts in the `aiCharts` object match the names of your step backgrounds:
```yaml
# Google doc block
Type: ai-scroller
ID: my-map-scroller
Width: normal
ForegroundPosition: middle
StackBackground: true
[.Steps]
Background: AiMap1
Text: #### Step 1
Lorem ipsum
: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
Text: #### Step 2
Lorem ipsum
:end
AltText: The same map now highlights 98th Street.
:end
Background: AiMap3
Text: #### Step 3
Lorem ipsum
:end
AltText: The same map now highlights three locations near 98th Street where something particulary important happened.
:end
[]
```

View file

@ -21,7 +21,7 @@
import { Template, Story } from '@storybook/addon-svelte-csf';
// @ts-ignore raw
import quickitDocs from './stories/docs/quickit.md?raw';
import archieML from './stories/docs/archieML.md?raw';
import { withStoryDocs } from '$lib/docs/utils/withParams.js';
@ -56,7 +56,7 @@
}}"
/>
<Story name="🚀 QUICKIT" {...withStoryDocs(quickitDocs)}>
<Story name="ArchieML" {...withStoryDocs(archieML)}>
<SiteHeadline
hed="{content.Hed}"
section="{content.Section}"

View file

@ -1,30 +0,0 @@
Setup your Google Doc to work with the `SiteHeadline` component.
```yaml
# Beginning of your Google doc
Section: Global News
SectionUrl:
Hed: A beautiful page
Authors: Samuel Granados, Dea Bankova
Published: 2022-09-12T08:30:00.000Z
Updated:
```
```svelte
<!-- App.svelte -->
<script>
import { SiteHeadline } from '@reuters-graphics/graphics-components';
// These should be already imported for you.
import content from '$locales/en/content.json';
</script>
<SiteHeadline
section="{content.Section}"
sectionUrl="{content.SectionUrl}"
hed="{content.Hed}"
authors="{content.Authors.split(',')}"
publishTime="{content.Published}"
updateTime="{content.Updated}"
/>
```

View file

@ -1,5 +1,6 @@
import { Meta } from '@storybook/blocks';
import { parameters } from '../utils/docsPage.js';
import Highlight from '../docs-components/Highlight/Highlight';
import startImg from './imgs/scss-start.png';
import highlightImg from './imgs/scss-highlight.png';
@ -29,13 +30,13 @@ Let's say you wanted to change our `BeforeAfter` component. You want the text ov
<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.
The first thing you should do is <Highlight>check out the elements you want to change in your web inspector</Highlight> 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>
In our case, we want to change the absolute position of those elements. To test that'll actually work, we can <Highlight>try it directly in the inspector first!</Highlight>
<img src={changeImg} width="500" style={{ margin: '0 0 1rem' }} />
@ -47,7 +48,7 @@ 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.
One thing we always need to do is <Highlight>strip out any Svelte class names</Highlight>, 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:
@ -55,7 +56,7 @@ That leaves us with:
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.)
The easiest way to make sure your style rule wins out is to <Highlight>add an ID either directly to the element or to a parent</Highlight>. 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 {
@ -81,12 +82,14 @@ div#my-before-after figure .overlay-container {
}
```
We can <span className="highlight">confirm the new style rule is winning by looking at its order back in our web inspector!</span>
We can <Highlight>confirm the new style rule is winning by looking at its order back in our web inspector!</Highlight>
<img src={winningImg} width="500" style={{ margin: '0 0 1rem' }} />
Done!
#### Can I just... `important!` it?
### 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`.
Yep! Just be sure your style rule is **very specific** and not something generic that might apply to other elements in your page like `div.container`.
Many of the components have `class` or `id` props you can use to attach additional classes or an id that will add more specificity to your components.

View file

@ -13,16 +13,16 @@ If you're _off_ deadline, we use GitHub issues to track things that need fixing
### 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.
🏷️ [Click here](https://github.com/reuters-graphics/graphics-components/issues/new?labels=bug&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.
🏷️ [Click here](https://github.com/reuters-graphics/graphics-components/issues/new?labels=documentation&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.
🏷️ [Click here](https://github.com/reuters-graphics/graphics-components/issues/new?labels=new%20feature&assignees=hobbes7878) and tell us more.

View file

@ -1,72 +0,0 @@
import { Meta } from '@storybook/blocks';
import { parameters } from '../utils/docsPage.js';
<Meta title="Guides/Using with Google docs" parameters={{ ...parameters }} />
# 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`.

View file

@ -1,5 +1,6 @@
import { Meta } from '@storybook/blocks';
import { parameters } from '../utils/docsPage.js';
import Highlight from '../docs-components/Highlight/Highlight';
<Meta
title="Guides/Using with the Graphics Kit"
@ -8,47 +9,26 @@ import { parameters } from '../utils/docsPage.js';
# 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.
Our graphics components are designed to work seemlessly with the [Graphics Kit](https://github.com/reuters-graphics/bluprint_graphics-kit) as well as just about any Svelte-based page builder.
## Quickit
**There is, however, one gotcha to watch out for:**
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.
When working with multimedia files like images or videos, components expect all paths to be <Highlight>absolute URLs.</Highlight>
(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`
✅ `https://reuters.com/graphics/.../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!
In the Graphics Kit, that means you'll need to prefix relative paths with the special [`assets`](https://svelte.dev/docs/kit/$app-paths#assets) SvelteKit module that contains the root URL for your project. 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 the assets module if it's not already there.
import { assets } from '$app/paths';
</script>
<!-- Use the assets module to prefix the path to your image. -->
<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)

Binary file not shown.

Before

Width:  |  Height:  |  Size: 51 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 148 KiB

After

Width:  |  Height:  |  Size: 152 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 324 KiB

After

Width:  |  Height:  |  Size: 380 KiB

View file

@ -1,11 +1,11 @@
import { Meta } from '@storybook/blocks';
import { parameters } from '../utils/docsPage.js';
import Highlight from '../docs-components/Highlight/Highlight';
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 }} />
@ -14,28 +14,34 @@ import moreStoriesImg from './imgs/more-stories.png';
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.
## Prerequisites
Reuters Graphics components are written using Svelte, and we assume in these docs you have a very basic understanding of how those components work.
If you don't, **🛑 STOP NOW** and read ["Bare minimum Svelte"](./?path=/docs/guides-bare-minimum-svelte--docs).
## 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:
Each component has a Docs page and one or more <Highlight>stories</Highlight> 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
### Parts of a component docs 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.
Each component page starts with an intro that includes a little documentation and a code <Highlight>snippet</Highlight>. 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.
Next is a <Highlight>frame</Highlight> 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.
Below the story frame is an <Highlight>args table</Highlight>. This is the most important part of every component&rsquo;s page. 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 }} />
@ -43,10 +49,6 @@ Each prop includes its name and a description with the data type that prop expec
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

View file

@ -49,8 +49,3 @@ export { default as Theme, themes } from './components/Theme/Theme.svelte';
export { default as ToolsHeader } from './components/ToolsHeader/ToolsHeader.svelte';
export { default as Video } from './components/Video/Video.svelte';
export { default as Visible } from './components/Visible/Visible.svelte';
// Utilities
export { getEndNotesPropsFromDoc } from './components/EndNotes/docProps.js';
export { getPhotoPackPropsFromDoc } from './components/PhotoPack/docProps.js';
export { getScrollerPropsFromDoc } from './components/Scroller/docProps.js';

View file

@ -31,7 +31,7 @@
"src/**/*.js",
"src/**/*.ts",
"src/**/*.svelte",
"src/**/*.jsx",
"src/**/*.{jsx,tsx}",
"bin/**/*.{js,cjs}",
"*.ts",
"*.js",