feat: enhance ShadowObjectCreationAPI with implicit event target support for on() and once() methods

Author: spearwolf

packages/shadow-objects/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## unreleased
 
+- **API Update:** `on()` and `once()` in `ShadowObjectCreationAPI` now support an implicit event target.
+    - If the first argument is a `string`, `symbol`, or `string[]`, 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.
 - sharpen the `EntityApi` type definitions
 - **Documentation:** Comprehensive update to the documentation structure and content.
     - Added dedicated documentation for Web Components (`<shae-worker>`, `<shae-ent>`, `<shae-prop>`) at `docs/03-api/04-web-components.md`.

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

@@ -141,23 +141,32 @@ Shadow Objects can communicate via an event system that mirrors standard DOM eve
 
 Listens for an event on a target.
 
-*   **Signature:** `on(target: object, event: string, callback: (type: string, data: any) => void): void`
+*   **Signature:**
+    *   `on(target: object, event: string, callback: Listener): void`
+    *   `on(event: string | symbol | string[], callback: Listener): void` (implicitly uses `entity` as target)
 *   **Targets:** Usually `entity` (the current entity instance).
+*   **Automatic Cleanup:** Subscriptions created via `on()` are automatically removed when the Shadow Object is destroyed.
 
 #### Listening to View Events
 To listen to events dispatched from the DOM (View Layer), listen to the special event name `'onViewEvent'` on the `entity` target.
 
 ```typescript
-on(entity, 'onViewEvent', (type, data) => {
+// Implicitly listens on the entity
+on('onViewEvent', (type, data) => {
     if (type === 'click') {
         console.log('Clicked!', data);
     }
 });
+
+// Explicit target (equivalent to above)
+on(entity, 'onViewEvent', (type, data) => {
+   // ...
+});
 ```
 
 ### `once(target, eventName, callback)`
 
-Same as `on`, but the listener is automatically removed after the first trigger.
+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 target.
 
 ---
 

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

@@ -586,14 +586,28 @@ export class Kernel {
           return sig;
         },
 
-        on(...args: Parameters<typeof on>): ReturnType<typeof on> {
+        on(...args: any[]): ReturnType<typeof on> {
+          const [firstArg] = args;
+          if (typeof firstArg === 'string' || typeof firstArg === 'symbol' || Array.isArray(firstArg)) {
+            // @ts-ignore
+            const unsub = on(entry.entity, ...args);
+            unsubscribeSecondary.add(unsub);
+            return unsub;
+          }
           // @ts-ignore
           const unsub = on(...args);
           unsubscribeSecondary.add(unsub);
           return unsub;
         },
 
-        once(...args: Parameters<typeof once>): ReturnType<typeof once> {
+        once(...args: any[]): ReturnType<typeof once> {
+          const [firstArg] = args;
+          if (typeof firstArg === 'string' || typeof firstArg === 'symbol' || Array.isArray(firstArg)) {
+            // @ts-ignore
+            const unsub = once(entry.entity, ...args);
+            unsubscribeSecondary.add(unsub);
+            return unsub;
+          }
           // @ts-ignore
           const unsub = once(...args);
           unsubscribeSecondary.add(unsub);

packages/shadow-objects/src/types.ts

@@ -140,8 +140,11 @@ export interface ShadowObjectCreationAPI {
   createSignal<T = unknown>(...args: Parameters<typeof createSignal<T>>): ReturnType<typeof createSignal<T>>;
   createMemo<T = unknown>(...args: Parameters<typeof createMemo<T>>): SignalReader<T>;
 
-  on(...args: Parameters<typeof on>): ReturnType<typeof on>; // TODO fix args type
-  once(...args: Parameters<typeof once>): ReturnType<typeof once>; // TODO fix args type
+  on(eventName: string | symbol | Array<string | symbol>, ...args: any[]): ReturnType<typeof on>;
+  on(...args: Parameters<typeof on>): ReturnType<typeof on>;
+
+  once(eventName: string | symbol | Array<string | symbol>, ...args: any[]): ReturnType<typeof once>;
+  once(...args: Parameters<typeof once>): ReturnType<typeof once>;
 
   onDestroy(callback: () => any): void;
 }