sub2api/frontend/src/views/auth/USAGE_EXAMPLES.md

# Authentication Views Usage Examples

This document provides practical examples of how to use the authentication views in the Sub2API frontend.

## Quick Start

### 1. Login Flow

**Scenario:** User wants to log into their existing account

```typescript
// Route: /login
// Component: LoginView.vue

// User interactions:
// 1. Navigate to /login
// 2. Enter username: "john_doe"
// 3. Enter password: "MySecurePass123"
// 4. Optionally check "Remember me"
// 5. Click "Sign In"

// What happens:
// - Form validation runs (client-side)
// - If valid, authStore.login() is called
// - API request to POST /api/auth/login
// - On success:
//   - Token stored in localStorage
//   - User data stored in state
//   - Success toast: "Login successful! Welcome back."
//   - Redirect to /dashboard (or intended route)
// - On error:
//   - Error message displayed inline
//   - Error toast shown
//   - User can retry
```

### 2. Registration Flow

**Scenario:** New user wants to create an account

```typescript
// Route: /register
// Component: RegisterView.vue

// User interactions:
// 1. Navigate to /register
// 2. Enter username: "jane_smith"
// 3. Enter email: "jane@example.com"
// 4. Enter password: "SecurePass123"
// 5. Enter confirm password: "SecurePass123"
// 6. Click "Create Account"

// What happens:
// - Form validation runs (client-side)
//   - Username: 3-50 chars, alphanumeric + _ -
//   - Email: Valid format
//   - Password: 8+ chars, letters + numbers
//   - Passwords match
// - If valid, authStore.register() is called
// - API request to POST /api/auth/register
// - On success:
//   - Token stored in localStorage
//   - User data stored in state
//   - Success toast: "Account created successfully! Welcome to Sub2API."
//   - Redirect to /dashboard
// - On error:
//   - Error message displayed inline
//   - Error toast shown
//   - User can retry
```

## Code Examples

### Importing the Views

```typescript
// Method 1: Direct import
import LoginView from '@/views/auth/LoginView.vue'
import RegisterView from '@/views/auth/RegisterView.vue'

// Method 2: Named exports from index
import { LoginView, RegisterView } from '@/views/auth'

// Method 3: Lazy loading (recommended for routes)
const LoginView = () => import('@/views/auth/LoginView.vue')
const RegisterView = () => import('@/views/auth/RegisterView.vue')
```

### Using in Router

```typescript
import { createRouter, createWebHistory } from 'vue-router'

const routes = [
  {
    path: '/login',
    name: 'Login',
    component: () => import('@/views/auth/LoginView.vue'),
    meta: { requiresAuth: false }
  },
  {
    path: '/register',
    name: 'Register',
    component: () => import('@/views/auth/RegisterView.vue'),
    meta: { requiresAuth: false }
  }
]

const router = createRouter({
  history: createWebHistory(),
  routes
})

export default router
```

### Navigation to Auth Views

```typescript
// From template
<router-link to="/login">Login</router-link>
<router-link to="/register">Sign Up</router-link>

// From script
import { useRouter } from 'vue-router';

const router = useRouter();

// Navigate to login
router.push('/login');

// Navigate to register
router.push('/register');

// Navigate with redirect query
router.push({
  path: '/login',
  query: { redirect: '/dashboard' }
});
```

### Programmatic Auth Flow

```typescript
import { useAuthStore } from '@/stores'
import { useAppStore } from '@/stores'
import { useRouter } from 'vue-router'

const authStore = useAuthStore()
const appStore = useAppStore()
const router = useRouter()

// Login
async function login() {
  try {
    await authStore.login({
      username: 'john_doe',
      password: 'MySecurePass123'
    })

    appStore.showSuccess('Login successful!')
    router.push('/dashboard')
  } catch (error) {
    appStore.showError('Login failed. Please check your credentials.')
  }
}

// Register
async function register() {
  try {
    await authStore.register({
      username: 'jane_smith',
      email: 'jane@example.com',
      password: 'SecurePass123'
    })

    appStore.showSuccess('Account created successfully!')
    router.push('/dashboard')
  } catch (error) {
    appStore.showError('Registration failed. Please try again.')
  }
}
```

## Validation Examples

### Login Validation

```typescript
// Valid inputs
✅ Username: "john_doe" (3+ chars)
✅ Password: "SecurePass123" (6+ chars)

// Invalid inputs
❌ Username: "jo" → Error: "Username must be at least 3 characters"
❌ Password: "12345" → Error: "Password must be at least 6 characters"
❌ Username: "" → Error: "Username is required"
❌ Password: "" → Error: "Password is required"
```

### Registration Validation

