@reuters-graphics/graphics-components 3.5.0 → 3.7.0

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 [];
+    }
+};

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

@@ -1,3 +1,30 @@
+/**
+ * A manually authored referral, used to populate `ReferralBlock` with your own
+ * stories instead of fetching recent stories from Reuters.com.
+ */
+export interface ReferralItem {
+    /** URL the referral links to. Used as-is, so include the full address. */
+    url: string;
+    /** Kicker or category text shown above the title. */
+    kicker: string;
+    /** Headline text for the referral. */
+    title: string;
+    /** URL of the thumbnail image. */
+    imageUrl: string;
+    /** Alt text for the thumbnail image. */
+    imageAlt?: string;
+    /**
+     * Publish time shown beneath the title. Accepts a `Date` or any value the
+     * `Date` constructor understands (e.g. an ISO string). Omit to hide the time.
+     */
+    time?: Date | string | number;
+}
+/**
+ * Anchor [target](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target)
+ * for a referral link. The standard keywords are suggested, but any named
+ * browsing context is allowed.
+ */
+export type LinkTarget = '_self' | '_blank' | '_parent' | '_top' | (string & {});
 export interface Referrals {
     statusCode: number;
     message: string;
@@ -30,7 +57,7 @@ export interface Article {
     authors: Author[];
     kicker: Kicker;
     content_elements: unknown[];
-    headline_category?: unknown;
+    headline_category?: string;
     content?: {
         third_party?: unknown;
     };