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

package/src/viewport/viewport.module.ts

@@ -0,0 +1,19 @@
+import { NgModule } from "@angular/core";
+
+import { ViewportDataPipe } from "./viewport-data/viewport-data.pipe";
+import { SsvViewportMatcherVarDirective } from "./viewport-matcher-var.directive";
+import { SsvViewportMatcherDirective } from "./viewport-matcher.directive";
+
+const EXPORTED_IMPORTS = [
+	SsvViewportMatcherDirective,
+	SsvViewportMatcherVarDirective,
+	ViewportDataPipe,
+];
+
+@NgModule({
+	imports: [EXPORTED_IMPORTS],
+	exports: [EXPORTED_IMPORTS]
+})
+export class SsvUxViewportModule {
+
+}

package/src/viewport/viewport.options.ts

@@ -0,0 +1,74 @@
+import { type EnvironmentProviders, InjectionToken, makeEnvironmentProviders } from "@angular/core";
+
+import type { Dictionary } from "../internal/internal.model";
+import { ViewportDataMatchStrategy } from "./viewport-data/viewport-data-matcher";
+import { VIEWPORT_SSR_DEVICE } from "./viewport-server-size.service";
+import { DeviceType } from "./viewport.model";
+
+/** Default viewport breakpoints. */
+export const UX_VIEWPORT_DEFAULT_BREAKPOINTS: Dictionary<number> = {
+	xsmall: 450,
+	small: 767,
+	medium: 992,
+	large: 1200,
+	xlarge: 1500,
+	xxlarge: 1920,
+	xxlarge1: 2100,
+};
+
+export interface UxViewportOptions {
+	/** Polling speed on resizing (in milliseconds). e.g. the higher the number the longer it takes to recalculate. */
+	resizePollingSpeed: number;
+
+	/** Breakpoints to use. Key needs to match the size type and the value the width threshold.
+	 * e.g. given width '1000' and `medium` is set to '992' => `large`.
+	 */
+	breakpoints: Dictionary<number>;
+
+	/** Default data match strategy to use. */
+	defaultDataMatchStrategy: ViewportDataMatchStrategy;
+}
+
+const DEFAULT_OPTIONS = Object.freeze<UxViewportOptions>({
+	resizePollingSpeed: 33,
+	breakpoints: UX_VIEWPORT_DEFAULT_BREAKPOINTS,
+	defaultDataMatchStrategy: ViewportDataMatchStrategy.smaller,
+});
+
+export const VIEWPORT_OPTIONS = new InjectionToken<UxViewportOptions>("SSV_UX_VIEWPORT_OPTIONS", {
+	factory: () => DEFAULT_OPTIONS,
+});
+
+export function provideSsvUxViewportOptions(
+	options: Partial<UxViewportOptions> | ((defaults: Readonly<UxViewportOptions>) => Partial<UxViewportOptions>),
+	...features: EnvironmentProviders[]
+): EnvironmentProviders {
+	return makeEnvironmentProviders([
+		{
+			provide: VIEWPORT_OPTIONS,
+			useFactory: () => {
+				let opts = typeof options === "function" ? options(DEFAULT_OPTIONS) : options;
+				opts = opts
+					? {
+						...DEFAULT_OPTIONS,
+						...opts, // NOTE: breakpoints shoudn't be merged
+					}
+					: DEFAULT_OPTIONS;
+				return opts;
+			},
+		},
+		...features,
+	]);
+}
+
+export function withViewportSsrDevice(options: DeviceType | (() => DeviceType)): EnvironmentProviders {
+	return makeEnvironmentProviders([
+		{
+			provide: VIEWPORT_SSR_DEVICE,
+			useFactory: () => {
+				const deviceType = typeof options === "function" ? options() : options;
+				return deviceType;
+			},
+		},
+	]);
+}

package/src/viewport/viewport.service.ts

