@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
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)
Comparsion Operands
Operand | Description |
---|
= | Equals |
<> | Not equals |
< | Less than |
<= | Less than or equal |
> | Greater than |
>= | Greater Than or equal |
Size Types
Size Type | Size Range |
---|
xsmall | <=450 |
small | 450-767 |
medium | 767-992 |
large | 992-1200 |
xlarge | 1200-1500 |
xxlarge | 1500-2000 |
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
<div *ssvViewportMatcher="'large'">
show only when large
</div>
<div *ssvViewportMatcher="['>=', 'xlarge']"> (see all operands and sizes)
show when >= xlarge
</div>
<div *ssvViewportMatcher="{size: 'xlarge', operation: '<='}"> (see all operands and sizes)
show when >= xlarge
</div>
<div *ssvViewportMatcher="['large', 'xlarge']">
show only when large, xlarge
</div>
<div *ssvViewportMatcher="''; exclude ['xsmall', 'small']">
hide only when xsmall, small
</div>
<div *ssvViewportMatcher="['>=', 'xlarge']; else otherwise">
show when >= xlarge
</div>
<ng-template #otherwise>
show when expression is falsy (< xlarge)
</ng-template>
<ng-template ssvViewportMatcher [ssvViewportMatcherExclude]="'xsmall'">
(exclude xsmall)
</ng-template>
Viewport Service
this.viewport.sizeType$
.pipe(
tap(x => console.log("Viewport - sizeType changed", x)),
)
.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 implemention 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 {
return size;
}
}
import { ViewportServerSizeService } from "@ssv/ngx.ux";
@NgModule( {
providers: [
{ provide: ViewportServerSizeService, useClass: SuperViewportServerSizeService }
]
}) export class AppModule {
}
Configure
In order to configure globally, you can do so as following:
import { SsvUxModule } from "@ssv/ngx.ux";
imports: [
SsvUxModule.forRoot({
viewport: { resizePollingSpeed: 66 }
}),
],
Getting Started
Setup Machine for Development
Install/setup the following:
- NodeJS v10+
- Visual Studio Code or similar code editor
- TypeScript 3.1+
- Git + SourceTree, SmartGit or similar (optional)
- Ensure to install global NPM modules using the following:
npm install -g git gulp yarn devtool
Cloning Repo
- Run
git clone https://github.com/sketch7/ngx.ux.git
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
Development utils
Watch
Builds on changes.
npm start
Running Continuous Tests
Spawns test runner and keep watching for changes.
npm run tdd
Preparation for Release
npm run prepare-release -- --bump major|minor|patch|prerelease (default: patch)
Check out the release workflow guide in order to guide you creating a release and publishing it.