Message Input Component Architecture in y-gui: React State Management and Bot Selection Deep Dive

The MessageInput component in y-gui implements a controlled React architecture with localStorage persistence for bot selection, SWR-based data fetching for bot configurations, and a flexible callback system that supports both standard form submissions and custom WebSocket integrations.

The message input component architecture in y-gui centers on the MessageInput component located at frontend/src/components/MessageInput.tsx. This component serves as the primary interface for capturing user chat messages, managing bot selection, and orchestrating the flow of data from the UI to the backend. Its design emphasizes separation of concerns by delegating state management to parent components while handling complex interactions like keyboard events, persistence, and dynamic theming internally.

Core Architecture Overview

The component follows a controlled component pattern where all state resides in parent components and is passed down via props. This architecture ensures that the MessageInput remains purely presentational and reusable across different contexts, from fixed-position chat interfaces to embedded input forms.

The main props interface accepts:

• message and setMessage for text input state
• selectedBot and setSelectedBot for bot selection state
• isLoading to control submission button states
• handleSubmit as the default submission handler
• Optional onSendMessage and onStop callbacks for custom behavior
• isFixed boolean to toggle viewport anchoring

State Management and Data Flow

Props Interface and Controlled State

In frontend/src/components/MessageInput.tsx (lines 6-16), the component defines a strict TypeScript interface that enforces the controlled pattern:

interface MessageInputProps {
  message: string;
  setMessage: (msg: string) => void;
  selectedBot: string | undefined;
  setSelectedBot: (bot: string | undefined) => void;
  isLoading: boolean;
  handleSubmit: (e: React.FormEvent) => Promise<void>;
  onSendMessage?: (content: string, botName: string) => void;
  onStop?: () => void;
  isFixed?: boolean;
}

This design ensures that the component never maintains its own copy of the message or selected bot, preventing synchronization issues between multiple instances or parent re-renders.

Bot Configuration Fetching

The component retrieves available bots using the useAuthenticatedSWR hook from frontend/src/utils/api.ts. At lines 31-35 in MessageInput.tsx, it fetches the bot configuration array:

const { data: botsData } = useAuthenticatedSWR<BotConfig[]>('/api/bots');
const bots = botsData ?? [];

The BotConfig type is defined in shared/types/index.ts (lines 59-68), ensuring type safety across the frontend and backend. This SWR-based approach provides automatic caching, revalidation, and error handling without additional boilerplate.

Persistence with localStorage

The architecture implements a dual-key persistence strategy to maintain bot selection across page reloads. In MessageInput.tsx (lines 38-54), a useEffect hook checks the current URL path to determine the appropriate storage key:

useEffect(() => {
  const isHomePage = window.location.pathname === '/';
  const storageKey = isHomePage ? 'y-gui-home-selected-bot' : 'y-gui-chat-selected-bot';
  const savedBot = localStorage.getItem(storageKey);
  
  if (savedBot && bots.some(b => b.name === savedBot)) {
    setSelectedBot(savedBot);
  } else if (bots.length > 0 && !selectedBot) {
    setSelectedBot(bots[0].name);
  }
}, [bots]);

A complementary effect at lines 56-69 persists any changes to selectedBot back to localStorage, ensuring the user's preference survives navigation between the home page and individual chat sessions.

User Interaction Handling

Keyboard Events and IME Support

The component handles keyboard submission through the handleKeyDown function (lines 71-80), which respects Input Method Editor (IME) composition states to prevent premature submission during complex character input:

const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
  if (e.key === 'Enter' && !e.shiftKey && !e.nativeEvent.isComposing) {
    e.preventDefault();
    onSubmit(e);
  }
};

This architecture ensures compatibility with Chinese, Japanese, and Korean input methods while maintaining the expected "Enter to send, Shift+Enter for newline" behavior.

Submission Logic and Callback Patterns

The onSubmit function (lines 82-98) implements a flexible delegation pattern that prioritizes custom handlers over default form submission:

const onSubmit = async (e: React.FormEvent) => {
  e.preventDefault();
  if (!message.trim() || !selectedBot || isLoading) return;

  if (onSendMessage) {
    onSendMessage(message.trim(), selectedBot);
    setMessage('');
  } else {
    await handleSubmit(e);
  }
};

This design allows parent components to either use the standard handleSubmit prop for HTTP requests or provide onSendMessage for WebSocket-based real-time communication, with the component handling message clearing and validation consistently.

Bot Selection Dropdown

The bot selector implements a custom dropdown using React state and native DOM event listeners. At lines 100-115, the component manages dropdown visibility and attaches a global mousedown listener to detect clicks outside the menu:

const [isOpen, setIsOpen] = useState(false);

useEffect(() => {
  const handleClickOutside = (event: MouseEvent) => {
    if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
      setIsOpen(false);
    }
  };
  document.addEventListener('mousedown', handleClickOutside);
  return () => document.removeEventListener('mousedown', handleClickOutside);
}, []);

