@vira-ui/react 1.0.2 → 1.1.1

package/README.md

@@ -1,746 +1,411 @@
-# @vira-ui/react
-
-<div align="center">
-
-**Vira Framework - React hooks for Vira Reactive Protocol (VRP)**
-
-[![Version](https://img.shields.io/npm/v/@vira-ui/react.svg)](https://www.npmjs.com/package/@vira-ui/react)
-[![License](https://img.shields.io/npm/l/@vira-ui/react.svg)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
-
-**React hooks для работы с Vira Reactive Protocol - синхронизация состояния в реальном времени через WebSocket.**
-
-[Установка](#-установка) • [Быстрый старт](#-быстрый-старт) • [API](#-api-reference) • [Примеры](#-примеры)
-
-</div>
-
----
-
-## 🎯 Что это?
-
-**@vira-ui/react** — это пакет React хуков для работы с **Vira Reactive Protocol (VRP)**. Он предоставляет простой способ синхронизации состояния между клиентом и сервером в реальном времени через WebSocket.
-
-### Основные возможности
-
-- ✅ **useViraState** — универсальный хук для работы с VRP каналами
-- ✅ **Автоматическая синхронизация** — состояние обновляется автоматически при изменениях на сервере
-- ✅ **Типизация** — полная поддержка TypeScript
-- ✅ **Idempotency** — поддержка msgId для предотвращения дублирования сообщений
-- ✅ **Deep merge** — умное слияние частичных обновлений
-- ✅ **Reconnection** — автоматическое переподключение при разрыве связи
-- ✅ **Session management** — управление сессиями для восстановления состояния
-
----
-
-## 📦 Установка
-
-```bash
-npm install @vira-ui/react @vira-ui/core react
-```
-
-**Требования:**
-- React 18.2.0+
-- @vira-ui/core 1.0.1+
-- TypeScript 5.3+ (рекомендуется)
-
----
-
-## 🚀 Быстрый старт
-
-### 1. Базовое использование
-
-```tsx
-import { useViraState } from "@vira-ui/react";
-
-function MyComponent() {
-  const { data, sendUpdate, sendDiff, sendEvent } = useViraState<User>(
-    "user:123"
-  );
-
-  if (!data) {
-    return <div>Loading...</div>;
-  }
-
-  return (
-    <div>
-      <h1>{data.name}</h1>
-      <button onClick={() => sendDiff({ name: "New Name" })}>
-        Обновить имя
-      </button>
-    </div>
-  );
-}
-```
-
-### 2. С опциями
-
-```tsx
-import { useViraState } from "@vira-ui/react";
-
-function MyComponent() {
-  const { data, sendUpdate, sendDiff, isConnected, error } = useViraState<User>(
-    "user:123",
-    {
-      initial: { name: "Guest", email: "" },
-      enableMsgId: true,
-      deepMerge: true,
-      onOpen: () => console.log("Connected"),
-      onClose: () => console.log("Disconnected"),
-      onError: (err) => console.error("Error:", err),
-      apiUrl: "http://localhost:8080",
-      authToken: "your-token",
-    }
-  );
-
-  if (error) {
-    return <div>Error: {error.message}</div>;
-  }
-
-  if (!isConnected) {
-    return <div>Connecting...</div>;
-  }
-
-  return <div>{data?.name}</div>;
-}
-```
-
-### 3. С несколькими каналами
-
-```tsx
-import { useViraState } from "@vira-ui/react";
-
-function Dashboard() {
-  const user = useViraState<User>("user:123");
-  const notifications = useViraState<Notification[]>("notifications:123");
-  const tasks = useViraState<Task[]>("tasks:123");
-
-  return (
-    <div>
-      <UserProfile data={user.data} />
-      <NotificationsList data={notifications.data} />
-      <TasksList data={tasks.data} />
-    </div>
-  );
-}
-```
-
----
-
-## 📚 API Reference
-
-### `useViraState<T>(channel, options?)`
-
-Универсальный хук для работы с VRP каналами.
-
-**Параметры:**
-
-- `channel` (string) — имя канала (например, `"user:123"`, `"tasks:456"`)
-- `options` (UseViraStateOptions, опционально) — опции хука
-
-**Возвращает:**
-
-```tsx
-{
-  // Текущее состояние данных
-  data: T | null;
-  
-  // Отправить событие на сервер
-  sendEvent: (name: string, payload: any, msgId?: string) => void;
-  
-  // Отправить полное обновление (заменяет состояние)
-  sendUpdate: (payload: T, msgId?: string) => void;
-  
-  // Отправить частичное обновление (сливается с текущим состоянием)
-  sendDiff: (patch: Partial<T>, msgId?: string) => void;
-  
-  // Статус подключения
-  isConnected: boolean;
-  
-  // Ошибка подключения, если есть
-  error: Error | null;
-}
-```
-
-**Опции:**
-
-```tsx
-interface UseViraStateOptions<T> {
-  // Начальное значение состояния
-  initial?: T | null;
-  
-  // Включить поддержку msgId для идемпотентности
-  enableMsgId?: boolean;
-  
-  // Callback при открытии соединения
-  onOpen?: () => void;
-  
-  // Callback при закрытии соединения
-  onClose?: (event: CloseEvent) => void;
-  
-  // Callback при ошибке соединения
-  onError?: (error: Error) => void;
-  
-  // Использовать deep merge для diff патчей (по умолчанию: true)
-  deepMerge?: boolean;
-  
-  // URL API (по умолчанию: VITE_API_URL или 'http://localhost:8080')
-  apiUrl?: string;
-  
-  // Auth token для handshake
-  authToken?: string;
-}
-```
-
----
-
-## 🎯 Примеры использования
-
-### Пример 1: Простое обновление состояния
-
-```tsx
-import { useViraState } from "@vira-ui/react";
-
-interface Counter {
-  count: number;
-}
-
-function CounterComponent() {
-  const { data, sendDiff } = useViraState<Counter>("counter:demo");
-
-  const increment = () => {
-    sendDiff({ count: (data?.count || 0) + 1 });
-  };
-
-  return (
-    <div>
-      <p>Count: {data?.count || 0}</p>
-      <button onClick={increment}>Increment</button>
-    </div>
-  );
-}
-```
-
-### Пример 2: Работа с пользователем
-
-```tsx
-import { useViraState } from "@vira-ui/react";
-
-interface User {
-  id: string;
-  name: string;
-  email: string;
-  avatar?: string;
-}
-
-function UserProfile({ userId }: { userId: string }) {
-  const { data, sendDiff, sendEvent, isConnected } = useViraState<User>(
-    `user:${userId}`,
-    {
-      initial: { id: userId, name: "", email: "" },
-      enableMsgId: true,
-    }
-  );
-
-  const updateName = (newName: string) => {
-    sendDiff({ name: newName });
-  };
-
-  const updateEmail = (newEmail: string) => {
-    sendDiff({ email: newEmail });
-  };
-
-  const uploadAvatar = (avatarUrl: string) => {
-    sendEvent("user.avatar.upload", { avatarUrl });
-  };
-
-  if (!isConnected) {
-    return <div>Connecting...</div>;
-  }
-
-  return (
-    <div>
-      <img src={data?.avatar} alt={data?.name} />
-      <input
-        value={data?.name || ""}
-        onChange={(e) => updateName(e.target.value)}
-      />
-      <input
-        value={data?.email || ""}
-        onChange={(e) => updateEmail(e.target.value)}
-      />
-    </div>
-  );
-}
-```
-
-### Пример 3: Kanban доска
-
-```tsx
-import { useViraState } from "@vira-ui/react";
-
-interface KanbanBoard {
-  id: string;
-  title: string;
-  columns: Column[];
-  cards: Record<string, Card>;
-}
-
-function KanbanBoard({ boardId }: { boardId: string }) {
-  const { data, sendEvent, sendDiff } = useViraState<KanbanBoard>(
-    `kanban:${boardId}`,
-    {
-      enableMsgId: true,
-      deepMerge: true,
-    }
-  );
-
-  const createCard = (columnId: string, title: string) => {
-    sendEvent("kanban.card.create", {
-      boardId,
-      columnId,
-      title,
-      at: Date.now(),
-    });
-  };
-
-  const moveCard = (
-    cardId: string,
-    fromColumnId: string,
-    toColumnId: string,
-    newOrder: number
-  ) => {
-    sendEvent("kanban.card.move", {
-      boardId,
-      cardId,
-      fromColumnId,
-      toColumnId,
-      newOrder,
-      at: Date.now(),
-    });
-  };
-
-  const updateCard = (cardId: string, updates: Partial<Card>) => {
-    sendDiff({
-      cards: {
-        [cardId]: updates,
-      },
-    });
-  };
-
-  if (!data) {
-    return <div>Loading board...</div>;
-  }
-
-  return (
-    <div>
-      <h1>{data.title}</h1>
-      {data.columns.map((column) => (
-        <Column
-          key={column.id}
-          column={column}
-          cards={getColumnCards(data, column.id)}
-          onCreateCard={(title) => createCard(column.id, title)}
-          onMoveCard={moveCard}
-          onUpdateCard={updateCard}
-        />
-      ))}
-    </div>
-  );
-}
-```
-
-### Пример 4: Чат приложение
-
-```tsx
-import { useViraState } from "@vira-ui/react";
-
-interface Chat {
-  messages: Message[];
-  participants: User[];
-}
-
-function ChatRoom({ roomId }: { roomId: string }) {
-  const { data, sendEvent, sendDiff } = useViraState<Chat>(`chat:${roomId}`, {
-    initial: { messages: [], participants: [] },
-    enableMsgId: true,
-  });
-
-  const sendMessage = (text: string) => {
-    sendEvent("chat.message.send", {
-      roomId,
-      text,
-      timestamp: Date.now(),
-    });
-  };
-
-  const addParticipant = (user: User) => {
-    sendDiff({
-      participants: [...(data?.participants || []), user],
-    });
-  };
-
-  return (
-    <div>
-      <div>
-        {data?.messages.map((msg) => (
-          <MessageBubble key={msg.id} message={msg} />
-        ))}
-      </div>
-      <MessageInput onSend={sendMessage} />
-    </div>
-  );
-}
-```
-
-### Пример 5: Редактирование документа
-
-```tsx
-import { useViraState } from "@vira-ui/react";
-
-interface Document {
-  id: string;
-  title: string;
-  content: string;
-  version: number;
-  updatedAt: number;
-}
-
-function DocumentEditor({ docId }: { docId: string }) {
-  const { data, sendDiff, isConnected } = useViraState<Document>(
-    `document:${docId}`,
-    {
-      enableMsgId: true,
-      deepMerge: true,
-      onOpen: () => console.log("Document loaded"),
-    }
-  );
-
-  const updateTitle = (title: string) => {
-    sendDiff({
-      title,
-      updatedAt: Date.now(),
-    });
-  };
-
-  const updateContent = (content: string) => {
-    sendDiff({
-      content,
-      updatedAt: Date.now(),
-    });
-  };
-
-  if (!isConnected || !data) {
-    return <div>Loading document...</div>;
-  }
-
-  return (
-    <div>
-      <input
-        value={data.title}
-        onChange={(e) => updateTitle(e.target.value)}
-      />
-      <textarea
-        value={data.content}
-        onChange={(e) => updateContent(e.target.value)}
-      />
-      <div>Version: {data.version}</div>
-    </div>
-  );
-}
-```
-
-### Пример 6: С обработкой ошибок
-
-```tsx
-import { useViraState } from "@vira-ui/react";
-
-function RobustComponent() {
-  const { data, sendDiff, isConnected, error } = useViraState<MyData>(
-    "my:channel",
-    {
-      onError: (err) => {
-        console.error("Connection error:", err);
-        // Можно отправить в систему мониторинга
-        // sendToMonitoring(err);
-      },
-      onClose: (event) => {
-        console.log("Connection closed:", event.code, event.reason);
-        // Можно показать уведомление пользователю
-      },
-    }
-  );
-
-  if (error) {
-    return (
-      <div>
-        <p>Ошибка подключения: {error.message}</p>
-        <button onClick={() => window.location.reload()}>
-          Перезагрузить
-        </button>
-      </div>
-    );
-  }
-
-  if (!isConnected) {
-    return <div>Подключение...</div>;
-  }
-
-  return <div>{/* Ваш контент */}</div>;
-}
-```
-
----
-
-## 🔧 Конфигурация
-
-### Переменные окружения
-
-```env
-# URL API сервера
-VITE_API_URL=http://localhost:8080
-
-# Auth token для подключения
-VITE_AUTH_TOKEN=your-secret-token
-```
-
-### Программная конфигурация
-
-```tsx
-import { useViraState } from "@vira-ui/react";
-
-function MyComponent() {
-  const { data } = useViraState("my:channel", {
-    apiUrl: "https://api.example.com",
-    authToken: "your-token",
-  });
-}
-```
-
----
-
-## 🎯 Vira Reactive Protocol (VRP)
-
-### Типы сообщений
-
-VRP поддерживает следующие типы сообщений:
-
-#### 1. `update` — полное обновление состояния
-
-```tsx
-sendUpdate({ name: "John", age: 30 });
-```
-
-#### 2. `diff` — частичное обновление
-
-```tsx
-sendDiff({ name: "Jane" }); // Обновит только name
-```
-
-#### 3. `event` — событие
-
-```tsx
-sendEvent("user.created", { userId: "123" });
-```
-
-### Каналы
-
-Каналы используются для изоляции данных:
-
-```tsx
-// Пользователь
-"user:123"
-
-// Задачи
-"tasks:456"
-
-// Уведомления
-"notifications:123"
-
-// Демо канал
-"demo"
-```
-
-### Idempotency (msgId)
-
-Для предотвращения дублирования сообщений используйте `enableMsgId`:
-
-```tsx
-const { sendUpdate } = useViraState("my:channel", {
-  enableMsgId: true, // Автоматически генерирует msgId
-});
-
-// Или вручную
-sendUpdate(data, "custom-msg-id");
-```
-
-### Deep Merge
-
-По умолчанию используется deep merge для diff обновлений:
-
-```tsx
-// Текущее состояние
-{ user: { name: "John", age: 30 } }
-
-// Отправляем diff
-sendDiff({ user: { name: "Jane" } });
-
-// Результат (deep merge)
-{ user: { name: "Jane", age: 30 } }
-```
-
-Для shallow merge:
-
-```tsx
-useViraState("my:channel", {
-  deepMerge: false, // Shallow merge
-});
-```
-
----
-
-## 🔥 Best Practices
-
-### 1. Используйте типизацию
-
-```tsx
-// ✅ Хорошо
-interface User {
-  id: string;
-  name: string;
-}
-
-const { data } = useViraState<User>("user:123");
-
-// ❌ Плохо
-const { data } = useViraState("user:123");
-```
-
-### 2. Используйте enableMsgId для критичных операций
-
-```tsx
-// ✅ Хорошо
-useViraState("payment:123", {
-  enableMsgId: true, // Предотвращает дублирование платежей
-});
-
-// ❌ Плохо
-useViraState("payment:123"); // Может привести к дублированию
-```
-
-### 3. Обрабатывайте ошибки
-
-```tsx
-// ✅ Хорошо
-const { data, error, isConnected } = useViraState("my:channel", {
-  onError: (err) => console.error(err),
-});
-
-if (error) {
-  return <ErrorComponent error={error} />;
-}
-
-// ❌ Плохо
-const { data } = useViraState("my:channel");
-// Нет обработки ошибок
-```
-
-### 4. Используйте initial для лучшего UX
-
-```tsx
-// ✅ Хорошо
-useViraState("user:123", {
-  initial: { name: "Loading...", email: "" },
-});
-
-// ❌ Плохо
-useViraState("user:123");
-// Пользователь видит пустой экран
-```
-
-### 5. Используйте sendDiff для частичных обновлений
-
-```tsx
-// ✅ Хорошо
-sendDiff({ name: "New Name" }); // Обновляет только name
-
-// ❌ Плохо
-sendUpdate({ ...data, name: "New Name" }); // Отправляет весь объект
-```
-
----
-
-## ❓ FAQ
-
-**Q: В чём разница между `sendUpdate` и `sendDiff`?**
-
-A: `sendUpdate` заменяет всё состояние целиком, а `sendDiff` сливает изменения с текущим состоянием. Используйте `sendDiff` для частичных обновлений.
-
-**Q: Что такое msgId и зачем он нужен?**
-
-A: `msgId` — это уникальный идентификатор сообщения для предотвращения дублирования. Включите `enableMsgId: true` для критичных операций.
-
-**Q: Как работает deep merge?**
-
-A: Deep merge рекурсивно сливает объекты, сохраняя вложенные структуры. Например, `{ user: { name: "Jane" } }` обновит только `name`, не затрагивая другие поля `user`.
-
-**Q: Можно ли использовать несколько каналов одновременно?**
-
-A: Да! Просто вызовите `useViraState` несколько раз с разными каналами.
-
-**Q: Что происходит при разрыве соединения?**
-
-A: Клиент автоматически пытается переподключиться. Вы можете отслеживать статус через `isConnected` и обрабатывать через `onClose` callback.
-
-**Q: Как работает сессия?**
-
-A: Сессия сохраняется между переподключениями, что позволяет восстановить подписки и состояние.
-
-**Q: Можно ли использовать без TypeScript?**
-
-A: Да, но TypeScript рекомендуется для лучшего DX и безопасности типов.
-
----
-
-## 🛣️ Roadmap
-
-### v1.1 (В разработке)
-- [ ] Поддержка batch операций
-- [ ] Оптимистичные обновления
-- [ ] Offline queue
-- [ ] Compression для больших payload
-
-### v1.2 (Планируется)
-- [ ] DevTools интеграция
-- [ ] Метрики и мониторинг
-- [ ] Поддержка подписок на несколько каналов
-- [ ] WebRTC fallback
-
----
-
-## 📄 License
-
-MIT
-
----
-
-## 🤝 Contributing
-
-Мы приветствуем вклад! Пожалуйста, прочитайте [CONTRIBUTING.md](../../CONTRIBUTING.md) для деталей.
-
----
-
-## 📞 Support
-
-- **GitHub Issues**: [Создать issue](https://github.com/skrolikov/vira-core/issues)
-- **Discussions**: [Обсуждения](https://github.com/skrolikov/vira-core/discussions)
-
----
-
-<div align="center">
-
-**Сделано с ❤️ командой Vira**
-
-[GitHub](https://github.com/skrolikov/vira-core) • [Документация](https://vira.dev/react) • [Примеры](https://vira.dev/examples)
-
-</div>
-
+# @vira-ui/react
+
+<div align="center">
+
+**React хуки для Vira Reactive Protocol (VRP)**
+
+[![Version](https://img.shields.io/npm/v/@vira-ui/react.svg)](https://www.npmjs.com/package/@vira-ui/react)
+[![License](https://img.shields.io/npm/l/@vira-ui/react.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
+
+**Синхронизация состояния между клиентом и сервером через WebSocket**
+
+[Установка](#-установка) • [Быстрый старт](#-быстрый-старт) • [Документация](#-документация)
+
+</div>
+
+---
+
+## 🎯 Что это?
+
+**@vira-ui/react** предоставляет React хуки для работы с Vira Reactive Protocol (VRP) — протоколом для real-time синхронизации состояния между клиентом и сервером через WebSocket.
+
+### Основные возможности
+
+- ✅ **Автоматическая синхронизация** — состояние обновляется при изменениях на сервере
+- ✅ **Двусторонняя связь** — можно отправлять события и обновления на сервер
+- ✅ **Diff-патчи** — обновляются только изменённые части данных
+- ✅ **Переподключение** — автоматическое восстановление соединения
+- ✅ **TypeScript** — полная типизация
+
+---
+
+## 📦 Установка
+
+```bash
+npm install @vira-ui/react @vira-ui/core react
+```
+
+**Требования:**
+- React 18.2.0+
+- `@vira-ui/core` ^1.0.0
+- Сервер с поддержкой Vira Reactive Protocol
+
+---
+
+## 🚀 Быстрый старт
+
+### useViraState
+
+Основной хук для синхронизации состояния:
+
+```tsx
+import { useViraState } from '@vira-ui/react';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+function UserProfile({ userId }: { userId: string }) {
+  const { data, sendUpdate, sendDiff, isConnected } = useViraState<User>(
+    `user:${userId}`,
+    {
+      initial: { id: userId, name: 'Guest', email: '' },
+      onOpen: () => console.log('Connected'),
+      deepMerge: true
+    }
+  );
+
+  if (!isConnected) return <div>Connecting...</div>;
+  if (!data) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h1>{data.name}</h1>
+      <p>{data.email}</p>
+      <button onClick={() => sendDiff({ name: 'New Name' })}>
+        Update Name
+      </button>
+    </div>
+  );
+}
+```
+
+---
+
+## 📚 Документация
+
+### useViraState
+
+Подключается к VRP каналу и синхронизирует состояние.
+
+**Параметры:**
+- `channel` — имя канала (например: `"user:123"`, `"tasks"`)
+- `options` — опции конфигурации
+
+**Возвращает:**
+- `data` — текущее состояние
+- `sendUpdate(payload)` — полная замена состояния
+- `sendDiff(patch)` — частичное обновление (merge)
+- `sendEvent(name, payload)` — отправка события
+- `isConnected` — статус соединения
+- `isLoading` — статус загрузки
+
+**Опции:**
+- `initial` — начальное значение
+- `apiUrl` — URL сервера (по умолчанию из `VITE_API_URL`)
+- `authToken` — токен авторизации
+- `deepMerge` — глубокое слияние для diff-патчей
+- `enableMsgId` — поддержка idempotency
+- `onOpen`, `onClose`, `onError` — колбэки событий соединения
+
+### Примеры использования
+
+#### Список элементов
+
+```tsx
+import { useViraState } from '@vira-ui/react';
+
+interface Task {
+  id: string;
+  title: string;
+  completed: boolean;
+}
+
+function TasksList() {
+  const { data, sendEvent, sendDiff } = useViraState<Task[]>(
+    'tasks',
+    { initial: [] }
+  );
+
+  const toggleTask = (taskId: string) => {
+    const task = data?.find(t => t.id === taskId);
+    if (task) {
+      sendDiff({ [taskId]: { completed: !task.completed } });
+    }
+  };
+
+  const createTask = (title: string) => {
+    sendEvent('task.created', {
+      id: crypto.randomUUID(),
+      title,
+      completed: false
+    });
+  };
+
+  return (
+    <div>
+      {data?.map(task => (
+        <div key={task.id}>
+          <input
+            type="checkbox"
+            checked={task.completed}
+            onChange={() => toggleTask(task.id)}
+          />
+          <span>{task.title}</span>
+        </div>
+      ))}
+      <button onClick={() => createTask('New Task')}>
+        Add Task
+      </button>
+    </div>
+  );
+}
+```
+
+#### Одиночный элемент
+
+```tsx
+function UserDetails({ userId }: { userId: string }) {
+  const { data, sendDiff, isConnected } = useViraState<User>(
+    `user:${userId}`,
+    {
+      initial: null,
+      deepMerge: true
+    }
+  );
+
+  const updateName = (name: string) => {
+    sendDiff({ name });
+  };
+
+  if (!isConnected) {
+    return <div>Connecting to server...</div>;
+  }
+
+  if (!data) {
+    return <div>Loading user...</div>;
+  }
+
+  return (
+    <div>
+      <input
+        value={data.name}
+        onChange={(e) => updateName(e.target.value)}
+      />
+      <p>Email: {data.email}</p>
+    </div>
+  );
+}
+```
+
+#### С обработкой ошибок
+
+```tsx
+function DataComponent({ channel }: { channel: string }) {
+  const { data, sendEvent, isConnected, error } = useViraState(
+    channel,
+    {
+      initial: null,
+      onError: (err) => {
+        console.error('VRP Error:', err);
+        // Можно показать уведомление пользователю
+      },
+      onClose: () => {
+        console.log('Connection closed, reconnecting...');
+      }
+    }
+  );
+
+  if (error) {
+    return <div>Error: {error.message}</div>;
+  }
+
+  if (!isConnected) {
+    return <div>Reconnecting...</div>;
+  }
+
+  return <div>{/* ... */}</div>;
+}
+```
+
+#### С авторизацией
+
+```tsx
+function AuthenticatedComponent() {
+  const authToken = useAuthToken(); // Ваш хук для получения токена
+  
+  const { data } = useViraState('protected:data', {
+    authToken,
+    onError: (err) => {
+      if (err.message.includes('unauthorized')) {
+        // Перенаправить на страницу входа
+      }
+    }
+  });
+
+  return <div>{/* ... */}</div>;
+}
+```
+
+---
+
+## 🔄 Паттерны использования
+
+### Real-time обновления
+
+```tsx
+function LiveDashboard() {
+  const { data } = useViraState('dashboard:stats', {
+    initial: { users: 0, orders: 0 }
+  });
+
+  // Данные автоматически обновляются при изменениях на сервере
+  return (
+    <div>
+      <div>Users: {data?.users}</div>
+      <div>Orders: {data?.orders}</div>
+    </div>
+  );
+}
+```
+
+### Оптимистичные обновления
+
+```tsx
+function OptimisticUpdate() {
+  const { data, sendDiff } = useViraState('user:123', {
+    initial: { name: 'John' }
+  });
+
+  const updateName = (newName: string) => {
+    // Сразу обновляем локально (оптимистично)
+    sendDiff({ name: newName });
+    
+    // Сервер подтвердит или откатит изменение
+  };
+
+  return (
+    <input
+      value={data?.name}
+      onChange={(e) => updateName(e.target.value)}
+    />
+  );
+}
+```
+
+### События вместо обновлений
+
+```tsx
+function EventDriven() {
+  const { sendEvent } = useViraState('tasks', { initial: [] });
+
+  const handleComplete = (taskId: string) => {
+    // Отправляем событие вместо прямого обновления
+    sendEvent('task.completed', { taskId });
+    
+    // Сервер обработает событие и обновит состояние
+  };
+
+  return <button onClick={() => handleComplete('123')}>Complete</button>;
+}
+```
+
+---
+
+## 🔗 Интеграция
+
+Обычно используется вместе с:
+
+- **@vira-ui/core** — базовый фреймворк
+- **@vira-ui/bindings-react** — компоненты с автоматическим связыванием
+
+---
+
+## 📖 Примеры
+
+### Kanban доска
+
+```tsx
+function KanbanBoard() {
+  const { data, sendEvent } = useViraState<Column[]>('kanban:board', {
+    initial: []
+  });
+
+  const moveCard = (cardId: string, fromColumn: string, toColumn: string) => {
+    sendEvent('card.moved', {
+      cardId,
+      fromColumn,
+      toColumn
+    });
+  };
+
+  return (
+    <div className="kanban-board">
+      {data?.map(column => (
+        <Column
+          key={column.id}
+          column={column}
+          onMoveCard={moveCard}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+### Чат
+
+```tsx
+function ChatRoom({ roomId }: { roomId: string }) {
+  const { data, sendEvent } = useViraState<Message[]>(
+    `chat:${roomId}`,
+    { initial: [] }
+  );
+
+  const sendMessage = (text: string) => {
+    sendEvent('message.sent', {
+      id: crypto.randomUUID(),
+      text,
+      timestamp: Date.now()
+    });
+  };
+
+  return (
+    <div>
+      <div className="messages">
+        {data?.map(msg => (
+          <Message key={msg.id} message={msg} />
+        ))}
+      </div>
+      <MessageInput onSend={sendMessage} />
+    </div>
+  );
+}
+```
+
+---
+
+## 🔥 Best Practices
+
+1. **Используйте типизацию** — всегда указывайте тип для `useViraState<T>`
+2. **Обрабатывайте ошибки** — используйте `onError` для обработки ошибок соединения
+3. **Оптимистичные обновления** — используйте `sendDiff` для мгновенного обновления UI
+4. **События для действий** — используйте `sendEvent` для действий, которые должны обрабатываться на сервере
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 🔗 Связанные пакеты
+
+- [`@vira-ui/core`](../core/README.md) - Базовый фреймворк с VRP клиентом
+- [`@vira-ui/bindings-react`](../bindings-react/README.md) - Компоненты с auto-binding
+- [`@vira-ui/ui`](../ui/README.md) - UI компоненты
+