docuservix chat

Reviewed-on: #6
Co-authored-by: Arswarog <arswarog@yandex.ru>
Co-committed-by: Arswarog <arswarog@yandex.ru>

CLAUDE.md

@@ -11,11 +11,13 @@ Docuservix docs — шаблон документационного сайта
 
 ## Commands
 
-- `npm start` — dev-сервер
+Используется **yarn**.
-- `npm run build` — production-сборка в `build/`
+
-- `npm run typecheck` — проверка типов (tsc)
+- `yarn start` — dev-сервер
-- `npm run prettier:check` — проверка форматирования
+- `yarn build` — production-сборка в `build/`
-- `npm run prettier:fix` — автоформатирование
+- `yarn typecheck` — проверка типов (tsc)
+- `yarn prettier:check` — проверка форматирования
+- `yarn prettier:fix` — автоформатирование
 
 ## Architecture
 

docusaurus.config.ts

@@ -35,7 +35,7 @@ const config: Config = {
     markdown: {
         mermaid: true,
     },
-    plugins: [docuservix],
+    plugins: [docuservix()],
     themes: ['@docusaurus/theme-mermaid'],
 
     // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future

package.json

@@ -48,7 +48,9 @@
         "js-yaml": "^4.2.0",
         "prism-react-renderer": "^2.3.0",
         "react": "^19.0.0",
-        "react-dom": "^19.0.0"
+        "react-dom": "^19.0.0",
+        "react-markdown": "^10.1.0",
+        "remark-gfm": "^4.0.1"
     },
     "devDependencies": {
         "@docusaurus/module-type-aliases": "3.10.1",

plugins/docuservix/entities/markdown/MD.module.css

@@ -0,0 +1,59 @@
+.MD p:last-child {
+    margin-bottom: 0;
+}
+
+.MD p:first-child {
+    margin-top: 0;
+}
+
+.MD code {
+    padding: 0.15em 0.4em;
+    border-radius: 4px;
+    background: var(--ifm-color-emphasis-200);
+    font-size: 0.85em;
+}
+
+.MD pre {
+    margin: 0.5em 0;
+    padding: 0.75em;
+    overflow-x: auto;
+    border-radius: 6px;
+    background: var(--ifm-color-emphasis-100);
+}
+
+.MD pre code {
+    padding: 0;
+    background: none;
+}
+
+.MD ul,
+.MD ol {
+    padding-left: 1.5em;
+    margin: 0.5em 0;
+}
+
+.MD table {
+    width: 100%;
+    margin: 0.5em 0;
+    border-collapse: collapse;
+    font-size: 0.9em;
+}
+
+.MD th,
+.MD td {
+    padding: 0.4em 0.75em;
+    border: 1px solid var(--ifm-color-emphasis-300);
+    text-align: left;
+}
+
+.MD th {
+    background: var(--ifm-color-emphasis-100);
+    font-weight: var(--ifm-font-weight-semibold);
+}
+
+.MD blockquote {
+    margin: 0.5em 0;
+    padding: 0.25em 1em;
+    border-left: 3px solid var(--ifm-color-emphasis-300);
+    color: var(--ifm-color-emphasis-700);
+}

plugins/docuservix/entities/markdown/MD.tsx

@@ -0,0 +1,17 @@
+import React, { ReactNode } from 'react';
+import Markdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+
+import styles from './MD.module.css';
+
+interface MDProps {
+    children: string;
+}
+
+export function MD({ children }: MDProps): ReactNode {
+    return (
+        <div className={styles.MD}>
+            <Markdown remarkPlugins={[remarkGfm]}>{children}</Markdown>
+        </div>
+    );
+}

plugins/docuservix/entities/markdown/index.ts

@@ -0,0 +1 @@
+export { MD } from './MD';

plugins/docuservix/hooks/useChat.ts

@@ -0,0 +1,88 @@
+import { useLocation } from '@docusaurus/router';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { useOptions } from '@docuservix/hooks/useOptions';
+import { IChat, IChatMessage, IChatSource } from '@docuservix/models/chat';
+
+interface UseChatResult {
+    dialog: IChat;
+    typing: boolean;
+    statusMessage?: string;
+    sendMessage: (text: string) => void;
+}
+
+function useQuery(): string {
+    const location = useLocation();
+    const params = new URLSearchParams(location.search);
+
+    return params.get('q') ?? '';
+}
+
+export function useChat(): UseChatResult {
+    const chatEndpoint = useOptions().api + '/chat';
+    const urlQuery = useQuery();
+
+    const [messages, setMessages] = useState<IChatMessage[]>([]);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+
+    const initialSentRef = useRef(false);
+    const messagesEndRef = useRef(messages);
+
+    messagesEndRef.current = messages;
+
+    const sendMessage = useCallback(
+        async (text: string) => {
+            const content = text.trim();
+
+            if (!content) {
+                return;
+            }
+
+            const userMessage: IChatMessage = { role: 'user', content };
+            const newHistory = [...messagesEndRef.current, userMessage];
+
+            setMessages(newHistory);
+            setLoading(true);
+            setError(null);
+
+            try {
+                const res = await fetch(chatEndpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ messages: newHistory }),
+                });
+
+                if (!res.ok) {
+                    throw new Error(`HTTP ${res.status}`);
+                }
+
+                const data: { answer: string; sources?: IChatSource[] } = await res.json();
+
+                setMessages((prev) => [
+                    ...prev,
+                    { role: 'assistant', content: data.answer, sources: data.sources },
+                ]);
+            } catch (err) {
+                setError(err instanceof Error ? err.message : 'Ошибка при обращении к серверу');
+            } finally {
+                setLoading(false);
+            }
+        },
+        [chatEndpoint],
+    );
+
+    useEffect(() => {
+        if (urlQuery && !initialSentRef.current) {
+            initialSentRef.current = true;
+            sendMessage(urlQuery);
+        }
+    }, [urlQuery, sendMessage]);
+
+    return {
+        dialog: { messages },
+        typing: loading,
+        statusMessage: error ?? undefined,
+        sendMessage,
+    };
+}

