vivth 1.4.10 → 1.5.0

package/src/web/bindings/WC_StyleProp_bind.mjs

@@ -0,0 +1,70 @@
+// @ts-check
+
+/**
+ * @description
+ * - type helper to create ref custom style `property`;
+ */
+export class WC_StyleProp_bind {
+	/**
+	 * @description
+	 * @param {HTMLElement} element
+	 * @param {string} name
+	 * - automatically prefixed with `--`;
+	 * @param {Object} options
+	 * @param {boolean} options.isGlobal
+	 * - `false`: target scoped `property` on that component, and that component instance alone;
+	 * >- will not even bleed to other instance with same constructor;
+	 * - `true`: target style variable defined in global scope(loaded on document `styles` | `link[rel="stylesheet"]`);
+	 * @example
+	 * @example
+	 * // webcomponent context via `WC_extends`
+	 * #myStyle = new WC_StyleProp_bind(this, 'my-theme', {isGlobal:false});
+	 * //
+	 */
+	constructor(element, name, { isGlobal }) {
+		if (!name.startsWith('--')) {
+			name = `--${name}`;
+		}
+		this.name = name;
+		if (isGlobal) {
+			this.#style = document.documentElement.style;
+		} else {
+			this.#style = element.style;
+		}
+	}
+	/**
+	 * @type {string}
+	 */
+	name;
+	/**
+	 * @type {CSSStyleDeclaration}
+	 */
+	#style;
+	/**
+	 * @param  {import('../../typehints/ParametersFollowingN.mts').ParametersFollowingN<CSSStyleDeclaration["setProperty"], 1>} args
+	 */
+	set = (...args) => {
+		if (!this.name) {
+			return;
+		}
+		this.#style.setProperty(this.name, ...args);
+	};
+	/**
+	 * @returns {string|void}
+	 */
+	get value() {
+		if (!this.name) {
+			return;
+		}
+		return this.#style.getPropertyValue(this.name);
+	}
+	/**
+	 * @returns {string|void}
+	 */
+	get priority() {
+		if (!this.name) {
+			return;
+		}
+		return this.#style.getPropertyPriority(this.name);
+	}
+}

package/src/web/bindings/WC_createElement_bind.mjs

@@ -0,0 +1,95 @@
+// @ts-check
+
+import { render } from 'lit-html';
+
+import { ForInSync } from '../../function/ForInSync.mjs';
+import { ForOfSync } from '../../function/ForOfSync.mjs';
+
+/**
+ * @import {ArrayToKeys} from '../../typehints/ArrayToKeys.mjs'
+ * @import {TemplateResult, RenderOptions} from 'lit-html'
+ */
+/**
+ * @typedef {typeof import('../../function/IsTypeOf.mjs').TypeMap} TypeMap
+ */
+/**
+ * @param {readonly string[]} namedSlots
+ * @param {Record<string, string>|undefined} childrenDataArgsPlaceholder
+ * @returns {any}
+ */
+const getChildrenData = (namedSlots, childrenDataArgsPlaceholder) => {
+	if (!childrenDataArgsPlaceholder) {
+		childrenDataArgsPlaceholder = {};
+		ForOfSync(namedSlots, (name) => {
+			// @ts-expect-error
+			childrenDataArgsPlaceholder[name] = name;
+		});
+	}
+	return childrenDataArgsPlaceholder;
+};
+/**
+ * @description
+ * - typesafe factory generator for creating element of `WC_extendsA`/`WC_extendsB` class;
+ * - this function is returned by static method `.define`;
+ * >- bind it with static property;
+ * - uses `lit-html` under the hood;
+ * @template {(new (...args: any[]) => HTMLElement) & {
+ *  tagName: string;
+ * 	extendIs: string;
+ *  observedAttributes?: readonly string[];
+ *  namedSlots?: readonly string[];
+ * 	props?: Record<string, keyof TypeMap|(new (...args:any[])=>any)>;
+ * }} BASE_CONSTRUCTOR
+ * @param {BASE_CONSTRUCTOR} arg0
+ * @returns {(
+ * 	param?:{
+ * 		attrs?:BASE_CONSTRUCTOR['observedAttributes'] extends readonly string[]
+ * 			? Partial<
+ * 					Record<ArrayToKeys<BASE_CONSTRUCTOR['observedAttributes']>, string>
+ * 				>
+ * 			: undefined;
+ * 		props?: {[K in keyof NonNullable<BASE_CONSTRUCTOR["props"]>]:
+ * 			NonNullable<BASE_CONSTRUCTOR["props"]>[K] extends keyof TypeMap
+ * 				? TypeMap[NonNullable<BASE_CONSTRUCTOR["props"]>[K]]
+ * 				: InstanceType<NonNullable<BASE_CONSTRUCTOR["props"]>[K]>
+ * 		};
+ * 		children?:(slotName:Record<ArrayToKeys<BASE_CONSTRUCTOR['namedSlots']>, string>)=>TemplateResult;
+ * 		renderOptions?:RenderOptions;
+ * 	},
+ * )=>InstanceType<BASE_CONSTRUCTOR>}
+ * @example
+ * // webcomponent context via `WC_extends`
+ * static createElement = this.define(...args);
+ * //
+ */
+export function WC_createElement_bind({ tagName, extendIs, namedSlots = [] }) {
+	/**
+	 * @type {Record<string, string>|undefined}
+	 */
+	let childrenDataArgsPlaceholder;
+	return ({ attrs, children, renderOptions, props } = {}) => {
+		/**
+		 * @type {InstanceType<BASE_CONSTRUCTOR>}
+		 */
+		let element;
+		if (!extendIs) {
+			// @ts-expect-error
+			element = document.createElement(tagName);
+		} else {
+			// @ts-expect-error
+			element = document.createElement(tagName, {
+				is: extendIs,
+			});
+		}
+		if (attrs) {
+			ForInSync(attrs, (key, value) => {
+				element.setAttribute(key.toString(), value ?? '');
+			});
+		}
+		if (children) {
+			const trueChildrenData = children(getChildrenData(namedSlots, childrenDataArgsPlaceholder));
+			render(trueChildrenData, element, renderOptions);
+		}
+		return Object.assign(element, { props });
+	};
+}

