@weavix/sdk-react 0.0.39 → 0.0.40

package/README.md

@@ -1,49 +1,433 @@
 # @weavix/sdk-react
 
-Generic plugin SDK React package — framework-agnostic `PluginProvider`, hooks, and components.
-
-Automatically includes [`@weavix/sdk-core`](https://www.npmjs.com/package/@weavix/sdk-core) as a dependency.
+React wrapper for [`@weavix/sdk-core`](https://www.npmjs.com/package/@weavix/sdk-core). Provides a provider component and reactive hooks for theme, language, slot context, and UI operations.
 
 ## Installation
 
 ```bash
 npm install @weavix/sdk-react
-# @weavix/sdk-core is installed automatically
 ```
 
-## Usage
+Peer dependencies: `react >= 18.0.0`, `react-dom >= 18.0.0`.
+
+## Quick start
 
 ```tsx
-import { PluginProvider, usePluginContext } from '@weavix/sdk-react';
+import { createRoot } from 'react-dom/client';
+import { PluginProvider, usePluginContext, useTheme } from '@weavix/sdk-react';
 
-// Wrap your app
-root.render(
+function App() {
+  const { slot, language } = usePluginContext();
+  const theme = useTheme();
+
+  return <div data-theme={theme}>Slot: {slot}, language: {language}</div>;
+}
+
+createRoot(document.getElementById('root')!).render(
   <PluginProvider>
     <App />
-  </PluginProvider>,
+  </PluginProvider>
+);
+```
+
+---
+
+## PluginProvider
+
+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.
+
+```tsx
+import { PluginProvider, PluginLoader } from '@weavix/sdk-react';
+
+root.render(
+  <PluginProvider
+    autoResize={true}
+    autoNotifyReady={true}
+    fallback={<PluginLoader />}
+    errorFallback={(error) => <div>Error: {error.message}</div>}
+  >
+    <App />
+  </PluginProvider>
 );
+```
+
+### 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 (`<a href>`, `data-href`) and calls `uiApi.navigate`, preventing direct navigation from the iframe.
+- Protected against double-initialisation in React StrictMode.
+- Wraps the application in an `ErrorBoundary`.
+
+---
+
+## Hooks
+
+### `usePluginContext(level?)`
+
+Main hook for accessing host data. All values are reactive — they update when push events are received from the host.
+
+```tsx
+import { usePluginContext } from '@weavix/sdk-react';
 
-// Use in components
 function App() {
-  const { slot, slotContext, theme, language, registerHandler } = usePluginContext();
+  // basic (default) — slotContext contains only { entityId }
+  const { theme, language, slot, slotContext, userId, orgId } = usePluginContext();
 
-  return <div>Slot: {slot}</div>;
+  // full — slotContext contains the full slot object
+  const { slotContext: fullCtx } = usePluginContext('full');
 }
+```
+
+> Requires `contextLevel: "full"` in the plugin manifest for the `'full'` level. Throws at runtime if there is a mismatch.
+
+**Return value (`PluginContextValue`):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `theme` | `Theme \| undefined` | Current theme (`'light'`, `'dark'`, `'light-hc'`, `'dark-hc'`, `'system'`) |
+| `language` | `string \| undefined` | Current language (`'ru'`, `'en'`, ...) |
+| `slot` | `string` | 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' \| 'full'` | Context level declared in the manifest |
+| `slotContext` | `BasicContext \| unknown \| undefined` | Slot context |
+| `registerHandler` | `RegisterHandlerFunction` | Register a handler for incoming host RPC requests |
+
+**`BasicContext`** (when `contextLevel: 'basic'`):
+
+```typescript
+{ entityId: string; entityMeta?: Record<string, string> }
+```
+
+### `useTheme()`
+
+Reactive current host theme. Updates on `theme.changed`.
 
-// Full context (requires contextLevel: "full" in manifest)
-function AppFull() {
-  const { slotContext } = usePluginContext('full');
-  // slotContext: unknown — cast to your type
-  const ctx = slotContext as { entityId: string };
-  return <div>Entity: {ctx.entityId}</div>;
+```tsx
+import { useTheme } from '@weavix/sdk-react';
+
+function App() {
+  const theme = useTheme(); // 'light' | 'dark' | 'light-hc' | 'dark-hc' | 'system' | undefined
+  return <div data-theme={theme}>...</div>;
 }
 ```
 
-## What's included
+### `useLanguage()`
+
+Reactive current host language. Updates on `language.changed`.
+
+```tsx
+import { useLanguage } from '@weavix/sdk-react';
+
+const language = useLanguage(); // 'ru' | 'en' | ... | undefined
+```
+
+### `useUserId()`
+
+Reactive current user ID. Updates on `userId.changed`.
+
+```tsx
+import { useUserId } from '@weavix/sdk-react';
+
+const userId = useUserId(); // string | undefined
+```
+
+### `useOrgId()`
+
+Reactive organisation ID. Updates on `orgId.changed`.
+
+```tsx
+import { useOrgId } from '@weavix/sdk-react';
+
+const orgId = useOrgId(); // string | undefined
+```
+
+### `useIsYateam()`
+
+Reactive Yandex-Team environment flag. Updates on `isYateam.changed`.
+
+```tsx
+import { useIsYateam } from '@weavix/sdk-react';
+
+const isYateam = useIsYateam(); // boolean | undefined
+```
+
+### `useIsOrbita()`
+
+Reactive Orbita flag. Updates on `isOrbita.changed`.
+
+```tsx
+import { useIsOrbita } from '@weavix/sdk-react';
+
+const isOrbita = useIsOrbita(); // boolean | undefined
+```
+
+### `useToaster()`
+
+Hook for showing toast notifications in the host application.
+
+> **Permission:** Requires `"toaster"` in `permissions.ui` of the plugin manifest.
+
+```tsx
+import { useToaster } from '@weavix/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()`
+
+Hook for showing a confirmation dialog.
+
+> **Permission:** Requires `"confirm"` in `permissions.ui` of the plugin manifest.
+
+```tsx
+import { useConfirm } from '@weavix/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 <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/sdk-react';
+
+function Label({ text }: { text: { ru: string; en: string } }) {
+  const t = useLocalizedString();
+  return <span>{t(text)}</span>;
+}
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `fallbackLanguage` | `string` | `'ru'` | Fallback language if the current language is not resolved |
+
+Returns `(value: LocalizedString) => string`.
+
+### `usePluginBootstrap(options?)`
+
+Low-level bootstrap hook. Use it when `PluginProvider` does not fit your use case (e.g. custom lifecycle or non-standard rendering).
+
+```tsx
+import { usePluginBootstrap } from '@weavix/sdk-react';
+
+function Root() {
+  const { loading, error, theme, language, context, host } = usePluginBootstrap({ autoResize: true });
+
+  if (loading) return <Spinner />;
+  if (error) return <div>Error: {error}</div>;
+
+  return <App theme={theme} language={language} context={context} host={host} />;
+}
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `autoResize` | `boolean` | `true` | Automatically resize the iframe height |
+
+**Returns `PluginBootstrapState<TContext>`:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `host` | `HostApi<TContext>` | Isolated `HostApi` instance (not the global `hostApi`) |
+| `loading` | `boolean` | `true` until initialisation completes |
+| `error` | `string \| null` | Error message or `null` |
+| `theme` | `Theme \| undefined` | Current theme |
+| `language` | `string \| undefined` | Current language |
+| `context` | `TContext \| undefined` | Slot context (only when `contextLevel: 'full'`) |
+| `userId` | `string \| undefined` | User ID |
+| `orgId` | `string \| undefined` | Organisation ID |
+| `isYateam` | `boolean \| undefined` | Yandex-Team flag |
+| `isOrbita` | `boolean \| undefined` | Orbita flag |
+
+---
+
+## Components
+
+### `PluginLoader`
+
+Built-in loading indicator to display during initialisation.
+
+```tsx
+import { PluginProvider, PluginLoader } from '@weavix/sdk-react';
+
+root.render(
+  <PluginProvider fallback={<PluginLoader />}>
+    <App />
+  </PluginProvider>
+);
+```
+
+No props.
+
+### `PluginError`
+
+Built-in component for displaying an initialisation error. Used as the default `errorFallback` in `PluginProvider`.
+
+```tsx
+import { PluginError } from '@weavix/sdk-react';
+
+<PluginProvider errorFallback={(error) => <PluginError error={error} />}>
+  <App />
+</PluginProvider>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `error` | `Error` | Error to display |
+
+### `ErrorBoundary`
+
+React Error Boundary. Can be used independently to wrap parts of the application.
+
+```tsx
+import { ErrorBoundary, PluginError } from '@weavix/sdk-react';
+
+<ErrorBoundary fallback={(error) => <PluginError error={error} />}>
+  <RiskyComponent />
+</ErrorBoundary>
+```
+
+---
+
+## Utilities
+
+### `isInternalUrl(url)`
+
+Checks whether a URL is internal (same origin as the plugin).
+
+```typescript
+import { isInternalUrl } from '@weavix/sdk-react';
+
+isInternalUrl('/local/path');      // true
+isInternalUrl('https://ext.com'); // false
+```
+
+---
+
+## Common patterns
+
+### Theme-aware rendering
+
+```tsx
+function App() {
+  const theme = useTheme();
+  return (
+    <div className={`app app--${theme ?? 'light'}`}>
+      ...
+    </div>
+  );
+}
+```
+
+### Localised strings
+
+```tsx
+const LABELS = {
+  save: { ru: 'Сохранить', en: 'Save' },
+  cancel: { ru: 'Отмена', en: 'Cancel' },
+};
+
+function Form() {
+  const t = useLocalizedString();
+  return (
+    <form>
+      <button type="submit">{t(LABELS.save)}</button>
+      <button type="button">{t(LABELS.cancel)}</button>
+    </form>
+  );
+}
+```
+
+### Registering a host RPC handler
+
+```tsx
+function App() {
+  const { registerHandler } = usePluginContext();
+
+  useEffect(() => {
+    registerHandler('getData', () => ({ version: '1.0', status: 'ready' }));
+  }, [registerHandler]);
+
+  return <div>...</div>;
+}
+```
+
+---
+
+## Related packages
+
+| Package | Purpose |
+|---------|---------|
+| [`@weavix/sdk-core`](https://www.npmjs.com/package/@weavix/sdk-core) | Base runtime (hostApi, uiApi, storageApi, events) |
+| [`@weavix/tracker-plugin-sdk`](https://www.npmjs.com/package/@weavix/tracker-plugin-sdk) | Typed wrapper for Tracker plugins |
+| [`@weavix/tracker-plugin-sdk-react`](https://www.npmjs.com/package/@weavix/tracker-plugin-sdk-react) | React integration for Tracker plugins |
+
+## License
 
-- **`PluginProvider`** — initializes the plugin, manages lifecycle, provides context
-- **`usePluginContext()`** — hook for accessing theme, language, slot, slotContext, registerHandler
-- **`isInternalUrl()`** — utility for checking if a URL is internal
-- **Hooks**: `useTheme`, `useLanguage`, `useIsYateam`, `useUserId`, `useOrgId`, `useIsOrbita`, `useConfirm`, `useToaster`, `useLocalizedString`
-- **Components**: `PluginError`, `PluginLoader`, `ErrorBoundary`
-- **Re-exports from `@weavix/sdk-core`**: `hostApi`, `uiApi`, `on`, `dispatchHostEvent`, error codes, types
+SEE LICENSE IN LICENSE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weavix/sdk-react",
-  "version": "0.0.39",
+  "version": "0.0.40",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -14,7 +14,7 @@
   ],
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "@weavix/sdk-core": "0.0.39"
+    "@weavix/sdk-core": "0.0.40"
   },
   "peerDependencies": {
     "react": "^18.0.0"