@ssa-ui-kit/core 2.33.0 → 3.1.0

package/dist/components/MultipleDropdown/types.d.ts

@@ -1,18 +1,92 @@
 import { DropdownOptionProps } from '../DropdownOptions/types';
+/**
+ * Props for the MultipleDropdown component
+ *
+ * A dropdown that supports selecting one or more options from a list.
+ * In multi-select mode (`isMultiple=true`) options toggle independently and
+ * a `+N` badge is shown for overflow. In single-select mode the menu closes
+ * after a pick. Forwards its ref to the root container div.
+ *
+ * @example
+ * ```tsx
+ * <MultipleDropdown
+ *   label="Fruits"
+ *   selectedItems={[{ value: 'apple' }]}
+ *   onChange={(value, isSelected) => handleChange(value, isSelected)}
+ * >
+ *   <DropdownOption value="apple">Apple</DropdownOption>
+ *   <DropdownOption value="banana">Banana</DropdownOption>
+ * </MultipleDropdown>
+ * ```
+ */
 export type DropdownProps<P extends DropdownOptionProps> = {
+    /**
+     * List of currently selected items
+     * Each entry must match one of the DropdownOption values
+     * @default []
+     */
     selectedItems?: P[];
+    /**
+     * Enables multi-select mode — each option toggles independently.
+     * When `false` the dropdown behaves like a single-select and closes on pick.
+     * @default true
+     */
     isMultiple?: boolean;
+    /**
+     * Disables the dropdown, preventing any user interaction
+     * @default false
+     */
     isDisabled?: boolean;
+    /**
+     * Placeholder shown in the toggle button when no item is selected
+     * @default 'Select something'
+     */
     placeholder?: string;
+    /**
+     * When `true` the placeholder value is included in the displayed list.
+     * Set to `false` to hide it and show only the badge count.
+     * @default true
+     */
     showPlaceholder?: boolean;
+    /**
+     * DropdownOption components to render as selectable items
+     */
     children?: React.ReactNode;
+    /**
+     * Custom CSS class name forwarded to the toggle button.
+     * Useful for styling via `styled(MultipleDropdown)`.
+     */
     className?: string;
+    /**
+     * Controlled open state — when provided, overrides internal open/close logic
+     */
     isOpen?: boolean;
+    /**
+     * Label prefix shown in the toggle button before the selected value(s)
+     * e.g. `label="Strategy"` renders "Strategy: Value"
+     */
     label?: string;
+    /**
+     * Callback fired when an option is toggled
+     * @param selectedItem - The value of the toggled option
+     * @param isSelected   - `true` if the option was just selected, `false` if deselected
+     */
     onChange?: (selectedItem: string | number, isSelected: boolean) => void;
 };
+/**
+ * Context value shared with child DropdownOption components via MultipleDropdownContext
+ */
 export interface DropdownContextType<T extends DropdownOptionProps> {
+    /**
+     * Function called when an option is clicked
+     */
     onChange: (item: T) => void;
+    /**
+     * Whether multi-select mode is active
+     */
     isMultiple?: boolean;
+    /**
+     * Map of all option values to their current state (including `isSelected`)
+     */
     allItems: Record<string | number, T>;
 }

package/dist/components/NavBar/types.d.ts

