@ssv/ngx.ux 2.1.2 → 3.0.0-dev.32

package/README.md

@@ -1,19 +1,10 @@
-[projectUri]: https://github.com/sketch7/ngx.ux
-[changeLog]: ./CHANGELOG.md
-[releaseWorkflowWiki]: ./docs/RELEASE-WORKFLOW.md
-
 [npm]: https://www.npmjs.com
 
 # @ssv/ngx.ux
-[![CI](https://github.com/sketch7/ngx.ux/actions/workflows/ci.yml/badge.svg)](https://github.com/sketch7/ngx.ux/actions/workflows/ci.yml)
 [![npm version](https://badge.fury.io/js/%40ssv%2Fngx.ux.svg)](https://badge.fury.io/js/%40ssv%2Fngx.ux)
 
 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]
@@ -26,29 +17,17 @@ Choose the version corresponding to your Angular version:
 
  | Angular | library |
  | ------- | ------- |
+ | 17+     | 3.x+    |
  | 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)
 
@@ -161,10 +140,19 @@ Since in SSR there is no way to know the client viewport size, we should at leas
 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";
+import { withViewportSsrDevice } from "@ssv/ngx.ux";
 
 const deviceType = deviceTypeFromServer;
-{ provide: UX_VIEWPORT_SSR_DEVICE, useValue: deviceType },
+export const appConfig: ApplicationConfig = {
+  providers: [
+    withViewportSsrDevice(deviceType)
+    // or
+    provideSsvUxViewportOptions(
+      {},
+      withViewportSsrDevice(deviceType)
+    )
+  ]
+}
 ```
 
 The default implementation can also be replaced by implementing a small class as following:
@@ -180,11 +168,10 @@ export class SuperViewportServerSizeService {
 
 import { ViewportServerSizeService } from "@ssv/ngx.ux";
 
-@NgModule( {
+export const appConfig: ApplicationConfig = {
   providers: [
     { provide: ViewportServerSizeService, useClass: SuperViewportServerSizeService }
   ]
-}) export class AppModule {
 }
 ```
 
@@ -194,7 +181,7 @@ You can configure the existing resize polling speed and as well as provide your
 
 ### Custom Breakpoints
 ```ts
-import { SsvUxModule, generateViewportSizeType } from "@ssv/ngx.ux";
+import { provideSsvUxViewportOptions, generateViewportSizeType } from "@ssv/ngx.ux";
 
 const breakpoints = { // custom breakpoints - key/width
   smallest: 500,
@@ -207,98 +194,25 @@ const breakpoints = { // custom breakpoints - key/width
   uhd: 3840
 };
 
-  imports: [
-    SsvUxModule.forRoot({
-      viewport: {
-        resizePollingSpeed: 66, // optional - defaults to 33
-        breakpoints // provide the custom breakpoints
-      }
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideSsvUxViewportOptions({
+      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: {
+    // override existing breakpoints
+    provideSsvUxViewportOptions(defaults => {
+      return {
         breakpoints: {
-          ...UX_VIEWPORT_DEFAULT_BREAKPOINTS, // use breakpoints provided with library
-          xxlarge1: 2000, // override xxlarge1
-          uhd: 3840 // add new breakpoint
+          ...defaults.breakpoints,
+          small: 1000,
         }
-      }
+      };
     }),
-  ],
-```
-
-
-## 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`

package/eslint.config.js

@@ -0,0 +1,43 @@
+const nx = require("@nx/eslint-plugin");
+const baseConfig = require("../../eslint.config.js");
+
+module.exports = [
+	...baseConfig,
+	{
+		files: ["**/*.json"],
+		rules: {
+			"@nx/dependency-checks": ["error", { ignoredFiles: ["{projectRoot}/eslint.config.{js,cjs,mjs}"] }],
+		},
+		languageOptions: { parser: require("jsonc-eslint-parser") },
+	},
+	...nx.configs["flat/angular"],
+	...nx.configs["flat/angular-template"],
+	{
+		files: ["**/*.ts"],
+		rules: {
+			"@angular-eslint/directive-selector": [
+				"error",
+				{
+					type: "attribute",
+					prefix: "ssv",
+					style: "camelCase",
+				},
+			],
+			"@angular-eslint/component-selector": [
+				"error",
+				{
+					type: "element",
+					prefix: "ssv",
+					style: "kebab-case",
+				},
+			],
+			"@angular-eslint/directive-selector": "off",
+			"@angular-eslint/no-input-rename": "off",
+		},
+	},
+	{
+		files: ["**/*.html"],
+		// Override or add rules here
+		rules: {},
+	},
+];

package/index.ts

@@ -0,0 +1 @@
+export * from "./src/index";

package/jest.config.ts

@@ -0,0 +1,21 @@
+export default {
+	displayName: "ngx.ux",
+	preset: "../../jest.preset.js",
+	setupFilesAfterEnv: ["<rootDir>/src/test-setup.ts"],
+	coverageDirectory: "../../coverage/libs/ngx.ux",
+	transform: {
+		"^.+\\.(ts|mjs|js|html)$": [
+			"jest-preset-angular",
+			{
+				tsconfig: "<rootDir>/tsconfig.spec.json",
+				stringifyContentPathRegex: "\\.(html|svg)$",
+			},
+		],
+	},
+	transformIgnorePatterns: ["node_modules/(?!.*\\.mjs$)"],
+	snapshotSerializers: [
+		"jest-preset-angular/build/serializers/no-ng-attributes",
+		"jest-preset-angular/build/serializers/ng-snapshot",
+		"jest-preset-angular/build/serializers/html-comment",
+	],
+};

package/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/libs/ngx.ux",
+  "lib": {
+    "entryFile": "src/index.ts"
+  }
+}

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@ssv/ngx.ux",
-  "version": "2.1.2",
+  "version": "3.0.0-dev.32",
   "versionSuffix": "",
   "description": "UX essentials for building apps, utilities which enables you writing richer apps easier.",
   "keywords": [
     "sketch7",
     "ngx",
-    "angular15",
     "angular",
     "ssv",
     "ux",
@@ -20,37 +19,12 @@
   "private": false,
   "repository": {
     "type": "git",
-    "url": "https://github.com/sketch7/ngx.ux.git"
-  },
-  "dependencies": {
-    "tslib": "^2.0.0"
+    "url": "https://github.com/sketch7/ssv.ngx.git"
   },
+  "dependencies": {},
   "peerDependencies": {
-    "@angular/core": ">=6.0.0",
-    "lodash": "^4.0.0",
+    "@angular/core": ">=17.0.0",
     "rxjs": ">=6.0.0"
   },
-  "resolutions": {
-    "natives": "1.1.3"
-  },
-  "module": "fesm2015/ssv-ngx.ux.mjs",
-  "es2020": "fesm2020/ssv-ngx.ux.mjs",
-  "esm2020": "esm2020/ssv-ngx.ux.mjs",
-  "fesm2020": "fesm2020/ssv-ngx.ux.mjs",
-  "fesm2015": "fesm2015/ssv-ngx.ux.mjs",
-  "typings": "index.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./index.d.ts",
-      "esm2020": "./esm2020/ssv-ngx.ux.mjs",
-      "es2020": "./fesm2020/ssv-ngx.ux.mjs",
-      "es2015": "./fesm2015/ssv-ngx.ux.mjs",
-      "node": "./fesm2015/ssv-ngx.ux.mjs",
-      "default": "./fesm2020/ssv-ngx.ux.mjs"
-    }
-  },
   "sideEffects": false
 }

