# Support Web Components

This a component library created to standardize the creation and
articulation of support article data provided via an API in JSON. Meaning when the new API provides content in JSON,
it will have a structure that maps to these components. That way the data from the backend will dictate the structure
and not the actual components.

The components can be viewed in this [Storybook](https://volvo-cars.github.io/ced-onboarding-support-components)

## Development

### Getting Started

- `npm install`
- `npm run dev` to run storybook
- `npm test` to run tests

### Publish

The library is automatically published to Github packages and NPM when
a new tag in the format `v.X.X.X` is pushed to Github.

The steps to publish are:

1. build: `npm run build`
2. bump version. Use `npm version <major>.<minor>.<patch>` to bump version

#### Pre-releases

Sometimes it may be useful to create a pre-release version for testing, these are the steps needed (replace "major" in the commands with patch|minor|major ad needed)

1. Running `npm version premajor --preid=rc` will add a prefix to a new major, eg. `2.0.0-rc.0`
2. For each iteration use `npm version prerelease` to create new pre-release version with bumped prefix, eg `2.0.0-rc.0`
3. To promote the pre-release to a release run `npm version major`

## Usage

The library is published as an NPM package and also a Github package.

### Install from NPM package registry

Run `npm install @volvo-cars/ced-os-react-components`.

### Install from Github package registry

To be able to install the package from the Github registry some configuration and Github authentication is needed.

Add a file called `.npmrc` to your project and paste the lines below into it to configure NPM to load @volvo-cars packages from the Github registry. The second line
references an environment variable on your machine: `VCC_GITHUB_PACKAGES_TOKEN`.

```
@volvo-cars:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${VCC_GITHUB_PACKAGES_TOKEN}
```

The value of VCC_GITHUB_PACKAGES_TOKEN should be a
[Github Personal Access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token)
with at least "read:packages" permissions.

If you use the [dotenv package](https://www.npmjs.com/package/dotenv) in your project it's also possible to define the
variable in the `.env` file. In which case you need to do `dotenv npm install`

### Example usage

#### Themes and styles

- Make sure the fonts needed are loaded for the respective theme, e. "Polestar Unica" for "polestar" and "Volvo Novum" for "volvo" (font is loading not handled by this library)
- Load the styles of the components and base theme `@volvo-cars/ced-os-react-components/lib/index.css`
- Load the styles of the theme(s) to be used.
  - `@volvo-cars/ced-os-react-components/lib/theme-polestar.css`
  - `@volvo-cars/ced-os-react-components/lib/theme-volvo.css`, and add the class
  - Alternatively override custom properties (variables) on `.dcs-base-theme` in your own styles to create a custom theme (See all variables in [lib/theme-base.css](lib/theme-base.css)).
- The theme `classNames` are applied automatically - `.dcs-base-theme` for base styles and if either "volvo" or "polestar"
  is passed to the `theme` prop the respective theme className of `dcs-volvo-theme` or `dcs-polestar-theme` is set.

#### JSONArticle

The main entrypoint

Pass JSON article content to the data prop. Set a theme name, and pass an optional config

```
// ...
import { JSONArticle } from '@volvo-cars/ced-os-react-components';

const Article = ({ articleId, content }) => {
    return (

            <JSONArticle data-article-id={articleId} data={content} theme="volvo" config={{
              locale: 'en-GB', // optional - will set correct direction based on locale
              linkComponent: (props)=> {/* optional custom link component eg. next/link */}
              icons: {
              // Supply URL:s to icons here if needed
                note: 'some/path/note.svg';
                warning: 'some/path/warning.svg';
                important: 'some/path/important.svg';
              }
            }} />
    );
};
```

#### Standalone

If you want to use the renderer without creating a full JS project, with NPM etc, you can use the standalone solution.

[Example here](https://volvo-cars.github.io/ced-onboarding-support-components/standalone-example.html).

Include the `standalone-example.iife.js` and `standalone-example.css` files found in the npm package under `@volvo-cars/ced-onboarding-support-components/lib`, in the [HTML template file](src/standalone/standalone-example.ejs), make sure to make the following replacements:

- `article: null` must be replaced with `article: '<article>'`, where `article` is the (JSON representation) of an article. It must contain an `externalId`. It must also contain the content of the document, i.e. a `title` and optionally also a `description` and `body`. These fields may be directly on the `article` object itself, or nested inside of `article.content` or `article.jsonContent`.
- `articleLinkClicked: null` may be replaced with `articleLinkClicked: function(articleId, targetId) { ... }`, where the function will be called whenever the user clicks a link to another article. The function takes two arguments: the ID of the article being linked to, as well as (optionally) the ID of the target element (will typically just be `null`). If `articleLinkClicked` is left as `null`, it will default to working as a normal link, such that if the current URL is `foo/bar/articleId1`, and the user clicks a link to an article with ID `articleId2`, it will navigate to `foo/bar/articleId2` (or `foo/bar/articleId2#targetId`, if `targetId` is not null).
- `linkClicked: null` may be replaced with `linkClicked: function(href) { ... }`, where the function will be called whenever the user clicks on an external link. The function takes one argument: the URL of the link target. If `linkClicked` is left as null, it will default to simply navigating to the link.

### Command line usage (CLI)

Run directly using `npx` without install

```
npx @volvo-cars/ced-os-react-components [JSON file path or JSON string] [options]
```

Or install globally and then use the command

```
support-content-to-html [JSON file path or JSON string] [options]
```

**Options:**

`--file=[input filename]` - The file contents is used as input to render
`--out=[output filename]` - The render result is written to a file
`--json=[JSON string]` - The string is used as input to render
`--clean` Option to remove all classnames