@tetherto/mdk-react-devkit 0.0.0-stage → 0.12.1

package/dist/primitives/utils/chart-tooltip.d.ts

@@ -0,0 +1,37 @@
+import type { ChartType, TooltipItem, TooltipOptions } from 'chart.js';
+export type ChartTooltipConfig = {
+    /** Color for label text. Use 'dataset' to match dataset border color. Defaults to COLOR.WHITE_ALPHA_05 */
+    labelColor?: string | 'dataset';
+    /** Color for value text. Use 'dataset' to match dataset border color. Defaults to 'dataset' */
+    valueColor?: string | 'dataset';
+    /** Format function for the displayed value. Receives raw value and the tooltip item context. */
+    valueFormatter?: (value: number, item: TooltipItem<any>) => string;
+    /** Background color of the tooltip (default: COLOR.DARK_BLACK / #10100F) */
+    backgroundColor?: string;
+    /** Font size in pixels (default: 12) */
+    fontSize?: number;
+    /** Minimum width in pixels (default: 200) */
+    minWidth?: number;
+    /** Show the chart title row in the tooltip (default: false) */
+    showTitle?: boolean;
+    /** Tooltip interaction mode (default: 'index'). Use 'nearest' for doughnut/pie charts. */
+    mode?: 'index' | 'nearest' | 'point' | 'dataset';
+    /** Whether tooltip requires direct intersection (default: false) */
+    intersect?: boolean;
+};
+/**
+ * Creates a Chart.js external tooltip handler matching the MDK design.
+ *
+ * The tooltip follows the real mouse cursor (not data points) via a mousemove
+ * listener on the chart container. Content is updated by Chart.js's external
+ * tooltip callback; positioning is driven entirely by the mouse.
+ *
+ * @example
+ * ```tsx
+ * <LineChart
+ *   data={data}
+ *   tooltip={{ valueFormatter: (v) => `${v.toFixed(2)} PH/s` }}
+ * />
+ * ```
+ */
+export declare const buildChartTooltip: (config?: ChartTooltipConfig) => Partial<TooltipOptions<ChartType>>;

package/dist/primitives/utils/chart-tooltip.js

