Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sketch7/ngx.ux
UX essentials for angular to build richer apps easier
https://github.com/sketch7/ngx.ux
angular angular6 angular7 hacktoberfest ngxux responsive responsive-web-design utils ux uxessentials viewport viewportmatcher
Last synced: about 2 months ago
JSON representation
UX essentials for angular to build richer apps easier
- Host: GitHub
- URL: https://github.com/sketch7/ngx.ux
- Owner: sketch7
- License: mit
- Created: 2018-11-23T17:47:34.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2024-11-21T00:16:21.000Z (2 months ago)
- Last Synced: 2024-11-21T01:22:34.378Z (2 months ago)
- Topics: angular, angular6, angular7, hacktoberfest, ngxux, responsive, responsive-web-design, utils, ux, uxessentials, viewport, viewportmatcher
- Language: TypeScript
- Homepage:
- Size: 1.34 MB
- Stars: 4
- Watchers: 6
- Forks: 4
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
[projectUri]: https://github.com/sketch7/ngx.ux
[changeLog]: ./CHANGELOG.md
[releaseWorkflowWiki]: ./docs/RELEASE-WORKFLOW.md
[npm]: https://www.npmjs.com
# @ssv/ngx.ux
[](https://github.com/sketch7/ngx.ux/actions/workflows/ci.yml)
[](https://badge.fury.io/js/%40ssv%2Fngx.ux)
> ## repo moved to https://github.com/sketch7/ssv.ngx
UX essentials for building apps, utilities which enables you writing richer apps easier.
**Quick links**
[Change logs][changeLog] | [Project Repository][projectUri]
## Installation
Get library via [npm]
```bash
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](./src/viewport/viewport-data/README.md)
# Usage
## Register module
```ts
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
```html
show only when large
=', 'xlarge']"> (see all operands and sizes)
show when >= xlarge
(see all operands and sizes)
show when >= xlarge
show only when large, xlarge
hide only when xsmall, small
=', 'xlarge']; else otherwise">
show when >= xlarge
show when expression is falsy (< xlarge)
(exclude xsmall)
```
### Viewport Matcher Var (directive)
Structural directive which provides the condition var whether it matches or not (params are similar to `ssvViewportMatcher`).
```html
isLarge={{isLarge}}
isMediumDown={{isMediumDown}}
isLargeOrSmall={{isLargeOrSmall}}
```
### Viewport Service
```ts
// 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.
```ts
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:
```ts
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
```ts
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
```ts
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:
```bash
npm install -g git gulp devtool
```
### Project Setup
The following process need to be executed in order to get started.
```bash
npm install
```
### Building the code
```bash
npm run build
```
### Running the tests
```bash
npm test
```
#### Watch
Handles compiling of changes.
```bash
npm start
```
#### Running Continuous Tests
Spawns test runner and keep watching for changes.
```bash
npm run tdd
```
### Preparation for Release
- Update changelogs
- bump version
Check out the [release workflow guide][releaseWorkflowWiki] 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`