Shared UI Components

Reusable React components used across all three products (FleetOS, Robo-Hub, Robo-Dapp).

Overview

This directory contains shared UI components that eliminate code duplication and provide consistent user experiences across the T420 ecosystem. All components use CSS variables for theming compatibility.

---

Available Components

1. Card Component

File: Card.tsx Purpose: Reusable card container with multiple visual variants

Variants:

• default - Standard card with subtle styling

• featured - Highlighted card with accent colors

• stat - Card optimized for displaying statistics

• service - Card for service listings

Sub-components:

• CardHeader - Optional header section

• CardFooter - Optional footer section

Usage:

import { Card, CardHeader, CardFooter } from '@/components/shared/Card';

<Card variant="featured" onClick={handleClick} hover>
  <CardHeader>
    <h3>Fleet Request</h3>
  </CardHeader>
  <div style={{ padding: '20px' }}>
    <p>Request details...</p>
  </div>
  <CardFooter>
    <button>Accept</button>
    <button>Decline</button>
  </CardFooter>
</Card>

Props:

interface CardProps {
  variant?: 'default' | 'featured' | 'stat' | 'service';
  children: ReactNode;
  className?: string;
  style?: CSSProperties;
  onClick?: () => void;
  hover?: boolean; // Enable hover effects
}

Use Cases:

• Blog post cards (BlogDirectoryPage)

• Service request cards (SupplierTodoList)

• Statistics dashboard cards

• RFQ listings (Robo-Hub)

---

2. EmptyState Component

File: EmptyState.tsx Purpose: Standardized UI for "no data" scenarios

Features:

• Customizable icon (emoji or React element)

• Title and description text

• Optional action button

• Support for custom children

Usage:

import { EmptyState } from '@/components/shared/EmptyState';

<EmptyState
  icon="📭"
  title="No Requests Yet"
  description="When fleets send you requests, they'll appear here."
  actionLabel="Invite a Fleet"
  onAction={() => setView('INVITE')}
/>

Props:

interface EmptyStateProps {
  icon?: string | ReactNode; // Default: '📭'
  title: string;
  description?: string;
  actionLabel?: string;
  onAction?: () => void;
  children?: ReactNode;
  className?: string;
  style?: CSSProperties;
}

Use Cases:

• Empty chat conversations

• No pending requests

• Empty supplier directory

• No search results

---

3. Breadcrumb Component

File: Breadcrumb.tsx Purpose: Navigation breadcrumb for hierarchical pages

Features:

• Clickable navigation items

• Custom separators

• Automatic last-item styling (non-clickable)

• Hover effects on navigation items

Usage:

import { Breadcrumb } from '@/components/shared/Breadcrumb';

<Breadcrumb
  items={[
    { label: 'Blog', view: 'BLOG_DIRECTORY' },
    { label: 'Getting Started', view: 'BLOG_POST' },
    { label: 'Authentication Guide' } // Current page (non-clickable)
  ]}
  onNavigate={(view) => setCurrentView(view as View)}
  separator="/"
/>

Props:

interface BreadcrumbItem {
  label: string;
  view?: string;
  onClick?: () => void;
}

interface BreadcrumbProps {
  items: BreadcrumbItem[];
  onNavigate?: (view: string) => void;
  separator?: string | React.ReactNode; // Default: '/'
  className?: string;
  style?: CSSProperties;
}

Use Cases:

• Blog navigation (BlogDirectoryPage, BlogPostPage)

• Multi-step forms

• Settings pages

• Hierarchical content

---

4. FilterBar Component

File: FilterBar.tsx Purpose: Search, filter, and sort interface with debouncing

Features:

• Debounced search input (300ms)

• Filter dropdown

• Sort dropdown

• Clear all filters button

• Responsive flex layout

Usage:

import { FilterBar } from '@/components/shared/FilterBar';

