@tetherto/mdk-react-devkit 0.0.0 → 0.12.1

package/dist/primitives/components/sidebar/menu-item.js

@@ -0,0 +1,97 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { ChevronDownIcon, ChevronUpIcon } from '@radix-ui/react-icons';
+import { cn } from '../../utils';
+import { getFirstLeaf, hasActiveDescendant } from './helpers';
+import { OverlayContent } from './overlay-content';
+import { useSidebarSectionState } from './use-sidebar-state';
+const initialOverlayPos = { top: 0, left: 0 };
+export const MenuItemInternal = ({ item, activeId, depth = 0, overlayId, isExpanded, onItemClick, onOverlayChange, inOverlay = false, }) => {
+    const isActive = item.id === activeId;
+    const isOverlayOpen = overlayId === item.id;
+    const hasChildren = Boolean(item.items?.length);
+    const isGroupActive = hasChildren && hasActiveDescendant(item, activeId);
+    const [persistedGroupOpen, setPersistedGroupOpen] = useSidebarSectionState(item.id, isGroupActive);
+    const [groupOpen, setGroupOpenState] = useState(persistedGroupOpen);
+    const [overlayPos, setOverlayPos] = useState(initialOverlayPos);
+    const setGroupOpen = useCallback((value) => {
+        setGroupOpenState((prev) => {
+            const newValue = typeof value === 'function' ? value(prev) : value;
+            setPersistedGroupOpen(newValue);
+            return newValue;
+        });
+    }, [setPersistedGroupOpen]);
+    const hoverOverlay = useRef(false);
+    const hoverContainer = useRef(false);
+    const containerRef = useRef(null);
+    useEffect(() => {
+        if (hasChildren && isGroupActive) {
+            setGroupOpen(true);
+        }
+    }, [hasChildren, isGroupActive]);
+    const handleClick = useCallback(() => {
+        if (item.disabled)
+            return;
+        if (hasChildren && item.items?.length) {
+            setGroupOpen(true);
+            onItemClick?.(getFirstLeaf(item));
+            return;
+        }
+        onItemClick?.(item);
+    }, [item, hasChildren, onItemClick]);
+    const handleGroupToggle = useCallback((e) => {
+        e.stopPropagation();
+        setGroupOpen((prev) => !prev);
+    }, []);
+    const dismissOverlay = useCallback(() => {
+        requestAnimationFrame(() => {
+            if (!hoverContainer.current && !hoverOverlay.current) {
+                onOverlayChange((current) => (current === item.id ? null : current));
+            }
+        });
+    }, [item.id, onOverlayChange]);
+    const handleMouseEnter = useCallback(() => {
+        hoverContainer.current = true;
+        if (isExpanded || !hasChildren || item.disabled)
+            return;
+        if (!inOverlay && containerRef.current) {
+            const rect = containerRef.current.getBoundingClientRect();
+            setOverlayPos({ top: rect.top, left: rect.right });
+        }
+        onOverlayChange(item.id);
+    }, [isExpanded, hasChildren, item.disabled, inOverlay, onOverlayChange, item.id]);
+    const handleMouseLeave = useCallback(() => {
+        hoverContainer.current = false;
+        dismissOverlay();
+    }, [dismissOverlay]);
+    const overlayMouseEnter = useCallback(() => {
+        hoverOverlay.current = true;
+    }, []);
+    const overlayMouseLeave = useCallback(() => {
+        hoverOverlay.current = false;
+        dismissOverlay();
+    }, [dismissOverlay]);
+    const baseItemClass = cn('mdk-sidebar__item', (isActive || isGroupActive) && 'mdk-sidebar__item--active', item.disabled && 'mdk-sidebar__item--disabled', depth > 0 && 'mdk-sidebar__item--sub');
+    const renderLabel = (isExpanded || depth > 0) && (_jsx("span", { className: "mdk-sidebar__item-label", children: item.label }));
+    if (!hasChildren) {
+        return (_jsxs("button", { type: "button", className: baseItemClass, onClick: handleClick, disabled: item.disabled, title: item.label, "aria-label": item.label, children: [item.icon && _jsx("span", { className: "mdk-sidebar__item-icon", children: item.icon }), renderLabel] }));
+    }
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { ref: containerRef, className: "mdk-sidebar__group", onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, children: [_jsxs("button", { type: "button", onClick: handleClick, disabled: item.disabled, className: baseItemClass, title: item.label, "aria-label": item.label, children: [item.icon && _jsx("span", { className: "mdk-sidebar__item-icon", children: item.icon }), renderLabel, isExpanded && !item.disabled && (_jsx("span", { className: "mdk-sidebar__group-toggle", role: "button", tabIndex: 0, onClick: handleGroupToggle, onKeyDown: (e) => {
+                                    if (e.key === 'Enter' || e.key === ' ') {
+                                        e.preventDefault();
+                                        setGroupOpen((prev) => !prev);
+                                    }
+                                }, "aria-label": groupOpen ? `Collapse ${item.label}` : `Expand ${item.label}`, children: groupOpen ? _jsx(ChevronUpIcon, {}) : _jsx(ChevronDownIcon, {}) }))] }), groupOpen && isExpanded && item.items?.length && (_jsx("div", { className: "mdk-sidebar__group-items", children: item.items.map((child) => (_jsx(MenuItemInternal, { item: child, depth: depth + 1, activeId: activeId, overlayId: overlayId, isExpanded: isExpanded, onItemClick: onItemClick, onOverlayChange: onOverlayChange }, child.id))) })), isOverlayOpen && !isExpanded && inOverlay && item.items?.length && (_jsx("div", { className: "mdk-sidebar__overlay mdk-sidebar__overlay--nested", onMouseEnter: overlayMouseEnter, onMouseLeave: overlayMouseLeave, children: _jsx(OverlayContent, { items: item.items, activeId: activeId, onItemClick: (clicked) => {
+                                onOverlayChange(null);
+                                onItemClick?.(clicked);
+                            } }) }))] }), isOverlayOpen &&
+                !isExpanded &&
+                !inOverlay &&
+                item.items?.length &&
+                createPortal(_jsx("div", { className: "mdk-sidebar__overlay", style: overlayPos, onMouseEnter: overlayMouseEnter, onMouseLeave: overlayMouseLeave, children: _jsx(OverlayContent, { items: item.items, activeId: activeId, onItemClick: (clicked) => {
+                            onOverlayChange(null);
+                            onItemClick?.(clicked);
+                        } }) }), document.body)] }));
+};
+MenuItemInternal.displayName = 'Sidebar.MenuItem';

