@wirestate/lit 0.6.0 → 0.7.0-experimental.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';
 
+/**
+ * Any object with string or symbol keys.
+ *
+ * @group Types
+ */
+type AnyObject = Record<string | symbol, any>;
+/**
+ * Type that can be null.
+ *
+ * @group Types
+ */
 type Optional<T> = T | null;
-type Maybe<T> = T | null | undefined;
+/**
+ * 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;
+/**
+ * Ensures 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,476 @@ 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>;
-};
+/**
+ * Represents definition of the injection decorator.
+ *
+ * @remarks
+ * Supports both TC39 and legacy experimental decorators.
+ *
+ * @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>;
+}
+/**
+ * Represents options for the {@link injection} decorator.
+ *
+ * @group Consumption
+ */
 interface InjectionOptions<T> {
+    /**
+     * The service identifier to inject.
+     */
     injectionId: ServiceIdentifier<T>;
-    subscribe?: boolean;
+    /**
+     * Whether to subscribe to container changes.
+     *
+     * @remarks
+     * If true, the property will be updated if the container in the context changes.
+     * Defaults to false.
+     */
+    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 or service identifier.
+ * @returns An instance of {@link InjectionDecorator}.
+ *
+ * @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>;
 
+/**
+ * Represents options for the {@link useInjection} hook.
+ *
+ * @group Consumption
+ */
 interface UseInjectionOptions<T> {
+    /**
+     * Whether to subscribe to container changes.
+     *
+     * @remarks
+     * If true, the service will be fetched only once when the controller is created.
+     * Defaults to false.
+     */
     once?: boolean;
+    /**
+     * Initial value before the service is fetched.
+     */
     value?: Optional<T>;
+    /**
+     * The service identifier to inject.
+     */
     injectionId: ServiceIdentifier<T>;
 }
+/**
+ * Represents result of the {@link useInjection} hook.
+ *
+ * @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.
+ *
+ * @group Consumption
+ *
+ * @param host - The host element.
+ * @param optionsOrInjectionId - Injection options or service identifier.
+ * @returns An instance of {@link UseInjectionValue}.
+ *
+ * @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>;
+
+/**
+ * Represents interface for the {@link onCommand} decorator.
+ *
+ * @remarks
+ * Supports both 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 for Lit element methods that handle a specific command.
+ *
+ * @remarks
+ * The handler is registered when the host connects and unregistered when it disconnects.
+ *
+ * @group Commands
+ *
+ * @param type - Unique identifier of the command to handle.
+ * @returns A method decorator function.
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   @onCommand("SAVE")
+ *   private onSave(data: SomeData): void {
+ *     // handle command
+ *   }
+ * }
+ * ```
+ */
+declare function onCommand<D = unknown, R = unknown>(type: CommandType): OnCommandDecorator<D, R>;
+
+/**
+ * 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.
+ * It automatically re-registers if the IoC container is updated.
+ *
+ * @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 - Unique identifier of the command 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;
+}
+
+/**
+ * Represents 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>;
+}
+/**
+ * Hook that registers a command handler 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>;
+
+/**
+ * Represents type definition for the on-event decorator.
+ *
+ * @remarks
+ * Supports both TC39 and legacy experimental decorators.
+ *
+ * @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 for Lit element methods that handle events from the event bus.
+ *
+ * @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 A method 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 for the host element's lifetime.
+ *
+ * @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
+ */
+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;
+}
+
+/**
+ * Represents options for the {@link useOnEvents} hook.
+ *
+ * @group Events
+ */
+interface UseOnEventsOptions<E extends Event = Event> {
+    /**
+     * The 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 that subscribes to events for the host element's lifetime.
+ *
+ * @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 An instance of {@link OnEventController}.
+ *
+ * @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: ["MY_EVENT"],
+ *     handler: (event) => console.log(event),
+ *   });
+ * }
+ * ```
+ */
+declare function useOnEvents<E extends Event = Event>(host: ReactiveElement, { types, handler }: UseOnEventsOptions): OnEventController<E>;
+
+/**
+ * Represents interface for the {@link onQuery} decorator.
+ *
+ * @remarks
+ * Supports both 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 for Lit element methods that handle a specific query.
+ *
+ * @remarks
+ * The handler is registered when the host connects and unregistered when it disconnects.
+ *
+ * @group Queries
+ *
+ * @param type - Unique identifier of the query to handle.
+ * @returns A method decorator function.
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   @onQuery("GET_USER_NAME")
+ *   private 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.
+ *
+ * @remarks
+ * The handler is registered when the host connects and unregistered when it disconnects.
+ * It automatically re-registers if the IoC container is updated.
+ *
+ * @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 - Unique identifier of the query 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;
+}
+
+/**
+ * Represents 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>;
+}
+/**
+ * Hook that registers a query handler 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 An instance of {@link OnQueryController}.
+ *
+ * @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 IoC container instance.
      */
     readonly container: Container;
     /**
@@ -50,47 +526,272 @@ interface IocContext {
      */
     readonly revision: number;
     /**
-     * Forces a revision update.
+     * Function to force a revision update.
      */
     readonly nextRevision: () => number;
 }
