@adoptaunabuelo/react-components 0.3.145 → 0.3.147

package/dist/index.d.ts

@@ -9,8 +9,19 @@ import { LocationProps as LocationProps$1 } from '@components/Input/Location/Inp
 
 declare const BreadCrumb: ({ steps, selectedStep, ...restProps }: Props$g) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Step indicator component displaying circular dots to show progress through a multi-step flow.
+ * Highlights the current active step with primary color.
+ *
+ * @example
+ * ```tsx
+ * <BreadCrumb steps={4} selectedStep={1} />
+ * ```
+ */
 interface Props$g extends ComponentPropsWithoutRef<"div"> {
+    /** Current active step index (0-based) */
     selectedStep?: number;
+    /** Total number of steps to display */
     steps: number;
 }
 
@@ -31,49 +42,121 @@ interface ButtonProps$1 extends ComponentPropsWithoutRef<"p"> {
 
 declare const Text: (props: TextProps) => react_jsx_runtime.JSX.Element | null;
 
+/**
+ * Unified typography component that renders headers (h1-h6, d1), paragraphs (p, p2, c1, c2, o1, o2), or button text (b1, b2, b3).
+ * Automatically chooses the correct semantic HTML element based on the `type` prop.
+ *
+ * @example
+ * ```tsx
+ * <Text type="h1" weight="bold">Page Title</Text>
+ * <Text type="p" color={ColorV2.text.neutralMedium}>Body text</Text>
+ * <Text type="b1">Button text</Text>
+ * ```
+ */
 type TextProps = HeaderProps | ParagraphProps | ButtonProps$1;
 
 declare const ProgressBar: (props: Props$f) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Animated progress bar supporting single or multiple progress indicators with optional percentage display.
+ * Smoothly transitions to new values with configurable animation timing.
+ *
+ * @example
+ * ```tsx
+ * <ProgressBar
+ *   progress={75}
+ *   showPercentage
+ *   animationTime={1.5}
+ * />
+ * ```
+ */
 interface Props$f extends ComponentPropsWithoutRef<"div"> {
+    /** Current progress value or array of multiple progress values with optional colors */
     progress: number | Array<{
         value: number;
         color?: string;
     }>;
+    /** Minimum value for progress calculation (default: 0) */
     minValue?: number;
+    /** Maximum value for progress calculation (default: 100) */
     maxValue?: number;
+    /** Bar color (overrides default primary color) */
     color?: string;
+    /** Animation duration in seconds */
     animationTime?: number;
+    /** Delay in seconds before animation starts */
     animationDelay?: number;
+    /** Display percentage badge above progress bar */
     showPercentage?: boolean;
 }
 
 declare const FeedBack: ({ type, text, isVisible, ...props }: FeedBackProps) => react_jsx_runtime.JSX.Element | null;
 
+/**
+ * Toast-style feedback notification with slide-in/out animation.
+ * Auto-dismisses after specified duration. Supports success, error, and custom types.
+ *
+ * @example
+ * ```tsx
+ * <Feedback
+ *   type="success"
+ *   text="Changes saved successfully"
+ *   isVisible={showFeedback}
+ *   closeAfter={5000}
+ *   onClose={() => setShowFeedback(false)}
+ * />
+ * ```
+ */
 interface FeedBackProps extends ComponentPropsWithoutRef<"div"> {
+    /** Controls visibility (triggers show/hide animation) */
     isVisible: boolean;
+    /** Visual variant: `success` (green with check), `error` (red with X), `custom` (use your own icon/color) */
     type: "success" | "error" | "custom";
+    /** Custom icon for `type="custom"` */
     icon?: ReactNode;
+    /** Message text to display */
     text: string;
+    /** Auto-dismiss duration in milliseconds (default: 3000) */
     closeAfter?: number;
+    /** Show manual close button */
     showClose?: boolean;
+    /** Callback fired when dismissed (auto or manual) */
     onClose?: () => void;
 }
 
 declare const Button: ({ design, onSuccess, ...restProps }: ButtonProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Button component with multiple visual variants and built-in loading/success states.
+ *
+ * @example
+ * ```tsx
+ * <Button design="primary" loading={isLoading}>
+ *   Submit
+ * </Button>
+ * ```
+ */
 interface ButtonProps extends ComponentPropsWithoutRef<"button"> {
+    /** Visual variant: `primary` for main actions, `secondary` for less emphasis, `text` for minimal style, `image` for icon-only, `call-to-action` for prominent CTAs */
     design?: "primary" | "secondary" | "text" | "image" | "call-to-action";
+    /** Button size: `normal` (default) or `small` for compact layouts */
     size?: "small" | "normal";
     icon?: react__default.ReactElement;
     iconPosition?: "left" | "right";
+    /** Shows animated loading spinner (Lottie animation) */
     loading?: boolean;
     disabled?: boolean;
+    /** Triggers success animation (Lottie checkmark) */
     success?: boolean;
+    /** Delay in milliseconds before showing loading animation */
     animationDelay?: number;
+    /** Duration in milliseconds for success animation before callback */
     animationTime?: number;
+    /** Time in seconds to display countdown on button */
     countdown?: number;
+    /** Callback fired when success animation completes */
     onSuccess?: (success: boolean) => void;
+    /** Callback fired when countdown reaches zero */
     onCountdownEnd?: () => void;
 }
 
@@ -81,50 +164,114 @@ interface InputStyledProps extends ComponentPropsWithRef<"input"> {
 }
 
 interface InputPrimaryProps extends InputStyledProps {
+    /** Custom React element to display on the left side of the input (e.g., icon, prefix) */
     LeftContent?: ReactElement;
+    /** Custom CSS properties for the outer container wrapper */
     containerStyle?: CSSProperties;
+    /** Error message displayed below the input in red text */
     error?: string | undefined;
     design?: "primary";
 }
 
 interface InputSecondaryProps extends InputStyledProps {
+    /** Custom React element to display on the left side of the input (e.g., icon, prefix) */
     LeftContent?: ReactElement;
+    /** Custom CSS properties for the outer container wrapper */
     containerStyle?: CSSProperties;
+    /** Error message displayed below the input in red text */
     error?: string | undefined;
     design?: "secondary";
 }
 
 interface InputThirdProps extends InputStyledProps {
+    /** Custom React element to display on the left side of the input (e.g., icon, prefix) */
     LeftContent?: ReactElement;
+    /** Custom CSS properties for the outer container wrapper */
     containerStyle?: CSSProperties;
+    /** Error message displayed below the input in red text */
     error?: string | undefined;
     design?: "third";
 }
 
 declare const Input: react.ForwardRefExoticComponent<(Omit<InputPrimaryProps & {
+    /** Input type: determines keyboard type and validation on mobile devices */
     type?: "text" | "email" | "date" | "password" | "time" | "number";
 }, "ref"> | Omit<InputSecondaryProps & {
+    /** Input type: determines keyboard type and validation on mobile devices */
     type?: "text" | "email" | "date" | "password" | "time" | "number";
 }, "ref"> | Omit<InputThirdProps & {
+    /** Input type: determines keyboard type and validation on mobile devices */
     type?: "text" | "email" | "date" | "password" | "time" | "number";
 }, "ref">) & react.RefAttributes<HTMLInputElement>>;
 
+/**
+ * Text input component with three visual design variants.
+ * Supports all native HTML input attributes plus custom styling and error handling.
+ *
+ * @example
+ * ```tsx
+ * <Input
+ *   design="secondary"
+ *   placeholder="Enter your email"
+ *   error="Invalid email format"
+ * />
+ * ```
+ */
 type InputProps = (InputPrimaryProps | InputSecondaryProps | InputThirdProps) & {
+    /** Input type: determines keyboard type and validation on mobile devices */
     type?: "text" | "email" | "date" | "password" | "time" | "number";
 };
 
 declare const InputBirthday: ({ error, onChange, containerStyle, ...restProps }: InputBirthdayProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Birthday input split into three numeric fields (Day/Month/Year).
+ * Auto-focuses next field when complete, validates date with moment.js.
+ *
+ * @example
+ * ```tsx
+ * <InputBirthday
+ *   defaultValue="1990-05-15"
+ *   error={validationError}
+ *   onChange={(date) => setDateOfBirth(date)}
+ * />
+ * ```
+ */
 type InputBirthdayProps = Omit<InputProps, 'onChange'> & {
+    /** Callback with valid Date object when all fields complete. Format for defaultValue: "YYYY-MM-DD" */
     onChange?: (date: Date | ChangeEvent<HTMLInputElement>) => void;
 };
 
 declare const InputChat: (props: InputChatProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Chat input with text messaging and voice recording capabilities.
+ * Features waveform visualization during recording and optional attachment menu.
+ *
+ * @example
+ * ```tsx
+ * <InputChat
+ *   placeholder="Type a message..."
+ *   options={[
+ *     { id: "photo", label: "Photo", icon: <Camera /> },
+ *     { id: "file", label: "File", icon: <Paperclip /> }
+ *   ]}
+ *   onOptionClick={(id) => handleAttachment(id)}
+ *   onSend={(data) => {
+ *     if (data.text) sendTextMessage(data.text);
+ *     if (data.media) sendAudioMessage(data.media.base64);
+ *   }}
+ * />
+ * ```
+ */
 interface InputChatProps extends ComponentPropsWithoutRef<"input"> {
+    /** Shows loading animation, disables input */
     loading?: boolean;
+    /** Attachment menu options (shows Plus icon button) */
     options?: Array<optionType>;
+    /** Callback when attachment menu item is clicked */
     onOptionClick?: (id: string) => void;
+    /** Callback when message is sent (Enter key or Send button). Audio is converted to base64 WAV format */
     onSend?: (data: {
         text?: string;
         media?: {
@@ -141,32 +288,81 @@ type optionType = {
 
 declare const InputCode: (props: InputCodeProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * 6-digit verification code input with monospace font and letter spacing.
+ * Auto-blurs and triggers callback when all 6 digits are entered.
+ *
+ * @example
+ * ```tsx
+ * <InputCode
+ *   autoFocus
+ *   error={codeError}
+ *   loading={isVerifying}
+ *   onChange={(code) => verifyCode(code)}
+ * />
+ * ```
+ */
 interface InputCodeProps {
     style?: CSSProperties;
     containerStyle?: CSSProperties;
     autoFocus?: boolean;
     error?: string;
     loading?: boolean;
+    /** Callback fired when 6 digits are entered (input auto-blurs) */
     onChange?: (code: string) => void;
 }
 
 declare const InputDateRange: (props: InputDateRangeProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Date range picker powered by react-dates (Airbnb).
+ * Uses moment.js for date handling with Spanish localization.
+ *
+ * @example
+ * ```tsx
+ * <InputDateRange
+ *   startDate={startDate}
+ *   endDate={endDate}
+ *   onChange={({ startDate, endDate }) => {
+ *     setStartDate(startDate);
+ *     setEndDate(endDate);
+ *   }}
+ *   isOutsideRange={(date) => date.isBefore(moment())}
+ * />
+ * ```
+ */
 interface InputDateRangeProps {
     style?: CSSProperties;
     startDate: moment.Moment | null;
     endDate: moment.Moment | null;
     focus?: boolean;
+    /** Callback fired when either date changes */
     onChange: (data: {
         startDate: moment.Moment | null;
         endDate: moment.Moment | null;
     }) => void;
+    /** Optional function to disable specific dates (return true to disable) */
     isOutsideRange?: (date: moment.Moment) => boolean;
 }
 
 declare const InputImage: (props: InputImageProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Image upload with crop, compression, and webcam capture.
+ * Uses react-image-crop for 1:1 aspect ratio cropping and compressorjs for compression.
+ *
+ * @example
+ * ```tsx
+ * <InputImage
+ *   options={["camera", "library"]}
+ *   maxHeight={1200}
+ *   maxWidth={1200}
+ *   onChange={(base64Image) => setProfilePhoto(base64Image)}
+ * />
+ * ```
+ */
 interface InputImageProps {
+    /** Image source options (shows modal on mobile if multiple). Default: ["library"] */
     options?: Array<"camera" | "library">;
     icon?: ReactElement;
     style?: CSSProperties;
@@ -174,32 +370,65 @@ interface InputImageProps {
     buttonText?: string;
     previewStyle?: CSSProperties;
     label?: string;
+    /** Max height in pixels for compressed image */
     maxHeight?: number;
+    /** Max width in pixels for compressed image */
     maxWidth?: number;
+    /** Skip crop UI, immediately compress and return image */
     hideCrop?: boolean;
+    /** Callback with base64-encoded WebP image */
     onChange?: (image: string | ArrayBuffer | null) => void;
 }
 
 declare const InputLocation: ({ isLoaded, isForm, searchTypes, searchFields, onLocationChange, ...restProps }: InputLocationProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Location autocomplete input powered by Google Maps Places API.
+ * Debounced search (500ms) with structured address parsing in Spanish.
+ *
+ * @example
+ * ```tsx
+ * <InputLocation
+ *   isLoaded={isGoogleMapsLoaded}
+ *   placeholder="Introduce tu dirección"
+ *   searchTypes={["address"]}
+ *   searchFields={["geometry", "address_components"]}
+ *   onLocationChange={(location) => {
+ *     console.log(location.address);
+ *     console.log(location.location); // { lat, lng }
+ *   }}
+ * />
+ * ```
+ */
 type InputLocationProps = InputProps & {
+    /** If true, only shows route + number in input after selection */
     isForm?: boolean;
+    /** Must be true when Google Maps API is loaded */
     isLoaded: boolean;
+    /** Google Places API search types. Default: ["address"] */
     searchTypes?: string[];
+    /** Google Places API fields to fetch. Default: ["geometry", "address_components"] */
     searchFields?: string[];
+    /** Callback with parsed location data */
     onLocationChange?: (result: LocationProps) => void;
 };
 interface LocationProps {
+    /** Full formatted address string */
     address?: string;
+    /** Short address (city, province, country) */
     sortAddress?: string;
+    /** Street name */
     route?: string;
+    /** Street number */
     routeNumber?: string;
     routeInfo?: string;
     city?: string;
     province?: string;
     zipCode?: string;
     country?: string;
+    /** ISO country code (e.g., "ES") */
     shortCountry?: string;
+    /** Coordinates { lat, lng } */
     location?: google.maps.LatLngLiteral;
     timeZone?: string;
 }
@@ -214,80 +443,203 @@ interface CountryProps {
 
 declare const InputPhone: (props: InputPhoneProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Phone input with country selector and validation using google-libphonenumber.
+ * Validates phone format for the selected country region.
+ *
+ * @example
+ * ```tsx
+ * <InputPhone
+ *   country="ES"
+ *   countryOptions={countryList}
+ *   onPhoneChange={({ country, value, isValid }) => {
+ *     if (isValid) setPhoneNumber(country + value);
+ *   }}
+ * />
+ * ```
+ */
 type InputPhoneProps = InputProps & {
+    /** ISO country code (e.g., "ES") to pre-select */
     country?: string;
+    /** Array of country options with prefix and countryCode */
     countryOptions?: CountryProps[];
+    /** Callback fired on input change or country change with validation status */
     onPhoneChange?: (item: {
+        /** Country prefix (e.g., "+34") */
         country: string;
+        /** Phone number without prefix */
         value?: string | number;
+        /** Whether phone is valid for selected country */
         isValid: boolean;
     }) => void;
 };
 
 declare const InputRange: (props: InputRangeProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Range slider with heart icon thumb and optional milestone markers ("presents").
+ * Milestones animate with Lottie pop effect when value reaches them.
+ *
+ * @example
+ * ```tsx
+ * <InputRange
+ *   min={0}
+ *   max={100}
+ *   unit="€"
+ *   value={currentValue}
+ *   presents={[
+ *     { value: 25, icon: Gift, color: "#ccc", colorSuccess: "#0088ff", onClick: () => alert("25 reached!") },
+ *     { value: 50, icon: Star, color: "#ccc", colorSuccess: "#0088ff" }
+ *   ]}
+ *   onChange={(e) => setValue(parseInt(e.target.value))}
+ * />
+ * ```
+ */
 interface InputRangeProps extends ComponentPropsWithoutRef<"input"> {
+    /** Color for filled portion of slider track */
     lineColor?: string;
+    /** Color for unfilled portion of slider track */
     backgroundColor?: string;
+    /** Color for heart icon thumb */
     thumbColor?: string;
     min?: number;
     max?: number;
+    /** Unit label shown at min/max (e.g., "€", "kg") */
     unit?: string;
+    /** Hide floating value tooltip above thumb */
     hideRange?: boolean;
+    /** Hide min/max labels below slider */
     hideLabels?: boolean;
+    /** Milestone markers with Lottie animation when reached */
     presents?: {
+        /** Value at which to show marker */
         value: number;
+        /** Lucide icon component */
         icon: React.ComponentType<{
             height?: number;
             width?: number;
             color?: string;
         }>;
+        /** Color when milestone not reached */
         color: string;
+        /** Color when milestone reached (slider value >= milestone value) */
         colorSuccess: string;
+        /** Optional callback when marker is clicked */
         onClick?: () => void;
     }[];
 }
 
 declare const InputPrice: (props: InputPriceProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Price selector with predefined options in horizontal scroll and optional custom input.
+ * Auto-centers selected option, validates minimum price. Spanish number formatting.
+ *
+ * @example
+ * ```tsx
+ * <InputPrice
+ *   options={[
+ *     { price: 10, data: [{ title: "1 coffee", icon: "Coffee" }] },
+ *     { price: 25, data: [{ title: "3 coffees", icon: "Coffee" }] },
+ *     { price: 50 }
+ *   ]}
+ *   currency="€"
+ *   label="Equivale a {{value}} cafés"
+ *   labelValueConversion={0.1}
+ *   defaultOption={25}
+ *   onChange={(price) => setDonationAmount(price)}
+ * />
+ * ```
+ */
 type InputPriceProps = {
     style?: CSSProperties;
     containerStyle?: CSSProperties;
+    /** Predefined price options (scrollable horizontally) */
     options: {
         price: number;
+        /** Optional feature list shown below price with icons */
         data?: {
             title: string;
+            /** Lucide icon name (e.g., "Check", "Coffee") */
             icon?: string;
         }[];
     }[];
+    /** Floating label above options. Use {{value}} for dynamic calculation */
     label?: string;
+    /** Multiplier for {{value}} in label (e.g., 0.1 converts 100€ to "10 coffees") */
     labelValueConversion?: number;
+    /** Currency symbol (e.g., "€", "$") */
     currency: string;
+    /** Pre-select an option by price */
     defaultOption?: number;
+    /** Hide custom amount input field */
     hideCustomAmount?: boolean;
+    /** Custom element shown below custom amount input */
     customAmountData?: React.ReactElement;
+    /** Callback with selected/entered price. Validates minimum from first option */
     onChange?: (value: number) => void;
 };
 
 declare const Select: (props: Props$e) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Dropdown select component with icons and keyboard-friendly navigation.
+ * Auto-closes when clicking outside. Supports controlled and uncontrolled modes.
+ *
+ * @example
+ * ```tsx
+ * <Select
+ *   id="language-select"
+ *   options={[
+ *     { label: "English", icon: <FlagIcon /> },
+ *     { label: "Spanish", icon: <FlagIcon /> }
+ *   ]}
+ *   selectedItem={currentLanguage}
+ *   onChange={(option) => setLanguage(option)}
+ * />
+ * ```
+ */
 interface Props$e extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
+    /** Unique identifier required for click-outside detection */
     id: string;
+    /** Custom styles for the dropdown options container */
     optionStyle?: CSSProperties;
+    /** Hide the selected item label (icon-only mode) */
     hideTitle?: boolean;
+    /** Array of selectable options */
     options: Array<OptionProps$5>;
+    /** Current selected option (controlled component) */
     selectedItem?: OptionProps$5;
+    /** Callback fired when selection changes */
     onChange?: (option: OptionProps$5) => void;
 }
 interface OptionProps$5 {
+    /** Optional icon displayed before label */
     icon?: React.ReactElement;
+    /** Display text for the option */
     label: string;
 }
 
 declare const SearchBar: (props: Props$d) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Search input with magnifying glass icon. Supports two sizes and visual designs.
+ * Auto-focuses on click and changes style on interaction.
+ *
+ * @example
+ * ```tsx
+ * <SearchBar
+ *   type="big"
+ *   design="primary"
+ *   placeholder="Search..."
+ *   onChange={(e) => handleSearch(e.target.value)}
+ * />
+ * ```
+ */
 interface Props$d extends ComponentPropsWithoutRef<"input"> {
+    /** Size variant: `big` (48px height) or `small` (38px height) */
     type?: "big" | "small";
+    /** Visual design: `primary` (gray background) or `secondary` (white with border) */
     design?: "primary" | "secondary";
 }
 
@@ -315,59 +667,141 @@ interface ModalRef {
 
 declare const ModalComponent: react.ForwardRefExoticComponent<ModalProps & react.RefAttributes<ModalRef>>;
 
+/**
+ * Modal dialog component with three display modes: default, form, and web.
+ * Use `type="form"` with `options` for structured form layouts, or `type="web"` with `url` to embed external content.
+ *
+ * @example
+ * ```tsx
+ * <Modal
+ *   type="form"
+ *   isVisible={isOpen}
+ *   options={[
+ *     { id: "name", title: "Name", Data: <Input /> },
+ *     { id: "separator" }
+ *   ]}
+ * />
+ * ```
+ */
 interface ModalProps extends ModalPrimaryProps {
+    /** Array of form field configurations for `type="form"`. Each item creates a labeled row or separator. */
     options?: Array<{
         id: string;
         title?: string;
         Data?: React.ReactElement;
         hidden?: boolean;
     }>;
+    /** External URL to display in an iframe when `type="web"` */
     url?: string;
 }
 
 declare const MenuList: react.ForwardRefExoticComponent<MenuProps & react.RefAttributes<MenuRef>>;
 
+/**
+ * Dropdown menu component with customizable positioning and icon trigger.
+ * Automatically closes when clicking outside. Supports both predefined options and custom children.
+ *
+ * @example
+ * ```tsx
+ * <Menu
+ *   id="actions-menu"
+ *   position="bottom-right"
+ *   options={[
+ *     { id: "edit", label: "Edit", icon: <EditIcon /> },
+ *     { id: "delete", label: "Delete", labelColor: "red" }
+ *   ]}
+ *   onClick={(option) => handleAction(option.id)}
+ * />
+ * ```
+ */
 interface MenuProps {
+    /** Unique identifier required for click-outside detection */
     id: string;
     style?: CSSProperties;
+    /** Custom styles for the dropdown menu container */
     menuStyle?: CSSProperties;
+    /** Icon for the button trigger (lowercase, used with Button component) */
     icon?: React.ReactElement;
+    /** Icon element for custom trigger (uppercase, replaces Button) */
     Icon?: React.ReactElement;
+    /** Positioning of the dropdown relative to the trigger button */
     position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Custom content to display in menu (alternative to options) */
     children?: React.ReactNode;
+    /** Array of menu items with labels and icons */
     options?: Array<OptionsProps>;
+    /** Callback fired when menu visibility changes */
     onChange?: (visible: boolean) => void;
+    /** Callback fired when a menu option is clicked */
     onClick?: (option: OptionsProps) => void;
 }
 interface OptionsProps {
     id: string;
     label: string;
+    /** Custom text color for the label */
     labelColor?: string;
     icon?: React.ReactElement;
 }
 interface MenuRef {
+    /** Programmatically close the menu */
     close: () => void;
 }
 
 declare const Label: (props: Props$c) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Label/badge component with status-aware coloring and two visual types.
+ * Automatically applies predefined colors for common status values (e.g., "pending", "active", "canceled").
+ *
+ * @example
+ * ```tsx
+ * <Label type="label" text="active" />
+ * <Label type="chip" size="big" text="Pending" />
+ * <Label text="done" icon={<CheckIcon />} />
+ * ```
+ */
 interface Props$c extends ComponentPropsWithoutRef<"div"> {
+    /** Text to display. For predefined status values, color is automatically applied. */
     text: string;
     disabled?: boolean;
+    /** Visual variant: `label` for badges, `chip` for rounded buttons */
     type?: "label" | "chip";
+    /** Size variant for chips: `big` (full text), `small` (initials only), `selector` (bordered) */
     size?: "big" | "small" | "selector";
+    /** Optional icon displayed before the text */
     icon?: ReactElement;
+    /** Custom background color (overrides automatic status colors) */
     backgroundColor?: string;
+    /** Custom text color (overrides automatic status colors) */
     color?: string;
 }
 
 declare const Avatar: (props: Props$b) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Circular avatar component supporting images, initials, and file upload.
+ * Click to view full-size image or to upload new one when editable.
+ *
+ * @example
+ * ```tsx
+ * <Avatar
+ *   icon={userImageUrl}
+ *   name="John Doe"
+ *   editable
+ *   onChange={(file) => uploadAvatar(file)}
+ * />
+ * ```
+ */
 interface Props$b extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
+    /** Image URL to display */
     icon?: string;
+    /** User name (displays first letter as fallback when no icon) */
     name?: string;
+    /** Enable file upload on click (accepts jpg, jpeg, png, gif) */
     editable?: boolean;
+    /** Enable click to view full-size image in modal */
     clickable?: boolean;
+    /** Callback fired when new image is selected, receives base64-encoded file */
     onChange?: (file: string | ArrayBuffer | null) => void;
 }
 
@@ -455,40 +889,94 @@ type CheckboxOption = {
     error?: boolean;
     [key: string]: string | React.ReactElement | boolean | undefined;
 };
+/**
+ * Checkbox list component supporting single or multiple selection modes.
+ * Renders a collection of checkboxes with optional labels, icons, and custom elements.
+ *
+ * @example
+ * ```tsx
+ * <CheckboxList
+ *   type="multiple"
+ *   options={[
+ *     { id: "1", label: "Option 1" },
+ *     { id: "2", label: "Option 2", sublabel: "Description" }
+ *   ]}
+ *   onChange={(selected) => console.log(selected)}
+ * />
+ * ```
+ */
 interface Props$a {
     style?: CSSProperties;
+    /** Custom styles applied to each individual checkbox element */
     elementStyle?: CSSProperties;
     options: Array<CheckboxOption>;
+    /** Pre-selected options (controlled component pattern) */
     selectedOptions?: Array<{
         id: string;
     }>;
+    /** Height in pixels for each checkbox */
     height?: number;
+    /** Width in pixels for each checkbox */
     width?: number;
+    /** Selection mode: `single` for radio-like behavior, `multiple` for checkboxes */
     type: "single" | "multiple";
+    /** Callback fired when selection changes, receives array of selected options */
     onChange?: (result: Array<CheckboxOption>) => void;
+    /** Position of the checkbox indicator relative to content */
     position?: "left" | "right";
+    /** Show avatar-style circular checkboxes */
     avatarEnabled?: boolean;
+    /** Visual shape of the checkbox indicator */
     shape?: "circle" | "square";
 }
 
 declare const Dropdown: (props: Props$9) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Dropdown select with optional search, multi-select, and icon support.
+ * Auto-closes when clicking outside. Displays selected items as comma-separated text.
+ *
+ * @example
+ * ```tsx
+ * <Dropdown
+ *   id="category-dropdown"
+ *   placeholder="Select categories"
+ *   type="multiple"
+ *   options={categories}
+ *   selectedOptions={selected}
+ *   onSearchChange={(text) => filterOptions(text)}
+ *   onChange={(items) => setSelected(items)}
+ * />
+ * ```
+ */
 interface Props$9 {
+    /** Unique identifier required for click-outside detection */
     id: string;
     style?: CSSProperties;
+    /** Custom styles for the dropdown menu container */
     menuStyle?: CSSProperties;
+    /** Custom styles for individual option items */
     optionStyle?: CSSProperties;
+    /** Array of selectable options */
     options: Array<OptionProps$4>;
+    /** Placeholder text shown when nothing is selected */
     placeholder: string;
+    /** Currently selected options (controlled component) */
     selectedOptions?: Array<OptionProps$4>;
+    /** Selection mode: `single` for one item, `multiple` for checkboxes */
     type?: "single" | "multiple";
+    /** Position of dropdown menu relative to trigger */
     menuPosition?: "bottom" | "top";
+    /** Callback fired when selection changes */
     onChange?: (a: Array<OptionProps$4>) => void;
+    /** Callback fired when search input changes, enables search functionality */
     onSearchChange?: (text: string) => void;
 }
 interface OptionProps$4 {
     id: string;
+    /** Display text for the option */
     title?: string;
+    /** Optional icon displayed before title */
     icon?: React.ReactElement;
 }
 
@@ -516,88 +1004,214 @@ declare const TextArea: (props: TextAreaDefaultProps | TextAreaEditorProps) => r
 
 declare const RadioButtonList: (props: Props$8) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Radio button list supporting single or multiple selection.
+ * Each option can contain any React content (text, images, custom components).
+ *
+ * @example
+ * ```tsx
+ * <RadioButtonList
+ *   type="single"
+ *   options={[
+ *     { id: "1", children: <div>Option 1</div>, selected: true },
+ *     { id: "2", children: <div>Option 2</div> }
+ *   ]}
+ *   onChange={(selected) => console.log(selected)}
+ * />
+ * ```
+ */
 interface Props$8 {
+    /** Array of radio button options with custom content */
     options: Array<OptionProps$3>;
+    /** Selection mode: `single` for radio behavior, `multiple` for checkboxes */
     type: "single" | "multiple";
     style?: CSSProperties;
+    /** Custom styles applied to each radio button cell */
     cellStyle?: CSSProperties;
+    /** Callback fired when selection changes, receives array of selected options */
     onChange?: (data: Array<OptionProps$3>) => void;
 }
 interface OptionProps$3 {
     id: string;
+    /** Custom React content to display in the radio button */
     children: React.ReactNode;
+    /** Initial selected state */
     selected?: boolean;
 }
 
 declare const CellSelector: (props: Props$7) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Grid of selectable cells with icons, titles, and optional subtitles.
+ * Supports single or multiple selection with visual feedback and hover states.
+ *
+ * @example
+ * ```tsx
+ * <CellSelector
+ *   type="multiple"
+ *   options={[
+ *     { id: "1", title: "Option 1", icon: <Icon />, subtitle: "Description" },
+ *     { id: "2", title: "Option 2", icon: <Icon />, disabled: true }
+ *   ]}
+ *   selectedOptions={selected}
+ *   onChange={(items) => setSelected(items)}
+ * />
+ * ```
+ */
 interface Props$7 {
     style?: CSSProperties;
+    /** Custom styles applied to each cell */
     cellStyle?: CSSProperties;
+    /** Array of selectable cell options */
     options: Array<OptionProps$2>;
+    /** Currently selected options (controlled component) */
     selectedOptions?: Array<OptionProps$2>;
+    /** Selection mode: `single` for radio behavior, `multiple` for checkboxes */
     type?: "single" | "multiple";
+    /** Callback fired when selection changes, receives array of selected options */
     onChange?: (array: Array<OptionProps$2>) => void;
+    /** Callback fired when individual cell is clicked */
     onClick?: (item: OptionProps$2) => void;
+    /** Visual design variant */
     design?: "design1" | "design2";
 }
 interface OptionProps$2 {
     id: string;
+    /** Main title displayed in the cell */
     title: string;
+    /** Optional subtitle displayed below the cell */
     subtitle?: string;
+    /** Icon displayed at the top of the cell */
     icon?: ReactElement;
+    /** Disables cell interaction and applies opacity */
     disabled?: boolean;
 }
 
 declare const Tabs: (props: Props$6) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Tab navigation component with two visual designs.
+ * Primary design shows underline indicator, secondary design shows rounded background.
+ *
+ * @example
+ * ```tsx
+ * <Tabs
+ *   design="secondary"
+ *   options={[
+ *     { id: "1", title: "Overview" },
+ *     { id: "2", title: "Details" }
+ *   ]}
+ *   selectedOption={currentTab}
+ *   onChange={(tab) => setCurrentTab(tab)}
+ * />
+ * ```
+ */
 interface Props$6 {
     style?: CSSProperties;
+    /** Custom styles for individual tab cells */
     cellStyle?: CSSProperties;
+    /** Custom styles for tab text labels */
     textStyle?: CSSProperties;
+    /** Background color for selected tab (secondary design) */
     cellColor?: string;
+    /** Text color for selected tab */
     textColor?: string;
+    /** Background color for the entire tabs container */
     backgroundColor?: string;
+    /** Array of tab options */
     options: Array<OptionProps$1>;
+    /** Currently selected tab (controlled component) */
     selectedOption?: OptionProps$1;
+    /** Visual design: `primary` (underline) or `secondary` (rounded background) */
     design?: "primary" | "secondary";
+    /** Callback fired when tab selection changes */
     onChange?: (option: OptionProps$1) => void;
 }
 interface OptionProps$1 {
     id: string;
+    /** Display text for the tab */
     title: string;
 }
 
 declare const Payout: react.ForwardRefExoticComponent<PayoutProps & react.RefAttributes<PayoutRef>>;
 
+/**
+ * Stripe payment method setup component supporting card and SEPA direct debit.
+ * Handles 3D Secure authentication flow in modal. Requires Stripe publishable key.
+ *
+ * @example
+ * ```tsx
+ * const payoutRef = useRef<PayoutRef>(null);
+ *
+ * <Payout
+ *   ref={payoutRef}
+ *   stripeKey={process.env.STRIPE_KEY}
+ *   paymentOption="card"
+ *   design="secondary"
+ *   onLoading={(loading) => setIsLoading(loading)}
+ *   onSetupConfirmed={() => handleSuccess()}
+ * />
+ *
+ * // Get payment method
+ * const method = await payoutRef.current?.getPaymentMethod();
+ * ```
+ */
 interface PayoutProps {
     style?: CSSProperties;
+    /** Stripe publishable API key (starts with pk_) */
     stripeKey: string;
+    /** 3D Secure confirmation URL from Stripe setup intent */
     stripeConfirmUrl?: string;
+    /** Payment method type: credit/debit card or SEPA direct debit */
     paymentOption: "sepa_debit" | "card";
+    /** Custom styles for the card input form */
     cardStyle?: CSSProperties;
     error?: boolean;
+    /** Pre-filled user data (email required for SEPA) */
     userData?: {
         email?: string;
     };
+    /** Visual design variant */
     design?: "primary" | "secondary";
+    /** Custom placeholder for name input */
     placeholderName?: string;
+    /** Custom placeholder for email input */
     placeholderEmail?: string;
+    /** Callback fired when 3D Secure authentication completes successfully */
     onSetupConfirmed?: () => void;
+    /** Callback fired when loading state changes */
     onLoading?: (a: boolean) => void;
 }
 interface PayoutRef {
+    /** Collects payment method from Stripe and returns payment method object */
     getPaymentMethod: () => Promise<PaymentMethod | undefined>;
 }
 
 declare const SwitchTag: (props: Props$5) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Icon-based toggle switch for switching between 2+ options.
+ * Displays icons in a pill-shaped container with active state highlighting.
+ *
+ * @example
+ * ```tsx
+ * <SwitchTag
+ *   options={[
+ *     { id: "grid", icon: <GridIcon /> },
+ *     { id: "list", icon: <ListIcon /> }
+ *   ]}
+ *   onChange={(option) => setViewMode(option.id)}
+ * />
+ * ```
+ */
 interface Props$5 {
     style?: CSSProperties;
+    /** Array of icon options (automatically colors icons based on selection) */
     options: Array<{
         id: string;
         icon: react__default.ReactElement;
     }>;
+    /** Callback fired when option changes, receives selected option */
     onChange?: (option: {
         id: string;
         icon: react__default.ReactElement;
@@ -606,78 +1220,213 @@ interface Props$5 {
 
 declare const Pagination: (props: Props$4) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Pagination control with first/previous/next/last navigation buttons.
+ * Displays current page number and total pages (e.g., "1 de 5").
+ *
+ * @example
+ * ```tsx
+ * <Pagination
+ *   length={100}
+ *   rowsPerPage={10}
+ *   start={0}
+ *   onChange={(page) => fetchData(page)}
+ * />
+ * ```
+ */
 interface Props$4 {
     style?: CSSProperties;
+    /** Initial/controlled page index (0-based) */
     start?: number;
+    /** Total number of items to paginate */
     length: number;
+    /** Number of items to display per page */
     rowsPerPage: number;
+    /** Callback fired when page changes, receives new page index (0-based) */
     onChange?: (page: number) => void;
 }
 
 declare const Countdown: (props: Props$3) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Countdown timer displaying human-readable time remaining or elapsed.
+ * Auto-warns with red background when less than 2 hours remain.
+ *
+ * @example
+ * ```tsx
+ * <Countdown
+ *   toDate={new Date("2024-12-31")}
+ *   color={ColorV2.surface.primary}
+ *   textColor={ColorV2.text.white}
+ * />
+ * // Shows: "3 días restantes" or "2 horas de retraso"
+ * ```
+ */
 interface Props$3 extends ComponentPropsWithoutRef<"div"> {
+    /** Target date to count down to (or count up from if past) */
     toDate: Date;
+    /** Background color (overridden by warning red when <2h remain) */
     color?: string;
+    /** Text and icon color (overridden by white when warning) */
     textColor?: string;
 }
 
 declare const TagSelector: (props: Props$2) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Tag selector component for single or multiple selection of options.
+ * Renders clickable tags with optional subtitles in a flex-wrap layout.
+ *
+ * @example
+ * ```tsx
+ * <TagSelector
+ *   type="multiple"
+ *   options={[
+ *     { id: "1", title: "React" },
+ *     { id: "2", title: "TypeScript", subtitle: "Recommended" }
+ *   ]}
+ *   optionsSelected={selectedTags}
+ *   onChange={(tags) => setSelectedTags(tags)}
+ * />
+ * ```
+ */
 interface Props$2 {
+    /** Selection mode: `single` for radio-like, `multiple` for multi-select */
     type?: "multiple" | "single";
     style?: CSSProperties;
+    /** Available tag options to display */
     options: Array<OptionProps>;
+    /** Pre-selected options (controlled component pattern) */
     optionsSelected?: Array<OptionProps>;
+    /** Callback fired when selection changes, receives array of selected options */
     onChange?: (selection: Array<OptionProps>) => void;
+    /** When true, disables click interactions (display only) */
     onlyVisual?: boolean;
+    /** Visual design variant */
     design?: "design1" | "design2";
 }
 interface OptionProps {
     id: string;
+    /** Main text displayed on the tag */
     title: string;
+    /** Optional secondary text below the title */
     subtitle?: string;
     style?: react__default.CSSProperties;
 }
 
 declare const FAQs: (props: Props$1) => react_jsx_runtime.JSX.Element;
 
+/**
+ * FAQ accordion component with expandable/collapsible question-answer pairs.
+ * Only one question can be expanded at a time.
+ *
+ * @example
+ * ```tsx
+ * <FAQs
+ *   options={[
+ *     {
+ *       id: "1",
+ *       title: "How do I get started?",
+ *       description: "To get started, simply..."
+ *     }
+ *   ]}
+ *   onClick={(index) => trackFaqClick(index)}
+ * />
+ * ```
+ */
 interface Props$1 {
     style?: CSSProperties;
+    /** Array of FAQ items with question and answer */
     options: Array<{
         id: string;
+        /** Question text (always visible) */
         title: string;
+        /** Answer text (visible when expanded) */
         description: string;
     }>;
+    /** Callback fired when FAQ item is clicked, receives item index */
     onClick?: (index: number) => void;
 }
 
 declare function Counter(props: Props): react_jsx_runtime.JSX.Element;
 
+/**
+ * Animated flip-clock style counter that animates from zero to the target amount.
+ * Each digit flips individually with a smooth animation effect.
+ *
+ * @example
+ * ```tsx
+ * <Counter
+ *   amount={12345}
+ *   height={60}
+ *   width={40}
+ *   fontSize={32}
+ * />
+ * ```
+ */
 interface Props {
+    /** Height in pixels for each digit block */
     height: number;
+    /** Width in pixels for each digit block */
     width: number;
+    /** Target number to count up to (animates from amount-10 or 0) */
     amount: number;
+    /** Text color for the digits */
     color?: string;
+    /** Background color for each digit block */
     backgroundColor?: string;
+    /** Border/divider color between digit segments */
     borderColor?: string;
+    /** Font size in pixels for the numbers */
     fontSize?: number;
 }
 
 declare const Stamp: (props: StampProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Decorative postage stamp component with perforated edges.
+ * Displays an emoji icon and title. Responsive sizing for mobile.
+ *
+ * @example
+ * ```tsx
+ * <Stamp
+ *   icon="🎉"
+ *   title="Celebration"
+ *   backgroundColor={ColorV2.surface.greenSoft}
+ * />
+ * ```
+ */
 interface StampProps {
     style?: CSSProperties;
+    /** Emoji or single character to display (rendered large) */
     icon: string;
+    /** Text label below the icon (truncates with ellipsis) */
     title: string;
+    /** Background color for the icon area */
     backgroundColor: string;
 }
 
 declare const Switch: (props: SwitchProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Toggle switch component with sliding animation and checkmark indicator.
+ * Changes color and position when toggled on/off.
+ *
+ * @example
+ * ```tsx
+ * <Switch
+ *   active={isEnabled}
+ *   color={ColorV2.surface.primary}
+ *   onChange={(on) => setIsEnabled(on)}
+ * />
+ * ```
+ */
 interface SwitchProps {
+    /** Current state (controlled component) */
     active?: boolean;
+    /** Custom color when active (default: primary) */
     color?: string;
+    /** Callback fired when toggled, receives new state */
     onChange?: (on: boolean) => void;
 }
 
@@ -705,17 +1454,36 @@ interface ChatMessageProps {
 
 declare const Chat: (props: ChatProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Full-featured chat interface with message history, template support, and media uploads.
+ * Automatically groups messages by date and shows template prompt when last message is > 24 hours old.
+ *
+ * @example
+ * ```tsx
+ * <Chat
+ *   messages={chatMessages}
+ *   templates={messageTemplates}
+ *   loading={isSending}
+ *   onSend={(data) => handleSendMessage(data)}
+ * />
+ * ```
+ */
 interface ChatProps {
     style?: CSSProperties;
+    /** Array of chat messages to display, grouped automatically by date */
     messages: ChatMessageProps[];
+    /** Shows loading spinner in input when true */
     loading?: boolean;
+    /** Placeholder text for the input field */
     placeholder?: string;
+    /** Available message templates shown when conversation is inactive (>24 hrs) */
     templates: {
         id: string;
         title: string;
         subtitle: string;
         description: string;
     }[];
+    /** Callback fired when user sends a message, template, or uploads media */
     onSend: (data: {
         text?: string;
         template?: string;
@@ -741,35 +1509,102 @@ interface LocationFormProps {
 
 declare const Form: (props: FormProps & LocationFormProps) => react_jsx_runtime.JSX.Element | null;
 
+/**
+ * Form router component (currently only supports location type).
+ * Delegates to specific form implementations based on type.
+ *
+ * @example
+ * ```tsx
+ * <Form
+ *   type="location"
+ *   isLoaded={isGoogleMapsLoaded}
+ *   onChange={(location) => setLocation(location)}
+ * />
+ * ```
+ */
 interface FormProps {
+    /** Form type to render */
     type: "location";
+    /** Whether Google Maps API is loaded (required for location form) */
     isLoaded: boolean;
 }
 
 declare const CurrencySelector: (props: CurrencySelectorProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Currency selector dropdown with modal for choosing from available currencies.
+ * Displays symbol and currency code (e.g., "€ EUR"). Responsive with full-screen modal on mobile.
+ *
+ * @example
+ * ```tsx
+ * <CurrencySelector
+ *   options={[
+ *     { currency: "EUR", name: "Euro", symbol: "€" },
+ *     { currency: "USD", name: "US Dollar", symbol: "$" },
+ *     { currency: "GBP", name: "British Pound", symbol: "£" }
+ *   ]}
+ *   selectedOption={{ currency: "EUR", name: "Euro", symbol: "€" }}
+ *   onChange={(option) => setCurrency(option.currency)}
+ * />
+ * ```
+ */
 interface CurrencySelectorProps {
     style?: React.CSSProperties;
+    /** Available currency options */
     options: CurrencySelectorOption[];
+    /** Currently selected currency (defaults to first option) */
     selectedOption?: CurrencySelectorOption;
+    /** Callback when currency is selected */
     onChange?: (option: CurrencySelectorOption) => void;
 }
 interface CurrencySelectorOption {
+    /** ISO currency code (e.g., "EUR", "USD") */
     currency: string;
+    /** Full currency name (e.g., "Euro") */
     name: string;
+    /** Currency symbol (e.g., "€", "$") */
     symbol: string;
 }
 
 declare const TextAnimated: ({ children, ...props }: TextAnimatedProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Text component with rotating animated words that cycle through options array.
+ * Uses {{data}} placeholder in children string for where animation appears.
+ *
+ * @example
+ * ```tsx
+ * <TextAnimated
+ *   type="h1"
+ *   options={["developers", "designers", "creators"]}
+ *   interval={3000}
+ * >
+ *   Built for {{data}}
+ * </TextAnimated>
+ * ```
+ */
 type TextAnimatedProps = TextProps & {
+    /** Array of strings to cycle through */
     options: string[];
+    /** Time in milliseconds between transitions. Default: 2500ms */
     interval?: number;
 };
 
 declare const Hover: ({ children, modalProps, ...props }: HoverProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Hover trigger component that displays content on hover.
+ * Content appears below the trigger element with shadow and border.
+ *
+ * @example
+ * ```tsx
+ * <Hover modalProps={{ children: <div>Hover content here</div> }}>
+ *   <button>Hover over me</button>
+ * </Hover>
+ * ```
+ */
 interface HoverProps extends ComponentPropsWithoutRef<"div"> {
+    /** Props for the hover content container (including children to display) */
     modalProps: React.ComponentProps<"div">;
 }