@reuters-graphics/graphics-components 3.4.1 → 3.6.0

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

@@ -0,0 +1,100 @@
+export type LegendMode = 'threshold' | 'continuous' | 'diverging' | 'categorical' | 'proportional-symbols';
+/** A formatter that turns a numeric value into a display string. */
+export type LegendFormatter = (value: number) => string;
+/**
+ * A threshold/diverging bin. Define at least one of `from`/`to`. Colors are
+ * passed through directly, so use any CSS color or design token.
+ */
+export interface LegendItem {
+    /** CSS color for the bin or category swatch. */
+    color: string;
+    /** Lower bound of the bin (inclusive). Omit for an open-ended first bin. */
+    from?: number | null;
+    /** Upper bound of the bin (exclusive). Omit for an open-ended last bin. */
+    to?: number | null;
+    /** Optional explicit label. Generated from the bounds when omitted. */
+    label?: string;
+}
+/** A continuous gradient stop. */
+export interface LegendStop {
+    /** Numeric position of the stop along the domain. */
+    value: number;
+    /** CSS color at this stop. */
+    color: string;
+    /** Optional explicit label. */
+    label?: string;
+}
+/** A continuous-mode axis tick. */
+export interface LegendTick {
+    /** Numeric position of the tick along the domain. */
+    value: number;
+    /** Optional explicit label. Formatted from `value` when omitted. */
+    label?: string;
+}
+/** The highlighted center of a diverging legend. */
+export interface LegendMidpoint {
+    /** Numeric value of the midpoint within the legend domain. */
+    value: number;
+    /** Optional explicit label. Formatted from `value` when omitted. */
+    label?: string;
+}
+/** A proportional-symbols entry. */
+export interface LegendSymbolItem {
+    /** Non-negative numeric value mapped to circle area. */
+    value: number;
+    /** Optional explicit label. Formatted from `value` when omitted. */
+    label?: string;
+}
+/** Fallback swatch for missing/unknown values. */
+export interface LegendNoData {
+    /** Label shown next to the fallback swatch. */
+    label: string;
+    /** Optional CSS color for the fallback swatch. */
+    color?: string;
+}
+import type { ContainerWidth } from '../@types/global';
+interface Props {
+    /** Optional legend heading displayed above the scale. */
+    title?: string;
+    /** Optional subtitle displayed beneath the title. */
+    subtitle?: string;
+    /** Legend rendering mode. */
+    mode?: LegendMode;
+    /**
+     * Legend entries. Threshold/diverging modes use numeric bounds and colors;
+     * categorical mode uses label and color pairs; proportional-symbols mode
+     * uses numeric values and optional labels.
+     */
+    items?: LegendItem[] | LegendSymbolItem[];
+    /** Ordered continuous color stops with numeric values. */
+    stops?: LegendStop[];
+    /** Optional tick values and labels for continuous mode. */
+    ticks?: LegendTick[];
+    /** Diverging midpoint with a numeric value and optional label. */
+    midpoint?: LegendMidpoint | null;
+    /** Optional formatter applied to numeric values. */
+    formatter?: LegendFormatter | null;
+    /** Optional fallback swatch for missing values. */
+    noData?: LegendNoData | null;
+    /** Width of the legend within the text well. */
+    width?: ContainerWidth;
+}
+/**
+ * `Legend` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-graphics-legend--docs)
+ *
+ * Quantitative and categorical legend for maps and data displays.
+ *
+ * Renders one of five legend types:
+ * - `threshold`: discrete bins with color swatches
+ * - `continuous`: a continuous gradient with ticks
+ * - `diverging`: threshold bins with a highlighted midpoint
+ * - `categorical`: square swatches with labels in a horizontal row
+ * - `proportional-symbols`: nested circles with leader lines and labels
+ *
+ * The component is presentational and can be placed anywhere in page layout. The
+ * optional `noData` prop renders a separate fallback swatch for missing, unknown,
+ * or unavailable values across all legend modes.
+ */
+declare const Legend: import("svelte").Component<Props, {}, "">;
+type Legend = ReturnType<typeof Legend>;
+export default Legend;

