@praxisjs/decorators 0.1.0

package/dist/properties/state.js

@@ -0,0 +1,24 @@
+import { signal } from "@praxisjs/core";
+export function State() {
+    return function (target, propertyKey) {
+        const signalMap = new WeakMap();
+        Object.defineProperty(target, propertyKey, {
+            get() {
+                if (!signalMap.has(this))
+                    signalMap.set(this, signal(undefined));
+                return signalMap.get(this)();
+            },
+            set(value) {
+                if (!signalMap.has(this))
+                    signalMap.set(this, signal(value));
+                else {
+                    this._stateDirty = true;
+                    signalMap.get(this).set(value);
+                }
+            },
+            enumerable: true,
+            configurable: true,
+        });
+    };
+}
+//# sourceMappingURL=state.js.map

package/dist/properties/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/properties/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAGxC,MAAM,UAAU,KAAK;IACnB,OAAO,UAAU,MAAc,EAAE,WAAmB;QAClD,MAAM,SAAS,GAAG,IAAI,OAAO,EAA2B,CAAC;QAEzD,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE;YACzC,GAAG;gBACD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;oBAAE,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;gBACjE,OAAQ,SAAS,CAAC,GAAG,CAAC,IAAI,CAAqB,EAAE,CAAC;YACpD,CAAC;YACD,GAAG,CAAe,KAAc;gBAC9B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;oBAAE,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;qBACxD,CAAC;oBACH,IAA0B,CAAC,WAAW,GAAG,IAAI,CAAC;oBAC9C,SAAS,CAAC,GAAG,CAAC,IAAI,CAAqB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBACtD,CAAC;YACH,CAAC;YACD,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@praxisjs/decorators",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@praxisjs/core": "0.1.0",
+    "@praxisjs/jsx": "0.1.0",
+    "@praxisjs/shared": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}

package/src/component/component.ts

@@ -0,0 +1,18 @@
+import type { ComponentConstructor, ComponentInstance } from "@praxisjs/shared";
+
+export function Component() {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return function <T extends new (...args: any[]) => ComponentInstance>(
+    constructor: T,
+  ): T & ComponentConstructor {
+    const Enhanced = class extends constructor {
+      static isComponent = true as const;
+    } as unknown as T & ComponentConstructor;
+
+    Object.defineProperty(Enhanced, "name", {
+      value: constructor.name,
+    });
+
+    return Enhanced;
+  };
+}

package/src/component/index.ts

@@ -0,0 +1,4 @@
+export { Component } from "./component";
+export { Memoize } from "./memoize";
+export { Lazy } from "./lazy";
+export { Virtual } from "./virtual";

package/src/component/lazy.ts

@@ -0,0 +1,56 @@
+import { type BaseComponent, signal } from "@praxisjs/core";
+import type { VNode } from "@praxisjs/shared";
+
+export function Lazy(placeholder = 200) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return function <T extends new (...args: any[]) => BaseComponent>(
+    constructor: T,
+  ): T {
+    return class LazyWrapper extends constructor {
+      private readonly _lazyVisible = signal(false);
+      private _observer?: IntersectionObserver;
+      private readonly _originalRender: () => VNode | null = this.render.bind(this);
+
+      onMount() {
+        super.onMount?.();
+
+        const el = document.querySelector<HTMLElement>(
+          `[data-component="${constructor.name}"]`,
+        );
+        if (!el) return;
+
+        if (!("IntersectionObserver" in window)) {
+          this._lazyVisible.set(true);
+          return;
+        }
+
+        if (!this._lazyVisible()) {
+          el.style.minHeight = `${String(placeholder)}px`;
+        }
+
+        this._observer = new IntersectionObserver(
+          (entries) => {
+            if (entries[0]?.isIntersecting) {
+              this._lazyVisible.set(true);
+              el.style.minHeight = "";
+              this._observer?.disconnect();
+            }
+          },
+          { rootMargin: "100px" },
+        );
+
+        this._observer.observe(el);
+      }
+
+      onUnmount() {
+        super.onUnmount?.();
+        this._observer?.disconnect();
+      }
+
+      render(): VNode | null {
+        if (!this._lazyVisible()) return null;
+        return this._originalRender();
+      }
+    } as unknown as T;
+  };
+}

