@myop/sdk 0.2.3 → 0.2.5

package/README.md

@@ -1,288 +1,448 @@
-# Myop SDKs
-# Enhance Your UI Management with Real-Time Flexibility
-
-## **Next-Level UI/UX Management with Myop SDKs**
-Myop offers an open-source set of SDKs designed to connect your application
-logic with dynamically chosen user interfaces.
-It simplifies experimenting with UI/UX changes without deployments or direct
-involvement from your host application.
-It allows developers to refactor the look and feel of any component without
-disrupting its core functionalities like data fetching, state or event handling
-while maintaining typed communication between components and the host application,
-just like any local component you have today.
-
-## **Table of Contents**
-1. [Root SDK](#root-sdk)
-2. [Host SDK](#host-sdk)
-3. [Iframe SDK](#iframe-sdk)
-4. [WebComponent SDK](#webcomponent-sdk)
-5. [Framework Integrations](#framework-integrations)
-    - [React](#react)
-    - [Angular](#angular)
-    - [Vue.js](#vuejs)
-6. [Key Features of Myop SDKs](#key-features-of-myop-sdks)
-7. [Why Choose Myop SDKs?](#why-choose-myop-sdks)
-8. [Get Started with Myop SDKs Today!](#get-started-with-myop-sdks-today)
-9. [Related Resources](#related-resources)
+<p align="center">
+  <a href="https://myop.dev">
+    <img src="https://docs.myop.dev/img/logo.svg" alt="Myop Logo" width="200" />
+  </a>
+</p>
+
+<h1 align="center">Myop SDK</h1>
+
+<p align="center">
+  <strong>Dynamic UI component management for modern web applications</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@myop/sdk"><img src="https://img.shields.io/npm/v/@myop/sdk.svg?style=flat-square" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@myop/sdk"><img src="https://img.shields.io/npm/dm/@myop/sdk.svg?style=flat-square" alt="npm downloads"></a>
+  <a href="https://myop.dev/discord"><img src="https://img.shields.io/badge/Discord-Join%20Us-7289da?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a>
+</p>
+
+<p align="center">
+  <a href="https://docs.myop.dev">Documentation</a> |
+  <a href="https://myop.dev">Website</a> |
+  <a href="https://myop.dev/discord">Discord</a>
+</p>
 
 ---
 
-## **Root SDK - The Core of Your Application Integration**
-The **Root SDK** is the starting point for using Myop’s powerful UI components. It enables you to dynamically load, control, and interact with Myop components inside your web application, offering full control over UI modifications with minimal setup.
+## What is Myop?
 
-### **Installation - How to Integrate the Root SDK**
-You can load the Root SDK into your application in one of two ways:
+Myop is an open-source SDK that enables **real-time UI modifications without deployments**. It bridges your application logic with dynamically swappable user interfaces, allowing developers to:
+
+- Experiment with UI/UX changes instantly
+- Refactor component appearance without touching core functionality
+- Maintain typed communication between components and host applications
+- Load and manage UI components dynamically at runtime
+
+## Installation
+
+```bash
+npm install @myop/sdk
+```
+
+Or via CDN:
 
-1. **Via CDN (Script Tag):**
 ```html
 <script src="https://cdn.myop.dev/sdk/next/myop_sdk.min.js"></script>
-<script>
-    // Initialize the SDK
-    const { hostSDK } = await window.myop.rootSDK.getHostModule();
-    const { MyopMessages } = await window.myop.rootSDK.getMyopMessages();
-</script>
 ```
-2 **Via NPM (Import into TypeScript/JavaScript Application):**
 
+## Quick Start
 
-```ts
+### Using npm/ESM
+
+```typescript
 import { getHostModule } from '@myop/sdk';
 
+// Initialize the SDK
 const { hostSDK } = await getHostModule();
-```
+hostSDK.init();
 
-Initialization and Component Loading
-Once the SDK is loaded, you can initialize the hostSDK and start interacting with components.
+// Load a component
+const component = await hostSDK.loadComponent(componentConfig, containerElement);
+await component.initiated();
+```
 
-```js
-// Initialize hostSDK instance
-hostSDK.init();
+### Using CDN
 
-// Load Myop components into your app dynamically
-let myopComponent1 = await hostSDK.loadComponent(config.components['myExternalComponent1'], appDiv);
-await myopComponent1.initiated();
+```html
+<script src="https://cdn.myop.dev/sdk/next/myop_sdk.min.js"></script>
+<script>
+  const { hostSDK } = await window.myop.rootSDK.getHostModule();
+  hostSDK.init();
 
-// Send messages or modify UI components
-const appTitleSelector = new MyopMessages.MyopElementSelector('myAppTitle');
-myopComponent1.send(new MyopMessages.ChangeTextMessage(appTitleSelector, `Myop - WebComponents`));
+  const component = await hostSDK.loadComponent(config, document.getElementById('app'));
+  await component.initiated();
+</script>
 ```
-Host SDK - Integrate Myop Components into Your App
-The Host SDK is designed for applications that act as containers for Myop components. It provides core functionalities for embedding and managing Myop components within your web app, enabling smooth communication and integration.
 
-With the Host SDK, you can:
+## Architecture
 
-Dynamically register, load, and control Myop components.
-Ensure seamless integration and maintain consistent UX across multiple components.
-Communicate with the embedded Myop components using event-driven APIs.
-### 📕 Host SDK Documentation
-Explore the full documentation for the Host SDK to unlock the full potential of Myop's component-based UI management.
+The Myop SDK is modular, consisting of several specialized packages:
 
-Iframe SDK - Isolation with Seamless Communication
-The Iframe SDK is perfect for integrating Myop components into isolated environments such as iframes. It provides tools and utilities for secure communication between the host app and the Myop components running inside iframes.
+| Module | Description | Import |
+|--------|-------------|--------|
+| **Host SDK** | Core module for embedding and managing Myop components | `@myop/sdk` or `@myop/sdk/host` |
+| **Iframe SDK** | Secure isolation for components in iframes | `@myop/sdk/iframe` |
+| **WebComponent SDK** | Support for self-contained web components | `@myop/sdk/webcomponent` |
+| **Messages** | Type-safe communication between host and components | `@myop/sdk/messages` |
+| **Helpers** | Utility functions and configuration builders | `@myop/sdk/helpers` |
 
-Using the Iframe SDK, developers can:
+## Framework Integration
 
-Achieve secure isolation for Myop components while retaining communication with the host application.
-Benefit from the overall structure and management capabilities of the host app, without sacrificing security or performance.
-Easily load and manage iframe-based components within your web app.
-How to Load the Iframe SDK
-You can load the Iframe SDK after loading the Root SDK in two simple steps:
+Myop provides official framework packages for seamless integration:
 
-Via Script Tag:
-```js
-const { IframeSDK } = await window.myop.rootSDK.getIframeModule();
-```
+| Package | Install |
+|---------|---------|
+| React | `npm install @myop/react` |
+| Vue.js | `npm install @myop/vue` |
+| Angular | `npm install @myop/angular` |
 
-Via NPM (Import into TypeScript/JavaScript Application):
+<details>
+<summary><strong>React</strong></summary>
 
-```ts
-import { getIframeModule } from '@myop/sdk';
-const { IframeSDK } = await getIframeModule();
+```bash
+npm install @myop/react
 ```
 
-### 📕 Iframe SDK Documentation
-For a deep dive into the Iframe SDK’s capabilities and usage, refer to the detailed documentation.
+```tsx
+import { MyopComponent } from '@myop/react';
+
+function App() {
+  return (
+    <MyopComponent
+      componentId="your-component-id"
+      environment="production"
+      data={{ user: 'John' }}
+      onLoad={(component) => console.log('Component loaded', component)}
+      onError={(error) => console.error('Error:', error)}
+      on={(action, payload) => {
+        // Handle CTA actions from the component
+        console.log('Action:', action, payload);
+      }}
+      loader={<div>Loading...</div>}
+      fallback={<div>Failed to load</div>}
+    />
+  );
+}
+```
 
-WebComponent SDK - Embedding Reusable Web Components
-The WebComponent SDK is built to support the use of Myop components packaged as self-contained web components. It simplifies lifecycle management, event handling, and communication, ensuring smooth integration with the host application.
+**Props:**
 
-With this SDK, developers can:
+| Prop | Type | Description |
+|------|------|-------------|
+| `componentId` | `string` | Component ID from Myop Cloud |
+| `environment` | `string` | Environment identifier (default: `"production"`) |
+| `data` | `any` | Data passed to `myop_init_interface` |
+| `onLoad` | `(component) => void` | Called when component loads |
+| `onError` | `(error) => void` | Called on error |
+| `on` | `(action, payload) => void` | Handler for `myop_cta_handler` calls |
+| `loader` | `ReactNode` | Custom loading indicator |
+| `fallback` | `ReactNode` | Custom error fallback |
+| `fadeDuration` | `number` | Loader fade duration in ms |
 
-Create modular, reusable web components that can be used across various applications.
-Benefit from lifecycle management tools to handle component states, initialization, and teardown.
-Enable communication between the host application and the web components for dynamic, real-time changes.
-How to Load the WebComponent SDK
-Once the Root SDK is loaded, you can seamlessly load the WebComponent SDK:
+**Preloading:**
 
-Via Script Tag:
-```js
-const { WebComponentSDK } = await window.myop.rootSDK.getWebcomponentModule();
-```
+```tsx
+import { preload, isPreloaded } from '@myop/react';
 
-Via NPM (Import into TypeScript/JavaScript Application):
+// Preload components for faster rendering
+await preload(['component-1', 'component-2'], 'production');
 
-```ts
-import { getWebcomponentModule } from '@myop/sdk';
-const { WebComponentSDK } = await getWebcomponentModule();
+// Check if already loaded
+if (isPreloaded('component-1')) {
+  // Component will render instantly
+}
 ```
 
-### 📕 WebComponent SDK Documentation
-Learn more about the WebComponent SDK and how it can enhance your application development in the full documentation.
+**Local Development:**
 
-Framework Integrations
-Myop SDKs can be seamlessly integrated with popular frontend frameworks like React, Angular, and Vue.js. This section provides detailed instructions for integrating Myop SDKs with these frameworks to help you get started faster.
+```tsx
+import { enableLocalDev } from '@myop/react';
 
-React Integration
-To use Myop with React, follow these steps:
+// Point to local server
+enableLocalDev();
+```
+
+</details>
 
-Install the Myop SDK via npm:
+<details>
+<summary><strong>Vue.js</strong></summary>
 
 ```bash
-npm install @myop/sdk
+npm install @myop/vue
 ```
-Create a React Component that Loads Myop Components:
-
-```jsx
-import React, { useEffect, useRef } from 'react';
-import { getHostModule } from '@myop/sdk';
 
-const MyopComponent = () => {
-    const containerRef = useRef(null);
+```vue
+<template>
+  <MyopContainer
+    :componentId="componentId"
+    :flowId="flowId"
+    @ready="onReady"
+    v-bind="$attrs"
+  >
+    <template #loading>
+      <div>Loading...</div>
+    </template>
+  </MyopContainer>
+</template>
 
-    useEffect(() => {
-        const loadMyopComponent = async () => {
-            const { hostSDK } = await getHostModule();
-            const myopComponent = await hostSDK.loadComponent(config.components['myExternalComponent1'], containerRef.current);
-            await myopComponent.initiated();
-        };
+<script setup lang="ts">
+import { MyopContainer } from '@myop/vue';
+import type { IMyopComponent } from '@myop/sdk/host';
 
-        loadMyopComponent();
-    }, []);
+const componentId = 'your-component-id';
+const flowId = 'optional-flow-id';
 
-    return <div ref={containerRef}></div>;
+const onReady = (component: IMyopComponent, innerRef?: any) => {
+  console.log('Component loaded', component);
 };
-
-export default MyopComponent;
+</script>
 ```
 
-Use the React Component:
+**Props:**
 
-```jsx
-import React from 'react';
-import MyopComponent from './MyopComponent';
+| Prop | Type | Description |
+|------|------|-------------|
+| `componentId` | `string` | Component ID from Myop Cloud |
+| `flowId` | `string?` | Optional flow ID |
+| `onReady` | `(component, innerRef?) => void` | Called when component loads |
 
-const App = () => {
-    return (
-        <div>
-            <h1>Myop + React</h1>
-            <MyopComponent />
-        </div>
-    );
-};
+**Slots:**
 
-export default App;
-```
+| Slot | Description |
+|------|-------------|
+| `loading` | Shown while component loads |
 
-Angular Integration
-For Angular applications, you can integrate Myop SDKs by following these steps:
+</details>
 
-Install Myop SDK via npm:
+<details>
+<summary><strong>Angular</strong></summary>
 
 ```bash
-npm install @myop/sdk
+npm install @myop/angular
 ```
 
-Import and Use Myop SDK in Angular Component:
-
-```ts
-import { Component, OnInit, ElementRef } from '@angular/core';
-import { getHostModule } from '@myop/sdk';
+```typescript
+import { Component } from '@angular/core';
+import { MyopContainerComponent } from '@myop/angular';
+import type { IMyopComponent } from '@myop/sdk/host';
 
 @Component({
-    selector: 'app-myop',
-    template: `<div #container></div>`,
+  selector: 'app-root',
+  standalone: true,
+  imports: [MyopContainerComponent],
+  template: `
+    <myop-container
+      [componentId]="componentId"
+      [flowId]="flowId"
+      [inputs]="inputs"
+      (componentReady)="onComponentReady($event)"
+    >
+      <!-- Content shown while loading -->
+      <div>Loading...</div>
+    </myop-container>
+  `
 })
-export class MyopComponent implements OnInit {
-    constructor(private el: ElementRef) {}
-
-    async ngOnInit() {
-        const { hostSDK } = await getHostModule();
-        const myopComponent = await hostSDK.loadComponent(config.components['myExternalComponent1'], this.el.nativeElement);
-        await myopComponent.initiated();
-    }
+export class AppComponent {
+  componentId = 'your-component-id';
+  flowId?: string;
+  inputs = { theme: 'dark' };
+
+  onComponentReady(component: IMyopComponent) {
+    console.log('Component loaded', component);
+  }
 }
 ```
-Add the Component in the Template:
+
+**Inputs:**
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `componentId` | `string` | Component ID from Myop Cloud |
+| `flowId` | `string?` | Optional flow ID |
+| `inputs` | `object` | Data passed to the component |
+
+**Outputs:**
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `componentReady` | `IMyopComponent` | Emitted when component loads |
+
+</details>
+
+<details>
+<summary><strong>Vanilla JavaScript / CDN</strong></summary>
 
 ```html
-<app-myop></app-myop>
-```
+<div id="myop-container"></div>
 
-Vue.js Integration
-Vue.js developers can integrate Myop SDKs with ease by following these steps:
-Install the Myop SDK:
+<script src="https://cdn.myop.dev/sdk/next/myop_sdk.min.js"></script>
+<script>
+  async function init() {
+    const { hostSDK } = await window.myop.rootSDK.getHostModule();
+    const { CloudRepository } = await window.myop.rootSDK.getMyopHelpers();
 
-```bash
-npm install @myop/sdk
+    const container = document.getElementById('myop-container');
+
+    // ============ V1: User Flows ============
+    // Fetch from auto-generated flow
+    const configV1 = await CloudRepository.Main.fetchComponentV1('component-id');
+    await hostSDK.loadComponent(configV1, container);
+
+    // Or fetch from a specific flow
+    const configFromFlow = await CloudRepository.Main.fetchComponentV1('component-id', 'flow-id');
+
+    // ============ V2: Direct Variant Loading ============
+    // Fetch variant directly by component ID and environment
+    const variantV2 = await CloudRepository.Main.fetchComponentV2('component-id', 'production');
+    await hostSDK.loadComponent(variantV2, container);
+  }
+
+  init();
+</script>
 ```
 
-Create a Vue Component that Loads Myop Components:
+</details>
 
-```vue
-<template>
-    <div ref="container"></div>
-</template>
+## API Reference
 
-<script>
+### CloudRepository
+
+Fetch component configurations from Myop Cloud:
+
+```typescript
+import { CloudRepository } from '@myop/sdk/helpers';
+
+// Fetch a component (v1 - from user flows)
+const componentConfig = await CloudRepository.Main.fetchComponent('component-id');
+
+// Fetch a component from a specific flow
+const componentConfig = await CloudRepository.Main.fetchComponent('component-id', 'flow-id');
+
+// Fetch a v2 component variant
+const variantConfig = await CloudRepository.Main.fetchComponentV2('component-id', 'environment');
+
+// Fetch a complete user flow
+const flow = await CloudRepository.Main.fetchFlow('flow-id');
+
+// Check if a component is preloaded
+const isLoaded = CloudRepository.Main.isPreloaded('component-id');
+```
+
+### Host SDK
+
+```typescript
 import { getHostModule } from '@myop/sdk';
 
-export default {
-    name: 'MyopComponent',
-    mounted() {
-        const loadMyopComponent = async () => {
-            const { hostSDK } = await getHostModule();
-            const myopComponent = await hostSDK.loadComponent(config.components['myExternalComponent1'], this.$refs.container);
-            await myopComponent.initiated();
-        };
-
-        loadMyopComponent();
-    },
-};
-</script>
+const { hostSDK } = await getHostModule();
+
+// Load a component into a container
+const component = await hostSDK.loadComponent(componentConfig, containerElement);
+
+// Load with options
+const component = await hostSDK.loadComponent(componentConfig, container, {
+  hidden: false,           // Start hidden
+  connectProps: true,      // Auto-connect props (default: true)
+  timeout: 5000,           // Initialization timeout
+  hooks: {                 // Lifecycle hooks
+    afterSkinSelected: async (skin) => skin
+  }
+});
+
+// Navigate to a different component
+const newComponent = await hostSDK.navigate(currentComponent, newConfig, {
+  staged: true,  // Load new component before disposing old one
+});
+
+// Send messages to component
+component.send(message);
+
+// Dispose component
+component.dispose();
 ```
 
-Use the Vue Component:
+### ComponentConfig Builder
 
-```vue
-<template>
-    <MyopComponent />
-</template>
+Build component configurations programmatically:
+
+```typescript
+import { ComponentConfig, SkinConfig } from '@myop/sdk/helpers';
+
+const skin = SkinConfig.create()
+  .withHTMLLoader({
+    HTML: '<div>My Component</div>',
+    shadowRootMode: 'open'
+  })
+  .build();
+
+const config = ComponentConfig.create()
+  .withName('my-component')
+  .withDefaultSkin(skin)
+  .withBasicRef('header')
+  .withBasicRef('content')
+  .build();
+```
+
+### Iframe SDK
+
+For components running inside iframes:
+
+```typescript
+import { getIframeModule } from '@myop/sdk';
+
+const { IframeSDK } = await getIframeModule();
 ```
 
-### Key Features of Myop SDKs
-- Real-time UI Modifications
-  - Modify your application's UI dynamically without requiring redeployment or backend changes.
-- Seamless Integration
-  - Easily integrate Myop components into any web application, whether in an iframe or as standalone web components.
-- Component Flexibility
-  - Load and use Myop components based on your app’s requirements and communication needs.
-- Independent Lifecycle Management
-  - Manage the lifecycle of each component independently, ensuring optimal performance and reusability.
-### Why Choose Myop SDKs?
-Myop offers a powerful, flexible approach to managing your web application’s UI/UX, making it easier to:
-
-- Scale your application with minimal friction.
-- Empower front-end developers to manage UI changes independently.
-- Build modular and reusable components that can be dynamically loaded based on real-time conditions.
-- With comprehensive documentation and support for various use cases, Myop SDKs provide a future-proof solution for modern web development.
-
-### Get Started with Myop SDKs Today!
-Take your web app to the next level with Myop SDKs. Whether you’re looking to integrate dynamic UI components, manage separate iframe-based applications, or work with modular web components, Myop has you covered.
-
-For more information, examples, and detailed documentation, check out the links to each SDK section above.
-
-Related Resources:
+### WebComponent SDK
+
+For self-contained web components:
+
+```typescript
+import { getWebcomponentModule } from '@myop/sdk';
+
+const { WebComponentSDK } = await getWebcomponentModule();
+```
+
+## Documentation
+
+For comprehensive documentation, guides, and examples, visit **[docs.myop.dev](https://docs.myop.dev)**.
+
+- [Getting Started Guide](https://docs.myop.dev/getting-started)
+- [Host SDK Reference](https://docs.myop.dev/host-sdk)
+- [Iframe SDK Reference](https://docs.myop.dev/iframe-sdk)
+- [WebComponent SDK Reference](https://docs.myop.dev/webcomponent-sdk)
+- [Message API Reference](https://docs.myop.dev/messages)
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Run tests
+npm test
+
+# Build for production
+npm run build
+
+# Generate documentation
+npm run build:docs
+```
+
+## Related Resources
+
 - [Read more about Myop](https://myop.dev)
 - [Myop Documentation](https://docs.myop.dev)
-- [Join Myop on GitHub](https://github.com/myopjs)
-- [Discord Community & Support Forum](https://discord.com/invite/wTwZn3fq)
+- [Discord Community](https://myop.dev/discord)
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+
+---
+
+<p align="center">
+  Made with care by the <a href="https://myop.dev">Myop</a> team
+</p>