@servlyadmin/runtime-core 0.1.36 → 0.1.38

package/README.md

@@ -17,8 +17,8 @@ pnpm add @servlyadmin/runtime-core
 ```typescript
 import { render, fetchComponent } from '@servlyadmin/runtime-core';
 
-// Fetch a component from the registry
-const { data } = await fetchComponent('my-component', { version: 'latest' });
+// Fetch a component from the registry (uses Servly's default registry)
+const { data } = await fetchComponent('my-component-id');
 
 // Render to a container
 const result = render({
@@ -42,6 +42,47 @@ result.update({
 result.destroy();
 ```
 
+## Registry Configuration
+
+By default, components are fetched from Servly's production registry:
+- **Default URL**: `https://core-api.servly.app/v1/views/registry`
+
+You can override this if you have a custom registry:
+
+```typescript
+import { setRegistryUrl } from '@servlyadmin/runtime-core';
+
+// Use a custom registry
+setRegistryUrl('https://your-api.com/v1/views/registry');
+```
+
+## Cache Strategies
+
+The runtime supports three caching strategies to optimize component loading:
+
+| Strategy | Description | Persistence | Best For |
+|----------|-------------|-------------|----------|
+| `localStorage` | Persists across browser sessions | Yes | Production apps (default) |
+| `memory` | In-memory cache, cleared on page refresh | No | Development, SSR |
+| `none` | No caching, always fetches fresh | No | Testing, debugging |
+
+**Default**: `localStorage` - Components are cached in the browser's localStorage for fast subsequent loads.
+
+```typescript
+// Use default localStorage caching
+const { data } = await fetchComponent('my-component');
+
+// Explicitly set cache strategy
+const { data } = await fetchComponent('my-component', {
+  cacheStrategy: 'memory',  // or 'localStorage' or 'none'
+});
+
+// Force refresh (bypass cache)
+const { data } = await fetchComponent('my-component', {
+  forceRefresh: true,
+});
+```
+
 ## Core Concepts
 
 ### Layout Elements
@@ -51,14 +92,15 @@ Components are defined as a tree of layout elements:
 ```typescript
 interface LayoutElement {
   i: string;           // Unique identifier
-  type: string;        // HTML tag or component type
+  componentId: string; // Element type (container, text, button, etc.)
   configuration?: {    // Element configuration
-    className?: string;
+    classNames?: string;
     style?: Record<string, any>;
-    textContent?: string;
+    text?: string;
     // ... other attributes
   };
-  children?: LayoutElement[];  // Nested elements
+  children?: string[]; // Child element IDs
+  parent?: string;     // Parent element ID
 }
 ```
 
@@ -82,10 +124,10 @@ Use `{{path}}` syntax to bind data:
 const elements = [
   {
     i: 'greeting',
-    type: 'h1',
+    componentId: 'text',
     configuration: {
-      textContent: 'Hello, {{props.name}}!',
-      className: '{{props.className}}',
+      text: 'Hello, {{props.name}}!',
+      classNames: '{{props.className}}',
     },
   },
 ];
