Merge branch 'main' into copilot/improve-useproperties-type-definitions

Author: spearwolf

packages/shadow-objects/CHANGELOG.md

@@ -5,16 +5,15 @@ 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
+## Unreleased
 
-- sharpen the `EntityApi` type definitions
 - improve `useProperties()` type inference with key-to-type maps
+- **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.
+- **Refactor** the `EntityApi` type
 - **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`.
-    - Clarified the usage of Component Contexts, Namespacing (`ns` attribute), and decoupled placement of View Components.
-    - Documented the `local` (Main Thread) and `no-structured-clone` attributes for `<shae-worker>`.
-    - Documented the `order` property in ViewComponent API and Entity metadata for sorting/layering.
-    - Updated guides to reflect current API usage (e.g., `.viewComponent`).
 
 ## [0.27.0] - 2026-01-19
 

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

@@ -145,23 +145,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

@@ -588,14 +588,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

@@ -142,8 +142,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;
 }