ردیف عملکرد هشتگ (HashtagPerformanceRow)

معرفی

HashtagPerformanceRow یک ردیف واحد در جدول یا لیست عملکرد هشتگ است. در یک سطر 40 پیکسلی (یا 28 پیکسلی در حالت فشرده) پنج قطعه اطلاعات را کنار هم می‌چیند: رتبه (اختیاری)، نام هشتگ با علامت #، بسامد استفاده به‌صورت خلاصه‌شده (مثلاً «12.8 هزار»)، نرخ تعامل، اسپارک‌لاین روند و دلتای درصدی تغییر. اگر delta صریح ندهید، خود کامپوننت آن را از مقایسه اولین و آخرین نقطه آرایه trend محاسبه می‌کند.

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

• لیست «هشتگ‌های برتر» در داشبورد پایش برند یا گزارش کمپین (مثلاً مقایسه کمپین تخفیف فصلی با رونمایی محصول جدید)
• به‌عنوان cell renderer داخل DataTable برای ساخت جدول کامل عملکرد هشتگ‌ها
• هر جایی که کاربر باید فهرستی از هشتگ‌ها را سریع اسکن کند و روند صعودی/نزولی را در یک نگاه ببیند

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

• نمایش نمودار روند بزرگ و مستقل → از Sparkline یا LineChart استفاده کنید
• گرفتن هشتگ از کاربر به‌عنوان ورودی فرم → از TagInput با prefix="#" استفاده کنید
• نمایش یک شاخص منفرد با عدد بزرگ و دلتا → از MetricCard استفاده کنید

استفاده

import { HashtagPerformanceRow, type HashtagPerformanceData } from '@partodata/ui'

const data: HashtagPerformanceData = {
  tag: 'کمپین_تخفیف_فصلی', // بدون # ابتدایی — کامپوننت خودش علامت را رندر می‌کند
  frequency: 12800,
  engagementRate: 4.8,
  trend: [820, 940, 1010, 1180, 1290, 1420, 1560],
}

export default function Example() {
  return <HashtagPerformanceRow data={data} rank={1} />
}

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

ردیف باریک (کارت موبایل)

ستون‌ها از عرض خود ردیف پیروی می‌کنند (container query)، نه عرض صفحه: زیر 448 پیکسل اسپارک‌لاین و زیر 384 پیکسل ستون نرخ تعامل حذف می‌شود؛ هشتگ هرچه می‌ماند می‌گیرد و با «…» کوتاه می‌شود (با فوکوس یا قرار گرفتن نشانگر موس روی آن کامل دیده می‌شود)، و هیچ ستونی از کارت بیرون نمی‌زند.

چگالی (density)

دو چگالی دارد: comfortable (پیش‌فرض، ارتفاع 40 پیکسل) و compact (ارتفاع 28 پیکسل). در حالت فشرده، اسپارک‌لاین برای صرفه‌جویی در فضا حذف می‌شود اما دلتا و آیکن روند باقی می‌مانند.

<HashtagPerformanceRow data={data} density="comfortable" />
<HashtagPerformanceRow data={data} density="compact" />

رتبه (rank)

با prop عددی rank، یک چیپ رتبه در ابتدای ردیف نمایش داده می‌شود — مناسب لیست‌های «10 هشتگ برتر». عدد رتبه مطابق locale بومی‌سازی می‌شود.

{
  topHashtags.map((item, index) => <HashtagPerformanceRow key={item.tag} data={item} rank={index + 1} />)
}

ردیف قابل کلیک (onRowClick)

با دادن onRowClick، کل ردیف تبدیل به یک عنصر تعاملی می‌شود: نشانگر ماوس pointer، افکت hover، حلقه فوکوس برند، و فعال‌سازی با Enter و Space. رویداد کلیک همان شیء HashtagPerformanceData را برمی‌گرداند تا drill-down تحلیلی سمت مصرف‌کننده باز شود.

<HashtagPerformanceRow data={data} rank={1} onRowClick={(item) => openHashtagAnalytics(item.tag)} />

دلتای صریح در برابر دلتای مشتق‌شده

• اگر delta بدهید، همان مقدار نمایش داده می‌شود — مناسب وقتی محاسبه دوره‌به‌دوره را backend انجام داده است.
• اگر delta ندهید ولی trend حداقل دو نقطه داشته باشد، دلتا از درصد تغییر اولین تا آخرین نقطه محاسبه می‌شود (گرد‌شده تا یک رقم اعشار).
• اگر هیچ‌کدام موجود نباشد (یا اولین نقطه trend صفر باشد)، بخش دلتا اصلاً رندر نمی‌شود.