package/src/web/bindings/WC_createNamedSlot.mjs

@@ -0,0 +1,29 @@
+// @ts-check
+
+import { html } from 'lit-html/static.js';
+
+/**
+ * @import {TemplateResult} from 'lit-html'
+ * @import {ArrayToKeys} from '../../typehints/ArrayToKeys.mts'
+ */
+
+/**
+ * @description
+ * - typesafe factory generator for creating slot element of `WC_extendsA`/`WC_extendsB` class;
+ * @template {{
+ * 	namedSlots?: readonly string[]
+ * }} NAMEDSLOTS
+ * @param {ArrayToKeys<NAMEDSLOTS["namedSlots"] extends readonly string[]
+ * 	? NAMEDSLOTS["namedSlots"]
+ * 	: never
+ * >} name
+ * @param {TemplateResult} [defaultNode]
+ * @returns {TemplateResult}
+ * @example
+ * // webcomponent context via `WC_extends`.callback props
+ * this.createNamedSlot(...args);
+ * //
+ */
+export function WC_createNamedSlot(name, defaultNode = html``) {
+	return html`<slot name="${name}">${defaultNode}</slot>`;
+}

package/src/web/bindings/WC_litRender_bind.mjs

@@ -0,0 +1,26 @@
+// @ts-check
+
+import { render } from 'lit-html';
+
+/**
+ * @description
+ * - factory to create simplified render function by omiting args[1++];
+ * @param {import('../../typehints/ParametersFollowingN.mts').ParametersFollowingN<typeof render, 1>} args
+ * @returns {(template: import('lit-html').TemplateResult)=>import('lit-html').RootPart}
+ * @example
+ * // webcomponent context via `WC_extends`
+ * constructor(){
+ * 	super();
+ * 	this.#root = this.attachShadow({ mode: 'closed' });
+ * 	this.#render = WC_litRender_bind(this.#root, this);
+ * }
+ * #root;
+ * #render;
+ * #something(){
+ * 	this.#render(html`<div></div>`); // <- args[1++] are omitted
+ * }
+ * ///
+ */
+export function WC_litRender_bind(...args) {
+	return (template) => render(template, ...args);
+}

package/src/web/bindings/WC_litStyleMap.mjs

@@ -0,0 +1,14 @@
+// @ts-check
+
+import { styleMap } from 'lit-html/directives/style-map.js';
+
+/**
+ * @description
+ * - type helper for `import { styleMap } from 'lit-html/directives/style-map.js';`, by typehinting the properties;
+ * @param {Partial<CSSStyleProperties>} properties
+ * @returns {import('lit-html/directive.js').DirectiveResult}
+ */
+export function WC_litStyleMap(properties) {
+	// @ts-expect-error
+	return styleMap(properties);
+}

package/src/web/common/CSS.mjs

