@praxisjs/decorators 0.4.2 → 0.5.0

package/src/component/lazy.ts

@@ -1,58 +1,56 @@
 import { type RootComponent, signal } from "@praxisjs/core/internal";
 
-export function Lazy(placeholder = 200) {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  return function <T extends new (...args: any[]) => RootComponent>(
-    constructor: T,
-    _context: ClassDecoratorContext,
-  ): T {
-    return class LazyWrapper extends constructor {
-      private readonly _lazyVisible = signal(false);
-      private _observer?: IntersectionObserver;
-      private readonly _originalRender: () => Node | Node[] | null =
-        this.render.bind(this);
+import { ClassBehavior, createClassDecorator, type ClassEnhancement } from "../create-class-decorator";
 
-      onMount() {
-        super.onMount?.();
+class LazyBehavior extends ClassBehavior {
+  constructor(private readonly placeholder: number) {
+    super();
+  }
 
-        // Use the end anchor to find the parent element
+  create(instance: RootComponent): ClassEnhancement {
+    const placeholder = this.placeholder;
+    const visible = signal(false);
+    let observer: IntersectionObserver | undefined;
+
+    return {
+      onMount() {
         const el =
-          (this as unknown as { _anchor?: Comment })._anchor
-            ?.parentElement ?? null;
+          (instance as { _anchor?: Comment })._anchor?.parentElement ?? null;
         if (!el) return;
 
         if (!("IntersectionObserver" in window)) {
-          this._lazyVisible.set(true);
+          visible.set(true);
           return;
         }
 
-        if (!this._lazyVisible()) {
-          el.style.minHeight = `${String(placeholder)}px`;
-        }
+        if (!visible()) el.style.minHeight = `${String(placeholder)}px`;
 
-        this._observer = new IntersectionObserver(
+        observer = new IntersectionObserver(
           (entries) => {
             if (entries[0]?.isIntersecting) {
-              this._lazyVisible.set(true);
+              visible.set(true);
               el.style.minHeight = "";
-              this._observer?.disconnect();
+              observer?.disconnect();
             }
           },
           { rootMargin: "100px" },
         );
 
-        this._observer.observe(el);
-      }
+        observer.observe(el);
+      },
 
       onUnmount() {
-        super.onUnmount?.();
-        this._observer?.disconnect();
-      }
-
-      render(): Node | Node[] | null {
-        if (!this._lazyVisible()) return null;
-        return this._originalRender();
-      }
-    } as unknown as T;
-  };
+        observer?.disconnect();
+      },
+
+      render(originalRender) {
+        if (!visible()) return null;
+        return originalRender();
+      },
+    };
+  }
+}
+
+export function Lazy(placeholder = 200) {
+  return createClassDecorator(new LazyBehavior(placeholder));
 }

package/src/component/virtual.tsx

@@ -1,81 +1,76 @@
 import { computed, effect, type RootComponent, signal } from "@praxisjs/core/internal";
 
+import { ClassBehavior, createClassDecorator, type ClassEnhancement } from "../create-class-decorator";
+
 interface VirtualHost {
   _anchor?: Comment;
   items?: unknown[];
   renderItem(item: unknown, index: number): Node | Node[] | null;
 }
 
-export function Virtual(itemHeight: number, buffer = 3) {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  return function <T extends new (...args: any[]) => RootComponent>(
-    constructor: T,
-    _context: ClassDecoratorContext,
-  ): T {
-    return class VirtualWrapper extends constructor {
-      private readonly _scrollTop = signal(0);
-      private readonly _viewHeight = signal(600);
-      private _container?: HTMLElement;
-      private _scrollHandler?: () => void;
-      private _cleanups: Array<() => void> = [];
-
+class VirtualBehavior extends ClassBehavior {
+  constructor(
+    private readonly itemHeight: number,
+    private readonly buffer: number,
+  ) {
+    super();
+  }
+
+  create(instance: RootComponent): ClassEnhancement {
+    const { itemHeight, buffer } = this;
+    const host = instance as unknown as VirtualHost;
+    const scrollTop = signal(0);
+    const viewHeight = signal(600);
+    let container: HTMLElement | undefined;
+    let scrollHandler: (() => void) | undefined;
+    const cleanups: Array<() => void> = [];
+
+    return {
       onMount() {
-        super.onMount?.();
-
-        // Use the end anchor set by the runtime to locate the parent element
-        this._container =
-          (this as unknown as VirtualHost)._anchor?.parentElement ?? undefined;
-
-        if (!this._container) return;
+        container = host._anchor?.parentElement ?? undefined;
+        if (!container) return;
 
-        this._container.style.overflowY = "auto";
-        this._container.style.position = "relative";
+        container.style.overflowY = "auto";
+        container.style.position = "relative";
+        viewHeight.set(container.clientHeight || 600);
 
-        this._viewHeight.set(this._container.clientHeight || 600);
-
-        this._scrollHandler = () => {
-          if (this._container) this._scrollTop.set(this._container.scrollTop);
+        scrollHandler = () => {
+          if (container) scrollTop.set(container.scrollTop);
         };
-
-        this._container.addEventListener("scroll", this._scrollHandler);
-      }
+        container.addEventListener("scroll", scrollHandler);
+      },
 
       onUnmount() {
-        super.onUnmount?.();
-        if (this._container && this._scrollHandler) {
-          this._container.removeEventListener("scroll", this._scrollHandler);
+        if (container && scrollHandler) {
+          container.removeEventListener("scroll", scrollHandler);
         }
-        this._cleanups.forEach((c) => { c(); });
-        this._cleanups = [];
-      }
+        cleanups.forEach((c) => { c(); });
+        cleanups.length = 0;
+      },
 
-      render() {
-        const host = this as unknown as VirtualHost;
+      render(originalRender) {
         const items = host.items ?? [];
         const total = items.length;
         const totalH = total * itemHeight;
 
         if (typeof host.renderItem !== "function") {
           console.warn(
-            `[Virtual] ${constructor.name} must implement renderItem(item, index)`,
+            `[Virtual] component must implement renderItem(item, index)`,
           );
-          return null;
+          return originalRender();
         }
 
         const renderItem = host.renderItem.bind(host);
 
-        const startIdx = computed(() => {
-          const start = Math.floor(this._scrollTop() / itemHeight) - buffer;
-          return Math.max(0, start);
-        });
-
-        const endIdx = computed(() => {
-          const end =
-            Math.ceil((this._scrollTop() + this._viewHeight()) / itemHeight) +
-            buffer;
-          return Math.min(total - 1, end);
-        });
-
+        const startIdx = computed(() =>
+          Math.max(0, Math.floor(scrollTop() / itemHeight) - buffer),
+        );
+        const endIdx = computed(() =>
+          Math.min(
+            total - 1,
+            Math.ceil((scrollTop() + viewHeight()) / itemHeight) + buffer,
+          ),
+        );
         const visibleItems = computed(() => {
           const result: Array<{ item: unknown; index: number }> = [];
           for (let i = startIdx(); i <= endIdx(); i++) {
@@ -83,31 +78,23 @@ export function Virtual(itemHeight: number, buffer = 3) {
           }
           return result;
         });
-
         const offsetTop = computed(() => startIdx() * itemHeight);
-        const offsetBottom = computed(
-          () => (total - 1 - endIdx()) * itemHeight,
-        );
+        const offsetBottom = computed(() => (total - 1 - endIdx()) * itemHeight);
 
         const outer = document.createElement("div");
-        outer.setAttribute(
-          "style",
-          `height:${String(totalH)}px; position:relative;`,
-        );
+        outer.setAttribute("style", `height:${String(totalH)}px; position:relative;`);
 
         const spacerTop = document.createElement("div");
-        this._cleanups.push(
+        cleanups.push(
           effect(() => {
             spacerTop.setAttribute("style", `height:${String(offsetTop())}px;`);
           }),
         );
 
         const itemsSlot = document.createElement("div");
-        this._cleanups.push(
+        cleanups.push(
           effect(() => {
-            while (itemsSlot.firstChild) {
-              itemsSlot.removeChild(itemsSlot.firstChild);
-            }
+            while (itemsSlot.firstChild) itemsSlot.removeChild(itemsSlot.firstChild);
             visibleItems().forEach(({ item, index }) => {
               const wrapper = document.createElement("div");
               wrapper.setAttribute(
@@ -116,10 +103,9 @@ export function Virtual(itemHeight: number, buffer = 3) {
               );
               const rendered = renderItem(item, index);
               if (rendered) {
-                const nodes = (
-                  Array.isArray(rendered) ? rendered.flat() : [rendered]
+                (Array.isArray(rendered) ? rendered.flat() : [rendered]).forEach(
+                  (n) => { wrapper.appendChild(n); },
                 );
-                nodes.forEach((n) => wrapper.appendChild(n));
               }
               itemsSlot.appendChild(wrapper);
             });
@@ -127,12 +113,9 @@ export function Virtual(itemHeight: number, buffer = 3) {
         );
 
         const spacerBottom = document.createElement("div");
-        this._cleanups.push(
+        cleanups.push(
           effect(() => {
-            spacerBottom.setAttribute(
-              "style",
-              `height:${String(offsetBottom())}px;`,
-            );
+            spacerBottom.setAttribute("style", `height:${String(offsetBottom())}px;`);
           }),
         );
 
@@ -141,7 +124,11 @@ export function Virtual(itemHeight: number, buffer = 3) {
         outer.appendChild(spacerBottom);
 
         return outer;
-      }
-    } as unknown as T;
-  };
+      },
+    };
+  }
+}
+
+export function Virtual(itemHeight: number, buffer = 3) {
+  return createClassDecorator(new VirtualBehavior(itemHeight, buffer));
 }

package/src/create-class-decorator.ts

@@ -0,0 +1,61 @@
+import type { RootComponent } from "@praxisjs/core/internal";
+
+export interface ClassEnhancement {
+  onMount?(): void;
+  onUnmount?(): void;
+  render?(
+    originalRender: () => Node | Node[] | null,
+  ): Node | Node[] | null;
+}
+
+export abstract class ClassBehavior {
+  abstract create(instance: RootComponent): ClassEnhancement;
+
+  /**
+   * Called once after the enhanced class is created.
+   * Use this to set static properties on the class constructor itself.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  initialize?(_Enhanced: new (...args: any[]) => unknown, _original: new (...args: any[]) => unknown): void;
+}
+
+export function createClassDecorator(behavior: ClassBehavior) {
+  return function <
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    T extends new (...args: any[]) => RootComponent<Record<string, any>>,
+  >(constructor: T, _context: ClassDecoratorContext): T {
+    const Enhanced = class extends constructor {
+      private readonly _enh: ClassEnhancement = behavior.create(
+        this as unknown as RootComponent,
+      );
+
+      onMount() {
+        super.onMount?.();
+        this._enh.onMount?.();
+      }
+
+      onUnmount() {
+        super.onUnmount?.();
+        this._enh.onUnmount?.();
+      }
+
+      render(...args: unknown[]): Node | Node[] | null {
+        const originalRender = () =>
+          (constructor.prototype as { render: (...a: unknown[]) => Node | Node[] | null }).render.apply(this, args);
+        if (this._enh.render) {
+          return this._enh.render(originalRender);
+        }
+        return originalRender();
+      }
+    };
+
+    // If the original class has no render, remove the wrapper so instances see `undefined`.
+    if (typeof (constructor.prototype as { render?: unknown }).render !== "function") {
+      delete (Enhanced.prototype as { render?: unknown }).render;
+    }
+
+    Object.defineProperty(Enhanced, "name", { value: constructor.name });
+    behavior.initialize?.(Enhanced, constructor);
+    return Enhanced as unknown as T;
+  };
+}

package/src/create-field-decorator.ts

@@ -0,0 +1,66 @@
+import type { StatefulComponent } from "@praxisjs/core";
+
+export interface FieldBinding {
+  /** Replaces the decorated property. If absent, the original property is left untouched. */
+  descriptor?: PropertyDescriptor;
+  /** Extra properties to define on the instance (e.g. companion properties like `nameHistory`). */
+  additional?: Record<string, PropertyDescriptor>;
+  onMount?: () => void;
+  onUnmount?: () => void;
+}
+
+export interface FieldBehavior {
+  bind(
+    instance: StatefulComponent,
+    name: string,
+    initialValue: unknown,
+  ): FieldBinding;
+}
+
+export function createFieldDecorator(behavior: FieldBehavior) {
+  return function (
+    _value: undefined,
+    context: ClassFieldDecoratorContext<StatefulComponent>,
+  ): void {
+    context.addInitializer(function (this: unknown) {
+      const instance = this as StatefulComponent & Record<string, unknown>;
+      const name = context.name as string;
+      const initialValue = instance[name];
+
+      const { descriptor, additional, onMount, onUnmount } = behavior.bind(
+        instance,
+        name,
+        initialValue,
+      );
+
+      if (descriptor) {
+        Reflect.deleteProperty(instance, name);
+        Object.defineProperty(instance, name, {
+          enumerable: true,
+          configurable: true,
+          ...descriptor,
+        });
+      }
+
+      for (const [key, desc] of Object.entries(additional ?? {})) {
+        Object.defineProperty(instance, key, {
+          configurable: true,
+          ...desc,
+        });
+      }
+
+      if (onMount ?? onUnmount) {
+        const prevMount = instance.onMount?.bind(instance);
+        const prevUnmount = instance.onUnmount?.bind(instance);
+        instance.onMount = () => {
+          prevMount?.();
+          onMount?.();
+        };
+        instance.onUnmount = () => {
+          prevUnmount?.();
+          onUnmount?.();
+        };
+      }
+    });
+  };
+}

package/src/create-getter-decorator.ts

@@ -0,0 +1,52 @@
+export interface GetterBehavior {
+  /**
+   * Given the original getter and the current instance, returns a function
+   * that produces the getter value. Called on every property access.
+   */
+  wrap(
+    original: (this: object) => unknown,
+    instance: object,
+  ): () => unknown;
+}
+
+export function createGetterDecorator(behavior: GetterBehavior) {
+  return function <This, T>(
+    target: (this: This) => T,
+    _context: ClassGetterDecoratorContext<This, T>,
+  ): (this: This) => T {
+    return function (this: This): T {
+      return behavior.wrap(
+        target as (this: object) => unknown,
+        this as object,
+      )() as T;
+    };
+  };
+}
+
+export interface GetterObserverBehavior {
+  /**
+   * Called once per instance when the class is initialized.
+   * Use this to set up observation side-effects on the getter without
+   * changing its return value (e.g. tracking changes for devtools).
+   */
+  observe(
+    getter: (this: object) => unknown,
+    instance: object,
+    name: string,
+  ): void;
+}
+
+export function createGetterObserverDecorator(behavior: GetterObserverBehavior) {
+  return function <This, T>(
+    target: (this: This) => T,
+    context: ClassGetterDecoratorContext<This, T>,
+  ): void {
+    context.addInitializer(function (this: unknown) {
+      behavior.observe(
+        target as (this: object) => unknown,
+        this as object,
+        context.name as string,
+      );
+    });
+  };
+}

package/src/create-lifecycle-method-decorator.ts

@@ -0,0 +1,38 @@
+import type { StatefulComponent } from "@praxisjs/core";
+
+export interface LifecycleMethodBehavior<
+  T extends StatefulComponent = StatefulComponent,
+> {
+  register(
+    callback: (...args: unknown[]) => void,
+    instance: T,
+  ): (() => void) | undefined;
+}
+
+export function createLifecycleMethodDecorator<
+  T extends StatefulComponent = StatefulComponent,
+>(behavior: LifecycleMethodBehavior<T>) {
+  return function (
+    value: (this: T, ...args: unknown[]) => void,
+    _context: ClassMethodDecoratorContext<T>,
+  ): void {
+    _context.addInitializer(function (this: unknown) {
+      const instance = this as T;
+      const prevMount = instance.onMount?.bind(instance);
+      const prevUnmount = instance.onUnmount?.bind(instance);
+      let cleanup: (() => void) | undefined;
+
+      instance.onMount = function (this: T) {
+        prevMount?.call(this);
+        const result = behavior.register(value.bind(this), this);
+        if (result) cleanup = result;
+      };
+
+      instance.onUnmount = function (this: T) {
+        prevUnmount?.call(this);
+        cleanup?.();
+        cleanup = undefined;
+      };
+    });
+  };
+}

package/src/create-method-decorator.ts

@@ -0,0 +1,26 @@
+import type { StatefulComponent } from "@praxisjs/core";
+
+export interface MethodBehavior {
+  wrap(
+    original: (...args: unknown[]) => unknown,
+    instance: object,
+    name: string,
+  ): (...args: unknown[]) => unknown;
+}
+
+export function createMethodDecorator(behavior: MethodBehavior) {
+  return function (
+    value: (this: object, ...args: unknown[]) => unknown,
+    context: ClassMethodDecoratorContext<StatefulComponent>,
+  ): void {
+    context.addInitializer(function (this: unknown) {
+      const instance = this as object;
+      const name = context.name as string;
+      Object.defineProperty(instance, name, {
+        value: behavior.wrap(value, instance, name),
+        configurable: true,
+        writable: true,
+      });
+    });
+  };
+}

package/src/events/emit.ts

@@ -1,42 +1,31 @@
 import type { StatefulComponent } from "@praxisjs/core";
 
+import { createMethodDecorator } from "../create-method-decorator";
 import { readProp } from "./helper";
 
 export function Emit(propName: string) {
-  return function (
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    value: (this: StatefulComponent, ...args: any[]) => any,
-    context: ClassMethodDecoratorContext<StatefulComponent>,
-  ): void {
-    const wrapped = function (
-      this: StatefulComponent,
-      ...args: unknown[]
-    ): unknown {
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-      const result = value.apply(this, args);
+  return createMethodDecorator({
+    wrap(original, instance) {
+      const comp = instance as StatefulComponent;
+      return (...args: unknown[]) => {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any
+        const result = original.apply(instance, args) as any;
 
-      const callback = readProp(this, propName);
-      if (typeof callback !== "function") return result;
+        const callback = readProp(comp, propName);
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        if (typeof callback !== "function") return result;
 
-      if (result !== undefined) {
-        (callback as (v: unknown) => void)(result);
-      } else if (args.length > 0) {
-        (callback as (...a: unknown[]) => void)(...args);
-      } else {
-        (callback as () => void)();
-      }
+        if (result !== undefined) {
+          (callback as (v: unknown) => void)(result);
+        } else if (args.length > 0) {
+          (callback as (...a: unknown[]) => void)(...args);
+        } else {
+          (callback as () => void)();
+        }
 
-      return result;
-    };
-
-    context.addInitializer(function (this: unknown) {
-      const name = context.name as string;
-      const bound = wrapped.bind(this as StatefulComponent);
-      Object.defineProperty(this as object, name, {
-        value: bound,
-        configurable: true,
-        writable: true,
-      });
-    });
-  };
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return result;
+      };
+    },
+  });
 }