@alwatr/action 9.18.1 → 9.19.0

package/dist/main.js

@@ -1,5 +1,5 @@
-/* 📦 @alwatr/action v9.18.1 */
+/* 📦 @alwatr/action v9.19.0 */
 import{createLogger as Z}from"@alwatr/logger";import{createChannelSignal as H}from"@alwatr/signal";var w=Z("alwatr-action"),J=H({name:"alwatr-action"});var P=new Map,I=new Map;P.set("prevent",(A)=>{return A.preventDefault(),!0});P.set("validate",(A,x)=>{let F=x instanceof HTMLFormElement?x:x.closest("form");if(!F)return!1;return F.checkValidity()});I.set("$value",(A,x)=>{return"value"in x?x.value:null});I.set("$formdata",(A,x)=>{let F=x instanceof HTMLFormElement?x:x.closest("form");return F?Object.fromEntries(new FormData(F)):null});I.set("$checked",(A,x)=>{return"checked"in x?x.checked:null});var M=/^([a-z0-9_:-]+)(?::([^;]+))?(?:;\s*([a-z0-9_,-]+))?$/,Q=new Map;function U(A){w.logMethodArgs?.("parseDescriptor__",{attributeValue:A});let x=Q.get(A);if(x!==void 0)return x;let F=A.match(M);if(!F)return w.accident("parseDescriptor__","invalid_syntax",{attributeValue:A}),Q.set(A,null),null;let K=F[1],D=F[2],z=F[3],N={modifiers:z?new Set(z.split(",").filter(Boolean)):new Set,actionId:K,payload:D};return Q.set(A,N),N}function Y(A){let x=A.type;w.logMethodArgs?.("handleDelegatedEvent__",{eventType:x});let F=A.target;if(!F)return;let K=`on-${x}`,D=F.closest?.(`[${K}]`);if(!D)return;let z=D.getAttribute?.(K)?.trim();if(!z){w.accident("handleDelegatedEvent__","empty_attribute",{eventType:x,actionElement:D});return}if(!(D instanceof HTMLElement)){w.accident("handleDelegatedEvent__","target_not_html_element",{eventType:x,actionElement:D});return}let q=U(z);if(!q)return;if(w.logMethodArgs?.("handleDelegatedEvent__.action",{eventType:x,descriptor:q}),q.modifiers.has("once"))D.removeAttribute(K);let N=D.closest("[action-context]")?.getAttribute("action-context")??void 0,O={type:q.actionId,context:N,payload:q.payload};for(let G of q.modifiers){if(G==="once")continue;let X=P.get(G);if(!X){w.accident("handleDelegatedEvent__","unknown_modifier",{eventType:x,modifier:G,attributeValue:z,descriptor:q});return}if(X(A,D,O)===!1)return}if(q.payload){let G=I.get(q.payload);if(G)O.payload=G(A,D)}else O.payload=void 0;J.dispatch(O.type,O)}var W=new Set,B=["click","submit","input","change"];function R(A=B){w.logMethodArgs?.("setupActionDelegation",{eventTypes:A});for(let x of A){if(W.has(x))continue;W.add(x),document.body.addEventListener(x,Y,{capture:!0})}}function V(){w.logMethod?.("teardownActionDelegation");for(let A of W)document.body.removeEventListener(A,Y,{capture:!0});W.clear(),Q.clear()}function T(A,x){return w.logMethodArgs?.("onAction",{type:A}),J.on(A,x)}function p(A){w.logMethodArgs?.("dispatchAction",A),J.dispatch(A.type,A)}function u(A,x){if(w.logMethodArgs?.("registerModifier",{name:A}),P.has(A))w.accident("registerModifier","modifier_already_registered",{name:A});P.set(A,x)}function c(A,x){if(w.logMethodArgs?.("registerPayloadResolver",{name:A}),I.has(A))w.accident("registerPayloadResolver","payload_resolver_already_registered",{name:A});I.set(A,x)}export{V as teardownActionDelegation,R as setupActionDelegation,c as registerPayloadResolver,u as registerModifier,T as onAction,p as dispatchAction,B as DEFAULT_DELEGATED_EVENTS};
 
