@alwatr/action 9.14.0 → 9.17.0

package/src/delegate.ts

@@ -10,14 +10,18 @@
  * time — O(N) initialization cost, O(N) memory for listener references, and
  * zero support for elements added after bootstrap.
  *
- * This module implements the **Qwik-inspired global delegation** pattern:
+ * This module implements the global delegation pattern:
  * - A single listener per event type is attached to `document.body` with
  *   `capture: true` (so it fires even for non-bubbling events).
  * - When an event fires, the handler walks up the DOM from `event.target`
- *   using `closest()` to find the nearest element with an `on-action`
- *   attribute whose event type matches.
- * - Modifiers and payload resolvers run in the same pipeline as before.
- * - `dispatchAction` is called with the resolved payload.
+ *   using `closest()` to find the nearest element with an `on-<eventType>`
+ *   attribute (e.g. `on-click`, `on-submit`).
+ * - 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
  *
@@ -35,74 +39,86 @@
  * - `stop` stops further bubbling but the delegation handler has already
  *   captured the event at `body` level — it does not prevent other delegation
  *   handlers from running on the same element.
- * - `once` is emulated by delete attribute elements after first fire.
+ * - `once` is emulated by removing the attribute after first fire.
  */
 
 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 ────────────────────────────────────────────────────────────
 
 /**
- * Parses the `on-action` attribute value into its three segments.
+ * Parses the `on-<eventType>` attribute value into its segments.
  *
- * Full syntax: `eventType[.modifier…]->actionId[:payload]`
+ * Syntax: `actionId[:payload][; modifier1,modifier2,…]`
  *
- * | Capture group | Matches                                     | Example              |
- * | ------------- | ------------------------------------------- | -------------------- |
- * | 1             | Event type + optional dot-chained modifiers | `click.prevent.once` |
- * | 2             | Action identifier                           | `open-drawer`        |
- * | 3             | Optional payload token or literal           | `main` / `$value`    |
+ * The event type is encoded in the **attribute name** itself (`on-click`,
+ * `on-submit`, etc.) rather than inside the value. This makes the HTML more
+ * readable and aligns with native event attribute conventions.
+ *
+ * | Capture group | Matches                                | Example                |
+ * | ------------- | -------------------------------------- | ---------------------- |
+ * | 1             | Action identifier                      | `open_drawer`          |
+ * | 2             | Optional payload token or literal      | `main_menu` / `$value` |
+ * | 3             | Optional comma-separated modifier list | `prevent,validate`     |
  *
  * @example
  * ```
- * 'click.prevent.once->open-drawer:main' → ['click.prevent.once', 'open-drawer', 'main']
- * 'input->search-query:$value'           → ['input',              'search-query', '$value']
- * 'submit.prevent->submit-form'          → ['submit.prevent',     'submit-form',  undefined]
+ * 'close_drawer'
+ *   → actionId='close_drawer', payload=undefined, modifiers={}
+ *
+ * 'open_drawer:main_menu'
+ *   → actionId='open_drawer', payload='main_menu', modifiers={}
+ *
+ * 'my_submit_handler:$formdata; prevent,validate'
+ *   → actionId='my_submit_handler', payload='$formdata', modifiers={'prevent','validate'}
  * ```
  */
