add forward-custom-events attribute

Author: spearwolf

packages/shadow-objects-testing/test/forward-custom-events.test.js

@@ -0,0 +1,87 @@
+import {expect} from '@esm-bundle/chai';
+import {ComponentContext} from '@spearwolf/shadow-objects';
+import '@spearwolf/shadow-objects/shae-ent.js';
+import '@spearwolf/shadow-objects/shae-worker.js';
+import {findElementsById} from '../src/findElementsById.js';
+import {render} from '../src/render.js';
+
+describe('forward-custom-events', () => {
+  beforeEach(async () => {
+    render(`
+      <shae-worker local no-autostart auto-sync="no" id="localEnv" no-structured-clone></shae-worker>
+
+      <shae-ent id="a" token="a" forward-custom-events></shae-ent>
+      <shae-ent id="b" token="b" forward-custom-events="foo"></shae-ent>
+      <shae-ent id="c" token="c" forward-custom-events="foo, bar"></shae-ent>
+    `);
+
+    await Promise.all(['shae-worker', 'shae-ent'].map((name) => customElements.whenDefined(name)));
+  });
+
+  afterEach(() => {
+    ComponentContext.get().clear();
+    document.getElementById('localEnv').shadowEnv.destroy();
+  });
+
+  it('should forward events as CustomEvents', async () => {
+    const [a, b, c, localEnv] = findElementsById('a', 'b', 'c', 'localEnv');
+
+    await localEnv.start();
+
+    const eventsA = [];
+    const eventsB = [];
+    const eventsC = [];
+
+    a.addEventListener('foo', (e) => eventsA.push(e));
+    a.addEventListener('bar', (e) => eventsA.push(e));
+    a.addEventListener('baz', (e) => eventsA.push(e));
+
+    b.addEventListener('foo', (e) => eventsB.push(e));
+    b.addEventListener('bar', (e) => eventsB.push(e));
+    b.addEventListener('baz', (e) => eventsB.push(e));
+
+    c.addEventListener('foo', (e) => eventsC.push(e));
+    c.addEventListener('bar', (e) => eventsC.push(e));
+    c.addEventListener('baz', (e) => eventsC.push(e));
+
+    // Simulate events arriving at the ViewComponent (from Shadow Objects)
+    a.viewComponent.dispatchEvent('foo', {val: 'a-foo'}, false);
+    a.viewComponent.dispatchEvent('bar', {val: 'a-bar'}, false);
+    a.viewComponent.dispatchEvent('baz', {val: 'a-baz'}, false);
+
+    b.viewComponent.dispatchEvent('foo', {val: 'b-foo'}, false);
+    b.viewComponent.dispatchEvent('bar', {val: 'b-bar'}, false);
+    b.viewComponent.dispatchEvent('baz', {val: 'b-baz'}, false);
+
+    c.viewComponent.dispatchEvent('foo', {val: 'c-foo'}, false);
+    c.viewComponent.dispatchEvent('bar', {val: 'c-bar'}, false);
+    c.viewComponent.dispatchEvent('baz', {val: 'c-baz'}, false);
+
+    // Events are synchronous when dispatched via dispatchEvent/emit locally?
+    // The on(...) subscription is synchronous.
+    // The CustomEvent dispatch is synchronous.
+    // So we don't need to wait for syncWait() unless there's an async process involved.
+    // But let's check.
+
+    // Check A (all events forwarded)
+    expect(eventsA).to.have.length(3);
+    expect(eventsA[0].type).to.equal('foo');
+    expect(eventsA[0].detail).to.deep.equal({val: 'a-foo'});
+    expect(eventsA[1].type).to.equal('bar');
+    expect(eventsA[1].detail).to.deep.equal({val: 'a-bar'});
+    expect(eventsA[2].type).to.equal('baz');
+    expect(eventsA[2].detail).to.deep.equal({val: 'a-baz'});
+
+    // Check B (only 'foo' forwarded)
+    expect(eventsB).to.have.length(1);
+    expect(eventsB[0].type).to.equal('foo');
+    expect(eventsB[0].detail).to.deep.equal({val: 'b-foo'});
+
+    // Check C (only 'foo' and 'bar' forwarded)
+    expect(eventsC).to.have.length(2);
+    expect(eventsC[0].type).to.equal('foo');
+    expect(eventsC[0].detail).to.deep.equal({val: 'c-foo'});
+    expect(eventsC[1].type).to.equal('bar');
+    expect(eventsC[1].detail).to.deep.equal({val: 'c-bar'});
+  });
+});