@@ -0,0 +1,35 @@
+// @ts-check
+
+import { TemplateLiteral } from '../../function/TemplateLiteral.mjs';
+import { NewStyleSheetSync } from './NewStyleSheetSync.mjs';
+
+/**
+ * @description
+ * - generate `CSSStyleSheet` with template literal;
+ * @param {TemplateStringsArray} strings
+ * @param {...string} values
+ * @returns {CSSStyleSheet}
+ * @example
+ * import { CSS as css } from 'vivth/neutral';
+ * // webcomponent context via `WC_extends`
+ * static CSS = css`
+ * 	:host{
+ * 		--my-theme: salmon;
+ * 		background-color: var(--my-theme);
+ * 	}
+ * `
+ * constructor(){
+ * 	super();
+ * 	const root = this.attachShadow({mode:'closed'});
+ * 	root.adoptedStyleSheets= [MyClass.CSS];
+ * }
+ * //
+ */
+export function CSS(strings, ...values) {
+	/**
+	 * @type {ReturnType<typeof TemplateLiteral<string, string>>}
+	 */
+	const handler = TemplateLiteral(({ currentValue }) => currentValue);
+	const string = handler(strings, ...values);
+	return NewStyleSheetSync(string);
+}

package/src/web/common/E.mjs

@@ -0,0 +1,126 @@
+// @ts-check
+
+import { Effect } from '../../class/Effect.mjs';
+import { Signal } from '../../class/Signal.mjs';
+import { WalkThrough } from '../../class/WalkThrough.mjs';
+import { ForInSync } from '../../function/ForInSync.mjs';
+import { IsTypeOf } from '../../function/IsTypeOf.mts';
+
+/**
+ * @param {Element} element
+ * @param {ChildNode[]} childNodes
+ * @returns {void}
+ */
+const modifyChild = (element, childNodes) => {
+	const len = Math.max(element.childNodes.length, childNodes.length);
+	/**
+	 * @type {ChildNode[]}
+	 */
+	const shouldBeRemoved = [];
+	for (let i = 0; i < len; i++) {
+		const currentChildNode = element.childNodes[i];
+		const shouldBeChildNode = childNodes[i];
+		if (currentChildNode) {
+			if (shouldBeChildNode) {
+				if (currentChildNode !== shouldBeChildNode) {
+					currentChildNode.replaceWith(shouldBeChildNode);
+				}
+			} else {
+				shouldBeRemoved.push(currentChildNode);
+			}
+		} else {
+			if (shouldBeChildNode) {
+				element.append(shouldBeChildNode);
+			} else {
+				break;
+			}
+		}
+	}
+	for (let i = 0; i < shouldBeRemoved.length; i++) {
+		shouldBeRemoved[i]?.remove();
+	}
+};
+
+/**
+ * @description
+ * - helper function to create element;
+ * @template {keyof HTMLElementTagNameMap} K
+ * @template {Partial<HTMLElementTagNameMap[K]> & Record<string, any>} RR
+ * @param {K} tagName
+ * @param {(
+ *   & Omit<Record<string, string|Signal<string>>, 'style'|'class'>
+ *   & { style?: string, class?: string }
+ * )} [attrs]
+ * @param {RR} [props]
+ * @param {ChildNode[]|Signal<ChildNode[]>} [childNodes]
+ * @returns {HTMLElementTagNameMap[K]
+ * 	& RR
+ * 	& {
+ * 		onDisconnected:()=>void;
+ * 		}
+ * }
+ * @example
+ * const text = new Text('hello');
+ * const div = E('div',{
+ * 		class: 'p-1 m-1',
+ * 		id: 'my-div',
+ * 	},
+ * 	{
+ * 		onclick(e){
+ * 			console.log(e);
+ * 		},
+ * 	},
+ * 	[text],
+ * )
+ * // fine grain modify
+ * text.nodeValue = 'hello world';
+ */
+export function E(
+	tagName,
+	attrs = {},
+	// @ts-expect-error
+	props = {},
+	childNodes = [],
+) {
+	const element = document.createElement(tagName);
+	/**
+	 * @type {Set<()=>any>}
+	 */
+	const setOFDisconnected = new Set();
+	ForInSync(attrs, (key, value) => {
+		if (IsTypeOf(value, 'string')) {
+			element.setAttribute(key, value);
+		} else {
+			const effect = new Effect(async ({ subscribe }) => {
+				element.setAttribute(key, subscribe(value).value);
+			});
+			value.subscribers.setOf.add(effect);
+			setOFDisconnected.add(() => {
+				value.vivthCleanup();
+				effect.vivthCleanup();
+			});
+		}
+	});
+	ForInSync(props, (key, value) => {
+		// @ts-expect-error
+		element[key] = value;
+	});
+	if (Array.isArray(childNodes)) {
+		element.append(...childNodes);
+	} else {
+		const effect = new Effect(async ({ subscribe }) => {
+			modifyChild(element, subscribe(childNodes).value);
+		});
+		childNodes.subscribers.setOf.add(effect);
+		setOFDisconnected.add(effect.vivthCleanup);
+	}
+	return Object.assign(element, {
+		...props,
+		onDisconnected: () => {
+			WalkThrough.set(setOFDisconnected, (cb) => {
+				cb();
+			});
+			element.remove();
+		},
+	});
+}

