@servlyadmin/runtime-core 0.1.45 → 0.2.1

package/README.md

@@ -14,10 +14,88 @@ 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 Loading & Error States
+
+```typescript
+const app = await mount({
+  componentId: 'my-component-id',
+  target: '#app',
+  props: { title: 'Hello' },
+  
+  // Show loading indicator
+  loadingComponent: '<div class="skeleton animate-pulse h-32 bg-gray-200 rounded"></div>',
+  
+  // Show error message on failure
+  errorComponent: (err) => `<div class="text-red-500">Failed to load: ${err.message}</div>`,
+  
+  // Optional: delay before showing loading (avoids flash for fast loads)
+  loadingDelay: 200,
+  
+  // Optional: minimum time to show loading (avoids flash)
+  minLoadingTime: 500,
+  
+  // Lifecycle callbacks
+  onLoadStart: () => console.log('Loading...'),
+  onLoadEnd: () => console.log('Done!'),
+  onReady: (result) => console.log('Mounted!'),
+  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
@@ -83,6 +161,36 @@ const { data } = await fetchComponent('my-component', {
 });
 ```
 
+## Prefetching
+
+Preload components for faster subsequent rendering:
+
+```typescript
+import { prefetch, prefetchAll, prefetchOnHover, prefetchOnVisible, prefetchOnIdle } from '@servlyadmin/runtime-core';
+
+// Prefetch a single component
+await prefetch('pricing-card');
+
+// Prefetch multiple components
+await prefetchAll(['pricing-card', 'contact-form', 'navbar']);
+
+// Prefetch with versions
+await prefetchAll([
+  { id: 'pricing-card', version: '^1.0.0' },
+  { id: 'contact-form', version: 'latest' }
+]);
+
+// Prefetch on hover (great for modals/dialogs)
+const cleanup = prefetchOnHover('#open-modal-btn', 'modal-component');
+// Later: cleanup() to remove listener
+
+// Prefetch when element becomes visible (Intersection Observer)
+const cleanup = prefetchOnVisible('#pricing-section', ['pricing-card', 'feature-list']);
+
+// Prefetch when browser is idle (non-critical components)
+prefetchOnIdle(['footer', 'sidebar', 'help-modal']);
+```
+
 ## Core Concepts
 
 ### Layout Elements
@@ -135,6 +243,65 @@ 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,
+  },
+  
+  // Loading & Error States
+  loadingComponent?: string | HTMLElement,  // HTML to show while loading
+  errorComponent?: (err: Error) => string | HTMLElement,  // Error display
+  loadingDelay?: number,         // Delay before showing loading (ms)
+  minLoadingTime?: number,       // Minimum loading display time (ms)
+  
+  // Lifecycle Callbacks
+  onLoadStart?: () => void,      // Called when loading starts
+  onLoadEnd?: () => void,        // Called when loading ends
+  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.
@@ -284,6 +451,53 @@ hasTemplateSyntax('{{props.name}}'); // true
 hasTemplateSyntax('static text');    // false
 ```
 
+### Prefetch API
+
+Preload components for faster subsequent rendering.
+
+```typescript
+import { 
+  prefetch, 
+  prefetchAll, 
+  prefetchOnHover, 
+  prefetchOnVisible, 
+  prefetchOnIdle 
+} from '@servlyadmin/runtime-core';
+
+// Prefetch single component
+await prefetch('pricing-card');
+await prefetch('pricing-card', '^1.0.0');  // With version
+
+// Prefetch multiple components
+const { success, failed } = await prefetchAll([
+  'pricing-card',
+  'contact-form',
+  { id: 'navbar', version: '^2.0.0' }
+]);
+
+// Prefetch on hover (returns cleanup function)
+const cleanup = prefetchOnHover(
+  '#open-modal-btn',  // Target element
+  'modal-component',  // Component ID
+  'latest',           // Version
+  { delay: 100 }      // Options: delay before prefetch
+);
+// Later: cleanup()
+
+// Prefetch when element becomes visible
+const cleanup = prefetchOnVisible(
+  '#pricing-section',                    // Target element
+  ['pricing-card', 'feature-list'],      // Components to prefetch
+  { rootMargin: '100px', threshold: 0 }  // IntersectionObserver options
+);
+
+// Prefetch during browser idle time
+prefetchOnIdle(
+  ['footer', 'sidebar', 'help-modal'],
+  { timeout: 5000 }  // Max wait time before forcing prefetch
+);
+```
+
 ## Slots
 
 Components can define slots for content injection: