نوار سهمیه (QuotaProgressBar)

معرفی

QuotaProgressBar نوار پیشرفت مخصوص محدودیت‌های سهمیه‌ای است — کاری که ورکر Booster در 24 ساعت اخیر انجام داده از کل مجاز، آپلود ساعتی کاربر CommentSanj، فراخوانی API تحلیل، و هر شمارنده‌ای که با نزدیک شدن به سقف باید هشدار بصری بدهد.

برخلاف Progress که variant ثابت می‌خواهد، QuotaProgressBar رنگ را خودکار از نسبت used / limit انتخاب می‌کند:

• 0–70٪ → سبز (--sentiment-positive)
• 70–90٪ → کهربایی (--warning-default)
• 90–100٪ → نارنجی (--severity-high) + آیکون ⚠
• ≥ 100٪ → قرمز (--destructive-default) + آیکون ⚠ با pulse

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

• سهمیه روزانه/ساعتی ورکر (لایک، کامنت، فالو) در داشبورد Booster
• آپلود فایل «3 از 10 در ساعت گذشته»
• فراخوانی API AI در هر دقیقه
• هر شمارنده تجمعی که به سقف نزدیک می‌شود

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

• پیشرفت کار async (تحلیل، کمپین) — از JobCardProgress استفاده کنید
• متریک تک‌عدد بدون سقف — از MetricCard استفاده کنید
• نمایش وضعیت rate-limit (وقتی به سقف خورده و باید منتظر بماند) — از RateLimitBanner استفاده کنید، این مکمل است

زمین بازی

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

استفاده

'use client'
import { QuotaProgressBar } from '@partodata/ui'

export function WorkerQuotas({ worker }) {
  return (
    <div className="flex flex-col gap-3">
      <QuotaProgressBar actionType="like" used={worker.likesToday} limit={100} />
      <QuotaProgressBar actionType="comment" used={worker.commentsToday} limit={50} />
      <QuotaProgressBar actionType="follow" used={worker.followsToday} limit={30} />
    </div>
  )
}

حالت 4 سطحی

هر سطح رنگ و (در صورت فعال بودن showWarningIcon) آیکون هشدار خودش را دارد. attribute data-level روی root گذاشته می‌شود تا بتوانید CSS سفارشی هم اضافه کنید.

ترکیب با ActionTypeKey

با prop actionType، برچسب پیش‌فرض از actionTypeLabels خوانده می‌شود — «پسندیدن»، «نظر»، … . این کوتاه‌ترین راه برای رندر یک سهمیه مرتبط با عملیات است.

overflow (مصرف بیش از سقف)

با showOverflow، وقتی used > limit است، نوار به صورت بصری با الگوی راه‌راه نمایش داده می‌شود ولی عرض آن در 100٪ clamp می‌شود. صفحه‌خوان مقدار واقعی (مثلاً 150) را در aria-valuenow می‌بیند.

اندازه‌ها

چهار اندازه: xs (h-1) / sm (h-1.5) / md (h-2) / lg (h-3). برای لیست‌های فشرده xs یا sm و برای کارت‌های detail md یا lg.

آستانه‌های سفارشی

<QuotaProgressBar used={50} limit={100} thresholds={{ amber: 0.4, orange: 0.8, red: 1 }} />

برای سناریوهایی که سیاست سختگیرانه‌تری دارند (مثلاً هشدار از 40٪)، آستانه‌ها را override کنید. هر سه را می‌توانید partial بدهید — باقی از default استفاده می‌شود.

Props

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

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

• نوار یک role="progressbar" با aria-valuenow/aria-valuemin=0/aria-valuemax=100 دارد. حتی در حالت overflow (ratio > 1)، valuenow مقدار حقیقی (مثلاً 150) را منتقل می‌کند تا صفحه‌خوان «over-quota» را بفهمد.
• aria-label از label یا actionType محاسبه می‌شود؛ اگر هیچ‌کدام نباشد، واژه‌ی هم‌زبانِ locale جایگزین می‌شود («سهمیه» / «الحصة» / «Quota»).
• آیکون هشدار aria-hidden="true" است — اطلاعات بصری اضافه است، معنا با متن منتقل می‌شود.
• در سطح red، pulse با motion-safe:animate-pulse است — در prefers-reduced-motion ساکن می‌ماند.

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

• RateLimitBanner — مکمل این کامپوننت؛ وقتی سهمیه تمام شد و باید صبر کرد، این banner را نمایش دهید
• Progress — نوار پیشرفت عمومی با variant ثابت
• JobCardProgress — برای پیشرفت کار async (نه سهمیه)
• ActionTypeChip — برای نمایش نوع عملیات به‌صورت chip جدا
• MetricCard — متریک تک‌عدد بدون سقف