@reuters-graphics/graphics-components 3.10.0 → 4.0.0

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

@@ -0,0 +1,248 @@
+# Headline
+
+**Category:** Components/Text elements/Headline
+
+**Import:** `import { Headline } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `hed` | `string \| Snippet` | `'Reuters Graphics Interactive'` |  | Headline, parsed as an _inline_ markdown string in an `h1` element OR as a custom snippet. |
+| `class` | `string` | `''` |  | Add extra classes to the block tag to target it with custom CSS. |
+| `hedSize` | `HeadlineSize` | `'normal'` |  | Headline size: small, normal, big, bigger, biggest Options: `small`, `normal`, `big`, `bigger`, `biggest` |
+| `dek` | `string \| Snippet` | — |  | Dek, parsed as a markdown string OR as a custom snippet. |
+| `section` | `string` | — |  | Section title |
+| `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. |
+| `width` | `'normal' \| 'wide' \| 'wider' \| 'widest'` | `'normal'` |  | Width of the headline: normal, wide, wider, widest Options: `normal`, `wide`, `wider`, `widest` |
+| `getAuthorPage` | `(author: string) => string` | — |  | Custom function that returns an author page URL. |
+| `crown` | `Snippet` | — |  | Custom crown snippet |
+| `byline` | `Snippet` | — |  | Optional snippet for a custom byline. |
+| `published` | `Snippet` | — |  | Optional snippet for a custom published dateline. |
+| `updated` | `Snippet` | — |  | Optional snippet for a custom updated dateline. |
+
+## Examples
+
+### Demo
+
+```svelte
+<Headline
+  hed="Reuters Graphics interactive"
+  dek="The beginning of a beautiful page"
+  section="World News"
+/>
+```
+
+### With byline and dateline
+
+```svelte
+<Headline
+  hed={'Reuters Graphics Interactive'}
+  dek={'The beginning of a beautiful page'}
+  section={'Global news'}
+  authors={['Jane Doe']}
+  publishTime={new Date('2020-01-01').toISOString()}
+  getAuthorPage={(author: string) => {
+    return `mailto:${author.replace(' ', '')}@example.com`;
+  }}
+/>
+```
+
+### Custom hed and dek
+
+```svelte
+<Headline width="wide">
+  {#snippet hed()}
+    <h1 class="custom-hed">
+      <span class="small block text-base">The secret to</span>
+      “The Nutcracker's”
+      <span class="small block text-base fpt-1">success</span>
+    </h1>
+  {/snippet}
+  {#snippet dek()}
+    <p class="custom-dek !fmt-3">
+      How “The Nutcracker” ballet became an<span
+        class="font-medium mx-1 px-1.5 py-1">American holday staple</span
+      >and a financial pillar of ballet companies across the country
+    </p>
+  {/snippet}
+</Headline>
+```
+
+### Crown image
+
+```svelte
+<Headline
+  class="!fmt-3"
+  hed="Europa"
+  publishTime={new Date('2020-01-01').toISOString()}
+>
+  <!-- Add a crown -->
+  {#snippet crown()}
+    <img
+      src={crownImgSrc}
+      width="100"
+      class="mx-auto mb-0"
+      alt="Illustration of Europe"
+    />
+  {/snippet}
+</Headline>
+```
+
+### Crown graphic
+
+```svelte
+<Headline
+  width="wider"
+  class="!fmt-1"
+  hed={'Unfriendly skies'}
+  dek={'How Russia’s invasion of Ukraine is redrawing air routes'}
+  section={'Ukraine Crisis'}
+  authors={['Simon Scarr', 'Vijdan Mohammad Kawoosa']}
+  publishTime={new Date('2022-03-04').toISOString()}
+>
+  <!-- Add a crown graphic -->
+  {#snippet crown()}
+    <Map />
+  {/snippet}
+</Headline>
+```
+
+## Documentation
+
+# Headline
+
+The `Headline` component creates headlines in the legacy Reuters Graphics style, with the text centred on the page.
+
+```svelte
+<script>
+  import { Headline } from '@reuters-graphics/graphics-components';
+</script>
+
+<Headline
+  hed="Reuters Graphics Interactive"
+  dek="The beginning of a beautiful page"
+  section="World News"
+/>
+```
+
+## With bylines and dateline
+
+Optionally, you can add authors and a publish time to the headline, which the `Headline` component internally renders with the [Byline](./?path=/docs/components-text-elements-byline--docs) component.
+
+> **Note**: Since `Headline` uses `Byline`, you can customise the author page hyperlink and bylines with the `getAuthorPage`, `byline`, `published` and `updated` props.
+
+```svelte
+<script>
+  import { Headline } from '@reuters-graphics/graphics-components';
+</script>
+
+<Headline
+  hed={'Reuters Graphics Interactive'}
+  dek={'The beginning of a beautiful page'}
+  section={'Global news'}
+  authors={['Jane Doe']}
+  publishTime={new Date('2020-01-01').toISOString()}
+  getAuthorPage={(author) => `mailto:${author.replace(' ', '')}@example.com`}
+/>
+```
+
+## Custom hed and dek
+
+Use the `hed` and/or `dek` [snippets](https://svelte.dev/docs/svelte/snippet) to override those elements with custom elements.
+
+```svelte
+<script>
+  import { Headline } from '@reuters-graphics/graphics-components';
+</script>
+
+<Headline width="wide">
+  <!-- Custom hed snippet -->
+  {#snippet hed()}
+    <h1 class="custom-hed">
+      <span class="small block text-base">The secret to</span>
+      “The Nutcracker's”
+      <span class="small block text-base fpt-1">success</span>
+    </h1>
+  {/snippet}
+
+  <!-- Custom dek snippet -->
+  {#snippet dek()}
+    <p class="custom-dek !fmt-3">
+      How “The Nutcracker” ballet became an<span
+        class="font-medium mx-1 px-1.5 py-1">American holday staple</span
+      >and a financial pillar of ballet companies across the country
+    </p>
+  {/snippet}
+</Headline>
+
+<!-- Custom styles -->
+<style lang="scss">
+  .custom-hed {
+    line-height: 0.9;
+  }
+  .custom-dek {
+    span {
+      background-color: #fde68a;
+    }
+  }
+</style>
+```
+
+## With crown image
+
+To add a crown image, use the `crown` [snippet](https://svelte.dev/docs/svelte/snippet).
+
+```svelte
+<script>
+  import { Headline } from '@reuters-graphics/graphics-components';
+  import { asset } from '$app/paths';
+</script>
+
+<Headline
+  class="!fmt-3"
+  hed="Europa"
+  publishTime={new Date('2020-01-01').toISOString()}
+>
+  <!-- Add a crown -->
+  {#snippet crown()}
+    <img
+      src={crownImgSrc}
+      width="100"
+      class="mx-auto mb-0"
+      alt="Illustration of Europe"
+    />
+  {/snippet}
+</Headline>
+```
+
+## With crown graphic
+
+Add a full graphic or any other component in the crown.
+
+```svelte
+<script>
+  import { Headline } from '@reuters-graphics/graphics-components';
+  import { asset } from '$app/paths'; // If in Graphis Kit
+
+  import Map from './ai2svelte/graphic.svelte'; // Import the crown graphic component
+</script>
+
+<Headline
+  width="wider"
+  class="!fmt-1"
+  hed={'Unfriendly skies'}
+  dek={'How Russia’s invasion of Ukraine is redrawing air routes'}
+  section={'Ukraine Crisis'}
+  authors={['Simon Scarr', 'Vijdan Mohammad Kawoosa']}
+  publishTime={new Date('2022-03-04').toISOString()}
+>
+  <!-- Add a crown graphic -->
+  {#snippet crown()}
+    <!-- Pass `assetsPath` if in graphics kit -->
+    <Map assetsPath={asset('/').replace(/\/$/, '')} />
+  {/snippet}
+</Headline>
+```

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

@@ -0,0 +1,55 @@
+# Headpile
+
+**Category:** Components/Text elements/Headpile
+
+**Import:** `import { Headpile } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `class` | `string` | — | ✓ | Add classes to target with custom CSS. |
+| `id` | `string` | — | ✓ | Add an id to target with custom CSS. |
+| `width` | `Extract<ContainerWidth, 'normal' \| 'wide'>` | `'normal'` |  | Width of the container. |
+| `colour` | `string` | `'#cccccc'` |  | Default background colour to be used as a mount behind the headshot. |
+| `figures` | `{       /**        * Headshot image src. Be sure to prefix the image        *        * ```typescript        * import { asset } from '$app/paths';        *        * const imgSrc = asset('/images/my-image.jpg');        * ```        */       img: string;       /**        * Figure name.        */       name: string;       /**        * Figure role or title.        */       role?: string;       /**        * Text describing the person.        */       text: string;       /**        * Background colour to be used as a mount behind the headshot.        */       colour?: string;     }[]` | — | ✓ | Individual figures -- i.e., people -- for the headpile. |
+
+## Examples
+
+### Demo
+
+```svelte
+<Headpile figures={/* defaultArgs */} />
+```
+
+## Documentation
+
+# Headpile
+
+The `Headpile` component is a headshot-bulleted list of people, identifying them with their names, roles and a short description of their significance to a story.
+
+It's designed to be used with headshots that have had their background removed, which can be done in the [Preview app](https://support.apple.com/en-gb/guide/preview/prvw15636/mac?#apd320b3b1b750a4) on macOS.
+
+```svelte
+<script>
+  import { Headpile } from '@reuters-graphics/graphics-components';
+  import { asset } from '$app/paths'; // 👈 If using in the graphics kit...
+</script>
+
+<Headpile
+  figures={[
+    {
+      img: asset('/images/person-A.jpg'),
+      name: 'General Abdel Fattah al-Burhan',
+      role: "Sudan's Sovereign Council Chief and military commander",
+      text: 'Burhan was little known in public life until taking part in the coup ...',
+    },
+    {
+      img: asset('/images/person-B.jpg'),
+      name: 'General Mohamed Hamdan Dagalo',
+      role: 'Leader of the Sudanese paramilitary Rapid Support Forces (RSF)',
+      text: 'Popularly known as Hemedti, Dagalo rose from lowly beginnings ...',
+    },
+  ]}
+/>
+```