@netbirdio/explain 0.1.0

package/src/client/AIChatBot.tsx

@@ -0,0 +1,309 @@
+"use client";
+
+import {
+  Bot,
+  MessageCircleQuestion,
+  Send,
+  Sparkles,
+  User,
+  X,
+} from "lucide-react";
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import type { Message } from "../types";
+import * as S from "./styles";
+
+type Props = {
+  open: boolean;
+  onClose: () => void;
+  initialQuery: string;
+  endpoint: string;
+  apiKey?: string;
+};
+
+async function fetchAIResponse(
+  endpoint: string,
+  apiKey: string | undefined,
+  messages: Message[],
+): Promise<string> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (apiKey) {
+    headers["Authorization"] = `Bearer ${apiKey}`;
+  }
+
+  const response = await fetch(endpoint, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      messages: messages.map((m) => ({
+        role: m.role,
+        content: m.content,
+      })),
+    }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`${response.status}: ${text}`);
+  }
+
+  const data = await response.json();
+  return data.reply;
+}
+
+export default function AIChatBot({
+  open,
+  onClose,
+  initialQuery,
+  endpoint,
+  apiKey,
+}: Props) {
+  const [messages, setMessages] = useState<Message[]>([]);
+  const [input, setInput] = useState("");
+  const [isTyping, setIsTyping] = useState(false);
+  const messagesEndRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const hasProcessedInitialQuery = useRef(false);
+
+  const scrollToBottom = useCallback(() => {
+    messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });
+  }, []);
+
+  useEffect(() => {
+    scrollToBottom();
+  }, [messages, isTyping, scrollToBottom]);
+
+  const getAIResponse = useCallback(
+    async (allMessages: Message[]) => {
+      setIsTyping(true);
+      try {
+        const reply = await fetchAIResponse(endpoint, apiKey, allMessages);
+        const response: Message = {
+          id: Date.now().toString(),
+          role: "assistant",
+          content: reply,
+        };
+        setMessages((prev) => [...prev, response]);
+      } catch (err) {
+        const errorMsg =
+          err instanceof Error ? err.message : "Unknown error";
+        const response: Message = {
+          id: Date.now().toString(),
+          role: "assistant",
+          content: `Sorry, I couldn't get a response. Error: ${errorMsg}`,
+        };
+        setMessages((prev) => [...prev, response]);
+      } finally {
+        setIsTyping(false);
+      }
+    },
+    [endpoint, apiKey],
+  );
+
+  // Handle initial query from explain mode
+  useEffect(() => {
+    if (open && initialQuery && !hasProcessedInitialQuery.current) {
+      hasProcessedInitialQuery.current = true;
+
+      const lines = initialQuery.split("\n");
+      const userMessage = lines[0];
+      const docsLine = lines.find((l) => l.startsWith("Docs: "));
+
+      const msgs: Message[] = [];
+
+      if (docsLine) {
+        msgs.push({
+          id: Date.now().toString() + "-ctx",
+          role: "context",
+          content: docsLine,
+        });
+      }
+
+      msgs.push({
+        id: Date.now().toString(),
+        role: "user",
+        content: userMessage,
+      });
+
+      setMessages(msgs);
+      getAIResponse(msgs);
+    }
+  }, [open, initialQuery, getAIResponse]);
+
+  // Reset when closed
+  useEffect(() => {
+    if (!open) {
+      hasProcessedInitialQuery.current = false;
+      setMessages([]);
+      setInput("");
+      setIsTyping(false);
+    }
+  }, [open]);
+
+  // Focus input when opened
+  useEffect(() => {
+    if (open) {
+      setTimeout(() => inputRef.current?.focus(), 200);
+    }
+  }, [open]);
+
+  const sendMessage = useCallback(() => {
+    const text = input.trim();
+    if (!text || isTyping) return;
+
+    const userMsg: Message = {
+      id: Date.now().toString(),
+      role: "user",
+      content: text,
+    };
+    const updatedMessages = [...messages, userMsg];
+    setMessages(updatedMessages);
+    setInput("");
+    getAIResponse(updatedMessages);
+  }, [input, isTyping, messages, getAIResponse]);
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      sendMessage();
+    }
+  };
+
+  if (!open) return null;
+
+  const active = !!input.trim() && !isTyping;
+
+  return (
+    <div style={S.chatPanel}>
+      {/* Header */}
+      <div style={S.chatHeader}>
+        <div style={S.chatHeaderLeft}>
+          <div style={S.chatHeaderIcon}>
+            <Sparkles size={15} style={{ color: "var(--nb-explain-accent)" }} />
+          </div>
+          <div>
+            <h3 style={S.chatHeaderTitle}>AI Assistant</h3>
+            <span style={S.chatHeaderSubtitle}>Ask anything</span>
+          </div>
+        </div>
+        <button
+          onClick={onClose}
+          style={S.chatCloseBtn}
+          onMouseEnter={(e) => {
+            e.currentTarget.style.color = "var(--nb-explain-text)";
+            e.currentTarget.style.background = "var(--nb-explain-bg-hover)";
+          }}
+          onMouseLeave={(e) => {
+            e.currentTarget.style.color = "var(--nb-explain-text-dim)";
+            e.currentTarget.style.background = "none";
+          }}
+        >
+          <X size={16} />
+        </button>
+      </div>
+
+      {/* Messages */}
+      <div style={S.messagesArea}>
+        {messages.length === 0 && !isTyping && (
+          <div style={S.emptyState}>
+            <MessageCircleQuestion
+              size={40}
+              style={{ color: "var(--nb-explain-text-dim)" }}
+            />
+            <div>
+              <p style={S.emptyStateTitle}>How can I help?</p>
+              <p style={S.emptyStateHint}>
+                Use the Explain button to click on any element, or ask a
+                question below.
+              </p>
+            </div>
+          </div>
+        )}
+
+        {messages.map((msg) =>
+          msg.role === "context" ? (
+            <div key={msg.id} style={S.contextBadge}>
+              <div style={S.contextBadgeInner}>
+                <Sparkles
+                  size={10}
+                  style={{ color: "var(--nb-explain-accent)", opacity: 0.6 }}
+                />
+                {msg.content}
+              </div>
+            </div>
+          ) : (
+            <div key={msg.id} style={S.messageRow(msg.role === "user")}>
+              {msg.role === "assistant" && (
+                <div style={S.messageAvatar(false)}>
+                  <Bot size={13} style={{ color: "var(--nb-explain-accent)" }} />
+                </div>
+              )}
+              <div style={S.messageBubble(msg.role === "user")}>
+                {msg.content.split("\n").map((line, i) => (
+                  <React.Fragment key={i}>
+                    {line
+                      .split(/(\*\*[^*]+\*\*)/)
+                      .map((part, j) =>
+                        part.startsWith("**") && part.endsWith("**") ? (
+                          <strong key={j} style={S.messageBold}>
+                            {part.slice(2, -2)}
+                          </strong>
+                        ) : (
+                          <React.Fragment key={j}>{part}</React.Fragment>
+                        ),
+                      )}
+                    {i < msg.content.split("\n").length - 1 && <br />}
+                  </React.Fragment>
+                ))}
+              </div>
+              {msg.role === "user" && (
+                <div style={S.messageAvatar(true)}>
+                  <User size={13} style={{ color: "var(--nb-explain-user-text)" }} />
+                </div>
+              )}
+            </div>
+          ),
+        )}
+
+        {isTyping && (
+          <div style={S.typingRow}>
+            <div style={S.messageAvatar(false)}>
+              <Bot size={13} style={{ color: "var(--nb-explain-accent)" }} />
+            </div>
+            <div style={S.typingBubble}>
+              <span className="nb-explain-dot-1" style={S.typingDot} />
+              <span className="nb-explain-dot-2" style={S.typingDot} />
+              <span className="nb-explain-dot-3" style={S.typingDot} />
+            </div>
+          </div>
+        )}
+
+        <div ref={messagesEndRef} />
+      </div>
+
+      {/* Input */}
+      <div style={S.inputArea}>
+        <div style={S.inputRow}>
+          <input
+            ref={inputRef}
+            type="text"
+            value={input}
+            onChange={(e) => setInput(e.target.value)}
+            onKeyDown={handleKeyDown}
+            placeholder="Ask a follow-up question..."
+            style={S.inputField}
+          />
+          <button
+            onClick={sendMessage}
+            disabled={!active}
+            style={S.sendBtn(active)}
+          >
+            <Send size={15} />
+          </button>
+        </div>
+        <p style={S.inputFooter}>AI-powered assistant</p>
+      </div>
+    </div>
+  );
+}