آیکن روند بر اساس مقدار دلتا انتخاب می‌شود: بالای 1+ درصد فلش صعودی با رنگ مثبت، زیر 1- درصد فلش نزولی با رنگ منفی، و بازه بین این دو خط تخت با رنگ خنثی — تا نوسان‌های جزئی به‌اشتباه «روند» جلوه نکنند.

اما رنگ سبز یعنی «خبر خوب»، و افزایش بسامد یک هشتگ خبر خوب نیست. برای فهرست هشتگ‌ها tone="neutral" بدهید: پیکان و علامت همان‌اند (از علامت دلتا) ولی رنگ آرام می‌شود و اسپارک‌لاین هم خنثی می‌شود. فقط وقتی تغییر واقعاً خوب یا بد است (مثلاً هشتگی که منفی‌گویی را می‌شمارد) positive یا negative بدهید.

<HashtagPerformanceRow data={data} tone="neutral" />

// دلتای محاسبه‌شده توسط backend، بدون اسپارک‌لاین
<HashtagPerformanceRow data={{ tag: 'باشگاه_مشتریان', frequency: 1900, delta: -3.2 }} />

// دلتای مشتق‌شده از trend
<HashtagPerformanceRow
  data={{ tag: 'بازخورد_بسته_بندی', frequency: 3100, trend: [300, 310, 295, 305, 302] }}
/>

ترکیب با DataTable

این کامپوننت برای قرار گرفتن مستقیم داخل cell renderer طراحی شده است:

import { DataTable, HashtagPerformanceRow, type HashtagPerformanceData } from '@partodata/ui'

interface HashtagRow extends HashtagPerformanceData {
  rank: number
}

;<DataTable<HashtagRow>
  columns={[
    {
      id: 'hashtag',
      header: 'هشتگ',
      cell: (row) => <HashtagPerformanceRow data={row} rank={row.rank} />,
    },
  ]}
  data={hashtags}
/>

بومی‌سازی (locale)

پیش‌فرض locale مقدار fa است: بسامد با formatLargeNumber خلاصه و فارسی‌سازی می‌شود («12.8 هزار»)، و رتبه، نرخ تعامل و دلتا با ارقام فارسی نمایش داده می‌شوند. مقادیر ar و en نیز پشتیبانی می‌شوند.

<HashtagPerformanceRow data={data} locale="en" />

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

Props

HashtagPerformanceRow

علاوه بر props زیر، تمام attributes استاندارد div (به‌جز onClick که با onRowClick جایگزین شده) پذیرفته می‌شود و ref نیز forward می‌شود.

HashtagPerformanceData

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

• بدون onRowClick، ردیف یک عنصر غیرتعاملی است: نه role دارد، نه tabIndex، و در ترتیب فوکوس صفحه قرار نمی‌گیرد.
• با onRowClick، ردیف role="button" و tabIndex=0 می‌گیرد و با Enter یا Space فعال می‌شود (Space صفحه را اسکرول نمی‌کند).
• حالت فوکوس کیبورد با حلقه focus-visible به رنگ برند مشخص می‌شود.
• اسپارک‌لاین aria-label توصیفی با نام هشتگ دارد («روند» + نام هشتگ) تا برای صفحه‌خوان قابل فهم باشد.
• مقدار دلتا علاوه بر نمایش بصری، aria-label عددی («دلتا» + درصد) دارد.
• آیکن‌های تزئینی (علامت هشتگ و فلش روند) با aria-hidden از درخت دسترسی‌پذیری خارج شده‌اند؛ اطلاعات روند از طریق متن دلتا منتقل می‌شود.
• ارقام با tabular-nums رندر می‌شوند تا ستون‌ها در لیست‌های عمودی تراز بمانند.

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

• Sparkline — اگر فقط نمودار روند کوچک می‌خواهید بدون ساختار ردیف هشتگ (همین کامپوننت داخلاً از آن استفاده می‌کند).
• DataTable — اگر مرتب‌سازی، صفحه‌بندی یا فیلتر ستونی لازم دارید، این ردیف را داخل cell renderer آن قرار دهید.
• TagInput با prefix="#" — برای گرفتن هشتگ از کاربر به‌عنوان ورودی فرم، نه نمایش عملکرد.
• MetricCard — اگر یک شاخص منفرد با عدد بزرگ و دلتا می‌خواهید، نه ردیف فهرستی.
• LineChart — برای تحلیل عمیق روند یک هشتگ در نمای بزرگ با محور و tooltip.