npm package: @servlyadmin/runtime-vue
Description: Vue wrapper for Servly runtime renderer
Author: Servly
Latest version: 0.1.45

# @servlyadmin/runtime-vue

Vue 3 wrapper for Servly runtime renderer. Render Servly components in your Vue applications with full slot support, state management, and reactive updates.

## Installation

```bash
npm install @servlyadmin/runtime-vue
# or
yarn add @servlyadmin/runtime-vue
# or
pnpm add @servlyadmin/runtime-vue
```

## Requirements

- Vue 3.0.0 or higher
- @servlyadmin/runtime-core (installed automatically)

## Quick Start

```vue
<template>
  <!-- That's it! Components are fetched from Servly's registry automatically -->
  <ServlyComponent
    id="my-component-id"
    :props="{ title: 'Hello World' }"
  />
</template>

<script setup lang="ts">
import { ServlyComponent } from '@servlyadmin/runtime-vue';
</script>
```

## Registry & Caching

### Default Registry

Components are fetched from Servly's production registry by default:
- **URL**: `https://core-api.servly.app/v1/views/registry`

To use a custom registry:

```typescript
import { setRegistryUrl } from '@servlyadmin/runtime-vue';

setRegistryUrl('https://your-api.com/v1/views/registry');
```

### Cache Strategies

The runtime supports three caching strategies:

| Strategy | Description | Persistence | Best For |
|----------|-------------|-------------|----------|
| `localStorage` | Persists across browser sessions | Yes | **Production (default)** |
| `memory` | In-memory cache, cleared on refresh | No | Development, SSR |
| `none` | No caching, always fetches fresh | No | Testing, debugging |

```vue
<template>
  <!-- Default: localStorage caching -->
  <ServlyComponent id="my-component" />

  <!-- Explicit cache strategy -->
  <ServlyComponent id="my-component" cache-strategy="memory" />

  <!-- No caching -->
  <ServlyComponent id="my-component" cache-strategy="none" />
</template>
```

## API Reference

### ServlyComponent Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `id` | `string` | **required** | Component ID from the registry |
| `version` | `string` | `'latest'` | Version specifier (exact, range, or "latest") |
| `props` | `object` | `{}` | Props to pass to the component |
| `cacheStrategy` | `'localStorage' \| 'memory' \| 'none'` | `'localStorage'` | Caching strategy |
| `retryConfig` | `object` | `undefined` | Retry configuration for failed fetches |
| `eventHandlers` | `object` | `undefined` | Event handlers keyed by element ID |
| `showSkeleton` | `boolean` | `true` | Show loading skeleton |
| `enableStateManager` | `boolean` | `false` | Enable built-in state management |
| `initialState` | `object` | `undefined` | Initial state for state manager |

### Events

| Event | Payload | Description |
|-------|---------|-------------|
| `load` | `ComponentData` | Emitted when component loads successfully |
| `error` | `Error` | Emitted when component fails to load |
| `stateChange` | `StateChangeEvent` | Emitted when state changes (if enabled) |
| `ready` | `void` | Emitted when component is fully rendered |

### Slots

```vue
<template>
  <ServlyComponent id="my-component">
    <!-- Custom loading state -->
    <template #fallback>
      <div>Loading...</div>
    </template>
    
    <!-- Custom error state -->
    <template #error="{ error, retry }">
      <div>
        <p>Error: {{ error.message }}</p>
        <button @click="retry">Retry</button>
      </div>
    </template>
    
    <!-- Named slots for component content -->
    <template #header>
      <h1>Custom Header</h1>
    </template>
    
    <template #footer>
      <p>Custom Footer</p>
    </template>
  </ServlyComponent>
</template>
```

## Advanced Usage

### With State Management

```vue
<template>
  <ServlyComponent
    id="counter-component"
    :props="{ count }"
    enable-state-manager
    :initial-state="{ count: 0 }"
    @state-change="onStateChange"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { ServlyComponent } from '@servlyadmin/runtime-vue';

const count = ref(0);

const onStateChange = (event) => {
  if (event.key === 'count') {
    count.value = event.value;
  }
};
</script>
```

### With Event Handlers

```vue
<template>
  <ServlyComponent
    id="form-component"
    :event-handlers="handlers"
  />
</template>

<script setup lang="ts">
import { ServlyComponent } from '@servlyadmin/runtime-vue';

const handlers = {
  'submit-btn': {
    click: (event) => {
      console.log('Button clicked!', event);
    },
  },
  'email-input': {
    change: (event) => {
      console.log('Email changed:', event.target.value);
    },
  },
};
</script>
```

### Accessing Component Instance

```vue
<template>
  <ServlyComponent
    ref="servlyRef"
    id="my-component"
  />
  <button @click="reload">Reload</button>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { ServlyComponent } from '@servlyadmin/runtime-vue';

const servlyRef = ref();

const reload = () => {
  servlyRef.value?.reload();
};

// Other exposed methods:
// servlyRef.value?.getSlotElement('header')
// servlyRef.value?.getSlotNames()
// servlyRef.value?.getStateManager()
// servlyRef.value?.update({ newProp: 'value' })
</script>
```

### Version Specifiers

```vue
<template>
  <!-- Exact version -->
  <ServlyComponent id="my-component" version="1.2.3" />
  
  <!-- Caret range (compatible with) -->
  <ServlyComponent id="my-component" version="^1.0.0" />
  
  <!-- Tilde range (approximately) -->
  <ServlyComponent id="my-component" version="~1.2.0" />
  
  <!-- Latest version (default) -->
  <ServlyComponent id="my-component" />
</template>
```

## TypeScript Support

Full TypeScript support is included:

```typescript
import type {
  ServlyComponentProps,
  BindingContext,
  ComponentData,
  StateChangeEvent,
} from '@servlyadmin/runtime-vue';
```

## Re-exported Utilities

For convenience, common utilities are re-exported:

```typescript
import {
  // Fetching
  fetchComponent,
  prefetchComponents,
  setRegistryUrl,
  DEFAULT_REGISTRY_URL,
  
  // Caching
  invalidateCache,
  clearAllCaches,
  
  // State management
  StateManager,
  
  // Event system
  EventSystem,
  getEventSystem,
} from '@servlyadmin/runtime-vue';
```

## License

MIT