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

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

@@ -0,0 +1,186 @@
+import * as RadioGroupPrimitive from '@radix-ui/react-radio-group';
+import type { BorderRadius, ComponentColor, ComponentSize } from '../../types';
+import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+type RadioItemProps = ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>;
+export type RadioProps = {
+    /** Value associated with this option */
+    value: RadioItemProps['value'];
+    /**
+     * Size variant of the radio
+     * @default 'md'
+     */
+    size?: ComponentSize;
+    /**
+     * Color variant when checked
+     * @default 'primary'
+     */
+    color?: ComponentColor;
+    /**
+     * Border radius variant (full makes it circular)
+     * @default 'full'
+     */
+    radius?: BorderRadius;
+    /**
+     * Custom className for the root element
+     */
+    className?: string;
+    /**
+     * Label text (or use children for custom content)
+     */
+    label?: string;
+    /**
+     * Children content (takes precedence over label)
+     */
+    children?: ReactNode;
+    /**
+     * Custom className for the indicator element
+     */
+    indicatorClassName?: string;
+} & RadioItemProps;
+/**
+ * Radio button component (use within RadioGroup)
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup>
+ *   <Radio value="option1" />
+ *   <Radio value="option2" />
+ * </RadioGroup>
+ * ```
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+declare const Radio: import("react").ForwardRefExoticComponent<{
+    /** Value associated with this option */
+    value: RadioItemProps['value'];
+    /**
+     * Size variant of the radio
+     * @default 'md'
+     */
+    size?: ComponentSize;
+    /**
+     * Color variant when checked
+     * @default 'primary'
+     */
+    color?: ComponentColor;
+    /**
+     * Border radius variant (full makes it circular)
+     * @default 'full'
+     */
+    radius?: BorderRadius;
+    /**
+     * Custom className for the root element
+     */
+    className?: string;
+    /**
+     * Label text (or use children for custom content)
+     */
+    label?: string;
+    /**
+     * Children content (takes precedence over label)
+     */
+    children?: ReactNode;
+    /**
+     * Custom className for the indicator element
+     */
+    indicatorClassName?: string;
+} & Omit<RadioGroupPrimitive.RadioGroupItemProps & import("react").RefAttributes<HTMLButtonElement>, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;
+export type RadioGroupProps = {
+    /**
+     * Layout orientation
+     * @default 'vertical'
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     *  Remove gap between radio items
+     * @default false
+     */
+    noGap?: boolean;
+    /**
+     * Custom className for the group
+     */
+    className?: string;
+} & ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>;
+/**
+ * RadioGroup component - container for Radio items
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup defaultValue="option1" onValueChange={setValue}>
+ *   <Radio value="option1" />
+ *   <Radio value="option2" />
+ * </RadioGroup>
+ * ```
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+declare const RadioGroup: import("react").ForwardRefExoticComponent<{
+    /**
+     * Layout orientation
+     * @default 'vertical'
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     *  Remove gap between radio items
+     * @default false
+     */
+    noGap?: boolean;
+    /**
+     * Custom className for the group
+     */
+    className?: string;
+} & Omit<RadioGroupPrimitive.RadioGroupProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+/**
+ * RadioCard component - button-like radio option
+ *
+ * Supports an `onChange` callback when selected.
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup defaultValue="5min" orientation="horizontal" onValueChange={value => console.log(value)}>
+ *   <RadioCard value="5min" label="5 Min" onChange={value => () => console.log('Selected:', value)} />
+ *   <RadioCard value="30min" label="30 Min" onChange={value => () => console.log('Selected:', value)} />
+ * </RadioGroup>
+ * ```
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+declare const RadioCard: import("react").ForwardRefExoticComponent<{
+    /** Value associated with this option */
+    value: RadioItemProps['value'];
+    /**
+     * Size variant of the radio
+     * @default 'md'
+     */
+    size?: ComponentSize;
+    /**
+     * Color variant when checked
+     * @default 'primary'
+     */
+    color?: ComponentColor;
+    /**
+     * Border radius variant (full makes it circular)
+     * @default 'full'
+     */
+    radius?: BorderRadius;
+    /**
+     * Custom className for the root element
+     */
+    className?: string;
+    /**
+     * Label text (or use children for custom content)
+     */
+    label?: string;
+    /**
+     * Children content (takes precedence over label)
+     */
+    children?: ReactNode;
+    /**
+     * Custom className for the indicator element
+     */
+    indicatorClassName?: string;
+} & Omit<RadioGroupPrimitive.RadioGroupItemProps & import("react").RefAttributes<HTMLButtonElement>, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;
+export { Radio, RadioCard, RadioGroup };

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

