ارتقا به نسخهٔ 3

چه چیزی در نسخهٔ 3 عوض شده و در پروژهٔ شما چه کاری لازم دارد

خلاصه برای عجله‌ای‌ها

اگر پروژه‌تان <html className="dark" data-theme="dark"> را ست می‌کند و از Icons استفاده نمی‌کند، فقط یک کار لازم دارید: نسخه را بالا ببرید و بیلد بگیرید.

pnpm add @partodata/ui@^3.0.0

بقیهٔ این صفحه برای بقیهٔ حالت‌هاست. هر بخش می‌گوید «اگر این کار را کرده‌اید» — اگر نکرده‌اید، ردش کنید.

چرا نسخهٔ اصلی عوض شد

نسخهٔ 3 یک بازبینی کامل بود: تمام ایرادهای بحرانی و ایرادهای دسترسی‌پذیری برطرف شدند. بیشتر تغییرها اصلاح باگ‌اند، نه تغییر سلیقه — یعنی رفتار قبلی در آن موارد غلط بود.


آیکون‌ها از بستهٔ اصلی جدا شدند

اگر Icons را import می‌کنید. این تنها تغییری است که حتماً باید دستی انجام دهید.

// قبل
import { Button, Icons } from '@partodata/ui'

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

چرا: شیء Icons دسته‌ای از آیکون‌ها را وارد بستهٔ اصلی می‌کرد، درحالی‌که هیچ کامپوننتی از خود کتابخانه از آن استفاده نمی‌کرد. جدا کردنش حجم بستهٔ اصلی را کم کرد. اگر از Icons استفاده نمی‌کنید، همین حالا بستهٔ سبک‌تری می‌گیرید بدون اینکه کاری بکنید.


تم تیره حالا روی حالت پیش‌فرض هم کار می‌کند

اگر روی <html> هیچ نشانگر تمی ست نمی‌کنید.

مستندات همیشه گفته بود «اگر چیزی ست نکنید، تیره رندر می‌شود». توکن‌های رنگ همین کار را می‌کردند، ولی کلاس‌های dark: روی آن حالت اصلاً فعال نمی‌شدند. نتیجه‌اش این بود که مثلاً حاشیهٔ قرمز فیلدهای خطادار عملاً دیده نمی‌شد.

حالا درست شده. اگر پروژه‌تان className="dark" یا data-theme="dark" را ست می‌کند — مثل روش پیشنهادی در نصب — هیچ فرقی نمی‌کند، دقیقاً مثل قبل رندر می‌شود.

اگر چیزی ست نمی‌کردید، ممکن است چند رنگ کمی متفاوت شود؛ آن‌ها همان رنگ‌هایی هستند که از اول قرار بود ببینید.


3. Drawer — به‌جای چپ و راست، ابتدا و انتها

اگر از Drawer با direction استفاده می‌کنید.

// قبل
<Drawer direction="right">
<Drawer direction="left">

// بعد — در صفحهٔ راست‌چین «انتها» یعنی سمت چپ، و برعکس
<Drawer side="end">
<Drawer side="start">

چرا: قبلاً کشو در صفحهٔ راست‌چین سمت اشتباه نقاشی می‌شد، از سمت مخالف انیمیشن می‌گرفت، و کشیدنش هم برعکس بود. حالا با جهت متن هماهنگ است.


4. TrendIndicator — علامت عدد دیگر با رنگ عوض نمی‌شود

اگر direction را دستی ست می‌کنید تا رنگ را برعکس کنید.

// قبل — این علامت عدد را هم برعکس می‌کرد
<TrendIndicator value={-20} direction="up" />   // «+20٪» می‌نوشت 😱

// بعد — علامت با داده می‌ماند، فقط رنگ عوض می‌شود
<TrendIndicator value={-20} tone="positive" />  // «−20٪» سبز

چرا: یک پراپ هم علامت و هم رنگ را کنترل می‌کرد. برای سنجه‌هایی که «کمتر بهتر است» (هزینه، نرخ خطا) هرکس رنگ را برعکس می‌کرد، علامت عدد هم برعکس می‌شد — یعنی داشبورد عدد معکوس نشان می‌داد. اگر direction را ست نمی‌کنید، چیزی برایتان عوض نشده.

همین اتفاق در ComparisonCard (با higherIsBetter) و در ستون‌های invert جدول هم بود و هر دو خودکار درست شده‌اند — کاری لازم نیست.


5. Sidebar — side="start" بالاخره سمت درست می‌چسبد

اگر برای درست شدن جای نوار کناری، side="end" گذاشته بودید.

آن دور زدن را بردارید. مقدار پیش‌فرض start قبلاً به سمت انتها می‌چسبید، که باگ بود.


عددهای بزرگ فارسی

پیش از این جاهایی رقم فارسی با پسوند کوتاه انگلیسی کنار هم نوشته می‌شد. حالا واحد به فارسی می‌آید — مثلاً «1.2 میلیون».

این خودکار است و کاری لازم ندارد، مگر اینکه در تست‌هایتان دقیقاً همان رشتهٔ قدیمی را چک کرده باشید.

همچنین ProfileCard حالا پراپ locale دارد و پیش‌فرض فارسی است. اگر خروجی انگلیسی می‌خواهید:

<ProfileCard followers={15000} locale="en" />   {/* 15K */}

ورودی عددی — مقدار داخل فیلد حالا ارقام لاتین است

اگر مستقیم روی input.value تست می‌نویسید.

NumberInputLocale دیگر ارقام فارسی را داخل مقدار فیلد نمی‌گذارد؛ ارقام لاتین می‌نویسد و فونت آن‌ها را فارسی نشان می‌دهد. ظاهرش برای کاربر عوض نمی‌شود، ولی کپی/پیست، جستجوی صفحه و صفحه‌خوان درست کار می‌کنند.


8. Banner — نقش دسترسی‌پذیری‌اش عوض شد

کاری لازم ندارد. فقط اگر در تست‌هایتان getByRole('banner') نوشته‌اید، حالا بسته به نوع پیام alert یا status است.


چک‌لیست

بکنید

  • نسخه را به ^3.0.0 ببرید و یک بیلد کامل بگیرید - اگر Icons را import می‌کنید، مسیرش را به @partodata/ui/icons عوض کنید - اگر Drawer با direction دارید، به side تغییرش دهید - اگر TrendIndicator با direction دستی دارید، به tone تغییرش دهید - اگر برای نوار کناری دور زده بودید، برش دارید

نکنید

  • تست‌هایی که خروجی عددی قدیمی (رقم فارسی با پسوند انگلیسی) را چک می‌کنند نگه ندارید — آن خروجی عمداً عوض شده - direction را برای عوض کردن رنگ استفاده نکنید؛ برای آن tone هست

صفحات مرتبط

  • تغییرات نسخه‌ها — فهرست کامل تغییرات هر نسخه
  • نصب — روش پیشنهادی راه‌اندازی، شامل ست کردن تم روی <html>
  • راهنمای مهاجرت — اگر تازه می‌خواهید پروژه‌ای را به سیستم طراحی بیاورید