@ssa-ui-kit/core 2.33.0 → 3.0.0

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

@@ -1,30 +1,110 @@
 import { useInteractions, FloatingArrow, Placement, UseFloatingReturn, OffsetOptions } from '@floating-ui/react';
-import { PointTooltipProps, Point } from '@nivo/line';
+import { PointTooltipProps, Point, LineSeries } from '@nivo/line';
 import { MapIconsType } from '../Icon/types';
 import { ProgressBarProps } from '../ProgressBar/types';
 import { SerializedStyles } from '@emotion/react';
 import { CommonProps } from '../../types/emotion';
+/**
+ * Size variant for tooltip content
+ * - `small`: Compact tooltip with minimal padding
+ * - `medium`: Standard tooltip size (default)
+ * - `large`: Larger tooltip for more content
+ */
 export type TooltipSize = 'small' | 'medium' | 'large';
+/**
+ * Props for the Tooltip component
+ *
+ * Root container component for tooltip system using compound component pattern.
+ * Provides context and positioning configuration for TooltipTrigger and TooltipContent.
+ * Built on Floating UI for flexible positioning and interaction modes.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip placement="top">
+ *   <TooltipTrigger>
+ *     <Button>Hover me</Button>
+ *   </TooltipTrigger>
+ *   <TooltipContent>This is a tooltip</TooltipContent>
+ * </Tooltip>
+ * ```
+ */
 export interface TooltipProps extends CommonProps {
+    /**
+     * TooltipTrigger and TooltipContent components
+     * Must include both TooltipTrigger and TooltipContent as children
+     */
     children: React.ReactNode;
+    /**
+     * Preferred placement of the tooltip relative to trigger
+     * Floating UI will auto-adjust if space is insufficient
+     */
     placement?: Placement;
+    /**
+     * Enable tooltip on hover interaction
+     * @default true
+     */
     enableHover?: boolean;
+    /**
+     * Enable tooltip on click interaction
+     * @default false
+     */
     enableClick?: boolean;
+    /**
+     * Enable tooltip to follow client point (mouse position)
+     * Useful for interactive tooltips like charts
+     * @default false
+     */
     enableClientPoint?: boolean;
+    /**
+     * Offset configuration for tooltip positioning
+     * Allows fine-tuning of spacing from trigger element
+     */
     offsetOptions?: OffsetOptions;
+    /**
+     * Allow hovering over tooltip content itself
+     * When true, tooltip stays open when hovering over content
+     * @default false
+     */
     allowHoverContent?: boolean;
+    /**
+     * Delay in milliseconds before tooltip appears on hover
+     * Helps prevent "traffic light" effect when quickly moving through multiple tooltips
+     * @default 0
+     */
+    hoverOpenDelay?: number;
+    /**
+     * Delay in milliseconds before tooltip disappears after mouse leaves
+     * Helps prevent tooltip from flickering when moving between trigger and content
+     * @default 0
+     */
+    hoverCloseDelay?: number;
+    /**
+     * Size variant of the tooltip content
+     * @default 'medium'
+     */
     size?: TooltipSize;
+    /**
+     * Whether to display arrow pointing to trigger
+     * @default true
+     */
     hasArrow?: boolean;
+    /**
+     * Additional props for the arrow element
+     */
     arrowProps?: TooltipArrowProps;
+    /**
+     * Controlled open state
+     * When provided, controls tooltip visibility externally
+     */
     isOpen?: boolean;
 }
 export type UseTooltipArgs = Omit<TooltipProps, 'children'>;
 type UseInteractions = ReturnType<typeof useInteractions>;
-interface MutableRefObject<T> {
+interface RefObject<T> {
     current: T;
 }
 export type UseTooltip = (props?: UseTooltipArgs) => Pick<TooltipProps, 'size' | 'hasArrow' | 'arrowProps'> & {
-    arrowRef: MutableRefObject<null>;
+    arrowRef: RefObject<null>;
     isOpen: boolean;
     setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;
 } & UseFloatingReturn & UseInteractions;
@@ -34,9 +114,26 @@ export type TooltipContextType = (UseFloatingReturn & ReturnType<typeof useInter
     setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;
 } & Pick<TooltipProps, 'size' | 'hasArrow' | 'arrowProps'>) | null;
 export type TooltipArrowProps = Omit<React.ComponentProps<typeof FloatingArrow>, 'context'>;
