@servlyadmin/runtime-core 0.1.7 → 0.1.9

package/README.md

@@ -0,0 +1,308 @@
+# @servlyadmin/runtime-core
+
+Framework-agnostic core renderer for Servly components. This package provides the foundation for rendering Servly components in any JavaScript environment.
+
+## Installation
+
+```bash
+npm install @servlyadmin/runtime-core
+# or
+yarn add @servlyadmin/runtime-core
+# or
+pnpm add @servlyadmin/runtime-core
+```
+
+## Quick Start
+
+```typescript
+import { render, fetchComponent } from '@servlyadmin/runtime-core';
+
+// Fetch a component from the registry
+const { data } = await fetchComponent('my-component', { version: 'latest' });
+
+// Render to a container
+const result = render({
+  container: document.getElementById('app'),
+  elements: data.layout,
+  context: {
+    props: { title: 'Hello World' },
+    state: {},
+    context: {},
+  },
+});
+
+// Update props
+result.update({
+  props: { title: 'Updated Title' },
+  state: {},
+  context: {},
+});
+
+// Cleanup
+result.destroy();
+```
+
+## Core Concepts
+
+### Layout Elements
+
+Components are defined as a tree of layout elements:
+
+```typescript
+interface LayoutElement {
+  i: string;           // Unique identifier
+  type: string;        // HTML tag or component type
+  configuration?: {    // Element configuration
+    className?: string;
+    style?: Record<string, any>;
+    textContent?: string;
+    // ... other attributes
+  };
+  children?: LayoutElement[];  // Nested elements
+}
+```
+
+### Binding Context
+
+Data is passed to components through a binding context:
+
+```typescript
+interface BindingContext {
+  props: Record<string, any>;   // Component props
+  state: Record<string, any>;   // Component state
+  context: Record<string, any>; // Additional context
+}
+```
+
+### Template Bindings
+
+Use `{{path}}` syntax to bind data:
+
+```typescript
+const elements = [
+  {
+    i: 'greeting',
+    type: 'h1',
+    configuration: {
+      textContent: 'Hello, {{props.name}}!',
+      className: '{{props.className}}',
+    },
+  },
+];
+```
+
+## API Reference
+
+### render(options)
+
+Renders elements to a container.
+
+```typescript
+const result = render({
+  container: HTMLElement,
+  elements: LayoutElement[],
+  context: BindingContext,
+  eventHandlers?: Record<string, Record<string, (e: Event) => void>>,
+});
+
+// Returns
+interface RenderResult {
+  update(context: BindingContext): void;
+  destroy(): void;
+  getElement(id: string): HTMLElement | null;
+}
+```
+
+### fetchComponent(id, options?)
+
+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
+  retryConfig: {
+    maxRetries: 3,
+    retryDelay: 1000,
+  },
+});
+```
+
+### StateManager
+
+Manages component state with subscriptions.
+
+```typescript
+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');
+
+// Subscribe to changes
+const unsubscribe = stateManager.subscribe((state) => {
+  console.log('State changed:', state);
+});
+
+// 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
+```
+
+### EventSystem
+
+Handles events with plugin-based actions.
+
+```typescript
+import { EventSystem } from '@servlyadmin/runtime-core';
+
+const eventSystem = new EventSystem();
+
+// 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);
+});
+```
+
+#### Built-in Plugins
+
+- `console-log` - Log messages to console
+- `set-state` - Update state values
+- `delay` - Add delay between actions
+- `prevent-default` - Call event.preventDefault()
+- `stop-propagation` - Call event.stopPropagation()
+
+### Cache
+
+Component caching with multiple strategies.
+
+```typescript
+import { ComponentCache } from '@servlyadmin/runtime-core';
+
+const cache = new ComponentCache({
+  maxSize: 100,
+  strategy: 'memory', // 'memory' | 'localStorage' | 'none'
+});
+
+// Set with TTL
+cache.set('key', data, { ttl: 60000 }); // 1 minute
+
+// Component-specific methods
+cache.setComponent('comp-id', '1.0.0', componentData);
+cache.getComponent('comp-id', 'latest');
+cache.invalidateComponent('comp-id');
+
+// Statistics
+const stats = cache.getStats();
+console.log(`Hit rate: ${stats.hitRate * 100}%`);
+```
+
+### Bindings
+
+Template resolution utilities.
+
+```typescript
+import { resolveTemplate, resolveBindings, isTemplate } from '@servlyadmin/runtime-core';
+
+const context = {
+  props: { name: 'World', count: 42 },
+  state: {},
+  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' }
+```
+
+## Slots
+
+Components can define slots for content injection:
+
+```typescript
+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',
+        },
+      },
+    ],
+  },
+];
+```
+
+Framework wrappers handle slot content injection automatically.
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  LayoutElement,
+  BindingContext,
+  RenderResult,
+  ComponentData,
+  CacheStrategy,
+  RetryConfig,
+} from '@servlyadmin/runtime-core';
+```
+
+## Browser Support
+
+- Chrome 80+
+- Firefox 75+
+- Safari 13+
+- Edge 80+
+
+## License
+
+MIT