package/src/client/AIFloatingButton.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import { MessageCircleQuestion, X } from "lucide-react";
+import React from "react";
+import * as S from "./styles";
+
+type Props = {
+  isOpen: boolean;
+  onClick: () => void;
+};
+
+export default function AIFloatingButton({ isOpen, onClick }: Props) {
+  return (
+    <button
+      onClick={onClick}
+      data-nb-explain-ignore
+      style={S.fab(isOpen)}
+      onMouseEnter={(e) => {
+        e.currentTarget.style.transform = "scale(1.05)";
+      }}
+      onMouseLeave={(e) => {
+        e.currentTarget.style.transform = "scale(1)";
+      }}
+      onMouseDown={(e) => {
+        e.currentTarget.style.transform = "scale(0.95)";
+      }}
+      onMouseUp={(e) => {
+        e.currentTarget.style.transform = "scale(1.05)";
+      }}
+    >
+      {isOpen ? <X size={20} /> : <MessageCircleQuestion size={22} />}
+    </button>
+  );
+}

package/src/client/index.ts

@@ -0,0 +1,4 @@
+export { default as AIAssistantProvider, useAIAssistant } from "./AIAssistantProvider";
+export { default as AIChatBot } from "./AIChatBot";
+export { default as AIFloatingButton } from "./AIFloatingButton";
+export type { Message, ExplainContext } from "../types";

