@wakastellar/ui 3.1.0 → 3.3.0

package/src/components/waka-credit-breakdown/index.tsx

@@ -0,0 +1,487 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../utils/cn"
+import {
+  PieChart,
+  Pie,
+  Cell,
+  BarChart,
+  Bar,
+  XAxis,
+  YAxis,
+  Tooltip,
+  Legend,
+  ResponsiveContainer,
+} from "recharts"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface BreakdownItem {
+  /** Unique identifier */
+  id: string
+  /** Display name */
+  name: string
+  /** Credit consumption value */
+  value: number
+  /** Custom color for this segment */
+  color?: string
+}
+
+export interface WakaCreditBreakdownProps {
+  /** Breakdown data items */
+  data: BreakdownItem[]
+  /** Visualization variant */
+  variant?: "pie" | "donut" | "bar"
+  /** Show percentage labels */
+  showPercentages?: boolean
+  /** Show legend */
+  showLegend?: boolean
+  /** Chart height in pixels */
+  height?: number
+  /** Enable animations */
+  animated?: boolean
+  /** Callback when a segment is clicked */
+  onSegmentClick?: (item: BreakdownItem) => void
+  /** Custom value formatter */
+  formatValue?: (value: number) => string
+  /** Additional CSS classes */
+  className?: string
+}
+
+// ============================================================================
+// Default Colors (matching waka-cost-breakdown palette)
+// ============================================================================
+
+const defaultColors = [
+  "hsl(var(--chart-1))",
+  "hsl(var(--chart-2))",
+  "hsl(var(--chart-3))",
+  "hsl(var(--chart-4))",
+  "hsl(var(--chart-5))",
+  "hsl(var(--primary))",
+  "hsl(var(--info))",
+  "hsl(var(--warning))",
+  "hsl(var(--success))",
+  "hsl(var(--destructive))",
+]
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+function assignColors(items: BreakdownItem[]): BreakdownItem[] {
+  return items.map((item, index) => ({
+    ...item,
+    color: item.color || defaultColors[index % defaultColors.length],
+  }))
+}
+
+function calculateTotal(items: BreakdownItem[]): number {
+  return items.reduce((sum, item) => sum + item.value, 0)
+}
+
+function defaultFormatValue(value: number): string {
+  if (value >= 1000000) {
+    return `${(value / 1000000).toFixed(1)}M`
+  }
+  if (value >= 1000) {
+    return `${(value / 1000).toFixed(1)}K`
+  }
+  return value.toLocaleString()
+}
+
+// ============================================================================
+// Custom Tooltip
+// ============================================================================
+
+interface CustomTooltipProps {
+  active?: boolean
+  payload?: Array<{
+    name: string
+    value: number
+    payload: BreakdownItem & { color: string }
+  }>
+  total: number
+  formatter: (value: number) => string
+}
+
+function CustomTooltip({ active, payload, total, formatter }: CustomTooltipProps) {
+  if (!active || !payload || !payload.length) return null
+
+  const entry = payload[0]
+  const percentage = total > 0 ? ((entry.value / total) * 100).toFixed(1) : "0"
+
+  return (
+    <div
+      className={cn(
+        "px-3 py-2 text-sm rounded-lg shadow-lg",
+        "bg-foreground text-background",
+        "pointer-events-none min-w-[140px]"
+      )}
+    >
+      <div className="font-semibold mb-1 flex items-center gap-2">
+        <span
+          className="w-2.5 h-2.5 rounded-full flex-shrink-0"
+          style={{ backgroundColor: entry.payload.color }}
+        />
+        {entry.name}
+      </div>
+      <div className="flex justify-between gap-4">
+        <span className="opacity-70">Value:</span>
+        <span className="font-medium">{formatter(entry.value)}</span>
+      </div>
+      <div className="flex justify-between gap-4">
+        <span className="opacity-70">Share:</span>
+        <span>{percentage}%</span>
+      </div>
+    </div>
+  )
+}
+
+// ============================================================================
+// Custom Label for Pie/Donut
+// ============================================================================
+
+interface PieLabelProps {
+  cx: number
+  cy: number
+  midAngle: number
+  innerRadius: number
+  outerRadius: number
+  percent: number
+  name: string
+}
+
+function renderPieLabel({
+  cx,
+  cy,
+  midAngle,
+  innerRadius,
+  outerRadius,
+  percent,
+}: PieLabelProps) {
+  const RADIAN = Math.PI / 180
+  const radius = innerRadius + (outerRadius - innerRadius) * 0.5 + 20
+  const x = cx + radius * Math.cos(-midAngle * RADIAN)
+  const y = cy + radius * Math.sin(-midAngle * RADIAN)
+
+  if (percent < 0.05) return null
+
+  return (
+    <text
+      x={x}
+      y={y}
+      fill="currentColor"
+      textAnchor={x > cx ? "start" : "end"}
+      dominantBaseline="central"
+      className="text-xs fill-foreground"
+    >
+      {`${(percent * 100).toFixed(0)}%`}
+    </text>
+  )
+}
+
+// ============================================================================
+// Donut Center Label
+// ============================================================================
+
+interface CenterLabelProps {
+  viewBox?: { cx: number; cy: number }
+  total: number
+  formatter: (value: number) => string
+}
+
+function CenterLabel({ viewBox, total, formatter }: CenterLabelProps) {
+  if (!viewBox) return null
+  const { cx, cy } = viewBox
+
+  return (
+    <g>
+      <text
+        x={cx}
+        y={cy - 10}
+        textAnchor="middle"
+        dominantBaseline="middle"
+        className="text-xs fill-muted-foreground"
+      >
+        Total
+      </text>
+      <text
+        x={cx}
+        y={cy + 12}
+        textAnchor="middle"
+        dominantBaseline="middle"
+        className="text-base font-bold fill-foreground"
+      >
+        {formatter(total)}
+      </text>
+    </g>
+  )
+}
+
+// ============================================================================
+// Pie Variant
+// ============================================================================
+
+interface PieVariantProps {
+  data: BreakdownItem[]
+  total: number
+  height: number
+  animated: boolean
+  showPercentages: boolean
+  showLegend: boolean
+  formatter: (value: number) => string
+  onSegmentClick?: (item: BreakdownItem) => void
+}
+
+function PieVariant({
+  data,
+  total,
+  height,
+  animated,
+  showPercentages,
+  showLegend,
+  formatter,
+  onSegmentClick,
+}: PieVariantProps) {
+  return (
+    <ResponsiveContainer width="100%" height={height}>
+      <PieChart>
+        <Pie
+          data={data}
+          dataKey="value"
+          nameKey="name"
+          cx="50%"
+          cy="50%"
+          outerRadius={height / 2 - 40}
+          isAnimationActive={animated}
+          animationDuration={800}
+          label={showPercentages ? renderPieLabel : false}
+          labelLine={false}
+          onClick={
+            onSegmentClick
+              ? (_: unknown, index: number) => onSegmentClick(data[index])
+              : undefined
+          }
+          style={onSegmentClick ? { cursor: "pointer" } : undefined}
+        >
+          {data.map((entry) => (
+            <Cell key={entry.id} fill={entry.color} />
+          ))}
+        </Pie>
+        <Tooltip
+          content={
+            <CustomTooltip total={total} formatter={formatter} />
+          }
+        />
+        {showLegend && (
+          <Legend
+            verticalAlign="bottom"
+            formatter={(value: string) => (
+              <span className="text-sm text-foreground">{value}</span>
+            )}
+          />
+        )}
+      </PieChart>
+    </ResponsiveContainer>
+  )
+}
+
+// ============================================================================
+// Donut Variant
+// ============================================================================
+
+function DonutVariant({
+  data,
+  total,
+  height,
+  animated,
+  showPercentages,
+  showLegend,
+  formatter,
+  onSegmentClick,
+}: PieVariantProps) {
+  const outerRadius = height / 2 - 40
+  const innerRadius = outerRadius * 0.55
+
+  return (
+    <ResponsiveContainer width="100%" height={height}>
+      <PieChart>
+        <Pie
+          data={data}
+          dataKey="value"
+          nameKey="name"
+          cx="50%"
+          cy="50%"
+          innerRadius={innerRadius}
+          outerRadius={outerRadius}
+          isAnimationActive={animated}
+          animationDuration={800}
+          paddingAngle={2}
+          label={showPercentages ? renderPieLabel : false}
+          labelLine={false}
+          onClick={
+            onSegmentClick
+              ? (_: unknown, index: number) => onSegmentClick(data[index])
+              : undefined
+          }
+          style={onSegmentClick ? { cursor: "pointer" } : undefined}
+        >
+          {data.map((entry) => (
+            <Cell key={entry.id} fill={entry.color} />
+          ))}
+          <CenterLabel total={total} formatter={formatter} />
+        </Pie>
+        <Tooltip
+          content={
+            <CustomTooltip total={total} formatter={formatter} />
+          }
+        />
+        {showLegend && (
+          <Legend
+            verticalAlign="bottom"
+            formatter={(value: string) => (
+              <span className="text-sm text-foreground">{value}</span>
+            )}
+          />
+        )}
+      </PieChart>
+    </ResponsiveContainer>
+  )
+}
+
+// ============================================================================
+// Bar Variant (Horizontal)
+// ============================================================================
+
+interface BarVariantProps {
+  data: BreakdownItem[]
+  total: number
+  height: number
+  animated: boolean
+  showPercentages: boolean
+  showLegend: boolean
+  formatter: (value: number) => string
+  onSegmentClick?: (item: BreakdownItem) => void
+}
+
+function BarVariant({
+  data,
+  total,
+  height,
+  animated,
+  showPercentages,
+  showLegend,
+  formatter,
+  onSegmentClick,
+}: BarVariantProps) {
+  const barData = data.map((item) => ({
+    ...item,
+    percentage: total > 0 ? ((item.value / total) * 100).toFixed(1) : "0",
+  }))
+
+  return (
+    <ResponsiveContainer width="100%" height={height}>
+      <BarChart
+        data={barData}
+        layout="vertical"
+        barCategoryGap="20%"
+      >
+        <XAxis
+          type="number"
+          tickFormatter={(value: number) =>
+            showPercentages
+              ? `${total > 0 ? ((value / total) * 100).toFixed(0) : 0}%`
+              : formatter(value)
+          }
+          axisLine={false}
+          tickLine={false}
+          tick={{ className: "text-xs fill-muted-foreground" }}
+        />
+        <YAxis
+          dataKey="name"
+          type="category"
+          width={100}
+          axisLine={false}
+          tickLine={false}
+          tick={{ className: "text-sm fill-foreground" }}
+        />
+        <Tooltip
+          content={
+            <CustomTooltip total={total} formatter={formatter} />
+          }
+        />
+        {showLegend && (
+          <Legend
+            verticalAlign="bottom"
+            formatter={(value: string) => (
+              <span className="text-sm text-foreground">{value}</span>
+            )}
+          />
+        )}
+        <Bar
+          dataKey="value"
+          name="Credits"
+          radius={[0, 4, 4, 0]}
+          isAnimationActive={animated}
+          animationDuration={800}
+          barSize={24}
+          onClick={
+            onSegmentClick
+              ? (_: unknown, index: number) => onSegmentClick(data[index])
+              : undefined
+          }
+          style={onSegmentClick ? { cursor: "pointer" } : undefined}
+        >
+          {data.map((entry) => (
+            <Cell key={entry.id} fill={entry.color} />
+          ))}
+        </Bar>
+      </BarChart>
+    </ResponsiveContainer>
+  )
+}
+
+// ============================================================================
+// Main Component
+// ============================================================================
+
+export function WakaCreditBreakdown({
+  data,
+  variant = "pie",
+  showPercentages = false,
+  showLegend = true,
+  height = 300,
+  animated = true,
+  onSegmentClick,
+  formatValue,
+  className,
+}: WakaCreditBreakdownProps) {
+  const coloredData = React.useMemo(() => assignColors(data), [data])
+  const total = React.useMemo(() => calculateTotal(coloredData), [coloredData])
+  const formatter = formatValue || defaultFormatValue
+
+  const sharedProps = {
+    data: coloredData,
+    total,
+    height,
+    animated,
+    showPercentages,
+    showLegend,
+    formatter,
+    onSegmentClick,
+  }
+
+  return (
+    <div className={cn("w-full", className)}>
+      {variant === "pie" && <PieVariant {...sharedProps} />}
+      {variant === "donut" && <DonutVariant {...sharedProps} />}
+      {variant === "bar" && <BarVariant {...sharedProps} />}
+    </div>
+  )
+}
+
+export default WakaCreditBreakdown

