672 lines
17 KiB
Markdown
672 lines
17 KiB
Markdown
# 🚀 ChatJS Best Practices - Second Brain Integration Guide
|
|
|
|
## Overview
|
|
This document contains advanced patterns from [ChatJS](https://github.com/FranciscoMoretti/chatjs) that should be integrated into the Second Brain project to achieve production-grade quality.
|
|
|
|
---
|
|
|
|
## 1. 📜 Smart Scroll Management
|
|
|
|
**Problem**: Current implementation scrolls even when user is reading previous messages.
|
|
|
|
**ChatJS Solution**: `use-scroll-anchor.ts`
|
|
|
|
```typescript
|
|
// hooks/use-scroll-anchor.ts
|
|
import { useEffect, useRef, useState } from 'react'
|
|
|
|
export function useScrollAnchor() {
|
|
const messagesRef = useRef<HTMLDivElement>(null)
|
|
const scrollRef = useRef<HTMLDivElement>(null)
|
|
const isAtBottomRef = useRef(true)
|
|
const [showScrollButton, setShowScrollButton] = useState(false)
|
|
|
|
useEffect(() => {
|
|
const messagesEl = messagesRef.current
|
|
const scrollEl = scrollRef.current
|
|
|
|
if (!messagesEl || !scrollEl) return
|
|
|
|
const handleScroll = () => {
|
|
const { scrollTop, scrollHeight, clientHeight } = scrollEl
|
|
const distanceFromBottom = scrollHeight - scrollTop - clientHeight
|
|
|
|
// User is at bottom if within 50px
|
|
isAtBottomRef.current = distanceFromBottom < 50
|
|
setShowScrollButton(!isAtBottomRef.current)
|
|
}
|
|
|
|
scrollEl.addEventListener('scroll', handleScroll)
|
|
return () => scrollEl.removeEventListener('scroll', handleScroll)
|
|
}, [])
|
|
|
|
const scrollToBottom = () => {
|
|
const messagesEl = messagesRef.current
|
|
if (messagesEl) {
|
|
messagesEl.scrollIntoView({ behavior: 'smooth', block: 'end' })
|
|
}
|
|
}
|
|
|
|
// Auto-scroll ONLY if user is at bottom
|
|
const autoScroll = () => {
|
|
if (isAtBottomRef.current) {
|
|
scrollToBottom()
|
|
}
|
|
}
|
|
|
|
return {
|
|
messagesRef,
|
|
scrollRef,
|
|
showScrollButton,
|
|
scrollToBottom,
|
|
autoScroll,
|
|
}
|
|
}
|
|
```
|
|
|
|
**Usage in ChatPage**:
|
|
```typescript
|
|
export function ChatPage() {
|
|
const { messages, isTyping } = useChatStore()
|
|
const { messagesRef, scrollRef, showScrollButton, scrollToBottom, autoScroll } = useScrollAnchor()
|
|
|
|
useEffect(() => {
|
|
autoScroll() // Only scrolls if user is at bottom
|
|
}, [messages, isTyping])
|
|
|
|
return (
|
|
<div className="flex flex-col h-full">
|
|
<div ref={scrollRef} className="flex-1 overflow-y-auto">
|
|
<div className="py-8">
|
|
{messages.map(msg => <ChatMessage key={msg.id} message={msg} />)}
|
|
{isTyping && <TypingIndicator />}
|
|
<div ref={messagesRef} />
|
|
</div>
|
|
</div>
|
|
|
|
{/* Scroll to Bottom Button */}
|
|
{showScrollButton && (
|
|
<button
|
|
onClick={scrollToBottom}
|
|
className="absolute bottom-24 right-8 p-3 bg-primary rounded-full shadow-lg"
|
|
>
|
|
<ChevronDown className="w-5 h-5 text-white" />
|
|
</button>
|
|
)}
|
|
|
|
<ChatInput />
|
|
</div>
|
|
)
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 2. 🎬 Message Actions
|
|
|
|
**ChatJS has excellent message actions on hover.**
|
|
|
|
```typescript
|
|
// components/chat/MessageActions.tsx
|
|
import { Copy, RotateCw, Edit, Share, MoreHorizontal } from 'lucide-react'
|
|
import { toast } from 'sonner'
|
|
|
|
interface MessageActionsProps {
|
|
message: Message
|
|
onRegenerate?: () => void
|
|
onEdit?: () => void
|
|
}
|
|
|
|
export function MessageActions({ message, onRegenerate, onEdit }: MessageActionsProps) {
|
|
const copyToClipboard = () => {
|
|
navigator.clipboard.writeText(message.content)
|
|
toast.success('Copied to clipboard')
|
|
}
|
|
|
|
return (
|
|
<div className="flex items-center gap-1 opacity-0 group-hover:opacity-100 transition-opacity">
|
|
{/* Copy */}
|
|
<button
|
|
onClick={copyToClipboard}
|
|
className="p-1.5 hover:bg-zinc-800 rounded transition-colors"
|
|
title="Copy"
|
|
>
|
|
<Copy className="w-4 h-4 text-zinc-400" />
|
|
</button>
|
|
|
|
{/* Regenerate (AI messages only) */}
|
|
{message.role === 'assistant' && onRegenerate && (
|
|
<button
|
|
onClick={onRegenerate}
|
|
className="p-1.5 hover:bg-zinc-800 rounded transition-colors"
|
|
title="Regenerate"
|
|
>
|
|
<RotateCw className="w-4 h-4 text-zinc-400" />
|
|
</button>
|
|
)}
|
|
|
|
{/* Edit (User messages only) */}
|
|
{message.role === 'user' && onEdit && (
|
|
<button
|
|
onClick={onEdit}
|
|
className="p-1.5 hover:bg-zinc-800 rounded transition-colors"
|
|
title="Edit"
|
|
>
|
|
<Edit className="w-4 h-4 text-zinc-400" />
|
|
</button>
|
|
)}
|
|
|
|
{/* Share */}
|
|
<button
|
|
className="p-1.5 hover:bg-zinc-800 rounded transition-colors"
|
|
title="Share"
|
|
>
|
|
<Share className="w-4 h-4 text-zinc-400" />
|
|
</button>
|
|
</div>
|
|
)
|
|
}
|
|
```
|
|
|
|
**Update ChatMessage to include actions**:
|
|
```typescript
|
|
export function ChatMessage({ message }: ChatMessageProps) {
|
|
const { regenerateMessage } = useChatStore()
|
|
const isUser = message.role === 'user'
|
|
|
|
return (
|
|
<div className="group flex gap-3 max-w-4xl px-6 py-4 relative">
|
|
{/* Avatar */}
|
|
<div className={/* ... */}>
|
|
{/* ... */}
|
|
</div>
|
|
|
|
{/* Content */}
|
|
<div className="flex-1 flex flex-col gap-2">
|
|
{/* ... existing content ... */}
|
|
</div>
|
|
|
|
{/* Actions - appears on hover */}
|
|
<MessageActions
|
|
message={message}
|
|
onRegenerate={() => regenerateMessage(message.id)}
|
|
/>
|
|
</div>
|
|
)
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 📎 Advanced File Upload
|
|
|
|
**ChatJS has excellent drag & drop with preview.**
|
|
|
|
```typescript
|
|
// components/chat/FileUploadZone.tsx
|
|
import { useState } from 'react'
|
|
import { Upload, X, File, Image } from 'lucide-react'
|
|
|
|
interface FileUploadZoneProps {
|
|
onFilesSelect: (files: File[]) => void
|
|
selectedFiles: File[]
|
|
onFileRemove: (index: number) => void
|
|
}
|
|
|
|
export function FileUploadZone({ onFilesSelect, selectedFiles, onFileRemove }: FileUploadZoneProps) {
|
|
const [isDragging, setIsDragging] = useState(false)
|
|
|
|
const handleDrop = (e: React.DragEvent) => {
|
|
e.preventDefault()
|
|
setIsDragging(false)
|
|
|
|
const files = Array.from(e.dataTransfer.files)
|
|
onFilesSelect(files)
|
|
}
|
|
|
|
const handleDragOver = (e: React.DragEvent) => {
|
|
e.preventDefault()
|
|
setIsDragging(true)
|
|
}
|
|
|
|
const handleDragLeave = () => {
|
|
setIsDragging(false)
|
|
}
|
|
|
|
return (
|
|
<div>
|
|
{/* Drag & Drop Zone */}
|
|
<div
|
|
onDrop={handleDrop}
|
|
onDragOver={handleDragOver}
|
|
onDragLeave={handleDragLeave}
|
|
className={`
|
|
border-2 border-dashed rounded-lg p-8 transition-all
|
|
${isDragging
|
|
? 'border-primary bg-primary/5'
|
|
: 'border-zinc-700 hover:border-zinc-600'
|
|
}
|
|
`}
|
|
>
|
|
<div className="flex flex-col items-center gap-2 text-center">
|
|
<Upload className={`w-8 h-8 ${isDragging ? 'text-primary' : 'text-zinc-500'}`} />
|
|
<p className="text-sm text-zinc-400">
|
|
{isDragging ? 'Drop files here' : 'Drag files here or click to browse'}
|
|
</p>
|
|
<p className="text-xs text-zinc-600">
|
|
Supports: Images, PDFs, Documents (max 10MB)
|
|
</p>
|
|
</div>
|
|
</div>
|
|
|
|
{/* File Previews */}
|
|
{selectedFiles.length > 0 && (
|
|
<div className="mt-4 space-y-2">
|
|
{selectedFiles.map((file, index) => (
|
|
<FilePreviewCard
|
|
key={index}
|
|
file={file}
|
|
onRemove={() => onFileRemove(index)}
|
|
/>
|
|
))}
|
|
</div>
|
|
)}
|
|
</div>
|
|
)
|
|
}
|
|
|
|
// File Preview Card
|
|
function FilePreviewCard({ file, onRemove }: { file: File; onRemove: () => void }) {
|
|
const isImage = file.type.startsWith('image/')
|
|
const [preview, setPreview] = useState<string | null>(null)
|
|
|
|
useEffect(() => {
|
|
if (isImage) {
|
|
const reader = new FileReader()
|
|
reader.onloadend = () => setPreview(reader.result as string)
|
|
reader.readAsDataURL(file)
|
|
}
|
|
}, [file, isImage])
|
|
|
|
return (
|
|
<div className="flex items-center gap-3 p-3 bg-zinc-900 border border-zinc-800 rounded-lg">
|
|
{/* Icon or Image Preview */}
|
|
{isImage && preview ? (
|
|
<img src={preview} alt={file.name} className="w-12 h-12 object-cover rounded" />
|
|
) : (
|
|
<div className="w-12 h-12 bg-zinc-800 rounded flex items-center justify-center">
|
|
<File className="w-6 h-6 text-zinc-500" />
|
|
</div>
|
|
)}
|
|
|
|
{/* File Info */}
|
|
<div className="flex-1 min-w-0">
|
|
<p className="text-sm font-medium text-zinc-200 truncate">{file.name}</p>
|
|
<p className="text-xs text-zinc-500">{formatFileSize(file.size)}</p>
|
|
</div>
|
|
|
|
{/* Remove Button */}
|
|
<button
|
|
onClick={onRemove}
|
|
className="p-1 hover:bg-zinc-800 rounded transition-colors"
|
|
>
|
|
<X className="w-4 h-4 text-zinc-500" />
|
|
</button>
|
|
</div>
|
|
)
|
|
}
|
|
|
|
function formatFileSize(bytes: number): string {
|
|
if (bytes < 1024) return bytes + ' B'
|
|
if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB'
|
|
return (bytes / (1024 * 1024)).toFixed(1) + ' MB'
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. ⌨️ Advanced Keyboard Shortcuts
|
|
|
|
**ChatJS has a keyboard shortcuts modal.**
|
|
|
|
```typescript
|
|
// components/KeyboardShortcutsModal.tsx
|
|
import { useEffect, useState } from 'react'
|
|
|
|
export function KeyboardShortcutsModal() {
|
|
const [isOpen, setIsOpen] = useState(false)
|
|
|
|
useEffect(() => {
|
|
const handleKeyDown = (e: KeyboardEvent) => {
|
|
// Cmd+/ or Ctrl+/ to toggle
|
|
if ((e.metaKey || e.ctrlKey) && e.key === '/') {
|
|
e.preventDefault()
|
|
setIsOpen(prev => !prev)
|
|
}
|
|
}
|
|
|
|
window.addEventListener('keydown', handleKeyDown)
|
|
return () => window.removeEventListener('keydown', handleKeyDown)
|
|
}, [])
|
|
|
|
if (!isOpen) return null
|
|
|
|
const shortcuts = [
|
|
{ keys: ['Cmd', 'N'], action: 'New chat' },
|
|
{ keys: ['Cmd', 'K'], action: 'Search conversations' },
|
|
{ keys: ['Cmd', 'L'], action: 'Go to library' },
|
|
{ keys: ['Cmd', 'M'], action: 'Go to neural map' },
|
|
{ keys: ['Cmd', '/'], action: 'Show keyboard shortcuts' },
|
|
{ keys: ['Escape'], action: 'Close modal' },
|
|
{ keys: ['Cmd', 'Enter'], action: 'Send message' },
|
|
]
|
|
|
|
return (
|
|
<div className="fixed inset-0 bg-black/50 flex items-center justify-center z-50">
|
|
<div className="bg-zinc-900 border border-zinc-800 rounded-xl p-6 max-w-md w-full">
|
|
<h2 className="text-xl font-bold text-zinc-100 mb-4">
|
|
Keyboard Shortcuts
|
|
</h2>
|
|
|
|
<div className="space-y-2">
|
|
{shortcuts.map((shortcut, i) => (
|
|
<div key={i} className="flex items-center justify-between py-2">
|
|
<span className="text-sm text-zinc-400">{shortcut.action}</span>
|
|
<div className="flex gap-1">
|
|
{shortcut.keys.map((key, j) => (
|
|
<kbd
|
|
key={j}
|
|
className="px-2 py-1 bg-zinc-800 border border-zinc-700 rounded text-xs font-mono text-zinc-300"
|
|
>
|
|
{key}
|
|
</kbd>
|
|
))}
|
|
</div>
|
|
</div>
|
|
))}
|
|
</div>
|
|
|
|
<button
|
|
onClick={() => setIsOpen(false)}
|
|
className="mt-6 w-full px-4 py-2 bg-primary text-white rounded-lg hover:bg-primary/90 transition-colors"
|
|
>
|
|
Close
|
|
</button>
|
|
</div>
|
|
</div>
|
|
)
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 🔄 Regenerate Message
|
|
|
|
**Add to chatStore.ts**:
|
|
|
|
```typescript
|
|
interface ChatState {
|
|
messages: Message[]
|
|
isTyping: boolean
|
|
sendMessage: (params: SendMessageParams) => Promise<void>
|
|
regenerateMessage: (messageId: string) => Promise<void> // NEW
|
|
clearMessages: () => void
|
|
}
|
|
|
|
export const useChatStore = create<ChatState>((set, get) => ({
|
|
// ... existing code ...
|
|
|
|
regenerateMessage: async (messageId: string) => {
|
|
const { messages } = get()
|
|
const messageIndex = messages.findIndex(m => m.id === messageId)
|
|
|
|
if (messageIndex === -1) return
|
|
|
|
// Find the last user message before this AI message
|
|
const userMessage = messages
|
|
.slice(0, messageIndex)
|
|
.reverse()
|
|
.find(m => m.role === 'user')
|
|
|
|
if (!userMessage) return
|
|
|
|
// Remove the AI message and everything after it
|
|
set({ messages: messages.slice(0, messageIndex) })
|
|
|
|
// Regenerate from user message
|
|
set({ isTyping: true })
|
|
|
|
try {
|
|
const res = await fetch('/api/chat', {
|
|
method: 'POST',
|
|
headers: { 'Content-Type': 'application/json' },
|
|
body: JSON.stringify({
|
|
message: userMessage.content,
|
|
// Use same model/rag settings as original
|
|
}),
|
|
})
|
|
|
|
const data = await res.json()
|
|
|
|
const newMessage: Message = {
|
|
id: Date.now().toString(),
|
|
role: 'assistant',
|
|
content: data.answer,
|
|
timestamp: new Date(),
|
|
sources: data.sources,
|
|
}
|
|
|
|
set(state => ({ messages: [...state.messages, newMessage] }))
|
|
} catch (err) {
|
|
console.error('Regenerate error:', err)
|
|
} finally {
|
|
set({ isTyping: false })
|
|
}
|
|
},
|
|
}))
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 📱 Mobile Improvements
|
|
|
|
**ChatJS has excellent mobile UX.**
|
|
|
|
### Mobile-Specific Improvements:
|
|
|
|
```typescript
|
|
// components/chat/MobileOptimizations.tsx
|
|
|
|
// 1. Virtual Keyboard Handling
|
|
useEffect(() => {
|
|
const handleResize = () => {
|
|
// Adjust viewport when keyboard opens
|
|
const vh = window.innerHeight * 0.01
|
|
document.documentElement.style.setProperty('--vh', `${vh}px`)
|
|
}
|
|
|
|
window.addEventListener('resize', handleResize)
|
|
handleResize()
|
|
|
|
return () => window.removeEventListener('resize', handleResize)
|
|
}, [])
|
|
|
|
// 2. Touch Gestures for Sidebar
|
|
const handleSwipe = (e: TouchEvent) => {
|
|
// Swipe from left edge to open sidebar
|
|
if (e.touches[0].clientX < 20) {
|
|
openSidebar()
|
|
}
|
|
}
|
|
|
|
// 3. Prevent Zoom on Double-Tap
|
|
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no" />
|
|
|
|
// 4. Safe Area Insets (for iPhone notch)
|
|
<div className="pb-[env(safe-area-inset-bottom)]">
|
|
<ChatInput />
|
|
</div>
|
|
```
|
|
|
|
---
|
|
|
|
## 7. 🎨 Loading States
|
|
|
|
**ChatJS has skeleton loaders everywhere.**
|
|
|
|
```typescript
|
|
// components/ui/MessageSkeleton.tsx
|
|
export function MessageSkeleton() {
|
|
return (
|
|
<div className="flex gap-3 max-w-4xl px-6 py-4 animate-pulse">
|
|
<div className="w-8 h-8 rounded-full bg-zinc-800" />
|
|
<div className="flex-1 space-y-2">
|
|
<div className="h-3 bg-zinc-800 rounded w-1/4" />
|
|
<div className="h-4 bg-zinc-800 rounded w-3/4" />
|
|
<div className="h-4 bg-zinc-800 rounded w-2/3" />
|
|
</div>
|
|
</div>
|
|
)
|
|
}
|
|
|
|
// Usage
|
|
{isLoading ? (
|
|
<>
|
|
<MessageSkeleton />
|
|
<MessageSkeleton />
|
|
</>
|
|
) : (
|
|
messages.map(msg => <ChatMessage key={msg.id} message={msg} />)
|
|
)}
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 🔔 Better Error Handling
|
|
|
|
**ChatJS shows user-friendly errors.**
|
|
|
|
```typescript
|
|
// lib/error-handler.ts
|
|
export function handleChatError(error: unknown) {
|
|
console.error('Chat error:', error)
|
|
|
|
if (error instanceof Error) {
|
|
// Network errors
|
|
if (error.message.includes('Failed to fetch')) {
|
|
toast.error('Connection lost. Check your internet.')
|
|
return
|
|
}
|
|
|
|
// API errors
|
|
if (error.message.includes('429')) {
|
|
toast.error('Rate limit exceeded. Please wait a moment.')
|
|
return
|
|
}
|
|
|
|
if (error.message.includes('401')) {
|
|
toast.error('Session expired. Please log in again.')
|
|
return
|
|
}
|
|
}
|
|
|
|
// Generic error
|
|
toast.error('Something went wrong. Please try again.')
|
|
}
|
|
|
|
// Usage in chatStore
|
|
catch (err) {
|
|
handleChatError(err)
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 9. 💾 Local Storage Persistence
|
|
|
|
**ChatJS saves draft messages.**
|
|
|
|
```typescript
|
|
// hooks/useLocalStorage.ts
|
|
export function useLocalStorage<T>(key: string, initialValue: T) {
|
|
const [storedValue, setStoredValue] = useState<T>(() => {
|
|
try {
|
|
const item = window.localStorage.getItem(key)
|
|
return item ? JSON.parse(item) : initialValue
|
|
} catch (error) {
|
|
console.error(error)
|
|
return initialValue
|
|
}
|
|
})
|
|
|
|
const setValue = (value: T | ((val: T) => T)) => {
|
|
try {
|
|
const valueToStore = value instanceof Function ? value(storedValue) : value
|
|
setStoredValue(valueToStore)
|
|
window.localStorage.setItem(key, JSON.stringify(valueToStore))
|
|
} catch (error) {
|
|
console.error(error)
|
|
}
|
|
}
|
|
|
|
return [storedValue, setValue] as const
|
|
}
|
|
|
|
// Usage in ChatInput
|
|
export function ChatInput() {
|
|
const [draftInput, setDraftInput] = useLocalStorage('chat-draft', '')
|
|
|
|
const handleSend = () => {
|
|
// ... send logic
|
|
setDraftInput('') // Clear draft
|
|
}
|
|
|
|
return (
|
|
<textarea
|
|
value={draftInput}
|
|
onChange={(e) => setDraftInput(e.target.value)}
|
|
/>
|
|
)
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 10. 🎯 Implementation Priority
|
|
|
|
**For Second Brain, implement in this order:**
|
|
|
|
1. ✅ **Smart Scroll** (useScrollAnchor) - Immediate UX improvement
|
|
2. ✅ **Message Actions** (Copy, Regenerate) - Professional feel
|
|
3. ✅ **Better File Upload** (Drag & drop with preview) - Core feature
|
|
4. ✅ **Keyboard Shortcuts Modal** - Power user feature
|
|
5. ⏳ **Loading Skeletons** - Polish
|
|
6. ⏳ **Error Handling** - Reliability
|
|
7. ⏳ **Draft Persistence** - Nice to have
|
|
8. ⏳ **Mobile Optimizations** - Once desktop is solid
|
|
|
|
---
|
|
|
|
## 📝 Summary
|
|
|
|
ChatJS demonstrates production-grade patterns that Second Brain should adopt:
|
|
|
|
- **Smart scrolling** prevents annoying auto-scroll
|
|
- **Message actions** make the chat feel professional
|
|
- **File previews** improve upload UX dramatically
|
|
- **Keyboard shortcuts** delight power users
|
|
- **Error handling** builds trust
|
|
- **Loading states** feel responsive
|
|
|
|
The key insight: **Small details compound into a delightful experience.**
|
|
|
|
---
|
|
|
|
## 🔗 Resources
|
|
|
|
- ChatJS Live Demo: https://chatjs.dev
|
|
- ChatJS Docs: https://chatjs.dev/docs
|
|
- ChatJS GitHub: https://github.com/FranciscoMoretti/chatjs
|
|
|
|
Use this as reference when polishing Second Brain! 🚀
|