@alwatr/action 9.14.0 → 9.17.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Declarative DOM action-dispatch — the Action layer for Unidirectional Data Flow.**
 
-`@alwatr/action` bridges HTML `on-action` attributes to typed signal handlers using **global event delegation**. One listener on `document.body` covers every element on the page — including elements added dynamically after bootstrap — with O(1) initialization cost regardless of how many elements exist.
+`@alwatr/action` bridges HTML `on-<eventType>` attributes to typed signal handlers using **global event delegation**. One listener on `document.body` covers every element on the page — including elements added dynamically after bootstrap — with O(1) initialization cost regardless of how many elements exist.
 
 ---
 
@@ -23,9 +23,11 @@
 
 The action bus is powered by a [`ChannelSignal`](../signal/README.md) from `@alwatr/signal`. Dispatching action `'A'` performs a single `Map.get('A')` lookup and invokes only the handlers registered for that specific action — **O(1) per dispatch**, regardless of how many other actions are subscribed.
 
+Every message on the bus is a full **`Action<K>`** object (Alwatr Flux Standard Action — AFSA) rather than a bare payload. This means every handler receives `type`, `payload`, `context`, and `meta` in one unified structure.
+
 ### Global Event Delegation
 
-A single capture-phase listener on `document.body` handles all `on-action` elements. When an event fires, the handler walks up from `event.target` using `closest('[on-action]')`, parses the attribute, runs modifiers, resolves the payload, and dispatches the action.
+A single capture-phase listener on `document.body` handles all `on-<eventType>` elements. When an event fires, the handler walks up from `event.target` using `closest('[on-click]')` (or the matching attribute), resolves the nearest `[action-context]` ancestor, parses the attribute value, runs modifiers, resolves the payload, and dispatches the full `Action` object.
 
 ```
 User clicks a button
@@ -33,13 +35,18 @@ User clicks a button
         ▼
 document.body capture listener  (1 listener per event type)
         │
-        └─ closest('[on-action^=click]') → finds element
-           parse attribute → 'click->add-to-cart:42'
+        └─ closest('[on-click]') → finds element
+           closest('[action-context]') → resolves context (e.g. 'product-list')
+           parse attribute → 'add_to_cart:42'
            run modifiers   → none
            resolve payload → '42'
-           internalChannel_.dispatch('add-to-cart', '42')
+           internalChannel_.dispatch('add_to_cart', {
+             type: 'add_to_cart',
+             payload: '42',
+             context: 'product-list',
+           })
                 │
-                └─ Map.get('add-to-cart') → O(1) → invoke only matching handlers
+                └─ Map.get('add_to_cart') → O(1) → invoke only matching handlers
 ```
 
 ### Complexity
@@ -53,7 +60,7 @@ document.body capture listener  (1 listener per event type)
 
 ### `once` modifier
 
-In delegation mode, `once` is implemented by removing the `on-action` attribute from the element after the first fire. This is simpler than a `WeakSet` cache and naturally handles element reuse — if the element is re-rendered with the attribute, it fires again.
+In delegation mode, `once` is implemented by removing the `on-<eventType>` attribute from the element after the first fire. This is simpler than a `WeakSet` cache and naturally handles element reuse — if the element is re-rendered with the attribute, it fires again.
 
 ---
 
