🚀 قالب آماده و مدرن داشبورد مدیریتی (Dashboard Starter Kit)

یک استارتر کیت پیشرفته، ماژولار و کاملاً راست‌چین (RTL) بر پایه React 19، Tailwind CSS v4، Vite 8 و Shadcn UI طراحی‌شده برای ساخت سریع پنل‌های ادمین و داشبوردهای سازمانی.

---

✨ ویژگی‌های کلیدی

• 🎨 طراحی مدرن و کاملاً راست‌چین (RTL-First): همراه با فونت وزیرمتن (Vazirmatn) و متغیرهای مدرن CSS.
• 🏛 شل سه ستونه هوشمند (Triple-Column Layout):
  • سایدبار راست (Right Sidebar): منوی جمع‌شونده (Collapsible Offcanvas) بر اساس کانفیگ متمرکز.
  • محتوای میانی (Main Content): هدر ناوبری (Topbar) همراه با Breadcrumb پویا.
  • پنل کشویی چپ (Left Slide-over Panel): باز شدن جزئیات هر رکورد از چپ بدون ترک یا فشرده شدن صفحه اصلی.
• ⚡ مدیریت پنل‌ها و مودال‌ها از طریق URL (usePanelRouting):
  • قابلیت اشتراک‌گذاری لینک مودال یا پنل باز (Deep Linking).
  • هماهنگ با دکمه Back/Forward مرورگر و کلید Escape.
• 🔍 ابزار جستجوی سراسری هوشمند (Command Palette): میانبر Ctrl + K یا Cmd + K برای دسترسی آنی به تمامی صفحات و اکشن‌های سریع.
• 🔒 سیستم احراز هویت یکپارچه (Auth Flow):
  • صفحه لاگین با حالت آزمایشی (Demo Mode) برای تست سریع بدون نیاز به بک‌اند.
  • کلاینت HTTP با هدرهای خودکار Bearer Token و مدیریت خطای ۴۰۱ (Auto-Logout).
  • گارد امنیتی مسیرها (RequireAuth).
• 🧩 بیش از ۲۵ کامپوننت آماده Shadcn UI + Radix:
  • Dialog / Modal، Alert Dialog، Table، Tabs، Sheet، Select، MultiSelect، Switch، Dropdown، Accordion، Pagination و...
• 📁 معماری تمیز و فیچرمحور (Feature-Based Architecture): سازمان‌دهی بر اساس موجودیت‌ها به همراه دو صفحه نمونه کامل CRUD (کاربران و آیتم‌ها).

---

🛠 راه‌اندازی و اجرا

# ۱. نصب پکیج‌ها
npm install

# ۲. اجرای سرور توسعه
npm run dev

# ۳. بررسی خطاهای تایپ‌اسکریپت
npm run typecheck

# ۴. بیلد نهایی پروداکشن
npm run build

اطلاعات حساب دمو (پیش‌فرض):

• ایمیل: admin@example.com
• رمز عبور: admin

---

📂 ساختار پوشه‌ها