package/dist/primitives/components/sidebar/overlay-content.d.ts

@@ -0,0 +1,5 @@
+import type { OverlayContentProps } from './types';
+export declare function OverlayContent({ items, activeId, onItemClick, }: OverlayContentProps): React.ReactNode;
+export declare namespace OverlayContent {
+    var displayName: string;
+}

package/dist/primitives/components/sidebar/overlay-content.js

@@ -0,0 +1,12 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useState } from 'react';
+import { MenuItemInternal } from './menu-item';
+export const OverlayContent = ({ items, activeId, onItemClick, }) => {
+    const [localOverlayId, setLocalOverlayId] = useState(null);
+    const handleItemClick = useCallback((clicked) => {
+        setLocalOverlayId(null);
+        onItemClick?.(clicked);
+    }, [onItemClick]);
+    return (_jsx(_Fragment, { children: items.map((child) => (_jsx(MenuItemInternal, { depth: 1, inOverlay: true, item: child, isExpanded: false, activeId: activeId, overlayId: localOverlayId, onItemClick: handleItemClick, onOverlayChange: setLocalOverlayId }, child.id))) }));
+};
+OverlayContent.displayName = 'OverlayContent';

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

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

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

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Runnable example for Sidebar.
+ */
+import { useState } from 'react';
+import { Sidebar } from '@tetherto/mdk-react-devkit';
+const items = [
+    { id: '/dashboard', label: 'Dashboard' },
+    { id: '/alerts', label: 'Alerts' },
+    { id: '/devices', label: 'Devices' },
+    { id: '/settings', label: 'Settings' },
+];
+export const SidebarExample = () => {
+    const [active, setActive] = useState('/dashboard');
+    return (_jsx(Sidebar, { items: items, activeId: active, onItemClick: (item) => setActive(item.id), defaultExpanded: true }));
+};

