@alwatr/action 9.11.2

package/src/directive.ts

@@ -0,0 +1,197 @@
+import {lazyDirective, Directive} from '@alwatr/directive';
+import {modifierRegistry, payloadRegistry} from './registry.js';
+import {dispatchAction} from './method.js';
+
+// ─── Attribute Syntax Parser ──────────────────────────────────────────────────
+
+/**
+ * Regex that parses the `on-action` attribute value into its three segments.
+ *
+ * Full syntax: `eventType[.modifier…]->actionId[:payload]`
+ *
+ * | Capture group | Matches                                     | Example              |
+ * | ------------- | ------------------------------------------- | -------------------- |
+ * | 1             | Event type + optional dot-chained modifiers | `click.prevent.once` |
+ * | 2             | Action identifier                           | `open-drawer`        |
+ * | 3             | Optional payload token or literal           | `main` / `$value`    |
+ *
+ * @example
+ * ```
+ * 'click.prevent.once->open-drawer:main' → ['click.prevent.once', 'open-drawer', 'main']
+ * 'input->search-query:$value'           → ['input',              'search-query', '$value']
+ * 'submit.prevent->submit-form'          → ['submit.prevent',     'submit-form',  undefined]
+ * ```
+ */
+const syntaxRegex = /^([a-z0-9.-]+)->([a-z0-9-]+)(?::(.+))?$/;
+
+// ─── Directive Class ──────────────────────────────────────────────────────────
+
+/**
+ * Directive that bridges a DOM event to a typed action signal.
+ *
+ * Activated automatically by the `on-action` HTML attribute when
+ * `registerActionDirective()` has been called before `bootstrapDirectives()`.
+ * You rarely need to reference this class directly.
+ *
+ * **Attribute syntax**
+ * ```
+ * on-action="eventType[.modifier…]->actionId[:payload]"
+ * ```
+ *
+ * - `eventType` — any standard DOM event name (e.g. `click`, `input`, `submit`).
+ * - `modifier` — dot-chained tokens processed before dispatch
+ *   (`prevent`, `stop`, `validate`, `once`, `passive`, or custom).
+ * - `actionId` — the identifier passed to `onAction` subscribers.
+ * - `payload` — an optional literal string or a `$`-prefixed resolver token
+ *   (e.g. `$value`, `$formdata`, or custom).
+ *
+ * @example
+ * ```html
+ * <!-- Dispatches 'open-drawer' with payload 'settings' on click -->
+ * <button on-action="click->open-drawer:settings">Settings</button>
+ *
+ * <!-- Dispatches 'search-query' with the live input value on every keystroke -->
+ * <input on-action="input->search-query:$value" />
+ *
+ * <!-- Prevents default, validates, then dispatches 'submit-form' with all field values -->
+ * <form on-action="submit.prevent.validate->submit-form:$formdata" novalidate>…</form>
+ * ```
+ */
+export class ActionDirective extends Directive {
+  /**
+   * Parsed and validated representation of the `on-action` attribute value.
+   *
+   * Set during `init_()` after the attribute is successfully parsed against
+   * `syntaxRegex`. Remains `undefined` when the attribute value is invalid,
+   * which prevents `dispatch_` from running.
+   */
+  protected actionContext_?: {
+    /** The DOM event type to listen for (e.g. `'click'`, `'input'`). */
+    eventType: string;
+    /** Set of active modifier names (e.g. `{'prevent', 'once'}`). */
+    modifiers: ReadonlySet<string>;
+    /** The action identifier dispatched to `onAction` subscribers. */
+    actionId: string;
+    /** Raw payload token from the attribute (literal string or `$`-resolver key). */
+    payload?: string;
+  };
+
+  /**
+   * Parses the `on-action` attribute, validates modifiers, and attaches the
+   * DOM event listener.
+   *
+   * Called once by `Directive` after one macrotask following element discovery.
+   * If the attribute value is malformed or references an unknown modifier,
+   * an accident is logged and the directive becomes a no-op.
+   */
+  protected override init_(): void {
+    this.logger_.logMethodArgs?.('init_', {attributeValue: this.attributeValue});
+
+    const match = this.attributeValue.trim().match(syntaxRegex);
+
+    if (!match) {
+      this.logger_.accident('init_', 'invalid_syntax', {attributeValue: this.attributeValue});
+      return;
+    }
+
+    const [eventType, ...modifierList] = match[1].split('.');
+    const actionId = match[2];
+    const payload = match[3] as string | undefined;
+
+    if (!eventType) {
+      this.logger_.accident('init_', 'invalid_syntax', {attributeValue: this.attributeValue});
+      return;
+    }
+
+    // Validate every modifier token against the registry (built-in native
+    // options 'once' and 'passive' are handled separately by the listener).
+    const modifiers = new Set<string>();
+    for (const modifier of modifierList) {
+      if (!modifierRegistry.has(modifier) && modifier !== 'once' && modifier !== 'passive') {
+        this.logger_.accident('init_', 'invalid_modifier', {attributeValue: this.attributeValue, modifier});
+        return;
+      }
+      modifiers.add(modifier);
+    }
+
+    // 'prevent' and 'passive' are mutually exclusive: a passive listener cannot
+    // call preventDefault(). Log an accident but continue — 'prevent' wins.
+    if (modifiers.has('prevent') && modifiers.has('passive')) {
+      this.logger_.accident('init_', 'conflicting_modifiers_prevent_passive', {attributeValue: this.attributeValue});
+    }
+
+    this.actionContext_ = {eventType, modifiers, actionId, payload};
+
+    // Bind once so the same function reference is used for both add and remove.
+    const listenerOptions: AddEventListenerOptions = {
+      once: modifiers.has('once'),
+      // 'passive' is only meaningful when 'prevent' is absent.
+      passive: modifiers.has('passive') && !modifiers.has('prevent'),
+    };
+
+    const boundDispatch = this.dispatch_.bind(this);
+    this.element_.addEventListener(eventType, boundDispatch, listenerOptions);
+    // Register cleanup so the listener is removed when the directive is destroyed
+    // (e.g. when the element is removed from the DOM via autoDestructDirectives).
+    this.addDestroyHook(() => {
+      this.element_.removeEventListener(eventType, boundDispatch, listenerOptions);
+    });
+  }
+
+  /**
+   * DOM event handler: runs modifiers, resolves the payload, and dispatches
+   * the action signal.
+   *
+   * Execution order:
+   * 1. Each modifier in `actionContext_.modifiers` is called in insertion order.
+   *    If any returns `false` the method returns early — no action is dispatched.
+   * 2. The raw payload token is looked up in `payloadRegistry`. If a resolver
+   *    is found it is called and its return value replaces the token.
+   * 3. `dispatchAction` is called with the resolved payload.
+   *
+   * @param event - The DOM event that triggered this handler.
+   */
+  protected dispatch_(event: Event): void {
+    this.logger_.logMethodArgs?.('dispatch_', {eventType: event.type, actionId: this.actionContext_?.actionId});
+
+    const context = this.actionContext_!;
+
+    // Step 1 — run modifiers; any returning false cancels the dispatch.
+    for (const mod of context.modifiers) {
+      const handler = modifierRegistry.get(mod);
+      if (handler && handler.call(this, event) === false) return;
+    }
+
+    // Step 2 — resolve dynamic payload tokens (e.g. '$value', '$formdata').
+    let payload: unknown = context.payload;
+    if (payload) {
+      const resolver = payloadRegistry.get(payload as string);
+      if (resolver) payload = resolver.call(this, event);
+    }
+
+    // Step 3 — dispatch the action to all onAction subscribers.
+    dispatchAction(context.actionId, payload);
+  }
+}
+
+// ─── Lazy Registration ────────────────────────────────────────────────────────
+
+/**
+ * Registers `ActionDirective` under the `on-action` attribute name.
+ *
+ * This is a **lazy** registration: calling this function is the only way to
+ * opt-in to `on-action` support. If it is never called, the entire directive
+ * module (including `ActionDirective`) is tree-shaken from the bundle.
+ *
+ * Call it once, before `bootstrapDirectives()`, at your application entry point.
+ *
+ * @example
+ * ```ts
+ * import {registerActionDirective} from '@alwatr/action';
+ * import {bootstrapDirectives} from '@alwatr/directive';
+ *
+ * registerActionDirective();
+ * bootstrapDirectives();
+ * ```
+ */
+export const registerActionDirective = lazyDirective('on-action', ActionDirective);

