retail/AUTH_UI_COMPONENT_TREE.txt

Authentication UI Component Tree
================================

1. LOGIN PAGE (login_page.dart)
   └── Scaffold
       └── SafeArea
           └── Center
               └── SingleChildScrollView
                   └── ConstrainedBox (max 400px)
                       └── Form
                           ├── AuthHeader
                           │   ├── Container (logo)
                           │   │   └── Icon (store)
                           │   ├── Text (title)
                           │   └── Text (subtitle)
                           │
                           ├── AuthTextField (email)
                           │   ├── Icon (email)
                           │   └── TextFormField
                           │
                           ├── PasswordField (password)
                           │   ├── Icon (lock)
                           │   ├── TextFormField (obscured)
                           │   └── IconButton (visibility toggle)
                           │
                           ├── Row (remember me + forgot password)
                           │   ├── Checkbox + Text
                           │   └── TextButton
                           │
                           ├── AuthButton (login)
                           │   └── ElevatedButton
                           │       └── CircularProgressIndicator | Text
                           │
                           ├── Row (divider)
                           │   ├── Divider
                           │   ├── Text ("OR")
                           │   └── Divider
                           │
                           └── Row (register link)
                               ├── Text
                               └── TextButton

---

2. REGISTER PAGE (register_page.dart)
   └── Scaffold
       ├── AppBar
       │   └── IconButton (back)
       │
       └── SafeArea
           └── Center
               └── SingleChildScrollView
                   └── ConstrainedBox (max 400px)
                       └── Form
                           ├── AuthHeader
                           │   ├── Container (logo)
                           │   ├── Text (title)
                           │   └── Text (subtitle)
                           │
                           ├── AuthTextField (name)
                           │   └── Icon (person)
                           │
                           ├── AuthTextField (email)
                           │   └── Icon (email)
                           │
                           ├── PasswordField (password)
                           │   ├── Icon (lock)
                           │   └── IconButton (toggle)
                           │
                           ├── PasswordField (confirm)
                           │   ├── Icon (lock)
                           │   └── IconButton (toggle)
                           │
                           ├── Row (terms)
                           │   ├── Checkbox
                           │   └── Text.rich (with links)
                           │
                           ├── AuthButton (register)
                           │   └── ElevatedButton
                           │
                           ├── Row (divider)
                           │   ├── Divider
                           │   ├── Text ("OR")
                           │   └── Divider
                           │
                           └── Row (login link)
                               ├── Text
                               └── TextButton

---

3. AUTH WRAPPER (auth_wrapper.dart)
   └── ConsumerWidget
       ├── if (loading) → Scaffold
       │   └── CircularProgressIndicator
       │
       ├── if (authenticated) → child widget
       │
       └── else → LoginPage

---

WIDGET RELATIONSHIPS:

AuthWrapper
    └── watches: authProvider
        ├── user
        ├── isAuthenticated
        ├── isLoading
        └── errorMessage

LoginPage & RegisterPage
    └── use: authProvider.notifier
        ├── login()
        ├── register()
        └── error handling

Reusable Widgets:
    ├── AuthHeader (logo + titles)
    ├── AuthTextField (custom input)
    ├── PasswordField (password input)
    └── AuthButton (action button)

Validators:
    ├── validateEmail()
    ├── validatePassword()
    ├── validateName()
    ├── validateConfirmPassword()
    └── validateLoginPassword()

---

STATE MANAGEMENT FLOW:

User Action → Form Validation → Provider Call → Loading State → API Call → Update State → UI Update

Example Login Flow:
1. User enters email/password
2. Validators check format
3. handleLogin() called
4. authProvider.notifier.login()
5. isLoading = true (button shows spinner)
6. API request sent
7. On success: isAuthenticated = true
8. AuthWrapper detects change
9. Navigates to child widget
10. On error: errorMessage set
11. SnackBar shows error

---

FILE DEPENDENCIES:

login_page.dart
    ├── imports: auth_provider.dart
    ├── imports: validators.dart
    ├── imports: widgets.dart (all)
    └── imports: register_page.dart

register_page.dart
    ├── imports: auth_provider.dart
    ├── imports: validators.dart
    └── imports: widgets.dart (all)

auth_wrapper.dart
    ├── imports: auth_provider.dart
    └── imports: login_page.dart

All widgets
    └── use: Theme.of(context)
        ├── colorScheme
        ├── textTheme
        └── other theme properties

---

THEME INTEGRATION:

Material 3 Theme
    ├── ColorScheme
    │   ├── primary (purple)
    │   ├── onPrimary (white)
    │   ├── surface (white/dark)
    │   ├── onSurface (black/white)
    │   ├── error (red)
    │   └── primaryContainer (light purple)
    │
    ├── TextTheme
    │   ├── displaySmall (titles)
    │   ├── bodyLarge (subtitles)
    │   ├── bodyMedium (body text)
    │   └── titleMedium (buttons)
    │
    └── InputDecorationTheme
        ├── filled: true
        ├── fillColor (gray)
        └── borderRadius: 8

---

INTERACTION PATTERNS:

Keyboard:
    ├── Email field: textInputAction = next
    ├── Password field: textInputAction = done
    ├── onFieldSubmitted: submit form
    └── GestureDetector: dismiss keyboard

Validation:
    ├── onChange: realtime validation
    ├── validator: on submit
    └── errorText: shown inline

Loading:
    ├── Disable all inputs
    ├── Show spinner in button
    └── Prevent navigation

Error:
    ├── SnackBar at bottom
    ├── Red background
    ├── Dismiss action
    └── Floating behavior

Success:
    ├── SnackBar with success
    ├── Auto-navigate via AuthWrapper
    └── Clear form (optional)

---

RESPONSIVE BEHAVIOR:

Small Screens (< 400px):
    └── Full width content
        ├── Scrollable vertically
        └── Padding: 24px

Large Screens (> 400px):
    └── ConstrainedBox maxWidth: 400px
        ├── Centered horizontally
        └── Same layout

Keyboard Open:
    └── SingleChildScrollView
        ├── Auto-scroll to focused field
        └── Content shifts up

Tablet/Desktop:
    └── Content centered
        ├── Max 400px width
        └── Whitespace on sides

---

COLOR USAGE:

Primary Purple (#6750A4):
    ├── App icon background (container)
    ├── Buttons background
    ├── Links text color
    ├── Checkbox active
    └── Input field focus border

Surface Gray (#F5F5F5):
    └── Text field backgrounds

Error Red (#B3261E):
    ├── Validation errors
    └── Error SnackBar

Text Colors:
    ├── Primary: onSurface (full opacity)
    ├── Secondary: onSurface (60% opacity)
    └── Disabled: onSurface (38% opacity)

---

VALIDATION RULES:

Email:
    ├── Required
    └── Must match: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$

Password (Register):
    ├── Required
    ├── Min 8 characters
    ├── At least 1 uppercase
    ├── At least 1 lowercase
    └── At least 1 number

Password (Login):
    └── Required only

Name:
    ├── Required
    ├── Min 2 characters
    └── Max 50 characters

Confirm Password:
    ├── Required
    └── Must match password

Terms:
    └── Must be checked (UI only)