@tetherto/mdk-react-devkit 0.0.0 → 0.12.1

package/dist/primitives/utils/format.js

@@ -0,0 +1,272 @@
+/**
+ * Formatting utilities
+ *
+ * Pure functions for formatting numbers, currencies, dates, hashrates,
+ * and other display values. All functions return a fallback string
+ * when the input is invalid.
+ */
+import { format as dateFnsFormat } from 'date-fns/format';
+const LOCALE = 'en-US';
+/**
+ * Default fallback string for invalid/missing values
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export const FALLBACK = '-';
+// ============================================================================
+// Number Formatting
+// ============================================================================
+/**
+ * Format number with locale formatting and configurable options
+ *
+ * Handles string-encoded numbers, null, and undefined gracefully.
+ *
+ * @example
+ * ```ts
+ * formatNumber(1234.567)                        // "1,234.57"
+ * formatNumber(null)                             // "-"
+ * formatNumber(1234, { minimumFractionDigits: 2 }) // "1,234.00"
+ * ```
+ */
+export const formatNumber = (number, options = {}, fallback = FALLBACK) => {
+    // Default options
+    const opts = {
+        minimumFractionDigits: 0,
+        maximumFractionDigits: 2,
+        maximumSignificantDigits: undefined,
+        ...options,
+    };
+    // If significant digits are set, don't override fraction digits
+    if (options?.maximumSignificantDigits !== undefined) {
+        delete opts.minimumFractionDigits;
+        delete opts.maximumFractionDigits;
+    }
+    const parsed = Number.parseFloat(number);
+    const result = Number.isFinite(parsed)
+        ? new Intl.NumberFormat(LOCALE, opts).format(number)
+        : fallback;
+    return result === '-0' ? '0' : result;
+};
+/**
+ * Format hashrate with rounding to 2 decimal places
+ */
+export const formatHashrate = (number, options, fallback = FALLBACK) => {
+    const parsed = Number.parseFloat(number);
+    return Number.isFinite(parsed)
+        ? formatNumber(Math.round(parsed * 100) / 100, options, fallback)
+        : fallback;
+};
+/**
+ * Format number as a percentage string
+ *
+ * @example
+ * ```ts
+ * getPercentFormattedNumber(0.75)  // "75%"
+ * ```
+ */
+export const getPercentFormattedNumber = (number, decimals = 2, fallback = FALLBACK) => formatNumber(number, {
+    minimumFractionDigits: 0,
+    maximumFractionDigits: decimals,
+    maximumSignificantDigits: undefined,
+    style: 'percent',
+}, fallback);
+// ============================================================================
+// Value + Unit Formatting
+// ============================================================================
+/**
+ * Format a value and unit into a display string
+ *
+ * Fiat currency symbols ($, €, £, ¥) are placed before the number.
+ * Other units are placed after with a space.
+ *
+ * @example
+ * ```ts
+ * formatValueUnit(1234, '$')    // "$1,234"
+ * formatValueUnit(1234, 'BTC')  // "1,234 BTC"
+ * ```
+ */
+export const formatValueUnit = (value, unit, options, fallback = FALLBACK, formatter = formatNumber) => {
+    const formattedValue = formatter(value, options, fallback);
+    if (formattedValue === fallback)
+        return fallback;
+    if (!unit)
+        return formattedValue;
+    // Fiat currency symbols go before the number with no space
+    const fiatSymbols = ['$', '€', '£', '¥'];
+    if (fiatSymbols.includes(unit)) {
+        return `${unit}${formattedValue}`;
+    }
+    // Crypto and other units go after with a space
+    return `${formattedValue} ${unit}`;
+};
+/**
+ * Format a ValueUnit object into a display string
+ */
+export const formatUnit = (object = {}, options, fallback = FALLBACK, formatter = formatNumber) => {
+    const { value, unit } = object;
+    return formatValueUnit(value, unit, options, fallback, formatter);
+};
+/**
+ * Format a hashrate ValueUnit object into a display string
+ */
+export const formatHashrateUnit = (object = {}, options, fallback = FALLBACK) => {
+    const { value, unit } = object;
+    return formatValueUnit(value, unit, options, fallback, formatHashrate);
+};
+// ============================================================================
+// Error Formatting
+// ============================================================================
+/**
+ * Format errors with timestamps into a human-readable string
+ *
+ * @param errors - Array of error objects, a plain string, or null
+ * @param getFormattedDate - Optional custom date formatter
+ */
+export const formatErrors = (errors, getFormattedDate) => {
+    if (!errors)
+        return '';
+    if (typeof errors === 'string')
+        return errors;
+    return errors
+        .map((error) => {
+        const { msg, message, timestamp } = error;
+        const text = msg || message;
+        if (!timestamp)
+            return `${text}. \n`;
+        const ts = typeof timestamp === 'string' ? Number.parseInt(timestamp, 10) : timestamp;
+        const dateString = getFormattedDate && ts ? getFormattedDate(new Date(ts)) : new Date(ts).toLocaleString();
+        return `${text}\n${dateString}`;
+    })
+        .join('\n\n');
+};
+// ============================================================================
+// Misc Formatting
+// ============================================================================
+/**
+ * Format MAC address to uppercase
+ */
+export const formatMacAddress = (macAddress) => macAddress ? macAddress.toUpperCase() : '';
+/**
+ * Convert a string to Title Case
+ *
+ * Handles camelCase, snake_case, kebab-case, and space-separated words.
+ *
+ * @example
+ * ```ts
+ * toTitleCase('hello_world')   // "Hello World"
+ * toTitleCase('helloWorld')    // "Hello World"
+ * ```
+ */
+export const toTitleCase = (name) => name
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join(' ');
+/**
+ * Format a chart date from a timestamp
+ *
+ * @param tsRaw - Timestamp (number or string)
+ * @param withYear - Whether to include the year (default: true)
+ * @param customFormatTemplate - Custom date-fns format template
+ * @param fallback - Fallback string for invalid values
+ *
+ * @example
+ * ```ts
+ * formatChartDate(1700000000000)                // "2023-11-14"
+ * formatChartDate(1700000000000, false)          // "11-14"
+ * formatChartDate(1700000000000, true, 'dd MMM') // "14 Nov"
+ * ```
+ */
+export const formatChartDate = (tsRaw, withYear = true, customFormatTemplate, fallback = FALLBACK) => {
+    if (tsRaw == null)
+        return fallback;
+    const ts = Number(tsRaw);
+    if (!Number.isFinite(ts))
+        return fallback;
+    let formatTemplate;
+    if (customFormatTemplate && customFormatTemplate.length > 0) {
+        formatTemplate = customFormatTemplate;
+    }
+    else if (withYear) {
+        formatTemplate = 'yyyy-MM-dd';
+    }
+    else {
+        formatTemplate = 'MM-dd';
+    }
+    return dateFnsFormat(new Date(ts), formatTemplate);
+};
+/**
+ * Format a count, capping display at 99+
+ *
+ * @example
+ * ```ts
+ * formatCountTo99Plus(5)    // "5"
+ * formatCountTo99Plus(150)  // "99+"
+ * formatCountTo99Plus(null) // "N/A"
+ * ```
+ */
+export const formatCountTo99Plus = (value) => {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return 'N/A';
+    return value > 99 ? '99+' : String(value);
+};
+/**
+ * Format table pagination count string
+ *
+ * @example
+ * ```ts
+ * showTotalTableCount(100, [1, 10])  // "1-10 of 100"
+ * ```
+ */
+export const showTotalTableCount = (total, range) => `${range[0]}-${range[1]} of ${total}`;
+/**
+ * Format currency with Intl.NumberFormat
+ *
+ * @example
+ * ```ts
+ * formatCurrency(1234.56)        // "$1,234.56"
+ * formatCurrency(1234.56, 'EUR') // "€1,234.56"
+ * ```
+ */
+export const formatCurrency = (amount, currency = 'USD') => {
+    return new Intl.NumberFormat(LOCALE, {
+        currency,
+        style: 'currency',
+    }).format(amount);
+};
+/**
+ * Format date with Intl.DateTimeFormat
+ *
+ * @example
+ * ```ts
+ * formatDate(new Date())
+ * formatDate('2024-01-15', { month: 'long', year: 'numeric' })
+ * ```
+ */
+export const formatDate = (date, options) => {
+    const dateObj = typeof date === 'string' ? new Date(date) : date;
+    return new Intl.DateTimeFormat(LOCALE, options).format(dateObj);
+};
+/**
+ * Format relative time (e.g., "2h ago", "just now")
+ */
+export const formatRelativeTime = (date) => {
+    const dateObj = typeof date === 'string' ? new Date(date) : date;
+    const now = new Date();
+    const diffInSeconds = Math.floor((now.getTime() - dateObj.getTime()) / 1000);
+    if (diffInSeconds < 60)
+        return 'just now';
+    if (diffInSeconds < 3600)
+        return `${Math.floor(diffInSeconds / 60)}m ago`;
+    if (diffInSeconds < 86400)
+        return `${Math.floor(diffInSeconds / 3600)}h ago`;
+    return `${Math.floor(diffInSeconds / 86400)}d ago`;
+};
+/**
+ * Convert number or string to CSS size
+ */
+export const toCssSize = (value) => typeof value === 'number' ? `${value}px` : value;
+export const convertKwToW = (valueInKw) => valueInKw && !Number.isNaN(Number(valueInKw)) ? Number(valueInKw) * 1000 : Number.NaN;