```typescript
// Valid inputs
✅ Username: "jane_smith" (3-50 chars, alphanumeric + _ -)
✅ Email: "jane@example.com" (valid format)
✅ Password: "SecurePass123" (8+ chars, letters + numbers)
✅ Confirm: "SecurePass123" (matches password)

// Invalid inputs
❌ Username: "ja" → Error: "Username must be at least 3 characters"
❌ Username: "jane@smith" → Error: "Username can only contain letters, numbers, underscores, and hyphens"
❌ Email: "invalid-email" → Error: "Please enter a valid email address"
❌ Password: "short" → Error: "Password must be at least 8 characters with letters and numbers"
❌ Password: "12345678" → Error: "Password must be at least 8 characters with letters and numbers" (no letters)
❌ Password: "password" → Error: "Password must be at least 8 characters with letters and numbers" (no numbers)
❌ Confirm: "DifferentPass" → Error: "Passwords do not match"
```

## Error Handling Examples

### Backend Errors

```typescript
// Example 1: Username already exists
{
  response: {
    data: {
      detail: "Username 'john_doe' is already taken"
    }
  }
}
// Displayed: "Username 'john_doe' is already taken"

// Example 2: Invalid credentials
{
  response: {
    data: {
      detail: 'Invalid username or password'
    }
  }
}
// Displayed: "Invalid username or password"

// Example 3: Network error
{
  message: 'Network Error'
}
// Displayed: "Network Error" + Error toast

// Example 4: Unknown error
{
}
// Displayed: "Login failed. Please check your credentials and try again." (default)
```

### Client-side Validation Errors

```typescript
// Multiple validation errors displayed simultaneously
errors = {
  username: 'Username must be at least 3 characters',
  email: 'Please enter a valid email address',
  password: 'Password must be at least 8 characters with letters and numbers',
  confirmPassword: 'Passwords do not match'
}

// Each error appears below its respective input field with red styling
```

## Testing Examples

### Unit Test: Login View

```typescript
import { describe, it, expect, vi } from 'vitest'
import { mount } from '@vue/test-utils'
import { createPinia } from 'pinia'
import LoginView from '@/views/auth/LoginView.vue'

describe('LoginView', () => {
  it('validates required fields', async () => {
    const wrapper = mount(LoginView, {
      global: {
        plugins: [createPinia()]
      }
    })

    // Submit empty form
    await wrapper.find('form').trigger('submit')

    // Check for validation errors
    expect(wrapper.text()).toContain('Username is required')
    expect(wrapper.text()).toContain('Password is required')
  })

  it('calls authStore.login on valid submission', async () => {
    const wrapper = mount(LoginView, {
      global: {
        plugins: [createPinia()]
      }
    })

    // Fill in form
    await wrapper.find('#username').setValue('john_doe')
    await wrapper.find('#password').setValue('SecurePass123')

    // Submit form
    await wrapper.find('form').trigger('submit')

    // Verify authStore.login was called
    // (mock implementation needed)
  })
})
```

### E2E Test: Registration Flow

```typescript
import { test, expect } from '@playwright/test'

test('user can register successfully', async ({ page }) => {
  // Navigate to register page
  await page.goto('/register')

  // Fill in registration form
  await page.fill('#username', 'new_user')
  await page.fill('#email', 'new_user@example.com')
  await page.fill('#password', 'SecurePass123')
  await page.fill('#confirmPassword', 'SecurePass123')

  // Submit form
  await page.click('button[type="submit"]')

  // Wait for redirect to dashboard
  await page.waitForURL('/dashboard')

  // Verify success toast appears
  await expect(page.locator('.toast-success')).toBeVisible()
  await expect(page.locator('.toast-success')).toContainText('Account created successfully')
})

test('shows validation errors for invalid inputs', async ({ page }) => {
  await page.goto('/register')

  // Enter mismatched passwords
  await page.fill('#password', 'SecurePass123')
  await page.fill('#confirmPassword', 'DifferentPass')

  // Submit form
  await page.click('button[type="submit"]')

  // Verify error message
  await expect(page.locator('text=Passwords do not match')).toBeVisible()
})
```

## Integration with Navigation Guards

### Router Guard Example

```typescript
import { useAuthStore } from '@/stores'

router.beforeEach((to, from, next) => {
  const authStore = useAuthStore()

  // Redirect authenticated users away from auth pages
  if (authStore.isAuthenticated && (to.path === '/login' || to.path === '/register')) {
    next('/dashboard')
    return
  }

  // Redirect unauthenticated users to login
  if (to.meta.requiresAuth && !authStore.isAuthenticated) {
    next({
      path: '/login',
      query: { redirect: to.fullPath }
    })
    return
  }

  next()
})
```

## Customization Examples

### Custom Success Redirect

```typescript
// In LoginView.vue
async function handleLogin(): Promise<void> {
  try {
    await authStore.login({
      username: formData.username,
      password: formData.password
    })

    appStore.showSuccess('Login successful!')

    // Custom redirect logic
    const isAdmin = authStore.isAdmin
    const redirectTo = isAdmin ? '/admin/dashboard' : '/dashboard'

    await router.push(redirectTo)
  } catch (error) {
    // Error handling...
  }
}
```

### Custom Validation Rules

