npm - @myop/cli - Versions diffs - 0.1.40 → 0.1.41 - Mend

@myop/cli 0.1.40 → 0.1.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/dist/myop-cli.js +1184 -833
package/dist/skills/myop-component/SKILL.md +233 -0
package/dist/skills/myop-component/references/best-practices.md +406 -0
package/dist/skills/myop-component/references/component-api.md +357 -0
package/dist/skills/myop-component/references/dev-workflow.md +218 -0
package/dist/skills/myop-component/references/sizing-and-layout.md +270 -0
package/dist/skills/myop-component/references/type-definitions.md +270 -0
package/package.json +2 -2

package/dist/skills/myop-component/SKILL.md ADDED Viewed

@@ -0,0 +1,233 @@
+---
+name: myop-component
+description: "Myop is a platform for creating self-contained HTML UI components that integrate into any host application. This skill covers the component public API (myop_init_interface, myop_cta_handler), type definitions, sizing, layout, development workflow, and CLI commands. When building or modifying a Myop component, you must learn this skill."
+---
+# Myop Component Developer
+Build high-performance, self-contained HTML components for the Myop platform.
+## Immediate Action Required - Read This First
+This skill activates when a `myop.config.json` file exists in the project, or when the user mentions "myop", "myop component", or asks to create/edit an HTML component for Myop.
+**Your first action MUST be:**
+1. Check if `myop.config.json` exists in the current directory
+2. If **YES** (existing component):
+   - Read `myop.config.json` to understand the component name and state
+   - Read `index.html` to understand the current component implementation
+   - Implement the requested changes following the patterns in this skill
+3. If **NO** (new component):
+   - Guide the user to run `myop create` to scaffold a new component
+   - Or create the files manually following the structure below
+## Component Architecture
+Every Myop component is a **single HTML file** (`index.html` or `dist/index.html`) that communicates with a host application through exactly **2 global functions**:
+| Function | Direction | Purpose | Reference |
+|----------|-----------|---------|-----------|
+| `myop_init_interface(data)` | Host -> Component | Receive data, render UI | [component-api.md](references/component-api.md) |
+| `myop_cta_handler(action, payload)` | Component -> Host | Send user actions back | [component-api.md](references/component-api.md) |
+## CRITICAL: Rules You Must Follow
+1. **Both functions MUST be defined at top-level script execution** - never inside `setTimeout`, `Promise.then`, `async`, `DOMContentLoaded`, or any deferred code
+2. **Rendering MUST be synchronous** - no `fetch`, no `await`, no `setTimeout` inside `myop_init_interface`
+3. **All state is private** - use an IIFE to encapsulate; only expose the 2 global functions
+4. **Single-file output** - the final deployed artifact is ONE HTML file with all CSS/JS inlined
+5. **No external network requests** - components cannot fetch external resources at runtime
+## Quick Start - Minimal Component
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="myop:size" content='{"width":"100%","height":"100%"}'>
+    <title>My Component</title>
+    <script type="myop/types">
+    interface MyopInitData {
+        title: string;
+        items: Array<{ id: string; label: string }>;
+    }
+    interface MyopCtaPayloads {
+        'item-selected': { itemId: string };
+        'size-requested': {
+            width?: number | null;
+            height?: number | null;
+            minWidth?: number | null;
+            maxWidth?: number | null;
+            minHeight?: number | null;
+            maxHeight?: number | null;
+            required?: boolean;
+        };
+    }
+    declare function myop_init_interface(): MyopInitData;
+    declare function myop_init_interface(data: MyopInitData): void;
+    declare function myop_cta_handler<K extends keyof MyopCtaPayloads>(
+        action: K, payload: MyopCtaPayloads[K]
+    ): void;
+    </script>
+    <style>
+        * { box-sizing: border-box; margin: 0; padding: 0; }
+        html, body { width: 100%; height: 100%; overflow: hidden;
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        }
+        #app-root { width: 100%; height: 100%; padding: 16px; }
+    </style>
+</head>
+<body>
+    <div id="app-root"></div>
+    <script>
+    (function() {
+        var state = {};
+        function render(data) {
+            state = data;
+            var root = document.getElementById('app-root');
+            root.innerHTML =
+                '<h2>' + (data.title || '') + '</h2>' +
+                '<ul>' + (data.items || []).map(function(item) {
+                    return '<li data-id="' + item.id + '">' + item.label + '</li>';
+                }).join('') + '</ul>';
+        }
+        window.myop_init_interface = function(data) {
+            if (!data) return state;
+            render(data);
+        };
+        window.myop_cta_handler = function(action, payload) {
+            // Overridden by host application
+        };
+        // Event delegation
+        document.getElementById('app-root').addEventListener('click', function(e) {
+            var li = e.target.closest('li');
+            if (li) {
+                window.myop_cta_handler('item-selected', { itemId: li.dataset.id });
+            }
+        });
+    })();
+    </script>
+    <script id="myop_preview">
+        window.myop_init_interface({
+            title: 'My Component',
+            items: [
+                { id: '1', label: 'First item' },
+                { id: '2', label: 'Second item' }
+            ]
+        });
+    </script>
+</body>
+</html>
+```
+## Component File Structure
+### Single-file mode (simplest)
+```
+project/
+├── index.html          # The entire component in one file
+├── myop.config.json    # Component metadata
+└── .gitignore
+```
+### Multi-file mode (with build step)
+```
+project/
+├── index.html          # HTML template with <link> and <script src>
+├── src/
+│   ├── index.js        # Entry point
+│   ├── modules/
+│   │   ├── app.js      # Application logic
+│   │   └── myop.js     # Myop interface setup
+│   └── styles/
+│       ├── index.css    # Style entry point
+│       └── main.css     # Main styles
+├── build.js            # esbuild bundler (inlines JS/CSS into dist/index.html)
+├── dist/
+│   └── index.html      # Built single-file output
+├── myop.config.json
+├── package.json
+└── .gitignore
+```
+### myop.config.json
+```json
+{
+  "name": "Component Name",
+  "componentId": "DEV",
+  "type": "html",
+  "author": "@myop-cli",
+  "HMR": true
+}
+```
+- `componentId` starts as `"DEV"` and gets replaced with a real UUID after first `myop push`
+- `organization` is added automatically after first push
+## Reference Documentation
+| Topic | Reference |
+|-------|-----------|
+| Public API (myop_init_interface, myop_cta_handler) | [component-api.md](references/component-api.md) |
+| Type Definitions (MyopInitData, MyopCtaPayloads) | [type-definitions.md](references/type-definitions.md) |
+| Sizing, Layout & Responsive Design | [sizing-and-layout.md](references/sizing-and-layout.md) |
+| CLI Commands & Dev Workflow | [dev-workflow.md](references/dev-workflow.md) |
+| Performance & Best Practices | [best-practices.md](references/best-practices.md) |
+## Common Mistakes - WRONG vs CORRECT
+### Function Definition Timing
+| WRONG | CORRECT |
+|-------|---------|
+| Defining inside `DOMContentLoaded` | Defining in top-level `<script>` |
+| Defining inside `setTimeout` | Defining in synchronous IIFE |
+| Defining inside `async` function | Defining before any async code |
+| Defining in a module with `export` | Assigning directly to `window` |
+### Rendering
+| WRONG | CORRECT |
+|-------|---------|
+| `await fetch()` inside `myop_init_interface` | Pure synchronous DOM manipulation |
+| `setTimeout(() => render())` | Immediate `innerHTML` assignment |
+| Multiple `appendChild` calls | Single `innerHTML` write |
+| `document.createElement` loops | Template literal string building |
+### State Management
+| WRONG | CORRECT |
+|-------|---------|
+| Global variables on `window` | Variables inside IIFE closure |
+| Mutating data passed to `myop_init_interface` | Storing a copy of the data |
+| Not returning state when called without args | `if (!data) return state;` pattern |
+## CLI Commands Quick Reference
+| Command | Description |
+|---------|-------------|
+| `myop create` | Create a new component (scaffolds files + starts dev server) |
+| `myop dev` | Start development server with HMR on port 9292 |
+| `myop push` | Upload component to Myop platform |
+| `myop sync` | Build and upload component to Myop platform |
+| `myop login` | Authenticate with Myop (opens browser) |
+| `myop logout` | Clear stored credentials |
+| `myop whoami` | Show current authenticated user |
+## Workflow Summary
+1. `myop create` - Scaffold a new component
+2. Edit `index.html` - Build your component UI
+3. `myop dev` - Preview with hot reload at http://localhost:9292
+4. `myop push` - Upload to Myop platform
+5. View on dashboard: `https://dashboard.myop.dev/dashboard/2.0/component/<componentId>`

package/dist/skills/myop-component/references/best-practices.md ADDED Viewed

@@ -0,0 +1,406 @@
+# Performance & Best Practices
+Myop components must render instantly within a single event loop tick. This document covers patterns for achieving high performance and avoiding common pitfalls.
+## Contents
+- [Performance Requirements](#performance-requirements)
+- [Rendering Patterns](#rendering-patterns)
+- [State Management](#state-management)
+- [Event Handling](#event-handling)
+- [CSS Patterns](#css-patterns)
+- [Accessibility](#accessibility)
+- [Anti-Patterns](#anti-patterns)
+## Performance Requirements
+1. **Synchronous rendering** - `myop_init_interface(data)` must update the DOM and return before yielding to the event loop
+2. **No network requests** - Components cannot fetch external resources
+3. **Single DOM write** - Build the entire HTML string, then set `innerHTML` once
+4. **Minimal reflows** - Avoid reading layout properties (offsetHeight, getBoundingClientRect) between writes
+## Rendering Patterns
+### Template Literal Rendering (recommended)
+```javascript
+function render(data) {
+    var root = document.getElementById('app-root');
+    root.innerHTML =
+        '<div class="header">' +
+            '<h2>' + escapeHtml(data.title) + '</h2>' +
+            '<span class="count">' + data.items.length + ' items</span>' +
+        '</div>' +
+        '<ul class="list">' +
+            data.items.map(function(item) {
+                return '<li class="item' + (item.active ? ' active' : '') + '"' +
+                    ' data-id="' + item.id + '">' +
+                    escapeHtml(item.name) +
+                '</li>';
+            }).join('') +
+        '</ul>';
+}
+function escapeHtml(str) {
+    if (!str) return '';
+    return String(str)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+```
+### DOM Caching
+Cache element references that don't change between renders:
+```javascript
+(function() {
+    // Cache once - these elements are in the static HTML
+    var root = document.getElementById('app-root');
+    var header = document.querySelector('.header');
+    var list = document.querySelector('.list');
+    function render(data) {
+        // Only update the parts that change
+        header.textContent = data.title;
+        list.innerHTML = data.items.map(function(item) {
+            return '<li data-id="' + item.id + '">' + item.name + '</li>';
+        }).join('');
+    }
+    // ...
+})();
+```
+### Conditional Rendering
+```javascript
+function render(data) {
+    var html = '<div class="container">';
+    if (data.loading) {
+        html += '<div class="spinner">Loading...</div>';
+    } else if (data.error) {
+        html += '<div class="error">' + escapeHtml(data.error) + '</div>';
+    } else if (data.items.length === 0) {
+        html += '<div class="empty">No items found</div>';
+    } else {
+        html += renderItemList(data.items);
+    }
+    html += '</div>';
+    document.getElementById('app-root').innerHTML = html;
+}
+```
+## State Management
+### IIFE Encapsulation (required)
+All component state and logic MUST be encapsulated in an IIFE (Immediately Invoked Function Expression):
+```javascript
+(function() {
+    // Private state - not accessible outside this closure
+    var state = {};
+    var selectedId = null;
+    var isExpanded = false;
+    // Private functions
+    function render(data) { /* ... */ }
+    function updateSelection(id) { /* ... */ }
+    // Only expose the 2 required globals
+    window.myop_init_interface = function(data) {
+        if (!data) return state;
+        state = data;
+        render(data);
+    };
+    window.myop_cta_handler = function(action, payload) {};
+})();
+```
+### Derived State
+Compute derived values during render, not on every access:
+```javascript
+function render(data) {
+    // Compute derived state once during render
+    var completedCount = data.tasks.filter(function(t) { return t.completed; }).length;
+    var pendingCount = data.tasks.length - completedCount;
+    var progress = data.tasks.length > 0
+        ? Math.round((completedCount / data.tasks.length) * 100)
+        : 0;
+    root.innerHTML =
+        '<div class="progress">' + progress + '% complete (' + completedCount + '/' + data.tasks.length + ')</div>' +
+        '<div class="list">' + renderTasks(data.tasks) + '</div>';
+}
+```
+### Local UI State
+For state that doesn't come from the host (e.g., expanded/collapsed sections, active tab):
+```javascript
+(function() {
+    var state = {};
+    var uiState = {
+        activeTab: 'all',
+        expandedSections: {}
+    };
+    function render(data) {
+        state = data;
+        var filtered = filterByTab(data.items, uiState.activeTab);
+        root.innerHTML = renderTabs(uiState.activeTab) + renderList(filtered);
+    }
+    function setTab(tab) {
+        uiState.activeTab = tab;
+        render(state);  // Re-render with same data, different UI state
+    }
+    // ...
+})();
+```
+## Event Handling
+### Event Delegation (required for dynamic content)
+Never attach event listeners to dynamically created elements. Use event delegation on a static parent:
+```javascript
+(function() {
+    var root = document.getElementById('app-root');
+    // Single listener handles all interactions
+    root.addEventListener('click', function(e) {
+        // Check what was clicked using closest()
+        var item = e.target.closest('.item');
+        if (item) {
+            window.myop_cta_handler('item-clicked', {
+                itemId: item.dataset.id
+            });
+            return;
+        }
+        var deleteBtn = e.target.closest('.delete-btn');
+        if (deleteBtn) {
+            e.stopPropagation();  // Don't trigger item click
+            window.myop_cta_handler('item-deleted', {
+                itemId: deleteBtn.closest('.item').dataset.id
+            });
+            return;
+        }
+        var tab = e.target.closest('.tab');
+        if (tab) {
+            setTab(tab.dataset.tab);
+            return;
+        }
+    });
+    // Input events
+    root.addEventListener('change', function(e) {
+        if (e.target.matches('.checkbox')) {
+            var item = e.target.closest('.item');
+            window.myop_cta_handler('item-toggled', {
+                itemId: item.dataset.id,
+                checked: e.target.checked
+            });
+        }
+    });
+})();
+```
+### Keyboard Support
+```javascript
+root.addEventListener('keydown', function(e) {
+    if (e.key === 'Enter' || e.key === ' ') {
+        var focusable = e.target.closest('[role="button"], .item');
+        if (focusable) {
+            e.preventDefault();
+            focusable.click();  // Reuse click handler
+        }
+    }
+});
+```
+## CSS Patterns
+### Scoped Styles
+Since the component runs in an iframe, global styles are safe. But for clarity, scope to `#app-root`:
+```css
+#app-root .header { /* ... */ }
+#app-root .item { /* ... */ }
+#app-root .item:hover { /* ... */ }
+#app-root .item.active { /* ... */ }
+```
+### Responsive Design
+Components should adapt to their container size. Use relative units and flexible layouts:
+```css
+#app-root {
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+    font-size: 14px;
+}
+/* Stack horizontally when wide enough */
+@media (min-width: 500px) {
+    .content {
+        flex-direction: row;
+    }
+}
+/* Compact mode for narrow containers */
+@media (max-width: 300px) {
+    .header { padding: 8px; font-size: 12px; }
+    .item { padding: 6px 8px; }
+}
+```
+### Theme Support
+Accept theme via data and apply with CSS classes:
+```javascript
+function render(data) {
+    document.documentElement.setAttribute('data-theme', data.config?.theme || 'light');
+    // ... render content
+}
+```
+```css
+:root {
+    --bg: #ffffff;
+    --text: #333333;
+    --border: #e0e0e0;
+}
+[data-theme="dark"] {
+    --bg: #1a1a2e;
+    --text: #e0e0e0;
+    --border: #333355;
+}
+#app-root {
+    background: var(--bg);
+    color: var(--text);
+}
+```
+## Accessibility
+### Semantic HTML
+```html
+<!-- Use semantic elements -->
+<nav class="tabs" role="tablist">...</nav>
+<main class="content" role="tabpanel">...</main>
+<!-- Use ARIA for custom widgets -->
+<div role="listbox" aria-label="Task list">
+    <div role="option" aria-selected="true">...</div>
+</div>
+```
+### Focus Management
+```css
+/* Visible focus indicators */
+:focus-visible {
+    outline: 2px solid #4a90d9;
+    outline-offset: 2px;
+}
+/* Interactive elements should be focusable */
+.item[tabindex="0"] { cursor: pointer; }
+```
+## Anti-Patterns
+### Never: Async operations in myop_init_interface
+```javascript
+// WRONG
+window.myop_init_interface = async function(data) {
+    const extra = await loadMoreData();     // NO
+    render(data, extra);
+};
+// WRONG
+window.myop_init_interface = function(data) {
+    fetch('/api/data').then(render);         // NO
+    setTimeout(() => render(data), 0);       // NO
+    requestAnimationFrame(() => render(data)); // NO
+};
+```
+### Never: Multiple DOM writes
+```javascript
+// WRONG - 3 reflows
+root.innerHTML = '<div class="header"></div>';
+root.querySelector('.header').textContent = data.title;
+root.innerHTML += '<ul>' + listHtml + '</ul>';
+// CORRECT - 1 DOM write
+root.innerHTML =
+    '<div class="header">' + data.title + '</div>' +
+    '<ul>' + listHtml + '</ul>';
+```
+### Never: Global variables
+```javascript
+// WRONG - pollutes global scope
+var myState = {};
+window.myHelper = function() {};
+// CORRECT - everything inside IIFE
+(function() {
+    var myState = {};
+    function myHelper() {}
+    // ...
+})();
+```
+### Never: Direct DOM creation in loops
+```javascript
+// WRONG - O(n) reflows
+data.items.forEach(function(item) {
+    var li = document.createElement('li');
+    li.textContent = item.name;
+    list.appendChild(li);        // Reflow on each append
+});
+// CORRECT - single innerHTML write
+list.innerHTML = data.items.map(function(item) {
+    return '<li>' + escapeHtml(item.name) + '</li>';
+}).join('');
+```
+### Never: External resource loading
+```javascript
+// WRONG - components can't fetch
+var img = new Image();
+img.src = 'https://external-cdn.com/image.png';  // NO
+// WRONG - loading external scripts
+var script = document.createElement('script');
+script.src = 'https://cdn.example.com/lib.js';    // NO
+```