# patricia-ui-components

This is a collection of UI components that will be used across all of Patricia's platforms to ensure consistent styling.

Check out the [Usage Guide](./USAGE.md)

## Project setup

```bash
npm install
```

### To demo or view your component

Import and use your component in `demo/App.vue`. Then run

```
npm run serve
```

### Export your component

You have to expose your component in `main.js` for it to be of any use. Simply import it and add it to the list of exports

```javascript
import AwesomeComponent from 'path/to/AwesomeComponent.vue'
...

export { ... AwesomeComponent ... }
```

### Customize the *theme*

To support custom themes, this library implements and uses a default theme, 
containing default values for properties such as *colors*, *fontSizes*, *screens* (can be used as screen sizes and breakpoints), 
and *roundness* (can be used for border-radius setting), and *dark* (used to indicate whether the theme is in dark mode or not)
so if no property is specified, it will apply the default theme

#### Using the theme in your project

You can do this in any project by attaching the theme object to the root Vue object of such project.

For example, in a Vue CLI project, you could do:

```javascript
import Vue from 'vue';
import App from './path/to/App.vue';

// other configs if any

Vue.prototype.$theme = {
  colors: {
    primary: {
      default: '#0276FF',
      base: '#032041',
      dark: '#0050AF',
      pale: '#E8F7FF',
      light: '#479BFF',
    },
    danger: {
      default: '#CC2E2E',
      dark: '#A10000',
      light: '#D75C5C',
      pale: '#FFF3F3',
    },
  },
  fontSizes: {
    heading: {
      1: '48px',
      2: '40px',
      3: '32px',
      4: '20px',
    },
  },
  roundness: {
    2: '2px',
    5: '5px',
  }
};


new Vue({
  render: h => h(App),
}).$mount('#app');
```

In a gridsome project, follow the guidelines here [https://gridsome.org/docs/assets-scripts/](https://gridsome.org/docs/assets-scripts/)

```javascript
//main.js

import DefaultLayout from '~/layouts/Default.vue';

export default function(Vue) {
  // Set default layout as a global component
  Vue.component('Layout', DefaultLayout);

  //Set up the color theme
  Vue.prototype.$theme = {
    colors: {
      primary: {
        default: '#0276FF',
        base: '#032041',
        dark: '#0050AF',
        pale: '#E8F7FF',
        light: '#479BFF',
      },
      danger: {
        default: '#CC2E2E',
        dark: '#A10000',
        light: '#D75C5C',
        pale: '#FFF3F3',
      },
    },
    fontSizes: {
      heading: {
        1: '48px',
        2: '40px',
        3: '32px',
        4: '20px',
      },
    },
    roundness: {
      2: '2px',
      5: '5px',
    }
  };
}
```

You can change the theme dynamically and all the components will automatically update to reflect the new/updated theme
A theme usually contain the following properties: 
- dark (boolean): whether this is a dark theme or light theme.
- roundness (object): roundness of common elements, such as buttons.
- colors (object): various colors used throughout different elements.
    - primary - variants of colors for your app, usually shades of the brand color.
    - danger 
    - success
    - pending
    - font
- screens (object) - screen sizes and breakpoints
- fontSizes (object)

**NOTE:** You can omit any key and it will fallback to the default. Hence, for most situations, you only need to specify some key parts of the theme.

#### Writing your components to factor in the theme

You might need to use several colors while writing your components, especially to set states: primary, success, danger etc. Please note the following.

A mixin has been written at `@/mixins/theme`

- Import and use the colors mixin as such in your component:

```javascript
import theme from '@/mixins/theme';

export default {
    mixins: [theme],
    ...
}
```

- Write your CSS/SCSS to use the css variables instead of hard-coded colors, especially for the colors included in the palette. The css variables follow the format `--primary` or `--success` (for the _default_ key) and `--primary-dark` or `--success-pale` for the other keys inside each palette.

```scss
.btn {
  &-error {
    background-color: var(--danger);

    &.loading {
      background-color: var(--danger-light);
    }
  }
}
```

Or CSS

```css
.btn-error {
  background-color: var(--danger);
}

.btn-error.loading,
.btn-error.disabled {
  background-color: var(--danger-light);
}
```

#### IMPORTANT NOTE

Do not try to use scss color functions with the css var() key. It won't work because the css variables aren't available until runtime in the browser.

### Compiles and minifies the component library for production deployment

```bash
npm run build-lib
```

This generates several files in the dist folder

### Run your unit tests

```
npm run test:unit
```

### Lints and fixes files

```
npm run lint
```

### Customize configuration

See [Configuration Reference](https://cli.vuejs.org/config/).

## StoryBook

We use Storybook to visualize our components and styles. Run storybook to interact with components.

```
npm run storybook
```

Remember to import these styles to your stories to enable Global utility classes.

```
import '@/assets/scss/tailwind.css';
import '@/assets/scss/global.scss';
```

## Publishing to npm
1. `npm run build-lib` : This builds the pakage
2. Increase the version number
3. `npm login` username is patricia_engineering and email is engineering@patricia.com.ng. Contact the Team lead or Engineering Manager for the password
3. ` npm publish --access public` : To publish the package