@alwatr/action 9.16.0 → 9.18.1

package/src/type.ts

@@ -0,0 +1,165 @@
+import type {DictionaryOpt} from '@alwatr/type-helper';
+
+/**
+ * Global registry mapping action identifiers to their payload types.
+ *
+ * Extend this interface via declaration merging to register your application's
+ * actions and gain full type safety in `onAction` and `dispatchAction`.
+ *
+ * This interface is intentionally empty in the base package — all actions are
+ * application-specific and should be declared in a dedicated `action-record.ts`
+ * file within each feature package.
+ *
+ * @example — registering actions in a feature package
+ * ```ts
+ * // pkg/my-feature/src/action-record.ts
+ * declare module '@alwatr/action' {
+ *   interface ActionRecord {
+ *     'open_drawer': string;
+ *     'add_to_cart': {productId: number; qty: number};
+ *     'logout': void;
+ *   }
+ * }
+ * ```
+ */
+export interface ActionRecord {}
+
+/**
+ * Builds the parameter type for `dispatchAction`.
+ *
+ * When `ActionRecord[K]` is `void`, the `payload` field becomes optional so
+ * callers can omit it entirely. For all other payload types the field remains
+ * required, preserving full type safety.
+ *
+ * @example — void action (payload omitted)
+ * ```ts
+ * dispatchAction({type: 'logout'});
+ * ```
+ *
+ * @example — typed action (payload required)
+ * ```ts
+ * dispatchAction({type: 'add_to_cart', payload: {productId: 42, qty: 1}});
+ * ```
+ */
+export type DispatchParam<K extends keyof ActionRecord> =
+  ActionRecord[K] extends void ? Omit<Action<K>, 'payload'> & {payload?: void} : Action<K>;
+
+/**
+ * Alwatr Flux Standard Action (AFSA).
+ *
+ * The single, canonical object passed to every `dispatchAction` call and
+ * received by every `onAction` handler. Keeping all action data in one
+ * structure makes the bus extensible without breaking existing call sites.
+ *
+ * @template K - A key of `ActionRecord`; constrains `type` and `payload` together.
+ *
+ * @example — dispatching
+ * ```ts
+ * dispatchAction({type: 'add_to_cart', payload: {productId: 42, qty: 1}});
+ * ```
+ *
+ * @example — subscribing
+ * ```ts
+ * onAction('add_to_cart', (action) => {
+ *   console.log(action.type);    // 'add_to_cart'
+ *   console.log(action.payload); // {productId: 42, qty: 1}
+ *   console.log(action.context); // e.g. 'product-list' (from DOM) or undefined
+ * });
+ * ```
+ */
+export interface Action<K extends keyof ActionRecord = keyof ActionRecord> {
+  /**
+   * Unique action identifier — must be a key of `ActionRecord`.
+   *
+   * @example 'cart:add-item', 'open_drawer', 'logout'
+   */
+  readonly type: K;
+
+  /**
+   * The DOM context in which the action was triggered.
+   *
+   * Extracted at delegation time from the nearest ancestor element that carries
+   * an `action-context` attribute. Useful for scoping the same action type to
+   * different UI regions (e.g. two sliders on the same page both dispatching
+   * `'slider:change'` but with different context values).
+   *
+   * `undefined` when the action is dispatched programmatically (no DOM involved)
+   * or when no `[action-context]` ancestor exists.
+   *
+   * @example 'slider-123', 'product-list', 'checkout-form'
+   */
+  readonly context?: string;
+
+  /**
+   * The pure business payload carried by this action.
+   *
+   * Type is inferred from `ActionRecord[K]` — the compiler enforces the correct
+   * shape at every call site. No manual generic annotation is needed.
+   */
+  readonly payload: ActionRecord[K];
+
+  /**
+   * Open-ended metadata bag for cross-cutting concerns.
+   *
+   * Intentionally untyped so that future infrastructure layers (tracing,
+   * analytics, A/B testing) can attach data without touching the typed API.
+   * Modifiers in the delegation pipeline may also write to `meta` before the
+   * action reaches subscribers.
+   *
+   * Treat values here as `unknown` and validate before use.
+   *
+   * @example {traceId: 'abc-123', timestamp: Date.now()}
+   */
+  meta?: DictionaryOpt<unknown>;
+}
+
+/**
+ * A modifier handler used in `on-<eventType>` attribute syntax.
+ *
+ * Receives the triggering DOM `event`, the `element` that owns the
+ * `on-<eventType>` attribute, and the **mutable** `action` object being built.
+ * The handler may mutate `action.meta` to attach cross-cutting data (e.g. a
+ * trace ID, a timestamp, or an A/B flag) before the action reaches subscribers.
+ *
+ * Return `true` (or any truthy value) to allow the action to proceed, or
+ * `false` to cancel the dispatch entirely.
+ *
+ * Using explicit parameters instead of `this` binding makes handlers
+ * compatible with arrow functions and easier to test in isolation.
+ *
+ * @example — a modifier that stamps a timestamp into meta
+ * ```ts
+ * const timestampHandler: ModifierHandler = (_event, _element, action) => {
+ *   action.meta ??= {};
+ *   action.meta['timestamp'] = Date.now();
+ *   return true;
+ * };
+ * ```
+ *
+ * @example — a modifier that cancels dispatch when the element is disabled
+ * ```ts
+ * const notDisabledHandler: ModifierHandler = (_event, element) => {
+ *   return !(element as HTMLButtonElement).disabled;
+ * };
+ * ```
+ */
+export type ModifierHandler = (event: Event, element: HTMLElement, action: Action) => boolean;
+
+/**
+ * A payload resolver used in `on-<eventType>` attribute syntax.
+ *
+ * Receives the triggering DOM `event` and the `element` that owns the
+ * `on-<eventType>` attribute. The return value becomes the `payload` field of
+ * the `Action` object passed to `onAction` subscribers.
+ *
+ * Using explicit parameters instead of `this` binding makes resolvers
+ * compatible with arrow functions and easier to test in isolation.
+ *
+ * @example — a resolver that returns the element's dataset id
+ * ```ts
+ * const dataIdResolver: PayloadResolver = (_event, element) => {
+ *   return (element as HTMLElement).dataset.id ?? null;
+ * };
+ * ```
+ */
+export type PayloadResolver = (event: Event, element: HTMLElement) => unknown;