@@ -0,0 +1,55 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as RadioGroupPrimitive from '@radix-ui/react-radio-group';
+import { cn } from '../../utils';
+import { forwardRef } from 'react';
+/**
+ * Radio button component (use within RadioGroup)
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup>
+ *   <Radio value="option1" />
+ *   <Radio value="option2" />
+ * </RadioGroup>
+ * ```
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+const Radio = forwardRef(({ className, indicatorClassName, size = 'md', color = 'primary', radius = 'full', label, children, ...props }, ref) => (_jsx(RadioGroupPrimitive.Item, { ref: ref, className: cn('mdk-radio', `mdk-radio--${size}`, `mdk-radio--${color}`, `mdk-radio--radius-${radius}`, className), ...props, children: (label || children) ?? (_jsx(RadioGroupPrimitive.Indicator, { className: cn('mdk-radio__indicator', indicatorClassName) })) })));
+Radio.displayName = 'Radio';
+/**
+ * RadioGroup component - container for Radio items
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup defaultValue="option1" onValueChange={setValue}>
+ *   <Radio value="option1" />
+ *   <Radio value="option2" />
+ * </RadioGroup>
+ * ```
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+const RadioGroup = forwardRef(({ className, orientation = 'vertical', noGap = false, ...props }, ref) => (_jsx(RadioGroupPrimitive.Root, { ref: ref, className: cn('mdk-radio-group', `mdk-radio-group--${orientation}`, noGap && 'mdk-radio-group--no-gap', className), ...props })));
+RadioGroup.displayName = 'RadioGroup';
+/**
+ * RadioCard component - button-like radio option
+ *
+ * Supports an `onChange` callback when selected.
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup defaultValue="5min" orientation="horizontal" onValueChange={value => console.log(value)}>
+ *   <RadioCard value="5min" label="5 Min" onChange={value => () => console.log('Selected:', value)} />
+ *   <RadioCard value="30min" label="30 Min" onChange={value => () => console.log('Selected:', value)} />
+ * </RadioGroup>
+ * ```
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+const RadioCard = forwardRef(({ className, size = 'sm', color = 'default', radius = 'none', label, children, ...props }, ref) => (_jsx(Radio, { ref: ref, className: cn('mdk-radio-card', `mdk-radio-card--${size}`, `mdk-radio-card--${color}`, `mdk-radio-card--radius-${radius}`, className), ...props, children: children || label })));
+RadioCard.displayName = 'RadioCard';
+export { Radio, RadioCard, RadioGroup };

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

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

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

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Runnable example for Radio and RadioGroup.
+ */
+import { useState } from 'react';
+import { Radio, RadioCard, RadioGroup } from '@tetherto/mdk-react-devkit';
+export const RadioExample = () => {
+    const [plan, setPlan] = useState('standard');
+    const [interval, setInterval] = useState('5min');
+    return (_jsxs("div", { className: "mdk-example-col", children: [_jsxs(RadioGroup, { value: plan, onValueChange: setPlan, orientation: "vertical", children: [_jsxs("div", { className: "mdk-example-inline", children: [_jsx(Radio, { value: "basic", color: "primary" }), _jsx("span", { children: "Basic" })] }), _jsxs("div", { className: "mdk-example-inline", children: [_jsx(Radio, { value: "standard", color: "primary" }), _jsx("span", { children: "Standard" })] }), _jsxs("div", { className: "mdk-example-inline", children: [_jsx(Radio, { value: "pro", color: "primary", disabled: true }), _jsx("span", { children: "Pro (unavailable)" })] })] }), _jsxs(RadioGroup, { value: interval, onValueChange: setInterval, orientation: "horizontal", children: [_jsx(RadioCard, { value: "5min", label: "5 Min" }), _jsx(RadioCard, { value: "15min", label: "15 Min" }), _jsx(RadioCard, { value: "30min", label: "30 Min" }), _jsx(RadioCard, { value: "1h", label: "1 Hour" })] })] }));
+};

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

