@myop/cli 0.1.45 → 0.1.47

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

@@ -0,0 +1,407 @@
+---
+name: myop-react-host
+description: "Integrate Myop components into React applications using @myop/react. ALWAYS use the MyopComponent React component or auto-generated packages — NEVER create iframes manually. This skill covers MyopComponent props, typed event handlers, data binding, preloading, auto-generated packages, and local dev setup. Activate when the user is building a React app that hosts Myop components, or when you see @myop/react in package.json."
+---
+
+# Myop React Host Integration
+
+Embed Myop components in React applications using `@myop/react`.
+
+## CRITICAL: Always Use the SDK
+
+**NEVER create `<iframe>` elements manually. NEVER call `myop_init_interface()` or wire `myop_cta_handler()` directly.**
+
+The `@myop/react` SDK handles all iframe management, communication, loading, error handling, sizing, and caching. Always use `<MyopComponent>` or an auto-generated package.
+
+```tsx
+// WRONG — never do this
+<iframe ref={ref} src="/component.html" />
+ref.current.contentWindow.myop_init_interface(data)
+
+// CORRECT — always use the SDK
+<MyopComponent componentId="abc-123" data={data} on={handler} />
+```
+
+## End-to-End Workflow: React 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 host app.
+
+### Step 1: Create component projects
+
+Each component needs its own directory with `myop.config.json` + `index.html`:
+
+```bash
+# Create first component
+mkdir components/sidebar && cd components/sidebar
+npx myop create        # Scaffolds index.html + myop.config.json, starts dev server
+# Build the component UI (see myop-component skill)
+# Ctrl+C to stop dev server when done
+
+# Create second component
+cd ../
+mkdir chart && cd chart
+npx myop create
+# Build this component too
+```
+
+### Step 2: Push components to get IDs
+
+Each component must be pushed to the Myop platform to get a `componentId`:
+
+```bash
+cd components/sidebar
+npx myop push          # Uploads and assigns a componentId (UUID)
+# Output: componentId is now in myop.config.json
+
+cd ../chart
+npx myop push
+```
+
+After push, each `myop.config.json` has a real `componentId` (UUID).
+
+### Step 3: Set up the React host app
+
+```bash
+cd my-react-app
+npm install @myop/react @myop/sdk
+```
+
+### Step 4: Use components in React
+
+```tsx
+import { MyopComponent } from "@myop/react";
+
+function App() {
+    return (
+        <div style={{ display: "flex", gap: 16 }}>
+            <MyopComponent
+                componentId="<sidebar-componentId-from-step-2>"
+                data={{ items: ["Home", "Settings"] }}
+                onItemSelected={({ itemId }) => console.log(itemId)}
+                style={{ width: 300, height: "100%" }}
+            />
+            <MyopComponent
+                componentId="<chart-componentId-from-step-2>"
+                data={{ values: [10, 20, 30] }}
+                style={{ flex: 1 }}
+            />
+        </div>
+    );
+}
+```
+
+### 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
+# Create a directory for the component and pull it by ID
+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 app to local dev server**
+
+```tsx
+import { enableLocalDev } from "@myop/react";
+enableLocalDev();      // All <MyopComponent> instances load from localhost:9292 instead of cloud
+```
+
+Now edits to `index.html` in the component directory are reflected instantly in the React app.
+
+**Step D: Push changes when done**
+
+```bash
+cd components/sidebar
+npx myop push          # Uploads updated component to the same componentId
+```
+
+Remove or comment out `enableLocalDev()` to go back to loading from the Myop cloud.
+
+**Full local dev flow (multiple components):**
+
+```bash
+# Pull all components you need to work on
+mkdir -p components && cd components
+npx myop pull <sidebar-id> -o sidebar/index.html
+npx myop pull <chart-id> -o chart/index.html
+
+# Start dev server (serves all components in subdirectories)
+npx myop dev -m        # Monorepo mode — select which components to serve
+```
+
+## When This Skill Activates
+
+- `@myop/react` is in `package.json` dependencies
+- User asks to "add a Myop component to React", "integrate Myop", "use MyopComponent"
+- Files import from `@myop/react`
+
+## Installation
+
+```bash
+npm install @myop/react @myop/sdk
+```
+
+## Quick Start
+
+### Option 1: Auto-Generated Package (Recommended)
+
+Every Myop component has an auto-generated, fully typed React package:
+
+```bash
+npm install https://cloud.myop.dev/npm/{componentId}/react
+```
+
+```tsx
+import { MyComponent } from "@myop/my-component";
+
+function App() {
+    return (
+        <MyComponent
+            data={{ title: "Hello", items: ["a", "b"] }}
+            onItemSelected={(payload) => {
+                // payload is typed: { itemId: string }
+                console.log(payload.itemId);
+            }}
+        />
+    );
+}
+```
+
+**Why auto-generated packages:**
+- Full TypeScript types for `data` and all CTA events — auto-generated from the component's `<script type="myop/types">` block
+- No `componentId` prop needed — baked into the package
+- Tiny bundle impact (~6KB for `@myop/react`, component loads at runtime)
+
+### Option 2: MyopComponent Directly
+
+```tsx
+import { MyopComponent } from "@myop/react";
+
+function App() {
+    return (
+        <MyopComponent
+            componentId="your-component-id"
+            data={{ title: "Hello" }}
+            on={(action, payload) => {
+                console.log(action, payload);
+            }}
+        />
+    );
+}
+```
+
+## MyopComponent Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `componentId` | `string` | — | Myop component ID (UUID) |
+| `data` | `TData` | — | Data passed to `myop_init_interface`. Reactive — updates trigger re-render in component |
+| `on` | `(action, payload) => void` | — | Generic handler for all CTA events |
+| `on[ActionName]` | `(payload) => void` | — | Typed handler for specific CTA (e.g., `onItemSelected`) |
+| `onLoad` | `(component) => void` | — | Called when component finishes loading |
+| `onError` | `(error: string) => void` | — | Called on load failure |
+| `onSizeChange` | `(size) => boolean \| void` | — | Called when auto-sized component changes dimensions. Return `false` to reject |
+| `style` | `CSSProperties` | — | CSS styles for the outer container |
+| `loader` | `ReactNode` | — | Custom loading indicator (shown while component loads) |
+| `fallback` | `ReactNode` | — | Custom error fallback UI |
+| `fadeDuration` | `number` | `200` | Loader fade-out duration in ms |
+| `autoSize` | `boolean` | `false` | Auto-size container to match iframe content |
+| `environment` | `string` | — | Load from specific environment (e.g., `"staging"`) |
+| `preview` | `boolean` | `false` | Load unpublished preview version |
+
+## Typed Event Handlers
+
+CTA actions from the component are converted to `on[PascalCase]` props:
+
+| Component CTA action | React prop |
+|----------------------|------------|
+| `'item-selected'` | `onItemSelected` |
+| `'form-submitted'` | `onFormSubmitted` |
+| `'row-clicked'` | `onRowClicked` |
+
+```tsx
+// Both work — use typed handlers for type safety, `on` for catch-all
+<MyopComponent<MyData, MyCtaPayloads>
+    componentId="..."
+    data={data}
+    onItemSelected={(payload) => {
+        // payload typed as MyCtaPayloads['item-selected']
+    }}
+    on={(action, payload) => {
+        // Generic catch-all
+    }}
+/>
+```
+
+## Data Binding
+
+The `data` prop is reactive. When it changes, `myop_init_interface(data)` is called automatically:
+
+```tsx
+function App() {
+    const [count, setCount] = useState(0);
+
+    return (
+        <>
+            <button onClick={() => setCount(c => c + 1)}>+1</button>
+            <MyopComponent
+                componentId="counter-display"
+                data={{ count }}  // Component updates when count changes
+            />
+        </>
+    );
+}
+```
+
+## Preloading
+
+Preload components to eliminate loading delay when they mount:
+
+```tsx
+import { preloadComponents, isPreloaded } from "@myop/react";
+
+// Preload on app startup or route entry
+await preloadComponents(["component-id-1", "component-id-2"]);
+
+// Optionally preload for a specific environment
+await preloadComponents(["component-id-1"], "staging");
+
+// Check if a component is cached
+if (isPreloaded("component-id-1")) {
+    console.log("Will render instantly");
+}
+```
+
+**When to preload:**
+- App startup — preload components on the landing page
+- Route transitions — preload components for the next page
+- Tab containers — preload all tab contents when container mounts
+
+## Configuration Functions
+
+```tsx
+import {
+    enableLocalDev,
+    setCloudRepositoryUrl,
+    setEnvironment,
+} from "@myop/react";
+
+// Point to local dev server (myop dev on port 9292)
+enableLocalDev();
+
+// Custom cloud URL
+setCloudRepositoryUrl("https://custom.myop.dev");
+
+// Set default environment for all components
+setEnvironment("staging");
+```
+
+## Accessing the Component Instance
+
+Use `onLoad` to get direct access to the loaded component:
+
+```tsx
+<MyopComponent
+    componentId="..."
+    onLoad={(component) => {
+        // component.props.myop_init_interface(data) — update data
+        // component.props.myop_cta_handler — read current handler
+        // component.dispose() — cleanup
+        // component.hide() / component.show()
+    }}
+/>
+```
+
+## Auto-Size Mode
+
+When `autoSize={true}`, the container dimensions follow the iframe content:
+
+```tsx
+<MyopComponent
+    componentId="..."
+    autoSize={true}
+    onSizeChange={(size) => {
+        console.log(size.width, size.height);
+        // Return false to reject the size change
+    }}
+    style={{ maxWidth: 600, maxHeight: 400 }}
+/>
+```
+
+## Complete Example
+
+```tsx
+import { MyopComponent, preloadComponents } from "@myop/react";
+import { useEffect, useState } from "react";
+
+// Preload on module load
+preloadComponents(["sidebar-abc123", "chart-def456"]);
+
+function Dashboard() {
+    const [tasks, setTasks] = useState([
+        { id: "1", title: "Review PR", completed: false },
+        { id: "2", title: "Deploy", completed: true },
+    ]);
+
+    return (
+        <div style={{ display: "flex", height: "100vh" }}>
+            <MyopComponent
+                componentId="sidebar-abc123"
+                data={{ tasks }}
+                onTaskToggled={({ taskId, completed }) => {
+                    setTasks(prev =>
+                        prev.map(t => t.id === taskId ? { ...t, completed } : t)
+                    );
+                }}
+                onTaskDeleted={({ taskId }) => {
+                    setTasks(prev => prev.filter(t => t.id !== taskId));
+                }}
+                loader={<div>Loading sidebar...</div>}
+                fallback={<div>Failed to load sidebar</div>}
+                style={{ width: 300, height: "100%" }}
+            />
+            <MyopComponent
+                componentId="chart-def456"
+                data={{ tasks }}
+                style={{ flex: 1 }}
+            />
+        </div>
+    );
+}
+```
+
+## TypeScript Types
+
+```typescript
+import type {
+    IPropTypes,           // Full props type (base + event handlers)
+    ITypedMyopComponent,  // Component instance with typed props
+    IMyopComponentProps,  // Props interface (myop_init_interface + myop_cta_handler)
+    EventHandlerProps,    // Generated on[Action] props type
+    KebabToPascal,        // Utility: 'item-selected' -> 'ItemSelected'
+} from "@myop/react";
+```
+
+## Common Mistakes — WRONG vs CORRECT
+
+| WRONG | CORRECT |
+|-------|---------|
+| Creating `<iframe>` elements manually | Using `<MyopComponent>` from `@myop/react` |
+| Calling `myop_init_interface()` on iframe contentWindow | Passing `data` prop to `<MyopComponent>` |
+| Wiring `myop_cta_handler` via refs | Using `on` or `onActionName` props |
+| Loading component HTML from local file | Using `componentId` — SDK fetches from Myop cloud |
+| Managing iframe lifecycle with useEffect | SDK handles load, error, cleanup automatically |
+
+## Reference
+
+- [Auto-Generated Packages](references/auto-generated-packages.md)