-declare const ContainerContext: {
+/**
+ * Lit context object for providing and consuming the IoC container.
+ *
+ * @group Context
+ */
+declare const IocContextObject: {
     __context__: IocContext;
 };
 
-declare class ContainerProviderController implements ReactiveController {
+/**
+ * Represents 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.
+ *
+ * @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
+ */
+declare class IocProviderController<E extends ReactiveControllerHost & HTMLElement = ReactiveControllerHost & HTMLElement> implements ReactiveController {
     private readonly host;
-    protected provider: ContextProvider<typeof ContainerContext>;
+    protected readonly provider: ContextProvider<typeof IocContextObject>;
+    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 {
+/**
+ * Represents interface for the {@link iocProvide} decorator.
+ *
+ * @remarks
+ * Supports both TC39 and legacy experimental decorators.
+ *
+ * @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 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
+ *
+ * @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" } })
+ *   private ioc!: IocProviderController;
+ * }
+ * ```
+ */
+declare function iocProvide<E extends ReactiveElement>({ container, seed, }?: IocProviderControllerOptions): IocProviderDecorator<E>;
+
+/**
+ * Represents a function that returns a value of type `T`.
+ *
+ * @group general-types
+ *
+ * @template T - The return type of the function.
+ */
+type Callable<T> = () => T;
+
+/**
+ * Represents 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 injectables to an IoC container for the host element's lifetime.
+ *
+ * @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
+ *
+ * @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 IocContextObject, 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;
+}
+
+/**
+ * Represents type for the {@link injectablesProvide} decorator.
+ *
+ * @remarks
+ * Supports both 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.
+ *
+ * @remarks
+ * Entries are bound when the host connects and unbound when it disconnects.
+ *
+ * @group Provision
+ *
+ * @param options - Provisioning options.
+ * @returns An instance of {@link InjectablesProviderDecorator}.
+ *
+ * @example
+ * ```typescript
+ * class MyComponent extends LitElement {
+ *   @injectablesProvide({ entries: [AuthService, UserService], activate: [AuthService] })
+ *   public controller!: InjectablesProviderController<MyComponent>;
+ * }
+ * ```
+ */
+declare function injectablesProvide<E extends ReactiveElement = ReactiveElement>(options: InjectablesProviderControllerOptions): InjectablesProviderDecorator<E>;
 
-interface UseContainerProvisionOptions {
+/**
+ * Hook that binds injectables to the nearest IoC container for the host element's lifetime.
+ *
+ * @group Provision
+ *
+ * @param host - The host element.
+ * @param options - Provisioning options.
+ * @returns An instance of {@link InjectablesProviderController}.
+ *
+ * @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>;
+
+/**
+ * Represents 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 that provides an IoC container to the host element and its children.
+ *
+ * @group Provision
+ *
+ * @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: "..." } });
+ * }
+ * ```
+ */
+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 { InjectablesProviderController, IocContextObject, IocProviderController, OnCommandController, OnEventController, OnQueryController, injectablesProvide, injection, iocProvide, onCommand, onEvent, onQuery, useInjectablesProvider, useInjection, useIocProvision, useOnCommand, useOnEvents, useOnQuery };
+export type { InjectablesProviderControllerOptions, InjectablesProviderDecorator, InjectionDecorator, InjectionOptions, IocContext, IocProviderControllerOptions, IocProviderDecorator, OnCommandDecorator, OnEventDecorator, OnQueryDecorator, UseInjectionOptions, UseInjectionValue, UseIocProvisionOptions, UseOnCommandOptions, UseOnEventsOptions, UseOnQueryOptions };