@delightui/components 0.1.105 → 0.1.107

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React$1 from 'react';
-import React__default, { ImgHTMLAttributes, SyntheticEvent, HTMLAttributes, ReactNode, MouseEvent, FormHTMLAttributes, Ref, InputHTMLAttributes, TextareaHTMLAttributes, LiHTMLAttributes, CSSProperties, RefObject, TableHTMLAttributes, TdHTMLAttributes, AriaRole, KeyboardEventHandler } from 'react';
+import React__default, { ImgHTMLAttributes, SyntheticEvent, HTMLAttributes, ReactNode, MouseEvent, FormHTMLAttributes, Ref, InputHTMLAttributes, TextareaHTMLAttributes, ComponentType, LiHTMLAttributes, CSSProperties, RefObject, TableHTMLAttributes, TdHTMLAttributes, AriaRole, KeyboardEventHandler } from 'react';
 import { LinkProps } from 'react-router-dom';
 import { Plugin } from 'flatpickr/dist/types/options';
 import FlatPickr from 'react-flatpickr';
@@ -1468,6 +1468,97 @@ type ModalProps = {
  */
 declare const Modal: (props: ModalProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Base props that all modal components must implement.
+ */
+type ModalComponentProps = {
+    /** Controls whether the modal is visible */
+    show?: boolean;
+    /** Callback function to handle modal cancellation/dismissal */
+    onCancel?: () => void;
+};
+/**
+ * Props for the ModalProvider component.
+ */
+type ModalProviderProps = {
+    /** Child components that will have access to the modal context */
+    children: ReactNode;
+};
+/**
+ * Return type for the useModal hook when a component type is provided.
+ */
+type UseModalReturn<T extends ModalComponentProps> = {
+    /**
+     * Opens the modal with the specified props.
+     * Uses the component type provided to the hook.
+     *
+     * @param props - Props to pass to the modal component
+     * @returns void
+     */
+    openModal: (props: T) => void;
+    /**
+     * Closes the modal instance managed by this hook.
+     *
+     * @returns void
+     */
+    closeModal: () => void;
+    /** The unique identifier for this modal instance */
+    modalId: string;
+};
+
+/**
+ * Provider component that manages modal state and renders modal instances.
+ * Wraps child components with modal context and renders all active modals.
+ *
+ * @param props - The provider props
+ * @param props.children - Child components that will have access to modal context
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <ModalProvider>
+ *       <MyApplication />
+ *     </ModalProvider>
+ *   );
+ * }
+ * ```
+ */
+declare const ModalProvider: ({ children }: ModalProviderProps) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Custom hook that provides an abstraction layer over the modal context.
+ * Takes a component type and returns functions to open/close that specific modal.
+ * Uses React's useId hook to generate a unique identifier for the modal instance.
+ *
+ * @template T - The props type for the modal component (must extend ModalComponentProps)
+ * @param Component - React component to use for the modal
+ * @returns An object containing openModal, closeModal functions and the modalId
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const confirmationModal = useModal(ConfirmationModal);
+ *
+ *   const handleDelete = () => {
+ *     confirmationModal.openModal({
+ *       title: 'Delete Item',
+ *       message: 'Are you sure you want to delete this item?',
+ *       show: true,
+ *       onConfirm: () => {
+ *         // perform delete
+ *         confirmationModal.closeModal();
+ *       },
+ *       onCancel: confirmationModal.closeModal
+ *     });
+ *   };
+ *
+ *   return <button onClick={handleDelete}>Delete</button>;
+ * }
+ * ```
+ */
+declare const useModal: <T extends ModalComponentProps>(Component: ComponentType<T>) => UseModalReturn<T>;
+
 /**
  * Defines the type of modal footer layout.
  * @default "1Button"
@@ -1711,6 +1802,21 @@ type ProgressBarProps = {
 
 declare const ProgressBar: React__default.FC<ProgressBarProps>;
 
+type RadioGroupProps = ControlledFormComponentProps<string | number> & {
+    className?: string;
+    /**
+     * The radio buttons to render
+     */
+    children: React.ReactElement<RadioButtonProps> | React.ReactElement<RadioButtonProps>[];
+    /**
+     * The orientation of the radio group
+     * @default 'vertical'
+     */
+    orientation?: 'horizontal' | 'vertical';
+};
+
+declare const RadioGroup: (props: RadioGroupProps) => react_jsx_runtime.JSX.Element;
+
 /**
  * Props for the Option component, extending LiHTMLAttributes<HTMLLIElement>.
  * Represents an option within a Select component.
@@ -2319,4 +2425,4 @@ declare const NotificationContext: React__default.Context<NotificationContextVal
 declare const NotificationProvider: React__default.FC<NotificationProviderProps>;
 declare const useNotification: () => NotificationContextValue;
 
-export { type AccessibilityActions, type AccessibilityProps, Accordion, AccordionDetails, AccordionGroup, AccordionSummary, ActionCard, type ActionCardProps, ActionImage, type ActionImageProps, Breadcrumb, type BreadcrumbProps, Breadcrumbs, type BreadcrumbsProps, Breakpoint, type BreakpointProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, Card, type CardProps, Checkbox, CheckboxItem, type CheckboxItemProps, type CheckboxLabelAlignmentEnum, type CheckboxProps, type CheckboxSizeEnum, type CheckboxTypeEnum, Chip, _default as ChipInput, type ChipInputProps, type ChipListItemProps, type ChipListItemTypeEnum, type ChipProps, ConditionalView, type ConditionalViewProps, ContextMenu, type ContextMenuProps, type CustomTimePickerConfig, CustomToggle, type CustomToggleProps, DatePicker, type DatePickerProps, SortableItem as DraggableItem, SortableTrigger as DraggableItemTrigger, Dropzone, DropzoneClear, DropzoneContent, type DropzoneContentProps, type DropzoneContentTypeEnum, DropzoneFilename, DropzoneFilename as DropzonePreview, type DropzoneProps, DropzoneSupportedFormats as DropzoneReject, DropzoneTrigger as DropzoneRoot, DropzoneSupportedFormats, DropzoneTrigger, type FieldValidationFunction, type FieldValidators, type FieldValue, Form, type FormContextValues, type FormErrors, FormField, type FormFieldProps, type FormProps, type FormProviderProps, type FormState, type FormStateChangeHandler, type FormSubmitHandler, type FormValidator, Grid, GridItem, type GridItemProps, GridList, type GridListProps, type GridProps, Icon, IconButton, type IconButtonProps, type IconButtonStyleEnum, type IconProps, type IconSizeEnum, type IconStyleEnum, Image, type ImageFitEnum, type ImageProps, Input, type InputProps, type InputTypeEnum, List, ListItem, type ListItemProps$1 as ListItemProps, type ListProps, Modal, ModalFooter, type ModalFooterProps, ModalHeader, type ModalHeaderProps, type ModalProps, Nav, NavItem, type NavItemProps, NavLink, type NavLinkProps, type NavProps, type NotificationContainerProps, NotificationContext, NotificationProvider, Option, type OptionProps, type OverlayDirectionEnum, Pagination, PaginationNumberField, type PaginationNumberFieldProps, type PaginationProps, Password, Popover, type PopoverHandle, type PopoverProps, ProgressBar, type ProgressBarProps, RadioButton, RadioButtonItem, type RadioButtonItemProps, type RadioButtonLabelAlignmentEnum, type RadioButtonProps, type RadioButtonSizeEnum, RenderStateView, type RenderStateViewProps, RepeaterList, type RepeaterListProps, type RequiredFields, ResponsiveComponent, type ResponsiveComponentProps, Select, SelectListItem, type SelectListItemProps, type SelectProps, SelectProvider, SlideOutPanel, type SlideOutPanelDirectionEnum, type SlideOutPanelProps, type SlideOutPanelSizeEnum, Slider, type SliderProps, Spinner, type SpinnerProps, TabContent, type TabContentProps, TabItem, type TabItemProps, Table, TableBody, type TableBodyProps, TableCell, type TableCellProps, TableHeader, TableHeaderCell, type TableHeaderCellProps, type TableHeaderProps, type TableProps, TableRow, type TableRowProps, Tabs, type TabsProps, Text, TextArea, type TextAreaProps, type TextDecorationEnum, type TextProps, type TextTypeEnum, type TextWeightEnum, ThemeContext, type ThemeContextType, ThemeProvider, type ThemeProviderProps, Toggle, ToggleButton, type ToggleButtonProps, type ToggleLabelAlignmentEnum, type ToggleProps, Tooltip, type TooltipProps, WrapTextNodes, type WrapTextNodesProps, applyPropsToChildren, getClickAccessibilityProps, mergeRefs, useDropzoneContext, useNotification, useSelectContext, useTab };
+export { type AccessibilityActions, type AccessibilityProps, Accordion, AccordionDetails, AccordionGroup, AccordionSummary, ActionCard, type ActionCardProps, ActionImage, type ActionImageProps, Breadcrumb, type BreadcrumbProps, Breadcrumbs, type BreadcrumbsProps, Breakpoint, type BreakpointProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, Card, type CardProps, Checkbox, CheckboxItem, type CheckboxItemProps, type CheckboxLabelAlignmentEnum, type CheckboxProps, type CheckboxSizeEnum, type CheckboxTypeEnum, Chip, _default as ChipInput, type ChipInputProps, type ChipListItemProps, type ChipListItemTypeEnum, type ChipProps, ConditionalView, type ConditionalViewProps, ContextMenu, type ContextMenuProps, type CustomTimePickerConfig, CustomToggle, type CustomToggleProps, DatePicker, type DatePickerProps, SortableItem as DraggableItem, SortableTrigger as DraggableItemTrigger, Dropzone, DropzoneClear, DropzoneContent, type DropzoneContentProps, type DropzoneContentTypeEnum, DropzoneFilename, DropzoneFilename as DropzonePreview, type DropzoneProps, DropzoneSupportedFormats as DropzoneReject, DropzoneTrigger as DropzoneRoot, DropzoneSupportedFormats, DropzoneTrigger, type FieldValidationFunction, type FieldValidators, type FieldValue, Form, type FormContextValues, type FormErrors, FormField, type FormFieldProps, type FormProps, type FormProviderProps, type FormState, type FormStateChangeHandler, type FormSubmitHandler, type FormValidator, Grid, GridItem, type GridItemProps, GridList, type GridListProps, type GridProps, Icon, IconButton, type IconButtonProps, type IconButtonStyleEnum, type IconProps, type IconSizeEnum, type IconStyleEnum, Image, type ImageFitEnum, type ImageProps, Input, type InputProps, type InputTypeEnum, List, ListItem, type ListItemProps$1 as ListItemProps, type ListProps, Modal, type ModalComponentProps, ModalFooter, type ModalFooterProps, ModalHeader, type ModalHeaderProps, type ModalProps, ModalProvider, type ModalProviderProps, Nav, NavItem, type NavItemProps, NavLink, type NavLinkProps, type NavProps, type NotificationContainerProps, NotificationContext, NotificationProvider, Option, type OptionProps, type OverlayDirectionEnum, Pagination, PaginationNumberField, type PaginationNumberFieldProps, type PaginationProps, Password, Popover, type PopoverHandle, type PopoverProps, ProgressBar, type ProgressBarProps, RadioButton, RadioButtonItem, type RadioButtonItemProps, type RadioButtonLabelAlignmentEnum, type RadioButtonProps, type RadioButtonSizeEnum, RadioGroup, type RadioGroupProps, RenderStateView, type RenderStateViewProps, RepeaterList, type RepeaterListProps, type RequiredFields, ResponsiveComponent, type ResponsiveComponentProps, Select, SelectListItem, type SelectListItemProps, type SelectProps, SelectProvider, SlideOutPanel, type SlideOutPanelDirectionEnum, type SlideOutPanelProps, type SlideOutPanelSizeEnum, Slider, type SliderProps, Spinner, type SpinnerProps, TabContent, type TabContentProps, TabItem, type TabItemProps, Table, TableBody, type TableBodyProps, TableCell, type TableCellProps, TableHeader, TableHeaderCell, type TableHeaderCellProps, type TableHeaderProps, type TableProps, TableRow, type TableRowProps, Tabs, type TabsProps, Text, TextArea, type TextAreaProps, type TextDecorationEnum, type TextProps, type TextTypeEnum, type TextWeightEnum, ThemeContext, type ThemeContextType, ThemeProvider, type ThemeProviderProps, Toggle, ToggleButton, type ToggleButtonProps, type ToggleLabelAlignmentEnum, type ToggleProps, Tooltip, type TooltipProps, type UseModalReturn, WrapTextNodes, type WrapTextNodesProps, applyPropsToChildren, getClickAccessibilityProps, mergeRefs, useDropzoneContext, useModal, useNotification, useSelectContext, useTab };

package/docs/README.md

@@ -0,0 +1,264 @@
+# @delightui/components
+
+A comprehensive React component library built with TypeScript, providing a complete set of UI components following atomic design principles. This library offers flexible, accessible, and highly customizable components for building modern web applications.
+
+## Features
+
+- **Atomic Design Architecture**: Components organized into Atoms, Molecules, and Organisms
+- **TypeScript Support**: Full TypeScript support with comprehensive type definitions
+- **Accessible**: Built with accessibility in mind following WCAG guidelines
+- **Customizable**: Flexible theming system with SCSS modules
+- **Modern React**: Built with React 18+ and modern hooks
+- **Storybook Integration**: Interactive component documentation and testing
+- **Testing**: Comprehensive test coverage with Vitest and Testing Library
+
+## Component Library
+
+### Atoms
+Basic building blocks and fundamental UI elements:
+
+- **[ActionImage](./docs/components/atoms/ActionImage.md)** - Interactive image component with action triggers that allows users to perform actions when interacting with images. This component combines visual display with user interaction capabilities.
+  - *Aliases: Action Image, Interactive Image, Clickable Image, Image Button*
+
+- **[Button](./docs/components/atoms/Button.md)** - Flexible button component with multiple variants, sizes, and states. Supports icons, loading states, and various styling options to fit different use cases throughout the application.
+  - *Aliases: Action Button, CTA (Call to Action), Click Button, Submit Button*
+
+- **[Checkbox](./docs/components/atoms/Checkbox.md)** - Customizable checkbox input component with support for controlled and uncontrolled states, various sizes, label positioning, and form integration. Includes proper accessibility features and validation support.
+  - *Aliases: Check Box, Tick Box, Selection Box, Boolean Input, Toggle Checkbox*
+
+- **[CheckboxItem](./docs/components/atoms/CheckboxItem.md)** - Enhanced checkbox component with integrated label styling and an optional right-side action button. Extends the base Checkbox functionality with additional interactive elements for more complex use cases.
+  - *Aliases: Checkbox List Item, Enhanced Checkbox, Action Checkbox, Checkbox with Button*
+
+- **[Chip](./docs/components/atoms/Chip.md)** - Small, compact elements used for tags, filters, categories, and interactive selections. Supports multiple visual styles, sizes, icons, and dismissible functionality for versatile use cases.
+  - *Aliases: Tag, Badge, Label, Token, Filter Chip*
+
+- **[CustomToggle](./docs/components/atoms/CustomToggle.md)** - A highly customizable toggle component that allows you to define custom content for both the on and off states. This component provides a flexible alternative to the standard Toggle component by letting you specify what content appears in each state, making it perfect for scenarios where you need more than just basic on/off visual states.
+  - *Aliases: CustomToggle, CustomSwitch, ContentToggle*
+
+- **[Icon](./docs/components/atoms/Icon.md)** - SVG icon component with dynamic imports that supports multiple icon styles and sizes. Provides a consistent way to display icons throughout the application with automatic SVG loading.
+  - *Aliases: SVG Icon, Vector Icon, Glyph, Symbol*
+
+- **[IconButton](./docs/components/atoms/IconButton.md)** - A specialized button component designed specifically for displaying icons without text content. IconButton inherits most functionality from the Button component but is optimized for icon-only interactions.
+  - *Aliases: IconButton, IconBtn, ActionIcon*
+
+- **[Image](./docs/components/atoms/Image.md)** - A versatile image component that extends the standard HTML img element with enhanced features including fallback support, different fit options, loading states, and aspect ratio control.
+  - *Aliases: Image, Img, Picture*
+
+- **[Input](./docs/components/atoms/Input.md)** - Text input component with validation, icons, and form integration support. Provides a flexible foundation for collecting user text input with proper accessibility and styling.
+  - *Aliases: Text Input, Text Field, Input Field, Form Input*
+
+- **[ListItem](./docs/components/atoms/ListItem.md)** - A versatile list item component that provides a standardized way to display individual items within lists. It supports leading and trailing icons, click interactions, and disabled states, making it ideal for navigation menus, option lists, and interactive collections.
+  - *Aliases: ListItem, ListElement, Item*
+
+- **[Password](./docs/components/atoms/Password.md)** - A specialized input component designed specifically for password entry. It extends the Input component with built-in password visibility toggle functionality, providing a secure and user-friendly way to handle password inputs.
+  - *Aliases: Password, PasswordInput, SecureInput*
+
+- **[RadioButton](./docs/components/atoms/RadioButton.md)** - A radio button component that allows users to select one option from a group of mutually exclusive choices. It provides flexible sizing, label positioning, and integrates seamlessly with form handling.
+  - *Aliases: RadioButton, Radio, OptionButton*
+
+- **[RadioButtonItem](./docs/components/atoms/RadioButtonItem.md)** - An enhanced radio button component that extends the basic RadioButton with additional action button functionality. It provides all the standard radio button features plus an optional right-side action button, making it perfect for scenarios where you need both selection and additional actions on radio options.
+  - *Aliases: RadioButtonItem, RadioItem, ActionRadioButton*
+
+- **[ResponsiveComponent](./docs/components/atoms/ResponsiveComponent.md)** - A utility component that renders different components based on screen width breakpoints. It provides a declarative way to handle responsive design by allowing you to specify different component configurations for different screen sizes, making it easy to create adaptive user interfaces.
+  - *Aliases: ResponsiveComponent, ResponsiveRenderer, BreakpointComponent*
+
+- **[SelectListItem](./docs/components/atoms/SelectListItem.md)** - A specialized list item component designed specifically for use within select dropdowns and option lists. It provides a consistent interface for selectable options with support for icons, disabled states, and click interactions.
+  - *Aliases: SelectListItem, SelectOption, DropdownItem*
+
+- **[Slider](./docs/components/atoms/Slider.md)** - A versatile slider component that allows users to select numeric values within a specified range. It supports both single-value and range selection modes, with customizable min/max values, step sizes, and display options.
+  - *Aliases: Slider, Range, RangeSlider*
+
+- **[Spinner](./docs/components/atoms/Spinner.md)** - A loading indicator component that displays an animated spinner to indicate processing, loading, or waiting states. This component provides visual feedback to users during asynchronous operations and helps maintain engagement during loading periods.
+  - *Aliases: Spinner, LoadingSpinner, Loader*
+
+- **[Text](./docs/components/atoms/Text.md)** - A comprehensive text component that provides a standardized way to display text content with consistent typography. It offers extensive customization options including different text types, weights, decorations, transformations, and layout controls, making it the foundation for all text display in the UI.
+  - *Aliases: Text, Typography, TextElement*
+
+- **[TextArea](./docs/components/atoms/TextArea.md)** - A multi-line text input component that extends the standard HTML textarea with enhanced form integration capabilities. It provides a consistent interface for collecting longer text inputs from users, with full support for controlled and uncontrolled usage patterns, validation, and accessibility features.
+  - *Aliases: TextArea, MultilineInput, TextBox*
+
+- **[ToastNotification](./docs/components/atoms/ToastNotification.md)** - A versatile notification component that displays temporary messages to users. It supports different styles (neutral, success, error), customizable icons, dismissible behavior, and auto-dismiss functionality.
+  - *Aliases: ToastNotification, Toast, Notification*
+
+- **[Toggle](./docs/components/atoms/Toggle.md)** - A toggle switch component that allows users to switch between two states (on/off, enabled/disabled). It provides a visual alternative to checkboxes for boolean inputs and includes flexible label positioning options.
+  - *Aliases: Toggle, Switch, ToggleSwitch*
+
+- **[ToggleButton](./docs/components/atoms/ToggleButton.md)** - A button component that maintains a pressed/unpressed state, functioning as a toggle between two states. It combines the visual appearance of a button with the state behavior of a toggle, making it perfect for scenarios where you need a button-like interface for binary choices or mode switches.
+  - *Aliases: ToggleButton, PressButton, StateButton*
+
+- **[Tooltip](./docs/components/atoms/Tooltip.md)** - A contextual tooltip component that displays helpful information when users interact with elements. Supports multiple trigger actions (hover, click, follow), positioning options, and customizable styling with arrow indicators for enhanced user experience.
+  - *Aliases: Tooltip, Popover, Hint, Help Text, Info Bubble*
+
+### Molecules
+Combinations of atoms forming more complex UI patterns:
+
+- **[Accordion](./docs/components/molecules/Accordion.md)** - A collapsible content component that allows users to expand and collapse sections of information. Supports controlled and uncontrolled modes, custom icons, different sizes, and can be used individually or grouped together for organizing complex content hierarchies.
+  - *Aliases: Accordion, Collapsible, Expandable, DropDown, Disclosure*
+
+- **[AccordionGroup](./docs/components/molecules/AccordionGroup.md)** - A container component that manages multiple accordion items as a group, allowing for coordinated behavior like ensuring only one accordion is open at a time. Provides structured organization for related collapsible content sections.
+  - *Aliases: AccordionGroup, AccordionSet, CollapsibleGroup*
+
+- **[ActionCard](./docs/components/molecules/ActionCard.md)** - A flexible card component that functions as a clickable or interactive container. It can serve as a navigation element or trigger actions while maintaining the visual structure of a card. Perfect for creating interactive tiles, feature cards, or clickable content blocks.
+  - *Aliases: ActionCard, ClickableCard, InteractiveCard*
+
+- **[Breadcrumb](./docs/components/molecules/Breadcrumb.md)** - An individual breadcrumb item component that represents a single step in a navigation path. Can function as a clickable link or a static indicator, with support for icons and selection states to show the current location.
+  - *Aliases: Breadcrumb, BreadcrumbItem, PathItem*
+
+- **[Breadcrumbs](./docs/components/molecules/Breadcrumbs.md)** - A navigation component that displays the current page's location within a hierarchical structure. Provides users with a clear path to understand their current position and navigate back to previous levels, enhancing website navigation and user experience.
+  - *Aliases: Breadcrumbs, BreadcrumbTrail, NavigationPath, PathNavigation, Breadcrumb Navigation*
+
+- **[ButtonGroup](./docs/components/molecules/ButtonGroup.md)** - A container component that groups related buttons together with consistent spacing and styling. Supports horizontal and vertical layouts with different visual treatments to create cohesive button collections for actions, navigation, and selection interfaces.
+  - *Aliases: ButtonGroup, ActionGroup, ButtonSet, ToolbarGroup, ButtonCluster*
+
+- **[Card](./docs/components/molecules/Card.md)** - A flexible container component that provides a consistent visual treatment for grouping related content. It serves as a foundational layout element with proper spacing, borders, and background styling, making it perfect for organizing information into discrete, scannable sections.
+  - *Aliases: Card, Panel, Tile, ContentCard*
+
+- **[ChipInput](./docs/components/molecules/ChipInput.md)** - An input field component that allows users to enter multiple values as chips or tags. Automatically converts typed input into removable chip elements, providing an intuitive interface for managing lists of items like tags, categories, email addresses, or any collection of discrete values.
+  - *Aliases: ChipInput, TagInput, TokenInput, MultiValueInput, ChipField*
+
+- **[ContextMenu](./docs/components/molecules/ContextMenu.md)** - A contextual menu component that appears on right-click or trigger actions, providing quick access to relevant actions and options. Supports nested menus, separators, and different item types for creating rich interaction experiences.
+  - *Aliases: ContextMenu, RightClickMenu, ActionMenu*
+
+- **[CustomTimeSelector](./docs/components/molecules/CustomTimeSelector.md)** - A Flatpickr plugin component that provides a custom time selection interface with dropdown functionality. It creates an enhanced time input field with a searchable time options dropdown, replacing the default Flatpickr time picker with a more user-friendly time selection experience.
+  - *Aliases: CustomTimeSelector, TimeDropdownPlugin, TimePickerPlugin, CustomTimePicker*
+
+- **[DatePicker](./docs/components/molecules/DatePicker.md)** - A comprehensive date and time selection component that provides an intuitive interface for choosing dates, times, or date ranges. Features calendar views, time selection, and flexible formatting options to handle various date input scenarios.
+  - *Aliases: DatePicker, Calendar, DateSelector*
+
+- **[DateTimeSelector](./docs/components/molecules/DateTimeSelector.md)** - A Flatpickr plugin component that provides a combined date and time selection interface with a custom time input field and dropdown. It enhances the DatePicker component by adding a labeled time input section alongside the calendar, providing a comprehensive date-time selection experience.
+  - *Aliases: DateTimeSelector, DateTimeDropdownPlugin, DateTimePickerPlugin, CombinedDateTimePicker*
+
+- **[FormField](./docs/components/molecules/FormField.md)** - A wrapper component that combines form inputs with labels, validation messages, and help text. It provides a consistent structure for form elements while handling validation states, error display, and accessibility requirements automatically.
+  - *Aliases: FormField, FieldWrapper, FormGroup*
+
+- **[Grid](./docs/components/molecules/Grid.md)** - A CSS Grid-based layout component that provides a flexible and powerful way to create responsive grid layouts. Offers control over columns, rows, gaps, and alignment to create complex layouts with minimal effort.
+  - *Aliases: Grid, GridLayout, CSSGrid*
+
+- **[GridItem](./docs/components/molecules/GridItem.md)** - An individual item within a Grid component that provides control over its positioning, spanning, and alignment within the grid system. Works in conjunction with the Grid component to create flexible layouts.
+  - *Aliases: GridItem, GridCell, GridElement*
+
+- **[GridList](./docs/components/molecules/GridList.md)** - A grid-based list component that extends the standard List component with CSS Grid layout functionality. It automatically arranges list items in a responsive grid format with customizable columns and spacing, providing an organized way to display collections of data in a grid pattern.
+  - *Aliases: GridList, GridCollection, DataGrid, GridContainer*
+
+- **[List](./docs/components/molecules/List.md)** - A flexible list component with sorting capabilities that provides a standardized way to render collections of data. Supports both regular and sortable list rendering with drag-and-drop functionality for reordering items.
+  - *Aliases: List, DataList, ItemList*
+
+- **[Modal](./docs/components/molecules/Modal.md)** - A comprehensive modal system that displays content in a layer above the main application interface. Includes both traditional modal components and a modern context-based system for programmatic modal management. Provides flexible sizing options, customizable header and footer areas, backdrop controls, and accessibility features for creating overlay dialogs, confirmations, and forms.
+  - *Aliases: Modal, Dialog, Popup, Overlay, Lightbox*
+
+- **[ModalProvider](./docs/components/molecules/ModalProvider.md)** - Context provider component that manages modal state across your application. Enables programmatic modal management by maintaining a centralized registry of active modals and providing functions to open and close them from anywhere in your component tree.
+  - *Aliases: ModalProvider, ModalContext*
+
+- **[ModalFooter](./docs/components/molecules/ModalFooter.md)** - A specialized footer component designed for use within Modal components. Provides consistent styling and layout for action buttons and other footer content, with predefined layouts for common button configurations.
+  - *Aliases: ModalFooter, DialogFooter, ModalActions*
+
+- **[ModalHeader](./docs/components/molecules/ModalHeader.md)** - A specialized header component designed for use within Modal components. Provides consistent styling for modal titles and includes built-in close functionality with customizable icon buttons.
+  - *Aliases: ModalHeader, DialogHeader, ModalTitle*
+
+- **[Nav](./docs/components/molecules/Nav.md)** - A navigation container component that provides a flexible foundation for building navigation interfaces. Supports various layout options and integrates seamlessly with routing libraries for creating menus, sidebars, and navigation bars.
+  - *Aliases: Nav, Navigation, Menu*
+
+- **[NavItem](./docs/components/molecules/NavItem.md)** - An individual navigation item component that represents a single entry within a navigation menu. Provides consistent styling and behavior for navigation elements while supporting active states and nested structures.
+  - *Aliases: NavItem, NavigationItem, MenuItem*
+
+- **[NavLink](./docs/components/molecules/NavLink.md)** - A navigation link component that extends standard link functionality with additional styling and state management. Integrates with routing libraries and provides visual feedback for active, hover, and focus states.
+  - *Aliases: NavLink, NavigationLink, MenuLink*
+
+- **[Option](./docs/components/molecules/Option.md)** - A select dropdown option component that represents individual choices within select components. Provides consistent styling, support for icons, and proper accessibility attributes for creating rich dropdown experiences.
+  - *Aliases: Option, SelectOption, Choice*
+
+- **[Pagination](./docs/components/molecules/Pagination.md)** - Pagination controls for navigating through multiple pages of content. Provides a complete interface with page numbers, next/previous navigation, and customizable display options for handling large datasets.
+  - *Aliases: Pagination, Pager, PageNavigation*
+
+- **[PaginationNumberField](./docs/components/molecules/PaginationNumberField.md)** - A specialized number input component designed for pagination controls. Allows users to directly enter page numbers with validation and integration with pagination systems.
+  - *Aliases: PaginationNumberField, PageNumberInput, PaginationInput*
+
+- **[Popover](./docs/components/molecules/Popover.md)** - A floating popover component that displays additional content in a positioned overlay. Supports various trigger methods, positioning options, and arrow indicators for creating contextual information displays and interactive menus.
+  - *Aliases: Popover, Popup, FloatingContent*
+
+- **[ProgressBar](./docs/components/molecules/ProgressBar.md)** - A progress indicator component that visually represents the completion status of tasks or processes. Supports different styles, sizes, and display options including percentage labels and custom formatting.
+  - *Aliases: ProgressBar, ProgressIndicator, LoadingBar*
+
+- **[RadioGroup](./docs/components/molecules/RadioGroup.md)** - A group container component for radio button options that manages selection state and provides coordinated behavior between radio button children. Supports both horizontal and vertical layouts, form integration, controlled and uncontrolled modes, and accessibility features for creating option selectors, preference settings, and choice-based inputs.
+  - *Aliases: RadioGroup, RadioButtonGroup, OptionGroup, ChoiceGroup, SelectionGroup, RadioSet*
+
+- **[RepeaterList](./docs/components/molecules/RepeaterList.md)** - A simple list rendering component that iterates over an array of data and renders each item using a specified component. It provides a minimal, lightweight approach to rendering collections without additional layout or styling, making it perfect for simple repetitive content rendering.
+  - *Aliases: RepeaterList, ItemRepeater, DataRepeater, ComponentRepeater*
+
+- **[Select](./docs/components/molecules/Select.md)** - A dropdown selection component that allows users to choose from a list of options. Supports single and multiple selections, custom icons, placeholder text, and integrates seamlessly with form validation. Built with accessibility and keyboard navigation in mind.
+  - *Aliases: Select, Dropdown, ComboBox, Picker, OptionList*
+
+- **[SortableTrigger](./docs/components/molecules/SortableTrigger.md)** - A trigger component that initiates drag-and-drop functionality for sortable list items. It provides a dedicated draggable handle with proper visual feedback and accessibility features, allowing users to easily identify and interact with sortable elements.
+  - *Aliases: SortableTrigger, DragHandle, DragTrigger, SortHandle*
+
+### Organisms
+Complex components combining multiple molecules and atoms:
+
+- **[Dropzone](./docs/components/organisms/Dropzone.md)** - A file upload component with drag-and-drop functionality that provides an intuitive interface for users to upload files. Supports multiple file selection, file type validation, drag-and-drop gestures, and progress tracking for comprehensive file upload experiences.
+  - *Aliases: Dropzone, FileUpload, DragDropUpload*
+
+- **[DropzoneClear](./docs/components/organisms/DropzoneClear.md)** - A specialized button component for clearing files from a dropzone. It integrates with the Dropzone context to provide a one-click solution for removing all uploaded files, with customizable icon display and consistent styling that matches the dropzone interface.
+  - *Aliases: DropzoneClear, ClearFiles, ResetDropzone, RemoveAllFiles*
+
+- **[DropzoneContent](./docs/components/organisms/DropzoneContent.md)** - The content area component specifically designed for use within Dropzone components. Provides customizable content display for different dropzone states including empty, dragging, and file preview states.
+  - *Aliases: DropzoneContent, UploadContent, FileDropContent*
+
+- **[DropzoneFilename](./docs/components/organisms/DropzoneFilename.md)** - A text component that displays the filename of uploaded files in a dropzone. It automatically retrieves file information from the Dropzone context and renders the filename with consistent text styling, supporting multiple files through index selection.
+  - *Aliases: DropzoneFilename, FileName, FileNameDisplay, UploadedFileName*
+
+- **[DropzoneSupportedFormats](./docs/components/organisms/DropzoneSupportedFormats.md)** - A text component that automatically displays the supported file formats for a dropzone. It reads the accepted file types from the Dropzone context and formats them into a readable list, helping users understand what file types they can upload.
+  - *Aliases: DropzoneSupportedFormats, SupportedFormats, AcceptedFileTypes, FileFormatList*
+
+- **[DropzoneTrigger](./docs/components/organisms/DropzoneTrigger.md)** - A button component that triggers the file selection dialog for a dropzone. It integrates with the Dropzone context to provide a clickable interface for users to browse and select files, serving as an alternative or complement to drag-and-drop functionality.
+  - *Aliases: DropzoneTrigger, FileSelectButton, BrowseButton, UploadTrigger*
+
+- **[Form](./docs/components/organisms/Form.md)** - A comprehensive form management component that provides state management, validation, error handling, and submission workflows. Built with TypeScript for type safety and supports both controlled and uncontrolled form patterns with extensive validation capabilities.
+  - *Aliases: Form, FormProvider, FormContainer, FormWrapper*
+
+- **[SlideOutPanel](./docs/components/organisms/SlideOutPanel.md)** - A sliding panel component that provides additional content space by sliding in from the edge of the screen. Perfect for displaying detailed information, settings, or secondary actions without navigating away from the current context.
+  - *Aliases: SlideOutPanel, SidePanel, DrawerPanel*
+
+- **[Table](./docs/components/organisms/Table.md)** - A comprehensive data table component that provides structure for presenting tabular data in an organized, accessible format. The Table component serves as the root container for table content and offers features like sticky headers for enhanced usability in data-heavy interfaces.
+  - *Aliases: Table, DataTable, Grid, TableContainer, DataGrid*
+
+- **[TableBody](./docs/components/organisms/TableBody.md)** - The body container component for tables that wraps and organizes table rows containing the main data content. Provides proper semantic structure and styling for the data portion of table components.
+  - *Aliases: TableBody, DataTableBody, GridBody*
+
+- **[TableCell](./docs/components/organisms/TableCell.md)** - An individual table cell component that displays data within table rows. Supports various content types, alignment options, and styling variants for flexible data presentation in table structures.
+  - *Aliases: TableCell, DataCell, GridCell*
+
+- **[TableHeader](./docs/components/organisms/TableHeader.md)** - The header container component for tables that organizes and styles column headers. Provides consistent structure and styling for table headers with support for sorting indicators and interactive elements.
+  - *Aliases: TableHeader, DataTableHeader, GridHeader*
+
+- **[TableHeaderCell](./docs/components/organisms/TableHeaderCell.md)** - An individual header cell component that displays column titles and controls within table headers. Supports sorting functionality, alignment options, and interactive elements for comprehensive table column management.
+  - *Aliases: TableHeaderCell, HeaderCell, ColumnHeader*
+
+- **[TableRow](./docs/components/organisms/TableRow.md)** - A table row container component that organizes and styles individual rows of data within tables. Provides consistent row styling, hover states, and selection capabilities for enhanced table interaction.
+  - *Aliases: TableRow, DataRow, GridRow*
+
+- **[TabContent](./docs/components/organisms/TabContent.md)** - The content area component for tab panels that displays the associated content for each tab. Works in conjunction with Tabs and TabItem components to create complete tabbed interface experiences.
+  - *Aliases: TabContent, TabPanel, PanelContent*
+
+- **[TabItem](./docs/components/organisms/TabItem.md)** - An individual tab item component that represents a single tab within a tab navigation system. Provides tab styling, active states, and click interactions for building comprehensive tabbed interfaces.
+  - *Aliases: TabItem, Tab, TabButton*
+
+- **[Tabs](./docs/components/organisms/Tabs.md)** - A tab navigation component that provides a complete tabbed interface system. Manages tab selection, content switching, and supports various tab layouts and styles for organizing content into logical sections.
+  - *Aliases: Tabs, TabNavigation, TabContainer*
+
+### Hooks
+React hooks for enhanced functionality:
+
+- **[useModal](./docs/components/molecules/useModal.md)** - A React hook that provides programmatic modal management with automatic ID generation and simplified modal state handling. Takes a modal component as a parameter and returns functions to open and close that specific modal, along with automatic unique identifier generation for each modal instance.
+  - *Aliases: useModal, Modal Hook, Modal Manager*
+
+### Utilities
+Helper components and utilities:
+
+- **[ConditionalView](./docs/components/utils/ConditionalView.md)** - A utility component that conditionally renders content based on boolean conditions or state values. Provides a declarative way to handle conditional rendering logic while maintaining clean and readable component code.
+  - *Aliases: ConditionalView, ConditionalRender, ShowIf*
+
+- **[RenderStateView](./docs/components/utils/RenderStateView.md)** - A component for handling different render states such as loading, error, empty, and success states. Provides a consistent pattern for managing asynchronous data loading and error handling with customizable content for each state.
+  - *Aliases: RenderStateView, StateRenderer, AsyncView*
+
+- **[WrapTextNodes](./docs/components/utils/WrapTextNodes.md)** - A utility component that automatically wraps text nodes with specified components or styling. Useful for applying consistent text treatment across complex component hierarchies without manually wrapping each text element.
+  - *Aliases: WrapTextNodes, TextWrapper, TextNodeWrapper*

package/docs/components/atoms/ActionImage.md

@@ -0,0 +1,119 @@
+# ActionImage
+
+## Description
+
+Interactive image component with action triggers that allows users to perform actions when interacting with images. This component combines visual display with user interaction capabilities.
+
+## Aliases
+
+- Action Image
+- Interactive Image
+- Clickable Image
+- Image Button
+
+## Props Breakdown
+
+**Extends:** `ImgHTMLAttributes<HTMLImageElement>` (via ImageProps)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `src` | `string` | - | Yes | Source URL of the image |
+| `alt` | `string` | - | Yes | Alternative text for accessibility |
+| `onClick` | `(event: MouseEvent) => void` | - | No | Click handler for the image action |
+| `disabled` | `boolean` | `false` | No | Whether the image action is disabled |
+| `loading` | `boolean` | `false` | No | Shows loading state |
+| `className` | `string` | - | No | Additional CSS class names |
+| `width` | `number \| string` | - | No | Width of the image |
+| `height` | `number \| string` | - | No | Height of the image |
+| `objectFit` | `'cover' \| 'contain' \| 'fill'` | `'cover'` | No | How the image should fit within its container |
+
+## Examples
+
+### Basic Usage
+```tsx
+import { ActionImage } from '@delightui/components';
+
+function BasicExample() {
+  return (
+    <ActionImage
+      src="/images/product.jpg"
+      alt="Product image"
+      onClick={() => console.log('Image clicked')}
+    />
+  );
+}
+```
+
+### Disabled State
+```tsx
+function DisabledExample() {
+  return (
+    <ActionImage
+      src="/images/product.jpg"
+      alt="Product image"
+      disabled={true}
+      onClick={() => console.log('This won\'t fire')}
+    />
+  );
+}
+```
+
+### Loading State
+```tsx
+function LoadingExample() {
+  return (
+    <ActionImage
+      src="/images/product.jpg"
+      alt="Product image"
+      loading={true}
+      onClick={() => console.log('Image clicked')}
+    />
+  );
+}
+```
+
+### Custom Dimensions
+```tsx
+function CustomSizeExample() {
+  return (
+    <ActionImage
+      src="/images/banner.jpg"
+      alt="Banner image"
+      width={400}
+      height={200}
+      objectFit="cover"
+      onClick={() => console.log('Banner clicked')}
+    />
+  );
+}
+```
+
+### Gallery Action
+```tsx
+function GalleryExample() {
+  const handleImageClick = (imageId: string) => {
+    console.log(`Opening image ${imageId} in lightbox`);
+  };
+
+  return (
+    <div className="gallery-grid">
+      <ActionImage
+        src="/images/gallery-1.jpg"
+        alt="Gallery image 1"
+        width={300}
+        height={200}
+        className="gallery-item"
+        onClick={() => handleImageClick('1')}
+      />
+      <ActionImage
+        src="/images/gallery-2.jpg"
+        alt="Gallery image 2"
+        width={300}
+        height={200}
+        className="gallery-item"
+        onClick={() => handleImageClick('2')}
+      />
+    </div>
+  );
+}
+```