vivth 1.4.10 → 1.5.0

package/src/web/signals/ObserverSignal.mjs

@@ -0,0 +1,93 @@
+// @ts-check
+
+import { Console } from '../../class/Console.mjs';
+import { Signal } from '../../class/Signal.mjs';
+/**
+ * @import {ParametersFollowingN} from '../../typehints/ParametersFollowingN.mts'
+ */
+
+/**
+ * @typedef {import('../../typehints/VivthCleanup.mjs').VivthCleanup} VivthCleanup
+ */
+
+/**
+ * @description
+ * - helper to create lazy `MutationObserver`;
+ * - use in tandem with `WC_extends`;
+ * @implements {VivthCleanup}
+ * @extends {Signal<MutationRecord[]|undefined>}
+ */
+export class ObserverSignal extends Signal {
+	/**
+	 * @description
+	 * @override
+	 * - cleanup callback;
+	 */
+	vivthCleanup = async () => {
+		this.unobserve();
+	};
+	/**
+	 * @param { MutationRecord[] | undefined} mutationRecords
+	 */
+	#modifySuperValue(mutationRecords) {
+		super.value = mutationRecords;
+	}
+	/**
+	 * @description
+	 * @param {Node} node
+	 * @param {ParametersFollowingN<
+	 * 	MutationObserver["observe"],1
+	 * >} mutationObserverInitArgs
+	 * - no default value;
+	 */
+	constructor(node, ...mutationObserverInitArgs) {
+		super(undefined);
+		this.#node = node;
+		this.#observer = new MutationObserver(this.#recordHandler);
+		this.#observer.observe(node, ...mutationObserverInitArgs);
+	}
+	/**
+	 * @type {Node}
+	 */
+	#node;
+	/**
+	 * @type {MutationObserver|undefined}
+	 */
+	#observer;
+	/**
+	 * @type {MutationCallback}
+	 */
+	#recordHandler(mutationRecords) {
+		super.value = mutationRecords;
+	}
+	/**
+	 * @override
+	 */
+	set value(_) {
+		Console.error({ node: this.#node, message: 'you cannot manually set ObserverSignal value' });
+	}
+	/**
+	 * @description
+	 * @override
+	 */
+	get value() {
+		return super.value;
+	}
+	/**
+	 * @description
+	 * - unobserve element;
+	 */
+	unobserve = () => {
+		const mutationRecords = this.#observer?.takeRecords();
+		this.#observer?.disconnect();
+		this.#observer = undefined;
+		this.subscribers.notify(
+			async () => {
+				this.#modifySuperValue(mutationRecords);
+			},
+			async () => {
+				this.remove.ref();
+			},
+		);
+	};
+}

package/src/web/signals/WC_litRef.mjs

@@ -0,0 +1,61 @@
+// @ts-check
+
+import { createRef, ref } from 'lit-html/directives/ref.js';
+
+import { Signal } from '../../class/Signal.mjs';
+import { Console } from '../../class/Console.mjs';
+import { Timeout } from '../../function/Timeout.mjs';
+
+/**
+ * @import {Ref, RefDirective,} from 'lit-html/directives/ref.js'
+ * @import {DirectiveResult} from 'lit-html/directive.js'
+ */
+
+/**
+ * @description
+ * - signal to get element reference on lit render;
+ * - warning, this class relies on creating macro task to trick lit-html render ref to get the `Element` reference, it might not be too accurate;
+ * @template {Element} EL
+ * @extends {Signal<EL|undefined>}
+ */
+export class WC_litRef extends Signal {
+	/**
+	 * @description
+	 */
+	constructor() {
+		super(undefined);
+	}
+	/**
+	 * @type {Ref<EL>}
+	 */
+	#createdRef = createRef();
+	/**
+	 * @returns {DirectiveResult<typeof RefDirective>}
+	 */
+	get ref() {
+		const directiveResultRef = ref(this.#createdRef);
+		directiveResultRef;
+		Timeout(0).then(() => {
+			/** macro task to let lit finish attaching `.value` to object  */
+			super.value = this.#createdRef.value;
+		});
+		return directiveResultRef;
+	}
+	onDisconnected = () => {
+		this.vivthCleanup();
+	};
+	/**
+	 * @override
+	 * @returns {EL|undefined}
+	 */
+	get value() {
+		return super.value;
+	}
+	/**
+	 * @returns {EL|undefined}
+	 * @override
+	 */
+	set value(_) {
+		Console.warn('you cannot manually set WC_litRef_signal_ref value');
+	}
+}

package/src/web/signals/WC_loopedSiblingsRef.mjs

@@ -0,0 +1,100 @@
+// @ts-check
+
+import { Console } from '../../class/Console.mjs';
+import { Signal } from '../../class/Signal.mjs';
+import { TrySync } from '../../function/TrySync.mjs';
+
+const loopedSiblingSymbol = Symbol('loopedSiblings');
+
+/**
+ * @description
+ * - `Signal` to check siblingIndex of a looped component;
+ * - automatically trigger check upon connectedCallback, by wrapping it with `this.ON` even without second argument;
+ * - automatically trigger cleanup upon disconnectedCallback, by wrapping it with `this.ON` even without second argument;
+ * - assumption is all sibling element must be from same class `WebCompoent`;
+ * ```html
+ * <div>
+ * 	<!-- looped <my-component></my-component> -->
+ * 	<!-- looped <my-component></my-component> -->
+ * 	<!-- looped <my-component></my-component> -->
+ * 	<my-component></my-component>
+ * 	<!-- looped <my-component></my-component> -->
+ * 	<!-- looped <my-component></my-component> -->
+ * </div>
+ * ```
+ * @extends {Signal<number|undefined>}
+ */
+export class WC_loopedSiblingsRef extends Signal {
+	/**
+	 * @param {HTMLElement} instanceRef
+	 */
+	constructor(instanceRef) {
+		super(undefined);
+		this.#instanceRef = instanceRef;
+	}
+	/**
+	 * @type {HTMLElement}
+	 */
+	#instanceRef;
+	/**
+	 * @type {number|undefined}
+	 */
+	#index;
+	/**
+	 * @description
+	 * - self auto register and cleanup when assigned with `ON` jut by passing empty object as second argument;
+	 * - the automatic part only works on `WC_extends${suffix}`;
+	 * >- the cleanup logic are infered by `WC_extends${suffix}` class inner behaviour;
+	 * - still need to be called manually if used outside `vivth/neutral` `WebComponent`;
+	 * @type {()=>void}
+	 */
+	onConnected = () => {
+		const [res, errorSettingUpLoopedSublingIndex] = TrySync(() => {
+			const instanceRef = this.#instanceRef;
+			if (this.#index === undefined) {
+				if (!instanceRef.isConnected) {
+					return undefined;
+				}
+				if (!instanceRef.previousElementSibling) {
+					this.#index = 0;
+				} else {
+					// @ts-expect-error
+					this.#index = instanceRef.previousElementSibling[loopedSiblingSymbol] + 1;
+				}
+				// @ts-expect-error
+				instanceRef[loopedSiblingSymbol] = this.#index;
+			}
+			return this.#index;
+		});
+		if (errorSettingUpLoopedSublingIndex) {
+			Console.error({ errorSettingUpLoopedSublingIndex });
+			return;
+		}
+		super.value = res;
+	};
+	/**
+	 * @description
+	 * - self auto register and cleanup when assigned with `ON` jut by passing empty object as second argument;
+	 * - the automatic part only works on `WC_extends${suffix}`;
+	 * >- the cleanup logic are infered by `WC_extends${suffix}` class inner behaviour;
+	 * - still need to be called manually if used outside `vivth/neutral` `WebComponent`;
+	 * @type {()=>void}
+	 */
+	onDisconnected = () => {
+		this.vivthCleanup();
+	};
+	/**
+	 * @type {number|undefined}
+	 * @override
+	 */
+	get value() {
+		return super.value;
+	}
+	/**
+	 * @type {number|undefined}
+	 * @override
+	 */
+	set value(_) {
+		Console.warn('you cannot manually set WC_loopedSiblings_ref value');
+	}
+}

package/tsconfig.json

@@ -1,41 +1,44 @@
-{
-	"compilerOptions": {
-		"checkJs": true,
-		"declaration": true,
-		"emitDeclarationOnly": true,
-		"outDir": "./types",
-		"esModuleInterop": true,
-		"removeComments": false,
-
-		// Environment setup & latest features
-		"lib": ["ESNext"],
-		"target": "ESNext",
-		"module": "Preserve",
-		"moduleDetection": "force",
-		"allowJs": true,
-
-		// Bundler mode
-		"moduleResolution": "bundler",
-		"allowImportingTsExtensions": true,
-		"verbatimModuleSyntax": true,
-		"noEmit": false,
-
-		// Best practices
-		"strict": true,
-		"skipLibCheck": true,
-		"noFallthroughCasesInSwitch": true,
-		"noUncheckedIndexedAccess": true,
-		"noImplicitOverride": true,
-
-		// Some stricter flags (disabled by default)
-		"noUnusedLocals": true,
-		"noUnusedParameters": false,
-		"noPropertyAccessFromIndexSignature": false
-	},
-	"include": [
-		//
-		"./index.mjs",
-		// "./dev",
-		"./src"
-	]
-}
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "./generated/types",
+    "esModuleInterop": true,
+    "removeComments": false,
+    "lib": [
+      "ESNext"
+    ],
+    "types": [
+      "node"
+    ],
+    "target": "esnext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": false,
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowUnreachableCode": false,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noPropertyAccessFromIndexSignature": false
+  },
+  "skipDefaultLibCheck": true,
+  "include": [
+    "./generated/vivth/exports",
+    "./src"
+  ],
+  "exclude": [
+    "./node_modules/**/*",
+    "**/*.js",
+    "**/*.as.ts",
+    "**/*.wasm"
+  ]
+}

