@mosaic/swap-widget

A self-contained swap widget for DeFi token swapping built with React and TypeScript.

📋 Overview

The swap widget provides a complete, reusable component for token swapping functionality. It's designed to be lightweight, customizable, and easy to integrate into any DeFi application.

🚀 Features

• Self-contained: Minimal external dependencies
• TypeScript: Full type safety and IntelliSense support
• Customizable: Flexible styling through className props
• Responsive: Works on desktop and mobile devices
• Accessible: Built with accessibility best practices

📦 Installation

This package is part of the Mosaic Frontend monorepo. Install dependencies from the root:

pnpm install

🛠️ Development

Local Development

Start the development server:

# From root
pnpm dev:swap-widget

# From package directory
pnpm dev

Storybook

View and develop components in isolation:

# From root
pnpm dev:storybook:swap-widget

# From package directory
pnpm storybook

This will start Storybook on http://localhost:6007

Building

Build the package:

# From root
pnpm build:swap-widget

# From package directory
pnpm build

📖 Usage

Basic Usage

import { SwapWidget } from '@mosaic/swap-widget';

function App() {
  return (
    <div>
      <SwapWidget />
    </div>
  );
}

Note: The widget automatically injects its CSS styles when imported. No additional CSS imports are required.

With Custom Styling

import { SwapWidget } from '@mosaic/swap-widget';

function App() {
  return (
    <div>
      <SwapWidget className='border border-gray-200 rounded-lg shadow-lg p-6' />
    </div>
  );
}

CSS Variables Support

The widget includes built-in CSS variables for theming:

:root {
  --primary: 250 202 32;
  --primary-foreground: 0 0 0;
  --background: 255 255 255;
  --foreground: 15 23 42;
  /* ... other variables */
}

.dark {
  --background: 2 6 23;
  --foreground: 139 141 145;
  /* ... dark theme variables */
}

🎨 Customization

The swap widget supports customization through:

• className: Apply custom CSS classes
• Tailwind CSS: Built-in support for utility-first styling
• Theme variants: Light/dark theme support through CSS classes

Example Themes

// Light theme (default)
<SwapWidget className="bg-white border border-gray-200" />

// Dark theme
<SwapWidget className="bg-gray-900 border border-gray-700 text-white" />

// Compact variant
<SwapWidget className="p-4 rounded-md" />

📚 API Reference

SwapWidget

The main swap component.

Props

| Prop | Type | Default | Description | | ----------- | -------- | ----------- | ------------------------------------------------------- | | className | string | undefined | Additional CSS classes to apply to the widget container |

Example

<SwapWidget className='w-full max-w-md mx-auto' />

🏗️ Architecture

The swap widget follows these architectural principles:

Component Structure

src/
├── components/
│   ├── swap-widget.tsx        # Main swap component
│   └── swap-widget.stories.tsx # Storybook stories
├── hooks/                     # Custom React hooks
├── types/                     # TypeScript type definitions
├── utils/                     # Utility functions
└── index.ts                   # Package exports

Design Patterns

• Compound Components: For complex UI patterns
• Custom Hooks: For reusable stateful logic
• Pure Functions: For utilities and calculations
• TypeScript First: Comprehensive type coverage

🧪 Testing

Storybook Stories

All components include comprehensive Storybook stories for:

• Visual testing
• Interactive development
• Documentation
• Accessibility testing

Running Tests

# Lint code
pnpm lint

# Type checking
pnpm type-check

🎯 Roadmap

Future enhancements planned:

• [ ] Token selection modal
• [ ] Price impact calculation
• [ ] Slippage settings
• [ ] Transaction history
• [ ] Multi-chain support
• [ ] Advanced order types

🤝 Contributing

This package follows the monorepo's development guidelines:

1. TypeScript: Use strict typing
2. Components: Keep them presentational and prop-driven
3. Hooks: Encapsulate stateful logic
4. Stories: Create comprehensive Storybook stories
5. Documentation: Include JSDoc comments

Code Standards

• Use compound component patterns for complex UI
• Export types explicitly from index files
• Follow consistent naming conventions
• Implement proper error boundaries

🔗 Related Packages

• @mosaic/ui - Shared UI components and utilities
• @mosaic/hooks - Reusable React hooks
• @mosaic/utils - Pure utility functions

📄 License

Part of the Mosaic Frontend monorepo. See root license for details.

🆘 Support

For questions or issues:

1. Check existing Storybook stories for usage examples
2. Review the type definitions in src/types/
3. Refer to the main monorepo documentation