@newskit-render/standalone-components 2.0.1-alpha.0 → 2.1.0-alpha.0

package/README.md

@@ -18,155 +18,21 @@ For npm:
 
 ## 1. Article recommendations
 
-- Endpoint `/api/recommendations` is used in the `core` package which returns a list of recommendations articles.
-
-- Endpoint accepts the following params
-
-  - `articleId`
-  - `userId`
-
-- Endpoint used in the following files in the `core` package
-
-  - `packages/core/pages/[section]/[articleId]/[articleSlug].tsx`
-  - `packages/core/pages/[section]/[articleId]/relatedArticles.tsx`
-
-- recommendationsProvider: Provider function that accepts `articleId`, `publisher` and `userId`. The function will return an array of recommended articles.
-
-- ArticleRecommendation: a component that accepts `article` and `size`, where
-
-  - `article` is an object with the following properties:
-    - href: string // mandatory
-    - title: string // mandatory
-    - text: string // optional
-  - `size` can be `large` or `small`.
-  - `overrides` can be used to pass overrides to the component to handle the styling
-    ```typescript
-    overrides: {
-      spaceStack?: MQ<string>
-      card?: {
-        overrides?: {
-          stylePreset?: MQ<string>
-          mediaContainer?: {
-            spaceInline?: MQ<string>
-          }
-        }
-        media?: {
-          overrides: {
-            width?: string
-            height?: string
-          }
-        }
-      }
-      headline?: {
-        spaceStack?: MQ<string>
-        overrides: {
-          typographyPreset?: MQ<string>
-        }
-      }
-      text?: {
-        spaceStack?: MQ<string>
-        overrides: {
-          stylePreset?: MQ<string>
-          typographyPreset?: MQ<string>
-        }
-      }
-    }
-    ```
+Article recommendations implementation is split into two main components:
 
-### How to use
+- ArticleRecommendationsProvider
+- RecommendedArticleList
 
-First, you need to fetch some article recommendations with the recommendationsProvider function, then iterate over the returned array and use the ArticleRecommendation component to display them.
+### Article Recommendations Provider
 
-```typescript
-import React from 'react'
-import { Block, Grid, Cell } from 'newskit'
-import {
-  ArticleRecommendation,
-  recommendationsProvider,
-  Article,
-} from '@newskit-render/standalone-components'
-import { Publisher } from '@newskit-render/api'
-
-const Recommendations: React.FC<{
-  recommendations: Article[]
-}> = ({ recommendations }) => (
-  <Block data-testid="RelatedArticles">
-    <Grid xsMargin="space000">
-      {recommendations.map((article) => (
-        <Cell
-          key={article.title}
-          xs={12}
-          sm={6}
-          lg={3}
-          data-testid="RelatedArticlesVerticalCard"
-        >
-          <ArticleRecommendation article={article} size="large" />
-        </Cell>
-      ))}
-    </Grid>
-  </Block>
-)
-
-export default Recommendations
-
-export async function getServerSideProps(context) {
-  const recommendations = await recommendationsProvider({
-    articleId,
-    publisher: Publisher.SUN_UK,
-  })
-
-  return {
-    props: {
-      recommendations,
-    },
-  }
-}
-```
-
-## 2. Article Grid
-
-Article Grid - this is a grid element to display a list of articles with a customizable layout.
-
-The component takes the following props:
-
-```typescript
-export type ArticleGridProps = {
-  overrides?: {
-    rowGap?: MQ<string>
-    columnGap?: MQ<string>
-  }
-  columnCount?: MQ<string>
-  size: 'large' | 'small'
-  articles: Article[]
-}
-```
-
-### How to use
-
-The `columnCount` prop will determine the number of columns in the grid, it supports media query as well.
-
-```typescript
-const ArticleList: React.FC<{
-  articles: Article[]
-}> = ({ articles }) => (
-  <AricleGrid
-    columnCount={{ md: '1', lg: '2' }}
-    articles={articles}
-    size="large"
-  />
-)
-```
-
-## 3. Article Recommendations Provider
-
-The purpose of this component is to hold the dpaTemplates in the context, fetch the recommended articles and map them to the appropriate templates.
+This component as the name suggests is a React context provider. It will hold the digital personalisation templates (DPATemplates), fetch the recommended articles and map them to the appropriate template.
 
 The component takes the following props.
 
 ```typescript
 export type ArticleRecommendationsProviderProps = {
   articleId?: string
-  context?: ArticleRecommendationsProviderBaseContextType
+  context: ArticleRecommendationsProviderBaseContextType
   children: ReactNode
   config: Config
 }
@@ -183,30 +49,41 @@ export type Config = {
 }
 ```
 
