کارت نمره معیار (CriterionScoreCard)

معرفی

CriterionScoreCard کارت فشرده برای نمایش یک معیار نمره‌دار در ارزیابی کمی یک پیج، ورکر، یا هر entity نمره‌پذیر است. هر کارت: نام معیار + نمره (۰-۱۰۰) + تِر (عالی/خوب/متوسط/ضعیف/بحرانی) + اختیاراً وزن، ورودی خام، روند، و آستانه‌های rubric.

پنج تِر canonical با توکن‌های --score-*:

• excellent (≥۸۰) → --score-excellent (سبز تیره)
• good (≥۶۰) → --score-good (سبز)
• moderate (≥۴۰) → --score-moderate (کهربایی)
• poor (≥۲۰) → --score-poor (نارنجی)
• critical (کمتر از ۲۰) → --destructive-default (قرمز)

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

• نمایش معیارهای ارزیابی کمی یک پیج (تعامل، رشد، ثبات، کیفیت محتوا)
• rubric scoring یک worker (نرخ موفقیت، بهره‌وری، پایداری)
• دسته‌ای از chips quality برای یک تحلیل
• daşboard کلی که از چند معیار composite score می‌سازد

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

• یک متریک تک‌عدد بدون مفهوم tiering — از MetricCard استفاده کنید
• نمایش فقط benchmark بدون بار rubric — از EngagementRateBenchmark استفاده کنید
• وقتی سلامت entity concept اصلی است، نه rubric — از EntityHealthCard استفاده کنید
• فقط وضعیت (running/paused/…) — از JobCard / StatusBadge استفاده کنید

زمین بازی

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

استفاده

'use client'
import { CriterionScoreCard } from '@parto-system-design/ui'

export function PageCriteria({ page }) {
  return (
    <div className="grid gap-3 sm:grid-cols-2">
      <CriterionScoreCard
        name="نمره تعامل"
        description="میانگین لایک و کامنت نرمال‌شده بر فالوور"
        score={page.metrics.engagementScore}
        weight={0.6}
        input={{ label: 'نرخ تعامل', value: `${page.eRate.toFixed(1)}٪` }}
        trend={{ delta: 12, label: 'نسبت به ماه قبل' }}
        showThresholdHint
      />
      <CriterionScoreCard
        name="نمره رشد"
        description="درصد افزایش فالوور در ۳۰ روز اخیر"
        score={page.metrics.growthScore}
        weight={0.4}
        input={{ label: 'رشد ماهانه', value: '+۵٫۲٪' }}
        trend={{ delta: -3 }}
      />
    </div>
  )
}

پنج تِر با آستانه‌های پیش‌فرض

هر کارت auto-detects تِر را از score / max + آستانه‌های پیش‌فرض. برای override، tier را صریحاً پاس دهید یا tierThresholds را سفارشی کنید.

با وزن، ورودی، و روند

• weight — عدد ۰ تا ۱. به صورت «وزن ۶۰٪» در header نمایش داده می‌شود.
• input — ورودی خام که نمره را ساخت (شفافیت برای کاربر).
• trend — دلتای نسبت به baseline (مثبت = بهتر شده).

حالت compact برای ردیف‌های لیست

با layout="compact"، کارت به یک ردیف فشرده تبدیل می‌شود: نام + نوار کوچک + نمره + tier chip. مناسب:

• جدول criteria breakdown
• card‌های inline در AnalysisPage
• drawer زیرمجموعه با چندین criterion

با آستانه rubric (آموزشی)

با showThresholdHint، یک ردیف footer با آستانه‌های tier (مثلاً «≥۸۰ عالی · ≥۶۰ خوب · …») رندر می‌شود. مناسب صفحه تحلیل که کاربر تازه‌وارد نیاز به راهنما دارد.

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

<CriterionScoreCard
  name="سرعت پاسخ worker"
  score={72}
  tierThresholds={{ excellent: 50, good: 35, moderate: 20, poor: 10 }}
  showThresholdHint
/>

برای دامنه‌هایی که thresholdهای پیش‌فرض مناسب نیستند (مثلاً متریک معکوس یا logarithmic)، آستانه‌ها را override کنید. همیشه به صورت «۰-۱۰۰» بیان می‌شوند و به max شما scale می‌شوند.

اندازه‌ها

Props

helpers

import { getCriterionTier, DEFAULT_CRITERION_THRESHOLDS, CRITERION_TIER_KEYS } from '@parto-system-design/ui'

// Auto-classify a score
getCriterionTier(72) // 'good'
getCriterionTier(85) // 'excellent'
getCriterionTier(8, 10) // 'excellent' (80%)

// Canonical tier order (worst → best or similar use)
CRITERION_TIER_KEYS // readonly: ['excellent', 'good', 'moderate', 'poor', 'critical']

DEFAULT_CRITERION_THRESHOLDS // { excellent: 80, good: 60, moderate: 40, poor: 20 }

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

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

• نوار پیشرفت role="progressbar" با aria-valuenow / aria-valuemin=0 / aria-valuemax={max} است.
• عنوان معیار به صورت <h4> semantic رندر می‌شود — در hierarchy صفحه جای خود را پیدا می‌کند.
• aria-label روی badge وزن حاوی متن کامل localized است (مثلاً «وزن: ۶۰٪»).
• Trend arrow aria-hidden="true" است — مقدار متنی aria-label حاوی delta + label است.
• تِر فقط با رنگ منتقل نمی‌شود — همیشه label متنی همراه chip است (برای کاربران color-blind).

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

• EntityHealthCard — وقتی روایت سلامت entity اصلی است، CriterionScoreCard را داخل آن compose کنید
• EngagementRateBenchmark — benchmark عمومی بدون بار rubric — این نسخه در سطح «کارت» است
• MetricCard — متریک تک‌عدد بدون tier
• ProgressBar — نوار عمومی بدون semantic
• StatDisplay — stat فشرده با trend برای inline