@@ -0,0 +1,110 @@
+import * as SelectPrimitive from '@radix-ui/react-select';
+import { type ComponentPropsWithoutRef } from 'react';
+type SelectRootProps = ComponentPropsWithoutRef<typeof SelectPrimitive.Root>;
+export type SelectProps = SelectRootProps & {
+    /** Controlled value */
+    value?: SelectRootProps['value'];
+    /** Uncontrolled initial value */
+    defaultValue?: SelectRootProps['defaultValue'];
+    /** Setter for the value */
+    onValueChange?: SelectRootProps['onValueChange'];
+    /**
+     * Show a clear button when a value is selected
+     * @default false
+     */
+    allowClear?: boolean;
+};
+export type SelectSize = 'sm' | 'md' | 'lg';
+export type SelectVariant = 'default' | 'colored';
+declare const SelectGroup: import("react").ForwardRefExoticComponent<SelectPrimitive.SelectGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+declare const SelectValue: import("react").ForwardRefExoticComponent<SelectPrimitive.SelectValueProps & import("react").RefAttributes<HTMLSpanElement>>;
+/**
+ * Dropdown select built on Radix UI. Supports `default` and `colored`
+ * variants, multiple sizes, and full keyboard navigation.
+ *
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+declare const Select: (allProps: SelectProps) => import("react").JSX.Element;
+export type SelectTriggerProps = ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger> & {
+    /**
+     * Size of the select trigger
+     * - `sm`: Small (32px height)
+     * - `md`: Medium (36px height)
+     * - `lg`: Large/Big (40px height)
+     * @default 'lg'
+     */
+    size?: SelectSize;
+    /**
+     * Visual variant
+     * - `default`: Standard border style
+     * - `colored`: Colored background (10% opacity) with colored text
+     * @default 'default'
+     */
+    variant?: SelectVariant;
+    /**
+     * Custom color for the colored variant (hex color)
+     * Only applies when variant="colored"
+     * @example "#72F59E"
+     */
+    color?: string;
+};
+/**
+ * SelectTrigger - The button that toggles the select dropdown
+ * @category forms
+ * @domain generic
+ * @tier internal
+ */
+declare const SelectTrigger: import("react").ForwardRefExoticComponent<Omit<SelectPrimitive.SelectTriggerProps & import("react").RefAttributes<HTMLButtonElement>, "ref"> & {
+    /**
+     * Size of the select trigger
+     * - `sm`: Small (32px height)
+     * - `md`: Medium (36px height)
+     * - `lg`: Large/Big (40px height)
+     * @default 'lg'
+     */
+    size?: SelectSize;
+    /**
+     * Visual variant
+     * - `default`: Standard border style
+     * - `colored`: Colored background (10% opacity) with colored text
+     * @default 'default'
+     */
+    variant?: SelectVariant;
+    /**
+     * Custom color for the colored variant (hex color)
+     * Only applies when variant="colored"
+     * @example "#72F59E"
+     */
+    color?: string;
+} & import("react").RefAttributes<HTMLButtonElement>>;
+/**
+ * Floating dropdown panel inside `<Select>` that hosts the list of `<SelectItem>`s.
+ * @category forms
+ * @domain generic
+ * @tier internal
+ */
+declare const SelectContent: import("react").ForwardRefExoticComponent<Omit<SelectPrimitive.SelectContentProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+/**
+ * SelectLabel - Label for a group of items
+ * @category forms
+ * @domain generic
+ * @tier internal
+ */
+declare const SelectLabel: import("react").ForwardRefExoticComponent<Omit<SelectPrimitive.SelectLabelProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+/**
+ * Single selectable option rendered inside `<SelectContent>` — pass `value` for the option key and children for the label.
+ * @category forms
+ * @domain generic
+ * @tier internal
+ */
+declare const SelectItem: import("react").ForwardRefExoticComponent<Omit<SelectPrimitive.SelectItemProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+/**
+ * SelectSeparator - Visual separator between items
+ * @category forms
+ * @domain generic
+ * @tier internal
+ */
+declare const SelectSeparator: import("react").ForwardRefExoticComponent<Omit<SelectPrimitive.SelectSeparatorProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue, };

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

