@blotch/angular-lynx-testing-library 22.2.4 → 22.2.6

package/README.md

@@ -110,7 +110,7 @@ Call this after any signal mutation that happens outside an event handler (e.g.
 
 ### `fireEvent`
 
-Dispatches Lynx events on JSDOM elements. Use the named helpers for standard Lynx events:
+Fires Lynx events at JSDOM elements. Use the named helpers for standard Lynx events:
 
 ```ts
 import { fireEvent } from '@blotch/angular-lynx-testing-library';
@@ -120,7 +120,16 @@ fireEvent.input(element, { value: 'hello' });
 fireEvent.scroll(element, { scrollTop: 100 });
 ```
 
-Named helpers dispatch a DOM event with the key `"bindEvent:<name>"` (e.g. `"bindEvent:tap"`), which matches the listener registered by `__AddEvent` when Angular processes a `(bindtap)` template binding.
+A named helper runs the handlers a device would, in the same order:
+
+- **Touch events bubble.** A tap, long press or touch runs the element's own `(bindtap)` or `(catchtap)`, then its ancestors' on the way up to the page. So a tap on a row inside a pressable card reaches the card's `(click)`. `(capture-bind…)` and `(capture-catch…)` handlers run before them, from the page down.
+- **Mouse, wheel and key events bubble too**, as Lynx sends them on desktop and web.
+- **A `catch` handler stops the event** where it runs: a `(catchtap)` panel keeps a tap from reaching the backdrop behind it.
+- **Other events stay on their element.** `scroll`, `input`, `layoutchange` and the rest run only the element's own handler.
+
+`init.bubbles` overrides the event's own: `fireEvent.tap(element, { bubbles: false })` runs only the element's handler.
+
+`init.eventType` fires at one kind of handler on the element and nothing else: `fireEvent.tap(element, { eventType: 'catchEvent' })` dispatches the DOM event `"catchEvent:tap"`, which reaches only the element's `(catchtap)`.
 
 To dispatch a raw DOM event directly:
 
@@ -134,7 +143,7 @@ fireEvent(element, new Event('bindEvent:tap'));
 
 ### `eventMap`
 
-The full Lynx event registry. Each entry has a `defaultInit` object (currently empty for all events, but present for forward-compatibility).
+The full Lynx event registry. Each entry has a `defaultInit` object: `{ bubbles: true }` for the events Lynx sends up the response chain, `{}` for the rest.
 
 ```ts
 import { eventMap } from '@blotch/angular-lynx-testing-library';
@@ -179,7 +188,7 @@ expect(getByRole('button', { name: 'Week', selected: true })).toBeTruthy();
 - **Role**: from each trait in the table. An `<image>` is an `img` unless it sets `accessibility-traits`.
 - **Reachable**: a screen reader reaches `<text>`, `<image>`, and other elements with `accessibility-element="true"`, outside `accessibility-elements-hidden`. A `tabbar` is read from the container around the tabs, so it needs no `accessibility-element`. Others match only with `hidden: true`.
 - **`name`**: the `accessibility-label`, or a `<text>`'s own text. A `<view>` gets no name from the text inside it, since iOS doesn't read it.
-- **`selected`**: the `selected` trait, as in `accessibility-traits="button,selected"`, which an active `routerLinkActive` element gets. iOS reads a comma-separated list. Android reads one trait (`button` or `image`) and treats a list as `none`.
+- **`selected`**: the `selected` trait, as in `accessibility-traits="button,selected"`, which an active `routerLinkActive` element gets, and which `[lynxAccessibilityTraits]="{ selected: true }"` adds. iOS reads a comma-separated list. Android reads one trait (`button` or `image`) and treats a list as `none`.
 - **`value: { text }`**: the `accessibility-value`.
 - **Other ARIA states** (`checked`, `pressed`, `expanded`, `level`, …) have no Lynx attribute, so Lynx elements never match them.
 
@@ -400,7 +409,7 @@ render(Component)
 
 AngularLynx registers event handlers via `__AddEvent(element, eventType, eventName, { type: 'worklet', value: callback })`. The testing environment stores this as a DOM event listener under the key `"${eventType}:${eventName}"` (e.g. `"bindEvent:tap"`).
 
-`fireEvent.tap(el)` dispatches a `"bindEvent:tap"` DOM event, which triggers the listener. The listener calls `runWorklet(callback, [event])` which invokes the Angular handler directly on the main thread.
+`fireEvent.tap(el)` walks Lynx's event response chain, from the page down to `el` and back up, and calls each element's listener for the kind of handler it has, stopping at a `catch` one. The listener calls `runWorklet(callback, [event])` which invokes the Angular handler directly on the main thread. One bubbling `"bindEvent:tap"` DOM event wouldn't do: it would pass a `(catchtap)` ancestor's `"catchEvent:tap"` listener by and run the handlers above it.
 
 Template binding → PAPI registration → DOM listener key:
 

package/dist/fire-event.d.ts

@@ -1,64 +1,110 @@
 /**
  * fireEvent — dispatches Lynx events through the dual-thread pipeline.
  *
- * Lynx events are registered via __AddEvent with a key of "bindEvent:<name>"
+ * Lynx events are registered via __AddEvent with a key of "<type>:<name>"
  * (e.g. "bindEvent:tap"). The event handler stored on the element calls
  * lynxCoreInject.tt.publishEvent(handlerSign, eventData) which routes the
  * event to the background thread (not used by AngularLynx, which runs on
  * the main thread).
  *
  * For AngularLynx, the (event) bindings in templates are wired by
- * LynxRenderer.listen() which calls __AddEvent internally. The DOM event
- * dispatched here triggers that listener directly on the main thread.
+ * LynxRenderer.listen() which calls __AddEvent internally. The named helpers
+ * (fireEvent.tap, …) run those handlers on the main thread along the path
+ * Lynx sends the event (see deliver()).
+ */
+/**
+ * The events the named helpers fire. Those with `bubbles: true` travel Lynx's
+ * event response chain, from the element up to the page, so a tap on a row
+ * inside a pressable card reaches the card's handler. The rest reach only
+ * the element they happened on, as Lynx sends an element's own events
+ * (scroll, input, layout, …).
+ *
+ * The touch events bubble on every platform, as React Lynx's testing library
+ * has them. Mouse, wheel and key events bubble too, where Lynx sends them:
+ * its desktop engine dispatches them with TouchEventHandler::HandleBubbleEvent
+ * (all but mouseenter and mouseleave) and Lynx for Web with the DOM event's
+ * own bubbling. iOS and Android don't send them.
  */
 export declare const eventMap: {
     tap: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     longtap: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     touchstart: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     touchmove: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     touchcancel: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     touchend: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     longpress: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     keydown: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     keyup: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     mousedown: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     mouseup: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     mousemove: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     mouseclick: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     mousedblclick: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     mouselongpress: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     wheel: {
-        defaultInit: {};
+        defaultInit: {
+            bubbles: boolean;
+        };
     };
     scroll: {
         defaultInit: {};

package/dist/fire-event.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fire-event.d.ts","sourceRoot":"","sources":["../src/fire-event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CpB,CAAC;AAEF,KAAK,SAAS,GAAG,MAAM,OAAO,QAAQ,CAAC;AACvC,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;AAC/E,KAAK,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,GAAG;KAC3D,CAAC,IAAI,SAAS,GAAG,YAAY;CAC/B,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,SAET,CAAC"}
+{"version":3,"file":"fire-event.d.ts","sourceRoot":"","sources":["../src/fire-event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAUH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CpB,CAAC;AAEF,KAAK,SAAS,GAAG,MAAM,OAAO,QAAQ,CAAC;AACvC,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;AAC/E,KAAK,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,GAAG;KAC3D,CAAC,IAAI,SAAS,GAAG,YAAY;CAC/B,CAAC;AA8GF,eAAO,MAAM,SAAS,EAAE,SAET,CAAC"}

package/dist/fire-event.js

@@ -1,38 +1,52 @@
 /**
  * fireEvent — dispatches Lynx events through the dual-thread pipeline.
  *
- * Lynx events are registered via __AddEvent with a key of "bindEvent:<name>"
+ * Lynx events are registered via __AddEvent with a key of "<type>:<name>"
  * (e.g. "bindEvent:tap"). The event handler stored on the element calls
  * lynxCoreInject.tt.publishEvent(handlerSign, eventData) which routes the
  * event to the background thread (not used by AngularLynx, which runs on
  * the main thread).
  *
  * For AngularLynx, the (event) bindings in templates are wired by
- * LynxRenderer.listen() which calls __AddEvent internally. The DOM event
- * dispatched here triggers that listener directly on the main thread.
+ * LynxRenderer.listen() which calls __AddEvent internally. The named helpers
+ * (fireEvent.tap, …) run those handlers on the main thread along the path
+ * Lynx sends the event (see deliver()).
  */
-import { createEvent, fireEvent as domFireEvent } from '@testing-library/dom';
+import { createEvent, fireEvent as domFireEvent, getConfig, } from '@testing-library/dom';
 const EVENT_INIT_KEYS = new Set(['bubbles', 'cancelable', 'composed']);
+/**
+ * The events the named helpers fire. Those with `bubbles: true` travel Lynx's
+ * event response chain, from the element up to the page, so a tap on a row
+ * inside a pressable card reaches the card's handler. The rest reach only
+ * the element they happened on, as Lynx sends an element's own events
+ * (scroll, input, layout, …).
+ *
+ * The touch events bubble on every platform, as React Lynx's testing library
+ * has them. Mouse, wheel and key events bubble too, where Lynx sends them:
+ * its desktop engine dispatches them with TouchEventHandler::HandleBubbleEvent
+ * (all but mouseenter and mouseleave) and Lynx for Web with the DOM event's
+ * own bubbling. iOS and Android don't send them.
+ */
 export const eventMap = {
     // Touch / gesture
-    tap: { defaultInit: {} },
-    longtap: { defaultInit: {} },
-    touchstart: { defaultInit: {} },
-    touchmove: { defaultInit: {} },
-    touchcancel: { defaultInit: {} },
-    touchend: { defaultInit: {} },
-    longpress: { defaultInit: {} },
+    tap: { defaultInit: { bubbles: true } },
+    longtap: { defaultInit: { bubbles: true } },
+    touchstart: { defaultInit: { bubbles: true } },
+    touchmove: { defaultInit: { bubbles: true } },
+    touchcancel: { defaultInit: { bubbles: true } },
+    touchend: { defaultInit: { bubbles: true } },
+    longpress: { defaultInit: { bubbles: true } },
     // Keyboard
-    keydown: { defaultInit: {} },
-    keyup: { defaultInit: {} },
+    keydown: { defaultInit: { bubbles: true } },
+    keyup: { defaultInit: { bubbles: true } },
     // Mouse
-    mousedown: { defaultInit: {} },
-    mouseup: { defaultInit: {} },
-    mousemove: { defaultInit: {} },
-    mouseclick: { defaultInit: {} },
-    mousedblclick: { defaultInit: {} },
-    mouselongpress: { defaultInit: {} },
-    wheel: { defaultInit: {} },
+    mousedown: { defaultInit: { bubbles: true } },
+    mouseup: { defaultInit: { bubbles: true } },
+    mousemove: { defaultInit: { bubbles: true } },
+    mouseclick: { defaultInit: { bubbles: true } },
+    mousedblclick: { defaultInit: { bubbles: true } },
+    mouselongpress: { defaultInit: { bubbles: true } },
+    wheel: { defaultInit: { bubbles: true } },
     // Scroll / viewport
     scroll: { defaultInit: {} },
     scrollend: { defaultInit: {} },
@@ -57,23 +71,113 @@ export const eventMap = {
     transitioncancel: { defaultInit: {} },
     animationend: { defaultInit: {} },
 };
+/**
+ * The kinds of handler Lynx runs on the way down the response chain to the
+ * target (capture) and on the way back up (bubble). An element has at most
+ * one handler per event name, of any kind (see the runtime's
+ * combinedEventType), so the order within a phase only matters to a test
+ * that registers more.
+ */
+const CAPTURE_PHASE = ['capture-bindEvent', 'capture-catchEvent'];
+const BUBBLE_PHASE = ['bindEvent', 'catchEvent'];
+/**
+ * The handler __AddEvent registered on `element` for the event `type:name`,
+ * if any. The testing environment keeps an element's handlers in an
+ * `eventMap` keyed that way, each also listening for the DOM event of that
+ * name (setup.ts's __GetEvents reads the same map).
+ */
+const handlerOf = (element, type, name) => element.eventMap?.[`${type}:${name}`];
+/**
+ * The event a handler of `type` receives: the `<type>:<name>` DOM event that
+ * reaches it when fired on its own, with the Lynx properties and the test's
+ * init on it. Standard EventInit keys are read-only on constructed events,
+ * so they're passed to the constructor and not assigned.
+ */
+const createLynxEvent = (elem, type, name, init) => {
+    const eventInit = { eventType: type, eventName: name, ...init };
+    const event = createEvent(`${type}:${name}`, elem, eventInit);
+    Object.assign(event, Object.fromEntries(Object.entries(eventInit).filter(([k]) => !EVENT_INIT_KEYS.has(k))));
+    return event;
+};
+/**
+ * Runs the handlers for the event `name` fired at `target`, as Lynx's
+ * TouchEventHandler::HandleEventInternal does on a device. An event that
+ * bubbles goes down from the page to the target, running `capture-bind` and
+ * `capture-catch` handlers, then back up, running `bind` and `catch` ones. A
+ * `catch` handler of either phase runs and stops the event there. Any other
+ * event runs the target's own `bind` or `catch` handler and nothing more.
+ *
+ * It calls the handlers rather than dispatching one DOM event, because the
+ * testing environment listens for a separate DOM event per kind
+ * (`bindEvent:tap`, `catchEvent:tap`, …): a bubbling `bindEvent:tap` would
+ * pass a `(catchtap)` ancestor by, and reach the handlers above it, where a
+ * device stops. Returns false if a handler canceled its event, as
+ * dispatchEvent does.
+ */
+const deliver = (target, name, init) => {
+    // The error Testing Library gives a query that found nothing, rather than
+    // a TypeError from reading its parent.
+    if (!target) {
+        throw new Error(`Unable to fire a "${name}" event - please provide a DOM element.`);
+    }
+    const chain = [target];
+    if (init['bubbles']) {
+        for (let el = target.parentElement; el; el = el.parentElement) {
+            chain.push(el);
+        }
+    }
+    let notCanceled = true;
+    /**
+     * Runs each element's handlers of `types` in turn. Returns true once a
+     * catch handler stops the event.
+     */
+    const runPhase = (elements, types) => {
+        for (const element of elements) {
+            let caught = false;
+            for (const type of types) {
+                const handler = handlerOf(element, type, name);
+                if (!handler)
+                    continue;
+                const event = createLynxEvent(target, type, name, init);
+                handler(event);
+                notCanceled &&= !event.defaultPrevented;
+                caught ||= type.endsWith('catchEvent');
+            }
+            if (caught)
+                return true;
+        }
+        return false;
+    };
+    // Lynx has no capture phase for the events that stay on their target.
+    const captured = !!init['bubbles'] && runPhase([...chain].reverse(), CAPTURE_PHASE);
+    if (!captured)
+        runPhase(chain, BUBBLE_PHASE);
+    return notCanceled;
+};
 export const fireEvent = ((elem, event) => {
     return domFireEvent(elem, event);
 });
 for (const key of Object.keys(eventMap)) {
     fireEvent[key] = (elem, init) => {
-        const eventType = init?.['eventType'] ?? 'bindEvent';
-        const eventInit = {
-            eventType,
-            eventName: key,
+        const { eventType, ...rest } = init ?? {};
+        if (eventType === undefined) {
+            const eventInit = { ...eventMap[key].defaultInit, ...rest };
+            // Run through Testing Library's eventWrapper, as its fireEvent runs a
+            // dispatch, for a test that configures one.
+            let notCanceled = true;
+            getConfig().eventWrapper(() => {
+                notCanceled = deliver(elem, key, eventInit);
+            });
+            return notCanceled;
+        }
+        // An explicit eventType fires the one `<eventType>:<name>` DOM event at
+        // elem: it reaches elem's handler of that kind, or a listener the test
+        // added for it, and goes no further unless init asks it to bubble.
+        const event = createLynxEvent(elem, String(eventType), key, {
             ...eventMap[key].defaultInit,
-            ...init,
-        };
-        const event = createEvent(`${eventType}:${key}`, elem, eventInit);
-        // Assign Lynx-specific custom properties (eventType, eventName, etc.).
-        // Standard EventInit keys are read-only on constructed events so we skip them.
-        const customProps = Object.fromEntries(Object.entries(eventInit).filter(([k]) => !EVENT_INIT_KEYS.has(k)));
-        Object.assign(event, customProps);
+            bubbles: false,
+            ...rest,
+        });
         return domFireEvent(elem, event);
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blotch/angular-lynx-testing-library",
-  "version": "22.2.4",
+  "version": "22.2.6",
   "description": "Testing utilities for AngularLynx apps",
   "homepage": "https://github.com/Blotch-Smart-Frames/AngularLynx#readme",
   "bugs": {