add tests and docs for emit from ShadowObjectCreationAPI

Author: spearwolf

packages/shadow-objects-testing/test/emit-helper/emit-helper.test.js

@@ -0,0 +1,72 @@
+import {expect} from '@esm-bundle/chai';
+import {on, once} from '@spearwolf/eventize';
+import {ComponentContext} from '@spearwolf/shadow-objects';
+import {shadowObjects} from '@spearwolf/shadow-objects/shadow-objects.js';
+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('ShadowObjectCreationAPI.emit helper', () => {
+  beforeEach(async () => {
+    render(`
+      <shae-worker local no-autostart auto-sync="no" id="localEnv" no-structured-clone></shae-worker>
+
+      <shae-ent id="a" token="A"></shae-ent>
+      <shae-ent id="b" token="B"></shae-ent>
+    `);
+
+    await Promise.all(['shae-worker', 'shae-ent'].map((name) => customElements.whenDefined(name)));
+  });
+
+  afterEach(() => {
+    ComponentContext.get().clear();
+    const localEnv = document.getElementById('localEnv');
+    if (localEnv && localEnv.shadowEnv) {
+      localEnv.shadowEnv.destroy();
+    }
+  });
+
+  it('emits events on the entity by default', async () => {
+    let emitted = false;
+
+    class MyShadowObject {
+      constructor({entity, emit}) {
+        once(entity, 'foo', () => {
+          emitted = true;
+        });
+        emit('foo');
+      }
+    }
+
+    shadowObjects.define('A', MyShadowObject);
+
+    const [localEnv] = findElementsById('localEnv');
+    await localEnv.start();
+    await localEnv.shadowEnv.syncWait();
+
+    expect(emitted).to.be.true;
+  });
+
+  it('emits events on a specific target if provided', async () => {
+    let emitted = false;
+
+    class MyShadowObject {
+      constructor({emit}) {
+        const otherObj = {};
+        on(otherObj, 'bar', () => {
+          emitted = true;
+        });
+        emit(otherObj, 'bar');
+      }
+    }
+
+    shadowObjects.define('B', MyShadowObject);
+
+    const [localEnv] = findElementsById('localEnv');
+    await localEnv.start();
+    await localEnv.shadowEnv.syncWait();
+
+    expect(emitted).to.be.true;
+  });
+});

packages/shadow-objects/docs/03-api/01-shadow-object-api.md

@@ -153,8 +153,8 @@ Listens for an event on a source.
 
 #### Listening to View Events
 
-### `on(entity, onViewEvent, callback)`
-### `onViewEvent(callback)`
+##### `on(entity, onViewEvent, callback)`
+##### `onViewEvent(callback)`
 
 To listen to events dispatched from the DOM (View Layer), listen to the special event name `onViewEvent` on the `entity` target.
 
@@ -187,6 +187,27 @@ function ShadowObject({ on, onViewEvent }: ShadowObjectCreationAPI) {
 
 Same as `on`, but the listener is automatically removed after the first trigger. Like `on`, if the first argument is a string, symbol, or array of strings/symbols, the `entity` is used as the event source.
 
+### `emit(eventNames, ...eventArgs)`
+
+Emits an event on the *entity* associated with the current shadow object.
+
+-   **`eventNames`** (`string` | `string[]`): The name(s) of the event(s) to emit.
+-   **`...eventArgs`** (`any[]`): Arguments to pass to the event listeners.
+
+### `emit(target, eventNames, ...eventArgs)`
+
+Emits an event on a specific *target* object.
+
+-   **`target`** (`Object`): The object to emit the event on. Must be compatible with the event system.
+-   **`eventNames`** (`string` | `string[]`): The name(s) of the event(s) to emit.
+-   **`...eventArgs`** (`any[]`): Arguments to pass to the event listeners.
+
+#### Best Practices
+
+*   **Use the default signature** (`emit('name')`) for events that represent the state or actions of the component itself. This allows parent components or other systems to listen to the entity easily.
+*   **Avoid tight coupling.** Use events to notify about changes rather than directly calling methods on other objects when possible.
+
+
 ---
 
 ## 5. View Integration

packages/shadow-objects/src/in-the-dark/Kernel.ts

@@ -628,10 +628,11 @@ export class Kernel {
           const [firstArg] = args;
           if (typeof firstArg === 'string' || typeof firstArg === 'symbol' || Array.isArray(firstArg)) {
             // @ts-ignore
-            return emit(entry.entity, ...args);
+            emit(entry.entity, ...args);
+          } else {
+            // @ts-ignore
+            emit(...args);
           }
-          // @ts-ignore
-          emit(...args);
         },
 
         onViewEvent(callback: (type: string, data: unknown) => any) {

packages/shadow-objects/src/types.ts

@@ -150,7 +150,20 @@ export interface ShadowObjectCreationAPI {
 
   onViewEvent(callback: (type: string, data: unknown) => any): void;
 
+  /**
+   * Emit an event on the *entity* associated with this shadow object.
+   *
+   * @param eventNames - The name(s) of the event(s) to emit.
+   * @param eventArgs - Arguments to pass to the event listeners.
+   */
   emit(eventNames: AnyEventNames, ...eventArgs: EventArgs): void;
+  /**
+   * Emit an event on a specific *target* object.
+   *
+   * @param target - The object to emit the event on.
+   * @param eventNames - The name(s) of the event(s) to emit.
+   * @param eventArgs - Arguments to pass to the event listeners.
+   */
   emit(target: EventizedObject, eventNames: AnyEventNames, ...eventArgs: EventArgs): void;
 
   onDestroy(callback: () => any): void;