const [searchValue, setSearchValue] = useState('');
const [filterValue, setFilterValue] = useState('');
const [sortValue, setSortValue] = useState('');

<FilterBar
  searchPlaceholder="Search requests..."
  searchValue={searchValue}
  onSearchChange={setSearchValue}
  filterOptions={[
    { value: 'ALL', label: 'All Status' },
    { value: 'pending', label: 'Pending' },
    { value: 'accepted', label: 'Accepted' }
  ]}
  filterValue={filterValue}
  onFilterChange={setFilterValue}
  filterLabel="Status"
  sortOptions={[
    { value: 'newest', label: 'Newest First' },
    { value: 'oldest', label: 'Oldest First' }
  ]}
  sortValue={sortValue}
  onSortChange={setSortValue}
  sortLabel="Sort by"
  onClearFilters={() => {
    setSearchValue('');
    setFilterValue('');
    setSortValue('');
  }}
/>

Props:

interface FilterOption {
  value: string;
  label: string;
}

interface FilterBarProps {
  searchPlaceholder?: string;
  searchValue?: string;
  onSearchChange?: (value: string) => void;
  filterOptions?: FilterOption[];
  filterValue?: string;
  onFilterChange?: (value: string) => void;
  filterLabel?: string;
  sortOptions?: SortOption[];
  sortValue?: string;
  onSortChange?: (value: string) => void;
  sortLabel?: string;
  onClearFilters?: () => void;
  showClearButton?: boolean; // Default: true
  className?: string;
  style?: CSSProperties;
}

Debouncing: The search input debounces user input by 300ms to avoid excessive API calls or re-renders during typing.

Use Cases:

• Service request lists

• Supplier directories

• Blog post listings

• RFQ browsing (Robo-Hub)

---

Shared Chat Helpers

chatHelpers.ts

File: chatHelpers.tsx Purpose: Reusable message rendering utilities for all chat interfaces

Functions:

getMessageBubbleStyles(message, currentRole)

Returns appropriate styling for message bubbles based on sender type.

Usage:

import { getMessageBubbleStyles } from '@/components/shared/chatHelpers';

const bubbleStyles = getMessageBubbleStyles(message, 'supplier');
// Returns: { backgroundColor, color, border, borderLeft? }

Styles:

• Current user: Accent color background

• System messages: Gray background

• AI messages: Amber background with left border accent

• Other users: Light gray background

getSenderLabel(message, currentRole)

Returns display label for message sender.

Usage:

const label = getSenderLabel(message, 'supplier');
// Returns: 'You' | 'System' | '🤖 AI' | senderName | role label

getSenderLabelColor(message, currentRole)

Returns color for sender label text.

getTimestampColor(message, currentRole)

Returns color for timestamp text.

formatMessageTime(date)

Formats timestamp for display (e.g., "2:45 PM").

Use Cases:

• AgenticChatInterface (FleetOS agents)

• ShepherdChatInterface (Robo-Hub shepherds)

• SupplierChatInterface (Supplier conversations)

Impact: Reduces 1,500 lines of duplicate chat code across 3 interfaces to ~400 lines (73% reduction).

---

Theme Compatibility

All components use CSS variables for theming:

/* Color palette (defined in your global CSS) */
--gray-1, --gray-2, ... --gray-12
--accent-1, --accent-2, ... --accent-12
--amber-3, --amber-6, --amber-9, --amber-11
--blue-11

/* Component-specific usage */
--gray-1: Background
--gray-6: Borders
--gray-11: Secondary text
--gray-12: Primary text
--accent-9: Primary actions

Product Theming:

• FleetOS: Uses accent colors sparingly, gray-dominant

• Robo-Hub: More vibrant accent usage, blue accents

• Robo-Dapp: Blockchain-inspired colors (future)

---

Best Practices

1. Import from Shared

Always import shared components to avoid duplication:

// ✅ Good
import { Card } from '@/components/shared/Card';
import { EmptyState } from '@/components/shared/EmptyState';

