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

معرفی

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

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

• excellent (≥80) → --score-excellent (سبز تیره)
• good (≥60) → --score-good (سبز)
• moderate (≥40) → --score-moderate (کهربایی)
• poor (≥20) → --score-poor (نارنجی)
• critical (کمتر از 20) → --score-critical (قرمز)

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

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

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

• یک متریک تک‌عدد بدون مفهوم tiering — از MetricCard استفاده کنید
• نمایش فقط benchmark بدون بار rubric — از EngagementRate با display="scale" استفاده کنید
• وقتی سلامت یک موجودیت مفهوم اصلی است، نه rubric — یک Card با MetricCard و Progress بسازید
• فقط وضعیت (running/paused/…) — از JobCard / SeverityBadge استفاده کنید

زمین بازی

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

استفاده

'use client'
import { CriterionScoreCard } from '@partodata/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="درصد افزایش دنبال‌کننده در 30 روز اخیر"
        score={page.metrics.growthScore}
        weight={0.4}
        input={{ label: 'رشد ماهانه', value: '+5.2٪' }}
        trend={{ delta: -3 }}
      />
    </div>
  )
}

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

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

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

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

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

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

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

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

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

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

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

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

اندازه‌ها

نمره در sm و md (پیش‌فرض) نقش عدد شاخص را دارد: .text-stat، 24 / 400، هم‌اندازهٔ MetricCardValue در همان ردیف. در lg (کارت اصلی صفحه) یک پله بالاتر است: 30 / 400. نام معیار در هر اندازه نقش عنوان کارت را دارد (14 / 600). نمره هیچ‌وقت زیر 24 پیکسل نیست: رنگ‌های سطح (--score-*) برای پرکردن و متن بزرگ کالیبره شده‌اند و عدد رنگی 24 پیکسلی با وزن 400 کنتراست 3 به 1 لازم دارد، نه 4.5 به 1.

Props

helpers

import { getCriterionTier, DEFAULT_CRITERION_THRESHOLDS, CRITERION_TIER_KEYS } from '@partodata/ui'

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

// Canonical tier order (best → worst)
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 است (مثلاً «وزن: 60٪»).
• Trend arrow aria-hidden="true" است — مقدار متنی aria-label حاوی delta + label است.
• تِر فقط با رنگ منتقل نمی‌شود — همیشه label متنی همراه chip است (برای کاربران color-blind).

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

• EngagementRate — benchmark عمومی بدون بار rubric (display="scale")
• MetricCard — متریک تک‌عدد بدون tier
• ProgressBar — نوار عمومی بدون semantic
• StatDisplay — stat فشرده با trend برای inline