@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 → COOKBOOK. Core API: tracker-plugin-external.

Установка

npm install @weavix/tracker-plugin-sdk-react

Использование

Инициализация плагина

Оберните приложение в TrackerPluginProvider в корне. Компонент управляет инициализацией, состояниями загрузки и ошибок, а также уведомляет хост о готовности плагина.

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.

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" в манифесте плагина.

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.

Локализация

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>;
}

Кастомные состояния загрузки и ошибок

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

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.

useToaster()

Хук для показа toast-уведомлений в хост-приложении.

Permission: "toaster" в permissions.ui манифеста.

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.

useLocalizedString(fallbackLanguage?)

Возвращает (value: LocalizedString) => string для текущего языка из контекста.

Полная документация

📖 AGENTS.md — вход для агентов.

📖 COOKBOOK — рецепты.

📖 API Reference — Provider, хуки, contextLevel.

📖 README tracker-core — trackerApi, hostApi, типы, ошибки.

Лицензия

UNLICENSED