@spearwolf/shadow-objects 0.21.1 → 0.23.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# CHANGELOG
+
+All notable changes to [@spearwolf/shadow-objects](https://github.com/spearwolf/shadow-objects/tree/main/packages/shadow-objects) will be documented in this file.
+
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.23.0] - 2025-11-26
+
+- enhance the shadow-objects creation api _aka_ `ShadowObjectParams`
+  - added the `useProperties()` function
+  - added the `useResource()` function
+- added lots of new tests and improved code coverage
+

package/README.md

@@ -1,154 +1,200 @@
-_hi! welcome to .._
-# shadow-objects 🧛
+# Shadow Objects Framework 🧛
 
-## Introduction
+The **Shadow Objects Framework** is a reactive library designed to decouple business logic and state management from the UI rendering layer. It runs application logic "in the dark" (e.g., in a web worker), mirroring the view hierarchy of your application.
 
-_Shadow-objects_ is a standalone, reactive entity←component framework 🔥
+> [!WARNING]
+> 🚀 This is a highly experimental framework that is slowly maturing. Use at your own risk. 🔥
 
-The original idea is visualized in this overview:
+## Core Concepts
 
-![architecture overview](https://raw.githubusercontent.com/spearwolf/shadow-objects/main/packages/shadow-objects/docs/architecture%402x.png)
+### 1. Entities
+An **Entity** is the fundamental unit in the framework. It represents a node in the hierarchy, mirroring a view component (e.g., a Web Component or a DOM element).
+- **Hierarchy**: Entities have parents and children, forming a tree structure.
+- **Properties**: Entities hold reactive properties that sync with the view.
+- **Context**: Entities participate in a hierarchical context system (dependency injection).
 
-> _ents_ is short for latin _"entitatis"_, which translates to _"shadow entities"_
+### 2. Shadow Objects
+A **Shadow Object** is a functional unit of logic attached to an Entity.
+- **Logic Containers**: They contain the state, effects, and business logic for a specific feature.
+- **Lifecycle**: They are automatically created and destroyed by the **Kernel** based on the Entity's **Token**.
+- **Reactivity**: They use **Signals** and **Effects** (via `@spearwolf/signalize`) to react to changes in properties or context.
 
-> [!IMPORTANT]
-> _Dear adventurer, be warned: everything here is highly experimental and in active development and constant flux!_
+### 3. The Kernel
+The **Kernel** is the brain of the framework.
+- **Manages Entities**: Handles creation, destruction, and hierarchy updates of Entities.
+- **Orchestrates Shadow Objects**: Instantiates the correct Shadow Objects for each Entity based on its Token and the Registry.
+- **Message Dispatch**: Handles communication between the View (UI) and the Shadow World.
 
-The components are created in the view space. Hierarchical. In your browser. There is a JavaScript API for this. But to keep things simple, there are also ready-to-use web components.
+### 4. The Registry
+The **Registry** maps **Tokens** to **Shadow Object Constructors**.
+- **Tokens**: Strings that identify what logic an Entity should have (e.g., `"my-component"`).
+- **Routes**: Defines rules for composing multiple Shadow Objects. For example, a token can "route" to other tokens, causing multiple Shadow Objects to be instantiated for a single Entity.
+- **Conditional Routing**: Routes can be triggered based on the presence of specific "truthy" properties on the Entity (e.g., `@myProp` routes only if `myProp` is set).
 
-```html
-<shae-worker-env local? src="./my-personal-shadow-objects.js" />
+---
 
-<shae-ent ns? token="foo">
-  <shae-ent ns? token="bar">
-    <shae-prop name="myNumbers" value="1 2 3" type="integer[]" />
-  </shae-ent>
-</shae-ent>
-```
-
-In the shadows, the _shadow objects_ come and go with the entities. An entity can cover many shadows. But all are united by the entity _token_. That token, which is specified by the _view components_.
-
-The _shadow object module_ stores which shadow objects are hidden behind a token. Either a _function_ or a _class_.
-
-```js
-shadowObjects.define('token', function() {
-  console.log('The simplest shadow object ever.');
-});
-
-@ShadowObject('token')
-class Foo {
-  constructor({
-    entity,
-    provideContext,
-    useContext,
-    useProperty,
-    onDestroy,
-  }: ShadowObjectParams) {
-    console.log('hello');    
-    
-    onDestroy(() => {
-      console.log('bye');
-    });
-  }
-}
-```
+## Developer Guide
 
-> [!WARNING]
-> Sorry, at this point there should be a precise and crisp introduction to the concepts of the framework, but unfortunately this is not currently available.
-> Instead of that, a few insights into the implementation will follow
+### 1. Defining Shadow Objects
 
-## 📖 Shadow Objects CHEAT SHEET
+You can define a Shadow Object as a **Function** or a **Class**. Both receive a `ShadowObjectParams` object containing the API methods.
 
-There are two ways to create a _shadow object component_: either as a _function_ or as a _class_:
+#### Function-based (Recommended)
 
-### Create Shadow Object by FUNCTION
+```typescript
+import { ShadowObjectParams } from "@spearwolf/shadow-objects";
 
-```js
-import { onDestroy, type ShadowObjectParams, type Entity } from "@spearwolf/shadow-objects/shadow-objects.js";
+export function MyShadowObject({
+  useProperty,
+  useContext,
+  createEffect,
+  on,
+  onDestroy
+}: ShadowObjectParams) {
 
-function MyShadowObject(params: ShadowObjectParams) {
-  //
-  // ... PUT YOUR IMPLEMENTATION HERE ...
-  //
- 
-  // Return an object. This step is optional.
-  return {
-    // All methods here are reactive and correspond to entity events of the same name!
+  // 1. Read Properties
+  const title = useProperty("title");
 
-    [onDestroy](entity: Entity) {
-      // Called when the shadow object is destroyed.
-      // This is one of the predefined events that a shadow object can receive.
+  // 2. React to changes
+  createEffect(() => {
+    console.log("Title is now:", title());
+  });
 
-      // This can happen when the entity is destroyed or the shadow object component
-      // is removed from the entity (e.g., by changing the entity token, view properties, and/or routing)
-    },
+  // 3. Handle Lifecycle
+  onDestroy(() => {
+    console.log("Shadow Object destroyed");
+  });
 
-    fooBar(plah) {
-      /* is called when the entity receives a 'fooBar' event */
-    },
+  // 4. Return public methods (optional)
+  return {
+    someMethod() { /* ... */ }
   };
 }
 ```
 
-### Create Shadow Object by CLASS
+#### Class-based
 
-Essentially the same as above, but as a `class`:
+```typescript
+import { ShadowObjectParams } from "@spearwolf/shadow-objects";
 
-```js
-import { onDestroy, type ShadowObjectParams, type Entity } from "@spearwolf/shadow-objects/shadow-objects.js";
+export class MyShadowObject {
+  constructor({ useProperty, createEffect, onDestroy }: ShadowObjectParams) {
+    const title = useProperty("title");
 
-class MyShadowObject {
-  constructor(params: ShadowObjectParams) {
-    //
-    // ... INITIALIZE SHADOW OBJECT ...
-    //
-  }
+    createEffect(() => {
+      console.log("Title is now:", title());
+    });
 
-  [onDestroy](entity: Entity) {
-    // ...
+    onDestroy(() => this.cleanup());
   }
 
-  fooBar(plah) {
-    // ...
+  cleanup() {
+    console.log("Shadow Object destroyed");
   }
 }
 ```
 
-### Shadow Object Construction API
+### 2. The `ShadowObjectParams` API
+
+The `ShadowObjectParams` object provides all necessary tools to interact with the Entity, the View, and the Context system.
+
+| Method | Description |
+| :--- | :--- |
+| **`useProperty(name)`** | Returns a signal reader for a specific property on the Entity. Updates when the view property changes. |
+| **`useProperties(map)`** | Returns an object of signal readers for multiple properties. |
+| **`useContext(name)`** | Consumes a context value provided by a parent Entity. |
+| **`useParentContext(name)`** | Skips the current Entity and consumes context directly from the parent. |
+| **`provideContext(name, value)`** | Provides a context value (or signal) to descendant Entities. |
+| **`provideGlobalContext(name, value)`** | Provides a context value globally to all Entities. |
+| **`useResource(factory, cleanup)`** | Manages an external resource (e.g., a Three.js object) with automatic cleanup when dependencies change. |
+| **`createEffect(callback)`** | Runs a side effect whenever accessed signals change. |
+| **`createSignal(initialValue)`** | Creates a local reactive state signal. |
+| **`createMemo(factory)`** | Creates a derived signal that updates only when dependencies change. |
+| **`on(target, event, callback)`** | Listens for events on the Entity or other event targets. |
+| **`once(target, event, callback)`** | Listens for an event exactly once. |
+| **`onDestroy(callback)`** | Registers a callback to be executed when the Shadow Object is destroyed. |
+
+### 3. Registering Shadow Objects
+
+Shadow Objects are organized in **Modules**. A module defines which Tokens map to which Shadow Objects.
+
+```typescript
+// my-module.ts
+import { MyShadowObject } from "./MyShadowObject";
+
+export default {
+  // Map tokens to constructors
+  define: {
+    "my-component": MyShadowObject,
+  },
+  // Define routing rules
+  routes: {
+    "my-component": ["mixin-logger", "mixin-analytics"], // Composition
+    "@debug": ["debug-overlay"], // Conditional routing based on 'debug' property
+  }
+};
+```
 
-The parameters that a shadow object receives when it is created contain all the important API methods for exchanging data and events with the _view_ and also with the _shadow entity hierarchy and context_.
+### 4. View Integration
 
-[The interface `ShadowObjectsParams` is defined here](./src/types.ts)
+In your HTML or View layer, you use the provided Web Components to create the Entity hierarchy.
+
+```html
+<!-- 1. Initialize the Environment -->
+<shae-worker-env src="./my-module.js"></shae-worker-env>
 
-#### Properties
+<!-- 2. Create Entities -->
+<shae-ent token="my-component">
+  <!-- Properties -->
+  <shae-prop name="title" value="Hello World"></shae-prop>
+
+  <!-- Nested Entities -->
+  <shae-ent token="child-component"></shae-ent>
+</shae-ent>
+```
 
-__entity__: The shadow entity.
+---
 
-#### Methods
+## Architecture & Internals
 
-| Name | Call Signature | Description |
-|------|----------------|-------------|
-| __useProperty__ | `useProperty(name, isEqual?): SignalReader` | Read access to the property value from the view |
-| __useContext__ | `useContext(name, isEqual?): SignalReader` | Get the value for a named context. The context is derived from the shadow entity hierarchy and the shadow object's position within it. |
-| __useParentContext__ | `useParentContext(name, isEqual?): SignalReader` | Unlike the `useContext` method, this method skips the context of the _current_ shadow entity and directly requests the context of the parent entity. This is useful when you want to provide a custom context that depends on the parent context. |
-| __provideContext__ | `provideContext(name, initialValue?, isEqual?): Signal` | Specify a context. This context overrides (if set) the context of the same name from the entity's parent hierarchy. The context applies to the current entity and all child entities. |
-| __provideGlobalContext__ | `provideGlobalContext(name, initialValue?, isEqual?): Signal` | Define a context that applies to _all_ entities, regardless of hierarchy. |
-| __createEffect__ | `createEffect(...): Effect` | see [@spearwolf/signalize#createEffect()](https://github.com/spearwolf/signalize) |
-| __createSignal__ | `createSignal(...): Signal` | see [@spearwolf/signalize#createSignal()](https://github.com/spearwolf/signalize) |
-| __createMemo__ | `createMemo(...): SignalReader` | see [@spearwolf/signalize#createMemo()](https://github.com/spearwolf/signalize) |
-| __on__ | `on(...): UnsubscribeCallback` | see [@spearwolf/eventize#on()](https://github.com/spearwolf/eventize) |
-| __once__ | `once(...): UnsubscribeCallback` | see [@spearwolf/eventize#once()](https://github.com/spearwolf/eventize) |
-| __onDestroy__ | `onDestroy(callback)` | Called when the shadow object is destroyed. |
+### Lifecycle
 
+1.  **Creation**: When an Entity is created (e.g., `<shae-ent>` connects), the Kernel looks up its Token in the Registry.
+2.  **Instantiation**: The Kernel instantiates all Shadow Objects associated with that Token (and its routes).
+3.  **Execution**: The Shadow Object function runs, setting up signals, effects, and context providers.
+4.  **Updates**:
+    *   **Properties**: When view properties change, the Entity's signals update, triggering any dependent effects in the Shadow Object.
+    *   **Context**: If a parent Entity changes a provided context, child Shadow Objects consuming that context automatically update.
+5.  **Destruction**: When an Entity is removed or its Token changes, the Kernel destroys the associated Shadow Objects, cleaning up all signals and effects.
 
-## Documentation
+### Architecture Diagram
+
+```mermaid
+graph TD
+    View[View / DOM] -->|Messages| Kernel
+    Kernel -->|Updates| EntityTree[Entity Tree]
+
+    subgraph "Shadow World"
+        EntityTree
+        Entity[Entity]
+        SO[Shadow Object]
+
+        EntityTree --> Entity
+        Entity -->|Has| SO
+
+        SO -->|Reads| Props[Properties]
+        SO -->|Reads/Writes| Context
+        SO -->|Runs| Logic[Business Logic]
+    end
+
+    Logic -->|Updates| Signals
+    Signals -->|Triggers| Effects
+```
 
-TODO ... add documentation here ... !
+### Further Reading
 
-Here is the big class graph overview:
-![class graph overview](https://raw.githubusercontent.com/spearwolf/shadow-objects/main/packages/shadow-objects/src/view/ClassGraphOverview.drawio.svg)
+For deep dives into specific subsystems:
 
-More in-depth docs here:
-- [ShadowEnv](https://github.com/spearwolf/shadow-objects/blob/main/packages/shadow-objects/src/view/README.md)
-- [ComponentContext](https://github.com/spearwolf/shadow-objects/blob/main/packages/shadow-objects/src/view/ComponentContext.md)
-- [ViewComponent](https://github.com/spearwolf/shadow-objects/blob/main/packages/shadow-objects/src/view/ViewComponent.md)
+-   [**ShadowEnv**](src/view/README.md): The environment wrapper.
+-   [**ComponentContext**](src/view/ComponentContext.md): Context implementation details.
+-   [**ViewComponent**](src/view/ViewComponent.md): Base class for view components.