vivth 1.4.10 → 1.5.0

package/generated/types/src/web/WC_extendsB.d.mts

@@ -0,0 +1,135 @@
+/**
+ * @import {ArrayToKeys} from '../typehints/ArrayToKeys.mjs'
+ * @import {WC_TagName_type} from './common/WC_TagName_type.mjs'
+ */
+/**
+ * @typedef {typeof import('../function/IsTypeOf.mjs').TypeMap} TypeMap
+ */
+/**
+ * @description
+ * - Generates a base class for Web Component definitions.
+ * - Note: This generator does not support `connectedMoveCallback`.
+ * For the needs of opting in to [connectedMoveCallback](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements) functionality, use [WC_extendsB](#wc_extendsb) instead.
+ * - This class relies heavily on complex type inference which can cause issues, during declaration file generation. To avoid "circular type" errors or build failures, set the following in your `tsconfig.json`:
+ * ```json
+ * {
+ * 	"compilerOptions": {
+ * 		"declaration": false
+ * 	}
+ * }
+ * ```
+ * - By disabling `declaration`, you prevent the TypeScript compiler from attempting to resolve and export the complex recursive type definitions generated by this factory;
+ * @template {new (...args: any[]) => HTMLElement} BASE_CONSTRUCTOR
+ * @template {{
+ * 	class?:string;
+ * 	style?:string;
+ *  observedAttributes?: readonly string[];
+ *  namedSlots?: readonly string[];
+ * 	props?: Record<string, keyof TypeMap|(new (...args:any[])=>any)>;
+ * }} STANDARD
+ * @template {(BASE_CONSTRUCTOR) & {
+ * 	tagName: string;
+ * 	extendIs: string;
+ * 	observedAttributes?: STANDARD["observedAttributes"];
+ * 	namedSlots?: STANDARD["namedSlots"];
+ * 	props?: STANDARD["props"];
+ * }} CREATEARGS
+ * @template { (new (...args: any[]) => InstanceType<BASE_CONSTRUCTOR> & {
+ * 		setObservedAttributes(attributes:Partial<
+ * 			Record<ArrayToKeys<STANDARD["observedAttributes"]extends readonly string[]
+ * 				? STANDARD["observedAttributes"]
+ * 				:never>,
+ * 			string>
+ * 		>):void;
+ * 		props: NonNullable<NonNullable<Parameters<ReturnType<typeof WC_createElement_bind<CREATEARGS>>>[0]>["props"]>;
+ *    adoptedCallback():void;
+ *    connectedCallback():void;
+ *    disonnectedCallback():void;
+ * 		attributeChangedCallback(name:ArrayToKeys<STANDARD["observedAttributes"]extends readonly string[]?STANDARD["observedAttributes"]:never>, oldValue:string|null, newValue:string|null): void;
+ * 		ON:<OBJ extends Record<any, any> & {
+ * 				onConnected?: NonNullable<Parameters<InstanceType<RET>["ON"]>[1]>["connected"];
+ * 				onConnectedMove?: NonNullable<Parameters<InstanceType<RET>["ON"]>[1]>["connectedMove"];
+ * 				onDisconnected?: NonNullable<Parameters<InstanceType<RET>["ON"]>[1]>["disconnected"];
+ * 				onAdopted?: NonNullable<Parameters<InstanceType<RET>["ON"]>[1]>["adopted"];
+ * 				onAttributeChanged?: NonNullable<Parameters<InstanceType<RET>["ON"]>[1]>["attributeChanged"];
+ * 			}>
+ * 		(obj:OBJ, callbacks?:
+ * 			{
+ * 				connected?:(obj:OBJ)=>void;
+ * 				connectedMove?:(obj:OBJ)=>void;
+ * 				disconnected?:(obj:OBJ)=>void;
+ * 				adopted?:(obj:OBJ)=>void;
+ * 				attributeChanged?:(
+ * 					obj:OBJ,
+ * 					name:STANDARD["observedAttributes"]extends readonly string[]
+ * 						? ArrayToKeys<STANDARD["observedAttributes"]>
+ * 						: never,
+ * 					oldValue:string|null,
+ * 					newValue:string|null
+ * 				)=>void;
+ * 			})=>OBJ;
+ *  }) & {
+ * 		tagName:string;
+ * 		extendIs:string;
+ *  	namedSlots: STANDARD["namedSlots"];
+ *  	observedAttributes: STANDARD["observedAttributes"];
+ * 		createNamedSlot: typeof WC_createNamedSlot<STANDARD>;
+ * 		props?: STANDARD["props"];
+ * 		define:<TAG extends string, CLASSREF extends RET>
+ * 			(
+ * 				tagName:WC_TagName_type<TAG>,
+ * 				classRef:CLASSREF,
+ * 				elementDefinitionOptions?:ElementDefinitionOptions,
+ * 			)=>ReturnType<typeof WC_createElement_bind<CLASSREF>>;
+ * 	}
+ * } RET
+ * @param {BASE_CONSTRUCTOR} Base
+ * @param {STANDARD} [staticMember]
+ * @returns {RET}
+ */
+export function WC_extendsB<BASE_CONSTRUCTOR extends new (...args: any[]) => HTMLElement, STANDARD extends {
+    class?: string;
+    style?: string;
+    observedAttributes?: readonly string[];
+    namedSlots?: readonly string[];
+    props?: Record<string, keyof TypeMap | (new (...args: any[]) => any)>;
+}, CREATEARGS extends (BASE_CONSTRUCTOR) & {
+    tagName: string;
+    extendIs: string;
+    observedAttributes?: STANDARD["observedAttributes"];
+    namedSlots?: STANDARD["namedSlots"];
+    props?: STANDARD["props"];
+}, RET extends (new (...args: any[]) => InstanceType<BASE_CONSTRUCTOR> & {
+    setObservedAttributes(attributes: Partial<Record<ArrayToKeys<STANDARD["observedAttributes"] extends readonly string[] ? STANDARD["observedAttributes"] : never>, string>>): void;
+    props: NonNullable<NonNullable<Parameters<ReturnType<typeof WC_createElement_bind<CREATEARGS>>>[0]>["props"]>;
+    adoptedCallback(): void;
+    connectedCallback(): void;
+    disonnectedCallback(): void;
+    attributeChangedCallback(name: ArrayToKeys<STANDARD["observedAttributes"] extends readonly string[] ? STANDARD["observedAttributes"] : never>, oldValue: string | null, newValue: string | null): void;
+    ON: <OBJ extends Record<any, any> & {
+        onConnected?: NonNullable<Parameters<InstanceType<RET>["ON"]>[1]>["connected"];
+        onConnectedMove?: NonNullable<Parameters<InstanceType<RET>["ON"]>[1]>["connectedMove"];
+        onDisconnected?: NonNullable<Parameters<InstanceType<RET>["ON"]>[1]>["disconnected"];
+        onAdopted?: NonNullable<Parameters<InstanceType<RET>["ON"]>[1]>["adopted"];
+        onAttributeChanged?: NonNullable<Parameters<InstanceType<RET>["ON"]>[1]>["attributeChanged"];
+    }>(obj: OBJ, callbacks?: {
+        connected?: (obj: OBJ) => void;
+        connectedMove?: (obj: OBJ) => void;
+        disconnected?: (obj: OBJ) => void;
+        adopted?: (obj: OBJ) => void;
+        attributeChanged?: (obj: OBJ, name: STANDARD["observedAttributes"] extends readonly string[] ? ArrayToKeys<STANDARD["observedAttributes"]> : never, oldValue: string | null, newValue: string | null) => void;
+    }) => OBJ;
+}) & {
+    tagName: string;
+    extendIs: string;
+    namedSlots: STANDARD["namedSlots"];
+    observedAttributes: STANDARD["observedAttributes"];
+    createNamedSlot: typeof WC_createNamedSlot<STANDARD>;
+    props?: STANDARD["props"];
+    define: <TAG extends string, CLASSREF extends RET>(tagName: WC_TagName_type<TAG>, classRef: CLASSREF, elementDefinitionOptions?: ElementDefinitionOptions) => ReturnType<typeof WC_createElement_bind<CLASSREF>>;
+}>(Base: BASE_CONSTRUCTOR, staticMember?: STANDARD): RET;
+export type TypeMap = typeof import("../function/IsTypeOf.mjs").TypeMap;
+import type { ArrayToKeys } from '../typehints/ArrayToKeys.mjs';
+import { WC_createElement_bind } from './bindings/WC_createElement_bind.mjs';
+import { WC_createNamedSlot } from './bindings/WC_createNamedSlot.mjs';
+import type { WC_TagName_type } from './common/WC_TagName_type.mjs';

