@alwatr/action 9.25.0 → 9.27.0

package/src/delegate.ts

@@ -1,359 +0,0 @@
-/**
- * @file delegate.ts
- *
- * Global Event Delegation engine for `@alwatr/action`.
- *
- * ## Why delegation instead of per-element listeners?
- *
- * The classic directive approach attaches one `addEventListener` per element.
- * With 100 buttons on a page, that means 100 listener registrations at boot
- * time — O(N) initialization cost, O(N) memory for listener references, and
- * zero support for elements added after bootstrap.
- *
- * This module implements the global delegation pattern:
- * - A single listener per event type is attached to `document.body` with
- *   `capture: true` (so it fires even for non-bubbling events).
- * - When an event fires, the handler walks up the DOM from `event.target`
- *   using `closest()` to find the nearest element with an `on-<eventType>`
- *   attribute (e.g. `on-click`, `on-submit`).
- * - The nearest `[action-context]` ancestor is also resolved and attached to
- *   the `Action` object as `context` — enabling the same action type to be
- *   scoped to different UI regions.
- * - Modifiers run with access to the mutable `Action` object so they can
- *   enrich `meta` before the action reaches subscribers.
- * - `dispatchAction` is called with the fully assembled `Action` object.
- *
- * ## Complexity
- *
- * | Metric          | Per-element listeners | Global delegation |
- * | --------------- | --------------------- | ----------------- |
- * | Boot time       | O(N elements)         | O(1) — 1 loop     |
- * | Memory          | O(N listeners)        | O(1) — 1 handler  |
- * | Dynamic content | Requires re-bootstrap | Works out-of-box  |
- * | `once` modifier | Native option         | Manual tracking   |
- *
- * ## Trade-offs vs. the directive approach
- *
- * - `passive` is not supported as a per-element option (all delegated listeners
- *   are non-passive so that `prevent` can call `preventDefault()`).
- * - `stop` stops further bubbling but the delegation handler has already
- *   captured the event at `body` level — it does not prevent other delegation
- *   handlers from running on the same element.
- * - `once` is emulated by removing the attribute after first fire.
- */
-
-import {internalChannel_, logger_} from './lib_.js';
-import {modifierRegistry, payloadRegistry} from './registry_.js';
-import type {Action, ActionRecord} from './type.js';
-
-// ─── Syntax Parser ────────────────────────────────────────────────────────────
-
-/**
- * Parses the `on-<eventType>` attribute value into its segments.
- *
- * Syntax: `actionId[:payload][; modifier1,modifier2,…]`
- *
- * The event type is encoded in the **attribute name** itself (`on-click`,
- * `on-submit`, etc.) rather than inside the value. This makes the HTML more
- * readable and aligns with native event attribute conventions.
- *
- * | Capture group | Matches                                | Example                    |
- * | ------------- | -------------------------------------- | -------------------------- |
- * | 1             | Action identifier                      | `ui_open_drawer`           |
- * | 2             | Optional payload token or literal      | `main_menu` / `$value`     |
- * | 3             | Optional comma-separated modifier list | `prevent,validate`         |
- *
- * @example
- * ```
- * 'ui_close_drawer'
- *   → actionId='ui_close_drawer', payload=undefined, modifiers={}
- *
- * 'ui_open_drawer:main_menu'
- *   → actionId='ui_open_drawer', payload='main_menu', modifiers={}
- *
- * 'ui_submit_form:$formdata; prevent,validate'
- *   → actionId='ui_submit_form', payload='$formdata', modifiers={'prevent','validate'}
- * ```
- */
-const syntaxRegex = /^(ui_[a-z0-9_-]+)(?::([^;]+))?(?:;\s*([a-z0-9_,-]+))?$/;
-
-// ─── Parsed Action Descriptor ─────────────────────────────────────────────────
-
-/**
- * Parsed and cached representation of a single `on-<eventType>` attribute value.
- *
- * Does not store `eventType` — the caller always has it from `event.type`,
- * and the attribute name already encodes it (e.g. `on-click`), so storing it
- * here would be redundant. This also keeps the cache key simple: just the raw
- * attribute value string, with no composite key needed.
- */
-interface ActionDescriptor {
-  /** Set of active modifier names (e.g. `{'prevent', 'once'}`). */
-  readonly modifiers: ReadonlySet<string>;
-  /** The action identifier dispatched to `onAction` subscribers. */
-  readonly actionId: string;
-  /** Raw payload token from the attribute (literal string or $-resolver key). */
-  readonly payload: string | undefined;
-}
-
-/**
- * Cache for parsed `on-<eventType>` attribute values.
- *
- * Attribute strings are typically repeated across many elements (e.g. every
- * "add to cart" button shares the same `on-click` value). Caching the parsed
- * descriptor avoids redundant regex work on every event.
- *
- * The cache key is the raw attribute value string. No composite key with
- * event type is needed because the attribute name already encodes the event
- * type — `on-click="ui_open_drawer"` and `on-submit="ui_open_drawer"` are two
- * separate attributes with the same value string, but they are read from
- * different attribute names and never collide in this cache.
- *
- * @internal
- */
-const descriptorCache__ = new Map<string, ActionDescriptor | null>();
-
-/**
- * Parses an `on-<eventType>` attribute value into an `ActionDescriptor`.
- *
- * Returns `null` when the syntax is invalid. Results are cached by the raw
- * attribute value string so repeated calls for the same value are O(1).
- *
- * @internal
- */
-function parseDescriptor__(attributeValue: string): ActionDescriptor | null {
-  logger_.logMethodArgs?.('parseDescriptor__', {attributeValue});
-
-  const cached = descriptorCache__.get(attributeValue);
-  // Explicit `undefined` check: `null` means "already parsed and invalid".
-  if (cached !== undefined) return cached;
-
-  const match = attributeValue.match(syntaxRegex);
-  if (!match) {
-    logger_.accident('parseDescriptor__', 'invalid_syntax', {attributeValue});
-    descriptorCache__.set(attributeValue, null);
-    return null;
-  }
-
-  const actionId = match[1];
-  const payload: string | undefined = match[2];
-  // match[3] is the raw modifier list string, e.g. "prevent,validate"
-  const modifierString = match[3];
-  const modifiers: Set<string> = modifierString ? new Set(modifierString.split(',').filter(Boolean)) : new Set();
-  const descriptor: ActionDescriptor = {modifiers, actionId, payload};
-
-  descriptorCache__.set(attributeValue, descriptor);
-  return descriptor;
-}
-
-// ─── Core Delegation Handler ──────────────────────────────────────────────────
-
-/**
- * Central event handler attached to `document.body` for every delegated event type.
- *
- * Execution flow for each incoming event:
- * 1. Walk up from `event.target` to find the nearest element with an
- *    `on-<eventType>` attribute (e.g. `on-click`, `on-submit`).
- * 2. Parse (or retrieve from cache) the `ActionDescriptor` for that attribute.
- * 3. Resolve `context` from the nearest `[action-context]` ancestor.
- * 4. Build a mutable `Action` object with `type`, `payload` (raw), and `context`.
- * 5. Run each modifier in order with access to the mutable `Action`; if any
- *    returns `false`, abort.
- * 6. Resolve the payload token (literal or $-resolver) and assign to `action.payload`.
- * 7. Call `dispatchAction(action)` with the fully assembled object.
- *
- * @internal
- */
-function handleDelegatedEvent__(event: Event): void {
-  const eventType = event.type;
-  logger_.logMethodArgs?.('handleDelegatedEvent__', {eventType});
-
-  const target = event.target as Element | null;
-  if (!target) return;
-
-  // Attribute name encodes the event type: on-click, on-submit, etc.
-  const actionAttrib = `on-${eventType}`;
-
-  // Walk up the DOM to find the closest element with the matching on-<eventType> attribute.
-  const actionElement = target.closest?.(`[${actionAttrib}]`);
-  if (!actionElement) return;
-
-  const attributeValue = actionElement.getAttribute?.(actionAttrib)?.trim();
-  if (!attributeValue) {
-    logger_.accident('handleDelegatedEvent__', 'empty_attribute', {eventType, actionElement});
-    return;
-  }
-
-  if (!(actionElement instanceof HTMLElement)) {
-    logger_.accident('handleDelegatedEvent__', 'target_not_html_element', {eventType, actionElement});
-    return;
-  }
-
-  const descriptor = parseDescriptor__(attributeValue);
-  if (!descriptor) return;
-
-  logger_.logMethodArgs?.('handleDelegatedEvent__.action', {eventType, descriptor});
-
-  // Step 1: handle `once` modifier — remove attribute before running other modifiers
-  // so that even if a modifier aborts, the element will not fire again.
-  if (descriptor.modifiers.has('once')) {
-    actionElement.removeAttribute(actionAttrib);
-  }
-
-  // Step 2: resolve `context` from the nearest [action-context] ancestor.
-  // Walk up from the action element itself (inclusive) to find the context scope.
-  // This allows the action element itself to carry action-context if needed.
-  const actionContext = actionElement.closest('[action-context]')?.getAttribute('action-context') ?? undefined;
-
-  // Step 3: build the mutable Action object.
-  // `payload` starts as the raw token string; it will be resolved in step 5.
-  // Modifiers in step 4 may mutate `meta` to attach cross-cutting data.
-  const action: Action = {
-    type: descriptor.actionId as keyof ActionRecord,
-    context: actionContext,
-    // Payload is temporarily set to the raw token; resolved below after modifiers run.
-    payload: descriptor.payload as ActionRecord[keyof ActionRecord],
-  };
-
-  // Step 4: run modifiers — each receives the mutable action so it can enrich meta.
-  for (const modifier of descriptor.modifiers) {
-    if (modifier === 'once') continue; // handled above
-    const handler = modifierRegistry.get(modifier);
-    if (!handler) {
-      logger_.accident('handleDelegatedEvent__', 'unknown_modifier', {eventType, modifier, attributeValue, descriptor});
-      return; // unknown modifier — abort to avoid silent misbehavior
-    }
-    if (handler(event, actionElement, action) === false) return;
-  }
-
-  // Step 5: resolve payload — replace raw token with the actual value.
-  // If the raw token starts with '$', look it up in the payload resolver registry.
-  // Otherwise treat it as a literal string payload.
-  if (descriptor.payload) {
-    const resolver = payloadRegistry.get(descriptor.payload);
-    if (resolver) {
-      // Cast needed: payload is typed as ActionRecord[K] but we're building generically.
-      (action as {payload: unknown}).payload = resolver(event, actionElement);
-    }
-    // else: keep the literal string already set on action.payload
-  } else {
-    // No payload token in the attribute — set to undefined.
-    (action as {payload: unknown}).payload = undefined;
-  }
-
-  // Step 6: dispatch the fully assembled Action object.
-  internalChannel_.dispatch(action.type, action);
-}
-
-// ─── Setup ────────────────────────────────────────────────────────────────────
-
-/**
- * The set of event types currently delegated to `document.body`.
- *
- * Tracked so that `setupActionDelegation` is idempotent — calling it multiple
- * times with the same event types does not register duplicate listeners.
- *
- * @internal
- */
-const delegatedEventTypes__ = new Set<string>();
-
-/**
- * Default DOM event types that cover the vast majority of interactive elements.
- *
- * - `click` — buttons, links, checkboxes, custom interactive elements
- * - `submit` — form submission
- * - `input` — live text input, range sliders
- * - `change` — select boxes, checkboxes, radio buttons (fires on commit)
- *
- * Pass additional types to `setupActionDelegation` when your app uses other
- * events (e.g. `'keydown'`, `'pointerup'`).
- */
-export const DEFAULT_DELEGATED_EVENTS: readonly string[] = ['click', 'submit', 'input', 'change'];
-
-/**
- * Registers global event delegation for `on-<eventType>` attributes.
- *
- * Attaches a single `capture`-phase listener on `document.body` for each
- * event type in `eventTypes`. All processing — context resolution, modifier
- * execution, payload resolution, and `dispatchAction` — happens inside that
- * one handler.
- *
- * **Call this once at application bootstrap**, before any user interaction.
- * Subsequent calls with the same event types are no-ops (idempotent).
- *
- * ### Why `capture: true`?
- *
- * Capture-phase listeners fire before bubble-phase listeners and also catch
- * events that do not bubble (e.g. `focus`, `blur`). This ensures the delegation
- * handler always runs, even when a child element calls `stopPropagation()`.
- *
- * ### Dynamic content
- *
- * Because the listener lives on `document.body`, any element added to the DOM
- * after this call — via `innerHTML`, `lit-html`, a framework renderer, or
- * server-sent HTML — is automatically covered. No re-bootstrap is needed.
- *
- * ### Context scoping
- *
- * Wrap a group of elements in a `[action-context]` container to scope their
- * actions. The delegation handler automatically resolves the nearest ancestor
- * and attaches its value to `action.context`:
- *
- * ```html
- * <section action-context="product-list">
- *   <button on-click="ui_add_to_cart:42">Add</button>
- * </section>
- * ```
- *
- * ```ts
- * onAction('ui_add_to_cart', (action) => {
- *   console.log(action.context); // 'product-list'
- * });
- * ```
- *
- * @param eventTypes - Event types to delegate. Defaults to `DEFAULT_DELEGATED_EVENTS`.
- *
- * @example — minimal bootstrap
- * ```ts
- * import {setupActionDelegation, onAction} from '@alwatr/action';
- *
- * // One call activates the entire page.
- * setupActionDelegation();
- *
- * onAction('ui_open_drawer', (action) => openDrawer(action.payload));
- * ```
- *
- * @example — with extra event types
- * ```ts
- * import {setupActionDelegation, DEFAULT_DELEGATED_EVENTS} from '@alwatr/action';
- *
- * setupActionDelegation([...DEFAULT_DELEGATED_EVENTS, 'keydown', 'pointerup']);
- * ```
- */
-export function setupActionDelegation(eventTypes: readonly string[] = DEFAULT_DELEGATED_EVENTS): void {
-  logger_.logMethodArgs?.('setupActionDelegation', {eventTypes});
-
-  for (const eventType of eventTypes) {
-    if (delegatedEventTypes__.has(eventType)) continue; // already registered — skip
-    delegatedEventTypes__.add(eventType);
-    // capture: true — fires before bubble-phase listeners and catches non-bubbling events.
-    document.body.addEventListener(eventType, handleDelegatedEvent__, {capture: true});
-  }
-}
-
-/**
- * Removes all global delegation listeners registered by `setupActionDelegation`.
- *
- * Useful in test environments where each test needs a clean slate, or in
- * micro-frontend setups where a sub-app is unmounted.
- *
- * After calling this, `setupActionDelegation` can be called again to re-register.
- */
-export function teardownActionDelegation(): void {
-  logger_.logMethod?.('teardownActionDelegation');
-  for (const eventType of delegatedEventTypes__) {
-    document.body.removeEventListener(eventType, handleDelegatedEvent__, {capture: true});
-  }
-  delegatedEventTypes__.clear();
-  descriptorCache__.clear();
-}

