From 4c641b9b16b374e1d68c263f8299e8acaa0a5c8f Mon Sep 17 00:00:00 2001 From: lorentz Date: Sun, 3 May 2026 13:51:06 -0400 Subject: [PATCH] docs(01-pwa-scaffolding): add gap closure plan 01-02 for PWA-04 safe-area utilities --- .planning/ROADMAP.md | 151 ------------------------------------------- 1 file changed, 151 deletions(-) delete mode 100644 .planning/ROADMAP.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md deleted file mode 100644 index bffa497..0000000 --- a/.planning/ROADMAP.md +++ /dev/null @@ -1,151 +0,0 @@ -# Roadmap: Pulse Mobile Shell Redesign - -## Overview - -Eight phases mirror the deliberate build order in the source spec -(`docs/superpowers/specs/2026-05-03-mobile-shell-design.md` §8). Each phase -ships independently to `master` — no big-bang merge. Phase 1 lays PWA -metadata and safe-area utilities. Phase 2 rebuilds `app/mobile/layout.tsx` -with the new header, 5-cell bottom nav, and More drawer (deleting -`/mobile/nav` in the same change). Once the shell lands, Phases 3–7 are -independent restyles/new pages and may be executed in parallel; Phase 8 -follows Phase 7 because the user profile is reached from the Engagement -overview. All work happens in place under `/mobile/*` — no `/mobile-v2`, -no parallel routes. - -## Phases - -**Phase Numbering:** -- Integer phases (1, 2, 3): Planned milestone work -- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED) - -Decimal phases appear between their surrounding integers in numeric order. - -- [ ] **Phase 1: PWA Scaffolding** — Manifest, viewport meta, and safe-area utilities so the shell installs and paints under the home indicator -- [ ] **Phase 2: Mobile Shell + More Drawer** — New `app/mobile/layout.tsx` (header + 5-cell bottom nav) and Sheet drawer that replaces `/mobile/nav` -- [ ] **Phase 3: Dashboard Restyle** — 2×2 KPI grid, Needs Attention strip, worker/backup status row (no charts) -- [ ] **Phase 4: Tickets Restyle** — Collapsible URL-synced filters, priority-bar rows, cursor-based infinite scroll, detail header reskin -- [ ] **Phase 5: Finance Restyle** — Adopt new Card + typography scale, swap wide tables for stacked lists -- [ ] **Phase 6: Analyzer Feed (NEW)** — `/mobile/analyzer` read-only stream + `/api/mobile/analyzer/feed` -- [ ] **Phase 7: Engagement Overview (NEW)** — `/mobile/engagement` phone-first overview reachable from the More drawer -- [ ] **Phase 8: Engagement User Profile (NEW)** — `/mobile/engagement/[userId]` real-page profile that replaces the desktop modal pattern - -## Phase Details - -### Phase 1: PWA Scaffolding -**Goal**: A manager who taps "Add to Home Screen" gets a standalone Pulse icon that opens to the mobile shell with content respecting the device safe areas. -**Depends on**: Nothing (first phase) -**Requirements**: PWA-01, PWA-02, PWA-03, PWA-04 -**Success Criteria** (what must be TRUE): - 1. Visiting `/manifest.json` returns valid JSON with `name: "Pulse"`, `display: "standalone"`, `start_url: "/mobile"`, and theme/background colors matching the app shells - 2. The root `app/layout.tsx` references the manifest via `` and the viewport meta includes `viewport-fit=cover` - 3. A safe-area utility (Tailwind arbitrary values or shared class) is available so any sticky top/bottom bar can opt into `env(safe-area-inset-top)` / `env(safe-area-inset-bottom)` padding - 4. Installing Pulse to a phone home screen launches a chromeless app pointed at `/mobile` (no service worker, no offline) -**Plans**: TBD -**UI hint**: no - -### Phase 2: Mobile Shell + More Drawer -**Goal**: Every `/mobile/*` page renders inside a new layout — sticky header (Wulf mark + Bell placeholder + avatar), scrollable content, and a 5-cell bottom nav whose fifth control opens a Sheet drawer that fully replaces `/mobile/nav`. -**Depends on**: Phase 1 -**Requirements**: SHELL-01, SHELL-02, SHELL-03, SHELL-04, SHELL-05, SHELL-06, NAV-01, NAV-02, NAV-03, DRAWER-01, DRAWER-02, DRAWER-03, DRAWER-04, DRAWER-05, DRAWER-06 -**Success Criteria** (what must be TRUE): - 1. On any `/mobile/*` route the user sees a sticky header with the Wulf wordmark linking to `/mobile/dashboard`, a Bell icon button (keyboard-focusable, no menu), and a compact avatar — no page title in the header - 2. A fixed bottom bar exposes four primary tabs (Dashboard, Tickets, Finance, Analyzer) plus a More cell; tapping a tab routes to its page and the active tab uses `text-primary` based on `pathname.startsWith(href)` - 3. Tapping More (or the header avatar) opens a single Sheet drawer with three sections — Mobile sections (Engagement), Full site (Quotes, Configuration Items, Backup Status, Ticket Digest, Admin/Sync — each with an `ExternalLink` hint), and Account (current user read-only + Sign out) - 4. Tapping Sign out in the drawer signs the user out and lands them on `/auth/sign-in` - 5. `app/mobile/nav/page.tsx` no longer exists; visiting `/mobile/nav` does not render the old standalone nav page - 6. Page content scrolls under the sticky header and is not hidden behind the bottom nav (bottom padding accounts for nav height + safe-area inset) -**Plans**: TBD -**UI hint**: yes - -### Phase 3: Dashboard Restyle -**Goal**: A manager opening `/mobile/dashboard` sees the state of the business at a glance — four KPIs, items needing attention, and a worker/backup status row — with no charts. -**Depends on**: Phase 2 -**Requirements**: DASH-01, DASH-02, DASH-03, DASH-04 -**Success Criteria** (what must be TRUE): - 1. Dashboard renders a 2×2 grid of four primary KPI cards drawn from desktop hero stats (no 1×4 row, no charts) - 2. Below the grid, a "Needs Attention" horizontally-scrollable strip surfaces overdue tickets, failed backups, and stalled workflows; tapping a card opens its detail view - 3. A compact status row shows analyzer worker, RMM worker, and backup-success-rate; tapping any element opens the corresponding desktop admin page - 4. The page contains no recharts/chart components on phone widths -**Plans**: TBD -**UI hint**: yes - -### Phase 4: Tickets Restyle -**Goal**: A manager triages tickets on a phone with a collapsible filter bar that deep-links via URL, priority-coloured rows, and infinite scroll — and the detail page header matches the new shell. -**Depends on**: Phase 2 -**Requirements**: TICK-01, TICK-02, TICK-03, TICK-04, TICK-05, TICK-06, TICK-07 -**Success Criteria** (what must be TRUE): - 1. The Tickets page opens with the filter strip collapsed; expanding it reveals status, priority, queue, and an assigned-to-me toggle, and changing any filter updates the URL query string (deep link works on reload) - 2. Each list row has a left-edge stripe matching priority (Critical/High/Medium/Low → red/orange/amber/slate) and shows ticket #, title, company, age, and assignee - 3. Single-tapping a row navigates to `/mobile/tickets/[id]` - 4. Scrolling to the bottom of the list automatically loads the next ~25 rows (no Next button); a "Load more" fallback button is also visible/focusable for accessibility - 5. The detail page header uses the new shell styling (Wulf mark, breadcrumb back) while the body remains largely unchanged -**Plans**: TBD -**UI hint**: yes - -### Phase 5: Finance Restyle -**Goal**: A manager reading AR / invoice / payment status on a phone sees properly spaced cards and stacked lists instead of squished wide tables — same data, new shell. -**Depends on**: Phase 2 -**Requirements**: FIN-01, FIN-02 -**Success Criteria** (what must be TRUE): - 1. `/mobile/finance` adopts the new Card and typography scale — no horizontal overflow, spacing legible on small phones - 2. Sections that previously rendered wide tables on phone widths now render as stacked lists (no new sections, no new data sources) -**Plans**: TBD -**UI hint**: yes - -### Phase 6: Analyzer Feed (NEW) -**Goal**: A manager taps the Analyzer tab and skims a most-recent-first stream of AI ticket analyses, opening any one to a phone-friendly summary view that links out to desktop for full details. -**Depends on**: Phase 2 -**Requirements**: ANL-01, ANL-02, ANL-03, ANL-04, ANL-05, ANL-06 -**Success Criteria** (what must be TRUE): - 1. Tapping the Analyzer tab in the bottom nav lands on `/mobile/analyzer` and shows a most-recent-first list of AI ticket analyses - 2. Each row shows ticket #, title, the analyzer's one-line summary, a confidence badge, and a stage indicator (Triage → Analyze → Deep Review) - 3. Tapping a row opens a mobile summary view rendering Summary, Next Step, and Next Step Rationale, with a "View full analysis" link out to the desktop analyzer page - 4. The mobile feed never exposes editing, re-run, or prompt-tuning controls (read-only by design) - 5. The list reads from `analyzer_analyses` via `/api/mobile/analyzer/feed` (or a reused list endpoint that already returns the right shape) -**Plans**: TBD -**UI hint**: yes - -### Phase 7: Engagement Overview (NEW) -**Goal**: A manager reaches Engagement from the More drawer and sees a phone-first overview — period chips, stacked summary cards, a sortable per-employee list, and one compact sparkline. -**Depends on**: Phase 2 -**Requirements**: ENG-01, ENG-02, ENG-03, ENG-04, ENG-05, ENG-09 -**Success Criteria** (what must be TRUE): - 1. The Mobile sections row in the More drawer links to `/mobile/engagement`; the Analyzer is on the bottom bar but Engagement is not - 2. The overview page shows a period selector (today / 7d / 30d) sticky just below the H1, with active period clearly indicated - 3. Summary cards (active users, total Graph hours, total Autotask hours, hours-per-active-user) render single-column stacked — no 4-up grid on phone widths - 4. The per-employee list renders as stacked rows (avatar/initials, name, role, hours bar) with a search input and a sort control above (sort by hours, name, utilization) - 5. A single compact "hours trend" sparkline renders at the top of the list, scoped to the selected period — no multi-series chart -**Plans**: TBD -**UI hint**: yes - -### Phase 8: Engagement User Profile (NEW) -**Goal**: From the Engagement overview, a manager taps an employee row and arrives at a real, shareable profile page — single-column phone-first — and the device back gesture returns them to the overview. -**Depends on**: Phase 7 -**Requirements**: ENG-06, ENG-07, ENG-08 -**Success Criteria** (what must be TRUE): - 1. Tapping a row in the per-employee list navigates to `/mobile/engagement/[userId]` (segment form, shareable URL) - 2. The profile is a real page (not a modal) — the device/browser back gesture returns to the overview at the same scroll position - 3. The profile renders single-column: identity header → period selector → key metrics (compact) → activity breakdown list → recent items, sourced from the existing engagement profile data endpoints (no new data) -**Plans**: TBD -**UI hint**: yes - -## Progress - -**Execution Order:** -Phases execute in numeric order. Phase 2 unblocks Phases 3–7 (any order, parallelizable). Phase 8 follows Phase 7. - -| Phase | Plans Complete | Status | Completed | -|-------|----------------|--------|-----------| -| 1. PWA Scaffolding | 0/TBD | Not started | - | -| 2. Mobile Shell + More Drawer | 0/TBD | Not started | - | -| 3. Dashboard Restyle | 0/TBD | Not started | - | -| 4. Tickets Restyle | 0/TBD | Not started | - | -| 5. Finance Restyle | 0/TBD | Not started | - | -| 6. Analyzer Feed | 0/TBD | Not started | - | -| 7. Engagement Overview | 0/TBD | Not started | - | -| 8. Engagement User Profile | 0/TBD | Not started | - | - ---- -*Roadmap created: 2026-05-03* -*Source spec: `docs/superpowers/specs/2026-05-03-mobile-shell-design.md`*