package/dist/skills/myop-react-host/references/auto-generated-packages.md

@@ -0,0 +1,70 @@
+# Auto-Generated Packages
+
+Myop auto-generates a fully typed npm package for every component, for each framework.
+
+## Install URL Pattern
+
+```
+https://cloud.myop.dev/npm/{componentId}/react
+https://cloud.myop.dev/npm/{componentId}/vue
+https://cloud.myop.dev/npm/{componentId}/angular
+https://cloud.myop.dev/npm/{componentId}/react-native
+https://cloud.myop.dev/npm/{componentId}/typescript
+```
+
+## How It Works
+
+1. The server reads the component's `<script type="myop/types">` block
+2. Extracts `MyopInitData` and `MyopCtaPayloads` interfaces
+3. Generates a typed wrapper component with the `componentId` baked in
+4. Returns a `.tgz` package installable via `npm install <url>`
+
+## What Gets Generated (React)
+
+```
+package/
+  package.json      # @myop/{component-name}, peerDeps: react, @myop/react
+  index.tsx         # forwardRef component wrapping MyopComponent
+  index.d.ts        # TypeScript declarations
+  index.js          # Compiled CommonJS
+```
+
+### Generated Component Code
+
+```tsx
+import { MyopComponent, IPropTypes } from '@myop/react';
+import { forwardRef } from 'react';
+
+// Types extracted from the component's <script type="myop/types">
+export interface MyopInitData { /* ... */ }
+export interface MyopCtaPayloads { /* ... */ }
+
+export type MyComponentProps = Omit<IPropTypes<MyopInitData, MyopCtaPayloads>, 'componentId'>;
+
+export const MyComponent = forwardRef<any, MyComponentProps>((props, ref) => (
+    <MyopComponent<MyopInitData, MyopCtaPayloads>
+        {...props}
+        componentId="baked-in-uuid"
+        ref={ref}
+    />
+));
+```
+
+### What You Get
+
+- `data` prop is typed as `MyopInitData`
+- Individual CTA handlers are typed (e.g., `onItemSelected: (payload: { itemId: string }) => void`)
+- No need to pass `componentId` — it's baked in
+- Full IntelliSense / autocomplete in IDEs
+
+## Info Endpoint
+
+Get install instructions and component info:
+
+```
+https://cloud.myop.dev/npm/{componentId}/react/info
+```
+
+## Updating
+
+Re-run `npm install <url>` to get the latest types after updating the component's type definitions.