@hivemindhq/core 0.4.0 → 0.5.0

package/src/components/CryptoAmount.tsx

@@ -0,0 +1,447 @@
+import * as React from 'react'
+import { cn } from '../utils/cn'
+import { Tooltip, TooltipTrigger, TooltipContent } from './ui/tooltip'
+import { formatCryptoAmount } from '../utils/formatting'
+
+/**
+ * Display variant for the CryptoAmount component.
+ * 
+ * - `default`: Crypto on top, fiat below (stacked)
+ * - `inline`: Single line with fiat in parentheses
+ * - `crypto-only`: Just the native token amount
+ * - `fiat-only`: Just the fiat equivalent (useful for previews)
+ * - `compact`: Abbreviated format for large amounts (1.5M TRUST)
+ */
+export type CryptoAmountVariant = 'default' | 'inline' | 'crypto-only' | 'fiat-only' | 'compact'
+
+/**
+ * Size variant for the CryptoAmount component.
+ */
+export type CryptoAmountSize = 'sm' | 'md' | 'lg'
+
+/**
+ * Controls where the secondary currency (fiat for crypto display, crypto for fiat display) appears.
+ * 
+ * - `inline`: Show alongside primary currency (default behavior)
+ * - `tooltip`: Show only in tooltip on hover (saves space)
+ * - `hidden`: Don't show secondary currency at all
+ */
+export type SecondaryDisplayMode = 'inline' | 'tooltip' | 'hidden'
+
+export interface CryptoAmountProps {
+  /** 
+   * The crypto amount. By default, expects wei/smallest unit (string or bigint).
+   * If `isTokenUnits` is true, expects the value already in token units (e.g., 1.5 for 1.5 TRUST).
+   */
+  value: string | bigint | number
+  
+  /** Number of decimals for the token (default: 18). Ignored when isTokenUnits is true. */
+  decimals?: number
+  
+  /**
+   * When true, the value is already in token units (e.g., 1.5 for 1.5 TRUST).
+   * When false (default), the value is in wei/smallest units and will be converted.
+   */
+  isTokenUnits?: boolean
+  
+  /** Token symbol to display (e.g., 'TRUST', 'ETH') */
+  symbol: string
+  
+  /**
+   * Exchange rate for fiat conversion (1 token = X fiat).
+   * If undefined/null, fiat display is hidden.
+   */
+  exchangeRate?: number | null
+  
+  /**
+   * Fiat currency code for formatting (default: 'USD').
+   * Used with Intl.NumberFormat for proper currency display.
+   */
+  currencyCode?: string
+  
+  /**
+   * Locale for number/currency formatting (default: browser locale or 'en-US')
+   */
+  locale?: string
+  
+  /** Display variant (default: 'default') */
+  variant?: CryptoAmountVariant
+  
+  /** Size variant (default: 'md') */
+  size?: CryptoAmountSize
+  
+  /**
+   * Maximum significant digits before truncation (default: 10).
+   * Amounts exceeding this will show "..." with full value in tooltip.
+   */
+  maxSignificantDigits?: number
+  
+  /**
+   * Maximum decimal places to display (default: 6).
+   * Applied after conversion but before significant digit truncation.
+   */
+  maxDecimals?: number
+  
+  /** Whether to show the token symbol (default: true) */
+  showSymbol?: boolean
+  
+  /** Whether to show fiat value when exchange rate is available (default: true) */
+  showFiat?: boolean
+  
+  /**
+   * Where to display the secondary currency (fiat when showing crypto, crypto when showing fiat).
+   * - `inline`: Show alongside primary (default behavior)
+   * - `tooltip`: Show in tooltip on hover (saves space in dense UIs)
+   * - `hidden`: Don't show at all
+   * @default 'inline'
+   */
+  secondaryDisplay?: SecondaryDisplayMode
+  
+  /** Additional CSS classes for the container */
+  className?: string
+  
+  /** Additional CSS classes for the crypto amount text */
+  cryptoClassName?: string
+  
+  /** Additional CSS classes for the fiat amount text */
+  fiatClassName?: string
+}
+
+/**
+ * A unified component for displaying cryptocurrency amounts with optional fiat conversion.
+ * 
+ * Features:
+ * - Crypto-first display (native token amount is primary)
+ * - Optional fiat conversion shown as secondary (inline or in tooltip)
+ * - Truncation with tooltip for large amounts
+ * - Multiple display variants (stacked, inline, compact)
+ * - Proper number formatting based on locale
+ * 
+ * @example
+ * ```tsx
+ * // Basic usage - stacked display
+ * <CryptoAmount 
+ *   value="1500000000000000000" 
+ *   symbol="TRUST" 
+ *   exchangeRate={0.42} 
+ * />
+ * // Renders:
+ * // 1.5 TRUST
+ * // $0.63
+ * 
+ * // Inline variant
+ * <CryptoAmount 
+ *   value="1500000000000000000" 
+ *   symbol="TRUST" 
+ *   exchangeRate={0.42}
+ *   variant="inline"
+ * />
+ * // Renders: 1.5 TRUST (~$0.63)
+ * 
+ * // Space-saving: show crypto only, fiat in tooltip
+ * <CryptoAmount 
+ *   value="1500000000000000000" 
+ *   symbol="TRUST"
+ *   exchangeRate={0.42}
+ *   secondaryDisplay="tooltip"
+ * />
+ * // Renders: 1.5 TRUST (hover shows: 1.5 TRUST + ≈ $0.63)
+ * 
+ * // Compact variant for large amounts
+ * <CryptoAmount 
+ *   value="1500000000000000000000000" 
+ *   symbol="TRUST"
+ *   variant="compact"
+ * />
+ * // Renders: 1.5M TRUST
+ * ```
+ */
+export function CryptoAmount({
+  value,
+  decimals = 18,
+  isTokenUnits = false,
+  symbol,
+  exchangeRate,
+  currencyCode = 'USD',
+  locale,
+  variant = 'default',
+  size = 'md',
+  maxSignificantDigits = 10,
+  maxDecimals = 6,
+  showSymbol = true,
+  showFiat = true,
+  secondaryDisplay = 'inline',
+  className,
+  cryptoClassName,
+  fiatClassName,
+}: CryptoAmountProps) {
+  // Determine locale
+  const effectiveLocale = locale || (typeof navigator !== 'undefined' ? navigator.language : 'en-US')
+  
+  // Format the crypto amount
+  const formatted = React.useMemo(() => {
+    // If value is already in token units, create a simple formatted result
+    if (isTokenUnits) {
+      const numericValue = typeof value === 'string' ? parseFloat(value) : Number(value)
+      const fullValue = numericValue.toString()
+      
+      // Apply maxDecimals truncation for display
+      let displayValue = fullValue
+      if (maxDecimals !== undefined) {
+        // Round to maxDecimals places
+        const factor = Math.pow(10, maxDecimals)
+        const truncated = Math.floor(numericValue * factor) / factor
+        displayValue = truncated.toLocaleString(effectiveLocale, {
+          minimumFractionDigits: 0,
+          maximumFractionDigits: maxDecimals,
+        })
+      }
+      
+      const isTruncated = displayValue !== fullValue
+      return {
+        display: displayValue,
+        fullValue,
+        isTruncated,
+        numericValue,
+      }
+    }
+    
+    // Otherwise, convert from wei
+    // Ensure value is string or bigint for formatCryptoAmount
+    const weiValue = typeof value === 'number' ? value.toString() : value
+    return formatCryptoAmount(weiValue, decimals, {
+      maxSignificantDigits,
+      maxDecimals,
+      compact: variant === 'compact',
+      locale: effectiveLocale,
+    })
+  }, [value, decimals, isTokenUnits, maxSignificantDigits, maxDecimals, variant, effectiveLocale])
+  
+  // Calculate fiat value if exchange rate is available
+  // Note: We calculate even when secondaryDisplay='tooltip' because we need it for the tooltip
+  const fiatFormatted = React.useMemo(() => {
+    if (!showFiat || exchangeRate == null || variant === 'crypto-only' || secondaryDisplay === 'hidden') {
+      return null
+    }
+    
+    const fiatValue = formatted.numericValue * exchangeRate
+    
+    try {
+      return new Intl.NumberFormat(effectiveLocale, {
+        style: 'currency',
+        currency: currencyCode.toUpperCase(),
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+      }).format(fiatValue)
+    } catch {
+      // Fallback if currency code is invalid
+      return null
+    }
+  }, [formatted.numericValue, exchangeRate, currencyCode, effectiveLocale, showFiat, variant, secondaryDisplay])
+  
+  // Determine if we should show fiat inline (vs in tooltip)
+  const showFiatInline = fiatFormatted && secondaryDisplay === 'inline'
+  
+  // Size-based styling
+  const sizeStyles = {
+    sm: {
+      crypto: 'text-sm',
+      fiat: 'text-xs',
+    },
+    md: {
+      crypto: 'text-base',
+      fiat: 'text-sm',
+    },
+    lg: {
+      crypto: 'text-lg font-semibold',
+      fiat: 'text-base',
+    },
+  }
+  
+  const styles = sizeStyles[size]
+  
+  // Build the crypto display string
+  const cryptoDisplay = showSymbol 
+    ? `${formatted.display} ${symbol}`
+    : formatted.display
+  
+  // Full value for tooltip (when truncated)
+  const fullCryptoDisplay = showSymbol
+    ? `${formatted.fullValue} ${symbol}`
+    : formatted.fullValue
+  
+  // Determine if we need a tooltip
+  // Show tooltip if truncated OR if secondary currency should be in tooltip
+  const showSecondaryInTooltip = secondaryDisplay === 'tooltip' && fiatFormatted
+  const needsTooltip = formatted.isTruncated || showSecondaryInTooltip
+  
+  // Render the crypto amount (with or without tooltip)
+  const cryptoElement = (
+    <span 
+      className={cn(
+        styles.crypto,
+        'font-medium',
+        // Add cursor hint when tooltip contains extra info
+        // showSecondaryInTooltip && 'cursor-help',
+        cryptoClassName
+      )}
+    >
+      {cryptoDisplay}
+    </span>
+  )
+  
+  // Build tooltip content - show full crypto always, add fiat if in tooltip mode
+  // Note: Tooltip uses bg-primary, so we use text-primary-foreground with opacity
+  // rather than text-muted-foreground which is designed for page backgrounds
+  const tooltipContent = (
+    <div className="flex flex-col gap-0.5">
+      <span className="font-mono text-xs">{fullCryptoDisplay}</span>
+      {showSecondaryInTooltip && (
+        <span className="text-xs text-primary-foreground/70">≈ {fiatFormatted}</span>
+      )}
+    </div>
+  )
+  
+  const cryptoWithTooltip = needsTooltip ? (
+    <Tooltip delayDuration={showSecondaryInTooltip ? 300 : 1000}>
+      <TooltipTrigger asChild>
+        {cryptoElement}
+      </TooltipTrigger>
+      <TooltipContent>
+        {tooltipContent}
+      </TooltipContent>
+    </Tooltip>
+  ) : cryptoElement
+  
+  // Render based on variant
+  if (variant === 'crypto-only') {
+    return (
+      <div className={cn('flex items-center', className)}>
+        {cryptoWithTooltip}
+      </div>
+    )
+  }
+  
+  if (variant === 'fiat-only') {
+    // Only show fiat, return null if no exchange rate available
+    if (!fiatFormatted) {
+      return null
+    }
+    return (
+      <span className={cn(
+        styles.fiat,
+        'text-muted-foreground',
+        fiatClassName,
+        className
+      )}>
+        ≈ {fiatFormatted}
+      </span>
+    )
+  }
+  
+  if (variant === 'inline') {
+    return (
+      <div className={cn('flex items-center gap-1', className)}>
+        {cryptoWithTooltip}
+        {showFiatInline && (
+          <span className={cn(
+            styles.fiat,
+            'text-muted-foreground',
+            fiatClassName
+          )}>
+            (~{fiatFormatted})
+          </span>
+        )}
+      </div>
+    )
+  }
+  
+  if (variant === 'compact') {
+    return (
+      <div className={cn('flex items-center gap-1', className)}>
+        {cryptoWithTooltip}
+        {showFiatInline && (
+          <span className={cn(
+            styles.fiat,
+            'text-muted-foreground',
+            fiatClassName
+          )}>
+            ({fiatFormatted})
+          </span>
+        )}
+      </div>
+    )
+  }
+  
+  // Default: stacked layout
+  return (
+    <div className={cn('flex flex-col', className)}>
+      {cryptoWithTooltip}
+      {showFiatInline && (
+        <span className={cn(
+          styles.fiat,
+          'text-muted-foreground',
+          fiatClassName
+        )}>
+          {fiatFormatted}
+        </span>
+      )}
+    </div>
+  )
+}
+
+export default CryptoAmount
+
+// ============================================================================
+// Helper utilities for creating CryptoAmount props
+// ============================================================================
+
+/**
+ * Props subset for creating a CryptoAmount from an exchange rate context.
+ * Use this type when building a hook wrapper in your app.
+ */
+export type CryptoAmountRateProps = Pick<
+  CryptoAmountProps,
+  'exchangeRate' | 'currencyCode' | 'locale'
+>
+
+/**
+ * Creates CryptoAmountRateProps from an exchange rate and currency settings.
+ * This is a helper for building hook wrappers in consuming applications.
+ * 
+ * @param exchangeRate - The current exchange rate (1 token = X fiat), or null/undefined
+ * @param currencyCode - The fiat currency code (e.g., 'USD', 'EUR')
+ * @param locale - Optional locale for formatting
+ * @returns Props object to spread onto CryptoAmount
+ * 
+ * @example
+ * ```tsx
+ * // In your app's hook wrapper:
+ * export function useCryptoAmountProps() {
+ *   const { data } = useExchangeRates()
+ *   const { selectedCurrency } = useCurrency()
+ *   
+ *   return createCryptoAmountRateProps(
+ *     data?.rate,
+ *     selectedCurrency,
+ *     navigator.language
+ *   )
+ * }
+ * 
+ * // Then in components:
+ * const rateProps = useCryptoAmountProps()
+ * <CryptoAmount value="1000000000000000000" symbol="TRUST" {...rateProps} />
+ * ```
+ */
+export function createCryptoAmountRateProps(
+  exchangeRate: number | null | undefined,
+  currencyCode: string = 'USD',
+  locale?: string
+): CryptoAmountRateProps {
+  return {
+    exchangeRate: exchangeRate ?? undefined,
+    currencyCode,
+    locale,
+  }
+}
+