```typescript
// Custom password strength validation
function validatePasswordStrength(password: string): boolean {
  const hasMinLength = password.length >= 12
  const hasUpperCase = /[A-Z]/.test(password)
  const hasLowerCase = /[a-z]/.test(password)
  const hasNumber = /[0-9]/.test(password)
  const hasSpecialChar = /[!@#$%^&*(),.?":{}|<>]/.test(password)

  return hasMinLength && hasUpperCase && hasLowerCase && hasNumber && hasSpecialChar
}

// Use in validation
if (!validatePasswordStrength(formData.password)) {
  errors.password =
    'Password must be at least 12 characters with uppercase, lowercase, numbers, and special characters'
  isValid = false
}
```

### Custom Error Handling

```typescript
// In RegisterView.vue
async function handleRegister(): Promise<void> {
  try {
    await authStore.register({
      username: formData.username,
      email: formData.email,
      password: formData.password
    })

    appStore.showSuccess('Account created successfully!')
    await router.push('/dashboard')
  } catch (error: unknown) {
    const err = error as { response?: { status?: number; data?: { detail?: string } } }

    // Custom error handling based on status code
    if (err.response?.status === 409) {
      errorMessage.value =
        'This username or email is already registered. Please use a different one.'
    } else if (err.response?.status === 422) {
      errorMessage.value = 'Invalid input. Please check your information and try again.'
    } else if (err.response?.status === 500) {
      errorMessage.value = 'Server error. Please try again later.'
    } else {
      errorMessage.value = err.response?.data?.detail || 'Registration failed. Please try again.'
    }

    appStore.showError(errorMessage.value)
  }
}
```

## Accessibility Examples

### Keyboard Navigation

```typescript
// Tab order:
// 1. Username input
// 2. Password input
// 3. Remember me checkbox (login) / Confirm password (register)
// 4. Submit button
// 5. Footer link (register/login)

// Enter key submits form
// Escape key can be used to clear focus
```

### Screen Reader Support

```html
<!-- Proper labels for screen readers -->
<label for="username" class="mb-1 block text-sm font-medium text-gray-700"> Username </label>
<input
  id="username"
  type="text"
  aria-label="Username"
  aria-required="true"
  aria-invalid="false"
  aria-describedby="username-error"
/>
<p id="username-error" role="alert" class="text-sm text-red-600">
  <!-- Error message here -->
</p>

<!-- Loading state announced -->
<button type="submit" aria-busy="true" aria-label="Signing in...">
  <span class="sr-only">Signing in...</span>
  <!-- Visual content -->
</button>
```

## Performance Considerations

### Lazy Loading

```typescript
// Router configuration with lazy loading
{
  path: '/login',
  component: () => import('@/views/auth/LoginView.vue'), // ✅ Lazy loaded
}

// Direct import (not recommended for routes)
import LoginView from '@/views/auth/LoginView.vue'; // ❌ Eager loaded
```

### Optimization Tips

1. Use `v-once` for static content
2. Debounce expensive validation operations
3. Minimize reactive dependencies
4. Use `shallowRef` for complex objects when possible
5. Avoid unnecessary watchers

## Security Best Practices

1. Never log passwords or tokens
2. Use HTTPS in production
3. Implement rate limiting on backend
4. Validate all inputs server-side
5. Use secure password hashing (bcrypt, argon2)
6. Implement CSRF protection
7. Set secure cookie flags
8. Use Content Security Policy headers
9. Sanitize all user inputs
10. Implement account lockout after failed attempts

## Common Issues and Solutions

### Issue: Token not persisting after refresh

```typescript
// Solution: Initialize auth state on app mount
// In main.ts or App.vue
import { useAuthStore } from '@/stores'

const authStore = useAuthStore()
authStore.checkAuth() // Restore auth from localStorage
```

### Issue: Redirect loop after login

```typescript
// Solution: Check router guard logic
router.beforeEach((to, from, next) => {
  const authStore = useAuthStore()

  // ✅ Correct: Check specific routes
  if (authStore.isAuthenticated && (to.path === '/login' || to.path === '/register')) {
    next('/dashboard')
    return
  }

  // ❌ Wrong: Blanket redirect
  // if (authStore.isAuthenticated) {
  //   next('/dashboard'); // This causes loops!
  // }

  next()
})
```

### Issue: Form not clearing after successful submission

```typescript
// Solution: Reset form data
async function handleLogin(): Promise<void> {
  try {
    await authStore.login({...});

    // Reset form
    formData.username = '';
    formData.password = '';
    formData.remember = false;

    // Clear errors
    errors.username = '';
    errors.password = '';

    await router.push('/dashboard');
  } catch (error) {
    // Error handling...
  }
}
```

## Additional Resources

- [Vue 3 Documentation](https://vuejs.org/)
- [Vue Router Documentation](https://router.vuejs.org/)
- [Pinia Documentation](https://pinia.vuejs.org/)
- [TailwindCSS Documentation](https://tailwindcss.com/)
- [TypeScript Handbook](https://www.typescriptlang.org/docs/)