package/src/web/common/NewStyleSheetAsync.mjs

@@ -0,0 +1,21 @@
+// @ts-check
+
+/**
+ * @description
+ * - function helper to asynchronously `CSSStyleSheet`;
+ * >- './main.css';
+ * ```css
+ * :host{
+ * 	background-color: red;
+ * }
+ * ```
+ * - internally used for `Dynamics`;
+ * @param {string} string
+ * @param {ConstructorParameters<typeof CSSStyleSheet>} arg1
+ * @returns {Promise<CSSStyleSheet>}
+ */
+export async function NewStyleSheetAsync(string, ...arg1) {
+	const sheet = new CSSStyleSheet(...arg1);
+	await sheet.replace(string);
+	return sheet;
+}

package/src/web/common/NewStyleSheetSync.mjs

@@ -0,0 +1,21 @@
+// @ts-check
+
+/**
+ * @description
+ * - function helper to synchronously `CSSStyleSheet`;
+ * >- './main.css';
+ * ```css
+ * :host{
+ * 	background-color: red;
+ * }
+ * ```
+ * - internally used for `CSS`;
+ * @param {string} string
+ * @param {ConstructorParameters<typeof CSSStyleSheet>} arg1
+ * @returns {CSSStyleSheet}
+ */
+export function NewStyleSheetSync(string, ...arg1) {
+	const sheet = new CSSStyleSheet(...arg1);
+	sheet.replaceSync(string);
+	return sheet;
+}

package/src/web/common/WC_TagName_type.mjs

@@ -0,0 +1,10 @@
+/**
+ * @preserve
+ * @description
+ * Validates whether a string follows the strict custom-element layout:
+ * - Must contain a hyphen (-)
+ * - No spaces allowed anywhere
+ * - Must be strictly lowercase
+ * @template {string} TAG
+ * @typedef {import('./WC_TagName_type.mts').WC_TagName_type<TAG>} WC_TagName_type
+ */

package/src/web/common/WC_TagName_type.mts

@@ -0,0 +1,36 @@
+// types.mts
+
+/**
+ * Checks if a string segment contains invalid characters (Spaces, Uppercase, or Symbols)
+ */
+export type IsValidSegment<S extends string> = S extends `${infer Char}${infer Rest}`
+	? Char extends ' ' | '_' | '/' | '\\' | '.' | ',' | '?' | '!' // Block spaces and common separators
+		? false
+		: Char extends Uppercase<Char> // Enforce strict lowercase (Blocks A-Z and symbols that don't have case)
+			? Char extends Lowercase<Char>
+				? true // It's a number or valid special character allowed by the browser
+				: false // It's an uppercase letter! Block it.
+			: IsValidSegment<Rest> // Continue checking character by character
+	: true;
+
+/**
+ * @preserve
+ * @description
+ * Validates whether a string follows the strict custom-element layout:
+ * - Must contain a hyphen (-)
+ * - No spaces allowed anywhere
+ * - Must be strictly lowercase
+ * @template {string} TAG
+ * @[blank]typedef {import('./WC_TagName_type.mts').WC_TagName_type<TAG>} WC_TagName_type
+ */
+export type WC_TagName_type<T extends string> = T extends `${infer Prefix}-${infer Suffix}`
+	? Prefix extends ''
+		? 'ERROR: Custom element tag names cannot start with a hyphen.'
+		: Suffix extends ''
+			? 'ERROR: Custom element tag names cannot end with a hyphen.'
+			: IsValidSegment<Prefix> extends false
+				? 'ERROR: Tag contains spaces, uppercase letters, or invalid characters in the prefix.'
+				: IsValidSegment<Suffix> extends false
+					? 'ERROR: Tag contains spaces, uppercase letters, or invalid characters in the suffix.'
+					: T // ✅ 100% Valid Custom Element tag structure!
+	: 'ERROR: Web Component tag names MUST contain a hyphen (-) character.';

