@alwatr/action 9.12.0 → 9.13.0

package/src/page-ready.ts

@@ -0,0 +1,31 @@
+import {createLogger} from '@alwatr/logger';
+import {createChannelSignal} from '@alwatr/signal';
+
+const logger = createLogger('page-ready');
+
+const pageReadyChannel_ = createChannelSignal<Record<string, undefined>>({
+  name: 'page-ready',
+});
+
+export function onPageReady<T extends string>(pageId: T, handler: () => void) {
+  logger.logMethodArgs?.('onPageReady', {pageId});
+  pageReadyChannel_.on(pageId, handler);
+}
+
+export function dispatchPageReady(): void {
+  logger.logMethod?.('dispatchPageReady');
+  const element = document.querySelector('[page-id]');
+  if (!element) {
+    logger.incident?.('dispatchPageReady', 'element_not_found');
+    return;
+  }
+
+  const pageId = element.getAttribute('page-id')?.trim();
+
+  if (!pageId) {
+    logger.accident('dispatchPageReady', 'empty_page_id', {element});
+    return;
+  }
+
+  pageReadyChannel_.dispatch(pageId);
+}

package/src/registry.ts

@@ -1,40 +1,38 @@
-import type {ActionDirective} from './directive.js';
-
 // ─── Type Definitions ────────────────────────────────────────────────────────
 
 /**
- * A modifier handler attached to an `on-action` directive.
+ * A modifier handler used in `on-action` attribute syntax.
  *
- * 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.
+ * Called with an `ActionContext` as `this` and the triggering DOM `event`.
+ * Return `true` (or any truthy value) to allow the action to proceed,
+ * or `false` to cancel the 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;
+ *   return !(this.element as HTMLButtonElement).disabled;
  * };
  * ```
  */
-export type ModifierHandler = (this: ActionDirective, event: Event) => boolean;
+export type ModifierHandler = (event: Event, element: HTMLElement) => boolean;
 
 /**
- * A payload resolver attached to an `on-action` directive.
+ * A payload resolver used in `on-action` attribute syntax.
  *
- * 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.
+ * Called with an `ActionContext` as `this` and the triggering DOM `event`
+ * at dispatch time. The return value becomes the `actionPayload` passed to
+ * `onAction` subscribers. Use this to compute dynamic payloads from 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;
+ *   return (this.element as HTMLElement).dataset.id ?? null;
  * };
  * ```
  */
-export type PayloadResolver = (this: ActionDirective, event: Event) => unknown;
+export type PayloadResolver = (event: Event, element: HTMLElement) => unknown;
 
 // ─── Registries ──────────────────────────────────────────────────────────────
 
@@ -77,37 +75,21 @@ modifierRegistry.set('prevent', (event) => {
   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.
+ * found the dispatch is also cancelled.
  *
  * Pair with `.prevent` on `submit` events to avoid page reloads:
  *
- * @example `<form on-action="submit.prevent.validate->submit-form" novalidate>`
+ * @example `<form on-action="submit.prevent.validate->submit-form:$formdata" 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;
-  }
+modifierRegistry.set('validate', function (_, element) {
+  const form = element instanceof HTMLFormElement ? element : element.closest('form');
+  if (!form) return false;
   return form.checkValidity();
 });
 
@@ -121,8 +103,8 @@ modifierRegistry.set('validate', function () {
  *
  * @example `<input on-action="input->search-query:$value" />`
  */
-payloadRegistry.set('$value', function () {
-  return 'value' in this.element_ ? (this.element_ as {value: unknown}).value : null;
+payloadRegistry.set('$value', function (_, element) {
+  return 'value' in element ? (element as {value: unknown}).value : null;
 });
 
 /**
@@ -132,14 +114,14 @@ payloadRegistry.set('$value', function () {
  * 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">`
+ * @example `<form on-action="submit.prevent.validate->submit-form:$formdata">`
  * ```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');
+payloadRegistry.set('$formdata', function (_, element) {
+  const form = element instanceof HTMLFormElement ? element : element.closest('form');
   return form ? Object.fromEntries(new FormData(form).entries()) : null;
 });

package/dist/directive.d.ts

@@ -1,94 +0,0 @@
-import { Directive } from '@alwatr/directive';
-/**
- * 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 declare 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 init_(): void;
-    /**
-     * 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;
-}
-/**
- * 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 declare const registerActionDirective: () => void;
-//# sourceMappingURL=directive.d.ts.map

package/dist/directive.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"directive.d.ts","sourceRoot":"","sources":["../src/directive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,SAAS,EAAC,MAAM,mBAAmB,CAAC;AA4B3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,eAAgB,SAAQ,SAAS;IAC5C;;;;;;OAMG;IACH,SAAS,CAAC,cAAc,CAAC,EAAE;QACzB,oEAAoE;QACpE,SAAS,EAAE,MAAM,CAAC;QAClB,iEAAiE;QACjE,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QAC/B,kEAAkE;QAClE,QAAQ,EAAE,MAAM,CAAC;QACjB,iFAAiF;QACjF,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF;;;;;;;OAOG;cACgB,KAAK,IAAI,IAAI;IAsDhC;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;CAqBxC;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,YAA8C,CAAC"}

package/dist/page-id.d.ts

@@ -1,57 +0,0 @@
-import { Directive } from '@alwatr/directive';
-/**
- * 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 declare 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 init_(): void;
-}
-/**
- * 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 declare const registerPageIdDirective: () => void;
-//# sourceMappingURL=page-id.d.ts.map

package/dist/page-id.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"page-id.d.ts","sourceRoot":"","sources":["../src/page-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAgB,MAAM,mBAAmB,CAAC;AAK3D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,eAAgB,SAAQ,SAAS;IAC5C;;;;;OAKG;cACgB,KAAK,IAAI,IAAI;CAYjC;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,uBAAuB,YAA4C,CAAC"}

package/src/directive.ts

@@ -1,197 +0,0 @@
-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/page-id.ts

@@ -1,74 +0,0 @@
-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);