Item

معرفی

Item یک بلوکِ ترکیبیِ عمومی برای ساختنِ یک «ردیف» است: آیکون/مدیا در ابتدای خط، عنوان و توضیح در میانه، و اقدام‌ها در انتهای خط. این کامپوننت، مکملِ نمایشیِ Field است (که برای کنترل‌های فرم است) و جایگزینِ بازنویسیِ دستیِ چیدمانِ ردیف در هر جای محصول می‌شود.

• چه زمانی استفاده کنیم

  • فهرستِ تنظیمات، اعلان‌ها، یا نتایج که هرکدام آیکون + متن + اقدام دارند.
  • مینی‌کارت‌های یک‌خطی/دوخطی که به یک کامپوننتِ دامنه‌ایِ اختصاصی (مثل PostCard) نیاز ندارند.
  • وقتی می‌خواهید چند ردیف با فاصله و تراز یکدست، بدون بازنویسیِ flex، داشته باشید.

• چه زمانی استفاده نکنیم

  • برای دادهٔ ردیف‌وستونیِ قابلِ مرتب‌سازی/فیلتر → از DataTable استفاده کنید.
  • برای محتوای دامنه‌ایِ غنی (پستِ شبکه‌اجتماعی، پروفایلِ اینفلوئنسر) → از PostCard/ProfileCard استفاده کنید.
  • برای کنترل‌های فرم با برچسب و خطا → از Field استفاده کنید.

استفاده

import {
  Item,
  ItemGroup,
  ItemMedia,
  ItemContent,
  ItemTitle,
  ItemDescription,
  ItemActions,
} from '@partodata/ui'
import { Bell } from 'lucide-react'
import { Button } from '@partodata/ui'

;<ItemGroup>
  <Item variant="outline">
    <ItemMedia variant="icon">
      <Bell className="size-4" />
    </ItemMedia>
    <ItemContent>
      <ItemTitle>اعلان‌های کمپین</ItemTitle>
      <ItemDescription>وقتی نرخ تعامل از آستانه عبور کرد، خبرم کن.</ItemDescription>
    </ItemContent>
    <ItemActions>
      <Button variant="outline" size="sm">
        پیکربندی
      </Button>
    </ItemActions>
  </Item>
</ItemGroup>

Item یک ردیفِ flex است؛ چون از خواصِ منطقی (logical) استفاده می‌کند، مدیا در ابتدای خط و اقدام‌ها در انتهای خط قرار می‌گیرند و در RTL و LTR هر دو درست می‌چرخند — بدونِ هیچ left/right فیزیکی.

حالت‌ها و انواع

سه نوعِ ظاهری:

<Item variant="default">…</Item>   {/* بدون کادر — فهرست‌های چگال */}
<Item variant="outline">…</Item>   {/* کادردار — هر ردیف یک واحد مجزا */}
<Item variant="muted">…</Item>     {/* پس‌زمینه ملایم — تأکید سبک */}

اندازه‌ها: پیش‌فرض sm (ردیفِ فشرده)؛ md برای تراکمِ کارت‌مانندِ بازتر.

<Item size="md">…</Item>

ItemMedia سه نوع دارد: default (بدونِ قاب)، icon (قابِ ۳۲px با پس‌زمینهٔ ملایم برای آیکون)، و image (قابِ ۴۰px با object-cover برای تصویرِ کوچک).

با asChild می‌توانید کلِ ردیف را به یک لینک یا دکمه تبدیل کنید؛ در این حالت افوردنسِ hover (پس‌زمینهٔ surface-200) روشن می‌شود:

<Item asChild variant="outline">
  <a href="/reports/weekly">…</a>
</Item>

راهنمای استفاده

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

زیرکامپوننت‌ها

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

• ItemGroup نقشِ list و ItemSeparator نقشِ separator با aria-orientation="horizontal" دارند.
• برای ردیفِ کلیک‌پذیر، asChild روی یک <a>/<button> بگذارید تا عنصر واقعاً قابلِ فوکوس و کیبوردپذیر باشد؛ حلقهٔ فوکوس با زبانِ فوکوسِ دیزاین‌سیستم (ring خنثی + offset) رندر می‌شود.
• هر زیربخش یک data-slot دارد تا استایل‌دهی و تست هدفمند باشد.

کامپوننت‌های مرتبط

• Field — اگر ردیف شامل کنترلِ فرم با برچسب/خطاست، از Field استفاده کنید نه Item.
• DataTable — اگر به مرتب‌سازی/فیلتر/ستون نیاز دارید، DataTable نه فهرستِ Item.
• Empty — برای حالتِ خالیِ همان فهرست.
• Card — برای بلوکِ محتواییِ بزرگ‌تر با هدر/بدنه/فوتر مجزا.