@ssa-ui-kit/core 2.33.0 → 3.0.0

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;
 }

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

@@ -58,7 +58,7 @@ export declare const BadgeWrapper: import("@emotion/styled").StyledComponent<{
     theme?: Theme;
     as?: React.ElementType;
 }, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
-export declare const StyledBadge: import("@emotion/styled").StyledComponent<Omit<Omit<import("react").HTMLProps<HTMLDivElement>, "size"> & import("../Badge/types").BadgeProps, "ref"> & import("react").RefAttributes<HTMLDivElement> & {
+export declare const StyledBadge: import("@emotion/styled").StyledComponent<Omit<Omit<import("react").HTMLProps<HTMLDivElement>, "size"> & import("..").BadgeProps, "ref"> & import("react").RefAttributes<HTMLDivElement> & {
     theme?: Theme;
 }, {}, {}>;
 export declare const CustomBadge: import("@emotion/styled").StyledComponent<{

package/dist/components/Popover/Popover.d.ts

@@ -1,5 +1,125 @@
 import * as React from 'react';
 import { PopoverOptions } from './types';
+/**
+ * Popover - Floating content container component
+ *
+ * A flexible popover system built on Floating UI that provides floating content
+ * containers relative to trigger elements. Uses a compound component pattern with
+ * Popover (root), PopoverTrigger (activator), PopoverContent (display),
+ * PopoverHeading, PopoverDescription, and PopoverClose (content helpers).
+ *
+ * Supports multiple interaction modes (click, hover, both), flexible positioning
+ * with auto-adjustment via Floating UI middleware, modal and non-modal modes,
+ * and comprehensive accessibility features including ARIA attributes and focus
+ * management.
+ *
+ * @category Components
+ * @subcategory Overlay
+ *
+ * @example
+ * ```tsx
+ * // Basic popover on click
+ * <Popover>
+ *   <PopoverTrigger>
+ *     <Button>Open Popover</Button>
+ *   </PopoverTrigger>
+ *   <PopoverContent>
+ *     <PopoverHeading variant="h4">Popover Title</PopoverHeading>
+ *     <PopoverDescription>
+ *       This is the popover content with helpful information.
+ *     </PopoverDescription>
+ *     <PopoverClose>Close</PopoverClose>
+ *   </PopoverContent>
+ * </Popover>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Popover with hover interaction
+ * <Popover interactionsEnabled="hover">
+ *   <PopoverTrigger>
+ *     <Icon name="info" />
+ *   </PopoverTrigger>
+ *   <PopoverContent>
+ *     <PopoverHeading variant="h4">Information</PopoverHeading>
+ *     <PopoverDescription>
+ *       This popover appears on hover.
+ *     </PopoverDescription>
+ *   </PopoverContent>
+ * </Popover>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Popover with custom placement
+ * <Popover placement="top">
+ *   <PopoverTrigger>
+ *     <Button>Show Above</Button>
+ *   </PopoverTrigger>
+ *   <PopoverContent>
+ *     <PopoverDescription>
+ *       This popover appears above the trigger element.
+ *     </PopoverDescription>
+ *     <PopoverClose>Close</PopoverClose>
+ *   </PopoverContent>
+ * </Popover>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Advanced positioning with Floating UI middleware
+ * <Popover
+ *   placement="top"
+ *   floatingOptions={{
+ *     middleware: [
+ *       offset(10),
+ *       flip(),
+ *       shift({ padding: 8 }),
+ *     ],
+ *   }}>
+ *   <PopoverTrigger>
+ *     <Button>Smart Positioning</Button>
+ *   </PopoverTrigger>
+ *   <PopoverContent>
+ *     <PopoverHeading variant="h4">Smart Positioning</PopoverHeading>
+ *     <PopoverDescription>
+ *       This popover automatically adjusts its position to stay in view.
+ *     </PopoverDescription>
+ *     <PopoverClose>Close</PopoverClose>
+ *   </PopoverContent>
+ * </Popover>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Modal popover with controlled state
+ * <Popover modal open={isOpen} onOpenChange={setIsOpen}>
+ *   <PopoverTrigger>
+ *     <Button>Open Modal Popover</Button>
+ *   </PopoverTrigger>
+ *   <PopoverContent>
+ *     <PopoverHeading variant="h4">Modal Popover</PopoverHeading>
+ *     <PopoverDescription>
+ *       This is a modal popover that traps focus.
+ *     </PopoverDescription>
+ *     <PopoverClose>Close</PopoverClose>
+ *   </PopoverContent>
+ * </Popover>
+ * ```
+ *
+ * @see {@link PopoverTrigger} - Trigger element component
+ * @see {@link PopoverContent} - Content display component
+ * @see {@link PopoverHeading} - Accessible heading component
+ * @see {@link PopoverDescription} - Accessible description component
+ * @see {@link PopoverClose} - Close button component
+ *
+ * @accessibility
+ * - Keyboard accessible (ESC to close, Enter/Space to activate)
+ * - Focus management with FloatingFocusManager for modal popovers
+ * - ARIA attributes automatically applied (role, aria-labelledby, aria-describedby)
+ * - Screen reader friendly with semantic heading and description components
+ * - Focus trap for modal popovers
+ */
 export declare const Popover: ({ children, modal, ...restOptions }: {
     children: React.ReactNode;
 } & PopoverOptions) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/Popover/PopoverClose.d.ts

@@ -1,2 +1,28 @@
 import * as React from 'react';
+/**
+ * PopoverClose - Close button for popover
+ *
+ * Renders a button that closes the popover when clicked. Uses Button component
+ * with secondary variant by default. Automatically handles closing the popover
+ * and supports all standard button props.
+ *
+ * @category Components
+ * @subcategory Overlay
+ *
+ * @example
+ * ```tsx
+ * <PopoverClose>Close</PopoverClose>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom button text and styling
+ * <PopoverClose size="small" variant="primary">
+ *   Done
+ * </PopoverClose>
+ * ```
+ *
+ * @see {@link Popover} - Root component
+ * @see {@link PopoverContent} - Content container component
+ */
 export declare const PopoverClose: React.ForwardRefExoticComponent<React.ButtonHTMLAttributes<HTMLButtonElement> & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/Popover/PopoverContent.d.ts

@@ -1,5 +1,38 @@
 import * as React from 'react';
 import { MountMode } from './types';
+/**
+ * PopoverContent - Content container for popover
+ *
+ * Renders the actual popover content that appears when the trigger is activated.
+ * Automatically positioned using Floating UI, supports portal rendering, and
+ * includes focus management for modal popovers. Can be configured to unmount
+ * or keep mounted when closed.
+ *
+ * @category Components
+ * @subcategory Overlay
+ *
+ * @example
+ * ```tsx
+ * <PopoverContent>
+ *   <PopoverHeading variant="h4">Title</PopoverHeading>
+ *   <PopoverDescription>Content goes here</PopoverDescription>
+ *   <PopoverClose>Close</PopoverClose>
+ * </PopoverContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Keep content mounted when closed
+ * <PopoverContent mountMode="keep-mounted">
+ *   <div>This stays in DOM when closed</div>
+ * </PopoverContent>
+ * ```
+ *
+ * @see {@link Popover} - Root component
+ * @see {@link PopoverTrigger} - Trigger element component
+ * @see {@link PopoverHeading} - Accessible heading component
+ * @see {@link PopoverDescription} - Accessible description component
+ */
 export declare const PopoverContent: React.ForwardRefExoticComponent<Omit<React.HTMLProps<HTMLDivElement> & {
     isFocusManagerDisabled?: boolean;
     mountMode?: MountMode;

package/dist/components/Popover/PopoverDescription.d.ts

@@ -1,2 +1,23 @@
 import * as React from 'react';
-export declare const PopoverDescription: React.ForwardRefExoticComponent<Omit<Omit<import("../Typography/types").TypographyProps, "ref"> & React.RefAttributes<HTMLElement>, "ref"> & React.RefAttributes<HTMLParagraphElement>>;
+/**
+ * PopoverDescription - Accessible description for popover
+ *
+ * Provides an accessible description for the popover content. Automatically sets
+ * `aria-describedby` on the PopoverContent when mounted. Uses Typography component
+ * for consistent styling and supports all Typography props.
+ *
+ * @category Components
+ * @subcategory Overlay
+ *
+ * @example
+ * ```tsx
+ * <PopoverDescription variant="body1">
+ *   This is the description text for the popover content.
+ * </PopoverDescription>
+ * ```
+ *
+ * @see {@link Popover} - Root component
+ * @see {@link PopoverContent} - Content container component
+ * @see {@link PopoverHeading} - Accessible heading component
+ */
+export declare const PopoverDescription: React.ForwardRefExoticComponent<Omit<Omit<import("..").TypographyProps, "ref"> & React.RefAttributes<HTMLElement>, "ref"> & React.RefAttributes<HTMLParagraphElement>>;

package/dist/components/Popover/PopoverHeading.d.ts

@@ -1,2 +1,23 @@
 import * as React from 'react';
-export declare const PopoverHeading: React.ForwardRefExoticComponent<Omit<Omit<import("../Typography/types").TypographyProps, "ref"> & React.RefAttributes<HTMLElement>, "ref"> & React.RefAttributes<HTMLHeadingElement>>;
+/**
+ * PopoverHeading - Accessible heading for popover
+ *
+ * Provides an accessible heading for the popover content. Automatically sets
+ * `aria-labelledby` on the PopoverContent when mounted. Uses Typography component
+ * for consistent styling and supports all Typography props.
+ *
+ * @category Components
+ * @subcategory Overlay
+ *
+ * @example
+ * ```tsx
+ * <PopoverHeading variant="h4">
+ *   Popover Title
+ * </PopoverHeading>
+ * ```
+ *
+ * @see {@link Popover} - Root component
+ * @see {@link PopoverContent} - Content container component
+ * @see {@link PopoverDescription} - Accessible description component
+ */
+export declare const PopoverHeading: React.ForwardRefExoticComponent<Omit<Omit<import("..").TypographyProps, "ref"> & React.RefAttributes<HTMLElement>, "ref"> & React.RefAttributes<HTMLHeadingElement>>;

package/dist/components/Popover/PopoverTrigger.d.ts

@@ -1,4 +1,34 @@
 import * as React from 'react';
 import { ButtonProps } from '../Button/types';
 import { PopoverTriggerProps } from './types';
+/**
+ * PopoverTrigger - Trigger element for popover
+ *
+ * Activates the popover when interacted with. By default renders as a Button,
+ * but can be customized using the `asChild` prop to render as any React element.
+ * Automatically receives Floating UI reference props for positioning and state
+ * management.
+ *
+ * @category Components
+ * @subcategory Overlay
+ *
+ * @example
+ * ```tsx
+ * // Default Button trigger
+ * <PopoverTrigger>
+ *   Open Popover
+ * </PopoverTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom element trigger
+ * <PopoverTrigger asChild>
+ *   <Icon name="info" />
+ * </PopoverTrigger>
+ * ```
+ *
+ * @see {@link Popover} - Root component
+ * @see {@link PopoverContent} - Content display component
+ */
 export declare const PopoverTrigger: React.ForwardRefExoticComponent<Omit<React.HTMLProps<HTMLElement> & ButtonProps & PopoverTriggerProps, "ref"> & React.RefAttributes<HTMLElement>>;

package/dist/components/Popover/hooks/usePopover.d.ts

@@ -1,2 +1,23 @@
 import { UsePopover } from '../types';
+/**
+ * usePopover - Hook for popover functionality
+ *
+ * Custom hook that provides popover state management, positioning, and interactions.
+ * Handles both controlled and uncontrolled modes, supports multiple interaction types
+ * (click, hover, both), and integrates with Floating UI for positioning and focus management.
+ *
+ * @param options - Popover configuration options
+ * @returns Popover context value with state, positioning, and interaction handlers
+ *
+ * @example
+ * ```tsx
+ * const popover = usePopover({
+ *   placement: 'top',
+ *   interactionsEnabled: 'click',
+ *   modal: false,
+ * });
+ * ```
+ *
+ * @see {@link Popover} - Component that uses this hook
+ */
 export declare const usePopover: UsePopover;

package/dist/components/Popover/hooks/usePopoverContext.d.ts

@@ -1,4 +1,27 @@
 import * as React from 'react';
 import { ContextType } from '../types';
+/**
+ * Context for popover components
+ *
+ * Provides popover state and functionality to child components. Created by
+ * Popover component and consumed by PopoverTrigger, PopoverContent, and other
+ * popover sub-components.
+ */
 export declare const PopoverContext: React.Context<ContextType>;
+/**
+ * usePopoverContext - Hook to access popover context
+ *
+ * Returns the popover context value. Throws an error if used outside of a
+ * Popover component.
+ *
+ * @returns Popover context value with state, positioning, and interaction handlers
+ * @throws Error if used outside of Popover component
+ *
+ * @example
+ * ```tsx
+ * const { open, setOpen, refs } = usePopoverContext();
+ * ```
+ *
+ * @see {@link Popover} - Component that provides this context
+ */
 export declare const usePopoverContext: () => ContextType;

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

@@ -1,23 +1,109 @@
 import { Placement, useInteractions, UseFloatingReturn, UseFloatingOptions } from '@floating-ui/react';
+/**
+ * Interaction modes for popover activation
+ * - `click`: Opens on click interaction (default)
+ * - `hover`: Opens on hover interaction
+ * - `both`: Opens on both click and hover interactions
+ */
 export type InteractionsEnabled = 'click' | 'hover' | 'both';
+/**
+ * Mount mode for popover content
+ * - `unmount`: Completely unmounts content when closed (default)
+ * - `keep-mounted`: Keeps content mounted but hidden when closed
+ */
 export type MountMode = 'unmount' | 'keep-mounted';
+/**
+ * Props for the Popover component
+ *
+ * Root container component for popover system using compound component pattern.
+ * Provides context and positioning configuration for PopoverTrigger, PopoverContent,
+ * PopoverHeading, PopoverDescription, and PopoverClose. Built on Floating UI for
+ * flexible positioning and interaction modes.
+ *
+ * @example
+ * ```tsx
+ * <Popover placement="top" interactionsEnabled="click">
+ *   <PopoverTrigger>
+ *     <Button>Open Popover</Button>
+ *   </PopoverTrigger>
+ *   <PopoverContent>
+ *     <PopoverHeading variant="h4">Title</PopoverHeading>
+ *     <PopoverDescription>This is a popover</PopoverDescription>
+ *     <PopoverClose>Close</PopoverClose>
+ *   </PopoverContent>
+ * </Popover>
+ * ```
+ */
 export interface PopoverOptions {
+    /**
+     * Initial open state for uncontrolled popover
+     * @default false
+     */
     initialOpen?: boolean;
+    /**
+     * Preferred placement of the popover relative to trigger
+     * Floating UI will auto-adjust if space is insufficient
+     * @default 'bottom'
+     */
     placement?: Placement;
+    /**
+     * Whether popover should behave as a modal (traps focus)
+     * @default false
+     */
     modal?: boolean;
+    /**
+     * Controlled open state
+     * When provided, controls popover visibility externally
+     */
     open?: boolean;
+    /**
+     * Additional Floating UI options for advanced positioning
+     * Allows customization of middleware, strategy, and other Floating UI settings
+     */
     floatingOptions?: Partial<UseFloatingOptions>;
+    /**
+     * Interaction mode for popover activation
+     * @default 'click'
+     */
     interactionsEnabled?: InteractionsEnabled;
+    /**
+     * Enable keyboard handlers for interactions
+     * @default true
+     */
     keyboardHandlers?: boolean;
+    /**
+     * Callback fired when open state changes
+     */
     onOpenChange?: (open: boolean) => void;
 }
 export type SetIDs = {
     setLabelId: React.Dispatch<React.SetStateAction<string | undefined>>;
     setDescriptionId: React.Dispatch<React.SetStateAction<string | undefined>>;
 };
+/**
+ * Props for PopoverTrigger component
+ *
+ * Trigger element that activates the popover. Can render as a Button (default) or
+ * as a custom element when using `asChild` prop. Automatically receives Floating UI
+ * reference props for positioning. Extends ButtonProps so you can pass Button props
+ * such as variant (default `primary`), size, css, etc.
+ */
 export interface PopoverTriggerProps {
+    /**
+     * Content to render as trigger
+     * When `asChild` is true, must be a single React element
+     */
     children?: React.ReactNode;
+    /**
+     * Render trigger as child element instead of Button
+     * When true, clones the child element and applies trigger props
+     * @default false
+     */
     asChild?: boolean;
+    /**
+     * Test ID for the trigger element
+     * @default 'trigger-button'
+     */
     dataTestId?: string;
 }
 type UseInteractions = ReturnType<typeof useInteractions>;