wires/hypnagaga
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

update docs

Browse source
This commit is contained in:
hobbes7878 2025-04-20 12:13:11 +01:00
parent 9b72dbe431
commit aca5453b42
Failed to extract signature
20 changed files with 46 additions and 428 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
src/actions/cssVariables/cssVariables.mdx
View file

@ -11,14 +11,13 @@ An action you can use to easily set [CSS variables](https://developer.mozilla.or
<script>
import { cssVariables } from '@reuters-graphics/graphics-components';
export let height = 300;
export let textColour = 'red';
let { height = 300, textColour = 'red' } = $props();
// Create an object of variable names and CSS values...
$: variables = {
let variables = $derived({
height: height + 'px',
textColour: textColour,
};
});
</script>
<!-- Attach it to a parent element with the action -->

2
src/components/AdSlot/InlineAd.mdx
View file

@ -25,7 +25,7 @@ Add programmatic ads inline on your page.
<script>
import { InlineAd } from '@reuters-graphics/graphics-components';
export let embedded = false;
let { embedded = false } = $props();
</script>
{#each content.blocks as block}

2
src/components/AdSlot/SponsorshipAd.mdx
View file

@ -25,7 +25,7 @@ Add a sponsorship ad to your page.
<script>
import { SponsorshipAd } from '@reuters-graphics/graphics-components';
export let embedded = false;
let { embedded = false } = $props();
</script>
<!-- Check if in an embed context! -->

2
src/components/Article/Article.mdx
View file

@ -78,7 +78,7 @@ If you're not using our `Block` component, you can still inherit the column widt
```svelte
<script>
export let width = 'normal';
let { width = 'normal' } = $props();
</script>
<div class="my-special-container {width}">

1
src/components/Headline/demo/graphic.svelte
View file

@ -10,7 +10,6 @@
// @ts-ignore img
import chartXl from './graphic-xl.png';
// export let assetsPath = './';
let width = $state();
</script>

6
src/components/HeroHeadline/HeroHeadline.mdx
View file

@ -77,7 +77,7 @@ To customise styles, use CSS to target the class passed to `HeroHeadline`.
import { assets } from '$app/paths'; // 👈 If using in the Graphics Kit...
export let embedded = false; // 👈 If using in the Graphics Kit...
let { embedded = false } = $props(); // 👈 If using in the Graphics Kit...
</script>
<HeroHeadline
@ -164,7 +164,7 @@ To add a video as the hero, use the [Video](?path=/docs/components-multimedia-vi
import { HeroHeadline, Video } from '@reuters-graphics/graphics-components';
import { assets } from '$app/paths'; // 👈 If using in the Graphics Kit...
export let embedded = false; // 👈 If using in the Graphics Kit...
let { embedded = false } = $props(); // 👈 If using in the Graphics Kit...
</script>
<HeroHeadline
@ -226,7 +226,7 @@ To use a photo, graphic, video, etc. as an inline hero -- i.e., to make the hero
} from '@reuters-graphics/graphics-components';
import { assets } from '$app/paths'; // 👈 If using in the Graphics Kit...
export let embedded = false; // 👈 If using in the Graphics Kit...
let { embedded = false } = $props(); // 👈 If using in the Graphics Kit...
</script>
<!-- Set `stacked` to `false` -->

1
src/components/HeroHeadline/demo/graphics/crash.svelte
View file

@ -1,5 +1,4 @@
<script>
// export let assetsPath = './';
let width = $state();
// @ts-ignore img

3
src/components/PaddingReset/PaddingReset.mdx
View file

@ -36,8 +36,7 @@ You can add the padding conditionally by setting the `containerIsFluid` prop to
<script>
import { Block, PaddingReset } from '@reuters-graphics/graphics-components';
export let src = 'https://...';
export let width = 'fluid';
let { src = 'https://...', width = 'fluid' } = $props();
</script>
<Block {width}>

67
src/docs/contributing/component-guidelines.mdx
View file

@ -20,7 +20,7 @@ By default, component's are written in TypeScript, which adds robust type-checki
### 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.
Document props using [JSDoc comments](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html) and type props with TypeScript.
Here are a few examples:
@ -28,27 +28,16 @@ Here are a few examples:
```svelte
<script lang="ts">
/** Height of the component */
export let height: number = 250;
/** Text colour */
export let colour: string = 'blue';
</script>
```
interface Props {
/** Required text content */
text: string;
/** Optional height of the component */
height?: number;
/** Optional text colour */
colour?: string;
}
#### Documenting required props
```svelte
<script lang="ts">
/**
* Image source
* @required
*/
export let src: string;
/**
* AltText for the image
* @required
*/
export let altText: string;
let { text, height = 250, colour = 'blue' }: Props = $props();
</script>
```
@ -58,40 +47,22 @@ Here are a few examples:
<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[];
interface Props {
/** Array of people */
people: Person[];
/** Optional width of the component within the text well. */
width?: ContainerWidth;
}
let { people, width = 'normal' }: Props = $props();
</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
@ -148,7 +119,7 @@ Use [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_c
```svelte
<script>
export let textColour = '#333';
let { textColour = '#333' } = $props();
</script>
<div style="--textColour: {textColour};">

14
src/docs/contributing/quickstart.mdx
View file

@ -23,24 +23,14 @@ 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...
```
pnpm 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...
```
pnpm start
```
When you're ready to share your chart, commit your branch to GitHub, make a PR and we'll get it published!
When you're ready to share your component, commit your branch to GitHub, make a PR and we'll get it published!
```
git push origin my-chart
git push origin my-component
```

77
src/docs/contributing/story-recipes/basic-story.mdx
View file

@ -1,77 +0,0 @@
import { Meta } from '@storybook/blocks';
import { parameters } from '../../utils/docsPage.js';
<Meta
title="Contributing/Recipes: Basic story"
parameters={{ ...parameters }}
/>
# 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`.

BIN
src/docs/contributing/story-recipes/source-code.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 30 KiB

46
src/docs/contributing/story-recipes/story-with-custom-controls.mdx
View file

@ -1,46 +0,0 @@
import { Meta } from '@storybook/blocks';
import { parameters } from '../../utils/docsPage.js';
<Meta
title="Contributing/Recipes: Story with custom controls"
parameters={{ ...parameters }}
/>
# 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).

130
src/docs/contributing/story-recipes/story-with-custom-docs.mdx
View file

@ -1,130 +0,0 @@
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 }}
/>
# 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 }))}
/>
```

50
src/docs/contributing/story-recipes/story-with-media.mdx
View file

@ -1,50 +0,0 @@
import { Meta } from '@storybook/blocks';
import { parameters } from '../../utils/docsPage.js';
<Meta
title="Contributing/Recipes: Story with media"
parameters={{ ...parameters }}
/>
# 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',
}}
/>
```