@@ -77,10 +84,10 @@ Extend `ActionRecord` via declaration merging. This gives you full type safety a
 // src/action-record.ts
 declare module '@alwatr/action' {
   interface ActionRecord {
-    'open-drawer': string;
-    'search-query': string;
-    'add-to-cart': {productId: number; qty: number};
-    'logout': void;
+    open_drawer: string;
+    search_query: string;
+    add_to_cart: {productId: number; qty: number};
+    logout: void;
   }
 }
 ```
@@ -93,29 +100,33 @@ import './action-record.js'; // ensure the declaration is loaded
 
 setupActionDelegation();
 
-// Payload types are inferred from ActionRecord — no generics needed.
-onAction('open-drawer', (panel) => openDrawer(panel)); // panel: string
-onAction('add-to-cart', (item) => {
-  cartService.add(item.productId, item.qty); // fully typed
+// The handler receives the full Action<K> object — payload, context, and meta in one place.
+onAction('open_drawer', (action) => openDrawer(action.payload)); // action.payload: string
+onAction('add_to_cart', (action) => {
+  cartService.add(action.payload.productId, action.payload.qty); // fully typed
+  console.log(action.context); // e.g. 'product-list' — from nearest [action-context] ancestor
 });
 ```
 
 ### 3. Add attributes to HTML
 
 ```html
-<!-- Dispatches 'open-drawer' with payload 'main' on click -->
-<button on-action="click->open-drawer:main">Open Drawer</button>
+<!-- Dispatches 'close_drawer' on click — no payload -->
+<button on-click="close_drawer">Close</button>
+
+<!-- Dispatches 'open_drawer' with payload 'main' on click -->
+<button on-click="open_drawer:main">Open Drawer</button>
 
-<!-- Dispatches 'search-query' with the input's live value -->
+<!-- Dispatches 'search_query' with the input's live value -->
 <input
   type="search"
-  on-action="input->search-query:$value"
+  on-input="search_query:$value"
   placeholder="Search…"
 />
 
 <!-- Prevents default, validates, then dispatches all field values -->
 <form
-  on-action="submit.prevent.validate->submit-form:$formdata"
+  on-submit="submit_form:$formdata; prevent,validate"
   novalidate
 >
   <input
@@ -126,18 +137,57 @@ onAction('add-to-cart', (item) => {
 </form>
 
 <!-- Fires only once — attribute is removed after first click -->
-<button on-action="click.once->welcome-dismissed">Got it</button>
+<button on-click="welcome_dismissed; once">Got it</button>
+```
+
+### 4. Context scoping with `action-context`
+
+Wrap a group of elements in an `[action-context]` container to scope their actions. The delegation handler automatically resolves the nearest ancestor and attaches its value to `action.context`. This lets the same action type serve multiple independent UI regions without creating separate action names.
+
+```html
+<!-- Two sliders on the same page, both dispatching 'slider:change' -->
+<section action-context="volume">
+  <input
+    type="range"
+    on-input="slider:change:$value"
+  />
+</section>
+
+<section action-context="brightness">
+  <input
+    type="range"
+    on-input="slider:change:$value"
+  />
+</section>
+```
+
+```ts
+onAction('slider:change', (action) => {
+  if (action.context === 'volume') audioService.setVolume(Number(action.payload));
+  if (action.context === 'brightness') displayService.setBrightness(Number(action.payload));
+});
 ```
 
-### 4. Programmatic dispatch
+Context is `undefined` when no `[action-context]` ancestor exists — programmatic dispatches also have no context by default.
+
+### 5. Programmatic dispatch
 
 ```ts
 import {dispatchAction} from '@alwatr/action';
 
+// dispatchAction takes a full Action object
 await uploadFile(file);
-dispatchAction('upload-complete', fileId);
+dispatchAction({type: 'upload_complete', payload: fileId});
 
-dispatchAction('navigate', '/dashboard');
+dispatchAction({type: 'navigate', payload: '/dashboard'});
+
+// With explicit context and meta
+dispatchAction({
+  type: 'slider:change',
+  payload: 75,
+  context: 'volume',
+  meta: {source: 'keyboard'},
+});
 ```
 
 ---
@@ -145,23 +195,23 @@ dispatchAction('navigate', '/dashboard');
 ## Attribute Syntax
 
 ```
-on-action="eventType[.modifier…]->actionId[:payload]"
+on-<eventType>="actionId[:payload][; modifier1,modifier2,…]"
 ```
 
