ساخت گزارش (ReportComposer)

معرفی

ReportComposer یک container برای ساخت گزارش/بولتن است: کاربر می‌تواند بخش‌ها (sections) را روشن/خاموش، collapse، یا drag-reorder کند. ReportSection building block هر بخش است. BulletinViewer همان داده در نمای read-only پرینت-friendly برای صفحه‌ی نهایی export.

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

• صفحه‌ی Bulletin Editor که analyst بخش‌ها را تنظیم می‌کند
• صفحه‌ی Bulletin Output / Print View برای ذخیره‌ی PDF
• داشبوردهای drag-and-drop سفارشی-سازی (با wiring native HTML5 DnD یا react-dnd)

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

• صفحات داشبورد فاقد ساختار Section → از Card و گرید معمولی استفاده کنید
• بخش‌های آماده مثل sentiment + flow → ReportSection خام نزنید، از section templates استفاده کنید

زمین بازی

با تغییر تنظیمات زیر، چیدمان گزارش را به‌صورت زنده مشاهده کنید.

استفاده

import {
  ReportComposer,
  ReportSection,
  BulletinViewer,
} from '@parto-system-design/ui'

// Editor mode
<ReportComposer
  title="بولتن هفتگی — هفته ۱۴"
  description="گزارش نظرات منتشره، ۷ تا ۱۳ خرداد"
  headerActions={<Button>ذخیره</Button>}
>
  <ReportSection
    title="خلاصه اجرایی"
    enabled={summaryOn}
    onEnabledChange={setSummaryOn}
    collapsed={summaryCollapsed}
    onCollapsedChange={setSummaryCollapsed}
  >
    <p>...</p>
  </ReportSection>
</ReportComposer>

// Print/output mode
<BulletinViewer
  title="بولتن هفتگی — هفته ۱۴"
  author="تیم تحلیل"
  publishedAt="۱۴ خرداد ۱۴۰۵"
  meta={[{ label: 'نسخه', value: '۱.۰' }]}
  headerActions={<Button>چاپ</Button>}
>
  <section>...</section>
</BulletinViewer>

ساختار

ReportComposer فقط wrapper سرتیتر است. ReportSection چندین slot دارد:

• enabled + onEnabledChange → Switch master toggle
• collapsed + onCollapsedChange → chevron collapse
• draggable + onDragHandlePointerDown → drag handle (consumer DnD wires)
• onSettingsClick → دکمه‌ی تنظیمات (popover خود را بسازید)
• headerActions → slot دکمه‌های اضافی

BulletinViewer در print mode headerActions را hide می‌کند (print:hidden)، content column عرض ثابت max-w-3xl دارد، و sectionها break-inside-avoid می‌گیرند تا روی هیچ صفحه‌ای نصف نشوند.

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

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

• 6 template آماده → Report Section Templates
• برای انتخاب template از یک palette → از CommandPalette استفاده کنید
• برای lifecycle ساخت bulletin async → JobWizard + ReportComposer در آخرین step

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

ReportComposer

ReportSection

BulletinViewer

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

• ReportComposer و BulletinViewer هر دو به‌صورت landmark <section> رندر می‌شوند؛ title به یک heading معنادار تبدیل می‌شود تا screen reader ساختار سند را بفهمد.
• ReportSection چندین کنترل keyboard-accessible دارد: Switch enable (Space toggle)، Button collapse (Enter/Space)، drag handle (pointerdown — consumer مسئول focus management هنگام drag است).
• درگ-اند-دراپ شورتکات keyboard ندارد به‌صورت native — اگر reorder حساس به a11y می‌خواهید، یک «انتقال به بالا/پایین» جایگزین در headerActions قرار دهید (recommended pattern).
• در BulletinViewer حالت چاپ (@media print)، header actions مخفی می‌شوند، sectionها break-inside-avoid می‌گیرند، و contrast text بالا حفظ می‌شود تا خروجی PDF خوانا باشد.
• aria-expanded روی collapse trigger و aria-pressed روی Switch enable به‌صورت خودکار ست می‌شوند.