@blotch/angular-lynx-testing-library 22.2.3 → 22.2.5

package/README.md

@@ -1,6 +1,6 @@
 # @blotch/angular-lynx-testing-library
 
-Testing utilities for [AngularLynx](https://github.com/Blotch-Smart-Frames/AngularLynx) apps. Renders Angular standalone components through the Lynx PAPI pipeline into a JSDOM tree, then exposes the result via [@testing-library/dom](https://testing-library.com/docs/dom-testing-library/intro) queries.
+Testing utilities for [AngularLynx](https://github.com/Blotch-Smart-Frames/AngularLynx) apps. Renders Angular standalone components through the Lynx PAPI pipeline into a JSDOM tree, then exposes the result via [@testing-library/dom](https://testing-library.com/docs/dom-testing-library/intro) queries, which also read Lynx's `accessibility-*` attributes.
 
 ## Installation
 
@@ -75,11 +75,11 @@ const { container, getByText, queryByRole } = await render(MyComponent);
 
 **Return value:**
 
-| Property     | Type         | Description                                                                                                 |
-| ------------ | ------------ | ----------------------------------------------------------------------------------------------------------- |
-| `container`  | `Element`    | The JSDOM `<page>` root element. All rendered children are descendants.                                     |
-| `unmount`    | `() => void` | Destroys the Angular app.                                                                                   |
-| `...queries` | —            | All `@testing-library/dom` queries bound to `container` (`getByText`, `queryByRole`, `findByTestId`, etc.). |
+| Property     | Type         | Description                                                                                                            |
+| ------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `container`  | `Element`    | The JSDOM `<page>` root element. All rendered children are descendants.                                                |
+| `unmount`    | `() => void` | Destroys the Angular app.                                                                                              |
+| `...queries` | —            | Every query in [`queries`](#queries) bound to `container` (`getByText`, `getByRole`, `getByAccessibilityLabel`, etc.). |
 
 ### `cleanup()`
 
@@ -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';
@@ -143,9 +152,53 @@ console.log(Object.keys(eventMap));
 // ['tap', 'longtap', 'touchstart', ...]
 ```
 
-### Re-exports from `@testing-library/dom`
+### `*ByAccessibilityLabel`
+
+Find elements by their `accessibility-label`, the text a screen reader reads on Lynx. Testing Library's `*ByLabelText` reads `<label>` and `aria-*` attributes, which Lynx elements don't have.
+
+```ts
+const { getByAccessibilityLabel } = await render(Toolbar);
+
+fireEvent.tap(getByAccessibilityLabel('Close'));
+```
+
+They come in Testing Library's six variants (`getBy`, `getAllBy`, `queryBy`, `queryAllBy`, `findBy`, `findAllBy`) and take its TextMatch (a string, RegExp or function) and MatcherOptions (`exact`, `normalizer`).
+
+### `*ByRole`
+
+Testing Library's `*ByRole`, reading Lynx's accessibility attributes as a screen reader does. Elements Testing Library gives a role still match, such as an `<input>` as a `textbox`.
+
+```ts
+const { getByRole } = await render(Toolbar);
+
+fireEvent.tap(getByRole('button', { name: 'Save' }));
+expect(getByRole('button', { name: 'Week', selected: true })).toBeTruthy();
+```
+
+| `accessibility-traits` | Role        |
+| ---------------------- | ----------- |
+| `button`               | `button`    |
+| `link`                 | `link`      |
+| `image`                | `img`       |
+| `header`               | `heading`   |
+| `search`               | `searchbox` |
+| `adjustable`           | `slider`    |
+| `tabbar`               | `tablist`   |
+
+- **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, 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.
+
+### `screen`, `within()` and `getQueriesForElement()`
+
+Testing Library's, with the queries above: `screen` binds every query to `document.body`, and `within(element)` binds them to `element`. `getQueriesForElement` is `within`.
+
+### `queries`
 
-`screen` · `within` · `getQueriesForElement`
+Every query, unbound (each takes the container first). Spread it into your own queries to keep them next to these. Each query is also exported on its own, such as `getByAccessibilityLabel(container, 'Close')`.
 
 ## Usage
 
@@ -356,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/accessibility-label-queries.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Queries that find an element by its `accessibility-label`, the text a
+ * screen reader reads for it on Lynx.
+ *
+ * Testing Library's `*ByLabelText` reads `<label>` elements and the ARIA
+ * label attributes, none of which Lynx has: a Lynx element gets its
+ * accessible name from `accessibility-label`. Like `*ByTitle` and
+ * `*ByAltText`, which also match one attribute, these take a TextMatch with
+ * MatcherOptions (`exact`, `normalizer`), throw errors worded the same way,
+ * and their `find*` variants retry for `waitFor`'s timeout.
+ */
+import { type AllByBoundAttribute, type FindAllByBoundAttribute, type FindByBoundAttribute, type GetByBoundAttribute, type QueryByBoundAttribute } from '@testing-library/dom';
+/**
+ * Finds every element whose `accessibility-label` matches, or none.
+ */
+declare const queryAll: <T extends HTMLElement = HTMLElement>(...args: Parameters<AllByBoundAttribute<T>>) => ReturnType<AllByBoundAttribute<T>>;
+/**
+ * Finds the element whose `accessibility-label` matches, or null. Throws when
+ * more than one does.
+ */
+declare const query: <T extends HTMLElement = HTMLElement>(...args: Parameters<QueryByBoundAttribute<T>>) => ReturnType<QueryByBoundAttribute<T>>;
+/**
+ * Finds every element whose `accessibility-label` matches. Throws when none
+ * does.
+ */
+declare const getAll: <T extends HTMLElement = HTMLElement>(...args: Parameters<AllByBoundAttribute<T>>) => ReturnType<AllByBoundAttribute<T>>;
+/**
+ * Finds the element whose `accessibility-label` matches. Throws when none or
+ * more than one does.
+ */
+declare const get: <T extends HTMLElement = HTMLElement>(...args: Parameters<GetByBoundAttribute<T>>) => ReturnType<GetByBoundAttribute<T>>;
+/**
+ * Waits for elements whose `accessibility-label` matches, as `getAll` finds
+ * them.
+ */
+declare const findAll: <T extends HTMLElement = HTMLElement>(...args: Parameters<FindAllByBoundAttribute<T>>) => ReturnType<FindAllByBoundAttribute<T>>;
+/**
+ * Waits for the element whose `accessibility-label` matches, as `get` finds
+ * it.
+ */
+declare const find: <T extends HTMLElement = HTMLElement>(...args: Parameters<FindByBoundAttribute<T>>) => ReturnType<FindByBoundAttribute<T>>;
+export { queryAll as queryAllByAccessibilityLabel, query as queryByAccessibilityLabel, getAll as getAllByAccessibilityLabel, get as getByAccessibilityLabel, findAll as findAllByAccessibilityLabel, find as findByAccessibilityLabel, };
+//# sourceMappingURL=accessibility-label-queries.d.ts.map

package/dist/accessibility-label-queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessibility-label-queries.d.ts","sourceRoot":"","sources":["../src/accessibility-label-queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EAGxB,KAAK,qBAAqB,EAG3B,MAAM,sBAAsB,CAAC;AAgC9B;;GAEG;AACH,QAAA,MAAM,QAAQ,EAAmC,CAC/C,CAAC,SAAS,WAAW,GAAG,WAAW,EAEnC,GAAG,IAAI,EAAE,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,KACxC,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;AAExC;;;GAGG;AACH,QAAA,MAAM,KAAK,EAAc,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC3D,GAAG,IAAI,EAAE,UAAU,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,KAC1C,UAAU,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC;AAE1C;;;GAGG;AACH,QAAA,MAAM,MAAM,EAAe,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC7D,GAAG,IAAI,EAAE,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,KACxC,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;AAExC;;;GAGG;AACH,QAAA,MAAM,GAAG,EAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EACvD,GAAG,IAAI,EAAE,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,KACxC,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;AAExC;;;GAGG;AACH,QAAA,MAAM,OAAO,EAAgB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC/D,GAAG,IAAI,EAAE,UAAU,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,KAC5C,UAAU,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC;AAE5C;;;GAGG;AACH,QAAA,MAAM,IAAI,EAAa,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EACzD,GAAG,IAAI,EAAE,UAAU,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,KACzC,UAAU,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;AAEzC,OAAO,EACL,QAAQ,IAAI,4BAA4B,EACxC,KAAK,IAAI,yBAAyB,EAClC,MAAM,IAAI,0BAA0B,EACpC,GAAG,IAAI,uBAAuB,EAC9B,OAAO,IAAI,2BAA2B,EACtC,IAAI,IAAI,wBAAwB,GACjC,CAAC"}

package/dist/accessibility-label-queries.js

@@ -0,0 +1,53 @@
+/**
+ * Queries that find an element by its `accessibility-label`, the text a
+ * screen reader reads for it on Lynx.
+ *
+ * Testing Library's `*ByLabelText` reads `<label>` elements and the ARIA
+ * label attributes, none of which Lynx has: a Lynx element gets its
+ * accessible name from `accessibility-label`. Like `*ByTitle` and
+ * `*ByAltText`, which also match one attribute, these take a TextMatch with
+ * MatcherOptions (`exact`, `normalizer`), throw errors worded the same way,
+ * and their `find*` variants retry for `waitFor`'s timeout.
+ */
+import { buildQueries, queryHelpers, } from '@testing-library/dom';
+/**
+ * Every element in `container` whose `accessibility-label` matches `label`.
+ * `buildQueries` names the other variants' suggestions after this function,
+ * so it keeps Testing Library's `queryAllBy*` name.
+ */
+const queryAllByAccessibilityLabel = (container, label, options) => queryHelpers.queryAllByAttribute('accessibility-label', container, label, options);
+const [queryBy, getAllBy, getBy, findAllBy, findBy] = buildQueries(queryAllByAccessibilityLabel, (_container, label) => `Found multiple elements with the accessibility-label: ${label}`, (_container, label) => `Unable to find an element with the accessibility-label: ${label}`);
+// buildQueries returns HTMLElement-typed functions. Testing Library declares
+// its own queries generic over the element type, so these are cast to the
+// same shape: getByAccessibilityLabel<TextElement>(...) works like
+// getByTitle<TextElement>(...).
+/**
+ * Finds every element whose `accessibility-label` matches, or none.
+ */
+const queryAll = queryAllByAccessibilityLabel;
+/**
+ * Finds the element whose `accessibility-label` matches, or null. Throws when
+ * more than one does.
+ */
+const query = queryBy;
+/**
+ * Finds every element whose `accessibility-label` matches. Throws when none
+ * does.
+ */
+const getAll = getAllBy;
+/**
+ * Finds the element whose `accessibility-label` matches. Throws when none or
+ * more than one does.
+ */
+const get = getBy;
+/**
+ * Waits for elements whose `accessibility-label` matches, as `getAll` finds
+ * them.
+ */
+const findAll = findAllBy;
+/**
+ * Waits for the element whose `accessibility-label` matches, as `get` finds
+ * it.
+ */
+const find = findBy;
+export { queryAll as queryAllByAccessibilityLabel, query as queryByAccessibilityLabel, getAll as getAllByAccessibilityLabel, get as getByAccessibilityLabel, findAll as findAllByAccessibilityLabel, find as findByAccessibilityLabel, };

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/dist/index.d.ts

@@ -2,5 +2,8 @@ export { render, cleanup, waitForUpdate } from './render.js';
 export type { RenderOptions, RenderResult } from './render.js';
 export type { ComponentRef } from '@angular/core';
 export { fireEvent, eventMap } from './fire-event.js';
-export { screen, within, getQueriesForElement } from '@testing-library/dom';
+export { screen, within, getQueriesForElement, queries } from './queries.js';
+export type { BoundAccessibilityLabelQueries, BoundLynxQueries, LynxQueries, LynxScreen, } from './queries.js';
+export { queryAllByAccessibilityLabel, queryByAccessibilityLabel, getAllByAccessibilityLabel, getByAccessibilityLabel, findAllByAccessibilityLabel, findByAccessibilityLabel, } from './accessibility-label-queries.js';
+export { queryAllByRole, queryByRole, getAllByRole, getByRole, findAllByRole, findByRole, } from './role-queries.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7D,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7D,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC7E,YAAY,EACV,8BAA8B,EAC9B,gBAAgB,EAChB,WAAW,EACX,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,4BAA4B,EAC5B,yBAAyB,EACzB,0BAA0B,EAC1B,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,cAAc,EACd,WAAW,EACX,YAAY,EACZ,SAAS,EACT,aAAa,EACb,UAAU,GACX,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,6 +1,8 @@
 export { render, cleanup, waitForUpdate } from './render.js';
 export { fireEvent, eventMap } from './fire-event.js';
-export { screen, within, getQueriesForElement } from '@testing-library/dom';
+export { screen, within, getQueriesForElement, queries } from './queries.js';
+export { queryAllByAccessibilityLabel, queryByAccessibilityLabel, getAllByAccessibilityLabel, getByAccessibilityLabel, findAllByAccessibilityLabel, findByAccessibilityLabel, } from './accessibility-label-queries.js';
+export { queryAllByRole, queryByRole, getAllByRole, getByRole, findAllByRole, findByRole, } from './role-queries.js';
 import { cleanup } from './render.js';
 /**
  * Auto-cleanup after each test (matches @testing-library/react convention).

package/dist/queries.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The queries a test gets from `render()`, `screen` and `within()`: Testing
+ * Library's, with `*ByRole` replaced by the Lynx-aware version and the
+ * `*ByAccessibilityLabel` queries added.
+ */
+import { type BoundFunction, type BoundFunctions, type FindAllByBoundAttribute, type FindByBoundAttribute, type GetByBoundAttribute, type AllByBoundAttribute, type Queries, type QueryByBoundAttribute, type Screen, queries as domQueries } from '@testing-library/dom';
+/**
+ * Every query, unbound: Testing Library's, with the Lynx-aware `*ByRole` and
+ * the `*ByAccessibilityLabel` queries. Spread it into your own queries to
+ * keep these next to them, as with Testing Library's `queries`.
+ */
+export declare const queries: {
+    queryAllByRole: typeof domQueries.queryAllByRole;
+    queryByRole: typeof domQueries.queryByRole;
+    getAllByRole: typeof domQueries.getAllByRole;
+    getByRole: typeof domQueries.getByRole;
+    findAllByRole: typeof domQueries.findAllByRole;
+    findByRole: typeof domQueries.findByRole;
+    queryAllByAccessibilityLabel: <T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined) => ReturnType<AllByBoundAttribute<T>>;
+    queryByAccessibilityLabel: <T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined) => ReturnType<QueryByBoundAttribute<T>>;
+    getAllByAccessibilityLabel: <T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined) => ReturnType<AllByBoundAttribute<T>>;
+    getByAccessibilityLabel: <T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined) => ReturnType<GetByBoundAttribute<T>>;
+    findAllByAccessibilityLabel: <T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined) => ReturnType<FindAllByBoundAttribute<T>>;
+    findByAccessibilityLabel: <T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined) => ReturnType<FindByBoundAttribute<T>>;
+    getByLabelText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").SelectorMatcherOptions | undefined): ReturnType<domQueries.GetByText<T>>;
+    getAllByLabelText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").SelectorMatcherOptions | undefined): ReturnType<domQueries.AllByText<T>>;
+    queryByLabelText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").SelectorMatcherOptions | undefined): ReturnType<domQueries.QueryByText<T>>;
+    queryAllByLabelText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").SelectorMatcherOptions | undefined): ReturnType<domQueries.AllByText<T>>;
+    findByLabelText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").SelectorMatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined): ReturnType<domQueries.FindByText<T>>;
+    findAllByLabelText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").SelectorMatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined): ReturnType<domQueries.FindAllByText<T>>;
+    getByPlaceholderText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<GetByBoundAttribute<T>>;
+    getAllByPlaceholderText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<AllByBoundAttribute<T>>;
+    queryByPlaceholderText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<QueryByBoundAttribute<T>>;
+    queryAllByPlaceholderText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<AllByBoundAttribute<T>>;
+    findByPlaceholderText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined): ReturnType<FindByBoundAttribute<T>>;
+    findAllByPlaceholderText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined): ReturnType<FindAllByBoundAttribute<T>>;
+    getByText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").SelectorMatcherOptions | undefined): ReturnType<domQueries.GetByText<T>>;
+    getAllByText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").SelectorMatcherOptions | undefined): ReturnType<domQueries.AllByText<T>>;
+    queryByText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").SelectorMatcherOptions | undefined): ReturnType<domQueries.QueryByText<T>>;
+    queryAllByText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").SelectorMatcherOptions | undefined): ReturnType<domQueries.AllByText<T>>;
+    findByText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").SelectorMatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined): ReturnType<domQueries.FindByText<T>>;
+    findAllByText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").SelectorMatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined): ReturnType<domQueries.FindAllByText<T>>;
+    getByAltText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<GetByBoundAttribute<T>>;
+    getAllByAltText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<AllByBoundAttribute<T>>;
+    queryByAltText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<QueryByBoundAttribute<T>>;
+    queryAllByAltText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<AllByBoundAttribute<T>>;
+    findByAltText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined): ReturnType<FindByBoundAttribute<T>>;
+    findAllByAltText<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined): ReturnType<FindAllByBoundAttribute<T>>;
+    getByTitle<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<GetByBoundAttribute<T>>;
+    getAllByTitle<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<AllByBoundAttribute<T>>;
+    queryByTitle<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<QueryByBoundAttribute<T>>;
+    queryAllByTitle<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<AllByBoundAttribute<T>>;
+    findByTitle<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined): ReturnType<FindByBoundAttribute<T>>;
+    findAllByTitle<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined): ReturnType<FindAllByBoundAttribute<T>>;
+    getByDisplayValue<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<GetByBoundAttribute<T>>;
+    getAllByDisplayValue<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<AllByBoundAttribute<T>>;
+    queryByDisplayValue<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<QueryByBoundAttribute<T>>;
+    queryAllByDisplayValue<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<AllByBoundAttribute<T>>;
+    findByDisplayValue<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined): ReturnType<FindByBoundAttribute<T>>;
+    findAllByDisplayValue<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined): ReturnType<FindAllByBoundAttribute<T>>;
+    getByTestId<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<GetByBoundAttribute<T>>;
+    getAllByTestId<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<AllByBoundAttribute<T>>;
+    queryByTestId<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<QueryByBoundAttribute<T>>;
+    queryAllByTestId<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined): ReturnType<AllByBoundAttribute<T>>;
+    findByTestId<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined): ReturnType<FindByBoundAttribute<T>>;
+    findAllByTestId<T extends HTMLElement = HTMLElement>(container: HTMLElement, id: import("@testing-library/dom").Matcher, options?: import("@testing-library/dom").MatcherOptions | undefined, waitForElementOptions?: import("@testing-library/dom").waitForOptions | undefined): ReturnType<FindAllByBoundAttribute<T>>;
+};
+export type LynxQueries = typeof queries;
+/**
+ * The `*ByAccessibilityLabel` queries bound to a container. Declared like
+ * Testing Library's bound queries, so each takes an element type:
+ * `getByAccessibilityLabel<MyElement>('Close')`.
+ */
+export type BoundAccessibilityLabelQueries = {
+    queryAllByAccessibilityLabel<T extends HTMLElement = HTMLElement>(...args: Parameters<BoundFunction<AllByBoundAttribute<T>>>): ReturnType<AllByBoundAttribute<T>>;
+    queryByAccessibilityLabel<T extends HTMLElement = HTMLElement>(...args: Parameters<BoundFunction<QueryByBoundAttribute<T>>>): ReturnType<QueryByBoundAttribute<T>>;
+    getAllByAccessibilityLabel<T extends HTMLElement = HTMLElement>(...args: Parameters<BoundFunction<AllByBoundAttribute<T>>>): ReturnType<AllByBoundAttribute<T>>;
+    getByAccessibilityLabel<T extends HTMLElement = HTMLElement>(...args: Parameters<BoundFunction<GetByBoundAttribute<T>>>): ReturnType<GetByBoundAttribute<T>>;
+    findAllByAccessibilityLabel<T extends HTMLElement = HTMLElement>(...args: Parameters<BoundFunction<FindAllByBoundAttribute<T>>>): ReturnType<FindAllByBoundAttribute<T>>;
+    findByAccessibilityLabel<T extends HTMLElement = HTMLElement>(...args: Parameters<BoundFunction<FindByBoundAttribute<T>>>): ReturnType<FindByBoundAttribute<T>>;
+};
+/**
+ * Every query, bound to a container.
+ */
+export type BoundLynxQueries = BoundAccessibilityLabelQueries & BoundFunctions<LynxQueries>;
+/**
+ * `screen`: every query bound to `document.body`, plus Testing Library's
+ * `debug()` and `logTestingPlaygroundURL()`.
+ */
+export type LynxScreen = BoundAccessibilityLabelQueries & Screen<LynxQueries>;
+/**
+ * Testing Library's `screen` with the Lynx queries in place of its own
+ * `*ByRole`, and the `*ByAccessibilityLabel` queries added.
+ */
+export declare const screen: LynxScreen;
+type Within = {
+    (element: HTMLElement): BoundLynxQueries;
+    <Q extends Queries>(element: HTMLElement, queriesToBind: Q): BoundFunctions<Q>;
+};
+/**
+ * Binds every query (or the ones you pass) to `element`, like Testing
+ * Library's `within()`, so a test can look inside one part of the tree.
+ */
+export declare const within: Within;
+/**
+ * The same as `within()`, under Testing Library's other name for it.
+ */
+export declare const getQueriesForElement: Within;
+export {};
+//# sourceMappingURL=queries.d.ts.map

package/dist/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,OAAO,EACZ,KAAK,qBAAqB,EAC1B,KAAK,MAAM,EAEX,OAAO,IAAI,UAAU,EAEtB,MAAM,sBAAsB,CAAC;AAoC9B;;;;GAIG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAoC,CAAC;AAEzD,MAAM,MAAM,WAAW,GAAG,OAAO,OAAO,CAAC;AAEzC;;;;GAIG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,4BAA4B,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,GAAG,IAAI,EAAE,UAAU,CAAC,aAAa,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,GACzD,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,yBAAyB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC3D,GAAG,IAAI,EAAE,UAAU,CAAC,aAAa,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC,GAC3D,UAAU,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,0BAA0B,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC5D,GAAG,IAAI,EAAE,UAAU,CAAC,aAAa,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,GACzD,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,uBAAuB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EACzD,GAAG,IAAI,EAAE,UAAU,CAAC,aAAa,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,GACzD,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,2BAA2B,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC7D,GAAG,IAAI,EAAE,UAAU,CAAC,aAAa,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC,GAC7D,UAAU,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,wBAAwB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC1D,GAAG,IAAI,EAAE,UAAU,CAAC,aAAa,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC,GAC1D,UAAU,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;CACxC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,8BAA8B,GAC3D,cAAc,CAAC,WAAW,CAAC,CAAC;AAE9B;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,8BAA8B,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;AAc9E;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,UAGN,CAAC;AAEhB,KAAK,MAAM,GAAG;IACZ,CAAC,OAAO,EAAE,WAAW,GAAG,gBAAgB,CAAC;IACzC,CAAC,CAAC,SAAS,OAAO,EAChB,OAAO,EAAE,WAAW,EACpB,aAAa,EAAE,CAAC,GACf,cAAc,CAAC,CAAC,CAAC,CAAC;CACtB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,MAAM,EAG+C,MAAM,CAAC;AAEzE;;GAEG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC"}

package/dist/queries.js

@@ -0,0 +1,56 @@
+/**
+ * The queries a test gets from `render()`, `screen` and `within()`: Testing
+ * Library's, with `*ByRole` replaced by the Lynx-aware version and the
+ * `*ByAccessibilityLabel` queries added.
+ */
+import { getQueriesForElement as getDomQueriesForElement, queries as domQueries, screen as domScreen, } from '@testing-library/dom';
+import { findAllByAccessibilityLabel, findByAccessibilityLabel, getAllByAccessibilityLabel, getByAccessibilityLabel, queryAllByAccessibilityLabel, queryByAccessibilityLabel, } from './accessibility-label-queries.js';
+import { findAllByRole, findByRole, getAllByRole, getByRole, queryAllByRole, queryByRole, } from './role-queries.js';
+/**
+ * The queries this library adds to Testing Library's or replaces in them.
+ */
+const lynxQueries = {
+    queryAllByRole,
+    queryByRole,
+    getAllByRole,
+    getByRole,
+    findAllByRole,
+    findByRole,
+    queryAllByAccessibilityLabel,
+    queryByAccessibilityLabel,
+    getAllByAccessibilityLabel,
+    getByAccessibilityLabel,
+    findAllByAccessibilityLabel,
+    findByAccessibilityLabel,
+};
+/**
+ * Every query, unbound: Testing Library's, with the Lynx-aware `*ByRole` and
+ * the `*ByAccessibilityLabel` queries. Spread it into your own queries to
+ * keep these next to them, as with Testing Library's `queries`.
+ */
+export const queries = { ...domQueries, ...lynxQueries };
+/**
+ * Binds `toBind` to `document.body`, looked up on each call rather than when
+ * this module loads, so importing the library doesn't need a document.
+ */
+const bindToBody = (toBind) => Object.fromEntries(Object.entries(toBind).map(([key, query]) => [
+    key,
+    (...args) => query(document.body, ...args),
+]));
+/**
+ * Testing Library's `screen` with the Lynx queries in place of its own
+ * `*ByRole`, and the `*ByAccessibilityLabel` queries added.
+ */
+export const screen = {
+    ...domScreen,
+    ...bindToBody(lynxQueries),
+};
+/**
+ * Binds every query (or the ones you pass) to `element`, like Testing
+ * Library's `within()`, so a test can look inside one part of the tree.
+ */
+export const within = ((element, queriesToBind = queries) => getDomQueriesForElement(element, queriesToBind));
+/**
+ * The same as `within()`, under Testing Library's other name for it.
+ */
+export const getQueriesForElement = within;

package/dist/render.d.ts

@@ -10,20 +10,22 @@
  *      → Angular renders tree → __CreateView/Text/… → JSDOM children
  *      → LynxRendererFactory2.end() → __FlushElementTree() (no-op in tests)
  *   3. appRef.tick() forces synchronous CD so all signal-driven updates land
- *   4. Return JSDOM container + @testing-library/dom queries
+ *   4. Return JSDOM container + queries (@testing-library/dom's, with the
+ *      Lynx-aware *ByRole and *ByAccessibilityLabel; see queries.ts)
  */
 import { type ComponentRef, type EnvironmentProviders, type Provider, type Type } from '@angular/core';
-import { type BoundFunctions, type Queries, queries as domQueries } from '@testing-library/dom';
-export type RenderOptions<Q extends Queries = typeof domQueries> = {
+import { type BoundFunctions, type Queries } from '@testing-library/dom';
+import { type BoundLynxQueries, type LynxQueries } from './queries.js';
+export type RenderOptions<Q extends Queries = LynxQueries> = {
     providers?: (Provider | EnvironmentProviders)[];
     /**
-     * Custom query helpers to merge with the standard `@testing-library/dom` queries.
+     * Custom query helpers to merge with the library's queries (see queries.ts).
      * Each helper receives the container as its first argument when bound.
      * Workaround if omitted: call `getQueriesForElement(container, customQueries)` directly.
      */
     queries?: Q;
 };
-export type RenderResult<Q extends Queries = typeof domQueries> = {
+export type RenderResult<Q extends Queries = LynxQueries> = {
     /**
      * The JSDOM root element (page element) containing all rendered children.
      */
@@ -55,9 +57,9 @@ export type RenderResult<Q extends Queries = typeof domQueries> = {
      * expose writable signals on the component instance instead.
      */
     componentRef: ComponentRef<unknown>;
-} & BoundFunctions<typeof domQueries> & BoundFunctions<Q>;
+} & BoundLynxQueries & BoundFunctions<Q>;
 export declare const cleanup: () => void;
-export declare const render: <Q extends Queries = typeof domQueries>(rootComponent: Type<unknown>, options?: RenderOptions<Q>) => Promise<RenderResult<Q>>;
+export declare const render: <Q extends Queries = LynxQueries>(rootComponent: Type<unknown>, options?: RenderOptions<Q>) => Promise<RenderResult<Q>>;
 /**
  * Wait for all pending Angular reactive updates to flush through the pipeline.
  * Call this after programmatic signal changes that happen outside event handlers.

package/dist/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,QAAQ,EAEb,KAAK,IAAI,EACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,OAAO,IAAI,UAAU,EAEtB,MAAM,sBAAsB,CAAC;AAG9B,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,UAAU,IAAI;IACjE,SAAS,CAAC,EAAE,CAAC,QAAQ,GAAG,oBAAoB,CAAC,EAAE,CAAC;IAChD;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,UAAU,IAAI;IAChE;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAC,SAAS,OAAO,GAAG,CAAC,EAC9B,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,EACxB,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,KACvB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B;;OAEG;IACH,UAAU,EAAE,MAAM,gBAAgB,CAAC;IACnC;;;;;;;;;;;;OAYG;IACH,YAAY,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;CACrC,GAAG,cAAc,CAAC,OAAO,UAAU,CAAC,GACnC,cAAc,CAAC,CAAC,CAAC,CAAC;AAIpB,eAAO,MAAM,OAAO,QAAO,IAM1B,CAAC;AAEF,eAAO,MAAM,MAAM,GAAU,CAAC,SAAS,OAAO,GAAG,OAAO,UAAU,EAChE,eAAe,IAAI,CAAC,OAAO,CAAC,EAC5B,UAAS,aAAa,CAAC,CAAC,CAA0B,KACjD,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAkDzB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,QAAa,OAAO,CAAC,IAAI,CAKlD,CAAC"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,QAAQ,EAEb,KAAK,IAAI,EACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,OAAO,EAEb,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,WAAW,EAAW,MAAM,cAAc,CAAC;AAEhF,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,OAAO,GAAG,WAAW,IAAI;IAC3D,SAAS,CAAC,EAAE,CAAC,QAAQ,GAAG,oBAAoB,CAAC,EAAE,CAAC;IAChD;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,OAAO,GAAG,WAAW,IAAI;IAC1D;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAC,SAAS,OAAO,GAAG,CAAC,EAC9B,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,EACxB,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,KACvB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B;;OAEG;IACH,UAAU,EAAE,MAAM,gBAAgB,CAAC;IACnC;;;;;;;;;;;;OAYG;IACH,YAAY,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;CACrC,GAAG,gBAAgB,GAClB,cAAc,CAAC,CAAC,CAAC,CAAC;AAIpB,eAAO,MAAM,OAAO,QAAO,IAM1B,CAAC;AAEF,eAAO,MAAM,MAAM,GAAU,CAAC,SAAS,OAAO,GAAG,WAAW,EAC1D,eAAe,IAAI,CAAC,OAAO,CAAC,EAC5B,UAAS,aAAa,CAAC,CAAC,CAA0B,KACjD,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAkDzB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,QAAa,OAAO,CAAC,IAAI,CAKlD,CAAC"}

package/dist/render.js

@@ -10,12 +10,14 @@
  *      → Angular renders tree → __CreateView/Text/… → JSDOM children
  *      → LynxRendererFactory2.end() → __FlushElementTree() (no-op in tests)
  *   3. appRef.tick() forces synchronous CD so all signal-driven updates land
- *   4. Return JSDOM container + @testing-library/dom queries
+ *   4. Return JSDOM container + queries (@testing-library/dom's, with the
+ *      Lynx-aware *ByRole and *ByAccessibilityLabel; see queries.ts)
  */
 import { provideZonelessChangeDetection, } from '@angular/core';
 import { bootstrapApplication } from '@angular/platform-browser';
-import { queries as domQueries, getQueriesForElement, } from '@testing-library/dom';
+import { getQueriesForElement, } from '@testing-library/dom';
 import { provideRenderer } from '@blotch/angular-lynx';
+import { queries } from './queries.js';
 let currentAppRef = null;
 export const cleanup = () => {
     if (currentAppRef) {
@@ -57,7 +59,7 @@ export const render = async (rootComponent, options = {}) => {
         asFragment: () => document.createRange().createContextualFragment(container.outerHTML),
         componentRef,
         ...getQueriesForElement(container, {
-            ...domQueries,
+            ...queries,
             ...options.queries,
         }),
     };

package/dist/role-queries.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `*ByRole` queries that read Lynx's accessibility attributes.
+ *
+ * Testing Library works out an element's role from `role` and HTML, and its
+ * name and state from `aria-*` attributes. A Lynx element has none of those,
+ * so on a Lynx tree Testing Library's `getByRole` found almost nothing: a
+ * `<view accessibility-traits="button">` has no ARIA role. These queries add
+ * what Lynx gives screen readers, read the way Lynx's native code reads it,
+ * to what Testing Library finds (a Lynx `<input>` is still a
+ * textbox):
+ *
+ * - Role: each trait in `accessibility-traits` that names a kind of element
+ *   (`TRAIT_ROLES`), or the element's own default: an `<image>` is an image.
+ * - Exposed: a screen reader reaches an element only when it's an
+ *   accessibility element. `<text>` and `<image>` are by default; anything
+ *   else needs `accessibility-element="true"`. The exception is a tab bar,
+ *   whose trait VoiceOver reads from the container around the tabs.
+ *   `accessibility-elements-hidden` hides an element and everything inside
+ *   it. With `hidden: false`, the default, the rest are left out, as Testing
+ *   Library leaves out what's off the accessibility tree.
+ * - Name: `accessibility-label`, or a `<text>`'s own text when it has none.
+ *   Lynx gives no other element a name from the text inside it: iOS reads an
+ *   accessibility element's label and skips its children.
+ * - State: the `selected` trait is `selected: true`, and `accessibility-value`
+ *   is `value: { text }`. Lynx has no other ARIA state.
+ *
+ * They take Testing Library's ByRoleOptions and throw its error messages.
+ */
+import { queries as domQueries } from '@testing-library/dom';
+declare const queryAll: typeof domQueries.queryAllByRole;
+declare const query: typeof domQueries.queryByRole;
+declare const getAll: typeof domQueries.getAllByRole;
+declare const get: typeof domQueries.getByRole;
+declare const findAll: typeof domQueries.findAllByRole;
+declare const find: typeof domQueries.findByRole;
+export { queryAll as queryAllByRole, query as queryByRole, getAll as getAllByRole, get as getByRole, findAll as findAllByRole, find as findByRole, };
+//# sourceMappingURL=role-queries.d.ts.map

package/dist/role-queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-queries.d.ts","sourceRoot":"","sources":["../src/role-queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAQL,OAAO,IAAI,UAAU,EACtB,MAAM,sBAAsB,CAAC;AAmW9B,QAAA,MAAM,QAAQ,EAAqB,OAAO,UAAU,CAAC,cAAc,CAAC;AACpE,QAAA,MAAM,KAAK,EAAc,OAAO,UAAU,CAAC,WAAW,CAAC;AACvD,QAAA,MAAM,MAAM,EAAe,OAAO,UAAU,CAAC,YAAY,CAAC;AAC1D,QAAA,MAAM,GAAG,EAAY,OAAO,UAAU,CAAC,SAAS,CAAC;AACjD,QAAA,MAAM,OAAO,EAAgB,OAAO,UAAU,CAAC,aAAa,CAAC;AAC7D,QAAA,MAAM,IAAI,EAAa,OAAO,UAAU,CAAC,UAAU,CAAC;AAEpD,OAAO,EACL,QAAQ,IAAI,cAAc,EAC1B,KAAK,IAAI,WAAW,EACpB,MAAM,IAAI,YAAY,EACtB,GAAG,IAAI,SAAS,EAChB,OAAO,IAAI,aAAa,EACxB,IAAI,IAAI,UAAU,GACnB,CAAC"}

package/dist/role-queries.js

@@ -0,0 +1,292 @@
+/**
+ * `*ByRole` queries that read Lynx's accessibility attributes.
+ *
+ * Testing Library works out an element's role from `role` and HTML, and its
+ * name and state from `aria-*` attributes. A Lynx element has none of those,
+ * so on a Lynx tree Testing Library's `getByRole` found almost nothing: a
+ * `<view accessibility-traits="button">` has no ARIA role. These queries add
+ * what Lynx gives screen readers, read the way Lynx's native code reads it,
+ * to what Testing Library finds (a Lynx `<input>` is still a
+ * textbox):
+ *
+ * - Role: each trait in `accessibility-traits` that names a kind of element
+ *   (`TRAIT_ROLES`), or the element's own default: an `<image>` is an image.
+ * - Exposed: a screen reader reaches an element only when it's an
+ *   accessibility element. `<text>` and `<image>` are by default; anything
+ *   else needs `accessibility-element="true"`. The exception is a tab bar,
+ *   whose trait VoiceOver reads from the container around the tabs.
+ *   `accessibility-elements-hidden` hides an element and everything inside
+ *   it. With `hidden: false`, the default, the rest are left out, as Testing
+ *   Library leaves out what's off the accessibility tree.
+ * - Name: `accessibility-label`, or a `<text>`'s own text when it has none.
+ *   Lynx gives no other element a name from the text inside it: iOS reads an
+ *   accessibility element's label and skips its children.
+ * - State: the `selected` trait is `selected: true`, and `accessibility-value`
+ *   is `value: { text }`. Lynx has no other ARIA state.
+ *
+ * They take Testing Library's ByRoleOptions and throw its error messages.
+ */
+import { buildQueries, getConfig, getRoles, isInaccessible, prettyDOM, queries as domQueries, } from '@testing-library/dom';
+/**
+ * The ARIA role of each Lynx trait that names a kind of element, as
+ * Testing Library spells it. iOS turns each trait into a UIAccessibilityTraits
+ * flag (`LynxConverter+UI.m`): `image` is UIAccessibilityTraitImage, the
+ * `img` role; `header` is a heading; `search`, a search field, is a searchbox;
+ * `adjustable`, a control swiped up and down through values, is a slider;
+ * and `tabbar`, a tab bar, is a tablist. The other traits describe state (`selected`,
+ * `disabled`, `updating`), behavior (`playable`, `keyboard`, `summary`), or
+ * plain text (`text`), which has no ARIA role.
+ */
+const TRAIT_ROLES = new Map([
+    ['button', 'button'],
+    ['link', 'link'],
+    ['image', 'img'],
+    ['header', 'heading'],
+    ['search', 'searchbox'],
+    ['adjustable', 'slider'],
+    ['tabbar', 'tablist'],
+]);
+/**
+ * The roles a screen reader reads from a container, not from an
+ * accessibility element. VoiceOver reads the tab bar trait from the view
+ * around the tabs, which can't be an accessibility element itself: that
+ * would hide the tabs inside it.
+ */
+const CONTAINER_ROLES = new Set(['tablist']);
+/**
+ * Testing Library refuses a state that ARIA doesn't define for the role, such
+ * as `selected` on a button. Lynx has `selected` (a trait) and a value
+ * (`accessibility-value`) on any element, so asking for them isn't a mistake
+ * here. It only means no element can match by ARIA.
+ */
+const UNSUPPORTED_ARIA_STATE = /^"aria-(selected|valuetext)" is not supported on role /;
+/**
+ * Whether `text` matches `matcher`. Text the element doesn't have (null)
+ * matches nothing.
+ */
+const matchesText = (text, element, matcher) => {
+    if (text === null)
+        return false;
+    if (typeof matcher === 'function')
+        return matcher(text, element);
+    if (matcher instanceof RegExp) {
+        const match = matcher.test(text);
+        // A global or sticky RegExp carries on from where the last test() left
+        // off, so the next element is tested from the start, as Testing Library
+        // does.
+        matcher.lastIndex = 0;
+        return match;
+    }
+    return text === String(matcher);
+};
+/**
+ * The element's traits. iOS splits `accessibility-traits` on commas and
+ * doesn't trim them, so `"button, selected"` isn't selected there: they're
+ * read the same way here. Android and HarmonyOS read the attribute as one
+ * trait, so a list only works on iOS. Without the attribute, an `<image>` has
+ * the image trait, Lynx's default for it (`LynxUIImage`), which
+ * `accessibility-traits="none"` takes away.
+ */
+const traitsOf = (element) => element.getAttribute('accessibility-traits')?.split(',') ??
+    (element.localName === 'image' ? ['image'] : []);
+/**
+ * The ARIA roles the element's traits give it.
+ */
+const lynxRolesOf = (element) => traitsOf(element).flatMap((trait) => TRAIT_ROLES.get(trait) ?? []);
+/**
+ * Whether the element is an accessibility element, one stop for a screen
+ * reader. Lynx makes `<text>` and `<image>` accessibility elements by default
+ * and nothing else, so a `<view>` is one only with
+ * `accessibility-element="true"`. The attribute holds a string, so any value
+ * but "false" is true, as the element directives' boolean inputs read it.
+ */
+const isAccessibilityElement = (element) => {
+    const flag = element.getAttribute('accessibility-element');
+    return flag === null
+        ? element.localName === 'text' || element.localName === 'image'
+        : flag !== 'false';
+};
+/**
+ * Whether a screen reader reads `role` on the element: from an accessibility
+ * element, or from a container for a container role, as long as nothing
+ * hides it.
+ */
+const exposesRole = (element, role) => (isAccessibilityElement(element) || CONTAINER_ROLES.has(role)) &&
+    element.closest('[accessibility-elements-hidden]:not([accessibility-elements-hidden="false"])') === null &&
+    // Testing Library's own check catches what Lynx doesn't draw either, such
+    // as an element styled display: none.
+    !isInaccessible(element);
+/**
+ * What a screen reader reads as the element's name: its
+ * `accessibility-label`, or for a `<text>`, the text it shows (iOS and
+ * Android read that when the label is missing or empty).
+ */
+const lynxNameOf = (element) => element.getAttribute('accessibility-label') ||
+    (element.localName === 'text'
+        ? element.textContent.replace(/\s+/g, ' ').trim()
+        : '');
+/**
+ * Whether the element is in the states `options` asks for. Lynx has two:
+ * the `selected` trait, and the value in `accessibility-value`. For the rest
+ * it answers as Testing Library does for an element without the `aria-*`
+ * attribute: not busy and not current, and never pressed, expanded, at a
+ * level or at a number. `checked` never gets here: Testing Library refuses
+ * it on every role Lynx gives.
+ */
+const matchesState = (element, traits, { selected, busy, pressed, current, expanded, level, value = {}, }) => (selected === undefined || selected === traits.includes('selected')) &&
+    !busy &&
+    (current === undefined || current === false) &&
+    pressed === undefined &&
+    expanded === undefined &&
+    level === undefined &&
+    value.now === undefined &&
+    value.min === undefined &&
+    value.max === undefined &&
+    (value.text === undefined ||
+        matchesText(element.getAttribute('accessibility-value'), element, value.text));
+/**
+ * The elements Lynx gives `role`.
+ */
+const queryAllByLynxRole = (container, role, options) => {
+    const { hidden = getConfig().defaultHidden, name, description } = options;
+    return Array.from(container.querySelectorAll('*')).filter((element) => {
+        const traits = traitsOf(element);
+        return (traits.some((trait) => TRAIT_ROLES.get(trait) === role) &&
+            (hidden || exposesRole(element, role)) &&
+            matchesState(element, traits, options) &&
+            (name === undefined ||
+                matchesText(lynxNameOf(element), element, name)) &&
+            // Lynx has no accessible description.
+            (description === undefined || matchesText('', element, description)));
+    });
+};
+/**
+ * The elements Testing Library gives `role`, from `role` attributes and HTML
+ * elements. An `accessibility-label` still names them: Lynx reads it on any
+ * element, an `<input>` included.
+ */
+const queryAllByAriaRole = (container, role, options) => {
+    const { name } = options;
+    try {
+        return domQueries.queryAllByRole(container, role, {
+            ...options,
+            name: name === undefined
+                ? undefined
+                : (accessibleName, element) => matchesText(element.getAttribute('accessibility-label') || accessibleName, element, name),
+        });
+    }
+    catch (error) {
+        if (UNSUPPORTED_ARIA_STATE.test(error.message))
+            return [];
+        throw error;
+    }
+};
+/**
+ * Every element in `container` with `role`, whether Lynx or Testing Library
+ * gives it the role, in document order. Testing Library's query runs first,
+ * so a container that isn't an element fails with its message.
+ */
+const queryAllByRole = (container, role, options = {}) => {
+    const found = new Set([
+        ...queryAllByAriaRole(container, role, options),
+        ...queryAllByLynxRole(container, role, options),
+    ]);
+    return Array.from(container.querySelectorAll('*')).filter((element) => found.has(element));
+};
+/**
+ * Describes a name or description matcher for an error message, as Testing
+ * Library does: a string in quotes, anything else in backticks.
+ */
+const describeMatcher = (label, matcher) => {
+    if (matcher === undefined)
+        return '';
+    return typeof matcher === 'string'
+        ? ` and ${label} "${matcher}"`
+        : ` and ${label} \`${String(matcher)}\``;
+};
+/**
+ * Lists the roles in `container` with each element's name and markup, as
+ * Testing Library's error does, including the roles Lynx gives.
+ */
+const prettyRoles = (container, hidden) => {
+    // A Set per role lists an element once, even when both Lynx and Testing
+    // Library give it the role.
+    const elementsByRole = new Map();
+    const add = (role, element) => {
+        elementsByRole.set(role, (elementsByRole.get(role) ?? new Set()).add(element));
+    };
+    for (const element of Array.from(container.querySelectorAll('*'))) {
+        for (const role of lynxRolesOf(element)) {
+            if (hidden || exposesRole(element, role))
+                add(role, element);
+        }
+    }
+    // getRoles() takes the hidden option, though its types leave it out.
+    const getAriaRoles = getRoles;
+    // Testing Library lists each child's roles, which leaves out the container.
+    for (const child of Array.from(container.children)) {
+        for (const [role, elements] of Object.entries(getAriaRoles(child, { hidden }))) {
+            // Testing Library leaves the generic role out of its list too.
+            if (role !== 'generic')
+                elements.forEach((el) => add(role, el));
+        }
+    }
+    return Array.from(elementsByRole)
+        .map(([role, elements]) => {
+        const described = Array.from(elements)
+            .map((element) => `Name "${lynxNameOf(element)}":\n${prettyDOM(element.cloneNode(false))}`)
+            .join('\n\n');
+        return `${role}:\n\n${described}\n\n${'-'.repeat(50)}`;
+    })
+        .join('\n');
+};
+/**
+ * The error message when no element has the role, worded as Testing
+ * Library's and followed by what Lynx does differently: a trait whose role
+ * has another name, or elements with the role that screen readers can't
+ * reach.
+ */
+const getMissingError = (container, role, options = {}) => {
+    const { hidden = getConfig().defaultHidden, name, description } = options;
+    const nameHint = describeMatcher('name', name);
+    const traitRole = TRAIT_ROLES.get(role);
+    const traitHint = traitRole !== undefined && traitRole !== role
+        ? `\n\nLynx's ${role} trait is the "${traitRole}" role, so query by "${traitRole}".`
+        : '';
+    // waitFor() turns expensive diagnostics off while it retries a find*
+    // query, and Testing Library then says only which role it looked for.
+    if (getConfig()
+        ._disableExpensiveErrorDiagnostics) {
+        return `Unable to find role="${role}"${nameHint}${traitHint}`;
+    }
+    const searched = container;
+    const roles = prettyRoles(searched, hidden);
+    let roleMessage;
+    if (roles.length === 0) {
+        roleMessage = hidden
+            ? 'There are no available roles.'
+            : 'There are no accessible roles. But there might be some inaccessible roles. If you wish to access them, then set the `hidden` option to `true`. Learn more about this here: https://testing-library.com/docs/dom-testing-library/api-queries#byrole';
+    }
+    else {
+        roleMessage =
+            `Here are the ${hidden ? 'available' : 'accessible'} roles:\n\n  ${roles
+                .replace(/\n/g, '\n  ')
+                .replace(/\n\s\s\n/g, '\n\n')}`.trim();
+    }
+    const unexposedHint = !hidden &&
+        queryAllByLynxRole(searched, role, { hidden: true }).some((element) => !exposesRole(element, role))
+        ? `\n\nSome elements with the role "${role}" are hidden from screen readers. Lynx reaches an element other than <text> and <image> only when it sets accessibility-element="true", and nothing inside accessibility-elements-hidden="true". Set the \`hidden\` option to \`true\` to include them.`
+        : '';
+    return `Unable to find an ${hidden ? '' : 'accessible '}element with the role "${role}"${nameHint}${describeMatcher('description', description)}\n\n${roleMessage}${traitHint}${unexposedHint}`;
+};
+const [queryBy, getAllBy, getBy, findAllBy, findBy] = buildQueries(queryAllByRole, (_container, role, { name } = {}) => `Found multiple elements with the role "${role}"${describeMatcher('name', name)}`, getMissingError);
+// buildQueries returns HTMLElement-typed functions. These take the generic
+// types of Testing Library's own role queries, so they stand in for them
+// anywhere, getByRole<TextElement>(...) included.
+const queryAll = queryAllByRole;
+const query = queryBy;
+const getAll = getAllBy;
+const get = getBy;
+const findAll = findAllBy;
+const find = findBy;
+export { queryAll as queryAllByRole, query as queryByRole, getAll as getAllByRole, get as getByRole, findAll as findAllByRole, find as findByRole, };

package/package.json

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