package/src/lib.ts

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

package/src/main.ts

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

package/src/method.ts

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

package/src/page-id.ts

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

package/src/registry.ts

@@ -0,0 +1,145 @@
+import type {ActionDirective} from './directive.js';
+
+// ─── Type Definitions ────────────────────────────────────────────────────────
+
+/**
+ * A modifier handler attached to an `on-action` directive.
+ *
+ * Called with the directive instance as `this` and the triggering DOM `event`.
+ * Return `true` to allow the action to proceed, or `false` to cancel it.
+ * Returning `false` is the only way a modifier can veto a dispatch.
+ *
+ * @example
+ * ```ts
+ * // A modifier that only allows the action when the element is not disabled
+ * const notDisabledHandler: ModifierHandler = function () {
+ *   return !(this.element_ as HTMLButtonElement).disabled;
+ * };
+ * ```
+ */
+export type ModifierHandler = (this: ActionDirective, event: Event) => boolean;
+
+/**
+ * A payload resolver attached to an `on-action` directive.
+ *
+ * Called with the directive instance as `this` and the triggering DOM `event`
+ * at dispatch time. The return value becomes the `actionPayload` of the
+ * dispatched action. Use this to compute dynamic payloads from the DOM state.
+ *
+ * @example
+ * ```ts
+ * // A resolver that returns the element's dataset id
+ * const dataIdResolver: PayloadResolver = function () {
+ *   return (this.element_ as HTMLElement).dataset.id ?? null;
+ * };
+ * ```
+ */
+export type PayloadResolver = (this: ActionDirective, event: Event) => unknown;
+
+// ─── Registries ──────────────────────────────────────────────────────────────
+
+/**
+ * Registry of all named modifier handlers.
+ *
+ * Keys are modifier names used in the `on-action` attribute syntax
+ * (e.g. `click.prevent->action-id`). Values are `ModifierHandler` functions.
+ * Populated at module load with built-in modifiers; extended at runtime via
+ * `registerModifier`.
+ *
+ * @internal
+ */
+export const modifierRegistry = new Map<string, ModifierHandler>();
+
+/**
+ * Registry of all named payload resolvers.
+ *
+ * Keys are resolver tokens used in the `on-action` attribute syntax
+ * (e.g. `click->action-id:$value`). Values are `PayloadResolver` functions.
+ * Populated at module load with built-in resolvers; extended at runtime via
+ * `registerPayloadResolver`.
+ *
+ * @internal
+ */
+export const payloadRegistry = new Map<string, PayloadResolver>();
+
+// ─── Built-in Modifiers ───────────────────────────────────────────────────────
+
+/**
+ * `prevent` — calls `event.preventDefault()` before dispatching.
+ *
+ * Use it to suppress the browser's default behaviour (e.g. form submission,
+ * link navigation, context menu).
+ *
+ * @example `<form on-action="submit.prevent->submit-form">`
+ */
+modifierRegistry.set('prevent', (event) => {
+  event.preventDefault();
+  return true;
+});
+
+/**
+ * `stop` — calls `event.stopPropagation()` before dispatching.
+ *
+ * Prevents the event from bubbling further up the DOM tree. Useful when a
+ * child element should handle a click without triggering a parent's listener.
+ *
+ * @example `<button on-action="click.stop->select-item:42">`
+ */
+modifierRegistry.set('stop', (event) => {
+  event.stopPropagation();
+  return true;
+});
+
+/**
+ * `validate` — cancels the dispatch if the nearest `<form>` fails validation.
+ *
+ * Looks for a `<form>` ancestor (or the element itself if it is a form) and
+ * calls `checkValidity()`. If the form is invalid the action is not dispatched,
+ * allowing native constraint-validation UI to surface errors. If no form is
+ * found the dispatch is also cancelled and an accident is logged.
+ *
+ * Pair with `.prevent` on `submit` events to avoid page reloads:
+ *
+ * @example `<form on-action="submit.prevent.validate->submit-form" novalidate>`
+ */
+modifierRegistry.set('validate', function () {
+  const form = this.element_ instanceof HTMLFormElement ? this.element_ : this.element_.closest('form');
+  if (!form) {
+    this.logger_.accident('validate_modifier', 'no_form_found', {element: this.element_});
+    return false;
+  }
+  return form.checkValidity();
+});
+
+// ─── Built-in Payload Resolvers ───────────────────────────────────────────────
+
+/**
+ * `$value` — resolves to the element's `.value` property at dispatch time.
+ *
+ * Works with any element that exposes a `value` property: `<input>`,
+ * `<textarea>`, `<select>`. Returns `null` for elements without `.value`.
+ *
+ * @example `<input on-action="input->search-query:$value" />`
+ */
+payloadRegistry.set('$value', function () {
+  return 'value' in this.element_ ? (this.element_ as {value: unknown}).value : null;
+});
+
+/**
+ * `$formdata` — resolves to a plain object of all fields in the nearest `<form>`.
+ *
+ * Collects entries via `FormData` and converts them to a `Record<string, FormDataEntryValue>`.
+ * Looks for a `<form>` ancestor (or the element itself). Returns `null` when no
+ * form is found.
+ *
+ * @example `<form on-action="submit.prevent.validate->submit-form">`
+ * ```ts
+ * onAction<Record<string, FormDataEntryValue>>('submit-form', (data) => {
+ *   console.log(data); // {username: 'ali', password: '…'}
+ * });
+ * ```
+ */
+payloadRegistry.set('$formdata', function () {
+  const form = this.element_ instanceof HTMLFormElement ? this.element_ : this.element_.closest('form');
+  return form ? Object.fromEntries(new FormData(form).entries()) : null;
+});