package/dist/action-record.d.ts

@@ -1,54 +0,0 @@
-/**
- * @file action-record.ts
- *
- * Global action type registry via TypeScript declaration merging.
- *
- * ## How it works
- *
- * `ActionRecord` is an open interface — any package in the monorepo (or any
- * consumer application) can extend it with their own action names and payload
- * types using declaration merging, without modifying this file:
- *
- * ```ts
- * // In your package: src/action-record.ts
- * declare module '@alwatr/action' {
- *   interface ActionRecord {
- *     'open_drawer': string;
- *     'add_to_cart': {productId: number; qty: number};
- *     'logout': void;
- *   }
- * }
- * ```
- *
- * Once declared, `onAction` and `dispatchAction` become fully type-safe for
- * those action names — the compiler enforces the correct payload type at every
- * call site and provides autocomplete for action identifiers.
- *
- * Only actions declared in `ActionRecord` are accepted. Passing an unknown
- * action name is a **compile error** — there is no string fallback.
- */
-/**
- * Global registry mapping action identifiers to their payload types.
- *
- * Extend this interface via declaration merging to register your application's
- * actions and gain full type safety in `onAction` and `dispatchAction`.
- *
- * This interface is intentionally empty in the base package — all actions are
- * application-specific and should be declared in a dedicated `action-record.ts`
- * file within each feature package.
- *
- * @example — registering actions in a feature package
- * ```ts
- * // pkg/my-feature/src/action-record.ts
- * declare module '@alwatr/action' {
- *   interface ActionRecord {
- *     'open_drawer': string;
- *     'add_to_cart': {productId: number; qty: number};
- *     'logout': void;
- *   }
- * }
- * ```
- */
-export interface ActionRecord {
-}
-//# sourceMappingURL=action-record.d.ts.map

package/dist/action-record.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"action-record.d.ts","sourceRoot":"","sources":["../src/action-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,YAAY;CAAG"}

package/dist/lib.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,eAAO,MAAM,OAAO,uCAAgC,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,iEAAwE,CAAC"}

package/dist/registry.d.ts

@@ -1,61 +0,0 @@
-/**
- * A modifier handler used in `on-action` attribute syntax.
- *
- * 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 = (_event, element) => {
- *   return !(element as HTMLButtonElement).disabled;
- * };
- * ```
- */
-export type ModifierHandler = (event: Event, element: HTMLElement) => boolean;
-/**
- * A payload resolver used in `on-action` attribute syntax.
- *
- * 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 = (_event, element) => {
- *   return (element as HTMLElement).dataset.id ?? null;
- * };
- * ```
- */
-export type PayloadResolver = (event: Event, element: HTMLElement) => unknown;
-/**
- * Registry of all named modifier handlers.
- *
- * 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`.
- *
- * @internal
- */
-export declare const modifierRegistry: Map<string, ModifierHandler>;
-/**
- * Registry of all named payload resolvers.
- *
- * 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`.
- *
- * @internal
- */
-export declare const payloadRegistry: Map<string, PayloadResolver>;
-//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC;AAE9E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC;AAI9E;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,8BAAqC,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,8BAAqC,CAAC"}

package/src/action-record.ts

@@ -1,54 +0,0 @@
-/**
- * @file action-record.ts
- *
- * Global action type registry via TypeScript declaration merging.
- *
- * ## How it works
- *
- * `ActionRecord` is an open interface — any package in the monorepo (or any
- * consumer application) can extend it with their own action names and payload
- * types using declaration merging, without modifying this file:
- *
- * ```ts
- * // In your package: src/action-record.ts
- * declare module '@alwatr/action' {
- *   interface ActionRecord {
- *     'open_drawer': string;
- *     'add_to_cart': {productId: number; qty: number};
- *     'logout': void;
- *   }
- * }
- * ```
- *
- * Once declared, `onAction` and `dispatchAction` become fully type-safe for
- * those action names — the compiler enforces the correct payload type at every
- * call site and provides autocomplete for action identifiers.
- *
- * Only actions declared in `ActionRecord` are accepted. Passing an unknown
- * action name is a **compile error** — there is no string fallback.
- */
-
-/**
- * Global registry mapping action identifiers to their payload types.
- *
- * Extend this interface via declaration merging to register your application's
- * actions and gain full type safety in `onAction` and `dispatchAction`.
- *
- * This interface is intentionally empty in the base package — all actions are
- * application-specific and should be declared in a dedicated `action-record.ts`
- * file within each feature package.
- *
- * @example — registering actions in a feature package
- * ```ts
- * // pkg/my-feature/src/action-record.ts
- * declare module '@alwatr/action' {
- *   interface ActionRecord {
- *     'open_drawer': string;
- *     'add_to_cart': {productId: number; qty: number};
- *     'logout': void;
- *   }
- * }
- * ```
- */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface ActionRecord {}