# Dashboard Recreation Plan: Next.js 14 + shadcn/ui

## Overview
Recreate the main dashboard page from https://shadcnblocks-admin.vercel.app/ using Next.js 14 App Router, shadcn/ui components, TypeScript, Chart.js, Inter font, and dark/light theme support with mock data.

## Project Status
- **Current State**: Empty directory (only readme.md exists)
- **Target**: Full-featured dashboard with sidebar navigation, metrics, charts, and data tables

---

## Implementation Phases

### Phase 1: Project Foundation (30 min)

#### 1. Initialize Next.js 14 Project
```bash
cd /e/repos/claude/shadcn-dashboard
npx create-next-app@latest . --typescript --tailwind --app --no-src-dir --import-alias "@/*"
```
Choose: TypeScript ✓, ESLint ✓, Tailwind CSS ✓, App Router ✓, No src/ directory

#### 2. Initialize shadcn/ui
```bash
npx shadcn@latest init
```
Choose: Default style, Slate base color, CSS variables ✓

#### 3. Install Dependencies
```bash
npm install chart.js react-chartjs-2 next-themes lucide-react date-fns
npm install -D @types/node
```

#### 4. Install shadcn/ui Components
```bash
npx shadcn@latest add button card table dropdown-menu tabs avatar badge separator input sidebar command dialog
```

---

### Phase 2: Theme & Layout Foundation (45 min)

#### 5. Create Theme Provider
**File**: [components/theme-provider.tsx](components/theme-provider.tsx)
- Wrap next-themes provider
- Export ThemeProvider component

#### 6. Configure Root Layout
**File**: [app/layout.tsx](app/layout.tsx)
- Import Inter font from next/font/google
- Wrap with ThemeProvider (attribute="class", defaultTheme="system")
- Wrap with SidebarProvider
- Add suppressHydrationWarning to html tag

#### 7. Create Theme Toggle Component
**File**: [components/layout/theme-toggle.tsx](components/layout/theme-toggle.tsx)
- Use useTheme() hook
- Dropdown menu: Light, Dark, System options
- Sun/Moon icons from lucide-react

#### 8. Build Sidebar Navigation
**File**: [components/layout/app-sidebar.tsx](components/layout/app-sidebar.tsx)
- Use shadcn/ui Sidebar components
- Navigation structure:
  - **General**: Dashboard (3 sub-items), Tasks, Users
  - **Pages**: Auth, Errors
  - **Other**: Settings, Developers
- Icons from lucide-react
- User profile section in footer

**File**: [components/layout/user-nav.tsx](components/layout/user-nav.tsx)
- Avatar with dropdown menu
- Options: Profile, Settings, Sign out

#### 9. Create Header Component
**File**: [components/layout/header.tsx](components/layout/header.tsx)
- Left: SidebarTrigger button
- Center: Command palette button (⌘K)
- Right: ThemeToggle component
- Sticky positioning with backdrop blur

---

### Phase 3: Data Layer (20 min)

#### 10. Define TypeScript Interfaces
**File**: [types/dashboard.ts](types/dashboard.ts)
```typescript
interface MetricCard {
  id: string;
  title: string;
  value: string | number;
  change: number;
  changeLabel: string;
}

interface Payment {
  id: string;
  status: 'success' | 'processing' | 'failed';
  email: string;
  amount: number;
}

interface TeamMember {
  id: string;
  name: string;
  email: string;
  role: string;
  avatar: string;
}

interface ChartDataPoint {
  label: string;
  value: number;
  secondaryValue?: number;
}

interface DashboardData {
  metrics: MetricCard[];
  revenueData: ChartDataPoint[];
  salesData: ChartDataPoint[];
  payments: Payment[];
  team: TeamMember[];
}
```

#### 11. Create Mock Data
**File**: [lib/mock-data.ts](lib/mock-data.ts)

Generate realistic data:
- **Metrics** (4 cards):
  - New Subscriptions: 4,682 (+15.54%)
  - New Orders: 1,226 (+40.2%)
  - Avg Order Revenue: 1,080 (+10.8%)
  - Total Revenue: $15,231.89 (+20.1%)

- **Revenue Chart**: 6 months of trend data
- **Sales Chart**: 12 months of bar data
- **Payments Table**: 12-15 transaction entries
- **Team Table**: 6-8 member entries

Export `getDashboardData()` function

---

### Phase 4: Chart Components (45 min)

#### 12. Configure Chart.js
**File**: [lib/chart-config.ts](lib/chart-config.ts)
- Register Chart.js components (CategoryScale, LinearScale, PointElement, LineElement, BarElement, Tooltip, Legend)
- Define default options
- Export `getChartColors(theme)` for theme-aware styling

#### 13. Create Line Chart Component
**File**: [components/charts/line-chart.tsx](components/charts/line-chart.tsx)
- Mark as "use client"
- Use dynamic import with `{ ssr: false }`
- Accept props: data, options, height
- Apply theme-aware colors using useTheme()

