@servlyadmin/runtime-core 0.1.44 → 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/{chunk-TXHGJYYM.js → chunk-GN6KAMNI.js}

@@ -33,6 +33,7 @@ function markTailwindAsLoaded() {
 function preloadTailwind(cdnUrl, usePlayCdn) {
   if (typeof document === "undefined") return;
   if (document.querySelector("link[data-servly-tailwind-preload]")) return;
+  if (document.querySelector('script[src*="tailwindcss.com"]')) return;
   const url = cdnUrl || DEFAULT_TAILWIND_CDN;
   const fullUrl = usePlayCdn ? `${url}?plugins=forms,typography,aspect-ratio` : url;
   const link = document.createElement("link");
@@ -40,15 +41,18 @@ function preloadTailwind(cdnUrl, usePlayCdn) {
   link.as = "script";
   link.href = fullUrl;
   link.setAttribute("data-servly-tailwind-preload", "true");
+  link.setAttribute("crossorigin", "anonymous");
   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);
+  if (!document.querySelector('link[rel="dns-prefetch"][href*="tailwindcss.com"]')) {
+    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;
@@ -135,7 +139,6 @@ function injectTailwind(config = {}) {
     const {
       cdnUrl = DEFAULT_TAILWIND_CDN,
       config: tailwindConfig,
-      plugins = [],
       usePlayCdn = false,
       onReady,
       onError,

package/dist/index.cjs

@@ -61,6 +61,7 @@ function markTailwindAsLoaded() {
 function preloadTailwind(cdnUrl, usePlayCdn) {
   if (typeof document === "undefined") return;
   if (document.querySelector("link[data-servly-tailwind-preload]")) return;
+  if (document.querySelector('script[src*="tailwindcss.com"]')) return;
   const url = cdnUrl || DEFAULT_TAILWIND_CDN;
   const fullUrl = usePlayCdn ? `${url}?plugins=forms,typography,aspect-ratio` : url;
   const link = document.createElement("link");
@@ -68,15 +69,18 @@ function preloadTailwind(cdnUrl, usePlayCdn) {
   link.as = "script";
   link.href = fullUrl;
   link.setAttribute("data-servly-tailwind-preload", "true");
+  link.setAttribute("crossorigin", "anonymous");
   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);
+  if (!document.querySelector('link[rel="dns-prefetch"][href*="tailwindcss.com"]')) {
+    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;
@@ -163,7 +167,6 @@ function injectTailwind(config = {}) {
     const {
       cdnUrl = DEFAULT_TAILWIND_CDN,
       config: tailwindConfig,
-      plugins = [],
       usePlayCdn = false,
       onReady,
       onError,
@@ -695,6 +698,7 @@ __export(index_exports, {
   camelToKebab: () => camelToKebab,
   clearAllCaches: () => clearAllCaches,
   clearIconCache: () => clearIconCache,
+  clearIconStorageCache: () => clearIconStorageCache,
   clearLocalStorageCache: () => clearLocalStorageCache,
   clearMemoryCache: () => clearMemoryCache,
   clearStyles: () => clearStyles,
@@ -769,6 +773,8 @@ __export(index_exports, {
   loadFont: () => loadFont,
   loadFonts: () => loadFonts,
   markElementReady: () => markElementReady,
+  mount: () => mount,
+  mountData: () => mountData,
   navigateTo: () => navigateTo,
   parseVersion: () => parseVersion,
   prefetchComponents: () => prefetchComponents,
@@ -3127,6 +3133,58 @@ function resetOverrideSystem() {
 
 // src/icons.ts
 var cdnEnabled = true;
+var ICON_CACHE_KEY = "servly-icon-cache";
+var ICON_CACHE_VERSION = "1";
+var localStorageLoaded = false;
+function loadIconCacheFromStorage() {
+  if (localStorageLoaded) return;
+  localStorageLoaded = true;
+  if (typeof localStorage === "undefined") return;
+  try {
+    const cached = localStorage.getItem(ICON_CACHE_KEY);
+    if (!cached) return;
+    const parsed = JSON.parse(cached);
+    if (parsed.version !== ICON_CACHE_VERSION) {
+      localStorage.removeItem(ICON_CACHE_KEY);
+      return;
+    }
+    for (const [key, data] of Object.entries(parsed.icons)) {
+      if (!iconCache.has(key) && !registeredIcons.has(key)) {
+        iconCache.set(key, data);
+      }
+    }
+  } catch {
+  }
+}
+function saveIconToStorage(key, data) {
+  if (typeof localStorage === "undefined") return;
+  try {
+    const cached = localStorage.getItem(ICON_CACHE_KEY);
+    let cacheData;
+    if (cached) {
+      cacheData = JSON.parse(cached);
+      if (cacheData.version !== ICON_CACHE_VERSION) {
+        cacheData = { version: ICON_CACHE_VERSION, icons: {} };
+      }
+    } else {
+      cacheData = { version: ICON_CACHE_VERSION, icons: {} };
+    }
+    cacheData.icons[key] = data;
+    const keys = Object.keys(cacheData.icons);
+    if (keys.length > 500) {
+      keys.slice(0, 100).forEach((k) => delete cacheData.icons[k]);
+    }
+    localStorage.setItem(ICON_CACHE_KEY, JSON.stringify(cacheData));
+  } catch {
+  }
+}
+function clearIconStorageCache() {
+  if (typeof localStorage === "undefined") return;
+  try {
+    localStorage.removeItem(ICON_CACHE_KEY);
+  } catch {
+  }
+}
 function setIconCdnEnabled(enabled) {
   cdnEnabled = enabled;
 }
@@ -3299,6 +3357,7 @@ function parseSvgResponse(svgText) {
 }
 async function getIconData(icon) {
   const key = `${icon.set}:${icon.name}`;
+  loadIconCacheFromStorage();
   if (iconCache.has(key)) {
     return iconCache.get(key);
   }
@@ -3314,11 +3373,13 @@ async function getIconData(icon) {
   pendingFetches.delete(key);
   if (data) {
     iconCache.set(key, data);
+    saveIconToStorage(key, data);
   }
   return data;
 }
 function getIconDataSync(icon) {
   const key = `${icon.set}:${icon.name}`;
+  loadIconCacheFromStorage();
   return iconCache.get(key) || null;
 }
 function createIconSVG(icon, data, size = 24, color = "currentColor") {
@@ -3418,12 +3479,15 @@ function renderIcon(container, icon, size = 24, color = "currentColor") {
 async function preloadIcons(icons) {
   await Promise.all(icons.map((icon) => getIconData(icon)));
 }
-function clearIconCache() {
+function clearIconCache(clearStorage = false) {
   iconCache.clear();
   pendingFetches.clear();
   registeredIcons.forEach((data, key) => {
     iconCache.set(key, data);
   });
+  if (clearStorage) {
+    clearIconStorageCache();
+  }
 }
 function isIconSetSupported(set) {
   return set in ICONIFY_COLLECTIONS;
@@ -4483,10 +4547,9 @@ function renderInShadow(options) {
     shadowRoot.insertBefore(styleEl, innerContainer);
   }
   if (shouldInjectTailwind) {
-    const tailwindLink = document.createElement("link");
-    tailwindLink.rel = "stylesheet";
-    tailwindLink.href = "https://cdn.tailwindcss.com";
-    shadowRoot.insertBefore(tailwindLink, innerContainer);
+    const tailwindScript2 = document.createElement("script");
+    tailwindScript2.src = "https://cdn.tailwindcss.com";
+    shadowRoot.insertBefore(tailwindScript2, innerContainer);
   }
   const result = render({
     ...renderOptions,
@@ -5221,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+)$/);
@@ -5618,6 +5784,7 @@ init_tailwind();
   camelToKebab,
   clearAllCaches,
   clearIconCache,
+  clearIconStorageCache,
   clearLocalStorageCache,
   clearMemoryCache,
   clearStyles,
@@ -5692,6 +5859,8 @@ init_tailwind();
   loadFont,
   loadFonts,
   markElementReady,
+  mount,
+  mountData,
   navigateTo,
   parseVersion,
   prefetchComponents,

package/dist/index.js

@@ -17,7 +17,7 @@ import {
   scheduleRefresh,
   updateTailwindConfig,
   waitForTailwind
-} from "./chunk-TXHGJYYM.js";
+} from "./chunk-GN6KAMNI.js";
 import {
   buildRegistryFromBundle,
   collectAllDependencies,
@@ -2332,6 +2332,58 @@ function resetOverrideSystem() {
 
 // src/icons.ts
 var cdnEnabled = true;
+var ICON_CACHE_KEY = "servly-icon-cache";
+var ICON_CACHE_VERSION = "1";
+var localStorageLoaded = false;
+function loadIconCacheFromStorage() {
+  if (localStorageLoaded) return;
+  localStorageLoaded = true;
+  if (typeof localStorage === "undefined") return;
+  try {
+    const cached = localStorage.getItem(ICON_CACHE_KEY);
+    if (!cached) return;
+    const parsed = JSON.parse(cached);
+    if (parsed.version !== ICON_CACHE_VERSION) {
+      localStorage.removeItem(ICON_CACHE_KEY);
+      return;
+    }
+    for (const [key, data] of Object.entries(parsed.icons)) {
+      if (!iconCache.has(key) && !registeredIcons.has(key)) {
+        iconCache.set(key, data);
+      }
+    }
+  } catch {
+  }
+}
+function saveIconToStorage(key, data) {
+  if (typeof localStorage === "undefined") return;
+  try {
+    const cached = localStorage.getItem(ICON_CACHE_KEY);
+    let cacheData;
+    if (cached) {
+      cacheData = JSON.parse(cached);
+      if (cacheData.version !== ICON_CACHE_VERSION) {
+        cacheData = { version: ICON_CACHE_VERSION, icons: {} };
+      }
+    } else {
+      cacheData = { version: ICON_CACHE_VERSION, icons: {} };
+    }
+    cacheData.icons[key] = data;
+    const keys = Object.keys(cacheData.icons);
+    if (keys.length > 500) {
+      keys.slice(0, 100).forEach((k) => delete cacheData.icons[k]);
+    }
+    localStorage.setItem(ICON_CACHE_KEY, JSON.stringify(cacheData));
+  } catch {
+  }
+}
+function clearIconStorageCache() {
+  if (typeof localStorage === "undefined") return;
+  try {
+    localStorage.removeItem(ICON_CACHE_KEY);
+  } catch {
+  }
+}
 function setIconCdnEnabled(enabled) {
   cdnEnabled = enabled;
 }
@@ -2504,6 +2556,7 @@ function parseSvgResponse(svgText) {
 }
 async function getIconData(icon) {
   const key = `${icon.set}:${icon.name}`;
+  loadIconCacheFromStorage();
   if (iconCache.has(key)) {
     return iconCache.get(key);
   }
@@ -2519,11 +2572,13 @@ async function getIconData(icon) {
   pendingFetches.delete(key);
   if (data) {
     iconCache.set(key, data);
+    saveIconToStorage(key, data);
   }
   return data;
 }
 function getIconDataSync(icon) {
   const key = `${icon.set}:${icon.name}`;
+  loadIconCacheFromStorage();
   return iconCache.get(key) || null;
 }
 function createIconSVG(icon, data, size = 24, color = "currentColor") {
@@ -2623,12 +2678,15 @@ function renderIcon(container, icon, size = 24, color = "currentColor") {
 async function preloadIcons(icons) {
   await Promise.all(icons.map((icon) => getIconData(icon)));
 }
-function clearIconCache() {
+function clearIconCache(clearStorage = false) {
   iconCache.clear();
   pendingFetches.clear();
   registeredIcons.forEach((data, key) => {
     iconCache.set(key, data);
   });
+  if (clearStorage) {
+    clearIconStorageCache();
+  }
 }
 function isIconSetSupported(set) {
   return set in ICONIFY_COLLECTIONS;
@@ -3685,10 +3743,9 @@ function renderInShadow(options) {
     shadowRoot.insertBefore(styleEl, innerContainer);
   }
   if (shouldInjectTailwind) {
-    const tailwindLink = document.createElement("link");
-    tailwindLink.rel = "stylesheet";
-    tailwindLink.href = "https://cdn.tailwindcss.com";
-    shadowRoot.insertBefore(tailwindLink, innerContainer);
+    const tailwindScript = document.createElement("script");
+    tailwindScript.src = "https://cdn.tailwindcss.com";
+    shadowRoot.insertBefore(tailwindScript, innerContainer);
   }
   const result = render({
     ...renderOptions,
@@ -3719,7 +3776,7 @@ async function createServlyRenderer(options) {
     container = containerOption;
   }
   if (shouldInjectTailwind) {
-    const { initServlyTailwind: initServlyTailwind2 } = await import("./tailwind-GU53TXCZ.js");
+    const { initServlyTailwind: initServlyTailwind2 } = await import("./tailwind-MYAEYQPY.js");
     await initServlyTailwind2(tailwindConfig);
   }
   const activeRenders = [];
@@ -4422,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+)$/);
@@ -4814,6 +4974,7 @@ export {
   camelToKebab,
   clearAllCaches,
   clearIconCache,
+  clearIconStorageCache,
   clearLocalStorageCache,
   clearMemoryCache,
   clearStyles,
@@ -4888,6 +5049,8 @@ export {
   loadFont,
   loadFonts,
   markElementReady,
+  mount,
+  mountData,
   navigateTo,
   parseVersion,
   prefetchComponents,

package/dist/{tailwind-GU53TXCZ.js → tailwind-MYAEYQPY.js}

@@ -18,7 +18,7 @@ import {
   tailwind_default,
   updateTailwindConfig,
   waitForTailwind
-} from "./chunk-TXHGJYYM.js";
+} from "./chunk-GN6KAMNI.js";
 export {
   DEFAULT_SERVLY_TAILWIND_CONFIG,
   addCustomStyles,