@docyrus/ui-pro-ai-assistant 0.1.3 → 0.1.5

package/README.md

@@ -0,0 +1,407 @@
+# @docyrus/ui-pro-ai-assistant
+
+A full-featured, drop-in AI assistant chat UI for React. Ships with multi-turn conversations, a work canvas, project management, multi-model and multi-agent support, voice input, file uploads, deep research, and built-in i18n for 9 languages.
+
+## Highlights
+
+- **Plug-and-play chat interface** — Modal or inline rendering with a single component.
+- **Work canvas** — AI-generated outputs (text, code, spreadsheets, images, charts, documents) are rendered in type-specific viewers side-by-side with the conversation.
+- **Projects & sessions** — Organize conversations into projects, manage threads, and persist context.
+- **Multi-model & multi-agent** — Let users switch between AI models and agent deployments on the fly.
+- **Deep research** — Extended research mode with live progress streaming.
+- **AI memories** — Persistent memory management across sessions.
+- **Voice input** — Browser-native speech-to-text.
+- **File uploads** — Attach files to messages with configurable format restrictions.
+- **i18n** — English, German, Spanish, French, Italian, Portuguese, Greek, Slovenian, Turkish.
+- **Vite plugin** — Optional dev-server middleware for Plate editor AI commands.
+
+## Installation
+
+```bash
+npm install @docyrus/ui-pro-ai-assistant
+```
+
+### Peer dependencies
+
+```bash
+npm install @docyrus/api-client @docyrus/ui-pro-shared react react-dom
+```
+
+| Peer | Version |
+|------|---------|
+| `@docyrus/api-client` | `>= 0.1.0` |
+| `@docyrus/ui-pro-shared` | `>= 0.0.1` |
+| `react` | `^19` |
+| `react-dom` | `^19` |
+| `vite` | `>= 5.0.0` *(optional)* |
+
+## Quick start
+
+```tsx
+import "@docyrus/ui-pro-ai-assistant/styles.css";
+
+import { useCallback, useMemo } from "react";
+import { useDocyrusAuth } from "@docyrus/signin";
+import { AssistantProvider, DocyAssistant } from "@docyrus/ui-pro-ai-assistant";
+
+function App() {
+  const { client, status } = useDocyrusAuth();
+
+  const getAuthToken = useCallback(async () => {
+    const token = await client?.getAccessToken();
+    if (!token) throw new Error("No access token available");
+    return token;
+  }, [client]);
+
+  const config = useMemo(() => ({
+    apiBaseUrl: "https://api.docyrus.com/v1",
+    getAuthToken,
+  }), [getAuthToken]);
+
+  if (status !== "authenticated" || !client) {
+    return <p>Authenticating...</p>;
+  }
+
+  return (
+    <AssistantProvider config={config}>
+      <DocyAssistant
+        tenantAiAgentId="your-agent-id"
+        renderMode="inline"
+        enableSidebar
+        enableNavDropdown
+        className="h-full w-full"
+      />
+    </AssistantProvider>
+  );
+}
+```
+
+### Modal mode
+
+```tsx
+function ModalExample() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setOpen(true)}>Open Assistant</button>
+      <AssistantProvider config={config}>
+        <DocyAssistant
+          tenantAiAgentId="your-agent-id"
+          renderMode="modal"
+          isOpen={open}
+          onClose={() => setOpen(false)}
+        />
+      </AssistantProvider>
+    </>
+  );
+}
+```
+
+## Exports
+
+| Entry point | Import path | Description |
+|-------------|-------------|-------------|
+| Main | `@docyrus/ui-pro-ai-assistant` | Components, provider, hooks, and types |
+| Vite plugin | `@docyrus/ui-pro-ai-assistant/vite` | Dev-server middleware for Plate AI |
+| Web worker | `@docyrus/ui-pro-ai-assistant/worker` | Worker entry for AI command handlers |
+| Stylesheet | `@docyrus/ui-pro-ai-assistant/styles.css` | Required CSS — import once at app root |
+
+### Exported symbols
+
+```ts
+// Components
+import { DocyAssistant } from "@docyrus/ui-pro-ai-assistant";
+
+// Provider & config
+import {
+  AssistantProvider,
+  useAssistantConfig,
+} from "@docyrus/ui-pro-ai-assistant";
+
+// i18n
+import {
+  AssistantI18nProvider,
+  useAssistantTranslation,
+} from "@docyrus/ui-pro-ai-assistant";
+
+// Types
+import type {
+  AssistantConfig,
+  AssistantUser,
+  Project,
+  Work,
+  WorkTypes,
+} from "@docyrus/ui-pro-ai-assistant";
+
+// Vite plugin (separate entry)
+import { plateEditorPlugin } from "@docyrus/ui-pro-ai-assistant/vite";
+```
+
+## API reference
+
+### `<AssistantProvider>`
+
+Wraps your component tree to provide API configuration context. Must be an ancestor of `<DocyAssistant>`.
+
+```tsx
+<AssistantProvider config={config}>
+  {children}
+</AssistantProvider>
+```
+
+#### `AssistantConfig`
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `apiBaseUrl` | `string` | Yes | Base API URL, e.g. `"https://api.docyrus.com/v1"` |
+| `getAuthToken` | `() => Promise<string>` | Yes | Async callback returning a valid Bearer token |
+| `user` | `AssistantUser \| null` | No | Current user info for display |
+| `getDataSourceSchema` | `(id: string) => Promise<DataSourceSchema \| null>` | No | Resolver for data source schemas |
+
+#### `AssistantUser`
+
+```ts
+interface AssistantUser {
+  id: string;
+  email?: string;
+  firstname?: string;
+  lastname?: string;
+  photo?: string;
+}
+```
+
+---
+
+### `<DocyAssistant>`
+
+The main chat interface component.
+
+#### Core
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tenantAiAgentId` | `string` | — | **Required.** ID of the tenant AI agent |
+| `renderMode` | `"modal" \| "inline"` | `"modal"` | Render as overlay dialog or embedded inline |
+| `isOpen` | `boolean` | — | Modal visibility (modal mode only) |
+| `onClose` | `() => void` | — | Called when the modal closes |
+| `className` | `string` | — | CSS class on the root element |
+
+#### Appearance
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | — | Header title |
+| `description` | `string` | — | Subtitle below the title |
+| `placeholder` | `string` | — | Chat input placeholder |
+| `logo` | `string` | — | Logo image URL |
+| `footerText` | `string` | — | Footer text |
+| `theme` | `"auto" \| "light" \| "dark"` | `"auto"` | Color theme |
+| `variant` | `"default" \| "docked" \| "expanded"` | `"default"` | Layout variant |
+| `size` | `"default" \| "large"` | `"default"` | Component size |
+
+#### Layout
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `enableSidebar` | `boolean` | `true` | Show the session list sidebar |
+| `enableNavDropdown` | `boolean` | `false` | Show navigation dropdown |
+| `defaultFullscreen` | `boolean` | `false` | Start in fullscreen |
+| `hideExpand` | `boolean` | `false` | Hide the fullscreen toggle |
+| `maxMessages` | `number` | — | Max messages to keep in context |
+
+#### Features
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `supportWebSearch` | `boolean` | `true` | Web search |
+| `supportThinking` | `boolean` | `true` | Thinking / reasoning mode |
+| `supportFiles` | `boolean` | `true` | File uploads |
+| `supportDocumentSearch` | `boolean` | `true` | Document search |
+| `supportDeepResearch` | `boolean` | `true` | Deep research mode |
+| `supportMultiModels` | `boolean` | `true` | Model selector |
+| `supportWorkCanvas` | `boolean` | `true` | Work canvas panel |
+| `supportedFileFormats` | `string[]` | — | Allowed upload MIME types / extensions |
+| `enableVoice` | `boolean` | `false` | Voice input mode |
+| `enableMicrophone` | `boolean` | `true` | Microphone button |
+
+#### Agent selection
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `agentSelectorUrl` | `string` | `"/ai/agent-deployments"` | Deployment selector endpoint |
+| `baseAgentSelectorUrl` | `string` | `"/ai/agent-deployments/base"` | Base agent selector endpoint |
+| `onAgentChange` | `(agentId: string, agentType: "base" \| "deployment") => void` | — | Fires when the active agent changes |
+
+#### API
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiEndpoint` | `string` | `"/ai/agents/:agentId/chat"` | Chat endpoint template (`:agentId` is replaced at runtime) |
+
+#### Callbacks
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `onMessageSend` | `(message: string) => void` | Fires when a message is sent |
+| `onVoiceStart` | `() => void` | Fires when voice recording starts |
+| `onVoiceEnd` | `() => void` | Fires when voice recording ends |
+
+---
+
+### `useAssistantConfig()`
+
+Returns the `AssistantConfig` from the nearest `AssistantProvider`. Throws if used outside the provider.
+
+```tsx
+const { apiBaseUrl, getAuthToken } = useAssistantConfig();
+```
+
+---
+
+### `useAssistantTranslation()`
+
+Returns the `t` function for translating assistant UI strings.
+
+```tsx
+const { t } = useAssistantTranslation();
+// t("common.untitled") → "Untitled"
+```
+
+---
+
+### `plateEditorPlugin()`
+
+Vite plugin that adds dev-server middleware for Plate editor AI commands (`/api/ai/command` and `/api/ai/copilot`). Only needed if you use the Plate rich-text editor AI features.
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { plateEditorPlugin } from "@docyrus/ui-pro-ai-assistant/vite";
+
+export default defineConfig({
+  plugins: [plateEditorPlugin()],
+});
+```
+
+## Work canvas types
+
+AI-generated outputs open in a side canvas with type-specific viewers:
+
+| `WorkTypes` value | Viewer | Description |
+|-------------------|--------|-------------|
+| `Text` | Plate.js rich editor | Editable rich text |
+| `Code` | Sandpack | Live code preview |
+| `Data` / `Xlsx` | Univer spreadsheet | Full spreadsheet with formulas |
+| `Image` | Image viewer | Generated images |
+| `Chart` | VChart | Interactive charts |
+| `Html` / `HtmlTemplate` | HTML iframe | Rendered HTML |
+| `Docyment` / `Docx` / `Pptx` | Document viewer | Office document preview |
+| `App` | App renderer | Custom applications |
+| `Record` | Record view | Structured data display |
+| `DataSource` | Data explorer | Data source output |
+| `CustomQuerySql` / `CustomQueryJson` | Query result | Query output display |
+
+## Internationalization
+
+9 built-in locales: `en`, `de`, `es`, `fr`, `it`, `pt`, `el`, `sl`, `tr`.
+
+The language is auto-detected. To override, wrap with `AssistantI18nProvider`:
+
+```tsx
+import { AssistantI18nProvider } from "@docyrus/ui-pro-ai-assistant";
+
+<AssistantI18nProvider locale="de">
+  <DocyAssistant ... />
+</AssistantI18nProvider>
+```
+
+## Types
+
+### `Project`
+
+```ts
+interface Project {
+  id: string;
+  name: string;
+  tenant_ai_agent_id: string;
+  description?: string;
+  instructions?: string;
+  tenant_ai_agent_deployment_id?: string;
+  color?: string;
+  icon?: string;
+  shared_to?: string[];
+  created_by?: string;
+}
+```
+
+### `Work`
+
+```ts
+interface Work {
+  id: string;
+  title: string;
+  type?: WorkTypes;
+  content_json?: unknown;
+  content_text?: string;
+  description?: string;
+  image_url?: string;
+  core_ai_model_id?: string | null;
+  base_message_id?: string;
+  base_thread_id?: string;
+  tenant_ai_agent_id?: string;
+  tenant_ai_agent_deployment_id?: string;
+  tenant_data_source_id?: string;
+  tenant_ai_project_id?: string;
+  shared_to?: string[];
+  created_by?: string;
+  created_on?: Date;
+  last_modified_on?: Date;
+}
+```
+
+### `WorkTypes`
+
+```ts
+const WorkTypes = {
+  Record: "record",
+  Data: "data",
+  Text: "text",
+  Code: "code",
+  Image: "image",
+  Xlsx: "xlsx",
+  Docx: "docx",
+  Pptx: "pptx",
+  Html: "html",
+  Docyment: "docyment",
+  Chart: "chart",
+  DataSource: "data_source",
+  HtmlTemplate: "html_template",
+  CustomQuerySql: "custom_query_sql",
+  CustomQueryJson: "custom_query_json",
+  App: "app",
+} as const;
+```
+
+## Environment variables
+
+When using with Vite, set these in your `.env`:
+
+```env
+VITE_DOCYRUS_API_URL=https://api.docyrus.com
+VITE_DOCYRUS_CLIENT_ID=your-client-id
+VITE_DOCYRUS_AGENT_ID=your-agent-id
+
+# Optional — for Plate editor AI plugin
+VITE_DOCYRUS_EDITOR_AGENT_ID=your-editor-agent-id
+```
+
+## Requirements
+
+- React 19+
+- ESM only (`"type": "module"`)
+- Tailwind CSS v4 (the stylesheet uses Tailwind utilities)
+
+## License
+
+MIT