-The `context` holds the `dpaTemplates`. The default context can be overridden or extended.
+The context holds the dpaTemplates dpaTemplate is a template, that holds information about the articles, ads and how they should be rendered on the screen.
 
 ```typescript
-const defaultContext: ArticleRecommendationsProviderContextType = {
+const context: ArticleRecommendationsProviderContextType = {
   dpaTemplates: [
     {
       templateId: 'list-1',
       columnCount: '1',
       size: 'small',
-      recommendedArticles: { totalArticlesCount: 4 },
-      adlibraryMPU: { totalArticlesCount: 0 },
+     {
+      templateId: 'list-1',
+      columnCount: '1',
+      size: 'small',
+      recommendedArticlesCount: 4,
+      ads: {
+        count: 3,
+        articlesMargin: 2,
+        options: {
+          id: 'dynamic-mpu',
+          className: 'nuk-ad-placeholder',
+          dataAdLabel: 'dynamicMpus',
+        },
+      },
     },
     {
       templateId: 'list-2',
       columnCount: { xs: '1', sm: '2', lg: '4' },
       size: 'large',
-      recommendedArticles: { totalArticlesCount: 8 },
-      adlibraryMPU: { totalArticlesCount: 0 },
+      recommendedArticlesCount: 8,
     },
   ],
 }
 ```
 
-Template props:
+dpa template props:
 
 `templateId` template identifier used to uniquely identify the template
 
@@ -214,11 +91,60 @@ Template props:
 
 `size` the size of the articles
 
-`recommendedArticles` and `adlibraryMPU` are the types of articles. These can be extended as well. Note the data fetching currently is done only for `recommendedArticles`
+`recommendedArticlesCount` is the number of the recommended articles
+`ads` is an optional object containing data for ads
+Ads props:
+`count` the number of ads that we want to have in the current template
+`articlesMargin` is the number of articles that you want to have in between the ads
+`options.id` will contain the prefix of the ad id(E.G dynamic-mpu-1, dynamic-mpu-2 etc.)
+`options.className` is the class name used for all ads
+`options.dataAdLabel` is the data attribute used for all ad
+
+### RecommendedArticleList
+
+This component should be a children of Article Recommendations provider. It's purpose is to render all articles and ads from a specific dpa template based on a template id
 
 ### Usage
 
+In order to use Article recommendations provider and recommended articles list you must wrap your page or the section where you want to display recommendations.
+
+You need to pass to Article recommendations provider the context object, that holds dpa templates and the config for Newskit API.
+
+Then you can use RecommenedArticleList as a children of ArticleRecommendationsProvider and pass it a template id, that is used as an id in one of the dpa templates.
+
+See example below:
+
 ```typescript
+
+const context: ArticleRecommendationsProviderContextType = {
+  dpaTemplates: [
+    {
+      templateId: 'list-1',
+      columnCount: '1',
+      size: 'small',
+     {
+      templateId: 'list-1',
+      columnCount: '1',
+      size: 'small',
+      recommendedArticlesCount: 4,
+      ads: {
+        count: 3,
+        articlesMargin: 2,
+        options: {
+          id: 'dynamic-mpu',
+          className: 'nuk-ad-placeholder',
+          dataAdLabel: 'dynamicMpus',
+        },
+      },
+    },
+    {
+      templateId: 'list-2',
+      columnCount: { xs: '1', sm: '2', lg: '4' },
+      size: 'large',
+      recommendedArticlesCount: 8,
+    },
+  ],
+}
 const Article: React.FC<ArticleSlug> = ({
   universalArticle,
   articleURL,
@@ -229,8 +155,10 @@ const Article: React.FC<ArticleSlug> = ({
   articleId,
   config,
 }) => (
-  <ArticleRecommendationsProvider articleId={articleId} config={config}>
-    <Highlights>
+  <ArticleRecommendationsProvider articleId={articleId} config={config} context={context}>
+      <RecommendedArticleList templateId="list-1" />
+        ...
+      <RecommendedArticleList templateId="list-2" />
   </ArticleRecommendationsProvider>
 )
 
@@ -247,59 +175,40 @@ export async function getServerSideProps(context) {
 }
 ```
 
