Merge pull request #102 from makeswift/andrew/ratings-style

feat: add total reviews count to ratings

Author: hunterbecton

src/components/rating/primitives.ts

@@ -13,3 +13,7 @@ export {
   RatingValue as Value,
   type RatingValueProps as ValueProps,
 } from '@/components/rating/primitives/rating-value';
+export {
+  RatingTotal as Total,
+  type RatingTotalProps as TotalProps,
+} from '@/components/rating/primitives/rating-total';

src/components/rating/primitives/rating-root.tsx

@@ -12,6 +12,8 @@ interface RatingContext {
   adjustedRating: number;
   stars: StarType[];
   showRating: boolean;
+  showTotalReviews: boolean;
+  totalReviews: number;
   getNextStarIndex: () => number;
   resetStarIndex: () => void;
 }
@@ -21,6 +23,8 @@ const RatingContext = createContext<RatingContext | undefined>(undefined);
 export interface RatingRootProps extends ComponentProps<'div'> {
   rating: number;
   showRating?: boolean;
+  showTotalReviews?: boolean;
+  totalReviews?: number;
   children: ReactNode;
 }
 
@@ -29,6 +33,8 @@ export function RatingRoot({
   className,
   rating,
   showRating = true,
+  showTotalReviews = true,
+  totalReviews = 0,
   ...props
 }: RatingRootProps) {
   const starIndexRef = useRef(0);
@@ -60,14 +66,16 @@ export function RatingRoot({
       adjustedRating,
       stars,
       showRating,
+      showTotalReviews,
+      totalReviews,
       getNextStarIndex,
       resetStarIndex,
     };
-  }, [rating, showRating, getNextStarIndex, resetStarIndex]);
+  }, [rating, showRating, showTotalReviews, totalReviews, getNextStarIndex, resetStarIndex]);
 
   return (
     <RatingContext.Provider value={contextValues}>
-      <div className={cn('flex items-center', className)} {...props}>
+      <div className={cn('flex items-center', className)} data-slot="rating-root" {...props}>
         {children}
       </div>
     </RatingContext.Provider>

src/components/rating/primitives/rating-star.tsx

@@ -52,6 +52,7 @@ export function RatingStar({ className, ...props }: RatingStarProps) {
   return (
     <svg
       className={cn('inline-block text-[var(--rating-icon,hsl(var(--foreground)))]', className)}
+      data-slot="rating-star"
       fill="none"
       height={20}
       viewBox="0 0 20 20"

src/components/rating/primitives/rating-stars.tsx

@@ -10,7 +10,7 @@ export function RatingStars() {
   return (
     <>
       {[0, 1, 2, 3, 4].map((i) => (
-        <RatingStar key={i} />
+        <RatingStar data-slot="rating-star" key={i} />
       ))}
     </>
   );

src/components/rating/primitives/rating-total.tsx

@@ -0,0 +1,27 @@
+'use client';
+
+import type { ComponentProps } from 'react';
+
+import { useRating } from '@/components/rating';
+import { cn } from '@/lib';
+
+export type RatingTotalProps = ComponentProps<'span'>;
+
+export function RatingTotal({ className, children, ...props }: RatingTotalProps) {
+  const { totalReviews, showTotalReviews } = useRating();
+
+  if (!showTotalReviews) return null;
+
+  return (
+    <span
+      className={cn(
+        'ml-2 border-l border-contrast-200 pl-2 font-normal text-[var(--rating-text,hsl(var(--contrast-500)))]',
+        className,
+      )}
+      data-slot="rating-total"
+      {...props}
+    >
+      {totalReviews.toLocaleString()} {totalReviews === 1 ? 'review' : 'reviews'}
+    </span>
+  );
+}

src/components/rating/primitives/rating-value.tsx

@@ -7,20 +7,22 @@ import { cn } from '@/lib';
 
 export type RatingValueProps = ComponentProps<'span'>;
 
-export function RatingValue({ className, ...props }: RatingValueProps) {
+export function RatingValue({ className, children, ...props }: RatingValueProps) {
   const { adjustedRating, showRating } = useRating();
 
   if (!showRating) return null;
 
   return (
     <span
       className={cn(
-        'ml-1.5 flex h-6 min-w-6 shrink-0 items-center justify-center rounded-full border border-[var(--rating-border,hsl(var(--contrast-100)))] px-1 text-xs font-medium text-[var(--rating-text,hsl(var(--contrast-400)))]',
+        'ml-2 flex text-xs font-bold leading-normal text-[var(--rating-text,hsl(var(--foreground)))]',
         className,
       )}
+      data-slot="rating-value"
       {...props}
     >
       {adjustedRating % 1 !== 0 ? adjustedRating.toFixed(1) : adjustedRating}
+      {children}
     </span>
   );
 }

src/components/rating/rating.tsx

@@ -2,7 +2,9 @@ import * as RatingPrimitive from '@/components/rating';
 
 export interface RatingProps {
   showRating?: boolean;
+  showTotalReviews?: boolean;
   rating: number;
+  totalReviews?: number;
   className?: string;
 }
 
@@ -18,11 +20,25 @@ export interface RatingProps {
  * }
  * ```
  */
-export function Rating({ showRating = true, rating, className }: Readonly<RatingProps>) {
+export function Rating({
+  showRating = true,
+  showTotalReviews = true,
+  rating,
+  totalReviews,
+  className,
+}: RatingProps) {
   return (
-    <RatingPrimitive.Root className={className} rating={rating} showRating={showRating}>
+    <RatingPrimitive.Root
+      className={className}
+      rating={rating}
+      showRating={showRating}
+      showTotalReviews={showTotalReviews}
+      totalReviews={totalReviews}
+    >
       <RatingPrimitive.Stars />
-      <RatingPrimitive.Value />
+      <RatingPrimitive.Value>
+        <RatingPrimitive.Total />
+      </RatingPrimitive.Value>
     </RatingPrimitive.Root>
   );
 }

src/components/rating/storybook/rating.stories.tsx

@@ -1,8 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
-import { Rating } from '@/components/rating';
+import * as RatingPrimitive from '@/components/rating';
+import { Rating, type RatingProps } from '@/components/rating';
 
-const meta = {
+const meta: Meta<typeof Rating> = {
   title: 'Components/Rating',
   component: Rating,
   parameters: {
@@ -12,117 +13,97 @@ const meta = {
   argTypes: {
     rating: {
       control: { type: 'number', min: 0, max: 5, step: 0.1 },
-      description: 'Rating value from 0 to 5',
+      description: 'The rating value (0-5)',
+    },
+    totalReviews: {
+      control: 'number',
+      description: 'Total number of reviews to display',
     },
     showRating: {
       control: 'boolean',
-      description: 'Show numeric rating badge',
-      table: {
-        defaultValue: { summary: 'true' },
-      },
+      description: 'Whether to show the numeric rating value',
+    },
+    showTotalReviews: {
+      control: 'boolean',
+      description: 'Whether to show the total reviews count',
     },
     className: {
       control: 'text',
-      description: 'Additional CSS classes',
+      description: 'Additional CSS classes for the root element',
     },
   },
-  args: {
-    rating: 4.5,
-    showRating: true,
-  },
-} satisfies Meta<typeof Rating>;
+};
 
 export default meta;
-
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<RatingProps>;
 
 export const Default: Story = {
   args: {
     rating: 4.5,
+    totalReviews: 128,
   },
 };
 
-export const FiveStars: Story = {
+export const FullStars: Story = {
   args: {
     rating: 5,
+    totalReviews: 1024,
   },
 };
 
-export const FourStars: Story = {
+export const HalfStar: Story = {
   args: {
-    rating: 4,
-  },
-};
-
-export const ThreeStars: Story = {
-  args: {
-    rating: 3,
-  },
-};
-
-export const TwoStars: Story = {
-  args: {
-    rating: 2,
-  },
-};
-
-export const OneStar: Story = {
-  args: {
-    rating: 1,
+    rating: 3.5,
+    totalReviews: 42,
   },
 };
 
-export const ZeroStars: Story = {
+export const LowRating: Story = {
   args: {
-    rating: 0,
+    rating: 1.5,
+    totalReviews: 7,
   },
 };
 
-export const HalfStars: Story = {
+export const SingleReview: Story = {
   args: {
-    rating: 3.5,
+    rating: 5,
+    totalReviews: 1,
   },
 };
 
-export const WithoutBadge: Story = {
+export const StarsOnly: Story = {
   args: {
-    rating: 4.5,
+    rating: 4,
     showRating: false,
+    showTotalReviews: false,
   },
 };
 
-export const AllRatings: Story = {
+export const WithoutTotalReviews: Story = {
   args: {
     rating: 4.5,
+    showTotalReviews: false,
   },
-  render: () => (
-    <div className="flex flex-col gap-4">
-      <Rating rating={5} />
-      <Rating rating={4.5} />
-      <Rating rating={4} />
-      <Rating rating={3.5} />
-      <Rating rating={3} />
-      <Rating rating={2.5} />
-      <Rating rating={2} />
-      <Rating rating={1.5} />
-      <Rating rating={1} />
-      <Rating rating={0.5} />
-      <Rating rating={0} />
-    </div>
-  ),
 };
 
-export const WithoutBadges: Story = {
-  args: {
-    rating: 4.5,
-  },
+/**
+ * The Rating component is built using composable primitives that can be used
+ * independently to create custom layouts. Here's the anatomy:
+ *
+ * - `Root` - Context provider and container
+ * - `Stars` - Renders all 5 stars based on the rating
+ * - `Star` - Individual star icon (empty, half, or full)
+ * - `Value` - Numeric rating display
+ * - `Total` - Review count display
+ */
+export const ComposableAnatomy: Story = {
   render: () => (
-    <div className="flex flex-col gap-4">
-      <Rating rating={5} showRating={false} />
-      <Rating rating={4.5} showRating={false} />
-      <Rating rating={4} showRating={false} />
-      <Rating rating={3.5} showRating={false} />
-      <Rating rating={3} showRating={false} />
-    </div>
+    <RatingPrimitive.Root rating={4.5} totalReviews={256}>
+      <RatingPrimitive.Stars />
+      <RatingPrimitive.Value>
+        <RatingPrimitive.Total />
+      </RatingPrimitive.Value>
+    </RatingPrimitive.Root>
   ),
 };