modern-react-ui-components/README.md

Modern React + TypeScript component library with Toaster, Input, and DatePicker components

# Modern React UI Components

[![npm version](https://badge.fury.io/js/modern-react-ui-components.svg)](https://www.npmjs.com/package/modern-react-ui-components)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A modern, reusable React + TypeScript component library featuring Toaster, Input, and DatePicker components with beautiful design and accessibility features.

## 📦 NPM Package

**This component library is now published on npm!**

```bash
npm install modern-react-ui-components
```

**👉 [View complete NPM usage guide](./NPM_USAGE_GUIDE.md) for installation instructions, import examples, and detailed prop documentation.**

## 🚀 Features

- **Modern React + TypeScript**: Built with latest React 18 and TypeScript for type safety
- **Accessible**: Full ARIA support and keyboard navigation
- **Customizable**: Multiple sizes, states, and styling options
- **Tree-shakeable**: ESM + CommonJS bundles for optimal performance
- **CSS Modules**: Scoped styling to prevent conflicts

## 📦 Local Development Installation

For local development of this library:

```bash
npm install
# or
yarn install
# or
pnpm install
```

For using the published package in your project, see the [NPM Usage Guide](./NPM_USAGE_GUIDE.md).

## 🧩 Components

### Toaster

Interactive toast notifications with four different states:

```tsx
// For NPM package usage:
import { Toaster, ToasterWithSpecs } from 'modern-react-ui-components';
import 'modern-react-ui-components/dist/style.css';

// For local development:
// import { Toaster, ToasterWithSpecs } from './src/components';

function App() {
  return (
    <div>
      {/* Individual toaster */}
      <Toaster
        type="success"
        message="Operation completed successfully!"
        onDismiss={() => console.log('dismissed')}
        autoHide={true}
        autoHideDelay={5000}
      />

      {/* Toaster with measurement specifications */}
      <ToasterWithSpecs
        type="success"
        message="We just released something new!"
        showSpecs={true}
      />
    </div>
  );
}
```

#### Toaster Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `type` | `'success' \| 'failed' \| 'info' \| 'attention'` | - | Toast type/state |
| `message` | `string` | - | Toast message content |
| `onDismiss` | `() => void` | - | Callback when toast is dismissed |
| `autoHide` | `boolean` | `true` | Auto-hide the toast |
| `autoHideDelay` | `number` | `5000` | Auto-hide delay in milliseconds |
| `className` | `string` | - | Additional CSS class |

#### Color Tokens

| State | Background Color | Icon Color |
|-------|------------------|------------|
| Success | #A6F5D6 | #003134 |
| Failed | #FAADAC | #003134 |
| Info | #CCFFFF | #003134 |
| Attention | #FFEBAD | #003134 |

### Input

Form input component with multiple states and accessibility features:

```tsx
// For NPM package usage:
import { Input } from 'modern-react-ui-components';
import 'modern-react-ui-components/dist/style.css';

// For local development:
// import { Input } from './src/components';

function MyForm() {
  const [value, setValue] = useState('');

  return (
    <Input
      label="Email Address"
      placeholder="Enter your email"
      helperText="We'll never share your email"
      errorText={value.includes('@') ? '' : 'Please enter a valid email'}
      size="medium"
      value={value}
      onChange={(e) => setValue(e.target.value)}
      fullWidth
    />
  );
}
```

#### Input Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | - | Input label |
| `helperText` | `string` | - | Helper text below input |
| `errorText` | `string` | - | Error message (overrides helperText) |
| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Input size variant |
| `state` | `'default' \| 'hover' \| 'focus' \| 'active' \| 'error' \| 'disabled'` | - | Force specific state |
| `fullWidth` | `boolean` | `false` | Make input full width |
| `disabled` | `boolean` | `false` | Disable the input |

#### State Colors

| State | Border Color |
|-------|--------------|
| Default/Active | #555555 |
| Hover | #003134 |
| Focus | #007173 |
| Error | #C4221F |
| Disabled | #555555 |

## 🎨 Preview

Run the preview application to see all components in action:

```bash
# Install dependencies
npm install

# Install preview dependencies
npm run preview:install

# Run preview
npm run preview
```

## 🏗️ Development

```bash
# Install dependencies
npm install

# Build the library
npm run build

# Run type checking
npm run type-check

# Run linting
npm run lint

# Watch mode for development
npm run dev
```

## 📁 Project Structure

```
├── src/
│   ├── components/
│   │   ├── Toaster/
│   │   │   ├── Toaster.tsx
│   │   │   ├── Toaster.module.css
│   │   │   ├── ToastContainer.tsx
│   │   │   └── ToastContainer.module.css
│   │   └── Input/
│   │       ├── Input.tsx
│   │       └── Input.module.css
│   └── index.ts
├── preview/          # Preview application
├── dist/            # Built library (after npm run build)
└── package.json
```

## 📤 Publishing

1. Build the library:
   ```bash
   npm run build
   ```

2. Update version in `package.json`

3. Login to npm (if not already logged in):
   ```bash
   npm login
   ```

4. Publish to npm:
   ```bash
   npm publish --access public
   ```

## 🔧 Bundle Information

- **ESM**: `dist/index.es.js`
- **CommonJS**: `dist/index.cjs.js`
- **Types**: `dist/index.d.ts`
- **CSS**: Bundled with components using CSS Modules

## 🎯 Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## 📄 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

For support, please open an issue in the GitHub repository.