package/src/component/lifecycle.ts

@@ -0,0 +1,47 @@
+import { type BaseComponent, VALID_LIFECYCLE_HOOK_SIGNATURES } from "@praxisjs/core";
+
+function getAllMethods(proto: object): string[] {
+  const methods: string[] = [];
+  let current: object | null = proto;
+
+  while (current !== null && current !== Object.prototype) {
+    const names = Object.getOwnPropertyNames(current);
+    for (const name of names) {
+      if (
+        name !== "constructor" &&
+        typeof (current as Record<string, unknown>)[name] === "function"
+      ) {
+        if (!methods.includes(name)) methods.push(name);
+      }
+    }
+    current = Object.getPrototypeOf(current) as object | null;
+  }
+
+  return methods;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function LifeCycle<T extends new (...args: any[]) => BaseComponent>(
+  constructor: T,
+): T {
+  if (process.env.NODE_ENV === "production") return constructor;
+
+  const validHooks = new Set<string>(
+    Object.keys(VALID_LIFECYCLE_HOOK_SIGNATURES),
+  );
+  const proto = constructor.prototype as Record<string, unknown>;
+
+  const allMethods = getAllMethods(proto);
+  for (const method of allMethods) {
+    if (!method.startsWith("on")) continue;
+
+    if (!validHooks.has(method)) {
+      console.warn(
+        `[LifeCycle] "${constructor.name}.${method}" appears to be a lifecycle hook but is not recognized.\n` +
+          `Valid hooks: ${[...validHooks].join(", ")}`,
+      );
+    }
+  }
+
+  return constructor;
+}

package/src/component/memoize.ts

@@ -0,0 +1,31 @@
+import type { ComponentInstance } from "@praxisjs/shared";
+
+type PropsRecord = Record<string, unknown>;
+
+function shallowEqual(a: PropsRecord, b: PropsRecord) {
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+
+  if (keysA.length !== keysB.length) return false;
+
+  const bHasOwnProperty = Object.prototype.hasOwnProperty.bind(b);
+
+  for (const aKey of keysA) {
+    if (!bHasOwnProperty(aKey)) return false;
+    if (!Object.is(a[aKey], b[aKey])) return false;
+  }
+  return true;
+}
+
+export function Memoize(
+  areEqual: (prev: PropsRecord, next: PropsRecord) => boolean = shallowEqual,
+) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return function <T extends new (...args: any[]) => ComponentInstance>(
+    constructor: T,
+  ): T {
+    (constructor as unknown as ComponentInstance)._isMemorized = true;
+    (constructor as unknown as ComponentInstance)._arePropsEqual = areEqual;
+    return constructor;
+  };
+}

package/src/component/virtual.tsx

