# Kashi (کاشی)

> Kashi is an open-source, RTL-first Persian design system: accessible React components (@kashi-ui/react), framework-agnostic CSS (@kashi-ui/css), design tokens, 4500 icons in six styles and Persian utilities such as Jalali dates and national ID, IBAN and card validation. MIT licensed.

Setup: `npm i @kashi-ui/react @kashi-ui/css`, import "@kashi-ui/css" once at the app root and set `<html lang="fa" dir="rtl">`. Without React, use the `k-*` CSS classes from each page's HTML example. In Tailwind projects, `@kashi-ui/tailwind` exposes the same tokens as classes (`bg-secondary`, `border-brand`, `rounded-lg`).

For coding assistants, the Kashi MCP server gives the same docs plus icon search, tokens and Persian utilities as tools: `npx -y @kashi-ui/mcp` (https://kashi.sepantapouya.com/docs/ai/).

---

# آکاردئون (Accordion, AccordionItem)

URL: https://kashi.sepantapouya.com/docs/components/accordion/

بخش‌های جمع‌شونده برای محتوای طولانی، مثل پرسش‌های متداول؛ روی details بومی.

```tsx
import { Accordion, AccordionItem } from "@kashi-ui/react";
```

## نمونه

با `type="single"` باز شدن هر بخش بقیه را می‌بندد.

```tsx
<Accordion type="single">
  <AccordionItem title="کاشی رایگان است؟" defaultOpen>بله. …</AccordionItem>
  <AccordionItem title="با Next.js کار می‌کند؟">بله؛ …</AccordionItem>
  <AccordionItem title="می‌توانم فونت خودم را استفاده کنم؟">بله، …</AccordionItem>
</Accordion>
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| type | "single" \| "multiple" | "multiple" | فقط یک بخش باز یا چند بخش (Accordion) |
| flush | boolean | false | بدون حاشیه (Accordion) |
| title | ReactNode | — | عنوان بخش (AccordionItem) |
| defaultOpen | boolean | false | باز در ابتدا (AccordionItem) |

## دسترس‌پذیری

روی `<details>` و `<summary>` بومی ساخته شده: بدون JavaScript کار می‌کند، با <kbd>Enter</kbd> و <kbd>Space</kbd> باز و بسته می‌شود و صفحه‌خوان وضعیت باز یا بسته را اعلام می‌کند. جستجوی صفحه (<kbd>Ctrl</kbd>+<kbd>F</kbd>) محتوای بخش‌های بسته را هم پیدا و باز می‌کند.

---

# هشدار (Alert)

URL: https://kashi.sepantapouya.com/docs/components/alert/

پیامی مهم دربارهٔ وضعیت سیستم یا نتیجهٔ یک عمل، با آیکون شاخص و عمل‌های اختیاری.

```tsx
import { Alert } from "@kashi-ui/react";
```

## رنگ‌ها

سطح هشدار خنثی است و رنگ فقط در آیکون شاخص دیده می‌شود؛ این کار صفحه را آرام نگه می‌دارد.

```tsx
<Alert tone="brand" title="نسخهٔ جدید منتشر شد">کاشی ۰.۲ با هفت کامپوننت تازه در دسترس است.</Alert>
<Alert tone="success" title="تغییرات ذخیره شد" />
<Alert tone="warning" title="اشتراک شما ۳ روز دیگر تمام می‌شود">برای جلوگیری از قطع سرویس، اشتراک را تمدید کنید.</Alert>
<Alert tone="error" title="پرداخت ناموفق بود">موجودی کارت کافی نیست. کارت دیگری را امتحان کنید.</Alert>
```

## عمل‌ها و بستن

```tsx
<Alert
  tone="info"
  title="به‌روزرسانی در دسترس است"
  actions={<>
    <Button variant="link">به‌روزرسانی</Button>
    <Button variant="link">بعداً</Button>
  </>}
  onClose={() => setOpen(false)}
>
  نسخهٔ جدید بهبودهای امنیتی دارد.
</Alert>
```

## پس‌زمینهٔ رنگی

برای پیام‌هایی که باید بیشتر دیده شوند، از `tinted` استفاده کنید.

```tsx
<Alert tone="warning" tinted title="حالت نگهداری">سرویس امشب از ساعت ۲ تا ۴ در دسترس نیست.</Alert>
```

## نوار بالای صفحه و فشرده

```tsx
<Alert tone="brand" layout="banner" title="نسخهٔ ۰.۸ منتشر شد" actions={…} onClose={…}>…</Alert>
<Alert tone="warning" size="sm" title="این ایمیل قبلاً ثبت شده است." />
```

**ویژگی‌های جدید**

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| layout | "card" \| "banner" | "card" | نوار تمام‌عرض بالای صفحه |
| size | "sm" \| "md" | "md" | نسخهٔ فشرده برای داخل فرم |
| classNames | { root, icon, title, description, actions } | — | کلاس دلخواه برای هر بخش |

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| tone | "neutral" \| "brand" \| "info" \| "success" \| "warning" \| "error" | "neutral" | رنگ و آیکون پیش‌فرض |
| title | ReactNode | — | عنوان |
| children | ReactNode | — | توضیح |
| icon | ReactNode \| false | — | آیکون سفارشی؛ false برای حذف |
| actions | ReactNode | — | دکمه‌ها یا لینک‌های زیر متن |
| onClose | () => void | — | با دادن این تابع دکمهٔ بستن نمایش داده می‌شود |
| closeLabel | string | "بستن" | نام دسترس‌پذیر دکمهٔ بستن |
| tinted | boolean | false | پس‌زمینهٔ رنگی کم‌رنگ |
| role | string | خودکار | پیش‌فرض alert برای خطا و هشدار، status برای بقیه |

## متغیرهای CSS

| متغیر CSS | پیش‌فرض | توضیح |
|---|---|---|
| --k-alert-radius | var(--k-radius-xl) | گردی گوشه‌ها |
| --k-alert-padding | 1rem × density | فاصلهٔ داخلی |
| --k-alert-bg | var(--k-bg-secondary) | پس‌زمینه |

## دسترس‌پذیری

- هشدارهای `error` و `warning` نقش `alert` دارند و صفحه‌خوان آن‌ها را فوراً اعلام می‌کند؛ بقیه با نقش `status` بدون قطع کاربر خوانده می‌شوند.
- فقط هشدارهایی را که پس از بارگذاری صفحه اضافه می‌شوند `alert` کنید؛ هشدار ثابت صفحه را با `role="note"` نمایش دهید.
- آیکون تزئینی است و از صفحه‌خوان پنهان است؛ عنوان باید معنا را کامل برساند.

---

# آواتار (Avatar, AvatarGroup)

URL: https://kashi.sepantapouya.com/docs/components/avatar/

نمایش تصویر یا حروف اول یک شخص، با وضعیت حضور و گروه‌بندی.

```tsx
import { Avatar, AvatarGroup } from "@kashi-ui/react";
```

## تصویر و حروف اول

اگر تصویر نباشد یا بارگذاری نشود، حروف اول نام نمایش داده می‌شود. بین حروف فارسی نیم‌فاصله قرار می‌گیرد تا به هم نچسبند. در اندازه‌های `xs` و `sm` فقط حرف اول نمایش داده می‌شود تا خوانا بماند.

```tsx
<Avatar name="سپنتا پویا" src="/images/sepanta-pouya.jpg" size="lg" />
<Avatar name="سارا احمدی" size="lg" />
<Avatar name="علی رضایی" size="lg" brand />
<Avatar name="کاشی" size="lg" square />
```

## اندازه‌ها

```tsx
<Avatar name="سارا احمدی" size="xs" />
<Avatar name="سارا احمدی" size="sm" />
<Avatar name="سارا احمدی" />
<Avatar name="سارا احمدی" size="lg" />
<Avatar name="سارا احمدی" size="xl" />
<Avatar name="سارا احمدی" size="2xl" />
```

## وضعیت

```tsx
<Avatar name="سارا احمدی" status="online" size="lg" />
<Avatar name="علی رضایی" status="busy" size="lg" />
<Avatar name="مریم کریمی" status="away" size="lg" />
<Avatar name="رضا نوری" status="offline" size="lg" />
```

## گروه

```tsx
<AvatarGroup max={4} aria-label="اعضای تیم">
  <Avatar name="سپنتا پویا" src="/images/sepanta-pouya.jpg" />
  <Avatar name="سارا احمدی" brand />
  <Avatar name="علی رضایی" />
  <Avatar name="مریم کریمی" brand />
  <Avatar name="رضا نوری" />
  <Avatar name="نگار صادقی" />
</AvatarGroup>
```

## رنگ خودکار

با `color="auto"` هر نام همیشه یک رنگ ثابت می‌گیرد (در هر دستگاه یکسان)؛ فهرست اعضا خواناتر و رنگارنگ‌تر می‌شود.

```tsx
{members.map((m) => <Avatar key={m.id} name={m.name} color="auto" size="lg" />)}
```

**ویژگی‌های جدید**

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| color | "auto" \| "neutral" \| "brand" \| "info" \| "success" \| "warning" \| "error" | "neutral" | رنگ حروف اول؛ همهٔ رنگ‌ها کنتراست AA دارند |

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| name | string | — | نام شخص (الزامی)؛ برای نام دسترس‌پذیر و حروف اول |
| src | string | — | آدرس تصویر |
| size | "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" | "md" | ۲۴ تا ۶۴ پیکسل |
| status | "online" \| "offline" \| "busy" \| "away" | — | نشانگر وضعیت حضور |
| statusLabels | Partial<Record<AvatarStatus, string>> | فارسی | متن وضعیت برای صفحه‌خوان |
| square | boolean | false | شکل مربعی برای سازمان‌ها و پروژه‌ها |
| brand | boolean | false | رنگ برند برای حالت حروف اول |

**ویژگی‌های AvatarGroup**

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| max | number | — | حداکثر تعداد نمایش؛ بقیه به شکل «+۲» |
| size | AvatarSize | "md" | اندازهٔ آواتار باقی‌مانده |
| moreLabel | (count: number) => string | "۲ نفر دیگر" | متن صفحه‌خوان برای باقی‌مانده |

## متغیرهای CSS

| متغیر CSS | پیش‌فرض | توضیح |
|---|---|---|
| --k-avatar-size | 2.5rem | اندازه |
| --k-avatar-radius | var(--k-radius-full) | گردی گوشه‌ها |
| --k-avatar-bg | var(--k-bg-tertiary) | پس‌زمینهٔ حروف اول |
| --k-avatar-fg | var(--k-text-secondary) | رنگ حروف اول |

## دسترس‌پذیری

- آواتار نقش `img` دارد و نام شخص به‌همراه وضعیت («سارا احمدی، آنلاین») اعلام می‌شود. تصویر داخلی تزئینی است.
- وضعیت فقط با رنگ نمایش داده نمی‌شود؛ متن آن برای صفحه‌خوان در دسترس است.

---

# بج (Badge)

URL: https://kashi.sepantapouya.com/docs/components/badge/

برچسب کوچک برای وضعیت، دسته‌بندی یا شمارش.

```tsx
import { Badge } from "@kashi-ui/react";
```

## رنگ‌ها

رنگ را بر اساس معنا انتخاب کنید، نه سلیقه؛ کاربر رنگ‌ها را در کل محصول یکسان تفسیر می‌کند.

```tsx
<Badge>پیش‌نویس</Badge>
<Badge tone="brand">جدید</Badge>
<Badge tone="success" dot>فعال</Badge>
<Badge tone="warning">در انتظار</Badge>
<Badge tone="error">رد شده</Badge>
<Badge tone="info">بتا</Badge>
```

## اندازه و شکل

```tsx
<Badge tone="brand" size="sm">کوچک</Badge>
<Badge tone="brand">متوسط</Badge>
<Badge tone="brand" size="lg">بزرگ</Badge>
<Badge tone="success" square>مربعی</Badge>
```

## سبک‌ها و برچسب‌های حذف‌شدنی

```tsx
<Badge tone="success" variant="solid">پرداخت‌شده</Badge>
<Badge tone="brand" variant="outline">بتا</Badge>
<Badge variant="outline" icon={<UserIcon />}>۱۲ عضو</Badge>

// فیلترهای فعال
{tags.map((t) => <Badge key={t} tone="brand" onRemove={() => remove(t)}>{t}</Badge>)}
```

**ویژگی‌های جدید**

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| variant | "soft" \| "solid" \| "outline" | "soft" | سبک |
| icon | ReactNode | — | آیکون ابتدای متن |
| onRemove / removeLabel | () => void / string | «حذف {متن}» | دکمهٔ حذف با نام برای صفحه‌خوان |

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| tone | "neutral" \| "brand" \| "error" \| "warning" \| "success" \| "info" | "neutral" | رنگ معنایی |
| size | "sm" \| "md" \| "lg" | "md" | اندازه |
| dot | boolean | false | نقطهٔ رنگی ابتدای متن |
| square | boolean | false | گوشهٔ کم به‌جای گرد |

## متغیرهای CSS

| متغیر CSS | پیش‌فرض | توضیح |
|---|---|---|
| --k-badge-radius | var(--k-radius-full) | گردی گوشه‌ها |
| --k-badge-font-weight | 500 | وزن متن |

## دسترس‌پذیری

- همهٔ ترکیب‌های رنگ متن و پس‌زمینه کنتراست حداقل ۴٫۵ به ۱ دارند.
- رنگ نباید تنها حامل معنا باشد؛ متن نشان باید به‌تنهایی وضعیت را برساند.
- اگر عدد نشان (مثلاً تعداد پیام‌ها) تغییر می‌کند، تغییر را با یک ناحیهٔ `aria-live` اعلام کنید.

---

# بنر (Banner)

URL: https://kashi.sepantapouya.com/docs/components/banner/

پیام سطح صفحه مثل نسخهٔ جدید، پایان اشتراک یا اختلال سرویس، با دکمهٔ عمل و بستن.

```tsx
import { Banner } from "@kashi-ui/react";
```

برای پیامی که به کل صفحه یا حساب مربوط است. پیام مربوط به یک بخش یا فرم را با `Alert` و پیام گذرا را با `Toast` نشان دهید.

## نمونه

```tsx
<Banner tone="brand" icon={<InfoIcon />} onClose={dismiss}
  actions={<Button size="sm" variant="primary">مشاهدهٔ تغییرات</Button>}>
  <strong>نسخهٔ ۰٫۱۰ منتشر شد.</strong> هفت کامپوننت تازه…
</Banner>

<Banner tone="warning" icon={<WarningIcon />} actions={<Button size="sm">تمدید اشتراک</Button>}>
  <strong>اشتراک شما ۳ روز دیگر تمام می‌شود.</strong> …
</Banner>
```

برای چسباندن به بالای صفحه، `flush` را بدهید تا حاشیه و گوشهٔ گرد حذف شود.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| tone | "neutral" \| "brand" \| "warning" \| "error" | "neutral" | رنگ |
| icon | ReactNode | — | آیکون شاخص |
| actions | ReactNode | — | دکمه یا لینک‌ها |
| onClose | () => void | — | با آن دکمهٔ بستن نمایش داده می‌شود |
| flush | boolean | false | بدون حاشیه، برای بالای صفحه |
| label / closeLabel | string | «اطلاعیه» / «بستن اطلاعیه» | نام ناحیه و دکمه |

## دسترس‌پذیری

ناحیهٔ `role="region"` با نام «اطلاعیه»، تا کاربر صفحه‌خوان بتواند به آن پرش کند. نوار به‌عمد `aria-live` ندارد، چون هنگام بارگذاری صفحه نمایش داده می‌شود؛ برای پیام‌هایی که بعداً ظاهر می‌شوند از `Toast` استفاده کنید.

---

# بردکرامب (Breadcrumb)

URL: https://kashi.sepantapouya.com/docs/components/breadcrumb/

نشان می‌دهد کاربر کجای ساختار سایت است.

```tsx
import { Breadcrumb } from "@kashi-ui/react";
```

## نمونه

خانه فقط با آیکون نمایش داده می‌شود و برچسبش برای صفحه‌خوان می‌ماند.

```tsx
<Breadcrumb items={[
  { label: "خانه", href: "/", icon: <HomeIcon />, hideLabel: true },
  { label: "تنظیمات", href: "/settings" },
  { label: "امنیت" },
]} />
```

## مسیر بلند

با `maxItems` وسط مسیر به «…» جمع می‌شود؛ با زدن آن، مسیر کامل باز می‌شود. نام‌های بلند هم کوتاه می‌شوند و متن کامل در `title` است.

```tsx
<Breadcrumb maxItems={3} items={[
  { label: "خانه", href: "/", icon: <HomeIcon />, hideLabel: true },
  { label: "پروژه‌ها", href: "/projects" },
  { label: "فروشگاه آنلاین", href: "/projects/shop" },
  { label: "تنظیمات", href: "/projects/shop/settings" },
  { label: "امنیت و ورود دو مرحله‌ای" },
]} />
```

## جداکنندهٔ «/»

```tsx
<Breadcrumb separator="slash" items={[…]} />
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| items | { label, href?, icon?, hideLabel? }[] | — | آخرین مورد صفحهٔ فعلی است |
| maxItems | number | — | جمع کردن وسط مسیرهای بلند |
| separator | "chevron" \| "slash" | "chevron" | شکل جداکننده |
| label | string | "مسیر" | نام nav برای صفحه‌خوان |
| expandLabel | string | "نمایش مسیر کامل" | نام دکمهٔ «…» |

## متغیرهای CSS

`--k-breadcrumb-max-item` (پیش‌فرض `14rem`): بیشترین عرض هر مورد پیش از کوتاه شدن.

## دسترس‌پذیری

داخل `<nav aria-label="مسیر">` با فهرست `<ol>`؛ صفحهٔ فعلی `aria-current="page"` دارد و لینک نیست. جداکننده‌ها تزئینی‌اند و در راست‌به‌چپ آینه می‌شوند. «…» یک دکمهٔ واقعی با نام «نمایش مسیر کامل» است.

---

# گروه دکمه (ButtonGroup, Button)

URL: https://kashi.sepantapouya.com/docs/components/button-group/

دکمه‌های چسبیده به هم برای عمل‌های مرتبط، مثل «روز / هفته / ماه» یا «قبلی / امروز / بعدی».

```tsx
import { ButtonGroup, Button } from "@kashi-ui/react";
```

## نمونه

```tsx
<ButtonGroup aria-label="بازهٔ تقویم">
  <Button aria-pressed={view === "day"} onClick={() => setView("day")}>روز</Button>
  <Button aria-pressed={view === "week"} onClick={() => setView("week")}>هفته</Button>
  <Button aria-pressed={view === "month"} onClick={() => setView("month")}>ماه</Button>
</ButtonGroup>

<ButtonGroup aria-label="پیمایش">
  <Button iconOnly aria-label="قبلی">…</Button>
  <Button>امروز</Button>
  <Button iconOnly aria-label="بعدی">…</Button>
</ButtonGroup>
```

برای انتخاب یک گزینه از چند گزینه، `SegmentedControl` معمولاً مناسب‌تر است؛ `ButtonGroup` برای عمل‌هاست. دکمهٔ روشن با `aria-pressed` یا `aria-current` برجسته می‌شود.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| aria-label | string | — | نام گروه برای صفحه‌خوان |
| children | Button[] | — | دکمه‌ها؛ همهٔ گونه‌ها و اندازه‌های Button |

## دسترس‌پذیری

ظرف `role="group"` با نام دارد. هر دکمه جدا در ترتیب Tab است و حلقهٔ فوکوس روی دکمهٔ کناری نمی‌رود.

---

# دکمه (Button)

URL: https://kashi.sepantapouya.com/docs/components/button/

برای اجرای یک عمل. شش گونه برای سلسله‌مراتب بصری، چهار اندازه و حالت بارگذاری دسترس‌پذیر.

```tsx
import { Button } from "@kashi-ui/react";
```

## گونه‌ها

در هر بخش از صفحه فقط یک دکمهٔ `primary` بگذارید. بقیهٔ عمل‌ها با `secondary` یا `tertiary` نمایش داده شوند.

```tsx
<Button variant="primary">ذخیره</Button>
<Button variant="secondary">پیش‌نمایش</Button>
<Button variant="tertiary">انصراف</Button>
<Button variant="link">اطلاعات بیشتر</Button>
<Button variant="danger">حذف</Button>
<Button variant="danger-secondary">بایگانی</Button>
```

## اندازه‌ها

```tsx
<Button variant="primary" size="sm">کوچک</Button>
<Button variant="primary">متوسط</Button>
<Button variant="primary" size="lg">بزرگ</Button>
<Button variant="primary" size="xl">خیلی بزرگ</Button>
```

## با آیکون

`iconStart` در RTL سمت راست و `iconEnd` سمت چپ قرار می‌گیرد. آیکون‌های جهت‌دار مثل فلش را با `data-k-mirror` علامت بزنید تا در RTL آینه شوند.

```tsx
<Button variant="primary" iconStart={<PlusIcon />}>پروژهٔ جدید</Button>
<Button iconEnd={<ArrowIcon />}>ادامه</Button>
<Button iconOnly aria-label="جستجو"><SearchIcon /></Button>
<Button variant="danger-secondary" iconOnly aria-label="حذف"><TrashIcon /></Button>
```

## حالت‌ها

```tsx
<Button variant="primary" loading>پرداخت</Button>
<Button disabled>غیرفعال</Button>
```

## شکل، اندازه و لینک

با `href` دکمه یک لینک واقعی (`<a>`) می‌شود؛ با `as` می‌توانید کامپوننت لینک روتر خود را بدهید، مثل `as={Link}` در Next.js.

```tsx
<Button variant="primary" shape="pill">کاملاً گرد</Button>
<Button shape="square">گوشهٔ کم</Button>
<Button size="xs">خیلی کوچک</Button>
<Button href="/docs" variant="link">دکمهٔ لینکی</Button>
<Button as={Link} href="/pricing">با Link در Next.js</Button>
```

**ویژگی‌های جدید**

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| shape | "default" \| "pill" \| "square" | "default" | شکل گوشه‌ها |
| size | "xs" \| "sm" \| "md" \| "lg" \| "xl" | "md" | اندازهٔ xs (۲۸ پیکسل) اضافه شد |
| href / target / rel | string | — | رندر به‌صورت لینک؛ با disabled، href حذف و aria-disabled گذاشته می‌شود |
| as | ElementType | — | عنصر یا کامپوننت دلخواه |

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| variant | "primary" \| "secondary" \| "tertiary" \| "link" \| "danger" \| "danger-secondary" | "secondary" | سبک بصری و اهمیت عمل |
| size | "sm" \| "md" \| "lg" \| "xl" | "md" | اندازه؛ ارتفاع‌ها ۳۶، ۴۰، ۴۴ و ۴۸ پیکسل |
| loading | boolean | false | نمایش اسپینر؛ دکمه فوکوس‌پذیر می‌ماند ولی کلیک نمی‌گیرد |
| loadingLabel | string | "در حال بارگذاری" | متنی که صفحه‌خوان هنگام بارگذاری اعلام می‌کند |
| iconStart | ReactNode | — | آیکون ابتدای متن |
| iconEnd | ReactNode | — | آیکون انتهای متن |
| iconOnly | boolean | false | دکمهٔ مربعی فقط‌آیکون؛ aria-label الزامی است |
| block | boolean | false | تمام‌عرض |

سایر ویژگی‌های `<button>` مثل `onClick`، `type` و `disabled` هم پشتیبانی می‌شوند. مقدار پیش‌فرض `type` برابر `"button"` است تا فرم‌ها ناخواسته ارسال نشوند.

## متغیرهای CSS

| متغیر CSS | پیش‌فرض | توضیح |
|---|---|---|
| --k-btn-height-{sm,md,lg,xl} | 2.25rem تا 3rem × density | ارتفاع هر اندازه |
| --k-btn-padding-{sm,md,lg,xl} | 0.75rem تا 1.25rem × density | فاصلهٔ افقی داخلی |
| --k-btn-radius | var(--k-radius-md) | گردی گوشه‌ها |
| --k-btn-font-weight | 600 | وزن متن |
| --k-btn-gap | var(--k-space-1_5) | فاصلهٔ آیکون و متن |

## دسترس‌پذیری

- در حالت `loading` از `aria-disabled` به‌جای `disabled` استفاده می‌شود تا فوکوس کیبورد از دست نرود، و متن «در حال بارگذاری» با `role="status"` اعلام می‌شود.
- دکمهٔ `iconOnly` بدون `aria-label` در حالت توسعه هشدار می‌دهد.
- حداقل ناحیهٔ لمس ۲۴×۲۴ پیکسل است و حلقهٔ فوکوس در حالت کنتراست بالای ویندوز هم دیده می‌شود.
- برای رفتن به صفحهٔ دیگر از لینک (`<a class="k-btn">`) استفاده کنید، نه دکمه.

---

# کارت (Card, CardHeader, CardTitle, CardDescription, CardBody, CardFooter)

URL: https://kashi.sepantapouya.com/docs/components/card/

ظرفی برای گروه‌بندی محتوای مرتبط، با سربرگ، بدنه و پانویس.

```tsx
import { Card, CardHeader, CardTitle, CardDescription, CardBody, CardFooter } from "@kashi-ui/react";
```

## پایه

```tsx
<Card>
  <CardHeader>
    <CardTitle>پلن حرفه‌ای</CardTitle>
    <CardDescription>برای تیم‌های در حال رشد</CardDescription>
  </CardHeader>
  <CardBody>۴۹۰ هزار تومان در ماه، تا ۲۰ کاربر.</CardBody>
  <CardFooter>
    <Button variant="tertiary">مقایسه</Button>
    <Button variant="primary">انتخاب پلن</Button>
  </CardFooter>
</Card>
```

## کارت قابل‌کلیک

کل سطح کارت قابل‌کلیک است، ولی فقط یک لینک با کلاس `k-card__link` دارد؛ کاربر کیبورد با یک Tab از آن عبور می‌کند.

```tsx
<Card interactive>
  <CardHeader>
    <Badge tone="brand">راهنما</Badge>
    <CardTitle>
      <a className="k-card__link" href="/docs/accessibility/">دسترس‌پذیری در کاشی</a>
    </CardTitle>
    <CardDescription>آنچه خودکار تضمین می‌شود و آنچه بر عهدهٔ شماست.</CardDescription>
  </CardHeader>
</Card>
```

## سبک‌ها، تصویر و منوی سربرگ

```tsx
<Card variant="elevated" padding="sm">
  <CardMedia src="/cover.jpg" alt="" ratio="16 / 9" />
  <CardHeader actions={<DropdownMenu trigger={…}>…</DropdownMenu>}>
    <CardTitle>سبک برجسته</CardTitle>
    <CardDescription>با تصویر و منوی سربرگ</CardDescription>
  </CardHeader>
</Card>

<Card variant="filled">…</Card>
```

**ویژگی‌های جدید**

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| variant | "outlined" \| "elevated" \| "filled" | "outlined" | سبک (Card) |
| padding | "none" \| "sm" \| "md" \| "lg" | "md" | فاصلهٔ داخلی همهٔ بخش‌ها (Card) |
| actions | ReactNode | — | دکمه یا منو در انتهای سربرگ (CardHeader) |
| ratio | string | "16 / 9" | نسبت ابعاد تصویر (CardMedia) |

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| as | ElementType | "article" | عنصر HTML؛ برای کارت‌های غیرمستقل div یا section |
| flat | boolean | false | بدون سایه |
| interactive | boolean | false | حالت hover و فوکوس برای کارت قابل‌کلیک |

`CardTitle` پیش‌فرض `h3` است. با `as` سطح عنوان را با ساختار صفحه هماهنگ کنید؛ برای مثال `<CardTitle as="h2">`.

## متغیرهای CSS

| متغیر CSS | پیش‌فرض | توضیح |
|---|---|---|
| --k-card-padding | 1.5rem × density | فاصلهٔ داخلی بخش‌ها |
| --k-card-radius | var(--k-radius-xl) | گردی گوشه‌ها |
| --k-card-bg | var(--k-bg-elevated) | پس‌زمینه |
| --k-card-border | var(--k-border-secondary) | رنگ حاشیه |
| --k-card-shadow | var(--k-shadow-xs) | سایه |

## دسترس‌پذیری

- از کارت‌هایی که کل آن‌ها یک لینک بزرگ است (`<a>` دور همهٔ محتوا) پرهیز کنید؛ صفحه‌خوان همهٔ متن را به‌عنوان نام لینک می‌خواند.
- در کارت قابل‌کلیک، دکمه‌های داخلی دیگر را بالای لایهٔ لینک (`position: relative; z-index: 1`) قرار دهید.

---

# کاروسل (Carousel)

URL: https://kashi.sepantapouya.com/docs/components/carousel/

نمایش چند کارت یا تصویر در یک ردیف قابل‌پیمایش، مثل محصولات پیشنهادی.

```tsx
import { Carousel } from "@kashi-ui/react";
```

## نمونه

```tsx
<Carousel label="محصولات پیشنهادی" perView={2}>
  {products.map((p) => <ProductCard key={p.id} {...p} />)}
</Carousel>
```

روی scroll-snap بومی مرورگر ساخته شده: با کشیدن انگشت، چرخ موس، دکمه‌ها و کلیدهای جهت کار می‌کند و در RTL خودکار درست است. چرخش خودکار ندارد، چون خواندن را برای همه، به‌خصوص کاربران صفحه‌خوان و کم‌بینا، سخت می‌کند.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| children | ReactNode | — | هر فرزند یک اسلاید |
| label | string | — | نام کاروسل (الزامی) |
| perView | number | 1 | تعداد اسلاید در هر نما؛ یا متغیر --k-carousel-per-view |
| dots | boolean | true | نقطه‌های پیمایش |
| labels | { prev?, next?, slide? } | — | متن دکمه‌ها و نام اسلایدها |

## دسترس‌پذیری

الگوی Carousel در WAI-ARIA: ظرف با `aria-roledescription="اسلایدر"` و هر اسلاید با نام «۲ از ۵». ریل اسلایدها فوکوس‌پذیر است و ←→ بین آن‌ها حرکت می‌کند؛ اسلاید فعال با `aria-live` اعلام می‌شود.

---

# نمودار (BarChart, BarList, LineChart, PieChart, ProportionBar, Sparkline)

URL: https://kashi.sepantapouya.com/docs/components/charts/

نمودار ستونی، انباشته، خطی، دایره‌ای و دونات، میله‌ای افقی، سهم از کل و خط روند؛ با ارقام فارسی و جدول هم‌ارز برای صفحه‌خوان.

```tsx
import { BarChart, BarList, LineChart, PieChart, ProportionBar, Sparkline } from "@kashi-ui/react";
```

نمودارهای کاشی برای داشبورد و پنل مدیریت ساخته شده‌اند، نه برای تحلیل سنگین داده. اگر نمودار تعاملی پیچیده لازم دارید، از کتابخانهٔ تخصصی استفاده کنید و رنگ‌ها را از متغیرهای `--k-chart-1` تا `--k-chart-4` بگیرید.

## ستونی

برای مقایسهٔ مقدار در چند دسته یا دوره. فقط بلندترین ستون برچسب دارد؛ مقدار بقیه با موس یا Tab نمایش داده می‌شود.

```tsx
<BarChart
  title="فروش ماهانه (میلیون تومان)"
  data={[{ label: "فروردین", value: 82 }, { label: "اردیبهشت", value: 96 }, …]}
/>
```

## ستونی انباشته

برای ترکیب یک کل در طول زمان، تا چهار سری. بخش‌ها با فاصلهٔ ۲ پیکسلی از هم جدا شده‌اند و راهنما همیشه نمایش داده می‌شود.

```tsx
<BarChart title="سفارش‌ها بر اساس کانال" labels={months} series={[
  { name: "وب", values: [420, 460, …] },
  { name: "اپ", values: [260, 300, …] },
  { name: "حضوری", values: [120, 110, …] },
]} />
```

## خطی

برای روند در طول زمان، تا چهار سری. محور زمان در جهت خواندن صفحه است: در RTL اولین ماه سمت راست. نام هر سری کنار انتهای خطش آمده تا تشخیص سری فقط به رنگ وابسته نباشد.

```tsx
<LineChart
  title="کاربران فعال روزانه"
  labels={["فروردین", "اردیبهشت", …]}
  series={[
    { name: "وب", values: [3200, 3600, …] },
    { name: "اپ", values: [1800, 2300, …] },
    { name: "API", values: [600, 700, …] },
  ]}
/>
```

## میله‌ای افقی

برای رتبه‌بندی، به‌خصوص وقتی نام‌ها بلندند؛ نام داخل میله و مقدار در انتهای ردیف.

```tsx
<BarList title="پربازدیدترین صفحه‌ها" data={[
  { label: "صفحهٔ اصلی", value: 48210 },
  { label: "محصولات / مبل راحتی", value: 21840, href: "/products/sofa" },
  …
]} />
```

## سهم از کل

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

```tsx
<ProportionBar title="منبع ورود کاربران" data={[
  { label: "جستجوی گوگل", value: 46200 },
  { label: "ورود مستقیم", value: 21800 },
  { label: "اینستاگرام", value: 15400 },
  { label: "سایر", value: 6100 },
]} />
```

## دایره‌ای و دونات

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

```tsx
<PieChart title="سفارش‌ها بر اساس استان" data={[
  { label: "تهران", value: 48200 },
  { label: "اصفهان", value: 18400 },
  …
]} />

<PieChart title="روش پرداخت" variant="pie" data={[…]} />
```

## خط روند

شکل روند بدون محور، برای کارت آمار و سلول جدول. نام دسترس‌پذیر را با جهت روند بدهید.

```tsx
<Sparkline values={[4, 6, 5, 8, 7, 9, 12]} tone="success" aria-label="روند فروش: افزایشی" />
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| title | string | — | عنوان و نام دسترس‌پذیر (الزامی) |
| data (BarChart) | { label, value }[] | — | یک سری |
| labels / series (BarChart) | string[] / { name, values }[] | — | ستون انباشته، حداکثر چهار سری |
| data (BarList) | { label, value, href? }[] | — | ردیف‌ها به همان ترتیب |
| data (ProportionBar) | { label, value }[] | — | حداکثر چهار بخش؛ percent برای درصد |
| data / variant (PieChart) | { label, value }[] / "donut" \| "pie" | "donut" | حداکثر پنج بخش؛ totalLabel برای متن وسط |
| values / tone (Sparkline) | number[] / brand \| success \| error \| neutral | — | بدون محور؛ aria-label بدهید |
| labels / series (LineChart) | string[] / { name, values }[] | — | حداکثر چهار سری؛ بیشتر نادیده گرفته می‌شود |
| format | (n: number) => string | ارقام فارسی | قالب مقدار در راهنما و جدول |
| area (LineChart) | boolean | false | سطح کم‌رنگ زیر خط، فقط برای یک سری |
| labelMax (BarChart) | boolean | true | برچسب مقدار روی بلندترین ستون |
| height | string | "14rem" | یا متغیر --k-chart-height |

## رنگ‌ها

چهار رنگ دسته‌ای با ترتیب ثابت، برای تم تیره و روشن جداگانه انتخاب و با شبیه‌سازی کوررنگی بررسی شده‌اند (فاصلهٔ رنگی دست‌کم ۸). رنگ همیشه به نام سری وابسته است، نه به جایگاهش. نمودار دومحوره نداریم؛ دو مقیاس متفاوت را در دو نمودار جدا نشان دهید.

## دسترس‌پذیری

هر نمودار یک جدول هم‌ارز پنهان دارد که صفحه‌خوان کامل می‌خواند. در نمودار ستونی هر ستون با Tab فوکوس می‌گیرد («آبان: ۱۸۴»)؛ در نمودار خطی، با فوکوس روی نمودار کلیدهای ←→ بین نقطه‌ها حرکت می‌کنند و مقدار همهٔ سری‌ها اعلام می‌شود.

---

# چک‌باکس (Checkbox)

URL: https://kashi.sepantapouya.com/docs/components/checkbox/

برای انتخاب یک یا چند گزینه، یا تأیید یک مورد. روی input بومی ساخته شده است.

```tsx
import { Checkbox } from "@kashi-ui/react";
```

## پایه

```tsx
<Checkbox label="مرا به خاطر بسپار" defaultChecked />
<Checkbox label="خبرنامه" description="ماهی یک ایمیل، بدون تبلیغات." />
```

## حالت‌ها

`indeterminate` برای «انتخاب همه» وقتی فقط بخشی از گزینه‌ها انتخاب شده‌اند.

```tsx
<Checkbox label="انتخاب همه" indeterminate />
<Checkbox label="قوانین را می‌پذیرم" invalid />
<Checkbox label="غیرفعال" disabled />
<Checkbox label="بزرگ" size="lg" defaultChecked />
```

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| label | ReactNode | — | برچسب کنار چک‌باکس؛ کل برچسب قابل‌کلیک است |
| description | ReactNode | — | توضیح زیر برچسب؛ با aria-describedby متصل می‌شود |
| indeterminate | boolean | false | حالت نیمه‌انتخاب |
| invalid | boolean | false | حالت خطا |
| size | "md" \| "lg" | "md" | ۱۸ یا ۲۰ پیکسل |

## متغیرهای CSS

| متغیر CSS | پیش‌فرض | توضیح |
|---|---|---|
| --k-checkbox-size | 1.125rem | اندازه |
| --k-checkbox-radius | 0.3125rem × radius-factor | گردی گوشه‌ها |

## دسترس‌پذیری

- روی `<input type="checkbox">` بومی ساخته شده؛ کلید Space، فرم‌ها و صفحه‌خوان‌ها بدون کد اضافه کار می‌کنند.
- در حالت کنتراست بالای ویندوز، ظاهر بومی سیستم نمایش داده می‌شود.
- برای گروه چک‌باکس‌ها از `<fieldset>` و `<legend>` استفاده کنید.

---

# چیپس (ChipGroup)

URL: https://kashi.sepantapouya.com/docs/components/chips/

فیلترهای روشن و خاموش‌شونده با تعداد نتیجه، بالای فهرست یا جدول.

```tsx
import { ChipGroup } from "@kashi-ui/react";
```

## نمونه

```tsx
<ChipGroup aria-label="وضعیت سفارش" value={v} onChange={setV} options={[
  { value: "paid", label: "پرداخت‌شده", count: 128 },
  { value: "pending", label: "در انتظار", count: 14 },
  { value: "shipped", label: "ارسال‌شده", count: 96 },
]} />
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| options | { value, label, icon?, count?, disabled? }[] | — | چیپ‌ها |
| value / defaultValue | string[] | [] | چیپ‌های روشن |
| onChange | (value: string[]) => void | — | — |
| single | boolean | false | فقط یکی روشن؛ کلیک دوباره خاموشش می‌کند |
| aria-label | string | — | نام گروه |

## دسترس‌پذیری

هر چیپ یک دکمه با `aria-pressed` است. حالت روشن با تیک، رنگ و حاشیه نشان داده می‌شود، نه فقط رنگ.

---

# انتخاب رنگ (ColorPicker)

URL: https://kashi.sepantapouya.com/docs/components/color-picker/

انتخاب رنگ برند یا برچسب با نمونه‌رنگ‌ها، پنل انتخاب دلخواه و کد hex، همراه کنتراست متن.

```tsx
import { ColorPicker } from "@kashi-ui/react";
```

## نمونه

```tsx
<ColorPicker label="رنگ برند" value={color} onChange={setColor} name="brand" />
```

با زدن روی مربع رنگ، پنل انتخاب دلخواه باز می‌شود: سطح اشباع و روشنایی، نوار رنگ‌مایه، فیلدهای R، G و B، و در مرورگرهایی که پشتیبانی می‌کنند قطره‌چکان برای برداشتن رنگ از صفحه. در سطح رنگ، کلیدهای جهت یک درصد و با Shift ده درصد جابه‌جا می‌کنند.

زیر انتخابگر، کنتراست رنگ با متن سفید یا مشکی (هر کدام بهتر است) نمایش داده می‌شود تا رنگی انتخاب نشود که متن روی آن خوانا نباشد. تابع `contrastRatio` هم صادر شده است.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | string | "#0b8077" | رنگ hex |
| onChange | (hex: string) => void | — | — |
| swatches | { name, value }[] | رنگ‌های کاشی | نمونه‌رنگ‌ها؛ [] برای حذف |
| showContrast | boolean | true | نمایش کنتراست متن |
| name | string | — | فیلد پنهان برای فرم |

## دسترس‌پذیری

نمونه‌رنگ‌ها رادیوهای بومی با نام فارسی هستند («فیروزه‌ای»)، نه فقط یک خانهٔ رنگی. کد hex یک فیلد متنی معمولی است، پس کاربر صفحه‌خوان هم می‌تواند رنگ دقیق را وارد کند. سطح رنگ یک slider با مقدار متنی است («اشباع ۹۱٪، روشنایی ۷۰٪») و Esc پنل را می‌بندد و فوکوس را به مربع رنگ برمی‌گرداند.

---

# کامبوباکس (Combobox)

URL: https://kashi.sepantapouya.com/docs/components/combobox/

فیلد جستجو با فهرست پیشنهادها (Combobox)؛ برای فهرست‌های بلند مثل شهر، کاربر یا محصول.

```tsx
import { Combobox } from "@kashi-ui/react";
```

وقتی گزینه‌ها بیشتر از ده‌تاست، به‌جای `Select` از `Combobox` استفاده کنید. جستجو متن فارسی را یکدست می‌کند: «ي» و «ی»، «ك» و «ک» و ارقام فارسی و انگلیسی یکی حساب می‌شوند.

## نمونه

```tsx
const [city, setCity] = useState<string | null>(null);

<Combobox label="استان" placeholder="جستجو کنید…"
  options={provinces.map((p) => ({ value: p, label: p }))}
  value={city} onChange={setCity} />
```

## گروه، توضیح و آیکون

```tsx
<Combobox label="مسئول" options={[
  { value: "sara", label: "سارا محمدی", description: "طراح محصول", group: "طراحی", icon: <Avatar name="سارا محمدی" size="xs" /> },
  { value: "ali", label: "علی رضایی", group: "فنی", keywords: ["ali"] },
  { value: "mina", label: "مینا احمدی", group: "فنی", disabled: true },
]} />
```

برای جستجوی سمت سرور، `onInputChange` را بگیرید، `options` را از پاسخ سرور بسازید، `loading` را در زمان درخواست روشن کنید و `filter={() => true}` بدهید.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| options | { value, label, description?, icon?, group?, keywords?, disabled? }[] | — | گزینه‌ها؛ گزینه‌های هم‌گروه باید پشت سر هم باشند |
| value / defaultValue | string \| null | null | مقدار انتخاب‌شده |
| onChange | (value: string \| null) => void | — | پس از انتخاب یا پاک کردن |
| onInputChange | (query: string) => void | — | تغییر متن جستجو |
| filter | (option, query) => boolean | defaultFilter | جستجوی سفارشی |
| loading | boolean | false | اسپینر و متن «در حال جستجو…» |
| emptyMessage | ReactNode | «نتیجه‌ای پیدا نشد.» | متن فهرست خالی |
| name | string | — | فیلد پنهان برای ارسال فرم |
| label / hint / error | ReactNode | — | مثل ورودی |

ابزارهای `defaultFilter`، `searchText` و `highlight` هم صادر شده‌اند تا در جستجوهای خودتان استفاده کنید.

## کیبورد

| کلید | عمل |
|---|---|
| <kbd>↓</kbd> / <kbd>↑</kbd> | باز کردن فهرست و رفتن به گزینهٔ بعد / قبل |
| <kbd>Enter</kbd> | انتخاب گزینهٔ فعال |
| <kbd>Esc</kbd> | بستن فهرست؛ اگر بسته است، پاک کردن مقدار |
| <kbd>Home</kbd> / <kbd>End</kbd> | اولین / آخرین گزینه (وقتی فهرست باز است) |

## دسترس‌پذیری

الگوی Combobox در WAI-ARIA با `aria-activedescendant`: فوکوس همیشه در فیلد می‌ماند و صفحه‌خوان گزینهٔ فعال را می‌خواند. تعداد نتیجه‌ها پس از هر تایپ با یک ناحیهٔ `aria-live` اعلام می‌شود («۳ نتیجه») و گزینه‌های غیرفعال `aria-disabled` دارند.

---

# کامند پالت (CommandPalette)

URL: https://kashi.sepantapouya.com/docs/components/command-palette/

جستجوی سریع صفحه‌ها و عملیات با Ctrl+K، به سبک ابزارهای حرفه‌ای.

```tsx
import { CommandPalette, type CommandItem } from "@kashi-ui/react";
```

## نمونه

```tsx
const [open, setOpen] = useState(false);
const items: CommandItem[] = [
  { id: "home", label: "داشبورد", group: "صفحه‌ها", icon: <HomeIcon />, shortcut: "G D", href: "/" },
  { id: "users", label: "کاربران", group: "صفحه‌ها", keywords: ["users"], href: "/users" },
  { id: "new", label: "پروژهٔ جدید", group: "عملیات", shortcut: "N", onSelect: createProject },
];

<Button onClick={() => setOpen(true)}>جستجوی دستور <Kbd keys={["Ctrl", "K"]} /></Button>
<CommandPalette open={open} onOpenChange={setOpen} items={items} />
```

پالت را یک بار در ریشهٔ برنامه بگذارید. با `shortcut` (پیش‌فرض روشن) میان‌بر <kbd>Ctrl</kbd>+<kbd>K</kbd> (و <kbd>⌘</kbd>+<kbd>K</kbd> در مک) در کل صفحه فعال است.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| open / onOpenChange | boolean / (open) => void | — | کنترل باز و بسته بودن |
| items | { id, label, group?, icon?, shortcut?, description?, keywords?, href?, onSelect? }[] | — | فرمان‌ها؛ با href به آن آدرس می‌رود |
| shortcut | boolean | true | میان‌بر سراسری Ctrl/⌘+K |
| placeholder | string | «جستجوی صفحه یا فرمان…» | — |
| emptyMessage | ReactNode | «نتیجه‌ای پیدا نشد.» | — |
| labels | { title?, navigate?, select?, close?, results? } | — | متن‌های راهنما و صفحه‌خوان |

## دسترس‌پذیری

روی `<dialog>` بومی ساخته شده، پس فوکوس داخل پنجره می‌ماند و پشت آن غیرفعال است. فیلد جستجو `role="combobox"` است و فهرست `listbox`؛ با <kbd>↑</kbd>/<kbd>↓</kbd> حرکت، <kbd>Enter</kbd> اجرا و <kbd>Esc</kbd> بسته می‌شود و فوکوس به دکمه‌ای که پالت را باز کرد برمی‌گردد.

---

# منوی راست‌کلیک (ContextMenu, MenuItem, MenuSeparator)

URL: https://kashi.sepantapouya.com/docs/components/context-menu/

منوی میان‌بر روی فایل، ردیف جدول یا کارت؛ با موس و کیبورد.

```tsx
import { ContextMenu, MenuItem, MenuSeparator } from "@kashi-ui/react";
```

## نمونه

```tsx
<ContextMenu label="عملیات فایل" menu={
  <>
    <MenuItem onSelect={open}>باز کردن</MenuItem>
    <MenuItem shortcut="Ctrl+D" onSelect={copy}>کپی</MenuItem>
    <MenuSeparator />
    <MenuItem tone="danger" onSelect={remove}>حذف</MenuItem>
  </>
}>
  <FileCard tabIndex={0} />
</ContextMenu>
```

گزینه‌ها همان `MenuItem`، `MenuSeparator` و `MenuLabel` دراپ‌داون‌اند. منو کنار نشانگر باز می‌شود و از لبهٔ صفحه بیرون نمی‌رود.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| children | ReactNode | — | ناحیهٔ راست‌کلیک |
| menu | ReactNode | — | گزینه‌ها |
| label | string | «گزینه‌ها» | نام منو |

## دسترس‌پذیری

راست‌کلیک برای کاربر کیبورد و صفحه‌خوان در دسترس نیست، پس منو با کلید ContextMenu یا <kbd>Shift</kbd>+<kbd>F10</kbd> روی عنصر فوکوس‌شده هم باز می‌شود و این راهنما به ناحیه وصل است. همهٔ عمل‌های منو باید از راه دیگری (دکمه یا منوی کشویی) هم در دسترس باشند.

---

# دکمهٔ کپی (CopyButton)

URL: https://kashi.sepantapouya.com/docs/components/copy-button/

کپی متن در کلیپ‌بورد با بازخورد «کپی شد»، برای کلید API، شماره شبا یا کد تخفیف.

```tsx
import { CopyButton } from "@kashi-ui/react";
```

## نمونه

```tsx
<Input aria-label="کلید API" readOnly value="sk_live_4f9a…b21c" />
<CopyButton value={apiKey} />
<CopyButton value={iban} iconOnly labels={{ copy: "کپی شماره شبا" }} />
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | string | — | متنی که کپی می‌شود |
| onCopy | (value: string) => void | — | پس از کپی موفق |
| iconOnly | boolean | false | فقط آیکون؛ نام از labels.copy |
| timeout | number | 2000 | مدت نمایش «کپی شد» به میلی‌ثانیه |
| labels | { copy?, copied?, failed? } | «کپی»، «کپی شد»، «کپی نشد» | — |
| variant / size | ButtonProps | "secondary" / "sm" | همهٔ props دکمه |

## دسترس‌پذیری

نتیجه («کپی شد» یا «کپی نشد») با `aria-live` اعلام می‌شود، پس کاربر صفحه‌خوان هم بازخورد می‌گیرد. در حالت فقط‌آیکون، نام دکمه هم به «کپی شد» تغییر می‌کند. کلیپ‌بورد فقط در HTTPS یا localhost در دسترس است.

---

# دیالوگ (Dialog)

URL: https://kashi.sepantapouya.com/docs/components/dialog/

پنجره‌ای روی صفحه برای کاری کوتاه یا تأیید یک تصمیم، روی dialog بومی مرورگر.

```tsx
import { Dialog } from "@kashi-ui/react";
```

## نمونه

```tsx
const [open, setOpen] = useState(false);

<Button onClick={() => setOpen(true)}>دعوت هم‌تیمی</Button>
<Dialog
  open={open}
  onOpenChange={setOpen}
  title="دعوت به تیم"
  description="ایمیل هم‌تیمی را وارد کنید تا دعوت‌نامه برایش ارسال شود."
  icon={<UserIcon />}
  footer={<>
    <Button variant="secondary" onClick={() => setOpen(false)}>انصراف</Button>
    <Button variant="primary">ارسال دعوت</Button>
  </>}
>
  <Input label="ایمیل" type="email" autoFocus />
</Dialog>

// تأیید عملیات مخرب
<Dialog tone="danger" size="sm" title="پروژه حذف شود؟" … />
```

## کشوی کناری و برگهٔ پایین

همان دسترس‌پذیری دیالوگ (تلهٔ فوکوس، Esc، برگشت فوکوس) با چیدمان کشو؛ برگهٔ پایین برای گوشی مناسب است.

```tsx
<Dialog placement="end" open={open} onOpenChange={setOpen} title="فیلترها" footer={…}>
  …
</Dialog>

<Dialog placement="bottom" …>…</Dialog>
```

**ویژگی‌های جدید**

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| placement | "center" \| "start" \| "end" \| "bottom" | "center" | جایگاه؛ در RTL «start» سمت راست است |
| size | "sm" \| "md" \| "lg" \| "full" | "md" | اندازهٔ full اضافه شد |

متغیرهای CSS: `--k-drawer-width` (پیش‌فرض ۲۶rem) و `--k-dialog-backdrop`.

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| open | boolean | — | باز بودن (کنترل‌شده) |
| onOpenChange | (open: boolean) => void | — | با Esc، دکمهٔ بستن یا کلیک روی پس‌زمینه |
| title | ReactNode | — | عنوان — الزامی |
| description | ReactNode | — | توضیح زیر عنوان |
| icon | ReactNode | — | آیکون شاخص |
| tone | "default" \| "danger" | "default" | رنگ آیکون برای عملیات مخرب |
| size | "sm" \| "md" \| "lg" | "md" | عرض: ۲۴، ۳۰ یا ۴۲ rem |
| footer | ReactNode | — | دکمه‌ها |
| dismissible | boolean | true | بستن با کلیک روی پس‌زمینه |
| closeLabel | string | "بستن" | نام دکمهٔ بستن |

## دسترس‌پذیری

- روی `<dialog>` بومی با `showModal()` ساخته شده: فوکوس داخل پنجره می‌ماند، بقیهٔ صفحه برای کیبورد و صفحه‌خوان غیرفعال می‌شود و <kbd>Esc</kbd> پنجره را می‌بندد.
- پس از بستن، فوکوس به دکمه‌ای که پنجره را باز کرده برمی‌گردد.
- عنوان و توضیح با `aria-labelledby` و `aria-describedby` به پنجره متصل‌اند.
- برای تأیید عملیات مخرب، دکمهٔ «انصراف» را اول بگذارید و نتیجهٔ کار را در توضیح صریح بنویسید.

---

# جداکننده و کلید میان‌بر (Divider, Kbd)

URL: https://kashi.sepantapouya.com/docs/components/divider/

خط جداکننده با متن اختیاری، و نمایش کلیدهای صفحه‌کلید.

```tsx
import { Divider, Kbd } from "@kashi-ui/react";
```

## جداکننده

```tsx
<Divider />
<Divider label="یا" />
```

## کلید صفحه‌کلید

```tsx
<Kbd keys={["Ctrl", "K"]} />
<Kbd>Esc</Kbd>
```

**ویژگی‌های Divider و Kbd**

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| label | ReactNode | — | متن وسط خط (Divider) |
| vertical | boolean | false | جداکنندهٔ عمودی (Divider) |
| keys | string[] | — | ترکیب کلیدها (Kbd) |

کلیدها همیشه چپ‌به‌راست نمایش داده می‌شوند تا ترتیب «Ctrl + K» در متن فارسی برعکس نشود.

---

# دراپ‌داون (DropdownMenu, MenuItem, MenuSeparator, MenuLabel)

URL: https://kashi.sepantapouya.com/docs/components/dropdown-menu/

فهرستی از عمل‌ها که با یک دکمه باز می‌شود؛ با الگوی Menu Button و پیمایش کامل کیبورد.

```tsx
import { DropdownMenu, MenuItem, MenuSeparator, MenuLabel } from "@kashi-ui/react";
```

## نمونه

```tsx
<DropdownMenu trigger={<Button>گزینه‌ها</Button>}>
  <MenuLabel>پروژه</MenuLabel>
  <MenuItem icon={<EditIcon />} shortcut="Ctrl+E" onSelect={edit}>ویرایش</MenuItem>
  <MenuItem icon={<CopyIcon />} shortcut="Ctrl+D" onSelect={copy}>کپی</MenuItem>
  <MenuItem icon={<ArchiveIcon />} disabled>بایگانی</MenuItem>
  <MenuSeparator />
  <MenuItem icon={<TrashIcon />} tone="danger" onSelect={remove}>حذف</MenuItem>
</DropdownMenu>

<DropdownMenu align="end" label="عملیات ردیف"
  trigger={<Button variant="tertiary" iconOnly aria-label="عملیات بیشتر"><DotsIcon /></Button>}>
  …
</DropdownMenu>
```

## کیبورد

| کلید | عمل |
|---|---|
| <kbd>Enter</kbd> / <kbd>Space</kbd> / <kbd>↓</kbd> | باز کردن و رفتن به اولین گزینه |
| <kbd>↑</kbd> روی دکمه | باز کردن و رفتن به آخرین گزینه |
| <kbd>↑</kbd> / <kbd>↓</kbd> | گزینهٔ قبل / بعد (گزینه‌های غیرفعال رد می‌شوند) |
| <kbd>Home</kbd> / <kbd>End</kbd> | اولین / آخرین گزینه |
| حرف | پرش به گزینه‌ای که با آن حرف شروع می‌شود |
| <kbd>Esc</kbd> | بستن و برگشت به دکمه |
| <kbd>Tab</kbd> | بستن و رفتن به عنصر بعدی صفحه |

## گزینه‌های تیک‌دار

برای تنظیماتی مثل نمایش ستون‌ها؛ منو پس از انتخاب باز می‌ماند تا چند گزینه پشت سر هم عوض شوند.

```tsx
<MenuItem checked={cols.date} onSelect={() => toggle("date")}>تاریخ</MenuItem>
```

`checked` نقش گزینه را `menuitemcheckbox` با `aria-checked` می‌کند. متغیرهای CSS: `--k-menu-min-width`، `--k-menu-radius`، `--k-menu-item-height`، `--k-menu-bg`.

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| trigger | ReactElement | — | دکمهٔ بازکننده (DropdownMenu) |
| label | string | متن دکمه | نام منو برای صفحه‌خوان |
| align | "start" \| "end" | "start" | هم‌ترازی با دکمه |
| onSelect | () => void | — | با انتخاب گزینه؛ منو بسته می‌شود (MenuItem) |
| icon / shortcut | ReactNode / string | — | آیکون و میان‌بر نمایشی |
| tone | "default" \| "danger" | "default" | رنگ قرمز برای عملیات مخرب |
| href | string | — | گزینهٔ لینکی |
| disabled | boolean | false | غیرفعال؛ در پیمایش رد می‌شود |

## دسترس‌پذیری

- دکمه `aria-haspopup="menu"` و `aria-expanded` دارد؛ منو `role="menu"` با گزینه‌های `menuitem`.
- فوکوس داخل منو با کلیدهای جهت‌دار جابه‌جا می‌شود، نه Tab؛ پس از انتخاب یا Esc، فوکوس به دکمه برمی‌گردد.
- منو برای **عمل‌ها** است. برای انتخاب یک مقدار در فرم از [سلکت](/docs/components/select/) استفاده کنید.

---

# حالت خالی (EmptyState)

URL: https://kashi.sepantapouya.com/docs/components/empty-state/

وقتی داده‌ای برای نمایش نیست؛ توضیح بدهید چرا و قدم بعدی را پیشنهاد کنید.

```tsx
import { EmptyState } from "@kashi-ui/react";
```

## نمونه

```tsx
<EmptyState
  icon={<FolderIcon />}
  title="هنوز پروژه‌ای ندارید"
  description="اولین پروژه را بسازید یا از یکی از قالب‌های آماده شروع کنید."
  actions={<>
    <Button variant="secondary">مشاهدهٔ قالب‌ها</Button>
    <Button variant="primary">پروژهٔ جدید</Button>
  </>}
/>
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| title | ReactNode | — | عنوان — الزامی |
| description | ReactNode | — | توضیح و راهنمایی |
| icon | ReactNode | — | آیکون |
| actions | ReactNode | — | دکمه‌ها |

داخل [جدول داده](/docs/components/table/) هم می‌توانید آن را به‌عنوان `empty` بدهید.

---

# آپلود فایل (FileUpload)

URL: https://kashi.sepantapouya.com/docs/components/file-upload/

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

```tsx
import { FileUpload } from "@kashi-ui/react";
```

## نمونه

فایلی که نامش «خطا» دارد، در این نمونه با شکست روبه‌رو می‌شود.

```tsx
<FileUpload
  accept="image/png,image/jpeg,application/pdf"
  maxSize={5 * 1024 * 1024}
  maxFiles={4}
  hint="PNG، JPG یا PDF؛ هر فایل تا ۵ مگابایت"
  uploader={(file, onProgress) => upload(file, { onProgress })}
/>
```

`uploader` هر فایل را می‌گیرد و یک Promise برمی‌گرداند؛ با `onProgress(درصد)` نوار پیشرفت به‌روز می‌شود. بدون `uploader`، فایل‌ها فقط فهرست می‌شوند و با `onFilesChange` به شما می‌رسند (یا با `name` در فرم ارسال می‌شوند).

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| accept | string | — | مثل input بومی |
| multiple | boolean | true | — |
| maxSize | number | — | بیشترین حجم هر فایل به بایت |
| maxFiles | number | — | بیشترین تعداد |
| uploader | (file, onProgress) => Promise<void> | — | بارگذاری هر فایل |
| onFilesChange | (items: FileItem[]) => void | — | وضعیت همهٔ فایل‌ها |
| hint | ReactNode | — | متن راهنما داخل ناحیه |
| labels | { browse?, drop?, tooBig?, wrongType?, tooMany?, … } | — | متن‌ها |

تابع `formatBytes` حجم را فارسی می‌نویسد: `formatBytes(1536)` ← «۱٫۵ کیلوبایت».

## دسترس‌پذیری

ناحیهٔ رها کردن یک دکمهٔ واقعی «انتخاب فایل» دارد، پس بدون موس هم کار می‌کند. هر فایل نام، حجم و وضعیتش را با متن نشان می‌دهد (نه فقط رنگ) و دکمهٔ حذف آن «حذف نام‌فایل» نام دارد. پایان بارگذاری و خطاها با `aria-live` اعلام می‌شوند.

---

# ویرایش درجا (InlineEdit)

URL: https://kashi.sepantapouya.com/docs/components/inline-edit/

ویرایش متن در همان جا، مثل نام پروژه یا عنوان کارت، بدون فرم جداگانه.

```tsx
import { InlineEdit } from "@kashi-ui/react";
```

## نمونه

```tsx
<InlineEdit label="نام پروژه" defaultValue="بازطراحی فروشگاه"
  validate={(v) => (v ? undefined : "نام پروژه نمی‌تواند خالی باشد.")}
  onSave={(v) => api.rename(v)} />
```

اگر `onSave` یک Promise برگرداند، دکمهٔ ثبت تا پایانش در حالت بارگذاری می‌ماند و در صورت خطا متن قبلی برمی‌گردد.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| label | string | — | نام فیلد برای صفحه‌خوان (الزامی) |
| value / defaultValue | string | "" | — |
| onSave | (value) => void \| Promise | — | پس از ثبت |
| validate | (value) => string \| undefined | — | پیام خطا |
| renderView | (value) => ReactNode | — | ظاهر حالت نمایش، مثلاً عنوان |
| placeholder | string | «خالی» | — |

## کیبورد

| کلید | عمل |
|---|---|
| <kbd>Enter</kbd> روی متن | شروع ویرایش |
| <kbd>Enter</kbd> در فیلد | ثبت |
| <kbd>Esc</kbd> | انصراف و برگشت به متن |

## دسترس‌پذیری

حالت نمایش یک دکمه با نام کامل است («نام پروژه: بازطراحی فروشگاه، ویرایش»). پس از ثبت یا انصراف، فوکوس به همان دکمه برمی‌گردد.

---

# ورودی (Input, Textarea)

URL: https://kashi.sepantapouya.com/docs/components/input/

فیلد متن تک‌خطی و چندخطی، با برچسب، متن راهنما، پیام خطا و افزونه.

```tsx
import { Input, Textarea } from "@kashi-ui/react";
```

## پایه

برچسب، متن راهنما و فیلد به‌صورت خودکار با `id` و `aria-describedby` به هم وصل می‌شوند.

```tsx
<Input label="نام و نام خانوادگی" placeholder="مثلاً سارا احمدی" hint="همان‌طور که در کارت ملی آمده است." required />
```

## خطا

با دادن `error`، فیلد `aria-invalid` می‌شود و پیام خطا پیش از متن راهنما خوانده می‌شود.

```tsx
<Input label="ایمیل" type="email" defaultValue="sara@example" error="آدرس ایمیل معتبر نیست." />
```

## افزونه‌ها

ایمیل، تلفن، آدرس اینترنتی، عدد و رمز عبور به‌صورت خودکار چپ‌به‌راست تایپ می‌شوند، ولی متن راهنمای داخل فیلد راست‌چین می‌ماند.

```tsx
<Input label="ایمیل" type="email" placeholder="you@example.com" addonStart={<MailIcon />} />
<Input label="مبلغ" inputMode="numeric" placeholder="۰" addonEnd="تومان" />
<Input aria-label="جستجو" placeholder="جستجو…" addonStart={<SearchIcon />} size="sm" />
```

## چندخطی

```tsx
<Textarea label="توضیحات" placeholder="چند خط بنویسید…" hint="حداکثر ۵۰۰ نویسه." />
```

## غیرفعال

```tsx
<Input label="کد ملی" defaultValue="۰۰۱۲۳۴۵۶۷۸" disabled />
```

## رمز، پاک کردن، شمارنده و بیشتر

```tsx
<Input label="رمز عبور" type="password" labelEnd={<a href="/forgot">فراموشی رمز؟</a>} />
<Input aria-label="جستجو" addonStart={<SearchIcon />} clearable />
<Input label="نام کاربری" loading hint="در حال بررسی…" />
<Input label="نام شرکت" optional />
<Textarea label="دربارهٔ شما" autoResize showCount maxLength={280} />
```

**ویژگی‌های جدید**

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| type="password" | — | — | دکمهٔ نمایش/پنهان کردن رمز خودکار اضافه می‌شود؛ با revealable={false} خاموش |
| clearable / onClear | boolean / () => void | — | دکمهٔ پاک کردن وقتی فیلد مقدار دارد |
| loading | boolean | false | اسپینر در انتهای فیلد |
| showCount | boolean | false | شمارندهٔ نویسه؛ با maxLength به شکل «۱۲ / ۲۸۰» |
| optional | boolean \| string | — | نشان «(اختیاری)» کنار برچسب |
| labelEnd | ReactNode | — | محتوای انتهای ردیف برچسب |
| autoResize / maxRows | boolean / number | — | ارتفاع خودکار Textarea |
| classNames | { root, label, box, control, addon, hint, error } | — | کلاس دلخواه برای هر بخش داخلی |
| labels | { clear, show, hide, loading } | فارسی | متن‌های صفحه‌خوان |

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| label | ReactNode | — | برچسب بالای فیلد؛ اگر نمی‌دهید aria-label بدهید |
| hint | ReactNode | — | متن راهنمای زیر فیلد |
| error | ReactNode | — | پیام خطا؛ فیلد را aria-invalid می‌کند |
| size | "sm" \| "md" \| "lg" | "md" | ارتفاع‌ها ۴۰، ۴۴ و ۴۸ پیکسل (فقط Input) |
| addonStart | ReactNode | — | آیکون یا متن ابتدای فیلد (فقط Input) |
| addonEnd | ReactNode | — | آیکون یا متن انتهای فیلد (فقط Input) |
| fieldClassName | string | — | کلاس ظرف بیرونی k-field |
| required | boolean | false | ستاره کنار برچسب و ویژگی required |

سایر ویژگی‌های `<input>` و `<textarea>` به خود فیلد منتقل می‌شوند. `ref` به عنصر فیلد اشاره می‌کند.

## متغیرهای CSS

| متغیر CSS | پیش‌فرض | توضیح |
|---|---|---|
| --k-input-height-{sm,md,lg} | 2.25rem تا 2.75rem × density | ارتفاع؛ هم‌قد دکمه‌های sm، md و lg |
| --k-input-radius | var(--k-radius-md) | گردی گوشه‌ها |
| --k-input-bg | var(--k-bg-primary) | پس‌زمینه |
| --k-input-border | var(--k-border-input) | رنگ حاشیه در حالت عادی |
| --k-field-gap | var(--k-space-1_5) | فاصلهٔ برچسب، فیلد و راهنما |

## دسترس‌پذیری

- حاشیهٔ فیلد کنتراست حداقل ۳ به ۱ دارد تا مرز آن برای کاربران کم‌بینا مشخص باشد.
- متن راهنمای داخل فیلد (placeholder) جایگزین برچسب نیست؛ با تایپ کاربر ناپدید می‌شود.
- پیام خطا باید بگوید چه اشتباهی رخ داده و چطور درست شود، نه فقط «نامعتبر».

---

# گیج (Meter)

URL: https://kashi.sepantapouya.com/docs/components/meter/

نمایش یک مقدار در برابر سقف، مثل فضای ذخیره، سهمیهٔ پیامک یا ظرفیت پلن.

```tsx
import { Meter } from "@kashi-ui/react";
```

## نمونه

```tsx
<Meter label="فضای ذخیره‌سازی" value={4.2} max={10} format={(n) => `${n} گیگابایت`} />
<Meter label="سهمیهٔ پیامک این ماه" value={8600} max={10000} />
<Meter label="کاربران پلن تیمی" value={49} max={50} />
```

فرق آن با `Progress`: نوار پیشرفت برای کاری است که در حال انجام است؛ گیج برای اندازه‌ای است که ثابت است، مثل میزان مصرف. از ۸۰٪ رنگ هشدار و از ۹۵٪ رنگ بحرانی می‌گیرد و وضعیت با متن و آیکون هم گفته می‌شود.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| label | ReactNode | — | نام گیج |
| value / max | number | — / 100 | — |
| warning / critical | number | ۸۰٪ / ۹۵٪ max | آستانهٔ هشدار و بحرانی |
| format | (n: number) => string | ارقام فارسی | قالب مقدار |
| labels | { ok?, warning?, critical?, of? } | — | متن وضعیت‌ها |

## دسترس‌پذیری

`role="meter"` با `aria-valuetext` کامل («۸٬۶۰۰ از ۱۰٬۰۰۰، ۸۶٪، نزدیک به سقف»). وضعیت فقط با رنگ نشان داده نمی‌شود.

---

# انتخاب چندتایی (MultiSelect)

URL: https://kashi.sepantapouya.com/docs/components/multi-select/

انتخاب چند گزینه از یک فهرست بلند با جستجو، مثل مسئولان پروژه یا برچسب‌های یک محصول.

```tsx
import { MultiSelect } from "@kashi-ui/react";
```

## نمونه

```tsx
<MultiSelect label="مسئولان پروژه" options={team} value={owners} onChange={setOwners}
  max={3} placeholder="جستجوی همکار" name="owners" />
```

همان گزینه‌ها و جستجوی `Combobox` را دارد (یکدست‌سازی «ي» و «ی»، توضیح و آیکون). انتخاب‌ها به‌شکل برچسب داخل فیلد نمایش داده می‌شوند و با رسیدن به `max`، بقیهٔ گزینه‌ها غیرفعال می‌شوند. برای وارد کردن مقدار آزاد، که در فهرست نیست، `TagInput` مناسب‌تر است.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| options | ComboboxOption[] | — | مثل Combobox |
| value / defaultValue | string[] | [] | مقدارهای انتخاب‌شده |
| onChange | (value: string[]) => void | — | — |
| max | number | — | بیشترین تعداد انتخاب |
| name | string | — | یک فیلد پنهان برای هر مقدار |
| labels | { remove?, selected?, max?, clear? } | — | متن‌های صفحه‌خوان |

## کیبورد

| کلید | عمل |
|---|---|
| <kbd>↓</kbd> / <kbd>↑</kbd> | گزینهٔ بعد / قبل |
| <kbd>Enter</kbd> | انتخاب یا لغو انتخاب گزینهٔ فعال |
| <kbd>Backspace</kbd> در فیلد خالی | حذف آخرین برچسب |
| <kbd>Esc</kbd> | بستن فهرست |

## دسترس‌پذیری

الگوی Combobox با `aria-multiselectable`؛ هر گزینه `aria-selected` دارد و تعداد انتخاب‌ها به فیلد وصل است («۲ مورد انتخاب شده»). افزودن و حذف با `aria-live` اعلام می‌شود.

---

# ورودی عدد (NumberInput)

URL: https://kashi.sepantapouya.com/docs/components/number-input/

فیلد عدد با دکمه‌های افزایش و کاهش، محدودهٔ مجاز و ارقام فارسی.

```tsx
import { NumberInput } from "@kashi-ui/react";
```

## نمونه

```tsx
<NumberInput label="تعداد مسافر" min={1} max={9} value={n} onChange={setN} unit="نفر" />
<NumberInput label="بودجه" min={0} step={100_000} defaultValue={1_500_000} thousands unit="تومان" />
```

کاربر می‌تواند با ارقام فارسی یا انگلیسی تایپ کند. هنگام تایپ عدد محدود نمی‌شود تا عدد نیمه‌کاره پاک نشود؛ با خروج از فیلد به محدودهٔ `min` و `max` برمی‌گردد.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | number \| null | null | — |
| onChange | (value: number \| null) => void | — | — |
| min / max | number | — | محدودهٔ مجاز |
| step | number | 1 | گام دکمه‌ها و کلیدهای جهت |
| thousands | boolean | false | جداکنندهٔ هزارگان |
| digits | "fa" \| "latin" | "fa" | ارقام نمایش |
| unit | ReactNode | — | واحد کنار عدد |
| labels | { increment?, decrement? } | «افزایش»، «کاهش» | نام دکمه‌ها |

## کیبورد

| کلید | عمل |
|---|---|
| <kbd>↑</kbd> / <kbd>↓</kbd> | یک گام بیشتر / کمتر |
| <kbd>PageUp</kbd> / <kbd>PageDown</kbd> | ده گام |
| <kbd>Home</kbd> / <kbd>End</kbd> | کمینه / بیشینه |

## دسترس‌پذیری

فیلد `role="spinbutton"` با `aria-valuenow`، `aria-valuemin` و `aria-valuemax` است. دکمه‌های + و − از ترتیب Tab بیرون‌اند (کلیدهای جهت همان کار را می‌کنند) و در مرز محدوده غیرفعال می‌شوند.

---

# صفحه‌بندی (Pagination)

URL: https://kashi.sepantapouya.com/docs/components/pagination/

پیمایش بین صفحه‌های یک فهرست، با ارقام فارسی و «…» برای صفحه‌های زیاد.

```tsx
import { Pagination } from "@kashi-ui/react";
```

## نمونه

```tsx
const [page, setPage] = useState(4);

<Pagination page={page} total={12} onChange={setPage} summary="صفحهٔ ۴ از ۱۲" />

// با لینک (بهتر برای موتورهای جستجو)
<Pagination page={page} total={12} getHref={(p) => `?page=${p}`} />
```

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| page / total | number | — | صفحهٔ فعلی و تعداد کل |
| onChange | (page) => void | — | برای صفحه‌بندی با دکمه |
| getHref | (page) => string | — | برای صفحه‌بندی با لینک |
| siblings | number | 1 | تعداد صفحه‌های کنار صفحهٔ فعلی |
| summary | ReactNode | — | متن خلاصه |
| digits | "fa" \| "latin" | "fa" | خط ارقام |
| pageSize / pageSizes / onPageSizeChange | number / number[] / (size) => void | — / [10, 20, 50, 100] | فهرست «در هر صفحه» |
| jumper | boolean | false | فیلد «برو به صفحه» (با onChange) |

## تعداد در هر صفحه و پرش به صفحه

برای جدول‌های بلند: با `onPageSizeChange` فهرست «در هر صفحه» و با `jumper` فیلد «برو به صفحه» نمایش داده می‌شود. فیلد پرش ارقام فارسی و انگلیسی را می‌پذیرد.

```tsx
<Pagination page={page} total={total} onChange={setPage}
  pageSize={size} onPageSizeChange={setSize} pageSizes={[10, 20, 50, 100]}
  jumper summary="۴۱ تا ۶۰ از ۴۸۷" />
```

## دسترس‌پذیری

- داخل `<nav aria-label="صفحه‌بندی">`؛ صفحهٔ فعلی `aria-current="page"` و هر شماره نام کامل «صفحهٔ ۵» دارد.
- «قبلی» در صفحهٔ اول و «بعدی» در صفحهٔ آخر غیرفعال‌اند. فوکوس کیبورد پس از تغییر صفحه حفظ می‌شود.

---

# قدرت رمز عبور (PasswordStrength)

URL: https://kashi.sepantapouya.com/docs/components/password-strength/

نوار قدرت رمز و فهرست شرط‌ها زیر فیلد رمز، با هشدار صفحه‌کلید فارسی.

```tsx
import { PasswordStrength } from "@kashi-ui/react";
```

## نمونه

اگر کاربر با صفحه‌کلید فارسی تایپ کند (مثلاً «سلام» به‌جای «sghl»)، هشدار داده می‌شود؛ اشتباه رایجی که کاربر فارسی‌زبان را پشت در ورود نگه می‌دارد.

```tsx
<Input label="رمز عبور" type="password" value={p} onChange={…} aria-describedby="pw-strength" />
<PasswordStrength id="pw-strength" password={p} />
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| password | string | — | رمز فعلی |
| rules | { label, test }[] | defaultPasswordRules | شرط‌ها؛ امتیاز به نسبت شرط‌های برآورده‌شده |
| showRules | boolean | true | نمایش فهرست شرط‌ها |
| warnPersian | boolean | true | هشدار حروف فارسی در رمز |
| id | string | — | برای aria-describedby فیلد رمز |
| labels | { title?, levels?, persian? } | «ضعیف، متوسط، خوب، قوی» | — |

این کامپوننت فقط راهنمای کاربر است و جایگزین بررسی رمز در سرور نیست.

## دسترس‌پذیری

سطح قدرت با `aria-live` اعلام می‌شود و هر شرط برای صفحه‌خوان «رعایت شده» یا «رعایت نشده» دارد. با `id` و `aria-describedby`، صفحه‌خوان این راهنما را همراه فیلد رمز می‌خواند. نوار رنگی تزئینی است و متن سطح همیشه نمایش داده می‌شود.

---

# پاپ‌اور (Popover)

URL: https://kashi.sepantapouya.com/docs/components/popover/

محتوای تعاملی کوتاه کنار یک دکمه، مثل فیلتر، فرم کوچک یا توضیح.

```tsx
import { Popover } from "@kashi-ui/react";
```

برخلاف `Tooltip`، داخل `Popover` می‌توان دکمه و فیلد گذاشت؛ برخلاف `Dialog`، بقیهٔ صفحه را مسدود نمی‌کند.

## نمونه

```tsx
<Popover title="فیلتر سفارش‌ها" trigger={<Button iconStart={<FilterIcon />}>فیلتر</Button>}>
  <Checkbox label="پرداخت‌شده" />
  …
</Popover>

<Popover placement="bottom-end" aria-label="دربارهٔ کارمزد"
  trigger={<Button variant="tertiary">کارمزد چطور محاسبه می‌شود؟</Button>}>
  کارمزد هر تراکنش ۱٪ مبلغ است.
</Popover>
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| trigger | ReactElement | — | دکمهٔ باز کردن |
| title | ReactNode | — | عنوان و نام پنجره |
| open / onOpenChange | boolean / (open) => void | — | حالت کنترل‌شده |
| placement | "bottom-start" \| "bottom-end" \| "top-start" \| "top-end" | "bottom-start" | جای پنجره |
| aria-label | string | — | نام پنجره وقتی title ندارد |

## دسترس‌پذیری

دکمه `aria-haspopup="dialog"` و `aria-expanded` می‌گیرد. با باز شدن، فوکوس به اولین عنصر داخل می‌رود؛ <kbd>Esc</kbd> می‌بندد و فوکوس را به دکمه برمی‌گرداند. کلیک بیرون یا رفتن فوکوس به بیرون هم پنجره را می‌بندد.

---

# نوار پیشرفت (Progress, Spinner)

URL: https://kashi.sepantapouya.com/docs/components/progress/

نمایش پیشرفت یک کار طولانی، به‌همراه اسپینر برای انتظارهای کوتاه.

```tsx
import { Progress, Spinner } from "@kashi-ui/react";
```

## نمونه

```tsx
<Progress value={35} label="آپلود گزارش.pdf" showValue />
<Progress value={100} tone="success" label="پشتیبان‌گیری" showValue size="sm" />
<Progress aria-label="در حال پردازش" size="sm" />   // بدون value: نامعین
<Spinner size="sm" />
```

## دایره‌ای

```tsx
<Progress variant="circular" value={72} showValue aria-label="پیشرفت پروژه" />
<Progress variant="circular" size="sm" aria-label="در حال پردازش" />
```

`variant="circular"` با همان `value`، `size`، `tone` و `showValue`. متغیرهای CSS: `--k-progress-height`، `--k-progress-color`، `--k-progress-ring-size`.

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | number | — | مقدار؛ بدون آن نوار نامعین است |
| max | number | 100 | حداکثر |
| label | ReactNode | — | برچسب؛ اگر نمی‌دهید aria-label بدهید |
| showValue | boolean | false | نمایش درصد |
| size | "sm" \| "md" \| "lg" | "md" | ضخامت |
| tone | "brand" \| "success" \| "warning" \| "error" | "brand" | رنگ |

## دسترس‌پذیری

- `role="progressbar"` با `aria-valuenow` و `aria-valuetext` فارسی («۳۵٪»)؛ در حالت نامعین `aria-valuenow` حذف می‌شود.
- اسپینر `role="status"` با متن «در حال بارگذاری» برای صفحه‌خوان دارد. با `prefers-reduced-motion` انیمیشن‌ها کند یا متوقف می‌شوند.

---

# رادیو

URL: https://kashi.sepantapouya.com/docs/components/radio/

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

```tsx
```

## فهرست

```tsx
<RadioGroup label="روش ارسال" name="shipping" defaultValue="post">
  <Radio value="post" label="پست پیشتاز" description="۳ تا ۵ روز کاری" />
  <Radio value="courier" label="پیک" description="همان روز، فقط تهران" />
  <Radio value="pickup" label="تحویل حضوری" disabled />
</RadioGroup>
```

## افقی

```tsx
<RadioGroup label="اندازه" variant="inline" name="size" defaultValue="m">
  <Radio value="s" label="کوچک" />
  <Radio value="m" label="متوسط" />
  <Radio value="l" label="بزرگ" />
</RadioGroup>
```

## کارت‌های قابل‌انتخاب

برای گزینه‌هایی که توضیح بیشتری لازم دارند، مثل انتخاب پلن.

```tsx
<RadioGroup label="پلن اشتراک" variant="cards" value={plan} onChange={setPlan}>
  <Radio value="basic" label="پایه" description="۱ کاربر · ۹۰ هزار تومان در ماه" />
  <Radio value="pro" label="حرفه‌ای" description="تا ۲۰ کاربر · ۴۹۰ هزار تومان در ماه" />
  <Radio value="org" label="سازمانی" description="کاربر نامحدود · تماس بگیرید" />
</RadioGroup>
```

## ویژگی‌های RadioGroup

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| label | ReactNode | — | عنوان گروه (legend) — الزامی |
| name | string | خودکار | نام فیلد فرم |
| value / defaultValue | string | — | گزینهٔ انتخاب‌شده |
| onChange | (value: string) => void | — | با تغییر انتخاب |
| variant | "list" \| "inline" \| "cards" | "list" | چیدمان |
| hint / error | ReactNode | — | راهنما و خطای گروه |
| required / disabled | boolean | false | الزامی یا غیرفعال کردن کل گروه |

## دسترس‌پذیری

- گروه در `<fieldset>` با `<legend>` است؛ صفحه‌خوان عنوان گروه را پیش از هر گزینه می‌خواند.
- رادیوها بومی‌اند: <kbd>Tab</kbd> وارد گروه می‌شود و کلیدهای جهت‌دار بین گزینه‌ها جابه‌جا می‌کنند.
- اگر کاربر باید چند گزینه انتخاب کند، از [چک‌باکس](/docs/components/checkbox/) استفاده کنید.

---

# امتیاز ستاره‌ای (Rating)

URL: https://kashi.sepantapouya.com/docs/components/rating/

دریافت یا نمایش امتیاز ۱ تا ۵، با نیم‌ستاره در حالت نمایش.

```tsx
import { Rating } from "@kashi-ui/react";
```

## نمونه

```tsx
<Rating label="امتیاز شما به این محصول" value={v} onChange={setV} showValue />

<Rating value={4.5} readOnly size="sm" showValue />
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | number | 0 | امتیاز؛ در readOnly اعشار هم می‌پذیرد |
| onChange | (value: number) => void | — | — |
| max | number | 5 | تعداد ستاره‌ها |
| readOnly | boolean | false | فقط نمایش |
| showValue | boolean | false | عدد کنار ستاره‌ها |
| size | "sm" \| "md" \| "lg" | "md" | — |
| label | string | «امتیاز» | نام گروه |
| starLabel | (n, max) => string | «n از max» | نام هر ستاره |

## دسترس‌پذیری

حالت قابل‌انتخاب یک `fieldset` با رادیوهای بومی است: <kbd>←</kbd>/<kbd>→</kbd> امتیاز را عوض می‌کند و هر ستاره نام «۳ از ۵» دارد. حالت فقط‌خواندنی یک تصویر با نام کامل است («امتیاز: ۴٫۵ از ۵») تا صفحه‌خوان ستاره‌ها را یکی‌یکی نخواند.

---

# سگمنت (SegmentedControl)

URL: https://kashi.sepantapouya.com/docs/components/segmented-control/

انتخاب یکی از چند گزینهٔ کوتاه کنار هم، مثل حالت نمایش یا بازهٔ زمانی گزارش.

```tsx
import { SegmentedControl } from "@kashi-ui/react";
```

برای دو تا پنج گزینهٔ کوتاه که نتیجه‌شان بلافاصله دیده می‌شود. برای گزینه‌های بیشتر یا فرم‌ها از `RadioGroup` یا `Select` استفاده کنید؛ برای جابه‌جایی بین محتواهای مختلف از `Tabs`.

## نمونه

```tsx
<SegmentedControl aria-label="نمایش" value={view} onChange={setView} options={[
  { value: "list", label: "فهرست", icon: <ListIcon /> },
  { value: "grid", label: "کارت", icon: <GridIcon /> },
]} />

<SegmentedControl aria-label="بازهٔ زمانی" size="sm" defaultValue="30" options={[
  { value: "1", label: "امروز" }, { value: "7", label: "۷ روز" },
  { value: "30", label: "۳۰ روز" }, { value: "365", label: "یک سال" },
]} />
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| options | { value, label, icon?, disabled?, aria-label? }[] | — | گزینه‌ها |
| value / defaultValue | string | اولین گزینهٔ فعال | — |
| onChange | (value: string) => void | — | — |
| aria-label / aria-labelledby | string | — | نام گروه (الزامی) |
| size | "sm" \| "md" | "md" | هم‌قد دکمه‌ها: ۳۶ و ۴۰ پیکسل |
| block | boolean | false | تمام‌عرض با بخش‌های هم‌اندازه |
| name | string | خودکار | نام رادیوها برای ارسال فرم |

## دسترس‌پذیری

روی رادیوهای بومی ساخته شده: <kbd>Tab</kbd> وارد گروه می‌شود و <kbd>←</kbd>/<kbd>→</kbd> گزینه را عوض می‌کند. گروه `role="radiogroup"` با نام دارد و گزینهٔ انتخاب‌شده با سطح برجسته و سایه، نه فقط رنگ، مشخص است. اگر گزینه فقط آیکون دارد، `aria-label` بدهید.

---

# سلکت (Select)

URL: https://kashi.sepantapouya.com/docs/components/select/

انتخاب یک گزینه از فهرست بلند، روی select بومی مرورگر.

```tsx
import { Select } from "@kashi-ui/react";
```

## نمونه

```tsx
<Select
  label="استان"
  placeholder="انتخاب کنید"
  hint="برای محاسبهٔ هزینهٔ ارسال"
  options={[
    { value: "thr", label: "تهران" },
    { value: "isf", label: "اصفهان" },
    { value: "frs", label: "فارس" },
    { value: "krm", label: "کرمان" },
  ]}
/>
```

## خطا و اندازه‌ها

```tsx
<Select label="نقش" error="یک نقش انتخاب کنید." placeholder="انتخاب کنید" required>
  <option value="admin">مدیر</option>
  <option value="editor">ویرایشگر</option>
</Select>
<Select label="مرتب‌سازی" size="sm" defaultValue="new">
  <option value="new">جدیدترین</option>
  <option value="price">ارزان‌ترین</option>
</Select>
```

## چرا select بومی؟

فهرست بومی مرورگر در گوشی انتخاب‌گر سیستم‌عامل را باز می‌کند (که برای انگشت ساخته شده)، با صفحه‌خوان‌ها بی‌نقص کار می‌کند و در فرم‌ها بدون کد اضافه ارسال می‌شود. کاشی فقط ظاهر آن را هماهنگ می‌کند.

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| label / hint / error | ReactNode | — | مثل Input |
| placeholder | string | — | گزینهٔ خالی اول که قابل‌انتخاب نیست |
| options | { value, label, disabled? }[] | — | گزینه‌ها؛ یا <option> به‌عنوان children |
| size | "sm" \| "md" \| "lg" | "md" | ارتفاع |

---

# سایدبار (SideNav)

URL: https://kashi.sepantapouya.com/docs/components/side-nav/

منوی کناری پنل مدیریت با گروه‌ها، زیرمنو، نشان و حالت جمع‌شده.

```tsx
import { SideNav } from "@kashi-ui/react";
```

## نمونه

```tsx
<SideNav
  collapsed={collapsed}
  header={<Logo />}
  sections={[
    { items: [
      { label: "داشبورد", href: "/", icon: <HomeIcon />, current: true },
      { label: "صندوق ورودی", href: "/inbox", icon: <InboxIcon />, badge: <Badge size="sm" tone="brand">۱۲</Badge> },
      { label: "گزارش‌ها", icon: <ChartIcon />, items: [
        { label: "فروش", href: "/reports/sales" },
        { label: "کاربران", href: "/reports/users" },
      ] },
    ] },
    { label: "مدیریت", items: [{ label: "تیم", href: "/team", icon: <UsersIcon /> }] },
  ]}
  footer={<UserMenu />}
/>
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| sections | { label?, items: SideNavItem[] }[] | — | گروه‌های منو |
| SideNavItem | { label, href?, icon?, badge?, current?, onClick?, items? } | — | با items، زیرمنوی باز و بسته‌شونده |
| collapsed | boolean | false | فقط آیکون‌ها |
| header / footer | ReactNode | — | بالا و پایین منو |
| aria-label | string | «اصلی» | نام ناحیهٔ ناوبری |

عرض با متغیر `--k-sidenav-width` (پیش‌فرض ۱۷rem) عوض می‌شود.

## دسترس‌پذیری

ناحیهٔ `<nav>` با نام «اصلی». صفحهٔ فعلی `aria-current="page"` دارد و زیرمنویی که صفحهٔ فعلی در آن است از اول باز است. والد زیرمنو دکمه‌ای با `aria-expanded` است. در حالت جمع‌شده، نام هر مورد با `aria-label` و `title` حفظ می‌شود.

---

# اسکلتون (Skeleton)

URL: https://kashi.sepantapouya.com/docs/components/skeleton/

جای خالی محتوا هنگام بارگذاری؛ از پرش صفحه جلوگیری می‌کند.

```tsx
import { Skeleton } from "@kashi-ui/react";
```

## نمونه

```tsx
<div aria-busy="true" aria-label="در حال بارگذاری">
  <Skeleton circle width={40} />
  <Skeleton lines={2} />
  <Skeleton height={120} />
  <Skeleton lines={3} />
</div>
```

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| width / height | string \| number | 100% / 1em | اندازه |
| circle | boolean | false | شکل دایره |
| lines | number | — | چند خط متن؛ خط آخر کوتاه‌تر است |

## دسترس‌پذیری

اسکلت تزئینی است (`aria-hidden`). روی ظرف بارگذاری `aria-busy="true"` و یک `aria-label` بگذارید تا صفحه‌خوان بداند محتوا در راه است. با `prefers-reduced-motion` درخشش متوقف می‌شود.

---

# اسلایدر (Slider)

URL: https://kashi.sepantapouya.com/docs/components/slider/

انتخاب یک عدد یا یک بازه با کشیدن، مثل صدا، روشنایی یا بازهٔ قیمت.

```tsx
import { Slider } from "@kashi-ui/react";
```

## مقدار تکی و بازه

برای بازه، به‌جای عدد یک آرایهٔ دوتایی بدهید؛ دستگیره‌ها از روی هم رد نمی‌شوند.

```tsx
<Slider label="روشنایی" value={v} onChange={setV} format={(n) => `${toFaDigits(n)}٪`} />

<Slider label="قیمت" min={0} max={10_000_000} step={500_000}
  value={price} onChange={setPrice}
  format={(n) => `${formatNumber(n)} تومان`}
  marks={[0, 5_000_000, 10_000_000]} />
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | number \| [number, number] | — | آرایه برای بازه |
| onChange | (value) => void | — | — |
| min / max / step | number | 0 / 100 / 1 | — |
| format | (n: number) => string | formatNumber | قالب نمایش و متن صفحه‌خوان |
| showValue | boolean | true | مقدار کنار برچسب |
| marks | number[] | — | برچسب‌های زیر نوار |
| name | string | — | در بازه: name_min و name_max |
| labels | { from?, to?, separator? } | «حداقل»، «حداکثر» | — |

## دسترس‌پذیری

روی `<input type="range">` بومی ساخته شده، پس همهٔ کلیدهای استاندارد (<kbd>←</kbd>/<kbd>→</kbd>، <kbd>PageUp</kbd>، <kbd>Home</kbd>/<kbd>End</kbd>) کار می‌کنند. `aria-valuetext` مقدار قالب‌بندی‌شده را می‌خواند («۲٬۰۰۰٬۰۰۰ تومان») و در بازه، هر دستگیره نام جدا دارد: «حداقل قیمت» و «حداکثر قیمت».

---

# اسپلیتر (Splitter)

URL: https://kashi.sepantapouya.com/docs/components/splitter/

دو پنل کنار هم یا زیر هم که کاربر اندازه‌شان را با کشیدن مرز تغییر می‌دهد.

```tsx
import { Splitter } from "@kashi-ui/react";
```

## نمونه

```tsx
<Splitter label="اندازهٔ فهرست فایل‌ها" defaultSize={35} height="16rem">
  <FileList />
  <Preview />
</Splitter>
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| children | [ReactNode, ReactNode] | — | پنل ابتدا و پنل انتها |
| orientation | "horizontal" \| "vertical" | "horizontal" | کنار هم یا زیر هم |
| size / defaultSize | number | 40 | اندازهٔ پنل اول به درصد |
| onSizeChange | (percent) => void | — | برای ذخیرهٔ اندازه |
| min / max | number | 15 / 85 | محدودهٔ درصد |
| label | string | «تغییر اندازهٔ پنل‌ها» | نام دستگیره |

## دسترس‌پذیری

دستگیره یک `role="separator"` فوکوس‌پذیر با `aria-valuenow` است. با ←→ (یا ↑↓ در حالت عمودی) پنج درصد، و با <kbd>Home</kbd>/<kbd>End</kbd> به کمینه و بیشینه می‌رود. دوبار کلیک اندازهٔ اولیه را برمی‌گرداند.

---

# کارت آمار (StatCard, StatGrid)

URL: https://kashi.sepantapouya.com/docs/components/stat-card/

نمایش شاخص‌های کلیدی (KPI) داشبورد با روند تغییر.

```tsx
import { StatCard, StatGrid } from "@kashi-ui/react";
```

## نمونه

```tsx
<StatGrid>
  <StatCard label="فروش این ماه" value="۱۸۴٬۵۰۰٬۰۰۰" unit="تومان" icon={<WalletIcon />}
    change={12.4} caption="نسبت به ماه قبل">
    <Sparkline points={…} />
  </StatCard>
  <StatCard label="کاربران فعال" value="۳٬۸۲۰" unit="نفر" change={-2} caption="نسبت به هفتهٔ قبل" />
  <StatCard label="نرخ خطا" value="۰٫۸٪" change={-35} invertTrend />
</StatGrid>
```

## ساده

```tsx
<StatCard label="سفارش‌های امروز" value="۴۸" />
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| label | ReactNode | — | نام شاخص |
| value | ReactNode | — | مقدار قالب‌بندی‌شده |
| unit | ReactNode | — | واحد کوچک کنار عدد، مثل «تومان» |
| icon | ReactNode | — | آیکون تزئینی |
| change | number | — | درصد تغییر؛ منفی یعنی کاهش |
| invertTrend | boolean | false | وقتی کاهش خوب است (رنگ سبز برای کاهش) |
| caption | ReactNode | — | متن کنار روند |
| children | ReactNode | — | نمودار کوچک یا محتوای اضافه |

`StatGrid` کارت‌ها را در ستون‌های خودکار (حداقل ۱۴rem) می‌چیند.

عدد با ارقام فارسی و عرض طبیعی نمایش داده می‌شود (نه `tabular-nums`)، چون ارقام فارسی با عرض ثابت از هم فاصله می‌گیرند. اندازهٔ عدد با `--k-stat-value-size` عوض می‌شود.

## دسترس‌پذیری

جهت روند فقط با رنگ و فلش نشان داده نمی‌شود: صفحه‌خوان متن کامل را می‌خواند («۱۲٫۴٪ افزایش»). رنگ روند بر اساس خوب یا بد بودن است، نه جهت.

---

# استپر (Stepper)

URL: https://kashi.sepantapouya.com/docs/components/stepper/

نشان دادن مراحل یک فرایند چندبخشی، مثل خرید یا ثبت‌نام.

```tsx
import { Stepper } from "@kashi-ui/react";
```

## افقی

```tsx
<Stepper current={1} steps={[
  { title: "سبد خرید", description: "۳ کالا" },
  { title: "اطلاعات ارسال", description: "آدرس و زمان" },
  { title: "پرداخت" },
  { title: "تأیید" },
]} />
```

## عمودی

```tsx
<Stepper orientation="vertical" current={2} steps={[…]} />
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| steps | { title, description? }[] | — | مراحل |
| current | number | — | مرحلهٔ فعلی از صفر |
| orientation | "horizontal" \| "vertical" | "horizontal" | جهت |
| label / labels | string / { complete?, current? } | «مراحل» | متن‌های صفحه‌خوان |

## دسترس‌پذیری

فهرست `<ol>` با نام «مراحل»؛ مرحلهٔ فعلی `aria-current="step"` دارد و صفحه‌خوان وضعیت هر مرحله را می‌خواند («ارسال، مرحلهٔ فعلی»، «سبد خرید، انجام شده»). وضعیت فقط با رنگ نمایش داده نمی‌شود: مراحل انجام‌شده تیک دارند.

---

# سوییچ (Switch)

URL: https://kashi.sepantapouya.com/docs/components/switch/

برای روشن و خاموش کردن تنظیمی که بلافاصله اعمال می‌شود.

```tsx
import { Switch } from "@kashi-ui/react";
```

## پایه

در راست‌به‌چپ، دستگیرهٔ سوییچ در حالت روشن به سمت چپ می‌رود؛ این رفتار خودکار است.

```tsx
<Switch label="اعلان‌های ایمیلی" description="خلاصهٔ هفتگی فعالیت‌ها" defaultChecked />
<Switch label="حالت تعطیلات" />
```

## اندازه‌ها و حالت‌ها

```tsx
<Switch label="کوچک" size="sm" defaultChecked />
<Switch label="متوسط" defaultChecked />
<Switch label="بزرگ" size="lg" defaultChecked />
<Switch label="غیرفعال" disabled />
```

## سوییچ یا چک‌باکس؟

- **سوییچ:** تغییر فوراً اعمال می‌شود، مثل روشن کردن اعلان‌ها.
- **چک‌باکس:** انتخاب پس از ارسال فرم اعمال می‌شود، مثل پذیرفتن قوانین.

## فهرست تنظیمات

با `labelPosition="start"` برچسب پیش از کنترل می‌آید و کنترل به انتهای ردیف می‌رود؛ چیدمان رایج صفحه‌های تنظیمات. برای Checkbox هم کار می‌کند.

```tsx
<Switch labelPosition="start" label="اعلان‌های ایمیلی" description="خلاصهٔ هفتگی فعالیت‌ها" />
```

**ویژگی‌های جدید**

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| labelPosition | "start" \| "end" | "end" | جای برچسب (Switch و Checkbox) |
| classNames | { root, control, label, description } | — | کلاس دلخواه برای هر بخش |

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| label | ReactNode | — | برچسب کنار سوییچ |
| description | ReactNode | — | توضیح زیر برچسب |
| size | "sm" \| "md" \| "lg" | "md" | اندازه |
| invalid | boolean | false | حالت خطا |

## متغیرهای CSS

| متغیر CSS | پیش‌فرض | توضیح |
|---|---|---|
| --k-switch-width | 2.25rem | عرض |
| --k-switch-height | 1.25rem | ارتفاع |
| --k-switch-track-on | var(--k-bg-brand) | رنگ مسیر در حالت روشن |
| --k-switch-track-off | var(--k-border-input) | رنگ مسیر در حالت خاموش |
| --k-switch-thumb | #fff | رنگ دستگیره |

## دسترس‌پذیری

- روی `<input type="checkbox" role="switch">` ساخته شده؛ صفحه‌خوان آن را «سوییچ، روشن» یا «خاموش» اعلام می‌کند.
- مسیر خاموش کنتراست حداقل ۳ به ۱ با پس‌زمینه دارد.

---

# جدول داده (DataTable)

URL: https://kashi.sepantapouya.com/docs/components/table/

جدول با مرتب‌سازی، انتخاب ردیف‌ها، ستون‌های عددی و حالت خالی.

```tsx
import { DataTable } from "@kashi-ui/react";
```

## نمونه

روی سرستون «مشتری» یا «مبلغ» بزنید تا مرتب شود. نام‌ها به ترتیب الفبای فارسی مرتب می‌شوند.

```tsx
<DataTable
  caption="تراکنش‌های اخیر"
  description="آخرین پرداخت‌های مشتریان در این ماه"
  rows={transactions}
  getRowId={(r) => r.id}
  selectable
  selected={selected}
  onSelectedChange={setSelected}
  defaultSort={{ key: "amount", direction: "descending" }}
  columns={[
    { key: "customer", header: "مشتری", sortable: true },
    { key: "date", header: "تاریخ" },
    { key: "status", header: "وضعیت", render: (r) => <Badge tone="success" dot>…</Badge> },
    { key: "amount", header: "مبلغ (تومان)", sortable: true, numeric: true,
      render: (r) => formatNumber(r.amount) },
  ]}
/>
```

## بارگذاری، راه‌راه، سرستون ثابت و صفحه‌بندی

روی «بارگذاری دوباره» بزنید تا ردیف‌های اسکلت را ببینید؛ روی هر ردیف بزنید تا رویداد کلیک را ببینید. جدول را اسکرول کنید: سرستون ثابت می‌ماند.

```tsx
<DataTable
  …
  striped
  stickyHeader
  maxHeight="16rem"
  loading={isLoading ? 4 : false}
  onRowClick={(row) => open(row)}
  columns={[
    { key: "date", header: "تاریخ", hideBelow: "sm" },
    { key: "status", header: "وضعیت", align: "center" },
    …
  ]}
  footer={<Pagination page={page} total={8} onChange={setPage} />}
/>
```

**ویژگی‌های جدید**

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| striped | boolean | false | ردیف‌های راه‌راه |
| stickyHeader / maxHeight | boolean / string | — | سرستون ثابت هنگام اسکرول |
| loading | boolean \| number | false | ردیف‌های اسکلت؛ عدد = تعداد ردیف |
| onRowClick | (row) => void | — | کلیک روی ردیف (کلیک روی دکمه و لینک داخل ردیف را نمی‌گیرد) |
| footer | ReactNode | — | محتوای پایین جدول |
| align / hideBelow / className (ستون) | — | — | چینش، پنهان شدن در موبایل، کلاس خانه‌ها |
| classNames | { root, table, row, cell, header, footer } | — | کلاس دلخواه برای هر بخش |

متغیرهای CSS: `--k-table-radius`، `--k-table-cell-px`، `--k-table-cell-py`، `--k-table-header-bg`، `--k-table-stripe`، `--k-table-row-hover`.

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| columns | Column[] | — | ستون‌ها: key، header، render، sortable، sortValue، numeric، width |
| rows | T[] | — | ردیف‌ها |
| getRowId | (row) => string | — | شناسهٔ یکتای هر ردیف |
| caption | ReactNode | — | عنوان جدول — الزامی، برای صفحه‌خوان |
| description / hideCaption | ReactNode / boolean | — | توضیح زیر عنوان / پنهان کردن عنوان از دید |
| selectable | boolean | false | ستون انتخاب با «انتخاب همه» |
| selected / onSelectedChange | string[] | — | ردیف‌های انتخاب‌شده |
| sort / defaultSort / onSortChange | { key, direction } \| null | — | مرتب‌سازی؛ کنترل‌شده برای مرتب‌سازی سمت سرور |
| empty | ReactNode | — | محتوای جدول خالی، مثلاً یک EmptyState |
| compact | boolean | false | ردیف‌های فشرده |

## دسترس‌پذیری

- جدول واقعی HTML با `<caption>` و سرستون‌های `scope="col"`؛ صفحه‌خوان‌ها می‌توانند بین خانه‌ها پیمایش کنند.
- سرستون مرتب‌شده `aria-sort` دارد و مرتب‌سازی با یک دکمهٔ واقعی انجام می‌شود.
- چک‌باکس هر ردیف نام اختصاصی می‌گیرد (`labels.selectRow`)، مثل «انتخاب تراکنش سارا احمدی».
- ظرف جدول در صفحه‌های باریک اسکرول افقی دارد و با کیبورد (Tab) قابل‌اسکرول است.

---

# تب‌ها (Tabs, TabList, Tab, TabPanel)

URL: https://kashi.sepantapouya.com/docs/components/tabs/

نمایش بخش‌های مرتبط یک محتوا در یک فضا، با سه سبک و پیمایش کامل کیبورد.

```tsx
import { Tabs, TabList, Tab, TabPanel } from "@kashi-ui/react";
```

## خطی

```tsx
<Tabs defaultValue="account">
  <TabList aria-label="تنظیمات">
    <Tab value="account">حساب کاربری</Tab>
    <Tab value="security">امنیت</Tab>
    <Tab value="billing">پرداخت <Badge tone="brand" size="sm">۲</Badge></Tab>
    <Tab value="api" disabled>API</Tab>
  </TabList>
  <TabPanel value="account">…</TabPanel>
  <TabPanel value="security">…</TabPanel>
  <TabPanel value="billing">…</TabPanel>
</Tabs>
```

## قرصی

```tsx
<Tabs defaultValue="account" variant="pill">…</Tabs>
```

## چندبخشی

```tsx
<Tabs defaultValue="account" variant="segmented">…</Tabs>
```

## کیبورد

| کلید | عمل |
|---|---|
| <kbd>Tab</kbd> | ورود به زبانهٔ فعال، سپس رفتن به محتوای پنل |
| <kbd>←</kbd> / <kbd>→</kbd> | زبانهٔ بعد / قبل (در راست‌به‌چپ) و فعال‌سازی آن |
| <kbd>Home</kbd> / <kbd>End</kbd> | اولین / آخرین زبانه |

## عمودی

برای صفحه‌های تنظیمات؛ کلیدهای ↑ و ↓ بین زبانه‌ها جابه‌جا می‌کنند. در صفحه‌های باریک خودکار افقی می‌شود.

```tsx
<Tabs defaultValue="profile" orientation="vertical">
  <TabList aria-label="تنظیمات حساب">…</TabList>
  …
</Tabs>
```

**ویژگی‌های جدید**

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| orientation | "horizontal" \| "vertical" | "horizontal" | جهت؛ aria-orientation و کلیدهای پیمایش هم تغییر می‌کنند |
| size | "sm" \| "md" | "md" | اندازه |

متغیرهای CSS: `--k-tab-height`، `--k-tab-radius`، `--k-tabs-gap`، `--k-tabs-indicator`، `--k-tabs-list-width`.

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | string | — | زبانهٔ فعال (Tabs) |
| onChange | (value: string) => void | — | با تغییر زبانه |
| variant | "line" \| "pill" \| "segmented" | "line" | سبک |
| block | boolean | false | زبانه‌ها تمام عرض را پر کنند |
| aria-label | string | — | نام فهرست زبانه‌ها (TabList) — الزامی |
| value | string | — | شناسهٔ زبانه و پنل متناظر (Tab و TabPanel) |

نشانگر زبانهٔ فعال (خط زیر زبانه، یا پس‌زمینه در گونه‌های قرصی و چندبخشی) با تغییر زبانه به‌نرمی جابه‌جا می‌شود؛ با تنظیم «کاهش حرکت» در سیستم، بدون انیمیشن.

## دسترس‌پذیری

- الگوی Tabs در WAI-ARIA: `tablist`، `tab` و `tabpanel` با اتصال `aria-controls` و `aria-labelledby`.
- فقط زبانهٔ فعال در ترتیب Tab است؛ زبانه‌های غیرفعال (`disabled`) در پیمایش رد می‌شوند.
- برای ناوبری بین صفحه‌ها از زبانه استفاده نکنید؛ لینک‌ها مناسب‌ترند.

---

# ورودی تگ (TagInput)

URL: https://kashi.sepantapouya.com/docs/components/tag-input/

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

```tsx
import { TagInput } from "@kashi-ui/react";
```

## نمونه

```tsx
const [tags, setTags] = useState(["طراحی", "React"]);

<TagInput label="مهارت‌ها" value={tags} onChange={setTags} max={5}
  hint="با Enter یا ویرگول جدا کنید؛ حداکثر ۵ مورد." />
```

با <kbd>Enter</kbd>، ویرگول انگلیسی و ویرگول فارسی «،» برچسب ساخته می‌شود؛ متن چسبانده‌شده هم جدا می‌شود. <kbd>Backspace</kbd> در فیلد خالی آخرین برچسب را حذف می‌کند.

## اعتبارسنجی

```tsx
<TagInput label="گیرندگان" tone="neutral"
  validate={(t) => (isEmail(t) ? undefined : "این ایمیل معتبر نیست.")} />
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | string[] | [] | برچسب‌ها |
| onChange | (tags: string[]) => void | — | — |
| separators | string[] | ["Enter", ",", "،"] | کلیدهای جداکننده |
| validate | (tag) => string \| undefined | — | پیام خطا برای برچسب نامعتبر |
| max | number | — | بیشترین تعداد |
| allowDuplicates | boolean | false | — |
| tone | BadgeTone | "brand" | رنگ برچسب‌ها |
| name | string | — | یک فیلد پنهان برای هر برچسب |

## دسترس‌پذیری

هر برچسب دکمهٔ حذف با نام «حذف React» دارد. افزودن، حذف و خطاها (تکراری، بیش از حد مجاز) با `aria-live` اعلام می‌شوند و پیام خطا به فیلد وصل است.

---

# تایم‌لاین (Timeline)

URL: https://kashi.sepantapouya.com/docs/components/timeline/

نمایش رویدادها و فعالیت‌ها به ترتیب زمان، مثل تاریخچهٔ سفارش یا فعالیت تیم.

```tsx
import { Timeline } from "@kashi-ui/react";
```

## نمونه

```tsx
<Timeline items={[
  { title: <><strong>سارا محمدی</strong> سفارش را تأیید کرد</>, time: new Date(…), tone: "success", icon: <CheckIcon /> },
  { title: <><strong>رضا کریمی</strong> نظر گذاشت</>, time: new Date(…), icon: <Avatar name="رضا کریمی" size="sm" />,
    content: "بسته‌بندی را دوبل کنید؛ کالا شکستنی است." },
  { title: "سفارش ثبت شد", time: "۱۲ آبان، ۱۰:۲۰" },
]} />
```

اگر `time` از نوع `Date` باشد، به شکل نسبی («۵ دقیقه پیش») با `RelativeTime` نمایش داده و خودکار به‌روز می‌شود؛ متن هم می‌توانید بدهید.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| items | { id?, title, time?, icon?, tone?, content? }[] | — | رویدادها به ترتیب نمایش |
| items[].tone | "neutral" \| "brand" \| "success" \| "error" | "neutral" | رنگ نشانگر |
| digits | "fa" \| "latin" | "fa" | ارقام زمان نسبی |

## دسترس‌پذیری

فهرست مرتب `<ol>` است، پس صفحه‌خوان تعداد و ترتیب رویدادها را می‌گوید. نشانگرها تزئینی‌اند و زمان در عنصر `<time>` با تاریخ دقیق است.

---

# توست (Toaster)

URL: https://kashi.sepantapouya.com/docs/components/toast/

پیام کوتاه و موقت پس از یک عمل، مثل «ذخیره شد»؛ با توقف هنگام hover و امکان واگرد.

```tsx
import { Toaster, toast } from "@kashi-ui/react";
```

`<Toaster />` را یک بار در ریشهٔ برنامه بگذارید؛ سپس از هر جای برنامه `toast()` را صدا بزنید.

## نمونه

```tsx
toast.success("تغییرات ذخیره شد", { description: "…" });
toast.error("پرداخت ناموفق بود");
toast.warning("اتصال اینترنت ناپایدار است");
toast({
  title: "پیام بایگانی شد",
  action: { label: "واگرد", onClick: () => restore() },
});

// در ریشهٔ برنامه
<Toaster />
```

## رفتار

- **زمان:** پیش‌فرض ۵ ثانیه. نوار پایین زمان باقی‌مانده را نشان می‌دهد و با hover یا فوکوس متوقف می‌شود.
- **با عمل:** اعلانی که دکمه دارد (مثل «واگرد») خودکار بسته نمی‌شود تا کاربر فرصت کافی داشته باشد.
- **بستن:** با دکمهٔ بستن یا <kbd>Esc</kbd> وقتی فوکوس روی اعلان است.

## کار زمان‌بر و جایگاه

`toast.promise` اعلان «در حال ذخیره…» را نشان می‌دهد و پس از پایان کار، **همان اعلان** را به پیام موفقیت یا خطا تغییر می‌دهد. (در این نمونه از هر چهار بار، حدود یک بار خطا شبیه‌سازی می‌شود.)

```tsx
toast.promise(saveFiles(), {
  loading: "در حال ذخیره…",
  success: (n) => `${n} فایل ذخیره شد`,
  error: (e) => `ذخیره نشد: ${e.message}`,
});

<Toaster placement="top-center" max={3} />
```

**ویژگی‌های جدید**

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| placement (Toaster) | "top-start" \| "top-center" \| "top-end" \| "bottom-start" \| "bottom-center" \| "bottom-end" | "bottom-end" | جایگاه؛ در RTL «end» سمت چپ است |
| max (Toaster) | number | 5 | بیشترین اعلان هم‌زمان |
| toast.promise | (promise, { loading, success, error }) | — | اعلان یک کار زمان‌بر |
| id (toast) | number \| string | — | با شناسهٔ تکراری، اعلان قبلی به‌روز می‌شود |

## ویژگی‌های toast()

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| title | ReactNode | — | متن اصلی |
| description | ReactNode | — | توضیح |
| tone | "neutral" \| "success" \| "error" \| "warning" \| "info" | "neutral" | رنگ و آیکون |
| duration | number | ۵۰۰۰، یا بی‌نهایت با action | میلی‌ثانیه |
| action | { label, onClick } | — | دکمهٔ عمل |

## دسترس‌پذیری

- ناحیهٔ اعلان‌ها با `aria-live="polite"` از ابتدا در صفحه است تا اعلان‌های جدید بدون جابه‌جایی فوکوس خوانده شوند؛ اعلان خطا با `role="alert"` فوراً خوانده می‌شود.
- توقف زمان هنگام hover و فوکوس و ماندن اعلان‌های دارای عمل، معیار WCAG 2.2.1 (زمان کافی) را برآورده می‌کنند.
- اطلاعات حیاتی را فقط در توست نگذارید؛ ممکن است کاربر آن را نبیند.

---

# تولتیپ (Tooltip)

URL: https://kashi.sepantapouya.com/docs/components/tooltip/

توضیح کوتاه یک کنترل هنگام hover یا فوکوس.

```tsx
import { Tooltip } from "@kashi-ui/react";
```

## نمونه

نشانگر را روی دکمه‌ها ببرید یا با <kbd>Tab</kbd> روی آن‌ها بروید.

```tsx
<Tooltip content="جستجو در همهٔ پروژه‌ها">
  <Button iconOnly aria-label="جستجو"><SearchIcon /></Button>
</Tooltip>

<Tooltip content="ایمیل برای همه قابل‌مشاهده نیست" placement="bottom">
  …
</Tooltip>
```

## چهار جایگاه

```tsx
<Tooltip content="…" placement="start">…</Tooltip>
```

`placement` حالا `"start"` و `"end"` هم می‌پذیرد. متغیرهای CSS: `--k-tooltip-bg`، `--k-tooltip-fg`، `--k-tooltip-max-width`، `--k-tooltip-radius`.

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| content | ReactNode | — | متن راهنما |
| children | ReactElement | — | یک عنصر فوکوس‌پذیر، معمولاً دکمه |
| placement | "top" \| "bottom" | "top" | جایگاه |
| delay | number | 300 | تأخیر نمایش با hover (میلی‌ثانیه)؛ با فوکوس فوری است |

## دسترس‌پذیری

- با `aria-describedby` به عنصر متصل است؛ صفحه‌خوان آن را پس از نام دکمه می‌خواند.
- طبق WCAG 1.4.13: با <kbd>Esc</kbd> بسته می‌شود، نشانگر می‌تواند روی خود راهنما برود بدون اینکه بسته شود، و تا وقتی hover یا فوکوس ادامه دارد می‌ماند.
- تولتیپ **جایگزین برچسب نیست**: دکمهٔ فقط‌آیکون همچنان `aria-label` لازم دارد. اطلاعات ضروری را در آن پنهان نکنید؛ کاربران لمسی آن را نمی‌بینند.

---

# تور معرفی (Tour)

URL: https://kashi.sepantapouya.com/docs/components/tour/

معرفی بخش‌های تازهٔ محصول به کاربر، مرحله به مرحله، با روشن کردن همان بخش.

```tsx
import { Tour } from "@kashi-ui/react";
```

## نمونه

```tsx
<Tour open={open} onOpenChange={setOpen} steps={[
  { target: "#search", title: "جستجوی سریع", content: "نام مشتری یا شمارهٔ سفارش را بنویسید." },
  { target: "#export", title: "خروجی اکسل", content: "فهرست فیلترشده را دانلود کنید." },
]} />
```

راهنما را کوتاه نگه دارید (سه تا پنج مرحله) و همیشه امکان «رد کردن» بدهید. بهتر است فقط یک بار، برای کاربر تازه یا بخش تازه، نمایش داده شود.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| steps | { target, title, content }[] | — | target یک CSS selector است |
| open / onOpenChange | boolean / (open) => void | — | — |
| onFinish | () => void | — | پس از آخرین مرحله |
| labels | { next?, prev?, done?, skip?, step? } | — | متن دکمه‌ها |

## دسترس‌پذیری

هر مرحله یک `role="dialog"` غیرمودال با عنوان و توضیح است و فوکوس به آن می‌رود. <kbd>Esc</kbd> می‌بندد، ←→ بین مرحله‌ها حرکت می‌کند و پس از پایان فوکوس به جای قبلی برمی‌گردد.

---

# نمای درختی (TreeView)

URL: https://kashi.sepantapouya.com/docs/components/tree-view/

نمایش ساختار سلسله‌مراتبی مثل پوشه‌ها، دسته‌بندی محصولات یا نمودار سازمانی.

```tsx
import { TreeView, type TreeNode } from "@kashi-ui/react";
```

## نمونه

```tsx
const items: TreeNode[] = [
  { id: "docs", label: "اسناد", icon: <FolderIcon />, meta: "۳ پوشه", children: [
    { id: "contracts", label: "قراردادها", icon: <FolderIcon />, children: [
      { id: "c1", label: "قرارداد-۱۴۰۵.pdf", icon: <FileIcon />, meta: "۲٫۴ مگابایت" },
    ] },
    { id: "archive", label: "بایگانی", disabled: true },
  ] },
];

<TreeView aria-label="فایل‌ها" items={items} selected={sel} onSelect={setSel}
  defaultExpanded={["docs", "contracts"]} />
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| items | { id, label, icon?, meta?, disabled?, children? }[] | — | گره‌ها |
| selected / defaultSelected | string \| null | null | گره انتخاب‌شده |
| onSelect | (id, node) => void | — | — |
| expanded / defaultExpanded | string[] | [] | شناسهٔ گره‌های باز |
| onExpandedChange | (ids: string[]) => void | — | — |
| aria-label | string | — | نام درخت (الزامی) |

## کیبورد

| کلید | عمل |
|---|---|
| <kbd>↓</kbd> / <kbd>↑</kbd> | ردیف بعد / قبل |
| <kbd>←</kbd> (در RTL) | باز کردن، یا رفتن به اولین زیرشاخه |
| <kbd>→</kbd> (در RTL) | بستن، یا رفتن به والد |
| <kbd>Home</kbd> / <kbd>End</kbd> | اولین / آخرین ردیف |
| <kbd>Enter</kbd> / <kbd>Space</kbd> | انتخاب |

در صفحه‌های چپ‌به‌راست، جهت ← و → برعکس است.

## دسترس‌پذیری

الگوی Tree در WAI-ARIA با `role="tree"`، `treeitem` و `group`؛ هر گره `aria-level` و `aria-expanded` دارد و فقط یک گره در ترتیب Tab است (roving tabindex). زیرشاخه‌های بسته رندر نمی‌شوند.

---

# راهنمای آیکون‌ها

URL: https://kashi.sepantapouya.com/docs/icons/usage/

۴۵۰۰ آیکون نرم در شش سبک با گوشه‌های پیوسته، هم‌خانواده با کامپوننت‌های کاشی؛ برای React، HTML، هر فریم‌ورک دیگر و فیگما.

آیکون‌های کاشی برای خود کاشی طراحی شده‌اند؛ همان سبکی که داخل دکمه‌ها، فیلدها و هشدارها می‌بینید. همه با `currentColor` رنگ می‌گیرند، پس رنگ متن اطراف را به ارث می‌برند و در تم تیره و روشن درست دیده می‌شوند. مجوز MIT است و در هر پروژه‌ای، حتی تجاری، آزادانه قابل استفاده‌اند.

```bash
npm i @kashi-ui/icons
```

همهٔ آیکون‌ها را دسته به دسته در [فهرست آیکون‌ها](/docs/icons/) ببینید.

## شش سبک

هر آیکون در شش سبک هست و همه از یک طرح خطی ساخته می‌شوند: `light` (خطی، پیش‌فرض)، `bold` (توپر)، `bulk` (حجمی)، `two-tone` (دورنگ)، `broken` (شکسته) و `curved` (منحنی).

```tsx
<IconWallet variant="bold" />
<Icon name="calendar" variant="bulk" />
```

```js
iconSvg("heart", { variant: "two-tone" });
```

هر سبک اسپرایت جدای خودش را دارد (`@kashi-ui/icons/sprite-bold.svg` با شناسهٔ `#k-home--bold`) و فایل‌های جدا در `@kashi-ui/icons/svg/<variant>/<name>.svg` هستند. سبک `bold` جزئیات را با ماسک SVG از دل شکل سوراخ می‌کند؛ هر نمونه شناسهٔ ماسک یکتای خودش را می‌گیرد.

## اصول طراحی

همهٔ آیکون‌ها از چند قاعدهٔ ساده پیروی می‌کنند تا کنار هم یکدست دیده شوند:

## React

هر آیکون یک کامپوننت جداست؛ فقط آیکون‌هایی که import می‌کنید در باندل می‌آیند.

```tsx
import { IconSearch, IconTrash } from "@kashi-ui/icons/react";

<IconSearch />
<IconTrash size={24} strokeWidth={2} className="danger" />
```

وقتی نام آیکون از داده می‌آید، از `Icon` استفاده کنید:

```tsx
import { Icon } from "@kashi-ui/icons/react";

<Icon name={item.icon} />
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| `size` | `number \| string` | `20` | عرض و ارتفاع؛ عدد یعنی پیکسل، یا هر واحد CSS مثل `"1.25em"` |
| `strokeWidth` | `number` | `1.5` | ضخامت خط |
| `title` | `string` | — | متن برای صفحه‌خوان؛ بدون آن آیکون تزئینی و پنهان است |
| `mirror` | `boolean` | `false` | قرینهٔ افقی؛ برای فلش‌ها در طرح‌های دوجهته |
| `name` | `IconName` | — | فقط در `Icon`؛ نام آیکون |

بقیهٔ ویژگی‌های `<svg>` (مثل `className`، `style` و `onClick`) هم پذیرفته می‌شوند و `ref` به خود `<svg>` می‌رسد.

## HTML و فریم‌ورک‌های دیگر

برای Vue، Svelte، Angular یا HTML ساده سه راه دارید.

**۱. کد SVG با جاوااسکریپت.** `iconSvg` رشتهٔ SVG برمی‌گرداند:

```js
import { iconSvg } from "@kashi-ui/icons";

button.innerHTML = iconSvg("trash", { size: 16 }) + " حذف";
```

**۲. اسپرایت.** فایل `@kashi-ui/icons/sprite.svg` را یک بار در صفحه بگذارید یا کنار سایتتان منتشر کنید و هر جا لازم شد صدا بزنید:

```html
<svg width="20" height="20" aria-hidden="true">
  <use href="/sprite.svg#k-search" />
</svg>
```

**۳. فایل SVG جدا.** هر آیکون در `@kashi-ui/icons/svg/<name>.svg` هم هست؛ برای `<img>` یا ابزارهای ساخت که SVG را import می‌کنند.

## داخل کامپوننت‌های کاشی

آیکون‌ها برای کار کنار کامپوننت‌ها ساخته شده‌اند و اندازه‌شان با دکمه و فیلد هماهنگ است:

```tsx
import { Button, Input } from "@kashi-ui/react";
import { IconPlus, IconSearch } from "@kashi-ui/icons/react";

<Button variant="primary" iconStart={<IconPlus />}>پروژهٔ جدید</Button>
<Input addonStart={<IconSearch />} placeholder="جستجو" />
```

## دسترس‌پذیری

- آیکون بدون `title` با `aria-hidden` از صفحه‌خوان پنهان می‌شود؛ برای آیکون‌هایی که کنار متن می‌آیند همین درست است.
- آیکونی که تنها می‌آید و معنا دارد (مثل دکمهٔ فقط‌آیکون) باید نام داشته باشد: یا `title` بدهید، یا بهتر، `aria-label` را روی خود دکمه بگذارید.
- آیکون‌ها `focusable="false"` دارند تا در اینترنت اکسپلورر و نسخه‌های قدیمی Edge در ترتیب Tab نیایند.

## راست‌به‌چپ

آیکون‌ها به‌طور پیش‌فرض قرینه نمی‌شوند؛ `arrow-left` همیشه به چپ اشاره می‌کند. در رابط فارسی، «بعدی» و «ادامه» یعنی فلش چپ و «بازگشت» یعنی فلش راست. شش آیکون جهت‌دار (فلش‌ها، شورون‌های چپ و راست، ارسال و خروج) در صفحهٔ هر آیکون با نشان «جهت‌دار» مشخص‌اند. اگر طرح شما هم راست‌به‌چپ و هم چپ‌به‌راست است، با `mirror` قرینه‌شان کنید.

## فیگما

همهٔ آیکون‌ها در صفحهٔ «🧩 Icons» [پلاگین فیگمای کاشی](/docs/figma/) هم هستند، دسته‌به‌دسته، هر کدام به شکل کامپوننت با نام `Icon / <دسته> / <name>` تا در پنل Assets هم پوشه‌بندی شوند؛ با Instance swap داخل دکمه‌ها و فیلدها عوض می‌شوند. فیگما و کد از یک منبع ساخته می‌شوند، پس شکل آیکون‌ها در هر دو یکی است.

## پیشنهاد آیکون تازه

آیکونی کم دارید؟ در [GitHub](https://github.com/Sepantapouya/Kashi/issues) بنویسید. آیکون‌های تازه با همین شبکه و ضخامت کشیده می‌شوند تا مجموعه یکدست بماند.

---

# معرفی

URL: https://kashi.sepantapouya.com/docs/

کاشی چیست، برای چه کسانی است و از چه بخش‌هایی تشکیل شده.

کاشی یک دیزاین‌سیستم متن‌باز برای محصولات فارسی است. نام آن از کاشی‌کاری ایرانی گرفته شده: قطعه‌های کوچک و دقیق که کنار هم یک کل یکپارچه می‌سازند.

```bash
npm i @kashi-ui/react @kashi-ui/css
```

## اصول

- **راست‌به‌چپ از پایه.** هیچ استایلی با `left` و `right` نوشته نشده؛ همه‌چیز با Logical Properties است. صفحه‌ای که با `dir="ltr"` باز شود هم بدون تغییر درست نمایش داده می‌شود.
- **دسترس‌پذیری به‌عنوان شرط انتشار.** هدف استاندارد WCAG 2.2 در سطح AA است. کنتراست رنگ‌ها در هر بیلد به‌صورت خودکار بررسی می‌شود و تست‌های خودکار ویژگی‌های ARIA را کنترل می‌کنند.
- **سفارشی‌سازی بدون جنگ با CSS.** همهٔ استایل‌ها در Cascade Layer قرار دارند؛ CSS شما همیشه اولویت دارد، بدون `!important`.
- **مستقل از فریم‌ورک.** ظاهر یک‌بار در CSS تعریف شده و هر فریم‌ورک لایهٔ نازکی روی آن است.

## پکیج‌ها

| پکیج | کاربرد |
|---|---|
| `@kashi-ui/tokens` | توکن‌های طراحی به‌صورت CSS Variables، JSON و JavaScript، به‌همراه `createTheme()` |
| `@kashi-ui/css` | استایل همهٔ کامپوننت‌ها با کلاس‌های `k-*`، به‌همراه فونت وزیرمتن |
| `@kashi-ui/react` | کامپوننت‌های React با تایپ کامل TypeScript |

## وضعیت پروژه

کاشی در نسخهٔ `0.x` است؛ یعنی API ممکن است پیش از نسخهٔ `1.0` تغییر کند. تغییرات ناسازگار همیشه در یادداشت انتشار ذکر می‌شوند.

---

# نصب

URL: https://kashi.sepantapouya.com/docs/installation/

کاشی را در پروژهٔ React یا هر پروژهٔ وب دیگری راه‌اندازی کنید.

## React

پکیج کامپوننت‌ها و استایل‌ها را نصب کنید:

```bash
npm i @kashi-ui/react @kashi-ui/css
```

فایل CSS را یک‌بار در ریشهٔ برنامه وارد کنید و جهت صفحه را راست‌به‌چپ قرار دهید:

```tsx
// main.tsx یا app/layout.tsx
import "@kashi-ui/css";
```

```html
<html lang="fa" dir="rtl">
```

حالا کامپوننت‌ها آمادهٔ استفاده‌اند:

```tsx
import { Button } from "@kashi-ui/react";

export function Example() {
  return <Button variant="primary">ثبت‌نام</Button>;
}
```

کاشی با React نسخهٔ ۱۸ و بالاتر کار می‌کند و با Next.js، Vite و Remix سازگار است.

## Tailwind

اگر پروژه‌تان Tailwind دارد، پریست کاشی را هم نصب کنید تا رنگ‌ها، فونت، گردی و سایه‌های کاشی به‌شکل کلاس‌های Tailwind (`bg-brand`، `rounded-lg`، `text-secondary`) در دسترس باشند و با تم تیره و روشن همگام بمانند:

```bash
npm i @kashi-ui/tailwind
```

```css
@import "@kashi-ui/tailwind";
@import "tailwindcss";
@import "@kashi-ui/css";
```

راهنمای کامل، فهرست کلاس‌ها و تنظیم Tailwind 3: [Tailwind](/docs/tailwind/)

## HTML و فریم‌ورک‌های دیگر

برای Vue، Svelte، Angular یا HTML ساده، فقط پکیج CSS لازم است:

```bash
npm i @kashi-ui/css
```

یا بدون نصب، از CDN:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kashi-ui/css/dist/kashi.css">
```

سپس از کلاس‌ها استفاده کنید. نمونهٔ HTML هر کامپوننت در صفحهٔ همان کامپوننت آمده است.

```html
<button class="k-btn k-btn--primary">ثبت‌نام</button>
```

## وارد کردن بخشی از CSS

اگر فقط به چند کامپوننت نیاز دارید، فایل‌ها را جداگانه وارد کنید. ترتیب مهم است: توکن‌ها، فونت و پایه، سپس کامپوننت‌ها.

```css
@import "@kashi-ui/css/tokens.css";
@import "@kashi-ui/css/font.css";
@import "@kashi-ui/css/base.css";
@import "@kashi-ui/css/components/button.css";
@import "@kashi-ui/css/components/input.css";
```

> فایل‌های جداگانه در Cascade Layer قرار ندارند. اگر به اولویت لایه‌ها نیاز دارید، از فایل کامل `kashi.css` استفاده کنید.

## تم روشن

تم پیش‌فرض تیره است. برای تم روشن، ویژگی `data-theme` را روی هر عنصری بگذارید؛ زیرشاخهٔ آن عنصر روشن می‌شود.

```html
<html lang="fa" dir="rtl" data-theme="light">
```

---

# هیت‌مپ فعالیت (ActivityHeatmap)

URL: https://kashi.sepantapouya.com/docs/persian/activity-heatmap/

فعالیت روزانهٔ یک سال شمسی به سبک GitHub، با ماه‌های جلالی و هفتهٔ شنبه‌تا‌جمعه.

```tsx
import { ActivityHeatmap } from "@kashi-ui/react";
```

## نمونه

```tsx
<ActivityHeatmap year={1405} unit="کامیت"
  data={{ "2026-03-21": 3, "2026-03-22": 7, … }} />
```

کلید داده تاریخ میلادی `YYYY-MM-DD` است (مثل خروجی `toISODate`) تا مستقیم از پایگاه‌داده بیاید. شدت رنگ نسبت به بیشترین مقدار سال در چهار پله است، با یک رنگ از کم‌رنگ به پررنگ.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| data | Record<string, number> | — | تعداد در هر روز؛ کلید YYYY-MM-DD |
| year | number | سال جاری | سال شمسی |
| unit | string | «فعالیت» | واحد در راهنما |
| label | string | — | نام دسترس‌پذیر |

## دسترس‌پذیری

برای صفحه‌خوان، نقشه یک تصویر با جمع کل است و یک جدول پنهان جمع هر ماه را می‌گوید؛ ۳۶۵ خانه یکی‌یکی خوانده نمی‌شوند. مقدار هر روز با نگه‌داشتن موس نمایش داده می‌شود.

---

# کارت بانکی (BankCard)

URL: https://kashi.sepantapouya.com/docs/persian/bank-card/

نمایش کارت بانکی با رنگ و لوگوی بانک، شمارهٔ پوشانده و تاریخ انقضای شمسی.

```tsx
import { BankCard } from "@kashi-ui/react";
```

## نمونه

```tsx
<BankCard number="6104337712345678" holder="سپنتا پویا"
  expiry={{ year: 1408, month: 5 }} masked />
```

بانک از شش رقم اول تشخیص داده می‌شود و کارت رنگ و لوگوی همان بانک را می‌گیرد. برای بانک‌های ناشناخته رنگ برند استفاده می‌شود و با `--k-bankcard-color` قابل تغییر است. برای کیف پول، انتخاب کارت ذخیره‌شده و صفحهٔ پرداخت مناسب است. با `masked` فقط شش رقم اول و چهار رقم آخر دیده می‌شود.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| number | string | — | با هر خطی |
| holder | ReactNode | — | نام دارنده |
| expiry | string \| { year, month } | — | «۰۸/۰۵» یا سال و ماه شمسی |
| masked | boolean | false | پنهان کردن ارقام میانی |
| bank | Bank \| null | — | بانک دستی |
| showLogo | boolean | true | — |
| digits | "fa" \| "latin" | "fa" | — |

## دسترس‌پذیری

کارت یک `figure` با نام کامل است، مثل «کارت بانک ملت، مختوم به ۵۶۷۸»، تا صفحه‌خوان ۱۶ رقم را جدا جدا نخواند. لوگو تزئینی است. رنگ‌ها تقریبی‌اند و رسمی نیستند.

---

# شمارش معکوس (Countdown)

URL: https://kashi.sepantapouya.com/docs/persian/countdown/

زمان باقی‌مانده با ارقام فارسی، برای ارسال دوبارهٔ کد، پایان تخفیف یا شروع رویداد.

```tsx
import { Countdown } from "@kashi-ui/react";
```

## نمونه

```tsx
ارسال دوبارهٔ کد تا <Countdown seconds={30} aria-label="زمان باقی‌مانده تا ارسال دوباره" onComplete={() => setDone(true)} />

<Countdown to={launchDate} variant="blocks" aria-label="زمان باقی‌مانده تا شروع فروش" />
```

برای شروع دوباره، `key` کامپوننت را عوض کنید. شمارش از ساعت سیستم حساب می‌شود، پس اگر زبانه مدتی پنهان باشد هم درست می‌ماند.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| to | Date | — | زمان پایان |
| seconds | number | — | یا مدت به ثانیه از لحظهٔ نمایش |
| onComplete | () => void | — | یک بار در پایان |
| variant | "clock" \| "blocks" | "clock" | ۰۲:۳۴ یا کادرهای روز و ساعت |
| digits | "fa" \| "latin" | "fa" | — |
| aria-label | string | — | موضوع شمارش |
| labels | { days?, hours?, minutes?, seconds? } | — | — |

## دسترس‌پذیری

`role="timer"` دارد که صفحه‌خوان آن را هر ثانیه اعلام نمی‌کند. نام دسترس‌پذیر متن کامل است («زمان باقی‌مانده تا ارسال دوباره: ۲ دقیقه و ۳۴ ثانیه»)، پس کاربر هر وقت به آن برسد زمان را می‌شنود.

---

# دیت‌پیکر شمسی (DatePicker, Calendar)

URL: https://kashi.sepantapouya.com/docs/persian/date-picker/

فیلد تاریخ با تقویم شمسی؛ تایپ مستقیم یا انتخاب از تقویم، با پیمایش کامل کیبورد و پشتیبانی صفحه‌خوان.

```tsx
import { DatePicker, Calendar } from "@kashi-ui/react";
```

کاربر می‌تواند تاریخ را مستقیم تایپ کند (با ارقام فارسی یا انگلیسی، مثل `۱۴۰۳/۵/۱۲`) یا آن را از تقویم انتخاب کند. مقدار کامپوننت یک `Date` استاندارد جاوااسکریپت است، پس سرور شما با تاریخ شمسی سروکار ندارد.

## تاریخ تولد

فهرست ماه و سال برای انتخاب سریع تاریخ‌های دور است. با `name`، مقدار میلادی به شکل `YYYY-MM-DD` در فرم ارسال می‌شود.

```tsx
const [birth, setBirth] = useState<Date | null>(null);

<DatePicker
  label="تاریخ تولد"
  name="birth"
  max={new Date()}
  yearRange={[1300, 1405]}
  onChange={setBirth}
/>
```

## محدود کردن روزها

با `min`، `max` و `isDateDisabled` روزهای غیرمجاز را مشخص کنید؛ مثلاً برای رزرو نوبت.

```tsx
<DatePicker
  label="تاریخ نوبت"
  min={new Date()}
  isDateDisabled={(date) => date.getDay() === 5} // جمعه
/>
```

## تقویم مستقل

`Calendar` همان تقویم بدون فیلد است؛ برای صفحه‌های رزرو یا داشبورد.

```tsx
const [date, setDate] = useState<Date | null>(new Date());

<Calendar value={date} onChange={setDate} />
```

## کیبورد

| کلید | عمل |
|---|---|
| <kbd>←</kbd> / <kbd>→</kbd> | روز بعد / روز قبل (در راست‌به‌چپ) |
| <kbd>↑</kbd> / <kbd>↓</kbd> | هفتهٔ قبل / هفتهٔ بعد |
| <kbd>Home</kbd> / <kbd>End</kbd> | شنبه / جمعهٔ همان هفته |
| <kbd>PageUp</kbd> / <kbd>PageDown</kbd> | ماه قبل / ماه بعد |
| <kbd>Shift</kbd> + <kbd>PageUp</kbd> / <kbd>PageDown</kbd> | سال قبل / سال بعد |
| <kbd>Enter</kbd> / <kbd>Space</kbd> | انتخاب روز |
| <kbd>Esc</kbd> | بستن تقویم و برگشت به دکمه |

## ویژگی‌های DatePicker

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | Date \| null | — | تاریخ انتخاب‌شده (کنترل‌شده) |
| defaultValue | Date \| null | null | مقدار اولیه (کنترل‌نشده) |
| onChange | (date: Date \| null) => void | — | با انتخاب، تایپ معتبر یا پاک کردن |
| min / max | Date | — | محدودهٔ مجاز |
| isDateDisabled | (date: Date) => boolean | — | غیرفعال کردن روزهای خاص |
| yearRange | [number, number] | ۱۰۰ سال قبل تا ۲۰ سال بعد | سال‌های فهرست سال (شمسی) |
| digits | "fa" \| "latin" | "fa" | خط ارقام |
| name | string | — | نام فیلد مخفی فرم با مقدار YYYY-MM-DD میلادی |
| invalidMessage | ReactNode | «تاریخ را به شکل … وارد کنید.» | پیام خطای تایپ نامعتبر |
| openLabel | string | "انتخاب تاریخ از تقویم" | نام دکمهٔ تقویم برای صفحه‌خوان |
| todayLabel | string | "امروز" | متن دکمهٔ امروز |

همهٔ ویژگی‌های `Input` مثل `label`، `hint` و `error` هم پشتیبانی می‌شوند.

## متغیرهای CSS

| متغیر CSS | پیش‌فرض | توضیح |
|---|---|---|
| --k-calendar-day-size | 2.5rem × density | اندازهٔ خانهٔ هر روز |
| --k-calendar-radius | var(--k-radius-full) | گردی خانهٔ روز |
| --k-calendar-bg | var(--k-bg-elevated) | پس‌زمینهٔ تقویم شناور |
| --k-datepicker-width | max-content | عرض تقویم شناور |

## دسترس‌پذیری

- تقویم از الگوی Date Picker در WAI-ARIA پیروی می‌کند: جدول با نقش `grid`، فقط یک روز در ترتیب Tab، و پیمایش با کلیدهای جهت‌دار.
- هر روز با نام کامل خوانده می‌شود («جمعه ۱۲ مرداد ۱۴۰۳»)، امروز با `aria-current="date"` و روز انتخاب‌شده با `aria-selected` مشخص است.
- تغییر ماه با یک ناحیهٔ `aria-live` اعلام می‌شود.
- دکمهٔ تقویم تاریخ فعلی را هم در نام خود دارد، پس کاربر صفحه‌خوان بدون باز کردن تقویم مقدار را می‌شنود.
- تایپ مستقیم همیشه ممکن است؛ کاربرانی که با تقویم راحت نیستند مجبور به استفاده از آن نیستند.

## تبدیل تاریخ

تبدیل شمسی و میلادی با پکیج `@kashi-ui/persian` انجام می‌شود که برای سال‌های ۱۳۰۰ تا ۱۵۰۰، روزبه‌روز با تقویم رسمی ICU تست شده است. [ابزارهای فارسی](/docs/persian/utilities/) را ببینید.

## تعطیلات

با `holidays`، جمعه‌ها و تعطیلات رسمی ثابت (نوروز، ۱۲ و ۱۳ فروردین، ۱۴ و ۱۵ خرداد، ۲۲ بهمن و ۲۹ اسفند) قرمز نمایش داده می‌شوند و نامشان برای صفحه‌خوان خوانده می‌شود. تعطیلات قمری هر سال با رؤیت ماه جابه‌جا می‌شوند، پس آن‌ها را از تقویم رسمی همان سال بدهید:

```tsx
import { getIranHoliday } from "@kashi-ui/persian";

<Calendar holidays /> // فقط جمعه‌ها و تعطیلات ثابت

<Calendar holidays={(d) => getIranHoliday(d, { extra: { "2026-03-20": "عید فطر" } })} />
```

---

# بازهٔ تاریخ شمسی (DateRangePicker)

URL: https://kashi.sepantapouya.com/docs/persian/date-range/

انتخاب بازهٔ تاریخ با تقویم جلالی و میان‌برهایی مثل «۷ روز اخیر» و «ماه قبل».

```tsx
import { DateRangePicker } from "@kashi-ui/react";
```

## نمونه

کلیک اول تاریخ شروع و کلیک دوم تاریخ پایان است (ترتیب مهم نیست)؛ پیش از کلیک دوم، بازه با حرکت موس یا فوکوس پیش‌نمایش می‌شود. تغییرها با «تأیید» ثبت می‌شوند.

```tsx
const [range, setRange] = useState<DateRange>({ start: null, end: null });

<DateRangePicker label="بازهٔ گزارش" name="period" value={range} onChange={setRange} max={new Date()} />
```

با `name`، دو فیلد پنهان `period_start` و `period_end` به شکل میلادی `YYYY-MM-DD` در فرم ارسال می‌شوند.

## میان‌برها

میان‌برهای پیش‌فرض (`defaultRangePresets`) «۷ روز اخیر»، «۳۰ روز اخیر»، «این ماه» و «ماه قبل» هستند و ماه‌ها شمسی حساب می‌شوند. فهرست خودتان را بدهید یا با `presets={[]}` حذفشان کنید:

```tsx
<DateRangePicker presets={[
  ...defaultRangePresets,
  { label: "امسال", range: (today) => ({ start: toGregorian(toJalali(today).jy, 1, 1), end: today }) },
]} />
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | { start: Date \| null; end: Date \| null } | — | — |
| onChange | (range) => void | — | پس از «تأیید» |
| min / max | Date | — | محدودهٔ مجاز |
| isDateDisabled | (date) => boolean | — | روزهای غیرقابل‌انتخاب |
| presets | { label, range: (today) => { start, end } }[] | defaultRangePresets | میان‌برها |
| name | string | — | name_start و name_end |
| digits | "fa" \| "latin" | "fa" | — |
| labels | { placeholder?, separator?, apply?, cancel?, presets?, pickEnd? } | — | متن‌ها |

## دسترس‌پذیری

دکمهٔ باز کردن `aria-haspopup="dialog"` و `aria-expanded` دارد و متن آن بازهٔ انتخاب‌شده است. تقویم همان الگوی grid تقویم تک‌تاریخ را دارد؛ روزهای داخل بازه `aria-selected` می‌گیرند. خلاصهٔ بازه پس از هر انتخاب با `aria-live` اعلام می‌شود و <kbd>Esc</kbd> بدون ثبت تغییر می‌بندد.

---

# برگ تقویم (DateTile)

URL: https://kashi.sepantapouya.com/docs/persian/date-tile/

کاشی تاریخ شمسی به شکل برگ تقویم، با روز هفته، مناسبت تعطیل و معادل میلادی.

```tsx
import { DateTile } from "@kashi-ui/react";
```

## نمونه

```tsx
<DateTile date={new Date()} size="lg" />
<DateTile date={new Date(2026, 2, 21)} />   {/* نوروز */}
```

برای رویدادها، نوبت‌دهی، تاریخ ارسال سفارش و فهرست جلسات. روزهای تعطیل (از جمله جمعه) قرمز می‌شوند و نام مناسبت رسمی نمایش داده می‌شود. تعطیلات قمری را با `holidays={{ extra: { … } }}` اضافه کنید. همان قالب `getIranHoliday` است.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| date | Date | — | — |
| holidays | boolean \| HolidayOptions | true | مناسبت و رنگ تعطیل |
| gregorian | boolean | true | معادل میلادی |
| size | "sm" \| "md" \| "lg" | "md" | — |

## دسترس‌پذیری

عنصر `<time>` با `datetime` استاندارد است تا موتورهای جستجو و ابزارها تاریخ را بفهمند.

---

# فیلد فارسی (PersianInput)

URL: https://kashi.sepantapouya.com/docs/persian/input/

یک کامپوننت برای همهٔ داده‌های فارسی؛ کد ملی، شناسهٔ شرکت، موبایل، تلفن، کارت، شبا، مبلغ، کد پستی، ساعت، پلاک و متن با اصلاح زبان صفحه‌کلید.

```tsx
import { PersianInput } from "@kashi-ui/react";
```

## نمونه

```tsx
<PersianInput kind="iban" name="iban" />
<PersianInput kind="price" min={10000} />
<PersianInput kind="postal" label="کد پستی محل کار" />
<PersianInput kind="text" label="جستجو" />   {/* با پیشنهاد «sghl» ← «سلام» */}
```

به جای به خاطر سپردن نام یازده کامپوننت، یک فیلد با `kind` بسازید. هر نوع برچسب، قالب، اعتبارسنجی و پیام خطای فارسی خودش را دارد. ویژگی‌های دیگر همان کامپوننت تخصصی است و TypeScript بر اساس `kind` آن‌ها را پیشنهاد می‌دهد. مثلاً `showBank` فقط برای `card` و `iban` مجاز است.

| kind | داده | کامپوننت تخصصی |
|---|---|---|
| `text` | متن با پیشنهاد اصلاح زبان صفحه‌کلید | [KeyboardFixInput](#text) |
| `national-id` | کد ملی | [NationalIdInput](#national-id) |
| `legal-id` | شناسهٔ ملی شرکت | [LegalIdInput](#legal-id) |
| `mobile` | موبایل با اپراتور | [MobileInput](#mobile) |
| `landline` | تلفن ثابت با استان | [LandlineInput](#landline) |
| `card` | شمارهٔ کارت با بانک | [CardNumberInput](#card) |
| `iban` | شبا با بانک | [IbanInput](#iban) |
| `price` | مبلغ با حروف | [PriceInput](#price) |
| `postal` | کد پستی | [PostalCodeInput](#postal) |
| `time` | ساعت | [TimeInput](#time) |
| `plate` | پلاک خودرو | [PlateInput](#plate) |

اگر برچسب ندهید، برچسب پیش‌فرض همان نوع («شمارهٔ شبا»، «کد پستی» و…) گذاشته می‌شود. با `aria-label` برچسب دیده نمی‌شود. فهرست برچسب‌ها در `PERSIAN_INPUT_LABELS` است.

## حجم بارگذاری

`PersianInput` همهٔ یازده فیلد را import می‌کند. اگر در صفحه فقط یکی را لازم دارید، کامپوننت تخصصی را مستقیم import کنید تا حجم کمتری بارگذاری شود.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| kind | "text" \| "national-id" \| "legal-id" \| "mobile" \| "landline" \| "card" \| "iban" \| "price" \| "postal" \| "time" \| "plate" | — | نوع داده |
| … | — | — | ویژگی‌های کامپوننت تخصصی همان نوع |

## ویژگی‌های هر نوع

در بخش‌های زیر، نمونه و ویژگی‌های اختصاصی هر نوع آمده است. همهٔ نوع‌ها ویژگی‌های `Input` مثل `label`، `hint`، `error`، `required` و `disabled` را هم می‌پذیرند.

## کد ملی

فیلد کد ملی با اعتبارسنجی رقم کنترل؛ ارقام فارسی و انگلیسی را می‌پذیرد.

```tsx
<PersianInput kind="national-id" />   // یا مستقیم: <NationalIdInput />
```

یک کد ملی آزمایشی معتبر: `0013542419`. یک رقم آخر را عوض کنید تا خطا را ببینید.

```tsx
<PersianInput kind="national-id"
  label="کد ملی"
  name="nationalId"
  onValueChange={(value, valid) => console.log(value, valid)}
/>
```

#### رفتار

- **ارقام:** کاربر می‌تواند با صفحه‌کلید فارسی یا انگلیسی تایپ کند. نمایش با ارقام فارسی است (`digits="latin"` برای انگلیسی)، ولی مقدار همیشه با ارقام انگلیسی به شما داده می‌شود.
- **محدودیت:** هر نویسهٔ غیر رقمی حذف می‌شود و بیش از ۱۰ رقم پذیرفته نمی‌شود. در گوشی، صفحه‌کلید عددی باز می‌شود.
- **اعتبارسنجی:** رقم دهم با الگوریتم رسمی رقم کنترل بررسی می‌شود. پیام خطا فقط پس از خروج از فیلد یا کامل شدن ۱۰ رقم نمایش داده می‌شود، نه هنگام تایپ.
- **فرم:** با `name`، مقدار با ارقام انگلیسی در یک فیلد مخفی ارسال می‌شود.

> اعتبارسنجی رقم کنترل فقط درستی ساختار کد را نشان می‌دهد، نه وجود آن را. برای احراز هویت، کد را با سرویس رسمی استعلام کنید.

#### ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | string | — | مقدار کنترل‌شده با ارقام انگلیسی |
| defaultValue | string | "" | مقدار اولیه |
| onValueChange | (value: string, valid: boolean) => void | — | با هر تغییر |
| digits | "fa" \| "latin" | "fa" | خط ارقام نمایشی |
| invalidMessage | ReactNode | "کد ملی معتبر نیست." | پیام خطا |
| name | string | — | نام فیلد مخفی فرم |

همهٔ ویژگی‌های `Input` مثل `label`، `hint`، `error` و `required` هم پشتیبانی می‌شوند.

#### بدون React

```ts

isValidNationalId("۰۰۱۳۵۴۲۴۱۹"); // true
isValidNationalId("1111111111"); // false
```

#### دسترس‌پذیری

- خطا با `aria-invalid` و `aria-describedby` به فیلد متصل است.
- فیلد با `dir="ltr"` است تا ترتیب ارقام هنگام تایپ جابه‌جا نشود.

## شناسهٔ ملی شرکت

شناسهٔ ملی ۱۱ رقمی اشخاص حقوقی با بررسی رقم کنترل.

```tsx
<PersianInput kind="legal-id" />   // یا مستقیم: <LegalIdInput />
```

```tsx
<PersianInput kind="legal-id" label="شناسهٔ ملی شرکت" name="legalId"
  onValueChange={(value, valid) => …} />
```

شناسهٔ ملی شرکت‌ها، مؤسسات و سازمان‌ها ۱۱ رقم دارد و رقم آخر آن رقم کنترل است. برای فرم‌های B2B، فاکتور رسمی و ثبت فروشنده در بازارگاه‌ها لازم است. ارقام فارسی و انگلیسی پذیرفته می‌شوند. بدون React هم با `isValidLegalId` از `@kashi-ui/persian` در دسترس است:

```ts
isValidLegalId("10380284790"); // true
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | string | — | ارقام لاتین |
| onValueChange | (value: string, valid: boolean) => void | — | — |
| digits | "fa" \| "latin" | "fa" | — |
| invalidMessage | ReactNode | «شناسهٔ ملی معتبر نیست.» | — |
| name | string | — | فیلد پنهان با ۱۱ رقم لاتین |

#### دسترس‌پذیری

خطا پس از خروج از فیلد یا کامل شدن ۱۱ رقم نمایش داده می‌شود و با `aria-describedby` به فیلد وصل است.

## شماره موبایل

فیلد شماره موبایل ایران با تبدیل خودکار +98، گروه‌بندی و تشخیص اپراتور.

```tsx
<PersianInput kind="mobile" />   // یا مستقیم: <MobileInput />
```

شماره را به هر شکلی بنویسید یا بچسبانید: `09123456789`، `+98 912 345 6789` یا `00989123456789`.

```tsx
<PersianInput kind="mobile"
  label="شماره موبایل"
  name="mobile"
  onValueChange={(mobile, valid, operator) => console.log(mobile, valid, operator)}
/>
```

#### رفتار

- **یکدست‌سازی:** `+98`، `0098`، `98` و شمارهٔ بدون صفر اول (`912…`) به شکل استاندارد `09xxxxxxxxx` درمی‌آیند.
- **اپراتور:** همراه اول، ایرانسل و رایتل از روی پیش‌شماره تشخیص داده می‌شوند. به دلیل امکان ترابرد شماره، اپراتور فقط برای راهنمایی است.
- **صفحه‌کلید:** در گوشی صفحه‌کلید تلفن باز می‌شود و مرورگر می‌تواند شمارهٔ ذخیره‌شده را پیشنهاد دهد.

#### ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | string | — | مقدار کنترل‌شده، به هر شکل |
| defaultValue | string | — | مقدار اولیه |
| onValueChange | (mobile: string, valid: boolean, operator: string \| null) => void | — | مقدار به شکل ۰۹xxxxxxxxx |
| digits | "fa" \| "latin" | "fa" | خط ارقام نمایشی |
| showOperator | boolean | true | نمایش نام اپراتور |
| invalidMessage | ReactNode | "شماره موبایل معتبر نیست." | پیام خطا |
| name | string | — | نام فیلد مخفی فرم |

#### بدون React

```ts

normalizeMobile("+98 912 345 6789"); // "09123456789"
getMobileOperator("0935")?.name;     // "ایرانسل"
formatMobile("09123456789");         // "0912 345 6789"
```

## تلفن ثابت

شمارهٔ تلفن ثابت با پیش‌شماره، گروه‌بندی و تشخیص استان.

```tsx
<PersianInput kind="landline" />   // یا مستقیم: <LandlineInput />
```

```tsx
<PersianInput kind="landline" label="تلفن ثابت" name="tel"
  onValueChange={(value, valid, province) => …} />
```

+98 و 0098 به ۰ تبدیل می‌شوند و نام استان از روی پیش‌شمارهٔ سه‌رقمی (مثل ۰۳۱ برای اصفهان) کنار فیلد نمایش داده می‌شود. پیش‌شمارهٔ هر ۳۱ استان در `getLandlineProvince` است.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | string | — | مثل 02188776655 |
| onValueChange | (value, valid, province) => void | — | — |
| showProvince | boolean | true | نام استان کنار فیلد |
| digits | "fa" \| "latin" | "fa" | — |
| invalidMessage | ReactNode | «شمارهٔ تلفن ثابت معتبر نیست.» | — |
| name | string | — | فیلد پنهان با ۱۱ رقم لاتین |

#### دسترس‌پذیری

نام استان با `aria-describedby` به فیلد وصل است. `autocomplete="tel-national"` و صفحه‌کلید عددی گوشی فعال است.

## شماره کارت

فیلد شماره کارت بانکی با گروه‌بندی خودکار، تشخیص بانک و اعتبارسنجی Luhn.

```tsx
<PersianInput kind="card" />   // یا مستقیم: <CardNumberInput />
```

شش رقم اول را تایپ کنید، مثلاً `603799` یا `610433`، تا لوگو و نام بانک نمایش داده شوند.

```tsx
<PersianInput kind="card"
  label="شماره کارت"
  name="card"
  onValueChange={(value, valid, bank) => console.log(value, valid, bank)}
/>
```

#### رفتار

- **گروه‌بندی:** ارقام به‌صورت خودکار در گروه‌های چهارتایی نمایش داده می‌شوند. هنگام ویرایش وسط شماره، مکان‌نما سر جای درستش می‌ماند.
- **چسباندن:** شماره‌ای که با فاصله، خط تیره یا ارقام فارسی کپی شده هم درست خوانده می‌شود.
- **تشخیص بانک:** لوگو و نام بانک از شش رقم اول (BIN) تشخیص داده می‌شوند. لوگوها فقط وقتی بانک شناخته شد بارگذاری می‌شوند و حجم اولیهٔ برنامه را زیاد نمی‌کنند ([لوگوی بانک‌ها](/docs/persian/bank-logos/)). فهرست بانک‌ها ممکن است کامل نباشد؛ از آن فقط برای راهنمایی کاربر استفاده کنید.
- **اعتبارسنجی:** شمارهٔ ۱۶ رقمی با الگوریتم Luhn بررسی می‌شود.
- **تکمیل خودکار:** با `autocomplete="cc-number"`، مرورگر می‌تواند کارت ذخیره‌شده را پیشنهاد دهد.

> این فیلد شماره را فقط در مرورگر قالب‌بندی می‌کند. شمارهٔ کارت داده‌ای حساس است؛ آن را فقط از طریق HTTPS ارسال کنید و بدون نیاز ذخیره نکنید.

#### ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | string | — | مقدار کنترل‌شده: ۱۶ رقم انگلیسی بدون فاصله |
| defaultValue | string | "" | مقدار اولیه |
| onValueChange | (value: string, valid: boolean, bank: string \| null) => void | — | با هر تغییر |
| digits | "fa" \| "latin" | "fa" | خط ارقام نمایشی |
| showBank | boolean | true | نمایش نام بانک |
| showBankLogo | boolean | true | نمایش لوگوی بانک (بارگذاری تنبل) |
| invalidMessage | ReactNode | "شماره کارت معتبر نیست." | پیام خطا |
| name | string | — | نام فیلد مخفی فرم با ارقام بدون فاصله |

#### بدون React

```ts

formatCardNumber("6037991234567890"); // "6037 9912 3456 7890"
getBankByCard("603799")?.name;        // "بانک ملی"
isValidCardNumber("4111 1111 1111 1111"); // true
```

#### دسترس‌پذیری

- نام بانک با `aria-describedby` به فیلد متصل است و صفحه‌خوان آن را همراه فیلد می‌خواند.
- خطا پس از خروج از فیلد یا کامل شدن ۱۶ رقم نمایش داده می‌شود، نه هنگام تایپ.

## شماره شبا

فیلد شبا (IBAN ایران) با IR خودکار، گروه‌بندی، لوگو و نام بانک و بررسی رقم‌های کنترل.

```tsx
<PersianInput kind="iban" />   // یا مستقیم: <IbanInput />
```

فقط ارقام را تایپ کنید؛ «IR» خودکار اضافه می‌شود. با تایپ ارقام ۳ تا ۵ (کد بانک)، لوگو و نام بانک نمایش داده می‌شوند.

```tsx
<PersianInput kind="iban"
  label="شماره شبا"
  name="iban"
  onValueChange={(iban, valid, bank) => console.log(iban, valid, bank)}
/>
```

#### رفتار

- **ورودی آزاد:** شبا با یا بدون «IR»، با فاصله یا بدون آن، و با ارقام فارسی یا انگلیسی پذیرفته می‌شود.
- **اعتبارسنجی:** رقم‌های کنترل با استاندارد ISO 13616 (باقیماندهٔ ۹۷) بررسی می‌شوند؛ هر رقم اشتباه یا جابه‌جایی ارقام مجاور تشخیص داده می‌شود.
- **مقدار:** همیشه به شکل `IR` + ۲۴ رقم بدون فاصله به شما داده می‌شود.
- **ارقام:** شبا معمولاً با ارقام انگلیسی نوشته می‌شود؛ برای ارقام فارسی `digits="fa"` بدهید.

#### ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | string | — | شبای کنترل‌شده، با یا بدون IR |
| defaultValue | string | — | مقدار اولیه |
| onValueChange | (iban: string, valid: boolean, bank: string \| null) => void | — | با هر تغییر |
| digits | "fa" \| "latin" | "latin" | خط ارقام نمایشی |
| showBank | boolean | true | نمایش نام بانک |
| showBankLogo | boolean | true | نمایش لوگوی بانک (بارگذاری تنبل) |
| invalidMessage | ReactNode | "شماره شبا معتبر نیست." | پیام خطا |
| name | string | — | نام فیلد مخفی فرم با مقدار IR… |

#### بدون React

```ts

isValidIban("IR06 2960 0000 0010 0324 2000 01");
getBankByIban("IR..0170...")?.name;   // "بانک ملی"
formatIban("062960000000100324200001"); // "IR06 2960 0000 0010 0324 2000 01"
```

#### دسترس‌پذیری

- نام بانک با `aria-describedby` به فیلد متصل است؛ لوگو تزئینی است (`alt=""`) تا صفحه‌خوان نام بانک را دو بار نخواند.

## مبلغ

فیلد مبلغ با جداکنندهٔ هزارگان فارسی، واحد پول و نمایش مبلغ به حروف.

```tsx
<PersianInput kind="price" />   // یا مستقیم: <PriceInput />
```

مبلغ به حروف زیر فیلد نمایش داده می‌شود تا کاربر مطمئن شود صفرها را درست وارد کرده است؛ اشتباهی رایج و پرهزینه در پرداخت‌ها.

```tsx
<PersianInput kind="price"
  label="مبلغ پرداخت"
  name="amount"
  max={500_000_000}
  onValueChange={(amount) => console.log(amount)}
/>
```

#### رفتار

- **قالب‌بندی:** جداکنندهٔ هزارگان فارسی (`٬`) هنگام تایپ اضافه می‌شود و مکان‌نما سر جایش می‌ماند.
- **به حروف:** «یک میلیون و دویست و پنجاه هزار تومان». با `showWords={false}` خاموش می‌شود.
- **واحد:** پیش‌فرض «تومان»؛ با `unit="ریال"` یا هر متن دیگری عوض می‌شود.
- **مقدار:** عدد (`number`) یا `null` برای فیلد خالی. صفرهای ابتدایی حذف می‌شوند. تا ۱۵ رقم.
- **محدوده:** با `min` و `max`، پس از خروج از فیلد پیام خطا نمایش داده می‌شود.

#### ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | number \| null | — | مقدار کنترل‌شده |
| defaultValue | number \| null | — | مقدار اولیه |
| onValueChange | (value: number \| null) => void | — | با هر تغییر |
| unit | ReactNode | "تومان" | واحد پول کنار فیلد |
| showWords | boolean | true | نمایش مبلغ به حروف در متن راهنما |
| min / max | number | — | محدودهٔ مجاز |
| rangeMessage | (min?, max?) => ReactNode | خودکار | پیام خطای محدوده |
| digits | "fa" \| "latin" | "fa" | خط ارقام نمایشی |
| name | string | — | نام فیلد مخفی فرم با مقدار عددی خام |

#### بدون React

```ts

numberToWords(1250000); // "یک میلیون و دویست و پنجاه هزار"
formatNumber(1250000);  // "۱٬۲۵۰٬۰۰۰"
```

#### دسترس‌پذیری

- مبلغ به حروف در متن راهنما است و با `aria-describedby` به فیلد متصل است؛ صفحه‌خوان پس از نام فیلد آن را می‌خواند.
- واحد پول کنار فیلد نمایش داده می‌شود؛ آن را در برچسب هم تکرار کنید اگر برای فهم فیلد ضروری است.

## کد پستی

کد پستی ۱۰ رقمی ایران با قالب ۱۲۳۴۵-۶۷۸۹۰ و بررسی قواعد آن.

```tsx
<PersianInput kind="postal" />   // یا مستقیم: <PostalCodeInput />
```

```tsx
<PersianInput kind="postal" label="کد پستی" name="postal"
  onValueChange={(value, valid) => …} />
```

ارقام فارسی و انگلیسی پذیرفته می‌شوند و خط تیره خودکار اضافه می‌شود. کد پستی ایران در پنج رقم اول ۰ و ۲ ندارد و چهار رقم یکسان پشت سر هم ندارد؛ `isValidPostalCode` همین قواعد را بررسی می‌کند. این بررسی وجود واقعی کد را تضمین نمی‌کند.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | string | — | ارقام لاتین |
| onValueChange | (value: string, valid: boolean) => void | — | — |
| digits | "fa" \| "latin" | "fa" | — |
| invalidMessage | ReactNode | «کد پستی معتبر نیست.» | — |
| name | string | — | فیلد پنهان با ۱۰ رقم لاتین |

#### دسترس‌پذیری

`autocomplete="postal-code"` دارد تا مرورگر بتواند آن را پر کند. خطا پس از خروج از فیلد یا کامل شدن ۱۰ رقم نمایش داده می‌شود، نه هنگام تایپ.

## ساعت

ورود ساعت ۲۴ساعته با ارقام فارسی، تایپ سریع و گام‌های ↑↓.

```tsx
<PersianInput kind="time" />   // یا مستقیم: <TimeInput />
```

کاربر می‌تواند «۹۳۰»، «۹:۳۰» یا «9.30» بنویسد؛ پس از خروج از فیلد به «۰۹:۳۰» تبدیل می‌شود. <kbd>↑</kbd>/<kbd>↓</kbd> به گام بعدی یا قبلی می‌پرد.

```tsx
<PersianInput kind="time" label="ساعت شروع جلسه" min="08:00" max="20:00" value={t} onChange={setT} name="start" />
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | "HH:MM" \| null | null | با ارقام لاتین |
| onChange | (value: string \| null) => void | — | — |
| step | number | 15 | گام ↑↓ به دقیقه |
| min / max | "HH:MM" | — | محدودهٔ مجاز |
| digits | "fa" \| "latin" | "fa" | — |
| invalidMessage | ReactNode | — | پیام ساعت نامعتبر |
| rangeMessage | (min, max) => ReactNode | «ساعت باید بین … و … باشد.» | پیام ساعت خارج از محدوده |

ابزارهای `parseTime` و `formatTime` در `@kashi-ui/persian` هم در دسترس‌اند.

#### دسترس‌پذیری

یک فیلد متنی ساده با برچسب و راهنما؛ برخلاف `<input type="time">`، در همهٔ مرورگرها یکسان و با ارقام فارسی کار می‌کند. خطا پس از خروج از فیلد نمایش داده و به آن وصل می‌شود.

## پلاک خودرو

ورود پلاک خودروی ایران با ظاهر واقعی پلاک: دو رقم، حرف، سه رقم و کد استان.

```tsx
<PersianInput kind="plate" />   // یا مستقیم: <PlateInput />
```

```tsx
<PersianInput kind="plate" label="پلاک خودرو" name="car"
  onChange={(plate, valid) => …} />
// plate = { first: "12", letter: "ب", middle: "345", region: "67" }
```

پلاک نسبت واقعی ۵۲۰ در ۱۱۰ میلی‌متر را دارد و رنگش مثل پلاک واقعی از روی حرف تعیین می‌شود (`plateType`):

| حرف | نوع | رنگ |
|---|---|---|
| ب، ج، د، س… | شخصی | سفید |
| ت / ع / ک | تاکسی / عمومی / کشاورزی | زرد |
| الف | دولتی | قرمز |
| پ / ث | پلیس / سپاه | سبز |
| ش | ارتش | قهوه‌ای روشن |
| ز / ف | وزارت دفاع / ستاد کل | آبی روشن |
| ژ | معلولین | سفید |

ارتفاع با `--k-plate-height` (پیش‌فرض 3.5rem) عوض می‌شود و عرض به همان نسبت تغییر می‌کند. با پر شدن هر بخش، فوکوس به بخش بعد می‌رود و <kbd>Backspace</kbd> در بخش خالی به بخش قبل برمی‌گردد. `formatPlate` متن خوانا می‌سازد: «۱۲ ب ۳۴۵ ایران ۶۷».

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | { first, letter, middle, region } | — | ارقام لاتین |
| onChange | (plate, valid: boolean) => void | — | — |
| name | string | — | چهار فیلد پنهان: name_first، name_letter، name_middle، name_region |
| labels | { first?, letter?, middle?, region? } | — | نام هر بخش برای صفحه‌خوان |
| invalidMessage | ReactNode | «پلاک خودرو معتبر نیست.» | — |

#### دسترس‌پذیری

یک `role="group"` با نام «پلاک خودرو» و چهار کنترل که هرکدام نام خودش را دارد («دو رقم اول پلاک»، «حرف پلاک»…). حرف با `<select>` بومی انتخاب می‌شود. وقتی پلاک کامل و معتبر شد، متن کامل آن با `aria-live` خوانده می‌شود.

## اصلاح زبان صفحه‌کلید

اگر کاربر فارسی را با صفحه‌کلید انگلیسی تایپ کند، شکل درست را پیشنهاد می‌دهد: sghl ← سلام.

```tsx
<PersianInput kind="text" />   // یا مستقیم: <KeyboardFixInput />
```

```tsx
<PersianInput kind="text" label="جستجو" value={query} onValueChange={setQuery} />
```

کاربر فارسی‌زبان زیاد پیش می‌آید که فراموش کند زبان صفحه‌کلید را عوض کند و «سلام» را «sghl» تایپ کند. این فیلد شکل فارسی را زیر فیلد پیشنهاد می‌دهد و با یک کلیک جایگزین می‌کند. برای جستجو بیشترین کاربرد را دارد.

تشخیص به‌صورت پیش‌فرض حدسی است (`suggest="auto"`): کلمه‌های لاتینِ بدون حرف صدادار یا با `;`، `'` و `[` در وسط کلمه مشکوک‌اند. برای پیشنهاد روی هر متن لاتین از `suggest="always"` استفاده کنید. تبدیل بر اساس چیدمان استاندارد صفحه‌کلید فارسی است.

```ts
fixKeyboardLayout("sghl o,fd?");       // "سلام خوبی؟"
fixKeyboardLayout("لخخلمث", "en");    // "google"
looksLikeWrongLayout("sghl");          // true
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | string | — | — |
| onValueChange | (value: string) => void | — | — |
| suggest | "auto" \| "always" | "auto" | — |
| renderSuggestion | (fixed, apply) => ReactNode | — | متن دلخواه پیشنهاد |

#### دسترس‌پذیری

پیشنهاد در ناحیهٔ `role="status"` است تا صفحه‌خوان آن را اعلام کند و دکمهٔ آن با کیبورد در دسترس است. پس از جایگزینی، فوکوس به فیلد برمی‌گردد.

---

# نمایش مبلغ (Money)

URL: https://kashi.sepantapouya.com/docs/persian/money/

مبلغ با تومان یا ریال، حالت خلاصه مثل «۱٫۲ میلیون» و مبلغ به حروف برای صفحه‌خوان.

```tsx
import { Money } from "@kashi-ui/react";
```

## نمونه

```tsx
<Money value={1250000} />
<Money value={1250000} compact />
<Money value={48500000} from="rial" compact />   {/* ریال به تومان */}
<Money value={-85000} signed />
```

در محصولات ایرانی مبلغ معمولاً در پایگاه داده به ریال است و به کاربر به تومان نشان داده می‌شود. با `from="rial"` تبدیل خودکار انجام می‌شود. حالت `compact` برای کارت‌ها و جدول‌ها مناسب است و برای اعداد بسیار بزرگ «همت» (هزار میلیارد تومان) را به کار می‌برد.

```ts
import { formatMoney } from "@kashi-ui/persian";
formatMoney(1250000);                    // "۱٬۲۵۰٬۰۰۰ تومان"
formatMoney(1250000, { compact: true }); // "۱٫۲۵ میلیون تومان"
formatMoney(5000, { unit: "rial" });     // "۵۰٬۰۰۰ ریال"
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | number | — | — |
| unit | "toman" \| "rial" | "toman" | واحد نمایش |
| from | "toman" \| "rial" | "toman" | واحد مقدار ورودی |
| compact | boolean | false | هزار، میلیون، میلیارد، همت |
| signed | boolean | false | + و رنگ سبز یا قرمز |
| words | boolean | true | مبلغ به حروف در title و برای صفحه‌خوان |
| size | "sm" \| "md" \| "lg" \| "xl" | "md" | — |

## دسترس‌پذیری

عنصر `<data>` مقدار عددی خام را در `value` نگه می‌دارد. صفحه‌خوان به جای ارقام جداشده، مبلغ را به حروف می‌خواند («یک میلیون و دویست و پنجاه هزار تومان»). رنگ مثبت و منفی همیشه همراه علامت + و − است.

---

# انتخاب ماه (MonthPicker)

URL: https://kashi.sepantapouya.com/docs/persian/month-picker/

انتخاب ماه و سال شمسی برای گزارش ماهانه، صورت‌حساب یا تاریخ انقضا.

```tsx
import { MonthPicker, type JalaliMonth } from "@kashi-ui/react";
```

## نمونه

```tsx
const [m, setM] = useState<JalaliMonth | null>(null);

<MonthPicker aria-label="ماه گزارش" value={m} onChange={setM} max={{ year: 1405, month: 12 }} />
```

برای تبدیل به تاریخ میلادی: `toGregorian(m.year, m.month, 1)` از `@kashi-ui/persian`.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | { year, month } \| null | null | ماه شمسی؛ month از ۱ تا ۱۲ |
| onChange | (value) => void | — | — |
| min / max | { year, month } | — | محدودهٔ مجاز |
| digits | "fa" \| "latin" | "fa" | — |
| aria-label | string | «انتخاب ماه» | — |
| labels | { prevYear?, nextYear? } | «سال قبل»، «سال بعد» | — |

## کیبورد

| کلید | عمل |
|---|---|
| <kbd>←</kbd> / <kbd>→</kbd> | ماه بعد / قبل (در RTL) |
| <kbd>↑</kbd> / <kbd>↓</kbd> | سه ماه قبل / بعد |
| <kbd>PageUp</kbd> / <kbd>PageDown</kbd> | سال قبل / بعد |
| <kbd>Home</kbd> / <kbd>End</kbd> | فروردین / اسفند |

## دسترس‌پذیری

هر ماه دکمه‌ای با نام کامل («آبان ۱۴۰۵») و `aria-pressed` است؛ ماه جاری `aria-current="date"` دارد. فقط یک ماه در ترتیب Tab است و سال با `aria-live` اعلام می‌شود.

---

# کد تأیید (OTP) (OtpInput)

URL: https://kashi.sepantapouya.com/docs/persian/otp/

ورود کد پیامکی یک‌بارمصرف؛ با پر شدن خودکار از پیامک در گوشی و ارقام فارسی.

```tsx
import { OtpInput } from "@kashi-ui/react";
```

## نمونه

کد آزمایشی `123456` را تایپ کنید، یا کد را کپی کنید و بچسبانید.

```tsx
<OtpInput
  label="کد ارسال‌شده به ۰۹۱۲ ••• ۶۷۸۹"
  length={6}
  groupAfter={3}
  onComplete={(code) => verify(code)}
/>
```

## چرا یک input؟

بیشتر پیاده‌سازی‌های OTP شش فیلد جدا دارند که چسباندن، پاک کردن و صفحه‌خوان را خراب می‌کند. کاشی **یک input واقعی** زیر خانه‌های نمایشی دارد، پس:

- **پر شدن خودکار:** با `autocomplete="one-time-code"`، iOS و Android کد پیامک دریافتی را بالای صفحه‌کلید پیشنهاد می‌دهند.
- **چسباندن:** «۱۲۳ ۴۵۶» یا «123-456» هم درست خوانده می‌شود؛ ارقام فارسی و فاصله‌ها پذیرفته می‌شوند.
- **صفحه‌خوان:** یک فیلد با یک برچسب می‌خواند، نه شش فیلد بی‌نام.
- **پاک کردن و جابه‌جایی:** <kbd>Backspace</kbd>، کلیدهای جهت‌دار و انتخاب متن همان رفتار عادی را دارند.

## ویژگی‌ها

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| length | number | 6 | تعداد رقم |
| value / defaultValue | string | — | کد با ارقام انگلیسی |
| onChange | (code) => void | — | با هر تغییر |
| onComplete | (code) => void | — | وقتی همهٔ رقم‌ها وارد شد |
| groupAfter | number | — | خط فاصله بعد از این تعداد رقم |
| label / hint / error | ReactNode | — | مثل Input |
| digits | "fa" \| "latin" | "fa" | خط ارقام نمایشی |
| size | "sm" \| "md" | "md" | اندازهٔ خانه‌ها |
| name | string | — | نام فیلد مخفی فرم |

---

# انتخاب استان (ProvinceSelect)

URL: https://kashi.sepantapouya.com/docs/persian/province/

انتخاب یکی از ۳۱ استان با جستجو؛ با نام مرکز استان هم پیدا می‌شود.

```tsx
import { ProvinceSelect } from "@kashi-ui/react";
```

## نمونه

```tsx
<ProvinceSelect value={province} onChange={setProvince} name="province" />
```

روی `Combobox` ساخته شده، پس همهٔ ویژگی‌های آن را دارد. فهرست استان‌ها با مرکز و پیش‌شمارهٔ تلفن ثابت در `PROVINCES` از `@kashi-ui/persian` هم در دسترس است:

```ts
import { PROVINCES } from "@kashi-ui/persian";
// [{ name: "اصفهان", capital: "اصفهان", areaCode: "31" }, …]
```

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | string \| null | — | نام استان |
| onChange | (value: string \| null) => void | — | — |
| showCapital | boolean | true | مرکز استان زیر نام |
| … | ComboboxProps | — | همهٔ ویژگی‌های Combobox |

## دسترس‌پذیری

همان الگوی Combobox در WAI-ARIA؛ تعداد نتیجه‌ها پس از هر تایپ اعلام می‌شود.

---

# رسید پرداخت (PaymentReceipt)

URL: https://kashi.sepantapouya.com/docs/persian/receipt/

صفحهٔ نتیجهٔ پرداخت با وضعیت، مبلغ به حروف، کد پیگیری قابل کپی و کارت پوشانده.

```tsx
import { PaymentReceipt } from "@kashi-ui/react";
```

## نمونه

```tsx
<PaymentReceipt status="success" amount={1250000} merchant="فروشگاه کاشی"
  trackingCode="482913" referenceId="140508270123"
  cardNumber="6104337712345678" date={paidAt}>
  <Button variant="primary">بازگشت به فروشگاه</Button>
</PaymentReceipt>
```

صفحه‌ای که کاربر پس از بازگشت از درگاه بانکی می‌بیند. سه وضعیت دارد: `success`، `pending` (بانک هنوز تأیید نکرده) و `failed`. برای پرداخت ناموفق، در `description` توضیح دهید که مبلغ کسرشده کی برمی‌گردد. کارت خودکار پوشانده می‌شود و تاریخ شمسی است. ردیف‌های دیگر را با `rows` اضافه کنید.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| status | "success" \| "pending" \| "failed" | — | — |
| amount | number | — | — |
| unit | "toman" \| "rial" | "toman" | — |
| title / description | ReactNode | — | پیش‌فرض بر اساس وضعیت |
| merchant | ReactNode | — | پذیرنده |
| trackingCode | string | — | با دکمهٔ کپی |
| referenceId | string | — | — |
| cardNumber | string | — | پوشانده با لوگوی بانک |
| date | Date | — | — |
| rows | [ReactNode, ReactNode][] | — | ردیف‌های دیگر |
| children | ReactNode | — | دکمه‌ها |

## دسترس‌پذیری

رسید یک `section` است که عنوانش نام آن است. وضعیت با آیکون، رنگ و متن عنوان بیان می‌شود، نه فقط با رنگ. دکمهٔ کپی کد پیگیری پس از کپی «کپی شد» را اعلام می‌کند.

---

# ویرایش نگارشی (PersianTextarea)

URL: https://kashi.sepantapouya.com/docs/persian/text-fix/

ناحیهٔ متن که «ي» و «ك» عربی، نیم‌فاصله، علامت‌های فارسی و ارقام را پیدا و با یک کلیک اصلاح می‌کند.

```tsx
import { PersianTextarea } from "@kashi-ui/react";
```

## نمونه

```tsx
<PersianTextarea label="توضیحات محصول" value={text} onValueChange={setText} />
```

متنی که از ورد، سایت‌های عربی یا صفحه‌کلیدهای مختلف کپی می‌شود معمولاً «ي» و «ك» عربی دارد که جستجو را خراب می‌کند. این فیلد تعداد مشکل‌ها را زیر متن نشان می‌دهد و با «اصلاح نگارش» همه را درست می‌کند:

| اصلاح | قبل | بعد |
|---|---|---|
| حروف عربی | كتاب، ايران | کتاب، ایران |
| نیم‌فاصله | مي خوانم، كتاب ها، بزرگ تر | می‌خوانم، کتاب‌ها، بزرگ‌تر |
| علامت‌ها | چرا ? خوب , بد | چرا؟ خوب، بد |
| ارقام | ۲۰ را 20 نوشتن | ۲۰ |
| فاصله | فاصلهٔ اضافه و فاصله پیش از نقطه | یک فاصله |

با `fixOnBlur` اصلاح هنگام خروج از فیلد خودکار انجام می‌شود. همین منطق در `fixPersianText` بدون React در دسترس است و تعداد هر نوع اصلاح را هم برمی‌گرداند.

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | string | — | — |
| onValueChange | (value: string) => void | — | — |
| fixDigits | boolean | true | ارقام لاتین کنار متن فارسی |
| fixOnBlur | boolean | false | اصلاح خودکار هنگام خروج |
| labels | { fix?, clean? } | — | — |

همهٔ ویژگی‌های `Textarea` مثل `autoResize` و `showCount` را هم می‌پذیرد.

---

# ابزارهای فارسی

URL: https://kashi.sepantapouya.com/docs/persian/utilities/

تاریخ شمسی، ارقام فارسی، قالب‌بندی اعداد و اعتبارسنجی؛ بدون وابستگی و برای هر فریم‌ورکی.

پکیج `@kashi-ui/persian` هیچ وابستگی‌ای ندارد و در مرورگر، Node.js و هر فریم‌ورکی (React، Vue، Svelte، Angular) کار می‌کند. کامپوننت‌های فارسی کاشی هم روی همین پکیج ساخته شده‌اند.

```bash
npm i @kashi-ui/persian
```

## تاریخ شمسی

```ts
import { toJalali, toGregorian, formatJalali, parseJalali } from "@kashi-ui/persian";

toJalali(new Date(2024, 7, 2));        // { jy: 1403, jm: 5, jd: 12 }
toGregorian(1403, 5, 12);               // Date: 2024-08-02

formatJalali(date);                     // "۱۴۰۳/۰۵/۱۲"
formatJalali(date, { style: "long" });  // "۱۲ مرداد ۱۴۰۳"
formatJalali(date, { style: "full" });  // "جمعه ۱۲ مرداد ۱۴۰۳"

parseJalali("۱۴۰۳/۵/۱۲");               // Date
parseJalali("1404/12/30");              // null (۱۴۰۴ کبیسه نیست)
```

| تابع | کاربرد |
|---|---|
| `toJalali(date)` | میلادی به شمسی |
| `toGregorian(jy, jm, jd)` | شمسی به `Date` |
| `formatJalali(date, options)` | نمایش؛ سبک `numeric`، `long` یا `full` |
| `parseJalali(text)` | خواندن متن کاربر؛ ارقام فارسی و جداکننده‌های `/`، `-` و `.` |
| `isLeapJalaliYear(jy)` | سال کبیسه |
| `jalaliMonthLength(jy, jm)` | تعداد روزهای ماه |
| `isValidJalaliDate(jy, jm, jd)` | وجود تاریخ |
| `jalaliWeekday(date)` | روز هفته؛ ۰ = شنبه |
| `toISODate(date)` | `YYYY-MM-DD` بر اساس وقت محلی، برای ارسال به سرور |
| `fromISODate(text)` | `YYYY-MM-DD` به `Date` محلی |
| `JALALI_MONTHS`، `WEEKDAYS` | نام ماه‌ها و روزها |

> **هشدار منطقهٔ زمانی:** برای ارسال تاریخ به سرور از `date.toISOString()` استفاده نکنید. این تابع زمان را به UTC تبدیل می‌کند و چون ایران ۳٫۵ ساعت جلوتر است، نیمه‌شب را روز قبل می‌کند. به‌جای آن از `toISODate(date)` استفاده کنید.

دقت: تبدیل برای همهٔ ۷۲٬۹۷۰ روز از ۱۳۰۰ تا ۱۵۰۰ با تقویم persian کتابخانهٔ ICU (همان تقویم مرورگرها) مقایسه و تست شده است.

## زمان نسبی

```ts
import { formatRelative } from "@kashi-ui/persian";

formatRelative(date);   // «همین الان»، «۵ دقیقه پیش»، «دیروز»، «۳ روز دیگر»، «۲ سال پیش»
```

«دیروز» و «فردا» بر اساس روز تقویمی محاسبه می‌شوند، نه ۲۴ ساعت. در React از `<RelativeTime date={date} />` استفاده کنید که هر دقیقه به‌روز می‌شود و تاریخ کامل شمسی را در `title` دارد.

## ارقام و اعداد

```ts
import { toFaDigits, toEnDigits, onlyDigits, formatNumber } from "@kashi-ui/persian";

toFaDigits(1403);              // "۱۴۰۳"
toEnDigits("۰۹۱۲ ٣٤٥");        // "0912 345"  (ارقام عربی هم)
onlyDigits("۰۹۱۲-۳۴۵ 67");     // "091234567"
formatNumber(1250000);         // "۱٬۲۵۰٬۰۰۰"
```

`toEnDigits` را همیشه پیش از ذخیرهٔ ورودی کاربر استفاده کنید؛ کاربر ایرانی ممکن است با هر دو صفحه‌کلید تایپ کند.

## عدد به حروف

```ts
import { numberToWords } from "@kashi-ui/persian";

numberToWords(1250000); // "یک میلیون و دویست و پنجاه هزار"
numberToWords(1001);    // "هزار و یک"
numberToWords(-45);     // "منفی چهل و پنج"
```

## یکدست‌سازی متن

کاربران با صفحه‌کلید عربی «ي» و «ك» تایپ می‌کنند و جستجوی «علی» دیگر «علي» را پیدا نمی‌کند. پیش از ذخیره و جستجو، متن را یکدست کنید:

```ts
import { normalizePersian } from "@kashi-ui/persian";

normalizePersian("علي كريمي");                 // "علی کریمی"
normalizePersian("مـــدرسه");                   // "مدرسه"   (حذف کشیده)
normalizePersian("كتاب ١٢", { digits: "fa" }); // "کتاب ۱۲"
```

برای متنی که کاربر می‌نویسد (توضیحات، نظرها، مقاله‌ها)، `fixPersianText` ویرایش نگارشی هم انجام می‌دهد: نیم‌فاصله، ویرگول و علامت سؤال فارسی و ارقام. تعداد هر نوع اصلاح را هم برمی‌گرداند. کامپوننت آن [ویرایش نگارشی](/docs/persian/text-fix/) است.

```ts
import { fixPersianText, fixKeyboardLayout } from "@kashi-ui/persian";

fixPersianText("كتاب ها را مي خوانم ?").text; // "کتاب‌ها را می‌خوانم؟"
fixKeyboardLayout("sghl");                     // "سلام" (صفحه‌کلید انگلیسی به فارسی)
```

## مبلغ

```ts
import { formatMoney, rialToToman } from "@kashi-ui/persian";

formatMoney(1250000);                              // "۱٬۲۵۰٬۰۰۰ تومان"
formatMoney(1250000, { compact: true });           // "۱٫۲۵ میلیون تومان"
formatMoney(125000000, { from: "rial", compact: true }); // "۱۲٫۵ میلیون تومان"
rialToToman(50000);                                // 5000
```

## اعتبارسنجی

```ts
import { isValidNationalId, isValidCardNumber, getBankByCard, formatCardNumber } from "@kashi-ui/persian";

isValidNationalId("0013542419");         // true
isValidLegalId("10380284790");           // true (شناسهٔ ملی شرکت)
isValidIban("IR062960000000100324200001");
isValidMobile("+98 912 345 6789");       // true
getMobileOperator("0935")?.name;          // "ایرانسل"
isValidCardNumber("4111111111111111");   // true
getBankByCard("610433");                 // { name: "بانک ملت", slug: "mellat" }
formatCardNumber("6104331234");          // "6104 3312 34"
isValidPostalCode("1193653471");         // true
formatPostalCode("1193653471");          // "11936-53471"
isValidPlate({ first: "12", letter: "ب", middle: "345", region: "67" }); // true
formatPlate({ first: "12", letter: "ب", middle: "345", region: "67" });  // "۱۲ ب ۳۴۵ ایران ۶۷"
plateType("ت");                          // "taxi"
isValidLandline("+98 21 8877 6655");     // true
getLandlineProvince("031");              // "اصفهان"
formatLandline("02188776655");           // "021 8877 6655"
```

## ساعت

```ts
import { parseTime, formatTime } from "@kashi-ui/persian";

parseTime("۹:۳۰");                       // { hours: 9, minutes: 30 }
parseTime("2145");                       // { hours: 21, minutes: 45 }
parseTime("25:00");                      // null
formatTime({ hours: 9, minutes: 5 });    // "09:05"
```

---

# Tailwind

URL: https://kashi.sepantapouya.com/docs/tailwind/

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

با پریست `@kashi-ui/tailwind`، توکن‌های کاشی در پروژهٔ Tailwind شما به‌شکل کلاس‌های آشنا در دسترس‌اند. کامپوننت‌های کاشی همان‌طور که هستند کار می‌کنند و برای بخش‌های دلخواه صفحه، به‌جای `bg-[var(--k-bg-secondary)]` می‌نویسید `bg-secondary`:

```tsx
<div className="bg-secondary border border-brand rounded-lg shadow-md p-4">
  <h3 className="text-primary text-lg font-semibold">سفارش‌های امروز</h3>
  <p className="text-tertiary text-sm">۱۲ سفارش تازه</p>
  <Button variant="primary">مشاهده</Button>
</div>
```

کلاس‌ها کپی رنگ‌ها نیستند؛ همه به همان متغیرهای کاشی (`var(--k-…)`) اشاره می‌کنند. پس تم تیره و روشن، رنگ برندی که با `createTheme` ساخته‌اید و هر نسخهٔ جدید کاشی، بدون هیچ کاری روی کلاس‌های Tailwind هم اعمال می‌شود. ساختار کاشی هم تغییری نمی‌کند؛ این پکیج فقط یک پل است.

## نصب

```bash
npm i @kashi-ui/react @kashi-ui/css @kashi-ui/tailwind
```

### Tailwind 4

در فایل CSS اصلی پروژه (مثلاً `app/globals.css`) این سه خط را **به همین ترتیب** بگذارید:

```css
@import "@kashi-ui/tailwind";
@import "tailwindcss";
@import "@kashi-ui/css";
```

> **ترتیب مهم است:** `@kashi-ui/tailwind` باید اول بیاید تا ترتیب لایه‌های CSS را تعیین کند و کلاس‌های Tailwind همیشه بر استایل کامپوننت‌های کاشی برنده باشند. با ترتیب دیگر، استایل کاشی برنده می‌شود و مثلاً `rounded-none` روی دکمه اثر نمی‌کند.

### Tailwind 3

در `tailwind.config.js` پریست را اضافه کنید و CSS کاشی را مثل همیشه وارد کنید. در Tailwind 3 کلاس‌ها بیرون از لایه‌ها ساخته می‌شوند و خودبه‌خود بر کاشی برنده‌اند:

```js
module.exports = {
  presets: [require("@kashi-ui/tailwind/preset")],
  content: ["./src/**/*.{js,ts,jsx,tsx}"],
};
```

```tsx
import "@kashi-ui/css";
```

## کلاس‌ها

### رنگ‌های معنایی

همان نام‌های توکن‌های کاشی، بدون پیشوند. این‌ها با تم تیره و روشن عوض می‌شوند و برای بیشتر رابط کاربری کافی‌اند.

<details class="tw-more">
<summary>فهرست متنی همهٔ رنگ‌های معنایی</summary>

پس‌زمینه `bg-primary`، `bg-secondary`، `bg-tertiary`، `bg-elevated`، `bg-hover`، `bg-active`، `bg-brand`، `bg-brand-hover`، `bg-brand-subtle`، `bg-error`، `bg-error-hover`، `bg-error-subtle`، `bg-warning-subtle`، `bg-success-subtle` و `bg-info-subtle`؛ متن `text-primary`، `text-secondary`، `text-tertiary`، `text-quaternary`، `text-on-brand`، `text-on-error`، `text-brand`، `text-error`، `text-warning`، `text-success` و `text-info`؛ حاشیه `border-primary`، `border-secondary`، `border-brand`، `border-input` و `border-error`. همهٔ حالت‌های Tailwind هم کار می‌کنند: `hover:bg-hover`، `focus:border-brand`، `md:bg-secondary`.

</details>

### طیف رنگ‌ها

طیف برند و رنگ‌های ایرانی کاشی، از ۵۰ تا ۹۵۰، با پشتیبانی از شفافیت مثل `bg-brand-500/50`. روی هر خانه بزنید تا کلاسش کپی شود:

نام طیف‌ها: `brand` (همان رنگی که `createTheme` می‌سازد)، `firoozeh` (فیروزه)، `lajvard` (لاجورد)، `zafaran` (زعفران)، `anar` (انار)، `pesteh` (پسته) و `shab` (شب)؛ مثل `bg-firoozeh-100`، `text-anar-600` یا `border-lajvard-300`.

### گردی و سایه

ضریب گردی کاشی (`--k-radius-factor`) روی همهٔ `rounded-*` ها اعمال می‌شود.

### متن، لایه و حرکت

| گروه | کلاس‌ها |
|---|---|
| فونت | `font-sans` (وزیرمتن یا فونت شما) · `font-display` · `font-mono` |
| اندازهٔ متن | `text-xs` تا `text-6xl`، با ضریب `--k-text-scale` |
| وزن | `font-light` · `font-regular` · `font-medium` · `font-semibold` · `font-bold` · `font-black` |
| ارتفاع خط | `leading-tight` · `leading-normal` · `leading-relaxed` |
| لایه | `z-dropdown` · `z-sticky` · `z-overlay` · `z-modal` · `z-toast` |
| حرکت | `ease-standard` · `ease-emphasized` |

فاصله‌ها (`p-4`، `gap-6`، `mt-8`) همان مقیاس پیش‌فرض Tailwind‌اند که با مقیاس کاشی (پله‌های ۴ پیکسلی) یکی است؛ `p-4` در هر دو ۱۶ پیکسل است.

## تم تیره و روشن

کاشی به‌طور پیش‌فرض تیره است و با `data-theme="light"` روی `<html>` روشن می‌شود. حالت‌های `dark:` و `light:` هم از همین پیروی می‌کنند:

```tsx
<div className="shadow-none light:shadow-sm">…</div>
```

برای بیشتر کارها به این حالت‌ها نیازی ندارید؛ رنگ‌های معنایی مثل `bg-secondary` خودشان با تم عوض می‌شوند.

## رنگ برند

تمی که با `createTheme` یا [تم‌ساز](/docs/theming/) می‌سازید، روی کلاس‌های Tailwind هم اعمال می‌شود:

```ts
import { createTheme } from "@kashi-ui/tokens";

const css = createTheme({ brand: "#3d5ef8", radius: 1.5 });
// حالا bg-brand، text-brand و rounded-lg هم لاجوردی و گردتر شده‌اند
```

## راست‌به‌چپ

Tailwind کلاس‌های منطقی دارد که در RTL و LTR درست کار می‌کنند؛ مثل کامپوننت‌های کاشی، به‌جای `ml-*` و `pr-*` از این‌ها استفاده کنید:

| به‌جای | بنویسید |
|---|---|
| `ml-4` / `mr-4` | `ms-4` / `me-4` |
| `pl-4` / `pr-4` | `ps-4` / `pe-4` |
| `left-0` / `right-0` | `start-0` / `end-0` |
| `text-left` | `text-start` |

برای جاهایی که واقعاً به جهت وابسته‌اند، حالت‌های `rtl:` و `ltr:` هم هست، مثل `rtl:rotate-180` برای فلش.

---

# سفارشی‌سازی و تم

URL: https://kashi.sepantapouya.com/docs/theming/

کاشی را با برند خود هماهنگ کنید؛ از یک رنگ تا جزئی‌ترین متغیر هر کامپوننت.

## تم‌ساز

تغییرات روی کل همین صفحه اعمال می‌شوند. کد تولیدشده را کپی کنید و در CSS پروژه بگذارید.

## چهار لایهٔ سفارشی‌سازی

### ۱. رنگ برند

همهٔ کامپوننت‌ها رنگ برند را از طیف `--k-brand-50` تا `--k-brand-950` می‌خوانند. تابع `createTheme()` این طیف را از یک رنگ می‌سازد:

```ts
import { createTheme } from "@kashi-ui/tokens";

const css = createTheme({ brand: "#7c3aed" });
// css را در یک تگ <style> یا فایل CSS قرار دهید
```

اگر طیف دقیق برندتان را دارید، آن را مستقیم بدهید:

```ts
createTheme({ brand: { 50: "#f5f3ff", 100: "#ede9fe", /* … */ 950: "#2e1065" } });
```

### ۲. پیچ‌های سراسری

| متغیر | پیش‌فرض | اثر |
|---|---|---|
| `--k-radius-factor` | `1` | ضریب همهٔ گوشه‌ها؛ `0` تیز، `2` بسیار گرد |
| `--k-density` | `1` | ضریب ارتفاع و فاصلهٔ داخلی کنترل‌ها؛ `0.875` فشرده |
| `--k-font-sans` | وزیرمتن | فونت اصلی؛ راهنمای کامل در [فونت و تایپوگرافی](/docs/typography/) |
| `--k-text-scale` | `1` | ضریب اندازهٔ همهٔ متن‌ها |

### ۳. متغیرهای هر کامپوننت

هر کامپوننت متغیرهای عمومی با الگوی `--k-{کامپوننت}-{ویژگی}` دارد. فهرست کامل در صفحهٔ هر کامپوننت آمده است.

```css
:root {
  --k-btn-radius: 999px;      /* دکمه‌های کاملاً گرد */
  --k-input-height-md: 3rem;  /* فیلدهای بلندتر */
}

/* فقط در یک بخش خاص */
.checkout {
  --k-card-padding: 2rem;
}
```

### ۴. کلاس برای هر بخش داخلی

کامپوننت‌های چندبخشی `classNames` می‌پذیرند تا بدون دستکاری CSS کاشی، هر بخش را جدا استایل دهید (مثلاً با Tailwind):

```tsx
<Input
  label="ایمیل"
  classNames={{ label: "text-lg", box: "rounded-full", control: "font-mono" }}
/>
<DataTable classNames={{ row: "h-14", header: "uppercase" }} … />
```

همچنین ریشهٔ کامپوننت‌ها ویژگی‌های `data-variant`، `data-size`، `data-tone`، `data-state` و `data-placement` دارند:

```css
.k-btn[data-variant="primary"][data-size="lg"] { letter-spacing: 0; }
.k-input[data-state="invalid"] { background: var(--k-bg-error-subtle); }
```

### ۵. بازنویسی مستقیم

همهٔ استایل‌های کاشی در Cascade Layer با نام `kashi` قرار دارند. هر CSS معمولی شما، با هر میزان اختصاصی بودن، روی آن‌ها اولویت دارد:

```css
/* بدون !important کار می‌کند */
.k-btn { letter-spacing: 0; }
```

> **دام رایج: استایل‌های سراسری عناصر.** چون CSS شما همیشه بر کاشی اولویت دارد، قاعده‌ای مثل `a { color: blue }` رنگ دکمه‌ای را هم که با `<a class="k-btn">` ساخته شده عوض می‌کند. دو راه حل:
>
> ```css
> /* ۱. دکمه‌ها را مستثنا کنید و اختصاصی بودن را صفر نگه دارید */
> :where(a:not(.k-btn)) { color: blue; }
>
> /* ۲. یا ریست‌ها و استایل‌های پایهٔ خودتان را در لایه‌ای پیش از کاشی بگذارید */
> @layer my-reset, kashi;
> @layer my-reset { a { color: blue; } }
> ```

## تم روشن و تیره

تم پیش‌فرض تیره است. ویژگی `data-theme` را روی `<html>` یا هر عنصری بگذارید:

```html
<html data-theme="light">
<section data-theme="dark">…</section>
```

برای پیروی از تنظیم سیستم کاربر:

```js
const dark = matchMedia("(prefers-color-scheme: dark)").matches;
document.documentElement.dataset.theme = dark ? "dark" : "light";
```

> طیفی که `createTheme()` می‌سازد خودکار از نظر کنتراست بررسی نمی‌شود. پس از انتخاب رنگ برند، کنتراست دکمهٔ اصلی را بررسی کنید.

---

# فونت و تایپوگرافی

URL: https://kashi.sepantapouya.com/docs/typography/

وزیرمتن پیش‌فرض است، ولی هر فونتی، رایگان یا خریداری‌شده، با یک خط قابل‌جایگزینی است.

## پیش‌نمایش زنده

فونت‌ها فقط هنگام انتخاب بارگذاری می‌شوند. کد تولیدشده را کپی کنید.

## سه متغیر برای فونت

| متغیر | پیش‌فرض | کاربرد |
|---|---|---|
| `--k-font-sans` | وزیرمتن | متن و همهٔ کامپوننت‌ها |
| `--k-font-display` | همان `--k-font-sans` | عنوان‌ها (h1 تا h6) |
| `--k-font-mono` | فونت سیستم + وزیرمتن | کد |
| `--k-text-scale` | `1` | ضریب اندازهٔ همهٔ متن‌ها |

## فونت رایگان

فونت را با npm نصب و CSS آن را وارد کنید، سپس نامش را به کاشی بدهید:

```ts
import "@fontsource-variable/estedad"; // npm i @fontsource-variable/estedad
import { createTheme } from "@kashi-ui/tokens";

const css = createTheme({ fontFamily: "Estedad Variable" });
```

یا فقط با CSS:

```css
@import "@fontsource-variable/estedad";
:root { --k-font-sans: "Estedad Variable", "Vazirmatn", Tahoma, sans-serif; }
```

<div class="table-wrap" role="region" aria-label="فونت‌های رایگان پیشنهادی" tabindex="0">
  <table class="ref-table">
    <thead><tr><th scope="col">فونت</th><th scope="col">پکیج npm</th><th scope="col">کاربرد</th><th scope="col">مجوز</th></tr></thead>
    <tbody>
      {fonts.map((f) => (
        <tr>
          <th scope="row">{f.name}</th>
          <td><code class="type">{f.pkg}</code></td>
          <td>{f.kind}؛ {f.note}</td>
          <td>{f.license}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

## فونت خریداری‌شده

فونت‌های تجاری مثل ایران‌سنس، یکان بخ، دانا یا پیدا مجوز جداگانه برای هر وب‌سایت دارند و نمی‌توان آن‌ها را در پکیج‌های عمومی منتشر کرد؛ فایل‌هایی را که خریده‌اید روی سرور خودتان بگذارید و به کاشی معرفی کنید:

```ts
import { createTheme } from "@kashi-ui/tokens";

const css = createTheme({
  fonts: [
    // فونت متغیر: یک فایل، همهٔ وزن‌ها
    { family: "IRANSansX", src: "/fonts/IRANSansXV.woff2", weight: "100 900" },
    // یا فونت ثابت: هر وزن یک فایل
    { family: "Yekan Bakh", src: "/fonts/YekanBakh-Regular.woff2", weight: 400 },
    { family: "Yekan Bakh", src: "/fonts/YekanBakh-Bold.woff2", weight: 700 },
  ],
  fontFamily: "IRANSansX",
  displayFontFamily: "Yekan Bakh",
});
// css شامل قواعد @font-face و متغیرهاست؛ آن را در یک <style> یا فایل CSS بگذارید
```

نام تنها (مثل `"IRANSansX"`) خودکار با وزیرمتن و فونت‌های سیستم کامل می‌شود تا تا زمان بارگذاری فونت اصلی، متن نامرئی نباشد.

> **حجم:** اگر از وزیرمتن استفاده نمی‌کنید، به‌جای `@kashi-ui/css` فایل `@kashi-ui/css/kashi.nofont.css` را وارد کنید تا فایل فونت (حدود ۱۱۰ کیلوبایت) در خروجی شما نیاید. مرورگر به‌هرحال فقط فونتی را دانلود می‌کند که واقعاً استفاده شود.

## حروف لاتین با فونت جدا

بیشتر فونت‌های فارسی حروف لاتین هم دارند. اگر برای متن انگلیسی فونت دیگری می‌خواهید، آن را **اول** بیاورید؛ مرورگر هر حرف را از اولین فونتی که آن را دارد می‌گیرد و چون Inter حروف فارسی ندارد، فارسی از فونت دوم خوانده می‌شود:

```css
:root { --k-font-sans: "Inter", "Vazirmatn", Tahoma, sans-serif; }
```

## اندازه و ارتفاع خط

فونت‌ها در یک اندازهٔ یکسان، درشتی متفاوتی دارند. با `textScale` (یا `--k-text-scale`) همهٔ اندازه‌ها را با هم کوچک یا بزرگ کنید، مثلاً `0.95` برای فونتی که درشت‌تر دیده می‌شود. ارتفاع خط با `--k-leading-normal` (پیش‌فرض ۱٫۷۵) قابل‌تغییر است؛ حروف فارسی به‌خاطر نقطه‌ها و دندانه‌ها فضای عمودی بیشتری از لاتین لازم دارند.

## ویژگی‌های فونت در createTheme

| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| fontFamily | string | — | فونت متن؛ نام تنها یا فهرست کامل |
| displayFontFamily | string | — | فونت عنوان‌ها |
| monoFontFamily | string | — | فونت کد |
| textScale | number | 1 | ضریب اندازهٔ متن‌ها |
| fonts | { family, src, weight?, style?, display?, unicodeRange? }[] | — | فایل‌های فونت برای ساخت @font-face |

`fontFace()` و `fontStack()` هم جداگانه از `@kashi-ui/tokens` صادر می‌شوند.