-| Segment     | Description                                               | Example                       |
-| ----------- | --------------------------------------------------------- | ----------------------------- |
-| `eventType` | Any standard DOM event name                               | `click`, `input`, `submit`    |
-| `modifier`  | Optional dot-chained tokens processed before dispatch     | `.prevent`, `.validate`       |
-| `actionId`  | Identifier your handler subscribes to                     | `open-drawer`, `search-query` |
-| `:payload`  | Optional literal string, or a `$`-prefixed resolver token | `:main`, `:$value`            |
+| Segment       | Description                                                 | Example                       |
+| ------------- | ----------------------------------------------------------- | ----------------------------- |
+| `eventType`   | Any standard DOM event name — encoded in the attribute name | `on-click`, `on-submit`       |
+| `actionId`    | Identifier your handler subscribes to                       | `open_drawer`, `search_query` |
+| `:payload`    | Optional literal string, or a `$`-prefixed resolver token   | `:main`, `:$value`            |
+| `; modifiers` | Optional comma-separated modifier list after a semicolon    | `; prevent,validate`          |
 
 ### Built-in modifiers
 
-| Modifier    | Behavior                                                                         |
-| ----------- | -------------------------------------------------------------------------------- |
-| `.prevent`  | Calls `event.preventDefault()`                                                   |
-| `.once`     | Removes the `on-action` attribute after first fire — action dispatches only once |
-| `.validate` | Cancels dispatch if the nearest `<form>` fails `checkValidity()`                 |
+| Modifier   | Behavior                                                                              |
+| ---------- | ------------------------------------------------------------------------------------- |
+| `prevent`  | Calls `event.preventDefault()`                                                        |
+| `once`     | Removes the `on-<eventType>` attribute after first fire — action dispatches only once |
+| `validate` | Cancels dispatch if the nearest `<form>` fails `checkValidity()`                      |
 
 ### Built-in payload resolvers
 
@@ -169,11 +219,81 @@ on-action="eventType[.modifier…]->actionId[:payload]"
 | ------------ | -------------------------------------------------------------- |
 | `:$value`    | `element.value` (for `<input>`, `<select>`, `<textarea>`)      |
 | `:$formdata` | `Object.fromEntries(new FormData(form))` from nearest `<form>` |
+| `:$checked`  | `(element as HTMLInputElement).checked` for checkboxes/radios  |
+
+---
+
+## The Action Object (AFSA)
+
+Every action flowing through the bus — whether triggered from HTML attributes or dispatched programmatically — is a single **`Action<K>`** object:
+
+```ts
+interface Action<K extends keyof ActionRecord> {
+  /** Action identifier — must be a key of ActionRecord. */
+  type: K;
+
+  /**
+   * DOM context from the nearest [action-context] ancestor.
+   * undefined for programmatic dispatches or when no ancestor exists.
+   */
+  context?: string;
+
+  /** Business payload — type is inferred from ActionRecord[K]. */
+  payload: ActionRecord[K];
+
+  /**
+   * Open-ended metadata bag for cross-cutting concerns.
+   * Modifiers may write to this before the action reaches subscribers.
+   */
+  meta?: Record<string, unknown>;
+}
+```
+
+Modifiers in the delegation pipeline receive the mutable `action` object and can enrich `meta` before the action reaches subscribers:
+
+```ts
+import {registerModifier} from '@alwatr/action';
+
+// A modifier that stamps a trace ID into meta
+registerModifier('trace', (_event, _element, action) => {
+  action.meta ??= {};
+  action.meta['traceId'] = crypto.randomUUID();
+  return true;
+});
+```
+
+```html
+<button on-click="submit_order:42; trace">Place Order</button>
+```
+
+```ts
+onAction('submit_order', (action) => {
+  console.log(action.meta?.['traceId']); // e.g. 'a1b2-c3d4-…'
+});
+```
 
 ---
 
 ## API Reference
 
+### `Action<K>` (interface)
+
+The Alwatr Flux Standard Action object. Every dispatch and every handler callback uses this structure.
+
+```ts
+import type {Action} from '@alwatr/action';
+
+// Reading fields in a handler
+onAction('add_to_cart', (action: Action<'add_to_cart'>) => {
+  console.log(action.type); // 'add_to_cart'
+  console.log(action.payload); // {productId: number; qty: number}
+  console.log(action.context); // string | undefined
+  console.log(action.meta); // Record<string, unknown> | undefined
+});
+```
+
+---
+
 ### `ActionRecord` (interface)
 
 The global action type registry. Extend via declaration merging to register typed actions.
