npm package: @n3/ng-uikit
Description: This library was created for Netrika LLC and its education projects. It contains basic components and services including sticky 1-3 column layout, form controls, tabs and modality.
Latest version: 0.0.46

# N3 ng-uikit v. 1.0.0-beta

This library was created for Netrika LLC and its education projects. It contains basic components and services including sticky 1-3 column layout, form controls, tabs and modality.
 
# N3 Grid

N3 Grid is an adaptive light-weight, Angular 5 compatible layout using CSS Grid Layout and position: sticky. 
It is designed to provide the user experience of a desktop application while working
with a web app in a browser. The most important feature of this layout are our new light-weight sticky
columns. Such UI pattern is used at a number of web apps such as Yandex Music, Facebook, VK.
Now with the most browsers supporting CSS Grid Layout and position: sticky the amount of JS/TS code used for the layout can be painlessly minimized.

## Using N3 Grid

N3 Grid contains following container types:
- **n3-grid:** General container which contains all the application. Usually placed inside the root component.
However one can place it anywhere at the application, depending on one's needs.
- **n3-header:** Specific container for the header
- **n3-neck:**: We refer to "neck" as to the changeable part of the header or something that goes between header and columns. 
- **n3-column-grid**: usually placed inside the router-outlet. Contains n3-columns elements. Changes its layout depending on the number of columns inside.
- **n3-column:** Can be sticky or fixed with its own scroll (if `type` attribute = `fixed`). 
- **n3-footer:** Footer element. Usually it is hidden with a 3-column layout to let the third fixed column be 100vh height.
To change this behaviour to default use `forceFooterWhenTriple` attribute = `true`.

## Adaptive layout standard behaviour

N3 Grid currently has one breakpoint at 999px. Mobile devices display only one
column at the same time. 2 others are collapsed until required. The standard behaviour
can be described as following:

1. The first opens by default, others are collapsed to the 40-px-width clickable vertical bars.
2. Upon the user click at the bar the corresponding column expands and becomes active while the current active column collapses.

User can change standard behaviour for example by triggering the collapse/expand events
upon other actions such as form submit or promise resolve.

To change standard behaviour one should provide the ColumnWorkerService to the component
where this changes take place. For more information see the `setActiveColumn` method at `ColumnWorkerService`. 

# N3 Uikit

Uikit consist of custom form controls (input, select, radio, checkbox, datepicker, file, wysiwyg), navigation controls (anchor menu,
bread crumbs, tabs, pagination) and auxiliary components (modal, overlay).

## Using N3 Uikit

All the form controls are suitable for both reactive and template-driven forms by implementing ControlValueAccessor.
Error handling and server-side validation is implemented via `error` property of a control component.
One should aware that input and datepicker values are of _string_ type. n3-select and n3-options values
are of the `N3 Data type`:

`{
  id: number,
  name: string
}`

One can use special data-processing functions  to convert values and options for n3-select to the type required.

### Common

All form controls provide to some extent the similar input interface. However any control has its own specific options, 
the most common ones are described here. 

#### Common options
- **title:** _string_ - Element title displayed at the top when the input is fulfilled.
- **placeholder:** _string_ - Element placeholder text. Displayed only when the value is empty.
- **isBlocked:** _boolean_ - True if the element is blocked.
- **error:** _any_ - Set Error function.

## Form Controls

### Input
`<n3-input></n3-input>`

Standard input component. Can be of any available type (text, number, password) except submit, radio or checkbox.
HTML5 validation will be added soon.

#### Options

- **type:** _string_ - Input type (text, password, number, etc...)
- **icon:** _string_ - Custom icon code (svg or iconic font)
- **mask:** _any_ - Text mask for the input field
 
### Select
`<n3-select></n3-select>`

#### Options

#### Data processing