package/src/components/ErrorBanner.tsx

@@ -0,0 +1,35 @@
+import { cn } from '../utils/cn'
+
+export interface ErrorBannerProps {
+  /** The error message to display */
+  error: string
+  /** Optional HTTP status code */
+  code?: number
+  /** Additional CSS classes */
+  className?: string
+}
+
+/**
+ * A simple error banner component for displaying error messages.
+ * Centered layout with large heading and subtitle.
+ * 
+ * @example
+ * <ErrorBanner error="Page not found" code={404} />
+ */
+export const ErrorBanner = ({ 
+  error, 
+  code, 
+  className 
+}: ErrorBannerProps) => {
+  return (
+    <div className={cn("flex flex-col gap-2 mt-12", className)}>
+      <h2 className="text-center text-2xl font-bold mb-8">
+        {code ? `${code} Error` : 'Error'}
+      </h2>
+      <p className="text-center text-lg text-gray-500">{error}</p>
+    </div>
+  )
+}
+
+export default ErrorBanner
+

package/src/components/IpfsImage.tsx

@@ -0,0 +1,21 @@
+import React from 'react'
+import { ipfsToHttp } from '../utils/formatting'
+
+export interface IpfsImageProps extends React.ImgHTMLAttributes<HTMLImageElement> {
+  /** The image source - can be an ipfs:// URI or regular URL */
+  src: string
+}
+
+/**
+ * An image component that automatically converts IPFS URIs to gateway URLs.
+ * 
+ * @example
+ * <IpfsImage src="ipfs://QmHash123" alt="IPFS image" />
+ */
+export const IpfsImage = ({ src, ...props }: IpfsImageProps) => {
+  const finalSrc = ipfsToHttp(src) || src
+  return <img src={finalSrc} {...props} />
+}
+
+export default IpfsImage
+

