Adolfo Delorenzo
5c30651754
- Add 08-01-SUMMARY.md: responsive tab bar + PWA infra with K monogram icons - Update STATE.md: phase 8 plan 1 progress, decisions, metrics - Update ROADMAP.md: phase 8 in progress (1/4 SUMMARY files) - Mark requirements MOB-01, MOB-02, MOB-04 complete - Update portal submodule pointer to acba978 (mobile nav + PWA commits) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
183 lines
8.5 KiB
Markdown
183 lines
8.5 KiB
Markdown
---
|
|
phase: 08-mobile-pwa
|
|
plan: 01
|
|
subsystem: ui
|
|
tags: [pwa, service-worker, serwist, next.js, tailwind, mobile, responsive]
|
|
|
|
# Dependency graph
|
|
requires:
|
|
- phase: 07-multilanguage
|
|
provides: next-intl i18n framework used for offline banner and mobile nav labels
|
|
- phase: 04-rbac
|
|
provides: RBAC role system used to filter More sheet items by user role
|
|
|
|
provides:
|
|
- PWA manifest at /manifest.webmanifest with K monogram icons
|
|
- Serwist service worker with precaching and runtime cache (app/sw.ts)
|
|
- Service worker registration component (components/sw-register.tsx)
|
|
- Offline detection hook (lib/use-offline.ts) and banner (components/offline-banner.tsx)
|
|
- Mobile bottom tab bar (components/mobile-nav.tsx) — 5 tabs, md:hidden
|
|
- Mobile More sheet (components/mobile-more-sheet.tsx) — RBAC-filtered secondary nav + LanguageSwitcher
|
|
- Responsive dashboard layout: sidebar hidden on mobile, tab bar shown, safe-area padding
|
|
|
|
affects:
|
|
- 08-02 through 08-04 (push notifications, offline cache, deep linking all build on this PWA foundation)
|
|
|
|
# Tech tracking
|
|
tech-stack:
|
|
added:
|
|
- "@serwist/next ^9.5.7"
|
|
- "serwist ^9.5.7"
|
|
- "idb (IndexedDB utilities, used in plan 03)"
|
|
- "sharp (devDep, icon generation script)"
|
|
patterns:
|
|
- "withNextIntl(withSerwist(nextConfig)) compose order in next.config.ts"
|
|
- "Viewport export with viewportFit: cover for iOS safe-area CSS env vars"
|
|
- "md:hidden for mobile-only components, hidden md:flex for desktop-only"
|
|
- "env(safe-area-inset-bottom) via inline style for iOS home indicator"
|
|
- "RBAC filtering in mobile UI mirrors desktop Nav.tsx pattern"
|
|
|
|
key-files:
|
|
created:
|
|
- packages/portal/app/manifest.ts
|
|
- packages/portal/app/sw.ts
|
|
- packages/portal/components/sw-register.tsx
|
|
- packages/portal/components/offline-banner.tsx
|
|
- packages/portal/lib/use-offline.ts
|
|
- packages/portal/components/mobile-nav.tsx
|
|
- packages/portal/components/mobile-more-sheet.tsx
|
|
- packages/portal/public/icon-192.png
|
|
- packages/portal/public/icon-512.png
|
|
- packages/portal/public/icon-maskable-192.png
|
|
- packages/portal/public/apple-touch-icon.png
|
|
- packages/portal/public/badge-72.png
|
|
- packages/portal/scripts/generate-icons.mjs
|
|
modified:
|
|
- packages/portal/next.config.ts
|
|
- packages/portal/app/layout.tsx
|
|
- packages/portal/app/(dashboard)/layout.tsx
|
|
- packages/portal/messages/en.json
|
|
- packages/portal/messages/es.json
|
|
- packages/portal/messages/pt.json
|
|
|
|
key-decisions:
|
|
- "Serwist service worker disabled in development (NODE_ENV !== production) — avoids stale cache headaches during dev"
|
|
- "ServiceWorkerRegistration placed outside NextIntlClientProvider — needs no translations, mounts immediately"
|
|
- "OfflineBanner placed inside NextIntlClientProvider — requires translations for offline message"
|
|
- "Mobile More sheet uses plain div + backdrop (not @base-ui/react Drawer) — simpler, zero dependency, fully functional"
|
|
- "Serwist class API (new Serwist + addEventListeners) used over deprecated installSerwist — linter enforced this"
|
|
- "Viewport exported from layout.tsx (not metadata) — Next.js 16 separates viewport from metadata"
|
|
- "K monogram icons generated via sharp from SVG with radial gradient glow — consistent with sidebar brand mark aesthetic"
|
|
- "nav.settings and nav.language keys added to en/es/pt — reused nav namespace to avoid duplication"
|
|
|
|
patterns-established:
|
|
- "All mobile-only UI uses md:hidden; all desktop-only uses hidden md:flex"
|
|
- "Bottom safe-area handled via env(safe-area-inset-bottom) as inline style (Tailwind cannot use CSS env() directly)"
|
|
- "PWA icons generated from script (scripts/generate-icons.mjs), not checked in from external tool"
|
|
|
|
requirements-completed:
|
|
- MOB-01
|
|
- MOB-02
|
|
- MOB-04
|
|
|
|
# Metrics
|
|
duration: 7min
|
|
completed: 2026-03-26
|
|
---
|
|
|
|
# Phase 8 Plan 1: Mobile PWA Foundation Summary
|
|
|
|
**Responsive bottom tab bar + PWA manifest/service worker with K monogram icons, offline detection banner, and iOS safe-area support**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** ~7 min
|
|
- **Started:** 2026-03-26T03:12:35Z
|
|
- **Completed:** 2026-03-26T03:19:34Z
|
|
- **Tasks:** 2
|
|
- **Files modified:** 19
|
|
|
|
## Accomplishments
|
|
|
|
- Bottom tab bar (Dashboard, Employees, Chat, Usage, More) renders on mobile; desktop sidebar unchanged
|
|
- More sheet with RBAC-filtered secondary nav (Billing, API Keys, Users, Platform, Settings) + LanguageSwitcher + Sign Out
|
|
- PWA manifest at `/manifest.webmanifest` with K monogram brand icons (192, 512, maskable, apple-touch-icon, badge-72)
|
|
- Serwist service worker for precaching and runtime cache; registered via client component in root layout
|
|
- Offline banner (amber, fixed top) appears automatically when `navigator.onLine` is false
|
|
- Viewport `viewportFit: cover` enables CSS `env(safe-area-inset-bottom)` for iOS home indicator clearance
|
|
- Build passes; no TypeScript errors
|
|
|
|
## Task Commits
|
|
|
|
Each task was committed atomically:
|
|
|
|
1. **Task 1: PWA infrastructure** - `53e66ff` (feat)
|
|
2. **Task 2: Mobile nav + responsive layout** - `acba978` (feat)
|
|
|
|
**Plan metadata:** (included in final docs commit)
|
|
|
|
## Files Created/Modified
|
|
|
|
- `app/manifest.ts` - PWA manifest with K monogram icons, start_url=/dashboard
|
|
- `app/sw.ts` - Serwist service worker (precache + runtime cache, Serwist class API)
|
|
- `components/sw-register.tsx` - Client component registering /sw.js on mount
|
|
- `components/offline-banner.tsx` - Fixed amber banner when offline, uses useOnlineStatus
|
|
- `lib/use-offline.ts` - useOnlineStatus hook via online/offline window events
|
|
- `components/mobile-nav.tsx` - Bottom tab bar: 5 tabs, md:hidden, active indicator dot
|
|
- `components/mobile-more-sheet.tsx` - Bottom sheet: RBAC items + LanguageSwitcher + Sign Out
|
|
- `scripts/generate-icons.mjs` - Sharp-based icon generation script
|
|
- `next.config.ts` - withNextIntl(withSerwist(nextConfig)) composition
|
|
- `app/layout.tsx` - Viewport export added, ServiceWorkerRegistration + OfflineBanner mounted
|
|
- `app/(dashboard)/layout.tsx` - Desktop sidebar wrapped in hidden md:flex; MobileNav added; pb-20 md:pb-8
|
|
|
|
## Decisions Made
|
|
|
|
- Serwist service worker disabled in development (`NODE_ENV === 'development'`) to avoid stale cache headaches
|
|
- Mobile More sheet implemented as plain div + backdrop overlay — simpler than @base-ui/react Drawer, zero additional complexity
|
|
- Serwist class API (new Serwist + addEventListeners) used over deprecated installSerwist — enforced by linter auto-correction
|
|
- Viewport exported separately from metadata (Next.js 16 requirement)
|
|
- K monogram icons generated by Node.js script using sharp/SVG rather than checked-in from external tool
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 1 - Bug] Serwist API: installSerwist replaced with Serwist class**
|
|
- **Found during:** Task 1 (app/sw.ts)
|
|
- **Issue:** Plan specified `installSerwist()` but linter auto-corrected to the current Serwist class API (`new Serwist(...) + addEventListeners()`) — `installSerwist` is deprecated in serwist 9.x
|
|
- **Fix:** Accepted linter correction — `new Serwist({ ... }); serwist.addEventListeners();`
|
|
- **Files modified:** `app/sw.ts`
|
|
- **Verification:** Build passes with corrected API
|
|
- **Committed in:** `53e66ff`
|
|
|
|
**2. [Rule 2 - Missing Critical] Added nav.settings + nav.language i18n keys**
|
|
- **Found during:** Task 2 (mobile-more-sheet.tsx)
|
|
- **Issue:** Settings link and Language label in More sheet required i18n keys not present in nav namespace
|
|
- **Fix:** Added `settings` and `language` keys to nav namespace in en/es/pt locale files
|
|
- **Files modified:** `messages/en.json`, `messages/es.json`, `messages/pt.json`
|
|
- **Verification:** Build passes with no missing translation errors
|
|
- **Committed in:** `acba978`
|
|
|
|
---
|
|
|
|
**Total deviations:** 2 auto-fixed (1 API update, 1 missing i18n keys)
|
|
**Impact on plan:** Both auto-fixes essential for correctness. No scope creep.
|
|
|
|
## Issues Encountered
|
|
|
|
- Previous session's commit (`acba978`) had already included mobile-nav.tsx and mobile-more-sheet.tsx stubs — these were incorporated and enhanced with LanguageSwitcher, Settings item, and RBAC filtering rather than replaced.
|
|
|
|
## Self-Check: PASSED
|
|
|
|
All files verified present. All commits verified in git history.
|
|
|
|
## Next Phase Readiness
|
|
|
|
- PWA foundation is complete; plan 08-02 (push notifications) can extend sw.ts with push event listeners
|
|
- Offline cache and background sync (plan 08-03) can use the precaching infrastructure already in place
|
|
- iOS safe-area CSS env vars are active; any new mobile components should use `env(safe-area-inset-bottom)` for bottom spacing
|
|
|
|
---
|
|
*Phase: 08-mobile-pwa*
|
|
*Completed: 2026-03-26*
|