@tetherto/mdk-react-devkit 0.0.0 → 0.12.1

package/dist/primitives/components/average-downtime-chart/utils.js

@@ -0,0 +1,65 @@
+import { buildBarChartData } from '../../utils/chart-options';
+import { formatNumber } from '../../utils/format';
+import { UNITS } from '../../constants/units';
+import { DEFAULT, SERIES, STACK_ID } from './constants';
+const hasRateSeries = (values) => values != null && values.length > 0;
+/**
+ * True when the chart has period labels and at least one rate series to render.
+ * All-zero rates still count as data (0% downtime is a valid outcome).
+ *
+ * @category charts
+ * @domain generic
+ * @tier agent-ready
+ */
+export const hasAverageDowntimeData = (data) => {
+    if (!data?.labels?.length)
+        return false;
+    return hasRateSeries(data.curtailment) || hasRateSeries(data.operationalIssues);
+};
+/**
+ * Maps downtime rates to stacked bar chart datasets (Curtailment + Op. Issues).
+ * Rates are expected as fractions (0–1), matching mining report builders.
+ *
+ * @category charts
+ * @domain generic
+ * @tier agent-ready
+ */
+export const buildAverageDowntimeBarChartData = (data, barWidth = DEFAULT.barWidth) => {
+    const labels = data?.labels ?? [];
+    return buildBarChartData({
+        labels,
+        barWidth,
+        series: [
+            {
+                label: SERIES.curtailment.label,
+                values: data?.curtailment ?? [],
+                color: SERIES.curtailment.color,
+                stack: STACK_ID,
+            },
+            {
+                label: SERIES.operationalIssues.label,
+                values: data?.operationalIssues ?? [],
+                color: SERIES.operationalIssues.color,
+                stack: STACK_ID,
+            },
+        ],
+    });
+};
+/**
+ * Default Y-axis, tooltip, and data-label formatter (fraction 0–1 → display percent).
+ *
+ * @category charts
+ * @domain generic
+ * @tier agent-ready
+ */
+export const defaultAverageDowntimeRateFormatter = (value) => formatNumber(value * 100);
+/**
+ * Tooltip formatter for stacked downtime rate bars (percentage).
+ *
+ * @category charts
+ * @domain generic
+ * @tier agent-ready
+ */
+export const buildAverageDowntimeTooltip = (formatRate = defaultAverageDowntimeRateFormatter) => ({
+    valueFormatter: (value) => `${formatRate(Number(value))}${UNITS.PERCENT}`,
+});

package/dist/primitives/components/badge/badge.example.d.ts

@@ -0,0 +1 @@
+export declare const BadgeExample: () => import("react").JSX.Element;

package/dist/primitives/components/badge/badge.example.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Runnable example for Badge.
+ */
+import { Badge, Button } from '@tetherto/mdk-react-devkit';
+export const BadgeExample = () => (_jsxs("div", { className: "mdk-example-row", children: [_jsx(Badge, { count: 5, children: _jsx(Button, { children: "Messages" }) }), _jsx(Badge, { count: 120, overflowCount: 99, children: _jsx(Button, { children: "Notifications" }) }), _jsx(Badge, { dot: true, children: _jsx(Button, { children: "Updates" }) }), _jsx(Badge, { status: "success", text: "Online" }), _jsx(Badge, { status: "error", text: "Offline" }), _jsx(Badge, { text: "NEW", color: "primary", square: true })] }));

package/dist/primitives/components/badge/index.d.ts