@@ -0,0 +1,96 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CheckIcon, Cross2Icon } from '@radix-ui/react-icons';
+import * as SelectPrimitive from '@radix-ui/react-select';
+import { cn, hexToRgba } from '../../utils';
+import { createContext, forwardRef, useContext, useState, } from 'react';
+const ChevronDownIcon = ({ className }) => (_jsx("svg", { className: className, xmlns: "http://www.w3.org/2000/svg", width: "24", height: "24", viewBox: "0 0 24 24", fill: "none", children: _jsx("path", { fillRule: "evenodd", clipRule: "evenodd", d: "M6.27592 8.65219C6.44783 8.48679 6.67838 8.39641 6.91689 8.40091C7.1554 8.40541 7.38237 8.50442 7.54792 8.67619L11.9999 13.4018L16.4519 8.67619C16.5328 8.58697 16.6309 8.51491 16.7401 8.46427C16.8494 8.41363 16.9678 8.38544 17.0881 8.38137C17.2085 8.37731 17.3285 8.39744 17.4409 8.44059C17.5534 8.48374 17.6561 8.54902 17.7428 8.63257C17.8296 8.71612 17.8987 8.81623 17.946 8.92698C17.9934 9.03772 18.0181 9.15685 18.0185 9.2773C18.019 9.39775 17.9953 9.51706 17.9488 9.62818C17.9023 9.7393 17.834 9.83996 17.7479 9.92419L12.6479 15.3242C12.564 15.4113 12.4633 15.4806 12.352 15.5279C12.2406 15.5752 12.1209 15.5996 11.9999 15.5996C11.8789 15.5996 11.7592 15.5752 11.6479 15.5279C11.5365 15.4806 11.4359 15.4113 11.3519 15.3242L6.25192 9.92419C6.08653 9.75228 5.99615 9.52173 6.00065 9.28322C6.00515 9.04471 6.10416 8.81774 6.27592 8.65219Z", fill: "currentColor" }) }));
+const SelectContext = createContext({});
+const SelectGroup = SelectPrimitive.Group;
+const SelectValue = SelectPrimitive.Value;
+/**
+ * Dropdown select built on Radix UI. Supports `default` and `colored`
+ * variants, multiple sizes, and full keyboard navigation.
+ *
+ * @category forms
+ * @domain generic
+ * @tier agent-ready
+ */
+const Select = (allProps) => {
+    const { allowClear, onValueChange, value, defaultValue, children, ...props } = allProps;
+    const [internalValue, setInternalValue] = useState(defaultValue);
+    const isControlled = 'value' in allProps;
+    const currentValue = isControlled ? value : internalValue;
+    /** Radix treats `value={undefined}` as uncontrolled (`prop === undefined`); use '' for controlled “no value”. */
+    const resolvedValue = isControlled ? currentValue : internalValue;
+    const radixValue = isControlled ? (resolvedValue ?? '') : internalValue;
+    const handleValueChange = (next) => {
+        if (!isControlled)
+            setInternalValue(next);
+        onValueChange?.(next);
+    };
+    const handleClear = () => {
+        if (!isControlled)
+            setInternalValue(undefined);
+        onValueChange?.('');
+    };
+    return (_jsx(SelectContext.Provider, { value: { value: currentValue, onClear: handleClear, allowClear }, children: _jsx(SelectPrimitive.Root, { value: radixValue, onValueChange: handleValueChange, ...props, children: children }) }));
+};
+/**
+ * SelectTrigger - The button that toggles the select dropdown
+ * @category forms
+ * @domain generic
+ * @tier internal
+ */
+const SelectTrigger = forwardRef(({ className, children, size = 'lg', variant = 'default', color, style, ...props }, ref) => {
+    const { value, onClear, allowClear } = useContext(SelectContext);
+    const hasValue = Boolean(value);
+    const showClear = allowClear && hasValue;
+    let coloredStyle = style;
+    if (variant === 'colored' && color) {
+        coloredStyle = {
+            '--select-color': color,
+            '--select-bg': hexToRgba(color, 0.1),
+            '--select-bg-hover': hexToRgba(color, 0.15),
+            ...style,
+        };
+    }
+    return (_jsxs(SelectPrimitive.Trigger, { ref: ref, className: cn('mdk-select__trigger', `mdk-select__trigger--${size}`, variant === 'colored' && 'mdk-select__trigger--colored', className), style: coloredStyle, ...props, children: [children, showClear ? (_jsx("span", { className: "mdk-select__clear", role: "button", "aria-label": "Clear selection", onPointerDown: (e) => {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    onClear?.();
+                }, children: _jsx(Cross2Icon, {}) })) : (_jsx(SelectPrimitive.Icon, { asChild: true, children: _jsx(ChevronDownIcon, { className: "mdk-select__icon" }) }))] }));
+});
+SelectTrigger.displayName = SelectPrimitive.Trigger.displayName;
+/**
+ * Floating dropdown panel inside `<Select>` that hosts the list of `<SelectItem>`s.
+ * @category forms
+ * @domain generic
+ * @tier internal
+ */
+const SelectContent = forwardRef(({ className, children, position = 'popper', sideOffset = 8, collisionPadding = 16, ...props }, ref) => (_jsx(SelectPrimitive.Portal, { children: _jsx(SelectPrimitive.Content, { ref: ref, className: cn('mdk-select__content', className), position: position, sideOffset: sideOffset, collisionPadding: collisionPadding, ...props, children: _jsx(SelectPrimitive.Viewport, { className: cn(position === 'popper' && 'mdk-select__viewport mdk-select__viewport--popper'), children: children }) }) })));
+SelectContent.displayName = SelectPrimitive.Content.displayName;
+/**
+ * SelectLabel - Label for a group of items
+ * @category forms
+ * @domain generic
+ * @tier internal
+ */
+const SelectLabel = forwardRef(({ className, ...props }, ref) => (_jsx(SelectPrimitive.Label, { ref: ref, className: cn('mdk-select__label', className), ...props })));
+SelectLabel.displayName = SelectPrimitive.Label.displayName;
+/**
+ * Single selectable option rendered inside `<SelectContent>` — pass `value` for the option key and children for the label.
+ * @category forms
+ * @domain generic
+ * @tier internal
+ */
+const SelectItem = forwardRef(({ className, children, ...props }, ref) => (_jsxs(SelectPrimitive.Item, { ref: ref, className: cn('mdk-select__item', className), ...props, children: [_jsx(SelectPrimitive.ItemText, { children: children }), _jsx(SelectPrimitive.ItemIndicator, { className: "mdk-select__item-indicator", children: _jsx(CheckIcon, {}) })] })));
+SelectItem.displayName = SelectPrimitive.Item.displayName;
+/**
+ * SelectSeparator - Visual separator between items
+ * @category forms
+ * @domain generic
+ * @tier internal
+ */
+const SelectSeparator = forwardRef(({ className, ...props }, ref) => (_jsx(SelectPrimitive.Separator, { ref: ref, className: cn('mdk-select__separator', className), ...props })));
+SelectSeparator.displayName = SelectPrimitive.Separator.displayName;
+export { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue, };

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

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

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

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Runnable example for Select.
+ */
+import { useState } from 'react';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from '@tetherto/mdk-react-devkit';
+export const SelectExample = () => {
+    const [value, setValue] = useState();
+    return (_jsxs(Select, { value: value, onValueChange: setValue, children: [_jsx(SelectTrigger, { style: { width: 240 }, children: _jsx(SelectValue, { placeholder: "Select a container" }) }), _jsxs(SelectContent, { children: [_jsx(SelectItem, { value: "cont-A", children: "Container A" }), _jsx(SelectItem, { value: "cont-B", children: "Container B" }), _jsx(SelectItem, { value: "cont-C", children: "Container C" })] })] }));
+};

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

