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

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

@@ -0,0 +1,128 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Slot } from '@radix-ui/react-slot';
+import { Controller, FormProvider, useFormContext } from 'react-hook-form';
+import { Label } from '../label';
+import { cn } from '../../utils';
+import { createContext, forwardRef, useContext, useId, } from 'react';
+const FormFieldContext = createContext(null);
+const FormItemContext = createContext(null);
+/**
+ * Read-only context hook for form field children — returns the field's id, error state, and ARIA attributes.
+ *
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+const useFormField = () => {
+    const fieldContext = useContext(FormFieldContext);
+    const itemContext = useContext(FormItemContext);
+    const { getFieldState, formState } = useFormContext();
+    if (!fieldContext) {
+        throw new Error('useFormField must be used within a <FormField>');
+    }
+    const fieldState = getFieldState(fieldContext.name, formState);
+    const id = itemContext?.id ?? '';
+    return {
+        id,
+        name: fieldContext.name,
+        formItemId: `${id}-form-item`,
+        formDescriptionId: `${id}-form-item-description`,
+        formMessageId: `${id}-form-item-message`,
+        ...fieldState,
+    };
+};
+/**
+ * React Hook Form provider wrapper. Pass the result of `useForm()` as
+ * `form` and render fields via `FormField` / `FormItem` / `FormLabel` /
+ * `FormControl` / `FormMessage`.
+ *
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+const Form = ({ form, children, className, ...props }) => {
+    return (_jsx(FormProvider, { ...form, children: _jsx("form", { className: cn('mdk-form', className), ...props, children: children }) }));
+};
+// ─── FormField ───────────────────────────────────────────────────────────────
+/**
+ * Wraps react-hook-form's Controller and provides field context to descendants.
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+const FormField = ({ ...props }) => {
+    return (_jsx(FormFieldContext.Provider, { value: { name: props.name }, children: _jsx(Controller, { ...props }) }));
+};
+// ─── FormItem ────────────────────────────────────────────────────────────────
+/**
+ * Layout wrapper for a form field. Generates a unique ID for accessibility linking.
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+const FormItem = forwardRef(({ className, ...props }, ref) => {
+    const id = useId();
+    return (_jsx(FormItemContext.Provider, { value: { id }, children: _jsx("div", { ref: ref, className: cn('mdk-form-item', className), ...props }) }));
+});
+FormItem.displayName = 'FormItem';
+// ─── FormLabel ───────────────────────────────────────────────────────────────
+/**
+ * Label that auto-links to the form field input via generated IDs.
+ * Applies error styling when the field has a validation error.
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+const FormLabel = forwardRef(({ className, ...props }, ref) => {
+    const { error, formItemId } = useFormField();
+    return (_jsx(Label, { ref: ref, className: cn('mdk-form-label', error && 'mdk-form-label--error', className), htmlFor: formItemId, ...props }));
+});
+FormLabel.displayName = 'FormLabel';
+// ─── FormControl ─────────────────────────────────────────────────────────────
+/**
+ * Slot-based wrapper that injects ARIA attributes onto its child input element
+ * without adding an extra DOM wrapper.
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+const FormControl = forwardRef(({ ...props }, ref) => {
+    const { error, formItemId, formDescriptionId, formMessageId } = useFormField();
+    return (_jsx(Slot, { ref: ref, id: formItemId, "aria-describedby": !error ? formDescriptionId : `${formDescriptionId} ${formMessageId}`, "aria-invalid": !!error, ...props }));
+});
+FormControl.displayName = 'FormControl';
+// ─── FormDescription ─────────────────────────────────────────────────────────
+/**
+ * Optional helper text displayed below the input.
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+const FormDescription = forwardRef(({ className, ...props }, ref) => {
+    const { formDescriptionId } = useFormField();
+    return (_jsx("p", { ref: ref, id: formDescriptionId, className: cn('mdk-form-description', className), ...props }));
+});
+FormDescription.displayName = 'FormDescription';
+// ─── FormMessage ─────────────────────────────────────────────────────────────
+/**
+ * Displays the validation error message from react-hook-form field state.
+ * Falls back to children if no error is present.
+ * Always renders to prevent layout shift when errors appear.
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+const FormMessage = forwardRef(({ className, children, ...props }, ref) => {
+    const { error, formMessageId } = useFormField();
+    const body = error ? String(error.message) : children;
+    return (_jsx("p", { ref: ref, id: formMessageId, className: cn('mdk-form-message', !body && 'mdk-form-message--empty', className), role: body ? 'alert' : undefined, "aria-live": body ? 'polite' : undefined, ...props, children: body || '\u00A0' }));
+});
+FormMessage.displayName = 'FormMessage';
+// ─── Exports ─────────────────────────────────────────────────────────────────
+export { Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, useFormField, };
+// Re-export pre-built field components
+export { FormCascader, FormCheckbox, FormDatePicker, FormInput, FormRadioGroup, FormSelect, FormSwitch, FormTagInput, FormTextArea, } from './form-fields';
+// Re-export hooks
+export { useFormReset } from './form-hooks';
+// Re-export utilities and validators
+export { contactSchema, createConditionalRequired, createDateRange, createFieldNames, createPasswordMatch, loginSchema, profileSchema, registerSchema, validators, } from './form-utils';

package/dist/primitives/components/gauge-chart/constants.d.ts

@@ -0,0 +1,20 @@
+export declare const GAUGE_VIEWBOX_WIDTH = 200;
+export declare const GAUGE_VIEWBOX_HEIGHT = 108;
+export declare const GAUGE_CENTER_X = 100;
+export declare const GAUGE_CENTER_Y = 100;
+export declare const GAUGE_OUTER_RADIUS = 90;
+export declare const GAUGE_SEGMENT_PADDING_RADIANS = 0.04;
+export declare const GAUGE_SEGMENT_CORNER_RADIUS = 4;
+export declare const GAUGE_NEEDLE_HUB_RADIUS = 8;
+export declare const GAUGE_NEEDLE_TIP_INSET = 20;
+export declare const GAUGE_NEEDLE_SWEEP_DURATION_MS = 900;
+export declare const GAUGE_PERCENT_LABEL_FONT_SIZE = 22;
+export declare const GAUGE_PERCENT_LABEL_VERTICAL_OFFSET = -40;
+export declare const DEFAULT_GAUGE_NEEDLE_COLOR: "#464A4F";
+export declare const DEFAULT_GAUGE_TEXT_COLOR: "#FFFFFF";
+export declare const GAUGE_SEGMENT_FALLBACK_COLOR: "#87888C";
+export declare const GAUGE_DEFAULT_HEIGHT = 200;
+export declare const GAUGE_DEFAULT_MAX_WIDTH = 500;
+export declare const GAUGE_DEFAULT_NR_OF_LEVELS = 3;
+export declare const GAUGE_DEFAULT_ARC_WIDTH = 0.2;
+export declare const GAUGE_DEFAULT_COLORS: ("#72F59E" | "#EF4444" | "#d9f25b")[];

package/dist/primitives/components/gauge-chart/constants.js

@@ -0,0 +1,21 @@
+import { COLOR } from '../../constants';
+export const GAUGE_VIEWBOX_WIDTH = 200; // in pixels
+export const GAUGE_VIEWBOX_HEIGHT = 108; // in pixels
+export const GAUGE_CENTER_X = 100; // in pixels
+export const GAUGE_CENTER_Y = 100; // in pixels
+export const GAUGE_OUTER_RADIUS = 90; // in pixels
+export const GAUGE_SEGMENT_PADDING_RADIANS = 0.04;
+export const GAUGE_SEGMENT_CORNER_RADIUS = 4; // in pixels
+export const GAUGE_NEEDLE_HUB_RADIUS = 8; // in pixels
+export const GAUGE_NEEDLE_TIP_INSET = 20; // in pixels
+export const GAUGE_NEEDLE_SWEEP_DURATION_MS = 900;
+export const GAUGE_PERCENT_LABEL_FONT_SIZE = 22; // in pixels
+export const GAUGE_PERCENT_LABEL_VERTICAL_OFFSET = -40; // in pixels
+export const DEFAULT_GAUGE_NEEDLE_COLOR = COLOR.STEEL_GRAY;
+export const DEFAULT_GAUGE_TEXT_COLOR = COLOR.WHITE;
+export const GAUGE_SEGMENT_FALLBACK_COLOR = COLOR.GREY;
+export const GAUGE_DEFAULT_HEIGHT = 200; // in pixels
+export const GAUGE_DEFAULT_MAX_WIDTH = 500; // in pixels
+export const GAUGE_DEFAULT_NR_OF_LEVELS = 3; // number of arc segments
+export const GAUGE_DEFAULT_ARC_WIDTH = 0.2; // arc thickness as a fraction of the gauge radius (0–1)
+export const GAUGE_DEFAULT_COLORS = [COLOR.GREEN, COLOR.SOFT_GREEN, COLOR.RED];

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

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

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

@@ -0,0 +1,6 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Runnable example for GaugeChart.
+ */
+import { GaugeChart } from '@tetherto/mdk-react-devkit';
+export const GaugeChartExample = () => (_jsxs("div", { className: "mdk-example-row", children: [_jsx(GaugeChart, { percent: 0.72, id: "gauge-hash-rate" }), _jsx(GaugeChart, { percent: 0.45, id: "gauge-efficiency", colors: ['#34C759', '#FF9500', '#FF3B30'], nrOfLevels: 5 }), _jsx(GaugeChart, { percent: 0.95, id: "gauge-uptime", hideText: true, height: 160 }), _jsx(GaugeChart, { percent: 0.68, id: "gauge-progress", arcsLength: [0.68, 0.32], colors: ['#009393', '#00939330'], hideNeedle: true, formatTextValue: (p) => `${Math.round(p * 100)}%` })] }));

