telygent-ui 0.1.2 → 0.1.4

package/README.md

@@ -0,0 +1,147 @@
+# telygent-ui
+
+A shadcn-style component registry + CLI for Telygent UI.
+
+## CLI workflow
+
+```bash
+npx telygent-ui setup
+npx telygent-ui add chat-interface
+```
+
+## Adapter pattern
+
+Wrap your app with `ChatProvider` and supply an adapter using your data library of choice.
+
+```tsx
+import {ChatProvider, type SendMessageInput, type SendMessageResult, type ChatMessage} from "@/components/ai/ChatProvider";
+import {ChatInterface} from "@/components/ai/ChatInterface";
+
+const adapter = {
+  async sendMessage({message, conversationId}: SendMessageInput): Promise<SendMessageResult> {
+    // Use React Query, Axios, RTK Query, etc.
+    const response = await api.send({message, conversationId});
+    return {
+      conversationId: response.conversationId,
+      message: {
+        role: "assistant",
+        content: response.content,
+        createdAt: new Date(),
+        visualizations: response.visualizations,
+      },
+    };
+  },
+  async getHistory(conversationId: string): Promise<ChatMessage[]> {
+    const history = await api.history(conversationId);
+    return history.messages.map((item) => ({
+      role: item.role === "assistant" ? "assistant" : "user",
+      content: item.content,
+      createdAt: new Date(item.timestamp),
+      visualizations: item.visualizations ?? [],
+      summaryCards: item.summaryCards ?? [],
+    }));
+  },
+};
+
+export default function Page() {
+  const conversationId = "your-conversation-id";
+  return (
+    <ChatProvider adapter={adapter}>
+      <ChatInterface conversationId={conversationId} aiName="Telygent" />
+    </ChatProvider>
+  );
+}
+```
+
+## SSE adapter example
+
+If your backend streams SSE updates, implement `sendMessageStream`:
+
+```tsx
+import {ChatProvider, type SendMessageInput, type ChatStreamEvent} from "@/components/ai/ChatProvider";
+import {ChatInterface} from "@/components/ai/ChatInterface";
+
+async function* streamChat(input: SendMessageInput): AsyncIterable<ChatStreamEvent> {
+  const response = await fetch("/api/chat/stream", {
+    method: "POST",
+    headers: {"Content-Type": "application/json"},
+    body: JSON.stringify({
+      question: input.message,
+      conversationId: input.conversationId,
+    }),
+  });
+
+  if (!response.body) {
+    throw new Error("No stream body");
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  const flush = async function* () {
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith("data:")) continue;
+      const payload = trimmed.replace(/^data:\s*/, "");
+      if (!payload) continue;
+      yield JSON.parse(payload) as ChatStreamEvent;
+    }
+  };
+
+  while (true) {
+    const {value, done} = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, {stream: true});
+    for await (const event of flush()) {
+      yield event;
+    }
+  }
+}
+
+const adapter = {
+  async sendMessage() {
+    throw new Error("sendMessage not used when streaming");
+  },
+  sendMessageStream: streamChat,
+};
+
+export default function Page() {
+  return (
+    <ChatProvider adapter={adapter}>
+      <ChatInterface conversationId="conv_123" />
+    </ChatProvider>
+  );
+}
+```
+
+## RTK Query SSE example
+
+If you already have an RTK Query SSE endpoint, you can bridge it with the helper hook:
+
+```tsx
+import {ChatProvider} from "@/components/ai/ChatProvider";
+import {ChatInterface} from "@/components/ai/ChatInterface";
+import {useRtkStreamAdapter} from "@/components/ai/hooks/use-rtk-stream-adapter";
+import {useSendAiStreamMessageQuery} from "@/redux/api/generalApi";
+
+export default function Page({conversationId}: {conversationId: string}) {
+  const {sendMessageStream} = useRtkStreamAdapter({useSendAiStreamMessageQuery});
+
+  return (
+    <ChatProvider adapter={{sendMessageStream} as any}>
+      <ChatInterface conversationId={conversationId} />
+    </ChatProvider>
+  );
+}
+```
+
+## Styles
+
+Import the MDX styles once (for example in your global CSS):
+
+```css
+@import "@/components/ai/ai-mdx.css";
+```

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "telygent-ui",
-  "version": "0.1.2",
+  "version": "0.1.4",
+  "description": "Telygent UI CLI",
   "type": "commonjs",
