@wirestate/lit 0.6.0 → 0.6.1

package/index.d.ts

@@ -1,14 +1,44 @@
 import { ReactiveElement, ReactiveControllerHost, ReactiveController } from '@lit/reactive-element';
-import { ServiceIdentifier, Container, Newable, InjectableDescriptor, SeedEntries } from '@wirestate/core';
+import { ServiceIdentifier, CommandType, CommandHandler, Event, EventType, EventHandler, QueryType, QueryHandler, Container, Newable, InjectableDescriptor, SeedEntries } from '@wirestate/core';
 import { ContextProvider, ContextConsumer } from '@lit/context';
-import { Callable } from '@wirestate/core/types/general';
 
+/**
+ * Represents any object with string or symbol keys.
+ *
+ * @group types
+ */
+type AnyObject = Record<string | symbol, any>;
+/**
+ * Represents a type that can be null.
+ *
+ * @group types
+ */
 type Optional<T> = T | null;
-type Maybe<T> = T | null | undefined;
+/**
+ * Represents a type that can be a value or a promise of that value.
+ *
+ * @group types
+ */
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Helper to extract the interface of a type.
+ *
+ * @group types
+ */
 type Interface<T> = {
     [K in keyof T]: T[K];
 };
+/**
+ * Return type for decorators.
+ *
+ * @group types
+ */
 type DecoratorReturn = void | any;
+/**
+ * Type helper to ensure that a decorated field matches the type being provided.
+ *
+ * @group types
+ */
 type FieldMustMatchProvidedType<Obj, Key extends PropertyKey, ProvidedType> = Obj extends Record<Key, infer ConsumingType> ? [ProvidedType] extends [ConsumingType] ? DecoratorReturn : {
     message: "provided type not assignable to consuming field";
     provided: ProvidedType;
@@ -19,30 +49,455 @@ type FieldMustMatchProvidedType<Obj, Key extends PropertyKey, ProvidedType> = Ob
     consuming: ConsumingType | undefined;
 } : DecoratorReturn;
 
-type InjectionDecorator<ValueType> = {
-    <C extends Interface<Omit<ReactiveElement, "renderRoot">>, V extends ValueType>(value: ClassAccessorDecoratorTarget<C, V>, context: ClassAccessorDecoratorContext<C, V>): void;
-    <K extends PropertyKey, Proto extends Interface<Omit<ReactiveElement, "renderRoot">>>(protoOrDescriptor: Proto, name?: K): FieldMustMatchProvidedType<Proto, K, ValueType>;
-};
+/**
+ * Type definition for the injection decorator.
+ *
+ * @group consumption
+ */
+interface InjectionDecorator<T> {
+    <C extends Interface<Omit<ReactiveElement, "renderRoot">>, V extends T>(value: ClassAccessorDecoratorTarget<C, V>, context: ClassAccessorDecoratorContext<C, V>): void;
+    <K extends PropertyKey, Proto extends Interface<Omit<ReactiveElement, "renderRoot">>>(protoOrDescriptor: Proto, name?: K): FieldMustMatchProvidedType<Proto, K, T>;
+}
+/**
+ * Options for the {@link injection} decorator.
+ *
+ * @group consumption
+ */
 interface InjectionOptions<T> {
+    /**
+     * The service identifier to inject from the IoC container.
+     */
     injectionId: ServiceIdentifier<T>;
-    subscribe?: boolean;
+    /**
+     * Whether to subscribe to changes in the context.
+     *
+     * If true, the property will be updated if the container in the context changes.
+     * False by default.
+     */
+    once?: boolean;
 }