@@ -0,0 +1,104 @@
+import { type BaseComponent, computed, signal } from "@praxisjs/core";
+import type { VNode } from "@praxisjs/shared";
+
+export function Virtual(itemHeight: number, buffer = 3) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return function <T extends new (...args: any[]) => BaseComponent>(
+    constructor: T,
+  ): T {
+    return class VirtualWrapper extends constructor {
+      private readonly _scrollTop = signal(0);
+      private readonly _viewHeight = signal(600);
+      private _container?: HTMLElement;
+      private _scrollHandler?: () => void;
+
+      onMount() {
+        super.onMount?.();
+
+        this._container =
+          document.querySelector<HTMLElement>(
+            `[data-component="${constructor.name}"]`,
+          ) ?? undefined;
+
+        if (!this._container) return;
+
+        this._container.style.overflowY = "auto";
+        this._container.style.position = "relative";
+
+        this._viewHeight.set(this._container.clientHeight || 600);
+
+        this._scrollHandler = () => {
+          if (this._container) this._scrollTop.set(this._container.scrollTop);
+        };
+
+        this._container.addEventListener("scroll", this._scrollHandler);
+      }
+
+      onUnmount() {
+        super.onUnmount?.();
+        if (this._container && this._scrollHandler) {
+          this._container.removeEventListener("scroll", this._scrollHandler);
+        }
+      }
+
+      render() {
+        const instance = this as unknown as Record<string, unknown>;
+        const items = (instance.items as unknown[] | undefined) ?? [];
+        const total = items.length;
+        const totalH = total * itemHeight;
+
+        const renderItem = instance.renderItem as
+          | ((item: unknown, i: number) => VNode | null)
+          | undefined;
+        if (!renderItem) {
+          console.warn(
+            `[Virtual] ${constructor.name} must implement renderItem(item, index)`,
+          );
+          return null;
+        }
+
+        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 visibleItems = computed(() => {
+          const result = [];
+          for (let i = startIdx(); i <= endIdx(); i++) {
+            result.push({ item: items[i], index: i });
+          }
+          return result;
+        });
+
+        const offsetTop = computed(() => startIdx() * itemHeight);
+        const offsetBottom = computed(
+          () => (total - 1 - endIdx()) * itemHeight,
+        );
+
+        return (
+          <div style={`height:${String(totalH)}px; position:relative;`}>
+            <div style={() => `height:${String(offsetTop())}px;`} />
+            {() =>
+              visibleItems().map(({ item, index }) => (
+                <div
+                  key={String(index)}
+                  style={`height:${String(itemHeight)}px; overflow:hidden;`}
+                >
+                  {renderItem.call(this, item, index)}
+                </div>
+              ))
+            }
+            <div style={() => `height:${String(offsetBottom())}px;`} />
+          </div>
+        ) as unknown as VNode;
+      }
+    } as unknown as T;
+  };
+}

package/src/events/command.ts

@@ -0,0 +1,17 @@
+export interface Command<T = void> {
+  trigger(arg: T): void;
+  subscribe(handler: (arg: T) => void): () => void;
+}
+
+export function createCommand<T = void>(): Command<T> {
+  const handlers = new Set<(arg: T) => void>();
+  return {
+    trigger(arg: T) {
+      handlers.forEach((h) => { h(arg); });
+    },
+    subscribe(handler) {
+      handlers.add(handler);
+      return () => handlers.delete(handler);
+    },
+  };
+}

package/src/events/emit.ts

@@ -0,0 +1,47 @@
+import type { BaseComponent } from "@praxisjs/core";
+
+import { readProp } from "./helper";
+
+export function Emit(propName: string) {
+  return function (
+    _target: object,
+    methodKey: string,
+    descriptor: PropertyDescriptor,
+  ): PropertyDescriptor {
+    const originalMethod = descriptor.value as (...args: unknown[]) => unknown;
+
+    const wrapped = function (
+      this: BaseComponent,
+      ...args: unknown[]
+    ): unknown {
+      const result = originalMethod.apply(this, args);
+
+      const callback = readProp(this, propName);
+      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)();
+      }
+
+      return result;
+    };
+
+    return {
+      configurable: true,
+      enumerable: false,
+      get(this: BaseComponent) {
+        const bound = wrapped.bind(this);
+        Object.defineProperty(this, methodKey, {
+          value: bound,
+          configurable: true,
+          writable: true,
+        });
+        return bound;
+      },
+    };
+  };
+}

package/src/events/helper.ts

@@ -0,0 +1,7 @@
+import type { BaseComponent } from "@praxisjs/core";
+
+export function readProp(instance: BaseComponent, propName: string): unknown {
+  const fromParent = instance._rawProps[propName];
+  if (fromParent !== undefined) return fromParent;
+  return instance._defaults[propName];
+}

package/src/events/index.ts

@@ -0,0 +1,3 @@
+export { type Command, createCommand } from "./command";
+export { Emit } from "./emit";
+export { OnCommand } from "./on-command";

package/src/events/on-command.ts

@@ -0,0 +1,55 @@
+import type { BaseComponent } from "@praxisjs/core";
+
+import { readProp } from "./helper";
+
+import type { Command } from "./command";
+
+export function OnCommand(propName: string) {
+  return function (
+    target: object,
+    _methodKey: string,
+    descriptor: PropertyDescriptor,
+  ): PropertyDescriptor {
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    const originalOnMount = (target as { onMount?(): void }).onMount;
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    const originalOnUnmount = (target as { onUnmount?(): void }).onUnmount;
+
+    const method = descriptor.value as (...args: unknown[]) => void;
+    const cleanups = new WeakMap<object, () => void>();
+
+    (target as { onMount?(): void }).onMount = function (this: BaseComponent) {
+      originalOnMount?.call(this);
+
+      const command = readProp(this, propName) as Command<unknown> | undefined;
+
+      if (!command) {
+        console.warn(
+          `[OnCommand] prop "${propName}" was not provided to ${this.constructor.name}`,
+        );
+        return;
+      }
+
+      if (typeof command.subscribe !== "function") {
+        console.warn(
+          `[OnCommand] prop "${propName}" is not a valid Command in ${this.constructor.name}`,
+        );
+        return;
+      }
+
+      const bound = method.bind(this);
+      const unsub = command.subscribe((...args: unknown[]) => { bound(...args); });
+      cleanups.set(this, unsub);
+    };
+
+    (target as { onUnmount?(): void }).onUnmount = function (
+      this: BaseComponent,
+    ) {
+      originalOnUnmount?.call(this);
+      cleanups.get(this)?.();
+      cleanups.delete(this);
+    };
+
+    return descriptor;
+  };
+}

package/src/functions/bind.ts

@@ -0,0 +1,22 @@
+export function Bind() {
+  return function (
+    _target: object,
+    methodKey: string,
+    descriptor: PropertyDescriptor,
+  ): PropertyDescriptor {
+    const originalMethod = descriptor.value as (...args: unknown[]) => unknown;
+    return {
+      enumerable: false,
+      configurable: true,
+      get(this: object) {
+        const bound = originalMethod.bind(this);
+        Object.defineProperty(this, methodKey, {
+          value: bound,
+          configurable: true,
+          writable: true,
+        });
+        return bound;
+      },
+    };
+  };
+}

package/src/functions/debounce.ts

@@ -0,0 +1,34 @@
+export function Debounce(ms: number) {
+  const timers = new WeakMap<object, ReturnType<typeof setTimeout>>();
+
+  return function (
+    _target: object,
+    methodKey: string,
+    descriptor: PropertyDescriptor,
+  ): PropertyDescriptor {
+    const originalMethod = descriptor.value as (...args: unknown[]) => unknown;
+    return {
+      enumerable: false,
+      configurable: true,
+      get(this: object) {
+        const bound = (...args: unknown[]) => {
+          const existing = timers.get(this);
+          if (existing !== undefined) clearTimeout(existing);
+
+          const timer = setTimeout(() => {
+            timers.delete(this);
+            originalMethod.apply(this, args);
+          }, ms);
+
+          timers.set(this, timer);
+        };
+        Object.defineProperty(this, methodKey, {
+          value: bound,
+          configurable: true,
+          writable: true,
+        });
+        return bound;
+      },
+    };
+  };
+}

package/src/functions/index.ts

@@ -0,0 +1,9 @@
+export { Memo } from "./memo";
+export { Bind } from "./bind";
+export { Log } from "./log";
+export { Once } from "./once";
+export { Retry } from "./retry";
+export { Debounce } from "./debounce";
+export { Throttle } from "./throttle";
+export { When } from "./when";
+export { Watch, type WatchVal, type WatchVals } from "./watch";

package/src/functions/log.ts

