@myop/cli 0.1.45 → 0.1.47

package/dist/skills/myop-react-native-host/SKILL.md

@@ -0,0 +1,438 @@
+---
+name: myop-react-native-host
+description: "Integrate Myop components into React Native applications using @myop/react-native. ALWAYS use the MyopComponent component or auto-generated packages — NEVER create WebViews manually. Covers MyopComponent props, CTA event handling, data binding, preloading, auto-generated packages, native-specific features (scroll, zoom, selection control), and local dev setup. Activate when the user is building a React Native app that hosts Myop components, or when you see @myop/react-native in package.json."
+---
+
+# Myop React Native Host Integration
+
+Embed Myop components in React Native applications using `@myop/react-native`. Components render inside a WebView with a native bridge for CTA communication.
+
+## CRITICAL: Always Use the SDK
+
+**NEVER create `<WebView>` elements manually. NEVER call `myop_init_interface()` or wire `myop_cta_handler()` directly.**
+
+The `@myop/react-native` SDK handles all WebView management, native bridge communication, loading, error handling, and caching. Always use `<MyopComponent>` or an auto-generated package.
+
+```tsx
+// WRONG — never do this
+<WebView source={{ uri: componentUrl }} />
+
+// CORRECT — always use the SDK
+<MyopComponent componentId="abc-123" data={data} on={handler} />
+```
+
+## End-to-End Workflow: React Native App with Myop Components
+
+Each Myop component is a **separate project** in its own directory. You create them, develop them, push them to get a `componentId`, then reference that ID in your React Native host app.
+
+### Step 1: Create component projects
+
+```bash
+# Each component gets its own directory
+mkdir components/sidebar && cd components/sidebar
+npx myop create        # Scaffolds index.html + myop.config.json
+# Build the component UI (see myop-component skill), then Ctrl+C
+
+cd ../ && mkdir chart && cd chart
+npx myop create
+```
+
+### Step 2: Push components to get IDs
+
+```bash
+cd components/sidebar
+npx myop push          # Uploads → componentId written to myop.config.json
+
+cd ../chart
+npx myop push
+```
+
+### Step 3: Use in your React Native app
+
+```bash
+cd my-rn-app
+npm install @myop/react-native react-native-webview
+```
+
+```tsx
+import { MyopComponent } from "@myop/react-native";
+
+function App() {
+    return (
+        <View style={{ flex: 1 }}>
+            <MyopComponent
+                componentId="<sidebar-componentId-from-step-2>"
+                data={{ items: ["Home", "Settings"] }}
+                on={(action, payload) => console.log(action, payload)}
+                style={{ height: 300 }}
+            />
+            <MyopComponent
+                componentId="<chart-componentId-from-step-2>"
+                data={{ values: [10, 20, 30] }}
+                style={{ flex: 1 }}
+            />
+        </View>
+    );
+}
+```
+
+### Working locally on existing components (componentId already in code)
+
+When you find `componentId` values already used in the codebase and the developer wants to modify those components locally:
+
+**Step A: Pull the component source**
+
+```bash
+mkdir components/sidebar && cd components/sidebar
+npx myop pull <componentId>
+# Downloads index.html + creates myop.config.json with the componentId
+```
+
+**Step B: Start the local dev server**
+
+```bash
+npx myop dev           # Serves component on port 9292 with HMR
+```
+
+**Step C: Point the React Native app to local dev server**
+
+```tsx
+import { enableLocalDev, setCloudRepositoryUrl } from "@myop/react-native";
+enableLocalDev();      // All <MyopComponent> instances load from localhost:9292
+
+// Android emulator requires explicit IP:
+// setCloudRepositoryUrl("http://10.0.2.2:9292");
+// Physical device — use your machine's IP:
+// setCloudRepositoryUrl("http://192.168.1.100:9292");
+```
+
+Now edits to `index.html` are reflected instantly in the React Native app.
+
+**Step D: Push changes when done**
+
+```bash
+npx myop push          # Uploads updated component to the same componentId
+```
+
+Remove or comment out `enableLocalDev()` to go back to loading from the Myop cloud.
+
+**Multiple components:**
+
+```bash
+mkdir -p components && cd components
+npx myop pull <sidebar-id> -o sidebar/index.html
+npx myop pull <chart-id> -o chart/index.html
+npx myop dev -m        # Monorepo mode — select which components to serve
+```
+
+## When This Skill Activates
+
+- `@myop/react-native` is in `package.json` dependencies
+- User asks to "add a Myop component to React Native", "integrate Myop in mobile"
+- Files import from `@myop/react-native`
+
+## Installation
+
+```bash
+npm install @myop/react-native react-native-webview
+```
+
+Peer dependencies: `react >= 16.8.0`, `react-native >= 0.60.0`, `react-native-webview >= 11.0.0`.
+
+For Expo projects:
+```bash
+npx expo install react-native-webview
+npm install @myop/react-native
+```
+
+## Quick Start
+
+### Option 1: Auto-Generated Package (Recommended)
+
+```bash
+npm install https://cloud.myop.dev/npm/{componentId}/react-native
+```
+
+```tsx
+import { MyComponent } from "@myop/my-component";
+
+function App() {
+    return (
+        <MyComponent
+            data={{ title: "Hello", items: ["a", "b"] }}
+            onItemSelected={(payload) => {
+                console.log(payload.itemId);
+            }}
+            style={{ flex: 1 }}
+        />
+    );
+}
+```
+
+The auto-generated package bakes in the `componentId` and exports typed interfaces.
+
+### Option 2: MyopComponent Directly
+
+```tsx
+import { MyopComponent } from "@myop/react-native";
+
+function App() {
+    return (
+        <MyopComponent
+            componentId="your-component-id"
+            data={{ title: "Hello" }}
+            on={(action, payload) => {
+                console.log(action, payload);
+            }}
+            style={{ flex: 1 }}
+        />
+    );
+}
+```
+
+## MyopComponent Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `componentId` | `string` | — | Myop component ID (UUID) |
+| `data` | `any` | — | Data passed to `myop_init_interface`. Reactive — updates trigger re-render |
+| `on` | `(action, payload) => void` | — | Generic handler for all CTA events |
+| `onLoad` | `(component: IMyopComponentProxy) => void` | — | Called when component finishes loading |
+| `onError` | `(error: string) => void` | — | Called on load failure |
+| `style` | `StyleProp<ViewStyle>` | `{width:'100%', height:'100%'}` | Style for the outer View container |
+| `loader` | `ReactNode` | — | Custom loading indicator |
+| `fallback` | `ReactNode` | — | Custom error fallback UI |
+| `fadeDuration` | `number` | `200` | Loader fade-out duration in ms |
+| `environment` | `string` | — | Load from specific environment |
+| `preview` | `boolean` | `false` | Load unpublished preview version |
+| `scrollEnabled` | `boolean` | `false` | Allow scrolling inside the WebView |
+| `zoomEnabled` | `boolean` | `false` | Allow pinch-to-zoom |
+| `selectionEnabled` | `boolean` | `false` | Allow text selection (disabled for native feel) |
+| `componentConfig` | `IComponentInstanceConfig` | — | Direct config object (advanced) |
+
+### Native-Specific Props
+
+The `scrollEnabled`, `zoomEnabled`, and `selectionEnabled` props are unique to React Native:
+
+```tsx
+<MyopComponent
+    componentId="article-viewer"
+    data={{ article }}
+    scrollEnabled={true}       // Allow scrolling for long content
+    zoomEnabled={false}        // Disable pinch zoom
+    selectionEnabled={false}   // Disable text selection for native feel
+    style={{ flex: 1 }}
+/>
+```
+
+When `selectionEnabled={false}` (default), CSS rules are injected to prevent text selection and touch callout, with exceptions for `<input>`, `<textarea>`, and `[contenteditable]` elements.
+
+## CTA Event Handling
+
+CTA events from the component are received via `postMessage` bridge and dispatched to the `on` callback:
+
+```tsx
+<MyopComponent
+    componentId="task-list"
+    data={{ tasks }}
+    on={(action, payload) => {
+        switch (action) {
+            case 'task-toggled':
+                console.log(payload.taskId, payload.completed);
+                break;
+            case 'task-deleted':
+                console.log(payload.taskId);
+                break;
+        }
+    }}
+/>
+```
+
+## Data Binding
+
+The `data` prop is reactive. When it changes (compared by JSON serialization to avoid redundant calls), `myop_init_interface(data)` is called automatically:
+
+```tsx
+function Counter() {
+    const [count, setCount] = useState(0);
+
+    return (
+        <View>
+            <Button title="+1" onPress={() => setCount(c => c + 1)} />
+            <MyopComponent
+                componentId="counter-display"
+                data={{ count }}
+                style={{ height: 200 }}
+            />
+        </View>
+    );
+}
+```
+
+**Note:** When `data` is provided, the WebView is hidden (opacity: 0) until the component has loaded and real data has been applied. This prevents the component's preview/placeholder content from flashing before `myop_init_interface` is called.
+
+## Component Instance (IMyopComponentProxy)
+
+The `onLoad` callback receives a proxy object for controlling the component:
+
+```tsx
+<MyopComponent
+    componentId="..."
+    onLoad={(component) => {
+        // component.id — the component ID
+        // component.props.myop_init_interface(data) — update data
+        // component.element.style.set('background', 'red') — style DOM
+        // component.element.style.get('background') — returns Promise
+        // component.element.set('innerHTML', '<b>hi</b>') — set DOM property
+        // component.element.get('scrollHeight') — returns Promise
+        // component.dispose() — cleanup
+        // component.hide() / component.show()
+    }}
+/>
+```
+
+The proxy communicates with the WebView via `injectJavaScript`. Element `get()` operations are asynchronous (return Promises) because they cross the native-WebView bridge.
+
+## Preloading
+
+```tsx
+import { preloadComponents, isPreloaded } from "@myop/react-native";
+
+// Preload on app startup or before navigating to a screen
+await preloadComponents(["component-id-1", "component-id-2"]);
+await preloadComponents(["component-id-1"], "staging");
+
+if (isPreloaded("component-id-1")) {
+    console.log("Will render instantly — no loader shown");
+}
+```
+
+When a component is preloaded, the loader is not shown at all.
+
+## Configuration Functions
+
+```tsx
+import {
+    enableLocalDev,
+    setCloudRepositoryUrl,
+    setEnvironment,
+} from "@myop/react-native";
+
+enableLocalDev();                          // localhost:9292
+setCloudRepositoryUrl("https://custom");   // Custom URL
+setEnvironment("staging");                 // Default environment
+```
+
+**Local dev note:** For iOS simulator, `localhost` works. For Android emulator, use `10.0.2.2` instead. For physical devices, use your machine's IP address:
+
+```tsx
+import { setCloudRepositoryUrl } from "@myop/react-native";
+
+// Android emulator
+setCloudRepositoryUrl("http://10.0.2.2:9292");
+
+// Physical device (replace with your machine's IP)
+setCloudRepositoryUrl("http://192.168.1.100:9292");
+```
+
+## Custom Loader
+
+Pass a React Native component as the `loader` prop. The loader supports a fade-out animation via `MyopLoader`:
+
+```tsx
+import { MyopComponent, MyopLoader } from "@myop/react-native";
+
+<MyopComponent
+    componentId="..."
+    loader={
+        <MyopLoader>
+            <ActivityIndicator size="large" color="#007AFF" />
+            <Text>Loading component...</Text>
+        </MyopLoader>
+    }
+    fallback={<Text>Failed to load component</Text>}
+    fadeDuration={300}
+/>
+```
+
+## Complete Example
+
+```tsx
+import React, { useState } from 'react';
+import { View, Button, Text, StyleSheet } from 'react-native';
+import { MyopComponent, preloadComponents } from '@myop/react-native';
+import type { IMyopComponentProxy } from '@myop/react-native';
+
+// Preload on module load
+preloadComponents(['task-list-abc123']);
+
+function TaskScreen() {
+    const [tasks, setTasks] = useState([
+        { id: '1', title: 'Review PR', completed: false },
+        { id: '2', title: 'Deploy', completed: true },
+    ]);
+
+    return (
+        <View style={styles.container}>
+            <Text style={styles.title}>My Tasks</Text>
+            <MyopComponent
+                componentId="task-list-abc123"
+                data={{ tasks }}
+                on={(action, payload) => {
+                    if (action === 'task-toggled') {
+                        setTasks(prev =>
+                            prev.map(t =>
+                                t.id === payload.taskId
+                                    ? { ...t, completed: payload.completed }
+                                    : t
+                            )
+                        );
+                    }
+                    if (action === 'task-deleted') {
+                        setTasks(prev => prev.filter(t => t.id !== payload.taskId));
+                    }
+                }}
+                onLoad={(component) => {
+                    console.log('Component loaded:', component.id);
+                }}
+                onError={(error) => {
+                    console.error('Failed:', error);
+                }}
+                scrollEnabled={true}
+                selectionEnabled={false}
+                style={styles.component}
+            />
+        </View>
+    );
+}
+
+const styles = StyleSheet.create({
+    container: { flex: 1 },
+    title: { fontSize: 24, padding: 16 },
+    component: { flex: 1 },
+});
+```
+
+## Auto-Generated React Native Package
+
+```bash
+npm install https://cloud.myop.dev/npm/{componentId}/react-native
+```
+
+The generated package exports:
+- Named component with `componentId` baked in (no `componentId` prop needed)
+- Typed `data` prop from `MyopInitData`
+- Typed `on[ActionName]` handlers from `MyopCtaPayloads`
+- `COMPONENT_ID` constant
+
+## TypeScript Types
+
+```typescript
+import type {
+    IMyopComponentProxy,       // Component instance proxy (onLoad callback)
+    IComponentInstanceConfig,  // Direct config object type
+} from "@myop/react-native";
+
+import { MyopLoader } from "@myop/react-native";
+import type { MyopLoaderRef } from "@myop/react-native";
+```