@alwatr/action 9.11.2

package/dist/directive.d.ts

@@ -0,0 +1,94 @@
+import { Directive } from '@alwatr/directive';
+/**
+ * Directive that bridges a DOM event to a typed action signal.
+ *
+ * Activated automatically by the `on-action` HTML attribute when
+ * `registerActionDirective()` has been called before `bootstrapDirectives()`.
+ * You rarely need to reference this class directly.
+ *
+ * **Attribute syntax**
+ * ```
+ * on-action="eventType[.modifier…]->actionId[:payload]"
+ * ```
+ *
+ * - `eventType` — any standard DOM event name (e.g. `click`, `input`, `submit`).
+ * - `modifier` — dot-chained tokens processed before dispatch
+ *   (`prevent`, `stop`, `validate`, `once`, `passive`, or custom).
+ * - `actionId` — the identifier passed to `onAction` subscribers.
+ * - `payload` — an optional literal string or a `$`-prefixed resolver token
+ *   (e.g. `$value`, `$formdata`, or custom).
+ *
+ * @example
+ * ```html
+ * <!-- Dispatches 'open-drawer' with payload 'settings' on click -->
+ * <button on-action="click->open-drawer:settings">Settings</button>
+ *
+ * <!-- Dispatches 'search-query' with the live input value on every keystroke -->
+ * <input on-action="input->search-query:$value" />
+ *
+ * <!-- Prevents default, validates, then dispatches 'submit-form' with all field values -->
+ * <form on-action="submit.prevent.validate->submit-form:$formdata" novalidate>…</form>
+ * ```
+ */
+export declare class ActionDirective extends Directive {
+    /**
+     * Parsed and validated representation of the `on-action` attribute value.
+     *
+     * Set during `init_()` after the attribute is successfully parsed against
+     * `syntaxRegex`. Remains `undefined` when the attribute value is invalid,
+     * which prevents `dispatch_` from running.
+     */
+    protected actionContext_?: {
+        /** The DOM event type to listen for (e.g. `'click'`, `'input'`). */
+        eventType: string;
+        /** Set of active modifier names (e.g. `{'prevent', 'once'}`). */
+        modifiers: ReadonlySet<string>;
+        /** The action identifier dispatched to `onAction` subscribers. */
+        actionId: string;
+        /** Raw payload token from the attribute (literal string or `$`-resolver key). */
+        payload?: string;
+    };
+    /**
+     * Parses the `on-action` attribute, validates modifiers, and attaches the
+     * DOM event listener.
+     *
+     * Called once by `Directive` after one macrotask following element discovery.
+     * If the attribute value is malformed or references an unknown modifier,
+     * an accident is logged and the directive becomes a no-op.
+     */
+    protected init_(): void;
+    /**
+     * DOM event handler: runs modifiers, resolves the payload, and dispatches
+     * the action signal.
+     *
+     * Execution order:
+     * 1. Each modifier in `actionContext_.modifiers` is called in insertion order.
+     *    If any returns `false` the method returns early — no action is dispatched.
+     * 2. The raw payload token is looked up in `payloadRegistry`. If a resolver
+     *    is found it is called and its return value replaces the token.
+     * 3. `dispatchAction` is called with the resolved payload.
+     *
+     * @param event - The DOM event that triggered this handler.
+     */
+    protected dispatch_(event: Event): void;
+}
+/**
+ * Registers `ActionDirective` under the `on-action` attribute name.
+ *
+ * This is a **lazy** registration: calling this function is the only way to
+ * opt-in to `on-action` support. If it is never called, the entire directive
+ * module (including `ActionDirective`) is tree-shaken from the bundle.
+ *
+ * Call it once, before `bootstrapDirectives()`, at your application entry point.
+ *
+ * @example
+ * ```ts
+ * import {registerActionDirective} from '@alwatr/action';
+ * import {bootstrapDirectives} from '@alwatr/directive';
+ *
+ * registerActionDirective();
+ * bootstrapDirectives();
+ * ```
+ */
+export declare const registerActionDirective: () => void;
+//# sourceMappingURL=directive.d.ts.map

package/dist/directive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive.d.ts","sourceRoot":"","sources":["../src/directive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,SAAS,EAAC,MAAM,mBAAmB,CAAC;AA4B3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,eAAgB,SAAQ,SAAS;IAC5C;;;;;;OAMG;IACH,SAAS,CAAC,cAAc,CAAC,EAAE;QACzB,oEAAoE;QACpE,SAAS,EAAE,MAAM,CAAC;QAClB,iEAAiE;QACjE,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QAC/B,kEAAkE;QAClE,QAAQ,EAAE,MAAM,CAAC;QACjB,iFAAiF;QACjF,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF;;;;;;;OAOG;cACgB,KAAK,IAAI,IAAI;IAsDhC;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;CAqBxC;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,YAA8C,CAAC"}

package/dist/lib.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The shape of every payload carried by the internal action signal.
+ *
+ * `actionId` identifies which action was dispatched (e.g. `'open-drawer'`).
+ * `actionPayload` is the optional value attached to the action — defaults to
+ * `string` but can be narrowed to any type via the generic parameter `T`.
+ *
+ * @template T The type of the action payload. Defaults to `string`.
+ *
+ * @example
+ * ```ts
+ * // Typed payload for a cart action
+ * const payload: ActionSignalPayload<{productId: number; qty: number}> = {
+ *   actionId: 'add-to-cart',
+ *   actionPayload: {productId: 42, qty: 1},
+ * };
+ * ```
+ */
+export interface ActionSignalPayload<T = string> {
+    actionId: string;
+    actionPayload?: T;
+}
+/**
+ * Module-scoped logger for `@alwatr/action`.
+ * Scoped to `'alwatr-action'` so log lines are easy to filter in the console.
+ *
+ * @internal
+ */
+export declare const logger_: import("@alwatr/logger").AlwatrLogger;
+/**
+ * The single shared event signal that carries every dispatched action.
+ *
+ * All `ActionDirective` instances write to this signal via `dispatchAction`,
+ * and all `onAction` subscriptions read from it. Using one central signal keeps
+ * the pub/sub wiring minimal and makes the action flow easy to trace.
+ *
+ * The payload is typed as `ActionSignalPayload<unknown>` at the signal level;
+ * individual subscribers narrow the type through the `onAction` generic.
+ *
+ * @internal — not part of the public API; use `onAction` / `dispatchAction` instead.
+ */
+export declare const internalSignal_: import("@alwatr/signal").EventSignal<ActionSignalPayload<unknown>>;
+//# sourceMappingURL=lib.d.ts.map

package/dist/lib.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,MAAM;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,CAAC,CAAC;CACnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,uCAAgC,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,oEAA2E,CAAC"}

package/dist/main.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @alwatr/action — Declarative DOM action-dispatch for Unidirectional Data Flow.
+ *
+ * Public API surface:
+ * - `onAction` / `dispatchAction` — subscribe to and dispatch named actions
+ * - `registerActionDirective` — opt-in to `on-action` HTML attribute support
+ * - `registerPageIdDirective` — opt-in to `page-id` HTML attribute support
+ * - `registerModifier` / `registerPayloadResolver` — extend the directive syntax
+ * - `ActionDirective` / `PageIdDirective` — directive classes (advanced use)
+ * - `ActionSignalPayload` — payload type carried by the internal signal
+ */
+export * from './method.js';
+export * from './directive.js';
+export * from './page-id.js';
+export type { ActionSignalPayload } from './lib.js';
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,YAAY,EAAC,mBAAmB,EAAC,MAAM,UAAU,CAAC"}