@@ -0,0 +1,208 @@
+import { COLOR } from '../constants/colors';
+const TOOLTIP_ATTR = 'data-msdk-chart-tooltip';
+const TRACKING_ATTR = 'data-msdk-mouse';
+const CURSOR_X_ATTR = 'data-msdk-tooltip-cursor-x';
+const CURSOR_Y_ATTR = 'data-msdk-tooltip-cursor-y';
+const GAP = 10;
+const OFFSET = 5;
+const storeCursor = (container, cursorX, cursorY) => {
+    container.setAttribute(CURSOR_X_ATTR, String(cursorX));
+    container.setAttribute(CURSOR_Y_ATTR, String(cursorY));
+};
+const readStoredCursor = (container) => {
+    const xAttr = container.getAttribute(CURSOR_X_ATTR);
+    const yAttr = container.getAttribute(CURSOR_Y_ATTR);
+    if (xAttr == null || yAttr == null)
+        return null;
+    const x = Number(xAttr);
+    const y = Number(yAttr);
+    if (!Number.isFinite(x) || !Number.isFinite(y))
+        return null;
+    return { x, y };
+};
+const clearStoredCursor = (container) => {
+    container.removeAttribute(CURSOR_X_ATTR);
+    container.removeAttribute(CURSOR_Y_ATTR);
+};
+const positionTooltip = (container, cursorX, cursorY) => {
+    const tooltipEl = container.querySelector(`[${TOOLTIP_ATTR}]`);
+    if (!tooltipEl || tooltipEl.style.opacity === '0')
+        return;
+    tooltipEl.style.visibility = 'hidden';
+    const tooltipWidth = tooltipEl.offsetWidth;
+    const tooltipHeight = tooltipEl.offsetHeight;
+    const containerWidth = container.offsetWidth;
+    const containerHeight = container.offsetHeight;
+    const fitsRight = cursorX + GAP + tooltipWidth <= containerWidth - OFFSET;
+    let left = fitsRight ? cursorX + GAP : cursorX - tooltipWidth - GAP;
+    if (left < OFFSET)
+        left = OFFSET;
+    if (left + tooltipWidth > containerWidth - OFFSET)
+        left = containerWidth - tooltipWidth - OFFSET;
+    let top = cursorY;
+    if (top + tooltipHeight > containerHeight - OFFSET)
+        top = containerHeight - tooltipHeight - OFFSET;
+    if (top < OFFSET)
+        top = OFFSET;
+    tooltipEl.style.left = `${left}px`;
+    tooltipEl.style.top = `${top}px`;
+    if (tooltipEl.style.opacity !== '0')
+        tooltipEl.style.visibility = 'visible';
+};
+// Listeners are intentionally not cleaned up — they're bound to the container element,
+// which React owns. When the container is removed from the DOM, the element and its
+// listeners are garbage-collected together. The data-attribute guard prevents double-binding.
+const ensureMouseTracking = (container) => {
+    if (container.getAttribute(TRACKING_ATTR))
+        return;
+    container.setAttribute(TRACKING_ATTR, '1');
+    container.addEventListener('mousemove', (e) => {
+        const rect = container.getBoundingClientRect();
+        const cursorX = e.clientX - rect.left;
+        const cursorY = e.clientY - rect.top;
+        storeCursor(container, cursorX, cursorY);
+        const tooltipEl = container.querySelector(`[${TOOLTIP_ATTR}]`);
+        if (!tooltipEl || tooltipEl.childElementCount === 0)
+            return;
+        if (tooltipEl.style.opacity === '0')
+            tooltipEl.style.opacity = '1';
+        positionTooltip(container, cursorX, cursorY);
+    }, { capture: true });
+    container.addEventListener('mouseleave', () => {
+        clearStoredCursor(container);
+        const tooltipEl = container.querySelector(`[${TOOLTIP_ATTR}]`);
+        if (tooltipEl) {
+            tooltipEl.style.opacity = '0';
+            tooltipEl.style.visibility = 'hidden';
+        }
+    });
+};
+const getOrCreateTooltipEl = (chart) => {
+    const canvas = chart.canvas;
+    const container = canvas.parentElement;
+    if (!container)
+        throw new Error('Chart canvas must have a parent element');
+    let tooltipEl = container.querySelector(`[${TOOLTIP_ATTR}]`);
+    if (!tooltipEl) {
+        tooltipEl = document.createElement('div');
+        tooltipEl.setAttribute(TOOLTIP_ATTR, '');
+        tooltipEl.style.position = 'absolute';
+        tooltipEl.style.pointerEvents = 'none';
+        tooltipEl.style.transition = 'none';
+        container.style.position = 'relative';
+        container.appendChild(tooltipEl);
+    }
+    ensureMouseTracking(container);
+    return tooltipEl;
+};
+const resolveDatasetColor = (item) => {
+    const ds = item.dataset;
+    const bg = ds.backgroundColor;
+    const border = ds.borderColor;
+    if (Array.isArray(bg))
+        return String(bg[item.dataIndex] ?? bg[0] ?? '#888');
+    if (Array.isArray(border))
+        return String(border[item.dataIndex] ?? border[0] ?? '#888');
+    const raw = border ?? bg ?? '#888';
+    if (typeof raw === 'string')
+        return raw;
+    return '#888';
+};
+/**
+ * Creates a Chart.js external tooltip handler matching the MDK design.
+ *
+ * The tooltip follows the real mouse cursor (not data points) via a mousemove
+ * listener on the chart container. Content is updated by Chart.js's external
+ * tooltip callback; positioning is driven entirely by the mouse.
+ *
+ * @example
+ * ```tsx
+ * <LineChart
+ *   data={data}
+ *   tooltip={{ valueFormatter: (v) => `${v.toFixed(2)} PH/s` }}
+ * />
+ * ```
+ */
+export const buildChartTooltip = (config = {}) => {
+    const { labelColor = COLOR.WHITE_ALPHA_05, valueColor = 'dataset', valueFormatter, backgroundColor = COLOR.DARK_BLACK, fontSize = 12, minWidth = 200, showTitle = false, mode = 'index', intersect = false, } = config;
+    const externalHandler = (context) => {
+        const { chart, tooltip } = context;
+        const tooltipEl = getOrCreateTooltipEl(chart);
+        if (tooltip.opacity === 0) {
+            tooltipEl.style.opacity = '0';
+            return;
+        }
+        const wrapper = document.createElement('div');
+        wrapper.style.display = 'flex';
+        wrapper.style.flexDirection = 'column';
+        wrapper.style.gap = '8px';
+        if (showTitle && tooltip.title?.length) {
+            const titleEl = document.createElement('div');
+            titleEl.style.fontSize = `${fontSize - 2}px`;
+            titleEl.style.color = COLOR.WHITE_ALPHA_05;
+            titleEl.style.opacity = '0.7';
+            titleEl.textContent = tooltip.title.join(' ');
+            wrapper.appendChild(titleEl);
+        }
+        const bodyItems = tooltip.dataPoints ?? [];
+        for (const item of bodyItems) {
+            const dsColor = resolveDatasetColor(item);
+            const resolvedLabelColor = labelColor === 'dataset' ? dsColor : labelColor;
+            const resolvedValueColor = valueColor === 'dataset' ? dsColor : valueColor;
+            const label = item.dataset.label || item.label || '';
+            const rawValue = typeof item.parsed === 'object'
+                ? (item.parsed.y ?? item.parsed.x ?? item.parsed ?? 0)
+                : (item.parsed ?? 0);
+            const formattedValue = valueFormatter
+                ? valueFormatter(Number(rawValue), item)
+                : String(rawValue);
+            const row = document.createElement('div');
+            row.style.display = 'flex';
+            row.style.justifyContent = 'space-between';
+            row.style.alignItems = 'baseline';
+            row.style.fontSize = `${fontSize}px`;
+            row.style.lineHeight = `${fontSize + 4}px`;
+            row.style.gap = '16px';
+            const labelSpan = document.createElement('span');
+            labelSpan.style.color = resolvedLabelColor;
+            labelSpan.style.whiteSpace = 'nowrap';
+            labelSpan.textContent = String(label);
+            const valueSpan = document.createElement('span');
+            valueSpan.style.color = resolvedValueColor;
+            valueSpan.style.whiteSpace = 'nowrap';
+            valueSpan.style.fontWeight = '600';
+            valueSpan.textContent = formattedValue;
+            row.appendChild(labelSpan);
+            row.appendChild(valueSpan);
+            wrapper.appendChild(row);
+        }
+        tooltipEl.replaceChildren(wrapper);
+        const container = chart.canvas.parentElement;
+        if (!container)
+            return;
+        Object.assign(tooltipEl.style, {
+            background: backgroundColor,
+            color: COLOR.WHITE_ALPHA_05,
+            clipPath: 'polygon(12px 0, 100% 0, 100% 100%, 0 100%, 0 12px)',
+            padding: '14px',
+            fontFamily: `'JetBrains Mono', monospace`,
+            fontSize: `${fontSize}px`,
+            minWidth: `${minWidth}px`,
+            zIndex: '10',
+        });
+        const cursor = readStoredCursor(container);
+        if (!cursor) {
+            tooltipEl.style.opacity = '0';
+            tooltipEl.style.visibility = 'hidden';
+            return;
+        }
+        tooltipEl.style.opacity = '1';
+        positionTooltip(container, cursor.x, cursor.y);
+    };
+    return {
+        enabled: false,
+        external: externalHandler,
+        mode,
+        intersect,
+    };
+};

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

