قالب‌های بخش گزارش (ReportSections)

معرفی

ReportComposer خود primitive container است؛ این مجموعه شش section template آماده است که 90٪ بخش‌های یک بولتن افکارسنجی را پوشش می‌دهند. هر template یک composition نازک از primitive های موجود (Distribution، Post، PartoLineChart، PlatformMark) داخل ReportSection shell است.

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

• وقتی بخش‌های استاندارد یک بولتن (خلاصه اجرایی، توزیع احساسات، روند زمانی، پست‌های برتر، منابع) را می‌سازید و نمی‌خواهید layout هر بخش را از صفر بنویسید
• وقتی بخش‌ها داخل ReportComposer یا BulletinViewer قرار می‌گیرند و به قابلیت‌های shell (فعال/غیرفعال، collapse، drag) نیاز دارید
• وقتی گزارش باید locale-aware باشد — عنوان پیش‌فرض هر بخش و فرمت اعداد بر اساس prop locale (fa/ar/en) خودکار تنظیم می‌شوند

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

• برای نمایش standalone یک نمودار خارج از بولتن — مستقیماً از Distribution یا PartoLineChart استفاده کنید
• وقتی layout بخش موردنظر با هیچ‌کدام از شش template منطبق نیست — به‌جای دور زدن props، یک ReportSection خام با محتوای سفارشی بسازید
• برای داشبوردهای تعاملی با فیلتر و drill-down — این templateها برای گزارش‌های ایستا و قابل چاپ طراحی شده‌اند

زمین بازی

استفاده

import { ReportComposer, ExecutiveSummarySection } from '@partodata/ui'

<ReportComposer title="بولتن هفتگی">
  <ExecutiveSummarySection
    summary="حجم گفت‌وگو درباره کمپین تخفیف فصلی نسبت به هفته گذشته رشد داشت."
    metrics={[{ label: 'تعداد پست', value: 4820, delta: 12.4 }]}
  />
</ReportComposer>

ترکیب کامل شش template کنار هم:

import {
  ReportComposer,
  ExecutiveSummarySection,
  SentimentBreakdownSection,
  FlowDistributionSection,
  TopPostsSection,
  TimelineSection,
  SourceBreakdownSection,
} from '@partodata/ui'
;<ReportComposer title="بولتن هفتگی">
  <ExecutiveSummarySection
    summary="نظرات مثبت روند صعودی داشت..."
    metrics={[
      { label: 'تعداد پست', value: 4820, delta: 12.4 },
      { label: 'سهم مثبت', value: 78, unit: '٪' },
    ]}
  />
  <SentimentBreakdownSection sentiment={sentiment} emotions={emotions} />
  <FlowDistributionSection flow={flow} />
  <TimelineSection data={dailyVolume} dataKeys={['volume']} summary={{ seriesKey: 'volume', from: 1240, to: 4820 }} />
  <TopPostsSection posts={topPosts} topN={5} />
  <SourceBreakdownSection
    sources={[
      { platform: 'instagram', count: 600 },
      { platform: 'twitter', count: 300 },
      { platform: 'telegram', count: 80 },
    ]}
  />
</ReportComposer>

شش Template

import { Sheet, SheetContent, SheetTitle, TopPostsSection } from '@partodata/ui'
import { Post, fromPostData } from '@partodata/ui/social'

const [openPost, setOpenPost] = React.useState<PostData | null>(null)

<TopPostsSection posts={topPosts} onOpen={setOpenPost} onOpenDetails={setOpenPost} />
<Sheet open={openPost !== null} onOpenChange={(open) => !open && setOpenPost(null)}>
  <SheetContent>
    <SheetTitle className="sr-only">جزئیات پست</SheetTitle>
    {openPost && <Post post={fromPostData(openPost)} layout="details" />}
  </SheetContent>
</Sheet>

ویژگی مشترک

هر شش template از ReportSectionShellProps ارث می‌برند، یعنی همه prop های slot ای ReportSection را پشتیبانی می‌کنند: enabled / onEnabledChange / collapsed / onCollapsedChange / draggable / onDragHandlePointerDown / onSettingsClick / headerActions. این اجازه می‌دهد در composer ادیتور هم استفاده شوند:

<ExecutiveSummarySection
  summary="..."
  enabled={summaryOn}
  onEnabledChange={setSummaryOn}
  collapsed={summaryCollapsed}
  onCollapsedChange={setSummaryCollapsed}
  draggable
  onDragHandlePointerDown={handleDragStart}
/>

عنوان پیش‌فرض هر template به‌صورت locale-aware: مثلاً ExecutiveSummarySection بدون title پاس‌دادن «خلاصه اجرایی» (fa) / «الملخص التنفيذي» (ar) / «Executive Summary» (en) رندر می‌کند. title prop آن را override می‌کند.

هر شش template همچنین isLoading را می‌پذیرند — چون داده هر بخش معمولاً مستقل fetch می‌شود، هر بخش باید بتواند وضعیت in-flight خودش را نشان دهد، نه اینکه با داده‌ی خالی یا صفر رندر شود:

<TimelineSection data={dailyVolume} dataKeys={['volume']} isLoading={isVolumeLoading} />

وقتی isLoading باشد، بخش به‌جای محتوای واقعی، Skeleton متناسب با layout خودش (پاراگراف + tile های متریک، bar نمودار، ردیف‌های منبع و…) نمایش می‌دهد.

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

تمام شش template از ReportSectionShellProps ارث می‌برند، یعنی این props مشترک‌اند:

پراپ‌های مشترک (همه‌ی templates)

ExecutiveSummarySection

SentimentBreakdownSection

FlowDistributionSection

TopPostsSection

TimelineSection

SourceBreakdownSection

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

• هر بخش با ReportSection shell wrap می‌شود که heading <h3> معنادار، landmark structure و کنترل‌های keyboard-accessible (Switch enable، Button collapse، drag handle) را تأمین می‌کند.
• چارت‌های داخلی (Distribution، PartoLineChart) خود ARIA labels و توضیحات text-summary مناسب رندر می‌کنند — <title> و <desc> در SVG.
• TrendIndicator در summary tile با aria-label مناسب (مثل «دلتا 12٪») جهت screen reader آماده می‌شود.
• در حالت چاپ، header actions (print:hidden) مخفی می‌شوند و sectionها break-inside-avoid می‌گیرند تا روی صفحه نصف نشوند.
• ترتیب tab روی sections از بالا به پایین RTL-aware است؛ drag handle قبل از Switch enable در tab order قرار می‌گیرد.

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

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

• container و shell → ReportComposer + ReportSection + BulletinViewer
• اگر template خودتان می‌خواهید → ReportSection خام بسازید
• پست‌های کامل به‌جای فهرست فشرده → EntityCollection از Post با چیدمان card
• توزیع به‌صورت standalone (نه داخل bulletin) → Distribution