package/dist/main.js

@@ -0,0 +1,5 @@
+/* 📦 @alwatr/action v9.11.2 */
+import{createLogger as S}from"@alwatr/logger";import{createEventSignal as V}from"@alwatr/signal";var J=S("alwatr-action"),Y=V({name:"alwatr-action"});var H=new Map,N=new Map;H.set("prevent",(M)=>{return M.preventDefault(),!0});H.set("stop",(M)=>{return M.stopPropagation(),!0});H.set("validate",function(){let M=this.element_ instanceof HTMLFormElement?this.element_:this.element_.closest("form");if(!M)return this.logger_.accident("validate_modifier","no_form_found",{element:this.element_}),!1;return M.checkValidity()});N.set("$value",function(){return"value"in this.element_?this.element_.value:null});N.set("$formdata",function(){let M=this.element_ instanceof HTMLFormElement?this.element_:this.element_.closest("form");return M?Object.fromEntries(new FormData(M).entries()):null});function k(M,q){return J.logMethodArgs?.("onAction",{actionId:M}),Y.subscribe((G)=>{if(G.actionId===M)J.logMethodArgs?.("onAction.invoke",{actionId:M,payload:G.actionPayload}),q(G.actionPayload)})}function X(M,q){J.logMethodArgs?.("dispatchAction",{actionId:M,actionPayload:q}),Y.dispatch({actionId:M,actionPayload:q})}function w(M,q){if(J.logMethodArgs?.("registerModifier",{name:M}),H.has(M))J.accident("registerModifier","modifier_already_registered",{name:M});H.set(M,q)}function D(M,q){if(J.logMethodArgs?.("registerPayloadResolver",{name:M}),N.has(M))J.accident("registerPayloadResolver","payload_resolver_already_registered",{name:M});N.set(M,q)}import{lazyDirective as C,Directive as L}from"@alwatr/directive";var z=/^([a-z0-9.-]+)->([a-z0-9-]+)(?::(.+))?$/;class F extends L{actionContext_;init_(){this.logger_.logMethodArgs?.("init_",{attributeValue:this.attributeValue});let M=this.attributeValue.trim().match(z);if(!M){this.logger_.accident("init_","invalid_syntax",{attributeValue:this.attributeValue});return}let[q,...G]=M[1].split("."),Q=M[2],W=M[3];if(!q){this.logger_.accident("init_","invalid_syntax",{attributeValue:this.attributeValue});return}let K=new Set;for(let U of G){if(!H.has(U)&&U!=="once"&&U!=="passive"){this.logger_.accident("init_","invalid_modifier",{attributeValue:this.attributeValue,modifier:U});return}K.add(U)}if(K.has("prevent")&&K.has("passive"))this.logger_.accident("init_","conflicting_modifiers_prevent_passive",{attributeValue:this.attributeValue});this.actionContext_={eventType:q,modifiers:K,actionId:Q,payload:W};let Z={once:K.has("once"),passive:K.has("passive")&&!K.has("prevent")},B=this.dispatch_.bind(this);this.element_.addEventListener(q,B,Z),this.addDestroyHook(()=>{this.element_.removeEventListener(q,B,Z)})}dispatch_(M){this.logger_.logMethodArgs?.("dispatch_",{eventType:M.type,actionId:this.actionContext_?.actionId});let q=this.actionContext_;for(let Q of q.modifiers){let W=H.get(Q);if(W&&W.call(this,M)===!1)return}let G=q.payload;if(G){let Q=N.get(G);if(Q)G=Q.call(this,M)}X(q.actionId,G)}}var u=C("on-action",F);import{Directive as j,lazyDirective as E}from"@alwatr/directive";class O extends j{init_(){let M=this.attributeValue.trim();if(this.logger_.logMethodArgs?.("init_",{pageId:M}),!M){this.logger_.accident("init_","empty_page_id");return}X("page-ready",M),this.destroy()}}var h=E("page-id",O);export{D as registerPayloadResolver,h as registerPageIdDirective,w as registerModifier,u as registerActionDirective,k as onAction,X as dispatchAction,O as PageIdDirective,F as ActionDirective};
+
+//# debugId=78292B0ADE08B5FA64756E2164756E21
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1,14 @@
+{
+  "version": 3,
+  "sources": ["../src/lib.ts", "../src/registry.ts", "../src/method.ts", "../src/directive.ts", "../src/page-id.ts"],
+  "sourcesContent": [
+    "import {createLogger} from '@alwatr/logger';\nimport {createEventSignal} from '@alwatr/signal';\n\n/**\n * The shape of every payload carried by the internal action signal.\n *\n * `actionId` identifies which action was dispatched (e.g. `'open-drawer'`).\n * `actionPayload` is the optional value attached to the action — defaults to\n * `string` but can be narrowed to any type via the generic parameter `T`.\n *\n * @template T The type of the action payload. Defaults to `string`.\n *\n * @example\n * ```ts\n * // Typed payload for a cart action\n * const payload: ActionSignalPayload<{productId: number; qty: number}> = {\n *   actionId: 'add-to-cart',\n *   actionPayload: {productId: 42, qty: 1},\n * };\n * ```\n */\nexport interface ActionSignalPayload<T = string> {\n  actionId: string;\n  actionPayload?: T;\n}\n\n/**\n * Module-scoped logger for `@alwatr/action`.\n * Scoped to `'alwatr-action'` so log lines are easy to filter in the console.\n *\n * @internal\n */\nexport const logger_ = createLogger('alwatr-action');\n\n/**\n * The single shared event signal that carries every dispatched action.\n *\n * All `ActionDirective` instances write to this signal via `dispatchAction`,\n * and all `onAction` subscriptions read from it. Using one central signal keeps\n * the pub/sub wiring minimal and makes the action flow easy to trace.\n *\n * The payload is typed as `ActionSignalPayload<unknown>` at the signal level;\n * individual subscribers narrow the type through the `onAction` generic.\n *\n * @internal — not part of the public API; use `onAction` / `dispatchAction` instead.\n */\nexport const internalSignal_ = createEventSignal<ActionSignalPayload<unknown>>({name: 'alwatr-action'});\n",
+    "import type {ActionDirective} from './directive.js';\n\n// ─── Type Definitions ────────────────────────────────────────────────────────\n\n/**\n * A modifier handler attached to an `on-action` directive.\n *\n * Called with the directive instance as `this` and the triggering DOM `event`.\n * Return `true` to allow the action to proceed, or `false` to cancel it.\n * Returning `false` is the only way a modifier can veto a dispatch.\n *\n * @example\n * ```ts\n * // A modifier that only allows the action when the element is not disabled\n * const notDisabledHandler: ModifierHandler = function () {\n *   return !(this.element_ as HTMLButtonElement).disabled;\n * };\n * ```\n */\nexport type ModifierHandler = (this: ActionDirective, event: Event) => boolean;\n\n/**\n * A payload resolver attached to an `on-action` directive.\n *\n * Called with the directive instance as `this` and the triggering DOM `event`\n * at dispatch time. The return value becomes the `actionPayload` of the\n * dispatched action. Use this to compute dynamic payloads from the DOM state.\n *\n * @example\n * ```ts\n * // A resolver that returns the element's dataset id\n * const dataIdResolver: PayloadResolver = function () {\n *   return (this.element_ as HTMLElement).dataset.id ?? null;\n * };\n * ```\n */\nexport type PayloadResolver = (this: ActionDirective, event: Event) => unknown;\n\n// ─── Registries ──────────────────────────────────────────────────────────────\n\n/**\n * Registry of all named modifier handlers.\n *\n * Keys are modifier names used in the `on-action` attribute syntax\n * (e.g. `click.prevent->action-id`). Values are `ModifierHandler` functions.\n * Populated at module load with built-in modifiers; extended at runtime via\n * `registerModifier`.\n *\n * @internal\n */\nexport const modifierRegistry = new Map<string, ModifierHandler>();\n\n/**\n * Registry of all named payload resolvers.\n *\n * Keys are resolver tokens used in the `on-action` attribute syntax\n * (e.g. `click->action-id:$value`). Values are `PayloadResolver` functions.\n * Populated at module load with built-in resolvers; extended at runtime via\n * `registerPayloadResolver`.\n *\n * @internal\n */\nexport const payloadRegistry = new Map<string, PayloadResolver>();\n\n// ─── Built-in Modifiers ───────────────────────────────────────────────────────\n\n/**\n * `prevent` — calls `event.preventDefault()` before dispatching.\n *\n * Use it to suppress the browser's default behaviour (e.g. form submission,\n * link navigation, context menu).\n *\n * @example `<form on-action=\"submit.prevent->submit-form\">`\n */\nmodifierRegistry.set('prevent', (event) => {\n  event.preventDefault();\n  return true;\n});\n\n/**\n * `stop` — calls `event.stopPropagation()` before dispatching.\n *\n * Prevents the event from bubbling further up the DOM tree. Useful when a\n * child element should handle a click without triggering a parent's listener.\n *\n * @example `<button on-action=\"click.stop->select-item:42\">`\n */\nmodifierRegistry.set('stop', (event) => {\n  event.stopPropagation();\n  return true;\n});\n\n/**\n * `validate` — cancels the dispatch if the nearest `<form>` fails validation.\n *\n * Looks for a `<form>` ancestor (or the element itself if it is a form) and\n * calls `checkValidity()`. If the form is invalid the action is not dispatched,\n * allowing native constraint-validation UI to surface errors. If no form is\n * found the dispatch is also cancelled and an accident is logged.\n *\n * Pair with `.prevent` on `submit` events to avoid page reloads:\n *\n * @example `<form on-action=\"submit.prevent.validate->submit-form\" novalidate>`\n */\nmodifierRegistry.set('validate', function () {\n  const form = this.element_ instanceof HTMLFormElement ? this.element_ : this.element_.closest('form');\n  if (!form) {\n    this.logger_.accident('validate_modifier', 'no_form_found', {element: this.element_});\n    return false;\n  }\n  return form.checkValidity();\n});\n\n// ─── Built-in Payload Resolvers ───────────────────────────────────────────────\n\n/**\n * `$value` — resolves to the element's `.value` property at dispatch time.\n *\n * Works with any element that exposes a `value` property: `<input>`,\n * `<textarea>`, `<select>`. Returns `null` for elements without `.value`.\n *\n * @example `<input on-action=\"input->search-query:$value\" />`\n */\npayloadRegistry.set('$value', function () {\n  return 'value' in this.element_ ? (this.element_ as {value: unknown}).value : null;\n});\n\n/**\n * `$formdata` — resolves to a plain object of all fields in the nearest `<form>`.\n *\n * Collects entries via `FormData` and converts them to a `Record<string, FormDataEntryValue>`.\n * Looks for a `<form>` ancestor (or the element itself). Returns `null` when no\n * form is found.\n *\n * @example `<form on-action=\"submit.prevent.validate->submit-form\">`\n * ```ts\n * onAction<Record<string, FormDataEntryValue>>('submit-form', (data) => {\n *   console.log(data); // {username: 'ali', password: '…'}\n * });\n * ```\n */\npayloadRegistry.set('$formdata', function () {\n  const form = this.element_ instanceof HTMLFormElement ? this.element_ : this.element_.closest('form');\n  return form ? Object.fromEntries(new FormData(form).entries()) : null;\n});\n",
+    "import {internalSignal_, logger_} from './lib.js';\nimport type {SubscribeResult} from '@alwatr/signal';\nimport {modifierRegistry, payloadRegistry, type ModifierHandler, type PayloadResolver} from './registry.js';\n\n// Re-export extension types so consumers can import them from the package root.\nexport type {ModifierHandler, PayloadResolver};\n\n// ─── Core Action API ──────────────────────────────────────────────────────────\n\n/**\n * Subscribes to a named action dispatched anywhere in the application.\n *\n * The handler is invoked every time `dispatchAction(actionId, payload)` is\n * called — whether from an `on-action` directive or from code — and the\n * `actionId` matches. Multiple subscribers for the same `actionId` are all\n * notified in subscription order.\n *\n * The generic parameter `T` narrows the type of the received payload.\n * Defaults to `string`, which covers the common case of attribute-driven\n * literal payloads.\n *\n * @param actionId - The action identifier to listen for (e.g. `'open-drawer'`).\n * @param handler  - Callback invoked with the resolved payload each time the\n *                   action is dispatched. `payload` is `undefined` when the\n *                   action was dispatched without a value.\n * @returns A `SubscribeResult` with an `unsubscribe()` method for cleanup.\n *\n * @example — basic string payload\n * ```ts\n * import {onAction} from '@alwatr/action';\n *\n * const sub = onAction('open-drawer', (panel) => {\n *   openDrawer(panel); // panel === 'settings'\n * });\n *\n * // Stop listening when the component is destroyed\n * sub.unsubscribe();\n * ```\n *\n * @example — typed object payload\n * ```ts\n * import {onAction} from '@alwatr/action';\n *\n * onAction<{productId: number; qty: number}>('add-to-cart', (item) => {\n *   cartService.add(item!.productId, item!.qty);\n * });\n * ```\n */\nexport function onAction<T = string>(actionId: string, handler: (payload?: T) => void): SubscribeResult {\n  logger_.logMethodArgs?.('onAction', {actionId});\n  return internalSignal_.subscribe((signal) => {\n    if (signal.actionId === actionId) {\n      logger_.logMethodArgs?.('onAction.invoke', {actionId, payload: signal.actionPayload});\n      handler(signal.actionPayload as T);\n    }\n  });\n}\n\n/**\n * Dispatches a named action to all `onAction` subscribers with a matching `actionId`.\n *\n * This is the programmatic counterpart to the `on-action` HTML attribute.\n * Use it when you need to trigger an action from code rather than from a DOM\n * event (e.g. after an async operation completes, or from a service layer).\n *\n * The generic parameter `T` types the payload. Omit it to default to `string`.\n *\n * @param actionId     - The action identifier (e.g. `'navigate'`).\n * @param actionPayload - Optional value passed to every matching subscriber.\n *\n * @example — dispatch without payload\n * ```ts\n * import {dispatchAction} from '@alwatr/action';\n *\n * dispatchAction('logout');\n * ```\n *\n * @example — dispatch with a typed payload\n * ```ts\n * import {dispatchAction} from '@alwatr/action';\n *\n * dispatchAction('navigate', '/dashboard');\n * dispatchAction<{code: number}>('show-error', {code: 404});\n * ```\n */\nexport function dispatchAction<T = string>(actionId: string, actionPayload?: T): void {\n  logger_.logMethodArgs?.('dispatchAction', {actionId, actionPayload});\n  internalSignal_.dispatch({actionId, actionPayload});\n}\n\n// ─── Extension API ────────────────────────────────────────────────────────────\n\n/**\n * Registers a custom modifier that can be used in `on-action` attribute syntax.\n *\n * A modifier is a dot-chained token placed after the event type\n * (e.g. `click.mymod->action-id`). Its handler runs before the payload is\n * resolved and the action is dispatched. Returning `false` cancels the dispatch.\n *\n * Built-in modifiers (`prevent`, `stop`, `validate`, `once`, `passive`) are\n * always available. This function lets you add domain-specific ones.\n *\n * Registering the same name twice logs an accident and overwrites the previous\n * handler — avoid duplicate registrations in production code.\n *\n * @param name    - The modifier token (lowercase, no dots or arrows).\n * @param handler - The `ModifierHandler` function bound to the directive instance.\n *\n * @example — a `confirm` modifier that shows a browser dialog\n * ```ts\n * import {registerModifier} from '@alwatr/action';\n *\n * registerModifier('confirm', function () {\n *   return window.confirm('Are you sure?');\n * });\n * ```\n * ```html\n * <button on-action=\"click.confirm->delete-item:42\">Delete</button>\n * ```\n */\nexport function registerModifier(name: string, handler: ModifierHandler): void {\n  logger_.logMethodArgs?.('registerModifier', {name});\n  if (modifierRegistry.has(name)) {\n    logger_.accident('registerModifier', 'modifier_already_registered', {name});\n  }\n  modifierRegistry.set(name, handler);\n}\n\n/**\n * Registers a custom payload resolver that can be used in `on-action` attribute syntax.\n *\n * A payload resolver is a colon-suffixed token in the attribute value\n * (e.g. `click->action-id:$mytoken`). Its function is called at dispatch time\n * with the directive instance as `this` and the DOM event as the argument.\n * The return value becomes the `actionPayload` passed to `onAction` subscribers.\n *\n * Built-in resolvers (`$value`, `$formdata`) are always available. This function\n * lets you add domain-specific ones.\n *\n * Registering the same name twice logs an accident and overwrites the previous\n * resolver — avoid duplicate registrations in production code.\n *\n * @param name     - The resolver token (should start with `$` by convention).\n * @param resolver - The `PayloadResolver` function bound to the directive instance.\n *\n * @example — a `$checked` resolver for checkbox state\n * ```ts\n * import {registerPayloadResolver} from '@alwatr/action';\n *\n * registerPayloadResolver('$checked', function () {\n *   return (this.element_ as HTMLInputElement).checked;\n * });\n * ```\n * ```html\n * <input type=\"checkbox\" on-action=\"change->toggle-feature:$checked\" />\n * ```\n *\n * @example — a `$dataset-id` resolver for data attributes\n * ```ts\n * registerPayloadResolver('$dataset-id', function () {\n *   return (this.element_ as HTMLElement).dataset.id ?? null;\n * });\n * ```\n * ```html\n * <li on-action=\"click->select-item:$dataset-id\" data-id=\"42\">Item</li>\n * ```\n */\nexport function registerPayloadResolver(name: string, resolver: PayloadResolver): void {\n  logger_.logMethodArgs?.('registerPayloadResolver', {name});\n  if (payloadRegistry.has(name)) {\n    logger_.accident('registerPayloadResolver', 'payload_resolver_already_registered', {name});\n  }\n  payloadRegistry.set(name, resolver);\n}\n",
+    "import {lazyDirective, Directive} from '@alwatr/directive';\nimport {modifierRegistry, payloadRegistry} from './registry.js';\nimport {dispatchAction} from './method.js';\n\n// ─── Attribute Syntax Parser ──────────────────────────────────────────────────\n\n/**\n * Regex that parses the `on-action` attribute value into its three segments.\n *\n * Full syntax: `eventType[.modifier…]->actionId[:payload]`\n *\n * | Capture group | Matches                                     | Example              |\n * | ------------- | ------------------------------------------- | -------------------- |\n * | 1             | Event type + optional dot-chained modifiers | `click.prevent.once` |\n * | 2             | Action identifier                           | `open-drawer`        |\n * | 3             | Optional payload token or literal           | `main` / `$value`    |\n *\n * @example\n * ```\n * 'click.prevent.once->open-drawer:main' → ['click.prevent.once', 'open-drawer', 'main']\n * 'input->search-query:$value'           → ['input',              'search-query', '$value']\n * 'submit.prevent->submit-form'          → ['submit.prevent',     'submit-form',  undefined]\n * ```\n */\nconst syntaxRegex = /^([a-z0-9.-]+)->([a-z0-9-]+)(?::(.+))?$/;\n\n// ─── Directive Class ──────────────────────────────────────────────────────────\n\n/**\n * Directive that bridges a DOM event to a typed action signal.\n *\n * Activated automatically by the `on-action` HTML attribute when\n * `registerActionDirective()` has been called before `bootstrapDirectives()`.\n * You rarely need to reference this class directly.\n *\n * **Attribute syntax**\n * ```\n * on-action=\"eventType[.modifier…]->actionId[:payload]\"\n * ```\n *\n * - `eventType` — any standard DOM event name (e.g. `click`, `input`, `submit`).\n * - `modifier` — dot-chained tokens processed before dispatch\n *   (`prevent`, `stop`, `validate`, `once`, `passive`, or custom).\n * - `actionId` — the identifier passed to `onAction` subscribers.\n * - `payload` — an optional literal string or a `$`-prefixed resolver token\n *   (e.g. `$value`, `$formdata`, or custom).\n *\n * @example\n * ```html\n * <!-- Dispatches 'open-drawer' with payload 'settings' on click -->\n * <button on-action=\"click->open-drawer:settings\">Settings</button>\n *\n * <!-- Dispatches 'search-query' with the live input value on every keystroke -->\n * <input on-action=\"input->search-query:$value\" />\n *\n * <!-- Prevents default, validates, then dispatches 'submit-form' with all field values -->\n * <form on-action=\"submit.prevent.validate->submit-form:$formdata\" novalidate>…</form>\n * ```\n */\nexport class ActionDirective extends Directive {\n  /**\n   * Parsed and validated representation of the `on-action` attribute value.\n   *\n   * Set during `init_()` after the attribute is successfully parsed against\n   * `syntaxRegex`. Remains `undefined` when the attribute value is invalid,\n   * which prevents `dispatch_` from running.\n   */\n  protected actionContext_?: {\n    /** The DOM event type to listen for (e.g. `'click'`, `'input'`). */\n    eventType: string;\n    /** Set of active modifier names (e.g. `{'prevent', 'once'}`). */\n    modifiers: ReadonlySet<string>;\n    /** The action identifier dispatched to `onAction` subscribers. */\n    actionId: string;\n    /** Raw payload token from the attribute (literal string or `$`-resolver key). */\n    payload?: string;\n  };\n\n  /**\n   * Parses the `on-action` attribute, validates modifiers, and attaches the\n   * DOM event listener.\n   *\n   * Called once by `Directive` after one macrotask following element discovery.\n   * If the attribute value is malformed or references an unknown modifier,\n   * an accident is logged and the directive becomes a no-op.\n   */\n  protected override init_(): void {\n    this.logger_.logMethodArgs?.('init_', {attributeValue: this.attributeValue});\n\n    const match = this.attributeValue.trim().match(syntaxRegex);\n\n    if (!match) {\n      this.logger_.accident('init_', 'invalid_syntax', {attributeValue: this.attributeValue});\n      return;\n    }\n\n    const [eventType, ...modifierList] = match[1].split('.');\n    const actionId = match[2];\n    const payload = match[3] as string | undefined;\n\n    if (!eventType) {\n      this.logger_.accident('init_', 'invalid_syntax', {attributeValue: this.attributeValue});\n      return;\n    }\n\n    // Validate every modifier token against the registry (built-in native\n    // options 'once' and 'passive' are handled separately by the listener).\n    const modifiers = new Set<string>();\n    for (const modifier of modifierList) {\n      if (!modifierRegistry.has(modifier) && modifier !== 'once' && modifier !== 'passive') {\n        this.logger_.accident('init_', 'invalid_modifier', {attributeValue: this.attributeValue, modifier});\n        return;\n      }\n      modifiers.add(modifier);\n    }\n\n    // 'prevent' and 'passive' are mutually exclusive: a passive listener cannot\n    // call preventDefault(). Log an accident but continue — 'prevent' wins.\n    if (modifiers.has('prevent') && modifiers.has('passive')) {\n      this.logger_.accident('init_', 'conflicting_modifiers_prevent_passive', {attributeValue: this.attributeValue});\n    }\n\n    this.actionContext_ = {eventType, modifiers, actionId, payload};\n\n    // Bind once so the same function reference is used for both add and remove.\n    const listenerOptions: AddEventListenerOptions = {\n      once: modifiers.has('once'),\n      // 'passive' is only meaningful when 'prevent' is absent.\n      passive: modifiers.has('passive') && !modifiers.has('prevent'),\n    };\n\n    const boundDispatch = this.dispatch_.bind(this);\n    this.element_.addEventListener(eventType, boundDispatch, listenerOptions);\n    // Register cleanup so the listener is removed when the directive is destroyed\n    // (e.g. when the element is removed from the DOM via autoDestructDirectives).\n    this.addDestroyHook(() => {\n      this.element_.removeEventListener(eventType, boundDispatch, listenerOptions);\n    });\n  }\n\n  /**\n   * DOM event handler: runs modifiers, resolves the payload, and dispatches\n   * the action signal.\n   *\n   * Execution order:\n   * 1. Each modifier in `actionContext_.modifiers` is called in insertion order.\n   *    If any returns `false` the method returns early — no action is dispatched.\n   * 2. The raw payload token is looked up in `payloadRegistry`. If a resolver\n   *    is found it is called and its return value replaces the token.\n   * 3. `dispatchAction` is called with the resolved payload.\n   *\n   * @param event - The DOM event that triggered this handler.\n   */\n  protected dispatch_(event: Event): void {\n    this.logger_.logMethodArgs?.('dispatch_', {eventType: event.type, actionId: this.actionContext_?.actionId});\n\n    const context = this.actionContext_!;\n\n    // Step 1 — run modifiers; any returning false cancels the dispatch.\n    for (const mod of context.modifiers) {\n      const handler = modifierRegistry.get(mod);\n      if (handler && handler.call(this, event) === false) return;\n    }\n\n    // Step 2 — resolve dynamic payload tokens (e.g. '$value', '$formdata').\n    let payload: unknown = context.payload;\n    if (payload) {\n      const resolver = payloadRegistry.get(payload as string);\n      if (resolver) payload = resolver.call(this, event);\n    }\n\n    // Step 3 — dispatch the action to all onAction subscribers.\n    dispatchAction(context.actionId, payload);\n  }\n}\n\n// ─── Lazy Registration ────────────────────────────────────────────────────────\n\n/**\n * Registers `ActionDirective` under the `on-action` attribute name.\n *\n * This is a **lazy** registration: calling this function is the only way to\n * opt-in to `on-action` support. If it is never called, the entire directive\n * module (including `ActionDirective`) is tree-shaken from the bundle.\n *\n * Call it once, before `bootstrapDirectives()`, at your application entry point.\n *\n * @example\n * ```ts\n * import {registerActionDirective} from '@alwatr/action';\n * import {bootstrapDirectives} from '@alwatr/directive';\n *\n * registerActionDirective();\n * bootstrapDirectives();\n * ```\n */\nexport const registerActionDirective = lazyDirective('on-action', ActionDirective);\n",
+    "import {Directive, lazyDirective} from '@alwatr/directive';\nimport {dispatchAction} from './method.js';\n\n// ─── Directive Class ──────────────────────────────────────────────────────────\n\n/**\n * Directive that announces the current page identity as an action signal.\n *\n * Activated by the `page-id` HTML attribute. On bootstrap the directive reads\n * the attribute value as the page identifier, dispatches a `'page-ready'`\n * action with that value as the payload, and immediately self-destructs — no\n * persistent listener is registered.\n *\n * Typical placement is on the `<body>` or the top-level page container so that\n * any part of the application can react to route changes by subscribing to the\n * `'page-ready'` action via `onAction`.\n *\n * @example\n * ```html\n * <!-- Dispatches dispatchAction('page-ready', 'home') on bootstrap -->\n * <body page-id=\"home\">…</body>\n * ```\n */\nexport class PageIdDirective extends Directive {\n  /**\n   * Reads the `page-id` attribute value, dispatches `'page-ready'` with it as\n   * the payload, then destroys the directive.\n   *\n   * Logs an accident and returns early if the attribute value is empty.\n   */\n  protected override init_(): void {\n    const pageId = this.attributeValue.trim();\n    this.logger_.logMethodArgs?.('init_', {pageId});\n\n    if (!pageId) {\n      this.logger_.accident('init_', 'empty_page_id');\n      return;\n    }\n\n    dispatchAction('page-ready', pageId);\n    this.destroy();\n  }\n}\n\n// ─── Lazy Registration ────────────────────────────────────────────────────────\n\n/**\n * Registers `PageIdDirective` under the `page-id` attribute name.\n *\n * This is a **lazy** registration: calling this function is the only way to\n * opt-in to `page-id` support. If it is never called, the entire directive\n * module is tree-shaken from the bundle.\n *\n * Call it once, before `bootstrapDirectives()`, at your application entry point.\n *\n * @example\n * ```ts\n * import {registerPageIdDirective, onAction} from '@alwatr/action';\n * import {bootstrapDirectives} from '@alwatr/directive';\n *\n * registerPageIdDirective();\n * bootstrapDirectives();\n *\n * // React to every page change\n * onAction('page-ready', (pageId) => {\n *   console.log('navigated to:', pageId); // e.g. 'home', 'about', 'product-detail'\n * });\n * ```\n *\n * ```html\n * <body page-id=\"home\">…</body>\n * ```\n */\nexport const registerPageIdDirective = lazyDirective('page-id', PageIdDirective);\n"
+  ],
+  "mappings": ";AAAA,uBAAQ,uBACR,4BAAQ,uBA+BD,IAAM,EAAU,EAAa,eAAe,EActC,EAAkB,EAAgD,CAAC,KAAM,eAAe,CAAC,ECI/F,IAAM,EAAmB,IAAI,IAYvB,EAAkB,IAAI,IAYnC,EAAiB,IAAI,UAAW,CAAC,IAAU,CAEzC,OADA,EAAM,eAAe,EACd,GACR,EAUD,EAAiB,IAAI,OAAQ,CAAC,IAAU,CAEtC,OADA,EAAM,gBAAgB,EACf,GACR,EAcD,EAAiB,IAAI,WAAY,QAAS,EAAG,CAC3C,IAAM,EAAO,KAAK,oBAAoB,gBAAkB,KAAK,SAAW,KAAK,SAAS,QAAQ,MAAM,EACpG,GAAI,CAAC,EAEH,OADA,KAAK,QAAQ,SAAS,oBAAqB,gBAAiB,CAAC,QAAS,KAAK,QAAQ,CAAC,EAC7E,GAET,OAAO,EAAK,cAAc,EAC3B,EAYD,EAAgB,IAAI,SAAU,QAAS,EAAG,CACxC,MAAO,UAAW,KAAK,SAAY,KAAK,SAA8B,MAAQ,KAC/E,EAgBD,EAAgB,IAAI,YAAa,QAAS,EAAG,CAC3C,IAAM,EAAO,KAAK,oBAAoB,gBAAkB,KAAK,SAAW,KAAK,SAAS,QAAQ,MAAM,EACpG,OAAO,EAAO,OAAO,YAAY,IAAI,SAAS,CAAI,EAAE,QAAQ,CAAC,EAAI,KAClE,EChGM,SAAS,CAAoB,CAAC,EAAkB,EAAiD,CAEtG,OADA,EAAQ,gBAAgB,WAAY,CAAC,UAAQ,CAAC,EACvC,EAAgB,UAAU,CAAC,IAAW,CAC3C,GAAI,EAAO,WAAa,EACtB,EAAQ,gBAAgB,kBAAmB,CAAC,WAAU,QAAS,EAAO,aAAa,CAAC,EACpF,EAAQ,EAAO,aAAkB,EAEpC,EA8BI,SAAS,CAA0B,CAAC,EAAkB,EAAyB,CACpF,EAAQ,gBAAgB,iBAAkB,CAAC,WAAU,eAAa,CAAC,EACnE,EAAgB,SAAS,CAAC,WAAU,eAAa,CAAC,EAiC7C,SAAS,CAAgB,CAAC,EAAc,EAAgC,CAE7E,GADA,EAAQ,gBAAgB,mBAAoB,CAAC,MAAI,CAAC,EAC9C,EAAiB,IAAI,CAAI,EAC3B,EAAQ,SAAS,mBAAoB,8BAA+B,CAAC,MAAI,CAAC,EAE5E,EAAiB,IAAI,EAAM,CAAO,EA0C7B,SAAS,CAAuB,CAAC,EAAc,EAAiC,CAErF,GADA,EAAQ,gBAAgB,0BAA2B,CAAC,MAAI,CAAC,EACrD,EAAgB,IAAI,CAAI,EAC1B,EAAQ,SAAS,0BAA2B,sCAAuC,CAAC,MAAI,CAAC,EAE3F,EAAgB,IAAI,EAAM,CAAQ,EC5KpC,wBAAQ,eAAe,0BAwBvB,IAAM,EAAc,0CAmCb,MAAM,UAAwB,CAAU,CAQnC,eAmBS,KAAK,EAAS,CAC/B,KAAK,QAAQ,gBAAgB,QAAS,CAAC,eAAgB,KAAK,cAAc,CAAC,EAE3E,IAAM,EAAQ,KAAK,eAAe,KAAK,EAAE,MAAM,CAAW,EAE1D,GAAI,CAAC,EAAO,CACV,KAAK,QAAQ,SAAS,QAAS,iBAAkB,CAAC,eAAgB,KAAK,cAAc,CAAC,EACtF,OAGF,IAAO,KAAc,GAAgB,EAAM,GAAG,MAAM,GAAG,EACjD,EAAW,EAAM,GACjB,EAAU,EAAM,GAEtB,GAAI,CAAC,EAAW,CACd,KAAK,QAAQ,SAAS,QAAS,iBAAkB,CAAC,eAAgB,KAAK,cAAc,CAAC,EACtF,OAKF,IAAM,EAAY,IAAI,IACtB,QAAW,KAAY,EAAc,CACnC,GAAI,CAAC,EAAiB,IAAI,CAAQ,GAAK,IAAa,QAAU,IAAa,UAAW,CACpF,KAAK,QAAQ,SAAS,QAAS,mBAAoB,CAAC,eAAgB,KAAK,eAAgB,UAAQ,CAAC,EAClG,OAEF,EAAU,IAAI,CAAQ,EAKxB,GAAI,EAAU,IAAI,SAAS,GAAK,EAAU,IAAI,SAAS,EACrD,KAAK,QAAQ,SAAS,QAAS,wCAAyC,CAAC,eAAgB,KAAK,cAAc,CAAC,EAG/G,KAAK,eAAiB,CAAC,YAAW,YAAW,WAAU,SAAO,EAG9D,IAAM,EAA2C,CAC/C,KAAM,EAAU,IAAI,MAAM,EAE1B,QAAS,EAAU,IAAI,SAAS,GAAK,CAAC,EAAU,IAAI,SAAS,CAC/D,EAEM,EAAgB,KAAK,UAAU,KAAK,IAAI,EAC9C,KAAK,SAAS,iBAAiB,EAAW,EAAe,CAAe,EAGxE,KAAK,eAAe,IAAM,CACxB,KAAK,SAAS,oBAAoB,EAAW,EAAe,CAAe,EAC5E,EAgBO,SAAS,CAAC,EAAoB,CACtC,KAAK,QAAQ,gBAAgB,YAAa,CAAC,UAAW,EAAM,KAAM,SAAU,KAAK,gBAAgB,QAAQ,CAAC,EAE1G,IAAM,EAAU,KAAK,eAGrB,QAAW,KAAO,EAAQ,UAAW,CACnC,IAAM,EAAU,EAAiB,IAAI,CAAG,EACxC,GAAI,GAAW,EAAQ,KAAK,KAAM,CAAK,IAAM,GAAO,OAItD,IAAI,EAAmB,EAAQ,QAC/B,GAAI,EAAS,CACX,IAAM,EAAW,EAAgB,IAAI,CAAiB,EACtD,GAAI,EAAU,EAAU,EAAS,KAAK,KAAM,CAAK,EAInD,EAAe,EAAQ,SAAU,CAAO,EAE5C,CAsBO,IAAM,EAA0B,EAAc,YAAa,CAAe,ECpMjF,oBAAQ,mBAAW,0BAuBZ,MAAM,UAAwB,CAAU,CAO1B,KAAK,EAAS,CAC/B,IAAM,EAAS,KAAK,eAAe,KAAK,EAGxC,GAFA,KAAK,QAAQ,gBAAgB,QAAS,CAAC,QAAM,CAAC,EAE1C,CAAC,EAAQ,CACX,KAAK,QAAQ,SAAS,QAAS,eAAe,EAC9C,OAGF,EAAe,aAAc,CAAM,EACnC,KAAK,QAAQ,EAEjB,CA+BO,IAAM,EAA0B,EAAc,UAAW,CAAe",
+  "debugId": "78292B0ADE08B5FA64756E2164756E21",
+  "names": []
+}