package/dist/primitives/utils/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Core utility functions
+ *
+ * Pure, side-effect-free utilities.
+ * Organized by domain: number, conversion, date, time, format,
+ * array, string, async, validation, and class names.
+ */
+export * from './array';
+export * from './async';
+export * from './chart';
+export * from './chart-options';
+export * from './chart-tooltip';
+export * from './cn';
+export * from './color';
+export * from './conversion';
+export * from './date';
+export * from './format';
+export * from './number';
+export * from './string';
+export * from './time';
+export * from './types';
+export * from './validation';

package/dist/primitives/utils/index.js

@@ -0,0 +1,37 @@
+/**
+ * Core utility functions
+ *
+ * Pure, side-effect-free utilities.
+ * Organized by domain: number, conversion, date, time, format,
+ * array, string, async, validation, and class names.
+ */
+// Array and collection utilities
+export * from './array';
+// Async utilities
+export * from './async';
+// Chart-specific utilities
+export * from './chart';
+// Chart utilities
+export * from './chart-options';
+// Chart tooltip (external HTML tooltip for Chart.js)
+export * from './chart-tooltip';
+// Class name merging
+export * from './cn';
+// Color utilities
+export * from './color';
+// Unit conversions (energy, power, pressure, transactions)
+export * from './conversion';
+// Date utilities
+export * from './date';
+// Formatting utilities
+export * from './format';
+// Number and math utilities
+export * from './number';
+// String utilities
+export * from './string';
+// Time range and interval utilities
+export * from './time';
+// Types
+export * from './types';
+// Validation utilities
+export * from './validation';

