@alwatr/action 9.13.0 → 9.16.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.
 
 ---
 
@@ -19,26 +19,27 @@
 
 ## How It Works
 
+### Action Bus
+
+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.
+
 ### Global Event Delegation
 
-Instead of attaching one listener per element, a single capture-phase listener is registered on `document.body` for each event type. When an event fires anywhere on the page, the handler walks up from `event.target` using `closest('[on-action]')` to find the nearest element with an `on-action` attribute, parses the attribute, runs modifiers, resolves the payload, and calls `dispatchAction`.
+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), parses the attribute value, runs modifiers, resolves the payload, and dispatches the action.
 
 ```
 User clicks a button
         │
         ▼
-document.body capture listener (1 listener total)
+document.body capture listener  (1 listener per event type)
         │
-        └─ closest('[on-action]') → finds element
-           parse attribute → 'click->add-to-cart:42'
+        └─ closest('[on-click]') → finds element
+           parse attribute → 'add_to_cart:42'
            run modifiers   → none
            resolve payload → '42'
-           dispatchAction('add-to-cart', '42')
-                │
-                ▼
-          ChannelSignal.dispatch('add-to-cart', '42')  [O(1)]
+           internalChannel_.dispatch('add_to_cart', '42')
                 │
-                └─ Map.get('add-to-cart') → invoke only matching handlers
+                └─ Map.get('add_to_cart') → O(1) → invoke only matching handlers
 ```
 
 ### Complexity
@@ -48,10 +49,11 @@ document.body capture listener (1 listener total)
 | Boot time       | O(N elements)         | **O(1)**             |
 | Memory          | O(N listeners)        | **O(1)**             |
 | Dynamic content | Requires re-bootstrap | **Works out-of-box** |
+| `once` modifier | Native option         | Remove attribute     |
 
-### Action Bus
+### `once` modifier
 
-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.
+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.
 
 ---
 
@@ -69,55 +71,54 @@ npm i @alwatr/action
 
 ### 1. Register your action types
 
-Create a declaration file in your package to extend `ActionRecord`. This gives you full type safety and IDE autocomplete across the entire app:
+Extend `ActionRecord` via declaration merging. This gives you full type safety and IDE autocomplete — passing an undeclared action name is a **compile error**.
 
 ```ts
 // 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;
   }
 }
 ```
 
-Passing an action name not declared in `ActionRecord` is a **compile error** — there is no string fallback.
-
 ### 2. Bootstrap delegation
 
 ```ts
 import {setupActionDelegation, onAction} from '@alwatr/action';
 import './action-record.js'; // ensure the declaration is loaded
 
-// One call — the entire page is covered, including future dynamic content.
 setupActionDelegation();
 
-// Payload types are inferred automatically from ActionRecord — no generics needed.
-onAction('open-drawer', (panel) => openDrawer(panel)); // panel: string
-onAction('search-query', (query) => performSearch(query)); // query: string
-onAction('add-to-cart', (item) => {
-  cartService.add(item.productId, item.qty); // fully typed, no `!`
+// 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
 });
 ```
 
 ### 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,19 +127,20 @@ onAction('add-to-cart', (item) => {
   />
   <button type="submit">Save</button>
 </form>
+
+<!-- Fires only once — attribute is removed after first click -->
+<button on-click="welcome_dismissed; once">Got it</button>
 ```
 
-### 3. Programmatic dispatch
+### 4. Programmatic dispatch
 
 ```ts
 import {dispatchAction} from '@alwatr/action';
 
-// Trigger actions from code — after async ops, from service layers, etc.
 await uploadFile(file);
-dispatchAction('upload-complete', fileId);
+dispatchAction('upload_complete', fileId);
 
 dispatchAction('navigate', '/dashboard');
-dispatchAction<{code: number}>('show-error', {code: 404});
 ```
 
 ---
@@ -146,27 +148,23 @@ dispatchAction<{code: number}>('show-error', {code: 404});
 ## 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()`                                       |
-| `.stop`     | Calls `event.stopPropagation()`                                      |
-| `.once`     | Dispatches the action only once per element (emulated via `WeakSet`) |
-| `.validate` | Cancels dispatch if the nearest `<form>` fails `checkValidity()`     |
-
-> **Note:** `.passive` is not supported in delegation mode because all delegated
-> listeners must be non-passive to allow `.prevent` to work.
+| 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
 
@@ -181,31 +179,22 @@ on-action="eventType[.modifier…]->actionId[:payload]"
 
 ### `ActionRecord` (interface)
 
-The global action type registry. Extend it via declaration merging to register your application's actions and unlock full type safety in `onAction` and `dispatchAction`.
+The global action type registry. Extend via declaration merging to register typed actions.
 
 ```ts
-// src/action-record.ts
 declare module '@alwatr/action' {
   interface ActionRecord {
-    'open-drawer': string;
-    'add-to-cart': {productId: number; qty: number};
-    'logout': void;
+    open_drawer: string;
+    logout: void;
   }
 }
 ```
 
