@servlyadmin/runtime-core 0.1.45 → 0.1.46

package/README.md

@@ -14,10 +14,60 @@ pnpm add @servlyadmin/runtime-core
 
 ## Quick Start
 
+The simplest way to render a component:
+
+```typescript
+import { mount } from '@servlyadmin/runtime-core';
+
+// Mount a component - that's it!
+const app = await mount({
+  componentId: 'my-component-id',
+  target: '#app',
+  props: { title: 'Hello World' }
+});
+
+// Update props
+app.update({ props: { title: 'Updated!' } });
+
+// Cleanup
+app.destroy();
+```
+
+### With Callbacks
+
+```typescript
+const app = await mount({
+  componentId: 'my-component-id',
+  target: '#app',
+  props: { title: 'Hello' },
+  onReady: (result) => console.log('Mounted!', result.version),
+  onError: (err) => console.error('Failed:', err)
+});
+```
+
+### With Version & Cache Control
+
+```typescript
+const app = await mount({
+  componentId: 'my-component-id',
+  target: document.getElementById('app'),
+  props: { title: 'Hello' },
+  version: '^1.0.0',
+  fetchOptions: {
+    cacheStrategy: 'memory',
+    forceRefresh: true
+  }
+});
+```
+
+## Low-Level API
+
+For more control, use `fetchComponent` and `render` directly:
+
 ```typescript
 import { render, fetchComponent } from '@servlyadmin/runtime-core';
 
-// Fetch a component from the registry (uses Servly's default registry)
+// Fetch a component from the registry
 const { data } = await fetchComponent('my-component-id');
 
 // Render to a container
@@ -135,6 +185,55 @@ const elements = [
 
 ## API Reference
 
+### mount(options) - Recommended
+
+The simplest way to render a component. Handles fetching, container resolution, and rendering.
+
+```typescript
+const app = await mount({
+  componentId: string,           // Required: Component ID to fetch
+  target: string | HTMLElement,  // Required: CSS selector or element
+  props?: Record<string, any>,   // Props to pass (default: {})
+  state?: Record<string, any>,   // Initial state (default: {})
+  context?: Record<string, any>, // Additional context (default: {})
+  version?: string,              // Version specifier (default: 'latest')
+  eventHandlers?: Record<string, Record<string, (e: Event) => void>>,
+  fetchOptions?: {
+    cacheStrategy?: 'localStorage' | 'memory' | 'none',
+    forceRefresh?: boolean,
+    apiKey?: string,
+    retryConfig?: RetryConfig,
+  },
+  onReady?: (result: MountResult) => void,
+  onError?: (error: Error) => void,
+});
+
+// Returns MountResult
+interface MountResult {
+  update(context: Partial<BindingContext>): void;
+  destroy(): void;
+  rootElement: HTMLElement | null;
+  container: HTMLElement;
+  data: ComponentData;
+  fromCache: boolean;
+  version: string;
+}
+```
+
+### mountData(options)
+
+Mount with pre-fetched data (useful for SSR or custom data sources):
+
+```typescript
+import { mountData } from '@servlyadmin/runtime-core';
+
+const app = mountData({
+  data: myComponentData,  // Pre-fetched ComponentData
+  target: '#app',
+  props: { title: 'Hello' }
+});
+```
+
 ### render(options)
 
 Renders elements to a container.

package/dist/index.cjs

@@ -773,6 +773,8 @@ __export(index_exports, {
   loadFont: () => loadFont,
   loadFonts: () => loadFonts,
   markElementReady: () => markElementReady,
+  mount: () => mount,
+  mountData: () => mountData,
   navigateTo: () => navigateTo,
   parseVersion: () => parseVersion,
   prefetchComponents: () => prefetchComponents,
@@ -5282,6 +5284,109 @@ async function getDependencyTree(id, options = {}) {
   return data.data;
 }
 
+// src/mount.ts
+async function mount(options) {
+  const {
+    componentId,
+    target,
+    props = {},
+    state = {},
+    context = {},
+    version = "latest",
+    eventHandlers,
+    fetchOptions = {},
+    onReady,
+    onError
+  } = options;
+  try {
+    const container = typeof target === "string" ? document.querySelector(target) : target;
+    if (!container) {
+      throw new Error(`Target container not found: ${target}`);
+    }
+    const fetchResult = await fetchComponentWithDependencies(componentId, {
+      ...fetchOptions,
+      version
+    });
+    const { data, fromCache, version: resolvedVersion, registry, views } = fetchResult;
+    const bindingContext = {
+      props,
+      state,
+      context
+    };
+    const renderResult = render({
+      container,
+      elements: data.layout,
+      context: bindingContext,
+      eventHandlers,
+      componentRegistry: registry,
+      views
+    });
+    const result = {
+      update: (newContext) => {
+        renderResult.update({
+          props: newContext.props ?? props,
+          state: newContext.state ?? state,
+          context: newContext.context ?? context
+        });
+      },
+      destroy: () => {
+        renderResult.destroy();
+      },
+      rootElement: renderResult.rootElement,
+      container,
+      data,
+      fromCache,
+      version: resolvedVersion
+    };
+    onReady?.(result);
+    return result;
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    onError?.(err);
+    throw err;
+  }
+}
+function mountData(options) {
+  const {
+    data,
+    target,
+    props = {},
+    state = {},
+    context = {},
+    eventHandlers
+  } = options;
+  const container = typeof target === "string" ? document.querySelector(target) : target;
+  if (!container) {
+    throw new Error(`Target container not found: ${target}`);
+  }
+  const bindingContext = {
+    props,
+    state,
+    context
+  };
+  const renderResult = render({
+    container,
+    elements: data.layout,
+    context: bindingContext,
+    eventHandlers
+  });
+  return {
+    update: (newContext) => {
+      renderResult.update({
+        props: newContext.props ?? props,
+        state: newContext.state ?? state,
+        context: newContext.context ?? context
+      });
+    },
+    destroy: () => {
+      renderResult.destroy();
+    },
+    rootElement: renderResult.rootElement,
+    container,
+    data
+  };
+}
+
 // src/version.ts
 function parseVersion(version) {
   const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
@@ -5754,6 +5859,8 @@ init_tailwind();
   loadFont,
   loadFonts,
   markElementReady,
+  mount,
+  mountData,
   navigateTo,
   parseVersion,
   prefetchComponents,

package/dist/index.js

@@ -4479,6 +4479,109 @@ async function getDependencyTree(id, options = {}) {
   return data.data;
 }
 
+// src/mount.ts
+async function mount(options) {
+  const {
+    componentId,
+    target,
+    props = {},
+    state = {},
+    context = {},
+    version = "latest",
+    eventHandlers,
+    fetchOptions = {},
+    onReady,
+    onError
+  } = options;
+  try {
+    const container = typeof target === "string" ? document.querySelector(target) : target;
+    if (!container) {
+      throw new Error(`Target container not found: ${target}`);
+    }
+    const fetchResult = await fetchComponentWithDependencies(componentId, {
+      ...fetchOptions,
+      version
+    });
+    const { data, fromCache, version: resolvedVersion, registry, views } = fetchResult;
+    const bindingContext = {
+      props,
+      state,
+      context
+    };
+    const renderResult = render({
+      container,
+      elements: data.layout,
+      context: bindingContext,
+      eventHandlers,
+      componentRegistry: registry,
+      views
+    });
+    const result = {
+      update: (newContext) => {
+        renderResult.update({
+          props: newContext.props ?? props,
+          state: newContext.state ?? state,
+          context: newContext.context ?? context
+        });
+      },
+      destroy: () => {
+        renderResult.destroy();
+      },
+      rootElement: renderResult.rootElement,
+      container,
+      data,
+      fromCache,
+      version: resolvedVersion
+    };
+    onReady?.(result);
+    return result;
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    onError?.(err);
+    throw err;
+  }
+}
+function mountData(options) {
+  const {
+    data,
+    target,
+    props = {},
+    state = {},
+    context = {},
+    eventHandlers
+  } = options;
+  const container = typeof target === "string" ? document.querySelector(target) : target;
+  if (!container) {
+    throw new Error(`Target container not found: ${target}`);
+  }
+  const bindingContext = {
+    props,
+    state,
+    context
+  };
+  const renderResult = render({
+    container,
+    elements: data.layout,
+    context: bindingContext,
+    eventHandlers
+  });
+  return {
+    update: (newContext) => {
+      renderResult.update({
+        props: newContext.props ?? props,
+        state: newContext.state ?? state,
+        context: newContext.context ?? context
+      });
+    },
+    destroy: () => {
+      renderResult.destroy();
+    },
+    rootElement: renderResult.rootElement,
+    container,
+    data
+  };
+}
+
 // src/version.ts
 function parseVersion(version) {
   const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
@@ -4946,6 +5049,8 @@ export {
   loadFont,
   loadFonts,
   markElementReady,
+  mount,
+  mountData,
   navigateTo,
   parseVersion,
   prefetchComponents,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@servlyadmin/runtime-core",
-  "version": "0.1.45",
+  "version": "0.1.46",
   "description": "Framework-agnostic core renderer for Servly components",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -40,4 +40,4 @@
     "vitest": "^1.0.0",
     "fast-check": "^3.15.0"
   }
-}
+}