رفتن به محتوای اصلی
  • معرفی
  • نصب
  • Tailwind
  • وب کامپوننت‌ها (بدون React)
  • دوزبانه، فارسی و انگلیسی
  • پلاگین‌های فیگما
  • استفاده با هوش مصنوعی
  • آیکون‌ها
  • راهنمای آیکون‌ها
  • سفارشی‌سازی و تم
  • حرکت و ریزتعامل‌ها
  • حالت‌های کامپوننت‌ها
  • فونت و تایپوگرافی
  • دسترس‌پذیری
  • نوشتن متن رابط
  • رنگ‌ها
  • برند کاشی
  • مقایسه با دیگران
  • نسخه‌ها
  • سیاست تغییرات
  • مهاجرت به ۲.۰
  • امنیت
  • حجم کامپوننت‌ها
  • فیلد فارسی
  • دیت‌پیکر شمسی
  • کد تأیید (OTP)
  • بازهٔ تاریخ شمسی
  • انتخاب ماه
  • شمارش معکوس
  • هیت‌مپ فعالیت
  • انتخاب استان
  • نقشهٔ ایران
  • فرم نشانی
  • انتخاب نوبت
  • ویرایش نگارشی
  • نمایش مبلغ
  • بازهٔ قیمت
  • کارت بانکی
  • رسید پرداخت
  • برگ تقویم
  • لوگوی بانک‌ها
  • ابزارهای فارسی
  • آپلود فایل
  • آکاردئون
  • آواتار
  • اسپلیتر
  • استپر
  • اسکلتون
  • اسلایدر
  • اعتبارسنجی فرم
  • امتیاز ستاره‌ای
  • انتخاب چندتایی
  • انتخاب رنگ
  • بج
  • بردکرامب
  • برگهٔ پایین
  • بنر
  • پاپ‌اور
  • تایم‌لاین
  • تب‌ها
  • تور معرفی
  • توست
  • تولتیپ
  • جداکننده و کلید میان‌بر
  • جدول داده
  • جستجو با پیشنهاد
  • چک‌باکس
  • چیپس
  • حالت خالی
  • دراپ‌داون
  • دکمه
  • دکمهٔ کپی
  • دیالوگ
  • رادیو
  • سایدبار
  • سگمنت
  • سلکت
  • سوییچ
  • صفحه‌بندی
  • قدرت رمز عبور
  • کارت
  • کارت آمار
  • کاروسل
  • کامبوباکس
  • کامند پالت
  • کشو
  • گروه دکمه
  • گیج
  • منوی راست‌کلیک
  • نمای درختی
  • نمودار
  • نمونهٔ رنگ
  • نوار پیشرفت
  • نوار ناوبری
  • ورودی
  • ورودی تگ
  • ورودی عدد
  • ویرایش درجا
  • هشدار
شروع کنید

نسخه‌ها و سیاست تغییرات

کاشی از نسخهٔ ۱.۰ قول می‌دهد که API کامپوننت‌ها بی‌خبر نشکند؛ هر حذفی دست‌کم یک نسخه پیش‌تر «منسوخ» اعلام می‌شود و هر نسخهٔ اصلی راهنمای مهاجرت دارد.

از نسخهٔ ۱.۰، کاشی برای استفاده در محصولات سازمانی پایدار است. این صفحه می‌گوید چه چیزی ثابت می‌ماند، چه چیزی چطور عوض می‌شود و هر نسخه تا کی پشتیبانی می‌شود.

شمارهٔ نسخه

کاشی از Semantic Versioning پیروی می‌کند. همهٔ پکیج‌ها (@kashi-ui/react، css، elements، persian، tokens، icons، bank-logos، tailwind و mcp) با یک شمارهٔ نسخه منتشر می‌شوند تا هیچ‌وقت لازم نباشد بپرسید کدام با کدام سازگار است.

تغییر مثال نسخه
رفع باگ، بهتر شدن ظاهر بدون تغییر API فاصلهٔ درست بین برچسب و فیلد 1.0.0 ← 1.0.1
قابلیت یا کامپوننت تازه، prop اختیاری تازه کامپوننت انتخاب نوبت 1.0.1 ← 1.1.0
تغییر ناسازگار حذف یا تغییر نام prop، تغییر مقدار پیش‌فرض، حذف کلاس CSS 1.1.0 ← 2.0.0