+/**
+ * Props for TooltipContent component
+ *
+ * Content container for tooltip. Renders the actual tooltip content that appears
+ * when the trigger is activated. Supports custom styling and is automatically
+ * positioned using Floating UI.
+ */
 export interface TooltipContentProps {
+    /**
+     * Tooltip content to display
+     * Can be text, React nodes, or formatted content
+     */
     children: React.ReactNode;
+    /**
+     * Custom CSS class name
+     */
     className?: string;
+    /**
+     * Inline styles for the tooltip content
+     */
     style?: React.CSSProperties;
 }
 export interface TooltipContentSizes {
@@ -44,12 +141,26 @@ export interface TooltipContentSizes {
     medium: SerializedStyles;
     large: SerializedStyles;
 }
+/**
+ * Props for TooltipTrigger component
+ *
+ * Trigger element that activates the tooltip. Must be a single React element
+ * (component or DOM element) that will receive the tooltip trigger props.
+ */
 export interface TooltipTriggerProps {
+    /**
+     * Single React element to use as trigger
+     * Can be any element (Button, Icon, div, etc.)
+     * Must be a valid React element (not fragment or array)
+     */
     children: React.ReactNode;
+    /**
+     * Custom CSS class name
+     */
     className?: string;
 }
-export type SimpleChartTooltipProps = PointTooltipProps & Pick<TooltipProps, 'size'> & {
-    renderValue?: (data: Point['data']) => React.ReactNode;
+export type SimpleChartTooltipProps<Series extends LineSeries> = PointTooltipProps<Series> & Pick<TooltipProps, 'size'> & {
+    renderValue?: (data: Point<Series>['data']) => React.ReactNode;
 };
 export interface ProgressChartTooltipProps {
     caption: string;

package/dist/components/TooltipContent/TooltipContent.d.ts

@@ -1,3 +1,48 @@
 import { TooltipContentProps } from '../Tooltip/types';
+/**
+ * TooltipContent - Content container for tooltip display
+ *
+ * Renders the actual tooltip content that appears when the trigger is activated.
+ * Uses Floating Portal for proper z-index stacking and FloatingFocusManager for
+ * keyboard accessibility. Automatically positions based on Floating UI context
+ * and respects size variants and arrow configuration.
+ *
+ * Only renders when tooltip is open (isOpen is true). Supports custom styling
+ * and can contain any React content.
+ *
+ * @category Components
+ * @subcategory Overlay
+ *
+ * @example
+ * ```tsx
+ * <Tooltip>
+ *   <TooltipTrigger>
+ *     <Button>Info</Button>
+ *   </TooltipTrigger>
+ *   <TooltipContent>
+ *     This is the tooltip content
+ *   </TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Tooltip with custom styling
+ * <TooltipContent style={{ padding: 16, maxWidth: 300 }}>
+ *   <div>
+ *     <strong>Title</strong>
+ *     <p>Detailed description here</p>
+ *   </div>
+ * </TooltipContent>
+ * ```
+ *
+ * @see {@link Tooltip} - Parent component that provides context
+ * @see {@link TooltipTrigger} - Trigger component that activates tooltip
+ *
+ * @accessibility
+ * - Renders in FloatingPortal for proper stacking
+ * - Uses FloatingFocusManager for keyboard navigation
+ * - Only visible when isOpen is true
+ */
 declare const TooltipContent: import("react").ForwardRefExoticComponent<TooltipContentProps & import("react").RefAttributes<HTMLDivElement>>;
 export default TooltipContent;

package/dist/components/TooltipTrigger/TooltipTrigger.d.ts

@@ -1,3 +1,29 @@
 import { TooltipTriggerProps } from '../Tooltip/types';
-declare const TooltipTrigger: ({ children, className }: TooltipTriggerProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | null;
+/**
+ * TooltipTrigger - Trigger element for tooltip activation
+ *
+ * Wraps a single React element to make it trigger the tooltip. The wrapped
+ * element receives tooltip interaction props (onMouseEnter, onMouseLeave, onClick, etc.)
+ * and Floating UI reference props for positioning.
+ *
+ * Must be used within a Tooltip component and must have a single child element
+ * (not a fragment or array). Returns null if children is not a valid element.
+ *
+ * @category Components
+ * @subcategory Overlay
+ *
+ * @example
+ * ```tsx
+ * <Tooltip>
+ *   <TooltipTrigger>
+ *     <Button>Hover me</Button>
+ *   </TooltipTrigger>
+ *   <TooltipContent>Tooltip content</TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @see {@link Tooltip} - Parent component that provides context
+ * @see {@link TooltipContent} - Content component that displays tooltip
+ */
+declare const TooltipTrigger: ({ children, className }: TooltipTriggerProps) => import("react").ReactElement<TooltipTriggerProps, string | import("react").JSXElementConstructor<any>> | null;
 export default TooltipTrigger;

package/dist/components/Typeahead/Typeahead.context.d.ts

@@ -6,11 +6,11 @@ export declare const TypeaheadContext: React.Context<{
     isDisabled: boolean | undefined;
     optionsWithKey: Record<string | number, import("./types").TypeaheadOptionProps>;
     selectedItems: import("./types").TypeaheadValue[];
-    inputRef: React.RefObject<HTMLInputElement>;
+    inputRef: React.RefObject<HTMLInputElement | null>;
     firstSuggestion: string;
     isMultiple: boolean | undefined;
     typeaheadId: string;
-    triggerRef: React.RefObject<HTMLDivElement>;
+    triggerRef: React.RefObject<HTMLDivElement | null>;
     className: string | undefined;
     startIcon: React.ReactNode;
     endIcon: React.ReactNode;
@@ -23,8 +23,14 @@ export declare const TypeaheadContext: React.Context<{
     status: "error" | "success" | "basic";
     error: import("react-hook-form").FieldError | import("react-hook-form").Merge<import("react-hook-form").FieldError, import("react-hook-form").FieldErrorsImpl<any>> | undefined;
     placeholder: string | null | undefined;
-    options: (React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | null)[];
-    useFormResult: UseFormReturn<FieldValues, any, undefined>;
+    options: (React.ReactElement<any, string | React.JSXElementConstructor<any>> | null)[];
+    customOptionValue: string | null;
+    handleChange: ({ value, shouldClose, resetInput, }: {
+        value?: string | number;
+        shouldClose?: boolean;
+        resetInput?: boolean;
+    }) => void;
+    useFormResult: UseFormReturn<FieldValues, any, FieldValues>;
     register: import("react-hook-form").UseFormRegister<FieldValues>;
     setValue: import("react-hook-form").UseFormSetValue<FieldValues>;
     onChange: ((selectedItem: import("./types").TypeaheadValue, isSelected: boolean) => void) | undefined;

package/dist/components/Typeahead/Typeahead.d.ts

@@ -1,11 +1,175 @@
 import { TypeaheadProps } from './types';
 /**
- * The structure of the component:
- * - TypeaheadTrigger
- * - TypeaheadOptions
- * - FormHelperText
- *
- * Aria attributes are set according to
- * https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/
- **/
-export declare const Typeahead: ({ name, label, selectedItems, defaultSelectedItems, isOpen, isDisabled, isMultiple, children, className, startIcon, endIcon, error, success, helperText, validationSchema, placeholder, startIconClassName, endIconClassName, popoverClassName, optionsClassName, wrapperClassName, filterOptions, width, onChange, onEmptyChange, onClearAll, onRemoveSelectedClick, renderOption, }: TypeaheadProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+ * Typeahead - Advanced autocomplete search component with dropdown functionality
+ *
+ * A powerful autocomplete component that provides search-as-you-type functionality
+ * with dropdown suggestions. Supports both single and multiple selection modes,
+ * filtering, custom rendering, custom values (user-typed values not in options list),
+ * and integrates seamlessly with React Hook Form for validation and form management.
+ *
+ * Component structure:
+ * - Typeahead (root container with context)
+ *   - TypeaheadTrigger (search input with selected items display)
+ *   - TypeaheadOptions (filtered dropdown options list)
+ *   - FormHelperText (validation messages and helper text)
+ *
+ * @category Form Controls
+ * @subcategory Selection
+ *
+ * @example
+ * ```tsx
+ * // Single selection with React Hook Form
+ * const form = useForm();
+ * return (
+ *   <FormProvider {...form}>
+ *     <Typeahead
+ *       name="language"
+ *       label="Programming Language"
+ *       placeholder="Select a language"
+ *       validationSchema={{ required: 'Language is required' }}>
+ *       {languages.map(lang => (
+ *         <TypeaheadOption key={lang.id} value={lang.id} label={lang.name}>
+ *           {lang.name}
+ *         </TypeaheadOption>
+ *       ))}
+ *     </Typeahead>
+ *   </FormProvider>
+ * );
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple selection
+ * <Typeahead
+ *   name="tags"
+ *   isMultiple
+ *   label="Tags"
+ *   selectedItems={selected}
+ *   onChange={(item, isSelected) => handleToggle(item, isSelected)}>
+ *   {options.map(opt => (
+ *     <TypeaheadOption key={opt.id} value={opt.id}>
+ *       {opt.label}
+ *     </TypeaheadOption>
+ *   ))}
+ * </Typeahead>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom values - allows users to type and add values not in options
+ * <Typeahead
+ *   name="tags"
+ *   isMultiple
+ *   allowCustomValues={true}
+ *   label="Tags">
+ *   {options.map(opt => (
+ *     <TypeaheadOption key={opt.id} value={opt.id}>
+ *       {opt.label}
+ *     </TypeaheadOption>
+ *   ))}
+ * </Typeahead>
+ * // Users can type "custom-tag" and press Enter to add it
+ * // Custom values appear in blue in the dropdown and selected items
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom option rendering
+ * <Typeahead
+ *   name="users"
+ *   label="Select User"
+ *   renderOption={({ value, label, input }) => (
+ *     <div>
+ *       <Avatar src={users[value].avatar} />
+ *       <span>{highlightMatch(label, input)}</span>
+ *     </div>
+ *   )}>
+ *   {users.map(user => (
+ *     <TypeaheadOption key={user.id} value={user.id} label={user.name} />
+ *   ))}
+ * </Typeahead>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Schema validation in Form Builder (JsonSchemaForm)
+ * // For single select - use 'required' in schema
+ * const schema = {
+ *   type: 'string',
+ *   title: 'Select field title',
+ *   enum: ['Option 1', 'Option 2'],
+ *   // required: ['selectField'] // Add to top-level required array
+ * };
+ *
+ * // For multiple select (array) - use 'required' + 'minItems'
+ * const schema = {
+ *   type: 'array',
+ *   title: 'Select multiple fields title',
+ *   items: {
+ *     type: 'string',
+ *     enum: ['Option 1', 'Option 2', 'Option 3'],
+ *   },
+ *   minItems: 1, // Ensures at least one item is selected
+ *   // required: ['selectMultipleField'] // Add to top-level required array
+ * };
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Schema validation in standalone mode (React Hook Form)
+ * // For single select - use 'required' in validationSchema
+ * <Typeahead
+ *   name="language"
+ *   label="Language"
+ *   validationSchema={{
+ *     required: 'Language is required',
+ *   }}>
+ *   {options.map(opt => (
+ *     <TypeaheadOption key={opt.id} value={opt.id}>
+ *       {opt.label}
+ *     </TypeaheadOption>
+ *   ))}
+ * </Typeahead>
+ *
+ * // For multiple select - use 'validate' function to check array length
+ * <Typeahead
+ *   name="tags"
+ *   isMultiple
+ *   label="Tags"
+ *   validationSchema={{
+ *     validate: (value: string[]) => {
+ *       if (!value || value.length === 0) {
+ *         return 'At least one tag is required';
+ *       }
+ *       return true;
+ *     },
+ *   }}>
+ *   {options.map(opt => (
+ *     <TypeaheadOption key={opt.id} value={opt.id}>
+ *       {opt.label}
+ *     </TypeaheadOption>
+ *   ))}
+ * </Typeahead>
+ * ```
+ *
+ * @note Validation differences:
+ * - **Form Builder (JsonSchemaForm)**: Uses JSON Schema validation. For arrays, use `minItems` property
+ *   (e.g., `minItems: 1` to require at least one selection). The `required` array at the schema root
+ *   marks fields as required.
+ * - **Standalone mode**: Uses React Hook Form validation. For arrays, use a `validate` function to check
+ *   array length, as React Hook Form doesn't have a built-in `minItems` rule. The `required` rule works
+ *   for single select fields.
+ *
+ * @see {@link TypeaheadOption} - Child component for individual options
+ * @see {@link Popover} - Used for dropdown positioning
+ *
+ * @accessibility
+ * - ARIA attributes set according to WAI-ARIA combobox pattern
+ * - Keyboard navigation (Arrow keys, Enter, Escape, Tab)
+ * - Screen reader friendly
+ * - Focus management with trap
+ * - Search input filtering
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/
+ */
+export declare const Typeahead: ({ name, label, selectedItems, defaultSelectedItems, isOpen, isDisabled, isMultiple, children, className, startIcon, endIcon, error, success, helperText, validationSchema, placeholder, startIconClassName, endIconClassName, popoverClassName, optionsClassName, wrapperClassName, filterOptions, autoSelect, allowCustomValues, width, onChange, onEmptyChange, onClearAll, onRemoveSelectedClick, renderOption, }: TypeaheadProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/Typeahead/components/TypeaheadOption.d.ts

@@ -1,2 +1,2 @@
 import { TypeaheadItemProps } from '../types';
-export declare const TypeaheadOption: ({ children, avatar, ...rest }: TypeaheadItemProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const TypeaheadOption: ({ children, avatar, isCustomValue, ...rest }: TypeaheadItemProps) => import("@emotion/react/jsx-runtime").JSX.Element;

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

@@ -17,6 +17,7 @@ export declare const TypeaheadItem: import("@emotion/styled").StyledComponent<{
     as?: React.ElementType;
 } & {
     isDisabled?: boolean;
+    isCustomValue?: boolean;
 }, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
 export declare const TypeaheadItemAvatar: import("@emotion/styled").StyledComponent<{
     theme?: Theme;
@@ -27,16 +28,20 @@ export declare const TypeaheadItemLabel: import("@emotion/styled").StyledCompone
     as?: React.ElementType;
 } & {
     isDisabled?: boolean;
+    isCustomValue?: boolean;
 }, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
-export declare const TypeaheadItemCross: import("@emotion/styled").StyledComponent<import("../Button/types").ButtonProps & import("react").RefAttributes<HTMLButtonElement> & {
+export declare const TypeaheadItemCross: import("@emotion/styled").StyledComponent<import("..").ButtonProps & import("react").RefAttributes<HTMLButtonElement> & {
     theme?: Theme;
+} & {
+    isCustomValue?: boolean;
 }, {}, {}>;
 export declare const TypeaheadInputsGroupWrapper: import("@emotion/styled").StyledComponent<{
     theme?: Theme;
     as?: React.ElementType;
 } & {
-    direction?: string;
-    alignItems?: string;
+    direction?: import("../Wrapper").WrapperDirection;
+    alignItems?: import("../Wrapper").WrapperAlignItems;
+    justifyContent?: import("../Wrapper").WrapperJustifyContent;
     fade?: boolean;
     fadeDelay?: number;
     isVisible?: boolean;
@@ -45,7 +50,7 @@ export declare const TypeaheadInputsGroupWrapper: import("@emotion/styled").Styl
 } & {
     isOpen: boolean;
 }, {}, {}>;
-export declare const TypeaheadTrigger: import("@emotion/styled").StyledComponent<Omit<import("react").HTMLProps<HTMLElement> & import("../Button/types").ButtonProps & import("../Popover/types").PopoverTriggerProps, "ref"> & import("react").RefAttributes<HTMLElement> & {
+export declare const TypeaheadTrigger: import("@emotion/styled").StyledComponent<Omit<import("react").HTMLProps<HTMLElement> & import("..").ButtonProps & import("../Popover/types").PopoverTriggerProps, "ref"> & import("react").RefAttributes<HTMLElement> & {
     theme?: Theme;
 } & {
     isOpen: boolean;