@@ -0,0 +1,123 @@
+import { Injectable, inject } from "@angular/core";
+import {
+	Observable,
+	fromEvent,
+	of,
+	map,
+	tap,
+	distinctUntilChanged,
+	startWith,
+	share,
+	shareReplay,
+	auditTime,
+} from "rxjs";
+
+import { ViewportSizeTypeInfo, ViewportSize } from "./viewport.model";
+import { WindowRef } from "../platform/window";
+import { ViewportServerSizeService } from "./viewport-server-size.service";
+import { generateViewportSizeTypeInfoList, generateViewportSizeTypeInfoRefs, getSizeTypeInfo } from "./viewport.util";
+import type { Dictionary } from "../internal/internal.model";
+import { VIEWPORT_OPTIONS } from "./viewport.options";
+
+@Injectable({
+	providedIn: "root",
+})
+export class ViewportService {
+
+	/** Window resize observable. */
+	readonly resizeSnap$: Observable<ViewportSize>;
+
+	/** Window resize observable (which is also throttled). */
+	readonly resize$: Observable<ViewportSize>;
+
+	/** Viewport size type observable (which is also throttled). */
+	readonly sizeType$: Observable<ViewportSizeTypeInfo>;
+
+	/** Viewport size type observable. */
+	readonly sizeTypeSnap$: Observable<ViewportSizeTypeInfo>;
+
+	/** Viewport size type snapshot of the last value. (Prefer use `sizeType$` observable when possible.) */
+	get sizeTypeSnapshot(): ViewportSizeTypeInfo { return this._sizeTypeSnapshot; }
+
+	/** Viewport size observable (which is also throttled). */
+	readonly size$: Observable<ViewportSize>;
+
+	/** Viewport size observable. */
+	readonly sizeSnap$: Observable<ViewportSize>;
+
+	/** Size types refs of the generated viewport size type info. */
+	get sizeTypeMap(): Dictionary<ViewportSizeTypeInfo> { return this._sizeTypeMap; }
+
+	/** Viewport size types list ordered by type, smallest to largest. */
+	get sizeTypes(): ViewportSizeTypeInfo[] { return this._sizeTypes; }
+
+	private _sizeTypeMap: Dictionary<ViewportSizeTypeInfo>;
+	private _sizeTypes: ViewportSizeTypeInfo[];
+	private _sizeTypeSnapshot: ViewportSizeTypeInfo;
+
+	constructor(
+		private windowRef: WindowRef,
+		private viewportServerSize: ViewportServerSizeService,
+	) {
+		const config = inject(VIEWPORT_OPTIONS);
+		this._sizeTypes = generateViewportSizeTypeInfoList(config.breakpoints);
+		this._sizeTypeMap = generateViewportSizeTypeInfoRefs(this._sizeTypes);
+
+		if (windowRef.hasNative) {
+			this.resizeSnap$ = fromEvent<Event>(window, "resize").pipe(
+				map(() => this.getViewportSize()),
+				share()
+			);
+
+			this.resize$ = this.resizeSnap$.pipe(
+				auditTime(config.resizePollingSpeed),
+				share(),
+			);
+		} else {
+			this.resizeSnap$ = this.resize$ = of(viewportServerSize.get());
+		}
+		const size = this.getViewportSize();
+		this._sizeTypeSnapshot = getSizeTypeInfo(size.width, this.sizeTypes);
+
+		const sizeFn = (obs$: Observable<ViewportSize>) => obs$.pipe(
+			startWith(size),
+			distinctUntilChanged((a, b) => a.width === b.width && a.height === b.height),
+			shareReplay(1),
+		);
+
+		this.sizeSnap$ = sizeFn(this.resizeSnap$);
+		this.size$ = sizeFn(this.resize$);
+
+		const sizeTypeFn = (obs$: Observable<ViewportSize>) => obs$.pipe(
+			distinctUntilChanged((a, b) => a.width === b.width),
+			map(x => getSizeTypeInfo(x.width, this.sizeTypes)),
+			distinctUntilChanged(),
+			tap(x => this._sizeTypeSnapshot = x),
+			shareReplay(1),
+		);
+
+		this.sizeType$ = sizeTypeFn(this.size$);
+		this.sizeTypeSnap$ = sizeTypeFn(this.sizeSnap$);
+	}
+
+	/** Returns the current viewport size */
+	private getViewportSize(): ViewportSize {
+		if (!this.windowRef.hasNative) {
+			return this.viewportServerSize.get();
+		}
+
+		const ua = navigator.userAgent.toLowerCase();
+		if (ua.indexOf("safari") !== -1 && ua.indexOf("chrome") === -1) { // safari subtracts the scrollbar width
+			return {
+				width: this.windowRef.native.document.documentElement.clientWidth,
+				height: this.windowRef.native.document.documentElement.clientHeight,
+			};
+		}
+
+		return {
+			width: this.windowRef.native.innerWidth,
+			height: this.windowRef.native.innerHeight,
+		};
+	}
+
+}