package/dist/method.d.ts

@@ -0,0 +1,141 @@
+import type { SubscribeResult } from '@alwatr/signal';
+import { type ModifierHandler, type PayloadResolver } from './registry.js';
+export type { ModifierHandler, PayloadResolver };
+/**
+ * Subscribes to a named action dispatched anywhere in the application.
+ *
+ * The handler is invoked every time `dispatchAction(actionId, payload)` is
+ * called — whether from an `on-action` directive or from code — and the
+ * `actionId` matches. Multiple subscribers for the same `actionId` are all
+ * notified in subscription order.
+ *
+ * The generic parameter `T` narrows the type of the received payload.
+ * Defaults to `string`, which covers the common case of attribute-driven
+ * literal payloads.
+ *
+ * @param actionId - The action identifier to listen for (e.g. `'open-drawer'`).
+ * @param handler  - Callback invoked with the resolved payload each time the
+ *                   action is dispatched. `payload` is `undefined` when the
+ *                   action was dispatched without a value.
+ * @returns A `SubscribeResult` with an `unsubscribe()` method for cleanup.
+ *
+ * @example — basic string payload
+ * ```ts
+ * import {onAction} from '@alwatr/action';
+ *
+ * const sub = onAction('open-drawer', (panel) => {
+ *   openDrawer(panel); // panel === 'settings'
+ * });
+ *
+ * // Stop listening when the component is destroyed
+ * sub.unsubscribe();
+ * ```
+ *
+ * @example — typed object payload
+ * ```ts
+ * import {onAction} from '@alwatr/action';
+ *
+ * onAction<{productId: number; qty: number}>('add-to-cart', (item) => {
+ *   cartService.add(item!.productId, item!.qty);
+ * });
+ * ```
+ */
+export declare function onAction<T = string>(actionId: string, handler: (payload?: T) => void): SubscribeResult;
+/**
+ * Dispatches a named action to all `onAction` subscribers with a matching `actionId`.
+ *
+ * This is the programmatic counterpart to the `on-action` HTML attribute.
+ * Use it when you need to trigger an action from code rather than from a DOM
+ * event (e.g. after an async operation completes, or from a service layer).
+ *
+ * The generic parameter `T` types the payload. Omit it to default to `string`.
+ *
+ * @param actionId     - The action identifier (e.g. `'navigate'`).
+ * @param actionPayload - Optional value passed to every matching subscriber.
+ *
+ * @example — dispatch without payload
+ * ```ts
+ * import {dispatchAction} from '@alwatr/action';
+ *
+ * dispatchAction('logout');
+ * ```
+ *
+ * @example — dispatch with a typed payload
+ * ```ts
+ * import {dispatchAction} from '@alwatr/action';
+ *
+ * dispatchAction('navigate', '/dashboard');
+ * dispatchAction<{code: number}>('show-error', {code: 404});
+ * ```
+ */
+export declare function dispatchAction<T = string>(actionId: string, actionPayload?: T): void;
+/**
+ * Registers a custom modifier that can be used in `on-action` attribute syntax.
+ *
+ * A modifier is a dot-chained token placed after the event type
+ * (e.g. `click.mymod->action-id`). Its handler runs before the payload is
+ * resolved and the action is dispatched. Returning `false` cancels the dispatch.
+ *
+ * Built-in modifiers (`prevent`, `stop`, `validate`, `once`, `passive`) are
+ * always available. This function lets you add domain-specific ones.
+ *
+ * Registering the same name twice logs an accident and overwrites the previous
+ * handler — avoid duplicate registrations in production code.
+ *
+ * @param name    - The modifier token (lowercase, no dots or arrows).
+ * @param handler - The `ModifierHandler` function bound to the directive instance.
+ *
+ * @example — a `confirm` modifier that shows a browser dialog
+ * ```ts
+ * import {registerModifier} from '@alwatr/action';
+ *
+ * registerModifier('confirm', function () {
+ *   return window.confirm('Are you sure?');
+ * });
+ * ```
+ * ```html
+ * <button on-action="click.confirm->delete-item:42">Delete</button>
+ * ```
+ */
+export declare function registerModifier(name: string, handler: ModifierHandler): void;
+/**
+ * Registers a custom payload resolver that can be used in `on-action` attribute syntax.
+ *
+ * A payload resolver is a colon-suffixed token in the attribute value
+ * (e.g. `click->action-id:$mytoken`). Its function is called at dispatch time
+ * with the directive instance as `this` and the DOM event as the argument.
+ * The return value becomes the `actionPayload` passed to `onAction` subscribers.
+ *
+ * Built-in resolvers (`$value`, `$formdata`) are always available. This function
+ * lets you add domain-specific ones.
+ *
+ * Registering the same name twice logs an accident and overwrites the previous
+ * resolver — avoid duplicate registrations in production code.
+ *
+ * @param name     - The resolver token (should start with `$` by convention).
+ * @param resolver - The `PayloadResolver` function bound to the directive instance.
+ *
+ * @example — a `$checked` resolver for checkbox state
+ * ```ts
+ * import {registerPayloadResolver} from '@alwatr/action';
+ *
+ * registerPayloadResolver('$checked', function () {
+ *   return (this.element_ as HTMLInputElement).checked;
+ * });
+ * ```
+ * ```html
+ * <input type="checkbox" on-action="change->toggle-feature:$checked" />
+ * ```
+ *
+ * @example — a `$dataset-id` resolver for data attributes
+ * ```ts
+ * registerPayloadResolver('$dataset-id', function () {
+ *   return (this.element_ as HTMLElement).dataset.id ?? null;
+ * });
+ * ```
+ * ```html
+ * <li on-action="click->select-item:$dataset-id" data-id="42">Item</li>
+ * ```
+ */
+export declare function registerPayloadResolver(name: string, resolver: PayloadResolver): void;
+//# sourceMappingURL=method.d.ts.map

