@alwatr/action 9.12.0 → 9.13.0

package/README.md

@@ -2,9 +2,7 @@
 
 **Declarative DOM action-dispatch — the Action layer for Unidirectional Data Flow.**
 
-`@alwatr/action` bridges HTML attributes to typed signal handlers. Add an `on-action` attribute to any element, and the library automatically listens for the specified DOM event, resolves the payload, and dispatches a named action signal. Subscribe to actions anywhere in your app with `onAction`.
-
-This package serves as the **Action layer** in a Unidirectional Data Flow (UDF) architecture: UI elements declare their intent via `on-action` attributes, actions flow upward to business logic via `dispatchAction`, and state flows back down to the UI through signals.
+`@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.
 
 ---
 
@@ -12,82 +10,95 @@ This package serves as the **Action layer** in a Unidirectional Data Flow (UDF)
 
 | Approach                               | Problem                                                  |
 | -------------------------------------- | -------------------------------------------------------- |
-| Inline `addEventListener` everywhere   | Scattered, hard to trace, breaks on dynamic content      |
+| Inline `addEventListener` everywhere   | O(N) boot cost, scattered, breaks on dynamic content     |
 | Framework event bindings (React, Vue…) | Requires full framework buy-in                           |
 | Custom events + `dispatchEvent`        | Verbose, no typed payload, no central subscription point |
-| **`@alwatr/action`**                   | ✅ Declarative, typed, zero-coupling, SPA-friendly       |
+| **`@alwatr/action`**                   | ✅ O(1) boot, declarative, typed, zero-coupling          |
 
 ---
 
-## Installation
+## How It Works
 
-```bash
-bun add @alwatr/action
-# or
-npm i @alwatr/action
-```
+### Global Event Delegation
 
----
-
-## Attribute Syntax
+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`.
 
 ```
-on-action="eventType->actionId"
-on-action="eventType->actionId:payload"
+User clicks a button
+        │
+        ▼
+document.body capture listener (1 listener total)
+        │
+        └─ closest('[on-action]') → finds element
+           parse attribute → 'click->add-to-cart:42'
+           run modifiers   → none
+           resolve payload → '42'
+           dispatchAction('add-to-cart', '42')
+                │
+                ▼
+          ChannelSignal.dispatch('add-to-cart', '42')  [O(1)]
+                │
+                └─ Map.get('add-to-cart') → invoke only matching handlers
 ```
 
-| Segment     | Description                                                  | Example                       |
-| ----------- | ------------------------------------------------------------ | ----------------------------- |
-| `eventType` | Any standard DOM event name                                  | `click`, `input`, `submit`    |
-| `actionId`  | Identifier your handler subscribes to                        | `open-drawer`, `search-query` |
-| `:payload`  | Optional literal string, or `$value` to read `element.value` | `:main`, `:$value`            |
+### Complexity
 
-### Payload resolvers
+| Metric          | Per-element listeners | Global delegation    |
+| --------------- | --------------------- | -------------------- |
+| Boot time       | O(N elements)         | **O(1)**             |
+| Memory          | O(N listeners)        | **O(1)**             |
+| Dynamic content | Requires re-bootstrap | **Works out-of-box** |
 
-| Token        | Resolves to                                                    |
-| ------------ | -------------------------------------------------------------- |
-| `:$value`    | `element.value` (for `<input>`, `<select>`, `<textarea>`)      |
-| `:$formdata` | `Object.fromEntries(new FormData(form))` from nearest `<form>` |
+### 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.
 
-### Event modifiers
+---
 
-Modifiers are chained with `.` after the event type:
+## Installation
 
-| Modifier    | Behavior                                                             |
-| ----------- | -------------------------------------------------------------------- |
-| `.prevent`  | Calls `event.preventDefault()`                                       |
-| `.stop`     | Calls `event.stopPropagation()`                                      |
-| `.once`     | Removes the listener after the first dispatch (native `once` option) |
-| `.passive`  | Marks the listener as passive (cannot be combined with `.prevent`)   |
-| `.validate` | Cancels dispatch if the nearest `<form>` fails `checkValidity()`     |
+```bash
+bun add @alwatr/action
+# or
+npm i @alwatr/action
+```
 
 ---
 
 ## Quick Start
 
-### 1. Register the directive and bootstrap
+### 1. Register your action types
 
