release: finalize FocusFlow v1.0

Author: jesusdev98

README.md

@@ -1,216 +1,162 @@
-<div align="center">
+# FocusFlow
 
-# DevBreak
+FocusFlow is an installable Angular productivity workspace for focused work, lightweight task planning, and healthier recovery habits.
 
-**A calm Angular productivity workspace for focused work, operational task flow, and sustainable recovery habits.**
-
-![Angular](https://img.shields.io/badge/Angular-21-DD0031?style=for-the-badge&logo=angular&logoColor=white)
-![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
-![RxJS](https://img.shields.io/badge/RxJS-7.8-B7178C?style=for-the-badge&logo=reactivex&logoColor=white)
-![SCSS](https://img.shields.io/badge/SCSS-Responsive%20UX-CC6699?style=for-the-badge&logo=sass&logoColor=white)
-![Cypress](https://img.shields.io/badge/Cypress-E2E-17202C?style=for-the-badge&logo=cypress&logoColor=white)
-
-</div>
-
----
+It combines a focus timer, Pomodoro workflows, a Kanban board, and wellness-aware break suggestions in a frontend-only PWA that works well on desktop, tablet, and mobile.
 
 ## Overview
 
-DevBreak is a portfolio-grade productivity workspace built with Angular. It combines an operational Kanban board, focus sessions, keyboard-first workflows, wellness-aware reminders, local persistence, accessibility support, and responsive dashboard ergonomics.
+FocusFlow is built around a simple idea: productivity tools should support attention without ignoring recovery. The app helps users plan tasks, run focused sessions, track meaningful daily progress, and take small movement or wellness breaks without adding noise to the workflow.
 
-The product is intentionally calm: it helps users move work forward without turning productivity into a noisy scoring system.
+The application is fully client-side and offline-first. User preferences, sessions, tasks, wellness exercises, language settings, and productivity state are persisted locally with safe restoration and fallback behavior.
 
----
+## Features
 
-## Highlights
+- Focus timer with completion tracking and daily productivity stats
+- Pomodoro mode with configurable focus, short break, and long break durations
+- Wellness mode for movement-friendly work sessions
+- Hybrid mode that blends focus sessions with active recovery prompts
+- Kanban workspace with task creation, editing, completion, archiving, restore, filtering, sorting, and drag/drop-ready workflows
+- Custom wellness exercises by category, including stretching, mobility, cardio, strength, and Pilates
+- Sound personalization with volume, preset, and repeat alert settings
+- Runtime internationalization for English, Spanish, and French
+- Installable PWA support with manifest, service worker, offline asset caching, and app-like standalone behavior
+- LocalStorage-backed offline persistence with defensive normalization for legacy or malformed data
+- Responsive layouts for desktop, installed PWA windows, tablets, and mobile screens
+- Accessibility-minded interaction design with keyboard navigation, focus handling, labels, and live announcements
 
-- Operational Kanban board with create, edit, archive, restore, drag/drop-ready workflows
-- Quick-add per column for low-friction task capture
-- Advanced filters, sorting, density modes, and search
-- Focus ownership mode with active-task workflow
-- Timer and Pomodoro sessions with resilient timestamp-based persistence
-- Adaptive wellness reminders for hydration, posture, and movement recovery
-- Contextual recovery suggestions and lightweight wellness consistency tracking
-- Keyboard shortcut personalization with conflict prevention
-- Workspace and daily productivity reset actions
-- Dark/light themes, reduced-motion support, and responsive layouts
-- Cypress E2E coverage for core workflows, persistence, keyboard, and accessibility behavior
+## Tech Stack
 
----
+- Angular
+- TypeScript
+- RxJS
+- SCSS
+- Angular CDK
+- Angular service worker / PWA support
+- ngx-translate
+- Vitest / Angular test runner
+- Cypress
 
-## Product Philosophy
+## Architecture
 
-DevBreak is not a Pomodoro clone and not a fitness tracker. It is a focused workspace that treats productivity and recovery as part of the same workflow.
+FocusFlow uses a frontend-only Angular architecture with feature modules for the timer and Kanban workspace. State is owned by focused Angular services and exposed through RxJS streams so UI components can stay mostly presentational.
 
-Wellness guidance is intentionally subtle:
+The app does not require a backend. Persistence is handled through localStorage with validation and normalization on restore. Productivity metrics are derived from canonical session and task history instead of separate drifting counters.
 
-- no blocking modals
-- no gamification pressure
-- no productivity guilt
-- no invasive notifications
-- supportive summaries only after meaningful activity exists
+Core architectural choices:
 
----
+- Client-side only, deployable as static assets
+- Offline-first PWA behavior after the first visit
+- Service-owned state for timer, session history, tasks, wellness preferences, shortcuts, language, and workspace mode
+- Derived productivity stats for completed sessions, skipped sessions, focus minutes, streaks, completed tasks, and recovery rhythm
+- Lightweight persistence with safe fallbacks instead of sync infrastructure
 
-## Architecture
+## Installation
 
-The app uses a modular feature structure with service-owned state and presentational component boundaries.
+Install dependencies:
 
-```text
-src/app/
-  features/
-    kanban/
-      components/
-      models/
-      services/
-    timer/
-      components/
-      models/
-      services/
-  models/
-  services/
+```bash
+npm install
 ```
 
-Key architectural choices:
-
-- RxJS streams for timer, workspace mode, focus, wellness, and derived UI state
-- LocalStorage persistence with validation and safe fallbacks
-- Angular CDK DragDrop for board interactions
-- Focused presentational component boundaries for settings, timer actions, wellness cards, and insights
-- CSS variables for density, theme, and responsive ergonomics
-- Minimal global state, no backend assumptions, no heavyweight store layer
+Run the development server:
 
----
-
-## Accessibility
-
-DevBreak includes an accessibility pass across semantics, keyboard behavior, screen-reader feedback, and motion preferences.
+```bash
+npm start
+```
 
-- Landmark and heading structure
-- Accessible form labels and icon/control labels
-- Visible focus states
-- ESC handling and focus restoration
-- Keyboard activation parity for primary workflows
-- ARIA live regions for meaningful state changes
-- `prefers-reduced-motion` support
-- Cypress coverage for keyboard and accessibility-critical flows
+Open the app:
 
----
+```text
+http://localhost:4200/
+```
 
-## Testing & Reliability
+Create a production build:
 
 ```bash
-npm test
 npm run build
-npm run e2e
 ```
 
-Current validation status:
-
-- 56 automated tests passing
-- Production build passing
-- Cypress workflow coverage stable
-
-Coverage includes:
-
-- Unit tests for timer persistence, wellness heuristics, shortcuts, filters, density, and component behavior
-- Cypress E2E tests for Kanban, focus sessions, persistence restore, keyboard workflows, and reduced-motion smoke coverage
-- Production build validation through Angular budgets
-
-Note for local Windows shells: if Cypress inherits `ELECTRON_RUN_AS_NODE`, clear it before running E2E.
+Run the unit test suite:
 
-```powershell
-Remove-Item Env:ELECTRON_RUN_AS_NODE -ErrorAction SilentlyContinue
-$env:CYPRESS_SKIP_VERIFY='true'
-npm run e2e
+```bash
+npm test -- --watch=false
 ```
 
----
-
-## Tech Stack
-
-- Angular
-- TypeScript
-- RxJS
-- SCSS
-- Angular CDK
-- Vitest / Angular unit testing
-- Cypress
-- GitHub Actions
-
----
-
-## Getting Started
-
-Use the Node version in `.nvmrc`.
+Run Cypress E2E tests:
 
 ```bash
-npm install
-npm start
+npm run e2e
 ```
 
-Open:
+## PWA Support
 
-```text
-http://localhost:4200/
-```
+FocusFlow includes Angular service worker support and a configured web app manifest.
 
-Production build:
+The production build supports:
 
-```bash
-npm run build
-```
+- Desktop installation in Chromium-based browsers such as Chrome and Edge
+- Android installation through supported mobile browsers
+- Standalone app display mode
+- Offline reload after the first successful visit
+- Cached application shell and static assets
+- Local persistence for tasks, settings, wellness exercises, language, theme, and productivity history
 
----
+Because the app is frontend-only, offline support is intentionally local-first. There is no account system or cloud sync layer.
 
-## Deployment
+## Accessibility
 
-The app is static-build ready.
+Accessibility is treated as part of the product surface, not as a separate mode.
 
-### GitHub Pages
+The app includes:
 
-The included workflow builds the Angular app with a repository-based `base-href`, uploads `dist/devbreak-timer/browser`, and adds a `404.html` fallback for SPA-compatible refresh behavior.
+- Keyboard-accessible primary flows
+- Visible focus states
+- Focus restoration for settings and dialog-like interactions
+- Escape handling where appropriate
+- Form labels and accessible control names
+- ARIA live announcements for important timer and task state changes
+- Responsive layouts that preserve readable controls on small screens
+- Reduced-motion considerations in the UI layer
 
-Required repository setting:
+## Screenshots
 
-```text
-Settings -> Pages -> Source -> GitHub Actions
-```
+Screenshots are intentionally left as placeholders so they can reflect the final deployed build.
 
-### Vercel
+### Desktop
 
-Recommended settings:
+Add a desktop screenshot here.
 
-```text
-Framework Preset: Angular
-Build Command: npm run build
-Output Directory: dist/devbreak-timer/browser
-Install Command: npm ci
-```
+### Mobile
+
+Add a mobile screenshot here.
 
-For SPA fallback routing, add a Vercel rewrite if routes are introduced later.
+### Wellness Mode
 
----
+Add a wellness mode screenshot here.
 
-## GitHub Actions
+### Kanban Workspace
 
-Workflows are intentionally lightweight:
+Add a Kanban workspace screenshot here.
 
-- CI: install, unit tests, production build
-- Pages deploy: install, unit tests, production build, upload static artifact
+## Future Improvements
 
-Cypress remains available for local and future CI expansion without making the default pipeline heavy.
+FocusFlow is intentionally complete as a local-first PWA, but a few realistic extensions would fit the product:
 
----
+- Optional cloud sync for users who want multi-device continuity
+- Richer productivity and recovery analytics
+- More built-in wellness exercise presets
+- Optional import/export for local data portability
+- Additional language packs
 
-## Portfolio Notes
+## Release Notes
 
-DevBreak demonstrates production-minded frontend work:
+FocusFlow is designed as a polished portfolio project that demonstrates production-minded Angular development:
 
-- product-oriented UX decisions
-- accessible keyboard-first interaction design
-- resilient local persistence
-- maintainable Angular boundaries
-- responsive operational UI
-- calm wellness-aware behavior
-- meaningful automated reliability coverage
+- Modular frontend architecture
+- Offline-first PWA integration
+- Responsive operational UI
+- Local persistence and defensive state restoration
+- Runtime i18n
+- Accessibility-aware interaction design
+- Behavior-focused tests around session tracking, tasks, wellness logic, and productivity stats

angular.json

@@ -47,7 +47,7 @@
               "budgets": [
                 {
                   "type": "initial",
-                  "maximumWarning": "500kB",
+                  "maximumWarning": "550kB",
                   "maximumError": "1MB"
                 },
                 {
@@ -56,7 +56,8 @@
                   "maximumError": "10kb"
                 }
               ],
-              "outputHashing": "all"
+              "outputHashing": "all",
+              "serviceWorker": "ngsw-config.json"
             },
             "development": {
               "optimization": false,

cypress/e2e/keyboard-accessibility.cy.ts

@@ -80,6 +80,22 @@ describe('Keyboard and accessibility workflows', () => {
     cy.focused().should('have.attr', 'data-testid', 'settings-button');
   });
 
+  it('keeps keyboard focus inside the settings dialog until it closes', () => {
+    cy.visit('/');
+
+    cy.getByTestId('settings-button').click();
+    cy.focused().should('contain.text', 'Close');
+
+    cy.focused().type('{shift+tab}');
+    cy.focused().should('contain.text', 'Apply');
+
+    cy.focused().type('{tab}');
+    cy.focused().should('contain.text', 'Close');
+
+    cy.get('body').type('{esc}');
+    cy.focused().should('have.attr', 'data-testid', 'settings-button');
+  });
+
   it('keeps workflows usable with reduced motion enabled', () => {
     cy.clock(now, ['Date', 'setInterval', 'clearInterval']);
     cy.visit('/', {