@@ -181,8 +301,8 @@ The global action type registry. Extend via declaration merging to register type
 ```ts
 declare module '@alwatr/action' {
   interface ActionRecord {
-    'open-drawer': string;
-    'logout': void;
+    open_drawer: string;
+    logout: void;
   }
 }
 ```
@@ -217,34 +337,46 @@ function teardownActionDelegation(): void;
 
 ---
 
-### `onAction(actionId, handler)`
+### `onAction(type, handler)`
 
-Subscribes to a named action. O(1) routing via `ChannelSignal`.
+Subscribes to a named action. O(1) routing via `ChannelSignal`. The handler receives the full `Action<K>` object.
 
 ```ts
-function onAction<K extends keyof ActionRecord>(
-  actionId: K,
-  handler: (payload: ActionRecord[K]) => void,
-): SubscribeResult;
+function onAction<K extends keyof ActionRecord>(type: K, handler: (action: Action<K>) => void): SubscribeResult;
 ```
 
 ```ts
-const sub = onAction('open-drawer', (panel) => openDrawer(panel));
+const sub = onAction('open_drawer', (action) => {
+  openDrawer(action.payload); // payload: string
+  console.log(action.context); // e.g. 'sidebar' or undefined
+});
 sub.unsubscribe(); // prevent memory leaks
 ```
 
 ---
 
-### `dispatchAction(actionId, payload?)`
+### `dispatchAction(action)`
 
 Dispatches a named action. Payload type is enforced by `ActionRecord`.
 
+```ts
+function dispatchAction<K extends keyof ActionRecord>(action: Action<K>): void;
+```
+
 ```ts
 // With payload
-dispatchAction('open-drawer', 'settings');
+dispatchAction({type: 'open_drawer', payload: 'settings'});
 
-// Void payload — no second argument
-dispatchAction('logout');
+// Void payload
+dispatchAction({type: 'logout', payload: undefined});
+
+// With context and meta
+dispatchAction({
+  type: 'open_drawer',
+  payload: 'settings',
+  context: 'header',
+  meta: {triggeredBy: 'keyboard'},
+});
 ```
 
 ---
@@ -253,20 +385,28 @@ dispatchAction('logout');
 
 Registers a custom modifier. Return `false` to cancel the dispatch.
 
-Handler signature: `(event: Event, element: HTMLElement) => boolean`
+Handler signature: `(event: Event, element: HTMLElement, action: Action) => boolean`
+
+The handler receives the mutable `action` object and may write to `action.meta`.
 
 ```ts
 import {registerModifier} from '@alwatr/action';
 
-// Arrow function — no `this` binding needed
-registerModifier('not-disabled', (_event, element) => {
+registerModifier('not_disabled', (_event, element) => {
   return !(element as HTMLButtonElement).disabled;
 });
+
+// A modifier that enriches meta before dispatch
+registerModifier('timestamp', (_event, _element, action) => {
+  action.meta ??= {};
+  action.meta['ts'] = Date.now();
+  return true;
+});
 ```
 
 ```html
 <button
-  on-action="click.not-disabled->select-item:$data-id"
+  on-click="select_item:$data_id; not_disabled,timestamp"
   data-id="42"
 >
   Select
@@ -284,11 +424,7 @@ Handler signature: `(event: Event, element: HTMLElement) => unknown`
 ```ts
 import {registerPayloadResolver} from '@alwatr/action';
 