-Once declared:
-
-- `onAction('open-drawer', (panel) => …)` — `panel` is inferred as `string`
-- `dispatchAction('add-to-cart', {productId: 42, qty: 1})` — payload type enforced
-- `dispatchAction('unknown-action', …)` — **compile error**
-
 ---
 
 ### `setupActionDelegation(eventTypes?)`
 
-Registers global event delegation on `document.body`. Call once at bootstrap.
-Subsequent calls with the same event types are no-ops (idempotent).
+Registers global event delegation on `document.body`. Call once at bootstrap. Idempotent.
 
 ```ts
 function setupActionDelegation(eventTypes?: readonly string[]): void;
@@ -216,18 +205,14 @@ Defaults to `DEFAULT_DELEGATED_EVENTS`: `['click', 'submit', 'input', 'change']`
 ```ts
 import {setupActionDelegation, DEFAULT_DELEGATED_EVENTS} from '@alwatr/action';
 
-// Default events
-setupActionDelegation();
-
-// Add extra event types
-setupActionDelegation([...DEFAULT_DELEGATED_EVENTS, 'keydown', 'pointerup']);
+setupActionDelegation([...DEFAULT_DELEGATED_EVENTS, 'keydown']);
 ```
 
 ---
 
 ### `teardownActionDelegation()`
 
-Removes all delegation listeners. Useful in tests or micro-frontend teardown.
+Removes all delegation listeners and clears the descriptor cache. Useful in tests or micro-frontend teardown.
 
 ```ts
 function teardownActionDelegation(): void;
@@ -237,54 +222,32 @@ function teardownActionDelegation(): void;
 
 ### `onAction(actionId, handler)`
 
-Subscribes to a named action. Uses `ChannelSignal.on()` for O(1) routing.
+Subscribes to a named action. O(1) routing via `ChannelSignal`.
 
 ```ts
-function onAction<T = string>(actionId: string, handler: (payload?: T) => void): SubscribeResult;
+function onAction<K extends keyof ActionRecord>(
+  actionId: K,
+  handler: (payload: ActionRecord[K]) => void,
+): SubscribeResult;
 ```
 
 ```ts
-const sub = onAction('open-drawer', (panel) => openDrawer(panel));
-
-// Unsubscribe when no longer needed (prevents memory leaks)
-sub.unsubscribe();
+const sub = onAction('open_drawer', (panel) => openDrawer(panel));
+sub.unsubscribe(); // prevent memory leaks
 ```
 
 ---
 
 ### `dispatchAction(actionId, payload?)`
 
-Dispatches a named action to all matching `onAction` subscribers.
+Dispatches a named action. Payload type is enforced by `ActionRecord`.
 
 ```ts
-function dispatchAction<T = string>(actionId: string, actionPayload?: T): void;
-```
-
----
-
-### `dispatchPageId(element?)`
+// With payload
+dispatchAction('open_drawer', 'settings');
 
-Reads the `page-id` attribute from `element` (defaults to `document.body`) and
-dispatches a `'page-ready'` action with the page identifier as payload.
-
-```ts
-function dispatchPageId(element?: HTMLElement): void;
-```
-
-```html
-<body page-id="home">
-  …
-</body>
-```
-
-```ts
-import {dispatchPageId, onAction} from '@alwatr/action';
-
-dispatchPageId(); // → dispatchAction('page-ready', 'home')
-
-onAction('page-ready', (pageId) => {
-  console.log('navigated to:', pageId); // 'home'
-});
+// Void payload — no second argument
+dispatchAction('logout');
 ```
 
 ---