@@ -0,0 +1,3 @@
+import type { SidebarMenuItem } from './types';
+export declare const hasActiveDescendant: (item: SidebarMenuItem, activeId?: string) => boolean;
+export declare const getFirstLeaf: (item: SidebarMenuItem) => SidebarMenuItem;

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

@@ -0,0 +1,4 @@
+export const hasActiveDescendant = (item, activeId) => !!activeId &&
+    (item.id === activeId ||
+        item.items?.some((child) => hasActiveDescendant(child, activeId)) === true);
+export const getFirstLeaf = (item) => item.items?.length ? getFirstLeaf(item.items[0]) : item;

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

@@ -0,0 +1,8 @@
+import type { SidebarProps } from './types';
+export type { SidebarCallbacks, SidebarMenuItem, SidebarMenuItemBase, SidebarMenuItemOptions, SidebarOptions, SidebarProps, } from './types';
+export { clearSidebarState, useSidebarExpandedState, useSidebarSectionState, } from './use-sidebar-state';
+declare function Sidebar({ items, onClose, expanded, activeId, className, onItemClick, visible, overlay, onExpandedChange, defaultExpanded, header, }: SidebarProps): React.ReactNode;
+declare namespace Sidebar {
+    var displayName: string;
+}
+export { Sidebar };

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

