@praxisjs/decorators 1.7.0 → 2.0.1

package/dist/shared-method.js

@@ -0,0 +1,87 @@
+// Replacements installed through sharedMethod, and the ones an outer decorator wrapped again. Only
+// read while decorating and while building the first instance of a class.
+const shared = new WeakSet();
+const superseded = new WeakSet();
+function isPrototype(object) {
+    // Class prototypes own their `constructor`; instances inherit it.
+    return Object.hasOwn(object, "constructor");
+}
+function ownerOf(object, name) {
+    let owner = object;
+    while (owner !== null && !Object.hasOwn(owner, name))
+        owner = Object.getPrototypeOf(owner);
+    return owner;
+}
+function defineOwnMethod(object, name, value) {
+    Object.defineProperty(object, name, { value, configurable: true, writable: true });
+}
+/**
+ * Returns `method`, the decorator's replacement for `value`, set up so that reading it from an
+ * instance returns it bound to that instance, the same function on every read: detached calls
+ * (`onClick={this.save}`) keep working. `method` is shared by every instance and keeps any
+ * per-instance state in symbol slots.
+ *
+ * Rather than defining a bound wrapper on each instance as it is built, the first instance turns
+ * the method's prototype entry into an accessor: an instance pays for its bound copy only when the
+ * method is first read from it, and nothing if it never is.
+ */
+export function sharedMethod(context, value, method = value) {
+    if (value === method) {
+        // @Bind over a decorator that already binds: nothing left to do.
+        if (shared.has(method))
+            return method;
+    }
+    else {
+        // The inner decorator's replacement now only runs through this one, which does the binding.
+        superseded.add(value);
+    }
+    shared.add(method);
+    // `this.#method` can't be read detached through a property, so there is nothing to bind.
+    if (context.private)
+        return method;
+    const name = context.name;
+    let installed = false;
+    let home;
+    const accessor = {
+        configurable: true,
+        enumerable: false,
+        get() {
+            // Read from a prototype, or through `super.method()` from a subclass override: caching a
+            // bound copy on the instance would then shadow the override. Read with no receiver at all,
+            // as `vi.spyOn(instance, name)` does with a getter it finds on the prototype: the spy then
+            // wraps the method itself, which takes `this` from each call.
+            if (this == null || isPrototype(this) || ownerOf(this, name) !== home)
+                return method;
+            const bound = method.bind(this);
+            defineOwnMethod(this, name, bound);
+            return bound;
+        },
+        set(next) {
+            defineOwnMethod(this, name, next);
+        },
+    };
+    context.addInitializer(function () {
+        if (installed)
+            return;
+        const target = this;
+        if (superseded.has(method)) {
+            installed = true;
+            return;
+        }
+        if (!context.static) {
+            for (let proto = Object.getPrototypeOf(target); proto !== null; proto = Object.getPrototypeOf(proto)) {
+                if (Object.getOwnPropertyDescriptor(proto, name)?.value === method) {
+                    installed = true;
+                    home = proto;
+                    Object.defineProperty(proto, name, accessor);
+                    return;
+                }
+            }
+        }
+        // A static method (bound to its class, as before), or a decorator applied by hand whose
+        // replacement never reached a prototype: bind it on the object itself.
+        defineOwnMethod(target, name, method.bind(target));
+    });
+    return method;
+}
+//# sourceMappingURL=shared-method.js.map

package/dist/shared-method.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-method.js","sourceRoot":"","sources":["../src/shared-method.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@praxisjs/decorators",
-  "version": "1.7.0",
+  "version": "2.0.1",
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -10,16 +11,24 @@
       "types": "./dist/index.d.ts"
     }
   },
+  "files": [
+    "dist",
+    "src",
+    "!dist/**/__tests__",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
   "devDependencies": {
     "@types/node": "^25.9.1",
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@praxisjs/core": "2.2.0",
-    "@praxisjs/shared": "0.3.1"
+    "@praxisjs/core": "^2.3.1",
+    "@praxisjs/shared": "^0.3.2"
   },
   "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch"
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit"
   }
 }

