معرفی

خانوادهٔ Page* مجموعهٔ ساختاریافته و اسلات‌محور چیدمان صفحه است، برگرفته از نسل جدید Page* سوپابیس و برای RTL امن‌شده (فقط خصوصیات منطقی، container-query محور). این خانواده سه لایه دارد: کانتینر عرض (PageContainer)، سربرگ ترکیبی صفحه (PageHeaderRoot + اجزایش) و بخش‌های صفحه (PageSection + اجزایش)، به‌علاوهٔ کرومِ تمام‌عرض (PageBreadcrumbs، PageNav).

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

• PageSection و اجزایش: بخش‌های محتوای یک CustomPage (صفحه‌ای که در هیچ قالبی جا نمی‌شود و DS-GAP دارد)، هر بخش با عنوان/توضیح/اقدام‌ها و بدنه
• PageContainer و PageHeaderRoot: فقط در کد خود سیستم طراحی، برای ساختن یک قالب یا بلوک صفحه‌ای

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

• برای ساختن یک صفحهٔ محصول — هر صفحه یک قالب صفحه است که عرض، سرِ صفحه، ریتم، اقدام‌ها و حالت‌ها را خودش می‌دهد؛ PageContainer یا سربرگی از خودتان ننویسید (قاعدهٔ ESLint parto/page-template)
• برای سرِ صفحه‌ای با زبانه، متا یا راه بازگشت — DetailPage (tabs، meta، back)
• برای چیدمان داخل یک کارت یا بخش کوچک — از Card/FormHeader استفاده کنید
• برای صفحات مستندات یا محتوای متنی که فریم‌ورک خودش را دارد

استفاده

در صفحهٔ محصول این خانواده فقط به شکل PageSectionها درون یک CustomPage می‌آید؛ سرِ صفحه، عرض و ریتم را خود قالب می‌دهد:

'use client'
import {
  Button,
  PageSection,
  PageSectionContent,
  PageSectionDescription,
  PageSectionMeta,
  PageSectionSummary,
  PageSectionTitle,
} from '@partodata/ui'
import { Icons } from '@partodata/ui/icons'
import { CustomPage } from '@partodata/ui/templates'

declare function createBulletin(): void

export default function CampaignReportPage() {
  return (
    // A page is ONE template; one that fits none is a CustomPage, whose content is PageSections.
    <CustomPage
      dsGap="DS-GAP-15: گزارش ترکیبی کمپین"
      title="گزارش کمپین تخفیف فصلی"
      description="نمای کلی عملکرد کمپین در شبکه‌های اجتماعی"
      primaryAction={
        <Button onClick={createBulletin} iconStart={<Icons.plus />}>
          ساخت بولتن
        </Button>
      }
    >
      <PageSection>
        <PageSectionMeta>
          <PageSectionSummary>
            <PageSectionTitle>پوشش انتشار</PageSectionTitle>
            <PageSectionDescription>تعداد پست‌های منتشرشده به تفکیک پلتفرم</PageSectionDescription>
          </PageSectionSummary>
        </PageSectionMeta>
        <PageSectionContent>{/* جدول یا نمودار */}</PageSectionContent>
      </PageSection>
    </CustomPage>
  )
}

اجزا و ساختار

PageContainer — کانتینر عرض

عرض حداکثر و padding افقی محتوا را تعیین می‌کند و context @container است که هر container-query داخلی نسبت به آن حل می‌شود. اندازه‌ها: small (768px)، default (1200px)، large (1600px)، full (بدون حد). اندازه را نوع صفحه تعیین می‌کند: small فرم و تنظیمات، default فهرست و جزئیات، large داشبورد و تحلیل، full فقط جدول بسیار پهن یا لاگ (هندسهٔ صفحه).

<PageContainer size="default">{/* محتوا */}</PageContainer>

PageHeaderRoot — سربرگ ترکیبی

سربرگ ترکیبی (آیکون، ردیف متا، تب‌های ناوبری)، جزء سطح پایینی برای کد خود سیستم طراحی؛ در صفحهٔ محصول نوشته نمی‌شود (صفحه‌ای که زبانه یا متا در سرش لازم دارد DetailPage است). بیرون از PageContainer (شکل پیش از 4.0) size را از طریق context به اجزای خودپیچ می‌دهد. اجزای آن:

• PageHeaderMeta — ردیف متا: چیدمان آیکون / خلاصه / aside
• PageHeaderIcon — آیکون پیشرو
• PageHeaderSummary — پشتهٔ عنوان + توضیح
• PageHeaderTitle — عنوان صفحه (h1، 24px، وزن متوسط)
• PageHeaderDescription — متن پشتیبان زیر عنوان
• PageHeaderAside — خوشهٔ اقدامات (دکمه، منو)؛ اقدام اصلی آخرین دکمه و تنها دکمهٔ variant="primary" آن است (از 4.0 دکمهٔ بی‌variant خنثی است)
• PageHeaderNavigationTabs — فوتر تب‌های ناوبری سربرگ
• PageHeaderBreadcrumb — ردیف breadcrumb داخل سربرگ (زیرجزء legacy؛ برای صفحات جدید PageBreadcrumbs را ترجیح دهید)

