@weavix/tracker-plugin-sdk-react 0.0.33 → 0.0.34

package/README.md

@@ -2,200 +2,428 @@
 
 React SDK for Tracker plugins (Weavix / npm).
 
-Для удобства написания плагинов:
+Provides `TrackerPluginProvider`, typed `useTrackerPluginContext`, hooks for theme, language, and UI operations. Re-exports `trackerApi`, `hostApi`, `storageApi`, and `uiApi` from [`@weavix/tracker-plugin-sdk`](https://www.npmjs.com/package/@weavix/tracker-plugin-sdk).
 
-Этот пакет предоставляет `TrackerPluginProvider`, хуки, а также реэкспортирует `trackerApi` и `hostApi` из core.
-
-> **Для агентов и AI:** [AGENTS.md](./AGENTS.md) → [COOKBOOK](../../docs/agent/COOKBOOK.md). Core API: [tracker-plugin-external](../tracker-plugin-external/README.md).
-
-## Установка
+## Installation
 
 ```bash
 npm install @weavix/tracker-plugin-sdk-react
 ```
 
-## Использование
-
-### Инициализация плагина
+Peer dependencies: `react >= 18.0.0`, `react-dom >= 18.0.0`.
 
-Оберните приложение в `TrackerPluginProvider` в корне. Компонент управляет инициализацией, состояниями загрузки и ошибок, а также уведомляет хост о готовности плагина.
+## Quick start
 
 ```tsx
-import { TrackerPluginProvider } from '@weavix/tracker-plugin-sdk-react';
 import { createRoot } from 'react-dom/client';
-import { App } from './App';
+import { TrackerPluginProvider, useTrackerPluginContext } from '@weavix/tracker-plugin-sdk-react';
 
-const root = createRoot(document.getElementById('root')!);
+function App() {
+  const { theme, language, slot, slotContext } = useTrackerPluginContext();
 
-root.render(
+  return (
+    <div data-theme={theme}>
+      Slot: {slot}, language: {language}, entityId: {slotContext?.entityId}
+    </div>
+  );
+}
+
+createRoot(document.getElementById('root')!).render(
   <TrackerPluginProvider>
     <App />
-  </TrackerPluginProvider>,
+  </TrackerPluginProvider>
+);
+```
+
+---
+
+## TrackerPluginProvider
+
+Root plugin component. Initialises the bridge, fetches initial values (theme, language, context, userId, orgId), notifies the host that the plugin is ready, and provides context to all child components.
+
+A typed wrapper over `PluginProvider` from `@weavix/sdk-react`: adds Tracker-typed `registerHandler` based on `SlotContextMap`.
+
+```tsx
+import { TrackerPluginProvider, PluginLoader } from '@weavix/tracker-plugin-sdk-react';
+
+root.render(
+  <TrackerPluginProvider
+    autoResize={true}
+    autoNotifyReady={true}
+    fallback={<PluginLoader />}
+    errorFallback={(error) => <div>Error: {error.message}</div>}
+  >
+    <App />
+  </TrackerPluginProvider>
+);
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `autoResize` | `boolean` | `true` | Automatically resize the iframe height when content changes |
+| `autoNotifyReady` | `boolean` | `true` | Send `plugin.ready` to the host after initialisation |
+| `fallback` | `ReactNode` | `undefined` | What to show during initialisation |
+| `errorFallback` | `(error: Error) => ReactNode` | `<PluginError />` | What to show on initialisation error |
+| `children` | `ReactNode` | — | Plugin content |
+
+**Behaviour:**
+- Intercepts clicks on external links and calls `uiApi.navigate`.
+- Protected against double-initialisation in React StrictMode.
+- Wraps the application in an `ErrorBoundary`.
+
+### Manual `notifyReady`
+
+```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>
 );
 ```
 
-### Получение темы, языка и контекста слота (basic)
+---
 
-По умолчанию в манифесте `contextLevel: "basic"` (или поле не задано) — в `slotContext` только `entityId` и опционально `entityMeta`.
+## useTrackerPluginContext(level?)
+
+Main hook for accessing host data. Typed for Tracker — `slotContext` has type `SlotContextMap[TSlot]`. All values are reactive.
 
 ```tsx
 import { useTrackerPluginContext } from '@weavix/tracker-plugin-sdk-react';
 
