npm package: @sagent/brand
Description: 1. Example ( `@use` keyword is a recommended way to import sass, it replaces `@import`, which will be depricated eventually):
Latest version: 0.0.37

# Sagent Brand

## USAGE

1. Example ( `@use` keyword is a recommended way to import sass, it replaces `@import`, which will be depricated eventually):

```scss
// Externally
@use "variables" as vars;

h3 {
  color: vars.$c-accent;
}

// Internally in the lib (relative path)
@use "../variables" as vars;

h3 {
  color: vars.$c-primary;
}
```

2. Library also contains 2 stylesheet files (part of `build.options` in `angular.json`):

```json
    ...
    "styles": [
        "node_modules/@sagent/brand/src/lib/scss/styles/_styles.scss",
        "node_modules/@sagent/brand/src/lib/css/_styles.css",
        ...
    ],
    ...
```

---

## HOW TO ADD ADDITIONAL FILE TO EXPORTS

1. Add file to ng-package.json "assets".
2. Add file to the package.json "exports".

---

## CREATE NEW LIB

1. Generate a new lib using nx generate with options (based on the needs)

```txt
    --style=scss
    --change-detection=OnPush
    --import-path=@sagent/example
    --publishable
    --tags=utils
```

2. Change path (for all environments) for tsconfig in "targets": "build": "configurations": "production": "tsConfig" to
   "tsconfig.lib.prod.json" (folder path needs to be removed)

3. Add scripts to package.json of the lib (replace lib name placeholder):

```json
    "scripts": {
        "patch": "npm version patch",
        "pack": "cd ../../dist/libs/[LIBRARY NAME] && npm pack && npm publish --access public",
        "publish": "npm run patch && nx build && npm run pack"
    }
```

4. Add tags to the lib for proper boundaries maintenance in `project.json`

```json
    "tags": ["scope:some-scope", "type:[app or feature or utils]"]
```

5. To publish the lib you will need to login into npm first:

```shell
    npm adduser
```

6. Now you can build and publish with one script from the monorepo root folder

```shell
    npx nx publish [lib_name]
```

---

## HOW TO LINT SCSS IN AN APP/PROJECT

0. Install npm package

```shell
    npm i --save-dev @sagent/brand
```

1. Install stylelint

```shell
    npm install --save-dev stylelint stylelint-config-standard-scss
```

2. Add script (optional) to package.json of the app

```json
    {
        "scripts": [
            "style-lint": "npx stylelint \"**/*.scss\"",
        ]
    }
```

3. Add config file to the root of the app/lib `.stylelintrc` or `.stylelintrc.json`

```json
{
  "extends": ["stylelint-config-standard-scss", "./src/lib/stylelint/sagent-stylelint-rules"]
}
```

4. Run script

```shell
    npm run style-lint
```

---

## NESTING

Ideally there should not be more than 2-3 levels of nesting. If selectors are named properly, thre is no need for deep nesting.

---

## NAMING CONVENTION

1. The project is utilizing mixed approach in naming css selectors.
2. If css selector is used in any DOM query (ex: `document.querySelector('.some-class')`) use `ts-` prefix, so that other developers will be aware.
3. Use top level wrapper/container for every component (there should almost no exceptions). Lets say you have a component a tag `<prefix-some-tag></prefix-some-tag>`. Then inside its template should look like this (prefix should be omitted):

```html
<div class="some-tag">...</div>
```

4. Use hyphen to separate words in the selector:

```scss
    .some-smart-component {
        ...
    }
```

5. For **inner** selectors, when they are part of component or always supposed to be used together, use low dash "`_`" to separate `parent name`, `item itself` and `modifier`:

```scss
    // NAME STRUCTURE
    .[component/feature-name]_[item-name]_[modifier] {

    }

    //
    .some-smart-component_title {
        ...
    }

    // MODIFIER IS OPTIONAL
    .some-smart-component_title_large {
        ...
    }

    .some-smart-component_image {
        ...
    }
    .some-smart-component_content {
        ...
    }
```

> No mater how deep your element sits inside component, as long as it is part of it, the selector should use the same
> naming convention. In the example in #6 the image tag (grandchild of the component) has a class `some-smart-component_image` and not `some-smart-component_content_image`.

6.  So the html will look like this:

```html
<div class="some-smart-component">
  <div class="some-smart-component_title">...</div>

  <div class="some-smart-component_content">
    ...
    <img class="some-smart-component_image" />
  </div>
</div>
```

7. Well-structured comments can save time when you’re trying to understand your code. You do not need to write comments to say `color: red` will give a red color. But, if you’re using a CSS trick that is less obvious, feel free to write a comment.

   > Take a look at how well commented the [Bootstrap](https://github.com/twbs/bootstrap/blob/v4-dev/scss/_carousel.scss) source code is.

---

## WHERE SHOULD I PUT MY STYLES?

If you are working on any design/style changes please follow the following guide:

1. Rule will be (or may be, or should be) used by **_more than 1 project_**: `@sagent/brand`.
2. Rule will be used AND **_shared between components_** only inside a **_single project_**: `styles.scss` in the project root or in any corresponding file name inside project `/styles` folder.

```scss
    // src/styles.scss

    // OPTION 1 - Reference another shared/global scss file
    @use './styles/feature_name.scss';

    // OPTION 2 - Directly in styles file
    .some-class {
        ...
    }
```

3. Rule will be used only by a **_single component_**: `.scss` in the component folder.

---

## **_DO_** and **_DON'T_**

To maintain the syntax for multi theme support every developer should be aware of DOs and DON'Ts. This will also make
the app design more consistent and will provide a better UI.

**_DON'T USE_**:

- color literal, only use color variables or mixins.

```scss
// WRONG
.foo {
  color: #ffffff;
}

// CORRECT
.moo {
  color: vars.$c-primary;
}
```

- background color literal, only use mixins. In this case color will be determined by a mixin, do not specify a font color as well:

```scss
// WRONG
.foo {
  background-color: #0000ff;
  color: grey;
}

// CORRECT, notice there is no color property.
.moo {
  @include mixins.color-bg("primary-dark");
}
```

- font/font-family/font-size/font-weight/letter-spacing properties directly, only use font mixins. A need for a new font has to be addressed by a designer and (if it is needed) it should be added to the `@sagent/brand` font mixin:

```scss
// WRONG
.foo-title {
  font-family: Arial;
  font-size: 54px;
  font-weight: 600;
}

// CORRECT
.moo {
  @include mixins.font("title-medium");
}
```

- margin/padding literals, only use variables (recommended) or `rem` units. There can be some exceptions, but they should not become normal:

```scss
// WRONG
.foo-title {
  margin: 6px 10px;
  padding: 7px;
}

// CORRECT
.moo {
  margin: vars.$space1x vars.$space2x;
  padding: vars.$space1x;

  // same as
  margin: 0.5rem 1rem;
  padding: 0.5rem;
}

// SOMETIMES, BUT RARE. Usually when margin/padding is too small (tooltips, badges, some icons, etc):
.too {
  padding: 1px 2px;
}
```