@@ -0,0 +1,93 @@
+import type { ChartDataset } from '../types';
+/**
+ * Convert a hex color string to an rgba string with the given opacity
+ *
+ * @param hex - Hex color string (e.g. '#FF0000' or '#F00')
+ * @param opacity - Opacity value between 0 and 1 (default: 0.2)
+ * @returns rgba color string
+ *
+ * @example
+ * ```ts
+ * hexToOpacity('#FF0000')       // 'rgba(255, 0, 0, 0.2)'
+ * hexToOpacity('#FF0000', 0.5)  // 'rgba(255, 0, 0, 0.5)'
+ * hexToOpacity('#F00')          // 'rgba(255, 0, 0, 0.2)'
+ * ```
+ */
+export declare const hexToOpacity: (hex: string, opacity?: number) => string;
+type ProcessDataProcessor = ((data: unknown) => unknown) | null | undefined;
+/**
+ * Merge new time-series data into existing dataset, deduplicating by `ts` key.
+ *
+ * @param newData - Object keyed by dataset name, each value is an array of data points with `ts`
+ * @param existingData - Previously accumulated dataset in the same shape
+ * @param processor - Optional transform applied to each newData array before merging
+ * @returns Merged dataset
+ *
+ * @example
+ * ```ts
+ * const merged = processDataset(
+ *   { default: [{ ts: 1, value: 10 }] },
+ *   { default: [{ ts: 0, value: 5 }] },
+ * )
+ * // { default: [{ ts: 0, value: 5 }, { ts: 1, value: 10 }] }
+ * ```
+ */
+export declare const processDataset: (newData: Record<string, unknown[]>, existingData: Record<string, unknown[]>, processor?: ProcessDataProcessor) => Record<string, unknown[]>;
+/**
+ * Check if chart datasets have any data available
+ *
+ * @param datasets - Array of Chart.js datasets
+ * @returns true if any dataset has data, false otherwise
+ *
+ * @example
+ * ```tsx
+ * const datasets = [
+ *   { label: 'Series 1', data: [1, 2, 3] },
+ *   { label: 'Series 2', data: [] }
+ * ]
+ *
+ * const hasData = getChartDataAvailability(datasets) // true
+ * ```
+ */
+export declare const getChartDataAvailability: (datasets: ChartDataset[]) => boolean;
+/**
+ * Recursively checks if a dataset contains any non-null, non-undefined values
+ *
+ * Ignores common chart metadata and styling properties to focus on actual data.
+ *
+ * @param dataset - The dataset to check (can be array, object, or primitive)
+ * @returns True if the dataset contains data values, false otherwise
+ *
+ * @example
+ * ```tsx
+ * // Primitive values
+ * hasDataValues(5) // true
+ * hasDataValues('text') // true
+ * hasDataValues(null) // false
+ * hasDataValues(undefined) // false
+ *
+ * // Arrays
+ * hasDataValues([1, 2, 3]) // true
+ * hasDataValues([null, null]) // false
+ * hasDataValues([]) // false
+ *
+ * // Objects with data
+ * hasDataValues({ data: [1, 2, 3], label: 'Chart' }) // true
+ * hasDataValues({ value: 100 }) // true
+ *
+ * // Objects without data (only metadata)
+ * hasDataValues({ label: 'Chart', backgroundColor: 'red' }) // false
+ * hasDataValues({}) // false
+ *
+ * // Nested structures
+ * hasDataValues({
+ *   series: [{ value: 10 }, { value: 20 }]
+ * }) // true
+ *
+ * hasDataValues({
+ *   datasets: [{ data: [1, 2, 3] }]
+ * }) // true
+ * ```
+ */
+export declare const hasDataValues: (dataset: unknown) => boolean;
+export {};