package/dist/primitives/components/sidebar/types.d.ts

@@ -0,0 +1,70 @@
+export type SidebarMenuItemBase = {
+    id: string;
+    label: string;
+};
+export type SidebarMenuItemOptions = Partial<{
+    disabled: boolean;
+    icon: React.ReactNode;
+    items: SidebarMenuItem[];
+}>;
+export type SidebarMenuItem = SidebarMenuItemBase & SidebarMenuItemOptions;
+export type SidebarOptions = Partial<{
+    /** Currently active item id */
+    activeId: string;
+    /** Controlled expanded state */
+    expanded: boolean;
+    /**
+     * Hide entirely without unmounting
+     * @default true
+     */
+    visible: boolean;
+    /**
+     * Show as fixed overlay with backdrop
+     * @default false
+     */
+    overlay: boolean;
+    /** Additional class names */
+    className: string;
+    /**
+     * Initial expanded state
+     * @default false
+     */
+    defaultExpanded: boolean;
+    /** Header content (e.g. logo, app name) */
+    header: React.ReactNode;
+}>;
+export type SidebarCallbacks = Partial<{
+    /** Called when the backdrop or ESC closes */
+    onClose: VoidFunction;
+    /** Setter for the expanded state */
+    onExpandedChange: (expanded: boolean) => void;
+    /** Item-click handler */
+    onItemClick: (item: SidebarMenuItem) => void;
+}>;
+export type SidebarProps = SidebarOptions & SidebarCallbacks & {
+    /** Menu items (supports nested `items`) */
+    items: SidebarMenuItem[];
+};
+export type MenuItemInternalOptions = Partial<{
+    depth: number;
+    activeId: string;
+    inOverlay: boolean;
+}>;
+export type MenuItemInternalCallbacks = Partial<{
+    onItemClick: (item: SidebarMenuItem) => void;
+}>;
+export type MenuItemInternalProps = MenuItemInternalOptions & MenuItemInternalCallbacks & {
+    item: SidebarMenuItem;
+    isExpanded: boolean;
+    overlayId: string | null;
+    onOverlayChange: React.Dispatch<React.SetStateAction<string | null>>;
+};
+export type OverlayContentOptions = Partial<{
+    activeId: string;
+}>;
+export type OverlayContentCallbacks = Partial<{
+    onItemClick: (item: SidebarMenuItem) => void;
+}>;
+export type OverlayContentProps = OverlayContentOptions & OverlayContentCallbacks & {
+    items: SidebarMenuItem[];
+};

package/dist/primitives/components/sidebar/types.js

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

package/dist/primitives/components/sidebar/use-sidebar-state.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Custom hook to persist sidebar expanded state in localStorage
+ * @category navigation
+ * @domain generic
+ * @tier agent-ready
+ */
+export declare const useSidebarExpandedState: (defaultExpanded: boolean) => [boolean, (expanded: boolean) => void];
+/**
+ * Custom hook to persist individual section open/closed states in localStorage
+ * @category navigation
+ * @domain generic
+ * @tier agent-ready
+ */
+export declare const useSidebarSectionState: (sectionId: string, defaultOpen: boolean) => [boolean, (open: boolean) => void];
+/**
+ * Clear all sidebar state from localStorage
+ */
+export declare const clearSidebarState: () => void;

package/dist/primitives/components/sidebar/use-sidebar-state.js