@@ -8,7 +8,7 @@ export interface NavBarProps {
 export type CustomIconProps = (props: {
     className?: string;
     showIconTooltip?: boolean;
-}) => JSX.Element;
+}) => React.JSX.Element;
 export type NavBarExtendedItem = {
     CustomIcon?: CustomIconProps;
     path: string;

package/dist/components/NotificationMenu/types.d.ts

@@ -1,10 +1,10 @@
 import { NotificationCardProps } from '../NotificationCard';
 export interface NotificationMenuProps {
-    trigger: string | JSX.Element;
+    trigger: string | React.JSX.Element;
     notifications: Array<NotificationCardProps>;
     children: React.ReactNode;
     onClick?: () => void;
     isLoading: boolean;
-    leftButton?: string | JSX.Element | null;
-    rightButton?: string | JSX.Element;
+    leftButton?: string | React.JSX.Element | null;
+    rightButton?: string | React.JSX.Element;
 }

package/dist/components/Pagination/ArrowButton.d.ts

@@ -1,2 +1,34 @@
 import { ArrowButtonProps } from './types';
+/**
+ * ArrowButton - Navigation arrow button for pagination
+ *
+ * Internal component used by Pagination to render previous/next navigation arrows.
+ * Displays a button with a carrot icon pointing left or right. Used for navigating
+ * between pages in the pagination component.
+ *
+ * @category Components
+ * @subcategory Navigation
+ *
+ * @example
+ * ```tsx
+ * // Used internally by Pagination component
+ * <ArrowButton
+ *   direction="left"
+ *   onClick={() => goToPreviousPage()}
+ *   isDisabled={isFirstPage}
+ * />
+ * ```
+ *
+ * @see {@link Pagination} - Parent component that uses this component
+ * @see {@link ArrowButtonProps} - Props interface
+ *
+ * @internal
+ * This component is not exported from the main index and is intended for
+ * internal use within the Pagination component.
+ *
+ * @accessibility
+ * - ARIA label set automatically based on direction
+ * - Keyboard navigation support via Button component
+ * - Screen reader friendly
+ */
 export declare const ArrowButton: ({ direction, onClick, isDisabled, className, }: ArrowButtonProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/Pagination/Pagination.d.ts

@@ -1,3 +1,84 @@
 import { PaginationProps } from './types';
+/**
+ * Pagination - Navigation controls for paginated data
+ *
+ * A comprehensive pagination component that provides navigation controls for
+ * paginated content. Supports page navigation with arrow buttons and numbered
+ * page buttons, optional manual page input, and optional rows per page selection.
+ * Uses PaginationContextProvider to manage page state and navigation.
+ *
+ * Component structure:
+ * - PaginationContextProvider (manages page state - required)
+ *   - Pagination (main component)
+ *     - RowsPerPageDropdown (optional)
+ *     - PageNumberInput (optional)
+ *     - ArrowButton (previous)
+ *     - PaginationButtons (numbered pages)
+ *     - ArrowButton (next)
+ *
+ * @category Components
+ * @subcategory Navigation
+ *
+ * @example
+ * ```tsx
+ * // Basic pagination
+ * <PaginationContextProvider selectedPage={1}>
+ *   <Pagination pagesCount={10} />
+ * </PaginationContextProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With rows per page dropdown
+ * <PaginationContextProvider selectedPage={1} defaultPerPage={25}>
+ *   <Pagination
+ *     pagesCount={20}
+ *     isRowPerPageVisible={true}
+ *     rowPerPageProps={{
+ *       rowsPerPageText: "Items per page",
+ *       rowsPerPageList: [
+ *         { id: 1, value: 10 },
+ *         { id: 2, value: 25 },
+ *         { id: 3, value: 50 },
+ *         { id: 4, value: 100 },
+ *       ],
+ *     }}
+ *   />
+ * </PaginationContextProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With manual page input
+ * <PaginationContextProvider selectedPage={3}>
+ *   <Pagination
+ *     pagesCount={15}
+ *     isPageSettingVisible={true}
+ *     pageNumberPlaceholder="Go to page"
+ *     errorTooltip="Please enter a valid page number"
+ *   />
+ * </PaginationContextProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled pagination
+ * <PaginationContextProvider selectedPage={5}>
+ *   <Pagination pagesCount={10} isDisabled />
+ * </PaginationContextProvider>
+ * ```
+ *
+ * @see {@link PaginationContextProvider} - Required context provider for state management
+ * @see {@link RowsPerPageDropdown} - Optional component for rows per page selection
+ *
+ * @requires PaginationContextProvider - Must be wrapped in PaginationContextProvider
+ *
+ * @accessibility
+ * - ARIA navigation role and labels
+ * - Keyboard navigation support (Enter for page input)
+ * - Arrow keys navigation (via arrow buttons)
+ * - Screen reader friendly
+ * - Proper focus management
+ */
 declare const Pagination: ({ pagesCount, className, as, ariaLabel, isDisabled, pageNumberPlaceholder, errorTooltip, isPageSettingVisible, isPageFromCountVisible, isRowPerPageVisible, rowPerPageProps, manualPageNumberProps, }: PaginationProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Pagination;

package/dist/components/Pagination/PaginationButtons.d.ts

@@ -1,2 +1,37 @@
 import { PaginationButtonsProps } from './types';
+/**
+ * PaginationButtons - Container component for page number buttons
+ *
+ * Internal component used by Pagination to render numbered page buttons.
+ * Displays a range of page numbers with ellipsis breaks for large page counts.
+ * Handles page selection and visual state (selected/disabled).
+ *
+ * @category Components
+ * @subcategory Navigation
+ *
+ * @example
+ * ```tsx
+ * // Used internally by Pagination component
+ * <PaginationButtons
+ *   range={[1, 2, 3, -1, 10]}  // -1 represents ellipsis break
+ *   selectedPage={2}
+ *   onClick={(page) => setPage(page)}
+ *   isDisabled={false}
+ * />
+ * ```
+ *
+ * @see {@link Pagination} - Parent component that uses this component
+ * @see {@link PaginationButtonsProps} - Props interface
+ * @see {@link PageButton} - Internal component for individual buttons
+ *
+ * @internal
+ * This component is not exported from the main index and is intended for
+ * internal use within the Pagination component.
+ *
+ * @accessibility
+ * - ARIA labels and current state via PageButton components
+ * - Keyboard navigation support via Button components
+ * - Screen reader friendly
+ * - Proper focus management
+ */
 export declare const PaginationButtons: ({ range, selectedPage, onClick, isDisabled, }: PaginationButtonsProps) => false | import("@emotion/react/jsx-runtime").JSX.Element[];

package/dist/components/Pagination/PaginationContext.d.ts

@@ -1,4 +1,34 @@
 import { PaginationContextProps, PaginationContextProviderProps } from './types';
+/**
+ * Pagination context
+ * Provides page state and navigation functions to child components
+ */
 export declare const PaginationContext: import("react").Context<PaginationContextProps>;
+/**
+ * Hook to access pagination context
+ * Must be used within PaginationContextProvider
+ *
+ * @returns Pagination context value with page state and navigation functions
+ * @throws Error if used outside PaginationContextProvider
+ */
 export declare const usePaginationContext: () => PaginationContextProps;
+/**
+ * PaginationContextProvider - Context provider for pagination state
+ *
+ * Provides pagination state (current page, items per page) and navigation
+ * functions to child components. Required wrapper for Pagination component.
+ *
+ * @category Components
+ * @subcategory Navigation
+ *
+ * @example
+ * ```tsx
+ * <PaginationContextProvider selectedPage={1} defaultPerPage={25}>
+ *   <Pagination pagesCount={10} />
+ * </PaginationContextProvider>
+ * ```
+ *
+ * @see {@link Pagination} - Child component that uses this context
+ * @see {@link usePaginationContext} - Hook to access context values
+ */
 export declare const PaginationContextProvider: ({ selectedPage, defaultPerPage, children, }: PaginationContextProviderProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/Pagination/WithPagination.d.ts

@@ -1,4 +1,47 @@
-export declare const WithPagination: <T extends object>(Component: React.ComponentType<T>) => {
-    (props: T): import("@emotion/react/jsx-runtime").JSX.Element;
-    displayName: string;
-};
+import React from 'react';
+/**
+ * WithPagination - Higher-order component that wraps a component with PaginationContextProvider
+ *
+ * A higher-order component (HOC) that automatically wraps a component with
+ * PaginationContextProvider, providing pagination context to all child components.
+ * Useful for simplifying pagination setup when you want to provide context
+ * at a component level.
+ *
+ * @category Components
+ * @subcategory Navigation
+ *
+ * @example
+ * ```tsx
+ * const MyComponent = () => {
+ *   return <div>Content with pagination</div>;
+ * };
+ *
+ * export const MyPaginationComponent = WithPagination(MyComponent);
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Used in page components
+ * const BotsPageComponent = () => {
+ *   return (
+ *     <div>
+ *       <BotsTable />
+ *       <Pagination pagesCount={10} />
+ *     </div>
+ *   );
+ * };
+ *
+ * export const BotsPage = WithPagination(BotsPageComponent);
+ * ```
+ *
+ * @see {@link PaginationContextProvider} - Context provider used internally
+ * @see {@link Pagination} - Component that uses the pagination context
+ *
+ * @note The HOC always initializes with selectedPage={1}
+ * @note Prop types may not work correctly with emotion due to known issue
+ *
+ * @template T - Props type of the wrapped component
+ * @param Component - Component to wrap with PaginationContextProvider
+ * @returns Wrapped component with pagination context
+ */
+export declare const WithPagination: <T extends object>(Component: React.ComponentType<T>) => React.ComponentType<T>;

package/dist/components/Pagination/components/RowsPerPageDropdown/RowsPerPageDropdown.d.ts

@@ -1,2 +1,43 @@
 import { RowsPerPageDropdownProps } from './types';
+/**
+ * RowsPerPageDropdown - Dropdown component for selecting rows per page
+ *
+ * A dropdown component that allows users to select the number of rows
+ * displayed per page in paginated data. Used within Pagination component
+ * when isRowPerPageVisible is true. Requires PaginationContextProvider
+ * to access and update the perPage state.
+ *
+ * @category Components
+ * @subcategory Navigation
+ *
+ * @example
+ * ```tsx
+ * <PaginationContextProvider selectedPage={1} defaultPerPage={25}>
+ *   <Pagination
+ *     pagesCount={20}
+ *     isRowPerPageVisible={true}
+ *     rowPerPageProps={{
+ *       selectedItem: 25,
+ *       rowsPerPageText: "Items per page",
+ *       rowsPerPageList: [
+ *         { id: 1, value: 10 },
+ *         { id: 2, value: 25 },
+ *         { id: 3, value: 50 },
+ *       ],
+ *     }}
+ *   />
+ * </PaginationContextProvider>
+ * ```
+ *
+ * @see {@link Pagination} - Parent component that uses this component
+ * @see {@link PaginationContextProvider} - Required context provider
+ * @see {@link Dropdown} - Base dropdown component used internally
+ *
+ * @requires PaginationContextProvider - Must be used within PaginationContextProvider
+ *
+ * @accessibility
+ * - ARIA attributes via Dropdown component
+ * - Keyboard navigation support
+ * - Screen reader friendly
+ */
 export declare const RowsPerPageDropdown: ({ selectedItem, rowsPerPageList, rowsPerPageText, ...rest }: RowsPerPageDropdownProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/Pagination/components/RowsPerPageDropdown/types.d.ts

@@ -1,7 +1,46 @@
 import { CommonProps } from '../../../../types/emotion';
+/**
+ * Props for the RowsPerPageDropdown component
+ *
+ * A dropdown component that allows users to select the number of rows
+ * displayed per page in paginated data. Used within Pagination component
+ * to control items per page. Requires PaginationContextProvider.
+ *
+ * @example
+ * ```tsx
+ * <PaginationContextProvider selectedPage={1} defaultPerPage={25}>
+ *   <Pagination
+ *     pagesCount={20}
+ *     isRowPerPageVisible={true}
+ *     rowPerPageProps={{
+ *       selectedItem: 25,
+ *       rowsPerPageText: "Items per page",
+ *       rowsPerPageList: [
+ *         { id: 1, value: 10 },
+ *         { id: 2, value: 25 },
+ *         { id: 3, value: 50 },
+ *       ],
+ *     }}
+ *   />
+ * </PaginationContextProvider>
+ * ```
+ */
 export interface RowsPerPageDropdownProps extends CommonProps {
+    /**
+     * Currently selected number of rows per page
+     * Must match a value in rowsPerPageList
+     */
     selectedItem?: number;
+    /**
+     * Label text displayed before the dropdown
+     * @default 'Rows per page'
+     */
     rowsPerPageText?: string;
+    /**
+     * Array of available rows per page options
+     * Each item must have id and value properties
+     * @default [{ id: 1, value: 10 }, { id: 2, value: 25 }, { id: 3, value: 50 }, { id: 4, value: 100 }]
+     */
     rowsPerPageList?: Array<{
         id: number;
         value: number;

package/dist/components/Pagination/styles.d.ts

@@ -6,6 +6,6 @@ export declare const PaginationNav: import("@emotion/styled").StyledComponent<{
     theme?: Theme;
     as?: React.ElementType;
 }, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLElement>, HTMLElement>, {}>;
-export declare const PageNumberInput: import("@emotion/styled").StyledComponent<import("../Input/types").InputProps & import("react").RefAttributes<HTMLInputElement> & {
+export declare const PageNumberInput: import("@emotion/styled").StyledComponent<import("..").InputProps & import("react").RefAttributes<HTMLInputElement> & {
     theme?: Theme;
 }, {}, {}>;

package/dist/components/Pagination/types.d.ts

@@ -1,44 +1,222 @@
 import { CommonProps } from '../../types/emotion';
 import { InputProps } from '../Input/types';
 import { RowsPerPageDropdownProps } from './components/RowsPerPageDropdown/types';
+/**
+ * Props for the Pagination component
+ *
+ * A comprehensive pagination component that provides navigation controls for
+ * paginated data. Supports page navigation, manual page input, and rows per page
+ * selection. Requires PaginationContextProvider to manage page state.
+ *
+ * @example
+ * ```tsx
+ * <PaginationContextProvider selectedPage={1}>
+ *   <Pagination pagesCount={10} />
+ * </PaginationContextProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With rows per page dropdown
+ * <PaginationContextProvider selectedPage={1} defaultPerPage={25}>
+ *   <Pagination
+ *     pagesCount={20}
+ *     isRowPerPageVisible={true}
+ *     rowPerPageProps={{
+ *       rowsPerPageList: [
+ *         { id: 1, value: 10 },
+ *         { id: 2, value: 25 },
+ *         { id: 3, value: 50 },
+ *       ],
+ *     }}
+ *   />
+ * </PaginationContextProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With manual page input
+ * <PaginationContextProvider selectedPage={3}>
+ *   <Pagination
+ *     pagesCount={15}
+ *     isPageSettingVisible={true}
+ *     pageNumberPlaceholder="Go to page"
+ *   />
+ * </PaginationContextProvider>
+ * ```
+ */
 export interface PaginationProps extends CommonProps {
+    /**
+     * Total number of pages
+     * Required to calculate page range and navigation limits
+     */
     pagesCount: number;
+    /**
+     * ARIA label for the pagination navigation
+     * @default 'Pagination'
+     */
     ariaLabel?: string;
+    /**
+     * Whether the pagination is disabled
+     * Disabled pagination prevents all navigation actions
+     * @default false
+     */
     isDisabled?: boolean;
+    /**
+     * Placeholder text for manual page input
+     * Only shown when isPageSettingVisible is true
+     * @default 'Page №'
+     */
     pageNumberPlaceholder?: string;
+    /**
+     * Whether to show manual page number input
+     * Allows users to jump directly to a specific page
+     * @default false
+     */
     isPageSettingVisible?: boolean;
+    /**
+     * Whether to show rows per page dropdown
+     * Allows users to control how many items are displayed per page
+     * @default false
+     */
     isRowPerPageVisible?: boolean;
+    /**
+     * Whether to show page count display (e.g., "3 / 15")
+     * Only shown when isPageSettingVisible is true
+     * @default true
+     */
     isPageFromCountVisible?: boolean;
+    /**
+     * Props for the rows per page dropdown
+     * Only used when isRowPerPageVisible is true
+     */
     rowPerPageProps?: RowsPerPageDropdownProps;
+    /**
+     * Props for the manual page number input
+     * Only used when isPageSettingVisible is true
+     */
     manualPageNumberProps?: InputProps;
+    /**
+     * Error tooltip message for invalid page number input
+     * @default 'The value is out of range'
+     */
     errorTooltip?: string;
 }
+/**
+ * Props for PaginationButtons component
+ * Internal component that renders the numbered page buttons
+ */
 export interface PaginationButtonsProps {
+    /**
+     * Array of page numbers to display
+     */
     range: number[];
+    /**
+     * Currently selected page number
+     */
     selectedPage?: number;
+    /**
+     * Callback function when a page button is clicked
+     */
     onClick: (page: number) => void;
+    /**
+     * Whether the buttons are disabled
+     * @default false
+     */
     isDisabled?: boolean;
 }
+/**
+ * Props for ArrowButton component
+ * Internal component for previous/next navigation arrows
+ */
 export interface ArrowButtonProps {
+    /**
+     * Direction of the arrow button
+     */
     direction: 'left' | 'right';
+    /**
+     * Callback function when arrow button is clicked
+     */
     onClick: () => void;
+    /**
+     * Whether the button is disabled
+     * @default false
+     */
     isDisabled?: boolean;
+    /**
+     * Custom CSS class name
+     */
     className?: string;
 }
+/**
+ * Props for PageButton component
+ * Internal component for individual page number buttons
+ */
 export interface PageButtonProps {
+    /**
+     * Callback function when page button is clicked
+     */
     onClick: () => void;
+    /**
+     * Page number or ellipsis string to display
+     */
     page: number | string;
+    /**
+     * Whether this page is currently selected
+     */
     isSelected: boolean;
+    /**
+     * Whether the button is disabled
+     * @default false
+     */
     isDisabled?: boolean;
 }
+/**
+ * Pagination context value
+ * Provides page state and navigation functions to child components
+ */
 export interface PaginationContextProps {
+    /**
+     * Current page number (1-indexed)
+     */
     page?: number;
+    /**
+     * Number of items per page
+     */
     perPage: number;
+    /**
+     * Function to set the current page number
+     */
     setPage: React.Dispatch<React.SetStateAction<number | undefined>>;
+    /**
+     * Function to set the number of items per page
+     */
     setPerPage: React.Dispatch<React.SetStateAction<number>>;
 }
+/**
+ * Props for PaginationContextProvider component
+ * Context provider that manages pagination state for child components
+ *
+ * @example
+ * ```tsx
+ * <PaginationContextProvider selectedPage={1} defaultPerPage={25}>
+ *   <Pagination pagesCount={10} />
+ * </PaginationContextProvider>
+ * ```
+ */
 export interface PaginationContextProviderProps {
+    /**
+     * Initial selected page number (1-indexed)
+     */
     selectedPage?: number;
+    /**
+     * Default number of items per page
+     * @default 10
+     */
     defaultPerPage?: number;
+    /**
+     * Child components that use pagination context
+     * Must include Pagination component
+     */
     children: React.ReactNode;
 }