package/dist/method.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"method.d.ts","sourceRoot":"","sources":["../src/method.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAoC,KAAK,eAAe,EAAE,KAAK,eAAe,EAAC,MAAM,eAAe,CAAC;AAG5G,YAAY,EAAC,eAAe,EAAE,eAAe,EAAC,CAAC;AAI/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,QAAQ,CAAC,CAAC,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,eAAe,CAQtG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,CAAC,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,CAAC,GAAG,IAAI,CAGpF;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAM7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAMrF"}

package/dist/page-id.d.ts

@@ -0,0 +1,57 @@
+import { Directive } from '@alwatr/directive';
+/**
+ * Directive that announces the current page identity as an action signal.
+ *
+ * Activated by the `page-id` HTML attribute. On bootstrap the directive reads
+ * the attribute value as the page identifier, dispatches a `'page-ready'`
+ * action with that value as the payload, and immediately self-destructs — no
+ * persistent listener is registered.
+ *
+ * Typical placement is on the `<body>` or the top-level page container so that
+ * any part of the application can react to route changes by subscribing to the
+ * `'page-ready'` action via `onAction`.
+ *
+ * @example
+ * ```html
+ * <!-- Dispatches dispatchAction('page-ready', 'home') on bootstrap -->
+ * <body page-id="home">…</body>
+ * ```
+ */
+export declare class PageIdDirective extends Directive {
+    /**
+     * Reads the `page-id` attribute value, dispatches `'page-ready'` with it as
+     * the payload, then destroys the directive.
+     *
+     * Logs an accident and returns early if the attribute value is empty.
+     */
+    protected init_(): void;
+}
+/**
+ * Registers `PageIdDirective` under the `page-id` attribute name.
+ *
+ * This is a **lazy** registration: calling this function is the only way to
+ * opt-in to `page-id` support. If it is never called, the entire directive
+ * module is tree-shaken from the bundle.
+ *
+ * Call it once, before `bootstrapDirectives()`, at your application entry point.
+ *
+ * @example
+ * ```ts
+ * import {registerPageIdDirective, onAction} from '@alwatr/action';
+ * import {bootstrapDirectives} from '@alwatr/directive';
+ *
+ * registerPageIdDirective();
+ * bootstrapDirectives();
+ *
+ * // React to every page change
+ * onAction('page-ready', (pageId) => {
+ *   console.log('navigated to:', pageId); // e.g. 'home', 'about', 'product-detail'
+ * });
+ * ```
+ *
+ * ```html
+ * <body page-id="home">…</body>
+ * ```
+ */
+export declare const registerPageIdDirective: () => void;
+//# sourceMappingURL=page-id.d.ts.map

