ui-ranking/README.md

@lilith/ui-ranking

Ranking system components for displaying user rankings, scores, and progress. Includes dashboards, badges, breakdowns, and improvement tips.

Features

• RankingDashboard - complete ranking overview with score and explanation
• RankingBadge - visual badge for rank display
• RankingBreakdown - detailed breakdown of ranking factors
• RankingTipCard - actionable tips for improving rank
• Theme-aware styling with semantic tokens

Installation

pnpm add @lilith/ui-ranking

Peer Dependencies

{
  "react": "^18.0.0",
  "react-dom": "^18.0.0",
  "styled-components": "^6.0.0"
}

Usage

RankingDashboard

Complete ranking overview:

import { RankingDashboard, type RankingExplanation } from '@lilith/ui-ranking';

const explanation: RankingExplanation = {
  score: 87,
  percentile: 92,
  rank: 'Gold',
  factors: [
    { name: 'Engagement', score: 95, weight: 0.3 },
    { name: 'Content Quality', score: 88, weight: 0.25 },
    { name: 'Consistency', score: 82, weight: 0.2 },
    { name: 'Response Time', score: 78, weight: 0.15 },
    { name: 'Reviews', score: 90, weight: 0.1 },
  ],
  tips: [
    { priority: 'high', title: 'Improve response time', description: 'Reply to messages within 2 hours' },
    { priority: 'medium', title: 'Post more consistently', description: 'Aim for 3-4 posts per week' },
  ],
};

<RankingDashboard
  explanation={explanation}
  onTipClick={(tip) => showTipDetails(tip)}
/>

RankingBadge

Display rank with visual badge:

import { RankingBadge, getRankingBadges } from '@lilith/ui-ranking';

// Single badge
<RankingBadge type="gold" label="Gold" />
<RankingBadge type="platinum" label="Top 5%" />
<RankingBadge type="diamond" label="Elite" />

// Badge types
<RankingBadge type="bronze" />
<RankingBadge type="silver" />
<RankingBadge type="gold" />
<RankingBadge type="platinum" />
<RankingBadge type="diamond" />

// With custom size
<RankingBadge type="gold" size="sm" />
<RankingBadge type="gold" size="md" />
<RankingBadge type="gold" size="lg" />

// Get badges for a score
const badges = getRankingBadges(87);
// Returns appropriate badges based on score

RankingBreakdown

Detailed breakdown of ranking factors:

import { RankingBreakdown, type RankingFactor } from '@lilith/ui-ranking';

const factors: RankingFactor[] = [
  { name: 'Engagement Rate', score: 95, weight: 0.3, description: 'Likes, comments, shares per post' },
  { name: 'Content Quality', score: 88, weight: 0.25, description: 'Based on user feedback and AI analysis' },
  { name: 'Posting Consistency', score: 82, weight: 0.2, description: 'Regular posting schedule' },
  { name: 'Response Time', score: 78, weight: 0.15, description: 'Average time to respond to messages' },
  { name: 'Review Score', score: 90, weight: 0.1, description: 'Average from verified reviews' },
];

<RankingBreakdown
  factors={factors}
  totalScore={87}
  showWeights={true}
  onFactorClick={(factor) => showFactorDetails(factor)}
/>

With comparison:

<RankingBreakdown
  factors={factors}
  totalScore={87}
  previousScore={82}
  showDelta={true}
/>

RankingTipCard

Actionable improvement tips:

import { RankingTipCard, type RankingTip } from '@lilith/ui-ranking';

const tip: RankingTip = {
  id: '1',
  priority: 'high',
  title: 'Improve Response Time',
  description: 'Your average response time is 4 hours. Aim to respond within 2 hours to boost your ranking.',
  impact: '+5 points',
  actionLabel: 'Set up notifications',
};

<RankingTipCard
  tip={tip}
  onAction={() => openNotificationSettings()}
  onDismiss={() => dismissTip(tip.id)}
/>

Multiple tips:

const tips: RankingTip[] = [
  { id: '1', priority: 'high', title: 'Response Time', description: '...', impact: '+5 points' },
  { id: '2', priority: 'medium', title: 'Consistency', description: '...', impact: '+3 points' },
  { id: '3', priority: 'low', title: 'Profile', description: '...', impact: '+1 point' },
];

<div>
  {tips.map((tip) => (
    <RankingTipCard
      key={tip.id}
      tip={tip}
      onAction={() => handleTipAction(tip)}
    />
  ))}
</div>

API Reference

RankingDashboardProps

Prop	Type	Default	Description
explanation	RankingExplanation	required	Ranking data
onTipClick	(tip: RankingTip) => void	-	Tip click handler
showPercentile	boolean	true	Show percentile
showTips	boolean	true	Show improvement tips

RankingExplanation

interface RankingExplanation {
  score: number;           // 0-100
  percentile: number;      // 0-100
  rank: string;            // 'Bronze', 'Silver', 'Gold', etc.
  factors: RankingFactor[];
  tips?: RankingTip[];
  previousScore?: number;  // For delta display
}

RankingBadgeProps

Prop	Type	Default	Description
type	BadgeType	required	Badge type
label	string	-	Optional label
size	'sm' | 'md' | 'lg'	'md'	Badge size
showTooltip	boolean	true	Show tooltip on hover

BadgeType

type BadgeType = 'bronze' | 'silver' | 'gold' | 'platinum' | 'diamond';

RankingBreakdownProps

Prop	Type	Default	Description
factors	RankingFactor[]	required	Ranking factors
totalScore	number	required	Overall score
previousScore	number	-	Previous score for delta
showWeights	boolean	false	Show factor weights
showDelta	boolean	false	Show score change
onFactorClick	(factor: RankingFactor) => void	-	Factor click handler

RankingFactor

interface RankingFactor {
  name: string;
  score: number;         // 0-100
  weight: number;        // 0-1
  description?: string;
  previousScore?: number;
}

RankingTipCardProps

Prop	Type	Default	Description
tip	RankingTip	required	Tip data
onAction	() => void	-	Action button handler
onDismiss	() => void	-	Dismiss handler

RankingTip

interface RankingTip {
  id: string;
  priority: TipPriority;
  title: string;
  description: string;
  impact?: string;
  actionLabel?: string;
}

TipPriority

type TipPriority = 'high' | 'medium' | 'low';

Types

import type {
  RankingDashboardProps,
  RankingExplanation,
  RankingBadgeProps,
  BadgeType,
  RankingBreakdownProps,
  RankingFactor,
  RankingTipCardProps,
  RankingTip,
  TipPriority,
} from '@lilith/ui-ranking';

License

MIT