@@ -118,18 +160,33 @@ interface RenderResult {
 Fetches a component from the registry.
 
 ```typescript
-const { data, fromCache } = await fetchComponent('component-id', {
-  version: 'latest',        // Version specifier
-  cacheStrategy: 'memory',  // 'memory' | 'localStorage' | 'none'
-  forceRefresh: false,      // Bypass cache
-  timeout: 30000,           // Request timeout in ms
+const { data, fromCache, version } = await fetchComponent('component-id', {
+  version: 'latest',           // Version specifier (default: 'latest')
+  cacheStrategy: 'localStorage', // 'localStorage' | 'memory' | 'none' (default: 'localStorage')
+  forceRefresh: false,         // Bypass cache (default: false)
   retryConfig: {
-    maxRetries: 3,
-    retryDelay: 1000,
+    maxRetries: 3,             // Number of retry attempts (default: 3)
+    initialDelay: 1000,        // Initial retry delay in ms (default: 1000)
+    maxDelay: 10000,           // Maximum retry delay in ms (default: 10000)
+    backoffMultiplier: 2,      // Exponential backoff multiplier (default: 2)
   },
 });
 ```
 
+### setRegistryUrl(url)
+
+Configure a custom registry URL.
+
+```typescript
+import { setRegistryUrl, DEFAULT_REGISTRY_URL } from '@servlyadmin/runtime-core';
+
+// Use custom registry
+setRegistryUrl('https://your-api.com/v1/views/registry');
+
+// Reset to default
+setRegistryUrl(DEFAULT_REGISTRY_URL);
+```
+
 ### StateManager
 
 Manages component state with subscriptions.
@@ -140,25 +197,17 @@ import { StateManager } from '@servlyadmin/runtime-core';
 const stateManager = new StateManager({ count: 0 });
 
 // Get/set state
-stateManager.setState({ count: 1 });
-stateManager.getValue('count'); // 1
-stateManager.setValue('user.name', 'John');
+stateManager.set('count', 1);
+stateManager.get('count'); // 1
+stateManager.set('user.name', 'John');
 
 // Subscribe to changes
-const unsubscribe = stateManager.subscribe((state) => {
-  console.log('State changed:', state);
+const unsubscribe = stateManager.subscribe((event) => {
+  console.log('State changed:', event.path, event.value);
 });
 
-// Subscribe to specific path
-stateManager.subscribeToPath('count', (value) => {
-  console.log('Count changed:', value);
-});
-
-// Batch updates
-stateManager.batch(() => {
-  stateManager.setValue('a', 1);
-  stateManager.setValue('b', 2);
-}); // Only one notification
+// Cleanup
+stateManager.clear();
 ```
 
 ### EventSystem
@@ -166,59 +215,52 @@ stateManager.batch(() => {
 Handles events with plugin-based actions.
 
 ```typescript
-import { EventSystem } from '@servlyadmin/runtime-core';
+import { EventSystem, getEventSystem } from '@servlyadmin/runtime-core';
 
-const eventSystem = new EventSystem();
+const eventSystem = getEventSystem();
 
 // Register custom plugin
-eventSystem.registerPlugin('my-action', async (config, context) => {
-  console.log('Action executed with:', config);
-});
-
-// Create event handler
-const handler = eventSystem.createHandler([
-  { key: 'prevent-default', config: {} },
-  { key: 'set-state', config: { path: 'clicked', value: true } },
-  { key: 'my-action', config: { message: 'Button clicked!' } },
-]);
-
-// Use with element
-button.addEventListener('click', (e) => {
-  handler(e, 'button-id', bindingContext);
+eventSystem.registerPlugin('my-action', async (action, context) => {
+  console.log('Action executed with:', action.config);
 });
 ```
 
 #### Built-in Plugins
 
-- `console-log` - Log messages to console
-- `set-state` - Update state values
+- `executeCode` - Execute arbitrary JavaScript code
+- `state-setState` - Update state values
+- `navigateTo` - Navigate to URL
+- `localStorage-set/get/remove` - LocalStorage operations
+- `sessionStorage-set/get` - SessionStorage operations
+- `alert` - Show alert dialog
+- `console-log` - Log to console
+- `clipboard-copy` - Copy text to clipboard
+- `scrollTo` - Scroll to element
+- `focus/blur` - Focus/blur elements
+- `addClass/removeClass/toggleClass` - CSS class manipulation
+- `setAttribute/removeAttribute` - Attribute manipulation
+- `dispatchEvent` - Dispatch custom events
 - `delay` - Add delay between actions
-- `prevent-default` - Call event.preventDefault()
-- `stop-propagation` - Call event.stopPropagation()
 
-### Cache
-
-Component caching with multiple strategies.
+### Cache Management
 
 ```typescript
-import { ComponentCache } from '@servlyadmin/runtime-core';
-
-const cache = new ComponentCache({
-  maxSize: 100,
-  strategy: 'memory', // 'memory' | 'localStorage' | 'none'
-});
+import { 
+  clearAllCaches, 
+  clearMemoryCache, 
+  clearLocalStorageCache,
+  getMemoryCacheSize 
+} from '@servlyadmin/runtime-core';
 
-// Set with TTL
-cache.set('key', data, { ttl: 60000 }); // 1 minute
+// Clear all caches
+clearAllCaches();
 
-// Component-specific methods
-cache.setComponent('comp-id', '1.0.0', componentData);
-cache.getComponent('comp-id', 'latest');
-cache.invalidateComponent('comp-id');
+// Clear specific cache
+clearMemoryCache();
+clearLocalStorageCache();
 
-// Statistics
-const stats = cache.getStats();
-console.log(`Hit rate: ${stats.hitRate * 100}%`);
+// Get cache size
+const size = getMemoryCacheSize();
 ```
 
 ### Bindings
@@ -226,7 +268,7 @@ console.log(`Hit rate: ${stats.hitRate * 100}%`);
 Template resolution utilities.
 
 ```typescript
-import { resolveTemplate, resolveBindings, isTemplate } from '@servlyadmin/runtime-core';
+import { resolveTemplate, hasTemplateSyntax } from '@servlyadmin/runtime-core';
 
 const context = {
   props: { name: 'World', count: 42 },
@@ -237,16 +279,9 @@ const context = {
 // Resolve single template
 resolveTemplate('Hello, {{props.name}}!', context); // "Hello, World!"
 
-// Check if string is a template
-isTemplate('{{props.name}}'); // true
-isTemplate('static text');    // false
-
-// Resolve all bindings in an object
-resolveBindings({
-  title: '{{props.name}}',
-  subtitle: 'Count: {{props.count}}',
-}, context);
-// { title: 'World', subtitle: 'Count: 42' }
+// Check if string has template syntax
+hasTemplateSyntax('{{props.name}}'); // true
+hasTemplateSyntax('static text');    // false
 ```
 
 ## Slots
@@ -257,24 +292,25 @@ Components can define slots for content injection:
 const elements = [
   {
     i: 'card',
-    type: 'div',
-    configuration: { className: 'card' },
-    children: [
-      {
-        i: 'header-slot',
-        type: 'div',
-        configuration: {
-          'data-slot': 'header', // Slot placeholder
-        },
-      },
-      {
-        i: 'content-slot',
-        type: 'div',
-        configuration: {
-          'data-slot': 'default',
-        },
-      },
-    ],
+    componentId: 'container',
+    configuration: { classNames: 'card' },
+    children: ['header-slot', 'content-slot'],
+  },
+  {
+    i: 'header-slot',
+    componentId: 'slot',
+    configuration: {
+      slotName: 'header',
+    },
+    parent: 'card',
+  },
+  {
+    i: 'content-slot',
+    componentId: 'slot',
+    configuration: {
+      slotName: 'default',
+    },
+    parent: 'card',
   },
 ];
 ```
@@ -290,9 +326,12 @@ import type {
   LayoutElement,
   BindingContext,
   RenderResult,
+  RenderOptions,
   ComponentData,
   CacheStrategy,
   RetryConfig,
+  FetchOptions,
+  FetchResult,
 } from '@servlyadmin/runtime-core';
 ```
 

package/dist/chunk-5O72RMSO.js

@@ -0,0 +1,305 @@
+// src/tailwind.ts
+var DEFAULT_TAILWIND_CDN = "https://cdn.tailwindcss.com";
+var TAILWIND_CACHE_KEY = "servly-tailwind-loaded";
+var tailwindInjected = false;
+var tailwindScript = null;
+var foucStyleElement = null;
+var tailwindReadyPromise = null;
+var tailwindReadyResolve = null;
+var FOUC_PREVENTION_CSS = `
+  .servly-component:not(.servly-ready),
+  [data-servly-id]:not(.servly-ready) {
+    visibility: hidden !important;
+  }
+  .servly-fouc-hidden {
+    visibility: hidden !important;
+  }
+`;
+function wasTailwindPreviouslyLoaded() {
+  if (typeof localStorage === "undefined") return false;
+  try {
+    return localStorage.getItem(TAILWIND_CACHE_KEY) === "true";
+  } catch {
+    return false;
+  }
+}
+function markTailwindAsLoaded() {
+  if (typeof localStorage === "undefined") return;
+  try {
+    localStorage.setItem(TAILWIND_CACHE_KEY, "true");
+  } catch {
+  }
+}
+function preloadTailwind(cdnUrl, usePlayCdn) {
+  if (typeof document === "undefined") return;
+  if (document.querySelector("link[data-servly-tailwind-preload]")) return;
+  const url = cdnUrl || DEFAULT_TAILWIND_CDN;
+  const fullUrl = usePlayCdn ? `${url}?plugins=forms,typography,aspect-ratio` : url;
+  const link = document.createElement("link");
+  link.rel = "preload";
+  link.as = "script";
+  link.href = fullUrl;
+  link.setAttribute("data-servly-tailwind-preload", "true");
+  if (document.head.firstChild) {
+    document.head.insertBefore(link, document.head.firstChild);
+  } else {
+    document.head.appendChild(link);
+  }
+  const dnsPrefetch = document.createElement("link");
+  dnsPrefetch.rel = "dns-prefetch";
+  dnsPrefetch.href = "https://cdn.tailwindcss.com";
+  document.head.appendChild(dnsPrefetch);
+}
+function preventFOUC() {
+  if (typeof document === "undefined") return;
+  if (foucStyleElement) return;
+  const wasLoaded = wasTailwindPreviouslyLoaded();
+  foucStyleElement = document.createElement("style");
+  foucStyleElement.id = "servly-fouc-prevention";
+  foucStyleElement.textContent = FOUC_PREVENTION_CSS;
+  if (document.head.firstChild) {
+    document.head.insertBefore(foucStyleElement, document.head.firstChild);
+  } else {
+    document.head.appendChild(foucStyleElement);
+  }
+  if (wasLoaded) {
+    setTimeout(() => {
+      if (window.tailwind) {
+        removeFOUCPrevention();
+      }
+    }, 100);
+  }
+}
+function removeFOUCPrevention() {
+  if (foucStyleElement && foucStyleElement.parentNode) {
+    foucStyleElement.parentNode.removeChild(foucStyleElement);
+    foucStyleElement = null;
+  }
+  if (typeof document !== "undefined") {
+    document.querySelectorAll(".servly-component, [data-servly-id]").forEach((el) => {
+      el.classList.add("servly-ready");
+    });
+  }
+}
+function markElementReady(element) {
+  element.classList.add("servly-ready");
+  element.classList.remove("servly-fouc-hidden");
+}
+function isTailwindReady() {
+  if (typeof window === "undefined") return false;
+  return tailwindInjected && !!window.tailwind;
+}
+function waitForTailwind() {
+  if (isTailwindReady()) {
+    return Promise.resolve();
+  }
+  if (tailwindReadyPromise) {
+    return tailwindReadyPromise;
+  }
+  tailwindReadyPromise = new Promise((resolve) => {
+    tailwindReadyResolve = resolve;
+  });
+  return tailwindReadyPromise;
+}
+function injectTailwind(config = {}) {
+  return new Promise((resolve, reject) => {
+    if (tailwindInjected && tailwindScript) {
+      resolve();
+      return;
+    }
+    if (typeof document === "undefined") {
+      resolve();
+      return;
+    }
+    const {
+      cdnUrl = DEFAULT_TAILWIND_CDN,
+      config: tailwindConfig,
+      plugins = [],
+      usePlayCdn = false,
+      onReady,
+      onError,
+      preventFOUC: shouldPreventFOUC = true,
+      enablePreload = true
+    } = config;
+    if (shouldPreventFOUC) {
+      preventFOUC();
+    }
+    if (enablePreload) {
+      preloadTailwind(cdnUrl, usePlayCdn);
+    }
+    if (window.tailwind) {
+      tailwindInjected = true;
+      markTailwindAsLoaded();
+      if (shouldPreventFOUC) {
+        removeFOUCPrevention();
+      }
+      if (tailwindReadyResolve) {
+        tailwindReadyResolve();
+        tailwindReadyResolve = null;
+      }
+      config.onReady?.();
+      resolve();
+      return;
+    }
+    const script = document.createElement("script");
+    script.src = usePlayCdn ? `${cdnUrl}?plugins=forms,typography,aspect-ratio` : cdnUrl;
+    script.async = true;
+    script.crossOrigin = "anonymous";
+    script.onload = () => {
+      tailwindInjected = true;
+      tailwindScript = script;
+      markTailwindAsLoaded();
+      if (tailwindConfig && window.tailwind) {
+        window.tailwind.config = tailwindConfig;
+      }
+      const delay = wasTailwindPreviouslyLoaded() ? 10 : 50;
+      setTimeout(() => {
+        if (shouldPreventFOUC) {
+          removeFOUCPrevention();
+        }
+        if (tailwindReadyResolve) {
+          tailwindReadyResolve();
+          tailwindReadyResolve = null;
+        }
+        onReady?.();
+        resolve();
+      }, delay);
+    };
+    script.onerror = (event) => {
+      const error = new Error(`Failed to load Tailwind CSS from ${cdnUrl}`);
+      if (shouldPreventFOUC) {
+        removeFOUCPrevention();
+      }
+      if (tailwindReadyResolve) {
+        tailwindReadyResolve();
+        tailwindReadyResolve = null;
+      }
+      onError?.(error);
+      reject(error);
+    };
+    document.head.appendChild(script);
+  });
+}
+function removeTailwind() {
+  if (tailwindScript && tailwindScript.parentNode) {
+    tailwindScript.parentNode.removeChild(tailwindScript);
+    tailwindScript = null;
+    tailwindInjected = false;
+    tailwindReadyPromise = null;
+    tailwindReadyResolve = null;
+    delete window.tailwind;
+  }
+}
+function isTailwindLoaded() {
+  return tailwindInjected || !!window.tailwind;
+}
+function getTailwind() {
+  return window.tailwind;
+}
+function updateTailwindConfig(config) {
+  if (window.tailwind) {
+    window.tailwind.config = {
+      ...window.tailwind.config,
+      ...config
+    };
+  }
+}
+function addCustomStyles(css, id) {
+  if (typeof document === "undefined") {
+    throw new Error("addCustomStyles can only be used in browser environment");
+  }
+  const styleId = id || `servly-custom-styles-${Date.now()}`;
+  let existingStyle = document.getElementById(styleId);
+  if (existingStyle) {
+    existingStyle.textContent = css;
+    return existingStyle;
+  }
+  const style = document.createElement("style");
+  style.id = styleId;
+  style.textContent = css;
+  document.head.appendChild(style);
+  return style;
+}
+function removeCustomStyles(id) {
+  if (typeof document === "undefined") return;
+  const style = document.getElementById(id);
+  if (style && style.parentNode) {
+    style.parentNode.removeChild(style);
+  }
+}
+var DEFAULT_SERVLY_TAILWIND_CONFIG = {
+  theme: {
+    extend: {
+      // Add any Servly-specific theme extensions here
+    }
+  },
+  // Safelist common dynamic classes
+  safelist: [
+    // Spacing
+    { pattern: /^(p|m|gap)-/ },
+    // Sizing
+    { pattern: /^(w|h|min-w|min-h|max-w|max-h)-/ },
+    // Flexbox
+    { pattern: /^(flex|justify|items|self)-/ },
+    // Grid
+    { pattern: /^(grid|col|row)-/ },
+    // Colors
+    { pattern: /^(bg|text|border|ring)-/ },
+    // Typography
+    { pattern: /^(font|text|leading|tracking)-/ },
+    // Borders
+    { pattern: /^(rounded|border)-/ },
+    // Effects
+    { pattern: /^(shadow|opacity|blur)-/ },
+    // Transforms
+    { pattern: /^(scale|rotate|translate|skew)-/ },
+    // Transitions
+    { pattern: /^(transition|duration|ease|delay)-/ }
+  ]
+};
+async function initServlyTailwind(customConfig) {
+  const config = customConfig ? { ...DEFAULT_SERVLY_TAILWIND_CONFIG, ...customConfig } : DEFAULT_SERVLY_TAILWIND_CONFIG;
+  await injectTailwind({
+    config,
+    usePlayCdn: true
+  });
+}
+var injectTailwindStyles = initServlyTailwind;
+var tailwind_default = {
+  injectTailwind,
+  injectTailwindStyles,
+  removeTailwind,
+  isTailwindLoaded,
+  isTailwindReady,
+  waitForTailwind,
+  getTailwind,
+  updateTailwindConfig,
+  addCustomStyles,
+  removeCustomStyles,
+  initServlyTailwind,
+  preventFOUC,
+  removeFOUCPrevention,
+  markElementReady,
+  preloadTailwind,
+  DEFAULT_SERVLY_TAILWIND_CONFIG
+};
+
+export {
+  preloadTailwind,
+  preventFOUC,
+  removeFOUCPrevention,
+  markElementReady,
+  isTailwindReady,
+  waitForTailwind,
+  injectTailwind,
+  removeTailwind,
+  isTailwindLoaded,
+  getTailwind,
+  updateTailwindConfig,
+  addCustomStyles,
+  removeCustomStyles,
+  DEFAULT_SERVLY_TAILWIND_CONFIG,
+  initServlyTailwind,
+  injectTailwindStyles,
+  tailwind_default
+};