@alwatr/action 9.12.0 → 9.14.0

package/dist/method.d.ts

@@ -1,74 +1,99 @@
+import type { Awaitable } from '@alwatr/type-helper';
 import type { SubscribeResult } from '@alwatr/signal';
 import { type ModifierHandler, type PayloadResolver } from './registry.js';
+import type { ActionRecord } from './action-record.js';
 export type { ModifierHandler, PayloadResolver };
 /**
  * Subscribes to a named action dispatched anywhere in the application.
  *
- * The handler is invoked every time `dispatchAction(actionId, payload)` is
- * called — whether from an `on-action` directive or from code — and the
- * `actionId` matches. Multiple subscribers for the same `actionId` are all
- * notified in subscription order.
+ * `actionId` must be a key of `ActionRecord`. The handler's `payload` parameter
+ * is automatically typed to the corresponding `ActionRecord` value — no manual
+ * generic annotation needed:
  *
- * The generic parameter `T` narrows the type of the received payload.
- * Defaults to `string`, which covers the common case of attribute-driven
- * literal payloads.
+ * ```ts
+ * // ActionRecord declares: 'add-to-cart': {productId: number; qty: number}
+ * onAction('add-to-cart', (item) => {
+ *   cartService.add(item.productId, item.qty); // fully typed, no `!` needed
+ * });
+ * ```
  *
- * @param actionId - The action identifier to listen for (e.g. `'open-drawer'`).
- * @param handler  - Callback invoked with the resolved payload each time the
- *                   action is dispatched. `payload` is `undefined` when the
- *                   action was dispatched without a value.
- * @returns A `SubscribeResult` with an `unsubscribe()` method for cleanup.
+ * Passing an action name not declared in `ActionRecord` is a **compile error**.
+ * Register new actions by extending `ActionRecord` via declaration merging:
  *
- * @example — basic string payload
  * ```ts
- * import {onAction} from '@alwatr/action';
+ * // src/action-record.ts
+ * declare module '@alwatr/action' {
+ *   interface ActionRecord {
+ *     'open-drawer': string;
+ *   }
+ * }
+ * ```
  *
- * const sub = onAction('open-drawer', (panel) => {
- *   openDrawer(panel); // panel === 'settings'
- * });
+ * Internally delegates to `ChannelSignal.on()` for **O(1) routing** — dispatching
+ * action `'A'` never invokes handlers registered for action `'B'`.
  *
- * // Stop listening when the component is destroyed
- * sub.unsubscribe();
- * ```
+ * @param actionId - A key of `ActionRecord`.
+ * @param handler  - Callback invoked with the typed payload on each dispatch.
+ * @returns A `SubscribeResult` with an `unsubscribe()` method for cleanup.
  *
- * @example — typed object payload
+ * @example
  * ```ts
  * import {onAction} from '@alwatr/action';
  *
- * onAction<{productId: number; qty: number}>('add-to-cart', (item) => {
- *   cartService.add(item!.productId, item!.qty);
+ * const sub = onAction('page-ready', (pageId) => {
+ *   router.setPage(pageId); // pageId: string — inferred from ActionRecord
  * });
+ *
+ * sub.unsubscribe(); // stop listening when no longer needed
  * ```
  */
