Merge origin/main into fix/issue-470-mobile-scanning

Author: helenahelenavanbeek-png

.eslintignore

@@ -3,3 +3,25 @@ node_modules/
 public/
 build/
 coverage/
+src/app/(auth)/
+src/app/admin/
+src/app/api/
+src/app/breadcrumbs-demo/
+src/app/certificates/
+src/app/components/
+src/app/dashboard/
+src/app/hooks/
+src/app/layout.tsx
+src/app/privacy/
+src/app/release-notes/
+src/app/support/
+src/app/tooltip-demo/
+src/components/
+src/context/
+src/form-management/
+src/hooks/
+src/schemas/
+src/services/
+src/types/
+src/utils/virtualBackgroundUtils.ts
+src/workers/

.idea/.gitignore

@@ -0,0 +1,233 @@
+# Circuit Breaker Implementation for Toast Notifications
+
+## Overview
+
+This document describes the Circuit Breaker pattern implementation for Toast Notifications in the TeachLink frontend. The Circuit Breaker prevents cascading failures and provides fallback behavior when the toast notification system is overwhelmed.
+
+## Architecture
+
+### Components
+
+1. **Circuit Breaker Core** (`src/utils/circuitBreaker.ts`)
+   - Implements the Circuit Breaker pattern with three states: CLOSED, OPEN, HALF_OPEN
+   - Tracks metrics including failure count, success count, and request statistics
+   - Provides configurable thresholds for failure tolerance and recovery
+
+2. **Toast Context Integration** (`src/context/ToastContext.tsx`)
+   - Integrates Circuit Breaker with the existing Toast notification system
+   - Provides fallback behavior when circuit is open
+   - Exposes metrics and reset functionality through the context API
+
+### Circuit States
+
+- **CLOSED**: Normal operation, all requests pass through
+- **OPEN**: Circuit is tripped, requests fail fast with fallback behavior
+- **HALF_OPEN**: Testing if the system has recovered, limited requests allowed
+
+## Configuration
+
+### Default Configuration
+
+```typescript
+{
+  failureThreshold: 5,        // Number of failures before opening
+  successThreshold: 2,        // Number of successes to close circuit
+  timeout: 60000,            // Time in ms before attempting recovery (1 minute)
+  monitoringPeriod: 10000,   // Time window for failure counting (10 seconds)
+  maxConcurrentRequests: 10  // Maximum concurrent toast operations
+}
+```
+
+### Custom Configuration
+
+You can customize the Circuit Breaker behavior by passing a config object:
+
+```typescript
+import { createToastCircuitBreaker } from '@/utils/circuitBreaker';
+
+const customBreaker = createToastCircuitBreaker({
+  failureThreshold: 10,
+  successThreshold: 5,
+  timeout: 30000,
+  monitoringPeriod: 20000,
+  maxConcurrentRequests: 20,
+});
+```
+
+## Usage
+
+### Basic Usage
+
+The Circuit Breaker is automatically integrated with the Toast system. No changes are needed in existing code:
+
+```typescript
+import { useToast } from '@/context/ToastContext';
+
+function MyComponent() {
+  const { success, error, info } = useToast();
+
+  const handleClick = () => {
+    success('Operation completed successfully');
+    // Circuit Breaker automatically handles this
+  };
+
+  return <button onClick={handleClick}>Click me</button>;
+}
+```
+
+### Accessing Metrics
+
+You can access Circuit Breaker metrics to monitor its state:
+
+```typescript
+import { useToast } from '@/context/ToastContext';
+
+function CircuitBreakerMonitor() {
+  const { getCircuitBreakerMetrics } = useToast();
+  const metrics = getCircuitBreakerMetrics();
+
+  console.log('Circuit State:', metrics.state);
+  console.log('Total Requests:', metrics.totalRequests);
+  console.log('Total Failures:', metrics.totalFailures);
+  console.log('Total Successes:', metrics.totalSuccesses);
+
+  return null;
+}
+```
+
+### Manual Reset
+
+You can manually reset the Circuit Breaker if needed:
+
+```typescript
+import { useToast } from '@/context/ToastContext';
+
+function ResetButton() {
+  const { resetCircuitBreaker } = useToast();
+
+  return (
+    <button onClick={resetCircuitBreaker}>
+      Reset Circuit Breaker
+    </button>
+  );
+}
+```
+
+## Fallback Behavior
+
+When the Circuit Breaker is OPEN, the system provides a fallback behavior:
+
+1. **Console Logging**: All suppressed toasts are logged to the console with details
+2. **Limited Fallback Toast**: A simplified "Notifications temporarily limited" toast is shown
+3. **Queue Management**: Only the most recent 2 toasts are kept in the queue
+
+This ensures users are informed without overwhelming the system.
+
+## Testing
+
+### Unit Tests
+
+Comprehensive unit tests are available in `src/utils/__tests__/circuitBreaker.test.ts`:
+
+```bash
+pnpm run test circuitBreaker.test.ts
+```
+
+Test coverage includes:
+- Initial state verification
+- Successful operations
+- Failed operations and threshold handling
+- Fallback behavior
+- Recovery (HALF_OPEN state transitions)
+- Concurrent request limiting
+- Metrics tracking
+- Manual reset functionality
+- Factory function behavior
+- Failure history cleanup
+
+### Running Tests
+
+```bash
+# Run all tests
+pnpm run test
+
+# Run with coverage
+pnpm run test:coverage
+
+# Run in watch mode
+pnpm run test:watch
+```
+
+## Performance Impact
+
+The Circuit Breaker has minimal performance impact:
+
+- **Overhead**: ~0.1ms per toast operation
+- **Memory**: ~1KB per Circuit Breaker instance
+- **No blocking**: All operations are asynchronous
+
+## Security Considerations
+
+- No sensitive data is stored in the Circuit Breaker
+- Metrics are purely for monitoring and debugging
+- Fallback behavior does not expose system internals
+
+## Accessibility
+
+The Circuit Breaker does not affect accessibility:
+- Toast notifications remain accessible when circuit is CLOSED
+- Fallback toast uses standard accessible patterns
+- No impact on screen readers or keyboard navigation
+
+## Troubleshooting
+
+### Circuit Stays Open
+
+If the Circuit Breaker remains OPEN for longer than expected:
+
+1. Check the timeout configuration
+2. Verify that operations are actually succeeding
+3. Use `getCircuitBreakerMetrics()` to inspect the state
+4. Manually reset if needed using `resetCircuitBreaker()`
+
+### Too Many Failures
+
+If you're seeing frequent circuit trips:
+
+1. Increase the `failureThreshold` configuration
+2. Investigate the root cause of toast operation failures
+3. Check if `maxConcurrentRequests` is too low for your use case
+
+### Metrics Not Updating
+
+If metrics appear stale:
+
+1. Verify the Circuit Breaker is being used (check `totalRequests`)
+2. Ensure the ToastProvider is wrapping your app
+3. Check browser console for any errors
+
+## Future Enhancements
+
+Potential improvements for future iterations:
+
+- [ ] Persistent metrics storage (localStorage)
+- [ ] Circuit Breaker state visualization in dev tools
+- [ ] Adaptive threshold adjustment based on system load
+- [ ] Integration with error tracking services
+- [ ] Circuit Breaker events for monitoring systems
+
+## References
+
+- [Circuit Breaker Pattern - Martin Fowler](https://martinfowler.com/bliki/CircuitBreaker.html)
+- [Microsoft Circuit Breaker Pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/circuit-breaker)
+
+## Changelog
+
+### Version 1.0.0
+- Initial implementation
+- Three-state Circuit Breaker (CLOSED, OPEN, HALF_OPEN)
+- Configurable thresholds and timeouts
+- Metrics tracking and reporting
+- Fallback behavior for suppressed toasts
+- Comprehensive unit tests
+- Integration with Toast Context

CIRCUIT_BREAKER_IMPLEMENTATION.md

@@ -38,6 +38,7 @@ Use **assertive** only for urgent errors or time-sensitive status.
 
 - Give the primary `<main>` a stable id such as `main-content` so skip links and **Alt+M** work everywhere. There should be **exactly one** `<main>` (or `role="main"`) per view.
 - For horizontal toolbars, add `data-roving-root` on the toolbar container. **Left/Right arrow** moves among buttons, links, tabs, and elements marked with `data-roving-item` (including those using `tabindex="-1"` for roving patterns).
+- Rich post editors should expose a named multiline textbox, a named formatting toolbar with pressed states, and helper text connected through `aria-describedby`. Post composer message lists should use `role="log"` with polite updates so new discussion activity is announced without interrupting the current task.
 
 ## What automation does _not_ prove
 

docs/ACCESSIBILITY.md

@@ -0,0 +1,38 @@
+**Canary Release for Tip Receiving**
+
+Summary
+- **Purpose:** Enable percentage-based canary rollout for the Tip Receiving feature.
+- **Mechanism:** Server-side feature flag evaluated per-request with deterministic user bucketing.
+
+Configuration
+- Set the rollout percentage via environment variable `TIP_RECEIVING_CANARY_PERCENT` (0-100).
+- `NEXT_PUBLIC_TIP_RECEIVING_CANARY_PERCENT` is also respected for environments that surface public envs.
+
+Rollout behavior
+- Server evaluates the flag for each incoming request to `/api/tips`.
+- A stable identifier is used for bucketing in this order:
+  - `user-id` cookie
+  - `x-user-id` request header
+  - `anon-user-id` cookie (generated and set when missing)
+- Deterministic DJB2 hash maps identifier into a 1..100 bucket; users in bucket <= percent are routed to canary.
+
+Rollback
+- To rollback, set `TIP_RECEIVING_CANARY_PERCENT=0` and reload configuration — no code change required.
+
+Observability
+- The server emits structured log lines for evaluation decisions:
+  - event: `tip_canary_evaluation`
+  - percent, bucket, enabled
+- Integrate these logs with your metrics pipeline to produce counts of canary vs stable users.
+
+Security
+- The decision is done server-side — clients cannot flip the flag.
+- The implementation avoids logging raw user identifiers; only bucket and percent are logged.
+
+Testing
+- Unit tests cover hashing, percent boundaries, deterministic bucketing and anon-id generation.
+- Integration tests exercise the `/api/tips` route with canary enabled and disabled.
+
+Operational notes
+- The canary flag reads environment variables at runtime — ensure your deployment system can change env vars without a full redeploy when possible.
+- For accurate bucketing of anonymous users, the `anon-user-id` cookie is set on first use.