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.

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

    <n3-overlay [contentTemplate]="dropdownTemplate" startView="dropdown" #n3Overlay ></n3-overlay>

  startView = dropdown | popup | modal ;

• template for dropdown part

  <ng-template  #dropdownTemplate> ... </ng-template>

• anchor directive for dropdown | popup modes, this is the header to which the pop-up part will be attached

  <div [n3AnchorOverlay]="n3Overlay" #n3Anchor> ... </div>

in ts component

  @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

  .mat-overlay-transparent-backdrop   /*popup | dropdown is backdropClass*/
  .n3-overlay-content
  .dropdown
  .popup
    .cross
      .fa fa-times