@wirestate/lit 0.6.1 → 0.7.0-experimental.2

package/CHANGELOG.md

@@ -1,4 +1,4 @@
-## 0.7.0
+## Unreleased
 
 - Add `useScope` in `@wirestate/react`
 - New lit elements modules - `@wirestate/lit` and `@wirestate/lit-signals`
@@ -8,6 +8,21 @@
 - `WireScope`: add new event/command/query subscribe-unsubscribe methods
 - Export more alias / methods from `@wirestate/core`
 - Export more alias / methods from `@wirestate/react-mobx`
+- Export missing methods typing for `@wirestate/core`
+- Extensive JSDoc coverage for wirestate packages
+- `createIocContainer`: Removed in favor of `createContainer`
+- `createContainer`: Added ability to instantly provide and activate entries, targeted seeds
+- `createInjectablesProvider`: Removed.
+- `IocProvider`: Removed
+- `useRootContainer`: Added separate hook for store management in React tree
+- `ContainerProvider`: Simpler provider for containers.
+- `SubContainerProvider`: Added component solving problems of removed `createInjectablesProvider`
+- `ContainerActivator`: Added separate activation component
+- Replace IoC-context provision APIs with `ContainerContext`, `containerProvide`, `ContainerProvider`, and `useContainerProvision`
+- Replace injectables-provider APIs with `subContainerProvide`, `SubContainerProvider`, and `useSubContainerProvider`
+- Provide plain `Container` values through Lit context instead of wrapper objects
+- Recreate managed child containers when the parent container context changes
+- Add `useContainer` and `useScope` consumers in `@wirestate/lit`
 
 ## 0.6.3
 
@@ -70,6 +85,6 @@
 - useService -> useInjection
 - AbstractService::getService -> AbstractService::resolve
 
-## 0.1.1
+## 0.1.0
 
 - Initial release

package/README.md