// ❌ Bad - Don't recreate these components
const MyCard = () => { /* duplicate implementation */ };

2. Use Props for Customization

Prefer props over creating new components:

// ✅ Good
<Card variant="featured" hover>

// ❌ Bad - Don't create FeaturedCard, StatCard, etc.
<FeaturedCard>

3. Extend with Children

Use children prop for custom content:

// ✅ Good
<EmptyState title="No data" icon="📭">
  <CustomActionButton />
</EmptyState>

// ❌ Bad - Don't fork the component
<EmptyStateWithButton title="No data" />

4. CSS Variables for Theming

Use CSS variables instead of hardcoded colors:

// ✅ Good
style={{ color: 'var(--gray-12)' }}

// ❌ Bad
style={{ color: '#000000' }}

---

Testing Shared Components

import { render, screen, fireEvent } from '@testing-library/react';
import { Card } from './Card';

describe('Card Component', () => {
  it('should render children', () => {
    render(<Card>Test Content</Card>);
    expect(screen.getByText('Test Content')).toBeInTheDocument();
  });

  it('should call onClick when clicked', () => {
    const handleClick = jest.fn();
    render(<Card onClick={handleClick}>Click me</Card>);
    fireEvent.click(screen.getByText('Click me'));
    expect(handleClick).toHaveBeenCalledTimes(1);
  });

  it('should apply variant styles', () => {
    const { container } = render(<Card variant="featured">Content</Card>);
    const card = container.firstChild;
    expect(card).toHaveStyle({ borderWidth: '2px' });
  });
});

---

Adding New Shared Components

When creating a new shared component:

1. Check for duplication - Search codebase for similar implementations

2. Design for reuse - Make it generic, not product-specific

3. Use TypeScript - Fully type all props and interfaces

4. Export types - Export prop interfaces for consumers

5. Add JSDoc comments - Document purpose and usage

6. Use CSS variables - For theming compatibility

7. Update this README - Add documentation and examples

8. Consider testing - Add tests for core functionality

---

Component Organization

components/shared/
├── Card.tsx              # Container cards
├── EmptyState.tsx        # No-data states
├── Breadcrumb.tsx        # Navigation
├── FilterBar.tsx         # Search/filter/sort
├── chatHelpers.ts        # Chat message utilities
└── README.md             # This file

Future Additions:

• Modal.tsx - Standardized modal dialogs (6 duplicate modals exist)

• BaseChatInterface.tsx - Base chat component (in progress)

• DashboardCard.tsx - Dashboard-specific cards (7 duplicate dashboards)

• LoadingSpinner.tsx - Loading states

• Tooltip.tsx - Hover tooltips

• Badge.tsx - Status badges

---

Migration from Product-Specific Components

If you have a product-specific component that could be shared:

1. Extract to shared/ - Move component to this directory

2. Generalize props - Remove product-specific assumptions

3. Update imports - Change all references to use shared version

4. Test across products - Verify it works in FleetOS, Robo-Hub, Robo-Dapp

5. Document here - Add section to this README

Example Migration:

// Before: components/fleetos/SupplierCard.tsx
export function SupplierCard({ supplier }) { ... }

// After: components/shared/Card.tsx
export function Card({ variant, children, onClick }) { ... }

// Usage in FleetOS:
<Card variant="service" onClick={() => selectSupplier(supplier)}>
  <SupplierInfo supplier={supplier} />
</Card>

---

Related Documentation

• Service Contracts: services/contracts/ - TypeScript interfaces for services

• Type Guards: lib/chatTypeGuards.ts - Runtime type checking

• Style Helpers: lib/styleHelpers.ts - Theme utilities

• Shared Services: services/shared/README.md - Backend service documentation

---

Last Updated: 2026-01-05 Maintained By: System Architect Component Count: 5 (Card, EmptyState, Breadcrumb, FilterBar, chatHelpers)