@wirestate/lit 0.6.1 → 0.7.0-experimental.2

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");
+var CONTAINER_KEY = Symbol("ContainerContext");
 /**
- * Lit context for providing and consuming the IoC container.
+ * Lit context object for providing and consuming the container.
  *
- * @group context
+ * @group Context
  */
-var ContainerContext = context.createContext(IOC_CONTAINER_KEY);
+var ContainerContext = context.createContext(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
@@ -62,8 +62,8 @@ function injection(optionsOrInjectionId) {
         var _this = this;
         new context.ContextConsumer(this, {
           context: ContainerContext,
-          callback: function (it) {
-            protoOrTarget.set.call(_this, it.container.get(injectionId));
+          callback: function (container) {
+            protoOrTarget.set.call(_this, container.get(injectionId));
           },
           subscribe: !once
         });
@@ -73,8 +73,8 @@ function injection(optionsOrInjectionId) {
       protoOrTarget.constructor.addInitializer(function (element) {
         new context.ContextConsumer(element, {
           context: ContainerContext,
-          callback: function (it) {
-            element[nameOrContext] = it.container.get(injectionId);
+          callback: function (container) {
+            element[nameOrContext] = container.get(injectionId);
           },
           subscribe: !once
         });
@@ -84,13 +84,48 @@ function injection(optionsOrInjectionId) {
 }
 
 /**
- * Hook (controller) to inject a service from the IoC container in a Lit component.
+ * Hook (consumer) to access the active container from the nearest parent context.
  *
- * @group consumption
+ * @remarks
+ * The returned value updates when the nearest provided container changes.
  *
- * @param host - the host element
- * @param optionsOrInjectionId - injection options including the service identifier or the service identifier itself
- * @returns injection descriptor object
+ * @group Consumption
+ *
+ * @param host - The host element.
+ * @returns An instance of {@link UseContainerValue}.
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   private container: UseContainerValue = useContainer(this);
+ *
+ *   public render() {
+ *     return html`<div>${this.container.value.isBound(MyService)}</div>`;
+ *   }
+ * }
+ * ```
+ */
+function useContainer(host) {
+  var current = {
+    value: null
+  };
+  new context.ContextConsumer(host, {
+    context: ContainerContext,
+    callback: function (container) {
+      current.value = container;
+    }
+  });
+  return current;
+}
+
+/**
+ * Hook (controller) to inject a service from the IoC container.
+ *
+ * @group Consumption
+ *
+ * @param host - The host element.
+ * @param optionsOrInjectionId - Injection options or service identifier.
+ * @returns An instance of {@link UseInjectionValue}.
  *
  * @example
  * ```typescript
@@ -128,25 +163,64 @@ function useInjection(host, optionsOrInjectionId) {
   new context.ContextConsumer(host, {
     context: ContainerContext,
     subscribe: !once,
-    callback: function (it) {
-      current.value = it.container.get(injectionId);
+    callback: function (container) {
+      current.value = container.get(injectionId);
     }
   });
   return current;
 }
 
 /**
- * Reactive controller that registers a command handler on the {@link CommandBus} for the host element's lifetime.
+ * Hook (consumer) to access the active {@link WireScope} from the nearest parent context.
+ *
+ * @remarks
+ * The returned value updates when the nearest provided container changes.
  *
+ * @group Consumption
+ *
+ * @param host - The host element.
+ * @returns An instance of {@link UseScopeValue}.
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   private scope: UseScopeValue = useScope(this);
+ *
+ *   public connectedCallback(): void {
+ *     super.connectedCallback();
+ *     this.scope.value.emitEvent("UI_READY");
+ *   }
+ * }
+ * ```
+ */
+function useScope(host) {
+  var current = {
+    value: undefined,
+    injectionId: core.WireScope
+  };
+  new context.ContextConsumer(host, {
+    context: ContainerContext,
+    subscribe: true,
+    callback: function (container) {
+      current.value = container.get(core.WireScope);
+    }
+  });
+  return current;
+}
+
+/**
+ * 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) {
@@ -159,8 +233,8 @@ var OnCommandController = /** @class */function () {
     new context.ContextConsumer(host, {
       context: ContainerContext,
       subscribe: true,
-      callback: function (context) {
-        _this.bus = context.container.get(core.CommandBus);
+      callback: function (container) {
+        _this.bus = container.get(core.CommandBus);
         if (host.isConnected) {
           _this.reregister();
         }
@@ -188,20 +262,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 +304,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 +331,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;
@@ -278,8 +355,8 @@ var OnEventController = /** @class */function () {
     new context.ContextConsumer(host, {
       context: ContainerContext,
       subscribe: true,
-      callback: function (context) {
-        _this.bus = context.container.get(core.EventBus);
+      callback: function (container) {
+        _this.bus = container.get(core.EventBus);
         if (host.isConnected) {
           _this.resubscribe();
         }
@@ -316,19 +393,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 +416,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 +426,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 +456,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 +479,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 +495,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;
@@ -436,8 +517,8 @@ var OnQueryController = /** @class */function () {
     new context.ContextConsumer(host, {
       context: ContainerContext,
       subscribe: true,
-      callback: function (context) {
-        _this.bus = context.container.get(core.QueryBus);
+      callback: function (container) {
+        _this.bus = container.get(core.QueryBus);
         if (host.isConnected) {
           _this.reregister();
         }
@@ -465,20 +546,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 +588,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
@@ -532,110 +614,211 @@ function useOnQuery(host, _a) {
   return new OnQueryController(host, type, handler);
 }
 
+var ERROR_CODE_INVALID_ARGUMENTS = 2051;
+
 /**
- * Controller that provides an IoC container context to the host element and its children.
+ * Provider that exposes an IoC container context to the host element and its children.
+ *
+ * @remarks
+ * The provider supports two modes:
  *
- * It manages the lifecycle of the container and handles revision updates to notify consumers.
+ * - External mode: `container` is an existing {@link Container}. The
+ *   provider passes it through context and does not alter its lifecycle.
+ * - Managed mode: `options` is {@link CreateContainerOptions}. The provider
+ *   creates a container during construction without eager activation,
+ *   activates configured entries when the host connects, disposes the
+ *   container when the host disconnects, and recreates it on reconnect.
  *
- * @group provision
+ * @group Provision
  */
-var IocProviderController = /** @class */function () {
+var ContainerProvider = /** @class */function (_super) {
+  tslib.__extends(ContainerProvider, _super);
   /**
-   * @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 - External container instance to provide.
+   * @param options.options - Managed container creation options.
    */
-  function IocProviderController(host, _a) {
-    var _b = _a === void 0 ? {} : _a,
-      container = _b.container,
-      seed = _b.seed;
+  function ContainerProvider(host, options) {
     var _this = this;
-    this.host = host;
-    this.revision = 1;
-    this.host.addController(this);
-    this.container = container !== null && container !== void 0 ? container : core.createIocContainer();
-    this.seed = seed;
-    this.provider = new context.ContextProvider(host, {
+    if (!options.container && !options.options) {
+      throw new core.WirestateError(ERROR_CODE_INVALID_ARGUMENTS, "ContainerProvider requires a valid container instance or creation options.");
+    } else if (options.container && options.options) {
+      throw new core.WirestateError(ERROR_CODE_INVALID_ARGUMENTS, "ContainerProvider requires only container or valid options object to be provided.");
+    }
+    _this = _super.call(this, host, {
       context: ContainerContext,
-      initialValue: {
-        container: this.container,
-        revision: this.revision,
-        nextRevision: function () {
-          return _this.nextRevision();
+      initialValue: options.container ? options.container : core.createContainer(tslib.__assign(tslib.__assign({}, options.options), {
+        activate: []
+      }))
+    }) || this;
+    _this.destroyed = false;
+    _this.options = options.options;
+    return _this;
+  }
+  ContainerProvider.prototype.hostConnected = function () {
+    var _a;
+    if (this.options) {
+      if (this.destroyed) {
+        this.value = core.createContainer(this.options);
+        this.destroyed = false;
+      } else {
+        if ((_a = this.options) === null || _a === void 0 ? void 0 : _a.activate) {
+          for (var _i = 0, _b = this.options.activate; _i < _b.length; _i++) {
+            var entry = _b[_i];
+            this.value.get(entry);
+          }
         }
       }
-    });
-  }
-  Object.defineProperty(IocProviderController.prototype, "value", {
-    /**
-     * @returns current {@link IocContext} value served to child consumers
-     */
-    get: function () {
-      return this.provider.value;
-    },
-    enumerable: false,
-    configurable: true
-  });
-  IocProviderController.prototype.hostConnected = function () {
-    if (this.seed) {
-      core.applySharedSeed(this.container, this.seed);
     }
+    _super.prototype.hostConnected.call(this);
   };
-  IocProviderController.prototype.hostDisconnected = function () {};
-  IocProviderController.prototype.nextRevision = function () {
-    var _this = this;
-    this.revision += 1;
-    this.provider.setValue({
-      container: this.container,
-      revision: this.revision,
-      nextRevision: function () {
-        return _this.nextRevision();
+  ContainerProvider.prototype.hostDisconnected = function () {
+    if (this.options) {
+      this.value.unbindAll();
+      this.destroyed = true;
+    }
+  };
+  return ContainerProvider;
+}(context.ContextProvider);
+
+/**
+ * Provider that exposes a managed child container for the host element's lifetime.
+ *
+ * @remarks
+ * The provider always owns a child container derived from the nearest parent
+ * {@link ContainerContext}. When connected, it creates a child container using
+ * the latest parent context, provides it to descendants, destroys it when the
+ * host disconnects, and replaces it whenever the parent container changes.
+ *
+ * @group Provision
+ *
+ * @example
+ * ```typescript
+ * class MyComponent extends LitElement {
+ *   private container = new SubContainerProvider(this, {
+ *     options: {
+ *       entries: [AuthService, UserService],
+ *       activate: [AuthService],
+ *       seeds: [[AuthService, { role: "admin" }]],
+ *     },
+ *   });
+ * }
+ * ```
+ */
+var SubContainerProvider = /** @class */function (_super) {
+  tslib.__extends(SubContainerProvider, _super);
+  /**
+   * @param host - The host element.
+   * @param options - Provisioning options, including child entries, eager activations, and seeds.
+   */
+  function SubContainerProvider(host, options) {
+    var _this = _super.call(this, host, {
+      context: ContainerContext
+    }) || this;
+    _this.parent = null;
+    _this.destroyed = true;
+    _this.options = options.options;
+    _this.consumer = new context.ContextConsumer(host, {
+      context: ContainerContext,
+      subscribe: true,
+      callback: function (context) {
+        var previousParent = _this.parent;
+        _this.parent = context;
+        if (host.isConnected) {
+          if (_this.destroyed || !_this.value || previousParent !== context) {
+            _this.destroyContainer();
+            _this.createContainer();
+          }
+        }
       }
     });
-    return this.revision;
+    return _this;
+  }
+  SubContainerProvider.prototype.hostConnected = function () {
+    if (this.parent && (this.destroyed || !this.value)) {
+      this.destroyContainer();
+      this.createContainer();
+    }
+    _super.prototype.hostConnected.call(this);
   };
-  return IocProviderController;
-}();
+  SubContainerProvider.prototype.hostDisconnected = function () {
+    this.destroyContainer();
+  };
+  /**
+   * Replaces the currently provided child container with a new one derived
+   * from the latest parent context.
+   */
+  SubContainerProvider.prototype.createContainer = function () {
+    var container = core.createContainer(tslib.__assign(tslib.__assign({}, this.options), {
+      parent: this.parent
+    }));
+    this.destroyed = false;
+    this.value = container;
+  };
+  /**
+   * Destroys the currently provided child container.
+   */
+  SubContainerProvider.prototype.destroyContainer = function () {
+    if (this.value && !this.destroyed) {
+      this.value.unbindAll();
+      this.destroyed = true;
+    }
+  };
+  return SubContainerProvider;
+}(context.ContextProvider);
 
 /**
- * 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.
+ *
+ * - Pass `container` to expose an external container without taking
+ *   ownership.
+ * - Pass `options` to create a managed container during construction,
+ *   activate configured entries on connect, destroy it on disconnect, and
+ *   recreate it on reconnect.
  *
- * @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 - External container instance to provide.
+ * @param options.options - Managed container creation options.
+ * @returns An instance of {@link ContainerProviderDecorator}.
  *
  * @example
  * ```typescript
  * class MyRootElement extends LitElement {
- *   @iocProvide({ seed: { someData: 'value' } })
- *   private ioc!: IocProviderController;
+ *   @containerProvide({
+ *     options: {
+ *       seed: { someData: "value" },
+ *       entries: [LoggerService],
+ *     },
+ *   })
+ *   private containerProvider!: ContainerProvider;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * class MyRootElement extends LitElement {
+ *   @containerProvide({ container: container })
+ *   private containerProvider!: ContainerProvider;
  * }
  * ```
  */
-function iocProvide(_a) {
-  var _b = _a === void 0 ? {} : _a,
-    container = _b.container,
-    seed = _b.seed;
+function containerProvide(options) {
   return function (protoOrTarget, nameOrContext) {
     if (typeof nameOrContext === "object") {
       // Standard decorators:
       nameOrContext.addInitializer(function () {
-        protoOrTarget.set.call(this, new IocProviderController(this, {
-          container: container,
-          seed: seed
-        }));
+        protoOrTarget.set.call(this, new ContainerProvider(this, options));
       });
     } else {
       var controller_1;
       protoOrTarget.constructor.addInitializer(function (element) {
-        controller_1 = new IocProviderController(element, {
-          container: container,
-          seed: seed
-        });
+        controller_1 = new ContainerProvider(element, options);
       });
       return {
         get: function () {
@@ -649,158 +832,49 @@ 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.
+ * Decorator that provides a managed child container derived from the nearest
+ * parent container context.
  *
- * 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
+ * The child container is created from the current parent context when the host
+ * connects, destroyed when it disconnects, and recreated when the parent
+ * container changes.
  *
- * @group provision
+ * @group Provision
  *
- * @example
- * ```typescript
- * class MyComponent extends LitElement {
- *   private services = new InjectablesProviderController(this, {
- *     entries: [AuthService, UserService],
- *     activate: [AuthService],
- *     seeds: [[AuthService, { role: "admin" }]],
- *   });
- * }
- * ```
- */
-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
-   */
-  function InjectablesProviderController(host, options) {
-    var _this = this;
-    var _a, _b, _c;
-    this.host = host;
-    /**
-     * Tracks the context to which entries are currently bound, for correct cleanup on disconnect.
-     */
-    this.boundContext = null;
-    this.host.addController(this);
-    this.entries = options.entries;
-    this.activate = (_a = options.activate) !== null && _a !== void 0 ? _a : null;
-    this.seeds = (_b = options.seeds) !== null && _b !== void 0 ? _b : null;
-    this.into = (_c = options.into) !== null && _c !== void 0 ? _c : null;
-    if (!this.into) {
-      // subscribe: false — binding happens once per connect, not on every revision update.
-      this.consumer = new context.ContextConsumer(host, {
-        context: ContainerContext,
-        subscribe: false,
-        callback: function (context) {
-          if (!host.isConnected) {
-            return;
-          }
-          _this.bind(context);
-        }
-      });
-    }
-  }
-  InjectablesProviderController.prototype.hostConnected = function () {
-    var _a;
-    if (!this.into) {
-      // ContextConsumer with subscribe:false only invokes the user callback once (provided flag stays true
-      // after disconnect). On reconnect we fall back to the cached consumer.value so bind() still fires.
-      if ((_a = this.consumer) === null || _a === void 0 ? void 0 : _a.value) {
-        this.bind(this.consumer.value);
-      }
-      return;
-    }
-    var context = typeof this.into === "function" ? this.into() : this.into;
-    if (!context) {
-      throw new core.WirestateError(ERROR_CODE_INVALID_ARGUMENTS, "InjectablesProviderController: the 'into' option resolved to null or undefined. " + "Ensure the value or resolver function returns a valid IocContext.");
-    }
-    this.bind(context);
-  };
-  InjectablesProviderController.prototype.hostDisconnected = function () {
-    if (!this.boundContext) {
-      return;
-    }
-    this.unbind(this.boundContext);
-  };
-  InjectablesProviderController.prototype.bind = function (context) {
-    if (this.boundContext) {
-      // Re-binding without unbinding first would leave stale entries; unbind the previous context.
-      this.unbind(this.boundContext);
-    }
-    this.boundContext = context;
-    // Seeds must be applied before binding so @Inject(SEEDS_TOKEN) resolves during activation.
-    if (this.seeds) {
-      core.applySeeds(context.container, this.seeds);
-    }
-    for (var _i = 0, _a = this.entries; _i < _a.length; _i++) {
-      var entry = _a[_i];
-      core.bindEntry(context.container, entry);
-    }
-    if (this.activate) {
-      for (var _b = 0, _c = this.activate; _b < _c.length; _b++) {
-        var token = _c[_b];
-        context.container.get(token);
-      }
-    }
-  };
-  InjectablesProviderController.prototype.unbind = function (context) {
-    for (var _i = 0, _a = this.entries; _i < _a.length; _i++) {
-      var entry = _a[_i];
-      var token = core.getEntryToken(entry);
-      if (context.container.isBound(token)) {
-        context.container.unbind(token);
-      }
-    }
-    if (this.seeds) {
-      core.unapplySeeds(context.container, this.seeds);
-    }
-    this.boundContext = null;
-  };
-  return InjectablesProviderController;
-}();
-
-/**
- * Decorator that 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.
- * The decorated accessor or property holds the resulting {@link InjectablesProviderController} instance.
- *
- * @group provision
- *
- * @param options - provisioning options
- * @returns injectables provider decorator instance
+ * @param options - Provisioning options.
+ * @param options.options - Child-container creation options.
+ * @returns An instance of {@link SubContainerProviderDecorator}.
  *
  * @example
  * ```typescript
  * class MyComponent extends LitElement {
- *   @injectablesProvide({ entries: [AuthService, UserService], activate: [AuthService] })
- *   public services!: InjectablesProviderController<MyComponent>;
+ *   @subContainerProvide({
+ *     options: {
+ *       entries: [AuthService, UserService],
+ *       activate: [AuthService],
+ *     },
+ *   })
+ *   public containerProvider!: SubContainerProvider<MyComponent>;
  * }
  * ```
  */
-function injectablesProvide(options) {
+function subContainerProvide(options) {
   return function (protoOrTarget, nameOrContext) {
     if (typeof nameOrContext === "object") {
       // Standard decorators:
       nameOrContext.addInitializer(function () {
-        protoOrTarget.set.call(this, new InjectablesProviderController(this, options));
+        protoOrTarget.set.call(this, new SubContainerProvider(this, options));
       });
     } else {
-      var controller_1;
+      var provider_1;
       protoOrTarget.constructor.addInitializer(function (element) {
-        controller_1 = new InjectablesProviderController(element, options);
+        provider_1 = new SubContainerProvider(element, options);
       });
       return {
         get: function () {
-          return controller_1;
+          return provider_1;
         },
         set: function () {},
         configurable: true,
@@ -811,75 +885,93 @@ function injectablesProvide(options) {
 }
 
 /**
- * Binds a set of injectables to the nearest IoC container for the host element's lifetime.
+ * Hook that provides a container to the host element and its children.
  *
- * Entries are bound when the host connects and unbound when it disconnects.
+ * @remarks
+ * Pass `container` to expose an external `Container` without taking
+ * ownership. Pass `options` to create a managed container during
+ * construction, activate configured entries on connect, destroy it on
+ * disconnect, and recreate it on reconnect.
  *
- * @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.
+ * @param options.container - External container instance to provide.
+ * @param options.options - Managed container creation options.
+ * @returns An instance of {@link ContainerProvider}.
  *
  * @example
  * ```typescript
- * class MyComponent extends LitElement {
- *   private services = useInjectablesProvider(this, {
- *     entries: [AuthService, UserService],
- *     activate: [AuthService],
+ * class MyRootElement extends LitElement {
+ *   private containerProvider: ContainerProvider = useContainerProvision(this, {
+ *     options: {
+ *       entries: [LoggerService],
+ *       activate: [LoggerService],
+ *     },
  *   });
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * class MyRootElement extends LitElement {
+ *   private containerProvider: ContainerProvider = useContainerProvision(this, { container: container });
+ * }
+ * ```
  */
-function useInjectablesProvider(host, options) {
-  return new InjectablesProviderController(host, options);
+function useContainerProvision(host, options) {
+  return new ContainerProvider(host, options);
 }
 
 /**
- * Hook (controller) to provide an IoC container to the host element and its children.
+ * Hook that provides a managed child container for the host element's lifetime.
  *
- * @group provision
+ * @remarks
+ * The child container is derived from the current parent
+ * {@link ContainerContext}, recreated when that parent context changes, and
+ * destroyed when the host disconnects.
  *
- * @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
+ * @group Provision
+ *
+ * @param host - The host element.
+ * @param options - Provisioning options.
+ * @param options.options - Child-container creation options.
+ * @returns An instance of {@link SubContainerProvider}.
  *
  * @example
  * ```typescript
- * class MyRootElement extends LitElement {
- *   private ioc = useIocProvision(this, { seed: { initialData: '...' } });
+ * class MyComponent extends LitElement {
+ *   private containerProvider: SubContainerProvider = useSubContainerProvider(this, {
+ *     options: {
+ *       entries: [AuthService, UserService],
+ *     },
+ *   });
  * }
  * ```
  */
-function useIocProvision(host, options) {
-  if (options === void 0) {
-    options = {};
-  }
-  return new IocProviderController(host, options);
+function useSubContainerProvider(host, options) {
+  return new SubContainerProvider(host, options);
 }
 
 exports.ContainerContext = ContainerContext;
-exports.InjectablesProviderController = InjectablesProviderController;
-exports.IocProviderController = IocProviderController;
+exports.ContainerProvider = ContainerProvider;
 exports.OnCommandController = OnCommandController;
 exports.OnEventController = OnEventController;
 exports.OnQueryController = OnQueryController;
-exports.injectablesProvide = injectablesProvide;
+exports.SubContainerProvider = SubContainerProvider;
+exports.containerProvide = containerProvide;
 exports.injection = injection;
-exports.iocProvide = iocProvide;
 exports.onCommand = onCommand;
 exports.onEvent = onEvent;
 exports.onQuery = onQuery;
-exports.useInjectablesProvider = useInjectablesProvider;
+exports.subContainerProvide = subContainerProvide;
+exports.useContainer = useContainer;
+exports.useContainerProvision = useContainerProvision;
 exports.useInjection = useInjection;
-exports.useIocProvision = useIocProvision;
 exports.useOnCommand = useOnCommand;
 exports.useOnEvents = useOnEvents;
 exports.useOnQuery = useOnQuery;
+exports.useScope = useScope;
+exports.useSubContainerProvider = useSubContainerProvider;
 //# sourceMappingURL=index.js.map