diff --git a/src/components/Article/Article.mdx b/src/components/Article/Article.mdx index ad6935ce..5c038bd2 100644 --- a/src/components/Article/Article.mdx +++ b/src/components/Article/Article.mdx @@ -6,9 +6,9 @@ import * as ArticleStories from './Article.stories.svelte'; # Article -The `Article` component contains all the content of our story and also establishes the dimensions of our article well, the default central trunk of our page layout. +The `Article` component contains all the contents of our story. -> 📌 In most cases, **you won't need to mess with the `Article` component** because it's already included in our rigs for you! +> 📌 In most cases, **you don't need to mess with the `Article` component** because it's already set up in the Graphics Kit. ```svelte
- +
``` -## Custom well widths +## Custom column widths -The `Article` component also creates several column dimensions inside our article well. The standard widths of columns follow a basic class scheme: +The `Article` component also establishes the widths of columns that contain individual sections of the story, such as text, photos, and charts. The default column widths follow a basic class scheme: -- `narrower` A bit narrower than narrow... -- `narrow` A bit narrower than the text column -- `normal` **The main width of the body text column** -- `wide` A bit wider than the text column +- `narrower` The narrowest... +- `narrow` A bit narrower than the default body text column +- `normal` **The default width of the body text column** +- `wide` A bit wider - `wider` A bit wider than wide... - `widest` Edge-to-edge, but _excluding_ the left and right padding on `Article` - `fluid` Fully edge-to-edge -When combined with the `Block` component, you can set custom column widths by passing an object to the `columnWidths` prop with pixel values for the `narrower`, `narrow`, `normal`, `wide` and `wider` column widths. +You can set custom column widths by passing an object to the `columnWidths` prop with pixel values for the `narrower`, `narrow`, `normal`, `wide` and `wider` classes. These can then be used by the `Block` component or other elements housed inside `
`. -> **For most pages, you shouldn't customise the column widths.** Other tools, like our AI templates, use our default column widths, so customising those widths here has downstream consequences for graphics made outside your code. The main exception is SREP stories. +> **For most Graphics Kit pages, you shouldn't customise the column widths.** Other Reuters tools, like our AI templates, use our default column widths, so customising those widths here has downstream consequences for graphics made outside Graphics Kit. The main exception is SREP stories. ```svelte +
+ @@ -58,11 +60,11 @@ When combined with the `Block` component, you can set custom column widths by pa
``` -If you're not using our `Block` component, you can still inherit the column widths from `Article` to create your own custom container with the article well dimensions by using [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) like this: +If you're not using our `Block` component, you can still inherit the column widths from `Article` and create your own custom containers by using [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) like this: ```svelte
- +
``` -... or you can make your component entirely configurable within the article well doing something like this: +... or you can make your column widths entirely configurable by adding classes and manually specifying widths: ```svelte
- +
``` -Here's an example of how custom\* `columnWidths` can be used to change the article well columns: +Here's an example of how custom `columnWidths` can be used to change column widths: + + diff --git a/src/components/Article/Article.stories.svelte b/src/components/Article/Article.stories.svelte index c0683455..79d69c36 100644 --- a/src/components/Article/Article.stories.svelte +++ b/src/components/Article/Article.stories.svelte @@ -2,36 +2,25 @@ import { defineMeta } from '@storybook/addon-svelte-csf'; import Block from '../Block/Block.svelte'; import Article from './Article.svelte'; - // @ts-ignore raw - import customWellWidthsDocs from './stories/docs/customWellWidths.md?raw'; - - import { withComponentDocs, withStoryDocs } from '$docs/utils/withParams.js'; const { Story } = defineMeta({ - title: 'Components/Page Layout/Article', + title: 'Components/Page layout/Article', component: Article, }); - - - +
-
Article container
+
Article well
⇤15px padding
 - + +

Default column widths

+
narrower @@ -43,22 +32,23 @@ fluid
+

Custom column widths

- narrower* - narrow* - normal* - wide* - wider* + narrower + narrow + normal + wide + wider widest fluid
@@ -66,6 +56,13 @@ -``` - -... or you can make your component entirely configurable within the article well doing something like this: - -```svelte - - -
- -
- - -``` - -Here's an example of how custom\* `columnWidths` can be used to change the article well columns: diff --git a/src/components/Byline/Byline.mdx b/src/components/Byline/Byline.mdx index dbff6ad5..3f812644 100644 --- a/src/components/Byline/Byline.mdx +++ b/src/components/Byline/Byline.mdx @@ -58,7 +58,7 @@ updateTime: 2021-09-12T12:57:00.000Z -## Cutomisation +## Custom byline, published and updated datelines Use [snippets](https://svelte.dev/docs/svelte/snippet) to customise the byline, published and updated datelines. @@ -82,3 +82,25 @@ Use [snippets](https://svelte.dev/docs/svelte/snippet) to customise the byline, ``` + +## Custom author page + +By default, the `Byline` component will hyperlink each author's byline to their Reuters.com page, formatted `https://www.reuters.com/authors/{author-slug}/`. + +To hyperlink to different pages or email addresses, pass a custom function to the `getAuthorPage` prop. + +```svelte + + { + return `mailto:${author.replace(' ', '')}@example.com`; + }} +/> + +``` + + +```` diff --git a/src/components/Byline/Byline.stories.svelte b/src/components/Byline/Byline.stories.svelte index c0cf796a..33705d5a 100644 --- a/src/components/Byline/Byline.stories.svelte +++ b/src/components/Byline/Byline.stories.svelte @@ -18,7 +18,6 @@ + + { + return `mailto:${author.replace(' ', '')}@example.com`; + }, + }} +/> diff --git a/src/components/Byline/Byline.svelte b/src/components/Byline/Byline.svelte index 37050af2..4d932679 100644 --- a/src/components/Byline/Byline.svelte +++ b/src/components/Byline/Byline.svelte @@ -1,8 +1,8 @@ + + +``` + + diff --git a/src/components/DocumentCloud/DocumentCloud.stories.svelte b/src/components/DocumentCloud/DocumentCloud.stories.svelte index 7a111585..22f69e6d 100644 --- a/src/components/DocumentCloud/DocumentCloud.stories.svelte +++ b/src/components/DocumentCloud/DocumentCloud.stories.svelte @@ -1,38 +1,23 @@ - - - - diff --git a/src/components/DocumentCloud/DocumentCloud.svelte b/src/components/DocumentCloud/DocumentCloud.svelte index 195c4c8a..01a86cc6 100644 --- a/src/components/DocumentCloud/DocumentCloud.svelte +++ b/src/components/DocumentCloud/DocumentCloud.svelte @@ -1,43 +1,41 @@ - diff --git a/src/components/DocumentCloud/stories/docs/component.md b/src/components/DocumentCloud/stories/docs/component.md deleted file mode 100644 index 6b52ec2a..00000000 --- a/src/components/DocumentCloud/stories/docs/component.md +++ /dev/null @@ -1,17 +0,0 @@ -Embed a document hosted by [DocumentCloud](https://documentcloud.org) - ---- - -The document must have its access level set to public before it can be embedded. The `slug` argument can be found after the final slash in the document's URL. For instance, the document included in the example is found at [documentcloud.org/documents/3259984-Trump-Intelligence-Allegations](https://www.documentcloud.org/documents/3259984-Trump-Intelligence-Allegations). The slug is "3259984-Trump-Intelligence-Allegations". - -```svelte - - - -``` diff --git a/src/components/FeaturePhoto/FeaturePhoto.mdx b/src/components/FeaturePhoto/FeaturePhoto.mdx new file mode 100644 index 00000000..9ea5a3af --- /dev/null +++ b/src/components/FeaturePhoto/FeaturePhoto.mdx @@ -0,0 +1,72 @@ +import { Meta, Canvas } from '@storybook/blocks'; + +import * as FeaturePhotoStories from './FeaturePhoto.stories.svelte'; + + + +# FeaturePhoto + +The `FeaturePhoto` component adds a full-width photo. + +```svelte + + + +``` + + + +## Using with ArchieML docs + +With the Graphics Kit, you'll likely get your text value from an ArchieML doc... + +```yaml +# ArchieML doc +[blocks] + +type: photo +width: normal +src: images/shark.jpg +altText: The king of the sea +caption: Carcharodon carcharias - REUTERS + +[] +``` + +... which you'll parse out of a ArchieML block object before passing to the `FeaturePhoto` component. + +```svelte + + + +{#each content.blocks as block} + {#if block.Type === 'text'} + + {:else if block.type === 'photo'} + + {/if} +{/each} +``` + +## Missing alt text + +`altText` is required in this component. If your photo is missing it, a small red text box will overlay the image. + + diff --git a/src/components/FeaturePhoto/FeaturePhoto.stories.svelte b/src/components/FeaturePhoto/FeaturePhoto.stories.svelte index 07b53afb..55769963 100644 --- a/src/components/FeaturePhoto/FeaturePhoto.stories.svelte +++ b/src/components/FeaturePhoto/FeaturePhoto.stories.svelte @@ -1,26 +1,10 @@ - - - - - diff --git a/src/components/FeaturePhoto/FeaturePhoto.svelte b/src/components/FeaturePhoto/FeaturePhoto.svelte index 0ff0b7f6..a750d23d 100644 --- a/src/components/FeaturePhoto/FeaturePhoto.svelte +++ b/src/components/FeaturePhoto/FeaturePhoto.svelte @@ -1,75 +1,89 @@ - - -{#each content.blocks as block} - {#if block.Type === 'text'} - - - {:else if block.type === 'photo'} - - - - {/if} -{/each} -``` diff --git a/src/components/FeaturePhoto/stories/docs/component.md b/src/components/FeaturePhoto/stories/docs/component.md deleted file mode 100644 index 846cfcf9..00000000 --- a/src/components/FeaturePhoto/stories/docs/component.md +++ /dev/null @@ -1,16 +0,0 @@ -A full-width photo inside the text well. - -```svelte - - - -``` diff --git a/src/components/FeaturePhoto/stories/docs/missingAltText.md b/src/components/FeaturePhoto/stories/docs/missingAltText.md deleted file mode 100644 index 48016d3e..00000000 --- a/src/components/FeaturePhoto/stories/docs/missingAltText.md +++ /dev/null @@ -1 +0,0 @@ -If your photo is missing `altText` a small warning will overlay the image. diff --git a/src/components/GraphicBlock/AriaHidden.svelte b/src/components/GraphicBlock/AriaHidden.svelte deleted file mode 100644 index 4379590c..00000000 --- a/src/components/GraphicBlock/AriaHidden.svelte +++ /dev/null @@ -1,20 +0,0 @@ - - -{#if hidden} - -{:else} - {@render children?.()} -{/if} diff --git a/src/components/GraphicBlock/GraphicBlock.mdx b/src/components/GraphicBlock/GraphicBlock.mdx new file mode 100644 index 00000000..10ef9fea --- /dev/null +++ b/src/components/GraphicBlock/GraphicBlock.mdx @@ -0,0 +1,215 @@ +import { Meta, Canvas } from '@storybook/blocks'; + +import * as GraphicBlockStories from './GraphicBlock.stories.svelte'; + + + +# GraphicBlock + +The `GraphicBlock` component is a special derivative of the [Block](?path=/docs/components-page-layout-block--docs) component that wraps around your graphic. It also adds a title, description, notes and other text elements. + +Many other Reuters Graphics components use `GraphicBlock` to wrap graphics with styled text. + +```svelte + + + + +
+ +``` + + + +## Using with ai2svelte and ArchieML docs + +The `GraphicBlock` component is built to handle [ai2svelte](https://github.com/reuters-graphics/ai2svelte) graphics in Graphics Kit. + +You'll likely get your text value from an ArchieML doc... + +```yaml +# ArchieML doc +[blocks] +type: ai-graphic +width: normal +chart: AiMap # IMPORTANT: This must match the name of the ai2svelte chart you import in App.svelte +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 +altText: A map that shows the shake intensity of the earthquake, which was worst in central Haiti. +:end +[] +``` + +... which you'll parse out of a ArchieML block object before passing to the `GraphicBlock` component. + +To pass your ai2svelte graphic into `GraphicBlock` component, import your ai2svelte graphic at the top of `App.svelte` and add it to the `aiCharts` object. + +> **Important❗:** Make sure that the value for `chart` in the ArchieML doc matches the name of the ai2svelte file imported in `App.svelte`. + +```svelte + + + + +{#each content.blocks as block} + {#if block.type === 'ai-graphic'} + {#if !aiCharts[block.chart]} + + + {:else} + + {@const AiChart = aiCharts[block.chart]} + + + + + {/if} + {/if} +{/each} +``` + + + +## Custom text + +You can override the default styles for title and notes by making your own custom elements and passing them as `title` and `notes` [snippets](https://svelte.dev/docs/svelte/snippet) instead of as strings: + +```svelte + + + {#snippet title()} +
My smaller title
+ {/snippet} + + +
+ + + {#snippet notes()} + + {/snippet} + +``` + + + +## ARIA descriptions + +If the text in your chart isn't easily read by screen readers — for example, a map with annotations that wouldn't make sense without the visual — add an `ariaDescription` that describes the chart. + +The `ariaDescription` string will be processed as markdown, so you can add multiple paragraphs, links, headers, etc. in markdown. + +> **Note:** When you set an `ariaDescription`, your graphic will be automatically wrapped in a div with [aria-hidden="true"](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden), which tells screen readers to read the hidden ARIA description and skip the text in the graphic. + +```svelte + + + + +``` + + + +## Custom ARIA descriptions + +Sometimes, instead of a simple sentence, we want to provide a data table or something more complex as an ARIA description. To do this, pass the custom elements as an `ariaDescription` [snippet](https://svelte.dev/docs/svelte/snippet) instead of as a string, as in the [example above](?path=/docs/components-graphics-graphicblock--docs#aria-descriptions). + +[Read this](https://accessibility.psu.edu/images/charts/) for more information on using screen reader data tables for charts. + +> **Note:** The `customAria` snippet will override the `ariaDescription` and will also hide the text in your graphic from screen readers. + +```svelte + + + + + + {#snippet ariaDescription()} +

+ A shakemap shows the intensity of the 7.2-magnitude earthquake that struck + Haiti at 8:29 a.m. EST, Aug. 14, 2021. +

+ + + + + + + + + + + + + + + +
CityFelt shake strength
Les CayesVery strong
JeremieStrong
+ {/snippet} + + + + +``` + + diff --git a/src/components/GraphicBlock/GraphicBlock.stories.svelte b/src/components/GraphicBlock/GraphicBlock.stories.svelte index 6923b855..f19268eb 100644 --- a/src/components/GraphicBlock/GraphicBlock.stories.svelte +++ b/src/components/GraphicBlock/GraphicBlock.stories.svelte @@ -1,23 +1,10 @@ - - - - - + + +
+ placeholder +
+ + + + - - - {#snippet title()} -
-
My smaller title
-
- {/snippet} + +
- placeholder + placeholder
+ + {#snippet title()} +
My smaller title
+ {/snippet} + {#snippet notes()} -