-The `ArticleRecommendationsProvider` will fetch the recommended articles. Once the fetch is complete it will slice and map the articles to the dpaTemplates.
+<!--
+## 2. Article Grid
+
+Article Grid - this is a grid element to display a list of articles with a customizable layout.
 
-Example: The default context after the mapping will look like below
+The component takes the following props:
 
 ```typescript
-const defaultContext: ArticleRecommendationsProviderContextType = {
-  dpaTemplates: [
-    {
-      templateId: 'list-1',
-      columnCount: '1',
-      size: 'small',
-      recommendedArticles: [{ article }, ...], // 4 articles
-      adlibraryMPU: [],
-    },
-    {
-      templateId: 'list-2',
-      columnCount: { xs: '1', sm: '2', lg: '4' },
-      size: 'large',
-      recommendedArticles: [{ article }, ...], //8 articles
-      adlibraryMPU: [],
-    },
-  ],
+export type ArticleGridProps = {
+  overrides?: {
+    rowGap?: MQ<string>
+    columnGap?: MQ<string>
+  }
+  columnCount?: MQ<string>
+  size: 'large' | 'small'
+  articles: Article[]
 }
 ```
 
-The `ArticleList` component based on the `templateId` will get the correct article data from the context and it will use the `ArticleGrid` component to render the layout.
-
-```typescript
-const ArticleList: React.FC<{ templateId: string }> = ({ templateId }) => {
-  const context = useContext(
-    ArticleRecommendationsProviderContext
-  ) as ArticleRecommendationsProviderContextTypeWithArticles
-
-  const dpaTemplate = context.dpaTemplates.find(
-    (dpaTemplate) => dpaTemplate.templateId === templateId
-  )
-
-  if (!dpaTemplate) {
-    return null
-  }
+### How to use
 
-  const { recommendedArticles, columnCount, size } = dpaTemplate
-  return (
-    <AricleGrid
-      articles={recommendedArticles}
-      columnCount={columnCount}
-      size={size}
-    />
-  )
-}
+The `columnCount` prop will determine the number of columns in the grid, it supports media query as well.
 
-const Highlights: React.FC = () => <ArticleList templateId="list-1" />
-```
+```typescript
+const ArticleList: React.FC<{
+  articles: Article[]
+}> = ({ articles }) => (
+  <AricleGrid
+    columnCount={{ md: '1', lg: '2' }}
+    articles={articles}
+    size="large"
+  />
+)
+``` -->
 
 ## 4. Help-hub:
 
@@ -328,7 +237,7 @@ For obtaining the Algolia credentials, ask your manager
 If your team does not have account, you will have to request or create such
 
 Ask CSP for futher information about populating the data in Algolia. They can assist for getting the data from Salesforce.