@@ -0,0 +1,135 @@
+import { type ReactNode } from 'react';
+import type { ColorVariant, ComponentSize } from '../../types';
+export type BadgeProps = {
+    /**
+     * Badge content (wraps children with badge)
+     */
+    children?: ReactNode;
+    /**
+     * Number to display in badge
+     * If > overflowCount, will show "overflowCount+"
+     * @default 0
+     */
+    count?: number;
+    /**
+     * Maximum count to display
+     * @default 99
+     */
+    overflowCount?: number;
+    /**
+     * Whether to show badge when count is 0
+     * @default false
+     */
+    showZero?: boolean;
+    /**
+     * Show badge as a dot
+     * @default false
+     */
+    dot?: boolean;
+    /**
+     * Custom badge content (overrides count)
+     */
+    text?: string;
+    /**
+     * Color variant
+     * @default 'primary'
+     */
+    color?: ColorVariant;
+    /**
+     * Badge size
+     * @default 'md'
+     */
+    size?: ComponentSize;
+    /**
+     * Offset position [x, y] in pixels
+     * @default [0, 0]
+     */
+    offset?: [number, number];
+    /**
+     * Square badge (no border-radius)
+     * @default false
+     */
+    square?: boolean;
+    /**
+     * Custom className for badge
+     */
+    className?: string;
+    /**
+     * Custom className for wrapper
+     */
+    wrapperClassName?: string;
+    /**
+     * Badge title for accessibility
+     */
+    title?: string;
+    /**
+     * Status badge (small dot badge with text)
+     */
+    status?: 'success' | 'processing' | 'error' | 'warning' | 'default';
+};
+/**
+ * Badge component - Display badge with number or dot
+ *
+ * @example
+ * // Basic number badge
+ * ```tsx
+ * <Badge count={5}>
+ *   <Button>Messages</Button>
+ * </Badge>
+ * ```
+ *
+ * @example
+ * // Dot badge
+ * ```tsx
+ * <Badge dot>
+ *   <BellIcon />
+ * </Badge>
+ * ```
+ *
+ * @example
+ * // Square badge
+ * ```tsx
+ * <Badge count={5} square>
+ *   <Button>Messages</Button>
+ * </Badge>
+ * ```
+ *
+ * @example
+ * // Standalone badge
+ * ```tsx
+ * <Badge count={25} />
+ * <Badge text="NEW" color="primary" square />
+ * ```
+ *
+ * @example
+ * // With overflow
+ * ```tsx
+ * <Badge count={100} overflowCount={99}>
+ *   <Button>Notifications</Button>
+ * </Badge>
+ * // Shows "99+"
+ * ```
+ *
+ * @example
+ * // Status badge
+ * ```tsx
+ * <Badge status="success" text="Online" />
+ * <Badge status="error" text="Offline" />
+ * ```
+ *
+ * @example
+ * // Different colors
+ * ```tsx
+ * <Badge count={5} color="success">
+ *   <Button>Success</Button>
+ * </Badge>
+ * <Badge count={5} color="error">
+ *   <Button>Error</Button>
+ * </Badge>
+ * ```
+ * @category display
+ * @domain generic
+ * @tier agent-ready
+ */
+declare const Badge: import("react").ForwardRefExoticComponent<BadgeProps & import("react").RefAttributes<HTMLSpanElement>>;
+export { Badge };

package/dist/primitives/components/badge/index.js

