@wirestate/lit 0.6.1 → 0.7.0-experimental.1

package/cjs/development/index.js

@@ -5,25 +5,25 @@ var core = require('@wirestate/core');
 var tslib = require('tslib');
 
 /**
- * Context key for the IoC container.
+ * Unique symbol used as a key for the IoC context.
  *
- * @group context
+ * @group Context
  */
 var IOC_CONTAINER_KEY = Symbol("ContainerContext");
 /**
- * Lit context for providing and consuming the IoC container.
+ * Lit context object for providing and consuming the IoC container.
  *
- * @group context
+ * @group Context
  */
-var ContainerContext = context.createContext(IOC_CONTAINER_KEY);
+var IocContextObject = context.createContext(IOC_CONTAINER_KEY);
 
 /**
  * Decorator to inject a service from the IoC container into a Lit element property.
  *
- * @group consumption
+ * @group Consumption
  *
- * @param optionsOrInjectionId - injection options including the service identifier or the service identifier itself
- * @returns injection decorator instance
+ * @param optionsOrInjectionId - Injection options or service identifier.
+ * @returns An instance of {@link InjectionDecorator}.
  *
  * @example
  * ```typescript
@@ -61,7 +61,7 @@ function injection(optionsOrInjectionId) {
       nameOrContext.addInitializer(function () {
         var _this = this;
         new context.ContextConsumer(this, {
-          context: ContainerContext,
+          context: IocContextObject,
           callback: function (it) {
             protoOrTarget.set.call(_this, it.container.get(injectionId));
           },
@@ -72,7 +72,7 @@ function injection(optionsOrInjectionId) {
       // Experimental decorators branch.
       protoOrTarget.constructor.addInitializer(function (element) {
         new context.ContextConsumer(element, {
-          context: ContainerContext,
+          context: IocContextObject,
           callback: function (it) {
             element[nameOrContext] = it.container.get(injectionId);
           },
@@ -84,13 +84,13 @@ function injection(optionsOrInjectionId) {
 }
 
 /**
- * Hook (controller) to inject a service from the IoC container in a Lit component.
+ * Hook (controller) to inject a service from the IoC container.
  *
- * @group consumption
+ * @group Consumption
  *
- * @param host - the host element
- * @param optionsOrInjectionId - injection options including the service identifier or the service identifier itself
- * @returns injection descriptor object
+ * @param host - The host element.
+ * @param optionsOrInjectionId - Injection options or service identifier.
+ * @returns An instance of {@link UseInjectionValue}.
  *
  * @example
  * ```typescript
@@ -126,7 +126,7 @@ function useInjection(host, optionsOrInjectionId) {
     injectionId: injectionId
   };
   new context.ContextConsumer(host, {
-    context: ContainerContext,
+    context: IocContextObject,
     subscribe: !once,
     callback: function (it) {
       current.value = it.container.get(injectionId);
@@ -136,17 +136,18 @@ function useInjection(host, optionsOrInjectionId) {
 }
 
 /**
- * Reactive controller that registers a command handler on the {@link CommandBus} for the host element's lifetime.
+ * Controller that registers a command handler for the host element's lifetime.
  *
+ * @remarks
  * The handler is registered when the host connects and unregistered when it disconnects.
- * When the IoC context is updated (container revision change), the handler is re-registered automatically.
+ * It automatically re-registers if the IoC container is updated.
  *
- * @group commands
+ * @group Commands
  */
 var OnCommandController = /** @class */function () {
   /**
    * @param host - The host element.
-   * @param type - The command type to handle.
+   * @param type - Unique identifier of the command to handle.
    * @param handler - The command handler function.
    */
   function OnCommandController(host, type, handler) {
@@ -157,7 +158,7 @@ var OnCommandController = /** @class */function () {
     this.type = type;
     this.handler = handler;
     new context.ContextConsumer(host, {
-      context: ContainerContext,
+      context: IocContextObject,
       subscribe: true,
       callback: function (context) {
         _this.bus = context.container.get(core.CommandBus);
@@ -188,20 +189,21 @@ var OnCommandController = /** @class */function () {
 }();
 
 /**
- * Decorator that registers a Lit element method as a command handler for the given type.
+ * Decorator for Lit element methods that handle a specific command.
  *
- * The handler is registered when the host element connects to the DOM and unregistered when it disconnects.
+ * @remarks
+ * The handler is registered when the host connects and unregistered when it disconnects.
  *
- * @group commands
+ * @group Commands
  *
- * @param type - the command type to handle
- * @returns the decorator function.
+ * @param type - Unique identifier of the command to handle.
+ * @returns A method decorator function.
  *
  * @example
  * ```typescript
  * class MyElement extends LitElement {
  *   @onCommand("SAVE")
- *   private handleSave(data: SomeData): void {
+ *   private onSave(data: SomeData): void {
  *     // handle command
  *   }
  * }
@@ -229,15 +231,15 @@ function onCommand(type) {
 }
 
 /**
- * Registers a command handler on the CommandBus for the host element's lifetime.
+ * Hook that registers a command handler for the host element's lifetime.
  *
- * @group commands
+ * @group Commands
  *
- * @param host - the host element
- * @param options - command handling options
- * @param options.type - the command type to listen for
- * @param options.handler - the command handler function
- * @returns the command controller instance
+ * @param host - The host element.
+ * @param options - Command handling options.
+ * @param options.type - The command type to listen for.
+ * @param options.handler - The command handler function.
+ * @returns The command controller instance.
  *
  * @example
  * ```typescript
@@ -256,17 +258,19 @@ function useOnCommand(host, _a) {
 }
 
 /**
- * Controller that subscribes to events from the event bus.
+ * Controller that subscribes to events for the host element's lifetime.
  *
- * It automatically handles subscription and unsubscription based on the host element's lifecycle.
+ * @remarks
+ * The handler is registered when the host connects and unregistered when it disconnects.
+ * It automatically re-subscribes if the IoC container is updated.
  *
- * @group events
+ * @group Events
  */
 var OnEventController = /** @class */function () {
   /**
-   * @param host - the host element
-   * @param types - event types to listen for, if null, all events will be handled
-   * @param handler - the event handler function
+   * @param host - The host element.
+   * @param types - Event types to listen for. If null, all events will be handled.
+   * @param handler - The event handler function.
    */
   function OnEventController(host, types, handler) {
     var _this = this;
@@ -276,7 +280,7 @@ var OnEventController = /** @class */function () {
     this.types = types;
     this.handler = handler;
     new context.ContextConsumer(host, {
-      context: ContainerContext,
+      context: IocContextObject,
       subscribe: true,
       callback: function (context) {
         _this.bus = context.container.get(core.EventBus);
@@ -316,19 +320,22 @@ var OnEventController = /** @class */function () {
 }();
 
 /**
- * Decorator to handle events from the event bus.
+ * Decorator for Lit element methods that handle events from the event bus.
  *
- * @group events
+ * @remarks
+ * The handler is registered when the host connects and unregistered when it disconnects.
+ *
+ * @group Events
  *
  * @param types - Event types to listen for. If omitted, all events will be handled.
- * @returns The decorator function.
+ * @returns A method decorator function.
  *
  * @example
  * ```typescript
  * class MyElement extends LitElement {
  *   @onEvent()
  *   private onMyEvent(event: Event) {
- *     console.log('Event received:', event);
+ *     console.log("Event received:", event);
  *   }
  * }
  * ```
@@ -336,9 +343,9 @@ var OnEventController = /** @class */function () {
  * @example
  * ```typescript
  * class MyElement extends LitElement {
- *   @onEvent('MY_EVENT_TYPE')
+ *   @onEvent("MY_EVENT_TYPE")
  *   private onMyEvent(event: MyEvent) {
- *     console.log('Event received:', event);
+ *     console.log("Event received:", event);
  *   }
  * }
  * ```
@@ -346,9 +353,9 @@ var OnEventController = /** @class */function () {
  * @example
  * ```typescript
  * class MyElement extends LitElement {
- *   @onEvent(['MY_EVENT_TYPE_1', 'MY_EVENT_TYPE_2'])
+ *   @onEvent(["MY_EVENT_TYPE_1", "MY_EVENT_TYPE_2"])
  *   private onMyEvent(event: Event) {
- *     console.log('Event received:', event);
+ *     console.log("Event received:", event);
  *   }
  * }
  * ```
@@ -376,15 +383,15 @@ function onEvent(types) {
 }
 
 /**
- * Hook (controller) to handle events from the event bus.
+ * Hook that subscribes to events for the host element's lifetime.
  *
- * @group events
+ * @group Events
  *
- * @param host - the host element
- * @param options - event handling options
- * @param options.handler - event handler function
- * @param options.types - event types to listen for, if null or undefined, all events will be handled
- * @returns events subscription controller
+ * @param host - The host element.
+ * @param options - Event handling options.
+ * @param options.handler - Event handler function.
+ * @param options.types - Event types to listen for, if null or undefined, all events will be handled.
+ * @returns An instance of {@link OnEventController}.
  *
  * @example
  * ```typescript
@@ -399,7 +406,7 @@ function onEvent(types) {
  * ```typescript
  * class MyElement extends LitElement {
  *   private eventHandler = useOnEvents(this, {
- *     types: [MyEvent],
+ *     types: ["MY_EVENT"],
  *     handler: (event) => console.log(event),
  *   });
  * }
@@ -415,16 +422,17 @@ function useOnEvents(host, _a) {
 /**
  * Reactive controller that registers a query handler on the {@link QueryBus} for the host element's lifetime.
  *
+ * @remarks
  * The handler is registered when the host connects and unregistered when it disconnects.
- * When the IoC context is updated (container revision change), the handler is re-registered automatically.
+ * It automatically re-registers if the IoC container is updated.
  *
- * @group queries
+ * @group Queries
  */
 var OnQueryController = /** @class */function () {
   /**
-   * @param host - the host element
-   * @param type - the query type to handle
-   * @param handler - the query handler function
+   * @param host - The host element.
+   * @param type - Unique identifier of the query to handle.
+   * @param handler - The query handler function.
    */
   function OnQueryController(host, type, handler) {
     var _this = this;
@@ -434,7 +442,7 @@ var OnQueryController = /** @class */function () {
     this.type = type;
     this.handler = handler;
     new context.ContextConsumer(host, {
-      context: ContainerContext,
+      context: IocContextObject,
       subscribe: true,
       callback: function (context) {
         _this.bus = context.container.get(core.QueryBus);
@@ -465,20 +473,21 @@ var OnQueryController = /** @class */function () {
 }();
 
 /**
- * Decorator that registers a Lit element method as a query handler for the given type.
+ * Decorator for Lit element methods that handle a specific query.
  *
- * The handler is registered when the host element connects to the DOM and unregistered when it disconnects.
+ * @remarks
+ * The handler is registered when the host connects and unregistered when it disconnects.
  *
- * @group queries
+ * @group Queries
  *
- * @param type - the query type to handle
- * @returns the decorator function
+ * @param type - Unique identifier of the query to handle.
+ * @returns A method decorator function.
  *
  * @example
  * ```typescript
  * class MyElement extends LitElement {
  *   @onQuery("GET_USER_NAME")
- *   public onGetUserName(data: QueryData) {
+ *   private onGetUserName(data: QueryData) {
  *     return "Alice";
  *   }
  * }
@@ -506,15 +515,15 @@ function onQuery(type) {
 }
 
 /**
- * Registers a query handler on the {@link QueryBus} for the host element's lifetime.
+ * Hook that registers a query handler for the host element's lifetime.
  *
- * @group queries
+ * @group Queries
  *
- * @param host - the host element
- * @param options - query handling options
- * @param options.type - the query type to handle
- * @param options.handler - the query handler function
- * @returns the query controller instance
+ * @param host - The host element.
+ * @param options - Query handling options.
+ * @param options.type - The query type to handle.
+ * @param options.handler - The query handler function.
+ * @returns An instance of {@link OnQueryController}.
  *
  * @example
  * ```typescript
@@ -535,16 +544,19 @@ function useOnQuery(host, _a) {
 /**
  * Controller that provides an IoC container context to the host element and its children.
  *
+ * @remarks
  * It manages the lifecycle of the container and handles revision updates to notify consumers.
+ * The container is created (or used from options) when the controller is instantiated.
+ * Seed data is applied when the host connects.
  *
- * @group provision
+ * @group Provision
  */
 var IocProviderController = /** @class */function () {
   /**
-   * @param host - the host element
-   * @param options - provisioning options
-   * @param options.container - optional existing container to use. If not provided, a new one will be created
-   * @param options.seed - optional seed data to apply to the container
+   * @param host - The host element.
+   * @param options - Provisioning options.
+   * @param options.container - Optional existing container to use. If not provided, a new one will be created.
+   * @param options.seed - Optional seed data to apply to the container.
    */
   function IocProviderController(host, _a) {
     var _b = _a === void 0 ? {} : _a,
@@ -554,10 +566,10 @@ var IocProviderController = /** @class */function () {
     this.host = host;
     this.revision = 1;
     this.host.addController(this);
-    this.container = container !== null && container !== void 0 ? container : core.createIocContainer();
+    this.container = container !== null && container !== void 0 ? container : core.createContainer();
     this.seed = seed;
     this.provider = new context.ContextProvider(host, {
-      context: ContainerContext,
+      context: IocContextObject,
       initialValue: {
         container: this.container,
         revision: this.revision,
@@ -569,7 +581,7 @@ var IocProviderController = /** @class */function () {
   }
   Object.defineProperty(IocProviderController.prototype, "value", {
     /**
-     * @returns current {@link IocContext} value served to child consumers
+     * @returns Current {@link IocContext} value served to child consumers.
      */
     get: function () {
       return this.provider.value;
@@ -599,19 +611,22 @@ var IocProviderController = /** @class */function () {
 }();
 
 /**
- * Decorator to provide an IoC container to child components.
+ * Decorator that provides an IoC container to child components.
+ *
+ * @remarks
+ * The container is provided via Lit context. It is created (or used from options) when the host connects.
  *
- * @group provision
+ * @group Provision
  *
- * @param options - provisioning options including container and seed data
- * @param options.container - optional existing container to use, if not provided, a new one will be created
- * @param options.seed - optional seed data to apply to the container
- * @returns IOC provision controller instance
+ * @param options - Provisioning options.
+ * @param options.container - Optional existing container to use, if not provided, a new one will be created.
+ * @param options.seed - Optional seed data to apply to the container.
+ * @returns An instance of {@link IocProviderDecorator}.
  *
  * @example
  * ```typescript
  * class MyRootElement extends LitElement {
- *   @iocProvide({ seed: { someData: 'value' } })
+ *   @iocProvide({ seed: { someData: "value" } })
  *   private ioc!: IocProviderController;
  * }
  * ```
@@ -652,14 +667,14 @@ function iocProvide(_a) {
 var ERROR_CODE_INVALID_ARGUMENTS = 2051;
 
 /**
- * Controller that binds a set of injectables to an IoC container when the host connects
- * and unbinds them when the host disconnects.
+ * Controller that binds injectables to an IoC container for the host element's lifetime.
  *
- * When no `into` context is provided, the controller uses the nearest {@link IocProviderController}
- * ancestor via Lit context. Seeds are applied before entries so that `@Inject(SEEDS_TOKEN)`
- * works during service activation.
+ * @remarks
+ * Entries are bound when the host connects and unbound when it disconnects.
+ * If no `into` context is provided, it uses the nearest {@link IocProviderController}.
+ * Seeds are applied before entries are bound.
  *
- * @group provision
+ * @group Provision
  *
  * @example
  * ```typescript
@@ -674,12 +689,12 @@ var ERROR_CODE_INVALID_ARGUMENTS = 2051;
  */
 var InjectablesProviderController = /** @class */function () {
   /**
-   * @param host - the host element
-   * @param options - provisioning options
-   * @param options.entries - list of service entries to bind to the container
-   * @param options.into - target IoC context; if omitted, uses the nearest provider context
-   * @param options.activate - list of service identifiers to activate immediately after binding
-   * @param options.seeds - seed data applied before binding
+   * @param host - The host element.
+   * @param options - Provisioning options.
+   * @param options.entries - List of service entries to bind to the container.
+   * @param options.into - Target IoC context; if omitted, uses the nearest provider context.
+   * @param options.activate - List of service identifiers to activate immediately after binding.
+   * @param options.seeds - Seed data applied before binding.
    */
   function InjectablesProviderController(host, options) {
     var _this = this;
@@ -697,7 +712,7 @@ var InjectablesProviderController = /** @class */function () {
     if (!this.into) {
       // subscribe: false — binding happens once per connect, not on every revision update.
       this.consumer = new context.ContextConsumer(host, {
-        context: ContainerContext,
+        context: IocContextObject,
         subscribe: false,
         callback: function (context) {
           if (!host.isConnected) {
@@ -770,19 +785,19 @@ var InjectablesProviderController = /** @class */function () {
 /**
  * Decorator that binds a set of injectables to the nearest IoC container for the host element's lifetime.
  *
+ * @remarks
  * Entries are bound when the host connects and unbound when it disconnects.
- * The decorated accessor or property holds the resulting {@link InjectablesProviderController} instance.
  *
- * @group provision
+ * @group Provision
  *
- * @param options - provisioning options
- * @returns injectables provider decorator instance
+ * @param options - Provisioning options.
+ * @returns An instance of {@link InjectablesProviderDecorator}.
  *
  * @example
  * ```typescript
  * class MyComponent extends LitElement {
  *   @injectablesProvide({ entries: [AuthService, UserService], activate: [AuthService] })
- *   public services!: InjectablesProviderController<MyComponent>;
+ *   public controller!: InjectablesProviderController<MyComponent>;
  * }
  * ```
  */
@@ -811,19 +826,13 @@ function injectablesProvide(options) {
 }
 
 /**
- * Binds a set of injectables to the nearest IoC container for the host element's lifetime.
- *
- * Entries are bound when the host connects and unbound when it disconnects.
+ * Hook that binds injectables to the nearest IoC container for the host element's lifetime.
  *
- * @group provision
+ * @group Provision
  *
- * @param host - the host element
- * @param options - provisioning options
- * @param options.entries - list of service entries to bind to the container
- * @param options.into - target IoC context; if omitted, uses the nearest provider context
- * @param options.activate - list of service identifiers to activate immediately after binding
- * @param options.seeds - seed data applied before binding
- * @returns the controller instance
+ * @param host - The host element.
+ * @param options - Provisioning options.
+ * @returns An instance of {@link InjectablesProviderController}.
  *
  * @example
  * ```typescript
@@ -840,20 +849,18 @@ function useInjectablesProvider(host, options) {
 }
 
 /**
- * Hook (controller) to provide an IoC container to the host element and its children.
+ * Hook that provides an IoC container to the host element and its children.
  *
- * @group provision
+ * @group Provision
  *
- * @param host - the host element
- * @param options - provisioning options
- * @param options.container - optional existing container to use
- * @param options.seed - optional seed data to apply to the container
- * @returns ioc provision controller instance
+ * @param host - The host element.
+ * @param options - Provisioning options.
+ * @returns An instance of {@link IocProviderController}.
  *
  * @example
  * ```typescript
  * class MyRootElement extends LitElement {
- *   private ioc = useIocProvision(this, { seed: { initialData: '...' } });
+ *   private ioc = useIocProvision(this, { seed: { initialData: "..." } });
  * }
  * ```
  */
@@ -864,8 +871,8 @@ function useIocProvision(host, options) {
   return new IocProviderController(host, options);
 }
 
-exports.ContainerContext = ContainerContext;
 exports.InjectablesProviderController = InjectablesProviderController;
+exports.IocContextObject = IocContextObject;
 exports.IocProviderController = IocProviderController;
 exports.OnCommandController = OnCommandController;
 exports.OnEventController = OnEventController;