@alwatr/action 9.16.0 → 9.17.0

package/src/action.ts

@@ -0,0 +1,97 @@
+/**
+ * @file action.ts
+ *
+ * Defines the Alwatr Flux Standard Action (AFSA) — the single, unified data
+ * structure that flows through the entire action bus for both dispatch and
+ * subscription.
+ *
+ * ## Why a single Action object?
+ *
+ * Previously, `dispatchAction(id, payload)` and `onAction(id, handler(payload))`
+ * treated the action as two separate concerns: an identifier and a raw payload.
+ * This made it impossible to carry cross-cutting metadata (context, trace IDs,
+ * timestamps) without breaking every call site.
+ *
+ * AFSA wraps everything into one object:
+ * - `type`    — the action identifier (replaces the first positional argument)
+ * - `payload` — the business data (replaces the second positional argument)
+ * - `context` — the DOM context extracted from the nearest `[action-context]`
+ *               ancestor at delegation time; `undefined` for programmatic dispatches
+ * - `meta`    — open-ended bag for future cross-cutting concerns (trace IDs,
+ *               timestamps, A/B flags, etc.) without breaking the typed API
+ *
+ * Modifiers in the delegation pipeline can also mutate `meta` before the action
+ * reaches subscribers — e.g. a `trace` modifier could stamp a request ID.
+ */
+
+import type {DictionaryOpt} from '@alwatr/type-helper';
+import type {ActionRecord} from './action-record.js';
+
+/**
+ * Alwatr Flux Standard Action (AFSA).
+ *
+ * The single, canonical object passed to every `dispatchAction` call and
+ * received by every `onAction` handler. Keeping all action data in one
+ * structure makes the bus extensible without breaking existing call sites.
+ *
+ * @template K - A key of `ActionRecord`; constrains `type` and `payload` together.
+ *
+ * @example — dispatching
+ * ```ts
+ * dispatchAction({type: 'add_to_cart', payload: {productId: 42, qty: 1}});
+ * ```
+ *
+ * @example — subscribing
+ * ```ts
+ * onAction('add_to_cart', (action) => {
+ *   console.log(action.type);    // 'add_to_cart'
+ *   console.log(action.payload); // {productId: 42, qty: 1}
+ *   console.log(action.context); // e.g. 'product-list' (from DOM) or undefined
+ * });
+ * ```
+ */
+export interface Action<K extends keyof ActionRecord = keyof ActionRecord> {
+  /**
+   * Unique action identifier — must be a key of `ActionRecord`.
+   *
+   * @example 'cart:add-item', 'open_drawer', 'logout'
+   */
+  readonly type: K;
+
+  /**
+   * The DOM context in which the action was triggered.
+   *
+   * Extracted at delegation time from the nearest ancestor element that carries
+   * an `action-context` attribute. Useful for scoping the same action type to
+   * different UI regions (e.g. two sliders on the same page both dispatching
+   * `'slider:change'` but with different context values).
+   *
+   * `undefined` when the action is dispatched programmatically (no DOM involved)
+   * or when no `[action-context]` ancestor exists.
+   *
+   * @example 'slider-123', 'product-list', 'checkout-form'
+   */
+  readonly context?: string;
+
+  /**
+   * The pure business payload carried by this action.
+   *
+   * Type is inferred from `ActionRecord[K]` — the compiler enforces the correct
+   * shape at every call site. No manual generic annotation is needed.
+   */
+  readonly payload: ActionRecord[K];
+
+  /**
+   * Open-ended metadata bag for cross-cutting concerns.
+   *
+   * Intentionally untyped so that future infrastructure layers (tracing,
+   * analytics, A/B testing) can attach data without touching the typed API.
+   * Modifiers in the delegation pipeline may also write to `meta` before the
+   * action reaches subscribers.
+   *
+   * Treat values here as `unknown` and validate before use.
+   *
+   * @example {traceId: 'abc-123', timestamp: Date.now()}
+   */
+  meta?: DictionaryOpt<unknown>;
+}

package/src/delegate.ts

@@ -16,8 +16,12 @@
  * - When an event fires, the handler walks up the DOM from `event.target`
  *   using `closest()` to find the nearest element with an `on-<eventType>`
  *   attribute (e.g. `on-click`, `on-submit`).