package/src/web/signals/IsInViewPortSignal.mjs

@@ -0,0 +1,140 @@
+// @ts-check
+
+import { Console } from '../../class/Console.mjs';
+import { QChannel } from '../../class/QChannel.mjs';
+import { Signal } from '../../class/Signal.mjs';
+import { IsInstanceOf } from '../../function/IsInstanceOf.mjs';
+import { LazyFactory } from '../../function/LazyFactory.mjs';
+
+/**
+ * @typedef {import('../../typehints/VivthCleanup.mjs').VivthCleanup} VivthCleanup
+ */
+
+/**
+ * @description
+ * - signal helper to check whether element is in viewport;
+ * @implements {VivthCleanup}
+ * @extends {Signal<boolean>}
+ */
+export class IsInViewPortSignal extends Signal {
+	/**
+	 * @description
+	 * @override
+	 * - cleanup callback;
+	 */
+	vivthCleanup = async () => {
+		IsInViewPortSignal.#intersectionObserver.unobserve(this.#element);
+		this.remove.ref();
+		IsInViewPortSignal.#mapped.delete(this.#element);
+	};
+	/**
+	 * @description
+	 * @param {Element} element
+	 */
+	constructor(element) {
+		super(IsInViewPortSignal.#isInViewport(element));
+		IsInViewPortSignal.#mapped.set(element, this);
+		this.#element = element;
+		IsInViewPortSignal.#intersectionObserver.observe(element);
+	}
+	/**
+	 * @type {Element}
+	 */
+	#element;
+	/**
+	 * @type {WeakMap<Element, Signal<boolean>>}
+	 */
+	static #mapped = new WeakMap();
+	/**
+	 * @type {IntersectionObserver|undefined}
+	 */
+	static #intersectionObserver_;
+	static #q = LazyFactory(() => new QChannel('IsInViewPort'));
+	static get #intersectionObserver() {
+		if (!IsInViewPortSignal.#intersectionObserver_) {
+			IsInViewPortSignal.#intersectionObserver_ = new IntersectionObserver(
+				IsInViewPortSignal.#intersectionObserverCallback,
+				IsInViewPortSignal.#intersectionObserverInit,
+			);
+		}
+		return IsInViewPortSignal.#intersectionObserver_;
+	}
+	/**
+	 * @type {IntersectionObserverInit}
+	 */
+	static #intersectionObserverInit = {
+		root: null,
+		rootMargin: '0px',
+		threshold: 0,
+	};
+	/**
+	 * @type {IntersectionObserverCallback}
+	 */
+	static #intersectionObserverCallback = (entries) => {
+		for (let i = 0; i < entries.length; i++) {
+			const entry = entries[i];
+			if (!entry) {
+				continue;
+			}
+			const target = entry.target;
+			if (!IsInstanceOf(target, Element)) {
+				continue;
+			}
+			IsInViewPortSignal.#q.callback(target, async ({ isLastOnQ }) => {
+				await IsInViewPortSignal.#qCB(isLastOnQ, target, entry);
+			});
+		}
+	};
+	/**
+	 * @param {()=>boolean} isLastOnQ
+	 * @param {Element} target
+	 * @param {IntersectionObserverEntry} entry
+	 * @returns {Promise<void>}
+	 */
+	static #qCB = async (isLastOnQ, target, entry) => {
+		if (!isLastOnQ()) {
+			return;
+		}
+		const signal = IsInViewPortSignal.#mapped.get(target);
+		if (!signal || !IsInstanceOf(signal, IsInViewPortSignal)) {
+			return;
+		}
+		signal.#setSuperValue(entry.isIntersecting);
+	};
+	/**
+	 * @param {Element} element
+	 * @returns {boolean}
+	 */
+	static #isInViewport(element) {
+		const rect = element.getBoundingClientRect();
+		return (
+			rect.top < window.innerHeight &&
+			rect.bottom > 0 &&
+			rect.left < window.innerWidth &&
+			rect.right > 0
+		);
+	}
+	/**
+	 *
+	 * @param {boolean} newValue
+	 */
+	#setSuperValue(newValue) {
+		super.value = newValue;
+	}
+	/**
+	 * @description
+	 * - `Signal.value` reference to check if element is in viewport;
+	 * @returns {boolean}
+	 * @override
+	 */
+	get value() {
+		return super.value;
+	}
+	/**
+	 * @returns {boolean}
+	 * @override
+	 */
+	set value(_) {
+		Console.error('you cannot manually set value of IsInViewPortSignal');
+	}
+}