wip

.prettierignore

@@ -4,4 +4,4 @@
 /src/core/basics/provider-compitibility
 /src/core/basics/validator-customization
 /src/core/composables/form-fallthrough
-/src/core/composables/media-query
+-/src/core/composables/media-query

angular.json

@@ -26,6 +26,53 @@
 			},
 			"projectType": "library",
 			"root": "."
+		},
+		"docs": {
+			"architect": {
+				"build": {
+					"builder": "@angular-devkit/build-angular:browser-esbuild",
+					"configurations": {
+						"development": {
+							"extractLicenses": false,
+							"optimization": false,
+							"sourceMap": true
+						},
+						"production": {
+							"outputHashing": "all"
+						}
+					},
+					"defaultConfiguration": "production",
+					"options": {
+						"allowedCommonJsDependencies": ["@messageformat/core"],
+						"assets": ["./src/docs/favicon.ico", "./src/docs/assets"],
+						"index": "./src/docs/index.html",
+						"inlineStyleLanguage": "scss",
+						"main": "./src/docs/main.ts",
+						"outputPath": "./docs",
+						"polyfills": ["zone.js"],
+						"styles": ["./src/docs/styles.scss"],
+						"tsConfig": "./src/docs/tsconfig.json"
+					}
+				},
+				"serve": {
+					"builder": "@angular-devkit/build-angular:dev-server",
+					"configurations": {
+						"development": {
+							"buildTarget": "docs:build:development"
+						},
+						"production": {
+							"buildTarget": "docs:build:production"
+						}
+					},
+					"defaultConfiguration": "development",
+					"options": {
+						"open": true
+					}
+				}
+			},
+			"projectType": "application",
+			"root": ".",
+			"sourceRoot": "./src/docs"
 		}
 	},
 	"version": 1

package.json

@@ -10,6 +10,8 @@
 	},
 	"scripts": {
 		"build": "ng build core",
+		"build:docs": "ng build docs",
+		"start:docs": "ng serve docs",
 		"test": "ng test",
 		"format": "prettier --write ."
 	},

src/core/basics/form-reactivity/README.md

@@ -1,3 +1,5 @@
+<!-- todo: better docs -->
+
 # Form Reactivity
 
 ## Usage

src/core/basics/form-reactivity/index.23907451.spec.ts

@@ -4,6 +4,8 @@ import {FormControl, FormGroup, Validators} from '@angular/forms';
 
 import {formi} from '.';
 