چه چیزهایی API عمومی است

  • همهٔ کامپوننت‌ها، propها و نوع‌های TypeScript که از @kashi-ui/react و @kashi-ui/elements export شده‌اند.
  • نام تگ‌های وب کامپوننت (kashi-*)، ویژگی‌ها (attributes) و رویدادهای kashi-change.
  • کلاس‌های CSS با پیشوند k- و متغیرهای CSS با پیشوند --k-.
  • تابع‌های @kashi-ui/persian و توکن‌های @kashi-ui/tokens.
  • کلیدهای فرهنگ متن‌ها (faMessages، enMessages).

ساختار داخلی HTML، کلاس‌ها و متغیرهایی که با _ شروع می‌شوند (مثل --_p) و متن پیش‌فرض برچسب‌ها جزو API نیستند. متن‌ها ممکن است در نسخهٔ کوچک بهتر شوند؛ اگر به متن دقیقی نیاز دارید، آن را با prop یا messages خودتان بدهید.

منسوخ کردن، پیش از حذف

هیچ قابلیتی بی‌خبر حذف نمی‌شود:

۱. اعلام منسوخ شدن در یک نسخهٔ کوچک (مثلاً 1.4.0): قابلیت هنوز کار می‌کند، در حالت توسعه یک هشدار [kashi] منسوخ: … در کنسول می‌آید که جایگزین را می‌گوید، در صفحهٔ همان کامپوننت برچسب «منسوخ» می‌خورد و در یادداشت نسخه‌ها نوشته می‌شود. ۲. دست‌کم یک نسخهٔ کوچک با هر دو راه، قدیمی و جدید، منتشر می‌شود تا فرصت مهاجرت داشته باشید. ۳. حذف فقط در نسخهٔ اصلی بعدی (مثلاً 2.0.0)، همراه با راهنمای مهاجرت.

هشدارها فقط در حالت توسعه نشان داده می‌شوند و در بیلد production هیچ هزینه‌ای ندارند.

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

هر نسخهٔ اصلی صفحهٔ مهاجرت خودش را دارد: چه چیزی عوض شده، چرا، و کد قبل و بعد برای هر مورد. مهاجرت به ۲.۰ و ۱.۰

مدت پشتیبانی

نسخه وضعیت پشتیبانی
۱.x فعلی قابلیت تازه، رفع باگ و رفع امنیتی
۰.x قدیمی به ۱.۰ مهاجرت کنید؛ مهاجرت تغییر کدی لازم ندارد

وقتی نسخهٔ ۲.۰ منتشر شود، ۱.x تا ۱۲ ماه رفع‌های امنیتی و باگ‌های جدی را می‌گیرد. جزئیات گزارش و رفع آسیب‌پذیری‌ها در امنیت آمده است.

سازگاری

پشتیبانی‌شده
React ۱۸ و ۱۹؛ در App Router نکست کامپوننت‌ها در صفحه‌های سرور هم کار می‌کنند
فریم‌ورک‌ها Next.js (در هر تغییر خودکار نصب و بیلد می‌شود)، Vite، Remix؛ وب کامپوننت‌ها برای Vue، Svelte، Angular و HTML
مرورگرها Chrome و Edge ۱۲۰+، Firefox ۱۲۱+، Safari ۱۶٫۴+ (iOS و macOS)
Tailwind ۳ و ۴
Node.js (برای ابزارها) ۲۲ به بالا

چطور کیفیت حفظ می‌شود

در هر تغییر، پیش از انتشار:

  • تست رفتار برای همهٔ کامپوننت‌ها، ابزارهای فارسی و وب کامپوننت‌ها.
  • تست دوزبانه: همهٔ کامپوننت‌ها به انگلیسی رندر می‌شوند و نباید حتی یک حرف فارسی در متن‌هایشان بماند.
  • تست تصویری: از همهٔ نمونه‌های این سایت و حالت‌های حساس (خطا کنار فیلد بی‌خطا، متن بلند، غیرفعال، انگلیسی) در تم روشن و تیره عکس گرفته و با عکس مرجع مقایسه می‌شود.
  • سقف حجم: هر کامپوننت سقف حجم دارد و بزرگ‌تر شدنش بی‌اجازه ممکن نیست. حجم کامپوننت‌ها
  • کنتراست رنگ همهٔ جفت‌رنگ‌های تم با WCAG 2.2 AA.
  • نصب واقعی در یک پروژهٔ Next.js، با npm و با shadcn.
  • کیت فیگما در شبیه‌ساز اجرا و پیکسل‌به‌پیکسل با CSS مقایسه می‌شود.