package/src/components/LoadingDots.tsx

@@ -0,0 +1,55 @@
+export interface LoadingDotsProps {
+  /** Duration of opacity transition in ms */
+  transitionDuration?: number
+  /** Whether the dots are visible */
+  isVisible?: boolean
+  /** Additional CSS classes */
+  className?: string
+}
+
+/**
+ * Animated loading dots indicator.
+ * Shows three dots with a wave animation.
+ * 
+ * @example
+ * <LoadingDots isVisible={isLoading} />
+ */
+export function LoadingDots({
+  transitionDuration = 300,
+  isVisible = true,
+  className = '',
+}: LoadingDotsProps) {
+  return (
+    <div
+      className={`flex gap-1 justify-center items-center ${className}`}
+      style={{
+        opacity: isVisible ? 1 : 0,
+        transition: `opacity ${transitionDuration}ms ease-in-out`,
+      }}
+    >
+      {[0, 1, 2].map((i) => (
+        <span
+          key={i}
+          className="w-2 h-2 bg-gray-600 rounded-full"
+          style={{
+            animation: 'hivemind-loading-dots-wave 1.2s infinite ease-in-out',
+            animationDelay: `${i * 0.2}s`,
+          }}
+        />
+      ))}
+      <style>{`
+        @keyframes hivemind-loading-dots-wave {
+          0%, 100% {
+            transform: translateY(0);
+          }
+          50% {
+            transform: translateY(-6px);
+          }
+        }
+      `}</style>
+    </div>
+  )
+}
+
+export default LoadingDots
+