package/dist/primitives/utils/chart.js

@@ -0,0 +1,195 @@
+import { LABEL_TO_IGNORE } from '../constants/charts';
+import { isNil, isPlainObject } from './validation';
+/**
+ * Convert a hex color string to an rgba string with the given opacity
+ *
+ * @param hex - Hex color string (e.g. '#FF0000' or '#F00')
+ * @param opacity - Opacity value between 0 and 1 (default: 0.2)
+ * @returns rgba color string
+ *
+ * @example
+ * ```ts
+ * hexToOpacity('#FF0000')       // 'rgba(255, 0, 0, 0.2)'
+ * hexToOpacity('#FF0000', 0.5)  // 'rgba(255, 0, 0, 0.5)'
+ * hexToOpacity('#F00')          // 'rgba(255, 0, 0, 0.2)'
+ * ```
+ */
+export const hexToOpacity = (hex, opacity = 0.2) => {
+    if (typeof hex !== 'string') {
+        throw new TypeError(`Expected a string for HEX color, but received ${typeof hex} ${JSON.stringify(hex)}`);
+    }
+    let cleanedHex = hex.replace('#', '');
+    if (cleanedHex.length === 3) {
+        cleanedHex = cleanedHex
+            .split('')
+            .map((char) => char + char)
+            .join('');
+    }
+    const r = Number.parseInt(cleanedHex.slice(0, 2), 16);
+    const g = Number.parseInt(cleanedHex.slice(2, 4), 16);
+    const b = Number.parseInt(cleanedHex.slice(4, 6), 16);
+    return `rgba(${r}, ${g}, ${b}, ${opacity})`;
+};
+/**
+ * Merge new time-series data into existing dataset, deduplicating by `ts` key.
+ *
+ * @param newData - Object keyed by dataset name, each value is an array of data points with `ts`
+ * @param existingData - Previously accumulated dataset in the same shape
+ * @param processor - Optional transform applied to each newData array before merging
+ * @returns Merged dataset
+ *
+ * @example
+ * ```ts
+ * const merged = processDataset(
+ *   { default: [{ ts: 1, value: 10 }] },
+ *   { default: [{ ts: 0, value: 5 }] },
+ * )
+ * // { default: [{ ts: 0, value: 5 }, { ts: 1, value: 10 }] }
+ * ```
+ */
+export const processDataset = (newData, existingData, processor = null) => {
+    const result = {};
+    for (const key of Object.keys(newData)) {
+        const processedData = processor ? processor(newData[key]) : newData[key];
+        const existingByTs = new Map();
+        const existingArr = existingData[key];
+        if (existingArr) {
+            for (const item of existingArr) {
+                existingByTs.set(item.ts, item);
+            }
+        }
+        const newArr = processedData;
+        if (newArr) {
+            for (const item of newArr) {
+                existingByTs.set(item.ts, item);
+            }
+        }
+        result[key] = Array.from(existingByTs.values());
+    }
+    return result;
+};
+/**
+ * Check if chart datasets have any data available
+ *
+ * @param datasets - Array of Chart.js datasets
+ * @returns true if any dataset has data, false otherwise
+ *
+ * @example
+ * ```tsx
+ * const datasets = [
+ *   { label: 'Series 1', data: [1, 2, 3] },
+ *   { label: 'Series 2', data: [] }
+ * ]
+ *
+ * const hasData = getChartDataAvailability(datasets) // true
+ * ```
+ */
+export const getChartDataAvailability = (datasets) => {
+    // Empty or null datasets array
+    if (!datasets || datasets.length === 0) {
+        return false;
+    }
+    // Check if at least one dataset has non-empty data
+    return datasets.some((dataset) => {
+        // Ensure dataset is an object and has data property
+        if (!dataset || typeof dataset !== 'object') {
+            return false;
+        }
+        const data = dataset.data;
+        // Check if data is a non-empty array
+        return Array.isArray(data) && data.length > 0;
+    });
+};
+/**
+ * Recursively checks if a dataset contains any non-null, non-undefined values
+ *
+ * Ignores common chart metadata and styling properties to focus on actual data.
+ *
+ * @param dataset - The dataset to check (can be array, object, or primitive)
+ * @returns True if the dataset contains data values, false otherwise
+ *
+ * @example
+ * ```tsx
+ * // Primitive values
+ * hasDataValues(5) // true
+ * hasDataValues('text') // true
+ * hasDataValues(null) // false
+ * hasDataValues(undefined) // false
+ *
+ * // Arrays
+ * hasDataValues([1, 2, 3]) // true
+ * hasDataValues([null, null]) // false
+ * hasDataValues([]) // false
+ *
+ * // Objects with data
+ * hasDataValues({ data: [1, 2, 3], label: 'Chart' }) // true
+ * hasDataValues({ value: 100 }) // true
+ *
+ * // Objects without data (only metadata)
+ * hasDataValues({ label: 'Chart', backgroundColor: 'red' }) // false
+ * hasDataValues({}) // false
+ *
+ * // Nested structures
+ * hasDataValues({
+ *   series: [{ value: 10 }, { value: 20 }]
+ * }) // true
+ *
+ * hasDataValues({
+ *   datasets: [{ data: [1, 2, 3] }]
+ * }) // true
+ * ```
+ */
+export const hasDataValues = (dataset) => {
+    // Null or undefined - no data
+    if (isNil(dataset)) {
+        return false;
+    }
+    // Handle arrays
+    if (Array.isArray(dataset)) {
+        if (dataset.length === 0) {
+            return false;
+        }
+        // Recursively check if any element has data
+        return dataset.some((item) => hasDataValues(item));
+    }
+    // Handle primitive values (numbers, strings, booleans)
+    if (!isPlainObject(dataset)) {
+        return true; // Any non-nil primitive is valid data
+    }
+    // Handle objects
+    const keys = Object.keys(dataset);
+    // Empty object - no data
+    if (keys.length === 0) {
+        return false;
+    }
+    // Check if any non-ignored property contains data values
+    return keys.some((key) => {
+        // Skip metadata/styling properties
+        if (LABEL_TO_IGNORE.includes(key)) {
+            return false;
+        }
+        const item = dataset[key];
+        // Nil value - no data
+        if (isNil(item)) {
+            return false;
+        }
+        // Primitive value - valid data
+        if (!isPlainObject(item) && !Array.isArray(item)) {
+            return true;
+        }
+        // Object or array - check recursively
+        if (isPlainObject(item)) {
+            // Special case: check for 'value' property first
+            if ('value' in item && !isNil(item.value)) {
+                return true;
+            }
+            // Otherwise check recursively
+            return hasDataValues(item);
+        }
+        // Array - check recursively
+        if (Array.isArray(item)) {
+            return hasDataValues(item);
+        }
+        return false;
+    });
+};

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

