@qontinui/ui-bridge-native 0.1.2

package/README.md

@@ -0,0 +1,244 @@
+# ui-bridge-native
+
+UI Bridge framework for React Native applications. Enables AI-driven UI automation and testing for mobile apps.
+
+## Installation
+
+```bash
+npm install ui-bridge-native
+# or
+yarn add ui-bridge-native
+```
+
+## Quick Start
+
+### 1. Wrap your app in the provider
+
+```tsx
+// app/_layout.tsx or App.tsx
+import { UIBridgeNativeProvider } from 'ui-bridge-native';
+
+export default function RootLayout() {
+  return (
+    <UIBridgeNativeProvider
+      features={{ server: __DEV__, debug: __DEV__ }}
+      config={{ serverPort: 8087 }}
+    >
+      <Stack>{/* Your app content */}</Stack>
+    </UIBridgeNativeProvider>
+  );
+}
+```
+
+### 2. Use hooks in your components
+
+```tsx
+import { useUIElement } from 'ui-bridge-native';
+
+function SubmitButton({ onPress }) {
+  const { ref, onLayout, bridgeProps } = useUIElement({
+    id: 'submit-button',
+    type: 'button',
+    label: 'Submit Form',
+  });
+
+  return (
+    <Pressable ref={ref} onLayout={onLayout} {...bridgeProps} onPress={onPress}>
+      <Text>Submit</Text>
+    </Pressable>
+  );
+}
+```
+
+### 3. Control from Python (unchanged from web!)
+
+```python
+from ui_bridge import UIBridgeClient
+
+# Connect to device (use 10.0.2.2 for Android emulator)
+client = UIBridgeClient("http://10.0.2.2:8087")
+
+# Find and interact with elements
+client.press("submit-button")
+client.type("email-input", "test@example.com")
+
+# Get element state
+state = client.get_element_state("submit-button")
+print(f"Button visible: {state['visible']}")
+```
+
+## Hooks
+
+### useUIElement
+
+Register individual elements for control.
+
+```tsx
+const { ref, onLayout, bridgeProps, trigger, getState } = useUIElement({
+  id: 'my-element',
+  type: 'button', // or 'input', 'text', 'view', etc.
+  label: 'My Button', // Human-readable label
+});
+
+// Spread onto your component
+<Pressable ref={ref} onLayout={onLayout} {...bridgeProps}>
+  <Text>Click Me</Text>
+</Pressable>;
+```
+
+### useUIElementWithProps
+
+Extended version that captures props for action execution.
+
+```tsx
+const { ref, onLayout, bridgeProps, captureProps } = useUIElementWithProps({
+  id: 'text-input',
+  type: 'input',
+});
+
+// Capture props so bridge can call onChangeText
+captureProps({ onChangeText, value });
+
+<TextInput
+  ref={ref}
+  onLayout={onLayout}
+  {...bridgeProps}
+  value={value}
+  onChangeText={onChangeText}
+/>;
+```
+
+### useUIComponent
+
+Register component-level actions.
+
+```tsx
+useUIComponent({
+  id: 'login-form',
+  name: 'Login Form',
+  actions: [
+    {
+      id: 'submit-login',
+      label: 'Submit Login',
+      handler: async ({ email, password }) => {
+        setEmail(email);
+        setPassword(password);
+        await submitLogin();
+      },
+    },
+    {
+      id: 'clear-form',
+      label: 'Clear Form',
+      handler: () => {
+        setEmail('');
+        setPassword('');
+      },
+    },
+  ],
+});
+```
+
+### useUIBridge
+
+Access bridge functionality from any component.
+
+```tsx
+const { available, elements, components, executeAction, find, createSnapshot } = useUIBridge();
+
+// Find all buttons
+const buttons = await find({ types: ['button'] });
+
+// Execute action
+await executeAction('submit-button', { action: 'press' });
+```
+
+## Element Types
+
+- `button` - Pressable buttons
+- `input` - Text inputs
+- `text` - Text elements
+- `view` - Generic views
+- `scroll` - ScrollViews
+- `list` - FlatList/SectionList
+- `listItem` - List items
+- `switch` - Toggle switches
+- `checkbox` - Checkboxes
+- `radio` - Radio buttons
+- `image` - Images
+- `touchable` - TouchableOpacity/TouchableHighlight
+- `pressable` - Pressable components
+- `modal` - Modals
+- `custom` - Custom elements
+
+## Actions
+
+- `press` - Single tap
+- `longPress` - Long press
+- `doubleTap` - Double tap
+- `type` - Type text (for inputs)
+- `clear` - Clear text
+- `focus` - Focus element
+- `blur` - Blur element
+- `scroll` - Scroll
+- `swipe` - Swipe gesture
+- `toggle` - Toggle switch/checkbox
+
+## HTTP Server
+
+The package includes an embedded HTTP server for external control. Configure with:
+
+```tsx
+<UIBridgeNativeProvider
+  features={{ server: true }}
+  config={{ serverPort: 8087 }}
+>
+```
+
+### 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        |
+
+### Custom Server Adapter
+
+The HTTP server requires a platform-specific adapter. See [documentation](./docs/server-adapters.md) for examples with:
+
+- `react-native-http-bridge`
+- `@aspect/react-native-http-server`
+
+## Debug Inspector
+
+Built-in visual inspector for development:
+
+```tsx
+import { UIBridgeInspector } from 'ui-bridge-native/debug';
+
+function App() {
+  return (
+    <UIBridgeNativeProvider features={{ debug: __DEV__ }}>
+      <MainContent />
+      {__DEV__ && <UIBridgeInspector />}
+    </UIBridgeNativeProvider>
+  );
+}
+```
+
+## TypeScript
+
+Full TypeScript support included. Import types as needed:
+
+```tsx
+import type { NativeElementState, NativeElementType, UseUIElementOptions } from 'ui-bridge-native';
+```
+
+## License
+
+MIT