package/index.mjs

@@ -1,91 +0,0 @@
-// @ts-check
-
-/**
- * automatically generated by `vivth.JSautoDOC`
- * @copyright
- * this library is made and distributed under MIT license;
- */
-
-export { ToBundledJSPlugin } from './src/bundler/adds/ToBundledJSPlugin.mjs';
-export { CompileJS } from './src/bundler/CompileJS.mjs';
-export { CreateESPlugin } from './src/bundler/CreateESPlugin.mjs';
-export { EsBundler } from './src/bundler/EsBundler.mjs';
-export { FSInline } from './src/bundler/FSInline.mjs';
-export { FSInlineAnalyzer } from './src/bundler/FSInlineAnalyzer.mjs';
-export { Console } from './src/class/Console.mjs';
-export { Derived } from './src/class/Derived.mjs';
-export { Effect } from './src/class/Effect.mjs';
-export { EnvSignal } from './src/class/EnvSignal.mjs';
-export { EventSignal } from './src/class/EventSignal.mjs';
-export { FileSafe } from './src/class/FileSafe.mjs';
-export { ListDerived } from './src/class/ListDerived.mjs';
-export { ListSignal } from './src/class/ListSignal.mjs';
-export { LitExp } from './src/class/LitExp.mjs';
-export { Paths } from './src/class/Paths.mjs';
-export { QChannel } from './src/class/QChannel.mjs';
-export { SafeExit } from './src/class/SafeExit.mjs';
-export { Setup } from './src/class/Setup.mjs';
-export { Signal } from './src/class/Signal.mjs';
-export { WalkThrough } from './src/class/WalkThrough.mjs';
-export { WorkerMainThread } from './src/class/WorkerMainThread.mjs';
-export { WorkerResult } from './src/class/WorkerResult.mjs';
-export { WorkerThread } from './src/class/WorkerThread.mjs';
-export { Base64URL } from './src/common/Base64URL.mjs';
-export { Base64URLFromFile } from './src/common/Base64URLFromFile.mjs';
-export { CreateStringID } from './src/common/CreateStringID.mjs';
-export { Dev } from './src/common/Dev.mjs';
-export { EventNameSpace } from './src/common/EventNameSpace.mjs';
-export { Trace } from './src/common/Trace.mjs';
-export { TracePath } from './src/common/TracePath.mjs';
-export { JSautoDOC } from './src/doc/JSautoDOC.mjs';
-export { CreateImmutable } from './src/function/CreateImmutable.mjs';
-export { EventCheck } from './src/function/EventCheck.mjs';
-export { EventObject } from './src/function/EventObject.mjs';
-export { GetNamedImportAlias } from './src/function/GetNamedImportAlias.mjs';
-export { GetRuntime } from './src/function/GetRuntime.mjs';
-export { IsAsync } from './src/function/IsAsync.mjs';
-export { LazyFactory } from './src/function/LazyFactory.mjs';
-export { TemplateLiteral } from './src/function/TemplateLiteral.mjs';
-export { Timeout } from './src/function/Timeout.mjs';
-export { Tries } from './src/function/Tries.mjs';
-export { TryAsync } from './src/function/TryAsync.mjs';
-export { TryNew } from './src/function/TryNew.mjs';
-export { TrySync } from './src/function/TrySync.mjs';
-export { TsToMjs } from './src/function/TsToMjs.mjs';
-/**
- * @typedef {import('./src/types/AnyButUndefined.mjs').AnyButUndefined} AnyButUndefined
- */
-/**
- * @typedef {import('./src/types/DevTestCB.mjs').DevTestCB} DevTestCB
- */
-/**
- * @typedef {import('./src/types/ExtnameType.mjs').ExtnameType} ExtnameType
- */
-/**
- * @typedef {import('./src/types/IsListSignal.mjs').IsListSignal} IsListSignal
- */
-/**
- * @typedef {import('./src/types/ListArg.mjs').ListArg} ListArg
- */
-/**
- * @typedef {import('./src/types/LitExpKeyType.mjs').LitExpKeyType} LitExpKeyType
- */
-/**
- * @template {import('./src/types/LitExpKeyType.mjs').LitExpKeyType} KEYS
- * @typedef {import('./src/types/LitExpResultType.mjs').LitExpResultType<KEYS>} LitExpResultType
- */
-/**
- * @typedef {import('./src/types/MutationType.mjs').MutationType} MutationType
- */
-/**
- * @typedef {import('./src/types/QCBFIFOReturn.mjs').QCBFIFOReturn} QCBFIFOReturn
- */
-/**
- * @typedef {import('./src/types/QCBReturn.mjs').QCBReturn} QCBReturn
- */
-/**
- * @typedef {import('./src/types/Runtime.mjs').Runtime} Runtime
- */
-/**
- * @typedef {import('./src/types/VivthDevCodeBlockStringType.mjs').VivthDevCodeBlockStringType} VivthDevCodeBlockStringType
- */