package/src/components/waka-credit-burn-rate/WakaCreditBurnRate.stories.tsx

@@ -0,0 +1,227 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { WakaCreditBurnRate } from "./index"
+
+// ============================================================================
+// Mock Data Generators
+// ============================================================================
+
+function generateDailyUsage(
+  days: number,
+  baseValue: number,
+  variance: number
+): { date: string; value: number }[] {
+  const data: { date: string; value: number }[] = []
+  const now = new Date()
+
+  for (let i = days - 1; i >= 0; i--) {
+    const date = new Date(now)
+    date.setDate(date.getDate() - i)
+    const jitter = (Math.random() - 0.5) * 2 * variance
+    const value = Math.max(0, baseValue + jitter)
+    data.push({
+      date: date.toISOString().split("T")[0],
+      value: Math.round(value * 10) / 10,
+    })
+  }
+
+  return data
+}
+
+// Deterministic mock data for consistent stories
+const defaultUsage: { date: string; value: number }[] = [
+  { date: "2026-01-30", value: 42.3 },
+  { date: "2026-01-31", value: 38.7 },
+  { date: "2026-02-01", value: 45.1 },
+  { date: "2026-02-02", value: 40.5 },
+  { date: "2026-02-03", value: 43.8 },
+  { date: "2026-02-04", value: 37.2 },
+  { date: "2026-02-05", value: 41.6 },
+  { date: "2026-02-06", value: 44.9 },
+  { date: "2026-02-07", value: 39.3 },
+  { date: "2026-02-08", value: 46.2 },
+  { date: "2026-02-09", value: 42.7 },
+  { date: "2026-02-10", value: 38.1 },
+  { date: "2026-02-11", value: 43.4 },
+  { date: "2026-02-12", value: 41.0 },
+]
+
+const highBurnUsage: { date: string; value: number }[] = [
+  { date: "2026-01-30", value: 180.5 },
+  { date: "2026-01-31", value: 195.2 },
+  { date: "2026-02-01", value: 210.8 },
+  { date: "2026-02-02", value: 188.3 },
+  { date: "2026-02-03", value: 225.1 },
+  { date: "2026-02-04", value: 203.7 },
+  { date: "2026-02-05", value: 198.4 },
+  { date: "2026-02-06", value: 215.6 },
+  { date: "2026-02-07", value: 230.2 },
+  { date: "2026-02-08", value: 207.9 },
+  { date: "2026-02-09", value: 222.3 },
+  { date: "2026-02-10", value: 240.1 },
+  { date: "2026-02-11", value: 218.5 },
+  { date: "2026-02-12", value: 235.7 },
+]
+
+const lowBurnUsage: { date: string; value: number }[] = [
+  { date: "2026-01-30", value: 5.2 },
+  { date: "2026-01-31", value: 3.8 },
+  { date: "2026-02-01", value: 6.1 },
+  { date: "2026-02-02", value: 4.5 },
+  { date: "2026-02-03", value: 2.9 },
+  { date: "2026-02-04", value: 5.7 },
+  { date: "2026-02-05", value: 3.3 },
+  { date: "2026-02-06", value: 4.8 },
+  { date: "2026-02-07", value: 6.4 },
+  { date: "2026-02-08", value: 3.1 },
+  { date: "2026-02-09", value: 5.5 },
+  { date: "2026-02-10", value: 4.2 },
+  { date: "2026-02-11", value: 3.6 },
+  { date: "2026-02-12", value: 5.0 },
+]
+
+// ============================================================================
+// Meta
+// ============================================================================
+
+const meta: Meta<typeof WakaCreditBurnRate> = {
+  title: "Components/Credit/WakaCreditBurnRate",
+  component: WakaCreditBurnRate,
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component:
+          "Displays credit burn rate with an SVG sparkline, projection line, and depletion estimate. Available in compact sparkline and full card variants.",
+      },
+    },
+  },
+  tags: ["autodocs"],
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["sparkline", "card"],
+      description: "Display variant",
+    },
+    showProjection: {
+      control: "boolean",
+      description: "Show projection line on the sparkline",
+    },
+    projectionDays: {
+      control: { type: "number", min: 1, max: 30 },
+      description: "Number of days to project forward",
+    },
+    width: {
+      control: { type: "number", min: 60, max: 600 },
+      description: "Width of the SVG sparkline",
+    },
+    height: {
+      control: { type: "number", min: 16, max: 200 },
+      description: "Height of the SVG sparkline",
+    },
+    animated: {
+      control: "boolean",
+      description: "Animate the sparkline on mount",
+    },
+    balance: {
+      control: { type: "number", min: 0 },
+      description: "Current credit balance",
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof WakaCreditBurnRate>
+
+// ============================================================================
+// Stories
+// ============================================================================
+
+/** Default sparkline variant showing moderate burn rate with healthy remaining days. */
+export const Default: Story = {
+  args: {
+    dailyUsage: defaultUsage,
+    balance: 5000,
+    variant: "sparkline",
+    width: 120,
+    height: 32,
+    animated: true,
+  },
+}
+
+/** Full card variant with sparkline, burn rate number, days remaining, and projected depletion date. */
+export const Card: Story = {
+  args: {
+    dailyUsage: defaultUsage,
+    balance: 5000,
+    variant: "card",
+    width: 280,
+    height: 64,
+    animated: true,
+    showProjection: true,
+    projectionDays: 7,
+  },
+}
+
+/** Sparkline with projection line showing expected future usage trend. */
+export const WithProjection: Story = {
+  args: {
+    dailyUsage: defaultUsage,
+    balance: 5000,
+    variant: "sparkline",
+    showProjection: true,
+    projectionDays: 7,
+    width: 160,
+    height: 32,
+    animated: true,
+  },
+}
+
+/** High burn rate scenario: credits are depleting rapidly (< 7 days remaining). Red status indicator. */
+export const HighBurn: Story = {
+  args: {
+    dailyUsage: highBurnUsage,
+    balance: 800,
+    variant: "card",
+    width: 280,
+    height: 64,
+    showProjection: true,
+    projectionDays: 7,
+    animated: true,
+  },
+}
+
+/** Low burn rate scenario: credits will last a very long time (> 30 days). Green status indicator. */
+export const LowBurn: Story = {
+  args: {
+    dailyUsage: lowBurnUsage,
+    balance: 10000,
+    variant: "card",
+    width: 280,
+    height: 64,
+    showProjection: true,
+    projectionDays: 14,
+    animated: true,
+  },
+}
+
+/** Animated sparkline demonstrating the draw-in animation on mount. */
+export const Animated: Story = {
+  args: {
+    dailyUsage: defaultUsage,
+    balance: 2000,
+    variant: "sparkline",
+    showProjection: true,
+    projectionDays: 7,
+    width: 160,
+    height: 32,
+    animated: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Demonstrates the animated sparkline draw-in effect. The polyline is progressively revealed using stroke-dashoffset transitions.",
+      },
+    },
+  },
+}