package/dist/components/ReferralBlock/Referral.svelte

@@ -0,0 +1,143 @@
+<!-- @component `Referral` renders a single referral card (a linked headline, kicker, time and thumbnail). It's used by `ReferralBlock` but can be dropped into any layout on its own. -->
+<script lang="ts">
+  // Utils
+  import { getTime } from '../SiteHeader/NavBar/NavDropdown/StoryCard/time';
+
+  // Types
+  import type { ReferralItem, LinkTarget } from './types';
+
+  interface Props extends ReferralItem {
+    /**
+     * Link [target](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target), e.g., `_blank` or `_parent`.
+     */
+    linkTarget?: LinkTarget;
+    /** Use the narrower thumbnail sizing, for tight layouts. */
+    compact?: boolean;
+    /** Render as a single full-width column instead of a half-width card. */
+    stacked?: boolean;
+    /** Add a class to the card's root element. */
+    class?: string;
+  }
+
+  let {
+    url,
+    kicker,
+    title,
+    imageUrl,
+    imageAlt = '',
+    time,
+    linkTarget = '_self',
+    compact = false,
+    stacked = false,
+    class: cls = '',
+  }: Props = $props();
+</script>
+
+<div class="referral {cls}" class:stacked>
+  <a
+    href={url}
+    target={linkTarget}
+    rel={linkTarget === '_blank' ? 'noreferrer' : null}
+  >
+    <div class="referral-pack flex justify-around my-0 mx-auto">
+      <div class="headline" class:xs={compact}>
+        <div
+          class="kicker m-0 body-caption leading-tighter"
+          data-chromatic="ignore"
+        >
+          {kicker}
+        </div>
+        <div
+          class="title m-0 body-caption leading-tighter"
+          data-chromatic="ignore"
+        >
+          {title}
+        </div>
+        {#if time}
+          <div
+            class="publish-time body-caption leading-tighter"
+            data-chromatic="ignore"
+          >
+            {getTime(new Date(time))}
+          </div>
+        {/if}
+      </div>
+      <div
+        class="image-container block m-0 overflow-hidden relative"
+        class:xs={compact}
+      >
+        <img
+          class="block object-cover m-0 w-full"
+          data-chromatic="ignore"
+          src={imageUrl}
+          alt={imageAlt}
+        />
+      </div>
+    </div>
+  </a>
+</div>
+
+<style>/* Generated from 
+https://utopia.fyi/space/calculator/?c=320,18,1.125,1280,21,1.25,7,3,&s=0.75|0.5|0.25,1.5|2|3|4|6,s-l&g=s,l,xl,12
+*/
+/* Generated from 
+https://utopia.fyi/space/calculator/?c=320,18,1.125,1280,21,1.25,7,3,&s=0.75|0.5|0.25,1.5|2|3|4|6,s-l&g=s,l,xl,12
+*/
+/* Scales by 1.125 */
+a {
+  text-decoration: none;
+}
+
+.referral {
+  display: block;
+  width: calc(50% - 30px);
+  max-width: 450px;
+  margin-block-start: clamp(0.31rem, 0.31rem + 0vw, 0.31rem);
+  margin-block-end: clamp(0.31rem, 0.31rem + 0vw, 0.31rem);
+}
+.referral.stacked {
+  width: 100%;
+}
+.referral.stacked .headline {
+  width: calc(100% - 7rem);
+}
+.referral:hover .title {
+  text-decoration: underline;
+}
+.referral:hover img {
+  filter: brightness(85%);
+}
+.referral .headline {
+  display: inline-block;
+  width: calc(100% - 9rem);
+  padding-inline-end: clamp(0.56rem, 0.52rem + 0.21vw, 0.69rem);
+}
+.referral .headline .kicker {
+  font-size: var(--theme-font-size-xxs);
+  font-family: Knowledge, sans-serif;
+}
+.referral .headline .title {
+  margin-block-start: clamp(0.31rem, 0.31rem + 0vw, 0.31rem);
+  font-weight: 500;
+  font-size: var(--theme-font-size-sm);
+  color: var(--theme-colour-text-primary);
+  font-family: Knowledge, sans-serif;
+}
+.referral .headline .publish-time {
+  font-size: var(--theme-font-size-xxs);
+  font-family: Knowledge, sans-serif;
+}
+.referral .image-container {
+  border-radius: 0.25rem;
+  border: 1px solid var(--theme-colour-brand-rules);
+  width: 9rem;
+}
+.referral .image-container.xs {
+  width: 7rem;
+}
+.referral .image-container img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  transition: filter 0.1s;
+}</style>

