@ssa-ui-kit/core 2.33.0 → 3.1.0

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

package/dist/components/Radio/Radio.d.ts

@@ -1,3 +1,71 @@
 import { RadioProps } from './types';
-declare const Radio: ({ id, name, value, isChecked, isDisabled, isRequired, text, colors, className, onChange, }: RadioProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+/**
+ * Radio - Radio button component for single selection
+ *
+ * A radio button component for selecting a single option from a group.
+ * Supports controlled and uncontrolled states, palette-based color variants,
+ * and full accessibility. Displays a radio icon that changes appearance based
+ * on checked state and hover interactions.
+ *
+ * Colors are sourced from `theme.palette` for consistency with Button and
+ * Checkbox. Pass `color="custom"` together with the `colors` object to supply
+ * arbitrary CSS color values.
+ *
+ * Typically used within RadioGroup for managing selection state across
+ * multiple radio buttons, but can also be used standalone.
+ *
+ * @category Form Controls
+ * @subcategory Input
+ *
+ * @example
+ * ```tsx
+ * // Default (primary / blue)
+ * <Radio
+ *   id="option1"
+ *   name="choice"
+ *   value="option1"
+ *   text="Option 1"
+ *   onChange={(value) => console.log(value)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Success (green) variant
+ * <Radio
+ *   name="status"
+ *   value="active"
+ *   text="Active"
+ *   color="success"
+ *   onChange={handleChange}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom color escape hatch
+ * <Radio
+ *   name="priority"
+ *   value="high"
+ *   text="High Priority"
+ *   color="custom"
+ *   colors={{
+ *     default: '#ff0000',
+ *     hovered: '#cc0000',
+ *     disabled: '#cccccc',
+ *     focusShadow: 'rgba(255,0,0,0.25)',
+ *   }}
+ *   onChange={handleChange}
+ * />
+ * ```
+ *
+ * @see {@link RadioGroup} - For managing groups of radio buttons
+ *
+ * @accessibility
+ * - Full keyboard navigation (Arrow keys to navigate group, Space to select)
+ * - Proper ARIA attributes (role="radio", aria-checked)
+ * - Screen reader friendly
+ * - Focus management with visible focus indicators
+ */
+declare const Radio: ({ id, name, value, isChecked, isDisabled, isRequired, text, color, colors, className, onChange, }: RadioProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Radio;

package/dist/components/Radio/RadioBase.d.ts

@@ -1,4 +1,4 @@
-export declare const RadioBase: import("@emotion/styled").StyledComponent<import("../Label/types").LabelProps & {
+export declare const RadioBase: import("@emotion/styled").StyledComponent<import("..").LabelProps & {
     theme?: import("@emotion/react").Theme;
 } & {
     focusShadowColor?: string;

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

@@ -1,17 +1,126 @@
+/**
+ * Props for the Radio component
+ *
+ * Radio button component for single selection from a group of options.
+ * Supports controlled and uncontrolled states, palette-based color variants,
+ * and full accessibility. Typically used within RadioGroup for managing
+ * selection state.
+ *
+ * Colors are driven by `theme.palette`:
+ * - `primary` (default) — blue; uses `palette.primary.main` for resting/checked,
+ *   `palette.primary.dark` for hover.
+ * - `success` — green; uses `palette.success.main` for resting/checked,
+ *   `palette.success.dark` for hover.
+ * - `custom` — no built-in color; provide exact values via the `colors` object.
+ *
+ * @example
+ * ```tsx
+ * // Basic radio button (primary / blue by default)
+ * <Radio
+ *   id="option1"
+ *   name="choice"
+ *   value="option1"
+ *   text="Option 1"
+ *   onChange={(value) => handleChange(value)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Success (green) variant
+ * <Radio
+ *   name="status"
+ *   value="active"
+ *   text="Active"
+ *   color="success"
+ *   onChange={(value) => handleChange(value)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom color via escape hatch
+ * <Radio
+ *   name="priority"
+ *   value="high"
+ *   text="High Priority"
+ *   color="custom"
+ *   colors={{
+ *     default: '#ff0000',
+ *     hovered: '#cc0000',
+ *     disabled: '#cccccc',
+ *     focusShadow: 'rgba(255, 0, 0, 0.25)',
+ *   }}
+ *   onChange={(value) => handleChange(value)}
+ * />
+ * ```
+ */
 export interface RadioProps {
+    /**
+     * Unique identifier for the radio input
+     * If not provided, a unique ID will be auto-generated
+     */
     id?: string;
+    /**
+     * Value of the radio button
+     * Passed to onChange callback when selected
+     */
     value: string;
+    /**
+     * Name attribute for grouping radio buttons
+     * Radio buttons with the same name form a group
+     * @default ''
+     */
     name?: string;
+    /**
+     * Whether the radio button is checked
+     * Use for controlled component pattern
+     */
     isChecked?: boolean;
+    /**
+     * Whether the radio button is disabled
+     * Disabled radios cannot be selected
+     * @default false
+     */
     isDisabled?: boolean;
+    /**
+     * Whether the radio button is required for form validation
+     * @default false
+     */
     isRequired?: boolean;
+    /**
+     * Callback function called when radio is selected
+     * Receives the radio's value as parameter
+     */
     onChange?: (value: string) => void;
+    /**
+     * Label text displayed next to the radio button
+     */
     text?: string;
+    /**
+     * Custom CSS class name
+     */
     className?: string;
+    /**
+     * Palette-based color variant.
+     * - `primary` — blue (uses `palette.primary`)
+     * - `success` — green (uses `palette.success`)
+     * - `custom` — unstyled; supply exact colors via the `colors` prop
+     * @default 'primary'
+     */
+    color?: 'primary' | 'success' | 'custom';
+    /**
+     * Fine-grained color overrides — only applied when `color="custom"`.
+     * Allows overriding every interactive state independently.
+     */
     colors?: {
+        /** Resting (and checked) icon color */
         default?: string;
+        /** Hover icon color */
         hovered?: string;
+        /** Disabled state icon color */
         disabled?: string;
+        /** Focus ring drop-shadow color */
         focusShadow?: string;
     };
 }

package/dist/components/RadioGroup/RadioGroup.d.ts

@@ -1,3 +1,3 @@
 import { RadioGroupProps } from './types';
-declare const RadioGroup: ({ name, isRequired, externalState, onChange, children, className, }: RadioGroupProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+declare const RadioGroup: ({ name, isRequired, externalState, onChange, children, className, color, }: RadioGroupProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default RadioGroup;

package/dist/components/RadioGroup/index.d.ts

@@ -1 +1,2 @@
 export { default } from './RadioGroup';
+export type * from './types';