+  "main": "dist/index.js",
   "bin": {
     "telygent-ui": "dist/index.js"
   },
@@ -9,5 +11,14 @@
     "dist",
     "registry"
   ],
+  "keywords": [
+    "telygent",
+    "ui",
+    "cli"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {}
 }

package/registry/components/ChatInterface.tsx

@@ -8,7 +8,7 @@ import * as echarts from "echarts";
 import type {EChartsOption} from "echarts";
 
 import {cn} from "@/lib/utils";
-import {type ChatMessage, type ChatVisualization} from "./ChatProvider";
+import {type ChatMessage, type ChatSummaryCard, type ChatVisualization} from "./ChatProvider";
 import {useDatabaseChat} from "../hooks/use-database-chat";
 
 const MemoizedAIWriter = React.memo(({children}: {children: React.ReactNode}) => {
@@ -55,25 +55,59 @@ const renderVisualization = (viz: ChatVisualization, key: string) => {
   );
 };
 
-const renderMessageWithVisualizations = (
+const renderSummaryCard = (card: ChatSummaryCard, key: string) => {
+  const trendTone =
+    card.trend === "up"
+      ? "text-emerald-600"
+      : card.trend === "down"
+      ? "text-rose-600"
+      : "text-slate-600";
+
+  return (
+    <div
+      key={key}
+      className="rounded-2xl border border-slate-200 bg-white/95 p-4 shadow-[0_10px_24px_rgba(15,23,42,0.08)]"
+    >
+      <p className="text-xs uppercase tracking-wide text-slate-400">{card.title}</p>
+      <div className="mt-2 flex items-end justify-between gap-3">
+        <p className="text-2xl font-semibold text-slate-900">{card.value}</p>
+        {card.delta ? (
+          <p className={cn("text-xs font-semibold", trendTone)}>{card.delta}</p>
+        ) : null}
+      </div>
+      {card.subtitle ? (
+        <p className="mt-1 text-sm text-slate-500">{card.subtitle}</p>
+      ) : null}
+    </div>
+  );
+};
+
+const renderMessageWithRichContent = (
   message: string,
   visualizations: ChatVisualization[],
+  summaryCards: ChatSummaryCard[],
   isLatest: boolean
 ) => {
-  const placeholderRegex = /\[\[viz:([^\]]+)\]\]/g;
+  const placeholderRegex = /\[\[(viz|card):([^\]]+)\]\]/g;
   const vizById = new Map(
     visualizations
       .filter((viz) => viz.id)
       .map((viz) => [viz.id as string, viz])
   );
+  const cardsById = new Map(
+    summaryCards
+      .filter((card) => card.id)
+      .map((card) => [card.id as string, card])
+  );
   const usedVizIds = new Set<string>();
+  const usedCardIds = new Set<string>();
 
   let match: RegExpExecArray | null;
   let lastIndex = 0;
   const parts: React.ReactNode[] = [];
 
   while ((match = placeholderRegex.exec(message)) !== null) {
-    const [placeholder, id] = match;
+    const [placeholder, type, id] = match;
     const start = match.index;
     const end = start + placeholder.length;
 
@@ -92,10 +126,20 @@ const renderMessageWithVisualizations = (
       }
     }
 
-    const viz = vizById.get(id);
-    if (viz) {
-      usedVizIds.add(id);
-      parts.push(renderVisualization(viz, `viz-${id}-${start}`));
+    if (type === "viz") {
+      const viz = vizById.get(id);
+      if (viz) {
+        usedVizIds.add(id);
+        parts.push(renderVisualization(viz, `viz-${id}-${start}`));
+      }
+    }
+
+    if (type === "card") {
+      const card = cardsById.get(id);
+      if (card) {
+        usedCardIds.add(id);
+        parts.push(renderSummaryCard(card, `card-${id}-${start}`));
+      }
     }
 
     lastIndex = end;
@@ -115,12 +159,16 @@ const renderMessageWithVisualizations = (
   }
 
   const unused = visualizations.filter((viz) => !viz.id || !usedVizIds.has(viz.id));
-  if (unused.length) {
+  const unusedCards = summaryCards.filter((card) => !card.id || !usedCardIds.has(card.id));
+  if (unused.length || unusedCards.length) {
     parts.push(
       <div key="viz-unused" className="mt-4 space-y-4">
         {unused.map((viz, vizIndex) =>
           renderVisualization(viz, `viz-unused-${viz.id ?? vizIndex}`)
         )}
+        {unusedCards.map((card, cardIndex) =>
+          renderSummaryCard(card, `card-unused-${card.id ?? cardIndex}`)
+        )}
       </div>
     );
   }
@@ -198,7 +246,7 @@ export function ChatInterface({
             className={cn(
               "ml-12 rounded-3xl rounded-tl-sm border border-slate-200 bg-white/90 p-4 shadow-[0_12px_30px_rgba(0,0,0,0.08)]",
               item.status === "thinking"
-                ? "min-h-[76px] max-h-[76px] overflow-y-auto"
+                ? "min-h-[76px] h-auto overflow-y-auto"
                 : ""
             )}
           >
@@ -209,10 +257,12 @@ export function ChatInterface({
                   <span>Thinking…</span>
                 </p>
               ) : null}
-              {item.visualizations && item.visualizations.length > 0
-                ? renderMessageWithVisualizations(
+              {(item.visualizations && item.visualizations.length > 0) ||
+              (item.summaryCards && item.summaryCards.length > 0)
+                ? renderMessageWithRichContent(
                     item.content,
-                    item.visualizations,
+                    item.visualizations ?? [],
+                    item.summaryCards ?? [],
                     timeline.length === index + 1
                   )
                 : timeline.length === index + 1

package/registry/components/ChatProvider.tsx

@@ -11,12 +11,22 @@ export type ChatVisualization = {
   options?: unknown;
 };
 
+export type ChatSummaryCard = {
+  id?: string;
+  title: string;
+  value: string;
+  subtitle?: string;
+  trend?: "up" | "down" | string;
+  delta?: string;
+};
+
 export type ChatMessage = {
   id?: string;
   role: ChatMessageRole;
   content: string;
   createdAt?: Date;
   visualizations?: ChatVisualization[];
+  summaryCards?: ChatSummaryCard[];
   phase?: "thinking" | "final" | "error";
   status?: string;
   meta?: Record<string, unknown>;
@@ -42,6 +52,7 @@ export type ChatStreamEvent = {
   content?: string;
   conversationId?: string;
   visualizations?: ChatVisualization[];
+  summaryCards?: ChatSummaryCard[];
   meta?: Record<string, unknown>;
   tool_calls?: unknown[];
   softCap?: number;

package/registry/hooks/use-database-chat.ts

@@ -54,7 +54,12 @@ export function useDatabaseChat(options: UseDatabaseChatOptions) {
       setLoadingHistory(true);
       const history = await adapter.getHistory(conversationId);
       if (history && history.length > 0) {
-        setTimeline(history);
+        const normalized = history.map((item) => ({
+          ...item,
+          visualizations: item.visualizations ?? [],
+          summaryCards: (item as any).summaryCards ?? (item as any).summary_cards ?? [],
+        }));
+        setTimeline(normalized);
       }
     } finally {
       setLoadingHistory(false);
@@ -110,6 +115,7 @@ export function useDatabaseChat(options: UseDatabaseChatOptions) {
                 phase: event.phase,
                 status: event.status,
                 visualizations: event.visualizations ?? [],
+                summaryCards: event.summaryCards ?? [],
                 meta: event.meta,
                 toolCalls: event.tool_calls ?? [],
                 softCap: event.softCap,

package/registry/hooks/use-rtk-stream-adapter.ts

@@ -30,7 +30,7 @@ export function useRtkStreamAdapter({useSendAiStreamMessageQuery}: UseRtkStreamA
           queueRef.current = resolve;
         });
         yield next;
-        if (next.phase === "final" || next.phase === "error") {
+        if (next.status === "final" || next.status === "error") {
           break;
         }
       }