package/dist/primitives/components/gauge-chart/gauge-svg.d.ts

@@ -0,0 +1,3 @@
+import type { GaugeSvgProps } from './types';
+export type { GaugeSvgProps } from './types';
+export declare const GaugeSvg: import("react").ForwardRefExoticComponent<GaugeSvgProps & import("react").RefAttributes<SVGSVGElement>>;

package/dist/primitives/components/gauge-chart/gauge-svg.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useEffect, useState } from 'react';
+import { UNITS } from '../../constants';
+import { DEFAULT_GAUGE_NEEDLE_COLOR, DEFAULT_GAUGE_TEXT_COLOR, GAUGE_CENTER_X, GAUGE_CENTER_Y, GAUGE_NEEDLE_HUB_RADIUS, GAUGE_NEEDLE_SWEEP_DURATION_MS, GAUGE_NEEDLE_TIP_INSET, GAUGE_OUTER_RADIUS, GAUGE_PERCENT_LABEL_FONT_SIZE, GAUGE_PERCENT_LABEL_VERTICAL_OFFSET, GAUGE_SEGMENT_CORNER_RADIUS, GAUGE_SEGMENT_FALLBACK_COLOR, GAUGE_SEGMENT_PADDING_RADIANS, GAUGE_VIEWBOX_HEIGHT, GAUGE_VIEWBOX_WIDTH, } from './constants';
+import { buildArcSegmentPath, clampToUnitRange, easeOutCubic, polarToCartesian, resolveSegmentColors, } from './utils';
+export const GaugeSvg = forwardRef(({ id, colors, percent, hideText, arcWidth, nrOfLevels, textColor = DEFAULT_GAUGE_TEXT_COLOR, needleColor = DEFAULT_GAUGE_NEEDLE_COLOR, arcsLength, hideNeedle = false, formatTextValue, }, ref) => {
+    const safePercent = clampToUnitRange(percent);
+    const innerRadius = GAUGE_OUTER_RADIUS * (1 - clampToUnitRange(arcWidth));
+    // Segment proportions: custom `arcsLength` (normalised) when provided,
+    // otherwise `nrOfLevels` even segments.
+    const positiveArcs = arcsLength?.filter((length) => length > 0) ?? [];
+    const arcsTotal = positiveArcs.reduce((sum, length) => sum + length, 0);
+    const proportions = positiveArcs.length > 0 && arcsTotal > 0
+        ? positiveArcs.map((length) => length / arcsTotal)
+        : Array.from({ length: Math.max(1, Math.floor(nrOfLevels)) }, () => 0);
+    const segmentCount = proportions.length;
+    const evenShare = 1 / segmentCount;
+    const normalisedProportions = arcsTotal > 0 && positiveArcs.length > 0 ? proportions : proportions.map(() => evenShare);
+    const segmentColors = resolveSegmentColors(colors, segmentCount);
+    const [needlePercent, setNeedlePercent] = useState(0);
+    useEffect(() => {
+        let frame = 0;
+        const start = performance.now();
+        const tick = (now) => {
+            const timeIndex = Math.min(1, (now - start) / GAUGE_NEEDLE_SWEEP_DURATION_MS);
+            setNeedlePercent(safePercent * easeOutCubic(timeIndex));
+            if (timeIndex < 1)
+                frame = requestAnimationFrame(tick);
+        };
+        frame = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(frame);
+    }, [safePercent]);
+    const halfSegmentPaddingRadians = GAUGE_SEGMENT_PADDING_RADIANS / 2;
+    let cumulativeFraction = 0;
+    const segments = normalisedProportions.map((proportion, index) => {
+        const startFraction = cumulativeFraction;
+        cumulativeFraction += proportion;
+        const startAngleRadians = Math.PI * (1 - startFraction);
+        const endAngleRadians = Math.PI * (1 - cumulativeFraction);
+        return {
+            d: buildArcSegmentPath(innerRadius, GAUGE_OUTER_RADIUS, startAngleRadians - halfSegmentPaddingRadians, endAngleRadians + halfSegmentPaddingRadians, GAUGE_SEGMENT_CORNER_RADIUS),
+            color: segmentColors[index] ?? GAUGE_SEGMENT_FALLBACK_COLOR,
+            key: `${id}-seg-${index}`,
+        };
+    });
+    const needleAngleRadians = Math.PI * (1 - needlePercent);
+    const needleLength = innerRadius - GAUGE_NEEDLE_TIP_INSET;
+    const needleTip = polarToCartesian(needleLength, needleAngleRadians);
+    const needleBaseLeft = polarToCartesian(GAUGE_NEEDLE_HUB_RADIUS, needleAngleRadians - Math.PI / 2);
+    const needleBaseRight = polarToCartesian(GAUGE_NEEDLE_HUB_RADIUS, needleAngleRadians + Math.PI / 2);
+    const titleId = `${id}-title`;
+    const percentLabel = `${Math.round(safePercent * 100)}${UNITS.PERCENT}`;
+    return (_jsxs("svg", { ref: ref, role: "img", "aria-labelledby": titleId, preserveAspectRatio: "xMidYMid meet", viewBox: `0 0 ${GAUGE_VIEWBOX_WIDTH} ${GAUGE_VIEWBOX_HEIGHT}`, children: [_jsx("title", { id: titleId, children: `Gauge: ${percentLabel}` }), _jsx("g", { children: segments.map((segment) => (_jsx("path", { d: segment.d, fill: segment.color }, segment.key))) }), !hideNeedle && (_jsxs("g", { "aria-hidden": "true", children: [_jsx("polygon", { points: [
+                            `${needleTip.x.toFixed(3)},${needleTip.y.toFixed(3)}`,
+                            `${needleBaseLeft.x.toFixed(3)},${needleBaseLeft.y.toFixed(3)}`,
+                            `${needleBaseRight.x.toFixed(3)},${needleBaseRight.y.toFixed(3)}`,
+                        ].join(' '), fill: needleColor }), _jsx("circle", { cx: GAUGE_CENTER_X, cy: GAUGE_CENTER_Y, r: GAUGE_NEEDLE_HUB_RADIUS, fill: needleColor })] })), !hideText && (_jsx("text", { x: GAUGE_CENTER_X, y: GAUGE_CENTER_Y + GAUGE_PERCENT_LABEL_VERTICAL_OFFSET, fill: textColor, fontSize: GAUGE_PERCENT_LABEL_FONT_SIZE, fontFamily: "inherit", textAnchor: "middle", dominantBaseline: "middle", children: formatTextValue ? formatTextValue(safePercent) : percentLabel }))] }));
+});
+GaugeSvg.displayName = 'GaugeSvg';

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

