@wirestate/lit 0.6.1 → 0.7.0-experimental.1

package/index.d.ts

@@ -3,27 +3,27 @@ import { ServiceIdentifier, CommandType, CommandHandler, Event, EventType, Event
 import { ContextProvider, ContextConsumer } from '@lit/context';
 
 /**
- * Represents any object with string or symbol keys.
+ * Any object with string or symbol keys.
  *
- * @group types
+ * @group Types
  */
 type AnyObject = Record<string | symbol, any>;
 /**
- * Represents a type that can be null.
+ * Type that can be null.
  *
- * @group types
+ * @group Types
  */
 type Optional<T> = T | null;
 /**
- * Represents a type that can be a value or a promise of that value.
+ * Value or a promise of that value.
  *
- * @group types
+ * @group Types
  */
 type MaybePromise<T> = T | Promise<T>;
 /**
  * Helper to extract the interface of a type.
  *
- * @group types
+ * @group Types
  */
 type Interface<T> = {
     [K in keyof T]: T[K];
@@ -31,13 +31,13 @@ type Interface<T> = {
 /**
  * Return type for decorators.
  *
- * @group types
+ * @group Types
  */
 type DecoratorReturn = void | any;
 /**
- * Type helper to ensure that a decorated field matches the type being provided.
+ * Ensures that a decorated field matches the type being provided.
  *
- * @group types
+ * @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";
@@ -50,39 +50,43 @@ type FieldMustMatchProvidedType<Obj, Key extends PropertyKey, ProvidedType> = Ob
 } : DecoratorReturn;
 
 /**
- * Type definition for the injection decorator.
+ * Represents definition of the injection decorator.
  *
- * @group consumption
+ * @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>;
 }
 /**
- * Options for the {@link injection} decorator.
+ * Represents options for the {@link injection} decorator.
  *
- * @group consumption
+ * @group Consumption
  */
 interface InjectionOptions<T> {
     /**
-     * The service identifier to inject from the IoC container.
+     * The service identifier to inject.
      */
     injectionId: ServiceIdentifier<T>;
     /**
-     * Whether to subscribe to changes in the context.
+     * Whether to subscribe to container changes.
      *
+     * @remarks
      * If true, the property will be updated if the container in the context changes.
-     * False by default.
+     * Defaults to false.
      */
     once?: boolean;
 }
 /**
  * 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
@@ -111,18 +115,21 @@ interface InjectionOptions<T> {
 declare function injection<T>(optionsOrInjectionId: InjectionOptions<T> | ServiceIdentifier<T>): InjectionDecorator<T>;
 
 /**
- * Options for the {@link useInjection} hook.
+ * Represents options for the {@link useInjection} hook.
  *
- * @group consumption
+ * @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.
-     * If false (default), it will update if the container in the context changes.
+     * Defaults to false.
      */
     once?: boolean;
     /**
-     * Initial value for the injection before it's fetched from the container.
+     * Initial value before the service is fetched.
      */
     value?: Optional<T>;
     /**
@@ -131,9 +138,9 @@ interface UseInjectionOptions<T> {
     injectionId: ServiceIdentifier<T>;
 }
 /**
- * The return value of the {@link useInjection} hook, containing the injected service.
+ * Represents result of the {@link useInjection} hook.
  *
- * @group consumption
+ * @group Consumption
  */
 interface UseInjectionValue<T> {
     /**
@@ -146,13 +153,13 @@ interface UseInjectionValue<T> {
     value: T;
 }
 /**
- * Hook (controller) to inject a service from the IoC container in a Lit component.
+ * Hook (controller) to inject a service from the IoC container.
  *
- * @group consumption
+ * @group Consumption
  *
- * @param host - the host element
- * @param optionsOrInjectionId - injection options including the service identifier or the service identifier itself
- * @returns injection descriptor object
+ * @param host - The host element.
+ * @param optionsOrInjectionId - Injection options or service identifier.
+ * @returns An instance of {@link UseInjectionValue}.
  *
  * @example
  * ```typescript
@@ -179,31 +186,33 @@ interface UseInjectionValue<T> {
 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.
+ * Represents interface for the {@link onCommand} decorator.
  *
- * Supports both standard (TC39) and legacy experimental decorators.
+ * @remarks
+ * Supports both TC39 and legacy experimental decorators.
  *
- * @group commands
+ * @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.
+ * 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
  *   }
  * }
@@ -212,12 +221,13 @@ interface OnCommandDecorator<D = unknown, R = unknown> {
 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.
+ * 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
  */
 declare class OnCommandController<D = unknown, R = unknown> implements ReactiveController {
     private bus;
@@ -226,7 +236,7 @@ declare class OnCommandController<D = unknown, R = unknown> implements ReactiveC
     private readonly handler;
     /**
      * @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.
      */
     constructor(host: ReactiveElement, type: CommandType, handler: CommandHandler<D, R>);
@@ -237,9 +247,9 @@ declare class OnCommandController<D = unknown, R = unknown> implements ReactiveC
 }
 
 /**
- * Options for the {@link useOnCommand} hook.
+ * Represents options for the {@link useOnCommand} hook.
  *
- * @group commands
+ * @group Commands
  */
 interface UseOnCommandOptions<D = unknown, R = unknown> {
     /**
@@ -252,15 +262,15 @@ interface UseOnCommandOptions<D = unknown, R = unknown> {
     handler: CommandHandler<D, R>;
 }
 /**
- * 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
@@ -275,28 +285,34 @@ interface UseOnCommandOptions<D = unknown, R = unknown> {
 declare function useOnCommand<D = unknown, R = unknown>(host: ReactiveElement, { type, handler }: UseOnCommandOptions<D, R>): OnCommandController<D, R>;
 
 /**
- * Type definition for the on-event decorator.
+ * Represents type definition for the on-event decorator.
+ *
+ * @remarks
+ * Supports both TC39 and legacy experimental decorators.
  *
- * @group events
+ * @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.
+ * 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);
  *   }
  * }
  * ```
@@ -304,9 +320,9 @@ interface OnEventDecorator<E extends Event = Event> {
  * @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);
  *   }
  * }
  * ```
@@ -314,9 +330,9 @@ interface OnEventDecorator<E extends Event = Event> {
  * @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);
  *   }
  * }
  * ```
@@ -324,11 +340,13 @@ interface OnEventDecorator<E extends Event = Event> {
 declare function onEvent<E extends Event = Event>(types?: EventType | ReadonlyArray<EventType>): OnEventDecorator<E>;
 
 /**
- * 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
  */
 declare class OnEventController<E extends Event = Event> implements ReactiveController {
     private bus;
@@ -336,9 +354,9 @@ declare class OnEventController<E extends Event = Event> implements ReactiveCont
     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
+     * @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;
@@ -348,13 +366,13 @@ declare class OnEventController<E extends Event = Event> implements ReactiveCont
 }
 
 /**
- * Options for the {@link useOnEvents} hook.
+ * Represents options for the {@link useOnEvents} hook.
  *
- * @group events
+ * @group Events
  */
 interface UseOnEventsOptions<E extends Event = Event> {
     /**
-     * Event handler function.
+     * The event handler function.
      */
     handler: EventHandler<E>;
     /**
@@ -363,15 +381,15 @@ interface UseOnEventsOptions<E extends Event = Event> {
     types?: Optional<EventType | ReadonlyArray<EventType>>;
 }
 /**
- * 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
@@ -386,7 +404,7 @@ interface UseOnEventsOptions<E extends Event = Event> {
  * ```typescript
  * class MyElement extends LitElement {
  *   private eventHandler = useOnEvents(this, {
- *     types: [MyEvent],
+ *     types: ["MY_EVENT"],
  *     handler: (event) => console.log(event),
  *   });
  * }
@@ -395,31 +413,33 @@ interface UseOnEventsOptions<E extends Event = Event> {
 declare function useOnEvents<E extends Event = Event>(host: ReactiveElement, { types, handler }: UseOnEventsOptions): OnEventController<E>;
 
 /**
- * Interface for the {@link onQuery} decorator.
+ * Represents interface for the {@link onQuery} decorator.
  *
- * Supports both standard (TC39) and legacy experimental decorators.
+ * @remarks
+ * Supports both TC39 and legacy experimental decorators.
  *
- * @group queries
+ * @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.
+ * 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";
  *   }
  * }
@@ -430,10 +450,11 @@ declare function onQuery<D = unknown, R = unknown>(type: QueryType): OnQueryDeco
 /**
  * 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
  */
 declare class OnQueryController<D = unknown, R = unknown> implements ReactiveController {
     private bus;
@@ -441,9 +462,9 @@ declare class OnQueryController<D = unknown, R = unknown> implements ReactiveCon
     private readonly type;
     private readonly handler;
     /**
-     * @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.
      */
     constructor(host: ReactiveElement, type: QueryType, handler: QueryHandler<D, R>);
     hostConnected(): void;
@@ -453,9 +474,9 @@ declare class OnQueryController<D = unknown, R = unknown> implements ReactiveCon
 }
 
 /**
- * Options for the {@link useOnQuery} hook.
+ * Represents options for the {@link useOnQuery} hook.
  *
- * @group queries
+ * @group Queries
  */
 interface UseOnQueryOptions<D = unknown, R = unknown> {
     /**
@@ -468,15 +489,15 @@ interface UseOnQueryOptions<D = unknown, R = unknown> {
     handler: QueryHandler<D, R>;
 }
 /**
- * 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
@@ -493,11 +514,11 @@ declare function useOnQuery<D = unknown, R = unknown>(host: ReactiveElement, { t
 /**
  * Interface for the IoC context value.
  *
- * @group context
+ * @group Context
  */
 interface IocContext {
     /**
-     * The Inversify IoC container.
+     * The IoC container instance.
      */
     readonly container: Container;
     /**
@@ -510,18 +531,18 @@ interface IocContext {
     readonly nextRevision: () => number;
 }
 /**
- * Lit context for providing and consuming the IoC container.
+ * Lit context object for providing and consuming the IoC container.
  *
- * @group context
+ * @group Context
  */
-declare const ContainerContext: {
+declare const IocContextObject: {
     __context__: IocContext;
 };
 
 /**
- * Options for the {@link IocProviderController}.
+ * Represents options for the {@link IocProviderController}.
  *
- * @group provision
+ * @group Provision
  */
 interface IocProviderControllerOptions {
     /**
@@ -536,13 +557,16 @@ interface IocProviderControllerOptions {
 /**
  * Controller that provides an IoC container context to the host element and its children.
  *
+ * @remarks
  * It manages the lifecycle of the container and handles revision updates to notify consumers.
+ * The container is created (or used from options) when the controller is instantiated.
+ * Seed data is applied when the host connects.
  *
- * @group provision
+ * @group Provision
  */
 declare class IocProviderController<E extends ReactiveControllerHost & HTMLElement = ReactiveControllerHost & HTMLElement> implements ReactiveController {
     private readonly host;
-    protected readonly provider: ContextProvider<typeof ContainerContext>;
+    protected readonly provider: ContextProvider<typeof IocContextObject>;
     protected readonly seed?: AnyObject;
     protected revision: number;
     /**
@@ -550,14 +574,14 @@ declare class IocProviderController<E extends ReactiveControllerHost & HTMLEleme
      */
     container: Container;
     /**
-     * @returns current {@link IocContext} value served to child consumers
+     * @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
+     * @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;
@@ -566,28 +590,34 @@ declare class IocProviderController<E extends ReactiveControllerHost & HTMLEleme
 }
 
 /**
- * Type definition for the ioc-provide decorator.
+ * Represents interface for the {@link iocProvide} decorator.
+ *
+ * @remarks
+ * Supports both TC39 and legacy experimental decorators.
  *
- * @group provision
+ * @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.
+ * Decorator that provides an IoC container to child components.
  *
- * @group provision
+ * @remarks
+ * The container is provided via Lit context. It is created (or used from options) when the host connects.
  *
- * @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
+ * @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' } })
+ *   @iocProvide({ seed: { someData: "value" } })
  *   private ioc!: IocProviderController;
  * }
  * ```
@@ -595,14 +625,18 @@ interface IocProviderDecorator<E extends ReactiveElement = ReactiveElement> {
 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;
 
 /**
- * Options for the {@link InjectablesProviderController}.
+ * Represents options for the {@link InjectablesProviderController}.
  *
- * @group provision
+ * @group Provision
  */
 interface InjectablesProviderControllerOptions {
     /**
@@ -626,14 +660,14 @@ interface InjectablesProviderControllerOptions {
     seeds?: SeedEntries;
 }
 /**
- * Controller that binds a set of injectables to an IoC container when the host connects
- * and unbinds them when the host disconnects.
+ * Controller that binds injectables to an IoC container for the host element's lifetime.
  *
- * When no `into` context is provided, the controller uses the nearest {@link IocProviderController}
- * ancestor via Lit context. Seeds are applied before entries so that `@Inject(SEEDS_TOKEN)`
- * works during service activation.
+ * @remarks
+ * Entries are bound when the host connects and unbound when it disconnects.
+ * If no `into` context is provided, it uses the nearest {@link IocProviderController}.
+ * Seeds are applied before entries are bound.
  *
- * @group provision
+ * @group Provision
  *
  * @example
  * ```typescript
@@ -648,7 +682,7 @@ interface InjectablesProviderControllerOptions {
  */
 declare class InjectablesProviderController<E extends ReactiveControllerHost & HTMLElement = ReactiveControllerHost & HTMLElement> implements ReactiveController {
     private readonly host;
-    protected readonly consumer?: ContextConsumer<typeof ContainerContext, E>;
+    protected readonly consumer?: ContextConsumer<typeof IocContextObject, E>;
     private readonly entries;
     private readonly activate;
     private readonly seeds;
@@ -658,12 +692,12 @@ declare class InjectablesProviderController<E extends ReactiveControllerHost & H
      */
     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
+     * @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;
@@ -673,11 +707,12 @@ declare class InjectablesProviderController<E extends ReactiveControllerHost & H
 }
 
 /**
- * Type for the {@link injectablesProvide} decorator.
+ * Represents type for the {@link injectablesProvide} decorator.
  *
- * Supports both standard (TC39) and legacy experimental decorators.
+ * @remarks
+ * Supports both TC39 and legacy experimental decorators.
  *
- * @group provision
+ * @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;
@@ -686,38 +721,32 @@ interface InjectablesProviderDecorator<T extends ReactiveElement = ReactiveEleme
 /**
  * Decorator that binds a set of injectables to the nearest IoC container for the host element's lifetime.
  *
+ * @remarks
  * Entries are bound when the host connects and unbound when it disconnects.
- * The decorated accessor or property holds the resulting {@link InjectablesProviderController} instance.
  *
- * @group provision
+ * @group Provision
  *
- * @param options - provisioning options
- * @returns injectables provider decorator instance
+ * @param options - Provisioning options.
+ * @returns An instance of {@link InjectablesProviderDecorator}.
  *
  * @example
  * ```typescript
  * class MyComponent extends LitElement {
  *   @injectablesProvide({ entries: [AuthService, UserService], activate: [AuthService] })
- *   public services!: InjectablesProviderController<MyComponent>;
+ *   public controller!: InjectablesProviderController<MyComponent>;
  * }
  * ```
  */
 declare function injectablesProvide<E extends ReactiveElement = ReactiveElement>(options: InjectablesProviderControllerOptions): InjectablesProviderDecorator<E>;
 
 /**
- * Binds a set of injectables to the nearest IoC container for the host element's lifetime.
- *
- * Entries are bound when the host connects and unbound when it disconnects.
+ * Hook that binds injectables to the nearest IoC container for the host element's lifetime.
  *
- * @group provision
+ * @group Provision
  *
- * @param host - the host element
- * @param options - provisioning options
- * @param options.entries - list of service entries to bind to the container
- * @param options.into - target IoC context; if omitted, uses the nearest provider context
- * @param options.activate - list of service identifiers to activate immediately after binding
- * @param options.seeds - seed data applied before binding
- * @returns the controller instance
+ * @param host - The host element.
+ * @param options - Provisioning options.
+ * @returns An instance of {@link InjectablesProviderController}.
  *
  * @example
  * ```typescript
@@ -732,9 +761,9 @@ declare function injectablesProvide<E extends ReactiveElement = ReactiveElement>
 declare function useInjectablesProvider<E extends ReactiveControllerHost & HTMLElement>(host: E, options: InjectablesProviderControllerOptions): InjectablesProviderController<E>;
 
 /**
- * Options for the {@link useIocProvision} hook.
+ * Represents options for the {@link useIocProvision} hook.
  *
- * @group provision
+ * @group Provision
  */
 interface UseIocProvisionOptions {
     /**
@@ -747,24 +776,22 @@ interface UseIocProvisionOptions {
     seed?: AnyObject;
 }
 /**
- * Hook (controller) to provide an IoC container to the host element and its children.
+ * Hook that provides an IoC container to the host element and its children.
  *
- * @group provision
+ * @group Provision
  *
- * @param host - the host element
- * @param options - provisioning options
- * @param options.container - optional existing container to use
- * @param options.seed - optional seed data to apply to the container
- * @returns ioc provision controller instance
+ * @param host - The host element.
+ * @param options - Provisioning options.
+ * @returns An instance of {@link IocProviderController}.
  *
  * @example
  * ```typescript
  * class MyRootElement extends LitElement {
- *   private ioc = useIocProvision(this, { seed: { initialData: '...' } });
+ *   private ioc = useIocProvision(this, { seed: { initialData: "..." } });
  * }
  * ```
  */
 declare function useIocProvision<E extends ReactiveControllerHost & HTMLElement>(host: E, options?: UseIocProvisionOptions): IocProviderController<E>;
 
-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 };
+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 };