-export declare function onAction<T = string>(actionId: string, handler: (payload?: T) => void): SubscribeResult;
+export declare function onAction<K extends keyof ActionRecord>(actionId: K, handler: (payload: ActionRecord[K]) => Awaitable<void>): SubscribeResult;
 /**
  * Dispatches a named action to all `onAction` subscribers with a matching `actionId`.
  *
- * This is the programmatic counterpart to the `on-action` HTML attribute.
- * Use it when you need to trigger an action from code rather than from a DOM
- * event (e.g. after an async operation completes, or from a service layer).
+ * `actionId` must be a key of `ActionRecord`. The `payload` parameter is
+ * automatically typed — passing the wrong type is a **compile error**:
  *
- * The generic parameter `T` types the payload. Omit it to default to `string`.
+ * ```ts
+ * // ActionRecord declares: 'add-to-cart': {productId: number; qty: number}
+ * dispatchAction('add-to-cart', {productId: 42, qty: 1}); // ✅
+ * dispatchAction('add-to-cart', 'wrong');                  // ❌ compile error
+ * dispatchAction('unknown-action', 'x');                   // ❌ compile error
+ * ```
  *
- * @param actionId     - The action identifier (e.g. `'navigate'`).
- * @param actionPayload - Optional value passed to every matching subscriber.
+ * Register new actions by extending `ActionRecord` via declaration merging:
  *
- * @example — dispatch without payload
  * ```ts
- * import {dispatchAction} from '@alwatr/action';
- *
- * dispatchAction('logout');
+ * // src/action-record.ts
+ * declare module '@alwatr/action' {
+ *   interface ActionRecord {
+ *     'navigate': string;
+ *     'logout': void;
+ *   }
+ * }
  * ```
  *
- * @example — dispatch with a typed payload
+ * Use `dispatchAction` when triggering an action from code — e.g. after an
+ * async operation, from a service layer, or in tests. For DOM-driven actions,
+ * use the `on-action` HTML attribute with `setupActionDelegation`.
+ *
+ * @param actionId      - A key of `ActionRecord`.
+ * @param actionPayload - The payload; type is enforced by `ActionRecord`.
+ *
+ * @example — with payload
  * ```ts
  * import {dispatchAction} from '@alwatr/action';
  *
+ * dispatchAction('page-ready', 'home');
  * dispatchAction('navigate', '/dashboard');
- * dispatchAction<{code: number}>('show-error', {code: 404});
+ * ```
+ *
+ * @example — void payload (no second argument)
+ * ```ts
+ * dispatchAction('logout');
  * ```
  */
-export declare function dispatchAction<T = string>(actionId: string, actionPayload?: T): void;
+export declare function dispatchAction<K extends keyof ActionRecord>(...args: ActionRecord[K] extends void | undefined ? [actionId: K] : [actionId: K, actionPayload: ActionRecord[K]]): void;
 /**
  * Registers a custom modifier that can be used in `on-action` attribute syntax.
  *
@@ -76,22 +101,20 @@ export declare function dispatchAction<T = string>(actionId: string, actionPaylo
  * (e.g. `click.mymod->action-id`). Its handler runs before the payload is
  * resolved and the action is dispatched. Returning `false` cancels the dispatch.
  *
- * Built-in modifiers (`prevent`, `stop`, `validate`, `once`, `passive`) are
- * always available. This function lets you add domain-specific ones.
+ * Built-in modifiers (`prevent`, `stop`, `validate`, `once`) are always
+ * available. This function lets you add domain-specific ones.
  *
  * Registering the same name twice logs an accident and overwrites the previous
  * handler — avoid duplicate registrations in production code.
  *
  * @param name    - The modifier token (lowercase, no dots or arrows).
- * @param handler - The `ModifierHandler` function bound to the directive instance.
+ * @param handler - A `ModifierHandler` receiving `(event, element)`.
  *
  * @example — a `confirm` modifier that shows a browser dialog
  * ```ts
  * import {registerModifier} from '@alwatr/action';
  *
- * registerModifier('confirm', function () {
- *   return window.confirm('Are you sure?');
- * });
+ * registerModifier('confirm', () => window.confirm('Are you sure?'));
  * ```
  * ```html
  * <button on-action="click.confirm->delete-item:42">Delete</button>
@@ -103,7 +126,7 @@ export declare function registerModifier(name: string, handler: ModifierHandler)
  *
  * A payload resolver is a colon-suffixed token in the attribute value
  * (e.g. `click->action-id:$mytoken`). Its function is called at dispatch time
- * with the directive instance as `this` and the DOM event as the argument.
+ * with an `ActionContext` as `this` and the DOM event as the argument.
  * The return value becomes the `actionPayload` passed to `onAction` subscribers.
  *
  * Built-in resolvers (`$value`, `$formdata`) are always available. This function
@@ -113,29 +136,19 @@ export declare function registerModifier(name: string, handler: ModifierHandler)
  * resolver — avoid duplicate registrations in production code.
  *
  * @param name     - The resolver token (should start with `$` by convention).
- * @param resolver - The `PayloadResolver` function bound to the directive instance.
+ * @param resolver - A `PayloadResolver` receiving `(event, element)`.
  *
  * @example — a `$checked` resolver for checkbox state
  * ```ts
  * import {registerPayloadResolver} from '@alwatr/action';
  *
- * registerPayloadResolver('$checked', function () {
- *   return (this.element_ as HTMLInputElement).checked;
+ * registerPayloadResolver('$checked', (_event, element) => {
+ *   return (element as HTMLInputElement).checked;
  * });
  * ```
  * ```html
  * <input type="checkbox" on-action="change->toggle-feature:$checked" />
  * ```
- *
- * @example — a `$dataset-id` resolver for data attributes
- * ```ts
- * registerPayloadResolver('$dataset-id', function () {
- *   return (this.element_ as HTMLElement).dataset.id ?? null;
- * });
- * ```
- * ```html
- * <li on-action="click->select-item:$dataset-id" data-id="42">Item</li>
- * ```
  */
 export declare function registerPayloadResolver(name: string, resolver: PayloadResolver): void;
 //# sourceMappingURL=method.d.ts.map