package/dist/primitives/utils/number.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Number and math utilities
+ *
+ * Pure functions for numeric operations: percentage calculations,
+ * unit conversions, and value validation.
+ */
+import type { UnitLabel } from './types';
+/**
+ * Calculate percentage of a value relative to total
+ *
+ * @param partialValue - The part value
+ * @param totalValue - The total value
+ * @param keepOriginalRelation - If true, returns decimal (0-1) instead of percentage (0-100)
+ * @returns The percentage value
+ *
+ * @example
+ * ```ts
+ * percentage(25, 100)        // 25
+ * percentage(25, 100, true)  // 0.25
+ * ```
+ */
+export declare const percentage: (partialValue: number, totalValue: number, keepOriginalRelation?: boolean) => number;
+/**
+ * Formats `value` as a share of `total` on a 0–100 scale (two decimal places, no “%” suffix).
+ * Returns `"0"` when `total` is zero.
+ *
+ * @example
+ * ```ts
+ * formatPercentShare(500, 1500) // "33.33"
+ * formatPercentShare(0, 0)      // "0"
+ * ```
+ */
+export declare const formatPercentShare: (value: number, total: number) => string;
+/**
+ * Unit label constants for SI-prefix conversions
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export declare const UNIT_LABELS: {
+    DECIMAL: 'decimal';
+    KILO: 'k';
+    MEGA: 'M';
+    GIGA: 'G';
+    TERA: 'T';
+    PETA: 'P';
+};
+/**
+ * Multiplier map from unit name to the factor used by `convertValue` for unit-of-measure conversions.
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export declare const UNIT: Record<UnitLabel, number>;
+/**
+ * Convert a value between SI-prefix units
+ *
+ * @example
+ * ```ts
+ * convertUnits(1000, 'decimal', 'k')  // 1
+ * convertUnits(1, 'M', 'k')           // 1000
+ * ```
+ */
+export declare const convertUnits: (value: number, fromUnit?: UnitLabel, toUnit?: UnitLabel) => number;
+/**
+ * Convert decimal number to mega units
+ */
+export declare const decimalToMegaNumber: (value: number) => number;
+/**
+ * Check if a value should be displayed (is finite, non-null, non-zero)
+ */
+export declare const shouldDisplayValue: (value: number | null | undefined) => boolean;
+/**
+ * Calculate percent change between two values
+ *
+ * @returns The rounded percent change, or null if inputs are invalid
+ *
+ * @example
+ * ```ts
+ * getPercentChange(110, 100)  // 10
+ * getPercentChange(90, 100)   // -10
+ * getPercentChange(100, 0)    // null
+ * ```
+ */
+export declare const getPercentChange: (currentValue: number, historicalValue: number) => number | null;
+/**
+ * Safely converts unknown value to number
+ * Returns 0 if value is not a number
+ */
+export declare const safeNumber: (value: unknown) => number;
+/**
+ * Watts per megawatt (1e6). Used by power conversion helpers.
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export declare const W_TO_MW = 1000000;
+/**
+ * Number of satoshis in one bitcoin (1e8). Used by unit conversion helpers.
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export declare const BTC_SATS = 100000000;
+/**
+ * Number of hours in a calendar day (24). Used by duration helpers.
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export declare const HOURS_IN_DAY = 24;
+/**
+ * Hashrate units per petahash/second (1e15). Used by hashrate conversion helpers.
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export declare const HASHRATE_PER_PHS = 1000000000;
+/**
+ * Number of milliseconds in one hour (3.6e6). Used by duration conversion helpers.
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export declare const MS_PER_HOUR: number;
+/**
+ * Number of seconds in a calendar day (86400). Used by duration conversion helpers.
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export declare const SECONDS_PER_DAY: number;

package/dist/primitives/utils/number.js

@@ -0,0 +1,162 @@
+/**
+ * Number and math utilities
+ *
+ * Pure functions for numeric operations: percentage calculations,
+ * unit conversions, and value validation.
+ */
+/**
+ * Calculate percentage of a value relative to total
+ *
+ * @param partialValue - The part value
+ * @param totalValue - The total value
+ * @param keepOriginalRelation - If true, returns decimal (0-1) instead of percentage (0-100)
+ * @returns The percentage value
+ *
+ * @example
+ * ```ts
+ * percentage(25, 100)        // 25
+ * percentage(25, 100, true)  // 0.25
+ * ```
+ */
+export const percentage = (partialValue, totalValue, keepOriginalRelation = false) => {
+    if (!partialValue || !totalValue) {
+        return 0;
+    }
+    const multiplier = keepOriginalRelation ? 1 : 100;
+    return (multiplier * partialValue) / totalValue;
+};
+/**
+ * Formats `value` as a share of `total` on a 0–100 scale (two decimal places, no “%” suffix).
+ * Returns `"0"` when `total` is zero.
+ *
+ * @example
+ * ```ts
+ * formatPercentShare(500, 1500) // "33.33"
+ * formatPercentShare(0, 0)      // "0"
+ * ```
+ */
+export const formatPercentShare = (value, total) => {
+    if (total === 0)
+        return '0';
+    return ((value / total) * 100).toFixed(2);
+};
+/**
+ * Unit label constants for SI-prefix conversions
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export const UNIT_LABELS = {
+    DECIMAL: 'decimal',
+    KILO: 'k',
+    MEGA: 'M',
+    GIGA: 'G',
+    TERA: 'T',
+    PETA: 'P',
+};
+/**
+ * Multiplier map from unit name to the factor used by `convertValue` for unit-of-measure conversions.
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export const UNIT = {
+    [UNIT_LABELS.DECIMAL]: 1,
+    [UNIT_LABELS.KILO]: 1_000,
+    [UNIT_LABELS.MEGA]: 1_000_000,
+    [UNIT_LABELS.GIGA]: 1_000_000_000,
+    [UNIT_LABELS.TERA]: 1_000_000_000_000,
+    [UNIT_LABELS.PETA]: 1_000_000_000_000_000,
+};
+/**
+ * Convert a value between SI-prefix units
+ *
+ * @example
+ * ```ts
+ * convertUnits(1000, 'decimal', 'k')  // 1
+ * convertUnits(1, 'M', 'k')           // 1000
+ * ```
+ */
+export const convertUnits = (value, fromUnit = UNIT_LABELS.DECIMAL, toUnit = UNIT_LABELS.KILO) => (value * UNIT[fromUnit]) / UNIT[toUnit];
+/**
+ * Convert decimal number to mega units
+ */
+export const decimalToMegaNumber = (value) => convertUnits(value, UNIT_LABELS.DECIMAL, UNIT_LABELS.MEGA);
+/**
+ * Check if a value should be displayed (is finite, non-null, non-zero)
+ */
+export const shouldDisplayValue = (value) => value !== null && value !== undefined && !Number.isNaN(value) && value !== 0;
+/**
+ * Calculate percent change between two values
+ *
+ * @returns The rounded percent change, or null if inputs are invalid
+ *
+ * @example
+ * ```ts
+ * getPercentChange(110, 100)  // 10
+ * getPercentChange(90, 100)   // -10
+ * getPercentChange(100, 0)    // null
+ * ```
+ */
+export const getPercentChange = (currentValue, historicalValue) => {
+    if (!Number.isFinite(currentValue) ||
+        !Number.isFinite(historicalValue) ||
+        historicalValue === 0) {
+        return null;
+    }
+    const percentChange = Math.round(((currentValue - historicalValue) / historicalValue) * 100);
+    return percentChange || null;
+};
+/**
+ * Safely converts unknown value to number
+ * Returns 0 if value is not a number
+ */
+export const safeNumber = (value) => {
+    const num = Number(value);
+    return Number.isNaN(num) ? 0 : num;
+};
+// ============================================================================
+// Energy / Power / Mining Constants
+// ============================================================================
+/**
+ * Watts per megawatt (1e6). Used by power conversion helpers.
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export const W_TO_MW = 1e6;
+/**
+ * Number of satoshis in one bitcoin (1e8). Used by unit conversion helpers.
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export const BTC_SATS = 1e8;
+/**
+ * Number of hours in a calendar day (24). Used by duration helpers.
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export const HOURS_IN_DAY = 24;
+/**
+ * Hashrate units per petahash/second (1e15). Used by hashrate conversion helpers.
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export const HASHRATE_PER_PHS = 1e9;
+/**
+ * Number of milliseconds in one hour (3.6e6). Used by duration conversion helpers.
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export const MS_PER_HOUR = 1_000 * 60 * 60;
+/**
+ * Number of seconds in a calendar day (86400). Used by duration conversion helpers.
+ * @category utilities
+ * @domain generic
+ * @tier internal
+ */
+export const SECONDS_PER_DAY = HOURS_IN_DAY * 60 * 60;