package/dist/components/ReferralBlock/Referral.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { ReferralItem, LinkTarget } from './types';
+interface Props extends ReferralItem {
+    /**
+     * Link [target](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target), e.g., `_blank` or `_parent`.
+     */
+    linkTarget?: LinkTarget;
+    /** Use the narrower thumbnail sizing, for tight layouts. */
+    compact?: boolean;
+    /** Render as a single full-width column instead of a half-width card. */
+    stacked?: boolean;
+    /** Add a class to the card's root element. */
+    class?: string;
+}
+/** `Referral` renders a single referral card (a linked headline, kicker, time and thumbnail). It's used by `ReferralBlock` but can be dropped into any layout on its own. */
+declare const Referral: import("svelte").Component<Props, {}, "">;
+type Referral = ReturnType<typeof Referral>;
+export default Referral;

package/dist/components/ReferralBlock/ReferralBlock.svelte

@@ -2,16 +2,17 @@
 <script lang="ts">
   // Utils
   import { onMount } from 'svelte';
-  import { getTime } from '../SiteHeader/NavBar/NavDropdown/StoryCard/time';
-  import { articleIsNotCurrentPage } from './filterCurrentPage';
+  import { fetchReferrals } from './getReferrals';
 
   // Components
   import Block from '../Block/Block.svelte';
+  import Referral from './Referral.svelte';
 
   // Types