-function MyComponent() {
+function App() {
+  // basic (default) — slotContext: { entityId, entityMeta? }
   const { theme, language, slot, slotContext } = useTrackerPluginContext();
 
   return (
     <div className={theme}>
-      <p>Язык: {language}</p>
-      <p>Слот: {slot}</p>
-      <p>Сущность: {slotContext?.entityId}</p>
+      <p>Language: {language}</p>
+      <p>Slot: {slot}</p>
+      <p>Entity: {slotContext?.entityId}</p>
     </div>
   );
 }
 ```
 
-### Полный контекст слота (Issue)
+### Full slot context
 
-Требуется `"contextLevel": "full"` в манифесте плагина.
+Requires `contextLevel: "full"` in the plugin manifest.
 
 ```tsx
 import { useTrackerPluginContext } from '@weavix/tracker-plugin-sdk-react';
 
 function IssuePlugin() {
   const { slotContext } = useTrackerPluginContext<'issue.action'>('full');
+  // slotContext: Issue | undefined
 
   return (
     <div>
-      <h1>Задача: {slotContext?.key}</h1>
-      <p>Версия: {slotContext?.version}</p>
+      <h1>Issue: {slotContext?.key}</h1>
+      <p>Status: {slotContext?.status?.key}</p>
+      <p>Version: {slotContext?.version}</p>
     </div>
   );
 }
 ```
 
-Тип `Issue` в контексте слота — из **`@weavix/tracker-core`** (реэкспорт из core). Типы ответов **`trackerApi.v3`** — из **`@weavix/tracker-api-types`**.
+### contextLevel in the manifest
 
-### Локализация
+| Manifest | `useTrackerPluginContext()` | `useTrackerPluginContext('full')` |
+|----------|---------------------------|----------------------------------|
+| `contextLevel: "basic"` (default) | `slotContext: BasicContext \| undefined` | **runtime error** |
+| `contextLevel: "full"` | `slotContext: BasicContext \| undefined` | `slotContext: SlotContextMap[TSlot] \| undefined` |
 
-```tsx
-import { useLocalizedString } from '@weavix/tracker-plugin-sdk-react';
+### Return value
 
-function MyComponent() {
-  const localize = useLocalizedString();
+**`BasicTrackerPluginContextValue<TSlot>`** (`level: 'basic'`):
 
-  const field = {
-    name: { ru: 'Название', en: 'Summary' },
-  };
+| Field | Type | Description |
+|-------|------|-------------|
+| `theme` | `Theme \| undefined` | Current theme (`'light'`, `'dark'`, `'light-hc'`, `'dark-hc'`, `'system'`) |
+| `language` | `string \| undefined` | Current language (`'ru'`, `'en'`, ...) |
+| `slot` | `TSlot` | Current slot name |
+| `service` | `string` | Service identifier |
+| `origin` | `string` | Host origin |
+| `innerUrl` | `string` | Plugin URL |
+| `queryParams` | `Record<string, string>` | Plugin query parameters |
+| `userId` | `string \| undefined` | Current user ID |
+| `orgId` | `string \| undefined` | Organisation ID |
+| `isYateam` | `boolean \| undefined` | Yandex-Team environment flag |
+| `isOrbita` | `boolean \| undefined` | Orbita flag |
+| `contextLevel` | `'basic'` | Context level from the manifest |
+| `slotContext` | `BasicContext \| undefined` | `{ entityId, entityMeta? }` |
+| `registerHandler` | `RegisterHandlerFunction<TSlot>` | Register a Tracker-typed handler for host RPC |
+
+**`FullTrackerPluginContextValue<TSlot>`** (`level: 'full'`): same fields, but `slotContext: SlotContextMap[TSlot] | undefined`.
+
+### registerHandler
 
-  return <h1>{localize(field.name)}</h1>;
+Registers a Tracker-typed handler for incoming host RPC requests.
+
+```tsx
+function App() {
+  const { registerHandler } = useTrackerPluginContext<'issue.action'>();
+
+  useEffect(() => {
+    // For 'getData', the handler type is derived from GetDataResultMap[TSlot]
+    registerHandler('getData', () => ({
+      key: 'QUEUE-1',
+      summary: 'Data from plugin',
+    }));
+  }, [registerHandler]);
+
+  return <div>...</div>;
 }
 ```
 
-### Кастомные состояния загрузки и ошибок
+---
+
+## Hooks
+
+### `useTheme()`
 
 ```tsx
-import { TrackerPluginProvider } from '@weavix/tracker-plugin-sdk-react';
+import { useTheme } from '@weavix/tracker-plugin-sdk-react';
 
-root.render(
-  <TrackerPluginProvider
-    autoResize={false}
-    fallback={<div>Загрузка...</div>}
-    errorFallback={(error) => <div>Ошибка: {error.message}</div>}
-    autoNotifyReady={false}
-  >
-    <App />
-  </TrackerPluginProvider>,
-);
+const theme = useTheme(); // 'light' | 'dark' | 'light-hc' | 'dark-hc' | 'system' | undefined
 ```
 
-### Ручной вызов `notifyReady`
+### `useLanguage()`
 
 ```tsx
-import { TrackerPluginProvider, hostApi } from '@weavix/tracker-plugin-sdk-react';
-import { useEffect } from 'react';
+import { useLanguage } from '@weavix/tracker-plugin-sdk-react';
 
-function App() {
-  useEffect(() => {
-    initializeApp().then(() => {
-      hostApi.notifyReady();
+const language = useLanguage(); // 'ru' | 'en' | ... | undefined
+```
+
+### `useToaster()`
+
+Show toast notifications in the host application.
+
+> **Permission:** Requires `"toaster"` in `permissions.ui` of the plugin manifest.
+
+```tsx
+import { useToaster } from '@weavix/tracker-plugin-sdk-react';
+
+function SaveButton() {
+  const toaster = useToaster();
+
+  const handleSave = async () => {
+    await save();
+    toaster.add({ title: 'Saved', theme: 'success' });
+  };
+
+  return <button onClick={handleSave}>Save</button>;
+}
+```
+
+Returns `{ add: (options: ToastOptions) => Promise<{ name: string }> }`.
+
+**`ToastOptions`:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `title` | `string` | — | Toast title (required, max 200 chars) |
+| `name` | `string` | auto | Unique key for deduplication |
+| `theme` | `'success' \| 'danger' \| 'warning' \| 'info'` | `'info'` | Theme |
+| `content` | `string` | — | Body text (max 500 chars) |
+| `autoHiding` | `number` | `5000` | Display time in ms (1000–30000) |
+| `isClosable` | `boolean` | `true` | Show close button |
+| `actions` | `ToastAction[]` | — | Action buttons (max 2): `{ label: string; onClick: () => void }` |
+
+### `useConfirm()`
+
+Show a confirmation dialog.
+
+> **Permission:** Requires `"confirm"` in `permissions.ui` of the plugin manifest.
+
+```tsx
+import { useConfirm } from '@weavix/tracker-plugin-sdk-react';
+
+function DeleteButton() {
+  const confirm = useConfirm();
+
+  const handleDelete = async () => {
+    const { confirmed } = await confirm.show({
+      title: 'Delete issue?',
+      message: 'This action cannot be undone.',
+      theme: 'danger',
     });
-  }, []);
+    if (confirmed) {
+      await deleteItem();
+    }
+  };
 
-  return <div>My Plugin</div>;
+  return <button onClick={handleDelete}>Delete</button>;
 }
+```
+
+Returns `{ show: (options: ConfirmOptions) => Promise<ConfirmResult> }`.
+
+**`ConfirmOptions`:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `message` | `string` | — | Dialog body text (required) |
+| `title` | `string` | — | Dialog title |
+| `textButtonApply` | `string` | — | Confirm button label |
+| `textButtonCancel` | `string` | — | Cancel button label |
+| `theme` | `'normal' \| 'danger'` | `'normal'` | Confirm button theme |
+
+### `useLocalizedString(fallbackLanguage?)`
+
+Returns a resolver function that resolves a `LocalizedString` based on the current host language.
+
+```tsx
+import { useLocalizedString } from '@weavix/tracker-plugin-sdk-react';
+
+function Label({ text }: { text: { ru: string; en: string } }) {
+  const t = useLocalizedString();
+  return <span>{t(text)}</span>;
+}
+```
+
+### `useIsOrbita()`
+
+```tsx
+import { useIsOrbita } from '@weavix/tracker-plugin-sdk-react';
+
+const isOrbita = useIsOrbita(); // boolean | undefined
+```
+
+---
+
+## Components
+
+### `PluginLoader`
+
+Built-in loading indicator to display during initialisation.
+
+```tsx
+import { TrackerPluginProvider, PluginLoader } from '@weavix/tracker-plugin-sdk-react';
 
 root.render(
-  <TrackerPluginProvider autoNotifyReady={false}>
+  <TrackerPluginProvider fallback={<PluginLoader />}>
     <App />
-  </TrackerPluginProvider>,
+  </TrackerPluginProvider>
 );
 ```
 
-## Компоненты
+No props.
 
-### `TrackerPluginProvider`
+### `PluginError`
 
-Оборачивает приложение и управляет жизненным циклом плагина.
+Built-in component for displaying an initialisation error.
 
-**Props:**
+```tsx
+import { PluginError } from '@weavix/tracker-plugin-sdk-react';
 
-| Prop              | Тип                           | По умолчанию       | Описание                                                        |
-| ----------------- | ----------------------------- | ------------------ | --------------------------------------------------------------- |
-| `autoResize`      | `boolean`                     | `true`             | Автоматически изменять размер контейнера при изменении контента |
-| `fallback`        | `ReactNode`                   | `<PluginLoader />` | Отображается во время инициализации                             |
-| `errorFallback`   | `(error: Error) => ReactNode` | `<PluginError />`  | Отображается при ошибке инициализации                           |
-| `autoNotifyReady` | `boolean`                     | `true`             | Автоматически уведомлять хост о готовности плагина              |
+<TrackerPluginProvider errorFallback={(error) => <PluginError error={error} />}>
+  <App />
+</TrackerPluginProvider>
+```
 
-## Хуки
+| Prop | Type | Description |
+|------|------|-------------|
+| `error` | `Error` | Error to display |
 
-### `useTrackerPluginContext<TSlot>(level?)`
+---
 
-Возвращает тему, язык, имя слота и контекст слота.
+## Common patterns
 
-- **`level: 'basic'`** (по умолчанию) — `slotContext`: `{ entityId, entityMeta? }`
-- **`level: 'full'`** — полный контекст слота (`Issue` для `issue.action`); нужен `contextLevel: "full"` в манифесте
+### Theme-aware rendering
 
-**Возвращает:** `{ theme, language, slot, slotContext, registerHandler }`
+```tsx
+function App() {
+  const theme = useTheme();
+  return (
+    <div className={`app app--${theme ?? 'light'}`}>
+      ...
+    </div>
+  );
+}
+```
 
-Подробнее: [API Reference — useTrackerPluginContext](./API_REFERENCE.md#usetrackerplugincontext).
+### Localised strings
 
-### `useToaster()`
+```tsx
+const LABELS = {
+  save: { ru: 'Сохранить', en: 'Save' },
+  cancel: { ru: 'Отмена', en: 'Cancel' },
+};
 
-Хук для показа toast-уведомлений в хост-приложении.
+function Form() {
+  const t = useLocalizedString();
+  return (
+    <form>
+      <button type="submit">{t(LABELS.save)}</button>
+      <button type="button">{t(LABELS.cancel)}</button>
+    </form>
+  );
+}
+```
 
-> **Permission:** `"toaster"` в `permissions.ui` манифеста.
+### Reading the current issue (full context)
 
 ```tsx
-import { useToaster } from '@weavix/tracker-plugin-sdk-react';
+function IssueActions() {
+  const { slotContext: issue } = useTrackerPluginContext<'issue.action'>('full');
+  // issue: Issue | undefined
 
-function MyComponent() {
-  const toaster = useToaster();
+  if (!issue) return null;
 
-  const handleSave = async () => {
-    await saveData();
-    toaster.add({ title: 'Сохранено', theme: 'success' });
-  };
-
-  return <button onClick={handleSave}>Сохранить</button>;
+  return (
+    <div>
+      <h2>{issue.key}: {issue.summary}</h2>
+      <p>Queue: {issue.queue?.key}</p>
+      <p>Assignee: {issue.assignee?.login}</p>
+    </div>
+  );
 }
 ```
 
-Параметры `add(options)` — в [README tracker-core](../tracker-plugin-external/README.md#тосты-toast-notifications).
+### Calling the Tracker API
 
-### `useLocalizedString(fallbackLanguage?)`
+```tsx
+import { trackerApi } from '@weavix/tracker-plugin-sdk-react';
 
-Возвращает `(value: LocalizedString) => string` для текущего языка из контекста.
+function IssueList() {
+  const [issues, setIssues] = useState([]);
 
-## Полная документация
+  useEffect(() => {
+    trackerApi.v3.post['/v2/issues/_search']({
+      bodyParams: { filter: { queue: 'MYQUEUE' } },
+    }).then(({ data }) => setIssues(data));
+  }, []);
 
-📖 [AGENTS.md](./AGENTS.md) — вход для агентов.
+  return <ul>{issues.map(i => <li key={i.id}>{i.summary}</li>)}</ul>;
+}
+```
 
-📖 [COOKBOOK](../../docs/agent/COOKBOOK.md) — рецепты.
+---
 
-📖 [API Reference](./API_REFERENCE.md) — Provider, хуки, contextLevel.
+## Related packages
 
-📖 [README tracker-core](../tracker-plugin-external/README.md) — `trackerApi`, `hostApi`, типы, ошибки.
+| Package | Purpose |
+|---------|---------|
+| [`@weavix/tracker-plugin-sdk`](https://www.npmjs.com/package/@weavix/tracker-plugin-sdk) | Core SDK: `trackerApi`, `hostApi`, `storageApi` |
+| [`@weavix/tracker-api-types`](https://www.npmjs.com/package/@weavix/tracker-api-types) | Tracker Public API v3 types |
+| [`@weavix/sdk-react`](https://www.npmjs.com/package/@weavix/sdk-react) | Base React wrapper |
+| [`@weavix/sdk-core`](https://www.npmjs.com/package/@weavix/sdk-core) | Base runtime |
 
-## Лицензия
+## License
 
-UNLICENSED
+SEE LICENSE IN LICENSE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weavix/tracker-plugin-sdk-react",
-  "version": "0.0.33",
+  "version": "0.0.34",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -23,14 +23,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@weavix/tracker-plugin-sdk": "^0.0.33",
-    "@weavix/sdk-core": "^0.0.35",
-    "@weavix/sdk-react": "^0.0.35",
-    "@weavix/tracker-core": "^0.0.33"
+    "@weavix/tracker-plugin-sdk": "^0.0.34",
+    "@weavix/sdk-core": "^0.0.39",
+    "@weavix/sdk-react": "^0.0.39",
+    "@weavix/tracker-core": "^0.0.34"
   },
   "peerDependencies": {
     "react": "^18.0.0",
-    "@weavix/tracker-core": "^0.0.33"
+    "@weavix/tracker-core": "^0.0.34"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "*",