@@ -0,0 +1,106 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useMemo } from 'react';
+import { cn } from '../../utils';
+/**
+ * Badge component - Display badge with number or dot
+ *
+ * @example
+ * // Basic number badge
+ * ```tsx
+ * <Badge count={5}>
+ *   <Button>Messages</Button>
+ * </Badge>
+ * ```
+ *
+ * @example
+ * // Dot badge
+ * ```tsx
+ * <Badge dot>
+ *   <BellIcon />
+ * </Badge>
+ * ```
+ *
+ * @example
+ * // Square badge
+ * ```tsx
+ * <Badge count={5} square>
+ *   <Button>Messages</Button>
+ * </Badge>
+ * ```
+ *
+ * @example
+ * // Standalone badge
+ * ```tsx
+ * <Badge count={25} />
+ * <Badge text="NEW" color="primary" square />
+ * ```
+ *
+ * @example
+ * // With overflow
+ * ```tsx
+ * <Badge count={100} overflowCount={99}>
+ *   <Button>Notifications</Button>
+ * </Badge>
+ * // Shows "99+"
+ * ```
+ *
+ * @example
+ * // Status badge
+ * ```tsx
+ * <Badge status="success" text="Online" />
+ * <Badge status="error" text="Offline" />
+ * ```
+ *
+ * @example
+ * // Different colors
+ * ```tsx
+ * <Badge count={5} color="success">
+ *   <Button>Success</Button>
+ * </Badge>
+ * <Badge count={5} color="error">
+ *   <Button>Error</Button>
+ * </Badge>
+ * ```
+ * @category display
+ * @domain generic
+ * @tier agent-ready
+ */
+const Badge = forwardRef(({ children, count = 0, overflowCount = 99, showZero = false, dot = false, text, color = 'primary', size = 'md', offset = [0, 0], square = false, className, wrapperClassName, title, status, }, ref) => {
+    const hasChildren = Boolean(children);
+    const hasOffset = offset[0] !== 0 || offset[1] !== 0;
+    const shouldApplyOffset = hasChildren && hasOffset;
+    // Determine if badge should be shown
+    const shouldShow = useMemo(() => {
+        if (dot || status)
+            return true;
+        if (text)
+            return true;
+        if (count === 0)
+            return showZero;
+        return count > 0;
+    }, [dot, status, text, count, showZero]);
+    // Get display content
+    const displayContent = useMemo(() => {
+        if (text)
+            return text;
+        if (dot || status)
+            return null;
+        if (count > overflowCount)
+            return `${overflowCount}+`;
+        return count;
+    }, [text, dot, status, count, overflowCount]);
+    // Badge element
+    const badgeElement = shouldShow && (_jsx("span", { ref: hasChildren ? undefined : ref, className: cn('mdk-badge', `mdk-badge--${size}`, `mdk-badge--${color}`, dot && 'mdk-badge--dot', square && 'mdk-badge--square', status && `mdk-badge--status mdk-badge--status-${status}`, !hasChildren && 'mdk-badge--standalone', className), style: {
+            ...(shouldApplyOffset && {
+                transform: `translate(calc(50% + ${offset[0]}px), calc(-50% + ${offset[1]}px))`,
+            }),
+        }, title: title, children: displayContent }));
+    // If no children, return badge alone
+    if (!hasChildren) {
+        return badgeElement;
+    }
+    // Wrap children with badge
+    return (_jsxs("span", { ref: ref, className: cn('mdk-badge-wrapper', wrapperClassName), "data-has-offset": hasOffset, children: [children, badgeElement] }));
+});
+Badge.displayName = 'Badge';
+export { Badge };

package/dist/primitives/components/bar-chart/bar-canvas.d.ts

@@ -0,0 +1,11 @@
+import 'chartjs-adapter-date-fns';
+import type { ComponentProps } from 'react';
+import { Bar } from 'react-chartjs-2';
+export type BarCanvasProps = Pick<ComponentProps<typeof Bar>, 'data' | 'options'> & {
+    showDataLabels?: boolean;
+};
+export declare function BarCanvas({ showDataLabels, ...rest }: BarCanvasProps): React.JSX.Element;
+export declare namespace BarCanvas {
+    var displayName: string;
+}
+export default BarCanvas;

package/dist/primitives/components/bar-chart/bar-canvas.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { BarElement, CategoryScale, Chart as ChartJS, Legend, LinearScale, LineElement, PointElement, Title, Tooltip, } from 'chart.js';
+import 'chartjs-adapter-date-fns';
+import ChartDataLabels from 'chartjs-plugin-datalabels';
+import { Bar } from 'react-chartjs-2';
+import { legendMarginPlugin } from '../../utils/chart-options';
+// Engine-bound leaf for BarChart. Isolated in its own module so the chart.js +
+// react-chartjs-2 runtime (and the datalabels plugin) is code-split into a lazy
+// chunk and only loaded when a bar chart actually renders (see `index.tsx`).
+ChartJS.register(CategoryScale, LinearScale, BarElement, LineElement, PointElement, Title, Tooltip, Legend);
+export const BarCanvas = ({ showDataLabels, ...rest }) => {
+    const plugins = showDataLabels ? [legendMarginPlugin, ChartDataLabels] : [legendMarginPlugin];
+    return _jsx(Bar, { ...rest, plugins: plugins });
+};
+BarCanvas.displayName = 'BarCanvas';
+export default BarCanvas;