package/dist/control/index.d.mts

@@ -0,0 +1,94 @@
+import { N as NativeActionExecutor, C as ControlActionRequest, a as ControlActionResponse, b as ComponentActionRequest, c as ComponentActionResponse, W as WaitResult } from '../types-BgZTILOS.mjs';
+export { A as ActionExecutionOptions, e as PageNavigateRequest, f as PageNavigationResponse, P as PressActionParams, S as ScrollActionParams, d as SwipeActionParams, T as TypeActionParams } from '../types-BgZTILOS.mjs';
+import { a as NativeUIBridgeRegistry } from '../registry-D9J7IVo1.mjs';
+import { l as NativeFindRequest, m as NativeFindResponse, W as WaitOptions } from '../types-DM6yMpW8.mjs';
+
+/**
+ * Native Action Executor
+ *
+ * Executes actions on registered native elements and components.
+ * In React Native, we execute actions by calling prop handlers directly
+ * (onPress, onChangeText, etc.) rather than simulating DOM events.
+ */
+
+/**
+ * Default native action executor implementation
+ */
+declare class DefaultNativeActionExecutor implements NativeActionExecutor {
+    private registry;
+    constructor(registry: NativeUIBridgeRegistry);
+    /**
+     * Execute an action on an element
+     */
+    executeAction(elementId: string, request: ControlActionRequest): Promise<ControlActionResponse>;
+    /**
+     * Perform an action on an element
+     */
+    private performAction;
+    /**
+     * Perform press action
+     */
+    private performPress;
+    /**
+     * Perform long press action
+     */
+    private performLongPress;
+    /**
+     * Perform double tap action
+     */
+    private performDoubleTap;
+    /**
+     * Perform type action
+     */
+    private performType;
+    /**
+     * Perform clear action
+     */
+    private performClear;
+    /**
+     * Perform focus action
+     */
+    private performFocus;
+    /**
+     * Perform blur action
+     */
+    private performBlur;
+    /**
+     * Perform scroll action
+     */
+    private performScroll;
+    /**
+     * Perform swipe action
+     */
+    private performSwipe;
+    /**
+     * Perform toggle action
+     */
+    private performToggle;
+    /**
+     * Create a synthetic press event
+     */
+    private createPressEvent;
+    /**
+     * Execute a component action
+     */
+    executeComponentAction(componentId: string, request: ComponentActionRequest): Promise<ComponentActionResponse>;
+    /**
+     * Find elements
+     */
+    find(request: NativeFindRequest): Promise<NativeFindResponse>;
+    /**
+     * Wait for element conditions
+     */
+    waitForElement(elementId: string, options: WaitOptions): Promise<WaitResult>;
+    /**
+     * Internal wait implementation
+     */
+    private waitForElementInternal;
+}
+/**
+ * Create a native action executor
+ */
+declare function createNativeActionExecutor(registry: NativeUIBridgeRegistry): NativeActionExecutor;
+
+export { ComponentActionRequest, ComponentActionResponse, ControlActionRequest, ControlActionResponse, DefaultNativeActionExecutor, NativeActionExecutor, WaitResult, createNativeActionExecutor };

