@spearwolf/shadow-objects 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -5,9 +5,39 @@ All notable changes to [@spearwolf/shadow-objects](https://github.com/spearwolf/
 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).
 
-## unreleased
+## [0.28.0] - 2026-01-20
+
+- **API Update:** `on()` and `once()` in `ShadowObjectCreationAPI` now support an implicit event source.
+    - If the first argument is a `string`, `symbol`, or `[]`, the `entity` is automatically used as the event source.
+    - Example: `on('eventName', callback)` is equivalent to `on(entity, 'eventName', callback)`.
+    - This simplifies the common case of listening to entity events.
+- **API Update:** introduce `onViewEvent()` in `ShadowObjectCreationAPI`
+    - Simplifies listening to view events dispatched to the entity.
+    - Example:
+      ```typescript
+      onViewEvent((type, data) => {
+        if (type === 'my-event') {
+          // handle event
+        }
+      });
+      ```
+- **Refactor** the `EntityApi` type
+- **Refactor** the `useProperties` supports type maps now
+- **Documentation:** Comprehensive update to the documentation structure and content.
 
-- sharpen the `EntityApi` type definitions
+### ⚠️ Breaking Changes
+- The _entity_ events `onCreate`, `onDestroy`, `onParentChanged` and `onViewEvent` changed to _symbols_.
+    - Update your event listeners accordingly:
+      - import the event symbols from the package:
+        ```typescript
+        import { onCreate, onDestroy, onParentChanged, onViewEvent } from '@spearwolf/shadow-objects/shadow-objects.js';
+        ```
+      - _Functional Shadow-Objects:_
+        - **Before:** `on(entity, 'onCreate', ...)`
+        - **After:** `on(onCreate, ...)`
+      - _Class-based Shadow-Objects:_
+        - **Before:** `onCreate(entity)`
+        - **After:** `[onCreate](entity)`
 
 ## [0.27.0] - 2026-01-19
 

package/README.md

@@ -1,51 +1,18 @@
-# Shadow Objects Framework 🧛
+# Shadow Objects Framework
 
-The **Shadow Objects Framework** is a reactive library designed to decouple business logic and state management from the UI rendering layer. It allows your application logic to run "in the dark" (typically in a Web Worker), mirroring the view hierarchy of your application.
+This package contains the core library for the **Shadow Objects Framework**.
 
-> [!WARNING]
-> 🚀 This is a highly experimental framework that is slowly maturing. Use at your own risk. 🔥
+**👉 [Read the Documentation](./docs/README.md)**
 
-## Documentation
+## Contents
 
-**👉 The complete and authoritative documentation is located in the [docs/](./docs/) directory.**
+*   [**Concepts**](./docs/01-concepts/): Understand the mental model, architecture, and lifecycle.
+*   [**Guides**](./docs/02-guides/): Step-by-step instructions.
+*   [**API Reference**](./docs/03-api/): Detailed API docs.
+*   [**Best Practices & Patterns**](./docs/04-patterns/): Idiomatic usage and design patterns.
 
-*   [**Fundamentals**](./docs/01-fundamentals/): Understand the mental model, architecture, and lifecycle.
-*   [**Guides**](./docs/02-guides/): Step-by-step instructions for getting started and building with Shadow Objects.
-*   [**API Reference**](./docs/03-api/): Detailed API documentation for Shadow Objects and the Registry.
-
-## Overview
-
-### What is it?
-
-Shadow Objects creates a strict separation between the **View** (what the user sees) and the **Logic** (how the application behaves).
-
-*   **View (Browser Window):** Handles rendering and user input. It remains lightweight and "dumb".
-*   **Logic (Web Worker):** Manages state, side effects, and business rules. It is organized as "Shadow Objects" that are attached to abstract "Entities".
-
-### Installation
-
-The framework is available as an npm package:
+## Installation
 
 ```bash
 npm install @spearwolf/shadow-objects
 ```
-
-### Integration
-
-To integrate Shadow Objects into your project, you connect the View to your Logic using tokens.
-
-1.  **Define Logic**: Write your Shadow Objects (logic units) using the functional API.
-2.  **Register**: Map your Shadow Objects to **Tokens** in a module definition.
-3.  **Connect View**: Use the provided Web Components to load your module and build your UI hierarchy.
-
-```html
-<!-- 1. Initialize the Environment & Load Logic -->
-<shae-worker src="./my-logic-module.js"></shae-worker>
-
-<!-- 2. Create Entities in the View -->
-<shae-ent token="my-feature">
-    <!-- The framework automatically instantiates the Shadow Object mapped to "my-feature" in the worker -->
-</shae-ent>
-```
-
-For detailed setup instructions, please refer to the [Getting Started](./docs/02-guides/01-getting-started.md) guide.