packages/shadow-objects/CHANGELOG.md

@@ -5,47 +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).
 
+## [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.
+  - 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
-        }
-      });
-      ```
+  - 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.
 
 ### ⚠️ 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)`
+  - 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

packages/shadow-objects/docs/01-concepts/04-entity-tree-context-events.md

@@ -9,32 +9,35 @@ This section explores the hierarchical nature of the Shadow World, explaining ho
 At the core of the Shadow World is the **Entity Tree**. This tree structure mirrors the hierarchy of your View components (e.g., the DOM structure of `<shae-ent>` elements).
 
 ### Hierarchy
-*   **Entities (Puppets):** These are the nodes in the tree. Every `<shae-ent>` in your HTML corresponds to one Entity instance in the Shadow World.
-*   **Shadow Objects (Logic):** Shadow Objects are **attached** to these Entities.
+
+- **Entities (Puppets):** These are the nodes in the tree. Every `<shae-ent>` in your HTML corresponds to one Entity instance in the Shadow World.
+- **Shadow Objects (Logic):** Shadow Objects are **attached** to these Entities.
 
 > [!IMPORTANT]
 > **Shadow Objects are NOT nodes in the tree.**
 > They are "components" or "behaviors" attached to an Entity node.
 >
-> *   An Entity can have multiple Shadow Objects (via Routing).
-> *   All Shadow Objects on the same Entity share the same properties and lifecycle.
+> - An Entity can have multiple Shadow Objects (via Routing).
+> - All Shadow Objects on the same Entity share the same properties and lifecycle.
 
 ## Context (Dependency Injection)
 
 Context allows you to share data deep into the component tree without passing props manually at every level ("prop drilling").
 
 ### How it Works
+
 1.  **Provider:** A Shadow Object on an Entity calls `provideContext`.
 2.  **Scope:** This value becomes available to:
-    *   **All other Shadow Objects on the same Entity.**
-    *   **All Shadow Objects on descendant (child) Entities.**
+    - **All other Shadow Objects on the same Entity.**
+    - **All Shadow Objects on descendant (child) Entities.**
 3.  **Consumer:** A Shadow Object calls `useContext` to read the value.
 
 ### Context is Entity-Bound
+
 Since Context is attached to the **Entity**, it acts as a shared bus for all logic attached to that node.
 
-*   If `ShadowObject A` provides a context, `ShadowObject B` (on the same Entity) can immediately consume it.
-*   This is the primary way to compose complex logic from smaller, reusable Shadow Objects.
+- If `ShadowObject A` provides a context, `ShadowObject B` (on the same Entity) can immediately consume it.
+- This is the primary way to compose complex logic from smaller, reusable Shadow Objects.
 
 ```mermaid
 graph TD
@@ -51,70 +54,78 @@ graph TD
 ```
 
 ### Reactivity
+
 Context values are **Signals**.