package/dist/control/index.d.ts

@@ -0,0 +1,94 @@
+import { N as NativeActionExecutor, C as ControlActionRequest, a as ControlActionResponse, b as ComponentActionRequest, c as ComponentActionResponse, W as WaitResult } from '../types-D27YUSIk.js';
+export { A as ActionExecutionOptions, e as PageNavigateRequest, f as PageNavigationResponse, P as PressActionParams, S as ScrollActionParams, d as SwipeActionParams, T as TypeActionParams } from '../types-D27YUSIk.js';
+import { a as NativeUIBridgeRegistry } from '../registry-C_35zBrv.js';
+import { l as NativeFindRequest, m as NativeFindResponse, W as WaitOptions } from '../types-DM6yMpW8.js';
+
+/**
+ * Native Action Executor
+ *
+ * Executes actions on registered native elements and components.
+ * In React Native, we execute actions by calling prop handlers directly
+ * (onPress, onChangeText, etc.) rather than simulating DOM events.
+ */
+
+/**
+ * Default native action executor implementation
+ */
+declare class DefaultNativeActionExecutor implements NativeActionExecutor {
+    private registry;
+    constructor(registry: NativeUIBridgeRegistry);
+    /**
+     * Execute an action on an element
+     */
+    executeAction(elementId: string, request: ControlActionRequest): Promise<ControlActionResponse>;
+    /**
+     * Perform an action on an element
+     */
+    private performAction;
+    /**
+     * Perform press action
+     */
+    private performPress;
+    /**
+     * Perform long press action
+     */
+    private performLongPress;
+    /**
+     * Perform double tap action
+     */
+    private performDoubleTap;
+    /**
+     * Perform type action
+     */
+    private performType;
+    /**
+     * Perform clear action
+     */
+    private performClear;
+    /**
+     * Perform focus action
+     */
+    private performFocus;
+    /**
+     * Perform blur action
+     */
+    private performBlur;
+    /**
+     * Perform scroll action
+     */
+    private performScroll;
+    /**
+     * Perform swipe action
+     */
+    private performSwipe;
+    /**
+     * Perform toggle action
+     */
+    private performToggle;
+    /**
+     * Create a synthetic press event
+     */
+    private createPressEvent;
+    /**
+     * Execute a component action
+     */
+    executeComponentAction(componentId: string, request: ComponentActionRequest): Promise<ComponentActionResponse>;
+    /**
+     * Find elements
+     */
+    find(request: NativeFindRequest): Promise<NativeFindResponse>;
+    /**
+     * Wait for element conditions
+     */
+    waitForElement(elementId: string, options: WaitOptions): Promise<WaitResult>;
+    /**
+     * Internal wait implementation
+     */
+    private waitForElementInternal;
+}
+/**
+ * Create a native action executor
+ */
+declare function createNativeActionExecutor(registry: NativeUIBridgeRegistry): NativeActionExecutor;
+
+export { ComponentActionRequest, ComponentActionResponse, ControlActionRequest, ControlActionResponse, DefaultNativeActionExecutor, NativeActionExecutor, WaitResult, createNativeActionExecutor };