@weavix/tracker-plugin-sdk-react 0.0.1

package/AGENTS.md

@@ -0,0 +1,31 @@
+# @weavix/tracker-plugin-sdk-react — agents
+
+**Пакет:** React (Weavix / npm) + реэкспорт core.
+
+## Импорты
+
+```typescript
+import {
+  TrackerPluginProvider,
+  useTrackerPluginContext,
+  useToaster,
+  useConfirm,
+  hostApi,
+  trackerApi,
+} from '@weavix/tracker-plugin-sdk-react';
+```
+
+## Правила
+
+- **contextLevel** `basic` / `full` — см. [COOKBOOK](../../docs/agent/COOKBOOK.md).
+- **hostApi** + **trackerApi.v3** — см. [core AGENTS](../tracker-plugin-external/AGENTS.md).
+
+## Документация
+
+| Файл | Назначение |
+|------|------------|
+| [../../AGENTS.md](../../AGENTS.md) | Общий вход |
+| [../../docs/agent/COOKBOOK.md](../../docs/agent/COOKBOOK.md) | Рецепты |
+| [README.md](./README.md) | Быстрый старт |
+| [API_REFERENCE.md](./API_REFERENCE.md) | Provider, хуки |
+| [../tracker-plugin-external/API_REFERENCE.md](../tracker-plugin-external/API_REFERENCE.md) | hostApi, uiApi, v3 |

package/API_REFERENCE.md