package/src/components/TripleAreaChart.tsx

@@ -0,0 +1,108 @@
+import {
+  Area,
+  AreaChart,
+  CartesianGrid,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from 'recharts'
+
+export interface TripleAreaChartDataPoint {
+  /** The x-axis value (typically position value) */
+  xValue: number
+  /** Vault (FOR) position value */
+  vault?: number
+  /** Counter vault (AGAINST) position value */
+  counterVault?: number
+}
+
+export interface TripleAreaChartProps {
+  /** Pre-formatted chart data points */
+  chartData: TripleAreaChartDataPoint[]
+  /** Display variant - 'min' hides axes/grid, 'max' shows full chart */
+  variant?: 'min' | 'max'
+  /** Color for vault (FOR) area */
+  vaultColor?: string
+  /** Color for counter vault (AGAINST) area */
+  counterVaultColor?: string
+}
+
+/**
+ * An area chart for visualizing triple position distributions.
+ * Shows vault (FOR) positions on positive side and counter vault (AGAINST) on negative.
+ * 
+ * @example
+ * <TripleAreaChart 
+ *   chartData={formattedPositions} 
+ *   variant="min" 
+ * />
+ */
+export const TripleAreaChart = ({
+  chartData,
+  variant = 'min',
+  vaultColor = 'green',
+  counterVaultColor = 'red',
+}: TripleAreaChartProps) => {
+  // Clone data to avoid mutating props
+  const data = [...chartData]
+  
+  const maxValue = Math.max(...data.map((d) => d.xValue))
+  const minValue = Math.min(...data.map((d) => d.xValue))
+  
+  // Add padding points for better visualization
+  if (maxValue > 0) {
+    data.push({
+      xValue: maxValue * 1.2,
+      vault: maxValue,
+    })
+  }
+  if (minValue < 0) {
+    data.push({
+      xValue: minValue * 1.2,
+      counterVault: minValue * -1,
+    })
+  }
+  
+  data.sort((a, b) => a.xValue - b.xValue)
+  const maxAbsValue = Math.max(...data.map((d) => Math.abs(d.xValue)))
+  const domain = [maxAbsValue * -1, maxAbsValue]
+
+  return (
+    <ResponsiveContainer width="100%" height="100%">
+      <AreaChart data={data} layout="vertical">
+        {variant !== 'min' && (
+          <>
+            <CartesianGrid strokeDasharray="3 3" />
+            <Tooltip />
+          </>
+        )}
+        <XAxis type="number" hide={variant === 'min'} />
+        <YAxis
+          dataKey="xValue"
+          type="number"
+          reversed
+          domain={domain}
+          hide={variant === 'min'}
+        />
+        <Area
+          type="stepBefore"
+          dataKey="vault"
+          stroke={vaultColor}
+          fill={vaultColor}
+          fillOpacity={0.5}
+        />
+        <Area
+          type="stepAfter"
+          dataKey="counterVault"
+          stroke={counterVaultColor}
+          fill={counterVaultColor}
+          fillOpacity={0.5}
+        />
+      </AreaChart>
+    </ResponsiveContainer>
+  )
+}
+
+export default TripleAreaChart
+