نوار منبع (SourceScope)

معرفی

SourceScope نوار منبعِ صفحه‌های جست‌وجو و رتبه‌بندی است: جست‌وجوی پست، برترین‌ها، مسائل و هر صفحه‌ای از همین جنس. در این صفحه‌ها هر منبع — اینستاگرام، تلگرام، ایکس، وب و خبر، تلویزیون … — پایگاه دادهٔ جداست؛ پس صفحه در هر لحظه فقط در یک منبع می‌گردد و منبع‌ها با هم آمیخته نمی‌شوند. منبع اول انتخاب می‌شود و همیشه پیداست، و گزینهٔ «همهٔ منابع» ندارد.

هر منبع نشان و نامش را دارد (PlatformMark)، و اگر API بدهد شمار نتیجهٔ پرسش در همان منبع را. منبعی که در طرح حساب نیست یا هنوز وصل نشده، کم‌رنگ و انتخاب‌نشدنی با دلیلش می‌ماند.

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

• صفحهٔ جست‌وجوی پست، برترین‌ها، مسائل و هر صفحهٔ جست‌وجو یا رتبه‌بندی که منبع‌هایش پایگاه‌دادهٔ جدا دارند.

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

• محصولی که همهٔ شبکه‌ها را با هم نشان می‌دهد (کامنت‌سنج، بولتن، فهرست منشن‌ها): آن‌جا شبکه یک فاست معمولی است، DataTableFacetedFilter با platformOptions() در filters.
• برای نشان دادن منبع یک مورد: PlatformMark.

زمین بازی

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

import { SourceScope, useSourceScope, type SourceScopeItem } from '@partodata/ui/social'

const SOURCES: SourceScopeItem[] = [
  { value: 'instagram', count: 1240 },
  { value: 'twitter', count: 312 },
  { value: 'tv', available: false, reason: 'در طرح شما نیست' },
]

// Kept per product: every search page of the product opens on the last source.
const [source, setSource] = useSourceScope({ product: 'my-product', sources: SOURCES })

<ListPage
  title="جست‌وجوی پست"
  source={<SourceScope sources={SOURCES} value={source} onValueChange={setSource} />}
  …
/>

استفاده

'use client'
import { SourceScope, useSourceScope, type SourceKey } from '@partodata/ui/social'
import { ListPage } from '@partodata/ui/templates'

// The sources the product searches — each its own database: one at a time, never «all».
const SOURCES: SourceKey[] = ['instagram', 'telegram', 'twitter', 'web', 'tv']

export function PostSearch() {
  // Kept per product: every search page of the product opens on the user's last source.
  const [source, setSource] = useSourceScope({ product: 'my-product', sources: SOURCES })
  const [page, setPage] = React.useState(1)
  // … the query and the request read `source`
  return (
    <ListPage
      title="جست‌وجوی پست"
      source={
        <SourceScope
          sources={SOURCES}
          value={source}
          onValueChange={(next) => {
            setSource(next)
            setPage(1)
          }}
        />
      }
      query={…}
      state={…}
    >
      …
    </ListPage>
  )
}

جای آن در صفحه

نوار منبع در source قالب صفحه است — ListPage (جست‌وجوی پست، فهرست برترین‌ها) یا DashboardPage (داشبورد مسائل یا برترین‌ها) — و قالب آن را اول، زیر عنوان می‌گذارد: بالای فیلد پرسش، فیلترها و شاخص‌ها، در همهٔ حالت‌های صفحه (بارگذاری، خالی، خطا). نه در نوار بالای ProductFrame، چون منبع کل برنامه نیست: صفحه‌های تجمیعی مثل کامنت‌سنج و بولتن منبع ندارند، و نواری در سرِ قاب یا در آن‌ها بی‌معنا بود یا در صفحه‌های جست‌وجو از فیلترهایی که منبع رویشان اثر دارد دور می‌افتاد. نه داخل فیلترها، چون منبع فیلتر نیست: «پاک کردن فیلترها» آن را برنمی‌گرداند و در شمار فیلترهای نوارابزار نیست.

نگه‌داشتن برای هر محصول

useSourceScope({ product, sources, defaultValue }) منبع انتخاب‌شده را در مرورگر برای هر محصول نگه می‌دارد؛ پس همهٔ صفحه‌های جست‌وجو و رتبه‌بندی یک محصول با آخرین منبعی که کاربر انتخاب کرده باز می‌شوند. رندر اول defaultValue است (بی ناهمخوانی با رندر سرور) و منبع نگه‌داشته بلافاصله بعد از آن می‌نشیند. مقدار همیشه یکی از منبع‌های در دسترسِ sources است: منبعی که صفحه ندارد یا در دسترس نیست کنار گذاشته می‌شود.

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

• شمار نتیجه: count در هر منبع، بعد از نامش (formatCount: «1.2 هزار»، رقم‌ها با فونت فارسی دیده می‌شوند). بی count چیزی نشان داده نمی‌شود، هرگز 0 ساختگی.
• در دسترس نیست: available: false با reason («در طرح شما نیست»): کم‌رنگ، انتخاب‌نشدنی، دلیل بعد از نامش خوانده می‌شود.
• عرض کم: وقتی محتوای صفحه (ظرف قالب صفحه) کمتر از 36rem است — در گوشی — منبع‌های دیگر فقط نشانشان را نشان می‌دهند و منبع جاری نامش را نگه می‌دارد؛ نام همهٔ منبع‌ها نام دسترس‌پذیرشان می‌ماند. اگر باز هم جا نشود، نوار افقی پیمایش می‌شود.

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

Props

SourceScopeItem

useSourceScope

خروجی: [source, setSource].

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

• یک گروه رادیویی (radiogroup) با نام «منبع»؛ هر منبع یک radio با نامش (و شمار و دلیلش).
• Tab به منبع جاری می‌رسد؛ کلیدهای جهت‌دار در جهت صفحه جابه‌جا و انتخاب می‌کنند (در راست‌به‌چپ، چپ یعنی بعدی).
• منبع در دسترس نیست disabled است و دلیلش در نامش خوانده می‌شود.

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

• PlatformMark — نشان منبع یک مورد.
• ListPage — صفحهٔ جست‌وجومحور با source.
• DashboardPage — داشبورد یک منبع با source.