@@ -0,0 +1,649 @@
+# API Reference - @weavix/tracker-plugin-sdk-react
+
+## Table of Contents
+
+- [Components](#components)
+  - [TrackerPluginProvider](#trackerpluginprovider)
+- [Hooks](#hooks)
+  - [useTrackerPluginContext](#usetrackerplugincontext)
+  - [useLocalizedString](#uselocalizedstring)
+- [Types](#types)
+  - [TrackerPluginProviderProps](#trackerpluginproviderprops)
+  - [TrackerPluginContextValue](#trackerplugincontextvalue)
+  - [BasicTrackerPluginContextValue](#basictrackerplugincontextvalue)
+  - [FullTrackerPluginContextValue](#fulltrackerplugincontextvalue)
+- [Публичное API](#публичное-api) — hostApi, trackerApi (реэкспорт из core)
+- [Утилиты](#утилиты)
+  - [getLocalizedString](#getlocalizedstring)
+
+---
+
+## Components
+
+### TrackerPluginProvider
+
+Провайдер для инициализации плагина Tracker. Оборачивает приложение и управляет жизненным циклом плагина. Предоставляет тему, язык и контекст слота через контекст React.
+
+**Props:** [`TrackerPluginProviderProps`](#trackerpluginproviderprops)
+
+**Features:**
+
+- Автоматическая инициализация плагина
+- Управление состояниями загрузки и ошибок
+- Предоставление контекста через React Context API
+- Автоматическое уведомление хоста о готовности плагина
+- Защита от двойной инициализации в React StrictMode
+
+**Example (базовое использование):**
+
+```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>,
+);
+```
+
+**Example (с кастомными опциями):**
+
+```tsx
+import { TrackerPluginProvider } from '@weavix/tracker-plugin-sdk-react';
+import { Loader } from './components/Loader';
+import { ErrorScreen } from './components/ErrorScreen';
+
+root.render(
+  <TrackerPluginProvider
+    autoResize={false}
+    fallback={<Loader />}
+    errorFallback={(error) => <ErrorScreen error={error} />}
+    autoNotifyReady={false}
+  >
+    <App />
+  </TrackerPluginProvider>,
+);
+```
+
+**Example (отключение автоматического уведомления):**
+
+```tsx
+import { TrackerPluginProvider, hostApi } from '@weavix/tracker-plugin-sdk-react';
+
+function App() {
+  useEffect(() => {
+    // Выполняем дополнительную инициализацию, затем уведомляем хост
+    initializeApp().then(() => {
+      hostApi.notifyReady()
+    });
+  }, []);
+
+  return <div>My Plugin</div>;
+}
+
+root.render(
+  <TrackerPluginProvider autoNotifyReady={false}>
+    <App />
+  </TrackerPluginProvider>,
+);
+```
+
+---
+
+## Hooks
+
+### useTrackerPluginContext
+
+Хук для получения темы, языка и контекста слота из [`TrackerPluginProvider`](#trackerpluginprovider).
+
+Поддерживает два уровня контекста, управляемых полем `contextLevel` в манифесте плагина:
+
+- **`'basic'`** (по умолчанию) — `slotContext` содержит только `{ entityId, entityMeta? }`. Данные берутся из параметров iframe без postMessage-запроса к хосту.
+- **`'full'`** — `slotContext` содержит полный объект слота (Issue и т.д.). Требует `contextLevel: "full"` в манифесте.
+
+**Type Signature:**
+
+```typescript
+// Без аргумента или с 'basic' — slotContext: BasicContext | undefined
+function useTrackerPluginContext(): BasicTrackerPluginContextValue;
+function useTrackerPluginContext(level: 'basic'): BasicTrackerPluginContextValue;
+
+// С 'full' — slotContext: SlotContextMap[TSlot] | undefined
+function useTrackerPluginContext(level: 'full'): FullTrackerPluginContextValue;
+
+// С generic — типизированный контекст для конкретного слота
+function useTrackerPluginContext<TSlot extends keyof SlotContextMap>(level?: 'basic'): BasicTrackerPluginContextValue<TSlot>;
+function useTrackerPluginContext<TSlot extends keyof SlotContextMap>(level: 'full'): FullTrackerPluginContextValue<TSlot>;
+```
+
+**Parameters:**
+
+- `level` — `'basic' | 'full'` (опционально, по умолчанию `'basic'`). Уровень запрашиваемого контекста.
+
+**Type Parameters:**
+
+- `TSlot` — тип слота (опционально). С generic — `slotContext` типизирован под этот слот.
+
+**Returns:** [`BasicTrackerPluginContextValue`](#basictrackerplugincontextvalue) или [`FullTrackerPluginContextValue`](#fulltrackerplugincontextvalue)
+
+**Throws:**
+
+- `Error` — если используется вне [`TrackerPluginProvider`](#trackerpluginprovider)
+- `Error` — если код запрашивает `'full'` контекст, но манифест объявляет `'basic'` (runtime security guard)
+
+**Example (базовый контекст — только entityId и entityMeta):**
+
+```tsx
+import { useTrackerPluginContext } from '@weavix/tracker-plugin-sdk-react';
+
+function MyPlugin() {
+  // По умолчанию — basic контекст
+  const { slotContext } = useTrackerPluginContext();
+  // slotContext: { entityId: string; entityMeta?: Record<string, string> } | undefined
+
+  return <div>Entity: {slotContext?.entityId}</div>;
+}
+```
+
+**Example (полный контекст — требует contextLevel: "full" в манифесте):**
+
+```tsx
+import { useTrackerPluginContext } from '@weavix/tracker-plugin-sdk-react';
+
+function IssuePlugin() {
+  const { theme, language, slotContext } = useTrackerPluginContext('full');
+  // slotContext: Issue | undefined (для слота issue.action)
+
+  return (
+    <div>
+      <h1>Issue: {slotContext?.key}</h1>
+      <p>Version: {slotContext?.version}</p>
+      <p>Theme: {theme}</p>
+    </div>
+  );
+}
+```
+
+**Example (полный контекст с типизацией слота):**
+
+```tsx
+const { slotContext } = useTrackerPluginContext<'issue.action'>('full');
+slotContext?.key; // тип контекста — Issue (из @weavix/tracker-core)
+```
+
+**Example (несколько слотов — сужение по slot):**
+
+```tsx
+const { slot, slotContext } = useTrackerPluginContext('full');
+if (slot === 'issue.action') {
+  slotContext?.key; // здесь slotContext типизирован под слот issue.action
+}
+```
+
+---
+
+### useLocalizedString
+
+Хук для получения локализованной строки на основе текущего языка из контекста [`TrackerPluginProvider`](#trackerpluginprovider).
+
+**Type Signature:**
+
+```typescript
+function useLocalizedString(fallbackLanguage?: string): (value: LocalizedString) => string;
+```
+
+**Parameters:**
+
+- `fallbackLanguage` - `string` (опционально, по умолчанию 'en') - резервный язык, если основной не найден
+
+**Returns:** Функция для локализации строк `(value: LocalizedString) => string`
+
+**Example (базовое использование):**
+
+```tsx
+import { useLocalizedString } from '@weavix/tracker-plugin-sdk-react';
+
+function MyComponent() {
+  const localize = useLocalizedString();
+
+  const field = {
+    name: { ru: 'Имя', en: 'Name' },
+    description: { ru: 'Описание', en: 'Description' },
+  };
+
+  return (
+    <div>
+      <h1>{localize(field.name)}</h1>
+      <p>{localize(field.description)}</p>
+    </div>
+  );
+}
+```
+
+**Example (с резервным языком):**
+
+```tsx
+import { useLocalizedString } from '@weavix/tracker-plugin-sdk-react';
+
+function MyComponent() {
+  // Если перевод на текущем языке не найден, используется русский
+  const localize = useLocalizedString('ru');
+
+  const name = { en: 'Name' }; // нет русского перевода
+
+  return <div>{localize(name)}</div>; // вернет 'Name'
+}
+```
+
+**Example (работа с полями задачи):**
+
+```tsx
+import {
+  useLocalizedString,
+  useTrackerPluginContext,
+} from '@weavix/tracker-plugin-sdk-react';
+import { trackerApi } from '@weavix/tracker-plugin-sdk-react';
+
+function FieldsList() {
+  const localize = useLocalizedString();
+  const { slotContext } = useTrackerPluginContext<'issue.action'>();
+  const [fields, setFields] = useState([]);
+
+  useEffect(() => {
+    trackerApi.v3.get['/fields/...']({ ... }).then(setFields);
+  }, []);
+
+  return (
+    <ul>
+      {fields.map((field) => (
+        <li key={field.id}>
+          <strong>{localize(field.name)}</strong>
+          {field.description && <p>{localize(field.description)}</p>}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+---
+
+## Types
+
+### TrackerPluginProviderProps
+
+Свойства компонента [`TrackerPluginProvider`](#trackerpluginprovider).
+
+```typescript
+interface TrackerPluginProviderProps {
+  /** Дочерние элементы */
+  children: ReactNode;
+
+  /**
+   * Автоматически изменять размер контейнера плагина при изменении содержимого
+   * @default true
+   */
+  autoResize?: boolean;
+
+  /**
+   * Компонент для отображения во время инициализации
+   * @default <PluginLoader />
+   */
+  fallback?: ReactNode;
+
+  /**
+   * Компонент для отображения при ошибке инициализации
+   * @default <PluginError error={error} />
+   */
+  errorFallback?: (error: Error) => ReactNode;
+
+  /**
+   * Автоматически уведомить хост о готовности плагина после инициализации
+   * @default true
+   */
+  autoNotifyReady?: boolean;
+}
+```
+
+**Properties:**
+
+#### `children`
+
+- **Type:** `ReactNode`
+- **Required:** Yes
+- **Description:** Дочерние компоненты, которые будут отрендерены после успешной инициализации
+
+#### `autoResize`
+
+- **Type:** `boolean`
+- **Required:** No
+- **Description:** Автоматически изменять размер контейнера плагина при изменении содержимого. Включает отслеживание изменений DOM и автоматическую отправку новой высоты хосту.
+- **Default:** `true`
+
+**Example:**
+
+```tsx
+<TrackerPluginProvider autoResize={false}>
+  <App />
+</TrackerPluginProvider>
+```
+
+**Note:** Отключайте autoResize, если вы управляете размером контейнера вручную (через доступный в конфигурации API).
+
+#### `fallback`
+
+- **Type:** `ReactNode`
+- **Required:** No
+- **Description:** Компонент, отображаемый во время инициализации плагина
+- **Default:** Встроенный компонент `<PluginLoader />`
+
+**Example:**
+
+```tsx
+<TrackerPluginProvider fallback={<div>Loading...</div>}>
+  <App />
+</TrackerPluginProvider>
+```
+
+#### `errorFallback`
+
+- **Type:** `(error: Error) => ReactNode`
+- **Required:** No
+- **Description:** Функция, возвращающая компонент для отображения при ошибке инициализации
+- **Default:** Встроенный компонент `<PluginError error={error} />`
+
+**Example:**
+
+```tsx
+<TrackerPluginProvider
+  errorFallback={(error) => (
+    <div>
+      <h1>Error!</h1>
+      <p>{error.message}</p>
+    </div>
+  )}
+>
+  <App />
+</TrackerPluginProvider>
+```
+
+#### `autoNotifyReady`
+
+- **Type:** `boolean`
+- **Required:** No
+- **Description:** Автоматически уведомлять хост о готовности плагина после инициализации
+- **Default:** `true`
+
+**Example:**
+
+```tsx
+<TrackerPluginProvider autoNotifyReady={false}>
+  <App />
+</TrackerPluginProvider>
+```
+
+---
+
+### TrackerPluginContextValue
+
+Union-тип: [`BasicTrackerPluginContextValue`](#basictrackerplugincontextvalue) | [`FullTrackerPluginContextValue`](#fulltrackerplugincontextvalue).
+
+```typescript
+type TrackerPluginContextValue<TSlot extends keyof SlotContextMap = keyof SlotContextMap> =
+  | BasicTrackerPluginContextValue<TSlot>
+  | FullTrackerPluginContextValue<TSlot>;
+```
+
+---
+
+### BasicTrackerPluginContextValue
+
+Значение контекста при `contextLevel = 'basic'`. Возвращается хуком [`useTrackerPluginContext()`](#usetrackerplugincontext) или `useTrackerPluginContext('basic')`.
+
+```typescript
+interface BasicTrackerPluginContextValue<TSlot extends keyof SlotContextMap = keyof SlotContextMap> {
+  theme: Theme | undefined;
+  language: string | undefined;
+  service: string;
+  userId?: string;
+  isYateam?: boolean;
+  origin: string;
+  /** Имя слота, в котором открыт плагин */
+  slot: TSlot;
+  innerUrl: string;
+  queryParams: Record<string, string>;
+  /** Контекст страницы — только entityId и entityMeta при basic уровне */
+  slotContext: BasicContext | undefined;
+  registerHandler: RegisterHandlerFunction<TSlot>;
+  /** Уровень контекста — всегда 'basic' */
+  contextLevel: 'basic';
+}
+```
+
+#### `slotContext` (basic)
+
+- **Type:** `BasicContext | undefined`
+- **Description:** Содержит только `entityId` и опциональный `entityMeta`, переданные хостом в параметрах iframe. Доступен без postMessage-запроса.
+
+```typescript
+type BasicContext = {
+  entityId: string;
+  entityMeta?: Record<string, string>;
+};
+```
+
+**Example:**
+
+```tsx
+const { slotContext } = useTrackerPluginContext(); // basic по умолчанию
+console.log(slotContext?.entityId);   // 'QUEUE-123'
+console.log(slotContext?.entityMeta); // { key: 'QUEUE-123' } или undefined
+```
+
+---
+
+### FullTrackerPluginContextValue
+
+Значение контекста при `contextLevel = 'full'`. Возвращается хуком [`useTrackerPluginContext('full')`](#usetrackerplugincontext). Требует `contextLevel: "full"` в манифесте плагина.
+
+```typescript
+interface FullTrackerPluginContextValue<TSlot extends keyof SlotContextMap = keyof SlotContextMap> {
+  theme: Theme | undefined;
+  language: string | undefined;
+  service: string;
+  userId?: string;
+  isYateam?: boolean;
+  origin: string;
+  /** Имя слота, в котором открыт плагин */
+  slot: TSlot;
+  innerUrl: string;
+  queryParams: Record<string, string>;
+  /** Полный контекст слота (Issue, TriggerContext и т.д.) */
+  slotContext: SlotContextMap[TSlot] | undefined;
+  registerHandler: RegisterHandlerFunction<TSlot>;
+  /** Уровень контекста — всегда 'full' */
+  contextLevel: 'full';
+}
+```
+
+#### `slotContext` (full)
+
+- **Type:** `SlotContextMap[TSlot] | undefined`
+- **Description:** Полный контекст слота, полученный через postMessage (`context.get`). Для `'issue.action'` — тип `Issue` из **`@weavix/tracker-core`**.
+
+**Example:**
+
+```tsx
+const { slotContext } = useTrackerPluginContext<'issue.action'>('full');
+console.log(slotContext?.key);     // 'QUEUE-123'
+console.log(slotContext?.version); // 42
+```
+
+#### `theme`
+
+- **Type:** `Theme | undefined` (`'light' | 'light-hc' | 'dark' | 'dark-hc' | 'system'`)
+- **Description:** Текущая тема оформления хоста
+
+**Example:**
+
+```tsx
+const { theme } = useTrackerPluginContext();
+const isDark = theme === 'dark' || theme === 'dark-hc';
+```
+
+#### `language`
+
+- **Type:** `string | undefined`
+- **Description:** Код текущего языка хоста (например, 'ru', 'en')
+
+**Example:**
+
+```tsx
+const { language } = useTrackerPluginContext();
+const greeting = language === 'ru' ? 'Привет' : 'Hello';
+```
+
+#### `slot`
+
+- **Type:** `TSlot` (ключ из `SlotContextMap`)
+- **Description:** Имя слота, в котором открыт плагин (например, `'issue.action'`, `'navigation'`)
+
+#### `contextLevel`
+
+- **Type:** `'basic' | 'full'`
+- **Description:** Уровень контекста, объявленный в манифесте плагина. Определяет тип `slotContext`.
+
+---
+
+
+## Публичное API
+
+Пакет `@weavix/tracker-plugin-sdk-react` реэкспортирует **hostApi**, **trackerApi** и типы из `@weavix/tracker-plugin-sdk`.
+
+- **hostApi** — работа с хостом: инициализация, тема, язык, контекст слота, размер окна, `notifyReady()`. Подробнее в [API Reference tracker-core](../tracker-plugin-external/API_REFERENCE.md#hostapi-hostapi).
+- **trackerApi** — вызовы Tracker Public API через **типизированное API v3**: `trackerApi.v3.get`, `trackerApi.v3.post`, `trackerApi.v3.put`, `trackerApi.v3.patch`, `trackerApi.v3.delete`. Ключи — пути эндпоинтов (с автоподсказкой и JSDoc из `@weavix/tracker-api-types`). Описание методов и форматов: [Common format](https://docs.yandex-team.ru/tracker/common-format).
+
+**Пример:**
+
+```ts
+import { trackerApi } from '@weavix/tracker-plugin-sdk-react';
+
+const issue = await trackerApi.v3.get['/issues/{id}']({
+  pathParams: { id: 'KEY-1' },
+  queryParams: { expand: ['COMMENTS'] },
+});
+```
+
+Тема, язык и контекст слота доступны через [`useTrackerPluginContext`](#usetrackerplugincontext). Инициализация и уведомление хоста — через **hostApi** (или внутри `TrackerPluginProvider`). Вызовы эндпоинтов Tracker — через **trackerApi.v3**.
+
+**Полная документация по API (типы, коды ошибок, утилиты):**
+
+📖 [API Reference — @weavix/tracker-plugin-sdk](../tracker-plugin-external/API_REFERENCE.md)
+
+---
+
+## Утилиты
+
+### getLocalizedString
+
+Получает локализованную строку на основе языка. Полезно для локализации вне React-компонентов или когда нужен прямой контроль над языком.
+
+**Type Signature:**
+
+```typescript
+function getLocalizedString(
+  value: LocalizedString,
+  language: string,
+  fallbackLanguage?: string,
+): string;
+```
+
+**Parameters:**
+
+- `value` - `LocalizedString` - локализованная строка (может быть строкой или объектом с переводами)
+- `language` - `string` - код языка ('ru' или 'en')
+- `fallbackLanguage` - `string` (опционально, по умолчанию 'en') - резервный язык, если основной не найден
+
+**Returns:** `string` - локализованная строка на указанном языке
+
+**Example (базовое использование):**
+
+```tsx
+import { getLocalizedString } from '@weavix/tracker-plugin-sdk-react';
+import type { LocalizedString } from '@weavix/tracker-plugin-sdk-react';
+
+function getFieldName(name: LocalizedString, language: string): string {
+  return getLocalizedString(name, language);
+}
+// language можно получить из useTrackerPluginContext() в компоненте
+
+const name = { ru: 'Название', en: 'Summary' };
+const localizedName = getFieldName(name, 'ru');
+console.log(localizedName); // 'Название'
+```
+
+**Example (с резервным языком):**
+
+```tsx
+import { getLocalizedString } from '@weavix/tracker-plugin-sdk-react';
+
+// Если перевод на русский отсутствует, используется английский
+const partial = { en: 'Name' };
+const name = getLocalizedString(partial, 'ru', 'en');
+console.log(name); // 'Name'
+
+// Если передана простая строка, она возвращается как есть
+const simple = 'Simple string';
+const result = getLocalizedString(simple, 'ru');
+console.log(result); // 'Simple string'
+```
+
+**Example (в обработчике событий):**
+
+```tsx
+import {
+  getLocalizedString,
+  useTrackerPluginContext,
+} from '@weavix/tracker-plugin-sdk-react';
+import type { LocalizedString } from '@weavix/tracker-plugin-sdk-react';
+
+type FieldWithName = { id: string; name: LocalizedString };
+
+function FieldSelector({ fields }: { fields: FieldWithName[] }) {
+  const { language } = useTrackerPluginContext();
+  const handleFieldSelect = (field: FieldWithName) => {
+    const localizedName = getLocalizedString(field.name, language);
+    alert(`Выбрано поле: ${localizedName}`);
+  };
+
+  return (
+    <ul>
+      {fields.map((field) => (
+        <li key={field.id} onClick={() => handleFieldSelect(field)}>
+          {field.id}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+**Примечание:** В React-компонентах предпочтительнее использовать хук [`useLocalizedString`](#uselocalizedstring), который автоматически получает язык из контекста:
+
+```tsx
+import { useLocalizedString } from '@weavix/tracker-plugin-sdk-react';
+
+function MyComponent() {
+  const localize = useLocalizedString();
+  
+  const field = { name: { ru: 'Название', en: 'Title' } };
+  return <div>{localize(field.name)}</div>;
+}
+```
+
+---
+