# Despia Version Guard

A framework-agnostic solution for conditionally rendering UI elements based on the Despia Native SDK runtime version (`window.bundleNumber`). Supports **React**, **Vue**, **Angular**, **Svelte**, and **Vanilla JS/Web Components**. This allows you to build conditional UI for major version shifts while remaining store-compliant and managing versioning for dynamic Despia apps.

## Installation

```bash
npm install despia-version-guard
```

## Framework Support

- **React** (16.8+)
- **Vue 3**
- **Angular** (Standalone components)
- **Svelte**
- **Vanilla JS / Web Components**

## Usage

### React

```tsx
import { VersionGuard } from 'despia-version-guard';

// Only show this feature if version is 21.0.3 or higher
<VersionGuard min_version="21.0.3">
  <NewFeatureComponent />
</VersionGuard>

// Only show this feature if version is 21.0.3 or lower
<VersionGuard max_version="21.0.3">
  <LegacyFeatureComponent />
</VersionGuard>

// Only show this feature if version is between 21.0.0 and 21.0.3 (inclusive)
<VersionGuard min_version="21.0.0" max_version="21.0.3">
  <VersionSpecificFeature />
</VersionGuard>
```

### Vue 3

```vue
<template>
  <VersionGuard :min-version="'21.0.3'">
    <NewFeatureComponent />
  </VersionGuard>

  <VersionGuard :max-version="'21.0.3'">
    <LegacyFeatureComponent />
  </VersionGuard>

  <VersionGuard :min-version="'21.0.0'" :max-version="'21.0.3'">
    <VersionSpecificFeature />
  </VersionGuard>
</template>

<script setup lang="ts">
import { VersionGuard } from 'despia-version-guard/vue';
</script>
```

### Angular

```typescript
import { Component } from '@angular/core';
import { VersionGuardComponent } from 'despia-version-guard/angular';

@Component({
  selector: 'app-feature',
  standalone: true,
  imports: [VersionGuardComponent],
  template: `
    <version-guard [minVersion]="'21.0.3'">
      <new-feature-component />
    </version-guard>

    <version-guard [maxVersion]="'21.0.3'">
      <legacy-feature-component />
    </version-guard>

    <version-guard [minVersion]="'21.0.0'" [maxVersion]="'21.0.3'">
      <version-specific-feature />
    </version-guard>
  `
})
export class FeatureComponent {}
```

### Svelte

```svelte
<script>
  import VersionGuard from 'despia-version-guard/svelte';
</script>

<VersionGuard minVersion="21.0.3">
  <NewFeatureComponent />
</VersionGuard>

<VersionGuard maxVersion="21.0.3">
  <LegacyFeatureComponent />
</VersionGuard>

<VersionGuard minVersion="21.0.0" maxVersion="21.0.3">
  <VersionSpecificFeature />
</VersionGuard>
```

### Vanilla JS / Web Components

#### Web Component (Recommended)

```html
<!-- Register the component (only needed once) -->
<script type="module">
  import 'despia-version-guard/vanilla';
</script>

<!-- Use the component -->
<version-guard min-version="21.0.3">
  <div>New Feature</div>
</version-guard>

<version-guard max-version="21.0.3">
  <div>Legacy Feature</div>
</version-guard>

<version-guard min-version="21.0.0" max-version="21.0.3">
  <div>Version-Specific Feature</div>
</version-guard>
```

#### Programmatic API

```javascript
import { createVersionGuard } from 'despia-version-guard/vanilla';

const element = document.getElementById('my-feature');

// Create version guard
const updateVisibility = createVersionGuard({
  minVersion: '21.0.3',
  element: element
});

// Manually check version (optional)
updateVisibility();
```

### Use Cases

1. **Major UI Shifts**: Show new UI only to users with the required minimum version
2. **Deprecation**: Hide legacy features when version exceeds maximum
3. **Upgrade Prompts**: Conditionally show upgrade buttons based on version
4. **Store Compliance**: Ensure app review compatibility by version-gating major changes
5. **Enterprise Reliability**: Prevent broken UI when Despia adds new runtime features that old users don't have
6. **Progressive Enhancement**: Gracefully degrade features for users with older runtimes