PageSection — بخش صفحه

هر بخش 48px ریتم بالا، 24px فاصلهٔ داخلی و 48px دنبالهٔ آخرین بخش دارد. با orientation="horizontal" به یک گرید 1fr/2fr (متا ⁄ محتوا) در @3xl تقسیم می‌شود. اجزای آن:

• PageSectionMeta — ردیف متا: خلاصه + aside
• PageSectionSummary — پشتهٔ عنوان + توضیح
• PageSectionTitle — عنوان بخش (h2، 20px، وزن متوسط)
• PageSectionDescription — متن پشتیبان زیر عنوان بخش
• PageSectionAside — خوشهٔ اقدامات بخش
• PageSectionContent — بدنهٔ اصلی بخش (فرم، جدول، گرید)

کرومِ تمام‌عرض — PageBreadcrumbs و PageNav

این دو ردیفِ کرومِ تمام‌عرض‌اند که بالای سربرگ و بیرون از PageContainer می‌نشینند، نه داخل سربرگ. (داخل یک PageContainer هم ظرف دومی نمی‌سازند و به عرض آن ظرف درمی‌آیند.) مسیر بازگشت و زبانه‌های یک صفحهٔ محصول را قالبش می‌دهد (back، breadcrumbs، tabs)؛ این دو برای کد خود سیستم طراحی‌اند:

import {
  PageBreadcrumbs,
  PageBreadcrumbsActions,
  PageNav,
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbPage,
  Button,
} from '@partodata/ui'
;<>
  <PageBreadcrumbs
    actions={
      <PageBreadcrumbsActions>
        <Button variant="default">اقدام</Button>
      </PageBreadcrumbsActions>
    }
  >
    <BreadcrumbList>
      <BreadcrumbItem>
        <BreadcrumbLink href="/campaigns">کمپین‌ها</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbItem>
        <BreadcrumbPage>کمپین تخفیف فصلی</BreadcrumbPage>
      </BreadcrumbItem>
    </BreadcrumbList>
  </PageBreadcrumbs>

  <PageNav>{/* یک NavMenu یا nav تب‌ها */}</PageNav>
</>

هر دو ردیف با PageContainer inset="chrome" رندر می‌شوند: فاصلهٔ افقی‌شان در همهٔ عرض‌ها ثابت 16px است و مثل محتوای صفحه با نردبان page-inset (16/24/40px) پهن نمی‌شود. اگر خودتان کانتینری برای کروم می‌سازید، همین inset="chrome" را بدهید؛ گذاشتن ps-4 روی کانتینرِ پیش‌فرض کار نمی‌کند، چون page-inset خصوصیت میان‌بُر padding-inline را می‌نویسد و در ترتیب CSS بعد از کلاس‌های ps-* می‌آید.

چیدمان افقی (دو ستونی)

یک بخش از محتوای CustomPage:

<PageSection orientation="horizontal">
  {/* ستون باریک (1fr): متا/خلاصه */}
  <PageSectionMeta>
    <PageSectionSummary>
      <PageSectionTitle>خلاصهٔ اینفلوئنسر</PageSectionTitle>
      <PageSectionDescription>اطلاعات کلی و پلتفرم‌ها</PageSectionDescription>
    </PageSectionSummary>
  </PageSectionMeta>
  {/* ستون پهن (2fr): محتوای اصلی */}
  <PageSectionContent>{/* نمودارها و آمار */}</PageSectionContent>
</PageSection>

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

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

PageContainer

PageHeaderRoot

PageSection

PageSectionContent

PageBreadcrumbs

PageNav

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

• PageHeaderTitle یک h1 واقعی و PageSectionTitle یک h2 است، پس سلسله‌مراتب تیترها برای ناوبری صفحه‌خوان درست می‌ماند — h1 صفحه را قالب می‌دهد
• کل خانواده از خصوصیات منطقی CSS (ps/pe، start/end) استفاده می‌کند و به‌صورت خودکار RTL-صحیح است
• چیدمان‌ها container-query محورند، پس در عرض‌های مختلف (نه فقط viewport) درست پاسخ می‌دهند؛ کرومِ تمام‌عرض ارتفاع ثابت 48px و فاصلهٔ افقی ثابت 16px دارد

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

• PageHeader — سرِ صفحه‌ای که قالب‌ها رندر می‌کنند
• انتخاب قالب صفحه — هر صفحهٔ محصول یک قالب است
• CustomPage — تنها جایی که PageSection مستقیم در صفحه می‌آید
• چیدمان (الگو) — اجزای سطح پایینی که قالب‌ها رویشان ساخته شده‌اند
• صفحهٔ تحلیل — نمونهٔ کامل یک صفحهٔ تحلیل، با قالب DetailPage
• Breadcrumb — عناصر breadcrumb که داخل PageBreadcrumbs قرار می‌گیرند