راهنمای مهاجرت

راهنمای گام‌به‌گام مهاجرت پروژه‌های فرانت‌اند به Parto Design System

ارتقا از 4.x به 5.0

نسخهٔ 5.0 هرچه در 4.x منسوخ شده بود را حذف می‌کند، SecretDisplay را برمی‌دارد و کامپوننت‌های تکراری را یکی می‌کند (Distribution به‌جای سه توزیع، SeverityBadge به‌جای StatusBadge، TableOfContents به‌جای SectionNavigator، MediaFrame layout="fill" به‌جای SafeImage). همهٔ جایگزین‌ها از 4.2 موجودند، ولی خود codemod فقط در 5.0 هست؛ پس اول ارتقا دهید و در همان تغییر codemod را اجرا کنید:

pnpm add @partodata/ui@^5.
npx --no parto-migrate-v5 ./src را اول بدون --write اجرا کنید و گزارشش را بخوانید، بعد با --write. تغییر نام‌ها، اندازه‌های icon* و loading دکمه، و فیلدهای قدیمی یادداشت انتشار (title، type، media، cta ← اولین مورد changes) را خودش می‌نویسد و بقیه را با جایگزینشان گزارش می‌کند.
موارد گزارش‌شده را دستی درست کنید و typecheck بگیرید؛ نامی که جا مانده باشد خطای نوع می‌دهد.

فهرست کامل هر نام و جایگزینش: MIGRATION-v5.md در بستهٔ @partodata/ui.

پیش‌نیازها

قبل از شروع مهاجرت، مطمئن شوید:

پروژه از React ≥ 18 استفاده می‌کند
Tailwind CSS نصب و پیکربندی شده
پروژه از TypeScript استفاده می‌کند (توصیه‌شده)

مراحل مهاجرت

نصب و راه‌اندازی

# نصب پکیج
pnpm add @partodata/ui

# یا با npm
npm install @partodata/ui

وارد کردن استایل‌ها

روی Tailwind v4 (مسیر پیشنهادی) فقط یک خط لازم است — همان یک import، استایل کامپوننت‌ها، نگاشت نقش‌ها، و متغیر dark: را با هم می‌آورد:

/* app/globals.css */
@import 'tailwindcss';
@import '@partodata/ui/tailwind.css';

Tailwind v3 پشتیبانی نمی‌شود. محصولی که هنوز روی v3 (یا React 18) است، پیش از مهاجرت به کامپوننت‌ها سکو را ارتقا می‌دهد (گام 3). تا آن زمان، اگر از قبل کامپوننت‌های پرتو 3.x را به کار می‌برد روی 3.x می‌ماند، و اگر هنوز کامپوننتی ندارد فقط لایهٔ پایه را از tokens.css می‌گیرد (راهنمای نصب).

ارتقای سکو (Tailwind v4 و React 19)

روی Tailwind v4 پیکربندی JS و preset لازم نیست. محصولی روی Tailwind v3 اول با ابزار رسمی npx @tailwindcss/upgrade به v4 می‌رود و tailwind.config آن جای خود را به @theme در CSS می‌دهد؛ محصولی روی React 18 اول react و react-dom را به نسخهٔ 19 می‌برد و کتابخانه‌هایی را که با آن سازگار نیستند جایگزین می‌کند. مهاجرت به کامپوننت‌های پرتو بعد از این گام است، نه هم‌زمان با آن.

Tailwind v3 با preset پرتو → Tailwind v4

محصولی که کامپوننت‌های پرتو 3.x را روی Tailwind v3، با preset پرتو در tailwind.config و styles.css، به کار می‌برد، این ترتیب را نگه می‌دارد:

