@alwatr/action 9.13.0 → 9.16.0

package/src/registry.ts

@@ -3,15 +3,18 @@
 /**
  * A modifier handler used in `on-action` attribute syntax.
  *
- * 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.
+ * Receives the triggering DOM `event` and the `element` that owns the
+ * `on-action` attribute. Return `true` (or any truthy value) to allow the
+ * action to proceed, or `false` to cancel the dispatch.
+ *
+ * Using explicit parameters instead of `this` binding makes handlers
+ * compatible with arrow functions and easier to test in isolation.
  *
  * @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;
+ * const notDisabledHandler: ModifierHandler = (_event, element) => {
+ *   return !(element as HTMLButtonElement).disabled;
  * };
  * ```
  */
@@ -20,15 +23,18 @@ export type ModifierHandler = (event: Event, element: HTMLElement) => boolean;
 /**
  * A payload resolver used in `on-action` attribute syntax.
  *
- * 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.
+ * Receives the triggering DOM `event` and the `element` that owns the
+ * `on-action` attribute. The return value becomes the `actionPayload` passed
+ * to `onAction` subscribers. Use this to compute dynamic payloads from DOM state.
+ *
+ * Using explicit parameters instead of `this` binding makes resolvers
+ * compatible with arrow functions and easier to test in isolation.
  *
  * @example
  * ```ts
  * // A resolver that returns the element's dataset id
- * const dataIdResolver: PayloadResolver = function () {
- *   return (this.element as HTMLElement).dataset.id ?? null;
+ * const dataIdResolver: PayloadResolver = (_event, element) => {
+ *   return (element as HTMLElement).dataset.id ?? null;
  * };
  * ```
  */
@@ -39,8 +45,8 @@ export type PayloadResolver = (event: Event, element: HTMLElement) => unknown;
 /**
  * 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.
+ * Keys are modifier names used in the `on-<eventType>` attribute syntax
+ * (e.g. `on-click="action-id; prevent"`). Values are `ModifierHandler` functions.
  * Populated at module load with built-in modifiers; extended at runtime via
  * `registerModifier`.
  *
@@ -51,8 +57,8 @@ 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.
+ * Keys are resolver tokens used in the `on-<eventType>` attribute syntax
+ * (e.g. `on-input="search_query:$value"`). Values are `PayloadResolver` functions.
  * Populated at module load with built-in resolvers; extended at runtime via
  * `registerPayloadResolver`.
  *
@@ -68,7 +74,7 @@ export const payloadRegistry = new Map<string, PayloadResolver>();
  * 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">`
+ * @example `<form on-submit="submit-form; prevent">`
  */
 modifierRegistry.set('prevent', (event) => {
   event.preventDefault();
@@ -85,9 +91,9 @@ modifierRegistry.set('prevent', (event) => {
  *
  * Pair with `.prevent` on `submit` events to avoid page reloads:
  *
- * @example `<form on-action="submit.prevent.validate->submit-form:$formdata" novalidate>`
+ * @example `<form on-submit="submit_form:$formdata; prevent,validate" novalidate>`
  */
-modifierRegistry.set('validate', function (_, element) {
+modifierRegistry.set('validate', (_event, element) => {
   const form = element instanceof HTMLFormElement ? element : element.closest('form');
   if (!form) return false;
   return form.checkValidity();
@@ -101,9 +107,9 @@ modifierRegistry.set('validate', function (_, element) {
  * 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" />`
+ * @example `<input on-input="search_query:$value" />`
  */
-payloadRegistry.set('$value', function (_, element) {
+payloadRegistry.set('$value', (_event, element) => {
   return 'value' in element ? (element as {value: unknown}).value : null;
 });
 
@@ -114,14 +120,31 @@ payloadRegistry.set('$value', function (_, element) {
  * 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:$formdata">`
+ * @example `<form on-submit="submit_form:$formdata; prevent,validate">`
  * ```ts
- * onAction<Record<string, FormDataEntryValue>>('submit-form', (data) => {
+ * onAction('submit_form', (data) => {
  *   console.log(data); // {username: 'ali', password: '…'}
  * });
  * ```
  */
-payloadRegistry.set('$formdata', function (_, element) {
+payloadRegistry.set('$formdata', (_event, element) => {
   const form = element instanceof HTMLFormElement ? element : element.closest('form');
-  return form ? Object.fromEntries(new FormData(form).entries()) : null;
+  return form ? Object.fromEntries(new FormData(form)) : null;
+});
+
+/**
+ * `$checked` — resolves to the `.checked` boolean property of a checkbox or radio input.
+ *
+ * Works with `<input type="checkbox">` and `<input type="radio">`.
+ * Returns `null` for elements that do not have a `checked` property.
+ *
+ * @example `<input type="checkbox" on-change="toggle_feature:$checked" />`
+ * ```ts
+ * onAction('toggle_feature', (isChecked) => {
+ *   featureSignal.set(isChecked as boolean);
+ * });
+ * ```
+ */
+payloadRegistry.set('$checked', (_event, element) => {
+  return 'checked' in element ? (element as HTMLInputElement).checked : null;
 });

package/dist/page-ready.d.ts

@@ -1,3 +0,0 @@
-export declare function onPageReady<T extends string>(pageId: T, handler: () => void): void;
-export declare function dispatchPageReady(): void;
-//# sourceMappingURL=page-ready.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"page-ready.d.ts","sourceRoot":"","sources":["../src/page-ready.ts"],"names":[],"mappings":"AASA,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,IAAI,QAG3E;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAgBxC"}

package/src/page-ready.ts

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