# TODO
 - RXJS import
 - steps to start the development
 - describe framework and demo dependencies
 - create a new component guide
 - usage guide
 - move nebular-icons in separate repository
 
# MUST!
- Don’t overcomplicate
- Don’t make things too abstract
- Use tslint, styles-lint
- Use lifecycle interfaces
- Use default angular view encapsulation
- Try to use changeDetection: ChangeDetectionStrategy.OnPush
- Never forget typedoc comments
- Do tests
- Create playground page per each new component/feature


# NEW Feature Checklist
- lint checks are passing
- tests are added/updated
- showcase in the playground updated
- demo updated
- SCSS variables added/updated
- tsdocs added/updated
- commit message is properly formatted
- for the override - registered in a list of overrides
- component *.theme registered in a list of component themes
- looks great on all default themes
- takes into account `inverse` feature
- requires approval from several core team contributors

# Objectives
The main aim of the project is to create a second version of ng2-admin called ngx-admin which will fix all the architecture issues of the current version:

  - make it modular
  - publish it npm on package
  - customizable color themes with HOT reload support
  - create a library of custom layout components
  - expanded documentation and guides
  - replace ng2-bootstrap with ng-bootstrap
  - get rid of jQuery
  - follow Angular code style
  - use Angular CLI


# Framework Structure

- src
    - app - Components playground, used for components development showcase, also covered with UI tests
    - docs - Documentation and framework website built on top on the framework
    - backend - Small backend example to run UI tests for @nebular/auth 
    - framework - Framework itself, divided into npm packages
        - theme - `@nebular/theme` npm package, main framework package
        - auth - `@nebular/auth` npm package, auth package (login, register, etc)       
        - icons - `nebular-icons` npm package, cool icons font
      
      
# Auth // TODO      

# Theme
Theme module is the main framework module, consisting of:
 
  - custom UI Kit components (layout, cards, tabs, etc)
  - css-themes with hot reload support 
  - appearance overrides for 3rd party libraries.

## UI Kit structure 

Located in `theme/components`.
Each component consists of the standard angular component structure + `*.theme.scss` file, which is a customizable part (customizable here means dependable on a specific theme variables) of component's styles.

## Services

Located in `theme/services`.
Global theme services.

## Styles structure

Located in `theme/styles`

- core/ - Common mixins and functions
- global/ - Root of the 3rd party components overrides and other global styles
- prebuilt/ - Technical files of which css themes will be compiled
- themes/ - built-in themes
- common/ - Shared components styles
- all.scss - exports all themes' variables, theming engine and global styles
- components.scss - exports all themes' variables and theming engine but DOES NOT export global styles (should be used in a component)
- globals.scss - exports all global styles (overrides, components' `*.theme.scss` themes, fonts, etc)
- themes.scss - all built-in themes
- theming.scss - themesation engine 

### CSS Themes

- Problem
  Customizable themes support doesn't work good with angular, as encapsulated in framework components' styles can't access user app variables unless you make them non-encapsulated and export as scss-files).
  Thus, we need to ask a user to include the framework styles separately as global styles, so that it is possible to change SASS variables before the theme styles are processed.
  
- Solution
  The solution is to separate component's styles into configurable (with SASS variables) and non-configurable (hardcoded) styles.
  Then place hardcoded styles into `*.component.scss`, and dynamic styles into `*.theme.scss`.
  The `*.theme` files will be included into one `*theme` file with access to the theme variables. This file has to be included by the user into their project.
  
- Disadvantages
    - We separate styles, thus it's hard to read the styles in the development mode.
    - Theme styles are not encapsulated, basically are global styles.
  
- Possible future solution
    - CSS variables (currently lack of browsers support)
 
  
### Multi Themes

- Problem
  We cannot change SCSS variables in the runtime as user change the theme (possible with CSS variables but browser support is quite limited). 
  
- Solution
  Thus, we need to build multiple instances of styles in the runtime and encapsulate each theme's bunch of styles under some .theme-name class:
   ```
    .nb-theme-default {
      nb-layout {
        color: black;
      }
    }
    .nb-theme-red {
      nb-layout {
        color: red;
      }
    }
    
   ```
  Then, by changing a css class on the root element (nb-layout) we can change the page appearance in the runtime.
  
  - SCSS MAP
    Moreover, to have an arbitrary amount of themes we need to store the variables as an `SCSS `.
    Then, each component' styles (user components' styles) needs to be wrapped into `nb-install-component` mixing, 
    which will be called in a loop for each theme, setting its own variables.
    Variables then accessible through `nb-theme(var-name)` function.
    Finally, example of such component will look like:
    ```
      @import '@nebular/theme/styles/component';
      
      @include nb-install-component() {
        div {
          color: nb-theme(primary-fg);
        }
      }
    ```
    
- Disadvantages
  - Double (triple, multiple) sizes of generated css file. 

- Possible future solution
  - CSS variables


// TODO: create and use custom themes
      
## JS Themes - // TODO

TBD

## Documentation
Documentation is generated by the custom generator built on top of @nebular/theme.

## Release

To start a new release (publish the framework packages on NPM) you need:

1. npm run release:prepare - this will create ready for publishing packages in src/.lib
2. npm run release:validate - this will build prod & AOT builds of the playground app using prepared packages in src/.lib and run e2e tests again it.
3. MANUALLY update a version in main ./package.json to a new one
4. release:
  * make sure you are logged in as a corresponding NPM user
  * npm run release - will update all package.json's, run prepare & validate and finally publish the packages to NPM
  * manually correct the changelog
  * commit, git tag, git push 
5. create release on github