چیپ برچسب (LabelChip)

معرفی

LabelChip یک چیپ فشرده برای نمایش برچسب‌های موضوعی و دسته‌بندی روی پست‌ها، خوشه‌ها و ردیف‌های جدول است — با شش tone رنگی، پنج اندازه، نشانگر «تولیدشده توسط هوش مصنوعی» به‌همراه درصد اطمینان، و دکمه‌های ویرایش و حذف درون‌خطی.

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

• نمایش برچسب‌های موضوعی و کمپینی روی پست‌ها و خوشه‌های تحلیلی (مانند «کمپین تخفیف فصلی» یا «بازخورد بسته‌بندی»)
• در داشبوردهای خوشه‌بندی هوشمند، برای تفکیک برچسب‌های خودکار (aiGenerated) از برچسب‌های انسانی
• وقتی کاربر باید بتواند برچسب را همان‌جا ویرایش یا حذف کند (onEdit / onRemove) یا با کلیک روی آن فید را فیلتر کند (onSelect)

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

• برای نمایش فیلترهای فعال جستجو در نوار فیلتر — از FilterChip استفاده کنید
• برای نشان دادن وضعیت یا شمارنده ایستا بدون هیچ تعاملی — Badge ساده‌تر و کافی است
• وقتی کاربر باید خودش تگ جدید تایپ و اضافه کند — از TagInput استفاده کنید

استفاده

import { LabelChip } from '@partodata/ui'

<LabelChip tone="brand" onRemove={() => removeLabel('seasonal-campaign')}>
  کمپین تخفیف فصلی
</LabelChip>

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

رنگ‌ها و اندازه‌ها

از prop tone برای تعیین رنگ چیپ استفاده کنید — شش حالت دارد: neutral (پیش‌فرض)، brand، success، warning، destructive و ai. prop size پنج اندازه دارد: xs، sm (پیش‌فرض)، md، lg و xl — از xs برای جدول‌های فشرده و از lg/xl برای هدر یک خوشه استفاده کنید.

<LabelChip tone="neutral">دسته‌بندی عمومی</LabelChip>
<LabelChip tone="brand">کمپین تخفیف فصلی</LabelChip>
<LabelChip tone="success">بازخورد مثبت بسته‌بندی</LabelChip>
<LabelChip tone="warning">در انتظار بازبینی</LabelChip>
<LabelChip tone="destructive">شکایت مشتری</LabelChip>
<LabelChip size="xs" tone="brand">اندازه xs</LabelChip>
<LabelChip size="md" tone="brand">اندازه md</LabelChip>
<LabelChip size="lg" tone="brand">اندازه lg</LabelChip>

برچسب هوش مصنوعی

با aiGenerated یک پیشوند ✦ ظریف به ابتدای چیپ اضافه می‌شود و اگر tone را صریح تنظیم نکرده باشید، tone مخصوص ai به‌صورت خودکار اعمال می‌شود. با confidence (عددی بین 0 و 1) میزان اطمینان مدل به‌صورت درصد گردشده در انتهای چیپ نمایش داده می‌شود. رقم‌ها با ارقام لاتین نوشته و شکل فارسی آن‌ها توسط قابلیت ss01 فونت یکان بخ رندر می‌شود؛ هیچ تبدیل عددی در جاوااسکریپت انجام نمی‌شود تا کپی/جست‌وجو (Ctrl+F) و خواندن صفحه‌خوان سالم بماند.

<LabelChip aiGenerated confidence={0.87}>
  گفتمان درباره برند
</LabelChip>

ویرایش و حذف درون‌خطی

با تنظیم onEdit دکمه مداد و با تنظیم onRemove دکمه ✕ در انتهای چیپ رندر می‌شود. باز کردن ویرایشگر بر عهده مصرف‌کننده است — کامپوننت فقط رویداد را گزارش می‌کند.

<LabelChip onEdit={() => openLabelEditor('packaging')} onRemove={() => removeLabel('packaging')}>
  بازخورد بسته‌بندی
</LabelChip>

چیپ قابل کلیک

با تنظیم onSelect کل چیپ قابل کلیک و قابل فوکوس می‌شود — مناسب جریان «فیلتر بر اساس برچسب». دکمه‌های ویرایش و حذف داخلی، کلیک خودشان را از onSelect جدا نگه می‌دارند.

<LabelChip tone="brand" onSelect={() => filterByLabel('seasonal-campaign')}>
  کمپین تخفیف فصلی
</LabelChip>

حالت انتخاب‌شده و غیرفعال

وقتی onSelect برای فیلتر بر اساس برچسب استفاده می‌شود، با selected مشخص کنید کدام برچسب‌ها هم‌اکنون به‌عنوان فیلتر فعال هستند — چیپ data-selected و aria-pressed می‌گیرد و حاشیه‌اش پررنگ‌تر می‌شود. با disabled می‌توانید یک برچسب را موقتاً غیرقابل‌اعمال کنید؛ کلیک، کیبورد و دکمه‌های ویرایش/حذف همه غیرفعال می‌شوند.