package/src/viewport/viewport.util.spec.ts

@@ -0,0 +1,254 @@
+import {
+	isViewportConditionMatch as isViewportConditionMatch_,
+	generateViewportSizeTypeInfoList,
+	generateViewportSizeTypeInfoRefs,
+	generateViewportSizeType,
+	getSizeTypeInfo,
+} from "./viewport.util";
+import { ComparisonOperation, ViewportMatchConditions, ViewportSizeType, ViewportSizeTypeInfo } from "./viewport.model";
+import { UX_VIEWPORT_DEFAULT_BREAKPOINTS } from "./viewport.options";
+
+export enum TestViewportSizeType {
+	xsmall = 0,
+	small = 1,
+	medium = 2,
+	large = 3,
+	hd = 4,
+	fullHd = 5,
+}
+
+const breakpoints: Record<keyof typeof TestViewportSizeType, number> = {
+	xsmall: 450,
+	small: 767,
+	medium: 992,
+	large: 1200,
+	hd: 1280,
+	fullHd: 1920,
+};
+const sizeTypes = generateViewportSizeTypeInfoList(breakpoints);
+const sizeRefs = generateViewportSizeTypeInfoRefs(sizeTypes) as Record<keyof typeof TestViewportSizeType, ViewportSizeTypeInfo>;
+
+const isViewportConditionMatch = (
+	evaluateSize: ViewportSizeTypeInfo,
+	conditions: ViewportMatchConditions
+) => isViewportConditionMatch_(evaluateSize, conditions, sizeRefs);
+
+describe("Viewport utils", () => {
+
+	describe("given default breakpoints", () => {
+
+		it("should match ViewportSizeType definition", () => {
+			const result = Object.keys(UX_VIEWPORT_DEFAULT_BREAKPOINTS).reduce((r, key) => {
+				const idx = ViewportSizeType[key as unknown as ViewportSizeType];
+
+				expect(idx).not.toBeUndefined();
+				r.push(idx);
+				return r;
+			}, [] as string[]);
+
+			const viewportSizeTypeItems = Object.keys(ViewportSizeType).filter(v => isNaN(+v));
+			expect(viewportSizeTypeItems.length).toBe(result.length);
+		});
+
+	});
+
+
+	describe("generateViewportSizeType", () => {
+
+		describe("given custom breakpoints are used", () => {
+			const result = generateViewportSizeType(breakpoints);
+
+			it("should match the expected key/value pair", () => {
+				expect(result).toEqual(({
+					0: "xsmall",
+					1: "small",
+					2: "medium",
+					3: "large",
+					4: "hd",
+					5: "fullHd",
+					xsmall: 0,
+					small: 1,
+					medium: 2,
+					large: 3,
+					hd: 4,
+					fullHd: 5,
+				}));
+			});
+		});
+
+	});
+
+
+	describe("generateViewportSizeTypeInfoList", () => {
+
+		describe("given custom breakpoints are used", () => {
+			const result = generateViewportSizeTypeInfoList(breakpoints);
+
+			it("should match", () => {
+				expect(result).toEqual([
+					{ name: "xsmall", type: 0, widthThreshold: 450 },
+					{ name: "small", type: 1, widthThreshold: 767 },
+					{ name: "medium", type: 2, widthThreshold: 992 },
+					{ name: "large", type: 3, widthThreshold: 1200 },
+					{ name: "hd", type: 4, widthThreshold: 1280 },
+					{ name: "fullHd", type: 5, widthThreshold: 1920 }
+				]);
+			});
+		});
+
+	});
+
+
+	describe("generateViewportSizeTypeInfoRefs", () => {
+
+		describe("given custom breakpoints are used", () => {
+			const sizes = generateViewportSizeTypeInfoList(breakpoints);
+			const result = generateViewportSizeTypeInfoRefs(sizes);
+
+			it("should match", () => {
+				expect(result).toEqual(
+					{
+						xsmall: { name: "xsmall", type: 0, widthThreshold: 450 },
+						small: { name: "small", type: 1, widthThreshold: 767 },
+						medium: { name: "medium", type: 2, widthThreshold: 992 },
+						large: { name: "large", type: 3, widthThreshold: 1200 },
+						hd: { name: "hd", type: 4, widthThreshold: 1280 },
+						fullHd: { name: "fullHd", type: 5, widthThreshold: 1920 },
+						0: { name: "xsmall", type: 0, widthThreshold: 450 },
+						1: { name: "small", type: 1, widthThreshold: 767 },
+						2: { name: "medium", type: 2, widthThreshold: 992 },
+						3: { name: "large", type: 3, widthThreshold: 1200 },
+						4: { name: "hd", type: 4, widthThreshold: 1280 },
+						5: { name: "fullHd", type: 5, widthThreshold: 1920 },
+					}
+				);
+			});
+		});
+
+	});
+
+	describe("getSizeTypeInfo", () => {
+		describe("when different widths are passed", () => {
+
+			it("should match", () => {
+				const dataSet = [
+					{ width: 10, expectedSize: "xsmall" },
+					{ width: 450, expectedSize: "xsmall" },
+					{ width: 992, expectedSize: "medium" },
+					{ width: 993, expectedSize: "large" },
+					{ width: 1199, expectedSize: "large" },
+					{ width: 1200, expectedSize: "large" },
+					{ width: 1201, expectedSize: "hd" },
+					{ width: 1280, expectedSize: "hd" },
+					{ width: 1281, expectedSize: "fullHd" },
+					{ width: 1920, expectedSize: "fullHd" },
+					{ width: 2000, expectedSize: "fullHd" },
+				];
+
+				for (const data of dataSet) {
+					const result = getSizeTypeInfo(data.width, sizeTypes);
+					expect(result.name).toBe(data.expectedSize);
+				}
+			});
+
+		});
+	});
+
+
+	describe("isViewportConditionMatch", () => {
+
+		describe("given only size include is used", () => {
+
+			describe("when single matching value is passed", () => {
+				const sizeType = "small";
+				const viewportRef = sizeRefs[sizeType];
+				const result = isViewportConditionMatch(viewportRef, { sizeType });
+
+				it("should return true", () => {
+					expect(result).toBe(true);
+				});
+			});
+
+			describe("when single not matching value is passed", () => {
+				const viewportRef = sizeRefs.small;
+				const result = isViewportConditionMatch(viewportRef, { sizeType: "xsmall" });
+
+				it("should return false", () => {
+					expect(result).toBe(false);
+				});
+			});
+
+			describe("when multi values are passed with a matching value", () => {
+				const viewportRef = sizeRefs.small;
+				const result = isViewportConditionMatch(viewportRef, {
+					sizeType: ["small", "medium"]
+				});
+
+				it("should return true", () => {
+					expect(result).toBe(true);
+				});
+			});
+
+			describe("when multi values are passed with a non matching value", () => {
+				const viewportRef = sizeRefs.large;
+				const result = isViewportConditionMatch(viewportRef, {
+					sizeType: ["small", "medium"]
+				});
+
+				it("should return false", () => {
+					expect(result).toBe(false);
+				});
+			});
+		});
+
+		describe("given expression tuple is used", () => {
+			describe("when different expressions are passed", () => {
+
+				it("should match", () => {
+					const dataSet = [
+						{
+							size: sizeRefs.small,
+							expression: { operation: ComparisonOperation.equals, size: "small" },
+							expectedResult: true
+						},
+						{
+							size: sizeRefs.xsmall,
+							expression: { operation: ComparisonOperation.notEquals, size: "small" },
+							expectedResult: true
+						},
+						{
+							size: sizeRefs.small,
+							expression: { operation: ComparisonOperation.notEquals, size: "small" },
+							expectedResult: false
+						},
+						{
+							size: sizeRefs.small,
+							expression: { operation: ComparisonOperation.lessThan, size: "medium" },
+							expectedResult: true
+						},
+						{
+							size: sizeRefs.medium,
+							expression: { operation: ComparisonOperation.lessThan, size: "medium" },
+							expectedResult: false
+						},
+						{
+							size: sizeRefs.medium,
+							expression: { operation: ComparisonOperation.lessOrEqualThan, size: "medium" },
+							expectedResult: true
+						},
+					];
+
+					for (const data of dataSet) {
+						const result = isViewportConditionMatch(data.size, {
+							expression: data.expression
+						});
+						expect(result).toBe(data.expectedResult);
+					}
+				});
+
+			});
+		});
+
+	});
+
+});

