@vira-ui/react 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,746 @@
+# @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>
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vira-ui/react",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Vira Framework - React hooks for Vira Reactive Protocol",
   "author": "Vira Team",
   "license": "MIT",
@@ -32,7 +32,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@vira-ui/core": "workspace:*",
+    "@vira-ui/core": "^1.0.1",
     "react": "^18.2.0"
   },
   "peerDependencies": {