@wakastellar/ui 3.2.0 → 3.3.0

package/src/components/waka-credit-usage-chart/index.tsx

@@ -0,0 +1,307 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../utils/cn"
+import {
+  AreaChart,
+  Area,
+  XAxis,
+  YAxis,
+  CartesianGrid,
+  Tooltip,
+  Legend,
+  ResponsiveContainer,
+} from "recharts"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface UsageDataPoint {
+  date: string
+  value: number
+}
+
+export interface WakaCreditUsageChartProps {
+  /** Array of data points with date and value */
+  data: UsageDataPoint[]
+  /** Optional comparison dataset (previous period) rendered as dashed/lighter area */
+  compareWith?: UsageDataPoint[]
+  /** Time period granularity */
+  period?: "day" | "week" | "month" | "year"
+  /** Whether to stack the areas */
+  stacked?: boolean
+  /** Chart height in pixels */
+  height?: number
+  /** Show the legend below the chart */
+  showLegend?: boolean
+  /** Show the cartesian grid */
+  showGrid?: boolean
+  /** Enable chart animations */
+  animated?: boolean
+  /** Primary area color */
+  color?: string
+  /** Comparison area color */
+  compareColor?: string
+  /** Custom value formatter for tooltip and Y axis */
+  formatValue?: (value: number) => string
+  /** Callback when the period selector is changed; renders period tabs when provided */
+  onPeriodChange?: (period: string) => void
+  /** Additional CSS classes */
+  className?: string
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const PERIODS: { value: "day" | "week" | "month" | "year"; label: string }[] = [
+  { value: "day", label: "Day" },
+  { value: "week", label: "Week" },
+  { value: "month", label: "Month" },
+  { value: "year", label: "Year" },
+]
+
+const DEFAULT_COLOR = "#3b82f6"
+const DEFAULT_COMPARE_COLOR = "#94a3b8"
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Merge the main dataset with the comparison dataset into a single array
+ * suitable for recharts, keyed on the `date` field.
+ */
+function mergeData(
+  data: UsageDataPoint[],
+  compareWith?: UsageDataPoint[]
+): Array<{ date: string; value: number; compareValue?: number }> {
+  if (!compareWith || compareWith.length === 0) {
+    return data.map((d) => ({ date: d.date, value: d.value }))
+  }
+
+  // Build a map from comparison data keyed by index (same position alignment)
+  // because comparison period dates will typically differ.
+  return data.map((d, i) => ({
+    date: d.date,
+    value: d.value,
+    compareValue: compareWith[i]?.value,
+  }))
+}
+
+function defaultFormatValue(value: number): string {
+  return value.toLocaleString("en-US")
+}
+
+// ============================================================================
+// Custom Tooltip
+// ============================================================================
+
+interface CustomTooltipProps {
+  active?: boolean
+  payload?: Array<{
+    name: string
+    value: number
+    color: string
+    dataKey: string
+  }>
+  label?: string
+  formatValue: (value: number) => string
+}
+
+function CustomTooltip({ active, payload, label, formatValue }: CustomTooltipProps) {
+  if (!active || !payload || payload.length === 0) return null
+
+  return (
+    <div className="rounded-lg border bg-popover px-3 py-2 shadow-md">
+      <p className="mb-1 text-xs font-medium text-muted-foreground">{label}</p>
+      {payload.map((entry) => (
+        <div key={entry.dataKey} className="flex items-center gap-2 text-sm">
+          <span
+            className="inline-block h-2 w-2 rounded-full"
+            style={{ backgroundColor: entry.color }}
+          />
+          <span className="text-muted-foreground">{entry.name}:</span>
+          <span className="font-semibold tabular-nums">{formatValue(entry.value)}</span>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+// ============================================================================
+// Period Selector
+// ============================================================================
+
+interface PeriodSelectorProps {
+  period: "day" | "week" | "month" | "year"
+  onPeriodChange: (period: string) => void
+}
+
+function PeriodSelector({ period, onPeriodChange }: PeriodSelectorProps) {
+  return (
+    <div className="mb-4 flex gap-1 rounded-lg bg-muted p-1">
+      {PERIODS.map((p) => (
+        <button
+          key={p.value}
+          type="button"
+          onClick={() => onPeriodChange(p.value)}
+          className={cn(
+            "rounded-md px-3 py-1.5 text-xs font-medium transition-colors",
+            period === p.value
+              ? "bg-background text-foreground shadow-sm"
+              : "text-muted-foreground hover:text-foreground"
+          )}
+        >
+          {p.label}
+        </button>
+      ))}
+    </div>
+  )
+}
+
+// ============================================================================
+// Main Component
+// ============================================================================
+
+export function WakaCreditUsageChart({
+  data,
+  compareWith,
+  period = "month",
+  stacked = false,
+  height = 300,
+  showLegend = false,
+  showGrid = true,
+  animated = true,
+  color = DEFAULT_COLOR,
+  compareColor = DEFAULT_COMPARE_COLOR,
+  formatValue = defaultFormatValue,
+  onPeriodChange,
+  className,
+}: WakaCreditUsageChartProps) {
+  const mergedData = React.useMemo(
+    () => mergeData(data, compareWith),
+    [data, compareWith]
+  )
+
+  const gradientId = React.useId()
+  const compareGradientId = React.useId()
+
+  // Sanitize IDs for use as SVG references (remove colons from React.useId output)
+  const safeGradientId = `usage-gradient-${gradientId.replace(/:/g, "")}`
+  const safeCompareGradientId = `compare-gradient-${compareGradientId.replace(/:/g, "")}`
+
+  const hasComparison = compareWith && compareWith.length > 0
+
+  return (
+    <div className={cn("w-full", className)}>
+      {/* Period selector tabs */}
+      {onPeriodChange && (
+        <PeriodSelector period={period} onPeriodChange={onPeriodChange} />
+      )}
+
+      {/* Chart */}
+      <ResponsiveContainer width="100%" height={height}>
+        <AreaChart
+          data={mergedData}
+          margin={{ top: 4, right: 4, left: 0, bottom: 0 }}
+        >
+          {/* Gradient definitions */}
+          <defs>
+            <linearGradient id={safeGradientId} x1="0" y1="0" x2="0" y2="1">
+              <stop offset="5%" stopColor={color} stopOpacity={0.4} />
+              <stop offset="95%" stopColor={color} stopOpacity={0.05} />
+            </linearGradient>
+            {hasComparison && (
+              <linearGradient id={safeCompareGradientId} x1="0" y1="0" x2="0" y2="1">
+                <stop offset="5%" stopColor={compareColor} stopOpacity={0.15} />
+                <stop offset="95%" stopColor={compareColor} stopOpacity={0.02} />
+              </linearGradient>
+            )}
+          </defs>
+
+          {/* Grid */}
+          {showGrid && (
+            <CartesianGrid
+              strokeDasharray="3 3"
+              vertical={false}
+              className="stroke-border/50"
+            />
+          )}
+
+          {/* Axes */}
+          <XAxis
+            dataKey="date"
+            axisLine={false}
+            tickLine={false}
+            tick={{ fontSize: 12 }}
+            className="fill-muted-foreground"
+            dy={8}
+          />
+          <YAxis
+            axisLine={false}
+            tickLine={false}
+            tick={{ fontSize: 12 }}
+            className="fill-muted-foreground"
+            tickFormatter={(v: number) => formatValue(v)}
+            width={60}
+          />
+
+          {/* Tooltip */}
+          <Tooltip
+            content={<CustomTooltip formatValue={formatValue} />}
+            cursor={{ stroke: "hsl(var(--border))", strokeWidth: 1 }}
+          />
+
+          {/* Legend */}
+          {showLegend && (
+            <Legend
+              verticalAlign="bottom"
+              align="center"
+              wrapperStyle={{ paddingTop: 16 }}
+              iconType="circle"
+            />
+          )}
+
+          {/* Comparison area (rendered first, behind the main area) */}
+          {hasComparison && (
+            <Area
+              dataKey="compareValue"
+              name="Previous Period"
+              type="monotone"
+              stroke={compareColor}
+              strokeWidth={1.5}
+              strokeDasharray="6 3"
+              fill={`url(#${safeCompareGradientId})`}
+              fillOpacity={1}
+              stackId={stacked ? "stack" : undefined}
+              isAnimationActive={animated}
+              animationDuration={800}
+              dot={false}
+              activeDot={{ r: 3, fill: compareColor, stroke: "white", strokeWidth: 1.5 }}
+            />
+          )}
+
+          {/* Main area */}
+          <Area
+            dataKey="value"
+            name="Current Period"
+            type="monotone"
+            stroke={color}
+            strokeWidth={2}
+            fill={`url(#${safeGradientId})`}
+            fillOpacity={1}
+            stackId={stacked ? "stack" : undefined}
+            isAnimationActive={animated}
+            animationDuration={800}
+            dot={false}
+            activeDot={{ r: 4, fill: color, stroke: "white", strokeWidth: 2 }}
+          />
+        </AreaChart>
+      </ResponsiveContainer>
+    </div>
+  )
+}
+
+export default WakaCreditUsageChart

package/src/components/waka-doc-breadcrumb/WakaDocBreadcrumb.stories.tsx

@@ -0,0 +1,47 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { WakaDocBreadcrumb } from './index'
+import * as React from 'react'
+
+const meta: Meta<typeof WakaDocBreadcrumb> = {
+  title: 'Components/Documentation/WakaDocBreadcrumb',
+  component: WakaDocBreadcrumb,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'Breadcrumb navigation for documentation pages with clickable intermediate items.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof WakaDocBreadcrumb>
+
+export const Default: Story = {
+  args: {
+    items: [
+      { id: 'docs', label: 'Documentation' },
+      { id: 'guide', label: 'Guide' },
+      { id: 'install', label: 'Installation' },
+    ],
+  },
+}
+
+export const SingleItem: Story = {
+  args: {
+    items: [{ id: 'home', label: 'Documentation' }],
+  },
+}
+
+export const LongPath: Story = {
+  args: {
+    items: [
+      { id: 'docs', label: 'Documentation' },
+      { id: 'api', label: 'API Reference' },
+      { id: 'components', label: 'Components' },
+      { id: 'doc-renderer', label: 'WakaDocRenderer' },
+    ],
+  },
+}

package/src/components/waka-doc-breadcrumb/index.tsx

@@ -0,0 +1,42 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../utils"
+import { ChevronRight, BookOpen } from "lucide-react"
+
+export interface BreadcrumbItem {
+  id: string
+  label: string
+  href?: string
+}
+
+export interface WakaDocBreadcrumbProps {
+  items: BreadcrumbItem[]
+  onItemClick?: (item: BreadcrumbItem) => void
+  className?: string
+}
+
+export function WakaDocBreadcrumb({ items, onItemClick, className }: WakaDocBreadcrumbProps) {
+  if (items.length === 0) return null
+
+  return (
+    <nav className={cn("flex items-center gap-1 text-sm", className)}>
+      <BookOpen className="h-4 w-4 text-muted-foreground" />
+      {items.map((item, i) => (
+        <React.Fragment key={item.id}>
+          {i > 0 && <ChevronRight className="h-3 w-3 text-muted-foreground/50" />}
+          {i === items.length - 1 ? (
+            <span className="font-medium text-foreground">{item.label}</span>
+          ) : (
+            <button
+              onClick={() => onItemClick?.(item)}
+              className="text-muted-foreground transition-colors hover:text-foreground"
+            >
+              {item.label}
+            </button>
+          )}
+        </React.Fragment>
+      ))}
+    </nav>
+  )
+}

package/src/components/waka-doc-callout/WakaDocCallout.stories.tsx

@@ -0,0 +1,67 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { WakaDocCallout } from './index'
+import * as React from 'react'
+
+const meta: Meta<typeof WakaDocCallout> = {
+  title: 'Components/Documentation/WakaDocCallout',
+  component: WakaDocCallout,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'Styled callout blocks for documentation: info, warning, danger, and tip variants with icons and colored borders.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    type: {
+      control: 'select',
+      options: ['info', 'warning', 'danger', 'tip'],
+    },
+    title: { control: 'text' },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof WakaDocCallout>
+
+export const Default: Story = {
+  args: {
+    type: 'info',
+    title: 'Information',
+    children: 'This is an informational callout for documentation.',
+  },
+}
+
+export const AllVariants: Story = {
+  render: () => (
+    <div className="w-[500px] space-y-4">
+      <WakaDocCallout type="info" title="Information">
+        This is an informational callout. Use it for general notes.
+      </WakaDocCallout>
+      <WakaDocCallout type="warning" title="Attention">
+        This is a warning callout. Something needs attention.
+      </WakaDocCallout>
+      <WakaDocCallout type="danger" title="Danger">
+        This is a danger callout. Critical issue or breaking change.
+      </WakaDocCallout>
+      <WakaDocCallout type="tip" title="Astuce">
+        This is a tip callout. Helpful advice for the reader.
+      </WakaDocCallout>
+    </div>
+  ),
+}
+
+export const WithoutTitle: Story = {
+  render: () => (
+    <div className="w-[500px] space-y-4">
+      <WakaDocCallout type="info">
+        A simple callout without a title.
+      </WakaDocCallout>
+      <WakaDocCallout type="tip">
+        Tips can also appear without titles for brief notes.
+      </WakaDocCallout>
+    </div>
+  ),
+}

package/src/components/waka-doc-callout/index.tsx

@@ -0,0 +1,86 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../utils"
+import { Info, AlertTriangle, XCircle, Lightbulb } from "lucide-react"
+
+export type CalloutType = "info" | "warning" | "danger" | "tip"
+
+export interface WakaDocCalloutProps {
+  type?: CalloutType
+  title?: string
+  children: React.ReactNode
+  className?: string
+}
+
+const CALLOUT_CONFIG: Record<CalloutType, {
+  icon: React.ElementType
+  borderColor: string
+  bgColor: string
+  iconColor: string
+  titleColor: string
+}> = {
+  info: {
+    icon: Info,
+    borderColor: "border-l-blue-500",
+    bgColor: "bg-blue-500/5",
+    iconColor: "text-blue-500",
+    titleColor: "text-blue-700 dark:text-blue-400",
+  },
+  warning: {
+    icon: AlertTriangle,
+    borderColor: "border-l-amber-500",
+    bgColor: "bg-amber-500/5",
+    iconColor: "text-amber-500",
+    titleColor: "text-amber-700 dark:text-amber-400",
+  },
+  danger: {
+    icon: XCircle,
+    borderColor: "border-l-red-500",
+    bgColor: "bg-red-500/5",
+    iconColor: "text-red-500",
+    titleColor: "text-red-700 dark:text-red-400",
+  },
+  tip: {
+    icon: Lightbulb,
+    borderColor: "border-l-emerald-500",
+    bgColor: "bg-emerald-500/5",
+    iconColor: "text-emerald-500",
+    titleColor: "text-emerald-700 dark:text-emerald-400",
+  },
+}
+
+export function WakaDocCallout({
+  type = "info",
+  title,
+  children,
+  className,
+}: WakaDocCalloutProps) {
+  const config = CALLOUT_CONFIG[type]
+  const Icon = config.icon
+
+  return (
+    <div
+      className={cn(
+        "my-4 rounded-r-lg border-l-4 p-4 backdrop-blur-sm",
+        config.borderColor,
+        config.bgColor,
+        className
+      )}
+    >
+      <div className="flex gap-3">
+        <Icon className={cn("mt-0.5 h-5 w-5 shrink-0", config.iconColor)} />
+        <div className="min-w-0 flex-1">
+          {title && (
+            <p className={cn("mb-1 font-semibold", config.titleColor)}>
+              {title}
+            </p>
+          )}
+          <div className="text-sm text-foreground/80 [&>p]:mb-2 [&>p:last-child]:mb-0">
+            {children}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/waka-doc-code-block/WakaDocCodeBlock.stories.tsx

@@ -0,0 +1,92 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { WakaDocCodeBlock } from './index'
+import * as React from 'react'
+
+const meta: Meta<typeof WakaDocCodeBlock> = {
+  title: 'Components/Documentation/WakaDocCodeBlock',
+  component: WakaDocCodeBlock,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'Code block with PrismJS syntax highlighting, copy-to-clipboard, line numbers, and line highlighting.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    language: {
+      control: 'select',
+      options: ['typescript', 'javascript', 'python', 'bash', 'json', 'css', 'go', 'rust', 'sql', 'yaml'],
+    },
+    showLineNumbers: { control: 'boolean' },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof WakaDocCodeBlock>
+
+const tsCode = `interface User {
+  id: string
+  name: string
+  email: string
+  role: "admin" | "user"
+}
+
+async function getUser(id: string): Promise<User> {
+  const response = await fetch(\`/api/users/\${id}\`)
+  if (!response.ok) throw new Error("User not found")
+  return response.json()
+}`
+
+export const Default: Story = {
+  args: {
+    code: tsCode,
+    language: 'typescript',
+    filename: 'api.ts',
+    showLineNumbers: true,
+  },
+}
+
+export const WithHighlightedLines: Story = {
+  args: {
+    code: tsCode,
+    language: 'typescript',
+    filename: 'api.ts',
+    showLineNumbers: true,
+    highlightLines: [8, 9, 10],
+  },
+}
+
+export const MultipleLanguages: Story = {
+  render: () => (
+    <div className="w-[600px] space-y-4">
+      <WakaDocCodeBlock
+        code='const greeting = "Hello, World!";\nconsole.log(greeting);'
+        language="javascript"
+        filename="hello.js"
+      />
+      <WakaDocCodeBlock
+        code='def fibonacci(n):\n    if n <= 1:\n        return n\n    return fibonacci(n-1) + fibonacci(n-2)'
+        language="python"
+        filename="math.py"
+        showLineNumbers
+      />
+      <WakaDocCodeBlock
+        code='{\n  "name": "@wakastellar/ui",\n  "version": "3.1.0",\n  "description": "UI Library"\n}'
+        language="json"
+        filename="package.json"
+      />
+      <WakaDocCodeBlock
+        code="docker build -t myapp .\ndocker run -p 3000:3000 myapp"
+        language="bash"
+      />
+    </div>
+  ),
+}
+
+export const NoLanguage: Story = {
+  args: {
+    code: 'Just plain text\nwith multiple lines\nno syntax highlighting',
+  },
+}