-  import type { Article } from './types';
-  import type { Referrals } from './types';
-  type ContainerWidth = 'normal' | 'wide' | 'wider' | 'widest' | 'fluid';
+  import type { ContainerWidth } from '../@types/global';
+  import type { ReferralItem, LinkTarget } from './types';
+
+  type ReferralBlockWidth = Exclude<ContainerWidth, 'narrower' | 'narrow'>;
 
   interface Props {
     /**
@@ -24,6 +25,12 @@
      * Collection alias, as defined in Arc Collections editor.
      */
     collection?: string;
+    /**
+     * Provide your own referrals instead of fetching recent stories from
+     * Reuters.com. When set, the `section`/`collection` fetch is skipped and
+     * these stories are rendered as-is.
+     */
+    stories?: ReferralItem[];
     /**
      * Number of referrals to show.
      */
@@ -31,7 +38,7 @@
     /**
      * Link [target](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target), e.g., `_blank` or `_parent`.
      */
-    linkTarget?: string;
+    linkTarget?: LinkTarget;
     /**
      * Add a heading to the referral block.
      */
@@ -39,7 +46,7 @@
     /**
      * Width of the component within the text well: 'normal' | 'wide' | 'wider' | 'widest' | 'fluid'
      */
-    width?: ContainerWidth;
+    width?: ReferralBlockWidth;
     /** Add an ID to target with SCSS. */
     id?: string;
     /** Add a class to target with SCSS. */
@@ -49,6 +56,7 @@
   let {
     section = '/world/',
     collection,
+    stories = [],
     number = 4,
     linkTarget = '_self',
     heading = '',
@@ -59,51 +67,27 @@
 
   let clientWidth = $state(0);
 
-  const SECTION_API = 'recent-stories-by-sections-v1';
-
-  /** @TODO - Check if collections alias API still exists*/
-  const COLLECTION_API = 'articles-by-collection-alias-or-id-v1';
-
-  let referrals: Article[] = $state([]);
-
-  const getReferrals = async () => {
-    if (typeof window === 'undefined') return;
-    // fetch only reliably works on prod sites
-    if (window?.location?.hostname !== 'www.reuters.com') return;
-    const isCollection = Boolean(collection);
-    const API = isCollection ? COLLECTION_API : SECTION_API;
-    try {
-      const response = await fetch(
-        `https://www.reuters.com/pf/api/v3/content/fetch/${API}?` +
-          new URLSearchParams({
-            query: JSON.stringify({
-              section_ids: isCollection ? undefined : section,
-              collection_alias: isCollection ? collection : undefined,
-              size: 20,
-              website: 'reuters',
-            }),
-          })
-      );
-
-      const data = (await response.json()) as Referrals;
-
-      const articles = data.result.articles
-        .filter((a) => a?.headline_category || a?.kicker?.name)
-        .filter((a) => a?.thumbnail?.url)
-        .filter((a) => !a?.content?.third_party)
-        .filter(articleIsNotCurrentPage)
-        .slice(0, number);
-
-      referrals = articles;
-    } catch {
-      console.warn('Unable to fetch referral links.');
-    }
-  };
-
-  onMount(getReferrals);
+  let fetchedReferrals: ReferralItem[] = $state([]);
+
+  // Manually provided stories take precedence. Otherwise, only show fetched
+  // stories once the API returns the full requested number, which avoids
+  // rendering a partial block.
+  const referrals = $derived<ReferralItem[]>(
+    stories.length ? stories
+    : fetchedReferrals.length === number ? fetchedReferrals
+    : []
+  );
+
+  onMount(() => {
+    // Skip the network request entirely when stories are supplied by hand.
+    if (stories.length) return;
+    fetchReferrals({ section, collection, number }).then((items) => {
+      fetchedReferrals = items;
+    });
+  });
 </script>
 
-{#if referrals.length === number}
+{#if referrals.length}
   <Block {width} {id} class="referrals-block {cls}">
     <div
       class="block-container"
@@ -124,65 +108,19 @@
         class:xs={clientWidth && clientWidth < 450}
       >
         {#each referrals as referral}
-          <div class="referral">
-            <a
-              href="https://www.reuters.com{referral.canonical_url}"
-              target={linkTarget}
-              rel={linkTarget === '_blank' ? 'noreferrer' : null}
-            >
-              <div class="referral-pack flex justify-around my-0 mx-auto">
-                <div
-                  class="headline"
-                  class:xs={clientWidth && clientWidth < 450}
-                >
-                  <div
-                    class="kicker m-0 body-caption leading-tighter"
-                    data-chromatic="ignore"
-                  >
-                    {referral.headline_category || referral.kicker.name}
-                  </div>
-                  <div
-                    class="title m-0 body-caption leading-tighter"
-                    data-chromatic="ignore"
-                  >
-                    {referral.title}
-                  </div>
-                  <div
-                    class="publish-time body-caption leading-tighter"
-                    data-chromatic="ignore"
-                  >
-                    {getTime(new Date(referral.display_time))}
-                  </div>
-                </div>
-                <div
-                  class="image-container block m-0 overflow-hidden relative"
-                  class:xs={clientWidth && clientWidth < 450}
-                >
-                  <img
-                    class="block object-cover m-0 w-full"
-                    data-chromatic="ignore"
-                    src={referral.thumbnail.url}
-                    alt={referral.thumbnail.alt_text ||
-                      referral.thumbnail.caption}
-                  />
-                </div>
-              </div>
-            </a>
-          </div>
+          <Referral
+            {...referral}
+            {linkTarget}
+            compact={clientWidth > 0 && clientWidth < 450}
+            stacked={clientWidth > 0 && clientWidth < 750}
+          />
         {/each}
       </div>
     </div>
   </Block>
 {/if}
 
-<style>/* Generated from 
-https://utopia.fyi/space/calculator/?c=320,18,1.125,1280,21,1.25,7,3,&s=0.75|0.5|0.25,1.5|2|3|4|6,s-l&g=s,l,xl,12
-*/
-/* Generated from 
-https://utopia.fyi/space/calculator/?c=320,18,1.125,1280,21,1.25,7,3,&s=0.75|0.5|0.25,1.5|2|3|4|6,s-l&g=s,l,xl,12
-*/
-/* Scales by 1.125 */
-div.block-container.stacked {
+<style>div.block-container.stacked {
   display: flex;
   flex-direction: column;
   align-items: center;
@@ -196,61 +134,6 @@ div.heading.stacked {
   max-width: 450px;
 }
 
-.referral-container a {
-  text-decoration: none;
-}
 .referral-container.stacked {
   max-width: 450px;
-}
-.referral-container.stacked .referral {
-  width: 100%;
-}
-.referral-container.stacked .referral .headline {
-  width: calc(100% - 7rem);
-}
-.referral-container .referral {
-  display: block;
-  width: calc(50% - 30px);
-  max-width: 450px;
-  margin-block-start: clamp(0.31rem, 0.31rem + 0vw, 0.31rem);
-  margin-block-end: clamp(0.31rem, 0.31rem + 0vw, 0.31rem);
-}
-.referral-container .referral:hover .title {
-  text-decoration: underline;
-}
-.referral-container .referral:hover img {
-  filter: brightness(85%);
-}
-.referral-container .referral .headline {
-  display: inline-block;
-  width: calc(100% - 9rem);
-  padding-inline-end: clamp(0.56rem, 0.52rem + 0.21vw, 0.69rem);
-}
-.referral-container .referral .headline .kicker {
-  font-size: var(--theme-font-size-xxs);
-  font-family: Knowledge, sans-serif;
-}
-.referral-container .referral .headline .title {
-  font-weight: 500;
-  font-size: var(--theme-font-size-sm);
-  color: var(--theme-colour-text-primary);
-  font-family: Knowledge, sans-serif;
-}
-.referral-container .referral .headline .publish-time {
-  font-size: var(--theme-font-size-xxs);
-  font-family: Knowledge, sans-serif;
-}
-.referral-container .referral .image-container {
-  border-radius: 0.25rem;
-  border: 1px solid var(--theme-colour-brand-rules);
-  width: 9rem;
-}
-.referral-container .referral .image-container.xs {
-  width: 7rem;
-}
-.referral-container .referral .image-container img {
-  width: 100%;
-  height: 100%;
-  object-fit: cover;
-  transition: filter 0.1s;
 }</style>

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

@@ -1,4 +1,6 @@
-type ContainerWidth = 'normal' | 'wide' | 'wider' | 'widest' | 'fluid';
+import type { ContainerWidth } from '../@types/global';
+import type { ReferralItem, LinkTarget } from './types';
+type ReferralBlockWidth = Exclude<ContainerWidth, 'narrower' | 'narrow'>;
 interface Props {
     /**
      * Section ID, which is often the URL path to the section page on reuters.com.
@@ -10,6 +12,12 @@ interface Props {
      * Collection alias, as defined in Arc Collections editor.
      */
     collection?: string;
+    /**
+     * Provide your own referrals instead of fetching recent stories from
+     * Reuters.com. When set, the `section`/`collection` fetch is skipped and
+     * these stories are rendered as-is.
+     */
+    stories?: ReferralItem[];
     /**
      * Number of referrals to show.
      */
@@ -17,7 +25,7 @@ interface Props {
     /**
      * Link [target](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target), e.g., `_blank` or `_parent`.
      */
-    linkTarget?: string;
+    linkTarget?: LinkTarget;
     /**
      * Add a heading to the referral block.
      */
@@ -25,7 +33,7 @@ interface Props {
     /**
      * Width of the component within the text well: 'normal' | 'wide' | 'wider' | 'widest' | 'fluid'
      */
-    width?: ContainerWidth;
+    width?: ReferralBlockWidth;
     /** Add an ID to target with SCSS. */
     id?: string;
     /** Add a class to target with SCSS. */

package/dist/components/ReferralBlock/getReferrals.d.ts

@@ -0,0 +1,26 @@
+import type { ReferralItem } from './types';
+/**
+ * Environment gate for the live fetch. The Reuters.com referral API is only
+ * same-origin — and therefore CORS-accessible — on production, so by default we
+ * only fetch when running on www.reuters.com. Stories and tests can override
+ * `enabled` to feed mocked data through the real fetch/transform path without
+ * loosening this guard for real, non-production environments.
+ */
+export declare const referralsApi: {
+    enabled: () => boolean;
+};
+interface FetchReferralsOptions {
+    /** Section ID/path passed to the recent-stories-by-section API. */
+    section?: string;
+    /** Collection alias passed to the articles-by-collection API. */
+    collection?: string;
+    /** Maximum number of referrals to return. */
+    number?: number;
+}
+/**
+ * Fetch recent Reuters.com stories for a section or collection and map them
+ * into referral items. Returns an empty array when fetching is disabled (see
+ * `referralsApi`) or the request fails.
+ */
+export declare const fetchReferrals: ({ section, collection, number, }: FetchReferralsOptions) => Promise<ReferralItem[]>;
+export {};

package/dist/components/ReferralBlock/getReferrals.js

@@ -0,0 +1,58 @@
+import { articleIsNotCurrentPage } from './filterCurrentPage';
+const SECTION_API = 'recent-stories-by-sections-v1';
+/** @TODO - Check if collections alias API still exists*/
+const COLLECTION_API = 'articles-by-collection-alias-or-id-v1';
+/** Map a fetched Reuters.com article into the referral shape. */
+const articleToItem = (a) => ({
+    url: `https://www.reuters.com${a.canonical_url}`,
+    kicker: a.headline_category || a.kicker.name,
+    title: a.title,
+    imageUrl: a.thumbnail.url,
+    imageAlt: a.thumbnail.alt_text || a.thumbnail.caption || '',
+    time: new Date(a.display_time),
+});
+/**
+ * Environment gate for the live fetch. The Reuters.com referral API is only
+ * same-origin — and therefore CORS-accessible — on production, so by default we
+ * only fetch when running on www.reuters.com. Stories and tests can override
+ * `enabled` to feed mocked data through the real fetch/transform path without
+ * loosening this guard for real, non-production environments.
+ */
+export const referralsApi = {
+    enabled: () => typeof window !== 'undefined' &&
+        window.location?.hostname === 'www.reuters.com',
+};
+/**
+ * Fetch recent Reuters.com stories for a section or collection and map them
+ * into referral items. Returns an empty array when fetching is disabled (see
+ * `referralsApi`) or the request fails.
+ */
+export const fetchReferrals = async ({ section = '/world/', collection, number = 4, }) => {
+    if (!referralsApi.enabled())
+        return [];
+    const isCollection = Boolean(collection);
+    const API = isCollection ? COLLECTION_API : SECTION_API;
+    try {
+        const response = await fetch(`https://www.reuters.com/pf/api/v3/content/fetch/${API}?` +
+            new URLSearchParams({
+                query: JSON.stringify({
+                    section_ids: isCollection ? undefined : section,
+                    collection_alias: isCollection ? collection : undefined,
+                    size: 20,
+                    website: 'reuters',
+                }),
+            }));
+        const data = (await response.json());
+        return data.result.articles
+            .filter((a) => a?.headline_category || a?.kicker?.name)
+            .filter((a) => a?.thumbnail?.url)
+            .filter((a) => !a?.content?.third_party)
+            .filter(articleIsNotCurrentPage)
+            .slice(0, number)
+            .map(articleToItem);
+    }
+    catch {
+        console.warn('Unable to fetch referral links.');
+        return [];
+    }
+};