dothtml-interfaces 0.4.6 → 1.0.0

package/README.md

@@ -1,4 +1,4 @@
-
-# DOThtml Interfaces
-
+
+# DOThtml Interfaces
+
 DOThtml interfaces allows DOThtml to be used in projects requiring dependency injection!

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "dothtml-interfaces",
-  "version": "0.4.6",
+  "version": "1.0.0",
   "description": "Dependency injection interfaces for DOTHtml.",
-  "main": "src/index.d.ts",
-  "types": "src/index.d.ts",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
   "scripts": {},
   "author": "",
   "license": "ISC",
   "devDependencies": {
     "typescript": "^5.3.2"
   },
-  "exports": "./src/index.d.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
   "files": [
     "src/**/*"
   ]

package/src/bindings/{i-binding.d.ts → i-binding.ts}

@@ -1,12 +1,12 @@
-import { IWatcher } from "./i-watcher";
-
-export interface IBinding<T = any, Td = T>{
-	_source: IWatcher<T>;
-	_get: ()=>Td;
-	_set: (v: string|number|boolean)=>void;
-	
-	_transform: {
-		display?: (v: T)=>Td;
-		read?: (v: string)=>T;
-	}
+import { IWatcher } from "./i-watcher";
+
+export interface IBinding<T = any, Td = T>{
+	_source: IWatcher<T>;
+	_get: ()=>Td;
+	_set: (v: string|number|boolean)=>void;
+	
+	_transform: {
+		display?: (v: T)=>Td;
+		read?: (v: string)=>T;
+	}
 }

package/src/bindings/{i-observer.d.ts → i-observer.ts}

@@ -1,3 +1,3 @@
-export interface IObserver<T = any>{
-	observerUpdate(value: T, obsreverId: number): void;
+export interface IObserver<T = any>{
+	observerUpdate(value: T, obsreverId: number): void;
 }

package/src/bindings/{i-reactive.d.ts → i-reactive.ts}

@@ -1,4 +1,4 @@
-import { IBinding } from "./i-binding";
-import { IWatcher } from "./i-watcher";
-
-export type IReactive = IBinding|IWatcher;
+import { IBinding } from "./i-binding";
+import { IWatcher } from "./i-watcher";
+
+export type IReactive<T = any> = IBinding<any, T>|IWatcher<T>;

package/src/bindings/i-ref.ts

@@ -0,0 +1,5 @@
+import { IWatcher } from "./i-watcher";
+
+export interface IRef<T = any> extends IWatcher<T | null> {
+	get element(): T;
+}

package/src/bindings/{i-watcher.d.ts → i-watcher.ts}

@@ -1,38 +1,52 @@
-import { IBinding } from "./i-binding";
-
-export interface IWatcher<T = any>{
-	// Get the value.
-	get value(): T;
-	// Set the value.
-	set value(v: T|null|undefined);
-
-	// Key is used for observable array proxy bindings.
-	// If a key is provided, it's used to uniquely identify array elements.
-	// If a key is not provided, identification is done automatically by the framework by comparing object references.
-	key: string;
-	// subscribeNode(node: Node): number;
-	// subscribeAttr(node: HTMLElement, attributeName: string): number;
-	// subscribeCallback(callback: (value: T)=>void): number;
-	// detachBinding(id: number);
-
-	/** 
-	 * Subscribe to changes in the reactive object.
-	*/
-	subscribe(callback: Function): number;
-
-	_subscribe(boundReactive: IBinding, item: any);
-	_detachBinding(id: number);
-
-	/**
-	 * Called manually by the user to trigger an update.
-	 * Useful for arrays and objects.
-	 */
-	updateObservers(): void;
-
-	bindAs<Td = string>(transform: (((v: T)=>Td)|({
-		display?: (v: T)=>Td;
-		read?: (v: string)=>T;
-	}))): IBinding<T, Td>;
-
-	bind(): IBinding<T>;
-}
+import { IBinding } from "./i-binding";
+
+export interface IWatcher<T = any>{
+	/**
+	 * Gets or sets the current value of the signal.
+	 * Accessing this property inside a computed signal or effect automatically registers it as a dependency.
+	 */
+	get value(): T;
+	set value(v: T|null|undefined);
+	getValue(): T;
+	getValue(): T;
+
+	// Key is used for observable array proxy bindings.
+	// If a key is provided, it's used to uniquely identify array elements.
+	// If a key is not provided, identification is done automatically by the framework by comparing object references.
+	key: string;
+	// subscribeNode(node: Node): number;
+	// subscribeAttr(node: HTMLElement, attributeName: string): number;
+	// subscribeCallback(callback: (value: T)=>void): number;
+	// detachBinding(id: number);
+
+	/** 
+	 * Subscribe to changes in the reactive object.
+	*/
+	subscribe(callback: Function): number;
+
+	_subscribe(boundReactive: IBinding, item: any);
+	_detachBinding(id: number);
+
+	/**
+	 * Called manually by the user to trigger an update.
+	 * Useful for arrays and objects.
+	 */
+	updateObservers(): void;
+
+	bindAs<Td = string>(transform: (((v: T)=>Td)|({
+		display?: (v: T)=>Td;
+		read?: (v: string)=>T;
+	}))): IBinding<T, Td>;
+
+	bind(): IBinding<T>;
+	unsubscribe(id: number): void;
+	refresh(priority?: any): void;
+
+	/**
+	 * Sets a new value for the signal. 
+	 * Equivalent to setting the `.value` property, but allows specifying an update priority.
+	 * @param v The new value.
+	 * @param priority Optional update priority.
+	 */
+	setValue(v: T, priority?: any): void;
+}

package/src/{i-dot-component.d.ts → i-dot-component.ts}

@@ -1,84 +1,113 @@
-
-import { IDotCore, IDotDocument } from "./i-dot";
-
-// export type EventNames<T> = T extends { allowedEvents: infer E } ? E : never;
-
-// TODO: I think this could be typed so that it forces you to emit events from the list of strings.
-export interface FrameworkItems {
-	/**
-	 * The shadow root element of the component.
-	 */
-	readonly refs: { [key: string]: HTMLElement };
-	emit<T>(event: string, ...args: Array<any>): void;
-	restyle(): void;
-	readonly props: Record<string, any>;
-	readonly _meta: {
-		readonly allowedEvents: string[];
-		readonly shadowRoot: ShadowRoot;
-		readonly isRendered: boolean;
-		readonly tagName: string;
-		// readonly styles: Array<string>; // Can't have this anymore because it's a memory leak.
-		readonly args: Array<any>;
-		// readonly styleElement: HTMLStyleElement;
-		readonly sharedStyles: CSSStyleSheet[];
-	}
-	// css: IDotCss;
-	// html: IDotGenericElement;
-}
-
-
-// TODO: there's a weird problem where if a constructor is not provided, it's not possible have a custom builder.
-// It should be the contsructor that depends on the builder, not the other way around. If we can't get this working, 
-// it might just be better to rethink how stuff gets passed into components.
-export default interface IDotComponent/*<TProps extends Array<string> = [], TEvents extends Array<string> = []>*/ {
-
-	readonly _?: FrameworkItems;
-
-	// Regrettably, TS forces clients to implement the constructor, which is not ideal because we want to internalize that.
-	// There's no way to make the constructor optional.
-	// new (attrs?: ComponentArgs<TProps, TEvents>): IComponent<TProps, TEvents>;
-	// new (): IComponent<TProps, TEvents>;
-
-    // Lifecycle hooks
-
-	/**
-	 * A function returning DOThtml (required). The `build` hook is called once per component instance, and constructs the component's virtual DOM.
-	 * @param dot - The DOThtml core object passed in for DI purposes. You can also just use the main .
-	 * @returns The DOThtml document representing the component's virtual DOM.	 */
-    build(dot: IDotCore): IDotDocument;
-
-	/**
-	 * An optional function called after the component is built. Is only called once per component instance. 
-	 */
-    built?(): void;
-	
-	/**
-	 * An optional function that gets called before the component is mounted.
-	 */
-    mounting?(): void;
-
-	/**
-	 * An optional function called after the element has been mounted. May be called mulitple times if the component is rerendered.
-	 */
-    mounted?(): void;
-	
-	/**
-	 * An optional function that gets called before the component is unmounted. Use it to do custom cleanup or data saving.
-	 */
-    unmounting?(): void;
-
-	/**
-	 * An optional function called after the element has been unmounted. May be called mulitple times if the component is rerendered.
-	 */
-    unmounted?(): void;
-
-	/**
-	 * A function that returns a string containing CSS rules to be applied to all instances of the component.
-	 * It will only be called exactly once per component. We use a function so that you can return a potentially 
-	 * large string containing CSS without introducing a memory leak. The reason it's not static is so that 
-	 * it will work in JavaScript, and because static members are not valid in DI interfaces. All styles are scoped
-	 * to the component's shadow DOM.
-	 * @returns A string (or array of strings) containing imported CSS rules.
-	 */
-	stylize?(): string|Array<string>;
-}
+
+import { IDotCore, IDotDocument } from "./i-dot";
+
+// export type EventNames<T> = T extends { allowedEvents: infer E } ? E : never;
+
+// TODO: I think this could be typed so that it forces you to emit events from the list of strings.
+export interface FrameworkItems {
+	/**
+	 * The shadow root element of the component.
+	 */
+	readonly refs: { [key: string]: HTMLElement };
+	emit<T>(event: string, ...args: Array<any>): void;
+	restyle(): void;
+	readonly props: Record<string, any>;
+	readonly cvdom: any;
+	readonly _meta: {
+		readonly allowedEvents: string[];
+		readonly shadowRoot: ShadowRoot;
+		readonly isRendered: boolean;
+		readonly tagName: string;
+		readonly args: Array<any>;
+		readonly sharedStyles: CSSStyleSheet[];
+	}
+}
+
+
+// TODO: there's a weird problem where if a constructor is not provided, it's not possible have a custom builder.
+// It should be the contsructor that depends on the builder, not the other way around. If we can't get this working, 
+// it might just be better to rethink how stuff gets passed into components.
+export default interface IDotComponent/*<TProps extends Array<string> = [], TEvents extends Array<string> = []>*/ {
+
+	readonly _?: FrameworkItems;
+	props?: any;
+	slots?: Record<string, any>;
+
+	/**
+	 * Registers a side effect that is automatically cleaned up when the component is unmounted.
+	 * @param callback The side effect to run. Can return a cleanup function.
+	 */
+	effect?(callback: () => void | (() => void)): void;
+
+	// Regrettably, TS forces clients to implement the constructor, which is not ideal because we want to internalize that.
+	// There's no way to make the constructor optional.
+	// new (attrs?: ComponentArgs<TProps, TEvents>): IComponent<TProps, TEvents>;
+	// new (): IComponent<TProps, TEvents>;
+
+    // Lifecycle hooks
+
+	/**
+	 * A function returning DOThtml (required). The `build` hook is called once per component instance, and constructs the component's virtual DOM.
+	 * @param dot - The DOThtml core object passed in for DI purposes. You can also just use the main .
+	 * @returns The DOThtml document representing the component's virtual DOM.	 */
+    build(dot: IDotCore): IDotDocument;
+
+	/**
+	 * An optional function called after the component is built. Is only called once per component instance. 
+	 */
+    built?(): void;
+	
+	/**
+	 * An optional function that gets called before the component is mounted.
+	 */
+    mounting?(): void;
+
+	/**
+	 * An optional function called after the element has been mounted. May be called mulitple times if the component is rerendered.
+	 */
+    mounted?(): void;
+	
+	/**
+	 * An optional function that gets called before the component is unmounted. Use it to do custom cleanup or data saving.
+	 */
+    unmounting?(): void;
+
+	/**
+	 * An optional function called after the element has been unmounted. May be called mulitple times if the component is rerendered.
+	 */
+    unmounted?(): void;
+
+	/**
+	 * An optional function called after the component has entered the DOM.
+	 */
+	onEnter?(): void;
+
+	/**
+	 * An optional function called before the component leaves the DOM.
+	 * If it returns a Promise, the VDOM engine will wait for it to resolve before removing the component.
+	 */
+	onLeave?(): Promise<void> | void;
+
+	/**
+	 * A function that returns a string containing CSS rules to be applied to all instances of the component.
+	 * It will only be called exactly once per component. We use a function so that you can return a potentially 
+	 * large string containing CSS without introducing a memory leak. The reason it's not static is so that 
+	 * it will work in JavaScript, and because static members are not valid in DI interfaces. All styles are scoped
+	 * to the component's shadow DOM.
+	 * @returns A string (or array of strings) containing imported CSS rules.
+	 */
+	stylize?(s?: any): string | string[] | any;
+
+	/**
+	 * An optional function that allows you to apply styles directly to the component's host element.
+	 */
+	hostStyle?(s: any): void;
+
+	/**
+	 * An optional function that gets called when an error occurs during the component's lifecycle.
+	 * If implemented, the component acts as an error boundary.
+	 * @param error - The error that occurred.
+	 * @returns The DOThtml document to render as a fallback UI.
+	 */
+	errorCaught?(error: any): IDotDocument | void;
+}