@@ -0,0 +1,85 @@
+import { useCallback, useState } from 'react';
+const SIDEBAR_STORAGE_KEY = 'mdk-sidebar-state';
+const SECTION_STORAGE_KEY = 'mdk-sidebar-sections';
+/**
+ * Custom hook to persist sidebar expanded state in localStorage
+ * @category navigation
+ * @domain generic
+ * @tier agent-ready
+ */
+export const useSidebarExpandedState = (defaultExpanded) => {
+    const [expanded, setExpandedState] = useState(() => {
+        try {
+            const stored = localStorage.getItem(SIDEBAR_STORAGE_KEY);
+            if (stored) {
+                const state = JSON.parse(stored);
+                return state.expanded;
+            }
+        }
+        catch (error) {
+            // oxlint-disable-next-line no-console -- storage failure is non-fatal; surface it without throwing
+            console.warn('Failed to load sidebar state from localStorage:', error);
+        }
+        return defaultExpanded;
+    });
+    const setExpanded = useCallback((newExpanded) => {
+        setExpandedState(newExpanded);
+        try {
+            localStorage.setItem(SIDEBAR_STORAGE_KEY, JSON.stringify({ expanded: newExpanded }));
+        }
+        catch (error) {
+            // oxlint-disable-next-line no-console -- storage failure is non-fatal; surface it without throwing
+            console.warn('Failed to save sidebar state to localStorage:', error);
+        }
+    }, []);
+    return [expanded, setExpanded];
+};
+/**
+ * Custom hook to persist individual section open/closed states in localStorage
+ * @category navigation
+ * @domain generic
+ * @tier agent-ready
+ */
+export const useSidebarSectionState = (sectionId, defaultOpen) => {
+    const [isOpen, setIsOpenState] = useState(() => {
+        try {
+            const stored = localStorage.getItem(SECTION_STORAGE_KEY);
+            if (stored) {
+                const states = JSON.parse(stored);
+                return states[sectionId] ?? defaultOpen;
+            }
+        }
+        catch (error) {
+            // oxlint-disable-next-line no-console -- storage failure is non-fatal; surface it without throwing
+            console.warn('Failed to load section states from localStorage:', error);
+        }
+        return defaultOpen;
+    });
+    const setIsOpen = useCallback((newOpen) => {
+        setIsOpenState(newOpen);
+        try {
+            const stored = localStorage.getItem(SECTION_STORAGE_KEY);
+            const states = stored ? JSON.parse(stored) : {};
+            states[sectionId] = newOpen;
+            localStorage.setItem(SECTION_STORAGE_KEY, JSON.stringify(states));
+        }
+        catch (error) {
+            // oxlint-disable-next-line no-console -- storage failure is non-fatal; surface it without throwing
+            console.warn('Failed to save section state to localStorage:', error);
+        }
+    }, [sectionId]);
+    return [isOpen, setIsOpen];
+};
+/**
+ * Clear all sidebar state from localStorage
+ */
+export const clearSidebarState = () => {
+    try {
+        localStorage.removeItem(SIDEBAR_STORAGE_KEY);
+        localStorage.removeItem(SECTION_STORAGE_KEY);
+    }
+    catch (error) {
+        // oxlint-disable-next-line no-console -- storage failure is non-fatal; surface it without throwing
+        console.warn('Failed to clear sidebar state from localStorage:', error);
+    }
+};

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

