@forus/ui

Shared UI component library for Forus EOS applications.

Installation

From the workspace root:

# Install dependencies
cd packages/forus-ui
npm install

# Build the package
npm run build

Usage in Forus Apps

1. Add to package.json

In your app's package.json (e.g., app-value or app-spark):

{
  "dependencies": {
    "@forus/ui": "file:../../packages/forus-ui"
  }
}

2. Install

npm install

3. Import Components

import { 
  // Input Components
  NumericInput, 
  CurrencyInput, 
  PercentageInput,
  
  // Display Components
  InfoBox,
  FormTitle,
  AppBar,
  Card,
  MetricCard,
  
  // Drawer Components
  Drawer,
  LeftDrawer,
  RightDrawer
} from '@forus/ui';

Available Components

Input Components

NumericInput

Base numeric input with validation and formatting.

<NumericInput
  value={value}
  onChange={(val) => setValue(val)}
  label="Amount"
  description="Enter the amount"
  suffix="%"
  min={0}
  max={100}
/>

CurrencyInput

Currency input with symbol display and cents/dollars conversion.

<CurrencyInput
  value={priceInCents}
  onChange={(val) => setPriceInCents(parseFloat(val) * 100)}
  label="Price"
  description="Product price"
  currency="USD"
  isCents={true}
/>

Supported currencies: USD, ZAR, NGN, GHS, ETB, RWF, TZS, BRL

PercentageInput

Percentage input with decimal conversion support.

<PercentageInput
  value={rate}
  onChange={(val) => setRate(parseFloat(val) / 100)}
  label="Interest Rate"
  description="Annual percentage rate"
  isDecimal={true}
/>

Display Components

InfoBox

Contextual information boxes with variants.

<InfoBox variant="tip" title="Pro Tip">
  This is helpful information for the user.
</InfoBox>

Variants: info, tip, settings, warning

FormTitle

Consistent form section headers.

<FormTitle
  title="Section Title"
  description="Optional description text"
/>

AppBar

Standardized app header with Forus branding.

<AppBar 
  appName="Value Creator"
  logoSrc="/forus-logo.svg"
  tooltip={{
    title: "About Forus",
    description: "Forus transforms business domains...",
    items: [
      { label: "Domains", content: "Self-organizing entities" },
      { label: "Value", content: "Shared success model" }
    ]
  }}
  onMenuClick={() => setMenuOpen(true)}
  leftmostContent={<ChevronButton />}
/>

Card

Basic card container component.

<Card className="p-4">
  <h3>Card Title</h3>
  <p>Card content goes here</p>
</Card>

MetricCard

Specialized card for displaying metrics.

<MetricCard
  title="Total Value"
  value="$1,234,567"
  subtitle="Monthly recurring"
  trend={{ value: 12.5, isPositive: true }}
/>

Drawer Components

Drawer

Base drawer component with full customization.

<Drawer
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  position="left"
  width="w-80"
  header={<h2>Drawer Title</h2>}
  footer={<button>Save Changes</button>}
>
  <div className="p-4">
    Drawer content
  </div>
</Drawer>

Props:

• isOpen: Boolean to control visibility
• onClose: Callback when drawer should close
• position: "left" | "right" (default: "left")
• width: Tailwind width class (default: "w-80")
• showOverlay: Show backdrop overlay (default: true)
• closeOnOverlayClick: Close when clicking overlay (default: true)
• closeButton: Show close button in header (default: true)
• header: ReactNode for custom header
• footer: ReactNode for custom footer

LeftDrawer

Specialized left drawer with back button support.

<LeftDrawer
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="Settings"
  backButton={true}
  onBack={() => navigateBack()}
>
  <div className="p-4">
    Settings content
  </div>
</LeftDrawer>

Additional props:

• title: String title for the drawer
• backButton: Show back navigation button
• onBack: Callback for back button click

RightDrawer

Specialized right drawer with icon and subtitle support.

<RightDrawer
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="User Profile"
  subtitle="Manage your account"
  icon={<UserIcon className="w-6 h-6" />}
>
  <div className="p-4">
    Profile content
  </div>
</RightDrawer>

Additional props:

• title: String title for the drawer
• subtitle: String subtitle below the title
• icon: ReactNode for header icon

Design Tokens

The library follows Forus design standards:

const forusTheme = {
  colors: {
    primary: '#027DB8',      // Forus blue
    secondary: '#81CAC9',    // Tooltip teal
    neutral: '#EEEEEE',      // Card background
    error: '#EF4444',
    success: '#10B981'
  },
  spacing: {
    xs: '0.5rem',   // 8px
    sm: '1rem',     // 16px
    md: '1.5rem',   // 24px
    lg: '2rem',     // 32px
    xl: '3rem'      // 48px
  }
}

Component Standards

• Focus states: focus:ring-2 focus:ring-blue-500 focus:border-transparent
• Disabled states: disabled:bg-gray-50 disabled:text-gray-500
• Numeric validation: Built-in keyboard and paste validation
• TypeScript: Full type safety with interfaces

Development

Build

npm run build

Watch Mode

npm run watch

Clean

npm run clean

Drawer Features

All drawer components include:

• Smooth animations: Slide in/out transitions
• Keyboard support: ESC key to close
• Body scroll lock: Prevents background scrolling when open
• Accessibility: Proper ARIA labels and focus management
• Mobile-first: Optimized for touch interactions
• Portal rendering: Renders at document root for proper stacking

TypeScript Support

The library exports all component props interfaces:

import type { 
  DrawerProps, 
  LeftDrawerProps, 
  RightDrawerProps 
} from '@forus/ui';

Future Enhancements

• [ ] Date/time inputs
• [ ] Select/dropdown components
• [ ] Modal/dialog components
• [ ] Button variants
• [ ] Loading states
• [ ] Toast notifications
• [ ] Table components
• [ ] Tabs component