-declare function injection<T>({ injectionId, subscribe }: InjectionOptions<T>): InjectionDecorator<T>;
+/**
+ * Decorator to inject a service from the IoC container into a Lit element property.
+ *
+ * @group consumption
+ *
+ * @param optionsOrInjectionId - injection options including the service identifier or the service identifier itself
+ * @returns injection decorator instance
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   @injection(MyService)
+ *   private myService!: MyService;
+ *
+ *   public render() {
+ *     return html`<div>${this.myService.getName()}</div>`;
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   @injection({ injectionId: MyService, once: true })
+ *   private myService!: MyService;
+ *
+ *   public render() {
+ *     return html`<div>${this.myService.getName()}</div>`;
+ *   }
+ * }
+ * ```
+ */
+declare function injection<T>(optionsOrInjectionId: InjectionOptions<T> | ServiceIdentifier<T>): InjectionDecorator<T>;
 
+/**
+ * Options for the {@link useInjection} hook.
+ *
+ * @group consumption
+ */
 interface UseInjectionOptions<T> {
+    /**
+     * If true, the service will be fetched only once when the controller is created.
+     * If false (default), it will update if the container in the context changes.
+     */
     once?: boolean;
+    /**
+     * Initial value for the injection before it's fetched from the container.
+     */
     value?: Optional<T>;
+    /**
+     * The service identifier to inject.
+     */
     injectionId: ServiceIdentifier<T>;
 }
+/**
+ * The return value of the {@link useInjection} hook, containing the injected service.
+ *
+ * @group consumption
+ */
 interface UseInjectionValue<T> {
+    /**
+     * The service identifier used for injection.
+     */
     injectionId: ServiceIdentifier<T>;
+    /**
+     * The injected service instance.
+     */
     value: T;
 }
