renolation/retail
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
10ccd0300d9c6cac3c1090797d8de8ea113cf2d0
retail/lib/WIDGETS_DOCUMENTATION.md
Phuoc Nguyen b94c158004 runable
2025-10-10 16:38:07 +07:00

14 KiB
Raw Blame History

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
  2. Shared Widgets
  3. Product Widgets
  4. Category Widgets
  5. Cart/Home Widgets
  6. 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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

// 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)

  • LoadingIndicator (with shimmer and overlay variants)
  • EmptyState (with specialized variants)
  • CustomErrorWidget (with specialized variants)
  • CustomButton (with FAB variant)

Shared Widgets (4/4)

  • PriceDisplay (with strike-through variant)
  • AppBottomNav (with navigation rail and responsive wrapper)
  • CustomAppBar (with search and modal variants)
  • BadgeWidget (with status, count, and notification variants)

Product Widgets (3/3)

  • ProductCard (with compact variant)
  • ProductGrid (with sliver and refreshable variants)
  • ProductSearchBar (with filter and compact variants)

Category Widgets (2/2)

  • CategoryCard (with chip and chip list variants)
  • CategoryGrid (with sliver and refreshable variants)

Cart Widgets (2/2)

  • CartItemCard (with compact variant)
  • CartSummary (with compact variant and summary row)

Theme (1/1)

  • 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: