@financial-times/cp-content-pipeline-ui 6.15.6-beta.0 → 7.0.0

package/src/components/RichText/index.tsx

@@ -34,8 +34,12 @@ import {
   TableRow,
 } from './BasicComponents'
 
-import type { StructuredContentFragment } from '@financial-times/cp-content-pipeline-client'
+import type {
+  StructuredContentFragment,
+  ReferenceMapping,
+} from '@financial-times/cp-content-pipeline-client'
 import { ContentTreeWorkarounds } from '@financial-times/cp-content-pipeline-schema'
+import { mapNodeToReference } from '@financial-times/cp-content-pipeline-schema/lib/resolvers/content-tree/references'
 import TableBody from '../Table/TableBody'
 import { TableCell } from '../Table/TableCell'
 import {
@@ -46,17 +50,33 @@ import {
 } from '../Scrollytelling'
 import { ScrollyImage } from '../Scrollytelling/ScrollyImage'
 import YoutubeVideo from '../YoutubeVideo'
+import { ContentProps } from '../types'
 
 import RichTextContext from './context'
 
-export type RichTextComponentMapRecord = Partial<
-  Record<
-    ContentTreeWorkarounds.AnyNode['type'] | 'fallback',
-    // using any here, no easy way to make a type that works for all the potential renderers
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    JSXElementConstructor<any>
+// A helper type that takes a content tree type identifier and maps it to the
+// object that is returned in an accompanying reference
+type mapComponentToReference<T extends ContentTreeWorkarounds.AnyNode['type']> =
+  T extends keyof typeof mapNodeToReference
+    ? (typeof mapNodeToReference)[T] extends keyof ReferenceMapping
+      ? ReferenceMapping[(typeof mapNodeToReference)[T]]
+      : never
+    : Record<string, never>
+
+// Partial record of content tree nodes and their associated reference types
+export type RichTextComponentMapRecord = {
+  [T in
+    | ContentTreeWorkarounds.AnyNode
+    | { type: 'fallback' } as T['type']]?: JSXElementConstructor<
+    React.PropsWithChildren<
+      T['type'] extends 'fallback'
+        ? unknown
+        : ContentProps<
+            T & mapComponentToReference<Exclude<T['type'], 'fallback'>>
+          >
+    >
   >
->
+}
 
 export const ComponentsContext = createContext<
   RichTextComponentMapRecord | undefined
@@ -165,16 +185,19 @@ const RichTextChild: React.FC<RichTextChildProps> = ({
           .filter(Boolean)
       : []
 
-    const reference =
+    const reference:
+      | StructuredContentFragment['references'][number]
+      | Record<string, never> =
       typeof node.data?.referenceIndex === 'number'
-        ? references[node.data?.referenceIndex]
+        ? references[node.data?.referenceIndex] ?? {}
         : {}
 
     return (
       <RichTextContext.Provider value={RichText}>
         <Component
-          {...node}
-          {...reference}
+          // HACK:20240808:IM TypeScript fails to unify the content types here
+          // and I'm not sure why :(
+          content={{ ...node, ...reference } as never}
           key={parentIndex}
           parentIndex={parentIndex}
         >

package/src/components/Scrollytelling/ScrollyImage.tsx

@@ -1,8 +1,8 @@
-import { ContentTree } from '@financial-times/content-tree'
-import { ScrollyImageFragment } from '@financial-times/cp-content-pipeline-client'
 import React, { useContext } from 'react'
 import { BreakpointGetter, FallbackImage, Sources } from '../ImageSet'
 import { ScrollyIDContext } from '.'
+import { ContentProps } from '../types'
+import type * as ComponentWorkarounds from '../Workarounds'
 
 const scrollyGetBreakpoints: BreakpointGetter = (image) => {
   switch (image.format) {
@@ -25,9 +25,12 @@ const scrollyGetBreakpoints: BreakpointGetter = (image) => {
   }
 }
 
-export const ScrollyImage: React.FC<
-  ContentTree.ScrollyImage & ScrollyImageFragment
-> = ({ picture }) => {
+interface ScrollyImageProps
+  extends ContentProps<ComponentWorkarounds.ScrollyImage> {}
+
+export const ScrollyImage: React.FC<ScrollyImageProps> = ({
+  content: { picture },
+}) => {
   const scrollyId = useContext(ScrollyIDContext)
 
   if (!picture?.images) {
@@ -47,7 +50,7 @@ export const ScrollyImage: React.FC<
           getBreakpoints={scrollyGetBreakpoints}
         />
         <FallbackImage
-          image={picture.fallbackImage}
+          content={{ image: picture.fallbackImage }}
           imageType={picture.imageType}
           className="n-scrollytelling__image"
           inSourceSet={true}
@@ -61,4 +64,4 @@ export const ScrollyImage: React.FC<
       )}
     </figure>
   )
-}
+}

package/src/components/Scrollytelling/index.tsx

@@ -3,14 +3,16 @@ import type { ContentTree } from '@financial-times/content-tree'
 import classnames from 'classnames'
 import type scrollytelling from '@financial-times/n-scrollytelling-image/server'
 import { ParagraphContext } from '../Paragraph'
+import { ContentProps } from '../types'
 
 export const ScrollyIDContext = createContext<string | null>(null)
 
+interface ScrollyBlockProps
+  extends ContentProps<ContentTree.transit.ScrollyBlock> {}
+
 export const ScrollyBlock: React.FC<
-  React.PropsWithChildren<Omit<ContentTree.ScrollyBlock, 'children'>> & {
-    parentIndex: number
-  }
-> = ({ children, theme, parentIndex }) => (
+  React.PropsWithChildren<ScrollyBlockProps>
+> = ({ content: { theme }, children, parentIndex }) => (
   <div
     className="n-content-layout n-content-layout--scrollytelling"
     data-layout-name="auto"
@@ -42,9 +44,12 @@ type ScrollySectionOptions = Pick<
 const ScrollySectionOptionsContext =
   createContext<ScrollySectionOptions | null>(null)
 
+interface ScrollySectionProps
+  extends ContentProps<ContentTree.transit.ScrollySection> {}
+
 export const ScrollySection: React.FC<
-  React.PropsWithChildren<ContentTree.ScrollySection>
-> = ({ children, display, noBox, position, transition }) => (
+  React.PropsWithChildren<ScrollySectionProps>
+> = ({ content: { display, noBox, position, transition }, children }) => (
   <ScrollySectionOptionsContext.Provider
     value={{ display, noBox, position, transition }}
   >
@@ -55,8 +60,10 @@ export const ScrollySection: React.FC<
 type ScrollytellingDisplaySuffix =
   scrollytelling.ScrollytellingOptionsMap['display'][keyof scrollytelling.ScrollytellingOptionsMap['display']]
 
+interface ScrollyCopyProps extends ContentProps<ContentTree.ScrollyCopy> {}
+
 export const ScrollyCopy: React.FC<
-  React.PropsWithChildren<ContentTree.ScrollyCopy>
+  React.PropsWithChildren<ScrollyCopyProps>
 > = ({ children }) => {
   const { display, noBox, position, transition } = useContext(
     ScrollySectionOptionsContext
@@ -100,9 +107,12 @@ export const ScrollyCopy: React.FC<
   )
 }
 
+interface ScrollyHeadingProps
+  extends ContentProps<ContentTree.ScrollyHeading> {}
+
 export const ScrollyHeading: React.FC<
-  React.PropsWithChildren<ContentTree.ScrollyHeading>
-> = ({ children, level }) => {
+  React.PropsWithChildren<ScrollyHeadingProps>
+> = ({ content: { level }, children }) => {
   const classNames = classnames(
     'n-scrollytelling__overlay-text',
     `n-scrollytelling__overlay-text--text-style-${level}`

package/src/components/Table/TableBody.tsx

@@ -1,9 +1,13 @@
 import { ContentTreeWorkarounds } from '@financial-times/cp-content-pipeline-schema'
 import React from 'react'
+import { ContentProps } from '../types'
 
-const TableBody: React.FC<
-  React.PropsWithChildren<ContentTreeWorkarounds.TableBody>
-> = ({ children }) => {
+interface TableBodyProps
+  extends ContentProps<ContentTreeWorkarounds.TableBody> {}
+
+const TableBody: React.FC<React.PropsWithChildren<TableBodyProps>> = ({
+  children,
+}) => {
   const [headerRow, ...bodyRows] = React.Children.toArray(children)
 
   return (

package/src/components/Table/TableCell.tsx

@@ -2,20 +2,22 @@ import React, { useContext } from 'react'
 import type { ContentTreeWorkarounds } from '@financial-times/cp-content-pipeline-schema'
 import { ColumnSettingsContext } from '.'
 import classNames from 'classnames'
+import { ContentProps } from '../types'
 
-type TableCellProps =
-  React.PropsWithChildren<ContentTreeWorkarounds.TableCell> & {
-    parentIndex: number
-  }
-export const TableCell: React.FC<TableCellProps> = (props) => {
+interface TableCellProps
+  extends ContentProps<ContentTreeWorkarounds.TableCell> {}
+
+export const TableCell: React.FC<React.PropsWithChildren<TableCellProps>> = (
+  props
+) => {
   const allColumnSettings = useContext(ColumnSettingsContext)
   const columnSettings: ContentTreeWorkarounds.TableColumnSettings =
-    allColumnSettings[props.parentIndex] ?? {
+    (props.parentIndex ? allColumnSettings[props.parentIndex] : undefined) ?? {
       hideOnMobile: false,
       sortable: false,
     }
 
-  return props.heading ? (
+  return props.content.heading ? (
     <th
       className={classNames({
         'n-content-body__table-cell--hide-mobile': columnSettings.hideOnMobile,

package/src/components/Table/index.tsx

@@ -1,21 +1,24 @@
 import type { ContentTreeWorkarounds } from '@financial-times/cp-content-pipeline-schema'
 import React, { createContext } from 'react'
 import classNames from 'classnames'
+import { ContentProps } from '../types'
 
 export const ColumnSettingsContext = createContext<
   ContentTreeWorkarounds.TableColumnSettings[]
 >([])
 
-const Table: React.FC<
-  React.PropsWithChildren<ContentTreeWorkarounds.Table>
-> = ({
+interface TableProps extends ContentProps<ContentTreeWorkarounds.Table> {}
+
+const Table: React.FC<React.PropsWithChildren<TableProps>> = ({
   children,
-  compact,
-  layoutWidth,
-  stripes,
-  responsiveStyle,
-  columnSettings,
-  collapseAfterHowManyRows,
+  content: {
+    compact,
+    layoutWidth,
+    stripes,
+    responsiveStyle,
+    columnSettings,
+    collapseAfterHowManyRows,
+  },
 }) => {
   return (
     <ColumnSettingsContext.Provider value={columnSettings}>

package/src/components/Topper/Picture.tsx

@@ -3,6 +3,8 @@ import React from 'react'
 import type { TopperFragment } from '@financial-times/cp-content-pipeline-client'
 
 import { AliasedBreakpoints, BreakpointGetter, Sources } from '../ImageSet'
+import { PictureOverrideWrapper } from '../ImageOverrideWrappers'
+import { ContentTree } from '@financial-times/content-tree'
 
 const topperGetBreakpointsMap: Partial<
   Record<TopperFragment['__typename'], BreakpointGetter>
@@ -64,12 +66,13 @@ const topperGetBreakpointsMap: Partial<
   },
 }
 
-type PictureProps = {
+export type PictureProps = {
   topper: TopperFragment
   alt?: string
 }
 
-const Picture: React.FC<PictureProps> = ({ topper, alt = '' }) => {
+const Picture: React.FC<PictureProps> = (props) => {
+  const { topper, alt = '' } = props
   if (!('images' in topper) || !topper.fallbackImage) {
     return null
   }
@@ -77,17 +80,19 @@ const Picture: React.FC<PictureProps> = ({ topper, alt = '' }) => {
   return (
     <figure className="o-topper__visual">
       <picture className="o-topper__picture" key="responsive-images">
-        <Sources
-          images={topper.images}
-          getBreakpoints={topperGetBreakpointsMap[topper.__typename]}
-        />
+        <PictureOverrideWrapper {...props}>
+          <Sources
+            images={topper.images as readonly ContentTree.Image[]}
+            getBreakpoints={topperGetBreakpointsMap[topper.__typename]}
+          />
 
-        <img
-          alt={alt}
-          className="o-topper__image"
-          src={topper.fallbackImage.sourceSet[0]?.url}
-          key="fallback-image"
-        />
+          <img
+            alt={alt}
+            className="o-topper__image"
+            src={topper.fallbackImage.sourceSet[0]?.url}
+            key="fallback-image"
+          />
+        </PictureOverrideWrapper>
       </picture>
       {topper.fallbackImage.caption ||
       topper.__typename === 'DeepPortraitTopper' ||

package/src/components/Topper/index.tsx

@@ -147,10 +147,13 @@ const Topper: React.FC<TopperProps> = ({
             />
             {isLiveBlog && isFlourish ? (
               <Flourish
-                id={topper.leadFlourish.id || ''}
-                flourishType={topper.leadFlourish.type || ''}
-                description={topper.leadFlourish.description || ''}
-                fallbackImage={topper.leadFlourish.fallbackImage || ''}
+                content={{
+                  type: 'flourish',
+                  id: topper.leadFlourish.id ?? '',
+                  flourishType: topper.leadFlourish.type ?? '',
+                  description: topper.leadFlourish.description ?? '',
+                  fallbackImage: topper.leadFlourish.fallbackImage,
+                }}
                 iFrame={true}
                 inArticleBody={false}
               />

package/src/components/Tweet/index.tsx

@@ -1,8 +1,10 @@
 import React from 'react'
 import type { ContentTree } from '@financial-times/content-tree'
-import { TweetFragment } from '@financial-times/cp-content-pipeline-client'
+import { ContentProps } from '../types'
 
-const Tweet: React.FC<ContentTree.Tweet & TweetFragment> = (tweet) => {
+interface TweetProps extends ContentProps<ContentTree.Tweet> {}
+
+const Tweet: React.FC<TweetProps> = ({ content: tweet }) => {
   if (tweet.html) {
     return (
       <div

package/src/components/Video/index.tsx

@@ -1,12 +1,10 @@
 import React from 'react'
-import { VideoFragment } from '@financial-times/cp-content-pipeline-client'
+import { ContentProps } from '../types'
 import { ContentTreeWorkarounds } from '@financial-times/cp-content-pipeline-schema'
 
-const Video: React.FC<VideoFragment & ContentTreeWorkarounds.Video> = ({
-  id,
-  embedded,
-  title,
-}) => {
+interface VideoProps extends ContentProps<ContentTreeWorkarounds.Video> {}
+
+const Video: React.FC<VideoProps> = ({ content: { id, embedded, title } }) => {
   return (
     <div
       className="n-content-video n-content-video--internal"

package/src/components/Workarounds.ts

@@ -0,0 +1,188 @@
+import type { ContentTree } from '@financial-times/content-tree'
+import {
+  ConceptFragment,
+  TranscriptFragment,
+} from '@financial-times/cp-content-pipeline-client'
+import type { ContentTreeWorkarounds } from '@financial-times/cp-content-pipeline-schema'
+import type {
+  LiteralToPrimitiveDeep,
+  SetFieldType,
+  SetOptional,
+  Simplify,
+} from 'type-fest'
+
+// Analogous to the Content Tree workarounds we use in the schema package,
+// these are workarounds for Content Tree types passed to components. These
+// differ insofar as they also include the reference type for nodes, i.e., they
+// are the ContentTree.full types to schema's ContentTree.transit types.
+// Similarly, we should aim to reduce these divergences by either adding them
+// to Content Tree or finding alternative ways of resolving them in our API.
+// Unlike the schema's workarounds, I've opted for a more declarative, verbose
+// approach to listing the differences between the workarounds and the original
+// types, with the hope that the differences can be fixed more incrementally.
+
+/**
+ * Helper type to extend partial/undefined fields to also be null. Optional
+ * fields in the Content Tree are represented by a partial field, but are
+ * represented by null (abstracted by the Maybe type) in the content pipeline.
+ */
+type PartialToMaybe<T> = Simplify<{
+  [K in keyof T]: Extract<T[K], undefined> extends never ? T[K] : T[K] | null
+}>
+/**
+ * Helper type to apply PartialToMaybe mapper type to each object field
+ * recursively.
+ */
+type PartialToMaybeDeep<T> = T extends object
+  ? PartialToMaybe<{
+      [K in keyof T]: PartialToMaybeDeep<T[K]>
+    }>
+  : T
+/**
+ * Helper type to convert arrays to readonly arrays. Content Tree arrays are
+ * mutable but the arrays we return from our API are expected to be readonly. We
+ * should explore which assumption is correct and match that in the other
+ * declaration file.
+ */
+type ReadonlyArrays<T> = {
+  [K in keyof T]: ReadonlyArray<T[K]>
+}
+// define conditional type separately so that it distributes the mapping over
+// union types (e.g., to avoid removing the undefined from a union)
+type ReadonlyArray<T> = T extends Array<infer Item> ? readonly Item[] : T
+
+export type TeaserConcept = PartialToMaybe<
+  ReadonlyArrays<
+    SetOptional<
+      ContentTree.TeaserConcept,
+      'apiUrl' | 'directType' | 'predicate' | 'prefLabel' | 'type' | 'types'
+    >
+  >
+>
+
+export type Image = PartialToMaybe<
+  ReadonlyArrays<
+    LiteralToPrimitiveDeep<
+      SetOptional<ContentTree.Image, 'width' | 'height' | 'sourceSet'>
+    >
+  >
+>
+
+export type Teaser = PartialToMaybeDeep<
+  LiteralToPrimitiveDeep<
+    SetOptional<
+      SetFieldType<
+        SetFieldType<
+          ContentTree.Teaser,
+          'metaLink' | 'metaAltLink',
+          TeaserConcept
+        >,
+        'image',
+        Omit<Image, 'id' | 'format'>
+      >,
+      'type' | 'metaLink' | 'metaAltLink' | 'indicators' | 'image'
+    >
+  >
+>
+
+export type Recommended = PartialToMaybe<
+  ContentTreeWorkarounds.Recommended & {
+    teaser?: Teaser
+  }
+>
+
+export type ImageSetPicture = PartialToMaybe<
+  ReadonlyArrays<
+    SetOptional<
+      SetFieldType<
+        SetFieldType<ContentTree.ImageSetPicture, 'fallbackImage', Image>,
+        'images',
+        Image[]
+      >,
+      'caption' | 'credit'
+    >
+  >
+>
+
+export type ImageSet = PartialToMaybe<
+  SetOptional<
+    SetFieldType<
+      ContentTree.ImageSet | ContentTree.LayoutImage,
+      'picture',
+      ImageSetPicture
+    >,
+    'picture'
+  >
+>
+
+export type ScrollyImage = PartialToMaybe<
+  SetOptional<
+    SetFieldType<ContentTree.ScrollyImage, 'picture', ImageSetPicture>,
+    'picture'
+  >
+>
+
+type ClipFormat = 'standard-inline' | 'mobile'
+interface ClipSource {
+  audioCodec?: string
+  binaryUrl: string
+  duration?: number
+  mediaType: string
+  pixelHeight?: number
+  pixelWidth?: number
+  videoCodec?: string
+}
+export type Clip = PartialToMaybeDeep<
+  ReadonlyArrays<{
+    format?: ClipFormat
+    dataSource: ClipSource[]
+    poster?: string
+  }>
+>
+interface ClipCaption {
+  mediaType?: string
+  url?: string
+}
+type ClipTranscript = TranscriptFragment
+export type ClipAccessibility = PartialToMaybeDeep<
+  ReadonlyArrays<{
+    captions?: ClipCaption[]
+    transcript?: ClipTranscript
+  }>
+>
+interface ClipSetReferences {
+  id: string
+  type: string
+  accessibility?: ClipAccessibility
+  noAudio?: boolean
+  caption?: string
+  credits?: string
+  description?: string
+  displayTitle?: string
+  contentWarning?: string[]
+  source?: string
+  subtitle?: string
+  publishedDate?: string
+  clips?: Clip[]
+}
+
+export type ClipSet = PartialToMaybeDeep<
+  ReadonlyArrays<
+    (ContentTreeWorkarounds.OldClip | ContentTreeWorkarounds.ClipSet) &
+      ClipSetReferences
+  >
+>
+
+export type RawImage = ContentTreeWorkarounds.RawImage & {
+  image: Image
+}
+
+export type MainImageRaw = ContentTreeWorkarounds.MainImageRaw & {
+  image: Image
+}
+
+export type Author = PartialToMaybe<
+  ContentTreeWorkarounds.Author & {
+    concept?: ConceptFragment
+  }
+>

package/src/components/YoutubeVideo/index.tsx

@@ -1,9 +1,10 @@
 import React from 'react'
-import { ContentTreeWorkarounds } from '@financial-times/cp-content-pipeline-schema'
+import { ContentTree } from '@financial-times/content-tree'
+import { ContentProps } from '../types'
 
-const YoutubeVideo: React.FC<ContentTreeWorkarounds.YoutubeVideo> = ({
-  url,
-}) => {
+interface YoutubeVideoProps extends ContentProps<ContentTree.YoutubeVideo> {}
+
+const YoutubeVideo: React.FC<YoutubeVideoProps> = ({ content: { url } }) => {
   try {
     const parsed = new URL(url)
     const id = parsed.searchParams.get('v')

package/src/components/types.ts

@@ -0,0 +1,6 @@
+import { ContentTree } from '@financial-times/content-tree'
+
+export interface ContentProps<T extends ContentTree.Node> {
+  content: T
+  parentIndex?: number
+}

package/src/context.ts

@@ -1,4 +1,13 @@
-import { createContext } from 'react'
+import { createContext, PropsWithChildren } from 'react'
+
+import type { FallbackImageProps, ImageSetProps } from './components/ImageSet'
+import type { PictureProps } from './components/Topper/Picture'
+
+export type PresentationOverrideTypes = {
+  FallbackImage: React.FC<PropsWithChildren<FallbackImageProps>>
+  ImageSet: React.FC<PropsWithChildren<ImageSetProps>>
+  Picture: React.FC<PropsWithChildren<PictureProps>>
+}
 
 // HACK:20240618:IM we're still not at the point where all components behave
 // correctly across all consumers. this context allows consumers to
@@ -9,3 +18,15 @@ export interface PresentationFlags {
   reduceFullBleedImages?: boolean
 }
 export const PresentationFlagsContext = createContext<PresentationFlags>({})
+
+// COMPLEX:20240815:RB similarly to PresentationFlags, some consumers need
+// to customise the presentation and behaviour of some components. This should be
+// replaced by more transparent support in the consumer with the aim of removing
+// this context.
+export interface PresentationOverrides {
+  FallbackImage?: PresentationOverrideTypes['FallbackImage']
+  ImageSet?: PresentationOverrideTypes['ImageSet']
+  Picture?: PresentationOverrideTypes['Picture']
+}
+export const PresentationOverridesContext =
+  createContext<PresentationOverrides>({})

package/src/index.ts

@@ -34,4 +34,7 @@ export {
   Strikethrough,
   Cite,
 } from './components/RichText/BasicComponents'
-export { PresentationFlagsContext } from './context'
+export {
+  PresentationFlagsContext,
+  PresentationOverridesContext,
+} from './context'