نشان گرایش (FlowBadge)

معرفی

FlowBadge برای نمایش گرایش غالب یک خوشه، پست، یا پیج نسبت به یک موضوع/برند پایش‌شده استفاده می‌شود. پنج گرایش مستقل از sentiment هستند — یک خوشه می‌تواند هم‌زمان «منتقد سازنده» و «منفی» باشد.

ورودی flow انعطاف‌پذیر است: می‌توانید کلید گرایش، کد عددی (۱ تا ۵)، یا متن (نام انگلیسی یا برچسب محلی) بدهید — کامپوننت در هر حالت گرایش درست را تشخیص می‌دهد و رنگ، آیکون و برچسب متناظر را نمایش می‌دهد.

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

• در کارت خوشه (ConceptCard) برای نمایش گرایش غالب
• در سطر جدول خوشه‌ها یا صفحات
• در فید پست‌ها برای تمایز سریع موضع نویسنده

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

• برای sentiment یا emotion — از SentimentBadge / EmotionBadge استفاده کنید
• برای نمایش توزیع درصدی چند گرایش در یک جا — از FlowDistribution استفاده کنید
• وقتی موضوعِ پایش‌شده ندارید — این مفهوم گرایش‌بودنِ مخاطب نسبت به «چیزی» را پیش‌فرض می‌گیرد

زمین بازی

import { FlowBadge } from '@partodata/ui'

<FlowBadge />

مقادیر و نگاشت عددی

نشان گرایش روی مقیاس عددی گرایش مخاطب کار می‌کند. کدها از 1 (حامی) شروع و به 5 (خنثی) ختم می‌شوند:

کلیدهای متنی تایپ FlowKey شناسه‌های legacy برای سازگاری با کد قدیمی‌اند و هرگز در UI نمایش داده نمی‌شوند — برچسب نمایشی همیشه ستون «برچسب فارسی» (یا معادل محلی‌شده) است:

type FlowKey = 'pro-gov' | 'internal-critic' | 'internal-opponent' | 'external-opponent' | 'grey'

استفاده

flow هر یک از این فرم‌ها را می‌پذیرد:

import { FlowBadge } from '@partodata/ui';

// ۱) کلید گرایش (FlowKey)
<FlowBadge flow="grey" />

// ۲) کد عددی (۱ تا ۵) — مثلاً خروجی مستقیم API
<FlowBadge flow={1} />              {/* → حامی */}
<FlowBadge flow={4} count={62} />   {/* → مخالف جدی */}

// ۳) متن — نام انگلیسی، رشته‌ی عددی، یا برچسب محلی (بزرگ/کوچک مهم نیست)
<FlowBadge flow="Supporter" /> {/* → حامی */}
<FlowBadge flow="مخالف" />  {/* → مخالف */}
<FlowBadge flow={'5'} />            {/* → خنثی */}

// سایر تنظیمات
<FlowBadge flow={4} size="sm" showLabel={false} />

// مقدار ناشناخته یا خارج از بازه → چیزی رندر نمی‌شود
<FlowBadge flow={0} />              {/* → null */}

ورودی از کد عددی (۱ تا ۵)

ورودی از متن

نام انگلیسی، رشته‌ی عددی، یا برچسب فارسی/عربی — همه به یک گرایش نگاشت می‌شوند.

اندازه‌ها

Props

ابزار کمکی

برای تبدیل دستی مقدار به کلید گرایش (خارج از این کامپوننت)، از resolveFlow استفاده کنید. خروجی برای مقادیر نامعتبر null است:

import { resolveFlow, FLOW_VALUE_MAP, FLOW_KEY_TO_VALUE } from '@partodata/ui'

resolveFlow(1) // 'pro-gov'
resolveFlow('Supporter') // 'pro-gov'
resolveFlow('مخالف جدی') // 'external-opponent'
resolveFlow('4') // 'external-opponent'
resolveFlow(0) // null
resolveFlow(99) // null

FLOW_VALUE_MAP[1] // 'pro-gov'
FLOW_KEY_TO_VALUE.grey // 5

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

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

• هر گرایش هم آیکون اختصاصی و هم رنگ دارد
• با showLabel={false} مقدار aria-label حفظ می‌شود
• رنگ‌ها با پس‌زمینه‌ی هر دو تم light و dark کنتراست WCAG AA دارند

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

• FlowDistribution — توزیع درصدی چند گرایش
• SentimentBadge — بُعد مستقل sentiment
• EmotionBadge — بُعد مستقل emotion