plugins/docuservix/hooks/useOptions.ts

@@ -0,0 +1,7 @@
+import { usePluginData } from '@docusaurus/useGlobalData';
+
+import { DocuservixOptions } from '@docuservix/models/docuservix';
+
+export function useOptions(): DocuservixOptions {
+    return usePluginData('docuservix') as DocuservixOptions;
+}

plugins/docuservix/index.ts

@@ -2,7 +2,12 @@ import path from 'path';
 
 import type { LoadContext, Plugin } from '@docusaurus/types';
 
-function pluginDocuservix(_context: LoadContext): Plugin {
+import { DocuservixOptions } from '@docuservix/models/docuservix';
+
+export default function docuservix(options: Partial<DocuservixOptions> = {}) {
+    const { api = '/api' } = options;
+
+    return function pluginDocuservix(_context: LoadContext): Plugin {
         return {
             name: 'docuservix',
 
@@ -17,7 +22,11 @@ function pluginDocuservix(_context: LoadContext): Plugin {
             },
 
             async contentLoaded({ actions }) {
-            const { addRoute } = actions;
+                const { addRoute, setGlobalData } = actions;
+
+                setGlobalData({
+                    api,
+                });
 
                 addRoute({
                     path: '/chat',
@@ -26,6 +35,5 @@ function pluginDocuservix(_context: LoadContext): Plugin {
                 });
             },
         };
+    };
 }
-
-export default pluginDocuservix;

plugins/docuservix/models/chat.ts

@@ -2,7 +2,36 @@ export interface IChat {
     messages: IChatMessage[];
 }
 
+export interface IChatSource {
+    file: string;
+    heading: string;
+    anchor: string;
+    score: number;
+}
+
 export interface IChatMessage {
     role: 'user' | 'assistant';
     content: string;
+    sources?: IChatSource[];
+}
+
+function stripNumericPrefixes(p: string): string {
+    return p
+        .split('/')
+        .map((seg) => seg.replace(/^\d+-/, ''))
+        .join('/');
+}
+
+export function sourceToUrl(file: string, anchor: string): string {
+    let p = file.replace(/^docs\//, '').replace(/\.md$/, '');
+
+    p = stripNumericPrefixes(p);
+
+    return `/docs/${p}${anchor ? `#${anchor}` : ''}`;
+}
+
+export function sourceToPath(file: string): string {
+    const p = file.replace(/^docs\//, '').replace(/\.md$/, '');
+
+    return stripNumericPrefixes(p);
 }

plugins/docuservix/models/docuservix.ts

@@ -0,0 +1,3 @@
+export interface DocuservixOptions {
+    api?: string;
+}

plugins/docuservix/pages/chat/ChatPage.tsx

@@ -1,30 +1,20 @@
 import Layout from '@theme/Layout';
 import { ReactNode } from 'react';
 
-import { IChat } from '@docuservix/models/chat';
+import { useChat } from '@docuservix/hooks/useChat';
 import { Chat } from '@docuservix/widgets/chat';
 
-const dialog: IChat = {
-    messages: [
-        {
-            role: 'user',
-            content: 'Can you show me some CSS animations? It can be simple tools like chatbots...',
-        },
-        {
-            role: 'assistant',
-            content: "Hello! I'm your AI assistant. How can I help you today?",
-        },
-    ],
-};
-
 export function ChatPage(): ReactNode {
+    const { dialog, typing, statusMessage, sendMessage } = useChat();
+
     return (
         <Layout title="Чат">
             <main className="container margin-vert--lg">
                 <Chat
                     dialog={dialog}
-                    statusMessage="Unable to connect to the server"
+                    typing={typing}
-                    typing
+                    statusMessage={statusMessage}
+                    onSend={sendMessage}
                 />
             </main>
         </Layout>

plugins/docuservix/widgets/chat/Chat.tsx

@@ -29,7 +29,7 @@ export function Chat({ dialog, typing, statusMessage, onSend }: ChatProps): Reac
             />
             {statusMessage && <div className={b('statusMessage')}>{statusMessage}</div>}
             <Input
-                loading={typing}
+                disabled={typing}
                 onSend={onSend}
             />
         </div>

plugins/docuservix/widgets/chat/Input.tsx

@@ -7,17 +7,17 @@ import styles from './Input.module.css';
 const b = block(styles, 'Input');
 
 interface InputProps {
-    loading?: boolean;
+    disabled?: boolean;
     onSend?: (text: string) => void;
 }
 
-export function Input({ loading, onSend }: InputProps): ReactNode {
+export function Input({ disabled, onSend }: InputProps): ReactNode {
     const [input, setInput] = useState('');
 
     const handleSend = () => {
         const text = input.trim();
 
-        if (!text || loading) {
+        if (!text || disabled) {
             return;
         }
 
@@ -41,12 +41,12 @@ export function Input({ loading, onSend }: InputProps): ReactNode {
                 onKeyDown={handleKeyDown}
                 placeholder="Type your message here..."
                 rows={1}
-                disabled={loading}
+                disabled={disabled}
             />
             <button
                 className={b('send')}
                 onClick={handleSend}
-                disabled={loading || !input.trim()}
+                disabled={disabled || !input.trim()}
             >
                 <PaperPlaneIcon />
             </button>

plugins/docuservix/widgets/chat/Message.module.css

@@ -1,5 +1,5 @@
 .Message {
-    max-width: 85%;
+    max-width: 90%;
     animation: slideIn 0.3s ease-out;
 }
 
@@ -34,8 +34,37 @@
     border-bottom-right-radius: 0.25rem;
 }
 
-@media (min-width: 576px) {
+.Message__sources {
+    margin-top: 8px;
+    padding: 8px 1rem 0;
+    border-top: 1px solid var(--ifm-color-emphasis-200);
+}
+
+.Message__sourcesLabel {
+    margin-bottom: 4px;
+    color: var(--ifm-color-emphasis-600);
+    font-weight: var(--ifm-font-weight-semibold);
+    font-size: 0.75rem;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+}
+
+.Message__sourceLink {
+    display: block;
+    overflow: hidden;
+    color: var(--ifm-color-primary);
+    font-size: 0.8rem;
+    white-space: nowrap;
+    text-decoration: none;
+    text-overflow: ellipsis;
+}
+
+.Message__sourceLink:hover {
+    text-decoration: underline;
+}
+
+@media (max-width: 576px) {
     .Message {
-        max-width: 75%;
+        max-width: 100%;
     }
 }

plugins/docuservix/widgets/chat/Message.tsx

@@ -1,6 +1,11 @@
+import Link from '@docusaurus/Link';
 import block from 'bem-css-modules';
 import React, { ReactNode } from 'react';
 
+import { MD } from '@docuservix/entities/markdown';
+
+import { IChatSource, sourceToPath, sourceToUrl } from '@docuservix/models/chat';
+
 import styles from './Message.module.css';
 
 const b = block(styles, 'Message');
@@ -8,12 +13,30 @@ const b = block(styles, 'Message');
 interface MessageProps {
     role: 'user' | 'assistant';
     content: string;
+    sources?: IChatSource[];
 }
 
-export function Message({ role, content }: MessageProps): ReactNode {
+export function Message({ role, content, sources }: MessageProps): ReactNode {
     return (
         <div className={b({ role })}>
-            <div className={b('content')}>{content}</div>
+            <div className={b('content')}>
+                <MD>{content}</MD>
+            </div>
+
+            {sources && sources.length > 0 && (
+                <div className={b('sources')}>
+                    <div className={b('sourcesLabel')}>Источники:</div>
+                    {sources.map((src, j) => (
+                        <Link
+                            key={j}
+                            to={sourceToUrl(src.file, src.anchor)}
+                            className={b('sourceLink')}
+                        >
+                            {src.heading || sourceToPath(src.file)}
+                        </Link>
+                    ))}
+                </div>
+            )}
         </div>
     );
 }

plugins/docuservix/widgets/chat/Messages.tsx

@@ -21,6 +21,7 @@ export function Messages({ messages, typing }: MessagesProps): ReactNode {
                     key={i}
                     role={msg.role}
                     content={msg.content}
+                    sources={msg.sources}
                 />
             ))}
 

yarn.lock

@@ -7308,6 +7308,11 @@ html-tags@^3.3.1:
   resolved "https://registry.yarnpkg.com/html-tags/-/html-tags-3.3.1.tgz#a04026a18c882e4bba8a01a3d39cfe465d40b5ce"
   integrity sha512-ztqyC3kLto0e9WbNp0aeP+M3kTt+nbaIveGmUxAtZa+8iFgKLUOD4YKM5j+f3QD89bra7UeumolZHKuOXnTmeQ==
 
+html-url-attributes@^3.0.0:
+  version "3.0.1"
+  resolved "https://registry.yarnpkg.com/html-url-attributes/-/html-url-attributes-3.0.1.tgz#83b052cd5e437071b756cd74ae70f708870c2d87"
+  integrity sha512-ol6UPyBWqsrO6EJySPz2O7ZSr856WDrEzM5zMqp+FJJLGMW35cLYmmZnl0vztAZxRUoNZJFTCohfjuIJ8I4QBQ==
+
 html-void-elements@^3.0.0:
   version "3.0.0"
   resolved "https://registry.yarnpkg.com/html-void-elements/-/html-void-elements-3.0.0.tgz#fc9dbd84af9e747249034d4d62602def6517f1d7"
@@ -10556,6 +10561,23 @@ react-loadable-ssr-addon-v5-slorber@^1.0.3:
   dependencies:
     "@types/react" "*"
 
+react-markdown@^10.1.0:
+  version "10.1.0"
+  resolved "https://registry.yarnpkg.com/react-markdown/-/react-markdown-10.1.0.tgz#e22bc20faddbc07605c15284255653c0f3bad5ca"
+  integrity sha512-qKxVopLT/TyA6BX3Ue5NwabOsAzm0Q7kAPwq6L+wWDwisYs7R8vZ0nRXqq6rkueboxpkjvLGU9fWifiX/ZZFxQ==
+  dependencies:
+    "@types/hast" "^3.0.0"
+    "@types/mdast" "^4.0.0"
+    devlop "^1.0.0"
+    hast-util-to-jsx-runtime "^2.0.0"
+    html-url-attributes "^3.0.0"
+    mdast-util-to-hast "^13.0.0"
+    remark-parse "^11.0.0"
+    remark-rehype "^11.0.0"
+    unified "^11.0.0"
+    unist-util-visit "^5.0.0"
+    vfile "^6.0.0"
+
 react-router-config@^5.1.1:
   version "5.1.1"
   resolved "https://registry.yarnpkg.com/react-router-config/-/react-router-config-5.1.1.tgz#0f4263d1a80c6b2dc7b9c1902c9526478194a988"
@@ -10809,7 +10831,7 @@ remark-frontmatter@^5.0.0:
     micromark-extension-frontmatter "^2.0.0"
     unified "^11.0.0"
 
-remark-gfm@^4.0.0:
+remark-gfm@^4.0.0, remark-gfm@^4.0.1:
   version "4.0.1"
   resolved "https://registry.yarnpkg.com/remark-gfm/-/remark-gfm-4.0.1.tgz#33227b2a74397670d357bf05c098eaf8513f0d6b"
   integrity sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==