update products
This commit is contained in:
Phuoc Nguyen
340
docs/BARREL_EXPORTS_QUICK_REFERENCE.md
Normal file
340
docs/BARREL_EXPORTS_QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,340 @@
|
||||
# Barrel Exports Quick Reference
|
||||
|
||||
## Quick Import Guide
|
||||
|
||||
### Complete Feature Import
|
||||
```dart
|
||||
// Import entire auth feature (all layers)
|
||||
import 'package:retail/features/auth/auth.dart';
|
||||
|
||||
// Import entire products feature
|
||||
import 'package:retail/features/products/products.dart';
|
||||
|
||||
// Import entire categories feature
|
||||
import 'package:retail/features/categories/categories.dart';
|
||||
|
||||
// Import entire home/cart feature
|
||||
import 'package:retail/features/home/home.dart';
|
||||
|
||||
// Import entire settings feature
|
||||
import 'package:retail/features/settings/settings.dart';
|
||||
|
||||
// Import ALL features at once
|
||||
import 'package:retail/features/features.dart';
|
||||
```
|
||||
|
||||
### Layer-Specific Imports
|
||||
```dart
|
||||
// Auth layers
|
||||
import 'package:retail/features/auth/data/data.dart'; // Data layer only
|
||||
import 'package:retail/features/auth/domain/domain.dart'; // Domain layer only
|
||||
import 'package:retail/features/auth/presentation/presentation.dart'; // Presentation only
|
||||
|
||||
// Products layers
|
||||
import 'package:retail/features/products/data/data.dart';
|
||||
import 'package:retail/features/products/domain/domain.dart';
|
||||
import 'package:retail/features/products/presentation/presentation.dart';
|
||||
|
||||
// Categories layers
|
||||
import 'package:retail/features/categories/data/data.dart';
|
||||
import 'package:retail/features/categories/domain/domain.dart';
|
||||
import 'package:retail/features/categories/presentation/presentation.dart';
|
||||
|
||||
// Home/Cart layers
|
||||
import 'package:retail/features/home/data/data.dart';
|
||||
import 'package:retail/features/home/domain/domain.dart';
|
||||
import 'package:retail/features/home/presentation/presentation.dart';
|
||||
|
||||
// Settings layers
|
||||
import 'package:retail/features/settings/data/data.dart';
|
||||
import 'package:retail/features/settings/domain/domain.dart';
|
||||
import 'package:retail/features/settings/presentation/presentation.dart';
|
||||
```
|
||||
|
||||
### Component-Specific Imports
|
||||
```dart
|
||||
// Models
|
||||
import 'package:retail/features/products/data/models/models.dart';
|
||||
import 'package:retail/features/auth/data/models/models.dart';
|
||||
|
||||
// Entities
|
||||
import 'package:retail/features/products/domain/entities/entities.dart';
|
||||
import 'package:retail/features/home/domain/entities/entities.dart';
|
||||
|
||||
// Use Cases
|
||||
import 'package:retail/features/products/domain/usecases/usecases.dart';
|
||||
import 'package:retail/features/categories/domain/usecases/usecases.dart';
|
||||
|
||||
// Providers
|
||||
import 'package:retail/features/products/presentation/providers/providers.dart';
|
||||
import 'package:retail/features/home/presentation/providers/providers.dart';
|
||||
|
||||
// Pages
|
||||
import 'package:retail/features/products/presentation/pages/pages.dart';
|
||||
import 'package:retail/features/auth/presentation/pages/pages.dart';
|
||||
|
||||
// Widgets
|
||||
import 'package:retail/features/products/presentation/widgets/widgets.dart';
|
||||
import 'package:retail/features/auth/presentation/widgets/widgets.dart';
|
||||
```
|
||||
|
||||
### Core Utilities
|
||||
```dart
|
||||
// All core utilities
|
||||
import 'package:retail/core/core.dart';
|
||||
|
||||
// Specific core modules
|
||||
import 'package:retail/core/constants/constants.dart'; // All constants
|
||||
import 'package:retail/core/theme/theme.dart'; // Theme configuration
|
||||
import 'package:retail/core/network/network.dart'; // HTTP & network
|
||||
import 'package:retail/core/errors/errors.dart'; // Exceptions & failures
|
||||
import 'package:retail/core/utils/utils.dart'; // Utilities & helpers
|
||||
import 'package:retail/core/di/di.dart'; // Dependency injection
|
||||
import 'package:retail/core/database/database.dart'; // Hive database
|
||||
import 'package:retail/core/storage/storage.dart'; // Secure storage
|
||||
import 'package:retail/core/widgets/widgets.dart'; // Core widgets
|
||||
```
|
||||
|
||||
### Shared Components
|
||||
```dart
|
||||
// Shared widgets and components
|
||||
import 'package:retail/shared/shared.dart';
|
||||
```
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### Building a Page
|
||||
```dart
|
||||
// In a page file, you typically need presentation layer
|
||||
import 'package:retail/features/products/presentation/presentation.dart';
|
||||
// This gives you: pages, widgets, providers
|
||||
```
|
||||
|
||||
### Implementing a Repository
|
||||
```dart
|
||||
// In repository implementation, import domain interfaces
|
||||
import 'package:retail/features/products/domain/domain.dart';
|
||||
// This gives you: entities, repository interfaces, use cases
|
||||
```
|
||||
|
||||
### Creating a Provider
|
||||
```dart
|
||||
// In a provider, import domain layer and other providers
|
||||
import 'package:retail/features/products/domain/domain.dart';
|
||||
import 'package:retail/features/products/presentation/providers/providers.dart';
|
||||
```
|
||||
|
||||
### Using Multiple Features
|
||||
```dart
|
||||
// When you need multiple features
|
||||
import 'package:retail/features/products/products.dart';
|
||||
import 'package:retail/features/categories/categories.dart';
|
||||
import 'package:retail/core/core.dart';
|
||||
```
|
||||
|
||||
## Layer Dependencies (Important!)
|
||||
|
||||
### Allowed Dependencies
|
||||
|
||||
```
|
||||
Presentation Layer:
|
||||
✅ Can import: domain, core, shared
|
||||
❌ Cannot import: data
|
||||
|
||||
Data Layer:
|
||||
✅ Can import: domain, core
|
||||
❌ Cannot import: presentation
|
||||
|
||||
Domain Layer:
|
||||
✅ Can import: core (only exceptions/interfaces)
|
||||
❌ Cannot import: data, presentation
|
||||
|
||||
Core:
|
||||
✅ Can import: nothing (self-contained)
|
||||
❌ Cannot import: features
|
||||
|
||||
Shared:
|
||||
✅ Can import: core
|
||||
❌ Cannot import: features (to avoid circular dependencies)
|
||||
```
|
||||
|
||||
### Example: Correct Dependencies
|
||||
|
||||
```dart
|
||||
// ✅ GOOD: Presentation imports domain
|
||||
// In: features/products/presentation/pages/products_page.dart
|
||||
import 'package:retail/features/products/domain/domain.dart';
|
||||
import 'package:retail/core/core.dart';
|
||||
|
||||
// ✅ GOOD: Data imports domain
|
||||
// In: features/products/data/repositories/product_repository_impl.dart
|
||||
import 'package:retail/features/products/domain/domain.dart';
|
||||
import 'package:retail/core/core.dart';
|
||||
|
||||
// ✅ GOOD: Domain is independent
|
||||
// In: features/products/domain/entities/product.dart
|
||||
import 'package:retail/core/errors/errors.dart'; // Only core exceptions
|
||||
|
||||
// ❌ BAD: Domain importing data or presentation
|
||||
// In: features/products/domain/usecases/get_products.dart
|
||||
import 'package:retail/features/products/data/data.dart'; // NEVER!
|
||||
import 'package:retail/features/products/presentation/presentation.dart'; // NEVER!
|
||||
```
|
||||
|
||||
## Import Decision Tree
|
||||
|
||||
```
|
||||
1. Do I need the entire feature?
|
||||
├─ Yes → import 'features/[feature]/[feature].dart'
|
||||
└─ No → Continue to 2
|
||||
|
||||
2. Do I need an entire layer?
|
||||
├─ Yes → import 'features/[feature]/[layer]/[layer].dart'
|
||||
└─ No → Continue to 3
|
||||
|
||||
3. Do I need specific components?
|
||||
└─ Yes → import 'features/[feature]/[layer]/[component]/[component].dart'
|
||||
|
||||
4. Is it a core utility?
|
||||
├─ All utilities → import 'core/core.dart'
|
||||
└─ Specific module → import 'core/[module]/[module].dart'
|
||||
|
||||
5. Is it a shared component?
|
||||
└─ Yes → import 'shared/shared.dart'
|
||||
```
|
||||
|
||||
## Migration from Direct Imports
|
||||
|
||||
### Before (Direct Imports - Fragile)
|
||||
```dart
|
||||
import 'package:retail/features/products/data/models/product_model.dart';
|
||||
import 'package:retail/features/products/data/datasources/product_local_datasource.dart';
|
||||
import 'package:retail/features/products/data/repositories/product_repository_impl.dart';
|
||||
import 'package:retail/features/products/domain/entities/product.dart';
|
||||
import 'package:retail/features/products/domain/repositories/product_repository.dart';
|
||||
import 'package:retail/features/products/presentation/pages/products_page.dart';
|
||||
import 'package:retail/features/products/presentation/widgets/product_card.dart';
|
||||
import 'package:retail/features/products/presentation/widgets/product_grid.dart';
|
||||
import 'package:retail/core/constants/api_constants.dart';
|
||||
import 'package:retail/core/theme/colors.dart';
|
||||
```
|
||||
|
||||
### After (Barrel Imports - Clean & Maintainable)
|
||||
```dart
|
||||
import 'package:retail/features/products/products.dart';
|
||||
import 'package:retail/core/core.dart';
|
||||
```
|
||||
|
||||
## Special Notes
|
||||
|
||||
### Products Providers
|
||||
The products feature has all providers consolidated in `products_provider.dart`:
|
||||
```dart
|
||||
// Import all product providers at once
|
||||
import 'package:retail/features/products/presentation/providers/providers.dart';
|
||||
|
||||
// This includes:
|
||||
// - productsProvider (list of products)
|
||||
// - searchQueryProvider (search state)
|
||||
// - filteredProductsProvider (filtered results)
|
||||
```
|
||||
|
||||
### Selected Category Provider
|
||||
The `selectedCategoryProvider` exists in multiple places:
|
||||
- In `categories_provider.dart` (for category management)
|
||||
- In `products/selected_category_provider.dart` (for product filtering)
|
||||
|
||||
Use the one from products when filtering products:
|
||||
```dart
|
||||
import 'package:retail/features/products/presentation/providers/providers.dart';
|
||||
// Use: selectedCategoryProvider for product filtering
|
||||
```
|
||||
|
||||
### Core Providers
|
||||
Core providers are in `core/providers/providers.dart`:
|
||||
```dart
|
||||
import 'package:retail/core/providers/providers.dart';
|
||||
// Includes: networkInfoProvider, syncStatusProvider
|
||||
```
|
||||
|
||||
## Tips for Best Practices
|
||||
|
||||
1. **Start broad, narrow down if needed**
|
||||
- Try feature-level import first
|
||||
- Move to layer-level if you only need one layer
|
||||
- Use component-level for very specific needs
|
||||
|
||||
2. **Avoid circular dependencies**
|
||||
- Domain never imports from data/presentation
|
||||
- Features don't import from each other (use shared instead)
|
||||
|
||||
3. **Use IDE autocomplete**
|
||||
- Type `import 'package:retail/` and let IDE suggest
|
||||
- Barrel exports will show up clearly
|
||||
|
||||
4. **Keep imports organized**
|
||||
```dart
|
||||
// 1. Dart/Flutter imports
|
||||
import 'package:flutter/material.dart';
|
||||
|
||||
// 2. Third-party packages
|
||||
import 'package:riverpod_annotation/riverpod_annotation.dart';
|
||||
|
||||
// 3. Project features
|
||||
import 'package:retail/features/products/products.dart';
|
||||
|
||||
// 4. Core utilities
|
||||
import 'package:retail/core/core.dart';
|
||||
|
||||
// 5. Shared components
|
||||
import 'package:retail/shared/shared.dart';
|
||||
```
|
||||
|
||||
5. **Update barrel exports when adding files**
|
||||
- Added new model? Update `models/models.dart`
|
||||
- Added new page? Update `pages/pages.dart`
|
||||
- New use case? Update `usecases/usecases.dart`
|
||||
|
||||
## File Locations Reference
|
||||
|
||||
```
|
||||
Core Barrel Exports:
|
||||
/lib/core/core.dart
|
||||
/lib/core/config/config.dart
|
||||
/lib/core/constants/constants.dart
|
||||
/lib/core/database/database.dart
|
||||
/lib/core/di/di.dart
|
||||
/lib/core/errors/errors.dart
|
||||
/lib/core/network/network.dart
|
||||
/lib/core/storage/storage.dart
|
||||
/lib/core/theme/theme.dart
|
||||
/lib/core/utils/utils.dart
|
||||
|
||||
Feature Barrel Exports:
|
||||
/lib/features/features.dart
|
||||
/lib/features/auth/auth.dart
|
||||
/lib/features/products/products.dart
|
||||
/lib/features/categories/categories.dart
|
||||
/lib/features/home/home.dart
|
||||
/lib/features/settings/settings.dart
|
||||
|
||||
Shared Barrel Exports:
|
||||
/lib/shared/shared.dart
|
||||
```
|
||||
|
||||
## Quick Command Reference
|
||||
|
||||
```bash
|
||||
# Find all barrel export files
|
||||
find lib -name "*.dart" -type f | grep -E "\/(data|domain|presentation|entities|models|usecases|providers|pages|widgets|datasources|constants|errors|network|storage|theme|utils|di|config|database)\.dart$"
|
||||
|
||||
# Check for ambiguous exports
|
||||
flutter analyze | grep "ambiguous_export"
|
||||
|
||||
# Verify imports compile
|
||||
flutter analyze
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember:** Barrel exports make your code cleaner, more maintainable, and easier to refactor!
|
||||
500
docs/EXPORTS_DOCUMENTATION.md
Normal file
500
docs/EXPORTS_DOCUMENTATION.md
Normal file
@@ -0,0 +1,500 @@
|
||||
# Clean Architecture Export Files Documentation
|
||||
|
||||
This document describes all barrel export files created for the retail POS application, following clean architecture principles.
|
||||
|
||||
## Overview
|
||||
|
||||
Barrel export files provide a clean, organized way to import code by:
|
||||
- Simplifying imports across the codebase
|
||||
- Enforcing layer separation and boundaries
|
||||
- Making refactoring easier
|
||||
- Improving IDE autocomplete
|
||||
- Documenting module structure
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
lib/
|
||||
├── core/
|
||||
│ ├── core.dart # Main core export
|
||||
│ ├── config/
|
||||
│ │ └── config.dart # Configuration exports
|
||||
│ ├── constants/
|
||||
│ │ └── constants.dart # All constants
|
||||
│ ├── database/
|
||||
│ │ └── database.dart # Database utilities
|
||||
│ ├── di/
|
||||
│ │ └── di.dart # Dependency injection
|
||||
│ ├── errors/
|
||||
│ │ └── errors.dart # Exceptions & failures
|
||||
│ ├── network/
|
||||
│ │ └── network.dart # HTTP & network
|
||||
│ ├── storage/
|
||||
│ │ └── storage.dart # Secure storage
|
||||
│ ├── theme/
|
||||
│ │ └── theme.dart # Material 3 theme
|
||||
│ ├── utils/
|
||||
│ │ └── utils.dart # Utilities & helpers
|
||||
│ └── widgets/
|
||||
│ └── widgets.dart # Core widgets (already exists)
|
||||
├── features/
|
||||
│ ├── features.dart # Main features export
|
||||
│ ├── auth/
|
||||
│ │ ├── auth.dart # Main auth export
|
||||
│ │ ├── data/
|
||||
│ │ │ ├── data.dart # Auth data layer
|
||||
│ │ │ ├── datasources/
|
||||
│ │ │ └── models/
|
||||
│ │ │ └── models.dart # Auth models
|
||||
│ │ ├── domain/
|
||||
│ │ │ ├── domain.dart # Auth domain layer
|
||||
│ │ │ └── entities/
|
||||
│ │ │ └── entities.dart # Auth entities
|
||||
│ │ └── presentation/
|
||||
│ │ ├── presentation.dart # Auth presentation layer
|
||||
│ │ ├── pages/
|
||||
│ │ │ └── pages.dart # Auth pages
|
||||
│ │ └── widgets/
|
||||
│ │ └── widgets.dart # Auth widgets
|
||||
│ ├── categories/
|
||||
│ │ ├── categories.dart # Main categories export
|
||||
│ │ ├── data/
|
||||
│ │ │ ├── data.dart # Categories data layer
|
||||
│ │ │ ├── datasources/
|
||||
│ │ │ │ └── datasources.dart # Category data sources
|
||||
│ │ │ └── models/
|
||||
│ │ │ └── models.dart # Category models
|
||||
│ │ ├── domain/
|
||||
│ │ │ ├── domain.dart # Categories domain layer
|
||||
│ │ │ ├── entities/
|
||||
│ │ │ │ └── entities.dart # Category entities
|
||||
│ │ │ └── usecases/
|
||||
│ │ │ └── usecases.dart # Category use cases
|
||||
│ │ └── presentation/
|
||||
│ │ ├── presentation.dart # Categories presentation layer
|
||||
│ │ ├── pages/
|
||||
│ │ │ └── pages.dart # Category pages
|
||||
│ │ ├── providers/
|
||||
│ │ │ └── providers.dart # Category providers (already exists)
|
||||
│ │ └── widgets/
|
||||
│ │ └── widgets.dart # Category widgets (already exists)
|
||||
│ ├── home/
|
||||
│ │ ├── home.dart # Main home/cart export
|
||||
│ │ ├── data/
|
||||
│ │ │ ├── data.dart # Cart data layer
|
||||
│ │ │ ├── datasources/
|
||||
│ │ │ │ └── datasources.dart # Cart data sources
|
||||
│ │ │ └── models/
|
||||
│ │ │ └── models.dart # Cart models
|
||||
│ │ ├── domain/
|
||||
│ │ │ ├── domain.dart # Cart domain layer
|
||||
│ │ │ ├── entities/
|
||||
│ │ │ │ └── entities.dart # Cart entities
|
||||
│ │ │ └── usecases/
|
||||
│ │ │ └── usecases.dart # Cart use cases
|
||||
│ │ └── presentation/
|
||||
│ │ ├── presentation.dart # Cart presentation layer
|
||||
│ │ ├── pages/
|
||||
│ │ │ └── pages.dart # Cart pages
|
||||
│ │ ├── providers/
|
||||
│ │ │ └── providers.dart # Cart providers (already exists)
|
||||
│ │ └── widgets/
|
||||
│ │ └── widgets.dart # Cart widgets (already exists)
|
||||
│ ├── products/
|
||||
│ │ ├── products.dart # Main products export
|
||||
│ │ ├── data/
|
||||
│ │ │ ├── data.dart # Products data layer
|
||||
│ │ │ ├── datasources/
|
||||
│ │ │ │ └── datasources.dart # Product data sources
|
||||
│ │ │ └── models/
|
||||
│ │ │ └── models.dart # Product models
|
||||
│ │ ├── domain/
|
||||
│ │ │ ├── domain.dart # Products domain layer
|
||||
│ │ │ ├── entities/
|
||||
│ │ │ │ └── entities.dart # Product entities
|
||||
│ │ │ └── usecases/
|
||||
│ │ │ └── usecases.dart # Product use cases
|
||||
│ │ └── presentation/
|
||||
│ │ ├── presentation.dart # Products presentation layer
|
||||
│ │ ├── pages/
|
||||
│ │ │ └── pages.dart # Product pages
|
||||
│ │ ├── providers/
|
||||
│ │ │ └── providers.dart # Product providers
|
||||
│ │ └── widgets/
|
||||
│ │ └── widgets.dart # Product widgets (already exists)
|
||||
│ └── settings/
|
||||
│ ├── settings.dart # Main settings export
|
||||
│ ├── data/
|
||||
│ │ ├── data.dart # Settings data layer
|
||||
│ │ ├── datasources/
|
||||
│ │ │ └── datasources.dart # Settings data sources
|
||||
│ │ └── models/
|
||||
│ │ └── models.dart # Settings models
|
||||
│ ├── domain/
|
||||
│ │ ├── domain.dart # Settings domain layer
|
||||
│ │ ├── entities/
|
||||
│ │ │ └── entities.dart # Settings entities
|
||||
│ │ └── usecases/
|
||||
│ │ └── usecases.dart # Settings use cases
|
||||
│ └── presentation/
|
||||
│ ├── presentation.dart # Settings presentation layer
|
||||
│ ├── pages/
|
||||
│ │ └── pages.dart # Settings pages
|
||||
│ ├── providers/
|
||||
│ │ └── providers.dart # Settings providers (already exists)
|
||||
│ └── widgets/
|
||||
│ └── widgets.dart # Settings widgets
|
||||
└── shared/
|
||||
└── shared.dart # Shared components export
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### 1. Importing Entire Features
|
||||
|
||||
```dart
|
||||
// Import complete auth feature (all layers)
|
||||
import 'package:retail/features/auth/auth.dart';
|
||||
|
||||
// Import complete products feature
|
||||
import 'package:retail/features/products/products.dart';
|
||||
|
||||
// Import all features at once
|
||||
import 'package:retail/features/features.dart';
|
||||
```
|
||||
|
||||
### 2. Importing Specific Layers
|
||||
|
||||
```dart
|
||||
// Import only auth domain layer (entities + repositories)
|
||||
import 'package:retail/features/auth/domain/domain.dart';
|
||||
|
||||
// Import only products presentation layer (pages + widgets + providers)
|
||||
import 'package:retail/features/products/presentation/presentation.dart';
|
||||
|
||||
// Import only cart data layer
|
||||
import 'package:retail/features/home/data/data.dart';
|
||||
```
|
||||
|
||||
### 3. Importing Specific Components
|
||||
|
||||
```dart
|
||||
// Import only auth entities
|
||||
import 'package:retail/features/auth/domain/entities/entities.dart';
|
||||
|
||||
// Import only product models
|
||||
import 'package:retail/features/products/data/models/models.dart';
|
||||
|
||||
// Import only category use cases
|
||||
import 'package:retail/features/categories/domain/usecases/usecases.dart';
|
||||
|
||||
// Import only product providers
|
||||
import 'package:retail/features/products/presentation/providers/providers.dart';
|
||||
```
|
||||
|
||||
### 4. Importing Core Utilities
|
||||
|
||||
```dart
|
||||
// Import all core utilities
|
||||
import 'package:retail/core/core.dart';
|
||||
|
||||
// Import only constants
|
||||
import 'package:retail/core/constants/constants.dart';
|
||||
|
||||
// Import only theme
|
||||
import 'package:retail/core/theme/theme.dart';
|
||||
|
||||
// Import only network utilities
|
||||
import 'package:retail/core/network/network.dart';
|
||||
|
||||
// Import only error handling
|
||||
import 'package:retail/core/errors/errors.dart';
|
||||
```
|
||||
|
||||
### 5. Importing Shared Components
|
||||
|
||||
```dart
|
||||
// Import shared widgets
|
||||
import 'package:retail/shared/shared.dart';
|
||||
```
|
||||
|
||||
## Clean Architecture Benefits
|
||||
|
||||
### Layer Isolation
|
||||
|
||||
The export structure enforces clean architecture principles:
|
||||
|
||||
```dart
|
||||
// ✅ GOOD: Domain layer importing from domain
|
||||
import 'package:retail/features/products/domain/domain.dart';
|
||||
|
||||
// ❌ BAD: Domain layer importing from data/presentation
|
||||
// Domain should never depend on outer layers
|
||||
import 'package:retail/features/products/data/data.dart';
|
||||
```
|
||||
|
||||
### Dependency Flow
|
||||
|
||||
Dependencies flow inward:
|
||||
- **Presentation** → Domain ← Data
|
||||
- **Data** → Domain (implements interfaces)
|
||||
- **Domain** → Independent (pure business logic)
|
||||
|
||||
```dart
|
||||
// In presentation layer - ✅ GOOD
|
||||
import 'package:retail/features/products/domain/domain.dart';
|
||||
|
||||
// In data layer - ✅ GOOD
|
||||
import 'package:retail/features/products/domain/domain.dart';
|
||||
|
||||
// In domain layer - ❌ NEVER
|
||||
// import 'package:retail/features/products/data/data.dart';
|
||||
// import 'package:retail/features/products/presentation/presentation.dart';
|
||||
```
|
||||
|
||||
## Feature Export Hierarchy
|
||||
|
||||
Each feature follows this export hierarchy:
|
||||
|
||||
```
|
||||
feature.dart # Top-level feature export
|
||||
├── data/data.dart # Data layer export
|
||||
│ ├── datasources/datasources.dart
|
||||
│ ├── models/models.dart
|
||||
│ └── repositories/ # Implementations (exported directly)
|
||||
├── domain/domain.dart # Domain layer export
|
||||
│ ├── entities/entities.dart
|
||||
│ ├── repositories/ # Interfaces (exported directly)
|
||||
│ └── usecases/usecases.dart
|
||||
└── presentation/presentation.dart # Presentation layer export
|
||||
├── pages/pages.dart
|
||||
├── providers/providers.dart
|
||||
└── widgets/widgets.dart
|
||||
```
|
||||
|
||||
## Import Guidelines
|
||||
|
||||
### DO's
|
||||
|
||||
1. **Import at the appropriate level**
|
||||
```dart
|
||||
// If you need the entire feature
|
||||
import 'package:retail/features/auth/auth.dart';
|
||||
|
||||
// If you only need domain entities
|
||||
import 'package:retail/features/auth/domain/entities/entities.dart';
|
||||
```
|
||||
|
||||
2. **Use barrel exports for cleaner code**
|
||||
```dart
|
||||
// ✅ Clean and maintainable
|
||||
import 'package:retail/features/products/presentation/presentation.dart';
|
||||
|
||||
// ❌ Messy and fragile
|
||||
import 'package:retail/features/products/presentation/pages/products_page.dart';
|
||||
import 'package:retail/features/products/presentation/widgets/product_card.dart';
|
||||
import 'package:retail/features/products/presentation/widgets/product_grid.dart';
|
||||
import 'package:retail/features/products/presentation/providers/products_provider.dart';
|
||||
```
|
||||
|
||||
3. **Respect layer boundaries**
|
||||
```dart
|
||||
// In a use case (domain layer)
|
||||
import 'package:retail/features/products/domain/domain.dart'; // ✅
|
||||
import 'package:retail/core/core.dart'; // ✅ (core is shared)
|
||||
```
|
||||
|
||||
### DON'Ts
|
||||
|
||||
1. **Don't bypass barrel exports**
|
||||
```dart
|
||||
// ❌ Bypasses barrel export
|
||||
import 'package:retail/features/products/data/models/product_model.dart';
|
||||
|
||||
// ✅ Use barrel export
|
||||
import 'package:retail/features/products/data/models/models.dart';
|
||||
```
|
||||
|
||||
2. **Don't violate layer dependencies**
|
||||
```dart
|
||||
// In domain layer
|
||||
// ❌ Domain depends on outer layers
|
||||
import 'package:retail/features/products/data/data.dart';
|
||||
import 'package:retail/features/products/presentation/presentation.dart';
|
||||
```
|
||||
|
||||
3. **Don't import entire feature when you need one layer**
|
||||
```dart
|
||||
// ❌ Over-importing
|
||||
import 'package:retail/features/products/products.dart'; // Imports all layers
|
||||
// When you only need:
|
||||
import 'package:retail/features/products/domain/entities/entities.dart';
|
||||
```
|
||||
|
||||
## Benefits Summary
|
||||
|
||||
### 1. Clean Imports
|
||||
Before:
|
||||
```dart
|
||||
import 'package:retail/features/products/data/models/product_model.dart';
|
||||
import 'package:retail/features/products/domain/entities/product.dart';
|
||||
import 'package:retail/features/products/domain/repositories/product_repository.dart';
|
||||
import 'package:retail/features/products/presentation/pages/products_page.dart';
|
||||
import 'package:retail/features/products/presentation/widgets/product_card.dart';
|
||||
import 'package:retail/features/products/presentation/widgets/product_grid.dart';
|
||||
```
|
||||
|
||||
After:
|
||||
```dart
|
||||
import 'package:retail/features/products/products.dart';
|
||||
```
|
||||
|
||||
### 2. Layer Isolation
|
||||
- Domain layer never imports from data/presentation
|
||||
- Each layer has clear boundaries
|
||||
- Enforces dependency inversion
|
||||
|
||||
### 3. Easy Refactoring
|
||||
- Change internal structure without breaking imports
|
||||
- Move files within a layer without updating imports
|
||||
- Rename files without affecting external code
|
||||
|
||||
### 4. Better IDE Support
|
||||
- Autocomplete shows only exported items
|
||||
- Easier to navigate code structure
|
||||
- Clear module boundaries
|
||||
|
||||
### 5. Documentation
|
||||
- Export files serve as documentation
|
||||
- Shows what's public vs private
|
||||
- Makes architecture explicit
|
||||
|
||||
## Migration Guide
|
||||
|
||||
If you have existing imports, migrate them gradually:
|
||||
|
||||
### Step 1: Update feature-level imports
|
||||
```dart
|
||||
// Old
|
||||
import 'package:retail/features/products/presentation/pages/products_page.dart';
|
||||
|
||||
// New
|
||||
import 'package:retail/features/products/presentation/pages/pages.dart';
|
||||
```
|
||||
|
||||
### Step 2: Consolidate layer imports
|
||||
```dart
|
||||
// Old
|
||||
import 'package:retail/features/products/presentation/pages/pages.dart';
|
||||
import 'package:retail/features/products/presentation/widgets/widgets.dart';
|
||||
import 'package:retail/features/products/presentation/providers/providers.dart';
|
||||
|
||||
// New
|
||||
import 'package:retail/features/products/presentation/presentation.dart';
|
||||
```
|
||||
|
||||
### Step 3: Use top-level feature import when appropriate
|
||||
```dart
|
||||
// If you need multiple layers
|
||||
import 'package:retail/features/products/products.dart';
|
||||
```
|
||||
|
||||
## Complete File List
|
||||
|
||||
Total export files created: **54 files**
|
||||
|
||||
### Core Module (10 files)
|
||||
1. `/Users/ssg/project/retail/lib/core/core.dart`
|
||||
2. `/Users/ssg/project/retail/lib/core/config/config.dart`
|
||||
3. `/Users/ssg/project/retail/lib/core/constants/constants.dart`
|
||||
4. `/Users/ssg/project/retail/lib/core/database/database.dart`
|
||||
5. `/Users/ssg/project/retail/lib/core/di/di.dart`
|
||||
6. `/Users/ssg/project/retail/lib/core/errors/errors.dart`
|
||||
7. `/Users/ssg/project/retail/lib/core/network/network.dart`
|
||||
8. `/Users/ssg/project/retail/lib/core/storage/storage.dart`
|
||||
9. `/Users/ssg/project/retail/lib/core/theme/theme.dart`
|
||||
10. `/Users/ssg/project/retail/lib/core/utils/utils.dart`
|
||||
|
||||
### Auth Feature (8 files)
|
||||
11. `/Users/ssg/project/retail/lib/features/auth/auth.dart`
|
||||
12. `/Users/ssg/project/retail/lib/features/auth/data/data.dart`
|
||||
13. `/Users/ssg/project/retail/lib/features/auth/data/models/models.dart`
|
||||
14. `/Users/ssg/project/retail/lib/features/auth/domain/domain.dart`
|
||||
15. `/Users/ssg/project/retail/lib/features/auth/domain/entities/entities.dart`
|
||||
16. `/Users/ssg/project/retail/lib/features/auth/presentation/presentation.dart`
|
||||
17. `/Users/ssg/project/retail/lib/features/auth/presentation/pages/pages.dart`
|
||||
18. `/Users/ssg/project/retail/lib/features/auth/presentation/widgets/widgets.dart` *(updated by flutter expert)*
|
||||
|
||||
### Products Feature (10 files)
|
||||
19. `/Users/ssg/project/retail/lib/features/products/products.dart`
|
||||
20. `/Users/ssg/project/retail/lib/features/products/data/data.dart`
|
||||
21. `/Users/ssg/project/retail/lib/features/products/data/datasources/datasources.dart`
|
||||
22. `/Users/ssg/project/retail/lib/features/products/data/models/models.dart`
|
||||
23. `/Users/ssg/project/retail/lib/features/products/domain/domain.dart`
|
||||
24. `/Users/ssg/project/retail/lib/features/products/domain/entities/entities.dart`
|
||||
25. `/Users/ssg/project/retail/lib/features/products/domain/usecases/usecases.dart`
|
||||
26. `/Users/ssg/project/retail/lib/features/products/presentation/presentation.dart`
|
||||
27. `/Users/ssg/project/retail/lib/features/products/presentation/pages/pages.dart`
|
||||
28. `/Users/ssg/project/retail/lib/features/products/presentation/providers/providers.dart`
|
||||
|
||||
### Categories Feature (10 files)
|
||||
29. `/Users/ssg/project/retail/lib/features/categories/categories.dart`
|
||||
30. `/Users/ssg/project/retail/lib/features/categories/data/data.dart`
|
||||
31. `/Users/ssg/project/retail/lib/features/categories/data/datasources/datasources.dart`
|
||||
32. `/Users/ssg/project/retail/lib/features/categories/data/models/models.dart`
|
||||
33. `/Users/ssg/project/retail/lib/features/categories/domain/domain.dart`
|
||||
34. `/Users/ssg/project/retail/lib/features/categories/domain/entities/entities.dart`
|
||||
35. `/Users/ssg/project/retail/lib/features/categories/domain/usecases/usecases.dart`
|
||||
36. `/Users/ssg/project/retail/lib/features/categories/presentation/presentation.dart`
|
||||
37. `/Users/ssg/project/retail/lib/features/categories/presentation/pages/pages.dart`
|
||||
38. `/Users/ssg/project/retail/lib/features/categories/presentation/providers/providers.dart` *(already exists)*
|
||||
|
||||
### Home/Cart Feature (10 files)
|
||||
39. `/Users/ssg/project/retail/lib/features/home/home.dart`
|
||||
40. `/Users/ssg/project/retail/lib/features/home/data/data.dart`
|
||||
41. `/Users/ssg/project/retail/lib/features/home/data/datasources/datasources.dart`
|
||||
42. `/Users/ssg/project/retail/lib/features/home/data/models/models.dart`
|
||||
43. `/Users/ssg/project/retail/lib/features/home/domain/domain.dart`
|
||||
44. `/Users/ssg/project/retail/lib/features/home/domain/entities/entities.dart`
|
||||
45. `/Users/ssg/project/retail/lib/features/home/domain/usecases/usecases.dart`
|
||||
46. `/Users/ssg/project/retail/lib/features/home/presentation/presentation.dart`
|
||||
47. `/Users/ssg/project/retail/lib/features/home/presentation/pages/pages.dart`
|
||||
48. `/Users/ssg/project/retail/lib/features/home/presentation/providers/providers.dart` *(already exists)*
|
||||
|
||||
### Settings Feature (10 files)
|
||||
49. `/Users/ssg/project/retail/lib/features/settings/settings.dart`
|
||||
50. `/Users/ssg/project/retail/lib/features/settings/data/data.dart`
|
||||
51. `/Users/ssg/project/retail/lib/features/settings/data/datasources/datasources.dart`
|
||||
52. `/Users/ssg/project/retail/lib/features/settings/data/models/models.dart`
|
||||
53. `/Users/ssg/project/retail/lib/features/settings/domain/domain.dart`
|
||||
54. `/Users/ssg/project/retail/lib/features/settings/domain/entities/entities.dart`
|
||||
55. `/Users/ssg/project/retail/lib/features/settings/domain/usecases/usecases.dart`
|
||||
56. `/Users/ssg/project/retail/lib/features/settings/presentation/presentation.dart`
|
||||
57. `/Users/ssg/project/retail/lib/features/settings/presentation/pages/pages.dart`
|
||||
58. `/Users/ssg/project/retail/lib/features/settings/presentation/providers/providers.dart` *(already exists)*
|
||||
59. `/Users/ssg/project/retail/lib/features/settings/presentation/widgets/widgets.dart`
|
||||
|
||||
### Top-Level Exports (2 files)
|
||||
60. `/Users/ssg/project/retail/lib/features/features.dart`
|
||||
61. `/Users/ssg/project/retail/lib/shared/shared.dart`
|
||||
|
||||
### Documentation (1 file)
|
||||
62. `/Users/ssg/project/retail/lib/EXPORTS_DOCUMENTATION.md`
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
When adding new files to the project:
|
||||
|
||||
1. **New file in existing module**: Update the appropriate barrel export
|
||||
2. **New module**: Create new barrel exports following the pattern
|
||||
3. **Removing files**: Update barrel exports to remove deleted exports
|
||||
4. **Renaming files**: Update barrel exports to reflect new names
|
||||
|
||||
## Support
|
||||
|
||||
For questions or issues with the export structure, refer to:
|
||||
- This documentation
|
||||
- Clean Architecture principles
|
||||
- Feature-first organization patterns
|
||||
720
docs/WIDGETS_DOCUMENTATION.md
Normal file
720
docs/WIDGETS_DOCUMENTATION.md
Normal file
@@ -0,0 +1,720 @@
|
||||
# Retail POS App - Widget Documentation
|
||||
|
||||
## Overview
|
||||
This document provides a comprehensive overview of all custom Material 3 widgets created for the Retail POS application.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
1. [Core Widgets](#core-widgets)
|
||||
2. [Shared Widgets](#shared-widgets)
|
||||
3. [Product Widgets](#product-widgets)
|
||||
4. [Category Widgets](#category-widgets)
|
||||
5. [Cart/Home Widgets](#carthome-widgets)
|
||||
6. [Theme Configuration](#theme-configuration)
|
||||
|
||||
---
|
||||
|
||||
## Core Widgets
|
||||
|
||||
### 1. LoadingIndicator
|
||||
**Location:** `/lib/core/widgets/loading_indicator.dart`
|
||||
|
||||
A Material 3 loading indicator with optional message.
|
||||
|
||||
**Features:**
|
||||
- Customizable size and color
|
||||
- Optional loading message
|
||||
- Shimmer loading effect for skeleton screens
|
||||
- Overlay loading indicator
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
LoadingIndicator(
|
||||
size: 40.0,
|
||||
message: 'Loading products...',
|
||||
)
|
||||
|
||||
// Shimmer effect
|
||||
ShimmerLoading(
|
||||
width: 200,
|
||||
height: 20,
|
||||
borderRadius: BorderRadius.circular(8),
|
||||
)
|
||||
|
||||
// Overlay loading
|
||||
OverlayLoadingIndicator(
|
||||
isLoading: true,
|
||||
message: 'Processing...',
|
||||
child: YourWidget(),
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. EmptyState
|
||||
**Location:** `/lib/core/widgets/empty_state.dart`
|
||||
|
||||
Display empty state with icon, message, and optional action button.
|
||||
|
||||
**Features:**
|
||||
- Customizable icon and messages
|
||||
- Optional action button
|
||||
- Specialized variants for common scenarios
|
||||
|
||||
**Variants:**
|
||||
- `EmptyProductsState` - For empty product lists
|
||||
- `EmptyCategoriesState` - For empty category lists
|
||||
- `EmptyCartState` - For empty shopping cart
|
||||
- `EmptySearchState` - For no search results
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
EmptyState(
|
||||
icon: Icons.inventory_2_outlined,
|
||||
title: 'No Products Found',
|
||||
message: 'There are no products available.',
|
||||
actionLabel: 'Refresh',
|
||||
onAction: () => refreshProducts(),
|
||||
)
|
||||
|
||||
// Or use specialized variants
|
||||
EmptyProductsState(onRefresh: () => refresh())
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. CustomErrorWidget
|
||||
**Location:** `/lib/core/widgets/error_widget.dart`
|
||||
|
||||
Error display widget with retry functionality.
|
||||
|
||||
**Features:**
|
||||
- Customizable error messages
|
||||
- Retry button
|
||||
- Different error types
|
||||
|
||||
**Variants:**
|
||||
- `NetworkErrorWidget` - For network errors
|
||||
- `ServerErrorWidget` - For server errors
|
||||
- `DataErrorWidget` - For data errors
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
CustomErrorWidget(
|
||||
title: 'Something went wrong',
|
||||
message: 'Please try again',
|
||||
onRetry: () => retryOperation(),
|
||||
)
|
||||
|
||||
// Or use specialized variants
|
||||
NetworkErrorWidget(onRetry: () => retry())
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. CustomButton
|
||||
**Location:** `/lib/core/widgets/custom_button.dart`
|
||||
|
||||
Material 3 button with loading state support.
|
||||
|
||||
**Features:**
|
||||
- Multiple button types (primary, secondary, outlined, text)
|
||||
- Loading state
|
||||
- Optional icon
|
||||
- Full width option
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
CustomButton(
|
||||
label: 'Add to Cart',
|
||||
icon: Icons.shopping_cart,
|
||||
onPressed: () => addToCart(),
|
||||
isLoading: false,
|
||||
isFullWidth: true,
|
||||
type: ButtonType.primary,
|
||||
)
|
||||
|
||||
// FAB with badge
|
||||
CustomFAB(
|
||||
icon: Icons.shopping_cart,
|
||||
onPressed: () => viewCart(),
|
||||
badgeCount: 5,
|
||||
tooltip: 'View cart',
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Shared Widgets
|
||||
|
||||
### 5. PriceDisplay
|
||||
**Location:** `/lib/shared/widgets/price_display.dart`
|
||||
|
||||
Display formatted prices with currency symbols.
|
||||
|
||||
**Features:**
|
||||
- Currency symbol customization
|
||||
- Decimal control
|
||||
- Custom styling
|
||||
- Strike-through variant for discounts
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
PriceDisplay(
|
||||
price: 99.99,
|
||||
currencySymbol: '\$',
|
||||
showDecimals: true,
|
||||
color: Colors.blue,
|
||||
)
|
||||
|
||||
// Strike-through price
|
||||
StrikeThroughPrice(
|
||||
price: 129.99,
|
||||
currencySymbol: '\$',
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. AppBottomNav
|
||||
**Location:** `/lib/shared/widgets/app_bottom_nav.dart`
|
||||
|
||||
Material 3 bottom navigation bar with badge support.
|
||||
|
||||
**Features:**
|
||||
- 4 tabs: POS, Products, Categories, Settings
|
||||
- Cart item count badge
|
||||
- Navigation rail for larger screens
|
||||
- Responsive navigation wrapper
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
AppBottomNav(
|
||||
currentIndex: 0,
|
||||
onTabChanged: (index) => handleTabChange(index),
|
||||
cartItemCount: 3,
|
||||
)
|
||||
|
||||
// Navigation rail for tablets
|
||||
AppNavigationRail(
|
||||
currentIndex: 0,
|
||||
onTabChanged: (index) => handleTabChange(index),
|
||||
cartItemCount: 3,
|
||||
extended: true,
|
||||
)
|
||||
|
||||
// Responsive wrapper
|
||||
ResponsiveNavigation(
|
||||
currentIndex: 0,
|
||||
onTabChanged: (index) => handleTabChange(index),
|
||||
cartItemCount: 3,
|
||||
child: YourContent(),
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. CustomAppBar
|
||||
**Location:** `/lib/shared/widgets/custom_app_bar.dart`
|
||||
|
||||
Customizable Material 3 app bar.
|
||||
|
||||
**Variants:**
|
||||
- `CustomAppBar` - Standard app bar
|
||||
- `SearchAppBar` - App bar with search functionality
|
||||
- `ModalAppBar` - Compact app bar for modals
|
||||
- `AppBarActionWithBadge` - Action button with badge
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
CustomAppBar(
|
||||
title: 'Products',
|
||||
actions: [
|
||||
IconButton(icon: Icon(Icons.filter_list), onPressed: () {}),
|
||||
],
|
||||
)
|
||||
|
||||
// Search app bar
|
||||
SearchAppBar(
|
||||
title: 'Products',
|
||||
searchHint: 'Search products...',
|
||||
onSearchChanged: (query) => search(query),
|
||||
)
|
||||
|
||||
// App bar action with badge
|
||||
AppBarActionWithBadge(
|
||||
icon: Icons.shopping_cart,
|
||||
onPressed: () => viewCart(),
|
||||
badgeCount: 5,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8. BadgeWidget
|
||||
**Location:** `/lib/shared/widgets/badge_widget.dart`
|
||||
|
||||
Material 3 badges for various purposes.
|
||||
|
||||
**Variants:**
|
||||
- `BadgeWidget` - General purpose badge
|
||||
- `StatusBadge` - Status indicators (success, warning, error, info, neutral)
|
||||
- `CountBadge` - Number display badge
|
||||
- `NotificationBadge` - Simple dot badge
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
BadgeWidget(
|
||||
count: 5,
|
||||
child: Icon(Icons.notifications),
|
||||
)
|
||||
|
||||
StatusBadge(
|
||||
label: 'Low Stock',
|
||||
type: StatusBadgeType.warning,
|
||||
icon: Icons.warning,
|
||||
)
|
||||
|
||||
CountBadge(count: 10)
|
||||
|
||||
NotificationBadge(
|
||||
show: true,
|
||||
child: Icon(Icons.notifications),
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Product Widgets
|
||||
|
||||
### 9. ProductCard
|
||||
**Location:** `/lib/features/products/presentation/widgets/product_card.dart`
|
||||
|
||||
Material 3 product card for grid display.
|
||||
|
||||
**Features:**
|
||||
- Product image with caching
|
||||
- Product name (2 lines max with ellipsis)
|
||||
- Price display with currency
|
||||
- Stock status badge (low stock/out of stock)
|
||||
- Category badge
|
||||
- Add to cart button
|
||||
- Ripple effect
|
||||
- Responsive sizing
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
ProductCard(
|
||||
id: '1',
|
||||
name: 'Premium Coffee Beans',
|
||||
price: 24.99,
|
||||
imageUrl: 'https://example.com/image.jpg',
|
||||
categoryName: 'Beverages',
|
||||
stockQuantity: 5,
|
||||
isAvailable: true,
|
||||
onTap: () => viewProduct(),
|
||||
onAddToCart: () => addToCart(),
|
||||
currencySymbol: '\$',
|
||||
)
|
||||
|
||||
// Compact variant
|
||||
CompactProductCard(
|
||||
id: '1',
|
||||
name: 'Premium Coffee Beans',
|
||||
price: 24.99,
|
||||
imageUrl: 'https://example.com/image.jpg',
|
||||
onTap: () => viewProduct(),
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 10. ProductGrid
|
||||
**Location:** `/lib/features/products/presentation/widgets/product_grid.dart`
|
||||
|
||||
Responsive grid layout for products.
|
||||
|
||||
**Features:**
|
||||
- Adaptive column count (2-5 columns)
|
||||
- RepaintBoundary for performance
|
||||
- Customizable spacing
|
||||
- Pull-to-refresh variant
|
||||
- Sliver variant for CustomScrollView
|
||||
|
||||
**Responsive Breakpoints:**
|
||||
- Mobile portrait: 2 columns
|
||||
- Mobile landscape: 3 columns
|
||||
- Tablet portrait: 3-4 columns
|
||||
- Tablet landscape/Desktop: 4-5 columns
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
ProductGrid(
|
||||
products: productWidgets,
|
||||
childAspectRatio: 0.75,
|
||||
crossAxisSpacing: 12,
|
||||
mainAxisSpacing: 12,
|
||||
)
|
||||
|
||||
// With pull-to-refresh
|
||||
RefreshableProductGrid(
|
||||
products: productWidgets,
|
||||
onRefresh: () => refreshProducts(),
|
||||
)
|
||||
|
||||
// Sliver variant
|
||||
SliverProductGrid(
|
||||
products: productWidgets,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 11. ProductSearchBar
|
||||
**Location:** `/lib/features/products/presentation/widgets/product_search_bar.dart`
|
||||
|
||||
Search bar with debouncing.
|
||||
|
||||
**Features:**
|
||||
- 300ms debouncing
|
||||
- Clear button
|
||||
- Optional filter button
|
||||
- Customizable hint text
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
ProductSearchBar(
|
||||
initialQuery: '',
|
||||
onSearchChanged: (query) => search(query),
|
||||
hintText: 'Search products...',
|
||||
debounceDuration: Duration(milliseconds: 300),
|
||||
)
|
||||
|
||||
// With filter
|
||||
ProductSearchBarWithFilter(
|
||||
onSearchChanged: (query) => search(query),
|
||||
onFilterTap: () => showFilters(),
|
||||
hasActiveFilters: true,
|
||||
)
|
||||
|
||||
// Compact variant
|
||||
CompactSearchField(
|
||||
onSearchChanged: (query) => search(query),
|
||||
hintText: 'Search...',
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Category Widgets
|
||||
|
||||
### 12. CategoryCard
|
||||
**Location:** `/lib/features/categories/presentation/widgets/category_card.dart`
|
||||
|
||||
Material 3 category card with custom colors.
|
||||
|
||||
**Features:**
|
||||
- Category icon/image
|
||||
- Category name
|
||||
- Product count badge
|
||||
- Custom background color
|
||||
- Selection state
|
||||
- Hero animation ready
|
||||
- Contrasting text color calculation
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
CategoryCard(
|
||||
id: '1',
|
||||
name: 'Electronics',
|
||||
productCount: 45,
|
||||
imageUrl: 'https://example.com/image.jpg',
|
||||
iconPath: 'electronics',
|
||||
backgroundColor: Colors.blue,
|
||||
isSelected: false,
|
||||
onTap: () => selectCategory(),
|
||||
)
|
||||
|
||||
// Category chip
|
||||
CategoryChip(
|
||||
id: '1',
|
||||
name: 'Electronics',
|
||||
isSelected: true,
|
||||
onTap: () => selectCategory(),
|
||||
)
|
||||
|
||||
// Horizontal chip list
|
||||
CategoryChipList(
|
||||
categories: categoryData,
|
||||
selectedCategoryId: '1',
|
||||
onCategorySelected: (id) => selectCategory(id),
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 13. CategoryGrid
|
||||
**Location:** `/lib/features/categories/presentation/widgets/category_grid.dart`
|
||||
|
||||
Responsive grid layout for categories.
|
||||
|
||||
**Features:**
|
||||
- Adaptive column count (2-5 columns)
|
||||
- Square aspect ratio (1:1)
|
||||
- Pull-to-refresh variant
|
||||
- Sliver variant
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
CategoryGrid(
|
||||
categories: categoryWidgets,
|
||||
childAspectRatio: 1.0,
|
||||
)
|
||||
|
||||
// With pull-to-refresh
|
||||
RefreshableCategoryGrid(
|
||||
categories: categoryWidgets,
|
||||
onRefresh: () => refreshCategories(),
|
||||
)
|
||||
|
||||
// Sliver variant
|
||||
SliverCategoryGrid(
|
||||
categories: categoryWidgets,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cart/Home Widgets
|
||||
|
||||
### 14. CartItemCard
|
||||
**Location:** `/lib/features/home/presentation/widgets/cart_item_card.dart`
|
||||
|
||||
Cart item with quantity controls and swipe-to-delete.
|
||||
|
||||
**Features:**
|
||||
- Product thumbnail (60x60)
|
||||
- Product name and unit price
|
||||
- Quantity controls (+/-)
|
||||
- Line total calculation
|
||||
- Remove button
|
||||
- Swipe-to-delete gesture
|
||||
- Max quantity validation
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
CartItemCard(
|
||||
productId: '1',
|
||||
productName: 'Premium Coffee Beans',
|
||||
price: 24.99,
|
||||
quantity: 2,
|
||||
imageUrl: 'https://example.com/image.jpg',
|
||||
onIncrement: () => incrementQuantity(),
|
||||
onDecrement: () => decrementQuantity(),
|
||||
onRemove: () => removeFromCart(),
|
||||
maxQuantity: 10,
|
||||
currencySymbol: '\$',
|
||||
)
|
||||
|
||||
// Compact variant
|
||||
CompactCartItem(
|
||||
productName: 'Premium Coffee Beans',
|
||||
price: 24.99,
|
||||
quantity: 2,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 15. CartSummary
|
||||
**Location:** `/lib/features/home/presentation/widgets/cart_summary.dart`
|
||||
|
||||
Order summary with checkout button.
|
||||
|
||||
**Features:**
|
||||
- Subtotal display
|
||||
- Tax calculation
|
||||
- Discount display
|
||||
- Total calculation (bold, larger)
|
||||
- Checkout button (full width)
|
||||
- Loading state support
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
CartSummary(
|
||||
subtotal: 99.99,
|
||||
tax: 8.50,
|
||||
discount: 10.00,
|
||||
currencySymbol: '\$',
|
||||
onCheckout: () => processCheckout(),
|
||||
isCheckoutEnabled: true,
|
||||
isLoading: false,
|
||||
)
|
||||
|
||||
// Compact variant
|
||||
CompactCartSummary(
|
||||
itemCount: 3,
|
||||
total: 98.49,
|
||||
onTap: () => viewCart(),
|
||||
)
|
||||
|
||||
// Summary row (reusable component)
|
||||
SummaryRow(
|
||||
label: 'Subtotal',
|
||||
value: '\$99.99',
|
||||
isBold: false,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Theme Configuration
|
||||
|
||||
### AppTheme
|
||||
**Location:** `/lib/core/theme/app_theme.dart`
|
||||
|
||||
Material 3 theme configuration.
|
||||
|
||||
**Features:**
|
||||
- Light and dark themes
|
||||
- Custom color schemes
|
||||
- Consistent typography
|
||||
- Card styling
|
||||
- Button styling
|
||||
- Input decoration
|
||||
|
||||
**Colors:**
|
||||
- Primary: `#6750A4`
|
||||
- Secondary: `#625B71`
|
||||
- Tertiary: `#7D5260`
|
||||
- Error: `#B3261E`
|
||||
- Success: `#4CAF50`
|
||||
- Warning: `#FF9800`
|
||||
|
||||
**Usage:**
|
||||
```dart
|
||||
MaterialApp(
|
||||
theme: AppTheme.lightTheme,
|
||||
darkTheme: AppTheme.darkTheme,
|
||||
themeMode: ThemeMode.system,
|
||||
home: HomePage(),
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Widget Best Practices
|
||||
|
||||
### Performance Optimization
|
||||
1. **Use const constructors** wherever possible
|
||||
2. **RepaintBoundary** around grid items
|
||||
3. **Cached network images** for all product/category images
|
||||
4. **Debouncing** for search inputs (300ms)
|
||||
5. **ListView.builder/GridView.builder** for long lists
|
||||
|
||||
### Accessibility
|
||||
1. All widgets include **semanticsLabel** for screen readers
|
||||
2. Proper **tooltip** attributes on buttons
|
||||
3. Sufficient **color contrast** for text
|
||||
4. **Touch target sizes** meet minimum 48x48 dp
|
||||
|
||||
### Responsive Design
|
||||
1. Adaptive column counts based on screen width
|
||||
2. Navigation rail for tablets/desktop
|
||||
3. Bottom navigation for mobile
|
||||
4. Flexible layouts with Expanded/Flexible
|
||||
|
||||
### Material 3 Compliance
|
||||
1. Uses Material 3 components (NavigationBar, SearchBar, etc.)
|
||||
2. Proper elevation and shadows
|
||||
3. Rounded corners (8-12px border radius)
|
||||
4. Ripple effects on interactive elements
|
||||
5. Theme-aware colors
|
||||
|
||||
---
|
||||
|
||||
## Import Shortcuts
|
||||
|
||||
For easier imports, use the barrel exports:
|
||||
|
||||
```dart
|
||||
// Core widgets
|
||||
import 'package:retail/core/widgets/widgets.dart';
|
||||
|
||||
// Shared widgets
|
||||
import 'package:retail/shared/widgets/widgets.dart';
|
||||
|
||||
// Product widgets
|
||||
import 'package:retail/features/products/presentation/widgets/widgets.dart';
|
||||
|
||||
// Category widgets
|
||||
import 'package:retail/features/categories/presentation/widgets/widgets.dart';
|
||||
|
||||
// Cart widgets
|
||||
import 'package:retail/features/home/presentation/widgets/widgets.dart';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Widget Checklist
|
||||
|
||||
### Core Widgets (4/4)
|
||||
- [x] LoadingIndicator (with shimmer and overlay variants)
|
||||
- [x] EmptyState (with specialized variants)
|
||||
- [x] CustomErrorWidget (with specialized variants)
|
||||
- [x] CustomButton (with FAB variant)
|
||||
|
||||
### Shared Widgets (4/4)
|
||||
- [x] PriceDisplay (with strike-through variant)
|
||||
- [x] AppBottomNav (with navigation rail and responsive wrapper)
|
||||
- [x] CustomAppBar (with search and modal variants)
|
||||
- [x] BadgeWidget (with status, count, and notification variants)
|
||||
|
||||
### Product Widgets (3/3)
|
||||
- [x] ProductCard (with compact variant)
|
||||
- [x] ProductGrid (with sliver and refreshable variants)
|
||||
- [x] ProductSearchBar (with filter and compact variants)
|
||||
|
||||
### Category Widgets (2/2)
|
||||
- [x] CategoryCard (with chip and chip list variants)
|
||||
- [x] CategoryGrid (with sliver and refreshable variants)
|
||||
|
||||
### Cart Widgets (2/2)
|
||||
- [x] CartItemCard (with compact variant)
|
||||
- [x] CartSummary (with compact variant and summary row)
|
||||
|
||||
### Theme (1/1)
|
||||
- [x] AppTheme (light and dark themes)
|
||||
|
||||
**Total: 16 main widget components with 30+ variants**
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
To use these widgets in your app:
|
||||
|
||||
1. **Install dependencies** (already added to pubspec.yaml):
|
||||
- cached_network_image
|
||||
- flutter_riverpod
|
||||
- intl
|
||||
|
||||
2. **Initialize Hive** for offline storage
|
||||
|
||||
3. **Create domain models** for Product, Category, CartItem
|
||||
|
||||
4. **Set up Riverpod providers** for state management
|
||||
|
||||
5. **Build feature pages** using these widgets
|
||||
|
||||
6. **Test widgets** with different data states
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For questions or issues with these widgets, please refer to:
|
||||
- Material 3 Guidelines: https://m3.material.io/
|
||||
- Flutter Widget Catalog: https://docs.flutter.dev/ui/widgets
|
||||
- Cached Network Image: https://pub.dev/packages/cached_network_image
|
||||
Reference in New Issue
Block a user