There are 2 types of data processing for the N3 Select. You can use a fixed list of options
or request it dynamically from the server. If your data is not of the N3 Data type you can
process it using DataHandlingService [N3 ng-base library](https://gitlab.develop.netrika.ru/js-engine/n3ng-base).

### Checkbox
`<n3-checkbox></n3-checkbox>`

Custom checkbox with standard or custom mark design.

#### Options

- **isCustom:** _boolean_ - True if one should use custom checkbox mark (the library has its default, however one can write custom styles).

### Radio
`<n3-radio></n3-radio>`

Custom set of radio buttons with standard or custom mark design. Radio buttons array are of the N3 Data Type.

#### Options

- **list:** _array_ - Radio buttons of N3 data type
- **isCustom:** _boolean_ - True if one should use custom checkbox mark (the library has its default, however one can write custom styles).

### Datepicker
`<n3-datepicker></n3-datepicker>`

Datepicker that opens inside the modal window and provides a set of date-choosing possibilities.

#### Options

- **isTime:** _boolean_ - True if one needs date-and-time-picker.

### File
`<n3-file></n3-file>`

File input.

#### Options

Only standard

## Navigation

### Tabs
`<n3-tab></n3-tab>`

Set of tabs changing the route hash. One can subscribe to the params change event and switch some content blocks depending on the active tab.

#### Options

- **tabs:** _array_ - Tabs are set using `N3 Data type` as an array of objects.
- **tabName:** _string_ - query parameter name for the current tabs row

### Pagination

Standard pager supporting next, previous pages and showing the list of all pages.

`<n3-pager></n3-pager>`

#### Options

- **current:** _number_ - current page
- **items:** _number_ - total number of items
- **pages:** _number_ - total number of pages
- **limit:** _number_ - limit of items per page

### Anchor menu
`<n3-anchor-menu></n3-anchor-menu>` - Menu component

`<anchor-target></anchor-target>` - Anchor link

Anchor menu component and directive

#### Options

- **anchors:** _array_ - Set of menu items.

### Bread crumbs
`<n3-bread-crumbs></n3-bread-crumbs>`

Navigation component showing multiple levels of navigation. Optionally it can render the title of the current page.

#### Options

- **title:** _string_ - Title of the current page
- **list:** _array_ - List of bread crumbs

The list item type is the following:

`{
  link: string
  text: string
}`

# Further plans until the final release
- **n3-select** - add "autocomplete" mode
- **n3-datepicker** - add "date_time" и "date_range" modes
- **n3-wysiwyg** - change the plugin
- Polyfills for position: sticky

### Overlay component 

  npm i @n3/ng-uikit

  #### in style.css 

  `@import '~@angular/cdk/overlay-prebuilt.css';`
      
  #### in html template
  
  - overlay component
    ```html
      <n3-overlay [contentTemplate]="dropdownTemplate" startView="dropdown" #n3Overlay ></n3-overlay>
    ```
    > startView = dropdown | popup | modal ;

  - template for dropdown part
    ```html
    <ng-template  #dropdownTemplate> ... </ng-template>
    ``` 
  - anchor directive for dropdown | popup modes, this is the header to which the pop-up part will be attached
    ```html
    <div [n3AnchorOverlay]="n3Overlay" #n3Anchor> ... </div>
    ``` 
  

  #### in ts component

  ```ts
    @ViewChild('n3Overlay') overlay: OverlayComponent<any>;
    @ViewChild('n3Anchor') element: ElementRef;

    public open(event) {

      const clientRect = this.element.nativeElement.getBoundingClientRect() as ClientRect;

      if (...) {
        this.overlay.open(clientRect.width);
        event.stopPropagation();
      }
    }

    public close(event) {

      if (...) {
        this.overlay.close();
        event.stopPropagation();
      }
    }
  ```
  #### css classes
  ```css
    .mat-overlay-transparent-backdrop   /*popup | dropdown is backdropClass*/
    .n3-overlay-content
    .dropdown
    .popup
      .cross
        .fa fa-times
  ```