<LabelChip tone="brand" selected onSelect={() => filterByLabel('seasonal-campaign')}>
  کمپین تخفیف فصلی
</LabelChip>
<LabelChip tone="brand" disabled onSelect={() => filterByLabel('seasonal-campaign')}>
  کمپین تخفیف فصلی
</LabelChip>

helper به نام labelChipVariants

اگر فقط استایل چیپ را برای یک عنصر دیگر نیاز دارید، می‌توانید از helper کلاس‌ساز labelChipVariants استفاده کنید.

import { labelChipVariants } from '@partodata/ui'

<span className={labelChipVariants({ tone: 'success', size: 'md' })}>بازخورد مثبت بسته‌بندی</span>

با توضیح (کارت برچسب تحلیلی)

یک قاعده برای همهٔ برچسب‌های تحلیلی (برچسب‌های طبقه‌بندی Comment و Post، SentimentBadge و همین چیپ): با description، اشاره‌گر یا فوکوس صفحه‌کلید روی چیپ کارتی باز می‌کند با نام برچسب، معنای آن و — اگر confidence داده باشید — اطمینان مدل با نوار.

<LabelChip aiGenerated confidence={0.82} description="گفت‌وگو دربارهٔ بسته‌بندی و ظاهر محصول">
  بسته‌بندی
</LabelChip>

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

Props

سایر ویژگی‌های استاندارد span (مانند className و id) نیز به عنصر ریشه منتقل می‌شوند — به‌جز onClick که عمداً حذف شده است؛ به‌جای آن از onSelect استفاده کنید.

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

• بدون onSelect، چیپ یک span غیرتعاملی است و در ترتیب فوکوس صفحه قرار نمی‌گیرد.
• با onSelect، چیپ role="button" و tabIndex صفر می‌گیرد و با Enter یا Space فعال می‌شود (اسکرول پیش‌فرض Space جلوگیری می‌شود). تا وقتی چیپ قابل کلیک است، aria-pressed هم مطابق selected تنظیم می‌شود — کاربر صفحه‌خوان می‌فهمد کدام برچسب‌ها هم‌اکنون فیلتر فعال هستند.
• دکمه‌های ویرایش و حذف، عنصر button واقعی با aria-label فارسی («ویرایش برچسب» و «حذف برچسب») هستند و کلیک آن‌ها با stopPropagation از فعال شدن onSelect جدا می‌ماند. فشردن Enter یا Space روی این دکمه‌ها هم فقط خودِ دکمه را فعال می‌کند؛ رویداد کیبورد چیپ فقط وقتی اجرا می‌شود که فوکوس روی خودِ چیپ باشد.
• جعبه بصری دکمه‌های ویرایش و حذف 14 پیکسل است، اما هدف لمسی/اشاره‌گر آن‌ها با utility داخلی hit-area بدون تغییر چیدمان به حدود 26 پیکسل بزرگ‌تر می‌شود (حداقل WCAG 2.5.8).
• disabled هم روی ریشه (aria-disabled + کلیک/کیبورد غیرفعال) و هم روی خود دکمه‌های ویرایش و حذف (attribute استاندارد disabled) اعمال می‌شود.
• پیشوند ✦ برچسب هوش مصنوعی و آیکون‌های داخلی با aria-hidden از صفحه‌خوان مخفی هستند — اطلاعات از طریق متن برچسب منتقل می‌شود.
• حلقه فوکوس با focus-visible:ring-2 و رنگ برند نمایش داده می‌شود.
• درصد اطمینان با ارقام لاتین رندر می‌شود و شکل فارسی آن از قابلیت ss01 فونت می‌آید (بدون Intl.NumberFormat)، تا مقدار قابل کپی، قابل جست‌وجو و قابل خواندن برای صفحه‌خوان بماند. کلاس tabular-nums روی آن قرار دارد ولی در فونت یکان بخ بی‌اثر است، چون tnum ندارد.

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

• Badge — اگر فقط یک برچسب یا وضعیت ایستا بدون ویرایش، حذف و کلیک نیاز دارید، Badge ساده‌تر است.
• FilterChip — اگر فیلترهای فعال جستجو را نمایش می‌دهید و کاربر باید بتواند آن‌ها را بردارد، FilterChip گزینه درست است: روی صفحهٔ فهرست فقط برای فیلترهایی که بیرون از نوارابزار تنظیم شده‌اند، در activeFilters قالب ListPage؛ و در ردیف فیلتر یک پنل در FilterBar.
• TagInput — اگر کاربر باید خودش تگ جدید وارد کند، TagInput ورودی و مدیریت تگ را یک‌جا فراهم می‌کند.
• ActionTypeChip — اگر نوع یک عملیات شبکه اجتماعی (پسند، نظر، ذخیره و مانند آن) را نمایش می‌دهید، از چیپ domain-specific آن استفاده کنید.
• Label — برای برچسب فیلدهای فرم است و با وجود شباهت نام، ارتباطی با چیپ برچسب موضوعی ندارد.