@reuters-graphics/graphics-components 2.0.2 → 3.0.0

package/dist/components/Block/Block.mdx

@@ -0,0 +1,99 @@
+import { Meta, Canvas } from '@storybook/blocks';
+
+import * as BlockStories from './Block.stories.svelte';
+
+<Meta of={BlockStories} />
+
+# 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>
+```
+
+<Canvas of={BlockStories.Demo} />
+
+## 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>
+```
+
+<Canvas of={BlockStories.CustomLayout} />
+
+## 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>
+```
+
+<Canvas of={BlockStories.SnapWidthsBasic} />
+
+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/components/Block/Block.stories.svelte

@@ -1,59 +1,44 @@
-<script context="module">import componentDocs from "./stories/docs/component.md?raw";
-import customLayoutsDocs from "./stories/docs/customLayouts.md?raw";
-import snapWidthsDocs from "./stories/docs/snapWidths.md?raw";
-import Block from "./Block.svelte";
-import { withComponentDocs, withStoryDocs } from "$docs/utils/withParams.js";
-import { toId } from "@storybook/csf";
-export const meta = {
-  title: "Components/Page layout/Block",
-  component: Block,
-  parameters: {
-    ...withComponentDocs(componentDocs).parameters,
-    canvasDocs: {
-      [toId("Components/Page layout/Block", "default")]: componentDocs
-    }
-  },
-  argTypes: {
-    width: {
-      control: "select",
-      options: [
-        "narrower",
-        "narrow",
-        "normal",
-        "wide",
-        "wider",
-        "widest",
-        "fluid"
-      ]
-    }
-  }
-};
+<script module lang="ts">
+  import { defineMeta } from '@storybook/addon-svelte-csf';
+  import Block from './Block.svelte';
+
+  const { Story } = defineMeta({
+    title: 'Components/Page layout/Block',
+    component: Block,
+    tags: ['autodocs'],
+    argTypes: {
+      width: {
+        control: 'select',
+        options: [
+          'narrower',
+          'narrow',
+          'normal',
+          'wide',
+          'wider',
+          'widest',
+          'fluid',
+        ],
+      },
+    },
+  });
 </script>
 
 <script>
-  import { Template, Story } from '@storybook/addon-svelte-csf';
   import Article from '../Article/Article.svelte';
 </script>
 
-<Template let:args>
+<Story name="Demo">
   <Article id="block-demo-article">
     <div class="article-boundaries">
       <div class="label">Article</div>
-      <Block {...args}>
+      <Block>
         <div class="label">Block</div>
       </Block>
     </div>
   </Article>
-</Template>
-
-<Story
-  name="Default"
-  args="{{
-    width: 'normal',
-  }}"
-/>
+</Story>
 
-<Story name="Custom layouts" {...withStoryDocs(customLayoutsDocs)}>
+<Story name="Custom layout" exportName="CustomLayout">
   <Block width="fluid">
     <!-- Enter bootstrap grid! -->
     <div id="block-flex-example">
@@ -70,53 +55,77 @@ export const meta = {
   </Block>
 </Story>
 
-<Story name="Snap widths" {...withStoryDocs(snapWidthsDocs)}>
+<Story name="Snap widths" exportName="SnapWidthsBasic">
   <Article id="block-demo-article">
     <div class="article-boundaries">
       <div class="label">Article</div>
-      <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
-      >
-      <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
-      >
+      <h4>snap widths</h4>
+      <Block snap={true}>
+        <div class="label">Block</div>
+      </Block>
+    </div>
+  </Article>
+</Story>
+
+<Story name="Snap and skip widths" exportName="SnapSkipWidths">
+  <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}"
+        snap={true}
         class="block-snap-widths-demo even skip-narrow"
-        >normal.skip-narrow</Block
       >
+        normal.skip-narrow
+      </Block>
       <Block
         width="wide"
-        snap="{true}"
+        snap={true}
         class="block-snap-widths-demo even skip-normal skip-narrow"
-        >wide.skip-normal.skip-narrow</Block
       >
+        wide.skip-normal.skip-narrow
+      </Block>
       <Block
         width="wider"
-        snap="{true}"
-        class="block-snap-widths-demo even skip-wide">wider.skip-wide</Block
+        snap={true}
+        class="block-snap-widths-demo even skip-wide"
       >
+        wider.skip-wide
+      </Block>
     </div>
   </Article>
 </Story>
 
-<style>:global(#block-demo-article) {
+<style>h4 {
+  text-align: center;
+}
+
+:global(#block-demo-article) {
   background-color: #ddd;
   position: relative;
   width: calc(100% + 30px);
@@ -146,9 +155,10 @@ export const meta = {
 }
 
 :global(#block-demo-article .label,
-      #block-demo-article div.article-block.block-snap-widths-demo) {
+    #block-demo-article div.article-block.block-snap-widths-demo) {
   padding-left: 3px;
   color: white;
+  font-weight: 500;
 }
 
 div#block-flex-example {

package/dist/components/Block/Block.stories.svelte.d.ts

@@ -1,32 +1,19 @@
-import { SvelteComponent } from "svelte";
-export declare const meta: {
-    title: string;
-    component: typeof Block;
-    parameters: {
-        canvasDocs: {
-            [x: string]: any;
-        };
-        docs: any;
+import Block from './Block.svelte';
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
     };
-    argTypes: {
-        width: {
-            control: string;
-            options: string[];
-        };
-    };
-};
-declare const __propDef: {
-    props: Record<string, never>;
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {};
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type BlockProps = typeof __propDef.props;
-export type BlockEvents = typeof __propDef.events;
-export type BlockSlots = typeof __propDef.slots;
-export default class Block extends SvelteComponent<BlockProps, BlockEvents, BlockSlots> {
+    z_$$bindings?: Bindings;
 }
-export {};
+declare const Block: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type Block = InstanceType<typeof Block>;
+export default Block;

package/dist/components/Block/Block.svelte

@@ -1,22 +1,44 @@
 <!-- @component `Block` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-page-layout-block--docs) -->
-<script>export let width = "normal";
-export let id = "";
-let cls = "";
-export { cls as class };
-export let snap = false;
-export let role = null;
-export let ariaLabel = null;
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import type { ContainerWidth } from '../@types/global';
+
+  interface Props {
+    /** Content that goes inside `<Block>`*/
+    children: Snippet;
+    /** Width of the block within the article well. */
+    width?: ContainerWidth;
+    /** Add an id to the block tag to target it with custom CSS. */
+    id?: string;
+    /** Add custom classes to the block tag to target it with custom CSS. */
+    class?: string;
+    /** Snap block to column widths, rather than fluidly resizing them. */
+    snap?: boolean;
+    /** ARIA [role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) for the block */
+    role?: string;
+    /** ARIA [label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) for the block */
+    ariaLabel?: string;
+  }
+
+  let {
+    children,
+    width = 'normal',
+    id = '',
+    class: cls = '',
+    snap = false,
+    role,
+    ariaLabel,
+  }: Props = $props();
 </script>
 
 <div
   {id}
   class="article-block fmx-auto {width} {cls}"
-  class:snap="{snap && width !== 'fluid' && width !== 'widest'}"
+  class:snap={snap && width !== 'fluid' && width !== 'widest'}
   {role}
-  aria-label="{ariaLabel}"
+  aria-label={ariaLabel}
 >
-  <!-- block content -->
-  <slot />
+  {@render children()}
 </div>
 
 <style>/* Generated from 

package/dist/components/Block/Block.svelte.d.ts

@@ -1,27 +1,22 @@
-import { SvelteComponent } from "svelte";
+import type { Snippet } from 'svelte';
 import type { ContainerWidth } from '../@types/global';
-declare const __propDef: {
-    props: {
-        /** Width of the block within the article well. */ width?: ContainerWidth;
-        /** Add an id to the block tag to target it with custom CSS. */ id?: string;
-        /** Add extra classes to the block tag to target it with custom CSS. */ class?: string;
-        /** Snap block to column widths, rather than fluidly resizing them. */ snap?: boolean;
-        /** ARIA [role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) for the block */ role?: string | null;
-        /** ARIA [label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) for the block */ ariaLabel?: string | null;
-    };
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {
-        default: {};
-    };
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type BlockProps = typeof __propDef.props;
-export type BlockEvents = typeof __propDef.events;
-export type BlockSlots = typeof __propDef.slots;
-/** `Block` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-page-layout-block--docs) */
-export default class Block extends SvelteComponent<BlockProps, BlockEvents, BlockSlots> {
+interface Props {
+    /** Content that goes inside `<Block>`*/
+    children: Snippet;
+    /** Width of the block within the article well. */
+    width?: ContainerWidth;
+    /** Add an id to the block tag to target it with custom CSS. */
+    id?: string;
+    /** Add custom classes to the block tag to target it with custom CSS. */
+    class?: string;
+    /** Snap block to column widths, rather than fluidly resizing them. */
+    snap?: boolean;
+    /** ARIA [role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) for the block */
+    role?: string;
+    /** ARIA [label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) for the block */
+    ariaLabel?: string;
 }
-export {};
+/** `Block` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-page-layout-block--docs) */
+declare const Block: import("svelte").Component<Props, {}, "">;
+type Block = ReturnType<typeof Block>;
+export default Block;

package/dist/components/BodyText/BodyText.mdx

@@ -0,0 +1,115 @@
+import { Meta, Canvas } from '@storybook/blocks';
+
+import * as BodyTextStories from './BodyText.stories.svelte';
+
+<Meta of={BodyTextStories} />
+
+# 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} />
+```
+
+<Canvas of={BodyTextStories.Demo} />
+
+## 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}
+```
+
+<Canvas of={BodyTextStories.Demo} />
+
+## 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 ..."
+/>
+```
+
+<Canvas of={BodyTextStories.TypographySample} />
+
+### 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;
+}
+```
+
+<Canvas of={BodyTextStories.CustomStyles} />
+
+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;
+  }
+}
+```