-declare function useInjection<T extends object, E extends ReactiveControllerHost & HTMLElement>(host: E, { once, injectionId, value }: UseInjectionOptions<T>): UseInjectionValue<T>;
+/**
+ * Hook (controller) to inject a service from the IoC container in a Lit component.
+ *
+ * @group consumption
+ *
+ * @param host - the host element
+ * @param optionsOrInjectionId - injection options including the service identifier or the service identifier itself
+ * @returns injection descriptor object
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   private myService = useInjection(this, MyService);
+ *
+ *   render() {
+ *     return html`<div>${this.myService.value.getName()}</div>`;
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   private myService = useInjection(this, { injectionId: MyService, once: true });
+ *
+ *   render() {
+ *     return html`<div>${this.myService.value.getName()}</div>`;
+ *   }
+ * }
+ * ```
+ */
+declare function useInjection<T extends object, E extends ReactiveControllerHost & HTMLElement>(host: E, optionsOrInjectionId: UseInjectionOptions<T> | ServiceIdentifier<T>): UseInjectionValue<T>;
+
+/**
+ * Interface for the {@link onCommand} decorator.
+ *
+ * Supports both standard (TC39) and legacy experimental decorators.
+ *
+ * @group commands
+ */
+interface OnCommandDecorator<D = unknown, R = unknown> {
+    <This extends Interface<Omit<ReactiveElement, "renderRoot">>>(value: (this: This, data: D) => MaybePromise<R>, context: ClassMethodDecoratorContext<This>): void;
+    (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+}
+/**
+ * Decorator that registers a Lit element method as a command handler for the given type.
+ *
+ * The handler is registered when the host element connects to the DOM and unregistered when it disconnects.
+ *
+ * @group commands
+ *
+ * @param type - the command type to handle
+ * @returns the decorator function.
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   @onCommand("SAVE")
+ *   private handleSave(data: SomeData): void {
+ *     // handle command
+ *   }
+ * }
+ * ```
+ */
+declare function onCommand<D = unknown, R = unknown>(type: CommandType): OnCommandDecorator<D, R>;
+
+/**
+ * Reactive controller that registers a command handler on the {@link CommandBus} for the host element's lifetime.
+ *
+ * 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.
+ *
+ * @group commands
+ */
+declare class OnCommandController<D = unknown, R = unknown> implements ReactiveController {
+    private bus;
+    private unregister;
+    private readonly type;
+    private readonly handler;
+    /**
+     * @param host - The host element.
+     * @param type - The command type to handle.
+     * @param handler - The command handler function.
+     */
+    constructor(host: ReactiveElement, type: CommandType, handler: CommandHandler<D, R>);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    private reregister;
+    private cleanup;
+}
+
+/**
+ * Options for the {@link useOnCommand} hook.
+ *
+ * @group commands
+ */
+interface UseOnCommandOptions<D = unknown, R = unknown> {
+    /**
+     * The command type to listen for.
+     */
+    type: CommandType;
+    /**
+     * The command handler function.
+     */
+    handler: CommandHandler<D, R>;
+}
+/**
+ * Registers a command handler on the CommandBus for the host element's lifetime.
+ *
+ * @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
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   private onSave = useOnCommand(this, {
+ *     type: "SAVE",
+ *     handler: (data) => console.log("Saving:", data),
+ *   });
+ * }
+ * ```
+ */
+declare function useOnCommand<D = unknown, R = unknown>(host: ReactiveElement, { type, handler }: UseOnCommandOptions<D, R>): OnCommandController<D, R>;
+
+/**
+ * Type definition for the on-event decorator.
+ *
+ * @group events
+ */
+interface OnEventDecorator<E extends Event = Event> {
+    <This extends Interface<Omit<ReactiveElement, "renderRoot">>>(value: (this: This, event: E) => void, context: ClassMethodDecoratorContext<This>): void;
+    (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+}
+/**
+ * Decorator to handle events from the event bus.
+ *
+ * @group events
+ *
+ * @param types - Event types to listen for. If omitted, all events will be handled.
+ * @returns The decorator function.
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   @onEvent()
+ *   private onMyEvent(event: Event) {
+ *     console.log('Event received:', event);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   @onEvent('MY_EVENT_TYPE')
+ *   private onMyEvent(event: MyEvent) {
+ *     console.log('Event received:', event);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   @onEvent(['MY_EVENT_TYPE_1', 'MY_EVENT_TYPE_2'])
+ *   private onMyEvent(event: Event) {
+ *     console.log('Event received:', event);
+ *   }
+ * }
+ * ```
+ */
+declare function onEvent<E extends Event = Event>(types?: EventType | ReadonlyArray<EventType>): OnEventDecorator<E>;
+
+/**
+ * Controller that subscribes to events from the event bus.
+ *
+ * It automatically handles subscription and unsubscription based on the host element's lifecycle.
+ *
+ * @group events
+ */
+declare class OnEventController<E extends Event = Event> implements ReactiveController {
+    private bus;
+    private unsubscriber;
+    private readonly types;
+    private readonly handler;
+    /**
+     * @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
+     */
+    constructor(host: ReactiveElement, types: Optional<ReadonlyArray<EventType>>, handler: EventHandler<E>);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    private resubscribe;
+    private cleanup;
+}
+
+/**
+ * Options for the {@link useOnEvents} hook.
+ *
+ * @group events
+ */
+interface UseOnEventsOptions<E extends Event = Event> {
+    /**
+     * Event handler function.
+     */
+    handler: EventHandler<E>;
+    /**
+     * Event types to listen for. If null or undefined, all events will be handled.
+     */
+    types?: Optional<EventType | ReadonlyArray<EventType>>;
+}
+/**
+ * Hook (controller) to handle events from the event bus.
+ *
+ * @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
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   private eventHandler = useOnEvents(this, {
+ *     handler: (event) => console.log(event),
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   private eventHandler = useOnEvents(this, {
+ *     types: [MyEvent],
+ *     handler: (event) => console.log(event),
+ *   });
+ * }
+ * ```
+ */
+declare function useOnEvents<E extends Event = Event>(host: ReactiveElement, { types, handler }: UseOnEventsOptions): OnEventController<E>;
+
+/**
+ * Interface for the {@link onQuery} decorator.
+ *
+ * Supports both standard (TC39) and legacy experimental decorators.
+ *
+ * @group queries
+ */
+interface OnQueryDecorator<D = unknown, R = unknown> {
+    <This extends Interface<Omit<ReactiveElement, "renderRoot">>>(value: (this: This, data: D) => MaybePromise<R>, context: ClassMethodDecoratorContext<This>): void;
+    (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+}
+/**
+ * Decorator that registers a Lit element method as a query handler for the given type.
+ *
+ * The handler is registered when the host element connects to the DOM and unregistered when it disconnects.
+ *
+ * @group queries
+ *
+ * @param type - the query type to handle
+ * @returns the decorator function
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   @onQuery("GET_USER_NAME")
+ *   public onGetUserName(data: QueryData) {
+ *     return "Alice";
+ *   }
+ * }
+ * ```
+ */
+declare function onQuery<D = unknown, R = unknown>(type: QueryType): OnQueryDecorator<D, R>;
 
+/**
+ * Reactive controller that registers a query handler on the {@link QueryBus} for the host element's lifetime.
+ *
+ * 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.
+ *
+ * @group queries
+ */
+declare class OnQueryController<D = unknown, R = unknown> implements ReactiveController {
+    private bus;
+    private unregister;
+    private readonly type;
+    private readonly handler;
+    /**
+     * @param host - the host element
+     * @param type - the query type to handle
+     * @param handler - the query handler function
+     */
+    constructor(host: ReactiveElement, type: QueryType, handler: QueryHandler<D, R>);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    private reregister;
+    private cleanup;
+}
+
+/**
+ * Options for the {@link useOnQuery} hook.
+ *
+ * @group queries
+ */
+interface UseOnQueryOptions<D = unknown, R = unknown> {
+    /**
+     * The query type to handle.
+     */
+    type: QueryType;
+    /**
+     * The query handler function.
+     */
+    handler: QueryHandler<D, R>;
+}
+/**
+ * Registers a query handler on the {@link QueryBus} for the host element's lifetime.
+ *
+ * @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
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   private getUserController = useOnQuery(this, {
+ *     type: "GET_USER",
+ *     handler: (data) => ({ name: "Alice" }),
+ *   });
+ * }
+ * ```
+ */
+declare function useOnQuery<D = unknown, R = unknown>(host: ReactiveElement, { type, handler }: UseOnQueryOptions<D, R>): OnQueryController<D, R>;
+
+/**
+ * Interface for the IoC context value.
+ *
+ * @group context
+ */
 interface IocContext {
     /**
-     * Inversify container.
+     * The Inversify IoC container.
      */
     readonly container: Container;
     /**
@@ -50,47 +505,266 @@ interface IocContext {
      */
     readonly revision: number;
     /**
-     * Forces a revision update.
+     * Function to force a revision update.
      */
     readonly nextRevision: () => number;
 }
+/**
+ * Lit context for providing and consuming the IoC container.
+ *
+ * @group context
+ */
 declare const ContainerContext: {
     __context__: IocContext;
 };
 
-declare class ContainerProviderController implements ReactiveController {
+/**
+ * Options for the {@link IocProviderController}.
+ *
+ * @group provision
+ */
+interface IocProviderControllerOptions {
+    /**
+     * Optional existing container to use. If not provided, a new one will be created.
+     */
+    container?: Container;
+    /**
+     * Optional seed data to apply to the container.
+     */
+    seed?: AnyObject;
+}
+/**
+ * Controller that provides an IoC container context to the host element and its children.
+ *
+ * It manages the lifecycle of the container and handles revision updates to notify consumers.
+ *
+ * @group provision
+ */
+declare class IocProviderController<E extends ReactiveControllerHost & HTMLElement = ReactiveControllerHost & HTMLElement> implements ReactiveController {
     private readonly host;
-    protected provider: ContextProvider<typeof ContainerContext>;
+    protected readonly provider: ContextProvider<typeof ContainerContext>;
+    protected readonly seed?: AnyObject;
     protected revision: number;
+    /**
+     * The managed Inversify IoC container.
+     */
     container: Container;
-    constructor(host: ReactiveControllerHost & HTMLElement, container?: Maybe<Container>);
+    /**
+     * @returns current {@link IocContext} value served to child consumers
+     */
+    get value(): IocContext;
+    /**
+     * @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
+     */
+    constructor(host: E, { container, seed }?: IocProviderControllerOptions);
     hostConnected(): void;
     hostDisconnected(): void;
     nextRevision(): number;
 }
 
-interface ServicesProviderControllerOptions {
+/**
+ * Type definition for the ioc-provide decorator.
+ *
+ * @group provision
+ */
+interface IocProviderDecorator<E extends ReactiveElement = ReactiveElement> {
+    <C extends Interface<Omit<ReactiveElement, "renderRoot">>, V extends IocProviderController<E>>(value: ClassAccessorDecoratorTarget<C, V>, context: ClassAccessorDecoratorContext<C, V>): void;
+    <K extends PropertyKey, Proto extends Interface<Omit<ReactiveElement, "renderRoot">>>(protoOrDescriptor: Proto, name?: K): FieldMustMatchProvidedType<Proto, K, IocProviderController<E>>;
+}
+/**
+ * Decorator to provide an IoC container to child components.
+ *
+ * @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
+ *
+ * @example
+ * ```typescript
+ * class MyRootElement extends LitElement {
+ *   @iocProvide({ seed: { someData: 'value' } })
+ *   private ioc!: IocProviderController;
+ * }
+ * ```
+ */
+declare function iocProvide<E extends ReactiveElement>({ container, seed, }?: IocProviderControllerOptions): IocProviderDecorator<E>;
+
+/**
+ * @group general-types
+ */
+type Callable<T> = () => T;
+
+/**
+ * Options for the {@link InjectablesProviderController}.
+ *
+ * @group provision
+ */
+interface InjectablesProviderControllerOptions {
+    /**
+     * List of service entries to bind to the container.
+     */
     entries: ReadonlyArray<Newable<object> | InjectableDescriptor>;
-    into?: IocContext | (() => IocContext);
+    /**
+     * Target IoC context to bind injectables into.
+     * If not provided, uses the context from the nearest provider.
+     * Accepts a static {@link IocContext} reference or a resolver function.
+     */
+    into?: IocContext | Callable<IocContext>;
+    /**
+     * List of service identifiers to activate (get from container) immediately after binding.
+     */
     activate?: ReadonlyArray<ServiceIdentifier>;
+    /**
+     * Seed data to apply to the container before binding.
+     * Applied before entries are bound so that `@Inject(SEEDS_TOKEN)` works during activation.
+     */
     seeds?: SeedEntries;
 }
-declare class ServicesProviderController<E extends ReactiveControllerHost & HTMLElement> implements ReactiveController {
+/**
+ * Controller that binds a set of injectables to an IoC container when the host connects
+ * and unbinds them when the host disconnects.
+ *
+ * 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.
+ *
+ * @group provision
+ *
+ * @example
+ * ```typescript
+ * class MyComponent extends LitElement {
+ *   private services = new InjectablesProviderController(this, {
+ *     entries: [AuthService, UserService],
+ *     activate: [AuthService],
+ *     seeds: [[AuthService, { role: "admin" }]],
+ *   });
+ * }
+ * ```
+ */
+declare class InjectablesProviderController<E extends ReactiveControllerHost & HTMLElement = ReactiveControllerHost & HTMLElement> implements ReactiveController {
     private readonly host;
-    readonly consumer: ContextConsumer<typeof ContainerContext, E>;
-    readonly entries: ReadonlyArray<Newable<object> | InjectableDescriptor>;
-    readonly activate: Maybe<ReadonlyArray<ServiceIdentifier>>;
-    readonly seeds: Maybe<SeedEntries>;
-    readonly into: Maybe<IocContext | Callable<IocContext>>;
-    constructor(host: E, options: ServicesProviderControllerOptions);
+    protected readonly consumer?: ContextConsumer<typeof ContainerContext, E>;
+    private readonly entries;
+    private readonly activate;
+    private readonly seeds;
+    private readonly into;
+    /**
+     * Tracks the context to which entries are currently bound, for correct cleanup on disconnect.
+     */
+    private boundContext;
+    /**
+     * @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
+     */
+    constructor(host: E, options: InjectablesProviderControllerOptions);
     hostConnected(): void;
     hostDisconnected(): void;
+    private bind;
+    private unbind;
+}
+
+/**
+ * Type for the {@link injectablesProvide} decorator.
+ *
+ * Supports both standard (TC39) and legacy experimental decorators.
+ *
+ * @group provision
+ */
+interface InjectablesProviderDecorator<T extends ReactiveElement = ReactiveElement> {
+    <C extends Interface<Omit<ReactiveElement, "renderRoot">>, V extends InjectablesProviderController<T>>(value: ClassAccessorDecoratorTarget<C, V>, context: ClassAccessorDecoratorContext<C, V>): void;
+    <K extends PropertyKey, Proto extends Interface<Omit<ReactiveElement, "renderRoot">>>(protoOrDescriptor: Proto, name?: K): FieldMustMatchProvidedType<Proto, K, InjectablesProviderController<T>>;
 }
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * class MyComponent extends LitElement {
+ *   @injectablesProvide({ entries: [AuthService, UserService], activate: [AuthService] })
+ *   public services!: InjectablesProviderController<MyComponent>;
+ * }
+ * ```
+ */
+declare function injectablesProvide<E extends ReactiveElement = ReactiveElement>(options: InjectablesProviderControllerOptions): InjectablesProviderDecorator<E>;
 
-interface UseContainerProvisionOptions {
+/**
+ * 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.
+ *
+ * @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
+ *
+ * @example
+ * ```typescript
+ * class MyComponent extends LitElement {
+ *   private services = useInjectablesProvider(this, {
+ *     entries: [AuthService, UserService],
+ *     activate: [AuthService],
+ *   });
+ * }
+ * ```
+ */
+declare function useInjectablesProvider<E extends ReactiveControllerHost & HTMLElement>(host: E, options: InjectablesProviderControllerOptions): InjectablesProviderController<E>;
+
+/**
+ * Options for the {@link useIocProvision} hook.
+ *
+ * @group provision
+ */
+interface UseIocProvisionOptions {
+    /**
+     * Optional existing container to use.
+     */
     container?: Container;
+    /**
+     * Optional seed data to apply to the container.
+     */
+    seed?: AnyObject;
 }
-declare function useContainerProvision<E extends ReactiveControllerHost & HTMLElement>(host: E, { container }: UseContainerProvisionOptions): UseContainerProvisionOptions;
+/**
+ * Hook (controller) to provide an IoC container to the host element and its children.
+ *
+ * @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
+ *
+ * @example
+ * ```typescript
+ * class MyRootElement extends LitElement {
+ *   private ioc = useIocProvision(this, { seed: { initialData: '...' } });
+ * }
+ * ```
+ */
+declare function useIocProvision<E extends ReactiveControllerHost & HTMLElement>(host: E, options?: UseIocProvisionOptions): IocProviderController<E>;
 
-export { ContainerContext, ContainerProviderController, ServicesProviderController, injection, useContainerProvision, useInjection };
-export type { InjectionDecorator, UseInjectionOptions, UseInjectionValue };
+export { ContainerContext, InjectablesProviderController, IocProviderController, OnCommandController, OnEventController, OnQueryController, injectablesProvide, injection, iocProvide, onCommand, onEvent, onQuery, useInjectablesProvider, useInjection, useIocProvision, useOnCommand, useOnEvents, useOnQuery };
+export type { InjectablesProviderControllerOptions, InjectablesProviderDecorator, InjectionDecorator, InjectionOptions, IocProviderControllerOptions, IocProviderDecorator, OnCommandDecorator, OnEventDecorator, OnQueryDecorator, UseInjectionOptions, UseInjectionValue, UseIocProvisionOptions, UseOnCommandOptions, UseOnEventsOptions, UseOnQueryOptions };