package/dist/primitives/components/bar-chart/bar-chart.example.d.ts

@@ -0,0 +1 @@
+export declare const BarChartExample: () => import("react").JSX.Element;

package/dist/primitives/components/bar-chart/bar-chart.example.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Runnable example for BarChart.
+ */
+import { BarChart } from '@tetherto/mdk-react-devkit';
+const groupedData = {
+    labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
+    datasets: [
+        {
+            label: 'Foundry EU',
+            data: [42, 38, 45, 50, 47, 30, 35],
+            backgroundColor: '#F7931A',
+        },
+        {
+            label: 'AntPool',
+            data: [28, 32, 29, 35, 33, 25, 27],
+            backgroundColor: '#4B9EFF',
+        },
+    ],
+};
+const stackedData = {
+    labels: ['Week 1', 'Week 2', 'Week 3', 'Week 4'],
+    datasets: [
+        { label: 'Accepted', data: [320, 340, 310, 360], backgroundColor: '#34C759' },
+        { label: 'Rejected', data: [12, 8, 15, 10], backgroundColor: '#FF3B30' },
+    ],
+};
+export const BarChartExample = () => (_jsxs("div", { className: "mdk-example-col", children: [_jsx(BarChart, { data: groupedData, height: 220 }), _jsx(BarChart, { data: stackedData, isStacked: true, height: 220, showDataLabels: true })] }));

package/dist/primitives/components/bar-chart/index.d.ts

@@ -0,0 +1,60 @@
+import type { Chart as ChartJS } from 'chart.js';
+import type { FlexAlign, Position } from '../../types';
+import type { ChartTooltipConfig } from '../../utils/chart-tooltip';
+export type BarChartProps = {
+    /** Chart data - required, provided by parent. Use `as any` for mixed bar+line datasets. */
+    data: any;
+    /** Chart.js options - merged with defaults */
+    options?: ChartJS<'bar'>['options'];
+    /**
+     * Stack bars on top of each other
+     * @default false
+     */
+    isStacked?: boolean;
+    /**
+     * Render bars horizontally (indexAxis: 'y')
+     * @default false
+     */
+    isHorizontal?: boolean;
+    /** Format Y-axis tick labels */
+    formatYLabel?: (value: number) => string;
+    /**
+     * Show built-in Chart.js legend
+     * @default true
+     */
+    showLegend?: boolean;
+    /**
+     * Position of the legend
+     * @default 'top'
+     */
+    legendPosition?: Position;
+    /**
+     * Alignment of the legend labels within their position
+     * @default 'start'
+     */
+    legendAlign?: FlexAlign;
+    /**
+     * Show values above each bar
+     * @default false
+     */
+    showDataLabels?: boolean;
+    /** Format data label values (default: round to nearest integer) */
+    formatDataLabel?: (value: number) => string;
+    /** Custom HTML tooltip configuration. When provided, replaces the default Chart.js tooltip. */
+    tooltip?: ChartTooltipConfig;
+    /**
+     * Chart height in pixels
+     * @default 300
+     */
+    height?: number;
+    /** Additional class for the wrapper `div` */
+    className?: string;
+};
+/**
+ * Presentational Chart.js bar chart. Data must be pre-aggregated; use grouped or stacked categories via `datasets`.
+ *
+ * @category charts
+ * @domain generic
+ * @tier agent-ready
+ */
+export declare const BarChart: import("react").ForwardRefExoticComponent<BarChartProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/primitives/components/bar-chart/index.js

