@alwatr/action 9.12.0 → 9.14.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,93 @@ 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
-```
+### 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.
 
-## Attribute Syntax
+### 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.
 
 ```
-on-action="eventType->actionId"
-on-action="eventType->actionId:payload"
+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'
+           run modifiers   → none
+           resolve payload → '42'
+           internalChannel_.dispatch('add-to-cart', '42')
+                │
+                └─ Map.get('add-to-cart') → O(1) → 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** |
+| `once` modifier | Native option         | Remove attribute     |
 
-| Token        | Resolves to                                                    |
-| ------------ | -------------------------------------------------------------- |
-| `:$value`    | `element.value` (for `<input>`, `<select>`, `<textarea>`)      |
-| `:$formdata` | `Object.fromEntries(new FormData(form))` from nearest `<form>` |
+### `once` modifier
 
-### Event modifiers
+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.
 
-Modifiers are chained with `.` after the event type:
+---
 
-| 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()`     |
+## Installation
+
+```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';
+Extend `ActionRecord` via declaration merging. This gives you full type safety and IDE autocomplete — passing an undeclared action name is a **compile error**.
 
-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
+### 2. Bootstrap delegation
 
-```typescript
-import {onAction} from '@alwatr/action';
+```ts
+import {setupActionDelegation, onAction} from '@alwatr/action';
+import './action-record.js'; // ensure the declaration is loaded
 
-// Fires whenever any element with on-action="click->open-drawer:main" is clicked
-onAction('open-drawer', (payload) => {
-  openDrawer(payload); // payload === 'main'
-});
+setupActionDelegation();
 
-// Fires on every keystroke in an input with on-action="input->search-query:$value"
-onAction('search-query', (query) => {
-  performSearch(query);
+// 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
 });
 ```
 
@@ -97,9 +106,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,131 +113,183 @@ 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>
+
+<!-- Fires only once — attribute is removed after first click -->
+<button on-action="click.once->welcome-dismissed">Got it</button>
 ```
 
----
+### 4. Programmatic dispatch
 
-## Programmatic Dispatch
+```ts
+import {dispatchAction} from '@alwatr/action';
 
-Dispatch actions from code using `dispatchAction` — useful after async operations or from service layers:
+await uploadFile(file);
+dispatchAction('upload-complete', fileId);
 
-```typescript
-import {dispatchAction} from '@alwatr/action';
+dispatchAction('navigate', '/dashboard');
+```
+
+---
 
-dispatchAction('open-drawer', 'main');
-dispatchAction('navigate', '/home');
-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()`                                                   |
+| `.once`     | Removes the `on-action` attribute after first fire — action dispatches only once |
+| `.validate` | Cancels dispatch if the nearest `<form>` fails `checkValidity()`                 |
+
+### 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 via declaration merging to register typed actions.
 
-```typescript
-function onAction<T = string>(actionId: string, handler: (payload?: T) => void): SubscribeResult;
+```ts
+declare module '@alwatr/action' {
+  interface ActionRecord {
+    'open-drawer': string;
+    'logout': void;
+  }
+}
 ```
 
-| Parameter  | Type                    | Description                         |
-| ---------- | ----------------------- | ----------------------------------- |
-| `actionId` | `string`                | The action identifier to listen for |
-| `handler`  | `(payload?: T) => void` | Called with the resolved payload    |
+---
 
-Returns a `SubscribeResult` with an `unsubscribe()` method.
+### `setupActionDelegation(eventTypes?)`
 
-```typescript
-const sub = onAction('open-drawer', (payload) => {
-  /* … */
-});
+Registers global event delegation on `document.body`. Call once at bootstrap. Idempotent.
 
-// Stop listening when no longer needed (prevents memory leaks)
-sub.unsubscribe();
+```ts
+function setupActionDelegation(eventTypes?: readonly string[]): void;
 ```
 
----
+Defaults to `DEFAULT_DELEGATED_EVENTS`: `['click', 'submit', 'input', 'change']`.
 
-### `dispatchAction(actionId, payload?)`
-
-Dispatches a named action signal. Any `onAction` subscriber with a matching `actionId` will be invoked.
+```ts
+import {setupActionDelegation, DEFAULT_DELEGATED_EVENTS} from '@alwatr/action';
 
-```typescript
-function dispatchAction<T = string>(actionId: string, actionPayload?: T): void;
+setupActionDelegation([...DEFAULT_DELEGATED_EVENTS, 'keydown']);
 ```
 
 ---
 
-### `registerActionDirective()`
-
-Lazy registration for `ActionDirective`. Call once before `bootstrapDirectives()`.
-If never called, the entire directive module is tree-shaken from the bundle.
+### `teardownActionDelegation()`
 
-```typescript
-import {registerActionDirective} from '@alwatr/action';
-import {bootstrapDirectives} from '@alwatr/directive';
+Removes all delegation listeners and clears the descriptor cache. Useful in tests or micro-frontend teardown.
 
