@spearwolf/shadow-objects 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -5,17 +5,55 @@ 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.29.0] - 2026-01-21
+
+- **New Feature:** Added `forward-custom-events` attribute to `<shae-ent>` custom element.
+  - Allows forwarding events emitted by the internal `ViewComponent` (Shadow Object) as standard DOM `CustomEvent`s on the `<shae-ent>` element.
+  - Supports forwarding all events or filtering specific event types (e.g., `forward-custom-events="my-event,another-event"`).
+  - Event payload is passed as `detail` property of the `CustomEvent`.
+
+## [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
 
 ### ⚠️ Breaking Changes
 
 - **API Update:** `dispatchMessageToView` has been moved from the `entity` instance to the `ShadowObjectCreationAPI`.
-    - **Before:** `entity.dispatchMessageToView(...)`
-    - **After:** `dispatchMessageToView(...)` (available as an argument in the constructor/factory function)
+  - **Before:** `entity.dispatchMessageToView(...)`
+  - **After:** `dispatchMessageToView(...)` (available as an argument in the constructor/factory function)
 - **Type Definitions:** Removed `dispatchMessageToView` from `EntityApi` interface.
 
 ## [0.26.4] - 2026-01-15

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.