@@ -0,0 +1,75 @@
+export type GaugeChartProps = {
+    /** Value between 0 and 1 (e.g. 0.75 = 75%). Values outside the range are clamped. */
+    percent: number;
+    /**
+     * Arc colours in HEX format.
+     * @default [COLOR.GREEN, COLOR.RED]
+     */
+    colors?: string[];
+    /**
+     * Arc thickness as a fraction of the gauge radius (0–1).
+     * @default 0.2
+     */
+    arcWidth?: number;
+    /**
+     * Number of arc segments. Ignored when `arcsLength` is provided.
+     * @default 3
+     */
+    nrOfLevels?: number;
+    /**
+     * Custom arc-segment proportions (auto-normalised), overriding `nrOfLevels`.
+     * e.g. `[0.7, 0.3]` for a progress-style gauge whose first arc is the fill.
+     */
+    arcsLength?: number[];
+    /**
+     * Needle + hub colour.
+     * @default COLOR.STEEL_GRAY
+     */
+    needleColor?: string;
+    /**
+     * Hide the needle + hub (e.g. for a progress-style gauge).
+     * @default false
+     */
+    hideNeedle?: boolean;
+    /** Format the center label from the clamped fraction (0–1). */
+    formatTextValue?: (percent: number) => string;
+    /**
+     * Hide the percentage text rendered inside the gauge.
+     * @default false
+     */
+    hideText?: boolean;
+    /**
+     * Stable id used for the gauge's accessibility labels.
+     * @default 'mdk-gauge-chart'
+     */
+    id?: string;
+    /**
+     * Chart height in pixels or any CSS length (e.g. `'200px'` or `'50%'`).
+     * @default 200
+     */
+    height?: number | string;
+    /** Maximum width in pixels. */
+    maxWidth?: number;
+    /** Additional class for the root `div` */
+    className?: string;
+};
+/**
+ * GaugeChart - Presentational gauge / speedometer chart.
+ *
+ * Implementation note: the gauge is drawn by a pure-SVG internal implementation
+ * (see `./gauge-svg.tsx`), so the component is bundler- and runtime-agnostic and
+ * carries no third-party runtime dependency. The gauge packages on NPM are
+ * published CommonJS-only with a `module` field pointing at the same CJS file,
+ * which crashes under ESM bundlers that add no `__esModule ? .default : module`
+ * interop shim (Webpack 4, raw esbuild, some SSR setups) with React's
+ * "Element type is invalid" error.
+ *
+ * @example
+ * ```tsx
+ * <GaugeChart percent={0.75} colors={['#00FF00', '#FF0000']} />
+ * ```
+ * @category charts
+ * @domain generic
+ * @tier agent-ready
+ */
+export declare const GaugeChart: import("react").ForwardRefExoticComponent<GaugeChartProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from '../../utils';
+import { GaugeSvg } from './gauge-svg';
+import { GAUGE_DEFAULT_ARC_WIDTH, GAUGE_DEFAULT_COLORS, GAUGE_DEFAULT_HEIGHT, GAUGE_DEFAULT_MAX_WIDTH, GAUGE_DEFAULT_NR_OF_LEVELS, } from './constants';
+import { forwardRef } from 'react';
+/**
+ * GaugeChart - Presentational gauge / speedometer chart.
+ *
+ * Implementation note: the gauge is drawn by a pure-SVG internal implementation
+ * (see `./gauge-svg.tsx`), so the component is bundler- and runtime-agnostic and
+ * carries no third-party runtime dependency. The gauge packages on NPM are
+ * published CommonJS-only with a `module` field pointing at the same CJS file,
+ * which crashes under ESM bundlers that add no `__esModule ? .default : module`
+ * interop shim (Webpack 4, raw esbuild, some SSR setups) with React's
+ * "Element type is invalid" error.
+ *
+ * @example
+ * ```tsx
+ * <GaugeChart percent={0.75} colors={['#00FF00', '#FF0000']} />
+ * ```
+ * @category charts
+ * @domain generic
+ * @tier agent-ready
+ */
+export const GaugeChart = forwardRef(({ percent, className, hideText = false, id = 'mdk-gauge-chart', colors = GAUGE_DEFAULT_COLORS, height = GAUGE_DEFAULT_HEIGHT, maxWidth = GAUGE_DEFAULT_MAX_WIDTH, arcWidth = GAUGE_DEFAULT_ARC_WIDTH, nrOfLevels = GAUGE_DEFAULT_NR_OF_LEVELS, arcsLength, needleColor, hideNeedle, formatTextValue, }, ref) => {
+    return (_jsx("div", { ref: ref, className: cn('mdk-gauge-chart', className), style: { height, maxWidth }, children: _jsx(GaugeSvg, { id: id, percent: percent, colors: colors, arcWidth: arcWidth, hideText: hideText, nrOfLevels: nrOfLevels, arcsLength: arcsLength, needleColor: needleColor, hideNeedle: hideNeedle, formatTextValue: formatTextValue }) }));
+});
+GaugeChart.displayName = 'GaugeChart';