-Slack channel: [#cps-support](https://newsuktechnology.slack.com/archives/CM0M0NFEE) 
+Slack channel: [#cps-support](https://newsuktechnology.slack.com/archives/CM0M0NFEE)
 
 ### How to use
 
@@ -461,163 +370,170 @@ export const baseContext: BaseContextOptions = {
   },
 }
 ```
+
 2.2 Properties of BaseContextOptions
 
-  1. baseUrl - relative url when the help hub landing page lives
+1. baseUrl - relative url when the help hub landing page lives
 
-  2. seo: - Used in the Header component
+2. seo: - Used in the Header component
 
-     - title: string
-     - description: string
-     - url: string
-     - siteHost: string
-     - hrefLang: string
+   - title: string
+   - description: string
+   - url: string
+   - siteHost: string
+   - hrefLang: string
 
-  3. navigationPrimary - Global property changes nav links in top banner area - Array of nav objects or false to have no nav
+3. navigationPrimary - Global property changes nav links in top banner area - Array of nav objects or false to have no nav
 
-    - nav?:
-      - text: string
-      - link: string
-      - icon: React.ReactElement<NewsKitIconProps>
-      - ariaLabel?: string
-    - title?: string
-    - logoSrc?: string (path to logo.svg)
-    - logoWidth?: string (width of logo)
-    - titlePosition?: string (uses css top property to ajust title position)
+   - nav?:
+     - text: string
+     - link: string
+     - icon: React.ReactElement<NewsKitIconProps>
+     - ariaLabel?: string
+   - title?: string
+   - logoSrc?: string (path to logo.svg)
+   - logoWidth?: string (width of logo)
+   - titlePosition?: string (uses css top property to ajust title position)
 
-  4. header - Property used to change the title value and styles of each page
+4. header - Property used to change the title value and styles of each page
 
-    - overlineOverrides
-       - typographyPreset: MQ
-       - stylePreset: MQ
-       - spaceStack: MQ
-    - title: string
-    - titleOverrides
-      - typographyPreset: MQ
-      - stylePreset: MQ
-      - spaceStack: string
-      - as: h1 | h2 | h3 | h4 | h5 | h6
-  
-    - description: string
-    - descriptionOverrides
-      - typographyPreset: MQ
-      - stylePreset: MQ
-      - spaceStack: string
-  
-    - backButtonOverrides
-      - spaceStack: MQ
-      - stylePreset: MQ
-      - typographyPreset: MQ
-      - iconSize: MQ
-  
-    - spaceStack: MQ
-    - showDivider: boolean
+   - overlineOverrides
+     - typographyPreset: MQ
+     - stylePreset: MQ
+     - spaceStack: MQ
+   - title: string
+   - titleOverrides
+
+     - typographyPreset: MQ
+     - stylePreset: MQ
+     - spaceStack: string
+     - as: h1 | h2 | h3 | h4 | h5 | h6
+
+   - description: string
+   - descriptionOverrides
+
+     - typographyPreset: MQ
+     - stylePreset: MQ
+     - spaceStack: string
+
+   - backButtonOverrides
+
+     - spaceStack: MQ
+     - stylePreset: MQ
+     - typographyPreset: MQ
+     - iconSize: MQ
 
-  5. searchBar: Property used to style the search bar container
+   - spaceStack: MQ
+   - showDivider: boolean
 
-    - spaceStack: MQ
+5. searchBar: Property used to style the search bar container
 
-  6. contentListView: Property used to style the results table
+   - spaceStack: MQ
 
-    - introduction: - Used to style the table title
-       - spaceStack: MQ
-    
-  7. articleNotFound: string - Warning message for when the article is not found
+6. contentListView: Property used to style the results table
 
-  8. searchResultEmpty: string - Warning message for when there is not search string
+   - introduction: - Used to style the table title
+     - spaceStack: MQ
 
-  9. spaceStack: MQ
+7. articleNotFound: string - Warning message for when the article is not found
 
-  10. inputPlaceholder: string - Search bar placeholder
+8. searchResultEmpty: string - Warning message for when there is not search string
 
-  11. footer: Global property
+9. spaceStack: MQ
+
+10. inputPlaceholder: string - Search bar placeholder
+
+11. footer: Global property
 
     - menuItemArray: [
       {
-        text: string
-        href: string
-        id: integer,
+      text: string
+      href: string
+      id: integer,
       }
-    ]
+      ]
     - legalText: string
 
-  12. footerOverrides: Global property
+12. footerOverrides: Global property
 
     - ariaLabel: string
     - menuItemOverrides:
+
       - stylePreset: MQ
       - typographyPreset: MQ
-  
+
     - menuOverrides:
+
       - spaceStack: MQ
       - backgroundColor: MQ
       - borderColor: MQ
       - padding: MQ
-  
+
     - legalTextOverrides:
       - spaceStack: MQ
       - stylePreset: MQ
       - typographyPreset: MQ
       - padding: MQ
 
-
-
-
-As said above, help hub consists of three pages and we will take a look on how to add each one of them individually. 
+As said above, help hub consists of three pages and we will take a look on how to add each one of them individually.
 
 Each page extend the above BaseContextOptions with their own properties:
 
 2.3 HelpHubLandingPageContextOptions
 
- 1. articlesTabelInfo
-    - title: string
-    - titleOverrides
-      - typographyPreset: MQ
-      - stylePreset: MQ
-      - spaceStack: string
-      - as: h1 | h2 | h3 | h4 | h5 | h6
-  2. mostReadArticles: [
-    {
-      - title: string
-      - objectID: string
-    }
-  ]
+1. articlesTabelInfo
+   - title: string
+   - titleOverrides
+     - typographyPreset: MQ
+     - stylePreset: MQ
+     - spaceStack: string
+     - as: h1 | h2 | h3 | h4 | h5 | h6
+2. mostReadArticles: [
+   {
+   - title: string
+   - objectID: string
+     }
+     ]
 
 2.4 ResultsPageContextOptions
 
-  1. hits: [
-    {
-      - title: string
-      - objectID: string
-      - content: string
-    }
-  ]
-  2. introductionProps: 
-    - title: string
-    - titleOverrides
-      - typographyPreset: MQ
-      - stylePreset: MQ
-      - spaceStack: string
-      - as: h1 | h2 | h3 | h4 | h5 | h6
-    - description: string
-    - showDivider: boolean
-  3. stylePreset: MQ<string>
-  4. showDividerByBreakpoint: boolean
+1. hits: [
+   {
+   - title: string
+   - objectID: string
+   - content: string
+     }
+     ]
+2. introductionProps:
+
+   - title: string
+   - titleOverrides
+     - typographyPreset: MQ
+     - stylePreset: MQ
+     - spaceStack: string
+     - as: h1 | h2 | h3 | h4 | h5 | h6
+   - description: string
+   - showDivider: boolean
+
+3. stylePreset: MQ<string>
+4. showDividerByBreakpoint: boolean
 
 2.5 ArticlePageContextOptions
 
-  1. introductionProps:
-    - titleOverrides
-      - typographyPreset: MQ
-      - stylePreset: MQ
-      - spaceStack: string
-      - as: h1 | h2 | h3 | h4 | h5 | h6
-  2. title: string
-  3. content: string
+1. introductionProps:
+
+   - titleOverrides
+     - typographyPreset: MQ
+     - stylePreset: MQ
+     - spaceStack: string
+     - as: h1 | h2 | h3 | h4 | h5 | h6
+
+2. title: string
+3. content: string
 
 Standalone-components package exports page components, page context, page context types (PageContextOptions) and a provider function for each page.
 
-2.6 Help-Hub Landing page. 
+2.6 Help-Hub Landing page.
 
 As stated above, landing page will display the most read articles. For now these articles are hardcoded and need to be passed to the Landing page (see example below). These articles must be already imported in Algolia in order for them to work.
 
@@ -764,7 +680,7 @@ export const getServerSideProps = async (context) => {
 }
 ```
 
-By default ResultsPage will return up to 20 results. This can be changed by adding a second parameter to `helpHubResultsProvider` 
+By default ResultsPage will return up to 20 results. This can be changed by adding a second parameter to `helpHubResultsProvider`
 
 ```typescript
 export const getServerSideProps = async (context) => {
@@ -837,4 +753,4 @@ export const getServerSideProps = async (context) => {
 
   return helpHubArticleProvider(context)
 }
-```
+```

package/dist/cjs/article-recommendations/components/AdPlaceholder.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+declare const AdPlaceHolder: React.FC<{
+    id: string;
+    height?: string;
+    maxWidth?: string;
+    className?: string;
+    dataAdLabel?: string;
+}>;
+export default AdPlaceHolder;