@weavix/tracker-plugin-sdk-react 0.0.1

package/README.md

@@ -0,0 +1,201 @@
+# @weavix/tracker-plugin-sdk-react
+
+React SDK for Tracker plugins (Weavix / npm). Mirrors `@yandex-data-ui/tracker-plugin-sdk-react`.
+
+Для удобства написания плагинов:
+
+Этот пакет предоставляет `TrackerPluginProvider`, хуки, а также реэкспортирует `trackerApi` и `hostApi` из core.
+
+> **Для агентов и AI:** [AGENTS.md](./AGENTS.md) → [COOKBOOK](../../docs/agent/COOKBOOK.md). Core API: [tracker-plugin-external](../tracker-plugin-external/README.md).
+
+## Установка
+
+```bash
+npm install @weavix/tracker-plugin-sdk-react
+```
+
+## Использование
+
+### Инициализация плагина
+
+Оберните приложение в `TrackerPluginProvider` в корне. Компонент управляет инициализацией, состояниями загрузки и ошибок, а также уведомляет хост о готовности плагина.
+
+```tsx
+import { TrackerPluginProvider } from '@weavix/tracker-plugin-sdk-react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+
+const root = createRoot(document.getElementById('root')!);
+
+root.render(
+  <TrackerPluginProvider>
+    <App />
+  </TrackerPluginProvider>,
+);
+```
+
+### Получение темы, языка и контекста слота (basic)
+
+По умолчанию в манифесте `contextLevel: "basic"` (или поле не задано) — в `slotContext` только `entityId` и опционально `entityMeta`.
+
+```tsx
+import { useTrackerPluginContext } from '@weavix/tracker-plugin-sdk-react';
+
+function MyComponent() {
+  const { theme, language, slot, slotContext } = useTrackerPluginContext();
+
+  return (
+    <div className={theme}>
+      <p>Язык: {language}</p>
+      <p>Слот: {slot}</p>
+      <p>Сущность: {slotContext?.entityId}</p>
+    </div>
+  );
+}
+```
+
+### Полный контекст слота (Issue)
+
+Требуется `"contextLevel": "full"` в манифесте плагина.
+
+```tsx
+import { useTrackerPluginContext } from '@weavix/tracker-plugin-sdk-react';
+
+function IssuePlugin() {
+  const { slotContext } = useTrackerPluginContext<'issue.action'>('full');
+
+  return (
+    <div>
+      <h1>Задача: {slotContext?.key}</h1>
+      <p>Версия: {slotContext?.version}</p>
+    </div>
+  );
+}
+```
+
+Тип `Issue` в контексте слота — из **`@weavix/tracker-core`** (реэкспорт из core). Типы ответов **`trackerApi.v3`** — из **`@weavix/tracker-api-types`**.
+
+### Локализация
+
+```tsx
+import { useLocalizedString } from '@weavix/tracker-plugin-sdk-react';
+
+function MyComponent() {
+  const localize = useLocalizedString();
+
+  const field = {
+    name: { ru: 'Название', en: 'Summary' },
+  };
+
+  return <h1>{localize(field.name)}</h1>;
+}
+```
+
+### Кастомные состояния загрузки и ошибок
+
+```tsx
+import { TrackerPluginProvider } from '@weavix/tracker-plugin-sdk-react';
+
+root.render(
+  <TrackerPluginProvider
+    autoResize={false}
+    fallback={<div>Загрузка...</div>}
+    errorFallback={(error) => <div>Ошибка: {error.message}</div>}
+    autoNotifyReady={false}
+  >
+    <App />
+  </TrackerPluginProvider>,
+);
+```
+
+### Ручной вызов `notifyReady`
+
+```tsx
+import { TrackerPluginProvider, hostApi } from '@weavix/tracker-plugin-sdk-react';
+import { useEffect } from 'react';
+
+function App() {
+  useEffect(() => {
+    initializeApp().then(() => {
+      hostApi.notifyReady();
+    });
+  }, []);
+
+  return <div>My Plugin</div>;
+}
+
+root.render(
+  <TrackerPluginProvider autoNotifyReady={false}>
+    <App />
+  </TrackerPluginProvider>,
+);
+```
+
+## Компоненты
+
+### `TrackerPluginProvider`
+
+Оборачивает приложение и управляет жизненным циклом плагина.
+
+**Props:**
+
+| Prop | Тип | По умолчанию | Описание |
+|------|-----|--------------|----------|
+| `autoResize` | `boolean` | `true` | Автоматически изменять размер контейнера при изменении контента |
+| `fallback` | `ReactNode` | `<PluginLoader />` | Отображается во время инициализации |
+| `errorFallback` | `(error: Error) => ReactNode` | `<PluginError />` | Отображается при ошибке инициализации |
+| `autoNotifyReady` | `boolean` | `true` | Автоматически уведомлять хост о готовности плагина |
+
+## Хуки
+
+### `useTrackerPluginContext<TSlot>(level?)`
+
+Возвращает тему, язык, имя слота и контекст слота.
+
+- **`level: 'basic'`** (по умолчанию) — `slotContext`: `{ entityId, entityMeta? }`
+- **`level: 'full'`** — полный контекст слота (`Issue` для `issue.action`); нужен `contextLevel: "full"` в манифесте
+
+**Возвращает:** `{ theme, language, slot, slotContext, registerHandler }`
+
+Подробнее: [API Reference — useTrackerPluginContext](./API_REFERENCE.md#usetrackerplugincontext).
+
+### `useToaster()`
+
+Хук для показа toast-уведомлений в хост-приложении.
+
+> **Permission:** `"toaster"` в `permissions.ui` манифеста.
+
+```tsx
+import { useToaster } from '@weavix/tracker-plugin-sdk-react';
+
+function MyComponent() {
+  const toaster = useToaster();
+
+  const handleSave = async () => {
+    await saveData();
+    toaster.add({ title: 'Сохранено', theme: 'success' });
+  };
+
+  return <button onClick={handleSave}>Сохранить</button>;
+}
+```
+
+Параметры `add(options)` — в [README tracker-core](../tracker-plugin-external/README.md#тосты-toast-notifications).
+
+### `useLocalizedString(fallbackLanguage?)`
+
+Возвращает `(value: LocalizedString) => string` для текущего языка из контекста.
+
+## Полная документация
+
+📖 [AGENTS.md](./AGENTS.md) — вход для агентов.
+
+📖 [COOKBOOK](../../docs/agent/COOKBOOK.md) — рецепты.
+
+📖 [API Reference](./API_REFERENCE.md) — Provider, хуки, contextLevel.
+
+📖 [README tracker-core](../tracker-plugin-external/README.md) — `trackerApi`, `hostApi`, типы, ошибки.
+
+## Лицензия
+
+UNLICENSED