@@ -0,0 +1,156 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from '../../utils';
+import { defaultChartColors, defaultChartOptions, makeBarGradient } from '../../utils/chart-options';
+import { buildChartTooltip } from '../../utils/chart-tooltip';
+import { forwardRef, lazy, Suspense, useMemo } from 'react';
+// chart.js + react-chartjs-2 (and the datalabels plugin) are code-split into a
+// lazy chunk so importing this component does not pull the chart engine into a
+// consumer's initial bundle.
+const BarCanvas = lazy(() => import('./bar-canvas'));
+/**
+ * Presentational Chart.js bar chart. Data must be pre-aggregated; use grouped or stacked categories via `datasets`.
+ *
+ * @category charts
+ * @domain generic
+ * @tier agent-ready
+ */
+export const BarChart = forwardRef(({ data, options, isStacked = false, isHorizontal = false, formatYLabel, showLegend = true, legendPosition = 'top', legendAlign = 'start', tooltip: tooltipConfig, showDataLabels = false, formatDataLabel, height = 300, className, }, ref) => {
+    const mergedOptions = useMemo(() => {
+        const base = {
+            ...defaultChartOptions,
+            ...options,
+        };
+        if (tooltipConfig) {
+            base.plugins = {
+                ...base.plugins,
+                tooltip: buildChartTooltip(tooltipConfig),
+            };
+        }
+        if (isHorizontal) {
+            ;
+            base.indexAxis = 'y';
+        }
+        base.plugins = {
+            ...base.plugins,
+            legend: {
+                ...base.plugins?.legend,
+                display: showLegend,
+                position: legendPosition,
+                align: legendAlign,
+            },
+            datalabels: showDataLabels
+                ? {
+                    display: (context) => {
+                        const { chart, dataset, datasetIndex, dataIndex } = context;
+                        if (dataset.type === 'line')
+                            return false;
+                        if (!isStacked)
+                            return true;
+                        const stackKey = dataset.stack || '__default__';
+                        const dsets = chart.data.datasets ?? [];
+                        for (let i = dsets.length - 1; i >= 0; i--) {
+                            const ds = dsets[i];
+                            if (!ds || ds.type === 'line')
+                                continue;
+                            if ((ds.stack || '__default__') !== stackKey)
+                                continue;
+                            if (!chart.isDatasetVisible(i))
+                                continue;
+                            const v = Array.isArray(ds.data) ? ds.data[dataIndex] : null;
+                            if (v == null || v === 0)
+                                continue;
+                            return i === datasetIndex;
+                        }
+                        return true;
+                    },
+                    anchor: 'end',
+                    align: 'end',
+                    offset: 2,
+                    clamp: true,
+                    clip: false,
+                    color: 'rgba(255, 255, 255, 0.85)',
+                    font: { size: 11, weight: 'normal' },
+                    formatter: (v) => {
+                        if (v == null)
+                            return '';
+                        return formatDataLabel ? formatDataLabel(v) : Math.round(v);
+                    },
+                }
+                : { display: false },
+        };
+        if (showDataLabels) {
+            const baseAny = base;
+            const existingLayout = typeof baseAny.layout === 'object' && baseAny.layout ? baseAny.layout : {};
+            baseAny.layout = { ...existingLayout, padding: { top: 20 } };
+        }
+        const scales = { ...base.scales };
+        if (isStacked) {
+            scales.x = { ...scales.x, stacked: true };
+            scales.y = { ...scales.y, stacked: true };
+        }
+        if (formatYLabel) {
+            const valueAxis = isHorizontal ? 'x' : 'y';
+            const existing = scales[valueAxis] ?? {};
+            const existingTicks = typeof existing === 'object' && 'ticks' in existing ? existing.ticks : {};
+            scales[valueAxis] = {
+                ...existing,
+                ticks: {
+                    ...(typeof existingTicks === 'object' ? existingTicks : {}),
+                    callback: (_value, index, values) => formatYLabel(values[index]?.value ?? 0),
+                },
+            };
+        }
+        return { ...base, scales };
+    }, [
+        options,
+        isStacked,
+        isHorizontal,
+        formatYLabel,
+        showLegend,
+        legendPosition,
+        legendAlign,
+        showDataLabels,
+        formatDataLabel,
+        tooltipConfig,
+    ]);
+    const chartData = useMemo(() => {
+        const datasets = data.datasets?.map((ds, i) => {
+            const dsType = ds.type;
+            const isLine = dsType === 'line';
+            const solidColor = String(ds.borderColor ?? ds.backgroundColor ?? defaultChartColors[i % defaultChartColors.length]);
+            if (isLine) {
+                return {
+                    ...ds,
+                    borderColor: ds.borderColor ?? solidColor,
+                    backgroundColor: ds.backgroundColor ?? solidColor,
+                };
+            }
+            const bgIsFunction = typeof ds.backgroundColor === 'function';
+            const bgIsArray = Array.isArray(ds.backgroundColor);
+            let backgroundColor;
+            if (bgIsFunction) {
+                backgroundColor = ds.backgroundColor;
+            }
+            else if (bgIsArray) {
+                backgroundColor = ((context) => makeBarGradient(context, ds.backgroundColor[context.dataIndex] ?? solidColor));
+            }
+            else {
+                backgroundColor = ((context) => makeBarGradient(context, solidColor));
+            }
+            return {
+                ...ds,
+                backgroundColor,
+                borderColor: ds.borderColor ?? solidColor,
+                borderWidth: ds.borderWidth ??
+                    (isHorizontal
+                        ? { top: 0, right: 1.5, bottom: 0, left: 0 }
+                        : { top: 1.5, right: 0, bottom: 0, left: 0 }),
+                borderSkipped: ds.borderSkipped ?? false,
+                borderRadius: ds.borderRadius ?? 0,
+            };
+        });
+        return { ...data, datasets };
+    }, [data, isHorizontal]);
+    return (_jsx("div", { ref: ref, className: cn('mdk-bar-chart', className), style: { height }, children: _jsx(Suspense, { fallback: null, children: _jsx(BarCanvas, { data: chartData, options: mergedOptions, showDataLabels: showDataLabels }) }) }));
+});
+BarChart.displayName = 'BarChart';

