@alwatr/action 9.26.0 → 9.28.0

package/src/action-service.ts

@@ -0,0 +1,397 @@
+import {createLogger} from '@alwatr/logger';
+import {createChannelSignal} from '@alwatr/signal';
+import type {SubscribeResult} from '@alwatr/signal';
+import type {Awaitable, VoidFunc} from '@alwatr/type-helper';
+
+import type {Action, ActionRecord, DispatchParam, ModifierHandler, PayloadResolver} from './type.js';
+
+/**
+ * Parsed representation of an action attribute descriptor.
+ * @internal
+ */
+interface ActionDescriptor {
+  readonly modifiers: ReadonlySet<string>;
+  readonly actionId: string;
+  readonly payload: string | undefined;
+}
+
+/**
+ * Regex parser for the `on-<eventType>` attribute syntax.
+ * Syntax: `actionId[:payload][; modifier1,modifier2,...]`
+ */
+const syntaxRegex = /^(ui_[a-z0-9_-]+)(?::([^;]+))?(?:;\s*([a-z0-9_,-]+))?$/;
+
+/**
+ * Service to manage declarative DOM actions, programmatic dispatch,
+ * modifiers, payload resolvers, and global event delegation.
+ *
+ * @example
+ * ```ts
+ * import {ActionService} from '@alwatr/action';
+ *
+ * const customActionService = new ActionService();
+ * ```
+ */
+export class ActionService {
+  /**
+   * Default DOM event types that cover the vast majority of interactive elements.
+   */
+  static readonly DEFAULT_DELEGATED_EVENTS: readonly string[] = ['click', 'submit', 'input', 'change'];
+
+  protected readonly logger_ = createLogger('action-service');
+
+  /**
+   * Internal ChannelSignal used for routing dispatched actions.
+   * @protected
+   */
+  protected readonly internalChannel_ = createChannelSignal<Record<string, Action>>({name: 'action-service'});
+
+  /**
+   * Registry mapping custom modifiers to their handlers.
+   * @protected
+   */
+  protected readonly modifierRegistry_ = new Map<string, ModifierHandler>();
+
+  /**
+   * Registry mapping custom payload resolvers to their functions.
+   * @protected
+   */
+  protected readonly payloadRegistry_ = new Map<string, PayloadResolver>();
+
+  /**
+   * Cache of parsed action descriptors to prevent redundant regex evaluation.
+   * @protected
+   */
+  protected readonly descriptorCache_ = new Map<string, ActionDescriptor | null>();
+
+  /**
+   * Tracked event types currently delegated to `document.body`.
+   * @protected
+   */
+  protected readonly delegatedEventTypes_ = new Set<string>();
+
+  /**
+   * Bound delegation handler for add/removeEventListener.
+   * @private
+   */
+  private readonly handleDelegatedEventBound__ = this.handleDelegatedEvent_.bind(this);
+
+  constructor() {
+    this.logger_.logMethod?.('constructor');
+    this.registerDefaultModifiersAndResolvers__();
+  }
+
+  /**
+   * Subscribes to a named action dispatched anywhere in the application.
+   *
+   * @template K - A key of ActionRecord.
+   * @param type    - Action type or array of action types to subscribe to.
+   * @param handler - Callback invoked with the full Action object.
+   * @returns SubscribeResult containing an `unsubscribe` method.
+   *
+   * @example
+   * ```ts
+   * // Subscribe to a single action
+   * const sub1 = actionService.on('ui_open_drawer', (action) => {
+   *   console.log(action.payload);
+   * });
+   *
+   * // Subscribe to multiple action types
+   * const sub2 = actionService.on(['ui_open_drawer', 'ui_close_drawer'], (action) => {
+   *   console.log(action.type, action.payload);
+   * });
+   * ```
+   */
+  on<K extends keyof ActionRecord>(type: K | K[], handler: (action: Action<K>) => Awaitable<void>): SubscribeResult {
+    this.logger_.logMethodArgs?.('on', {type});
+    if (Array.isArray(type)) {
+      const typeList = type as K[];
+      const unsubscribeList: VoidFunc[] = [];
+      for (const type_ of typeList) {
+        unsubscribeList.push(
+          this.internalChannel_.on(type_, handler as (action: Action) => Awaitable<void>).unsubscribe,
+        );
+      }
+      return {
+        unsubscribe: () => {
+          this.logger_.logMethod?.('unsubscribe');
+          for (const unsubscribe of unsubscribeList) {
+            unsubscribe();
+          }
+          unsubscribeList.length = 0;
+        },
+      };
+    }
+    return this.internalChannel_.on(type, handler as (action: Action) => Awaitable<void>);
+  }
+
+  /**
+   * Dispatches an action to all subscribers matching `action.type`.
+   *
+   * @template K - A key of ActionRecord.
+   * @param action - Action object containing `type` and `payload`.
+   *
+   * @example
+   * ```ts
+   * // Dispatches a typed action (payload is required)
+   * actionService.dispatch({type: 'upload_complete', payload: 'file-123'});
+   *
+   * // Dispatches a void action (payload can be omitted)
+   * actionService.dispatch({type: 'auth_expired'});
+   * ```
+   */
+  dispatch<K extends keyof ActionRecord>(action: DispatchParam<K>): void {
+    this.logger_.logMethodArgs?.('dispatch', action);
+    this.internalChannel_.dispatch(action.type, action as Action<K>);
+  }
+
+  /**
+   * Registers a custom modifier to enrich or filter actions before dispatch.
+   *
+   * @param name    - Modifier name (lowercase, alphanumeric).
+   * @param handler - Function called when modifier is invoked.
+   *
+   * @example
+   * ```ts
+   * actionService.registerModifier('trace', (_event, _element, action) => {
+   *   action.meta ??= {};
+   *   action.meta['time'] = Date.now();
+   *   return true;
+   * });
+   * ```
+   */
+  registerModifier(name: string, handler: ModifierHandler): void {
+    this.logger_.logMethodArgs?.('registerModifier', {name});
+    if (this.modifierRegistry_.has(name)) {
+      this.logger_.accident('registerModifier', 'modifier_already_registered', {name});
+      return;
+    }
+    this.modifierRegistry_.set(name, handler);
+  }
+
+  /**
+   * Registers a custom payload resolver to map DOM state to action payload.
+   *
+   * @param name     - Resolver token (by convention starting with `$`).
+   * @param resolver - Function yielding payload from the event and element.
+   *
+   * @example
+   * ```ts
+   * actionService.registerPayloadResolver('$data-id', (_event, element) => {
+   *   return element.dataset.id;
+   * });
+   * ```
+   */
+  registerPayloadResolver(name: string, resolver: PayloadResolver): void {
+    this.logger_.logMethodArgs?.('registerPayloadResolver', {name});
+    if (this.payloadRegistry_.has(name)) {
+      this.logger_.accident('registerPayloadResolver', 'payload_resolver_already_registered', {name});
+      return;
+    }
+    this.payloadRegistry_.set(name, resolver);
+  }
+
+  /**
+   * Registers global event delegation listeners on `document.body`.
+   *
+   * @param eventTypes - List of event types to delegate. Defaults to ActionService.DEFAULT_DELEGATED_EVENTS.
+   *
+   * @example
+   * ```ts
+   * actionService.setupDelegation();
+   * ```
+   */
+  setupDelegation(eventTypes: readonly string[] = ActionService.DEFAULT_DELEGATED_EVENTS): void {
+    this.logger_.logMethodArgs?.('setupDelegation', {eventTypes});
+    if (typeof document === 'undefined' || !document.body) {
+      this.logger_.incident?.('setupDelegation', 'document_body_not_found');
+      return;
+    }
+
+    for (const eventType of eventTypes) {
+      if (this.delegatedEventTypes_.has(eventType)) continue;
+      this.delegatedEventTypes_.add(eventType);
+      document.body.addEventListener(eventType, this.handleDelegatedEventBound__, {capture: true});
+    }
+  }
+
+  /**
+   * Unregisters all global event delegation listeners.
+   *
+   * @example
+   * ```ts
+   * actionService.teardownDelegation();
+   * ```
+   */
+  teardownDelegation(): void {
+    this.logger_.logMethod?.('teardownDelegation');
+    if (typeof document === 'undefined' || !document.body) {
+      return;
+    }
+    for (const eventType of this.delegatedEventTypes_) {
+      document.body.removeEventListener(eventType, this.handleDelegatedEventBound__, {capture: true});
+    }
+    this.delegatedEventTypes_.clear();
+    this.descriptorCache_.clear();
+  }
+
+  /**
+   * Parses attribute values into action descriptor, utilizing the internal cache.
+   * @protected
+   */
+  protected parseDescriptor_(attributeValue: string): ActionDescriptor | null {
+    this.logger_.logMethodArgs?.('parseDescriptor_', {attributeValue});
+
+    const cached = this.descriptorCache_.get(attributeValue);
+    if (cached !== undefined) return cached;
+
+    const match = attributeValue.match(syntaxRegex);
+    if (!match) {
+      this.logger_.accident('parseDescriptor_', 'invalid_syntax', {attributeValue});
+      this.descriptorCache_.set(attributeValue, null);
+      return null;
+    }
+
+    const actionId = match[1]!;
+    const payload = match[2];
+    const modifierString = match[3];
+    const modifiers = modifierString ? new Set(modifierString.split(',').filter(Boolean)) : new Set<string>();
+
+    const descriptor: ActionDescriptor = {modifiers, actionId, payload};
+    this.descriptorCache_.set(attributeValue, descriptor);
+    return descriptor;
+  }
+
+  /**
+   * Global event delegation handler.
+   * @protected
+   */
+  protected handleDelegatedEvent_(event: Event): void {
+    const eventType = event.type;
+    this.logger_.logMethodArgs?.('handleDelegatedEvent_', {eventType});
+
+    const target = event.target as Element | null;
+    if (!target) return;
+
+    const actionAttrib = `on-${eventType}`;
+    const actionElement = target.closest?.(`[${actionAttrib}]`);
+    if (!actionElement) return;
+
+    const attributeValue = actionElement.getAttribute?.(actionAttrib)?.trim();
+    if (!attributeValue) {
+      this.logger_.accident('handleDelegatedEvent_', 'empty_attribute', {eventType, actionElement});
+      return;
+    }
+
+    if (!(actionElement instanceof HTMLElement)) {
+      this.logger_.accident('handleDelegatedEvent_', 'target_not_html_element', {eventType, actionElement});
+      return;
+    }
+
+    const descriptor = this.parseDescriptor_(attributeValue);
+    if (!descriptor) return;
+
+    this.logger_.logMethodArgs?.('handleDelegatedEvent_.action', {eventType, descriptor});
+
+    if (descriptor.modifiers.has('once')) {
+      actionElement.removeAttribute(actionAttrib);
+    }
+
+    const actionContext = actionElement.closest('[action-context]')?.getAttribute('action-context') ?? undefined;
+
+    const action: Action = {
+      type: descriptor.actionId as keyof ActionRecord,
+      context: actionContext,
+      payload: descriptor.payload as ActionRecord[keyof ActionRecord],
+    };
+
+    for (const modifier of descriptor.modifiers) {
+      if (modifier === 'once') continue;
+      const handler = this.modifierRegistry_.get(modifier);
+      if (!handler) {
+        this.logger_.accident('handleDelegatedEvent_', 'unknown_modifier', {
+          eventType,
+          modifier,
+          attributeValue,
+          descriptor,
+        });
+        return;
+      }
+      try {
+        if (handler(event, actionElement, action) === false) return;
+      } catch (error) {
+        this.logger_.accident('handleDelegatedEvent_', 'modifier_execution_failed', {
+          modifier,
+          error,
+        });
+        return;
+      }
+    }
+
+    if (descriptor.payload) {
+      const resolver = this.payloadRegistry_.get(descriptor.payload);
+      if (resolver) {
+        try {
+          (action as {payload: unknown}).payload = resolver(event, actionElement);
+        } catch (error) {
+          this.logger_.accident('handleDelegatedEvent_', 'payload_resolver_failed', {
+            resolver: descriptor.payload,
+            error,
+          });
+          return;
+        }
+      }
+    } else {
+      (action as {payload: unknown}).payload = undefined;
+    }
+
+    this.internalChannel_.dispatch(action.type, action);
+  }
+
+  /**
+   * Registers default modifiers and resolvers.
+   * @private
+   */
+  private registerDefaultModifiersAndResolvers__(): void {
+    this.logger_.logMethod?.('registerDefaultModifiersAndResolvers__');
+
+    // Built-in modifiers
+    this.registerModifier('prevent', (event) => {
+      event.preventDefault();
+      return true;
+    });
+
+    this.registerModifier('validate', (_event, element) => {
+      const form = element instanceof HTMLFormElement ? element : element.closest('form');
+      if (!form) return false;
+      return form.checkValidity();
+    });
+
+    // Built-in resolvers
+    this.registerPayloadResolver('$value', (_event, element) => {
+      return 'value' in element ? (element as {value: unknown}).value : null;
+    });
+
+    this.registerPayloadResolver('$formdata', (_event, element) => {
+      const form = element instanceof HTMLFormElement ? element : element.closest('form');
+      return form ? Object.fromEntries(new FormData(form)) : null;
+    });
+
+    this.registerPayloadResolver('$checked', (_event, element) => {
+      return 'checked' in element ? (element as HTMLInputElement).checked : null;
+    });
+  }
+}
+
+/**
+ * Singleton instance of the ActionService.
+ * Ready for immediate use.
+ *
+ * @example
+ * ```ts
+ * import {actionService} from '@alwatr/action';
+ *
+ * actionService.setupDelegation();
+ * ```
+ */
+export const actionService = new ActionService();