package/dist/{chunk-CIUQK4GA.js → chunk-EQFZFPI7.mjs}

@@ -1,4 +1,4 @@
-// src/registry.ts
+// packages/runtime-core/src/registry.ts
 function createRegistry() {
   const components = /* @__PURE__ */ new Map();
   return {

package/dist/chunk-RKUT63EF.mjs

@@ -0,0 +1,154 @@
+// packages/runtime-core/src/tailwind.ts
+var DEFAULT_TAILWIND_CDN = "https://cdn.tailwindcss.com";
+var tailwindInjected = false;
+var tailwindScript = null;
+function injectTailwind(config = {}) {
+  return new Promise((resolve, reject) => {
+    if (tailwindInjected && tailwindScript) {
+      resolve();
+      return;
+    }
+    if (typeof document === "undefined") {
+      resolve();
+      return;
+    }
+    if (window.tailwind) {
+      tailwindInjected = true;
+      config.onReady?.();
+      resolve();
+      return;
+    }
+    const {
+      cdnUrl = DEFAULT_TAILWIND_CDN,
+      config: tailwindConfig,
+      plugins = [],
+      usePlayCdn = false,
+      onReady,
+      onError
+    } = config;
+    const script = document.createElement("script");
+    script.src = usePlayCdn ? `${cdnUrl}?plugins=forms,typography,aspect-ratio` : cdnUrl;
+    script.async = true;
+    script.onload = () => {
+      tailwindInjected = true;
+      tailwindScript = script;
+      if (tailwindConfig && window.tailwind) {
+        window.tailwind.config = tailwindConfig;
+      }
+      onReady?.();
+      resolve();
+    };
+    script.onerror = (event) => {
+      const error = new Error(`Failed to load Tailwind CSS from ${cdnUrl}`);
+      onError?.(error);
+      reject(error);
+    };
+    document.head.appendChild(script);
+  });
+}
+function removeTailwind() {
+  if (tailwindScript && tailwindScript.parentNode) {
+    tailwindScript.parentNode.removeChild(tailwindScript);
+    tailwindScript = null;
+    tailwindInjected = false;
+    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 tailwind_default = {
+  injectTailwind,
+  removeTailwind,
+  isTailwindLoaded,
+  getTailwind,
+  updateTailwindConfig,
+  addCustomStyles,
+  removeCustomStyles,
+  initServlyTailwind,
+  DEFAULT_SERVLY_TAILWIND_CONFIG
+};
+
+export {
+  injectTailwind,
+  removeTailwind,
+  isTailwindLoaded,
+  getTailwind,
+  updateTailwindConfig,
+  addCustomStyles,
+  removeCustomStyles,
+  DEFAULT_SERVLY_TAILWIND_CONFIG,
+  initServlyTailwind,
+  tailwind_default
+};