-const syntaxRegex = /^([a-z0-9.-]+)->([a-z0-9-]+)(?::(.+))?$/;
+const syntaxRegex = /^([a-z0-9_:-]+)(?::([^;]+))?(?:;\s*([a-z0-9_,-]+))?$/;
 
 // ─── Parsed Action Descriptor ─────────────────────────────────────────────────
 
 /**
- * Parsed and cached representation of a single `on-action` attribute value.
+ * Parsed and cached representation of a single `on-<eventType>` attribute value.
  *
- * Caching avoids re-parsing the same attribute string on every event fire.
- * The cache is keyed by the raw attribute string so identical values share
- * the same descriptor object.
+ * Does not store `eventType` — the caller always has it from `event.type`,
+ * and the attribute name already encodes it (e.g. `on-click`), so storing it
+ * here would be redundant. This also keeps the cache key simple: just the raw
+ * attribute value string, with no composite key needed.
  */
 interface ActionDescriptor {
-  /** The DOM event type to listen for (e.g. `'click'`, `'input'`). */
-  readonly eventType: string;
   /** Set of active modifier names (e.g. `{'prevent', 'once'}`). */
   readonly modifiers: ReadonlySet<string>;
   /** The action identifier dispatched to `onAction` subscribers. */
   readonly actionId: string;
-  /** Raw payload token from the attribute (literal string or `$`-resolver key). */
+  /** Raw payload token from the attribute (literal string or $-resolver key). */
   readonly payload: string | undefined;
 }
 
 /**
- * LRU-style cache for parsed `on-action` attribute values.
+ * Cache for parsed `on-<eventType>` attribute values.
  *
  * Attribute strings are typically repeated across many elements (e.g. every
- * "add to cart" button shares the same `on-action` value). Caching the parsed
+ * "add to cart" button shares the same `on-click` value). Caching the parsed
  * descriptor avoids redundant regex work on every event.
  *
- * Using a plain `Map` here is intentional — attribute strings are short-lived
- * keys and the map size is bounded by the number of distinct `on-action` values
- * in the page, which is typically small.
+ * The cache key is the raw attribute value string. No composite key with
+ * event type is needed because the attribute name already encodes the event
+ * type — `on-click="open_drawer"` and `on-submit="open_drawer"` are two
+ * separate attributes with the same value string, but they are read from
+ * different attribute names and never collide in this cache.
  *
  * @internal
  */
 const descriptorCache__ = new Map<string, ActionDescriptor | null>();
 
 /**
- * Parses an `on-action` attribute value into an `ActionDescriptor`.
+ * Parses an `on-<eventType>` attribute value into an `ActionDescriptor`.
  *
  * Returns `null` when the syntax is invalid. Results are cached by the raw
- * attribute string so repeated calls for the same value are O(1).
+ * attribute value string so repeated calls for the same value are O(1).
  *
  * @internal
  */
@@ -120,23 +136,12 @@ function parseDescriptor__(attributeValue: string): ActionDescriptor | null {
     return null;
   }
 
-  const [eventType, ...modifierList] = match[1].split('.');
-  if (!eventType) {
-    logger_.accident('parseDescriptor__', 'missing_event_type', {attributeValue});
-    descriptorCache__.set(attributeValue, null);
-    return null;
-  }
-
-  const modifiers = new Set(modifierList);
-  const actionId = match[2];
-  const payload: string | undefined = match[3];
-
-  const descriptor: ActionDescriptor = {
-    eventType,
-    modifiers,
-    actionId,
-    payload,
-  };
+  const actionId = match[1];
+  const payload: string | undefined = match[2];
+  // match[3] is the raw modifier list string, e.g. "prevent,validate"
+  const modifierString = match[3];
+  const modifiers: Set<string> = modifierString ? new Set(modifierString.split(',').filter(Boolean)) : new Set();
+  const descriptor: ActionDescriptor = {modifiers, actionId, payload};
 
   descriptorCache__.set(attributeValue, descriptor);
   return descriptor;
