@myop/cli 0.1.45 → 0.1.47

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

@@ -0,0 +1,374 @@
+---
+name: myop-vue-host
+description: "Integrate Myop components into Vue 3 applications using @myop/vue. ALWAYS use the MyopComponent Vue component or auto-generated packages — NEVER create iframes manually. Covers MyopComponent props, events, slots, data binding, preloading, auto-generated packages, and local dev setup. Activate when the user is building a Vue app that hosts Myop components, or when you see @myop/vue in package.json."
+---
+
+# Myop Vue Host Integration
+
+Embed Myop components in Vue 3 applications using `@myop/vue`.
+
+## CRITICAL: Always Use the SDK
+
+**NEVER create `<iframe>` elements manually. NEVER call `myop_init_interface()` or wire `myop_cta_handler()` directly.**
+
+The `@myop/vue` SDK handles all iframe management, communication, loading, error handling, and caching. Always use `<MyopComponent>` or an auto-generated package.
+
+```vue
+<!-- WRONG — never do this -->
+<iframe ref="myIframe" src="/component.html" />
+
+<!-- CORRECT — always use the SDK -->
+<MyopComponent component-id="abc-123" :data="data" @cta="handleCta" />
+```
+
+## End-to-End Workflow: Vue 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 Vue 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 Vue app
+
+```bash
+cd my-vue-app
+npm install @myop/vue @myop/sdk
+```
+
+```vue
+<script setup>
+import { MyopComponent } from "@myop/vue";
+</script>
+
+<template>
+    <MyopComponent
+        component-id="<sidebar-componentId-from-step-2>"
+        :data="{ items: ['Home', 'Settings'] }"
+        @cta="(action, payload) => console.log(action, payload)"
+        style="width: 300px"
+    />
+    <MyopComponent
+        component-id="<chart-componentId-from-step-2>"
+        :data="{ values: [10, 20, 30] }"
+        style="flex: 1"
+    />
+</template>
+```
+
+### 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 Vue app to local dev server**
+
+```ts
+import { enableLocalDev } from "@myop/vue";
+enableLocalDev();      // All <MyopComponent> instances load from localhost:9292
+```
+
+Now edits to `index.html` are reflected instantly in the Vue 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/vue` is in `package.json` dependencies
+- User asks to "add a Myop component to Vue", "integrate Myop in Vue"
+- Files import from `@myop/vue`
+
+## Installation
+
+```bash
+npm install @myop/vue @myop/sdk
+```
+
+Requires **Vue 3.5+**.
+
+## Quick Start
+
+### Option 1: Auto-Generated Package (Recommended)
+
+```bash
+npm install https://cloud.myop.dev/npm/{componentId}/vue
+```
+
+```vue
+<script setup lang="ts">
+import { MyComponent } from "@myop/my-component";
+</script>
+
+<template>
+    <MyComponent
+        :data="{ title: 'Hello', items: ['a', 'b'] }"
+        @cta="(action, payload) => console.log(action, payload)"
+    />
+</template>
+```
+
+The auto-generated package bakes in the `componentId` and exports typed props and events.
+
+### Option 2: MyopComponent Directly
+
+```vue
+<script setup lang="ts">
+import { MyopComponent } from "@myop/vue";
+</script>
+
+<template>
+    <MyopComponent
+        component-id="your-component-id"
+        :data="{ title: 'Hello' }"
+        @cta="(action, payload) => console.log(action, payload)"
+    />
+</template>
+```
+
+## MyopComponent Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `componentId` | `string` | — | Myop component ID (UUID) |
+| `data` | `TData` | — | Data passed to `myop_init_interface`. Reactive — deep-watched |
+| `on` | `(action, payload) => void` | — | Generic CTA callback (alternative to `@cta` event) |
+| `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 |
+| `preview` | `boolean` | `false` | Load unpublished preview version |
+| `componentConfig` | `IComponentInstanceConfig` | — | Direct config object (advanced) |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `@load` | `ITypedMyopComponent` | Component finished loading |
+| `@error` | `string` | Load failure message |
+| `@sizeChange` | `SizeInfo` | Auto-sized component changed dimensions |
+| `@cta` | `action: string, payload: any` | CTA event from component |
+
+```vue
+<MyopComponent
+    component-id="..."
+    :data="data"
+    @load="onComponentLoaded"
+    @error="onError"
+    @cta="handleCta"
+/>
+```
+
+```ts
+function handleCta(action: string, payload: any) {
+    switch (action) {
+        case 'item-selected':
+            console.log(payload.itemId);
+            break;
+        case 'form-submitted':
+            console.log(payload);
+            break;
+    }
+}
+```
+
+## Slots
+
+| Slot | Purpose |
+|------|---------|
+| `loader` | Custom loading indicator |
+| `fallback` | Custom error fallback UI |
+
+```vue
+<MyopComponent component-id="...">
+    <template #loader>
+        <div class="spinner">Loading...</div>
+    </template>
+    <template #fallback>
+        <div class="error">Failed to load component</div>
+    </template>
+</MyopComponent>
+```
+
+## Data Binding
+
+The `data` prop is **deep-watched**. Vue reactivity changes automatically call `myop_init_interface`:
+
+```vue
+<script setup>
+import { ref } from 'vue';
+
+const count = ref(0);
+</script>
+
+<template>
+    <button @click="count++">+1</button>
+    <MyopComponent
+        component-id="counter-display"
+        :data="{ count }"
+    />
+</template>
+```
+
+**Important:** Vue reactive proxies are automatically stripped (via `JSON.parse(JSON.stringify())`) before passing data to the SDK, so no Vue internals leak into the iframe.
+
+## Preloading
+
+```ts
+import { preloadComponents, isPreloaded } from "@myop/vue";
+
+await preloadComponents(["component-id-1", "component-id-2"]);
+await preloadComponents(["component-id-1"], "staging");
+
+if (isPreloaded("component-id-1")) {
+    console.log("Will render instantly");
+}
+```
+
+## Configuration Functions
+
+```ts
+import { enableLocalDev, setCloudRepositoryUrl, setEnvironment } from "@myop/vue";
+
+enableLocalDev();                          // localhost:9292
+setCloudRepositoryUrl("https://custom");   // Custom URL
+setEnvironment("staging");                 // Default environment
+```
+
+## Accessing Component Instance
+
+Via template ref:
+
+```vue
+<script setup>
+import { ref } from 'vue';
+
+const myopRef = ref(null);
+
+function updateManually() {
+    myopRef.value?.myopComponent?.props?.myop_init_interface({ title: 'Updated' });
+}
+</script>
+
+<template>
+    <MyopComponent ref="myopRef" component-id="..." />
+</template>
+```
+
+Exposed properties: `myopComponent` (SDK component instance), `isLoaded` (boolean ref).
+
+## Generics (TypeScript)
+
+The component supports Vue 3 generics for typed `data` and events:
+
+```vue
+<script setup lang="ts" generic="TData, TCtaPayloads extends Record<string, any>">
+// TypeScript generics flow through to props and events
+</script>
+```
+
+## Complete Example
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { MyopComponent, preloadComponents } from '@myop/vue';
+
+preloadComponents(['sidebar-abc123']);
+
+const tasks = ref([
+    { id: '1', title: 'Review PR', completed: false },
+    { id: '2', title: 'Deploy', completed: true },
+]);
+
+function handleCta(action: string, payload: any) {
+    if (action === 'task-toggled') {
+        const task = tasks.value.find(t => t.id === payload.taskId);
+        if (task) task.completed = payload.completed;
+    }
+    if (action === 'task-deleted') {
+        tasks.value = tasks.value.filter(t => t.id !== payload.taskId);
+    }
+}
+</script>
+
+<template>
+    <div style="display: flex; height: 100vh">
+        <MyopComponent
+            component-id="sidebar-abc123"
+            :data="{ tasks }"
+            @cta="handleCta"
+            style="width: 300px"
+        >
+            <template #loader>
+                <div>Loading...</div>
+            </template>
+        </MyopComponent>
+    </div>
+</template>
+```
+
+## Auto-Generated Vue Package
+
+```bash
+npm install https://cloud.myop.dev/npm/{componentId}/vue
+```
+
+The generated package uses `defineComponent` with the `componentId` baked in. It emits `load`, `error`, `sizeChange`, and `cta` events — same API as `MyopComponent` but without needing a `componentId` prop.
+
+## TypeScript Types
+
+```ts
+import type {
+    IPropTypes,           // Full props type
+    ITypedMyopComponent,  // Component instance with typed props
+    IMyopComponentProps,  // myop_init_interface + myop_cta_handler
+    SizeInfo,             // { width, height, autoSizingWidth, autoSizingHeight }
+    EventHandlerProps,    // Generated event handler types
+    KebabToPascal,        // Utility type
+} from "@myop/vue";
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myop/cli",
-  "version": "0.1.45",
+  "version": "0.1.47",
   "description": "Myop cli",
   "type": "module",
   "repository": {