- * - Modifiers and payload resolvers run in the same pipeline as before.
- * - `dispatchAction` is called with the resolved payload.
+ * - The nearest `[action-context]` ancestor is also resolved and attached to
+ *   the `Action` object as `context` — enabling the same action type to be
+ *   scoped to different UI regions.
+ * - Modifiers run with access to the mutable `Action` object so they can
+ *   enrich `meta` before the action reaches subscribers.
+ * - `dispatchAction` is called with the fully assembled `Action` object.
  *
  * ## Complexity
  *
@@ -40,6 +44,8 @@
 
 import {internalChannel_, logger_} from './lib.js';
 import {modifierRegistry, payloadRegistry} from './registry.js';
+import type {Action} from './action.js';
+import type {ActionRecord} from './action-record.js';
 
 // ─── Syntax Parser ────────────────────────────────────────────────────────────
 
@@ -70,7 +76,7 @@ import {modifierRegistry, payloadRegistry} from './registry.js';
  *   → actionId='my_submit_handler', payload='$formdata', modifiers={'prevent','validate'}
  * ```
  */
-const syntaxRegex = /^([a-z0-9_-]+)(?::([^;]+))?(?:;\s*([a-z0-9_,-]+))?$/;
+const syntaxRegex = /^([a-z0-9_:-]+)(?::([^;]+))?(?:;\s*([a-z0-9_,-]+))?$/;
 
 // ─── Parsed Action Descriptor ─────────────────────────────────────────────────
 
@@ -150,9 +156,12 @@ function parseDescriptor__(attributeValue: string): ActionDescriptor | null {
  * 1. Walk up from `event.target` to find the nearest element with an
  *    `on-<eventType>` attribute (e.g. `on-click`, `on-submit`).
  * 2. Parse (or retrieve from cache) the `ActionDescriptor` for that attribute.
- * 3. Run each modifier in order; if any returns `false`, abort.
- * 4. Resolve the payload token (literal or $-resolver).
- * 5. Call `dispatchAction(actionId, payload)`.
+ * 3. Resolve `context` from the nearest `[action-context]` ancestor.
+ * 4. Build a mutable `Action` object with `type`, `payload` (raw), and `context`.
+ * 5. Run each modifier in order with access to the mutable `Action`; if any
+ *    returns `false`, abort.
+ * 6. Resolve the payload token (literal or $-resolver) and assign to `action.payload`.
+ * 7. Call `dispatchAction(action)` with the fully assembled object.
  *
  * @internal
  */
@@ -186,13 +195,28 @@ function handleDelegatedEvent__(event: Event): void {
 
   logger_.logMethodArgs?.('handleDelegatedEvent__.action', {eventType, descriptor});
 
-  // Step 1: handle once modifier — remove attribute before running other modifiers
+  // Step 1: handle `once` modifier — remove attribute before running other modifiers
   // so that even if a modifier aborts, the element will not fire again.
   if (descriptor.modifiers.has('once')) {
     actionElement.removeAttribute(actionAttrib);
   }
 
-  // Step 2: run modifiers
+  // Step 2: resolve `context` from the nearest [action-context] ancestor.
+  // Walk up from the action element itself (inclusive) to find the context scope.
+  // This allows the action element itself to carry action-context if needed.
+  const actionContext = actionElement.closest('[action-context]')?.getAttribute('action-context') ?? undefined;
+
+  // Step 3: build the mutable Action object.
+  // `payload` starts as the raw token string; it will be resolved in step 5.
+  // Modifiers in step 4 may mutate `meta` to attach cross-cutting data.
+  const action: Action = {
+    type: descriptor.actionId as keyof ActionRecord,
+    context: actionContext,
+    // Payload is temporarily set to the raw token; resolved below after modifiers run.
+    payload: descriptor.payload as ActionRecord[keyof ActionRecord],
+  };
+
+  // Step 4: run modifiers — each receives the mutable action so it can enrich meta.
   for (const modifier of descriptor.modifiers) {
     if (modifier === 'once') continue; // handled above
     const handler = modifierRegistry.get(modifier);
@@ -200,18 +224,26 @@ function handleDelegatedEvent__(event: Event): void {
       logger_.accident('handleDelegatedEvent__', 'unknown_modifier', {eventType, modifier, attributeValue, descriptor});
       return; // unknown modifier — abort to avoid silent misbehavior
     }
-    if (handler(event, actionElement) === false) return;
+    if (handler(event, actionElement, action) === false) return;
   }
 
-  // Step 3: resolve payload
-  let payload: unknown = descriptor.payload;
-  if (payload) {
-    const resolver = payloadRegistry.get(payload as string);
-    if (resolver) payload = resolver(event, actionElement);
+  // Step 5: resolve payload — replace raw token with the actual value.
+  // If the raw token starts with '$', look it up in the payload resolver registry.
+  // Otherwise treat it as a literal string payload.
+  if (descriptor.payload) {
+    const resolver = payloadRegistry.get(descriptor.payload);
+    if (resolver) {
+      // Cast needed: payload is typed as ActionRecord[K] but we're building generically.
+      (action as {payload: unknown}).payload = resolver(event, actionElement);
+    }
+    // else: keep the literal string already set on action.payload
+  } else {
+    // No payload token in the attribute — set to undefined.
+    (action as {payload: unknown}).payload = undefined;
   }
 
-  // Step 4: dispatch
-  internalChannel_.dispatch(descriptor.actionId, payload);
+  // Step 6: dispatch the fully assembled Action object.
+  internalChannel_.dispatch(action.type, action);
 }
 
 // ─── Setup ────────────────────────────────────────────────────────────────────
@@ -243,8 +275,9 @@ export const DEFAULT_DELEGATED_EVENTS: readonly string[] = ['click', 'submit', '
  * Registers global event delegation for `on-<eventType>` attributes.
  *
  * Attaches a single `capture`-phase listener on `document.body` for each
- * event type in `eventTypes`. All processing — modifier execution, payload
- * resolution, and `dispatchAction` — happens inside that one handler.
+ * event type in `eventTypes`. All processing — context resolution, modifier
+ * execution, payload resolution, and `dispatchAction` — happens inside that
+ * one handler.
  *
  * **Call this once at application bootstrap**, before any user interaction.
  * Subsequent calls with the same event types are no-ops (idempotent).
@@ -261,6 +294,24 @@ export const DEFAULT_DELEGATED_EVENTS: readonly string[] = ['click', 'submit', '
  * after this call — via `innerHTML`, `lit-html`, a framework renderer, or
  * server-sent HTML — is automatically covered. No re-bootstrap is needed.
  *
+ * ### Context scoping
+ *
+ * Wrap a group of elements in a `[action-context]` container to scope their
+ * actions. The delegation handler automatically resolves the nearest ancestor
+ * and attaches its value to `action.context`:
+ *
+ * ```html
+ * <section action-context="product-list">
+ *   <button on-click="add_to_cart:42">Add</button>
+ * </section>
+ * ```
+ *
+ * ```ts
+ * onAction('add_to_cart', (action) => {
+ *   console.log(action.context); // 'product-list'
+ * });
+ * ```
+ *
  * @param eventTypes - Event types to delegate. Defaults to `DEFAULT_DELEGATED_EVENTS`.
  *
  * @example — minimal bootstrap
@@ -270,7 +321,7 @@ export const DEFAULT_DELEGATED_EVENTS: readonly string[] = ['click', 'submit', '
  * // One call activates the entire page.
  * setupActionDelegation();
  *
- * onAction('open_drawer', (panel) => openDrawer(panel));
+ * onAction('open_drawer', (action) => openDrawer(action.payload));
  * ```
  *
  * @example — with extra event types

