@hivemindhq/core 0.4.0 → 0.5.0

package/src/utils/formatting.ts

@@ -0,0 +1,624 @@
+/**
+ * Formatting utilities for display purposes
+ */
+
+// ============================================================================
+// Crypto Amount Formatting
+// ============================================================================
+
+/**
+ * Options for formatting crypto amounts.
+ */
+export interface FormatCryptoAmountOptions {
+  /** Maximum significant digits before truncation (default: 10) */
+  maxSignificantDigits?: number
+  /** Use compact notation for large numbers (default: false) */
+  compact?: boolean
+  /** Locale for number formatting (default: 'en-US') */
+  locale?: string
+  /** Minimum decimal places to show (default: 0) */
+  minDecimals?: number
+  /** Maximum decimal places to show (default: 6) */
+  maxDecimals?: number
+}
+
+/**
+ * Result of formatting a crypto amount.
+ */
+export interface FormattedCryptoAmount {
+  /** The display string (may be truncated) */
+  display: string
+  /** The full value string (for tooltips) */
+  fullValue: string
+  /** Whether the display was truncated */
+  isTruncated: boolean
+  /** The numeric value (for calculations) */
+  numericValue: number
+}
+
+/**
+ * Formats a raw crypto amount (in wei/smallest unit) for display.
+ * 
+ * Handles:
+ * - Conversion from smallest unit to readable format
+ * - Truncation of excessive precision with tooltip support
+ * - Compact notation for large amounts (1.5M, 2.3B)
+ * - Locale-aware number formatting
+ * 
+ * @param value - Raw amount as string or bigint (e.g., "1500000000000000000" for 1.5 tokens)
+ * @param decimals - Token decimals (default: 18)
+ * @param options - Formatting options
+ * @returns Formatted amount with display string and metadata
+ * 
+ * @example
+ * formatCryptoAmount("1500000000000000000", 18)
+ * // Returns: { display: "1.5", fullValue: "1.5", isTruncated: false, numericValue: 1.5 }
+ * 
+ * formatCryptoAmount("12345678901234567890123", 18, { maxSignificantDigits: 6 })
+ * // Returns: { display: "12345.6...", fullValue: "12345.678901234567890123", isTruncated: true, ... }
+ */
+export function formatCryptoAmount(
+  value: string | bigint,
+  decimals: number = 18,
+  options: FormatCryptoAmountOptions = {}
+): FormattedCryptoAmount {
+  const {
+    maxSignificantDigits = 10,
+    compact = false,
+    locale = 'en-US',
+    minDecimals = 0,
+    maxDecimals = 6,
+  } = options
+  
+  // Convert to bigint if string
+  const bigIntValue = typeof value === 'string' ? BigInt(value) : value
+  
+  // Handle zero case
+  if (bigIntValue === 0n) {
+    return {
+      display: '0',
+      fullValue: '0',
+      isTruncated: false,
+      numericValue: 0,
+    }
+  }
+  
+  // Convert from smallest unit to readable format
+  const divisor = 10n ** BigInt(decimals)
+  const wholePart = bigIntValue / divisor
+  const fractionalPart = bigIntValue % divisor
+  
+  // Build the full decimal string
+  const fractionalStr = fractionalPart.toString().padStart(decimals, '0')
+  const trimmedFractional = fractionalStr.replace(/0+$/, '') // Remove trailing zeros
+  
+  const fullValue = trimmedFractional 
+    ? `${wholePart}.${trimmedFractional}`
+    : wholePart.toString()
+  
+  const numericValue = Number(fullValue)
+  
+  // Handle compact notation
+  if (compact && Math.abs(numericValue) >= 1000) {
+    const compactDisplay = formatCompact(numericValue)
+    return {
+      display: compactDisplay,
+      fullValue,
+      isTruncated: true, // Compact is always "truncated" conceptually
+      numericValue,
+    }
+  }
+  
+  // Step 1: Check if decimals will be truncated (for tooltip purposes)
+  const originalDecimalCount = trimmedFractional.length
+  const decimalsWillBeTruncated = originalDecimalCount > maxDecimals
+  
+  // Step 2: Apply maxDecimals limit FIRST (this is the primary display constraint)
+  let decimalLimitedValue: string
+  try {
+    decimalLimitedValue = new Intl.NumberFormat(locale, {
+      minimumFractionDigits: minDecimals,
+      maximumFractionDigits: maxDecimals,
+      useGrouping: false, // Disable commas for significant digit counting
+    }).format(numericValue)
+  } catch {
+    decimalLimitedValue = fullValue
+  }
+  
+  // Step 3: Check if significant digits truncation is STILL needed after decimal limiting
+  const { truncated, isTruncated: sigDigitsTruncated } = truncateSignificantDigits(
+    decimalLimitedValue, 
+    maxSignificantDigits
+  )
+  
+  // isTruncated is true if EITHER decimals were limited OR significant digits were truncated
+  const isTruncated = decimalsWillBeTruncated || sigDigitsTruncated
+  
+  // Step 4: Format for display
+  let display: string
+  if (sigDigitsTruncated) {
+    // Extract numeric part (without ellipsis) and apply locale formatting for grouping separators
+    const numericPart = truncated.replace('…', '')
+    try {
+      const formattedPart = new Intl.NumberFormat(locale, {
+        maximumFractionDigits: maxDecimals,
+      }).format(parseFloat(numericPart))
+      display = `${formattedPart}…`
+    } catch {
+      display = truncated
+    }
+  } else {
+    // Re-apply locale formatting with grouping (commas) for final display
+    try {
+      display = new Intl.NumberFormat(locale, {
+        minimumFractionDigits: minDecimals,
+        maximumFractionDigits: maxDecimals,
+      }).format(numericValue)
+    } catch {
+      display = decimalLimitedValue
+    }
+  }
+  
+  return {
+    display,
+    fullValue,
+    isTruncated,
+    numericValue,
+  }
+}
+
+/**
+ * Truncates a numeric string to a maximum number of significant digits.
+ * Leading zeros in decimals don't count toward the limit.
+ * 
+ * @param value - The numeric string to truncate
+ * @param maxDigits - Maximum significant digits to keep
+ * @returns Object with truncated string and whether truncation occurred
+ * 
+ * @example
+ * truncateSignificantDigits("123456789012", 10)
+ * // Returns: { truncated: "1234567890…", isTruncated: true }
+ * 
+ * truncateSignificantDigits("0.0000123456789", 10)
+ * // Returns: { truncated: "0.0000123456789", isTruncated: false }
+ * // (leading zeros don't count, only 9 significant digits)
+ */
+export function truncateSignificantDigits(
+  value: string,
+  maxDigits: number
+): { truncated: string; isTruncated: boolean } {
+  if (!value) {
+    return { truncated: '0', isTruncated: false }
+  }
+  
+  // Handle negative numbers
+  const isNegative = value.startsWith('-')
+  const absValue = isNegative ? value.slice(1) : value
+  
+  // Split into whole and fractional parts
+  const [wholePart, fractionalPart] = absValue.split('.')
+  
+  // Count significant digits (skip leading zeros in fractional part)
+  let significantCount = 0
+  let truncatedWhole = ''
+  let truncatedFractional = ''
+  let isTruncated = false
+  
+  // Process whole part (all digits are significant unless the whole thing is "0")
+  if (wholePart !== '0') {
+    for (const char of wholePart) {
+      if (significantCount >= maxDigits) {
+        isTruncated = true
+        break
+      }
+      truncatedWhole += char
+      significantCount++
+    }
+    
+    // If we truncated in whole part, we're done (no fractional)
+    if (isTruncated) {
+      const result = isNegative ? `-${truncatedWhole}` : truncatedWhole
+      return { truncated: `${result}…`, isTruncated: true }
+    }
+  } else {
+    truncatedWhole = '0'
+  }
+  
+  // Process fractional part if exists
+  if (fractionalPart) {
+    let foundNonZero = wholePart !== '0' // If whole is non-zero, all fractional digits count
+    
+    for (const char of fractionalPart) {
+      if (!foundNonZero && char === '0') {
+        // Leading zeros in fractional don't count
+        truncatedFractional += char
+        continue
+      }
+      
+      foundNonZero = true
+      
+      if (significantCount >= maxDigits) {
+        isTruncated = true
+        break
+      }
+      
+      truncatedFractional += char
+      significantCount++
+    }
+  }
+  
+  // Build final result
+  let result = truncatedWhole
+  if (truncatedFractional) {
+    result += `.${truncatedFractional}`
+  }
+  
+  if (isNegative) {
+    result = `-${result}`
+  }
+  
+  return { truncated: result, isTruncated }
+}
+
+/**
+ * Truncates an address or ID for display.
+ * Shows first N characters after optional prefix.
+ *
+ * @param value - The full address or ID string
+ * @param chars - Number of characters to show (default: 5)
+ * @param prefix - Prefix to skip (default: '0x')
+ * @returns Truncated string
+ *
+ * @example
+ * truncateId('0x123456789098765432') // Returns: '12345'
+ * truncateId('0x123456789098765432', 8) // Returns: '12345678'
+ */
+export function truncateId(
+  value: string,
+  chars: number = 5,
+  prefix: string = '0x'
+): string {
+  if (!value) return ''
+  const start = value.startsWith(prefix) ? prefix.length : 0
+  return value.slice(start, start + chars)
+}
+
+/**
+ * Converts an IPFS URI to an HTTP gateway URL.
+ *
+ * @param uri - The IPFS URI (ipfs://... format)
+ * @param gateway - The gateway to use (default: ipfs.io)
+ * @returns HTTP URL for the content
+ *
+ * @example
+ * ipfsToHttp('ipfs://QmHash123') // Returns: 'https://ipfs.io/ipfs/QmHash123'
+ */
+export function ipfsToHttp(
+  uri: string | undefined | null,
+  gateway: string = 'https://ipfs.io/ipfs/'
+): string | undefined {
+  if (!uri) return undefined
+  if (uri.startsWith('ipfs://')) {
+    return uri.replace('ipfs://', gateway)
+  }
+  return uri
+}
+
+/**
+ * Formats a number with compact notation (K, M, B, etc.)
+ *
+ * @param value - The number to format
+ * @param decimals - Maximum decimal places (default: 2)
+ * @returns Formatted string
+ *
+ * @example
+ * formatCompact(1500) // Returns: '1.5K'
+ * formatCompact(2500000) // Returns: '2.5M'
+ */
+export function formatCompact(
+  value: number,
+  decimals: number = 2
+): string {
+  if (value === 0) return '0'
+  
+  const formatter = new Intl.NumberFormat('en-US', {
+    notation: 'compact',
+    maximumFractionDigits: decimals,
+  })
+  
+  return formatter.format(value)
+}
+
+/**
+ * Strengthens/normalizes an image URL to ensure it's displayable.
+ * Handles IPFS URIs, raw IPFS hashes, and validates HTTP URLs.
+ *
+ * @param url - The image URL to process
+ * @returns A normalized HTTP(S) URL
+ *
+ * @example
+ * strengthenImageUrl('ipfs://QmHash123') // Returns: 'https://ipfs.io/ipfs/QmHash123'
+ * strengthenImageUrl('QmHash123') // Returns: 'https://ipfs.io/ipfs/QmHash123'
+ * strengthenImageUrl('https://example.com/img.png') // Returns: 'https://example.com/img.png'
+ */
+export function strengthenImageUrl(url: string = ''): string {
+  // Validate input
+  if (!url || typeof url !== 'string' || url.trim() === '') {
+    return url
+  }
+  
+  const trimmedUrl = url.trim()
+  
+  // Handle IPFS protocol
+  if (trimmedUrl.startsWith('ipfs://')) {
+    return trimmedUrl.replace('ipfs://', 'https://ipfs.io/ipfs/')
+  }
+  
+  // Already a valid HTTP(S) URL
+  if (trimmedUrl.startsWith('https://') || trimmedUrl.startsWith('http://')) {
+    return trimmedUrl
+  }
+  
+  // Handle IPFS hashes without protocol (Qm... or baf...)
+  if (trimmedUrl.startsWith('Qm') || trimmedUrl.startsWith('baf')) {
+    return 'https://ipfs.io/ipfs/' + trimmedUrl
+  }
+  
+  return trimmedUrl
+}
+
+// ============================================================================
+// String Manipulation Utilities
+// ============================================================================
+
+/**
+ * Ellipsizes a string by showing characters from start and end with '...' in middle.
+ *
+ * @param str - The string to ellipsize
+ * @param length - Total visible characters (split between start and end)
+ * @returns Ellipsized string or original if shorter than length
+ *
+ * @example
+ * ellipsizeString('0x1234567890abcdef', 8) // Returns: '0x12...cdef'
+ */
+export function ellipsizeString(
+  str: string | undefined | null,
+  length: number
+): string {
+  if (!str) return ''
+  if (str.length < length) return str
+  const first = str.substring(0, length / 2)
+  const second = str.substring(str.length - length / 2, str.length)
+  return [first, second].join('...')
+}
+
+/**
+ * Ellipsizes a hex string (0x-prefixed) preserving the prefix.
+ *
+ * @param hex - The hex string to ellipsize (must start with 0x)
+ * @param length - Visible characters in the payload (default: 12)
+ * @returns Ellipsized hex string
+ * @throws Error if hex doesn't start with 0x
+ *
+ * @example
+ * ellipsizeHex('0x1234567890abcdef1234567890abcdef') // Returns: '0x123456...abcdef'
+ */
+export function ellipsizeHex(hex: string, length: number = 12): string {
+  if (!hex || !hex.startsWith('0x')) throw new Error('Invalid hex')
+  const prefix = '0x'
+  const payload = hex.replace('0x', '')
+  const shortenedPayload = ellipsizeString(payload, length)
+  return `${prefix}${shortenedPayload}`
+}
+
+/**
+ * Truncates a string to a specified length, adding '...' at the end.
+ *
+ * @param str - The string to truncate
+ * @param length - Maximum length before truncation
+ * @returns Truncated string with '...' or original if shorter
+ *
+ * @example
+ * truncateString('Hello World', 5) // Returns: 'Hello...'
+ */
+export function truncateString(
+  str: string | undefined | null = '',
+  length: number
+): string {
+  if (!str) return ''
+  if (str.length < length) return str
+  return `${str.substring(0, length)}...`
+}
+
+/**
+ * Intelligently shortens a label based on its type (hex, URL, IPFS, DID, etc.)
+ * This is the main utility for displaying atom/entity labels in the UI.
+ *
+ * @param label - The label to shorten
+ * @param length - Maximum length for generic strings (default: 50)
+ * @returns Shortened label appropriate for its type
+ *
+ * @example
+ * shortenLabel('0x1234567890abcdef...') // Returns: '0x1234...cdef'
+ * shortenLabel('https://example.com/page') // Returns: 'example.com/page'
+ * shortenLabel('ipfs://bafkre...') // Returns: 'bafkre...xyz'
+ */
+export function shortenLabel(
+  label: string | null | undefined,
+  length: number = 50
+): string {
+  if (!label) return ''
+
+  // Handle hex addresses
+  if (label.startsWith('0x')) {
+    return ellipsizeHex(label, 12)
+  }
+
+  // Handle IPFS
+  if (label.startsWith('bafkre')) {
+    return ellipsizeString(label, 12)
+  }
+  if (label.startsWith('ipfs://bafkre')) {
+    return ellipsizeString(label.replace('ipfs://', ''), 12)
+  }
+
+  // Handle URLs - remove protocol and truncate if needed
+  if (label.startsWith('https://') || label.startsWith('http://')) {
+    const cleanUrl = label.replace(/^https?:\/\//, '')
+    return cleanUrl.length > length ? cleanUrl.slice(0, length) + '...' : cleanUrl
+  }
+
+  // Handle DID URIs
+  if (label.startsWith('did:')) {
+    // Extract meaningful parts of DID
+    if (label.includes('eip155:') && label.includes('|discord:')) {
+      const parts = label.split('|')
+      const ethPart = parts[0] // did:eip155:84532:0x...
+      const discordPart = parts[1] // discord:391378559945670667
+
+      // Extract just the address from the first part
+      const addressMatch = ethPart.match(/0x[a-fA-F0-9]+/)
+      const address = addressMatch ? ellipsizeHex(addressMatch[0], 8) : ethPart
+
+      return `${address} | ${discordPart}`
+    }
+
+    // Fallback for other DID formats
+    return ellipsizeString(label, length)
+  }
+
+  // Handle CAIP-10 identifiers
+  if (label.startsWith('caip10:eip155:')) {
+    const parsedLabel = label.split(':')
+    const addressIndex = parsedLabel.findIndex(part => part.startsWith('0x'))
+    if (addressIndex !== -1) {
+      const address = parsedLabel[addressIndex]
+      parsedLabel[addressIndex] = ellipsizeHex(address, 12)
+    }
+    return parsedLabel.join(':')
+  }
+
+  // Default: truncate to specified length
+  return label.length > length ? label.slice(0, length) + '...' : label
+}
+
+// ============================================================================
+// Capitalization Utilities
+// ============================================================================
+
+/**
+ * Capitalizes the first letter of a string.
+ *
+ * @param str - The string to capitalize
+ * @returns String with first letter capitalized
+ *
+ * @example
+ * capitalizeFirstLetter('hello') // Returns: 'Hello'
+ */
+export function capitalizeFirstLetter(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}
+
+/**
+ * Capitalizes the first letter of each word in a phrase.
+ *
+ * @param phrase - The phrase to capitalize
+ * @returns Phrase with each word capitalized
+ *
+ * @example
+ * capitalize('hello world') // Returns: 'Hello World'
+ */
+export function capitalize(phrase: string): string {
+  if (!phrase) return ''
+  return phrase
+    .split(' ')
+    .map(word => word ? word.charAt(0).toUpperCase() + word.slice(1) : '')
+    .join(' ')
+}
+
+// ============================================================================
+// Time Utilities
+// ============================================================================
+
+/**
+ * Converts seconds to a compact human-readable format (e.g., "5d", "3h", "10m").
+ *
+ * @param seconds - Number of seconds
+ * @returns Compact time string
+ *
+ * @example
+ * secondsToHms(3700) // Returns: '1h'
+ * secondsToHms(90) // Returns: '1m'
+ */
+export function secondsToHms(seconds: number): string {
+  seconds = Number(seconds)
+  const d = Math.floor(seconds / (3600 * 24))
+  if (d > 0) return `${d}d`
+  const h = Math.floor(seconds / 3600)
+  if (h > 0) return `${h}h`
+  const m = Math.floor((seconds % 3600) / 60)
+  if (m > 0) return `${m}m`
+  const s = Math.floor((seconds % 3600) % 60)
+  if (s > 0) return `${s}s`
+  return ''
+}
+
+/**
+ * Formats a date as a human-readable "time ago" string.
+ * Handles various date input formats including Unix timestamps.
+ *
+ * @param date - Date object, ISO string, or Unix timestamp (10 or 13 digits)
+ * @param ago - Whether to append "ago" suffix (default: true)
+ * @returns Human-readable time difference string
+ *
+ * @example
+ * timeAgo(new Date(Date.now() - 3600000)) // Returns: '1h ago'
+ * timeAgo('1703001600', false) // Returns: '5d'
+ */
+export function timeAgo(date: Date | string, ago: boolean = true): string {
+  let output: Date
+  if (typeof date === 'string') {
+    if (date.length === 10) {
+      // Unix timestamp in seconds
+      output = new Date(parseInt(date) * 1000)
+    } else if (date.length === 13) {
+      // Unix timestamp in milliseconds
+      output = new Date(parseInt(date))
+    } else {
+      // ISO string or other format
+      output = new Date(date)
+    }
+  } else {
+    output = date
+  }
+  
+  const dateTimestamp = output.getTime() / 1000
+  const nowTimestamp = Date.now() / 1000
+  const timeGap = secondsToHms(nowTimestamp - dateTimestamp)
+  
+  return ago ? `${timeGap} ago` : timeGap
+}
+
+/**
+ * Converts seconds to a descriptive duration string (e.g., "5 d", "3 h").
+ *
+ * @param inputVar - Seconds as number or string
+ * @returns Duration string with space before unit
+ *
+ * @example
+ * secondsToDhms(90000) // Returns: '1 d'
+ */
+export function secondsToDhms(inputVar: string | number): string {
+  const inputNumber = Number(inputVar)
+  const days = Math.floor(inputNumber / (3600 * 24))
+  const hours = Math.floor((inputNumber % (3600 * 24)) / 3600)
+  const minutes = Math.floor(((inputNumber % (3600 * 24)) % 3600) / 60)
+  const seconds = Math.floor(((inputNumber % (3600 * 24)) % 3600) % 60)
+
+  if (days) return `${days} d`
+  if (hours) return `${hours} h`
+  if (minutes) return `${minutes} m`
+  if (seconds) return `${seconds} s`
+  return ''
+}
+

package/src/utils/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Utility functions shared across Hive Mind applications
+ */
+
+export { cn } from './cn'
+export * from './formatting'
+export * from './atom'
+export * from './atom-label-detection'
+export * from './search'
+export * from './multivault-errors'
+