package/generated/types/src/web/bindings/WC_StyleProp_bind.d.mts

@@ -0,0 +1,42 @@
+/**
+ * @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: HTMLElement, name: string, { isGlobal }: {
+        isGlobal: boolean;
+    });
+    /**
+     * @type {string}
+     */
+    name: string;
+    /**
+     * @param  {import('../../typehints/ParametersFollowingN.mts').ParametersFollowingN<CSSStyleDeclaration["setProperty"], 1>} args
+     */
+    set: (...args: import("../../typehints/ParametersFollowingN.mts").ParametersFollowingN<CSSStyleDeclaration["setProperty"], 1>) => void;
+    /**
+     * @returns {string|void}
+     */
+    get value(): string | void;
+    /**
+     * @returns {string|void}
+     */
+    get priority(): string | void;
+    #private;
+}

package/generated/types/src/web/bindings/WC_createElement_bind.d.mts

@@ -0,0 +1,51 @@
+/**
+ * @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<BASE_CONSTRUCTOR extends (new (...args: any[]) => HTMLElement) & {
+    tagName: string;
+    extendIs: string;
+    observedAttributes?: readonly string[];
+    namedSlots?: readonly string[];
+    props?: Record<string, keyof TypeMap | (new (...args: any[]) => any)>;
+}>({ tagName, extendIs, namedSlots }: BASE_CONSTRUCTOR): (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>;
+export type TypeMap = typeof import("../../function/IsTypeOf.mjs").TypeMap;
+import type { ArrayToKeys } from '../../typehints/ArrayToKeys.mjs';
+import type { TemplateResult } from 'lit-html';
+import type { RenderOptions } from 'lit-html';

package/generated/types/src/web/bindings/WC_createNamedSlot.d.mts

@@ -0,0 +1,26 @@
+/**
+ * @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<NAMEDSLOTS extends {
+    namedSlots?: readonly string[];
+}>(name: ArrayToKeys<NAMEDSLOTS["namedSlots"] extends readonly string[] ? NAMEDSLOTS["namedSlots"] : never>, defaultNode?: TemplateResult): TemplateResult;
+import type { ArrayToKeys } from '../../typehints/ArrayToKeys.mts';
+import type { TemplateResult } from 'lit-html';

package/generated/types/src/web/bindings/WC_litRender_bind.d.mts

@@ -0,0 +1,20 @@
+/**
+ * @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(container: import("lit-html").RenderRootNode, options?: import("lit-html").RenderOptions | undefined): (template: import("lit-html").TemplateResult) => import("lit-html").RootPart;

package/generated/types/src/web/bindings/WC_litStyleMap.d.mts

@@ -0,0 +1,7 @@
+/**
+ * @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: Partial<CSSStyleProperties>): import("lit-html/directive.js").DirectiveResult;

package/generated/types/src/web/common/CSS.d.mts

@@ -0,0 +1,23 @@
+/**
+ * @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: TemplateStringsArray, ...values: string[]): CSSStyleSheet;

package/generated/types/src/web/common/E.d.mts

@@ -0,0 +1,41 @@
+/**
+ * @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<K extends keyof HTMLElementTagNameMap, RR extends Partial<HTMLElementTagNameMap[K]> & Record<string, any>>(tagName: K, attrs?: (Omit<Record<string, string | Signal<string>>, "style" | "class"> & {
+    style?: string;
+    class?: string;
+}), props?: RR, childNodes?: ChildNode[] | Signal<ChildNode[]>): HTMLElementTagNameMap[K] & RR & {
+    onDisconnected: () => void;
+};
+import { Signal } from '../../class/Signal.mjs';

package/generated/types/src/web/common/NewStyleSheetAsync.d.mts

@@ -0,0 +1,15 @@
+/**
+ * @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 function NewStyleSheetAsync(string: string, options?: CSSStyleSheetInit | undefined): Promise<CSSStyleSheet>;

package/generated/types/src/web/common/NewStyleSheetSync.d.mts

@@ -0,0 +1,15 @@
+/**
+ * @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: string, options?: CSSStyleSheetInit | undefined): CSSStyleSheet;

package/generated/types/src/web/common/WC_TagName_type.d.mts

@@ -0,0 +1,15 @@
+/**
+ * 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 ' ' | '_' | '/' | '\\' | '.' | ',' | '?' | '!' ? false : Char extends Uppercase<Char> ? Char extends Lowercase<Char> ? true : false : IsValidSegment<Rest> : 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 : 'ERROR: Web Component tag names MUST contain a hyphen (-) character.';

package/generated/types/src/web/signals/IsInViewPortSignal.d.mts

@@ -0,0 +1,52 @@
+/**
+ * @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<boolean> implements VivthCleanup {
+    /**
+     * @type {WeakMap<Element, Signal<boolean>>}
+     */
+    static #mapped: WeakMap<Element, Signal<boolean>>;
+    /**
+     * @type {IntersectionObserver|undefined}
+     */
+    static #intersectionObserver_: IntersectionObserver | undefined;
+    static #q: QChannel<import("../../typehints/AnyButUndefined.mjs").AnyButUndefined> & {
+        [x: symbol]: QChannel<import("../../typehints/AnyButUndefined.mjs").AnyButUndefined>;
+    };
+    static get #intersectionObserver(): IntersectionObserver;
+    /**
+     * @type {IntersectionObserverInit}
+     */
+    static #intersectionObserverInit: IntersectionObserverInit;
+    /**
+     * @type {IntersectionObserverCallback}
+     */
+    static #intersectionObserverCallback: IntersectionObserverCallback;
+    /**
+     * @param {()=>boolean} isLastOnQ
+     * @param {Element} target
+     * @param {IntersectionObserverEntry} entry
+     * @returns {Promise<void>}
+     */
+    static #qCB: (isLastOnQ: () => boolean, target: Element, entry: IntersectionObserverEntry) => Promise<void>;
+    /**
+     * @param {Element} element
+     * @returns {boolean}
+     */
+    static #isInViewport(element: Element): boolean;
+    /**
+     * @description
+     * @param {Element} element
+     */
+    constructor(element: Element);
+    #private;
+}
+export type VivthCleanup = import("../../typehints/VivthCleanup.mjs").VivthCleanup;
+import { Signal } from '../../class/Signal.mjs';
+import { QChannel } from '../../class/QChannel.mjs';