package/dist/primitives/components/gauge-chart/types.d.ts

@@ -0,0 +1,25 @@
+export type CartesianPoint = {
+    x: number;
+    y: number;
+};
+export type RgbColor = {
+    r: number;
+    g: number;
+    b: number;
+};
+export type GaugeSvgProps = {
+    id: string;
+    percent: number;
+    colors: string[];
+    arcWidth: number;
+    hideText: boolean;
+    nrOfLevels: number;
+    textColor?: string;
+    needleColor?: string;
+    /** Custom arc-segment proportions (auto-normalised); overrides `nrOfLevels`. */
+    arcsLength?: number[];
+    /** Hide the needle + hub (e.g. for a progress-style gauge). */
+    hideNeedle?: boolean;
+    /** Format the center label from the clamped fraction (0–1). */
+    formatTextValue?: (percent: number) => string;
+};

package/dist/primitives/components/gauge-chart/types.js

@@ -0,0 +1 @@
+export {};

package/dist/primitives/components/gauge-chart/utils.d.ts

@@ -0,0 +1,14 @@
+import type { CartesianPoint } from './types';
+export declare const polarToCartesian: (radius: number, angleRadians: number) => CartesianPoint;
+/**
+ * Build an SVG path for a single ring segment between two angles.
+ * `startAngle` > `endAngle` (we sweep clockwise across the top of the gauge).
+ *
+ * When `cornerRadius > 0` the four corners of the segment are rounded with
+ * tangent arcs of that radius (the radius is automatically clamped so it
+ * never exceeds half the radial thickness or half the angular span).
+ */
+export declare const buildArcSegmentPath: (innerRadius: number, outerRadius: number, startAngleRadians: number, endAngleRadians: number, cornerRadius?: number) => string;
+export declare const clampToUnitRange: (value: number) => number;
+export declare const resolveSegmentColors: (palette: string[], segmentCount: number) => string[];
+export declare const easeOutCubic: (time: number) => number;

