نقشه حرارتی فراوانی انتشار (PostingFrequencyHeatmap)

معرفی

PostingFrequencyHeatmap نشان می‌دهد چه زمانی یک حساب پست می‌گذارد — ۷ روز هفته روی محور عمودی × ۲۴ ساعت روی محور افقی، با شدت رنگ متناسب با تعداد پست‌های آن cell. به‌علاوه، یک ردیف summary در بالا: نمره ثبات ۰-۱۰۰، طولانی‌ترین فاصله به روز، درصد روزهای فعال، و کل پست‌ها.

روی PartoHeatMap ساخته شده (با Visx) و فقط API دامنه‌ای اضافه می‌کند: ورودی sparse cells + summary.

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

• صفحه تحلیل یک پیج در پنل ارزیابی (Page-evaluation) — آیا حساب ثبات انتشار دارد؟
• بررسی worker Booster — در چه ساعتی فعال است؟
• ارائه bulletin به کمیته با «الگوی زمانی انتشار» یک clustering
• قبل از کمپین، بهترین ساعات publish را تشخیص دهید

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

• برای timeline رویدادها با جزئیات بیشتر — از ActionTimeline استفاده کنید
• نمایش سری زمانی (نه الگوی هفتگی) — از line-chart استفاده کنید
• تنها نشان دادن شمارنده کل — از MetricCard استفاده کنید
• heatmap عمومی با داده غیر-زمانی — از PartoHeatMap مستقیم استفاده کنید

زمین بازی

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

استفاده

'use client'
import { PostingFrequencyHeatmap } from '@parto-system-design/ui'

export function PageFrequency({ page }) {
  return (
    <PostingFrequencyHeatmap
      title="الگوی زمانی انتشار"
      description="۳۰ روز اخیر"
      data={page.heatmapCells}
      summary={{
        consistencyScore: page.freq.consistencyScore,
        maxGapDays: page.freq.consistencyDetails.maxGapDays,
        activeDaysRatio: page.freq.consistencyDetails.activeDaysRatio,
        totalPosts: page.freq.overall.totalPosts,
      }}
    />
  )
}

ساختار داده

ورودی یک آرایه sparse است؛ cellهای خالی به طور خودکار با مقدار صفر پر می‌شوند:

type PostingFrequencyCell = {
  dayOfWeek: number // 0-6 — شنبه=0 برای fa، یکشنبه=0 برای en
  hour: number // 0-23
  value: number // تعداد پست در آن ساعت از آن روز
}

هفته شنبه-شروع (fa/ar) vs. یکشنبه-شروع (en)

با weekStart="saturday" (پیش‌فرض در fa/ar)، ردیف صفر شنبه است. با weekStart="sunday" یا "monday" ترتیب ردیف‌ها تغییر می‌کند. این فقط ترتیب نمایش را تغییر می‌دهد — داده‌ای که پاس می‌دهید باید با convention انگلیسی باشد (۰=یکشنبه، ۱=دوشنبه، …).

summary row اختیاری

چهار tile:

• ثبات انتشار (۰-۱۰۰) — سبز (≥۸۰)، کهربایی (≥۴۰)، قرمز (کمتر از ۴۰)
• طولانی‌ترین فاصله (به روز) — سبز (≤۷)، کهربایی (۸-۱۴)، قرمز (بیشتر از ۱۴)
• روزهای فعال (درصد)
• کل پست‌ها

هر تایلی که مقدار undefined داشته باشد، رندر نمی‌شود.

بدون summary

با showSummary={false} یا حذف summary، فقط heatmap رندر می‌شود — مناسب embed در کارت‌های کوچک.

ارتفاع سفارشی

با chartHeight={160} heatmap فشرده‌تر می‌شود (حداقل ۱۶۰ توصیه می‌شود تا برچسب‌های ساعت خوانا بمانند).

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

Props

PostingFrequencyCell

PostingFrequencySummary

helpers

import { buildPostingFrequencyRows } from '@parto-system-design/ui'

// Normalize sparse cell array into the 7×24 HeatMapRow[] format
// that PartoHeatMap expects. Handles duplicates (sums them) and
// out-of-range inputs (ignored).
const rows = buildPostingFrequencyRows(cells, 'saturday')

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

• heatmap با role="img" + aria-label localized رندر می‌شود — screen reader می‌فهمد که این یک chart است.
• Summary tileها متن + رنگ دارند — معنا فقط با رنگ منتقل نمی‌شود.
• hover-tooltipها متن کامل برای cell فعال نشان می‌دهند (روز + ساعت + مقدار + متریک).
• xTickFilter پیش‌فرض هر ۳ ساعت یک tick نمایش می‌دهد تا محور افقی شلوغ نشود.

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

• PartoHeatMap — heatmap عمومی که این کامپوننت روی آن ساخته شده
• CriterionScoreCard — وقتی می‌خواهید فقط نمره ثبات را نمایش دهید، از آن استفاده کنید
• EntityHealthCard — heatmap می‌تواند در کنار سلامت entity compose شود
• ActionTimeline — timeline رویدادها با جزئیات بیشتر (نه الگوی هفتگی)
• line-chart — برای trend عددی در طول زمان