# Elements

## Elements single release guide
We are changing the way we release Elements from the existing individual packages in the `frontend-toolkits` repository to a **single package release** in a new `elements` repository.

This will make it easier for you to install and use the components and themes of the Design System. It will also make it easier for us to maintain and scale.

## Requirements

This is a Node-based repository, so you will need to have [Node and NPM (Node Package Manager)](https://nodejs.org/en/download/) installed.

To use Elements components and themes you need:

- npm version 7 or higher
- Node.js version 18.14.0 or higher
- Dart Sass to compile your styles


## Installation

You will get all of the components and themes by installing the single package.

To install the Elements themes and components, enter the following command in your Terminal:

```bash
npm install @springernature/elements
```

The package contains `components`, `themes` and `utilities`.

The `brand-context` will now be known as `themes`. At first, we’ll support the `springer-nature` and `nature` themes.

For now, the `utilities` will be empty. We will develop their functionality in future releases.
At the moment you can find the utilitiy classes inside the `themes`.

For any component you want to use, import the relevant sass file from the component `scss` folder path.

## Import the styles

##### Step 1: import the Theme:

If you are working on a project with the **Springer Nature** theme then include the theme like this:

- Import the `core` theme into your core styles
```css
@import '../../node_modules/@springernature/elements/themes/springernature/scss/core.scss';
```
- Import the `enhanced` theme into your enhanced styles

```css
@import '../../node_modules/@springernature/elements/themes/springernature/scss/enhanced.scss';
```

- If you need them, import the `utilities` of the theme into your styles as a single import for all of them

```css
@import '../../node_modules/@springernature/elements/themes/springernature/scss/utilities.scss';
```

If you are working on a project with the **Nature** theme then include the theme like this:

- Import the `core` theme into your core styles
```css
@import '../../node_modules/@springernature/elements/themes/nature/scss/core.scss';
```
- Import the `enhanced` theme into your enhanced styles

```css
@import '../../node_modules/@springernature/elements/themes/nature/scss/enhanced.scss';
```

- If you need them, import the `utilities` of the theme into your styles as a single import for all of them

```css
@import '../../node_modules/@springernature/elements/themes/nature/scss/utilities.scss';
```

##### Step 2: import the styles for the component.

For the **Springer Nature** theme, import the `scss` by adding this to your component sass file:
```css
@import '../../node_modules/@springernature/elements/components/card/';
```
This imports the `index.scss` file that includes `springernature` theme and the styles for the component.

If you want to use the `nature` theme, import the `nature` scss file:

```css
@import '../../node_modules/@springernature/elements/components/card/nature';
```

This imports the `nature.scss` file that includes `springernature` theme, the `nature` theme and the styles for the component.

##Templates

The location of the template has moved. It used to be in the `view` folder. Now it is in the `root` folder of the component.

Consume the `.hbs` file that you find inside the component folder.

Example of a file path:
```html
'../../node_modules/@springernature/elements/component/template.hbs’
```

## Design tokens

In Elements we use [Design Tokens](https://css-tricks.com/what-are-design-tokens).

Currently, the Elements team generates the `json` for the design tokens. We are working on a process to allow you to do this yourself.

If you want to create a new component, you can still follow this guideline and hardcode the variables inside the `component-name.token.scss`. Then, a member of the Elements team will create the `json` for the design tokens as part of the review of the pull request or at a later point in time.

## JavaScript

Import the script from `elements` and then execute it.

For example:
```js
import {header} from '@springernature/elements/nature-header/js/header';
header();
```

## New `data` folder

In the single release package, components will now have a `data` folder.

Here you will find:
- a `schema.json` file
- an `example.json` file


## Creating a component

There is now a command you can run to help you to create new components.

Enter the following command in your Terminal, in the root folder:

```bash
npm run create
```

You will be prompted with the question:

`What is the name of the new component?`

The system then creates a new folder in the components folder based on your answer.

For example, if you enter `my-component` as the component name, the system will create the following files automatically:

- `my-component.hbs`, a handlebars template for the component
- `my-component.schema.json`, a schema for the data that will be used to compile the `my-component.hbs` template
- `my-component.example.json`, some example data to fit the schema and compile the template
- A sass folder with an `index.scss`, `component-name.token.scss` and `component-name.scss`.

In the sass folder there is a `component-name.token.scss` file. This file contains the variables used inside the `component-name.scss`.

Import `component-name.token.scss` and `component-name.scss` into `index.scss`.

## Tests after component creation

The system will also create a test file, `my-component.test.js`, using [Jest](https://jestjs.io/).

To test your component you can run:
```bash
npm run create:test
```
This test will check that the:

- template, schema, and example data files exist
- example data file fits the schema
- template can be compiled and rendered using the example data
- rendered HTML passes basic accessibility standards

To author your component, adapt the given files to create a data structure and template that work together correctly and continue to pass these tests.


## Development Docs

The documentation site for Elements also lives in this repository. It uses a static site generator called [Eleventy](https://www.11ty.dev/).

To run the docs site locally:

1. Navigate to the **/docs** folder (`cd docs`)
2. Run `npm i` to install the dependencies
3. Run `npm start` to start a local server

Depending on the developmental state of the docs site, you may not see much (or any) content. See what Eleventy is generating by exploring the **/docs/build** folder.