package/dist/primitives/components/gauge-chart/utils.js

@@ -0,0 +1,86 @@
+import { GAUGE_CENTER_X, GAUGE_CENTER_Y, GAUGE_SEGMENT_FALLBACK_COLOR } from './constants';
+import { hexToRgb, rgbToHex } from '../../utils/color';
+import _size from 'lodash/size';
+export const polarToCartesian = (radius, angleRadians) => ({
+    x: GAUGE_CENTER_X + radius * Math.cos(angleRadians),
+    y: GAUGE_CENTER_Y - radius * Math.sin(angleRadians),
+});
+/**
+ * Build an SVG path for a single ring segment between two angles.
+ * `startAngle` > `endAngle` (we sweep clockwise across the top of the gauge).
+ *
+ * When `cornerRadius > 0` the four corners of the segment are rounded with
+ * tangent arcs of that radius (the radius is automatically clamped so it
+ * never exceeds half the radial thickness or half the angular span).
+ */
+export const buildArcSegmentPath = (innerRadius, outerRadius, startAngleRadians, endAngleRadians, cornerRadius = 0) => {
+    const angularSpan = startAngleRadians - endAngleRadians;
+    const radialThickness = outerRadius - innerRadius;
+    const safeCornerRadius = Math.max(0, Math.min(cornerRadius, radialThickness / 2, 
+    // The corner uses ~`cornerRadius` of arc length on each side, so cap by
+    // half of the *inner* arc length (the most constrained side).
+    (innerRadius * angularSpan) / 2));
+    const fmt = (value) => value.toFixed(3);
+    if (safeCornerRadius === 0) {
+        const outerStart = polarToCartesian(outerRadius, startAngleRadians);
+        const outerEnd = polarToCartesian(outerRadius, endAngleRadians);
+        const innerStart = polarToCartesian(innerRadius, endAngleRadians);
+        const innerEnd = polarToCartesian(innerRadius, startAngleRadians);
+        return [
+            `M ${fmt(outerStart.x)} ${fmt(outerStart.y)}`,
+            `A ${outerRadius} ${outerRadius} 0 0 1 ${fmt(outerEnd.x)} ${fmt(outerEnd.y)}`,
+            `L ${fmt(innerStart.x)} ${fmt(innerStart.y)}`,
+            `A ${innerRadius} ${innerRadius} 0 0 0 ${fmt(innerEnd.x)} ${fmt(innerEnd.y)}`,
+            'Z',
+        ].join(' ');
+    }
+    const outerAngularInset = safeCornerRadius / outerRadius;
+    const innerAngularInset = safeCornerRadius / innerRadius;
+    const outerArcStart = polarToCartesian(outerRadius, startAngleRadians - outerAngularInset);
+    const outerArcEnd = polarToCartesian(outerRadius, endAngleRadians + outerAngularInset);
+    const topRightOnRadial = polarToCartesian(outerRadius - safeCornerRadius, endAngleRadians);
+    const bottomRightOnRadial = polarToCartesian(innerRadius + safeCornerRadius, endAngleRadians);
+    const innerArcStart = polarToCartesian(innerRadius, endAngleRadians + innerAngularInset);
+    const innerArcEnd = polarToCartesian(innerRadius, startAngleRadians - innerAngularInset);
+    const bottomLeftOnRadial = polarToCartesian(innerRadius + safeCornerRadius, startAngleRadians);
+    const topLeftOnRadial = polarToCartesian(outerRadius - safeCornerRadius, startAngleRadians);
+    return [
+        `M ${fmt(outerArcStart.x)} ${fmt(outerArcStart.y)}`,
+        `A ${outerRadius} ${outerRadius} 0 0 1 ${fmt(outerArcEnd.x)} ${fmt(outerArcEnd.y)}`,
+        `A ${safeCornerRadius} ${safeCornerRadius} 0 0 1 ${fmt(topRightOnRadial.x)} ${fmt(topRightOnRadial.y)}`,
+        `L ${fmt(bottomRightOnRadial.x)} ${fmt(bottomRightOnRadial.y)}`,
+        `A ${safeCornerRadius} ${safeCornerRadius} 0 0 1 ${fmt(innerArcStart.x)} ${fmt(innerArcStart.y)}`,
+        `A ${innerRadius} ${innerRadius} 0 0 0 ${fmt(innerArcEnd.x)} ${fmt(innerArcEnd.y)}`,
+        `A ${safeCornerRadius} ${safeCornerRadius} 0 0 1 ${fmt(bottomLeftOnRadial.x)} ${fmt(bottomLeftOnRadial.y)}`,
+        `L ${fmt(topLeftOnRadial.x)} ${fmt(topLeftOnRadial.y)}`,
+        `A ${safeCornerRadius} ${safeCornerRadius} 0 0 1 ${fmt(outerArcStart.x)} ${fmt(outerArcStart.y)}`,
+        'Z',
+    ].join(' ');
+};
+export const clampToUnitRange = (value) => {
+    if (Number.isNaN(value))
+        return 0;
+    return Math.max(0, Math.min(1, value));
+};
+export const resolveSegmentColors = (palette, segmentCount) => {
+    if (_size(palette) === 0) {
+        return Array.from({ length: segmentCount }, () => GAUGE_SEGMENT_FALLBACK_COLOR);
+    }
+    if (_size(palette) === segmentCount) {
+        return palette;
+    }
+    if (segmentCount === 1) {
+        return [palette[0] ?? GAUGE_SEGMENT_FALLBACK_COLOR];
+    }
+    const startColor = hexToRgb(palette[0] ?? GAUGE_SEGMENT_FALLBACK_COLOR);
+    const endColor = hexToRgb(palette[_size(palette) - 1] ?? GAUGE_SEGMENT_FALLBACK_COLOR);
+    return Array.from({ length: segmentCount }, (_, index) => {
+        const interpolation = index / (segmentCount - 1);
+        return rgbToHex({
+            r: Math.round(startColor.r + (endColor.r - startColor.r) * interpolation),
+            g: Math.round(startColor.g + (endColor.g - startColor.g) * interpolation),
+            b: Math.round(startColor.b + (endColor.b - startColor.b) * interpolation),
+        });
+    });
+};
+export const easeOutCubic = (time) => 1 - (1 - time) ** 3;

