diff --git a/src/actions/cssVariables/cssVariables.mdx b/src/actions/cssVariables/cssVariables.mdx index fb5f97a9..c67b6353 100644 --- a/src/actions/cssVariables/cssVariables.mdx +++ b/src/actions/cssVariables/cssVariables.mdx @@ -11,14 +11,13 @@ An action you can use to easily set [CSS variables](https://developer.mozilla.or diff --git a/src/components/AdSlot/InlineAd.mdx b/src/components/AdSlot/InlineAd.mdx index 5be76a80..ef65d15d 100644 --- a/src/components/AdSlot/InlineAd.mdx +++ b/src/components/AdSlot/InlineAd.mdx @@ -25,7 +25,7 @@ Add programmatic ads inline on your page. {#each content.blocks as block} diff --git a/src/components/AdSlot/SponsorshipAd.mdx b/src/components/AdSlot/SponsorshipAd.mdx index 12f41b49..78eb0cdf 100644 --- a/src/components/AdSlot/SponsorshipAd.mdx +++ b/src/components/AdSlot/SponsorshipAd.mdx @@ -25,7 +25,7 @@ Add a sponsorship ad to your page. diff --git a/src/components/Article/Article.mdx b/src/components/Article/Article.mdx index b5defaa4..be645601 100644 --- a/src/components/Article/Article.mdx +++ b/src/components/Article/Article.mdx @@ -78,7 +78,7 @@ If you're not using our `Block` component, you can still inherit the column widt ```svelte
diff --git a/src/components/Headline/demo/graphic.svelte b/src/components/Headline/demo/graphic.svelte index b202a85d..41afe758 100644 --- a/src/components/Headline/demo/graphic.svelte +++ b/src/components/Headline/demo/graphic.svelte @@ -10,7 +10,6 @@ // @ts-ignore img import chartXl from './graphic-xl.png'; - // export let assetsPath = './'; let width = $state(); diff --git a/src/components/HeroHeadline/HeroHeadline.mdx b/src/components/HeroHeadline/HeroHeadline.mdx index 07570b1e..b141ac9e 100644 --- a/src/components/HeroHeadline/HeroHeadline.mdx +++ b/src/components/HeroHeadline/HeroHeadline.mdx @@ -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... diff --git a/src/components/HeroHeadline/demo/graphics/crash.svelte b/src/components/HeroHeadline/demo/graphics/crash.svelte index ea7ca990..9f2ac0fb 100644 --- a/src/components/HeroHeadline/demo/graphics/crash.svelte +++ b/src/components/HeroHeadline/demo/graphics/crash.svelte @@ -1,5 +1,4 @@ diff --git a/src/docs/contributing/component-guidelines.mdx b/src/docs/contributing/component-guidelines.mdx index a63a6cb8..ce1f0aa7 100644 --- a/src/docs/contributing/component-guidelines.mdx +++ b/src/docs/contributing/component-guidelines.mdx @@ -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 -``` + interface Props { + /** Required text content */ + text: string; + /** Optional height of the component */ + height?: number; + /** Optional text colour */ + colour?: string; + } -#### Documenting required props - -```svelte - ``` @@ -58,40 +47,22 @@ Here are a few examples: ``` -#### 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
diff --git a/src/docs/contributing/quickstart.mdx b/src/docs/contributing/quickstart.mdx index cc42151d..d382b0cd 100644 --- a/src/docs/contributing/quickstart.mdx +++ b/src/docs/contributing/quickstart.mdx @@ -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 ``` diff --git a/src/docs/contributing/story-recipes/basic-story.mdx b/src/docs/contributing/story-recipes/basic-story.mdx deleted file mode 100644 index 4dab01bb..00000000 --- a/src/docs/contributing/story-recipes/basic-story.mdx +++ /dev/null @@ -1,77 +0,0 @@ -import { Meta } from '@storybook/blocks'; -import { parameters } from '../../utils/docsPage.js'; - - - -# 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 - - - - - - - - -``` - -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 - -``` - -You can define additional stories with _different_ args to show how your component will render with different props like: - -```svelte - - - - - -``` - -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 - - - -``` - -> **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`. diff --git a/src/docs/contributing/story-recipes/source-code.png b/src/docs/contributing/story-recipes/source-code.png deleted file mode 100644 index e5cccd4d..00000000 Binary files a/src/docs/contributing/story-recipes/source-code.png and /dev/null differ diff --git a/src/docs/contributing/story-recipes/story-with-custom-controls.mdx b/src/docs/contributing/story-recipes/story-with-custom-controls.mdx deleted file mode 100644 index e279dc16..00000000 --- a/src/docs/contributing/story-recipes/story-with-custom-controls.mdx +++ /dev/null @@ -1,46 +0,0 @@ -import { Meta } from '@storybook/blocks'; -import { parameters } from '../../utils/docsPage.js'; - - - -# 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 - - - - - - - - -``` - -Read more about Storybook's custom controls options [here](https://storybook.js.org/docs/svelte/essentials/controls). diff --git a/src/docs/contributing/story-recipes/story-with-custom-docs.mdx b/src/docs/contributing/story-recipes/story-with-custom-docs.mdx deleted file mode 100644 index 24a3b1f1..00000000 --- a/src/docs/contributing/story-recipes/story-with-custom-docs.mdx +++ /dev/null @@ -1,130 +0,0 @@ -import { Meta } from '@storybook/blocks'; -import { parameters } from '../../utils/docsPage.js'; - -import SourceCodeImg from './source-code.png'; - -import '../../docStyles.scss'; - - - -# 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 - - - - - - - - - - - - -``` - -## Customising copyable source code - -If you need to, you can customise the "Copy" source code available below a component story's iframe window. - - - -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 - - - - - - - - -``` - -> **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 - - - -``` diff --git a/src/docs/contributing/story-recipes/story-with-media.mdx b/src/docs/contributing/story-recipes/story-with-media.mdx deleted file mode 100644 index 1ac08b86..00000000 --- a/src/docs/contributing/story-recipes/story-with-media.mdx +++ /dev/null @@ -1,50 +0,0 @@ -import { Meta } from '@storybook/blocks'; -import { parameters } from '../../utils/docsPage.js'; - - - -# 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 - - - - - - - - -``` diff --git a/src/docs/contributing/writing-component-stories.mdx b/src/docs/contributing/writing-component-stories.mdx index 0c345cf1..f5bc3d6a 100644 --- a/src/docs/contributing/writing-component-stories.mdx +++ b/src/docs/contributing/writing-component-stories.mdx @@ -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). diff --git a/src/docs/contributing/writing-docs-stories.mdx b/src/docs/contributing/writing-docs-stories.mdx deleted file mode 100644 index 85bea3f6..00000000 --- a/src/docs/contributing/writing-docs-stories.mdx +++ /dev/null @@ -1,35 +0,0 @@ -import { Meta } from '@storybook/blocks'; -import { parameters } from '../utils/docsPage.js'; - - - -# 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'; - - - -# My docs page - -Your docs TK... -``` - -From there, write whatever you need in markdown. diff --git a/src/docs/guides/graphics-kit.mdx b/src/docs/guides/graphics-kit.mdx index 93d4ceec..dd24c69b 100644 --- a/src/docs/guides/graphics-kit.mdx +++ b/src/docs/guides/graphics-kit.mdx @@ -30,5 +30,5 @@ In the Graphics Kit, that means you'll need to prefix relative paths with the sp - + ``` diff --git a/src/docs/guides/svelte-components.mdx b/src/docs/guides/svelte-components.mdx index 5afd7783..44ee14dd 100644 --- a/src/docs/guides/svelte-components.mdx +++ b/src/docs/guides/svelte-components.mdx @@ -19,9 +19,11 @@ A component is usually composed of several parts: JavaScript for managing data, ```svelte @@ -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 + - ``` @@ -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. diff --git a/src/docs/intro.mdx b/src/docs/intro.mdx index 7ecbe52a..b6866704 100644 --- a/src/docs/intro.mdx +++ b/src/docs/intro.mdx @@ -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