پیش از اجرای npx @tailwindcss/upgrade، هر آنچه از پرتو در tailwind.config است بردارید: preset پرتو، مسیر node_modules/@partodata/ui/dist در content، و هر بازنویسی توکن پرتو (رنگ‌های border، background، foreground، primary، …، --radius، container، فهرست فونت). ابزار ارتقا هرچه در tailwind.config بماند را به @theme اپ می‌برد و بازنویسی نقش‌های پرتو در سطح اپ به همهٔ کامپوننت‌ها می‌رسد. رنگ یا اندازه‌ای که مال خود محصول است، می‌ماند.
import styles.css را با همان دو خط Tailwind v4 عوض کنید:
```
@import 'tailwindcss';
@import '@partodata/ui/tailwind.css';
```
انتظار داشته باشید کلاس‌های /alpha روی توکن‌ها (مثل bg-brand/10 یا text-foreground/60) که در نسخهٔ 3 هیچ CSSی نمی‌ساختند، حالا رنگ بگیرند؛ صفحه‌ها را پس از ارتقا ببینید.
cn اپ را به cn پرتو (از @partodata/ui) یا tailwind-merge نسخهٔ 3 ببرید؛ tailwind-merge نسخهٔ 2 کلاس‌های متنی پرتو (text-caption، text-body) را رنگ می‌شمارد و یکی از دو کلاس را دور می‌اندازد.

پیکربندی Next.js (اگر از Next.js استفاده می‌کنید)

// next.config.mjs
const config = {
  transpilePackages: ['@partodata/ui'],
  // ...
}

جایگزینی کامپوننت‌ها

ترتیب پیشنهادی

مهاجرت را از پایین‌ترین سطح شروع کنید و به بالا بروید:

ابتدا Primitive‌ها — Button, Input, Badge, Label, Separator
سپس Form Controls — Select, Checkbox, Radio, Switch, Textarea
سپس Feedback — Toast, Alert, Dialog, Tooltip, Progress
سپس Data Display — Card, Table, Skeleton, Avatar
سپس Navigation و قاب — Tabs, Breadcrumb, Pagination؛ قاب برنامه ProductFrame (یک بار در layout ریشه، به‌جای Sidebar + AppBar یا AppShell)
سپس Composed — PageToolbar, DataTable, MetricCard, Empty, ErrorState

الگوی جایگزینی

برای هر کامپوننت:

// قبل
import { Button } from '@/components/ui/button'

// بعد
import { Button } from '@partodata/ui'

تفاوت‌های کلیدی API

کامپوننت	shadcn محلی	Parto DS	تغییر مورد نیاز
Button	`variant: 'default'`	`variant: 'primary'`	بروزرسانی variant‌ها
Button	`size: 'default'`	`size: 'sm'`	سایز پیش‌فرض `sm` است
Card	فقط `default`	`default`, `outlined`, `elevated`, `interactive`	بدون تغییر لازم
Badge	`variant: 'default'`	همان + `success`, `warning`, `brand`	variant‌های جدید در دسترس
Select	بدون سایز	سایزهای `xs` تا `xl`	می‌توانید سایز اضافه کنید

حذف کامپوننت‌های محلی

بعد از جایگزینی هر کامپوننت:

از تمام importها مطمئن شوید که به DS اشاره می‌کنند
فایل محلی کامپوننت را حذف کنید
اگر فایل components/ui/ خالی شد، کل دایرکتوری را حذف کنید

حذف وابستگی‌های اضافی

بعد از مهاجرت کامل، این وابستگی‌ها را می‌توانید حذف کنید:

# وابستگی‌های Radix UI تکراری
pnpm remove @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-select
# ... و سایر پکیج‌های @radix-ui

# ابزارهای استایل
pnpm remove class-variance-authority clsx tailwind-merge
# (فقط اگر در جای دیگری استفاده نمی‌شوند)

# ابزارهای UI
pnpm remove lucide-react cmdk vaul sonner
# (فقط اگر مستقیماً استفاده نمی‌شوند — DS آن‌ها را re-export می‌کند)

هوک‌ها

DS هوک‌های آماده‌ای دارد که معادل هوک‌های محلی پروژه‌تان هستند:

هوک محلی	معادل DS	توضیح
`useMobile()` / `useIsMobile()`	`useIsMobile()`	نکته: در SSR مقدار `undefined` برمی‌گرداند
`useDebounce()`	`useDebounce()`	debounce مقدار
`useLocalStorage()`	`useLocalStorage()`	sync با localStorage
`useScrollLock()`	`useScrollLock()`	قفل اسکرول body
`useToast()`	`useToast()`	re-export از Sonner
`useInfiniteScroll()`	`useInfiniteScroll()`	تشخیص رسیدن به انتهای لیست