package/dist/page-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-id.d.ts","sourceRoot":"","sources":["../src/page-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAgB,MAAM,mBAAmB,CAAC;AAK3D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,eAAgB,SAAQ,SAAS;IAC5C;;;;;OAKG;cACgB,KAAK,IAAI,IAAI;CAYjC;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,uBAAuB,YAA4C,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,56 @@
+import type { ActionDirective } from './directive.js';
+/**
+ * A modifier handler attached to an `on-action` directive.
+ *
+ * Called with the directive instance as `this` and the triggering DOM `event`.
+ * Return `true` to allow the action to proceed, or `false` to cancel it.
+ * Returning `false` is the only way a modifier can veto a dispatch.
+ *
+ * @example
+ * ```ts
+ * // A modifier that only allows the action when the element is not disabled
+ * const notDisabledHandler: ModifierHandler = function () {
+ *   return !(this.element_ as HTMLButtonElement).disabled;
+ * };
+ * ```
+ */
+export type ModifierHandler = (this: ActionDirective, event: Event) => boolean;
+/**
+ * A payload resolver attached to an `on-action` directive.
+ *
+ * Called with the directive instance as `this` and the triggering DOM `event`
+ * at dispatch time. The return value becomes the `actionPayload` of the
+ * dispatched action. Use this to compute dynamic payloads from the DOM state.
+ *
+ * @example
+ * ```ts
+ * // A resolver that returns the element's dataset id
+ * const dataIdResolver: PayloadResolver = function () {
+ *   return (this.element_ as HTMLElement).dataset.id ?? null;
+ * };
+ * ```
+ */
+export type PayloadResolver = (this: ActionDirective, event: Event) => unknown;
+/**
+ * Registry of all named modifier handlers.
+ *
+ * Keys are modifier names used in the `on-action` attribute syntax
+ * (e.g. `click.prevent->action-id`). Values are `ModifierHandler` functions.
+ * Populated at module load with built-in modifiers; extended at runtime via
+ * `registerModifier`.
+ *
+ * @internal
+ */
+export declare const modifierRegistry: Map<string, ModifierHandler>;
+/**
+ * Registry of all named payload resolvers.
+ *
+ * Keys are resolver tokens used in the `on-action` attribute syntax
+ * (e.g. `click->action-id:$value`). Values are `PayloadResolver` functions.
+ * Populated at module load with built-in resolvers; extended at runtime via
+ * `registerPayloadResolver`.
+ *
+ * @internal
+ */
+export declare const payloadRegistry: Map<string, PayloadResolver>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAIpD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;AAE/E;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;AAI/E;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,8BAAqC,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,8BAAqC,CAAC"}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@alwatr/action",
+  "version": "9.11.2",
+  "description": "Declarative DOM action-dispatch — bridge HTML attributes to typed signal handlers.",
+  "license": "MPL-2.0",
+  "author": "S. Ali Mihandoost <ali.mihandoost@gmail.com> (https://ali.mihandoost.com)",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Alwatr/alwatr",
+    "directory": "pkg/nanolib/action"
+  },
+  "homepage": "https://github.com/Alwatr/alwatr/tree/next/pkg/nanolib/action#readme",
+  "bugs": "https://github.com/Alwatr/alwatr/issues",
+  "exports": {
+    ".": {
+      "types": "./dist/main.d.ts",
+      "import": "./dist/main.js",
+      "default": "./dist/main.js"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@alwatr/directive": "9.11.2",
+    "@alwatr/logger": "9.11.2",
+    "@alwatr/signal": "9.11.2"
+  },
+  "devDependencies": {
+    "@alwatr/nano-build": "9.10.1",
+    "@alwatr/standard": "9.11.2",
+    "@alwatr/type-helper": "9.11.2",
+    "@happy-dom/global-registrator": "^20.9.0",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "b": "bun run build",
+    "build": "bun run build:ts && bun run build:es",
+    "build:es": "nano-build --preset=module-web src/main.ts",
+    "build:ts": "tsc --build",
+    "cl": "bun run clean",
+    "clean": "rm -rfv dist *.tsbuildinfo",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "lint": "eslint src/ --ext .ts",
+    "t": "bun run test",
+    "test": "ALWATR_DEBUG=0 bun test",
+    "w": "bun run watch",
+    "watch": "bun run watch:ts & bun run watch:es",
+    "watch:es": "bun run build:es --watch",
+    "watch:ts": "bun run build:ts --watch --preserveWatchOutput"
+  },
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "action",
+    "alwatr",
+    "browser-api",
+    "declarative-ui",
+    "decorator",
+    "directive",
+    "dom",
+    "esm",
+    "event",
+    "frontend",
+    "javascript",
+    "lightweight",
+    "module",
+    "nanolib",
+    "signal",
+    "spa",
+    "typescript",
+    "ui-library",
+    "unidirectional-data-flow",
+    "vanilla-js",
+    "web-development"
+  ],
+  "gitHead": "ad72dc5b615ab443b1f7e2616ec647574bb04cf5"
+}