How to Document Components¶

Creating a New Component Document¶

Create a file [component_name].md in bidscript-dev-docs/docs/frontend/components/(...any remaining appropriate sub-directories)/.
Use this template:

# Component Name(components/component_name.tsx)

## Overview
One-line description of the component's purpose and main functionality.

## Features
Key capabilities and interactions.

## Dependencies
Required imports and packages.

## Props
Interface definition and usage.

## Implementation
### State Management
State variables and their purpose.

### Methods
Key functions and their parameters.

### Unique Functionality
Special features or behaviors.

### HTML Structure
Core DOM structure and styling approach.

## API Integration
Endpoints used by the component.

## Components Used
Other components that this component uses.

## Notes
Important considerations.

3. Update the mkdocs.yml file's nav section to include your new component documentation:

nav:
  - Frontend:
      - Components:
          - YourComponent: frontend/components/your-component.md

Example (from codebase)¶

Modern Chatbot (components/modern-chatbot.tsx)¶

Overview¶

A sophisticated chatbot interface component featuring real-time messaging, animations, and interactive features. The component provides a draggable chat window with message history, typing indicators, and file attachment capabilities.

Features¶

Real-time messaging
Animated transitions
Typing indicators
File attachments
Clipboard integration
Error handling
Message history
Draggable window
User authentication
Response streaming

Dependencies¶

import { useState, useEffect, useRef } from 'react'
import { motion } from 'framer-motion'
import { Button } from '@/components/ui/button'
import { Textarea } from '@/components/ui/textarea'
import { ScrollArea } from '@/components/ui/scroll-area'
import { useSession } from 'next-auth/react'

Props¶

interface ModernChatbotProps {
  onSendMessage: (message: string) => Promise<void>;
  onFileUpload: (file: File) => Promise<void>;
  onClose: () => void;
  isVisible: boolean;
  messages: Message[];
  isTyping: boolean;
}

interface Message {
  id: string;
  content: string;
  sender: 'user' | 'bot';
  timestamp: string;
  attachments?: Attachment[];
}

interface Attachment {
  id: string;
  name: string;
  url: string;
  type: string;
}

Implementation¶

State Management¶

const [inputValue, setInputValue] = useState('');
const [isDragging, setIsDragging] = useState(false);
const [position, setPosition] = useState({ x: 0, y: 0 });
const [isMinimized, setIsMinimized] = useState(false);

Methods¶

const handleSendMessage = async () => {
  if (!inputValue.trim()) return;

  try {
    await onSendMessage(inputValue);
    setInputValue('');
  } catch (error) {
    console.error('Failed to send message:', error);
  }
};

const handleFileUpload = async (event: React.ChangeEvent<HTMLInputElement>) => {
  const file = event.target.files?.[0];
  if (!file) return;

  try {
    await onFileUpload(file);
  } catch (error) {
    console.error('Failed to upload file:', error);
  }
};

const handleDragEnd = (event: any, info: any) => {
  setIsDragging(false);
  setPosition({
    x: position.x + info.offset.x,
    y: position.y + info.offset.y
  });
};

Unique Functionality¶

// Provides real-time chat interface with draggable window and file uploads

HTML Structure¶

<motion.div
  drag
  dragMomentum={false}
  dragElastic={0}
  onDragStart={() => setIsDragging(true)}
  onDragEnd={handleDragEnd}
  animate={{
    x: position.x,
    y: position.y,
    scale: isMinimized ? 0.5 : 1
  }}
  className="fixed bottom-4 right-4 w-96 bg-white rounded-lg shadow-lg"
>
  <div className="p-4">
    (/**Website Body**/)
  </div>
</motion.div>

API Integration¶

Message sending and receiving
File upload handling
User session management
Real-time updates

Components Used¶

Notes¶

Features draggable window
Supports file attachments
Handles real-time updates
Provides typing indicators
Maintains message history