package/dist/primitives/utils/string.d.ts

@@ -0,0 +1,61 @@
+/**
+ * String utilities
+ *
+ * Pure functions for string parsing, transformation, and extraction.
+ */
+/**
+ * Parse an auth token string to extract role names
+ *
+ * @example
+ * ```ts
+ * getRolesFromAuthToken('...roles:admin:viewer:...')
+ * // ['admin', 'viewer']
+ * ```
+ */
+export declare const getRolesFromAuthToken: (authToken?: string) => string[];
+/**
+ * Format a dot-separated location string into a readable label
+ *
+ * @example
+ * ```ts
+ * getLocationLabel('site_a.lab_1')  // "Site A Lab 1"
+ * getLocationLabel(null)            // "Unknown"
+ * getLocationLabel('unknown')       // "Unknown"
+ * ```
+ */
+export declare const getLocationLabel: (location: string | null | undefined) => string;
+/**
+ * Get the major (site) part of a "site.location" string
+ *
+ * @example
+ * ```ts
+ * getMajorLocation('site-a.lab_1')  // "site-a"
+ * getMajorLocation('invalid')        // "unknown"
+ * ```
+ */
+export declare const getMajorLocation: (location: string) => string;
+/**
+ * Get the minor (sub-location) part of a "site.location" string
+ *
+ * @example
+ * ```ts
+ * getMinorLocation('site-a.lab_1')  // "lab_1"
+ * getMinorLocation('invalid')        // "unknown"
+ * ```
+ */
+export declare const getMinorLocation: (location: string) => string;
+/**
+ * Normalize a hex color by removing the leading `#`
+ *
+ * @example
+ * ```ts
+ * normalizeHexColor('#ff0000')  // "ff0000"
+ * normalizeHexColor('ff0000')   // "ff0000"
+ * ```
+ */
+export declare const normalizeHexColor: (color: string) => string;
+/**
+ * Safely converts unknown value to string for display
+ * Returns empty string if value is null or undefined
+ */
+export declare const safeString: (value: unknown) => string;