#### 14. Create Bar Chart Component
**File**: [components/charts/bar-chart.tsx](components/charts/bar-chart.tsx)
- Similar to LineChart but using Bar from react-chartjs-2
- "use client" directive
- Theme-aware colors

---

### Phase 5: Dashboard Components (90 min)

#### 15. Create Metric Card
**File**: [components/dashboard/metric-card.tsx](components/dashboard/metric-card.tsx)
- Use Card component
- Display: title, value, change percentage (colored), change label
- Add TrendingUp/TrendingDown icon based on change

#### 16. Build Revenue Chart Component
**File**: [components/dashboard/revenue-chart.tsx](components/dashboard/revenue-chart.tsx)
- Use LineChart component
- Dual-line display (Revenue + Subscriptions)
- Wrap in Card with title

#### 17. Build Sales Activity Chart
**File**: [components/dashboard/sales-chart.tsx](components/dashboard/sales-chart.tsx)
- Use BarChart component
- 12-month bar display
- Wrap in Card with title

#### 18. Create Payments Table
**File**: [components/dashboard/payments-table.tsx](components/dashboard/payments-table.tsx)
- Use Table components
- Columns: Status (Badge), Email, Amount (formatted), Actions (DropdownMenu)
- Color-coded status badges (green/yellow/red)
- Wrap in Card with title

#### 19. Create Team Members Table
**File**: [components/dashboard/team-table.tsx](components/dashboard/team-table.tsx)
- Use Table components
- Columns: Member (Avatar + name), Email, Role
- Wrap in Card with title

#### 20. Create Dashboard Tabs
**File**: [components/dashboard/dashboard-tabs.tsx](components/dashboard/dashboard-tabs.tsx)
- Use Tabs component
- Four tabs: Overview (active), Analytics, Reports, Notifications (last 3 disabled)
- Overview contains all dashboard content

---

### Phase 6: Assembly & Polish (60 min)

#### 21. Build Main Dashboard Page
**File**: [app/page.tsx](app/page.tsx)
- Import all dashboard components
- Call getDashboardData()
- Layout structure:
  - Page header with title
  - DashboardTabs wrapper
  - Metric cards grid (1→2→4 cols responsive)
  - Charts row (1→2 cols responsive)
  - Tables row (1→2 cols responsive)

#### 22. Configure Inter Font
**File**: [app/layout.tsx](app/layout.tsx)
- Import Inter from next/font/google
- Apply to body with className

#### 23. Add Custom Styling
**File**: [app/globals.css](app/globals.css)
- Smooth transitions for theme changes
- Custom scrollbar styling
- Hover effects
- Focus states

#### 24. Create Avatar Placeholders
**Directory**: [public/avatars/](public/avatars/)
- Create 01.png through 08.png
- Use UI Avatars service or placeholder images
- Ensure Avatar components have fallback initials

---

### Phase 7: Testing & Refinement (30 min)

#### 25. Development Testing
```bash
npm run dev
```
Test checklist:
- ✓ Dashboard loads at localhost:3000
- ✓ Theme toggle works (light/dark/system)
- ✓ Sidebar collapse/expand
- ✓ All metric cards display
- ✓ Charts render with data
- ✓ Tables show all entries
- ✓ Responsive design works
- ✓ Command palette (⌘K) opens
- ✓ No TypeScript errors

#### 26. Build Optimization
```bash
npm run build
npm start
```
Verify:
- No build errors
- Reasonable bundle size
- Chart.js code-split properly
- Production performance good

#### 27. Final Polish
- Add loading states for charts
- Add empty states for tables
- Improve accessibility (ARIA labels)
- Add tooltips where helpful
- Refine responsive breakpoints

---

## Critical Files to Create (22 total)

### Configuration (Auto-generated)
- package.json, tsconfig.json, tailwind.config.ts, next.config.js, components.json

### Application Core
1. [app/layout.tsx](app/layout.tsx) - Root layout with providers
2. [app/page.tsx](app/page.tsx) - Main dashboard page
3. [app/globals.css](app/globals.css) - Global styles

### Theme & Layout
4. [components/theme-provider.tsx](components/theme-provider.tsx)
5. [components/layout/app-sidebar.tsx](components/layout/app-sidebar.tsx)
6. [components/layout/header.tsx](components/layout/header.tsx)
7. [components/layout/theme-toggle.tsx](components/layout/theme-toggle.tsx)
8. [components/layout/user-nav.tsx](components/layout/user-nav.tsx)

### Dashboard Components
9. [components/dashboard/metric-card.tsx](components/dashboard/metric-card.tsx)
10. [components/dashboard/revenue-chart.tsx](components/dashboard/revenue-chart.tsx)
11. [components/dashboard/sales-chart.tsx](components/dashboard/sales-chart.tsx)
12. [components/dashboard/payments-table.tsx](components/dashboard/payments-table.tsx)
13. [components/dashboard/team-table.tsx](components/dashboard/team-table.tsx)
14. [components/dashboard/dashboard-tabs.tsx](components/dashboard/dashboard-tabs.tsx)

