native-update
Version:
Foundation package for building a comprehensive update system for Capacitor apps. Provides architecture and interfaces but requires backend implementation.
821 lines (710 loc) • 42.6 kB
Markdown
# Task 2: Dashboard UI/UX Plan
**Created:** 2025-12-27
**Status:** 📝 Planning
**Framework:** React 19 + RadixUI + Tailwind CSS
---
## 🎯 Objectives
Design and implement a complete user dashboard with:
- Clean, intuitive navigation
- Responsive layout (mobile-first)
- Consistent with marketing website theme
- All CRUD operations for apps and builds
- Real-time status updates
- Professional, modern design
---
## 🏗️ Dashboard Layout Structure
### Main Layout Component
```
┌─────────────────────────────────────────────────────────────┐
│ Header (DashboardHeader) │
│ Logo | Dashboard | [User Profile ▼] | Logout │
└─────────────────────────────────────────────────────────────┘
┌──────────────┬──────────────────────────────────────────────┐
│ │ │
│ Sidebar │ Main Content Area │
│ (DashboardSidebar) (Outlet) │
│ │ │
│ [Icon] Overview │
│ [Icon] Apps │
│ [Icon] Builds │
│ [Icon] Upload │
│ [Icon] Drive │
│ [Icon] Config │
│ [Icon] Settings │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
└──────────────┴──────────────────────────────────────────────┘
```
### Responsive Behavior
**Desktop (1024px+):**
- Sidebar always visible (250px width)
- Main content beside sidebar
- Header full width
**Tablet (640px - 1023px):**
- Collapsible sidebar (hamburger menu)
- Sidebar overlays content when open
- Full-width main content
**Mobile (<640px):**
- Bottom navigation bar instead of sidebar
- Full-width main content
- Header simplified (logo + hamburger)
---
## 📄 Page Designs
### Page 1: Overview (Dashboard Home)
**Route:** `/dashboard`
**File:** `src/pages/dashboard/OverviewPage.tsx`
**Purpose:** Quick snapshot of user's account and recent activity
**Layout:**
```
┌─────────────────────────────────────────────────────────────┐
│ Dashboard Overview [Date] │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ APPS │ │ BUILDS │ │ STORAGE │ │
│ │ 5 │ │ 23 │ │ 1.2 GB │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ │
│ Quick Actions │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ + New App │ │ ↑ Upload Build │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
│ Recent Builds [View All →] │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ App Name v1.0.1 Production 2 hours ago│ │
│ │ Another App v2.0.0 Staging 1 day ago │ │
│ │ Test App v0.9.0 Development 3 days ago │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Google Drive Status │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ ✅ Connected to: user@gmail.com │ │
│ │ Last sync: 5 minutes ago │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
**Components:**
- StatCard (reusable for apps/builds/storage count)
- QuickActionCard (buttons for common actions)
- RecentBuildsList (table of recent builds)
- DriveStatusCard (connection status)
**Data to Display:**
- Total apps count
- Total builds count
- Total storage used
- Recent 5 builds
- Drive connection status
- Quick action buttons
---
### Page 2: Apps Management
**Route:** `/dashboard/apps`
**File:** `src/pages/dashboard/AppsPage.tsx`
**Purpose:** View, create, edit, delete apps
**Layout:**
```
┌─────────────────────────────────────────────────────────────┐
│ Apps [+ New App] │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ [Icon] My Awesome App │ │
│ │ com.example.awesome │ │
│ │ Platforms: Android, iOS │ │
│ │ 5 builds • Production channel enabled │ │
│ │ [View Details] [Settings] [Delete] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ [Icon] Another App │ │
│ │ com.example.another │ │
│ │ Platforms: Web │ │
│ │ 12 builds • All channels enabled │ │
│ │ [View Details] [Settings] [Delete] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ [Empty State if no apps] │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 📱 │ │
│ │ No apps yet │ │
│ │ Create your first app to get started │ │
│ │ [+ Create App] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
**Modal: Create/Edit App**
```
┌─────────────────────────────────────┐
│ Create New App [×] │
├─────────────────────────────────────┤
│ │
│ App Name * │
│ ┌─────────────────────────────┐ │
│ │ My Awesome App │ │
│ └─────────────────────────────┘ │
│ │
│ Package ID * │
│ ┌─────────────────────────────┐ │
│ │ com.example.awesome │ │
│ └─────────────────────────────┘ │
│ │
│ Description │
│ ┌─────────────────────────────┐ │
│ │ A great mobile app │ │
│ └─────────────────────────────┘ │
│ │
│ Platforms * │
│ ☑ Android ☑ iOS ☐ Web │
│ │
│ App Icon (optional) │
│ [Upload Image] │
│ │
│ [Cancel] [Create App] │
│ │
└─────────────────────────────────────┘
```
---
### Page 3: App Details
**Route:** `/dashboard/apps/:appId`
**File:** `src/pages/dashboard/AppDetailsPage.tsx`
**Purpose:** View app details, builds, and configuration
**Layout:**
```
┌─────────────────────────────────────────────────────────────┐
│ ← Back to Apps │
├─────────────────────────────────────────────────────────────┤
│ │
│ [Icon] My Awesome App │
│ com.example.awesome │
│ Platforms: Android, iOS │
│ │
│ [Tabs: Builds | Channels | Settings] │
│ │
│ ────────── Builds Tab ────────── │
│ │
│ Production Builds [Upload Build →] │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ v1.0.1 • 15 MB • Android • 2 hours ago │ │
│ │ [Download] [Delete] │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ v1.0.0 • 14 MB • Android • 3 days ago │ │
│ │ [Download] [Delete] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Staging Builds │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ v1.1.0-beta • 16 MB • Android • 1 day ago │ │
│ │ [Download] [Delete] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ────────── Channels Tab ────────── │
│ │
│ Configure update channels for this app │
│ │
│ Production Channel │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ ☑ Enabled │ │
│ │ Update Strategy: Background │ │
│ │ ☑ Auto-update │ │
│ │ ☐ Require user consent │ │
│ │ Minimum version: 1.0.0 │ │
│ │ [Save Changes] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ [Similar cards for Staging and Development] │
│ │
│ ────────── Settings Tab ────────── │
│ │
│ App Information │
│ [Edit form similar to create modal] │
│ │
│ Danger Zone │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Delete App │ │
│ │ This will delete all builds and cannot be undone │ │
│ │ [Delete App] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
### Page 4: All Builds
**Route:** `/dashboard/builds`
**File:** `src/pages/dashboard/BuildsPage.tsx`
**Purpose:** View all builds across all apps
**Layout:**
```
┌─────────────────────────────────────────────────────────────┐
│ Builds [Upload Build] │
├─────────────────────────────────────────────────────────────┤
│ │
│ Filters: │
│ [All Apps ▼] [All Channels ▼] [All Platforms ▼] │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ App Version Channel Platform Uploaded │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ My App v1.0.1 Prod Android 2h ago │ │
│ │ Another v2.0.0 Staging iOS 1d ago │ │
│ │ Test App v0.9.0 Dev Web 3d ago │ │
│ │ My App v1.0.0 Prod Android 5d ago │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ [Load More] │
│ │
└─────────────────────────────────────────────────────────────┘
```
**Features:**
- Sortable columns
- Filterable by app, channel, platform
- Searchable
- Pagination (20 per page)
- Click row to view build details
---
### Page 5: Upload Build
**Route:** `/dashboard/upload`
**File:** `src/pages/dashboard/UploadPage.tsx`
**Purpose:** Upload new build to Google Drive
**Layout:**
```
┌─────────────────────────────────────────────────────────────┐
│ Upload New Build │
├─────────────────────────────────────────────────────────────┤
│ │
│ Step 1: Select App │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Select app ▼ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Step 2: Build Details │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Version * │ │
│ │ ┌─────────────────┐ │ │
│ │ │ 1.0.1 │ │ │
│ │ └─────────────────┘ │ │
│ │ │ │
│ │ Build Number * │ │
│ │ ┌─────────────────┐ │ │
│ │ │ 2 │ │ │
│ │ └─────────────────┘ │ │
│ │ │ │
│ │ Channel * │ │
│ │ ○ Production ○ Staging ○ Development │ │
│ │ │ │
│ │ Platform * │ │
│ │ ○ Android ○ iOS ○ Web │ │
│ │ │ │
│ │ Release Notes │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ - Bug fixes │ │ │
│ │ │ - Performance improvements │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Step 3: Upload File │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Drag & drop file here │ │
│ │ or │ │
│ │ [Browse Files] │ │
│ │ │ │
│ │ Accepted: .zip, .apk, .ipa │ │
│ │ Max size: 500 MB │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ [When uploading:] │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Uploading: app-v1.0.1.zip (15 MB) │ │
│ │ ████████████░░░░░░░░░ 65% │ │
│ │ Uploading to Google Drive... │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ [Cancel] [Upload Build] │
│ │
└─────────────────────────────────────────────────────────────┘
```
**Upload Flow:**
1. Select app from dropdown
2. Fill in version, build number, channel, platform
3. Add release notes (optional)
4. Drag & drop or browse for file
5. Validate file (size, type)
6. Upload to Firebase Storage (temp)
7. Call backend to upload to Google Drive
8. Show progress bar
9. Success message with link to view build
---
### Page 6: Google Drive
**Route:** `/dashboard/drive`
**File:** `src/pages/dashboard/GoogleDrivePage.tsx`
**Already designed in:** `TASK_2_GOOGLE_DRIVE_INTEGRATION.md`
---
### Page 7: Configuration
**Route:** `/dashboard/config`
**File:** `src/pages/dashboard/ConfigPage.tsx`
**Purpose:** Generate configuration for integrating plugin into user's app
**Layout:**
```
┌─────────────────────────────────────────────────────────────┐
│ Configuration │
├─────────────────────────────────────────────────────────────┤
│ │
│ Select App │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ My Awesome App ▼ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Plugin Configuration [Copy] [Download] │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ // capacitor.config.ts │ │
│ │ import { CapacitorConfig } from '@capacitor/cli'; │ │
│ │ │ │
│ │ const config: CapacitorConfig = { │ │
│ │ plugins: { │ │
│ │ NativeUpdate: { │ │
│ │ serverUrl: 'https://api.nativeupdate.com', │ │
│ │ userId: 'abc123xyz789', │ │
│ │ appId: 'app_abc123', │ │
│ │ autoCheck: true, │ │
│ │ channel: 'production' │ │
│ │ } │ │
│ │ } │ │
│ │ }; │ │
│ │ │ │
│ │ export default config; │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Integration Steps │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 1. Install the plugin: │ │
│ │ npm install native-update │ │
│ │ │ │
│ │ 2. Add configuration to capacitor.config.ts │ │
│ │ │ │
│ │ 3. Initialize in your app: │ │
│ │ import { NativeUpdate } from 'native-update'; │ │
│ │ await NativeUpdate.checkForUpdate(); │ │
│ │ │ │
│ │ 4. Build and test! │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ API Endpoints (for reference) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Check for updates: │ │
│ │ GET https://api.nativeupdate.com/updates/:appId │ │
│ │ │ │
│ │ Download build: │ │
│ │ GET https://api.nativeupdate.com/download/:buildId │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
**Features:**
- Select app from dropdown
- Auto-generate config based on app settings
- Syntax-highlighted code display
- One-click copy to clipboard
- Download as JSON file
- Step-by-step integration guide
- API endpoint reference
---
### Page 8: Settings
**Route:** `/dashboard/settings`
**File:** `src/pages/dashboard/SettingsPage.tsx`
**Purpose:** User profile and account settings
**Layout:**
```
┌─────────────────────────────────────────────────────────────┐
│ Settings │
├─────────────────────────────────────────────────────────────┤
│ │
│ [Tabs: Profile | Preferences | Account] │
│ │
│ ────────── Profile Tab ────────── │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ [Profile Photo] │ │
│ │ [Change Photo] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Display Name │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ John Doe │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Email │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ user@example.com │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ [Save Changes] │
│ │
│ ────────── Preferences Tab ────────── │
│ │
│ Notifications │
│ ☑ Email notifications │
│ ☑ Update notifications │
│ │
│ Appearance │
│ Theme: ○ Light ○ Dark ● Auto │
│ │
│ Language │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ English ▼ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ [Save Preferences] │
│ │
│ ────────── Account Tab ────────── │
│ │
│ Account Information │
│ Created: January 15, 2025 │
│ Plan: Free │
│ Storage used: 1.2 GB │
│ │
│ Danger Zone │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Delete Account │ │
│ │ This will permanently delete your account and all │ │
│ │ associated data. This action cannot be undone. │ │
│ │ [Delete My Account] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## 🧩 Reusable Components
### Component 1: DashboardLayout
**File:** `src/pages/dashboard/DashboardLayout.tsx`
```typescript
import { Outlet } from 'react-router-dom';
import { DashboardHeader } from '@/components/dashboard/DashboardHeader';
import { DashboardSidebar } from '@/components/dashboard/DashboardSidebar';
import { ProtectedRoute } from '@/components/auth/ProtectedRoute';
export default function DashboardLayout() {
return (
<ProtectedRoute requireEmailVerification>
<div className="min-h-screen bg-gray-50">
<DashboardHeader />
<div className="flex">
<DashboardSidebar />
<main className="flex-1 p-6 lg:p-8">
<Outlet />
</main>
</div>
</div>
</ProtectedRoute>
);
}
```
### Component 2: DashboardHeader
**File:** `src/components/dashboard/DashboardHeader.tsx`
**Features:**
- Logo (links to marketing site)
- "Dashboard" title
- User profile dropdown
- Logout button
### Component 3: DashboardSidebar
**File:** `src/components/dashboard/DashboardSidebar.tsx`
**Features:**
- Navigation links with icons
- Active state highlighting
- Collapse on mobile
- Responsive hamburger menu
**Navigation Items:**
```typescript
const navItems = [
{ label: 'Overview', path: '/dashboard', icon: HomeIcon },
{ label: 'Apps', path: '/dashboard/apps', icon: RocketIcon },
{ label: 'Builds', path: '/dashboard/builds', icon: ArchiveIcon },
{ label: 'Upload', path: '/dashboard/upload', icon: UploadIcon },
{ label: 'Google Drive', path: '/dashboard/drive', icon: CloudIcon },
{ label: 'Configuration', path: '/dashboard/config', icon: CodeIcon },
{ label: 'Settings', path: '/dashboard/settings', icon: GearIcon },
];
```
### Component 4: StatCard
**File:** `src/components/dashboard/StatCard.tsx`
**Props:**
```typescript
interface StatCardProps {
icon: React.ComponentType;
label: string;
value: number | string;
iconColor?: string;
}
```
**Usage:**
```tsx
<StatCard icon={RocketIcon} label="Apps" value={5} iconColor="text-brand-600" />
```
### Component 5: BuildCard
**File:** `src/components/dashboard/BuildCard.tsx`
**Props:**
```typescript
interface BuildCardProps {
build: {
id: string;
appName: string;
version: string;
channel: string;
platform: string;
uploadedAt: Date;
fileSize: number;
};
onDownload?: () => void;
onDelete?: () => void;
}
```
### Component 6: AppCard
**File:** `src/components/dashboard/AppCard.tsx`
**Props:**
```typescript
interface AppCardProps {
app: {
id: string;
name: string;
packageId: string;
icon: string | null;
platforms: string[];
totalBuilds: number;
};
onView?: () => void;
onEdit?: () => void;
onDelete?: () => void;
}
```
### Component 7: FileUpload
**File:** `src/components/dashboard/FileUpload.tsx`
**Features:**
- Drag & drop zone
- File browser
- File validation (type, size)
- Upload progress
- File preview (name, size)
### Component 8: ConfigDisplay
**File:** `src/components/dashboard/ConfigDisplay.tsx`
**Features:**
- Syntax-highlighted code (using react-syntax-highlighter)
- Copy to clipboard button
- Download as file button
- Language selection (JSON, TypeScript)
### Component 9: EmptyState
**File:** `src/components/dashboard/EmptyState.tsx`
**Props:**
```typescript
interface EmptyStateProps {
icon: React.ComponentType;
title: string;
description: string;
actionLabel?: string;
onAction?: () => void;
}
```
**Usage:**
```tsx
<EmptyState
icon={RocketIcon}
title="No apps yet"
description="Create your first app to get started"
actionLabel="Create App"
onAction={handleCreateApp}
/>
```
---
## 🎨 Design System Consistency
### Colors (from marketing website)
```css
--brand-600: #0284c7; /* Cyan-blue */
--accent-600: #c026d3; /* Purple-magenta */
--gray-50: #f9fafb;
--gray-100: #f3f4f6;
--gray-600: #4b5563;
--gray-900: #111827;
```
### Typography
- **Headings:** Plus Jakarta Sans (from marketing site)
- **Body:** Inter
- **Code:** JetBrains Mono
### Component Styling
- Use existing Button, Card, Container components
- Match border radius (8px)
- Match shadows and hover effects
- Consistent spacing (4px grid)
---
## 📱 Responsive Design
### Breakpoints
```typescript
const breakpoints = {
sm: '640px', // Tablet
md: '768px', // Small laptop
lg: '1024px', // Desktop
xl: '1280px', // Large desktop
};
```
### Mobile Adaptations
- Stack cards vertically
- Full-width buttons
- Hamburger menu for sidebar
- Bottom navigation bar
- Simplified header
- Touch-friendly tap targets (min 44x44px)
---
## ✅ Implementation Checklist
### Layout Components
- [ ] Create DashboardLayout
- [ ] Create DashboardHeader
- [ ] Create DashboardSidebar
- [ ] Add responsive navigation
- [ ] Add mobile hamburger menu
### Page Components
- [ ] Build OverviewPage
- [ ] Build AppsPage
- [ ] Build AppDetailsPage
- [ ] Build BuildsPage
- [ ] Build UploadPage
- [ ] Build GoogleDrivePage (already planned)
- [ ] Build ConfigPage
- [ ] Build SettingsPage
### Reusable Components
- [ ] Create StatCard
- [ ] Create BuildCard
- [ ] Create AppCard
- [ ] Create FileUpload
- [ ] Create ConfigDisplay
- [ ] Create EmptyState
- [ ] Create LoadingSpinner
- [ ] Create ConfirmDialog
### Modals & Dialogs
- [ ] Create App modal
- [ ] Edit App modal
- [ ] Delete confirmation dialog
- [ ] Upload progress modal
### Navigation
- [ ] Setup React Router routes
- [ ] Add active state styling
- [ ] Test navigation flow
- [ ] Add breadcrumbs (optional)
### Responsive Testing
- [ ] Test on mobile (320px-640px)
- [ ] Test on tablet (640px-1024px)
- [ ] Test on desktop (1024px+)
- [ ] Test touch interactions
- [ ] Test keyboard navigation
### Styling
- [ ] Match marketing site theme
- [ ] Use consistent colors
- [ ] Use consistent typography
- [ ] Add hover effects
- [ ] Add loading states
- [ ] Add error states
---
**Plan Status:** ✅ Complete and ready for implementation
**Total Pages:** 8 dashboard pages
**Total Components:** 15+ reusable components
**Estimated Time:** 20-30 hours