package/src/lib.ts

@@ -1,6 +1,8 @@
 import {createLogger} from '@alwatr/logger';
 import {createChannelSignal} from '@alwatr/signal';
 
+import type {Action} from './action.js';
+
 /**
  * Module-scoped logger for `@alwatr/action`.
  * Scoped to `'alwatr-action'` so log lines are easy to filter in the console.
@@ -10,16 +12,17 @@ import {createChannelSignal} from '@alwatr/signal';
 export const logger_ = createLogger('alwatr-action');
 
 /**
- * The action channel — a `ChannelSignal` strictly typed by `ActionRecord`.
+ * The internal action channel — a `ChannelSignal` keyed by action `type`.
  *
- * Only action names declared in `ActionRecord` (via declaration merging) are
- * accepted at compile time. Passing an unknown action name to `onAction` or
- * `dispatchAction` is a **compile error** — there is no string fallback.
+ * Each message on this channel is a full `Action` object (AFSA), not just a
+ * raw payload. Subscribers registered via `onAction('foo', handler)` receive
+ * the entire `Action<'foo'>` so they have access to `context`, `meta`, and
+ * `payload` in one place.
  *
  * Uses `ChannelSignal` for O(1) routing: dispatching action `'A'` performs a
  * single `Map.get('A')` lookup and invokes only the handlers registered for
- * that specific action — never handlers for `'B'`, `'C'`, etc.
+ * that specific type — never handlers for `'B'`, `'C'`, etc.
  *
  * @internal — not part of the public API; use `onAction` / `dispatchAction` instead.
  */