package/src/client/styles.ts

@@ -0,0 +1,353 @@
+/**
+ * All styles for netbird-explain components.
+ * Uses inline styles + CSS custom properties so the package
+ * works without any external CSS framework.
+ *
+ * Consumers can override via CSS custom properties:
+ *   --nb-explain-bg:          panel background
+ *   --nb-explain-bg-subtle:   input/message background
+ *   --nb-explain-border:      border color
+ *   --nb-explain-text:        primary text
+ *   --nb-explain-text-muted:  secondary text
+ *   --nb-explain-text-dim:    tertiary/placeholder text
+ *   --nb-explain-accent:      accent color (yellow)
+ *   --nb-explain-accent-hover: accent hover
+ *   --nb-explain-user-bg:     user message background
+ *   --nb-explain-user-text:   user message text
+ *   --nb-explain-radius:      border radius
+ *   --nb-explain-font:        font family
+ */
+
+export const CSS_VARS = `
+  :root {
+    --nb-explain-bg: #0a0a0f;
+    --nb-explain-bg-subtle: rgba(255,255,255,0.06);
+    --nb-explain-bg-hover: rgba(255,255,255,0.08);
+    --nb-explain-border: rgba(255,255,255,0.1);
+    --nb-explain-text: #f0f0f5;
+    --nb-explain-text-muted: #9ca3af;
+    --nb-explain-text-dim: #6b7280;
+    --nb-explain-accent: #eab308;
+    --nb-explain-accent-hover: #facc15;
+    --nb-explain-accent-glow: rgba(234,179,8,0.15);
+    --nb-explain-user-bg: #4f46e5;
+    --nb-explain-user-text: #ffffff;
+    --nb-explain-user-glow: rgba(79,70,229,0.25);
+    --nb-explain-radius: 12px;
+    --nb-explain-radius-sm: 8px;
+    --nb-explain-radius-xs: 6px;
+    --nb-explain-font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    --nb-explain-shadow: 0 25px 50px -12px rgba(0,0,0,0.5), 0 0 0 1px rgba(255,255,255,0.05);
+    --nb-explain-banner-bg: rgba(234,179,8,0.92);
+    --nb-explain-banner-text: #000000;
+    --nb-explain-error-text: #f87171;
+  }
+`;
+
+// --- Chat Panel ---
+
+export const chatPanel: React.CSSProperties = {
+  position: "fixed",
+  bottom: 80,
+  right: 20,
+  zIndex: 9998,
+  width: 420,
+  height: 600,
+  display: "flex",
+  flexDirection: "column",
+  borderRadius: "var(--nb-explain-radius)",
+  border: "1px solid var(--nb-explain-border)",
+  background: "var(--nb-explain-bg)",
+  boxShadow: "var(--nb-explain-shadow)",
+  fontFamily: "var(--nb-explain-font)",
+  overflow: "hidden",
+  animation: "nb-explain-slide-up 0.2s ease-out",
+};
+
+export const chatHeader: React.CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "space-between",
+  padding: "12px 16px",
+  borderBottom: "1px solid var(--nb-explain-border)",
+};
+
+export const chatHeaderLeft: React.CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  gap: 10,
+};
+
+export const chatHeaderIcon: React.CSSProperties = {
+  width: 28,
+  height: 28,
+  borderRadius: "var(--nb-explain-radius-sm)",
+  background: "var(--nb-explain-accent-glow)",
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+};
+
+export const chatHeaderTitle: React.CSSProperties = {
+  fontSize: 14,
+  fontWeight: 600,
+  color: "var(--nb-explain-text)",
+  lineHeight: 1,
+  margin: 0,
+};
+
+export const chatHeaderSubtitle: React.CSSProperties = {
+  fontSize: 11,
+  color: "var(--nb-explain-text-dim)",
+};
+
+export const chatCloseBtn: React.CSSProperties = {
+  padding: 6,
+  borderRadius: "var(--nb-explain-radius-xs)",
+  color: "var(--nb-explain-text-dim)",
+  background: "none",
+  border: "none",
+  cursor: "pointer",
+  display: "flex",
+  alignItems: "center",
+  transition: "color 0.15s, background 0.15s",
+};
+
+// --- Messages ---
+
+export const messagesArea: React.CSSProperties = {
+  flex: 1,
+  overflowY: "auto",
+  padding: "16px",
+  display: "flex",
+  flexDirection: "column",
+  gap: 16,
+};
+
+export const emptyState: React.CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  alignItems: "center",
+  justifyContent: "center",
+  height: "100%",
+  textAlign: "center",
+  gap: 12,
+  opacity: 0.5,
+};
+
+export const emptyStateTitle: React.CSSProperties = {
+  fontSize: 14,
+  color: "var(--nb-explain-text-muted)",
+  fontWeight: 500,
+  margin: 0,
+};
+
+export const emptyStateHint: React.CSSProperties = {
+  fontSize: 12,
+  color: "var(--nb-explain-text-dim)",
+  marginTop: 4,
+};
+
+// Context badge
+export const contextBadge: React.CSSProperties = {
+  display: "flex",
+  justifyContent: "center",
+};
+
+export const contextBadgeInner: React.CSSProperties = {
+  fontSize: 11,
+  color: "var(--nb-explain-text-dim)",
+  background: "var(--nb-explain-bg-subtle)",
+  borderRadius: 20,
+  padding: "4px 12px",
+  display: "flex",
+  alignItems: "center",
+  gap: 6,
+};
+
+// Message row
+export const messageRow = (isUser: boolean): React.CSSProperties => ({
+  display: "flex",
+  gap: 10,
+  justifyContent: isUser ? "flex-end" : "flex-start",
+});
+
+export const messageAvatar = (isUser: boolean): React.CSSProperties => ({
+  width: 24,
+  height: 24,
+  borderRadius: "var(--nb-explain-radius-xs)",
+  background: isUser ? "var(--nb-explain-user-glow)" : "var(--nb-explain-accent-glow)",
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+  flexShrink: 0,
+  marginTop: 2,
+});
+
+export const messageBubble = (isUser: boolean): React.CSSProperties => ({
+  maxWidth: "85%",
+  borderRadius: "var(--nb-explain-radius-sm)",
+  padding: "8px 12px",
+  fontSize: 14,
+  lineHeight: 1.6,
+  background: isUser ? "var(--nb-explain-user-bg)" : "var(--nb-explain-bg-subtle)",
+  color: isUser ? "var(--nb-explain-user-text)" : "var(--nb-explain-text)",
+  wordBreak: "break-word",
+});
+
+export const messageBold: React.CSSProperties = {
+  fontWeight: 600,
+  color: "var(--nb-explain-text)",
+};
+
+// Typing indicator
+export const typingRow: React.CSSProperties = {
+  display: "flex",
+  gap: 10,
+};
+
+export const typingBubble: React.CSSProperties = {
+  background: "var(--nb-explain-bg-subtle)",
+  borderRadius: "var(--nb-explain-radius-sm)",
+  padding: "12px 16px",
+  display: "flex",
+  gap: 6,
+};
+
+export const typingDot: React.CSSProperties = {
+  width: 6,
+  height: 6,
+  borderRadius: "50%",
+  background: "var(--nb-explain-text-dim)",
+};
+
+// --- Input area ---
+
+export const inputArea: React.CSSProperties = {
+  padding: "12px 16px",
+  borderTop: "1px solid var(--nb-explain-border)",
+};
+
+export const inputRow: React.CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  gap: 8,
+  background: "var(--nb-explain-bg-subtle)",
+  borderRadius: "var(--nb-explain-radius-sm)",
+  padding: "8px 12px",
+};
+
+export const inputField: React.CSSProperties = {
+  flex: 1,
+  background: "none",
+  border: "none",
+  outline: "none",
+  fontSize: 14,
+  color: "var(--nb-explain-text)",
+  fontFamily: "var(--nb-explain-font)",
+};
+
+export const sendBtn = (active: boolean): React.CSSProperties => ({
+  padding: 6,
+  borderRadius: "var(--nb-explain-radius-xs)",
+  background: "none",
+  border: "none",
+  cursor: active ? "pointer" : "not-allowed",
+  color: active ? "var(--nb-explain-accent)" : "var(--nb-explain-text-dim)",
+  display: "flex",
+  alignItems: "center",
+  transition: "color 0.15s",
+  opacity: active ? 1 : 0.5,
+});
+
+export const inputFooter: React.CSSProperties = {
+  fontSize: 10,
+  color: "var(--nb-explain-text-dim)",
+  textAlign: "center",
+  marginTop: 6,
+};
+
+// --- Floating button ---
+
+export const fab = (isOpen: boolean): React.CSSProperties => ({
+  position: "fixed",
+  bottom: 20,
+  right: 20,
+  zIndex: 9997,
+  width: 48,
+  height: 48,
+  borderRadius: "50%",
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+  border: "none",
+  cursor: "pointer",
+  transition: "transform 0.2s, box-shadow 0.2s",
+  boxShadow: "0 4px 20px rgba(0,0,0,0.3)",
+  background: isOpen
+    ? "var(--nb-explain-bg-hover)"
+    : "linear-gradient(135deg, var(--nb-explain-accent), #f97316)",
+  color: isOpen ? "var(--nb-explain-text-muted)" : "#fff",
+});
+
+// --- Banner ---
+
+export const banner: React.CSSProperties = {
+  position: "fixed",
+  top: 12,
+  left: "50%",
+  transform: "translateX(-50%)",
+  zIndex: 9996,
+  background: "var(--nb-explain-banner-bg)",
+  color: "var(--nb-explain-banner-text)",
+  fontSize: 14,
+  fontWeight: 500,
+  padding: "6px 16px",
+  borderRadius: 20,
+  boxShadow: "0 4px 20px rgba(234,179,8,0.3)",
+  display: "flex",
+  alignItems: "center",
+  gap: 8,
+  fontFamily: "var(--nb-explain-font)",
+  animation: "nb-explain-fade-in 0.2s ease-out",
+};
+
+export const bannerCancel: React.CSSProperties = {
+  marginLeft: 4,
+  color: "rgba(0,0,0,0.5)",
+  background: "none",
+  border: "none",
+  cursor: "pointer",
+  textDecoration: "underline",
+  fontSize: 12,
+  fontFamily: "var(--nb-explain-font)",
+};
+
+// --- Animations (injected as <style>) ---
+
+export const ANIMATIONS = `
+  @keyframes nb-explain-slide-up {
+    from { opacity: 0; transform: translateY(8px); }
+    to { opacity: 1; transform: translateY(0); }
+  }
+  @keyframes nb-explain-fade-in {
+    from { opacity: 0; transform: translateX(-50%) translateY(-4px); }
+    to { opacity: 1; transform: translateX(-50%) translateY(0); }
+  }
+  @keyframes nb-explain-bounce {
+    0%, 80%, 100% { transform: translateY(0); }
+    40% { transform: translateY(-4px); }
+  }
+  .nb-explain-dot-1 { animation: nb-explain-bounce 1.2s infinite; animation-delay: 0ms; }
+  .nb-explain-dot-2 { animation: nb-explain-bounce 1.2s infinite; animation-delay: 150ms; }
+  .nb-explain-dot-3 { animation: nb-explain-bounce 1.2s infinite; animation-delay: 300ms; }
+`;
+
+export const HIGHLIGHT_STYLES = `
+  [data-nb-explain-highlight] {
+    outline: 2px solid rgba(234, 179, 8, 0.7) !important;
+    border-radius: 6px;
+    cursor: help !important;
+    transition: outline 0.1s ease;
+  }
+`;