@newskit-render/standalone-components 0.2.1 → 0.3.0

package/README.md

@@ -2,7 +2,82 @@
 
 ## Overview
 
-Standalone components is a package that contains components, that can live with or without the Render application. You can add the package with this command `npm install @newskit-render/standalone-components` or if you use yarn `yarn add @newskit-render/standalone-components`.
+The Standalone-components package contains components, that can live with or without 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: this component provides two main facilities:
+
+- 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`.
+
+# How to use
+
+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.
+
+Example of use:
+
+```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,
+    },
+  }
+}
+```
 
 .
 .

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newskit-render/standalone-components",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Newskit Render Standalone Components",
   "author": "",
   "license": "UNLICENSED",