-//# debugId=727670A7DA05103E64756E2164756E21
+//# debugId=892FE9BF82CC1DCC64756E2164756E21
 //# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -8,6 +8,6 @@
     "import type {Awaitable} from '@alwatr/type-helper';\nimport type {SubscribeResult} from '@alwatr/signal';\n\nimport {internalChannel_, logger_} from './lib_.js';\nimport {modifierRegistry, payloadRegistry} from './registry_.js';\nimport type {Action, ActionRecord, DispatchParam, ModifierHandler, PayloadResolver} from './type.js';\n\n// ─── Core Action API ──────────────────────────────────────────────────────────\n\n/**\n * Subscribes to a named action dispatched anywhere in the application.\n *\n * `type` must be a key of `ActionRecord`. The handler receives the full\n * `Action<K>` object — giving access to `payload`, `context`, and `meta`\n * in one place. No manual generic annotation is needed; the compiler infers\n * the correct `payload` type from `ActionRecord`:\n *\n * ```ts\n * // ActionRecord declares: 'add_to_cart': {productId: number; qty: number}\n * onAction('add_to_cart', (action) => {\n *   cartService.add(action.payload.productId, action.payload.qty); // fully typed\n *   console.log(action.context); // e.g. 'product-list' (from DOM) or undefined\n * });\n * ```\n *\n * Passing an action name not declared in `ActionRecord` is a **compile error**.\n * Register new actions by extending `ActionRecord` via declaration merging:\n *\n * ```ts\n * // src/action-record.ts\n * declare module '@alwatr/action' {\n *   interface ActionRecord {\n *     'open_drawer': string;\n *   }\n * }\n * ```\n *\n * Internally delegates to `ChannelSignal.on()` for **O(1) routing** — dispatching\n * action `'A'` never invokes handlers registered for action `'B'`.\n *\n * @param type    - A key of `ActionRecord`.\n * @param handler - Callback invoked with the full `Action<K>` on each dispatch.\n * @returns A `SubscribeResult` with an `unsubscribe()` method for cleanup.\n *\n * @example\n * ```ts\n * import {onAction} from '@alwatr/action';\n *\n * const sub = onAction('page_ready', (action) => {\n *   router.setPage(action.payload); // payload: string — inferred from ActionRecord\n * });\n *\n * sub.unsubscribe(); // stop listening when no longer needed\n * ```\n */\nexport function onAction<K extends keyof ActionRecord>(\n  type: K,\n  handler: (action: Action<K>) => Awaitable<void>,\n): SubscribeResult {\n  logger_.logMethodArgs?.('onAction', {type});\n  // The internal channel stores Action<any>; we cast to Action<K> here because\n  // the channel key guarantees the type matches — only Action<K> objects are\n  // ever dispatched under key K.\n  return internalChannel_.on(type, handler as (action: Action) => Awaitable<void>);\n}\n\n/**\n * Dispatches an action to all `onAction` subscribers with a matching `type`.\n *\n * Accepts a full `Action<K>` object. The `payload` field is automatically\n * typed from `ActionRecord[K]` — passing the wrong shape is a **compile error**:\n *\n * ```ts\n * // ActionRecord declares: 'add_to_cart': {productId: number; qty: number}\n * dispatchAction({type: 'add_to_cart', payload: {productId: 42, qty: 1}}); // ✅\n * dispatchAction({type: 'add_to_cart', payload: 'wrong'});                  // ❌ compile error\n * dispatchAction({type: 'unknown_action', payload: 'x'});                   // ❌ compile error\n * ```\n *\n * The `context` and `meta` fields are optional. When dispatching from code\n * (not from the DOM), omit `context` — it is only meaningful for DOM-originated\n * actions where an `[action-context]` ancestor exists.\n *\n * Use `dispatchAction` when triggering an action from code — e.g. after an\n * async operation, from a service layer, or in tests. For DOM-driven actions,\n * use the `on-<eventType>` HTML attribute with `setupActionDelegation`.\n *\n * @param action - A full `Action<K>` object with at minimum `type` and `payload`.\n *\n * @example — with payload\n * ```ts\n * import {dispatchAction} from '@alwatr/action';\n *\n * dispatchAction({type: 'navigate', payload: '/dashboard'});\n * dispatchAction({type: 'add_to_cart', payload: {productId: 42, qty: 1}});\n * ```\n *\n * @example — void payload (payload field is optional and can be omitted entirely)\n * ```ts\n * dispatchAction({type: 'logout'});\n * // or explicitly:\n * dispatchAction({type: 'logout', payload: undefined});\n * ```\n *\n * @example — with context and meta\n * ```ts\n * dispatchAction({\n *   type: 'slider_change',\n *   payload: 75,\n *   context: 'volume_slider',\n *   meta: {traceId: 'abc-123'},\n * });\n * ```\n */\nexport function dispatchAction<K extends keyof ActionRecord>(action: DispatchParam<K>): void {\n  logger_.logMethodArgs?.('dispatchAction', action);\n  internalChannel_.dispatch(action.type, action as Action<K>);\n}\n\n// ─── Extension API ────────────────────────────────────────────────────────────\n\n/**\n * Registers a custom modifier that can be used in `on-<eventType>` attribute syntax.\n *\n * A modifier is a comma-separated token placed after the `;` separator\n * (e.g. `on-click=\"action-id; mymod\"`). Its handler runs before the payload is\n * resolved and the action is dispatched. Returning `false` cancels the dispatch.\n *\n * The handler also receives the **mutable** `action` object being built, so it\n * can attach data to `action.meta` before the action reaches subscribers.\n *\n * Built-in modifiers (`prevent`, `validate`, `once`) are always available.\n * 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 special characters).\n * @param handler - A `ModifierHandler` receiving `(event, element, action)`.\n *\n * @example — a `confirm` modifier that shows a browser dialog\n * ```ts\n * import {registerModifier} from '@alwatr/action';\n *\n * registerModifier('confirm', () => window.confirm('Are you sure?'));\n * ```\n * ```html\n * <button on-click=\"delete_item:42; confirm\">Delete</button>\n * ```\n *\n * @example — a `trace` modifier that stamps a trace ID into meta\n * ```ts\n * registerModifier('trace', (_event, _element, action) => {\n *   action.meta ??= {};\n *   action.meta['traceId'] = crypto.randomUUID();\n *   return true;\n * });\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-<eventType>` attribute syntax.\n *\n * A payload resolver is a colon-prefixed token in the attribute value\n * (e.g. `on-click=\"action-id:$mytoken\"`). Its function is called at dispatch time\n * with the DOM event and the element. The return value becomes the `payload`\n * field of the `Action` object passed to `onAction` subscribers.\n *\n * Built-in resolvers (`$value`, `$formdata`, `$checked`) are always available.\n * This function 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 - A `PayloadResolver` receiving `(event, element)`.\n *\n * @example — a `$data-id` resolver that reads a data attribute\n * ```ts\n * import {registerPayloadResolver} from '@alwatr/action';\n *\n * registerPayloadResolver('$data-id', (_event, element) => {\n *   return (element as HTMLElement).dataset.id ?? null;\n * });\n * ```\n * ```html\n * <button on-click=\"select_item:$data-id\" data-id=\"42\">Select</button>\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"
   ],
   "mappings": ";AAAA,uBAAQ,uBACR,8BAAQ,uBASD,IAAM,EAAU,EAAa,eAAe,EAgBtC,EAAmB,EAA4C,CAAC,KAAM,eAAe,CAAC,ECd5F,IAAM,EAAmB,IAAI,IAYvB,EAAkB,IAAI,IAYnC,EAAiB,IAAI,UAAW,CAAC,IAAU,CAEzC,OADA,EAAM,eAAe,EACd,GACR,EAcD,EAAiB,IAAI,WAAY,CAAC,EAAQ,IAAY,CACpD,IAAM,EAAO,aAAmB,gBAAkB,EAAU,EAAQ,QAAQ,MAAM,EAClF,GAAI,CAAC,EAAM,MAAO,GAClB,OAAO,EAAK,cAAc,EAC3B,EAYD,EAAgB,IAAI,SAAU,CAAC,EAAQ,IAAY,CACjD,MAAO,UAAW,EAAW,EAA6B,MAAQ,KACnE,EAgBD,EAAgB,IAAI,YAAa,CAAC,EAAQ,IAAY,CACpD,IAAM,EAAO,aAAmB,gBAAkB,EAAU,EAAQ,QAAQ,MAAM,EAClF,OAAO,EAAO,OAAO,YAAY,IAAI,SAAS,CAAI,CAAC,EAAI,KACxD,EAgBD,EAAgB,IAAI,WAAY,CAAC,EAAQ,IAAY,CACnD,MAAO,YAAa,EAAW,EAA6B,QAAU,KACvE,EC/BD,IAAM,EAAc,uDAoCd,EAAoB,IAAI,IAU9B,SAAS,CAAiB,CAAC,EAAiD,CAC1E,EAAQ,gBAAgB,oBAAqB,CAAC,gBAAc,CAAC,EAE7D,IAAM,EAAS,EAAkB,IAAI,CAAc,EAEnD,GAAI,IAAW,OAAW,OAAO,EAEjC,IAAM,EAAQ,EAAe,MAAM,CAAW,EAC9C,GAAI,CAAC,EAGH,OAFA,EAAQ,SAAS,oBAAqB,iBAAkB,CAAC,gBAAc,CAAC,EACxE,EAAkB,IAAI,EAAgB,IAAI,EACnC,KAGT,IAAM,EAAW,EAAM,GACjB,EAA8B,EAAM,GAEpC,EAAiB,EAAM,GAEvB,EAA+B,CAAC,UADP,EAAiB,IAAI,IAAI,EAAe,MAAM,GAAG,EAAE,OAAO,OAAO,CAAC,EAAI,IAAI,IACxD,WAAU,SAAO,EAGlE,OADA,EAAkB,IAAI,EAAgB,CAAU,EACzC,EAqBT,SAAS,CAAsB,CAAC,EAAoB,CAClD,IAAM,EAAY,EAAM,KACxB,EAAQ,gBAAgB,yBAA0B,CAAC,WAAS,CAAC,EAE7D,IAAM,EAAS,EAAM,OACrB,GAAI,CAAC,EAAQ,OAGb,IAAM,EAAe,MAAM,IAGrB,EAAgB,EAAO,UAAU,IAAI,IAAe,EAC1D,GAAI,CAAC,EAAe,OAEpB,IAAM,EAAiB,EAAc,eAAe,CAAY,GAAG,KAAK,EACxE,GAAI,CAAC,EAAgB,CACnB,EAAQ,SAAS,yBAA0B,kBAAmB,CAAC,YAAW,eAAa,CAAC,EACxF,OAGF,GAAI,EAAE,aAAyB,aAAc,CAC3C,EAAQ,SAAS,yBAA0B,0BAA2B,CAAC,YAAW,eAAa,CAAC,EAChG,OAGF,IAAM,EAAa,EAAkB,CAAc,EACnD,GAAI,CAAC,EAAY,OAMjB,GAJA,EAAQ,gBAAgB,gCAAiC,CAAC,YAAW,YAAU,CAAC,EAI5E,EAAW,UAAU,IAAI,MAAM,EACjC,EAAc,gBAAgB,CAAY,EAM5C,IAAM,EAAgB,EAAc,QAAQ,kBAAkB,GAAG,aAAa,gBAAgB,GAAK,OAK7F,EAAiB,CACrB,KAAM,EAAW,SACjB,QAAS,EAET,QAAS,EAAW,OACtB,EAGA,QAAW,KAAY,EAAW,UAAW,CAC3C,GAAI,IAAa,OAAQ,SACzB,IAAM,EAAU,EAAiB,IAAI,CAAQ,EAC7C,GAAI,CAAC,EAAS,CACZ,EAAQ,SAAS,yBAA0B,mBAAoB,CAAC,YAAW,WAAU,iBAAgB,YAAU,CAAC,EAChH,OAEF,GAAI,EAAQ,EAAO,EAAe,CAAM,IAAM,GAAO,OAMvD,GAAI,EAAW,QAAS,CACtB,IAAM,EAAW,EAAgB,IAAI,EAAW,OAAO,EACvD,GAAI,EAED,EAA8B,QAAU,EAAS,EAAO,CAAa,EAKxE,KAAC,EAA8B,QAAU,OAI3C,EAAiB,SAAS,EAAO,KAAM,CAAM,EAa/C,IAAM,EAAwB,IAAI,IAarB,EAA8C,CAAC,QAAS,SAAU,QAAS,QAAQ,EA8DzF,SAAS,CAAqB,CAAC,EAAgC,EAAgC,CACpG,EAAQ,gBAAgB,wBAAyB,CAAC,YAAU,CAAC,EAE7D,QAAW,KAAa,EAAY,CAClC,GAAI,EAAsB,IAAI,CAAS,EAAG,SAC1C,EAAsB,IAAI,CAAS,EAEnC,SAAS,KAAK,iBAAiB,EAAW,EAAwB,CAAC,QAAS,EAAI,CAAC,GAY9E,SAAS,CAAwB,EAAS,CAC/C,EAAQ,YAAY,0BAA0B,EAC9C,QAAW,KAAa,EACtB,SAAS,KAAK,oBAAoB,EAAW,EAAwB,CAAC,QAAS,EAAI,CAAC,EAEtF,EAAsB,MAAM,EAC5B,EAAkB,MAAM,EC9SnB,SAAS,CAAsC,CACpD,EACA,EACiB,CAKjB,OAJA,EAAQ,gBAAgB,WAAY,CAAC,MAAI,CAAC,EAInC,EAAiB,GAAG,EAAM,CAA8C,EAmD1E,SAAS,CAA4C,CAAC,EAAgC,CAC3F,EAAQ,gBAAgB,iBAAkB,CAAM,EAChD,EAAiB,SAAS,EAAO,KAAM,CAAmB,EA2CrD,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,EAgC7B,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",
