diff --git a/docs/superpowers/plans/2026-04-15-mobile-stat-cards-implementation.md b/docs/superpowers/plans/2026-04-15-mobile-stat-cards-implementation.md new file mode 100644 index 00000000..c1e3934c --- /dev/null +++ b/docs/superpowers/plans/2026-04-15-mobile-stat-cards-implementation.md @@ -0,0 +1,502 @@ +# Mobile Stat Cards Responsive Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Implement two-column flexbox layout for stat cards across Inventory, Logs, and Admin pages to fix content overflow on mobile iPhone screens. + +**Architecture:** Create a reusable `StatCard` component with responsive Tailwind classes (`flex justify-between`, responsive font sizing, label truncation). Replace inline stat displays on three pages with this component. + +**Tech Stack:** React, Next.js 15, Tailwind CSS, Lucide Icons + +--- + +## File Structure + +**Files to Create:** +- `frontend/components/StatCard.tsx` — Reusable stat card component + +**Files to Modify:** +- `frontend/app/inventory/page.tsx` — Replace stat displays with StatCard component +- `frontend/app/logs/page.tsx` — Replace stat displays with StatCard component +- `frontend/app/admin/page.tsx` — Replace stat displays with StatCard component + +--- + +## Task 1: Create Reusable StatCard Component + +**Files:** +- Create: `frontend/components/StatCard.tsx` + +- [ ] **Step 1: Create the StatCard component file** + +Create `frontend/components/StatCard.tsx`: + +```tsx +import React from 'react'; +import { LucideIcon } from 'lucide-react'; + +interface StatCardProps { + label: string; + value: number; + icon?: LucideIcon; +} + +export default function StatCard({ label, value, icon: Icon }: StatCardProps) { + return ( +
+ {/* Icon + Label Container */} +
+ {Icon && } + + {label} + +
+ + {/* Number (Right) */} + + {value} + +
+ ); +} +``` + +**Key Implementation Details:** +- `flex justify-between items-center` — Label left, number right, vertically centered +- `gap-2` — 8px spacing between label and number +- `p-4` — 16px padding on mobile +- `bg-slate-900 rounded-lg` — Dark background, rounded corners +- `min-w-0` — Allows label container to shrink (enables truncate) +- `text-sm md:text-base` — Label: 14px mobile, 16px desktop+ +- `truncate` — Label ellipsis if too long +- `text-lg md:text-xl` — Number: 18px mobile, 20px desktop+ +- `whitespace-nowrap` — Number never wraps +- `flex-shrink-0` on icon — Icon doesn't shrink + +- [ ] **Step 2: Commit the component** + +```bash +git add frontend/components/StatCard.tsx +git commit -m "feat: create reusable StatCard component with responsive layout + +- Two-column flexbox layout (label left, number right) +- Responsive font sizing (sm/md breakpoints) +- Label truncation for overflow handling +- Optional icon support via Lucide +- Ready for use across Inventory, Logs, Admin pages" +``` + +--- + +## Task 2: Update Inventory Page Stat Cards + +**Files:** +- Modify: `frontend/app/inventory/page.tsx` + +- [ ] **Step 1: Read the current inventory page to find stat card implementations** + +Look for sections displaying: +- "Categories" with count +- "Item Types" with count +- "Total Boxes" with count + +Expected current pattern (inline flex layout): +```tsx +
+ +
+

Categories

+

{categoriesCount}