@@ -0,0 +1,58 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useState } from 'react';
+import { ChevronLeftIcon, ChevronRightIcon } from '@radix-ui/react-icons';
+import { cn } from '../../utils';
+import { MenuItemInternal } from './menu-item';
+import { useSidebarExpandedState } from './use-sidebar-state';
+export { clearSidebarState, useSidebarExpandedState, useSidebarSectionState, } from './use-sidebar-state';
+/**
+ * Application sidebar with collapsible state, persistent expansion (via
+ * `localStorage`), optional overlay mode, and item-click + active-item
+ * highlighting.
+ *
+ * @category navigation
+ * @domain generic
+ * @tier agent-ready
+ *
+ * @example
+ * ```tsx
+ * <Sidebar
+ *   items={navItems}
+ *   activeId={currentRoute}
+ *   onItemClick={({ id }) => router.push(id)}
+ * />
+ * ```
+ */
+const Sidebar = ({ items, onClose, expanded, activeId, className, onItemClick, visible = true, overlay = false, onExpandedChange, defaultExpanded = false, header, }) => {
+    const [overlayId, setOverlayId] = useState(null);
+    const [persistedExpanded, setPersistedExpanded] = useSidebarExpandedState(defaultExpanded);
+    const [internalExpanded, setInternalExpanded] = useState(persistedExpanded);
+    const showBackdrop = overlay && visible;
+    const isControlled = expanded !== undefined;
+    const isExpanded = overlay || (isControlled ? expanded : internalExpanded);
+    const handleToggle = useCallback(() => {
+        if (overlay) {
+            onClose?.();
+            return;
+        }
+        const newExpanded = !isExpanded;
+        if (!isControlled) {
+            setInternalExpanded(newExpanded);
+            setPersistedExpanded(newExpanded);
+        }
+        onExpandedChange?.(newExpanded);
+    }, [overlay, onClose, isExpanded, isControlled, onExpandedChange, setPersistedExpanded]);
+    useEffect(() => {
+        if (!showBackdrop)
+            return;
+        const handleEscape = (e) => {
+            if (e.key === 'Escape')
+                onClose?.();
+        };
+        document.addEventListener('keydown', handleEscape);
+        return () => document.removeEventListener('keydown', handleEscape);
+    }, [showBackdrop, onClose]);
+    return (_jsxs(_Fragment, { children: [showBackdrop && _jsx("div", { className: "mdk-sidebar__backdrop", onClick: onClose }), _jsxs("nav", { className: cn('mdk-sidebar', isExpanded && 'mdk-sidebar--expanded', !visible && 'mdk-sidebar--hidden', overlay && 'mdk-sidebar--overlay', showBackdrop && 'mdk-sidebar--overlay-visible', header && 'mdk-sidebar--with-header', className), children: [header && _jsx("div", { className: "mdk-sidebar__header", children: header }), _jsx("button", { type: "button", className: "mdk-sidebar__toggle", onClick: handleToggle, "aria-label": overlay ? 'Close sidebar' : isExpanded ? 'Collapse sidebar' : 'Expand sidebar', children: isExpanded ? _jsx(ChevronLeftIcon, {}) : _jsx(ChevronRightIcon, {}) }), _jsx("div", { className: "mdk-sidebar__menu", children: items.map((item) => (_jsx(MenuItemInternal, { item: item, activeId: activeId, isExpanded: isExpanded, onItemClick: onItemClick, overlayId: overlayId, onOverlayChange: setOverlayId }, item.id))) })] })] }));
+};
+Sidebar.displayName = 'Sidebar';
+export { Sidebar };

package/dist/primitives/components/sidebar/menu-item.d.ts

@@ -0,0 +1,5 @@
+import type { MenuItemInternalProps } from './types';
+export declare function MenuItemInternal({ item, activeId, depth, overlayId, isExpanded, onItemClick, onOverlayChange, inOverlay, }: MenuItemInternalProps): React.ReactNode;
+export declare namespace MenuItemInternal {
+    var displayName: string;
+}