@alwatr/action 9.14.0 → 9.17.0

package/src/method.ts

@@ -1,25 +1,30 @@
 import type {Awaitable} from '@alwatr/type-helper';
-import {internalChannel_, logger_} from './lib.js';
 import type {SubscribeResult} from '@alwatr/signal';
+
+import {internalChannel_, logger_} from './lib.js';
 import {modifierRegistry, payloadRegistry, type ModifierHandler, type PayloadResolver} from './registry.js';
 import type {ActionRecord} from './action-record.js';
+import type {Action} from './action.js';
 
 // Re-export extension types so consumers can import them from the package root.
 export type {ModifierHandler, PayloadResolver};
+export type {Action};
 
 // ─── Core Action API ──────────────────────────────────────────────────────────
 
 /**
  * Subscribes to a named action dispatched anywhere in the application.
  *
- * `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:
+ * `type` must be a key of `ActionRecord`. The handler receives the full
+ * `Action<K>` object — giving access to `payload`, `context`, and `meta`
+ * in one place. No manual generic annotation is needed; the compiler infers
+ * the correct `payload` type from `ActionRecord`:
  *
  * ```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
+ * // ActionRecord declares: 'add_to_cart': {productId: number; qty: number}
+ * onAction('add_to_cart', (action) => {
+ *   cartService.add(action.payload.productId, action.payload.qty); // fully typed
+ *   console.log(action.context); // e.g. 'product-list' (from DOM) or undefined
  * });
  * ```
  *
@@ -30,7 +35,7 @@ export type {ModifierHandler, PayloadResolver};
  * // src/action-record.ts
  * declare module '@alwatr/action' {
  *   interface ActionRecord {
- *     'open-drawer': string;
+ *     'open_drawer': string;
  *   }
  * }
  * ```
@@ -38,99 +43,103 @@ export type {ModifierHandler, PayloadResolver};
  * Internally delegates to `ChannelSignal.on()` for **O(1) routing** — dispatching
  * action `'A'` never invokes handlers registered for action `'B'`.
  *
- * @param actionId - A key of `ActionRecord`.
- * @param handler  - Callback invoked with the typed payload on each dispatch.
+ * @param type    - A key of `ActionRecord`.
+ * @param handler - Callback invoked with the full `Action<K>` on each dispatch.
  * @returns A `SubscribeResult` with an `unsubscribe()` method for cleanup.
  *
  * @example
  * ```ts
  * import {onAction} from '@alwatr/action';
  *
- * const sub = onAction('page-ready', (pageId) => {
- *   router.setPage(pageId); // pageId: string — inferred from ActionRecord
+ * const sub = onAction('page_ready', (action) => {
+ *   router.setPage(action.payload); // payload: string — inferred from ActionRecord
  * });
  *
  * sub.unsubscribe(); // stop listening when no longer needed
  * ```
  */
 export function onAction<K extends keyof ActionRecord>(
-  actionId: K,
-  handler: (payload: ActionRecord[K]) => Awaitable<void>,
+  type: K,
+  handler: (action: Action<K>) => Awaitable<void>,
 ): SubscribeResult {
-  logger_.logMethodArgs?.('onAction', {actionId});
-  return internalChannel_.on(actionId, handler as (payload: unknown) => Awaitable<void>);
+  logger_.logMethodArgs?.('onAction', {type});
+  // The internal channel stores Action<any>; we cast to Action<K> here because
+  // the channel key guarantees the type matches — only Action<K> objects are
+  // ever dispatched under key K.
+  return internalChannel_.on(type, handler as (action: Action) => Awaitable<void>);
 }
 
 /**
- * Dispatches a named action to all `onAction` subscribers with a matching `actionId`.
+ * Dispatches an action to all `onAction` subscribers with a matching `type`.
  *
- * `actionId` must be a key of `ActionRecord`. The `payload` parameter is
- * automatically typed — passing the wrong type is a **compile error**:
+ * Accepts a full `Action<K>` object. The `payload` field is automatically
+ * typed from `ActionRecord[K]` — passing the wrong shape is a **compile error**:
  *
  * ```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
+ * // ActionRecord declares: 'add_to_cart': {productId: number; qty: number}
+ * dispatchAction({type: 'add_to_cart', payload: {productId: 42, qty: 1}}); // ✅
+ * dispatchAction({type: 'add_to_cart', payload: 'wrong'});                  // ❌ compile error
+ * dispatchAction({type: 'unknown_action', payload: 'x'});                   // ❌ compile error
  * ```
  *
- * Register new actions by extending `ActionRecord` via declaration merging:
- *
- * ```ts
- * // src/action-record.ts
- * declare module '@alwatr/action' {
- *   interface ActionRecord {
- *     'navigate': string;
- *     'logout': void;
- *   }
- * }
- * ```
+ * The `context` and `meta` fields are optional. When dispatching from code
+ * (not from the DOM), omit `context` — it is only meaningful for DOM-originated
+ * actions where an `[action-context]` ancestor exists.
  *
  * 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`.
+ * use the `on-<eventType>` HTML attribute with `setupActionDelegation`.
  *
- * @param actionId      - A key of `ActionRecord`.
- * @param actionPayload - The payload; type is enforced by `ActionRecord`.
+ * @param action - A full `Action<K>` object with at minimum `type` and `payload`.
  *
  * @example — with payload
  * ```ts
  * import {dispatchAction} from '@alwatr/action';
  *
- * dispatchAction('page-ready', 'home');
- * dispatchAction('navigate', '/dashboard');
+ * dispatchAction({type: 'navigate', payload: '/dashboard'});
+ * dispatchAction({type: 'add_to_cart', payload: {productId: 42, qty: 1}});
  * ```
  *
- * @example — void payload (no second argument)
+ * @example — void payload
  * ```ts
- * dispatchAction('logout');
+ * dispatchAction({type: 'logout', payload: undefined});
+ * ```
+ *
+ * @example — with context and meta
+ * ```ts
+ * dispatchAction({
+ *   type: 'slider_change',
+ *   payload: 75,
+ *   context: 'volume_slider',
+ *   meta: {traceId: 'abc-123'},
+ * });
  * ```
  */
