@newskit-render/standalone-components 0.0.0-006778a6b

package/README.md

@@ -0,0 +1,798 @@
+# @newskit-render/standalone-components
+
+## Overview
+
+The Standalone-components package contains components, that can live within or outside the Render application.
+
+## Getting started
+
+Install the package to start using it. Depending on your package manager, run:
+
+For yarn:
+`yarn add @newskit-render/standalone-components`
+
+For npm:
+`npm install @newskit-render/standalone-components`.
+
+## Components
+
+## 1. Article recommendations
+
+Article recommendations implementation is split into two main components:
+
+- ArticleRecommendationsProvider
+- RecommendedArticleList
+
+### Article Recommendations Provider
+
+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
+  children: ReactNode
+  config: Config
+}
+```
+
+`articleId` is required to get the recommended articles for the given article
+
+`config` is required to access NewsKit API to be able to fetch the recommended articles
+
+```typescript
+export type Config = {
+  newskitApiEnvUrl: string
+  newskitApiXApiKey: string
+}
+```
+
+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 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,
+    },
+  ],
+}
+```
+
+dpa template props:
+
+`templateId` template identifier used to uniquely identify the template
+
+`columnCount` together with the `totalArticlesCount` will determine the layout. Example: `list-1` will result in a 1x4 article grid, while `list-2` will result in a 4x2 grid on a large screen.
+
+`size` the size of the articles
+
+`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,
+  twitterUsername,
+  siteHost,
+  gscId,
+  user,
+  articleId,
+  config,
+}) => (
+  <ArticleRecommendationsProvider articleId={articleId} config={config} context={context}>
+      <RecommendedArticleList templateId="list-1" />
+        ...
+      <RecommendedArticleList templateId="list-2" />
+  </ArticleRecommendationsProvider>
+)
+
+export async function getServerSideProps(context) {
+  return {
+    props: {
+      config: {
+        newskitApiEnvUrl,
+        newskitApiXApiKey,
+      },
+      articleId,
+    },
+  }
+}
+```
+
+<!--
+## 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"
+  />
+)
+``` -->
+
+## 4. Help-hub:
+
+Help-Hub is a section of a website on which your customers can search for a specific problem and find some help to resolve it. It consists of three parts:
+
+1. Landing page: Where the user is able to search their queries and see the most common questions.
+2. Search results page: Displaying the relevant results based on the user query. To facilitate the search we are using Algolia.
+3. Help article page: Page displaying a specific search result.
+
+The Help-hub pages will work independent of other components and are customized using the context.
+
+### Prerequisite
+
+Help-hub is designed to work only with Next.js, so make sure that your app is running with Next.js
+Before integrating Help-hub, you must ensure that you have an Algolia (Search API) account. If you don't have an account, please create one. After you have obtained an Algolia account, you need to insert the data in it (see docs: https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/#pushing-your-data-to-an-algolia-index). The data must follow the following format:
+
+```typescript
+{
+  title: string
+  objectID: string
+  content: string
+}
+```
+
+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)
+
+### How to use
+
+#### 1. Credentials
+
+You need to have Algolia credentials as enviromnent variables:
+
+- ALGOLIA_API_KEY
+- ALGOLIA_APP_ID
+- ALGOLIA_INDEX
+
+#### 2. Implementation
+
+2.1. Context
+
+This is the default context for all the pages use out of the box
+
+```
+export const baseContext: BaseContextOptions = {
+  baseUrl: '/help-hub',
+  seo: {
+    title: 'Help Hub',
+    description: '',
+    url: '',
+    siteHost: '',
+    hrefLang: '',
+  },
+  navigationPrimary: {
+    nav: [
+      {
+        text: 'Section One',
+        link: '/section-one',
+        icon: null,
+        ariaLabel: 'Section One Link',
+      },
+      {
+        text: 'Section Two',
+        link: '/section-two',
+        icon: null,
+        ariaLabel: 'Section Two Link',
+      },
+      {
+        text: 'Section Three',
+        link: '/section-three',
+        icon: null,
+        ariaLabel: 'Section Three Link',
+      },
+    ],
+  },
+  header: {
+    overlineOverrides: {
+      typographyPreset: {
+        xs: 'utitityLabel020',
+        sm: 'utitityLabel030',
+      },
+      stylePreset: 'inkBrand010',
+      marginBlockEnd: 'space040',
+    },
+    title: '',
+    titleOverrides: {
+      typographyPreset: { xs: 'utilityHeading040', sm: 'utilityHeading050' },
+      stylePreset: 'inkContrast',
+      marginBlockEnd: 'space000',
+      as: 'h1',
+    },
+    description: '',
+    descriptionOverrides: {
+      typographyPreset: { xs: 'utilityBody020', sm: 'utilityBody030' },
+      stylePreset: 'inkBase',
+      marginBlockEnd: 'space000',
+    },
+    backButtonOverrides: {
+      marginBlockEnd: { xs: 'space050', sm: 'space060', md: 'space070' },
+      stylePreset: 'buttonOutlinedSecondary',
+      typographyPreset: 'utilityButton010',
+      iconSize: 'iconSize010',
+    },
+    marginBlockEnd: { xs: 'space050', sm: 'space060', md: 'space040' },
+    showDivider: false,
+  },
+  searchBar: {
+    marginBlockEnd: { xs: 'space060', sm: 'space080' },
+    color: 'inkBase',
+    placeholder: {
+      color: 'inkSubtle',
+      typographyPreset: 'utilityBody030',
+    },
+    icon: {
+      color: 'inkBrand010',
+      position: 'right' as const,
+    },
+    autocomplete: {
+      color: 'interactivePrimary030',
+    },
+    border: {
+      style: '1px solid',
+      color: 'interactiveInput020',
+    },
+    outline: {
+      style: 'outlineStyleDefault',
+      color: 'outlineColorDefault',
+      width: 'outlineWidthDefault',
+    },
+  },
+  contentListView: {
+    introduction: {
+      marginBlockEnd: 'space060',
+    },
+  },
+  articleNotFound: "Sorry, we can't find the article you are looking for",
+  searchResultEmpty: "Sorry, we can't find the result you are looking for",
+  marginBlockEnd: { xs: 'space070', md: 'space090' },
+  inputPlaceholder: 'Describe your issue',
+  footer: {
+    menuItemArray: [
+      { text: 'About us', href: '/about-us', id: 1 },
+      {
+        text: 'Privacy & cookie policy',
+        href: 'http://www.newsprivacy.co.uk/',
+        id: 3,
+      },
+      { text: 'Terms & conditions', href: '/terms-and-conditions', id: 4 },
+    ],
+    legalText: `© NewsKit Limited ${new Date().getFullYear()}.
+      Registered in England No. 000000. Registered office: 1 London Bridge Street, SE1 9GF.`,
+  },
+  footerOverrides: {
+    ariaLabel: 'Footer Menu',
+    menuItemOverrides: {
+      stylePreset: 'baseInteractivePrimary030',
+      typographyPreset: 'utilityButton020',
+    },
+    menuOverrides: {
+      marginBlockEnd: 'space050',
+      backgroundColor: 'interface010',
+      borderColor: 'interface050',
+      padding: {
+        md: 'sizing090',
+        xs: 'sizing040',
+      },
+    },
+    legalTextOverrides: {
+      marginBlockEnd: 'space050',
+      stylePreset: 'legalText',
+      typographyPreset: 'utilityMeta010',
+      padding: {
+        md: 'sizing100',
+        xs: 'sizing060',
+      },
+    },
+  },
+}
+```
+
+2.2 Properties of BaseContextOptions
+
+1. baseUrl - relative url when the help hub landing page lives
+
+2. seo: - Used in the Header component
+
+   - 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
+
+   - 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
+
+   - overlineOverrides
+     - typographyPreset: MQ
+     - stylePreset: MQ
+     - marginBlockEnd: MQ
+   - title: string
+   - titleOverrides
+
+     - typographyPreset: MQ
+     - stylePreset: MQ
+     - marginBlockEnd: string
+     - as: h1 | h2 | h3 | h4 | h5 | h6
+
+   - description: string
+   - descriptionOverrides
+
+     - typographyPreset: MQ
+     - stylePreset: MQ
+     - marginBlockEnd: string
+
+   - backButtonOverrides
+
+     - marginBlockEnd: MQ
+     - stylePreset: MQ
+     - typographyPreset: MQ
+     - iconSize: MQ
+
+   - marginBlockEnd: MQ
+   - showDivider: boolean
+
+5. searchBar: Property used to style the search bar container
+
+   - marginBlockEnd: MQ
+   - color: string - Search bar input text color
+   - placeholder
+     - color: string - Placeholder text color
+     - typographyPreset: string
+   - icon
+     - color: string - Search icon color
+     - position: string - Position of the icon relative to the search input text.
+   - autocomplete
+     - color: string - Autocomplete results text color
+   - border
+     - style: string - Style of the search bar border.
+     - color: string - Border color.
+   - outline
+     - style: string - Style of the search bar outline
+     - color: string - outline color
+     - width: string - outline width
+
+6. contentListView: Property used to style the results table
+
+   - introduction: - Used to style the table title
+     - marginBlockEnd: MQ
+
+7. articleNotFound: string - Warning message for when the article is not found
+
+8. searchResultEmpty: string - Warning message for when there is not search string
+
+9. marginBlockEnd: MQ
+
+10. inputPlaceholder: string - Search bar placeholder
+
+11. footer: Global property
+
+    - menuItemArray: [
+      {
+      text: string
+      href: string
+      id: integer,
+      }
+      ]
+    - legalText: string
+
+12. footerOverrides: Global property
+
+    - ariaLabel: string
+    - menuItemOverrides:
+
+      - stylePreset: MQ
+      - typographyPreset: MQ
+
+    - menuOverrides:
+
+      - marginBlockEnd: MQ
+      - backgroundColor: MQ
+      - borderColor: MQ
+      - padding: MQ
+
+    - legalTextOverrides:
+      - marginBlockEnd: 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.
+
+Each page extend the above BaseContextOptions with their own properties:
+
+2.3 HelpHubLandingPageContextOptions
+
+1. articlesTabelInfo
+   - title: string
+   - titleOverrides
+     - typographyPreset: MQ
+     - stylePreset: MQ
+     - marginBlockEnd: 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
+     - marginBlockEnd: 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
+     - marginBlockEnd: string
+     - as: h1 | h2 | h3 | h4 | h5 | h6
+
+2. title: string
+3. content: string
+4. searchBreadcrumbContext?:
+   - searchBreadcrumbProps?: Omit<BreadcrumbsProps, 'children'> see Newskit
+   - notFoundBreadcrumbProps?: Omit<BreadcrumbsProps, 'children'>
+   - searchBreadcrumbItemOne?: string
+   - searchBreadcrumbItemTwo?: 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.
+
+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.
+
+This example shows how to set up the page and override the page context with your own values:
+
+```typescript
+import React, { useContext } from 'react'
+import newrelic from 'newrelic'
+import {
+  AlgoliaCredentials,
+  HelpHubLandingPage,
+  helpHubLandingPageContext,
+  HelpHubLandingPageContextOptions,
+  helpHubLandingPageProvider,
+} from '@newskit-render/standalone-components'
+import { createThemeDropdownObject } from '../../helpers/createThemeDropdownObject'
+import { AppContext } from '../../context'
+import { addCacheHeaders } from '../../helpers/addCacheHeaders'
+
+const landingPageContext: Partial<HelpHubLandingPageContextOptions> = {
+  ...helpHubLandingPageContext,
+  header: {
+    title: 'Your custom title',
+  },
+  mostReadArticles: [
+    {
+      title: 'Sign-in with Google',
+      objectID: 'sign-with-google',
+    },
+    {
+      title:
+        'I am trying to share an article via Google+ but an error message keeps appearing',
+      objectID:
+        'i-am-trying-to-share-an-article-via-google-but-an-error-message-keeps-appearing',
+    },
+    {
+      title: 'How will I find out if I have won a competition?',
+      objectID: 'how-will-i-find-out-if-i-have-won-a-competition',
+    },
+    {
+      title: 'How do I login/reset my password?',
+      objectID: 'how-do-i-login-reset-my-password',
+    },
+    {
+      title: 'How do I cancel or change my pack?',
+      objectID: 'how-do-i-cancel-or-change-my-pack',
+    },
+    {
+      title: 'Can I share my Times & Sunday Times iPad subscription access?',
+      objectID: 'can-i-share-my-times-sunday-times-ipad-subscription-access',
+    },
+  ],
+}
+
+const LandingPage: React.FC<{
+  credentials: AlgoliaCredentials
+}> = (props) => {
+  const { theme, setTheme } = useContext(AppContext)
+  const themeDropdownObject = createThemeDropdownObject(setTheme)
+
+  return (
+    <HelpHubLandingPage
+      {...props}
+      context={landingPageContext}
+      customTheme={theme}
+      themeDropdownObject={themeDropdownObject}
+    />
+  )
+}
+
+export default LandingPage
+
+export const getServerSideProps = async (context) => {
+  newrelic.setTransactionName('HelpHubLandingPage')
+  console.warn('context:')
+  console.warn(context.req && context.req.headers)
+  addCacheHeaders(context.res)
+
+  return helpHubLandingPageProvider()
+}
+```
+
+2.7 Help-hub Search Results page.
+
+example usage:
+
+```typescript
+import React, { useContext } from 'react'
+import newrelic from 'newrelic'
+import {
+  HelpHubResultsPage,
+  AlgoliaCredentials,
+  Hit,
+  helpHubResultsProvider,
+  helpHubResultsPageContext,
+  HelpHubResultsPageContextOptions,
+} from '@newskit-render/standalone-components'
+import { createThemeDropdownObject } from '../../helpers/createThemeDropdownObject'
+import { AppContext } from '../../context'
+import { addCacheHeaders } from '../../helpers/addCacheHeaders'
+
+const resultsPageContext: Partial<HelpHubResultsPageContextOptions> = {
+  ...helpHubResultsPageContext,
+  header: {
+    title: 'Search results custom title',
+    description: 'Your search for "##QUERY##" returned ##COUNT## results',
+    titleOverrides: {
+      marginBlockEnd: 'space050',
+    },
+    marginBlockEnd: 'space060',
+  },
+  searchBar: {
+    marginBlockEnd: { xs: 'space060', md: 'space070' },
+  },
+  marginBlockEnd: { xs: 'space060', sm: 'space070', md: 'space090' },
+}
+
+const ResultsPage: React.FC<{
+  credentials: AlgoliaCredentials
+  hits: Hit[]
+}> = (props) => {
+  const { theme, setTheme } = useContext(AppContext)
+  const themeDropdownObject = createThemeDropdownObject(setTheme)
+
+  return (
+    <HelpHubResultsPage
+      {...props}
+      customTheme={theme}
+      context={resultsPageContext}
+      themeDropdownObject={themeDropdownObject}
+    />
+  )
+}
+
+export default ResultsPage
+
+export const getServerSideProps = async (context) => {
+  newrelic.setTransactionName('HelpHubResultsPage')
+  console.warn('context:')
+  console.warn(context.req && context.req.headers)
+  addCacheHeaders(context.res)
+
+  return helpHubResultsProvider(context)
+}
+```
+
+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) => {
+  newrelic.setTransactionName('HelpHubResultsPage')
+  console.warn('context:')
+  console.warn(context.req && context.req.headers)
+  addCacheHeaders(context.res)
+
+  return helpHubResultsProvider(context, 10)
+}
+```
+
+2.8 Help-hub Help Article page. Article page uses Next.js router to get the article parameter in order to fetch the article. The parameter is called title. That means that your path in Next routing system should look like this:
+
+`help-hub/article/[title]/index.tsx`
+
+Example use:
+
+```typescript
+import React, { useContext } from 'react'
+import newrelic from 'newrelic'
+import {
+  AlgoliaCredentials,
+  HelpHubArticlePage,
+  helpHubArticleProvider,
+  helpHubArticlePageContext,
+  HelpHubArticlePageContextOptions,
+} from '@newskit-render/standalone-components'
+import { createThemeDropdownObject } from '../../../../helpers/createThemeDropdownObject'
+import { AppContext } from '../../../../context'
+import { addCacheHeaders } from '../../../../helpers/addCacheHeaders'
+
+const articlePageContext: Partial<HelpHubArticlePageContextOptions> = {
+  ...helpHubArticlePageContext,
+  introductionProps: {
+    titleOverrides: {
+      typographyPreset: { xs: 'utilityHeading040', sm: 'utilityHeading050' },
+      stylePreset: 'inkContrast',
+      marginBlockEnd: 'space040',
+      as: 'h1',
+    },
+  },
+}
+
+const ArticlePage: React.FC<{
+  credentials: AlgoliaCredentials
+  title: string
+  content: string
+}> = (props) => {
+  const { theme, setTheme } = useContext(AppContext)
+  const themeDropdownObject = createThemeDropdownObject(setTheme)
+
+  return (
+    <HelpHubArticlePage
+      {...props}
+      customTheme={theme}
+      context={articlePageContext}
+      themeDropdownObject={themeDropdownObject}
+    />
+  )
+}
+
+export default ArticlePage
+
+export const getServerSideProps = async (context) => {
+  newrelic.setTransactionName('HelpHubArticlePage')
+  console.warn('context:')
+  console.warn(context.req && context.req.headers)
+  addCacheHeaders(context.res)
+
+  return helpHubArticleProvider(context)
+}
+```