@underverse-ui/underverse 1.0.96 → 1.0.98

package/dist/index.d.cts

@@ -29,6 +29,7 @@ declare const SIZE_STYLES_BTN: {
     icon: string;
 };
 
+/** Public props for the `Button` component. */
 interface ButtonProps extends React__default.ButtonHTMLAttributes<HTMLButtonElement> {
     onClick?: (event: React__default.MouseEvent<HTMLButtonElement>) => void;
     children?: React__default.ReactNode;
@@ -61,6 +62,7 @@ interface ButtonProps extends React__default.ButtonHTMLAttributes<HTMLButtonElem
 }
 declare const Button: React__default.ForwardRefExoticComponent<ButtonProps & React__default.RefAttributes<HTMLButtonElement>>;
 
+/** Public props for the `Badge` component. */
 interface BadgeProps {
     children?: React$1.ReactNode;
     variant?: "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "destructive" | "info" | "outline" | "ghost" | "transparent" | "gradient";
@@ -80,6 +82,7 @@ interface BadgeProps {
     onClick?: () => void;
 }
 declare const Badge: React$1.FC<BadgeProps>;
+/** Public props for the `NotificationBadge` component. */
 interface NotificationBadgeProps {
     children: React$1.ReactNode;
     count?: number;
@@ -94,31 +97,37 @@ interface NotificationBadgeProps {
     pulse?: boolean;
 }
 declare const NotificationBadge: React$1.FC<NotificationBadgeProps>;
+/** Public props for the `StatusBadge` component. */
 interface StatusBadgeProps extends Omit<BadgeProps, "variant"> {
     status?: "online" | "offline" | "busy" | "away" | "idle";
 }
 declare const StatusBadge: React$1.FC<StatusBadgeProps>;
+/** Public props for the `TagBadge` component. */
 interface TagBadgeProps extends Omit<BadgeProps, "removable"> {
     tags?: string[];
     onTagRemove?: (tag: string) => void;
     maxTags?: number;
 }
 declare const TagBadge: React$1.FC<TagBadgeProps>;
+/** Public props for the `InteractiveBadge` component. */
 interface InteractiveBadgeProps extends BadgeProps {
     active?: boolean;
     disabled?: boolean;
 }
 declare const InteractiveBadge: React$1.FC<InteractiveBadgeProps>;
+/** Public props for the `GradientBadge` component. */
 interface GradientBadgeProps extends Omit<BadgeProps, "variant"> {
     from?: string;
     to?: string;
 }
 declare const GradientBadge: React$1.FC<GradientBadgeProps>;
+/** Public props for the `PulseBadge` component. */
 interface PulseBadgeProps extends BadgeProps {
     speed?: "slow" | "normal" | "fast";
 }
 declare const PulseBadge: React$1.FC<PulseBadgeProps>;
 
+/** Public props for the `Card` component. */
 interface CardProps extends Omit<React__default.HTMLAttributes<HTMLDivElement>, "title"> {
     title?: React__default.ReactNode;
     description?: React__default.ReactNode;
@@ -135,6 +144,7 @@ interface CardProps extends Omit<React__default.HTMLAttributes<HTMLDivElement>,
 }
 declare const Card: React__default.ForwardRefExoticComponent<CardProps & React__default.RefAttributes<HTMLDivElement>>;
 
+/** Public props for the `Checkbox` component. */
 interface CheckboxProps extends React$1.InputHTMLAttributes<HTMLInputElement> {
     label?: React$1.ReactNode;
     labelClassName?: string;
@@ -142,6 +152,7 @@ interface CheckboxProps extends React$1.InputHTMLAttributes<HTMLInputElement> {
 }
 declare const Checkbox: React$1.ForwardRefExoticComponent<CheckboxProps & React$1.RefAttributes<HTMLInputElement>>;
 
+/** Public props for the `Input` component. */
 interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size"> {
     label?: string;
     /** Custom class for label */
@@ -167,16 +178,19 @@ interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size">
     rightAddon?: React__default.ReactNode;
 }
 declare const Input: React__default.ForwardRefExoticComponent<InputProps & React__default.RefAttributes<HTMLInputElement>>;
+/** Public props for the `SearchInput` component. */
 interface SearchInputProps extends Omit<InputProps, "leftIcon" | "type"> {
     onSearch?: (value: string) => void;
     searchDelay?: number;
 }
 declare const SearchInput: React__default.ForwardRefExoticComponent<SearchInputProps & React__default.RefAttributes<HTMLInputElement>>;
+/** Public props for the `PasswordInput` component. */
 interface PasswordInputProps extends Omit<InputProps, "type"> {
     showStrength?: boolean;
     strengthLabels?: string[];
 }
 declare const PasswordInput: React__default.ForwardRefExoticComponent<PasswordInputProps & React__default.RefAttributes<HTMLInputElement>>;
+/** Public props for the `NumberInput` component. */
 interface NumberInputProps extends Omit<InputProps, "type" | "value" | "onChange"> {
     min?: number;
     max?: number;
@@ -190,6 +204,7 @@ interface NumberInputProps extends Omit<InputProps, "type" | "value" | "onChange
     onChange?: React__default.ChangeEventHandler<HTMLInputElement>;
 }
 declare const NumberInput: React__default.ForwardRefExoticComponent<NumberInputProps & React__default.RefAttributes<HTMLInputElement>>;
+/** Public props for the `Textarea` component. */
 interface TextareaProps extends React__default.TextareaHTMLAttributes<HTMLTextAreaElement> {
     label?: string;
     /** Custom class for label */
@@ -205,6 +220,7 @@ interface TextareaProps extends React__default.TextareaHTMLAttributes<HTMLTextAr
 }
 declare const Textarea: React__default.ForwardRefExoticComponent<TextareaProps & React__default.RefAttributes<HTMLTextAreaElement>>;
 
+/** Public props for the `EmojiPicker` component. */
 interface EmojiPickerProps {
     onEmojiSelect: (emoji: string) => void;
     className?: string;
@@ -219,6 +235,7 @@ interface EmojiPickerProps {
 }
 declare const EmojiPicker: React__default.FC<EmojiPickerProps>;
 
+/** Public props for the `TagInput` component. */
 interface TagInputProps {
     /** Danh sách tags hiện tại */
     value: string[];
@@ -263,6 +280,7 @@ interface TagInputProps {
 }
 declare const TagInput: React__default.ForwardRefExoticComponent<TagInputProps & React__default.RefAttributes<HTMLInputElement>>;
 
+/** Public props for the `Switch` component. */
 interface SwitchProps extends Omit<React$1.InputHTMLAttributes<HTMLInputElement>, "size"> {
     checked: boolean;
     onCheckedChange: (checked: boolean) => void;
@@ -278,6 +296,7 @@ declare const Switch: React$1.FC<SwitchProps>;
 declare const Label: React$1.ForwardRefExoticComponent<React$1.LabelHTMLAttributes<HTMLLabelElement> & VariantProps<(props?: class_variance_authority_types.ClassProp | undefined) => string> & React$1.RefAttributes<HTMLLabelElement>>;
 
 type StatusType = "online" | "offline" | "busy" | "away" | "none";
+/** Public props for the `Avatar` component. */
 interface AvatarProps extends React$1.HTMLAttributes<HTMLDivElement> {
     src?: string;
     alt?: string;
@@ -293,6 +312,7 @@ interface AvatarProps extends React$1.HTMLAttributes<HTMLDivElement> {
 }
 declare const Avatar: ({ src, alt, fallback, size, showStatus, status, hideStatusOnHover, className, onClick, ...props }: AvatarProps) => react_jsx_runtime.JSX.Element;
 
+/** Public props for the `Skeleton` component. */
 interface SkeletonProps {
     className?: string;
     width?: string | number;
@@ -342,6 +362,7 @@ declare const SkeletonTable: React__default.FC<{
     className?: string;
 }>;
 
+/** Public props for the `Progress` component. */
 interface ProgressProps {
     value: number;
     max?: number;
@@ -357,6 +378,7 @@ interface ProgressProps {
     status?: "normal" | "error" | "complete";
 }
 declare const Progress: React__default.FC<ProgressProps>;
+/** Public props for the `CircularProgress` component. */
 interface CircularProgressProps {
     value: number;
     max?: number;
@@ -371,6 +393,7 @@ interface CircularProgressProps {
     trackColor?: string;
 }
 declare const CircularProgress: React__default.FC<CircularProgressProps>;
+/** Public props for the `StepProgress` component. */
 interface StepProgressProps {
     steps: string[];
     currentStep: number;
@@ -379,6 +402,7 @@ interface StepProgressProps {
     size?: "sm" | "md" | "lg";
 }
 declare const StepProgress: React__default.FC<StepProgressProps>;
+/** Public props for the `MiniProgress` component. */
 interface MiniProgressProps {
     value: number;
     max?: number;
@@ -387,6 +411,7 @@ interface MiniProgressProps {
     showValue?: boolean;
 }
 declare const MiniProgress: React__default.FC<MiniProgressProps>;
+/** Public props for the `BatteryProgress` component. */
 interface BatteryProgressProps {
     value: number;
     max?: number;
@@ -395,6 +420,7 @@ interface BatteryProgressProps {
     showValue?: boolean;
 }
 declare const BatteryProgress: React__default.FC<BatteryProgressProps>;
+/** Public props for the `SegmentedProgress` component. */
 interface SegmentedProgressProps {
     segments: number;
     activeSegments: number;
@@ -403,6 +429,7 @@ interface SegmentedProgressProps {
     size?: "sm" | "md" | "lg";
 }
 declare const SegmentedProgress: React__default.FC<SegmentedProgressProps>;
+/** Public props for the `LoadingProgress` component. */
 interface LoadingProgressProps {
     value: number;
     max?: number;
@@ -415,6 +442,7 @@ interface LoadingProgressProps {
 }
 declare const LoadingProgress: React__default.FC<LoadingProgressProps>;
 
+/** Public props for the `Modal` component. */
 interface ModalProps {
     isOpen: boolean;
     onClose: () => void;
@@ -456,6 +484,7 @@ interface ToastContextType {
     toasts: Toast[];
 }
 declare const useToast: () => ToastContextType;
+/** Public props for the `ToastProvider` component. */
 interface ToastProviderProps {
     children: React__default.ReactNode;
     position?: ToastPosition;
@@ -481,6 +510,7 @@ declare const Tooltip: React$1.ForwardRefExoticComponent<Omit<React$1.HTMLAttrib
 } & React$1.RefAttributes<HTMLElement>>;
 
 type PopoverPlacement = "top" | "bottom" | "left" | "right" | "top-start" | "bottom-start" | "top-end" | "bottom-end";
+/** Public props for the `Popover` component. */
 interface PopoverProps {
     trigger: React$1.ReactElement;
     children: React$1.ReactNode;
@@ -498,6 +528,7 @@ interface PopoverProps {
 }
 declare const Popover: React$1.FC<PopoverProps>;
 
+/** Public props for the `Sheet` component. */
 interface SheetProps {
     open: boolean;
     onOpenChange: (open: boolean) => void;
@@ -516,24 +547,29 @@ interface SheetProps {
     overlayOpacity?: number;
 }
 declare const Sheet: React$1.FC<SheetProps>;
+/** Public props for the `Drawer` component. */
 interface DrawerProps extends Omit<SheetProps, "side"> {
     placement?: "left" | "right";
 }
 declare const Drawer: React$1.FC<DrawerProps>;
+/** Public props for the `SlideOver` component. */
 interface SlideOverProps extends Omit<SheetProps, "side" | "variant"> {
 }
 declare const SlideOver: React$1.FC<SlideOverProps>;
+/** Public props for the `BottomSheet` component. */
 interface BottomSheetProps extends Omit<SheetProps, "side"> {
     snapPoints?: string[];
     defaultSnap?: number;
 }
 declare const BottomSheet: React$1.FC<BottomSheetProps>;
+/** Public props for the `SidebarSheet` component. */
 interface SidebarSheetProps extends Omit<SheetProps, "side" | "variant"> {
     navigation?: React$1.ReactNode;
 }
 declare const SidebarSheet: React$1.FC<SidebarSheetProps>;
 
 type AlertVariant = "default" | "info" | "success" | "warning" | "error";
+/** Public props for the `Alert` component. */
 interface AlertProps {
     title?: string;
     description?: ReactNode;
@@ -548,6 +584,7 @@ interface AlertProps {
 }
 declare const Alert: ({ title, description, variant, className, icon, dismissible, onClose, actions, closeAriaLabel, overflowHidden, }: AlertProps) => react_jsx_runtime.JSX.Element | null;
 
+/** Public props for the `GlobalLoading` component. */
 interface GlobalLoadingProps {
     className?: string;
     backdrop?: boolean;
@@ -559,11 +596,13 @@ interface GlobalLoadingProps {
  * Chỉ cần gắn 1 lần ở root của app
  */
 declare const GlobalLoading: React__default.FC<GlobalLoadingProps>;
+/** Public props for the `PageLoading` component. */
 interface PageLoadingProps {
     message?: string;
     className?: string;
 }
 declare const PageLoading: React__default.FC<PageLoadingProps>;
+/** Public props for the `InlineLoading` component. */
 interface InlineLoadingProps {
     isLoading: boolean;
     text?: string;
@@ -571,6 +610,7 @@ interface InlineLoadingProps {
     size?: "sm" | "md" | "lg";
 }
 declare const InlineLoading: React__default.FC<InlineLoadingProps>;
+/** Public props for the `ButtonLoading` component. */
 interface ButtonLoadingProps {
     isLoading: boolean;
     children: React__default.ReactNode;
@@ -588,6 +628,7 @@ interface BreadcrumbItem {
     }>;
     disabled?: boolean;
 }
+/** Public props for the `Breadcrumb` component. */
 interface BreadcrumbProps {
     items: BreadcrumbItem[];
     className?: string;
@@ -615,7 +656,9 @@ interface Tab {
     target?: React$1.HTMLAttributeAnchorTarget;
     rel?: string;
 }
+/** Public props for the `Tabs` component. */
 interface TabsProps {
+    id?: string;
     tabs: Tab[];
     defaultValue?: string;
     className?: string;
@@ -630,6 +673,7 @@ interface TabsProps {
     animateContent?: boolean;
 }
 declare const Tabs: React$1.FC<TabsProps>;
+/** Public props for the `SimpleTabs` component. */
 interface SimpleTabsProps {
     tabs: Array<{
         label: string;
@@ -640,15 +684,18 @@ interface SimpleTabsProps {
     className?: string;
 }
 declare const SimpleTabs: React$1.FC<SimpleTabsProps>;
+/** Public props for the `PillTabs` component. */
 interface PillTabsProps extends TabsProps {
     contained?: boolean;
 }
 declare const PillTabs: React$1.FC<PillTabsProps>;
+/** Public props for the `VerticalTabs` component. */
 interface VerticalTabsProps extends TabsProps {
     sidebarWidth?: string;
 }
 declare const VerticalTabs: React$1.FC<VerticalTabsProps>;
 
+/** Public props for the `DropdownMenu` component. */
 interface DropdownMenuProps {
     trigger: React__default.ReactElement;
     children?: React__default.ReactNode;
@@ -668,6 +715,7 @@ interface DropdownMenuProps {
     }>;
 }
 declare const DropdownMenu: React__default.FC<DropdownMenuProps>;
+/** Public props for the `DropdownMenuItem` component. */
 interface DropdownMenuItemProps {
     children?: React__default.ReactNode;
     label?: string;
@@ -694,6 +742,7 @@ declare const SelectDropdown: React__default.FC<{
     className?: string;
 }>;
 
+/** Public props for the `Pagination` component. */
 interface PaginationProps {
     page: number;
     totalPages: number;
@@ -719,6 +768,7 @@ interface PaginationProps {
     };
 }
 declare const Pagination: React$1.FC<PaginationProps>;
+/** Public props for the `SimplePagination` component. */
 interface SimplePaginationProps {
     page: number;
     totalPages: number;
@@ -731,6 +781,7 @@ interface SimplePaginationProps {
     pageSize?: number;
 }
 declare const SimplePagination: React$1.FC<SimplePaginationProps>;
+/** Public props for the `CompactPagination` component. */
 interface CompactPaginationProps {
     page: number;
     totalPages: number;
@@ -741,6 +792,7 @@ interface CompactPaginationProps {
 declare const CompactPagination: React$1.FC<CompactPaginationProps>;
 
 type GradientDirection = "to-r" | "to-l" | "to-b" | "to-t" | "to-br" | "to-bl" | "to-tr" | "to-tl";
+/** Public props for the `Section` component. */
 interface SectionProps extends React__default.HTMLAttributes<HTMLElement> {
     children: React__default.ReactNode;
     className?: string;
@@ -766,6 +818,7 @@ interface SectionProps extends React__default.HTMLAttributes<HTMLElement> {
 }
 declare const Section: React__default.ForwardRefExoticComponent<SectionProps & React__default.RefAttributes<HTMLElement>>;
 
+/** Public props for the `ScrollArea` component. */
 interface ScrollAreaProps extends HTMLAttributes<HTMLDivElement> {
     className?: string;
     contentClassName?: string;
@@ -789,6 +842,7 @@ interface OverlayScrollbarBehavior {
     exclude: string;
 }
 
+/** Public props for the `OverlayScrollbarProvider` component. */
 interface OverlayScrollbarProviderProps extends Partial<OverlayScrollbarBehavior> {
     children?: React__default.ReactNode;
     /** @deprecated Global selector scanning is removed. Kept only for backward compatibility. */
@@ -799,6 +853,7 @@ interface UseOverlayScrollbarTargetOptions extends Partial<OverlayScrollbarBehav
 declare function OverlayScrollbarProvider({ enabled, theme, visibility, autoHide, autoHideDelay, dragScroll, clickScroll, overflowX, overflowY, exclude, selector, children, }?: OverlayScrollbarProviderProps): react_jsx_runtime.JSX.Element;
 declare function useOverlayScrollbarTarget<T extends HTMLElement>(targetRef: React__default.RefObject<T | null>, options?: UseOverlayScrollbarTargetOptions): void;
 
+/** Public props for the `OverlayScrollArea` component. */
 interface OverlayScrollAreaProps extends React__default.HTMLAttributes<HTMLDivElement> {
     viewportClassName?: string;
     viewportProps?: React__default.HTMLAttributes<HTMLDivElement>;
@@ -808,6 +863,7 @@ interface OverlayScrollAreaProps extends React__default.HTMLAttributes<HTMLDivEl
 }
 declare const OverlayScrollArea: React__default.ForwardRefExoticComponent<OverlayScrollAreaProps & React__default.RefAttributes<HTMLDivElement>>;
 
+/** Public props for the `DatePicker` component. */
 interface DatePickerProps {
     id?: string;
     value?: Date;
@@ -831,6 +887,7 @@ interface DatePickerProps {
     maxDate?: Date;
 }
 declare const DatePicker: React$1.FC<DatePickerProps>;
+/** Public props for the `DateRangePicker` component. */
 interface DateRangePickerProps {
     id?: string;
     startDate?: Date;
@@ -857,6 +914,7 @@ declare const CompactDatePicker: React$1.FC<{
     className?: string;
 }>;
 
+/** Public props for the `DateTimePicker` component. */
 interface DateTimePickerProps {
     value?: Date;
     onChange: (date: Date | undefined) => void;
@@ -883,6 +941,7 @@ declare const DateTimePicker: React$1.FC<DateTimePickerProps>;
 
 type TimeFormat = "24" | "12";
 type TimePickerVariant = "default" | "compact" | "inline";
+/** Public props for the `TimePicker` component. */
 interface TimePickerProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "onChange"> {
     value?: string;
     defaultValue?: string;
@@ -939,6 +998,7 @@ declare function TimePicker({ value, defaultValue, onChange, placeholder, disabl
 
 type MonthYearPickerVariant = "default" | "compact" | "inline";
 type PickerSize = "sm" | "md" | "lg";
+/** Public props for the `MonthYearPicker` component. */
 interface MonthYearPickerProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "onChange" | "value" | "defaultValue"> {
     /** Current value as Date or {month, year} */
     value?: Date | {
@@ -1026,6 +1086,7 @@ interface CalendarEvent {
     color?: string;
     badge?: string;
 }
+/** Public props for the `Calendar` component. */
 interface CalendarProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "defaultValue" | "value" | "onSelect"> {
     month?: Date;
     defaultMonth?: Date;
@@ -1259,6 +1320,7 @@ type CalendarTimelineAdaptiveSlotWidths = boolean | {
      */
     fillDistribute?: "event" | "all";
 };
+/** Public props for the `CalendarTimeline` component. */
 interface CalendarTimelineProps<TResourceMeta = unknown, TEventMeta = unknown> extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "onChange"> {
     resources: CalendarTimelineResource<TResourceMeta>[];
     events: CalendarTimelineEvent<TEventMeta>[];
@@ -1487,6 +1549,7 @@ type ComboboxOption = string | {
     description?: string;
     disabled?: boolean;
 };
+/** Public props for the `Combobox` component. */
 interface ComboboxProps {
     id?: string;
     options: ComboboxOption[];
@@ -1528,6 +1591,7 @@ interface MultiComboboxOption {
     disabled?: boolean;
     group?: string;
 }
+/** Public props for the `MultiCombobox` component. */
 interface MultiComboboxProps {
     id?: string;
     options: Array<string | MultiComboboxOption>;
@@ -1565,6 +1629,7 @@ interface MultiComboboxProps {
 }
 declare const MultiCombobox: React$1.FC<MultiComboboxProps>;
 
+/** Public props for the `RadioGroup` component. */
 interface RadioGroupProps {
     value?: string;
     defaultValue?: string;
@@ -1581,6 +1646,7 @@ interface RadioGroupProps {
     errorMessage?: string;
 }
 declare const RadioGroup: React$1.ForwardRefExoticComponent<RadioGroupProps & React$1.RefAttributes<HTMLDivElement>>;
+/** Public props for the `RadioGroupItem` component. */
 interface RadioGroupItemProps {
     value: string;
     id?: string;
@@ -1597,6 +1663,7 @@ interface RadioGroupItemProps {
 }
 declare const RadioGroupItem: React$1.ForwardRefExoticComponent<RadioGroupItemProps & React$1.RefAttributes<HTMLButtonElement>>;
 
+/** Public props for the `Slider` component. */
 interface SliderProps extends Omit<React$1.InputHTMLAttributes<HTMLInputElement>, "onChange" | "size"> {
     mode?: "single" | "range";
     value?: number;
@@ -1630,6 +1697,7 @@ interface SliderProps extends Omit<React$1.InputHTMLAttributes<HTMLInputElement>
 }
 declare const Slider: React$1.ForwardRefExoticComponent<SliderProps & React$1.RefAttributes<HTMLInputElement>>;
 
+/** Public props for the `OverlayControls` component. */
 interface OverlayControlsProps {
     mode: "live" | "review";
     value: number;
@@ -1660,70 +1728,140 @@ interface OverlayControlsProps {
 declare function OverlayControls({ mode, value, max, step, onChange, onCommit, playing, onTogglePlay, onGoLive, volume, muted, onVolumeChange, onToggleMute, rate, onChangeRate, onToggleFullscreen, showOnHover, className, showTime, skipSeconds, onSkip, onSeekPreview, autoHide, autoHideDelay, enableKeyboardShortcuts, }: OverlayControlsProps): react_jsx_runtime.JSX.Element;
 
 interface Category {
+    /** Unique category id used for selection and tree relationships. */
     id: number;
+    /** Visible label rendered for this node. */
     name: string;
+    /** Parent category id. Omit or set `null` for a root node. */
     parent_id?: number | null;
+    /** Optional custom icon rendered before the category label. */
     icon?: React__default.ReactNode;
 }
+/**
+ * Override the built-in copy used by {@link CategoryTreeSelect}.
+ * Useful for i18n or product-specific wording.
+ */
 interface CategoryTreeSelectLabels {
-    /** Text shown when no categories available */
+    /** Text shown when no categories are available. */
     emptyText?: string;
-    /** Text shown when categories are selected, receives count as parameter */
+    /** Text shown when categories are selected. Receives the selected count. */
     selectedText?: (count: number) => string;
-    /** Placeholder text for search input (when enabled) */
+    /** Placeholder text for the search input when search is enabled. */
     searchPlaceholder?: string;
-    /** Text shown when search yields no results */
+    /** Text shown when search yields no results. */
     noResultsText?: string;
 }
+/**
+ * Shared props for both single-select and multi-select modes.
+ *
+ * @remarks
+ * Use `defaultExpanded`, `defaultExpandedIds`, or `expandToId` for initial
+ * uncontrolled expand state. If you need to fully control the expanded tree
+ * from the outside, use `expandedIds` together with `onExpandedChange`.
+ */
 interface CategoryTreeSelectBaseProps {
     id?: string;
+    /** Optional field label rendered above the control. */
     label?: string;
+    /** Extra classes for the label element. */
     labelClassName?: string;
+    /** Flat category list. Parent/child relationships are resolved via `parent_id`. */
     categories: Category[];
+    /** Placeholder text when no category is selected. */
     placeholder?: string;
+    /** Disables interaction and fades the control. */
     disabled?: boolean;
+    /** Participate in form-required validation. */
     required?: boolean;
+    /** Visual size of the trigger. */
     size?: "sm" | "md" | "lg";
+    /** Visual style of the trigger. */
     variant?: "default" | "outline" | "ghost" | "filled";
+    /** Show a clear button when a selection exists. */
     allowClear?: boolean;
+    /** External error message. Takes precedence over helper text. */
     error?: string;
+    /** Helper text shown below the field when there is no error. */
     helperText?: string;
-    /** When true, renders as a read-only tree view without select functionality */
+    /** When true, renders as a read-only tree view without selection behavior. */
     viewOnly?: boolean;
-    /** Default expanded state for all nodes */
+    /**
+     * Expand every parent node by default.
+     *
+     * @remarks
+     * This applies to `inline` and `viewOnly` trees. In dropdown mode, branches
+     * still start collapsed unless expanded by other props.
+     */
     defaultExpanded?: boolean;
+    /** Explicit branch ids that should start expanded in uncontrolled mode. */
+    defaultExpandedIds?: number[];
+    /**
+     * Expand the ancestor path so a specific node is visible by default.
+     *
+     * @remarks
+     * The node id itself is also added to the expanded set, which is useful when
+     * `expandToId` points to a parent category.
+     */
+    expandToId?: number | null;
+    /** Controlled expanded branch ids. */
+    expandedIds?: number[];
+    /** Called whenever expand/collapse changes the expanded branch ids. */
+    onExpandedChange?: (expandedIds: number[]) => void;
     /**
      * Enable search input for filtering categories.
      * Default: auto-enabled when `categories.length > 10` (similar to MultiCombobox).
      */
     enableSearch?: boolean;
-    /** i18n labels for localization */
+    /** Replace built-in labels for localization or custom wording. */
     labels?: CategoryTreeSelectLabels;
-    /** When true, render tree directly without dropdown trigger */
+    /** Render the tree directly instead of inside a dropdown trigger. */
     inline?: boolean;
-    /** Callback when a node is clicked (useful for navigation) */
+    /** Called when a node row is clicked. Useful for navigation flows. */
     onNodeClick?: (node: Category) => void;
-    /** Custom class for the tree container */
+    /** Custom class for the outer tree container. */
     className?: string;
-    /** Enable OverlayScrollbars for dropdown tree viewport. Default: false */
+    /** Enable OverlayScrollbars for the dropdown tree viewport. Default: `false`. */
     useOverlayScrollbar?: boolean;
-    /** When true, only leaf nodes can be selected; parent nodes only expand/collapse */
+    /** When true, only leaf nodes can be selected; parent nodes only expand/collapse. */
     leafOnlySelect?: boolean;
 }
+/** Multi-select mode. This is the default when `singleSelect` is omitted. */
 interface CategoryTreeSelectMultiProps extends CategoryTreeSelectBaseProps {
     singleSelect?: false;
+    /** Selected category ids. */
     value?: number[];
+    /** Called with the full selected id list. */
     onChange?: (selectedIds: number[]) => void;
 }
+/** Single-select mode. */
 interface CategoryTreeSelectSingleProps extends CategoryTreeSelectBaseProps {
     singleSelect: true;
+    /** Selected category id or `null` when nothing is selected. */
     value?: number | null;
+    /** Called with the selected id or `null`. */
     onChange?: (selectedId: number | null) => void;
 }
+/** Union of the single-select and multi-select prop shapes. */
 type CategoryTreeSelectProps = CategoryTreeSelectMultiProps | CategoryTreeSelectSingleProps;
+/**
+ * Tree-based category picker with single-select, multi-select, inline, and
+ * read-only modes.
+ *
+ * @example
+ * ```tsx
+ * <CategoryTreeSelect
+ *   categories={categories}
+ *   value={selectedIds}
+ *   onChange={setSelectedIds}
+ *   label="Categories"
+ *   allowClear
+ * />
+ * ```
+ */
 declare function CategoryTreeSelect(props: CategoryTreeSelectProps): react_jsx_runtime.JSX.Element;
 
 type Fit = "cover" | "contain";
+/** Public props for the `SmartImage` component. */
 interface SmartImageProps {
     src: string | undefined | null;
     alt: string;
@@ -1766,6 +1904,7 @@ interface UploadedImage {
     height?: number;
     formattedSize?: string;
 }
+/** Public props for the `ImageUpload` component. */
 interface ImageUploadProps {
     onUpload?: (image: UploadedImage) => void;
     onRemove?: (imageId: string) => void;
@@ -1795,6 +1934,7 @@ interface UploadedFile {
     error?: string;
     formattedSize?: string;
 }
+/** Public props for the `FileUpload` component. */
 interface FileUploadProps {
     /** Callback when a file is uploaded */
     onUpload?: (file: UploadedFile) => void;
@@ -1854,6 +1994,7 @@ interface CarouselEffectOptions {
     stackOffset?: number;
     stackLift?: number;
 }
+/** Public props for the `Carousel` component. */
 interface CarouselProps {
     children: React$1.ReactNode;
     autoScroll?: boolean;
@@ -1881,6 +2022,7 @@ declare function Carousel({ children, autoScroll, autoScrollInterval, animation,
 type IconComponent = React__default.ComponentType<{
     className?: string;
 }>;
+/** Public props for the `FallingIcons` component. */
 interface FallingIconsProps {
     icon?: IconComponent;
     imageUrl?: string;
@@ -1912,6 +2054,7 @@ declare function FallingIcons({ icon: Icon, imageUrl, count, className, areaClas
 
 type Variant$2 = "plain" | "outlined" | "soft" | "bordered" | "card" | "flush" | "striped";
 type Size$1 = "xs" | "sm" | "md" | "lg";
+/** Public props for the `List` component. */
 interface ListProps extends React$1.HTMLAttributes<HTMLUListElement> {
     as?: "ul" | "ol" | "div";
     ordered?: boolean;
@@ -1933,6 +2076,7 @@ interface ListProps extends React$1.HTMLAttributes<HTMLUListElement> {
     /** Clip overflow on the outer list wrapper. Mainly relevant for striped/card-like variants. */
     overflowHidden?: boolean;
 }
+/** Public props for the `ListItem` component. */
 interface ListItemProps extends React$1.HTMLAttributes<HTMLLIElement> {
     as?: "li" | "div" | "a" | "button";
     selected?: boolean;
@@ -1973,6 +2117,7 @@ declare const List: React$1.ForwardRefExoticComponent<ListProps & React$1.RefAtt
 type WatermarkPreset = "confidential" | "draft" | "sample" | "copyright" | "doNotCopy" | "internal";
 type WatermarkPattern = "diagonal" | "grid" | "straight";
 type AnimationVariant = "fade" | "slide" | "scale" | "pulse" | "none";
+/** Public props for the `Watermark` component. */
 interface WatermarkProps extends React$1.HTMLAttributes<HTMLDivElement> {
     text?: string | string[];
     image?: string;
@@ -2025,6 +2170,7 @@ type Variant$1 = "default" | "outlined" | "card" | "minimal" | "modern" | "gradi
 type Size = "sm" | "md" | "lg" | "xl";
 type Mode = "vertical" | "horizontal";
 type LineStyle = "solid" | "dashed" | "dotted";
+/** Public props for the `Timeline` component. */
 interface TimelineProps extends React$1.HTMLAttributes<HTMLDivElement> {
     align?: Align;
     variant?: Variant$1;
@@ -2041,6 +2187,7 @@ interface TimelineProps extends React$1.HTMLAttributes<HTMLDivElement> {
     /** Show connecting line */
     showLine?: boolean;
 }
+/** Public props for the `TimelineItem` component. */
 interface TimelineItemProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "title"> {
     title?: React$1.ReactNode;
     description?: React$1.ReactNode;
@@ -2072,6 +2219,7 @@ declare const Timeline: React$1.ForwardRefExoticComponent<TimelineProps & React$
 type OutputFormat = "hex" | "rgba" | "hsl" | "hsla";
 type ColorPickerSize = "sm" | "md" | "lg";
 type ColorPickerVariant = "default" | "compact" | "full" | "minimal";
+/** Public props for the `ColorPicker` component. */
 interface ColorPickerProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "onChange"> {
     value?: string;
     defaultValue?: string;
@@ -2110,6 +2258,7 @@ interface Song {
     startTime?: number;
     endTime?: number;
 }
+/** Public props for the `MusicPlayer` component. */
 interface MusicPlayerProps {
     playlist?: Song[];
     autoPlay?: boolean;
@@ -2130,6 +2279,7 @@ type ResponsiveConfig = Partial<{
 }>;
 type GridVariant = "default" | "bordered" | "card" | "flat" | "glass";
 type GridAutoFlow = "row" | "column" | "row dense" | "column dense";
+/** Public props for the `Grid` component. */
 interface GridProps extends React__default.HTMLAttributes<HTMLDivElement> {
     /** Number of columns or full template string. Default: 12 (1fr each). */
     columns?: number | string;
@@ -2166,6 +2316,7 @@ interface GridProps extends React__default.HTMLAttributes<HTMLDivElement> {
     /** Apply Card-like outline (rounded + border + bg-card). @deprecated Use variant="card" instead */
     outlined?: boolean;
 }
+/** Public props for the `GridItem` component. */
 interface GridItemProps extends React__default.HTMLAttributes<HTMLDivElement> {
     /** Column span (e.g., 3 => span 3). */
     colSpan?: number | string;
@@ -2196,23 +2347,27 @@ declare const Grid: React__default.ForwardRefExoticComponent<GridProps & React__
     Item: React__default.ForwardRefExoticComponent<GridItemProps & React__default.RefAttributes<HTMLDivElement>>;
 };
 
+/** Public props for the `ClientOnly` component. */
 interface ClientOnlyProps {
     children: React.ReactNode;
     fallback?: React.ReactNode;
 }
 declare function ClientOnly({ children, fallback }: ClientOnlyProps): react_jsx_runtime.JSX.Element;
 
+/** Public props for the `LoadingSpinner` component. */
 interface LoadingSpinnerProps {
     size?: 'sm' | 'md' | 'lg';
     className?: string;
     color?: 'primary' | 'foreground' | 'muted';
 }
 declare const LoadingSpinner: React__default.FC<LoadingSpinnerProps>;
+/** Public props for the `LoadingDots` component. */
 interface LoadingDotsProps {
     className?: string;
     color?: 'primary' | 'foreground' | 'muted';
 }
 declare const LoadingDots: React__default.FC<LoadingDotsProps>;
+/** Public props for the `LoadingBar` component. */
 interface LoadingBarProps {
     progress?: number;
     className?: string;
@@ -2304,6 +2459,7 @@ type DataTableLabels = {
     alignRight?: string;
     noData?: string;
 };
+/** Public props for the `DataTable` component. */
 interface DataTableProps<T> {
     columns: DataTableColumn<T>[];
     data: T[];
@@ -2349,6 +2505,7 @@ interface DataTableProps<T> {
 
 declare function DataTable<T extends Record<string, any>>({ columns, data, rowKey, loading, total, page, pageSize, pageSizeOptions, onQueryChange, caption, toolbar, size, enableColumnVisibilityToggle, enableDensityToggle, enableHeaderAlignToggle, striped, columnDividers, className, storageKey, stickyHeader, maxHeight, horizontalMode, overflowHidden, useOverlayScrollbar, enableHeaderAutoFit, labels, }: DataTableProps<T>): react_jsx_runtime.JSX.Element;
 
+/** Public props for the `Table` component. */
 interface TableProps extends React__default.HTMLAttributes<HTMLTableElement> {
     containerClassName?: string;
     disableContainer?: boolean;
@@ -2356,6 +2513,7 @@ interface TableProps extends React__default.HTMLAttributes<HTMLTableElement> {
     useOverlayScrollbar?: boolean;
 }
 declare const Table: React__default.ForwardRefExoticComponent<TableProps & React__default.RefAttributes<HTMLTableElement>>;
+/** Public props for the `TableHeader` component. */
 interface TableHeaderProps extends React__default.HTMLAttributes<HTMLTableSectionElement> {
     filterRow?: React__default.ReactNode;
 }
@@ -2367,6 +2525,7 @@ declare const TableHead: React__default.ForwardRefExoticComponent<React__default
 declare const TableCell: React__default.ForwardRefExoticComponent<React__default.TdHTMLAttributes<HTMLTableCellElement> & React__default.RefAttributes<HTMLTableCellElement>>;
 declare const TableCaption: React__default.ForwardRefExoticComponent<React__default.HTMLAttributes<HTMLTableCaptionElement> & React__default.RefAttributes<HTMLTableCaptionElement>>;
 
+/** Public props for the `FormWrapper` component. */
 interface FormWrapperProps<T extends FieldValues = FieldValues> {
     children: React$1.ReactNode;
     onSubmit: SubmitHandler<T>;
@@ -2416,6 +2575,7 @@ interface NotificationItem {
     created_at: string;
     metadata?: any;
 }
+/** Public props for the `NotificationModal` component. */
 interface NotificationModalProps {
     isOpen: boolean;
     onClose: () => void;
@@ -2427,6 +2587,7 @@ interface NotificationModalProps {
 declare function NotificationModal({ isOpen, onClose, notification, titleText, openLinkText, closeText }: NotificationModalProps): react_jsx_runtime.JSX.Element | null;
 
 type Variant = "destructive" | "warning" | "info";
+/** Public props for the `AccessDenied` component. */
 interface AccessDeniedProps {
     title?: string;
     description?: string;
@@ -2441,6 +2602,7 @@ interface AccessDeniedProps {
 declare function AccessDenied({ title, description, variant, icon: Icon, className, children, overflowHidden, }: AccessDeniedProps): react_jsx_runtime.JSX.Element;
 
 type ThemeMode = "light" | "dark" | "system";
+/** Public props for the `ThemeToggleHeadless` component. */
 interface ThemeToggleHeadlessProps {
     theme: ThemeMode;
     onChange: (theme: ThemeMode) => void;
@@ -2459,6 +2621,7 @@ interface LanguageOption {
     name: string;
     flag?: string;
 }
+/** Public props for the `LanguageSwitcherHeadless` component. */
 interface LanguageSwitcherHeadlessProps {
     locales: LanguageOption[];
     currentLocale: string;
@@ -2635,6 +2798,7 @@ declare const VARIANT_STYLES_ALERT: {
 
 type Locale = "en" | "vi" | "ko" | "ja";
 type Translations = Record<string, Record<string, string | Record<string, string>>>;
+/** Public props for the `TranslationProvider` component. */
 interface TranslationProviderProps {
     children: React$1.ReactNode;
     /** Current locale. Defaults to "en" */
@@ -2689,6 +2853,7 @@ declare const useUnderverseTranslations: (namespace: string) => (key: string) =>
  */
 declare const useUnderverseLocale: () => Locale;
 
+/** Public props for the `NextIntlAdapter` component. */
 interface NextIntlAdapterProps {
     children: React$1.ReactNode;
     locale?: string | null;
@@ -2784,6 +2949,7 @@ type UEditorLetterSpacingOption = {
     label: string;
     value: string;
 };
+/** Public props for the `UEditor` component. */
 interface UEditorProps {
     content?: string;
     onChange?: (content: string) => void;
@@ -2824,6 +2990,8 @@ declare function prepareUEditorContentForSave({ html, uploadImageForSave, }: {
     uploadImageForSave?: UEditorUploadImageForSave;
 }): Promise<UEditorPrepareContentForSaveResult>;
 
+/** Button component for actions, icon buttons, loading states, and submit flows. */
+
 declare const underverseMessages: {
     readonly en: {
         Common: {
@@ -3876,6 +4044,7 @@ declare const underverseMessages: {
         };
     };
 };
+/** Supported locale keys available in `underverseMessages`. */
 type UnderverseLocale = keyof typeof underverseMessages;
 declare function getUnderverseMessages(locale?: UnderverseLocale): {
     Common: {