package/src/bundler/FSInline.mjs

@@ -1,67 +0,0 @@
-// @ts-check
-
-import { join } from 'node:path';
-import { readFile } from 'node:fs/promises';
-
-import { Paths } from '../class/Paths.mjs';
-
-/**
- * @description
- * - class helper to inline files;
- * >- as `type: "buffer"`;
- * - use only if you are planning to use [CompileJS](#compilejs);
- * >- the class static methods don't obfuscate target file;
- * >- don't embed any sensitive content using this methods of this class;
- */
-export class FSInline {
-	/**
-	 * @description
-	 * - declare entrypoint of file inlining;
-	 * >- on the dev time, it's just regullar `readFile` from `node:fs/promises`;
-	 * >- on the compiled, it will read file from `FSInline.vivthFSInlinelists`
-	 * @param {string} filePathFromProject
-	 * - doesn't require prefix;
-	 * @returns {Promise<Buffer<ArrayBuffer>>}
-	 * - dev: returns `ArrayBuffer`;
-	 * - bundled: embed the `ArrayBuffer` of file, which then returned;
-	 * >- `Dev` will be cleaned up;
-	 * @example
-	 * import { FSInline } from 'vivth';
-	 *
-	 * (await FSInline.vivthFSInlineFile('/assets/text.txt')).toString('utf-8');
-	 */
-	static vivthFSInlineFile = async (filePathFromProject) => {
-		filePathFromProject = Paths.normalizesForRoot(filePathFromProject);
-		if (Paths.root === undefined) {
-			return Buffer.from([]);
-		}
-		const fullAbsolutePath = join(Paths.root, filePathFromProject);
-		return Buffer.from(await readFile(fullAbsolutePath));
-	};
-	/**
-	 * @description
-	 * - declare entrypoint of file inlining, include all files on `dir` and `subdir` that match the `fileRule`;
-	 * - consider this as inline assets embed/bundler;
-	 * @param {string} dirPathFromProject
-	 * - doesn't require prefix;
-	 * @param {RegExp} fileRule
-	 * @returns {Promise<typeof FSInline["vivthFSInlineFile"]>}
-	 * @example
-	 * import { FSInline } from 'vivth';
-	 *
-	 * export const pngAssets = await FSInline.vivthFSInlineDir('/assets', /.png$/g);
-	 */
-	static vivthFSInlineDir = async (dirPathFromProject, fileRule) => {
-		dirPathFromProject = Paths.normalizesForRoot(dirPathFromProject);
-		return (path_) => FSInline.vivthFSInlineFile(join(dirPathFromProject, path_));
-	};
-	/**
-	 * @description
-	 * - placeholder for FSInline;
-	 * - it's remain publicly accessible so it doesn't mess with regex analyze on bundle;
-	 * - shouldn't be manually accessed;
-	 * >- access via `FSInline.vivthFSInlineFile` or `FSInline.vivthFSInlineDir`;
-	 * @type {Record<string, Buffer<ArrayBuffer>>}
-	 */
-	static vivthFSInlinelists = {};
-}