### How It Works

- The component reads `window.bundleNumber` from the Despia Native SDK runtime
- It compares the current version with `min_version` and `max_version` props
- If the version is outside the specified range, the component returns `null` (renders nothing)
- If the version is within range (or no constraints are specified), it renders the children wrapped in a `div`

### Version Comparison

Version comparison uses semantic versioning:
- `"21.0.2" < "21.0.3"` → true
- `"21.0.3" == "21.0.3"` → true
- `"21.0.4" > "21.0.3"` → true

### Examples

#### Example 1: Minimum Version Only
```tsx
// Hide if version is less than 21.0.3
<VersionGuard min_version="21.0.3">
  <div>This only shows on 21.0.3+</div>
</VersionGuard>
```

If `window.bundleNumber` is `"21.0.2"`, the content will be hidden.

#### Example 2: Maximum Version Only
```tsx
// Hide if version is greater than 21.0.3
<VersionGuard max_version="21.0.3">
  <div>This only shows on 21.0.3 or lower</div>
</VersionGuard>
```

If `window.bundleNumber` is `"21.0.4"`, the content will be hidden.

#### Example 3: Version Range
```tsx
// Only show for versions between 21.0.0 and 21.0.3 (inclusive)
<VersionGuard min_version="21.0.0" max_version="21.0.3">
  <div>This shows for versions 21.0.0 through 21.0.3</div>
</VersionGuard>
```

#### Example 4: Enterprise Use Case - New Despia Runtime Feature
```tsx
// Despia adds a new feature in runtime 21.0.4
// Hide the feature from old users and show upgrade prompt
<VersionGuard min_version="21.0.4">
  <NewDespiaFeature />
</VersionGuard>

// Show critical upgrade prompt for very old users
<VersionGuard max_version="21.0.1">
  <CriticalUpgradePrompt />
</VersionGuard>

// Show standard upgrade prompt for users who need minor update
{!isVersionInRange(window.bundleNumber, '21.0.4') && 
 isVersionInRange(window.bundleNumber, '21.0.2') && (
  <StandardUpgradePrompt />
)}
```

This pattern ensures:
- **100% Reliability**: Old users never see broken features
- **Clear Upgrade Path**: Users know when and why to update
- **Enterprise-Grade**: Critical for apps where users depend on functionality working correctly
- **Store Compliance**: Prevents app review issues from broken features

## API

### Component Props / Attributes

| Prop/Attribute | Type | Required | Description |
|----------------|------|----------|-------------|
| `min_version` / `minVersion` / `min-version` | `string` | No | Minimum version (inclusive). Content is hidden if current version is less than this. |
| `max_version` / `maxVersion` / `max-version` | `string` | No | Maximum version (inclusive). Content is hidden if current version is greater than this. |

**Note**: Prop naming varies by framework:
- **React**: `min_version`, `max_version` (snake_case)
- **Vue**: `minVersion`, `maxVersion` (camelCase)
- **Angular**: `minVersion`, `maxVersion` (camelCase)
- **Svelte**: `minVersion`, `maxVersion` (camelCase)
- **Web Components**: `min-version`, `max-version` (kebab-case)

### Utility Functions

You can also import utility functions for custom version comparison:

```tsx
import { compareVersions, isVersionInRange } from 'despia-version-guard';

// Compare two versions
compareVersions("21.0.3", "21.0.2"); // Returns 1 (first is greater)

// Check if version is in range
isVersionInRange("21.0.3", "21.0.0", "21.0.5"); // Returns true
```

## Framework-Specific Imports

```typescript
// React (default)
import { VersionGuard } from 'despia-version-guard';

// Vue
import { VersionGuard } from 'despia-version-guard/vue';

// Angular
import { VersionGuardComponent } from 'despia-version-guard/angular';

// Svelte
import VersionGuard from 'despia-version-guard/svelte';

// Vanilla JS
import { createVersionGuard, VersionGuardElement } from 'despia-version-guard/vanilla';
```

## Requirements

- **Framework**: React 16.8+, Vue 3, Angular (standalone), Svelte, or none (vanilla JS)
- **Runtime**: Despia Native SDK with `window.bundleNumber` available

## License

MIT