# @datacomvn/progress-and-modal

<div align="center">

![npm version](https://img.shields.io/npm/v/@datacomvn/progress-and-modal?style=flat-square)
![downloads](https://img.shields.io/npm/dm/@datacomvn/progress-and-modal?style=flat-square)
![license](https://img.shields.io/npm/l/@datacomvn/progress-and-modal?style=flat-square)
![platform](https://img.shields.io/badge/platform-iOS%20%7C%20Android-lightgrey?style=flat-square)

**🚀 Thư viện hiển thị Progress Loading, Lottie Animation và Toast thông minh cho React Native**

*Được phát triển bởi Datacom Vietnam | Powered by Nitro Modules*

[📚 Documentation](#-api-reference) • [🎯 Examples](#-examples) • [💬 Support](https://github.com/DeveloperDtc/react-native-progress-and-modal/issues)

</div>

---

## ✨ Tính năng nổi bật

- 🎯 **Native Performance** - Sử dụng Nitro Modules cho hiệu suất tối ưu
- 🎨 **Lottie Animations** - Hỗ trợ animation Lottie native mượt mà
- 🍞 **Smart Toast** - Toast tùy chỉnh với hình ảnh và animation
- ⚙️ **Highly Customizable** - Tùy chỉnh màu sắc, kích thước, thời gian
- 📱 **Cross Platform** - Hoạt động native trên cả iOS và Android
- 🎛️ **Easy Configuration** - Cấu hình đơn giản, sử dụng linh hoạt
- 🔥 **TypeScript Support** - Type definitions đầy đủ
- 🎪 **Multiple Loading States** - Spinner mặc định và Lottie loading
- 🛑 **Force Hide Control** - Khả năng ẩn tất cả loading trong trường hợp khẩn cấp

## 📦 Cài đặt

### Cài đặt package

```bash
# NPM
npm install @datacomvn/progress-and-modal react-native-nitro-modules

# Yarn
yarn add @datacomvn/progress-and-modal react-native-nitro-modules

# PNPM
pnpm add @datacomvn/progress-and-modal react-native-nitro-modules
```

### iOS Setup

```bash
cd ios && pod install
```

### Android Setup

Không cần cấu hình thêm cho Android.

> **💡 Lưu ý quan trọng:** `react-native-nitro-modules` là dependency bắt buộc. Tìm hiểu thêm tại [Nitro Documentation](https://nitro.margelo.com/)

## 🚀 Sử dụng cơ bản

```typescript
import {
  configure,
  showLoading,
  hideLoading,
  showLottie,
  hideLottie,
  forceHideLoading,
  showToast,
} from '@datacomvn/progress-and-modal';

// Import types (nếu cần)
import type {
  PAM_ConfigParams,
  PAM_LottieLoadingParams,
  PAM_ToastParams,
} from '@datacomvn/progress-and-modal';

// Cấu hình toàn cục (tùy chọn)
configure({
  backgroundAlpha: 0.3,
  indicatorColor: '#FF6B35',
});

// Hiển thị loading đơn giản
showLoading();

// Ẩn loading
hideLoading();

// Hiển thị toast
showToast({
  message: 'Thao tác thành công! 🎉',
  backgroundColor: '#4CAF50',
  textColor: '#FFFFFF',
  duration: 3000,
});
```

## 🎯 Examples

### 🔄 Basic Loading

```typescript
const handleBasicLoading = async () => {
  showLoading();
  
  try {
    await someAsyncOperation();
    showToast({
      message: 'Hoàn thành!',
      backgroundColor: '#4CAF50',
      textColor: '#FFFFFF',
    });
  } catch (error) {
    showToast({
      message: 'Có lỗi xảy ra!',
      backgroundColor: '#F44336',
      textColor: '#FFFFFF',
    });
  } finally {
    hideLoading();
  }
};
```

### 🎨 Lottie Loading với Custom Animation

```typescript
const handleLottieLoading = async () => {
  showLottie({
    lottie: require('./assets/loading_animation.json'),
    title: 'Đang xử lý dữ liệu',
    subtitle: 'Vui lòng chờ trong giây lát...',
  });
  
  await processData();
  
  hideLottie({ 
    lottie: require('./assets/done_animation.json'),
    title: 'Hoàn thành!',
  });
};
```

### 🍞 Advanced Toast với Icon

```typescript
const showSuccessToast = () => {
  showToast({
    message: 'Đã lưu thành công',
    backgroundColor: '#4CAF50',
    textColor: '#FFFFFF',
    fontSize: 16,
    image: require('./assets/ic_success.png'), // Truyền ảnh từ local bundle
    imageSize: 24,
    duration: 2500,
  });
};

const showErrorToast = () => {
  showToast({
    message: 'Không thể kết nối server',
    backgroundColor: '#F44336',
    textColor: '#FFFFFF',
    image: require('./assets/ic_error.png'),
    imageSize: 24,
  });
};
```

### 🛑 Force Hide Loading

```typescript
const handleForceStop = () => {
  // Trong trường hợp khẩn cấp, ẩn tất cả loading hiện tại
  forceHideLoading();
  
  showToast({
    message: 'Đã dừng tất cả loading',
    backgroundColor: '#FF9800',
    textColor: '#FFFFFF',
  });
};

// Sử dụng khi cần reset trạng thái loading
const handleReset = async () => {
  forceHideLoading(); // Đảm bảo không có loading nào đang hiển thị
  
  // Bắt đầu lottie loading mới
  showLottie({ 
    lottie: require('./assets/reset_animation.json'),
    title: 'Đang reset...' 
  });
  
  await resetApplication();
  hideLottie({ 
    lottie: require('./assets/success_animation.json'),
    title: 'Reset thành công!' 
  });
};
```

### 🎛️ Custom Configuration

```typescript
// Cấu hình cho giao diện tối
configure({
  backgroundAlpha: 0.8,
  indicatorColor: '#BB86FC',
});

// Hoặc cấu hình cho giao diện sáng
configure({
  backgroundAlpha: 0.2,
  indicatorColor: '#6200EE',
});
```

## 📖 API Reference

### `configure(params: PAM_ConfigParams)`

Cấu hình toàn cục cho loading indicators.

```typescript
interface PAM_ConfigParams {
  backgroundAlpha?: number; // 0.0 - 1.0, mặc định: 0.16
  indicatorColor?: string;  // Hex color, mặc định: '#666666'
}
```

### `showLoading()`

Hiển thị spinner loading mặc định ở giữa màn hình.

### `hideLoading()`

Ẩn spinner loading mặc định.

### `showLottie(params: PAM_LottieParams)`

Hiển thị loading với Lottie animation.

```typescript
interface PAM_LottieParams {
  lottie: any | string;      // require('./animation.json') hoặc tên asset native
  title?: string;            // Tiêu đề
  subtitle?: string;         // Phụ đề
}

// Sử dụng
showLottie({ 
  lottie: require('./my_animation.json'), 
  title: 'Đang tải...' 
});
```

### `hideLottie(params: PAM_LottieParams)`

Ẩn Lottie loading (thường dùng để hiển thị "Success/Done" animation trước khi đóng hẳn).

```typescript
hideLottie({ 
  lottie: require('./done.json'),
  title: 'Xong!'
});
```

### `forceHideLoading()`

Ẩn tất cả loading indicators hiện tại (bao gồm cả loading mặc định và Lottie).

```typescript
forceHideLoading(); // Ẩn tất cả loading đang hiển thị
```

### `showToast(params: PAM_ToastParams)`

Hiển thị toast notification.

```typescript
interface PAM_ToastParams {
  message: string;           // Nội dung toast (bắt buộc)
  backgroundColor: string;   // Màu nền (bắt buộc)
  textColor: string;        // Màu chữ (bắt buộc)
  fontSize?: number;        // Kích thước font (dp)
  image?: any | string;     // Truyền require('./image.png') 
  imageSize?: number;       // Kích thước ảnh (dp), mặc định: 24
  duration?: number;        // Thời gian hiển thị (ms), mặc định: 2000
}
```

## 🎨 Cấu hình Assets

> [!TIP]
> Bạn khuyến khích truyền thẳng `require('./path/to/asset')` qua params của thư viện để tận dụng Hot Reload và giảm dung lượng Native Bundle. Nếu bạn dùng string cũ tích hợp bằng tay vào Native Asset, hãy bỏ qua mục này để xem tham khảo.


## 🛠️ Troubleshooting

### ❌ Common Issues

**Metro bundler không tìm thấy module:**
```bash
# Clear cache và restart
npx react-native start --reset-cache
```

**iOS build lỗi sau khi install:**
```bash
cd ios && pod install --clean-install
```

**Android build lỗi:**
```bash
cd android && ./gradlew clean
```

**Lottie animation không hiển thị:**
- ✅ Kiểm tra file `.json` đã được thêm vào native project
- ✅ Tên file không chứa ký tự đặc biệt
- ✅ File size không quá lớn (khuyến nghị < 500KB)

**Toast icon không hiển thị:**
- ✅ Kiểm tra tên file không có extension
- ✅ File đã được thêm vào đúng thư mục native
- ✅ Rebuild app sau khi thêm assets

## 📋 Example App

Xem example app đầy đủ trong thư mục [`/example`](./example) để tham khảo implementation chi tiết.

```bash
# Chạy example app
cd example
npm install
npx react-native run-ios
# hoặc
npx react-native run-android
```

## 🤝 Contributing

Chúng tôi rất hoan nghênh các đóng góp! Xem [CONTRIBUTING.md](CONTRIBUTING.md) để biết thêm chi tiết.

### Development Setup

```bash
# Clone repository
git clone https://github.com/DeveloperDtc/react-native-progress-and-modal.git
cd react-native-progress-and-modal

# Install dependencies
yarn install

# Setup example app
cd example
yarn install
npx pod-install ios # Chỉ cho iOS
```

## 📋 Requirements

- React Native >= 0.70.0
- iOS >= 11.0
- Android API Level >= 21
- Node.js >= 16

## 📄 License

MIT License - xem [LICENSE](LICENSE) để biết thêm chi tiết.

## 🙏 Credits

- **Nitro Modules** - [margelo.com](https://nitro.margelo.com/)
- **React Native Builder Bob** - [callstack.com](https://github.com/callstack/react-native-builder-bob)
- **Lottie React Native** - [lottiefiles.com](https://lottiefiles.com/)

---

<div align="center">

**Made with ❤️ by [Datacom Vietnam](https://datacom.vn)**

[🌟 Star us on GitHub](https://github.com/DeveloperDtc/react-native-progress-and-modal) • [🐛 Report Issues](https://github.com/DeveloperDtc/react-native-progress-and-modal/issues) • [💬 Discussions](https://github.com/DeveloperDtc/react-native-progress-and-modal/discussions)

</div>