@alwatr/action 9.16.0 → 9.17.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +249 -70
- package/dist/action.d.ts +93 -0
- package/dist/action.d.ts.map +1 -0
- package/dist/delegate.d.ts +28 -5
- package/dist/delegate.d.ts.map +1 -1
- package/dist/lib.d.ts +8 -6
- package/dist/lib.d.ts.map +1 -1
- package/dist/main.d.ts +30 -3
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +3 -3
- package/dist/main.js.map +6 -6
- package/dist/method.d.ts +62 -45
- package/dist/method.d.ts.map +1 -1
- package/dist/registry.d.ts +24 -12
- package/dist/registry.d.ts.map +1 -1
- package/package.json +2 -2
- package/src/action.ts +97 -0
- package/src/delegate.ts +70 -19
- package/src/lib.ts +9 -6
- package/src/main.ts +30 -3
- package/src/method.ts +72 -54
- package/src/registry.ts +31 -17
package/dist/main.d.ts
CHANGED
|
@@ -1,6 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* @alwatr/action — Declarative DOM action-dispatch for Unidirectional Data Flow.
|
|
3
3
|
*
|
|
4
|
+
* Implements the **Alwatr Flux Standard Action (AFSA)** pattern: every action
|
|
5
|
+
* flowing through the bus is a single, typed `Action<K>` object carrying
|
|
6
|
+
* `type`, `payload`, `context`, and optional `meta`. This replaces the previous
|
|
7
|
+
* two-argument `(id, payload)` API with a unified structure that is extensible
|
|
8
|
+
* without breaking existing call sites.
|
|
9
|
+
*
|
|
4
10
|
* ## Activating `on-<eventType>` attributes
|
|
5
11
|
*
|
|
6
12
|
* Call `setupActionDelegation()` once at bootstrap. A single capture-phase
|
|
@@ -11,7 +17,7 @@
|
|
|
11
17
|
* import {setupActionDelegation, onAction} from '@alwatr/action';
|
|
12
18
|
*
|
|
13
19
|
* setupActionDelegation();
|
|
14
|
-
* onAction('open_drawer', (
|
|
20
|
+
* onAction('open_drawer', (action) => openDrawer(action.payload));
|
|
15
21
|
* ```
|
|
16
22
|
*
|
|
17
23
|
* ## Attribute syntax
|
|
@@ -26,12 +32,31 @@
|
|
|
26
32
|
* <form on-submit="submit_form:$formdata; prevent,validate" novalidate>…</form>
|
|
27
33
|
* ```
|
|
28
34
|
*
|
|
35
|
+
* ## Context scoping
|
|
36
|
+
*
|
|
37
|
+
* Wrap elements in an `[action-context]` container to scope their actions.
|
|
38
|
+
* The delegation handler resolves the nearest ancestor and attaches its value
|
|
39
|
+
* to `action.context`:
|
|
40
|
+
*
|
|
41
|
+
* ```html
|
|
42
|
+
* <section action-context="product-list">
|
|
43
|
+
* <button on-click="add_to_cart:42">Add</button>
|
|
44
|
+
* </section>
|
|
45
|
+
* ```
|
|
46
|
+
*
|
|
47
|
+
* ```ts
|
|
48
|
+
* onAction('add_to_cart', (action) => {
|
|
49
|
+
* console.log(action.context); // 'product-list'
|
|
50
|
+
* console.log(action.payload); // '42'
|
|
51
|
+
* });
|
|
52
|
+
* ```
|
|
53
|
+
*
|
|
29
54
|
* ## Programmatic dispatch
|
|
30
55
|
*
|
|
31
56
|
* ```ts
|
|
32
57
|
* import {dispatchAction} from '@alwatr/action';
|
|
33
58
|
*
|
|
34
|
-
* dispatchAction('navigate', '/dashboard');
|
|
59
|
+
* dispatchAction({type: 'navigate', payload: '/dashboard'});
|
|
35
60
|
* ```
|
|
36
61
|
*
|
|
37
62
|
* ## Registering typed actions
|
|
@@ -51,7 +76,8 @@
|
|
|
51
76
|
*
|
|
52
77
|
* ## Public API
|
|
53
78
|
*
|
|
54
|
-
* - `
|
|
79
|
+
* - `Action` — the AFSA object interface (`type`, `payload`, `context`, `meta`)
|
|
80
|
+
* - `ActionRecord` — extend this interface to register typed actions
|
|
55
81
|
* - `setupActionDelegation` / `teardownActionDelegation` — global delegation lifecycle
|
|
56
82
|
* - `DEFAULT_DELEGATED_EVENTS` — default event types covered by delegation
|
|
57
83
|
* - `onAction` / `dispatchAction` — subscribe to and dispatch named actions
|
|
@@ -62,6 +88,7 @@
|
|
|
62
88
|
* For page-ready signals in SSG/SSR apps, use `@alwatr/page-ready` instead.
|
|
63
89
|
*/
|
|
64
90
|
export type { ActionRecord } from './action-record.js';
|
|
91
|
+
export type { Action } from './action.js';
|
|
65
92
|
export * from './method.js';
|
|
66
93
|
export * from './delegate.js';
|
|
67
94
|
//# sourceMappingURL=main.d.ts.map
|
package/dist/main.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,YAAY,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrD,YAAY,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AACxC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}
|
package/dist/main.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
/* 📦 @alwatr/action v9.
|
|
2
|
-
import{createLogger as
|
|
1
|
+
/* 📦 @alwatr/action v9.17.0 */
|
|
2
|
+
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});function k(A,x){return w.logMethodArgs?.("onAction",{type:A}),J.on(A,x)}function V(A){w.logMethodArgs?.("dispatchAction",A),J.dispatch(A.type,A)}function f(A,x){if(w.logMethodArgs?.("registerModifier",{name:A}),P.has(A))w.accident("registerModifier","modifier_already_registered",{name:A});P.set(A,x)}function E(A,x){if(w.logMethodArgs?.("registerPayloadResolver",{name:A}),I.has(A))w.accident("registerPayloadResolver","payload_resolver_already_registered",{name:A});I.set(A,x)}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 p(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 u(){w.logMethod?.("teardownActionDelegation");for(let A of W)document.body.removeEventListener(A,Y,{capture:!0});W.clear(),Q.clear()}export{u as teardownActionDelegation,p as setupActionDelegation,E as registerPayloadResolver,f as registerModifier,k as onAction,V as dispatchAction,B as DEFAULT_DELEGATED_EVENTS};
|
|
3
3
|
|
|
4
|
-
//# debugId=
|
|
4
|
+
//# debugId=F2B64ABE6411370464756E2164756E21
|
|
5
5
|
//# sourceMappingURL=main.js.map
|
package/dist/main.js.map
CHANGED
|
@@ -2,12 +2,12 @@
|
|
|
2
2
|
"version": 3,
|
|
3
3
|
"sources": ["../src/lib.ts", "../src/registry.ts", "../src/method.ts", "../src/delegate.ts"],
|
|
4
4
|
"sourcesContent": [
|
|
5
|
-
"import {createLogger} from '@alwatr/logger';\nimport {createChannelSignal} from '@alwatr/signal';\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 action channel — a `ChannelSignal`
|
|
6
|
-
"// ─── Type Definitions ────────────────────────────────────────────────────────\n\n/**\n * A modifier handler used in `on
|
|
7
|
-
"import type {Awaitable} from '@alwatr/type-helper';\nimport {
|
|
8
|
-
"/**\n * @file delegate.ts\n *\n * Global Event Delegation engine for `@alwatr/action`.\n *\n * ## Why delegation instead of per-element listeners?\n *\n * The classic directive approach attaches one `addEventListener` per element.\n * With 100 buttons on a page, that means 100 listener registrations at boot\n * time — O(N) initialization cost, O(N) memory for listener references, and\n * zero support for elements added after bootstrap.\n *\n * This module implements the global delegation pattern:\n * - A single listener per event type is attached to `document.body` with\n * `capture: true` (so it fires even for non-bubbling events).\n * - When an event fires, the handler walks up the DOM from `event.target`\n * using `closest()` to find the nearest element with an `on-<eventType>`\n * attribute (e.g. `on-click`, `on-submit`).\n * - Modifiers and payload resolvers run in the same pipeline as before.\n * - `dispatchAction` is called with the resolved payload.\n *\n * ## Complexity\n *\n * | Metric | Per-element listeners | Global delegation |\n * | --------------- | --------------------- | ----------------- |\n * | Boot time | O(N elements) | O(1) — 1 loop |\n * | Memory | O(N listeners) | O(1) — 1 handler |\n * | Dynamic content | Requires re-bootstrap | Works out-of-box |\n * | `once` modifier | Native option | Manual tracking |\n *\n * ## Trade-offs vs. the directive approach\n *\n * - `passive` is not supported as a per-element option (all delegated listeners\n * are non-passive so that `prevent` can call `preventDefault()`).\n * - `stop` stops further bubbling but the delegation handler has already\n * captured the event at `body` level — it does not prevent other delegation\n * handlers from running on the same element.\n * - `once` is emulated by removing the attribute after first fire.\n */\n\nimport {internalChannel_, logger_} from './lib.js';\nimport {modifierRegistry, payloadRegistry} from './registry.js';\n\n// ─── Syntax Parser ────────────────────────────────────────────────────────────\n\n/**\n * Parses the `on-<eventType>` attribute value into its segments.\n *\n * Syntax: `actionId[:payload][; modifier1,modifier2,…]`\n *\n * The event type is encoded in the **attribute name** itself (`on-click`,\n * `on-submit`, etc.) rather than inside the value. This makes the HTML more\n * readable and aligns with native event attribute conventions.\n *\n * | Capture group | Matches | Example |\n * | ------------- | -------------------------------------- | ---------------------- |\n * | 1 | Action identifier | `open_drawer` |\n * | 2 | Optional payload token or literal | `main_menu` / `$value` |\n * | 3 | Optional comma-separated modifier list | `prevent,validate` |\n *\n * @example\n * ```\n * 'close_drawer'\n * → actionId='close_drawer', payload=undefined, modifiers={}\n *\n * 'open_drawer:main_menu'\n * → actionId='open_drawer', payload='main_menu', modifiers={}\n *\n * 'my_submit_handler:$formdata; prevent,validate'\n * → actionId='my_submit_handler', payload='$formdata', modifiers={'prevent','validate'}\n * ```\n */\nconst syntaxRegex = /^([a-z0-9_-]+)(?::([^;]+))?(?:;\\s*([a-z0-9_,-]+))?$/;\n\n// ─── Parsed Action Descriptor ─────────────────────────────────────────────────\n\n/**\n * Parsed and cached representation of a single `on-<eventType>` attribute value.\n *\n * Does not store `eventType` — the caller always has it from `event.type`,\n * and the attribute name already encodes it (e.g. `on-click`), so storing it\n * here would be redundant. This also keeps the cache key simple: just the raw\n * attribute value string, with no composite key needed.\n */\ninterface ActionDescriptor {\n /** Set of active modifier names (e.g. `{'prevent', 'once'}`). */\n readonly modifiers: ReadonlySet<string>;\n /** The action identifier dispatched to `onAction` subscribers. */\n readonly actionId: string;\n /** Raw payload token from the attribute (literal string or $-resolver key). */\n readonly payload: string | undefined;\n}\n\n/**\n * Cache for parsed `on-<eventType>` attribute values.\n *\n * Attribute strings are typically repeated across many elements (e.g. every\n * \"add to cart\" button shares the same `on-click` value). Caching the parsed\n * descriptor avoids redundant regex work on every event.\n *\n * The cache key is the raw attribute value string. No composite key with\n * event type is needed because the attribute name already encodes the event\n * type — `on-click=\"open_drawer\"` and `on-submit=\"open_drawer\"` are two\n * separate attributes with the same value string, but they are read from\n * different attribute names and never collide in this cache.\n *\n * @internal\n */\nconst descriptorCache__ = new Map<string, ActionDescriptor | null>();\n\n/**\n * Parses an `on-<eventType>` attribute value into an `ActionDescriptor`.\n *\n * Returns `null` when the syntax is invalid. Results are cached by the raw\n * attribute value string so repeated calls for the same value are O(1).\n *\n * @internal\n */\nfunction parseDescriptor__(attributeValue: string): ActionDescriptor | null {\n logger_.logMethodArgs?.('parseDescriptor__', {attributeValue});\n\n const cached = descriptorCache__.get(attributeValue);\n // Explicit `undefined` check: `null` means \"already parsed and invalid\".\n if (cached !== undefined) return cached;\n\n const match = attributeValue.match(syntaxRegex);\n if (!match) {\n logger_.accident('parseDescriptor__', 'invalid_syntax', {attributeValue});\n descriptorCache__.set(attributeValue, null);\n return null;\n }\n\n const actionId = match[1];\n const payload: string | undefined = match[2];\n // match[3] is the raw modifier list string, e.g. \"prevent,validate\"\n const modifierString = match[3];\n const modifiers: Set<string> = modifierString ? new Set(modifierString.split(',').filter(Boolean)) : new Set();\n const descriptor: ActionDescriptor = {modifiers, actionId, payload};\n\n descriptorCache__.set(attributeValue, descriptor);\n return descriptor;\n}\n\n// ─── Core Delegation Handler ──────────────────────────────────────────────────\n\n/**\n * Central event handler attached to `document.body` for every delegated event type.\n *\n * Execution flow for each incoming event:\n * 1. Walk up from `event.target` to find the nearest element with an\n * `on-<eventType>` attribute (e.g. `on-click`, `on-submit`).\n * 2. Parse (or retrieve from cache) the `ActionDescriptor` for that attribute.\n * 3. Run each modifier in order; if any returns `false`, abort.\n * 4. Resolve the payload token (literal or $-resolver).\n * 5. Call `dispatchAction(actionId, payload)`.\n *\n * @internal\n */\nfunction handleDelegatedEvent__(event: Event): void {\n const eventType = event.type;\n logger_.logMethodArgs?.('handleDelegatedEvent__', {eventType});\n\n const target = event.target as Element | null;\n if (!target) return;\n\n // Attribute name encodes the event type: on-click, on-submit, etc.\n const actionAttrib = `on-${eventType}`;\n\n // Walk up the DOM to find the closest element with the matching on-<eventType> attribute.\n const actionElement = target.closest?.(`[${actionAttrib}]`);\n if (!actionElement) return;\n\n const attributeValue = actionElement.getAttribute?.(actionAttrib)?.trim();\n if (!attributeValue) {\n logger_.accident('handleDelegatedEvent__', 'empty_attribute', {eventType, actionElement});\n return;\n }\n\n if (!(actionElement instanceof HTMLElement)) {\n logger_.accident('handleDelegatedEvent__', 'target_not_html_element', {eventType, actionElement});\n return;\n }\n\n const descriptor = parseDescriptor__(attributeValue);\n if (!descriptor) return;\n\n logger_.logMethodArgs?.('handleDelegatedEvent__.action', {eventType, descriptor});\n\n // Step 1: handle once modifier — remove attribute before running other modifiers\n // so that even if a modifier aborts, the element will not fire again.\n if (descriptor.modifiers.has('once')) {\n actionElement.removeAttribute(actionAttrib);\n }\n\n // Step 2: run modifiers\n for (const modifier of descriptor.modifiers) {\n if (modifier === 'once') continue; // handled above\n const handler = modifierRegistry.get(modifier);\n if (!handler) {\n logger_.accident('handleDelegatedEvent__', 'unknown_modifier', {eventType, modifier, attributeValue, descriptor});\n return; // unknown modifier — abort to avoid silent misbehavior\n }\n if (handler(event, actionElement) === false) return;\n }\n\n // Step 3: resolve payload\n let payload: unknown = descriptor.payload;\n if (payload) {\n const resolver = payloadRegistry.get(payload as string);\n if (resolver) payload = resolver(event, actionElement);\n }\n\n // Step 4: dispatch\n internalChannel_.dispatch(descriptor.actionId, payload);\n}\n\n// ─── Setup ────────────────────────────────────────────────────────────────────\n\n/**\n * The set of event types currently delegated to `document.body`.\n *\n * Tracked so that `setupActionDelegation` is idempotent — calling it multiple\n * times with the same event types does not register duplicate listeners.\n *\n * @internal\n */\nconst delegatedEventTypes__ = new Set<string>();\n\n/**\n * Default DOM event types that cover the vast majority of interactive elements.\n *\n * - `click` — buttons, links, checkboxes, custom interactive elements\n * - `submit` — form submission\n * - `input` — live text input, range sliders\n * - `change` — select boxes, checkboxes, radio buttons (fires on commit)\n *\n * Pass additional types to `setupActionDelegation` when your app uses other\n * events (e.g. `'keydown'`, `'pointerup'`).\n */\nexport const DEFAULT_DELEGATED_EVENTS: readonly string[] = ['click', 'submit', 'input', 'change'];\n\n/**\n * Registers global event delegation for `on-<eventType>` attributes.\n *\n * Attaches a single `capture`-phase listener on `document.body` for each\n * event type in `eventTypes`. All processing — modifier execution, payload\n * resolution, and `dispatchAction` — happens inside that one handler.\n *\n * **Call this once at application bootstrap**, before any user interaction.\n * Subsequent calls with the same event types are no-ops (idempotent).\n *\n * ### Why `capture: true`?\n *\n * Capture-phase listeners fire before bubble-phase listeners and also catch\n * events that do not bubble (e.g. `focus`, `blur`). This ensures the delegation\n * handler always runs, even when a child element calls `stopPropagation()`.\n *\n * ### Dynamic content\n *\n * Because the listener lives on `document.body`, any element added to the DOM\n * after this call — via `innerHTML`, `lit-html`, a framework renderer, or\n * server-sent HTML — is automatically covered. No re-bootstrap is needed.\n *\n * @param eventTypes - Event types to delegate. Defaults to `DEFAULT_DELEGATED_EVENTS`.\n *\n * @example — minimal bootstrap\n * ```ts\n * import {setupActionDelegation, onAction} from '@alwatr/action';\n *\n * // One call activates the entire page.\n * setupActionDelegation();\n *\n * onAction('open_drawer', (panel) => openDrawer(panel));\n * ```\n *\n * @example — with extra event types\n * ```ts\n * import {setupActionDelegation, DEFAULT_DELEGATED_EVENTS} from '@alwatr/action';\n *\n * setupActionDelegation([...DEFAULT_DELEGATED_EVENTS, 'keydown', 'pointerup']);\n * ```\n */\nexport function setupActionDelegation(eventTypes: readonly string[] = DEFAULT_DELEGATED_EVENTS): void {\n logger_.logMethodArgs?.('setupActionDelegation', {eventTypes});\n\n for (const eventType of eventTypes) {\n if (delegatedEventTypes__.has(eventType)) continue; // already registered — skip\n delegatedEventTypes__.add(eventType);\n // capture: true — fires before bubble-phase listeners and catches non-bubbling events.\n document.body.addEventListener(eventType, handleDelegatedEvent__, {capture: true});\n }\n}\n\n/**\n * Removes all global delegation listeners registered by `setupActionDelegation`.\n *\n * Useful in test environments where each test needs a clean slate, or in\n * micro-frontend setups where a sub-app is unmounted.\n *\n * After calling this, `setupActionDelegation` can be called again to re-register.\n */\nexport function teardownActionDelegation(): void {\n logger_.logMethod?.('teardownActionDelegation');\n for (const eventType of delegatedEventTypes__) {\n document.body.removeEventListener(eventType, handleDelegatedEvent__, {capture: true});\n }\n delegatedEventTypes__.clear();\n descriptorCache__.clear();\n}\n"
|
|
5
|
+
"import {createLogger} from '@alwatr/logger';\nimport {createChannelSignal} from '@alwatr/signal';\n\nimport type {Action} from './action.js';\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 internal action channel — a `ChannelSignal` keyed by action `type`.\n *\n * Each message on this channel is a full `Action` object (AFSA), not just a\n * raw payload. Subscribers registered via `onAction('foo', handler)` receive\n * the entire `Action<'foo'>` so they have access to `context`, `meta`, and\n * `payload` in one place.\n *\n * Uses `ChannelSignal` for O(1) routing: dispatching action `'A'` performs a\n * single `Map.get('A')` lookup and invokes only the handlers registered for\n * that specific type — never handlers for `'B'`, `'C'`, etc.\n *\n * @internal — not part of the public API; use `onAction` / `dispatchAction` instead.\n */\nexport const internalChannel_ = createChannelSignal<Record<string, Action>>({name: 'alwatr-action'});\n",
|
|
6
|
+
"import type {Action} from './action.js';\n\n// ─── Type Definitions ────────────────────────────────────────────────────────\n\n/**\n * A modifier handler used in `on-<eventType>` attribute syntax.\n *\n * Receives the triggering DOM `event`, the `element` that owns the\n * `on-<eventType>` attribute, and the **mutable** `action` object being built.\n * The handler may mutate `action.meta` to attach cross-cutting data (e.g. a\n * trace ID, a timestamp, or an A/B flag) before the action reaches subscribers.\n *\n * Return `true` (or any truthy value) to allow the action to proceed, or\n * `false` to cancel the dispatch entirely.\n *\n * Using explicit parameters instead of `this` binding makes handlers\n * compatible with arrow functions and easier to test in isolation.\n *\n * @example — a modifier that stamps a timestamp into meta\n * ```ts\n * const timestampHandler: ModifierHandler = (_event, _element, action) => {\n * action.meta ??= {};\n * action.meta['timestamp'] = Date.now();\n * return true;\n * };\n * ```\n *\n * @example — a modifier that cancels dispatch when the element is disabled\n * ```ts\n * const notDisabledHandler: ModifierHandler = (_event, element) => {\n * return !(element as HTMLButtonElement).disabled;\n * };\n * ```\n */\nexport type ModifierHandler = (event: Event, element: HTMLElement, action: Action) => boolean;\n\n/**\n * A payload resolver used in `on-<eventType>` attribute syntax.\n *\n * Receives the triggering DOM `event` and the `element` that owns the\n * `on-<eventType>` attribute. The return value becomes the `payload` field of\n * the `Action` object passed to `onAction` subscribers.\n *\n * Using explicit parameters instead of `this` binding makes resolvers\n * compatible with arrow functions and easier to test in isolation.\n *\n * @example — a resolver that returns the element's dataset id\n * ```ts\n * const dataIdResolver: PayloadResolver = (_event, element) => {\n * return (element as HTMLElement).dataset.id ?? null;\n * };\n * ```\n */\nexport type PayloadResolver = (event: Event, element: HTMLElement) => unknown;\n\n// ─── Registries ──────────────────────────────────────────────────────────────\n\n/**\n * Registry of all named modifier handlers.\n *\n * Keys are modifier names used in the `on-<eventType>` attribute syntax\n * (e.g. `on-click=\"action-id; prevent\"`). 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-<eventType>` attribute syntax\n * (e.g. `on-input=\"search_query:$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-submit=\"submit-form; prevent\">`\n */\nmodifierRegistry.set('prevent', (event) => {\n event.preventDefault();\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.\n *\n * Pair with `prevent` on `submit` events to avoid page reloads:\n *\n * @example `<form on-submit=\"submit_form:$formdata; prevent,validate\" novalidate>`\n */\nmodifierRegistry.set('validate', (_event, element) => {\n const form = element instanceof HTMLFormElement ? element : element.closest('form');\n if (!form) return false;\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-input=\"search_query:$value\" />`\n */\npayloadRegistry.set('$value', (_event, element) => {\n return 'value' in element ? (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-submit=\"submit_form:$formdata; prevent,validate\">`\n * ```ts\n * onAction('submit_form', (action) => {\n * console.log(action.payload); // {username: 'ali', password: '…'}\n * });\n * ```\n */\npayloadRegistry.set('$formdata', (_event, element) => {\n const form = element instanceof HTMLFormElement ? element : element.closest('form');\n return form ? Object.fromEntries(new FormData(form)) : null;\n});\n\n/**\n * `$checked` — resolves to the `.checked` boolean property of a checkbox or radio input.\n *\n * Works with `<input type=\"checkbox\">` and `<input type=\"radio\">`.\n * Returns `null` for elements that do not have a `checked` property.\n *\n * @example `<input type=\"checkbox\" on-change=\"toggle_feature:$checked\" />`\n * ```ts\n * onAction('toggle_feature', (action) => {\n * console.log(action.payload); // true or false\n * featureSignal.set(action.payload);\n * });\n * ```\n */\npayloadRegistry.set('$checked', (_event, element) => {\n return 'checked' in element ? (element as HTMLInputElement).checked : null;\n});\n",
|
|
7
|
+
"import type {Awaitable} from '@alwatr/type-helper';\nimport type {SubscribeResult} from '@alwatr/signal';\n\nimport {internalChannel_, logger_} from './lib.js';\nimport {modifierRegistry, payloadRegistry, type ModifierHandler, type PayloadResolver} from './registry.js';\nimport type {ActionRecord} from './action-record.js';\nimport type {Action} from './action.js';\n\n// Re-export extension types so consumers can import them from the package root.\nexport type {ModifierHandler, PayloadResolver};\nexport type {Action};\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\n * ```ts\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: Action<K>): void {\n logger_.logMethodArgs?.('dispatchAction', action);\n internalChannel_.dispatch(action.type, action);\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",
|
|
8
|
+
"/**\n * @file delegate.ts\n *\n * Global Event Delegation engine for `@alwatr/action`.\n *\n * ## Why delegation instead of per-element listeners?\n *\n * The classic directive approach attaches one `addEventListener` per element.\n * With 100 buttons on a page, that means 100 listener registrations at boot\n * time — O(N) initialization cost, O(N) memory for listener references, and\n * zero support for elements added after bootstrap.\n *\n * This module implements the global delegation pattern:\n * - A single listener per event type is attached to `document.body` with\n * `capture: true` (so it fires even for non-bubbling events).\n * - When an event fires, the handler walks up the DOM from `event.target`\n * using `closest()` to find the nearest element with an `on-<eventType>`\n * attribute (e.g. `on-click`, `on-submit`).\n * - The nearest `[action-context]` ancestor is also resolved and attached to\n * the `Action` object as `context` — enabling the same action type to be\n * scoped to different UI regions.\n * - Modifiers run with access to the mutable `Action` object so they can\n * enrich `meta` before the action reaches subscribers.\n * - `dispatchAction` is called with the fully assembled `Action` object.\n *\n * ## Complexity\n *\n * | Metric | Per-element listeners | Global delegation |\n * | --------------- | --------------------- | ----------------- |\n * | Boot time | O(N elements) | O(1) — 1 loop |\n * | Memory | O(N listeners) | O(1) — 1 handler |\n * | Dynamic content | Requires re-bootstrap | Works out-of-box |\n * | `once` modifier | Native option | Manual tracking |\n *\n * ## Trade-offs vs. the directive approach\n *\n * - `passive` is not supported as a per-element option (all delegated listeners\n * are non-passive so that `prevent` can call `preventDefault()`).\n * - `stop` stops further bubbling but the delegation handler has already\n * captured the event at `body` level — it does not prevent other delegation\n * handlers from running on the same element.\n * - `once` is emulated by removing the attribute after first fire.\n */\n\nimport {internalChannel_, logger_} from './lib.js';\nimport {modifierRegistry, payloadRegistry} from './registry.js';\nimport type {Action} from './action.js';\nimport type {ActionRecord} from './action-record.js';\n\n// ─── Syntax Parser ────────────────────────────────────────────────────────────\n\n/**\n * Parses the `on-<eventType>` attribute value into its segments.\n *\n * Syntax: `actionId[:payload][; modifier1,modifier2,…]`\n *\n * The event type is encoded in the **attribute name** itself (`on-click`,\n * `on-submit`, etc.) rather than inside the value. This makes the HTML more\n * readable and aligns with native event attribute conventions.\n *\n * | Capture group | Matches | Example |\n * | ------------- | -------------------------------------- | ---------------------- |\n * | 1 | Action identifier | `open_drawer` |\n * | 2 | Optional payload token or literal | `main_menu` / `$value` |\n * | 3 | Optional comma-separated modifier list | `prevent,validate` |\n *\n * @example\n * ```\n * 'close_drawer'\n * → actionId='close_drawer', payload=undefined, modifiers={}\n *\n * 'open_drawer:main_menu'\n * → actionId='open_drawer', payload='main_menu', modifiers={}\n *\n * 'my_submit_handler:$formdata; prevent,validate'\n * → actionId='my_submit_handler', payload='$formdata', modifiers={'prevent','validate'}\n * ```\n */\nconst syntaxRegex = /^([a-z0-9_:-]+)(?::([^;]+))?(?:;\\s*([a-z0-9_,-]+))?$/;\n\n// ─── Parsed Action Descriptor ─────────────────────────────────────────────────\n\n/**\n * Parsed and cached representation of a single `on-<eventType>` attribute value.\n *\n * Does not store `eventType` — the caller always has it from `event.type`,\n * and the attribute name already encodes it (e.g. `on-click`), so storing it\n * here would be redundant. This also keeps the cache key simple: just the raw\n * attribute value string, with no composite key needed.\n */\ninterface ActionDescriptor {\n /** Set of active modifier names (e.g. `{'prevent', 'once'}`). */\n readonly modifiers: ReadonlySet<string>;\n /** The action identifier dispatched to `onAction` subscribers. */\n readonly actionId: string;\n /** Raw payload token from the attribute (literal string or $-resolver key). */\n readonly payload: string | undefined;\n}\n\n/**\n * Cache for parsed `on-<eventType>` attribute values.\n *\n * Attribute strings are typically repeated across many elements (e.g. every\n * \"add to cart\" button shares the same `on-click` value). Caching the parsed\n * descriptor avoids redundant regex work on every event.\n *\n * The cache key is the raw attribute value string. No composite key with\n * event type is needed because the attribute name already encodes the event\n * type — `on-click=\"open_drawer\"` and `on-submit=\"open_drawer\"` are two\n * separate attributes with the same value string, but they are read from\n * different attribute names and never collide in this cache.\n *\n * @internal\n */\nconst descriptorCache__ = new Map<string, ActionDescriptor | null>();\n\n/**\n * Parses an `on-<eventType>` attribute value into an `ActionDescriptor`.\n *\n * Returns `null` when the syntax is invalid. Results are cached by the raw\n * attribute value string so repeated calls for the same value are O(1).\n *\n * @internal\n */\nfunction parseDescriptor__(attributeValue: string): ActionDescriptor | null {\n logger_.logMethodArgs?.('parseDescriptor__', {attributeValue});\n\n const cached = descriptorCache__.get(attributeValue);\n // Explicit `undefined` check: `null` means \"already parsed and invalid\".\n if (cached !== undefined) return cached;\n\n const match = attributeValue.match(syntaxRegex);\n if (!match) {\n logger_.accident('parseDescriptor__', 'invalid_syntax', {attributeValue});\n descriptorCache__.set(attributeValue, null);\n return null;\n }\n\n const actionId = match[1];\n const payload: string | undefined = match[2];\n // match[3] is the raw modifier list string, e.g. \"prevent,validate\"\n const modifierString = match[3];\n const modifiers: Set<string> = modifierString ? new Set(modifierString.split(',').filter(Boolean)) : new Set();\n const descriptor: ActionDescriptor = {modifiers, actionId, payload};\n\n descriptorCache__.set(attributeValue, descriptor);\n return descriptor;\n}\n\n// ─── Core Delegation Handler ──────────────────────────────────────────────────\n\n/**\n * Central event handler attached to `document.body` for every delegated event type.\n *\n * Execution flow for each incoming event:\n * 1. Walk up from `event.target` to find the nearest element with an\n * `on-<eventType>` attribute (e.g. `on-click`, `on-submit`).\n * 2. Parse (or retrieve from cache) the `ActionDescriptor` for that attribute.\n * 3. Resolve `context` from the nearest `[action-context]` ancestor.\n * 4. Build a mutable `Action` object with `type`, `payload` (raw), and `context`.\n * 5. Run each modifier in order with access to the mutable `Action`; if any\n * returns `false`, abort.\n * 6. Resolve the payload token (literal or $-resolver) and assign to `action.payload`.\n * 7. Call `dispatchAction(action)` with the fully assembled object.\n *\n * @internal\n */\nfunction handleDelegatedEvent__(event: Event): void {\n const eventType = event.type;\n logger_.logMethodArgs?.('handleDelegatedEvent__', {eventType});\n\n const target = event.target as Element | null;\n if (!target) return;\n\n // Attribute name encodes the event type: on-click, on-submit, etc.\n const actionAttrib = `on-${eventType}`;\n\n // Walk up the DOM to find the closest element with the matching on-<eventType> attribute.\n const actionElement = target.closest?.(`[${actionAttrib}]`);\n if (!actionElement) return;\n\n const attributeValue = actionElement.getAttribute?.(actionAttrib)?.trim();\n if (!attributeValue) {\n logger_.accident('handleDelegatedEvent__', 'empty_attribute', {eventType, actionElement});\n return;\n }\n\n if (!(actionElement instanceof HTMLElement)) {\n logger_.accident('handleDelegatedEvent__', 'target_not_html_element', {eventType, actionElement});\n return;\n }\n\n const descriptor = parseDescriptor__(attributeValue);\n if (!descriptor) return;\n\n logger_.logMethodArgs?.('handleDelegatedEvent__.action', {eventType, descriptor});\n\n // Step 1: handle `once` modifier — remove attribute before running other modifiers\n // so that even if a modifier aborts, the element will not fire again.\n if (descriptor.modifiers.has('once')) {\n actionElement.removeAttribute(actionAttrib);\n }\n\n // Step 2: resolve `context` from the nearest [action-context] ancestor.\n // Walk up from the action element itself (inclusive) to find the context scope.\n // This allows the action element itself to carry action-context if needed.\n const actionContext = actionElement.closest('[action-context]')?.getAttribute('action-context') ?? undefined;\n\n // Step 3: build the mutable Action object.\n // `payload` starts as the raw token string; it will be resolved in step 5.\n // Modifiers in step 4 may mutate `meta` to attach cross-cutting data.\n const action: Action = {\n type: descriptor.actionId as keyof ActionRecord,\n context: actionContext,\n // Payload is temporarily set to the raw token; resolved below after modifiers run.\n payload: descriptor.payload as ActionRecord[keyof ActionRecord],\n };\n\n // Step 4: run modifiers — each receives the mutable action so it can enrich meta.\n for (const modifier of descriptor.modifiers) {\n if (modifier === 'once') continue; // handled above\n const handler = modifierRegistry.get(modifier);\n if (!handler) {\n logger_.accident('handleDelegatedEvent__', 'unknown_modifier', {eventType, modifier, attributeValue, descriptor});\n return; // unknown modifier — abort to avoid silent misbehavior\n }\n if (handler(event, actionElement, action) === false) return;\n }\n\n // Step 5: resolve payload — replace raw token with the actual value.\n // If the raw token starts with '$', look it up in the payload resolver registry.\n // Otherwise treat it as a literal string payload.\n if (descriptor.payload) {\n const resolver = payloadRegistry.get(descriptor.payload);\n if (resolver) {\n // Cast needed: payload is typed as ActionRecord[K] but we're building generically.\n (action as {payload: unknown}).payload = resolver(event, actionElement);\n }\n // else: keep the literal string already set on action.payload\n } else {\n // No payload token in the attribute — set to undefined.\n (action as {payload: unknown}).payload = undefined;\n }\n\n // Step 6: dispatch the fully assembled Action object.\n internalChannel_.dispatch(action.type, action);\n}\n\n// ─── Setup ────────────────────────────────────────────────────────────────────\n\n/**\n * The set of event types currently delegated to `document.body`.\n *\n * Tracked so that `setupActionDelegation` is idempotent — calling it multiple\n * times with the same event types does not register duplicate listeners.\n *\n * @internal\n */\nconst delegatedEventTypes__ = new Set<string>();\n\n/**\n * Default DOM event types that cover the vast majority of interactive elements.\n *\n * - `click` — buttons, links, checkboxes, custom interactive elements\n * - `submit` — form submission\n * - `input` — live text input, range sliders\n * - `change` — select boxes, checkboxes, radio buttons (fires on commit)\n *\n * Pass additional types to `setupActionDelegation` when your app uses other\n * events (e.g. `'keydown'`, `'pointerup'`).\n */\nexport const DEFAULT_DELEGATED_EVENTS: readonly string[] = ['click', 'submit', 'input', 'change'];\n\n/**\n * Registers global event delegation for `on-<eventType>` attributes.\n *\n * Attaches a single `capture`-phase listener on `document.body` for each\n * event type in `eventTypes`. All processing — context resolution, modifier\n * execution, payload resolution, and `dispatchAction` — happens inside that\n * one handler.\n *\n * **Call this once at application bootstrap**, before any user interaction.\n * Subsequent calls with the same event types are no-ops (idempotent).\n *\n * ### Why `capture: true`?\n *\n * Capture-phase listeners fire before bubble-phase listeners and also catch\n * events that do not bubble (e.g. `focus`, `blur`). This ensures the delegation\n * handler always runs, even when a child element calls `stopPropagation()`.\n *\n * ### Dynamic content\n *\n * Because the listener lives on `document.body`, any element added to the DOM\n * after this call — via `innerHTML`, `lit-html`, a framework renderer, or\n * server-sent HTML — is automatically covered. No re-bootstrap is needed.\n *\n * ### Context scoping\n *\n * Wrap a group of elements in a `[action-context]` container to scope their\n * actions. The delegation handler automatically resolves the nearest ancestor\n * and attaches its value to `action.context`:\n *\n * ```html\n * <section action-context=\"product-list\">\n * <button on-click=\"add_to_cart:42\">Add</button>\n * </section>\n * ```\n *\n * ```ts\n * onAction('add_to_cart', (action) => {\n * console.log(action.context); // 'product-list'\n * });\n * ```\n *\n * @param eventTypes - Event types to delegate. Defaults to `DEFAULT_DELEGATED_EVENTS`.\n *\n * @example — minimal bootstrap\n * ```ts\n * import {setupActionDelegation, onAction} from '@alwatr/action';\n *\n * // One call activates the entire page.\n * setupActionDelegation();\n *\n * onAction('open_drawer', (action) => openDrawer(action.payload));\n * ```\n *\n * @example — with extra event types\n * ```ts\n * import {setupActionDelegation, DEFAULT_DELEGATED_EVENTS} from '@alwatr/action';\n *\n * setupActionDelegation([...DEFAULT_DELEGATED_EVENTS, 'keydown', 'pointerup']);\n * ```\n */\nexport function setupActionDelegation(eventTypes: readonly string[] = DEFAULT_DELEGATED_EVENTS): void {\n logger_.logMethodArgs?.('setupActionDelegation', {eventTypes});\n\n for (const eventType of eventTypes) {\n if (delegatedEventTypes__.has(eventType)) continue; // already registered — skip\n delegatedEventTypes__.add(eventType);\n // capture: true — fires before bubble-phase listeners and catches non-bubbling events.\n document.body.addEventListener(eventType, handleDelegatedEvent__, {capture: true});\n }\n}\n\n/**\n * Removes all global delegation listeners registered by `setupActionDelegation`.\n *\n * Useful in test environments where each test needs a clean slate, or in\n * micro-frontend setups where a sub-app is unmounted.\n *\n * After calling this, `setupActionDelegation` can be called again to re-register.\n */\nexport function teardownActionDelegation(): void {\n logger_.logMethod?.('teardownActionDelegation');\n for (const eventType of delegatedEventTypes__) {\n document.body.removeEventListener(eventType, handleDelegatedEvent__, {capture: true});\n }\n delegatedEventTypes__.clear();\n descriptorCache__.clear();\n}\n"
|
|
9
9
|
],
|
|
10
|
-
"mappings": ";AAAA,uBAAQ,uBACR,8BAAQ,
|
|
11
|
-
"debugId": "
|
|
10
|
+
"mappings": "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",
|
|
11
|
+
"debugId": "F2B64ABE6411370464756E2164756E21",
|
|
12
12
|
"names": []
|
|
13
13
|
}
|
package/dist/method.d.ts
CHANGED
|
@@ -2,18 +2,22 @@ import type { Awaitable } from '@alwatr/type-helper';
|
|
|
2
2
|
import type { SubscribeResult } from '@alwatr/signal';
|
|
3
3
|
import { type ModifierHandler, type PayloadResolver } from './registry.js';
|
|
4
4
|
import type { ActionRecord } from './action-record.js';
|
|
5
|
+
import type { Action } from './action.js';
|
|
5
6
|
export type { ModifierHandler, PayloadResolver };
|
|
7
|
+
export type { Action };
|
|
6
8
|
/**
|
|
7
9
|
* Subscribes to a named action dispatched anywhere in the application.
|
|
8
10
|
*
|
|
9
|
-
* `
|
|
10
|
-
*
|
|
11
|
-
* generic annotation needed
|
|
11
|
+
* `type` must be a key of `ActionRecord`. The handler receives the full
|
|
12
|
+
* `Action<K>` object — giving access to `payload`, `context`, and `meta`
|
|
13
|
+
* in one place. No manual generic annotation is needed; the compiler infers
|
|
14
|
+
* the correct `payload` type from `ActionRecord`:
|
|
12
15
|
*
|
|
13
16
|
* ```ts
|
|
14
17
|
* // ActionRecord declares: 'add_to_cart': {productId: number; qty: number}
|
|
15
|
-
* onAction('add_to_cart', (
|
|
16
|
-
* cartService.add(
|
|
18
|
+
* onAction('add_to_cart', (action) => {
|
|
19
|
+
* cartService.add(action.payload.productId, action.payload.qty); // fully typed
|
|
20
|
+
* console.log(action.context); // e.g. 'product-list' (from DOM) or undefined
|
|
17
21
|
* });
|
|
18
22
|
* ```
|
|
19
23
|
*
|
|
@@ -32,68 +36,69 @@ export type { ModifierHandler, PayloadResolver };
|
|
|
32
36
|
* Internally delegates to `ChannelSignal.on()` for **O(1) routing** — dispatching
|
|
33
37
|
* action `'A'` never invokes handlers registered for action `'B'`.
|
|
34
38
|
*
|
|
35
|
-
* @param
|
|
36
|
-
* @param handler
|
|
39
|
+
* @param type - A key of `ActionRecord`.
|
|
40
|
+
* @param handler - Callback invoked with the full `Action<K>` on each dispatch.
|
|
37
41
|
* @returns A `SubscribeResult` with an `unsubscribe()` method for cleanup.
|
|
38
42
|
*
|
|
39
43
|
* @example
|
|
40
44
|
* ```ts
|
|
41
45
|
* import {onAction} from '@alwatr/action';
|
|
42
46
|
*
|
|
43
|
-
* const sub = onAction('page_ready', (
|
|
44
|
-
* router.setPage(
|
|
47
|
+
* const sub = onAction('page_ready', (action) => {
|
|
48
|
+
* router.setPage(action.payload); // payload: string — inferred from ActionRecord
|
|
45
49
|
* });
|
|
46
50
|
*
|
|
47
51
|
* sub.unsubscribe(); // stop listening when no longer needed
|
|
48
52
|
* ```
|
|
49
53
|
*/
|
|
50
|
-
export declare function onAction<K extends keyof ActionRecord>(
|
|
54
|
+
export declare function onAction<K extends keyof ActionRecord>(type: K, handler: (action: Action<K>) => Awaitable<void>): SubscribeResult;
|
|
51
55
|
/**
|
|
52
|
-
* Dispatches
|
|
56
|
+
* Dispatches an action to all `onAction` subscribers with a matching `type`.
|
|
53
57
|
*
|
|
54
|
-
*
|
|
55
|
-
*
|
|
58
|
+
* Accepts a full `Action<K>` object. The `payload` field is automatically
|
|
59
|
+
* typed from `ActionRecord[K]` — passing the wrong shape is a **compile error**:
|
|
56
60
|
*
|
|
57
61
|
* ```ts
|
|
58
62
|
* // ActionRecord declares: 'add_to_cart': {productId: number; qty: number}
|
|
59
|
-
* dispatchAction('add_to_cart', {productId: 42, qty: 1}); // ✅
|
|
60
|
-
* dispatchAction('add_to_cart', 'wrong'); // ❌ compile error
|
|
61
|
-
* dispatchAction('unknown_action', 'x'); // ❌ compile error
|
|
63
|
+
* dispatchAction({type: 'add_to_cart', payload: {productId: 42, qty: 1}}); // ✅
|
|
64
|
+
* dispatchAction({type: 'add_to_cart', payload: 'wrong'}); // ❌ compile error
|
|
65
|
+
* dispatchAction({type: 'unknown_action', payload: 'x'}); // ❌ compile error
|
|
62
66
|
* ```
|
|
63
67
|
*
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
*
|
|
67
|
-
* // src/action-record.ts
|
|
68
|
-
* declare module '@alwatr/action' {
|
|
69
|
-
* interface ActionRecord {
|
|
70
|
-
* 'navigate': string;
|
|
71
|
-
* 'logout': void;
|
|
72
|
-
* }
|
|
73
|
-
* }
|
|
74
|
-
* ```
|
|
68
|
+
* The `context` and `meta` fields are optional. When dispatching from code
|
|
69
|
+
* (not from the DOM), omit `context` — it is only meaningful for DOM-originated
|
|
70
|
+
* actions where an `[action-context]` ancestor exists.
|
|
75
71
|
*
|
|
76
72
|
* Use `dispatchAction` when triggering an action from code — e.g. after an
|
|
77
73
|
* async operation, from a service layer, or in tests. For DOM-driven actions,
|
|
78
74
|
* use the `on-<eventType>` HTML attribute with `setupActionDelegation`.
|
|
79
75
|
*
|
|
80
|
-
* @param
|
|
81
|
-
* @param actionPayload - The payload; type is enforced by `ActionRecord`.
|
|
76
|
+
* @param action - A full `Action<K>` object with at minimum `type` and `payload`.
|
|
82
77
|
*
|
|
83
78
|
* @example — with payload
|
|
84
79
|
* ```ts
|
|
85
80
|
* import {dispatchAction} from '@alwatr/action';
|
|
86
81
|
*
|
|
87
|
-
* dispatchAction('
|
|
88
|
-
* dispatchAction('
|
|
82
|
+
* dispatchAction({type: 'navigate', payload: '/dashboard'});
|
|
83
|
+
* dispatchAction({type: 'add_to_cart', payload: {productId: 42, qty: 1}});
|
|
89
84
|
* ```
|
|
90
85
|
*
|
|
91
|
-
* @example — void payload
|
|
86
|
+
* @example — void payload
|
|
92
87
|
* ```ts
|
|
93
|
-
* dispatchAction('logout');
|
|
88
|
+
* dispatchAction({type: 'logout', payload: undefined});
|
|
89
|
+
* ```
|
|
90
|
+
*
|
|
91
|
+
* @example — with context and meta
|
|
92
|
+
* ```ts
|
|
93
|
+
* dispatchAction({
|
|
94
|
+
* type: 'slider_change',
|
|
95
|
+
* payload: 75,
|
|
96
|
+
* context: 'volume_slider',
|
|
97
|
+
* meta: {traceId: 'abc-123'},
|
|
98
|
+
* });
|
|
94
99
|
* ```
|
|
95
100
|
*/
|
|
96
|
-
export declare function dispatchAction<K extends keyof ActionRecord>(
|
|
101
|
+
export declare function dispatchAction<K extends keyof ActionRecord>(action: Action<K>): void;
|
|
97
102
|
/**
|
|
98
103
|
* Registers a custom modifier that can be used in `on-<eventType>` attribute syntax.
|
|
99
104
|
*
|
|
@@ -101,14 +106,17 @@ export declare function dispatchAction<K extends keyof ActionRecord>(...args: Ac
|
|
|
101
106
|
* (e.g. `on-click="action-id; mymod"`). Its handler runs before the payload is
|
|
102
107
|
* resolved and the action is dispatched. Returning `false` cancels the dispatch.
|
|
103
108
|
*
|
|
104
|
-
*
|
|
105
|
-
*
|
|
109
|
+
* The handler also receives the **mutable** `action` object being built, so it
|
|
110
|
+
* can attach data to `action.meta` before the action reaches subscribers.
|
|
111
|
+
*
|
|
112
|
+
* Built-in modifiers (`prevent`, `validate`, `once`) are always available.
|
|
113
|
+
* This function lets you add domain-specific ones.
|
|
106
114
|
*
|
|
107
115
|
* Registering the same name twice logs an accident and overwrites the previous
|
|
108
116
|
* handler — avoid duplicate registrations in production code.
|
|
109
117
|
*
|
|
110
118
|
* @param name - The modifier token (lowercase, no special characters).
|
|
111
|
-
* @param handler - A `ModifierHandler` receiving `(event, element)`.
|
|
119
|
+
* @param handler - A `ModifierHandler` receiving `(event, element, action)`.
|
|
112
120
|
*
|
|
113
121
|
* @example — a `confirm` modifier that shows a browser dialog
|
|
114
122
|
* ```ts
|
|
@@ -119,6 +127,15 @@ export declare function dispatchAction<K extends keyof ActionRecord>(...args: Ac
|
|
|
119
127
|
* ```html
|
|
120
128
|
* <button on-click="delete_item:42; confirm">Delete</button>
|
|
121
129
|
* ```
|
|
130
|
+
*
|
|
131
|
+
* @example — a `trace` modifier that stamps a trace ID into meta
|
|
132
|
+
* ```ts
|
|
133
|
+
* registerModifier('trace', (_event, _element, action) => {
|
|
134
|
+
* action.meta ??= {};
|
|
135
|
+
* action.meta['traceId'] = crypto.randomUUID();
|
|
136
|
+
* return true;
|
|
137
|
+
* });
|
|
138
|
+
* ```
|
|
122
139
|
*/
|
|
123
140
|
export declare function registerModifier(name: string, handler: ModifierHandler): void;
|
|
124
141
|
/**
|
|
@@ -126,11 +143,11 @@ export declare function registerModifier(name: string, handler: ModifierHandler)
|
|
|
126
143
|
*
|
|
127
144
|
* A payload resolver is a colon-prefixed token in the attribute value
|
|
128
145
|
* (e.g. `on-click="action-id:$mytoken"`). Its function is called at dispatch time
|
|
129
|
-
* with
|
|
130
|
-
*
|
|
146
|
+
* with the DOM event and the element. The return value becomes the `payload`
|
|
147
|
+
* field of the `Action` object passed to `onAction` subscribers.
|
|
131
148
|
*
|
|
132
|
-
* Built-in resolvers (`$value`, `$formdata`) are always available.
|
|
133
|
-
* lets you add domain-specific ones.
|
|
149
|
+
* Built-in resolvers (`$value`, `$formdata`, `$checked`) are always available.
|
|
150
|
+
* This function lets you add domain-specific ones.
|
|
134
151
|
*
|
|
135
152
|
* Registering the same name twice logs an accident and overwrites the previous
|
|
136
153
|
* resolver — avoid duplicate registrations in production code.
|
|
@@ -138,16 +155,16 @@ export declare function registerModifier(name: string, handler: ModifierHandler)
|
|
|
138
155
|
* @param name - The resolver token (should start with `$` by convention).
|
|
139
156
|
* @param resolver - A `PayloadResolver` receiving `(event, element)`.
|
|
140
157
|
*
|
|
141
|
-
* @example — a `$
|
|
158
|
+
* @example — a `$data-id` resolver that reads a data attribute
|
|
142
159
|
* ```ts
|
|
143
160
|
* import {registerPayloadResolver} from '@alwatr/action';
|
|
144
161
|
*
|
|
145
|
-
* registerPayloadResolver('$
|
|
146
|
-
* return (element as
|
|
162
|
+
* registerPayloadResolver('$data-id', (_event, element) => {
|
|
163
|
+
* return (element as HTMLElement).dataset.id ?? null;
|
|
147
164
|
* });
|
|
148
165
|
* ```
|
|
149
166
|
* ```html
|
|
150
|
-
* <
|
|
167
|
+
* <button on-click="select_item:$data-id" data-id="42">Select</button>
|
|
151
168
|
* ```
|
|
152
169
|
*/
|
|
153
170
|
export declare function registerPayloadResolver(name: string, resolver: PayloadResolver): void;
|
package/dist/method.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"method.d.ts","sourceRoot":"","sources":["../src/method.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;
|
|
1
|
+
{"version":3,"file":"method.d.ts","sourceRoot":"","sources":["../src/method.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAGpD,OAAO,EAAoC,KAAK,eAAe,EAAE,KAAK,eAAe,EAAC,MAAM,eAAe,CAAC;AAC5G,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AAGxC,YAAY,EAAC,eAAe,EAAE,eAAe,EAAC,CAAC;AAC/C,YAAY,EAAC,MAAM,EAAC,CAAC;AAIrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,YAAY,EACnD,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,IAAI,CAAC,GAC9C,eAAe,CAMjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAGpF;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAM7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAMrF"}
|
package/dist/registry.d.ts
CHANGED
|
@@ -1,35 +1,47 @@
|
|
|
1
|
+
import type { Action } from './action.js';
|
|
1
2
|
/**
|
|
2
|
-
* A modifier handler used in `on
|
|
3
|
+
* A modifier handler used in `on-<eventType>` attribute syntax.
|
|
3
4
|
*
|
|
4
|
-
* Receives the triggering DOM `event
|
|
5
|
-
* `on
|
|
6
|
-
*
|
|
5
|
+
* Receives the triggering DOM `event`, the `element` that owns the
|
|
6
|
+
* `on-<eventType>` attribute, and the **mutable** `action` object being built.
|
|
7
|
+
* The handler may mutate `action.meta` to attach cross-cutting data (e.g. a
|
|
8
|
+
* trace ID, a timestamp, or an A/B flag) before the action reaches subscribers.
|
|
9
|
+
*
|
|
10
|
+
* Return `true` (or any truthy value) to allow the action to proceed, or
|
|
11
|
+
* `false` to cancel the dispatch entirely.
|
|
7
12
|
*
|
|
8
13
|
* Using explicit parameters instead of `this` binding makes handlers
|
|
9
14
|
* compatible with arrow functions and easier to test in isolation.
|
|
10
15
|
*
|
|
11
|
-
* @example
|
|
16
|
+
* @example — a modifier that stamps a timestamp into meta
|
|
17
|
+
* ```ts
|
|
18
|
+
* const timestampHandler: ModifierHandler = (_event, _element, action) => {
|
|
19
|
+
* action.meta ??= {};
|
|
20
|
+
* action.meta['timestamp'] = Date.now();
|
|
21
|
+
* return true;
|
|
22
|
+
* };
|
|
23
|
+
* ```
|
|
24
|
+
*
|
|
25
|
+
* @example — a modifier that cancels dispatch when the element is disabled
|
|
12
26
|
* ```ts
|
|
13
|
-
* // A modifier that only allows the action when the element is not disabled
|
|
14
27
|
* const notDisabledHandler: ModifierHandler = (_event, element) => {
|
|
15
28
|
* return !(element as HTMLButtonElement).disabled;
|
|
16
29
|
* };
|
|
17
30
|
* ```
|
|
18
31
|
*/
|
|
19
|
-
export type ModifierHandler = (event: Event, element: HTMLElement) => boolean;
|
|
32
|
+
export type ModifierHandler = (event: Event, element: HTMLElement, action: Action) => boolean;
|
|
20
33
|
/**
|
|
21
|
-
* A payload resolver used in `on
|
|
34
|
+
* A payload resolver used in `on-<eventType>` attribute syntax.
|
|
22
35
|
*
|
|
23
36
|
* Receives the triggering DOM `event` and the `element` that owns the
|
|
24
|
-
* `on
|
|
25
|
-
*
|
|
37
|
+
* `on-<eventType>` attribute. The return value becomes the `payload` field of
|
|
38
|
+
* the `Action` object passed to `onAction` subscribers.
|
|
26
39
|
*
|
|
27
40
|
* Using explicit parameters instead of `this` binding makes resolvers
|
|
28
41
|
* compatible with arrow functions and easier to test in isolation.
|
|
29
42
|
*
|
|
30
|
-
* @example
|
|
43
|
+
* @example — a resolver that returns the element's dataset id
|
|
31
44
|
* ```ts
|
|
32
|
-
* // A resolver that returns the element's dataset id
|
|
33
45
|
* const dataIdResolver: PayloadResolver = (_event, element) => {
|
|
34
46
|
* return (element as HTMLElement).dataset.id ?? null;
|
|
35
47
|
* };
|
package/dist/registry.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AAIxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;AAE9F;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC;AAI9E;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,8BAAqC,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,8BAAqC,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alwatr/action",
|
|
3
|
-
"version": "9.
|
|
3
|
+
"version": "9.17.0",
|
|
4
4
|
"description": "Declarative DOM action-dispatch — bridge HTML attributes to typed signal handlers.",
|
|
5
5
|
"license": "MPL-2.0",
|
|
6
6
|
"author": "S. Ali Mihandoost <ali.mihandoost@gmail.com> (https://ali.mihandoost.com)",
|
|
@@ -79,5 +79,5 @@
|
|
|
79
79
|
"vanilla-js",
|
|
80
80
|
"web-development"
|
|
81
81
|
],
|
|
82
|
-
"gitHead": "
|
|
82
|
+
"gitHead": "782563375f55c55d29719cbcfebaca251d69ddcd"
|
|
83
83
|
}
|