package/dist/method.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"method.d.ts","sourceRoot":"","sources":["../src/method.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAoC,KAAK,eAAe,EAAE,KAAK,eAAe,EAAC,MAAM,eAAe,CAAC;AAG5G,YAAY,EAAC,eAAe,EAAE,eAAe,EAAC,CAAC;AAI/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,QAAQ,CAAC,CAAC,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,eAAe,CAQtG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,CAAC,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,CAAC,GAAG,IAAI,CAGpF;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAM7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAMrF"}
+{"version":3,"file":"method.d.ts","sourceRoot":"","sources":["../src/method.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAoC,KAAK,eAAe,EAAE,KAAK,eAAe,EAAC,MAAM,eAAe,CAAC;AAC5G,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAGrD,YAAY,EAAC,eAAe,EAAE,eAAe,EAAC,CAAC;AAI/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,YAAY,EACnD,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,IAAI,CAAC,GACrD,eAAe,CAGjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,YAAY,EACzD,GAAG,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,SAAS,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,EAAE,aAAa,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,GAChH,IAAI,CAIN;AAID;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAM7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAMrF"}

package/dist/registry.d.ts

@@ -1,36 +1,41 @@
-import type { ActionDirective } from './directive.js';
 /**
- * A modifier handler attached to an `on-action` directive.
+ * A modifier handler used in `on-action` attribute syntax.
  *
- * Called with the directive instance as `this` and the triggering DOM `event`.
- * Return `true` to allow the action to proceed, or `false` to cancel it.
- * Returning `false` is the only way a modifier can veto a dispatch.
+ * Receives the triggering DOM `event` and the `element` that owns the
+ * `on-action` attribute. Return `true` (or any truthy value) to allow the
+ * action to proceed, or `false` to cancel the dispatch.
+ *
+ * Using explicit parameters instead of `this` binding makes handlers
+ * compatible with arrow functions and easier to test in isolation.
  *
  * @example
  * ```ts
  * // A modifier that only allows the action when the element is not disabled
- * const notDisabledHandler: ModifierHandler = function () {
- *   return !(this.element_ as HTMLButtonElement).disabled;
+ * const notDisabledHandler: ModifierHandler = (_event, element) => {
+ *   return !(element as HTMLButtonElement).disabled;
  * };
  * ```
  */
-export type ModifierHandler = (this: ActionDirective, event: Event) => boolean;
+export type ModifierHandler = (event: Event, element: HTMLElement) => boolean;
 /**
- * A payload resolver attached to an `on-action` directive.
+ * A payload resolver used in `on-action` attribute syntax.
+ *
+ * Receives the triggering DOM `event` and the `element` that owns the
+ * `on-action` attribute. The return value becomes the `actionPayload` passed
+ * to `onAction` subscribers. Use this to compute dynamic payloads from DOM state.
  *
- * Called with the directive instance as `this` and the triggering DOM `event`
- * at dispatch time. The return value becomes the `actionPayload` of the
- * dispatched action. Use this to compute dynamic payloads from the DOM state.
+ * Using explicit parameters instead of `this` binding makes resolvers
+ * compatible with arrow functions and easier to test in isolation.
  *
  * @example
  * ```ts
  * // A resolver that returns the element's dataset id
- * const dataIdResolver: PayloadResolver = function () {
- *   return (this.element_ as HTMLElement).dataset.id ?? null;
+ * const dataIdResolver: PayloadResolver = (_event, element) => {
+ *   return (element as HTMLElement).dataset.id ?? null;
  * };
  * ```
  */
-export type PayloadResolver = (this: ActionDirective, event: Event) => unknown;
+export type PayloadResolver = (event: Event, element: HTMLElement) => unknown;
 /**
  * Registry of all named modifier handlers.
  *

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAIpD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;AAE/E;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;AAI/E;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,8BAAqC,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,8BAAqC,CAAC"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC;AAE9E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC;AAI9E;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,8BAAqC,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,8BAAqC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwatr/action",
-  "version": "9.12.0",
+  "version": "9.14.0",
   "description": "Declarative DOM action-dispatch — bridge HTML attributes to typed signal handlers.",
   "license": "MPL-2.0",
   "author": "S. Ali Mihandoost <ali.mihandoost@gmail.com> (https://ali.mihandoost.com)",
@@ -21,15 +21,13 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@alwatr/directive": "9.11.2",
-    "@alwatr/logger": "9.11.2",
-    "@alwatr/signal": "9.12.0"
+    "@alwatr/logger": "9.14.0",
+    "@alwatr/signal": "9.14.0"
   },
   "devDependencies": {
-    "@alwatr/nano-build": "9.10.1",
-    "@alwatr/standard": "9.11.2",
-    "@alwatr/type-helper": "9.11.2",
-    "@happy-dom/global-registrator": "^20.9.0",
+    "@alwatr/nano-build": "9.14.0",
+    "@alwatr/standard": "9.14.0",
+    "@alwatr/type-helper": "9.14.0",
     "typescript": "^6.0.3"
   },
   "scripts": {
@@ -81,5 +79,5 @@
     "vanilla-js",
     "web-development"
   ],
-  "gitHead": "b4ca873ebd15cd2e25b34273d76febfd75267b62"
+  "gitHead": "4e499b23191d4460ea60f34cde8a99b472741f1a"
 }

package/src/action-record.ts

@@ -0,0 +1,54 @@
+/**
+ * @file action-record.ts
+ *
+ * Global action type registry via TypeScript declaration merging.
+ *
+ * ## How it works
+ *
+ * `ActionRecord` is an open interface — any package in the monorepo (or any
+ * consumer application) can extend it with their own action names and payload
+ * types using declaration merging, without modifying this file:
+ *
+ * ```ts
+ * // In your package: src/action-record.ts
+ * declare module '@alwatr/action' {
+ *   interface ActionRecord {
+ *     'open-drawer': string;
+ *     'add-to-cart': {productId: number; qty: number};
+ *     'logout': void;
+ *   }
+ * }
+ * ```
+ *
+ * Once declared, `onAction` and `dispatchAction` become fully type-safe for
+ * those action names — the compiler enforces the correct payload type at every
+ * call site and provides autocomplete for action identifiers.
+ *
+ * Only actions declared in `ActionRecord` are accepted. Passing an unknown
+ * action name is a **compile error** — there is no string fallback.
+ */
+
+/**
+ * Global registry mapping action identifiers to their payload types.
+ *
+ * Extend this interface via declaration merging to register your application's
+ * actions and gain full type safety in `onAction` and `dispatchAction`.
+ *
+ * This interface is intentionally empty in the base package — all actions are
+ * application-specific and should be declared in a dedicated `action-record.ts`
+ * file within each feature package.
+ *
+ * @example — registering actions in a feature package
+ * ```ts
+ * // pkg/my-feature/src/action-record.ts
+ * declare module '@alwatr/action' {
+ *   interface ActionRecord {
+ *     'open-drawer': string;
+ *     'add-to-cart': {productId: number; qty: number};
+ *     'logout': void;
+ *   }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface ActionRecord {}