package/generated/types/src/web/signals/ObserverSignal.d.mts

@@ -0,0 +1,32 @@
+/**
+ * @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<MutationRecord[] | undefined> implements VivthCleanup {
+    /**
+     * @description
+     * @param {Node} node
+     * @param {ParametersFollowingN<
+     * 	MutationObserver["observe"],1
+     * >} mutationObserverInitArgs
+     * - no default value;
+     */
+    constructor(node: Node, options?: MutationObserverInit | undefined);
+    /**
+     * @description
+     * - unobserve element;
+     */
+    unobserve: () => void;
+    #private;
+}
+export type VivthCleanup = import("../../typehints/VivthCleanup.mjs").VivthCleanup;
+import { Signal } from '../../class/Signal.mjs';

package/generated/types/src/web/signals/WC_litRef.d.mts

@@ -0,0 +1,26 @@
+/**
+ * @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<EL extends Element> extends Signal<EL | undefined> {
+    /**
+     * @description
+     */
+    constructor();
+    /**
+     * @returns {DirectiveResult<typeof RefDirective>}
+     */
+    get ref(): DirectiveResult<typeof RefDirective>;
+    onDisconnected: () => void;
+    #private;
+}
+import { Signal } from '../../class/Signal.mjs';
+import type { RefDirective } from 'lit-html/directives/ref.js';
+import type { DirectiveResult } from 'lit-html/directive.js';

package/generated/types/src/web/signals/WC_loopedSiblingsRef.d.mts

@@ -0,0 +1,44 @@
+/**
+ * @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<number | undefined> {
+    /**
+     * @param {HTMLElement} instanceRef
+     */
+    constructor(instanceRef: HTMLElement);
+    /**
+     * @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: () => void;
+    /**
+     * @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: () => void;
+    #private;
+}
+import { Signal } from '../../class/Signal.mjs';