@@ -0,0 +1,39 @@
+import React from 'react';
+export type SkeletonBlockProps = Partial<{
+    /**
+     * Renders a perfect circle using `height` as the diameter
+     * @default false
+     */
+    circle: boolean;
+    /** Additional class for the element */
+    className: string;
+    /** Width in pixels (number) or any CSS value (string) */
+    width: number | string;
+    /** Height in pixels (number) or any CSS value (string) */
+    height: number | string;
+    /** Border radius; ignored when `circle` is true */
+    borderRadius: number | string;
+}>;
+/**
+ * Rectangular shimmer placeholder used to hint at content shape while data is loading.
+ *
+ * @category feedback
+ * @domain generic
+ * @tier agent-ready
+ */
+declare const SkeletonBlock: React.ForwardRefExoticComponent<Partial<{
+    /**
+     * Renders a perfect circle using `height` as the diameter
+     * @default false
+     */
+    circle: boolean;
+    /** Additional class for the element */
+    className: string;
+    /** Width in pixels (number) or any CSS value (string) */
+    width: number | string;
+    /** Height in pixels (number) or any CSS value (string) */
+    height: number | string;
+    /** Border radius; ignored when `circle` is true */
+    borderRadius: number | string;
+}> & React.RefAttributes<HTMLDivElement>>;
+export { SkeletonBlock };

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

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React from 'react';
+import { cn, toCssSize } from '../../utils';
+/**
+ * Rectangular shimmer placeholder used to hint at content shape while data is loading.
+ *
+ * @category feedback
+ * @domain generic
+ * @tier agent-ready
+ */
+const SkeletonBlock = React.forwardRef(({ width, height, className, borderRadius, circle = false, ...props }, ref) => {
+    const computedStyle = {
+        height: toCssSize(height),
+        width: circle ? toCssSize(height) : toCssSize(width),
+        borderRadius: circle ? '50%' : toCssSize(borderRadius),
+    };
+    return (_jsx("div", { ref: ref, className: cn('mdk-skeleton mdk-skeleton__line', className), style: computedStyle, ...props }));
+});
+SkeletonBlock.displayName = 'SkeletonBlock';
+export { SkeletonBlock };

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

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

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

@@ -0,0 +1,6 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Runnable example for SkeletonBlock.
+ */
+import { SkeletonBlock } from '@tetherto/mdk-react-devkit';
+export const SkeletonExample = () => (_jsxs("div", { className: "mdk-example-col", children: [_jsx(SkeletonBlock, { width: 320, height: 16, borderRadius: 4 }), _jsx(SkeletonBlock, { width: 240, height: 16, borderRadius: 4 }), _jsx(SkeletonBlock, { width: 280, height: 16, borderRadius: 4 }), _jsxs("div", { className: "mdk-example-inline", children: [_jsx(SkeletonBlock, { circle: true, height: 40 }), _jsxs("div", { className: "mdk-example-col", children: [_jsx(SkeletonBlock, { width: 160, height: 14, borderRadius: 4 }), _jsx(SkeletonBlock, { width: 120, height: 12, borderRadius: 4 })] })] }), _jsx(SkeletonBlock, { width: "100%", height: 80, borderRadius: 8 })] }));

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