+
+
+``` + +- [ ] **Step 2: Import StatCard component at top of file** + +Add to imports: +```tsx +import StatCard from '@/components/StatCard'; +``` + +(Adjust import path based on actual file location) + +- [ ] **Step 3: Replace Categories stat display with StatCard** + +Find the Categories display section and replace with: + +```tsx + +``` + +Ensure `Layers` icon is imported from lucide-react (should already be if used previously). + +- [ ] **Step 4: Replace Item Types stat display with StatCard** + +Find the Item Types display section and replace with: + +```tsx + +``` + +Ensure `Package` icon is imported from lucide-react (standard Lucide icon for item types). + +- [ ] **Step 5: Replace Total Boxes stat display with StatCard** + +Find the Total Boxes display section and replace with: + +```tsx + +``` + +Ensure `Box` icon is imported from lucide-react. + +- [ ] **Step 6: Verify all three stat cards are now using StatCard component** + +Check that the Inventory page displays three stat cards in a consistent layout. + +- [ ] **Step 7: Commit the changes** + +```bash +git add frontend/app/inventory/page.tsx +git commit -m "fix: refactor Inventory page stat cards to use StatCard component + +- Replace Categories, Item Types, Total Boxes with StatCard +- Fixes mobile content overflow with two-column flexbox layout +- Responsive font sizing for mobile/desktop +- Label truncation for long text" +``` + +--- + +## Task 3: Update Logs Page Stat Cards + +**Files:** +- Modify: `frontend/app/logs/page.tsx` + +- [ ] **Step 1: Read the current logs page to find stat card implementations** + +Look for "Total Events" or similar stat display with a count. + +- [ ] **Step 2: Import StatCard component** + +Add to imports: +```tsx +import StatCard from '@/components/StatCard'; +``` + +- [ ] **Step 3: Replace Total Events stat display with StatCard** + +Find the Total Events display section and replace with: + +```tsx + +``` + +Ensure `LogSquare` icon is imported from lucide-react (or use `FileText`, `ListChecks`, or other appropriate icon if LogSquare doesn't exist). + +- [ ] **Step 4: Verify the stat card displays correctly** + +Check that the Logs page displays the Total Events stat in the new layout. + +- [ ] **Step 5: Commit the changes** + +```bash +git add frontend/app/logs/page.tsx +git commit -m "fix: refactor Logs page stat cards to use StatCard component + +- Replace Total Events display with StatCard +- Fixes mobile content overflow with responsive layout +- Consistent styling with Inventory page" +``` + +--- + +## Task 4: Update Admin Page Stat Cards + +**Files:** +- Modify: `frontend/app/admin/page.tsx` + +- [ ] **Step 1: Read the current admin page to find stat card implementations** + +Look for any label + number stat displays (e.g., "Users", "Sessions", "Audit Logs", etc.). + +- [ ] **Step 2: Import StatCard component** + +Add to imports: +```tsx +import StatCard from '@/components/StatCard'; +``` + +- [ ] **Step 3: Replace all stat displays with StatCard** + +For each stat display on the Admin page, replace with: + +```tsx + +``` + +Example (if there's a "Users" stat): +```tsx + +``` + +Map appropriate Lucide icons to each stat: +- Users → `Users` +- Sessions → `Zap` or `Activity` +- Audit Logs → `LogSquare` or `FileText` +- Admins → `Shield` +- Active Sessions → `Activity` + +- [ ] **Step 4: Verify all admin stat cards are updated** + +Check that the Admin page displays all stats with consistent StatCard styling. + +- [ ] **Step 5: Commit the changes** + +```bash +git add frontend/app/admin/page.tsx +git commit -m "fix: refactor Admin page stat cards to use StatCard component + +- Replace all stat displays with StatCard +- Fixes mobile content overflow with responsive layout +- Consistent styling across all admin stats" +``` + +--- + +## Task 5: Test on Mobile Viewport + +**Files:** +- Test: All three pages (Inventory, Logs, Admin) + +- [ ] **Step 1: Start the development server** + +```bash +./start_server.sh +``` + +Expected: Frontend runs on `http://localhost:8907` + +- [ ] **Step 2: Open browser DevTools and set mobile viewport** + +1. Open DevTools (F12 or Cmd+Shift+I) +2. Toggle Device Toolbar (Cmd+Shift+M or Ctrl+Shift+M) +3. Set to iPhone SE (375px) or iPhone 12 (390px) + +- [ ] **Step 3: Test Inventory page on mobile** + +Navigate to Inventory page. +Verify: +- ✓ "Categories 2" — Label on left, number on right, no overflow +- ✓ "Item Types 6" — Label on left, number on right, no overflow +- ✓ "Total Boxes 2" — Label on left, number on right, no overflow +- ✓ All text is visible (not cut off) +- ✓ Cards are properly padded + +- [ ] **Step 4: Test Logs page on mobile** + +Navigate to Logs page. +Verify: +- ✓ "Total Events [number]" — Label and number both visible, no overflow +- ✓ Text formatting is correct + +- [ ] **Step 5: Test Admin page on mobile** + +Navigate to Admin page. +Verify: +- ✓ All stat cards display correctly without overflow +- ✓ Labels and numbers are properly aligned + +- [ ] **Step 6: Test on different mobile widths** + +Resize browser to test at: +- 320px (iPhone SE smallest) +- 375px (iPhone SE) +- 390px (iPhone 12) +- 430px (iPhone 14 Pro Max) + +Verify no overflow occurs and layout remains stable. + +- [ ] **Step 7: Test on tablet and desktop** + +Resize to: +- 768px (tablet) — verify `md:` breakpoint applies +- 1024px (desktop) — verify `lg:` breakpoint applies + +- [ ] **Step 8: Test with long labels** + +(If possible, temporarily update a label to test truncation) +Example: `` + +Verify: Label shows ellipsis ("Total Events in System...") and doesn't overflow. + +- [ ] **Step 9: No test failures** + +Run any existing tests to ensure no regressions: + +```bash +npm run test +``` + +Expected: All tests pass (or maintain same pass rate as before) + +- [ ] **Step 10: Commit test verification notes (optional)** + +```bash +git add . +git commit -m "test: verify stat card responsive layout on mobile viewports + +- iPhone SE (375px): No overflow ✓ +- iPhone 12 (390px): No overflow ✓ +- iPhone 14 Pro Max (430px): No overflow ✓ +- Tablet (768px): Desktop styling ✓ +- Desktop (1024px): Large text ✓ +- Long label truncation: Ellipsis works ✓" +``` + +--- + +## Task 6: Final Verification & Documentation Update + +**Files:** +- Review: All modified pages +- Update: `dev_docs/SESSION_STATE.md` (handover) + +- [ ] **Step 1: Verify all commits are in place** + +```bash +git log --oneline -6 +``` + +Expected output includes: +- `feat: create reusable StatCard component...` +- `fix: refactor Inventory page stat cards...` +- `fix: refactor Logs page stat cards...` +- `fix: refactor Admin page stat cards...` +- (optional) `test: verify stat card responsive layout...` + +- [ ] **Step 2: Check for any remaining inline stat displays** + +Search the codebase for any remaining old-style stat displays: + +```bash +grep -r "text-xs text-slate-500" frontend/app --include="*.tsx" | grep -i "categor\|item\|box\|event\|user\|session" +``` + +If found, replace with StatCard component. + +- [ ] **Step 3: Update SESSION_STATE.md handover** + +Add to `dev_docs/SESSION_STATE.md`: + +```markdown +### Mobile Stat Cards Responsive Fix (Completed) + +**Issue:** Stat card content overflowed outside card boundaries on iPhone mobile screens (< 640px). + +**Solution:** Created reusable `StatCard` component with two-column flexbox layout: +- Label (left, flexible, truncates if long) +- Number (right, fixed, never wraps) +- Responsive font sizes: `text-sm md:text-base` (label), `text-lg md:text-xl` (number) + +**Pages Fixed:** +- ✓ Inventory page (Categories, Item Types, Total Boxes) +- ✓ Logs page (Total Events) +- ✓ Admin page (all stat displays) + +**Verification:** +- ✓ iPhone SE (375px): No overflow +- ✓ iPhone 12 (390px): No overflow +- ✓ Tablet/Desktop: Responsive scaling works +- ✓ Long labels: Truncate with ellipsis +- ✓ All tests pass + +**Files Changed:** +- Created: `frontend/components/StatCard.tsx` +- Modified: `frontend/app/inventory/page.tsx` +- Modified: `frontend/app/logs/page.tsx` +- Modified: `frontend/app/admin/page.tsx` + +**Next Steps:** Deploy to remote server and verify on real iPhone device if possible. +``` + +- [ ] **Step 4: Commit the handover update** + +```bash +git add dev_docs/SESSION_STATE.md +git commit -m "docs: update session state - mobile stat cards responsive fix complete + +- StatCard component created and integrated +- All three pages (Inventory, Logs, Admin) updated +- Mobile testing verified (375px-430px widths) +- Responsive breakpoints working correctly" +``` + +- [ ] **Step 5: Verify no uncommitted changes** + +```bash +git status +``` + +Expected: `working tree clean` + +- [ ] **Step 6: Review the spec coverage one final time** + +Check `docs/superpowers/specs/2026-04-15-mobile-stat-cards-responsive-design.md`: + +**Spec Requirements vs. Implementation:** +- ✓ Two-column flexbox layout implemented +- ✓ Label left, number right implemented +- ✓ Responsive font sizing (sm/md/lg) implemented +- ✓ Label truncation for long text implemented +- ✓ Inventory page stat cards fixed +- ✓ Logs page stat cards fixed +- ✓ Admin page stat cards fixed +- ✓ Mobile testing completed +- ✓ No regressions on desktop/tablet + +All spec requirements are covered. + +--- + +## Summary + +**6 Tasks, ~45-60 minutes total:** +1. Create StatCard component (5 min) +2. Update Inventory page (10 min) +3. Update Logs page (10 min) +4. Update Admin page (10 min) +5. Test on mobile (15 min) +6. Final verification & docs (5 min) + +**Commits Created:** 5-6 commits with clear, descriptive messages + +**Testing:** Manual mobile viewport testing across iPhone SE, 12, 14 Pro Max widths + +**Outcome:** All stat cards on Inventory, Logs, and Admin pages now display with responsive two-column layout. No content overflow on mobile. Consistent styling across all pages. + +---