@qontinui/ui-bridge-native 0.6.12 → 0.6.14

package/README.md

@@ -5,9 +5,9 @@ UI Bridge framework for React Native applications. Enables AI-driven UI automati
 ## Installation
 
 ```bash
-npm install ui-bridge-native
+npm install @qontinui/ui-bridge-native
 # or
-yarn add ui-bridge-native
+yarn add @qontinui/ui-bridge-native
 ```
 
 ## Quick Start
@@ -16,7 +16,7 @@ yarn add ui-bridge-native
 
 ```tsx
 // app/_layout.tsx or App.tsx
-import { UIBridgeNativeProvider } from 'ui-bridge-native';
+import { UIBridgeNativeProvider } from '@qontinui/ui-bridge-native';
 
 export default function RootLayout() {
   return (
@@ -33,7 +33,7 @@ export default function RootLayout() {
 ### 2. Use hooks in your components
 
 ```tsx
-import { useUIElement } from 'ui-bridge-native';
+import { useUIElement } from '@qontinui/ui-bridge-native';
 
 function SubmitButton({ onPress }) {
   const { ref, onLayout, bridgeProps } = useUIElement({
@@ -180,6 +180,7 @@ await executeAction('submit-button', { action: 'press' });
 - `focus` - Focus element
 - `blur` - Blur element
 - `scroll` - Scroll
+- `scrollIntoView` - Scroll the element's declared `scrollAncestorId` container (vertical ScrollView / FlatList) so the element is on screen; advertised only on elements that declare one
 - `swipe` - Swipe gesture
 - `toggle` - Toggle switch/checkbox
 
@@ -196,16 +197,35 @@ The package includes an embedded HTTP server for external control. Configure wit
 
 ### API Endpoints
 
-| Method | Path                                                | Description              |
-| ------ | --------------------------------------------------- | ------------------------ |
-| GET    | `/ui-bridge/health`                                 | Health check             |
-| GET    | `/ui-bridge/control/elements`                       | List all elements        |
-| GET    | `/ui-bridge/control/element/:id`                    | Get element details      |
-| POST   | `/ui-bridge/control/element/:id/action`             | Execute action           |
-| GET    | `/ui-bridge/control/components`                     | List all components      |
-| POST   | `/ui-bridge/control/component/:id/action/:actionId` | Execute component action |
-| POST   | `/ui-bridge/control/find`                           | Find elements            |
-| GET    | `/ui-bridge/control/snapshot`                       | Get full snapshot        |
+The bridge serves **56** method+path pairs. Two of them tell you about the other
+54, so this README does not try to be the list — it went stale at 7 rows while
+the surface grew, and a partial table read as a complete one is worse than no
+table:
+
+| Method | Path                  | Description                                                  |
+| ------ | --------------------- | ------------------------------------------------------------ |
+| GET    | `/ui-bridge/_routes`  | Every mounted route as `{method, path}` — ask the live server |
+| GET    | `/ui-bridge/_help`    | The same list plus per-handler descriptions, actions and tips |
+
+```bash
+curl -s http://localhost:8087/ui-bridge/_routes | jq '.data.routes'
+```
+
+Statically, the same contract is the exported `UI_BRIDGE_NATIVE_ROUTES`:
+
+```ts
+import { UI_BRIDGE_NATIVE_ROUTES } from '@qontinui/ui-bridge-native';
+```
+
+Entries carrying `requiresTestHooks: true` are mounted only when the server
+config sets `testHooks`; a production build answers those with a plain 404.
+`route-table-parity.test.ts` pins the exported table against `_routes` in both
+directions, and separately at `testHooks: false`, so neither can drift from the
+router.
+
+A wrong verb on a path the bridge does publish answers **405** with an `Allow`
+header naming the verbs it accepts (and the same verbs in the JSON envelope's
+`error`); a path it does not publish answers **404**.
 
 ### Custom Server Adapter
 
@@ -219,7 +239,7 @@ The HTTP server requires a platform-specific adapter. See [documentation](./docs
 Built-in visual inspector for development:
 
 ```tsx
-import { UIBridgeInspector } from 'ui-bridge-native/debug';
+import { UIBridgeInspector } from '@qontinui/ui-bridge-native/debug';
 
 function App() {
   return (
@@ -236,7 +256,7 @@ function App() {
 Full TypeScript support included. Import types as needed:
 
 ```tsx
-import type { NativeElementState, NativeElementType, UseUIElementOptions } from 'ui-bridge-native';
+import type { NativeElementState, NativeElementType, UseUIElementOptions } from '@qontinui/ui-bridge-native';
 ```
 
 ## License

package/dist/control/action-executor.d.ts

@@ -7,7 +7,17 @@
  */
 import type { NativeUIBridgeRegistry } from '../core/registry';
 import type { NativeFindRequest, NativeFindResponse, WaitOptions } from '../core/types';
-import type { ControlActionRequest, ControlActionResponse, ComponentActionRequest, ComponentActionResponse, WaitResult, NativeActionExecutor, NativeActionListener } from './types';
+import type { ControlActionRequest, ControlActionResponse, ComponentActionRequest, ComponentActionResponse, ComponentActionInvokeOptions, WaitResult, NativeActionExecutor, NativeActionListener } from './types';
+/**
+ * An action failure that carries a machine-readable code of its own, so the
+ * HTTP handler can report it as that code instead of the generic
+ * `ACTION_FAILED`. Used for `NOT_SUPPORTED` — "this element cannot do that",
+ * which a caller must not retry with a different request shape.
+ */
+export declare class NativeActionError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
 /**
  * Default native action executor implementation
  */
@@ -73,6 +83,36 @@ export declare class DefaultNativeActionExecutor implements NativeActionExecutor
      * Perform scroll action
      */
     private performScroll;
+    /**
+     * Perform scrollIntoView: scroll the element's DECLARED scroll container so
+     * the element sits `padding` dp below the top of its viewport.
+     *
+     * The container comes from `scrollAncestorId` and nowhere else — the
+     * registry keeps no parent chain (`RegisterElementOptions.scrollAncestorId`),
+     * so there is no "nearest ScrollView" to find. Nothing here tracks a
+     * ScrollView's content offset either (`performScroll` only fakes an
+     * `onScroll` event), so the target is measured CONTENT-relative with
+     * `measureLayout` against the container's inner content view: stateless,
+     * and immune to a stale-offset race.
+     *
+     * Result shape mirrors the web executor's `scrollIntoView`
+     * (`@qontinui/ui-bridge` `control/action-executor.ts`):
+     * `{ alreadyVisible, scrolled }`, short-circuiting when the element is
+     * already fully inside its clip region. "Fully visible" is only claimed when
+     * it is MEASURED — a page-space rect for the element and a known,
+     * non-empty clip (window ∩ declared container), both measured at call
+     * time. Anything unknown scrolls.
+     *
+     * Containers: a ScrollView, or a VirtualizedList (FlatList / SectionList)
+     * unwrapped through `getNativeScrollRef()` / `getScrollResponder()`.
+     * Vertical only — a `horizontal` container is NOT_SUPPORTED. The action
+     * returns once `scrollTo` is dispatched; positions settle on the next frame.
+     *
+     * Prerequisites are checked BEFORE the visibility short-circuit, so whether
+     * the element supports the action does not depend on where it happens to be
+     * on screen. Each missing prerequisite is a `NOT_SUPPORTED` failure.
+     */
+    private performScrollIntoView;
     /**
      * Perform swipe action
      */
@@ -88,7 +128,7 @@ export declare class DefaultNativeActionExecutor implements NativeActionExecutor
     /**
      * Execute a component action
      */
-    executeComponentAction(componentId: string, request: ComponentActionRequest): Promise<ComponentActionResponse>;
+    executeComponentAction(componentId: string, request: ComponentActionRequest, options?: ComponentActionInvokeOptions): Promise<ComponentActionResponse>;
     /**
      * Find elements
      */

package/dist/control/action-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-executor.d.ts","sourceRoot":"","sources":["../../src/control/action-executor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAEV,iBAAiB,EACjB,kBAAkB,EAElB,WAAW,EACZ,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,UAAU,EACV,oBAAoB,EAEpB,oBAAoB,EAKrB,MAAM,SAAS,CAAC;AAqBjB;;GAEG;AACH,qBAAa,2BAA4B,YAAW,oBAAoB;IAG1D,OAAO,CAAC,QAAQ;IAF5B,OAAO,CAAC,eAAe,CAAmC;gBAEtC,QAAQ,EAAE,sBAAsB;IAEpD,gBAAgB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAO5D,uGAAuG;IACvG,OAAO,CAAC,eAAe;IAUvB;;OAEG;IACG,aAAa,CACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAwHjC;;OAEG;YACW,aAAa;IAyD3B;;OAEG;YACW,YAAY;IAmB1B;;OAEG;YACW,gBAAgB;IAa9B;;OAEG;YACW,gBAAgB;IAmB9B;;OAEG;YACW,WAAW;IA6CzB;;;;;;;;;;;;;OAaG;YACW,eAAe;IAiC7B;;OAEG;YACW,YAAY;IAkB1B;;OAEG;YACW,YAAY;IAa1B;;OAEG;YACW,WAAW;IAazB;;OAEG;YACW,aAAa;IAc3B;;OAEG;YACW,YAAY;IA4B1B;;OAEG;YACW,aAAa;IAiB3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;OAEG;IACG,sBAAsB,CAC1B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,uBAAuB,CAAC;IAmDnC;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA2DnE;;OAEG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAIlF;;OAEG;YACW,sBAAsB;CA4DrC;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,sBAAsB,GAAG,oBAAoB,CAEjG"}
+{"version":3,"file":"action-executor.d.ts","sourceRoot":"","sources":["../../src/control/action-executor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAEV,iBAAiB,EACjB,kBAAkB,EAElB,WAAW,EACZ,MAAM,eAAe,CAAC;AAevB,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,4BAA4B,EAC5B,UAAU,EACV,oBAAoB,EAEpB,oBAAoB,EAMrB,MAAM,SAAS,CAAC;AAcjB;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAGxC,QAAQ,CAAC,IAAI,EAAE,MAAM;gBADrB,OAAO,EAAE,MAAM,EACN,IAAI,EAAE,MAAM;CAKxB;AAkID;;GAEG;AACH,qBAAa,2BAA4B,YAAW,oBAAoB;IAG1D,OAAO,CAAC,QAAQ;IAF5B,OAAO,CAAC,eAAe,CAAmC;gBAEtC,QAAQ,EAAE,sBAAsB;IAEpD,gBAAgB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAO5D,uGAAuG;IACvG,OAAO,CAAC,eAAe;IAUvB;;OAEG;IACG,aAAa,CACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAyHjC;;OAEG;YACW,aAAa;IAmE3B;;OAEG;YACW,YAAY;IAmB1B;;OAEG;YACW,gBAAgB;IAa9B;;OAEG;YACW,gBAAgB;IAmB9B;;OAEG;YACW,WAAW;IA6CzB;;;;;;;;;;;;;OAaG;YACW,eAAe;IAiC7B;;OAEG;YACW,YAAY;IAkB1B;;OAEG;YACW,YAAY;IAa1B;;OAEG;YACW,WAAW;IAazB;;OAEG;YACW,aAAa;IAc3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;YACW,qBAAqB;IA2KnC;;OAEG;YACW,YAAY;IA4B1B;;OAEG;YACW,aAAa;IAiB3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;OAEG;IACG,sBAAsB,CAC1B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,sBAAsB,EAC/B,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,uBAAuB,CAAC;IAmJnC;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA2DnE;;OAEG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAIlF;;OAEG;YACW,sBAAsB;CA4DrC;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,sBAAsB,GAAG,oBAAoB,CAEjG"}