@@ -0,0 +1,7 @@
+/**
+ * Slider input component (Radix UI).
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+export * from '@radix-ui/react-slider';

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

@@ -0,0 +1,7 @@
+/**
+ * Slider input component (Radix UI).
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+export * from '@radix-ui/react-slider';

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

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

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

@@ -0,0 +1,65 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Runnable example for Slider (Radix Slider re-export).
+ */
+import { useState } from 'react';
+import { Slider } from '@tetherto/mdk-react-devkit';
+export const SliderExample = () => {
+    const [value, setValue] = useState([60]);
+    const [range, setRange] = useState([20, 80]);
+    return (_jsxs("div", { className: "mdk-example-col", children: [_jsxs("div", { children: [_jsxs("p", { children: ["Fan Speed: ", value[0], "%"] }), _jsxs(Slider.Root, { value: value, onValueChange: setValue, min: 0, max: 100, step: 1, style: {
+                            position: 'relative',
+                            display: 'flex',
+                            alignItems: 'center',
+                            userSelect: 'none',
+                            width: '300px',
+                            height: '20px',
+                        }, children: [_jsx(Slider.Track, { style: {
+                                    position: 'relative',
+                                    flexGrow: 1,
+                                    borderRadius: '9999px',
+                                    height: '4px',
+                                    background: 'var(--mdk-color-bg-tertiary)',
+                                }, children: _jsx(Slider.Range, { style: {
+                                        position: 'absolute',
+                                        height: '100%',
+                                        borderRadius: '9999px',
+                                        background: 'var(--mdk-color-primary)',
+                                    } }) }), _jsx(Slider.Thumb, { style: {
+                                    display: 'block',
+                                    width: '16px',
+                                    height: '16px',
+                                    borderRadius: '50%',
+                                    background: 'var(--mdk-color-primary)',
+                                }, "aria-label": "Fan speed" })] })] }), _jsxs("div", { children: [_jsxs("p", { children: ["Hash Rate Range: ", range[0], "\u2013", range[1], " TH/s"] }), _jsxs(Slider.Root, { value: range, onValueChange: setRange, min: 0, max: 100, step: 5, style: {
+                            position: 'relative',
+                            display: 'flex',
+                            alignItems: 'center',
+                            userSelect: 'none',
+                            width: '300px',
+                            height: '20px',
+                        }, children: [_jsx(Slider.Track, { style: {
+                                    position: 'relative',
+                                    flexGrow: 1,
+                                    borderRadius: '9999px',
+                                    height: '4px',
+                                    background: 'var(--mdk-color-bg-tertiary)',
+                                }, children: _jsx(Slider.Range, { style: {
+                                        position: 'absolute',
+                                        height: '100%',
+                                        borderRadius: '9999px',
+                                        background: 'var(--mdk-color-primary)',
+                                    } }) }), _jsx(Slider.Thumb, { style: {
+                                    display: 'block',
+                                    width: '16px',
+                                    height: '16px',
+                                    borderRadius: '50%',
+                                    background: 'var(--mdk-color-primary)',
+                                }, "aria-label": "Min hash rate" }), _jsx(Slider.Thumb, { style: {
+                                    display: 'block',
+                                    width: '16px',
+                                    height: '16px',
+                                    borderRadius: '50%',
+                                    background: 'var(--mdk-color-primary)',
+                                }, "aria-label": "Max hash rate" })] })] })] }));
+};

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

