npm package: @litforge/state-vue
Description: Vue.js integration for `@litforge/state`. Provides a composable hook for using the state management system in Vue 3 applications.
Latest version: 0.1.22

# @litforge/state-vue

Vue.js integration for `@litforge/state`. Provides a composable hook for using the state management system in Vue 3 applications.

## Overview

`@litforge/state-vue` wraps `@litforge/state` with Vue-specific functionality, providing reactive state management through Vue's Composition API.

## Installation

```bash
npm install @litforge/state-vue @litforge/state
# or
pnpm add @litforge/state-vue @litforge/state
# or
yarn add @litforge/state-vue @litforge/state
```

**Note**: `@litforge/state` is a peer dependency and must be installed separately.

## Requirements

- Vue 3.x
- @litforge/state

## Basic Usage

### Using the Composable

```vue
<script setup lang="ts">
import { useStateSystem } from '@litforge/state-vue';

const { ready, log, pushEvent, subscribe, replay } = useStateSystem({
  connectDevtools: true,
  getState: () => window.__STATE__ ?? {},
  restoreState: (state) => {
    window.__STATE__ = state;
  }
});

// Push an event
const handleAction = () => {
  pushEvent({
    type: 'USER_ACTION',
    payload: { action: 'click' }
  });
};

// Subscribe to events
subscribe((event) => {
  console.log('Event received:', event);
});
</script>

<template>
  <div v-if="ready">
    <p>State system ready!</p>
    <button @click="handleAction">Trigger Event</button>
  </div>
</template>
```

## API

### `useStateSystem(options?)`

Returns a reactive object with the following properties:

#### Options

```typescript
interface UseStateSystemOptions<TState = any> {
  connectDevtools?: boolean;  // Connect to Redux DevTools (default: true)
  getState?: () => TState;    // Function to get current state
  restoreState?: (state: TState) => void; // Function to restore state
}
```

#### Return Value

- `ready`: Computed ref indicating if the state system is initialized
- `log`: Computed ref to the ActionLog instance
- `pushEvent(event)`: Function to push a new event
- `subscribe(fn)`: Function to subscribe to events
- `replay(index, applyEvent)`: Function to replay events
- `export()`: Export state as JSON string
- `import(json)`: Import state from JSON string
- `instance`: Getter for the ActionLog instance

## Example: Full Integration

```vue
<script setup lang="ts">
import { ref, computed } from 'vue';
import { useStateSystem } from '@litforge/state-vue';

// Your application state
const appState = ref({
  user: null,
  todos: []
});

// Initialize state system
const { ready, pushEvent, subscribe } = useStateSystem({
  connectDevtools: true,
  getState: () => appState.value,
  restoreState: (state) => {
    appState.value = state;
  }
});

// Subscribe to events and update state
subscribe((event) => {
  switch (event.type) {
    case 'USER_LOGIN':
      appState.value.user = event.payload;
      break;
    case 'ADD_TODO':
      appState.value.todos.push(event.payload);
      break;
  }
});

// Actions
const login = (user) => {
  pushEvent({
    type: 'USER_LOGIN',
    payload: user
  });
};

const addTodo = (todo) => {
  pushEvent({
    type: 'ADD_TODO',
    payload: todo
  });
};
</script>
```

## Lifecycle

The composable automatically:
- Initializes the state system on component mount
- Cleans up subscriptions on component unmount
- Handles async initialization gracefully

## TypeScript Support

Fully typed with TypeScript:

```typescript
import { useStateSystem } from '@litforge/state-vue';
import type { UseStateSystemOptions } from '@litforge/state-vue';

interface MyState {
  user: { id: string; name: string };
  count: number;
}

const options: UseStateSystemOptions<MyState> = {
  getState: () => ({ user: { id: '1', name: 'John' }, count: 0 }),
  restoreState: (state) => { /* ... */ }
};

const { log } = useStateSystem<MyState>(options);
```

## License

Part of the LitForge component library.