@reuters-graphics/graphics-components 3.9.0 → 3.10.1

package/dist/llm-docs/components/Block.md

@@ -0,0 +1,211 @@
+# Block
+
+**Category:** Components/Page layout/Block
+
+**Import:** `import { Block } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `children` | `Snippet` | — | ✓ | Content that goes inside `<Block>` |
+| `width` | `ContainerWidth` | `'normal'` |  | Width of the block within the article well. Options: `narrower`, `narrow`, `normal`, `wide`, `wider`, `widest`, `fluid` |
+| `id` | `string` | `''` |  | Add an id to the block tag to target it with custom CSS. |
+| `class` | `string` | `''` |  | Add custom classes to the block tag to target it with custom CSS. |
+| `snap` | `boolean` | `false` |  | Snap block to column widths, rather than fluidly resizing them. |
+| `role` | `string` | — |  | ARIA [role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) for the block |
+| `ariaLabel` | `string` | — |  | ARIA [label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) for the block |
+
+## Examples
+
+### Demo
+
+```svelte
+<Article id="block-demo-article">
+  <div class="article-boundaries">
+    <div class="label">Article</div>
+    <Block>
+      <div class="label">Block</div>
+    </Block>
+  </div>
+</Article>
+```
+
+### Custom layout
+
+```svelte
+<Block width="fluid">
+  <!-- Enter bootstrap grid! -->
+  <div id="block-flex-example">
+    <div class="row">
+      <div class="col">Column</div>
+      <div class="col-6">Column</div>
+      <div class="col">Column</div>
+    </div>
+    <div class="row">
+      <div class="col">Column</div>
+      <div class="col">Column</div>
+    </div>
+  </div>
+</Block>
+```
+
+### Snap widths
+
+```svelte
+<Article id="block-demo-article">
+  <div class="article-boundaries">
+    <div class="label">Article</div>
+    <h4>snap widths</h4>
+    <Block snap={true}>
+      <div class="label">Block</div>
+    </Block>
+  </div>
+</Article>
+```
+
+### Snap and skip widths
+
+```svelte
+<Article id="block-demo-article">
+  <div class="article-boundaries">
+    <div class="label">Article</div>
+    <h4>Regular layout</h4>
+
+    <Block width="narrower" snap={true} class="block-snap-widths-demo">
+      narrower
+    </Block>
+    <Block width="narrow" snap={true} class="block-snap-widths-demo">
+      narrow
+    </Block>
+    <Block width="normal" snap={true} class="block-snap-widths-demo">
+      normal
+    </Block>
+    <Block width="wide" snap={true} class="block-snap-widths-demo">
+      wide
+    </Block>
+    <Block width="wider" snap={true} class="block-snap-widths-demo">
+      wider
+    </Block>
+
+    <h4>with snap and skip</h4>
+    <Block width="narrower" snap={true} class="block-snap-widths-demo even">
+      narrower
+    </Block>
+    <Block width="narrow" snap={true} class="block-snap-widths-demo even">
+      narrow
+    </Block>
+    <Block
+      width="normal"
+      snap={true}
+      class="block-snap-widths-demo even skip-narrow"
+    >
+      normal.skip-narrow
+    </Block>
+    <Block
+      width="wide"
+      snap={true}
+      class="block-snap-widths-demo even skip-normal skip-narrow"
+    >
+      wide.skip-normal.skip-narrow
+    </Block>
+    <Block
+      width="wider"
+      snap={true}
+      class="block-snap-widths-demo even skip-wide"
+    >
+      wider.skip-wide
+    </Block>
+  </div>
+</Article>
+```
+
+## Documentation
+
+# Block
+
+The `Block` component is the basic building block of pages, a responsive container that wraps around each section of your piece.
+
+Blocks are stacked vertically within the well created by the [Article](./?path=/docs/components-page-layout-article--docs) component. They can have different widths on larger screens depending on the `width` prop.
+
+> 📌 Many of our other components already use the `Block` component internally. You'll usually only need to use it yourself if you're making something custom.
+
+```svelte
+<script>
+  import { Block } from '@reuters-graphics/graphics-components';
+</script>
+
+<Block>
+  <!-- Contents for this block goes here -->
+</Block>
+```
+
+## Custom layouts
+
+Our article well is designed to provide a basic responsive layout for you, but it also lets you customise.
+
+The radical but easiest way to do this is to create a `Block` with a `fluid` width -- which basically cancels out the article well dimensions -- and then code whatever you need from scratch or with another framework.
+
+The demo below does exactly that to create an edge-to-edge grid with [flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/).
+
+```svelte
+<Block width="fluid">
+  <div class="my-radical-container">
+    <!-- Now, you have full control over layout! -->
+  </div>
+</Block>
+```
+
+## Snap widths
+
+Normally, `Block` containers resize fluidly below the original `width`. Sometimes, though, you may want the container to snap to the next breakpoint -- for example, if you have a static graphic that looks fine at the set block breakpoints, but isn't so great at widths inbetween.
+
+You can use the `snap` prop to force the container to snap to each block width successively as the window sizes down.
+
+```svelte
+<Block width="wider" snap={true}>
+  <!-- Contents for this block -->
+</Block>
+```
+
+If you want to skip certain block widths entirely, you can add one or more class of `skip-{block width class}` to the `Block`.
+
+> **NOTE:** The snap width breakpoints only work on `Block` components with widths `wider` and below. `widest` and `fluid` are both **always** fluid, since they go edge-to-edge.
+
+```svelte
+<!-- Will skip wide and go straight to normal column width on resize. -->
+<Block width="wider" snap={true} class="skip-wide">
+  <!-- Contents for this block -->
+</Block>
+```
+
+This is probably easier to see in action than explain in words, so [resize the demo](./?path=/docs/components-page-layout-block--snap-skip-widths) to get a better picture of how it all works.
+
+## Using with custom column widths
+
+Snap width breakpoints are hard-coded to the default article well column widths, so if you set custom `columnWidths` on the [Article](./?path=/docs/components-page-layout-article--docs) component (**rare!**), you need to do a littie work to use this functionality.
+
+Luckily, it's still pretty easy. Just add a `cls` or `id` to your `Block` so you can target it with some custom SCSS. Then define a few SCSS variables corresponding to your custom column widths, and use the `block-snap-widths` SCSS mixin to get the same functionality at your custom breakpoints.
+
+```svelte
+<Block width="wider" snap={true} class="custom-blocks">
+  <!-- Contents for this block -->
+</Block>
+
+<style lang="scss">
+  // Define custom column widths
+  $column-width-narrower: 310px;
+  $column-width-narrow: 450px;
+  $column-width-normal: 600px;
+  $column-width-wide: 860px;
+  $column-width-wider: 1400px;
+
+  @use '@reuters-graphics/graphics-components/scss/mixins' as mixins;
+
+  :global {
+    div.custom-blocks {
+      @include mixins.block-snap-widths; // Use the `block-snap-widths` mixin
+    }
+  }
+</style>
+```

package/dist/llm-docs/components/BlogPost.md

@@ -0,0 +1,68 @@
+# BlogPost
+
+**Category:** Components/Blog/BlogPost
+
+**Import:** `import { BlogPost } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `title` | `string` | `'Reuters Graphics blog post'` |  | Title of the blog post |
+| `slugTitle` | `string` | `'Reuters Graphics blog post'` |  | A sluggable title of the blog post.  **Important:** Do not change this title after publishing the post. Changes will break published links to the post. |
+| `base` | `string` | `''` |  | Base path prepended to the copied URL, e.g. "/graphics", usually gotten from base store in SvelteKit. |
+| `authors` | `string[]` | `[]` |  | Array of author names, which will be slugified to create links to Reuters author pages |
+| `publishTime` | `string` | `''` |  | Publish time as a datetime string. |
+| `updateTime` | `string` | `''` |  | Update time as a datetime string. |
+| `id` | `string` | `''` |  | Add an id to target post headline with custom CSS. |
+| `cls` | `string` | `''` |  | Add extra classes to target post headline with custom CSS. |
+| `isLastPost` | `boolean` | `false` |  | If the post is the last on the page, remove the dividing rule used to separate posts. |
+| `children` | `import('svelte').Snippet` | — |  | — |
+
+## Examples
+
+### Demo
+
+```svelte
+<BlogPost
+  title="Iran fires ballistic missiles at Israel in major escalation"
+  slugTitle="Iran fires ballistic missiles at Israel in major escalation"
+  authors={['John Smith', 'Jane Doe']}
+  publishTime="2024-10-01T18:30:00Z"
+  updateTime="2024-10-01T21:45:00Z"
+  base=""
+>
+  <BodyText
+    text="Iran launched a barrage of ballistic missiles at Israel on Tuesday in its first direct attack on Israeli territory, marking a significant escalation in the conflict gripping the Middle East."
+  />
+  <BodyText
+    text="The attack, which Iran said was in retaliation for Israeli strikes that killed senior Hezbollah and Hamas leaders, prompted Israel and the United States to vow a response."
+  />
+</BlogPost>
+```
+
+## Documentation
+
+# BlogPost
+
+The `BlogPost` component renders a single entry in a graphics blog page, including a headline, dateline, authors and a divider. Body content is passed as children.
+
+```svelte
+<script>
+  import { BlogPost } from '@reuters-graphics/graphics-components';
+  import { base } from '$app/paths';
+</script>
+
+<BlogPost
+  title="Iran fires ballistic missiles at Israel in major escalation"
+  slugTitle="Iran fires ballistic missiles at Israel in major escalation"
+  authors={['John Smith', 'Jane Doe']}
+  publishTime="2024-10-01T18:30:00Z"
+  updateTime="2024-10-01T21:45:00Z"
+  {base}
+>
+  <!-- Post body content goes here -->
+</BlogPost>
+```
+
+> **Important:** Do not change `slugTitle` after publishing. It is used to generate the post's anchor link — changing it will break any published links to the post.