@@ -0,0 +1,68 @@
+export interface LogOptions {
+  level?: "log" | "warn" | "error" | "debug";
+  args?: boolean;
+  result?: boolean;
+  time?: boolean;
+  devOnly?: boolean;
+}
+
+export function Log(options: LogOptions = {}) {
+  const {
+    level = "log",
+    args: logArgs = true,
+    result = true,
+    time = false,
+    devOnly = true,
+  } = options;
+
+  return function (
+    _target: object,
+    methodKey: string,
+    descriptor: PropertyDescriptor,
+  ): PropertyDescriptor {
+    const originalMethod = descriptor.value as (...args: unknown[]) => unknown;
+
+    descriptor.value = function (this: object, ...args: unknown[]) {
+      if (
+        devOnly &&
+        typeof process !== "undefined" &&
+        process.env.NODE_ENV === "production"
+      ) {
+        return originalMethod.apply(this, args);
+      }
+
+      const className = (this.constructor as { name?: string }).name ?? "Unknown";
+      const label = `[${className}.${methodKey}]`;
+      const logger = console[level].bind(console);
+
+      if (logArgs) logger(`${label} args:`, args);
+
+      const start = time ? performance.now() : 0;
+      const output = originalMethod.apply(this, args);
+
+      if (output instanceof Promise) {
+        return (output as Promise<unknown>)
+          .then((resolved) => {
+            const elapsed = time
+              ? ` (${(performance.now() - start).toFixed(2)}ms)`
+              : "";
+            if (result) logger(`${label} resolved:`, resolved, elapsed);
+            return resolved;
+          })
+          .catch((e: unknown) => {
+            logger(`${label} rejected:`, e);
+            throw e;
+          });
+      }
+
+      const elapsed = time
+        ? ` (${(performance.now() - start).toFixed(2)}ms)`
+        : "";
+      if (result) logger(`${label} returned:`, output, elapsed);
+
+      return output;
+    };
+
+    return descriptor;
+  };
+}

package/src/functions/memo.ts

@@ -0,0 +1,63 @@
+import { computed } from "@praxisjs/core";
+import type { Computed } from "@praxisjs/shared";
+
+const instanceCache = new WeakMap<
+  object,
+  Map<string, Map<string, Computed<unknown>>>
+>();
+
+function getCache(
+  instance: object,
+  methodName: string,
+  argKey: string,
+  factory: () => unknown,
+): Computed<unknown> {
+  let methodMap = instanceCache.get(instance);
+  if (!methodMap) {
+    methodMap = new Map();
+    instanceCache.set(instance, methodMap);
+  }
+
+  let argMap = methodMap.get(methodName);
+  if (!argMap) {
+    argMap = new Map();
+    methodMap.set(methodName, argMap);
+  }
+
+  let cached = argMap.get(argKey);
+  if (!cached) {
+    cached = computed(factory);
+    argMap.set(argKey, cached);
+  }
+
+  return cached;
+}
+
+function serializeArgs(args: unknown[]) {
+  if (args.length === 0) return "__no_args__";
+  return args
+    .map((a) => {
+      if (a === null || typeof a === "object") return JSON.stringify(a);
+      if (typeof a === "symbol") return a.toString();
+      return String(a as string | number | boolean | bigint | undefined);
+    })
+    .join("|");
+}
+
+export function Memo() {
+  return function (
+    _target: object,
+    methodName: string,
+    descriptor: PropertyDescriptor,
+  ): PropertyDescriptor {
+    const originalMethod = descriptor.value as (...args: unknown[]) => unknown;
+    descriptor.value = function (this: object, ...args: unknown[]) {
+      const argKey = serializeArgs(args);
+      const memoized = getCache(this, methodName, argKey, () =>
+        originalMethod.apply(this, args),
+      );
+      return memoized();
+    };
+    return descriptor;
+  };
+}

package/src/functions/once.ts

@@ -0,0 +1,22 @@
+export function Once() {
+  const called = new WeakMap<object, boolean>();
+  const results = new WeakMap<object, unknown>();
+
+  return function (
+    _target: object,
+    _methodKey: string,
+    descriptor: PropertyDescriptor,
+  ): PropertyDescriptor {
+    const originalMethod = descriptor.value as (...args: unknown[]) => unknown;
+
+    descriptor.value = function (this: object, ...args: unknown[]) {
+      if (called.get(this)) return results.get(this);
+      const result = originalMethod.apply(this, args);
+      called.set(this, true);
+      results.set(this, result);
+      return result;
+    };
+
+    return descriptor;
+  };
+}