-registerPayloadResolver('$checked', (_event, element) => {
-  return (element as HTMLInputElement).checked;
-});
-
-registerPayloadResolver('$data-id', (_event, element) => {
+registerPayloadResolver('$data_id', (_event, element) => {
   return (element as HTMLElement).dataset.id ?? null;
 });
 ```
@@ -296,10 +432,10 @@ registerPayloadResolver('$data-id', (_event, element) => {
 ```html
 <input
   type="checkbox"
-  on-action="change->toggle-feature:$checked"
+  on-change="toggle_feature:$checked"
 />
 <li
-  on-action="click->select-item:$data-id"
+  on-click="select_item:$data_id"
   data-id="42"
 >
   Item
@@ -311,33 +447,41 @@ registerPayloadResolver('$data-id', (_event, element) => {
 ## Unidirectional Data Flow
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│                        UI Layer                         │
-│  <button on-action="click->add-to-cart:42">Add</button> │
-└────────────────────────┬────────────────────────────────┘
-                         │ DOM event bubbles to body
-                         ▼
-┌─────────────────────────────────────────────────────────┐
-│              Action Layer (@alwatr/action)               │
-│  document.body capture listener (1 per event type)      │
-│  → closest('[on-action]') → parse → modifiers           │
-│  → internalChannel_.dispatch('add-to-cart', '42') [O(1)]│
-└────────────────────────┬────────────────────────────────┘
-                         │ O(1) routing via ChannelSignal
-                         ▼
-┌─────────────────────────────────────────────────────────┐
-│                   Business Logic Layer                  │
-│  onAction('add-to-cart', (id) => cartService.add(id))   │
-└────────────────────────┬────────────────────────────────┘
-                         │ state update
-                         ▼
-┌─────────────────────────────────────────────────────────┐
-│                    State Layer (@alwatr/signal)          │
-│  cartSignal.set(newCartState)                           │
-└────────────────────────┬────────────────────────────────┘
-                         │ state flows down to UI
-                         ▼
-                      UI re-renders
+┌────────────────────────────────────────────────────────────┐
+│                           UI Layer                         │
+│  <section action-context="cart">                           │
+│    <button on-click="add_to_cart:42">Add</button>          │
+│  </section>                                                │
+└─────────────────────────┬──────────────────────────────────┘
+                          │ DOM event bubbles to body
+                          ▼
+┌────────────────────────────────────────────────────────────┐
+│                 Action Layer (@alwatr/action)              │
+│  document.body capture listener (1 per event type)         │
+│  → closest('[on-click]') → parse attribute                 │
+│  → closest('[action-context]') → context = 'cart'          │
+│  → run modifiers (may enrich action.meta)                  │
+│  → resolve payload → '42'                                  │
+│  → dispatch Action {type, payload, context, meta}  [O(1)]  │
+└─────────────────────────┬──────────────────────────────────┘
+                          │ O(1) routing via ChannelSignal
+                          ▼
+┌────────────────────────────────────────────────────────────┐
+│                     Business Logic Layer                   │
+│  onAction('add_to_cart', (action) => {                     │
+│    cartService.add(action.payload);                        │
+│    // action.context === 'cart'                            │
+│  })                                                        │
+└─────────────────────────┬──────────────────────────────────┘
+                          │ state update
+                          ▼
+┌────────────────────────────────────────────────────────────┐
+│                   State Layer (@alwatr/signal)             │
+│  cartSignal.set(newCartState)                              │
+└─────────────────────────┬──────────────────────────────────┘
+                          │ state flows down to UI
+                          ▼
+                     UI re-renders
 ```
 
 ---
@@ -353,30 +497,94 @@ concern, not a user-interaction action.
 
 ## Migration from Previous Versions
 
-### `ActionContext` removed
+### `dispatchAction` API changed
 
-The `this` context in modifier and resolver handlers changed to explicit parameters:
+`dispatchAction` now takes a single `Action` object instead of two positional arguments.
 
 **Before:**
 
 ```ts
-registerModifier('not-disabled', function () {
-  return !(this.element as HTMLButtonElement).disabled;
+dispatchAction('open_drawer', 'settings');
+dispatchAction('logout');
+```
+
+**After:**
+
+```ts
+dispatchAction({type: 'open_drawer', payload: 'settings'});
+dispatchAction({type: 'logout', payload: undefined});
+```
+
+### `onAction` handler signature changed
+
+Handlers now receive the full `Action<K>` object instead of just the payload.
+
+**Before:**
+
+```ts
+onAction('add_to_cart', (item) => {
+  cartService.add(item.productId, item.qty);
 });
 ```
 
 **After:**
 
 ```ts
-registerModifier('not-disabled', (_event, element) => {
+onAction('add_to_cart', (action) => {
+  cartService.add(action.payload.productId, action.payload.qty);
+  // action.context is now also available
+});
+```
+
+### `registerModifier` handler signature changed
+
+Modifier handlers now receive a third `action` argument for `meta` enrichment.
+
+**Before:**
+
+```ts
+registerModifier('not_disabled', (_event, element) => {
   return !(element as HTMLButtonElement).disabled;
 });
 ```
 
-### `once` behavior changed
+**After (backward-compatible — third arg is optional to use):**
 
-Previously tracked via `WeakSet`. Now removes the `on-action` attribute after first fire.
-Behavior is equivalent for typical use cases.
+```ts
+registerModifier('not_disabled', (_event, element, _action) => {
+  return !(element as HTMLButtonElement).disabled;
+});
+```
+
+### Attribute syntax changed
+
+The event type is now encoded in the **attribute name** instead of the value, and modifiers are listed after a semicolon instead of dot-chained before the arrow.
+
+**Before:**
+
+```html
+<button on-action="click->open_drawer:main">Open</button>
+<form
+  on-action="submit.prevent.validate->submit_form:$formdata"
+  novalidate
+>
+  …
+</form>
+<button on-action="click.once->welcome_dismissed">Got it</button>
+```
+
+**After:**
+
+```html
+<button on-click="open_drawer:main">Open</button>
+<form
+  on-submit="submit_form:$formdata; prevent,validate"
+  novalidate
+>
+  …
+</form>
+<button on-click="welcome_dismissed; once">Got it</button>
+```
 
 ### `page-ready` moved to `@alwatr/page-ready`
 
@@ -384,6 +592,38 @@ Behavior is equivalent for typical use cases.
 
 ---
 
+## 🌊 Part of Alwatr Flux
+
+`@alwatr/action` is the **Action Layer** of the [Alwatr Flux](https://github.com/Alwatr/alwatr/tree/next/pkg/flux) architecture — a complete Unidirectional Data Flow system for building scalable Progressive Web Applications.
+
+```
+View (HTML on-<event> attributes + action-context)
+  ↓
+Action Layer (@alwatr/action) — global delegation, O(1) routing, AFSA objects
+  ↓
+Controller (business logic via onAction — receives full Action object)
+  ↓
+State Layer (@alwatr/signal) — fine-grained reactivity
+  ↓
+View (re-render only affected nodes)
+```
+
+`@alwatr/action` is the bridge between the **View** and **Controller** layers. It captures user intent from HTML attributes and routes it to the right handler — without any coupling between the UI and business logic.
+
+**The full Flux bundle** (`@alwatr/flux`) includes actions, signals, directives, page-ready, and storage — everything you need to build a complete reactive application from a single import.
+
+```typescript
+// Use @alwatr/flux for the complete architecture
+import {setupActionDelegation, onAction, createStateSignal} from '@alwatr/flux';
+
+// Or use @alwatr/action standalone for just the action bus
+import {setupActionDelegation, onAction, dispatchAction} from '@alwatr/action';
+```
+
+→ [View the complete Flux documentation](https://github.com/Alwatr/alwatr/tree/next/pkg/flux)
+
+---
+
 ## Contributing
 
 Contributions are welcome! Please read our [contribution guidelines](https://github.com/Alwatr/.github/blob/next/CONTRIBUTING.md) before submitting a pull request.

package/dist/action-record.d.ts

@@ -13,8 +13,8 @@
  * // In your package: 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;
  *   }
  * }
@@ -42,8 +42,8 @@
  * // pkg/my-feature/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;
  *   }
  * }