package/dist/primitives/components/heatmap/heatmap-legend.d.ts

@@ -0,0 +1,5 @@
+import type { HeatmapLegendProps } from "./types";
+export declare function HeatmapLegend({ min, max, unit, label, colors, className, }: HeatmapLegendProps): import("react").JSX.Element;
+export declare namespace HeatmapLegend {
+    var displayName: string;
+}

package/dist/primitives/components/heatmap/heatmap-legend.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn, HEATMAP_GRADIENT } from "../../utils";
+const formatBound = (bound, unit) => unit ? `${bound} ${unit}` : String(bound);
+/**
+ * HeatmapLegend — a gradient bar with low/high scale labels, matching the
+ * gradient used by {@link Heatmap}.
+ *
+ * @example
+ * ```tsx
+ * <HeatmapLegend label="Temperature" min={20} max={85} unit="°C" />
+ * ```
+ * @category charts
+ * @domain generic
+ * @tier agent-ready
+ */
+export const HeatmapLegend = ({ min, max, unit, label, colors = HEATMAP_GRADIENT, className, }) => {
+    const gradient = `linear-gradient(to right, ${colors.join(", ")})`;
+    return (_jsxs("div", { className: cn("mdk-heatmap-legend", className), children: [label !== undefined && _jsx("div", { className: "mdk-heatmap-legend__label", children: label }), _jsx("div", { className: "mdk-heatmap-legend__bar", style: { background: gradient } }), _jsxs("div", { className: "mdk-heatmap-legend__scale", children: [_jsx("span", { children: formatBound(min, unit) }), _jsx("span", { children: formatBound(max, unit) })] })] }));
+};
+HeatmapLegend.displayName = "HeatmapLegend";

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

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

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

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Runnable example for Heatmap + HeatmapLegend.
+ */
+import { Heatmap, HeatmapLegend } from "@tetherto/mdk-react-devkit";
+const rows = [
+    [{ value: 20 }, { value: 35 }, { value: 50 }, { value: 42 }],
+    [{ value: 60 }, { value: 72 }, { value: null }, { value: 55 }],
+    [{ value: 44 }, { value: 81 }, { value: 66 }, { value: 30 }],
+];
+export const HeatmapExample = () => (_jsxs("div", { className: "mdk-example-row", children: [_jsx(Heatmap, { data: rows, showValues: true }), _jsx(HeatmapLegend, { label: "Temperature", min: 20, max: 81, unit: "\u00B0C" })] }));

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

