nativeproof 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to NativeProof are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/) and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## 0.8.0
+
+Relative locators — `Locator.near` scopes to the match nearest an anchor.
+
+**Added**
+
+- **`Locator.near(anchor, { maxDistance? })`** — orders this locator's matches by bounds-centre
+  distance to the `anchor` locator's match, nearest first, so a control is addressed by the element
+  beside it: `getByRole("checkbox").near(getByText("Wi-Fi"))` is the checkbox in the Wi-Fi row.
+  `maxDistance` (px) drops farther matches, so an absent control resolves to nothing. Composes with
+  `.nth()` / `.check()` / `expect(locator).toBeChecked()`. Together with role selectors this retires
+  source-bounds geometry for "the control next to this label".
+
 ## 0.7.0
 
 Role selectors — `getByRole` matches by element role, not just name.

package/README.md

@@ -449,8 +449,15 @@ await p.getByText("Item").count();       // how many elements match
 await p.getByText("Item").nth(1).tap();  // the 2nd match (.first() / .last(); negative counts from the end)
 await member.terms.check();              // checkbox/switch → tap to checked (no-op if already there); also uncheck()
 await member.terms.isChecked();          // boolean
+await p.getByRole("checkbox").near(p.getByText("Wi-Fi")).check(); // the checkbox in the Wi-Fi row
 ```
 
+**Relative locators.** `getByRole(role)` matches by element class/type (`checkbox`, `switch`, `button`,
+`textfield`, `image`), and `Locator.near(anchor, { maxDistance? })` scopes to the match nearest an
+anchor's element — so a control beside a label is addressed by the label, not by coordinates:
+`page(driver).getByRole("checkbox").near(page(driver).getByText("Wi-Fi"))`. Compose with `.check()` /
+`expect(locator).toBeChecked()`.
+
 `tap()` resolves the element's bounds from the page source and taps the centre — a coordinate
 tap that works even on Compose / SwiftUI nodes Appium reports as non-clickable.
 

package/dist/locator.d.ts

@@ -74,18 +74,36 @@ export declare class Locator {
     private readonly options;
     /** When set, the locator resolves to the nth match (negative counts from the end). */
     private readonly index?;
+    /** When set, matches are ordered by proximity to the anchor (and filtered by maxDistance). */
+    private readonly proximity?;
     constructor(driver: Driver, selector: Selector, options?: WaitOptions, 
     /** When set, the locator resolves to the nth match (negative counts from the end). */
-    index?: number | undefined);
+    index?: number | undefined, 
+    /** When set, matches are ordered by proximity to the anchor (and filtered by maxDistance). */
+    proximity?: {
+        anchor: Locator;
+        maxDistance?: number;
+    } | undefined);
     private attribute;
     /** Node tags this selector matches in `source`, in document order (role- or attribute-based). */
     private nodesIn;
-    /** All node tags this selector matches in the current source, in document order. */
+    /**
+     * All node tags this selector matches in the current source — document order, or, when a
+     * `near` anchor is set, ordered nearest-first by bounds-centre distance (filtered by maxDistance).
+     */
     private matchedNodes;
     /** The single node this locator resolves to (the nth match, or the first when unindexed). */
     private pick;
     /** A locator scoped to the nth match (0-based; negative counts from the end). */
     nth(index: number): Locator;
+    /**
+     * Scope to the match nearest `anchor` (by bounds-centre distance) — the relative locator for
+     * native: `getByRole("checkbox").near(getByText("Wi-Fi"))` is the checkbox in the Wi-Fi row.
+     * `maxDistance` (px) drops matches farther than that, so an absent control resolves to nothing.
+     */
+    near(anchor: Locator, options?: {
+        maxDistance?: number;
+    }): Locator;
     /** A locator scoped to the first match. */
     first(): Locator;
     /** A locator scoped to the last match. */

package/dist/locator.js

@@ -66,13 +66,17 @@ export class Locator {
     selector;
     options;
     index;
+    proximity;
     constructor(driver, selector, options = {}, 
     /** When set, the locator resolves to the nth match (negative counts from the end). */
-    index) {
+    index, 
+    /** When set, matches are ordered by proximity to the anchor (and filtered by maxDistance). */
+    proximity) {
         this.driver = driver;
         this.selector = selector;
         this.options = options;
         this.index = index;
+        this.proximity = proximity;
     }
     attribute() {
         return attributeFor(this.selector, this.driver.platform);
@@ -83,9 +87,28 @@ export class Locator {
             ? nodesForRole(source, this.selector.value, this.driver.platform)
             : nodesForAttribute(source, this.attribute(), this.selector.value);
     }
-    /** All node tags this selector matches in the current source, in document order. */
+    /**
+     * All node tags this selector matches in the current source — document order, or, when a
+     * `near` anchor is set, ordered nearest-first by bounds-centre distance (filtered by maxDistance).
+     */
     async matchedNodes() {
-        return this.nodesIn(await this.driver.source());
+        const nodes = this.nodesIn(await this.driver.source());
+        if (!this.proximity)
+            return nodes;
+        const anchor = await this.proximity.anchor.bounds();
+        if (!anchor)
+            return [];
+        const { maxDistance } = this.proximity;
+        return nodes
+            .map((node) => ({ node, bounds: parseBounds(/bounds="([^"]+)"/.exec(node)?.[1]) }))
+            .filter((entry) => entry.bounds !== null)
+            .map((entry) => ({
+            node: entry.node,
+            distance: Math.hypot(entry.bounds.centerX - anchor.centerX, entry.bounds.centerY - anchor.centerY),
+        }))
+            .filter((entry) => maxDistance === undefined || entry.distance <= maxDistance)
+            .sort((a, b) => a.distance - b.distance)
+            .map((entry) => entry.node);
     }
     /** The single node this locator resolves to (the nth match, or the first when unindexed). */
     pick(nodes) {
@@ -96,7 +119,16 @@ export class Locator {
     }
     /** A locator scoped to the nth match (0-based; negative counts from the end). */
     nth(index) {
-        return new Locator(this.driver, this.selector, this.options, index);
+        return new Locator(this.driver, this.selector, this.options, index, this.proximity);
+    }
+    /**
+     * Scope to the match nearest `anchor` (by bounds-centre distance) — the relative locator for
+     * native: `getByRole("checkbox").near(getByText("Wi-Fi"))` is the checkbox in the Wi-Fi row.
+     * `maxDistance` (px) drops matches farther than that, so an absent control resolves to nothing.
+     */
+    near(anchor, options = {}) {
+        const proximity = options.maxDistance === undefined ? { anchor } : { anchor, maxDistance: options.maxDistance };
+        return new Locator(this.driver, this.selector, this.options, this.index, proximity);
     }
     /** A locator scoped to the first match. */
     first() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nativeproof",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "MIT",
   "type": "module",
   "description": "Native Mobile E2E test framework inspired by Playwright (fixtures, locators, expect, route-style mocking) on Appium/WebdriverIO.",