-*   If the Provider updates the value, all Consumers (even deep in the tree) update automatically.
-*   You don't need to subscribe manually; just reading the value in an effect creates a dependency.
+
+- If the Provider updates the value, all Consumers (even deep in the tree) update automatically.
+- You don't need to subscribe manually; just reading the value in an effect creates a dependency.
 
 ## Events
 
 The framework provides a powerful event system based on [@spearwolf/eventize](https://github.com/spearwolf/eventize). This allows decoupled communication between Shadow Objects, Entities, and the View.
 
 ### The Event Bus: The Entity
+
 Every Entity acts as an event emitter. Since multiple Shadow Objects can be attached to the same Entity, the Entity serves as a shared "bus" for them.
 
-*   **Shared Scope:** If one Shadow Object emits an event on its Entity, **all other Shadow Objects on that same Entity** can receive it.
-*   **Decoupling:** Shadow Objects don't need to know about each other; they just listen to the Entity they are attached to.
+- **Shared Scope:** If one Shadow Object emits an event on its Entity, **all other Shadow Objects on that same Entity** can receive it.
+- **Decoupling:** Shadow Objects don't need to know about each other; they just listen to the Entity they are attached to.
 
 ### 1. View -> Shadow Events
+
 Events dispatched by the View Component are automatically forwarded to the corresponding Entity as _View Events_.
 
-*   **View Layer:**
-    ```javascript
-    // In your Web Component or View Logic
-    this.viewComponent.dispatchShadowObjectsEvent('my-custom-event', { some: 'data' });
-    ```
-*   **Shadow World:**
-    ```typescript
-    // Your Shadow Object
-    export function MyLogic({ onViewEvent }: ShadowObjectCreationAPI) {
-      onViewEvent((type, data) => {
-        if (type === 'my-custom-event') {
-          console.log('Received from View:', data);
-        }
-      });
-    }
-    ```
+- **View Layer:**
+  ```javascript
+  // In your Web Component or View Logic
+  this.viewComponent.dispatchShadowObjectsEvent('my-custom-event', {some: 'data'});
+  ```
+- **Shadow World:**
+  ```typescript
+  // Your Shadow Object
+  export function MyLogic({onViewEvent}: ShadowObjectCreationAPI) {
+    onViewEvent((type, data) => {
+      if (type === 'my-custom-event') {
+        console.log('Received from View:', data);
+      }
+    });
+  }
+  ```
 
 ### 2. Shadow Object -> Shadow Object (Same Entity)
+
 Shadow Objects attached to the same Entity can communicate via events.
 
 ```typescript
-import { emit } from '@spearwolf/eventize';
+import {emit} from '@spearwolf/eventize';
 
 // Feature A
-export function FeatureA({ on }: ShadowObjectCreationAPI) {
+export function FeatureA({on}: ShadowObjectCreationAPI) {
   // Listen for event from Feature B
-  on('data-loaded', (data) => { /* ... */ });
+  on('data-loaded', (data) => {
+    /* ... */
+  });
 }
 
 // Feature B
-export function FeatureB({ entity }: ShadowObjectCreationAPI) {
+export function FeatureB({entity}: ShadowObjectCreationAPI) {
   // Emit event via the entity
-  emit(entity, 'data-loaded', { id: 123 });
+  emit(entity, 'data-loaded', {id: 123});
 }
 ```
 
 ### 3. Broadcasting to Children (Traverse the Entity Tree)
+
 You can broadcast events to all descendant Entities using the `traverse` helper. This is useful for "global" updates like a frame tick or a resize event.
 
 ```typescript
-import { emit } from '@spearwolf/eventize';
+import {emit} from '@spearwolf/eventize';
 
-export function StageController({ entity, on }: ShadowObjectCreationAPI) {
+export function StageController({entity, on}: ShadowObjectCreationAPI) {
   // Example: Broadcast a 'frame-update' event to the entire subtree
   on('tick', (deltaTime) => {
     entity.traverse((e) => {
-      emit(e, 'frame-update', { deltaTime });
+      emit(e, 'frame-update', {deltaTime});
     });
   });
 }
@@ -124,21 +135,26 @@ export function StageController({ entity, on }: ShadowObjectCreationAPI) {
 > `traverse()` visits first the current entity and then all its descendants recursively.
 
 ### 4. Shadow -> View Events
+
 You can send events back to the View Layer using `dispatchMessageToView`.
 
-*   **Shadow World:**
-    ```typescript
-    export function MyLogic({ dispatchMessageToView }: ShadowObjectCreationAPI) {
-      dispatchMessageToView('notify', { message: 'Save successful!' });
-    }
-    ```
-*   **View Layer:**
-    ```javascript
-    import {on} from '@spearwolf/eventize';
-
-    on(viewComponent, {
-      notify(data) {
-        console.log('Received a notification:', data);
-      }
-    });
-    ```
+- **Shadow World:**
+  ```typescript
+  export function MyLogic({dispatchMessageToView}: ShadowObjectCreationAPI) {
+    dispatchMessageToView('notify', {message: 'Save successful!'});
+  }
+  ```
+- **View Layer:**
+
+  ```javascript
+  import {on} from '@spearwolf/eventize';
+
+  on(viewComponent, {
+    notify(data) {
+      console.log('Received a notification:', data);
+    },
+  });
+  ```
+
+> [!TIP]
+> **Forwarding to DOM:** If you are using `<shae-ent>`, you can automatically forward these events to the DOM element using the `forward-custom-events` attribute. See the [Web Components API](../03-api/04-web-components.md#forward-custom-events) for details.