@@ -144,17 +149,19 @@ function parseDescriptor__(attributeValue: string): ActionDescriptor | null {
 
 // ─── Core Delegation Handler ──────────────────────────────────────────────────
 
-const onActionAttrib__ = 'on-action';
 /**
  * Central event handler attached to `document.body` for every delegated event type.
  *
  * Execution flow for each incoming event:
  * 1. Walk up from `event.target` to find the nearest element with an
- *    `on-action` attribute whose event type matches the current event.
+ *    `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
  */
@@ -162,62 +169,81 @@ function handleDelegatedEvent__(event: Event): void {
   const eventType = event.type;
   logger_.logMethodArgs?.('handleDelegatedEvent__', {eventType});
 
-  // Walk up the DOM to find the closest element with a matching on-action attribute.
-  // We use `closest` on the composedPath target to support Shadow DOM correctly.
   const target = event.target as Element | null;
   if (!target) return;
 
-  // Find the nearest ancestor (or self) that has an on-action attribute
-  const actionElement = target.closest?.(`[${onActionAttrib__}^=${eventType}]`);
+  // Attribute name encodes the event type: on-click, on-submit, etc.
+  const actionAttrib = `on-${eventType}`;
+
+  // Walk up the DOM to find the closest element with the matching on-<eventType> attribute.
+  const actionElement = target.closest?.(`[${actionAttrib}]`);
   if (!actionElement) return;
 
-  const attributeValue = actionElement.getAttribute?.(onActionAttrib__)?.trim();
+  const attributeValue = actionElement.getAttribute?.(actionAttrib)?.trim();
   if (!attributeValue) {
-    logger_.accident('handleDelegatedEvent__', 'empty_attribute', {eventType, attributeValue, actionElement});
+    logger_.accident('handleDelegatedEvent__', 'empty_attribute', {eventType, actionElement});
     return;
   }
 
   if (!(actionElement instanceof HTMLElement)) {
-    logger_.accident('handleDelegatedEvent__', 'target_not_html_element', {eventType, attributeValue, actionElement});
+    logger_.accident('handleDelegatedEvent__', 'target_not_html_element', {eventType, actionElement});
     return;
   }
 
   const descriptor = parseDescriptor__(attributeValue);
-  if (!descriptor) {
-    logger_.accident('handleDelegatedEvent__', 'invalid_attribute', {eventType, attributeValue, actionElement});
-    return;
-  }
+  if (!descriptor) return;
 
-  if (descriptor.eventType !== eventType) return;
+  logger_.logMethodArgs?.('handleDelegatedEvent__.action', {eventType, descriptor});
 
-  logger_.logMethodArgs?.('handleDelegatedEvent__.action', descriptor);
-
-  // Step 1: handle once modifier
+  // 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(onActionAttrib__); // remove on-action to prevent repeat the action
-    descriptorCache__.delete(attributeValue); // free memory for 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 separately
+    if (modifier === 'once') continue; // handled above
     const handler = modifierRegistry.get(modifier);
     if (!handler) {
-      logger_.accident('handleDelegatedEvent__', 'unknown_modifier', {modifier, attributeValue});
-      return; // unknown modifier — abort to avoid silent misbehaviour
+      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 ────────────────────────────────────────────────────────────────────
@@ -246,11 +272,12 @@ const delegatedEventTypes__ = new Set<string>();
 export const DEFAULT_DELEGATED_EVENTS: readonly string[] = ['click', 'submit', 'input', 'change'];
 
 /**
- * Registers global event delegation for `on-action` attributes.
+ * Registers global event delegation for `on-<eventType>` attributes.
  *
  * Attaches a single `capture`-phase listener on `document.body` for each
- * event type in `eventTypes`. All `on-action` 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).
@@ -267,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
@@ -276,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,17 +1,54 @@
 /**
  * @alwatr/action — Declarative DOM action-dispatch for Unidirectional Data Flow.
  *
- * ## Activating `on-action` attributes
+ * 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
- * listener on `document.body` handles every `on-action` element — including
- * elements added dynamically after bootstrap — with O(1) initialization cost.
+ * listener on `document.body` handles every `on-click`, `on-submit`, etc. element —
+ * including elements added dynamically after bootstrap — with O(1) initialization cost.
  *
  * ```ts
  * import {setupActionDelegation, onAction} from '@alwatr/action';
  *
  * setupActionDelegation();
- * onAction('open-drawer', (panel) => openDrawer(panel));
+ * onAction('open_drawer', (action) => openDrawer(action.payload));
+ * ```
+ *
+ * ## Attribute syntax
+ *
+ * ```
+ * on-<eventType>="actionId[:payload][; modifier1,modifier2,…]"
+ * ```
+ *
+ * ```html
+ * <button on-click="open_drawer:main">Open</button>
+ * <input on-input="search_query:$value" />
+ * <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
@@ -19,7 +56,7 @@
  * ```ts
  * import {dispatchAction} from '@alwatr/action';
  *
- * dispatchAction('navigate', '/dashboard');
+ * dispatchAction({type: 'navigate', payload: '/dashboard'});
  * ```
  *
  * ## Registering typed actions
@@ -30,8 +67,8 @@
  * // src/action-record.ts
  * declare module '@alwatr/action' {
  *   interface ActionRecord {
- *     'open-drawer': string;
- *     'add-to-cart': {productId: number; qty: number};
+ *     'open_drawer': string;
+ *     'add_to_cart': {productId: number; qty: number};
  *     'logout': void;
  *   }
  * }
@@ -39,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
@@ -50,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';