@@ -0,0 +1,28 @@
+import type { HeatmapProps } from "./types";
+import "./styles.scss";
+/**
+ * Heatmap — a generic grid of value-coloured cells on a low→high gradient.
+ *
+ * Presentational and domain-agnostic: pass a row-major matrix of cells and an
+ * optional `[min, max]` range (auto-derived otherwise). Use `renderCell` to
+ * overlay domain content (socket borders, selection, tooltips) without forking
+ * the primitive — the grid still owns each cell's background colour. Pair with
+ * {@link HeatmapLegend} for a gradient scale.
+ *
+ * @example
+ * ```tsx
+ * <Heatmap
+ *   data={[
+ *     [{ value: 20 }, { value: 45 }],
+ *     [{ value: 70 }, { value: null }],
+ *   ]}
+ *   showValues
+ * />
+ * ```
+ * @category charts
+ * @domain generic
+ * @tier agent-ready
+ */
+export declare const Heatmap: import("react").ForwardRefExoticComponent<HeatmapProps & import("react").RefAttributes<HTMLDivElement>>;
+export { HeatmapLegend } from "./heatmap-legend";
+export type { HeatmapCell, HeatmapCellContext, HeatmapLegendProps, HeatmapProps, } from "./types";

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

@@ -0,0 +1,50 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { cn, getHeatmapColor, HEATMAP_FALLBACK_COLOR, HEATMAP_GRADIENT } from "../../utils";
+// oxlint-disable-next-line no-unused-vars -- in scope for the {@link HeatmapLegend} below
+import { HeatmapLegend } from "./heatmap-legend";
+import { getHeatmapRange } from "./utils";
+const cellText = (cell) => {
+    if (cell.label !== undefined)
+        return cell.label;
+    return cell.value === null ? "" : String(cell.value);
+};
+/**
+ * Heatmap — a generic grid of value-coloured cells on a low→high gradient.
+ *
+ * Presentational and domain-agnostic: pass a row-major matrix of cells and an
+ * optional `[min, max]` range (auto-derived otherwise). Use `renderCell` to
+ * overlay domain content (socket borders, selection, tooltips) without forking
+ * the primitive — the grid still owns each cell's background colour. Pair with
+ * {@link HeatmapLegend} for a gradient scale.
+ *
+ * @example
+ * ```tsx
+ * <Heatmap
+ *   data={[
+ *     [{ value: 20 }, { value: 45 }],
+ *     [{ value: 70 }, { value: null }],
+ *   ]}
+ *   showValues
+ * />
+ * ```
+ * @category charts
+ * @domain generic
+ * @tier agent-ready
+ */
+export const Heatmap = forwardRef(({ data, min, max, colors = HEATMAP_GRADIENT, emptyColor = HEATMAP_FALLBACK_COLOR, showValues = false, renderCell, ariaLabel = "Heatmap", className, }, ref) => {
+    const range = getHeatmapRange(data);
+    const lowerBound = min ?? range.min;
+    const upperBound = max ?? range.max;
+    const columnCount = data.reduce((widest, row) => Math.max(widest, row.length), 0);
+    return (_jsx("div", { ref: ref, className: cn("mdk-heatmap", className), role: "img", "aria-label": ariaLabel, style: { gridTemplateColumns: `repeat(${columnCount}, minmax(0, 1fr))` }, children: data.map((row, rowIndex) => row.map((cell, colIndex) => {
+            const color = cell.value === null
+                ? emptyColor
+                : getHeatmapColor(cell.value, lowerBound, upperBound, colors);
+            return (_jsx("div", { className: "mdk-heatmap__cell", style: { backgroundColor: color }, children: renderCell
+                    ? renderCell(cell, { color, row: rowIndex, col: colIndex })
+                    : showValues && _jsx("span", { className: "mdk-heatmap__value", children: cellText(cell) }) }, cell.key ?? `${rowIndex}-${colIndex}`));
+        })) }));
+});
+Heatmap.displayName = "Heatmap";
+export { HeatmapLegend } from "./heatmap-legend";