-export const internalChannel_ = createChannelSignal<Record<string, unknown>>({name: 'alwatr-action'});
+export const internalChannel_ = createChannelSignal<Record<string, Action>>({name: 'alwatr-action'});

package/src/main.ts

@@ -1,6 +1,12 @@
 /**
  * @alwatr/action — Declarative DOM action-dispatch for Unidirectional Data Flow.
  *
+ * Implements the **Alwatr Flux Standard Action (AFSA)** pattern: every action
+ * flowing through the bus is a single, typed `Action<K>` object carrying
+ * `type`, `payload`, `context`, and optional `meta`. This replaces the previous
+ * two-argument `(id, payload)` API with a unified structure that is extensible
+ * without breaking existing call sites.
+ *
  * ## Activating `on-<eventType>` attributes
  *
  * Call `setupActionDelegation()` once at bootstrap. A single capture-phase
@@ -11,7 +17,7 @@
  * import {setupActionDelegation, onAction} from '@alwatr/action';
  *
  * setupActionDelegation();
- * onAction('open_drawer', (panel) => openDrawer(panel));
+ * onAction('open_drawer', (action) => openDrawer(action.payload));
  * ```
  *
  * ## Attribute syntax
@@ -26,12 +32,31 @@
  * <form on-submit="submit_form:$formdata; prevent,validate" novalidate>…</form>
  * ```
  *
+ * ## Context scoping
+ *
+ * Wrap elements in an `[action-context]` container to scope their actions.
+ * The delegation handler resolves the nearest ancestor and attaches its value
+ * to `action.context`:
+ *
+ * ```html
+ * <section action-context="product-list">
+ *   <button on-click="add_to_cart:42">Add</button>
+ * </section>
+ * ```
+ *
+ * ```ts
+ * onAction('add_to_cart', (action) => {
+ *   console.log(action.context); // 'product-list'
+ *   console.log(action.payload); // '42'
+ * });
+ * ```
+ *
  * ## Programmatic dispatch
  *
  * ```ts
  * import {dispatchAction} from '@alwatr/action';
  *
- * dispatchAction('navigate', '/dashboard');
+ * dispatchAction({type: 'navigate', payload: '/dashboard'});
  * ```
  *
  * ## Registering typed actions
@@ -51,7 +76,8 @@
  *
  * ## Public API
  *
- * - `ActionRecord` — extend this interface to register typed actions
+ * - `Action`          — the AFSA object interface (`type`, `payload`, `context`, `meta`)
+ * - `ActionRecord`    — extend this interface to register typed actions
  * - `setupActionDelegation` / `teardownActionDelegation` — global delegation lifecycle
  * - `DEFAULT_DELEGATED_EVENTS` — default event types covered by delegation
  * - `onAction` / `dispatchAction` — subscribe to and dispatch named actions
@@ -62,5 +88,6 @@
  * For page-ready signals in SSG/SSR apps, use `@alwatr/page-ready` instead.
  */
 export type {ActionRecord} from './action-record.js';
+export type {Action} from './action.js';
 export * from './method.js';
 export * from './delegate.js';

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
+ * 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
  * });
  * ```
  *
@@ -38,80 +43,81 @@ 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
+ * 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-<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 ────────────────────────────────────────────────────────────
@@ -123,14 +129,17 @@ export function dispatchAction<K extends keyof ActionRecord>(
  * (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 special characters).
- * @param handler - A `ModifierHandler` receiving `(event, element)`.
+ * @param handler - A `ModifierHandler` receiving `(event, element, action)`.
  *
  * @example — a `confirm` modifier that shows a browser dialog
  * ```ts
@@ -141,6 +150,15 @@ export function dispatchAction<K extends keyof ActionRecord>(
  * ```html
  * <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 {
   logger_.logMethodArgs?.('registerModifier', {name});
@@ -155,11 +173,11 @@ export function registerModifier(name: string, handler: ModifierHandler): void {
  *
  * 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 an `ActionContext` as `this` and the DOM event as the argument.
- * The return value becomes the `actionPayload` passed to `onAction` subscribers.
+ * 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-change="toggle_feature:$checked" />
+ * <button on-click="select_item:$data-id" data-id="42">Select</button>
  * ```
  */
 export function registerPayloadResolver(name: string, resolver: PayloadResolver): void {