-  "debugId": "727670A7DA05103E64756E2164756E21",
+  "debugId": "892FE9BF82CC1DCC64756E2164756E21",
   "names": []
 }

package/dist/type.d.ts

@@ -152,7 +152,7 @@ export type ModifierHandler = (event: Event, element: HTMLElement, action: Actio
  * @example — a resolver that returns the element's dataset id
  * ```ts
  * const dataIdResolver: PayloadResolver = (_event, element) => {
- *   return (element as HTMLElement).dataset.id ?? null;
+ *   return element.dataset.id ?? null;
  * };
  * ```
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwatr/action",
-  "version": "9.18.1",
+  "version": "9.19.0",
   "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)",
@@ -79,5 +79,5 @@
     "vanilla-js",
     "web-development"
   ],
-  "gitHead": "33191a8579a5f910b1c1da19f8d20ba88852a83c"
+  "gitHead": "20106a8e95925e2b6f895325afe1c7b7c263e2cc"
 }

package/src/type.ts

@@ -158,7 +158,7 @@ export type ModifierHandler = (event: Event, element: HTMLElement, action: Actio
  * @example — a resolver that returns the element's dataset id
  * ```ts
  * const dataIdResolver: PayloadResolver = (_event, element) => {
- *   return (element as HTMLElement).dataset.id ?? null;
+ *   return element.dataset.id ?? null;
  * };
  * ```
  */