Item

معرفی

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

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

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

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

  • برای دادهٔ ردیف‌وستونیِ قابلِ مرتب‌سازی/فیلتر → از DataTable استفاده کنید.
  • برای محتوای دامنه‌ایِ غنی (پستِ شبکه‌اجتماعی، حسابِ اینفلوئنسر) → از Post / Account (@partodata/ui/social) استفاده کنید.
  • برای کنترل‌های فرم با برچسب و خطا → از 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 (قابِ 32px با پس‌زمینهٔ ملایم برای آیکون)، و image (قابِ 40px با object-cover برای تصویرِ کوچک).

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

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

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

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

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

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

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

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

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