package/src/viewport/viewport.util.ts

@@ -0,0 +1,152 @@
+import { Dictionary } from "../internal/internal.model";
+import {
+	ComparisonOperation,
+	ViewportSizeMatcherExpression,
+	ViewportSizeTypeInfo,
+	ViewportMatchConditions
+} from "./viewport.model";
+
+export function isViewportSizeMatcherExpression(value: unknown): value is ViewportSizeMatcherExpression {
+	if (typeof value !== "object" || !value) {
+		return false;
+	}
+	const args: Partial<ViewportSizeMatcherExpression> = value;
+	if (args.size && args.operation) {
+		return true;
+	}
+	return false;
+}
+
+export function isViewportSizeMatcherTupleExpression(arg: unknown): arg is [ComparisonOperation, string] {
+	if (!arg) {
+		return false;
+	}
+	if (Array.isArray(arg)) {
+		if (arg.length === 2) {
+			const [op] = arg;
+			return operations.includes(op);
+		}
+	}
+	return false;
+}
+
+
+const operations = Object.values(ComparisonOperation);
+
+export const COMPARISON_OPERATION_FUNC_MAPPING: Dictionary<(a: number, b: number) => boolean> = {
+	[ComparisonOperation.equals]: (a: number, b: number) => a === b,
+	[ComparisonOperation.notEquals]: (a: number, b: number) => a !== b,
+	[ComparisonOperation.lessThan]: (a: number, b: number) => a < b,
+	[ComparisonOperation.lessOrEqualThan]: (a: number, b: number) => a <= b,
+	[ComparisonOperation.greaterThan]: (a: number, b: number) => a > b,
+	[ComparisonOperation.greaterOrEqualThan]: (a: number, b: number) => a >= b,
+};
+
+export function isViewportConditionMatch(
+	evaluateSize: ViewportSizeTypeInfo,
+	conditions: ViewportMatchConditions,
+	viewportSizeTypeInfoRefs: Dictionary<ViewportSizeTypeInfo>
+): boolean {
+	const isExcluded = match(conditions.sizeTypeExclude, evaluateSize.name, false);
+	let isIncluded;
+	let isExpressionTruthy;
+
+	if (!isExcluded && conditions.expression) {
+		const ref = viewportSizeTypeInfoRefs[conditions.expression.size];
+		if(!ref) {
+			throw new Error(`Viewport size type is invalid. Size type: '${conditions.expression.size}'`);
+		}
+		const expMatcher = COMPARISON_OPERATION_FUNC_MAPPING[conditions.expression.operation];
+
+		isExpressionTruthy = expMatcher(evaluateSize.type, ref.type);
+	} else {
+		isIncluded = match(conditions.sizeType, evaluateSize.name, true);
+	}
+
+	const shouldRender = (isExpressionTruthy || isIncluded) && !isExcluded;
+	// console.warn(">>> shouldRender", { evaluateSize, conditions, shouldRender });
+	return !!shouldRender;
+}
+
+function match(value: string | string[] | null | undefined, targetValue: string, defaultValue: boolean) {
+	if (!value) {
+		return defaultValue;
+	}
+
+	return Array.isArray(value)
+		? value.includes(targetValue)
+		: value === targetValue;
+}
+
+export function getSizeTypeInfo(width: number, sizeTypes: ViewportSizeTypeInfo[]): ViewportSizeTypeInfo {
+	const lastEntryIndex = sizeTypes.length - 1;
+
+	for (let idx = 0; idx < lastEntryIndex; idx++) {
+		const viewportSizeTypeInfo = sizeTypes[idx];
+
+		if (width <= viewportSizeTypeInfo.widthThreshold) {
+			return viewportSizeTypeInfo;
+		}
+	}
+
+	return sizeTypes[lastEntryIndex];
+}
+
+/**
+ * Converts the breakpoints into a 2 dimensional array containing the name and width, and sorted from
+ *  smallest to largest.
+ * @param breakpoints the breakpoints obtained from the config
+ * @internal
+ */
+function getSortedBreakpoints(breakpoints: Dictionary<number>): [string, number][] {
+	return Object.entries(breakpoints)
+		.sort(([, widthA], [, widthB]) => widthA - widthB);
+}
+
+/**
+ * A util function which generates the ViewportSizeTypeInfo.type for each breakpoint.
+ * @param breakpoints the custom breakpoints
+ */
+export function generateViewportSizeType<T extends Record<string, number>>(breakpoints: T): T & Record<number, string> {
+	return Object.freeze(
+		getSortedBreakpoints(breakpoints).reduce<Record<number | string, string | number>>(
+			(dictionary, [name], index) => {
+				dictionary[name] = index;
+				dictionary[index] = name;
+				return dictionary;
+			}, {}
+		)
+	) as T & Record<number, string>;
+}
+
+/**
+ * Pre-processes the given breakpoints into an ordered list from smallest to largest while generating
+ *  all the necessary information on the viewport.
+ * @param breakpoints the breakpoints obtained from the config
+ * @internal
+ */
+export function generateViewportSizeTypeInfoList(breakpoints: Dictionary<number>): ViewportSizeTypeInfo[] {
+	return getSortedBreakpoints(breakpoints)
+		.map(([name, width], index) =>
+			(Object.freeze({
+				name,
+				type: index,
+				widthThreshold: width
+			}))
+		);
+}
+
+/**
+ * Converts the breakpoint list into a dictionary while using the name as key.
+ * @param breakpointList the list of breakpoints
+ * @internal
+ */
+export function generateViewportSizeTypeInfoRefs(breakpointList: ViewportSizeTypeInfo[]): Dictionary<ViewportSizeTypeInfo> {
+	return Object.freeze(
+		breakpointList.reduce<Dictionary<ViewportSizeTypeInfo>>((dictionary, breakpoint) => {
+			dictionary[breakpoint.name] = breakpoint;
+			dictionary[breakpoint.type] = breakpoint;
+			return dictionary;
+		}, {})
+	);
+}

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ],
+  "extends": "../../tsconfig.base.json",
+  "angularCompilerOptions": {
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "strictTemplates": true
+  }
+}

package/tsconfig.lib.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "declaration": true,
+    "declarationMap": true,
+    "inlineSources": true,
+    "types": []
+  },
+  "exclude": ["src/**/*.spec.ts", "src/test-setup.ts", "jest.config.ts", "src/**/*.test.ts"],
+  "include": ["src/**/*.ts"]
+}

package/tsconfig.lib.prod.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.lib.json",
+  "compilerOptions": {
+    "declarationMap": false
+  },
+  "angularCompilerOptions": {
+    "compilationMode": "partial"
+  }
+}

package/tsconfig.spec.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "module": "commonjs",
+    "target": "es2016",
+    "types": ["jest", "node"]
+  },
+  "files": ["src/test-setup.ts"],
+  "include": ["jest.config.ts", "src/**/*.test.ts", "src/**/*.spec.ts", "src/**/*.d.ts"]
+}