smartopt-ui/README.md

Modern React UI component library with scoped CSS and CSS variables

# SmartOpt UI Components

Modern React UI component library with scoped CSS and CSS variables for consistent, customizable, and accessible components.

## 🚀 Features

- **Scoped CSS**: No conflicts with existing styles
- **CSS Variables**: Easy customization and theming
- **Modern React**: Built with React 18+ and modern JavaScript
- **Accessible**: WCAG compliant components
- **TypeScript Ready**: Full TypeScript support
- **Tree Shakeable**: Only import what you need
- **No Dependencies**: Minimal external dependencies

## 📦 Installation

```bash
npm install @smartopt/ui-components
```

## 🎨 Quick Start

### 1. Import CSS

```javascript
// Import the main CSS file
import '@smartopt/ui-components/styles';
```

### 2. Use Components

```jsx
import { Button, Input, Card } from '@smartopt/ui-components';

function App() {
  return (
    <Card>
      <Input placeholder="Enter your name" />
      <Button variant="primary">Submit</Button>
    </Card>
  );
}
```

## 🎯 Components

### Core Components

- **Button** - Versatile button with multiple variants
- **Input** - Form input with validation states
- **Card** - Container component with elevation options
- **Loading** - Loading indicators (spinner/dots)
- **Modal** - Overlay dialogs
- **Alert** - Notification messages
- **Tooltip** - Hover information

### Form Components

- **Select** - Dropdown selection
- **Checkbox** - Checkbox input
- **Radio** - Radio button group
- **Toggle** - Switch component

### Date/Time Components

- **DatePicker** - Date selection
- **TimePicker** - Time selection
- **DateTimePicker** - Combined date and time
- **RangePicker** - Date range selection

### Layout Components

- **Header** - Navigation header
- **Tabs** - Tab navigation
- **Sidebar** - Side navigation
- **Drawer** - Slide-out panels

## 🎨 Customization

### CSS Variables

Customize the look and feel using CSS variables:

```css
:root {
  --smartopt-primary: #007bff;
  --smartopt-secondary: #6c757d;
  --smartopt-success: #28a745;
  --smartopt-danger: #dc3545;
  --smartopt-warning: #ffc107;
  --smartopt-info: #17a2b8;
  
  /* Typography */
  --smartopt-font-family: 'Inter', sans-serif;
  --smartopt-font-size-sm: 0.875rem;
  
  /* Spacing */
  --smartopt-spacing-4: 1rem;
  
  /* Border Radius */
  --smartopt-radius-md: 0.375rem;
}
```

### Component Variants

```jsx
// Button variants
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="success">Success</Button>
<Button variant="danger">Danger</Button>
<Button variant="outline">Outline</Button>

// Button sizes
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

// Input states
<Input variant="default" placeholder="Default" />
<Input variant="error" placeholder="Error state" />
<Input variant="success" placeholder="Success state" />
```

## 🔧 Advanced Usage

### Context Providers

```jsx
import { AppProvider, useTheme, useAlert } from '@smartopt/ui-components';

function App() {
  return (
    <AppProvider>
      <MyApp />
    </AppProvider>
  );
}

function MyComponent() {
  const { darkMode, toggleTheme } = useTheme();
  const { addAlert } = useAlert();
  
  return (
    <Button onClick={() => addAlert({ type: 'success', message: 'Success!' })}>
      Show Alert
    </Button>
  );
}
```

### Custom Styling

```jsx
// Using className prop
<Button className="my-custom-button">Custom Button</Button>

// Using CSS variables
<div style={{ '--smartopt-primary': '#ff6b6b' }}>
  <Button variant="primary">Custom Color</Button>
</div>
```

## 📚 API Reference

### Button

```jsx
<Button
  variant="primary" // primary, secondary, success, danger, warning, info, light, dark, outline
  size="md" // sm, md, lg
  disabled={false}
  onClick={() => {}}
  className=""
>
  Button Text
</Button>
```

### Input

```jsx
<Input
  type="text" // text, email, password, number, tel, url
  variant="default" // default, error, success
  disabled={false}
  placeholder=""
  value=""
  onChange={(e) => {}}
  className=""
/>
```

### Card

```jsx
<Card
  variant="default" // default, elevated, bordered, flat
  className=""
>
  Card Content
</Card>
```

## 🎨 Theming

### Dark Mode

The library automatically supports dark mode using `prefers-color-scheme`:

```css
@media (prefers-color-scheme: dark) {
  :root {
    --smartopt-white: #1a1a1a;
    --smartopt-black: #ffffff;
    /* ... other dark mode variables */
  }
}
```

### Custom Theme

Create your own theme by overriding CSS variables:

```css
.my-theme {
  --smartopt-primary: #6366f1;
  --smartopt-secondary: #64748b;
  --smartopt-success: #10b981;
  --smartopt-danger: #ef4444;
  --smartopt-warning: #f59e0b;
  --smartopt-info: #06b6d4;
}
```

## 🚀 Development

### Setup

```bash
git clone https://github.com/smartopt/ui-components.git
cd ui-components
npm install
npm run dev
```

### Build

```bash
npm run build:lib
```

### Publish

```bash
npm publish
```

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📞 Support

- 📧 Email: support@smartopt.com
- 🐛 Issues: [GitHub Issues](https://github.com/smartopt/ui-components/issues)
- 📖 Documentation: [GitHub Wiki](https://github.com/smartopt/ui-components/wiki)

## 🔄 Changelog

See [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.