توابع کمکی

تابع محلی	معادل DS	توضیح
`cn()`	`cn()`	ادغام کلاس‌ها (clsx + tailwind-merge)
`formatNumber()`	`formatNumber()`	فرمت عدد با locale
`toPersianNumber()`	— (حذف کنید)	ارقام از فونت می‌آیند؛ برای جداکننده `formatNumber`

توکن‌های رنگ

نگاشت رنگ‌ها

الگوی shadcn	معادل Parto DS
`bg-background`	`bg-background` یا `bg`
`text-foreground`	`text-foreground` یا `text`
`border-border`	`border-border-default` یا `border`
`bg-muted`	`bg-background-muted` یا `bg-muted`
`text-muted-foreground`	`text-foreground-muted` یا `text-muted`
`bg-primary`	`bg-brand`
`text-primary`	`text-brand-600`
`bg-destructive`	`bg-destructive`
`bg-card`	`bg-background-surface-100`

رنگ‌های اضافی DS

DS توکن‌هایی دارد که در shadcn پیش‌فرض وجود ندارند:

Score Tiers: bg-score-excellent, text-score-critical, bg-score-moderate-bg
Engagement: bg-engagement-excellent, text-engagement-poor
Sentiment: text-sentiment-positive, bg-sentiment-negative
Elevation: shadow-elevation-1 تا shadow-elevation-4
Surface Levels: bg-surface-75 تا bg-surface-400 — این‌ها یک نردبان تخت و یکنواخت نیستند: surface-75/100/300 سطوح توپُر (solid) هستند، اما surface-200 و surface-400 لایه‌های نیمه‌شفاف تطبیقی‌اند که روی پس‌زمینهٔ پشت خود ترکیب می‌شوند و با آن بالا می‌آیند

تم‌ها

DS دو تم دارد: Light و Dark.

اگر پروژه‌تان از next-themes استفاده می‌کند، DS خودش next-themes را به‌عنوان optional peer dependency پشتیبانی می‌کند.

// Dark mode خودکار
<div className="dark:bg-background-surface-100">

نکات مهم

RTL

DS بر اساس CSS Logical Properties ساخته شده:

// اشتباه
className = 'ml-4 mr-2 pl-3 pr-1 left-0 text-left border-l'

// درست
className = 'ms-4 me-2 ps-3 pe-1 start-0 text-start border-s'

سایز پیش‌فرض

از نسخهٔ 4.0 دو پیش‌فرض هست: دکمه‌ها "sm" (30 پیکسل) و فیلدهای فرم "md" (38 پیکسل). در نوار ابزار و ردیف فیلتر (PageToolbar، FilterBar) همهٔ کنترل‌ها sm می‌شوند. size="default" منسوخ است (xs می‌دهد). فیلدی که کنار دکمه در سرِ کارت نمودار، سربرگ صفحه، FormHeader، AppBar یا SiteHeader است هم خودش sm می‌شود. راهنمای کامل ارتقا همراه بسته نصب می‌شود: node_modules/@partodata/ui/MIGRATION-v4.md (هر تغییر با پیش و پس و prop صریحی که ظاهر قبلی را نگه می‌دارد، و codemod آن: npx parto-migrate-v4 ./src)؛ دلیل عددها در اندازه و تراکم.

آیکون‌ها

DS آیکون‌های Lucide را re-export می‌کند. اگر آیکون خاصی را لازم دارید:

// آیکون‌های re-export شده از DS
import { Icons } from '@partodata/ui/icons'
;<Icons.search className="size-4" />

// اگر آیکونی در DS نبود، مستقیماً از lucide-react وارد کنید
import { SpecificIcon } from 'lucide-react'

`"use client"`

تمام کامپوننت‌های تعاملی DS دارای "use client" هستند — نیازی به اضافه کردن مجدد ندارید.