@@ -1,9 +1,9 @@
-# @wirestate/lit
+# @wirestate/lit [[monorepo](https://github.com/Neloreck/wirestate)] [[docs](https://neloreck.github.io/wirestate/)]
 
 [![npm](https://img.shields.io/npm/v/@wirestate/lit.svg?style=flat-square)](https://www.npmjs.com/package/@wirestate/lit)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://github.com/Neloreck/wirestate/blob/master/LICENSE)
 
-Lit elements integration for wirestate. Provides dependency injection and messaging for Lit components.
+Lit elements integration for wirestate. Provides container provisioning, dependency injection, and messaging for Lit components.
 
 ## Installation
 
@@ -18,25 +18,31 @@ npm install @wirestate/core @wirestate/lit lit reflect-metadata
   - **Events**: Subscribe to events from the global event bus using `@onEvent` or `useOnEvents`.
   - **Commands**: Register command handlers using `@onCommand` or `useOnCommand`.
   - **Queries**: Register query handlers using `@onQuery` or `useOnQuery`.
-- **Container Provisioning**: Provide and manage IoC containers within the Lit component tree using `@iocProvide` or `useIocProvision`.
-- **Service Binding**: Dynamically bind services to the container using `@injectablesProvide`, `useInjectablesProvider`, or `InjectablesProviderController`.
+- **Container Provisioning**: Provide and manage containers within the Lit component tree using `@containerProvide` or `useContainerProvision`.
+- **Sub-containers**: Create managed child containers derived from the parent context using `@subContainerProvide`, `useSubContainerProvider`, or `SubContainerProvider`.
 - **Test Utilities**: Simplified setup for unit testing components with IoC dependencies.
 
 ## Provisioning
 
-### `@iocProvide(options?)` / `useIocProvision(host, options?)`
+### `@containerProvide(options)` / `useContainerProvision(host, options)`
 
-Provides an IoC container to the component tree. It uses Lit Context to propagate the container to child elements.
+Provides a container to the component tree. It uses Lit Context to propagate the container to child elements.
+
+Pass `container` to expose an existing container, or pass `options` to create and manage one for the host lifecycle.
 
 ```typescript
-import { LitElement, html } from 'lit';
-import { customElement } from 'lit/decorators.js';
-import { iocProvide, IocProviderController } from '@wirestate/lit';
+import { LitElement, html } from "lit";
+import { customElement } from "lit/decorators.js";
+import { containerProvide, ContainerProvider } from "@wirestate/lit";
 
-@customElement('my-app')
+@customElement("my-app")
 class MyApp extends LitElement {
-  @iocProvide()
-  private ioc!: IocProviderController;
+  @containerProvide({
+    options: {
+      seed: { someData: "value" },
+    },
+  })
+  private containerProvider!: ContainerProvider;
 
   render() {
     return html`<my-component></my-component>`;
@@ -44,69 +50,81 @@ class MyApp extends LitElement {
 }
 ```
 
-### `@injectablesProvide(options)` / `useInjectablesProvider(host, options)`
+### `@subContainerProvide(options)` / `useSubContainerProvider(host, options)`
 
-Binds a set of injectables to the nearest IoC container for the host element's lifetime. Entries are bound when the host connects and unbound when it disconnects.
+Creates a managed child container derived from the nearest parent container for the host element's lifetime. The child container is recreated when the parent container changes and destroyed when the host disconnects.
 
 Using the decorator (accessor):
 
 ```typescript
-import { LitElement } from 'lit';
-import { customElement } from 'lit/decorators.js';
-import { injectablesProvide, InjectablesProviderController } from '@wirestate/lit';
+import { LitElement } from "lit";
+import { customElement } from "lit/decorators.js";
+import { subContainerProvide, SubContainerProvider } from "@wirestate/lit";
 
-import { AuthService, UserService } from './services';
+import { AuthService, UserService } from "./services";
 
-@customElement('my-app')
+@customElement("my-app")
 class MyApp extends LitElement {
-  @injectablesProvide({ entries: [AuthService, UserService], activate: [AuthService] })
-  public services!: InjectablesProviderController<MyApp>;
+  @subContainerProvide({
+    options: {
+      entries: [AuthService, UserService],
+      activate: [AuthService],
+    },
+  })
+  public containerProvider!: SubContainerProvider;
 }
 ```
 
 Using the hook:
 
 ```typescript
-import { LitElement } from 'lit';
-import { useInjectablesProvider } from '@wirestate/lit';
+import { LitElement } from "lit";
+import { useSubContainerProvider } from "@wirestate/lit";
 
-import { AuthService, UserService } from './services';
+import { AuthService, UserService } from "./services";
 
 class MyApp extends LitElement {
-  private services = useInjectablesProvider(this, {
-    entries: [AuthService, UserService],
-    activate: [AuthService],
+  private container = useSubContainerProvider(this, {
+    options: {
+      entries: [AuthService, UserService],
+      activate: [AuthService],
+    },
   });
 }
 ```
 
-Using the controller directly:
+Using the provider directly:
 
 ```typescript
-import { LitElement } from 'lit';
-import { InjectablesProviderController } from '@wirestate/lit';
+import { LitElement } from "lit";
+import { SubContainerProvider } from "@wirestate/lit";
 
-import { AuthService, UserService } from './services';
+import { AuthService, UserService } from "./services";
 
 class MyApp extends LitElement {
-  private services = new InjectablesProviderController(this, {
-    entries: [AuthService, UserService],
-    activate: [AuthService],
+  private containerProvider: SubContainerProvider = new SubContainerProvider(this, {
+    options: {
+      entries: [AuthService, UserService],
+      activate: [AuthService],
+    },
   });
 }
 ```
 
-To bind into a specific container instead of the nearest provider context, pass the `into` option:
+To seed the child container during creation, pass `seeds` inside `options`:
 
 ```typescript
-import { LitElement } from 'lit';
-import { useInjectablesProvider } from '@wirestate/lit';
+import { LitElement } from "lit";
+import { useSubContainerProvider } from "@wirestate/lit";
 
-import { AuthService, UserService } from './services';
+import { AuthService, UserService } from "./services";
 
 class MyApp extends LitElement {
-  private services = useInjectablesProvider(this, {
-    entries: [AuthService, UserService],
+  private provider: SubContainerProvider = useSubContainerProvider(this, {
+    options: {
+      entries: [AuthService, UserService],
+      seeds: [[AuthService, { role: "admin" }]],
+    },
   });
 }
 ```
@@ -115,16 +133,16 @@ class MyApp extends LitElement {
 
 ### `@injection(optionsOrId)` / `useInjection(host, optionsOrId)`
 
-Injects a service from the nearest IoC container. Supports both options object and direct service identifier.
+Injects a service from the nearest parent container. Supports both options object and direct service identifier.
 
 ```typescript
-import { LitElement, html } from 'lit';
-import { customElement } from 'lit/decorators.js';
-import { injection } from '@wirestate/lit';
+import { LitElement, html } from "lit";
+import { customElement } from "lit/decorators.js";
+import { injection } from "@wirestate/lit";
 
-import { MyService } from './services';
+import { MyService } from "./services";
 
-@customElement('my-component')
+@customElement("my-component")
 class MyComponent extends LitElement {
   // Using identifier:
   @injection(MyService)
@@ -140,13 +158,13 @@ class MyComponent extends LitElement {
 }
 ```
 
-Using the controller:
+Using the hook:
 
 ```typescript
-import { LitElement, html } from 'lit';
-import { useInjection } from '@wirestate/lit';
+import { LitElement, html } from "lit";
+import { useInjection } from "@wirestate/lit";
 
-import { MyService } from './services';
+import { MyService } from "./services";
 
 class MyComponent extends LitElement {
   // Using identifier:
@@ -165,18 +183,18 @@ class MyComponent extends LitElement {
 
 ### Events
 
-Subscribe to events from the event bus using `@onEvent` decorator or `useOnEvents` controller.
+Subscribe to events from the event bus using `@onEvent` decorator or `useOnEvents` controller. Handlers follow the active container context when the nearest container changes.
 
 ```typescript
-import { LitElement } from 'lit';
-import { onEvent } from '@wirestate/lit';
+import { LitElement } from "lit";
+import { onEvent } from "@wirestate/lit";
 
-import { UserLoggedInEvent } from './events';
+import { UserLoggedInEvent } from "./events";
 
 class MyListener extends LitElement {
   @onEvent("USER_LOGGED_IN")
   private handleLogin(event: UserLoggedInEvent) {
-    console.log('User logged in:', event.payload);
+    console.log("User logged in:", event.payload);
   }
 }
 ```
@@ -184,26 +202,26 @@ class MyListener extends LitElement {
 Using the controller:
 
 ```typescript
-import { LitElement } from 'lit';
-import { useOnEvents } from '@wirestate/lit';
+import { LitElement } from "lit";
+import { useOnEvents } from "@wirestate/lit";
 
 class MyListener extends LitElement {
   private events = useOnEvents(this, {
-    handler: (event) => console.log('Event received:', event),
+    handler: (event) => console.log("Event received:", event),
   });
 }
 ```
 
 ### Commands
 
-Register a handler for a specific command type.
+Register a handler for a specific command type. Handlers follow the active container context when the nearest container changes.
 
 ```typescript
-import { LitElement } from 'lit';
-import { onCommand } from '@wirestate/lit';
+import { LitElement } from "lit";
+import { onCommand } from "@wirestate/lit";
 
 class MyCommander extends LitElement {
-  @onCommand('RESET_STATE')
+  @onCommand("RESET_STATE")
   private handleReset() {
     // perform reset
   }
@@ -212,14 +230,14 @@ class MyCommander extends LitElement {
 
 ### Queries
 
-Register a handler for a specific query type.
+Register a handler for a specific query type. Handlers follow the active container context when the nearest container changes.
 
 ```typescript
-import { LitElement } from 'lit';
-import { onQuery } from '@wirestate/lit';
+import { LitElement } from "lit";
+import { onQuery } from "@wirestate/lit";
 
 class MyQuerier extends LitElement {
-  @onQuery('GET_VIEW_PORT')
+  @onQuery("GET_VIEW_PORT")
   private handleGetViewport() {
     return { width: window.innerWidth, height: window.innerHeight };
   }
@@ -233,9 +251,9 @@ class MyQuerier extends LitElement {
 Creates a test fixture with a provider element and an IoC container. Useful for unit testing components that use injections.
 
 ```typescript
-import { createLitProvision } from '@wirestate/lit/test-utils';
+import { createLitProvision } from "@wirestate/lit/test-utils";
 
-describe('MyComponent', () => {
+describe("MyComponent", () => {
   let fixture: ReturnType<typeof createLitProvision>;
 
   beforeEach(() => {
@@ -246,8 +264,8 @@ describe('MyComponent', () => {
     fixture.cleanup();
   });
 
-  it('should work', () => {
-    const el = document.createElement('my-component');
+  it("should work", () => {
+    const el = document.createElement("my-component");
     fixture.provider.appendChild(el);
     // ...
   });