dashboard-template/
├── src/
│   ├── app/                      # روتینگ، گارد احراز هویت و شل اصلی
│   │   ├── App.tsx               # بدنه اصلی (Sidebar + Topbar + PanelSlot)
│   │   ├── router.tsx            # تعریف مسیرهای پروژه
│   │   └── providers.tsx         # کانتکست‌های عمومی (React Query و ...)
│   │
│   ├── config/                   # تنظیمات متمرکز سیستم
│   │   ├── site.ts               # نام پروژه، لوگو و اطلاعات برند
│   │   └── navigation.ts         # لیست صفحات و منوهای سایدبار
│   │
│   ├── components/
│   │   ├── ui/                   # کامپوننت‌های پایه Shadcn (Button, Dialog, Table, ...)
│   │   ├── layout/               # اجزای قالب (AppSidebar, Topbar, PanelSlot)
│   │   └── shared/               # کامپوننت‌های پرتکرار (TablePagination, DeleteConfirmDialog, ...)
│   │
│   ├── features/                 # ماژول‌های بیزینسی (Feature-based)
│   │   ├── auth/                 # ورود، خروج و گارد دسترسی
│   │   ├── dashboard/            # صفحه داشبورد و آمار
│   │   ├── users/                # مدیریت کاربران (جدول، مودال ایجاد/ویرایش)
│   │   ├── items/                # مدیریت نمونه آیتم‌ها (CRUD الگو)
│   │   ├── panels/               # پنل‌های کشویی جزئیات رکوردها
│   │   ├── filters/              # دراور فیلترهای پیشرفته
│   │   └── settings/             # صفحه تنظیمات پنل
│   │
│   ├── services/                 # ارتباط با سرور و API
│   │   ├── http.ts               # کلاینت مرکزی Fetch با اینترسپتور توکن
│   │   ├── auth.ts               # سرویس لاگین و پروفایل
│   │   ├── users-api.ts          # سرویس کاربران (همراه با Mock fallback)
│   │   └── sample-api.ts         # سرویس نمونه CRUD
│   │
│   ├── stores/                   # استیت‌های کلاینت با Zustand (Auth, Search, ...)
│   ├── hooks/                    # هوک‌های سفارشی (usePanelRouting, useMobile, ...)
│   ├── types.ts                  # تایپ‌های عمومی، Pagination و دامنه‌ها
│   └── index.css                 # توکن‌های طراحی، متغیرهای CSS و رنگ‌های قالب

---

📖 راهنمای استفاده در پروژه‌های جدید

۱. چگونه نام و برند داشبورد را تغییر دهم؟

فایل src/config/site.ts را باز کرده و عنوان و توضیحات را ویرایش کنید:

export const siteConfig = {
  name: 'پنل مدیریت من',
  shortName: 'داشبورد',
  description: 'سیستم یکپارچه مدیریت سازمانی',
}

۲. چگونه منوی جدید به سایدبار اضافه کنم؟

فایل src/config/navigation.ts را ویرایش کنید. منو به‌صورت خودکار در سایدبار و در پنجره Ctrl+K نمایش داده می‌شود:

{
  title: 'محصولات و انبار',
  items: [
    { title: 'لیست کالاها', to: '/products', icon: 'grid' },
    { title: 'سفارش‌ها', to: '/orders', icon: 'folder', badge: '۳ جدید' },
  ],
}

۳. چگونه یک مودال (Modal) ایجاد و باز کنم؟

از هوک usePanelRouting استفاده کنید:

import { usePanelRouting } from '@/hooks/use-panel-routing'

function MyComponent() {
  const { openModal } = usePanelRouting()

  return (
    <Button onClick={() => openModal('user', 'new')}>
      افزودن کاربر
    </Button>
  )
}

این کار پارامتر ?edit=user:new را در URL ست می‌کند که باعث باز شدن مودال مربوطه می‌شود. برای ویرایش، شناسه رکورد را بفرستید: openModal('user', '123').

۴. چگونه پنل کشویی جزئیات (Detail Drawer) را از سمت چپ باز کنم؟

به سادگی شناسه و نوع را با openPanel صدا بزنید:

const { openPanel } = usePanelRouting()

// در رویداد کلیک روی سطر جدول:
<TableRow onClick={() => openPanel('user', user.id)}>

سپس در src/components/layout/PanelSlot.tsx کامپوننت پنل جدیدتان را به switch-case اضافه نمایید.

۵. چگونه رنگ اصلی برند (Primary Color) را تغییر دهم؟

در فایل src/index.css، مقدار متغیر --primary را با کد رنگ دلخواهتان جایگزین کنید:

:root {
  --primary: #3b82f6; /* آبی کاربنی */
  /* یا #10b981 (زمردی) یا #8b5cf6 (بنفش) */
}

---

💻 کپی برای پروژه جدید

برای ساخت یک پروژه جدید بر اساس این تمپلیت، کافیست محتویات این پوشه را کپی کرده و شروع به توسعه فیچرهای جدید کنید:

cp -r /path/to/dashboard-template /path/to/my-new-app
cd /path/to/my-new-app
npm install
npm run dev