@@ -0,0 +1,13 @@
+import type { ClassValue } from 'clsx';
+/**
+ * Utility function to merge class names using clsx
+ *
+ * @param inputs - Class names to merge
+ * @returns Merged class string
+ *
+ * @example
+ * ```ts
+ * cn('base-class', condition && 'conditional-class', { 'object-class': true })
+ * ```
+ */
+export declare const cn: (...inputs: ClassValue[]) => string;

package/dist/primitives/utils/cn.js

@@ -0,0 +1,15 @@
+import { clsx } from 'clsx';
+/**
+ * Utility function to merge class names using clsx
+ *
+ * @param inputs - Class names to merge
+ * @returns Merged class string
+ *
+ * @example
+ * ```ts
+ * cn('base-class', condition && 'conditional-class', { 'object-class': true })
+ * ```
+ */
+export const cn = (...inputs) => {
+    return clsx(inputs);
+};

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

@@ -0,0 +1,46 @@
+/**
+ * Converts a hex color to rgba format with specified opacity
+ * Supports:
+ *  - #RGB
+ *  - #RRGGBB
+ *  - RGB / RRGGBB (without #)
+ */
+export declare const hexToRgba: (hex: string, opacity?: number) => string;
+export type RgbColor = {
+    r: number;
+    g: number;
+    b: number;
+};
+/**
+ * Parse a hex color (`#RGB` / `#RRGGBB`, with or without `#`) into RGB
+ * channels. Returns black for malformed input rather than throwing, so it is
+ * safe to feed user-supplied palette values.
+ */
+export declare const hexToRgb: (hex: string) => RgbColor;
+/** Serialise RGB channels back to a `#RRGGBB` hex string. */
+export declare const rgbToHex: ({ r, g, b }: RgbColor) => string;
+/**
+ * Default cold→hot heatmap gradient (blue → green → yellow → red), ported from
+ * the operator app's `HEATMAP` palette. Ordered low value → high value.
+ *
+ * @tier internal
+ */
+export declare const HEATMAP_GRADIENT: readonly ['#002ea3', '#00a35e', '#e6e939', '#c0392b'];
+/**
+ * Colour returned when a value or the range is not finite.
+ *
+ * @tier internal
+ */
+export declare const HEATMAP_FALLBACK_COLOR = "#000000";
+/**
+ * Map a numeric value to a colour on an evenly-spaced multi-stop gradient,
+ * clamped to `[min, max]`. Generalises the operator app's temperature-colour
+ * helper: values ≤ min take the first stop, values ≥ max the last, and values
+ * in between are linearly interpolated between the two surrounding stops.
+ *
+ * @param value   the sample to colour
+ * @param min     range floor (maps to `stops[0]`)
+ * @param max     range ceiling (maps to the last stop)
+ * @param stops   gradient colours low→high (defaults to {@link HEATMAP_GRADIENT})
+ */
+export declare const getHeatmapColor: (value: number, min: number, max: number, stops?: readonly string[]) => string;