@@ -292,48 +255,57 @@ onAction('page-ready', (pageId) => {
 ### `registerModifier(name, handler)`
 
 Registers a custom modifier. Return `false` to cancel the dispatch.
-Works with both delegation and programmatic dispatch.
+
+Handler signature: `(event: Event, element: HTMLElement) => boolean`
 
 ```ts
 import {registerModifier} from '@alwatr/action';
 
-registerModifier('confirm', function () {
-  return window.confirm('Are you sure?');
+registerModifier('not_disabled', (_event, element) => {
+  return !(element as HTMLButtonElement).disabled;
 });
 ```
 
 ```html
-<button on-action="click.confirm->delete-item:42">Delete</button>
-```
-
-The handler receives an `ActionContext` as `this`:
-
-```ts
-interface ActionContext {
-  readonly element: HTMLElement; // the element with the on-action attribute
-}
+<button
+  on-click="select_item:$data_id; not_disabled"
+  data-id="42"
+>
+  Select
+</button>
 ```
 
 ---
 
 ### `registerPayloadResolver(name, resolver)`
 
-Registers a custom payload resolver. The return value becomes the action payload.
-Works with both delegation and programmatic dispatch.
+Registers a custom payload resolver.
+
+Handler signature: `(event: Event, element: HTMLElement) => unknown`
 
 ```ts
 import {registerPayloadResolver} from '@alwatr/action';
 
-registerPayloadResolver('$checked', function () {
-  return (this.element as HTMLInputElement).checked;
+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"
+  on-change="toggle_feature:$checked"
 />
+<li
+  on-click="select_item:$data_id"
+  data-id="42"
+>
+  Item
+</li>
 ```
 
 ---
@@ -341,93 +313,135 @@ registerPayloadResolver('$checked', function () {
 ## 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 listener total)      │
-│  → closest('[on-action]') → parse → run modifiers       │
-│  → dispatchAction('add-to-cart', '42')          [O(1)] │
-└────────────────────────┬────────────────────────────────┘
-                         │ action signal (O(1) routing)
-                         ▼
-┌─────────────────────────────────────────────────────────┐
-│                   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                         │
+│  <button on-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-click]') → 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
 ```
 
 ---
 
+## Page Identity
+
+For page-ready signals in SSG/SSR apps (reading `page-id` attribute and notifying
+page-specific handlers), use [`@alwatr/page-ready`](../page-ready/README.md) instead.
+It is intentionally separate from the action bus — page identity is a routing/lifecycle
+concern, not a user-interaction action.
+
+---
+
 ## Migration from Previous Versions
 
-### `registerActionDirective` / `registerPageIdDirective` removed
+### Attribute syntax changed
 
-The directive-based approach has been replaced by global delegation.
+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:**
 
-```ts
-import {registerActionDirective, registerPageIdDirective} from '@alwatr/action';
-import {bootstrapDirectives} from '@alwatr/directive';
-
-registerActionDirective();
-registerPageIdDirective();
-bootstrapDirectives();
+```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:**
 
-```ts
-import {setupActionDelegation, dispatchPageId} from '@alwatr/action';
-
-setupActionDelegation();
-dispatchPageId();
+```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>
 ```
 
-### `ActionDirective` / `PageIdDirective` removed
-
-These classes are no longer exported. Use `setupActionDelegation()` and
-`dispatchPageId()` instead.
-
-### `ModifierHandler` / `PayloadResolver` context changed
+### `ActionContext` removed
 
-The `this` context in custom modifier and resolver functions changed from
-`ActionDirective` to `ActionContext`:
+The `this` context in modifier and resolver handlers changed to explicit parameters:
 
 **Before:**
 
 ```ts
-registerModifier('not-disabled', function () {
-  return !(this.element_ as HTMLButtonElement).disabled; // this.element_
+registerModifier('not_disabled', function () {
+  return !(this.element as HTMLButtonElement).disabled;
 });
 ```
 
 **After:**
 
 ```ts
-registerModifier('not-disabled', function () {
-  return !(this.element as HTMLButtonElement).disabled; // this.element (no underscore)
+registerModifier('not_disabled', (_event, element) => {
+  return !(element as HTMLButtonElement).disabled;
 });
 ```
 
-### `ActionSignalPayload` removed
+### `page-ready` moved to `@alwatr/page-ready`
+
+`dispatchPageId` / `onPageReady` are no longer part of this package.
+
+---
+
+---
+
+## 🌊 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 Layer (@alwatr/action) — global delegation, O(1) routing
+  ↓
+Controller (business logic via onAction)
+  ↓
+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';
+```
 
-This type was an implementation detail of the old `EventSignal`-based bus and
-is no longer needed. Use `onAction` and `dispatchAction` directly.
+→ [View the complete Flux documentation](https://github.com/Alwatr/alwatr/tree/next/pkg/flux)
 
 ---
 

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;
  *   }
  * }
@@ -33,34 +33,22 @@
  * Extend this interface via declaration merging to register your application's
  * actions and gain full type safety in `onAction` and `dispatchAction`.
  *
- * Built-in system actions are declared here. Application-level actions should
- * be declared in a dedicated `action-record.ts` file within each feature package.
+ * 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};
+ *     'open_drawer': string;
+ *     'add_to_cart': {productId: number; qty: number};
  *     'logout': void;
  *   }
  * }
  * ```
  */
 export interface ActionRecord {
-    /**
-     * Dispatched by `dispatchPageId()` when the page identity is read from the
-     * `page-id` HTML attribute. Payload is the page identifier string.
-     *
-     * @example
-     * ```html
-     * <body page-id="home">…</body>
-     * ```
-     * ```ts
-     * onAction('page-ready', (pageId) => router.setPage(pageId));
-     * ```
-     */
-    'page-ready': string;
 }
 //# sourceMappingURL=action-record.d.ts.map

package/dist/action-record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-record.d.ts","sourceRoot":"","sources":["../src/action-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;;OAWG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB"}
+{"version":3,"file":"action-record.d.ts","sourceRoot":"","sources":["../src/action-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,YAAY;CAAG"}