package/project.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ssv/ngx.ux",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/ngx.ux/src",
+  "prefix": "ssv",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/angular:package",
+      "outputs": ["{workspaceRoot}/dist/{projectRoot}"],
+      "options": {
+        "project": "libs/ngx.ux/ng-package.json"
+      },
+      "configurations": {
+        "production": {
+          "tsConfig": "libs/ngx.ux/tsconfig.lib.prod.json"
+        },
+        "development": {
+          "tsConfig": "libs/ngx.ux/tsconfig.lib.json"
+        }
+      },
+      "defaultConfiguration": "production"
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "options": {
+        "jestConfig": "libs/ngx.ux/jest.config.ts"
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint"
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { SsvUxModule } from "./ux.module";
+export * from "./viewport/index";
+
+export { VERSION } from "./version";

package/src/internal/internal.model.ts

@@ -0,0 +1,3 @@
+export interface Dictionary<T> {
+	[key: string]: T;
+}

package/src/platform/window.ts

@@ -0,0 +1,31 @@
+import { InjectionToken, Injectable, inject } from "@angular/core";
+
+export const WINDOW = new InjectionToken<Window>("Window", {
+	factory: () => _window() as Window,
+});
+
+export function _window(): unknown {
+	if (typeof window !== "undefined") {
+		return window;
+	}
+	return {};
+}
+
+@Injectable({
+	providedIn: "root",
+})
+export class WindowRef {
+
+	private readonly window = inject(WINDOW);
+
+	/** Window underlying native object. */
+	get native(): Window {
+		return this.window as Window;
+	}
+
+	/** Determines whether native element is supported or not. Generally `false` when executing in SSR. */
+	get hasNative(): boolean {
+		return !!this.native.window;
+	}
+
+}

package/src/test-setup.ts

@@ -0,0 +1,8 @@
+// @ts-expect-error https://thymikee.github.io/jest-preset-angular/docs/getting-started/test-environment
+globalThis.ngJest = {
+	testEnvironmentOptions: {
+		errorOnUnknownElements: true,
+		errorOnUnknownProperties: true,
+	},
+};
+import "jest-preset-angular/setup-jest";

package/src/ux.module.ts

@@ -0,0 +1,15 @@
+import { NgModule } from "@angular/core";
+
+import { SsvUxViewportModule } from "./viewport/viewport.module";
+
+const EXPORTED_IMPORTS = [
+	SsvUxViewportModule,
+];
+
+@NgModule({
+	imports: [EXPORTED_IMPORTS],
+	exports: [EXPORTED_IMPORTS]
+})
+export class SsvUxModule {
+
+}

package/src/version.ts

@@ -0,0 +1 @@
+export const VERSION = "3.0.0-dev.32";

package/src/viewport/index.ts

@@ -0,0 +1,20 @@
+export * from "./viewport-data/index";
+
+export { SsvUxViewportModule } from "./viewport.module";
+export { provideSsvUxViewportOptions, VIEWPORT_OPTIONS, type UxViewportOptions, withViewportSsrDevice } from "./viewport.options";
+
+export { SsvViewportMatcherVarDirective, SsvViewportMatcherVarContext } from "./viewport-matcher-var.directive";
+export { SsvViewportMatcherDirective, SsvViewportMatcherContext } from "./viewport-matcher.directive";
+export { VIEWPORT_SSR_DEVICE, ViewportServerSizeService } from "./viewport-server-size.service";
+export {
+	type ComparisonOperationValueType,
+	type ComparisonOperationLiteral,
+	type ComparisonOperationKeyType,
+	type ViewportSize,
+	type ViewportSizeTypeInfo,
+	ComparisonOperation,
+	DeviceType,
+	ViewportSizeType,
+} from "./viewport.model";
+export { ViewportService } from "./viewport.service";
+export { generateViewportSizeType } from "./viewport.util";

package/src/viewport/viewport-data/README.md

@@ -0,0 +1,47 @@
+# Viewport Data
+Data/config per viewport with fallback strategies
+
+## Usage
+
+```ts
+import { ViewportDataConfig } from "@ssv/ngx.ux";
+
+// define data config object
+dataConfig: ViewportDataConfig<string> = {
+  default: "default",
+  small: "small",
+  large: "large",
+  xlarge: "laaarger (xlarge)",
+};
+```
+
+```html
+{{ dataConfig | ssvViewportData: "smaller" }}
+```
+
+### Using Service
+```ts
+import { ViewportDataService, ViewportDataConfig } from "@ssv/ngx.ux";
+
+class MyComp {
+
+  constructor(
+    viewportDataService: ViewportDataService
+  ) {
+    viewportDataService.get$(dataConfig, ViewportDataMatchStrategy.smaller).pipe(
+      tap(x => console.log("Viewport - data changed", x)),
+    ).subscribe(); // handle unsubscribe
+  }
+
+}
+```
+
+### Viewport Matcher Strategies
+
+| Strategy            | Description                                                                                                   |
+| ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| exact               | Size should match exact or default.                                                                           |
+| smaller             | Size matches when exact, first match smaller (down) or default.                                               |
+| larger              | Size matches when exact match, first match larger (up) or default.                                            |
+| closestSmallerFirst | size matches when exact match, or it tries both smaller/larger (smaller is preferred) until match or default. |
+| closestLargerFirst  | Size matches when exact match, or it tries both larger/smaller (larger is preferred) until match or default.  |

package/src/viewport/viewport-data/index.ts

@@ -0,0 +1,3 @@
+export { ViewportDataService } from "./viewport-data.service";
+export { ViewportDataPipe } from "./viewport-data.pipe";
+export { type ViewportDataConfig, ViewportDataMatchStrategy, type ViewportDataMatchStrategyLiteral } from "./viewport-data-matcher";