-```typescript
-import {bootstrapDirectives} from '@alwatr/directive';
-import {registerActionDirective} from '@alwatr/action';
+Create a declaration file in your package to extend `ActionRecord`. This gives you full type safety and IDE autocomplete across the entire app:
 
-registerActionDirective(); // registers ActionDirective under 'on-action'
-bootstrapDirectives();
+```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;
+  }
+}
 ```
 
-### 2. Subscribe to actions
+Passing an action name not declared in `ActionRecord` is a **compile error** — there is no string fallback.
 
-```typescript
-import {onAction} from '@alwatr/action';
+### 2. Bootstrap delegation
 
-// Fires whenever any element with on-action="click->open-drawer:main" is clicked
-onAction('open-drawer', (payload) => {
-  openDrawer(payload); // payload === 'main'
-});
+```ts
+import {setupActionDelegation, onAction} from '@alwatr/action';
+import './action-record.js'; // ensure the declaration is loaded
 
-// Fires on every keystroke in an input with on-action="input->search-query:$value"
-onAction('search-query', (query) => {
-  performSearch(query);
+// 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 `!`
 });
 ```
 
@@ -97,9 +108,6 @@ onAction('search-query', (query) => {
 <!-- Dispatches 'open-drawer' with payload 'main' on click -->
 <button on-action="click->open-drawer:main">Open Drawer</button>
 
-<!-- Dispatches 'open-drawer' with payload 'settings' on click -->
-<button on-action="click->open-drawer:settings">Settings</button>
-
 <!-- Dispatches 'search-query' with the input's live value -->
 <input
   type="search"
@@ -107,99 +115,175 @@ onAction('search-query', (query) => {
   placeholder="Search…"
 />
 
-<!-- Prevents default and validates form before dispatching all field values -->
+<!-- Prevents default, validates, then dispatches all field values -->
 <form
   on-action="submit.prevent.validate->submit-form:$formdata"
   novalidate
 >
-  <!-- ... -->
+  <input
+    name="username"
+    required
+  />
+  <button type="submit">Save</button>
 </form>
 ```
 
----
-
-## Programmatic Dispatch
+### 3. Programmatic dispatch
 
-Dispatch actions from code using `dispatchAction` — useful after async operations or from service layers:
-
-```typescript
+```ts
 import {dispatchAction} from '@alwatr/action';
 
-dispatchAction('open-drawer', 'main');
-dispatchAction('navigate', '/home');
+// Trigger actions from code — after async ops, from service layers, etc.
+await uploadFile(file);
+dispatchAction('upload-complete', fileId);
+
+dispatchAction('navigate', '/dashboard');
 dispatchAction<{code: number}>('show-error', {code: 404});
 ```
 
 ---
 
+## Attribute Syntax
+
+```
+on-action="eventType[.modifier…]->actionId[:payload]"
+```
+
+| 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`            |
+
+### 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.
+
+### Built-in payload resolvers
+
+| Token        | Resolves to                                                    |
+| ------------ | -------------------------------------------------------------- |
+| `:$value`    | `element.value` (for `<input>`, `<select>`, `<textarea>`)      |
+| `:$formdata` | `Object.fromEntries(new FormData(form))` from nearest `<form>` |
+
+---
+
 ## API Reference
 
-### `onAction(actionId, handler)`
+### `ActionRecord` (interface)
 
-Subscribes to a named action dispatched by any `on-action` directive or `dispatchAction` call.
+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`.
 
-```typescript
-function onAction<T = string>(actionId: string, handler: (payload?: T) => void): SubscribeResult;
+```ts
+// src/action-record.ts
+declare module '@alwatr/action' {
+  interface ActionRecord {
+    'open-drawer': string;
+    'add-to-cart': {productId: number; qty: number};
+    'logout': void;
+  }
+}
 ```
 
-| Parameter  | Type                    | Description                         |
-| ---------- | ----------------------- | ----------------------------------- |
-| `actionId` | `string`                | The action identifier to listen for |
-| `handler`  | `(payload?: T) => void` | Called with the resolved payload    |
+Once declared:
 
-Returns a `SubscribeResult` with an `unsubscribe()` method.
+- `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**
 
-```typescript
-const sub = onAction('open-drawer', (payload) => {
-  /* … */
-});
+---
 
-// Stop listening when no longer needed (prevents memory leaks)
-sub.unsubscribe();
+### `setupActionDelegation(eventTypes?)`
+
+Registers global event delegation on `document.body`. Call once at bootstrap.
+Subsequent calls with the same event types are no-ops (idempotent).
+
+```ts
+function setupActionDelegation(eventTypes?: readonly string[]): void;
+```
+
+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']);
 ```
 
 ---
 
-### `dispatchAction(actionId, payload?)`
+### `teardownActionDelegation()`
 
-Dispatches a named action signal. Any `onAction` subscriber with a matching `actionId` will be invoked.
+Removes all delegation listeners. Useful in tests or micro-frontend teardown.
 
-```typescript
-function dispatchAction<T = string>(actionId: string, actionPayload?: T): void;
+```ts
+function teardownActionDelegation(): void;
 ```
 
 ---
 
-### `registerActionDirective()`
+### `onAction(actionId, handler)`
 
-Lazy registration for `ActionDirective`. Call once before `bootstrapDirectives()`.
-If never called, the entire directive module is tree-shaken from the bundle.
+Subscribes to a named action. Uses `ChannelSignal.on()` for O(1) routing.
 
-```typescript
-import {registerActionDirective} from '@alwatr/action';
-import {bootstrapDirectives} from '@alwatr/directive';
+```ts
+function onAction<T = string>(actionId: string, handler: (payload?: T) => void): SubscribeResult;
+```
 
-registerActionDirective();
-bootstrapDirectives();
+```ts
+const sub = onAction('open-drawer', (panel) => openDrawer(panel));
+
+// Unsubscribe when no longer needed (prevents memory leaks)
+sub.unsubscribe();
 ```
 
 ---
 
-### `registerPageIdDirective()`
+### `dispatchAction(actionId, payload?)`
+
+Dispatches a named action to all matching `onAction` subscribers.
 
-Registers the `page-id` directive, which dispatches a `'page-ready'` action with the page ID as payload when the element is initialized.
+```ts
+function dispatchAction<T = string>(actionId: string, actionPayload?: T): void;
+```
+
+---
+
+### `dispatchPageId(element?)`
+
+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>
+<body page-id="home">
+  …
+</body>
 ```
 
-```typescript
-import {registerPageIdDirective, onAction} from '@alwatr/action';
+```ts
+import {dispatchPageId, onAction} from '@alwatr/action';
 
-registerPageIdDirective();
+dispatchPageId(); // → dispatchAction('page-ready', 'home')
 
 onAction('page-ready', (pageId) => {
-  console.log('Page is ready:', pageId); // 'home'
+  console.log('navigated to:', pageId); // 'home'
 });
 ```
 
@@ -207,9 +291,10 @@ onAction('page-ready', (pageId) => {
 
 ### `registerModifier(name, handler)`
 
-Registers a custom modifier for use in `on-action` directives. Return `false` from the handler to cancel the dispatch.
+Registers a custom modifier. Return `false` to cancel the dispatch.
+Works with both delegation and programmatic dispatch.
 
-```typescript
+```ts
 import {registerModifier} from '@alwatr/action';
 
 registerModifier('confirm', function () {
@@ -221,17 +306,26 @@ registerModifier('confirm', function () {
 <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
+}
+```
+
 ---
 
 ### `registerPayloadResolver(name, resolver)`
 
-Registers a custom payload resolver for use in `on-action` directives.
+Registers a custom payload resolver. The return value becomes the action payload.
+Works with both delegation and programmatic dispatch.
 
-```typescript
+```ts
 import {registerPayloadResolver} from '@alwatr/action';
 
 registerPayloadResolver('$checked', function () {
-  return (this.element_ as HTMLInputElement).checked;
+  return (this.element as HTMLInputElement).checked;
 });
 ```
 
@@ -244,14 +338,6 @@ registerPayloadResolver('$checked', function () {
 
 ---
 
-### `ActionDirective`
-
-The directive class registered under the `on-action` attribute. Extends `Directive` from `@alwatr/directive`.
-
-You rarely need to interact with this class directly — use `registerActionDirective()` to register it.
-
----
-
 ## Unidirectional Data Flow
 
 ```
@@ -259,13 +345,15 @@ You rarely need to interact with this class directly — use `registerActionDire
 │                        UI Layer                         │
 │  <button on-action="click->add-to-cart:42">Add</button> │
 └────────────────────────┬────────────────────────────────┘
-                         │ DOM event
+                         │ DOM event bubbles to body
                          ▼
 ┌─────────────────────────────────────────────────────────┐
-│                    Action Layer (@alwatr/action)         │
-│  dispatchAction('add-to-cart', '42')                    │
+│              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
+                         │ action signal (O(1) routing)
                          ▼
 ┌─────────────────────────────────────────────────────────┐
 │                   Business Logic Layer                  │
@@ -275,45 +363,72 @@ You rarely need to interact with this class directly — use `registerActionDire
                          ▼
 ┌─────────────────────────────────────────────────────────┐
 │                    State Layer (@alwatr/signal)          │
-│  cartSignal.dispatch(newCartState)                      │
+│  cartSignal.set(newCartState)                           │
 └────────────────────────┬────────────────────────────────┘
                          │ state flows down to UI
                          ▼
-                      UI Layer
+                      UI re-renders
 ```
 
 ---
 
-## Lifecycle
+## Migration from Previous Versions
+
+### `registerActionDirective` / `registerPageIdDirective` removed
+
+The directive-based approach has been replaced by global delegation.
+
+**Before:**
 
+```ts
+import {registerActionDirective, registerPageIdDirective} from '@alwatr/action';
+import {bootstrapDirectives} from '@alwatr/directive';
+
+registerActionDirective();
+registerPageIdDirective();
+bootstrapDirectives();
 ```
-bootstrapDirectives()
-  │
-  └─ finds element with on-action="click->open-drawer:main"
-       │
-       └─ new ActionDirective(element, 'on-action')
-            │
-            └─ after one macrotask → init_()
-                 │
-                 ├─ parse attributeValue with syntaxRegex
-                 ├─ if invalid → log accident, return
-                 └─ addEventListener(eventType, dispatch_)
-                    addDestroyHook(removeEventListener)
+
+**After:**
+
+```ts
+import {setupActionDelegation, dispatchPageId} from '@alwatr/action';
+
+setupActionDelegation();
+dispatchPageId();
 ```
 
----
+### `ActionDirective` / `PageIdDirective` removed
+
+These classes are no longer exported. Use `setupActionDelegation()` and
+`dispatchPageId()` instead.
 
-## Cleanup & Memory Management
+### `ModifierHandler` / `PayloadResolver` context changed
 
-Every `addEventListener` registered by the directive has a corresponding `removeEventListener` in a destroy hook. Call `autoDestructDirectives()` periodically (or on route changes) to clean up directives whose elements have been removed from the DOM.
+The `this` context in custom modifier and resolver functions changed from
+`ActionDirective` to `ActionContext`:
 
-```typescript
-import {autoDestructDirectives} from '@alwatr/directive';
+**Before:**
 
-// Clean up on every SPA navigation
-router.on('navigate', autoDestructDirectives);
+```ts
+registerModifier('not-disabled', function () {
+  return !(this.element_ as HTMLButtonElement).disabled; // this.element_
+});
 ```
 
+**After:**
+
+```ts
+registerModifier('not-disabled', function () {
+  return !(this.element as HTMLButtonElement).disabled; // this.element (no underscore)
+});
+```
+
+### `ActionSignalPayload` removed
+
+This type was an implementation detail of the old `EventSignal`-based bus and
+is no longer needed. Use `onAction` and `dispatchAction` directly.
+
 ---
 
 ## Contributing

package/dist/action-record.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @file action-record.ts
+ *
+ * Global action type registry via TypeScript declaration merging.
+ *
+ * ## How it works
+ *
+ * `ActionRecord` is an open interface — any package in the monorepo (or any
+ * consumer application) can extend it with their own action names and payload
+ * types using declaration merging, without modifying this file:
+ *
+ * ```ts
+ * // In your package: src/action-record.ts
+ * declare module '@alwatr/action' {
+ *   interface ActionRecord {
+ *     'open-drawer': string;
+ *     'add-to-cart': {productId: number; qty: number};
+ *     'logout': void;
+ *   }
+ * }
+ * ```
+ *
+ * Once declared, `onAction` and `dispatchAction` become fully type-safe for
+ * those action names — the compiler enforces the correct payload type at every
+ * call site and provides autocomplete for action identifiers.
+ *
+ * Only actions declared in `ActionRecord` are accepted. Passing an unknown
+ * action name is a **compile error** — there is no string fallback.
+ */
+/**
+ * Global registry mapping action identifiers to their payload types.
+ *
+ * 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.
+ *
+ * @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};
+ *     '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

@@ -0,0 +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"}