package/src/main.ts

@@ -1,100 +1,147 @@
+import type {SubscribeResult} from '@alwatr/signal';
+import type {Awaitable} from '@alwatr/type-helper';
+
+import {actionService, ActionService} from './action-service.js';
+import type {Action, ActionRecord, DispatchParam, ModifierHandler, PayloadResolver} from './type.js';
+
+export {actionService, ActionService};
+export type {Action, ActionRecord, DispatchParam, ModifierHandler, PayloadResolver};
+
 /**
- * @alwatr/action — Declarative DOM action-dispatch for Unidirectional Data Flow.
+ * Default DOM event types that cover the vast majority of interactive elements.
  *
- * Implements the **Alwatr Flux Standard Action (AFSA)** pattern: every action
- * flowing through the bus is a single, typed `Action<K>` object carrying
- * `type`, `payload`, `context`, and optional `meta`. This replaces the previous
- * two-argument `(id, payload)` API with a unified structure that is extensible
- * without breaking existing call sites.
- *
- * ## Activating `on-<eventType>` attributes
+ * - `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)
+ */
+export const DEFAULT_DELEGATED_EVENTS = ActionService.DEFAULT_DELEGATED_EVENTS;
+
+/**
+ * Subscribes to a named action dispatched anywhere in the application.
  *
- * Call `setupActionDelegation()` once at bootstrap. A single capture-phase
- * listener on `document.body` handles every `on-click`, `on-submit`, etc. element —
- * including elements added dynamically after bootstrap — with O(1) initialization cost.
+ * @template K - A key of ActionRecord.
+ * @param type    - Action type or array of action types to subscribe to.
+ * @param handler - Callback invoked with the full Action object.
+ * @returns SubscribeResult containing an `unsubscribe` method.
  *
+ * @example
  * ```ts
- * import {setupActionDelegation, onAction} from '@alwatr/action';
+ * import {onAction} from '@alwatr/action';
  *
- * setupActionDelegation();
- * onAction('ui_open_drawer', (action) => openDrawer(action.payload));
+ * // Subscribe to multiple action types
+ * const sub = onAction(['ui_open_drawer', 'ui_close_drawer'], (action) => {
+ *   console.log(action.type, action.payload);
+ * });
+ * sub.unsubscribe();
  * ```
  *
- * ## Attribute syntax
- *
- * ```
- * on-<eventType>="actionId[:payload][; modifier1,modifier2,…]"
- * ```
+ * @deprecated Use `actionService.on` instead.
+ */
+export function onAction<K extends keyof ActionRecord>(
+  type: K | K[],
+  handler: (action: Action<K>) => Awaitable<void>,
+): SubscribeResult {
+  return actionService.on(type, handler);
+}
+
+/**
+ * Dispatches an action to all subscribers matching `action.type`.
  *
- * ```html
- * <button on-click="ui_open_drawer:main">Open</button>
- * <input on-input="ui_search_query:$value" />
- * <form on-submit="ui_submit_form:$formdata; prevent,validate" novalidate>…</form>
- * ```
+ * @template K - A key of ActionRecord.
+ * @param action - Action object containing `type` and `payload`.
  *
- * ## Context scoping
+ * @example
+ * ```ts
+ * import {dispatchAction} from '@alwatr/action';
  *
- * Wrap elements in an `[action-context]` container to scope their actions.
- * The delegation handler resolves the nearest ancestor and attaches its value
- * to `action.context`:
+ * // Dispatches a typed action (payload is required)
+ * dispatchAction({type: 'upload_complete', payload: 'file-123'});
  *
- * ```html
- * <section action-context="product-list">
- *   <button on-click="ui_add_to_cart:42">Add</button>
- * </section>
+ * // Dispatches a void action (payload can be omitted)
+ * dispatchAction({type: 'auth_expired'});
  * ```
  *
+ * @deprecated Use `actionService.dispatch` instead.
+ */
+export function dispatchAction<K extends keyof ActionRecord>(action: DispatchParam<K>): void {
+  actionService.dispatch(action);
+}
+
+/**
+ * Registers global event delegation listeners on `document.body`.
+ *
+ * @param eventTypes - List of event types to delegate. Defaults to DEFAULT_DELEGATED_EVENTS.
+ *
+ * @example
  * ```ts
- * onAction('ui_add_to_cart', (action) => {
- *   console.log(action.context); // 'product-list'
- *   console.log(action.payload); // '42'
- * });
- * ```
+ * import {setupActionDelegation} from '@alwatr/action';
  *
- * ## Programmatic dispatch
+ * setupActionDelegation();
+ * ```
  *
- * Code-originated actions should not use the `ui_` prefix — that prefix is
- * reserved for DOM-originated actions dispatched via HTML attributes.
+ * @deprecated Use `actionService.setupDelegation` instead.
+ */
+export function setupActionDelegation(eventTypes?: readonly string[]): void {
+  actionService.setupDelegation(eventTypes);
+}
+
+/**
+ * Unregisters all global event delegation listeners.
  *
+ * @example
  * ```ts
- * import {dispatchAction} from '@alwatr/action';
+ * import {teardownActionDelegation} from '@alwatr/action';
  *
- * dispatchAction({type: 'navigate', payload: '/dashboard'});
+ * teardownActionDelegation();
  * ```
  *
- * ## Registering typed actions
+ * @deprecated Use `actionService.teardownDelegation` instead.
+ */
+export function teardownActionDelegation(): void {
+  actionService.teardownDelegation();
+}
+
+/**
+ * Registers a custom modifier to enrich or filter actions before dispatch.
  *
- * Extend `ActionRecord` via declaration merging to get full type safety:
+ * @param name    - Modifier name (lowercase, alphanumeric).
+ * @param handler - Function called when modifier is invoked.
  *
+ * @example
  * ```ts
- * // src/action-record.ts
- * declare module '@alwatr/action' {
- *   interface ActionRecord {
- *     // UI-originated actions — must start with 'ui_'
- *     'ui_open_drawer': string;
- *     'ui_add_to_cart': {productId: number; qty: number};
- *     'ui_logout': void;
- *
- *     // Code-originated actions — no 'ui_' prefix
- *     'upload_complete': string;
- *     'auth_expired': void;
- *   }
- * }
+ * import {registerModifier} from '@alwatr/action';
+ *
+ * registerModifier('trace', (_event, _element, action) => {
+ *   action.meta ??= {};
+ *   action.meta['time'] = Date.now();
+ *   return true;
+ * });
  * ```
  *
- * ## Public API
+ * @deprecated Use `actionService.registerModifier` instead.
+ */
+export function registerModifier(name: string, handler: ModifierHandler): void {
+  actionService.registerModifier(name, handler);
+}
+
+/**
+ * Registers a custom payload resolver to map DOM state to action payload.
+ *
+ * @param name     - Resolver token (by convention starting with `$`).
+ * @param resolver - Function yielding payload from the event and element.
  *
- * - `Action`          — the AFSA object interface (`type`, `payload`, `context`, `meta`)
- * - `ActionRecord`    — extend this interface to register typed actions
- * - `setupActionDelegation` / `teardownActionDelegation` — global delegation lifecycle
- * - `DEFAULT_DELEGATED_EVENTS` — default event types covered by delegation
- * - `onAction` / `dispatchAction` — subscribe to and dispatch named actions
- * - `registerModifier` / `registerPayloadResolver` — extend the attribute syntax
+ * @example
+ * ```ts
+ * import {registerPayloadResolver} from '@alwatr/action';
  *
- * ## Page identity
+ * registerPayloadResolver('$data-id', (_event, element) => {
+ *   return element.dataset.id;
+ * });
+ * ```
  *
- * For page-ready signals in SSG/SSR apps, use `@alwatr/page-ready` instead.
+ * @deprecated Use `actionService.registerPayloadResolver` instead.
  */
-export * from './delegate.js';
-export * from './method.js';
-export type * from './type.js';
+export function registerPayloadResolver(name: string, resolver: PayloadResolver): void {
+  actionService.registerPayloadResolver(name, resolver);
+}