package/dist/llm-docs/components/BlogTOC.md

@@ -0,0 +1,91 @@
+# BlogTOC
+
+**Category:** Components/Blog/BlogTOC
+
+**Import:** `import { BlogTOC } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `posts` | `Post[]` | — | ✓ | — |
+| `base` | `string` | `''` |  | Base path prepended to post links, e.g. "/graphics". |
+| `label` | `string` | `'Show all articles'` |  | The label for the table of contents toggle button. |
+| `maxHeight` | `number` | `300` |  | The maximum height of the table of contents list in pixels. |
+
+## Examples
+
+### Demo
+
+```svelte
+<Headline
+  section="Graphics"
+  hed="Maps of the Iran crisis"
+  hedSize="big"
+  width="normal"
+  class="mb-2"
+/>
+
+<ClockWall
+  cities={[
+    { name: 'Tehran', tzIdentifier: 'Asia/Tehran' },
+    { name: 'Tel Aviv', tzIdentifier: 'Asia/Tel_Aviv' },
+    { name: 'Washington D.C.', tzIdentifier: 'America/New_York' },
+  ]}
+/>
+
+<BlogTOC {posts} base="" />
+
+<BlogPost
+  title="Iran fires ballistic missiles at Israel in major escalation"
+  slugTitle="Iran fires ballistic missiles at Israel in major escalation"
+  authors={['John Smith', 'Jane Doe']}
+  publishTime="2024-10-01T18:30:00Z"
+  updateTime="2024-10-01T21:45:00Z"
+  base=""
+>
+  <BodyText
+    text="Iran launched a barrage of ballistic missiles at Israel on Tuesday in its first direct attack on Israeli territory, marking a significant escalation in the conflict gripping the Middle East."
+  />
+  <BodyText
+    text="The attack, which Iran said was in retaliation for Israeli strikes that killed senior Hezbollah and Hamas leaders, prompted Israel and the United States to vow a response."
+  />
+</BlogPost>
+```
+
+## Documentation
+
+# BlogTOC
+
+The `BlogTOC` component renders a collapsible table of contents for a graphics blog page, listing all posts sorted chronologically. It only renders when there are two or more posts.
+
+```svelte
+<script>
+  import { BlogTOC } from '@reuters-graphics/graphics-components';
+  import { base } from '$app/paths';
+</script>
+
+<BlogTOC
+  posts={[
+    {
+      title: 'Iran fires ballistic missiles at Israel',
+      slugTitle: 'Iran fires ballistic missiles at Israel',
+      publishTime: '2024-10-01T18:30:00Z',
+    },
+    {
+      title: 'Israel vows response',
+      slugTitle: 'Israel vows response',
+      publishTime: '2024-10-02T09:15:00Z',
+    },
+  ]}
+  {base}
+/>
+```
+
+The `base` prop should be set to your SvelteKit `base` path (e.g. `"/graphics"`) so that post links resolve correctly.
+
+Each post in the `posts` array must have:
+
+- `title` — the display title
+- `slugTitle` — used to generate the anchor link; **do not change after publishing**
+- `publishTime` — an ISO datetime string used for sorting and the dateline

package/dist/llm-docs/components/BodyText.md

@@ -0,0 +1,143 @@
+# BodyText
+
+**Category:** Components/Text elements/BodyText
+
+**Import:** `import { BodyText } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `text` | `string` | — | ✓ | A markdown text string. |
+| `class` | `string` | `''` |  | Add a class to target with SCSS. |
+| `id` | `string` | `''` |  | Add an id to the block tag to target it with custom CSS. |
+
+## Examples
+
+### Demo
+
+```svelte
+<BodyText text={/* value — see Props/Types for full type */} />
+```
+
+### Typography sample
+
+```svelte
+<BodyText
+  class="body-text-typography-example-story"
+  text={/* value — see Props/Types for full type */}
+/>
+```
+
+### Custom styles
+
+```svelte
+<BodyText
+  class="body-text-custom-styles-story"
+  text="Venison shoulder <span class="highlight">ham hock</span> ham leberkas."
+/>
+```
+
+## Documentation
+
+# BodyText
+
+The `BodyText` component creates the main text of your page. You can pass the `text` prop a [markdown-formatted](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) string, which will be parsed into paragraphs, headers, lists, links, blockquotes and other markdown-supported elements.
+
+```svelte
+<script>
+  import { BodyText } from '@reuters-graphics/graphics-components';
+
+  const markdownText = `Bacon ipsum **dolor amet** cow tongue tri-tip.
+  
+Biltong turducken ground round kevin [hamburger turkey](https://reuters.com) pig.
+
+- Steak
+- [Pork chop](https://www.google.com)
+- Fillet
+  
+Venison shoulder *ham hock ham leberkas*. Flank beef ribs fatback, jerky meatball ham hock.`;
+</script>
+
+<BodyText text={markdownText} />
+```
+
+## Using with ArchieML docs
+
+With the graphics kit, you'll likely get your text value from an ArchieML doc...
+
+```yaml
+# ArchieML doc
+[blocks]
+
+type: text
+text: Bacon ipsum ...
+
+... etc.
+:end
+
+[]
+```
+
+... which you'll parse out of a ArchieML block object before passing to the `BodyText` component.
+
+```svelte
+<!-- App.svelte -->
+<script>
+  import { BodyText } from '@reuters-graphics/graphics-components';
+  import content from '$locales/en/content.json';
+</script>
+
+{#each content.blocks as block}
+  {#if block.type === 'text'}
+    <BodyText text={block.text} />
+  {/if}
+{/each}
+```
+
+## Styling text
+
+Styles are built in for many text elements created by `BodyText`, including headings, ordered and unordered lists, links, blockquotes and even drop caps (using a `"drop-cap"` classed span).
+
+```svelte
+<BodyText
+  text="<span class='drop-cap'>R</span>eprehenderit hamburger pork bresaola ..."
+/>
+```
+
+### Custom styles
+
+To add your own styling, you can write styles in a global SCSS stylesheet:
+
+```svelte
+<BodyText
+  text="Venison shoulder <span class='highlight'>ham hock</span> ham leberkas."
+/>
+```
+
+```scss
+// global.scss
+span.highlight {
+  background: palegoldenrod;
+  padding: 2px 4px;
+}
+```
+
+If you want to make sure styles for one portion of text don't apply other parts of the page, add a `class` to BodyText to use as an additional selector.
+
+```svelte highlight=2
+<BodyText
+  class="my-special-text-block"
+  text="Venison shoulder <span class='highlight'>ham hock</span> ham leberkas."
+/>
+```
+
+```scss
+// global.scss
+.my-special-text-block {
+  span.highlight {
+    background: palegoldenrod;
+    padding: 2px 4px;
+  }
+}
+```