11
src/docs/contributing/writing-component-stories.mdx
View file

@ -9,24 +9,23 @@ As well as writing your component, you should also document how to use it using
## 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.
Paraphrasing [Storybook's definition](https://storybook.js.org/docs/get-started/whats-a-story): 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:
To make a story page, you'll create a `*.stories.svelte` and a `*.mdx` file next to your component like this:
```
src/
components/
YourComponent/
YourComponent.mdx
YourComponent.svelte
YourComponent.stories.svelte
```
Your component's story page will then have at least one story that shows how it can be used.
The `*.stories.svelte` component is where you will define the stories or specific demos of your component. The `*.mdx` file is where you can write extended documentation about your component.
## 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.)
Read more about writing stories using the Svelte component story format (CSF) [here](https://github.com/storybookjs/addon-svelte-csf?tab=readme-ov-file#-usage) and writing accompanying MDX docs [here](https://storybook.js.org/docs/writing-docs/mdx).

35
src/docs/contributing/writing-docs-stories.mdx
View file

@ -1,35 +0,0 @@
import { Meta } from '@storybook/blocks';
import { parameters } from '../utils/docsPage.js';
<Meta title="Contributing/Writing docs pages" parameters={{ ...parameters }} />
# 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 }} />
# My docs page
Your docs TK...
```
From there, write whatever you need in markdown.

2
src/docs/guides/graphics-kit.mdx
View file

@ -30,5 +30,5 @@ In the Graphics Kit, that means you'll need to prefix relative paths with the sp
</script>
<!-- Use the assets module to prefix the path to your image. -->
<FeautrePhoto src={`${assets}/imgs/myImage.jpg`} />
<FeautrePhoto src="{assets}/imgs/myImage.jpg" />
```

16
src/docs/guides/svelte-components.mdx
View file

@ -19,9 +19,11 @@ A component is usually composed of several parts: JavaScript for managing data,
```svelte
<!-- JavaScript -->
<script>
export let imgSrc = 'https://reuters.com/image.jpg';
export let altText = 'A cat';
export let caption = 'Mousing all day is hard work ...';
let {
imgSrc = 'https://reuters.com/image.jpg',
altText = 'A cat',
caption = 'Mousing all day is hard work ...',
} = $props();
</script>
<!-- HTML -->
@ -47,11 +49,11 @@ A component is usually composed of several parts: JavaScript for managing data,
To use a component, you first need to import it. For example, below is a component called `Button.svelte`:
```svelte
<!-- Button.svelte -->
<script>
export let text = 'Click me';
let { text = 'Click me' } = $props();
</script>
<!-- Button.svelte -->
<button>{text}</button>
```
@ -131,8 +133,6 @@ The component's props are `src`, `altTtext`, `caption` and `width` and each show
## Next steps
To learn more about Svelte, you're not short of great tutorials. There are dozens of YouTube videos, online courses and articles to introduce you to more advanced features of the framework. Watch out for our own training courses on the Graphics Team to learn more about Svelte or JavaScript. But in a pinch, each desk has at least one developer who can help you through any problems as you're working with Svelte.
To learn more about Svelte, check out the [official interactive tutorial](https://svelte.dev/tutorial/svelte/welcome-to-svelte).
All are also welcome to join the "⚙️ Graphics Dev Group" channel in Teams, where we occasionally chat about code tips or tricks.
> **NOTE:** As of now, we are using version 4 Svelte syntax. We will soon upgrade to version 5, but for now, we recommend looking for older tutorials online and not the official guides for the latest version.

2
src/docs/intro.mdx
View file

@ -25,7 +25,7 @@ Svelte components, SCSS and more you can use in graphics projects.
pnpm i @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.
2. Checkout the [guides](?path=/docs/guides-using-these-docs--docs), if you haven't, or dive straight into the docs to start using components.
```svelte
<script>