@ssv/ngx.ux

UX essentials for building apps, utilities which enables you writing richer apps easier.

Quick links

Change logs | Project Repository

Installation

Get library via npm

npm install @ssv/ngx.ux

Choose the version corresponding to your Angular version:

| Angular | library | | ------- | ------- | | 10+ | 2.x+ | | 4 to 9 | 1.x+ |

Features

• Viewport (see below)
  • Viewport Data

Usage

Register module

import { SsvUxModule } from "@ssv/ngx.ux";

@NgModule({
  imports: [
    SsvUxModule
  ]
}
export class AppModule {
}

Viewport

Provides utilities to handle responsiveness easier based on the viewport (view size)

Comparison Operands

| Operand | Description | | ------- | --------------------- | | = | Equals | | <> | Not equals | | < | Less than | | <= | Less than or equal | | > | Greater than | | >= | Greater Than or equal |

Size Types

These are the defaults, but they are configurable.

| Size Type | Size Range | | --------- | ---------- | | xsmall | <=450 | | small | 451-767 | | medium | 768-992 | | large | 993-1200 | | xlarge | 1201-1500 | | xxlarge | 1501-1920 | | xxlarge1 | >=1921 |

Viewport Matcher Attribute (directive)

Structural directive which loads components based on a viewport sizing condition e.g. show ONLY if viewport is greater than xlarge.

Examples

<!-- simple -->
<div *ssvViewportMatcher="'large'">
  show only when large
</div>

<!-- expression based - tuple (shorthand) *recommended usage* -->
<div *ssvViewportMatcher="['>=', 'xlarge']"> (see all operands and sizes)
  show when >= xlarge
</div>

<!-- expression based - object -->
<div *ssvViewportMatcher="{size: 'xlarge', operation: '<='}"> (see all operands and sizes)
  show when >= xlarge
</div>

<!-- includes -->
<div *ssvViewportMatcher="['large', 'xlarge']">
  show only when large, xlarge
</div>

<!-- excludes -->
<div *ssvViewportMatcher="''; exclude ['xsmall', 'small']">
  hide only when xsmall, small
</div>

<!-- match/else -->
<div *ssvViewportMatcher="['>=', 'xlarge']; else otherwise">
  show when >= xlarge
</div>

<ng-template #otherwise>
  show when expression is falsy (< xlarge)
</ng-template>

<!-- non structure syntax -->
<ng-template ssvViewportMatcher [ssvViewportMatcherExclude]="'xsmall'">
    (exclude xsmall)
</ng-template>

Viewport Matcher Var (directive)

Structural directive which provides the condition var whether it matches or not (params are similar to ssvViewportMatcher).

<!-- simple -->
<div *ssvViewportMatcherVar="let isLarge when 'large'">
  isLarge={{isLarge}}
</div>

<!-- expression based - tuple (shorthand) *recommended usage* -->
<div *ssvViewportMatcherVar="let isMediumDown when ['<=', 'medium']">
  isMediumDown={{isMediumDown}}
</div>

<!-- includes/or -->
<div *ssvViewportMatcherVar="let isLargeOrSmall when ['small', 'large']">
  isLargeOrSmall={{isLargeOrSmall}}
</div>

Viewport Service

// get size type
this.viewport.sizeType$.pipe(
    tap(x => console.log("Viewport - sizeType changed", x)), // { type: 4, name: "xlarge", widthThreshold: 1500 }
  ).subscribe();

Viewport for SSR

Since in SSR there is no way to know the client viewport size, we should at least determine device type and handle provide 3 different sizes based on device type e.g. mobile, tablet or desktop so the initial rendering will be closer based on device type.

The basic implementation allows to provide a device type mobile, tablet or desktop and there are static sizes for those.

import { UX_VIEWPORT_SSR_DEVICE } from "@ssv/ngx.ux";

const deviceType = deviceTypeFromServer;
{ provide: UX_VIEWPORT_SSR_DEVICE, useValue: deviceType },

The default implementation can also be replaced by implementing a small class as following:

export class SuperViewportServerSizeService {
  get(): ViewportSize {
    // do your magic..
    return size;
  }
}

import { ViewportServerSizeService } from "@ssv/ngx.ux";

@NgModule( {
  providers: [
    { provide: ViewportServerSizeService, useClass: SuperViewportServerSizeService }
  ]
}) export class AppModule {
}

Configure

You can configure the existing resize polling speed and as well as provide your custom breakpoints.

Custom Breakpoints

import { SsvUxModule, generateViewportSizeType } from "@ssv/ngx.ux";

const breakpoints = { // custom breakpoints - key/width
  smallest: 500,
  small: 700,
  medium: 1000,
  large: 1400,
  extralarge: 1600,
  xxlarge: 1800,
  fhd: 1920,
  uhd: 3840
};

  imports: [
    SsvUxModule.forRoot({
      viewport: {
        resizePollingSpeed: 66, // optional - defaults to 33
        breakpoints // provide the custom breakpoints
      }
    }),
  ],

Override existing Breakpoints

import { SsvUxModule, UX_VIEWPORT_DEFAULT_BREAKPOINTS } from "@ssv/ngx.ux";

  imports: [
    SsvUxModule.forRoot({
      viewport: {
        breakpoints: {
          ...UX_VIEWPORT_DEFAULT_BREAKPOINTS, // use breakpoints provided with library
          xxlarge1: 2000, // override xxlarge1
          uhd: 3840 // add new breakpoint
        }
      }
    }),
  ],

Getting Started

Setup Machine for Development

Install/setup the following:

• NodeJS v18.16.0+
• Visual Studio Code or similar code editor
• TypeScript 5.0+
• Git + SourceTree, SmartGit or similar (optional)
• Ensure to install global NPM modules using the following:

npm install -g git gulp devtool

Project Setup

The following process need to be executed in order to get started.

npm install

Building the code

npm run build

Running the tests

npm test

Watch

Handles compiling of changes.

npm start

Running Continuous Tests

Spawns test runner and keep watching for changes.

npm run tdd

Preparation for Release

• Update changelogs
• bump version

Check out the release workflow guide in order to guide you creating a release and publishing it.

Regen Examples

• ng new examples --skip-install --create-application=false
• cd examples
• ng g example-app --routing --style=scss
• ng lint
• ng add @angular/material