# os-micro-frontend-shared

> Shared React component library for Tap Payments micro frontends

[![npm version](https://img.shields.io/npm/v/@tap-payments/os-micro-frontend-shared)](https://www.npmjs.com/package/@tap-payments/os-micro-frontend-shared)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

## What is this?

A comprehensive React component library providing:

- **100+ UI components** (buttons, tables, dialogs, forms, filters)
- **18 custom hooks** (toast, window dimensions, theme mode)
- **47 utility modules** (date/currency formatting, validation)
- **Full TypeScript support** with type definitions
- **MUI-based theming** with dark/light modes and RTL/LTR support
- **High-performance virtual tables** for large datasets

## Quick Start

```bash
npm install @tap-payments/os-micro-frontend-shared
# or
yarn add @tap-payments/os-micro-frontend-shared
```

```typescript
import { Button, VirtualTable, useToast } from '@tap-payments/os-micro-frontend-shared'

function MyApp() {
  const toast = useToast()

  return (
    <Button variant="confirm" onClick={() => toast.success('Hello!')}>
      Click me
    </Button>
  )
}
```

## Documentation

📚 **[Full Documentation →](./docs/overview.md)**

| Document                                         | Description                              | Read Time |
| ------------------------------------------------ | ---------------------------------------- | --------- |
| **[Quick Reference](./docs/quick_reference.md)** | Cheat sheet, snippets, common tasks      | 5 min     |
| **[Overview](./docs/overview.md)**               | Architecture, patterns, design decisions | 15 min    |
| **[Setup & Stack](./docs/setup_and_stack.md)**   | Installation, development, workflows     | 10 min    |
| **[Component Guide](./docs/component_guide.md)** | All components categorized with examples | Reference |

**For AI Agents**: Start with [quick_reference.md](./docs/quick_reference.md) for instant context.

**For Developers**: Read in order: [quick_reference](./docs/quick_reference.md) → [overview](./docs/overview.md) → [setup_and_stack](./docs/setup_and_stack.md).

## Key Features

- ✅ **ESM-only** - Modern module system with tree-shaking
- ✅ **Peer dependencies** - Avoid version conflicts
- ✅ **Full TypeScript** - Complete type safety
- ✅ **100+ Components** - Comprehensive UI library
- ✅ **Virtual tables** - High-performance lists
- ✅ **React Hook Form** - Integrated form components
- ✅ **Theming** - Dark/light modes, RTL/LTR
- ✅ **Memoized** - Optimized for performance

## Development

```bash
# Install dependencies
yarn install

# Start dev server
yarn dev

# Build library
yarn build

# Test locally in another project
yarn push:local   # requires yalc
```

See [Setup & Stack Guide](./docs/setup_and_stack.md) for detailed instructions.

## Publishing

### Automated (Recommended)

Merging a PR to `main` automatically:

1. Bumps patch version
2. Commits version change
3. Builds library
4. Publishes to npm

### Manual

```bash
# Test version (with -test tag)
yarn push:test

# Production
yarn push
```

See [Publishing Documentation](./docs/setup_and_stack.md#staging-vs-production-publishing) for details.

## Contributing

1. Create feature branch
2. Make changes in `src/`
3. Run `yarn lint:fix` and `yarn prettier:fix`
4. Commit (pre-commit hooks will run)
5. Push and create PR to `main`

See [Development Workflows](./docs/setup_and_stack.md#common-workflows) for detailed guide.

## Project Structure

```
src/
├── components/      # 100+ React components
├── hooks/          # 18 custom React hooks
├── utils/          # 47 utility modules
├── types/          # TypeScript type definitions
├── constants/      # App constants and configs
└── theme/          # MUI theme configuration
```

See [Folder Structure](./docs/overview.md#folder--module-structure) for details.

## Tech Stack

- React 18 + TypeScript 5
- MUI (Material-UI) 5 + Emotion
- React Hook Form + Yup
- Vite 6 (build + dev)
- ESLint + Prettier

See [Tech Stack Details](./docs/setup_and_stack.md#tech-stack) for complete list.

## License

MIT © [Tap Payments](https://tap.company)

---

## Links

- [npm Package](https://www.npmjs.com/package/@tap-payments/os-micro-frontend-shared)
- [Documentation](./docs/)
- [Tap Payments](https://tap.company)

## Support

For issues, questions, or contributions, please refer to the [documentation](./docs/) or create an issue.