package/src/lib_.ts

@@ -1,27 +0,0 @@
-import {createLogger} from '@alwatr/logger';
-import {createChannelSignal} from '@alwatr/signal';
-import type {Action} from './type.js';
-
-/**
- * Module-scoped logger for `@alwatr/action`.
- * Scoped to `'alwatr-action'` so log lines are easy to filter in the console.
- *
- * @internal
- */
-export const logger_ = createLogger('alwatr-action');
-
-/**
- * The internal action channel — a `ChannelSignal` keyed by action `type`.
- *
- * Each message on this channel is a full `Action` object (AFSA), not just a
- * raw payload. Subscribers registered via `onAction('foo', handler)` receive
- * the entire `Action<'foo'>` so they have access to `context`, `meta`, and
- * `payload` in one place.
- *
- * Uses `ChannelSignal` for O(1) routing: dispatching action `'A'` performs a
- * single `Map.get('A')` lookup and invokes only the handlers registered for
- * that specific type — never handlers for `'B'`, `'C'`, etc.
- *
- * @internal — not part of the public API; use `onAction` / `dispatchAction` instead.
- */
-export const internalChannel_ = createChannelSignal<Record<string, Action>>({name: 'alwatr-action'});

package/src/method.ts

@@ -1,219 +0,0 @@
-import type {Awaitable, VoidFunc} from '@alwatr/type-helper';
-import type {SubscribeResult} from '@alwatr/signal';
-
-import {internalChannel_, logger_} from './lib_.js';
-import {modifierRegistry, payloadRegistry} from './registry_.js';
-import type {Action, ActionRecord, DispatchParam, ModifierHandler, PayloadResolver} from './type.js';
-
-// ─── Core Action API ──────────────────────────────────────────────────────────
-
-/**
- * Subscribes to a named action dispatched anywhere in the application.
- *
- * `type` must be a key of `ActionRecord`. The handler receives the full
- * `Action<K>` object — giving access to `payload`, `context`, and `meta`
- * in one place. No manual generic annotation is needed; the compiler infers
- * the correct `payload` type from `ActionRecord`:
- *
- * ```ts
- * // ActionRecord declares: 'ui_add_to_cart': {productId: number; qty: number}
- * onAction('ui_add_to_cart', (action) => {
- *   cartService.add(action.payload.productId, action.payload.qty); // fully typed
- *   console.log(action.context); // e.g. 'product-list' (from DOM) or undefined
- * });
- * ```
- *
- * Passing an action name not declared in `ActionRecord` is a **compile error**.
- * Register new actions by extending `ActionRecord` via declaration merging:
- *
- * ```ts
- * // src/action-record.ts
- * declare module '@alwatr/action' {
- *   interface ActionRecord {
- *     'ui_open_drawer': string;
- *   }
- * }
- * ```
- *
- * Internally delegates to `ChannelSignal.on()` for **O(1) routing** — dispatching
- * action `'A'` never invokes handlers registered for action `'B'`.
- *
- * @param type    - A key of `ActionRecord`.
- * @param handler - Callback invoked with the full `Action<K>` on each dispatch.
- * @returns A `SubscribeResult` with an `unsubscribe()` method for cleanup.
- *
- * @example
- * ```ts
- * import {onAction} from '@alwatr/action';
- *
- * const sub = onAction('ui_page_ready', (action) => {
- *   router.setPage(action.payload); // payload: string — inferred from ActionRecord
- * });
- *
- * sub.unsubscribe(); // stop listening when no longer needed
- * ```
- */
-export function onAction<K extends keyof ActionRecord>(
-  type: K | K[],
-  handler: (action: Action<K>) => Awaitable<void>,
-): SubscribeResult {
-  logger_.logMethodArgs?.('onAction', {type});
-  // The internal channel stores Action<any>; we cast to Action<K> here because
-  // the channel key guarantees the type matches — only Action<K> objects are
-  // ever dispatched under key K.
-  if (Array.isArray(type)) {
-    const typeList = type as K[];
-    const unsubscribeList: VoidFunc[] = [];
-    for (const type_ of typeList) {
-      unsubscribeList.push(internalChannel_.on(type_, handler as (action: Action) => Awaitable<void>).unsubscribe);
-    }
-    return {
-      unsubscribe: () => {
-        for (const unsubscribe of unsubscribeList) {
-          unsubscribe();
-        }
-        unsubscribeList.length = 0;
-      },
-    };
-  }
-  // else single type
-  return internalChannel_.on(type, handler as (action: Action) => Awaitable<void>);
-}
-
-/**
- * Dispatches an action to all `onAction` subscribers with a matching `type`.
- *
- * Accepts a full `Action<K>` object. The `payload` field is automatically
- * typed from `ActionRecord[K]` — passing the wrong shape is a **compile error**:
- *
- * ```ts
- * // ActionRecord declares: 'ui_add_to_cart': {productId: number; qty: number}
- * dispatchAction({type: 'ui_add_to_cart', payload: {productId: 42, qty: 1}}); // ✅
- * dispatchAction({type: 'ui_add_to_cart', payload: 'wrong'});                  // ❌ compile error
- * dispatchAction({type: 'unknown_action', payload: 'x'});                   // ❌ compile error
- * ```
- *
- * The `context` and `meta` fields are optional. When dispatching from code
- * (not from the DOM), omit `context` — it is only meaningful for DOM-originated
- * actions where an `[action-context]` ancestor exists.
- *
- * Use `dispatchAction` when triggering an action from code — e.g. after an
- * async operation, from a service layer, or in tests. For DOM-driven actions,
- * use the `on-<eventType>` HTML attribute with `setupActionDelegation`.
- *
- * @param action - A full `Action<K>` object with at minimum `type` and `payload`.
- *
- * @example — with payload (code-originated action — no 'ui_' prefix)
- * ```ts
- * import {dispatchAction} from '@alwatr/action';
- *
- * dispatchAction({type: 'navigate', payload: '/dashboard'});
- * dispatchAction({type: 'upload_complete', payload: fileId});
- * ```
- *
- * @example — void payload (payload field is optional and can be omitted entirely)
- * ```ts
- * dispatchAction({type: 'auth_expired'});
- * // or explicitly:
- * dispatchAction({type: 'auth_expired', payload: undefined});
- * ```
- *
- * @example — with context and meta
- * ```ts
- * dispatchAction({
- *   type: 'slider_change',
- *   payload: 75,
- *   context: 'volume_slider',
- *   meta: {traceId: 'abc-123'},
- * });
- * ```
- */
-export function dispatchAction<K extends keyof ActionRecord>(action: DispatchParam<K>): void {
-  logger_.logMethodArgs?.('dispatchAction', action);
-  internalChannel_.dispatch(action.type, action as Action<K>);
-}
-
-// ─── Extension API ────────────────────────────────────────────────────────────
-
-/**
- * Registers a custom modifier that can be used in `on-<eventType>` attribute syntax.
- *
- * A modifier is a comma-separated token placed after the `;` separator
- * (e.g. `on-click="action-id; mymod"`). Its handler runs before the payload is
- * resolved and the action is dispatched. Returning `false` cancels the dispatch.
- *
- * The handler also receives the **mutable** `action` object being built, so it
- * can attach data to `action.meta` before the action reaches subscribers.
- *
- * Built-in modifiers (`prevent`, `validate`, `once`) 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 special characters).
- * @param handler - A `ModifierHandler` receiving `(event, element, action)`.
- *
- * @example — a `confirm` modifier that shows a browser dialog
- * ```ts
- * import {registerModifier} from '@alwatr/action';
- *
- * registerModifier('confirm', () => window.confirm('Are you sure?'));
- * ```
- * ```html
- * <button on-click="ui_delete_item:42; confirm">Delete</button>
- * ```
- *
- * @example — a `trace` modifier that stamps a trace ID into meta
- * ```ts
- * registerModifier('trace', (_event, _element, action) => {
- *   action.meta ??= {};
- *   action.meta['traceId'] = crypto.randomUUID();
- *   return true;
- * });
- * ```
- */
-export function registerModifier(name: string, handler: ModifierHandler): void {
-  logger_.logMethodArgs?.('registerModifier', {name});
-  if (modifierRegistry.has(name)) {
-    logger_.accident('registerModifier', 'modifier_already_registered', {name});
-  }
-  modifierRegistry.set(name, handler);
-}
-
-/**
- * Registers a custom payload resolver that can be used in `on-<eventType>` attribute syntax.
- *
- * A payload resolver is a colon-prefixed token in the attribute value
- * (e.g. `on-click="action-id:$mytoken"`). Its function is called at dispatch time
- * with the DOM event and the element. The return value becomes the `payload`
- * field of the `Action` object passed to `onAction` subscribers.
- *
- * Built-in resolvers (`$value`, `$formdata`, `$checked`) 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 - A `PayloadResolver` receiving `(event, element)`.
- *
- * @example — a `$data-id` resolver that reads a data attribute
- * ```ts
- * import {registerPayloadResolver} from '@alwatr/action';
- *
- * registerPayloadResolver('$data-id', (_event, element) => {
- *   return (element as HTMLElement).dataset.id ?? null;
- * });
- * ```
- * ```html
- * <button on-click="ui_select_item:$data-id" data-id="42">Select</button>
- * ```
- */
-export function registerPayloadResolver(name: string, resolver: PayloadResolver): void {
-  logger_.logMethodArgs?.('registerPayloadResolver', {name});
-  if (payloadRegistry.has(name)) {
-    logger_.accident('registerPayloadResolver', 'payload_resolver_already_registered', {name});
-  }
-  payloadRegistry.set(name, resolver);
-}