package/src/component/component.ts

@@ -1,40 +1,21 @@
 import { StatelessComponent } from "@praxisjs/core";
-import type { RootComponent } from "@praxisjs/core/internal";
 import type {
   ComponentConstructor,
   ComponentInstance,
 } from "@praxisjs/shared/internal";
 
-import {
-  ClassBehavior,
-  createClassDecorator,
-  type ClassEnhancement,
-} from "../create-class-decorator";
-
-class ComponentBehavior extends ClassBehavior {
-  create(_instance: RootComponent): ClassEnhancement {
-    return {};
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  initialize(Enhanced: new (...args: any[]) => unknown, original: new (...args: any[]) => unknown): void {
-    const isStateless = (original.prototype as object) instanceof StatelessComponent;
-    Object.defineProperty(Enhanced, "__isComponent", { value: true, configurable: true });
-    Object.defineProperty(Enhanced, "__isStateless", { value: isStateless, configurable: true });
-  }
-}
-
-const behavior = new ComponentBehavior();
-
+// @Component only marks the class for the runtime. It adds no behavior, so it marks the class itself
+// instead of wrapping it in an enhanced subclass: every instance would otherwise pay for the
+// wrapper's per-instance object and per-render closure.
 export function Component() {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   return function <T extends new (...args: any[]) => ComponentInstance>(
     constructor: T,
-    context: ClassDecoratorContext,
+    _context: ClassDecoratorContext,
   ): T & ComponentConstructor {
-    return createClassDecorator(behavior)(
-      constructor as unknown as T & (new(...args: unknown[]) => RootComponent<Record<string, unknown>>),
-      context,
-    ) as unknown as T & ComponentConstructor;
+    const isStateless = (constructor.prototype as object) instanceof StatelessComponent;
+    Object.defineProperty(constructor, "__isComponent", { value: true, configurable: true });
+    Object.defineProperty(constructor, "__isStateless", { value: isStateless, configurable: true });
+    return constructor as T & ComponentConstructor;
   };
 }

package/src/component/lazy.ts

@@ -1,7 +1,9 @@
 import {
   getComponentAnchor,
+  readSignal,
   type RootComponent,
-  signal,
+  SignalNode,
+  writeSignal,
 } from "@praxisjs/core/internal";
 
 import { ClassBehavior, createClassDecorator, type ClassEnhancement } from "../create-class-decorator";
@@ -19,56 +21,64 @@ export interface LazyOptions {
   rootMargin?: string;
 }
 
-class LazyBehavior extends ClassBehavior {
-  constructor(private readonly options: LazyOptions) {
-    super();
-  }
+// One object per instance whose methods live on the prototype, instead of three closures.
+class LazyEnhancement implements ClassEnhancement {
+  private readonly visible = new SignalNode(false);
+  private observer: IntersectionObserver | undefined = undefined;
+
+  constructor(
+    private readonly instance: RootComponent,
+    private readonly options: LazyOptions,
+  ) {}
+
+  onMount(): void {
+    const el = getComponentAnchor(this.instance)?.parentElement ?? null;
+    if (!el) return;
+
+    if (!("IntersectionObserver" in window)) {
+      writeSignal(this.visible, true);
+      return;
+    }
 
-  create(instance: RootComponent): ClassEnhancement {
     const { placeholder = 200, root, rootMargin = "100px" } = this.options;
-    const visible = signal(false);
-    let observer: IntersectionObserver | undefined;
+    if (!this.visible.value) el.style.minHeight = `${String(placeholder)}px`;
 
-    return {
-      onMount() {
-        const el = getComponentAnchor(instance)?.parentElement ?? null;
-        if (!el) return;
+    const rootEl =
+      root === undefined || root === null ? null : root.current ?? null;
 
-        if (!("IntersectionObserver" in window)) {
-          visible.set(true);
-          return;
+    this.observer = new IntersectionObserver(
+      (entries) => {
+        if (entries[0]?.isIntersecting) {
+          writeSignal(this.visible, true);
+          el.style.minHeight = "";
+          this.observer?.disconnect();
         }
+      },
+      { root: rootEl, rootMargin },
+    );
 
-        if (!visible()) el.style.minHeight = `${String(placeholder)}px`;
-
-        const rootEl =
-          root === undefined || root === null ? null : root.current ?? null;
+    this.observer.observe(el);
+  }
 
-        observer = new IntersectionObserver(
-          (entries) => {
-            if (entries[0]?.isIntersecting) {
-              visible.set(true);
-              el.style.minHeight = "";
-              observer?.disconnect();
-            }
-          },
-          { root: rootEl, rootMargin },
-        );
+  onUnmount(): void {
+    this.observer?.disconnect();
+  }
 
-        observer.observe(el);
-      },
+  render(originalRender: () => Node | Node[] | null): Node | Node[] | null {
+    return (() => {
+      if (!readSignal(this.visible)) return null;
+      return originalRender();
+    }) as unknown as Node;
+  }
+}
 
-      onUnmount() {
-        observer?.disconnect();
-      },
+class LazyBehavior extends ClassBehavior {
+  constructor(private readonly options: LazyOptions) {
+    super();
+  }
 
-      render(originalRender) {
-        return (() => {
-          if (!visible()) return null;
-          return originalRender();
-        }) as unknown as Node;
-      },
-    };
+  create(instance: RootComponent): ClassEnhancement {
+    return new LazyEnhancement(instance, this.options);
   }
 }
 

package/src/create-class-decorator.ts

@@ -1,68 +1,127 @@
 import type { RootComponent } from "@praxisjs/core/internal";
 
+import { assertMemberKind } from "./field";
+
+type RenderResult = Node | Node[] | null;
+
 export interface ClassEnhancement {
   onMount?(): void;
   onUnmount?(): void;
-  render?(
-    originalRender: () => Node | Node[] | null,
-  ): Node | Node[] | null;
+  render?(originalRender: () => RenderResult): RenderResult;
 }
 
-export abstract class ClassBehavior {
-  abstract create(instance: RootComponent): ClassEnhancement;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyConstructor = new (...args: any[]) => unknown;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyComponent = RootComponent<Record<string, any>>;
+
+/**
+ * The behavior a class decorator adds. Every method is optional: hooks that take the instance
+ * (`onMount`, `onUnmount`, `render`) live on the behavior itself and allocate nothing per
+ * instance; `create` returns a per-instance `ClassEnhancement` when hooks need their own closures.
+ */
+export abstract class ClassBehavior<Instance extends object = AnyComponent> {
+  /** Names the decorator in error messages, e.g. `"@Analytics()"`. */
+  label?: string;
+
+  /** Runs once per instance, after its own constructor. */
+  create?(instance: Instance): ClassEnhancement;
+
+  /** Runs on every mount of each instance, after the class's own `onMount`. */
+  onMount?(instance: Instance): void;
+
+  /** Runs on every unmount of each instance, after the class's own `onUnmount`. */
+  onUnmount?(instance: Instance): void;
+
+  /** Wraps every render of each instance; `originalRender` renders the class's own output. */
+  render?(instance: Instance, originalRender: () => RenderResult): RenderResult;
 
   /**
    * 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;
+  initialize?(_Enhanced: AnyConstructor, _original: AnyConstructor): void;
 }
 
-// Tracks instances whose render is currently being called as `originalRender`
-// from within an enhancement. When set, the Enhanced render skips the
-// this._enh.render dispatch so stacked decorators (e.g. @Lazy + @Component)
-// don't re-enter the outermost enhancement recursively.
-const _originalRenderInProgress = new WeakSet();
+// Keyed by symbols so they can't collide with the component's own fields.
+const ENHANCEMENT: unique symbol = Symbol("praxis.classEnhancement");
+// Set on an instance while its render is being called as `originalRender` from within an
+// enhancement. While set, the Enhanced render skips the enhancement's render so stacked decorators
+// (e.g. @Lazy + another render-overriding decorator) don't re-enter the outermost one recursively.
+const IN_ORIGINAL_RENDER: unique symbol = Symbol("praxis.inOriginalRender");
+
+const NO_ENHANCEMENT: ClassEnhancement = Object.freeze({});
 
-export function createClassDecorator(behavior: ClassBehavior) {
+type Render = (...args: unknown[]) => RenderResult;
+
+interface EnhancedHost {
+  [ENHANCEMENT]: ClassEnhancement;
+  [IN_ORIGINAL_RENDER]?: boolean;
+}
+
+/**
+ * Builds a class decorator from a `ClassBehavior`. The class is extended by a subclass that runs
+ * the behavior's hooks; a behavior with only `initialize` leaves the class as it is.
+ */
+export function createClassDecorator<Instance extends object = AnyComponent>(behavior: ClassBehavior<Instance>) {
+  const label = behavior.label ?? "This class decorator";
   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,
-      );
+    T extends new (...args: any[]) => Instance,
+  >(constructor: T, context: ClassDecoratorContext): T {
+    assertMemberKind(context, "class", label);
+    const hasCreate = behavior.create !== undefined;
+    const sharedRender = behavior.render !== undefined;
+    if (!hasCreate && !sharedRender && behavior.onMount === undefined && behavior.onUnmount === undefined) {
+      behavior.initialize?.(constructor, constructor);
+      return constructor;
+    }
+
+    const original = (constructor.prototype as { render?: Render }).render;
+
+    const Enhanced = class extends (constructor as unknown as new (...args: unknown[]) => RootComponent) {
+      readonly [ENHANCEMENT]: ClassEnhancement = hasCreate
+        ? (behavior as Required<Pick<ClassBehavior<Instance>, "create">>).create(this as unknown as Instance)
+        : NO_ENHANCEMENT;
 
       onMount() {
         super.onMount?.();
-        this._enh.onMount?.();
+        behavior.onMount?.(this as unknown as Instance);
+        this[ENHANCEMENT].onMount?.();
       }
 
       onUnmount() {
         super.onUnmount?.();
-        this._enh.onUnmount?.();
+        behavior.onUnmount?.(this as unknown as Instance);
+        this[ENHANCEMENT].onUnmount?.();
       }
 
-      render(...args: unknown[]): Node | Node[] | null {
-        const originalRender = () => {
-          _originalRenderInProgress.add(this);
+      render(...args: unknown[]): RenderResult {
+        const render = original as Render;
+        const host = this as unknown as EnhancedHost;
+        const enhancement = host[ENHANCEMENT];
+        if ((!sharedRender && enhancement.render === undefined) || host[IN_ORIGINAL_RENDER] === true) {
+          return render.apply(this, args);
+        }
+        const renderOriginal = (): RenderResult => {
+          host[IN_ORIGINAL_RENDER] = true;
           try {
-            return (constructor.prototype as { render: (...a: unknown[]) => Node | Node[] | null }).render.apply(this, args);
+            return render.apply(this, args);
           } finally {
-            _originalRenderInProgress.delete(this);
+            host[IN_ORIGINAL_RENDER] = false;
           }
         };
-        if (this._enh.render && !_originalRenderInProgress.has(this)) {
-          return this._enh.render(originalRender);
-        }
-        return (constructor.prototype as { render: (...a: unknown[]) => Node | Node[] | null }).render.apply(this, args);
+        const inner =
+          enhancement.render === undefined
+            ? renderOriginal
+            : () => (enhancement as Required<ClassEnhancement>).render(renderOriginal);
+        if (!sharedRender) return inner();
+        return (behavior as Required<Pick<ClassBehavior<Instance>, "render">>).render(this as unknown as Instance, inner);
       }
     };
 
     // If the original class has no render, remove the wrapper so instances see `undefined`.
-    if (typeof (constructor.prototype as { render?: unknown }).render !== "function") {
+    if (typeof original !== "function") {
       delete (Enhanced.prototype as { render?: unknown }).render;
     }
 

package/src/create-field-decorator.ts

@@ -1,5 +1,8 @@
 import type { StatefulComponent } from "@praxisjs/core";
 
+import { addClaimableInitializer, assertFieldContext, describeValue, type FieldDecorator, type FieldHost } from "./field";
+import { addLifecycleHooks } from "./lifecycle";
+
 export interface FieldBinding {
   /** Replaces the decorated property. If absent, the original property is left untouched. */
   descriptor?: PropertyDescriptor;
@@ -9,58 +12,132 @@ export interface FieldBinding {
   onUnmount?: () => void;
 }
 
-export interface FieldBehavior<T = object> {
-  bind(
-    instance: T,
-    name: string,
-    initialValue: unknown,
-  ): FieldBinding;
+export interface FieldBehavior<T = object, Value = unknown> {
+  /** Names the decorator in error messages, e.g. `"@SessionValue()"`. */
+  label?: string;
+  /** Runs once per instance, while it is built. */
+  bind(instance: T, name: string, initialValue: Value): FieldBinding;
+}
+
+/**
+ * What a shared field decorator installs. `get` and `set` become one accessor pair shared by every
+ * instance (`this` is the instance), so per-instance state belongs in symbol slots on the instance,
+ * created in `init`.
+ */
+export interface FieldSetup<This = object, Value = unknown> {
+  get?(this: This): Value;
+  set?(this: This, value: Value): void;
+  /**
+   * Runs once per instance, before `get`/`set` are installed, with the field's initial value. A
+   * decorator stacked under this one has already installed its own property.
+   */
+  init?: (instance: This, initialValue: Value) => void;
+  onMount?: (instance: This) => void;
+  onUnmount?: (instance: This) => void;
+  /** Defaults to `true`, like a plain field. */
+  enumerable?: boolean;
 }
 
-export function createFieldDecorator<T = StatefulComponent>(behavior: FieldBehavior<T>) {
-  return function <This extends T, Value = unknown>(
-    _value: undefined,
-    context: ClassFieldDecoratorContext<This, Value>,
-  ): void {
-    context.addInitializer(function (this: unknown) {
-      const instance = this as This & StatefulComponent & Record<string, unknown>;
-      const name = context.name as string;
-      const initialValue = instance[name];
+export interface SharedFieldBehavior<Host = object, Value = unknown> {
+  /** Names the decorator in error messages, e.g. `"@Clamp()"`. */
+  label?: string;
+  /** Runs once per decorated field, when the class is defined. */
+  setup(name: string, context: ClassFieldDecoratorContext<Host, Value>): FieldSetup<Host, Value>;
+}
 
-      const { descriptor, additional, onMount, onUnmount } = behavior.bind(
-        instance as T,
-        name,
-        initialValue,
-      );
+const DEFAULT_LABEL = "This field decorator";
+
+function defineValue(instance: object, name: string, value: unknown): void {
+  Object.defineProperty(instance, name, { value, writable: true, enumerable: true, configurable: true });
+}
+
+function bindField<T, Value>(behavior: FieldBehavior<T, Value>): FieldDecorator<T, Value> {
+  const label = behavior.label ?? DEFAULT_LABEL;
+  return function (_value, context) {
+    assertFieldContext(context, label);
+    const name = context.name as string;
+    addClaimableInitializer(context, function (initialValue) {
+      const instance = this as unknown as T & object;
+      const binding: unknown = behavior.bind(instance, name, initialValue as Value);
+      if (typeof binding !== "object" || binding === null) {
+        throw new TypeError(`${label}: bind() must return an object (a FieldBinding), got ${describeValue(binding)}.`);
+      }
+      const { descriptor, additional, onMount, onUnmount } = binding as FieldBinding;
 
       if (descriptor) {
-        Reflect.deleteProperty(instance, name);
-        Object.defineProperty(instance, name, {
-          enumerable: true,
-          configurable: true,
-          ...descriptor,
-        });
+        // The descriptor is fresh from bind(), so defaults are filled in place rather than copied.
+        descriptor.enumerable ??= true;
+        descriptor.configurable ??= true;
+        Object.defineProperty(instance, name, descriptor);
+      } else if (!Object.hasOwn(instance, name)) {
+        // A binding without a descriptor keeps the plain field, which a claimed field has not got yet.
+        defineValue(instance, name, initialValue);
       }
 
-      for (const [key, desc] of Object.entries(additional ?? {})) {
-        Object.defineProperty(instance, key, {
-          configurable: true,
-          ...desc,
-        });
+      if (additional) {
+        for (const key in additional) {
+          const desc = additional[key];
+          desc.configurable ??= true;
+          Object.defineProperty(instance, key, desc);
+        }
       }
 
-      if (onMount ?? onUnmount) {
-        const prevMount = instance.onMount?.bind(instance);
-        const prevUnmount = instance.onUnmount?.bind(instance);
-        instance.onMount = () => {
-          prevMount?.();
-          onMount?.();
-        };
-        instance.onUnmount = () => {
-          prevUnmount?.();
-          onUnmount?.();
-        };
+      if (onMount ?? onUnmount) addLifecycleHooks(instance, onMount, onUnmount);
+    });
+  } as FieldDecorator<T, Value>;
+}
+
+function sharedFieldDecorator<Host, Value>(behavior: SharedFieldBehavior<Host, Value>): FieldDecorator<Host, Value> {
+  const label = behavior.label ?? DEFAULT_LABEL;
+  return function (_value, context) {
+    assertFieldContext(context, label);
+    const name = context.name as string;
+    const result: unknown = behavior.setup(name, context as ClassFieldDecoratorContext<Host, Value>);
+    if (typeof result !== "object" || result === null) {
+      throw new TypeError(`${label}: setup() must return an object (a FieldSetup), got ${describeValue(result)}.`);
+    }
+    const field = result as FieldSetup<Host, Value>;
+    const { init, onMount, onUnmount } = field;
+    const descriptor: PropertyDescriptor | undefined =
+      field.get === undefined && field.set === undefined
+        ? undefined
+        // eslint-disable-next-line @typescript-eslint/unbound-method -- installed as accessors, which call them with the instance as `this`
+        : { get: field.get, set: field.set, enumerable: field.enumerable ?? true, configurable: true };
+    const hooks = onMount !== undefined || onUnmount !== undefined;
+    addClaimableInitializer(context, function (value) {
+      const instance = this as unknown as Host & FieldHost;
+      init?.(instance, value as Value);
+      if (descriptor !== undefined) Object.defineProperty(instance, name, descriptor);
+      else if (!Object.hasOwn(instance, name)) defineValue(instance, name, value);
+      if (hooks) {
+        addLifecycleHooks(
+          instance,
+          onMount as ((instance: object) => void) | undefined,
+          onUnmount as ((instance: object) => void) | undefined,
+        );
       }
     });
-  };
+  } as FieldDecorator<Host, Value>;
+}
+
+/**
+ * Builds a field decorator.
+ *
+ * With `setup`, the recommended form, the decorator's accessors are created once per decorated
+ * field and shared by every instance, which keeps its state in symbol slots: building an instance
+ * allocates no closures and every instance keeps the same hidden class.
+ *
+ * With `bind`, a binding (descriptor, hooks, extra properties) is created for each instance, which
+ * suits decorators that wrap whatever property a decorator stacked under them installed.
+ */
+export function createFieldDecorator<Host = object, Value = unknown>(
+  behavior: SharedFieldBehavior<Host, Value>,
+): FieldDecorator<Host, Value>;
+export function createFieldDecorator<T = StatefulComponent, Value = unknown>(
+  behavior: FieldBehavior<T, Value>,
+): FieldDecorator<T, Value>;
+export function createFieldDecorator(
+  behavior: SharedFieldBehavior | FieldBehavior,
+): FieldDecorator<object> {
+  return "setup" in behavior ? sharedFieldDecorator(behavior) : bindField(behavior);
 }