@@ -0,0 +1,92 @@
+import { type ComponentPropsWithoutRef } from 'react';
+import type { ComponentSize } from '../../types';
+export type SpinnerProps = {
+    /**
+     * Size variant of the spinner
+     * @default 'md'
+     */
+    size?: ComponentSize;
+    /**
+     * Color variant of the spinner
+     * @default 'primary'
+     */
+    color?: 'primary' | 'secondary';
+    /**
+     * Whether to display in fullscreen mode
+     * @default false
+     */
+    fullScreen?: boolean;
+    /**
+     * Custom className for the root element
+     */
+    className?: string;
+    /**
+     * Optional label text to display below the spinner
+     */
+    label?: string;
+    /**
+     * Speed of the animation
+     * @default 'normal'
+     */
+    speed?: 'slow' | 'normal' | 'fast';
+    /**
+     * Type of spinner animation
+     * @default 'square'
+     * @remarks
+     * - 'circle': Rotating circle animation
+     * - 'square': Rotating squares animation
+     */
+    type?: 'circle' | 'square';
+} & ComponentPropsWithoutRef<'div'>;
+/**
+ * Spinner component - display loading state with rotating squares
+ *
+ * @example
+ * ```tsx
+ * <Spinner />
+ * <Spinner size="lg" color="primary" />
+ * <Spinner fullScreen />
+ * ```
+ * @category feedback
+ * @domain generic
+ * @tier agent-ready
+ */
+declare const Spinner: import("react").ForwardRefExoticComponent<{
+    /**
+     * Size variant of the spinner
+     * @default 'md'
+     */
+    size?: ComponentSize;
+    /**
+     * Color variant of the spinner
+     * @default 'primary'
+     */
+    color?: 'primary' | 'secondary';
+    /**
+     * Whether to display in fullscreen mode
+     * @default false
+     */
+    fullScreen?: boolean;
+    /**
+     * Custom className for the root element
+     */
+    className?: string;
+    /**
+     * Optional label text to display below the spinner
+     */
+    label?: string;
+    /**
+     * Speed of the animation
+     * @default 'normal'
+     */
+    speed?: 'slow' | 'normal' | 'fast';
+    /**
+     * Type of spinner animation
+     * @default 'square'
+     * @remarks
+     * - 'circle': Rotating circle animation
+     * - 'square': Rotating squares animation
+     */
+    type?: 'circle' | 'square';
+} & Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export { Spinner };

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

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { cn } from '../../utils';
+const SpinnerCircle = forwardRef(({ className, size = 'md', color = 'orange', fullScreen = false, label, speed = 'normal', ...props }, ref) => {
+    return (_jsx("div", { ref: ref, className: cn('mdk-spinner', fullScreen && 'mdk-spinner--fullscreen', className), ...props, children: _jsxs("div", { className: "mdk-spinner__content", children: [_jsx("div", { className: cn('mdk-spinner__circle', `mdk-spinner__circle--${size}`, `mdk-spinner__circle--${color}`, `mdk-spinner__circle--${speed}`), role: "status", "aria-live": "polite", "aria-label": label || 'Loading' }), label && (_jsx("span", { className: cn('mdk-spinner__label', `mdk-spinner__label--${size}`), children: label }))] }) }));
+});
+const SpinnerSquare = forwardRef(({ className, size = 'md', color = 'amber', speed = 'normal', fullScreen = false, label, ...props }, ref) => {
+    return (_jsx("div", { ref: ref, className: cn('mdk-spinner', fullScreen && 'mdk-spinner--fullscreen', className), ...props, children: _jsxs("div", { className: "mdk-spinner__content", children: [_jsxs("div", { className: cn('mdk-spinner__dot', `mdk-spinner__dot--${size}`, `mdk-spinner__dot--${speed}`), role: "status", "aria-live": "polite", "aria-label": label || 'Loading', children: [_jsx("span", { className: cn('mdk-spinner__dot-item', `mdk-spinner__dot-item--${color}`) }), _jsx("span", { className: cn('mdk-spinner__dot-item', `mdk-spinner__dot-item--${color}`) }), _jsx("span", { className: cn('mdk-spinner__dot-item', `mdk-spinner__dot-item--${color}`) }), _jsx("span", { className: cn('mdk-spinner__dot-item', `mdk-spinner__dot-item--${color}`) })] }), label && (_jsx("span", { className: cn('mdk-spinner__label', `mdk-spinner__label--${size}`, `mdk-spinner__label--${color}`), children: label }))] }) }));
+});
+/**
+ * Spinner component - display loading state with rotating squares
+ *
+ * @example
+ * ```tsx
+ * <Spinner />
+ * <Spinner size="lg" color="primary" />
+ * <Spinner fullScreen />
+ * ```
+ * @category feedback
+ * @domain generic
+ * @tier agent-ready
+ */
+const Spinner = forwardRef(({ className, size = 'md', color = 'primary', fullScreen = false, type = 'square', speed = 'normal', label, ...props }, ref) => {
+    const isCircle = type === 'circle';
+    if (isCircle) {
+        return (_jsx(SpinnerCircle, { ref: ref, className: className, size: size, color: color, fullScreen: fullScreen, label: label, type: "circle", ...props }));
+    }
+    return (_jsx(SpinnerSquare, { ref: ref, className: className, size: size, color: color, fullScreen: fullScreen, label: label, speed: speed, type: "square", ...props }));
+});
+Spinner.displayName = 'Spinner';
+export { Spinner };

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

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

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

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Runnable example for Spinner.
+ */
+import { Spinner } from '@tetherto/mdk-react-devkit';
+export const SpinnerExample = () => {
+    return (_jsxs("div", { style: { display: 'flex', gap: 32, alignItems: 'center' }, children: [_jsx(Spinner, { size: "sm" }), _jsx(Spinner, { size: "md", type: "circle" }), _jsx(Spinner, { size: "lg", label: "Loading miners\u2026" })] }));
+};