### Charts
15. [components/charts/line-chart.tsx](components/charts/line-chart.tsx)
16. [components/charts/bar-chart.tsx](components/charts/bar-chart.tsx)

### Data Layer
17. [lib/mock-data.ts](lib/mock-data.ts)
18. [lib/chart-config.ts](lib/chart-config.ts)
19. [lib/utils.ts](lib/utils.ts) - Auto-generated by shadcn

### Types
20. [types/dashboard.ts](types/dashboard.ts)

### Assets
21-28. [public/avatars/01-08.png](public/avatars/) - Avatar placeholder images

---

## Key Technical Decisions

### 1. Chart.js Integration
- Use Chart.js (as requested) with react-chartjs-2
- Mark chart components as "use client"
- Use dynamic imports with `{ ssr: false }` to avoid SSR issues
- Theme-aware colors using useTheme() hook

### 2. Sidebar Implementation
- Use shadcn/ui Sidebar component (official, accessible)
- Built-in state management with cookie persistence
- Fully customizable with Tailwind

### 3. Theme Management
- Use next-themes package (industry standard)
- Zero-flash on load with suppressHydrationWarning
- CSS class strategy for theme switching

### 4. Component Strategy
- Server Components by default
- "use client" only when necessary (charts, theme toggle, interactive elements)
- Feature-based organization in components/ directory

### 5. Responsive Design
- Mobile-first with Tailwind breakpoints
- Metrics: 1→2→4 column grid
- Charts/Tables: 1→2 column grid
- Horizontal scroll for tables on mobile

---

## Potential Challenges & Solutions

### Challenge 1: Chart.js SSR Issues
**Solution**: Use dynamic imports with `{ ssr: false }` and "use client" directive

### Challenge 2: Theme Flash on Load
**Solution**: Use next-themes with suppressHydrationWarning and disableTransitionOnChange

### Challenge 3: Sidebar State Persistence
**Solution**: shadcn/ui Sidebar has built-in cookie persistence

### Challenge 4: Responsive Tables
**Solution**: Wrap tables in `overflow-x-auto` containers

### Challenge 5: Chart Colors in Dark Mode
**Solution**: Use useTheme() to detect theme and apply color schemes from chart-config.ts

---

## Project Directory Structure

```
shadcn-dashboard/
├── app/
│   ├── layout.tsx                 # Root layout with providers
│   ├── page.tsx                   # Main dashboard page
│   └── globals.css                # Global styles
├── components/
│   ├── ui/                        # shadcn/ui components (auto-generated)
│   ├── layout/
│   │   ├── app-sidebar.tsx        # Main sidebar
│   │   ├── header.tsx             # Top header
│   │   ├── theme-toggle.tsx       # Theme switcher
│   │   └── user-nav.tsx           # User profile dropdown
│   ├── dashboard/
│   │   ├── metric-card.tsx        # Metric display card
│   │   ├── revenue-chart.tsx      # Revenue line chart
│   │   ├── sales-chart.tsx        # Sales bar chart
│   │   ├── payments-table.tsx     # Payments data table
│   │   ├── team-table.tsx         # Team members table
│   │   └── dashboard-tabs.tsx     # Tab navigation
│   ├── charts/
│   │   ├── line-chart.tsx         # Line chart wrapper
│   │   └── bar-chart.tsx          # Bar chart wrapper
│   └── theme-provider.tsx         # Theme context provider
├── lib/
│   ├── utils.ts                   # Utility functions
│   ├── mock-data.ts               # Mock dashboard data
│   └── chart-config.ts            # Chart.js config
├── types/
│   └── dashboard.ts               # TypeScript interfaces
├── public/
│   └── avatars/                   # User avatar images
├── tailwind.config.ts
├── tsconfig.json
├── next.config.js
├── components.json
└── package.json
```

---

## Estimated Timeline
- **Phase 1** (Foundation): 30 minutes
- **Phase 2** (Theme & Layout): 45 minutes
- **Phase 3** (Data Layer): 20 minutes
- **Phase 4** (Charts): 45 minutes
- **Phase 5** (Dashboard Components): 90 minutes
- **Phase 6** (Assembly & Polish): 60 minutes
- **Phase 7** (Testing): 30 minutes

**Total**: 5-6 hours for complete implementation

---

## Next Steps After Approval

1. Run project initialization commands
2. Install and configure all dependencies
3. Create file structure
4. Implement components in order
5. Test thoroughly
6. Polish and optimize

## Future Enhancement Possibilities

1. **Real API Integration**: Replace mock data with API calls
2. **Authentication**: Add NextAuth.js or Clerk
3. **More Pages**: Analytics, Reports, User Management
4. **Real-time Updates**: WebSocket integration
5. **Advanced Tables**: Add TanStack Table for sorting/filtering
6. **Alternative Charts**: Consider shadcn/ui Chart components (Recharts) for better theme integration