-registerActionDirective();
-bootstrapDirectives();
+```ts
+function teardownActionDelegation(): void;
 ```
 
 ---
 
-### `registerPageIdDirective()`
+### `onAction(actionId, handler)`
 
-Registers the `page-id` directive, which dispatches a `'page-ready'` action with the page ID as payload when the element is initialized.
+Subscribes to a named action. O(1) routing via `ChannelSignal`.
 
-```html
-<body page-id="home"></body>
+```ts
+function onAction<K extends keyof ActionRecord>(
+  actionId: K,
+  handler: (payload: ActionRecord[K]) => void,
+): SubscribeResult;
 ```
 
-```typescript
-import {registerPageIdDirective, onAction} from '@alwatr/action';
+```ts
+const sub = onAction('open-drawer', (panel) => openDrawer(panel));
+sub.unsubscribe(); // prevent memory leaks
+```
 
-registerPageIdDirective();
+---
 
-onAction('page-ready', (pageId) => {
-  console.log('Page is ready:', pageId); // 'home'
-});
+### `dispatchAction(actionId, payload?)`
+
+Dispatches a named action. Payload type is enforced by `ActionRecord`.
+
+```ts
+// With payload
+dispatchAction('open-drawer', 'settings');
+
+// Void payload — no second argument
+dispatchAction('logout');
 ```
 
 ---
 
 ### `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.
+
+Handler signature: `(event: Event, element: HTMLElement) => boolean`
 
-```typescript
+```ts
 import {registerModifier} from '@alwatr/action';
 
-registerModifier('confirm', function () {
-  return window.confirm('Are you sure?');
+// Arrow function — no `this` binding needed
+registerModifier('not-disabled', (_event, element) => {
+  return !(element as HTMLButtonElement).disabled;
 });
 ```
 
 ```html
-<button on-action="click.confirm->delete-item:42">Delete</button>
+<button
+  on-action="click.not-disabled->select-item:$data-id"
+  data-id="42"
+>
+  Select
+</button>
 ```
 
 ---
 
 ### `registerPayloadResolver(name, resolver)`
 
-Registers a custom payload resolver for use in `on-action` directives.
+Registers a custom payload resolver.
+
+Handler signature: `(event: Event, element: HTMLElement) => unknown`
 
-```typescript
+```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;
 });
 ```
 
@@ -240,18 +298,16 @@ registerPayloadResolver('$checked', function () {
   type="checkbox"
   on-action="change->toggle-feature:$checked"
 />
+<li
+  on-action="click->select-item:$data-id"
+  data-id="42"
+>
+  Item
+</li>
 ```
 
 ---
 
-### `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 +315,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 per event type)      │
+│  → closest('[on-action]') → parse → modifiers           │
+│  → internalChannel_.dispatch('add-to-cart', '42') [O(1)]│
 └────────────────────────┬────────────────────────────────┘
-                         │ action signal
+                         │ O(1) routing via ChannelSignal
                          ▼
 ┌─────────────────────────────────────────────────────────┐
 │                   Business Logic Layer                  │
@@ -275,45 +333,55 @@ 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
+## Page Identity
 
-```
-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)
-```
+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.
 
 ---
 
-## Cleanup & Memory Management
+## Migration from Previous Versions
 
-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.
+### `ActionContext` removed
 
-```typescript
-import {autoDestructDirectives} from '@alwatr/directive';
+The `this` context in modifier and resolver handlers changed to explicit parameters:
 
-// Clean up on every SPA navigation
-router.on('navigate', autoDestructDirectives);
+**Before:**
+
+```ts
+registerModifier('not-disabled', function () {
+  return !(this.element as HTMLButtonElement).disabled;
+});
+```
+
+**After:**
+
+```ts
+registerModifier('not-disabled', (_event, element) => {
+  return !(element as HTMLButtonElement).disabled;
+});
 ```
 
+### `once` behavior changed
+
+Previously tracked via `WeakSet`. Now removes the `on-action` attribute after first fire.
+Behavior is equivalent for typical use cases.
+
+### `page-ready` moved to `@alwatr/page-ready`
+
+`dispatchPageId` / `onPageReady` are no longer part of this package.
+
 ---
 
 ## Contributing

package/dist/action-record.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @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`.
+ *
+ * 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};
+ *     'logout': void;
+ *   }
+ * }
+ * ```
+ */
+export interface ActionRecord {
+}
+//# 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;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,YAAY;CAAG"}