package/dist/primitives/components/breadcrumbs/breadcrumbs.example.d.ts

@@ -0,0 +1 @@
+export declare const BreadcrumbsExample: () => import("react").JSX.Element;

package/dist/primitives/components/breadcrumbs/breadcrumbs.example.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Runnable example for Breadcrumbs.
+ */
+import { Breadcrumbs } from '@tetherto/mdk-react-devkit';
+export const BreadcrumbsExample = () => (_jsx(Breadcrumbs, { showBack: true, onBackClick: () => undefined, items: [
+        { label: 'Dashboard', href: '/' },
+        { label: 'Devices', onClick: () => undefined },
+        { label: 'Miner #42' },
+    ] }));

package/dist/primitives/components/breadcrumbs/index.d.ts

@@ -0,0 +1,48 @@
+import { type ReactNode } from 'react';
+export type BreadcrumbItem = {
+    /** Text shown for the crumb */
+    label: string;
+    /** Renders the crumb as a link; takes precedence over `onClick` */
+    href?: string;
+    /** Renders the crumb as a button when `href` is absent; with neither, the crumb is plain text */
+    onClick?: VoidFunction;
+};
+export type BreadcrumbsProps = {
+    /** Ordered trail; the last item is rendered as current */
+    items: BreadcrumbItem[];
+    /**
+     * Show a leading "Back" button
+     * @default false
+     */
+    showBack?: boolean;
+    /**
+     * Label for the back button
+     * @default "Back"
+     */
+    backLabel?: string;
+    /** Root class names */
+    className?: string;
+    /** Class names applied to each item */
+    itemClassName?: string;
+    /** Class names applied to the back button */
+    backClassName?: string;
+    /** Callback fired when the back button is clicked */
+    onBackClick?: VoidFunction;
+    /**
+     * Custom separator between items
+     * @default "/"
+     */
+    separator?: ReactNode;
+};
+/**
+ * Hierarchical navigation trail that renders the path of pages leading to the
+ * current view. Each item can be a link (`href` or `onClick`) or plain text;
+ * the last item is rendered as the current page. Pass `showBack` to prepend a
+ * "back" affordance for mobile/touch layouts. The separator between items is
+ * customisable via `separator` (defaults to `/`).
+ *
+ * @category navigation
+ * @domain generic
+ * @tier agent-ready
+ */
+export declare const Breadcrumbs: import("react").ForwardRefExoticComponent<BreadcrumbsProps & import("react").RefAttributes<HTMLElement>>;