When a user selects a bot, the setSelectedBot callback updates the parent state, triggering the persistence effect and closing the dropdown.

UI Adaptations and Theming

Fixed Positioning

The component supports two layout modes via the isFixed prop. When isFixed is true, the wrapper div receives Tailwind classes fixed bottom-0 left-0 right-0 (lines 16-18), anchoring the input to the viewport bottom for full-screen chat interfaces. When false, it flows normally within the document layout.

Dark Mode Integration

The architecture integrates with the theme system through the useTheme hook from frontend/src/contexts/ThemeContext.tsx. The isDarkMode boolean (lines 42-44 in ThemeContext) drives conditional Tailwind classes throughout the component, switching background, border, and text colors between light and dark themes without prop drilling.

Loading States

During submission, the isLoading prop transforms the UI: the submit button converts to a stop button (when onStop is provided) and displays a loading spinner SVG. The button remains disabled when no message text or bot is selected, preventing invalid submissions.

Implementation Examples

Basic Usage in a Chat Page

This example demonstrates standard HTTP-based submission using the handleSubmit prop:

import MessageInput from '@/components/MessageInput';
import { useState } from 'react';

export default function ChatPage() {
  const [msg, setMsg] = useState('');
  const [bot, setBot] = useState<string | undefined>(undefined);
  const [loading, setLoading] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);
    await fetch('/api/chat', {
      method: 'POST',
      body: JSON.stringify({ content: msg, bot }),
    });
    setMsg('');
    setLoading(false);
  };

  return (
    <MessageInput
      message={msg}
      setMessage={setMsg}
      selectedBot={bot}
      setSelectedBot={setBot}
      isLoading={loading}
      handleSubmit={handleSubmit}
    />
  );
}

WebSocket Integration with Custom Callbacks

For real-time applications, override the default submission behavior:

<MessageInput
  message={msg}
  setMessage={setMsg}
  selectedBot={activeBot}
  setSelectedBot={setActiveBot}
  isLoading={isStreaming}
  handleSubmit={async () => {}} // Required but unused when onSendMessage provided
  onSendMessage={(content, botName) => {
    socket.emit('chat_message', { content, bot: botName });
  }}
  onStop={() => socket.emit('abort_generation')}
/>

Fixed Position Variant for Full-Screen Layouts

<MessageInput
  {...commonProps}
  isFixed={true}
/>

Summary

• Controlled Architecture: The MessageInput component maintains no internal state for message content or bot selection, receiving all data via props to ensure synchronization with parent components.

• Dual Persistence Strategy: Bot selection persists to localStorage using context-aware keys (y-gui-home-selected-bot vs y-gui-chat-selected-bot), maintaining user preferences across page reloads and navigation contexts.

• Flexible Submission Patterns: The component supports both standard form submission via handleSubmit and custom real-time communication through onSendMessage, with automatic message clearing and validation.

• IME-Aware Input: Keyboard handling respects composition states via e.nativeEvent.isComposing, ensuring compatibility with CJK input methods while maintaining Enter-to-submit functionality.

• Theme and Position Adaptability: Integration with ThemeContext provides automatic dark mode support, while the isFixed prop enables viewport-anchored layouts for immersive chat experiences.

Frequently Asked Questions

How does the MessageInput component handle bot selection persistence?

The component implements a dual-key localStorage strategy that distinguishes between the home page and individual chat sessions. On mount, it checks window.location.pathname to determine whether to read from y-gui-home-selected-bot or y-gui-chat-selected-bot. When the user selects a different bot, a separate effect writes the new value back to the appropriate localStorage key, ensuring preferences survive page reloads and navigation between different sections of the application.

What is the difference between handleSubmit and onSendMessage props?

The handleSubmit prop accepts a standard React form event handler ((e: React.FormEvent) => Promise<void>) and is used when the parent component manages the submission lifecycle, typically for HTTP requests. The onSendMessage prop is an optional callback signature (content: string, botName: string) => void that bypasses the form handling entirely, allowing direct integration with WebSockets or other real-time communication channels. When onSendMessage is provided, the component automatically clears the message field after invocation; with handleSubmit, clearing is the parent's responsibility.

How does the component prevent breaking IME input when using Enter to submit?

The keyboard event handler in handleKeyDown checks e.nativeEvent.isComposing before triggering submission. This property is true when the user is in the middle of an Input Method Editor composition session, such as when converting phonetic input to Chinese characters or selecting Japanese kanji. By checking this flag, the component ensures that pressing Enter during composition selects the candidate character rather than prematurely submitting the incomplete message, providing proper support for CJK language input.

Can the MessageInput component be used without fixed positioning?

Yes, the isFixed prop controls the positioning behavior. When isFixed is true (the default), the component applies Tailwind classes fixed bottom-0 left-0 right-0 to anchor the input to the bottom of the viewport, suitable for full-screen chat applications. When set to false, the component renders as a normal flow element within the document, allowing it to be placed anywhere in the layout without viewport anchoring. This flexibility enables reuse across different page layouts without structural changes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}