-export function dispatchAction<K extends keyof ActionRecord>(
-  ...args: ActionRecord[K] extends void | undefined ? [actionId: K] : [actionId: K, actionPayload: ActionRecord[K]]
-): void {
-  const [actionId, actionPayload] = args;
-  logger_.logMethodArgs?.('dispatchAction', {actionId, actionPayload});
-  internalChannel_.dispatch(actionId, actionPayload);
+export function dispatchAction<K extends keyof ActionRecord>(action: Action<K>): void {
+  logger_.logMethodArgs?.('dispatchAction', action);
+  internalChannel_.dispatch(action.type, action);
 }
 
 // ─── Extension API ────────────────────────────────────────────────────────────
 
 /**
- * Registers a custom modifier that can be used in `on-action` attribute syntax.
+ * Registers a custom modifier that can be used in `on-<eventType>` attribute syntax.
  *
- * A modifier is a dot-chained token placed after the event type
- * (e.g. `click.mymod->action-id`). Its handler runs before the payload is
+ * A modifier is a comma-separated token placed after the `;` separator
+ * (e.g. `on-click="action-id; mymod"`). 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`) are always
- * available. This function lets you add domain-specific ones.
+ * The handler also receives the **mutable** `action` object being built, so it
+ * can attach data to `action.meta` before the action reaches subscribers.
+ *
+ * Built-in modifiers (`prevent`, `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 - A `ModifierHandler` receiving `(event, element)`.
+ * @param name    - The modifier token (lowercase, no special characters).
+ * @param handler - A `ModifierHandler` receiving `(event, element, action)`.
  *
  * @example — a `confirm` modifier that shows a browser dialog
  * ```ts
@@ -139,7 +148,16 @@ export function dispatchAction<K extends keyof ActionRecord>(
  * registerModifier('confirm', () => window.confirm('Are you sure?'));
  * ```
  * ```html
- * <button on-action="click.confirm->delete-item:42">Delete</button>
+ * <button on-click="delete_item:42; confirm">Delete</button>
+ * ```
+ *
+ * @example — a `trace` modifier that stamps a trace ID into meta
+ * ```ts
+ * registerModifier('trace', (_event, _element, action) => {
+ *   action.meta ??= {};
+ *   action.meta['traceId'] = crypto.randomUUID();
+ *   return true;
+ * });
  * ```
  */
 export function registerModifier(name: string, handler: ModifierHandler): void {
@@ -151,15 +169,15 @@ export function registerModifier(name: string, handler: ModifierHandler): void {
 }
 
 /**
- * Registers a custom payload resolver that can be used in `on-action` attribute syntax.
+ * Registers a custom payload resolver that can be used in `on-<eventType>` attribute syntax.
  *
- * 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 an `ActionContext` as `this` and the DOM event as the argument.
- * The return value becomes the `actionPayload` passed to `onAction` subscribers.
+ * A payload resolver is a colon-prefixed token in the attribute value
+ * (e.g. `on-click="action-id:$mytoken"`). Its function is called at dispatch time
+ * with the DOM event and the element. The return value becomes the `payload`
+ * field of the `Action` object passed to `onAction` subscribers.
  *
- * Built-in resolvers (`$value`, `$formdata`) are always available. This function
- * lets you add domain-specific ones.
+ * Built-in resolvers (`$value`, `$formdata`, `$checked`) are always available.
+ * This function lets you add domain-specific ones.
  *
  * Registering the same name twice logs an accident and overwrites the previous
  * resolver — avoid duplicate registrations in production code.
@@ -167,16 +185,16 @@ export function registerModifier(name: string, handler: ModifierHandler): void {
  * @param name     - The resolver token (should start with `$` by convention).
  * @param resolver - A `PayloadResolver` receiving `(event, element)`.
  *
- * @example — a `$checked` resolver for checkbox state
+ * @example — a `$data-id` resolver that reads a data attribute
  * ```ts
  * import {registerPayloadResolver} from '@alwatr/action';
  *
- * registerPayloadResolver('$checked', (_event, element) => {
- *   return (element as HTMLInputElement).checked;
+ * registerPayloadResolver('$data-id', (_event, element) => {
+ *   return (element as HTMLElement).dataset.id ?? null;
  * });
  * ```
  * ```html
- * <input type="checkbox" on-action="change->toggle-feature:$checked" />
+ * <button on-click="select_item:$data-id" data-id="42">Select</button>
  * ```
  */
 export function registerPayloadResolver(name: string, resolver: PayloadResolver): void {

package/src/registry.ts

@@ -1,38 +1,51 @@
+import type {Action} from './action.js';
+
 // ─── Type Definitions ────────────────────────────────────────────────────────
 
 /**
- * A modifier handler used in `on-action` attribute syntax.
+ * A modifier handler used in `on-<eventType>` attribute syntax.
  *
- * 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.
+ * Receives the triggering DOM `event`, the `element` that owns the
+ * `on-<eventType>` attribute, and the **mutable** `action` object being built.
+ * The handler may mutate `action.meta` to attach cross-cutting data (e.g. a
+ * trace ID, a timestamp, or an A/B flag) before the action reaches subscribers.
+ *
+ * Return `true` (or any truthy value) to allow the action to proceed, or
+ * `false` to cancel the dispatch entirely.
  *
  * Using explicit parameters instead of `this` binding makes handlers
  * compatible with arrow functions and easier to test in isolation.
  *
- * @example
+ * @example — a modifier that stamps a timestamp into meta
+ * ```ts
+ * const timestampHandler: ModifierHandler = (_event, _element, action) => {
+ *   action.meta ??= {};
+ *   action.meta['timestamp'] = Date.now();
+ *   return true;
+ * };
+ * ```
+ *
+ * @example — a modifier that cancels dispatch when the element is disabled
  * ```ts
- * // A modifier that only allows the action when the element is not disabled
  * const notDisabledHandler: ModifierHandler = (_event, element) => {
  *   return !(element as HTMLButtonElement).disabled;
  * };
  * ```
  */
-export type ModifierHandler = (event: Event, element: HTMLElement) => boolean;
+export type ModifierHandler = (event: Event, element: HTMLElement, action: Action) => boolean;
 
 /**
- * A payload resolver used in `on-action` attribute syntax.
+ * A payload resolver used in `on-<eventType>` 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.
+ * `on-<eventType>` attribute. The return value becomes the `payload` field of
+ * the `Action` object passed to `onAction` subscribers.
  *
  * Using explicit parameters instead of `this` binding makes resolvers
  * compatible with arrow functions and easier to test in isolation.
  *
- * @example
+ * @example — a resolver that returns the element's dataset id
  * ```ts
- * // A resolver that returns the element's dataset id
  * const dataIdResolver: PayloadResolver = (_event, element) => {
  *   return (element as HTMLElement).dataset.id ?? null;
  * };
@@ -45,8 +58,8 @@ export type PayloadResolver = (event: Event, element: HTMLElement) => unknown;
 /**
  * Registry of all named modifier handlers.
  *
- * Keys are modifier names used in the `on-action` attribute syntax
- * (e.g. `click.prevent->action-id`). Values are `ModifierHandler` functions.
+ * Keys are modifier names used in the `on-<eventType>` attribute syntax
+ * (e.g. `on-click="action-id; prevent"`). Values are `ModifierHandler` functions.
  * Populated at module load with built-in modifiers; extended at runtime via
  * `registerModifier`.
  *
@@ -57,8 +70,8 @@ export const modifierRegistry = new Map<string, ModifierHandler>();
 /**
  * Registry of all named payload resolvers.
  *
- * Keys are resolver tokens used in the `on-action` attribute syntax
- * (e.g. `click->action-id:$value`). Values are `PayloadResolver` functions.
+ * Keys are resolver tokens used in the `on-<eventType>` attribute syntax
+ * (e.g. `on-input="search_query:$value"`). Values are `PayloadResolver` functions.
  * Populated at module load with built-in resolvers; extended at runtime via
  * `registerPayloadResolver`.
  *
@@ -74,7 +87,7 @@ export const payloadRegistry = new Map<string, PayloadResolver>();
  * Use it to suppress the browser's default behaviour (e.g. form submission,
  * link navigation, context menu).
  *
- * @example `<form on-action="submit.prevent->submit-form">`
+ * @example `<form on-submit="submit-form; prevent">`
  */
 modifierRegistry.set('prevent', (event) => {
   event.preventDefault();
@@ -89,9 +102,9 @@ modifierRegistry.set('prevent', (event) => {
  * allowing native constraint-validation UI to surface errors. If no form is
  * found the dispatch is also cancelled.
  *
- * Pair with `.prevent` on `submit` events to avoid page reloads:
+ * Pair with `prevent` on `submit` events to avoid page reloads:
  *
- * @example `<form on-action="submit.prevent.validate->submit-form:$formdata" novalidate>`
+ * @example `<form on-submit="submit_form:$formdata; prevent,validate" novalidate>`
  */
 modifierRegistry.set('validate', (_event, element) => {
   const form = element instanceof HTMLFormElement ? element : element.closest('form');
@@ -107,7 +120,7 @@ modifierRegistry.set('validate', (_event, element) => {
  * Works with any element that exposes a `value` property: `<input>`,
  * `<textarea>`, `<select>`. Returns `null` for elements without `.value`.
  *
- * @example `<input on-action="input->search-query:$value" />`
+ * @example `<input on-input="search_query:$value" />`
  */
 payloadRegistry.set('$value', (_event, element) => {
   return 'value' in element ? (element as {value: unknown}).value : null;
@@ -120,14 +133,32 @@ payloadRegistry.set('$value', (_event, element) => {
  * Looks for a `<form>` ancestor (or the element itself). Returns `null` when no
  * form is found.
  *
- * @example `<form on-action="submit.prevent.validate->submit-form:$formdata">`
+ * @example `<form on-submit="submit_form:$formdata; prevent,validate">`
  * ```ts
- * onAction('submit-form', (data) => {
- *   console.log(data); // {username: 'ali', password: '…'}
+ * onAction('submit_form', (action) => {
+ *   console.log(action.payload); // {username: 'ali', password: '…'}
  * });
  * ```
  */
 payloadRegistry.set('$formdata', (_event, element) => {
   const form = element instanceof HTMLFormElement ? element : element.closest('form');
-  return form ? Object.fromEntries(new FormData(form).entries()) : null;
+  return form ? Object.fromEntries(new FormData(form)) : null;
+});
+
+/**
+ * `$checked` — resolves to the `.checked` boolean property of a checkbox or radio input.
+ *
+ * Works with `<input type="checkbox">` and `<input type="radio">`.
+ * Returns `null` for elements that do not have a `checked` property.
+ *
+ * @example `<input type="checkbox" on-change="toggle_feature:$checked" />`
+ * ```ts
+ * onAction('toggle_feature', (action) => {
+ *   console.log(action.payload); // true or false
+ *   featureSignal.set(action.payload);
+ * });
+ * ```
+ */
+payloadRegistry.set('$checked', (_event, element) => {
+  return 'checked' in element ? (element as HTMLInputElement).checked : null;
 });