+// todo: better descriptions
+
 describe('formi', () => {
 	it('should reflect actual state', fakeAsync(async () => {
 		let form = new FormGroup({
@@ -15,6 +17,7 @@ describe('formi', () => {
 			}),
 		});
 
+		// todo
 		for await (let _ of (async function* () {
 			yield;
 			for (let fn of [
@@ -48,6 +51,7 @@ describe('formi', () => {
 	it('should trigger changes properly', fakeAsync(async () => {
 		let form = new FormControl(null);
 
+		// todo: rename
 		let effectFn = jest.fn(() => {
 			formi(form).disabled;
 		});

src/core/basics/form-reactivity/index.ts

@@ -29,13 +29,17 @@ export type ReadonlyReactiveFormProxy<
 	& Readonly<Pick<ControlT, ReadonlyReactiveFormProp>>
 );
 
+// todo: rework
+// todo: rename
 export const formi: {
 	<ControlT extends AbstractControl>(
 		control: ControlT,
 	): ReadonlyReactiveFormProxy<ControlT>;
 } = (() => {
 	let create = (control) => {
+		// todo: use helper
 		let changes$ = signal({});
+		// todo: use helper
 		[
 			'_updatePristine',
 			'_updateTouched',

src/core/basics/lggajrsh/index.ts

@@ -0,0 +1,31 @@
+import {DestroyRef, ElementRef, Signal, computed, inject, isSignal, signal} from '@angular/core';
+
+export const onDestroy: {
+	(fn: {(): void}): void;
+} = (fn) => {
+	let ref = inject(DestroyRef, {optional: true});
+	if (ref) {
+		ref.onDestroy(fn);
+	}
+};
+
+export type MaybeSignal<T> = T | Signal<T>;
+
+export const resolveSignal: {
+	<T>(v: MaybeSignal<T>): Signal<T>;
+} = (v) => (isSignal(v) ? v : signal(v).asReadonly());
+
+export type MaybeElementSignal<T> = MaybeSignal<T | ElementRef<T>>;
+
+export const resolveElementSignal: {
+	<T>(v: MaybeElementSignal<T>): Signal<T>;
+} = (v) => {
+	let v$ = resolveSignal(v);
+	return computed(() => {
+		let v = v$();
+		if (v instanceof ElementRef) {
+			return v.nativeElement;
+		}
+		return v;
+	});
+};

src/core/basics/provider-compitibility/README.md

@@ -1,3 +1,5 @@
+<!-- todo: better docs -->
+
 # Provider Compitibility
 
 Simplifies the definition of providers and extends it with type safety.

src/core/basics/provider-compitibility/index.45921704.spec.ts

@@ -25,18 +25,18 @@ describe('provide', () => {
 		b = faker.number.int();
 	}
 
-	describe('regular', () => {
+	describe('single', () => {
 		let token = new InjectionToken<A>('');
 
 		describe('useValue', () => {
-			it('should create correct provider', fakeAsync(async () => {
+			it('should create a correct provider', fakeAsync(async () => {
 				expect(provide(token).useValue(A.asValue)).toEqual({
 					provide: token,
 					useValue: A.asValue,
 				});
 			}));
 
-			it('should ensure type safety', fakeAsync(async () => {
+			it('should enforce type safety', fakeAsync(async () => {
 				expect(async () => {
 					// @ts-expect-error
 					provide(token).useValue(B.asValue);
@@ -51,14 +51,14 @@ describe('provide', () => {
 		});
 
 		describe('useFactory', () => {
-			it('should create correct provider', fakeAsync(async () => {
+			it('should create a correct provider', fakeAsync(async () => {
 				expect(provide(token).useFactory(A.asFactory)).toEqual({
 					provide: token,
 					useFactory: A.asFactory,
 				});
 			}));
 
-			it('should ensure type safety', fakeAsync(async () => {
+			it('should enforce type safety', fakeAsync(async () => {
 				expect(async () => {
 					// @ts-expect-error
 					provide(token).useFactory(A.asValue);
@@ -73,14 +73,14 @@ describe('provide', () => {
 		});
 
 		describe('useClass', () => {
-			it('should create correct provider', fakeAsync(async () => {
+			it('should create a correct provider', fakeAsync(async () => {
 				expect(provide(token).useClass(A.asClass)).toEqual({
 					provide: token,
 					useClass: A.asClass,
 				});
 			}));
 
-			it('should ensure type safety', fakeAsync(async () => {
+			it('should enforce type safety', fakeAsync(async () => {
 				expect(async () => {
 					// @ts-expect-error
 					provide(token).useClass(A.asValue);
@@ -95,14 +95,14 @@ describe('provide', () => {
 		});
 
 		describe('useExisting', () => {
-			it('should create correct provider', fakeAsync(async () => {
+			it('should create a correct provider', fakeAsync(async () => {
 				expect(provide(token).useExisting(A.asExisting)).toEqual({
 					provide: token,
 					useExisting: A.asExisting,
 				});
 			}));
 
-			it('should ensure type safety', fakeAsync(async () => {
+			it('should enforce type safety', fakeAsync(async () => {
 				expect(async () => {
 					// @ts-expect-error
 					provide(token).useExisting(A.asValue);
@@ -121,15 +121,15 @@ describe('provide', () => {
 		let token = new InjectionToken<Array<A>>('');
 
 		describe('useValue', () => {
-			it('should create correct provider', fakeAsync(async () => {
+			it('should create a correct provider', fakeAsync(async () => {
 				expect(provide(token, {multi: true}).useValue(A.asValue)).toEqual({
 					provide: token,
 					multi: true,
 					useValue: A.asValue,
 				});
 			}));
 
-			it('should ensure type safety', fakeAsync(async () => {
+			it('should enforce type safety', fakeAsync(async () => {
 				expect(async () => {
 					// @ts-expect-error
 					provide(token, {multi: true}).useValue(B.asValue);
@@ -144,15 +144,15 @@ describe('provide', () => {
 		});
 
 		describe('useFactory', () => {
-			it('should create correct provider', fakeAsync(async () => {
+			it('should create a correct provider', fakeAsync(async () => {
 				expect(provide(token, {multi: true}).useFactory(A.asFactory)).toEqual({
 					provide: token,
 					multi: true,
 					useFactory: A.asFactory,
 				});
 			}));
 
-			it('should ensure type safety', fakeAsync(async () => {
+			it('should enforce type safety', fakeAsync(async () => {
 				expect(async () => {
 					// @ts-expect-error
 					provide(token, {multi: true}).useFactory(A.asValue);
@@ -167,15 +167,15 @@ describe('provide', () => {
 		});
 
 		describe('useClass', () => {
-			it('should create correct provider', fakeAsync(async () => {
+			it('should create a correct provider', fakeAsync(async () => {
 				expect(provide(token, {multi: true}).useClass(A.asClass)).toEqual({
 					provide: token,
 					multi: true,
 					useClass: A.asClass,
 				});
 			}));
 
-			it('should ensure type safety', fakeAsync(async () => {
+			it('should enforce type safety', fakeAsync(async () => {
 				expect(async () => {
 					// @ts-expect-error
 					provide(token, {multi: true}).useClass(A.asValue);
@@ -190,7 +190,7 @@ describe('provide', () => {
 		});
 
 		describe('useExisting', () => {
-			it('should create correct provider', fakeAsync(async () => {
+			it('should create a correct provider', fakeAsync(async () => {
 				expect(provide(token, {multi: true}).useExisting(A.asExisting)).toEqual(
 					{
 						provide: token,
@@ -200,7 +200,7 @@ describe('provide', () => {
 				);
 			}));
 
-			it('should ensure type safety', fakeAsync(async () => {
+			it('should enforce type safety', fakeAsync(async () => {
 				expect(async () => {
 					// @ts-expect-error
 					provide(token, {multi: true}).useExisting(A.asValue);

src/core/basics/provider-compitibility/index.ts

@@ -29,6 +29,7 @@ export const provide: {
 } = (token, {
 	multi = false,
 } = {}) => {
+	// todo: rename
 	let provider = {provide: token, ...(multi ? {multi} : {})};
 	return oo(
 		...[

src/core/basics/validator-customization/README.md

@@ -1,3 +1,5 @@
+<!-- todo: better docs -->
+
 # Validator Customization
 
 ## Usage

src/core/basics/validator-customization/async/index.96048722.spec.ts

@@ -4,7 +4,7 @@ import {FormControl} from '@angular/forms';
 import {composeAsyncValidators, noopAsyncValidator, stubAsyncValidator, withAsyncValidators} from '.';
 
 describe('withAsyncValidators', () => {
-	it('should work', fakeAsync(async () => {
+	it('should work in a common scenario', fakeAsync(async () => {
 		let form = withAsyncValidators(
 			new FormControl<number>(1, {
 				nonNullable: true,
@@ -27,7 +27,7 @@ describe('withAsyncValidators', () => {
 		expect(form.errors).toBeNull();
 	}));
 
-	it('should contain validators', fakeAsync(async () => {
+	it('should contain all provided validators', fakeAsync(async () => {
 		let form = new FormControl(null);
 		let validators = [null, null].map((v) => async () => v);
 		withAsyncValidators(form, ...validators);
@@ -62,7 +62,7 @@ describe('withAsyncValidators', () => {
 });
 
 describe('composeAsyncValidators', () => {
-	it('should work', fakeAsync(async () => {
+	it('should work in a common scenario', fakeAsync(async () => {
 		let form = withAsyncValidators(
 			new FormControl<number>(1, {
 				nonNullable: true,
@@ -96,7 +96,7 @@ describe('composeAsyncValidators', () => {
 		expect(form.errors).toBeNull();
 	}));
 
-	it('should skip other validators after one fails', fakeAsync(async () => {
+	it('should skip remaining validators if one fails', fakeAsync(async () => {
 		let validators = [null, {error: true}, null].map((v) => jest.fn(async () => v));
 		new FormControl(null, {
 			asyncValidators: composeAsyncValidators(validators),
@@ -109,19 +109,19 @@ describe('composeAsyncValidators', () => {
 		expect(validators[2]).not.toHaveBeenCalled();
 	}));
 
-	it('should return same validator if only one provided', fakeAsync(async () => {
+	it('should return the same validator if only one provided', fakeAsync(async () => {
 		let validator = async () => null;
 
 		expect(composeAsyncValidators([validator])).toBe(validator);
 	}));
 
-	it('should return no-op validator if nothing provided', fakeAsync(async () => {
+	it('should return a no-op validator if no validators provided', fakeAsync(async () => {
 		expect(composeAsyncValidators([])).toBe(noopAsyncValidator);
 	}));
 });
 
 describe('noopAsyncValidator', () => {
-	it('should work', fakeAsync(async () => {
+	it('should return null', fakeAsync(async () => {
 		let form = withAsyncValidators(new FormControl(null), noopAsyncValidator);
 
 		tick();
@@ -131,7 +131,7 @@ describe('noopAsyncValidator', () => {
 });
 
 describe('stubAsyncValidator', () => {
-	it('should work', fakeAsync(async () => {
+	it('should return provided errors', fakeAsync(async () => {
 		let form = withAsyncValidators(new FormControl(null), stubAsyncValidator({error: true}));
 
 		tick();